diff --git a/.cursor/.gitignore b/.cursor/.gitignore
new file mode 100644
index 00000000000..8bf7cc27a18
--- /dev/null
+++ b/.cursor/.gitignore
@@ -0,0 +1 @@
+plans/
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 0c4c30240ca..cc1f11cd8ba 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -2,15 +2,22 @@
   "name": "T3 Code Dev",
   "image": "debian:bookworm",
   "features": {
-    "ghcr.io/devcontainers-extra/features/bun:1": {},
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers-extra/features/bun:1": {
+      "version": "1.3.11"
+    },
     "ghcr.io/devcontainers/features/node:1": {
-      "version": "24",
-      "nodeGypDependencies": true
+      "version": "24.13.1"
     },
     "ghcr.io/devcontainers/features/python:1": {
-      "version": "3.12"
+      "version": "3.10",
+      "installTools": false
     }
   },
+  "overrideFeatureInstallOrder": [
+    "ghcr.io/devcontainers/features/git",
+    "ghcr.io/devcontainers-extra/features/bun"
+  ],
   "postCreateCommand": {
     "bun-install": "bun install --backend=copyfile --frozen-lockfile"
   },
diff --git a/.docs/remote-architecture.md b/.docs/remote-architecture.md
index 32e35d7cafa..75274095a12 100644
--- a/.docs/remote-architecture.md
+++ b/.docs/remote-architecture.md
@@ -93,6 +93,8 @@ Examples:
 
 A known environment may or may not know the target `environmentId` before first successful connect.
 
+In the hosted web app, known environments are browser-local. A hosted pairing URL can create the saved entry, but it does not give the hosted app a server-side control plane or a copy of the session state.
+
 ### AccessEndpoint
 
 An `AccessEndpoint` is one concrete way to reach a known environment.
@@ -108,6 +110,67 @@ A single environment may have many endpoints:
 
 The environment stays the same. Only the access path changes.
 
+### AdvertisedEndpoint
+
+An `AdvertisedEndpoint` is a server or desktop-authored candidate endpoint for an environment. It is how the backend tells the client which URLs may be useful for pairing and reconnecting.
+
+`AdvertisedEndpoint` is deliberately narrower than the full access model:
+
+- it describes a concrete HTTP and WebSocket base URL pair
+- it can mark the endpoint as default, available, or unavailable
+- it includes reachability hints such as loopback, LAN, private, public, or tunnel
+- it includes compatibility hints such as whether the endpoint can be used from the hosted HTTPS app
+
+Clients should treat advertised endpoints as hints, not as proof that a route works from the current device. The final connection attempt still decides whether the endpoint is reachable.
+
+The UI presents one default advertised endpoint in the network-access summary and keeps the rest behind an expandable advanced list. The default controls pairing QR codes and primary copy actions. Users can override it, but that override is a UI preference, not backend configuration.
+
+Persist the override by stable endpoint kind rather than raw URL whenever possible. For example, a LAN endpoint should be stored as the desktop LAN endpoint preference, not as `192.168.x.y`, because the address can change when the user switches networks. Provider endpoints should use provider-specific stable keys such as Tailscale IP or Tailscale MagicDNS HTTPS. Custom endpoints may fall back to their concrete identity.
+
+When no user default is saved, endpoint selection should prefer:
+
+1. endpoints compatible with the hosted HTTPS app
+2. explicitly default endpoints
+3. non-loopback endpoints
+4. loopback endpoints only for same-machine clients
+
+This keeps endpoint discovery centralized without making any one provider, such as Tailscale or a future tunnel service, part of the core environment model.
+
+### Endpoint providers
+
+Endpoint providers are add-ons that contribute advertised endpoints for the current environment.
+
+The provider boundary is intentionally outside the core environment model:
+
+- core owns `ExecutionEnvironment`, saved environments, pairing, and connection lifecycle
+- providers discover or synthesize endpoints
+- providers return normalized `AdvertisedEndpoint` records
+- the UI and pairing logic select from those records without knowing provider-specific commands
+
+The first provider is Tailscale. It can discover Tailnet IP and MagicDNS addresses from the local machine and publish them as additional endpoint candidates. Future providers, such as a hosted tunnel service, should plug into the same shape rather than adding a separate remote environment path.
+
+Provider-specific confidence should remain a hint. A Tailscale endpoint still needs a successful browser or desktop connection before the client treats it as connected.
+
+### Hosted pairing request
+
+A hosted pairing request is a bootstrap URL for the static web app, not a transport.
+
+Example:
+
+```text
+https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
+```
+
+The hosted app reads the `host` parameter and pairing token, exchanges the token directly with that backend, then saves the resulting environment record in browser local storage.
+
+Important constraints:
+
+- the hosted app does not proxy HTTP or WebSocket traffic
+- the backend must still be reachable directly from the browser
+- HTTPS pages can only connect to HTTPS/WSS backends
+- HTTP LAN endpoints should keep using direct desktop or CLI pairing URLs
+- the token belongs in the URL hash so it is not sent to the hosted app origin
+
 ### RepositoryIdentity
 
 `RepositoryIdentity` remains a best-effort logical repo grouping mechanism across environments.
@@ -151,6 +214,8 @@ Benefits:
 - no client-specific process management required
 - best fit for hosted or self-managed remote T3 deployments
 
+Browser security rules are part of this access method. A hosted HTTPS web client can connect to `wss://` backends, but it cannot connect to plain `ws://` or `http://` LAN backends because that would be mixed content.
+
 ### 2. Tunneled WebSocket access
 
 Examples:
@@ -170,6 +235,8 @@ This is especially useful when:
 - mobile must reach a desktop-hosted environment
 - a machine should be reachable without exposing raw LAN or public ports
 
+Tailscale-backed access sits here architecturally even though the current implementation is endpoint discovery rather than a T3-managed tunnel. It contributes private-network endpoints and lets the existing HTTP/WebSocket client path do the actual connection.
+
 ### 3. Desktop-managed SSH access
 
 SSH is an access and launch helper, not a separate environment type.
@@ -185,6 +252,8 @@ After that, the renderer should still connect using an ordinary WebSocket URL ag
 
 This keeps the renderer transport model consistent with every other access method.
 
+The desktop main process owns the SSH bridge because it can spawn local SSH processes, manage askpass prompts, write temporary launch scripts, and clean up forwards. The renderer receives a saved environment record and connects through the forwarded URL; it should not need SSH-specific RPC paths for normal environment traffic.
+
 ## Launch methods
 
 Launch methods answer a different question:
@@ -227,6 +296,15 @@ The recommended T3 flow is:
 4. Desktop establishes local port forwarding.
 5. Renderer connects to the forwarded WebSocket endpoint as a normal environment.
 
+The saved environment should remember that it was created by desktop SSH launch only for reconnect and lifecycle UX. That metadata should not change the server protocol or the environment identity model.
+
+Failure handling should be explicit:
+
+- SSH authentication failure should surface before any environment is saved
+- remote launch failure should include remote logs or the launcher command output when available
+- forwarded-port failure should leave the saved environment disconnected rather than falling back to an unrelated endpoint
+- reconnect should attempt to restore the SSH bridge before reconnecting the normal WebSocket client
+
 ### 3. Client-managed local publish
 
 This is the inverse of remote launch: a local T3 server is already running, and the client publishes it through a tunnel.
@@ -267,6 +345,8 @@ T3 already supports a WebSocket auth token on the server. That should become a f
 
 For publicly reachable environments, authenticated access should be treated as required.
 
+Hosted pairing should be treated as a client-side convenience only. The hosted app must not receive pairing tokens through query parameters, must not store pairing state server-side, and must not imply that an HTTP backend is safe or reachable from an HTTPS browser context.
+
 ## Relationship to Zed
 
 Zed is a useful reference implementation for managed remote launch and reconnect behavior.
diff --git a/.github/VOUCHED.td b/.github/VOUCHED.td
index 5535d54a5b4..73376110d9a 100644
--- a/.github/VOUCHED.td
+++ b/.github/VOUCHED.td
@@ -30,3 +30,6 @@ github:Yash-Singh1
 github:eggfriedrice24
 github:Ymit24
 github:shivamhwp
+github:jappyjan
+github:justsomelegs
+github:UtkarshUsername
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5c2d2c83813..e3329b1dad9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,7 +9,7 @@ on:
 jobs:
   quality:
     name: Format, Lint, Typecheck, Test, Browser Test, Build
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: blacksmith-8vcpu-ubuntu-2404
     timeout-minutes: 10
     steps:
       - name: Checkout
@@ -71,12 +71,12 @@ jobs:
 
       - name: Verify preload bundle output
         run: |
-          test -f apps/desktop/dist-electron/preload.js
-          grep -nE "desktopBridge|getLocalEnvironmentBootstrap|PICK_FOLDER_CHANNEL|wsUrl" apps/desktop/dist-electron/preload.js
+          test -f apps/desktop/dist-electron/preload.cjs
+          grep -nE "desktopBridge|getLocalEnvironmentBootstrap|PICK_FOLDER_CHANNEL|wsUrl" apps/desktop/dist-electron/preload.cjs
 
   release_smoke:
     name: Release Smoke
-    runs-on: ubuntu-24.04
+    runs-on: blacksmith-8vcpu-ubuntu-2404
     timeout-minutes: 10
     steps:
       - name: Checkout
@@ -92,5 +92,8 @@ jobs:
         with:
           node-version-file: package.json
 
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
       - name: Exercise release-only workflow steps
         run: node scripts/release-smoke.ts
diff --git a/.github/workflows/pr-size.yml b/.github/workflows/pr-size.yml
index 15c04d663d3..af557dff62d 100644
--- a/.github/workflows/pr-size.yml
+++ b/.github/workflows/pr-size.yml
@@ -124,6 +124,9 @@ jobs:
       group: pr-size-${{ github.event.pull_request.number }}
       cancel-in-progress: true
     steps:
+      # This pull_request_target job may fetch untrusted PR commits only as passive
+      # git data. Do not add dependency installs, build/test scripts, or cache
+      # actions here; use pull_request plus workflow_run for that pattern instead.
       - name: Checkout base repository
         uses: actions/checkout@v4
         with:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index ac01ee87934..d90479087cf 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,60 +1,89 @@
-name: Release Desktop
+name: Release
 
 on:
   push:
     tags:
       - "v*.*.*"
+      - "!v*-nightly.*"
+  schedule:
+    - cron: "0 */3 * * *"
   workflow_dispatch:
     inputs:
+      channel:
+        description: "Release channel"
+        required: false
+        default: stable
+        type: choice
+        options:
+          - stable
+          - nightly
       version:
         description: "Release version (for example 1.2.3 or v1.2.3)"
-        required: true
+        required: false
         type: string
 
 permissions:
-  contents: write
-  id-token: write
+  contents: read
+  id-token: none
 
 jobs:
+  check_changes:
+    name: Check for changes since last nightly
+    if: github.event_name == 'schedule'
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    outputs:
+      has_changes: ${{ steps.check.outputs.has_changes }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - id: check
+        name: Compare HEAD to last nightly tag
+        run: |
+          last_nightly_tag=$(git tag --list 'v*-nightly.*' 'nightly-v*' --sort=-creatordate | head -n 1)
+          if [[ -z "$last_nightly_tag" ]]; then
+            echo "No previous nightly tag found. Proceeding with release."
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          last_nightly_sha=$(git rev-parse "$last_nightly_tag^{commit}")
+          head_sha=$(git rev-parse HEAD)
+
+          if [[ "$last_nightly_sha" == "$head_sha" ]]; then
+            echo "No changes on main since last nightly release ($last_nightly_tag). Skipping."
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Changes detected on main since $last_nightly_tag ($last_nightly_sha → $head_sha). Proceeding."
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
   preflight:
     name: Preflight
-    runs-on: ubuntu-24.04
+    needs: [check_changes]
+    if: |
+      !failure() && !cancelled() &&
+      (github.event_name != 'schedule' || needs.check_changes.outputs.has_changes == 'true')
+    runs-on: blacksmith-8vcpu-ubuntu-2404
     timeout-minutes: 10
     outputs:
+      release_channel: ${{ steps.release_meta.outputs.release_channel }}
       version: ${{ steps.release_meta.outputs.version }}
       tag: ${{ steps.release_meta.outputs.tag }}
+      release_name: ${{ steps.release_meta.outputs.name }}
+      short_sha: ${{ steps.release_meta.outputs.short_sha }}
+      previous_tag: ${{ steps.previous_tag.outputs.previous_tag }}
+      cli_dist_tag: ${{ steps.release_meta.outputs.cli_dist_tag }}
       is_prerelease: ${{ steps.release_meta.outputs.is_prerelease }}
       make_latest: ${{ steps.release_meta.outputs.make_latest }}
       ref: ${{ github.sha }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-
-      - id: release_meta
-        name: Resolve release version
-        shell: bash
-        run: |
-          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
-            raw="${{ github.event.inputs.version }}"
-          else
-            raw="${GITHUB_REF_NAME}"
-          fi
-
-          version="${raw#v}"
-          if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
-            echo "Invalid release version: $raw" >&2
-            exit 1
-          fi
-
-          echo "version=$version" >> "$GITHUB_OUTPUT"
-          echo "tag=v$version" >> "$GITHUB_OUTPUT"
-          if [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
-            echo "make_latest=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
-            echo "make_latest=false" >> "$GITHUB_OUTPUT"
-          fi
+        with:
+          fetch-depth: 0
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -69,6 +98,60 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - id: release_meta
+        name: Resolve release version
+        shell: bash
+        env:
+          DISPATCH_CHANNEL: ${{ github.event.inputs.channel }}
+          DISPATCH_VERSION: ${{ github.event.inputs.version }}
+          NIGHTLY_DATE: ${{ github.run_started_at }}
+          NIGHTLY_SHA: ${{ github.sha }}
+          NIGHTLY_RUN_NUMBER: ${{ github.run_number }}
+        run: |
+          if [[ "${GITHUB_EVENT_NAME}" == "schedule" || ( "${GITHUB_EVENT_NAME}" == "workflow_dispatch" && "${DISPATCH_CHANNEL:-stable}" == "nightly" ) ]]; then
+            nightly_date="$(date -u -d "$NIGHTLY_DATE" +%Y%m%d)"
+
+            node scripts/resolve-nightly-release.ts \
+              --date "$nightly_date" \
+              --run-number "$NIGHTLY_RUN_NUMBER" \
+              --sha "$NIGHTLY_SHA" \
+              --github-output
+
+            echo "release_channel=nightly" >> "$GITHUB_OUTPUT"
+            echo "cli_dist_tag=nightly" >> "$GITHUB_OUTPUT"
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+            echo "make_latest=false" >> "$GITHUB_OUTPUT"
+          else
+            if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+              raw="${DISPATCH_VERSION}"
+              if [[ -z "$raw" ]]; then
+                echo "workflow_dispatch stable releases require the version input." >&2
+                exit 1
+              fi
+            else
+              raw="${GITHUB_REF_NAME}"
+            fi
+
+            version="${raw#v}"
+            if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+              echo "Invalid release version: $raw" >&2
+              exit 1
+            fi
+
+            echo "release_channel=stable" >> "$GITHUB_OUTPUT"
+            echo "version=$version" >> "$GITHUB_OUTPUT"
+            echo "tag=v$version" >> "$GITHUB_OUTPUT"
+            echo "name=T3 Code v$version" >> "$GITHUB_OUTPUT"
+            echo "cli_dist_tag=latest" >> "$GITHUB_OUTPUT"
+            if [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+              echo "make_latest=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+              echo "make_latest=false" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+
       - name: Lint
         run: bun run lint
 
@@ -78,9 +161,18 @@ jobs:
       - name: Test
         run: bun run test
 
+      - id: previous_tag
+        name: Resolve previous release tag
+        run: |
+          node scripts/resolve-previous-release-tag.ts \
+            --channel "${{ steps.release_meta.outputs.release_channel }}" \
+            --current-tag "${{ steps.release_meta.outputs.tag }}" \
+            --github-output
+
   build:
     name: Build ${{ matrix.label }}
     needs: preflight
+    if: ${{ !failure() && !cancelled() && needs.preflight.result == 'success' }}
     runs-on: ${{ matrix.runner }}
     timeout-minutes: 30
     strategy:
@@ -88,25 +180,30 @@ jobs:
       matrix:
         include:
           - label: macOS arm64
-            runner: macos-14
+            runner: blacksmith-12vcpu-macos-26
             platform: mac
             target: dmg
             arch: arm64
           - label: macOS x64
-            runner: macos-15-intel
+            runner: blacksmith-12vcpu-macos-26
             platform: mac
             target: dmg
             arch: x64
           - label: Linux x64
-            runner: ubuntu-24.04
+            runner: blacksmith-32vcpu-ubuntu-2404
             platform: linux
             target: AppImage
             arch: x64
           - label: Windows x64
-            runner: windows-2022
+            runner: blacksmith-32vcpu-windows-2025
             platform: win
             target: nsis
             arch: x64
+          # - label: Windows arm64
+          #   runner: windows-11-arm
+          #   platform: win
+          #   target: nsis
+          #   arch: arm64
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -130,6 +227,85 @@ jobs:
       - name: Align package versions to release version
         run: node scripts/update-release-package-versions.ts "${{ needs.preflight.outputs.version }}"
 
+      - name: Install Spectre-mitigated MSVC libs
+        if: matrix.platform == 'win'
+        shell: pwsh
+        run: |
+          $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+             $installPath = & $vswhere -products * -latest -property installationPath
+             $setupExe = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\setup.exe"
+             $proc = Start-Process -FilePath $setupExe `
+              -ArgumentList "modify", "--installPath", "`"$installPath`"", "--add", `
+              "Microsoft.VisualStudio.Component.VC.Tools.x86.x64.Spectre", "--quiet", "--norestart" `
+              -Wait -PassThru -NoNewWindow
+             if ($null -eq $proc -or $proc.ExitCode -ne 0) {
+               $code = if ($null -ne $proc) { $proc.ExitCode } else { 1 }
+               Write-Error "Visual Studio Installer failed with exit code $code"
+               exit $code
+             }
+
+      - name: Prepare Azure Trusted Signing
+        if: matrix.platform == 'win'
+        shell: pwsh
+        env:
+          AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+          AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+          AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+          AZURE_TRUSTED_SIGNING_ENDPOINT: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
+          AZURE_TRUSTED_SIGNING_ACCOUNT_NAME: ${{ secrets.AZURE_TRUSTED_SIGNING_ACCOUNT_NAME }}
+          AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME: ${{ secrets.AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME }}
+          AZURE_TRUSTED_SIGNING_PUBLISHER_NAME: ${{ secrets.AZURE_TRUSTED_SIGNING_PUBLISHER_NAME }}
+        run: |
+          $ErrorActionPreference = "Stop"
+
+          $requiredSecrets = @(
+            $env:AZURE_TENANT_ID,
+            $env:AZURE_CLIENT_ID,
+            $env:AZURE_CLIENT_SECRET,
+            $env:AZURE_TRUSTED_SIGNING_ENDPOINT,
+            $env:AZURE_TRUSTED_SIGNING_ACCOUNT_NAME,
+            $env:AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME,
+            $env:AZURE_TRUSTED_SIGNING_PUBLISHER_NAME
+          )
+          if ($requiredSecrets | Where-Object { [string]::IsNullOrWhiteSpace($_) }) {
+            Write-Host "Azure Trusted Signing disabled; skipping TrustedSigning module preparation."
+            exit 0
+          }
+
+          try {
+            Install-PackageProvider `
+              -Name NuGet `
+              -MinimumVersion 2.8.5.201 `
+              -Force `
+              -Scope CurrentUser `
+              -ErrorAction Stop
+          } catch {
+            Write-Warning "Could not bootstrap NuGet package provider. Continuing because the runner may already have a usable provider. $($_.Exception.Message)"
+          }
+
+          Install-Module `
+            -Name TrustedSigning `
+            -MinimumVersion 0.5.0 `
+            -Force `
+            -AllowClobber `
+            -Repository PSGallery `
+            -Scope CurrentUser `
+            -ErrorAction Stop
+
+          Import-Module TrustedSigning -MinimumVersion 0.5.0 -Force
+          Get-Command Invoke-TrustedSigning -ErrorAction Stop
+
+          $moduleRoots = @(
+            [System.IO.Path]::Combine([Environment]::GetFolderPath("MyDocuments"), "PowerShell", "Modules"),
+            [System.IO.Path]::Combine([Environment]::GetFolderPath("MyDocuments"), "WindowsPowerShell", "Modules"),
+            [System.IO.Path]::Combine($env:ProgramFiles, "PowerShell", "Modules"),
+            [System.IO.Path]::Combine($env:ProgramFiles, "WindowsPowerShell", "Modules")
+          )
+          $modulePathEntries = @($moduleRoots + ($env:PSModulePath -split ";")) |
+            Where-Object { $_ -and (Test-Path $_) } |
+            Select-Object -Unique
+          "PSModulePath=$($modulePathEntries -join ';')" >> $env:GITHUB_ENV
+
       - name: Build desktop artifact
         shell: bash
         env:
@@ -206,18 +382,31 @@ jobs:
             "release/*.AppImage" \
             "release/*.exe" \
             "release/*.blockmap" \
-            "release/latest*.yml"; do
+            "release/*.yml"; do
             for file in $pattern; do
               cp "$file" release-publish/
             done
           done
 
           if [[ "${{ matrix.platform }}" == "mac" && "${{ matrix.arch }}" != "arm64" ]]; then
-            if [[ -f release-publish/latest-mac.yml ]]; then
-              mv release-publish/latest-mac.yml "release-publish/latest-mac-${{ matrix.arch }}.yml"
-            fi
+            shopt -s nullglob
+            for manifest in release-publish/*-mac.yml; do
+              mv "$manifest" "${manifest%.yml}-${{ matrix.arch }}.yml"
+            done
           fi
 
+          # Enable if Windows arm64 builds are enabled.
+          # Windows updater metadata is channel-specific (for example
+          # "latest.yml" or "nightly.yml"). Suffix each per-arch copy so the
+          # release job can merge matching arm64/x64 manifests back into one
+          # canonical manifest per channel.
+          # if [[ "${{ matrix.platform }}" == "win" ]]; then
+          #   shopt -s nullglob
+          #   for manifest in release-publish/*.yml; do
+          #     mv "$manifest" "${manifest%.yml}-win-${{ matrix.arch }}.yml"
+          #   done
+          # fi
+
       - name: Upload build artifacts
         uses: actions/upload-artifact@v7
         with:
@@ -228,8 +417,12 @@ jobs:
   publish_cli:
     name: Publish CLI to npm
     needs: [preflight, build]
-    runs-on: ubuntu-24.04
+    if: ${{ !failure() && !cancelled() && needs.preflight.result == 'success' && needs.build.result == 'success' }}
+    runs-on: ubuntu-24.04 # blacksmith-8vcpu-ubuntu-2404
     timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -248,33 +441,53 @@ jobs:
           registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: bun install --frozen-lockfile --filter=t3 --filter=@t3tools/web --filter=@t3tools/scripts
 
       - name: Align package versions to release version
         run: node scripts/update-release-package-versions.ts "${{ needs.preflight.outputs.version }}"
 
+      - name: Build web package
+        run: bun --filter=@t3tools/web run build
+
       - name: Build CLI package
-        run: bun run build --filter=@t3tools/web --filter=t3
+        run: bun --filter=t3 run build
 
       - name: Publish CLI package
-        run: node apps/server/scripts/cli.ts publish --tag latest --app-version "${{ needs.preflight.outputs.version }}" --verbose
+        run: node apps/server/scripts/cli.ts publish --tag "${{ needs.preflight.outputs.cli_dist_tag }}" --app-version "${{ needs.preflight.outputs.version }}" --verbose
 
   release:
     name: Publish GitHub Release
     needs: [preflight, build, publish_cli]
-    runs-on: ubuntu-24.04
+    if: ${{ !failure() && !cancelled() && needs.preflight.result == 'success' && needs.build.result == 'success' && needs.publish_cli.result == 'success' }}
+    runs-on: blacksmith-8vcpu-ubuntu-2404
     timeout-minutes: 10
     steps:
+      - id: app_token
+        name: Mint release app token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
       - name: Checkout
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+
       - name: Setup Node
         uses: actions/setup-node@v6
         with:
           node-version-file: package.json
 
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --filter=@t3tools/scripts
+
       - name: Download all desktop artifacts
         uses: actions/download-artifact@v8
         with:
@@ -284,17 +497,72 @@ jobs:
 
       - name: Merge macOS updater manifests
         run: |
-          node scripts/merge-mac-update-manifests.ts \
-            release-assets/latest-mac.yml \
-            release-assets/latest-mac-x64.yml
-          rm -f release-assets/latest-mac-x64.yml
+          shopt -s nullglob
+          for x64_manifest in release-assets/*-mac-x64.yml; do
+            arm64_manifest="${x64_manifest%-x64.yml}.yml"
+            if [[ -f "$arm64_manifest" ]]; then
+              node scripts/merge-update-manifests.ts --platform mac "$arm64_manifest" "$x64_manifest"
+              rm -f "$x64_manifest"
+            fi
+          done
+
+      # - name: Merge Windows updater manifests
+      #   run: |
+      #     shopt -s nullglob
+      #     found_windows_manifest=false
+      #     for x64_manifest in release-assets/*-win-x64.yml; do
+      #       if [[ "$(basename "$x64_manifest")" == builder-debug-* ]]; then
+      #         continue
+      #       fi
+
+      #       arm64_manifest="${x64_manifest/-x64.yml/-arm64.yml}"
+      #       output_manifest="${x64_manifest/-win-x64.yml/.yml}"
+      #       if [[ ! -f "$arm64_manifest" ]]; then
+      #         echo "Missing matching arm64 Windows manifest for $x64_manifest" >&2
+      #         exit 1
+      #       fi
+
+      #       found_windows_manifest=true
+      #       node scripts/merge-update-manifests.ts --platform win \
+      #         "$arm64_manifest" \
+      #         "$x64_manifest" \
+      #         "$output_manifest"
+      #       rm -f "$arm64_manifest" "$x64_manifest"
+      #     done
+
+      #     if [[ "$found_windows_manifest" != true ]]; then
+      #       echo "No Windows updater manifests found to merge." >&2
+      #       exit 1
+      #     fi
 
       - name: Publish release
+        if: needs.preflight.outputs.previous_tag != ''
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.preflight.outputs.tag }}
+          target_commitish: ${{ needs.preflight.outputs.ref }}
+          name: ${{ needs.preflight.outputs.release_name }}
+          generate_release_notes: true
+          previous_tag: ${{ needs.preflight.outputs.previous_tag }}
+          prerelease: ${{ needs.preflight.outputs.is_prerelease }}
+          make_latest: ${{ needs.preflight.outputs.make_latest }}
+          files: |
+            release-assets/*.dmg
+            release-assets/*.zip
+            release-assets/*.AppImage
+            release-assets/*.exe
+            release-assets/*.blockmap
+            release-assets/*.yml
+          fail_on_unmatched_files: true
+          token: ${{ steps.app_token.outputs.token }}
+
+      - name: Publish first release
+        if: needs.preflight.outputs.previous_tag == ''
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ needs.preflight.outputs.tag }}
           target_commitish: ${{ needs.preflight.outputs.ref }}
-          name: T3 Code v${{ needs.preflight.outputs.version }}
+          name: ${{ needs.preflight.outputs.release_name }}
           generate_release_notes: true
           prerelease: ${{ needs.preflight.outputs.is_prerelease }}
           make_latest: ${{ needs.preflight.outputs.make_latest }}
@@ -304,13 +572,107 @@ jobs:
             release-assets/*.AppImage
             release-assets/*.exe
             release-assets/*.blockmap
-            release-assets/latest*.yml
+            release-assets/*.yml
           fail_on_unmatched_files: true
+          token: ${{ steps.app_token.outputs.token }}
+
+  deploy_web:
+    name: Deploy hosted web app
+    needs: [preflight, release]
+    if: ${{ !failure() && !cancelled() && needs.preflight.result == 'success' && needs.release.result == 'success' }}
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 10
+    env:
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      T3CODE_WEB_ROUTER_URL: ${{ vars.T3CODE_WEB_ROUTER_URL }}
+      T3CODE_WEB_LATEST_DOMAIN: ${{ vars.T3CODE_WEB_LATEST_DOMAIN }}
+      T3CODE_WEB_NIGHTLY_DOMAIN: ${{ vars.T3CODE_WEB_NIGHTLY_DOMAIN }}
+      VERCEL_TEAM_SLUG: ${{ vars.VERCEL_TEAM_SLUG }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.preflight.outputs.ref }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+
+      - name: Install release tooling dependencies
+        run: bun install --frozen-lockfile --filter=@t3tools/scripts --filter=@t3tools/web
+
+      - name: Align package versions to release version
+        run: node scripts/update-release-package-versions.ts "${{ needs.preflight.outputs.version }}"
+
+      - name: Refresh release lockfile
+        run: bun install --lockfile-only --ignore-scripts
+
+      - name: Deploy and alias channel
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ -z "${VERCEL_TOKEN:-}" || -z "${VERCEL_ORG_ID:-}" || -z "${VERCEL_PROJECT_ID:-}" ]]; then
+            echo "Missing one or more required Vercel secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID." >&2
+            exit 1
+          fi
+
+          router_url="${T3CODE_WEB_ROUTER_URL:-https://app.t3.codes}"
+          latest_domain="${T3CODE_WEB_LATEST_DOMAIN:-latest.app.t3.codes}"
+          nightly_domain="${T3CODE_WEB_NIGHTLY_DOMAIN:-nightly.app.t3.codes}"
+          router_domain="${router_url#http://}"
+          router_domain="${router_domain#https://}"
+          router_domain="${router_domain%%/*}"
+
+          if [[ "${{ needs.preflight.outputs.release_channel }}" == "stable" ]]; then
+            channel_domain="$latest_domain"
+            channel_name="latest"
+          else
+            channel_domain="$nightly_domain"
+            channel_name="nightly"
+          fi
+
+          vercel_scope="${VERCEL_TEAM_SLUG:-$VERCEL_ORG_ID}"
+          vercel_scope_args=(--scope "$vercel_scope")
+
+          echo "Deploying hosted web app for $channel_name channel."
+          deployment_url="$(
+            bunx vercel@53.1.1 deploy \
+              --prod \
+              --skip-domain \
+              --yes \
+              --token "$VERCEL_TOKEN" \
+              "${vercel_scope_args[@]}" \
+              --build-env "APP_VERSION=${{ needs.preflight.outputs.version }}" \
+              --build-env "VITE_HOSTED_APP_URL=$router_url" \
+              --build-env "VITE_HOSTED_APP_CHANNEL=$channel_name"
+          )"
+
+          echo "Aliasing $deployment_url to $channel_domain."
+          bunx vercel@53.1.1 alias set "$deployment_url" "$channel_domain" \
+            --token "$VERCEL_TOKEN" \
+            "${vercel_scope_args[@]}"
+
+          if [[ "$channel_name" == "latest" && -n "$router_domain" && "$router_domain" != "$channel_domain" ]]; then
+            echo "Aliasing $deployment_url to router domain $router_domain."
+            bunx vercel@53.1.1 alias set "$deployment_url" "$router_domain" \
+              --token "$VERCEL_TOKEN" \
+              "${vercel_scope_args[@]}"
+          fi
 
   finalize:
     name: Finalize release
+    if: ${{ !failure() && !cancelled() && needs.preflight.result == 'success' && needs.release.result == 'success' && needs.preflight.outputs.release_channel == 'stable' }}
     needs: [preflight, release]
-    runs-on: ubuntu-24.04
+    runs-on: blacksmith-8vcpu-ubuntu-2404
     timeout-minutes: 10
     steps:
       - id: app_token
@@ -349,6 +711,9 @@ jobs:
         with:
           node-version-file: package.json
 
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --filter=@t3tools/scripts
+
       - id: update_versions
         name: Update version strings
         env:
@@ -357,7 +722,7 @@ jobs:
 
       - name: Format package.json files
         if: steps.update_versions.outputs.changed == 'true'
-        run: bunx oxfmt apps/server/package.json apps/desktop/package.json apps/web/package.json packages/contracts/package.json
+        run: bunx oxfmt@0.40.0 apps/server/package.json apps/desktop/package.json apps/web/package.json packages/contracts/package.json
 
       - name: Refresh lockfile
         if: steps.update_versions.outputs.changed == 'true'
@@ -380,3 +745,61 @@ jobs:
           git add apps/server/package.json apps/desktop/package.json apps/web/package.json packages/contracts/package.json bun.lock
           git commit -m "chore(release): prepare $RELEASE_TAG"
           git push origin HEAD:main
+
+  announce_discord:
+    name: Announce release on Discord
+    if: |
+      always() && !cancelled() &&
+      needs.preflight.result == 'success' &&
+      needs.release.result == 'success' &&
+      needs.deploy_web.result == 'success' &&
+      (needs.finalize.result == 'success' || needs.finalize.result == 'skipped')
+    needs: [preflight, release, deploy_web, finalize]
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.preflight.outputs.ref }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --filter=@t3tools/scripts
+
+      - name: Announce prerelease on Discord
+        if: needs.preflight.outputs.is_prerelease == 'true'
+        continue-on-error: true
+        env:
+          DISCORD_MENTION_ROLE_ID: ${{ secrets.DISCORD_RELEASE_NIGHTLY_ROLE_ID }}
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_RELEASE_WEBHOOK_URL }}
+        run: |
+          node scripts/notify-discord-release.ts prerelease \
+            --role-id "$DISCORD_MENTION_ROLE_ID" \
+            --release-name "${{ needs.preflight.outputs.release_name }}" \
+            --release-version "${{ needs.preflight.outputs.version }}" \
+            --tag "${{ needs.preflight.outputs.tag }}" \
+            --release-url "https://github.com/${{ github.repository }}/releases/tag/${{ needs.preflight.outputs.tag }}"
+
+      - name: Announce latest release on Discord
+        if: needs.preflight.outputs.make_latest == 'true'
+        continue-on-error: true
+        env:
+          DISCORD_MENTION_ROLE_ID: ${{ secrets.DISCORD_RELEASE_LATEST_ROLE_ID }}
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_RELEASE_WEBHOOK_URL }}
+        run: |
+          node scripts/notify-discord-release.ts latest \
+            --role-id "$DISCORD_MENTION_ROLE_ID" \
+            --release-name "${{ needs.preflight.outputs.release_name }}" \
+            --release-version "${{ needs.preflight.outputs.version }}" \
+            --tag "${{ needs.preflight.outputs.tag }}" \
+            --release-url "https://github.com/${{ github.repository }}/releases/tag/${{ needs.preflight.outputs.tag }}"
diff --git a/.gitignore b/.gitignore
index 6c48782f9ac..5e941c7b9f0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,7 @@ apps/web/src/components/__screenshots__
 __screenshots__/
 .tanstack
 squashfs-root/
+.vercel
+.gstack/
+dist-electron/
+.electron-runtime/
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index 776d11b8035..3d65d9c93bb 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -10,7 +10,16 @@
     "*.tsbuildinfo",
     "**/routeTree.gen.ts",
     "apps/web/public/mockServiceWorker.js",
-    "apps/web/src/lib/vendor/qrcodegen.ts"
+    "apps/web/src/lib/vendor/qrcodegen.ts",
+    "*.icon/**"
   ],
-  "sortPackageJson": {}
+  "sortPackageJson": {},
+  "overrides": [
+    {
+      "files": [".devcontainer/devcontainer.json"],
+      "options": {
+        "trailingComma": "none"
+      }
+    }
+  ]
 }
diff --git a/.oxlintrc.json b/.oxlintrc.json
index 8ea8fbf2b8b..de3a72ae112 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -9,6 +9,7 @@
     "**/routeTree.gen.ts"
   ],
   "plugins": ["eslint", "oxc", "react", "unicorn", "typescript"],
+  "jsPlugins": ["./oxlint-plugin-t3code/index.ts"],
   "categories": {
     "correctness": "warn",
     "suspicious": "warn",
@@ -17,6 +18,8 @@
   "rules": {
     "react-in-jsx-scope": "off",
     "eslint/no-shadow": "off",
-    "eslint/no-await-in-loop": "off"
+    "eslint/no-await-in-loop": "off",
+    "eslint/no-underscore-dangle": "off",
+    "t3code/no-inline-schema-compile": "warn"
   }
 }
diff --git a/.plans/19-remote-endpoints-hosted-static.md b/.plans/19-remote-endpoints-hosted-static.md
new file mode 100644
index 00000000000..ada2f681ce4
--- /dev/null
+++ b/.plans/19-remote-endpoints-hosted-static.md
@@ -0,0 +1,349 @@
+# Remote Endpoints and Hosted Static App Plan
+
+## Purpose
+
+Make remote access feel first-class while keeping the free DIY path open.
+
+The immediate product goal is:
+
+- users can expose a backend through LAN, their own Tailscale, MagicDNS, a manual HTTPS endpoint, or later T3 Tunnel
+- users can generate a hosted pairing link for `app.t3.codes`
+- the hosted app can pair, persist, reconnect, and operate against saved environments without requiring a backend at the hosted app origin
+- all transports reuse the same backend auth, WebSocket runtime, saved environment registry, and pairing UX
+
+This plan intentionally leaves the paid T3 cloud tunnel fabric out of scope. It defines the OSS foundation that T3 Tunnel should later plug into.
+
+## Current State
+
+Already present or in progress:
+
+- Server auth distinguishes bootstrap credentials from session credentials.
+- One-time pairing credentials can be exchanged for browser sessions or bearer sessions.
+- Saved remote environments store `httpBaseUrl`, `wsBaseUrl`, and a bearer token.
+- Remote environment WebSocket connections use a short-lived WebSocket token.
+- Pairing URLs can carry tokens in the URL fragment.
+- Hosted `/pair?host=...#token=...` can add a saved environment.
+- Hosted static startup can avoid assuming the page origin is the backend.
+
+Main gaps:
+
+- Reachability is represented ad hoc as `endpointUrl`, manual host input, or saved environment URLs.
+- Desktop exposure, hosted pairing, manual remote environments, and future tunnels do not share one endpoint model.
+- Tailscale/MagicDNS endpoints are not detected or surfaced.
+- Hosted-static empty/offline states are still thin.
+- Browser compatibility is not explicitly modeled, especially HTTPS hosted app to HTTP backend mixed-content failure.
+
+## Core Decision: Add `AdvertisedEndpoint`
+
+Add a new first-class contract instead of extending the environment descriptor.
+
+### Why not extend `ExecutionEnvironmentDescriptor`
+
+`ExecutionEnvironmentDescriptor` answers: "What environment is this?"
+
+Examples:
+
+- environment id
+- label
+- platform
+- server version
+- capabilities
+
+`AdvertisedEndpoint` answers: "How can a client reach this environment right now?"
+
+Examples:
+
+- loopback URL
+- LAN URL
+- Tailscale IP URL
+- MagicDNS/Serve URL
+- manual URL
+- future T3 Tunnel URL
+- browser compatibility and exposure level
+
+Those are different lifecycles. One environment can have many endpoints, endpoints can appear/disappear as network interfaces change, and the same descriptor is returned regardless of which endpoint the client used. Extending the descriptor would blur environment identity with transport reachability and make saved environments harder to reason about.
+
+### Target Contract
+
+Add a schema in `packages/contracts`, likely `remoteAccess.ts`:
+
+```ts
+type AdvertisedEndpointProvider =
+  | "loopback"
+  | "lan"
+  | "tailscale-ip"
+  | "tailscale-magicdns"
+  | "manual"
+  | "t3-tunnel";
+
+type AdvertisedEndpointVisibility = "local" | "private-network" | "tailnet" | "public";
+
+type AdvertisedEndpointCompatibility = {
+  hostedHttpsApp: "compatible" | "mixed-content-blocked" | "untrusted-certificate" | "unknown";
+  desktopApp: "compatible" | "unknown";
+};
+
+type AdvertisedEndpoint = {
+  id: string;
+  provider: AdvertisedEndpointProvider;
+  label: string;
+  httpBaseUrl: string;
+  wsBaseUrl: string;
+  visibility: AdvertisedEndpointVisibility;
+  compatibility: AdvertisedEndpointCompatibility;
+  source: "server" | "desktop" | "user";
+  status: "available" | "unavailable" | "unknown";
+  isDefault?: boolean;
+};
+```
+
+Keep the contract schema-only. All classification logic belongs in `packages/shared`, `apps/server`, `apps/desktop`, or `apps/web`.
+
+## HTTP/WS and HTTPS/WSS Readiness
+
+The codebase is partially ready, but the UX and compatibility model are not explicit enough.
+
+What is ready:
+
+- Remote target parsing already derives `ws://` from `http://` and `wss://` from `https://`.
+- Saved environments store both HTTP and WebSocket base URLs.
+- Remote auth uses bearer tokens instead of cookies, so cross-origin hosted clients are viable.
+- WebSocket connections can use a dynamically issued `wsToken`.
+- Server CORS support exists for browser remote auth endpoints.
+
+What is not solved by code alone:
+
+- `https://app.t3.codes` cannot reliably call `http://...` or `ws://...` endpoints because browsers block mixed content.
+- `wss://100.x.y.z:3773` needs a certificate the browser trusts. A raw Tailscale IP does not solve certificate trust.
+- LAN `http://192.168.x.y:3773` is usable from another desktop/native context but not from the hosted HTTPS app.
+- The UI needs to explain why an endpoint is copyable for desktop pairing but not hosted-app compatible.
+
+Policy:
+
+- Support both HTTP/WS and HTTPS/WSS at the runtime layer.
+- Mark endpoint compatibility at the product layer.
+- Generate `app.t3.codes` links only from endpoints that are likely hosted-browser compatible, or show a warning with an explicit fallback.
+
+## Architecture
+
+### Endpoint Sources
+
+Endpoint records can come from several providers:
+
+1. **Server runtime**
+   - headless bind host and port
+   - server-known explicit advertised host config
+
+2. **Desktop shell**
+   - loopback backend URL
+   - LAN exposure state
+   - network interface discovery
+   - Tailscale CLI/status discovery
+
+3. **User configuration**
+   - manually added hostnames
+   - preferred endpoint labels
+   - hidden/disabled endpoints
+
+4. **Future cloud provider**
+   - T3 Tunnel endpoint
+   - billing/account status
+   - tunnel lifecycle state
+
+### Endpoint Registry
+
+Create a central runtime registry:
+
+- `packages/contracts/src/remoteAccess.ts`
+- `packages/shared/src/remoteAccess.ts` for URL normalization and compatibility classification
+- `apps/server/src/remoteAccess/*` for server/headless endpoints
+- `apps/desktop/src/remoteAccess/*` for desktop-discovered endpoints
+- `apps/web/src/environments/endpoints/*` for client-side display and pairing selection
+
+The web app should consume endpoint records and not care whether they came from LAN, Tailscale, or a future tunnel.
+
+### Pairing Link Generation
+
+Move hosted pairing link generation to endpoint-driven input:
+
+```ts
+buildHostedPairingUrl({
+  endpoint: AdvertisedEndpoint,
+  token,
+});
+```
+
+Generated URL:
+
+```text
+https://app.t3.codes/pair?host=<encoded endpoint httpBaseUrl>#token=<one-time token>
+```
+
+Use fragment tokens by default. Continue accepting `?token=` for compatibility.
+
+## Phase 1: Endpoint Abstraction
+
+### Goals
+
+- Centralize URL normalization, protocol derivation, and compatibility checks.
+- Replace ad hoc desktop `endpointUrl` pairing logic with endpoint selection.
+- Preserve all current remote behavior.
+
+### Tasks
+
+1. Add `AdvertisedEndpoint` schemas to `packages/contracts`.
+2. Add shared helpers:
+   - normalize HTTP base URL
+   - derive WebSocket base URL
+   - classify loopback/private/LAN/Tailscale/public host
+   - classify hosted HTTPS compatibility
+3. Add server endpoint discovery:
+   - loopback endpoint
+   - configured non-loopback endpoint
+   - explicit advertised host override
+4. Add desktop endpoint discovery:
+   - local loopback
+   - LAN exposure endpoint
+   - endpoint status labels
+5. Add WebSocket/API method or existing config field for endpoint snapshots.
+6. Refactor settings connections UI:
+   - render endpoint rows
+   - endpoint picker for pairing link copy
+   - show compatibility warnings
+7. Refactor hosted link builder to accept endpoint records.
+8. Add tests for URL normalization and compatibility classification.
+
+### Acceptance Criteria
+
+- Existing LAN/network access UI still works.
+- Pairing links are generated from endpoint records.
+- Loopback endpoints never produce hosted pairing links silently.
+- HTTP private-network endpoints are marked incompatible with `app.t3.codes`.
+- No remote environment runtime changes are required for existing saved environments.
+
+## Phase 2: BYO Tailscale/MagicDNS
+
+### Goals
+
+- Detect free DIY Tailscale reachability.
+- Surface Tailscale endpoints as normal advertised endpoints.
+- Keep users in control of their own tailnet.
+
+### Tasks
+
+1. Detect Tailscale IPs from network interfaces:
+   - IPv4 `100.64.0.0/10`
+   - mark as `provider: "tailscale-ip"`
+2. Add optional desktop-side `tailscale status --json` discovery:
+   - MagicDNS hostname
+   - Tailscale Serve/Funnel HTTPS endpoint if discoverable
+   - graceful failure if CLI is missing
+3. Add manual Tailscale endpoint override:
+   - hostname
+   - label
+   - preferred/default flag
+4. Show Tailscale endpoint rows in settings:
+   - raw IP HTTP endpoint: desktop-compatible, hosted-app likely blocked
+   - HTTPS MagicDNS/Serve endpoint: hosted-compatible if URL is HTTPS
+5. Generate pairing links using selected Tailscale endpoint.
+6. Document DIY setup:
+   - local desktop-to-desktop over Tailscale
+   - hosted app requirements
+   - why HTTPS matters
+
+### Acceptance Criteria
+
+- A machine on Tailscale shows a Tailscale endpoint without paid features.
+- Users can copy a Tailscale-hosted pairing link when the endpoint is HTTPS-compatible.
+- Users can still copy token-only/manual values when endpoint compatibility is unknown.
+- Tailscale is optional and never required for regular LAN/loopback use.
+
+## Phase 3: Hosted Static App Completion
+
+### Goals
+
+- `app.t3.codes` works as a real client shell.
+- It can pair, persist, reconnect, and clearly explain offline/incompatible states.
+
+### Tasks
+
+1. Finish hosted-static root behavior:
+   - no primary backend required
+   - saved environment hydration before initial routing decisions
+   - first saved environment selected as active
+2. Add hosted empty state:
+   - no saved environments
+   - paste pairing URL
+   - add host + token
+3. Add offline saved environment UI:
+   - last connected
+   - reconnect
+   - remove
+   - copy/add alternate endpoint
+4. Audit primary-backend assumptions:
+   - command palette
+   - settings pages
+   - server config atom defaults
+   - keybindings
+   - provider/model lists
+   - update/desktop-only affordances
+5. Add route tests for:
+   - hosted `/pair?host=...#token=...`
+   - hosted root with no saved environments
+   - hosted root with saved environment
+   - primary backend unavailable but saved environment present
+6. Add deployment hardening:
+   - SPA fallback
+   - strict CSP
+   - no third-party scripts
+   - no query token logging
+   - disable or hide source maps in production if needed
+7. Add browser error messages:
+   - mixed content
+   - unreachable backend
+   - CORS failure
+   - certificate failure
+
+### Acceptance Criteria
+
+- `app.t3.codes` can pair a reachable HTTPS backend and reconnect after reload.
+- A saved environment can be used without any backend at `app.t3.codes`.
+- Offline machines show a useful state instead of a generic boot error.
+- HTTP endpoints are still supported in desktop/native/local contexts.
+- Hosted HTTPS app only promises compatibility for HTTPS/WSS endpoints.
+
+## Phase 4: Future T3 Tunnel Provider
+
+Not part of the current implementation, but the endpoint abstraction should make it straightforward.
+
+Future tunnel provider responsibilities:
+
+- create endpoint with `provider: "t3-tunnel"`
+- surface tunnel status
+- provide stable HTTPS URL
+- use existing backend pairing/session auth
+- never bypass server auth
+
+The tunnel fabric can later be Pipenet-derived, Tailscale-derived, or another reverse tunnel implementation. The rest of T3 Code should only see an `AdvertisedEndpoint`.
+
+## Security Checklist
+
+- Pairing tokens are short-lived and one-time.
+- Generated hosted pairing links put tokens in the fragment.
+- The backend remains the authorization boundary.
+- Endpoint discovery never disables backend auth.
+- Hosted app does not silently downgrade to HTTP.
+- Tunnel/public endpoints require explicit user action.
+- Client sessions remain revocable.
+- Endpoint URLs and request logs must avoid recording pairing tokens.
+- Future cloud tunnel must authenticate tunnel creation and tunnel data connections separately from backend pairing.
+
+## Verification
+
+Each implementation PR should run:
+
+- `bun fmt`
+- `bun lint`
+- `bun typecheck`
+- focused tests for changed backend/web behavior
+- backend tests for any server-side endpoint discovery or auth changes using `bun run test`, never `bun test`
diff --git a/.plans/19-version-control-phase-1-vcs-driver-foundation.md b/.plans/19-version-control-phase-1-vcs-driver-foundation.md
new file mode 100644
index 00000000000..e71c22d0ce3
--- /dev/null
+++ b/.plans/19-version-control-phase-1-vcs-driver-foundation.md
@@ -0,0 +1,216 @@
+# Version Control Phase 1: VCS Driver Foundation
+
+## Goal
+
+Introduce a provider-neutral VCS layer and rewrite the local Git implementation as an Effect-native driver. This phase should preserve user-visible behavior while replacing the Git-first service boundary with an abstraction that can support Git, Jujutsu, and later Sapling or another viable VCS.
+
+The existing `GitCore` implementation is a behavior reference and source of regression tests, not the target architecture. New code should follow the newer package style used by `effect-acp` and `effect-codex-app-server`: typed service tags, schema-backed tagged errors, scoped process usage, explicit decode boundaries, and no Promise-based process helper as the core execution primitive.
+
+## Scope
+
+- Add VCS-domain contracts in `packages/contracts/src/vcs.ts`.
+- Add shared runtime parsing helpers in `packages/shared/src/vcs/*` only when they are useful to both server and web.
+- Add server services under `apps/server/src/vcs`:
+  - `Services/VcsDriver.ts`
+  - `Services/VcsRepositoryResolver.ts`
+  - `Services/VcsProcess.ts`
+  - `Layers/GitVcsDriver.ts`
+  - `errors.ts`
+- Migrate server callers from Git-specific terms where the operation is actually VCS-generic.
+- Update active consumers to the new VCS APIs in the same phase; do not add backwards-compatible export shims.
+- Leave source-control hosting providers out of this phase except for remote metadata needed to describe repository status.
+
+## Non-Goals
+
+- No GitLab, Azure DevOps, or GitHub provider rewrite yet.
+- No Jujutsu driver yet, but every interface must be designed so a Jujutsu driver does not have to pretend to be Git.
+- No T3 Review implementation yet.
+- No broad UI redesign.
+
+## Driver Model
+
+Use provider-neutral nouns in new APIs:
+
+- `VcsDriver`: local repository mechanics.
+- `RepositoryIdentity`: detected VCS kind, root path, common metadata path when available, remotes.
+- `WorkingCopyStatus`: dirty state, changed files, aggregate insertions/deletions, current branch/bookmark/change name.
+- `ChangeSet`: a committed or pending unit of change, not necessarily a Git commit.
+- `RefName`: branch, bookmark, tag, or provider-specific ref.
+
+The initial driver capabilities should be explicit:
+
+```ts
+export interface VcsDriverCapabilities {
+  readonly kind: "git" | "jj" | "sapling" | "unknown";
+  readonly supportsWorktrees: boolean;
+  readonly supportsBookmarks: boolean;
+  readonly supportsAtomicSnapshot: boolean;
+  readonly supportsPushDefaultRemote: boolean;
+}
+```
+
+Do not model Jujutsu as `GitCoreShape extends ...`. The Git driver can expose Git-specific implementation details internally, but the public VCS layer should describe operations by intent:
+
+- `detectRepository(cwd)`
+- `status(cwd, options)`
+- `listRefs(cwd, query/pagination)`
+- `checkoutRef(cwd, ref)`
+- `createRef(cwd, ref, from?)`
+- `createWorkspace(cwd, ref, path?)`
+- `removeWorkspace(path)`
+- `prepareChangeContext(cwd, filePaths?)`
+- `createChange(cwd, message, options)`
+- `push(cwd, target?)`
+- `rangeContext(cwd, base, head)`
+- `listWorkspaceFiles(cwd, options)`
+
+## Effect Process Layer
+
+Create a small reusable `VcsProcess` service instead of using `runProcess`.
+
+Requirements:
+
+- Implement with `ChildProcess` and `ChildProcessSpawner` from `effect/unstable/process`.
+- Support scoped acquisition/release for long-running commands and interruption.
+- Support bounded stdout/stderr collection with truncation markers.
+  - DO not eagerly consume full stdout/stderr, return stream apis and expose helpers for consumers so we don't consume streams to memory unnecessarily...
+- Support stdin.
+- Support timeout through Effect scheduling/interruption, not ad-hoc timers.
+- Stream output lines to progress callbacks as Effects.
+- Return a typed `ProcessOutput` value for successful execution.
+- Fail with typed errors, not generic thrown exceptions.
+
+Errors should be schema-backed tagged classes, for example:
+
+- `VcsProcessSpawnError`
+- `VcsProcessExitError`
+- `VcsProcessTimeoutError`
+- `VcsOutputDecodeError`
+- `VcsRepositoryDetectionError`
+- `VcsUnsupportedOperationError`
+
+Every error should carry operation name, command display string, cwd when applicable, exit code when applicable, stderr/stdout tails when useful, and original cause where available. Override `message` for user readable messages that provides meaning and hints where appropriate. Errors are schema backed so the full error details will be persisted and serialized properly when stored to DB/Logfiles.
+
+## Git Driver Rewrite
+
+Rewrite Git support against `VcsProcess`.
+
+Carry forward current behavior from:
+
+- `apps/server/src/git/Layers/GitCore.ts`
+- `apps/server/src/git/Layers/GitCore.test.ts`
+- current Git status/branch/worktree contracts
+
+But split the implementation into smaller modules:
+
+- command execution and hardening config
+- repository detection
+- status parsing
+- branch/ref parsing
+- worktree operations
+- commit/range context generation
+- push/pull operations
+
+Keep parsing deterministic. Prefer Git porcelain formats, null-separated output, and schema decoding for JSON-like command output. Avoid regex parsing where Git gives a structured format.
+
+## Freshness and Local Caching
+
+Define freshness rules in the VCS layer before adding more providers. Local VCS status is cheap enough to refresh often; network-backed status is not.
+
+Treat these as live/local:
+
+- repository detection for the active cwd
+- working copy dirty state
+- staged/unstaged/untracked file summaries
+- current branch/bookmark/change name
+- local branch/bookmark lists
+- local worktree/workspace lists
+
+These may run on user-visible polling, but should still be debounced and coalesced per repository root. Prefer filesystem-triggered invalidation where available, with a short fallback poll interval. Concurrent requests for the same repository/status shape should share one in-flight Effect.
+
+Treat these as cached or explicit-refresh only:
+
+- remote tracking branch refreshes
+- ahead/behind counts that require network fetches
+- default branch discovery from a remote provider
+- remote branch lists beyond locally known refs
+
+The VCS driver should expose freshness metadata with status results:
+
+```ts
+export interface VcsFreshness {
+  readonly source: "live-local" | "cached-local" | "cached-remote" | "explicit-remote";
+  readonly observedAt: string;
+  readonly expiresAt?: string;
+}
+```
+
+Remote refreshes should be opt-in per operation, for example `refresh: "local-only" | "allow-cached-remote" | "force-remote"`. The default for background status should be `local-only`.
+
+Use Effect `Cache` for repository identity and expensive local metadata:
+
+- key by resolved repository root plus VCS kind
+- invalidate on cwd/root changes and workspace mutation operations
+- use short TTLs for local status caches when filesystem events are unavailable
+- never hide command failures behind stale values unless the caller explicitly accepts stale data
+
+## Cutover Policy
+
+Prefer direct migration and deletion over compatibility wrappers.
+
+Rules:
+
+- Update consumers to call `VcsDriver`/`VcsRepositoryResolver` directly as soon as the new API exists.
+- Delete migrated `GitCore` service methods and tests in the same PR that moves their consumers.
+- Do not keep backwards-compatible export shims, barrel aliases, or old service names for convenience.
+- Transitional modules are allowed only when a caller group is too complex or risky to migrate in the same PR.
+- Every transitional module must have a narrow owner, a removal checklist, and a test proving it delegates to the new implementation.
+- No new feature work may depend on transitional modules.
+
+Expected transitional candidates:
+
+- The highest-level `GitManager` orchestration can be migrated in slices if doing the full Commit + PR flow in one PR is too risky.
+- WebSocket payload compatibility can remain only where changing it would require a coordinated UI/server protocol migration. Internal server code should still use the new VCS contracts.
+
+## Tests
+
+Add integration-style tests with real temporary Git repositories for the new Git driver:
+
+- non-repository detection
+- status for clean/dirty/untracked/staged states
+- branch/ref list with pagination
+- checkout/create branch
+- worktree create/remove
+- commit context generation with file filters
+- commit creation with hook progress events
+- push behavior against a local bare remote
+- status polling does not perform remote network refresh by default
+- concurrent duplicate status requests are coalesced
+- bounded output/truncation
+- timeout/interruption
+- typed error shape for command failure and missing executable
+
+Move or duplicate only the tests needed to prove behavior, then delete the old service tests in the same migration slice.
+
+## Migration Steps
+
+1. Add `vcs` contracts and tagged errors.
+2. Add `VcsProcess` and unit tests around process execution semantics.
+3. Add `VcsDriver` and `VcsRepositoryResolver` service contracts.
+4. Implement `GitVcsDriver` with real Git command integration tests.
+5. Move `GitStatusBroadcaster` and branch/worktree flows to the VCS service directly.
+6. Move commit/range/push callers to the VCS service directly.
+7. Delete migrated `GitCore` internals and tests as each caller group moves.
+8. Add a transitional adapter only for any remaining `GitManager` path that is explicitly too complex to cut over safely in one PR.
+9. Remove every transitional adapter before starting Phase 2 unless the adapter is documented as blocking on the provider cutover.
+
+## Acceptance Criteria
+
+- Current Git branch/status/worktree/commit behavior remains intact.
+- New Git implementation does not depend on `processRunner.ts`.
+- New errors are typed and inspectable by tests.
+- VCS interfaces contain no GitHub/GitLab/Azure concepts.
+- Active consumers use the new VCS APIs directly; any remaining transitional module has a written removal checklist and no compatibility export shim.
+- Background status refresh is local-only by default and cannot hit provider rate limits.
+- Jujutsu can be added by implementing a real driver instead of conforming to Git command semantics.
+- `bun fmt`, `bun lint`, and `bun typecheck` pass.
diff --git a/.plans/20-version-control-phase-2-source-control-provider-foundation.md b/.plans/20-version-control-phase-2-source-control-provider-foundation.md
new file mode 100644
index 00000000000..ac1186ba5f9
--- /dev/null
+++ b/.plans/20-version-control-phase-2-source-control-provider-foundation.md
@@ -0,0 +1,268 @@
+# Version Control Phase 2: Source Control Provider Foundation
+
+## Goal
+
+Introduce a pluggable source-control provider layer and rewrite GitHub support as an Effect-native provider. This phase should preserve the existing GitHub Commit + PR flow while making GitLab and Azure DevOps additive drivers rather than branches inside GitHub-oriented code.
+
+The existing `GitHubCli` service and GitHub-specific `GitManager` paths are behavior references. The new provider layer should use detailed tagged errors, schema decode boundaries, `effect/unstable/process`, capability flags, and provider-neutral change-request types.
+
+## Scope
+
+- Add provider-domain contracts in `packages/contracts/src/sourceControl.ts`.
+- Add provider URL/reference parsing helpers in `packages/shared/src/sourceControl/*`.
+- Add server services under `apps/server/src/sourceControl`:
+  - `Services/SourceControlProvider.ts`
+  - `Services/SourceControlProviderRegistry.ts`
+  - `Services/SourceControlProcess.ts`
+  - `Layers/GitHubSourceControlProvider.ts`
+  - `errors.ts`
+- Migrate PR creation, PR lookup, default-branch lookup, clone URL lookup, and PR checkout through the provider layer.
+- Update active consumers to the provider APIs directly; do not add backwards-compatible `GitHubCli` export shims.
+- Keep GitHub as the only production provider at the end of this phase, but make GitLab and Azure implementation paths obvious and bounded.
+
+## Non-Goals
+
+- No GitLab implementation in this phase, except fixtures/contracts that prove the abstraction can represent merge requests.
+- No Azure DevOps implementation in this phase, except URL/reference parser test cases if cheap.
+- No in-app review UI yet.
+- No hard dependency on one CLI forever. The first GitHub driver may use `gh`, but the interface should support REST/GraphQL implementations later.
+
+## Provider Model
+
+Use provider-neutral names:
+
+- `SourceControlProvider`: hosted repository and change-request mechanics.
+- `ChangeRequest`: GitHub pull request, GitLab merge request, Azure pull request.
+- `ChangeRequestThread`: review or discussion thread.
+- `ChangeRequestComment`: top-level or inline comment.
+- `ProviderRepository`: owner/project/repo identity plus clone URLs.
+
+Core provider operations:
+
+- `detectRemote(remoteUrl)`
+- `checkAuth(cwd)`
+- `getRepository(cwd | remoteUrl)`
+- `getDefaultTargetRef(repository)`
+- `listChangeRequests(repository, filters)`
+- `getChangeRequest(repository, reference)`
+- `createChangeRequest(repository, input)`
+- `checkoutChangeRequest(cwd, changeRequest, options)`
+- `getCloneUrls(repository)`
+
+Review-facing operations should be designed now, even if unimplemented:
+
+- `listReviewThreads(changeRequest)`
+- `createReviewComment(changeRequest, input)`
+- `replyToReviewThread(thread, input)`
+- `resolveReviewThread(thread)`
+- `submitReview(changeRequest, input)`
+
+Each operation should be guarded by capabilities:
+
+```ts
+export interface SourceControlProviderCapabilities {
+  readonly kind: "github" | "gitlab" | "azure-devops" | "unknown";
+  readonly supportsCreateChangeRequest: boolean;
+  readonly supportsCheckoutChangeRequest: boolean;
+  readonly supportsReviewThreads: boolean;
+  readonly supportsInlineComments: boolean;
+  readonly supportsDraftChangeRequests: boolean;
+}
+```
+
+## Provider Registry
+
+Add a registry that resolves a provider from repository remotes and explicit user input.
+
+Rules:
+
+- Detection should be pure where possible and testable without spawning CLIs.
+- Remote URL parsing belongs in `packages/shared`, not server-only provider layers.
+- Unknown providers should return explicit unsupported-operation errors, not silently fall back to GitHub.
+- Provider selection should be stable per operation and logged with enough context to debug bad remote detection.
+
+The registry should support multiple provider implementations at runtime, not a single dispatcher file with inline provider branches.
+
+## Rate Limits and Provider Caching
+
+Design the provider layer around a strict freshness budget. Provider API and CLI calls must not be part of frequent background polling unless the operation is explicitly marked safe and cached.
+
+Default behavior:
+
+- Pure URL/remote parsing is always live because it is local.
+- Provider detection from local remotes is live-local.
+- Authentication checks are cached.
+- Repository metadata is cached.
+- Default branch metadata is cached.
+- Change-request lists are cached and refreshed on explicit user actions or coarse intervals.
+- Full review threads, comments, file diffs, and timeline data are fetched only when the user opens the relevant review surface or explicitly refreshes it.
+- Create/update operations invalidate affected cache keys immediately after success.
+
+The provider API should make freshness explicit:
+
+```ts
+export interface SourceControlFreshness {
+  readonly source: "live-local" | "cached-provider" | "live-provider";
+  readonly observedAt: string;
+  readonly expiresAt?: string;
+  readonly stale?: boolean;
+}
+
+export type ProviderRefreshPolicy =
+  | "cache-first"
+  | "stale-while-revalidate"
+  | "force-refresh"
+  | "local-only";
+```
+
+Every read operation that can touch a provider should accept a refresh policy. Background UI reads should default to `cache-first` or `stale-while-revalidate`; direct user actions like pressing refresh can use `force-refresh`.
+
+Use Effect `Cache` for provider data:
+
+- auth status: key by provider kind, hostname, workspace identity, and account if known; TTL around minutes, not seconds
+- repository metadata/default branch: key by provider repository stable ID or normalized remote URL; TTL around tens of minutes
+- change-request summary lists: key by provider repository, state/filter, source ref, target ref; short TTL with stale-while-revalidate
+- individual change-request summaries: key by provider repository and provider CR ID; short TTL, invalidated after create/update/comment operations
+- review threads/comments/diffs: key by provider CR ID and head SHA/version when available; fetch on demand for T3 Review
+
+Provider drivers should surface rate-limit signals when available:
+
+- remaining quota
+- reset time
+- retry-after duration
+- whether the limit is primary, secondary/abuse, or unknown
+
+Rate-limit errors should be typed, retryable when the provider gives a reset/retry time, and visible enough for the UI to avoid repeatedly retrying a blocked operation.
+
+Avoid rate-limit footguns:
+
+- no provider calls from render loops or fast status polling
+- no listing all PRs/MRs across all repos to infer one branch state
+- no silent GitHub fallback for unknown providers
+- no unbounded cache cardinality for branch names or free-form search queries
+- no per-thread duplicate provider refresh when multiple views observe the same repository
+
+## GitHub Provider Rewrite
+
+Rewrite GitHub support as `GitHubSourceControlProvider`.
+
+Carry forward behavior from:
+
+- `apps/server/src/git/Layers/GitHubCli.ts`
+- `apps/server/src/git/Layers/GitHubCli.test.ts`
+- `apps/server/src/git/githubPullRequests.ts`
+- GitHub-specific `GitManager` PR paths
+
+Implementation requirements:
+
+- Use `SourceControlProcess` built on `effect/unstable/process`, not `runProcess`.
+- Decode `gh api` and `gh pr --json` responses with Effect Schema.
+- Use typed errors for auth failure, missing CLI, command failure, output decode failure, unsupported reference, and provider mismatch.
+- Keep stdout/stderr bounded.
+- Avoid global mutable auth caches unless they are Effect `Cache` values with explicit keys, TTLs, and invalidation behavior.
+- Parse provider rate-limit headers or CLI/API error payloads when available and map them to typed rate-limit errors.
+- Keep GitHub nouns inside the GitHub driver; convert to `ChangeRequest` at the provider boundary.
+
+## GitManager Cutover
+
+Refactor `GitManager` so it coordinates three independent services:
+
+- `VcsDriver` for local repository mechanics.
+- `SourceControlProviderRegistry` for hosted provider selection.
+- `TextGeneration` for message/body generation.
+
+`GitManager` should stop depending directly on GitHub services. User-visible step labels should be provider-neutral unless the selected provider is known and the label is intentionally provider-specific.
+
+The Commit + PR flow should become:
+
+1. Resolve VCS repository and local status.
+2. Resolve source-control provider from remotes.
+3. Generate commit content through the existing text generation service.
+4. Create local change through `VcsDriver`.
+5. Push through `VcsDriver` or a narrow provider push helper only if the VCS requires provider-specific target syntax.
+6. Generate change-request title/body.
+7. Create the change request through `SourceControlProvider`.
+
+## Cutover Policy
+
+This phase should aggressively remove old GitHub-specific internals.
+
+Rules:
+
+- Move each active consumer directly to `SourceControlProviderRegistry` or a concrete provider test layer.
+- Delete migrated `GitHubCli` methods, tests, and GitHub-specific helper exports in the same PR that moves their final consumer.
+- Do not add compatibility export shims from `apps/server/src/git` to `apps/server/src/sourceControl`.
+- Transitional modules are allowed only for a bounded `GitManager` slice that cannot move safely with the rest of the provider cutover.
+- Every transitional module must have an owner comment, a removal checklist, and no public exports consumed by new code.
+- Provider-neutral web parsing should replace GitHub-only parsing directly; do not keep parallel parser stacks unless a route still requires both during a single PR.
+
+## GitLab and Azure Readiness
+
+Use the triaged references as implementation inputs, not merge targets:
+
+- GitLab PR #592 is useful for `glab mr` command mapping and JSON normalization.
+- Azure issue #1138 defines a good first Azure slice: remote/URL detection and change-request thread setup for same-repo URLs.
+
+The abstraction should let Phase 3 add:
+
+- `GitLabSourceControlProvider` using `glab`.
+- `AzureDevOpsSourceControlProvider` using `az repos pr` or REST APIs.
+
+No provider should need to edit GitHub code to join the registry.
+
+## T3 Review Design Constraint
+
+Do not optimize only for creation/checkout. The provider layer must be able to support a future in-app review surface.
+
+That means contracts should include stable IDs and enough metadata for:
+
+- file-level diffs
+- inline review threads
+- resolved/unresolved state
+- top-level discussion comments
+- pending review submission
+- provider URL back-links
+
+Provider-specific fields can live in a metadata bag, but core review behavior should not require the UI to know whether the backing service is GitHub, GitLab, or Azure DevOps.
+
+## Tests
+
+Add tests at three levels:
+
+- Pure parser tests for GitHub, GitLab, and Azure remote URLs and change-request references.
+- Provider unit tests with fake `SourceControlProcess` output and schema decode failures.
+- Integration-style GitHub CLI tests only where they can run hermetically or be skipped without hiding unit coverage.
+
+Required cases:
+
+- GitHub PR URL, number, and branch-ish references.
+- GitLab MR URL/reference parsing.
+- Azure DevOps PR URL parsing for same-repo URLs.
+- unknown provider returns unsupported-operation errors.
+- missing CLI and auth failures produce distinct typed errors.
+- invalid CLI JSON fails at decode boundary with useful context.
+
+## Migration Steps
+
+1. Add `sourceControl` contracts and provider-neutral schemas.
+2. Add shared remote/reference parser helpers and tests.
+3. Add `SourceControlProcess` and provider errors.
+4. Add provider registry with GitHub-only registration.
+5. Implement `GitHubSourceControlProvider` from scratch against the new process layer.
+6. Cut GitHub PR operations in `GitManager` over to the provider registry.
+7. Replace web PR-reference parsing with provider-neutral parser output while keeping current GitHub UX.
+8. Add provider cache metrics and tests for cache hit, stale refresh, invalidation, and rate-limit error mapping.
+9. Delete the migrated `GitHubCli` implementation, tests, and GitHub-specific helper exports unless an explicit transitional checklist remains.
+
+## Acceptance Criteria
+
+- Existing GitHub Commit + PR and PR checkout flows still work.
+- `GitManager` no longer imports or depends on `GitHubCli`.
+- Active consumers use source-control provider APIs directly; any remaining transitional module has a written removal checklist and no compatibility export shim.
+- Source-control contracts can represent GitHub PRs, GitLab MRs, and Azure DevOps PRs.
+- Unknown/unsupported providers fail explicitly and visibly.
+- GitHub command execution does not depend on `processRunner.ts`.
+- Background provider reads are cached/coalesced and do not consume provider API quota on every status refresh.
+- Rate-limit responses become typed errors with retry/reset metadata where available.
+- The provider API includes the review operations needed by future T3 Review work, even if they are capability-gated.
+- `bun fmt`, `bun lint`, and `bun typecheck` pass.
diff --git a/.plans/README.md b/.plans/README.md
index 7bb69a3b912..379158d4efd 100644
--- a/.plans/README.md
+++ b/.plans/README.md
@@ -10,3 +10,5 @@
 8. `08-precommit-format-and-lint.md`
 9. `09-event-state-test-expansion.md`
 10. `10-unify-process-session-abstraction.md`
+19. `19-version-control-phase-1-vcs-driver-foundation.md`
+20. `20-version-control-phase-2-source-control-provider-foundation.md`
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 752d9a90713..8a1b614ddd9 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -5,5 +5,5 @@
     "source.fixAll.oxc": "always"
   },
   "oxc.unusedDisableDirectives": "warn",
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "js/ts.tsdk.path": "node_modules/typescript/lib"
 }
diff --git a/README.md b/README.md
index d3a54a1b906..c439743cea5 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,16 @@
 # T3 Code
 
-T3 Code is a minimal web GUI for coding agents (currently Codex and Claude, more coming soon).
+T3 Code is a minimal web GUI for coding agents (currently Codex, Claude, and OpenCode, more coming soon).
 
 ## Installation
 
 > [!WARNING]
-> T3 Code currently supports Codex and Claude.
+> T3 Code currently supports Codex, Claude, and OpenCode.
 > Install and authenticate at least one provider before use:
 >
-> - Codex: install [Codex CLI](https://github.com/openai/codex) and run `codex login`
-> - Claude: install Claude Code and run `claude auth login`
+> - Codex: install [Codex CLI](https://developers.openai.com/codex/cli) and run `codex login`
+> - Claude: install [Claude Code](https://claude.com/product/claude-code) and run `claude auth login`
+> - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
 
 ### Run without installing
 
@@ -49,6 +50,14 @@ Observability guide: [docs/observability.md](./docs/observability.md)
 
 ## If you REALLY want to contribute still.... read this first
 
+Before local development, prepare the environment and install dependencies:
+
+```bash
+# Optional: only needed if you use mise for dev tool management.
+mise install
+bun install .
+```
+
 Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening an issue or PR.
 
 Need support? Join the [Discord](https://discord.gg/jn4EGJjrvv).
diff --git a/REMOTE.md b/REMOTE.md
index 30dc562792f..56510e62890 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -22,9 +22,41 @@ If you are already running the desktop app and want to make it reachable from ot
 
 1. Open **Settings** → **Connections**.
 2. Under **Manage Local Backend**, toggle **Network access** on. This will restart the app and run the backend on all network interfaces.
-3. The settings panel will show the address the server is reachable at (e.g. `http://192.168.x.y:3773`).
+3. The settings panel will show the default reachable endpoint, with a `+N` control when more endpoints are available. Expand it to inspect alternatives such as loopback, LAN, private-network, or HTTPS endpoints.
 4. Use **Create Link** to generate a pairing link you can share with another device.
 
+The default endpoint controls the QR code and primary copy action for pairing links. You can change it from the expanded endpoint list. The preference is stored by endpoint type, so choosing the local LAN endpoint survives normal IP address changes when you move between networks.
+
+When no user default is saved, the app uses the built-in LAN endpoint for pairing links when
+available. You can set another endpoint as the default from the expanded endpoint list.
+
+- HTTPS/WSS-compatible endpoints work from `https://app.t3.codes`, but are not made the default
+  automatically.
+- Non-loopback HTTP endpoints are useful for direct LAN pairing.
+- Loopback-only endpoints are not useful for another device unless that device is the same machine.
+
+If the copied link points directly at `http://192.168.x.y:3773`, open it from a client that can reach that LAN address. If it points at `https://app.t3.codes/pair?...`, the hosted web app will save the environment and connect directly to the backend URL in the link.
+
+### Tailscale Endpoints
+
+When the desktop app can detect Tailscale, it adds Tailnet endpoints to the reachable endpoint list.
+
+Depending on your Tailscale setup, this may include:
+
+- the machine's `100.x.y.z` Tailnet IP
+- a MagicDNS name
+- an HTTPS MagicDNS endpoint when Tailscale Serve is configured for this backend
+
+The Tailscale HTTPS endpoint uses the clean MagicDNS URL, such as
+`https://machine.tailnet.ts.net/`, and is disabled until the app verifies that the URL reaches this
+backend. Use **Setup** on the Tailscale HTTPS row to opt in. The desktop app restarts the backend
+with the same server-side behavior as `t3 serve --tailscale-serve`, then the server asks Tailscale
+Serve to proxy HTTPS traffic to the local backend.
+
+The Tailscale support is an endpoint provider add-on. The core remote model still works without Tailscale: LAN HTTP endpoints, custom HTTPS endpoints, future tunnels, and SSH-launched environments all use the same saved environment and pairing flow.
+
+For `https://app.t3.codes`, prefer an HTTPS Tailnet or other HTTPS endpoint. A plain `http://100.x.y.z:3773` endpoint can still work from a desktop client or another browser page served over HTTP, but it will not work from the hosted HTTPS app because of browser mixed-content rules.
+
 ### Option 2: Headless Server (CLI)
 
 Use this when you want to run the server without a GUI, for example on a remote machine over SSH.
@@ -47,14 +79,79 @@ From there, connect from another device in either of these ways:
 - scan the QR code on your phone
 - in the desktop app, enter the full pairing URL
 - in the desktop app, enter the host and token separately
+- in the hosted web app, open a hosted pairing URL when the backend is reachable over HTTPS
 
 Use `t3 serve --help` for the full flag reference. It supports the same general startup options as the normal server command, including an optional `cwd` argument.
 
+For hosted web pairing over Tailscale HTTPS, opt in to Tailscale Serve:
+
+```bash
+npx t3 serve --tailscale-serve
+```
+
+By default this configures Tailscale Serve on HTTPS port 443 and advertises
+`https://machine.tailnet.ts.net/`. Advanced users can choose a different HTTPS port:
+
+```bash
+npx t3 serve --tailscale-serve --tailscale-serve-port 8443
+```
+
 > Note
 > The GUIs do not currently support adding projects on remote environments.
 > For now, use `t3 project ...` on the server machine instead.
 > Full GUI support for remote project management is coming soon.
 
+### Option 3: Desktop-Managed SSH Launch
+
+Use this when you want the desktop app to start or reuse T3 Code on another machine over SSH.
+
+1. Open **Settings** → **Connections**.
+2. Under **Remote Environments**, choose **Add environment**.
+3. Select the SSH launch flow.
+4. Enter the SSH target, such as `user@example.com`.
+5. Confirm the launch. The desktop app probes the host, starts or reuses a remote T3 server, opens a local port forward, and saves the environment.
+
+After setup, the renderer connects to a local forwarded HTTP/WebSocket endpoint. The remote host still owns the actual T3 server, projects, files, git state, terminals, and provider sessions.
+
+SSH launch is a desktop feature because it needs local process and SSH access. Once the environment is paired and saved, it uses the same environment list and connection model as direct LAN, Tailscale, HTTPS, or future tunnel-backed environments.
+
+#### SSH Launch Troubleshooting
+
+The desktop SSH launcher connects with a non-interactive `sh` session, writes a small launcher script under `~/.t3/ssh-launch/<host-key>/`, starts or reuses a remote T3 server, and forwards the remote loopback port back to your desktop.
+
+The remote host must have a compatible Node.js runtime. T3 Code uses the server package's `engines.node` requirement:
+
+```text
+^22.16 || ^23.11 || >=24.10
+```
+
+During SSH launch, T3 Code first checks whether `node` is already available on `PATH`. If it is missing, the launcher tries common non-interactive shell locations and version-manager shims/activation hooks:
+
+- `~/.local/bin`, `~/bin`, `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
+- Volta via `~/.volta/bin`
+- asdf via `~/.asdf/shims`, `~/.asdf/bin`, or `~/.asdf/asdf.sh`
+- mise via `~/.local/share/mise/shims`, `~/.mise/shims`, or `mise activate sh`
+- fnm via `fnm env --use-on-cd --shell sh` or `fnm env --shell sh`
+- nodenv via `~/.nodenv/bin`, `~/.nodenv/shims`, or `nodenv init -`
+- nvm via `$NVM_DIR/nvm.sh`, then `nvm use default`, `nvm use node`, or `nvm use --lts`
+- installed nvm versions under `$NVM_DIR/versions/node/*/bin`
+
+If launch fails with `node: command not found`, a port-scan failure, or a message that the remote Node version does not satisfy the required range, SSH into the host and check the same non-interactive shell path T3 Code uses:
+
+```bash
+ssh user@example.com 'sh -lc "command -v node && node --version"'
+```
+
+If that does not print a compatible Node version, configure your version manager for non-interactive shells or install a compatible Node binary in one of the searched locations. For example, with nvm you may need a default alias:
+
+```bash
+nvm alias default 24
+```
+
+With mise/asdf/fnm/nodenv, make sure the tool's shim directory is installed and points at a Node version satisfying the range above.
+
+If reconnecting after an app update fails, retry the SSH launch once. The launcher now compares its generated runner script, stops stale launcher-managed remote servers, clears the SSH launch PID/port state, and starts a fresh remote server. You should not normally need to delete `~/.t3/ssh-launch` or kill `t3` processes manually.
+
 ## How Pairing Works
 
 The remote device does not need a long-lived secret up front.
@@ -67,6 +164,20 @@ Instead:
 
 After pairing, future access is session-based. You do not need to keep reusing the original token unless you are pairing a new device.
 
+## Hosted Web App Pairing
+
+The hosted web app at `https://app.t3.codes` can save a remote backend in browser local storage from a URL like:
+
+```text
+https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
+```
+
+Use hosted pairing when the backend is reachable from the browser over HTTPS/WSS. This includes a backend behind a trusted HTTPS tunnel or another HTTPS endpoint you operate.
+
+Do not use hosted pairing for plain HTTP LAN URLs such as `http://192.168.x.y:3773`. Browsers block an HTTPS page from connecting to an insecure HTTP or WS backend. For those endpoints, use the direct pairing URL shown by the desktop app or CLI from a client that can open that HTTP URL directly.
+
+Hosted pairing does not proxy traffic through T3 Code. The browser still connects directly to the backend URL in the pairing link.
+
 ## Managing Access Later
 
 Use `t3 auth` to manage access after the initial pairing flow.
@@ -84,4 +195,5 @@ Use `t3 auth --help` and the nested subcommand help pages for the full reference
 - Treat pairing URLs and pairing tokens like passwords.
 - Prefer binding `--host` to a trusted private address, such as a Tailnet IP, instead of exposing the server broadly.
 - Anyone with a valid pairing credential can create a session until that credential expires or is revoked.
+- Hosted pairing links keep the credential in the URL hash so it is not sent to the hosted app server, but it can still be exposed through browser history, screenshots, logs, or copy/paste.
 - Use `t3 auth` to revoke credentials or sessions you no longer trust.
diff --git a/apps/desktop/.gitignore b/apps/desktop/.gitignore
deleted file mode 100644
index 45b848af652..00000000000
--- a/apps/desktop/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-dist-electron/
-.electron-runtime/
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index a38ffd2df12..ead57b5cbf2 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -1,26 +1,32 @@
 {
   "name": "@t3tools/desktop",
-  "version": "0.0.17",
+  "version": "0.0.24",
   "private": true,
-  "main": "dist-electron/main.js",
+  "type": "module",
+  "main": "dist-electron/main.cjs",
   "scripts": {
     "dev": "bun run --parallel dev:bundle dev:electron",
     "dev:bundle": "tsdown --watch",
-    "dev:electron": "bun run scripts/dev-electron.mjs",
+    "dev:electron": "node scripts/dev-electron.mjs",
     "build": "tsdown",
-    "start": "bun run scripts/start-electron.mjs",
+    "start": "node scripts/start-electron.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
     "smoke-test": "node scripts/smoke-test.mjs"
   },
   "dependencies": {
+    "@effect/platform-node": "catalog:",
+    "@t3tools/contracts": "workspace:*",
+    "@t3tools/shared": "workspace:*",
+    "@t3tools/ssh": "workspace:*",
+    "@t3tools/tailscale": "workspace:*",
     "effect": "catalog:",
-    "electron": "40.6.0",
+    "electron": "41.5.0",
     "electron-updater": "^6.6.2"
   },
   "devDependencies": {
-    "@t3tools/contracts": "workspace:*",
-    "@t3tools/shared": "workspace:*",
+    "@effect/language-service": "catalog:",
+    "@effect/vitest": "catalog:",
     "@types/node": "catalog:",
     "tsdown": "catalog:",
     "typescript": "catalog:",
diff --git a/apps/desktop/scripts/dev-electron.mjs b/apps/desktop/scripts/dev-electron.mjs
index 7c0d55ac9a7..9a7e68dfbbb 100644
--- a/apps/desktop/scripts/dev-electron.mjs
+++ b/apps/desktop/scripts/dev-electron.mjs
@@ -17,12 +17,12 @@ if (!Number.isInteger(port) || port <= 0) {
 }
 
 const requiredFiles = [
-  "dist-electron/main.js",
-  "dist-electron/preload.js",
+  "dist-electron/main.cjs",
+  "dist-electron/preload.cjs",
   "../server/dist/bin.mjs",
 ];
 const watchedDirectories = [
-  { directory: "dist-electron", files: new Set(["main.js", "preload.js"]) },
+  { directory: "dist-electron", files: new Set(["main.cjs", "preload.cjs"]) },
   { directory: "../server/dist", files: new Set(["bin.mjs"]) },
 ];
 const forcedShutdownTimeoutMs = 1_500;
@@ -69,7 +69,7 @@ function startApp() {
 
   const app = spawn(
     resolveElectronPath(),
-    [`--t3code-dev-root=${desktopDir}`, "dist-electron/main.js"],
+    [`--t3code-dev-root=${desktopDir}`, "dist-electron/main.cjs"],
     {
       cwd: desktopDir,
       env: childEnv,
diff --git a/apps/desktop/scripts/electron-launcher.mjs b/apps/desktop/scripts/electron-launcher.mjs
index b8875b08abf..1453cbe666e 100644
--- a/apps/desktop/scripts/electron-launcher.mjs
+++ b/apps/desktop/scripts/electron-launcher.mjs
@@ -6,8 +6,8 @@ import {
   cpSync,
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
-  readdirSync,
   rmSync,
   statSync,
   writeFileSync,
@@ -19,10 +19,13 @@ import { fileURLToPath } from "node:url";
 const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
 const APP_DISPLAY_NAME = isDevelopment ? "T3 Code (Dev)" : "T3 Code (Alpha)";
 const APP_BUNDLE_ID = isDevelopment ? "com.t3tools.t3code.dev" : "com.t3tools.t3code";
-const LAUNCHER_VERSION = 1;
+const LAUNCHER_VERSION = 2;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const desktopDir = resolve(__dirname, "..");
+const repoRoot = resolve(desktopDir, "..", "..");
+const defaultIconPath = join(desktopDir, "resources", "icon.icns");
+const developmentMacIconPngPath = join(repoRoot, "assets", "dev", "blueprint-macos-1024.png");
 
 function setPlistString(plistPath, key, value) {
   const replaceResult = spawnSync("plutil", ["-replace", key, "-string", value, plistPath], {
@@ -43,6 +46,68 @@ function setPlistString(plistPath, key, value) {
   throw new Error(`Failed to update plist key "${key}" at ${plistPath}: ${details}`.trim());
 }
 
+function runChecked(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8" });
+  if (result.status === 0) {
+    return;
+  }
+
+  const details = [result.stdout, result.stderr].filter(Boolean).join("\n");
+  throw new Error(`Failed to run ${command} ${args.join(" ")}: ${details}`.trim());
+}
+
+function ensureDevelopmentIconIcns(runtimeDir) {
+  const generatedIconPath = join(runtimeDir, "icon-dev.icns");
+  mkdirSync(runtimeDir, { recursive: true });
+
+  if (!existsSync(developmentMacIconPngPath)) {
+    return defaultIconPath;
+  }
+
+  const sourceMtimeMs = statSync(developmentMacIconPngPath).mtimeMs;
+  if (existsSync(generatedIconPath) && statSync(generatedIconPath).mtimeMs >= sourceMtimeMs) {
+    return generatedIconPath;
+  }
+
+  const iconsetRoot = mkdtempSync(join(runtimeDir, "dev-iconset-"));
+  const iconsetDir = join(iconsetRoot, "icon.iconset");
+  mkdirSync(iconsetDir, { recursive: true });
+
+  try {
+    for (const size of [16, 32, 128, 256, 512]) {
+      runChecked("sips", [
+        "-z",
+        String(size),
+        String(size),
+        developmentMacIconPngPath,
+        "--out",
+        join(iconsetDir, `icon_${size}x${size}.png`),
+      ]);
+
+      const retinaSize = size * 2;
+      runChecked("sips", [
+        "-z",
+        String(retinaSize),
+        String(retinaSize),
+        developmentMacIconPngPath,
+        "--out",
+        join(iconsetDir, `icon_${size}x${size}@2x.png`),
+      ]);
+    }
+
+    runChecked("iconutil", ["-c", "icns", iconsetDir, "-o", generatedIconPath]);
+    return generatedIconPath;
+  } catch (error) {
+    console.warn(
+      "[desktop-launcher] Failed to generate dev macOS icon, falling back to default icon.",
+      error,
+    );
+    return defaultIconPath;
+  } finally {
+    rmSync(iconsetRoot, { recursive: true, force: true });
+  }
+}
+
 function patchMainBundleInfoPlist(appBundlePath, iconPath) {
   const infoPlistPath = join(appBundlePath, "Contents", "Info.plist");
   setPlistString(infoPlistPath, "CFBundleDisplayName", APP_DISPLAY_NAME);
@@ -55,40 +120,6 @@ function patchMainBundleInfoPlist(appBundlePath, iconPath) {
   copyFileSync(iconPath, join(resourcesDir, "electron.icns"));
 }
 
-function patchHelperBundleInfoPlists(appBundlePath) {
-  const frameworksDir = join(appBundlePath, "Contents", "Frameworks");
-  if (!existsSync(frameworksDir)) {
-    return;
-  }
-
-  for (const entry of readdirSync(frameworksDir, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !entry.name.endsWith(".app")) {
-      continue;
-    }
-    if (!entry.name.startsWith("Electron Helper")) {
-      continue;
-    }
-
-    const helperPlistPath = join(frameworksDir, entry.name, "Contents", "Info.plist");
-    if (!existsSync(helperPlistPath)) {
-      continue;
-    }
-
-    const suffix = entry.name.replace("Electron Helper", "").replace(".app", "").trim();
-    const helperName = suffix
-      ? `${APP_DISPLAY_NAME} Helper ${suffix}`
-      : `${APP_DISPLAY_NAME} Helper`;
-    const helperIdSuffix = suffix.replace(/[()]/g, "").trim().toLowerCase().replace(/\s+/g, "-");
-    const helperBundleId = helperIdSuffix
-      ? `${APP_BUNDLE_ID}.helper.${helperIdSuffix}`
-      : `${APP_BUNDLE_ID}.helper`;
-
-    setPlistString(helperPlistPath, "CFBundleDisplayName", helperName);
-    setPlistString(helperPlistPath, "CFBundleName", helperName);
-    setPlistString(helperPlistPath, "CFBundleIdentifier", helperBundleId);
-  }
-}
-
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -102,7 +133,7 @@ function buildMacLauncher(electronBinaryPath) {
   const runtimeDir = join(desktopDir, ".electron-runtime");
   const targetAppBundlePath = join(runtimeDir, `${APP_DISPLAY_NAME}.app`);
   const targetBinaryPath = join(targetAppBundlePath, "Contents", "MacOS", "Electron");
-  const iconPath = join(desktopDir, "resources", "icon.icns");
+  const iconPath = isDevelopment ? ensureDevelopmentIconIcns(runtimeDir) : defaultIconPath;
   const metadataPath = join(runtimeDir, "metadata.json");
 
   mkdirSync(runtimeDir, { recursive: true });
@@ -126,7 +157,6 @@ function buildMacLauncher(electronBinaryPath) {
   rmSync(targetAppBundlePath, { recursive: true, force: true });
   cpSync(sourceAppBundlePath, targetAppBundlePath, { recursive: true });
   patchMainBundleInfoPlist(targetAppBundlePath, iconPath);
-  patchHelperBundleInfoPlists(targetAppBundlePath);
   writeFileSync(metadataPath, `${JSON.stringify(expectedMetadata, null, 2)}\n`);
 
   return targetBinaryPath;
@@ -140,5 +170,11 @@ export function resolveElectronPath() {
     return electronBinaryPath;
   }
 
+  // Dev launches do not need a renamed app bundle badly enough to risk breaking
+  // Electron helper resource lookup on macOS.
+  if (isDevelopment) {
+    return electronBinaryPath;
+  }
+
   return buildMacLauncher(electronBinaryPath);
 }
diff --git a/apps/desktop/scripts/smoke-test.mjs b/apps/desktop/scripts/smoke-test.mjs
index 883da7203a5..fdbe69b7780 100644
--- a/apps/desktop/scripts/smoke-test.mjs
+++ b/apps/desktop/scripts/smoke-test.mjs
@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const desktopDir = resolve(__dirname, "..");
 const electronBin = resolve(desktopDir, "node_modules/.bin/electron");
-const mainJs = resolve(desktopDir, "dist-electron/main.js");
+const mainJs = resolve(desktopDir, "dist-electron/main.cjs");
 
 console.log("\nLaunching Electron smoke test...");
 
diff --git a/apps/desktop/scripts/start-electron.mjs b/apps/desktop/scripts/start-electron.mjs
index bf93adb6b0d..375dbfe575f 100644
--- a/apps/desktop/scripts/start-electron.mjs
+++ b/apps/desktop/scripts/start-electron.mjs
@@ -5,7 +5,7 @@ import { desktopDir, resolveElectronPath } from "./electron-launcher.mjs";
 const childEnv = { ...process.env };
 delete childEnv.ELECTRON_RUN_AS_NODE;
 
-const child = spawn(resolveElectronPath(), ["dist-electron/main.js"], {
+const child = spawn(resolveElectronPath(), ["dist-electron/main.cjs"], {
   stdio: "inherit",
   cwd: desktopDir,
   env: childEnv,
diff --git a/apps/desktop/src/app/DesktopApp.ts b/apps/desktop/src/app/DesktopApp.ts
new file mode 100644
index 00000000000..b9817552969
--- /dev/null
+++ b/apps/desktop/src/app/DesktopApp.ts
@@ -0,0 +1,240 @@
+import * as Cause from "effect/Cause";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Random from "effect/Random";
+import * as Ref from "effect/Ref";
+
+import * as NetService from "@t3tools/shared/Net";
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronDialog from "../electron/ElectronDialog.ts";
+import * as ElectronProtocol from "../electron/ElectronProtocol.ts";
+import { installDesktopIpcHandlers } from "../ipc/DesktopIpcHandlers.ts";
+import * as DesktopAppIdentity from "./DesktopAppIdentity.ts";
+import * as DesktopApplicationMenu from "../window/DesktopApplicationMenu.ts";
+import * as DesktopBackendManager from "../backend/DesktopBackendManager.ts";
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+import * as DesktopLifecycle from "./DesktopLifecycle.ts";
+import * as DesktopObservability from "./DesktopObservability.ts";
+import * as DesktopServerExposure from "../backend/DesktopServerExposure.ts";
+import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
+import * as DesktopShellEnvironment from "../shell/DesktopShellEnvironment.ts";
+import * as DesktopState from "./DesktopState.ts";
+import * as DesktopUpdates from "../updates/DesktopUpdates.ts";
+
+const DEFAULT_DESKTOP_BACKEND_PORT = 3773;
+const MAX_TCP_PORT = 65_535;
+const DESKTOP_BACKEND_PORT_PROBE_HOSTS = ["127.0.0.1", "0.0.0.0", "::"] as const;
+
+const makeDesktopRunId = Random.nextUUIDv4.pipe(
+  Effect.map((value) => value.replaceAll("-", "").slice(0, 12)),
+);
+
+class DesktopBackendPortUnavailableError extends Data.TaggedError(
+  "DesktopBackendPortUnavailableError",
+)<{
+  readonly startPort: number;
+  readonly maxPort: number;
+  readonly hosts: readonly string[];
+}> {
+  override get message() {
+    return `No desktop backend port is available on hosts ${this.hosts.join(", ")} between ${this.startPort} and ${this.maxPort}.`;
+  }
+}
+
+class DesktopDevelopmentBackendPortRequiredError extends Data.TaggedError(
+  "DesktopDevelopmentBackendPortRequiredError",
+)<{}> {
+  override get message() {
+    return "T3CODE_PORT is required in desktop development.";
+  }
+}
+
+const { logInfo: logBootstrapInfo, logWarning: logBootstrapWarning } =
+  DesktopObservability.makeComponentLogger("desktop-bootstrap");
+
+const { logInfo: logStartupInfo, logError: logStartupError } =
+  DesktopObservability.makeComponentLogger("desktop-startup");
+
+const resolveDesktopBackendPort = Effect.fn("resolveDesktopBackendPort")(function* (
+  configuredPort: Option.Option<number>,
+) {
+  if (Option.isSome(configuredPort)) {
+    return {
+      port: configuredPort.value,
+      selectedByScan: false,
+    } as const;
+  }
+
+  const net = yield* NetService.NetService;
+  for (let port = DEFAULT_DESKTOP_BACKEND_PORT; port <= MAX_TCP_PORT; port += 1) {
+    let availableOnEveryHost = true;
+
+    for (const host of DESKTOP_BACKEND_PORT_PROBE_HOSTS) {
+      if (!(yield* net.canListenOnHost(port, host))) {
+        availableOnEveryHost = false;
+        break;
+      }
+    }
+
+    if (availableOnEveryHost) {
+      return {
+        port,
+        selectedByScan: true,
+      } as const;
+    }
+  }
+
+  return yield* new DesktopBackendPortUnavailableError({
+    startPort: DEFAULT_DESKTOP_BACKEND_PORT,
+    maxPort: MAX_TCP_PORT,
+    hosts: DESKTOP_BACKEND_PORT_PROBE_HOSTS,
+  });
+});
+
+const handleFatalStartupError = Effect.fn("desktop.startup.handleFatalStartupError")(function* (
+  stage: string,
+  error: unknown,
+): Effect.fn.Return<
+  void,
+  never,
+  | DesktopLifecycle.DesktopShutdown
+  | DesktopState.DesktopState
+  | ElectronApp.ElectronApp
+  | ElectronDialog.ElectronDialog
+> {
+  const shutdown = yield* DesktopLifecycle.DesktopShutdown;
+  const state = yield* DesktopState.DesktopState;
+  const electronApp = yield* ElectronApp.ElectronApp;
+  const electronDialog = yield* ElectronDialog.ElectronDialog;
+  const message = error instanceof Error ? error.message : String(error);
+  const detail =
+    error instanceof Error && typeof error.stack === "string" ? `\n${error.stack}` : "";
+  yield* logStartupError("fatal startup error", {
+    stage,
+    message,
+    ...(detail.length > 0 ? { detail } : {}),
+  });
+  const wasQuitting = yield* Ref.getAndSet(state.quitting, true);
+  if (!wasQuitting) {
+    yield* electronDialog.showErrorBox(
+      "T3 Code failed to start",
+      `Stage: ${stage}\n${message}${detail}`,
+    );
+  }
+  yield* shutdown.request;
+  yield* electronApp.quit;
+});
+
+const fatalStartupCause = <E>(stage: string, cause: Cause.Cause<E>) =>
+  handleFatalStartupError(stage, Cause.pretty(cause)).pipe(Effect.andThen(Effect.failCause(cause)));
+
+const bootstrap = Effect.gen(function* () {
+  const backendManager = yield* DesktopBackendManager.DesktopBackendManager;
+  const state = yield* DesktopState.DesktopState;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const desktopSettings = yield* DesktopAppSettings.DesktopAppSettings;
+  const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+  yield* logBootstrapInfo("bootstrap start");
+
+  if (environment.isDevelopment && Option.isNone(environment.configuredBackendPort)) {
+    return yield* new DesktopDevelopmentBackendPortRequiredError();
+  }
+
+  const backendPortSelection = yield* resolveDesktopBackendPort(environment.configuredBackendPort);
+  const backendPort = backendPortSelection.port;
+  yield* logBootstrapInfo(
+    backendPortSelection.selectedByScan
+      ? "selected backend port via sequential scan"
+      : "using configured backend port",
+    {
+      port: backendPort,
+      ...(backendPortSelection.selectedByScan ? { startPort: DEFAULT_DESKTOP_BACKEND_PORT } : {}),
+    },
+  );
+
+  const settings = yield* desktopSettings.get;
+  if (settings.serverExposureMode !== environment.defaultDesktopSettings.serverExposureMode) {
+    yield* logBootstrapInfo("bootstrap restoring persisted server exposure mode", {
+      mode: settings.serverExposureMode,
+    });
+  }
+  const serverExposureState = yield* serverExposure.configureFromSettings({ port: backendPort });
+  const backendConfig = yield* serverExposure.backendConfig;
+  yield* logBootstrapInfo("bootstrap resolved backend endpoint", {
+    baseUrl: backendConfig.httpBaseUrl.href,
+  });
+  if (serverExposureState.endpointUrl) {
+    yield* logBootstrapInfo("bootstrap enabled network access", {
+      endpointUrl: serverExposureState.endpointUrl,
+    });
+  } else if (settings.serverExposureMode === "network-accessible") {
+    yield* logBootstrapWarning(
+      "bootstrap fell back to local-only because no advertised network host was available",
+    );
+  }
+
+  yield* installDesktopIpcHandlers;
+  yield* logBootstrapInfo("bootstrap ipc handlers registered");
+
+  if (!(yield* Ref.get(state.quitting))) {
+    yield* backendManager.start;
+    yield* logBootstrapInfo("bootstrap backend start requested");
+  }
+}).pipe(Effect.withSpan("desktop.bootstrap"));
+
+const startup = Effect.gen(function* () {
+  const appIdentity = yield* DesktopAppIdentity.DesktopAppIdentity;
+  const applicationMenu = yield* DesktopApplicationMenu.DesktopApplicationMenu;
+  const electronApp = yield* ElectronApp.ElectronApp;
+  const electronProtocol = yield* ElectronProtocol.ElectronProtocol;
+  const lifecycle = yield* DesktopLifecycle.DesktopLifecycle;
+  const shellEnvironment = yield* DesktopShellEnvironment.DesktopShellEnvironment;
+  const desktopSettings = yield* DesktopAppSettings.DesktopAppSettings;
+  const updates = yield* DesktopUpdates.DesktopUpdates;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+
+  yield* shellEnvironment.installIntoProcess;
+  const userDataPath = yield* appIdentity.resolveUserDataPath;
+  yield* electronApp.setPath("userData", userDataPath);
+  yield* logStartupInfo("runtime logging configured", { logDir: environment.logDir });
+  yield* desktopSettings.load;
+
+  if (environment.platform === "linux") {
+    yield* electronApp.appendCommandLineSwitch("class", environment.linuxWmClass);
+  }
+
+  yield* appIdentity.configure;
+  yield* lifecycle.register;
+
+  yield* electronApp.whenReady.pipe(
+    Effect.withSpan("desktop.electron.whenReady"),
+    Effect.catchCause((cause) => fatalStartupCause("whenReady", cause)),
+  );
+  yield* logStartupInfo("app ready");
+  yield* appIdentity.configure;
+  yield* applicationMenu.configure;
+  yield* electronProtocol.registerDesktopFileProtocol;
+  yield* updates.configure;
+  yield* bootstrap.pipe(Effect.catchCause((cause) => fatalStartupCause("bootstrap", cause)));
+}).pipe(Effect.withSpan("desktop.startup"));
+
+const scopedProgram = Effect.scoped(
+  Effect.gen(function* () {
+    const runId = yield* makeDesktopRunId;
+    yield* Effect.annotateLogsScoped({ scope: "desktop", runId });
+    yield* Effect.annotateCurrentSpan({ scope: "desktop", runId });
+
+    const shutdown = yield* DesktopLifecycle.DesktopShutdown;
+    const backendManager = yield* DesktopBackendManager.DesktopBackendManager;
+
+    yield* Effect.addFinalizer(() =>
+      backendManager.stop().pipe(Effect.ensuring(shutdown.markComplete)),
+    );
+
+    yield* startup;
+    yield* shutdown.awaitRequest;
+  }),
+);
+
+export const program = scopedProgram.pipe(Effect.withSpan("desktop.app"));
diff --git a/apps/desktop/src/app/DesktopAppIdentity.test.ts b/apps/desktop/src/app/DesktopAppIdentity.test.ts
new file mode 100644
index 00000000000..f95fd1bef71
--- /dev/null
+++ b/apps/desktop/src/app/DesktopAppIdentity.test.ts
@@ -0,0 +1,176 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import type * as Electron from "electron";
+
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as DesktopAppIdentity from "./DesktopAppIdentity.ts";
+import * as DesktopAssets from "./DesktopAssets.ts";
+import * as DesktopConfig from "./DesktopConfig.ts";
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+
+const defaultEnvironmentInput = {
+  dirname: "/repo/apps/desktop/dist-electron",
+  homeDirectory: "/Users/alice",
+  platform: "darwin",
+  processArch: "arm64",
+  appVersion: "1.2.3",
+  appPath: "/Applications/T3 Code.app/Contents/Resources/app.asar",
+  isPackaged: true,
+  resourcesPath: "/Applications/T3 Code.app/Contents/Resources",
+  runningUnderArm64Translation: false,
+} satisfies DesktopEnvironment.MakeDesktopEnvironmentInput;
+
+type TestEnvironmentInput = Partial<DesktopEnvironment.MakeDesktopEnvironmentInput> & {
+  readonly env?: Record<string, string | undefined>;
+};
+
+interface ElectronAppCalls {
+  readonly setAboutPanelOptions: Array<Electron.AboutPanelOptionsOptions>;
+  readonly setDockIcon: string[];
+  readonly setName: string[];
+}
+
+const makeElectronAppLayer = (calls: ElectronAppCalls) =>
+  Layer.succeed(ElectronApp.ElectronApp, {
+    metadata: Effect.die("unexpected metadata read"),
+    name: Effect.succeed("T3 Code"),
+    whenReady: Effect.void,
+    quit: Effect.void,
+    exit: () => Effect.void,
+    relaunch: () => Effect.void,
+    setPath: () => Effect.void,
+    setName: (name) =>
+      Effect.sync(() => {
+        calls.setName.push(name);
+      }),
+    setAboutPanelOptions: (options) =>
+      Effect.sync(() => {
+        calls.setAboutPanelOptions.push(options);
+      }),
+    setAppUserModelId: () => Effect.void,
+    setDesktopName: () => Effect.void,
+    setDockIcon: (iconPath) =>
+      Effect.sync(() => {
+        calls.setDockIcon.push(iconPath);
+      }),
+    appendCommandLineSwitch: () => Effect.void,
+    on: () => Effect.void,
+  } satisfies ElectronApp.ElectronAppShape);
+
+const makeAssetsLayer = (png: Option.Option<string>) =>
+  Layer.succeed(DesktopAssets.DesktopAssets, {
+    iconPaths: Effect.succeed({
+      ico: Option.none(),
+      icns: Option.none(),
+      png,
+    }),
+    resolveResourcePath: () => Effect.succeed(Option.none()),
+  } satisfies DesktopAssets.DesktopAssetsShape);
+
+const makeEnvironmentLayer = (overrides: TestEnvironmentInput = {}) => {
+  const { env, ...environmentOverrides } = overrides;
+  return DesktopEnvironment.layer({
+    ...defaultEnvironmentInput,
+    ...environmentOverrides,
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        DesktopConfig.layerTest({
+          ...env,
+        }),
+      ),
+    ),
+  );
+};
+
+const withIdentity = <A, E, R>(
+  effect: Effect.Effect<
+    A,
+    E,
+    | R
+    | DesktopAppIdentity.DesktopAppIdentity
+    | DesktopEnvironment.DesktopEnvironment
+    | FileSystem.FileSystem
+  >,
+  input: {
+    readonly calls?: ElectronAppCalls;
+    readonly environment?: TestEnvironmentInput;
+    readonly legacyPathExists?: boolean;
+    readonly packageJson?: string;
+    readonly pngIconPath?: Option.Option<string>;
+  } = {},
+) => {
+  const calls: ElectronAppCalls = input.calls ?? {
+    setAboutPanelOptions: [],
+    setDockIcon: [],
+    setName: [],
+  };
+
+  return effect.pipe(
+    Effect.provide(
+      DesktopAppIdentity.layer.pipe(
+        Layer.provideMerge(
+          FileSystem.layerNoop({
+            exists: (path) =>
+              Effect.succeed(input.legacyPathExists === true && path.includes("T3 Code (Alpha)")),
+            readFileString: () =>
+              Effect.succeed(input.packageJson ?? '{"t3codeCommitHash":"abcdef1234567890"}'),
+          }),
+        ),
+        Layer.provideMerge(makeAssetsLayer(input.pngIconPath ?? Option.none())),
+        Layer.provideMerge(makeElectronAppLayer(calls)),
+        Layer.provideMerge(makeEnvironmentLayer(input.environment)),
+      ),
+    ),
+  );
+};
+
+describe("DesktopAppIdentity", () => {
+  it.effect("keeps using the legacy userData path when it already exists", () =>
+    withIdentity(
+      Effect.gen(function* () {
+        const identity = yield* DesktopAppIdentity.DesktopAppIdentity;
+        const userDataPath = yield* identity.resolveUserDataPath;
+
+        assert.equal(userDataPath, "/Users/alice/Library/Application Support/T3 Code (Alpha)");
+      }),
+      { legacyPathExists: true },
+    ),
+  );
+
+  it.effect("configures app identity from the environment commit override", () => {
+    const calls: ElectronAppCalls = {
+      setAboutPanelOptions: [],
+      setDockIcon: [],
+      setName: [],
+    };
+
+    return withIdentity(
+      Effect.gen(function* () {
+        const identity = yield* DesktopAppIdentity.DesktopAppIdentity;
+        yield* identity.configure;
+
+        assert.deepEqual(calls.setName, ["T3 Code (Alpha)"]);
+        assert.equal(calls.setAboutPanelOptions[0]?.applicationName, "T3 Code (Alpha)");
+        assert.equal(calls.setAboutPanelOptions[0]?.applicationVersion, "1.2.3");
+        assert.equal(calls.setAboutPanelOptions[0]?.version, "0123456789ab");
+        assert.deepEqual(calls.setDockIcon, ["/icon.png"]);
+      }),
+      {
+        calls,
+        environment: {
+          env: {
+            T3CODE_COMMIT_HASH: "0123456789abcdef",
+          },
+        },
+        pngIconPath: Option.some("/icon.png"),
+      },
+    );
+  });
+});
diff --git a/apps/desktop/src/app/DesktopAppIdentity.ts b/apps/desktop/src/app/DesktopAppIdentity.ts
new file mode 100644
index 00000000000..c525d01d9d8
--- /dev/null
+++ b/apps/desktop/src/app/DesktopAppIdentity.ts
@@ -0,0 +1,128 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as DesktopAssets from "./DesktopAssets.ts";
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+
+const COMMIT_HASH_PATTERN = /^[0-9a-f]{7,40}$/i;
+const COMMIT_HASH_DISPLAY_LENGTH = 12;
+
+const AppPackageMetadata = Schema.Struct({
+  t3codeCommitHash: Schema.optional(Schema.String),
+});
+const decodeAppPackageMetadata = Schema.decodeEffect(Schema.fromJsonString(AppPackageMetadata));
+
+export interface DesktopAppIdentityShape {
+  readonly resolveUserDataPath: Effect.Effect<string>;
+  readonly configure: Effect.Effect<void>;
+}
+
+export class DesktopAppIdentity extends Context.Service<
+  DesktopAppIdentity,
+  DesktopAppIdentityShape
+>()("t3/desktop/AppIdentity") {}
+
+const normalizeCommitHash = (value: string): Option.Option<string> => {
+  const trimmed = value.trim();
+  return COMMIT_HASH_PATTERN.test(trimmed)
+    ? Option.some(trimmed.slice(0, COMMIT_HASH_DISPLAY_LENGTH).toLowerCase())
+    : Option.none();
+};
+
+const make = Effect.gen(function* () {
+  const assets = yield* DesktopAssets.DesktopAssets;
+  const electronApp = yield* ElectronApp.ElectronApp;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const commitHashCache = yield* Ref.make<Option.Option<Option.Option<string>>>(Option.none());
+
+  const resolveEmbeddedCommitHash = Effect.gen(function* () {
+    const packageJsonPath = environment.path.join(environment.appRoot, "package.json");
+    const raw = yield* fileSystem.readFileString(packageJsonPath).pipe(Effect.option);
+    return yield* Option.match(raw, {
+      onNone: () => Effect.succeed(Option.none<string>()),
+      onSome: (value) =>
+        decodeAppPackageMetadata(value).pipe(
+          Effect.map((parsed) =>
+            Option.fromNullishOr(parsed.t3codeCommitHash).pipe(Option.flatMap(normalizeCommitHash)),
+          ),
+          Effect.catch(() => Effect.succeed(Option.none<string>())),
+        ),
+    });
+  });
+
+  const resolveAboutCommitHash = Effect.gen(function* () {
+    const cached = yield* Ref.get(commitHashCache);
+    if (Option.isSome(cached)) {
+      return cached.value;
+    }
+
+    const override = Option.flatMap(environment.commitHashOverride, normalizeCommitHash);
+    if (Option.isSome(override)) {
+      yield* Ref.set(commitHashCache, Option.some(override));
+      return override;
+    }
+
+    if (!environment.isPackaged) {
+      const empty = Option.none<string>();
+      yield* Ref.set(commitHashCache, Option.some(empty));
+      return empty;
+    }
+
+    const commitHash = yield* resolveEmbeddedCommitHash;
+    yield* Ref.set(commitHashCache, Option.some(commitHash));
+    return commitHash;
+  });
+
+  const resolveUserDataPath = Effect.gen(function* () {
+    const legacyPath = environment.path.join(
+      environment.appDataDirectory,
+      environment.legacyUserDataDirName,
+    );
+    const legacyPathExists = yield* fileSystem
+      .exists(legacyPath)
+      .pipe(Effect.orElseSucceed(() => false));
+    return legacyPathExists
+      ? legacyPath
+      : environment.path.join(environment.appDataDirectory, environment.userDataDirName);
+  }).pipe(Effect.withSpan("desktop.appIdentity.resolveUserDataPath"));
+
+  const configure = Effect.gen(function* () {
+    const commitHash = yield* resolveAboutCommitHash;
+    yield* electronApp.setName(environment.displayName);
+    yield* electronApp.setAboutPanelOptions({
+      applicationName: environment.displayName,
+      applicationVersion: environment.appVersion,
+      version: Option.getOrElse(commitHash, () => "unknown"),
+    });
+
+    if (environment.platform === "win32") {
+      yield* electronApp.setAppUserModelId(environment.appUserModelId);
+    }
+
+    if (environment.platform === "linux") {
+      yield* electronApp.setDesktopName(environment.linuxDesktopEntryName);
+    }
+
+    if (environment.platform === "darwin") {
+      const iconPaths = yield* assets.iconPaths;
+      yield* Option.match(iconPaths.png, {
+        onNone: () => Effect.void,
+        onSome: electronApp.setDockIcon,
+      });
+    }
+  }).pipe(Effect.withSpan("desktop.appIdentity.configure"));
+
+  return DesktopAppIdentity.of({
+    resolveUserDataPath,
+    configure,
+  });
+});
+
+export const layer = Layer.effect(DesktopAppIdentity, make);
diff --git a/apps/desktop/src/app/DesktopAssets.ts b/apps/desktop/src/app/DesktopAssets.ts
new file mode 100644
index 00000000000..60ff477d34f
--- /dev/null
+++ b/apps/desktop/src/app/DesktopAssets.ts
@@ -0,0 +1,85 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+
+export interface DesktopIconPaths {
+  readonly ico: Option.Option<string>;
+  readonly icns: Option.Option<string>;
+  readonly png: Option.Option<string>;
+}
+
+export interface DesktopAssetsShape {
+  readonly iconPaths: Effect.Effect<DesktopIconPaths>;
+  readonly resolveResourcePath: (fileName: string) => Effect.Effect<Option.Option<string>>;
+}
+
+export class DesktopAssets extends Context.Service<DesktopAssets, DesktopAssetsShape>()(
+  "t3/desktop/Assets",
+) {}
+
+const resolveResourcePath = Effect.fn("desktop.assets.resolveResourcePath")(function* (
+  fileName: string,
+): Effect.fn.Return<
+  Option.Option<string>,
+  never,
+  FileSystem.FileSystem | DesktopEnvironment.DesktopEnvironment
+> {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const candidates = environment.resolveResourcePathCandidates(fileName);
+  for (const candidate of candidates) {
+    const exists = yield* fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false));
+    if (exists) {
+      return Option.some(candidate);
+    }
+  }
+  return Option.none<string>();
+});
+
+const resolveIconPath = Effect.fn("desktop.assets.resolveIconPath")(function* (
+  ext: keyof DesktopIconPaths,
+): Effect.fn.Return<
+  Option.Option<string>,
+  never,
+  FileSystem.FileSystem | DesktopEnvironment.DesktopEnvironment
+> {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  if (environment.isDevelopment && process.platform === "darwin" && ext === "png") {
+    const developmentDockIconPath = environment.developmentDockIconPath;
+    const developmentDockIconExists = yield* fileSystem
+      .exists(developmentDockIconPath)
+      .pipe(Effect.orElseSucceed(() => false));
+    if (developmentDockIconExists) {
+      return Option.some(developmentDockIconPath);
+    }
+  }
+
+  return yield* resolveResourcePath(`icon.${ext}`);
+});
+
+const make = Effect.gen(function* () {
+  const context = yield* Effect.context<
+    FileSystem.FileSystem | DesktopEnvironment.DesktopEnvironment
+  >();
+  const [ico, icns, png] = yield* Effect.all(
+    [resolveIconPath("ico"), resolveIconPath("icns"), resolveIconPath("png")] as const,
+    { concurrency: "unbounded" },
+  );
+  const iconPaths = { ico, icns, png } satisfies DesktopIconPaths;
+
+  return DesktopAssets.of({
+    iconPaths: Effect.succeed(iconPaths),
+    resolveResourcePath: Effect.fn("desktop.assets.resolveResourcePath.scoped")(
+      function* (fileName) {
+        return yield* resolveResourcePath(fileName).pipe(Effect.provide(context));
+      },
+    ),
+  });
+});
+
+export const layer = Layer.effect(DesktopAssets, make);
diff --git a/apps/desktop/src/app/DesktopConfig.ts b/apps/desktop/src/app/DesktopConfig.ts
new file mode 100644
index 00000000000..a9218314018
--- /dev/null
+++ b/apps/desktop/src/app/DesktopConfig.ts
@@ -0,0 +1,58 @@
+import * as Config from "effect/Config";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Option from "effect/Option";
+
+const trimNonEmptyOption = (value: string): Option.Option<string> => {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? Option.some(trimmed) : Option.none();
+};
+
+const trimmedString = (name: string) =>
+  Config.string(name).pipe(Config.option, Config.map(Option.flatMap(trimNonEmptyOption)));
+
+const optionalBoolean = (name: string) =>
+  Config.boolean(name).pipe(Config.option, Config.map(Option.getOrElse(() => false)));
+
+const commaSeparatedStrings = (name: string) =>
+  trimmedString(name).pipe(
+    Config.map(
+      Option.match({
+        onNone: () => [],
+        onSome: (value) =>
+          value
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0),
+      }),
+    ),
+  );
+
+const compactEnv = (env: Readonly<Record<string, string | undefined>>): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+
+export const DesktopConfig = Config.all({
+  appDataDirectory: trimmedString("APPDATA"),
+  xdgConfigHome: trimmedString("XDG_CONFIG_HOME"),
+  t3Home: trimmedString("T3CODE_HOME"),
+  devServerUrl: Config.url("VITE_DEV_SERVER_URL").pipe(Config.option),
+  devRemoteT3ServerEntryPath: trimmedString("T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH"),
+  configuredBackendPort: Config.port("T3CODE_PORT").pipe(Config.option),
+  commitHashOverride: trimmedString("T3CODE_COMMIT_HASH"),
+  desktopLanHostOverride: trimmedString("T3CODE_DESKTOP_LAN_HOST"),
+  desktopHttpsEndpointUrls: commaSeparatedStrings("T3CODE_DESKTOP_HTTPS_ENDPOINTS"),
+  otlpTracesUrl: trimmedString("T3CODE_OTLP_TRACES_URL"),
+  otlpExportIntervalMs: Config.int("T3CODE_OTLP_EXPORT_INTERVAL_MS").pipe(
+    Config.withDefault(10_000),
+  ),
+  appImagePath: trimmedString("APPIMAGE"),
+  disableAutoUpdate: optionalBoolean("T3CODE_DISABLE_AUTO_UPDATE"),
+  mockUpdates: optionalBoolean("T3CODE_DESKTOP_MOCK_UPDATES"),
+  mockUpdateServerPort: Config.port("T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT").pipe(
+    Config.withDefault(3000),
+  ),
+});
+
+export const layerTest = (env: Readonly<Record<string, string | undefined>>) =>
+  ConfigProvider.layer(ConfigProvider.fromEnv({ env: compactEnv(env) }));
diff --git a/apps/desktop/src/app/DesktopEnvironment.test.ts b/apps/desktop/src/app/DesktopEnvironment.test.ts
new file mode 100644
index 00000000000..427b8848833
--- /dev/null
+++ b/apps/desktop/src/app/DesktopEnvironment.test.ts
@@ -0,0 +1,117 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+import * as DesktopConfig from "./DesktopConfig.ts";
+
+const defaultInput = {
+  dirname: "/repo/apps/desktop/dist-electron",
+  homeDirectory: "/Users/alice",
+  platform: "darwin",
+  processArch: "arm64",
+  appVersion: "0.0.22",
+  appPath: "/Applications/T3 Code.app/Contents/Resources/app.asar",
+  isPackaged: false,
+  resourcesPath: "/Applications/T3 Code.app/Contents/Resources",
+  runningUnderArm64Translation: false,
+} satisfies DesktopEnvironment.MakeDesktopEnvironmentInput;
+
+const makeEnvironmentLayer = (
+  overrides: Partial<DesktopEnvironment.MakeDesktopEnvironmentInput> = {},
+  env: Record<string, string | undefined> = {},
+) =>
+  DesktopEnvironment.layer({
+    ...defaultInput,
+    ...overrides,
+  }).pipe(Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest(env))));
+
+const makeEnvironment = (
+  overrides: Partial<DesktopEnvironment.MakeDesktopEnvironmentInput> = {},
+  env: Record<string, string | undefined> = {},
+) =>
+  Effect.gen(function* () {
+    return yield* DesktopEnvironment.DesktopEnvironment;
+  }).pipe(Effect.provide(makeEnvironmentLayer(overrides, env)));
+
+describe("DesktopEnvironment", () => {
+  it.effect("derives state paths and development identity inside Effect", () =>
+    Effect.gen(function* () {
+      const environment = yield* makeEnvironment(
+        {},
+        {
+          T3CODE_HOME: " /tmp/t3 ",
+          T3CODE_COMMIT_HASH: " 0123456789abcdef ",
+          T3CODE_PORT: "4949",
+          VITE_DEV_SERVER_URL: "http://localhost:5173",
+          T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH: " /remote/server.mjs ",
+          T3CODE_OTLP_TRACES_URL: " http://127.0.0.1:4318/v1/traces ",
+          T3CODE_OTLP_EXPORT_INTERVAL_MS: "2500",
+        },
+      );
+
+      assert.equal(environment.isDevelopment, true);
+      assert.equal(environment.appDataDirectory, "/Users/alice/Library/Application Support");
+      assert.equal(environment.baseDir, "/tmp/t3");
+      assert.equal(environment.stateDir, "/tmp/t3/dev");
+      assert.equal(environment.desktopSettingsPath, "/tmp/t3/dev/desktop-settings.json");
+      assert.equal(environment.clientSettingsPath, "/tmp/t3/dev/client-settings.json");
+      assert.equal(environment.savedEnvironmentRegistryPath, "/tmp/t3/dev/saved-environments.json");
+      assert.equal(environment.serverSettingsPath, "/tmp/t3/dev/settings.json");
+      assert.equal(environment.logDir, "/tmp/t3/dev/logs");
+      assert.equal(environment.rootDir, "/repo");
+      assert.equal(environment.appRoot, "/repo");
+      assert.equal(environment.backendEntryPath, "/repo/apps/server/dist/bin.mjs");
+      assert.equal(environment.backendCwd, "/repo");
+      assert.equal(environment.appUserModelId, "com.t3tools.t3code.dev");
+      assert.equal(environment.linuxWmClass, "t3code-dev");
+      assert.deepEqual(
+        Option.map(environment.devServerUrl, (url) => url.href),
+        Option.some("http://localhost:5173/"),
+      );
+      assert.deepEqual(environment.devRemoteT3ServerEntryPath, Option.some("/remote/server.mjs"));
+      assert.deepEqual(environment.configuredBackendPort, Option.some(4949));
+      assert.deepEqual(environment.commitHashOverride, Option.some("0123456789abcdef"));
+      assert.deepEqual(environment.otlpTracesUrl, Option.some("http://127.0.0.1:4318/v1/traces"));
+      assert.equal(environment.otlpExportIntervalMs, 2500);
+    }),
+  );
+
+  it.effect("derives production state paths under userdata", () =>
+    Effect.gen(function* () {
+      const environment = yield* makeEnvironment(
+        {},
+        {
+          T3CODE_HOME: "/tmp/t3",
+        },
+      );
+
+      assert.equal(environment.isDevelopment, false);
+      assert.equal(environment.stateDir, "/tmp/t3/userdata");
+      assert.equal(environment.logDir, "/tmp/t3/userdata/logs");
+      assert.equal(environment.serverSettingsPath, "/tmp/t3/userdata/settings.json");
+    }),
+  );
+
+  it.effect("resolves picker defaults without nullish sentinels", () =>
+    Effect.gen(function* () {
+      const environment = yield* makeEnvironment();
+
+      assert.deepEqual(environment.resolvePickFolderDefaultPath(null), Option.none());
+      assert.deepEqual(
+        environment.resolvePickFolderDefaultPath({ initialPath: " " }),
+        Option.none(),
+      );
+      assert.deepEqual(
+        environment.resolvePickFolderDefaultPath({ initialPath: "~" }),
+        Option.some("/Users/alice"),
+      );
+      assert.deepEqual(
+        environment.resolvePickFolderDefaultPath({ initialPath: "~/project" }),
+        Option.some("/Users/alice/project"),
+      );
+    }),
+  );
+});
diff --git a/apps/desktop/src/app/DesktopEnvironment.ts b/apps/desktop/src/app/DesktopEnvironment.ts
new file mode 100644
index 00000000000..a5212f25358
--- /dev/null
+++ b/apps/desktop/src/app/DesktopEnvironment.ts
@@ -0,0 +1,249 @@
+import type {
+  DesktopAppBranding,
+  DesktopAppStageLabel,
+  DesktopRuntimeArch,
+  DesktopRuntimeInfo,
+} from "@t3tools/contracts";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+
+import {
+  type DesktopSettings,
+  resolveDefaultDesktopSettings,
+} from "../settings/DesktopAppSettings.ts";
+import * as DesktopConfig from "./DesktopConfig.ts";
+import { isNightlyDesktopVersion } from "../updates/updateChannels.ts";
+
+export interface MakeDesktopEnvironmentInput {
+  readonly dirname: string;
+  readonly homeDirectory: string;
+  readonly platform: NodeJS.Platform;
+  readonly processArch: string;
+  readonly appVersion: string;
+  readonly appPath: string;
+  readonly isPackaged: boolean;
+  readonly resourcesPath: string;
+  readonly runningUnderArm64Translation: boolean;
+}
+
+export interface DesktopEnvironmentShape {
+  readonly path: Path.Path;
+  readonly dirname: string;
+  readonly platform: NodeJS.Platform;
+  readonly processArch: string;
+  readonly isPackaged: boolean;
+  readonly isDevelopment: boolean;
+  readonly appVersion: string;
+  readonly appPath: string;
+  readonly resourcesPath: string;
+  readonly homeDirectory: string;
+  readonly appDataDirectory: string;
+  readonly baseDir: string;
+  readonly stateDir: string;
+  readonly desktopSettingsPath: string;
+  readonly clientSettingsPath: string;
+  readonly savedEnvironmentRegistryPath: string;
+  readonly serverSettingsPath: string;
+  readonly logDir: string;
+  readonly rootDir: string;
+  readonly appRoot: string;
+  readonly backendEntryPath: string;
+  readonly backendCwd: string;
+  readonly preloadPath: string;
+  readonly appUpdateYmlPath: string;
+  readonly devServerUrl: Option.Option<URL>;
+  readonly devRemoteT3ServerEntryPath: Option.Option<string>;
+  readonly configuredBackendPort: Option.Option<number>;
+  readonly commitHashOverride: Option.Option<string>;
+  readonly otlpTracesUrl: Option.Option<string>;
+  readonly otlpExportIntervalMs: number;
+  readonly branding: DesktopAppBranding;
+  readonly displayName: string;
+  readonly appUserModelId: string;
+  readonly linuxDesktopEntryName: string;
+  readonly linuxWmClass: string;
+  readonly userDataDirName: string;
+  readonly legacyUserDataDirName: string;
+  readonly defaultDesktopSettings: DesktopSettings;
+  readonly runtimeInfo: DesktopRuntimeInfo;
+  readonly resolvePickFolderDefaultPath: (rawOptions: unknown) => Option.Option<string>;
+  readonly resolveResourcePathCandidates: (fileName: string) => readonly string[];
+  readonly developmentDockIconPath: string;
+}
+
+export class DesktopEnvironment extends Context.Service<
+  DesktopEnvironment,
+  DesktopEnvironmentShape
+>()("t3/desktop/Environment") {}
+
+const APP_BASE_NAME = "T3 Code";
+
+function resolveDesktopAppStageLabel(input: {
+  readonly isDevelopment: boolean;
+  readonly appVersion: string;
+}): DesktopAppStageLabel {
+  if (input.isDevelopment) {
+    return "Dev";
+  }
+
+  return isNightlyDesktopVersion(input.appVersion) ? "Nightly" : "Alpha";
+}
+
+function resolveDesktopAppBranding(input: {
+  readonly isDevelopment: boolean;
+  readonly appVersion: string;
+}): DesktopAppBranding {
+  const stageLabel = resolveDesktopAppStageLabel(input);
+  return {
+    baseName: APP_BASE_NAME,
+    stageLabel,
+    displayName: `${APP_BASE_NAME} (${stageLabel})`,
+  };
+}
+
+function normalizeDesktopArch(arch: string): DesktopRuntimeArch {
+  if (arch === "arm64") return "arm64";
+  if (arch === "x64") return "x64";
+  return "other";
+}
+
+function resolveDesktopRuntimeInfo(input: {
+  readonly platform: NodeJS.Platform;
+  readonly processArch: string;
+  readonly runningUnderArm64Translation: boolean;
+}): DesktopRuntimeInfo {
+  const appArch = normalizeDesktopArch(input.processArch);
+
+  if (input.platform !== "darwin") {
+    return {
+      hostArch: appArch,
+      appArch,
+      runningUnderArm64Translation: false,
+    };
+  }
+
+  const hostArch = appArch === "arm64" || input.runningUnderArm64Translation ? "arm64" : appArch;
+
+  return {
+    hostArch,
+    appArch,
+    runningUnderArm64Translation: input.runningUnderArm64Translation,
+  };
+}
+
+const makeDesktopEnvironment = Effect.fn("desktop.environment.make")(function* (
+  input: MakeDesktopEnvironmentInput,
+): Effect.fn.Return<DesktopEnvironmentShape, Config.ConfigError, Path.Path> {
+  const path = yield* Path.Path;
+  const config = yield* DesktopConfig.DesktopConfig;
+  const homeDirectory = input.homeDirectory;
+  const devServerUrl = config.devServerUrl;
+  const isDevelopment = Option.isSome(devServerUrl);
+  const appDataDirectory =
+    input.platform === "win32"
+      ? Option.getOrElse(config.appDataDirectory, () =>
+          path.join(homeDirectory, "AppData", "Roaming"),
+        )
+      : input.platform === "darwin"
+        ? path.join(homeDirectory, "Library", "Application Support")
+        : Option.getOrElse(config.xdgConfigHome, () => path.join(homeDirectory, ".config"));
+  const baseDir = Option.getOrElse(config.t3Home, () => path.join(homeDirectory, ".t3"));
+  const rootDir = path.resolve(input.dirname, "../../..");
+  const appRoot = input.isPackaged ? input.appPath : rootDir;
+  const branding = resolveDesktopAppBranding({
+    isDevelopment,
+    appVersion: input.appVersion,
+  });
+  const displayName = branding.displayName;
+  const stateDir = path.join(baseDir, isDevelopment ? "dev" : "userdata");
+  const userDataDirName = isDevelopment ? "t3code-dev" : "t3code";
+  const legacyUserDataDirName = isDevelopment ? "T3 Code (Dev)" : "T3 Code (Alpha)";
+  const resourcesPath = input.resourcesPath;
+
+  return DesktopEnvironment.of({
+    path,
+    dirname: input.dirname,
+    platform: input.platform,
+    processArch: input.processArch,
+    isPackaged: input.isPackaged,
+    isDevelopment,
+    appVersion: input.appVersion,
+    appPath: input.appPath,
+    resourcesPath,
+    homeDirectory,
+    appDataDirectory,
+    baseDir,
+    stateDir,
+    desktopSettingsPath: path.join(stateDir, "desktop-settings.json"),
+    clientSettingsPath: path.join(stateDir, "client-settings.json"),
+    savedEnvironmentRegistryPath: path.join(stateDir, "saved-environments.json"),
+    serverSettingsPath: path.join(stateDir, "settings.json"),
+    logDir: path.join(stateDir, "logs"),
+    rootDir,
+    appRoot,
+    backendEntryPath: path.join(appRoot, "apps/server/dist/bin.mjs"),
+    backendCwd: input.isPackaged ? homeDirectory : appRoot,
+    preloadPath: path.join(input.dirname, "preload.cjs"),
+    appUpdateYmlPath: input.isPackaged
+      ? path.join(resourcesPath, "app-update.yml")
+      : path.join(input.appPath, "dev-app-update.yml"),
+    devServerUrl,
+    devRemoteT3ServerEntryPath: config.devRemoteT3ServerEntryPath,
+    configuredBackendPort: config.configuredBackendPort,
+    commitHashOverride: config.commitHashOverride,
+    otlpTracesUrl: config.otlpTracesUrl,
+    otlpExportIntervalMs: config.otlpExportIntervalMs,
+    branding,
+    displayName,
+    appUserModelId: isDevelopment ? "com.t3tools.t3code.dev" : "com.t3tools.t3code",
+    linuxDesktopEntryName: isDevelopment ? "t3code-dev.desktop" : "t3code.desktop",
+    linuxWmClass: isDevelopment ? "t3code-dev" : "t3code",
+    userDataDirName,
+    legacyUserDataDirName,
+    defaultDesktopSettings: resolveDefaultDesktopSettings(input.appVersion),
+    runtimeInfo: resolveDesktopRuntimeInfo({
+      platform: input.platform,
+      processArch: input.processArch,
+      runningUnderArm64Translation: input.runningUnderArm64Translation,
+    }),
+    resolvePickFolderDefaultPath: (rawOptions) => {
+      if (typeof rawOptions !== "object" || rawOptions === null) {
+        return Option.none();
+      }
+
+      const { initialPath } = rawOptions as { initialPath?: unknown };
+      if (typeof initialPath !== "string") {
+        return Option.none();
+      }
+
+      const trimmedPath = initialPath.trim();
+      if (trimmedPath.length === 0) {
+        return Option.none();
+      }
+
+      if (trimmedPath === "~") {
+        return Option.some(homeDirectory);
+      }
+
+      if (trimmedPath.startsWith("~/") || trimmedPath.startsWith("~\\")) {
+        return Option.some(path.join(homeDirectory, trimmedPath.slice(2)));
+      }
+
+      return Option.some(path.resolve(trimmedPath));
+    },
+    resolveResourcePathCandidates: (fileName) => [
+      path.join(input.dirname, "../resources", fileName),
+      path.join(input.dirname, "../prod-resources", fileName),
+      path.join(resourcesPath, "resources", fileName),
+      path.join(resourcesPath, fileName),
+    ],
+    developmentDockIconPath: path.join(rootDir, "assets", "dev", "blueprint-macos-1024.png"),
+  });
+});
+
+export const layer = (input: MakeDesktopEnvironmentInput) =>
+  Layer.effect(DesktopEnvironment, makeDesktopEnvironment(input));
diff --git a/apps/desktop/src/app/DesktopLifecycle.ts b/apps/desktop/src/app/DesktopLifecycle.ts
new file mode 100644
index 00000000000..b9a7636a411
--- /dev/null
+++ b/apps/desktop/src/app/DesktopLifecycle.ts
@@ -0,0 +1,233 @@
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+
+import type * as Electron from "electron";
+
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+import * as DesktopObservability from "./DesktopObservability.ts";
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronTheme from "../electron/ElectronTheme.ts";
+import * as DesktopState from "./DesktopState.ts";
+import * as DesktopWindow from "../window/DesktopWindow.ts";
+
+export interface DesktopShutdownShape {
+  readonly request: Effect.Effect<void>;
+  readonly awaitRequest: Effect.Effect<void>;
+  readonly markComplete: Effect.Effect<void>;
+  readonly awaitComplete: Effect.Effect<void>;
+  readonly isComplete: Effect.Effect<boolean>;
+}
+
+export class DesktopShutdown extends Context.Service<DesktopShutdown, DesktopShutdownShape>()(
+  "t3/desktop/Shutdown",
+) {}
+
+const makeShutdown = Effect.gen(function* () {
+  const requested = yield* Deferred.make<void>();
+  const completed = yield* Deferred.make<void>();
+  const completedRef = yield* Ref.make(false);
+
+  return DesktopShutdown.of({
+    request: Deferred.succeed(requested, undefined).pipe(Effect.asVoid),
+    awaitRequest: Deferred.await(requested),
+    markComplete: Ref.set(completedRef, true).pipe(
+      Effect.andThen(Deferred.succeed(completed, undefined)),
+      Effect.asVoid,
+    ),
+    awaitComplete: Deferred.await(completed),
+    isComplete: Ref.get(completedRef),
+  });
+});
+
+export const layerShutdown = Layer.effect(DesktopShutdown, makeShutdown);
+
+export type DesktopLifecycleRuntimeServices =
+  | DesktopEnvironment.DesktopEnvironment
+  | DesktopShutdown
+  | DesktopState.DesktopState
+  | DesktopWindow.DesktopWindow
+  | ElectronApp.ElectronApp
+  | ElectronTheme.ElectronTheme;
+
+export interface DesktopLifecycleShape {
+  readonly relaunch: (
+    reason: string,
+  ) => Effect.Effect<void, never, DesktopLifecycleRuntimeServices>;
+  readonly register: Effect.Effect<void, never, Scope.Scope | DesktopLifecycleRuntimeServices>;
+}
+
+export class DesktopLifecycle extends Context.Service<DesktopLifecycle, DesktopLifecycleShape>()(
+  "t3/desktop/Lifecycle",
+) {}
+
+const { logInfo: logLifecycleInfo, logError: logLifecycleError } =
+  DesktopObservability.makeComponentLogger("desktop-lifecycle");
+
+function addScopedListener<Args extends ReadonlyArray<unknown>>(
+  target: unknown,
+  eventName: string,
+  listener: (...args: Args) => void,
+): Effect.Effect<void, never, Scope.Scope> {
+  const eventTarget = target as {
+    on: (eventName: string, listener: (...args: Array<unknown>) => void) => unknown;
+    removeListener: (eventName: string, listener: (...args: Array<unknown>) => void) => unknown;
+  };
+  const untypedListener = listener as unknown as (...args: Array<unknown>) => void;
+  return Effect.acquireRelease(
+    Effect.sync(() => {
+      eventTarget.on(eventName, untypedListener);
+    }),
+    () =>
+      Effect.sync(() => {
+        eventTarget.removeListener(eventName, untypedListener);
+      }),
+  ).pipe(Effect.asVoid);
+}
+
+const requestDesktopShutdownAndWait = Effect.fn("desktop.lifecycle.requestShutdownAndWait")(
+  function* (): Effect.fn.Return<void, never, DesktopShutdown> {
+    const shutdown = yield* DesktopShutdown;
+    yield* shutdown.request;
+    yield* shutdown.awaitComplete;
+  },
+);
+
+function handleBeforeQuit(
+  event: Electron.Event,
+  runEffect: <A, E>(effect: Effect.Effect<A, E, DesktopLifecycleRuntimeServices>) => Promise<A>,
+  allowQuit: () => boolean,
+  markQuitAllowed: () => void,
+): void {
+  if (allowQuit()) {
+    void runEffect(
+      Effect.gen(function* () {
+        const state = yield* DesktopState.DesktopState;
+        yield* Ref.set(state.quitting, true);
+        yield* logLifecycleInfo("before-quit received");
+      }).pipe(Effect.withSpan("desktop.lifecycle.beforeQuit")),
+    );
+    return;
+  }
+
+  event.preventDefault();
+  void runEffect(
+    Effect.gen(function* () {
+      const state = yield* DesktopState.DesktopState;
+      yield* Ref.set(state.quitting, true);
+      yield* logLifecycleInfo("before-quit received");
+      yield* requestDesktopShutdownAndWait();
+    }).pipe(Effect.withSpan("desktop.lifecycle.beforeQuit")),
+  ).finally(() => {
+    markQuitAllowed();
+    void runEffect(
+      Effect.gen(function* () {
+        const electronApp = yield* ElectronApp.ElectronApp;
+        yield* electronApp.quit;
+      }).pipe(Effect.withSpan("desktop.lifecycle.quitAfterShutdown")),
+    );
+  });
+}
+
+function quitFromSignal(
+  signal: "SIGINT" | "SIGTERM",
+  runEffect: <A, E>(effect: Effect.Effect<A, E, DesktopLifecycleRuntimeServices>) => Promise<A>,
+): void {
+  void runEffect(
+    Effect.gen(function* () {
+      yield* Effect.annotateCurrentSpan({ signal });
+      const electronApp = yield* ElectronApp.ElectronApp;
+      const state = yield* DesktopState.DesktopState;
+      const wasQuitting = yield* Ref.getAndSet(state.quitting, true);
+      if (wasQuitting) return;
+      yield* logLifecycleInfo("process signal received", { signal });
+      yield* requestDesktopShutdownAndWait();
+      yield* electronApp.quit;
+    }).pipe(Effect.withSpan("desktop.lifecycle.processSignal")),
+  );
+}
+
+export const layer = Layer.succeed(
+  DesktopLifecycle,
+  DesktopLifecycle.of({
+    relaunch: Effect.fn("desktop.lifecycle.relaunch")(function* (reason) {
+      const electronApp = yield* ElectronApp.ElectronApp;
+      const environment = yield* DesktopEnvironment.DesktopEnvironment;
+      const state = yield* DesktopState.DesktopState;
+      yield* logLifecycleInfo("desktop relaunch requested", { reason });
+      yield* Effect.gen(function* () {
+        yield* Effect.yieldNow;
+        yield* Ref.set(state.quitting, true);
+        yield* requestDesktopShutdownAndWait();
+        if (environment.isDevelopment) {
+          yield* electronApp.exit(75);
+          return;
+        }
+        yield* electronApp.relaunch({
+          execPath: process.execPath,
+          args: process.argv.slice(1),
+        });
+        yield* electronApp.exit(0);
+      }).pipe(
+        Effect.catchCause((cause) =>
+          logLifecycleError("desktop relaunch failed", {
+            cause: Cause.pretty(cause),
+          }),
+        ),
+        Effect.forkDetach,
+        Effect.asVoid,
+      );
+    }),
+    register: Effect.gen(function* () {
+      const desktopWindow = yield* DesktopWindow.DesktopWindow;
+      const electronApp = yield* ElectronApp.ElectronApp;
+      const electronTheme = yield* ElectronTheme.ElectronTheme;
+      const environment = yield* DesktopEnvironment.DesktopEnvironment;
+      const context = yield* Effect.context<DesktopLifecycleRuntimeServices>();
+      const runEffect = Effect.runPromiseWith(context);
+      let quitAllowed = false;
+      yield* electronTheme.onUpdated(() => {
+        void runEffect(
+          desktopWindow.syncAppearance.pipe(Effect.withSpan("desktop.lifecycle.themeUpdated")),
+        );
+      });
+      yield* electronApp.on("before-quit", (event: Electron.Event) => {
+        handleBeforeQuit(
+          event,
+          runEffect,
+          () => quitAllowed,
+          () => {
+            quitAllowed = true;
+          },
+        );
+      });
+      yield* electronApp.on("activate", () => {
+        void runEffect(desktopWindow.activate.pipe(Effect.withSpan("desktop.lifecycle.activate")));
+      });
+      yield* electronApp.on("window-all-closed", () => {
+        void runEffect(
+          Effect.gen(function* () {
+            const app = yield* ElectronApp.ElectronApp;
+            const state = yield* DesktopState.DesktopState;
+            if (environment.platform !== "darwin" && !(yield* Ref.get(state.quitting))) {
+              yield* app.quit;
+            }
+          }).pipe(Effect.withSpan("desktop.lifecycle.windowAllClosed")),
+        );
+      });
+
+      if (environment.platform !== "win32") {
+        yield* addScopedListener(process, "SIGINT", () => {
+          quitFromSignal("SIGINT", runEffect);
+        });
+        yield* addScopedListener(process, "SIGTERM", () => {
+          quitFromSignal("SIGTERM", runEffect);
+        });
+      }
+    }).pipe(Effect.withSpan("desktop.lifecycle.register")),
+  }),
+);
diff --git a/apps/desktop/src/app/DesktopObservability.test.ts b/apps/desktop/src/app/DesktopObservability.test.ts
new file mode 100644
index 00000000000..a78de48d5e1
--- /dev/null
+++ b/apps/desktop/src/app/DesktopObservability.test.ts
@@ -0,0 +1,162 @@
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+
+import * as DesktopConfig from "./DesktopConfig.ts";
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+import * as DesktopObservability from "./DesktopObservability.ts";
+
+const DesktopBackendChildLogRecord = Schema.Struct({
+  message: Schema.String,
+  level: Schema.Literals(["INFO", "ERROR"]),
+  timestamp: Schema.String,
+  annotations: Schema.Record(Schema.String, Schema.Unknown),
+  spans: Schema.Record(Schema.String, Schema.Unknown),
+  fiberId: Schema.String,
+});
+
+const decodeDesktopBackendChildLogRecord = Schema.decodeEffect(
+  Schema.fromJsonString(DesktopBackendChildLogRecord),
+);
+
+const TraceRecordLine = Schema.Struct({
+  name: Schema.String,
+  attributes: Schema.Record(Schema.String, Schema.Unknown),
+  events: Schema.Array(
+    Schema.Struct({
+      name: Schema.String,
+      attributes: Schema.Record(Schema.String, Schema.Unknown),
+    }),
+  ),
+});
+
+const decodeTraceRecordLine = Schema.decodeUnknownSync(Schema.fromJsonString(TraceRecordLine));
+
+const environmentInput = (baseDir: string) =>
+  ({
+    dirname: "/repo/apps/desktop/dist-electron",
+    homeDirectory: baseDir,
+    platform: "darwin",
+    processArch: "arm64",
+    appVersion: "1.2.3",
+    appPath: "/repo",
+    isPackaged: false,
+    resourcesPath: "/repo/resources",
+    runningUnderArm64Translation: false,
+  }) satisfies DesktopEnvironment.MakeDesktopEnvironmentInput;
+
+const makeEnvironmentLayer = (baseDir: string) =>
+  DesktopEnvironment.layer(environmentInput(baseDir)).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        DesktopConfig.layerTest({
+          T3CODE_HOME: baseDir,
+          VITE_DEV_SERVER_URL: "http://127.0.0.1:5733",
+        }),
+      ),
+    ),
+  );
+
+describe("DesktopObservability", () => {
+  it.effect("persists desktop Effect logs as span events in desktop.trace.ndjson", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-desktop-observability-test-",
+      });
+      const environmentLayer = makeEnvironmentLayer(baseDir);
+      const tracePath = yield* Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        return environment.path.join(environment.logDir, "desktop.trace.ndjson");
+      }).pipe(Effect.provide(environmentLayer));
+      const logPath = yield* Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        return environment.path.join(environment.logDir, "desktop-main.log");
+      }).pipe(Effect.provide(environmentLayer));
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          yield* Effect.annotateCurrentSpan({ "desktop.test": true });
+          yield* Effect.logInfo("desktop trace event");
+        }).pipe(
+          Effect.withSpan("desktop-observability-test"),
+          Effect.provide(DesktopObservability.layer.pipe(Layer.provideMerge(environmentLayer))),
+        ),
+      );
+
+      const records = (yield* fileSystem.readFileString(tracePath))
+        .trim()
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => decodeTraceRecordLine(line));
+      const record = records.find((entry) => entry.name === "desktop-observability-test");
+
+      assert.notEqual(record, undefined);
+      if (!record) {
+        return;
+      }
+      assert.equal(record.attributes["desktop.test"], true);
+      assert.equal(
+        record.events.some((event) => event.name === "desktop trace event"),
+        true,
+      );
+      assert.isFalse(yield* fileSystem.exists(logPath));
+    }).pipe(
+      Effect.scoped,
+      Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici)),
+    ),
+  );
+
+  it.effect("persists backend child output as structured JSON records in development", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-desktop-backend-output-log-test-",
+      });
+      const environmentLayer = makeEnvironmentLayer(baseDir);
+      const logPath = yield* Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        return environment.path.join(environment.logDir, "server-child.log");
+      }).pipe(Effect.provide(environmentLayer));
+
+      yield* Effect.gen(function* () {
+        const outputLog = yield* DesktopObservability.DesktopBackendOutputLog;
+        yield* outputLog.writeSessionBoundary({
+          phase: "START",
+          details: "pid=123 port=3773 cwd=/repo",
+        });
+        yield* outputLog.writeOutputChunk("stdout", new TextEncoder().encode("hello server\n"));
+      }).pipe(
+        Effect.annotateLogs({ runId: "test-run" }),
+        Effect.provide(DesktopObservability.layer.pipe(Layer.provideMerge(environmentLayer))),
+      );
+
+      const log = yield* fileSystem.readFileString(logPath);
+      const lines = log.trimEnd().split("\n");
+      const boundary = yield* decodeDesktopBackendChildLogRecord(lines[0] ?? "");
+      const output = yield* decodeDesktopBackendChildLogRecord(lines[1] ?? "");
+
+      assert.equal(boundary.message, "backend child process session start");
+      assert.equal(boundary.level, "INFO");
+      assert.equal(boundary.annotations.component, "desktop-backend-child");
+      assert.equal(boundary.annotations.runId, "test-run");
+      assert.equal(boundary.annotations.phase, "START");
+      assert.equal(boundary.annotations.details, "pid=123 port=3773 cwd=/repo");
+
+      assert.equal(output.message, "backend child process output");
+      assert.equal(output.level, "INFO");
+      assert.equal(output.annotations.component, "desktop-backend-child");
+      assert.equal(output.annotations.runId, "test-run");
+      assert.equal(output.annotations.stream, "stdout");
+      assert.equal(output.annotations.text, "hello server\n");
+    }).pipe(
+      Effect.scoped,
+      Effect.provide(Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici)),
+    ),
+  );
+});
diff --git a/apps/desktop/src/app/DesktopObservability.ts b/apps/desktop/src/app/DesktopObservability.ts
new file mode 100644
index 00000000000..4eeb76bd62a
--- /dev/null
+++ b/apps/desktop/src/app/DesktopObservability.ts
@@ -0,0 +1,395 @@
+import { makeLocalFileTracer, makeTraceSink } from "@t3tools/shared/observability";
+import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as References from "effect/References";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Tracer from "effect/Tracer";
+import { OtlpSerialization, OtlpTracer } from "effect/unstable/observability";
+
+import * as DesktopEnvironment from "./DesktopEnvironment.ts";
+
+const DESKTOP_LOG_FILE_MAX_BYTES = 10 * 1024 * 1024;
+const DESKTOP_LOG_FILE_MAX_FILES = 10;
+const DESKTOP_BACKEND_CHILD_LOG_FIBER_ID = "#backend-child";
+const DESKTOP_TRACE_BATCH_WINDOW_MS = 200;
+
+export interface RotatingLogFileWriter {
+  readonly writeBytes: (chunk: Uint8Array) => Effect.Effect<void>;
+  readonly writeText: (chunk: string) => Effect.Effect<void>;
+}
+
+export interface DesktopBackendOutputLogShape {
+  readonly writeSessionBoundary: (input: {
+    readonly phase: "START" | "END";
+    readonly details: string;
+  }) => Effect.Effect<void>;
+  readonly writeOutputChunk: (
+    streamName: "stdout" | "stderr",
+    chunk: Uint8Array,
+  ) => Effect.Effect<void>;
+}
+
+export class DesktopBackendOutputLog extends Context.Service<
+  DesktopBackendOutputLog,
+  DesktopBackendOutputLogShape
+>()("t3/desktop/BackendOutputLog") {}
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export type DesktopLogAnnotations = Record<string, unknown>;
+
+export interface DesktopComponentLogger {
+  readonly annotate: <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+    annotations?: DesktopLogAnnotations,
+  ) => Effect.Effect<A, E, R>;
+  readonly logDebug: (message: string, annotations?: DesktopLogAnnotations) => Effect.Effect<void>;
+  readonly logInfo: (message: string, annotations?: DesktopLogAnnotations) => Effect.Effect<void>;
+  readonly logWarning: (
+    message: string,
+    annotations?: DesktopLogAnnotations,
+  ) => Effect.Effect<void>;
+  readonly logError: (message: string, annotations?: DesktopLogAnnotations) => Effect.Effect<void>;
+}
+
+export function makeComponentLogger(component: string): DesktopComponentLogger {
+  const annotate: DesktopComponentLogger["annotate"] = (effect, annotations) =>
+    effect.pipe(
+      Effect.annotateLogs({
+        component,
+        ...annotations,
+      }),
+    );
+
+  return {
+    annotate,
+    logDebug: (message, annotations) => annotate(Effect.logDebug(message), annotations),
+    logInfo: (message, annotations) => annotate(Effect.logInfo(message), annotations),
+    logWarning: (message, annotations) => annotate(Effect.logWarning(message), annotations),
+    logError: (message, annotations) => annotate(Effect.logError(message), annotations),
+  };
+}
+
+class DesktopLogFileWriterConfigurationError extends Data.TaggedError(
+  "DesktopLogFileWriterConfigurationError",
+)<{
+  readonly option: "maxBytes" | "maxFiles";
+  readonly value: number;
+}> {
+  override get message() {
+    return `${this.option} must be >= 1 (received ${this.value})`;
+  }
+}
+
+type DesktopLogFileWriterError =
+  | DesktopLogFileWriterConfigurationError
+  | PlatformError.PlatformError;
+
+const sanitizeLogValue = (value: string): string => value.replace(/\s+/g, " ").trim();
+
+const DesktopBackendChildLogRecord = Schema.Struct({
+  message: Schema.String,
+  level: Schema.Literals(["INFO", "ERROR"]),
+  timestamp: Schema.String,
+  annotations: Schema.Record(Schema.String, Schema.Unknown),
+  spans: Schema.Record(Schema.String, Schema.Unknown),
+  fiberId: Schema.String,
+});
+
+const encodeDesktopBackendChildLogRecord = Schema.encodeEffect(
+  Schema.fromJsonString(DesktopBackendChildLogRecord),
+);
+
+const DesktopBackendOutputLogNoop: DesktopBackendOutputLogShape = {
+  writeSessionBoundary: () => Effect.void,
+  writeOutputChunk: () => Effect.void,
+};
+
+const currentDesktopRunId = Effect.gen(function* () {
+  const annotations = yield* References.CurrentLogAnnotations;
+  const runId = annotations.runId;
+  return typeof runId === "string" && runId.length > 0 ? runId : "unknown";
+});
+
+const refreshFileSize = (
+  fileSystem: FileSystem.FileSystem,
+  filePath: string,
+): Effect.Effect<number, never> =>
+  fileSystem.stat(filePath).pipe(
+    Effect.map((stat) => Number(stat.size)),
+    Effect.orElseSucceed(() => 0),
+  );
+
+const makeRotatingLogFileWriter = Effect.fn("makeRotatingLogFileWriter")(function* (input: {
+  readonly filePath: string;
+  readonly maxBytes?: number;
+  readonly maxFiles?: number;
+}): Effect.fn.Return<
+  RotatingLogFileWriter,
+  DesktopLogFileWriterError,
+  FileSystem.FileSystem | Path.Path
+> {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const maxBytes = input.maxBytes ?? DESKTOP_LOG_FILE_MAX_BYTES;
+  const maxFiles = input.maxFiles ?? DESKTOP_LOG_FILE_MAX_FILES;
+  const directory = path.dirname(input.filePath);
+  const baseName = path.basename(input.filePath);
+
+  if (maxBytes < 1) {
+    return yield* new DesktopLogFileWriterConfigurationError({
+      option: "maxBytes",
+      value: maxBytes,
+    });
+  }
+  if (maxFiles < 1) {
+    return yield* new DesktopLogFileWriterConfigurationError({
+      option: "maxFiles",
+      value: maxFiles,
+    });
+  }
+
+  yield* fileSystem.makeDirectory(directory, { recursive: true });
+
+  const withSuffix = (index: number) => `${input.filePath}.${index}`;
+  const currentSize = yield* Ref.make(yield* refreshFileSize(fileSystem, input.filePath));
+  const mutex = yield* Semaphore.make(1);
+
+  const pruneOverflowBackups = Effect.gen(function* () {
+    const entries = yield* fileSystem.readDirectory(directory).pipe(Effect.orElseSucceed(() => []));
+    for (const entry of entries) {
+      if (!entry.startsWith(`${baseName}.`)) continue;
+      const suffix = Number(entry.slice(baseName.length + 1));
+      if (!Number.isInteger(suffix) || suffix <= maxFiles) continue;
+      yield* fileSystem.remove(path.join(directory, entry), { force: true }).pipe(Effect.ignore);
+    }
+  });
+
+  const rotate = Effect.gen(function* () {
+    yield* fileSystem.remove(withSuffix(maxFiles), { force: true }).pipe(Effect.ignore);
+    for (let index = maxFiles - 1; index >= 1; index -= 1) {
+      const source = withSuffix(index);
+      const sourceExists = yield* fileSystem.exists(source).pipe(Effect.orElseSucceed(() => false));
+      if (sourceExists) {
+        yield* fileSystem.rename(source, withSuffix(index + 1));
+      }
+    }
+    const currentExists = yield* fileSystem
+      .exists(input.filePath)
+      .pipe(Effect.orElseSucceed(() => false));
+    if (currentExists) {
+      yield* fileSystem.rename(input.filePath, withSuffix(1));
+    }
+    yield* Ref.set(currentSize, 0);
+  }).pipe(
+    Effect.catch(() =>
+      refreshFileSize(fileSystem, input.filePath).pipe(
+        Effect.flatMap((size) => Ref.set(currentSize, size)),
+      ),
+    ),
+  );
+
+  const writeBytes = (chunk: Uint8Array): Effect.Effect<void> => {
+    if (chunk.byteLength === 0) return Effect.void;
+
+    return mutex.withPermits(1)(
+      Effect.gen(function* () {
+        const beforeSize = yield* Ref.get(currentSize);
+        if (beforeSize > 0 && beforeSize + chunk.byteLength > maxBytes) {
+          yield* rotate;
+        }
+
+        yield* fileSystem.writeFile(input.filePath, chunk, { flag: "a" });
+        const afterSize = (yield* Ref.get(currentSize)) + chunk.byteLength;
+        yield* Ref.set(currentSize, afterSize);
+
+        if (afterSize > maxBytes) {
+          yield* rotate;
+        }
+      }).pipe(
+        Effect.catch(() =>
+          refreshFileSize(fileSystem, input.filePath).pipe(
+            Effect.flatMap((size) => Ref.set(currentSize, size)),
+          ),
+        ),
+      ),
+    );
+  };
+
+  yield* pruneOverflowBackups;
+
+  return {
+    writeBytes,
+    writeText: (chunk) => writeBytes(textEncoder.encode(chunk)),
+  } satisfies RotatingLogFileWriter;
+});
+
+const readPersistedOtlpTracesUrl: Effect.Effect<
+  Option.Option<string>,
+  never,
+  FileSystem.FileSystem | DesktopEnvironment.DesktopEnvironment
+> = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const raw = yield* fileSystem.readFileString(environment.serverSettingsPath).pipe(Effect.option);
+  if (Option.isNone(raw)) {
+    return Option.none();
+  }
+
+  const parsed = parsePersistedServerObservabilitySettings(raw.value);
+  return Option.fromNullishOr(parsed.otlpTracesUrl);
+});
+
+const resolveOtlpTracesUrl = Effect.gen(function* () {
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  if (Option.isSome(environment.otlpTracesUrl)) {
+    return environment.otlpTracesUrl;
+  }
+  return yield* readPersistedOtlpTracesUrl;
+});
+
+const writeDevelopmentConsoleOutput = (
+  streamName: "stdout" | "stderr",
+  chunk: Uint8Array,
+): Effect.Effect<void> =>
+  Effect.sync(() => {
+    const output = streamName === "stderr" ? process.stderr : process.stdout;
+    output.write(chunk);
+  }).pipe(Effect.ignore);
+
+const writeBackendChildLogRecord = Effect.fn("desktop.observability.writeBackendChildLogRecord")(
+  function* (
+    logFile: RotatingLogFileWriter,
+    input: {
+      readonly message: string;
+      readonly level: "INFO" | "ERROR";
+      readonly annotations: Record<string, unknown>;
+    },
+  ): Effect.fn.Return<void> {
+    return yield* Effect.gen(function* () {
+      const timestamp = DateTime.formatIso(yield* DateTime.now);
+      const encoded = yield* encodeDesktopBackendChildLogRecord({
+        message: input.message,
+        level: input.level,
+        timestamp,
+        annotations: input.annotations,
+        spans: {},
+        fiberId: DESKTOP_BACKEND_CHILD_LOG_FIBER_ID,
+      });
+      yield* logFile.writeText(`${encoded}\n`);
+    }).pipe(Effect.ignore({ log: true }));
+  },
+);
+
+const backendOutputLogLayer = Layer.effect(
+  DesktopBackendOutputLog,
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+
+    const writer = yield* makeRotatingLogFileWriter({
+      filePath: environment.path.join(environment.logDir, "server-child.log"),
+    }).pipe(Effect.option);
+
+    return Option.match(writer, {
+      onNone: () => DesktopBackendOutputLogNoop,
+      onSome: (logFile) =>
+        ({
+          writeSessionBoundary: Effect.fn(
+            "desktop.observability.backendOutput.writeSessionBoundary",
+          )(function* ({ phase, details }) {
+            const runId = yield* currentDesktopRunId;
+            yield* writeBackendChildLogRecord(logFile, {
+              message: `backend child process session ${phase.toLowerCase()}`,
+              level: "INFO",
+              annotations: {
+                component: "desktop-backend-child",
+                runId,
+                phase,
+                details: sanitizeLogValue(details),
+              },
+            });
+          }),
+          writeOutputChunk: Effect.fn("desktop.observability.backendOutput.writeOutputChunk")(
+            function* (streamName, chunk) {
+              if (environment.isDevelopment) {
+                yield* writeDevelopmentConsoleOutput(streamName, chunk);
+              }
+              const runId = yield* currentDesktopRunId;
+              yield* writeBackendChildLogRecord(logFile, {
+                message: "backend child process output",
+                level: streamName === "stderr" ? "ERROR" : "INFO",
+                annotations: {
+                  component: "desktop-backend-child",
+                  runId,
+                  stream: streamName,
+                  text: textDecoder.decode(chunk),
+                },
+              });
+            },
+          ),
+        }) satisfies DesktopBackendOutputLogShape,
+    });
+  }),
+);
+
+const desktopLoggerLayer = Layer.mergeAll(
+  Logger.layer([Logger.consolePretty(), Logger.tracerLogger], { mergeWithExisting: false }),
+  Layer.succeed(References.MinimumLogLevel, "Info"),
+);
+
+const tracerLayer = Layer.unwrap(
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const otlpTracesUrl = yield* resolveOtlpTracesUrl;
+    const tracePath = environment.path.join(environment.logDir, "desktop.trace.ndjson");
+    const sink = yield* makeTraceSink({
+      filePath: tracePath,
+      maxBytes: DESKTOP_LOG_FILE_MAX_BYTES,
+      maxFiles: DESKTOP_LOG_FILE_MAX_FILES,
+      batchWindowMs: DESKTOP_TRACE_BATCH_WINDOW_MS,
+    });
+    const delegate = Option.isNone(otlpTracesUrl)
+      ? undefined
+      : yield* OtlpTracer.make({
+          url: otlpTracesUrl.value,
+          exportInterval: `${environment.otlpExportIntervalMs} millis`,
+          resource: {
+            serviceName: "desktop",
+            attributes: {
+              "service.runtime": "desktop",
+              "service.mode": environment.isDevelopment ? "development" : "packaged",
+            },
+          },
+        });
+    const tracer = yield* makeLocalFileTracer({
+      filePath: tracePath,
+      maxBytes: DESKTOP_LOG_FILE_MAX_BYTES,
+      maxFiles: DESKTOP_LOG_FILE_MAX_FILES,
+      batchWindowMs: DESKTOP_TRACE_BATCH_WINDOW_MS,
+      sink,
+      ...(delegate ? { delegate } : {}),
+    });
+
+    return Layer.succeed(Tracer.Tracer, tracer);
+  }),
+).pipe(Layer.provideMerge(OtlpSerialization.layerJson));
+
+export const layer = Layer.mergeAll(
+  backendOutputLogLayer,
+  desktopLoggerLayer,
+  tracerLayer,
+  Layer.succeed(Tracer.MinimumTraceLevel, "Info"),
+  Layer.succeed(References.TracerTimingEnabled, true),
+);
diff --git a/apps/desktop/src/app/DesktopState.ts b/apps/desktop/src/app/DesktopState.ts
new file mode 100644
index 00000000000..43960ada65f
--- /dev/null
+++ b/apps/desktop/src/app/DesktopState.ts
@@ -0,0 +1,21 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+
+export interface DesktopStateShape {
+  readonly backendReady: Ref.Ref<boolean>;
+  readonly quitting: Ref.Ref<boolean>;
+}
+
+export class DesktopState extends Context.Service<DesktopState, DesktopStateShape>()(
+  "t3/desktop/State",
+) {}
+
+export const layer = Layer.effect(
+  DesktopState,
+  Effect.all({
+    backendReady: Ref.make(false),
+    quitting: Ref.make(false),
+  }),
+);
diff --git a/apps/desktop/src/backend/DesktopBackendConfiguration.test.ts b/apps/desktop/src/backend/DesktopBackendConfiguration.test.ts
new file mode 100644
index 00000000000..96e56a87c9d
--- /dev/null
+++ b/apps/desktop/src/backend/DesktopBackendConfiguration.test.ts
@@ -0,0 +1,195 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopBackendConfiguration from "./DesktopBackendConfiguration.ts";
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopServerExposure from "./DesktopServerExposure.ts";
+
+const PersistedServerObservabilitySettingsDocument = Schema.Struct({
+  observability: Schema.Struct({
+    otlpTracesUrl: Schema.String,
+    otlpMetricsUrl: Schema.String,
+  }),
+});
+
+const encodePersistedServerObservabilitySettingsDocument = Schema.encodeEffect(
+  Schema.fromJsonString(PersistedServerObservabilitySettingsDocument),
+);
+
+const serverExposureLayer = Layer.succeed(DesktopServerExposure.DesktopServerExposure, {
+  getState: Effect.die("unexpected getState"),
+  backendConfig: Effect.succeed({
+    port: 4888,
+    bindHost: "0.0.0.0",
+    httpBaseUrl: new URL("http://127.0.0.1:4888"),
+    tailscaleServeEnabled: true,
+    tailscaleServePort: 8443,
+  }),
+  configureFromSettings: () => Effect.die("unexpected configureFromSettings"),
+  setMode: () => Effect.die("unexpected setMode"),
+  setTailscaleServeEnabled: () => Effect.die("unexpected setTailscaleServeEnabled"),
+  getAdvertisedEndpoints: Effect.succeed([]),
+} satisfies DesktopServerExposure.DesktopServerExposureShape);
+
+function makeEnvironmentLayer(
+  baseDir: string,
+  options?: {
+    readonly isPackaged?: boolean;
+    readonly devServerUrl?: string;
+  },
+) {
+  return DesktopEnvironment.layer({
+    dirname: "/repo/apps/desktop/src",
+    homeDirectory: baseDir,
+    platform: "darwin",
+    processArch: "x64",
+    appVersion: "1.2.3",
+    appPath: "/repo",
+    isPackaged: options?.isPackaged ?? true,
+    resourcesPath: "/missing/resources",
+    runningUnderArm64Translation: false,
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        DesktopConfig.layerTest({
+          T3CODE_HOME: baseDir,
+          T3CODE_PORT: "9999",
+          T3CODE_MODE: "desktop",
+          T3CODE_DESKTOP_LAN_HOST: "192.168.1.50",
+          VITE_DEV_SERVER_URL: options?.devServerUrl,
+        }),
+      ),
+    ),
+  );
+}
+
+const withHarness = <A, E, R>(
+  effect: Effect.Effect<
+    A,
+    E,
+    | R
+    | DesktopEnvironment.DesktopEnvironment
+    | FileSystem.FileSystem
+    | DesktopBackendConfiguration.DesktopBackendConfiguration
+  >,
+) =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+      prefix: "t3-desktop-backend-config-test-",
+    });
+
+    return yield* effect.pipe(
+      Effect.provide(
+        DesktopBackendConfiguration.layer.pipe(
+          Layer.provideMerge(serverExposureLayer),
+          Layer.provideMerge(makeEnvironmentLayer(baseDir)),
+        ),
+      ),
+    );
+  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
+
+describe("DesktopBackendConfiguration", () => {
+  it.effect("resolves backend start config with a stable scoped bootstrap token", () =>
+    withHarness(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
+
+        const first = yield* configuration.resolve;
+        const second = yield* configuration.resolve;
+
+        assert.equal(first.executablePath, process.execPath);
+        assert.equal(first.entryPath, environment.backendEntryPath);
+        assert.equal(first.cwd, environment.backendCwd);
+        assert.equal(first.captureOutput, true);
+        assert.equal(first.env.ELECTRON_RUN_AS_NODE, "1");
+        assert.isUndefined(first.env.T3CODE_PORT);
+        assert.isUndefined(first.env.T3CODE_MODE);
+        assert.isUndefined(first.env.T3CODE_DESKTOP_LAN_HOST);
+
+        assert.equal(first.bootstrap.mode, "desktop");
+        assert.equal(first.bootstrap.noBrowser, true);
+        assert.equal(first.bootstrap.port, 4888);
+        assert.equal(first.bootstrap.host, "0.0.0.0");
+        assert.equal(first.bootstrap.t3Home, environment.baseDir);
+        assert.equal(first.bootstrap.tailscaleServeEnabled, true);
+        assert.equal(first.bootstrap.tailscaleServePort, 8443);
+        assert.match(first.bootstrap.desktopBootstrapToken, /^[0-9a-f]{48}$/i);
+        assert.equal(second.bootstrap.desktopBootstrapToken, first.bootstrap.desktopBootstrapToken);
+      }),
+    ),
+  );
+
+  it.effect("includes persisted backend observability endpoints when present", () =>
+    withHarness(
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
+
+        yield* fileSystem.makeDirectory(environment.path.dirname(environment.serverSettingsPath), {
+          recursive: true,
+        });
+        yield* fileSystem.writeFileString(
+          environment.serverSettingsPath,
+          yield* encodePersistedServerObservabilitySettingsDocument({
+            observability: {
+              otlpTracesUrl: " http://127.0.0.1:4318/v1/traces ",
+              otlpMetricsUrl: " http://127.0.0.1:4318/v1/metrics ",
+            },
+          }),
+        );
+
+        const config = yield* configuration.resolve;
+        assert.equal(config.bootstrap.otlpTracesUrl, "http://127.0.0.1:4318/v1/traces");
+        assert.equal(config.bootstrap.otlpMetricsUrl, "http://127.0.0.1:4318/v1/metrics");
+      }),
+    ),
+  );
+
+  it.effect("omits backend observability endpoints when settings are missing", () =>
+    withHarness(
+      Effect.gen(function* () {
+        const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
+        const config = yield* configuration.resolve;
+
+        assert.isUndefined(config.bootstrap.otlpTracesUrl);
+        assert.isUndefined(config.bootstrap.otlpMetricsUrl);
+      }),
+    ),
+  );
+
+  it.effect("captures backend output in development so child process logs can be persisted", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-desktop-backend-config-test-",
+      });
+
+      yield* Effect.gen(function* () {
+        const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
+        const config = yield* configuration.resolve;
+        assert.equal(config.captureOutput, true);
+      }).pipe(
+        Effect.provide(
+          DesktopBackendConfiguration.layer.pipe(
+            Layer.provideMerge(serverExposureLayer),
+            Layer.provideMerge(
+              makeEnvironmentLayer(baseDir, {
+                isPackaged: false,
+                devServerUrl: "http://127.0.0.1:5733",
+              }),
+            ),
+          ),
+        ),
+      );
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+  );
+});
diff --git a/apps/desktop/src/backend/DesktopBackendConfiguration.ts b/apps/desktop/src/backend/DesktopBackendConfiguration.ts
new file mode 100644
index 00000000000..42e4ada438b
--- /dev/null
+++ b/apps/desktop/src/backend/DesktopBackendConfiguration.ts
@@ -0,0 +1,170 @@
+import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Random from "effect/Random";
+import * as Ref from "effect/Ref";
+
+import * as DesktopBackendManager from "./DesktopBackendManager.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as DesktopServerExposure from "./DesktopServerExposure.ts";
+
+export interface DesktopBackendConfigurationShape {
+  readonly resolve: Effect.Effect<DesktopBackendManager.DesktopBackendStartConfig>;
+}
+
+export class DesktopBackendConfiguration extends Context.Service<
+  DesktopBackendConfiguration,
+  DesktopBackendConfigurationShape
+>()("t3/desktop/BackendConfiguration") {}
+
+interface BackendObservabilitySettings {
+  readonly otlpTracesUrl: Option.Option<string>;
+  readonly otlpMetricsUrl: Option.Option<string>;
+}
+
+const emptyBackendObservabilitySettings: BackendObservabilitySettings = {
+  otlpTracesUrl: Option.none(),
+  otlpMetricsUrl: Option.none(),
+};
+
+const DESKTOP_BACKEND_ENV_NAMES = [
+  "T3CODE_PORT",
+  "T3CODE_MODE",
+  "T3CODE_NO_BROWSER",
+  "T3CODE_HOST",
+  "T3CODE_DESKTOP_WS_URL",
+  "T3CODE_DESKTOP_LAN_ACCESS",
+  "T3CODE_DESKTOP_LAN_HOST",
+  "T3CODE_DESKTOP_HTTPS_ENDPOINTS",
+  "T3CODE_TAILSCALE_SERVE",
+  "T3CODE_TAILSCALE_SERVE_PORT",
+] as const;
+
+const backendChildEnvPatch = (): Record<string, string | undefined> =>
+  Object.fromEntries(DESKTOP_BACKEND_ENV_NAMES.map((name) => [name, undefined]));
+
+const { logWarning: logBackendConfigurationWarning } = DesktopObservability.makeComponentLogger(
+  "desktop-backend-configuration",
+);
+
+const readPersistedBackendObservabilitySettings: Effect.Effect<
+  BackendObservabilitySettings,
+  never,
+  FileSystem.FileSystem | DesktopEnvironment.DesktopEnvironment
+> = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const exists = yield* fileSystem
+    .exists(environment.serverSettingsPath)
+    .pipe(Effect.orElseSucceed(() => false));
+  if (!exists) {
+    return emptyBackendObservabilitySettings;
+  }
+
+  const raw = yield* fileSystem.readFileString(environment.serverSettingsPath).pipe(Effect.option);
+  if (Option.isNone(raw)) {
+    yield* logBackendConfigurationWarning(
+      "failed to read persisted backend observability settings",
+    );
+    return emptyBackendObservabilitySettings;
+  }
+
+  const parsed = parsePersistedServerObservabilitySettings(raw.value);
+  return {
+    otlpTracesUrl: Option.fromNullishOr(parsed.otlpTracesUrl),
+    otlpMetricsUrl: Option.fromNullishOr(parsed.otlpMetricsUrl),
+  };
+});
+
+const getOrCreateBootstrapToken = Effect.fn("desktop.backendConfiguration.bootstrapToken")(
+  function* (tokenRef: Ref.Ref<Option.Option<string>>) {
+    const existing = yield* Ref.get(tokenRef);
+    if (Option.isSome(existing)) {
+      return existing.value;
+    }
+
+    let token = "";
+    while (token.length < 48) {
+      token += (yield* Random.nextUUIDv4).replace(/-/g, "");
+    }
+    token = token.slice(0, 48);
+    yield* Ref.set(tokenRef, Option.some(token));
+    return token;
+  },
+);
+
+const resolveBackendStartConfig = Effect.fn("desktop.backendConfiguration.resolveStartConfig")(
+  function* (input: {
+    readonly bootstrapToken: string;
+    readonly observabilitySettings: BackendObservabilitySettings;
+  }): Effect.fn.Return<
+    DesktopBackendManager.DesktopBackendStartConfig,
+    never,
+    DesktopEnvironment.DesktopEnvironment | DesktopServerExposure.DesktopServerExposure
+  > {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+    const backendExposure = yield* serverExposure.backendConfig;
+
+    return {
+      executablePath: process.execPath,
+      entryPath: environment.backendEntryPath,
+      cwd: environment.backendCwd,
+      env: {
+        ...backendChildEnvPatch(),
+        ELECTRON_RUN_AS_NODE: "1",
+      },
+      bootstrap: {
+        mode: "desktop",
+        noBrowser: true,
+        port: backendExposure.port,
+        t3Home: environment.baseDir,
+        host: backendExposure.bindHost,
+        desktopBootstrapToken: input.bootstrapToken,
+        tailscaleServeEnabled: backendExposure.tailscaleServeEnabled,
+        tailscaleServePort: backendExposure.tailscaleServePort,
+        ...Option.match(input.observabilitySettings.otlpTracesUrl, {
+          onNone: () => ({}),
+          onSome: (otlpTracesUrl) => ({ otlpTracesUrl }),
+        }),
+        ...Option.match(input.observabilitySettings.otlpMetricsUrl, {
+          onNone: () => ({}),
+          onSome: (otlpMetricsUrl) => ({ otlpMetricsUrl }),
+        }),
+      },
+      httpBaseUrl: backendExposure.httpBaseUrl,
+      captureOutput: true,
+    };
+  },
+);
+
+export const layer = Layer.effect(
+  DesktopBackendConfiguration,
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const fileSystem = yield* FileSystem.FileSystem;
+    const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+    const tokenRef = yield* Ref.make(Option.none<string>());
+
+    return DesktopBackendConfiguration.of({
+      resolve: Effect.gen(function* () {
+        const bootstrapToken = yield* getOrCreateBootstrapToken(tokenRef);
+        const observabilitySettings = yield* readPersistedBackendObservabilitySettings.pipe(
+          Effect.provideService(FileSystem.FileSystem, fileSystem),
+          Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),
+        );
+        return yield* resolveBackendStartConfig({
+          bootstrapToken,
+          observabilitySettings,
+        }).pipe(
+          Effect.provideService(DesktopEnvironment.DesktopEnvironment, environment),
+          Effect.provideService(DesktopServerExposure.DesktopServerExposure, serverExposure),
+        );
+      }).pipe(Effect.withSpan("desktop.backendConfiguration.resolve")),
+    });
+  }),
+);
diff --git a/apps/desktop/src/backend/DesktopBackendManager.test.ts b/apps/desktop/src/backend/DesktopBackendManager.test.ts
new file mode 100644
index 00000000000..6c5109c8714
--- /dev/null
+++ b/apps/desktop/src/backend/DesktopBackendManager.test.ts
@@ -0,0 +1,494 @@
+import {
+  DesktopBackendBootstrap,
+  type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
+} from "@t3tools/contracts";
+import { assert, describe, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Sink from "effect/Sink";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as DesktopBackendManager from "./DesktopBackendManager.ts";
+import * as DesktopBackendConfiguration from "./DesktopBackendConfiguration.ts";
+import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as DesktopState from "../app/DesktopState.ts";
+import * as DesktopWindow from "../window/DesktopWindow.ts";
+
+const decodeDesktopBackendBootstrap = Schema.decodeEffect(
+  Schema.fromJsonString(DesktopBackendBootstrap),
+);
+
+const baseConfig: DesktopBackendManager.DesktopBackendStartConfig = {
+  executablePath: "/electron",
+  entryPath: "/server/bin.mjs",
+  cwd: "/server",
+  env: { ELECTRON_RUN_AS_NODE: "1" },
+  bootstrap: {
+    mode: "desktop",
+    noBrowser: true,
+    port: 3773,
+    t3Home: "/tmp/t3",
+    host: "127.0.0.1",
+    desktopBootstrapToken: "token",
+    tailscaleServeEnabled: false,
+    tailscaleServePort: 443,
+  },
+  httpBaseUrl: new URL("http://127.0.0.1:3773"),
+  captureOutput: true,
+};
+
+const configWithObservability: DesktopBackendBootstrapValue = {
+  ...baseConfig.bootstrap,
+  tailscaleServeEnabled: true,
+  otlpTracesUrl: "http://127.0.0.1:4318/v1/traces",
+};
+
+function makeProcess(options?: {
+  readonly stdout?: Stream.Stream<Uint8Array>;
+  readonly stderr?: Stream.Stream<Uint8Array>;
+  readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+  readonly kill?: ChildProcessSpawner.ChildProcessHandle["kill"];
+}): ChildProcessSpawner.ChildProcessHandle {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout: options?.stdout ?? Stream.empty,
+    stderr: options?.stderr ?? Stream.empty,
+    all: Stream.merge(options?.stdout ?? Stream.empty, options?.stderr ?? Stream.empty),
+    exitCode: options?.exitCode ?? Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+    isRunning: Effect.succeed(false),
+    kill: options?.kill ?? (() => Effect.void),
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+}
+
+function responseForRequest(
+  request: HttpClientRequest.HttpClientRequest,
+  status: number,
+): HttpClientResponse.HttpClientResponse {
+  return HttpClientResponse.fromWeb(request, new Response(null, { status }));
+}
+
+function httpClientLayer(
+  handler: (
+    request: HttpClientRequest.HttpClientRequest,
+  ) => Effect.Effect<HttpClientResponse.HttpClientResponse>,
+) {
+  return Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => handler(request)),
+  );
+}
+
+const healthyHttpClientLayer = httpClientLayer((request) =>
+  Effect.succeed(responseForRequest(request, 200)),
+);
+
+function decodeBootstrap(raw: string) {
+  return decodeDesktopBackendBootstrap(raw);
+}
+
+function makeManagerLayer(input: {
+  readonly spawnerLayer: Layer.Layer<ChildProcessSpawner.ChildProcessSpawner>;
+  readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient>;
+  readonly backendOutputLog?: Partial<DesktopObservability.DesktopBackendOutputLogShape>;
+  readonly desktopState?: DesktopState.DesktopStateShape;
+  readonly desktopWindow?: Partial<DesktopWindow.DesktopWindowShape>;
+  readonly config?: DesktopBackendManager.DesktopBackendStartConfig;
+}) {
+  return DesktopBackendManager.layer.pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        FileSystem.layerNoop({
+          exists: () => Effect.succeed(true),
+        }),
+        Layer.succeed(DesktopBackendConfiguration.DesktopBackendConfiguration, {
+          resolve: Effect.succeed(input.config ?? baseConfig),
+        }),
+        input.spawnerLayer,
+        input.httpClientLayer ?? healthyHttpClientLayer,
+        input.desktopState
+          ? Layer.succeed(DesktopState.DesktopState, input.desktopState)
+          : DesktopState.layer,
+        Layer.succeed(DesktopObservability.DesktopBackendOutputLog, {
+          writeSessionBoundary: () => Effect.void,
+          writeOutputChunk: () => Effect.void,
+          ...input.backendOutputLog,
+        } satisfies DesktopObservability.DesktopBackendOutputLogShape),
+        Layer.succeed(DesktopWindow.DesktopWindow, {
+          createMain: Effect.die("unexpected createMain"),
+          ensureMain: Effect.die("unexpected ensureMain"),
+          revealOrCreateMain: Effect.die("unexpected revealOrCreateMain"),
+          activate: Effect.void,
+          createMainIfBackendReady: Effect.void,
+          handleBackendReady: Effect.void,
+          dispatchMenuAction: () => Effect.void,
+          syncAppearance: Effect.void,
+          ...input.desktopWindow,
+        } satisfies DesktopWindow.DesktopWindowShape),
+      ),
+    ),
+  );
+}
+
+describe("DesktopBackendManager", () => {
+  it.effect("spawns the backend with fd3 bootstrap JSON and reports HTTP readiness", () =>
+    Effect.gen(function* () {
+      let spawnedCommand: ChildProcess.Command | undefined;
+      let bootstrapJson = "";
+      let readyCount = 0;
+      const ready = yield* Deferred.make<void>();
+      const exited = yield* Queue.unbounded<void>();
+
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make((command) =>
+          Effect.gen(function* () {
+            spawnedCommand = command;
+            if (command._tag === "StandardCommand") {
+              const fd3 = command.options.additionalFds?.fd3;
+              if (fd3?.type === "input" && fd3.stream) {
+                bootstrapJson = yield* fd3.stream.pipe(Stream.decodeText(), Stream.mkString);
+              }
+            }
+
+            return makeProcess({
+              exitCode: Deferred.await(ready).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+            });
+          }),
+        ),
+      );
+
+      const managerLayer = makeManagerLayer({
+        config: {
+          ...baseConfig,
+          bootstrap: configWithObservability,
+        },
+        spawnerLayer,
+        desktopWindow: {
+          handleBackendReady: Effect.sync(() => {
+            readyCount += 1;
+          }).pipe(Effect.andThen(Deferred.succeed(ready, void 0))),
+        },
+        backendOutputLog: {
+          writeSessionBoundary: ({ phase }) =>
+            phase === "END" ? Queue.offer(exited, void 0).pipe(Effect.asVoid) : Effect.void,
+        },
+      });
+
+      yield* Effect.gen(function* () {
+        const manager = yield* DesktopBackendManager.DesktopBackendManager;
+        yield* manager.start;
+        yield* Queue.take(exited);
+
+        assert.equal(readyCount, 1);
+        assert.isDefined(spawnedCommand);
+        if (spawnedCommand._tag !== "StandardCommand") {
+          throw new Error("Expected backend to spawn a standard command.");
+        }
+
+        assert.equal(spawnedCommand.command, "/electron");
+        assert.deepEqual(spawnedCommand.args, ["/server/bin.mjs", "--bootstrap-fd", "3"]);
+        assert.equal(spawnedCommand.options.cwd, "/server");
+        assert.equal(spawnedCommand.options.extendEnv, true);
+        assert.equal(spawnedCommand.options.stdout, "pipe");
+        assert.equal(spawnedCommand.options.stderr, "pipe");
+        assert.equal(spawnedCommand.options.killSignal, "SIGTERM");
+        assert.isDefined(spawnedCommand.options.forceKillAfter);
+        assert.equal(
+          Duration.toMillis(Duration.fromInputUnsafe(spawnedCommand.options.forceKillAfter)),
+          2_000,
+        );
+
+        assert.deepEqual(yield* decodeBootstrap(bootstrapJson), configWithObservability);
+      }).pipe(Effect.provide(managerLayer));
+    }),
+  );
+
+  it.effect("retries HTTP readiness before reporting the backend ready", () =>
+    Effect.gen(function* () {
+      const requestUrls: Array<string> = [];
+      const statuses = [503, 200];
+      let readyCount = 0;
+      const firstRequest = yield* Deferred.make<void>();
+      const ready = yield* Deferred.make<void>();
+      const exited = yield* Queue.unbounded<void>();
+
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make(() =>
+          Effect.succeed(
+            makeProcess({
+              exitCode: Deferred.await(ready).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+            }),
+          ),
+        ),
+      );
+
+      const managerLayer = makeManagerLayer({
+        spawnerLayer,
+        httpClientLayer: httpClientLayer((request) =>
+          Effect.gen(function* () {
+            const status = statuses.shift();
+            assert.isDefined(status);
+            requestUrls.push(request.url);
+            yield* Deferred.succeed(firstRequest, void 0);
+            return responseForRequest(request, status);
+          }),
+        ),
+        desktopWindow: {
+          handleBackendReady: Effect.sync(() => {
+            readyCount += 1;
+          }).pipe(Effect.andThen(Deferred.succeed(ready, void 0))),
+        },
+        backendOutputLog: {
+          writeSessionBoundary: ({ phase }) =>
+            phase === "END" ? Queue.offer(exited, void 0).pipe(Effect.asVoid) : Effect.void,
+        },
+      });
+
+      yield* Effect.gen(function* () {
+        const manager = yield* DesktopBackendManager.DesktopBackendManager;
+        yield* manager.start;
+        yield* Deferred.await(firstRequest);
+
+        assert.equal(readyCount, 0);
+        assert.deepEqual(requestUrls, ["http://127.0.0.1:3773/.well-known/t3/environment"]);
+
+        yield* TestClock.adjust(Duration.millis(100));
+        yield* Queue.take(exited);
+
+        assert.equal(readyCount, 1);
+        assert.deepEqual(requestUrls, [
+          "http://127.0.0.1:3773/.well-known/t3/environment",
+          "http://127.0.0.1:3773/.well-known/t3/environment",
+        ]);
+      }).pipe(Effect.provide(Layer.merge(TestClock.layer(), managerLayer)));
+    }),
+  );
+
+  it.effect("starts the configured backend and closes the scoped process on stop", () =>
+    Effect.gen(function* () {
+      let startCount = 0;
+      let closedCount = 0;
+      const closed = yield* Deferred.make<void>();
+      const startedPids = yield* Queue.unbounded<number>();
+      const ready = yield* Deferred.make<void>();
+      const backendReady = yield* Ref.make(false);
+      const quitting = yield* Ref.make(false);
+
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make(() =>
+          Effect.gen(function* () {
+            const scope = yield* Scope.Scope;
+            startCount += 1;
+            yield* Queue.offer(startedPids, 123);
+            const close = Effect.sync(() => {
+              closedCount += 1;
+            }).pipe(Effect.andThen(Deferred.succeed(closed, void 0)), Effect.asVoid);
+
+            yield* Scope.addFinalizer(scope, close);
+
+            return makeProcess({
+              exitCode: Deferred.await(closed).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+              kill: () => close,
+            });
+          }),
+        ),
+      );
+
+      const managerLayer = makeManagerLayer({
+        spawnerLayer,
+        desktopState: {
+          backendReady,
+          quitting,
+        },
+        desktopWindow: {
+          handleBackendReady: Deferred.succeed(ready, void 0).pipe(Effect.asVoid),
+        },
+      });
+
+      yield* Effect.gen(function* () {
+        const manager = yield* DesktopBackendManager.DesktopBackendManager;
+        assert.isTrue(Option.isNone(yield* manager.currentConfig));
+
+        yield* manager.start;
+        assert.equal(yield* Queue.take(startedPids), 123);
+        yield* Deferred.await(ready);
+        assert.isTrue(yield* Ref.get(backendReady));
+        assert.deepEqual(yield* manager.currentConfig, Option.some(baseConfig));
+
+        const runningSnapshot = yield* manager.snapshot;
+        assert.equal(runningSnapshot.ready, true);
+        assert.deepEqual(runningSnapshot.activePid, Option.some(123));
+
+        yield* manager.stop();
+        assert.equal(startCount, 1);
+        assert.equal(closedCount, 1);
+
+        const stoppedSnapshot = yield* manager.snapshot;
+        assert.isFalse(yield* Ref.get(backendReady));
+        assert.equal(stoppedSnapshot.desiredRunning, false);
+        assert.equal(stoppedSnapshot.ready, false);
+        assert.equal(Option.isNone(stoppedSnapshot.activePid), true);
+      }).pipe(Effect.provide(managerLayer));
+    }),
+  );
+
+  it.effect("restarts an unexpectedly exited backend with the Effect clock", () =>
+    Effect.gen(function* () {
+      const starts = yield* Queue.unbounded<number>();
+      let startCount = 0;
+
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make(() =>
+          Effect.sync(() => {
+            startCount += 1;
+            return makeProcess({
+              exitCode: Queue.offer(starts, startCount).pipe(
+                Effect.as(ChildProcessSpawner.ExitCode(1)),
+              ),
+            });
+          }),
+        ),
+      );
+
+      const managerLayer = makeManagerLayer({
+        spawnerLayer,
+        httpClientLayer: httpClientLayer(() => Effect.never),
+      });
+
+      yield* Effect.gen(function* () {
+        const manager = yield* DesktopBackendManager.DesktopBackendManager;
+        yield* manager.start;
+
+        assert.equal(yield* Queue.take(starts), 1);
+
+        yield* TestClock.adjust(Duration.millis(499));
+        assert.equal(yield* Queue.size(starts), 0);
+        yield* TestClock.adjust(Duration.millis(1));
+        assert.equal(yield* Queue.take(starts), 2);
+
+        yield* TestClock.adjust(Duration.millis(999));
+        assert.equal(yield* Queue.size(starts), 0);
+        yield* TestClock.adjust(Duration.millis(1));
+        assert.equal(yield* Queue.take(starts), 3);
+      }).pipe(Effect.provide(Layer.merge(TestClock.layer(), managerLayer)));
+    }),
+  );
+
+  it.effect("cancels a scheduled restart when start is requested manually", () =>
+    Effect.gen(function* () {
+      const starts = yield* Queue.unbounded<number>();
+      const secondClosed = yield* Deferred.make<void>();
+      let startCount = 0;
+
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make(() =>
+          Effect.gen(function* () {
+            startCount += 1;
+            yield* Queue.offer(starts, startCount);
+
+            if (startCount === 1) {
+              return makeProcess({
+                exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(1)),
+              });
+            }
+
+            const scope = yield* Scope.Scope;
+            const close = Deferred.succeed(secondClosed, void 0).pipe(Effect.asVoid);
+            yield* Scope.addFinalizer(scope, close);
+            return makeProcess({
+              exitCode: Deferred.await(secondClosed).pipe(
+                Effect.as(ChildProcessSpawner.ExitCode(0)),
+              ),
+              kill: () => close,
+            });
+          }),
+        ),
+      );
+
+      const managerLayer = makeManagerLayer({
+        spawnerLayer,
+        httpClientLayer: httpClientLayer(() => Effect.never),
+      });
+
+      yield* Effect.gen(function* () {
+        const manager = yield* DesktopBackendManager.DesktopBackendManager;
+        yield* manager.start;
+
+        assert.equal(yield* Queue.take(starts), 1);
+
+        yield* manager.start;
+        assert.equal(yield* Queue.take(starts), 2);
+
+        yield* manager.stop();
+        yield* TestClock.adjust(Duration.millis(500));
+
+        assert.equal(yield* Queue.size(starts), 0);
+      }).pipe(Effect.provide(Layer.merge(TestClock.layer(), managerLayer)));
+    }),
+  );
+
+  it.effect("does not restart after stop cancels a scheduled restart", () =>
+    Effect.gen(function* () {
+      const starts = yield* Queue.unbounded<number>();
+      let startCount = 0;
+
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make(() =>
+          Effect.sync(() => {
+            startCount += 1;
+            return makeProcess({
+              exitCode: Queue.offer(starts, startCount).pipe(
+                Effect.as(ChildProcessSpawner.ExitCode(1)),
+              ),
+            });
+          }),
+        ),
+      );
+
+      const managerLayer = makeManagerLayer({
+        spawnerLayer,
+        httpClientLayer: httpClientLayer(() => Effect.never),
+      });
+
+      yield* Effect.gen(function* () {
+        const manager = yield* DesktopBackendManager.DesktopBackendManager;
+        yield* manager.start;
+        assert.equal(yield* Queue.take(starts), 1);
+
+        let restartScheduled = false;
+        while (!restartScheduled) {
+          restartScheduled = (yield* manager.snapshot).restartScheduled;
+          if (!restartScheduled) {
+            yield* Effect.yieldNow;
+          }
+        }
+
+        yield* manager.stop();
+        yield* TestClock.adjust(Duration.millis(500));
+
+        assert.equal(yield* Queue.size(starts), 0);
+        assert.equal((yield* manager.snapshot).desiredRunning, false);
+      }).pipe(Effect.provide(Layer.merge(TestClock.layer(), managerLayer)));
+    }),
+  );
+});
diff --git a/apps/desktop/src/backend/DesktopBackendManager.ts b/apps/desktop/src/backend/DesktopBackendManager.ts
new file mode 100644
index 00000000000..97931f42dbd
--- /dev/null
+++ b/apps/desktop/src/backend/DesktopBackendManager.ts
@@ -0,0 +1,596 @@
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  DesktopBackendBootstrap,
+  type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
+} from "@t3tools/contracts";
+
+import * as DesktopBackendConfiguration from "./DesktopBackendConfiguration.ts";
+import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as DesktopState from "../app/DesktopState.ts";
+import * as DesktopWindow from "../window/DesktopWindow.ts";
+
+const INITIAL_RESTART_DELAY = Duration.millis(500);
+const MAX_RESTART_DELAY = Duration.seconds(10);
+const DEFAULT_BACKEND_READINESS_TIMEOUT = Duration.minutes(1);
+const DEFAULT_BACKEND_READINESS_INTERVAL = Duration.millis(100);
+const DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT = Duration.seconds(1);
+const DEFAULT_BACKEND_TERMINATE_GRACE = Duration.seconds(2);
+const BACKEND_READINESS_PATH = "/.well-known/t3/environment";
+
+type BackendProcessLayerServices = ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient;
+
+type BackendProcessRunRequirements = BackendProcessLayerServices | Scope.Scope;
+
+export type BackendProcessOutputStream = "stdout" | "stderr";
+
+export interface DesktopBackendStartConfig {
+  readonly executablePath: string;
+  readonly entryPath: string;
+  readonly cwd: string;
+  readonly env: Record<string, string | undefined>;
+  readonly bootstrap: DesktopBackendBootstrapValue;
+  readonly httpBaseUrl: URL;
+  readonly captureOutput: boolean;
+}
+
+interface BackendProcessExit {
+  readonly code: Option.Option<number>;
+  readonly reason: string;
+  readonly result: Result.Result<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>;
+}
+
+export class BackendTimeoutError extends Data.TaggedError("BackendTimeoutError")<{
+  readonly url: URL;
+}> {
+  override get message() {
+    return `Timed out waiting for backend readiness at ${this.url.href}.`;
+  }
+}
+
+class BackendProcessBootstrapEncodeError extends Data.TaggedError(
+  "BackendProcessBootstrapEncodeError",
+)<{
+  readonly cause: Schema.SchemaError;
+}> {
+  override get message() {
+    return `Failed to encode desktop backend bootstrap payload: ${this.cause.message}`;
+  }
+}
+
+class BackendProcessSpawnError extends Data.TaggedError("BackendProcessSpawnError")<{
+  readonly cause: PlatformError.PlatformError;
+}> {
+  override get message() {
+    return `Failed to spawn desktop backend process: ${this.cause.message}`;
+  }
+}
+
+type BackendProcessError = BackendProcessBootstrapEncodeError | BackendProcessSpawnError;
+
+interface RunBackendProcessOptions extends DesktopBackendStartConfig {
+  readonly readinessTimeout?: Duration.Duration;
+  readonly onStarted?: (pid: number) => Effect.Effect<void>;
+  readonly onReady?: () => Effect.Effect<void>;
+  readonly onReadinessFailure?: (error: BackendTimeoutError) => Effect.Effect<void>;
+  readonly onOutput?: (
+    streamName: BackendProcessOutputStream,
+    chunk: Uint8Array,
+  ) => Effect.Effect<void>;
+}
+
+export interface DesktopBackendSnapshot {
+  readonly desiredRunning: boolean;
+  readonly ready: boolean;
+  readonly activePid: Option.Option<number>;
+  readonly restartAttempt: number;
+  readonly restartScheduled: boolean;
+}
+
+export interface DesktopBackendManagerShape {
+  readonly start: Effect.Effect<void>;
+  readonly stop: (options?: { readonly timeout?: Duration.Duration }) => Effect.Effect<void>;
+  readonly currentConfig: Effect.Effect<Option.Option<DesktopBackendStartConfig>>;
+  readonly snapshot: Effect.Effect<DesktopBackendSnapshot>;
+}
+
+export class DesktopBackendManager extends Context.Service<
+  DesktopBackendManager,
+  DesktopBackendManagerShape
+>()("t3/desktop/BackendManager") {}
+
+const { logWarning: logBackendManagerWarning, logError: logBackendManagerError } =
+  DesktopObservability.makeComponentLogger("desktop-backend-manager");
+
+interface ActiveBackendRun {
+  readonly id: number;
+  readonly scope: Scope.Closeable;
+  readonly fiber: Option.Option<Fiber.Fiber<void, never>>;
+  readonly pid: Option.Option<number>;
+}
+
+interface BackendManagerState {
+  readonly desiredRunning: boolean;
+  readonly ready: boolean;
+  readonly config: Option.Option<DesktopBackendStartConfig>;
+  readonly active: Option.Option<ActiveBackendRun>;
+  readonly restartAttempt: number;
+  readonly restartFiber: Option.Option<Fiber.Fiber<void, never>>;
+  readonly nextRunId: number;
+}
+
+const initialState: BackendManagerState = {
+  desiredRunning: false,
+  ready: false,
+  config: Option.none(),
+  active: Option.none(),
+  restartAttempt: 0,
+  restartFiber: Option.none(),
+  nextRunId: 1,
+};
+
+const activePid = (active: Option.Option<ActiveBackendRun>): Option.Option<number> =>
+  Option.flatMap(active, (run) => run.pid);
+
+const withActiveRun =
+  (runId: number, f: (run: ActiveBackendRun) => ActiveBackendRun) =>
+  (state: BackendManagerState): BackendManagerState => ({
+    ...state,
+    active: Option.map(state.active, (run) => (run.id === runId ? f(run) : run)),
+  });
+
+const calculateRestartDelay = (attempt: number): Duration.Duration =>
+  Duration.min(Duration.times(INITIAL_RESTART_DELAY, 2 ** attempt), MAX_RESTART_DELAY);
+
+const closeRun = (
+  run: ActiveBackendRun,
+  options?: { readonly timeout?: Duration.Duration },
+): Effect.Effect<void> => {
+  const waitForFiber = Option.match(run.fiber, {
+    onNone: () => Effect.void,
+    onSome: (fiber) => Fiber.await(fiber).pipe(Effect.asVoid),
+  });
+  const close = Scope.close(run.scope, Exit.void).pipe(Effect.andThen(waitForFiber));
+
+  return (
+    options?.timeout ? close.pipe(Effect.timeoutOption(options.timeout), Effect.asVoid) : close
+  ).pipe(Effect.ignore);
+};
+
+const waitForHttpReady = Effect.fn("desktop.backendManager.waitForHttpReady")(function* (
+  baseUrl: URL,
+  timeout: Duration.Duration,
+): Effect.fn.Return<void, BackendTimeoutError, HttpClient.HttpClient> {
+  const readinessUrl = new URL(BACKEND_READINESS_PATH, baseUrl);
+  const client = (yield* HttpClient.HttpClient).pipe(
+    HttpClient.filterStatusOk,
+    HttpClient.transformResponse(Effect.timeout(DEFAULT_BACKEND_READINESS_REQUEST_TIMEOUT)),
+    HttpClient.retry(Schedule.spaced(DEFAULT_BACKEND_READINESS_INTERVAL)),
+  );
+
+  yield* client.get(readinessUrl).pipe(
+    Effect.asVoid,
+    Effect.timeout(timeout),
+    Effect.mapError(() => new BackendTimeoutError({ url: readinessUrl })),
+  );
+});
+
+function describeProcessExit(
+  result: Result.Result<ChildProcessSpawner.ExitCode, PlatformError.PlatformError>,
+): BackendProcessExit {
+  if (Result.isSuccess(result)) {
+    return {
+      code: Option.some(result.success),
+      reason: `code=${result.success}`,
+      result,
+    };
+  }
+
+  return {
+    code: Option.none(),
+    reason: result.failure.message,
+    result,
+  };
+}
+
+function drainBackendOutput(
+  streamName: BackendProcessOutputStream,
+  stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>,
+  onOutput: (streamName: BackendProcessOutputStream, chunk: Uint8Array) => Effect.Effect<void>,
+): Effect.Effect<void> {
+  return stream.pipe(
+    Stream.runForEach((chunk) => onOutput(streamName, chunk)),
+    Effect.ignore,
+  );
+}
+
+const encodeBootstrapJson = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap));
+
+const runBackendProcess = Effect.fn("runBackendProcess")(function* (
+  options: RunBackendProcessOptions,
+): Effect.fn.Return<BackendProcessExit, BackendProcessError, BackendProcessRunRequirements> {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const bootstrapJson = yield* encodeBootstrapJson(options.bootstrap).pipe(
+    Effect.mapError((cause) => new BackendProcessBootstrapEncodeError({ cause })),
+  );
+  const onOutput = options.onOutput ?? (() => Effect.void);
+  const command = ChildProcess.make(
+    options.executablePath,
+    [options.entryPath, "--bootstrap-fd", "3"],
+    {
+      cwd: options.cwd,
+      env: options.env,
+      extendEnv: true,
+      // In Electron main, process.execPath points to the Electron binary.
+      // Run the child in Node mode so this backend process does not become a GUI app instance.
+      stdin: "ignore",
+      stdout: options.captureOutput ? "pipe" : "inherit",
+      stderr: options.captureOutput ? "pipe" : "inherit",
+      killSignal: "SIGTERM",
+      forceKillAfter: DEFAULT_BACKEND_TERMINATE_GRACE,
+      additionalFds: {
+        fd3: {
+          type: "input",
+          stream: Stream.encodeText(Stream.make(`${bootstrapJson}\n`)),
+        },
+      },
+    },
+  );
+
+  const handle = yield* spawner
+    .spawn(command)
+    .pipe(Effect.mapError((cause) => new BackendProcessSpawnError({ cause })));
+
+  yield* options.onStarted?.(handle.pid) ?? Effect.void;
+  if (options.captureOutput) {
+    yield* drainBackendOutput("stdout", handle.stdout, onOutput).pipe(Effect.forkScoped);
+    yield* drainBackendOutput("stderr", handle.stderr, onOutput).pipe(Effect.forkScoped);
+  }
+  yield* waitForHttpReady(
+    options.httpBaseUrl,
+    options.readinessTimeout ?? DEFAULT_BACKEND_READINESS_TIMEOUT,
+  ).pipe(
+    Effect.tap(() => options.onReady?.() ?? Effect.void),
+    Effect.catch((error) => options.onReadinessFailure?.(error) ?? Effect.void),
+    Effect.forkScoped,
+  );
+
+  return describeProcessExit(yield* Effect.result(handle.exitCode));
+});
+
+const makeDesktopBackendManager = Effect.fn("makeDesktopBackendManager")(function* () {
+  const parentScope = yield* Scope.Scope;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
+  const backendOutputLog = yield* DesktopObservability.DesktopBackendOutputLog;
+  const desktopState = yield* DesktopState.DesktopState;
+  const desktopWindow = yield* DesktopWindow.DesktopWindow;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const httpClient = yield* HttpClient.HttpClient;
+  const state = yield* Ref.make(initialState);
+  const mutex = yield* Semaphore.make(1);
+
+  const updateActiveRun = (runId: number, f: (run: ActiveBackendRun) => ActiveBackendRun) =>
+    Ref.update(state, withActiveRun(runId, f));
+
+  const snapshot = Ref.get(state).pipe(
+    Effect.map(
+      (current): DesktopBackendSnapshot => ({
+        desiredRunning: current.desiredRunning,
+        ready: current.ready,
+        activePid: activePid(current.active),
+        restartAttempt: current.restartAttempt,
+        restartScheduled: Option.isSome(current.restartFiber),
+      }),
+    ),
+  );
+  const currentConfig = Ref.get(state).pipe(Effect.map((current) => current.config));
+
+  const cancelRestart = Effect.gen(function* () {
+    const restartFiber = yield* Ref.modify(state, (current) => [
+      current.restartFiber,
+      {
+        ...current,
+        restartFiber: Option.none(),
+      },
+    ]);
+
+    yield* Option.match(restartFiber, {
+      onNone: () => Effect.void,
+      onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.asVoid),
+    });
+  });
+
+  const start: Effect.Effect<void> = Effect.suspend(() =>
+    mutex.withPermits(1)(
+      Effect.gen(function* () {
+        const current = yield* Ref.get(state);
+        if (Option.isSome(current.active)) {
+          return;
+        }
+
+        yield* Ref.set(desktopState.backendReady, false);
+        const config = yield* configuration.resolve;
+        const entryExists = yield* fileSystem
+          .exists(config.entryPath)
+          .pipe(Effect.orElseSucceed(() => false));
+
+        yield* cancelRestart;
+        yield* Ref.update(state, (latest) => ({
+          ...latest,
+          desiredRunning: true,
+          ready: false,
+          config: Option.some(config),
+        }));
+
+        if (!entryExists) {
+          yield* scheduleRestart(`missing server entry at ${config.entryPath}`);
+          return;
+        }
+
+        const runScope = yield* Scope.make("sequential");
+        const runId = yield* Ref.modify(state, (latest) => [
+          latest.nextRunId,
+          {
+            ...latest,
+            active: Option.some({
+              id: latest.nextRunId,
+              scope: runScope,
+              fiber: Option.none(),
+              pid: Option.none(),
+            } satisfies ActiveBackendRun),
+            nextRunId: latest.nextRunId + 1,
+          },
+        ]);
+
+        const finalizeRun = Effect.fn("desktop.backendManager.finalizeRun")(function* (
+          reason: string,
+        ) {
+          yield* mutex.withPermits(1)(
+            Effect.gen(function* () {
+              const { isCurrentRun, nextState, pid } = yield* Ref.modify(
+                state,
+                (
+                  latest,
+                ): readonly [
+                  {
+                    readonly isCurrentRun: boolean;
+                    readonly nextState: BackendManagerState;
+                    readonly pid: Option.Option<number>;
+                  },
+                  BackendManagerState,
+                ] => {
+                  const currentRun = Option.getOrUndefined(latest.active);
+                  if (currentRun?.id !== runId) {
+                    return [
+                      {
+                        isCurrentRun: false,
+                        nextState: latest,
+                        pid: Option.none<number>(),
+                      },
+                      latest,
+                    ] as const;
+                  }
+
+                  const next = {
+                    ...latest,
+                    active: Option.none<ActiveBackendRun>(),
+                    ready: false,
+                  };
+                  return [
+                    {
+                      isCurrentRun: true,
+                      nextState: next,
+                      pid: currentRun.pid,
+                    },
+                    next,
+                  ] as const;
+                },
+              );
+
+              if (isCurrentRun) {
+                if (Option.isSome(pid)) {
+                  yield* backendOutputLog.writeSessionBoundary({
+                    phase: "END",
+                    details: `pid=${pid.value} ${reason}`,
+                  });
+                }
+                yield* Ref.set(desktopState.backendReady, false);
+              }
+
+              if (isCurrentRun && nextState.desiredRunning) {
+                yield* scheduleRestart(reason);
+              }
+            }),
+          );
+        });
+
+        const program = runBackendProcess({
+          ...config,
+          onStarted: Effect.fn("desktop.backendManager.onStarted")(function* (pid) {
+            yield* updateActiveRun(runId, (run) => ({
+              ...run,
+              pid: Option.some(pid),
+            }));
+            yield* backendOutputLog.writeSessionBoundary({
+              phase: "START",
+              details: `pid=${pid} port=${config.bootstrap.port} cwd=${config.cwd}`,
+            });
+          }),
+          onReady: Effect.fn("desktop.backendManager.onReady")(function* () {
+            const isCurrentRun = yield* Ref.modify(state, (latest) => {
+              const activeRun = Option.getOrUndefined(latest.active);
+              if (activeRun?.id !== runId) {
+                return [false, latest] as const;
+              }
+
+              return [
+                true,
+                {
+                  ...latest,
+                  restartAttempt: 0,
+                  ready: true,
+                },
+              ] as const;
+            });
+            if (!isCurrentRun) {
+              return;
+            }
+
+            yield* Ref.set(desktopState.backendReady, true);
+            yield* desktopWindow.handleBackendReady.pipe(
+              Effect.catch((error) =>
+                logBackendManagerError("failed to open main window after backend readiness", {
+                  message: error.message,
+                }),
+              ),
+            );
+          }),
+          onReadinessFailure: (error) =>
+            logBackendManagerWarning("backend readiness check failed during bootstrap", {
+              error: error.message,
+            }),
+          onOutput: (streamName, chunk) => backendOutputLog.writeOutputChunk(streamName, chunk),
+        }).pipe(
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+          Effect.provideService(HttpClient.HttpClient, httpClient),
+          Scope.provide(runScope),
+          Effect.matchEffect({
+            onFailure: (error) => finalizeRun(error.message),
+            onSuccess: (exit) => finalizeRun(exit.reason),
+          }),
+          Effect.ensuring(Scope.close(runScope, Exit.void).pipe(Effect.ignore)),
+        );
+
+        const fiber = yield* Effect.forkIn(program, parentScope);
+        yield* updateActiveRun(runId, (run) => ({
+          ...run,
+          fiber: Option.some(fiber),
+        }));
+      }),
+    ),
+  ).pipe(Effect.withSpan("desktop.backendManager.start"));
+
+  const scheduleRestart = Effect.fn("desktop.backendManager.scheduleRestart")(function* (
+    reason: string,
+  ) {
+    const scheduled = yield* Ref.modify(state, (latest) => {
+      if (!latest.desiredRunning || Option.isSome(latest.restartFiber)) {
+        return [Option.none<Duration.Duration>(), latest] as const;
+      }
+
+      const delay = calculateRestartDelay(latest.restartAttempt);
+      return [
+        Option.some(delay),
+        {
+          ...latest,
+          restartAttempt: latest.restartAttempt + 1,
+        },
+      ] as const;
+    });
+
+    yield* Option.match(scheduled, {
+      onNone: () => Effect.void,
+      onSome: Effect.fn("desktop.backendManager.scheduleRestartFiber")(function* (delay) {
+        yield* logBackendManagerError("backend exited unexpectedly; restart scheduled", {
+          reason,
+          delayMs: Duration.toMillis(delay),
+        });
+        const restartFiber = yield* Effect.forkIn(
+          Effect.sleep(delay).pipe(
+            Effect.andThen(
+              Ref.modify(state, (latest) => {
+                const shouldRestart = latest.desiredRunning;
+                return [
+                  shouldRestart,
+                  {
+                    ...latest,
+                    restartFiber: Option.none(),
+                  },
+                ] as const;
+              }),
+            ),
+            Effect.flatMap((shouldRestart) => (shouldRestart ? start : Effect.void)),
+            Effect.catchCause((cause) =>
+              logBackendManagerError("desktop backend restart fiber failed", {
+                cause: Cause.pretty(cause),
+              }),
+            ),
+          ),
+          parentScope,
+        );
+        yield* Ref.update(state, (latest) =>
+          Option.isNone(latest.restartFiber)
+            ? {
+                ...latest,
+                restartFiber: Option.some(restartFiber),
+              }
+            : latest,
+        );
+      }),
+    });
+  });
+
+  const stop = Effect.fn("desktop.backendManager.stop")(function* (options?: {
+    readonly timeout?: Duration.Duration;
+  }) {
+    const { active, restartFiber } = yield* mutex.withPermits(1)(
+      Effect.gen(function* () {
+        const result = yield* Ref.modify(state, (latest) => [
+          {
+            active: latest.active,
+            restartFiber: latest.restartFiber,
+          },
+          {
+            ...latest,
+            desiredRunning: false,
+            ready: false,
+            active: Option.none<ActiveBackendRun>(),
+            restartFiber: Option.none<Fiber.Fiber<void, never>>(),
+          },
+        ]);
+        yield* Ref.set(desktopState.backendReady, false);
+        return result;
+      }),
+    );
+
+    yield* Option.match(restartFiber, {
+      onNone: () => Effect.void,
+      onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.asVoid),
+    });
+    yield* Option.match(active, {
+      onNone: () => Effect.void,
+      onSome: (run) => closeRun(run, options),
+    });
+  });
+
+  yield* Effect.addFinalizer(() => stop());
+
+  return DesktopBackendManager.of({
+    start,
+    stop,
+    currentConfig,
+    snapshot,
+  });
+});
+
+export const layer = Layer.effect(DesktopBackendManager, makeDesktopBackendManager());
diff --git a/apps/desktop/src/backend/DesktopServerExposure.test.ts b/apps/desktop/src/backend/DesktopServerExposure.test.ts
new file mode 100644
index 00000000000..0f3e9eaeb45
--- /dev/null
+++ b/apps/desktop/src/backend/DesktopServerExposure.test.ts
@@ -0,0 +1,365 @@
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  DesktopEnvironment,
+  layer as makeDesktopEnvironmentLayer,
+} from "../app/DesktopEnvironment.ts";
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopServerExposure from "./DesktopServerExposure.ts";
+import type { DesktopNetworkInterfaces } from "./DesktopServerExposure.ts";
+import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
+
+const encoder = new TextEncoder();
+
+const emptyNetworkInterfaces: DesktopNetworkInterfaces = {};
+const lanNetworkInterfaces: DesktopNetworkInterfaces = {
+  en0: [
+    {
+      address: "192.168.1.20",
+      family: "IPv4",
+      internal: false,
+    },
+  ],
+};
+
+const tailnetNetworkInterfaces: DesktopNetworkInterfaces = {
+  tailscale0: [
+    {
+      address: "100.90.1.2",
+      family: "IPv4",
+      internal: false,
+    },
+  ],
+};
+
+function mockSpawnerLayer(statusJson = "{}") {
+  return Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make(() =>
+      Effect.succeed(
+        ChildProcessSpawner.makeHandle({
+          pid: ChildProcessSpawner.ProcessId(1),
+          exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+          isRunning: Effect.succeed(false),
+          kill: () => Effect.void,
+          unref: Effect.succeed(Effect.void),
+          stdin: Sink.drain,
+          stdout: Stream.make(encoder.encode(statusJson)),
+          stderr: Stream.empty,
+          all: Stream.empty,
+          getInputFd: () => Sink.drain,
+          getOutputFd: () => Stream.empty,
+        }),
+      ),
+    ),
+  );
+}
+
+function makeEnvironmentLayer(baseDir: string, env: Record<string, string | undefined> = {}) {
+  return makeDesktopEnvironmentLayer({
+    dirname: "/repo/apps/desktop/src",
+    homeDirectory: baseDir,
+    platform: "darwin",
+    processArch: "x64",
+    appVersion: "1.2.3",
+    appPath: "/repo",
+    isPackaged: true,
+    resourcesPath: "/missing/resources",
+    runningUnderArm64Translation: false,
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({ T3CODE_HOME: baseDir, ...env })),
+    ),
+  );
+}
+
+function makeLayer(input: {
+  readonly baseDir: string;
+  readonly networkInterfaces?: DesktopNetworkInterfaces;
+  readonly env?: Record<string, string | undefined>;
+}) {
+  const env = { T3CODE_HOME: input.baseDir, ...input.env };
+  const environmentLayer = makeEnvironmentLayer(input.baseDir, env);
+  const networkLayer = Layer.succeed(DesktopServerExposure.DesktopNetworkInterfacesService, {
+    read: Effect.succeed(input.networkInterfaces ?? emptyNetworkInterfaces),
+  });
+
+  return DesktopServerExposure.layer.pipe(
+    Layer.provideMerge(DesktopAppSettings.layer),
+    Layer.provideMerge(NodeFileSystem.layer),
+    Layer.provideMerge(NodeHttpClient.layerUndici),
+    Layer.provideMerge(mockSpawnerLayer()),
+    Layer.provideMerge(networkLayer),
+    Layer.provideMerge(DesktopConfig.layerTest(env)),
+    Layer.provideMerge(environmentLayer),
+  );
+}
+
+const withHarness = <A, E, R>(
+  networkInterfaces: DesktopNetworkInterfaces,
+  effect: Effect.Effect<
+    A,
+    E,
+    | R
+    | DesktopEnvironment
+    | FileSystem.FileSystem
+    | DesktopServerExposure.DesktopServerExposure
+    | DesktopAppSettings.DesktopAppSettings
+  >,
+  env: Record<string, string | undefined> = {},
+) =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+      prefix: "t3-desktop-server-exposure-test-",
+    });
+    return yield* effect.pipe(Effect.provide(makeLayer({ baseDir, networkInterfaces, env })));
+  }).pipe(Effect.provide(NodeServices.layer), Effect.scoped);
+
+describe("DesktopServerExposure", () => {
+  it.effect("falls back to local-only without losing the requested network preference", () =>
+    withHarness(
+      emptyNetworkInterfaces,
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+
+        yield* settings.setServerExposureMode("network-accessible");
+
+        const state = yield* serverExposure.configureFromSettings({ port: 4173 });
+        assert.equal(state.mode, "local-only");
+        assert.equal(state.endpointUrl, null);
+        assert.equal((yield* settings.get).serverExposureMode, "network-accessible");
+
+        const backendConfig = yield* serverExposure.backendConfig;
+        assert.equal(backendConfig.bindHost, "127.0.0.1");
+        assert.equal(backendConfig.httpBaseUrl.href, "http://127.0.0.1:4173/");
+      }),
+    ),
+  );
+
+  it.effect("returns a typed error when network access is explicitly unavailable", () =>
+    withHarness(
+      emptyNetworkInterfaces,
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        yield* serverExposure.configureFromSettings({ port: 4173 });
+
+        const error = yield* serverExposure.setMode("network-accessible").pipe(Effect.flip);
+        assert.ok(error._tag === "DesktopServerExposureNoNetworkAddressError");
+        assert.equal(error.port, 4173);
+      }),
+    ),
+  );
+
+  it.effect("persists network-accessible mode and updates backend binding state", () =>
+    withHarness(
+      lanNetworkInterfaces,
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+
+        yield* settings.load;
+        yield* serverExposure.configureFromSettings({ port: 4173 });
+
+        const change = yield* serverExposure.setMode("network-accessible");
+        assert.equal(change.requiresRelaunch, true);
+        assert.deepEqual(change.state, {
+          mode: "network-accessible",
+          endpointUrl: "http://192.168.1.20:4173",
+          advertisedHost: "192.168.1.20",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+        });
+
+        const backendConfig = yield* serverExposure.backendConfig;
+        assert.equal(backendConfig.bindHost, "0.0.0.0");
+        assert.equal(backendConfig.httpBaseUrl.href, "http://127.0.0.1:4173/");
+
+        const persisted = yield* settings.get;
+        assert.equal(persisted.serverExposureMode, "network-accessible");
+      }),
+    ),
+  );
+
+  it.effect("persists tailscale serve preferences atomically and reports no-op updates", () =>
+    withHarness(
+      emptyNetworkInterfaces,
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+
+        yield* settings.load;
+        yield* serverExposure.configureFromSettings({ port: 4173 });
+
+        const changed = yield* serverExposure.setTailscaleServeEnabled({
+          enabled: true,
+          port: 8443,
+        });
+        assert.equal(changed.requiresRelaunch, true);
+        assert.equal(changed.state.tailscaleServeEnabled, true);
+        assert.equal(changed.state.tailscaleServePort, 8443);
+
+        const unchanged = yield* serverExposure.setTailscaleServeEnabled({
+          enabled: true,
+          port: 8443,
+        });
+        assert.equal(unchanged.requiresRelaunch, false);
+
+        const persisted = yield* settings.get;
+        assert.equal(persisted.tailscaleServeEnabled, true);
+        assert.equal(persisted.tailscaleServePort, 8443);
+      }),
+    ),
+  );
+
+  it.effect("resolves advertised endpoints from the scoped runtime state", () =>
+    withHarness(
+      { ...lanNetworkInterfaces, ...tailnetNetworkInterfaces },
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        yield* serverExposure.configureFromSettings({ port: 4173 });
+        yield* serverExposure.setMode("network-accessible");
+
+        const endpoints = yield* serverExposure.getAdvertisedEndpoints;
+        assert.deepEqual(
+          endpoints.map((endpoint) => endpoint.httpBaseUrl),
+          ["http://127.0.0.1:4173/", "http://192.168.1.20:4173/", "http://100.90.1.2:4173/"],
+        );
+      }),
+    ),
+  );
+
+  it.effect("uses ConfigProvider desktop exposure overrides", () =>
+    withHarness(
+      lanNetworkInterfaces,
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        yield* serverExposure.configureFromSettings({ port: 4173 });
+        const change = yield* serverExposure.setMode("network-accessible");
+
+        assert.equal(change.state.advertisedHost, "10.0.0.7");
+        assert.equal(change.state.endpointUrl, "http://10.0.0.7:4173");
+
+        const endpoints = yield* serverExposure.getAdvertisedEndpoints;
+        assert.deepEqual(
+          endpoints.map((endpoint) => endpoint.httpBaseUrl),
+          ["http://127.0.0.1:4173/", "http://10.0.0.7:4173/", "https://public.example.test/"],
+        );
+      }),
+      {
+        T3CODE_DESKTOP_LAN_HOST: "10.0.0.7",
+        T3CODE_DESKTOP_HTTPS_ENDPOINTS: "https://public.example.test",
+      },
+    ),
+  );
+
+  it.effect("advertises loopback, LAN, and configured manual endpoints from runtime state", () =>
+    withHarness(
+      lanNetworkInterfaces,
+      Effect.gen(function* () {
+        const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+        yield* serverExposure.configureFromSettings({ port: 3773 });
+        yield* serverExposure.setMode("network-accessible");
+
+        const endpoints = yield* serverExposure.getAdvertisedEndpoints;
+        assert.deepEqual(endpoints, [
+          {
+            id: "desktop-loopback:3773",
+            label: "This machine",
+            provider: {
+              id: "desktop-core",
+              label: "Desktop",
+              kind: "core",
+              isAddon: false,
+            },
+            httpBaseUrl: "http://127.0.0.1:3773/",
+            wsBaseUrl: "ws://127.0.0.1:3773/",
+            reachability: "loopback",
+            compatibility: {
+              hostedHttpsApp: "mixed-content-blocked",
+              desktopApp: "compatible",
+            },
+            source: "desktop-core",
+            status: "available",
+            description: "Loopback endpoint for this desktop app.",
+          },
+          {
+            id: "desktop-lan:http://192.168.1.20:3773",
+            label: "Local network",
+            provider: {
+              id: "desktop-core",
+              label: "Desktop",
+              kind: "core",
+              isAddon: false,
+            },
+            httpBaseUrl: "http://192.168.1.20:3773/",
+            wsBaseUrl: "ws://192.168.1.20:3773/",
+            reachability: "lan",
+            compatibility: {
+              hostedHttpsApp: "mixed-content-blocked",
+              desktopApp: "compatible",
+            },
+            source: "desktop-core",
+            status: "available",
+            isDefault: true,
+            description: "Reachable from devices on the same network.",
+          },
+          {
+            id: "manual:https://desktop.example.ts.net",
+            label: "Custom HTTPS",
+            provider: {
+              id: "manual",
+              label: "Manual",
+              kind: "manual",
+              isAddon: false,
+            },
+            httpBaseUrl: "https://desktop.example.ts.net/",
+            wsBaseUrl: "wss://desktop.example.ts.net/",
+            reachability: "public",
+            compatibility: {
+              hostedHttpsApp: "compatible",
+              desktopApp: "compatible",
+            },
+            source: "user",
+            status: "unknown",
+            description: "User-configured HTTPS endpoint for this desktop backend.",
+          },
+          {
+            id: "manual:http://desktop.example.test:3773",
+            label: "Custom endpoint",
+            provider: {
+              id: "manual",
+              label: "Manual",
+              kind: "manual",
+              isAddon: false,
+            },
+            httpBaseUrl: "http://desktop.example.test:3773/",
+            wsBaseUrl: "ws://desktop.example.test:3773/",
+            reachability: "public",
+            compatibility: {
+              hostedHttpsApp: "mixed-content-blocked",
+              desktopApp: "compatible",
+            },
+            source: "user",
+            status: "unknown",
+            description: "User-configured endpoint for this desktop backend.",
+          },
+        ]);
+      }),
+      {
+        T3CODE_DESKTOP_HTTPS_ENDPOINTS:
+          "https://desktop.example.ts.net,http://desktop.example.test:3773,not-a-url",
+      },
+    ),
+  );
+});
diff --git a/apps/desktop/src/backend/DesktopServerExposure.ts b/apps/desktop/src/backend/DesktopServerExposure.ts
new file mode 100644
index 00000000000..bd0939a7775
--- /dev/null
+++ b/apps/desktop/src/backend/DesktopServerExposure.ts
@@ -0,0 +1,548 @@
+import * as NodeOS from "node:os";
+
+import {
+  createAdvertisedEndpoint,
+  type CreateAdvertisedEndpointInput,
+} from "@t3tools/shared/advertisedEndpoint";
+import type {
+  AdvertisedEndpoint,
+  AdvertisedEndpointProvider,
+  DesktopServerExposureMode,
+  DesktopServerExposureState,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { DEFAULT_DESKTOP_SETTINGS, type DesktopSettings } from "../settings/DesktopAppSettings.ts";
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import { resolveTailscaleAdvertisedEndpoints } from "./tailscaleEndpointProvider.ts";
+import * as DesktopAppSettingsService from "../settings/DesktopAppSettings.ts";
+
+export const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
+const DESKTOP_LAN_BIND_HOST = "0.0.0.0";
+
+export interface DesktopNetworkInterfaceInfo {
+  readonly address: string;
+  readonly family: string | number;
+  readonly internal: boolean;
+  readonly netmask?: string;
+  readonly mac?: string;
+  readonly cidr?: string | null;
+  readonly scopeid?: number;
+}
+
+export type DesktopNetworkInterfaces = Readonly<
+  Record<string, readonly DesktopNetworkInterfaceInfo[] | undefined>
+>;
+
+interface ResolvedDesktopServerExposure {
+  readonly mode: DesktopServerExposureMode;
+  readonly bindHost: string;
+  readonly localHttpUrl: string;
+  readonly localWsUrl: string;
+  readonly endpointUrl: string | null;
+  readonly advertisedHost: string | null;
+}
+
+interface DesktopAdvertisedEndpointInput {
+  readonly port: number;
+  readonly exposure: ResolvedDesktopServerExposure;
+  readonly customHttpsEndpointUrls?: readonly string[];
+}
+
+const DESKTOP_CORE_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
+  id: "desktop-core",
+  label: "Desktop",
+  kind: "core",
+  isAddon: false,
+};
+
+const DESKTOP_MANUAL_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
+  id: "manual",
+  label: "Manual",
+  kind: "manual",
+  isAddon: false,
+};
+
+const normalizeOptionalHost = (value: string | undefined): string | undefined => {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : undefined;
+};
+
+const isUsableLanIpv4Address = (address: string): boolean =>
+  !address.startsWith("127.") && !address.startsWith("169.254.");
+
+const isHttpsEndpointUrl = (value: string): boolean => {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+
+const resolveLanAdvertisedHost = (
+  networkInterfaces: DesktopNetworkInterfaces,
+  explicitHost: string | undefined,
+): string | null => {
+  const normalizedExplicitHost = normalizeOptionalHost(explicitHost);
+  if (normalizedExplicitHost) {
+    return normalizedExplicitHost;
+  }
+
+  for (const interfaceAddresses of Object.values(networkInterfaces)) {
+    if (!interfaceAddresses) continue;
+
+    for (const address of interfaceAddresses) {
+      if (address.internal) continue;
+      if (address.family !== "IPv4") continue;
+      if (!isUsableLanIpv4Address(address.address)) continue;
+      return address.address;
+    }
+  }
+
+  return null;
+};
+
+const resolveDesktopServerExposure = (input: {
+  readonly mode: DesktopServerExposureMode;
+  readonly port: number;
+  readonly networkInterfaces: DesktopNetworkInterfaces;
+  readonly advertisedHostOverride?: string;
+}): ResolvedDesktopServerExposure => {
+  const localHttpUrl = `http://${DESKTOP_LOOPBACK_HOST}:${input.port}`;
+  const localWsUrl = `ws://${DESKTOP_LOOPBACK_HOST}:${input.port}`;
+
+  if (input.mode === "local-only") {
+    return {
+      mode: input.mode,
+      bindHost: DESKTOP_LOOPBACK_HOST,
+      localHttpUrl,
+      localWsUrl,
+      endpointUrl: null,
+      advertisedHost: null,
+    };
+  }
+
+  const advertisedHost = resolveLanAdvertisedHost(
+    input.networkInterfaces,
+    input.advertisedHostOverride,
+  );
+
+  return {
+    mode: input.mode,
+    bindHost: DESKTOP_LAN_BIND_HOST,
+    localHttpUrl,
+    localWsUrl,
+    endpointUrl: advertisedHost ? `http://${advertisedHost}:${input.port}` : null,
+    advertisedHost,
+  };
+};
+
+const createDesktopEndpoint = (
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint =>
+  createAdvertisedEndpoint({
+    ...input,
+    provider: DESKTOP_CORE_ENDPOINT_PROVIDER,
+    source: "desktop-core",
+  });
+
+const createManualEndpoint = (
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint =>
+  createAdvertisedEndpoint({
+    ...input,
+    provider: DESKTOP_MANUAL_ENDPOINT_PROVIDER,
+    source: "user",
+  });
+
+const resolveDesktopCoreAdvertisedEndpoints = (
+  input: DesktopAdvertisedEndpointInput,
+): readonly AdvertisedEndpoint[] => {
+  const endpoints: AdvertisedEndpoint[] = [
+    createDesktopEndpoint({
+      id: `desktop-loopback:${input.port}`,
+      label: "This machine",
+      httpBaseUrl: input.exposure.localHttpUrl,
+      reachability: "loopback",
+      status: "available",
+      description: "Loopback endpoint for this desktop app.",
+    }),
+  ];
+
+  if (input.exposure.endpointUrl) {
+    endpoints.push(
+      createDesktopEndpoint({
+        id: `desktop-lan:${input.exposure.endpointUrl}`,
+        label: "Local network",
+        httpBaseUrl: input.exposure.endpointUrl,
+        reachability: "lan",
+        status: "available",
+        isDefault: true,
+        description: "Reachable from devices on the same network.",
+      }),
+    );
+  }
+
+  for (const customEndpointUrl of input.customHttpsEndpointUrls ?? []) {
+    try {
+      const isHttpsEndpoint = isHttpsEndpointUrl(customEndpointUrl);
+      endpoints.push(
+        createManualEndpoint({
+          id: `manual:${customEndpointUrl}`,
+          label: isHttpsEndpoint ? "Custom HTTPS" : "Custom endpoint",
+          httpBaseUrl: customEndpointUrl,
+          reachability: "public",
+          ...(isHttpsEndpoint ? ({ hostedHttpsCompatibility: "compatible" } as const) : {}),
+          status: "unknown",
+          description: isHttpsEndpoint
+            ? "User-configured HTTPS endpoint for this desktop backend."
+            : "User-configured endpoint for this desktop backend.",
+        }),
+      );
+    } catch {
+      // Ignore malformed user-configured endpoints without dropping valid endpoints.
+    }
+  }
+
+  return endpoints;
+};
+
+type DesktopServerExposurePersistenceOperation = "server-exposure-mode" | "tailscale-serve";
+
+export class DesktopServerExposureNoNetworkAddressError extends Data.TaggedError(
+  "DesktopServerExposureNoNetworkAddressError",
+)<{
+  readonly port: number;
+}> {
+  override get message() {
+    return `No reachable network address is available for desktop network access on port ${this.port}.`;
+  }
+}
+
+export class DesktopServerExposurePersistenceError extends Data.TaggedError(
+  "DesktopServerExposurePersistenceError",
+)<{
+  readonly operation: DesktopServerExposurePersistenceOperation;
+  readonly cause: DesktopAppSettingsService.DesktopSettingsWriteError;
+}> {
+  override get message() {
+    return `Failed to persist desktop ${this.operation} settings.`;
+  }
+}
+
+export type DesktopServerExposureSetModeError =
+  | DesktopServerExposureNoNetworkAddressError
+  | DesktopServerExposurePersistenceError;
+
+export type DesktopServerExposureError = DesktopServerExposureSetModeError;
+
+export interface DesktopServerExposureBackendConfig {
+  readonly port: number;
+  readonly bindHost: string;
+  readonly httpBaseUrl: URL;
+  readonly tailscaleServeEnabled: boolean;
+  readonly tailscaleServePort: number;
+}
+
+export interface DesktopServerExposureChange {
+  readonly state: DesktopServerExposureState;
+  readonly requiresRelaunch: boolean;
+}
+
+export interface DesktopServerExposureShape {
+  readonly getState: Effect.Effect<DesktopServerExposureState>;
+  readonly backendConfig: Effect.Effect<DesktopServerExposureBackendConfig>;
+  readonly configureFromSettings: (input: {
+    readonly port: number;
+  }) => Effect.Effect<DesktopServerExposureState>;
+  readonly setMode: (
+    mode: DesktopServerExposureMode,
+  ) => Effect.Effect<DesktopServerExposureChange, DesktopServerExposureSetModeError>;
+  readonly setTailscaleServeEnabled: (input: {
+    readonly enabled: boolean;
+    readonly port?: number;
+  }) => Effect.Effect<DesktopServerExposureChange, DesktopServerExposurePersistenceError>;
+  readonly getAdvertisedEndpoints: Effect.Effect<readonly AdvertisedEndpoint[]>;
+}
+
+export class DesktopServerExposure extends Context.Service<
+  DesktopServerExposure,
+  DesktopServerExposureShape
+>()("t3/desktop/ServerExposure") {}
+
+export interface DesktopNetworkInterfacesServiceShape {
+  readonly read: Effect.Effect<DesktopNetworkInterfaces>;
+}
+
+export class DesktopNetworkInterfacesService extends Context.Service<
+  DesktopNetworkInterfacesService,
+  DesktopNetworkInterfacesServiceShape
+>()("t3/desktop/ServerExposure/NetworkInterfaces") {}
+
+interface RuntimeState {
+  readonly requestedMode: DesktopServerExposureMode;
+  readonly mode: DesktopServerExposureMode;
+  readonly port: number;
+  readonly bindHost: string;
+  readonly localHttpUrl: string;
+  readonly localWsUrl: string;
+  readonly httpBaseUrl: URL;
+  readonly endpointUrl: Option.Option<string>;
+  readonly advertisedHost: Option.Option<string>;
+  readonly tailscaleServeEnabled: boolean;
+  readonly tailscaleServePort: number;
+}
+
+interface ResolvedRuntimeState {
+  readonly state: RuntimeState;
+  readonly unavailable: boolean;
+}
+
+const initialRuntimeState = (): RuntimeState =>
+  runtimeStateFromResolvedExposure({
+    requestedMode: DEFAULT_DESKTOP_SETTINGS.serverExposureMode,
+    settings: DEFAULT_DESKTOP_SETTINGS,
+    exposure: resolveDesktopServerExposure({
+      mode: DEFAULT_DESKTOP_SETTINGS.serverExposureMode,
+      port: 0,
+      networkInterfaces: {},
+    }),
+    port: 0,
+  });
+
+const toContractState = (state: RuntimeState): DesktopServerExposureState => ({
+  mode: state.mode,
+  endpointUrl: Option.getOrNull(state.endpointUrl),
+  advertisedHost: Option.getOrNull(state.advertisedHost),
+  tailscaleServeEnabled: state.tailscaleServeEnabled,
+  tailscaleServePort: state.tailscaleServePort,
+});
+
+const toBackendConfig = (state: RuntimeState): DesktopServerExposureBackendConfig => ({
+  port: state.port,
+  bindHost: state.bindHost,
+  httpBaseUrl: state.httpBaseUrl,
+  tailscaleServeEnabled: state.tailscaleServeEnabled,
+  tailscaleServePort: state.tailscaleServePort,
+});
+
+const toResolvedExposure = (state: RuntimeState): ResolvedDesktopServerExposure => ({
+  mode: state.mode,
+  bindHost: state.bindHost,
+  localHttpUrl: state.localHttpUrl,
+  localWsUrl: state.localWsUrl,
+  endpointUrl: Option.getOrNull(state.endpointUrl),
+  advertisedHost: Option.getOrNull(state.advertisedHost),
+});
+
+function runtimeStateFromResolvedExposure(input: {
+  readonly requestedMode: DesktopServerExposureMode;
+  readonly settings: DesktopSettings;
+  readonly exposure: ResolvedDesktopServerExposure;
+  readonly port: number;
+}): RuntimeState {
+  return {
+    requestedMode: input.requestedMode,
+    mode: input.exposure.mode,
+    port: input.port,
+    bindHost: input.exposure.bindHost,
+    localHttpUrl: input.exposure.localHttpUrl,
+    localWsUrl: input.exposure.localWsUrl,
+    httpBaseUrl: new URL(input.exposure.localHttpUrl),
+    endpointUrl: Option.fromNullishOr(input.exposure.endpointUrl),
+    advertisedHost: Option.fromNullishOr(input.exposure.advertisedHost),
+    tailscaleServeEnabled: input.settings.tailscaleServeEnabled,
+    tailscaleServePort: input.settings.tailscaleServePort,
+  };
+}
+
+function resolveRuntimeState(input: {
+  readonly requestedMode: DesktopServerExposureMode;
+  readonly settings: DesktopSettings;
+  readonly port: number;
+  readonly networkInterfaces: DesktopNetworkInterfaces;
+  readonly advertisedHostOverride: Option.Option<string>;
+}): ResolvedRuntimeState {
+  const advertisedHostOverride = Option.getOrUndefined(input.advertisedHostOverride);
+  const requestedExposure = resolveDesktopServerExposure({
+    mode: input.requestedMode,
+    port: input.port,
+    networkInterfaces: input.networkInterfaces,
+    ...(advertisedHostOverride ? { advertisedHostOverride } : {}),
+  });
+  const unavailable =
+    input.requestedMode === "network-accessible" && requestedExposure.endpointUrl === null;
+  const exposure = unavailable
+    ? resolveDesktopServerExposure({
+        mode: "local-only",
+        port: input.port,
+        networkInterfaces: input.networkInterfaces,
+        ...(advertisedHostOverride ? { advertisedHostOverride } : {}),
+      })
+    : requestedExposure;
+
+  return {
+    state: runtimeStateFromResolvedExposure({
+      requestedMode: input.requestedMode,
+      settings: input.settings,
+      exposure,
+      port: input.port,
+    }),
+    unavailable,
+  };
+}
+
+const requiresBackendRelaunch = (previous: RuntimeState, next: RuntimeState): boolean =>
+  previous.port !== next.port ||
+  previous.bindHost !== next.bindHost ||
+  previous.localHttpUrl !== next.localHttpUrl;
+
+const make = Effect.gen(function* () {
+  const config = yield* DesktopConfig.DesktopConfig;
+  const networkInterfaces = yield* DesktopNetworkInterfacesService;
+  const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const httpClient = yield* HttpClient.HttpClient;
+  const desktopSettings = yield* DesktopAppSettingsService.DesktopAppSettings;
+  const stateRef = yield* Ref.make(initialRuntimeState());
+
+  const readNetworkInterfaces = networkInterfaces.read;
+
+  const getState = Ref.get(stateRef).pipe(Effect.map(toContractState));
+  const backendConfig = Ref.get(stateRef).pipe(Effect.map(toBackendConfig));
+
+  const configureFromSettings = Effect.fn("desktop.serverExposure.configureFromSettings")(
+    function* ({ port }: { readonly port: number }) {
+      yield* Effect.annotateCurrentSpan({ port });
+      const settings = yield* desktopSettings.get;
+      const currentNetworkInterfaces = yield* readNetworkInterfaces;
+      const resolved = resolveRuntimeState({
+        requestedMode: settings.serverExposureMode,
+        settings,
+        port,
+        networkInterfaces: currentNetworkInterfaces,
+        advertisedHostOverride: config.desktopLanHostOverride,
+      });
+      yield* Ref.set(stateRef, resolved.state);
+      return toContractState(resolved.state);
+    },
+  );
+
+  const setMode = Effect.fn("desktop.serverExposure.setMode")(function* (
+    mode: DesktopServerExposureMode,
+  ) {
+    yield* Effect.annotateCurrentSpan({ mode });
+    const previous = yield* Ref.get(stateRef);
+    const currentSettings = yield* desktopSettings.get;
+    const nextSettings = {
+      ...currentSettings,
+      serverExposureMode: mode,
+    };
+    const currentNetworkInterfaces = yield* readNetworkInterfaces;
+    const resolved = resolveRuntimeState({
+      requestedMode: mode,
+      settings: nextSettings,
+      port: previous.port,
+      networkInterfaces: currentNetworkInterfaces,
+      advertisedHostOverride: config.desktopLanHostOverride,
+    });
+
+    if (resolved.unavailable) {
+      return yield* new DesktopServerExposureNoNetworkAddressError({ port: previous.port });
+    }
+
+    const change = yield* desktopSettings.setServerExposureMode(mode).pipe(
+      Effect.mapError(
+        (cause) =>
+          new DesktopServerExposurePersistenceError({
+            operation: "server-exposure-mode",
+            cause,
+          }),
+      ),
+    );
+
+    yield* Ref.set(stateRef, resolved.state);
+    return {
+      state: toContractState(resolved.state),
+      requiresRelaunch: change.changed || requiresBackendRelaunch(previous, resolved.state),
+    };
+  });
+
+  const setTailscaleServeEnabled = Effect.fn("desktop.serverExposure.setTailscaleServeEnabled")(
+    function* (input: { readonly enabled: boolean; readonly port?: number }) {
+      yield* Effect.annotateCurrentSpan({
+        enabled: input.enabled,
+        ...(input.port === undefined ? {} : { port: input.port }),
+      });
+      const result = yield* desktopSettings
+        .setTailscaleServe({
+          enabled: input.enabled,
+          port: Option.fromNullishOr(input.port),
+        })
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new DesktopServerExposurePersistenceError({
+                operation: "tailscale-serve",
+                cause,
+              }),
+          ),
+        );
+
+      const nextState = yield* Ref.updateAndGet(stateRef, (current) => ({
+        ...current,
+        tailscaleServeEnabled: result.settings.tailscaleServeEnabled,
+        tailscaleServePort: result.settings.tailscaleServePort,
+      }));
+
+      return {
+        state: toContractState(nextState),
+        requiresRelaunch: result.changed,
+      };
+    },
+  );
+
+  const getAdvertisedEndpoints = Effect.gen(function* () {
+    const state = yield* Ref.get(stateRef);
+    const currentNetworkInterfaces = yield* readNetworkInterfaces;
+    const coreEndpoints = resolveDesktopCoreAdvertisedEndpoints({
+      port: state.port,
+      exposure: toResolvedExposure(state),
+      customHttpsEndpointUrls: config.desktopHttpsEndpointUrls,
+    });
+    const tailscaleEndpoints = yield* resolveTailscaleAdvertisedEndpoints({
+      port: state.port,
+      serveEnabled: state.tailscaleServeEnabled,
+      servePort: state.tailscaleServePort,
+      networkInterfaces: currentNetworkInterfaces,
+    }).pipe(
+      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, childProcessSpawner),
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+    );
+    return [...coreEndpoints, ...tailscaleEndpoints];
+  }).pipe(Effect.withSpan("desktop.serverExposure.getAdvertisedEndpoints"));
+
+  return DesktopServerExposure.of({
+    getState,
+    backendConfig,
+    configureFromSettings,
+    setMode,
+    setTailscaleServeEnabled,
+    getAdvertisedEndpoints,
+  });
+});
+
+export const layer = Layer.effect(DesktopServerExposure, make);
+
+export const networkInterfacesLayer = Layer.succeed(
+  DesktopNetworkInterfacesService,
+  DesktopNetworkInterfacesService.of({
+    read: Effect.sync(() => NodeOS.networkInterfaces()),
+  }),
+);
diff --git a/apps/desktop/src/backend/tailscaleEndpointProvider.test.ts b/apps/desktop/src/backend/tailscaleEndpointProvider.test.ts
new file mode 100644
index 00000000000..612ef3bd73f
--- /dev/null
+++ b/apps/desktop/src/backend/tailscaleEndpointProvider.test.ts
@@ -0,0 +1,142 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  resolveTailscaleAdvertisedEndpoints,
+} from "./tailscaleEndpointProvider.ts";
+
+const unusedTailscaleExternalServicesLayer = Layer.mergeAll(
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make(() => Effect.die("unexpected Tailscale HTTPS probe")),
+  ),
+  Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make(() => Effect.die("unexpected tailscale status process")),
+  ),
+);
+
+describe("tailscale endpoint provider", () => {
+  it("detects Tailnet IPv4 addresses", () => {
+    assert.equal(isTailscaleIpv4Address("100.64.0.1"), true);
+    assert.equal(isTailscaleIpv4Address("100.127.255.254"), true);
+    assert.equal(isTailscaleIpv4Address("100.128.0.1"), false);
+    assert.equal(isTailscaleIpv4Address("192.168.1.44"), false);
+  });
+
+  it.effect("parses MagicDNS names from tailscale status", () =>
+    Effect.gen(function* () {
+      const dnsName = yield* parseTailscaleMagicDnsName(
+        `{"Self":{"DNSName":"desktop.tail.ts.net."}}`,
+      );
+      assert.equal(dnsName, "desktop.tail.ts.net");
+      assert.equal(yield* parseTailscaleMagicDnsName("{}"), null);
+      const malformed = yield* Effect.result(parseTailscaleMagicDnsName("not-json"));
+      assert.isTrue(malformed._tag === "Failure");
+    }),
+  );
+
+  it.effect("resolves Tailscale endpoints as add-on advertised endpoints", () =>
+    Effect.gen(function* () {
+      const endpoints = yield* resolveTailscaleAdvertisedEndpoints({
+        port: 3773,
+        networkInterfaces: {
+          tailscale0: [
+            {
+              address: "100.100.100.100",
+              family: "IPv4",
+              internal: false,
+              netmask: "255.192.0.0",
+              cidr: "100.100.100.100/10",
+              mac: "00:00:00:00:00:00",
+            },
+          ],
+        },
+        statusJson: `{"Self":{"DNSName":"desktop.tail.ts.net."}}`,
+      });
+      assert.deepEqual(endpoints, [
+        {
+          id: "tailscale-ip:http://100.100.100.100:3773",
+          label: "Tailscale IP",
+          provider: {
+            id: "tailscale",
+            label: "Tailscale",
+            kind: "private-network",
+            isAddon: true,
+          },
+          httpBaseUrl: "http://100.100.100.100:3773/",
+          wsBaseUrl: "ws://100.100.100.100:3773/",
+          reachability: "private-network",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-addon",
+          status: "available",
+          description: "Reachable from devices on the same Tailnet.",
+        },
+        {
+          id: "tailscale-magicdns:https://desktop.tail.ts.net/",
+          label: "Tailscale HTTPS",
+          provider: {
+            id: "tailscale",
+            label: "Tailscale",
+            kind: "private-network",
+            isAddon: true,
+          },
+          httpBaseUrl: "https://desktop.tail.ts.net/",
+          wsBaseUrl: "wss://desktop.tail.ts.net/",
+          reachability: "private-network",
+          compatibility: {
+            hostedHttpsApp: "requires-configuration",
+            desktopApp: "compatible",
+          },
+          source: "desktop-addon",
+          status: "unavailable",
+          description: "MagicDNS hostname. Configure Tailscale Serve for HTTPS access.",
+        },
+      ]);
+    }).pipe(Effect.provide(unusedTailscaleExternalServicesLayer)),
+  );
+
+  it.effect(
+    "marks the Tailscale HTTPS endpoint available after Serve is enabled and reachable",
+    () =>
+      Effect.gen(function* () {
+        const endpoints = yield* resolveTailscaleAdvertisedEndpoints({
+          port: 3773,
+          networkInterfaces: {},
+          statusJson: `{"Self":{"DNSName":"desktop.tail.ts.net."}}`,
+          serveEnabled: true,
+          probe: () => Effect.succeed(true),
+        });
+        assert.deepEqual(endpoints, [
+          {
+            id: "tailscale-magicdns:https://desktop.tail.ts.net/",
+            label: "Tailscale HTTPS",
+            provider: {
+              id: "tailscale",
+              label: "Tailscale",
+              kind: "private-network",
+              isAddon: true,
+            },
+            httpBaseUrl: "https://desktop.tail.ts.net/",
+            wsBaseUrl: "wss://desktop.tail.ts.net/",
+            reachability: "private-network",
+            compatibility: {
+              hostedHttpsApp: "compatible",
+              desktopApp: "compatible",
+            },
+            source: "desktop-addon",
+            status: "available",
+            description: "HTTPS endpoint served by Tailscale Serve.",
+          },
+        ]);
+      }).pipe(Effect.provide(unusedTailscaleExternalServicesLayer)),
+  );
+});
diff --git a/apps/desktop/src/backend/tailscaleEndpointProvider.ts b/apps/desktop/src/backend/tailscaleEndpointProvider.ts
new file mode 100644
index 00000000000..bd46e9f03f5
--- /dev/null
+++ b/apps/desktop/src/backend/tailscaleEndpointProvider.ts
@@ -0,0 +1,138 @@
+import { createAdvertisedEndpoint } from "@t3tools/shared/advertisedEndpoint";
+import type { AdvertisedEndpoint, AdvertisedEndpointProvider } from "@t3tools/contracts";
+import {
+  buildTailscaleHttpsBaseUrl,
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  probeTailscaleHttpsEndpoint,
+  readTailscaleStatus,
+} from "@t3tools/tailscale";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import type { DesktopNetworkInterfaces } from "./DesktopServerExposure.ts";
+
+export { isTailscaleIpv4Address, parseTailscaleMagicDnsName } from "@t3tools/tailscale";
+
+const TAILSCALE_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
+  id: "tailscale",
+  label: "Tailscale",
+  kind: "private-network",
+  isAddon: true,
+};
+
+function resolveTailscaleIpAdvertisedEndpoints(input: {
+  readonly port: number;
+  readonly networkInterfaces: DesktopNetworkInterfaces;
+}): readonly AdvertisedEndpoint[] {
+  const seen = new Set<string>();
+  const endpoints: AdvertisedEndpoint[] = [];
+
+  for (const interfaceAddresses of Object.values(input.networkInterfaces)) {
+    if (!interfaceAddresses) continue;
+
+    for (const address of interfaceAddresses) {
+      if (address.internal) continue;
+      if (address.family !== "IPv4") continue;
+      if (!isTailscaleIpv4Address(address.address)) continue;
+      if (seen.has(address.address)) continue;
+      seen.add(address.address);
+
+      endpoints.push(
+        createAdvertisedEndpoint({
+          provider: TAILSCALE_ENDPOINT_PROVIDER,
+          source: "desktop-addon",
+          id: `tailscale-ip:http://${address.address}:${input.port}`,
+          label: "Tailscale IP",
+          httpBaseUrl: `http://${address.address}:${input.port}`,
+          reachability: "private-network",
+          status: "available",
+          description: "Reachable from devices on the same Tailnet.",
+        }),
+      );
+    }
+  }
+
+  return endpoints;
+}
+
+const resolveTailscaleMagicDnsAdvertisedEndpoint = Effect.fn(
+  "resolveTailscaleMagicDnsAdvertisedEndpoint",
+)(function* (input: {
+  readonly dnsName: string | null;
+  readonly serveEnabled: boolean;
+  readonly servePort?: number;
+  readonly probe?: (baseUrl: string) => Effect.Effect<boolean, never, HttpClient.HttpClient>;
+}): Effect.fn.Return<Option.Option<AdvertisedEndpoint>, never, HttpClient.HttpClient> {
+  if (!input.dnsName) {
+    return Option.none();
+  }
+
+  const httpBaseUrl = buildTailscaleHttpsBaseUrl({
+    magicDnsName: input.dnsName,
+    ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+  });
+  const probe =
+    input.probe?.(httpBaseUrl) ??
+    probeTailscaleHttpsEndpoint({
+      baseUrl: httpBaseUrl,
+    });
+  const isReachable = input.serveEnabled ? yield* probe : false;
+
+  return Option.some(
+    createAdvertisedEndpoint({
+      provider: TAILSCALE_ENDPOINT_PROVIDER,
+      source: "desktop-addon",
+      id: `tailscale-magicdns:${httpBaseUrl}`,
+      label: "Tailscale HTTPS",
+      httpBaseUrl,
+      reachability: "private-network",
+      hostedHttpsCompatibility: isReachable ? "compatible" : "requires-configuration",
+      status: isReachable ? "available" : "unavailable",
+      description: isReachable
+        ? "HTTPS endpoint served by Tailscale Serve."
+        : "MagicDNS hostname. Configure Tailscale Serve for HTTPS access.",
+    }),
+  );
+});
+
+export const resolveTailscaleAdvertisedEndpoints = Effect.fn("resolveTailscaleAdvertisedEndpoints")(
+  function* (input: {
+    readonly port: number;
+    readonly serveEnabled?: boolean;
+    readonly servePort?: number;
+    readonly networkInterfaces: DesktopNetworkInterfaces;
+    readonly statusJson?: string | null;
+    readonly probe?: (baseUrl: string) => Effect.Effect<boolean, never, HttpClient.HttpClient>;
+  }): Effect.fn.Return<
+    readonly AdvertisedEndpoint[],
+    never,
+    ChildProcessSpawner.ChildProcessSpawner | HttpClient.HttpClient
+  > {
+    const ipEndpoints = resolveTailscaleIpAdvertisedEndpoints(input);
+    const dnsName =
+      input.statusJson === undefined
+        ? yield* readTailscaleStatus.pipe(
+            Effect.map((status) => status.magicDnsName),
+            Effect.catch(() => Effect.succeed(null)),
+          )
+        : input.statusJson
+          ? yield* parseTailscaleMagicDnsName(input.statusJson).pipe(
+              Effect.catch(() => Effect.succeed(null)),
+            )
+          : null;
+    const magicDnsEndpoint = yield* resolveTailscaleMagicDnsAdvertisedEndpoint({
+      dnsName,
+      serveEnabled: input.serveEnabled === true,
+      ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+      ...(input.probe === undefined ? {} : { probe: input.probe }),
+    });
+
+    return Option.match(magicDnsEndpoint, {
+      onNone: () => ipEndpoints,
+      onSome: (endpoint) => [...ipEndpoints, endpoint],
+    });
+  },
+);
diff --git a/apps/desktop/src/backendPort.test.ts b/apps/desktop/src/backendPort.test.ts
deleted file mode 100644
index 8f586deb702..00000000000
--- a/apps/desktop/src/backendPort.test.ts
+++ /dev/null
@@ -1,109 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { resolveDesktopBackendPort } from "./backendPort";
-
-describe("resolveDesktopBackendPort", () => {
-  it("returns the starting port when it is available", async () => {
-    const canListenOnHost = vi.fn(async (port: number) => port === 3773);
-
-    await expect(
-      resolveDesktopBackendPort({
-        host: "127.0.0.1",
-        startPort: 3773,
-        canListenOnHost,
-      }),
-    ).resolves.toBe(3773);
-
-    expect(canListenOnHost).toHaveBeenCalledTimes(1);
-    expect(canListenOnHost).toHaveBeenCalledWith(3773, "127.0.0.1");
-  });
-
-  it("increments sequentially until it finds an available port", async () => {
-    const canListenOnHost = vi.fn(async (port: number) => port === 3775);
-
-    await expect(
-      resolveDesktopBackendPort({
-        host: "127.0.0.1",
-        startPort: 3773,
-        canListenOnHost,
-      }),
-    ).resolves.toBe(3775);
-
-    expect(canListenOnHost.mock.calls).toEqual([
-      [3773, "127.0.0.1"],
-      [3774, "127.0.0.1"],
-      [3775, "127.0.0.1"],
-    ]);
-  });
-
-  it("treats wildcard-bound ports as unavailable even when loopback probing succeeds", async () => {
-    const canListenOnHost = vi.fn(async (port: number, host: string) => {
-      if (port === 3773 && host === "127.0.0.1") return true;
-      if (port === 3773 && host === "0.0.0.0") return false;
-      return port === 3774;
-    });
-
-    await expect(
-      resolveDesktopBackendPort({
-        host: "127.0.0.1",
-        requiredHosts: ["0.0.0.0"],
-        startPort: 3773,
-        canListenOnHost,
-      }),
-    ).resolves.toBe(3774);
-
-    expect(canListenOnHost.mock.calls).toEqual([
-      [3773, "127.0.0.1"],
-      [3773, "0.0.0.0"],
-      [3774, "127.0.0.1"],
-      [3774, "0.0.0.0"],
-    ]);
-  });
-
-  it("checks overlapping hosts sequentially to avoid self-interference", async () => {
-    let inFlightCount = 0;
-    const canListenOnHost = vi.fn(async (_port: number, _host: string) => {
-      inFlightCount += 1;
-      const overlapped = inFlightCount > 1;
-      await Promise.resolve();
-      inFlightCount -= 1;
-      return !overlapped;
-    });
-
-    await expect(
-      resolveDesktopBackendPort({
-        host: "127.0.0.1",
-        requiredHosts: ["0.0.0.0", "::"],
-        startPort: 3773,
-        maxPort: 3773,
-        canListenOnHost,
-      }),
-    ).resolves.toBe(3773);
-
-    expect(canListenOnHost.mock.calls).toEqual([
-      [3773, "127.0.0.1"],
-      [3773, "0.0.0.0"],
-      [3773, "::"],
-    ]);
-  });
-
-  it("fails when the scan range is exhausted", async () => {
-    const canListenOnHost = vi.fn(async () => false);
-
-    await expect(
-      resolveDesktopBackendPort({
-        host: "127.0.0.1",
-        startPort: 65534,
-        maxPort: 65535,
-        canListenOnHost,
-      }),
-    ).rejects.toThrow(
-      "No desktop backend port is available on hosts 127.0.0.1 between 65534 and 65535",
-    );
-
-    expect(canListenOnHost.mock.calls).toEqual([
-      [65534, "127.0.0.1"],
-      [65535, "127.0.0.1"],
-    ]);
-  });
-});
diff --git a/apps/desktop/src/backendPort.ts b/apps/desktop/src/backendPort.ts
deleted file mode 100644
index 1ce90a257fa..00000000000
--- a/apps/desktop/src/backendPort.ts
+++ /dev/null
@@ -1,83 +0,0 @@
-import * as Effect from "effect/Effect";
-import { NetService } from "@t3tools/shared/Net";
-
-export const DEFAULT_DESKTOP_BACKEND_PORT = 3773;
-const MAX_TCP_PORT = 65_535;
-
-export interface ResolveDesktopBackendPortOptions {
-  readonly host: string;
-  readonly startPort?: number;
-  readonly maxPort?: number;
-  readonly requiredHosts?: ReadonlyArray<string>;
-  readonly canListenOnHost?: (port: number, host: string) => Promise<boolean>;
-}
-
-const defaultCanListenOnHost = async (port: number, host: string): Promise<boolean> =>
-  Effect.service(NetService).pipe(
-    Effect.flatMap((net) => net.canListenOnHost(port, host)),
-    Effect.provide(NetService.layer),
-    Effect.runPromise,
-  );
-
-const isValidPort = (port: number): boolean =>
-  Number.isInteger(port) && port >= 1 && port <= MAX_TCP_PORT;
-
-const normalizeHosts = (
-  host: string,
-  requiredHosts: ReadonlyArray<string>,
-): ReadonlyArray<string> =>
-  Array.from(
-    new Set(
-      [host, ...requiredHosts]
-        .map((candidate) => candidate.trim())
-        .filter((candidate) => candidate.length > 0),
-    ),
-  );
-
-async function canListenOnAllHosts(
-  port: number,
-  hosts: ReadonlyArray<string>,
-  canListenOnHost: (port: number, host: string) => Promise<boolean>,
-): Promise<boolean> {
-  for (const candidateHost of hosts) {
-    if (!(await canListenOnHost(port, candidateHost))) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-export async function resolveDesktopBackendPort({
-  host,
-  startPort = DEFAULT_DESKTOP_BACKEND_PORT,
-  maxPort = MAX_TCP_PORT,
-  requiredHosts = [],
-  canListenOnHost = defaultCanListenOnHost,
-}: ResolveDesktopBackendPortOptions): Promise<number> {
-  if (!isValidPort(startPort)) {
-    throw new Error(`Invalid desktop backend start port: ${startPort}`);
-  }
-
-  if (!isValidPort(maxPort)) {
-    throw new Error(`Invalid desktop backend max port: ${maxPort}`);
-  }
-
-  if (maxPort < startPort) {
-    throw new Error(`Desktop backend max port ${maxPort} is below start port ${startPort}`);
-  }
-
-  const hostsToCheck = normalizeHosts(host, requiredHosts);
-
-  // Keep desktop startup predictable across app restarts by probing upward from
-  // the same preferred port instead of picking a fresh ephemeral port.
-  for (let port = startPort; port <= maxPort; port += 1) {
-    if (await canListenOnAllHosts(port, hostsToCheck, canListenOnHost)) {
-      return port;
-    }
-  }
-
-  throw new Error(
-    `No desktop backend port is available on hosts ${hostsToCheck.join(", ")} between ${startPort} and ${maxPort}`,
-  );
-}
diff --git a/apps/desktop/src/backendReadiness.test.ts b/apps/desktop/src/backendReadiness.test.ts
deleted file mode 100644
index fd6180b5dac..00000000000
--- a/apps/desktop/src/backendReadiness.test.ts
+++ /dev/null
@@ -1,83 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  BackendReadinessAbortedError,
-  isBackendReadinessAborted,
-  waitForHttpReady,
-} from "./backendReadiness";
-
-describe("waitForHttpReady", () => {
-  it("returns once the backend reports a successful session endpoint", async () => {
-    const fetchImpl = vi
-      .fn<typeof fetch>()
-      .mockResolvedValueOnce(new Response(null, { status: 503 }))
-      .mockResolvedValueOnce(new Response(null, { status: 200 }));
-
-    await waitForHttpReady("http://127.0.0.1:3773", {
-      fetchImpl,
-      timeoutMs: 1_000,
-      intervalMs: 0,
-    });
-
-    expect(fetchImpl).toHaveBeenCalledTimes(2);
-  });
-
-  it("retries after a readiness request stalls past the per-request timeout", async () => {
-    const fetchImpl = vi
-      .fn<typeof fetch>()
-      .mockImplementationOnce(
-        (_input, init) =>
-          new Promise((_resolve, reject) => {
-            init?.signal?.addEventListener(
-              "abort",
-              () => {
-                reject(new Error("request timed out"));
-              },
-              { once: true },
-            );
-          }) as ReturnType<typeof fetch>,
-      )
-      .mockResolvedValueOnce(new Response(null, { status: 200 }));
-
-    await waitForHttpReady("http://127.0.0.1:3773", {
-      fetchImpl,
-      timeoutMs: 100,
-      intervalMs: 0,
-      requestTimeoutMs: 1,
-    });
-
-    expect(fetchImpl).toHaveBeenCalledTimes(2);
-  });
-
-  it("aborts an in-flight readiness wait", async () => {
-    const controller = new AbortController();
-    const fetchImpl = vi.fn<typeof fetch>().mockImplementation(
-      () =>
-        new Promise((_resolve, reject) => {
-          controller.signal.addEventListener(
-            "abort",
-            () => {
-              reject(new BackendReadinessAbortedError());
-            },
-            { once: true },
-          );
-        }) as ReturnType<typeof fetch>,
-    );
-
-    const waitPromise = waitForHttpReady("http://127.0.0.1:3773", {
-      fetchImpl,
-      timeoutMs: 1_000,
-      intervalMs: 0,
-      signal: controller.signal,
-    });
-
-    controller.abort();
-
-    await expect(waitPromise).rejects.toBeInstanceOf(BackendReadinessAbortedError);
-  });
-
-  it("recognizes aborted readiness errors", () => {
-    expect(isBackendReadinessAborted(new BackendReadinessAbortedError())).toBe(true);
-    expect(isBackendReadinessAborted(new Error("nope"))).toBe(false);
-  });
-});
diff --git a/apps/desktop/src/backendReadiness.ts b/apps/desktop/src/backendReadiness.ts
deleted file mode 100644
index cd5a3c023ef..00000000000
--- a/apps/desktop/src/backendReadiness.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-export interface WaitForHttpReadyOptions {
-  readonly timeoutMs?: number;
-  readonly intervalMs?: number;
-  readonly requestTimeoutMs?: number;
-  readonly fetchImpl?: typeof fetch;
-  readonly signal?: AbortSignal;
-}
-
-const DEFAULT_TIMEOUT_MS = 10_000;
-const DEFAULT_INTERVAL_MS = 100;
-const DEFAULT_REQUEST_TIMEOUT_MS = 1_000;
-
-export class BackendReadinessAbortedError extends Error {
-  constructor() {
-    super("Backend readiness wait was aborted.");
-    this.name = "BackendReadinessAbortedError";
-  }
-}
-
-function delay(ms: number, signal: AbortSignal | undefined): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      cleanup();
-      resolve();
-    }, ms);
-
-    const onAbort = () => {
-      cleanup();
-      reject(new BackendReadinessAbortedError());
-    };
-
-    const cleanup = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-    };
-
-    if (signal?.aborted) {
-      cleanup();
-      reject(new BackendReadinessAbortedError());
-      return;
-    }
-
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-export function isBackendReadinessAborted(error: unknown): error is BackendReadinessAbortedError {
-  return error instanceof BackendReadinessAbortedError;
-}
-
-export async function waitForHttpReady(
-  baseUrl: string,
-  options?: WaitForHttpReadyOptions,
-): Promise<void> {
-  const fetchImpl = options?.fetchImpl ?? fetch;
-  const signal = options?.signal;
-  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const intervalMs = options?.intervalMs ?? DEFAULT_INTERVAL_MS;
-  const requestTimeoutMs = options?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-  const deadline = Date.now() + timeoutMs;
-
-  for (;;) {
-    if (signal?.aborted) {
-      throw new BackendReadinessAbortedError();
-    }
-
-    const requestController = new AbortController();
-    const requestTimeout = setTimeout(() => {
-      requestController.abort();
-    }, requestTimeoutMs);
-    const abortRequest = () => {
-      requestController.abort();
-    };
-    signal?.addEventListener("abort", abortRequest, { once: true });
-
-    try {
-      const response = await fetchImpl(`${baseUrl}/api/auth/session`, {
-        redirect: "manual",
-        signal: requestController.signal,
-      });
-      if (response.ok) {
-        return;
-      }
-    } catch (error) {
-      if (isBackendReadinessAborted(error)) {
-        throw error;
-      }
-      if (signal?.aborted) {
-        throw new BackendReadinessAbortedError();
-      }
-      // Retry until the backend becomes reachable or the deadline expires.
-    } finally {
-      clearTimeout(requestTimeout);
-      signal?.removeEventListener("abort", abortRequest);
-    }
-
-    if (Date.now() >= deadline) {
-      throw new Error(`Timed out waiting for backend readiness at ${baseUrl}.`);
-    }
-
-    await delay(intervalMs, signal);
-  }
-}
diff --git a/apps/desktop/src/clientPersistence.test.ts b/apps/desktop/src/clientPersistence.test.ts
deleted file mode 100644
index df2178c0b0d..00000000000
--- a/apps/desktop/src/clientPersistence.test.ts
+++ /dev/null
@@ -1,234 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import {
-  EnvironmentId,
-  type ClientSettings,
-  type PersistedSavedEnvironmentRecord,
-} from "@t3tools/contracts";
-import { afterEach, describe, expect, it } from "vitest";
-
-import {
-  readClientSettings,
-  readSavedEnvironmentRegistry,
-  readSavedEnvironmentSecret,
-  removeSavedEnvironmentSecret,
-  writeClientSettings,
-  writeSavedEnvironmentRegistry,
-  writeSavedEnvironmentSecret,
-  type DesktopSecretStorage,
-} from "./clientPersistence";
-
-const tempDirectories: string[] = [];
-
-afterEach(() => {
-  for (const directory of tempDirectories.splice(0)) {
-    fs.rmSync(directory, { recursive: true, force: true });
-  }
-});
-
-function makeTempPath(fileName: string): string {
-  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "t3-client-persistence-test-"));
-  tempDirectories.push(directory);
-  return path.join(directory, fileName);
-}
-
-function makeSecretStorage(available: boolean): DesktopSecretStorage {
-  return {
-    isEncryptionAvailable: () => available,
-    encryptString: (value) => Buffer.from(`enc:${value}`, "utf8"),
-    decryptString: (value) => {
-      const decoded = value.toString("utf8");
-      if (!decoded.startsWith("enc:")) {
-        throw new Error("invalid secret");
-      }
-      return decoded.slice("enc:".length);
-    },
-  };
-}
-
-const clientSettings: ClientSettings = {
-  confirmThreadArchive: true,
-  confirmThreadDelete: false,
-  diffWordWrap: true,
-  sidebarProjectSortOrder: "manual",
-  sidebarThreadSortOrder: "created_at",
-  timestampFormat: "24-hour",
-};
-
-const savedRegistryRecord: PersistedSavedEnvironmentRecord = {
-  environmentId: EnvironmentId.make("environment-1"),
-  label: "Remote environment",
-  httpBaseUrl: "https://remote.example.com/",
-  wsBaseUrl: "wss://remote.example.com/",
-  createdAt: "2026-04-09T00:00:00.000Z",
-  lastConnectedAt: "2026-04-09T01:00:00.000Z",
-};
-
-describe("clientPersistence", () => {
-  it("persists and reloads client settings", () => {
-    const settingsPath = makeTempPath("client-settings.json");
-
-    writeClientSettings(settingsPath, clientSettings);
-
-    expect(readClientSettings(settingsPath)).toEqual(clientSettings);
-  });
-
-  it("persists and reloads saved environment metadata", () => {
-    const registryPath = makeTempPath("saved-environments.json");
-
-    writeSavedEnvironmentRegistry(registryPath, [savedRegistryRecord]);
-
-    expect(readSavedEnvironmentRegistry(registryPath)).toEqual([savedRegistryRecord]);
-  });
-
-  it("persists encrypted saved environment secrets when encryption is available", () => {
-    const registryPath = makeTempPath("saved-environments.json");
-    const secretStorage = makeSecretStorage(true);
-
-    writeSavedEnvironmentRegistry(registryPath, [savedRegistryRecord]);
-
-    expect(
-      writeSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secret: "bearer-token",
-        secretStorage,
-      }),
-    ).toBe(true);
-
-    expect(
-      readSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secretStorage,
-      }),
-    ).toBe("bearer-token");
-
-    expect(JSON.parse(fs.readFileSync(registryPath, "utf8"))).toEqual({
-      records: [
-        {
-          ...savedRegistryRecord,
-          encryptedBearerToken: Buffer.from("enc:bearer-token", "utf8").toString("base64"),
-        },
-      ],
-    });
-  });
-
-  it("preserves existing secrets when encryption is unavailable", () => {
-    const registryPath = makeTempPath("saved-environments.json");
-    const availableSecretStorage = makeSecretStorage(true);
-
-    writeSavedEnvironmentRegistry(registryPath, [savedRegistryRecord]);
-
-    writeSavedEnvironmentSecret({
-      registryPath,
-      environmentId: savedRegistryRecord.environmentId,
-      secret: "bearer-token",
-      secretStorage: availableSecretStorage,
-    });
-
-    expect(
-      writeSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secret: "next-token",
-        secretStorage: makeSecretStorage(false),
-      }),
-    ).toBe(false);
-
-    expect(
-      readSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secretStorage: availableSecretStorage,
-      }),
-    ).toBe("bearer-token");
-  });
-
-  it("removes saved environment secrets", () => {
-    const registryPath = makeTempPath("saved-environments.json");
-    const secretStorage = makeSecretStorage(true);
-
-    writeSavedEnvironmentRegistry(registryPath, [savedRegistryRecord]);
-
-    writeSavedEnvironmentSecret({
-      registryPath,
-      environmentId: savedRegistryRecord.environmentId,
-      secret: "bearer-token",
-      secretStorage,
-    });
-
-    removeSavedEnvironmentSecret({
-      registryPath,
-      environmentId: savedRegistryRecord.environmentId,
-    });
-
-    expect(
-      readSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secretStorage,
-      }),
-    ).toBeNull();
-  });
-
-  it("treats malformed secrets documents as empty", () => {
-    const registryPath = makeTempPath("saved-environments.json");
-    fs.writeFileSync(registryPath, "{}\n", "utf8");
-
-    expect(
-      readSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secretStorage: makeSecretStorage(true),
-      }),
-    ).toBeNull();
-
-    expect(() =>
-      removeSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-      }),
-    ).not.toThrow();
-  });
-
-  it("returns false when writing a secret without metadata", () => {
-    const registryPath = makeTempPath("saved-environments.json");
-
-    expect(
-      writeSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secret: "bearer-token",
-        secretStorage: makeSecretStorage(true),
-      }),
-    ).toBe(false);
-  });
-
-  it("preserves encrypted secrets when metadata is rewritten", () => {
-    const registryPath = makeTempPath("saved-environments.json");
-    const secretStorage = makeSecretStorage(true);
-
-    writeSavedEnvironmentRegistry(registryPath, [savedRegistryRecord]);
-
-    writeSavedEnvironmentSecret({
-      registryPath,
-      environmentId: savedRegistryRecord.environmentId,
-      secret: "bearer-token",
-      secretStorage,
-    });
-
-    writeSavedEnvironmentRegistry(registryPath, [savedRegistryRecord]);
-
-    expect(readSavedEnvironmentRegistry(registryPath)).toEqual([savedRegistryRecord]);
-    expect(
-      readSavedEnvironmentSecret({
-        registryPath,
-        environmentId: savedRegistryRecord.environmentId,
-        secretStorage,
-      }),
-    ).toBe("bearer-token");
-  });
-});
diff --git a/apps/desktop/src/clientPersistence.ts b/apps/desktop/src/clientPersistence.ts
deleted file mode 100644
index 183de1a971b..00000000000
--- a/apps/desktop/src/clientPersistence.ts
+++ /dev/null
@@ -1,216 +0,0 @@
-import * as FS from "node:fs";
-import * as Path from "node:path";
-
-import type { ClientSettings, PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
-import { Predicate } from "effect";
-
-interface ClientSettingsDocument {
-  readonly settings: ClientSettings;
-}
-
-interface PersistedSavedEnvironmentStorageRecord extends PersistedSavedEnvironmentRecord {
-  readonly encryptedBearerToken?: string;
-}
-
-interface SavedEnvironmentRegistryDocument {
-  readonly records: readonly PersistedSavedEnvironmentStorageRecord[];
-}
-
-export interface DesktopSecretStorage {
-  readonly isEncryptionAvailable: () => boolean;
-  readonly encryptString: (value: string) => Buffer;
-  readonly decryptString: (value: Buffer) => string;
-}
-
-function readJsonFile<T>(filePath: string): T | null {
-  try {
-    if (!FS.existsSync(filePath)) {
-      return null;
-    }
-    return JSON.parse(FS.readFileSync(filePath, "utf8")) as T;
-  } catch {
-    return null;
-  }
-}
-
-function writeJsonFile(filePath: string, value: unknown): void {
-  const directory = Path.dirname(filePath);
-  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  FS.mkdirSync(directory, { recursive: true });
-  FS.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-  FS.renameSync(tempPath, filePath);
-}
-
-function isPersistedSavedEnvironmentStorageRecord(
-  value: unknown,
-): value is PersistedSavedEnvironmentStorageRecord {
-  return (
-    Predicate.isObject(value) &&
-    typeof value.environmentId === "string" &&
-    typeof value.label === "string" &&
-    typeof value.httpBaseUrl === "string" &&
-    typeof value.wsBaseUrl === "string" &&
-    typeof value.createdAt === "string" &&
-    (value.lastConnectedAt === null || typeof value.lastConnectedAt === "string") &&
-    (value.encryptedBearerToken === undefined || typeof value.encryptedBearerToken === "string")
-  );
-}
-
-function readSavedEnvironmentRegistryDocument(filePath: string): SavedEnvironmentRegistryDocument {
-  const parsed = readJsonFile<SavedEnvironmentRegistryDocument>(filePath);
-  if (!Predicate.isObject(parsed)) {
-    return { records: [] };
-  }
-
-  return {
-    records: Array.isArray(parsed.records)
-      ? parsed.records.filter(isPersistedSavedEnvironmentStorageRecord)
-      : [],
-  };
-}
-
-function toPersistedSavedEnvironmentRecord(
-  record: PersistedSavedEnvironmentStorageRecord,
-): PersistedSavedEnvironmentRecord {
-  return {
-    environmentId: record.environmentId,
-    label: record.label,
-    httpBaseUrl: record.httpBaseUrl,
-    wsBaseUrl: record.wsBaseUrl,
-    createdAt: record.createdAt,
-    lastConnectedAt: record.lastConnectedAt,
-  };
-}
-
-export function readClientSettings(settingsPath: string): ClientSettings | null {
-  return readJsonFile<ClientSettingsDocument>(settingsPath)?.settings ?? null;
-}
-
-export function writeClientSettings(settingsPath: string, settings: ClientSettings): void {
-  writeJsonFile(settingsPath, { settings } satisfies ClientSettingsDocument);
-}
-
-export function readSavedEnvironmentRegistry(
-  registryPath: string,
-): readonly PersistedSavedEnvironmentRecord[] {
-  return readSavedEnvironmentRegistryDocument(registryPath).records.map((record) =>
-    toPersistedSavedEnvironmentRecord(record),
-  );
-}
-
-export function writeSavedEnvironmentRegistry(
-  registryPath: string,
-  records: readonly PersistedSavedEnvironmentRecord[],
-): void {
-  const currentDocument = readSavedEnvironmentRegistryDocument(registryPath);
-  const encryptedBearerTokenById = new Map(
-    currentDocument.records.flatMap((record) =>
-      record.encryptedBearerToken
-        ? [[record.environmentId, record.encryptedBearerToken] as const]
-        : [],
-    ),
-  );
-  writeJsonFile(registryPath, {
-    records: records.map((record) => {
-      const encryptedBearerToken = encryptedBearerTokenById.get(record.environmentId);
-      return encryptedBearerToken
-        ? {
-            environmentId: record.environmentId,
-            label: record.label,
-            httpBaseUrl: record.httpBaseUrl,
-            wsBaseUrl: record.wsBaseUrl,
-            createdAt: record.createdAt,
-            lastConnectedAt: record.lastConnectedAt,
-            encryptedBearerToken,
-          }
-        : record;
-    }),
-  } satisfies SavedEnvironmentRegistryDocument);
-}
-
-export function readSavedEnvironmentSecret(input: {
-  readonly registryPath: string;
-  readonly environmentId: string;
-  readonly secretStorage: DesktopSecretStorage;
-}): string | null {
-  const document = readSavedEnvironmentRegistryDocument(input.registryPath);
-  const encoded = document.records.find(
-    (record) => record.environmentId === input.environmentId,
-  )?.encryptedBearerToken;
-  if (!encoded) {
-    return null;
-  }
-
-  if (!input.secretStorage.isEncryptionAvailable()) {
-    return null;
-  }
-
-  try {
-    return input.secretStorage.decryptString(Buffer.from(encoded, "base64"));
-  } catch {
-    return null;
-  }
-}
-
-export function writeSavedEnvironmentSecret(input: {
-  readonly registryPath: string;
-  readonly environmentId: string;
-  readonly secret: string;
-  readonly secretStorage: DesktopSecretStorage;
-}): boolean {
-  const document = readSavedEnvironmentRegistryDocument(input.registryPath);
-
-  if (!input.secretStorage.isEncryptionAvailable()) {
-    return false;
-  }
-
-  let found = false;
-
-  writeJsonFile(input.registryPath, {
-    records: document.records.map((record) => {
-      if (record.environmentId !== input.environmentId) {
-        return record;
-      }
-
-      found = true;
-      const encryptedBearerToken = input.secretStorage
-        .encryptString(input.secret)
-        .toString("base64");
-      return {
-        environmentId: record.environmentId,
-        label: record.label,
-        httpBaseUrl: record.httpBaseUrl,
-        wsBaseUrl: record.wsBaseUrl,
-        createdAt: record.createdAt,
-        lastConnectedAt: record.lastConnectedAt,
-        encryptedBearerToken,
-      } satisfies PersistedSavedEnvironmentStorageRecord;
-    }),
-  } satisfies SavedEnvironmentRegistryDocument);
-  return found;
-}
-
-export function removeSavedEnvironmentSecret(input: {
-  readonly registryPath: string;
-  readonly environmentId: string;
-}): void {
-  const document = readSavedEnvironmentRegistryDocument(input.registryPath);
-  if (
-    !document.records.some(
-      (record) =>
-        record.environmentId === input.environmentId && record.encryptedBearerToken !== undefined,
-    )
-  ) {
-    return;
-  }
-
-  writeJsonFile(input.registryPath, {
-    records: document.records.map((record) => {
-      if (record.environmentId !== input.environmentId) {
-        return record;
-      }
-
-      return toPersistedSavedEnvironmentRecord(record);
-    }),
-  } satisfies SavedEnvironmentRegistryDocument);
-}
diff --git a/apps/desktop/src/confirmDialog.test.ts b/apps/desktop/src/confirmDialog.test.ts
deleted file mode 100644
index 4a4c0ddbed6..00000000000
--- a/apps/desktop/src/confirmDialog.test.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import type { BrowserWindow } from "electron";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const { showMessageBoxMock } = vi.hoisted(() => ({
-  showMessageBoxMock: vi.fn(),
-}));
-
-vi.mock("electron", () => ({
-  dialog: {
-    showMessageBox: showMessageBoxMock,
-  },
-}));
-
-import { showDesktopConfirmDialog } from "./confirmDialog";
-
-describe("showDesktopConfirmDialog", () => {
-  beforeEach(() => {
-    showMessageBoxMock.mockReset();
-  });
-
-  it("returns false and does not open a dialog for empty messages", async () => {
-    const result = await showDesktopConfirmDialog("   ", null);
-
-    expect(result).toBe(false);
-    expect(showMessageBoxMock).not.toHaveBeenCalled();
-  });
-
-  it("opens a dialog for the focused window and returns true on confirm", async () => {
-    const ownerWindow = { id: 1 } as BrowserWindow;
-    showMessageBoxMock.mockResolvedValue({ response: 1 });
-
-    const result = await showDesktopConfirmDialog("Delete worktree?", ownerWindow);
-
-    expect(result).toBe(true);
-    expect(showMessageBoxMock).toHaveBeenCalledWith(
-      ownerWindow,
-      expect.objectContaining({
-        buttons: ["No", "Yes"],
-        message: "Delete worktree?",
-      }),
-    );
-  });
-
-  it("opens an app-level dialog when there is no focused window", async () => {
-    showMessageBoxMock.mockResolvedValue({ response: 0 });
-
-    const result = await showDesktopConfirmDialog("Delete worktree?", null);
-
-    expect(result).toBe(false);
-    expect(showMessageBoxMock).toHaveBeenCalledWith(
-      expect.objectContaining({
-        buttons: ["No", "Yes"],
-        message: "Delete worktree?",
-      }),
-    );
-  });
-});
diff --git a/apps/desktop/src/confirmDialog.ts b/apps/desktop/src/confirmDialog.ts
deleted file mode 100644
index c941d090652..00000000000
--- a/apps/desktop/src/confirmDialog.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { type BrowserWindow, dialog } from "electron";
-
-const CONFIRM_BUTTON_INDEX = 1;
-
-export async function showDesktopConfirmDialog(
-  message: string,
-  ownerWindow: BrowserWindow | null,
-): Promise<boolean> {
-  const normalizedMessage = message.trim();
-  if (normalizedMessage.length === 0) {
-    return false;
-  }
-
-  const options = {
-    type: "question" as const,
-    buttons: ["No", "Yes"],
-    defaultId: 0,
-    cancelId: 0,
-    noLink: true,
-    message: normalizedMessage,
-  };
-  const result = ownerWindow
-    ? await dialog.showMessageBox(ownerWindow, options)
-    : await dialog.showMessageBox(options);
-  return result.response === CONFIRM_BUTTON_INDEX;
-}
diff --git a/apps/desktop/src/desktopSettings.test.ts b/apps/desktop/src/desktopSettings.test.ts
deleted file mode 100644
index e687bf544eb..00000000000
--- a/apps/desktop/src/desktopSettings.test.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { afterEach, describe, expect, it } from "vitest";
-
-import {
-  DEFAULT_DESKTOP_SETTINGS,
-  readDesktopSettings,
-  setDesktopServerExposurePreference,
-  writeDesktopSettings,
-} from "./desktopSettings";
-
-const tempDirectories: string[] = [];
-
-afterEach(() => {
-  for (const directory of tempDirectories.splice(0)) {
-    fs.rmSync(directory, { recursive: true, force: true });
-  }
-});
-
-function makeSettingsPath() {
-  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "t3-desktop-settings-test-"));
-  tempDirectories.push(directory);
-  return path.join(directory, "desktop-settings.json");
-}
-
-describe("desktopSettings", () => {
-  it("returns defaults when no settings file exists", () => {
-    expect(readDesktopSettings(makeSettingsPath())).toEqual(DEFAULT_DESKTOP_SETTINGS);
-  });
-
-  it("persists and reloads the configured server exposure mode", () => {
-    const settingsPath = makeSettingsPath();
-
-    writeDesktopSettings(settingsPath, {
-      serverExposureMode: "network-accessible",
-    });
-
-    expect(readDesktopSettings(settingsPath)).toEqual({
-      serverExposureMode: "network-accessible",
-    });
-  });
-
-  it("preserves the requested network-accessible preference across temporary fallback", () => {
-    expect(
-      setDesktopServerExposurePreference(
-        {
-          serverExposureMode: "local-only",
-        },
-        "network-accessible",
-      ),
-    ).toEqual({
-      serverExposureMode: "network-accessible",
-    });
-  });
-
-  it("falls back to defaults when the settings file is malformed", () => {
-    const settingsPath = makeSettingsPath();
-    fs.writeFileSync(settingsPath, "{not-json", "utf8");
-
-    expect(readDesktopSettings(settingsPath)).toEqual(DEFAULT_DESKTOP_SETTINGS);
-  });
-});
diff --git a/apps/desktop/src/desktopSettings.ts b/apps/desktop/src/desktopSettings.ts
deleted file mode 100644
index 80ef229ea23..00000000000
--- a/apps/desktop/src/desktopSettings.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import * as FS from "node:fs";
-import * as Path from "node:path";
-import type { DesktopServerExposureMode } from "@t3tools/contracts";
-
-export interface DesktopSettings {
-  readonly serverExposureMode: DesktopServerExposureMode;
-}
-
-export const DEFAULT_DESKTOP_SETTINGS: DesktopSettings = {
-  serverExposureMode: "local-only",
-};
-
-export function setDesktopServerExposurePreference(
-  settings: DesktopSettings,
-  requestedMode: DesktopServerExposureMode,
-): DesktopSettings {
-  return settings.serverExposureMode === requestedMode
-    ? settings
-    : {
-        ...settings,
-        serverExposureMode: requestedMode,
-      };
-}
-
-export function readDesktopSettings(settingsPath: string): DesktopSettings {
-  try {
-    if (!FS.existsSync(settingsPath)) {
-      return DEFAULT_DESKTOP_SETTINGS;
-    }
-
-    const raw = FS.readFileSync(settingsPath, "utf8");
-    const parsed = JSON.parse(raw) as {
-      readonly serverExposureMode?: unknown;
-    };
-
-    return {
-      serverExposureMode:
-        parsed.serverExposureMode === "network-accessible" ? "network-accessible" : "local-only",
-    };
-  } catch {
-    return DEFAULT_DESKTOP_SETTINGS;
-  }
-}
-
-export function writeDesktopSettings(settingsPath: string, settings: DesktopSettings): void {
-  const directory = Path.dirname(settingsPath);
-  const tempPath = `${settingsPath}.${process.pid}.${Date.now()}.tmp`;
-  FS.mkdirSync(directory, { recursive: true });
-  FS.writeFileSync(tempPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
-  FS.renameSync(tempPath, settingsPath);
-}
diff --git a/apps/desktop/src/electron/ElectronApp.test.ts b/apps/desktop/src/electron/ElectronApp.test.ts
new file mode 100644
index 00000000000..c51157a2364
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronApp.test.ts
@@ -0,0 +1,109 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import { beforeEach, vi } from "vitest";
+
+const {
+  appendSwitchMock,
+  exitMock,
+  getAppPathMock,
+  getVersionMock,
+  onMock,
+  quitMock,
+  relaunchMock,
+  removeListenerMock,
+  setAboutPanelOptionsMock,
+  setAppUserModelIdMock,
+  setDesktopNameMock,
+  setDockIconMock,
+  setNameMock,
+  setPathMock,
+  whenReadyMock,
+} = vi.hoisted(() => ({
+  appendSwitchMock: vi.fn(),
+  exitMock: vi.fn(),
+  getAppPathMock: vi.fn(() => "/app"),
+  getVersionMock: vi.fn(() => "1.2.3"),
+  onMock: vi.fn(),
+  quitMock: vi.fn(),
+  relaunchMock: vi.fn(),
+  removeListenerMock: vi.fn(),
+  setAboutPanelOptionsMock: vi.fn(),
+  setAppUserModelIdMock: vi.fn(),
+  setDesktopNameMock: vi.fn(),
+  setDockIconMock: vi.fn(),
+  setNameMock: vi.fn(),
+  setPathMock: vi.fn(),
+  whenReadyMock: vi.fn(() => Promise.resolve()),
+}));
+
+vi.mock("electron", () => ({
+  app: {
+    commandLine: {
+      appendSwitch: appendSwitchMock,
+    },
+    dock: {
+      setIcon: setDockIconMock,
+    },
+    getAppPath: getAppPathMock,
+    getVersion: getVersionMock,
+    isPackaged: true,
+    name: "T3 Code",
+    on: onMock,
+    quit: quitMock,
+    relaunch: relaunchMock,
+    removeListener: removeListenerMock,
+    runningUnderARM64Translation: false,
+    setAboutPanelOptions: setAboutPanelOptionsMock,
+    setAppUserModelId: setAppUserModelIdMock,
+    setDesktopName: setDesktopNameMock,
+    setName: setNameMock,
+    setPath: setPathMock,
+    whenReady: whenReadyMock,
+    exit: exitMock,
+  },
+}));
+
+import * as ElectronApp from "./ElectronApp.ts";
+
+describe("ElectronApp", () => {
+  beforeEach(() => {
+    appendSwitchMock.mockClear();
+    exitMock.mockClear();
+    onMock.mockClear();
+    quitMock.mockClear();
+    relaunchMock.mockClear();
+    removeListenerMock.mockClear();
+    setPathMock.mockClear();
+  });
+
+  it.effect("reads app metadata through the service", () =>
+    Effect.gen(function* () {
+      const electronApp = yield* ElectronApp.ElectronApp;
+      const metadata = yield* electronApp.metadata;
+
+      assert.deepEqual(metadata, {
+        appVersion: "1.2.3",
+        appPath: "/app",
+        isPackaged: true,
+        resourcesPath: process.resourcesPath,
+        runningUnderArm64Translation: false,
+      });
+    }).pipe(Effect.provide(ElectronApp.layer)),
+  );
+
+  it.effect("scopes app event listeners", () =>
+    Effect.gen(function* () {
+      const listener = vi.fn();
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const electronApp = yield* ElectronApp.ElectronApp;
+          yield* electronApp.on("activate", listener);
+        }),
+      );
+
+      assert.deepEqual(onMock.mock.calls, [["activate", listener]]);
+      assert.deepEqual(removeListenerMock.mock.calls, [["activate", listener]]);
+    }).pipe(Effect.provide(ElectronApp.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronApp.ts b/apps/desktop/src/electron/ElectronApp.ts
new file mode 100644
index 00000000000..2e330c2d275
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronApp.ts
@@ -0,0 +1,118 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+
+import * as Electron from "electron";
+
+export interface ElectronAppMetadata {
+  readonly appVersion: string;
+  readonly appPath: string;
+  readonly isPackaged: boolean;
+  readonly resourcesPath: string;
+  readonly runningUnderArm64Translation: boolean;
+}
+
+export interface ElectronAppShape {
+  readonly metadata: Effect.Effect<ElectronAppMetadata>;
+  readonly name: Effect.Effect<string>;
+  readonly whenReady: Effect.Effect<void>;
+  readonly quit: Effect.Effect<void>;
+  readonly exit: (code: number) => Effect.Effect<void>;
+  readonly relaunch: (options: Electron.RelaunchOptions) => Effect.Effect<void>;
+  readonly setPath: (
+    name: Parameters<Electron.App["setPath"]>[0],
+    path: string,
+  ) => Effect.Effect<void>;
+  readonly setName: (name: string) => Effect.Effect<void>;
+  readonly setAboutPanelOptions: (
+    options: Electron.AboutPanelOptionsOptions,
+  ) => Effect.Effect<void>;
+  readonly setAppUserModelId: (id: string) => Effect.Effect<void>;
+  readonly setDesktopName: (desktopName: string) => Effect.Effect<void>;
+  readonly setDockIcon: (iconPath: string) => Effect.Effect<void>;
+  readonly appendCommandLineSwitch: (switchName: string, value?: string) => Effect.Effect<void>;
+  readonly on: <Args extends ReadonlyArray<unknown>>(
+    eventName: string,
+    listener: (...args: Args) => void,
+  ) => Effect.Effect<void, never, Scope.Scope>;
+}
+
+export class ElectronApp extends Context.Service<ElectronApp, ElectronAppShape>()(
+  "t3/desktop/electron/App",
+) {}
+
+const addScopedAppListener = <Args extends ReadonlyArray<unknown>>(
+  eventName: string,
+  listener: (...args: Args) => void,
+): Effect.Effect<void, never, Scope.Scope> =>
+  Effect.acquireRelease(
+    Effect.sync(() => {
+      Electron.app.on(eventName as any, listener as any);
+    }),
+    () =>
+      Effect.sync(() => {
+        Electron.app.removeListener(eventName as any, listener as any);
+      }),
+  ).pipe(Effect.asVoid);
+
+const make = ElectronApp.of({
+  metadata: Effect.sync(() => ({
+    appVersion: Electron.app.getVersion(),
+    appPath: Electron.app.getAppPath(),
+    isPackaged: Electron.app.isPackaged,
+    resourcesPath: process.resourcesPath,
+    runningUnderArm64Translation: Electron.app.runningUnderARM64Translation === true,
+  })),
+  name: Effect.sync(() => Electron.app.name),
+  whenReady: Effect.promise(() => Electron.app.whenReady()).pipe(Effect.asVoid),
+  quit: Effect.sync(() => {
+    Electron.app.quit();
+  }),
+  exit: (code) =>
+    Effect.sync(() => {
+      Electron.app.exit(code);
+    }),
+  relaunch: (options) =>
+    Effect.sync(() => {
+      Electron.app.relaunch(options);
+    }),
+  setPath: (name, path) =>
+    Effect.sync(() => {
+      Electron.app.setPath(name, path);
+    }),
+  setName: (name) =>
+    Effect.sync(() => {
+      Electron.app.setName(name);
+    }),
+  setAboutPanelOptions: (options) =>
+    Effect.sync(() => {
+      Electron.app.setAboutPanelOptions(options);
+    }),
+  setAppUserModelId: (id) =>
+    Effect.sync(() => {
+      Electron.app.setAppUserModelId(id);
+    }),
+  setDesktopName: (desktopName) =>
+    Effect.sync(() => {
+      const linuxApp = Electron.app as Electron.App & {
+        setDesktopName?: (desktopName: string) => void;
+      };
+      linuxApp.setDesktopName?.(desktopName);
+    }),
+  setDockIcon: (iconPath) =>
+    Effect.sync(() => {
+      Electron.app.dock?.setIcon(iconPath);
+    }),
+  appendCommandLineSwitch: (switchName, value) =>
+    Effect.sync(() => {
+      if (value === undefined) {
+        Electron.app.commandLine.appendSwitch(switchName);
+        return;
+      }
+      Electron.app.commandLine.appendSwitch(switchName, value);
+    }),
+  on: addScopedAppListener,
+});
+
+export const layer = Layer.succeed(ElectronApp, make);
diff --git a/apps/desktop/src/electron/ElectronDialog.test.ts b/apps/desktop/src/electron/ElectronDialog.test.ts
new file mode 100644
index 00000000000..61b40bcfc4c
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronDialog.test.ts
@@ -0,0 +1,93 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { BrowserWindow } from "electron";
+import { beforeEach, vi } from "vitest";
+
+import * as ElectronDialog from "./ElectronDialog.ts";
+
+const { showMessageBoxMock, showOpenDialogMock, showErrorBoxMock } = vi.hoisted(() => ({
+  showMessageBoxMock: vi.fn(),
+  showOpenDialogMock: vi.fn(),
+  showErrorBoxMock: vi.fn(),
+}));
+
+vi.mock("electron", () => ({
+  dialog: {
+    showMessageBox: showMessageBoxMock,
+    showOpenDialog: showOpenDialogMock,
+    showErrorBox: showErrorBoxMock,
+  },
+}));
+
+describe("ElectronDialog", () => {
+  beforeEach(() => {
+    showMessageBoxMock.mockReset();
+    showOpenDialogMock.mockReset();
+    showErrorBoxMock.mockReset();
+  });
+
+  it.effect("returns false without opening a confirm dialog for empty messages", () =>
+    Effect.gen(function* () {
+      const dialog = yield* ElectronDialog.ElectronDialog;
+
+      const result = yield* dialog.confirm({
+        message: "   ",
+        owner: Option.none(),
+      });
+
+      assert.isFalse(result);
+      assert.equal(showMessageBoxMock.mock.calls.length, 0);
+    }).pipe(Effect.provide(ElectronDialog.layer)),
+  );
+
+  it.effect("opens a confirm dialog for the owner window", () =>
+    Effect.gen(function* () {
+      const owner = { id: 1 } as BrowserWindow;
+      showMessageBoxMock.mockResolvedValue({ response: 1 });
+      const dialog = yield* ElectronDialog.ElectronDialog;
+
+      const result = yield* dialog.confirm({
+        message: "Delete worktree?",
+        owner: Option.some(owner),
+      });
+
+      assert.isTrue(result);
+      assert.deepEqual(showMessageBoxMock.mock.calls[0], [
+        owner,
+        {
+          type: "question",
+          buttons: ["No", "Yes"],
+          defaultId: 0,
+          cancelId: 0,
+          noLink: true,
+          message: "Delete worktree?",
+        },
+      ]);
+    }).pipe(Effect.provide(ElectronDialog.layer)),
+  );
+
+  it.effect("opens an app-level confirm dialog when there is no owner window", () =>
+    Effect.gen(function* () {
+      showMessageBoxMock.mockResolvedValue({ response: 0 });
+      const dialog = yield* ElectronDialog.ElectronDialog;
+
+      const result = yield* dialog.confirm({
+        message: "Delete worktree?",
+        owner: Option.none(),
+      });
+
+      assert.isFalse(result);
+      assert.deepEqual(showMessageBoxMock.mock.calls[0], [
+        {
+          type: "question",
+          buttons: ["No", "Yes"],
+          defaultId: 0,
+          cancelId: 0,
+          noLink: true,
+          message: "Delete worktree?",
+        },
+      ]);
+    }).pipe(Effect.provide(ElectronDialog.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronDialog.ts b/apps/desktop/src/electron/ElectronDialog.ts
new file mode 100644
index 00000000000..5a4fdfd7ac4
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronDialog.ts
@@ -0,0 +1,84 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as Electron from "electron";
+
+const CONFIRM_BUTTON_INDEX = 1;
+
+export interface ElectronDialogPickFolderInput {
+  readonly owner: Option.Option<Electron.BrowserWindow>;
+  readonly defaultPath: Option.Option<string>;
+}
+
+export interface ElectronDialogConfirmInput {
+  readonly owner: Option.Option<Electron.BrowserWindow>;
+  readonly message: string;
+}
+
+export interface ElectronDialogShape {
+  readonly pickFolder: (
+    input: ElectronDialogPickFolderInput,
+  ) => Effect.Effect<Option.Option<string>>;
+  readonly confirm: (input: ElectronDialogConfirmInput) => Effect.Effect<boolean>;
+  readonly showMessageBox: (
+    options: Electron.MessageBoxOptions,
+  ) => Effect.Effect<Electron.MessageBoxReturnValue>;
+  readonly showErrorBox: (title: string, content: string) => Effect.Effect<void>;
+}
+
+export class ElectronDialog extends Context.Service<ElectronDialog, ElectronDialogShape>()(
+  "t3/desktop/electron/Dialog",
+) {}
+
+const make = ElectronDialog.of({
+  pickFolder: Effect.fn("desktop.electron.dialog.pickFolder")(function* (input) {
+    const openDialogOptions: Electron.OpenDialogOptions = Option.match(input.defaultPath, {
+      onNone: () => ({
+        properties: ["openDirectory", "createDirectory"],
+      }),
+      onSome: (defaultPath) => ({
+        properties: ["openDirectory", "createDirectory"],
+        defaultPath,
+      }),
+    });
+    const result = yield* Option.match(input.owner, {
+      onNone: () => Effect.promise(() => Electron.dialog.showOpenDialog(openDialogOptions)),
+      onSome: (owner) =>
+        Effect.promise(() => Electron.dialog.showOpenDialog(owner, openDialogOptions)),
+    });
+
+    if (result.canceled) {
+      return Option.none();
+    }
+    return Option.fromNullishOr(result.filePaths[0]);
+  }),
+  confirm: Effect.fn("desktop.electron.dialog.confirm")(function* (input) {
+    const normalizedMessage = input.message.trim();
+    if (normalizedMessage.length === 0) {
+      return false;
+    }
+
+    const options = {
+      type: "question" as const,
+      buttons: ["No", "Yes"],
+      defaultId: 0,
+      cancelId: 0,
+      noLink: true,
+      message: normalizedMessage,
+    };
+    const result = yield* Option.match(input.owner, {
+      onNone: () => Effect.promise(() => Electron.dialog.showMessageBox(options)),
+      onSome: (owner) => Effect.promise(() => Electron.dialog.showMessageBox(owner, options)),
+    });
+    return result.response === CONFIRM_BUTTON_INDEX;
+  }),
+  showMessageBox: (options) => Effect.promise(() => Electron.dialog.showMessageBox(options)),
+  showErrorBox: (title, content) =>
+    Effect.sync(() => {
+      Electron.dialog.showErrorBox(title, content);
+    }),
+});
+
+export const layer = Layer.succeed(ElectronDialog, make);
diff --git a/apps/desktop/src/electron/ElectronMenu.test.ts b/apps/desktop/src/electron/ElectronMenu.test.ts
new file mode 100644
index 00000000000..0e66c5a6f3f
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronMenu.test.ts
@@ -0,0 +1,119 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type * as Electron from "electron";
+import { beforeEach, vi } from "vitest";
+
+const { buildFromTemplateMock, createFromNamedImageMock, setApplicationMenuMock } = vi.hoisted(
+  () => ({
+    buildFromTemplateMock: vi.fn(),
+    createFromNamedImageMock: vi.fn(),
+    setApplicationMenuMock: vi.fn(),
+  }),
+);
+
+vi.mock("electron", () => ({
+  Menu: {
+    buildFromTemplate: buildFromTemplateMock,
+    setApplicationMenu: setApplicationMenuMock,
+  },
+  nativeImage: {
+    createFromNamedImage: createFromNamedImageMock,
+  },
+}));
+
+import * as ElectronMenu from "./ElectronMenu.ts";
+
+describe("ElectronMenu", () => {
+  beforeEach(() => {
+    buildFromTemplateMock.mockReset();
+    createFromNamedImageMock.mockReset();
+    setApplicationMenuMock.mockReset();
+  });
+
+  it.effect("returns none without building a menu when there are no valid items", () =>
+    Effect.gen(function* () {
+      const electronMenu = yield* ElectronMenu.ElectronMenu;
+      const selectedItemId = yield* electronMenu.showContextMenu({
+        window: {} as Electron.BrowserWindow,
+        items: [],
+        position: Option.none(),
+      });
+
+      assert.isTrue(Option.isNone(selectedItemId));
+      assert.equal(buildFromTemplateMock.mock.calls.length, 0);
+    }).pipe(Effect.provide(ElectronMenu.layer)),
+  );
+
+  it.effect("resolves with the clicked leaf item id", () =>
+    Effect.gen(function* () {
+      buildFromTemplateMock.mockImplementation(
+        (template: Electron.MenuItemConstructorOptions[]) => ({
+          popup: () => {
+            const firstItem = template[0];
+            assert.isDefined(firstItem);
+            const click = firstItem.click;
+            if (!click) {
+              throw new Error("Expected menu item to have a click handler.");
+            }
+            click({} as Electron.MenuItem, {} as Electron.BrowserWindow, {} as KeyboardEvent);
+          },
+        }),
+      );
+
+      const electronMenu = yield* ElectronMenu.ElectronMenu;
+      const selectedItemId = yield* electronMenu.showContextMenu({
+        window: {} as Electron.BrowserWindow,
+        items: [{ id: "copy", label: "Copy" }],
+        position: Option.none(),
+      });
+
+      assert.equal(Option.getOrNull(selectedItemId), "copy");
+    }).pipe(Effect.provide(ElectronMenu.layer)),
+  );
+
+  it.effect("resolves with none when the menu closes without a click", () =>
+    Effect.gen(function* () {
+      buildFromTemplateMock.mockImplementation(() => ({
+        popup: (options: Electron.PopupOptions) => {
+          options.callback?.();
+        },
+      }));
+
+      const electronMenu = yield* ElectronMenu.ElectronMenu;
+      const selectedItemId = yield* electronMenu.showContextMenu({
+        window: {} as Electron.BrowserWindow,
+        items: [{ id: "copy", label: "Copy" }],
+        position: Option.some({ x: 10.8, y: 20.2 }),
+      });
+
+      assert.isTrue(Option.isNone(selectedItemId));
+      assert.deepEqual(buildFromTemplateMock.mock.calls[0]?.[0][0], {
+        label: "Copy",
+        enabled: true,
+        click: buildFromTemplateMock.mock.calls[0]?.[0][0].click,
+      });
+    }).pipe(Effect.provide(ElectronMenu.layer)),
+  );
+
+  it.effect("defers popupTemplate side effects until the returned Effect runs", () =>
+    Effect.gen(function* () {
+      const popupMock = vi.fn();
+      buildFromTemplateMock.mockImplementation(() => ({ popup: popupMock }));
+
+      const electronMenu = yield* ElectronMenu.ElectronMenu;
+      const popup = electronMenu.popupTemplate({
+        window: {} as Electron.BrowserWindow,
+        template: [{ label: "Copy" }],
+      });
+
+      assert.equal(buildFromTemplateMock.mock.calls.length, 0);
+      assert.equal(popupMock.mock.calls.length, 0);
+
+      yield* popup;
+
+      assert.equal(buildFromTemplateMock.mock.calls.length, 1);
+      assert.equal(popupMock.mock.calls.length, 1);
+    }).pipe(Effect.provide(ElectronMenu.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronMenu.ts b/apps/desktop/src/electron/ElectronMenu.ts
new file mode 100644
index 00000000000..7164fdb54c1
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronMenu.ts
@@ -0,0 +1,181 @@
+import type { ContextMenuItem } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as Electron from "electron";
+
+export interface ElectronMenuPosition {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface ElectronMenuContextInput {
+  readonly window: Electron.BrowserWindow;
+  readonly items: readonly ContextMenuItem[];
+  readonly position: Option.Option<ElectronMenuPosition>;
+}
+
+export interface ElectronMenuTemplateInput {
+  readonly window: Electron.BrowserWindow;
+  readonly template: readonly Electron.MenuItemConstructorOptions[];
+}
+
+export interface ElectronMenuShape {
+  readonly setApplicationMenu: (
+    template: readonly Electron.MenuItemConstructorOptions[],
+  ) => Effect.Effect<void>;
+  readonly showContextMenu: (
+    input: ElectronMenuContextInput,
+  ) => Effect.Effect<Option.Option<string>>;
+  readonly popupTemplate: (input: ElectronMenuTemplateInput) => Effect.Effect<void>;
+}
+
+export class ElectronMenu extends Context.Service<ElectronMenu, ElectronMenuShape>()(
+  "t3/desktop/electron/Menu",
+) {}
+
+function normalizeContextMenuItems(source: readonly ContextMenuItem[]): ContextMenuItem[] {
+  const normalizedItems: ContextMenuItem[] = [];
+
+  for (const sourceItem of source) {
+    if (typeof sourceItem.id !== "string" || typeof sourceItem.label !== "string") {
+      continue;
+    }
+
+    const normalizedItem: ContextMenuItem = {
+      id: sourceItem.id,
+      label: sourceItem.label,
+      destructive: sourceItem.destructive === true,
+      disabled: sourceItem.disabled === true,
+    };
+
+    if (sourceItem.children) {
+      const normalizedChildren = normalizeContextMenuItems(sourceItem.children);
+      if (normalizedChildren.length === 0) {
+        continue;
+      }
+      normalizedItem.children = normalizedChildren;
+    }
+
+    normalizedItems.push(normalizedItem);
+  }
+
+  return normalizedItems;
+}
+
+const normalizePosition = (
+  position: Option.Option<ElectronMenuPosition>,
+): Option.Option<ElectronMenuPosition> =>
+  Option.filter(
+    position,
+    ({ x, y }) => Number.isFinite(x) && Number.isFinite(y) && x >= 0 && y >= 0,
+  ).pipe(Option.map(({ x, y }) => ({ x: Math.floor(x), y: Math.floor(y) })));
+
+export const layer = Layer.sync(ElectronMenu, () => {
+  let destructiveMenuIconCache: Option.Option<Electron.NativeImage> | undefined;
+
+  const getDestructiveMenuIcon = (): Option.Option<Electron.NativeImage> => {
+    if (process.platform !== "darwin") {
+      return Option.none();
+    }
+    if (destructiveMenuIconCache !== undefined) {
+      return destructiveMenuIconCache;
+    }
+
+    try {
+      const icon = Electron.nativeImage.createFromNamedImage("trash").resize({
+        width: 12,
+        height: 12,
+      });
+      destructiveMenuIconCache = icon.isEmpty() ? Option.none() : Option.some(icon);
+    } catch {
+      destructiveMenuIconCache = Option.none();
+    }
+
+    return destructiveMenuIconCache;
+  };
+
+  const buildTemplate = (
+    entries: readonly ContextMenuItem[],
+    complete: (selectedItemId: Option.Option<string>) => void,
+  ): Electron.MenuItemConstructorOptions[] => {
+    const template: Electron.MenuItemConstructorOptions[] = [];
+    let hasInsertedDestructiveSeparator = false;
+
+    for (const item of entries) {
+      if (item.destructive && !hasInsertedDestructiveSeparator && template.length > 0) {
+        template.push({ type: "separator" });
+        hasInsertedDestructiveSeparator = true;
+      }
+
+      const itemOption: Electron.MenuItemConstructorOptions = {
+        label: item.label,
+        enabled: !item.disabled,
+      };
+      if (item.children && item.children.length > 0) {
+        itemOption.submenu = buildTemplate(item.children, complete);
+      } else {
+        itemOption.click = () => complete(Option.some(item.id));
+      }
+      if (item.destructive && (!item.children || item.children.length === 0)) {
+        const destructiveIcon = getDestructiveMenuIcon();
+        if (Option.isSome(destructiveIcon)) {
+          itemOption.icon = destructiveIcon.value;
+        }
+      }
+
+      template.push(itemOption);
+    }
+
+    return template;
+  };
+
+  return ElectronMenu.of({
+    setApplicationMenu: (template) =>
+      Effect.sync(() => {
+        Electron.Menu.setApplicationMenu(Electron.Menu.buildFromTemplate([...template]));
+      }),
+    popupTemplate: (input) =>
+      Effect.sync(() => {
+        if (input.template.length === 0) {
+          return;
+        }
+        Electron.Menu.buildFromTemplate([...input.template]).popup({ window: input.window });
+      }),
+    showContextMenu: (input) =>
+      Effect.callback<Option.Option<string>>((resume) => {
+        const normalizedItems = normalizeContextMenuItems(input.items);
+        if (normalizedItems.length === 0) {
+          resume(Effect.succeed(Option.none()));
+          return;
+        }
+
+        let completed = false;
+        const complete = (selectedItemId: Option.Option<string>) => {
+          if (completed) {
+            return;
+          }
+          completed = true;
+          resume(Effect.succeed(selectedItemId));
+        };
+
+        const menu = Electron.Menu.buildFromTemplate(buildTemplate(normalizedItems, complete));
+        const popupPosition = normalizePosition(input.position);
+        const popupOptions = Option.match(popupPosition, {
+          onNone: (): Electron.PopupOptions => ({
+            window: input.window,
+            callback: () => complete(Option.none()),
+          }),
+          onSome: (position): Electron.PopupOptions => ({
+            window: input.window,
+            x: position.x,
+            y: position.y,
+            callback: () => complete(Option.none()),
+          }),
+        });
+        menu.popup(popupOptions);
+      }),
+  });
+});
diff --git a/apps/desktop/src/electron/ElectronProtocol.test.ts b/apps/desktop/src/electron/ElectronProtocol.test.ts
new file mode 100644
index 00000000000..955813d6d35
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronProtocol.test.ts
@@ -0,0 +1,105 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import type * as Electron from "electron";
+import { beforeEach, vi } from "vitest";
+
+const { registerFileProtocolMock, registerSchemesAsPrivilegedMock, unregisterProtocolMock } =
+  vi.hoisted(() => ({
+    registerFileProtocolMock: vi.fn(),
+    registerSchemesAsPrivilegedMock: vi.fn(),
+    unregisterProtocolMock: vi.fn(),
+  }));
+
+vi.mock("electron", () => ({
+  protocol: {
+    registerFileProtocol: registerFileProtocolMock,
+    registerSchemesAsPrivileged: registerSchemesAsPrivilegedMock,
+    unregisterProtocol: unregisterProtocolMock,
+  },
+}));
+
+import * as ElectronProtocol from "./ElectronProtocol.ts";
+
+describe("ElectronProtocol", () => {
+  beforeEach(() => {
+    registerFileProtocolMock.mockReset();
+    registerSchemesAsPrivilegedMock.mockReset();
+    unregisterProtocolMock.mockReset();
+  });
+
+  it("normalizes safe desktop protocol pathnames", () => {
+    assert.equal(
+      Option.getOrNull(ElectronProtocol.normalizeDesktopProtocolPathname("/settings/./general")),
+      "settings/general",
+    );
+    assert.isTrue(Option.isNone(ElectronProtocol.normalizeDesktopProtocolPathname("/../secret")));
+  });
+
+  it.effect("registers desktop scheme privileges through a layer", () =>
+    Effect.scoped(
+      Layer.build(ElectronProtocol.layerSchemePrivileges).pipe(
+        Effect.andThen(
+          Effect.sync(() => {
+            assert.deepEqual(registerSchemesAsPrivilegedMock.mock.calls, [
+              [
+                [
+                  {
+                    scheme: "t3",
+                    privileges: {
+                      standard: true,
+                      secure: true,
+                      supportFetchAPI: true,
+                      corsEnabled: true,
+                    },
+                  },
+                ],
+              ],
+            ]);
+          }),
+        ),
+      ),
+    ),
+  );
+
+  it.effect("scopes registered file protocols", () =>
+    Effect.gen(function* () {
+      let capturedHandler:
+        | ((
+            request: Electron.ProtocolRequest,
+            callback: (response: Electron.ProtocolResponse) => void,
+          ) => void)
+        | undefined;
+
+      registerFileProtocolMock.mockImplementation((_scheme, handler) => {
+        capturedHandler = handler;
+        return true;
+      });
+
+      const response = yield* Effect.scoped(
+        Effect.gen(function* () {
+          const electronProtocol = yield* ElectronProtocol.ElectronProtocol;
+          yield* electronProtocol.registerFileProtocol({
+            scheme: "t3",
+            handler: () => Effect.succeed({ path: "/app/index.html" }),
+          });
+
+          assert.isDefined(capturedHandler);
+          return yield* Effect.callback<Electron.ProtocolResponse>((resume) => {
+            capturedHandler?.({ url: "t3://app/" } as Electron.ProtocolRequest, (response) =>
+              resume(Effect.succeed(response)),
+            );
+          });
+        }),
+      );
+
+      assert.deepEqual(response, { path: "/app/index.html" });
+      assert.deepEqual(
+        registerFileProtocolMock.mock.calls.map((call) => call[0]),
+        ["t3"],
+      );
+      assert.deepEqual(unregisterProtocolMock.mock.calls, [["t3"]]);
+    }).pipe(Effect.provide(ElectronProtocol.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronProtocol.ts b/apps/desktop/src/electron/ElectronProtocol.ts
new file mode 100644
index 00000000000..32d23ba485d
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronProtocol.ts
@@ -0,0 +1,272 @@
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+
+import * as Electron from "electron";
+
+import { DesktopEnvironment, type DesktopEnvironmentShape } from "../app/DesktopEnvironment.ts";
+
+export const DESKTOP_SCHEME = "t3";
+
+export class ElectronProtocolRegistrationError extends Data.TaggedError(
+  "ElectronProtocolRegistrationError",
+)<{
+  readonly scheme: string;
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return `Failed to register ${this.scheme}: file protocol.`;
+  }
+}
+
+export class ElectronProtocolStaticBundleMissingError extends Data.TaggedError(
+  "ElectronProtocolStaticBundleMissingError",
+)<{}> {
+  override get message() {
+    return "Desktop static bundle missing. Build apps/server (with bundled client) first.";
+  }
+}
+
+export interface ElectronProtocolShape {
+  readonly registerFileProtocol: <E, R>(input: {
+    readonly scheme: string;
+    readonly handler: (
+      request: Electron.ProtocolRequest,
+    ) => Effect.Effect<Electron.ProtocolResponse, E, R>;
+    readonly onFailure?: (
+      request: Electron.ProtocolRequest,
+      cause: Cause.Cause<E>,
+    ) => Electron.ProtocolResponse;
+  }) => Effect.Effect<void, ElectronProtocolRegistrationError, R | Scope.Scope>;
+  readonly registerDesktopFileProtocol: Effect.Effect<
+    void,
+    ElectronProtocolRegistrationError | ElectronProtocolStaticBundleMissingError,
+    FileSystem.FileSystem | DesktopEnvironment | Scope.Scope
+  >;
+}
+
+export class ElectronProtocol extends Context.Service<ElectronProtocol, ElectronProtocolShape>()(
+  "t3/desktop/electron/Protocol",
+) {}
+
+export function normalizeDesktopProtocolPathname(rawPath: string): Option.Option<string> {
+  const segments: string[] = [];
+  for (const segment of rawPath.split("/")) {
+    if (segment.length === 0 || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      return Option.none();
+    }
+    segments.push(segment);
+  }
+  return Option.some(segments.join("/"));
+}
+
+const registerDesktopSchemePrivileges = Effect.sync(() => {
+  Electron.protocol.registerSchemesAsPrivileged([
+    {
+      scheme: DESKTOP_SCHEME,
+      privileges: {
+        standard: true,
+        secure: true,
+        supportFetchAPI: true,
+        corsEnabled: true,
+      },
+    },
+  ]);
+}).pipe(Effect.withSpan("desktop.electron.protocol.registerSchemePrivileges"));
+
+export const layerSchemePrivileges = Layer.effectDiscard(registerDesktopSchemePrivileges);
+
+const resolveDesktopStaticDir: Effect.Effect<
+  Option.Option<string>,
+  never,
+  FileSystem.FileSystem | DesktopEnvironment
+> = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const environment = yield* DesktopEnvironment;
+  const candidates = [
+    environment.path.join(environment.appRoot, "apps/server/dist/client"),
+    environment.path.join(environment.appRoot, "apps/web/dist"),
+  ];
+  for (const candidate of candidates) {
+    const hasIndex = yield* fileSystem
+      .exists(environment.path.join(candidate, "index.html"))
+      .pipe(Effect.orElseSucceed(() => false));
+    if (hasIndex) {
+      return Option.some(candidate);
+    }
+  }
+  return Option.none<string>();
+});
+
+const resolveDesktopStaticPath = Effect.fn("desktop.electron.protocol.resolveDesktopStaticPath")(
+  function* (
+    staticRoot: string,
+    requestUrl: string,
+  ): Effect.fn.Return<string, never, FileSystem.FileSystem | DesktopEnvironment> {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const environment = yield* DesktopEnvironment;
+    const url = new URL(requestUrl);
+    const rawPath = decodeURIComponent(url.pathname);
+    const normalizedPath = normalizeDesktopProtocolPathname(rawPath);
+    if (Option.isNone(normalizedPath)) {
+      return environment.path.join(staticRoot, "index.html");
+    }
+
+    const requestedPath = normalizedPath.value.length > 0 ? normalizedPath.value : "index.html";
+    const resolvedPath = environment.path.join(staticRoot, requestedPath);
+
+    if (environment.path.extname(resolvedPath)) {
+      return resolvedPath;
+    }
+
+    const nestedIndex = environment.path.join(resolvedPath, "index.html");
+    const nestedIndexExists = yield* fileSystem
+      .exists(nestedIndex)
+      .pipe(Effect.orElseSucceed(() => false));
+    if (nestedIndexExists) {
+      return nestedIndex;
+    }
+
+    return environment.path.join(staticRoot, "index.html");
+  },
+);
+
+function isStaticAssetRequest(requestUrl: string, environment: DesktopEnvironmentShape): boolean {
+  try {
+    const url = new URL(requestUrl);
+    return environment.path.extname(url.pathname).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+const make = Effect.gen(function* () {
+  const registeredProtocols = yield* Ref.make<ReadonlySet<string>>(new Set());
+
+  const registerFileProtocol = Effect.fn("desktop.electron.protocol.registerFileProtocol")(
+    function* <E, R>({
+      scheme,
+      handler,
+      onFailure,
+    }: {
+      readonly scheme: string;
+      readonly handler: (
+        request: Electron.ProtocolRequest,
+      ) => Effect.Effect<Electron.ProtocolResponse, E, R>;
+      readonly onFailure?: (
+        request: Electron.ProtocolRequest,
+        cause: Cause.Cause<E>,
+      ) => Electron.ProtocolResponse;
+    }): Effect.fn.Return<void, ElectronProtocolRegistrationError, R | Scope.Scope> {
+      yield* Effect.annotateCurrentSpan({ scheme });
+      const alreadyRegistered = yield* Ref.get(registeredProtocols).pipe(
+        Effect.map((protocols) => protocols.has(scheme)),
+      );
+      if (alreadyRegistered) {
+        return;
+      }
+
+      const context = yield* Effect.context<R>();
+      const runPromise = Effect.runPromiseWith(context);
+
+      yield* Effect.acquireRelease(
+        Effect.try({
+          try: () => {
+            const registered = Electron.protocol.registerFileProtocol(
+              scheme,
+              (request, callback) => {
+                const response = handler(request).pipe(
+                  Effect.withSpan("desktop.electron.protocol.handleFileRequest"),
+                  Effect.catchCause((cause) =>
+                    Effect.succeed(onFailure?.(request, cause) ?? ({ error: -2 } as const)),
+                  ),
+                );
+
+                void runPromise(response).then(callback, () => callback({ error: -2 }));
+              },
+            );
+            if (!registered) {
+              throw new ElectronProtocolRegistrationError({
+                scheme,
+                cause: "registerFileProtocol returned false",
+              });
+            }
+          },
+          catch: (cause) =>
+            cause instanceof ElectronProtocolRegistrationError
+              ? cause
+              : new ElectronProtocolRegistrationError({ scheme, cause }),
+        }).pipe(
+          Effect.andThen(
+            Ref.update(registeredProtocols, (protocols) => new Set(protocols).add(scheme)),
+          ),
+        ),
+        () =>
+          Effect.sync(() => {
+            Electron.protocol.unregisterProtocol(scheme);
+          }).pipe(
+            Effect.andThen(
+              Ref.update(registeredProtocols, (protocols) => {
+                const next = new Set(protocols);
+                next.delete(scheme);
+                return next;
+              }),
+            ),
+          ),
+      );
+    },
+  );
+
+  const registerDesktopFileProtocol = Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment;
+    if (environment.isDevelopment) return;
+
+    const staticRoot = yield* resolveDesktopStaticDir;
+    if (Option.isNone(staticRoot)) {
+      return yield* new ElectronProtocolStaticBundleMissingError();
+    }
+
+    const staticRootResolved = environment.path.resolve(staticRoot.value);
+    const staticRootPrefix = `${staticRootResolved}${environment.path.sep}`;
+    const fallbackIndex = environment.path.join(staticRootResolved, "index.html");
+
+    yield* registerFileProtocol({
+      scheme: DESKTOP_SCHEME,
+      handler: Effect.fn("desktop.electron.protocol.handleDesktopFileRequest")(function* (request) {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const environment = yield* DesktopEnvironment;
+        const candidate = yield* resolveDesktopStaticPath(staticRootResolved, request.url);
+        const resolvedCandidate = environment.path.resolve(candidate);
+        const isInRoot =
+          resolvedCandidate === fallbackIndex || resolvedCandidate.startsWith(staticRootPrefix);
+        const isAssetRequest = isStaticAssetRequest(request.url, environment);
+        const exists = yield* fileSystem
+          .exists(resolvedCandidate)
+          .pipe(Effect.orElseSucceed(() => false));
+
+        if (!isInRoot || !exists) {
+          return isAssetRequest ? ({ error: -6 } as const) : ({ path: fallbackIndex } as const);
+        }
+
+        return { path: resolvedCandidate } as const;
+      }),
+      onFailure: () => ({ path: fallbackIndex }),
+    });
+  }).pipe(Effect.withSpan("desktop.electron.protocol.registerDesktopFileProtocol"));
+
+  return ElectronProtocol.of({
+    registerFileProtocol,
+    registerDesktopFileProtocol,
+  });
+});
+
+export const layer = Layer.effect(ElectronProtocol, make);
diff --git a/apps/desktop/src/electron/ElectronSafeStorage.ts b/apps/desktop/src/electron/ElectronSafeStorage.ts
new file mode 100644
index 00000000000..eebb3e2b2f8
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronSafeStorage.ts
@@ -0,0 +1,70 @@
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import * as Electron from "electron";
+
+export class ElectronSafeStorageAvailabilityError extends Data.TaggedError(
+  "ElectronSafeStorageAvailabilityError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return "Electron safe storage failed to check encryption availability.";
+  }
+}
+
+export class ElectronSafeStorageEncryptError extends Data.TaggedError(
+  "ElectronSafeStorageEncryptError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return "Electron safe storage failed to encrypt a string.";
+  }
+}
+
+export class ElectronSafeStorageDecryptError extends Data.TaggedError(
+  "ElectronSafeStorageDecryptError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return "Electron safe storage failed to decrypt a string.";
+  }
+}
+
+export interface ElectronSafeStorageShape {
+  readonly isEncryptionAvailable: Effect.Effect<boolean, ElectronSafeStorageAvailabilityError>;
+  readonly encryptString: (
+    value: string,
+  ) => Effect.Effect<Uint8Array, ElectronSafeStorageEncryptError>;
+  readonly decryptString: (
+    value: Uint8Array,
+  ) => Effect.Effect<string, ElectronSafeStorageDecryptError>;
+}
+
+export class ElectronSafeStorage extends Context.Service<
+  ElectronSafeStorage,
+  ElectronSafeStorageShape
+>()("@t3tools/desktop/ElectronSafeStorage") {}
+
+const make = ElectronSafeStorage.of({
+  isEncryptionAvailable: Effect.try({
+    try: () => Electron.safeStorage.isEncryptionAvailable(),
+    catch: (cause) => new ElectronSafeStorageAvailabilityError({ cause }),
+  }),
+  encryptString: (value) =>
+    Effect.try({
+      try: () => Electron.safeStorage.encryptString(value),
+      catch: (cause) => new ElectronSafeStorageEncryptError({ cause }),
+    }),
+  decryptString: (value) =>
+    Effect.try({
+      try: () => Electron.safeStorage.decryptString(Buffer.from(value)),
+      catch: (cause) => new ElectronSafeStorageDecryptError({ cause }),
+    }),
+});
+
+export const layer = Layer.succeed(ElectronSafeStorage, make);
diff --git a/apps/desktop/src/electron/ElectronShell.test.ts b/apps/desktop/src/electron/ElectronShell.test.ts
new file mode 100644
index 00000000000..42d1bb33add
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronShell.test.ts
@@ -0,0 +1,59 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import { beforeEach, vi } from "vitest";
+
+const { openExternalMock, writeTextMock } = vi.hoisted(() => ({
+  openExternalMock: vi.fn(),
+  writeTextMock: vi.fn(),
+}));
+
+vi.mock("electron", () => ({
+  shell: {
+    openExternal: openExternalMock,
+  },
+  clipboard: {
+    writeText: writeTextMock,
+  },
+}));
+
+import * as ElectronShell from "./ElectronShell.ts";
+
+describe("ElectronShell", () => {
+  beforeEach(() => {
+    openExternalMock.mockReset();
+    writeTextMock.mockReset();
+  });
+
+  it.effect("opens safe external URLs", () =>
+    Effect.gen(function* () {
+      openExternalMock.mockResolvedValue(undefined);
+
+      const electronShell = yield* ElectronShell.ElectronShell;
+      const result = yield* electronShell.openExternal("https://example.com/path");
+
+      assert.equal(result, true);
+      assert.deepEqual(openExternalMock.mock.calls, [["https://example.com/path"]]);
+    }).pipe(Effect.provide(ElectronShell.layer)),
+  );
+
+  it.effect("does not open unsafe external URLs", () =>
+    Effect.gen(function* () {
+      const electronShell = yield* ElectronShell.ElectronShell;
+      const result = yield* electronShell.openExternal("file:///etc/passwd");
+
+      assert.equal(result, false);
+      assert.equal(openExternalMock.mock.calls.length, 0);
+    }).pipe(Effect.provide(ElectronShell.layer)),
+  );
+
+  it.effect("returns false when Electron rejects openExternal", () =>
+    Effect.gen(function* () {
+      openExternalMock.mockRejectedValue(new Error("open failed"));
+
+      const electronShell = yield* ElectronShell.ElectronShell;
+      const result = yield* electronShell.openExternal("https://example.com/path");
+
+      assert.equal(result, false);
+    }).pipe(Effect.provide(ElectronShell.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronShell.ts b/apps/desktop/src/electron/ElectronShell.ts
new file mode 100644
index 00000000000..09826a95b09
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronShell.ts
@@ -0,0 +1,50 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as Electron from "electron";
+
+const SAFE_EXTERNAL_PROTOCOLS = new Set(["http:", "https:"]);
+
+export function parseSafeExternalUrl(rawUrl: unknown): Option.Option<string> {
+  if (typeof rawUrl !== "string") {
+    return Option.none();
+  }
+
+  try {
+    const url = new URL(rawUrl);
+    return SAFE_EXTERNAL_PROTOCOLS.has(url.protocol) ? Option.some(url.href) : Option.none();
+  } catch {
+    return Option.none();
+  }
+}
+
+export interface ElectronShellShape {
+  readonly openExternal: (rawUrl: unknown) => Effect.Effect<boolean>;
+  readonly copyText: (text: string) => Effect.Effect<void>;
+}
+
+export class ElectronShell extends Context.Service<ElectronShell, ElectronShellShape>()(
+  "t3/desktop/electron/Shell",
+) {}
+
+const make = ElectronShell.of({
+  openExternal: (rawUrl) =>
+    Option.match(parseSafeExternalUrl(rawUrl), {
+      onNone: () => Effect.succeed(false),
+      onSome: (externalUrl) =>
+        Effect.promise(() =>
+          Electron.shell.openExternal(externalUrl).then(
+            () => true,
+            () => false,
+          ),
+        ),
+    }),
+  copyText: (text) =>
+    Effect.sync(() => {
+      Electron.clipboard.writeText(text);
+    }),
+});
+
+export const layer = Layer.succeed(ElectronShell, make);
diff --git a/apps/desktop/src/electron/ElectronTheme.test.ts b/apps/desktop/src/electron/ElectronTheme.test.ts
new file mode 100644
index 00000000000..c52882852ff
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronTheme.test.ts
@@ -0,0 +1,52 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import { beforeEach, vi } from "vitest";
+
+const { onMock, removeListenerMock, themeState } = vi.hoisted(() => ({
+  onMock: vi.fn(),
+  removeListenerMock: vi.fn(),
+  themeState: {
+    shouldUseDarkColors: true,
+    themeSource: "system",
+  },
+}));
+
+vi.mock("electron", () => ({
+  nativeTheme: {
+    get shouldUseDarkColors() {
+      return themeState.shouldUseDarkColors;
+    },
+    set themeSource(value: string) {
+      themeState.themeSource = value;
+    },
+    on: onMock,
+    removeListener: removeListenerMock,
+  },
+}));
+
+import * as ElectronTheme from "./ElectronTheme.ts";
+
+describe("ElectronTheme", () => {
+  beforeEach(() => {
+    onMock.mockClear();
+    removeListenerMock.mockClear();
+    themeState.shouldUseDarkColors = true;
+    themeState.themeSource = "system";
+  });
+
+  it.effect("scopes native theme update listeners", () =>
+    Effect.gen(function* () {
+      const listener = vi.fn();
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const electronTheme = yield* ElectronTheme.ElectronTheme;
+          yield* electronTheme.onUpdated(listener);
+        }),
+      );
+
+      assert.deepEqual(onMock.mock.calls, [["updated", listener]]);
+      assert.deepEqual(removeListenerMock.mock.calls, [["updated", listener]]);
+    }).pipe(Effect.provide(ElectronTheme.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronTheme.ts b/apps/desktop/src/electron/ElectronTheme.ts
new file mode 100644
index 00000000000..ecf1f98dade
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronTheme.ts
@@ -0,0 +1,40 @@
+import type { DesktopTheme } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+
+import * as Electron from "electron";
+
+export interface ElectronThemeShape {
+  readonly shouldUseDarkColors: Effect.Effect<boolean>;
+  readonly setSource: (theme: DesktopTheme) => Effect.Effect<void>;
+  readonly onUpdated: (listener: () => void) => Effect.Effect<void, never, Scope.Scope>;
+}
+
+export class ElectronTheme extends Context.Service<ElectronTheme, ElectronThemeShape>()(
+  "t3/desktop/electron/Theme",
+) {}
+
+const make = ElectronTheme.of({
+  shouldUseDarkColors: Effect.sync(() => Electron.nativeTheme.shouldUseDarkColors),
+  setSource: (theme) =>
+    Effect.suspend(() => {
+      Electron.nativeTheme.themeSource = theme;
+      return Effect.void;
+    }),
+  onUpdated: (listener) =>
+    Effect.acquireRelease(
+      Effect.suspend(() => {
+        Electron.nativeTheme.on("updated", listener);
+        return Effect.void;
+      }),
+      () =>
+        Effect.suspend(() => {
+          Electron.nativeTheme.removeListener("updated", listener);
+          return Effect.void;
+        }),
+    ),
+});
+
+export const layer = Layer.succeed(ElectronTheme, make);
diff --git a/apps/desktop/src/electron/ElectronUpdater.test.ts b/apps/desktop/src/electron/ElectronUpdater.test.ts
new file mode 100644
index 00000000000..eec21a9ae56
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronUpdater.test.ts
@@ -0,0 +1,79 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import { beforeEach, vi } from "vitest";
+
+const { autoUpdaterMock } = vi.hoisted(() => ({
+  autoUpdaterMock: {
+    allowDowngrade: false,
+    allowPrerelease: false,
+    autoDownload: true,
+    autoInstallOnAppQuit: true,
+    channel: "latest",
+    disableDifferentialDownload: false,
+    checkForUpdates: vi.fn(() => Promise.resolve(null)),
+    downloadUpdate: vi.fn(() => Promise.resolve([])),
+    on: vi.fn(),
+    quitAndInstall: vi.fn(),
+    removeListener: vi.fn(),
+    setFeedURL: vi.fn(),
+  },
+}));
+
+vi.mock("electron-updater", () => ({
+  autoUpdater: autoUpdaterMock,
+}));
+
+import * as ElectronUpdater from "./ElectronUpdater.ts";
+
+describe("ElectronUpdater", () => {
+  beforeEach(() => {
+    autoUpdaterMock.allowDowngrade = false;
+    autoUpdaterMock.allowPrerelease = false;
+    autoUpdaterMock.autoDownload = true;
+    autoUpdaterMock.autoInstallOnAppQuit = true;
+    autoUpdaterMock.channel = "latest";
+    autoUpdaterMock.disableDifferentialDownload = false;
+    autoUpdaterMock.checkForUpdates.mockClear();
+    autoUpdaterMock.checkForUpdates.mockImplementation(() => Promise.resolve(null));
+    autoUpdaterMock.downloadUpdate.mockClear();
+    autoUpdaterMock.downloadUpdate.mockImplementation(() => Promise.resolve([]));
+    autoUpdaterMock.on.mockClear();
+    autoUpdaterMock.quitAndInstall.mockClear();
+    autoUpdaterMock.removeListener.mockClear();
+    autoUpdaterMock.setFeedURL.mockClear();
+  });
+
+  it.effect("scopes updater event listeners", () =>
+    Effect.gen(function* () {
+      const listener = vi.fn();
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const updater = yield* ElectronUpdater.ElectronUpdater;
+          yield* updater.on("update-available", listener);
+        }),
+      );
+
+      assert.deepEqual(autoUpdaterMock.on.mock.calls, [["update-available", listener]]);
+      assert.deepEqual(autoUpdaterMock.removeListener.mock.calls, [["update-available", listener]]);
+    }).pipe(Effect.provide(ElectronUpdater.layer)),
+  );
+
+  it.effect("wraps rejected update checks in the method-specific typed error", () =>
+    Effect.gen(function* () {
+      const cause = new Error("network unavailable");
+      autoUpdaterMock.checkForUpdates.mockImplementationOnce(() => Promise.reject(cause));
+      const updater = yield* ElectronUpdater.ElectronUpdater;
+
+      const exit = yield* Effect.exit(updater.checkForUpdates);
+
+      assert.equal(exit._tag, "Failure");
+      if (exit._tag === "Failure") {
+        const error = Cause.squash(exit.cause);
+        assert.instanceOf(error, ElectronUpdater.ElectronUpdaterCheckForUpdatesError);
+        assert.equal(error.cause, cause);
+      }
+    }).pipe(Effect.provide(ElectronUpdater.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronUpdater.ts b/apps/desktop/src/electron/ElectronUpdater.ts
new file mode 100644
index 00000000000..ad8afbcdfc3
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronUpdater.ts
@@ -0,0 +1,139 @@
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+
+import { autoUpdater } from "electron-updater";
+
+type AutoUpdater = typeof autoUpdater;
+
+export type ElectronUpdaterFeedUrl = Parameters<AutoUpdater["setFeedURL"]>[0];
+
+export class ElectronUpdaterCheckForUpdatesError extends Data.TaggedError(
+  "ElectronUpdaterCheckForUpdatesError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return "Electron updater failed to check for updates.";
+  }
+}
+
+export class ElectronUpdaterDownloadUpdateError extends Data.TaggedError(
+  "ElectronUpdaterDownloadUpdateError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return "Electron updater failed to download the update.";
+  }
+}
+
+export class ElectronUpdaterQuitAndInstallError extends Data.TaggedError(
+  "ElectronUpdaterQuitAndInstallError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return "Electron updater failed to quit and install the update.";
+  }
+}
+
+export type ElectronUpdaterError =
+  | ElectronUpdaterCheckForUpdatesError
+  | ElectronUpdaterDownloadUpdateError
+  | ElectronUpdaterQuitAndInstallError;
+
+export interface ElectronUpdaterShape {
+  readonly setFeedURL: (options: ElectronUpdaterFeedUrl) => Effect.Effect<void>;
+  readonly setAutoDownload: (value: boolean) => Effect.Effect<void>;
+  readonly setAutoInstallOnAppQuit: (value: boolean) => Effect.Effect<void>;
+  readonly setChannel: (channel: string) => Effect.Effect<void>;
+  readonly setAllowPrerelease: (value: boolean) => Effect.Effect<void>;
+  readonly allowDowngrade: Effect.Effect<boolean>;
+  readonly setAllowDowngrade: (value: boolean) => Effect.Effect<void>;
+  readonly setDisableDifferentialDownload: (value: boolean) => Effect.Effect<void>;
+  readonly checkForUpdates: Effect.Effect<void, ElectronUpdaterCheckForUpdatesError>;
+  readonly downloadUpdate: Effect.Effect<void, ElectronUpdaterDownloadUpdateError>;
+  readonly quitAndInstall: (options: {
+    readonly isSilent: boolean;
+    readonly isForceRunAfter: boolean;
+  }) => Effect.Effect<void, ElectronUpdaterQuitAndInstallError>;
+  readonly on: <Args extends ReadonlyArray<unknown>>(
+    eventName: string,
+    listener: (...args: Args) => void,
+  ) => Effect.Effect<void, never, Scope.Scope>;
+}
+
+export class ElectronUpdater extends Context.Service<ElectronUpdater, ElectronUpdaterShape>()(
+  "t3/desktop/electron/Updater",
+) {}
+
+export const layer = Layer.succeed(ElectronUpdater, {
+  setFeedURL: (options) =>
+    Effect.suspend(() => {
+      autoUpdater.setFeedURL(options);
+      return Effect.void;
+    }),
+  setAutoDownload: (value) =>
+    Effect.suspend(() => {
+      autoUpdater.autoDownload = value;
+      return Effect.void;
+    }),
+  setAutoInstallOnAppQuit: (value) =>
+    Effect.suspend(() => {
+      autoUpdater.autoInstallOnAppQuit = value;
+      return Effect.void;
+    }),
+  setChannel: (channel) =>
+    Effect.suspend(() => {
+      autoUpdater.channel = channel;
+      return Effect.void;
+    }),
+  setAllowPrerelease: (value) =>
+    Effect.suspend(() => {
+      autoUpdater.allowPrerelease = value;
+      return Effect.void;
+    }),
+  allowDowngrade: Effect.sync(() => autoUpdater.allowDowngrade),
+  setAllowDowngrade: (value) =>
+    Effect.suspend(() => {
+      autoUpdater.allowDowngrade = value;
+      return Effect.void;
+    }),
+  setDisableDifferentialDownload: (value) =>
+    Effect.suspend(() => {
+      autoUpdater.disableDifferentialDownload = value;
+      return Effect.void;
+    }),
+  checkForUpdates: Effect.tryPromise({
+    try: () => autoUpdater.checkForUpdates(),
+    catch: (cause) => new ElectronUpdaterCheckForUpdatesError({ cause }),
+  }).pipe(Effect.asVoid),
+  downloadUpdate: Effect.tryPromise({
+    try: () => autoUpdater.downloadUpdate(),
+    catch: (cause) => new ElectronUpdaterDownloadUpdateError({ cause }),
+  }).pipe(Effect.asVoid),
+  quitAndInstall: ({ isSilent, isForceRunAfter }) =>
+    Effect.try({
+      try: () => autoUpdater.quitAndInstall(isSilent, isForceRunAfter),
+      catch: (cause) => new ElectronUpdaterQuitAndInstallError({ cause }),
+    }),
+  on: (eventName, listener) => {
+    const eventTarget = autoUpdater as unknown as {
+      on: (eventName: string, listener: (...args: Array<unknown>) => void) => void;
+      removeListener: (eventName: string, listener: (...args: Array<unknown>) => void) => void;
+    };
+    const untypedListener = listener as unknown as (...args: Array<unknown>) => void;
+    return Effect.acquireRelease(
+      Effect.sync(() => {
+        eventTarget.on(eventName, untypedListener);
+      }),
+      () =>
+        Effect.sync(() => {
+          eventTarget.removeListener(eventName, untypedListener);
+        }),
+    ).pipe(Effect.asVoid);
+  },
+} satisfies ElectronUpdaterShape);
diff --git a/apps/desktop/src/electron/ElectronWindow.test.ts b/apps/desktop/src/electron/ElectronWindow.test.ts
new file mode 100644
index 00000000000..bc8a4cdd282
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronWindow.test.ts
@@ -0,0 +1,51 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import type * as Electron from "electron";
+import { beforeEach, vi } from "vitest";
+
+const { appFocusMock, getAllWindowsMock } = vi.hoisted(() => ({
+  appFocusMock: vi.fn(),
+  getAllWindowsMock: vi.fn(),
+}));
+
+vi.mock("electron", () => ({
+  app: {
+    focus: appFocusMock,
+  },
+  BrowserWindow: {
+    getAllWindows: getAllWindowsMock,
+  },
+}));
+
+import * as ElectronWindow from "./ElectronWindow.ts";
+
+function makeBrowserWindow(input: { readonly destroyed: boolean }) {
+  return {
+    isDestroyed: vi.fn(() => input.destroyed),
+  } as unknown as Electron.BrowserWindow;
+}
+
+describe("ElectronWindow", () => {
+  beforeEach(() => {
+    appFocusMock.mockReset();
+    getAllWindowsMock.mockReset();
+  });
+
+  it.effect("skips windows destroyed before appearance sync runs", () =>
+    Effect.gen(function* () {
+      const liveWindow = makeBrowserWindow({ destroyed: false });
+      const destroyedWindow = makeBrowserWindow({ destroyed: true });
+      getAllWindowsMock.mockReturnValue([destroyedWindow, liveWindow]);
+
+      const syncedWindows: Electron.BrowserWindow[] = [];
+      const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.syncAllAppearance((window) =>
+        Effect.sync(() => {
+          syncedWindows.push(window);
+        }),
+      );
+
+      assert.deepEqual(syncedWindows, [liveWindow]);
+    }).pipe(Effect.provide(ElectronWindow.layer)),
+  );
+});
diff --git a/apps/desktop/src/electron/ElectronWindow.ts b/apps/desktop/src/electron/ElectronWindow.ts
new file mode 100644
index 00000000000..ed31fb0700e
--- /dev/null
+++ b/apps/desktop/src/electron/ElectronWindow.ts
@@ -0,0 +1,135 @@
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+
+import * as Electron from "electron";
+
+export class ElectronWindowCreateError extends Data.TaggedError("ElectronWindowCreateError")<{
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return "Failed to create Electron BrowserWindow.";
+  }
+}
+
+export interface ElectronWindowShape {
+  readonly create: (
+    options: Electron.BrowserWindowConstructorOptions,
+  ) => Effect.Effect<Electron.BrowserWindow, ElectronWindowCreateError>;
+  readonly main: Effect.Effect<Option.Option<Electron.BrowserWindow>>;
+  readonly currentMainOrFirst: Effect.Effect<Option.Option<Electron.BrowserWindow>>;
+  readonly focusedMainOrFirst: Effect.Effect<Option.Option<Electron.BrowserWindow>>;
+  readonly setMain: (window: Electron.BrowserWindow) => Effect.Effect<void>;
+  readonly clearMain: (window: Option.Option<Electron.BrowserWindow>) => Effect.Effect<void>;
+  readonly reveal: (window: Electron.BrowserWindow) => Effect.Effect<void>;
+  readonly sendAll: (channel: string, ...args: readonly unknown[]) => Effect.Effect<void>;
+  readonly destroyAll: Effect.Effect<void>;
+  readonly syncAllAppearance: <E, R>(
+    sync: (window: Electron.BrowserWindow) => Effect.Effect<void, E, R>,
+  ) => Effect.Effect<void, E, R>;
+}
+
+export class ElectronWindow extends Context.Service<ElectronWindow, ElectronWindowShape>()(
+  "t3/desktop/electron/Window",
+) {}
+
+const make = Effect.gen(function* () {
+  const mainWindowRef = yield* Ref.make<Option.Option<Electron.BrowserWindow>>(Option.none());
+
+  const liveMain = Ref.get(mainWindowRef).pipe(
+    Effect.map(Option.filter((value) => !value.isDestroyed())),
+  );
+
+  const currentMainOrFirst = Effect.gen(function* () {
+    const main = yield* liveMain;
+    if (Option.isSome(main)) {
+      return main;
+    }
+
+    return Option.fromNullishOr(Electron.BrowserWindow.getAllWindows()[0] ?? null).pipe(
+      Option.filter((window) => !window.isDestroyed()),
+    );
+  });
+
+  const focusedMainOrFirst = Effect.sync(() =>
+    Option.fromNullishOr(Electron.BrowserWindow.getFocusedWindow() ?? null).pipe(
+      Option.filter((window) => !window.isDestroyed()),
+    ),
+  ).pipe(
+    Effect.flatMap((focused) =>
+      Option.isSome(focused) ? Effect.succeed(focused) : currentMainOrFirst,
+    ),
+  );
+
+  return ElectronWindow.of({
+    create: (options) =>
+      Effect.try({
+        try: () => new Electron.BrowserWindow(options),
+        catch: (cause) => new ElectronWindowCreateError({ cause }),
+      }),
+    main: liveMain,
+    currentMainOrFirst,
+    focusedMainOrFirst,
+    setMain: (window) => Ref.set(mainWindowRef, Option.some(window)),
+    clearMain: (window) =>
+      Ref.update(mainWindowRef, (current) => {
+        if (Option.isNone(current)) {
+          return current;
+        }
+        if (Option.isSome(window) && current.value !== window.value) {
+          return current;
+        }
+        return Option.none();
+      }),
+    reveal: (window) =>
+      Effect.sync(() => {
+        if (window.isDestroyed()) {
+          return;
+        }
+
+        if (window.isMinimized()) {
+          window.restore();
+        }
+
+        if (!window.isVisible()) {
+          window.show();
+        }
+
+        if (process.platform === "darwin") {
+          Electron.app.focus({ steal: true });
+        }
+
+        window.focus();
+      }),
+    sendAll: (channel, ...args) =>
+      Effect.sync(() => {
+        for (const window of Electron.BrowserWindow.getAllWindows()) {
+          if (window.isDestroyed()) {
+            continue;
+          }
+          window.webContents.send(channel, ...args);
+        }
+      }),
+    destroyAll: Effect.sync(() => {
+      for (const window of Electron.BrowserWindow.getAllWindows()) {
+        window.destroy();
+      }
+    }),
+    syncAllAppearance: Effect.fn("desktop.electron.window.syncAllAppearance")(function* <E, R>(
+      sync: (window: Electron.BrowserWindow) => Effect.Effect<void, E, R>,
+    ) {
+      const windows = Electron.BrowserWindow.getAllWindows();
+      for (const window of windows) {
+        if (window.isDestroyed()) {
+          continue;
+        }
+        yield* sync(window);
+      }
+    }),
+  });
+});
+
+export const layer = Layer.effect(ElectronWindow, make);
diff --git a/apps/desktop/src/ipc/DesktopIpc.ts b/apps/desktop/src/ipc/DesktopIpc.ts
new file mode 100644
index 00000000000..05a0f25512e
--- /dev/null
+++ b/apps/desktop/src/ipc/DesktopIpc.ts
@@ -0,0 +1,219 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+
+export interface DesktopIpcInvokeEvent {}
+
+export interface DesktopIpcSyncEvent {
+  returnValue: unknown;
+}
+
+export type DesktopIpcHandleListener = (
+  event: DesktopIpcInvokeEvent,
+  raw: unknown,
+) => unknown | Promise<unknown>;
+
+export type DesktopIpcSyncListener = (event: DesktopIpcSyncEvent) => void;
+
+export interface DesktopIpcMain {
+  removeHandler(channel: string): void;
+  handle(channel: string, listener: DesktopIpcHandleListener): void;
+  removeAllListeners(channel: string): void;
+  on(channel: string, listener: DesktopIpcSyncListener): void;
+}
+
+export interface DesktopIpcMethod<E, R> {
+  readonly channel: string;
+  readonly handler: (raw: unknown) => Effect.Effect<unknown, E, R>;
+}
+
+export interface DesktopSyncIpcMethod<E, R> {
+  readonly channel: string;
+  readonly handler: () => Effect.Effect<unknown, E, R>;
+}
+
+export interface DesktopIpcShape {
+  readonly handle: <E, R>(
+    input: DesktopIpcMethod<E, R>,
+  ) => Effect.Effect<void, never, R | Scope.Scope>;
+  readonly handleSync: <E, R>(
+    input: DesktopSyncIpcMethod<E, R>,
+  ) => Effect.Effect<void, never, R | Scope.Scope>;
+}
+
+export class DesktopIpc extends Context.Service<DesktopIpc, DesktopIpcShape>()("t3/desktop/Ipc") {}
+
+export const make = (ipcMain: DesktopIpcMain): DesktopIpcShape =>
+  DesktopIpc.of({
+    handle: Effect.fn("desktop.ipc.registerInvoke")(function* <E, R>({
+      channel,
+      handler,
+    }: DesktopIpcMethod<E, R>) {
+      yield* Effect.annotateCurrentSpan({ channel });
+      const context = yield* Effect.context<R>();
+      const runPromise = Effect.runPromiseWith(context);
+
+      yield* Effect.acquireRelease(
+        Effect.sync(() => {
+          ipcMain.removeHandler(channel);
+          ipcMain.handle(channel, (_event, raw) =>
+            runPromise(
+              Effect.gen(function* () {
+                yield* Effect.annotateCurrentSpan({ channel });
+                return yield* handler(raw);
+              }).pipe(Effect.annotateLogs({ channel }), Effect.withSpan("desktop.ipc.invoke")),
+            ),
+          );
+        }),
+        () => Effect.sync(() => ipcMain.removeHandler(channel)),
+      );
+    }),
+
+    handleSync: Effect.fn("desktop.ipc.registerSync")(function* <E, R>({
+      channel,
+      handler,
+    }: DesktopSyncIpcMethod<E, R>) {
+      yield* Effect.annotateCurrentSpan({ channel });
+      const context = yield* Effect.context<R>();
+      const runSync = Effect.runSyncWith(context);
+
+      yield* Effect.acquireRelease(
+        Effect.sync(() => {
+          ipcMain.removeAllListeners(channel);
+          ipcMain.on(channel, (event) => {
+            event.returnValue = runSync(
+              Effect.gen(function* () {
+                yield* Effect.annotateCurrentSpan({ channel });
+                return yield* handler();
+              }).pipe(Effect.annotateLogs({ channel }), Effect.withSpan("desktop.ipc.invokeSync")),
+            );
+          });
+        }),
+        () => Effect.sync(() => ipcMain.removeAllListeners(channel)),
+      );
+    }),
+  });
+
+/**
+ * Convenience helpers for creating IPC methods
+ */
+
+export interface DesktopIpcMethodRegistration<
+  Payload,
+  EncodedPayload,
+  Result,
+  EncodedResult,
+  E,
+  R,
+  PayloadDecodingServices = never,
+  PayloadEncodingServices = never,
+  ResultDecodingServices = never,
+  ResultEncodingServices = never,
+> {
+  readonly channel: string;
+  readonly payload: Schema.Codec<
+    Payload,
+    EncodedPayload,
+    PayloadDecodingServices,
+    PayloadEncodingServices
+  >;
+  readonly result: Schema.Codec<
+    Result,
+    EncodedResult,
+    ResultDecodingServices,
+    ResultEncodingServices
+  >;
+  readonly handler: (input: Payload) => Effect.Effect<Result, E, R>;
+}
+
+export const makeIpcMethod = <
+  Payload,
+  EncodedPayload,
+  Result,
+  EncodedResult,
+  E,
+  R,
+  PayloadDecodingServices = never,
+  PayloadEncodingServices = never,
+  ResultDecodingServices = never,
+  ResultEncodingServices = never,
+>(
+  method: DesktopIpcMethodRegistration<
+    Payload,
+    EncodedPayload,
+    Result,
+    EncodedResult,
+    E,
+    R,
+    PayloadDecodingServices,
+    PayloadEncodingServices,
+    ResultDecodingServices,
+    ResultEncodingServices
+  >,
+): DesktopIpcMethod<
+  E | Schema.SchemaError,
+  R | PayloadDecodingServices | ResultEncodingServices
+> => {
+  const decode = Schema.decodeUnknownEffect(method.payload);
+  const encode = Schema.encodeUnknownEffect(method.result);
+
+  return {
+    channel: method.channel,
+    handler: (raw) =>
+      decode(raw).pipe(
+        Effect.flatMap(method.handler),
+        Effect.flatMap(encode),
+        Effect.withSpan("desktop.ipc.method", { attributes: { channel: method.channel } }),
+      ),
+  };
+};
+
+export interface DesktopSyncIpcMethodRegistration<
+  Result,
+  EncodedResult,
+  E,
+  R,
+  ResultDecodingServices = never,
+  ResultEncodingServices = never,
+> {
+  readonly channel: string;
+  readonly result: Schema.Codec<
+    Result,
+    EncodedResult,
+    ResultDecodingServices,
+    ResultEncodingServices
+  >;
+  readonly handler: () => Effect.Effect<Result, E, R>;
+}
+
+export const makeSyncIpcMethod = <
+  Result,
+  EncodedResult,
+  E,
+  R,
+  ResultDecodingServices = never,
+  ResultEncodingServices = never,
+>(
+  method: DesktopSyncIpcMethodRegistration<
+    Result,
+    EncodedResult,
+    E,
+    R,
+    ResultDecodingServices,
+    ResultEncodingServices
+  >,
+): DesktopSyncIpcMethod<E | Schema.SchemaError, R | ResultEncodingServices> => {
+  const encode = Schema.encodeUnknownEffect(method.result);
+
+  return {
+    channel: method.channel,
+    handler: () =>
+      method
+        .handler()
+        .pipe(
+          Effect.flatMap(encode),
+          Effect.withSpan("desktop.ipc.method", { attributes: { channel: method.channel } }),
+        ),
+  };
+};
diff --git a/apps/desktop/src/ipc/DesktopIpcHandlers.ts b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
new file mode 100644
index 00000000000..8717c877951
--- /dev/null
+++ b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
@@ -0,0 +1,84 @@
+import * as Effect from "effect/Effect";
+
+import * as DesktopIpc from "./DesktopIpc.ts";
+import { getClientSettings, setClientSettings } from "./methods/clientSettings.ts";
+import {
+  getSavedEnvironmentRegistry,
+  getSavedEnvironmentSecret,
+  removeSavedEnvironmentSecret,
+  setSavedEnvironmentRegistry,
+  setSavedEnvironmentSecret,
+} from "./methods/savedEnvironments.ts";
+import {
+  getAdvertisedEndpoints,
+  getServerExposureState,
+  setServerExposureMode,
+  setTailscaleServeEnabled,
+} from "./methods/serverExposure.ts";
+import {
+  bootstrapSshBearerSession,
+  disconnectSshEnvironment,
+  discoverSshHosts,
+  ensureSshEnvironment,
+  fetchSshEnvironmentDescriptor,
+  fetchSshSessionState,
+  issueSshWebSocketToken,
+  resolveSshPasswordPrompt,
+} from "./methods/sshEnvironment.ts";
+import {
+  checkForUpdate,
+  downloadUpdate,
+  getUpdateState,
+  installUpdate,
+  setUpdateChannel,
+} from "./methods/updates.ts";
+import {
+  confirm,
+  getAppBranding,
+  getLocalEnvironmentBootstrap,
+  openExternal,
+  pickFolder,
+  setTheme,
+  showContextMenu,
+} from "./methods/window.ts";
+
+export const installDesktopIpcHandlers = Effect.gen(function* () {
+  const ipc = yield* DesktopIpc.DesktopIpc;
+
+  yield* ipc.handleSync(getAppBranding);
+  yield* ipc.handleSync(getLocalEnvironmentBootstrap);
+
+  yield* ipc.handle(getClientSettings);
+  yield* ipc.handle(setClientSettings);
+  yield* ipc.handle(getSavedEnvironmentRegistry);
+  yield* ipc.handle(setSavedEnvironmentRegistry);
+  yield* ipc.handle(getSavedEnvironmentSecret);
+  yield* ipc.handle(setSavedEnvironmentSecret);
+  yield* ipc.handle(removeSavedEnvironmentSecret);
+
+  yield* ipc.handle(discoverSshHosts);
+  yield* ipc.handle(ensureSshEnvironment);
+  yield* ipc.handle(disconnectSshEnvironment);
+  yield* ipc.handle(fetchSshEnvironmentDescriptor);
+  yield* ipc.handle(bootstrapSshBearerSession);
+  yield* ipc.handle(fetchSshSessionState);
+  yield* ipc.handle(issueSshWebSocketToken);
+  yield* ipc.handle(resolveSshPasswordPrompt);
+
+  yield* ipc.handle(getServerExposureState);
+  yield* ipc.handle(setServerExposureMode);
+  yield* ipc.handle(setTailscaleServeEnabled);
+  yield* ipc.handle(getAdvertisedEndpoints);
+
+  yield* ipc.handle(pickFolder);
+  yield* ipc.handle(confirm);
+  yield* ipc.handle(setTheme);
+  yield* ipc.handle(showContextMenu);
+  yield* ipc.handle(openExternal);
+
+  yield* ipc.handle(getUpdateState);
+  yield* ipc.handle(setUpdateChannel);
+  yield* ipc.handle(downloadUpdate);
+  yield* ipc.handle(installUpdate);
+  yield* ipc.handle(checkForUpdate);
+}).pipe(Effect.withSpan("desktop.ipc.installHandlers"));
diff --git a/apps/desktop/src/ipc/channels.ts b/apps/desktop/src/ipc/channels.ts
new file mode 100644
index 00000000000..2715b20cb36
--- /dev/null
+++ b/apps/desktop/src/ipc/channels.ts
@@ -0,0 +1,35 @@
+export const PICK_FOLDER_CHANNEL = "desktop:pick-folder";
+export const CONFIRM_CHANNEL = "desktop:confirm";
+export const SET_THEME_CHANNEL = "desktop:set-theme";
+export const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
+export const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
+export const MENU_ACTION_CHANNEL = "desktop:menu-action";
+export const UPDATE_STATE_CHANNEL = "desktop:update-state";
+export const UPDATE_GET_STATE_CHANNEL = "desktop:update-get-state";
+export const UPDATE_SET_CHANNEL_CHANNEL = "desktop:update-set-channel";
+export const UPDATE_DOWNLOAD_CHANNEL = "desktop:update-download";
+export const UPDATE_INSTALL_CHANNEL = "desktop:update-install";
+export const UPDATE_CHECK_CHANNEL = "desktop:update-check";
+export const GET_APP_BRANDING_CHANNEL = "desktop:get-app-branding";
+export const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL = "desktop:get-local-environment-bootstrap";
+export const GET_CLIENT_SETTINGS_CHANNEL = "desktop:get-client-settings";
+export const SET_CLIENT_SETTINGS_CHANNEL = "desktop:set-client-settings";
+export const GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:get-saved-environment-registry";
+export const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-registry";
+export const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
+export const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
+export const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
+export const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
+export const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+export const DISCONNECT_SSH_ENVIRONMENT_CHANNEL = "desktop:disconnect-ssh-environment";
+export const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
+export const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
+export const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
+export const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
+export const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
+export const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
+export const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
+export const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
+export const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
+export const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
+export const SSH_PASSWORD_PROMPT_CANCELLED_RESULT = "ssh-password-prompt-cancelled";
diff --git a/apps/desktop/src/ipc/methods/clientSettings.ts b/apps/desktop/src/ipc/methods/clientSettings.ts
new file mode 100644
index 00000000000..52b173266cd
--- /dev/null
+++ b/apps/desktop/src/ipc/methods/clientSettings.ts
@@ -0,0 +1,28 @@
+import { ClientSettingsSchema } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
+import * as IpcChannels from "../channels.ts";
+import { makeIpcMethod } from "../DesktopIpc.ts";
+
+export const getClientSettings = makeIpcMethod({
+  channel: IpcChannels.GET_CLIENT_SETTINGS_CHANNEL,
+  payload: Schema.Void,
+  result: Schema.NullOr(ClientSettingsSchema),
+  handler: Effect.fn("desktop.ipc.clientSettings.get")(function* () {
+    const clientSettings = yield* DesktopClientSettings.DesktopClientSettings;
+    return Option.getOrNull(yield* clientSettings.get);
+  }),
+});
+
+export const setClientSettings = makeIpcMethod({
+  channel: IpcChannels.SET_CLIENT_SETTINGS_CHANNEL,
+  payload: ClientSettingsSchema,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.clientSettings.set")(function* (settings) {
+    const clientSettings = yield* DesktopClientSettings.DesktopClientSettings;
+    yield* clientSettings.set(settings);
+  }),
+});
diff --git a/apps/desktop/src/ipc/methods/savedEnvironments.ts b/apps/desktop/src/ipc/methods/savedEnvironments.ts
new file mode 100644
index 00000000000..bc5e4a9aeb2
--- /dev/null
+++ b/apps/desktop/src/ipc/methods/savedEnvironments.ts
@@ -0,0 +1,76 @@
+import { EnvironmentId, PersistedSavedEnvironmentRecordSchema } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import * as DesktopSavedEnvironments from "../../settings/DesktopSavedEnvironments.ts";
+import * as IpcChannels from "../channels.ts";
+import { makeIpcMethod } from "../DesktopIpc.ts";
+
+const SavedEnvironmentRegistryPayload = Schema.Array(PersistedSavedEnvironmentRecordSchema);
+const NonBlankString = Schema.String.check(
+  Schema.makeFilter((value) =>
+    value.trim().length > 0 ? undefined : "Expected a non-empty string",
+  ),
+);
+
+const SetSavedEnvironmentSecretInput = Schema.Struct({
+  environmentId: EnvironmentId,
+  secret: NonBlankString,
+});
+
+export const getSavedEnvironmentRegistry = makeIpcMethod({
+  channel: IpcChannels.GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL,
+  payload: Schema.Void,
+  result: SavedEnvironmentRegistryPayload,
+  handler: Effect.fn("desktop.ipc.savedEnvironments.getRegistry")(function* () {
+    const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+    return yield* savedEnvironments.getRegistry;
+  }),
+});
+
+export const setSavedEnvironmentRegistry = makeIpcMethod({
+  channel: IpcChannels.SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL,
+  payload: SavedEnvironmentRegistryPayload,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.savedEnvironments.setRegistry")(function* (records) {
+    const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+    yield* savedEnvironments.setRegistry(records);
+  }),
+});
+
+export const getSavedEnvironmentSecret = makeIpcMethod({
+  channel: IpcChannels.GET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
+  payload: EnvironmentId,
+  result: Schema.NullOr(Schema.String),
+  handler: Effect.fn("desktop.ipc.savedEnvironments.getSecret")(function* (environmentId) {
+    const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+    return Option.getOrNull(yield* savedEnvironments.getSecret(environmentId));
+  }),
+});
+
+export const setSavedEnvironmentSecret = makeIpcMethod({
+  channel: IpcChannels.SET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
+  payload: SetSavedEnvironmentSecretInput,
+  result: Schema.Boolean,
+  handler: Effect.fn("desktop.ipc.savedEnvironments.setSecret")(function* ({
+    environmentId,
+    secret,
+  }) {
+    const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+    return yield* savedEnvironments.setSecret({
+      environmentId,
+      secret,
+    });
+  }),
+});
+
+export const removeSavedEnvironmentSecret = makeIpcMethod({
+  channel: IpcChannels.REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL,
+  payload: EnvironmentId,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.savedEnvironments.removeSecret")(function* (environmentId) {
+    const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+    yield* savedEnvironments.removeSecret(environmentId);
+  }),
+});
diff --git a/apps/desktop/src/ipc/methods/serverExposure.ts b/apps/desktop/src/ipc/methods/serverExposure.ts
new file mode 100644
index 00000000000..cd0f215e193
--- /dev/null
+++ b/apps/desktop/src/ipc/methods/serverExposure.ts
@@ -0,0 +1,69 @@
+import {
+  AdvertisedEndpoint,
+  DesktopServerExposureModeSchema,
+  DesktopServerExposureStateSchema,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+import * as DesktopLifecycle from "../../app/DesktopLifecycle.ts";
+import * as DesktopServerExposure from "../../backend/DesktopServerExposure.ts";
+import * as IpcChannels from "../channels.ts";
+import { makeIpcMethod } from "../DesktopIpc.ts";
+
+const SetTailscaleServeEnabledInput = Schema.Struct({
+  enabled: Schema.Boolean,
+  port: Schema.optionalKey(Schema.Number),
+});
+
+export const getServerExposureState = makeIpcMethod({
+  channel: IpcChannels.GET_SERVER_EXPOSURE_STATE_CHANNEL,
+  payload: Schema.Void,
+  result: DesktopServerExposureStateSchema,
+  handler: Effect.fn("desktop.ipc.serverExposure.getState")(function* () {
+    const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+    return yield* serverExposure.getState;
+  }),
+});
+
+export const setServerExposureMode = makeIpcMethod({
+  channel: IpcChannels.SET_SERVER_EXPOSURE_MODE_CHANNEL,
+  payload: DesktopServerExposureModeSchema,
+  result: DesktopServerExposureStateSchema,
+  handler: Effect.fn("desktop.ipc.serverExposure.setMode")(function* (mode) {
+    const lifecycle = yield* DesktopLifecycle.DesktopLifecycle;
+    const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+    const change = yield* serverExposure.setMode(mode);
+    if (change.requiresRelaunch) {
+      yield* lifecycle.relaunch(`serverExposureMode=${mode}`);
+    }
+    return change.state;
+  }),
+});
+
+export const setTailscaleServeEnabled = makeIpcMethod({
+  channel: IpcChannels.SET_TAILSCALE_SERVE_ENABLED_CHANNEL,
+  payload: SetTailscaleServeEnabledInput,
+  result: DesktopServerExposureStateSchema,
+  handler: Effect.fn("desktop.ipc.serverExposure.setTailscaleServeEnabled")(function* (input) {
+    const lifecycle = yield* DesktopLifecycle.DesktopLifecycle;
+    const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+    const change = yield* serverExposure.setTailscaleServeEnabled(input);
+    if (change.requiresRelaunch) {
+      yield* lifecycle.relaunch(
+        change.state.tailscaleServeEnabled ? "tailscale-serve-enabled" : "tailscale-serve-disabled",
+      );
+    }
+    return change.state;
+  }),
+});
+
+export const getAdvertisedEndpoints = makeIpcMethod({
+  channel: IpcChannels.GET_ADVERTISED_ENDPOINTS_CHANNEL,
+  payload: Schema.Void,
+  result: Schema.Array(AdvertisedEndpoint),
+  handler: Effect.fn("desktop.ipc.serverExposure.getAdvertisedEndpoints")(function* () {
+    const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+    return yield* serverExposure.getAdvertisedEndpoints;
+  }),
+});
diff --git a/apps/desktop/src/ipc/methods/sshEnvironment.ts b/apps/desktop/src/ipc/methods/sshEnvironment.ts
new file mode 100644
index 00000000000..efea3dd132d
--- /dev/null
+++ b/apps/desktop/src/ipc/methods/sshEnvironment.ts
@@ -0,0 +1,127 @@
+import {
+  DesktopDiscoveredSshHostSchema,
+  DesktopSshBearerBootstrapInputSchema,
+  DesktopSshBearerRequestInputSchema,
+  DesktopSshEnvironmentEnsureInputSchema,
+  DesktopSshEnvironmentEnsureResultSchema,
+  DesktopSshEnvironmentTargetSchema,
+  DesktopSshHttpBaseUrlInputSchema,
+  DesktopSshPasswordPromptCancelledType,
+  DesktopSshPasswordPromptResolutionInputSchema,
+  ExecutionEnvironmentDescriptor,
+  AuthBearerBootstrapResult,
+  AuthSessionState,
+  AuthWebSocketTokenResult,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+import * as IpcChannels from "../channels.ts";
+import { makeIpcMethod } from "../DesktopIpc.ts";
+import * as DesktopSshEnvironment from "../../ssh/DesktopSshEnvironment.ts";
+import * as DesktopSshPasswordPrompts from "../../ssh/DesktopSshPasswordPrompts.ts";
+import * as DesktopSshRemoteApi from "../../ssh/DesktopSshRemoteApi.ts";
+
+export const discoverSshHosts = makeIpcMethod({
+  channel: IpcChannels.DISCOVER_SSH_HOSTS_CHANNEL,
+  payload: Schema.Void,
+  result: Schema.Array(DesktopDiscoveredSshHostSchema),
+  handler: Effect.fn("desktop.ipc.sshEnvironment.discoverHosts")(function* () {
+    const sshEnvironment = yield* DesktopSshEnvironment.DesktopSshEnvironment;
+    return yield* sshEnvironment.discoverHosts();
+  }),
+});
+
+export const ensureSshEnvironment = makeIpcMethod({
+  channel: IpcChannels.ENSURE_SSH_ENVIRONMENT_CHANNEL,
+  payload: DesktopSshEnvironmentEnsureInputSchema,
+  result: DesktopSshEnvironmentEnsureResultSchema,
+  handler: Effect.fn("desktop.ipc.sshEnvironment.ensureEnvironment")(function* ({
+    target,
+    options,
+  }) {
+    const sshEnvironment = yield* DesktopSshEnvironment.DesktopSshEnvironment;
+    return yield* sshEnvironment.ensureEnvironment(target, options).pipe(
+      Effect.catch((error) =>
+        DesktopSshEnvironment.isDesktopSshPasswordPromptCancellation(error)
+          ? Effect.succeed({
+              type: DesktopSshPasswordPromptCancelledType,
+              message: error.message,
+            })
+          : Effect.fail(error),
+      ),
+    );
+  }),
+});
+
+export const disconnectSshEnvironment = makeIpcMethod({
+  channel: IpcChannels.DISCONNECT_SSH_ENVIRONMENT_CHANNEL,
+  payload: DesktopSshEnvironmentTargetSchema,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.sshEnvironment.disconnectEnvironment")(function* (target) {
+    const sshEnvironment = yield* DesktopSshEnvironment.DesktopSshEnvironment;
+    yield* sshEnvironment.disconnectEnvironment(target);
+  }),
+});
+
+export const fetchSshEnvironmentDescriptor = makeIpcMethod({
+  channel: IpcChannels.FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL,
+  payload: DesktopSshHttpBaseUrlInputSchema,
+  result: ExecutionEnvironmentDescriptor,
+  handler: Effect.fn("desktop.ipc.sshEnvironment.fetchDescriptor")(function* ({ httpBaseUrl }) {
+    const remoteApi = yield* DesktopSshRemoteApi.DesktopSshRemoteApi;
+    return yield* remoteApi.fetchEnvironmentDescriptor({ httpBaseUrl });
+  }),
+});
+
+export const bootstrapSshBearerSession = makeIpcMethod({
+  channel: IpcChannels.BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL,
+  payload: DesktopSshBearerBootstrapInputSchema,
+  result: AuthBearerBootstrapResult,
+  handler: Effect.fn("desktop.ipc.sshEnvironment.bootstrapBearerSession")(function* ({
+    httpBaseUrl,
+    credential,
+  }) {
+    const remoteApi = yield* DesktopSshRemoteApi.DesktopSshRemoteApi;
+    return yield* remoteApi.bootstrapBearerSession({ httpBaseUrl, credential });
+  }),
+});
+
+export const fetchSshSessionState = makeIpcMethod({
+  channel: IpcChannels.FETCH_SSH_SESSION_STATE_CHANNEL,
+  payload: DesktopSshBearerRequestInputSchema,
+  result: AuthSessionState,
+  handler: Effect.fn("desktop.ipc.sshEnvironment.fetchSessionState")(function* ({
+    httpBaseUrl,
+    bearerToken,
+  }) {
+    const remoteApi = yield* DesktopSshRemoteApi.DesktopSshRemoteApi;
+    return yield* remoteApi.fetchSessionState({ httpBaseUrl, bearerToken });
+  }),
+});
+
+export const issueSshWebSocketToken = makeIpcMethod({
+  channel: IpcChannels.ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL,
+  payload: DesktopSshBearerRequestInputSchema,
+  result: AuthWebSocketTokenResult,
+  handler: Effect.fn("desktop.ipc.sshEnvironment.issueWebSocketToken")(function* ({
+    httpBaseUrl,
+    bearerToken,
+  }) {
+    const remoteApi = yield* DesktopSshRemoteApi.DesktopSshRemoteApi;
+    return yield* remoteApi.issueWebSocketToken({ httpBaseUrl, bearerToken });
+  }),
+});
+
+export const resolveSshPasswordPrompt = makeIpcMethod({
+  channel: IpcChannels.RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL,
+  payload: DesktopSshPasswordPromptResolutionInputSchema,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.sshEnvironment.resolvePasswordPrompt")(function* ({
+    requestId,
+    password,
+  }) {
+    const prompts = yield* DesktopSshPasswordPrompts.DesktopSshPasswordPrompts;
+    yield* prompts.resolve({ requestId, password });
+  }),
+});
diff --git a/apps/desktop/src/ipc/methods/updates.ts b/apps/desktop/src/ipc/methods/updates.ts
new file mode 100644
index 00000000000..45ea8502121
--- /dev/null
+++ b/apps/desktop/src/ipc/methods/updates.ts
@@ -0,0 +1,62 @@
+import {
+  DesktopUpdateActionResultSchema,
+  DesktopUpdateChannelSchema,
+  DesktopUpdateCheckResultSchema,
+  DesktopUpdateStateSchema,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+import * as DesktopUpdates from "../../updates/DesktopUpdates.ts";
+import * as IpcChannels from "../channels.ts";
+import { makeIpcMethod } from "../DesktopIpc.ts";
+
+export const getUpdateState = makeIpcMethod({
+  channel: IpcChannels.UPDATE_GET_STATE_CHANNEL,
+  payload: Schema.Void,
+  result: DesktopUpdateStateSchema,
+  handler: Effect.fn("desktop.ipc.updates.getState")(function* () {
+    const updates = yield* DesktopUpdates.DesktopUpdates;
+    return yield* updates.getState;
+  }),
+});
+
+export const setUpdateChannel = makeIpcMethod({
+  channel: IpcChannels.UPDATE_SET_CHANNEL_CHANNEL,
+  payload: DesktopUpdateChannelSchema,
+  result: DesktopUpdateStateSchema,
+  handler: Effect.fn("desktop.ipc.updates.setChannel")(function* (channel) {
+    const updates = yield* DesktopUpdates.DesktopUpdates;
+    return yield* updates.setChannel(channel);
+  }),
+});
+
+export const downloadUpdate = makeIpcMethod({
+  channel: IpcChannels.UPDATE_DOWNLOAD_CHANNEL,
+  payload: Schema.Void,
+  result: DesktopUpdateActionResultSchema,
+  handler: Effect.fn("desktop.ipc.updates.download")(function* () {
+    const updates = yield* DesktopUpdates.DesktopUpdates;
+    return yield* updates.download;
+  }),
+});
+
+export const installUpdate = makeIpcMethod({
+  channel: IpcChannels.UPDATE_INSTALL_CHANNEL,
+  payload: Schema.Void,
+  result: DesktopUpdateActionResultSchema,
+  handler: Effect.fn("desktop.ipc.updates.install")(function* () {
+    const updates = yield* DesktopUpdates.DesktopUpdates;
+    return yield* updates.install;
+  }),
+});
+
+export const checkForUpdate = makeIpcMethod({
+  channel: IpcChannels.UPDATE_CHECK_CHANNEL,
+  payload: Schema.Void,
+  result: DesktopUpdateCheckResultSchema,
+  handler: Effect.fn("desktop.ipc.updates.check")(function* () {
+    const updates = yield* DesktopUpdates.DesktopUpdates;
+    return yield* updates.check("web-ui");
+  }),
+});
diff --git a/apps/desktop/src/ipc/methods/window.ts b/apps/desktop/src/ipc/methods/window.ts
new file mode 100644
index 00000000000..1cb4d7265a1
--- /dev/null
+++ b/apps/desktop/src/ipc/methods/window.ts
@@ -0,0 +1,135 @@
+import {
+  ContextMenuItemSchema,
+  DesktopAppBrandingSchema,
+  DesktopEnvironmentBootstrapSchema,
+  DesktopThemeSchema,
+  PickFolderOptionsSchema,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import * as DesktopBackendManager from "../../backend/DesktopBackendManager.ts";
+import * as DesktopEnvironment from "../../app/DesktopEnvironment.ts";
+import * as ElectronDialog from "../../electron/ElectronDialog.ts";
+import * as ElectronMenu from "../../electron/ElectronMenu.ts";
+import * as ElectronShell from "../../electron/ElectronShell.ts";
+import * as ElectronTheme from "../../electron/ElectronTheme.ts";
+import * as ElectronWindow from "../../electron/ElectronWindow.ts";
+import * as IpcChannels from "../channels.ts";
+import { makeIpcMethod, makeSyncIpcMethod } from "../DesktopIpc.ts";
+
+const ContextMenuPosition = Schema.Struct({
+  x: Schema.Number,
+  y: Schema.Number,
+});
+
+const ContextMenuInput = Schema.Struct({
+  items: Schema.Array(ContextMenuItemSchema),
+  position: Schema.optionalKey(ContextMenuPosition),
+});
+
+function toWebSocketBaseUrl(httpBaseUrl: URL): string {
+  const url = new URL(httpBaseUrl.href);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.href;
+}
+
+export const getAppBranding = makeSyncIpcMethod({
+  channel: IpcChannels.GET_APP_BRANDING_CHANNEL,
+  result: Schema.NullOr(DesktopAppBrandingSchema),
+  handler: Effect.fn("desktop.ipc.window.getAppBranding")(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    return environment.branding;
+  }),
+});
+
+export const getLocalEnvironmentBootstrap = makeSyncIpcMethod({
+  channel: IpcChannels.GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL,
+  result: Schema.NullOr(DesktopEnvironmentBootstrapSchema),
+  handler: Effect.fn("desktop.ipc.window.getLocalEnvironmentBootstrap")(function* () {
+    const backendManager = yield* DesktopBackendManager.DesktopBackendManager;
+    const config = yield* backendManager.currentConfig;
+    return Option.match(config, {
+      onNone: () => null,
+      onSome: ({ bootstrap, httpBaseUrl }) => ({
+        label: "Local environment",
+        httpBaseUrl: httpBaseUrl.href,
+        wsBaseUrl: toWebSocketBaseUrl(httpBaseUrl),
+        ...(bootstrap.desktopBootstrapToken
+          ? { bootstrapToken: bootstrap.desktopBootstrapToken }
+          : {}),
+      }),
+    });
+  }),
+});
+
+export const pickFolder = makeIpcMethod({
+  channel: IpcChannels.PICK_FOLDER_CHANNEL,
+  payload: Schema.UndefinedOr(PickFolderOptionsSchema),
+  result: Schema.NullOr(Schema.String),
+  handler: Effect.fn("desktop.ipc.window.pickFolder")(function* (options) {
+    const dialog = yield* ElectronDialog.ElectronDialog;
+    const electronWindow = yield* ElectronWindow.ElectronWindow;
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const selectedPath = yield* dialog.pickFolder({
+      owner: yield* electronWindow.focusedMainOrFirst,
+      defaultPath: environment.resolvePickFolderDefaultPath(options),
+    });
+    return Option.getOrNull(selectedPath);
+  }),
+});
+
+export const confirm = makeIpcMethod({
+  channel: IpcChannels.CONFIRM_CHANNEL,
+  payload: Schema.String,
+  result: Schema.Boolean,
+  handler: Effect.fn("desktop.ipc.window.confirm")(function* (message) {
+    const dialog = yield* ElectronDialog.ElectronDialog;
+    const electronWindow = yield* ElectronWindow.ElectronWindow;
+    return yield* electronWindow.focusedMainOrFirst.pipe(
+      Effect.flatMap((owner) => dialog.confirm({ owner, message })),
+    );
+  }),
+});
+
+export const setTheme = makeIpcMethod({
+  channel: IpcChannels.SET_THEME_CHANNEL,
+  payload: DesktopThemeSchema,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.window.setTheme")(function* (theme) {
+    const electronTheme = yield* ElectronTheme.ElectronTheme;
+    yield* electronTheme.setSource(theme);
+  }),
+});
+
+export const showContextMenu = makeIpcMethod({
+  channel: IpcChannels.CONTEXT_MENU_CHANNEL,
+  payload: ContextMenuInput,
+  result: Schema.NullOr(Schema.String),
+  handler: Effect.fn("desktop.ipc.window.showContextMenu")(function* (input) {
+    const electronMenu = yield* ElectronMenu.ElectronMenu;
+    const electronWindow = yield* ElectronWindow.ElectronWindow;
+    const window = yield* electronWindow.focusedMainOrFirst;
+    if (Option.isNone(window)) {
+      return null;
+    }
+
+    const selectedItemId = yield* electronMenu.showContextMenu({
+      window: window.value,
+      items: input.items,
+      position: Option.fromNullishOr(input.position),
+    });
+    return Option.getOrNull(selectedItemId);
+  }),
+});
+
+export const openExternal = makeIpcMethod({
+  channel: IpcChannels.OPEN_EXTERNAL_CHANNEL,
+  payload: Schema.String,
+  result: Schema.Boolean,
+  handler: Effect.fn("desktop.ipc.window.openExternal")(function* (url) {
+    const shell = yield* ElectronShell.ElectronShell;
+    return yield* shell.openExternal(url);
+  }),
+});
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index ef30d3b4bbb..0bc1badff2d 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -1,1910 +1,154 @@
-import * as ChildProcess from "node:child_process";
-import * as Crypto from "node:crypto";
-import * as FS from "node:fs";
-import * as OS from "node:os";
-import * as Path from "node:path";
-
-import {
-  app,
-  BrowserWindow,
-  clipboard,
-  dialog,
-  ipcMain,
-  Menu,
-  nativeImage,
-  nativeTheme,
-  protocol,
-  safeStorage,
-  shell,
-} from "electron";
-import type { MenuItemConstructorOptions } from "electron";
-import type {
-  ClientSettings,
-  DesktopTheme,
-  DesktopServerExposureMode,
-  DesktopServerExposureState,
-  PersistedSavedEnvironmentRecord,
-  DesktopUpdateActionResult,
-  DesktopUpdateCheckResult,
-  DesktopUpdateState,
-} from "@t3tools/contracts";
-import { autoUpdater } from "electron-updater";
-
-import type { ContextMenuItem } from "@t3tools/contracts";
-import { RotatingFileSink } from "@t3tools/shared/logging";
-import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
-import { DEFAULT_DESKTOP_BACKEND_PORT, resolveDesktopBackendPort } from "./backendPort";
-import {
-  DEFAULT_DESKTOP_SETTINGS,
-  readDesktopSettings,
-  setDesktopServerExposurePreference,
-  writeDesktopSettings,
-} from "./desktopSettings";
-import {
-  readClientSettings,
-  readSavedEnvironmentRegistry,
-  readSavedEnvironmentSecret,
-  removeSavedEnvironmentSecret,
-  writeClientSettings,
-  writeSavedEnvironmentRegistry,
-  writeSavedEnvironmentSecret,
-} from "./clientPersistence";
-import { isBackendReadinessAborted, waitForHttpReady } from "./backendReadiness";
-import { showDesktopConfirmDialog } from "./confirmDialog";
-import { resolveDesktopServerExposure } from "./serverExposure";
-import { syncShellEnvironment } from "./syncShellEnvironment";
-import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState";
-import {
-  createInitialDesktopUpdateState,
-  reduceDesktopUpdateStateOnCheckFailure,
-  reduceDesktopUpdateStateOnCheckStart,
-  reduceDesktopUpdateStateOnDownloadComplete,
-  reduceDesktopUpdateStateOnDownloadFailure,
-  reduceDesktopUpdateStateOnDownloadProgress,
-  reduceDesktopUpdateStateOnDownloadStart,
-  reduceDesktopUpdateStateOnInstallFailure,
-  reduceDesktopUpdateStateOnNoUpdate,
-  reduceDesktopUpdateStateOnUpdateAvailable,
-} from "./updateMachine";
-import { isArm64HostRunningIntelBuild, resolveDesktopRuntimeInfo } from "./runtimeArch";
-
-syncShellEnvironment();
-
-const PICK_FOLDER_CHANNEL = "desktop:pick-folder";
-const CONFIRM_CHANNEL = "desktop:confirm";
-const SET_THEME_CHANNEL = "desktop:set-theme";
-const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
-const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
-const MENU_ACTION_CHANNEL = "desktop:menu-action";
-const UPDATE_STATE_CHANNEL = "desktop:update-state";
-const UPDATE_GET_STATE_CHANNEL = "desktop:update-get-state";
-const UPDATE_DOWNLOAD_CHANNEL = "desktop:update-download";
-const UPDATE_INSTALL_CHANNEL = "desktop:update-install";
-const UPDATE_CHECK_CHANNEL = "desktop:update-check";
-const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL = "desktop:get-local-environment-bootstrap";
-const GET_CLIENT_SETTINGS_CHANNEL = "desktop:get-client-settings";
-const SET_CLIENT_SETTINGS_CHANNEL = "desktop:set-client-settings";
-const GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:get-saved-environment-registry";
-const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-registry";
-const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
-const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
-const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
-const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
-const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
-const BASE_DIR = process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
-const STATE_DIR = Path.join(BASE_DIR, "userdata");
-const DESKTOP_SETTINGS_PATH = Path.join(STATE_DIR, "desktop-settings.json");
-const CLIENT_SETTINGS_PATH = Path.join(STATE_DIR, "client-settings.json");
-const SAVED_ENVIRONMENT_REGISTRY_PATH = Path.join(STATE_DIR, "saved-environments.json");
-const DESKTOP_SCHEME = "t3";
-const ROOT_DIR = Path.resolve(__dirname, "../../..");
-const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
-const APP_DISPLAY_NAME = isDevelopment ? "T3 Code (Dev)" : "T3 Code (Alpha)";
-const APP_USER_MODEL_ID = isDevelopment ? "com.t3tools.t3code.dev" : "com.t3tools.t3code";
-const LINUX_DESKTOP_ENTRY_NAME = isDevelopment ? "t3code-dev.desktop" : "t3code.desktop";
-const LINUX_WM_CLASS = isDevelopment ? "t3code-dev" : "t3code";
-const USER_DATA_DIR_NAME = isDevelopment ? "t3code-dev" : "t3code";
-const LEGACY_USER_DATA_DIR_NAME = isDevelopment ? "T3 Code (Dev)" : "T3 Code (Alpha)";
-const COMMIT_HASH_PATTERN = /^[0-9a-f]{7,40}$/i;
-const COMMIT_HASH_DISPLAY_LENGTH = 12;
-const LOG_DIR = Path.join(STATE_DIR, "logs");
-const LOG_FILE_MAX_BYTES = 10 * 1024 * 1024;
-const LOG_FILE_MAX_FILES = 10;
-const APP_RUN_ID = Crypto.randomBytes(6).toString("hex");
-const SERVER_SETTINGS_PATH = Path.join(STATE_DIR, "settings.json");
-const AUTO_UPDATE_STARTUP_DELAY_MS = 15_000;
-const AUTO_UPDATE_POLL_INTERVAL_MS = 4 * 60 * 60 * 1000;
-const DESKTOP_UPDATE_CHANNEL = "latest";
-const DESKTOP_UPDATE_ALLOW_PRERELEASE = false;
-const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
-const DESKTOP_REQUIRED_PORT_PROBE_HOSTS = ["0.0.0.0", "::"] as const;
-
-type DesktopUpdateErrorContext = DesktopUpdateState["errorContext"];
-type LinuxDesktopNamedApp = Electron.App & {
-  setDesktopName?: (desktopName: string) => void;
-};
-
-let mainWindow: BrowserWindow | null = null;
-let backendProcess: ChildProcess.ChildProcess | null = null;
-let backendPort = 0;
-let backendBindHost = DESKTOP_LOOPBACK_HOST;
-let backendBootstrapToken = "";
-let backendHttpUrl = "";
-let backendWsUrl = "";
-let backendEndpointUrl: string | null = null;
-let backendAdvertisedHost: string | null = null;
-let backendReadinessAbortController: AbortController | null = null;
-let restartAttempt = 0;
-let restartTimer: ReturnType<typeof setTimeout> | null = null;
-let isQuitting = false;
-let desktopProtocolRegistered = false;
-let aboutCommitHashCache: string | null | undefined;
-let desktopLogSink: RotatingFileSink | null = null;
-let backendLogSink: RotatingFileSink | null = null;
-let restoreStdIoCapture: (() => void) | null = null;
-let backendObservabilitySettings = readPersistedBackendObservabilitySettings();
-let desktopSettings = readDesktopSettings(DESKTOP_SETTINGS_PATH);
-let desktopServerExposureMode: DesktopServerExposureMode = desktopSettings.serverExposureMode;
-
-let destructiveMenuIconCache: Electron.NativeImage | null | undefined;
-const expectedBackendExitChildren = new WeakSet<ChildProcess.ChildProcess>();
-const desktopRuntimeInfo = resolveDesktopRuntimeInfo({
-  platform: process.platform,
-  processArch: process.arch,
-  runningUnderArm64Translation: app.runningUnderARM64Translation === true,
-});
-const initialUpdateState = (): DesktopUpdateState =>
-  createInitialDesktopUpdateState(app.getVersion(), desktopRuntimeInfo);
-
-function logTimestamp(): string {
-  return new Date().toISOString();
-}
-
-function logScope(scope: string): string {
-  return `${scope} run=${APP_RUN_ID}`;
-}
-
-function sanitizeLogValue(value: string): string {
-  return value.replace(/\s+/g, " ").trim();
-}
-
-function readPersistedBackendObservabilitySettings(): {
-  readonly otlpTracesUrl: string | undefined;
-  readonly otlpMetricsUrl: string | undefined;
-} {
-  try {
-    if (!FS.existsSync(SERVER_SETTINGS_PATH)) {
-      return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
-    }
-    return parsePersistedServerObservabilitySettings(FS.readFileSync(SERVER_SETTINGS_PATH, "utf8"));
-  } catch (error) {
-    console.warn("[desktop] failed to read persisted backend observability settings", error);
-    return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
-  }
-}
-
-function resolveConfiguredDesktopBackendPort(rawPort: string | undefined): number | undefined {
-  if (!rawPort) {
-    return undefined;
-  }
-
-  const parsedPort = Number.parseInt(rawPort, 10);
-  if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65_535) {
-    return undefined;
-  }
-
-  return parsedPort;
-}
-
-function resolveDesktopDevServerUrl(): string {
-  const devServerUrl = process.env.VITE_DEV_SERVER_URL?.trim();
-  if (!devServerUrl) {
-    throw new Error("VITE_DEV_SERVER_URL is required in desktop development.");
-  }
-
-  return devServerUrl;
-}
-
-function backendChildEnv(): NodeJS.ProcessEnv {
-  const env = { ...process.env };
-  delete env.T3CODE_PORT;
-  delete env.T3CODE_MODE;
-  delete env.T3CODE_NO_BROWSER;
-  delete env.T3CODE_HOST;
-  delete env.T3CODE_DESKTOP_WS_URL;
-  delete env.T3CODE_DESKTOP_LAN_ACCESS;
-  delete env.T3CODE_DESKTOP_LAN_HOST;
-  return env;
-}
-
-function getDesktopServerExposureState(): DesktopServerExposureState {
-  return {
-    mode: desktopServerExposureMode,
-    endpointUrl: backendEndpointUrl,
-    advertisedHost: backendAdvertisedHost,
-  };
-}
-
-function getDesktopSecretStorage() {
-  return {
-    isEncryptionAvailable: () => safeStorage.isEncryptionAvailable(),
-    encryptString: (value: string) => safeStorage.encryptString(value),
-    decryptString: (value: Buffer) => safeStorage.decryptString(value),
-  } as const;
-}
-
-function resolveAdvertisedHostOverride(): string | undefined {
-  const override = process.env.T3CODE_DESKTOP_LAN_HOST?.trim();
-  return override && override.length > 0 ? override : undefined;
-}
-
-async function applyDesktopServerExposureMode(
-  mode: DesktopServerExposureMode,
-  options?: { readonly persist?: boolean; readonly rejectIfUnavailable?: boolean },
-): Promise<DesktopServerExposureState> {
-  const advertisedHostOverride = resolveAdvertisedHostOverride();
-  const requestedMode = mode;
-  let exposure = resolveDesktopServerExposure({
-    mode,
-    port: backendPort,
-    networkInterfaces: OS.networkInterfaces(),
-    ...(advertisedHostOverride ? { advertisedHostOverride } : {}),
-  });
-
-  if (requestedMode === "network-accessible" && exposure.endpointUrl === null) {
-    if (options?.rejectIfUnavailable) {
-      throw new Error("No reachable network address is available for this desktop right now.");
-    }
-    exposure = resolveDesktopServerExposure({
-      mode: "local-only",
-      port: backendPort,
-      networkInterfaces: OS.networkInterfaces(),
-      ...(advertisedHostOverride ? { advertisedHostOverride } : {}),
-    });
-  }
-
-  desktopServerExposureMode = exposure.mode;
-  desktopSettings = setDesktopServerExposurePreference(desktopSettings, requestedMode);
-  backendBindHost = exposure.bindHost;
-  backendHttpUrl = exposure.localHttpUrl;
-  backendWsUrl = exposure.localWsUrl;
-  backendEndpointUrl = exposure.endpointUrl;
-  backendAdvertisedHost = exposure.advertisedHost;
-
-  if (options?.persist) {
-    writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
-  }
-
-  return getDesktopServerExposureState();
-}
-
-function relaunchDesktopApp(reason: string): void {
-  writeDesktopLogHeader(`desktop relaunch requested reason=${reason}`);
-  setImmediate(() => {
-    isQuitting = true;
-    clearUpdatePollTimer();
-    cancelBackendReadinessWait();
-    void stopBackendAndWaitForExit()
-      .catch((error) => {
-        writeDesktopLogHeader(
-          `desktop relaunch backend shutdown warning message=${formatErrorMessage(error)}`,
-        );
-      })
-      .finally(() => {
-        restoreStdIoCapture?.();
-        if (isDevelopment) {
-          app.exit(75);
-          return;
-        }
-        app.relaunch({
-          execPath: process.execPath,
-          args: process.argv.slice(1),
-        });
-        app.exit(0);
-      });
-  });
-}
-
-function writeDesktopLogHeader(message: string): void {
-  if (!desktopLogSink) return;
-  desktopLogSink.write(`[${logTimestamp()}] [${logScope("desktop")}] ${message}\n`);
-}
-
-function writeBackendSessionBoundary(phase: "START" | "END", details: string): void {
-  if (!backendLogSink) return;
-  const normalizedDetails = sanitizeLogValue(details);
-  backendLogSink.write(
-    `[${logTimestamp()}] ---- APP SESSION ${phase} run=${APP_RUN_ID} ${normalizedDetails} ----\n`,
-  );
-}
-
-function formatErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return String(error);
-}
-
-function getSafeExternalUrl(rawUrl: unknown): string | null {
-  if (typeof rawUrl !== "string" || rawUrl.length === 0) {
-    return null;
-  }
-
-  let parsedUrl: URL;
-  try {
-    parsedUrl = new URL(rawUrl);
-  } catch {
-    return null;
-  }
-
-  if (parsedUrl.protocol !== "https:" && parsedUrl.protocol !== "http:") {
-    return null;
-  }
-
-  return parsedUrl.toString();
-}
-
-function getSafeTheme(rawTheme: unknown): DesktopTheme | null {
-  if (rawTheme === "light" || rawTheme === "dark" || rawTheme === "system") {
-    return rawTheme;
-  }
-
-  return null;
-}
-
-async function waitForBackendHttpReady(baseUrl: string): Promise<void> {
-  cancelBackendReadinessWait();
-  const controller = new AbortController();
-  backendReadinessAbortController = controller;
-
-  try {
-    await waitForHttpReady(baseUrl, {
-      signal: controller.signal,
-    });
-  } finally {
-    if (backendReadinessAbortController === controller) {
-      backendReadinessAbortController = null;
-    }
-  }
-}
-
-function cancelBackendReadinessWait(): void {
-  backendReadinessAbortController?.abort();
-  backendReadinessAbortController = null;
-}
-
-function writeDesktopStreamChunk(
-  streamName: "stdout" | "stderr",
-  chunk: unknown,
-  encoding: BufferEncoding | undefined,
-): void {
-  if (!desktopLogSink) return;
-  const buffer = Buffer.isBuffer(chunk)
-    ? chunk
-    : Buffer.from(String(chunk), typeof chunk === "string" ? encoding : undefined);
-  desktopLogSink.write(`[${logTimestamp()}] [${logScope(streamName)}] `);
-  desktopLogSink.write(buffer);
-  if (buffer.length === 0 || buffer[buffer.length - 1] !== 0x0a) {
-    desktopLogSink.write("\n");
-  }
-}
-
-function installStdIoCapture(): void {
-  if (!app.isPackaged || desktopLogSink === null || restoreStdIoCapture !== null) {
-    return;
-  }
-
-  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
-  const originalStderrWrite = process.stderr.write.bind(process.stderr);
-
-  const patchWrite =
-    (streamName: "stdout" | "stderr", originalWrite: typeof process.stdout.write) =>
-    (
-      chunk: string | Uint8Array,
-      encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
-      callback?: (error?: Error | null) => void,
-    ): boolean => {
-      const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
-      writeDesktopStreamChunk(streamName, chunk, encoding);
-      if (typeof encodingOrCallback === "function") {
-        return originalWrite(chunk, encodingOrCallback);
-      }
-      if (callback !== undefined) {
-        return originalWrite(chunk, encoding, callback);
-      }
-      if (encoding !== undefined) {
-        return originalWrite(chunk, encoding);
-      }
-      return originalWrite(chunk);
-    };
-
-  process.stdout.write = patchWrite("stdout", originalStdoutWrite);
-  process.stderr.write = patchWrite("stderr", originalStderrWrite);
-
-  restoreStdIoCapture = () => {
-    process.stdout.write = originalStdoutWrite;
-    process.stderr.write = originalStderrWrite;
-    restoreStdIoCapture = null;
-  };
-}
-
-function initializePackagedLogging(): void {
-  if (!app.isPackaged) return;
-  try {
-    desktopLogSink = new RotatingFileSink({
-      filePath: Path.join(LOG_DIR, "desktop-main.log"),
-      maxBytes: LOG_FILE_MAX_BYTES,
-      maxFiles: LOG_FILE_MAX_FILES,
-    });
-    backendLogSink = new RotatingFileSink({
-      filePath: Path.join(LOG_DIR, "server-child.log"),
-      maxBytes: LOG_FILE_MAX_BYTES,
-      maxFiles: LOG_FILE_MAX_FILES,
-    });
-    installStdIoCapture();
-    writeDesktopLogHeader(`runtime log capture enabled logDir=${LOG_DIR}`);
-  } catch (error) {
-    // Logging setup should never block app startup.
-    console.error("[desktop] failed to initialize packaged logging", error);
-  }
-}
-
-function captureBackendOutput(child: ChildProcess.ChildProcess): void {
-  if (!app.isPackaged || backendLogSink === null) return;
-  const writeChunk = (chunk: unknown): void => {
-    if (!backendLogSink) return;
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
-    backendLogSink.write(buffer);
-  };
-  child.stdout?.on("data", writeChunk);
-  child.stderr?.on("data", writeChunk);
-}
-
-initializePackagedLogging();
-
-if (process.platform === "linux") {
-  app.commandLine.appendSwitch("class", LINUX_WM_CLASS);
-}
-
-function getDestructiveMenuIcon(): Electron.NativeImage | undefined {
-  if (process.platform !== "darwin") return undefined;
-  if (destructiveMenuIconCache !== undefined) {
-    return destructiveMenuIconCache ?? undefined;
-  }
-  try {
-    const icon = nativeImage.createFromNamedImage("trash").resize({
-      width: 14,
-      height: 14,
-    });
-    if (icon.isEmpty()) {
-      destructiveMenuIconCache = null;
-      return undefined;
-    }
-    icon.setTemplateImage(true);
-    destructiveMenuIconCache = icon;
-    return icon;
-  } catch {
-    destructiveMenuIconCache = null;
-    return undefined;
-  }
-}
-let updatePollTimer: ReturnType<typeof setInterval> | null = null;
-let updateStartupTimer: ReturnType<typeof setTimeout> | null = null;
-let updateCheckInFlight = false;
-let updateDownloadInFlight = false;
-let updateInstallInFlight = false;
-let updaterConfigured = false;
-let updateState: DesktopUpdateState = initialUpdateState();
-
-function resolveUpdaterErrorContext(): DesktopUpdateErrorContext {
-  if (updateInstallInFlight) return "install";
-  if (updateDownloadInFlight) return "download";
-  if (updateCheckInFlight) return "check";
-  return updateState.errorContext;
-}
-
-protocol.registerSchemesAsPrivileged([
-  {
-    scheme: DESKTOP_SCHEME,
-    privileges: {
-      standard: true,
-      secure: true,
-      supportFetchAPI: true,
-      corsEnabled: true,
-    },
-  },
-]);
-
-function resolveAppRoot(): string {
-  if (!app.isPackaged) {
-    return ROOT_DIR;
-  }
-  return app.getAppPath();
-}
-
-/** Read the baked-in app-update.yml config (if applicable). */
-function readAppUpdateYml(): Record<string, string> | null {
-  try {
-    // electron-updater reads from process.resourcesPath in packaged builds,
-    // or dev-app-update.yml via app.getAppPath() in dev.
-    const ymlPath = app.isPackaged
-      ? Path.join(process.resourcesPath, "app-update.yml")
-      : Path.join(app.getAppPath(), "dev-app-update.yml");
-    const raw = FS.readFileSync(ymlPath, "utf-8");
-    // The YAML is simple key-value pairs — avoid pulling in a YAML parser by
-    // doing a line-based parse (fields: provider, owner, repo, releaseType, …).
-    const entries: Record<string, string> = {};
-    for (const line of raw.split("\n")) {
-      const match = line.match(/^(\w+):\s*(.+)$/);
-      if (match?.[1] && match[2]) entries[match[1]] = match[2].trim();
-    }
-    return entries.provider ? entries : null;
-  } catch {
-    return null;
-  }
-}
-
-function normalizeCommitHash(value: unknown): string | null {
-  if (typeof value !== "string") {
-    return null;
-  }
-  const trimmed = value.trim();
-  if (!COMMIT_HASH_PATTERN.test(trimmed)) {
-    return null;
-  }
-  return trimmed.slice(0, COMMIT_HASH_DISPLAY_LENGTH).toLowerCase();
-}
-
-function resolveEmbeddedCommitHash(): string | null {
-  const packageJsonPath = Path.join(resolveAppRoot(), "package.json");
-  if (!FS.existsSync(packageJsonPath)) {
-    return null;
-  }
-
-  try {
-    const raw = FS.readFileSync(packageJsonPath, "utf8");
-    const parsed = JSON.parse(raw) as { t3codeCommitHash?: unknown };
-    return normalizeCommitHash(parsed.t3codeCommitHash);
-  } catch {
-    return null;
-  }
-}
-
-function resolveAboutCommitHash(): string | null {
-  if (aboutCommitHashCache !== undefined) {
-    return aboutCommitHashCache;
-  }
-
-  const envCommitHash = normalizeCommitHash(process.env.T3CODE_COMMIT_HASH);
-  if (envCommitHash) {
-    aboutCommitHashCache = envCommitHash;
-    return aboutCommitHashCache;
-  }
-
-  // Only packaged builds are required to expose commit metadata.
-  if (!app.isPackaged) {
-    aboutCommitHashCache = null;
-    return aboutCommitHashCache;
-  }
-
-  aboutCommitHashCache = resolveEmbeddedCommitHash();
-
-  return aboutCommitHashCache;
-}
-
-function resolveBackendEntry(): string {
-  return Path.join(resolveAppRoot(), "apps/server/dist/bin.mjs");
-}
-
-function resolveBackendCwd(): string {
-  if (!app.isPackaged) {
-    return resolveAppRoot();
-  }
-  return OS.homedir();
-}
-
-function resolveDesktopStaticDir(): string | null {
-  const appRoot = resolveAppRoot();
-  const candidates = [
-    Path.join(appRoot, "apps/server/dist/client"),
-    Path.join(appRoot, "apps/web/dist"),
-  ];
-
-  for (const candidate of candidates) {
-    if (FS.existsSync(Path.join(candidate, "index.html"))) {
-      return candidate;
-    }
-  }
-
-  return null;
-}
-
-function resolveDesktopStaticPath(staticRoot: string, requestUrl: string): string {
-  const url = new URL(requestUrl);
-  const rawPath = decodeURIComponent(url.pathname);
-  const normalizedPath = Path.posix.normalize(rawPath).replace(/^\/+/, "");
-  if (normalizedPath.includes("..")) {
-    return Path.join(staticRoot, "index.html");
-  }
-
-  const requestedPath = normalizedPath.length > 0 ? normalizedPath : "index.html";
-  const resolvedPath = Path.join(staticRoot, requestedPath);
-
-  if (Path.extname(resolvedPath)) {
-    return resolvedPath;
-  }
-
-  const nestedIndex = Path.join(resolvedPath, "index.html");
-  if (FS.existsSync(nestedIndex)) {
-    return nestedIndex;
-  }
-
-  return Path.join(staticRoot, "index.html");
-}
-
-function isStaticAssetRequest(requestUrl: string): boolean {
-  try {
-    const url = new URL(requestUrl);
-    return Path.extname(url.pathname).length > 0;
-  } catch {
-    return false;
-  }
-}
-
-function handleFatalStartupError(stage: string, error: unknown): void {
-  const message = formatErrorMessage(error);
-  const detail =
-    error instanceof Error && typeof error.stack === "string" ? `\n${error.stack}` : "";
-  writeDesktopLogHeader(`fatal startup error stage=${stage} message=${message}`);
-  console.error(`[desktop] fatal startup error (${stage})`, error);
-  if (!isQuitting) {
-    isQuitting = true;
-    dialog.showErrorBox("T3 Code failed to start", `Stage: ${stage}\n${message}${detail}`);
-  }
-  stopBackend();
-  restoreStdIoCapture?.();
-  app.quit();
-}
-
-function registerDesktopProtocol(): void {
-  if (isDevelopment || desktopProtocolRegistered) return;
-
-  const staticRoot = resolveDesktopStaticDir();
-  if (!staticRoot) {
-    throw new Error(
-      "Desktop static bundle missing. Build apps/server (with bundled client) first.",
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeOS from "node:os";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as Electron from "electron";
+
+import * as NetService from "@t3tools/shared/Net";
+import { resolveRemoteT3CliPackageSpec } from "@t3tools/ssh/command";
+import type { RemoteT3RunnerOptions } from "@t3tools/ssh/tunnel";
+import serverPackageJson from "../../server/package.json" with { type: "json" };
+
+import type { DesktopSettings as DesktopSettingsValue } from "./settings/DesktopAppSettings.ts";
+import * as DesktopIpc from "./ipc/DesktopIpc.ts";
+import * as ElectronApp from "./electron/ElectronApp.ts";
+import * as ElectronDialog from "./electron/ElectronDialog.ts";
+import * as ElectronMenu from "./electron/ElectronMenu.ts";
+import * as ElectronProtocol from "./electron/ElectronProtocol.ts";
+import * as DesktopSecretStorage from "./electron/ElectronSafeStorage.ts";
+import * as ElectronShell from "./electron/ElectronShell.ts";
+import * as ElectronTheme from "./electron/ElectronTheme.ts";
+import * as ElectronUpdater from "./electron/ElectronUpdater.ts";
+import * as ElectronWindow from "./electron/ElectronWindow.ts";
+import * as DesktopApp from "./app/DesktopApp.ts";
+import * as DesktopAppIdentity from "./app/DesktopAppIdentity.ts";
+import * as DesktopApplicationMenu from "./window/DesktopApplicationMenu.ts";
+import * as DesktopAssets from "./app/DesktopAssets.ts";
+import * as DesktopBackendConfiguration from "./backend/DesktopBackendConfiguration.ts";
+import * as DesktopBackendManager from "./backend/DesktopBackendManager.ts";
+import * as DesktopEnvironment from "./app/DesktopEnvironment.ts";
+import * as DesktopLifecycle from "./app/DesktopLifecycle.ts";
+import * as DesktopObservability from "./app/DesktopObservability.ts";
+import * as DesktopServerExposure from "./backend/DesktopServerExposure.ts";
+import * as DesktopClientSettings from "./settings/DesktopClientSettings.ts";
+import * as DesktopSavedEnvironments from "./settings/DesktopSavedEnvironments.ts";
+import * as DesktopAppSettings from "./settings/DesktopAppSettings.ts";
+import * as DesktopShellEnvironment from "./shell/DesktopShellEnvironment.ts";
+import * as DesktopSshEnvironment from "./ssh/DesktopSshEnvironment.ts";
+import * as DesktopSshPasswordPrompts from "./ssh/DesktopSshPasswordPrompts.ts";
+import * as DesktopSshRemoteApi from "./ssh/DesktopSshRemoteApi.ts";
+import * as DesktopState from "./app/DesktopState.ts";
+import * as DesktopUpdates from "./updates/DesktopUpdates.ts";
+import * as DesktopWindow from "./window/DesktopWindow.ts";
+
+const desktopEnvironmentLayer = Layer.unwrap(
+  Effect.gen(function* () {
+    const metadata = yield* Effect.service(ElectronApp.ElectronApp).pipe(
+      Effect.flatMap((app) => app.metadata),
     );
-  }
-
-  const staticRootResolved = Path.resolve(staticRoot);
-  const staticRootPrefix = `${staticRootResolved}${Path.sep}`;
-  const fallbackIndex = Path.join(staticRootResolved, "index.html");
-
-  protocol.registerFileProtocol(DESKTOP_SCHEME, (request, callback) => {
-    try {
-      const candidate = resolveDesktopStaticPath(staticRootResolved, request.url);
-      const resolvedCandidate = Path.resolve(candidate);
-      const isInRoot =
-        resolvedCandidate === fallbackIndex || resolvedCandidate.startsWith(staticRootPrefix);
-      const isAssetRequest = isStaticAssetRequest(request.url);
-
-      if (!isInRoot || !FS.existsSync(resolvedCandidate)) {
-        if (isAssetRequest) {
-          callback({ error: -6 });
-          return;
-        }
-        callback({ path: fallbackIndex });
-        return;
-      }
-
-      callback({ path: resolvedCandidate });
-    } catch {
-      callback({ path: fallbackIndex });
-    }
-  });
-
-  desktopProtocolRegistered = true;
-}
-
-function dispatchMenuAction(action: string): void {
-  const existingWindow =
-    BrowserWindow.getFocusedWindow() ?? mainWindow ?? BrowserWindow.getAllWindows()[0];
-  const targetWindow = existingWindow ?? createWindow();
-  if (!existingWindow) {
-    mainWindow = targetWindow;
-  }
-
-  const send = () => {
-    if (targetWindow.isDestroyed()) return;
-    targetWindow.webContents.send(MENU_ACTION_CHANNEL, action);
-    revealWindow(targetWindow);
-  };
-
-  if (targetWindow.webContents.isLoadingMainFrame()) {
-    targetWindow.webContents.once("did-finish-load", send);
-    return;
-  }
-
-  send();
-}
-
-function handleCheckForUpdatesMenuClick(): void {
-  const hasUpdateFeedConfig =
-    readAppUpdateYml() !== null || Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
-  const disabledReason = getAutoUpdateDisabledReason({
-    isDevelopment,
-    isPackaged: app.isPackaged,
-    platform: process.platform,
-    appImage: process.env.APPIMAGE,
-    disabledByEnv: process.env.T3CODE_DISABLE_AUTO_UPDATE === "1",
-    hasUpdateFeedConfig,
-  });
-  if (disabledReason) {
-    console.info("[desktop-updater] Manual update check requested, but updates are disabled.");
-    void dialog.showMessageBox({
-      type: "info",
-      title: "Updates unavailable",
-      message: "Automatic updates are not available right now.",
-      detail: disabledReason,
-      buttons: ["OK"],
-    });
-    return;
-  }
-
-  if (!BrowserWindow.getAllWindows().length) {
-    mainWindow = createWindow();
-  }
-  void checkForUpdatesFromMenu();
-}
-
-async function checkForUpdatesFromMenu(): Promise<void> {
-  await checkForUpdates("menu");
-
-  if (updateState.status === "up-to-date") {
-    void dialog.showMessageBox({
-      type: "info",
-      title: "You're up to date!",
-      message: `T3 Code ${updateState.currentVersion} is currently the newest version available.`,
-      buttons: ["OK"],
-    });
-  } else if (updateState.status === "error") {
-    void dialog.showMessageBox({
-      type: "warning",
-      title: "Update check failed",
-      message: "Could not check for updates.",
-      detail: updateState.message ?? "An unknown error occurred. Please try again later.",
-      buttons: ["OK"],
-    });
-  }
-}
-
-function configureApplicationMenu(): void {
-  const template: MenuItemConstructorOptions[] = [];
-
-  if (process.platform === "darwin") {
-    template.push({
-      label: app.name,
-      submenu: [
-        { role: "about" },
-        {
-          label: "Check for Updates...",
-          click: () => handleCheckForUpdatesMenuClick(),
-        },
-        { type: "separator" },
-        {
-          label: "Settings...",
-          accelerator: "CmdOrCtrl+,",
-          click: () => dispatchMenuAction("open-settings"),
-        },
-        { type: "separator" },
-        { role: "services" },
-        { type: "separator" },
-        { role: "hide" },
-        { role: "hideOthers" },
-        { role: "unhide" },
-        { type: "separator" },
-        { role: "quit" },
-      ],
-    });
-  }
-
-  template.push(
-    {
-      label: "File",
-      submenu: [
-        ...(process.platform === "darwin"
-          ? []
-          : [
-              {
-                label: "Settings...",
-                accelerator: "CmdOrCtrl+,",
-                click: () => dispatchMenuAction("open-settings"),
-              },
-              { type: "separator" as const },
-            ]),
-        { role: process.platform === "darwin" ? "close" : "quit" },
-      ],
-    },
-    { role: "editMenu" },
-    {
-      label: "View",
-      submenu: [
-        { role: "reload" },
-        { role: "forceReload" },
-        { role: "toggleDevTools" },
-        { type: "separator" },
-        { role: "resetZoom" },
-        { role: "zoomIn", accelerator: "CmdOrCtrl+=" },
-        { role: "zoomIn", accelerator: "CmdOrCtrl+Plus", visible: false },
-        { role: "zoomOut" },
-        { type: "separator" },
-        { role: "togglefullscreen" },
-      ],
-    },
-    { role: "windowMenu" },
-    {
-      role: "help",
-      submenu: [
-        {
-          label: "Check for Updates...",
-          click: () => handleCheckForUpdatesMenuClick(),
-        },
-      ],
-    },
-  );
-
-  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
-}
-
-function resolveResourcePath(fileName: string): string | null {
-  const candidates = [
-    Path.join(__dirname, "../resources", fileName),
-    Path.join(__dirname, "../prod-resources", fileName),
-    Path.join(process.resourcesPath, "resources", fileName),
-    Path.join(process.resourcesPath, fileName),
-  ];
-
-  for (const candidate of candidates) {
-    if (FS.existsSync(candidate)) {
-      return candidate;
-    }
-  }
-
-  return null;
-}
-
-function resolveIconPath(ext: "ico" | "icns" | "png"): string | null {
-  return resolveResourcePath(`icon.${ext}`);
-}
-
-/**
- * Resolve the Electron userData directory path.
- *
- * Electron derives the default userData path from `productName` in
- * package.json, which currently produces directories with spaces and
- * parentheses (e.g. `~/.config/T3 Code (Alpha)` on Linux). This is
- * unfriendly for shell usage and violates Linux naming conventions.
- *
- * We override it to a clean lowercase name (`t3code`). If the legacy
- * directory already exists we keep using it so existing users don't
- * lose their Chromium profile data (localStorage, cookies, sessions).
- */
-function resolveUserDataPath(): string {
-  const appDataBase =
-    process.platform === "win32"
-      ? process.env.APPDATA || Path.join(OS.homedir(), "AppData", "Roaming")
-      : process.platform === "darwin"
-        ? Path.join(OS.homedir(), "Library", "Application Support")
-        : process.env.XDG_CONFIG_HOME || Path.join(OS.homedir(), ".config");
-
-  const legacyPath = Path.join(appDataBase, LEGACY_USER_DATA_DIR_NAME);
-  if (FS.existsSync(legacyPath)) {
-    return legacyPath;
-  }
-
-  return Path.join(appDataBase, USER_DATA_DIR_NAME);
-}
-
-function configureAppIdentity(): void {
-  app.setName(APP_DISPLAY_NAME);
-  const commitHash = resolveAboutCommitHash();
-  app.setAboutPanelOptions({
-    applicationName: APP_DISPLAY_NAME,
-    applicationVersion: app.getVersion(),
-    version: commitHash ?? "unknown",
-  });
-
-  if (process.platform === "win32") {
-    app.setAppUserModelId(APP_USER_MODEL_ID);
-  }
-
-  if (process.platform === "linux") {
-    (app as LinuxDesktopNamedApp).setDesktopName?.(LINUX_DESKTOP_ENTRY_NAME);
-  }
-
-  if (process.platform === "darwin" && app.dock) {
-    const iconPath = resolveIconPath("png");
-    if (iconPath) {
-      app.dock.setIcon(iconPath);
-    }
-  }
-}
-
-function clearUpdatePollTimer(): void {
-  if (updateStartupTimer) {
-    clearTimeout(updateStartupTimer);
-    updateStartupTimer = null;
-  }
-  if (updatePollTimer) {
-    clearInterval(updatePollTimer);
-    updatePollTimer = null;
-  }
-}
-
-function revealWindow(window: BrowserWindow): void {
-  if (window.isDestroyed()) {
-    return;
-  }
-
-  if (window.isMinimized()) {
-    window.restore();
-  }
-
-  if (!window.isVisible()) {
-    window.show();
-  }
-
-  if (process.platform === "darwin") {
-    app.focus({ steal: true });
-  }
-
-  window.focus();
-}
-
-function emitUpdateState(): void {
-  for (const window of BrowserWindow.getAllWindows()) {
-    if (window.isDestroyed()) continue;
-    window.webContents.send(UPDATE_STATE_CHANNEL, updateState);
-  }
-}
-
-function setUpdateState(patch: Partial<DesktopUpdateState>): void {
-  updateState = { ...updateState, ...patch };
-  emitUpdateState();
-}
-
-function shouldEnableAutoUpdates(): boolean {
-  const hasUpdateFeedConfig =
-    readAppUpdateYml() !== null || Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
-  return (
-    getAutoUpdateDisabledReason({
-      isDevelopment,
-      isPackaged: app.isPackaged,
+    return DesktopEnvironment.layer({
+      dirname: __dirname,
+      homeDirectory: NodeOS.homedir(),
       platform: process.platform,
-      appImage: process.env.APPIMAGE,
-      disabledByEnv: process.env.T3CODE_DISABLE_AUTO_UPDATE === "1",
-      hasUpdateFeedConfig,
-    }) === null
-  );
-}
-
-async function checkForUpdates(reason: string): Promise<boolean> {
-  if (isQuitting || !updaterConfigured || updateCheckInFlight) return false;
-  if (updateState.status === "downloading" || updateState.status === "downloaded") {
-    console.info(
-      `[desktop-updater] Skipping update check (${reason}) while status=${updateState.status}.`,
-    );
-    return false;
-  }
-  updateCheckInFlight = true;
-  setUpdateState(reduceDesktopUpdateStateOnCheckStart(updateState, new Date().toISOString()));
-  console.info(`[desktop-updater] Checking for updates (${reason})...`);
-
-  try {
-    await autoUpdater.checkForUpdates();
-    return true;
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    setUpdateState(
-      reduceDesktopUpdateStateOnCheckFailure(updateState, message, new Date().toISOString()),
-    );
-    console.error(`[desktop-updater] Failed to check for updates: ${message}`);
-    return true;
-  } finally {
-    updateCheckInFlight = false;
-  }
-}
-
-async function downloadAvailableUpdate(): Promise<{ accepted: boolean; completed: boolean }> {
-  if (!updaterConfigured || updateDownloadInFlight || updateState.status !== "available") {
-    return { accepted: false, completed: false };
-  }
-  updateDownloadInFlight = true;
-  setUpdateState(reduceDesktopUpdateStateOnDownloadStart(updateState));
-  autoUpdater.disableDifferentialDownload = isArm64HostRunningIntelBuild(desktopRuntimeInfo);
-  console.info("[desktop-updater] Downloading update...");
-
-  try {
-    await autoUpdater.downloadUpdate();
-    return { accepted: true, completed: true };
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    setUpdateState(reduceDesktopUpdateStateOnDownloadFailure(updateState, message));
-    console.error(`[desktop-updater] Failed to download update: ${message}`);
-    return { accepted: true, completed: false };
-  } finally {
-    updateDownloadInFlight = false;
-  }
-}
-
-async function installDownloadedUpdate(): Promise<{ accepted: boolean; completed: boolean }> {
-  if (isQuitting || !updaterConfigured || updateState.status !== "downloaded") {
-    return { accepted: false, completed: false };
-  }
-
-  isQuitting = true;
-  updateInstallInFlight = true;
-  clearUpdatePollTimer();
-  try {
-    await stopBackendAndWaitForExit();
-    // Destroy all windows before launching the NSIS installer to avoid the installer finding live windows it needs to close.
-    for (const win of BrowserWindow.getAllWindows()) {
-      win.destroy();
-    }
-    // `quitAndInstall()` only starts the handoff to the updater. The actual
-    // install may still fail asynchronously, so keep the action incomplete
-    // until we either quit or receive an updater error.
-    autoUpdater.quitAndInstall(true, true);
-    return { accepted: true, completed: false };
-  } catch (error: unknown) {
-    const message = formatErrorMessage(error);
-    updateInstallInFlight = false;
-    isQuitting = false;
-    setUpdateState(reduceDesktopUpdateStateOnInstallFailure(updateState, message));
-    console.error(`[desktop-updater] Failed to install update: ${message}`);
-    return { accepted: true, completed: false };
-  }
-}
-
-function configureAutoUpdater(): void {
-  const githubToken =
-    process.env.T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim() || "";
-  if (githubToken) {
-    // When a token is provided, re-configure the feed with `private: true` so
-    // electron-updater uses the GitHub API (api.github.com) instead of the
-    // public Atom feed (github.com/…/releases.atom) which rejects Bearer auth.
-    const appUpdateYml = readAppUpdateYml();
-    if (appUpdateYml?.provider === "github") {
-      autoUpdater.setFeedURL({
-        ...appUpdateYml,
-        provider: "github" as const,
-        private: true,
-        token: githubToken,
-      });
-    }
-  }
-
-  if (process.env.T3CODE_DESKTOP_MOCK_UPDATES) {
-    autoUpdater.setFeedURL({
-      provider: "generic",
-      url: `http://localhost:${process.env.T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT ?? 3000}`,
+      processArch: process.arch,
+      ...metadata,
     });
-  }
-
-  const enabled = shouldEnableAutoUpdates();
-  setUpdateState({
-    ...createInitialDesktopUpdateState(app.getVersion(), desktopRuntimeInfo),
-    enabled,
-    status: enabled ? "idle" : "disabled",
-  });
-  if (!enabled) {
-    return;
-  }
-  updaterConfigured = true;
-
-  autoUpdater.autoDownload = false;
-  autoUpdater.autoInstallOnAppQuit = false;
-  // Keep alpha branding, but force all installs onto the stable update track.
-  autoUpdater.channel = DESKTOP_UPDATE_CHANNEL;
-  autoUpdater.allowPrerelease = DESKTOP_UPDATE_ALLOW_PRERELEASE;
-  autoUpdater.allowDowngrade = false;
-  autoUpdater.disableDifferentialDownload = isArm64HostRunningIntelBuild(desktopRuntimeInfo);
-  let lastLoggedDownloadMilestone = -1;
-
-  if (isArm64HostRunningIntelBuild(desktopRuntimeInfo)) {
-    console.info(
-      "[desktop-updater] Apple Silicon host detected while running Intel build; updates will switch to arm64 packages.",
-    );
-  }
-
-  autoUpdater.on("checking-for-update", () => {
-    console.info("[desktop-updater] Looking for updates...");
-  });
-  autoUpdater.on("update-available", (info) => {
-    setUpdateState(
-      reduceDesktopUpdateStateOnUpdateAvailable(
-        updateState,
-        info.version,
-        new Date().toISOString(),
-      ),
-    );
-    lastLoggedDownloadMilestone = -1;
-    console.info(`[desktop-updater] Update available: ${info.version}`);
-  });
-  autoUpdater.on("update-not-available", () => {
-    setUpdateState(reduceDesktopUpdateStateOnNoUpdate(updateState, new Date().toISOString()));
-    lastLoggedDownloadMilestone = -1;
-    console.info("[desktop-updater] No updates available.");
-  });
-  autoUpdater.on("error", (error) => {
-    const message = formatErrorMessage(error);
-    if (updateInstallInFlight) {
-      updateInstallInFlight = false;
-      isQuitting = false;
-      setUpdateState(reduceDesktopUpdateStateOnInstallFailure(updateState, message));
-      console.error(`[desktop-updater] Updater error: ${message}`);
-      return;
-    }
-    if (!updateCheckInFlight && !updateDownloadInFlight) {
-      setUpdateState({
-        status: "error",
-        message,
-        checkedAt: new Date().toISOString(),
-        downloadPercent: null,
-        errorContext: resolveUpdaterErrorContext(),
-        canRetry: updateState.availableVersion !== null || updateState.downloadedVersion !== null,
-      });
-    }
-    console.error(`[desktop-updater] Updater error: ${message}`);
-  });
-  autoUpdater.on("download-progress", (progress) => {
-    const percent = Math.floor(progress.percent);
-    if (
-      shouldBroadcastDownloadProgress(updateState, progress.percent) ||
-      updateState.message !== null
-    ) {
-      setUpdateState(reduceDesktopUpdateStateOnDownloadProgress(updateState, progress.percent));
-    }
-    const milestone = percent - (percent % 10);
-    if (milestone > lastLoggedDownloadMilestone) {
-      lastLoggedDownloadMilestone = milestone;
-      console.info(`[desktop-updater] Download progress: ${percent}%`);
-    }
-  });
-  autoUpdater.on("update-downloaded", (info) => {
-    setUpdateState(reduceDesktopUpdateStateOnDownloadComplete(updateState, info.version));
-    console.info(`[desktop-updater] Update downloaded: ${info.version}`);
-  });
-
-  clearUpdatePollTimer();
-
-  updateStartupTimer = setTimeout(() => {
-    updateStartupTimer = null;
-    void checkForUpdates("startup");
-  }, AUTO_UPDATE_STARTUP_DELAY_MS);
-  updateStartupTimer.unref();
-
-  updatePollTimer = setInterval(() => {
-    void checkForUpdates("poll");
-  }, AUTO_UPDATE_POLL_INTERVAL_MS);
-  updatePollTimer.unref();
-}
-function scheduleBackendRestart(reason: string): void {
-  if (isQuitting || restartTimer) return;
-
-  const delayMs = Math.min(500 * 2 ** restartAttempt, 10_000);
-  restartAttempt += 1;
-  console.error(`[desktop] backend exited unexpectedly (${reason}); restarting in ${delayMs}ms`);
-
-  restartTimer = setTimeout(() => {
-    restartTimer = null;
-    startBackend();
-  }, delayMs);
-}
-
-function startBackend(): void {
-  if (isQuitting || backendProcess) return;
-
-  backendObservabilitySettings = readPersistedBackendObservabilitySettings();
-  const backendEntry = resolveBackendEntry();
-  if (!FS.existsSync(backendEntry)) {
-    scheduleBackendRestart(`missing server entry at ${backendEntry}`);
-    return;
-  }
-
-  const captureBackendLogs = app.isPackaged && backendLogSink !== null;
-  const child = ChildProcess.spawn(process.execPath, [backendEntry, "--bootstrap-fd", "3"], {
-    cwd: resolveBackendCwd(),
-    // In Electron main, process.execPath points to the Electron binary.
-    // Run the child in Node mode so this backend process does not become a GUI app instance.
-    env: {
-      ...backendChildEnv(),
-      ELECTRON_RUN_AS_NODE: "1",
-    },
-    stdio: captureBackendLogs
-      ? ["ignore", "pipe", "pipe", "pipe"]
-      : ["ignore", "inherit", "inherit", "pipe"],
-  });
-  const bootstrapStream = child.stdio[3];
-  if (bootstrapStream && "write" in bootstrapStream) {
-    bootstrapStream.write(
-      `${JSON.stringify({
-        mode: "desktop",
-        noBrowser: true,
-        port: backendPort,
-        t3Home: BASE_DIR,
-        host: backendBindHost,
-        desktopBootstrapToken: backendBootstrapToken,
-        ...(backendObservabilitySettings.otlpTracesUrl
-          ? { otlpTracesUrl: backendObservabilitySettings.otlpTracesUrl }
-          : {}),
-        ...(backendObservabilitySettings.otlpMetricsUrl
-          ? { otlpMetricsUrl: backendObservabilitySettings.otlpMetricsUrl }
-          : {}),
-      })}\n`,
-    );
-    bootstrapStream.end();
-  } else {
-    child.kill("SIGTERM");
-    scheduleBackendRestart("missing desktop bootstrap pipe");
-    return;
-  }
-  backendProcess = child;
-  let backendSessionClosed = false;
-  const closeBackendSession = (details: string) => {
-    if (backendSessionClosed) return;
-    backendSessionClosed = true;
-    writeBackendSessionBoundary("END", details);
-  };
-  writeBackendSessionBoundary(
-    "START",
-    `pid=${child.pid ?? "unknown"} port=${backendPort} cwd=${resolveBackendCwd()}`,
-  );
-  captureBackendOutput(child);
-
-  child.once("spawn", () => {
-    restartAttempt = 0;
-  });
-
-  child.on("error", (error) => {
-    const wasExpected = expectedBackendExitChildren.has(child);
-    if (backendProcess === child) {
-      backendProcess = null;
-    }
-    closeBackendSession(`pid=${child.pid ?? "unknown"} error=${error.message}`);
-    if (wasExpected) {
-      return;
-    }
-    scheduleBackendRestart(error.message);
-  });
-
-  child.on("exit", (code, signal) => {
-    const wasExpected = expectedBackendExitChildren.has(child);
-    if (backendProcess === child) {
-      backendProcess = null;
-    }
-    closeBackendSession(
-      `pid=${child.pid ?? "unknown"} code=${code ?? "null"} signal=${signal ?? "null"}`,
-    );
-    if (isQuitting || wasExpected) return;
-    const reason = `code=${code ?? "null"} signal=${signal ?? "null"}`;
-    scheduleBackendRestart(reason);
-  });
-}
-
-function stopBackend(): void {
-  cancelBackendReadinessWait();
-  if (restartTimer) {
-    clearTimeout(restartTimer);
-    restartTimer = null;
-  }
-
-  const child = backendProcess;
-  backendProcess = null;
-  if (!child) return;
-
-  if (child.exitCode === null && child.signalCode === null) {
-    expectedBackendExitChildren.add(child);
-    child.kill("SIGTERM");
-    setTimeout(() => {
-      if (child.exitCode === null && child.signalCode === null) {
-        child.kill("SIGKILL");
-      }
-    }, 2_000).unref();
-  }
-}
-
-async function stopBackendAndWaitForExit(timeoutMs = 5_000): Promise<void> {
-  cancelBackendReadinessWait();
-  if (restartTimer) {
-    clearTimeout(restartTimer);
-    restartTimer = null;
-  }
-
-  const child = backendProcess;
-  backendProcess = null;
-  if (!child) return;
-  const backendChild = child;
-  if (backendChild.exitCode !== null || backendChild.signalCode !== null) return;
-  expectedBackendExitChildren.add(backendChild);
-
-  await new Promise<void>((resolve) => {
-    let settled = false;
-    let forceKillTimer: ReturnType<typeof setTimeout> | null = null;
-    let exitTimeoutTimer: ReturnType<typeof setTimeout> | null = null;
-
-    function settle(): void {
-      if (settled) return;
-      settled = true;
-      backendChild.off("exit", onExit);
-      if (forceKillTimer) {
-        clearTimeout(forceKillTimer);
-      }
-      if (exitTimeoutTimer) {
-        clearTimeout(exitTimeoutTimer);
-      }
-      resolve();
-    }
-
-    function onExit(): void {
-      settle();
-    }
-
-    backendChild.once("exit", onExit);
-    backendChild.kill("SIGTERM");
-
-    forceKillTimer = setTimeout(() => {
-      if (backendChild.exitCode === null && backendChild.signalCode === null) {
-        backendChild.kill("SIGKILL");
-      }
-    }, 2_000);
-    forceKillTimer.unref();
-
-    exitTimeoutTimer = setTimeout(() => {
-      settle();
-    }, timeoutMs);
-    exitTimeoutTimer.unref();
-  });
-}
-
-function registerIpcHandlers(): void {
-  ipcMain.removeAllListeners(GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL);
-  ipcMain.on(GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL, (event) => {
-    event.returnValue = {
-      label: "Local environment",
-      httpBaseUrl: backendHttpUrl || null,
-      wsBaseUrl: backendWsUrl || null,
-      bootstrapToken: backendBootstrapToken || undefined,
-    } as const;
-  });
-
-  ipcMain.removeHandler(GET_CLIENT_SETTINGS_CHANNEL);
-  ipcMain.handle(GET_CLIENT_SETTINGS_CHANNEL, async () => readClientSettings(CLIENT_SETTINGS_PATH));
-
-  ipcMain.removeHandler(SET_CLIENT_SETTINGS_CHANNEL);
-  ipcMain.handle(SET_CLIENT_SETTINGS_CHANNEL, async (_event, rawSettings: unknown) => {
-    if (typeof rawSettings !== "object" || rawSettings === null) {
-      throw new Error("Invalid client settings payload.");
-    }
-
-    writeClientSettings(CLIENT_SETTINGS_PATH, rawSettings as ClientSettings);
-  });
-
-  ipcMain.removeHandler(GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL);
-  ipcMain.handle(GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, async () =>
-    readSavedEnvironmentRegistry(SAVED_ENVIRONMENT_REGISTRY_PATH),
-  );
-
-  ipcMain.removeHandler(SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL);
-  ipcMain.handle(SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, async (_event, rawRecords: unknown) => {
-    if (!Array.isArray(rawRecords)) {
-      throw new Error("Invalid saved environment registry payload.");
-    }
-
-    writeSavedEnvironmentRegistry(
-      SAVED_ENVIRONMENT_REGISTRY_PATH,
-      rawRecords as readonly PersistedSavedEnvironmentRecord[],
-    );
-  });
-
-  ipcMain.removeHandler(GET_SAVED_ENVIRONMENT_SECRET_CHANNEL);
-  ipcMain.handle(
-    GET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
-    async (_event, rawEnvironmentId: unknown) => {
-      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
-        return null;
-      }
-
-      return readSavedEnvironmentSecret({
-        registryPath: SAVED_ENVIRONMENT_REGISTRY_PATH,
-        environmentId: rawEnvironmentId,
-        secretStorage: getDesktopSecretStorage(),
-      });
-    },
-  );
-
-  ipcMain.removeHandler(SET_SAVED_ENVIRONMENT_SECRET_CHANNEL);
-  ipcMain.handle(
-    SET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
-    async (_event, rawEnvironmentId: unknown, rawSecret: unknown) => {
-      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
-        throw new Error("Invalid saved environment id.");
-      }
-      if (typeof rawSecret !== "string" || rawSecret.trim().length === 0) {
-        throw new Error("Invalid saved environment secret.");
-      }
-
-      return writeSavedEnvironmentSecret({
-        registryPath: SAVED_ENVIRONMENT_REGISTRY_PATH,
-        environmentId: rawEnvironmentId,
-        secret: rawSecret,
-        secretStorage: getDesktopSecretStorage(),
-      });
-    },
-  );
-
-  ipcMain.removeHandler(REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL);
-  ipcMain.handle(
-    REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL,
-    async (_event, rawEnvironmentId: unknown) => {
-      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
-        return;
-      }
-
-      removeSavedEnvironmentSecret({
-        registryPath: SAVED_ENVIRONMENT_REGISTRY_PATH,
-        environmentId: rawEnvironmentId,
-      });
-    },
-  );
-
-  ipcMain.removeHandler(GET_SERVER_EXPOSURE_STATE_CHANNEL);
-  ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () => getDesktopServerExposureState());
-
-  ipcMain.removeHandler(SET_SERVER_EXPOSURE_MODE_CHANNEL);
-  ipcMain.handle(SET_SERVER_EXPOSURE_MODE_CHANNEL, async (_event, rawMode: unknown) => {
-    if (rawMode !== "local-only" && rawMode !== "network-accessible") {
-      throw new Error("Invalid desktop server exposure input.");
-    }
-
-    const nextMode = rawMode as DesktopServerExposureMode;
-    if (nextMode === desktopServerExposureMode) {
-      return getDesktopServerExposureState();
-    }
-
-    const nextState = await applyDesktopServerExposureMode(nextMode, {
-      persist: true,
-      rejectIfUnavailable: true,
-    });
-    relaunchDesktopApp(`serverExposureMode=${nextMode}`);
-    return nextState;
-  });
-
-  ipcMain.removeHandler(PICK_FOLDER_CHANNEL);
-  ipcMain.handle(PICK_FOLDER_CHANNEL, async () => {
-    const owner = BrowserWindow.getFocusedWindow() ?? mainWindow;
-    const result = owner
-      ? await dialog.showOpenDialog(owner, {
-          properties: ["openDirectory", "createDirectory"],
-        })
-      : await dialog.showOpenDialog({
-          properties: ["openDirectory", "createDirectory"],
-        });
-    if (result.canceled) return null;
-    return result.filePaths[0] ?? null;
-  });
-
-  ipcMain.removeHandler(CONFIRM_CHANNEL);
-  ipcMain.handle(CONFIRM_CHANNEL, async (_event, message: unknown) => {
-    if (typeof message !== "string") {
-      return false;
-    }
-
-    const owner = BrowserWindow.getFocusedWindow() ?? mainWindow;
-    return showDesktopConfirmDialog(message, owner);
-  });
-
-  ipcMain.removeHandler(SET_THEME_CHANNEL);
-  ipcMain.handle(SET_THEME_CHANNEL, async (_event, rawTheme: unknown) => {
-    const theme = getSafeTheme(rawTheme);
-    if (!theme) {
-      return;
-    }
-
-    nativeTheme.themeSource = theme;
-  });
-
-  ipcMain.removeHandler(CONTEXT_MENU_CHANNEL);
-  ipcMain.handle(
-    CONTEXT_MENU_CHANNEL,
-    async (_event, items: ContextMenuItem[], position?: { x: number; y: number }) => {
-      const normalizedItems = items
-        .filter((item) => typeof item.id === "string" && typeof item.label === "string")
-        .map((item) => ({
-          id: item.id,
-          label: item.label,
-          destructive: item.destructive === true,
-          disabled: item.disabled === true,
-        }));
-      if (normalizedItems.length === 0) {
-        return null;
-      }
-
-      const popupPosition =
-        position &&
-        Number.isFinite(position.x) &&
-        Number.isFinite(position.y) &&
-        position.x >= 0 &&
-        position.y >= 0
-          ? {
-              x: Math.floor(position.x),
-              y: Math.floor(position.y),
-            }
-          : null;
-
-      const window = BrowserWindow.getFocusedWindow() ?? mainWindow;
-      if (!window) return null;
-
-      return new Promise<string | null>((resolve) => {
-        const template: MenuItemConstructorOptions[] = [];
-        let hasInsertedDestructiveSeparator = false;
-        for (const item of normalizedItems) {
-          if (item.destructive && !hasInsertedDestructiveSeparator && template.length > 0) {
-            template.push({ type: "separator" });
-            hasInsertedDestructiveSeparator = true;
-          }
-          const itemOption: MenuItemConstructorOptions = {
-            label: item.label,
-            enabled: !item.disabled,
-            click: () => resolve(item.id),
-          };
-          if (item.destructive) {
-            const destructiveIcon = getDestructiveMenuIcon();
-            if (destructiveIcon) {
-              itemOption.icon = destructiveIcon;
-            }
-          }
-          template.push(itemOption);
-        }
-
-        const menu = Menu.buildFromTemplate(template);
-        menu.popup({
-          window,
-          ...popupPosition,
-          callback: () => resolve(null),
-        });
-      });
-    },
-  );
-
-  ipcMain.removeHandler(OPEN_EXTERNAL_CHANNEL);
-  ipcMain.handle(OPEN_EXTERNAL_CHANNEL, async (_event, rawUrl: unknown) => {
-    const externalUrl = getSafeExternalUrl(rawUrl);
-    if (!externalUrl) {
-      return false;
-    }
-
-    try {
-      await shell.openExternal(externalUrl);
-      return true;
-    } catch {
-      return false;
-    }
-  });
-
-  ipcMain.removeHandler(UPDATE_GET_STATE_CHANNEL);
-  ipcMain.handle(UPDATE_GET_STATE_CHANNEL, async () => updateState);
-
-  ipcMain.removeHandler(UPDATE_DOWNLOAD_CHANNEL);
-  ipcMain.handle(UPDATE_DOWNLOAD_CHANNEL, async () => {
-    const result = await downloadAvailableUpdate();
-    return {
-      accepted: result.accepted,
-      completed: result.completed,
-      state: updateState,
-    } satisfies DesktopUpdateActionResult;
-  });
-
-  ipcMain.removeHandler(UPDATE_INSTALL_CHANNEL);
-  ipcMain.handle(UPDATE_INSTALL_CHANNEL, async () => {
-    if (isQuitting) {
-      return {
-        accepted: false,
-        completed: false,
-        state: updateState,
-      } satisfies DesktopUpdateActionResult;
-    }
-    const result = await installDownloadedUpdate();
+  }),
+);
+
+const resolveDesktopSshCliRunner = (
+  environment: DesktopEnvironment.DesktopEnvironmentShape,
+  settings: DesktopSettingsValue,
+): RemoteT3RunnerOptions => {
+  const devRemoteEntryPath = Option.getOrUndefined(environment.devRemoteT3ServerEntryPath);
+  if (environment.isDevelopment && devRemoteEntryPath !== undefined) {
     return {
-      accepted: result.accepted,
-      completed: result.completed,
-      state: updateState,
-    } satisfies DesktopUpdateActionResult;
-  });
-
-  ipcMain.removeHandler(UPDATE_CHECK_CHANNEL);
-  ipcMain.handle(UPDATE_CHECK_CHANNEL, async () => {
-    if (!updaterConfigured) {
-      return {
-        checked: false,
-        state: updateState,
-      } satisfies DesktopUpdateCheckResult;
-    }
-    const checked = await checkForUpdates("web-ui");
-    return {
-      checked,
-      state: updateState,
-    } satisfies DesktopUpdateCheckResult;
-  });
-}
-
-function getIconOption(): { icon: string } | Record<string, never> {
-  if (process.platform === "darwin") return {}; // macOS uses .icns from app bundle
-  const ext = process.platform === "win32" ? "ico" : "png";
-  const iconPath = resolveIconPath(ext);
-  return iconPath ? { icon: iconPath } : {};
-}
-
-function getInitialWindowBackgroundColor(): string {
-  return nativeTheme.shouldUseDarkColors ? "#0a0a0a" : "#ffffff";
-}
-
-function createWindow(): BrowserWindow {
-  const window = new BrowserWindow({
-    width: 1100,
-    height: 780,
-    minWidth: 840,
-    minHeight: 620,
-    show: isDevelopment,
-    autoHideMenuBar: true,
-    backgroundColor: getInitialWindowBackgroundColor(),
-    ...getIconOption(),
-    title: APP_DISPLAY_NAME,
-    titleBarStyle: "hiddenInset",
-    trafficLightPosition: { x: 16, y: 18 },
-    webPreferences: {
-      preload: Path.join(__dirname, "preload.js"),
-      contextIsolation: true,
-      nodeIntegration: false,
-      sandbox: true,
-    },
-  });
-
-  window.webContents.on("context-menu", (event, params) => {
-    event.preventDefault();
-
-    const menuTemplate: MenuItemConstructorOptions[] = [];
-
-    if (params.misspelledWord) {
-      for (const suggestion of params.dictionarySuggestions.slice(0, 5)) {
-        menuTemplate.push({
-          label: suggestion,
-          click: () => window.webContents.replaceMisspelling(suggestion),
-        });
-      }
-      if (params.dictionarySuggestions.length === 0) {
-        menuTemplate.push({ label: "No suggestions", enabled: false });
-      }
-      menuTemplate.push({ type: "separator" });
-    }
-
-    const externalUrl = getSafeExternalUrl(params.linkURL);
-    if (externalUrl) {
-      menuTemplate.push(
-        { label: "Copy Link", click: () => clipboard.writeText(params.linkURL) },
-        { type: "separator" },
-      );
-    }
-
-    if (params.mediaType === "image") {
-      menuTemplate.push({
-        label: "Copy Image",
-        click: () => window.webContents.copyImageAt(params.x, params.y),
-      });
-      menuTemplate.push({ type: "separator" });
-    }
-
-    menuTemplate.push(
-      { role: "cut", enabled: params.editFlags.canCut },
-      { role: "copy", enabled: params.editFlags.canCopy },
-      { role: "paste", enabled: params.editFlags.canPaste },
-      { role: "selectAll", enabled: params.editFlags.canSelectAll },
-    );
-
-    Menu.buildFromTemplate(menuTemplate).popup({ window });
-  });
-
-  window.webContents.setWindowOpenHandler(({ url }) => {
-    const externalUrl = getSafeExternalUrl(url);
-    if (externalUrl) {
-      void shell.openExternal(externalUrl);
-    }
-    return { action: "deny" };
-  });
-
-  window.on("page-title-updated", (event) => {
-    event.preventDefault();
-    window.setTitle(APP_DISPLAY_NAME);
-  });
-  window.webContents.on("did-finish-load", () => {
-    window.setTitle(APP_DISPLAY_NAME);
-    emitUpdateState();
-  });
-  if (!isDevelopment) {
-    window.once("ready-to-show", () => {
-      revealWindow(window);
-    });
-  }
-
-  if (isDevelopment) {
-    void window.loadURL(resolveDesktopDevServerUrl());
-    window.webContents.openDevTools({ mode: "detach" });
-    setImmediate(() => {
-      revealWindow(window);
-    });
-  } else {
-    void window.loadURL(resolveDesktopWindowUrl());
-  }
-
-  window.on("closed", () => {
-    if (mainWindow === window) {
-      mainWindow = null;
-    }
-  });
-
-  return window;
-}
-
-function resolveDesktopWindowUrl(): string {
-  if (backendHttpUrl) {
-    return backendHttpUrl;
-  }
-
-  return `${DESKTOP_SCHEME}://app`;
-}
-
-// Override Electron's userData path before the `ready` event so that
-// Chromium session data uses a filesystem-friendly directory name.
-// Must be called synchronously at the top level — before `app.whenReady()`.
-app.setPath("userData", resolveUserDataPath());
-
-configureAppIdentity();
-
-async function bootstrap(): Promise<void> {
-  writeDesktopLogHeader("bootstrap start");
-  const configuredBackendPort = resolveConfiguredDesktopBackendPort(process.env.T3CODE_PORT);
-  if (isDevelopment && configuredBackendPort === undefined) {
-    throw new Error("T3CODE_PORT is required in desktop development.");
-  }
-
-  backendPort =
-    configuredBackendPort ??
-    (await resolveDesktopBackendPort({
-      host: DESKTOP_LOOPBACK_HOST,
-      startPort: DEFAULT_DESKTOP_BACKEND_PORT,
-      requiredHosts: DESKTOP_REQUIRED_PORT_PROBE_HOSTS,
-    }));
-  writeDesktopLogHeader(
-    configuredBackendPort === undefined
-      ? `selected backend port via sequential scan startPort=${DEFAULT_DESKTOP_BACKEND_PORT} port=${backendPort}`
-      : `using configured backend port port=${backendPort}`,
-  );
-  backendBootstrapToken = Crypto.randomBytes(24).toString("hex");
-  if (desktopSettings.serverExposureMode !== DEFAULT_DESKTOP_SETTINGS.serverExposureMode) {
-    writeDesktopLogHeader(
-      `bootstrap restoring persisted server exposure mode mode=${desktopSettings.serverExposureMode}`,
-    );
-  }
-  const serverExposureState = await applyDesktopServerExposureMode(
-    desktopSettings.serverExposureMode,
-    {
-      persist: desktopSettings.serverExposureMode !== DEFAULT_DESKTOP_SETTINGS.serverExposureMode,
-    },
-  );
-  writeDesktopLogHeader(`bootstrap resolved backend endpoint baseUrl=${backendHttpUrl}`);
-  if (serverExposureState.endpointUrl) {
-    writeDesktopLogHeader(
-      `bootstrap enabled network access endpointUrl=${serverExposureState.endpointUrl}`,
-    );
-  } else if (desktopSettings.serverExposureMode === "network-accessible") {
-    writeDesktopLogHeader(
-      "bootstrap fell back to local-only because no advertised network host was available",
-    );
-  }
-
-  registerIpcHandlers();
-  writeDesktopLogHeader("bootstrap ipc handlers registered");
-  startBackend();
-  writeDesktopLogHeader("bootstrap backend start requested");
-
-  if (isDevelopment) {
-    mainWindow = createWindow();
-    writeDesktopLogHeader("bootstrap main window created");
-    void waitForBackendHttpReady(backendHttpUrl)
-      .then(() => {
-        writeDesktopLogHeader("bootstrap backend ready");
-      })
-      .catch((error) => {
-        if (isBackendReadinessAborted(error)) {
-          return;
-        }
-        writeDesktopLogHeader(
-          `bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
-        );
-        console.warn("[desktop] backend readiness check timed out during dev bootstrap", error);
-      });
-    return;
+      nodeScriptPath: devRemoteEntryPath,
+      nodeEngineRange: serverPackageJson.engines.node,
+    };
   }
+  return {
+    packageSpec: resolveRemoteT3CliPackageSpec({
+      appVersion: environment.appVersion,
+      updateChannel: settings.updateChannel,
+      isDevelopment: environment.isDevelopment,
+    }),
+    nodeEngineRange: serverPackageJson.engines.node,
+  };
+};
 
-  await waitForBackendHttpReady(backendHttpUrl);
-  writeDesktopLogHeader("bootstrap backend ready");
-  mainWindow = createWindow();
-  writeDesktopLogHeader("bootstrap main window created");
-}
-
-app.on("before-quit", () => {
-  isQuitting = true;
-  updateInstallInFlight = false;
-  writeDesktopLogHeader("before-quit received");
-  clearUpdatePollTimer();
-  cancelBackendReadinessWait();
-  stopBackend();
-  restoreStdIoCapture?.();
-});
-
-app
-  .whenReady()
-  .then(() => {
-    writeDesktopLogHeader("app ready");
-    configureAppIdentity();
-    configureApplicationMenu();
-    registerDesktopProtocol();
-    configureAutoUpdater();
-    void bootstrap().catch((error) => {
-      if (isBackendReadinessAborted(error) && isQuitting) {
-        return;
-      }
-      handleFatalStartupError("bootstrap", error);
-    });
-
-    app.on("activate", () => {
-      const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0];
-      if (existingWindow) {
-        revealWindow(existingWindow);
-        return;
-      }
-      mainWindow = createWindow();
+const desktopSshEnvironmentLayer = Layer.unwrap(
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const settings = yield* DesktopAppSettings.DesktopAppSettings;
+    return DesktopSshEnvironment.layer({
+      resolveCliRunner: settings.get.pipe(
+        Effect.map((currentSettings) => resolveDesktopSshCliRunner(environment, currentSettings)),
+      ),
     });
-  })
-  .catch((error) => {
-    handleFatalStartupError("whenReady", error);
-  });
-
-app.on("window-all-closed", () => {
-  if (process.platform !== "darwin" && !isQuitting) {
-    app.quit();
-  }
-});
-
-if (process.platform !== "win32") {
-  process.on("SIGINT", () => {
-    if (isQuitting) return;
-    isQuitting = true;
-    writeDesktopLogHeader("SIGINT received");
-    clearUpdatePollTimer();
-    cancelBackendReadinessWait();
-    stopBackend();
-    restoreStdIoCapture?.();
-    app.quit();
-  });
-
-  process.on("SIGTERM", () => {
-    if (isQuitting) return;
-    isQuitting = true;
-    writeDesktopLogHeader("SIGTERM received");
-    clearUpdatePollTimer();
-    stopBackend();
-    restoreStdIoCapture?.();
-    app.quit();
-  });
-}
+  }),
+);
+
+const electronLayer = Layer.mergeAll(
+  ElectronApp.layer,
+  ElectronDialog.layer,
+  ElectronMenu.layer,
+  ElectronProtocol.layer,
+  DesktopSecretStorage.layer,
+  ElectronShell.layer,
+  ElectronTheme.layer,
+  ElectronUpdater.layer,
+  ElectronWindow.layer,
+  Layer.succeed(DesktopIpc.DesktopIpc, DesktopIpc.make(Electron.ipcMain)),
+);
+
+const desktopFoundationLayer = Layer.mergeAll(
+  DesktopState.layer,
+  DesktopLifecycle.layerShutdown,
+  DesktopAppSettings.layer,
+  DesktopClientSettings.layer,
+  DesktopSavedEnvironments.layer,
+  DesktopAssets.layer,
+  DesktopObservability.layer,
+).pipe(Layer.provideMerge(desktopEnvironmentLayer));
+
+const desktopSshLayer = Layer.mergeAll(desktopSshEnvironmentLayer, DesktopSshRemoteApi.layer).pipe(
+  Layer.provideMerge(DesktopSshPasswordPrompts.layer()),
+);
+
+const desktopServerExposureLayer = DesktopServerExposure.layer.pipe(
+  Layer.provideMerge(DesktopServerExposure.networkInterfacesLayer),
+  Layer.provideMerge(desktopFoundationLayer),
+);
+
+const desktopWindowLayer = DesktopWindow.layer.pipe(Layer.provideMerge(desktopServerExposureLayer));
+
+const desktopBackendLayer = DesktopBackendManager.layer.pipe(
+  Layer.provideMerge(DesktopAppIdentity.layer),
+  Layer.provideMerge(DesktopBackendConfiguration.layer),
+  Layer.provideMerge(desktopWindowLayer),
+);
+
+const desktopApplicationLayer = Layer.mergeAll(
+  DesktopLifecycle.layer,
+  DesktopApplicationMenu.layer,
+  DesktopShellEnvironment.layer,
+  desktopSshLayer,
+).pipe(Layer.provideMerge(DesktopUpdates.layer), Layer.provideMerge(desktopBackendLayer));
+
+const desktopRuntimeLayer = ElectronProtocol.layerSchemePrivileges.pipe(
+  Layer.flatMap(() =>
+    desktopApplicationLayer.pipe(
+      Layer.provideMerge(NodeServices.layer),
+      Layer.provideMerge(NodeHttpClient.layerUndici),
+      Layer.provideMerge(NetService.layer),
+      Layer.provideMerge(electronLayer),
+    ),
+  ),
+);
+
+DesktopApp.program.pipe(Effect.provide(desktopRuntimeLayer), NodeRuntime.runMain);
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index e3107a92485..173be8fb54a 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -1,78 +1,127 @@
-import { contextBridge, ipcRenderer } from "electron";
 import type { DesktopBridge } from "@t3tools/contracts";
+import { contextBridge, ipcRenderer } from "electron";
+
+import * as IpcChannels from "./ipc/channels.ts";
 
-const PICK_FOLDER_CHANNEL = "desktop:pick-folder";
-const CONFIRM_CHANNEL = "desktop:confirm";
-const SET_THEME_CHANNEL = "desktop:set-theme";
-const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
-const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
-const MENU_ACTION_CHANNEL = "desktop:menu-action";
-const UPDATE_STATE_CHANNEL = "desktop:update-state";
-const UPDATE_GET_STATE_CHANNEL = "desktop:update-get-state";
-const UPDATE_CHECK_CHANNEL = "desktop:update-check";
-const UPDATE_DOWNLOAD_CHANNEL = "desktop:update-download";
-const UPDATE_INSTALL_CHANNEL = "desktop:update-install";
-const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL = "desktop:get-local-environment-bootstrap";
-const GET_CLIENT_SETTINGS_CHANNEL = "desktop:get-client-settings";
-const SET_CLIENT_SETTINGS_CHANNEL = "desktop:set-client-settings";
-const GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:get-saved-environment-registry";
-const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-registry";
-const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
-const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
-const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
-const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
-const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
+function unwrapEnsureSshEnvironmentResult(result: unknown) {
+  if (
+    typeof result === "object" &&
+    result !== null &&
+    "type" in result &&
+    result.type === IpcChannels.SSH_PASSWORD_PROMPT_CANCELLED_RESULT
+  ) {
+    const message =
+      "message" in result && typeof result.message === "string"
+        ? result.message
+        : "SSH authentication cancelled.";
+    throw new Error(message);
+  }
+  return result as Awaited<ReturnType<DesktopBridge["ensureSshEnvironment"]>>;
+}
 
 contextBridge.exposeInMainWorld("desktopBridge", {
+  getAppBranding: () => {
+    const result = ipcRenderer.sendSync(IpcChannels.GET_APP_BRANDING_CHANNEL);
+    if (typeof result !== "object" || result === null) {
+      return null;
+    }
+    return result as ReturnType<DesktopBridge["getAppBranding"]>;
+  },
   getLocalEnvironmentBootstrap: () => {
-    const result = ipcRenderer.sendSync(GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL);
+    const result = ipcRenderer.sendSync(IpcChannels.GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL);
     if (typeof result !== "object" || result === null) {
       return null;
     }
     return result as ReturnType<DesktopBridge["getLocalEnvironmentBootstrap"]>;
   },
-  getClientSettings: () => ipcRenderer.invoke(GET_CLIENT_SETTINGS_CHANNEL),
-  setClientSettings: (settings) => ipcRenderer.invoke(SET_CLIENT_SETTINGS_CHANNEL, settings),
-  getSavedEnvironmentRegistry: () => ipcRenderer.invoke(GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL),
+  getClientSettings: () => ipcRenderer.invoke(IpcChannels.GET_CLIENT_SETTINGS_CHANNEL),
+  setClientSettings: (settings) =>
+    ipcRenderer.invoke(IpcChannels.SET_CLIENT_SETTINGS_CHANNEL, settings),
+  getSavedEnvironmentRegistry: () =>
+    ipcRenderer.invoke(IpcChannels.GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL),
   setSavedEnvironmentRegistry: (records) =>
-    ipcRenderer.invoke(SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, records),
+    ipcRenderer.invoke(IpcChannels.SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, records),
   getSavedEnvironmentSecret: (environmentId) =>
-    ipcRenderer.invoke(GET_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
+    ipcRenderer.invoke(IpcChannels.GET_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
   setSavedEnvironmentSecret: (environmentId, secret) =>
-    ipcRenderer.invoke(SET_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId, secret),
+    ipcRenderer.invoke(IpcChannels.SET_SAVED_ENVIRONMENT_SECRET_CHANNEL, { environmentId, secret }),
   removeSavedEnvironmentSecret: (environmentId) =>
-    ipcRenderer.invoke(REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
-  getServerExposureState: () => ipcRenderer.invoke(GET_SERVER_EXPOSURE_STATE_CHANNEL),
-  setServerExposureMode: (mode) => ipcRenderer.invoke(SET_SERVER_EXPOSURE_MODE_CHANNEL, mode),
-  pickFolder: () => ipcRenderer.invoke(PICK_FOLDER_CHANNEL),
-  confirm: (message) => ipcRenderer.invoke(CONFIRM_CHANNEL, message),
-  setTheme: (theme) => ipcRenderer.invoke(SET_THEME_CHANNEL, theme),
-  showContextMenu: (items, position) => ipcRenderer.invoke(CONTEXT_MENU_CHANNEL, items, position),
-  openExternal: (url: string) => ipcRenderer.invoke(OPEN_EXTERNAL_CHANNEL, url),
+    ipcRenderer.invoke(IpcChannels.REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
+  discoverSshHosts: () => ipcRenderer.invoke(IpcChannels.DISCOVER_SSH_HOSTS_CHANNEL),
+  ensureSshEnvironment: async (target, options) =>
+    unwrapEnsureSshEnvironmentResult(
+      await ipcRenderer.invoke(IpcChannels.ENSURE_SSH_ENVIRONMENT_CHANNEL, {
+        target,
+        ...(options === undefined ? {} : { options }),
+      }),
+    ),
+  disconnectSshEnvironment: (target) =>
+    ipcRenderer.invoke(IpcChannels.DISCONNECT_SSH_ENVIRONMENT_CHANNEL, target),
+  fetchSshEnvironmentDescriptor: (httpBaseUrl) =>
+    ipcRenderer.invoke(IpcChannels.FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, { httpBaseUrl }),
+  bootstrapSshBearerSession: (httpBaseUrl, credential) =>
+    ipcRenderer.invoke(IpcChannels.BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL, {
+      httpBaseUrl,
+      credential,
+    }),
+  fetchSshSessionState: (httpBaseUrl, bearerToken) =>
+    ipcRenderer.invoke(IpcChannels.FETCH_SSH_SESSION_STATE_CHANNEL, { httpBaseUrl, bearerToken }),
+  issueSshWebSocketToken: (httpBaseUrl, bearerToken) =>
+    ipcRenderer.invoke(IpcChannels.ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL, { httpBaseUrl, bearerToken }),
+  onSshPasswordPrompt: (listener) => {
+    const wrappedListener = (_event: Electron.IpcRendererEvent, request: unknown) => {
+      if (typeof request !== "object" || request === null) return;
+      listener(request as Parameters<typeof listener>[0]);
+    };
+
+    ipcRenderer.on(IpcChannels.SSH_PASSWORD_PROMPT_CHANNEL, wrappedListener);
+    return () => {
+      ipcRenderer.removeListener(IpcChannels.SSH_PASSWORD_PROMPT_CHANNEL, wrappedListener);
+    };
+  },
+  resolveSshPasswordPrompt: (requestId, password) =>
+    ipcRenderer.invoke(IpcChannels.RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL, { requestId, password }),
+  getServerExposureState: () => ipcRenderer.invoke(IpcChannels.GET_SERVER_EXPOSURE_STATE_CHANNEL),
+  setServerExposureMode: (mode) =>
+    ipcRenderer.invoke(IpcChannels.SET_SERVER_EXPOSURE_MODE_CHANNEL, mode),
+  setTailscaleServeEnabled: (input) =>
+    ipcRenderer.invoke(IpcChannels.SET_TAILSCALE_SERVE_ENABLED_CHANNEL, input),
+  getAdvertisedEndpoints: () => ipcRenderer.invoke(IpcChannels.GET_ADVERTISED_ENDPOINTS_CHANNEL),
+  pickFolder: (options) => ipcRenderer.invoke(IpcChannels.PICK_FOLDER_CHANNEL, options),
+  confirm: (message) => ipcRenderer.invoke(IpcChannels.CONFIRM_CHANNEL, message),
+  setTheme: (theme) => ipcRenderer.invoke(IpcChannels.SET_THEME_CHANNEL, theme),
+  showContextMenu: (items, position) =>
+    ipcRenderer.invoke(IpcChannels.CONTEXT_MENU_CHANNEL, {
+      items,
+      ...(position === undefined ? {} : { position }),
+    }),
+  openExternal: (url: string) => ipcRenderer.invoke(IpcChannels.OPEN_EXTERNAL_CHANNEL, url),
   onMenuAction: (listener) => {
     const wrappedListener = (_event: Electron.IpcRendererEvent, action: unknown) => {
       if (typeof action !== "string") return;
       listener(action);
     };
 
-    ipcRenderer.on(MENU_ACTION_CHANNEL, wrappedListener);
+    ipcRenderer.on(IpcChannels.MENU_ACTION_CHANNEL, wrappedListener);
     return () => {
-      ipcRenderer.removeListener(MENU_ACTION_CHANNEL, wrappedListener);
+      ipcRenderer.removeListener(IpcChannels.MENU_ACTION_CHANNEL, wrappedListener);
     };
   },
-  getUpdateState: () => ipcRenderer.invoke(UPDATE_GET_STATE_CHANNEL),
-  checkForUpdate: () => ipcRenderer.invoke(UPDATE_CHECK_CHANNEL),
-  downloadUpdate: () => ipcRenderer.invoke(UPDATE_DOWNLOAD_CHANNEL),
-  installUpdate: () => ipcRenderer.invoke(UPDATE_INSTALL_CHANNEL),
+  getUpdateState: () => ipcRenderer.invoke(IpcChannels.UPDATE_GET_STATE_CHANNEL),
+  setUpdateChannel: (channel) =>
+    ipcRenderer.invoke(IpcChannels.UPDATE_SET_CHANNEL_CHANNEL, channel),
+  checkForUpdate: () => ipcRenderer.invoke(IpcChannels.UPDATE_CHECK_CHANNEL),
+  downloadUpdate: () => ipcRenderer.invoke(IpcChannels.UPDATE_DOWNLOAD_CHANNEL),
+  installUpdate: () => ipcRenderer.invoke(IpcChannels.UPDATE_INSTALL_CHANNEL),
   onUpdateState: (listener) => {
     const wrappedListener = (_event: Electron.IpcRendererEvent, state: unknown) => {
       if (typeof state !== "object" || state === null) return;
       listener(state as Parameters<typeof listener>[0]);
     };
 
-    ipcRenderer.on(UPDATE_STATE_CHANNEL, wrappedListener);
+    ipcRenderer.on(IpcChannels.UPDATE_STATE_CHANNEL, wrappedListener);
     return () => {
-      ipcRenderer.removeListener(UPDATE_STATE_CHANNEL, wrappedListener);
+      ipcRenderer.removeListener(IpcChannels.UPDATE_STATE_CHANNEL, wrappedListener);
     };
   },
 } satisfies DesktopBridge);
diff --git a/apps/desktop/src/rotatingFileSink.test.ts b/apps/desktop/src/rotatingFileSink.test.ts
deleted file mode 100644
index 53dd98ade8c..00000000000
--- a/apps/desktop/src/rotatingFileSink.test.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-import { RotatingFileSink } from "@t3tools/shared/logging";
-import { afterEach, describe, expect, it } from "vitest";
-
-const tempRoots: string[] = [];
-
-function makeTempDir(): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-rotating-log-"));
-  tempRoots.push(dir);
-  return dir;
-}
-
-afterEach(() => {
-  for (const dir of tempRoots.splice(0)) {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-describe("RotatingFileSink", () => {
-  it("rotates when writes exceed max bytes", () => {
-    const dir = makeTempDir();
-    const logPath = path.join(dir, "desktop-main.log");
-    const sink = new RotatingFileSink({
-      filePath: logPath,
-      maxBytes: 10,
-      maxFiles: 3,
-    });
-
-    sink.write("12345");
-    sink.write("67890");
-    sink.write("abc");
-
-    expect(fs.readFileSync(path.join(dir, "desktop-main.log"), "utf8")).toBe("abc");
-    expect(fs.readFileSync(path.join(dir, "desktop-main.log.1"), "utf8")).toBe("1234567890");
-  });
-
-  it("retains only maxFiles backups", () => {
-    const dir = makeTempDir();
-    const logPath = path.join(dir, "server-child.log");
-    const sink = new RotatingFileSink({
-      filePath: logPath,
-      maxBytes: 4,
-      maxFiles: 2,
-    });
-
-    sink.write("aaaa");
-    sink.write("bbbb");
-    sink.write("cccc");
-    sink.write("dddd");
-
-    expect(fs.existsSync(path.join(dir, "server-child.log.1"))).toBe(true);
-    expect(fs.existsSync(path.join(dir, "server-child.log.2"))).toBe(true);
-    expect(fs.existsSync(path.join(dir, "server-child.log.3"))).toBe(false);
-  });
-
-  it("prunes stale backups above maxFiles on startup", () => {
-    const dir = makeTempDir();
-    const logPath = path.join(dir, "desktop-main.log");
-    fs.writeFileSync(path.join(dir, "desktop-main.log.1"), "first");
-    fs.writeFileSync(path.join(dir, "desktop-main.log.4"), "stale");
-
-    const sink = new RotatingFileSink({
-      filePath: logPath,
-      maxBytes: 16,
-      maxFiles: 2,
-    });
-    sink.write("hello");
-
-    expect(fs.existsSync(path.join(dir, "desktop-main.log.4"))).toBe(false);
-  });
-});
diff --git a/apps/desktop/src/runtimeArch.test.ts b/apps/desktop/src/runtimeArch.test.ts
deleted file mode 100644
index 258a8fb2152..00000000000
--- a/apps/desktop/src/runtimeArch.test.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { isArm64HostRunningIntelBuild, resolveDesktopRuntimeInfo } from "./runtimeArch";
-
-describe("resolveDesktopRuntimeInfo", () => {
-  it("detects Rosetta-translated Intel builds on Apple Silicon", () => {
-    const runtimeInfo = resolveDesktopRuntimeInfo({
-      platform: "darwin",
-      processArch: "x64",
-      runningUnderArm64Translation: true,
-    });
-
-    expect(runtimeInfo).toEqual({
-      hostArch: "arm64",
-      appArch: "x64",
-      runningUnderArm64Translation: true,
-    });
-    expect(isArm64HostRunningIntelBuild(runtimeInfo)).toBe(true);
-  });
-
-  it("detects native Apple Silicon builds", () => {
-    const runtimeInfo = resolveDesktopRuntimeInfo({
-      platform: "darwin",
-      processArch: "arm64",
-      runningUnderArm64Translation: false,
-    });
-
-    expect(runtimeInfo).toEqual({
-      hostArch: "arm64",
-      appArch: "arm64",
-      runningUnderArm64Translation: false,
-    });
-    expect(isArm64HostRunningIntelBuild(runtimeInfo)).toBe(false);
-  });
-
-  it("passes through non-mac builds without translation", () => {
-    const runtimeInfo = resolveDesktopRuntimeInfo({
-      platform: "linux",
-      processArch: "x64",
-      runningUnderArm64Translation: true,
-    });
-
-    expect(runtimeInfo).toEqual({
-      hostArch: "x64",
-      appArch: "x64",
-      runningUnderArm64Translation: false,
-    });
-  });
-});
diff --git a/apps/desktop/src/runtimeArch.ts b/apps/desktop/src/runtimeArch.ts
deleted file mode 100644
index 127abf51ab8..00000000000
--- a/apps/desktop/src/runtimeArch.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import type { DesktopRuntimeArch, DesktopRuntimeInfo } from "@t3tools/contracts";
-
-interface ResolveDesktopRuntimeInfoInput {
-  readonly platform: NodeJS.Platform;
-  readonly processArch: string;
-  readonly runningUnderArm64Translation: boolean;
-}
-
-function normalizeDesktopArch(arch: string): DesktopRuntimeArch {
-  if (arch === "arm64") return "arm64";
-  if (arch === "x64") return "x64";
-  return "other";
-}
-
-export function resolveDesktopRuntimeInfo(
-  input: ResolveDesktopRuntimeInfoInput,
-): DesktopRuntimeInfo {
-  const appArch = normalizeDesktopArch(input.processArch);
-
-  if (input.platform !== "darwin") {
-    return {
-      hostArch: appArch,
-      appArch,
-      runningUnderArm64Translation: false,
-    };
-  }
-
-  const hostArch = appArch === "arm64" || input.runningUnderArm64Translation ? "arm64" : appArch;
-
-  return {
-    hostArch,
-    appArch,
-    runningUnderArm64Translation: input.runningUnderArm64Translation,
-  };
-}
-
-export function isArm64HostRunningIntelBuild(runtimeInfo: DesktopRuntimeInfo): boolean {
-  return runtimeInfo.hostArch === "arm64" && runtimeInfo.appArch === "x64";
-}
diff --git a/apps/desktop/src/serverExposure.test.ts b/apps/desktop/src/serverExposure.test.ts
deleted file mode 100644
index b1ae4bef4f5..00000000000
--- a/apps/desktop/src/serverExposure.test.ts
+++ /dev/null
@@ -1,139 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { resolveDesktopServerExposure, resolveLanAdvertisedHost } from "./serverExposure";
-
-describe("resolveLanAdvertisedHost", () => {
-  it("prefers an explicit host override", () => {
-    expect(
-      resolveLanAdvertisedHost(
-        {
-          en0: [
-            {
-              address: "192.168.1.44",
-              family: "IPv4",
-              internal: false,
-              netmask: "255.255.255.0",
-              cidr: "192.168.1.44/24",
-              mac: "00:00:00:00:00:00",
-            },
-          ],
-        },
-        "10.0.0.9",
-      ),
-    ).toBe("10.0.0.9");
-  });
-
-  it("returns the first usable non-internal IPv4 address", () => {
-    expect(
-      resolveLanAdvertisedHost(
-        {
-          lo0: [
-            {
-              address: "127.0.0.1",
-              family: "IPv4",
-              internal: true,
-              netmask: "255.0.0.0",
-              cidr: "127.0.0.1/8",
-              mac: "00:00:00:00:00:00",
-            },
-          ],
-          en0: [
-            {
-              address: "192.168.1.44",
-              family: "IPv4",
-              internal: false,
-              netmask: "255.255.255.0",
-              cidr: "192.168.1.44/24",
-              mac: "00:00:00:00:00:00",
-            },
-          ],
-        },
-        undefined,
-      ),
-    ).toBe("192.168.1.44");
-  });
-
-  it("returns null when no usable network address is available", () => {
-    expect(
-      resolveLanAdvertisedHost(
-        {
-          lo0: [
-            {
-              address: "127.0.0.1",
-              family: "IPv4",
-              internal: true,
-              netmask: "255.0.0.0",
-              cidr: "127.0.0.1/8",
-              mac: "00:00:00:00:00:00",
-            },
-          ],
-        },
-        undefined,
-      ),
-    ).toBeNull();
-  });
-});
-
-describe("resolveDesktopServerExposure", () => {
-  it("keeps the desktop server loopback-only when local-only mode is selected", () => {
-    expect(
-      resolveDesktopServerExposure({
-        mode: "local-only",
-        port: 3773,
-        networkInterfaces: {},
-      }),
-    ).toEqual({
-      mode: "local-only",
-      bindHost: "127.0.0.1",
-      localHttpUrl: "http://127.0.0.1:3773",
-      localWsUrl: "ws://127.0.0.1:3773",
-      endpointUrl: null,
-      advertisedHost: null,
-    });
-  });
-
-  it("binds to all interfaces in network-accessible mode", () => {
-    expect(
-      resolveDesktopServerExposure({
-        mode: "network-accessible",
-        port: 3773,
-        networkInterfaces: {
-          en0: [
-            {
-              address: "192.168.1.44",
-              family: "IPv4",
-              internal: false,
-              netmask: "255.255.255.0",
-              cidr: "192.168.1.44/24",
-              mac: "00:00:00:00:00:00",
-            },
-          ],
-        },
-      }),
-    ).toEqual({
-      mode: "network-accessible",
-      bindHost: "0.0.0.0",
-      localHttpUrl: "http://127.0.0.1:3773",
-      localWsUrl: "ws://127.0.0.1:3773",
-      endpointUrl: "http://192.168.1.44:3773",
-      advertisedHost: "192.168.1.44",
-    });
-  });
-
-  it("stays network-accessible even when no LAN address is currently detectable", () => {
-    expect(
-      resolveDesktopServerExposure({
-        mode: "network-accessible",
-        port: 3773,
-        networkInterfaces: {},
-      }),
-    ).toEqual({
-      mode: "network-accessible",
-      bindHost: "0.0.0.0",
-      localHttpUrl: "http://127.0.0.1:3773",
-      localWsUrl: "ws://127.0.0.1:3773",
-      endpointUrl: null,
-      advertisedHost: null,
-    });
-  });
-});
diff --git a/apps/desktop/src/serverExposure.ts b/apps/desktop/src/serverExposure.ts
deleted file mode 100644
index 65c99b60e13..00000000000
--- a/apps/desktop/src/serverExposure.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import type { NetworkInterfaceInfo } from "node:os";
-import type { DesktopServerExposureMode } from "@t3tools/contracts";
-
-const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
-const DESKTOP_LAN_BIND_HOST = "0.0.0.0";
-
-export interface DesktopServerExposure {
-  readonly mode: DesktopServerExposureMode;
-  readonly bindHost: string;
-  readonly localHttpUrl: string;
-  readonly localWsUrl: string;
-  readonly endpointUrl: string | null;
-  readonly advertisedHost: string | null;
-}
-
-const normalizeOptionalHost = (value: string | undefined): string | undefined => {
-  const normalized = value?.trim();
-  return normalized && normalized.length > 0 ? normalized : undefined;
-};
-
-const isUsableLanIpv4Address = (address: string): boolean =>
-  !address.startsWith("127.") && !address.startsWith("169.254.");
-
-export function resolveLanAdvertisedHost(
-  networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>,
-  explicitHost: string | undefined,
-): string | null {
-  const normalizedExplicitHost = normalizeOptionalHost(explicitHost);
-  if (normalizedExplicitHost) {
-    return normalizedExplicitHost;
-  }
-
-  for (const interfaceAddresses of Object.values(networkInterfaces)) {
-    if (!interfaceAddresses) continue;
-
-    for (const address of interfaceAddresses) {
-      if (address.internal) continue;
-      if (address.family !== "IPv4") continue;
-      if (!isUsableLanIpv4Address(address.address)) continue;
-      return address.address;
-    }
-  }
-
-  return null;
-}
-
-export function resolveDesktopServerExposure(input: {
-  readonly mode: DesktopServerExposureMode;
-  readonly port: number;
-  readonly networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>;
-  readonly advertisedHostOverride?: string;
-}): DesktopServerExposure {
-  const localHttpUrl = `http://${DESKTOP_LOOPBACK_HOST}:${input.port}`;
-  const localWsUrl = `ws://${DESKTOP_LOOPBACK_HOST}:${input.port}`;
-
-  if (input.mode === "local-only") {
-    return {
-      mode: input.mode,
-      bindHost: DESKTOP_LOOPBACK_HOST,
-      localHttpUrl,
-      localWsUrl,
-      endpointUrl: null,
-      advertisedHost: null,
-    };
-  }
-
-  const advertisedHost = resolveLanAdvertisedHost(
-    input.networkInterfaces,
-    input.advertisedHostOverride,
-  );
-
-  return {
-    mode: input.mode,
-    bindHost: DESKTOP_LAN_BIND_HOST,
-    localHttpUrl,
-    localWsUrl,
-    endpointUrl: advertisedHost ? `http://${advertisedHost}:${input.port}` : null,
-    advertisedHost,
-  };
-}
diff --git a/apps/desktop/src/settings/DesktopAppSettings.test.ts b/apps/desktop/src/settings/DesktopAppSettings.test.ts
new file mode 100644
index 00000000000..db6194cf8f7
--- /dev/null
+++ b/apps/desktop/src/settings/DesktopAppSettings.test.ts
@@ -0,0 +1,284 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import {
+  DEFAULT_DESKTOP_SETTINGS,
+  resolveDefaultDesktopSettings,
+  type DesktopSettings as DesktopSettingsValue,
+} from "./DesktopAppSettings.ts";
+import * as DesktopAppSettings from "./DesktopAppSettings.ts";
+
+const DesktopSettingsPatch = Schema.Struct({
+  serverExposureMode: Schema.optionalKey(Schema.Literals(["local-only", "network-accessible"])),
+  tailscaleServeEnabled: Schema.optionalKey(Schema.Boolean),
+  tailscaleServePort: Schema.optionalKey(Schema.Number),
+  updateChannel: Schema.optionalKey(Schema.Literals(["latest", "nightly"])),
+  updateChannelConfiguredByUser: Schema.optionalKey(Schema.Boolean),
+});
+
+const decodeDesktopSettingsPatch = Schema.decodeEffect(Schema.fromJsonString(DesktopSettingsPatch));
+const encodeDesktopSettingsPatch = Schema.encodeEffect(Schema.fromJsonString(DesktopSettingsPatch));
+
+function makeEnvironmentLayer(baseDir: string, appVersion = "0.0.17") {
+  return DesktopEnvironment.layer({
+    dirname: "/repo/apps/desktop/src",
+    homeDirectory: baseDir,
+    platform: "darwin",
+    processArch: "x64",
+    appVersion,
+    appPath: "/repo",
+    isPackaged: true,
+    resourcesPath: "/missing/resources",
+    runningUnderArm64Translation: false,
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({ T3CODE_HOME: baseDir })),
+    ),
+  );
+}
+
+const withSettings = <A, E, R>(
+  effect: Effect.Effect<
+    A,
+    E,
+    R | DesktopAppSettings.DesktopAppSettings | DesktopEnvironment.DesktopEnvironment
+  >,
+  options?: { readonly appVersion?: string },
+) =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+      prefix: "t3-desktop-settings-test-",
+    });
+    return yield* effect.pipe(
+      Effect.provide(
+        DesktopAppSettings.layer.pipe(
+          Layer.provideMerge(makeEnvironmentLayer(baseDir, options?.appVersion)),
+          Layer.provideMerge(NodeServices.layer),
+        ),
+      ),
+    );
+  }).pipe(Effect.provide(NodeServices.layer), Effect.scoped);
+
+function writeSettingsPatch(patch: typeof DesktopSettingsPatch.Type) {
+  return Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const fileSystem = yield* FileSystem.FileSystem;
+    const encoded = yield* encodeDesktopSettingsPatch(patch);
+    yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+    yield* fileSystem.writeFileString(environment.desktopSettingsPath, `${encoded}\n`);
+  });
+}
+
+describe("DesktopSettings", () => {
+  it.effect("loads defaults when no settings file exists", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        assert.deepEqual(yield* settings.load, DEFAULT_DESKTOP_SETTINGS);
+        assert.deepEqual(yield* settings.get, DEFAULT_DESKTOP_SETTINGS);
+      }),
+    ),
+  );
+
+  it("defaults packaged nightly builds to the nightly update channel", () => {
+    assert.deepEqual(resolveDefaultDesktopSettings("0.0.17-nightly.20260415.1"), {
+      serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
+      updateChannel: "nightly",
+      updateChannelConfiguredByUser: false,
+    } satisfies DesktopSettingsValue);
+  });
+
+  it.effect("loads persisted settings and applies semantic updates", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        yield* writeSettingsPatch({
+          serverExposureMode: "network-accessible",
+          tailscaleServeEnabled: true,
+          tailscaleServePort: 8443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: true,
+        });
+
+        assert.deepEqual(yield* settings.load, {
+          serverExposureMode: "network-accessible",
+          tailscaleServeEnabled: true,
+          tailscaleServePort: 8443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: true,
+        } satisfies DesktopSettingsValue);
+
+        const exposure = yield* settings.setServerExposureMode("local-only");
+        assert.isTrue(exposure.changed);
+        assert.equal(exposure.settings.serverExposureMode, "local-only");
+
+        const tailscale = yield* settings.setTailscaleServe({
+          enabled: true,
+          port: Option.some(9443),
+        });
+        assert.isTrue(tailscale.changed);
+        assert.equal(tailscale.settings.tailscaleServePort, 9443);
+
+        const updateChannel = yield* settings.setUpdateChannel("nightly");
+        assert.isTrue(updateChannel.changed);
+        assert.equal(updateChannel.settings.updateChannel, "nightly");
+        assert.equal(updateChannel.settings.updateChannelConfiguredByUser, true);
+      }),
+    ),
+  );
+
+  it.effect("does not persist no-op semantic updates", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+
+        const exposure = yield* settings.setServerExposureMode("local-only");
+        assert.isFalse(exposure.changed);
+
+        const tailscale = yield* settings.setTailscaleServe({
+          enabled: false,
+          port: Option.none(),
+        });
+        assert.isFalse(tailscale.changed);
+
+        const updateChannel = yield* settings.setUpdateChannel("latest");
+        assert.isFalse(updateChannel.changed);
+        assert.equal(updateChannel.settings.updateChannelConfiguredByUser, false);
+      }),
+    ),
+  );
+
+  it.effect("falls back to defaults when the settings file is malformed", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(environment.desktopSettingsPath, "{not-json");
+
+        assert.deepEqual(yield* settings.load, DEFAULT_DESKTOP_SETTINGS);
+      }),
+    ),
+  );
+
+  it.effect("loads lenient persisted desktop settings JSON", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(
+          environment.desktopSettingsPath,
+          `{
+            // JSONC-style comments and trailing commas match server settings parsing.
+            "serverExposureMode": "network-accessible",
+            "tailscaleServeEnabled": true,
+            "tailscaleServePort": 8443,
+          }\n`,
+        );
+
+        assert.deepEqual(yield* settings.load, {
+          serverExposureMode: "network-accessible",
+          tailscaleServeEnabled: true,
+          tailscaleServePort: 8443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: false,
+        } satisfies DesktopSettingsValue);
+      }),
+    ),
+  );
+
+  it.effect("persists sparse desktop settings documents", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+
+        yield* settings.setServerExposureMode("network-accessible");
+
+        const persisted = yield* decodeDesktopSettingsPatch(
+          yield* fileSystem.readFileString(environment.desktopSettingsPath),
+        );
+        assert.deepEqual(persisted, {
+          serverExposureMode: "network-accessible",
+        } satisfies typeof DesktopSettingsPatch.Type);
+      }),
+    ),
+  );
+
+  it.effect("migrates legacy implicit update channels to the runtime default", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        yield* writeSettingsPatch({
+          serverExposureMode: "local-only",
+          updateChannel: "latest",
+        });
+
+        assert.deepEqual(yield* settings.load, {
+          serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+          updateChannel: "nightly",
+          updateChannelConfiguredByUser: false,
+        } satisfies DesktopSettingsValue);
+      }),
+      { appVersion: "0.0.17-nightly.20260415.1" },
+    ),
+  );
+
+  it.effect("preserves explicit stable update channel on nightly builds", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        yield* writeSettingsPatch({
+          serverExposureMode: "local-only",
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: true,
+        });
+
+        assert.deepEqual(yield* settings.load, {
+          serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: true,
+        } satisfies DesktopSettingsValue);
+      }),
+      { appVersion: "0.0.17-nightly.20260415.1" },
+    ),
+  );
+
+  it.effect("normalizes invalid persisted Tailscale Serve ports", () =>
+    withSettings(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        yield* writeSettingsPatch({
+          tailscaleServeEnabled: true,
+          tailscaleServePort: 0,
+        });
+
+        assert.deepEqual(yield* settings.load, {
+          serverExposureMode: "local-only",
+          tailscaleServeEnabled: true,
+          tailscaleServePort: 443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: false,
+        } satisfies DesktopSettingsValue);
+      }),
+    ),
+  );
+});
diff --git a/apps/desktop/src/settings/DesktopAppSettings.ts b/apps/desktop/src/settings/DesktopAppSettings.ts
new file mode 100644
index 00000000000..177f05a4b2b
--- /dev/null
+++ b/apps/desktop/src/settings/DesktopAppSettings.ts
@@ -0,0 +1,318 @@
+import {
+  DesktopServerExposureModeSchema,
+  DesktopUpdateChannelSchema,
+  type DesktopServerExposureMode,
+  type DesktopUpdateChannel,
+} from "@t3tools/contracts";
+import { fromLenientJson } from "@t3tools/shared/schemaJson";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import { resolveDefaultDesktopUpdateChannel } from "../updates/updateChannels.ts";
+
+export interface DesktopSettings {
+  readonly serverExposureMode: DesktopServerExposureMode;
+  readonly tailscaleServeEnabled: boolean;
+  readonly tailscaleServePort: number;
+  readonly updateChannel: DesktopUpdateChannel;
+  readonly updateChannelConfiguredByUser: boolean;
+}
+
+export interface DesktopSettingsChange {
+  readonly settings: DesktopSettings;
+  readonly changed: boolean;
+}
+
+export const DEFAULT_TAILSCALE_SERVE_PORT = 443;
+
+export const DEFAULT_DESKTOP_SETTINGS: DesktopSettings = {
+  serverExposureMode: "local-only",
+  tailscaleServeEnabled: false,
+  tailscaleServePort: DEFAULT_TAILSCALE_SERVE_PORT,
+  updateChannel: "latest",
+  updateChannelConfiguredByUser: false,
+};
+
+const DesktopSettingsDocument = Schema.Struct({
+  serverExposureMode: Schema.optionalKey(DesktopServerExposureModeSchema),
+  tailscaleServeEnabled: Schema.optionalKey(Schema.Boolean),
+  tailscaleServePort: Schema.optionalKey(Schema.Number),
+  updateChannel: Schema.optionalKey(DesktopUpdateChannelSchema),
+  updateChannelConfiguredByUser: Schema.optionalKey(Schema.Boolean),
+});
+
+type DesktopSettingsDocument = typeof DesktopSettingsDocument.Type;
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+const DesktopSettingsJson = fromLenientJson(DesktopSettingsDocument);
+const decodeDesktopSettingsJson = Schema.decodeEffect(DesktopSettingsJson);
+const encodeDesktopSettingsJson = Schema.encodeEffect(DesktopSettingsJson);
+
+const settingsChange = (settings: DesktopSettings, changed: boolean): DesktopSettingsChange => ({
+  settings,
+  changed,
+});
+
+export class DesktopSettingsWriteError extends Data.TaggedError("DesktopSettingsWriteError")<{
+  readonly cause: PlatformError.PlatformError | Schema.SchemaError;
+}> {
+  override get message() {
+    return `Failed to write desktop settings: ${this.cause.message}`;
+  }
+}
+
+export interface DesktopAppSettingsShape {
+  readonly load: Effect.Effect<DesktopSettings>;
+  readonly get: Effect.Effect<DesktopSettings>;
+  readonly setServerExposureMode: (
+    mode: DesktopServerExposureMode,
+  ) => Effect.Effect<DesktopSettingsChange, DesktopSettingsWriteError>;
+  readonly setTailscaleServe: (input: {
+    readonly enabled: boolean;
+    readonly port: Option.Option<number>;
+  }) => Effect.Effect<DesktopSettingsChange, DesktopSettingsWriteError>;
+  readonly setUpdateChannel: (
+    channel: DesktopUpdateChannel,
+  ) => Effect.Effect<DesktopSettingsChange, DesktopSettingsWriteError>;
+}
+
+export class DesktopAppSettings extends Context.Service<
+  DesktopAppSettings,
+  DesktopAppSettingsShape
+>()("t3/desktop/AppSettings") {}
+
+export function resolveDefaultDesktopSettings(appVersion: string): DesktopSettings {
+  return {
+    ...DEFAULT_DESKTOP_SETTINGS,
+    updateChannel: resolveDefaultDesktopUpdateChannel(appVersion),
+  };
+}
+
+function normalizeTailscaleServePort(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65_535
+    ? value
+    : DEFAULT_TAILSCALE_SERVE_PORT;
+}
+
+function normalizeDesktopSettingsDocument(
+  parsed: DesktopSettingsDocument,
+  appVersion: string,
+): DesktopSettings {
+  const defaultSettings = resolveDefaultDesktopSettings(appVersion);
+  const parsedUpdateChannel = Option.fromNullishOr(parsed.updateChannel);
+  const isLegacySettings = parsed.updateChannelConfiguredByUser === undefined;
+  const updateChannelConfiguredByUser =
+    parsed.updateChannelConfiguredByUser === true ||
+    (isLegacySettings && Option.contains(parsedUpdateChannel, "nightly"));
+
+  return {
+    serverExposureMode:
+      parsed.serverExposureMode === "network-accessible" ? "network-accessible" : "local-only",
+    tailscaleServeEnabled: parsed.tailscaleServeEnabled === true,
+    tailscaleServePort: normalizeTailscaleServePort(parsed.tailscaleServePort),
+    updateChannel: updateChannelConfiguredByUser
+      ? Option.getOrElse(parsedUpdateChannel, () => defaultSettings.updateChannel)
+      : defaultSettings.updateChannel,
+    updateChannelConfiguredByUser,
+  };
+}
+
+function toDesktopSettingsDocument(
+  settings: DesktopSettings,
+  defaults: DesktopSettings,
+): DesktopSettingsDocument {
+  const document: Mutable<DesktopSettingsDocument> = {};
+
+  if (settings.serverExposureMode !== defaults.serverExposureMode) {
+    document.serverExposureMode = settings.serverExposureMode;
+  }
+  if (settings.tailscaleServeEnabled !== defaults.tailscaleServeEnabled) {
+    document.tailscaleServeEnabled = settings.tailscaleServeEnabled;
+  }
+  if (settings.tailscaleServePort !== defaults.tailscaleServePort) {
+    document.tailscaleServePort = settings.tailscaleServePort;
+  }
+  if (settings.updateChannel !== defaults.updateChannel) {
+    document.updateChannel = settings.updateChannel;
+  }
+  if (settings.updateChannelConfiguredByUser !== defaults.updateChannelConfiguredByUser) {
+    document.updateChannelConfiguredByUser = settings.updateChannelConfiguredByUser;
+  }
+
+  return document;
+}
+
+function setServerExposureMode(
+  settings: DesktopSettings,
+  requestedMode: DesktopServerExposureMode,
+): DesktopSettings {
+  return settings.serverExposureMode === requestedMode
+    ? settings
+    : {
+        ...settings,
+        serverExposureMode: requestedMode,
+      };
+}
+
+function setTailscaleServe(
+  settings: DesktopSettings,
+  input: { readonly enabled: boolean; readonly port: Option.Option<number> },
+): DesktopSettings {
+  const port = Option.match(input.port, {
+    onNone: () => settings.tailscaleServePort,
+    onSome: normalizeTailscaleServePort,
+  });
+  return settings.tailscaleServeEnabled === input.enabled && settings.tailscaleServePort === port
+    ? settings
+    : {
+        ...settings,
+        tailscaleServeEnabled: input.enabled,
+        tailscaleServePort: port,
+      };
+}
+
+function setUpdateChannel(
+  settings: DesktopSettings,
+  requestedChannel: DesktopUpdateChannel,
+): DesktopSettings {
+  return settings.updateChannel === requestedChannel
+    ? settings
+    : {
+        ...settings,
+        updateChannel: requestedChannel,
+        updateChannelConfiguredByUser: true,
+      };
+}
+
+function readSettings(
+  fileSystem: FileSystem.FileSystem,
+  settingsPath: string,
+  appVersion: string,
+): Effect.Effect<DesktopSettings> {
+  const defaultSettings = resolveDefaultDesktopSettings(appVersion);
+
+  return fileSystem.readFileString(settingsPath).pipe(
+    Effect.option,
+    Effect.flatMap(
+      Option.match({
+        onNone: () => Effect.succeed(defaultSettings),
+        onSome: (raw) =>
+          decodeDesktopSettingsJson(raw).pipe(
+            Effect.map((parsed) => normalizeDesktopSettingsDocument(parsed, appVersion)),
+            Effect.catch(() => Effect.succeed(defaultSettings)),
+          ),
+      }),
+    ),
+  );
+}
+
+const writeSettings = Effect.fn("desktop.settings.writeSettings")(function* (input: {
+  readonly fileSystem: FileSystem.FileSystem;
+  readonly path: Path.Path;
+  readonly settingsPath: string;
+  readonly settings: DesktopSettings;
+  readonly defaultSettings: DesktopSettings;
+}): Effect.fn.Return<void, PlatformError.PlatformError | Schema.SchemaError> {
+  const directory = input.path.dirname(input.settingsPath);
+  const suffix = (yield* Random.nextUUIDv4).replace(/-/g, "");
+  const tempPath = `${input.settingsPath}.${process.pid}.${suffix}.tmp`;
+  const encoded = yield* encodeDesktopSettingsJson(
+    toDesktopSettingsDocument(input.settings, input.defaultSettings),
+  );
+  yield* input.fileSystem.makeDirectory(directory, { recursive: true });
+  yield* input.fileSystem.writeFileString(tempPath, `${encoded}\n`);
+  yield* input.fileSystem.rename(tempPath, input.settingsPath);
+});
+
+export const layer = Layer.effect(
+  DesktopAppSettings,
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const settingsRef = yield* SynchronizedRef.make(environment.defaultDesktopSettings);
+
+    const persist = (
+      update: (settings: DesktopSettings) => DesktopSettings,
+    ): Effect.Effect<DesktopSettingsChange, DesktopSettingsWriteError> =>
+      SynchronizedRef.modifyEffect(settingsRef, (settings) => {
+        const nextSettings = update(settings);
+        if (nextSettings === settings) {
+          return Effect.succeed([settingsChange(settings, false), settings] as const);
+        }
+
+        return writeSettings({
+          fileSystem,
+          path,
+          settingsPath: environment.desktopSettingsPath,
+          settings: nextSettings,
+          defaultSettings: environment.defaultDesktopSettings,
+        }).pipe(
+          Effect.mapError((cause) => new DesktopSettingsWriteError({ cause })),
+          Effect.as([settingsChange(nextSettings, true), nextSettings] as const),
+        );
+      });
+
+    return DesktopAppSettings.of({
+      get: SynchronizedRef.get(settingsRef),
+      load: Effect.gen(function* () {
+        const settings = yield* readSettings(
+          fileSystem,
+          environment.desktopSettingsPath,
+          environment.appVersion,
+        );
+        return yield* SynchronizedRef.setAndGet(settingsRef, settings);
+      }).pipe(Effect.withSpan("desktop.settings.load")),
+      setServerExposureMode: (mode) =>
+        persist((settings) => setServerExposureMode(settings, mode)).pipe(
+          Effect.withSpan("desktop.settings.setServerExposureMode", { attributes: { mode } }),
+        ),
+      setTailscaleServe: (input) =>
+        persist((settings) => setTailscaleServe(settings, input)).pipe(
+          Effect.withSpan("desktop.settings.setTailscaleServe", { attributes: input }),
+        ),
+      setUpdateChannel: (channel) =>
+        persist((settings) => setUpdateChannel(settings, channel)).pipe(
+          Effect.withSpan("desktop.settings.setUpdateChannel", { attributes: { channel } }),
+        ),
+    });
+  }),
+);
+
+export const layerTest = (initialSettings: DesktopSettings = DEFAULT_DESKTOP_SETTINGS) =>
+  Layer.effect(
+    DesktopAppSettings,
+    Effect.gen(function* () {
+      const settingsRef = yield* SynchronizedRef.make(initialSettings);
+      const update = (f: (settings: DesktopSettings) => DesktopSettings) =>
+        SynchronizedRef.modify(settingsRef, (settings) => {
+          const nextSettings = f(settings);
+          return [
+            {
+              settings: nextSettings,
+              changed: nextSettings !== settings,
+            },
+            nextSettings,
+          ] as const;
+        });
+
+      return DesktopAppSettings.of({
+        get: SynchronizedRef.get(settingsRef),
+        load: SynchronizedRef.get(settingsRef),
+        setServerExposureMode: (mode) =>
+          update((settings) => setServerExposureMode(settings, mode)),
+        setTailscaleServe: (input) => update((settings) => setTailscaleServe(settings, input)),
+        setUpdateChannel: (channel) => update((settings) => setUpdateChannel(settings, channel)),
+      });
+    }),
+  );
diff --git a/apps/desktop/src/settings/DesktopClientSettings.test.ts b/apps/desktop/src/settings/DesktopClientSettings.test.ts
new file mode 100644
index 00000000000..f666e692860
--- /dev/null
+++ b/apps/desktop/src/settings/DesktopClientSettings.test.ts
@@ -0,0 +1,185 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import { ClientSettingsSchema, type ClientSettings } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopClientSettings from "./DesktopClientSettings.ts";
+
+const clientSettings: ClientSettings = {
+  autoOpenPlanSidebar: false,
+  confirmThreadArchive: true,
+  confirmThreadDelete: false,
+  dismissedProviderUpdateNotificationKeys: [],
+  diffIgnoreWhitespace: true,
+  diffWordWrap: true,
+  favorites: [],
+  providerModelPreferences: {},
+  sidebarProjectGroupingMode: "repository_path",
+  sidebarProjectGroupingOverrides: {
+    "environment-1:/tmp/project-a": "separate",
+  },
+  sidebarProjectSortOrder: "manual",
+  sidebarThreadSortOrder: "created_at",
+  sidebarThreadPreviewCount: 6,
+  timestampFormat: "24-hour",
+};
+
+const decodeClientSettingsJson = Schema.decodeEffect(Schema.fromJsonString(ClientSettingsSchema));
+const decodeRecordJson = Schema.decodeEffect(
+  Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown)),
+);
+
+function makeLayer(baseDir: string) {
+  const environmentLayer = DesktopEnvironment.layer({
+    dirname: "/repo/apps/desktop/src",
+    homeDirectory: baseDir,
+    platform: "darwin",
+    processArch: "x64",
+    appVersion: "1.2.3",
+    appPath: "/repo",
+    isPackaged: true,
+    resourcesPath: "/missing/resources",
+    runningUnderArm64Translation: false,
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({ T3CODE_HOME: baseDir })),
+    ),
+  );
+
+  return DesktopClientSettings.layer.pipe(
+    Layer.provideMerge(environmentLayer),
+    Layer.provideMerge(NodeServices.layer),
+  );
+}
+
+const withClientSettings = <A, E, R>(
+  effect: Effect.Effect<A, E, R | DesktopClientSettings.DesktopClientSettings>,
+) =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+      prefix: "t3-desktop-client-settings-test-",
+    });
+    return yield* effect.pipe(Effect.provide(makeLayer(baseDir)));
+  }).pipe(Effect.provide(NodeServices.layer), Effect.scoped);
+
+describe("DesktopClientSettings", () => {
+  it.effect("returns none when no client settings file exists", () =>
+    withClientSettings(
+      Effect.gen(function* () {
+        const settings = yield* DesktopClientSettings.DesktopClientSettings;
+        assert.isTrue(Option.isNone(yield* settings.get));
+      }),
+    ),
+  );
+
+  it.effect("persists and reloads client settings", () =>
+    withClientSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopClientSettings.DesktopClientSettings;
+        yield* settings.set(clientSettings);
+
+        assert.deepEqual(yield* settings.get, Option.some(clientSettings));
+        assert.deepEqual(
+          yield* decodeClientSettingsJson(
+            yield* fileSystem.readFileString(environment.clientSettingsPath),
+          ),
+          clientSettings,
+        );
+        assert.isFalse(
+          Object.hasOwn(
+            yield* decodeRecordJson(
+              yield* fileSystem.readFileString(environment.clientSettingsPath),
+            ),
+            "settings",
+          ),
+        );
+      }),
+    ),
+  );
+
+  it.effect("loads lenient direct client settings documents", () =>
+    withClientSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopClientSettings.DesktopClientSettings;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(
+          environment.clientSettingsPath,
+          `{
+            // Matches server settings parsing.
+            "timestampFormat": "24-hour",
+          }\n`,
+        );
+
+        const persisted = yield* settings.get;
+        assert.isTrue(Option.isSome(persisted));
+        if (Option.isSome(persisted)) {
+          assert.equal(persisted.value.timestampFormat, "24-hour");
+        }
+      }),
+    ),
+  );
+
+  it.effect("loads legacy wrapped client settings documents", () =>
+    withClientSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopClientSettings.DesktopClientSettings;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(
+          environment.clientSettingsPath,
+          `{
+            "settings": {
+              "timestampFormat": "12-hour"
+            }
+          }\n`,
+        );
+
+        const persisted = yield* settings.get;
+        assert.isTrue(Option.isSome(persisted));
+        if (Option.isSome(persisted)) {
+          assert.equal(persisted.value.timestampFormat, "12-hour");
+        }
+      }),
+    ),
+  );
+
+  it.effect("loads defaults from empty client settings documents", () =>
+    withClientSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopClientSettings.DesktopClientSettings;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(environment.clientSettingsPath, "{}\n");
+
+        assert.deepEqual(yield* settings.get, Option.some(yield* decodeClientSettingsJson("{}")));
+      }),
+    ),
+  );
+
+  it.effect("treats malformed client settings documents as absent", () =>
+    withClientSettings(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const settings = yield* DesktopClientSettings.DesktopClientSettings;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(environment.clientSettingsPath, "{not-json");
+
+        assert.isTrue(Option.isNone(yield* settings.get));
+      }),
+    ),
+  );
+});
diff --git a/apps/desktop/src/settings/DesktopClientSettings.ts b/apps/desktop/src/settings/DesktopClientSettings.ts
new file mode 100644
index 00000000000..2153125e8e7
--- /dev/null
+++ b/apps/desktop/src/settings/DesktopClientSettings.ts
@@ -0,0 +1,122 @@
+import { ClientSettingsSchema, type ClientSettings } from "@t3tools/contracts";
+import { fromLenientJson } from "@t3tools/shared/schemaJson";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import * as Ref from "effect/Ref";
+
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+
+const ClientSettingsDocumentSchema = Schema.Struct({
+  settings: ClientSettingsSchema,
+});
+
+const ClientSettingsJson = fromLenientJson(ClientSettingsSchema);
+const LegacyClientSettingsDocumentJson = fromLenientJson(ClientSettingsDocumentSchema);
+const decodeLegacyClientSettingsDocumentJson = Schema.decodeEffect(
+  LegacyClientSettingsDocumentJson,
+);
+const decodeClientSettingsJsonValue = Schema.decodeEffect(ClientSettingsJson);
+const decodeClientSettingsJson = (raw: string): Effect.Effect<ClientSettings, Schema.SchemaError> =>
+  decodeLegacyClientSettingsDocumentJson(raw).pipe(
+    Effect.map((document) => document.settings),
+    Effect.catch(() => decodeClientSettingsJsonValue(raw)),
+  );
+const encodeClientSettingsJson = Schema.encodeEffect(ClientSettingsJson);
+
+export class DesktopClientSettingsWriteError extends Data.TaggedError(
+  "DesktopClientSettingsWriteError",
+)<{
+  readonly cause: PlatformError.PlatformError | Schema.SchemaError;
+}> {
+  override get message() {
+    return `Failed to write desktop client settings: ${this.cause.message}`;
+  }
+}
+
+export interface DesktopClientSettingsShape {
+  readonly get: Effect.Effect<Option.Option<ClientSettings>>;
+  readonly set: (settings: ClientSettings) => Effect.Effect<void, DesktopClientSettingsWriteError>;
+}
+
+export class DesktopClientSettings extends Context.Service<
+  DesktopClientSettings,
+  DesktopClientSettingsShape
+>()("t3/desktop/ClientSettings") {}
+
+const readClientSettings = (
+  fileSystem: FileSystem.FileSystem,
+  settingsPath: string,
+): Effect.Effect<Option.Option<ClientSettings>> =>
+  fileSystem.readFileString(settingsPath).pipe(
+    Effect.option,
+    Effect.flatMap(
+      Option.match({
+        onNone: () => Effect.succeed(Option.none<ClientSettings>()),
+        onSome: (raw) =>
+          decodeClientSettingsJson(raw).pipe(
+            Effect.map((settings) => Option.some(settings)),
+            Effect.catch(() => Effect.succeed(Option.none<ClientSettings>())),
+          ),
+      }),
+    ),
+  );
+
+const writeClientSettings = Effect.fnUntraced(function* (input: {
+  readonly fileSystem: FileSystem.FileSystem;
+  readonly path: Path.Path;
+  readonly settingsPath: string;
+  readonly settings: ClientSettings;
+}): Effect.fn.Return<void, PlatformError.PlatformError | Schema.SchemaError> {
+  const directory = input.path.dirname(input.settingsPath);
+  const suffix = (yield* Random.nextUUIDv4).replace(/-/g, "");
+  const tempPath = `${input.settingsPath}.${process.pid}.${suffix}.tmp`;
+  const encoded = yield* encodeClientSettingsJson(input.settings);
+  yield* input.fileSystem.makeDirectory(directory, { recursive: true });
+  yield* input.fileSystem.writeFileString(tempPath, `${encoded}\n`);
+  yield* input.fileSystem.rename(tempPath, input.settingsPath);
+});
+
+export const layer = Layer.effect(
+  DesktopClientSettings,
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+
+    return DesktopClientSettings.of({
+      get: readClientSettings(fileSystem, environment.clientSettingsPath).pipe(
+        Effect.withSpan("desktop.clientSettings.get"),
+      ),
+      set: (settings) =>
+        writeClientSettings({
+          fileSystem,
+          path,
+          settingsPath: environment.clientSettingsPath,
+          settings,
+        }).pipe(
+          Effect.mapError((cause) => new DesktopClientSettingsWriteError({ cause })),
+          Effect.withSpan("desktop.clientSettings.set"),
+        ),
+    });
+  }),
+);
+
+export const layerTest = (initialSettings: Option.Option<ClientSettings> = Option.none()) =>
+  Layer.effect(
+    DesktopClientSettings,
+    Effect.gen(function* () {
+      const settingsRef = yield* Ref.make(initialSettings);
+      return DesktopClientSettings.of({
+        get: Ref.get(settingsRef),
+        set: (settings) => Ref.set(settingsRef, Option.some(settings)),
+      });
+    }),
+  );
diff --git a/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts b/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
new file mode 100644
index 00000000000..d1d37b96e11
--- /dev/null
+++ b/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
@@ -0,0 +1,344 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import { EnvironmentId, type PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as ElectronSafeStorage from "../electron/ElectronSafeStorage.ts";
+import * as DesktopSavedEnvironments from "./DesktopSavedEnvironments.ts";
+
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+
+const savedRegistryRecord: PersistedSavedEnvironmentRecord = {
+  environmentId: EnvironmentId.make("environment-1"),
+  label: "Remote environment",
+  httpBaseUrl: "https://remote.example.com/",
+  wsBaseUrl: "wss://remote.example.com/",
+  createdAt: "2026-04-09T00:00:00.000Z",
+  lastConnectedAt: "2026-04-09T01:00:00.000Z",
+  desktopSsh: {
+    alias: "devbox",
+    hostname: "devbox.example.com",
+    username: "julius",
+    port: 22,
+  },
+};
+
+const SavedEnvironmentRegistryDocumentProbe = Schema.Struct({
+  version: Schema.Number,
+  records: Schema.Array(Schema.Unknown),
+});
+const decodeSavedEnvironmentRegistryDocumentProbe = Schema.decodeEffect(
+  Schema.fromJsonString(SavedEnvironmentRegistryDocumentProbe),
+);
+
+function makeSafeStorageLayer(input: {
+  readonly available: boolean;
+  readonly availabilityError?: unknown;
+  readonly encryptError?: unknown;
+  readonly decryptError?: unknown;
+}) {
+  return Layer.succeed(ElectronSafeStorage.ElectronSafeStorage, {
+    isEncryptionAvailable:
+      input.availabilityError === undefined
+        ? Effect.succeed(input.available)
+        : Effect.fail(
+            new ElectronSafeStorage.ElectronSafeStorageAvailabilityError({
+              cause: input.availabilityError,
+            }),
+          ),
+    encryptString: (value) =>
+      input.encryptError === undefined
+        ? Effect.succeed(textEncoder.encode(`enc:${value}`))
+        : Effect.fail(
+            new ElectronSafeStorage.ElectronSafeStorageEncryptError({
+              cause: input.encryptError,
+            }),
+          ),
+    decryptString: (value) => {
+      if (input.decryptError !== undefined) {
+        return Effect.fail(
+          new ElectronSafeStorage.ElectronSafeStorageDecryptError({
+            cause: input.decryptError,
+          }),
+        );
+      }
+
+      const decoded = textDecoder.decode(value);
+      if (!decoded.startsWith("enc:")) {
+        return Effect.fail(
+          new ElectronSafeStorage.ElectronSafeStorageDecryptError({
+            cause: new Error("invalid secret"),
+          }),
+        );
+      }
+      return Effect.succeed(decoded.slice("enc:".length));
+    },
+  } satisfies ElectronSafeStorage.ElectronSafeStorageShape);
+}
+
+function makeLayer(
+  baseDir: string,
+  options?: {
+    readonly availableSecretStorage?: boolean;
+    readonly availabilityError?: unknown;
+    readonly encryptError?: unknown;
+    readonly decryptError?: unknown;
+  },
+) {
+  const environmentLayer = DesktopEnvironment.layer({
+    dirname: "/repo/apps/desktop/src",
+    homeDirectory: baseDir,
+    platform: "darwin",
+    processArch: "x64",
+    appVersion: "1.2.3",
+    appPath: "/repo",
+    isPackaged: true,
+    resourcesPath: "/missing/resources",
+    runningUnderArm64Translation: false,
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({ T3CODE_HOME: baseDir })),
+    ),
+  );
+
+  return DesktopSavedEnvironments.layer.pipe(
+    Layer.provideMerge(environmentLayer),
+    Layer.provideMerge(
+      makeSafeStorageLayer({
+        available: options?.availableSecretStorage ?? true,
+        availabilityError: options?.availabilityError,
+        encryptError: options?.encryptError,
+        decryptError: options?.decryptError,
+      }),
+    ),
+    Layer.provideMerge(NodeServices.layer),
+  );
+}
+
+const withSavedEnvironments = <A, E, R>(
+  effect: Effect.Effect<A, E, R | DesktopSavedEnvironments.DesktopSavedEnvironments>,
+  options?: {
+    readonly availableSecretStorage?: boolean;
+    readonly availabilityError?: unknown;
+    readonly encryptError?: unknown;
+    readonly decryptError?: unknown;
+  },
+) =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+      prefix: "t3-desktop-saved-environments-test-",
+    });
+    return yield* effect.pipe(Effect.provide(makeLayer(baseDir, options)));
+  }).pipe(Effect.provide(NodeServices.layer), Effect.scoped);
+
+describe("DesktopSavedEnvironments", () => {
+  it.effect("persists and reloads saved environment metadata", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* savedEnvironments.setRegistry([savedRegistryRecord]);
+
+        assert.deepEqual(yield* savedEnvironments.getRegistry, [savedRegistryRecord]);
+        const persisted = yield* decodeSavedEnvironmentRegistryDocumentProbe(
+          yield* fileSystem.readFileString(environment.savedEnvironmentRegistryPath),
+        );
+        assert.equal(persisted.version, 1);
+        assert.lengthOf(persisted.records, 1);
+      }),
+    ),
+  );
+
+  it.effect("loads lenient saved environment registry documents", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(
+          environment.savedEnvironmentRegistryPath,
+          `{
+            // Same optional envelope shape as browser saved environments.
+            "version": 1,
+            "records": [
+              {
+                "environmentId": "${savedRegistryRecord.environmentId}",
+                "label": "Remote environment",
+                "httpBaseUrl": "https://remote.example.com/",
+                "wsBaseUrl": "wss://remote.example.com/",
+                "createdAt": "2026-04-09T00:00:00.000Z",
+                "lastConnectedAt": "2026-04-09T01:00:00.000Z",
+                "desktopSsh": {
+                  "alias": "devbox",
+                  "hostname": "devbox.example.com",
+                  "username": "julius",
+                  "port": 22,
+                },
+              },
+            ],
+          }\n`,
+        );
+
+        assert.deepEqual(yield* savedEnvironments.getRegistry, [savedRegistryRecord]);
+      }),
+    ),
+  );
+
+  it.effect("persists encrypted saved environment secrets when encryption is available", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* savedEnvironments.setRegistry([savedRegistryRecord]);
+
+        assert.isTrue(
+          yield* savedEnvironments.setSecret({
+            environmentId: savedRegistryRecord.environmentId,
+            secret: "bearer-token",
+          }),
+        );
+
+        assert.deepEqual(
+          yield* savedEnvironments.getSecret(savedRegistryRecord.environmentId),
+          Option.some("bearer-token"),
+        );
+      }),
+    ),
+  );
+
+  it.effect("returns false when writing secrets while encryption is unavailable", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* savedEnvironments.setRegistry([savedRegistryRecord]);
+
+        assert.isFalse(
+          yield* savedEnvironments.setSecret({
+            environmentId: savedRegistryRecord.environmentId,
+            secret: "next-token",
+          }),
+        );
+      }),
+      { availableSecretStorage: false },
+    ),
+  );
+
+  it.effect("surfaces typed safe storage availability failures", () => {
+    const cause = new Error("safe storage unavailable");
+    return withSavedEnvironments(
+      Effect.gen(function* () {
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* savedEnvironments.setRegistry([savedRegistryRecord]);
+
+        const error = yield* savedEnvironments
+          .setSecret({
+            environmentId: savedRegistryRecord.environmentId,
+            secret: "next-token",
+          })
+          .pipe(Effect.flip);
+
+        assert.instanceOf(error, ElectronSafeStorage.ElectronSafeStorageAvailabilityError);
+        assert.equal(error.cause, cause);
+      }),
+      { availabilityError: cause },
+    );
+  });
+
+  it.effect("removes saved environment secrets", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* savedEnvironments.setRegistry([savedRegistryRecord]);
+        yield* savedEnvironments.setSecret({
+          environmentId: savedRegistryRecord.environmentId,
+          secret: "bearer-token",
+        });
+
+        yield* savedEnvironments.removeSecret(savedRegistryRecord.environmentId);
+
+        assert.isTrue(
+          Option.isNone(yield* savedEnvironments.getSecret(savedRegistryRecord.environmentId)),
+        );
+      }),
+    ),
+  );
+
+  it.effect("treats empty saved environment documents as empty", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(environment.savedEnvironmentRegistryPath, "{}\n");
+
+        assert.deepEqual(yield* savedEnvironments.getRegistry, []);
+        assert.isTrue(
+          Option.isNone(yield* savedEnvironments.getSecret(savedRegistryRecord.environmentId)),
+        );
+      }),
+    ),
+  );
+
+  it.effect("treats malformed saved environment documents as empty", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const environment = yield* DesktopEnvironment.DesktopEnvironment;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+        yield* fileSystem.writeFileString(environment.savedEnvironmentRegistryPath, "{not-json");
+
+        assert.deepEqual(yield* savedEnvironments.getRegistry, []);
+        assert.isTrue(
+          Option.isNone(yield* savedEnvironments.getSecret(savedRegistryRecord.environmentId)),
+        );
+      }),
+    ),
+  );
+
+  it.effect("returns false when writing a secret without metadata", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+
+        assert.isFalse(
+          yield* savedEnvironments.setSecret({
+            environmentId: savedRegistryRecord.environmentId,
+            secret: "bearer-token",
+          }),
+        );
+      }),
+    ),
+  );
+
+  it.effect("preserves encrypted secrets when metadata is rewritten", () =>
+    withSavedEnvironments(
+      Effect.gen(function* () {
+        const savedEnvironments = yield* DesktopSavedEnvironments.DesktopSavedEnvironments;
+        yield* savedEnvironments.setRegistry([savedRegistryRecord]);
+        yield* savedEnvironments.setSecret({
+          environmentId: savedRegistryRecord.environmentId,
+          secret: "bearer-token",
+        });
+
+        yield* savedEnvironments.setRegistry([savedRegistryRecord]);
+
+        assert.deepEqual(yield* savedEnvironments.getRegistry, [savedRegistryRecord]);
+        assert.deepEqual(
+          yield* savedEnvironments.getSecret(savedRegistryRecord.environmentId),
+          Option.some("bearer-token"),
+        );
+      }),
+    ),
+  );
+});
diff --git a/apps/desktop/src/settings/DesktopSavedEnvironments.ts b/apps/desktop/src/settings/DesktopSavedEnvironments.ts
new file mode 100644
index 00000000000..ec36aa4f6ef
--- /dev/null
+++ b/apps/desktop/src/settings/DesktopSavedEnvironments.ts
@@ -0,0 +1,390 @@
+import { EnvironmentId, type PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
+import { fromLenientJson } from "@t3tools/shared/schemaJson";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import * as Ref from "effect/Ref";
+
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as ElectronSafeStorage from "../electron/ElectronSafeStorage.ts";
+
+type PersistedSavedEnvironmentDesktopSsh = NonNullable<
+  PersistedSavedEnvironmentRecord["desktopSsh"]
+>;
+
+interface PersistedSavedEnvironmentStorageRecord extends Omit<
+  PersistedSavedEnvironmentRecord,
+  "desktopSsh"
+> {
+  readonly desktopSsh?: PersistedSavedEnvironmentDesktopSsh;
+  readonly encryptedBearerToken?: string;
+}
+
+interface SavedEnvironmentRegistryDocument {
+  readonly version: number;
+  readonly records: readonly PersistedSavedEnvironmentStorageRecord[];
+}
+
+interface SavedEnvironmentRegistryStorageDocument {
+  readonly version?: number;
+  readonly records?: readonly PersistedSavedEnvironmentStorageRecord[];
+}
+
+const DesktopSshTargetSchema = Schema.Struct({
+  alias: Schema.String,
+  hostname: Schema.String,
+  username: Schema.NullOr(Schema.String),
+  port: Schema.NullOr(Schema.Number),
+});
+
+const PersistedSavedEnvironmentStorageRecordSchema = Schema.Struct({
+  environmentId: EnvironmentId,
+  label: Schema.String,
+  httpBaseUrl: Schema.String,
+  wsBaseUrl: Schema.String,
+  createdAt: Schema.String,
+  lastConnectedAt: Schema.NullOr(Schema.String),
+  desktopSsh: Schema.optionalKey(DesktopSshTargetSchema),
+  encryptedBearerToken: Schema.optionalKey(Schema.String),
+});
+
+const SavedEnvironmentRegistryDocumentSchema = Schema.Struct({
+  version: Schema.optionalKey(Schema.Number),
+  records: Schema.optionalKey(Schema.Array(PersistedSavedEnvironmentStorageRecordSchema)),
+});
+
+const SavedEnvironmentRegistryDocumentJson = fromLenientJson(
+  SavedEnvironmentRegistryDocumentSchema,
+);
+const decodeSavedEnvironmentRegistryDocumentJson = Schema.decodeEffect(
+  SavedEnvironmentRegistryDocumentJson,
+);
+const encodeSavedEnvironmentRegistryDocumentJson = Schema.encodeEffect(
+  SavedEnvironmentRegistryDocumentJson,
+);
+
+export class DesktopSavedEnvironmentsWriteError extends Data.TaggedError(
+  "DesktopSavedEnvironmentsWriteError",
+)<{
+  readonly cause: PlatformError.PlatformError | Schema.SchemaError;
+}> {
+  override get message() {
+    return `Failed to write desktop saved environments: ${this.cause.message}`;
+  }
+}
+
+export class DesktopSavedEnvironmentSecretDecodeError extends Data.TaggedError(
+  "DesktopSavedEnvironmentSecretDecodeError",
+)<{
+  readonly cause: Encoding.EncodingError;
+}> {
+  override get message() {
+    return "Failed to decode desktop saved environment secret.";
+  }
+}
+
+export type DesktopSavedEnvironmentsGetSecretError =
+  | DesktopSavedEnvironmentSecretDecodeError
+  | ElectronSafeStorage.ElectronSafeStorageAvailabilityError
+  | ElectronSafeStorage.ElectronSafeStorageDecryptError;
+
+export type DesktopSavedEnvironmentsSetSecretError =
+  | DesktopSavedEnvironmentsWriteError
+  | ElectronSafeStorage.ElectronSafeStorageAvailabilityError
+  | ElectronSafeStorage.ElectronSafeStorageEncryptError;
+
+export interface DesktopSavedEnvironmentsShape {
+  readonly getRegistry: Effect.Effect<readonly PersistedSavedEnvironmentRecord[]>;
+  readonly setRegistry: (
+    records: readonly PersistedSavedEnvironmentRecord[],
+  ) => Effect.Effect<void, DesktopSavedEnvironmentsWriteError>;
+  readonly getSecret: (
+    environmentId: string,
+  ) => Effect.Effect<Option.Option<string>, DesktopSavedEnvironmentsGetSecretError>;
+  readonly setSecret: (input: {
+    readonly environmentId: string;
+    readonly secret: string;
+  }) => Effect.Effect<boolean, DesktopSavedEnvironmentsSetSecretError>;
+  readonly removeSecret: (
+    environmentId: string,
+  ) => Effect.Effect<void, DesktopSavedEnvironmentsWriteError>;
+}
+
+export class DesktopSavedEnvironments extends Context.Service<
+  DesktopSavedEnvironments,
+  DesktopSavedEnvironmentsShape
+>()("t3/desktop/SavedEnvironments") {}
+
+function toPersistedSavedEnvironmentRecord(
+  record: PersistedSavedEnvironmentStorageRecord,
+): PersistedSavedEnvironmentRecord {
+  const nextRecord = {
+    environmentId: record.environmentId,
+    label: record.label,
+    httpBaseUrl: record.httpBaseUrl,
+    wsBaseUrl: record.wsBaseUrl,
+    createdAt: record.createdAt,
+    lastConnectedAt: record.lastConnectedAt,
+  };
+  return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
+}
+
+function toSavedEnvironmentStorageRecord(
+  record: PersistedSavedEnvironmentRecord | PersistedSavedEnvironmentStorageRecord,
+  encryptedBearerToken: Option.Option<string>,
+): PersistedSavedEnvironmentStorageRecord {
+  const nextRecord = {
+    environmentId: record.environmentId,
+    label: record.label,
+    httpBaseUrl: record.httpBaseUrl,
+    wsBaseUrl: record.wsBaseUrl,
+    createdAt: record.createdAt,
+    lastConnectedAt: record.lastConnectedAt,
+  };
+  const desktopSsh = record.desktopSsh;
+  if (desktopSsh) {
+    return Option.match(encryptedBearerToken, {
+      onNone: () => ({ ...nextRecord, desktopSsh }),
+      onSome: (value) => ({
+        ...nextRecord,
+        desktopSsh,
+        encryptedBearerToken: value,
+      }),
+    });
+  }
+  return Option.match(encryptedBearerToken, {
+    onNone: () => nextRecord,
+    onSome: (value) => ({ ...nextRecord, encryptedBearerToken: value }),
+  });
+}
+
+function normalizeSavedEnvironmentRegistryDocument(
+  document: SavedEnvironmentRegistryStorageDocument,
+): SavedEnvironmentRegistryDocument {
+  return {
+    version: document.version ?? 1,
+    records: document.records ?? [],
+  };
+}
+
+function readRegistryDocument(
+  fileSystem: FileSystem.FileSystem,
+  registryPath: string,
+): Effect.Effect<SavedEnvironmentRegistryDocument> {
+  return fileSystem.readFileString(registryPath).pipe(
+    Effect.option,
+    Effect.flatMap(
+      Option.match({
+        onNone: () => Effect.succeed({ version: 1, records: [] }),
+        onSome: (raw) =>
+          decodeSavedEnvironmentRegistryDocumentJson(raw).pipe(
+            Effect.map(normalizeSavedEnvironmentRegistryDocument),
+            Effect.catch(() => Effect.succeed({ version: 1, records: [] })),
+          ),
+      }),
+    ),
+  );
+}
+
+const writeRegistryDocument = Effect.fn("desktop.savedEnvironments.writeRegistryDocument")(
+  function* (input: {
+    readonly fileSystem: FileSystem.FileSystem;
+    readonly path: Path.Path;
+    readonly registryPath: string;
+    readonly document: SavedEnvironmentRegistryDocument;
+  }): Effect.fn.Return<void, PlatformError.PlatformError | Schema.SchemaError> {
+    const directory = input.path.dirname(input.registryPath);
+    const suffix = (yield* Random.nextUUIDv4).replace(/-/g, "");
+    const tempPath = `${input.registryPath}.${process.pid}.${suffix}.tmp`;
+    const encoded = yield* encodeSavedEnvironmentRegistryDocumentJson(input.document);
+    yield* input.fileSystem.makeDirectory(directory, { recursive: true });
+    yield* input.fileSystem.writeFileString(tempPath, `${encoded}\n`);
+    yield* input.fileSystem.rename(tempPath, input.registryPath);
+  },
+);
+
+function preserveExistingSecrets(
+  currentDocument: SavedEnvironmentRegistryDocument,
+  records: readonly PersistedSavedEnvironmentRecord[],
+): SavedEnvironmentRegistryDocument {
+  const encryptedBearerTokenById = new Map(
+    currentDocument.records.flatMap((record) =>
+      record.encryptedBearerToken
+        ? [[record.environmentId, record.encryptedBearerToken] as const]
+        : [],
+    ),
+  );
+
+  return {
+    version: currentDocument.version,
+    records: records.map((record) => {
+      const encryptedBearerToken = encryptedBearerTokenById.get(record.environmentId);
+      return toSavedEnvironmentStorageRecord(record, Option.fromNullishOr(encryptedBearerToken));
+    }),
+  };
+}
+
+function decodeSecretBytes(
+  encoded: string,
+): Effect.Effect<Uint8Array, DesktopSavedEnvironmentSecretDecodeError> {
+  return Effect.fromResult(Encoding.decodeBase64(encoded)).pipe(
+    Effect.mapError((cause) => new DesktopSavedEnvironmentSecretDecodeError({ cause })),
+  );
+}
+
+export const layer = Layer.effect(
+  DesktopSavedEnvironments,
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const safeStorage = yield* ElectronSafeStorage.ElectronSafeStorage;
+
+    const writeDocument = (document: SavedEnvironmentRegistryDocument) =>
+      writeRegistryDocument({
+        fileSystem,
+        path,
+        registryPath: environment.savedEnvironmentRegistryPath,
+        document,
+      }).pipe(Effect.mapError((cause) => new DesktopSavedEnvironmentsWriteError({ cause })));
+
+    return DesktopSavedEnvironments.of({
+      getRegistry: readRegistryDocument(fileSystem, environment.savedEnvironmentRegistryPath).pipe(
+        Effect.map((document) =>
+          document.records.map((record) => toPersistedSavedEnvironmentRecord(record)),
+        ),
+        Effect.withSpan("desktop.savedEnvironments.getRegistry"),
+      ),
+      setRegistry: Effect.fn("desktop.savedEnvironments.setRegistry")(function* (records) {
+        const currentDocument = yield* readRegistryDocument(
+          fileSystem,
+          environment.savedEnvironmentRegistryPath,
+        );
+        yield* writeDocument(preserveExistingSecrets(currentDocument, records));
+      }),
+      getSecret: Effect.fn("desktop.savedEnvironments.getSecret")(function* (environmentId) {
+        yield* Effect.annotateCurrentSpan({ environmentId });
+        const document = yield* readRegistryDocument(
+          fileSystem,
+          environment.savedEnvironmentRegistryPath,
+        );
+        const encoded = Option.fromNullishOr(
+          document.records.find((record) => record.environmentId === environmentId)
+            ?.encryptedBearerToken,
+        );
+        if (Option.isNone(encoded) || !(yield* safeStorage.isEncryptionAvailable)) {
+          return Option.none<string>();
+        }
+
+        const secretBytes = yield* decodeSecretBytes(encoded.value);
+        return Option.some(yield* safeStorage.decryptString(secretBytes));
+      }),
+      setSecret: Effect.fn("desktop.savedEnvironments.setSecret")(function* (input) {
+        const { environmentId, secret } = input;
+        yield* Effect.annotateCurrentSpan({ environmentId });
+        const document = yield* readRegistryDocument(
+          fileSystem,
+          environment.savedEnvironmentRegistryPath,
+        );
+
+        if (!(yield* safeStorage.isEncryptionAvailable)) {
+          return false;
+        }
+
+        const encryptedBearerToken = Encoding.encodeBase64(
+          yield* safeStorage.encryptString(secret),
+        );
+        let found = false;
+        const nextDocument: SavedEnvironmentRegistryDocument = {
+          version: document.version,
+          records: document.records.map((record) => {
+            if (record.environmentId !== environmentId) {
+              return record;
+            }
+
+            found = true;
+            return toSavedEnvironmentStorageRecord(record, Option.some(encryptedBearerToken));
+          }),
+        };
+
+        if (found) {
+          yield* writeDocument(nextDocument);
+        }
+        return found;
+      }),
+      removeSecret: Effect.fn("desktop.savedEnvironments.removeSecret")(function* (environmentId) {
+        yield* Effect.annotateCurrentSpan({ environmentId });
+        const document = yield* readRegistryDocument(
+          fileSystem,
+          environment.savedEnvironmentRegistryPath,
+        );
+        if (
+          !document.records.some(
+            (record) =>
+              record.environmentId === environmentId && record.encryptedBearerToken !== undefined,
+          )
+        ) {
+          return;
+        }
+
+        yield* writeDocument({
+          version: document.version,
+          records: document.records.map((record) => {
+            if (record.environmentId !== environmentId) {
+              return record;
+            }
+            return toPersistedSavedEnvironmentRecord(record);
+          }),
+        });
+      }),
+    });
+  }),
+);
+
+export const layerTest = (input?: {
+  readonly records?: readonly PersistedSavedEnvironmentRecord[];
+  readonly secrets?: ReadonlyMap<string, string>;
+}) =>
+  Layer.effect(
+    DesktopSavedEnvironments,
+    Effect.gen(function* () {
+      const recordsRef = yield* Ref.make(input?.records ?? []);
+      const secretsRef = yield* Ref.make(new Map(input?.secrets ?? []));
+
+      return DesktopSavedEnvironments.of({
+        getRegistry: Ref.get(recordsRef),
+        setRegistry: (records) => Ref.set(recordsRef, records),
+        getSecret: (environmentId) =>
+          Ref.get(secretsRef).pipe(
+            Effect.map((secrets) => Option.fromNullishOr(secrets.get(environmentId))),
+          ),
+        setSecret: ({ environmentId, secret }) =>
+          Ref.get(recordsRef).pipe(
+            Effect.flatMap((records) => {
+              if (!records.some((record) => record.environmentId === environmentId)) {
+                return Effect.succeed(false);
+              }
+              return Ref.update(secretsRef, (secrets) => {
+                const nextSecrets = new Map(secrets);
+                nextSecrets.set(environmentId, secret);
+                return nextSecrets;
+              }).pipe(Effect.as(true));
+            }),
+          ),
+        removeSecret: (environmentId) =>
+          Ref.update(secretsRef, (secrets) => {
+            const nextSecrets = new Map(secrets);
+            nextSecrets.delete(environmentId);
+            return nextSecrets;
+          }),
+      });
+    }),
+  );
diff --git a/apps/desktop/src/shell/DesktopShellEnvironment.test.ts b/apps/desktop/src/shell/DesktopShellEnvironment.test.ts
new file mode 100644
index 00000000000..897e7336a24
--- /dev/null
+++ b/apps/desktop/src/shell/DesktopShellEnvironment.test.ts
@@ -0,0 +1,232 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopShellEnvironment from "./DesktopShellEnvironment.ts";
+
+const textEncoder = new TextEncoder();
+
+function envOutput(values: Readonly<Record<string, string>>): string {
+  return Object.entries(values)
+    .flatMap(([name, value]) => [
+      `__T3CODE_ENV_${name}_START__`,
+      value,
+      `__T3CODE_ENV_${name}_END__`,
+    ])
+    .join("\n");
+}
+
+function makeProcess(output: string): ChildProcessSpawner.ChildProcessHandle {
+  const stdout = output.length === 0 ? Stream.empty : Stream.make(textEncoder.encode(output));
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout,
+    stderr: Stream.empty,
+    all: stdout,
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+}
+
+function withProcessEnv<A, E, R>(
+  env: NodeJS.ProcessEnv,
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> {
+  return Effect.acquireUseRelease(
+    Effect.sync(() => {
+      const previous = process.env;
+      process.env = env;
+      return previous;
+    }),
+    () => effect,
+    (previous) =>
+      Effect.sync(() => {
+        process.env = previous;
+      }),
+  );
+}
+
+function runShellEnvironment(input: {
+  readonly env: NodeJS.ProcessEnv;
+  readonly platform: NodeJS.Platform;
+  readonly handler: (command: ChildProcess.Command) => string;
+}) {
+  const environmentLayer = Layer.succeed(
+    DesktopEnvironment.DesktopEnvironment,
+    DesktopEnvironment.DesktopEnvironment.of({
+      platform: input.platform,
+    } as DesktopEnvironment.DesktopEnvironmentShape),
+  );
+  const spawnerLayer = Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make((command) => Effect.succeed(makeProcess(input.handler(command)))),
+  );
+
+  const program = Effect.gen(function* () {
+    const shellEnvironment = yield* DesktopShellEnvironment.DesktopShellEnvironment;
+    yield* shellEnvironment.installIntoProcess;
+  }).pipe(
+    Effect.provide(
+      DesktopShellEnvironment.layer.pipe(
+        Layer.provide(Layer.mergeAll(environmentLayer, spawnerLayer)),
+      ),
+    ),
+  );
+
+  return withProcessEnv(input.env, program);
+}
+
+describe("DesktopShellEnvironment", () => {
+  it.effect("hydrates PATH and missing SSH_AUTH_SOCK from the login shell on macOS", () =>
+    Effect.gen(function* () {
+      const env: NodeJS.ProcessEnv = {
+        SHELL: "/bin/zsh",
+        PATH: "/Users/test/.local/bin:/usr/bin",
+      };
+      const commands: ChildProcess.Command[] = [];
+
+      yield* runShellEnvironment({
+        env,
+        platform: "darwin",
+        handler: (command) => {
+          commands.push(command);
+          return envOutput({
+            PATH: "/opt/homebrew/bin:/usr/bin",
+            SSH_AUTH_SOCK: "/tmp/secretive.sock",
+            HOMEBREW_PREFIX: "/opt/homebrew",
+          });
+        },
+      });
+
+      assert.equal(commands.length, 1);
+      assert.equal(commands[0]?._tag === "StandardCommand" ? commands[0].command : "", "/bin/zsh");
+      assert.equal(env.PATH, "/opt/homebrew/bin:/usr/bin:/Users/test/.local/bin");
+      assert.equal(env.SSH_AUTH_SOCK, "/tmp/secretive.sock");
+      assert.equal(env.HOMEBREW_PREFIX, "/opt/homebrew");
+    }),
+  );
+
+  it.effect("preserves inherited POSIX values when present", () =>
+    Effect.gen(function* () {
+      const env: NodeJS.ProcessEnv = {
+        SHELL: "/bin/zsh",
+        PATH: "/usr/bin",
+        SSH_AUTH_SOCK: "/tmp/inherited.sock",
+      };
+
+      yield* runShellEnvironment({
+        env,
+        platform: "darwin",
+        handler: () =>
+          envOutput({
+            PATH: "/opt/homebrew/bin:/usr/bin",
+            SSH_AUTH_SOCK: "/tmp/login-shell.sock",
+          }),
+      });
+
+      assert.equal(env.PATH, "/opt/homebrew/bin:/usr/bin");
+      assert.equal(env.SSH_AUTH_SOCK, "/tmp/inherited.sock");
+    }),
+  );
+
+  it.effect("hydrates PATH and missing SSH_AUTH_SOCK from the login shell on linux", () =>
+    Effect.gen(function* () {
+      const env: NodeJS.ProcessEnv = {
+        SHELL: "/bin/zsh",
+        PATH: "/usr/bin",
+      };
+
+      yield* runShellEnvironment({
+        env,
+        platform: "linux",
+        handler: () =>
+          envOutput({
+            PATH: "/home/linuxbrew/.linuxbrew/bin:/usr/bin",
+            SSH_AUTH_SOCK: "/tmp/secretive.sock",
+          }),
+      });
+
+      assert.equal(env.PATH, "/home/linuxbrew/.linuxbrew/bin:/usr/bin");
+      assert.equal(env.SSH_AUTH_SOCK, "/tmp/secretive.sock");
+    }),
+  );
+
+  it.effect("falls back to launchctl PATH on macOS when shell probing does not return one", () =>
+    Effect.gen(function* () {
+      const env: NodeJS.ProcessEnv = {
+        SHELL: "/opt/homebrew/bin/nu",
+        PATH: "/usr/bin",
+      };
+      const commands: string[] = [];
+
+      yield* runShellEnvironment({
+        env,
+        platform: "darwin",
+        handler: (command) => {
+          if (command._tag !== "StandardCommand") return "";
+          commands.push(command.command);
+          return command.command === "/bin/launchctl" ? "/opt/homebrew/bin:/usr/bin" : "";
+        },
+      });
+
+      assert.deepEqual(commands, ["/opt/homebrew/bin/nu", "/bin/zsh", "/bin/launchctl"]);
+      assert.equal(env.PATH, "/opt/homebrew/bin:/usr/bin");
+    }),
+  );
+
+  it.effect("loads PowerShell profile environment on Windows", () =>
+    Effect.gen(function* () {
+      const env: NodeJS.ProcessEnv = {
+        PATH: "C:\\Windows\\System32",
+        APPDATA: "C:\\Users\\testuser\\AppData\\Roaming",
+        LOCALAPPDATA: "C:\\Users\\testuser\\AppData\\Local",
+        USERPROFILE: "C:\\Users\\testuser",
+      };
+
+      yield* runShellEnvironment({
+        env,
+        platform: "win32",
+        handler: (command) => {
+          if (command._tag !== "StandardCommand") return "";
+          const loadProfile = !command.args.includes("-NoProfile");
+          return loadProfile
+            ? envOutput({
+                PATH: "C:\\Profile\\Node;C:\\Windows\\System32",
+                FNM_DIR: "C:\\Users\\testuser\\AppData\\Roaming\\fnm",
+                FNM_MULTISHELL_PATH: "C:\\Users\\testuser\\AppData\\Local\\fnm_multishells\\123",
+              })
+            : envOutput({ PATH: "C:\\Custom\\Bin;C:\\Windows\\System32" });
+        },
+      });
+
+      assert.equal(
+        env.PATH,
+        [
+          "C:\\Profile\\Node",
+          "C:\\Windows\\System32",
+          "C:\\Users\\testuser\\AppData\\Roaming\\npm",
+          "C:\\Users\\testuser\\AppData\\Local\\Programs\\nodejs",
+          "C:\\Users\\testuser\\AppData\\Local\\Volta\\bin",
+          "C:\\Users\\testuser\\AppData\\Local\\pnpm",
+          "C:\\Users\\testuser\\.bun\\bin",
+          "C:\\Users\\testuser\\scoop\\shims",
+          "C:\\Custom\\Bin",
+        ].join(";"),
+      );
+      assert.equal(env.FNM_DIR, "C:\\Users\\testuser\\AppData\\Roaming\\fnm");
+      assert.equal(
+        env.FNM_MULTISHELL_PATH,
+        "C:\\Users\\testuser\\AppData\\Local\\fnm_multishells\\123",
+      );
+    }),
+  );
+});
diff --git a/apps/desktop/src/shell/DesktopShellEnvironment.ts b/apps/desktop/src/shell/DesktopShellEnvironment.ts
new file mode 100644
index 00000000000..358729e05ef
--- /dev/null
+++ b/apps/desktop/src/shell/DesktopShellEnvironment.ts
@@ -0,0 +1,356 @@
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+
+type EnvironmentPatch = Record<string, string>;
+
+interface ShellEnvironmentConfig {
+  readonly env: NodeJS.ProcessEnv;
+  readonly platform: NodeJS.Platform;
+  readonly userShell: Option.Option<string>;
+}
+
+interface WindowsProbeOptions {
+  readonly loadProfile: boolean;
+}
+
+export interface DesktopShellEnvironmentShape {
+  readonly installIntoProcess: Effect.Effect<void, never>;
+}
+
+export class DesktopShellEnvironment extends Context.Service<
+  DesktopShellEnvironment,
+  DesktopShellEnvironmentShape
+>()("t3/desktop/ShellEnvironment") {}
+
+const LOGIN_SHELL_ENV_NAMES = [
+  "PATH",
+  "SSH_AUTH_SOCK",
+  "HOMEBREW_PREFIX",
+  "HOMEBREW_CELLAR",
+  "HOMEBREW_REPOSITORY",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+] as const;
+const WINDOWS_PROFILE_ENV_NAMES = ["PATH", "FNM_DIR", "FNM_MULTISHELL_PATH"] as const;
+const WINDOWS_SHELL_CANDIDATES = ["pwsh.exe", "powershell.exe"] as const;
+const LOGIN_SHELL_TIMEOUT = Duration.seconds(5);
+const LAUNCHCTL_TIMEOUT = Duration.seconds(2);
+const PROCESS_TERMINATE_GRACE = Duration.seconds(1);
+
+const trimNonEmpty = (value: string | null | undefined): Option.Option<string> =>
+  Option.fromNullishOr(value).pipe(
+    Option.map((entry) => entry.trim()),
+    Option.filter((entry) => entry.length > 0),
+  );
+
+const pathDelimiter = (platform: NodeJS.Platform) => (platform === "win32" ? ";" : ":");
+
+const readEnvPath = (env: NodeJS.ProcessEnv): Option.Option<string> =>
+  trimNonEmpty(env.PATH ?? env.Path ?? env.path);
+
+const pathComparisonKey = (entry: string, platform: NodeJS.Platform) => {
+  const normalized = entry.trim().replace(/^"+|"+$/g, "");
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+};
+
+const mergePaths = (
+  platform: NodeJS.Platform,
+  values: ReadonlyArray<Option.Option<string>>,
+): Option.Option<string> => {
+  const delimiter = pathDelimiter(platform);
+  const entries: string[] = [];
+  const seen = new Set<string>();
+
+  for (const value of values) {
+    if (Option.isNone(value)) continue;
+
+    for (const entry of value.value.split(delimiter)) {
+      const trimmed = entry.trim();
+      if (trimmed.length === 0) continue;
+
+      const key = pathComparisonKey(trimmed, platform);
+      if (key.length === 0 || seen.has(key)) continue;
+
+      seen.add(key);
+      entries.push(trimmed);
+    }
+  }
+
+  return entries.length > 0 ? Option.some(entries.join(delimiter)) : Option.none();
+};
+
+const listLoginShellCandidates = (config: ShellEnvironmentConfig): ReadonlyArray<string> => {
+  const fallback =
+    config.platform === "darwin" ? "/bin/zsh" : config.platform === "linux" ? "/bin/bash" : "";
+  const seen = new Set<string>();
+  const candidates: string[] = [];
+
+  for (const candidate of [
+    trimNonEmpty(config.env.SHELL),
+    config.userShell,
+    trimNonEmpty(fallback),
+  ]) {
+    if (Option.isNone(candidate) || seen.has(candidate.value)) continue;
+    seen.add(candidate.value);
+    candidates.push(candidate.value);
+  }
+
+  return candidates;
+};
+
+const knownWindowsCliDirs = (env: NodeJS.ProcessEnv): ReadonlyArray<string> => [
+  ...trimNonEmpty(env.APPDATA).pipe(
+    Option.match({
+      onNone: () => [],
+      onSome: (value) => [`${value}\\npm`],
+    }),
+  ),
+  ...trimNonEmpty(env.LOCALAPPDATA).pipe(
+    Option.match({
+      onNone: () => [],
+      onSome: (value) => [`${value}\\Programs\\nodejs`, `${value}\\Volta\\bin`, `${value}\\pnpm`],
+    }),
+  ),
+  ...trimNonEmpty(env.USERPROFILE).pipe(
+    Option.match({
+      onNone: () => [],
+      onSome: (value) => [`${value}\\.bun\\bin`, `${value}\\scoop\\shims`],
+    }),
+  ),
+];
+
+const startMarker = (name: string) => `__T3CODE_ENV_${name}_START__`;
+const endMarker = (name: string) => `__T3CODE_ENV_${name}_END__`;
+
+const capturePosixEnvironmentCommand = (names: ReadonlyArray<string>) =>
+  names
+    .map((name) => {
+      return [
+        `printf '%s\\n' '${startMarker(name)}'`,
+        `printenv ${name} || true`,
+        `printf '%s\\n' '${endMarker(name)}'`,
+      ].join("; ");
+    })
+    .join("; ");
+
+const captureWindowsEnvironmentCommand = (names: ReadonlyArray<string>) =>
+  [
+    "$ErrorActionPreference = 'Stop'",
+    ...names.flatMap((name) => {
+      return [
+        `Write-Output '${startMarker(name)}'`,
+        `$value = [Environment]::GetEnvironmentVariable('${name}')`,
+        "if ($null -ne $value -and $value.Length -gt 0) { Write-Output $value }",
+        `Write-Output '${endMarker(name)}'`,
+      ];
+    }),
+  ].join("; ");
+
+const extractEnvironment = (output: string, names: ReadonlyArray<string>): EnvironmentPatch => {
+  const environment: EnvironmentPatch = {};
+
+  for (const name of names) {
+    const start = output.indexOf(startMarker(name));
+    if (start === -1) continue;
+
+    const valueStart = start + startMarker(name).length;
+    const end = output.indexOf(endMarker(name), valueStart);
+    if (end === -1) continue;
+
+    const value = output
+      .slice(valueStart, end)
+      .replace(/^\r?\n/, "")
+      .replace(/\r?\n$/, "");
+    if (value.length > 0) {
+      environment[name] = value;
+    }
+  }
+
+  return environment;
+};
+
+const runCommandOutput = Effect.fn("desktop.shellEnvironment.runCommandOutput")(function* (input: {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly timeout: Duration.Duration;
+  readonly shell?: boolean;
+}): Effect.fn.Return<string, never, ChildProcessSpawner.ChildProcessSpawner> {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  return yield* spawner
+    .string(
+      ChildProcess.make(input.command, input.args, {
+        shell: input.shell ?? false,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+        killSignal: "SIGTERM",
+        forceKillAfter: PROCESS_TERMINATE_GRACE,
+      }),
+    )
+    .pipe(
+      Effect.timeoutOption(input.timeout),
+      Effect.map(Option.getOrElse(() => "")),
+      Effect.catch(() => Effect.succeed("")),
+    );
+});
+
+const readLoginShellEnvironment = (
+  shell: string,
+  names: ReadonlyArray<string>,
+): Effect.Effect<EnvironmentPatch, never, ChildProcessSpawner.ChildProcessSpawner> =>
+  names.length === 0
+    ? Effect.succeed({})
+    : runCommandOutput({
+        command: shell,
+        args: ["-ilc", capturePosixEnvironmentCommand(names)],
+        timeout: LOGIN_SHELL_TIMEOUT,
+      }).pipe(Effect.map((output) => extractEnvironment(output, names)));
+
+const readLaunchctlPath: Effect.Effect<
+  Option.Option<string>,
+  never,
+  ChildProcessSpawner.ChildProcessSpawner
+> = runCommandOutput({
+  command: "/bin/launchctl",
+  args: ["getenv", "PATH"],
+  timeout: LAUNCHCTL_TIMEOUT,
+}).pipe(Effect.map(trimNonEmpty));
+
+const readWindowsEnvironment = Effect.fn("desktop.shellEnvironment.readWindowsEnvironment")(
+  function* (
+    names: ReadonlyArray<string>,
+    options: WindowsProbeOptions,
+  ): Effect.fn.Return<EnvironmentPatch, never, ChildProcessSpawner.ChildProcessSpawner> {
+    if (names.length === 0) return {};
+
+    const args = [
+      "-NoLogo",
+      ...(options.loadProfile ? ([] as const) : (["-NoProfile"] as const)),
+      "-NonInteractive",
+      "-Command",
+      captureWindowsEnvironmentCommand(names),
+    ];
+
+    for (const command of WINDOWS_SHELL_CANDIDATES) {
+      const output = yield* runCommandOutput({
+        command,
+        args,
+        shell: true,
+        timeout: LOGIN_SHELL_TIMEOUT,
+      });
+      const environment = extractEnvironment(output, names);
+      if (Object.keys(environment).length > 0) {
+        return environment;
+      }
+    }
+
+    return {};
+  },
+);
+
+const installWindowsEnvironment = Effect.fn("desktop.shellEnvironment.installWindowsEnvironment")(
+  function* (
+    config: ShellEnvironmentConfig,
+  ): Effect.fn.Return<void, never, ChildProcessSpawner.ChildProcessSpawner> {
+    const noProfile = yield* readWindowsEnvironment(["PATH"], { loadProfile: false });
+    const profile = yield* readWindowsEnvironment(WINDOWS_PROFILE_ENV_NAMES, {
+      loadProfile: true,
+    });
+    const mergedPath = mergePaths("win32", [
+      trimNonEmpty(profile.PATH),
+      trimNonEmpty(knownWindowsCliDirs(config.env).join(";")),
+      trimNonEmpty(noProfile.PATH),
+      readEnvPath(config.env),
+    ]);
+
+    if (Option.isSome(mergedPath)) {
+      config.env.PATH = mergedPath.value;
+    }
+    if (!config.env.FNM_DIR && profile.FNM_DIR) {
+      config.env.FNM_DIR = profile.FNM_DIR;
+    }
+    if (!config.env.FNM_MULTISHELL_PATH && profile.FNM_MULTISHELL_PATH) {
+      config.env.FNM_MULTISHELL_PATH = profile.FNM_MULTISHELL_PATH;
+    }
+  },
+);
+
+const installPosixEnvironment = Effect.fn("desktop.shellEnvironment.installPosixEnvironment")(
+  function* (
+    config: ShellEnvironmentConfig,
+  ): Effect.fn.Return<void, never, ChildProcessSpawner.ChildProcessSpawner> {
+    const shellEnvironment: EnvironmentPatch = {};
+
+    for (const shell of listLoginShellCandidates(config)) {
+      Object.assign(
+        shellEnvironment,
+        yield* readLoginShellEnvironment(shell, LOGIN_SHELL_ENV_NAMES),
+      );
+      if (shellEnvironment.PATH) break;
+    }
+
+    const launchctlPath =
+      config.platform === "darwin" && !shellEnvironment.PATH
+        ? yield* readLaunchctlPath
+        : Option.none<string>();
+    const mergedPath = mergePaths(config.platform, [
+      trimNonEmpty(shellEnvironment.PATH).pipe(Option.orElse(() => launchctlPath)),
+      readEnvPath(config.env),
+    ]);
+
+    if (Option.isSome(mergedPath)) {
+      config.env.PATH = mergedPath.value;
+    }
+    if (!config.env.SSH_AUTH_SOCK && shellEnvironment.SSH_AUTH_SOCK) {
+      config.env.SSH_AUTH_SOCK = shellEnvironment.SSH_AUTH_SOCK;
+    }
+
+    for (const name of [
+      "HOMEBREW_PREFIX",
+      "HOMEBREW_CELLAR",
+      "HOMEBREW_REPOSITORY",
+      "XDG_CONFIG_HOME",
+      "XDG_DATA_HOME",
+    ] as const) {
+      if (!config.env[name] && shellEnvironment[name]) {
+        config.env[name] = shellEnvironment[name];
+      }
+    }
+  },
+);
+
+const installShellEnvironment = (
+  config: ShellEnvironmentConfig,
+): Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner> => {
+  if (config.platform === "win32") {
+    return installWindowsEnvironment(config);
+  }
+  if (config.platform === "darwin" || config.platform === "linux") {
+    return installPosixEnvironment(config);
+  }
+  return Effect.void;
+};
+
+export const layer = Layer.effect(
+  DesktopShellEnvironment,
+  Effect.gen(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    return DesktopShellEnvironment.of({
+      installIntoProcess: installShellEnvironment({
+        env: process.env,
+        platform: environment.platform,
+        userShell: Option.none(),
+      }).pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+        Effect.withSpan("desktop.shellEnvironment.installIntoProcess"),
+      ),
+    });
+  }),
+);
diff --git a/apps/desktop/src/ssh/DesktopSshEnvironment.test.ts b/apps/desktop/src/ssh/DesktopSshEnvironment.test.ts
new file mode 100644
index 00000000000..77c86be39d2
--- /dev/null
+++ b/apps/desktop/src/ssh/DesktopSshEnvironment.test.ts
@@ -0,0 +1,118 @@
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as NetService from "@t3tools/shared/Net";
+import { SshPasswordPromptError } from "@t3tools/ssh/errors";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+
+import * as DesktopSshEnvironment from "./DesktopSshEnvironment.ts";
+import * as DesktopSshPasswordPrompts from "./DesktopSshPasswordPrompts.ts";
+
+function makeTempHomeDir() {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    return yield* fs.makeTempDirectoryScoped({ prefix: "t3-ssh-env-test-" });
+  });
+}
+
+describe("sshEnvironment", () => {
+  it("treats password prompt timeouts as cancellable authentication prompts", () => {
+    assert.equal(
+      DesktopSshEnvironment.isDesktopSshPasswordPromptCancellation(
+        new SshPasswordPromptError({
+          message: "SSH authentication timed out for devbox.",
+          cause: new DesktopSshPasswordPrompts.DesktopSshPromptTimedOutError({
+            requestId: "prompt-1",
+            destination: "devbox",
+          }),
+        }),
+      ),
+      true,
+    );
+  });
+
+  it.effect("wires desktop host discovery through the ssh package runtime", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const homeDir = yield* makeTempHomeDir();
+      const sshDir = path.join(homeDir, ".ssh");
+      yield* fs.makeDirectory(path.join(sshDir, "config.d"), { recursive: true });
+      yield* fs.writeFileString(
+        path.join(sshDir, "config"),
+        ["Host devbox", "  HostName devbox.example.com", "Include config.d/*.conf", ""].join("\n"),
+      );
+      yield* fs.writeFileString(
+        path.join(sshDir, "config.d", "team.conf"),
+        [
+          "Host staging",
+          "  HostName staging.example.com",
+          "Host *",
+          "  ServerAliveInterval 30",
+          "",
+        ].join("\n"),
+      );
+      yield* fs.writeFileString(
+        path.join(sshDir, "known_hosts"),
+        [
+          "known.example.com ssh-ed25519 AAAA",
+          "|1|hashed|entry ssh-ed25519 AAAA",
+          "[bastion.example.com]:2222 ssh-ed25519 AAAA",
+          "",
+        ].join("\n"),
+      );
+
+      const sshEnvironment = yield* DesktopSshEnvironment.DesktopSshEnvironment;
+      const hosts = yield* sshEnvironment.discoverHosts({ homeDir });
+      assert.deepEqual(hosts, [
+        {
+          alias: "bastion.example.com",
+          hostname: "bastion.example.com",
+          username: null,
+          port: null,
+          source: "known-hosts",
+        },
+        {
+          alias: "devbox",
+          hostname: "devbox",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
+        {
+          alias: "known.example.com",
+          hostname: "known.example.com",
+          username: null,
+          port: null,
+          source: "known-hosts",
+        },
+        {
+          alias: "staging",
+          hostname: "staging",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
+      ]);
+    }).pipe(
+      Effect.provide(
+        DesktopSshEnvironment.layer().pipe(
+          Layer.provideMerge(
+            Layer.succeed(DesktopSshPasswordPrompts.DesktopSshPasswordPrompts, {
+              request: () => Effect.die("unexpected password prompt request"),
+              resolve: () => Effect.die("unexpected password prompt resolution"),
+              cancelPending: () => Effect.void,
+            }),
+          ),
+          Layer.provideMerge(NodeServices.layer),
+          Layer.provideMerge(NodeHttpClient.layerUndici),
+          Layer.provideMerge(NetService.layer),
+        ),
+      ),
+      Effect.scoped,
+    ),
+  );
+});
diff --git a/apps/desktop/src/ssh/DesktopSshEnvironment.ts b/apps/desktop/src/ssh/DesktopSshEnvironment.ts
new file mode 100644
index 00000000000..2fbf1f4357b
--- /dev/null
+++ b/apps/desktop/src/ssh/DesktopSshEnvironment.ts
@@ -0,0 +1,150 @@
+import type {
+  DesktopDiscoveredSshHost,
+  DesktopSshEnvironmentBootstrap,
+  DesktopSshEnvironmentTarget,
+} from "@t3tools/contracts";
+import * as NetService from "@t3tools/shared/Net";
+import {
+  SshPasswordPrompt,
+  type SshPasswordPromptShape,
+  type SshPasswordRequest,
+} from "@t3tools/ssh/auth";
+import { discoverSshHosts } from "@t3tools/ssh/config";
+import {
+  SshCommandError,
+  SshHostDiscoveryError,
+  SshInvalidTargetError,
+  SshLaunchError,
+  SshPairingError,
+  SshPasswordPromptError,
+  SshReadinessError,
+} from "@t3tools/ssh/errors";
+import { SshEnvironmentManager, type RemoteT3RunnerOptions } from "@t3tools/ssh/tunnel";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as DesktopSshPasswordPrompts from "./DesktopSshPasswordPrompts.ts";
+
+export type DesktopSshEnvironmentRuntimeServices =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | HttpClient.HttpClient
+  | NetService.NetService;
+
+export type DesktopSshEnvironmentOperationError =
+  | SshCommandError
+  | SshInvalidTargetError
+  | SshLaunchError
+  | SshPairingError
+  | SshReadinessError
+  | SshPasswordPromptError
+  | NetService.NetError;
+
+export type DesktopSshEnvironmentDiscoverError = SshHostDiscoveryError;
+
+export type DesktopSshEnvironmentError =
+  | DesktopSshEnvironmentDiscoverError
+  | DesktopSshEnvironmentOperationError;
+
+export interface DesktopSshEnvironmentShape {
+  readonly discoverHosts: (input?: {
+    readonly homeDir?: string;
+  }) => Effect.Effect<readonly DesktopDiscoveredSshHost[], DesktopSshEnvironmentDiscoverError>;
+  readonly ensureEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+    options?: { readonly issuePairingToken?: boolean },
+  ) => Effect.Effect<DesktopSshEnvironmentBootstrap, DesktopSshEnvironmentOperationError>;
+  readonly disconnectEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+  ) => Effect.Effect<void, DesktopSshEnvironmentOperationError>;
+}
+
+export class DesktopSshEnvironment extends Context.Service<
+  DesktopSshEnvironment,
+  DesktopSshEnvironmentShape
+>()("t3/desktop/SshEnvironment") {}
+
+export interface DesktopSshEnvironmentLayerOptions {
+  readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: Effect.Effect<RemoteT3RunnerOptions>;
+}
+
+function discoverDesktopSshHostsEffect(input?: { readonly homeDir?: string }) {
+  return discoverSshHosts(input ?? {});
+}
+
+export function isDesktopSshPasswordPromptCancellation(
+  error: unknown,
+): error is SshPasswordPromptError {
+  return (
+    error instanceof SshPasswordPromptError &&
+    DesktopSshPasswordPrompts.isDesktopSshPasswordPromptCancellation(error.cause)
+  );
+}
+
+const makePasswordPrompt = (
+  prompts: DesktopSshPasswordPrompts.DesktopSshPasswordPromptsShape,
+): SshPasswordPromptShape => ({
+  isAvailable: true,
+  request: (request: SshPasswordRequest) =>
+    prompts.request(request).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SshPasswordPromptError({
+            message: cause.message,
+            cause,
+          }),
+      ),
+    ),
+});
+
+const make = Effect.gen(function* () {
+  const manager = yield* SshEnvironmentManager;
+  const prompts = yield* DesktopSshPasswordPrompts.DesktopSshPasswordPrompts;
+  const runtimeContext = yield* Effect.context<DesktopSshEnvironmentRuntimeServices>();
+  const passwordPrompt = SshPasswordPrompt.of(makePasswordPrompt(prompts));
+
+  return DesktopSshEnvironment.of({
+    discoverHosts: (input) =>
+      discoverDesktopSshHostsEffect(input).pipe(
+        Effect.provide(runtimeContext),
+        Effect.withSpan("desktop.ssh.discoverHosts"),
+      ),
+    ensureEnvironment: (target, ensureOptions) =>
+      manager
+        .ensureEnvironment(target, ensureOptions)
+        .pipe(
+          Effect.provideService(SshPasswordPrompt, passwordPrompt),
+          Effect.provide(runtimeContext),
+          Effect.withSpan("desktop.ssh.ensureEnvironment"),
+        ),
+    disconnectEnvironment: (target) =>
+      manager
+        .disconnectEnvironment(target)
+        .pipe(
+          Effect.provideService(SshPasswordPrompt, passwordPrompt),
+          Effect.provide(runtimeContext),
+          Effect.withSpan("desktop.ssh.disconnectEnvironment"),
+        ),
+  });
+});
+
+export const layer = (options: DesktopSshEnvironmentLayerOptions = {}) =>
+  Layer.effect(DesktopSshEnvironment, make).pipe(
+    Layer.provide(
+      SshEnvironmentManager.layer({
+        ...(options.resolveCliPackageSpec === undefined
+          ? {}
+          : { resolveCliPackageSpec: options.resolveCliPackageSpec }),
+        ...(options.resolveCliRunner === undefined
+          ? {}
+          : { resolveCliRunner: options.resolveCliRunner }),
+      }),
+    ),
+  );
diff --git a/apps/desktop/src/ssh/DesktopSshPasswordPrompts.test.ts b/apps/desktop/src/ssh/DesktopSshPasswordPrompts.test.ts
new file mode 100644
index 00000000000..9e9cfcc737e
--- /dev/null
+++ b/apps/desktop/src/ssh/DesktopSshPasswordPrompts.test.ts
@@ -0,0 +1,144 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as TestClock from "effect/testing/TestClock";
+import type * as Electron from "electron";
+
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
+import * as IpcChannels from "../ipc/channels.ts";
+import * as DesktopSshPasswordPrompts from "./DesktopSshPasswordPrompts.ts";
+
+interface SentMessage {
+  readonly channel: string;
+  readonly args: readonly unknown[];
+}
+
+function makeTestWindow() {
+  const listeners = new Map<string, Set<() => void>>();
+  const sentMessages: SentMessage[] = [];
+  let destroyed = false;
+  let minimized = true;
+  let restored = false;
+  let focused = false;
+
+  const window = {
+    isDestroyed: () => destroyed,
+    isMinimized: () => minimized,
+    restore: () => {
+      restored = true;
+      minimized = false;
+    },
+    focus: () => {
+      focused = true;
+    },
+    once: (eventName: string, listener: () => void) => {
+      const eventListeners = listeners.get(eventName) ?? new Set<() => void>();
+      eventListeners.add(listener);
+      listeners.set(eventName, eventListeners);
+    },
+    removeListener: (eventName: string, listener: () => void) => {
+      listeners.get(eventName)?.delete(listener);
+    },
+    webContents: {
+      send: (channel: string, ...args: readonly unknown[]) => {
+        sentMessages.push({ channel, args });
+      },
+    },
+  };
+
+  return {
+    window,
+    sentMessages,
+    isRestored: () => restored,
+    isFocused: () => focused,
+    close: () => {
+      destroyed = true;
+      const closedListeners = [...(listeners.get("closed") ?? [])];
+      listeners.delete("closed");
+      for (const listener of closedListeners) {
+        listener();
+      }
+    },
+  };
+}
+
+function makeElectronWindowLayer(window: ReturnType<typeof makeTestWindow>["window"]) {
+  return Layer.succeed(
+    ElectronWindow.ElectronWindow,
+    ElectronWindow.ElectronWindow.of({
+      create: () => Effect.die("unexpected BrowserWindow creation"),
+      main: Effect.succeed(Option.some(window as Electron.BrowserWindow)),
+      currentMainOrFirst: Effect.succeed(Option.some(window as Electron.BrowserWindow)),
+      focusedMainOrFirst: Effect.succeed(Option.some(window as Electron.BrowserWindow)),
+      setMain: () => Effect.void,
+      clearMain: () => Effect.void,
+      reveal: () => Effect.void,
+      sendAll: () => Effect.void,
+      destroyAll: Effect.void,
+      syncAllAppearance: () => Effect.void,
+    }),
+  );
+}
+
+function makeLayer(window: ReturnType<typeof makeTestWindow>["window"]) {
+  return DesktopSshPasswordPrompts.layer({ passwordPromptTimeoutMs: 1_000 }).pipe(
+    Layer.provide(makeElectronWindowLayer(window)),
+    Layer.provideMerge(TestClock.layer()),
+  );
+}
+
+describe("DesktopSshPasswordPrompts", () => {
+  it.effect("sends renderer prompts and resolves them by request id", () => {
+    const testWindow = makeTestWindow();
+
+    return Effect.gen(function* () {
+      const prompts = yield* DesktopSshPasswordPrompts.DesktopSshPasswordPrompts;
+      const fiber = yield* prompts
+        .request({
+          destination: "devbox",
+          username: "julius",
+          prompt: "Enter the SSH password.",
+          attempt: 1,
+        })
+        .pipe(Effect.forkScoped);
+
+      yield* Effect.yieldNow;
+      assert.equal(testWindow.sentMessages.length, 1);
+      const sent = testWindow.sentMessages[0];
+      assert.ok(sent);
+      assert.equal(sent.channel, IpcChannels.SSH_PASSWORD_PROMPT_CHANNEL);
+      const request = sent.args[0] as { readonly requestId: string; readonly destination: string };
+      assert.equal(request.destination, "devbox");
+      assert.equal(testWindow.isRestored(), true);
+      assert.equal(testWindow.isFocused(), true);
+
+      yield* prompts.resolve({ requestId: request.requestId, password: "secret" });
+      assert.equal(yield* Fiber.join(fiber), "secret");
+    }).pipe(Effect.provide(makeLayer(testWindow.window)), Effect.scoped);
+  });
+
+  it.effect("times out pending renderer prompts with a typed error", () => {
+    const testWindow = makeTestWindow();
+
+    return Effect.gen(function* () {
+      const prompts = yield* DesktopSshPasswordPrompts.DesktopSshPasswordPrompts;
+      const fiber = yield* prompts
+        .request({
+          destination: "devbox",
+          username: null,
+          prompt: "Enter the SSH password.",
+          attempt: 1,
+        })
+        .pipe(Effect.forkScoped);
+
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(1_000));
+      const error = yield* Fiber.join(fiber).pipe(Effect.flip);
+      assert.instanceOf(error, DesktopSshPasswordPrompts.DesktopSshPromptTimedOutError);
+      assert.equal(error.destination, "devbox");
+    }).pipe(Effect.provide(makeLayer(testWindow.window)), Effect.scoped);
+  });
+});
diff --git a/apps/desktop/src/ssh/DesktopSshPasswordPrompts.ts b/apps/desktop/src/ssh/DesktopSshPasswordPrompts.ts
new file mode 100644
index 00000000000..a53de9fd8e4
--- /dev/null
+++ b/apps/desktop/src/ssh/DesktopSshPasswordPrompts.ts
@@ -0,0 +1,332 @@
+import type { DesktopSshPasswordPromptRequest } from "@t3tools/contracts";
+import { DesktopSshPasswordPromptResolutionInputSchema } from "@t3tools/contracts";
+import type { SshPasswordRequest } from "@t3tools/ssh/auth";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Random from "effect/Random";
+import * as Ref from "effect/Ref";
+
+import * as IpcChannels from "../ipc/channels.ts";
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
+
+const DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
+const WINDOW_UNAVAILABLE_MESSAGE = "T3 Code window is not available for SSH authentication.";
+
+type DesktopSshPasswordPromptResolutionInput =
+  typeof DesktopSshPasswordPromptResolutionInputSchema.Type;
+
+export class DesktopSshPromptUnavailableError extends Data.TaggedError(
+  "DesktopSshPromptUnavailableError",
+)<{
+  readonly reason: string;
+}> {
+  override get message() {
+    return this.reason;
+  }
+}
+
+export class DesktopSshPromptWindowUnavailableError extends Data.TaggedError(
+  "DesktopSshPromptWindowUnavailableError",
+)<{
+  readonly destination: string;
+}> {
+  override get message() {
+    return WINDOW_UNAVAILABLE_MESSAGE;
+  }
+}
+
+export class DesktopSshPromptSendError extends Data.TaggedError("DesktopSshPromptSendError")<{
+  readonly requestId: string;
+  readonly destination: string;
+  readonly cause: unknown;
+}> {
+  override get message() {
+    return WINDOW_UNAVAILABLE_MESSAGE;
+  }
+}
+
+export class DesktopSshPromptTimedOutError extends Data.TaggedError(
+  "DesktopSshPromptTimedOutError",
+)<{
+  readonly requestId: string;
+  readonly destination: string;
+}> {
+  override get message() {
+    return `SSH authentication timed out for ${this.destination}.`;
+  }
+}
+
+export class DesktopSshPromptCancelledError extends Data.TaggedError(
+  "DesktopSshPromptCancelledError",
+)<{
+  readonly requestId: string;
+  readonly destination: string;
+  readonly reason: string;
+}> {
+  override get message() {
+    return this.reason;
+  }
+}
+
+export class DesktopSshPromptInvalidRequestIdError extends Data.TaggedError(
+  "DesktopSshPromptInvalidRequestIdError",
+)<{
+  readonly requestId: string;
+}> {
+  override get message() {
+    return "Invalid SSH password prompt id.";
+  }
+}
+
+export class DesktopSshPromptExpiredError extends Data.TaggedError("DesktopSshPromptExpiredError")<{
+  readonly requestId: string;
+}> {
+  override get message() {
+    return "SSH password prompt expired. Try connecting again.";
+  }
+}
+
+export type DesktopSshPasswordPromptRequestError =
+  | DesktopSshPromptUnavailableError
+  | DesktopSshPromptWindowUnavailableError
+  | DesktopSshPromptSendError
+  | DesktopSshPromptTimedOutError
+  | DesktopSshPromptCancelledError;
+
+export type DesktopSshPasswordPromptResolveError =
+  | DesktopSshPromptInvalidRequestIdError
+  | DesktopSshPromptExpiredError;
+
+export type DesktopSshPasswordPromptError =
+  | DesktopSshPasswordPromptRequestError
+  | DesktopSshPasswordPromptResolveError;
+
+export function isDesktopSshPasswordPromptCancellation(
+  error: unknown,
+): error is DesktopSshPromptCancelledError | DesktopSshPromptTimedOutError {
+  return (
+    error instanceof DesktopSshPromptCancelledError ||
+    error instanceof DesktopSshPromptTimedOutError
+  );
+}
+
+export interface DesktopSshPasswordPromptsShape {
+  readonly request: (
+    request: SshPasswordRequest,
+  ) => Effect.Effect<string, DesktopSshPasswordPromptRequestError>;
+  readonly resolve: (
+    input: DesktopSshPasswordPromptResolutionInput,
+  ) => Effect.Effect<void, DesktopSshPasswordPromptResolveError>;
+  readonly cancelPending: (reason: string) => Effect.Effect<void>;
+}
+
+export class DesktopSshPasswordPrompts extends Context.Service<
+  DesktopSshPasswordPrompts,
+  DesktopSshPasswordPromptsShape
+>()("t3/desktop/SshPasswordPrompts") {}
+
+interface PendingSshPasswordPrompt {
+  readonly requestId: string;
+  readonly destination: string;
+  readonly deferred: Deferred.Deferred<string, DesktopSshPasswordPromptRequestError>;
+}
+
+interface LayerOptions {
+  readonly passwordPromptTimeoutMs?: number;
+}
+
+const removePending = (
+  pendingRef: Ref.Ref<Map<string, PendingSshPasswordPrompt>>,
+  requestId: string,
+) =>
+  Ref.modify(pendingRef, (pending) => {
+    const entry = pending.get(requestId);
+    if (entry === undefined) {
+      return [Option.none<PendingSshPasswordPrompt>(), pending] as const;
+    }
+
+    const nextPending = new Map(pending);
+    nextPending.delete(requestId);
+    return [Option.some(entry), nextPending] as const;
+  });
+
+const failPending = (
+  pending: PendingSshPasswordPrompt,
+  error: DesktopSshPasswordPromptRequestError,
+) => Deferred.fail(pending.deferred, error).pipe(Effect.asVoid);
+
+const make = Effect.fn("desktop.sshPasswordPrompts.make")(function* (options: LayerOptions = {}) {
+  const electronWindow = yield* ElectronWindow.ElectronWindow;
+  const pendingRef = yield* Ref.make(new Map<string, PendingSshPasswordPrompt>());
+  const passwordPromptTimeoutMs =
+    options.passwordPromptTimeoutMs ?? DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS;
+
+  const cancelPending = (reason: string): Effect.Effect<void> =>
+    Ref.getAndSet(pendingRef, new Map()).pipe(
+      Effect.flatMap((pending) =>
+        Effect.forEach(
+          pending.values(),
+          (entry) =>
+            failPending(
+              entry,
+              new DesktopSshPromptCancelledError({
+                requestId: entry.requestId,
+                destination: entry.destination,
+                reason,
+              }),
+            ),
+          { discard: true },
+        ),
+      ),
+      Effect.asVoid,
+    );
+
+  yield* Effect.addFinalizer(() =>
+    cancelPending("SSH password prompt service stopped.").pipe(Effect.ignore),
+  );
+
+  const resolve = Effect.fn("desktop.sshPasswordPrompts.resolve")(function* (
+    input: DesktopSshPasswordPromptResolutionInput,
+  ): Effect.fn.Return<void, DesktopSshPasswordPromptResolveError> {
+    const requestId = input.requestId.trim();
+    if (requestId.length === 0) {
+      return yield* new DesktopSshPromptInvalidRequestIdError({ requestId: input.requestId });
+    }
+
+    const pending = yield* removePending(pendingRef, requestId);
+    if (Option.isNone(pending)) {
+      return yield* new DesktopSshPromptExpiredError({ requestId });
+    }
+
+    const entry = pending.value;
+    if (input.password === null) {
+      yield* failPending(
+        entry,
+        new DesktopSshPromptCancelledError({
+          requestId,
+          destination: entry.destination,
+          reason: `SSH authentication cancelled for ${entry.destination}.`,
+        }),
+      );
+      return;
+    }
+
+    yield* Deferred.succeed(entry.deferred, input.password).pipe(Effect.asVoid);
+  });
+
+  const request = Effect.fn("desktop.sshPasswordPrompts.request")(function* (
+    input: SshPasswordRequest,
+  ): Effect.fn.Return<string, DesktopSshPasswordPromptRequestError> {
+    const window = yield* electronWindow.main;
+    if (Option.isNone(window) || window.value.isDestroyed()) {
+      return yield* new DesktopSshPromptWindowUnavailableError({
+        destination: input.destination,
+      });
+    }
+
+    const requestId = yield* Random.nextUUIDv4;
+    const now = yield* DateTime.now;
+    const expiresAt = DateTime.formatIso(
+      DateTime.add(now, { milliseconds: passwordPromptTimeoutMs }),
+    );
+    const promptRequest: DesktopSshPasswordPromptRequest = {
+      requestId,
+      destination: input.destination,
+      username: input.username,
+      prompt: input.prompt,
+      expiresAt,
+    };
+    const deferred = yield* Deferred.make<string, DesktopSshPasswordPromptRequestError>();
+    const pending: PendingSshPasswordPrompt = {
+      requestId,
+      destination: input.destination,
+      deferred,
+    };
+    yield* Ref.update(pendingRef, (entries) => new Map(entries).set(requestId, pending));
+
+    const context = yield* Effect.context();
+    const runFork = Effect.runForkWith(context);
+
+    const cancelOnWindowClosed = () => {
+      runFork(
+        removePending(pendingRef, requestId).pipe(
+          Effect.flatMap((entry) =>
+            Option.match(entry, {
+              onNone: () => Effect.void,
+              onSome: (pending) =>
+                failPending(
+                  pending,
+                  new DesktopSshPromptCancelledError({
+                    requestId,
+                    destination: input.destination,
+                    reason: "SSH authentication was cancelled because the app window closed.",
+                  }),
+                ),
+            }),
+          ),
+        ),
+      );
+    };
+    const cleanup = Effect.sync(() => {
+      if (!window.value.isDestroyed()) {
+        window.value.removeListener("closed", cancelOnWindowClosed);
+      }
+    }).pipe(Effect.andThen(removePending(pendingRef, requestId)), Effect.asVoid);
+    const waitForPassword = Deferred.await(deferred).pipe(
+      Effect.timeoutOption(Duration.millis(passwordPromptTimeoutMs)),
+      Effect.flatMap(
+        Option.match({
+          onNone: () =>
+            Effect.fail(
+              new DesktopSshPromptTimedOutError({
+                requestId,
+                destination: input.destination,
+              }),
+            ),
+          onSome: Effect.succeed,
+        }),
+      ),
+    );
+
+    return yield* Effect.try({
+      try: () => {
+        if (window.value.isDestroyed()) {
+          throw new Error(WINDOW_UNAVAILABLE_MESSAGE);
+        }
+        window.value.once("closed", cancelOnWindowClosed);
+        window.value.webContents.send(IpcChannels.SSH_PASSWORD_PROMPT_CHANNEL, promptRequest);
+        if (window.value.isDestroyed()) {
+          throw new Error(WINDOW_UNAVAILABLE_MESSAGE);
+        }
+        if (window.value.isMinimized()) {
+          window.value.restore();
+        }
+        if (window.value.isDestroyed()) {
+          throw new Error(WINDOW_UNAVAILABLE_MESSAGE);
+        }
+        window.value.focus();
+      },
+      catch: (cause) =>
+        new DesktopSshPromptSendError({
+          requestId,
+          destination: input.destination,
+          cause,
+        }),
+    }).pipe(Effect.andThen(waitForPassword), Effect.ensuring(cleanup));
+  });
+
+  return DesktopSshPasswordPrompts.of({
+    request,
+    resolve,
+    cancelPending,
+  });
+});
+
+export const layer = (options: LayerOptions = {}) =>
+  Layer.effect(DesktopSshPasswordPrompts, make(options));
diff --git a/apps/desktop/src/ssh/DesktopSshRemoteApi.test.ts b/apps/desktop/src/ssh/DesktopSshRemoteApi.test.ts
new file mode 100644
index 00000000000..8b6798d38cb
--- /dev/null
+++ b/apps/desktop/src/ssh/DesktopSshRemoteApi.test.ts
@@ -0,0 +1,79 @@
+import { assert, describe, it } from "@effect/vitest";
+import { SshHttpBridgeError } from "@t3tools/ssh/errors";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+
+import * as DesktopSshRemoteApi from "./DesktopSshRemoteApi.ts";
+
+function jsonResponse(request: HttpClientRequest.HttpClientRequest, body: unknown, status = 200) {
+  return HttpClientResponse.fromWeb(
+    request,
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { "content-type": "application/json" },
+    }),
+  );
+}
+
+function makeLayer(
+  handler: (
+    request: HttpClientRequest.HttpClientRequest,
+  ) => Effect.Effect<HttpClientResponse.HttpClientResponse>,
+) {
+  return DesktopSshRemoteApi.layer.pipe(
+    Layer.provide(
+      Layer.succeed(
+        HttpClient.HttpClient,
+        HttpClient.make((request) => handler(request)),
+      ),
+    ),
+  );
+}
+
+describe("DesktopSshRemoteApi", () => {
+  it.effect("fetches and decodes the remote environment descriptor", () => {
+    const requestUrls: string[] = [];
+    const layer = makeLayer((request) =>
+      Effect.sync(() => {
+        requestUrls.push(request.url);
+        return jsonResponse(request, {
+          environmentId: "remote-env",
+          label: "Remote Devbox",
+          platform: { os: "linux", arch: "x64" },
+          serverVersion: "1.2.3",
+          capabilities: { repositoryIdentity: true },
+        });
+      }),
+    );
+
+    return Effect.gen(function* () {
+      const remoteApi = yield* DesktopSshRemoteApi.DesktopSshRemoteApi;
+      const descriptor = yield* remoteApi.fetchEnvironmentDescriptor({
+        httpBaseUrl: "http://127.0.0.1:41773/",
+      });
+
+      assert.equal(descriptor.label, "Remote Devbox");
+      assert.deepEqual(requestUrls, ["http://127.0.0.1:41773/.well-known/t3/environment"]);
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.effect("wraps schema decode failures in a typed remote api error", () => {
+    const layer = makeLayer((request) =>
+      Effect.succeed(jsonResponse(request, { environmentId: "remote-env" })),
+    );
+
+    return Effect.gen(function* () {
+      const remoteApi = yield* DesktopSshRemoteApi.DesktopSshRemoteApi;
+      const error = yield* remoteApi
+        .fetchEnvironmentDescriptor({
+          httpBaseUrl: "http://127.0.0.1:41773/",
+        })
+        .pipe(Effect.flip);
+
+      assert.instanceOf(error, DesktopSshRemoteApi.DesktopSshRemoteApiError);
+      assert.equal(error.operation, "fetch-environment-descriptor");
+      assert.equal(error.cause instanceof SshHttpBridgeError, false);
+    }).pipe(Effect.provide(layer));
+  });
+});
diff --git a/apps/desktop/src/ssh/DesktopSshRemoteApi.ts b/apps/desktop/src/ssh/DesktopSshRemoteApi.ts
new file mode 100644
index 00000000000..60184d098a6
--- /dev/null
+++ b/apps/desktop/src/ssh/DesktopSshRemoteApi.ts
@@ -0,0 +1,124 @@
+import {
+  AuthBearerBootstrapResult,
+  AuthSessionState,
+  AuthWebSocketTokenResult,
+  type AuthBearerBootstrapResult as AuthBearerBootstrapResultType,
+  type AuthSessionState as AuthSessionStateType,
+  type AuthWebSocketTokenResult as AuthWebSocketTokenResultType,
+  ExecutionEnvironmentDescriptor,
+  type ExecutionEnvironmentDescriptor as ExecutionEnvironmentDescriptorType,
+} from "@t3tools/contracts";
+import { SshHttpBridgeError } from "@t3tools/ssh/errors";
+import { fetchLoopbackSshJson } from "@t3tools/ssh/tunnel";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { HttpClient } from "effect/unstable/http";
+
+export type DesktopSshRemoteApiOperation =
+  | "fetch-environment-descriptor"
+  | "bootstrap-bearer-session"
+  | "fetch-session-state"
+  | "issue-websocket-token";
+
+export class DesktopSshRemoteApiError extends Data.TaggedError("DesktopSshRemoteApiError")<{
+  readonly operation: DesktopSshRemoteApiOperation;
+  readonly cause: SshHttpBridgeError | Schema.SchemaError;
+}> {
+  override get message() {
+    return `SSH remote API request failed during ${this.operation}.`;
+  }
+}
+
+export interface DesktopSshRemoteApiShape {
+  readonly fetchEnvironmentDescriptor: (input: {
+    readonly httpBaseUrl: string;
+  }) => Effect.Effect<ExecutionEnvironmentDescriptorType, DesktopSshRemoteApiError>;
+  readonly bootstrapBearerSession: (input: {
+    readonly httpBaseUrl: string;
+    readonly credential: string;
+  }) => Effect.Effect<AuthBearerBootstrapResultType, DesktopSshRemoteApiError>;
+  readonly fetchSessionState: (input: {
+    readonly httpBaseUrl: string;
+    readonly bearerToken: string;
+  }) => Effect.Effect<AuthSessionStateType, DesktopSshRemoteApiError>;
+  readonly issueWebSocketToken: (input: {
+    readonly httpBaseUrl: string;
+    readonly bearerToken: string;
+  }) => Effect.Effect<AuthWebSocketTokenResultType, DesktopSshRemoteApiError>;
+}
+
+export class DesktopSshRemoteApi extends Context.Service<
+  DesktopSshRemoteApi,
+  DesktopSshRemoteApiShape
+>()("t3/desktop/SshRemoteApi") {}
+
+const decodeExecutionEnvironmentDescriptor = Schema.decodeUnknownEffect(
+  ExecutionEnvironmentDescriptor,
+);
+const decodeAuthBearerBootstrapResult = Schema.decodeUnknownEffect(AuthBearerBootstrapResult);
+const decodeAuthSessionState = Schema.decodeUnknownEffect(AuthSessionState);
+const decodeAuthWebSocketTokenResult = Schema.decodeUnknownEffect(AuthWebSocketTokenResult);
+
+const mapError =
+  (operation: DesktopSshRemoteApiOperation) =>
+  (cause: SshHttpBridgeError | Schema.SchemaError): DesktopSshRemoteApiError =>
+    new DesktopSshRemoteApiError({ operation, cause });
+
+const make = Effect.gen(function* () {
+  const httpClient = yield* HttpClient.HttpClient;
+  const provideHttpClient = <A, E>(effect: Effect.Effect<A, E, HttpClient.HttpClient>) =>
+    effect.pipe(Effect.provideService(HttpClient.HttpClient, httpClient));
+
+  return DesktopSshRemoteApi.of({
+    fetchEnvironmentDescriptor: ({ httpBaseUrl }) =>
+      fetchLoopbackSshJson<unknown>({
+        httpBaseUrl,
+        pathname: "/.well-known/t3/environment",
+      }).pipe(
+        Effect.flatMap(decodeExecutionEnvironmentDescriptor),
+        Effect.mapError(mapError("fetch-environment-descriptor")),
+        provideHttpClient,
+        Effect.withSpan("desktop.sshRemoteApi.fetchEnvironmentDescriptor"),
+      ),
+    bootstrapBearerSession: ({ httpBaseUrl, credential }) =>
+      fetchLoopbackSshJson<unknown>({
+        httpBaseUrl,
+        pathname: "/api/auth/bootstrap/bearer",
+        method: "POST",
+        body: { credential },
+      }).pipe(
+        Effect.flatMap(decodeAuthBearerBootstrapResult),
+        Effect.mapError(mapError("bootstrap-bearer-session")),
+        provideHttpClient,
+        Effect.withSpan("desktop.sshRemoteApi.bootstrapBearerSession"),
+      ),
+    fetchSessionState: ({ httpBaseUrl, bearerToken }) =>
+      fetchLoopbackSshJson<unknown>({
+        httpBaseUrl,
+        pathname: "/api/auth/session",
+        bearerToken,
+      }).pipe(
+        Effect.flatMap(decodeAuthSessionState),
+        Effect.mapError(mapError("fetch-session-state")),
+        provideHttpClient,
+        Effect.withSpan("desktop.sshRemoteApi.fetchSessionState"),
+      ),
+    issueWebSocketToken: ({ httpBaseUrl, bearerToken }) =>
+      fetchLoopbackSshJson<unknown>({
+        httpBaseUrl,
+        pathname: "/api/auth/ws-token",
+        method: "POST",
+        bearerToken,
+      }).pipe(
+        Effect.flatMap(decodeAuthWebSocketTokenResult),
+        Effect.mapError(mapError("issue-websocket-token")),
+        provideHttpClient,
+        Effect.withSpan("desktop.sshRemoteApi.issueWebSocketToken"),
+      ),
+  });
+});
+
+export const layer = Layer.effect(DesktopSshRemoteApi, make);
diff --git a/apps/desktop/src/syncShellEnvironment.test.ts b/apps/desktop/src/syncShellEnvironment.test.ts
deleted file mode 100644
index cda78a20b2c..00000000000
--- a/apps/desktop/src/syncShellEnvironment.test.ts
+++ /dev/null
@@ -1,105 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { syncShellEnvironment } from "./syncShellEnvironment";
-
-describe("syncShellEnvironment", () => {
-  it("hydrates PATH and missing SSH_AUTH_SOCK from the login shell on macOS", () => {
-    const env: NodeJS.ProcessEnv = {
-      SHELL: "/bin/zsh",
-      PATH: "/usr/bin",
-    };
-    const readEnvironment = vi.fn(() => ({
-      PATH: "/opt/homebrew/bin:/usr/bin",
-      SSH_AUTH_SOCK: "/tmp/secretive.sock",
-    }));
-
-    syncShellEnvironment(env, {
-      platform: "darwin",
-      readEnvironment,
-    });
-
-    expect(readEnvironment).toHaveBeenCalledWith("/bin/zsh", ["PATH", "SSH_AUTH_SOCK"]);
-    expect(env.PATH).toBe("/opt/homebrew/bin:/usr/bin");
-    expect(env.SSH_AUTH_SOCK).toBe("/tmp/secretive.sock");
-  });
-
-  it("preserves an inherited SSH_AUTH_SOCK value", () => {
-    const env: NodeJS.ProcessEnv = {
-      SHELL: "/bin/zsh",
-      PATH: "/usr/bin",
-      SSH_AUTH_SOCK: "/tmp/inherited.sock",
-    };
-    const readEnvironment = vi.fn(() => ({
-      PATH: "/opt/homebrew/bin:/usr/bin",
-      SSH_AUTH_SOCK: "/tmp/login-shell.sock",
-    }));
-
-    syncShellEnvironment(env, {
-      platform: "darwin",
-      readEnvironment,
-    });
-
-    expect(env.PATH).toBe("/opt/homebrew/bin:/usr/bin");
-    expect(env.SSH_AUTH_SOCK).toBe("/tmp/inherited.sock");
-  });
-
-  it("preserves inherited values when the login shell omits them", () => {
-    const env: NodeJS.ProcessEnv = {
-      SHELL: "/bin/zsh",
-      PATH: "/usr/bin",
-      SSH_AUTH_SOCK: "/tmp/inherited.sock",
-    };
-    const readEnvironment = vi.fn(() => ({
-      PATH: "/opt/homebrew/bin:/usr/bin",
-    }));
-
-    syncShellEnvironment(env, {
-      platform: "darwin",
-      readEnvironment,
-    });
-
-    expect(env.PATH).toBe("/opt/homebrew/bin:/usr/bin");
-    expect(env.SSH_AUTH_SOCK).toBe("/tmp/inherited.sock");
-  });
-
-  it("hydrates PATH and missing SSH_AUTH_SOCK from the login shell on linux", () => {
-    const env: NodeJS.ProcessEnv = {
-      SHELL: "/bin/zsh",
-      PATH: "/usr/bin",
-    };
-    const readEnvironment = vi.fn(() => ({
-      PATH: "/home/linuxbrew/.linuxbrew/bin:/usr/bin",
-      SSH_AUTH_SOCK: "/tmp/secretive.sock",
-    }));
-
-    syncShellEnvironment(env, {
-      platform: "linux",
-      readEnvironment,
-    });
-
-    expect(readEnvironment).toHaveBeenCalledWith("/bin/zsh", ["PATH", "SSH_AUTH_SOCK"]);
-    expect(env.PATH).toBe("/home/linuxbrew/.linuxbrew/bin:/usr/bin");
-    expect(env.SSH_AUTH_SOCK).toBe("/tmp/secretive.sock");
-  });
-
-  it("does nothing outside macOS and linux", () => {
-    const env: NodeJS.ProcessEnv = {
-      SHELL: "C:/Program Files/Git/bin/bash.exe",
-      PATH: "C:\\Windows\\System32",
-      SSH_AUTH_SOCK: "/tmp/inherited.sock",
-    };
-    const readEnvironment = vi.fn(() => ({
-      PATH: "/usr/local/bin:/usr/bin",
-      SSH_AUTH_SOCK: "/tmp/secretive.sock",
-    }));
-
-    syncShellEnvironment(env, {
-      platform: "win32",
-      readEnvironment,
-    });
-
-    expect(readEnvironment).not.toHaveBeenCalled();
-    expect(env.PATH).toBe("C:\\Windows\\System32");
-    expect(env.SSH_AUTH_SOCK).toBe("/tmp/inherited.sock");
-  });
-});
diff --git a/apps/desktop/src/syncShellEnvironment.ts b/apps/desktop/src/syncShellEnvironment.ts
deleted file mode 100644
index 13036149b8d..00000000000
--- a/apps/desktop/src/syncShellEnvironment.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import {
-  readEnvironmentFromLoginShell,
-  resolveLoginShell,
-  ShellEnvironmentReader,
-} from "@t3tools/shared/shell";
-
-export function syncShellEnvironment(
-  env: NodeJS.ProcessEnv = process.env,
-  options: {
-    platform?: NodeJS.Platform;
-    readEnvironment?: ShellEnvironmentReader;
-  } = {},
-): void {
-  const platform = options.platform ?? process.platform;
-  if (platform !== "darwin" && platform !== "linux") return;
-
-  try {
-    const shell = resolveLoginShell(platform, env.SHELL);
-    if (!shell) return;
-
-    const shellEnvironment = (options.readEnvironment ?? readEnvironmentFromLoginShell)(shell, [
-      "PATH",
-      "SSH_AUTH_SOCK",
-    ]);
-
-    if (shellEnvironment.PATH) {
-      env.PATH = shellEnvironment.PATH;
-    }
-
-    if (!env.SSH_AUTH_SOCK && shellEnvironment.SSH_AUTH_SOCK) {
-      env.SSH_AUTH_SOCK = shellEnvironment.SSH_AUTH_SOCK;
-    }
-  } catch {
-    // Keep inherited environment if shell lookup fails.
-  }
-}
diff --git a/apps/desktop/src/updateState.test.ts b/apps/desktop/src/updateState.test.ts
deleted file mode 100644
index 8db92e1915f..00000000000
--- a/apps/desktop/src/updateState.test.ts
+++ /dev/null
@@ -1,174 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { DesktopUpdateState } from "@t3tools/contracts";
-
-import {
-  getCanRetryAfterDownloadFailure,
-  getAutoUpdateDisabledReason,
-  nextStatusAfterDownloadFailure,
-  shouldBroadcastDownloadProgress,
-} from "./updateState";
-
-const baseState: DesktopUpdateState = {
-  enabled: true,
-  status: "idle",
-  currentVersion: "1.0.0",
-  hostArch: "x64",
-  appArch: "x64",
-  runningUnderArm64Translation: false,
-  availableVersion: null,
-  downloadedVersion: null,
-  downloadPercent: null,
-  checkedAt: null,
-  message: null,
-  errorContext: null,
-  canRetry: false,
-};
-
-describe("shouldBroadcastDownloadProgress", () => {
-  it("broadcasts the first downloading progress update", () => {
-    expect(
-      shouldBroadcastDownloadProgress(
-        { ...baseState, status: "downloading", downloadPercent: null },
-        1,
-      ),
-    ).toBe(true);
-  });
-
-  it("skips progress updates within the same 10% bucket", () => {
-    expect(
-      shouldBroadcastDownloadProgress(
-        { ...baseState, status: "downloading", downloadPercent: 11.2 },
-        18.7,
-      ),
-    ).toBe(false);
-  });
-
-  it("broadcasts progress updates when a new 10% bucket is reached", () => {
-    expect(
-      shouldBroadcastDownloadProgress(
-        { ...baseState, status: "downloading", downloadPercent: 19.9 },
-        20.1,
-      ),
-    ).toBe(true);
-  });
-
-  it("broadcasts progress updates when a retry resets the download percentage", () => {
-    expect(
-      shouldBroadcastDownloadProgress(
-        { ...baseState, status: "downloading", downloadPercent: 50.4 },
-        0.2,
-      ),
-    ).toBe(true);
-  });
-});
-
-describe("getAutoUpdateDisabledReason", () => {
-  it("reports development builds as disabled", () => {
-    expect(
-      getAutoUpdateDisabledReason({
-        isDevelopment: true,
-        isPackaged: false,
-        platform: "darwin",
-        appImage: undefined,
-        disabledByEnv: false,
-        hasUpdateFeedConfig: true,
-      }),
-    ).toContain("packaged production builds");
-  });
-
-  it("reports packaged local builds without an update feed as disabled", () => {
-    expect(
-      getAutoUpdateDisabledReason({
-        isDevelopment: false,
-        isPackaged: true,
-        platform: "darwin",
-        appImage: undefined,
-        disabledByEnv: false,
-        hasUpdateFeedConfig: false,
-      }),
-    ).toContain("no update feed");
-  });
-
-  it("allows packaged builds with an update feed", () => {
-    expect(
-      getAutoUpdateDisabledReason({
-        isDevelopment: false,
-        isPackaged: true,
-        platform: "darwin",
-        appImage: undefined,
-        disabledByEnv: false,
-        hasUpdateFeedConfig: true,
-      }),
-    ).toBeNull();
-  });
-
-  it("reports env-disabled auto updates", () => {
-    expect(
-      getAutoUpdateDisabledReason({
-        isDevelopment: false,
-        isPackaged: true,
-        platform: "darwin",
-        appImage: undefined,
-        disabledByEnv: true,
-        hasUpdateFeedConfig: true,
-      }),
-    ).toContain("T3CODE_DISABLE_AUTO_UPDATE");
-  });
-
-  it("reports linux non-AppImage builds as disabled", () => {
-    expect(
-      getAutoUpdateDisabledReason({
-        isDevelopment: false,
-        isPackaged: true,
-        platform: "linux",
-        appImage: undefined,
-        disabledByEnv: false,
-        hasUpdateFeedConfig: true,
-      }),
-    ).toContain("AppImage");
-  });
-});
-
-describe("nextStatusAfterDownloadFailure", () => {
-  it("returns available when an update version is still known", () => {
-    expect(
-      nextStatusAfterDownloadFailure({
-        ...baseState,
-        status: "downloading",
-        availableVersion: "1.1.0",
-      }),
-    ).toBe("available");
-  });
-
-  it("returns error when no update version can be retried", () => {
-    expect(
-      nextStatusAfterDownloadFailure({
-        ...baseState,
-        status: "downloading",
-        availableVersion: null,
-      }),
-    ).toBe("error");
-  });
-});
-
-describe("getCanRetryAfterDownloadFailure", () => {
-  it("returns true when an available version is still present", () => {
-    expect(
-      getCanRetryAfterDownloadFailure({
-        ...baseState,
-        status: "downloading",
-        availableVersion: "1.1.0",
-      }),
-    ).toBe(true);
-  });
-
-  it("returns false when no version is available to retry", () => {
-    expect(
-      getCanRetryAfterDownloadFailure({
-        ...baseState,
-        status: "downloading",
-        availableVersion: null,
-      }),
-    ).toBe(false);
-  });
-});
diff --git a/apps/desktop/src/updateState.ts b/apps/desktop/src/updateState.ts
deleted file mode 100644
index 928bb408865..00000000000
--- a/apps/desktop/src/updateState.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-import type { DesktopUpdateState } from "@t3tools/contracts";
-
-export function shouldBroadcastDownloadProgress(
-  currentState: DesktopUpdateState,
-  nextPercent: number,
-): boolean {
-  if (currentState.status !== "downloading") {
-    return true;
-  }
-
-  const currentPercent = currentState.downloadPercent;
-  if (currentPercent === null) {
-    return true;
-  }
-
-  const previousStep = Math.floor(currentPercent / 10);
-  const nextStep = Math.floor(nextPercent / 10);
-  return nextStep !== previousStep || nextPercent === 100;
-}
-
-export function nextStatusAfterDownloadFailure(
-  currentState: DesktopUpdateState,
-): DesktopUpdateState["status"] {
-  return currentState.availableVersion ? "available" : "error";
-}
-
-export function getCanRetryAfterDownloadFailure(currentState: DesktopUpdateState): boolean {
-  return currentState.availableVersion !== null;
-}
-
-export function getAutoUpdateDisabledReason(args: {
-  isDevelopment: boolean;
-  isPackaged: boolean;
-  platform: NodeJS.Platform;
-  appImage?: string | undefined;
-  disabledByEnv: boolean;
-  hasUpdateFeedConfig: boolean;
-}): string | null {
-  if (!args.hasUpdateFeedConfig) {
-    return "Automatic updates are not available because no update feed is configured.";
-  }
-  if (args.isDevelopment || !args.isPackaged) {
-    return "Automatic updates are only available in packaged production builds.";
-  }
-  if (args.disabledByEnv) {
-    return "Automatic updates are disabled by the T3CODE_DISABLE_AUTO_UPDATE setting.";
-  }
-  if (args.platform === "linux" && !args.appImage) {
-    return "Automatic updates on Linux require running the AppImage build.";
-  }
-  return null;
-}
diff --git a/apps/desktop/src/updates/DesktopUpdates.test.ts b/apps/desktop/src/updates/DesktopUpdates.test.ts
new file mode 100644
index 00000000000..34d18f11a77
--- /dev/null
+++ b/apps/desktop/src/updates/DesktopUpdates.test.ts
@@ -0,0 +1,295 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import type { DesktopUpdateState } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as TestClock from "effect/testing/TestClock";
+
+import * as DesktopBackendManager from "../backend/DesktopBackendManager.ts";
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as ElectronUpdater from "../electron/ElectronUpdater.ts";
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
+import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
+import * as DesktopState from "../app/DesktopState.ts";
+import * as DesktopUpdates from "./DesktopUpdates.ts";
+
+interface UpdatesHarnessOptions {
+  readonly checkForUpdates?: Effect.Effect<
+    void,
+    ElectronUpdater.ElectronUpdaterCheckForUpdatesError
+  >;
+  readonly env?: Record<string, string | undefined>;
+}
+
+const flushCallbacks = Effect.yieldNow;
+
+function makeHarness(options: UpdatesHarnessOptions = {}) {
+  let checkCount = 0;
+  let allowDowngrade = false;
+  const feedUrls: ElectronUpdater.ElectronUpdaterFeedUrl[] = [];
+  const listeners = new Map<string, Set<(...args: readonly unknown[]) => void>>();
+  const sentStates: DesktopUpdateState[] = [];
+
+  const addListener = (eventName: string, listener: (...args: readonly unknown[]) => void) => {
+    const eventListeners = listeners.get(eventName) ?? new Set();
+    eventListeners.add(listener);
+    listeners.set(eventName, eventListeners);
+  };
+
+  const removeListener = (eventName: string, listener: (...args: readonly unknown[]) => void) => {
+    const eventListeners = listeners.get(eventName);
+    if (!eventListeners) {
+      return;
+    }
+    eventListeners.delete(listener);
+    if (eventListeners.size === 0) {
+      listeners.delete(eventName);
+    }
+  };
+
+  const updaterLayer = Layer.succeed(ElectronUpdater.ElectronUpdater, {
+    setFeedURL: (options) =>
+      Effect.sync(() => {
+        feedUrls.push(options);
+      }),
+    setAutoDownload: () => Effect.void,
+    setAutoInstallOnAppQuit: () => Effect.void,
+    setChannel: () => Effect.void,
+    setAllowPrerelease: () => Effect.void,
+    allowDowngrade: Effect.sync(() => allowDowngrade),
+    setAllowDowngrade: (value) =>
+      Effect.sync(() => {
+        allowDowngrade = value;
+      }),
+    setDisableDifferentialDownload: () => Effect.void,
+    checkForUpdates: Effect.sync(() => {
+      checkCount += 1;
+    }).pipe(Effect.andThen(options.checkForUpdates ?? Effect.void)),
+    downloadUpdate: Effect.void,
+    quitAndInstall: () => Effect.void,
+    on: (eventName, listener) =>
+      Effect.acquireRelease(
+        Effect.sync(() => {
+          addListener(eventName, listener as unknown as (...args: readonly unknown[]) => void);
+        }),
+        () =>
+          Effect.sync(() => {
+            removeListener(eventName, listener as unknown as (...args: readonly unknown[]) => void);
+          }),
+      ).pipe(Effect.asVoid),
+  } satisfies ElectronUpdater.ElectronUpdaterShape);
+
+  const windowLayer = Layer.succeed(ElectronWindow.ElectronWindow, {
+    create: () => Effect.die("unexpected BrowserWindow creation"),
+    main: Effect.succeed(Option.none()),
+    currentMainOrFirst: Effect.succeed(Option.none()),
+    focusedMainOrFirst: Effect.succeed(Option.none()),
+    setMain: () => Effect.void,
+    clearMain: () => Effect.void,
+    reveal: () => Effect.void,
+    sendAll: (_channel, state) =>
+      Effect.sync(() => {
+        sentStates.push(state as DesktopUpdateState);
+      }),
+    destroyAll: Effect.void,
+    syncAllAppearance: () => Effect.void,
+  } satisfies ElectronWindow.ElectronWindowShape);
+
+  const backendLayer = Layer.succeed(DesktopBackendManager.DesktopBackendManager, {
+    start: Effect.void,
+    stop: () => Effect.void,
+    currentConfig: Effect.succeed(Option.none()),
+    snapshot: Effect.succeed({
+      desiredRunning: false,
+      ready: false,
+      activePid: Option.none(),
+      restartAttempt: 0,
+      restartScheduled: false,
+    }),
+  });
+
+  const environmentLayer = DesktopEnvironment.layer({
+    dirname: "/repo/apps/desktop/src",
+    homeDirectory: `/tmp/t3-desktop-updates-home-${process.pid}`,
+    platform: "darwin",
+    processArch: "x64",
+    appVersion: "1.2.3",
+    appPath: "/repo",
+    isPackaged: true,
+    resourcesPath: "/missing/resources",
+    runningUnderArm64Translation: false,
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        DesktopConfig.layerTest({
+          T3CODE_HOME: `/tmp/t3-desktop-updates-test-${process.pid}`,
+          T3CODE_DESKTOP_MOCK_UPDATES: "true",
+          T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT: "4141",
+          ...options.env,
+        }),
+      ),
+    ),
+  );
+
+  const layer = DesktopUpdates.layer.pipe(
+    Layer.provideMerge(updaterLayer),
+    Layer.provideMerge(windowLayer),
+    Layer.provideMerge(backendLayer),
+    Layer.provideMerge(DesktopState.layer),
+    Layer.provideMerge(DesktopAppSettings.layer),
+    Layer.provideMerge(
+      DesktopConfig.layerTest({
+        T3CODE_HOME: `/tmp/t3-desktop-updates-test-${process.pid}`,
+        T3CODE_DESKTOP_MOCK_UPDATES: "true",
+        T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT: "4141",
+        ...options.env,
+      }),
+    ),
+    Layer.provideMerge(environmentLayer),
+    Layer.provideMerge(NodeServices.layer),
+  );
+
+  return {
+    layer,
+    checkCount: () => checkCount,
+    feedUrls: () => feedUrls,
+    listenerCount: () =>
+      Array.from(listeners.values()).reduce(
+        (total, eventListeners) => total + eventListeners.size,
+        0,
+      ),
+    sentStates,
+    emit: (eventName: string, payload?: unknown) => {
+      for (const listener of listeners.get(eventName) ?? []) {
+        listener(payload);
+      }
+    },
+  };
+}
+
+describe("DesktopUpdates", () => {
+  it.effect("configures the updater and runs startup checks on the test clock", () => {
+    const harness = makeHarness();
+
+    return Effect.gen(function* () {
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const updates = yield* DesktopUpdates.DesktopUpdates;
+          yield* updates.configure;
+
+          const state = yield* updates.getState;
+          assert.equal(state.enabled, true);
+          assert.equal(state.status, "idle");
+          assert.deepEqual(harness.feedUrls(), [
+            { provider: "generic", url: "http://localhost:4141" },
+          ]);
+          assert.equal(harness.listenerCount(), 6);
+          assert.equal(harness.checkCount(), 0);
+
+          yield* TestClock.adjust(Duration.millis(15_000));
+          assert.equal(harness.checkCount(), 1);
+        }),
+      );
+
+      assert.equal(harness.listenerCount(), 0);
+    }).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
+  });
+
+  it.effect("updates and broadcasts state from updater events", () => {
+    const harness = makeHarness();
+
+    return Effect.scoped(
+      Effect.gen(function* () {
+        const updates = yield* DesktopUpdates.DesktopUpdates;
+        yield* updates.configure;
+
+        harness.emit("update-available", { version: "1.2.4" });
+        yield* flushCallbacks;
+
+        const state = yield* updates.getState;
+        assert.equal(state.status, "available");
+        assert.equal(state.availableVersion, "1.2.4");
+        assert.isNotNull(state.checkedAt);
+        assert.equal(harness.sentStates.at(-1)?.status, "available");
+      }),
+    ).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
+  });
+
+  it.effect("persists channel changes through the settings service", () => {
+    const harness = makeHarness();
+
+    return Effect.scoped(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        const updates = yield* DesktopUpdates.DesktopUpdates;
+        yield* updates.configure;
+
+        const state = yield* updates.setChannel("nightly");
+        const persistedSettings = yield* settings.get;
+
+        assert.equal(state.channel, "nightly");
+        assert.equal(persistedSettings.updateChannel, "nightly");
+        assert.equal(persistedSettings.updateChannelConfiguredByUser, true);
+      }),
+    ).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
+  });
+
+  it.effect("does not persist an unchanged update channel as a user preference", () => {
+    const harness = makeHarness();
+
+    return Effect.scoped(
+      Effect.gen(function* () {
+        const settings = yield* DesktopAppSettings.DesktopAppSettings;
+        const updates = yield* DesktopUpdates.DesktopUpdates;
+        yield* updates.configure;
+
+        const state = yield* updates.setChannel("latest");
+        const persistedSettings = yield* settings.get;
+
+        assert.equal(state.channel, "latest");
+        assert.equal(persistedSettings.updateChannel, "latest");
+        assert.equal(persistedSettings.updateChannelConfiguredByUser, false);
+      }),
+    ).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
+  });
+
+  it.effect("fails channel changes with a typed error while a check is in progress", () =>
+    Effect.gen(function* () {
+      const checkStarted = yield* Deferred.make<void>();
+      const releaseCheck = yield* Deferred.make<void>();
+      const harness = makeHarness({
+        checkForUpdates: Deferred.succeed(checkStarted, undefined).pipe(
+          Effect.andThen(Deferred.await(releaseCheck)),
+        ),
+      });
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const updates = yield* DesktopUpdates.DesktopUpdates;
+          yield* updates.configure;
+
+          const checkFiber = yield* updates.check("manual").pipe(Effect.forkScoped);
+          yield* Deferred.await(checkStarted);
+
+          const exit = yield* Effect.exit(updates.setChannel("nightly"));
+          assert.equal(exit._tag, "Failure");
+          if (exit._tag === "Failure") {
+            const error = Cause.squash(exit.cause);
+            assert.instanceOf(error, DesktopUpdates.DesktopUpdateActionInProgressError);
+            assert.equal(error.action, "check");
+          }
+
+          yield* Deferred.succeed(releaseCheck, undefined);
+          yield* Fiber.join(checkFiber);
+        }),
+      ).pipe(Effect.provide(Layer.merge(TestClock.layer(), harness.layer)));
+    }),
+  );
+});
diff --git a/apps/desktop/src/updates/DesktopUpdates.ts b/apps/desktop/src/updates/DesktopUpdates.ts
new file mode 100644
index 00000000000..8c0acd2e8a6
--- /dev/null
+++ b/apps/desktop/src/updates/DesktopUpdates.ts
@@ -0,0 +1,667 @@
+import type {
+  DesktopRuntimeInfo,
+  DesktopUpdateActionResult,
+  DesktopUpdateChannel,
+  DesktopUpdateCheckResult,
+  DesktopUpdateState,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+
+import * as DesktopBackendManager from "../backend/DesktopBackendManager.ts";
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as DesktopState from "../app/DesktopState.ts";
+import * as ElectronUpdater from "../electron/ElectronUpdater.ts";
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
+import * as IpcChannels from "../ipc/channels.ts";
+import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
+import { resolveDefaultDesktopUpdateChannel } from "./updateChannels.ts";
+import {
+  createInitialDesktopUpdateState,
+  reduceDesktopUpdateStateOnCheckFailure,
+  reduceDesktopUpdateStateOnCheckStart,
+  reduceDesktopUpdateStateOnDownloadComplete,
+  reduceDesktopUpdateStateOnDownloadFailure,
+  reduceDesktopUpdateStateOnDownloadProgress,
+  reduceDesktopUpdateStateOnDownloadStart,
+  reduceDesktopUpdateStateOnInstallFailure,
+  reduceDesktopUpdateStateOnNoUpdate,
+  reduceDesktopUpdateStateOnUpdateAvailable,
+} from "./updateMachine.ts";
+
+const AUTO_UPDATE_STARTUP_DELAY = "15 seconds";
+const AUTO_UPDATE_POLL_INTERVAL = "4 minutes";
+
+const AppUpdateYmlConfig = Schema.Record(Schema.String, Schema.String);
+type AppUpdateYmlConfig = typeof AppUpdateYmlConfig.Type;
+
+const UpdateInfo = Schema.Struct({
+  version: Schema.String,
+});
+
+const DownloadProgressInfo = Schema.Struct({
+  percent: Schema.Number,
+});
+const decodeAppUpdateYmlConfig = Schema.decodeUnknownEffect(AppUpdateYmlConfig);
+const decodeUpdateInfo = Schema.decodeUnknownEffect(UpdateInfo);
+const decodeDownloadProgressInfo = Schema.decodeUnknownEffect(DownloadProgressInfo);
+
+const currentIsoTimestamp = DateTime.now.pipe(Effect.map(DateTime.formatIso));
+
+export class DesktopUpdateActionInProgressError extends Data.TaggedError(
+  "DesktopUpdateActionInProgressError",
+)<{
+  readonly action: "check" | "download" | "install";
+}> {
+  override get message() {
+    return `Cannot change update tracks while an update ${this.action} action is in progress.`;
+  }
+}
+
+export class DesktopUpdatePersistenceError extends Data.TaggedError(
+  "DesktopUpdatePersistenceError",
+)<{
+  readonly cause: DesktopAppSettings.DesktopSettingsWriteError;
+}> {
+  override get message() {
+    return "Failed to persist desktop update settings.";
+  }
+}
+
+export type DesktopUpdateConfigureError = never;
+
+export type DesktopUpdateSetChannelError =
+  | DesktopUpdateActionInProgressError
+  | DesktopUpdatePersistenceError;
+
+export interface DesktopUpdatesShape {
+  readonly getState: Effect.Effect<DesktopUpdateState>;
+  readonly emitState: Effect.Effect<void>;
+  readonly disabledReason: Effect.Effect<Option.Option<string>>;
+  readonly configure: Effect.Effect<void, DesktopUpdateConfigureError, Scope.Scope>;
+  readonly setChannel: (
+    channel: DesktopUpdateChannel,
+  ) => Effect.Effect<DesktopUpdateState, DesktopUpdateSetChannelError>;
+  readonly check: (reason: string) => Effect.Effect<DesktopUpdateCheckResult>;
+  readonly download: Effect.Effect<DesktopUpdateActionResult>;
+  readonly install: Effect.Effect<DesktopUpdateActionResult>;
+}
+
+export class DesktopUpdates extends Context.Service<DesktopUpdates, DesktopUpdatesShape>()(
+  "t3/desktop/Updates",
+) {}
+
+const {
+  logInfo: logUpdaterInfo,
+  logWarning: logUpdaterWarning,
+  logError: logUpdaterError,
+} = DesktopObservability.makeComponentLogger("desktop-updater");
+
+function parseAppUpdateYml(raw: string): Effect.Effect<Option.Option<AppUpdateYmlConfig>> {
+  const entries: Record<string, string> = {};
+  for (const line of raw.split("\n")) {
+    const match = line.match(/^(\w+):\s*(.+)$/);
+    if (match?.[1] && match[2]) {
+      entries[match[1]] = match[2].trim();
+    }
+  }
+
+  return decodeAppUpdateYmlConfig(entries).pipe(
+    Effect.map((config) => (config.provider ? Option.some(config) : Option.none())),
+    Effect.catch(() => Effect.succeed(Option.none<AppUpdateYmlConfig>())),
+  );
+}
+
+function createBaseUpdateState(
+  channel: DesktopUpdateChannel,
+  enabled: boolean,
+  environment: DesktopEnvironment.DesktopEnvironmentShape,
+): DesktopUpdateState {
+  return {
+    ...createInitialDesktopUpdateState(environment.appVersion, environment.runtimeInfo, channel),
+    enabled,
+    status: enabled ? "idle" : "disabled",
+  };
+}
+
+function getCanRetryFromState(state: DesktopUpdateState): boolean {
+  return state.availableVersion !== null || state.downloadedVersion !== null;
+}
+
+function shouldBroadcastDownloadProgress(
+  currentState: DesktopUpdateState,
+  nextPercent: number,
+): boolean {
+  if (currentState.status !== "downloading") {
+    return true;
+  }
+
+  const currentPercent = currentState.downloadPercent;
+  if (currentPercent === null) {
+    return true;
+  }
+
+  const previousStep = Math.floor(currentPercent / 10);
+  const nextStep = Math.floor(nextPercent / 10);
+  return nextStep !== previousStep || nextPercent === 100;
+}
+
+function getAutoUpdateDisabledReason(args: {
+  isDevelopment: boolean;
+  isPackaged: boolean;
+  platform: NodeJS.Platform;
+  appImage?: string | undefined;
+  disabledByEnv: boolean;
+  hasUpdateFeedConfig: boolean;
+}): string | null {
+  if (!args.hasUpdateFeedConfig) {
+    return "Automatic updates are not available because no update feed is configured.";
+  }
+  if (args.isDevelopment || !args.isPackaged) {
+    return "Automatic updates are only available in packaged production builds.";
+  }
+  if (args.disabledByEnv) {
+    return "Automatic updates are disabled by the T3CODE_DISABLE_AUTO_UPDATE setting.";
+  }
+  if (args.platform === "linux" && !args.appImage) {
+    return "Automatic updates on Linux require running the AppImage build.";
+  }
+  return null;
+}
+
+function isArm64HostRunningIntelBuild(runtimeInfo: DesktopRuntimeInfo): boolean {
+  return runtimeInfo.hostArch === "arm64" && runtimeInfo.appArch === "x64";
+}
+
+const make = Effect.gen(function* () {
+  const config = yield* DesktopConfig.DesktopConfig;
+  const backendManager = yield* DesktopBackendManager.DesktopBackendManager;
+  const desktopState = yield* DesktopState.DesktopState;
+  const electronUpdater = yield* ElectronUpdater.ElectronUpdater;
+  const electronWindow = yield* ElectronWindow.ElectronWindow;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const desktopSettings = yield* DesktopAppSettings.DesktopAppSettings;
+
+  const appUpdateYmlConfigRef = yield* Ref.make<Option.Option<AppUpdateYmlConfig>>(Option.none());
+  const updateCheckInFlightRef = yield* Ref.make(false);
+  const updateDownloadInFlightRef = yield* Ref.make(false);
+  const updateInstallInFlightRef = yield* Ref.make(false);
+  const updaterConfiguredRef = yield* Ref.make(false);
+  const lastLoggedDownloadMilestoneRef = yield* Ref.make(-1);
+  const updateStateRef = yield* Ref.make<DesktopUpdateState>(
+    createInitialDesktopUpdateState(
+      environment.appVersion,
+      environment.runtimeInfo,
+      environment.defaultDesktopSettings.updateChannel,
+    ),
+  );
+
+  const emitState = Ref.get(updateStateRef).pipe(
+    Effect.flatMap((state) => electronWindow.sendAll(IpcChannels.UPDATE_STATE_CHANNEL, state)),
+  );
+
+  const setState = (state: DesktopUpdateState): Effect.Effect<void> =>
+    Ref.set(updateStateRef, state).pipe(Effect.andThen(emitState));
+
+  const updateState = (
+    f: (state: DesktopUpdateState) => DesktopUpdateState,
+  ): Effect.Effect<DesktopUpdateState> =>
+    Ref.get(updateStateRef).pipe(
+      Effect.flatMap((state) => {
+        const nextState = f(state);
+        return setState(nextState).pipe(Effect.as(nextState));
+      }),
+    );
+
+  const readAppUpdateYml = fileSystem.readFileString(environment.appUpdateYmlPath, "utf-8").pipe(
+    Effect.option,
+    Effect.flatMap(
+      Option.match({
+        onNone: () => Effect.succeed(Option.none<AppUpdateYmlConfig>()),
+        onSome: parseAppUpdateYml,
+      }),
+    ),
+  );
+
+  const hasUpdateFeedConfig = Ref.get(appUpdateYmlConfigRef).pipe(
+    Effect.map((appUpdateYmlConfig) => Option.isSome(appUpdateYmlConfig) || config.mockUpdates),
+  );
+
+  const resolveDisabledReason = Effect.gen(function* () {
+    const hasFeedConfig = yield* hasUpdateFeedConfig;
+    return Option.fromNullishOr(
+      getAutoUpdateDisabledReason({
+        isDevelopment: environment.isDevelopment,
+        isPackaged: environment.isPackaged,
+        platform: environment.platform,
+        appImage: Option.getOrUndefined(config.appImagePath),
+        disabledByEnv: config.disableAutoUpdate,
+        hasUpdateFeedConfig: hasFeedConfig,
+      }),
+    );
+  });
+
+  const resolveUpdaterErrorContext = Effect.gen(function* () {
+    if (yield* Ref.get(updateInstallInFlightRef)) return "install" as const;
+    if (yield* Ref.get(updateDownloadInFlightRef)) return "download" as const;
+    if (yield* Ref.get(updateCheckInFlightRef)) return "check" as const;
+    return (yield* Ref.get(updateStateRef)).errorContext;
+  });
+
+  const activeUpdateAction = Effect.gen(function* () {
+    if (yield* Ref.get(updateInstallInFlightRef)) return Option.some("install" as const);
+    if (yield* Ref.get(updateDownloadInFlightRef)) return Option.some("download" as const);
+    if (yield* Ref.get(updateCheckInFlightRef)) return Option.some("check" as const);
+    return Option.none<"check" | "download" | "install">();
+  });
+
+  const applyAutoUpdaterChannel = Effect.fn("desktop.updates.applyAutoUpdaterChannel")(function* (
+    channel: DesktopUpdateChannel,
+  ) {
+    yield* Effect.annotateCurrentSpan({ channel });
+    const allowsPrerelease = channel === "nightly";
+    yield* electronUpdater.setChannel(channel);
+    yield* electronUpdater.setAllowPrerelease(allowsPrerelease);
+    yield* electronUpdater.setAllowDowngrade(allowsPrerelease);
+    yield* logUpdaterInfo("using update channel", {
+      channel,
+      allowPrerelease: allowsPrerelease,
+      allowDowngrade: allowsPrerelease,
+    });
+  });
+
+  const shouldEnableAutoUpdates = resolveDisabledReason.pipe(Effect.map(Option.isNone));
+
+  const checkForUpdates = Effect.fn("desktop.updates.checkForUpdates")(function* (reason: string) {
+    yield* Effect.annotateCurrentSpan({ reason });
+    if (yield* Ref.get(desktopState.quitting)) return false;
+    if (!(yield* Ref.get(updaterConfiguredRef))) return false;
+    if (yield* Ref.get(updateCheckInFlightRef)) return false;
+
+    const state = yield* Ref.get(updateStateRef);
+    if (state.status === "downloading" || state.status === "downloaded") {
+      yield* logUpdaterInfo("skipping update check while update is active", {
+        reason,
+        status: state.status,
+      });
+      return false;
+    }
+
+    yield* Ref.set(updateCheckInFlightRef, true);
+    const checkedAt = yield* currentIsoTimestamp;
+    yield* setState(reduceDesktopUpdateStateOnCheckStart(state, checkedAt));
+    yield* logUpdaterInfo("checking for updates", { reason });
+
+    return yield* electronUpdater.checkForUpdates.pipe(
+      Effect.as(true),
+      Effect.catch(
+        Effect.fn("desktop.updates.handleCheckForUpdatesFailure")(function* (error) {
+          const failedAt = yield* currentIsoTimestamp;
+          yield* updateState((current) =>
+            reduceDesktopUpdateStateOnCheckFailure(current, error.message, failedAt),
+          );
+          yield* logUpdaterError("failed to check for updates", { message: error.message });
+          return true;
+        }),
+      ),
+      Effect.ensuring(Ref.set(updateCheckInFlightRef, false)),
+    );
+  });
+
+  const downloadAvailableUpdate = Effect.gen(function* () {
+    const state = yield* Ref.get(updateStateRef);
+    if (
+      !(yield* Ref.get(updaterConfiguredRef)) ||
+      (yield* Ref.get(updateDownloadInFlightRef)) ||
+      state.status !== "available"
+    ) {
+      return { accepted: false, completed: false };
+    }
+
+    yield* Ref.set(updateDownloadInFlightRef, true);
+    return yield* Effect.gen(function* () {
+      yield* setState(reduceDesktopUpdateStateOnDownloadStart(state));
+      yield* electronUpdater.setDisableDifferentialDownload(
+        isArm64HostRunningIntelBuild(environment.runtimeInfo),
+      );
+      yield* logUpdaterInfo("downloading update");
+      yield* electronUpdater.downloadUpdate;
+      return { accepted: true, completed: true };
+    }).pipe(
+      Effect.catch(
+        Effect.fn("desktop.updates.handleDownloadFailure")(function* (error) {
+          yield* updateState((current) =>
+            reduceDesktopUpdateStateOnDownloadFailure(current, error.message),
+          );
+          yield* logUpdaterError("failed to download update", { message: error.message });
+          return { accepted: true, completed: false };
+        }),
+      ),
+      Effect.ensuring(Ref.set(updateDownloadInFlightRef, false)),
+    );
+  }).pipe(Effect.withSpan("desktop.updates.downloadAvailableUpdate"));
+
+  const installDownloadedUpdate = Effect.gen(function* () {
+    const state = yield* Ref.get(updateStateRef);
+    if (
+      (yield* Ref.get(desktopState.quitting)) ||
+      !(yield* Ref.get(updaterConfiguredRef)) ||
+      state.status !== "downloaded"
+    ) {
+      return { accepted: false, completed: false };
+    }
+
+    yield* Ref.set(desktopState.quitting, true);
+    yield* Ref.set(updateInstallInFlightRef, true);
+
+    return yield* Effect.gen(function* () {
+      yield* backendManager.stop({ timeout: Duration.seconds(5) });
+      yield* electronWindow.destroyAll;
+      yield* electronUpdater.quitAndInstall({
+        isSilent: true,
+        isForceRunAfter: true,
+      });
+      return { accepted: true, completed: false };
+    }).pipe(
+      Effect.catch(
+        Effect.fn("desktop.updates.handleInstallFailure")(function* (error) {
+          yield* Ref.set(updateInstallInFlightRef, false);
+          yield* updateState((current) =>
+            reduceDesktopUpdateStateOnInstallFailure(current, error.message),
+          );
+          yield* Ref.set(desktopState.quitting, false);
+          yield* logUpdaterError("failed to install update", { message: error.message });
+          return { accepted: true, completed: false };
+        }),
+      ),
+    );
+  }).pipe(Effect.withSpan("desktop.updates.installDownloadedUpdate"));
+
+  const startUpdatePollers: Effect.Effect<void, never, Scope.Scope> = Effect.gen(function* () {
+    yield* Effect.sleep(AUTO_UPDATE_STARTUP_DELAY).pipe(
+      Effect.andThen(checkForUpdates("startup")),
+      Effect.catchCause((cause) =>
+        logUpdaterError("startup update check failed", { cause: Cause.pretty(cause) }),
+      ),
+      Effect.forkScoped,
+    );
+    yield* Effect.sleep(AUTO_UPDATE_POLL_INTERVAL).pipe(
+      Effect.andThen(checkForUpdates("poll")),
+      Effect.forever,
+      Effect.catchCause((cause) =>
+        logUpdaterError("poll update check failed", { cause: Cause.pretty(cause) }),
+      ),
+      Effect.forkScoped,
+    );
+  }).pipe(Effect.withSpan("desktop.updates.startPollers"));
+
+  const handleUpdateAvailable = Effect.fn("desktop.updates.handleUpdateAvailable")(function* (
+    raw: unknown,
+  ) {
+    yield* decodeUpdateInfo(raw).pipe(
+      Effect.flatMap(
+        Effect.fn("desktop.updates.applyUpdateAvailable")(function* (info) {
+          const state = yield* Ref.get(updateStateRef);
+          if (resolveDefaultDesktopUpdateChannel(info.version) !== state.channel) {
+            yield* logUpdaterInfo("ignoring update that does not match selected channel", {
+              version: info.version,
+              channel: state.channel,
+            });
+            const checkedAt = yield* currentIsoTimestamp;
+            yield* setState(reduceDesktopUpdateStateOnNoUpdate(state, checkedAt));
+            yield* Ref.set(lastLoggedDownloadMilestoneRef, -1);
+            return;
+          }
+
+          const checkedAt = yield* currentIsoTimestamp;
+          yield* setState(
+            reduceDesktopUpdateStateOnUpdateAvailable(state, info.version, checkedAt),
+          );
+          yield* Ref.set(lastLoggedDownloadMilestoneRef, -1);
+          yield* logUpdaterInfo("update available", { version: info.version });
+        }),
+      ),
+      Effect.catchCause((cause) =>
+        logUpdaterWarning("ignored malformed update-available event", {
+          cause: Cause.pretty(cause),
+        }),
+      ),
+    );
+  });
+
+  const handleUpdateNotAvailable = Effect.gen(function* () {
+    const checkedAt = yield* currentIsoTimestamp;
+    const state = yield* Ref.get(updateStateRef);
+    yield* setState(reduceDesktopUpdateStateOnNoUpdate(state, checkedAt));
+    yield* Ref.set(lastLoggedDownloadMilestoneRef, -1);
+    yield* logUpdaterInfo("no updates available");
+  }).pipe(Effect.withSpan("desktop.updates.handleUpdateNotAvailable"));
+
+  const handleUpdaterError = Effect.fn("desktop.updates.handleUpdaterError")(function* (
+    error: unknown,
+  ) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (yield* Ref.get(updateInstallInFlightRef)) {
+      yield* Ref.set(updateInstallInFlightRef, false);
+      yield* Ref.set(desktopState.quitting, false);
+      yield* updateState((current) => reduceDesktopUpdateStateOnInstallFailure(current, message));
+      yield* logUpdaterError("updater error", { message });
+      return;
+    }
+
+    if (!(yield* Ref.get(updateCheckInFlightRef)) && !(yield* Ref.get(updateDownloadInFlightRef))) {
+      const errorContext = yield* resolveUpdaterErrorContext;
+      const checkedAt = yield* currentIsoTimestamp;
+      yield* updateState((current) => ({
+        ...current,
+        status: "error",
+        message,
+        checkedAt,
+        downloadPercent: null,
+        errorContext,
+        canRetry: getCanRetryFromState(current),
+      }));
+    }
+
+    yield* logUpdaterError("updater error", { message });
+  });
+
+  const handleDownloadProgress = Effect.fn("desktop.updates.handleDownloadProgress")(function* (
+    raw: unknown,
+  ) {
+    yield* decodeDownloadProgressInfo(raw).pipe(
+      Effect.flatMap(
+        Effect.fn("desktop.updates.applyDownloadProgress")(function* (progress) {
+          const state = yield* Ref.get(updateStateRef);
+          const percent = Math.floor(progress.percent);
+          if (shouldBroadcastDownloadProgress(state, progress.percent) || state.message !== null) {
+            yield* setState(reduceDesktopUpdateStateOnDownloadProgress(state, progress.percent));
+          }
+          const milestone = percent - (percent % 10);
+          const lastLoggedMilestone = yield* Ref.get(lastLoggedDownloadMilestoneRef);
+          if (milestone > lastLoggedMilestone) {
+            yield* Ref.set(lastLoggedDownloadMilestoneRef, milestone);
+            yield* logUpdaterInfo("download progress", { percent });
+          }
+        }),
+      ),
+      Effect.catchCause((cause) =>
+        logUpdaterWarning("ignored malformed download-progress event", {
+          cause: Cause.pretty(cause),
+        }),
+      ),
+    );
+  });
+
+  const handleUpdateDownloaded = Effect.fn("desktop.updates.handleUpdateDownloaded")(function* (
+    raw: unknown,
+  ) {
+    yield* decodeUpdateInfo(raw).pipe(
+      Effect.flatMap(
+        Effect.fn("desktop.updates.applyUpdateDownloaded")(function* (info) {
+          const state = yield* Ref.get(updateStateRef);
+          yield* setState(reduceDesktopUpdateStateOnDownloadComplete(state, info.version));
+          yield* logUpdaterInfo("update downloaded", { version: info.version });
+        }),
+      ),
+      Effect.catchCause((cause) =>
+        logUpdaterWarning("ignored malformed update-downloaded event", {
+          cause: Cause.pretty(cause),
+        }),
+      ),
+    );
+  });
+
+  return DesktopUpdates.of({
+    getState: Ref.get(updateStateRef),
+    emitState,
+    disabledReason: resolveDisabledReason,
+    configure: Effect.gen(function* () {
+      const context = yield* Effect.context<never>();
+      const runEffect = (effect: Effect.Effect<void>) => {
+        void Effect.runPromiseWith(context)(effect);
+      };
+
+      const appUpdateYmlConfig = yield* readAppUpdateYml;
+      yield* Ref.set(appUpdateYmlConfigRef, appUpdateYmlConfig);
+
+      if (config.mockUpdates) {
+        yield* electronUpdater.setFeedURL({
+          provider: "generic",
+          url: `http://localhost:${config.mockUpdateServerPort}`,
+        } as ElectronUpdater.ElectronUpdaterFeedUrl);
+      }
+
+      const settings = yield* desktopSettings.get;
+      const enabled = yield* shouldEnableAutoUpdates;
+      yield* setState(createBaseUpdateState(settings.updateChannel, enabled, environment));
+      if (!enabled) {
+        return;
+      }
+      yield* Ref.set(updaterConfiguredRef, true);
+
+      yield* electronUpdater.setAutoDownload(false);
+      yield* electronUpdater.setAutoInstallOnAppQuit(false);
+      yield* applyAutoUpdaterChannel(settings.updateChannel);
+      yield* electronUpdater.setDisableDifferentialDownload(
+        isArm64HostRunningIntelBuild(environment.runtimeInfo),
+      );
+
+      if (isArm64HostRunningIntelBuild(environment.runtimeInfo)) {
+        yield* logUpdaterInfo(
+          "Apple Silicon host detected while running Intel build; updates will switch to arm64 packages",
+        );
+      }
+
+      yield* electronUpdater.on("checking-for-update", () => {
+        runEffect(
+          logUpdaterInfo("looking for updates").pipe(
+            Effect.withSpan("desktop.updates.handleCheckingForUpdate"),
+          ),
+        );
+      });
+      yield* electronUpdater.on("update-available", (info: unknown) => {
+        runEffect(handleUpdateAvailable(info));
+      });
+      yield* electronUpdater.on("update-not-available", () => {
+        runEffect(handleUpdateNotAvailable);
+      });
+      yield* electronUpdater.on("error", (error: unknown) => {
+        runEffect(handleUpdaterError(error));
+      });
+      yield* electronUpdater.on("download-progress", (progress: unknown) => {
+        runEffect(handleDownloadProgress(progress));
+      });
+      yield* electronUpdater.on("update-downloaded", (info: unknown) => {
+        runEffect(handleUpdateDownloaded(info));
+      });
+
+      yield* startUpdatePollers;
+    }).pipe(Effect.withSpan("desktop.updates.configure")),
+    setChannel: Effect.fn("desktop.updates.setChannel")(function* (
+      nextChannel: DesktopUpdateChannel,
+    ) {
+      yield* Effect.annotateCurrentSpan({ channel: nextChannel });
+      const activeAction = yield* activeUpdateAction;
+      if (Option.isSome(activeAction)) {
+        return yield* new DesktopUpdateActionInProgressError({ action: activeAction.value });
+      }
+
+      const state = yield* Ref.get(updateStateRef);
+      if (nextChannel === state.channel) {
+        return state;
+      }
+
+      yield* desktopSettings
+        .setUpdateChannel(nextChannel)
+        .pipe(Effect.mapError((cause) => new DesktopUpdatePersistenceError({ cause })));
+
+      const enabled = yield* shouldEnableAutoUpdates;
+      yield* setState(createBaseUpdateState(nextChannel, enabled, environment));
+
+      if (!enabled || !(yield* Ref.get(updaterConfiguredRef))) {
+        return yield* Ref.get(updateStateRef);
+      }
+
+      yield* applyAutoUpdaterChannel(nextChannel);
+      const allowDowngrade = yield* electronUpdater.allowDowngrade;
+      yield* electronUpdater.setAllowDowngrade(true);
+      yield* checkForUpdates("channel-change").pipe(
+        Effect.ensuring(electronUpdater.setAllowDowngrade(allowDowngrade).pipe(Effect.ignore)),
+      );
+      return yield* Ref.get(updateStateRef);
+    }),
+    check: Effect.fn("desktop.updates.check")(function* (reason: string) {
+      yield* Effect.annotateCurrentSpan({ reason });
+      if (!(yield* Ref.get(updaterConfiguredRef))) {
+        return {
+          checked: false,
+          state: yield* Ref.get(updateStateRef),
+        };
+      }
+      const checked = yield* checkForUpdates(reason);
+      return {
+        checked,
+        state: yield* Ref.get(updateStateRef),
+      };
+    }),
+    download: Effect.gen(function* () {
+      const result = yield* downloadAvailableUpdate;
+      return {
+        accepted: result.accepted,
+        completed: result.completed,
+        state: yield* Ref.get(updateStateRef),
+      };
+    }).pipe(Effect.withSpan("desktop.updates.download")),
+    install: Effect.gen(function* () {
+      if (yield* Ref.get(desktopState.quitting)) {
+        return {
+          accepted: false,
+          completed: false,
+          state: yield* Ref.get(updateStateRef),
+        };
+      }
+      const result = yield* installDownloadedUpdate;
+      return {
+        accepted: result.accepted,
+        completed: result.completed,
+        state: yield* Ref.get(updateStateRef),
+      };
+    }).pipe(Effect.withSpan("desktop.updates.install")),
+  });
+});
+
+export const layer = Layer.effect(DesktopUpdates, make);
diff --git a/apps/desktop/src/updates/updateChannels.ts b/apps/desktop/src/updates/updateChannels.ts
new file mode 100644
index 00000000000..731910e441f
--- /dev/null
+++ b/apps/desktop/src/updates/updateChannels.ts
@@ -0,0 +1,11 @@
+import type { DesktopUpdateChannel } from "@t3tools/contracts";
+
+const NIGHTLY_VERSION_PATTERN = /-nightly\.\d{8}\.\d+$/;
+
+export function isNightlyDesktopVersion(version: string): boolean {
+  return NIGHTLY_VERSION_PATTERN.test(version);
+}
+
+export function resolveDefaultDesktopUpdateChannel(appVersion: string): DesktopUpdateChannel {
+  return isNightlyDesktopVersion(appVersion) ? "nightly" : "latest";
+}
diff --git a/apps/desktop/src/updateMachine.test.ts b/apps/desktop/src/updates/updateMachine.test.ts
similarity index 88%
rename from apps/desktop/src/updateMachine.test.ts
rename to apps/desktop/src/updates/updateMachine.test.ts
index 7fbc982eff8..e2f0519d350 100644
--- a/apps/desktop/src/updateMachine.test.ts
+++ b/apps/desktop/src/updates/updateMachine.test.ts
@@ -11,7 +11,7 @@ import {
   reduceDesktopUpdateStateOnInstallFailure,
   reduceDesktopUpdateStateOnNoUpdate,
   reduceDesktopUpdateStateOnUpdateAvailable,
-} from "./updateMachine";
+} from "./updateMachine.ts";
 
 const runtimeInfo = {
   hostArch: "x64",
@@ -23,7 +23,7 @@ describe("updateMachine", () => {
   it("clears transient errors when a check starts", () => {
     const state = reduceDesktopUpdateStateOnCheckStart(
       {
-        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo),
+        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo, "latest"),
         enabled: true,
         status: "error",
         message: "network",
@@ -42,7 +42,7 @@ describe("updateMachine", () => {
   it("records a check failure without exposing an action", () => {
     const state = reduceDesktopUpdateStateOnCheckFailure(
       {
-        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo),
+        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo, "latest"),
         enabled: true,
         status: "checking",
       },
@@ -58,7 +58,7 @@ describe("updateMachine", () => {
   it("preserves available version on download failure for retry", () => {
     const state = reduceDesktopUpdateStateOnDownloadFailure(
       {
-        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo),
+        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo, "latest"),
         enabled: true,
         status: "downloading",
         availableVersion: "1.1.0",
@@ -76,7 +76,7 @@ describe("updateMachine", () => {
   it("transitions to downloaded and then preserves install retry state", () => {
     const downloaded = reduceDesktopUpdateStateOnDownloadComplete(
       {
-        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo),
+        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo, "latest"),
         enabled: true,
         status: "downloading",
         availableVersion: "1.1.0",
@@ -98,7 +98,7 @@ describe("updateMachine", () => {
   it("clears stale download state when no update is available", () => {
     const state = reduceDesktopUpdateStateOnNoUpdate(
       {
-        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo),
+        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo, "latest"),
         enabled: true,
         status: "error",
         availableVersion: "1.1.0",
@@ -120,7 +120,7 @@ describe("updateMachine", () => {
   it("tracks available, download start, and progress cleanly", () => {
     const available = reduceDesktopUpdateStateOnUpdateAvailable(
       {
-        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo),
+        ...createInitialDesktopUpdateState("1.0.0", runtimeInfo, "latest"),
         enabled: true,
         status: "checking",
       },
@@ -131,6 +131,7 @@ describe("updateMachine", () => {
     const progress = reduceDesktopUpdateStateOnDownloadProgress(downloading, 55.5);
 
     expect(available.status).toBe("available");
+    expect(available.channel).toBe("latest");
     expect(downloading.status).toBe("downloading");
     expect(downloading.downloadPercent).toBe(0);
     expect(progress.downloadPercent).toBe(55.5);
diff --git a/apps/desktop/src/updateMachine.ts b/apps/desktop/src/updates/updateMachine.ts
similarity index 87%
rename from apps/desktop/src/updateMachine.ts
rename to apps/desktop/src/updates/updateMachine.ts
index f13b4202810..b5037225774 100644
--- a/apps/desktop/src/updateMachine.ts
+++ b/apps/desktop/src/updates/updateMachine.ts
@@ -1,14 +1,28 @@
-import type { DesktopRuntimeInfo, DesktopUpdateState } from "@t3tools/contracts";
+import type {
+  DesktopRuntimeInfo,
+  DesktopUpdateChannel,
+  DesktopUpdateState,
+} from "@t3tools/contracts";
 
-import { getCanRetryAfterDownloadFailure, nextStatusAfterDownloadFailure } from "./updateState";
+export function nextStatusAfterDownloadFailure(
+  currentState: DesktopUpdateState,
+): DesktopUpdateState["status"] {
+  return currentState.availableVersion ? "available" : "error";
+}
+
+export function getCanRetryAfterDownloadFailure(currentState: DesktopUpdateState): boolean {
+  return currentState.availableVersion !== null;
+}
 
 export function createInitialDesktopUpdateState(
   currentVersion: string,
   runtimeInfo: DesktopRuntimeInfo,
+  channel: DesktopUpdateChannel,
 ): DesktopUpdateState {
   return {
     enabled: false,
     status: "disabled",
+    channel,
     currentVersion,
     hostArch: runtimeInfo.hostArch,
     appArch: runtimeInfo.appArch,
diff --git a/apps/desktop/src/window/DesktopApplicationMenu.test.ts b/apps/desktop/src/window/DesktopApplicationMenu.test.ts
new file mode 100644
index 00000000000..fc589b3e39b
--- /dev/null
+++ b/apps/desktop/src/window/DesktopApplicationMenu.test.ts
@@ -0,0 +1,132 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import type * as Electron from "electron";
+
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronDialog from "../electron/ElectronDialog.ts";
+import * as ElectronMenu from "../electron/ElectronMenu.ts";
+import * as DesktopApplicationMenu from "./DesktopApplicationMenu.ts";
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopUpdates from "../updates/DesktopUpdates.ts";
+import * as DesktopWindow from "./DesktopWindow.ts";
+
+const environmentInput = {
+  dirname: "/repo/apps/desktop/dist-electron",
+  homeDirectory: "/Users/alice",
+  platform: "linux",
+  processArch: "arm64",
+  appVersion: "1.2.3",
+  appPath: "/repo",
+  isPackaged: false,
+  resourcesPath: "/repo/resources",
+  runningUnderArm64Translation: false,
+} satisfies DesktopEnvironment.MakeDesktopEnvironmentInput;
+
+const electronAppLayer = Layer.succeed(ElectronApp.ElectronApp, {
+  metadata: Effect.die("unexpected metadata read"),
+  name: Effect.succeed("T3 Code"),
+  whenReady: Effect.void,
+  quit: Effect.void,
+  exit: () => Effect.void,
+  relaunch: () => Effect.void,
+  setPath: () => Effect.void,
+  setName: () => Effect.void,
+  setAboutPanelOptions: () => Effect.void,
+  setAppUserModelId: () => Effect.void,
+  setDesktopName: () => Effect.void,
+  setDockIcon: () => Effect.void,
+  appendCommandLineSwitch: () => Effect.void,
+  on: () => Effect.void,
+} satisfies ElectronApp.ElectronAppShape);
+
+const electronDialogLayer = Layer.succeed(ElectronDialog.ElectronDialog, {
+  pickFolder: () => Effect.succeed(Option.none()),
+  confirm: () => Effect.succeed(false),
+  showMessageBox: () => Effect.succeed({ response: 0, checkboxChecked: false }),
+  showErrorBox: () => Effect.void,
+} satisfies ElectronDialog.ElectronDialogShape);
+
+const desktopUpdatesLayer = Layer.succeed(DesktopUpdates.DesktopUpdates, {
+  getState: Effect.die("unexpected getState"),
+  emitState: Effect.void,
+  disabledReason: Effect.succeed(Option.none()),
+  configure: Effect.void,
+  setChannel: () => Effect.die("unexpected setChannel"),
+  check: () => Effect.die("unexpected check"),
+  download: Effect.die("unexpected download"),
+  install: Effect.die("unexpected install"),
+} satisfies DesktopUpdates.DesktopUpdatesShape);
+
+const makeDesktopWindowLayer = (selectedAction: Deferred.Deferred<string>) =>
+  Layer.succeed(DesktopWindow.DesktopWindow, {
+    createMain: Effect.die("unexpected createMain"),
+    ensureMain: Effect.die("unexpected ensureMain"),
+    revealOrCreateMain: Effect.die("unexpected revealOrCreateMain"),
+    activate: Effect.void,
+    createMainIfBackendReady: Effect.void,
+    handleBackendReady: Effect.void,
+    dispatchMenuAction: (action) => Deferred.succeed(selectedAction, action).pipe(Effect.asVoid),
+    syncAppearance: Effect.void,
+  } satisfies DesktopWindow.DesktopWindowShape);
+
+const makeElectronMenuLayer = (
+  applicationMenuTemplate: Deferred.Deferred<readonly Electron.MenuItemConstructorOptions[]>,
+) =>
+  Layer.succeed(ElectronMenu.ElectronMenu, {
+    setApplicationMenu: (template) =>
+      Deferred.succeed(applicationMenuTemplate, template).pipe(Effect.asVoid),
+    popupTemplate: () => Effect.void,
+    showContextMenu: () => Effect.succeed(Option.none()),
+  } satisfies ElectronMenu.ElectronMenuShape);
+
+describe("DesktopApplicationMenu", () => {
+  it.effect("installs the native menu and routes Settings through DesktopWindow", () =>
+    Effect.gen(function* () {
+      const selectedAction = yield* Deferred.make<string>();
+      const applicationMenuTemplate =
+        yield* Deferred.make<readonly Electron.MenuItemConstructorOptions[]>();
+
+      yield* Effect.gen(function* () {
+        const menu = yield* DesktopApplicationMenu.DesktopApplicationMenu;
+        yield* menu.configure;
+      }).pipe(
+        Effect.provide(
+          DesktopApplicationMenu.layer.pipe(
+            Layer.provideMerge(makeElectronMenuLayer(applicationMenuTemplate)),
+            Layer.provideMerge(makeDesktopWindowLayer(selectedAction)),
+            Layer.provideMerge(desktopUpdatesLayer),
+            Layer.provideMerge(electronDialogLayer),
+            Layer.provideMerge(electronAppLayer),
+            Layer.provideMerge(
+              DesktopEnvironment.layer(environmentInput).pipe(
+                Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({}))),
+              ),
+            ),
+          ),
+        ),
+      );
+
+      const template = yield* Deferred.await(applicationMenuTemplate);
+      const fileMenu = template.find((item) => item.label === "File");
+      assert.isDefined(fileMenu);
+      if (!Array.isArray(fileMenu.submenu)) {
+        throw new Error("Expected File menu submenu to be an array.");
+      }
+      const settingsItem = fileMenu.submenu.find((item) => item.label === "Settings...");
+      assert.isDefined(settingsItem);
+      const settingsClick = settingsItem.click;
+      if (typeof settingsClick !== "function") {
+        throw new Error("Expected Settings menu item to have a click handler.");
+      }
+
+      settingsClick({} as Electron.MenuItem, {} as Electron.BrowserWindow, {} as KeyboardEvent);
+      assert.equal(yield* Deferred.await(selectedAction), "open-settings");
+    }),
+  );
+});
diff --git a/apps/desktop/src/window/DesktopApplicationMenu.ts b/apps/desktop/src/window/DesktopApplicationMenu.ts
new file mode 100644
index 00000000000..5e65d81910a
--- /dev/null
+++ b/apps/desktop/src/window/DesktopApplicationMenu.ts
@@ -0,0 +1,212 @@
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import type * as Electron from "electron";
+
+import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronDialog from "../electron/ElectronDialog.ts";
+import * as ElectronMenu from "../electron/ElectronMenu.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopUpdates from "../updates/DesktopUpdates.ts";
+import * as DesktopWindow from "./DesktopWindow.ts";
+
+export interface DesktopApplicationMenuShape {
+  readonly configure: Effect.Effect<void>;
+}
+
+export class DesktopApplicationMenu extends Context.Service<
+  DesktopApplicationMenu,
+  DesktopApplicationMenuShape
+>()("t3/desktop/ApplicationMenu") {}
+
+type DesktopApplicationMenuRuntimeServices =
+  | DesktopUpdates.DesktopUpdates
+  | DesktopWindow.DesktopWindow
+  | ElectronDialog.ElectronDialog;
+
+const { logInfo: logUpdaterInfo } = DesktopObservability.makeComponentLogger("desktop-updater");
+
+const { logError: logMenuError } = DesktopObservability.makeComponentLogger("desktop-menu");
+
+const dispatchMenuAction = Effect.fn("desktop.menu.dispatchMenuAction")(function* (
+  action: string,
+): Effect.fn.Return<void, DesktopWindow.DesktopWindowError, DesktopWindow.DesktopWindow> {
+  const desktopWindow = yield* DesktopWindow.DesktopWindow;
+  yield* desktopWindow.dispatchMenuAction(action);
+});
+
+const checkForUpdatesFromMenu: Effect.Effect<
+  void,
+  never,
+  DesktopUpdates.DesktopUpdates | ElectronDialog.ElectronDialog
+> = Effect.gen(function* () {
+  const updates = yield* DesktopUpdates.DesktopUpdates;
+  const electronDialog = yield* ElectronDialog.ElectronDialog;
+  const result = yield* updates.check("menu");
+  const updateState = result.state;
+
+  if (updateState.status === "up-to-date") {
+    yield* electronDialog.showMessageBox({
+      type: "info",
+      title: "You're up to date!",
+      message: `T3 Code ${updateState.currentVersion} is currently the newest version available.`,
+      buttons: ["OK"],
+    });
+  } else if (updateState.status === "error") {
+    yield* electronDialog.showMessageBox({
+      type: "warning",
+      title: "Update check failed",
+      message: "Could not check for updates.",
+      detail: updateState.message ?? "An unknown error occurred. Please try again later.",
+      buttons: ["OK"],
+    });
+  }
+}).pipe(Effect.withSpan("desktop.menu.checkForUpdates"));
+
+const handleCheckForUpdatesMenuClick: Effect.Effect<
+  void,
+  DesktopWindow.DesktopWindowError,
+  DesktopUpdates.DesktopUpdates | ElectronDialog.ElectronDialog | DesktopWindow.DesktopWindow
+> = Effect.gen(function* () {
+  const updates = yield* DesktopUpdates.DesktopUpdates;
+  const electronDialog = yield* ElectronDialog.ElectronDialog;
+  const disabledReason = yield* updates.disabledReason;
+  if (Option.isSome(disabledReason)) {
+    yield* logUpdaterInfo("manual update check requested, but updates are disabled", {
+      disabledReason: disabledReason.value,
+    });
+    yield* electronDialog.showMessageBox({
+      type: "info",
+      title: "Updates unavailable",
+      message: "Automatic updates are not available right now.",
+      detail: disabledReason.value,
+      buttons: ["OK"],
+    });
+    return;
+  }
+
+  const desktopWindow = yield* DesktopWindow.DesktopWindow;
+  yield* desktopWindow.ensureMain;
+  yield* checkForUpdatesFromMenu;
+}).pipe(Effect.withSpan("desktop.menu.handleCheckForUpdatesClick"));
+
+const make = Effect.gen(function* () {
+  const electronApp = yield* ElectronApp.ElectronApp;
+  const electronMenu = yield* ElectronMenu.ElectronMenu;
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const appName = yield* electronApp.name;
+  const context = yield* Effect.context<DesktopApplicationMenuRuntimeServices>();
+  const runPromise = Effect.runPromiseWith(context);
+
+  const runMenuEffect = <E>(
+    action: string,
+    effect: Effect.Effect<void, E, DesktopApplicationMenuRuntimeServices>,
+  ) => {
+    void runPromise(
+      effect.pipe(
+        Effect.annotateLogs({ action }),
+        Effect.withSpan("desktop.menu.action"),
+        Effect.catchCause((cause) =>
+          logMenuError("desktop menu action failed", {
+            action,
+            cause: Cause.pretty(cause),
+          }),
+        ),
+      ),
+    );
+  };
+
+  const configure = Effect.gen(function* () {
+    const checkForUpdatesClick = () => {
+      runMenuEffect("check-for-updates", handleCheckForUpdatesMenuClick);
+    };
+    const settingsClick = () => {
+      runMenuEffect("open-settings", dispatchMenuAction("open-settings"));
+    };
+    const template: Electron.MenuItemConstructorOptions[] = [];
+
+    if (environment.platform === "darwin") {
+      template.push({
+        label: appName,
+        submenu: [
+          { role: "about" },
+          {
+            label: "Check for Updates...",
+            click: checkForUpdatesClick,
+          },
+          { type: "separator" },
+          {
+            label: "Settings...",
+            accelerator: "CmdOrCtrl+,",
+            click: settingsClick,
+          },
+          { type: "separator" },
+          { role: "services" },
+          { type: "separator" },
+          { role: "hide" },
+          { role: "hideOthers" },
+          { role: "unhide" },
+          { type: "separator" },
+          { role: "quit" },
+        ],
+      });
+    }
+
+    template.push(
+      {
+        label: "File",
+        submenu: [
+          ...(environment.platform === "darwin"
+            ? []
+            : [
+                {
+                  label: "Settings...",
+                  accelerator: "CmdOrCtrl+,",
+                  click: settingsClick,
+                },
+                { type: "separator" as const },
+              ]),
+          { role: environment.platform === "darwin" ? "close" : "quit" },
+        ],
+      },
+      { role: "editMenu" },
+      {
+        label: "View",
+        submenu: [
+          { role: "reload" },
+          { role: "forceReload" },
+          { role: "toggleDevTools" },
+          { type: "separator" },
+          { role: "resetZoom" },
+          { role: "zoomIn", accelerator: "CmdOrCtrl+=" },
+          { role: "zoomIn", accelerator: "CmdOrCtrl+Plus", visible: false },
+          { role: "zoomOut" },
+          { type: "separator" },
+          { role: "togglefullscreen" },
+        ],
+      },
+      { role: "windowMenu" },
+      {
+        role: "help",
+        submenu: [
+          {
+            label: "Check for Updates...",
+            click: checkForUpdatesClick,
+          },
+        ],
+      },
+    );
+
+    yield* electronMenu.setApplicationMenu(template);
+  }).pipe(Effect.withSpan("desktop.menu.configure"));
+
+  return DesktopApplicationMenu.of({
+    configure,
+  });
+});
+
+export const layer = Layer.effect(DesktopApplicationMenu, make);
diff --git a/apps/desktop/src/window/DesktopWindow.test.ts b/apps/desktop/src/window/DesktopWindow.test.ts
new file mode 100644
index 00000000000..fbcc60934aa
--- /dev/null
+++ b/apps/desktop/src/window/DesktopWindow.test.ts
@@ -0,0 +1,180 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+
+import type * as Electron from "electron";
+import { vi } from "vitest";
+
+import * as DesktopAssets from "../app/DesktopAssets.ts";
+import * as DesktopConfig from "../app/DesktopConfig.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopState from "../app/DesktopState.ts";
+import * as ElectronMenu from "../electron/ElectronMenu.ts";
+import * as ElectronShell from "../electron/ElectronShell.ts";
+import * as ElectronTheme from "../electron/ElectronTheme.ts";
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
+import * as DesktopServerExposure from "../backend/DesktopServerExposure.ts";
+import * as DesktopWindow from "./DesktopWindow.ts";
+
+const environmentInput = {
+  dirname: "/repo/apps/desktop/dist-electron",
+  homeDirectory: "/Users/alice",
+  platform: "darwin",
+  processArch: "arm64",
+  appVersion: "1.2.3",
+  appPath: "/repo",
+  isPackaged: false,
+  resourcesPath: "/repo/resources",
+  runningUnderArm64Translation: false,
+} satisfies DesktopEnvironment.MakeDesktopEnvironmentInput;
+
+function makeFakeBrowserWindow() {
+  const webContents = {
+    copyImageAt: vi.fn(),
+    isLoadingMainFrame: vi.fn(() => false),
+    on: vi.fn(),
+    once: vi.fn(),
+    openDevTools: vi.fn(),
+    replaceMisspelling: vi.fn(),
+    send: vi.fn(),
+    setWindowOpenHandler: vi.fn(),
+  };
+
+  const window = {
+    focus: vi.fn(),
+    isDestroyed: vi.fn(() => false),
+    isMinimized: vi.fn(() => false),
+    isVisible: vi.fn(() => true),
+    loadURL: vi.fn(() => Promise.resolve()),
+    on: vi.fn(),
+    once: vi.fn(),
+    restore: vi.fn(),
+    setBackgroundColor: vi.fn(),
+    setTitle: vi.fn(),
+    setTitleBarOverlay: vi.fn(),
+    show: vi.fn(),
+    webContents,
+  };
+
+  return {
+    window: window as unknown as Electron.BrowserWindow,
+    loadURL: window.loadURL,
+    openDevTools: webContents.openDevTools,
+  };
+}
+
+const desktopAssetsLayer = Layer.succeed(DesktopAssets.DesktopAssets, {
+  iconPaths: Effect.succeed({
+    ico: Option.none<string>(),
+    icns: Option.none<string>(),
+    png: Option.none<string>(),
+  }),
+  resolveResourcePath: () => Effect.succeed(Option.none<string>()),
+} satisfies DesktopAssets.DesktopAssetsShape);
+
+const desktopServerExposureLayer = Layer.succeed(DesktopServerExposure.DesktopServerExposure, {
+  getState: Effect.die("unexpected getState"),
+  backendConfig: Effect.succeed({
+    port: 3773,
+    bindHost: "127.0.0.1",
+    httpBaseUrl: new URL("http://127.0.0.1:3773"),
+    tailscaleServeEnabled: false,
+    tailscaleServePort: 443,
+  }),
+  configureFromSettings: () => Effect.die("unexpected configureFromSettings"),
+  setMode: () => Effect.die("unexpected setMode"),
+  setTailscaleServeEnabled: () => Effect.die("unexpected setTailscaleServeEnabled"),
+  getAdvertisedEndpoints: Effect.die("unexpected getAdvertisedEndpoints"),
+} satisfies DesktopServerExposure.DesktopServerExposureShape);
+
+const electronMenuLayer = Layer.succeed(ElectronMenu.ElectronMenu, {
+  setApplicationMenu: () => Effect.void,
+  popupTemplate: () => Effect.void,
+  showContextMenu: () => Effect.succeed(Option.none()),
+} satisfies ElectronMenu.ElectronMenuShape);
+
+const electronShellLayer = Layer.succeed(ElectronShell.ElectronShell, {
+  openExternal: () => Effect.succeed(true),
+  copyText: () => Effect.void,
+} satisfies ElectronShell.ElectronShellShape);
+
+const electronThemeLayer = Layer.succeed(ElectronTheme.ElectronTheme, {
+  shouldUseDarkColors: Effect.succeed(false),
+  setSource: () => Effect.void,
+  onUpdated: () => Effect.void,
+} satisfies ElectronTheme.ElectronThemeShape);
+
+const desktopEnvironmentLayer = DesktopEnvironment.layer(environmentInput).pipe(
+  Layer.provide(
+    Layer.mergeAll(
+      NodeServices.layer,
+      DesktopConfig.layerTest({
+        T3CODE_PORT: "3773",
+        VITE_DEV_SERVER_URL: "http://127.0.0.1:5733",
+      }),
+    ),
+  ),
+);
+
+function makeTestLayer(input: {
+  readonly window: Electron.BrowserWindow;
+  readonly createCount: Ref.Ref<number>;
+  readonly mainWindow: Ref.Ref<Option.Option<Electron.BrowserWindow>>;
+}) {
+  const electronWindowLayer = Layer.succeed(ElectronWindow.ElectronWindow, {
+    create: () => Ref.update(input.createCount, (count) => count + 1).pipe(Effect.as(input.window)),
+    main: Ref.get(input.mainWindow),
+    currentMainOrFirst: Ref.get(input.mainWindow),
+    focusedMainOrFirst: Ref.get(input.mainWindow),
+    setMain: (window) => Ref.set(input.mainWindow, Option.some(window)),
+    clearMain: () => Ref.set(input.mainWindow, Option.none()),
+    reveal: () => Effect.void,
+    sendAll: () => Effect.void,
+    destroyAll: Effect.void,
+    syncAllAppearance: (sync) => sync(input.window),
+  } satisfies ElectronWindow.ElectronWindowShape);
+
+  return DesktopWindow.layer.pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        desktopAssetsLayer,
+        desktopEnvironmentLayer,
+        desktopServerExposureLayer,
+        DesktopState.layer,
+        electronMenuLayer,
+        electronShellLayer,
+        electronThemeLayer,
+        electronWindowLayer,
+      ),
+    ),
+  );
+}
+
+describe("DesktopWindow", () => {
+  it.effect("does not open a development window until the backend is ready", () =>
+    Effect.gen(function* () {
+      const fakeWindow = makeFakeBrowserWindow();
+      const createCount = yield* Ref.make(0);
+      const mainWindow = yield* Ref.make<Option.Option<Electron.BrowserWindow>>(Option.none());
+      const layer = makeTestLayer({
+        window: fakeWindow.window,
+        createCount,
+        mainWindow,
+      });
+
+      yield* Effect.gen(function* () {
+        const desktopWindow = yield* DesktopWindow.DesktopWindow;
+        yield* desktopWindow.activate;
+        assert.equal(yield* Ref.get(createCount), 0);
+
+        yield* desktopWindow.handleBackendReady;
+        assert.equal(yield* Ref.get(createCount), 1);
+        assert.deepEqual(fakeWindow.loadURL.mock.calls[0], ["http://127.0.0.1:5733/"]);
+        assert.equal(fakeWindow.openDevTools.mock.calls.length, 1);
+      }).pipe(Effect.provide(layer));
+    }),
+  );
+});
diff --git a/apps/desktop/src/window/DesktopWindow.ts b/apps/desktop/src/window/DesktopWindow.ts
new file mode 100644
index 00000000000..8ebd1041c6b
--- /dev/null
+++ b/apps/desktop/src/window/DesktopWindow.ts
@@ -0,0 +1,368 @@
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+
+import type * as Electron from "electron";
+
+import * as DesktopAssets from "../app/DesktopAssets.ts";
+import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
+import * as DesktopObservability from "../app/DesktopObservability.ts";
+import * as DesktopState from "../app/DesktopState.ts";
+import * as ElectronMenu from "../electron/ElectronMenu.ts";
+import * as ElectronShell from "../electron/ElectronShell.ts";
+import * as ElectronTheme from "../electron/ElectronTheme.ts";
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
+import * as IpcChannels from "../ipc/channels.ts";
+import * as DesktopServerExposure from "../backend/DesktopServerExposure.ts";
+
+const TITLEBAR_HEIGHT = 40;
+const TITLEBAR_COLOR = "#01000000"; // #00000000 does not work correctly on Linux
+const TITLEBAR_LIGHT_SYMBOL_COLOR = "#1f2937";
+const TITLEBAR_DARK_SYMBOL_COLOR = "#f8fafc";
+
+type WindowTitleBarOptions = Pick<
+  Electron.BrowserWindowConstructorOptions,
+  "titleBarOverlay" | "titleBarStyle" | "trafficLightPosition"
+>;
+
+type DesktopWindowRuntimeServices =
+  | DesktopEnvironment.DesktopEnvironment
+  | DesktopAssets.DesktopAssets
+  | DesktopServerExposure.DesktopServerExposure
+  | DesktopState.DesktopState
+  | ElectronMenu.ElectronMenu
+  | ElectronShell.ElectronShell
+  | ElectronTheme.ElectronTheme
+  | ElectronWindow.ElectronWindow;
+
+export class DesktopWindowDevServerUrlMissingError extends Data.TaggedError(
+  "DesktopWindowDevServerUrlMissingError",
+)<{}> {
+  override get message() {
+    return "VITE_DEV_SERVER_URL is required in desktop development.";
+  }
+}
+
+export type DesktopWindowError =
+  | DesktopWindowDevServerUrlMissingError
+  | ElectronWindow.ElectronWindowCreateError;
+
+export interface DesktopWindowShape {
+  readonly createMain: Effect.Effect<Electron.BrowserWindow, DesktopWindowError>;
+  readonly ensureMain: Effect.Effect<Electron.BrowserWindow, DesktopWindowError>;
+  readonly revealOrCreateMain: Effect.Effect<Electron.BrowserWindow, DesktopWindowError>;
+  readonly activate: Effect.Effect<void, DesktopWindowError>;
+  readonly createMainIfBackendReady: Effect.Effect<void, DesktopWindowError>;
+  readonly handleBackendReady: Effect.Effect<void, DesktopWindowError>;
+  readonly dispatchMenuAction: (action: string) => Effect.Effect<void, DesktopWindowError>;
+  readonly syncAppearance: Effect.Effect<void>;
+}
+
+export class DesktopWindow extends Context.Service<DesktopWindow, DesktopWindowShape>()(
+  "t3/desktop/Window",
+) {}
+
+const { logInfo: logWindowInfo, logWarning: logWindowWarning } =
+  DesktopObservability.makeComponentLogger("desktop-window");
+
+function resolveDesktopDevServerUrl(
+  environment: DesktopEnvironment.DesktopEnvironmentShape,
+): Effect.Effect<string, DesktopWindowDevServerUrlMissingError> {
+  return Option.match(environment.devServerUrl, {
+    onNone: () => Effect.fail(new DesktopWindowDevServerUrlMissingError()),
+    onSome: (url) => Effect.succeed(url.href),
+  });
+}
+
+function getIconOption(
+  iconPaths: DesktopAssets.DesktopIconPaths,
+): { icon: string } | Record<string, never> {
+  if (process.platform === "darwin") return {}; // macOS uses .icns from app bundle
+  const ext = process.platform === "win32" ? "ico" : "png";
+  return Option.match(iconPaths[ext], {
+    onNone: () => ({}),
+    onSome: (icon) => ({ icon }),
+  });
+}
+
+function getInitialWindowBackgroundColor(shouldUseDarkColors: boolean): string {
+  return shouldUseDarkColors ? "#0a0a0a" : "#ffffff";
+}
+
+function getWindowTitleBarOptions(shouldUseDarkColors: boolean): WindowTitleBarOptions {
+  if (process.platform === "darwin") {
+    return {
+      titleBarStyle: "hiddenInset",
+      trafficLightPosition: { x: 16, y: 18 },
+    };
+  }
+
+  return {
+    titleBarStyle: "hidden",
+    titleBarOverlay: {
+      color: TITLEBAR_COLOR,
+      height: TITLEBAR_HEIGHT,
+      symbolColor: shouldUseDarkColors ? TITLEBAR_DARK_SYMBOL_COLOR : TITLEBAR_LIGHT_SYMBOL_COLOR,
+    },
+  };
+}
+
+function syncWindowAppearance(
+  window: Electron.BrowserWindow,
+  shouldUseDarkColors: boolean,
+): Effect.Effect<void> {
+  return Effect.sync(() => {
+    if (window.isDestroyed()) {
+      return;
+    }
+
+    window.setBackgroundColor(getInitialWindowBackgroundColor(shouldUseDarkColors));
+    const { titleBarOverlay } = getWindowTitleBarOptions(shouldUseDarkColors);
+    if (typeof titleBarOverlay === "object") {
+      window.setTitleBarOverlay(titleBarOverlay);
+    }
+  });
+}
+
+type RevealSubscription = (listener: () => void) => void;
+
+function bindFirstRevealTrigger(
+  subscribers: readonly RevealSubscription[],
+  reveal: () => void,
+): void {
+  let revealed = false;
+  const fire = () => {
+    if (revealed) return;
+    revealed = true;
+    reveal();
+  };
+  for (const subscribe of subscribers) {
+    subscribe(fire);
+  }
+}
+
+const make = Effect.gen(function* () {
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const assets = yield* DesktopAssets.DesktopAssets;
+  const electronMenu = yield* ElectronMenu.ElectronMenu;
+  const electronShell = yield* ElectronShell.ElectronShell;
+  const electronTheme = yield* ElectronTheme.ElectronTheme;
+  const electronWindow = yield* ElectronWindow.ElectronWindow;
+  const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
+  const state = yield* DesktopState.DesktopState;
+  const context = yield* Effect.context<DesktopWindowRuntimeServices>();
+  const runPromise = Effect.runPromiseWith(context);
+
+  const createWindow = Effect.fn("desktop.window.createWindow")(function* (
+    backendHttpUrl: URL,
+  ): Effect.fn.Return<Electron.BrowserWindow, DesktopWindowError> {
+    const iconPaths = yield* assets.iconPaths;
+    const iconOption = getIconOption(iconPaths);
+    const shouldUseDarkColors = yield* electronTheme.shouldUseDarkColors;
+    const window = yield* electronWindow.create({
+      width: 1100,
+      height: 780,
+      minWidth: 840,
+      minHeight: 620,
+      show: false,
+      autoHideMenuBar: true,
+      backgroundColor: getInitialWindowBackgroundColor(shouldUseDarkColors),
+      ...iconOption,
+      title: environment.displayName,
+      ...getWindowTitleBarOptions(shouldUseDarkColors),
+      webPreferences: {
+        preload: environment.preloadPath,
+        contextIsolation: true,
+        nodeIntegration: false,
+        sandbox: true,
+      },
+    });
+
+    window.webContents.on("context-menu", (event, params) => {
+      event.preventDefault();
+
+      const menuTemplate: Electron.MenuItemConstructorOptions[] = [];
+
+      if (params.misspelledWord) {
+        for (const suggestion of params.dictionarySuggestions.slice(0, 5)) {
+          menuTemplate.push({
+            label: suggestion,
+            click: () => window.webContents.replaceMisspelling(suggestion),
+          });
+        }
+        if (params.dictionarySuggestions.length === 0) {
+          menuTemplate.push({ label: "No suggestions", enabled: false });
+        }
+        menuTemplate.push({ type: "separator" });
+      }
+
+      if (Option.isSome(ElectronShell.parseSafeExternalUrl(params.linkURL))) {
+        menuTemplate.push(
+          {
+            label: "Copy Link",
+            click: () => {
+              void runPromise(electronShell.copyText(params.linkURL));
+            },
+          },
+          { type: "separator" },
+        );
+      }
+
+      if (params.mediaType === "image") {
+        menuTemplate.push({
+          label: "Copy Image",
+          click: () => window.webContents.copyImageAt(params.x, params.y),
+        });
+        menuTemplate.push({ type: "separator" });
+      }
+
+      menuTemplate.push(
+        { role: "cut", enabled: params.editFlags.canCut },
+        { role: "copy", enabled: params.editFlags.canCopy },
+        { role: "paste", enabled: params.editFlags.canPaste },
+        { role: "selectAll", enabled: params.editFlags.canSelectAll },
+      );
+
+      void runPromise(electronMenu.popupTemplate({ window, template: menuTemplate }));
+    });
+
+    window.webContents.setWindowOpenHandler(({ url }) => {
+      if (Option.isSome(ElectronShell.parseSafeExternalUrl(url))) {
+        void runPromise(electronShell.openExternal(url));
+      }
+      return { action: "deny" };
+    });
+
+    window.on("page-title-updated", (event) => {
+      event.preventDefault();
+      window.setTitle(environment.displayName);
+    });
+    window.webContents.on("did-finish-load", () => {
+      window.setTitle(environment.displayName);
+    });
+    window.webContents.on(
+      "did-fail-load",
+      (_event, errorCode, errorDescription, validatedURL, isMainFrame) => {
+        if (!isMainFrame) {
+          return;
+        }
+        void runPromise(
+          logWindowWarning("main window failed to load", {
+            errorCode,
+            errorDescription,
+            url: validatedURL,
+          }),
+        );
+      },
+    );
+    window.webContents.on("render-process-gone", (_event, details) => {
+      void runPromise(
+        logWindowWarning("main window render process gone", {
+          reason: details.reason,
+          exitCode: details.exitCode,
+        }),
+      );
+    });
+
+    const revealSubscribers: RevealSubscription[] = [(fire) => window.once("ready-to-show", fire)];
+    if (process.platform === "linux") {
+      revealSubscribers.push((fire) => window.webContents.once("did-finish-load", fire));
+    }
+    bindFirstRevealTrigger(revealSubscribers, () => {
+      void runPromise(electronWindow.reveal(window));
+    });
+
+    if (environment.isDevelopment) {
+      const devServerUrl = yield* resolveDesktopDevServerUrl(environment);
+      void window.loadURL(devServerUrl);
+      window.webContents.openDevTools({ mode: "detach" });
+    } else {
+      void window.loadURL(backendHttpUrl.href);
+    }
+
+    window.on("closed", () => {
+      void runPromise(electronWindow.clearMain(Option.some(window)));
+    });
+
+    return window;
+  });
+
+  const createMain = Effect.gen(function* () {
+    const backendConfig = yield* serverExposure.backendConfig;
+    const window = yield* createWindow(backendConfig.httpBaseUrl);
+    yield* electronWindow.setMain(window);
+    yield* logWindowInfo("main window created");
+    return window;
+  }).pipe(Effect.withSpan("desktop.window.createMain"));
+
+  const ensureMain = Effect.gen(function* () {
+    const existingWindow = yield* electronWindow.currentMainOrFirst;
+    if (Option.isSome(existingWindow)) {
+      return existingWindow.value;
+    }
+    return yield* createMain;
+  }).pipe(Effect.withSpan("desktop.window.ensureMain"));
+
+  const revealOrCreateMain = Effect.gen(function* () {
+    const window = yield* ensureMain;
+    yield* electronWindow.reveal(window);
+    return window;
+  }).pipe(Effect.withSpan("desktop.window.revealOrCreateMain"));
+
+  const createMainIfBackendReady = Effect.gen(function* () {
+    const backendReady = yield* Ref.get(state.backendReady);
+    if (!backendReady) return;
+    const existingWindow = yield* electronWindow.currentMainOrFirst;
+    if (Option.isSome(existingWindow)) return;
+    yield* createMain;
+  }).pipe(Effect.withSpan("desktop.window.createMainIfBackendReady"));
+
+  return DesktopWindow.of({
+    createMain,
+    ensureMain,
+    revealOrCreateMain,
+    activate: Effect.gen(function* () {
+      const existingWindow = yield* electronWindow.currentMainOrFirst;
+      if (Option.isSome(existingWindow)) {
+        yield* electronWindow.reveal(existingWindow.value);
+      } else {
+        yield* createMainIfBackendReady;
+      }
+    }).pipe(Effect.withSpan("desktop.window.activate")),
+    createMainIfBackendReady,
+    handleBackendReady: Effect.gen(function* () {
+      yield* Ref.set(state.backendReady, true);
+      yield* logWindowInfo("backend ready", { source: "http" });
+      yield* createMainIfBackendReady;
+    }).pipe(Effect.withSpan("desktop.window.handleBackendReady")),
+    dispatchMenuAction: Effect.fn("desktop.window.dispatchMenuAction")(function* (action) {
+      yield* Effect.annotateCurrentSpan({ action });
+      const existingWindow = yield* electronWindow.focusedMainOrFirst;
+      const targetWindow = Option.isSome(existingWindow) ? existingWindow.value : yield* createMain;
+
+      const send = () => {
+        if (targetWindow.isDestroyed()) return;
+        targetWindow.webContents.send(IpcChannels.MENU_ACTION_CHANNEL, action);
+        void runPromise(electronWindow.reveal(targetWindow));
+      };
+
+      if (targetWindow.webContents.isLoadingMainFrame()) {
+        targetWindow.webContents.once("did-finish-load", send);
+        return;
+      }
+
+      send();
+    }),
+    syncAppearance: Effect.gen(function* () {
+      const shouldUseDarkColors = yield* electronTheme.shouldUseDarkColors;
+      yield* electronWindow.syncAllAppearance((window) =>
+        syncWindowAppearance(window, shouldUseDarkColors),
+      );
+    }).pipe(Effect.withSpan("desktop.window.syncAppearance")),
+  });
+});
+
+export const layer = Layer.effect(DesktopWindow, make);
diff --git a/apps/desktop/tsconfig.json b/apps/desktop/tsconfig.json
index 0ca5bcaa76a..ff3e4cd0f38 100644
--- a/apps/desktop/tsconfig.json
+++ b/apps/desktop/tsconfig.json
@@ -3,7 +3,7 @@
   "compilerOptions": {
     "composite": true,
     "types": ["node", "electron"],
-    "lib": ["ES2023", "DOM", "esnext.disposable"]
+    "lib": ["ESNext", "DOM", "esnext.disposable"]
   },
   "include": ["src", "tsdown.config.ts"]
 }
diff --git a/apps/desktop/tsdown.config.ts b/apps/desktop/tsdown.config.ts
index f3ebc973253..53b00393439 100644
--- a/apps/desktop/tsdown.config.ts
+++ b/apps/desktop/tsdown.config.ts
@@ -4,7 +4,7 @@ const shared = {
   format: "cjs" as const,
   outDir: "dist-electron",
   sourcemap: true,
-  outExtensions: () => ({ js: ".js" }),
+  outExtensions: () => ({ js: ".cjs" }),
 };
 
 export default defineConfig([
diff --git a/apps/marketing/public/apple-touch-icon.webp b/apps/marketing/public/apple-touch-icon.webp
new file mode 100644
index 00000000000..fc990561902
Binary files /dev/null and b/apps/marketing/public/apple-touch-icon.webp differ
diff --git a/apps/marketing/public/favicon-16x16.webp b/apps/marketing/public/favicon-16x16.webp
new file mode 100644
index 00000000000..b09dc155aef
Binary files /dev/null and b/apps/marketing/public/favicon-16x16.webp differ
diff --git a/apps/marketing/public/favicon-32x32.webp b/apps/marketing/public/favicon-32x32.webp
new file mode 100644
index 00000000000..72c9243de42
Binary files /dev/null and b/apps/marketing/public/favicon-32x32.webp differ
diff --git a/apps/marketing/public/harnesses/claude-ai-icon.svg b/apps/marketing/public/harnesses/claude-ai-icon.svg
new file mode 100644
index 00000000000..324389017b5
--- /dev/null
+++ b/apps/marketing/public/harnesses/claude-ai-icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="257" preserveAspectRatio="xMidYMid" viewBox="0 0 256 257"><path fill="#D97757" d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"></path></svg>
\ No newline at end of file
diff --git a/apps/marketing/public/harnesses/cursor_light.svg b/apps/marketing/public/harnesses/cursor_light.svg
new file mode 100644
index 00000000000..e61e0be3bfd
--- /dev/null
+++ b/apps/marketing/public/harnesses/cursor_light.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg id="cursor_light__Ebene_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 466.73 532.09"><defs></defs><path class="cursor_light__st0" d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"></path></svg>
\ No newline at end of file
diff --git a/apps/marketing/public/harnesses/openai_dark.svg b/apps/marketing/public/harnesses/openai_dark.svg
new file mode 100644
index 00000000000..b78a51db7bc
--- /dev/null
+++ b/apps/marketing/public/harnesses/openai_dark.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="260" preserveAspectRatio="xMidYMid" viewBox="0 0 256 260"><path fill="#fff" d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z"></path></svg>
\ No newline at end of file
diff --git a/apps/marketing/public/harnesses/opencode-dark.svg b/apps/marketing/public/harnesses/opencode-dark.svg
new file mode 100644
index 00000000000..fc467bf8440
--- /dev/null
+++ b/apps/marketing/public/harnesses/opencode-dark.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="512" height="512"><svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg"><rect width="512" height="512" fill="#131010"></rect><path d="M320 224V352H192V224H320Z" fill="#5A5858"></path><path fill-rule="evenodd" clip-rule="evenodd" d="M384 416H128V96H384V416ZM320 160H192V352H320V160Z" fill="white"></path></svg></svg>
\ No newline at end of file
diff --git a/apps/marketing/public/icon.webp b/apps/marketing/public/icon.webp
new file mode 100644
index 00000000000..aa6826dd36d
Binary files /dev/null and b/apps/marketing/public/icon.webp differ
diff --git a/apps/marketing/public/pfps/BennettBuhner.webp b/apps/marketing/public/pfps/BennettBuhner.webp
new file mode 100644
index 00000000000..39d5af923c5
Binary files /dev/null and b/apps/marketing/public/pfps/BennettBuhner.webp differ
diff --git a/apps/marketing/public/pfps/DavidKPiano.webp b/apps/marketing/public/pfps/DavidKPiano.webp
new file mode 100644
index 00000000000..d6b322bc2c1
Binary files /dev/null and b/apps/marketing/public/pfps/DavidKPiano.webp differ
diff --git a/apps/marketing/public/pfps/Josikinz.webp b/apps/marketing/public/pfps/Josikinz.webp
new file mode 100644
index 00000000000..68d5825222a
Binary files /dev/null and b/apps/marketing/public/pfps/Josikinz.webp differ
diff --git a/apps/marketing/public/pfps/Shay_Benshabtay.webp b/apps/marketing/public/pfps/Shay_Benshabtay.webp
new file mode 100644
index 00000000000..c827f7504c4
Binary files /dev/null and b/apps/marketing/public/pfps/Shay_Benshabtay.webp differ
diff --git a/apps/marketing/public/pfps/_winter_wonders.webp b/apps/marketing/public/pfps/_winter_wonders.webp
new file mode 100644
index 00000000000..8acff2310aa
Binary files /dev/null and b/apps/marketing/public/pfps/_winter_wonders.webp differ
diff --git a/apps/marketing/public/pfps/aronprins.webp b/apps/marketing/public/pfps/aronprins.webp
new file mode 100644
index 00000000000..90db37d28f2
Binary files /dev/null and b/apps/marketing/public/pfps/aronprins.webp differ
diff --git a/apps/marketing/public/pfps/developedbyed.webp b/apps/marketing/public/pfps/developedbyed.webp
new file mode 100644
index 00000000000..8f1dfbab6db
Binary files /dev/null and b/apps/marketing/public/pfps/developedbyed.webp differ
diff --git a/apps/marketing/public/pfps/ex0t1clol.webp b/apps/marketing/public/pfps/ex0t1clol.webp
new file mode 100644
index 00000000000..05bd80e019a
Binary files /dev/null and b/apps/marketing/public/pfps/ex0t1clol.webp differ
diff --git a/apps/marketing/public/pfps/gnukeith.webp b/apps/marketing/public/pfps/gnukeith.webp
new file mode 100644
index 00000000000..aa24d1996ff
Binary files /dev/null and b/apps/marketing/public/pfps/gnukeith.webp differ
diff --git a/apps/marketing/public/pfps/iamkaffe.webp b/apps/marketing/public/pfps/iamkaffe.webp
new file mode 100644
index 00000000000..ded6ed2cd86
Binary files /dev/null and b/apps/marketing/public/pfps/iamkaffe.webp differ
diff --git a/apps/marketing/public/pfps/jetpackjoe_.webp b/apps/marketing/public/pfps/jetpackjoe_.webp
new file mode 100644
index 00000000000..da415598564
Binary files /dev/null and b/apps/marketing/public/pfps/jetpackjoe_.webp differ
diff --git a/apps/marketing/public/pfps/kostyniuk00.webp b/apps/marketing/public/pfps/kostyniuk00.webp
new file mode 100644
index 00000000000..c52f0b305b9
Binary files /dev/null and b/apps/marketing/public/pfps/kostyniuk00.webp differ
diff --git a/apps/marketing/public/pfps/leodev.webp b/apps/marketing/public/pfps/leodev.webp
new file mode 100644
index 00000000000..91a47d5de94
Binary files /dev/null and b/apps/marketing/public/pfps/leodev.webp differ
diff --git a/apps/marketing/public/pfps/mil000.webp b/apps/marketing/public/pfps/mil000.webp
new file mode 100644
index 00000000000..37d784b752c
Binary files /dev/null and b/apps/marketing/public/pfps/mil000.webp differ
diff --git a/apps/marketing/public/pfps/peculiarnewbie.webp b/apps/marketing/public/pfps/peculiarnewbie.webp
new file mode 100644
index 00000000000..74be17008b2
Binary files /dev/null and b/apps/marketing/public/pfps/peculiarnewbie.webp differ
diff --git a/apps/marketing/public/pfps/pocarles.webp b/apps/marketing/public/pfps/pocarles.webp
new file mode 100644
index 00000000000..f259df83124
Binary files /dev/null and b/apps/marketing/public/pfps/pocarles.webp differ
diff --git a/apps/marketing/public/pfps/tannerlinsley.webp b/apps/marketing/public/pfps/tannerlinsley.webp
new file mode 100644
index 00000000000..8ea61b5dd46
Binary files /dev/null and b/apps/marketing/public/pfps/tannerlinsley.webp differ
diff --git a/apps/marketing/public/pfps/teja2495.webp b/apps/marketing/public/pfps/teja2495.webp
new file mode 100644
index 00000000000..457901988d4
Binary files /dev/null and b/apps/marketing/public/pfps/teja2495.webp differ
diff --git a/apps/marketing/public/pfps/uwunetes.webp b/apps/marketing/public/pfps/uwunetes.webp
new file mode 100644
index 00000000000..f15366aa66f
Binary files /dev/null and b/apps/marketing/public/pfps/uwunetes.webp differ
diff --git a/apps/marketing/public/screenshot.jpeg b/apps/marketing/public/screenshot.jpeg
deleted file mode 100644
index 0844b50ad5b..00000000000
Binary files a/apps/marketing/public/screenshot.jpeg and /dev/null differ
diff --git a/apps/marketing/public/screenshot.webp b/apps/marketing/public/screenshot.webp
new file mode 100644
index 00000000000..b9b0703dca0
Binary files /dev/null and b/apps/marketing/public/screenshot.webp differ
diff --git a/apps/marketing/public/updated-screenshot.webp b/apps/marketing/public/updated-screenshot.webp
new file mode 100644
index 00000000000..c245ddb64a1
Binary files /dev/null and b/apps/marketing/public/updated-screenshot.webp differ
diff --git a/apps/marketing/src/components/TuxIcon.astro b/apps/marketing/src/components/TuxIcon.astro
new file mode 100644
index 00000000000..a6f1b4902c6
--- /dev/null
+++ b/apps/marketing/src/components/TuxIcon.astro
@@ -0,0 +1,53 @@
+---
+interface Props {
+  class?: string;
+  idPrefix: string;
+}
+
+const { class: className, idPrefix } = Astro.props;
+---
+
+<svg
+  class={className}
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="0 0 256 295"
+  aria-hidden="true"
+>
+  <defs>
+    <linearGradient id={`${idPrefix}0`} x1="48.548%" x2="51.047%" y1="115.276%" y2="41.364%">
+      <stop offset="0%" stop-color="#FFEED7" />
+      <stop offset="100%" stop-color="#BDBFC2" />
+    </linearGradient>
+    <linearGradient id={`${idPrefix}6`} x1="49.984%" x2="49.984%" y1="89.845%" y2="40.632%">
+      <stop offset="0%" stop-color="#FFEED7" />
+      <stop offset="100%" stop-color="#BDBFC2" />
+    </linearGradient>
+    <linearGradient id={`${idPrefix}8`} x1="49.841%" x2="50.241%" y1="13.229%" y2="94.673%">
+      <stop offset="0%" stop-color="#FFF" stop-opacity=".8" />
+      <stop offset="100%" stop-color="#FFF" stop-opacity="0" />
+    </linearGradient>
+    <linearGradient id={`${idPrefix}c`} x1="53.467%" x2="38.949%" y1="48.921%" y2="98.1%">
+      <stop offset="0%" stop-color="#FFA63F" />
+      <stop offset="100%" stop-color="#FF0" />
+    </linearGradient>
+    <linearGradient id={`${idPrefix}e`} x1="30.581%" x2="65.887%" y1="34.024%" y2="89.175%">
+      <stop offset="0%" stop-color="#FFA63F" />
+      <stop offset="100%" stop-color="#FF0" />
+    </linearGradient>
+    <linearGradient id={`${idPrefix}i`} x1="49.733%" x2="50.558%" y1="17.609%" y2="99.385%">
+      <stop offset="0%" stop-color="#FFA63F" />
+      <stop offset="100%" stop-color="#FF0" />
+    </linearGradient>
+  </defs>
+  <g fill="none">
+    <path fill="#000" d="M63.213 215.474c-11.387-16.346-13.591-69.606 12.947-102.39C89.292 97.383 92.69 86.455 93.7 71.67c.734-16.805-11.846-66.851 35.537-70.616 48.027-3.857 45.364 43.526 45.088 68.596-.183 21.12 15.52 33.15 26.355 49.68 19.927 30.303 18.274 82.461-3.765 110.745-27.916 35.354-51.791 20.018-67.678 21.304-29.752 1.745-30.762 17.54-66.024-35.905" />
+    <path fill={`url(#${idPrefix}6)`} d="M81.027 145.684c6.52-14.785 20.386-40.772 20.662-60.883 0-15.978 47.843-19.835 51.7-3.856 3.856 15.978 13.59 39.853 19.834 51.424 6.245 11.478 24.335 48.118 5.051 80.074-17.356 28.284-69.973 50.69-98.073-3.856-9.55-18.917-7.806-42.333.826-62.903" />
+    <path fill={`url(#${idPrefix}8)`} d="M166.428 151.285c0 16.162-15.519 37.1-42.15 36.916-27.456.183-39.118-20.754-39.118-36.916 0-16.161 18.182-29.293 40.588-29.293 22.498.092 40.68 13.132 40.68 29.293" />
+    <path fill="#000" stroke="#000" stroke-width=".977" d="M176.805 117.86c13.59 11.02 38.292 49.587 2.204 74.748-11.846 7.806 10.468 32.508 23.049 19.927 43.618-43.894-1.102-94.308-16.53-111.664-13.774-15.151-25.987 3.49-8.723 16.989z" />
+    <path fill="#000" stroke="#000" stroke-width="1.25" d="M79.925 122.727c-8.907 14.509-30.211 48.669-1.652 66.484 38.384 23.6 27.548 47.108-7.53 25.895-49.404-29.568-5.97-89.257 13.774-112.03 22.59-25.529 4.316 4.683-4.592 19.65z" />
+    <path fill={`url(#${idPrefix}c)`} stroke="#E68C3F" stroke-width="6.25" d="M51.835 258.542c-20.57-10.928-50.414 2.112-39.578-27.457 2.204-6.704-3.214-16.805.275-23.325 4.133-7.989 13.04-6.244 18.366-11.57 5.234-5.51 8.54-15.06 18.366-13.59 9.734 1.468 16.254 13.406 23.049 28.099 5.05 10.468 22.865 25.253 21.672 37.007-1.47 17.998-21.948 21.396-42.15 10.836z" transform="translate(10)" />
+    <path fill={`url(#${idPrefix}e)`} stroke="#E68C3F" stroke-width="6.251" d="M194.445 253.49c15.06-18.273 48.578-14.508 25.988-39.577-4.775-5.418-3.306-16.989-9.183-21.947-6.887-6.061-14.509-1.102-21.488-4.224-6.979-3.398-14.325-9.918-22.865-5.327-8.54 4.684-9.459 16.805-10.285 32.783-.735 11.479-11.203 30.671-5.602 41.231 8.081 16.346 29.11 14.142 43.435-2.938z" transform="translate(10)" />
+    <path fill={`url(#${idPrefix}i)`} stroke="#E68C3F" stroke-width="3.75" d="M97.107 66.344c3.673-3.398 12.58-13.774 29.477-2.939 3.122 2.02 5.693 2.204 11.662 4.775 12.03 4.96 6.336 16.897-6.52 20.937-5.51 1.745-10.468 8.449-20.386 7.806-8.54-.46-10.744-6.06-15.978-9.091-9.275-5.234-10.652-12.305-5.602-16.07 5.051-3.765 6.98-5.143 7.347-5.418z" transform="translate(10)" />
+    <path fill="#000" d="M133.186 57.712c-.092 5.234 2.48 9.458 5.877 9.458 3.306 0 6.153-4.224 6.245-9.366.091-5.234-2.48-9.459-5.878-9.459-3.397 0-6.152 4.225-6.244 9.367m-21.212.092c.459 4.316-1.194 7.989-3.582 8.356-2.387.276-4.683-2.938-5.142-7.254-.46-4.316 1.194-7.99 3.581-8.357 2.388-.275 4.684 2.939 5.143 7.255" />
+  </g>
+</svg>
diff --git a/apps/marketing/src/layouts/Layout.astro b/apps/marketing/src/layouts/Layout.astro
index b4fa945e25a..e60637cbfd1 100644
--- a/apps/marketing/src/layouts/Layout.astro
+++ b/apps/marketing/src/layouts/Layout.astro
@@ -6,7 +6,7 @@ interface Props {
 
 const {
   title = "T3 Code",
-  description = "T3 Code — The best way to code with AI.",
+  description = "T3 Code — The open-source control plane for coding agents.",
 } = Astro.props;
 ---
 
@@ -18,7 +18,7 @@ const {
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link
-      href="https://fonts.googleapis.com/css2?family=DM+Sans:opsz,wght@9..40,400;9..40,500;9..40,600&display=swap"
+      href="https://fonts.googleapis.com/css2?family=DM+Sans:opsz,wght@9..40,400;9..40,500;9..40,600&family=JetBrains+Mono:wght@400;500&display=swap"
       rel="stylesheet"
     />
     <link rel="icon" href="/favicon.ico" sizes="48x48" />
@@ -30,18 +30,25 @@ const {
   <body>
     <div class="page">
       <nav class="nav">
-        <a href="/" class="nav-brand">
-          <img src="/icon.png" alt="T3" class="nav-icon" />
-        </a>
-        <a
-          href="https://github.com/pingdotgg/t3code"
-          target="_blank"
-          rel="noopener noreferrer"
-          class="nav-github"
-        >
-          GitHub
-          <span class="nav-github-arrow" aria-hidden="true">&#8599;</span>
-        </a>
+        <div class="nav-inner">
+          <a href="/" class="nav-brand" aria-label="T3 Code home">
+            <span class="nav-brand-name">T3 Code</span>
+          </a>
+          <div class="nav-right">
+            <a
+              class="nav-gh"
+              href="https://github.com/pingdotgg/t3code"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                <path d="M12 .5C5.65.5.5 5.65.5 12a11.5 11.5 0 007.86 10.93c.58.1.79-.25.79-.56v-2c-3.2.69-3.88-1.37-3.88-1.37-.52-1.33-1.27-1.69-1.27-1.69-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.02 1.76 2.68 1.25 3.33.96.1-.75.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.67 0-1.25.45-2.28 1.18-3.08-.12-.29-.51-1.45.11-3.02 0 0 .96-.31 3.15 1.18a10.96 10.96 0 015.74 0c2.19-1.49 3.15-1.18 3.15-1.18.62 1.57.23 2.73.11 3.02.74.8 1.18 1.83 1.18 3.08 0 4.41-2.7 5.38-5.27 5.66.41.36.78 1.06.78 2.13v3.16c0 .31.21.67.8.56A11.5 11.5 0 0023.5 12C23.5 5.65 18.35.5 12 .5z"/>
+              </svg>
+              <span>GitHub</span>
+            </a>
+            <a class="btn btn-primary" href="/#download">Download</a>
+          </div>
+        </div>
       </nav>
 
       <main class="main">
@@ -49,23 +56,54 @@ const {
       </main>
 
       <footer class="footer">
-        <span class="footer-copy">&copy; {new Date().getFullYear()} T3 Tools Inc</span>
-        <div class="footer-links">
-          <a href="https://github.com/pingdotgg/t3code" target="_blank" rel="noopener noreferrer">GitHub</a>
-          <a href="https://discord.gg/jn4EGJjrvv" target="_blank" rel="noopener noreferrer">Discord</a>
+        <div class="footer-inner">
+          <div class="footer-brand">
+            <img src="/icon.webp" alt="" />
+            <span>&copy; {new Date().getFullYear()} T3 Tools Inc · MIT licensed</span>
+          </div>
+          <div class="footer-links">
+            <a href="https://github.com/pingdotgg/t3code" target="_blank" rel="noopener noreferrer">GitHub</a>
+            <a href="https://discord.gg/jn4EGJjrvv" target="_blank" rel="noopener noreferrer">Discord</a>
+            <a href="/download">Download</a>
+          </div>
         </div>
       </footer>
     </div>
+
+    <script>
+      const nav = document.querySelector(".nav");
+      const onScroll = () => {
+        if (!nav) return;
+        if (window.scrollY > 12) nav.classList.add("is-scrolled");
+        else nav.classList.remove("is-scrolled");
+      };
+      window.addEventListener("scroll", onScroll, { passive: true });
+      onScroll();
+    </script>
   </body>
 </html>
 
 <style is:global>
   :root {
     --bg: #09090b;
+    --bg-elev: #0c0c0e;
+    --bg-card: #111113;
     --fg: #fafafa;
     --fg-muted: #a1a1aa;
     --fg-dim: #71717a;
+    --fg-faint: #52525b;
     --border: rgba(255, 255, 255, 0.08);
+    --border-strong: rgba(255, 255, 255, 0.14);
+    --accent-h: 250;
+    --accent: oklch(0.68 0.17 var(--accent-h));
+    --accent-dim: oklch(0.68 0.17 var(--accent-h) / 0.15);
+    --ok: oklch(0.72 0.16 150);
+    --warn: oklch(0.76 0.15 75);
+    --font-sans: "DM Sans", -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    --font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, monospace;
+    --radius: 12px;
+    --radius-sm: 8px;
+    --radius-lg: 16px;
   }
 
   * {
@@ -76,16 +114,19 @@ const {
 
   html {
     color-scheme: dark;
+    scroll-behavior: smooth;
   }
 
   body {
     background: var(--bg);
     color: var(--fg);
-    font-family: "DM Sans", -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+    font-family: var(--font-sans);
+    font-feature-settings: "ss01", "ss02";
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
     min-height: 100vh;
     overflow-x: hidden;
+    line-height: 1.5;
   }
 
   body::after {
@@ -105,11 +146,103 @@ const {
     text-decoration: none;
   }
 
-  img {
+  button {
+    font-family: inherit;
+    cursor: pointer;
+    border: 0;
+    background: none;
+    color: inherit;
+  }
+
+  img,
+  svg {
     display: block;
     max-width: 100%;
   }
 
+  .eyebrow {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--fg-dim);
+    font-weight: 500;
+  }
+
+  .display {
+    font-weight: 500;
+    letter-spacing: -0.035em;
+    line-height: 1.05;
+  }
+
+  .container {
+    width: 100%;
+    max-width: 1240px;
+    margin: 0 auto;
+    padding: 0 32px;
+  }
+
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    font-weight: 500;
+    font-size: 14px;
+    padding: 10px 18px;
+    border-radius: 8px;
+    transition: transform 0.18s ease, background 0.18s ease,
+      border-color 0.18s ease, color 0.18s ease;
+    white-space: nowrap;
+  }
+
+  .btn-primary {
+    background: var(--fg);
+    color: #09090b;
+    font-weight: 600;
+  }
+
+  .btn-primary:hover {
+    transform: translateY(-1px);
+    background: #fff;
+  }
+
+  .btn-primary:active {
+    transform: translateY(0);
+  }
+
+  .btn-ghost {
+    color: var(--fg-muted);
+    border: 1px solid var(--border);
+    background: transparent;
+  }
+
+  .btn-ghost:hover {
+    color: var(--fg);
+    border-color: var(--border-strong);
+    background: rgba(255, 255, 255, 0.02);
+  }
+
+  .btn-lg {
+    padding: 14px 22px;
+    font-size: 15px;
+    border-radius: 10px;
+  }
+
+  .tile {
+    position: relative;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    background: linear-gradient(180deg, rgba(255, 255, 255, 0.015), rgba(255, 255, 255, 0));
+    overflow: hidden;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+    border-radius: 4px;
+  }
+
   @keyframes fade-in {
     from {
       opacity: 0;
@@ -120,11 +253,26 @@ const {
       transform: translateY(0);
     }
   }
+
+  @keyframes pulse {
+    50% { opacity: 0.4; }
+  }
+
+  @keyframes spin {
+    to { transform: rotate(360deg); }
+  }
+
+  @keyframes floatDrift {
+    0%, 100% { translate: 0 0; }
+    50%      { translate: 0 -10px; }
+  }
+
+  @keyframes blink {
+    50% { opacity: 0; }
+  }
 </style>
 
 <style>
-  /* ── Page ── */
-
   .page {
     min-height: 100vh;
     display: flex;
@@ -132,97 +280,131 @@ const {
     overflow-x: hidden;
   }
 
-  /* ── Navbar ── */
-
   .nav {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 1.5rem 2.5rem;
-    opacity: 0.5;
-    transition: opacity 0.4s ease;
+    position: sticky;
+    top: 0;
+    z-index: 50;
+    backdrop-filter: blur(18px);
+    -webkit-backdrop-filter: blur(18px);
+    background: color-mix(in srgb, var(--bg) 75%, transparent);
+    border-bottom: 1px solid transparent;
+    transition: border-color 0.3s ease;
   }
 
-  .nav:hover {
-    opacity: 1;
+  .nav.is-scrolled {
+    border-bottom-color: var(--border);
   }
 
-  .nav-brand {
+  .nav-inner {
+    max-width: 1240px;
+    margin: 0 auto;
+    padding: 12px 32px;
     display: flex;
     align-items: center;
+    justify-content: space-between;
+    gap: 24px;
   }
 
-  .nav-icon {
-    width: 28px;
-    height: 28px;
-    border-radius: 6px;
+  .nav-brand {
+    display: inline-flex;
+    align-items: center;
+    color: var(--fg);
+    transition: color 0.2s ease;
   }
 
-  .nav-github {
-    display: flex;
-    align-items: center;
-    gap: 0.35rem;
-    color: var(--fg-muted);
-    font-size: 0.875rem;
-    transition: color 0.3s ease;
+  .nav-brand:hover {
+    color: #fff;
   }
 
-  .nav-github:hover {
-    color: var(--fg);
+  .nav-brand-name {
+    font-size: 16px;
+    font-weight: 650;
+    letter-spacing: -0.025em;
+    line-height: 1;
   }
 
-  .nav-github-arrow {
-    display: inline-block;
-    transition: transform 0.3s ease;
+  .nav-right {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
   }
 
-  .nav-github:hover .nav-github-arrow {
-    transform: translateX(2px) translateY(-1px);
+  .nav-gh {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 7px 12px;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    color: var(--fg-muted);
+    font-family: var(--font-mono);
+    font-size: 12px;
+    transition: color 0.2s ease, background 0.2s ease, border-color 0.2s ease;
   }
 
-  /* ── Main content ── */
+  .nav-gh:hover {
+    color: var(--fg);
+    background: rgba(255, 255, 255, 0.04);
+    border-color: var(--border-strong);
+  }
 
   .main {
     flex: 1;
     display: flex;
     flex-direction: column;
-    align-items: center;
   }
 
-  /* ── Footer ── */
-
   .footer {
+    margin-top: auto;
+    border-top: 1px solid var(--border);
+    padding: 40px 0 32px;
+  }
+
+  .footer-inner {
+    max-width: 1240px;
+    margin: 0 auto;
+    padding: 0 32px;
     display: flex;
+    flex-wrap: wrap;
+    gap: 24px;
     align-items: center;
     justify-content: space-between;
-    padding: 1.5rem 2.5rem;
-    font-size: 0.8rem;
+  }
+
+  .footer-brand {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    font-size: 13px;
     color: var(--fg-dim);
   }
 
+  .footer-brand img {
+    width: 20px;
+    height: 20px;
+    border-radius: 4px;
+  }
+
   .footer-links {
     display: flex;
-    gap: 1.25rem;
+    gap: 20px;
   }
 
   .footer-links a {
+    font-size: 13px;
     color: var(--fg-dim);
-    transition: color 0.3s ease;
+    transition: color 0.2s ease;
   }
 
   .footer-links a:hover {
     color: var(--fg);
   }
 
-  /* ── Mobile ── */
-
-  @media (max-width: 640px) {
-    .nav {
-      padding: 1.25rem;
-    }
-
-    .footer {
-      padding: 1.25rem;
+  @media (max-width: 820px) {
+    .nav-inner,
+    .footer-inner {
+      padding-left: 20px;
+      padding-right: 20px;
     }
   }
 </style>
diff --git a/apps/marketing/src/lib/tweets.ts b/apps/marketing/src/lib/tweets.ts
new file mode 100644
index 00000000000..7d6be71c5f1
--- /dev/null
+++ b/apps/marketing/src/lib/tweets.ts
@@ -0,0 +1,123 @@
+export type Tweet = {
+  handle: string;
+  content: string;
+  excerpt?: string;
+  link: string;
+};
+
+export const tweets = [
+  {
+    handle: "Shay_Benshabtay",
+    content:
+      "T3 code is not perfect, but it's damn good. Open and fun , I can make my own fork for my uses and use the great tooling with my own needs.",
+    link: "https://x.com/Shay_Benshabtay/status/2054668503857156326",
+  },
+  {
+    handle: "teja2495",
+    content:
+      "I’ve completely switched to T3 Code for all my workflows. I just switch between different subscriptions and harnesses depending on what I need.",
+    excerpt: "I’ve completely switched to T3 Code for all my workflows.",
+    link: "https://x.com/teja2495/status/2052420254991581623",
+  },
+  {
+    handle: "developedbyed",
+    content: "might say alpha but T3 code is pretty awesome, really fast too",
+    link: "https://x.com/developedbyed/status/2030627970532921605",
+  },
+  {
+    handle: "tannerlinsley",
+    content:
+      "The minute T3 Code supports Claude Code, it could potentially become my daily driver. There's something special there.",
+    link: "https://x.com/tannerlinsley/status/2031102771529920966",
+  },
+  {
+    handle: "aronprins",
+    content:
+      "I already loved T3 Code by @theo and @jullerino, but their Connections implementation is next level epic and for this they should both earn maximum repect 🔥🫡",
+    excerpt: "I already loved T3 Code, but their Connections implementation is next level epic.",
+    link: "https://x.com/aronprins/status/2045102518196183109",
+  },
+  {
+    handle: "BennettBuhner",
+    content:
+      "T3 Code is literally Codex but better; all your favorite models and harnesses, accessible anywhere! The app is great but the website is even greater, so instead of needing to SSH into a machine, T3 IS my SSH!",
+    excerpt:
+      "T3 Code is literally Codex but better; all your favorite models and harnesses, accessible anywhere.",
+    link: "https://x.com/BennettBuhner/status/2054667115697754387",
+  },
+  {
+    handle: "ex0t1clol",
+    content: "T3 Code is proof electron apps don't have to suck",
+    link: "https://x.com/ex0t1clol/status/2054666870008021197",
+  },
+  {
+    handle: "Josikinz",
+    content:
+      "T3 code is better because it’s like if the codex Mac app didn’t make my computer run like shit 😋",
+    link: "https://x.com/Josikinz/status/2030367951694745870",
+  },
+  {
+    handle: "jetpackjoe_",
+    content: "T3 code is pretty alright I guess",
+    link: "https://x.com/jetpackjoe_/status/2054666792933404959",
+  },
+  {
+    handle: "mil000",
+    content: "T3 code saved my relationship!",
+    link: "https://x.com/mil000/status/2030120041451246071",
+  },
+  {
+    handle: "_winter_wonders",
+    content: "Heartbreaking: AI-hater has to admit T3 Code is really good.",
+    link: "https://x.com/_winter_wonders/status/2052350198764970434",
+  },
+  {
+    handle: "kostyniuk00",
+    content:
+      "I was not expecting a year ago, that my anti-AI colleagues would thank me a year later, for persuading them to try T3 Code Beta, that really helped them with organizing their workflows. \n\nFantastic product by @jullerino and @theo. Go try it out if you haven’t yet!",
+    excerpt:
+      "My anti-AI colleagues thanked me for persuading them to try T3 Code Beta. Fantastic product.",
+    link: "https://x.com/kostyniuk00/status/2052041388179468521",
+  },
+  {
+    handle: "gnukeith",
+    content:
+      "I tried T3 Code it actually fixed issues that Opus couldn’t solve in Claude Code + Theo has replied with “UwU” under my post. Dario has not.",
+    link: "https://x.com/gnukeith/status/2054670073579630730",
+  },
+  {
+    handle: "peculiarnewbie",
+    content: "T3 Code is iOS and other harnesses are androids",
+    link: "https://x.com/peculiarnewbie/status/2054671685027233827",
+  },
+  {
+    handle: "leodev",
+    content:
+      "T3 Code is probably the first coding gui that didn't suck performance wise and had a smart team behind it.",
+    link: "https://x.com/leodev/status/2054679746353537042",
+  },
+  {
+    handle: "pocarles",
+    content:
+      "Only using Codex and T3 now.\n\nI thought all AI coding harnesses had roughly the same impact. Using T3 Code taught me how wrong I was. The interface between you and the model changes everything.",
+    excerpt:
+      "Using T3 Code taught me how wrong I was. The interface between you and the model changes everything.",
+    link: "https://x.com/pocarles/status/2054673964274758046",
+  },
+  {
+    handle: "DavidKPiano",
+    content: "It's like Claude Code if they didn't vibe-code the entire thing",
+    link: "https://x.com/DavidKPiano/status/2054682983504719930",
+  },
+  {
+    handle: "iamkaffe",
+    content: "T3Code was the first one to truly care about Linux users.",
+    link: "https://x.com/iamkaffe/status/2054675539311411280",
+  },
+  {
+    handle: "uwunetes",
+    content:
+      "claude code make me go *whine whine whine* and t3 code make me go woof woof awooooo!!!",
+    link: "https://x.com/uwunetes/status/2054683356022120640",
+  },
+] satisfies Tweet[];
diff --git a/apps/marketing/src/pages/download.astro b/apps/marketing/src/pages/download.astro
index 54454d40264..b9e0e0181e4 100644
--- a/apps/marketing/src/pages/download.astro
+++ b/apps/marketing/src/pages/download.astro
@@ -4,6 +4,7 @@ import { RELEASES_URL } from "../lib/releases";
 ---
 
 <Layout title="Download — T3 Code" description="Download T3 Code for macOS, Windows, or Linux.">
+  <div class="download-page">
   <h1 class="heading">Download T3 Code</h1>
   <p class="subheading">
     <span id="version-label">Loading latest release&hellip;</span>
@@ -64,6 +65,7 @@ import { RELEASES_URL } from "../lib/releases";
       GitHub releases page<span aria-hidden="true"> &#8599;</span>
     </a>
   </p>
+  </div>
 </Layout>
 
 <script>
@@ -111,7 +113,11 @@ import { RELEASES_URL } from "../lib/releases";
 </script>
 
 <style>
-  .main {
+  .download-page {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
     padding: 8vh 1.5rem 4rem;
   }
 
@@ -257,7 +263,7 @@ import { RELEASES_URL } from "../lib/releases";
   /* ── Mobile ── */
 
   @media (max-width: 640px) {
-    .main {
+    .download-page {
       padding: 5vh 1.25rem 4rem;
     }
 
diff --git a/apps/marketing/src/pages/index.astro b/apps/marketing/src/pages/index.astro
index 3a2111f4f88..a864c169924 100644
--- a/apps/marketing/src/pages/index.astro
+++ b/apps/marketing/src/pages/index.astro
@@ -1,26 +1,372 @@
 ---
 import Layout from "../layouts/Layout.astro";
+import TuxIcon from "../components/TuxIcon.astro";
+import { tweets } from "../lib/tweets";
+
+const desktopEndorsementRows = [
+  tweets.filter((_, index) => index % 2 === 0),
+  tweets.filter((_, index) => index % 2 === 1),
+];
+
+const mobileEndorsementRows = [
+  tweets.filter((_, index) => index % 3 === 0),
+  tweets.filter((_, index) => index % 3 === 1),
+  tweets.filter((_, index) => index % 3 === 2),
+];
 ---
 
 <Layout>
-  <h1 class="tagline">T3 Code is the best way to code with AI.</h1>
-
-  <a
-    id="download-btn"
-    href="https://github.com/pingdotgg/t3code/releases"
-    class="hero-button"
-  >
-    <svg class="hero-button-icon hero-button-icon--apple" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 814 1000" aria-hidden="true"><path fill="currentColor" d="M788.1 340.9c-5.8 4.5-108.2 62.2-108.2 190.5 0 148.4 130.3 200.9 134.2 202.2-.6 3.2-20.7 71.9-68.7 141.9-42.8 61.6-87.5 123.1-155.5 123.1s-85.5-39.5-164-39.5c-76.5 0-103.7 40.8-165.9 40.8s-105.6-57-155.5-127C46.7 790.7 0 663 0 541.8c0-194.4 126.4-297.5 250.8-297.5 66.1 0 121.2 43.4 162.7 43.4 39.5 0 101.1-46 176.3-46 28.5 0 130.9 2.6 198.3 99.2zm-234-181.5c31.1-36.9 53.1-88.1 53.1-139.3 0-7.1-.6-14.3-1.9-20.1-50.6 1.9-110.8 33.7-147.1 75.8-28.5 32.4-55.1 83.6-55.1 135.5 0 7.8 1.3 15.6 1.9 18.1 3.2.6 8.4 1.3 13.6 1.3 45.4 0 102.5-30.4 135.5-71.3z"/></svg>
-    <svg class="hero-button-icon hero-button-icon--windows" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 88 88" aria-hidden="true"><path fill="currentColor" d="m0 12.402 35.687-4.86.016 34.423-35.67.203zm35.67 33.529.028 34.453L.028 75.48.026 45.7zm4.326-39.025L87.314 0v41.527l-47.318.376zm47.329 39.349-.011 41.34-47.318-6.678-.066-34.739z"/></svg>
-    <svg class="hero-button-icon hero-button-icon--linux" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 295" aria-hidden="true"><defs><linearGradient id="lt0" x1="48.548%" x2="51.047%" y1="115.276%" y2="41.364%"><stop offset="0%" stop-color="#FFEED7"/><stop offset="100%" stop-color="#BDBFC2"/></linearGradient><linearGradient id="lt6" x1="49.984%" x2="49.984%" y1="89.845%" y2="40.632%"><stop offset="0%" stop-color="#FFEED7"/><stop offset="100%" stop-color="#BDBFC2"/></linearGradient><linearGradient id="lt8" x1="49.841%" x2="50.241%" y1="13.229%" y2="94.673%"><stop offset="0%" stop-color="#FFF" stop-opacity=".8"/><stop offset="100%" stop-color="#FFF" stop-opacity="0"/></linearGradient><linearGradient id="ltc" x1="53.467%" x2="38.949%" y1="48.921%" y2="98.1%"><stop offset="0%" stop-color="#FFA63F"/><stop offset="100%" stop-color="#FF0"/></linearGradient><linearGradient id="lte" x1="30.581%" x2="65.887%" y1="34.024%" y2="89.175%"><stop offset="0%" stop-color="#FFA63F"/><stop offset="100%" stop-color="#FF0"/></linearGradient><linearGradient id="lti" x1="49.733%" x2="50.558%" y1="17.609%" y2="99.385%"><stop offset="0%" stop-color="#FFA63F"/><stop offset="100%" stop-color="#FF0"/></linearGradient></defs><g fill="none"><path fill="#000" d="M63.213 215.474c-11.387-16.346-13.591-69.606 12.947-102.39C89.292 97.383 92.69 86.455 93.7 71.67c.734-16.805-11.846-66.851 35.537-70.616 48.027-3.857 45.364 43.526 45.088 68.596-.183 21.12 15.52 33.15 26.355 49.68 19.927 30.303 18.274 82.461-3.765 110.745-27.916 35.354-51.791 20.018-67.678 21.304-29.752 1.745-30.762 17.54-66.024-35.905"/><path fill="url(#lt6)" d="M81.027 145.684c6.52-14.785 20.386-40.772 20.662-60.883 0-15.978 47.843-19.835 51.7-3.856 3.856 15.978 13.59 39.853 19.834 51.424 6.245 11.478 24.335 48.118 5.051 80.074-17.356 28.284-69.973 50.69-98.073-3.856-9.55-18.917-7.806-42.333.826-62.903"/><path fill="url(#lt8)" d="M166.428 151.285c0 16.162-15.519 37.1-42.15 36.916-27.456.183-39.118-20.754-39.118-36.916 0-16.161 18.182-29.293 40.588-29.293 22.498.092 40.68 13.132 40.68 29.293"/><path fill="#000" stroke="#000" stroke-width=".977" d="M176.805 117.86c13.59 11.02 38.292 49.587 2.204 74.748-11.846 7.806 10.468 32.508 23.049 19.927 43.618-43.894-1.102-94.308-16.53-111.664-13.774-15.151-25.987 3.49-8.723 16.989z"/><path fill="#000" stroke="#000" stroke-width="1.25" d="M79.925 122.727c-8.907 14.509-30.211 48.669-1.652 66.484 38.384 23.6 27.548 47.108-7.53 25.895-49.404-29.568-5.97-89.257 13.774-112.03 22.59-25.529 4.316 4.683-4.592 19.65z"/><path fill="url(#ltc)" stroke="#E68C3F" stroke-width="6.25" d="M51.835 258.542c-20.57-10.928-50.414 2.112-39.578-27.457 2.204-6.704-3.214-16.805.275-23.325 4.133-7.989 13.04-6.244 18.366-11.57 5.234-5.51 8.54-15.06 18.366-13.59 9.734 1.468 16.254 13.406 23.049 28.099 5.05 10.468 22.865 25.253 21.672 37.007-1.47 17.998-21.948 21.396-42.15 10.836z" transform="translate(10)"/><path fill="url(#lte)" stroke="#E68C3F" stroke-width="6.251" d="M194.445 253.49c15.06-18.273 48.578-14.508 25.988-39.577-4.775-5.418-3.306-16.989-9.183-21.947-6.887-6.061-14.509-1.102-21.488-4.224-6.979-3.398-14.325-9.918-22.865-5.327-8.54 4.684-9.459 16.805-10.285 32.783-.735 11.479-11.203 30.671-5.602 41.231 8.081 16.346 29.11 14.142 43.435-2.938z" transform="translate(10)"/><path fill="url(#lti)" stroke="#E68C3F" stroke-width="3.75" d="M97.107 66.344c3.673-3.398 12.58-13.774 29.477-2.939 3.122 2.02 5.693 2.204 11.662 4.775 12.03 4.96 6.336 16.897-6.52 20.937-5.51 1.745-10.468 8.449-20.386 7.806-8.54-.46-10.744-6.06-15.978-9.091-9.275-5.234-10.652-12.305-5.602-16.07 5.051-3.765 6.98-5.143 7.347-5.418z" transform="translate(10)"/><path fill="#000" d="M133.186 57.712c-.092 5.234 2.48 9.458 5.877 9.458 3.306 0 6.153-4.224 6.245-9.366.091-5.234-2.48-9.459-5.878-9.459-3.397 0-6.152 4.225-6.244 9.367m-21.212.092c.459 4.316-1.194 7.989-3.582 8.356-2.387.276-4.683-2.938-5.142-7.254-.46-4.316 1.194-7.99 3.581-8.357 2.388-.275 4.684 2.939 5.143 7.255"/></g></svg>
-    <span id="download-label">Download now</span>
-  </a>
-
-  <a href="/download" class="other-platforms">Other platforms</a>
-
-  <div class="screenshot-wrap">
-    <img src="/screenshot.jpeg" alt="T3 Code" class="screenshot" />
-  </div>
+  <!-- ── Hero ──────────────────────────────────────────────────── -->
+  <section class="hero">
+    <div class="hero-grid" aria-hidden="true"></div>
+
+    <div class="hero-float" aria-hidden="true">
+      <span class="hero-float-mark hf-claude" title="Claude Code">
+        <img src="/harnesses/claude-ai-icon.svg" alt="" />
+      </span>
+      <span class="hero-float-mark hf-codex" title="Codex">
+        <img src="/harnesses/openai_dark.svg" alt="" />
+      </span>
+      <span class="hero-float-mark hf-opencode" title="OpenCode">
+        <img src="/harnesses/opencode-dark.svg" alt="" />
+      </span>
+      <span class="hero-float-mark hf-cursor" title="Cursor">
+        <img src="/harnesses/cursor_light.svg" alt="" />
+      </span>
+    </div>
+
+    <div class="container hero-inner">
+      <h1 class="hero-title display">
+        The open-source<br />control plane<br />for coding agents.
+      </h1>
+
+      <p class="hero-sub">
+        Orchestrate Claude Code, Codex, OpenCode and Cursor from one surface.
+        Bring your own subscription. Fork the whole thing.
+      </p>
+
+      <div class="hero-actions">
+        <a
+          id="download-btn"
+          href="https://github.com/pingdotgg/t3code/releases"
+          class="btn btn-primary btn-lg"
+        >
+          <svg class="dl-icon dl-icon--apple" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 814 1000" aria-hidden="true"><path fill="currentColor" d="M788.1 340.9c-5.8 4.5-108.2 62.2-108.2 190.5 0 148.4 130.3 200.9 134.2 202.2-.6 3.2-20.7 71.9-68.7 141.9-42.8 61.6-87.5 123.1-155.5 123.1s-85.5-39.5-164-39.5c-76.5 0-103.7 40.8-165.9 40.8s-105.6-57-155.5-127C46.7 790.7 0 663 0 541.8c0-194.4 126.4-297.5 250.8-297.5 66.1 0 121.2 43.4 162.7 43.4 39.5 0 101.1-46 176.3-46 28.5 0 130.9 2.6 198.3 99.2zm-234-181.5c31.1-36.9 53.1-88.1 53.1-139.3 0-7.1-.6-14.3-1.9-20.1-50.6 1.9-110.8 33.7-147.1 75.8-28.5 32.4-55.1 83.6-55.1 135.5 0 7.8 1.3 15.6 1.9 18.1 3.2.6 8.4 1.3 13.6 1.3 45.4 0 102.5-30.4 135.5-71.3z"/></svg>
+          <svg class="dl-icon dl-icon--windows" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 88 88" aria-hidden="true"><path fill="currentColor" d="m0 12.402 35.687-4.86.016 34.423-35.67.203zm35.67 33.529.028 34.453L.028 75.48.026 45.7zm4.326-39.025L87.314 0v41.527l-47.318.376zm47.329 39.349-.011 41.34-47.318-6.678-.066-34.739z"/></svg>
+          <TuxIcon class="dl-icon dl-icon--linux" idPrefix="hero-linux-" />
+          <span id="download-label">Download for macOS</span>
+        </a>
+        <a href="https://github.com/pingdotgg/t3code" target="_blank" rel="noopener noreferrer" class="btn btn-ghost btn-lg">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+            <path d="M12 .5C5.65.5.5 5.65.5 12a11.5 11.5 0 007.86 10.93c.58.1.79-.25.79-.56v-2c-3.2.69-3.88-1.37-3.88-1.37-.52-1.33-1.27-1.69-1.27-1.69-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.02 1.76 2.68 1.25 3.33.96.1-.75.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.67 0-1.25.45-2.28 1.18-3.08-.12-.29-.51-1.45.11-3.02 0 0 .96-.31 3.15 1.18a10.96 10.96 0 015.74 0c2.19-1.49 3.15-1.18 3.15-1.18.62 1.57.23 2.73.11 3.02.74.8 1.18 1.83 1.18 3.08 0 4.41-2.7 5.38-5.27 5.66.41.36.78 1.06.78 2.13v3.16c0 .31.21.67.8.56A11.5 11.5 0 0023.5 12C23.5 5.65 18.35.5 12 .5z"/>
+          </svg>
+          Star on GitHub
+        </a>
+      </div>
+
+      <div class="hero-preview">
+        <figure class="hero-screenshot-frame">
+          <img
+            src="/updated-screenshot.webp"
+            alt="T3 Code app showing multiple coding agent threads in one workspace"
+            width="2508"
+            height="1682"
+            loading="eager"
+            decoding="async"
+          />
+        </figure>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Endorsements ─────────────────────────────────────────── -->
+  <section id="endorsements" class="sec-endorsements" aria-labelledby="endorsements-title">
+    <div class="container">
+      <div class="endorsements-head">
+        <h2 id="endorsements-title">Developers love T3 Code</h2>
+        <p>Real reactions from people building with T3 Code today.</p>
+      </div>
+    </div>
+
+    <div class="endorsement-carousel endorsement-carousel--desktop" aria-label="Developer endorsements">
+        {
+          desktopEndorsementRows.map((row, rowIndex) => (
+            <div class:list={["endorsement-row", rowIndex === 1 && "is-reverse"]}>
+              <div class="endorsement-track">
+                {[0, 1].map((groupIndex) => (
+                  <div class="endorsement-track-group" aria-hidden={groupIndex === 1 ? "true" : undefined}>
+                    {row.map((tweet) => (
+                      <a
+                        class="endorsement-card"
+                        href={tweet.link}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        aria-label={`Read ${tweet.handle}'s post on X`}
+                        tabindex={groupIndex === 1 ? "-1" : undefined}
+                      >
+                        <div class="endorsement-author">
+                          <img
+                            src={`/pfps/${tweet.handle}.webp`}
+                            alt=""
+                            width="28"
+                            height="28"
+                            loading="lazy"
+                            decoding="async"
+                          />
+                          <div class="endorsement-handle">@{tweet.handle}</div>
+                        </div>
+                        <p>{tweet.excerpt ?? tweet.content}</p>
+                      </a>
+                    ))}
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))
+        }
+    </div>
+
+    <div class="endorsement-carousel endorsement-carousel--mobile" aria-label="Developer endorsements">
+        {
+          mobileEndorsementRows.map((row, rowIndex) => (
+            <div class:list={["endorsement-row", rowIndex === 1 && "is-reverse"]}>
+              <div class="endorsement-track">
+                {[0, 1].map((groupIndex) => (
+                  <div class="endorsement-track-group" aria-hidden={groupIndex === 1 ? "true" : undefined}>
+                    {row.map((tweet) => (
+                      <a
+                        class="endorsement-card"
+                        href={tweet.link}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        aria-label={`Read ${tweet.handle}'s post on X`}
+                        tabindex={groupIndex === 1 ? "-1" : undefined}
+                      >
+                        <div class="endorsement-author">
+                          <img
+                            src={`/pfps/${tweet.handle}.webp`}
+                            alt=""
+                            width="28"
+                            height="28"
+                            loading="lazy"
+                            decoding="async"
+                          />
+                          <div class="endorsement-handle">@{tweet.handle}</div>
+                        </div>
+                        <p>{tweet.excerpt ?? tweet.content}</p>
+                      </a>
+                    ))}
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))
+        }
+    </div>
+  </section>
+
+  <!-- ── Harnesses ─────────────────────────────────────────────── -->
+  <section id="harnesses" class="sec-harness">
+    <div class="container">
+      <div class="section-head">
+        <h2>Bring your own sub</h2>
+        <p>
+          T3 Code doesn't resell tokens. Plug in Claude Code, Codex, OpenCode,
+          or Cursor with the credentials you already have — we orchestrate
+          them, you keep your plan.
+        </p>
+      </div>
+
+      <div class="harness-grid">
+        <div class="harness">
+          <div class="harness-mark"><img src="/harnesses/claude-ai-icon.svg" alt="" /></div>
+          <div class="harness-meta">
+            <div class="harness-name">Claude Code</div>
+            <div class="harness-tag">claude auth login</div>
+          </div>
+        </div>
+        <div class="harness">
+          <div class="harness-mark"><img src="/harnesses/openai_dark.svg" alt="" /></div>
+          <div class="harness-meta">
+            <div class="harness-name">Codex CLI</div>
+            <div class="harness-tag">codex login</div>
+          </div>
+        </div>
+        <div class="harness">
+          <div class="harness-mark"><img src="/harnesses/opencode-dark.svg" alt="" /></div>
+          <div class="harness-meta">
+            <div class="harness-name">OpenCode</div>
+            <div class="harness-tag">opencode auth</div>
+          </div>
+        </div>
+        <div class="harness">
+          <div class="harness-mark"><img src="/harnesses/cursor_light.svg" alt="" /></div>
+          <div class="harness-meta">
+            <div class="harness-name">Cursor</div>
+            <div class="harness-tag">cursor-agent</div>
+          </div>
+        </div>
+      </div>
+
+      <div class="harness-footer">
+        <div class="harness-footer-item"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l5 5L20 6"/></svg> No keys resold. No quota caps.</div>
+        <div class="harness-footer-item"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l5 5L20 6"/></svg> Switch models mid-thread.</div>
+        <div class="harness-footer-item"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l5 5L20 6"/></svg> More harnesses shipping weekly.</div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Git ──────────────────────────────────────────────────── -->
+  <section id="git" class="sec-git">
+    <div class="container git-inner">
+      <div class="git-visual">
+        <div class="pr-card tile">
+          <div class="pr-head">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="6" cy="6" r="2.2"/><circle cx="6" cy="18" r="2.2"/><circle cx="18" cy="6" r="2.2"/><path d="M6 8v8M18 8v5a3 3 0 01-3 3h-3M13 13l-2 3 2 3"/></svg>
+            <span class="pr-title">Add marketing hero animation</span>
+            <span class="pr-status">Ready</span>
+          </div>
+          <div class="pr-meta">
+            <span><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="6" cy="6" r="2.2"/><circle cx="6" cy="18" r="2.2"/><circle cx="18" cy="6" r="2.2"/><path d="M6 8v8M6 12a6 6 0 006-6h6"/></svg> feat/marketing-hero → main</span>
+            <span>+142 −38</span>
+            <span>3 commits</span>
+          </div>
+          <div class="pr-files">
+            <div><code>apps/marketing/src/pages/index.astro</code> <span>+14 −2</span></div>
+            <div><code>apps/marketing/src/layouts/Layout.astro</code> <span>+8 −0</span></div>
+            <div><code>apps/marketing/public/hero.css</code> <span>+120 −36</span></div>
+          </div>
+          <div class="pr-foot">
+            <button class="btn btn-ghost" style="font-size:12px;padding:6px 10px">View diff</button>
+            <button class="btn btn-primary" style="font-size:12px;padding:6px 12px">
+              <svg width="12" height="12" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 .5C5.65.5.5 5.65.5 12a11.5 11.5 0 007.86 10.93c.58.1.79-.25.79-.56v-2c-3.2.69-3.88-1.37-3.88-1.37-.52-1.33-1.27-1.69-1.27-1.69-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.02 1.76 2.68 1.25 3.33.96.1-.75.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.67 0-1.25.45-2.28 1.18-3.08-.12-.29-.51-1.45.11-3.02 0 0 .96-.31 3.15 1.18a10.96 10.96 0 015.74 0c2.19-1.49 3.15-1.18 3.15-1.18.62 1.57.23 2.73.11 3.02.74.8 1.18 1.83 1.18 3.08 0 4.41-2.7 5.38-5.27 5.66.41.36.78 1.06.78 2.13v3.16c0 .31.21.67.8.56A11.5 11.5 0 0023.5 12C23.5 5.65 18.35.5 12 .5z"/></svg>
+              Open pull request
+            </button>
+          </div>
+        </div>
+        <div class="pr-trail">
+          <div class="pr-trail-dot"></div>
+          <div class="pr-trail-line"></div>
+          <div class="pr-trail-dot"></div>
+        </div>
+        <div class="pr-button-shell">
+          <button class="pr-button">
+            <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="6" cy="6" r="2.2"/><circle cx="6" cy="18" r="2.2"/><circle cx="18" cy="6" r="2.2"/><path d="M6 8v8M18 8v5a3 3 0 01-3 3h-3M13 13l-2 3 2 3"/></svg>
+            Commit &amp; push
+            <span class="pr-button-kbd">⌘⏎</span>
+          </button>
+        </div>
+      </div>
+
+      <div class="git-copy">
+        <div class="section-head" style="margin-bottom:0">
+          <h2>One button to commit, push, and make a PR.</h2>
+          <p>
+            Every agent thread writes to its own branch. When it's good, one
+            button opens the PR on GitHub with a generated title, body and
+            changelog. No terminal dance required.
+          </p>
+          <ul class="checklist" style="margin-top:24px">
+            <li><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l5 5L20 6"/></svg> Auto-generated PR titles &amp; bodies</li>
+            <li><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l5 5L20 6"/></svg> Inline diff review before you push</li>
+            <li><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l5 5L20 6"/></svg> Draft PRs, stack PRs, amend PRs</li>
+            <li><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l5 5L20 6"/></svg> Works with your existing GitHub auth</li>
+          </ul>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Open source ───────────────────────────────────────────── -->
+  <section id="open" class="sec-open">
+    <div class="container">
+      <div class="section-head open-head">
+        <div class="eyebrow">Open source</div>
+        <h2>If you don't like something, fork it.</h2>
+        <p>
+          T3 Code is as open as they come. We built this app to be modifiable,
+          customizable, and forkable. Go nuts - that's the whole point.
+        </p>
+      </div>
+
+      <div class="open-grid">
+        <div class="tile open-term">
+          <div class="open-term-head">
+            <span></span><span></span><span></span>
+            <span class="open-term-title">~/code</span>
+          </div>
+          <div class="open-term-body">
+            <div><span class="prompt">$</span> gh repo fork pingdotgg/t3code --clone</div>
+            <div class="dim">✓ Cloned t3code into ./t3code</div>
+            <div><span class="prompt">$</span> cd t3code &amp;&amp; bun install</div>
+            <div class="dim">✓ 1 284 packages installed in 4.2s</div>
+            <div><span class="prompt">$</span> bun dev</div>
+            <div class="dim">▲ T3 Code dev server → <span class="accent">http://localhost:4001</span></div>
+            <div class="cursor"><span class="prompt">$</span><span class="caret"></span></div>
+          </div>
+        </div>
+
+        <div class="open-stats">
+          <div class="tile open-stat">
+            <div class="open-stat-val">MIT</div>
+            <div class="open-stat-lbl">License · commercial-friendly</div>
+          </div>
+          <div class="tile open-stat">
+            <div class="open-stat-val">TypeScript</div>
+            <div class="open-stat-lbl">End-to-end, strictly typed</div>
+          </div>
+          <div class="tile open-stat">
+            <div class="open-stat-val">1 monorepo</div>
+            <div class="open-stat-lbl">Desktop · web · server · harnesses</div>
+          </div>
+          <div class="tile open-stat">
+            <div class="open-stat-val">No telemetry</div>
+            <div class="open-stat-lbl">Unless you opt in. Full stop.</div>
+          </div>
+        </div>
+      </div>
+
+      <div class="open-ctas">
+        <a class="btn btn-ghost" href="https://github.com/pingdotgg/t3code" target="_blank" rel="noopener noreferrer">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 .5C5.65.5.5 5.65.5 12a11.5 11.5 0 007.86 10.93c.58.1.79-.25.79-.56v-2c-3.2.69-3.88-1.37-3.88-1.37-.52-1.33-1.27-1.69-1.27-1.69-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.02 1.76 2.68 1.25 3.33.96.1-.75.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.67 0-1.25.45-2.28 1.18-3.08-.12-.29-.51-1.45.11-3.02 0 0 .96-.31 3.15 1.18a10.96 10.96 0 015.74 0c2.19-1.49 3.15-1.18 3.15-1.18.62 1.57.23 2.73.11 3.02.74.8 1.18 1.83 1.18 3.08 0 4.41-2.7 5.38-5.27 5.66.41.36.78 1.06.78 2.13v3.16c0 .31.21.67.8.56A11.5 11.5 0 0023.5 12C23.5 5.65 18.35.5 12 .5z"/></svg>
+          Star on GitHub
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7 17L17 7M8 7h9v9"/></svg>
+        </a>
+        <a class="btn btn-ghost" href="https://github.com/pingdotgg/t3code/fork" target="_blank" rel="noopener noreferrer">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="6" cy="5" r="2.2"/><circle cx="18" cy="5" r="2.2"/><circle cx="12" cy="19" r="2.2"/><path d="M6 7.2v2A3 3 0 009 12.2h6A3 3 0 0018 9.2v-2M12 14v2.8"/></svg>
+          Fork the repo
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7 17L17 7M8 7h9v9"/></svg>
+        </a>
+        <a class="btn btn-ghost" href="https://github.com/pingdotgg/t3code/blob/main/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="4.5" width="19" height="15" rx="2"/><path d="M7 10l3 2-3 2M12 16h5"/></svg>
+          Read CONTRIBUTING.md
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7 17L17 7M8 7h9v9"/></svg>
+        </a>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Final CTA ─────────────────────────────────────────────── -->
+  <section id="download" class="sec-cta">
+    <div class="container cta-inner">
+      <h2 class="display cta-title">
+        Your agents deserve better than a terminal.
+      </h2>
+      <p class="cta-sub">
+        T3 Code is free, open source and fast. Install it, plug in the harness
+        you already pay for, and let your agents get to work.
+      </p>
+      <div class="cta-actions">
+        <a id="cta-download-btn" class="btn btn-primary btn-lg" href="https://github.com/pingdotgg/t3code/releases">
+          <svg class="dl-icon dl-icon--apple" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 814 1000" aria-hidden="true"><path fill="currentColor" d="M788.1 340.9c-5.8 4.5-108.2 62.2-108.2 190.5 0 148.4 130.3 200.9 134.2 202.2-.6 3.2-20.7 71.9-68.7 141.9-42.8 61.6-87.5 123.1-155.5 123.1s-85.5-39.5-164-39.5c-76.5 0-103.7 40.8-165.9 40.8s-105.6-57-155.5-127C46.7 790.7 0 663 0 541.8c0-194.4 126.4-297.5 250.8-297.5 66.1 0 121.2 43.4 162.7 43.4 39.5 0 101.1-46 176.3-46 28.5 0 130.9 2.6 198.3 99.2zm-234-181.5c31.1-36.9 53.1-88.1 53.1-139.3 0-7.1-.6-14.3-1.9-20.1-50.6 1.9-110.8 33.7-147.1 75.8-28.5 32.4-55.1 83.6-55.1 135.5 0 7.8 1.3 15.6 1.9 18.1 3.2.6 8.4 1.3 13.6 1.3 45.4 0 102.5-30.4 135.5-71.3z"/></svg>
+          <svg class="dl-icon dl-icon--windows" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 88 88" aria-hidden="true"><path fill="currentColor" d="m0 12.402 35.687-4.86.016 34.423-35.67.203zm35.67 33.529.028 34.453L.028 75.48.026 45.7zm4.326-39.025L87.314 0v41.527l-47.318.376zm47.329 39.349-.011 41.34-47.318-6.678-.066-34.739z"/></svg>
+          <TuxIcon class="dl-icon dl-icon--linux" idPrefix="cta-linux-" />
+          <span id="cta-download-label">Download for macOS</span>
+        </a>
+        <a class="btn btn-ghost btn-lg" href="/download">Windows · Linux · other</a>
+      </div>
+    </div>
+  </section>
 </Layout>
 
 <script>
@@ -32,11 +378,7 @@ import Layout from "../layouts/Layout.astro";
     const ua = navigator.userAgent;
     if (/Win/i.test(ua)) return { os: "win", label: "Download for Windows" };
     if (/Mac/i.test(ua)) {
-      return {
-        os: "mac",
-        label: `Download for macOS`,
-        arch: "arm64",
-      };
+      return { os: "mac", label: "Download for macOS", arch: "arm64" };
     }
     if (/Linux/i.test(ua)) return { os: "linux", label: "Download for Linux" };
     return null;
@@ -44,23 +386,15 @@ import Layout from "../layouts/Layout.astro";
 
   function pickAsset(assets: ReleaseAsset[], platform: Platform): string | null {
     if (platform.os === "win") {
-      return (
-        assets.find((a) => a.name.endsWith("-x64.exe"))
-          ?.browser_download_url ?? null
-      );
+      return assets.find((a) => a.name.endsWith("-x64.exe"))?.browser_download_url ?? null;
     }
     if (platform.os === "mac") {
-      const preferred = assets.find((a) =>
-        a.name.endsWith(`-${platform.arch}.dmg`),
-      );
+      const preferred = assets.find((a) => a.name.endsWith(`-${platform.arch}.dmg`));
       const fallback = assets.find((a) => a.name.endsWith(".dmg"));
       return (preferred ?? fallback)?.browser_download_url ?? null;
     }
     if (platform.os === "linux") {
-      return (
-        assets.find((a) => a.name.endsWith(".AppImage"))
-          ?.browser_download_url ?? null
-      );
+      return assets.find((a) => a.name.endsWith(".AppImage"))?.browser_download_url ?? null;
     }
     return null;
   }
@@ -68,24 +402,33 @@ import Layout from "../layouts/Layout.astro";
   async function init() {
     const btn = document.getElementById("download-btn") as HTMLAnchorElement | null;
     const label = document.getElementById("download-label");
-    if (!btn || !label) return;
+    const ctaBtn = document.getElementById("cta-download-btn") as HTMLAnchorElement | null;
+    const ctaLabel = document.getElementById("cta-download-label");
 
     const platform = detectPlatform();
     if (!platform) return;
-
     document.documentElement.dataset.platform = platform.os;
-    label.textContent = platform.label;
+    if (label) label.textContent = platform.label;
+    if (ctaLabel) ctaLabel.textContent = platform.label;
 
     try {
       const release = await fetchLatestRelease();
       const url = pickAsset(release.assets ?? [], platform);
       if (url) {
-        btn.href = url;
-        btn.removeAttribute("target");
-        btn.removeAttribute("rel");
+        if (btn) {
+          btn.href = url;
+          btn.removeAttribute("target");
+          btn.removeAttribute("rel");
+        }
+        if (ctaBtn) {
+          ctaBtn.href = url;
+          ctaBtn.removeAttribute("target");
+          ctaBtn.removeAttribute("rel");
+        }
       }
     } catch {
-      btn.href = RELEASES_URL;
+      if (btn) btn.href = RELEASES_URL;
+      if (ctaBtn) ctaBtn.href = RELEASES_URL;
     }
   }
 
@@ -93,145 +436,693 @@ import Layout from "../layouts/Layout.astro";
 </script>
 
 <style>
-  .main {
-    padding-top: 10vh;
+  /* ── Section base ─────────────────────────────────────────── */
+  section {
+    position: relative;
+    padding: 96px 0;
+    border-top: 1px solid var(--border);
+  }
+
+  .section-head {
+    margin-bottom: 56px;
+    max-width: 720px;
   }
 
-  /* ── Tagline ── */
+  .section-head .eyebrow {
+    margin-bottom: 14px;
+    display: block;
+  }
 
-  .tagline {
+  .section-head h2 {
+    font-size: clamp(32px, 4vw, 48px);
     font-weight: 500;
-    font-size: clamp(2rem, 5vw, 3.5rem);
     letter-spacing: -0.035em;
-    line-height: 1.15;
-    text-align: center;
-    margin: 0 0 6vh;
-    opacity: 0;
-    animation: fade-in 1s ease-out forwards;
+    line-height: 1.05;
+    margin-bottom: 18px;
+  }
+
+  .section-head p {
+    color: var(--fg-muted);
+    font-size: 18px;
+    max-width: 620px;
+    letter-spacing: -0.005em;
   }
 
-  /* ── Hero button ── */
+  .checklist {
+    list-style: none;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
 
-  .hero-button {
-    display: inline-flex;
+  .checklist li {
+    display: flex;
     align-items: center;
-    gap: 0.55rem;
-    background: #fafafa;
-    color: #09090b;
-    padding: 0.75rem 2rem;
-    border-radius: 999px;
-    font-weight: 600;
-    font-size: 0.9rem;
-    margin-bottom: 1.25rem;
-    opacity: 0;
-    animation: fade-in 1s ease-out 0.15s forwards;
-    transition: transform 0.25s ease, box-shadow 0.25s ease;
+    gap: 10px;
+    color: var(--fg-muted);
+    font-size: 15px;
+  }
+
+  .checklist li svg {
+    color: var(--ok);
+    flex-shrink: 0;
+  }
+
+  /* ── Hero ─────────────────────────────────────────────────── */
+  .hero {
+    padding: 72px 0 60px;
+    position: relative;
+    overflow: hidden;
+    border-top: 0;
+  }
+
+  .hero-grid {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    background-image:
+      linear-gradient(to right, rgba(255, 255, 255, 0.035) 1px, transparent 1px),
+      linear-gradient(to bottom, rgba(255, 255, 255, 0.035) 1px, transparent 1px);
+    background-size: 48px 48px;
+    mask-image: radial-gradient(ellipse 80% 60% at 50% 40%, black 40%, transparent 100%);
+    -webkit-mask-image: radial-gradient(ellipse 80% 60% at 50% 40%, black 40%, transparent 100%);
+  }
+
+  .hero-inner {
+    position: relative;
+    text-align: center;
+  }
+
+  .hero-title {
+    font-size: clamp(38px, 5.6vw, 76px);
+    margin: 28px auto 22px;
+    max-width: 20ch;
+    text-wrap: balance;
   }
 
-  .hero-button:hover {
-    transform: scale(1.03);
-    box-shadow: 0 0 24px rgba(255, 255, 255, 0.08);
+  .hero-sub {
+    color: var(--fg-muted);
+    font-size: clamp(16px, 1.4vw, 19px);
+    max-width: 640px;
+    margin: 0 auto 36px;
+    letter-spacing: -0.005em;
+    line-height: 1.55;
   }
 
-  .hero-button:active {
-    transform: scale(0.98);
+  .hero-actions {
+    display: flex;
+    gap: 10px;
+    justify-content: center;
+    flex-wrap: wrap;
+    margin-bottom: 56px;
   }
 
-  .hero-button-icon {
+  /* Download button icons (platform-aware) */
+  .dl-icon {
     display: none;
-    width: 1em;
-    height: 1em;
+    width: 14px;
+    height: 14px;
     flex-shrink: 0;
   }
 
-  :global([data-platform="mac"]) .hero-button-icon--apple {
-    display: block;
+  :global([data-platform="mac"]) .dl-icon--apple { display: block; }
+  :global([data-platform="win"]) .dl-icon--windows { display: block; }
+  :global([data-platform="linux"]) .dl-icon--linux { display: block; }
+  :global(:not([data-platform])) .dl-icon--apple { display: block; }
+
+  /* Floating harness marks */
+  .hero-float {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 1;
+  }
+
+  .hero-float-mark {
+    position: absolute;
+    width: 96px;
+    height: 96px;
+    border-radius: 24px;
+    display: grid;
+    place-items: center;
+    background: rgba(20, 20, 24, 0.9);
+    border: 1px solid var(--border);
+    backdrop-filter: blur(10px);
+    -webkit-backdrop-filter: blur(10px);
+    box-shadow:
+      0 20px 48px -16px rgba(0, 0, 0, 0.65),
+      0 2px 0 0 rgba(255, 255, 255, 0.04) inset;
+    animation: floatDrift 9s ease-in-out infinite;
   }
 
-  :global([data-platform="win"]) .hero-button-icon--windows {
+  .hero-float-mark img {
+    width: 54px;
+    height: 54px;
     display: block;
+    object-fit: contain;
+  }
+
+  .hero-float-mark.hf-claude   { background: radial-gradient(circle at 30% 25%, rgba(217, 119, 87, 0.22), rgba(20, 20, 24, 0.92) 65%); top: 8%;  left: 7%;  animation-delay: 0s;    transform: rotate(-8deg); }
+  .hero-float-mark.hf-codex    { background: radial-gradient(circle at 30% 25%, rgba(255, 255, 255, 0.08), rgba(20, 20, 24, 0.92) 65%); top: 6%;  right: 7%; animation-delay: -2.5s; transform: rotate(6deg); }
+  .hero-float-mark.hf-opencode { background: radial-gradient(circle at 30% 25%, rgba(255, 255, 255, 0.06), rgba(20, 20, 24, 0.92) 65%); top: 32%; left: 5%;  animation-delay: -5s;   transform: rotate(4deg); }
+  .hero-float-mark.hf-cursor   { background: radial-gradient(circle at 30% 25%, rgba(255, 255, 255, 0.08), rgba(20, 20, 24, 0.92) 65%); top: 30%; right: 5%; animation-delay: -7s;   transform: rotate(-5deg); }
+
+  @media (max-width: 1180px) {
+    .hero-float-mark { width: 76px; height: 76px; border-radius: 20px; }
+    .hero-float-mark img { width: 42px; height: 42px; }
+    .hero-float-mark.hf-claude   { top: 4%;  left: 3%; }
+    .hero-float-mark.hf-codex    { top: 2%;  right: 3%; }
+    .hero-float-mark.hf-opencode { top: 26%; left: 2%; }
+    .hero-float-mark.hf-cursor   { top: 24%; right: 2%; }
+  }
+
+  @media (max-width: 820px) {
+    .hero {
+      padding-top: 132px;
+    }
+
+    .hero-title {
+      font-size: clamp(40px, 11vw, 56px);
+      margin-top: 14px;
+    }
+
+    .hero-actions {
+      margin-bottom: 96px;
+    }
+
+    .hero-float {
+      position: absolute;
+      inset: 0;
+      display: block;
+    }
+
+    .hero-float-mark {
+      position: absolute;
+      width: 78px;
+      height: 78px;
+      border-radius: 20px;
+    }
+
+    .hero-float-mark img {
+      width: 44px;
+      height: 44px;
+    }
+
+    /* Two above the title, two flanking the call-to-action area. */
+    .hero-float-mark.hf-claude {
+      top: 44px;
+      left: 10px;
+      transform: rotate(-10deg);
+    }
+
+    .hero-float-mark.hf-codex {
+      top: 44px;
+      right: 10px;
+      transform: rotate(8deg);
+    }
+
+    .hero-float-mark.hf-opencode {
+      top: 474px;
+      left: 4px;
+      right: auto;
+      transform: rotate(-6deg);
+    }
+
+    .hero-float-mark.hf-cursor {
+      top: 474px;
+      right: 4px;
+      left: auto;
+      transform: rotate(7deg);
+    }
   }
 
-  :global([data-platform="linux"]) .hero-button-icon--linux {
+  .hero-preview {
+    max-width: 1180px;
+    margin: 0 auto;
+    transform: perspective(2000px) rotateX(2deg);
+    transition: transform 0.6s ease;
+  }
+
+  .hero-preview:hover {
+    transform: perspective(2000px) rotateX(0deg);
+  }
+
+  .hero-screenshot-frame {
+    position: relative;
+    overflow: hidden;
+    aspect-ratio: 2508 / 1682;
+    border-radius: 14px;
+    background: #0a0a0c;
+    box-shadow: 0 28px 64px -28px rgba(0, 0, 0, 0.75);
+  }
+
+  .hero-screenshot-frame picture {
     display: block;
+    width: 100%;
+    height: 100%;
+  }
+
+  .hero-screenshot-frame img {
+    width: calc(100% + 4px);
+    height: calc(100% + 4px);
+    margin: -2px;
+    object-fit: cover;
+    object-position: center top;
+  }
+
+  /* ── Harnesses ─────────────────────────────────────────── */
+  .sec-harness { background: #09090b; }
+
+  .harness-grid {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 0;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    overflow: hidden;
+  }
+
+  .harness {
+    padding: 22px 20px;
+    display: flex; align-items: center; gap: 14px;
+    border-right: 1px solid var(--border);
+    background: linear-gradient(180deg, rgba(255, 255, 255, 0.015), transparent);
+    transition: background 0.2s ease;
   }
+  .harness:last-child { border-right: 0; }
+  .harness:hover { background: rgba(255, 255, 255, 0.025); }
 
-  /* ── Other platforms link ── */
+  .harness-mark {
+    color: var(--fg); opacity: 0.95;
+    flex-shrink: 0; width: 28px; height: 28px;
+    display: grid; place-items: center;
+  }
+  .harness-mark img { width: 22px; height: 22px; object-fit: contain; }
 
-  .other-platforms {
-    font-size: 0.825rem;
-    color: var(--fg-dim);
-    margin-bottom: 5vh;
-    opacity: 0;
-    animation: fade-in 1s ease-out 0.3s forwards;
-    transition: color 0.3s ease;
-    text-decoration: underline;
-    text-decoration-color: rgba(113, 113, 122, 0.4);
-    text-underline-offset: 3px;
+  .harness-meta { flex: 1; min-width: 0; }
+  .harness-name {
+    font-size: 14px; font-weight: 500;
+    letter-spacing: -0.01em; margin-bottom: 2px;
+  }
+  .harness-tag {
+    font-family: var(--font-mono);
+    font-size: 11px; color: var(--fg-dim);
   }
 
-  .other-platforms:hover {
+  .harness-footer {
+    display: flex; gap: 24px; flex-wrap: wrap;
+    margin-top: 28px; padding-top: 24px;
+    border-top: 1px dashed var(--border);
+    font-size: 13px; color: var(--fg-muted);
+  }
+  .harness-footer-item {
+    display: inline-flex; gap: 8px; align-items: center;
     color: var(--fg-muted);
-    text-decoration-color: var(--fg-muted);
   }
+  .harness-footer-item svg { color: var(--ok); }
 
-  /* ── Screenshot ── */
+  /* ── Endorsements ─────────────────────────────────────── */
+  .sec-endorsements {
+    overflow: hidden;
+  }
 
-  .screenshot-wrap {
-    margin: 0 auto;
-    width: min(95vw, 1400px);
-    opacity: 0;
-    transform: scale(0.98);
-    animation: screenshot-in 1s ease-out 0.15s forwards;
+  .endorsements-head {
+    max-width: 720px;
+    margin-bottom: 56px;
   }
 
-  .screenshot {
-    width: 100%;
-    display: block;
-    border-radius: 16px;
-    border: 1px solid rgba(255, 255, 255, 0.06);
-    mask-image: linear-gradient(to bottom, black 80%, transparent 100%);
-    -webkit-mask-image: linear-gradient(to bottom, black 80%, transparent 100%);
+  .endorsements-head h2 {
+    font-size: clamp(32px, 4vw, 48px);
+    font-weight: 500;
+    letter-spacing: -0.035em;
+    line-height: 1.05;
+    margin-bottom: 18px;
   }
 
-  .screenshot-wrap::after {
+  .endorsements-head p {
+    color: var(--fg-muted);
+    font-size: 18px;
+    max-width: 620px;
+    letter-spacing: -0.005em;
+  }
+
+  .endorsement-carousel {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+
+  .endorsement-carousel--mobile {
+    display: none;
+  }
+
+  .endorsement-carousel::before,
+  .endorsement-carousel::after {
     content: "";
-    display: block;
-    width: 100%;
-    height: 120px;
-    background: inherit;
-    margin-top: -1px;
-    opacity: 0.04;
-    transform: scaleY(-1);
-    mask-image: linear-gradient(to bottom, black 0%, transparent 60%);
-    -webkit-mask-image: linear-gradient(to bottom, black 0%, transparent 60%);
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    z-index: 2;
+    width: max(48px, calc((100vw - 1240px) / 2 + 56px));
+    pointer-events: none;
+  }
+
+  .endorsement-carousel::before {
+    left: 0;
+    background: linear-gradient(90deg, var(--bg), transparent);
+  }
+
+  .endorsement-carousel::after {
+    right: 0;
+    background: linear-gradient(270deg, var(--bg), transparent);
+  }
+
+  .endorsement-row {
+    overflow: hidden;
+  }
+
+  .endorsement-track {
+    width: max-content;
+    display: flex;
+    animation: endorsementMarquee 76s linear infinite;
+    will-change: transform;
+  }
+
+  .endorsement-track-group {
+    display: flex;
+    gap: 12px;
+    padding-right: 12px;
+  }
+
+  .endorsement-row.is-reverse .endorsement-track {
+    animation-direction: reverse;
+    animation-duration: 84s;
+  }
+
+  .endorsement-carousel:hover .endorsement-track,
+  .endorsement-carousel:focus-within .endorsement-track {
+    animation-play-state: paused;
+  }
+
+  .endorsement-card {
+    position: relative;
+    width: clamp(264px, 22vw, 308px);
+    height: 132px;
+    padding: 14px 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    background: rgba(255, 255, 255, 0.012);
+    transition:
+      border-color 0.18s ease,
+      background 0.18s ease;
+  }
+
+  .endorsement-card:hover {
+    border-color: var(--border-strong);
+    background: rgba(255, 255, 255, 0.03);
+  }
+
+  .endorsement-author {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    min-width: 0;
+  }
+
+  .endorsement-author img {
+    width: 28px;
+    height: 28px;
+    border-radius: 50%;
+    object-fit: cover;
+    flex-shrink: 0;
+  }
+
+  .endorsement-handle {
+    color: var(--fg-muted);
+    font-size: 13px;
+    font-weight: 500;
+    letter-spacing: -0.005em;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .endorsement-card p {
+    color: var(--fg);
+    font-size: 13.5px;
+    line-height: 1.4;
+    letter-spacing: -0.003em;
+    display: -webkit-box;
+    overflow: hidden;
+    -webkit-box-orient: vertical;
+    -webkit-line-clamp: 3;
+  }
+
+  /* ── Git ──────────────────────────────────────────────── */
+  .git-inner {
+    display: grid;
+    grid-template-columns: 1.1fr 1fr;
+    gap: 64px; align-items: center;
+  }
+
+  .git-visual {
+    position: relative;
+    display: flex; flex-direction: column;
+    align-items: stretch; gap: 20px;
+  }
+
+  .pr-card { padding: 20px; }
+  .pr-head {
+    display: flex; align-items: center; gap: 10px;
+    margin-bottom: 12px;
+  }
+  .pr-head svg { color: var(--ok); }
+  .pr-title { font-weight: 500; font-size: 15px; flex: 1; }
+  .pr-status {
+    font-family: var(--font-mono); font-size: 10px;
+    color: var(--ok); padding: 2px 8px;
+    border: 1px solid var(--ok); border-radius: 999px;
+    letter-spacing: 0.08em; text-transform: uppercase;
+  }
+  .pr-meta {
+    display: flex; gap: 14px;
+    font-family: var(--font-mono); font-size: 11px;
+    color: var(--fg-dim); margin-bottom: 14px; flex-wrap: wrap;
+  }
+  .pr-meta span { display: inline-flex; align-items: center; gap: 5px; }
+  .pr-files {
+    border: 1px solid var(--border); border-radius: 8px;
+    overflow: hidden; margin-bottom: 16px;
+  }
+  .pr-files > div {
+    display: flex; justify-content: space-between;
+    padding: 8px 12px; font-family: var(--font-mono);
+    font-size: 11px; border-top: 1px solid var(--border);
+    color: var(--fg-muted);
+  }
+  .pr-files > div:first-child { border-top: 0; }
+  .pr-files span { color: var(--fg-dim); }
+  .pr-foot { display: flex; justify-content: flex-end; gap: 8px; }
+
+  .pr-trail {
+    display: flex; flex-direction: column;
+    align-items: center; justify-content: center;
+    gap: 0; margin: -4px 0;
+  }
+  .pr-trail-dot {
+    width: 8px; height: 8px; border-radius: 999px;
+    background: var(--border-strong);
+  }
+  .pr-trail-line {
+    width: 1px; height: 28px;
+    background: linear-gradient(180deg, var(--border-strong), var(--accent));
+  }
+
+  .pr-button-shell { display: flex; justify-content: center; }
+  .pr-button {
+    display: inline-flex; align-items: center; gap: 10px;
+    padding: 12px 20px;
+    background: var(--fg); color: #09090b;
+    font-weight: 600; font-size: 13px;
+    border-radius: 10px;
+    box-shadow: 0 8px 24px -8px rgba(255, 255, 255, 0.2);
+  }
+  .pr-button-kbd {
+    font-family: var(--font-mono); font-size: 10px;
+    background: rgba(0, 0, 0, 0.1);
+    padding: 2px 6px; border-radius: 4px;
+  }
+
+  /* ── Open source ──────────────────────────────────────── */
+  .open-head {
+    text-align: center;
+    margin: 0 auto 56px;
+  }
+  .open-head p { margin: 0 auto; }
+
+  .open-grid {
+    display: grid;
+    grid-template-columns: 1.25fr 1fr;
+    gap: 20px; margin-bottom: 32px;
+  }
+
+  .open-term { padding: 0; overflow: hidden; }
+  .open-term-head {
+    display: flex; align-items: center; gap: 6px;
+    padding: 10px 14px; border-bottom: 1px solid var(--border);
+    background: rgba(255, 255, 255, 0.02);
+  }
+  .open-term-head span {
+    width: 10px; height: 10px; border-radius: 999px;
+    background: #2a2a30; display: block;
+  }
+  .open-term-title {
+    margin-left: 10px;
+    font-family: var(--font-mono); font-size: 11px;
+    color: var(--fg-dim); flex: 1; text-align: center;
+    background: transparent !important;
+    width: auto !important; height: auto !important;
+    border-radius: 0 !important;
+  }
+
+  .open-term-body {
+    padding: 20px 22px;
+    font-family: var(--font-mono); font-size: 13px;
+    line-height: 1.7; color: var(--fg);
+  }
+  .open-term-body > div {
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  }
+  .open-term-body .prompt { color: var(--accent); margin-right: 8px; }
+  .open-term-body .dim { color: var(--fg-dim); }
+  .open-term-body .accent { color: var(--accent); }
+  .open-term-body .cursor { display: flex; align-items: center; }
+  .caret {
+    display: inline-block;
+    width: 7px; height: 14px;
+    background: var(--fg);
+    margin-left: 4px;
+    animation: blink 1s steps(2) infinite;
+  }
+
+  .open-stats {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 12px;
+  }
+  .open-stat {
+    padding: 22px;
+    display: flex; flex-direction: column; gap: 6px;
+  }
+  .open-stat-val {
+    font-size: 22px; font-weight: 500;
+    letter-spacing: -0.015em;
+  }
+  .open-stat-lbl {
+    font-family: var(--font-mono); font-size: 10.5px;
+    color: var(--fg-dim); letter-spacing: 0.04em;
+  }
+
+  .open-ctas {
+    display: flex; gap: 10px;
+    justify-content: center; flex-wrap: wrap;
+  }
+
+  /* ── Final CTA ────────────────────────────────────────── */
+  .sec-cta {
+    text-align: center;
+    padding: 120px 0;
+    position: relative;
+    overflow: hidden;
+  }
+  .sec-cta::before {
+    content: "";
+    position: absolute;
+    inset: auto 0 -50% 0;
+    height: 60%;
+    background: radial-gradient(ellipse at center, var(--accent-dim) 0%, transparent 60%);
     pointer-events: none;
+    opacity: 0.6;
+  }
+  .cta-inner { position: relative; }
+  .cta-title {
+    font-size: clamp(40px, 6vw, 72px);
+  }
+  .cta-sub {
+    color: var(--fg-muted);
+    font-size: 18px;
+    max-width: 560px;
+    margin: 20px auto 36px;
+    line-height: 1.55;
+    letter-spacing: -0.005em;
+  }
+  .cta-actions {
+    display: flex; gap: 10px;
+    justify-content: center; flex-wrap: wrap;
+    margin-bottom: 24px;
   }
 
-  @keyframes screenshot-in {
+  @keyframes endorsementMarquee {
     from {
-      opacity: 0;
-      transform: scale(0.98);
+      transform: translateX(0);
     }
     to {
-      opacity: 1;
-      transform: scale(1);
+      transform: translateX(-50%);
     }
   }
 
-  /* ── Mobile ── */
-
-  @media (max-width: 640px) {
-    .main {
-      padding-top: 7vh;
+  /* ── Responsive ────────────────────────────────────────── */
+  @media (max-width: 960px) {
+    .hero-preview {
+      width: min(860px, calc(100vw - 24px));
+      margin-left: 50%;
+      transform: translateX(-50%) perspective(1600px) rotateX(1.5deg);
     }
-
-    .tagline {
-      margin-bottom: 4vh;
+    .hero-preview:hover {
+      transform: translateX(-50%) perspective(1600px) rotateX(0deg);
     }
+    .harness-grid { grid-template-columns: 1fr 1fr; }
+    .harness { border-right: 0; border-bottom: 1px solid var(--border); }
+    .harness:nth-child(odd) { border-right: 1px solid var(--border); }
+    .git-inner { grid-template-columns: 1fr; gap: 40px; }
+    .open-grid { grid-template-columns: 1fr; }
+  }
 
-    .screenshot-wrap {
-      width: 95vw;
+  @media (max-width: 820px) {
+    section { padding: 64px 0; }
+    .sec-cta { padding: 96px 0; }
+    .container { padding-left: 20px; padding-right: 20px; }
+    .hero-preview { display: none; }
+    .endorsements-head {
+      margin-bottom: 40px;
+    }
+    .endorsement-carousel--desktop {
+      display: none;
+    }
+    .endorsement-carousel--mobile {
+      display: flex;
+    }
+    .endorsement-carousel::before,
+    .endorsement-carousel::after {
+      width: 28px;
+    }
+    .endorsement-track {
+      animation-duration: 68s;
+    }
+    .endorsement-row.is-reverse .endorsement-track {
+      animation-duration: 76s;
+    }
+    .endorsement-card {
+      width: 268px;
+      height: 132px;
+      padding: 14px;
+    }
+    .endorsement-card p {
+      font-size: 13px;
     }
   }
 </style>
diff --git a/apps/marketing/tweets.md b/apps/marketing/tweets.md
new file mode 100644
index 00000000000..92a087d8018
--- /dev/null
+++ b/apps/marketing/tweets.md
@@ -0,0 +1,19 @@
+https://x.com/Shay_Benshabtay/status/2054668503857156326
+https://x.com/teja2495/status/2052420254991581623
+https://x.com/developedbyed/status/2030627970532921605
+https://x.com/tannerlinsley/status/2031102771529920966
+https://x.com/aronprins/status/2045102518196183109
+https://x.com/BennettBuhner/status/2054667115697754387
+https://x.com/ex0t1clol/status/2054666870008021197
+https://x.com/Josikinz/status/2030367951694745870
+https://x.com/jetpackjoe_/status/2054666792933404959
+https://x.com/mil000/status/2030120041451246071
+https://x.com/_winter_wonders/status/2052350198764970434
+https://x.com/kostyniuk00/status/2052041388179468521
+https://x.com/gnukeith/status/2054670073579630730
+https://x.com/peculiarnewbie/status/2054671685027233827
+https://x.com/leodev/status/2054679746353537042
+https://x.com/pocarles/status/2054673964274758046
+https://x.com/DavidKPiano/status/2054682983504719930
+https://x.com/iamkaffe/status/2054675539311411280
+https://x.com/uwunetes/status/2054683356022120640
diff --git a/apps/server/integration/OrchestrationEngineHarness.integration.ts b/apps/server/integration/OrchestrationEngineHarness.integration.ts
index 6daa43ca42a..837c32fc4fd 100644
--- a/apps/server/integration/OrchestrationEngineHarness.integration.ts
+++ b/apps/server/integration/OrchestrationEngineHarness.integration.ts
@@ -1,33 +1,30 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import { execFileSync } from "node:child_process";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import {
   ApprovalRequestId,
-  ProviderKind,
+  CodexSettings,
+  ProviderDriverKind,
   type OrchestrationEvent,
   type OrchestrationThread,
 } from "@t3tools/contracts";
-import {
-  Effect,
-  Exit,
-  FileSystem,
-  Layer,
-  ManagedRuntime,
-  Option,
-  Path,
-  Ref,
-  Schedule,
-  Schema,
-  Scope,
-  Stream,
-} from "effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 
 import { CheckpointStoreLive } from "../src/checkpointing/Layers/CheckpointStore.ts";
 import { CheckpointStore } from "../src/checkpointing/Services/CheckpointStore.ts";
-import { GitCoreLive } from "../src/git/Layers/GitCore.ts";
-import { GitCore, type GitCoreShape } from "../src/git/Services/GitCore.ts";
-import { GitStatusBroadcaster } from "../src/git/Services/GitStatusBroadcaster.ts";
-import { TextGeneration, type TextGenerationShape } from "../src/git/Services/TextGeneration.ts";
+import { TextGeneration, type TextGenerationShape } from "../src/textGeneration/TextGeneration.ts";
 import { OrchestrationCommandReceiptRepositoryLive } from "../src/persistence/Layers/OrchestrationCommandReceipts.ts";
 import { OrchestrationEventStoreLive } from "../src/persistence/Layers/OrchestrationEventStore.ts";
 import { ProjectionCheckpointRepositoryLive } from "../src/persistence/Layers/ProjectionCheckpoints.ts";
@@ -36,13 +33,16 @@ import { ProviderSessionRuntimeRepositoryLive } from "../src/persistence/Layers/
 import { makeSqlitePersistenceLive } from "../src/persistence/Layers/Sqlite.ts";
 import { ProjectionCheckpointRepository } from "../src/persistence/Services/ProjectionCheckpoints.ts";
 import { ProjectionPendingApprovalRepository } from "../src/persistence/Services/ProjectionPendingApprovals.ts";
-import { ProviderUnsupportedError } from "../src/provider/Errors.ts";
+import { makeAdapterRegistryMock } from "../src/provider/testUtils/providerAdapterRegistryMock.ts";
 import { ProviderAdapterRegistry } from "../src/provider/Services/ProviderAdapterRegistry.ts";
 import { ProviderSessionDirectoryLive } from "../src/provider/Layers/ProviderSessionDirectory.ts";
 import { ServerSettingsService } from "../src/serverSettings.ts";
 import { makeProviderServiceLive } from "../src/provider/Layers/ProviderService.ts";
-import { makeCodexAdapterLive } from "../src/provider/Layers/CodexAdapter.ts";
-import { CodexAdapter } from "../src/provider/Services/CodexAdapter.ts";
+import { makeCodexAdapter } from "../src/provider/Layers/CodexAdapter.ts";
+import {
+  NoOpProviderEventLoggers,
+  ProviderEventLoggers,
+} from "../src/provider/Layers/ProviderEventLoggers.ts";
 import { ProviderService } from "../src/provider/Services/ProviderService.ts";
 import { AnalyticsService } from "../src/telemetry/Services/AnalyticsService.ts";
 import { CheckpointReactorLive } from "../src/orchestration/Layers/CheckpointReactor.ts";
@@ -58,6 +58,7 @@ import {
   OrchestrationEngineService,
   type OrchestrationEngineShape,
 } from "../src/orchestration/Services/OrchestrationEngine.ts";
+import { ThreadDeletionReactor } from "../src/orchestration/Services/ThreadDeletionReactor.ts";
 import { OrchestrationReactor } from "../src/orchestration/Services/OrchestrationReactor.ts";
 import { ProjectionSnapshotQuery } from "../src/orchestration/Services/ProjectionSnapshotQuery.ts";
 import {
@@ -72,6 +73,12 @@ import {
 import { deriveServerPaths, ServerConfig } from "../src/config.ts";
 import { WorkspaceEntriesLive } from "../src/workspace/Layers/WorkspaceEntries.ts";
 import { WorkspacePathsLive } from "../src/workspace/Layers/WorkspacePaths.ts";
+import * as VcsDriverRegistry from "../src/vcs/VcsDriverRegistry.ts";
+import { VcsStatusBroadcaster } from "../src/vcs/VcsStatusBroadcaster.ts";
+import { GitWorkflowService } from "../src/git/GitWorkflowService.ts";
+import * as VcsProcess from "../src/vcs/VcsProcess.ts";
+
+const decodeCodexSettings = Schema.decodeEffect(CodexSettings);
 
 function runGit(cwd: string, args: ReadonlyArray<string>) {
   return execFileSync("git", args, {
@@ -213,7 +220,7 @@ export interface OrchestrationIntegrationHarness {
 }
 
 interface MakeOrchestrationIntegrationHarnessOptions {
-  readonly provider?: ProviderKind;
+  readonly provider?: ProviderDriverKind;
   readonly realCodex?: boolean;
 }
 
@@ -224,7 +231,7 @@ export const makeOrchestrationIntegrationHarness = (
     const path = yield* Path.Path;
     const fileSystem = yield* FileSystem.FileSystem;
 
-    const provider = options?.provider ?? "codex";
+    const provider = options?.provider ?? ProviderDriverKind.make("codex");
     const useRealCodex = options?.realCodex === true;
     const adapterHarness = useRealCodex
       ? null
@@ -232,13 +239,10 @@ export const makeOrchestrationIntegrationHarness = (
           provider,
         });
     const fakeRegistry = adapterHarness
-      ? Layer.succeed(ProviderAdapterRegistry, {
-          getByProvider: (resolvedProvider) =>
-            resolvedProvider === adapterHarness.provider
-              ? Effect.succeed(adapterHarness.adapter)
-              : Effect.fail(new ProviderUnsupportedError({ provider: resolvedProvider })),
-          listProviders: () => Effect.succeed([adapterHarness.provider]),
-        } as typeof ProviderAdapterRegistry.Service)
+      ? Layer.succeed(
+          ProviderAdapterRegistry,
+          makeAdapterRegistryMock({ [adapterHarness.provider]: adapterHarness.adapter }),
+        )
       : null;
     const rootDir = yield* fileSystem.makeTempDirectoryScoped({
       prefix: "t3-orchestration-integration-",
@@ -263,34 +267,33 @@ export const makeOrchestrationIntegrationHarness = (
     const realCodexRegistry = Layer.effect(
       ProviderAdapterRegistry,
       Effect.gen(function* () {
-        const codexAdapter = yield* CodexAdapter;
-        return {
-          getByProvider: (resolvedProvider) =>
-            resolvedProvider === "codex"
-              ? Effect.succeed(codexAdapter)
-              : Effect.fail(new ProviderUnsupportedError({ provider: resolvedProvider })),
-          listProviders: () => Effect.succeed(["codex"] as const),
-        } as typeof ProviderAdapterRegistry.Service;
+        const codexSettings = yield* decodeCodexSettings({});
+        const codexAdapter = yield* makeCodexAdapter(codexSettings);
+        return makeAdapterRegistryMock({
+          [ProviderDriverKind.make("codex")]: codexAdapter,
+        });
       }),
     ).pipe(
-      Layer.provide(makeCodexAdapterLive()),
       Layer.provideMerge(ServerConfig.layerTest(workspaceDir, rootDir)),
       Layer.provideMerge(NodeServices.layer),
       Layer.provideMerge(providerSessionDirectoryLayer),
     );
+    const providerEventLoggersLayer = Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers);
     const providerLayer = useRealCodex
       ? makeProviderServiceLive().pipe(
           Layer.provide(providerSessionDirectoryLayer),
           Layer.provide(realCodexRegistry),
           Layer.provide(AnalyticsService.layerTest),
+          Layer.provide(providerEventLoggersLayer),
         )
       : makeProviderServiceLive().pipe(
           Layer.provide(providerSessionDirectoryLayer),
           Layer.provide(fakeRegistry!),
           Layer.provide(AnalyticsService.layerTest),
+          Layer.provide(providerEventLoggersLayer),
         );
 
-    const checkpointStoreLayer = CheckpointStoreLive.pipe(Layer.provide(GitCoreLive));
+    const checkpointStoreLayer = CheckpointStoreLive.pipe(Layer.provide(VcsDriverRegistry.layer));
     const projectionSnapshotQueryLayer = OrchestrationProjectionSnapshotQueryLive;
     const runtimeServicesLayer = Layer.mergeAll(
       projectionSnapshotQueryLayer,
@@ -306,31 +309,34 @@ export const makeOrchestrationIntegrationHarness = (
       Layer.provideMerge(runtimeServicesLayer),
       Layer.provideMerge(serverSettingsLayer),
     );
-    const gitCoreLayer = Layer.succeed(GitCore, {
-      renameBranch: (input: Parameters<GitCoreShape["renameBranch"]>[0]) =>
-        Effect.succeed({ branch: input.newBranch }),
-    } as unknown as GitCoreShape);
+    const gitWorkflowLayer = Layer.mock(GitWorkflowService)({
+      renameBranch: (input: {
+        readonly cwd: string;
+        readonly oldBranch: string;
+        readonly newBranch: string;
+      }) => Effect.succeed({ branch: input.newBranch }),
+    });
     const textGenerationLayer = Layer.succeed(TextGeneration, {
       generateBranchName: () => Effect.succeed({ branch: "update" }),
       generateThreadTitle: () => Effect.succeed({ title: "New thread" }),
     } as unknown as TextGenerationShape);
     const providerCommandReactorLayer = ProviderCommandReactorLive.pipe(
       Layer.provideMerge(runtimeServicesLayer),
-      Layer.provideMerge(gitCoreLayer),
+      Layer.provideMerge(gitWorkflowLayer),
       Layer.provideMerge(textGenerationLayer),
       Layer.provideMerge(serverSettingsLayer),
     );
     const checkpointReactorLayer = CheckpointReactorLive.pipe(
       Layer.provideMerge(runtimeServicesLayer),
       Layer.provideMerge(
-        Layer.succeed(GitStatusBroadcaster, {
+        Layer.succeed(VcsStatusBroadcaster, {
           getStatus: () => Effect.die("getStatus should not be called in this test"),
           refreshLocalStatus: () =>
             Effect.succeed({
               isRepo: true,
-              hasOriginRemote: false,
-              isDefaultBranch: true,
-              branch: "main",
+              hasPrimaryRemote: false,
+              isDefaultRef: true,
+              refName: "main",
               hasWorkingTreeChanges: false,
               workingTree: { files: [], insertions: 0, deletions: 0 },
             }),
@@ -341,16 +347,23 @@ export const makeOrchestrationIntegrationHarness = (
       Layer.provideMerge(
         WorkspaceEntriesLive.pipe(
           Layer.provide(WorkspacePathsLive),
-          Layer.provideMerge(gitCoreLayer),
+          Layer.provideMerge(VcsDriverRegistry.layer),
           Layer.provide(NodeServices.layer),
         ),
       ),
       Layer.provideMerge(WorkspacePathsLive),
+      Layer.provideMerge(VcsProcess.layer),
     );
     const orchestrationReactorLayer = OrchestrationReactorLive.pipe(
       Layer.provideMerge(runtimeIngestionLayer),
       Layer.provideMerge(providerCommandReactorLayer),
       Layer.provideMerge(checkpointReactorLayer),
+      Layer.provideMerge(
+        Layer.succeed(ThreadDeletionReactor, {
+          start: () => Effect.void,
+          drain: Effect.void,
+        }),
+      ),
     );
     const layer = Layer.empty.pipe(
       Layer.provideMerge(runtimeServicesLayer),
diff --git a/apps/server/integration/TestProviderAdapter.integration.ts b/apps/server/integration/TestProviderAdapter.integration.ts
index f4973953078..28873c51f97 100644
--- a/apps/server/integration/TestProviderAdapter.integration.ts
+++ b/apps/server/integration/TestProviderAdapter.integration.ts
@@ -1,5 +1,3 @@
-import { randomUUID } from "node:crypto";
-
 import {
   ApprovalRequestId,
   EventId,
@@ -10,9 +8,12 @@ import {
   ProviderTurnStartResult,
   ThreadId,
   TurnId,
-  ProviderKind,
+  ProviderDriverKind,
 } from "@t3tools/contracts";
-import { Effect, Queue, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+import * as Random from "effect/Random";
+import * as Stream from "effect/Stream";
 
 import {
   ProviderAdapterSessionNotFoundError,
@@ -36,7 +37,7 @@ export interface TestTurnResponse {
 export type FixtureProviderRuntimeEvent = {
   readonly type: string;
   readonly eventId: EventId;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly createdAt: string;
   readonly threadId: string;
   readonly turnId?: string | undefined;
@@ -178,7 +179,7 @@ function normalizeFixtureEvent(rawEvent: Record<string, unknown>): ProviderRunti
 
 export interface TestProviderAdapterHarness {
   readonly adapter: ProviderAdapterShape<ProviderAdapterError>;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly queueTurnResponse: (
     threadId: ThreadId,
     response: TestTurnResponse,
@@ -198,15 +199,15 @@ export interface TestProviderAdapterHarness {
 }
 
 interface MakeTestProviderAdapterHarnessOptions {
-  readonly provider?: ProviderKind;
+  readonly provider?: ProviderDriverKind;
 }
 
 function nowIso(): string {
-  return new Date().toISOString();
+  return "2026-01-01T00:00:00.000Z";
 }
 
 function sessionNotFound(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   threadId: ThreadId,
 ): ProviderAdapterSessionNotFoundError {
   return new ProviderAdapterSessionNotFoundError({
@@ -216,7 +217,7 @@ function sessionNotFound(
 }
 
 function missingSessionEffect(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   threadId: ThreadId,
 ): Effect.Effect<never, ProviderAdapterError> {
   return Effect.fail(sessionNotFound(provider, threadId));
@@ -224,7 +225,7 @@ function missingSessionEffect(
 
 export const makeTestProviderAdapterHarness = (options?: MakeTestProviderAdapterHarnessOptions) =>
   Effect.gen(function* () {
-    const provider = options?.provider ?? "codex";
+    const provider = options?.provider ?? ProviderDriverKind.make("codex");
     const runtimeEvents = yield* Queue.unbounded<ProviderRuntimeEvent>();
     let sessionCount = 0;
     const sessions = new Map<ThreadId, SessionState>();
@@ -257,6 +258,9 @@ export const makeTestProviderAdapterHarness = (options?: MakeTestProviderAdapter
 
         const session: ProviderSession = {
           provider,
+          ...(input.providerInstanceId !== undefined
+            ? { providerInstanceId: input.providerInstanceId }
+            : {}),
           status: "ready",
           runtimeMode: input.runtimeMode,
           threadId,
@@ -305,10 +309,9 @@ export const makeTestProviderAdapterHarness = (options?: MakeTestProviderAdapter
         for (const fixtureEvent of response.events) {
           const rawEvent: Record<string, unknown> = {
             ...(fixtureEvent as Record<string, unknown>),
-            eventId: randomUUID(),
+            eventId: yield* Random.nextUUIDv4,
             provider,
             sessionId: RuntimeSessionId.make(String(input.threadId)),
-            createdAt: nowIso(),
           };
           rawEvent.threadId = state.snapshot.threadId;
           if (Object.hasOwn(rawEvent, "turnId")) {
@@ -363,7 +366,7 @@ export const makeTestProviderAdapterHarness = (options?: MakeTestProviderAdapter
         if (deferredTurnCompletedEvents.length === 0) {
           yield* emit({
             type: "turn.completed",
-            eventId: EventId.make(randomUUID()),
+            eventId: EventId.make(yield* Random.nextUUIDv4),
             provider,
             createdAt: nowIso(),
             threadId: state.snapshot.threadId,
diff --git a/apps/server/integration/fixtures/providerRuntime.ts b/apps/server/integration/fixtures/providerRuntime.ts
index 14a45518c3c..e1258c4cc62 100644
--- a/apps/server/integration/fixtures/providerRuntime.ts
+++ b/apps/server/integration/fixtures/providerRuntime.ts
@@ -1,7 +1,7 @@
-import { EventId, RuntimeRequestId } from "@t3tools/contracts";
+import { EventId, ProviderDriverKind, RuntimeRequestId } from "@t3tools/contracts";
 import type { LegacyProviderRuntimeEvent } from "../TestProviderAdapter.integration.ts";
 
-const PROVIDER = "codex" as const;
+const PROVIDER = ProviderDriverKind.make("codex");
 const SESSION_ID = "fixture-session";
 const THREAD_ID = "fixture-thread";
 const TURN_ID = "fixture-turn";
diff --git a/apps/server/integration/orchestrationEngine.integration.test.ts b/apps/server/integration/orchestrationEngine.integration.test.ts
index a7f845672ca..e79897c740e 100644
--- a/apps/server/integration/orchestrationEngine.integration.test.ts
+++ b/apps/server/integration/orchestrationEngine.integration.test.ts
@@ -1,20 +1,27 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import path from "node:path";
 
 import {
   ApprovalRequestId,
   CommandId,
+  defaultInstanceIdForDriver,
   DEFAULT_PROVIDER_INTERACTION_MODE,
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
   EventId,
   MessageId,
   ProjectId,
-  ProviderKind,
+  ProviderDriverKind,
   ThreadId,
   ModelSelection,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
-import { Effect, Option, Schema } from "effect";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 
 import type { TestTurnResponse } from "./TestProviderAdapter.integration.ts";
 import {
@@ -39,10 +46,12 @@ const PROJECT_ID = asProjectId("project-1");
 const THREAD_ID = ThreadId.make("thread-1");
 const FIXTURE_TURN_ID = "fixture-turn";
 const APPROVAL_REQUEST_ID = asApprovalRequestId("req-approval-1");
-type IntegrationProvider = ProviderKind;
+type IntegrationProvider = ProviderDriverKind;
+const CODEX_PROVIDER = ProviderDriverKind.make("codex");
+const CLAUDE_AGENT_PROVIDER = ProviderDriverKind.make("claudeAgent");
 
 function nowIso() {
-  return new Date().toISOString();
+  return "2026-05-01T00:00:00.000Z";
 }
 
 class IntegrationWaitTimeoutError extends Schema.TaggedErrorClass<IntegrationWaitTimeoutError>()(
@@ -59,14 +68,14 @@ function waitForSync<A>(
   timeoutMs = 10_000,
 ): Effect.Effect<A, never> {
   return Effect.gen(function* () {
-    const deadline = Date.now() + timeoutMs;
+    const deadline = (yield* Clock.currentTimeMillis) + timeoutMs;
 
     while (true) {
       const value = read();
       if (predicate(value)) {
         return value;
       }
-      if (Date.now() >= deadline) {
+      if ((yield* Clock.currentTimeMillis) >= deadline) {
         return yield* Effect.die(new IntegrationWaitTimeoutError({ description }));
       }
       yield* Effect.sleep(10);
@@ -74,7 +83,11 @@ function waitForSync<A>(
   });
 }
 
-function runtimeBase(eventId: string, createdAt: string, provider: IntegrationProvider = "codex") {
+function runtimeBase(
+  eventId: string,
+  createdAt: string,
+  provider: IntegrationProvider = CODEX_PROVIDER,
+) {
   return {
     eventId: asEventId(eventId),
     provider,
@@ -84,7 +97,7 @@ function runtimeBase(eventId: string, createdAt: string, provider: IntegrationPr
 
 function withHarness<A, E>(
   use: (harness: OrchestrationIntegrationHarness) => Effect.Effect<A, E>,
-  provider: IntegrationProvider = "codex",
+  provider: IntegrationProvider = CODEX_PROVIDER,
 ) {
   return Effect.acquireUseRelease(
     makeOrchestrationIntegrationHarness({ provider }),
@@ -97,7 +110,7 @@ function withRealCodexHarness<A, E>(
   use: (harness: OrchestrationIntegrationHarness) => Effect.Effect<A, E>,
 ) {
   return Effect.acquireUseRelease(
-    makeOrchestrationIntegrationHarness({ provider: "codex", realCodex: true }),
+    makeOrchestrationIntegrationHarness({ provider: CODEX_PROVIDER, realCodex: true }),
     use,
     (harness) => harness.dispose,
   ).pipe(Effect.provide(NodeServices.layer));
@@ -106,8 +119,9 @@ function withRealCodexHarness<A, E>(
 const seedProjectAndThread = (harness: OrchestrationIntegrationHarness) =>
   Effect.gen(function* () {
     const createdAt = nowIso();
-    const provider = harness.adapterHarness?.provider ?? "codex";
-    const defaultModel = DEFAULT_MODEL_BY_PROVIDER[provider];
+    const provider = harness.adapterHarness?.provider ?? CODEX_PROVIDER;
+    const defaultModel = DEFAULT_MODEL_BY_PROVIDER[provider] ?? DEFAULT_MODEL;
+    const instanceId = defaultInstanceIdForDriver(provider);
 
     yield* harness.engine.dispatch({
       type: "project.create",
@@ -116,7 +130,7 @@ const seedProjectAndThread = (harness: OrchestrationIntegrationHarness) =>
       title: "Integration Project",
       workspaceRoot: harness.workspaceDir,
       defaultModelSelection: {
-        provider,
+        instanceId,
         model: defaultModel,
       },
       createdAt,
@@ -129,7 +143,7 @@ const seedProjectAndThread = (harness: OrchestrationIntegrationHarness) =>
       projectId: PROJECT_ID,
       title: "Integration Thread",
       modelSelection: {
-        provider,
+        instanceId,
         model: defaultModel,
       },
       interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -146,6 +160,7 @@ const startTurn = (input: {
   readonly messageId: string;
   readonly text: string;
   readonly modelSelection?: ModelSelection;
+  readonly createdAt?: string;
 }) =>
   input.harness.engine.dispatch({
     type: "thread.turn.start",
@@ -164,7 +179,7 @@ const startTurn = (input: {
       : {}),
     interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
     runtimeMode: "approval-required",
-    createdAt: nowIso(),
+    createdAt: input.createdAt ?? nowIso(),
   });
 
 it.live("runs a single turn end-to-end and persists checkpoint state in sqlite + git", () =>
@@ -265,7 +280,7 @@ it.live.skipIf(!process.env.CODEX_BINARY_PATH)(
           title: "Integration Project",
           workspaceRoot: harness.workspaceDir,
           defaultModelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5.3-codex",
           },
           createdAt,
@@ -278,7 +293,7 @@ it.live.skipIf(!process.env.CODEX_BINARY_PATH)(
           projectId: PROJECT_ID,
           title: "Integration Thread",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5.3-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -496,6 +511,7 @@ it.live("runs multi-turn file edits and persists checkpoint diffs", () =>
         fromCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 1),
         toCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 2),
         fallbackFromToHead: false,
+        ignoreWhitespace: false,
       });
       assert.equal(incrementalDiff.includes("README.md"), true);
 
@@ -504,6 +520,7 @@ it.live("runs multi-turn file edits and persists checkpoint diffs", () =>
         fromCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 0),
         toCheckpointRef: checkpointRefForThreadTurn(THREAD_ID, 2),
         fallbackFromToHead: false,
+        ignoreWhitespace: false,
       });
       assert.equal(fullDiff.includes("README.md"), true);
 
@@ -743,6 +760,7 @@ it.live("reverts to an earlier checkpoint and trims checkpoint projections + git
         commandId: "cmd-turn-start-revert-1",
         messageId: "msg-user-revert-1",
         text: "First edit",
+        createdAt: "2026-02-24T10:04:59.900Z",
       });
 
       yield* harness.waitForThread(
@@ -801,6 +819,7 @@ it.live("reverts to an earlier checkpoint and trims checkpoint projections + git
         commandId: "cmd-turn-start-revert-2",
         messageId: "msg-user-revert-2",
         text: "Second edit",
+        createdAt: "2026-02-24T10:05:00.900Z",
       });
 
       yield* harness.waitForThread(
@@ -912,20 +931,32 @@ it.live("starts a claudeAgent session on first turn when provider is requested",
           events: [
             {
               type: "turn.started",
-              ...runtimeBase("evt-claude-start-1", "2026-02-24T10:10:00.000Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-start-1",
+                "2026-02-24T10:10:00.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
             },
             {
               type: "message.delta",
-              ...runtimeBase("evt-claude-start-2", "2026-02-24T10:10:00.050Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-start-2",
+                "2026-02-24T10:10:00.050Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               delta: "Claude first turn.\n",
             },
             {
               type: "turn.completed",
-              ...runtimeBase("evt-claude-start-3", "2026-02-24T10:10:00.100Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-start-3",
+                "2026-02-24T10:10:00.100Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               status: "completed",
@@ -939,7 +970,7 @@ it.live("starts a claudeAgent session on first turn when provider is requested",
           messageId: "msg-user-claude-initial",
           text: "Use Claude",
           modelSelection: {
-            provider: "claudeAgent",
+            instanceId: ProviderInstanceId.make("claudeAgent"),
             model: "claude-sonnet-4-6",
           },
         });
@@ -955,7 +986,7 @@ it.live("starts a claudeAgent session on first turn when provider is requested",
         );
         assert.equal(thread.session?.providerName, "claudeAgent");
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
 
@@ -969,20 +1000,32 @@ it.live("recovers claudeAgent sessions after provider stopAll using persisted re
           events: [
             {
               type: "turn.started",
-              ...runtimeBase("evt-claude-recover-1", "2026-02-24T10:11:00.000Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-recover-1",
+                "2026-02-24T10:11:00.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
             },
             {
               type: "message.delta",
-              ...runtimeBase("evt-claude-recover-2", "2026-02-24T10:11:00.050Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-recover-2",
+                "2026-02-24T10:11:00.050Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               delta: "Turn before restart.\n",
             },
             {
               type: "turn.completed",
-              ...runtimeBase("evt-claude-recover-3", "2026-02-24T10:11:00.100Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-recover-3",
+                "2026-02-24T10:11:00.100Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               status: "completed",
@@ -996,7 +1039,7 @@ it.live("recovers claudeAgent sessions after provider stopAll using persisted re
           messageId: "msg-user-claude-recover-1",
           text: "Before restart",
           modelSelection: {
-            provider: "claudeAgent",
+            instanceId: ProviderInstanceId.make("claudeAgent"),
             model: "claude-sonnet-4-6",
           },
         });
@@ -1018,20 +1061,32 @@ it.live("recovers claudeAgent sessions after provider stopAll using persisted re
           events: [
             {
               type: "turn.started",
-              ...runtimeBase("evt-claude-recover-4", "2026-02-24T10:11:01.000Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-recover-4",
+                "2026-02-24T10:11:01.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
             },
             {
               type: "message.delta",
-              ...runtimeBase("evt-claude-recover-5", "2026-02-24T10:11:01.050Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-recover-5",
+                "2026-02-24T10:11:01.050Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               delta: "Turn after restart.\n",
             },
             {
               type: "turn.completed",
-              ...runtimeBase("evt-claude-recover-6", "2026-02-24T10:11:01.100Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-recover-6",
+                "2026-02-24T10:11:01.100Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               status: "completed",
@@ -1063,7 +1118,7 @@ it.live("recovers claudeAgent sessions after provider stopAll using persisted re
         assert.equal(recoveredThread.session?.providerName, "claudeAgent");
         assert.equal(recoveredThread.session?.threadId, "thread-1");
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
 
@@ -1077,13 +1132,21 @@ it.live("forwards claudeAgent approval responses to the provider session", () =>
           events: [
             {
               type: "turn.started",
-              ...runtimeBase("evt-claude-approval-1", "2026-02-24T10:12:00.000Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-approval-1",
+                "2026-02-24T10:12:00.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
             },
             {
               type: "approval.requested",
-              ...runtimeBase("evt-claude-approval-2", "2026-02-24T10:12:00.050Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-approval-2",
+                "2026-02-24T10:12:00.050Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               requestId: APPROVAL_REQUEST_ID,
@@ -1092,7 +1155,11 @@ it.live("forwards claudeAgent approval responses to the provider session", () =>
             },
             {
               type: "turn.completed",
-              ...runtimeBase("evt-claude-approval-3", "2026-02-24T10:12:00.100Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-approval-3",
+                "2026-02-24T10:12:00.100Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               status: "completed",
@@ -1106,7 +1173,7 @@ it.live("forwards claudeAgent approval responses to the provider session", () =>
           messageId: "msg-user-claude-approval",
           text: "Need approval",
           modelSelection: {
-            provider: "claudeAgent",
+            instanceId: ProviderInstanceId.make("claudeAgent"),
             model: "claude-sonnet-4-6",
           },
         });
@@ -1137,7 +1204,7 @@ it.live("forwards claudeAgent approval responses to the provider session", () =>
         );
         assert.equal(approvalResponses[0]?.decision, "accept");
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
 
@@ -1151,20 +1218,32 @@ it.live("forwards thread.turn.interrupt to claudeAgent provider sessions", () =>
           events: [
             {
               type: "turn.started",
-              ...runtimeBase("evt-claude-interrupt-1", "2026-02-24T10:13:00.000Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-interrupt-1",
+                "2026-02-24T10:13:00.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
             },
             {
               type: "message.delta",
-              ...runtimeBase("evt-claude-interrupt-2", "2026-02-24T10:13:00.050Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-interrupt-2",
+                "2026-02-24T10:13:00.050Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               delta: "Long running output.\n",
             },
             {
               type: "turn.completed",
-              ...runtimeBase("evt-claude-interrupt-3", "2026-02-24T10:13:00.100Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-interrupt-3",
+                "2026-02-24T10:13:00.100Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               status: "completed",
@@ -1178,7 +1257,7 @@ it.live("forwards thread.turn.interrupt to claudeAgent provider sessions", () =>
           messageId: "msg-user-claude-interrupt",
           text: "Start long turn",
           modelSelection: {
-            provider: "claudeAgent",
+            instanceId: ProviderInstanceId.make("claudeAgent"),
             model: "claude-sonnet-4-6",
           },
         });
@@ -1206,7 +1285,7 @@ it.live("forwards thread.turn.interrupt to claudeAgent provider sessions", () =>
         );
         assert.equal(interruptCalls.length, 1);
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
 
@@ -1220,20 +1299,32 @@ it.live("reverts claudeAgent turns and rolls back provider conversation state",
           events: [
             {
               type: "turn.started",
-              ...runtimeBase("evt-claude-revert-1", "2026-02-24T10:14:00.000Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-revert-1",
+                "2026-02-24T10:14:00.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
             },
             {
               type: "message.delta",
-              ...runtimeBase("evt-claude-revert-2", "2026-02-24T10:14:00.050Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-revert-2",
+                "2026-02-24T10:14:00.050Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               delta: "README -> v2\n",
             },
             {
               type: "turn.completed",
-              ...runtimeBase("evt-claude-revert-3", "2026-02-24T10:14:00.100Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-revert-3",
+                "2026-02-24T10:14:00.100Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               status: "completed",
@@ -1251,7 +1342,7 @@ it.live("reverts claudeAgent turns and rolls back provider conversation state",
           messageId: "msg-user-claude-revert-1",
           text: "First Claude edit",
           modelSelection: {
-            provider: "claudeAgent",
+            instanceId: ProviderInstanceId.make("claudeAgent"),
             model: "claude-sonnet-4-6",
           },
         });
@@ -1266,20 +1357,32 @@ it.live("reverts claudeAgent turns and rolls back provider conversation state",
           events: [
             {
               type: "turn.started",
-              ...runtimeBase("evt-claude-revert-4", "2026-02-24T10:14:01.000Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-revert-4",
+                "2026-02-24T10:14:01.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
             },
             {
               type: "message.delta",
-              ...runtimeBase("evt-claude-revert-5", "2026-02-24T10:14:01.050Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-revert-5",
+                "2026-02-24T10:14:01.050Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               delta: "README -> v3\n",
             },
             {
               type: "turn.completed",
-              ...runtimeBase("evt-claude-revert-6", "2026-02-24T10:14:01.100Z", "claudeAgent"),
+              ...runtimeBase(
+                "evt-claude-revert-6",
+                "2026-02-24T10:14:01.100Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
               threadId: THREAD_ID,
               turnId: FIXTURE_TURN_ID,
               status: "completed",
@@ -1330,6 +1433,6 @@ it.live("reverts claudeAgent turns and rolls back provider conversation state",
         );
         assert.deepEqual(harness.adapterHarness!.getRollbackCalls(THREAD_ID), [1]);
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
diff --git a/apps/server/integration/providerService.integration.test.ts b/apps/server/integration/providerService.integration.test.ts
index 89cf6ac153d..57e93c5acdd 100644
--- a/apps/server/integration/providerService.integration.test.ts
+++ b/apps/server/integration/providerService.integration.test.ts
@@ -1,13 +1,22 @@
 import type { ProviderRuntimeEvent } from "@t3tools/contracts";
-import { ThreadId } from "@t3tools/contracts";
+import { ProviderDriverKind, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 import { DEFAULT_SERVER_SETTINGS } from "@t3tools/contracts/settings";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it, assert } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path, Queue, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
 
-import { ProviderUnsupportedError } from "../src/provider/Errors.ts";
 import { ProviderAdapterRegistry } from "../src/provider/Services/ProviderAdapterRegistry.ts";
+import { makeAdapterRegistryMock } from "../src/provider/testUtils/providerAdapterRegistryMock.ts";
 import { ProviderSessionDirectoryLive } from "../src/provider/Layers/ProviderSessionDirectory.ts";
+import {
+  NoOpProviderEventLoggers,
+  ProviderEventLoggers,
+} from "../src/provider/Layers/ProviderEventLoggers.ts";
 import { makeProviderServiceLive } from "../src/provider/Layers/ProviderService.ts";
 import {
   ProviderService,
@@ -29,6 +38,8 @@ import {
   codexTurnTextFixture,
 } from "./fixtures/providerRuntime.ts";
 
+const codexInstanceId = ProviderInstanceId.make("codex");
+
 const makeWorkspaceDirectory = Effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem;
   const pathService = yield* Path.Path;
@@ -47,13 +58,9 @@ const makeIntegrationFixture = Effect.gen(function* () {
   const cwd = yield* makeWorkspaceDirectory;
   const harness = yield* makeTestProviderAdapterHarness();
 
-  const registry: typeof ProviderAdapterRegistry.Service = {
-    getByProvider: (provider) =>
-      provider === "codex"
-        ? Effect.succeed(harness.adapter)
-        : Effect.fail(new ProviderUnsupportedError({ provider })),
-    listProviders: () => Effect.succeed(["codex"]),
-  };
+  const registry = makeAdapterRegistryMock({
+    [ProviderDriverKind.make("codex")]: harness.adapter,
+  });
 
   const directoryLayer = ProviderSessionDirectoryLive.pipe(
     Layer.provide(ProviderSessionRuntimeRepositoryLive),
@@ -64,6 +71,7 @@ const makeIntegrationFixture = Effect.gen(function* () {
     Layer.succeed(ProviderAdapterRegistry, registry),
     ServerSettingsService.layerTest(DEFAULT_SERVER_SETTINGS),
     AnalyticsService.layerTest,
+    Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers),
   ).pipe(Layer.provide(SqlitePersistenceMemory));
 
   const layer = makeProviderServiceLive().pipe(Layer.provide(shared));
@@ -124,7 +132,8 @@ it.live("replays typed runtime fixture events", () =>
       const provider = yield* ProviderService;
       const session = yield* provider.startSession(ThreadId.make("thread-integration-typed"), {
         threadId: ThreadId.make("thread-integration-typed"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         cwd: fixture.cwd,
         runtimeMode: "full-access",
       });
@@ -142,6 +151,10 @@ it.live("replays typed runtime fixture events", () =>
         observedEvents.map((event) => event.type),
         codexTurnTextFixture.map((event) => event.type),
       );
+      assert.deepEqual(
+        observedEvents.map((event) => event.providerInstanceId),
+        codexTurnTextFixture.map(() => codexInstanceId),
+      );
     }).pipe(Effect.provide(fixture.layer));
   }).pipe(Effect.provide(NodeServices.layer)),
 );
@@ -156,7 +169,8 @@ it.live("replays file-changing fixture turn events", () =>
       const provider = yield* ProviderService;
       const session = yield* provider.startSession(ThreadId.make("thread-integration-tools"), {
         threadId: ThreadId.make("thread-integration-tools"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         cwd: fixture.cwd,
         runtimeMode: "full-access",
       });
@@ -192,7 +206,8 @@ it.live("runs multi-turn tool/approval flow", () =>
       const provider = yield* ProviderService;
       const session = yield* provider.startSession(ThreadId.make("thread-integration-multi"), {
         threadId: ThreadId.make("thread-integration-multi"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         cwd: fixture.cwd,
         runtimeMode: "full-access",
       });
@@ -243,7 +258,8 @@ it.live("rolls back provider conversation state only", () =>
       const provider = yield* ProviderService;
       const session = yield* provider.startSession(ThreadId.make("thread-integration-rollback"), {
         threadId: ThreadId.make("thread-integration-rollback"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         cwd: fixture.cwd,
         runtimeMode: "full-access",
       });
diff --git a/apps/server/package.json b/apps/server/package.json
index 950079a4dc1..b8e6f482a28 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "t3",
-  "version": "0.0.17",
+  "version": "0.0.24",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,31 +15,35 @@
   ],
   "type": "module",
   "scripts": {
-    "dev": "bun run src/bin.ts",
+    "dev": "node --watch src/bin.ts",
     "build": "node scripts/cli.ts build",
+    "build:bundle": "tsdown",
     "start": "node dist/bin.mjs",
-    "prepare": "effect-language-service patch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.77",
     "@effect/platform-bun": "catalog:",
     "@effect/platform-node": "catalog:",
+    "@effect/platform-node-shared": "catalog:",
     "@effect/sql-sqlite-bun": "catalog:",
-    "@pierre/diffs": "^1.1.0-beta.16",
+    "@opencode-ai/sdk": "^1.3.15",
+    "@pierre/diffs": "catalog:",
     "effect": "catalog:",
-    "node-pty": "^1.1.0",
-    "open": "^10.1.0"
+    "node-pty": "^1.1.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.111",
     "@effect/language-service": "catalog:",
     "@effect/vitest": "catalog:",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
+    "@t3tools/tailscale": "workspace:*",
     "@t3tools/web": "workspace:*",
     "@types/bun": "catalog:",
     "@types/node": "catalog:",
+    "effect-acp": "workspace:*",
+    "effect-codex-app-server": "workspace:*",
     "tsdown": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"
diff --git a/apps/server/scripts/acp-mock-agent.ts b/apps/server/scripts/acp-mock-agent.ts
new file mode 100644
index 00000000000..e704b8d8a25
--- /dev/null
+++ b/apps/server/scripts/acp-mock-agent.ts
@@ -0,0 +1,591 @@
+#!/usr/bin/env bun
+// @effect-diagnostics nodeBuiltinImport:off
+import { appendFileSync } from "node:fs";
+
+import * as Effect from "effect/Effect";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+
+import * as EffectAcpAgent from "effect-acp/agent";
+import * as AcpError from "effect-acp/errors";
+import type * as AcpSchema from "effect-acp/schema";
+
+const requestLogPath = process.env.T3_ACP_REQUEST_LOG_PATH;
+const exitLogPath = process.env.T3_ACP_EXIT_LOG_PATH;
+const emitToolCalls = process.env.T3_ACP_EMIT_TOOL_CALLS === "1";
+const emitInterleavedAssistantToolCalls =
+  process.env.T3_ACP_EMIT_INTERLEAVED_ASSISTANT_TOOL_CALLS === "1";
+const emitGenericToolPlaceholders = process.env.T3_ACP_EMIT_GENERIC_TOOL_PLACEHOLDERS === "1";
+const emitAskQuestion = process.env.T3_ACP_EMIT_ASK_QUESTION === "1";
+const failSetConfigOption = process.env.T3_ACP_FAIL_SET_CONFIG_OPTION === "1";
+const exitOnSetConfigOption = process.env.T3_ACP_EXIT_ON_SET_CONFIG_OPTION === "1";
+const promptResponseText = process.env.T3_ACP_PROMPT_RESPONSE_TEXT;
+const sessionId = "mock-session-1";
+
+let currentModeId = "ask";
+let currentModelId = "default";
+let parameterizedModelPicker = false;
+let currentReasoning = "medium";
+let currentContext = "272k";
+let currentFast = false;
+const cancelledSessions = new Set<string>();
+
+function logExit(reason: string): void {
+  if (!exitLogPath) {
+    return;
+  }
+  appendFileSync(exitLogPath, `${reason}\n`, "utf8");
+}
+
+process.once("SIGTERM", () => {
+  logExit("SIGTERM");
+  process.exit(0);
+});
+
+process.once("SIGINT", () => {
+  logExit("SIGINT");
+  process.exit(0);
+});
+
+process.once("exit", (code) => {
+  logExit(`exit:${code}`);
+});
+
+function configOptions(): ReadonlyArray<AcpSchema.SessionConfigOption> {
+  if (parameterizedModelPicker) {
+    const baseOptions: Array<AcpSchema.SessionConfigOption> = [
+      {
+        id: "mode",
+        name: "Mode",
+        category: "mode",
+        type: "select",
+        currentValue: currentModeId,
+        options: availableModes.map((mode) => ({
+          value: mode.id,
+          name: mode.name,
+          ...(mode.description ? { description: mode.description } : {}),
+        })),
+      },
+      {
+        id: "model",
+        name: "Model",
+        category: "model",
+        type: "select",
+        currentValue: currentModelId,
+        options: [
+          { value: "default", name: "Auto" },
+          { value: "composer-2", name: "Composer 2" },
+          { value: "gpt-5.4", name: "GPT-5.4" },
+          { value: "claude-opus-4-6", name: "Opus 4.6" },
+        ],
+      },
+    ];
+
+    switch (currentModelId) {
+      case "gpt-5.4":
+        return [
+          ...baseOptions,
+          {
+            id: "reasoning",
+            name: "Reasoning",
+            category: "thought_level",
+            type: "select",
+            currentValue: currentReasoning,
+            options: [
+              { value: "none", name: "None" },
+              { value: "low", name: "Low" },
+              { value: "medium", name: "Medium" },
+              { value: "high", name: "High" },
+              { value: "extra-high", name: "Extra High" },
+            ],
+          },
+          {
+            id: "context",
+            name: "Context",
+            category: "model_config",
+            type: "select",
+            currentValue: currentContext,
+            options: [
+              { value: "272k", name: "272K" },
+              { value: "1m", name: "1M" },
+            ],
+          },
+          {
+            id: "fast",
+            name: "Fast",
+            category: "model_config",
+            type: "select",
+            currentValue: String(currentFast),
+            options: [
+              { value: "false", name: "Off" },
+              { value: "true", name: "Fast" },
+            ],
+          },
+        ];
+      case "composer-2":
+        return [
+          ...baseOptions,
+          {
+            id: "fast",
+            name: "Fast",
+            category: "model_config",
+            type: "select",
+            currentValue: String(currentFast),
+            options: [
+              { value: "false", name: "Off" },
+              { value: "true", name: "Fast" },
+            ],
+          },
+        ];
+      case "claude-opus-4-6":
+        return [
+          ...baseOptions,
+          {
+            id: "reasoning",
+            name: "Reasoning",
+            category: "thought_level",
+            type: "select",
+            currentValue: currentReasoning,
+            options: [
+              { value: "low", name: "Low" },
+              { value: "medium", name: "Medium" },
+              { value: "high", name: "High" },
+            ],
+          },
+          {
+            id: "thinking",
+            name: "Thinking",
+            category: "model_config",
+            type: "boolean",
+            currentValue: true,
+          },
+        ];
+      default:
+        return baseOptions;
+    }
+  }
+
+  return [
+    {
+      id: "model",
+      name: "Model",
+      category: "model",
+      type: "select" as const,
+      currentValue: currentModelId,
+      options: [
+        { value: "default", name: "Auto" },
+        { value: "composer-2", name: "Composer 2" },
+        { value: "composer-2[fast=true]", name: "Composer 2 Fast" },
+        { value: "gpt-5.3-codex[reasoning=medium,fast=false]", name: "Codex 5.3" },
+      ],
+    },
+  ];
+}
+
+const availableModes: ReadonlyArray<AcpSchema.SessionMode> = [
+  {
+    id: "ask",
+    name: "Ask",
+    description: "Request permission before making any changes",
+  },
+  {
+    id: "architect",
+    name: "Architect",
+    description: "Design and plan software systems without implementation",
+  },
+  {
+    id: "code",
+    name: "Code",
+    description: "Write and modify code with full tool access",
+  },
+];
+
+function modeState(): AcpSchema.SessionModeState {
+  return {
+    currentModeId,
+    availableModes,
+  };
+}
+
+const program = Effect.gen(function* () {
+  const agent = yield* EffectAcpAgent.AcpAgent;
+
+  yield* agent.handleInitialize((request) =>
+    Effect.sync(() => {
+      parameterizedModelPicker =
+        request.clientCapabilities?._meta?.parameterizedModelPicker === true;
+      return {
+        protocolVersion: 1,
+        agentCapabilities: { loadSession: true },
+      };
+    }),
+  );
+
+  yield* agent.handleAuthenticate(() => Effect.succeed({}));
+
+  yield* agent.handleCreateSession(() =>
+    Effect.succeed({
+      sessionId,
+      modes: modeState(),
+      configOptions: configOptions(),
+    }),
+  );
+
+  yield* agent.handleLoadSession((request) =>
+    agent.client
+      .sessionUpdate({
+        sessionId: String(request.sessionId ?? sessionId),
+        update: {
+          sessionUpdate: "user_message_chunk",
+          content: { type: "text", text: "replay" },
+        },
+      })
+      .pipe(
+        Effect.as({
+          modes: modeState(),
+          configOptions: configOptions(),
+        }),
+      ),
+  );
+
+  yield* agent.handleSetSessionConfigOption((request) =>
+    Effect.gen(function* () {
+      if (exitOnSetConfigOption) {
+        return yield* Effect.sync(() => {
+          process.exit(7);
+        });
+      }
+      if (failSetConfigOption) {
+        return yield* AcpError.AcpRequestError.invalidParams(
+          "Mock invalid params for session/set_config_option",
+          {
+            method: "session/set_config_option",
+            params: request,
+          },
+        );
+      }
+      if (request.configId === "mode" && typeof request.value === "string") {
+        currentModeId = request.value;
+      }
+      if (request.configId === "model" && typeof request.value === "string") {
+        currentModelId = request.value;
+      }
+      if (request.configId === "reasoning" && typeof request.value === "string") {
+        currentReasoning = request.value;
+      }
+      if (request.configId === "context" && typeof request.value === "string") {
+        currentContext = request.value;
+      }
+      if (request.configId === "fast") {
+        currentFast = request.value === true || request.value === "true";
+      }
+      return {
+        configOptions: configOptions(),
+      };
+    }),
+  );
+
+  yield* agent.handleCancel(({ sessionId }) =>
+    Effect.sync(() => {
+      cancelledSessions.add(String(sessionId ?? "mock-session-1"));
+    }),
+  );
+
+  yield* agent.handlePrompt((request) =>
+    Effect.gen(function* () {
+      const requestedSessionId = String(request.sessionId ?? sessionId);
+
+      if (emitInterleavedAssistantToolCalls) {
+        const toolCallId = "tool-call-1";
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "agent_message_chunk",
+            content: { type: "text", text: "before tool" },
+          },
+        });
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call",
+            toolCallId,
+            title: "Terminal",
+            kind: "execute",
+            status: "pending",
+            rawInput: {
+              command: ["echo", "hello"],
+            },
+          },
+        });
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call_update",
+            toolCallId,
+            status: "completed",
+            rawOutput: {
+              exitCode: 0,
+              stdout: "hello",
+              stderr: "",
+            },
+          },
+        });
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "agent_message_chunk",
+            content: { type: "text", text: "after tool" },
+          },
+        });
+
+        return { stopReason: "end_turn" };
+      }
+
+      if (emitToolCalls) {
+        const toolCallId = "tool-call-1";
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call",
+            toolCallId,
+            title: "Terminal",
+            kind: "execute",
+            status: "pending",
+            rawInput: {
+              command: ["cat", "server/package.json"],
+            },
+          },
+        });
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call_update",
+            toolCallId,
+            status: "in_progress",
+          },
+        });
+
+        const permission = yield* agent.client.requestPermission({
+          sessionId: requestedSessionId,
+          toolCall: {
+            toolCallId,
+            title: "`cat server/package.json`",
+            kind: "execute",
+            status: "pending",
+            content: [
+              {
+                type: "content",
+                content: {
+                  type: "text",
+                  text: "Not in allowlist: cat server/package.json",
+                },
+              },
+            ],
+          },
+          options: [
+            { optionId: "allow-once", name: "Allow once", kind: "allow_once" },
+            { optionId: "allow-always", name: "Allow always", kind: "allow_always" },
+            { optionId: "reject-once", name: "Reject", kind: "reject_once" },
+          ],
+        });
+
+        const cancelled =
+          cancelledSessions.delete(requestedSessionId) ||
+          permission.outcome.outcome === "cancelled";
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call_update",
+            toolCallId,
+            title: "Terminal",
+            kind: "execute",
+            status: "completed",
+            rawOutput: {
+              exitCode: 0,
+              stdout: '{ "name": "t3" }',
+              stderr: "",
+            },
+          },
+        });
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "agent_message_chunk",
+            content: { type: "text", text: "hello from mock" },
+          },
+        });
+
+        return { stopReason: cancelled ? "cancelled" : "end_turn" };
+      }
+
+      if (emitGenericToolPlaceholders) {
+        const toolCallId = "tool-call-generic-1";
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call",
+            toolCallId,
+            title: "Read File",
+            kind: "read",
+            status: "pending",
+            rawInput: {},
+          },
+        });
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call_update",
+            toolCallId,
+            status: "in_progress",
+          },
+        });
+
+        yield* agent.client.sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "tool_call_update",
+            toolCallId,
+            status: "completed",
+            rawOutput: {
+              content: "package.json\n",
+            },
+          },
+        });
+
+        return { stopReason: "end_turn" };
+      }
+
+      if (emitAskQuestion) {
+        yield* agent.client.extRequest("cursor/ask_question", {
+          toolCallId: "ask-question-tool-call-1",
+          title: "Question",
+          questions: [
+            {
+              id: "scope",
+              prompt: "Which scope?",
+              options: [
+                { id: "workspace", label: "Workspace" },
+                { id: "session", label: "Session" },
+              ],
+            },
+          ],
+        });
+
+        return { stopReason: "end_turn" };
+      }
+
+      yield* agent.client.sessionUpdate({
+        sessionId: requestedSessionId,
+        update: {
+          sessionUpdate: "plan",
+          entries: [
+            {
+              content: "Inspect mock ACP state",
+              priority: "high",
+              status: "completed",
+            },
+            {
+              content: "Implement the requested change",
+              priority: "high",
+              status: "in_progress",
+            },
+          ],
+        },
+      });
+
+      yield* agent.client.sessionUpdate({
+        sessionId: requestedSessionId,
+        update: {
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: promptResponseText ?? "hello from mock" },
+        },
+      });
+
+      return { stopReason: "end_turn" };
+    }),
+  );
+
+  yield* agent.handleUnknownExtRequest((method, params) => {
+    if (method !== "session/mode/set") {
+      return Effect.fail(AcpError.AcpRequestError.methodNotFound(method));
+    }
+
+    const nextModeId =
+      typeof params === "object" &&
+      params !== null &&
+      "modeId" in params &&
+      typeof params.modeId === "string"
+        ? params.modeId
+        : typeof params === "object" &&
+            params !== null &&
+            "mode" in params &&
+            typeof params.mode === "string"
+          ? params.mode
+          : undefined;
+    const requestedSessionId =
+      typeof params === "object" &&
+      params !== null &&
+      "sessionId" in params &&
+      typeof params.sessionId === "string"
+        ? params.sessionId
+        : sessionId;
+
+    if (typeof nextModeId === "string" && nextModeId.trim()) {
+      currentModeId = nextModeId.trim();
+      return agent.client
+        .sessionUpdate({
+          sessionId: requestedSessionId,
+          update: {
+            sessionUpdate: "current_mode_update",
+            currentModeId,
+          },
+        })
+        .pipe(Effect.as({}));
+    }
+
+    return Effect.succeed({});
+  });
+
+  return yield* Effect.never;
+}).pipe(
+  Effect.provide(
+    EffectAcpAgent.layerStdio(
+      requestLogPath
+        ? {
+            logIncoming: true,
+            logger: (event) => {
+              if (event.direction !== "incoming" || event.stage !== "raw") {
+                return Effect.void;
+              }
+              if (typeof event.payload !== "string") {
+                return Effect.void;
+              }
+              const payload = event.payload;
+              return Effect.sync(() => {
+                appendFileSync(
+                  requestLogPath,
+                  payload.endsWith("\n") ? payload : `${payload}\n`,
+                  "utf8",
+                );
+              });
+            },
+          }
+        : {},
+    ),
+  ),
+  Effect.scoped,
+  Effect.provide(NodeServices.layer),
+);
+
+NodeRuntime.runMain(program);
diff --git a/apps/server/scripts/cli.ts b/apps/server/scripts/cli.ts
index 299da67faba..c7f40de42d7 100644
--- a/apps/server/scripts/cli.ts
+++ b/apps/server/scripts/cli.ts
@@ -1,8 +1,13 @@
 #!/usr/bin/env node
-
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { Data, Effect, FileSystem, Logger, Option, Path } from "effect";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Logger from "effect/Logger";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
 import { Command, Flag } from "effect/unstable/cli";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
@@ -11,6 +16,7 @@ import {
   PUBLISH_ICON_OVERRIDES,
 } from "../../../scripts/lib/brand-assets.ts";
 import { resolveCatalogDependencies } from "../../../scripts/lib/resolve-catalog.ts";
+import { fromJsonStringPretty } from "@t3tools/shared/schemaJson";
 import rootPackageJson from "../../../package.json" with { type: "json" };
 import serverPackageJson from "../package.json" with { type: "json" };
 
@@ -30,6 +36,9 @@ interface PackageJson {
   overrides: Record<string, string>;
 }
 
+const PackageJsonPrettyJson = fromJsonStringPretty(Schema.Unknown);
+const encodePackageJson = Schema.encodeEffect(PackageJsonPrettyJson);
+
 class CliError extends Data.TaggedError("CliError")<{
   readonly message: string;
   readonly cause?: unknown;
@@ -147,13 +156,13 @@ const buildCmd = Command.make(
 
       yield* Effect.log("[cli] Running tsdown...");
       yield* runCommand(
-        ChildProcess.make({
+        ChildProcess.make(process.execPath, ["--run", "build:bundle"], {
           cwd: serverDir,
           stdout: config.verbose ? "inherit" : "ignore",
           stderr: "inherit",
-          // Windows needs shell mode to resolve .cmd shims (e.g. bun.cmd).
+          // Windows needs shell mode to resolve `.cmd` shims on PATH.
           shell: process.platform === "win32",
-        })`bun tsdown`,
+        }),
       );
 
       const webDist = path.join(repoRoot, "apps/web/dist");
@@ -203,10 +212,8 @@ const publishCmd = Command.make(
       }
 
       yield* Effect.acquireUseRelease(
-        // Acquire: backup package.json, resolve catalog: deps, strip devDependencies/scripts
+        // Acquire: backup package.json, resolve catalog dependencies, and strip devDependencies/scripts
         Effect.gen(function* () {
-          // Resolve catalog dependencies before any file mutations. If this throws,
-          // acquire fails and no release hook runs, so filesystem must still be untouched.
           const version = Option.getOrElse(config.appVersion, () => serverPackageJson.version);
           const pkg: PackageJson = {
             name: serverPackageJson.name,
@@ -216,25 +223,23 @@ const publishCmd = Command.make(
             version,
             engines: serverPackageJson.engines,
             files: serverPackageJson.files,
-            dependencies: serverPackageJson.dependencies,
-            overrides: rootPackageJson.overrides,
+            dependencies: resolveCatalogDependencies(
+              serverPackageJson.dependencies,
+              rootPackageJson.workspaces.catalog,
+              "apps/server",
+            ),
+            overrides: resolveCatalogDependencies(
+              rootPackageJson.overrides,
+              rootPackageJson.workspaces.catalog,
+              "apps/server",
+            ),
           };
 
-          pkg.dependencies = resolveCatalogDependencies(
-            pkg.dependencies,
-            rootPackageJson.workspaces.catalog,
-            "apps/server dependencies",
-          );
-          pkg.overrides = resolveCatalogDependencies(
-            pkg.overrides,
-            rootPackageJson.workspaces.catalog,
-            "root overrides",
-          );
-
           const original = yield* fs.readFileString(packageJsonPath);
+          const packageJsonString = yield* encodePackageJson(pkg);
           yield* fs.writeFileString(backupPath, original);
-          yield* fs.writeFileString(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`);
-          yield* Effect.log("[cli] Resolved package.json for publish");
+          yield* fs.writeFileString(packageJsonPath, `${packageJsonString}\n`);
+          yield* Effect.log("[cli] Prepared package.json for publish");
 
           const iconBackups = yield* applyPublishIconOverrides(repoRoot, serverDir);
           return { iconBackups };
diff --git a/apps/server/scripts/cursor-acp-model-mismatch-probe.ts b/apps/server/scripts/cursor-acp-model-mismatch-probe.ts
new file mode 100644
index 00000000000..04c2321870e
--- /dev/null
+++ b/apps/server/scripts/cursor-acp-model-mismatch-probe.ts
@@ -0,0 +1,439 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import process from "node:process";
+import readline from "node:readline";
+import * as NodeTimers from "node:timers";
+
+type JsonPrimitive = null | boolean | number | string;
+type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+type JsonRpcId = number | string;
+
+type JsonRpcMessage = {
+  jsonrpc?: string;
+  id?: JsonRpcId;
+  method?: string;
+  params?: JsonValue;
+  result?: JsonValue;
+  error?: JsonValue;
+  headers?: JsonValue;
+};
+
+type SelectLeafOption = {
+  value: string;
+  label?: string;
+  name?: string;
+};
+
+type SelectGroupOption = {
+  label?: string;
+  name?: string;
+  options: SelectLeafOption[];
+};
+
+type SessionConfigOption = {
+  id: string;
+  name?: string;
+  category?: string;
+  type?: string;
+  options?: Array<SelectLeafOption | SelectGroupOption>;
+};
+
+type SessionNewResult = {
+  sessionId: string;
+  configOptions?: SessionConfigOption[];
+};
+
+type SetConfigResult = {
+  configOptions?: SessionConfigOption[];
+};
+
+type PendingRequest = {
+  method: string;
+  resolve: (value: JsonValue | undefined) => void;
+  reject: (error: Error) => void;
+};
+
+const targetCwd = process.argv[2] ?? process.cwd();
+const targetModel = process.argv[3] ?? "gpt-5.4";
+const promptText = process.argv[4] ?? "helo";
+const targetReasoning = process.env.CURSOR_REASONING ?? "";
+const targetContext = process.env.CURSOR_CONTEXT ?? "";
+const targetFast = process.env.CURSOR_FAST ?? "";
+const agentBin = process.env.CURSOR_AGENT_BIN ?? "agent";
+const promptWaitMs = Number(process.env.CURSOR_PROMPT_WAIT_MS ?? "4000");
+const requestTimeoutMs = Number(process.env.CURSOR_REQUEST_TIMEOUT_MS ?? "20000");
+
+function logSection(title: string, value: unknown) {
+  process.stdout.write(`\n=== ${title} ===\n`);
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function fail(message: string): never {
+  throw new Error(message);
+}
+
+function asString(value: JsonValue | undefined): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function flattenSelectValues(option: SessionConfigOption | undefined): string[] {
+  if (!option || option.type !== "select" || !Array.isArray(option.options)) {
+    return [];
+  }
+
+  const values: string[] = [];
+  for (const entry of option.options) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    if ("value" in entry && typeof entry.value === "string") {
+      values.push(entry.value);
+      continue;
+    }
+    if ("options" in entry && Array.isArray(entry.options)) {
+      for (const nested of entry.options) {
+        if (nested && typeof nested === "object" && typeof nested.value === "string") {
+          values.push(nested.value);
+        }
+      }
+    }
+  }
+  return values;
+}
+
+function findConfigOption(
+  configOptions: SessionConfigOption[],
+  predicate: (option: SessionConfigOption) => boolean,
+): SessionConfigOption | undefined {
+  return configOptions.find(predicate);
+}
+
+function matchesKeyword(option: SessionConfigOption, keyword: string): boolean {
+  const haystack = `${option.id} ${option.name ?? ""}`.toLowerCase();
+  return haystack.includes(keyword.toLowerCase());
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => {
+    // @effect-diagnostics-next-line globalTimers:off - Standalone Node probe script, not an Effect runtime test.
+    NodeTimers.setTimeout(resolve, ms);
+  });
+}
+
+class JsonRpcChild {
+  readonly child: ChildProcessWithoutNullStreams;
+  readonly pending = new Map<JsonRpcId, PendingRequest>();
+  nextId = 1;
+  closed = false;
+
+  constructor(bin: string, args: string[], cwd: string) {
+    this.child = spawn(bin, args, {
+      cwd,
+      shell: process.platform === "win32",
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    this.child.on("exit", (code, signal) => {
+      this.closed = true;
+      const detail = `ACP process exited (code=${String(code)}, signal=${String(signal)})`;
+      for (const pending of this.pending.values()) {
+        pending.reject(new Error(`${detail} while waiting for ${pending.method}`));
+      }
+      this.pending.clear();
+    });
+
+    this.child.on("error", (error) => {
+      this.closed = true;
+      for (const pending of this.pending.values()) {
+        pending.reject(error);
+      }
+      this.pending.clear();
+    });
+
+    const stdout = readline.createInterface({ input: this.child.stdout });
+    stdout.on("line", (line) => {
+      void this.handleStdoutLine(line);
+    });
+
+    const stderr = readline.createInterface({ input: this.child.stderr });
+    stderr.on("line", (line) => {
+      process.stdout.write(`[stderr] ${line}\n`);
+    });
+  }
+
+  write(message: JsonRpcMessage) {
+    if (this.closed) {
+      fail("ACP process is already closed.");
+    }
+    const payload = JSON.stringify({
+      jsonrpc: "2.0",
+      headers: [],
+      ...message,
+    });
+    process.stdout.write(`>>> ${payload}\n`);
+    this.child.stdin.write(`${payload}\n`);
+  }
+
+  async request(method: string, params: JsonValue, timeoutMs = requestTimeoutMs) {
+    const id = this.nextId++;
+
+    const responsePromise = new Promise<JsonValue | undefined>((resolve, reject) => {
+      // @effect-diagnostics-next-line globalTimers:off - Standalone Node probe script request timeout.
+      const timeout = NodeTimers.setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for ${method} response after ${timeoutMs}ms.`));
+      }, timeoutMs);
+
+      this.pending.set(id, {
+        method,
+        resolve: (value) => {
+          NodeTimers.clearTimeout(timeout);
+          resolve(value);
+        },
+        reject: (error) => {
+          NodeTimers.clearTimeout(timeout);
+          reject(error);
+        },
+      });
+    });
+
+    this.write({
+      id,
+      method,
+      params,
+    });
+
+    return responsePromise;
+  }
+
+  notify(method: string, params: JsonValue) {
+    this.write({
+      method,
+      params,
+    });
+  }
+
+  respond(id: JsonRpcId, result: JsonValue) {
+    this.write({
+      id,
+      result,
+    });
+  }
+
+  respondError(id: JsonRpcId, code: number, message: string) {
+    this.write({
+      id,
+      error: {
+        code,
+        message,
+      },
+    });
+  }
+
+  async handleStdoutLine(line: string) {
+    if (line.trim().length === 0) {
+      return;
+    }
+
+    process.stdout.write(`<<< ${line}\n`);
+
+    let message: JsonRpcMessage;
+    try {
+      message = JSON.parse(line) as JsonRpcMessage;
+    } catch (error) {
+      process.stdout.write(`[parse-error] ${(error as Error).message}\n`);
+      return;
+    }
+
+    if (typeof message.id !== "undefined" && !message.method) {
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        return;
+      }
+      this.pending.delete(message.id);
+      if (typeof message.error !== "undefined") {
+        pending.reject(
+          new Error(`RPC ${pending.method} failed: ${JSON.stringify(message.error, null, 2)}`),
+        );
+        return;
+      }
+      pending.resolve(message.result);
+      return;
+    }
+
+    if (message.method === "session/request_permission" && typeof message.id !== "undefined") {
+      this.respond(message.id, {
+        outcome: {
+          outcome: "selected",
+          optionId: "allow",
+        },
+      });
+      return;
+    }
+
+    if (typeof message.id !== "undefined" && message.id !== "") {
+      this.respondError(
+        message.id,
+        -32601,
+        `Unhandled server request: ${message.method ?? "unknown"}`,
+      );
+    }
+  }
+
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.child.kill("SIGTERM");
+    await sleep(250);
+    if (!this.closed) {
+      this.child.kill("SIGKILL");
+    }
+  }
+}
+
+async function setSelectOptionIfAdvertised(
+  rpc: JsonRpcChild,
+  sessionId: string,
+  configOptions: SessionConfigOption[],
+  predicate: (option: SessionConfigOption) => boolean,
+  value: string,
+  label: string,
+) {
+  if (value.length === 0) {
+    return configOptions;
+  }
+
+  const option = findConfigOption(configOptions, predicate);
+  const values = flattenSelectValues(option);
+  if (!option || !values.includes(value)) {
+    logSection(`SKIP_${label}`, {
+      requestedValue: value,
+      availableValues: values,
+    });
+    return configOptions;
+  }
+
+  const response = (await rpc.request("session/set_config_option", {
+    sessionId,
+    configId: option.id,
+    value,
+  })) as SetConfigResult | null | undefined;
+
+  logSection(`SET_${label}_RESPONSE`, response);
+  return response?.configOptions ?? configOptions;
+}
+
+async function main() {
+  const rpc = new JsonRpcChild(agentBin, ["acp"], targetCwd);
+
+  try {
+    const initializeResponse = await rpc.request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+        _meta: {
+          parameterizedModelPicker: true,
+        },
+      },
+      clientInfo: {
+        name: "cursor-acp-model-mismatch-probe",
+        version: "0.0.0",
+      },
+    });
+    logSection("INITIALIZE_RESPONSE", initializeResponse);
+
+    const authenticateResponse = await rpc.request("authenticate", {
+      methodId: "cursor_login",
+    });
+    logSection("AUTHENTICATE_RESPONSE", authenticateResponse);
+
+    const sessionResponse = (await rpc.request("session/new", {
+      cwd: targetCwd,
+      mcpServers: [],
+    })) as SessionNewResult;
+    logSection("SESSION_NEW_RESPONSE", sessionResponse);
+
+    const sessionId = asString(sessionResponse.sessionId);
+    if (!sessionId) {
+      fail("session/new did not return a sessionId.");
+    }
+
+    let configOptions = sessionResponse.configOptions ?? [];
+    const modelConfig = findConfigOption(configOptions, (option) => option.category === "model");
+    const advertisedModels = flattenSelectValues(modelConfig);
+    logSection("ADVERTISED_MODEL_VALUES", advertisedModels);
+
+    if (!modelConfig || modelConfig.type !== "select") {
+      fail("Cursor ACP did not expose a select-type model config option.");
+    }
+
+    if (!advertisedModels.includes(targetModel)) {
+      fail(
+        `Cursor ACP did not advertise model ${JSON.stringify(targetModel)}. Advertised values: ${advertisedModels.join(", ")}`,
+      );
+    }
+
+    const setModelResponse = (await rpc.request("session/set_config_option", {
+      sessionId,
+      configId: modelConfig.id,
+      value: targetModel,
+    })) as SetConfigResult | null | undefined;
+    logSection("SET_MODEL_RESPONSE", setModelResponse);
+
+    configOptions = setModelResponse?.configOptions ?? configOptions;
+
+    configOptions = await setSelectOptionIfAdvertised(
+      rpc,
+      sessionId,
+      configOptions,
+      (option) => option.category === "thought_level",
+      targetReasoning,
+      "REASONING",
+    );
+
+    configOptions = await setSelectOptionIfAdvertised(
+      rpc,
+      sessionId,
+      configOptions,
+      (option) => option.category === "model_config" && matchesKeyword(option, "context"),
+      targetContext,
+      "CONTEXT",
+    );
+
+    configOptions = await setSelectOptionIfAdvertised(
+      rpc,
+      sessionId,
+      configOptions,
+      (option) => option.category === "model_config" && matchesKeyword(option, "fast"),
+      targetFast,
+      "FAST",
+    );
+
+    const promptResponse = await rpc.request("session/prompt", {
+      sessionId,
+      prompt: [
+        {
+          type: "text",
+          text: promptText,
+        },
+      ],
+    });
+    logSection("PROMPT_RESPONSE", promptResponse);
+
+    await sleep(promptWaitMs);
+    rpc.notify("session/cancel", { sessionId });
+  } finally {
+    await rpc.close();
+  }
+}
+
+void main().catch((error: unknown) => {
+  process.stderr.write(
+    `${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`,
+  );
+  process.exitCode = 1;
+});
diff --git a/apps/server/src/atomicWrite.ts b/apps/server/src/atomicWrite.ts
new file mode 100644
index 00000000000..764b6781919
--- /dev/null
+++ b/apps/server/src/atomicWrite.ts
@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Random from "effect/Random";
+
+export const writeFileStringAtomically = (input: {
+  readonly filePath: string;
+  readonly contents: string;
+}) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const tempFileId = yield* Random.nextUUIDv4;
+      const targetDirectory = path.dirname(input.filePath);
+
+      yield* fs.makeDirectory(targetDirectory, { recursive: true });
+      const tempDirectory = yield* fs.makeTempDirectoryScoped({
+        directory: targetDirectory,
+        prefix: `${path.basename(input.filePath)}.`,
+      });
+      const tempPath = path.join(tempDirectory, `${tempFileId}.tmp`);
+
+      yield* fs.writeFileString(tempPath, input.contents);
+      yield* fs.rename(tempPath, input.filePath);
+    }),
+  );
diff --git a/apps/server/src/attachmentPaths.ts b/apps/server/src/attachmentPaths.ts
index cd7e1faec85..8c6999a7341 100644
--- a/apps/server/src/attachmentPaths.ts
+++ b/apps/server/src/attachmentPaths.ts
@@ -1,9 +1,10 @@
-import path from "node:path";
+// @effect-diagnostics nodeBuiltinImport:off
+import NodePath from "node:path";
 
 export const ATTACHMENTS_ROUTE_PREFIX = "/attachments";
 
 export function normalizeAttachmentRelativePath(rawRelativePath: string): string | null {
-  const normalized = path.normalize(rawRelativePath).replace(/^[/\\]+/, "");
+  const normalized = NodePath.normalize(rawRelativePath).replace(/^[/\\]+/, "");
   if (normalized.length === 0 || normalized.startsWith("..") || normalized.includes("\0")) {
     return null;
   }
@@ -19,9 +20,9 @@ export function resolveAttachmentRelativePath(input: {
     return null;
   }
 
-  const attachmentsRoot = path.resolve(input.attachmentsDir);
-  const filePath = path.resolve(path.join(attachmentsRoot, normalizedRelativePath));
-  if (!filePath.startsWith(`${attachmentsRoot}${path.sep}`)) {
+  const attachmentsRoot = NodePath.resolve(input.attachmentsDir);
+  const filePath = NodePath.resolve(NodePath.join(attachmentsRoot, normalizedRelativePath));
+  if (!filePath.startsWith(`${attachmentsRoot}${NodePath.sep}`)) {
     return null;
   }
   return filePath;
diff --git a/apps/server/src/attachmentStore.test.ts b/apps/server/src/attachmentStore.test.ts
index e92c3d219d3..842667e61ba 100644
--- a/apps/server/src/attachmentStore.test.ts
+++ b/apps/server/src/attachmentStore.test.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/apps/server/src/attachmentStore.ts b/apps/server/src/attachmentStore.ts
index aa85b8c51a3..1e8dd93f603 100644
--- a/apps/server/src/attachmentStore.ts
+++ b/apps/server/src/attachmentStore.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 
diff --git a/apps/server/src/auth/Layers/AuthControlPlane.test.ts b/apps/server/src/auth/Layers/AuthControlPlane.test.ts
index 9fc091124be..23ea4e97958 100644
--- a/apps/server/src/auth/Layers/AuthControlPlane.test.ts
+++ b/apps/server/src/auth/Layers/AuthControlPlane.test.ts
@@ -1,8 +1,9 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
-import { ServerConfigShape } from "../../config.ts";
+import type { ServerConfigShape } from "../../config.ts";
 import { ServerConfig } from "../../config.ts";
 import { BootstrapCredentialServiceLive } from "./BootstrapCredentialService.ts";
 import { ServerSecretStoreLive } from "./ServerSecretStore.ts";
diff --git a/apps/server/src/auth/Layers/AuthControlPlane.ts b/apps/server/src/auth/Layers/AuthControlPlane.ts
index 98b2107800c..aea07fd286f 100644
--- a/apps/server/src/auth/Layers/AuthControlPlane.ts
+++ b/apps/server/src/auth/Layers/AuthControlPlane.ts
@@ -1,5 +1,7 @@
 import type { AuthClientSession, AuthPairingLink } from "@t3tools/contracts";
-import { DateTime, Effect, Layer } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import { BootstrapCredentialServiceLive } from "./BootstrapCredentialService.ts";
 import { ServerSecretStoreLive } from "./ServerSecretStore.ts";
@@ -10,8 +12,10 @@ import { layerConfig as SqlitePersistenceLayerLive } from "../../persistence/Lay
 import {
   AuthControlPlane,
   AuthControlPlaneError,
-  AuthControlPlaneShape,
   DEFAULT_SESSION_SUBJECT,
+} from "../Services/AuthControlPlane.ts";
+import type {
+  AuthControlPlaneShape,
   IssuedBearerSession,
   IssuedPairingLink,
 } from "../Services/AuthControlPlane.ts";
diff --git a/apps/server/src/auth/Layers/BootstrapCredentialService.test.ts b/apps/server/src/auth/Layers/BootstrapCredentialService.test.ts
index ec110ee96fb..110dae84379 100644
--- a/apps/server/src/auth/Layers/BootstrapCredentialService.test.ts
+++ b/apps/server/src/auth/Layers/BootstrapCredentialService.test.ts
@@ -1,7 +1,9 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Duration, Effect, Layer } from "effect";
-import { TestClock } from "effect/testing";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as TestClock from "effect/testing/TestClock";
 
 import type { ServerConfigShape } from "../../config.ts";
 import { ServerConfig } from "../../config.ts";
diff --git a/apps/server/src/auth/Layers/BootstrapCredentialService.ts b/apps/server/src/auth/Layers/BootstrapCredentialService.ts
index 5539f62c708..77d865eca68 100644
--- a/apps/server/src/auth/Layers/BootstrapCredentialService.ts
+++ b/apps/server/src/auth/Layers/BootstrapCredentialService.ts
@@ -1,6 +1,12 @@
 import type { AuthPairingLink } from "@t3tools/contracts";
-import { DateTime, Duration, Effect, Layer, PubSub, Ref, Stream } from "effect";
-import { Option } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+import * as Option from "effect/Option";
 
 import { ServerConfig } from "../../config.ts";
 import { AuthPairingLinkRepositoryLive } from "../../persistence/Layers/AuthPairingLinks.ts";
diff --git a/apps/server/src/auth/Layers/ServerAuth.test.ts b/apps/server/src/auth/Layers/ServerAuth.test.ts
index 0c3d71cc9fd..748f4ded731 100644
--- a/apps/server/src/auth/Layers/ServerAuth.test.ts
+++ b/apps/server/src/auth/Layers/ServerAuth.test.ts
@@ -1,6 +1,7 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import type { ServerConfigShape } from "../../config.ts";
 import { ServerConfig } from "../../config.ts";
diff --git a/apps/server/src/auth/Layers/ServerAuth.ts b/apps/server/src/auth/Layers/ServerAuth.ts
index cb1c6fa4c41..238475aca37 100644
--- a/apps/server/src/auth/Layers/ServerAuth.ts
+++ b/apps/server/src/auth/Layers/ServerAuth.ts
@@ -6,7 +6,10 @@ import {
   type AuthSessionState,
   type AuthWebSocketTokenResult,
 } from "@t3tools/contracts";
-import { DateTime, Effect, Layer, Option } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 
 import { AuthControlPlane } from "../Services/AuthControlPlane.ts";
diff --git a/apps/server/src/auth/Layers/ServerAuthPolicy.test.ts b/apps/server/src/auth/Layers/ServerAuthPolicy.test.ts
index 13ca0233ee1..fcc56686d8f 100644
--- a/apps/server/src/auth/Layers/ServerAuthPolicy.test.ts
+++ b/apps/server/src/auth/Layers/ServerAuthPolicy.test.ts
@@ -1,6 +1,7 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import type { ServerConfigShape } from "../../config.ts";
 import { ServerConfig } from "../../config.ts";
diff --git a/apps/server/src/auth/Layers/ServerAuthPolicy.ts b/apps/server/src/auth/Layers/ServerAuthPolicy.ts
index 43735b47618..2c000bc1883 100644
--- a/apps/server/src/auth/Layers/ServerAuthPolicy.ts
+++ b/apps/server/src/auth/Layers/ServerAuthPolicy.ts
@@ -1,5 +1,6 @@
 import type { ServerAuthDescriptor } from "@t3tools/contracts";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import { ServerConfig } from "../../config.ts";
 import { ServerAuthPolicy, type ServerAuthPolicyShape } from "../Services/ServerAuthPolicy.ts";
diff --git a/apps/server/src/auth/Layers/ServerSecretStore.test.ts b/apps/server/src/auth/Layers/ServerSecretStore.test.ts
index 7e6352eec25..30b5a9d35ed 100644
--- a/apps/server/src/auth/Layers/ServerSecretStore.test.ts
+++ b/apps/server/src/auth/Layers/ServerSecretStore.test.ts
@@ -1,6 +1,11 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Cause, Deferred, Effect, FileSystem, Layer, Ref } from "effect";
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
 import * as PlatformError from "effect/PlatformError";
 
 import { ServerConfig } from "../../config.ts";
diff --git a/apps/server/src/auth/Layers/ServerSecretStore.ts b/apps/server/src/auth/Layers/ServerSecretStore.ts
index c8acf11babe..d80242280bd 100644
--- a/apps/server/src/auth/Layers/ServerSecretStore.ts
+++ b/apps/server/src/auth/Layers/ServerSecretStore.ts
@@ -1,6 +1,10 @@
 import * as Crypto from "node:crypto";
 
-import { Effect, FileSystem, Layer, Path, Predicate } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Predicate from "effect/Predicate";
 import * as PlatformError from "effect/PlatformError";
 
 import { ServerConfig } from "../../config.ts";
diff --git a/apps/server/src/auth/Layers/SessionCredentialService.test.ts b/apps/server/src/auth/Layers/SessionCredentialService.test.ts
index bafd9c85c2c..5609c2fdea2 100644
--- a/apps/server/src/auth/Layers/SessionCredentialService.test.ts
+++ b/apps/server/src/auth/Layers/SessionCredentialService.test.ts
@@ -1,7 +1,9 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Duration, Effect, Layer } from "effect";
-import { TestClock } from "effect/testing";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as TestClock from "effect/testing/TestClock";
 
 import type { ServerConfigShape } from "../../config.ts";
 import { ServerConfig } from "../../config.ts";
diff --git a/apps/server/src/auth/Layers/SessionCredentialService.ts b/apps/server/src/auth/Layers/SessionCredentialService.ts
index 5ff4bbffff2..31e2b13240a 100644
--- a/apps/server/src/auth/Layers/SessionCredentialService.ts
+++ b/apps/server/src/auth/Layers/SessionCredentialService.ts
@@ -1,6 +1,14 @@
 import { AuthSessionId, type AuthClientMetadata, type AuthClientSession } from "@t3tools/contracts";
-import { Clock, DateTime, Duration, Effect, Layer, PubSub, Ref, Schema, Stream } from "effect";
-import { Option } from "effect";
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as Option from "effect/Option";
 
 import { ServerConfig } from "../../config.ts";
 import { AuthSessionRepositoryLive } from "../../persistence/Layers/AuthSessions.ts";
@@ -192,6 +200,7 @@ export const makeSessionCredentialService = Effect.gen(function* () {
       ),
     );
 
+  const encodeClaims = Schema.encodeEffect(Schema.fromJsonString(SessionClaims));
   const issue: SessionCredentialServiceShape["issue"] = (input) =>
     Effect.gen(function* () {
       const sessionId = AuthSessionId.make(crypto.randomUUID());
@@ -209,7 +218,13 @@ export const makeSessionCredentialService = Effect.gen(function* () {
         iat: issuedAt.epochMilliseconds,
         exp: expiresAt.epochMilliseconds,
       };
-      const encodedPayload = base64UrlEncode(JSON.stringify(claims));
+
+      const encodedPayload = yield* encodeClaims(claims).pipe(
+        Effect.map(base64UrlEncode),
+        Effect.mapError(
+          (cause) => new SessionCredentialError({ message: "Failed to encode claims", cause }),
+        ),
+      );
       const signature = signPayload(encodedPayload, signingSecret);
       const client = input?.client ?? createDefaultClientMetadata();
       yield* authSessions.create({
@@ -297,12 +312,19 @@ export const makeSessionCredentialService = Effect.gen(function* () {
         });
       }
 
+      const expiresAt = DateTime.make(claims.exp);
+      if (Option.isNone(expiresAt)) {
+        return yield* new SessionCredentialError({
+          message: "Invalid `exp` claim",
+        });
+      }
+
       return {
         sessionId: claims.sid,
         token,
         method: claims.method,
         client: toClientMetadata(row.value.client),
-        expiresAt: DateTime.makeUnsafe(claims.exp),
+        expiresAt: expiresAt.value,
         subject: claims.sub,
         role: claims.role,
       } satisfies VerifiedSession;
@@ -317,6 +339,7 @@ export const makeSessionCredentialService = Effect.gen(function* () {
       ),
     );
 
+  const encodeWsClaims = Schema.encodeEffect(Schema.fromJsonString(WebSocketClaims));
   const issueWebSocketToken: SessionCredentialServiceShape["issueWebSocketToken"] = (
     sessionId,
     input,
@@ -333,7 +356,12 @@ export const makeSessionCredentialService = Effect.gen(function* () {
         iat: issuedAt.epochMilliseconds,
         exp: expiresAt.epochMilliseconds,
       };
-      const encodedPayload = base64UrlEncode(JSON.stringify(claims));
+      const encodedPayload = yield* encodeWsClaims(claims).pipe(
+        Effect.map(base64UrlEncode),
+        Effect.mapError(
+          (cause) => new SessionCredentialError({ message: "Failed to encode claims", cause }),
+        ),
+      );
       const signature = signPayload(encodedPayload, signingSecret);
       return {
         token: `${encodedPayload}.${signature}`,
diff --git a/apps/server/src/auth/Services/AuthControlPlane.ts b/apps/server/src/auth/Services/AuthControlPlane.ts
index b59e330bcaa..b5e67639a65 100644
--- a/apps/server/src/auth/Services/AuthControlPlane.ts
+++ b/apps/server/src/auth/Services/AuthControlPlane.ts
@@ -4,8 +4,12 @@ import type {
   AuthPairingLink,
   AuthSessionId,
 } from "@t3tools/contracts";
-import { Data, DateTime, Duration, Effect, Context } from "effect";
-import { SessionRole } from "./SessionCredentialService";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import type { SessionRole } from "./SessionCredentialService.ts";
 
 export const DEFAULT_SESSION_SUBJECT = "cli-issued-session";
 
diff --git a/apps/server/src/auth/Services/BootstrapCredentialService.ts b/apps/server/src/auth/Services/BootstrapCredentialService.ts
index bcb6119a22e..70dd1d5aead 100644
--- a/apps/server/src/auth/Services/BootstrapCredentialService.ts
+++ b/apps/server/src/auth/Services/BootstrapCredentialService.ts
@@ -1,6 +1,10 @@
 import type { AuthPairingLink, ServerAuthBootstrapMethod } from "@t3tools/contracts";
-import { Data, DateTime, Duration, Context } from "effect";
-import type { Effect, Stream } from "effect";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
 export type BootstrapCredentialRole = "owner" | "client";
 
diff --git a/apps/server/src/auth/Services/ServerAuth.ts b/apps/server/src/auth/Services/ServerAuth.ts
index 07be98269bf..3ea93b77f94 100644
--- a/apps/server/src/auth/Services/ServerAuth.ts
+++ b/apps/server/src/auth/Services/ServerAuth.ts
@@ -12,8 +12,10 @@ import type {
   ServerAuthSessionMethod,
   AuthWebSocketTokenResult,
 } from "@t3tools/contracts";
-import { Data, DateTime, Context } from "effect";
-import type { Effect } from "effect";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 import type * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import type { SessionRole } from "./SessionCredentialService.ts";
 
diff --git a/apps/server/src/auth/Services/ServerAuthPolicy.ts b/apps/server/src/auth/Services/ServerAuthPolicy.ts
index 530d776998c..5d9ef68cf95 100644
--- a/apps/server/src/auth/Services/ServerAuthPolicy.ts
+++ b/apps/server/src/auth/Services/ServerAuthPolicy.ts
@@ -1,6 +1,6 @@
 import type { ServerAuthDescriptor } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 export interface ServerAuthPolicyShape {
   readonly getDescriptor: () => Effect.Effect<ServerAuthDescriptor>;
diff --git a/apps/server/src/auth/Services/ServerSecretStore.ts b/apps/server/src/auth/Services/ServerSecretStore.ts
index 7d97b4c3a10..f5c6f6dfef4 100644
--- a/apps/server/src/auth/Services/ServerSecretStore.ts
+++ b/apps/server/src/auth/Services/ServerSecretStore.ts
@@ -1,5 +1,6 @@
-import { Data, Context } from "effect";
-import type { Effect } from "effect";
+import * as Data from "effect/Data";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 export class SecretStoreError extends Data.TaggedError("SecretStoreError")<{
   readonly message: string;
diff --git a/apps/server/src/auth/Services/SessionCredentialService.ts b/apps/server/src/auth/Services/SessionCredentialService.ts
index 3d72b5a636c..7dc049c910e 100644
--- a/apps/server/src/auth/Services/SessionCredentialService.ts
+++ b/apps/server/src/auth/Services/SessionCredentialService.ts
@@ -4,8 +4,12 @@ import type {
   AuthSessionId,
   ServerAuthSessionMethod,
 } from "@t3tools/contracts";
-import { Data, DateTime, Duration, Context } from "effect";
-import type { Effect, Stream } from "effect";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
 export type SessionRole = "owner" | "client";
 
diff --git a/apps/server/src/auth/http.ts b/apps/server/src/auth/http.ts
index 76c14646e98..670ff5abbff 100644
--- a/apps/server/src/auth/http.ts
+++ b/apps/server/src/auth/http.ts
@@ -6,12 +6,15 @@ import {
   AuthRevokePairingLinkInput,
   type AuthWebSocketTokenResult,
 } from "@t3tools/contracts";
-import { DateTime, Effect, Schema } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
 import { AuthError, ServerAuth } from "./Services/ServerAuth.ts";
 import { SessionCredentialService } from "./Services/SessionCredentialService.ts";
 import { deriveAuthClientMetadata } from "./utils.ts";
+import { browserApiCorsHeaders } from "../httpCors.ts";
 
 export const respondToAuthError = (error: AuthError) =>
   Effect.gen(function* () {
@@ -25,7 +28,7 @@ export const respondToAuthError = (error: AuthError) =>
       {
         error: error.message,
       },
-      { status: error.status ?? 500 },
+      { status: error.status ?? 500, headers: browserApiCorsHeaders },
     );
   });
 
@@ -36,7 +39,10 @@ export const authSessionRouteLayer = HttpRouter.add(
     const request = yield* HttpServerRequest.HttpServerRequest;
     const serverAuth = yield* ServerAuth;
     const session = yield* serverAuth.getSessionState(request);
-    return HttpServerResponse.jsonUnsafe(session, { status: 200 });
+    return HttpServerResponse.jsonUnsafe(session, {
+      status: 200,
+      headers: browserApiCorsHeaders,
+    });
   }),
 );
 
@@ -79,7 +85,10 @@ export const authBootstrapRouteLayer = HttpRouter.add(
       deriveAuthClientMetadata({ request }),
     );
 
-    return yield* HttpServerResponse.jsonUnsafe(result.response, { status: 200 }).pipe(
+    return yield* HttpServerResponse.jsonUnsafe(result.response, {
+      status: 200,
+      headers: browserApiCorsHeaders,
+    }).pipe(
       HttpServerResponse.setCookie(sessions.cookieName, result.sessionToken, {
         expires: DateTime.toDate(result.response.expiresAt),
         httpOnly: true,
@@ -112,6 +121,7 @@ export const authBearerBootstrapRouteLayer = HttpRouter.add(
     );
     return HttpServerResponse.jsonUnsafe(result satisfies AuthBearerBootstrapResult, {
       status: 200,
+      headers: browserApiCorsHeaders,
     });
   }).pipe(Effect.catchTag("AuthError", (error) => respondToAuthError(error))),
 );
@@ -126,6 +136,7 @@ export const authWebSocketTokenRouteLayer = HttpRouter.add(
     const result = yield* serverAuth.issueWebSocketToken(session);
     return HttpServerResponse.jsonUnsafe(result satisfies AuthWebSocketTokenResult, {
       status: 200,
+      headers: browserApiCorsHeaders,
     });
   }).pipe(Effect.catchTag("AuthError", (error) => respondToAuthError(error))),
 );
diff --git a/apps/server/src/auth/utils.test.ts b/apps/server/src/auth/utils.test.ts
index a767b77de11..e7a540d81ba 100644
--- a/apps/server/src/auth/utils.test.ts
+++ b/apps/server/src/auth/utils.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { deriveAuthClientMetadata } from "./utils";
+import { deriveAuthClientMetadata } from "./utils.ts";
 
 describe("deriveAuthClientMetadata", () => {
   it("labels Electron user agents as Electron instead of Chrome", () => {
diff --git a/apps/server/src/cli.test.ts b/apps/server/src/bin.test.ts
similarity index 94%
rename from apps/server/src/cli.test.ts
rename to apps/server/src/bin.test.ts
index 7ebde01067a..a7bf2686101 100644
--- a/apps/server/src/cli.test.ts
+++ b/apps/server/src/bin.test.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics-next-line nodeBuiltinImport:off - NodeHttpServer.layer takes `NodeHttp.createServer` as arg
 import * as NodeHttp from "node:http";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -5,7 +6,7 @@ import { join } from "node:path";
 
 import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { NetService } from "@t3tools/shared/Net";
+import * as NetService from "@t3tools/shared/Net";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -15,9 +16,8 @@ import * as CliError from "effect/unstable/cli/CliError";
 import * as TestConsole from "effect/testing/TestConsole";
 import { Command } from "effect/unstable/cli";
 
-import { cli } from "./cli.ts";
+import { cli } from "./bin.ts";
 import { deriveServerPaths, ServerConfig, type ServerConfigShape } from "./config.ts";
-import { OrchestrationEngineService } from "./orchestration/Services/OrchestrationEngine.ts";
 import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
 import { OrchestrationLayerLive } from "./orchestration/runtimeLayer.ts";
 import {
@@ -76,6 +76,8 @@ const makeCliTestServerConfig = (baseDir: string) =>
       desktopBootstrapToken: undefined,
       autoBootstrapProjectFromCwd: false,
       logWebSocketEvents: false,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
     } satisfies ServerConfigShape;
   });
 
@@ -137,7 +139,7 @@ const withLiveProjectCliServer = <A, E, R>(baseDir: string, run: () => Effect.Ef
         }
         yield* persistServerRuntimeState({
           path: config.serverRuntimeStatePath,
-          state: makePersistedServerRuntimeState({
+          state: yield* makePersistedServerRuntimeState({
             config,
             port: address.port,
           }),
@@ -147,7 +149,7 @@ const withLiveProjectCliServer = <A, E, R>(baseDir: string, run: () => Effect.Ef
     );
   });
 
-it.layer(NodeServices.layer)("cli log-level parsing", (it) => {
+it.layer(NodeServices.layer)("bin cli parsing", (it) => {
   it.effect("accepts the built-in lowercase log-level flag values", () =>
     runCliWithRuntime(["--log-level", "debug", "--version"]),
   );
@@ -178,6 +180,7 @@ it.layer(NodeServices.layer)("cli log-level parsing", (it) => {
       const createdOutput = yield* captureStdout(
         runCli(["auth", "pairing", "create", "--base-dir", baseDir, "--json"]),
       );
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
       const created = JSON.parse(createdOutput.output) as {
         readonly id: string;
         readonly credential: string;
@@ -185,6 +188,7 @@ it.layer(NodeServices.layer)("cli log-level parsing", (it) => {
       const listedOutput = yield* captureStdout(
         runCli(["auth", "pairing", "list", "--base-dir", baseDir, "--json"]),
       );
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
       const listed = JSON.parse(listedOutput.output) as ReadonlyArray<{
         readonly id: string;
         readonly credential?: string;
@@ -206,6 +210,7 @@ it.layer(NodeServices.layer)("cli log-level parsing", (it) => {
       const issuedOutput = yield* captureStdout(
         runCli(["auth", "session", "issue", "--base-dir", baseDir, "--json"]),
       );
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
       const issued = JSON.parse(issuedOutput.output) as {
         readonly sessionId: string;
         readonly token: string;
@@ -214,6 +219,7 @@ it.layer(NodeServices.layer)("cli log-level parsing", (it) => {
       const listedOutput = yield* captureStdout(
         runCli(["auth", "session", "list", "--base-dir", baseDir, "--json"]),
       );
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
       const listed = JSON.parse(listedOutput.output) as ReadonlyArray<{
         readonly sessionId: string;
         readonly token?: string;
@@ -314,8 +320,8 @@ it.layer(NodeServices.layer)("cli log-level parsing", (it) => {
             "--base-dir",
             baseDir,
           ]);
-          const orchestrationEngine = yield* OrchestrationEngineService;
-          const readModel = yield* orchestrationEngine.getReadModel();
+          const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
+          const readModel = yield* projectionSnapshotQuery.getSnapshot();
           const addedProject = readModel.projects.find(
             (project) => project.workspaceRoot === workspaceRoot && project.deletedAt === null,
           );
diff --git a/apps/server/src/bin.ts b/apps/server/src/bin.ts
index 063d43326c3..4e829332c17 100644
--- a/apps/server/src/bin.ts
+++ b/apps/server/src/bin.ts
@@ -4,14 +4,25 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { Command } from "effect/unstable/cli";
 
-import { NetService } from "@t3tools/shared/Net";
-import { cli } from "./cli";
-import { version } from "../package.json" with { type: "json" };
+import * as NetService from "@t3tools/shared/Net";
+import packageJson from "../package.json" with { type: "json" };
+import { authCommand } from "./cli/auth.ts";
+import { sharedServerCommandFlags } from "./cli/config.ts";
+import { projectCommand } from "./cli/project.ts";
+import { runServerCommand, serveCommand, startCommand } from "./cli/server.ts";
 
 const CliRuntimeLayer = Layer.mergeAll(NodeServices.layer, NetService.layer);
 
-Command.run(cli, { version }).pipe(
-  Effect.scoped,
-  Effect.provide(CliRuntimeLayer),
-  NodeRuntime.runMain,
+export const cli = Command.make("t3", { ...sharedServerCommandFlags }).pipe(
+  Command.withDescription("Run the T3 Code server."),
+  Command.withHandler((flags) => runServerCommand(flags)),
+  Command.withSubcommands([startCommand, serveCommand, authCommand, projectCommand]),
 );
+
+if (import.meta.main) {
+  Command.run(cli, { version: packageJson.version }).pipe(
+    Effect.scoped,
+    Effect.provide(CliRuntimeLayer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/apps/server/src/bootstrap.test.ts b/apps/server/src/bootstrap.test.ts
index 3fce6af9c42..19c84aa9d01 100644
--- a/apps/server/src/bootstrap.test.ts
+++ b/apps/server/src/bootstrap.test.ts
@@ -1,16 +1,18 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import * as NFS from "node:fs";
 import * as path from "node:path";
 import { execFileSync, spawn } from "node:child_process";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
-import { FileSystem, Schema } from "effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
-import { TestClock } from "effect/testing";
+import * as TestClock from "effect/testing/TestClock";
 import { vi } from "vitest";
 
-import { readBootstrapEnvelope, resolveFdPath } from "./bootstrap";
+import { readBootstrapEnvelope, resolveFdPath } from "./bootstrap.ts";
 import { assertNone, assertSome } from "@effect/vitest/utils";
 
 const openSyncInterceptor = vi.hoisted(() => ({ failPath: null as string | null }));
@@ -36,6 +38,7 @@ vi.mock("node:fs", async (importOriginal) => {
 });
 
 const TestEnvelopeSchema = Schema.Struct({ mode: Schema.String });
+const encodeTestEnvelopeSchema = Schema.encodeEffect(Schema.fromJsonString(TestEnvelopeSchema));
 
 it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
   it.effect("uses platform-specific fd paths", () =>
@@ -53,9 +56,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
 
       yield* fs.writeFileString(
         filePath,
-        `${yield* Schema.encodeEffect(Schema.fromJsonString(TestEnvelopeSchema))({
-          mode: "desktop",
-        })}\n`,
+        `${yield* encodeTestEnvelopeSchema({ mode: "desktop" })}\n`,
       );
 
       const fd = yield* Effect.acquireRelease(
@@ -77,9 +78,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
 
       yield* fs.writeFileString(
         filePath,
-        `${yield* Schema.encodeEffect(Schema.fromJsonString(TestEnvelopeSchema))({
-          mode: "desktop",
-        })}\n`,
+        `${yield* encodeTestEnvelopeSchema({ mode: "desktop" })}\n`,
       );
 
       // Open without acquireRelease: the direct-stream fallback uses autoClose: true,
diff --git a/apps/server/src/bootstrap.ts b/apps/server/src/bootstrap.ts
index 0fb13522686..9ad6328798d 100644
--- a/apps/server/src/bootstrap.ts
+++ b/apps/server/src/bootstrap.ts
@@ -1,9 +1,15 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import * as NFS from "node:fs";
 import * as Net from "node:net";
 import * as readline from "node:readline";
 import type { Readable } from "node:stream";
 
-import { Data, Effect, Option, Predicate, Result, Schema } from "effect";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
 import { decodeJsonResult } from "@t3tools/shared/schemaJson";
 
 class BootstrapError extends Data.TaggedError("BootstrapError")<{
diff --git a/apps/server/src/checkpointing/Errors.ts b/apps/server/src/checkpointing/Errors.ts
index cb873559c16..1d8e113a4eb 100644
--- a/apps/server/src/checkpointing/Errors.ts
+++ b/apps/server/src/checkpointing/Errors.ts
@@ -1,6 +1,6 @@
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 import type { ProjectionRepositoryError } from "../persistence/Errors.ts";
-import { GitCommandError } from "@t3tools/contracts";
+import type { VcsError } from "@t3tools/contracts";
 
 /**
  * CheckpointUnavailableError - Expected checkpoint does not exist.
@@ -35,9 +35,6 @@ export class CheckpointInvariantError extends Schema.TaggedErrorClass<Checkpoint
   }
 }
 
-export type CheckpointStoreError =
-  | GitCommandError
-  | CheckpointInvariantError
-  | CheckpointUnavailableError;
+export type CheckpointStoreError = VcsError | CheckpointInvariantError | CheckpointUnavailableError;
 
 export type CheckpointServiceError = CheckpointStoreError | ProjectionRepositoryError;
diff --git a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.test.ts b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.test.ts
index 21cbe1509aa..ecbbbeae9f8 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.test.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.test.ts
@@ -1,5 +1,7 @@
 import { CheckpointRef, ProjectId, ThreadId, TurnId } from "@t3tools/contracts";
-import { Effect, Layer, Option } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import { describe, expect, it } from "vitest";
 
 import {
@@ -39,15 +41,115 @@ function makeThreadCheckpointContext(input: {
 }
 
 describe("CheckpointDiffQueryLive", () => {
+  it("uses the narrow full-thread context lookup for all-turns diffs", async () => {
+    const projectId = ProjectId.make("project-full-thread");
+    const threadId = ThreadId.make("thread-full-thread");
+    const toCheckpointRef = checkpointRefForThreadTurn(threadId, 4);
+    let getThreadCheckpointContextCalls = 0;
+    let getFullThreadDiffContextCalls = 0;
+    const diffCheckpointsCalls: Array<{
+      readonly fromCheckpointRef: CheckpointRef;
+      readonly toCheckpointRef: CheckpointRef;
+      readonly cwd: string;
+      readonly ignoreWhitespace: boolean;
+    }> = [];
+
+    const checkpointStore: CheckpointStoreShape = {
+      isGitRepository: () => Effect.succeed(true),
+      captureCheckpoint: () => Effect.void,
+      hasCheckpointRef: () => Effect.succeed(true),
+      restoreCheckpoint: () => Effect.succeed(true),
+      diffCheckpoints: ({ fromCheckpointRef, toCheckpointRef, cwd, ignoreWhitespace }) =>
+        Effect.sync(() => {
+          diffCheckpointsCalls.push({
+            fromCheckpointRef,
+            toCheckpointRef,
+            cwd,
+            ignoreWhitespace,
+          });
+          return "full thread diff patch";
+        }),
+      deleteCheckpointRefs: () => Effect.void,
+    };
+
+    const layer = CheckpointDiffQueryLive.pipe(
+      Layer.provideMerge(Layer.succeed(CheckpointStore, checkpointStore)),
+      Layer.provideMerge(
+        Layer.succeed(ProjectionSnapshotQuery, {
+          getCommandReadModel: () =>
+            Effect.die("CheckpointDiffQuery should not request the command read model"),
+          getSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
+          getShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the orchestration shell snapshot"),
+          getArchivedShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request archived shell snapshots"),
+          getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 0 }),
+          getCounts: () => Effect.succeed({ projectCount: 0, threadCount: 0 }),
+          getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.succeed(Option.none()),
+          getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+          getThreadCheckpointContext: () =>
+            Effect.sync(() => {
+              getThreadCheckpointContextCalls += 1;
+              return Option.none();
+            }),
+          getFullThreadDiffContext: () =>
+            Effect.sync(() => {
+              getFullThreadDiffContextCalls += 1;
+              return Option.some({
+                threadId,
+                projectId,
+                workspaceRoot: "/tmp/workspace",
+                worktreePath: "/tmp/worktree",
+                latestCheckpointTurnCount: 4,
+                toCheckpointRef,
+              });
+            }),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
+        }),
+      ),
+    );
+
+    const result = await Effect.runPromise(
+      Effect.gen(function* () {
+        const query = yield* CheckpointDiffQuery;
+        return yield* query.getFullThreadDiff({
+          threadId,
+          toTurnCount: 4,
+          ignoreWhitespace: true,
+        });
+      }).pipe(Effect.provide(layer)),
+    );
+
+    expect(getThreadCheckpointContextCalls).toBe(0);
+    expect(getFullThreadDiffContextCalls).toBe(1);
+    expect(diffCheckpointsCalls).toEqual([
+      {
+        cwd: "/tmp/worktree",
+        fromCheckpointRef: checkpointRefForThreadTurn(threadId, 0),
+        toCheckpointRef,
+        ignoreWhitespace: true,
+      },
+    ]);
+    expect(result).toEqual({
+      threadId,
+      fromTurnCount: 0,
+      toTurnCount: 4,
+      diff: "full thread diff patch",
+    });
+  });
+
   it("computes diffs using canonical turn-0 checkpoint refs", async () => {
     const projectId = ProjectId.make("project-1");
     const threadId = ThreadId.make("thread-1");
     const toCheckpointRef = checkpointRefForThreadTurn(threadId, 1);
-    const hasCheckpointRefCalls: Array<CheckpointRef> = [];
     const diffCheckpointsCalls: Array<{
       readonly fromCheckpointRef: CheckpointRef;
       readonly toCheckpointRef: CheckpointRef;
       readonly cwd: string;
+      readonly ignoreWhitespace: boolean;
     }> = [];
 
     const threadCheckpointContext = makeThreadCheckpointContext({
@@ -62,15 +164,16 @@ describe("CheckpointDiffQueryLive", () => {
     const checkpointStore: CheckpointStoreShape = {
       isGitRepository: () => Effect.succeed(true),
       captureCheckpoint: () => Effect.void,
-      hasCheckpointRef: ({ checkpointRef }) =>
-        Effect.sync(() => {
-          hasCheckpointRefCalls.push(checkpointRef);
-          return true;
-        }),
+      hasCheckpointRef: () => Effect.succeed(true),
       restoreCheckpoint: () => Effect.succeed(true),
-      diffCheckpoints: ({ fromCheckpointRef, toCheckpointRef, cwd }) =>
+      diffCheckpoints: ({ fromCheckpointRef, toCheckpointRef, cwd, ignoreWhitespace }) =>
         Effect.sync(() => {
-          diffCheckpointsCalls.push({ fromCheckpointRef, toCheckpointRef, cwd });
+          diffCheckpointsCalls.push({
+            fromCheckpointRef,
+            toCheckpointRef,
+            cwd,
+            ignoreWhitespace,
+          });
           return "diff patch";
         }),
       deleteCheckpointRefs: () => Effect.void,
@@ -80,12 +183,23 @@ describe("CheckpointDiffQueryLive", () => {
       Layer.provideMerge(Layer.succeed(CheckpointStore, checkpointStore)),
       Layer.provideMerge(
         Layer.succeed(ProjectionSnapshotQuery, {
+          getCommandReadModel: () =>
+            Effect.die("CheckpointDiffQuery should not request the command read model"),
           getSnapshot: () =>
             Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
+          getShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the orchestration shell snapshot"),
+          getArchivedShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request archived shell snapshots"),
+          getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 0 }),
           getCounts: () => Effect.succeed({ projectCount: 0, threadCount: 0 }),
           getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.succeed(Option.none()),
           getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
           getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
+          getFullThreadDiffContext: () => Effect.die("unused"),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
         }),
       ),
     );
@@ -97,17 +211,18 @@ describe("CheckpointDiffQueryLive", () => {
           threadId,
           fromTurnCount: 0,
           toTurnCount: 1,
+          ignoreWhitespace: true,
         });
       }).pipe(Effect.provide(layer)),
     );
 
     const expectedFromRef = checkpointRefForThreadTurn(threadId, 0);
-    expect(hasCheckpointRefCalls).toEqual([expectedFromRef, toCheckpointRef]);
     expect(diffCheckpointsCalls).toEqual([
       {
         cwd: "/tmp/workspace",
         fromCheckpointRef: expectedFromRef,
         toCheckpointRef,
+        ignoreWhitespace: true,
       },
     ]);
     expect(result).toEqual({
@@ -118,6 +233,141 @@ describe("CheckpointDiffQueryLive", () => {
     });
   });
 
+  it("defaults to hide whitespace changes", async () => {
+    const projectId = ProjectId.make("project-default-whitespace");
+    const threadId = ThreadId.make("thread-default-whitespace");
+    const toCheckpointRef = checkpointRefForThreadTurn(threadId, 1);
+    const diffCheckpointsCalls: Array<{ readonly ignoreWhitespace: boolean }> = [];
+
+    const threadCheckpointContext = makeThreadCheckpointContext({
+      projectId,
+      threadId,
+      workspaceRoot: "/tmp/workspace",
+      worktreePath: null,
+      checkpointTurnCount: 1,
+      checkpointRef: toCheckpointRef,
+    });
+
+    const checkpointStore: CheckpointStoreShape = {
+      isGitRepository: () => Effect.succeed(true),
+      captureCheckpoint: () => Effect.void,
+      hasCheckpointRef: () => Effect.succeed(true),
+      restoreCheckpoint: () => Effect.succeed(true),
+      diffCheckpoints: ({ ignoreWhitespace }) =>
+        Effect.sync(() => {
+          diffCheckpointsCalls.push({ ignoreWhitespace });
+          return "diff patch";
+        }),
+      deleteCheckpointRefs: () => Effect.void,
+    };
+
+    const layer = CheckpointDiffQueryLive.pipe(
+      Layer.provideMerge(Layer.succeed(CheckpointStore, checkpointStore)),
+      Layer.provideMerge(
+        Layer.succeed(ProjectionSnapshotQuery, {
+          getCommandReadModel: () =>
+            Effect.die("CheckpointDiffQuery should not request the command read model"),
+          getSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
+          getShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the orchestration shell snapshot"),
+          getArchivedShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request archived shell snapshots"),
+          getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 0 }),
+          getCounts: () => Effect.succeed({ projectCount: 0, threadCount: 0 }),
+          getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.succeed(Option.none()),
+          getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+          getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
+          getFullThreadDiffContext: () => Effect.die("unused"),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
+        }),
+      ),
+    );
+
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const query = yield* CheckpointDiffQuery;
+        return yield* query.getTurnDiff({
+          threadId,
+          fromTurnCount: 0,
+          toTurnCount: 1,
+        });
+      }).pipe(Effect.provide(layer)),
+    );
+
+    expect(diffCheckpointsCalls).toEqual([{ ignoreWhitespace: true }]);
+  });
+
+  it("does not preflight checkpoint refs before diffing", async () => {
+    const projectId = ProjectId.make("project-no-preflight");
+    const threadId = ThreadId.make("thread-no-preflight");
+    const toCheckpointRef = checkpointRefForThreadTurn(threadId, 1);
+    let hasCheckpointRefCallCount = 0;
+
+    const threadCheckpointContext = makeThreadCheckpointContext({
+      projectId,
+      threadId,
+      workspaceRoot: "/tmp/workspace",
+      worktreePath: null,
+      checkpointTurnCount: 1,
+      checkpointRef: toCheckpointRef,
+    });
+
+    const checkpointStore: CheckpointStoreShape = {
+      isGitRepository: () => Effect.succeed(true),
+      captureCheckpoint: () => Effect.void,
+      hasCheckpointRef: () =>
+        Effect.sync(() => {
+          hasCheckpointRefCallCount += 1;
+          return true;
+        }),
+      restoreCheckpoint: () => Effect.succeed(true),
+      diffCheckpoints: () => Effect.succeed("diff patch"),
+      deleteCheckpointRefs: () => Effect.void,
+    };
+
+    const layer = CheckpointDiffQueryLive.pipe(
+      Layer.provideMerge(Layer.succeed(CheckpointStore, checkpointStore)),
+      Layer.provideMerge(
+        Layer.succeed(ProjectionSnapshotQuery, {
+          getCommandReadModel: () =>
+            Effect.die("CheckpointDiffQuery should not request the command read model"),
+          getSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
+          getShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the orchestration shell snapshot"),
+          getArchivedShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request archived shell snapshots"),
+          getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 0 }),
+          getCounts: () => Effect.succeed({ projectCount: 0, threadCount: 0 }),
+          getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.succeed(Option.none()),
+          getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+          getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
+          getFullThreadDiffContext: () => Effect.die("unused"),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
+        }),
+      ),
+    );
+
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const query = yield* CheckpointDiffQuery;
+        return yield* query.getTurnDiff({
+          threadId,
+          fromTurnCount: 0,
+          toTurnCount: 1,
+          ignoreWhitespace: true,
+        });
+      }).pipe(Effect.provide(layer)),
+    );
+
+    expect(hasCheckpointRefCallCount).toBe(0);
+  });
+
   it("fails when the thread is missing from the snapshot", async () => {
     const threadId = ThreadId.make("thread-missing");
 
@@ -134,12 +384,23 @@ describe("CheckpointDiffQueryLive", () => {
       Layer.provideMerge(Layer.succeed(CheckpointStore, checkpointStore)),
       Layer.provideMerge(
         Layer.succeed(ProjectionSnapshotQuery, {
+          getCommandReadModel: () =>
+            Effect.die("CheckpointDiffQuery should not request the command read model"),
           getSnapshot: () =>
             Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
+          getShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the orchestration shell snapshot"),
+          getArchivedShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request archived shell snapshots"),
+          getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 0 }),
           getCounts: () => Effect.succeed({ projectCount: 0, threadCount: 0 }),
           getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.succeed(Option.none()),
           getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
           getThreadCheckpointContext: () => Effect.succeed(Option.none()),
+          getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
         }),
       ),
     );
diff --git a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts
index 1c2edee469e..b07c06ac936 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts
@@ -1,10 +1,14 @@
 import {
+  type CheckpointRef,
   OrchestrationGetTurnDiffResult,
-  type OrchestrationGetFullThreadDiffInput,
+  type ThreadId,
   type OrchestrationGetFullThreadDiffResult,
   type OrchestrationGetTurnDiffResult as OrchestrationGetTurnDiffResultType,
 } from "@t3tools/contracts";
-import { Effect, Layer, Option, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 
 import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
 import { CheckpointInvariantError, CheckpointUnavailableError } from "../Errors.ts";
@@ -17,6 +21,22 @@ import {
 
 const isTurnDiffResult = Schema.is(OrchestrationGetTurnDiffResult);
 
+function buildTurnDiffResult(
+  input: {
+    readonly threadId: ThreadId;
+    readonly fromTurnCount: number;
+    readonly toTurnCount: number;
+  },
+  diff: string,
+): OrchestrationGetTurnDiffResultType {
+  return {
+    threadId: input.threadId,
+    fromTurnCount: input.fromTurnCount,
+    toTurnCount: input.toTurnCount,
+    diff,
+  };
+}
+
 const make = Effect.gen(function* () {
   const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
   const checkpointStore = yield* CheckpointStore;
@@ -24,6 +44,13 @@ const make = Effect.gen(function* () {
   const getTurnDiff: CheckpointDiffQueryShape["getTurnDiff"] = Effect.fn("getTurnDiff")(
     function* (input) {
       const operation = "CheckpointDiffQuery.getTurnDiff";
+      const ignoreWhitespace = input.ignoreWhitespace ?? true;
+      yield* Effect.annotateCurrentSpan({
+        "checkpoint.thread_id": input.threadId,
+        "checkpoint.from_turn_count": input.fromTurnCount,
+        "checkpoint.to_turn_count": input.toTurnCount,
+        "checkpoint.ignore_whitespace": ignoreWhitespace,
+      });
 
       if (input.fromTurnCount === input.toTurnCount) {
         const emptyDiff: OrchestrationGetTurnDiffResultType = {
@@ -41,9 +68,9 @@ const make = Effect.gen(function* () {
         return emptyDiff;
       }
 
-      const threadContext = yield* projectionSnapshotQuery.getThreadCheckpointContext(
-        input.threadId,
-      );
+      const threadContext = yield* projectionSnapshotQuery
+        .getThreadCheckpointContext(input.threadId)
+        .pipe(Effect.withSpan("checkpoint.turnDiff.lookupContext"));
       if (Option.isNone(threadContext)) {
         return yield* new CheckpointInvariantError({
           operation,
@@ -96,68 +123,121 @@ const make = Effect.gen(function* () {
         });
       }
 
-      const [fromExists, toExists] = yield* Effect.all(
-        [
-          checkpointStore.hasCheckpointRef({
-            cwd: workspaceCwd,
-            checkpointRef: fromCheckpointRef,
-          }),
-          checkpointStore.hasCheckpointRef({
-            cwd: workspaceCwd,
-            checkpointRef: toCheckpointRef,
-          }),
-        ],
-        { concurrency: "unbounded" },
-      );
-
-      if (!fromExists) {
-        return yield* new CheckpointUnavailableError({
-          threadId: input.threadId,
-          turnCount: input.fromTurnCount,
-          detail: `Filesystem checkpoint is unavailable for turn ${input.fromTurnCount}.`,
+      const diff = yield* checkpointStore
+        .diffCheckpoints({
+          cwd: workspaceCwd,
+          fromCheckpointRef,
+          toCheckpointRef,
+          fallbackFromToHead: false,
+          ignoreWhitespace,
+        })
+        .pipe(Effect.withSpan("checkpoint.turnDiff.diffCheckpoints"));
+
+      const turnDiff = buildTurnDiffResult(input, diff);
+      if (!isTurnDiffResult(turnDiff)) {
+        return yield* new CheckpointInvariantError({
+          operation,
+          detail: "Computed turn diff result does not satisfy contract schema.",
         });
       }
 
-      if (!toExists) {
-        return yield* new CheckpointUnavailableError({
+      return turnDiff;
+    },
+  );
+
+  const getFullThreadDiff: CheckpointDiffQueryShape["getFullThreadDiff"] = Effect.fn(
+    "CheckpointDiffQuery.getFullThreadDiff",
+  )(function* (input) {
+    const operation = "CheckpointDiffQuery.getFullThreadDiff";
+    const ignoreWhitespace = input.ignoreWhitespace ?? true;
+    yield* Effect.annotateCurrentSpan({
+      "checkpoint.thread_id": input.threadId,
+      "checkpoint.from_turn_count": 0,
+      "checkpoint.to_turn_count": input.toTurnCount,
+      "checkpoint.ignore_whitespace": ignoreWhitespace,
+      "checkpoint.diff_kind": "full-thread",
+    });
+
+    if (input.toTurnCount === 0) {
+      const emptyDiff = buildTurnDiffResult(
+        {
           threadId: input.threadId,
-          turnCount: input.toTurnCount,
-          detail: `Filesystem checkpoint is unavailable for turn ${input.toTurnCount}.`,
+          fromTurnCount: 0,
+          toTurnCount: 0,
+        },
+        "",
+      );
+      if (!isTurnDiffResult(emptyDiff)) {
+        return yield* new CheckpointInvariantError({
+          operation,
+          detail: "Computed full thread diff result does not satisfy contract schema.",
         });
       }
+      return emptyDiff satisfies OrchestrationGetFullThreadDiffResult;
+    }
+
+    const threadContext = yield* projectionSnapshotQuery
+      .getFullThreadDiffContext(input.threadId, input.toTurnCount)
+      .pipe(Effect.withSpan("checkpoint.fullThread.lookupContext"));
 
-      const diff = yield* checkpointStore.diffCheckpoints({
+    if (Option.isNone(threadContext)) {
+      return yield* new CheckpointInvariantError({
+        operation,
+        detail: `Thread '${input.threadId}' not found.`,
+      });
+    }
+
+    if (input.toTurnCount > threadContext.value.latestCheckpointTurnCount) {
+      return yield* new CheckpointUnavailableError({
+        threadId: input.threadId,
+        turnCount: input.toTurnCount,
+        detail: `Turn diff range exceeds current turn count: requested ${input.toTurnCount}, current ${threadContext.value.latestCheckpointTurnCount}.`,
+      });
+    }
+
+    const workspaceCwd = threadContext.value.worktreePath ?? threadContext.value.workspaceRoot;
+    if (!workspaceCwd) {
+      return yield* new CheckpointInvariantError({
+        operation,
+        detail: `Workspace path missing for thread '${input.threadId}' when computing full thread diff.`,
+      });
+    }
+
+    if (!threadContext.value.toCheckpointRef) {
+      return yield* new CheckpointUnavailableError({
+        threadId: input.threadId,
+        turnCount: input.toTurnCount,
+        detail: `Checkpoint ref is unavailable for turn ${input.toTurnCount}.`,
+      });
+    }
+
+    const diff = yield* checkpointStore
+      .diffCheckpoints({
         cwd: workspaceCwd,
-        fromCheckpointRef,
-        toCheckpointRef,
+        fromCheckpointRef: checkpointRefForThreadTurn(input.threadId, 0),
+        toCheckpointRef: threadContext.value.toCheckpointRef as CheckpointRef,
         fallbackFromToHead: false,
-      });
+        ignoreWhitespace,
+      })
+      .pipe(Effect.withSpan("checkpoint.fullThread.diffCheckpoints"));
 
-      const turnDiff: OrchestrationGetTurnDiffResultType = {
+    const turnDiff = buildTurnDiffResult(
+      {
         threadId: input.threadId,
-        fromTurnCount: input.fromTurnCount,
+        fromTurnCount: 0,
         toTurnCount: input.toTurnCount,
-        diff,
-      };
-      if (!isTurnDiffResult(turnDiff)) {
-        return yield* new CheckpointInvariantError({
-          operation,
-          detail: "Computed turn diff result does not satisfy contract schema.",
-        });
-      }
-
-      return turnDiff;
-    },
-  );
+      },
+      diff,
+    );
+    if (!isTurnDiffResult(turnDiff)) {
+      return yield* new CheckpointInvariantError({
+        operation,
+        detail: "Computed full thread diff result does not satisfy contract schema.",
+      });
+    }
 
-  const getFullThreadDiff: CheckpointDiffQueryShape["getFullThreadDiff"] = (
-    input: OrchestrationGetFullThreadDiffInput,
-  ) =>
-    getTurnDiff({
-      threadId: input.threadId,
-      fromTurnCount: 0,
-      toTurnCount: input.toTurnCount,
-    }).pipe(Effect.map((result): OrchestrationGetFullThreadDiffResult => result));
+    return turnDiff satisfies OrchestrationGetFullThreadDiffResult;
+  });
 
   return {
     getTurnDiff,
diff --git a/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts b/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts
index fe377eb1ec3..2d4fd8a7df2 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts
@@ -1,31 +1,39 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import path from "node:path";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, PlatformError, Scope } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as PlatformError from "effect/PlatformError";
+import * as Scope from "effect/Scope";
 import { describe, expect } from "vitest";
 
 import { checkpointRefForThreadTurn } from "../Utils.ts";
 import { CheckpointStoreLive } from "./CheckpointStore.ts";
 import { CheckpointStore } from "../Services/CheckpointStore.ts";
-import { GitCoreLive } from "../../git/Layers/GitCore.ts";
-import { GitCore } from "../../git/Services/GitCore.ts";
-import { GitCommandError } from "@t3tools/contracts";
+import * as VcsDriverRegistry from "../../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../../vcs/VcsProcess.ts";
+import type { VcsError } from "@t3tools/contracts";
 import { ServerConfig } from "../../config.ts";
 import { ThreadId } from "@t3tools/contracts";
 
 const ServerConfigLayer = ServerConfig.layerTest(process.cwd(), {
   prefix: "t3-checkpoint-store-test-",
 });
-const GitCoreTestLayer = GitCoreLive.pipe(
-  Layer.provide(ServerConfigLayer),
-  Layer.provide(NodeServices.layer),
-);
+const VcsProcessTestLayer = VcsProcess.layer.pipe(Layer.provide(NodeServices.layer));
+const VcsDriverTestLayer = VcsDriverRegistry.layer.pipe(Layer.provide(VcsProcessTestLayer));
 const CheckpointStoreTestLayer = CheckpointStoreLive.pipe(
-  Layer.provide(GitCoreTestLayer),
-  Layer.provide(NodeServices.layer),
+  Layer.provideMerge(VcsDriverTestLayer),
+  Layer.provideMerge(NodeServices.layer),
+);
+const TestLayer = CheckpointStoreTestLayer.pipe(
+  Layer.provideMerge(VcsProcessTestLayer),
+  Layer.provideMerge(VcsDriverTestLayer),
+  Layer.provideMerge(ServerConfigLayer),
+  Layer.provideMerge(NodeServices.layer),
 );
-const TestLayer = Layer.mergeAll(NodeServices.layer, GitCoreTestLayer, CheckpointStoreTestLayer);
 
 function makeTmpDir(
   prefix = "checkpoint-store-test-",
@@ -49,11 +57,12 @@ function writeTextFile(
 function git(
   cwd: string,
   args: ReadonlyArray<string>,
-): Effect.Effect<string, GitCommandError, GitCore> {
+): Effect.Effect<string, VcsError, VcsProcess.VcsProcess> {
   return Effect.gen(function* () {
-    const gitCore = yield* GitCore;
-    const result = yield* gitCore.execute({
+    const process = yield* VcsProcess.VcsProcess;
+    const result = yield* process.run({
       operation: "CheckpointStore.test.git",
+      command: "git",
       cwd,
       args,
       timeoutMs: 10_000,
@@ -66,12 +75,11 @@ function initRepoWithCommit(
   cwd: string,
 ): Effect.Effect<
   void,
-  GitCommandError | PlatformError.PlatformError,
-  GitCore | FileSystem.FileSystem
+  VcsError | PlatformError.PlatformError,
+  VcsProcess.VcsProcess | FileSystem.FileSystem
 > {
   return Effect.gen(function* () {
-    const core = yield* GitCore;
-    yield* core.initRepo({ cwd });
+    yield* git(cwd, ["init"]);
     yield* git(cwd, ["config", "user.email", "test@test.com"]);
     yield* git(cwd, ["config", "user.name", "Test"]);
     yield* writeTextFile(path.join(cwd, "README.md"), "# test\n");
@@ -111,6 +119,7 @@ it.layer(TestLayer)("CheckpointStoreLive", (it) => {
           cwd: tmp,
           fromCheckpointRef,
           toCheckpointRef,
+          ignoreWhitespace: true,
         });
 
         expect(diff).toContain("diff --git");
@@ -118,5 +127,80 @@ it.layer(TestLayer)("CheckpointStoreLive", (it) => {
         expect(diff).toContain("+line 04999");
       }),
     );
+
+    it.effect("can hide indentation churn when changes wrap existing lines", () =>
+      Effect.gen(function* () {
+        const tmp = yield* makeTmpDir();
+        yield* initRepoWithCommit(tmp);
+        const checkpointStore = yield* CheckpointStore;
+        const threadId = ThreadId.make("thread-checkpoint-store-whitespace");
+        const fromCheckpointRef = checkpointRefForThreadTurn(threadId, 0);
+        const toCheckpointRef = checkpointRefForThreadTurn(threadId, 1);
+
+        const componentPath = path.join(tmp, "Component.tsx");
+        yield* writeTextFile(
+          componentPath,
+          [
+            "export function View() {",
+            "  return (",
+            "    <section>",
+            "      <h1>Title</h1>",
+            "      <p>Body</p>",
+            "    </section>",
+            "  );",
+            "}",
+            "",
+          ].join("\n"),
+        );
+        yield* checkpointStore.captureCheckpoint({
+          cwd: tmp,
+          checkpointRef: fromCheckpointRef,
+        });
+        yield* writeTextFile(
+          componentPath,
+          [
+            "export function View() {",
+            "  return (",
+            "    <section>",
+            "      {isReady ? (",
+            "        <div>",
+            "          <h1>Title</h1>",
+            "          <p>Body</p>",
+            "        </div>",
+            "      ) : null}",
+            "    </section>",
+            "  );",
+            "}",
+            "",
+          ].join("\n"),
+        );
+        yield* checkpointStore.captureCheckpoint({
+          cwd: tmp,
+          checkpointRef: toCheckpointRef,
+        });
+
+        const normalDiff = yield* checkpointStore.diffCheckpoints({
+          cwd: tmp,
+          fromCheckpointRef,
+          toCheckpointRef,
+          ignoreWhitespace: false,
+        });
+        const whitespaceIgnoredDiff = yield* checkpointStore.diffCheckpoints({
+          cwd: tmp,
+          fromCheckpointRef,
+          toCheckpointRef,
+          ignoreWhitespace: true,
+        });
+
+        expect(normalDiff).toContain("diff --git");
+        expect(normalDiff).toContain("-      <h1>Title</h1>");
+        expect(normalDiff).toContain("+          <h1>Title</h1>");
+        expect(whitespaceIgnoredDiff).toContain("diff --git");
+        expect(whitespaceIgnoredDiff).toContain("+      {isReady ? (");
+        expect(whitespaceIgnoredDiff).toContain("+        <div>");
+        expect(whitespaceIgnoredDiff).not.toContain("-      <h1>Title</h1>");
+        expect(whitespaceIgnoredDiff).not.toContain("+          <h1>Title</h1>");
+      }),
+    );
   });
 });
diff --git a/apps/server/src/checkpointing/Layers/CheckpointStore.ts b/apps/server/src/checkpointing/Layers/CheckpointStore.ts
index 184ec96323e..9bd72e78b6b 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointStore.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointStore.ts
@@ -1,272 +1,79 @@
 /**
  * CheckpointStoreLive - Filesystem checkpoint store adapter layer.
  *
- * Implements hidden Git-ref checkpoint capture/restore directly with
- * Effect-native child process execution (`effect/unstable/process`).
- *
- * This layer owns filesystem/Git interactions only; it does not persist
- * checkpoint metadata and does not coordinate provider rollback semantics.
+ * Resolves the active VCS driver once per checkpoint operation and delegates
+ * checkpoint-specific behavior to the driver's optional checkpoint capability.
  *
  * @module CheckpointStoreLive
  */
-import { randomUUID } from "node:crypto";
-
-import { Effect, Layer, FileSystem, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
-import { CheckpointInvariantError } from "../Errors.ts";
-import { GitCommandError } from "@t3tools/contracts";
-import { GitCore } from "../../git/Services/GitCore.ts";
 import { CheckpointStore, type CheckpointStoreShape } from "../Services/CheckpointStore.ts";
-import { CheckpointRef } from "@t3tools/contracts";
+import { VcsUnsupportedOperationError } from "@t3tools/contracts";
+import { VcsDriverRegistry } from "../../vcs/VcsDriverRegistry.ts";
+import type { VcsCheckpointOps } from "../../vcs/VcsDriver.ts";
 
 const makeCheckpointStore = Effect.gen(function* () {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const git = yield* GitCore;
-
-  const resolveHeadCommit = (cwd: string): Effect.Effect<string | null, GitCommandError> =>
-    git
-      .execute({
-        operation: "CheckpointStore.resolveHeadCommit",
-        cwd,
-        args: ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"],
-        allowNonZeroExit: true,
-      })
-      .pipe(
-        Effect.map((result) => {
-          if (result.code !== 0) {
-            return null;
-          }
-          const commit = result.stdout.trim();
-          return commit.length > 0 ? commit : null;
-        }),
-      );
+  const vcsRegistry = yield* VcsDriverRegistry;
 
-  const hasHeadCommit = (cwd: string): Effect.Effect<boolean, GitCommandError> =>
-    git
-      .execute({
-        operation: "CheckpointStore.hasHeadCommit",
-        cwd,
-        args: ["rev-parse", "--verify", "HEAD"],
-        allowNonZeroExit: true,
-      })
-      .pipe(Effect.map((result) => result.code === 0));
-
-  const resolveCheckpointCommit = (
+  const resolveCheckpoints = Effect.fn("CheckpointStore.resolveCheckpoints")(function* (
+    operation: string,
     cwd: string,
-    checkpointRef: CheckpointRef,
-  ): Effect.Effect<string | null, GitCommandError> =>
-    git
-      .execute({
-        operation: "CheckpointStore.resolveCheckpointCommit",
-        cwd,
-        args: ["rev-parse", "--verify", "--quiet", `${checkpointRef}^{commit}`],
-        allowNonZeroExit: true,
-      })
-      .pipe(
-        Effect.map((result) => {
-          if (result.code !== 0) {
-            return null;
-          }
-          const commit = result.stdout.trim();
-          return commit.length > 0 ? commit : null;
-        }),
-      );
+  ) {
+    const handle = yield* vcsRegistry.resolve({ cwd });
+    if (!handle.driver.checkpoints) {
+      return yield* new VcsUnsupportedOperationError({
+        operation,
+        kind: handle.kind,
+        detail: `${handle.kind} driver does not implement checkpoint operations.`,
+      });
+    }
+    return handle.driver.checkpoints satisfies VcsCheckpointOps;
+  });
 
   const isGitRepository: CheckpointStoreShape["isGitRepository"] = (cwd) =>
-    git
-      .execute({
-        operation: "CheckpointStore.isGitRepository",
-        cwd,
-        args: ["rev-parse", "--is-inside-work-tree"],
-        allowNonZeroExit: true,
-      })
-      .pipe(
-        Effect.map((result) => result.code === 0 && result.stdout.trim() === "true"),
-        Effect.catch(() => Effect.succeed(false)),
-      );
+    vcsRegistry.resolve({ cwd, requestedKind: "git" }).pipe(
+      Effect.map(() => true),
+      Effect.catch(() => Effect.succeed(false)),
+    );
 
   const captureCheckpoint: CheckpointStoreShape["captureCheckpoint"] = Effect.fn(
     "captureCheckpoint",
   )(function* (input) {
-    const operation = "CheckpointStore.captureCheckpoint";
-
-    yield* Effect.acquireUseRelease(
-      fs.makeTempDirectory({ prefix: "t3-fs-checkpoint-" }),
-      Effect.fn("captureCheckpoint.withTempDirectory")(function* (tempDir) {
-        const tempIndexPath = path.join(tempDir, `index-${randomUUID()}`);
-        const commitEnv: NodeJS.ProcessEnv = {
-          ...process.env,
-          GIT_INDEX_FILE: tempIndexPath,
-          GIT_AUTHOR_NAME: "T3 Code",
-          GIT_AUTHOR_EMAIL: "t3code@users.noreply.github.com",
-          GIT_COMMITTER_NAME: "T3 Code",
-          GIT_COMMITTER_EMAIL: "t3code@users.noreply.github.com",
-        };
-
-        const headExists = yield* hasHeadCommit(input.cwd);
-        if (headExists) {
-          yield* git.execute({
-            operation,
-            cwd: input.cwd,
-            args: ["read-tree", "HEAD"],
-            env: commitEnv,
-          });
-        }
-
-        yield* git.execute({
-          operation,
-          cwd: input.cwd,
-          args: ["add", "-A", "--", "."],
-          env: commitEnv,
-        });
-
-        const writeTreeResult = yield* git.execute({
-          operation,
-          cwd: input.cwd,
-          args: ["write-tree"],
-          env: commitEnv,
-        });
-        const treeOid = writeTreeResult.stdout.trim();
-        if (treeOid.length === 0) {
-          return yield* new GitCommandError({
-            operation,
-            command: "git write-tree",
-            cwd: input.cwd,
-            detail: "git write-tree returned an empty tree oid.",
-          });
-        }
-
-        const message = `t3 checkpoint ref=${input.checkpointRef}`;
-        const commitTreeResult = yield* git.execute({
-          operation,
-          cwd: input.cwd,
-          args: ["commit-tree", treeOid, "-m", message],
-          env: commitEnv,
-        });
-        const commitOid = commitTreeResult.stdout.trim();
-        if (commitOid.length === 0) {
-          return yield* new GitCommandError({
-            operation,
-            command: "git commit-tree",
-            cwd: input.cwd,
-            detail: "git commit-tree returned an empty commit oid.",
-          });
-        }
-
-        yield* git.execute({
-          operation,
-          cwd: input.cwd,
-          args: ["update-ref", input.checkpointRef, commitOid],
-        });
-      }),
-      (tempDir) => fs.remove(tempDir, { recursive: true }),
-    ).pipe(
-      Effect.catchTags({
-        PlatformError: (error) =>
-          Effect.fail(
-            new CheckpointInvariantError({
-              operation: "CheckpointStore.captureCheckpoint",
-              detail: "Failed to capture checkpoint.",
-              cause: error,
-            }),
-          ),
-      }),
-    );
+    const checkpoints = yield* resolveCheckpoints("CheckpointStore.captureCheckpoint", input.cwd);
+    return yield* checkpoints.captureCheckpoint(input);
   });
 
-  const hasCheckpointRef: CheckpointStoreShape["hasCheckpointRef"] = (input) =>
-    resolveCheckpointCommit(input.cwd, input.checkpointRef).pipe(
-      Effect.map((commit) => commit !== null),
-    );
+  const hasCheckpointRef: CheckpointStoreShape["hasCheckpointRef"] = Effect.fn("hasCheckpointRef")(
+    function* (input) {
+      const checkpoints = yield* resolveCheckpoints("CheckpointStore.hasCheckpointRef", input.cwd);
+      return yield* checkpoints.hasCheckpointRef(input);
+    },
+  );
 
   const restoreCheckpoint: CheckpointStoreShape["restoreCheckpoint"] = Effect.fn(
     "restoreCheckpoint",
   )(function* (input) {
-    const operation = "CheckpointStore.restoreCheckpoint";
-
-    let commitOid = yield* resolveCheckpointCommit(input.cwd, input.checkpointRef);
-
-    if (!commitOid && input.fallbackToHead === true) {
-      commitOid = yield* resolveHeadCommit(input.cwd);
-    }
-
-    if (!commitOid) {
-      return false;
-    }
-
-    yield* git.execute({
-      operation,
-      cwd: input.cwd,
-      args: ["restore", "--source", commitOid, "--worktree", "--staged", "--", "."],
-    });
-    yield* git.execute({
-      operation,
-      cwd: input.cwd,
-      args: ["clean", "-fd", "--", "."],
-    });
-
-    const headExists = yield* hasHeadCommit(input.cwd);
-    if (headExists) {
-      yield* git.execute({
-        operation,
-        cwd: input.cwd,
-        args: ["reset", "--quiet", "--", "."],
-      });
-    }
-
-    return true;
+    const checkpoints = yield* resolveCheckpoints("CheckpointStore.restoreCheckpoint", input.cwd);
+    return yield* checkpoints.restoreCheckpoint(input);
   });
 
   const diffCheckpoints: CheckpointStoreShape["diffCheckpoints"] = Effect.fn("diffCheckpoints")(
     function* (input) {
-      const operation = "CheckpointStore.diffCheckpoints";
-
-      let fromCommitOid = yield* resolveCheckpointCommit(input.cwd, input.fromCheckpointRef);
-      const toCommitOid = yield* resolveCheckpointCommit(input.cwd, input.toCheckpointRef);
-
-      if (!fromCommitOid && input.fallbackFromToHead === true) {
-        const headCommit = yield* resolveHeadCommit(input.cwd);
-        if (headCommit) {
-          fromCommitOid = headCommit;
-        }
-      }
-
-      if (!fromCommitOid || !toCommitOid) {
-        return yield* new GitCommandError({
-          operation,
-          command: "git diff",
-          cwd: input.cwd,
-          detail: "Checkpoint ref is unavailable for diff operation.",
-        });
-      }
-
-      const result = yield* git.execute({
-        operation,
-        cwd: input.cwd,
-        args: ["diff", "--patch", "--minimal", "--no-color", fromCommitOid, toCommitOid],
-      });
-
-      return result.stdout;
+      const checkpoints = yield* resolveCheckpoints("CheckpointStore.diffCheckpoints", input.cwd);
+      return yield* checkpoints.diffCheckpoints(input);
     },
   );
 
   const deleteCheckpointRefs: CheckpointStoreShape["deleteCheckpointRefs"] = Effect.fn(
     "deleteCheckpointRefs",
   )(function* (input) {
-    const operation = "CheckpointStore.deleteCheckpointRefs";
-
-    yield* Effect.forEach(
-      input.checkpointRefs,
-      (checkpointRef) =>
-        git.execute({
-          operation,
-          cwd: input.cwd,
-          args: ["update-ref", "-d", checkpointRef],
-          allowNonZeroExit: true,
-        }),
-      { discard: true },
+    const checkpoints = yield* resolveCheckpoints(
+      "CheckpointStore.deleteCheckpointRefs",
+      input.cwd,
     );
+    return yield* checkpoints.deleteCheckpointRefs(input);
   });
 
   return {
diff --git a/apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts b/apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts
index d865256ac59..4bb8b111827 100644
--- a/apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts
+++ b/apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts
@@ -12,8 +12,8 @@ import type {
   OrchestrationGetTurnDiffInput,
   OrchestrationGetTurnDiffResult,
 } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { CheckpointServiceError } from "../Errors.ts";
 
diff --git a/apps/server/src/checkpointing/Services/CheckpointStore.ts b/apps/server/src/checkpointing/Services/CheckpointStore.ts
index d9a43fa4e95..a7c4c3dbef0 100644
--- a/apps/server/src/checkpointing/Services/CheckpointStore.ts
+++ b/apps/server/src/checkpointing/Services/CheckpointStore.ts
@@ -10,8 +10,8 @@
  *
  * @module CheckpointStore
  */
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { CheckpointStoreError } from "../Errors.ts";
 import { CheckpointRef } from "@t3tools/contracts";
@@ -32,6 +32,7 @@ export interface DiffCheckpointsInput {
   readonly fromCheckpointRef: CheckpointRef;
   readonly toCheckpointRef: CheckpointRef;
   readonly fallbackFromToHead?: boolean;
+  readonly ignoreWhitespace: boolean;
 }
 
 export interface DeleteCheckpointRefsInput {
diff --git a/apps/server/src/checkpointing/Utils.ts b/apps/server/src/checkpointing/Utils.ts
index c709aa3735c..50d0163af5a 100644
--- a/apps/server/src/checkpointing/Utils.ts
+++ b/apps/server/src/checkpointing/Utils.ts
@@ -1,4 +1,4 @@
-import { Encoding } from "effect";
+import * as Encoding from "effect/Encoding";
 import { CheckpointRef, ProjectId, type ThreadId } from "@t3tools/contracts";
 
 export const CHECKPOINT_REFS_PREFIX = "refs/t3/checkpoints";
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts
deleted file mode 100644
index 5f737509202..00000000000
--- a/apps/server/src/cli.ts
+++ /dev/null
@@ -1,1132 +0,0 @@
-import { NetService } from "@t3tools/shared/Net";
-import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
-import {
-  AuthSessionId,
-  CommandId,
-  OrchestrationReadModel,
-  ProjectId,
-  type ClientOrchestrationCommand,
-} from "@t3tools/contracts";
-import {
-  Config,
-  Console,
-  Duration,
-  Effect,
-  Exit,
-  FileSystem,
-  Layer,
-  LogLevel,
-  Option,
-  Path,
-  References,
-  Schema,
-  SchemaIssue,
-  SchemaTransformation,
-} from "effect";
-import { Argument, Command, Flag, GlobalFlag } from "effect/unstable/cli";
-import {
-  FetchHttpClient,
-  HttpClient,
-  HttpClientRequest,
-  HttpClientResponse,
-} from "effect/unstable/http";
-
-import {
-  DEFAULT_PORT,
-  deriveServerPaths,
-  ensureServerDirectories,
-  resolveStaticDir,
-  ServerConfig,
-  RuntimeMode,
-  type ServerConfigShape,
-  type StartupPresentation,
-} from "./config";
-import { readBootstrapEnvelope } from "./bootstrap";
-import { expandHomePath, resolveBaseDir } from "./os-jank";
-import { runServer } from "./server";
-import { AuthControlPlaneRuntimeLive } from "./auth/Layers/AuthControlPlane.ts";
-import {
-  formatIssuedPairingCredential,
-  formatIssuedSession,
-  formatPairingCredentialList,
-  formatSessionList,
-} from "./cliAuthFormat";
-import { AuthControlPlane, AuthControlPlaneShape } from "./auth/Services/AuthControlPlane.ts";
-import { OrchestrationEngineService } from "./orchestration/Services/OrchestrationEngine.ts";
-import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
-import { OrchestrationLayerLive } from "./orchestration/runtimeLayer";
-import { layerConfig as SqlitePersistenceLayerLive } from "./persistence/Layers/Sqlite.ts";
-import { RepositoryIdentityResolverLive } from "./project/Layers/RepositoryIdentityResolver.ts";
-import { getAutoBootstrapDefaultModelSelection } from "./serverRuntimeStartup";
-import {
-  clearPersistedServerRuntimeState,
-  readPersistedServerRuntimeState,
-} from "./serverRuntimeState";
-import { WorkspacePaths } from "./workspace/Services/WorkspacePaths";
-import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths";
-
-const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
-
-const BootstrapEnvelopeSchema = Schema.Struct({
-  mode: Schema.optional(RuntimeMode),
-  port: Schema.optional(PortSchema),
-  host: Schema.optional(Schema.String),
-  t3Home: Schema.optional(Schema.String),
-  devUrl: Schema.optional(Schema.URLFromString),
-  noBrowser: Schema.optional(Schema.Boolean),
-  desktopBootstrapToken: Schema.optional(Schema.String),
-  autoBootstrapProjectFromCwd: Schema.optional(Schema.Boolean),
-  logWebSocketEvents: Schema.optional(Schema.Boolean),
-  otlpTracesUrl: Schema.optional(Schema.String),
-  otlpMetricsUrl: Schema.optional(Schema.String),
-});
-
-const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
-  Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
-  Flag.optional,
-);
-const portFlag = Flag.integer("port").pipe(
-  Flag.withSchema(PortSchema),
-  Flag.withDescription("Port for the HTTP/WebSocket server."),
-  Flag.optional,
-);
-const hostFlag = Flag.string("host").pipe(
-  Flag.withDescription("Host/interface to bind (for example 127.0.0.1, 0.0.0.0, or a Tailnet IP)."),
-  Flag.optional,
-);
-const baseDirFlag = Flag.string("base-dir").pipe(
-  Flag.withDescription("Base directory path (equivalent to T3CODE_HOME)."),
-  Flag.optional,
-);
-const devUrlFlag = Flag.string("dev-url").pipe(
-  Flag.withSchema(Schema.URLFromString),
-  Flag.withDescription("Dev web URL to proxy/redirect to (equivalent to VITE_DEV_SERVER_URL)."),
-  Flag.optional,
-);
-const noBrowserFlag = Flag.boolean("no-browser").pipe(
-  Flag.withDescription("Disable automatic browser opening."),
-  Flag.optional,
-);
-const bootstrapFdFlag = Flag.integer("bootstrap-fd").pipe(
-  Flag.withSchema(Schema.Int),
-  Flag.withDescription("Read one-time bootstrap secrets from the given file descriptor."),
-  Flag.optional,
-);
-const autoBootstrapProjectFromCwdFlag = Flag.boolean("auto-bootstrap-project-from-cwd").pipe(
-  Flag.withDescription(
-    "Create a project for the current working directory on startup when missing.",
-  ),
-  Flag.optional,
-);
-const logWebSocketEventsFlag = Flag.boolean("log-websocket-events").pipe(
-  Flag.withDescription(
-    "Emit server-side logs for outbound WebSocket push traffic (equivalent to T3CODE_LOG_WS_EVENTS).",
-  ),
-  Flag.withAlias("log-ws-events"),
-  Flag.optional,
-);
-
-const EnvServerConfig = Config.all({
-  logLevel: Config.logLevel("T3CODE_LOG_LEVEL").pipe(Config.withDefault("Info")),
-  traceMinLevel: Config.logLevel("T3CODE_TRACE_MIN_LEVEL").pipe(Config.withDefault("Info")),
-  traceTimingEnabled: Config.boolean("T3CODE_TRACE_TIMING_ENABLED").pipe(Config.withDefault(true)),
-  traceFile: Config.string("T3CODE_TRACE_FILE").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-  traceMaxBytes: Config.int("T3CODE_TRACE_MAX_BYTES").pipe(Config.withDefault(10 * 1024 * 1024)),
-  traceMaxFiles: Config.int("T3CODE_TRACE_MAX_FILES").pipe(Config.withDefault(10)),
-  traceBatchWindowMs: Config.int("T3CODE_TRACE_BATCH_WINDOW_MS").pipe(Config.withDefault(200)),
-  otlpTracesUrl: Config.string("T3CODE_OTLP_TRACES_URL").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-  otlpMetricsUrl: Config.string("T3CODE_OTLP_METRICS_URL").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-  otlpExportIntervalMs: Config.int("T3CODE_OTLP_EXPORT_INTERVAL_MS").pipe(
-    Config.withDefault(10_000),
-  ),
-  otlpServiceName: Config.string("T3CODE_OTLP_SERVICE_NAME").pipe(Config.withDefault("t3-server")),
-  mode: Config.schema(RuntimeMode, "T3CODE_MODE").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-  port: Config.port("T3CODE_PORT").pipe(Config.option, Config.map(Option.getOrUndefined)),
-  host: Config.string("T3CODE_HOST").pipe(Config.option, Config.map(Option.getOrUndefined)),
-  t3Home: Config.string("T3CODE_HOME").pipe(Config.option, Config.map(Option.getOrUndefined)),
-  devUrl: Config.url("VITE_DEV_SERVER_URL").pipe(Config.option, Config.map(Option.getOrUndefined)),
-  noBrowser: Config.boolean("T3CODE_NO_BROWSER").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-  bootstrapFd: Config.int("T3CODE_BOOTSTRAP_FD").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-  autoBootstrapProjectFromCwd: Config.boolean("T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-  logWebSocketEvents: Config.boolean("T3CODE_LOG_WS_EVENTS").pipe(
-    Config.option,
-    Config.map(Option.getOrUndefined),
-  ),
-});
-
-interface CliServerFlags {
-  readonly mode: Option.Option<RuntimeMode>;
-  readonly port: Option.Option<number>;
-  readonly host: Option.Option<string>;
-  readonly baseDir: Option.Option<string>;
-  readonly cwd: Option.Option<string>;
-  readonly devUrl: Option.Option<URL>;
-  readonly noBrowser: Option.Option<boolean>;
-  readonly bootstrapFd: Option.Option<number>;
-  readonly autoBootstrapProjectFromCwd: Option.Option<boolean>;
-  readonly logWebSocketEvents: Option.Option<boolean>;
-}
-
-interface CliAuthLocationFlags {
-  readonly baseDir: Option.Option<string>;
-  readonly devUrl?: Option.Option<URL>;
-}
-
-const resolveOptionPrecedence = <Value>(
-  ...values: ReadonlyArray<Option.Option<Value>>
-): Option.Option<Value> => Option.firstSomeOf(values);
-
-const loadPersistedObservabilitySettings = Effect.fn(function* (settingsPath: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const exists = yield* fs.exists(settingsPath).pipe(Effect.orElseSucceed(() => false));
-  if (!exists) {
-    return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
-  }
-
-  const raw = yield* fs.readFileString(settingsPath).pipe(Effect.orElseSucceed(() => ""));
-  return parsePersistedServerObservabilitySettings(raw);
-});
-
-export const resolveServerConfig = (
-  flags: CliServerFlags,
-  cliLogLevel: Option.Option<LogLevel.LogLevel>,
-  options?: {
-    readonly startupPresentation?: StartupPresentation;
-    readonly forceAutoBootstrapProjectFromCwd?: boolean;
-  },
-) =>
-  Effect.gen(function* () {
-    const { findAvailablePort } = yield* NetService;
-    const path = yield* Path.Path;
-    const fs = yield* FileSystem.FileSystem;
-    const env = yield* EnvServerConfig;
-    const normalizedFlags = {
-      mode: flags.mode ?? Option.none(),
-      port: flags.port ?? Option.none(),
-      host: flags.host ?? Option.none(),
-      baseDir: flags.baseDir ?? Option.none(),
-      cwd: flags.cwd ?? Option.none(),
-      devUrl: flags.devUrl ?? Option.none(),
-      noBrowser: flags.noBrowser ?? Option.none(),
-      bootstrapFd: flags.bootstrapFd ?? Option.none(),
-      autoBootstrapProjectFromCwd: flags.autoBootstrapProjectFromCwd ?? Option.none(),
-      logWebSocketEvents: flags.logWebSocketEvents ?? Option.none(),
-    } satisfies CliServerFlags;
-    const bootstrapFd = Option.getOrUndefined(normalizedFlags.bootstrapFd) ?? env.bootstrapFd;
-    const bootstrapEnvelope =
-      bootstrapFd !== undefined
-        ? yield* readBootstrapEnvelope(BootstrapEnvelopeSchema, bootstrapFd)
-        : Option.none();
-    const bootstrap = Option.getOrUndefined(bootstrapEnvelope);
-
-    const mode: RuntimeMode = Option.getOrElse(
-      resolveOptionPrecedence(
-        normalizedFlags.mode,
-        Option.fromUndefinedOr(env.mode),
-        Option.fromUndefinedOr(bootstrap?.mode),
-      ),
-      () => "web",
-    );
-
-    const port = yield* Option.match(
-      resolveOptionPrecedence(
-        normalizedFlags.port,
-        Option.fromUndefinedOr(env.port),
-        Option.fromUndefinedOr(bootstrap?.port),
-      ),
-      {
-        onSome: (value) => Effect.succeed(value),
-        onNone: () => {
-          if (mode === "desktop") {
-            return Effect.succeed(DEFAULT_PORT);
-          }
-          return findAvailablePort(DEFAULT_PORT);
-        },
-      },
-    );
-    const devUrl = Option.getOrElse(
-      resolveOptionPrecedence(
-        normalizedFlags.devUrl,
-        Option.fromUndefinedOr(env.devUrl),
-        Option.fromUndefinedOr(bootstrap?.devUrl),
-      ),
-      () => undefined,
-    );
-    const baseDir = yield* resolveBaseDir(
-      Option.getOrUndefined(
-        resolveOptionPrecedence(
-          normalizedFlags.baseDir,
-          Option.fromUndefinedOr(env.t3Home),
-          Option.fromUndefinedOr(bootstrap?.t3Home),
-        ),
-      ),
-    );
-    const rawCwd = Option.getOrElse(normalizedFlags.cwd, () => process.cwd());
-    const cwd = path.resolve(yield* expandHomePath(rawCwd.trim()));
-    yield* fs.makeDirectory(cwd, { recursive: true });
-    const derivedPaths = yield* deriveServerPaths(baseDir, devUrl);
-    yield* ensureServerDirectories(derivedPaths);
-    const persistedObservabilitySettings = yield* loadPersistedObservabilitySettings(
-      derivedPaths.settingsPath,
-    );
-    const serverTracePath = env.traceFile ?? derivedPaths.serverTracePath;
-    yield* fs.makeDirectory(path.dirname(serverTracePath), { recursive: true });
-    const startupPresentation = options?.startupPresentation ?? "browser";
-    const isHeadlessStartup = startupPresentation === "headless";
-    const noBrowser = Option.getOrElse(
-      resolveOptionPrecedence(
-        isHeadlessStartup ? Option.some(true) : Option.none(),
-        normalizedFlags.noBrowser,
-        Option.fromUndefinedOr(env.noBrowser),
-        Option.fromUndefinedOr(bootstrap?.noBrowser),
-      ),
-      () => mode === "desktop",
-    );
-    const desktopBootstrapToken = bootstrap?.desktopBootstrapToken;
-    const autoBootstrapProjectFromCwd = Option.getOrElse(
-      resolveOptionPrecedence(
-        Option.fromUndefinedOr(options?.forceAutoBootstrapProjectFromCwd),
-        isHeadlessStartup ? Option.some(false) : Option.none(),
-        normalizedFlags.autoBootstrapProjectFromCwd,
-        Option.fromUndefinedOr(env.autoBootstrapProjectFromCwd),
-        Option.fromUndefinedOr(bootstrap?.autoBootstrapProjectFromCwd),
-      ),
-      () => mode === "web",
-    );
-    const logWebSocketEvents = Option.getOrElse(
-      resolveOptionPrecedence(
-        normalizedFlags.logWebSocketEvents,
-        Option.fromUndefinedOr(env.logWebSocketEvents),
-        Option.fromUndefinedOr(bootstrap?.logWebSocketEvents),
-      ),
-      () => Boolean(devUrl),
-    );
-    const staticDir = devUrl ? undefined : yield* resolveStaticDir();
-    const host = Option.getOrElse(
-      resolveOptionPrecedence(
-        normalizedFlags.host,
-        Option.fromUndefinedOr(env.host),
-        Option.fromUndefinedOr(bootstrap?.host),
-      ),
-      () => (mode === "desktop" ? "127.0.0.1" : undefined),
-    );
-    const logLevel = Option.getOrElse(cliLogLevel, () => env.logLevel);
-
-    const config: ServerConfigShape = {
-      logLevel,
-      traceMinLevel: env.traceMinLevel,
-      traceTimingEnabled: env.traceTimingEnabled,
-      traceBatchWindowMs: env.traceBatchWindowMs,
-      traceMaxBytes: env.traceMaxBytes,
-      traceMaxFiles: env.traceMaxFiles,
-      otlpTracesUrl:
-        env.otlpTracesUrl ??
-        bootstrap?.otlpTracesUrl ??
-        persistedObservabilitySettings.otlpTracesUrl,
-      otlpMetricsUrl:
-        env.otlpMetricsUrl ??
-        bootstrap?.otlpMetricsUrl ??
-        persistedObservabilitySettings.otlpMetricsUrl,
-      otlpExportIntervalMs: env.otlpExportIntervalMs,
-      otlpServiceName: env.otlpServiceName,
-      mode,
-      port,
-      cwd,
-      baseDir,
-      ...derivedPaths,
-      serverTracePath,
-      host,
-      staticDir,
-      devUrl,
-      noBrowser,
-      startupPresentation,
-      desktopBootstrapToken,
-      autoBootstrapProjectFromCwd,
-      logWebSocketEvents,
-    };
-
-    return config;
-  });
-
-const resolveCliAuthConfig = (
-  flags: CliAuthLocationFlags,
-  cliLogLevel: Option.Option<LogLevel.LogLevel>,
-) =>
-  resolveServerConfig(
-    {
-      mode: Option.none(),
-      port: Option.none(),
-      host: Option.none(),
-      baseDir: flags.baseDir,
-      cwd: Option.none(),
-      devUrl: flags.devUrl ?? Option.none(),
-      noBrowser: Option.none(),
-      bootstrapFd: Option.none(),
-      autoBootstrapProjectFromCwd: Option.none(),
-      logWebSocketEvents: Option.none(),
-    },
-    cliLogLevel,
-  );
-
-const DurationShorthandPattern = /^(?<value>\d+)(?<unit>ms|s|m|h|d|w)$/i;
-
-const parseDurationInput = (value: string): Duration.Duration | null => {
-  const trimmed = value.trim();
-  if (trimmed.length === 0) return null;
-
-  const shorthand = DurationShorthandPattern.exec(trimmed);
-  const normalizedInput = shorthand?.groups
-    ? (() => {
-        const amountText = shorthand.groups.value;
-        const unitText = shorthand.groups.unit;
-        if (typeof amountText !== "string" || typeof unitText !== "string") {
-          return null;
-        }
-
-        const amount = Number.parseInt(amountText, 10);
-        if (!Number.isFinite(amount)) return null;
-
-        switch (unitText.toLowerCase()) {
-          case "ms":
-            return `${amount} millis`;
-          case "s":
-            return `${amount} seconds`;
-          case "m":
-            return `${amount} minutes`;
-          case "h":
-            return `${amount} hours`;
-          case "d":
-            return `${amount} days`;
-          case "w":
-            return `${amount} weeks`;
-          default:
-            return null;
-        }
-      })()
-    : (trimmed as Duration.Input);
-
-  if (normalizedInput === null) return null;
-
-  const decoded = Duration.fromInput(normalizedInput as Duration.Input);
-  return Option.isSome(decoded) ? decoded.value : null;
-};
-
-const DurationFromString = Schema.String.pipe(
-  Schema.decodeTo(
-    Schema.Duration,
-    SchemaTransformation.transformOrFail({
-      decode: (value) => {
-        const duration = parseDurationInput(value);
-        if (duration !== null) {
-          return Effect.succeed(duration);
-        }
-        return Effect.fail(
-          new SchemaIssue.InvalidValue(Option.some(value), {
-            message: "Invalid duration. Use values like 5m, 1h, 30d, or 15 minutes.",
-          }),
-        );
-      },
-      encode: (duration) => Effect.succeed(Duration.format(duration)),
-    }),
-  ),
-);
-
-const runWithAuthControlPlane = <A, E>(
-  flags: CliAuthLocationFlags,
-  run: (authControlPlane: AuthControlPlaneShape) => Effect.Effect<A, E>,
-  options?: {
-    readonly quietLogs?: boolean;
-  },
-) =>
-  Effect.gen(function* () {
-    const logLevel = yield* GlobalFlag.LogLevel;
-    const config = yield* resolveCliAuthConfig(flags, logLevel);
-    const minimumLogLevel = options?.quietLogs ? "Error" : config.logLevel;
-    return yield* Effect.gen(function* () {
-      const authControlPlane = yield* AuthControlPlane;
-      return yield* run(authControlPlane);
-    }).pipe(
-      Effect.provide(
-        Layer.mergeAll(AuthControlPlaneRuntimeLive).pipe(
-          Layer.provide(Layer.succeed(ServerConfig, config)),
-          Layer.provide(Layer.succeed(References.MinimumLogLevel, minimumLogLevel)),
-        ),
-      ),
-    );
-  });
-
-type ProjectMutationTarget = {
-  readonly id: ProjectId;
-  readonly title: string;
-  readonly workspaceRoot: string;
-};
-
-type ProjectCommandExecutionMode = "live" | "offline";
-type ProjectCliDispatchCommand = Extract<
-  ClientOrchestrationCommand,
-  { type: "project.create" | "project.meta.update" | "project.delete" }
->;
-
-const ProjectCliRuntimeLive = Layer.mergeAll(
-  WorkspacePathsLive,
-  OrchestrationLayerLive.pipe(
-    Layer.provideMerge(RepositoryIdentityResolverLive),
-    Layer.provideMerge(SqlitePersistenceLayerLive),
-  ),
-);
-
-const PROJECT_CLI_LIVE_SERVER_TIMEOUT = Duration.seconds(1);
-const OrchestrationHttpErrorResponse = Schema.Struct({
-  error: Schema.String,
-});
-
-const withProjectCliSessionToken = <A, E, R>(
-  authControlPlane: AuthControlPlaneShape,
-  run: (token: string) => Effect.Effect<A, E, R>,
-) =>
-  Effect.acquireUseRelease(
-    authControlPlane.issueSession({
-      role: "owner",
-      label: "t3 project cli",
-    }),
-    (issued) => run(issued.token),
-    (issued) => authControlPlane.revokeSession(issued.sessionId).pipe(Effect.ignore({ log: true })),
-  );
-
-const withProjectCliLiveServerTimeout = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
-  effect.pipe(Effect.timeout(PROJECT_CLI_LIVE_SERVER_TIMEOUT));
-
-const runLiveServerRequest = <A, E extends Error, R>(
-  request: HttpClientRequest.HttpClientRequest,
-  handle: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<A, E, R>,
-) =>
-  Effect.gen(function* () {
-    const httpClient = yield* HttpClient.HttpClient;
-    const response = yield* httpClient.execute(request);
-    return yield* handle(response);
-  }).pipe(withProjectCliLiveServerTimeout);
-
-const decodeOrchestrationReadModelResponse = (response: HttpClientResponse.HttpClientResponse) =>
-  HttpClientResponse.schemaBodyJson(OrchestrationReadModel)(response);
-
-const readErrorMessageFromResponse = (response: HttpClientResponse.HttpClientResponse) =>
-  HttpClientResponse.schemaBodyJson(OrchestrationHttpErrorResponse)(response).pipe(
-    Effect.map((body) => body.error),
-    Effect.catch(() => Effect.succeed(null)),
-    Effect.map((body) => {
-      if (typeof body === "string" && body.trim().length > 0) {
-        return body;
-      }
-      return `Server request failed with status ${response.status}.`;
-    }),
-  );
-
-const normalizeWorkspaceRootForProjectCommand = Effect.fn(
-  "normalizeWorkspaceRootForProjectCommand",
-)(function* (workspaceRoot: string) {
-  const workspacePaths = yield* WorkspacePaths;
-  return yield* workspacePaths.normalizeWorkspaceRoot(workspaceRoot);
-});
-
-const resolveProjectTitle = Effect.fn("resolveProjectTitle")(function* (
-  workspaceRoot: string,
-  explicitTitle?: string,
-) {
-  if (explicitTitle !== undefined) {
-    const trimmed = explicitTitle.trim();
-    if (trimmed.length > 0) {
-      return trimmed;
-    }
-    return yield* Effect.fail(new Error("Project title cannot be empty."));
-  }
-
-  const path = yield* Path.Path;
-  const basename = path.basename(workspaceRoot).trim();
-  return basename.length > 0 ? basename : "project";
-});
-
-const findActiveProjectTarget = Effect.fn("findActiveProjectTarget")(function* (input: {
-  readonly snapshot: OrchestrationReadModel;
-  readonly identifier: string;
-}) {
-  const trimmedIdentifier = input.identifier.trim();
-  if (trimmedIdentifier.length === 0) {
-    return yield* Effect.fail(new Error("Project identifier cannot be empty."));
-  }
-
-  const activeProjects = input.snapshot.projects.filter((project) => project.deletedAt === null);
-  const exactIdMatch = activeProjects.find((project) => project.id === trimmedIdentifier);
-  if (exactIdMatch) {
-    return {
-      id: exactIdMatch.id,
-      title: exactIdMatch.title,
-      workspaceRoot: exactIdMatch.workspaceRoot,
-    } satisfies ProjectMutationTarget;
-  }
-
-  const normalizedWorkspaceRootResult = yield* Effect.exit(
-    normalizeWorkspaceRootForProjectCommand(trimmedIdentifier),
-  );
-  const normalizedWorkspaceRoot = Exit.isSuccess(normalizedWorkspaceRootResult)
-    ? normalizedWorkspaceRootResult.value
-    : null;
-
-  const exactWorkspaceMatch =
-    normalizedWorkspaceRoot === null
-      ? undefined
-      : activeProjects.find((project) => project.workspaceRoot === normalizedWorkspaceRoot);
-
-  const resolved = exactWorkspaceMatch;
-  if (!resolved) {
-    return yield* Effect.fail(new Error(`No active project found for '${trimmedIdentifier}'.`));
-  }
-
-  return {
-    id: resolved.id,
-    title: resolved.title,
-    workspaceRoot: resolved.workspaceRoot,
-  } satisfies ProjectMutationTarget;
-});
-
-const fetchLiveOrchestrationSnapshot = (origin: string, bearerToken: string) =>
-  runLiveServerRequest(
-    HttpClientRequest.get(`${origin}/api/orchestration/snapshot`).pipe(
-      HttpClientRequest.acceptJson,
-      HttpClientRequest.bearerToken(bearerToken),
-    ),
-    HttpClientResponse.matchStatus({
-      "2xx": decodeOrchestrationReadModelResponse,
-      orElse: (response) =>
-        readErrorMessageFromResponse(response).pipe(
-          Effect.flatMap((message) => Effect.fail(new Error(message))),
-        ),
-    }),
-  );
-
-const dispatchLiveOrchestrationCommand = (
-  origin: string,
-  bearerToken: string,
-  command: ProjectCliDispatchCommand,
-) =>
-  HttpClientRequest.post(`${origin}/api/orchestration/dispatch`).pipe(
-    HttpClientRequest.acceptJson,
-    HttpClientRequest.bearerToken(bearerToken),
-    HttpClientRequest.bodyJson(command),
-    Effect.flatMap((request) =>
-      runLiveServerRequest(
-        request,
-        HttpClientResponse.matchStatus({
-          "2xx": () => Effect.void,
-          orElse: (response) =>
-            readErrorMessageFromResponse(response).pipe(
-              Effect.flatMap((message) => Effect.fail(new Error(message))),
-            ),
-        }),
-      ),
-    ),
-  );
-
-const getOfflineSnapshot = Effect.fn("getOfflineSnapshot")(function* () {
-  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
-  return yield* projectionSnapshotQuery.getSnapshot();
-});
-
-const tryResolveLiveProjectExecutionMode = Effect.fn("tryResolveLiveProjectExecutionMode")(
-  function* (authControlPlane: AuthControlPlaneShape, config: ServerConfigShape) {
-    const runtimeState = yield* readPersistedServerRuntimeState(config.serverRuntimeStatePath);
-    if (Option.isNone(runtimeState)) {
-      return Option.none<{ readonly origin: string }>();
-    }
-
-    const attempt = withProjectCliSessionToken(authControlPlane, (token) =>
-      fetchLiveOrchestrationSnapshot(runtimeState.value.origin, token).pipe(
-        Effect.as({
-          origin: runtimeState.value.origin,
-        }),
-      ),
-    );
-
-    const attempted = yield* Effect.exit(attempt);
-    if (Exit.isSuccess(attempted)) {
-      return Option.some(attempted.value);
-    }
-
-    yield* clearPersistedServerRuntimeState(config.serverRuntimeStatePath);
-    return Option.none<{ readonly origin: string }>();
-  },
-);
-
-const runProjectMutation = Effect.fn("runProjectMutation")(function* (
-  flags: CliAuthLocationFlags,
-  run: (input: {
-    readonly snapshot: OrchestrationReadModel;
-    readonly dispatch: (
-      command: ProjectCliDispatchCommand,
-    ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
-    readonly mode: ProjectCommandExecutionMode;
-  }) => Effect.Effect<
-    string,
-    Error,
-    FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | WorkspacePaths
-  >,
-) {
-  const logLevel = yield* GlobalFlag.LogLevel;
-  const config = yield* resolveCliAuthConfig(flags, logLevel);
-  const minimumLogLevel = config.logLevel;
-
-  return yield* Effect.gen(function* () {
-    const authControlPlane = yield* AuthControlPlane;
-    const liveMode = yield* tryResolveLiveProjectExecutionMode(authControlPlane, config);
-
-    if (Option.isSome(liveMode)) {
-      return yield* withProjectCliSessionToken(authControlPlane, (token) =>
-        Effect.gen(function* () {
-          const snapshot = yield* fetchLiveOrchestrationSnapshot(liveMode.value.origin, token);
-          const output = yield* run({
-            snapshot,
-            dispatch: (command) =>
-              dispatchLiveOrchestrationCommand(liveMode.value.origin, token, command),
-            mode: "live",
-          });
-          yield* Console.log(output);
-        }),
-      );
-    }
-
-    const offlineRuntimeLayer = ProjectCliRuntimeLive.pipe(
-      Layer.provide(Layer.succeed(ServerConfig, config)),
-      Layer.provide(Layer.succeed(References.MinimumLogLevel, minimumLogLevel)),
-    );
-
-    return yield* Effect.gen(function* () {
-      const snapshot = yield* getOfflineSnapshot();
-      const orchestrationEngine = yield* OrchestrationEngineService;
-      const output = yield* run({
-        snapshot,
-        dispatch: (command) => orchestrationEngine.dispatch(command),
-        mode: "offline",
-      });
-      yield* Console.log(output);
-    }).pipe(Effect.provide(offlineRuntimeLayer));
-  }).pipe(
-    Effect.provide(
-      Layer.mergeAll(AuthControlPlaneRuntimeLive, WorkspacePathsLive).pipe(
-        Layer.provideMerge(FetchHttpClient.layer),
-        Layer.provide(Layer.succeed(ServerConfig, config)),
-        Layer.provide(Layer.succeed(References.MinimumLogLevel, minimumLogLevel)),
-      ),
-    ),
-  );
-});
-
-const sharedServerLocationFlags = {
-  baseDir: baseDirFlag,
-  devUrl: devUrlFlag,
-} as const;
-
-const projectLocationFlags = {
-  baseDir: baseDirFlag,
-} as const;
-
-const sharedServerCommandFlags = {
-  mode: modeFlag,
-  port: portFlag,
-  host: hostFlag,
-  baseDir: baseDirFlag,
-  cwd: Argument.string("cwd").pipe(
-    Argument.withDescription(
-      "Working directory for provider sessions (defaults to the current directory).",
-    ),
-    Argument.optional,
-  ),
-  devUrl: devUrlFlag,
-  noBrowser: noBrowserFlag,
-  bootstrapFd: bootstrapFdFlag,
-  autoBootstrapProjectFromCwd: autoBootstrapProjectFromCwdFlag,
-  logWebSocketEvents: logWebSocketEventsFlag,
-} as const;
-
-const authLocationFlags = sharedServerLocationFlags;
-
-const ttlFlag = Flag.string("ttl").pipe(
-  Flag.withSchema(DurationFromString),
-  Flag.withDescription("TTL, for example `5m`, `1h`, `30d`, or `15 minutes`."),
-  Flag.optional,
-);
-
-const jsonFlag = Flag.boolean("json").pipe(
-  Flag.withDescription("Emit JSON instead of human-readable output."),
-  Flag.withDefault(false),
-);
-
-const sessionRoleFlag = Flag.choice("role", ["owner", "client"]).pipe(
-  Flag.withDescription("Role for the issued bearer session."),
-  Flag.withDefault("owner"),
-);
-
-const labelFlag = Flag.string("label").pipe(
-  Flag.withDescription("Optional human-readable label."),
-  Flag.optional,
-);
-
-const subjectFlag = Flag.string("subject").pipe(
-  Flag.withDescription("Optional session subject."),
-  Flag.optional,
-);
-
-const baseUrlFlag = Flag.string("base-url").pipe(
-  Flag.withDescription("Optional public base URL used to print a ready `/pair#token=...` link."),
-  Flag.optional,
-);
-
-const tokenOnlyFlag = Flag.boolean("token-only").pipe(
-  Flag.withDescription("Print only the issued bearer token."),
-  Flag.withDefault(false),
-);
-
-const pairingCreateCommand = Command.make("create", {
-  ...authLocationFlags,
-  ttl: ttlFlag,
-  label: labelFlag,
-  baseUrl: baseUrlFlag,
-  json: jsonFlag,
-}).pipe(
-  Command.withDescription("Issue a new client pairing token."),
-  Command.withHandler((flags) =>
-    runWithAuthControlPlane(
-      flags,
-      (authControlPlane) =>
-        Effect.gen(function* () {
-          const issued = yield* authControlPlane.createPairingLink({
-            role: "client",
-            subject: "one-time-token",
-            ...(Option.isSome(flags.ttl) ? { ttl: flags.ttl.value } : {}),
-            ...(Option.isSome(flags.label) ? { label: flags.label.value } : {}),
-          });
-          const output = formatIssuedPairingCredential(issued, {
-            json: flags.json,
-            ...(Option.isSome(flags.baseUrl) ? { baseUrl: flags.baseUrl.value } : {}),
-          });
-          yield* Console.log(output);
-        }),
-      {
-        quietLogs: flags.json,
-      },
-    ),
-  ),
-);
-
-const pairingListCommand = Command.make("list", {
-  ...authLocationFlags,
-  json: jsonFlag,
-}).pipe(
-  Command.withDescription("List active client pairing tokens without revealing their secrets."),
-  Command.withHandler((flags) =>
-    runWithAuthControlPlane(
-      flags,
-      (authControlPlane) =>
-        Effect.gen(function* () {
-          const pairingLinks = yield* authControlPlane.listPairingLinks({ role: "client" });
-          yield* Console.log(formatPairingCredentialList(pairingLinks, { json: flags.json }));
-        }),
-      {
-        quietLogs: flags.json,
-      },
-    ),
-  ),
-);
-
-const pairingRevokeCommand = Command.make("revoke", {
-  ...authLocationFlags,
-  id: Argument.string("id").pipe(Argument.withDescription("Pairing credential id to revoke.")),
-}).pipe(
-  Command.withDescription("Revoke an active client pairing token."),
-  Command.withHandler((flags) =>
-    runWithAuthControlPlane(flags, (authControlPlane) =>
-      Effect.gen(function* () {
-        const revoked = yield* authControlPlane.revokePairingLink(flags.id);
-        yield* Console.log(
-          revoked
-            ? `Revoked pairing credential ${flags.id}.\n`
-            : `No active pairing credential found for ${flags.id}.\n`,
-        );
-      }),
-    ),
-  ),
-);
-
-const pairingCommand = Command.make("pairing").pipe(
-  Command.withDescription("Manage one-time client pairing tokens."),
-  Command.withSubcommands([pairingCreateCommand, pairingListCommand, pairingRevokeCommand]),
-);
-
-const sessionIssueCommand = Command.make("issue", {
-  ...authLocationFlags,
-  ttl: ttlFlag,
-  role: sessionRoleFlag,
-  label: labelFlag,
-  subject: subjectFlag,
-  tokenOnly: tokenOnlyFlag,
-  json: jsonFlag,
-}).pipe(
-  Command.withDescription("Issue a bearer session token for headless or remote clients."),
-  Command.withHandler((flags) =>
-    runWithAuthControlPlane(
-      flags,
-      (authControlPlane) =>
-        Effect.gen(function* () {
-          const issued = yield* authControlPlane.issueSession({
-            role: flags.role,
-            ...(Option.isSome(flags.ttl) ? { ttl: flags.ttl.value } : {}),
-            ...(Option.isSome(flags.label) ? { label: flags.label.value } : {}),
-            ...(Option.isSome(flags.subject) ? { subject: flags.subject.value } : {}),
-          });
-          yield* Console.log(
-            formatIssuedSession(issued, {
-              json: flags.json,
-              tokenOnly: flags.tokenOnly,
-            }),
-          );
-        }),
-      {
-        quietLogs: flags.json || flags.tokenOnly,
-      },
-    ),
-  ),
-);
-
-const sessionListCommand = Command.make("list", {
-  ...authLocationFlags,
-  json: jsonFlag,
-}).pipe(
-  Command.withDescription("List active sessions without revealing bearer tokens."),
-  Command.withHandler((flags) =>
-    runWithAuthControlPlane(
-      flags,
-      (authControlPlane) =>
-        Effect.gen(function* () {
-          const sessions = yield* authControlPlane.listSessions();
-          yield* Console.log(formatSessionList(sessions, { json: flags.json }));
-        }),
-      {
-        quietLogs: flags.json,
-      },
-    ),
-  ),
-);
-
-const sessionRevokeCommand = Command.make("revoke", {
-  ...authLocationFlags,
-  sessionId: Argument.string("session-id").pipe(
-    Argument.withDescription("Session id to revoke."),
-    Argument.withSchema(AuthSessionId),
-  ),
-}).pipe(
-  Command.withDescription("Revoke an active session."),
-  Command.withHandler((flags) =>
-    runWithAuthControlPlane(flags, (authControlPlane) =>
-      Effect.gen(function* () {
-        const revoked = yield* authControlPlane.revokeSession(flags.sessionId);
-        yield* Console.log(
-          revoked
-            ? `Revoked session ${flags.sessionId}.\n`
-            : `No active session found for ${flags.sessionId}.\n`,
-        );
-      }),
-    ),
-  ),
-);
-
-const sessionCommand = Command.make("session").pipe(
-  Command.withDescription("Manage bearer sessions."),
-  Command.withSubcommands([sessionIssueCommand, sessionListCommand, sessionRevokeCommand]),
-);
-
-const authCommand = Command.make("auth").pipe(
-  Command.withDescription("Manage the local auth control plane for headless deployments."),
-  Command.withSubcommands([pairingCommand, sessionCommand]),
-);
-
-const projectAddCommand = Command.make("add", {
-  ...projectLocationFlags,
-  workspaceRoot: Argument.string("path").pipe(
-    Argument.withDescription("Workspace root to add as a project."),
-  ),
-  title: Flag.string("title").pipe(Flag.withDescription("Optional project title."), Flag.optional),
-}).pipe(
-  Command.withDescription("Add a project."),
-  Command.withHandler((flags) =>
-    runProjectMutation(
-      flags,
-      Effect.fn("projectAddMutation")(function* ({
-        snapshot,
-        dispatch,
-      }: {
-        readonly snapshot: OrchestrationReadModel;
-        readonly dispatch: (
-          command: ProjectCliDispatchCommand,
-        ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
-      }) {
-        const workspaceRoot = yield* normalizeWorkspaceRootForProjectCommand(flags.workspaceRoot);
-        const existingProject = snapshot.projects.find(
-          (project) => project.deletedAt === null && project.workspaceRoot === workspaceRoot,
-        );
-        if (existingProject) {
-          return yield* Effect.fail(
-            new Error(`An active project already exists for '${workspaceRoot}'.`),
-          );
-        }
-
-        const title = yield* resolveProjectTitle(workspaceRoot, Option.getOrUndefined(flags.title));
-        const projectId = ProjectId.make(crypto.randomUUID());
-        yield* dispatch({
-          type: "project.create",
-          commandId: CommandId.make(crypto.randomUUID()),
-          projectId,
-          title,
-          workspaceRoot,
-          defaultModelSelection: getAutoBootstrapDefaultModelSelection(),
-          createdAt: new Date().toISOString(),
-        });
-        return `Added project ${projectId} (${title}) at ${workspaceRoot}.`;
-      }),
-    ),
-  ),
-);
-
-const projectRemoveCommand = Command.make("remove", {
-  ...projectLocationFlags,
-  project: Argument.string("project").pipe(
-    Argument.withDescription("Project id or workspace root to remove."),
-  ),
-}).pipe(
-  Command.withDescription("Remove a project."),
-  Command.withHandler((flags) =>
-    runProjectMutation(
-      flags,
-      Effect.fn("projectRemoveMutation")(function* ({
-        snapshot,
-        dispatch,
-      }: {
-        readonly snapshot: OrchestrationReadModel;
-        readonly dispatch: (
-          command: ProjectCliDispatchCommand,
-        ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
-      }) {
-        const project = yield* findActiveProjectTarget({
-          snapshot,
-          identifier: flags.project,
-        });
-        yield* dispatch({
-          type: "project.delete",
-          commandId: CommandId.make(crypto.randomUUID()),
-          projectId: project.id,
-        });
-        return `Removed project ${project.id} (${project.title}).`;
-      }),
-    ),
-  ),
-);
-
-const projectRenameCommand = Command.make("rename", {
-  ...projectLocationFlags,
-  project: Argument.string("project").pipe(
-    Argument.withDescription("Project id or workspace root to rename."),
-  ),
-  title: Argument.string("title").pipe(Argument.withDescription("New project title.")),
-}).pipe(
-  Command.withDescription("Rename a project."),
-  Command.withHandler((flags) =>
-    runProjectMutation(
-      flags,
-      Effect.fn("projectRenameMutation")(function* ({
-        snapshot,
-        dispatch,
-      }: {
-        readonly snapshot: OrchestrationReadModel;
-        readonly dispatch: (
-          command: ProjectCliDispatchCommand,
-        ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
-      }) {
-        const project = yield* findActiveProjectTarget({
-          snapshot,
-          identifier: flags.project,
-        });
-        const nextTitle = yield* resolveProjectTitle(project.workspaceRoot, flags.title);
-        if (nextTitle === project.title) {
-          return `Project ${project.id} is already named ${nextTitle}.`;
-        }
-
-        yield* dispatch({
-          type: "project.meta.update",
-          commandId: CommandId.make(crypto.randomUUID()),
-          projectId: project.id,
-          title: nextTitle,
-        });
-        return `Renamed project ${project.id} to ${nextTitle}.`;
-      }),
-    ),
-  ),
-);
-
-const projectCommand = Command.make("project").pipe(
-  Command.withDescription("Manage projects."),
-  Command.withSubcommands([projectAddCommand, projectRemoveCommand, projectRenameCommand]),
-);
-
-const runServerCommand = (
-  flags: CliServerFlags,
-  options?: {
-    readonly startupPresentation?: StartupPresentation;
-    readonly forceAutoBootstrapProjectFromCwd?: boolean;
-  },
-) =>
-  Effect.gen(function* () {
-    const logLevel = yield* GlobalFlag.LogLevel;
-    const config = yield* resolveServerConfig(flags, logLevel, options);
-    return yield* runServer.pipe(Effect.provideService(ServerConfig, config));
-  });
-
-const startCommand = Command.make("start", { ...sharedServerCommandFlags }).pipe(
-  Command.withDescription("Run the T3 Code server."),
-  Command.withHandler((flags) => runServerCommand(flags)),
-);
-
-const serveCommand = Command.make("serve", { ...sharedServerCommandFlags }).pipe(
-  Command.withDescription(
-    "Run the T3 Code server without opening a browser and print headless pairing details.",
-  ),
-  Command.withHandler((flags) =>
-    runServerCommand(flags, {
-      startupPresentation: "headless",
-      forceAutoBootstrapProjectFromCwd: false,
-    }),
-  ),
-);
-
-export const cli = Command.make("t3", { ...sharedServerCommandFlags }).pipe(
-  Command.withDescription("Run the T3 Code server."),
-  Command.withHandler((flags) => runServerCommand(flags)),
-  Command.withSubcommands([startCommand, serveCommand, authCommand, projectCommand]),
-);
diff --git a/apps/server/src/cli/auth.ts b/apps/server/src/cli/auth.ts
new file mode 100644
index 00000000000..d54731b4a24
--- /dev/null
+++ b/apps/server/src/cli/auth.ts
@@ -0,0 +1,247 @@
+import { AuthSessionId } from "@t3tools/contracts";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as References from "effect/References";
+import { Argument, Command, Flag, GlobalFlag } from "effect/unstable/cli";
+
+import { AuthControlPlaneRuntimeLive } from "../auth/Layers/AuthControlPlane.ts";
+import { AuthControlPlane } from "../auth/Services/AuthControlPlane.ts";
+import type { AuthControlPlaneShape } from "../auth/Services/AuthControlPlane.ts";
+import {
+  formatIssuedPairingCredential,
+  formatIssuedSession,
+  formatPairingCredentialList,
+  formatSessionList,
+} from "../cliAuthFormat.ts";
+import { ServerConfig } from "../config.ts";
+import {
+  authLocationFlags,
+  type CliAuthLocationFlags,
+  DurationFromString,
+  resolveCliAuthConfig,
+} from "./config.ts";
+
+const runWithAuthControlPlane = <A, E>(
+  flags: CliAuthLocationFlags,
+  run: (authControlPlane: AuthControlPlaneShape) => Effect.Effect<A, E>,
+  options?: {
+    readonly quietLogs?: boolean;
+  },
+) =>
+  Effect.gen(function* () {
+    const logLevel = yield* GlobalFlag.LogLevel;
+    const config = yield* resolveCliAuthConfig(flags, logLevel);
+    const minimumLogLevel = options?.quietLogs ? "Error" : config.logLevel;
+    return yield* Effect.gen(function* () {
+      const authControlPlane = yield* AuthControlPlane;
+      return yield* run(authControlPlane);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(AuthControlPlaneRuntimeLive).pipe(
+          Layer.provide(Layer.succeed(ServerConfig, config)),
+          Layer.provide(Layer.succeed(References.MinimumLogLevel, minimumLogLevel)),
+        ),
+      ),
+    );
+  });
+
+const ttlFlag = Flag.string("ttl").pipe(
+  Flag.withSchema(DurationFromString),
+  Flag.withDescription("TTL, for example `5m`, `1h`, `30d`, or `15 minutes`."),
+  Flag.optional,
+);
+
+const jsonFlag = Flag.boolean("json").pipe(
+  Flag.withDescription("Emit JSON instead of human-readable output."),
+  Flag.withDefault(false),
+);
+
+const sessionRoleFlag = Flag.choice("role", ["owner", "client"]).pipe(
+  Flag.withDescription("Role for the issued bearer session."),
+  Flag.withDefault("owner"),
+);
+
+const labelFlag = Flag.string("label").pipe(
+  Flag.withDescription("Optional human-readable label."),
+  Flag.optional,
+);
+
+const subjectFlag = Flag.string("subject").pipe(
+  Flag.withDescription("Optional session subject."),
+  Flag.optional,
+);
+
+const baseUrlFlag = Flag.string("base-url").pipe(
+  Flag.withDescription("Optional public base URL used to print a ready `/pair#token=...` link."),
+  Flag.optional,
+);
+
+const tokenOnlyFlag = Flag.boolean("token-only").pipe(
+  Flag.withDescription("Print only the issued bearer token."),
+  Flag.withDefault(false),
+);
+
+const pairingCreateCommand = Command.make("create", {
+  ...authLocationFlags,
+  ttl: ttlFlag,
+  label: labelFlag,
+  baseUrl: baseUrlFlag,
+  json: jsonFlag,
+}).pipe(
+  Command.withDescription("Issue a new client pairing token."),
+  Command.withHandler((flags) =>
+    runWithAuthControlPlane(
+      flags,
+      (authControlPlane) =>
+        Effect.gen(function* () {
+          const issued = yield* authControlPlane.createPairingLink({
+            role: "client",
+            subject: "one-time-token",
+            ...(Option.isSome(flags.ttl) ? { ttl: flags.ttl.value } : {}),
+            ...(Option.isSome(flags.label) ? { label: flags.label.value } : {}),
+          });
+          const output = formatIssuedPairingCredential(issued, {
+            json: flags.json,
+            ...(Option.isSome(flags.baseUrl) ? { baseUrl: flags.baseUrl.value } : {}),
+          });
+          yield* Console.log(output);
+        }),
+      {
+        quietLogs: flags.json,
+      },
+    ),
+  ),
+);
+
+const pairingListCommand = Command.make("list", {
+  ...authLocationFlags,
+  json: jsonFlag,
+}).pipe(
+  Command.withDescription("List active client pairing tokens without revealing their secrets."),
+  Command.withHandler((flags) =>
+    runWithAuthControlPlane(
+      flags,
+      (authControlPlane) =>
+        Effect.gen(function* () {
+          const pairingLinks = yield* authControlPlane.listPairingLinks({ role: "client" });
+          yield* Console.log(formatPairingCredentialList(pairingLinks, { json: flags.json }));
+        }),
+      {
+        quietLogs: flags.json,
+      },
+    ),
+  ),
+);
+
+const pairingRevokeCommand = Command.make("revoke", {
+  ...authLocationFlags,
+  id: Argument.string("id").pipe(Argument.withDescription("Pairing credential id to revoke.")),
+}).pipe(
+  Command.withDescription("Revoke an active client pairing token."),
+  Command.withHandler((flags) =>
+    runWithAuthControlPlane(flags, (authControlPlane) =>
+      Effect.gen(function* () {
+        const revoked = yield* authControlPlane.revokePairingLink(flags.id);
+        yield* Console.log(
+          revoked
+            ? `Revoked pairing credential ${flags.id}.\n`
+            : `No active pairing credential found for ${flags.id}.\n`,
+        );
+      }),
+    ),
+  ),
+);
+
+const pairingCommand = Command.make("pairing").pipe(
+  Command.withDescription("Manage one-time client pairing tokens."),
+  Command.withSubcommands([pairingCreateCommand, pairingListCommand, pairingRevokeCommand]),
+);
+
+const sessionIssueCommand = Command.make("issue", {
+  ...authLocationFlags,
+  ttl: ttlFlag,
+  role: sessionRoleFlag,
+  label: labelFlag,
+  subject: subjectFlag,
+  tokenOnly: tokenOnlyFlag,
+  json: jsonFlag,
+}).pipe(
+  Command.withDescription("Issue a bearer session token for headless or remote clients."),
+  Command.withHandler((flags) =>
+    runWithAuthControlPlane(
+      flags,
+      (authControlPlane) =>
+        Effect.gen(function* () {
+          const issued = yield* authControlPlane.issueSession({
+            role: flags.role,
+            ...(Option.isSome(flags.ttl) ? { ttl: flags.ttl.value } : {}),
+            ...(Option.isSome(flags.label) ? { label: flags.label.value } : {}),
+            ...(Option.isSome(flags.subject) ? { subject: flags.subject.value } : {}),
+          });
+          yield* Console.log(
+            formatIssuedSession(issued, {
+              json: flags.json,
+              tokenOnly: flags.tokenOnly,
+            }),
+          );
+        }),
+      {
+        quietLogs: flags.json || flags.tokenOnly,
+      },
+    ),
+  ),
+);
+
+const sessionListCommand = Command.make("list", {
+  ...authLocationFlags,
+  json: jsonFlag,
+}).pipe(
+  Command.withDescription("List active sessions without revealing bearer tokens."),
+  Command.withHandler((flags) =>
+    runWithAuthControlPlane(
+      flags,
+      (authControlPlane) =>
+        Effect.gen(function* () {
+          const sessions = yield* authControlPlane.listSessions();
+          yield* Console.log(formatSessionList(sessions, { json: flags.json }));
+        }),
+      {
+        quietLogs: flags.json,
+      },
+    ),
+  ),
+);
+
+const sessionRevokeCommand = Command.make("revoke", {
+  ...authLocationFlags,
+  sessionId: Argument.string("session-id").pipe(
+    Argument.withDescription("Session id to revoke."),
+    Argument.withSchema(AuthSessionId),
+  ),
+}).pipe(
+  Command.withDescription("Revoke an active session."),
+  Command.withHandler((flags) =>
+    runWithAuthControlPlane(flags, (authControlPlane) =>
+      Effect.gen(function* () {
+        const revoked = yield* authControlPlane.revokeSession(flags.sessionId);
+        yield* Console.log(
+          revoked
+            ? `Revoked session ${flags.sessionId}.\n`
+            : `No active session found for ${flags.sessionId}.\n`,
+        );
+      }),
+    ),
+  ),
+);
+
+const sessionCommand = Command.make("session").pipe(
+  Command.withDescription("Manage bearer sessions."),
+  Command.withSubcommands([sessionIssueCommand, sessionListCommand, sessionRevokeCommand]),
+);
+
+export const authCommand = Command.make("auth").pipe(
+  Command.withDescription("Manage the local auth control plane for headless deployments."),
+  Command.withSubcommands([pairingCommand, sessionCommand]),
+);
diff --git a/apps/server/src/cli-config.test.ts b/apps/server/src/cli/config.test.ts
similarity index 77%
rename from apps/server/src/cli-config.test.ts
rename to apps/server/src/cli/config.test.ts
index 6fa6e0c96b6..9e73773d5a5 100644
--- a/apps/server/src/cli-config.test.ts
+++ b/apps/server/src/cli/config.test.ts
@@ -1,12 +1,38 @@
-import os from "node:os";
+import NodeOS from "node:os";
 
 import { assert, expect, it } from "@effect/vitest";
-import { ConfigProvider, Effect, FileSystem, Layer, Option, Path } from "effect";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
 
-import { NetService } from "@t3tools/shared/Net";
+import {
+  DesktopBackendBootstrap,
+  type DesktopBackendBootstrap as DesktopBackendBootstrapValue,
+} from "@t3tools/contracts";
+import * as NetService from "@t3tools/shared/Net";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { deriveServerPaths } from "./config";
-import { resolveServerConfig } from "./cli";
+import { deriveServerPaths } from "../config.ts";
+import { resolveServerConfig } from "./config.ts";
+
+const encodeDesktopBootstrap = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap));
+
+const makeDesktopBootstrap = (
+  overrides: Partial<DesktopBackendBootstrapValue> = {},
+): DesktopBackendBootstrapValue => ({
+  mode: "desktop",
+  noBrowser: true,
+  port: 4888,
+  t3Home: "/tmp/t3-bootstrap-home",
+  host: "127.0.0.1",
+  desktopBootstrapToken: "desktop-bootstrap-token",
+  tailscaleServeEnabled: false,
+  tailscaleServePort: 443,
+  ...overrides,
+});
 
 it.layer(NodeServices.layer)("cli config resolution", (it) => {
   const defaultObservabilityConfig = {
@@ -21,10 +47,11 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
     otlpServiceName: "t3-server",
   } as const;
 
-  const openBootstrapFd = Effect.fn(function* (payload: Record<string, unknown>) {
+  const openBootstrapFd = Effect.fn(function* (payload: DesktopBackendBootstrapValue) {
     const fs = yield* FileSystem.FileSystem;
     const filePath = yield* fs.makeTempFileScoped({ prefix: "t3-bootstrap-", suffix: ".ndjson" });
-    yield* fs.writeFileString(filePath, `${JSON.stringify(payload)}\n`);
+    const encoded = yield* encodeDesktopBootstrap(payload);
+    yield* fs.writeFileString(filePath, `${encoded}\n`);
     const { fd } = yield* fs.open(filePath, { flag: "r" });
     return fd;
   });
@@ -32,7 +59,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
   it.effect("falls back to effect/config values when flags are omitted", () =>
     Effect.gen(function* () {
       const { join } = yield* Path.Path;
-      const baseDir = join(os.tmpdir(), "t3-cli-config-env-base");
+      const baseDir = join(NodeOS.tmpdir(), "t3-cli-config-env-base");
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:5173"));
       const resolved = yield* resolveServerConfig(
         {
@@ -46,6 +73,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -87,6 +116,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -94,7 +125,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
   it.effect("uses CLI flags when provided", () =>
     Effect.gen(function* () {
       const { join } = yield* Path.Path;
-      const baseDir = join(os.tmpdir(), "t3-cli-config-flags-base");
+      const baseDir = join(NodeOS.tmpdir(), "t3-cli-config-flags-base");
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:4173"));
       const resolved = yield* resolveServerConfig(
         {
@@ -108,6 +139,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.some(true),
           logWebSocketEvents: Option.some(true),
+          tailscaleServeEnabled: Option.some(true),
+          tailscaleServePort: Option.some(8443),
         },
         Option.some("Debug"),
       ).pipe(
@@ -120,7 +153,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
                   T3CODE_MODE: "desktop",
                   T3CODE_PORT: "4001",
                   T3CODE_HOST: "0.0.0.0",
-                  T3CODE_HOME: join(os.tmpdir(), "ignored-base"),
+                  T3CODE_HOME: join(NodeOS.tmpdir(), "ignored-base"),
                   VITE_DEV_SERVER_URL: "http://127.0.0.1:5173",
                   T3CODE_NO_BROWSER: "false",
                   T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD: "false",
@@ -149,6 +182,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: true,
+        tailscaleServePort: 8443,
       });
     }),
   );
@@ -156,12 +191,14 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
   it.effect("preserves explicit false CLI boolean flags over env and bootstrap values", () =>
     Effect.gen(function* () {
       const { join } = yield* Path.Path;
-      const baseDir = join(os.tmpdir(), "t3-cli-config-false-flags");
-      const fd = yield* openBootstrapFd({
-        noBrowser: true,
-        autoBootstrapProjectFromCwd: true,
-        logWebSocketEvents: true,
-      });
+      const baseDir = join(NodeOS.tmpdir(), "t3-cli-config-false-flags");
+      const fd = yield* openBootstrapFd(
+        makeDesktopBootstrap({
+          noBrowser: true,
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+        }),
+      );
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:4173"));
 
       const resolved = yield* resolveServerConfig(
@@ -176,6 +213,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.some(false),
           logWebSocketEvents: Option.some(false),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -209,9 +248,11 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         devUrl: new URL("http://127.0.0.1:4173"),
         noBrowser: false,
         startupPresentation: "browser",
-        desktopBootstrapToken: undefined,
+        desktopBootstrapToken: "desktop-bootstrap-token",
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -220,19 +261,20 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
     Effect.gen(function* () {
       const { join } = yield* Path.Path;
       const baseDir = "/tmp/t3-bootstrap-home";
-      const fd = yield* openBootstrapFd({
-        mode: "desktop",
-        port: 4888,
-        host: "127.0.0.2",
-        t3Home: baseDir,
-        devUrl: "http://127.0.0.1:5173",
-        noBrowser: true,
-        autoBootstrapProjectFromCwd: false,
-        logWebSocketEvents: true,
-        otlpTracesUrl: "http://localhost:4318/v1/traces",
-        otlpMetricsUrl: "http://localhost:4318/v1/metrics",
-      });
-      const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:5173"));
+      const fd = yield* openBootstrapFd(
+        makeDesktopBootstrap({
+          port: 4888,
+          host: "127.0.0.2",
+          t3Home: baseDir,
+          noBrowser: true,
+          desktopBootstrapToken: "desktop-token",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+          otlpTracesUrl: "http://localhost:4318/v1/traces",
+          otlpMetricsUrl: "http://localhost:4318/v1/metrics",
+        }),
+      );
+      const derivedPaths = yield* deriveServerPaths(baseDir, undefined);
 
       const resolved = yield* resolveServerConfig(
         {
@@ -246,6 +288,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -274,15 +318,17 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         baseDir,
         ...derivedPaths,
         host: "127.0.0.2",
-        staticDir: undefined,
-        devUrl: new URL("http://127.0.0.1:5173"),
+        staticDir: resolved.staticDir,
+        devUrl: undefined,
         noBrowser: true,
         startupPresentation: "browser",
-        desktopBootstrapToken: undefined,
+        desktopBootstrapToken: "desktop-token",
         autoBootstrapProjectFromCwd: false,
-        logWebSocketEvents: true,
+        logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
-      assert.equal(join(baseDir, "dev"), resolved.stateDir);
+      assert.equal(join(baseDir, "userdata"), resolved.stateDir);
     }),
   );
 
@@ -305,6 +351,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -336,17 +384,18 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
   it.effect("applies flag then env precedence over bootstrap envelope values", () =>
     Effect.gen(function* () {
       const { join } = yield* Path.Path;
-      const baseDir = join(os.tmpdir(), "t3-cli-config-env-wins");
-      const fd = yield* openBootstrapFd({
-        mode: "desktop",
-        port: 4888,
-        host: "127.0.0.2",
-        t3Home: "/tmp/t3-bootstrap-home",
-        devUrl: "http://127.0.0.1:5173",
-        noBrowser: false,
-        autoBootstrapProjectFromCwd: false,
-        logWebSocketEvents: false,
-      });
+      const baseDir = join(NodeOS.tmpdir(), "t3-cli-config-env-wins");
+      const fd = yield* openBootstrapFd(
+        makeDesktopBootstrap({
+          port: 4888,
+          host: "127.0.0.2",
+          t3Home: "/tmp/t3-bootstrap-home",
+          noBrowser: false,
+          desktopBootstrapToken: "desktop-token",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+        }),
+      );
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:4173"));
 
       const resolved = yield* resolveServerConfig(
@@ -361,6 +410,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.some("Debug"),
       ).pipe(
@@ -396,9 +447,11 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         devUrl: new URL("http://127.0.0.1:4173"),
         noBrowser: true,
         startupPresentation: "browser",
-        desktopBootstrapToken: undefined,
+        desktopBootstrapToken: "desktop-token",
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -412,6 +465,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
       yield* fs.makeDirectory(path.dirname(derivedPaths.settingsPath), { recursive: true });
       yield* fs.writeFileString(
         derivedPaths.settingsPath,
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         `${JSON.stringify({
           observability: {
             otlpTracesUrl: "http://localhost:4318/v1/traces",
@@ -432,6 +486,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -463,6 +519,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -470,7 +528,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
   it.effect("forces noBrowser and disables auto-bootstrap for headless startup presentation", () =>
     Effect.gen(function* () {
       const { join } = yield* Path.Path;
-      const baseDir = join(os.tmpdir(), "t3-cli-config-headless-base");
+      const baseDir = join(NodeOS.tmpdir(), "t3-cli-config-headless-base");
       const derivedPaths = yield* deriveServerPaths(baseDir, undefined);
 
       const resolved = yield* resolveServerConfig(
@@ -485,6 +543,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
         {
@@ -522,6 +582,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
diff --git a/apps/server/src/cli/config.ts b/apps/server/src/cli/config.ts
new file mode 100644
index 00000000000..7182854e18c
--- /dev/null
+++ b/apps/server/src/cli/config.ts
@@ -0,0 +1,465 @@
+import * as NetService from "@t3tools/shared/Net";
+import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
+import { DesktopBackendBootstrap, PortSchema } from "@t3tools/contracts";
+import * as Config from "effect/Config";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as LogLevel from "effect/LogLevel";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import { Argument, Flag } from "effect/unstable/cli";
+
+import { readBootstrapEnvelope } from "../bootstrap.ts";
+import {
+  DEFAULT_PORT,
+  deriveServerPaths,
+  ensureServerDirectories,
+  resolveStaticDir,
+  RuntimeMode,
+  type ServerConfigShape,
+  type StartupPresentation,
+} from "../config.ts";
+import { expandHomePath, resolveBaseDir } from "../os-jank.ts";
+
+export const modeFlag = Flag.choice("mode", RuntimeMode.literals).pipe(
+  Flag.withDescription("Runtime mode. `desktop` keeps loopback defaults unless overridden."),
+  Flag.optional,
+);
+export const portFlag = Flag.integer("port").pipe(
+  Flag.withSchema(PortSchema),
+  Flag.withDescription("Port for the HTTP/WebSocket server."),
+  Flag.optional,
+);
+export const hostFlag = Flag.string("host").pipe(
+  Flag.withDescription("Host/interface to bind (for example 127.0.0.1, 0.0.0.0, or a Tailnet IP)."),
+  Flag.optional,
+);
+export const baseDirFlag = Flag.string("base-dir").pipe(
+  Flag.withDescription("Base directory path (equivalent to T3CODE_HOME)."),
+  Flag.optional,
+);
+export const devUrlFlag = Flag.string("dev-url").pipe(
+  Flag.withSchema(Schema.URLFromString),
+  Flag.withDescription("Dev web URL to proxy/redirect to (equivalent to VITE_DEV_SERVER_URL)."),
+  Flag.optional,
+);
+export const noBrowserFlag = Flag.boolean("no-browser").pipe(
+  Flag.withDescription("Disable automatic browser opening."),
+  Flag.optional,
+);
+export const bootstrapFdFlag = Flag.integer("bootstrap-fd").pipe(
+  Flag.withSchema(Schema.Int),
+  Flag.withDescription("Read one-time bootstrap secrets from the given file descriptor."),
+  Flag.optional,
+);
+export const autoBootstrapProjectFromCwdFlag = Flag.boolean("auto-bootstrap-project-from-cwd").pipe(
+  Flag.withDescription(
+    "Create a project for the current working directory on startup when missing.",
+  ),
+  Flag.optional,
+);
+export const logWebSocketEventsFlag = Flag.boolean("log-websocket-events").pipe(
+  Flag.withDescription(
+    "Emit server-side logs for outbound WebSocket push traffic (equivalent to T3CODE_LOG_WS_EVENTS).",
+  ),
+  Flag.withAlias("log-ws-events"),
+  Flag.optional,
+);
+export const tailscaleServeFlag = Flag.boolean("tailscale-serve").pipe(
+  Flag.withDescription(
+    "Configure Tailscale Serve to expose this backend over HTTPS on the Tailnet.",
+  ),
+  Flag.optional,
+);
+export const tailscaleServePortFlag = Flag.integer("tailscale-serve-port").pipe(
+  Flag.withSchema(PortSchema),
+  Flag.withDescription("HTTPS port for Tailscale Serve when --tailscale-serve is enabled."),
+  Flag.optional,
+);
+
+const EnvServerConfig = Config.all({
+  logLevel: Config.logLevel("T3CODE_LOG_LEVEL").pipe(Config.withDefault("Info")),
+  traceMinLevel: Config.logLevel("T3CODE_TRACE_MIN_LEVEL").pipe(Config.withDefault("Info")),
+  traceTimingEnabled: Config.boolean("T3CODE_TRACE_TIMING_ENABLED").pipe(Config.withDefault(true)),
+  traceFile: Config.string("T3CODE_TRACE_FILE").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  traceMaxBytes: Config.int("T3CODE_TRACE_MAX_BYTES").pipe(Config.withDefault(10 * 1024 * 1024)),
+  traceMaxFiles: Config.int("T3CODE_TRACE_MAX_FILES").pipe(Config.withDefault(10)),
+  traceBatchWindowMs: Config.int("T3CODE_TRACE_BATCH_WINDOW_MS").pipe(Config.withDefault(200)),
+  otlpTracesUrl: Config.string("T3CODE_OTLP_TRACES_URL").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  otlpMetricsUrl: Config.string("T3CODE_OTLP_METRICS_URL").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  otlpExportIntervalMs: Config.int("T3CODE_OTLP_EXPORT_INTERVAL_MS").pipe(
+    Config.withDefault(10_000),
+  ),
+  otlpServiceName: Config.string("T3CODE_OTLP_SERVICE_NAME").pipe(Config.withDefault("t3-server")),
+  mode: Config.schema(RuntimeMode, "T3CODE_MODE").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  port: Config.port("T3CODE_PORT").pipe(Config.option, Config.map(Option.getOrUndefined)),
+  host: Config.string("T3CODE_HOST").pipe(Config.option, Config.map(Option.getOrUndefined)),
+  t3Home: Config.string("T3CODE_HOME").pipe(Config.option, Config.map(Option.getOrUndefined)),
+  devUrl: Config.url("VITE_DEV_SERVER_URL").pipe(Config.option, Config.map(Option.getOrUndefined)),
+  noBrowser: Config.boolean("T3CODE_NO_BROWSER").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  bootstrapFd: Config.int("T3CODE_BOOTSTRAP_FD").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  autoBootstrapProjectFromCwd: Config.boolean("T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  logWebSocketEvents: Config.boolean("T3CODE_LOG_WS_EVENTS").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  tailscaleServeEnabled: Config.boolean("T3CODE_TAILSCALE_SERVE").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  tailscaleServePort: Config.port("T3CODE_TAILSCALE_SERVE_PORT").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+});
+
+export interface CliServerFlags {
+  readonly mode: Option.Option<RuntimeMode>;
+  readonly port: Option.Option<number>;
+  readonly host: Option.Option<string>;
+  readonly baseDir: Option.Option<string>;
+  readonly cwd: Option.Option<string>;
+  readonly devUrl: Option.Option<URL>;
+  readonly noBrowser: Option.Option<boolean>;
+  readonly bootstrapFd: Option.Option<number>;
+  readonly autoBootstrapProjectFromCwd: Option.Option<boolean>;
+  readonly logWebSocketEvents: Option.Option<boolean>;
+  readonly tailscaleServeEnabled: Option.Option<boolean>;
+  readonly tailscaleServePort: Option.Option<number>;
+}
+
+export interface CliAuthLocationFlags {
+  readonly baseDir: Option.Option<string>;
+  readonly devUrl?: Option.Option<URL>;
+}
+
+export const sharedServerLocationFlags = {
+  baseDir: baseDirFlag,
+  devUrl: devUrlFlag,
+} as const;
+
+export const projectLocationFlags = {
+  baseDir: baseDirFlag,
+} as const;
+
+export const sharedServerCommandFlags = {
+  mode: modeFlag,
+  port: portFlag,
+  host: hostFlag,
+  baseDir: baseDirFlag,
+  cwd: Argument.string("cwd").pipe(
+    Argument.withDescription(
+      "Working directory for provider sessions (defaults to the current directory).",
+    ),
+    Argument.optional,
+  ),
+  devUrl: devUrlFlag,
+  noBrowser: noBrowserFlag,
+  bootstrapFd: bootstrapFdFlag,
+  autoBootstrapProjectFromCwd: autoBootstrapProjectFromCwdFlag,
+  logWebSocketEvents: logWebSocketEventsFlag,
+  tailscaleServeEnabled: tailscaleServeFlag,
+  tailscaleServePort: tailscaleServePortFlag,
+} as const;
+
+export const authLocationFlags = sharedServerLocationFlags;
+
+const resolveOptionPrecedence = <Value>(
+  ...values: ReadonlyArray<Option.Option<Value>>
+): Option.Option<Value> => Option.firstSomeOf(values);
+
+const loadPersistedObservabilitySettings = Effect.fn(function* (settingsPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const exists = yield* fs.exists(settingsPath).pipe(Effect.orElseSucceed(() => false));
+  if (!exists) {
+    return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
+  }
+
+  const raw = yield* fs.readFileString(settingsPath).pipe(Effect.orElseSucceed(() => ""));
+  return parsePersistedServerObservabilitySettings(raw);
+});
+
+export const resolveServerConfig = (
+  flags: CliServerFlags,
+  cliLogLevel: Option.Option<LogLevel.LogLevel>,
+  options?: {
+    readonly startupPresentation?: StartupPresentation;
+    readonly forceAutoBootstrapProjectFromCwd?: boolean;
+  },
+) =>
+  Effect.gen(function* () {
+    const { findAvailablePort } = yield* NetService.NetService;
+    const path = yield* Path.Path;
+    const fs = yield* FileSystem.FileSystem;
+    const env = yield* EnvServerConfig;
+    const normalizedFlags = {
+      mode: flags.mode ?? Option.none(),
+      port: flags.port ?? Option.none(),
+      host: flags.host ?? Option.none(),
+      baseDir: flags.baseDir ?? Option.none(),
+      cwd: flags.cwd ?? Option.none(),
+      devUrl: flags.devUrl ?? Option.none(),
+      noBrowser: flags.noBrowser ?? Option.none(),
+      bootstrapFd: flags.bootstrapFd ?? Option.none(),
+      autoBootstrapProjectFromCwd: flags.autoBootstrapProjectFromCwd ?? Option.none(),
+      logWebSocketEvents: flags.logWebSocketEvents ?? Option.none(),
+      tailscaleServeEnabled: flags.tailscaleServeEnabled ?? Option.none(),
+      tailscaleServePort: flags.tailscaleServePort ?? Option.none(),
+    } satisfies CliServerFlags;
+    const bootstrapFd = Option.getOrUndefined(normalizedFlags.bootstrapFd) ?? env.bootstrapFd;
+    const bootstrapEnvelope =
+      bootstrapFd !== undefined
+        ? yield* readBootstrapEnvelope(DesktopBackendBootstrap, bootstrapFd)
+        : Option.none();
+    const bootstrap = Option.getOrUndefined(bootstrapEnvelope);
+
+    const mode: RuntimeMode = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.mode,
+        Option.fromUndefinedOr(env.mode),
+        Option.fromUndefinedOr(bootstrap?.mode),
+      ),
+      () => "web",
+    );
+
+    const port = yield* Option.match(
+      resolveOptionPrecedence(
+        normalizedFlags.port,
+        Option.fromUndefinedOr(env.port),
+        Option.fromUndefinedOr(bootstrap?.port),
+      ),
+      {
+        onSome: (value) => Effect.succeed(value),
+        onNone: () => {
+          if (mode === "desktop") {
+            return Effect.succeed(DEFAULT_PORT);
+          }
+          return findAvailablePort(DEFAULT_PORT);
+        },
+      },
+    );
+    const devUrl = Option.getOrElse(
+      resolveOptionPrecedence(normalizedFlags.devUrl, Option.fromUndefinedOr(env.devUrl)),
+      () => undefined,
+    );
+    const baseDir = yield* resolveBaseDir(
+      Option.getOrUndefined(
+        resolveOptionPrecedence(
+          normalizedFlags.baseDir,
+          Option.fromUndefinedOr(env.t3Home),
+          Option.fromUndefinedOr(bootstrap?.t3Home),
+        ),
+      ),
+    );
+    const rawCwd = Option.getOrElse(normalizedFlags.cwd, () => process.cwd());
+    const cwd = path.resolve(yield* expandHomePath(rawCwd.trim()));
+    yield* fs.makeDirectory(cwd, { recursive: true });
+    const derivedPaths = yield* deriveServerPaths(baseDir, devUrl);
+    yield* ensureServerDirectories(derivedPaths);
+    const persistedObservabilitySettings = yield* loadPersistedObservabilitySettings(
+      derivedPaths.settingsPath,
+    );
+    const serverTracePath = env.traceFile ?? derivedPaths.serverTracePath;
+    yield* fs.makeDirectory(path.dirname(serverTracePath), { recursive: true });
+    const startupPresentation = options?.startupPresentation ?? "browser";
+    const isHeadlessStartup = startupPresentation === "headless";
+    const noBrowser = Option.getOrElse(
+      resolveOptionPrecedence(
+        isHeadlessStartup ? Option.some(true) : Option.none(),
+        normalizedFlags.noBrowser,
+        Option.fromUndefinedOr(env.noBrowser),
+        Option.fromUndefinedOr(bootstrap?.noBrowser),
+      ),
+      () => mode === "desktop",
+    );
+    const desktopBootstrapToken = bootstrap?.desktopBootstrapToken;
+    const autoBootstrapProjectFromCwd = Option.getOrElse(
+      resolveOptionPrecedence(
+        Option.fromUndefinedOr(options?.forceAutoBootstrapProjectFromCwd),
+        isHeadlessStartup ? Option.some(false) : Option.none(),
+        normalizedFlags.autoBootstrapProjectFromCwd,
+        Option.fromUndefinedOr(env.autoBootstrapProjectFromCwd),
+      ),
+      () => mode === "web",
+    );
+    const logWebSocketEvents = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.logWebSocketEvents,
+        Option.fromUndefinedOr(env.logWebSocketEvents),
+      ),
+      () => Boolean(devUrl),
+    );
+    const tailscaleServeEnabled = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.tailscaleServeEnabled,
+        Option.fromUndefinedOr(env.tailscaleServeEnabled),
+        Option.fromUndefinedOr(bootstrap?.tailscaleServeEnabled),
+      ),
+      () => false,
+    );
+    const tailscaleServePort = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.tailscaleServePort,
+        Option.fromUndefinedOr(env.tailscaleServePort),
+        Option.fromUndefinedOr(bootstrap?.tailscaleServePort),
+      ),
+      () => 443,
+    );
+    const staticDir = devUrl ? undefined : yield* resolveStaticDir();
+    const host = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.host,
+        Option.fromUndefinedOr(env.host),
+        Option.fromUndefinedOr(bootstrap?.host),
+      ),
+      () => (mode === "desktop" ? "127.0.0.1" : undefined),
+    );
+    const logLevel = Option.getOrElse(cliLogLevel, () => env.logLevel);
+
+    const config: ServerConfigShape = {
+      logLevel,
+      traceMinLevel: env.traceMinLevel,
+      traceTimingEnabled: env.traceTimingEnabled,
+      traceBatchWindowMs: env.traceBatchWindowMs,
+      traceMaxBytes: env.traceMaxBytes,
+      traceMaxFiles: env.traceMaxFiles,
+      otlpTracesUrl:
+        env.otlpTracesUrl ??
+        bootstrap?.otlpTracesUrl ??
+        persistedObservabilitySettings.otlpTracesUrl,
+      otlpMetricsUrl:
+        env.otlpMetricsUrl ??
+        bootstrap?.otlpMetricsUrl ??
+        persistedObservabilitySettings.otlpMetricsUrl,
+      otlpExportIntervalMs: env.otlpExportIntervalMs,
+      otlpServiceName: env.otlpServiceName,
+      mode,
+      port,
+      cwd,
+      baseDir,
+      ...derivedPaths,
+      serverTracePath,
+      host,
+      staticDir,
+      devUrl,
+      noBrowser,
+      startupPresentation,
+      desktopBootstrapToken,
+      autoBootstrapProjectFromCwd,
+      logWebSocketEvents,
+      tailscaleServeEnabled,
+      tailscaleServePort,
+    };
+
+    return config;
+  });
+
+export const resolveCliAuthConfig = (
+  flags: CliAuthLocationFlags,
+  cliLogLevel: Option.Option<LogLevel.LogLevel>,
+) =>
+  resolveServerConfig(
+    {
+      mode: Option.none(),
+      port: Option.none(),
+      host: Option.none(),
+      baseDir: flags.baseDir,
+      cwd: Option.none(),
+      devUrl: flags.devUrl ?? Option.none(),
+      noBrowser: Option.none(),
+      bootstrapFd: Option.none(),
+      autoBootstrapProjectFromCwd: Option.none(),
+      logWebSocketEvents: Option.none(),
+      tailscaleServeEnabled: Option.none(),
+      tailscaleServePort: Option.none(),
+    },
+    cliLogLevel,
+  );
+
+const DurationShorthandPattern = /^(?<value>\d+)(?<unit>ms|s|m|h|d|w)$/i;
+
+const parseDurationInput = (value: string): Duration.Duration | null => {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return null;
+
+  const shorthand = DurationShorthandPattern.exec(trimmed);
+  const normalizedInput = shorthand?.groups
+    ? (() => {
+        const amountText = shorthand.groups.value;
+        const unitText = shorthand.groups.unit;
+        if (typeof amountText !== "string" || typeof unitText !== "string") {
+          return null;
+        }
+
+        const amount = Number.parseInt(amountText, 10);
+        if (!Number.isFinite(amount)) return null;
+
+        switch (unitText.toLowerCase()) {
+          case "ms":
+            return `${amount} millis`;
+          case "s":
+            return `${amount} seconds`;
+          case "m":
+            return `${amount} minutes`;
+          case "h":
+            return `${amount} hours`;
+          case "d":
+            return `${amount} days`;
+          case "w":
+            return `${amount} weeks`;
+          default:
+            return null;
+        }
+      })()
+    : (trimmed as Duration.Input);
+
+  if (normalizedInput === null) return null;
+
+  const decoded = Duration.fromInput(normalizedInput as Duration.Input);
+  return Option.isSome(decoded) ? decoded.value : null;
+};
+
+export const DurationFromString = Schema.String.pipe(
+  Schema.decodeTo(
+    Schema.Duration,
+    SchemaTransformation.transformOrFail({
+      decode: (value) => {
+        const duration = parseDurationInput(value);
+        if (duration !== null) {
+          return Effect.succeed(duration);
+        }
+        return Effect.fail(
+          new SchemaIssue.InvalidValue(Option.some(value), {
+            message: "Invalid duration. Use values like 5m, 1h, 30d, or 15 minutes.",
+          }),
+        );
+      },
+      encode: (duration) => Effect.succeed(Duration.format(duration)),
+    }),
+  ),
+);
diff --git a/apps/server/src/cli/project.ts b/apps/server/src/cli/project.ts
new file mode 100644
index 00000000000..39772fcd061
--- /dev/null
+++ b/apps/server/src/cli/project.ts
@@ -0,0 +1,440 @@
+import {
+  CommandId,
+  OrchestrationReadModel,
+  ProjectId,
+  type ClientOrchestrationCommand,
+} from "@t3tools/contracts";
+import * as Console from "effect/Console";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as References from "effect/References";
+import * as Schema from "effect/Schema";
+import { Argument, Command, Flag, GlobalFlag } from "effect/unstable/cli";
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/unstable/http";
+
+import { AuthControlPlaneRuntimeLive } from "../auth/Layers/AuthControlPlane.ts";
+import { AuthControlPlane } from "../auth/Services/AuthControlPlane.ts";
+import type { AuthControlPlaneShape } from "../auth/Services/AuthControlPlane.ts";
+import { ServerConfig, type ServerConfigShape } from "../config.ts";
+import { OrchestrationEngineService } from "../orchestration/Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "../orchestration/Services/ProjectionSnapshotQuery.ts";
+import { OrchestrationLayerLive } from "../orchestration/runtimeLayer.ts";
+import { layerConfig as SqlitePersistenceLayerLive } from "../persistence/Layers/Sqlite.ts";
+import { RepositoryIdentityResolverLive } from "../project/Layers/RepositoryIdentityResolver.ts";
+import { getAutoBootstrapDefaultModelSelection } from "../serverRuntimeStartup.ts";
+import {
+  clearPersistedServerRuntimeState,
+  readPersistedServerRuntimeState,
+} from "../serverRuntimeState.ts";
+import { WorkspacePathsLive } from "../workspace/Layers/WorkspacePaths.ts";
+import { WorkspacePaths } from "../workspace/Services/WorkspacePaths.ts";
+import { type CliAuthLocationFlags, projectLocationFlags, resolveCliAuthConfig } from "./config.ts";
+
+type ProjectMutationTarget = {
+  readonly id: ProjectId;
+  readonly title: string;
+  readonly workspaceRoot: string;
+};
+
+type ProjectCommandExecutionMode = "live" | "offline";
+type ProjectCliDispatchCommand = Extract<
+  ClientOrchestrationCommand,
+  { type: "project.create" | "project.meta.update" | "project.delete" }
+>;
+
+class ProjectCommandError extends Data.TaggedError("ProjectCommandError")<{
+  readonly message: string;
+}> {}
+
+const ProjectCliRuntimeLive = Layer.mergeAll(
+  WorkspacePathsLive,
+  OrchestrationLayerLive.pipe(
+    Layer.provideMerge(RepositoryIdentityResolverLive),
+    Layer.provideMerge(SqlitePersistenceLayerLive),
+  ),
+);
+
+const PROJECT_CLI_LIVE_SERVER_TIMEOUT = Duration.seconds(1);
+const OrchestrationHttpErrorResponse = Schema.Struct({
+  error: Schema.String,
+});
+
+const withProjectCliSessionToken = <A, E, R>(
+  authControlPlane: AuthControlPlaneShape,
+  run: (token: string) => Effect.Effect<A, E, R>,
+) =>
+  Effect.acquireUseRelease(
+    authControlPlane.issueSession({
+      role: "owner",
+      label: "t3 project cli",
+    }),
+    (issued) => run(issued.token),
+    (issued) => authControlPlane.revokeSession(issued.sessionId).pipe(Effect.ignore({ log: true })),
+  );
+
+const withProjectCliLiveServerTimeout = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(Effect.timeout(PROJECT_CLI_LIVE_SERVER_TIMEOUT));
+
+const runLiveServerRequest = <A, E extends Error, R>(
+  request: HttpClientRequest.HttpClientRequest,
+  handle: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<A, E, R>,
+) =>
+  Effect.gen(function* () {
+    const httpClient = yield* HttpClient.HttpClient;
+    const response = yield* httpClient.execute(request);
+    return yield* handle(response);
+  }).pipe(withProjectCliLiveServerTimeout);
+
+const decodeOrchestrationReadModelResponse = (response: HttpClientResponse.HttpClientResponse) =>
+  HttpClientResponse.schemaBodyJson(OrchestrationReadModel)(response);
+
+const readErrorMessageFromResponse = (response: HttpClientResponse.HttpClientResponse) =>
+  HttpClientResponse.schemaBodyJson(OrchestrationHttpErrorResponse)(response).pipe(
+    Effect.map((body) => body.error),
+    Effect.catch(() => Effect.succeed(null)),
+    Effect.map((body) => {
+      if (typeof body === "string" && body.trim().length > 0) {
+        return body;
+      }
+      return `Server request failed with status ${response.status}.`;
+    }),
+  );
+
+const normalizeWorkspaceRootForProjectCommand = Effect.fn(
+  "normalizeWorkspaceRootForProjectCommand",
+)(function* (workspaceRoot: string) {
+  const workspacePaths = yield* WorkspacePaths;
+  return yield* workspacePaths.normalizeWorkspaceRoot(workspaceRoot);
+});
+
+const resolveProjectTitle = Effect.fn("resolveProjectTitle")(function* (
+  workspaceRoot: string,
+  explicitTitle?: string,
+) {
+  if (explicitTitle !== undefined) {
+    const trimmed = explicitTitle.trim();
+    if (trimmed.length > 0) {
+      return trimmed;
+    }
+    return yield* new ProjectCommandError({ message: "Project title cannot be empty." });
+  }
+
+  const path = yield* Path.Path;
+  const basename = path.basename(workspaceRoot).trim();
+  return basename.length > 0 ? basename : "project";
+});
+
+const findActiveProjectTarget = Effect.fn("findActiveProjectTarget")(function* (input: {
+  readonly snapshot: OrchestrationReadModel;
+  readonly identifier: string;
+}) {
+  const trimmedIdentifier = input.identifier.trim();
+  if (trimmedIdentifier.length === 0) {
+    return yield* new ProjectCommandError({ message: "Project identifier cannot be empty." });
+  }
+
+  const activeProjects = input.snapshot.projects.filter((project) => project.deletedAt === null);
+  const exactIdMatch = activeProjects.find((project) => project.id === trimmedIdentifier);
+  if (exactIdMatch) {
+    return {
+      id: exactIdMatch.id,
+      title: exactIdMatch.title,
+      workspaceRoot: exactIdMatch.workspaceRoot,
+    } satisfies ProjectMutationTarget;
+  }
+
+  const normalizedWorkspaceRootResult = yield* Effect.exit(
+    normalizeWorkspaceRootForProjectCommand(trimmedIdentifier),
+  );
+  const normalizedWorkspaceRoot = Exit.isSuccess(normalizedWorkspaceRootResult)
+    ? normalizedWorkspaceRootResult.value
+    : null;
+
+  const exactWorkspaceMatch =
+    normalizedWorkspaceRoot === null
+      ? undefined
+      : activeProjects.find((project) => project.workspaceRoot === normalizedWorkspaceRoot);
+
+  const resolved = exactWorkspaceMatch;
+  if (!resolved) {
+    return yield* new ProjectCommandError({
+      message: `No active project found for '${trimmedIdentifier}'.`,
+    });
+  }
+
+  return {
+    id: resolved.id,
+    title: resolved.title,
+    workspaceRoot: resolved.workspaceRoot,
+  } satisfies ProjectMutationTarget;
+});
+
+const fetchLiveOrchestrationSnapshot = (origin: string, bearerToken: string) =>
+  runLiveServerRequest(
+    HttpClientRequest.get(`${origin}/api/orchestration/snapshot`).pipe(
+      HttpClientRequest.acceptJson,
+      HttpClientRequest.bearerToken(bearerToken),
+    ),
+    HttpClientResponse.matchStatus({
+      "2xx": decodeOrchestrationReadModelResponse,
+      orElse: (response) =>
+        readErrorMessageFromResponse(response).pipe(
+          Effect.flatMap((message) => Effect.fail(new ProjectCommandError({ message }))),
+        ),
+    }),
+  );
+
+const dispatchLiveOrchestrationCommand = (
+  origin: string,
+  bearerToken: string,
+  command: ProjectCliDispatchCommand,
+) =>
+  HttpClientRequest.post(`${origin}/api/orchestration/dispatch`).pipe(
+    HttpClientRequest.acceptJson,
+    HttpClientRequest.bearerToken(bearerToken),
+    HttpClientRequest.bodyJson(command),
+    Effect.flatMap((request) =>
+      runLiveServerRequest(
+        request,
+        HttpClientResponse.matchStatus({
+          "2xx": () => Effect.void,
+          orElse: (response) =>
+            readErrorMessageFromResponse(response).pipe(
+              Effect.flatMap((message) => Effect.fail(new ProjectCommandError({ message }))),
+            ),
+        }),
+      ),
+    ),
+  );
+
+const getOfflineSnapshot = Effect.fn("getOfflineSnapshot")(function* () {
+  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
+  return yield* projectionSnapshotQuery.getSnapshot();
+});
+
+const tryResolveLiveProjectExecutionMode = Effect.fn("tryResolveLiveProjectExecutionMode")(
+  function* (authControlPlane: AuthControlPlaneShape, config: ServerConfigShape) {
+    const runtimeState = yield* readPersistedServerRuntimeState(config.serverRuntimeStatePath);
+    if (Option.isNone(runtimeState)) {
+      return Option.none<{ readonly origin: string }>();
+    }
+
+    const attempt = withProjectCliSessionToken(authControlPlane, (token) =>
+      fetchLiveOrchestrationSnapshot(runtimeState.value.origin, token).pipe(
+        Effect.as({
+          origin: runtimeState.value.origin,
+        }),
+      ),
+    );
+
+    const attempted = yield* Effect.exit(attempt);
+    if (Exit.isSuccess(attempted)) {
+      return Option.some(attempted.value);
+    }
+
+    yield* clearPersistedServerRuntimeState(config.serverRuntimeStatePath);
+    return Option.none<{ readonly origin: string }>();
+  },
+);
+
+const runProjectMutation = Effect.fn("runProjectMutation")(function* (
+  flags: CliAuthLocationFlags,
+  run: (input: {
+    readonly snapshot: OrchestrationReadModel;
+    readonly dispatch: (
+      command: ProjectCliDispatchCommand,
+    ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
+    readonly mode: ProjectCommandExecutionMode;
+  }) => Effect.Effect<
+    string,
+    Error,
+    FileSystem.FileSystem | HttpClient.HttpClient | Path.Path | WorkspacePaths
+  >,
+) {
+  const logLevel = yield* GlobalFlag.LogLevel;
+  const config = yield* resolveCliAuthConfig(flags, logLevel);
+  const minimumLogLevel = config.logLevel;
+
+  return yield* Effect.gen(function* () {
+    const authControlPlane = yield* AuthControlPlane;
+    const liveMode = yield* tryResolveLiveProjectExecutionMode(authControlPlane, config);
+
+    if (Option.isSome(liveMode)) {
+      return yield* withProjectCliSessionToken(authControlPlane, (token) =>
+        Effect.gen(function* () {
+          const snapshot = yield* fetchLiveOrchestrationSnapshot(liveMode.value.origin, token);
+          const output = yield* run({
+            snapshot,
+            dispatch: (command) =>
+              dispatchLiveOrchestrationCommand(liveMode.value.origin, token, command),
+            mode: "live",
+          });
+          yield* Console.log(output);
+        }),
+      );
+    }
+
+    const offlineRuntimeLayer = ProjectCliRuntimeLive.pipe(
+      Layer.provide(Layer.succeed(ServerConfig, config)),
+      Layer.provide(Layer.succeed(References.MinimumLogLevel, minimumLogLevel)),
+    );
+
+    return yield* Effect.gen(function* () {
+      const snapshot = yield* getOfflineSnapshot();
+      const orchestrationEngine = yield* OrchestrationEngineService;
+      const output = yield* run({
+        snapshot,
+        dispatch: (command) => orchestrationEngine.dispatch(command),
+        mode: "offline",
+      });
+      yield* Console.log(output);
+    }).pipe(Effect.provide(offlineRuntimeLayer));
+  }).pipe(
+    Effect.provide(
+      Layer.mergeAll(AuthControlPlaneRuntimeLive, WorkspacePathsLive).pipe(
+        Layer.provideMerge(FetchHttpClient.layer),
+        Layer.provide(Layer.succeed(ServerConfig, config)),
+        Layer.provide(Layer.succeed(References.MinimumLogLevel, minimumLogLevel)),
+      ),
+    ),
+  );
+});
+
+const projectAddCommand = Command.make("add", {
+  ...projectLocationFlags,
+  workspaceRoot: Argument.string("path").pipe(
+    Argument.withDescription("Workspace root to add as a project."),
+  ),
+  title: Flag.string("title").pipe(Flag.withDescription("Optional project title."), Flag.optional),
+}).pipe(
+  Command.withDescription("Add a project."),
+  Command.withHandler((flags) =>
+    runProjectMutation(
+      flags,
+      Effect.fn("projectAddMutation")(function* ({
+        snapshot,
+        dispatch,
+      }: {
+        readonly snapshot: OrchestrationReadModel;
+        readonly dispatch: (
+          command: ProjectCliDispatchCommand,
+        ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
+      }) {
+        const workspaceRoot = yield* normalizeWorkspaceRootForProjectCommand(flags.workspaceRoot);
+        const existingProject = snapshot.projects.find(
+          (project) => project.deletedAt === null && project.workspaceRoot === workspaceRoot,
+        );
+        if (existingProject) {
+          return yield* new ProjectCommandError({
+            message: `An active project already exists for '${workspaceRoot}'.`,
+          });
+        }
+
+        const title = yield* resolveProjectTitle(workspaceRoot, Option.getOrUndefined(flags.title));
+        const projectId = ProjectId.make(crypto.randomUUID());
+        yield* dispatch({
+          type: "project.create",
+          commandId: CommandId.make(crypto.randomUUID()),
+          projectId,
+          title,
+          workspaceRoot,
+          defaultModelSelection: getAutoBootstrapDefaultModelSelection(),
+          createdAt: DateTime.formatIso(yield* DateTime.now),
+        });
+        return `Added project ${projectId} (${title}) at ${workspaceRoot}.`;
+      }),
+    ),
+  ),
+);
+
+const projectRemoveCommand = Command.make("remove", {
+  ...projectLocationFlags,
+  project: Argument.string("project").pipe(
+    Argument.withDescription("Project id or workspace root to remove."),
+  ),
+}).pipe(
+  Command.withDescription("Remove a project."),
+  Command.withHandler((flags) =>
+    runProjectMutation(
+      flags,
+      Effect.fn("projectRemoveMutation")(function* ({
+        snapshot,
+        dispatch,
+      }: {
+        readonly snapshot: OrchestrationReadModel;
+        readonly dispatch: (
+          command: ProjectCliDispatchCommand,
+        ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
+      }) {
+        const project = yield* findActiveProjectTarget({
+          snapshot,
+          identifier: flags.project,
+        });
+        yield* dispatch({
+          type: "project.delete",
+          commandId: CommandId.make(crypto.randomUUID()),
+          projectId: project.id,
+        });
+        return `Removed project ${project.id} (${project.title}).`;
+      }),
+    ),
+  ),
+);
+
+const projectRenameCommand = Command.make("rename", {
+  ...projectLocationFlags,
+  project: Argument.string("project").pipe(
+    Argument.withDescription("Project id or workspace root to rename."),
+  ),
+  title: Argument.string("title").pipe(Argument.withDescription("New project title.")),
+}).pipe(
+  Command.withDescription("Rename a project."),
+  Command.withHandler((flags) =>
+    runProjectMutation(
+      flags,
+      Effect.fn("projectRenameMutation")(function* ({
+        snapshot,
+        dispatch,
+      }: {
+        readonly snapshot: OrchestrationReadModel;
+        readonly dispatch: (
+          command: ProjectCliDispatchCommand,
+        ) => Effect.Effect<void, Error, FileSystem.FileSystem | HttpClient.HttpClient | Path.Path>;
+      }) {
+        const project = yield* findActiveProjectTarget({
+          snapshot,
+          identifier: flags.project,
+        });
+        const nextTitle = yield* resolveProjectTitle(project.workspaceRoot, flags.title);
+        if (nextTitle === project.title) {
+          return `Project ${project.id} is already named ${nextTitle}.`;
+        }
+
+        yield* dispatch({
+          type: "project.meta.update",
+          commandId: CommandId.make(crypto.randomUUID()),
+          projectId: project.id,
+          title: nextTitle,
+        });
+        return `Renamed project ${project.id} to ${nextTitle}.`;
+      }),
+    ),
+  ),
+);
+
+export const projectCommand = Command.make("project").pipe(
+  Command.withDescription("Manage projects."),
+  Command.withSubcommands([projectAddCommand, projectRemoveCommand, projectRenameCommand]),
+);
diff --git a/apps/server/src/cli/server.ts b/apps/server/src/cli/server.ts
new file mode 100644
index 00000000000..bc4b3f45706
--- /dev/null
+++ b/apps/server/src/cli/server.ts
@@ -0,0 +1,36 @@
+import * as Effect from "effect/Effect";
+import { Command, GlobalFlag } from "effect/unstable/cli";
+
+import { ServerConfig, type StartupPresentation } from "../config.ts";
+import { runServer } from "../server.ts";
+import { type CliServerFlags, resolveServerConfig, sharedServerCommandFlags } from "./config.ts";
+
+export const runServerCommand = (
+  flags: CliServerFlags,
+  options?: {
+    readonly startupPresentation?: StartupPresentation;
+    readonly forceAutoBootstrapProjectFromCwd?: boolean;
+  },
+) =>
+  Effect.gen(function* () {
+    const logLevel = yield* GlobalFlag.LogLevel;
+    const config = yield* resolveServerConfig(flags, logLevel, options);
+    return yield* runServer.pipe(Effect.provideService(ServerConfig, config));
+  });
+
+export const startCommand = Command.make("start", { ...sharedServerCommandFlags }).pipe(
+  Command.withDescription("Run the T3 Code server."),
+  Command.withHandler((flags) => runServerCommand(flags)),
+);
+
+export const serveCommand = Command.make("serve", { ...sharedServerCommandFlags }).pipe(
+  Command.withDescription(
+    "Run the T3 Code server without opening a browser and print headless pairing details.",
+  ),
+  Command.withHandler((flags) =>
+    runServerCommand(flags, {
+      startupPresentation: "headless",
+      forceAutoBootstrapProjectFromCwd: false,
+    }),
+  ),
+);
diff --git a/apps/server/src/cliAuthFormat.test.ts b/apps/server/src/cliAuthFormat.test.ts
index 017ced97e83..3ffaf6fba74 100644
--- a/apps/server/src/cliAuthFormat.test.ts
+++ b/apps/server/src/cliAuthFormat.test.ts
@@ -1,5 +1,5 @@
 import { expect, it } from "@effect/vitest";
-import { DateTime } from "effect";
+import * as DateTime from "effect/DateTime";
 
 import {
   formatIssuedPairingCredential,
@@ -15,8 +15,8 @@ it("formats issued pairing credentials with the secret and optional pair URL", (
       credential: "secret-pairing-token",
       role: "client",
       subject: "one-time-token",
-      createdAt: DateTime.fromDateUnsafe(new Date("2026-04-08T09:00:00.000Z")),
-      expiresAt: DateTime.fromDateUnsafe(new Date("2026-04-08T10:00:00.000Z")),
+      createdAt: DateTime.makeUnsafe("2026-04-08T09:00:00.000Z"),
+      expiresAt: DateTime.makeUnsafe("2026-04-08T10:00:00.000Z"),
     },
     { baseUrl: "https://example.com", json: false },
   );
@@ -34,8 +34,8 @@ it("formats pairing listings without exposing the secret token", () => {
         subject: "one-time-token",
         label: "Phone",
         role: "client",
-        createdAt: DateTime.fromDateUnsafe(new Date("2026-04-08T09:00:00.000Z")),
-        expiresAt: DateTime.fromDateUnsafe(new Date("2026-04-08T10:00:00.000Z")),
+        createdAt: DateTime.makeUnsafe("2026-04-08T09:00:00.000Z"),
+        expiresAt: DateTime.makeUnsafe("2026-04-08T10:00:00.000Z"),
       },
     ],
     { json: false },
@@ -57,7 +57,7 @@ it("formats issued sessions with the bearer token but omits tokens from listings
         label: "deploy-bot",
         deviceType: "bot",
       },
-      expiresAt: DateTime.fromDateUnsafe(new Date("2026-04-08T10:00:00.000Z")),
+      expiresAt: DateTime.makeUnsafe("2026-04-08T10:00:00.000Z"),
     },
     { json: false },
   );
@@ -75,8 +75,8 @@ it("formats issued sessions with the bearer token but omits tokens from listings
         },
         connected: false,
         current: false,
-        issuedAt: DateTime.fromDateUnsafe(new Date("2026-04-08T09:00:00.000Z")),
-        expiresAt: DateTime.fromDateUnsafe(new Date("2026-04-08T10:00:00.000Z")),
+        issuedAt: DateTime.makeUnsafe("2026-04-08T09:00:00.000Z"),
+        expiresAt: DateTime.makeUnsafe("2026-04-08T10:00:00.000Z"),
         lastConnectedAt: null,
       },
     ],
diff --git a/apps/server/src/cliAuthFormat.ts b/apps/server/src/cliAuthFormat.ts
index 44356c5a8a9..4078860ff94 100644
--- a/apps/server/src/cliAuthFormat.ts
+++ b/apps/server/src/cliAuthFormat.ts
@@ -1,5 +1,5 @@
 import type { AuthClientMetadata, AuthClientSession, AuthPairingLink } from "@t3tools/contracts";
-import { DateTime } from "effect";
+import * as DateTime from "effect/DateTime";
 
 import type { IssuedBearerSession, IssuedPairingLink } from "./auth/Services/AuthControlPlane.ts";
 
diff --git a/apps/server/src/codexAppServerManager.test.ts b/apps/server/src/codexAppServerManager.test.ts
deleted file mode 100644
index ab3b7a569de..00000000000
--- a/apps/server/src/codexAppServerManager.test.ts
+++ /dev/null
@@ -1,1070 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { randomUUID } from "node:crypto";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { ApprovalRequestId, ThreadId } from "@t3tools/contracts";
-
-import {
-  buildCodexInitializeParams,
-  CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
-  CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
-  CodexAppServerManager,
-  classifyCodexStderrLine,
-  isRecoverableThreadResumeError,
-  normalizeCodexModelSlug,
-  readCodexAccountSnapshot,
-  resolveCodexModelForAccount,
-} from "./codexAppServerManager";
-
-const asThreadId = (value: string): ThreadId => ThreadId.make(value);
-
-function createSendTurnHarness() {
-  const manager = new CodexAppServerManager();
-  const context = {
-    session: {
-      provider: "codex",
-      status: "ready",
-      threadId: "thread_1",
-      runtimeMode: "full-access",
-      model: "gpt-5.3-codex",
-      resumeCursor: { threadId: "thread_1" },
-      createdAt: "2026-02-10T00:00:00.000Z",
-      updatedAt: "2026-02-10T00:00:00.000Z",
-    },
-    account: {
-      type: "unknown",
-      planType: null,
-      sparkEnabled: true,
-    },
-    collabReceiverTurns: new Map(),
-  };
-
-  const requireSession = vi
-    .spyOn(
-      manager as unknown as { requireSession: (sessionId: string) => unknown },
-      "requireSession",
-    )
-    .mockReturnValue(context);
-  const sendRequest = vi
-    .spyOn(
-      manager as unknown as { sendRequest: (...args: unknown[]) => Promise<unknown> },
-      "sendRequest",
-    )
-    .mockResolvedValue({
-      turn: {
-        id: "turn_1",
-      },
-    });
-  const updateSession = vi
-    .spyOn(manager as unknown as { updateSession: (...args: unknown[]) => void }, "updateSession")
-    .mockImplementation(() => {});
-
-  return { manager, context, requireSession, sendRequest, updateSession };
-}
-
-function createThreadControlHarness() {
-  const manager = new CodexAppServerManager();
-  const context = {
-    session: {
-      provider: "codex",
-      status: "ready",
-      threadId: "thread_1",
-      runtimeMode: "full-access",
-      model: "gpt-5.3-codex",
-      resumeCursor: { threadId: "thread_1" },
-      createdAt: "2026-02-10T00:00:00.000Z",
-      updatedAt: "2026-02-10T00:00:00.000Z",
-    },
-    collabReceiverTurns: new Map(),
-  };
-
-  const requireSession = vi
-    .spyOn(
-      manager as unknown as { requireSession: (sessionId: string) => unknown },
-      "requireSession",
-    )
-    .mockReturnValue(context);
-  const sendRequest = vi.spyOn(
-    manager as unknown as { sendRequest: (...args: unknown[]) => Promise<unknown> },
-    "sendRequest",
-  );
-  const updateSession = vi
-    .spyOn(manager as unknown as { updateSession: (...args: unknown[]) => void }, "updateSession")
-    .mockImplementation(() => {});
-
-  return { manager, context, requireSession, sendRequest, updateSession };
-}
-
-function createPendingUserInputHarness() {
-  const manager = new CodexAppServerManager();
-  const context = {
-    session: {
-      provider: "codex",
-      status: "ready",
-      threadId: "thread_1",
-      runtimeMode: "full-access",
-      model: "gpt-5.3-codex",
-      resumeCursor: { threadId: "thread_1" },
-      createdAt: "2026-02-10T00:00:00.000Z",
-      updatedAt: "2026-02-10T00:00:00.000Z",
-    },
-    pendingUserInputs: new Map([
-      [
-        ApprovalRequestId.make("req-user-input-1"),
-        {
-          requestId: ApprovalRequestId.make("req-user-input-1"),
-          jsonRpcId: 42,
-          threadId: asThreadId("thread_1"),
-        },
-      ],
-    ]),
-    collabReceiverTurns: new Map(),
-  };
-
-  const requireSession = vi
-    .spyOn(
-      manager as unknown as { requireSession: (sessionId: string) => unknown },
-      "requireSession",
-    )
-    .mockReturnValue(context);
-  const writeMessage = vi
-    .spyOn(manager as unknown as { writeMessage: (...args: unknown[]) => void }, "writeMessage")
-    .mockImplementation(() => {});
-  const emitEvent = vi
-    .spyOn(manager as unknown as { emitEvent: (...args: unknown[]) => void }, "emitEvent")
-    .mockImplementation(() => {});
-
-  return { manager, context, requireSession, writeMessage, emitEvent };
-}
-
-function createCollabNotificationHarness() {
-  const manager = new CodexAppServerManager();
-  const context = {
-    session: {
-      provider: "codex",
-      status: "running",
-      threadId: asThreadId("thread_1"),
-      runtimeMode: "full-access",
-      model: "gpt-5.3-codex",
-      activeTurnId: "turn_parent",
-      resumeCursor: { threadId: "provider_parent" },
-      createdAt: "2026-02-10T00:00:00.000Z",
-      updatedAt: "2026-02-10T00:00:00.000Z",
-    },
-    account: {
-      type: "unknown",
-      planType: null,
-      sparkEnabled: true,
-    },
-    pending: new Map(),
-    pendingApprovals: new Map(),
-    pendingUserInputs: new Map(),
-    collabReceiverTurns: new Map<string, string>(),
-    nextRequestId: 1,
-    stopping: false,
-  };
-
-  const emitEvent = vi
-    .spyOn(manager as unknown as { emitEvent: (...args: unknown[]) => void }, "emitEvent")
-    .mockImplementation(() => {});
-  const updateSession = vi
-    .spyOn(manager as unknown as { updateSession: (...args: unknown[]) => void }, "updateSession")
-    .mockImplementation(() => {});
-
-  return { manager, context, emitEvent, updateSession };
-}
-
-describe("classifyCodexStderrLine", () => {
-  it("ignores empty lines", () => {
-    expect(classifyCodexStderrLine("   ")).toBeNull();
-  });
-
-  it("ignores non-error structured codex logs", () => {
-    const line =
-      "2026-02-08T04:24:19.241256Z  WARN codex_core::features: unknown feature key in config: skills";
-    expect(classifyCodexStderrLine(line)).toBeNull();
-  });
-
-  it("ignores known benign rollout path errors", () => {
-    const line =
-      "\u001b[2m2026-02-08T04:24:20.085687Z\u001b[0m \u001b[31mERROR\u001b[0m \u001b[2mcodex_core::rollout::list\u001b[0m: state db missing rollout path for thread 019c3b6c-46b8-7b70-ad23-82f824d161fb";
-    expect(classifyCodexStderrLine(line)).toBeNull();
-  });
-
-  it("keeps unknown structured errors", () => {
-    const line = "2026-02-08T04:24:20.085687Z ERROR codex_core::runtime: unrecoverable failure";
-    expect(classifyCodexStderrLine(line)).toEqual({
-      message: line,
-    });
-  });
-
-  it("keeps plain stderr messages", () => {
-    const line = "fatal: permission denied";
-    expect(classifyCodexStderrLine(line)).toEqual({
-      message: line,
-    });
-  });
-});
-
-describe("process stderr events", () => {
-  it("emits classified stderr lines as notifications", () => {
-    const manager = new CodexAppServerManager();
-    const emitEvent = vi
-      .spyOn(manager as unknown as { emitEvent: (...args: unknown[]) => void }, "emitEvent")
-      .mockImplementation(() => {});
-
-    (
-      manager as unknown as {
-        emitNotificationEvent: (
-          context: { session: { threadId: ThreadId } },
-          method: string,
-          message: string,
-        ) => void;
-      }
-    ).emitNotificationEvent(
-      {
-        session: {
-          threadId: asThreadId("thread-1"),
-        },
-      },
-      "process/stderr",
-      "fatal: permission denied",
-    );
-
-    expect(emitEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        kind: "notification",
-        method: "process/stderr",
-        threadId: "thread-1",
-        message: "fatal: permission denied",
-      }),
-    );
-  });
-});
-
-describe("normalizeCodexModelSlug", () => {
-  it("maps 5.3 aliases to gpt-5.3-codex", () => {
-    expect(normalizeCodexModelSlug("5.3")).toBe("gpt-5.3-codex");
-    expect(normalizeCodexModelSlug("gpt-5.3")).toBe("gpt-5.3-codex");
-  });
-
-  it("prefers codex id when model differs", () => {
-    expect(normalizeCodexModelSlug("gpt-5.3", "gpt-5.3-codex")).toBe("gpt-5.3-codex");
-  });
-
-  it("keeps non-aliased models as-is", () => {
-    expect(normalizeCodexModelSlug("gpt-5.2-codex")).toBe("gpt-5.2-codex");
-    expect(normalizeCodexModelSlug("gpt-5.2")).toBe("gpt-5.2");
-  });
-});
-
-describe("isRecoverableThreadResumeError", () => {
-  it("matches not-found resume errors", () => {
-    expect(
-      isRecoverableThreadResumeError(new Error("thread/resume failed: thread not found")),
-    ).toBe(true);
-  });
-
-  it("ignores non-resume errors", () => {
-    expect(
-      isRecoverableThreadResumeError(new Error("thread/start failed: permission denied")),
-    ).toBe(false);
-  });
-
-  it("ignores non-recoverable resume errors", () => {
-    expect(
-      isRecoverableThreadResumeError(
-        new Error("thread/resume failed: timed out waiting for server"),
-      ),
-    ).toBe(false);
-  });
-});
-
-describe("readCodexAccountSnapshot", () => {
-  it("disables spark for chatgpt plus accounts", () => {
-    expect(
-      readCodexAccountSnapshot({
-        type: "chatgpt",
-        email: "plus@example.com",
-        planType: "plus",
-      }),
-    ).toEqual({
-      type: "chatgpt",
-      planType: "plus",
-      sparkEnabled: false,
-    });
-  });
-
-  it("keeps spark enabled for chatgpt pro accounts", () => {
-    expect(
-      readCodexAccountSnapshot({
-        type: "chatgpt",
-        email: "pro@example.com",
-        planType: "pro",
-      }),
-    ).toEqual({
-      type: "chatgpt",
-      planType: "pro",
-      sparkEnabled: true,
-    });
-  });
-
-  it("disables spark for api key accounts", () => {
-    expect(
-      readCodexAccountSnapshot({
-        type: "apiKey",
-      }),
-    ).toEqual({
-      type: "apiKey",
-      planType: null,
-      sparkEnabled: false,
-    });
-  });
-
-  it("disables spark for unknown chatgpt plans", () => {
-    expect(
-      readCodexAccountSnapshot({
-        type: "chatgpt",
-        email: "unknown@example.com",
-      }),
-    ).toEqual({
-      type: "chatgpt",
-      planType: "unknown",
-      sparkEnabled: false,
-    });
-  });
-});
-
-describe("resolveCodexModelForAccount", () => {
-  it("falls back from spark to default for unsupported chatgpt plans", () => {
-    expect(
-      resolveCodexModelForAccount("gpt-5.3-codex-spark", {
-        type: "chatgpt",
-        planType: "plus",
-        sparkEnabled: false,
-      }),
-    ).toBe("gpt-5.3-codex");
-  });
-
-  it("keeps spark for supported plans", () => {
-    expect(
-      resolveCodexModelForAccount("gpt-5.3-codex-spark", {
-        type: "chatgpt",
-        planType: "pro",
-        sparkEnabled: true,
-      }),
-    ).toBe("gpt-5.3-codex-spark");
-  });
-
-  it("falls back from spark to default for api key auth", () => {
-    expect(
-      resolveCodexModelForAccount("gpt-5.3-codex-spark", {
-        type: "apiKey",
-        planType: null,
-        sparkEnabled: false,
-      }),
-    ).toBe("gpt-5.3-codex");
-  });
-});
-
-describe("startSession", () => {
-  it("enables Codex experimental api capabilities during initialize", () => {
-    expect(buildCodexInitializeParams()).toEqual({
-      clientInfo: {
-        name: "t3code_desktop",
-        title: "T3 Code Desktop",
-        version: "0.1.0",
-      },
-      capabilities: {
-        experimentalApi: true,
-      },
-    });
-  });
-
-  it("emits session/startFailed when resolving cwd throws before process launch", async () => {
-    const manager = new CodexAppServerManager();
-    const events: Array<{ method: string; kind: string; message?: string }> = [];
-    manager.on("event", (event) => {
-      events.push({
-        method: event.method,
-        kind: event.kind,
-        ...(event.message ? { message: event.message } : {}),
-      });
-    });
-
-    const processCwd = vi.spyOn(process, "cwd").mockImplementation(() => {
-      throw new Error("cwd missing");
-    });
-    try {
-      await expect(
-        manager.startSession({
-          threadId: asThreadId("thread-1"),
-          provider: "codex",
-          binaryPath: "codex",
-          runtimeMode: "full-access",
-        }),
-      ).rejects.toThrow("cwd missing");
-      expect(events).toHaveLength(1);
-      expect(events[0]).toEqual({
-        method: "session/startFailed",
-        kind: "error",
-        message: "cwd missing",
-      });
-    } finally {
-      processCwd.mockRestore();
-      manager.stopAll();
-    }
-  });
-
-  it("fails fast with an upgrade message when codex is below the minimum supported version", async () => {
-    const manager = new CodexAppServerManager();
-    const events: Array<{ method: string; kind: string; message?: string }> = [];
-    manager.on("event", (event) => {
-      events.push({
-        method: event.method,
-        kind: event.kind,
-        ...(event.message ? { message: event.message } : {}),
-      });
-    });
-
-    const versionCheck = vi
-      .spyOn(
-        manager as unknown as {
-          assertSupportedCodexCliVersion: (input: {
-            binaryPath: string;
-            cwd: string;
-            homePath?: string;
-          }) => void;
-        },
-        "assertSupportedCodexCliVersion",
-      )
-      .mockImplementation(() => {
-        throw new Error(
-          "Codex CLI v0.36.0 is too old for T3 Code. Upgrade to v0.37.0 or newer and restart T3 Code.",
-        );
-      });
-
-    try {
-      await expect(
-        manager.startSession({
-          threadId: asThreadId("thread-1"),
-          provider: "codex",
-          binaryPath: "codex",
-          runtimeMode: "full-access",
-        }),
-      ).rejects.toThrow(
-        "Codex CLI v0.36.0 is too old for T3 Code. Upgrade to v0.37.0 or newer and restart T3 Code.",
-      );
-      expect(versionCheck).toHaveBeenCalledTimes(1);
-      expect(events).toEqual([
-        {
-          method: "session/startFailed",
-          kind: "error",
-          message:
-            "Codex CLI v0.36.0 is too old for T3 Code. Upgrade to v0.37.0 or newer and restart T3 Code.",
-        },
-      ]);
-    } finally {
-      versionCheck.mockRestore();
-      manager.stopAll();
-    }
-  });
-});
-
-describe("sendTurn", () => {
-  it("sends text and image user input items to turn/start", async () => {
-    const { manager, context, requireSession, sendRequest, updateSession } =
-      createSendTurnHarness();
-
-    const result = await manager.sendTurn({
-      threadId: asThreadId("thread_1"),
-      input: "Inspect this image",
-      attachments: [
-        {
-          type: "image",
-          url: "data:image/png;base64,AAAA",
-        },
-      ],
-      model: "gpt-5.3",
-      serviceTier: "fast",
-      effort: "high",
-    });
-
-    expect(result).toEqual({
-      threadId: "thread_1",
-      turnId: "turn_1",
-      resumeCursor: { threadId: "thread_1" },
-    });
-    expect(requireSession).toHaveBeenCalledWith("thread_1");
-    expect(sendRequest).toHaveBeenCalledWith(context, "turn/start", {
-      threadId: "thread_1",
-      input: [
-        {
-          type: "text",
-          text: "Inspect this image",
-          text_elements: [],
-        },
-        {
-          type: "image",
-          url: "data:image/png;base64,AAAA",
-        },
-      ],
-      model: "gpt-5.3-codex",
-      serviceTier: "fast",
-      effort: "high",
-    });
-    expect(updateSession).toHaveBeenCalledWith(context, {
-      status: "running",
-      activeTurnId: "turn_1",
-      resumeCursor: { threadId: "thread_1" },
-    });
-  });
-
-  it("supports image-only turns", async () => {
-    const { manager, context, sendRequest } = createSendTurnHarness();
-
-    await manager.sendTurn({
-      threadId: asThreadId("thread_1"),
-      attachments: [
-        {
-          type: "image",
-          url: "data:image/png;base64,BBBB",
-        },
-      ],
-    });
-
-    expect(sendRequest).toHaveBeenCalledWith(context, "turn/start", {
-      threadId: "thread_1",
-      input: [
-        {
-          type: "image",
-          url: "data:image/png;base64,BBBB",
-        },
-      ],
-      model: "gpt-5.3-codex",
-    });
-  });
-
-  it("passes Codex plan mode as a collaboration preset on turn/start", async () => {
-    const { manager, context, sendRequest } = createSendTurnHarness();
-
-    await manager.sendTurn({
-      threadId: asThreadId("thread_1"),
-      input: "Plan the work",
-      interactionMode: "plan",
-    });
-
-    expect(sendRequest).toHaveBeenCalledWith(context, "turn/start", {
-      threadId: "thread_1",
-      input: [
-        {
-          type: "text",
-          text: "Plan the work",
-          text_elements: [],
-        },
-      ],
-      model: "gpt-5.3-codex",
-      collaborationMode: {
-        mode: "plan",
-        settings: {
-          model: "gpt-5.3-codex",
-          reasoning_effort: "medium",
-          developer_instructions: CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
-        },
-      },
-    });
-  });
-
-  it("passes Codex default mode as a collaboration preset on turn/start", async () => {
-    const { manager, context, sendRequest } = createSendTurnHarness();
-
-    await manager.sendTurn({
-      threadId: asThreadId("thread_1"),
-      input: "PLEASE IMPLEMENT THIS PLAN:\n- step 1",
-      interactionMode: "default",
-    });
-
-    expect(sendRequest).toHaveBeenCalledWith(context, "turn/start", {
-      threadId: "thread_1",
-      input: [
-        {
-          type: "text",
-          text: "PLEASE IMPLEMENT THIS PLAN:\n- step 1",
-          text_elements: [],
-        },
-      ],
-      model: "gpt-5.3-codex",
-      collaborationMode: {
-        mode: "default",
-        settings: {
-          model: "gpt-5.3-codex",
-          reasoning_effort: "medium",
-          developer_instructions: CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
-        },
-      },
-    });
-  });
-
-  it("keeps the session model when interaction mode is set without an explicit model", async () => {
-    const { manager, context, sendRequest } = createSendTurnHarness();
-    context.session.model = "gpt-5.2-codex";
-
-    await manager.sendTurn({
-      threadId: asThreadId("thread_1"),
-      input: "Plan this with my current session model",
-      interactionMode: "plan",
-    });
-
-    expect(sendRequest).toHaveBeenCalledWith(context, "turn/start", {
-      threadId: "thread_1",
-      input: [
-        {
-          type: "text",
-          text: "Plan this with my current session model",
-          text_elements: [],
-        },
-      ],
-      model: "gpt-5.2-codex",
-      collaborationMode: {
-        mode: "plan",
-        settings: {
-          model: "gpt-5.2-codex",
-          reasoning_effort: "medium",
-          developer_instructions: CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
-        },
-      },
-    });
-  });
-
-  it("rejects empty turn input", async () => {
-    const { manager } = createSendTurnHarness();
-
-    await expect(
-      manager.sendTurn({
-        threadId: asThreadId("thread_1"),
-      }),
-    ).rejects.toThrow("Turn input must include text or attachments.");
-  });
-});
-
-describe("thread checkpoint control", () => {
-  it("reads thread turns from thread/read", async () => {
-    const { manager, context, requireSession, sendRequest } = createThreadControlHarness();
-    sendRequest.mockResolvedValue({
-      thread: {
-        id: "thread_1",
-        turns: [
-          {
-            id: "turn_1",
-            items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
-          },
-        ],
-      },
-    });
-
-    const result = await manager.readThread(asThreadId("thread_1"));
-
-    expect(requireSession).toHaveBeenCalledWith("thread_1");
-    expect(sendRequest).toHaveBeenCalledWith(context, "thread/read", {
-      threadId: "thread_1",
-      includeTurns: true,
-    });
-    expect(result).toEqual({
-      threadId: "thread_1",
-      turns: [
-        {
-          id: "turn_1",
-          items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
-        },
-      ],
-    });
-  });
-
-  it("reads thread turns from flat thread/read responses", async () => {
-    const { manager, context, sendRequest } = createThreadControlHarness();
-    sendRequest.mockResolvedValue({
-      threadId: "thread_1",
-      turns: [
-        {
-          id: "turn_1",
-          items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
-        },
-      ],
-    });
-
-    const result = await manager.readThread(asThreadId("thread_1"));
-
-    expect(sendRequest).toHaveBeenCalledWith(context, "thread/read", {
-      threadId: "thread_1",
-      includeTurns: true,
-    });
-    expect(result).toEqual({
-      threadId: "thread_1",
-      turns: [
-        {
-          id: "turn_1",
-          items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
-        },
-      ],
-    });
-  });
-
-  it("rolls back turns via thread/rollback and resets session running state", async () => {
-    const { manager, context, sendRequest, updateSession } = createThreadControlHarness();
-    sendRequest.mockResolvedValue({
-      thread: {
-        id: "thread_1",
-        turns: [],
-      },
-    });
-
-    const result = await manager.rollbackThread(asThreadId("thread_1"), 2);
-
-    expect(sendRequest).toHaveBeenCalledWith(context, "thread/rollback", {
-      threadId: "thread_1",
-      numTurns: 2,
-    });
-    expect(updateSession).toHaveBeenCalledWith(context, {
-      status: "ready",
-      activeTurnId: undefined,
-    });
-    expect(result).toEqual({
-      threadId: "thread_1",
-      turns: [],
-    });
-  });
-});
-
-describe("respondToUserInput", () => {
-  it("serializes canonical answers to Codex native answer objects", async () => {
-    const { manager, context, requireSession, writeMessage, emitEvent } =
-      createPendingUserInputHarness();
-
-    await manager.respondToUserInput(
-      asThreadId("thread_1"),
-      ApprovalRequestId.make("req-user-input-1"),
-      {
-        scope: "All request methods",
-        compat: "Keep current envelope",
-      },
-    );
-
-    expect(requireSession).toHaveBeenCalledWith("thread_1");
-    expect(writeMessage).toHaveBeenCalledWith(context, {
-      id: 42,
-      result: {
-        answers: {
-          scope: { answers: ["All request methods"] },
-          compat: { answers: ["Keep current envelope"] },
-        },
-      },
-    });
-    expect(emitEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        method: "item/tool/requestUserInput/answered",
-        payload: {
-          requestId: "req-user-input-1",
-          answers: {
-            scope: { answers: ["All request methods"] },
-            compat: { answers: ["Keep current envelope"] },
-          },
-        },
-      }),
-    );
-  });
-
-  it("preserves explicit empty multi-select answers", async () => {
-    const { manager, context, requireSession, writeMessage, emitEvent } =
-      createPendingUserInputHarness();
-
-    await manager.respondToUserInput(
-      asThreadId("thread_1"),
-      ApprovalRequestId.make("req-user-input-1"),
-      {
-        scope: [],
-      },
-    );
-
-    expect(requireSession).toHaveBeenCalledWith("thread_1");
-    expect(writeMessage).toHaveBeenCalledWith(context, {
-      id: 42,
-      result: {
-        answers: {
-          scope: { answers: [] },
-        },
-      },
-    });
-    expect(emitEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        method: "item/tool/requestUserInput/answered",
-        payload: {
-          requestId: "req-user-input-1",
-          answers: {
-            scope: { answers: [] },
-          },
-        },
-      }),
-    );
-  });
-
-  it("tracks file-read approval requests with the correct method", () => {
-    const manager = new CodexAppServerManager();
-    const context = {
-      session: {
-        sessionId: "sess_1",
-        provider: "codex",
-        status: "ready",
-        threadId: asThreadId("thread_1"),
-        resumeCursor: { threadId: "thread_1" },
-        createdAt: "2026-02-10T00:00:00.000Z",
-        updatedAt: "2026-02-10T00:00:00.000Z",
-      },
-      pendingApprovals: new Map(),
-      pendingUserInputs: new Map(),
-      collabReceiverTurns: new Map(),
-    };
-    type ApprovalRequestContext = {
-      session: typeof context.session;
-      pendingApprovals: typeof context.pendingApprovals;
-      pendingUserInputs: typeof context.pendingUserInputs;
-    };
-
-    (
-      manager as unknown as {
-        handleServerRequest: (
-          context: ApprovalRequestContext,
-          request: Record<string, unknown>,
-        ) => void;
-      }
-    ).handleServerRequest(context, {
-      jsonrpc: "2.0",
-      id: 42,
-      method: "item/fileRead/requestApproval",
-      params: {},
-    });
-
-    const request = Array.from(context.pendingApprovals.values())[0];
-    expect(request?.requestKind).toBe("file-read");
-    expect(request?.method).toBe("item/fileRead/requestApproval");
-  });
-});
-
-describe("collab child conversation routing", () => {
-  it("rewrites child notification turn ids onto the parent turn", () => {
-    const { manager, context, emitEvent } = createCollabNotificationHarness();
-
-    (
-      manager as unknown as {
-        handleServerNotification: (context: unknown, notification: Record<string, unknown>) => void;
-      }
-    ).handleServerNotification(context, {
-      method: "item/completed",
-      params: {
-        item: {
-          type: "collabAgentToolCall",
-          id: "call_collab_1",
-          receiverThreadIds: ["child_provider_1"],
-        },
-        threadId: "provider_parent",
-        turnId: "turn_parent",
-      },
-    });
-
-    (
-      manager as unknown as {
-        handleServerNotification: (context: unknown, notification: Record<string, unknown>) => void;
-      }
-    ).handleServerNotification(context, {
-      method: "item/agentMessage/delta",
-      params: {
-        threadId: "child_provider_1",
-        turnId: "turn_child_1",
-        itemId: "msg_child_1",
-        delta: "working",
-      },
-    });
-
-    expect(emitEvent).toHaveBeenLastCalledWith(
-      expect.objectContaining({
-        method: "item/agentMessage/delta",
-        turnId: "turn_parent",
-        itemId: "msg_child_1",
-      }),
-    );
-  });
-
-  it("suppresses child lifecycle notifications so they cannot replace the parent turn", () => {
-    const { manager, context, emitEvent, updateSession } = createCollabNotificationHarness();
-
-    (
-      manager as unknown as {
-        handleServerNotification: (context: unknown, notification: Record<string, unknown>) => void;
-      }
-    ).handleServerNotification(context, {
-      method: "item/completed",
-      params: {
-        item: {
-          type: "collabAgentToolCall",
-          id: "call_collab_1",
-          receiverThreadIds: ["child_provider_1"],
-        },
-        threadId: "provider_parent",
-        turnId: "turn_parent",
-      },
-    });
-    emitEvent.mockClear();
-    updateSession.mockClear();
-
-    (
-      manager as unknown as {
-        handleServerNotification: (context: unknown, notification: Record<string, unknown>) => void;
-      }
-    ).handleServerNotification(context, {
-      method: "turn/started",
-      params: {
-        threadId: "child_provider_1",
-        turn: { id: "turn_child_1" },
-      },
-    });
-
-    (
-      manager as unknown as {
-        handleServerNotification: (context: unknown, notification: Record<string, unknown>) => void;
-      }
-    ).handleServerNotification(context, {
-      method: "turn/completed",
-      params: {
-        threadId: "child_provider_1",
-        turn: { id: "turn_child_1", status: "completed" },
-      },
-    });
-
-    expect(emitEvent).not.toHaveBeenCalled();
-    expect(updateSession).not.toHaveBeenCalled();
-  });
-
-  it("rewrites child approval requests onto the parent turn", () => {
-    const { manager, context, emitEvent } = createCollabNotificationHarness();
-
-    (
-      manager as unknown as {
-        handleServerNotification: (context: unknown, notification: Record<string, unknown>) => void;
-      }
-    ).handleServerNotification(context, {
-      method: "item/completed",
-      params: {
-        item: {
-          type: "collabAgentToolCall",
-          id: "call_collab_1",
-          receiverThreadIds: ["child_provider_1"],
-        },
-        threadId: "provider_parent",
-        turnId: "turn_parent",
-      },
-    });
-    emitEvent.mockClear();
-
-    (
-      manager as unknown as {
-        handleServerRequest: (context: unknown, request: Record<string, unknown>) => void;
-      }
-    ).handleServerRequest(context, {
-      id: 42,
-      method: "item/commandExecution/requestApproval",
-      params: {
-        threadId: "child_provider_1",
-        turnId: "turn_child_1",
-        itemId: "call_child_1",
-        command: "bun install",
-      },
-    });
-
-    expect(Array.from(context.pendingApprovals.values())[0]).toEqual(
-      expect.objectContaining({
-        turnId: "turn_parent",
-        itemId: "call_child_1",
-      }),
-    );
-    expect(emitEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        method: "item/commandExecution/requestApproval",
-        turnId: "turn_parent",
-        itemId: "call_child_1",
-      }),
-    );
-  });
-});
-
-describe.skipIf(!process.env.CODEX_BINARY_PATH)("startSession live Codex resume", () => {
-  it("keeps prior thread history when resuming with a changed runtime mode", async () => {
-    const workspaceDir = mkdtempSync(path.join(os.tmpdir(), "codex-live-resume-"));
-    writeFileSync(path.join(workspaceDir, "README.md"), "hello\n", "utf8");
-
-    const manager = new CodexAppServerManager();
-
-    try {
-      const firstSession = await manager.startSession({
-        threadId: asThreadId("thread-live"),
-        provider: "codex",
-        cwd: workspaceDir,
-        runtimeMode: "full-access",
-        binaryPath: process.env.CODEX_BINARY_PATH!,
-        ...(process.env.CODEX_HOME_PATH ? { homePath: process.env.CODEX_HOME_PATH } : {}),
-      });
-
-      const firstTurn = await manager.sendTurn({
-        threadId: firstSession.threadId,
-        input: `Reply with exactly the word ALPHA ${randomUUID()}`,
-      });
-
-      expect(firstTurn.threadId).toBe(firstSession.threadId);
-
-      await vi.waitFor(
-        async () => {
-          const snapshot = await manager.readThread(firstSession.threadId);
-          expect(snapshot.turns.length).toBeGreaterThan(0);
-        },
-        { timeout: 120_000, interval: 1_000 },
-      );
-
-      const firstSnapshot = await manager.readThread(firstSession.threadId);
-      const originalThreadId = firstSnapshot.threadId;
-      const originalTurnCount = firstSnapshot.turns.length;
-
-      manager.stopSession(firstSession.threadId);
-
-      const resumedSession = await manager.startSession({
-        threadId: firstSession.threadId,
-        provider: "codex",
-        cwd: workspaceDir,
-        runtimeMode: "approval-required",
-        resumeCursor: firstSession.resumeCursor,
-        binaryPath: process.env.CODEX_BINARY_PATH!,
-        ...(process.env.CODEX_HOME_PATH ? { homePath: process.env.CODEX_HOME_PATH } : {}),
-      });
-
-      expect(resumedSession.threadId).toBe(originalThreadId);
-
-      const resumedSnapshotBeforeTurn = await manager.readThread(resumedSession.threadId);
-      expect(resumedSnapshotBeforeTurn.threadId).toBe(originalThreadId);
-      expect(resumedSnapshotBeforeTurn.turns.length).toBeGreaterThanOrEqual(originalTurnCount);
-
-      await manager.sendTurn({
-        threadId: resumedSession.threadId,
-        input: `Reply with exactly the word BETA ${randomUUID()}`,
-      });
-
-      await vi.waitFor(
-        async () => {
-          const snapshot = await manager.readThread(resumedSession.threadId);
-          expect(snapshot.turns.length).toBeGreaterThan(originalTurnCount);
-        },
-        { timeout: 120_000, interval: 1_000 },
-      );
-    } finally {
-      manager.stopAll();
-      rmSync(workspaceDir, { recursive: true, force: true });
-    }
-  }, 180_000);
-});
diff --git a/apps/server/src/codexAppServerManager.ts b/apps/server/src/codexAppServerManager.ts
deleted file mode 100644
index 230ba8e3641..00000000000
--- a/apps/server/src/codexAppServerManager.ts
+++ /dev/null
@@ -1,1598 +0,0 @@
-import { type ChildProcessWithoutNullStreams, spawn, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { EventEmitter } from "node:events";
-import readline from "node:readline";
-
-import {
-  ApprovalRequestId,
-  EventId,
-  ProviderItemId,
-  ProviderRequestKind,
-  type ProviderUserInputAnswers,
-  ThreadId,
-  TurnId,
-  type ProviderApprovalDecision,
-  type ProviderEvent,
-  type ProviderSession,
-  type ProviderTurnStartResult,
-  RuntimeMode,
-  ProviderInteractionMode,
-} from "@t3tools/contracts";
-import { normalizeModelSlug } from "@t3tools/shared/model";
-import { Effect, Context } from "effect";
-
-import {
-  formatCodexCliUpgradeMessage,
-  isCodexCliVersionSupported,
-  parseCodexCliVersion,
-} from "./provider/codexCliVersion";
-import {
-  readCodexAccountSnapshot,
-  resolveCodexModelForAccount,
-  type CodexAccountSnapshot,
-} from "./provider/codexAccount";
-import { buildCodexInitializeParams, killCodexChildProcess } from "./provider/codexAppServer";
-
-export { buildCodexInitializeParams } from "./provider/codexAppServer";
-export { readCodexAccountSnapshot, resolveCodexModelForAccount } from "./provider/codexAccount";
-
-type PendingRequestKey = string;
-
-interface PendingRequest {
-  method: string;
-  timeout: ReturnType<typeof setTimeout>;
-  resolve: (value: unknown) => void;
-  reject: (error: Error) => void;
-}
-
-interface PendingApprovalRequest {
-  requestId: ApprovalRequestId;
-  jsonRpcId: string | number;
-  method:
-    | "item/commandExecution/requestApproval"
-    | "item/fileChange/requestApproval"
-    | "item/fileRead/requestApproval";
-  requestKind: ProviderRequestKind;
-  threadId: ThreadId;
-  turnId?: TurnId;
-  itemId?: ProviderItemId;
-}
-
-interface PendingUserInputRequest {
-  requestId: ApprovalRequestId;
-  jsonRpcId: string | number;
-  threadId: ThreadId;
-  turnId?: TurnId;
-  itemId?: ProviderItemId;
-}
-
-interface CodexUserInputAnswer {
-  answers: string[];
-}
-
-interface CodexSessionContext {
-  session: ProviderSession;
-  account: CodexAccountSnapshot;
-  child: ChildProcessWithoutNullStreams;
-  output: readline.Interface;
-  pending: Map<PendingRequestKey, PendingRequest>;
-  pendingApprovals: Map<ApprovalRequestId, PendingApprovalRequest>;
-  pendingUserInputs: Map<ApprovalRequestId, PendingUserInputRequest>;
-  collabReceiverTurns: Map<string, TurnId>;
-  nextRequestId: number;
-  stopping: boolean;
-}
-
-interface JsonRpcError {
-  code?: number;
-  message?: string;
-}
-
-interface JsonRpcRequest {
-  id: string | number;
-  method: string;
-  params?: unknown;
-}
-
-interface JsonRpcResponse {
-  id: string | number;
-  result?: unknown;
-  error?: JsonRpcError;
-}
-
-interface JsonRpcNotification {
-  method: string;
-  params?: unknown;
-}
-
-export interface CodexAppServerSendTurnInput {
-  readonly threadId: ThreadId;
-  readonly input?: string;
-  readonly attachments?: ReadonlyArray<{ type: "image"; url: string }>;
-  readonly model?: string;
-  readonly serviceTier?: string | null;
-  readonly effort?: string;
-  readonly interactionMode?: ProviderInteractionMode;
-}
-
-export interface CodexAppServerStartSessionInput {
-  readonly threadId: ThreadId;
-  readonly provider?: "codex";
-  readonly cwd?: string;
-  readonly model?: string;
-  readonly serviceTier?: string;
-  readonly resumeCursor?: unknown;
-  readonly binaryPath: string;
-  readonly homePath?: string;
-  readonly runtimeMode: RuntimeMode;
-}
-
-export interface CodexThreadTurnSnapshot {
-  id: TurnId;
-  items: unknown[];
-}
-
-export interface CodexThreadSnapshot {
-  threadId: string;
-  turns: CodexThreadTurnSnapshot[];
-}
-
-const CODEX_VERSION_CHECK_TIMEOUT_MS = 4_000;
-
-const ANSI_ESCAPE_CHAR = String.fromCharCode(27);
-const ANSI_ESCAPE_REGEX = new RegExp(`${ANSI_ESCAPE_CHAR}\\[[0-9;]*m`, "g");
-const CODEX_STDERR_LOG_REGEX =
-  /^\d{4}-\d{2}-\d{2}T\S+\s+(TRACE|DEBUG|INFO|WARN|ERROR)\s+\S+:\s+(.*)$/;
-const BENIGN_ERROR_LOG_SNIPPETS = [
-  "state db missing rollout path for thread",
-  "state db record_discrepancy: find_thread_path_by_id_str_in_subdir, falling_back",
-];
-const RECOVERABLE_THREAD_RESUME_ERROR_SNIPPETS = [
-  "not found",
-  "missing thread",
-  "no such thread",
-  "unknown thread",
-  "does not exist",
-];
-export const CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Plan Mode (Conversational)
-
-You work in 3 phases, and you should *chat your way* to a great plan before finalizing it. A great plan is very detailed-intent- and implementation-wise-so that it can be handed to another engineer or agent to be implemented right away. It must be **decision complete**, where the implementer does not need to make any decisions.
-
-## Mode rules (strict)
-
-You are in **Plan Mode** until a developer message explicitly ends it.
-
-Plan Mode is not changed by user intent, tone, or imperative language. If a user asks for execution while still in Plan Mode, treat it as a request to **plan the execution**, not perform it.
-
-## Plan Mode vs update_plan tool
-
-Plan Mode is a collaboration mode that can involve requesting user input and eventually issuing a \`<proposed_plan>\` block.
-
-Separately, \`update_plan\` is a checklist/progress/TODOs tool; it does not enter or exit Plan Mode. Do not confuse it with Plan mode or try to use it while in Plan mode. If you try to use \`update_plan\` in Plan mode, it will return an error.
-
-## Execution vs. mutation in Plan Mode
-
-You may explore and execute **non-mutating** actions that improve the plan. You must not perform **mutating** actions.
-
-### Allowed (non-mutating, plan-improving)
-
-Actions that gather truth, reduce ambiguity, or validate feasibility without changing repo-tracked state. Examples:
-
-* Reading or searching files, configs, schemas, types, manifests, and docs
-* Static analysis, inspection, and repo exploration
-* Dry-run style commands when they do not edit repo-tracked files
-* Tests, builds, or checks that may write to caches or build artifacts (for example, \`target/\`, \`.cache/\`, or snapshots) so long as they do not edit repo-tracked files
-
-### Not allowed (mutating, plan-executing)
-
-Actions that implement the plan or change repo-tracked state. Examples:
-
-* Editing or writing files
-* Running formatters or linters that rewrite files
-* Applying patches, migrations, or codegen that updates repo-tracked files
-* Side-effectful commands whose purpose is to carry out the plan rather than refine it
-
-When in doubt: if the action would reasonably be described as "doing the work" rather than "planning the work," do not do it.
-
-## PHASE 1 - Ground in the environment (explore first, ask second)
-
-Begin by grounding yourself in the actual environment. Eliminate unknowns in the prompt by discovering facts, not by asking the user. Resolve all questions that can be answered through exploration or inspection. Identify missing or ambiguous details only if they cannot be derived from the environment. Silent exploration between turns is allowed and encouraged.
-
-Before asking the user any question, perform at least one targeted non-mutating exploration pass (for example: search relevant files, inspect likely entrypoints/configs, confirm current implementation shape), unless no local environment/repo is available.
-
-Exception: you may ask clarifying questions about the user's prompt before exploring, ONLY if there are obvious ambiguities or contradictions in the prompt itself. However, if ambiguity might be resolved by exploring, always prefer exploring first.
-
-Do not ask questions that can be answered from the repo or system (for example, "where is this struct?" or "which UI component should we use?" when exploration can make it clear). Only ask once you have exhausted reasonable non-mutating exploration.
-
-## PHASE 2 - Intent chat (what they actually want)
-
-* Keep asking until you can clearly state: goal + success criteria, audience, in/out of scope, constraints, current state, and the key preferences/tradeoffs.
-* Bias toward questions over guessing: if any high-impact ambiguity remains, do NOT plan yet-ask.
-
-## PHASE 3 - Implementation chat (what/how we'll build)
-
-* Once intent is stable, keep asking until the spec is decision complete: approach, interfaces (APIs/schemas/I/O), data flow, edge cases/failure modes, testing + acceptance criteria, rollout/monitoring, and any migrations/compat constraints.
-
-## Asking questions
-
-Critical rules:
-
-* Strongly prefer using the \`request_user_input\` tool to ask any questions.
-* Offer only meaningful multiple-choice options; don't include filler choices that are obviously wrong or irrelevant.
-* In rare cases where an unavoidable, important question can't be expressed with reasonable multiple-choice options (due to extreme ambiguity), you may ask it directly without the tool.
-
-You SHOULD ask many questions, but each question must:
-
-* materially change the spec/plan, OR
-* confirm/lock an assumption, OR
-* choose between meaningful tradeoffs.
-* not be answerable by non-mutating commands.
-
-Use the \`request_user_input\` tool only for decisions that materially change the plan, for confirming important assumptions, or for information that cannot be discovered via non-mutating exploration.
-
-## Two kinds of unknowns (treat differently)
-
-1. **Discoverable facts** (repo/system truth): explore first.
-
-   * Before asking, run targeted searches and check likely sources of truth (configs/manifests/entrypoints/schemas/types/constants).
-   * Ask only if: multiple plausible candidates; nothing found but you need a missing identifier/context; or ambiguity is actually product intent.
-   * If asking, present concrete candidates (paths/service names) + recommend one.
-   * Never ask questions you can answer from your environment (e.g., "where is this struct").
-
-2. **Preferences/tradeoffs** (not discoverable): ask early.
-
-   * These are intent or implementation preferences that cannot be derived from exploration.
-   * Provide 2-4 mutually exclusive options + a recommended default.
-   * If unanswered, proceed with the recommended option and record it as an assumption in the final plan.
-
-## Finalization rule
-
-Only output the final plan when it is decision complete and leaves no decisions to the implementer.
-
-When you present the official plan, wrap it in a \`<proposed_plan>\` block so the client can render it specially:
-
-1) The opening tag must be on its own line.
-2) Start the plan content on the next line (no text on the same line as the tag).
-3) The closing tag must be on its own line.
-4) Use Markdown inside the block.
-5) Keep the tags exactly as \`<proposed_plan>\` and \`</proposed_plan>\` (do not translate or rename them), even if the plan content is in another language.
-
-Example:
-
-<proposed_plan>
-plan content
-</proposed_plan>
-
-plan content should be human and agent digestible. The final plan must be plan-only and include:
-
-* A clear title
-* A brief summary section
-* Important changes or additions to public APIs/interfaces/types
-* Test cases and scenarios
-* Explicit assumptions and defaults chosen where needed
-
-Do not ask "should I proceed?" in the final output. The user can easily switch out of Plan mode and request implementation if you have included a \`<proposed_plan>\` block in your response. Alternatively, they can decide to stay in Plan mode and continue refining the plan.
-
-Only produce at most one \`<proposed_plan>\` block per turn, and only when you are presenting a complete spec.
-</collaboration_mode>`;
-
-export const CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Collaboration Mode: Default
-
-You are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.
-
-Your active mode changes only when new developer instructions with a different \`<collaboration_mode>...</collaboration_mode>\` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are Default and Plan.
-
-## request_user_input availability
-
-The \`request_user_input\` tool is unavailable in Default mode. If you call it while in Default mode, it will return an error.
-
-In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.
-</collaboration_mode>`;
-
-function mapCodexRuntimeMode(runtimeMode: RuntimeMode): {
-  readonly approvalPolicy: "untrusted" | "on-request" | "never";
-  readonly sandbox: "read-only" | "workspace-write" | "danger-full-access";
-} {
-  switch (runtimeMode) {
-    case "approval-required":
-      return {
-        approvalPolicy: "untrusted",
-        sandbox: "read-only",
-      };
-    case "auto-accept-edits":
-      return {
-        approvalPolicy: "on-request",
-        sandbox: "workspace-write",
-      };
-    case "full-access":
-      return {
-        approvalPolicy: "never",
-        sandbox: "danger-full-access",
-      };
-  }
-}
-
-/**
- * On Windows with `shell: true`, `child.kill()` only terminates the `cmd.exe`
- * wrapper, leaving the actual command running. Use `taskkill /T` to kill the
- * entire process tree instead.
- */
-function killChildTree(child: ChildProcessWithoutNullStreams): void {
-  killCodexChildProcess(child);
-}
-
-export function normalizeCodexModelSlug(
-  model: string | undefined | null,
-  preferredId?: string,
-): string | undefined {
-  const normalized = normalizeModelSlug(model);
-  if (!normalized) {
-    return undefined;
-  }
-
-  if (preferredId?.endsWith("-codex") && preferredId !== normalized) {
-    return preferredId;
-  }
-
-  return normalized;
-}
-
-function buildCodexCollaborationMode(input: {
-  readonly interactionMode?: "default" | "plan";
-  readonly model?: string;
-  readonly effort?: string;
-}):
-  | {
-      mode: "default" | "plan";
-      settings: {
-        model: string;
-        reasoning_effort: string;
-        developer_instructions: string;
-      };
-    }
-  | undefined {
-  if (input.interactionMode === undefined) {
-    return undefined;
-  }
-  const model = normalizeCodexModelSlug(input.model) ?? "gpt-5.3-codex";
-  return {
-    mode: input.interactionMode,
-    settings: {
-      model,
-      reasoning_effort: input.effort ?? "medium",
-      developer_instructions:
-        input.interactionMode === "plan"
-          ? CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS
-          : CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
-    },
-  };
-}
-
-function toCodexUserInputAnswer(value: unknown): CodexUserInputAnswer {
-  if (typeof value === "string") {
-    return { answers: [value] };
-  }
-
-  if (Array.isArray(value)) {
-    const answers = value.filter((entry): entry is string => typeof entry === "string");
-    return { answers };
-  }
-
-  if (value && typeof value === "object") {
-    const maybeAnswers = (value as { answers?: unknown }).answers;
-    if (Array.isArray(maybeAnswers)) {
-      const answers = maybeAnswers.filter((entry): entry is string => typeof entry === "string");
-      return { answers };
-    }
-  }
-
-  throw new Error("User input answers must be strings or arrays of strings.");
-}
-
-function toCodexUserInputAnswers(
-  answers: ProviderUserInputAnswers,
-): Record<string, CodexUserInputAnswer> {
-  return Object.fromEntries(
-    Object.entries(answers).map(([questionId, value]) => [
-      questionId,
-      toCodexUserInputAnswer(value),
-    ]),
-  );
-}
-
-export function classifyCodexStderrLine(rawLine: string): { message: string } | null {
-  const line = rawLine.replaceAll(ANSI_ESCAPE_REGEX, "").trim();
-  if (!line) {
-    return null;
-  }
-
-  const match = line.match(CODEX_STDERR_LOG_REGEX);
-  if (match) {
-    const level = match[1];
-    if (level && level !== "ERROR") {
-      return null;
-    }
-
-    const isBenignError = BENIGN_ERROR_LOG_SNIPPETS.some((snippet) => line.includes(snippet));
-    if (isBenignError) {
-      return null;
-    }
-  }
-
-  return { message: line };
-}
-
-export function isRecoverableThreadResumeError(error: unknown): boolean {
-  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
-  if (!message.includes("thread/resume")) {
-    return false;
-  }
-
-  return RECOVERABLE_THREAD_RESUME_ERROR_SNIPPETS.some((snippet) => message.includes(snippet));
-}
-
-export interface CodexAppServerManagerEvents {
-  event: [event: ProviderEvent];
-}
-
-export class CodexAppServerManager extends EventEmitter<CodexAppServerManagerEvents> {
-  private readonly sessions = new Map<ThreadId, CodexSessionContext>();
-
-  private runPromise: (effect: Effect.Effect<unknown, never>) => Promise<unknown>;
-  constructor(services?: Context.Context<never>) {
-    super();
-    this.runPromise = services ? Effect.runPromiseWith(services) : Effect.runPromise;
-  }
-
-  async startSession(input: CodexAppServerStartSessionInput): Promise<ProviderSession> {
-    const threadId = input.threadId;
-    const now = new Date().toISOString();
-    let context: CodexSessionContext | undefined;
-
-    try {
-      const resolvedCwd = input.cwd ?? process.cwd();
-
-      const session: ProviderSession = {
-        provider: "codex",
-        status: "connecting",
-        runtimeMode: input.runtimeMode,
-        model: normalizeCodexModelSlug(input.model),
-        cwd: resolvedCwd,
-        threadId,
-        createdAt: now,
-        updatedAt: now,
-      };
-
-      const codexBinaryPath = input.binaryPath;
-      const codexHomePath = input.homePath;
-      this.assertSupportedCodexCliVersion({
-        binaryPath: codexBinaryPath,
-        cwd: resolvedCwd,
-        ...(codexHomePath ? { homePath: codexHomePath } : {}),
-      });
-      const child = spawn(codexBinaryPath, ["app-server"], {
-        cwd: resolvedCwd,
-        env: {
-          ...process.env,
-          ...(codexHomePath ? { CODEX_HOME: codexHomePath } : {}),
-        },
-        stdio: ["pipe", "pipe", "pipe"],
-        shell: process.platform === "win32",
-      });
-      const output = readline.createInterface({ input: child.stdout });
-
-      context = {
-        session,
-        account: {
-          type: "unknown",
-          planType: null,
-          sparkEnabled: true,
-        },
-        child,
-        output,
-        pending: new Map(),
-        pendingApprovals: new Map(),
-        pendingUserInputs: new Map(),
-        collabReceiverTurns: new Map(),
-        nextRequestId: 1,
-        stopping: false,
-      };
-
-      this.sessions.set(threadId, context);
-      this.attachProcessListeners(context);
-
-      this.emitLifecycleEvent(context, "session/connecting", "Starting codex app-server");
-
-      await this.sendRequest(context, "initialize", buildCodexInitializeParams());
-
-      this.writeMessage(context, { method: "initialized" });
-      try {
-        const modelListResponse = await this.sendRequest(context, "model/list", {});
-        console.log("codex model/list response", modelListResponse);
-      } catch (error) {
-        console.log("codex model/list failed", error);
-      }
-      try {
-        const accountReadResponse = await this.sendRequest(context, "account/read", {});
-        console.log("codex account/read response", accountReadResponse);
-        context.account = readCodexAccountSnapshot(accountReadResponse);
-        console.log("codex subscription status", {
-          type: context.account.type,
-          planType: context.account.planType,
-          sparkEnabled: context.account.sparkEnabled,
-        });
-      } catch (error) {
-        console.log("codex account/read failed", error);
-      }
-
-      const normalizedModel = resolveCodexModelForAccount(
-        normalizeCodexModelSlug(input.model),
-        context.account,
-      );
-      const sessionOverrides = {
-        model: normalizedModel ?? null,
-        ...(input.serviceTier !== undefined ? { serviceTier: input.serviceTier } : {}),
-        cwd: input.cwd ?? null,
-        ...mapCodexRuntimeMode(input.runtimeMode ?? "full-access"),
-      };
-
-      const threadStartParams = {
-        ...sessionOverrides,
-        experimentalRawEvents: false,
-      };
-      const resumeThreadId = readResumeThreadId(input);
-      this.emitLifecycleEvent(
-        context,
-        "session/threadOpenRequested",
-        resumeThreadId
-          ? `Attempting to resume thread ${resumeThreadId}.`
-          : "Starting a new Codex thread.",
-      );
-      await Effect.logInfo("codex app-server opening thread", {
-        threadId,
-        requestedRuntimeMode: input.runtimeMode,
-        requestedModel: normalizedModel ?? null,
-        requestedCwd: resolvedCwd,
-        resumeThreadId: resumeThreadId ?? null,
-      }).pipe(this.runPromise);
-
-      let threadOpenMethod: "thread/start" | "thread/resume" = "thread/start";
-      let threadOpenResponse: unknown;
-      if (resumeThreadId) {
-        try {
-          threadOpenMethod = "thread/resume";
-          threadOpenResponse = await this.sendRequest(context, "thread/resume", {
-            ...sessionOverrides,
-            threadId: resumeThreadId,
-          });
-        } catch (error) {
-          if (!isRecoverableThreadResumeError(error)) {
-            this.emitErrorEvent(
-              context,
-              "session/threadResumeFailed",
-              error instanceof Error ? error.message : "Codex thread resume failed.",
-            );
-            await Effect.logWarning("codex app-server thread resume failed", {
-              threadId,
-              requestedRuntimeMode: input.runtimeMode,
-              resumeThreadId,
-              recoverable: false,
-              cause: error instanceof Error ? error.message : String(error),
-            }).pipe(this.runPromise);
-            throw error;
-          }
-
-          threadOpenMethod = "thread/start";
-          this.emitLifecycleEvent(
-            context,
-            "session/threadResumeFallback",
-            `Could not resume thread ${resumeThreadId}; started a new thread instead.`,
-          );
-          await Effect.logWarning("codex app-server thread resume fell back to fresh start", {
-            threadId,
-            requestedRuntimeMode: input.runtimeMode,
-            resumeThreadId,
-            recoverable: true,
-            cause: error instanceof Error ? error.message : String(error),
-          }).pipe(this.runPromise);
-          threadOpenResponse = await this.sendRequest(context, "thread/start", threadStartParams);
-        }
-      } else {
-        threadOpenMethod = "thread/start";
-        threadOpenResponse = await this.sendRequest(context, "thread/start", threadStartParams);
-      }
-
-      const threadOpenRecord = this.readObject(threadOpenResponse);
-      const threadIdRaw =
-        this.readString(this.readObject(threadOpenRecord, "thread"), "id") ??
-        this.readString(threadOpenRecord, "threadId");
-      if (!threadIdRaw) {
-        throw new Error(`${threadOpenMethod} response did not include a thread id.`);
-      }
-      const providerThreadId = threadIdRaw;
-
-      this.updateSession(context, {
-        status: "ready",
-        resumeCursor: { threadId: providerThreadId },
-      });
-      this.emitLifecycleEvent(
-        context,
-        "session/threadOpenResolved",
-        `Codex ${threadOpenMethod} resolved.`,
-      );
-      await Effect.logInfo("codex app-server thread open resolved", {
-        threadId,
-        threadOpenMethod,
-        requestedResumeThreadId: resumeThreadId ?? null,
-        resolvedThreadId: providerThreadId,
-        requestedRuntimeMode: input.runtimeMode,
-      }).pipe(this.runPromise);
-      this.emitLifecycleEvent(context, "session/ready", `Connected to thread ${providerThreadId}`);
-      return { ...context.session };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to start Codex session.";
-      if (context) {
-        this.updateSession(context, {
-          status: "error",
-          lastError: message,
-        });
-        this.emitErrorEvent(context, "session/startFailed", message);
-        this.stopSession(threadId);
-      } else {
-        this.emitEvent({
-          id: EventId.make(randomUUID()),
-          kind: "error",
-          provider: "codex",
-          threadId,
-          createdAt: new Date().toISOString(),
-          method: "session/startFailed",
-          message,
-        });
-      }
-      throw new Error(message, { cause: error });
-    }
-  }
-
-  async sendTurn(input: CodexAppServerSendTurnInput): Promise<ProviderTurnStartResult> {
-    const context = this.requireSession(input.threadId);
-    context.collabReceiverTurns.clear();
-
-    const turnInput: Array<
-      { type: "text"; text: string; text_elements: [] } | { type: "image"; url: string }
-    > = [];
-    if (input.input) {
-      turnInput.push({
-        type: "text",
-        text: input.input,
-        text_elements: [],
-      });
-    }
-    for (const attachment of input.attachments ?? []) {
-      if (attachment.type === "image") {
-        turnInput.push({
-          type: "image",
-          url: attachment.url,
-        });
-      }
-    }
-    if (turnInput.length === 0) {
-      throw new Error("Turn input must include text or attachments.");
-    }
-
-    const providerThreadId = readResumeThreadId({
-      threadId: context.session.threadId,
-      runtimeMode: context.session.runtimeMode,
-      resumeCursor: context.session.resumeCursor,
-    });
-    if (!providerThreadId) {
-      throw new Error("Session is missing provider resume thread id.");
-    }
-    const turnStartParams: {
-      threadId: string;
-      input: Array<
-        { type: "text"; text: string; text_elements: [] } | { type: "image"; url: string }
-      >;
-      model?: string;
-      serviceTier?: string | null;
-      effort?: string;
-      collaborationMode?: {
-        mode: "default" | "plan";
-        settings: {
-          model: string;
-          reasoning_effort: string;
-          developer_instructions: string;
-        };
-      };
-    } = {
-      threadId: providerThreadId,
-      input: turnInput,
-    };
-    const normalizedModel = resolveCodexModelForAccount(
-      normalizeCodexModelSlug(input.model ?? context.session.model),
-      context.account,
-    );
-    if (normalizedModel) {
-      turnStartParams.model = normalizedModel;
-    }
-    if (input.serviceTier !== undefined) {
-      turnStartParams.serviceTier = input.serviceTier;
-    }
-    if (input.effort) {
-      turnStartParams.effort = input.effort;
-    }
-    const collaborationMode = buildCodexCollaborationMode({
-      ...(input.interactionMode !== undefined ? { interactionMode: input.interactionMode } : {}),
-      ...(normalizedModel !== undefined ? { model: normalizedModel } : {}),
-      ...(input.effort !== undefined ? { effort: input.effort } : {}),
-    });
-    if (collaborationMode) {
-      if (!turnStartParams.model) {
-        turnStartParams.model = collaborationMode.settings.model;
-      }
-      turnStartParams.collaborationMode = collaborationMode;
-    }
-
-    const response = await this.sendRequest(context, "turn/start", turnStartParams);
-
-    const turn = this.readObject(this.readObject(response), "turn");
-    const turnIdRaw = this.readString(turn, "id");
-    if (!turnIdRaw) {
-      throw new Error("turn/start response did not include a turn id.");
-    }
-    const turnId = TurnId.make(turnIdRaw);
-
-    this.updateSession(context, {
-      status: "running",
-      activeTurnId: turnId,
-      ...(context.session.resumeCursor !== undefined
-        ? { resumeCursor: context.session.resumeCursor }
-        : {}),
-    });
-
-    return {
-      threadId: context.session.threadId,
-      turnId,
-      ...(context.session.resumeCursor !== undefined
-        ? { resumeCursor: context.session.resumeCursor }
-        : {}),
-    };
-  }
-
-  async interruptTurn(threadId: ThreadId, turnId?: TurnId): Promise<void> {
-    const context = this.requireSession(threadId);
-    const effectiveTurnId = turnId ?? context.session.activeTurnId;
-
-    const providerThreadId = readResumeThreadId({
-      threadId: context.session.threadId,
-      runtimeMode: context.session.runtimeMode,
-      resumeCursor: context.session.resumeCursor,
-    });
-    if (!effectiveTurnId || !providerThreadId) {
-      return;
-    }
-
-    await this.sendRequest(context, "turn/interrupt", {
-      threadId: providerThreadId,
-      turnId: effectiveTurnId,
-    });
-  }
-
-  async readThread(threadId: ThreadId): Promise<CodexThreadSnapshot> {
-    const context = this.requireSession(threadId);
-    const providerThreadId = readResumeThreadId({
-      threadId: context.session.threadId,
-      runtimeMode: context.session.runtimeMode,
-      resumeCursor: context.session.resumeCursor,
-    });
-    if (!providerThreadId) {
-      throw new Error("Session is missing a provider resume thread id.");
-    }
-
-    const response = await this.sendRequest(context, "thread/read", {
-      threadId: providerThreadId,
-      includeTurns: true,
-    });
-    return this.parseThreadSnapshot("thread/read", response);
-  }
-
-  async rollbackThread(threadId: ThreadId, numTurns: number): Promise<CodexThreadSnapshot> {
-    const context = this.requireSession(threadId);
-    const providerThreadId = readResumeThreadId({
-      threadId: context.session.threadId,
-      runtimeMode: context.session.runtimeMode,
-      resumeCursor: context.session.resumeCursor,
-    });
-    if (!providerThreadId) {
-      throw new Error("Session is missing a provider resume thread id.");
-    }
-    if (!Number.isInteger(numTurns) || numTurns < 1) {
-      throw new Error("numTurns must be an integer >= 1.");
-    }
-
-    const response = await this.sendRequest(context, "thread/rollback", {
-      threadId: providerThreadId,
-      numTurns,
-    });
-    this.updateSession(context, {
-      status: "ready",
-      activeTurnId: undefined,
-    });
-    return this.parseThreadSnapshot("thread/rollback", response);
-  }
-
-  async respondToRequest(
-    threadId: ThreadId,
-    requestId: ApprovalRequestId,
-    decision: ProviderApprovalDecision,
-  ): Promise<void> {
-    const context = this.requireSession(threadId);
-    const pendingRequest = context.pendingApprovals.get(requestId);
-    if (!pendingRequest) {
-      throw new Error(`Unknown pending approval request: ${requestId}`);
-    }
-
-    context.pendingApprovals.delete(requestId);
-    this.writeMessage(context, {
-      id: pendingRequest.jsonRpcId,
-      result: {
-        decision,
-      },
-    });
-
-    this.emitEvent({
-      id: EventId.make(randomUUID()),
-      kind: "notification",
-      provider: "codex",
-      threadId: context.session.threadId,
-      createdAt: new Date().toISOString(),
-      method: "item/requestApproval/decision",
-      turnId: pendingRequest.turnId,
-      itemId: pendingRequest.itemId,
-      requestId: pendingRequest.requestId,
-      requestKind: pendingRequest.requestKind,
-      payload: {
-        requestId: pendingRequest.requestId,
-        requestKind: pendingRequest.requestKind,
-        decision,
-      },
-    });
-  }
-
-  async respondToUserInput(
-    threadId: ThreadId,
-    requestId: ApprovalRequestId,
-    answers: ProviderUserInputAnswers,
-  ): Promise<void> {
-    const context = this.requireSession(threadId);
-    const pendingRequest = context.pendingUserInputs.get(requestId);
-    if (!pendingRequest) {
-      throw new Error(`Unknown pending user input request: ${requestId}`);
-    }
-
-    context.pendingUserInputs.delete(requestId);
-    const codexAnswers = toCodexUserInputAnswers(answers);
-    this.writeMessage(context, {
-      id: pendingRequest.jsonRpcId,
-      result: {
-        answers: codexAnswers,
-      },
-    });
-
-    this.emitEvent({
-      id: EventId.make(randomUUID()),
-      kind: "notification",
-      provider: "codex",
-      threadId: context.session.threadId,
-      createdAt: new Date().toISOString(),
-      method: "item/tool/requestUserInput/answered",
-      turnId: pendingRequest.turnId,
-      itemId: pendingRequest.itemId,
-      requestId: pendingRequest.requestId,
-      payload: {
-        requestId: pendingRequest.requestId,
-        answers: codexAnswers,
-      },
-    });
-  }
-
-  stopSession(threadId: ThreadId): void {
-    const context = this.sessions.get(threadId);
-    if (!context) {
-      return;
-    }
-
-    context.stopping = true;
-
-    for (const pending of context.pending.values()) {
-      clearTimeout(pending.timeout);
-      pending.reject(new Error("Session stopped before request completed."));
-    }
-    context.pending.clear();
-    context.pendingApprovals.clear();
-    context.pendingUserInputs.clear();
-
-    context.output.close();
-
-    if (!context.child.killed) {
-      killChildTree(context.child);
-    }
-
-    this.updateSession(context, {
-      status: "closed",
-      activeTurnId: undefined,
-    });
-    this.emitLifecycleEvent(context, "session/closed", "Session stopped");
-    this.sessions.delete(threadId);
-  }
-
-  listSessions(): ProviderSession[] {
-    return Array.from(this.sessions.values(), ({ session }) => ({
-      ...session,
-    }));
-  }
-
-  hasSession(threadId: ThreadId): boolean {
-    return this.sessions.has(threadId);
-  }
-
-  stopAll(): void {
-    for (const threadId of this.sessions.keys()) {
-      this.stopSession(threadId);
-    }
-  }
-
-  private requireSession(threadId: ThreadId): CodexSessionContext {
-    const context = this.sessions.get(threadId);
-    if (!context) {
-      throw new Error(`Unknown session for thread: ${threadId}`);
-    }
-
-    if (context.session.status === "closed") {
-      throw new Error(`Session is closed for thread: ${threadId}`);
-    }
-
-    return context;
-  }
-
-  private attachProcessListeners(context: CodexSessionContext): void {
-    context.output.on("line", (line) => {
-      this.handleStdoutLine(context, line);
-    });
-
-    context.child.stderr.on("data", (chunk: Buffer) => {
-      const raw = chunk.toString();
-      const lines = raw.split(/\r?\n/g);
-      for (const rawLine of lines) {
-        const classified = classifyCodexStderrLine(rawLine);
-        if (!classified) {
-          continue;
-        }
-
-        this.emitNotificationEvent(context, "process/stderr", classified.message);
-      }
-    });
-
-    context.child.on("error", (error) => {
-      const message = error.message || "codex app-server process errored.";
-      this.updateSession(context, {
-        status: "error",
-        lastError: message,
-      });
-      this.emitErrorEvent(context, "process/error", message);
-    });
-
-    context.child.on("exit", (code, signal) => {
-      if (context.stopping) {
-        return;
-      }
-
-      const message = `codex app-server exited (code=${code ?? "null"}, signal=${signal ?? "null"}).`;
-      this.updateSession(context, {
-        status: "closed",
-        activeTurnId: undefined,
-        lastError: code === 0 ? context.session.lastError : message,
-      });
-      this.emitLifecycleEvent(context, "session/exited", message);
-      this.sessions.delete(context.session.threadId);
-    });
-  }
-
-  private handleStdoutLine(context: CodexSessionContext, line: string): void {
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line);
-    } catch {
-      this.emitErrorEvent(
-        context,
-        "protocol/parseError",
-        "Received invalid JSON from codex app-server.",
-      );
-      return;
-    }
-
-    if (!parsed || typeof parsed !== "object") {
-      this.emitErrorEvent(
-        context,
-        "protocol/invalidMessage",
-        "Received non-object protocol message.",
-      );
-      return;
-    }
-
-    if (this.isServerRequest(parsed)) {
-      this.handleServerRequest(context, parsed);
-      return;
-    }
-
-    if (this.isServerNotification(parsed)) {
-      this.handleServerNotification(context, parsed);
-      return;
-    }
-
-    if (this.isResponse(parsed)) {
-      this.handleResponse(context, parsed);
-      return;
-    }
-
-    this.emitErrorEvent(
-      context,
-      "protocol/unrecognizedMessage",
-      "Received protocol message in an unknown shape.",
-    );
-  }
-
-  private handleServerNotification(
-    context: CodexSessionContext,
-    notification: JsonRpcNotification,
-  ): void {
-    const rawRoute = this.readRouteFields(notification.params);
-    this.rememberCollabReceiverTurns(context, notification.params, rawRoute.turnId);
-    const childParentTurnId = this.readChildParentTurnId(context, notification.params);
-    const isChildConversation = childParentTurnId !== undefined;
-    if (
-      isChildConversation &&
-      this.shouldSuppressChildConversationNotification(notification.method)
-    ) {
-      return;
-    }
-    const textDelta =
-      notification.method === "item/agentMessage/delta"
-        ? this.readString(notification.params, "delta")
-        : undefined;
-
-    this.emitEvent({
-      id: EventId.make(randomUUID()),
-      kind: "notification",
-      provider: "codex",
-      threadId: context.session.threadId,
-      createdAt: new Date().toISOString(),
-      method: notification.method,
-      ...((childParentTurnId ?? rawRoute.turnId)
-        ? { turnId: childParentTurnId ?? rawRoute.turnId }
-        : {}),
-      ...(rawRoute.itemId ? { itemId: rawRoute.itemId } : {}),
-      textDelta,
-      payload: notification.params,
-    });
-
-    if (notification.method === "thread/started") {
-      const providerThreadId = normalizeProviderThreadId(
-        this.readString(this.readObject(notification.params)?.thread, "id"),
-      );
-      if (providerThreadId) {
-        this.updateSession(context, { resumeCursor: { threadId: providerThreadId } });
-      }
-      return;
-    }
-
-    if (notification.method === "turn/started") {
-      if (isChildConversation) {
-        return;
-      }
-      const turnId = toTurnId(this.readString(this.readObject(notification.params)?.turn, "id"));
-      this.updateSession(context, {
-        status: "running",
-        activeTurnId: turnId,
-      });
-      return;
-    }
-
-    if (notification.method === "turn/completed") {
-      if (isChildConversation) {
-        return;
-      }
-      context.collabReceiverTurns.clear();
-      const turn = this.readObject(notification.params, "turn");
-      const status = this.readString(turn, "status");
-      const errorMessage = this.readString(this.readObject(turn, "error"), "message");
-      this.updateSession(context, {
-        status: status === "failed" ? "error" : "ready",
-        activeTurnId: undefined,
-        lastError: errorMessage ?? context.session.lastError,
-      });
-      return;
-    }
-
-    if (notification.method === "error") {
-      if (isChildConversation) {
-        return;
-      }
-      const message = this.readString(this.readObject(notification.params)?.error, "message");
-      const willRetry = this.readBoolean(notification.params, "willRetry");
-
-      this.updateSession(context, {
-        status: willRetry ? "running" : "error",
-        lastError: message ?? context.session.lastError,
-      });
-    }
-  }
-
-  private handleServerRequest(context: CodexSessionContext, request: JsonRpcRequest): void {
-    const rawRoute = this.readRouteFields(request.params);
-    const childParentTurnId = this.readChildParentTurnId(context, request.params);
-    const effectiveTurnId = childParentTurnId ?? rawRoute.turnId;
-    const requestKind = this.requestKindForMethod(request.method);
-    let requestId: ApprovalRequestId | undefined;
-    if (requestKind) {
-      requestId = ApprovalRequestId.make(randomUUID());
-      const pendingRequest: PendingApprovalRequest = {
-        requestId,
-        jsonRpcId: request.id,
-        method:
-          requestKind === "command"
-            ? "item/commandExecution/requestApproval"
-            : requestKind === "file-read"
-              ? "item/fileRead/requestApproval"
-              : "item/fileChange/requestApproval",
-        requestKind,
-        threadId: context.session.threadId,
-        ...(effectiveTurnId ? { turnId: effectiveTurnId } : {}),
-        ...(rawRoute.itemId ? { itemId: rawRoute.itemId } : {}),
-      };
-      context.pendingApprovals.set(requestId, pendingRequest);
-    }
-
-    if (request.method === "item/tool/requestUserInput") {
-      requestId = ApprovalRequestId.make(randomUUID());
-      context.pendingUserInputs.set(requestId, {
-        requestId,
-        jsonRpcId: request.id,
-        threadId: context.session.threadId,
-        ...(effectiveTurnId ? { turnId: effectiveTurnId } : {}),
-        ...(rawRoute.itemId ? { itemId: rawRoute.itemId } : {}),
-      });
-    }
-
-    this.emitEvent({
-      id: EventId.make(randomUUID()),
-      kind: "request",
-      provider: "codex",
-      threadId: context.session.threadId,
-      createdAt: new Date().toISOString(),
-      method: request.method,
-      ...(effectiveTurnId ? { turnId: effectiveTurnId } : {}),
-      ...(rawRoute.itemId ? { itemId: rawRoute.itemId } : {}),
-      requestId,
-      requestKind,
-      payload: request.params,
-    });
-
-    if (requestKind) {
-      return;
-    }
-
-    if (request.method === "item/tool/requestUserInput") {
-      return;
-    }
-
-    this.writeMessage(context, {
-      id: request.id,
-      error: {
-        code: -32601,
-        message: `Unsupported server request: ${request.method}`,
-      },
-    });
-  }
-
-  private handleResponse(context: CodexSessionContext, response: JsonRpcResponse): void {
-    const key = String(response.id);
-    const pending = context.pending.get(key);
-    if (!pending) {
-      return;
-    }
-
-    clearTimeout(pending.timeout);
-    context.pending.delete(key);
-
-    if (response.error?.message) {
-      pending.reject(new Error(`${pending.method} failed: ${String(response.error.message)}`));
-      return;
-    }
-
-    pending.resolve(response.result);
-  }
-
-  private async sendRequest<TResponse>(
-    context: CodexSessionContext,
-    method: string,
-    params: unknown,
-    timeoutMs = 20_000,
-  ): Promise<TResponse> {
-    const id = context.nextRequestId;
-    context.nextRequestId += 1;
-
-    const result = await new Promise<unknown>((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        context.pending.delete(String(id));
-        reject(new Error(`Timed out waiting for ${method}.`));
-      }, timeoutMs);
-
-      context.pending.set(String(id), {
-        method,
-        timeout,
-        resolve,
-        reject,
-      });
-      this.writeMessage(context, {
-        method,
-        id,
-        params,
-      });
-    });
-
-    return result as TResponse;
-  }
-
-  private writeMessage(context: CodexSessionContext, message: unknown): void {
-    const encoded = JSON.stringify(message);
-    if (!context.child.stdin.writable) {
-      throw new Error("Cannot write to codex app-server stdin.");
-    }
-
-    context.child.stdin.write(`${encoded}\n`);
-  }
-
-  private emitLifecycleEvent(context: CodexSessionContext, method: string, message: string): void {
-    this.emitEvent({
-      id: EventId.make(randomUUID()),
-      kind: "session",
-      provider: "codex",
-      threadId: context.session.threadId,
-      createdAt: new Date().toISOString(),
-      method,
-      message,
-    });
-  }
-
-  private emitErrorEvent(context: CodexSessionContext, method: string, message: string): void {
-    this.emitEvent({
-      id: EventId.make(randomUUID()),
-      kind: "error",
-      provider: "codex",
-      threadId: context.session.threadId,
-      createdAt: new Date().toISOString(),
-      method,
-      message,
-    });
-  }
-
-  private emitNotificationEvent(
-    context: CodexSessionContext,
-    method: string,
-    message: string,
-  ): void {
-    this.emitEvent({
-      id: EventId.make(randomUUID()),
-      kind: "notification",
-      provider: "codex",
-      threadId: context.session.threadId,
-      createdAt: new Date().toISOString(),
-      method,
-      message,
-    });
-  }
-
-  private emitEvent(event: ProviderEvent): void {
-    this.emit("event", event);
-  }
-
-  private assertSupportedCodexCliVersion(input: {
-    readonly binaryPath: string;
-    readonly cwd: string;
-    readonly homePath?: string;
-  }): void {
-    assertSupportedCodexCliVersion(input);
-  }
-
-  private updateSession(context: CodexSessionContext, updates: Partial<ProviderSession>): void {
-    context.session = {
-      ...context.session,
-      ...updates,
-      updatedAt: new Date().toISOString(),
-    };
-  }
-
-  private requestKindForMethod(method: string): ProviderRequestKind | undefined {
-    if (method === "item/commandExecution/requestApproval") {
-      return "command";
-    }
-
-    if (method === "item/fileRead/requestApproval") {
-      return "file-read";
-    }
-
-    if (method === "item/fileChange/requestApproval") {
-      return "file-change";
-    }
-
-    return undefined;
-  }
-
-  private parseThreadSnapshot(method: string, response: unknown): CodexThreadSnapshot {
-    const responseRecord = this.readObject(response);
-    const thread = this.readObject(responseRecord, "thread");
-    const threadIdRaw =
-      this.readString(thread, "id") ?? this.readString(responseRecord, "threadId");
-    if (!threadIdRaw) {
-      throw new Error(`${method} response did not include a thread id.`);
-    }
-    const turnsRaw =
-      this.readArray(thread, "turns") ?? this.readArray(responseRecord, "turns") ?? [];
-    const turns = turnsRaw.map((turnValue, index) => {
-      const turn = this.readObject(turnValue);
-      const turnIdRaw = this.readString(turn, "id") ?? `${threadIdRaw}:turn:${index + 1}`;
-      const turnId = TurnId.make(turnIdRaw);
-      const items = this.readArray(turn, "items") ?? [];
-      return {
-        id: turnId,
-        items,
-      };
-    });
-
-    return {
-      threadId: threadIdRaw,
-      turns,
-    };
-  }
-
-  private isServerRequest(value: unknown): value is JsonRpcRequest {
-    if (!value || typeof value !== "object") {
-      return false;
-    }
-
-    const candidate = value as Record<string, unknown>;
-    return (
-      typeof candidate.method === "string" &&
-      (typeof candidate.id === "string" || typeof candidate.id === "number")
-    );
-  }
-
-  private isServerNotification(value: unknown): value is JsonRpcNotification {
-    if (!value || typeof value !== "object") {
-      return false;
-    }
-
-    const candidate = value as Record<string, unknown>;
-    return typeof candidate.method === "string" && !("id" in candidate);
-  }
-
-  private isResponse(value: unknown): value is JsonRpcResponse {
-    if (!value || typeof value !== "object") {
-      return false;
-    }
-
-    const candidate = value as Record<string, unknown>;
-    const hasId = typeof candidate.id === "string" || typeof candidate.id === "number";
-    const hasMethod = typeof candidate.method === "string";
-    return hasId && !hasMethod;
-  }
-
-  private readRouteFields(params: unknown): {
-    turnId?: TurnId;
-    itemId?: ProviderItemId;
-  } {
-    const route: {
-      turnId?: TurnId;
-      itemId?: ProviderItemId;
-    } = {};
-
-    const turnId = toTurnId(
-      this.readString(params, "turnId") ?? this.readString(this.readObject(params, "turn"), "id"),
-    );
-    const itemId = toProviderItemId(
-      this.readString(params, "itemId") ?? this.readString(this.readObject(params, "item"), "id"),
-    );
-
-    if (turnId) {
-      route.turnId = turnId;
-    }
-
-    if (itemId) {
-      route.itemId = itemId;
-    }
-
-    return route;
-  }
-
-  private readProviderConversationId(params: unknown): string | undefined {
-    return (
-      this.readString(params, "threadId") ??
-      this.readString(this.readObject(params, "thread"), "id") ??
-      this.readString(params, "conversationId")
-    );
-  }
-
-  private readChildParentTurnId(context: CodexSessionContext, params: unknown): TurnId | undefined {
-    const providerConversationId = this.readProviderConversationId(params);
-    if (!providerConversationId) {
-      return undefined;
-    }
-    return context.collabReceiverTurns.get(providerConversationId);
-  }
-
-  private rememberCollabReceiverTurns(
-    context: CodexSessionContext,
-    params: unknown,
-    parentTurnId: TurnId | undefined,
-  ): void {
-    if (!parentTurnId) {
-      return;
-    }
-    const payload = this.readObject(params);
-    const item = this.readObject(payload, "item") ?? payload;
-    const itemType = this.readString(item, "type") ?? this.readString(item, "kind");
-    if (itemType !== "collabAgentToolCall") {
-      return;
-    }
-
-    const receiverThreadIds =
-      this.readArray(item, "receiverThreadIds")
-        ?.map((value) => (typeof value === "string" ? value : null))
-        .filter((value): value is string => value !== null) ?? [];
-    for (const receiverThreadId of receiverThreadIds) {
-      context.collabReceiverTurns.set(receiverThreadId, parentTurnId);
-    }
-  }
-
-  private shouldSuppressChildConversationNotification(method: string): boolean {
-    return (
-      method === "thread/started" ||
-      method === "thread/status/changed" ||
-      method === "thread/archived" ||
-      method === "thread/unarchived" ||
-      method === "thread/closed" ||
-      method === "thread/compacted" ||
-      method === "thread/name/updated" ||
-      method === "thread/tokenUsage/updated" ||
-      method === "turn/started" ||
-      method === "turn/completed" ||
-      method === "turn/aborted" ||
-      method === "turn/plan/updated" ||
-      method === "item/plan/delta"
-    );
-  }
-
-  private readObject(value: unknown, key?: string): Record<string, unknown> | undefined {
-    const target =
-      key === undefined
-        ? value
-        : value && typeof value === "object"
-          ? (value as Record<string, unknown>)[key]
-          : undefined;
-
-    if (!target || typeof target !== "object") {
-      return undefined;
-    }
-
-    return target as Record<string, unknown>;
-  }
-
-  private readArray(value: unknown, key?: string): unknown[] | undefined {
-    const target =
-      key === undefined
-        ? value
-        : value && typeof value === "object"
-          ? (value as Record<string, unknown>)[key]
-          : undefined;
-    return Array.isArray(target) ? target : undefined;
-  }
-
-  private readString(value: unknown, key: string): string | undefined {
-    if (!value || typeof value !== "object") {
-      return undefined;
-    }
-
-    const candidate = (value as Record<string, unknown>)[key];
-    return typeof candidate === "string" ? candidate : undefined;
-  }
-
-  private readBoolean(value: unknown, key: string): boolean | undefined {
-    if (!value || typeof value !== "object") {
-      return undefined;
-    }
-
-    const candidate = (value as Record<string, unknown>)[key];
-    return typeof candidate === "boolean" ? candidate : undefined;
-  }
-}
-
-function brandIfNonEmpty<T extends string>(
-  value: string | undefined,
-  maker: (value: string) => T,
-): T | undefined {
-  const normalized = value?.trim();
-  return normalized?.length ? maker(normalized) : undefined;
-}
-
-function normalizeProviderThreadId(value: string | undefined): string | undefined {
-  return brandIfNonEmpty(value, (normalized) => normalized);
-}
-
-function assertSupportedCodexCliVersion(input: {
-  readonly binaryPath: string;
-  readonly cwd: string;
-  readonly homePath?: string;
-}): void {
-  const result = spawnSync(input.binaryPath, ["--version"], {
-    cwd: input.cwd,
-    env: {
-      ...process.env,
-      ...(input.homePath ? { CODEX_HOME: input.homePath } : {}),
-    },
-    encoding: "utf8",
-    shell: process.platform === "win32",
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: CODEX_VERSION_CHECK_TIMEOUT_MS,
-    maxBuffer: 1024 * 1024,
-  });
-
-  if (result.error) {
-    const lower = result.error.message.toLowerCase();
-    if (
-      lower.includes("enoent") ||
-      lower.includes("command not found") ||
-      lower.includes("not found")
-    ) {
-      throw new Error(`Codex CLI (${input.binaryPath}) is not installed or not executable.`);
-    }
-    throw new Error(
-      `Failed to execute Codex CLI version check: ${result.error.message || String(result.error)}`,
-    );
-  }
-
-  const stdout = result.stdout ?? "";
-  const stderr = result.stderr ?? "";
-  if (result.status !== 0) {
-    const detail = stderr.trim() || stdout.trim() || `Command exited with code ${result.status}.`;
-    throw new Error(`Codex CLI version check failed. ${detail}`);
-  }
-
-  const parsedVersion = parseCodexCliVersion(`${stdout}\n${stderr}`);
-  if (parsedVersion && !isCodexCliVersionSupported(parsedVersion)) {
-    throw new Error(formatCodexCliUpgradeMessage(parsedVersion));
-  }
-}
-
-function readResumeCursorThreadId(resumeCursor: unknown): string | undefined {
-  if (!resumeCursor || typeof resumeCursor !== "object" || Array.isArray(resumeCursor)) {
-    return undefined;
-  }
-  const rawThreadId = (resumeCursor as Record<string, unknown>).threadId;
-  return typeof rawThreadId === "string" ? normalizeProviderThreadId(rawThreadId) : undefined;
-}
-
-function readResumeThreadId(input: {
-  readonly resumeCursor?: unknown;
-  readonly threadId?: ThreadId;
-  readonly runtimeMode?: RuntimeMode;
-}): string | undefined {
-  return readResumeCursorThreadId(input.resumeCursor);
-}
-
-function toTurnId(value: string | undefined): TurnId | undefined {
-  return brandIfNonEmpty(value, TurnId.make);
-}
-
-function toProviderItemId(value: string | undefined): ProviderItemId | undefined {
-  return brandIfNonEmpty(value, ProviderItemId.make);
-}
diff --git a/apps/server/src/config.ts b/apps/server/src/config.ts
index c2e5ecee459..b0a23cb273c 100644
--- a/apps/server/src/config.ts
+++ b/apps/server/src/config.ts
@@ -6,7 +6,13 @@
  *
  * @module ServerConfig
  */
-import { Effect, FileSystem, Layer, LogLevel, Path, Schema, Context } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as LogLevel from "effect/LogLevel";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
 
 export const DEFAULT_PORT = 3773;
 
@@ -24,6 +30,7 @@ export interface ServerDerivedPaths {
   readonly dbPath: string;
   readonly keybindingsConfigPath: string;
   readonly settingsPath: string;
+  readonly providerStatusCacheDir: string;
   readonly worktreesDir: string;
   readonly attachmentsDir: string;
   readonly logsDir: string;
@@ -64,6 +71,8 @@ export interface ServerConfigShape extends ServerDerivedPaths {
   readonly desktopBootstrapToken: string | undefined;
   readonly autoBootstrapProjectFromCwd: boolean;
   readonly logWebSocketEvents: boolean;
+  readonly tailscaleServeEnabled: boolean;
+  readonly tailscaleServePort: number;
 }
 
 export const deriveServerPaths = Effect.fn(function* (
@@ -76,11 +85,13 @@ export const deriveServerPaths = Effect.fn(function* (
   const attachmentsDir = join(stateDir, "attachments");
   const logsDir = join(stateDir, "logs");
   const providerLogsDir = join(logsDir, "provider");
+  const providerStatusCacheDir = join(baseDir, "caches");
   return {
     stateDir,
     dbPath,
     keybindingsConfigPath: join(stateDir, "keybindings.json"),
     settingsPath: join(stateDir, "settings.json"),
+    providerStatusCacheDir,
     worktreesDir: join(baseDir, "worktrees"),
     attachmentsDir,
     logsDir,
@@ -110,6 +121,7 @@ export const ensureServerDirectories = Effect.fn(function* (derivedPaths: Server
       fs.makeDirectory(derivedPaths.worktreesDir, { recursive: true }),
       fs.makeDirectory(path.dirname(derivedPaths.keybindingsConfigPath), { recursive: true }),
       fs.makeDirectory(path.dirname(derivedPaths.settingsPath), { recursive: true }),
+      fs.makeDirectory(derivedPaths.providerStatusCacheDir, { recursive: true }),
       fs.makeDirectory(path.dirname(derivedPaths.anonymousIdPath), { recursive: true }),
       fs.makeDirectory(path.dirname(derivedPaths.serverRuntimeStatePath), { recursive: true }),
     ],
@@ -154,6 +166,8 @@ export class ServerConfig extends Context.Service<ServerConfig, ServerConfigShap
           mode: "web",
           autoBootstrapProjectFromCwd: false,
           logWebSocketEvents: false,
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
           port: 0,
           host: undefined,
           desktopBootstrapToken: undefined,
diff --git a/apps/server/src/diagnostics/ProcessDiagnostics.test.ts b/apps/server/src/diagnostics/ProcessDiagnostics.test.ts
new file mode 100644
index 00000000000..18a54326de1
--- /dev/null
+++ b/apps/server/src/diagnostics/ProcessDiagnostics.test.ts
@@ -0,0 +1,252 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as ProcessDiagnostics from "./ProcessDiagnostics.ts";
+
+const encoder = new TextEncoder();
+
+function mockHandle(result: {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly code?: number;
+}) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(result.code ?? 0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: Sink.drain,
+    stdout: Stream.make(encoder.encode(result.stdout ?? "")),
+    stderr: Stream.make(encoder.encode(result.stderr ?? "")),
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+describe("ProcessDiagnostics", () => {
+  it.effect("parses POSIX ps rows with full commands", () =>
+    Effect.sync(() => {
+      const rows = ProcessDiagnostics.parsePosixProcessRows(
+        [
+          "  10     1    10 Ss      0.0   1024   01:02.03 /usr/bin/node server.js",
+          "  11    10    10 S+     12.5  20480      00:04 codex app-server --config /tmp/one two",
+        ].join("\n"),
+      );
+
+      expect(rows).toEqual([
+        {
+          pid: 10,
+          ppid: 1,
+          pgid: 10,
+          status: "Ss",
+          cpuPercent: 0,
+          rssBytes: 1024 * 1024,
+          elapsed: "01:02.03",
+          command: "/usr/bin/node server.js",
+        },
+        {
+          pid: 11,
+          ppid: 10,
+          pgid: 10,
+          status: "S+",
+          cpuPercent: 12.5,
+          rssBytes: 20480 * 1024,
+          elapsed: "00:04",
+          command: "codex app-server --config /tmp/one two",
+        },
+      ]);
+    }),
+  );
+
+  it.effect("aggregates only descendants of the server process", () =>
+    Effect.sync(() => {
+      const diagnostics = ProcessDiagnostics.aggregateProcessDiagnostics({
+        serverPid: 100,
+        readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
+        rows: [
+          {
+            pid: 100,
+            ppid: 1,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 0,
+            rssBytes: 1_000,
+            elapsed: "01:00",
+            command: "t3 server",
+          },
+          {
+            pid: 101,
+            ppid: 100,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 1.5,
+            rssBytes: 2_000,
+            elapsed: "00:20",
+            command: "codex app-server",
+          },
+          {
+            pid: 102,
+            ppid: 101,
+            pgid: 100,
+            status: "R",
+            cpuPercent: 3.25,
+            rssBytes: 4_000,
+            elapsed: "00:05",
+            command: "git status",
+          },
+          {
+            pid: 200,
+            ppid: 1,
+            pgid: 200,
+            status: "S",
+            cpuPercent: 99,
+            rssBytes: 8_000,
+            elapsed: "00:01",
+            command: "unrelated",
+          },
+          {
+            pid: 201,
+            ppid: 100,
+            pgid: 100,
+            status: "R",
+            cpuPercent: 9,
+            rssBytes: 9_000,
+            elapsed: "00:00",
+            command: "ps -axo pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=",
+          },
+        ],
+      });
+
+      expect(diagnostics.serverPid).toBe(100);
+      expect(DateTime.formatIso(diagnostics.readAt)).toBe("2026-05-05T10:00:00.000Z");
+      expect(diagnostics.processCount).toBe(2);
+      expect(diagnostics.totalRssBytes).toBe(6_000);
+      expect(diagnostics.totalCpuPercent).toBe(4.75);
+      expect(diagnostics.processes.map((process) => process.pid)).toEqual([101, 102]);
+      expect(diagnostics.processes.map((process) => process.depth)).toEqual([0, 1]);
+      expect(Option.getOrNull(diagnostics.processes[0]!.pgid)).toBe(100);
+      expect(diagnostics.processes[0]?.childPids).toEqual([102]);
+    }),
+  );
+
+  it.effect("preserves ascending sibling order for nested descendants", () =>
+    Effect.sync(() => {
+      const diagnostics = ProcessDiagnostics.aggregateProcessDiagnostics({
+        serverPid: 100,
+        readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
+        rows: [
+          {
+            pid: 101,
+            ppid: 100,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 0,
+            rssBytes: 100,
+            elapsed: "00:10",
+            command: "agent",
+          },
+          {
+            pid: 103,
+            ppid: 101,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 0,
+            rssBytes: 100,
+            elapsed: "00:10",
+            command: "child-b",
+          },
+          {
+            pid: 102,
+            ppid: 101,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 0,
+            rssBytes: 100,
+            elapsed: "00:10",
+            command: "child-a",
+          },
+        ],
+      });
+
+      expect(diagnostics.processes.map((process) => process.pid)).toEqual([101, 102, 103]);
+    }),
+  );
+
+  it.effect("queries processes through the ChildProcessSpawner service", () =>
+    Effect.gen(function* () {
+      const commands: Array<{ readonly command: string; readonly args: ReadonlyArray<string> }> =
+        [];
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make((command) => {
+          const childProcess = command as unknown as {
+            readonly command: string;
+            readonly args: ReadonlyArray<string>;
+          };
+          commands.push({ command: childProcess.command, args: childProcess.args });
+          return Effect.succeed(
+            mockHandle({
+              stdout: [
+                ` ${process.pid}     1 ${process.pid} Ss 0.0 1024 01:02.03 t3 server`,
+                ` 4242 ${process.pid} ${process.pid} S  1.5 2048 00:04 agent`,
+              ].join("\n"),
+            }),
+          );
+        }),
+      );
+      const layer = ProcessDiagnostics.layer.pipe(Layer.provide(spawnerLayer));
+
+      const diagnostics = yield* Effect.service(ProcessDiagnostics.ProcessDiagnostics).pipe(
+        Effect.flatMap((pd) => pd.read),
+        Effect.provide(layer),
+      );
+
+      expect(diagnostics.processes.map((process) => process.pid)).toEqual([4242]);
+      expect(commands).toEqual([
+        {
+          command: "ps",
+          args: ["-axo", "pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command="],
+        },
+      ]);
+    }),
+  );
+
+  it.effect("does not allow signaling the diagnostics query process", () =>
+    Effect.gen(function* () {
+      const spawnerLayer = Layer.succeed(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make(() =>
+          Effect.succeed(
+            mockHandle({
+              stdout: [
+                ` ${process.pid}     1 ${process.pid} Ss 0.0 1024 01:02.03 t3 server`,
+                ` 4242 ${process.pid} ${process.pid} R  1.5 2048 00:00 ps -axo pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=`,
+              ].join("\n"),
+            }),
+          ),
+        ),
+      );
+      const layer = ProcessDiagnostics.layer.pipe(Layer.provide(spawnerLayer));
+
+      const result = yield* Effect.service(ProcessDiagnostics.ProcessDiagnostics).pipe(
+        Effect.flatMap((pd) => pd.signal({ pid: 4242, signal: "SIGINT" })),
+        Effect.provide(layer),
+      );
+
+      expect(result).toEqual({
+        pid: 4242,
+        signal: "SIGINT",
+        signaled: false,
+        message: Option.some("Process 4242 is not a live descendant of the T3 server."),
+      });
+    }),
+  );
+});
diff --git a/apps/server/src/diagnostics/ProcessDiagnostics.ts b/apps/server/src/diagnostics/ProcessDiagnostics.ts
new file mode 100644
index 00000000000..f56bf216513
--- /dev/null
+++ b/apps/server/src/diagnostics/ProcessDiagnostics.ts
@@ -0,0 +1,462 @@
+import type {
+  ServerProcessDiagnosticsEntry,
+  ServerProcessDiagnosticsResult,
+  ServerProcessSignal,
+  ServerSignalProcessResult,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
+
+export interface ProcessRow {
+  readonly pid: number;
+  readonly ppid: number;
+  readonly pgid: number | null;
+  readonly status: string;
+  readonly cpuPercent: number;
+  readonly rssBytes: number;
+  readonly elapsed: string;
+  readonly command: string;
+}
+
+const PROCESS_QUERY_TIMEOUT_MS = 1_000;
+const POSIX_PROCESS_QUERY_COMMAND = "pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=";
+const PROCESS_QUERY_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+export interface ProcessDiagnosticsShape {
+  readonly read: Effect.Effect<ServerProcessDiagnosticsResult>;
+  readonly signal: (input: {
+    readonly pid: number;
+    readonly signal: ServerProcessSignal;
+  }) => Effect.Effect<ServerSignalProcessResult>;
+}
+
+export class ProcessDiagnostics extends Context.Service<
+  ProcessDiagnostics,
+  ProcessDiagnosticsShape
+>()("t3/diagnostics/ProcessDiagnostics") {}
+
+class ProcessDiagnosticsError extends Schema.TaggedErrorClass<ProcessDiagnosticsError>()(
+  "ProcessDiagnosticsError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {}
+const isProcessDiagnosticsError = Schema.is(ProcessDiagnosticsError);
+
+function toProcessDiagnosticsError(message: string, cause?: unknown): ProcessDiagnosticsError {
+  return new ProcessDiagnosticsError({
+    message,
+    ...(cause === undefined ? {} : { cause }),
+  });
+}
+
+function parsePositiveInt(value: string): number | null {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parseNonNegativeInt(value: string): number | null {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+
+function parseNumber(value: string): number | null {
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function parsePosixProcessRows(output: string): ReadonlyArray<ProcessRow> {
+  const rows: ProcessRow[] = [];
+  const rowPattern =
+    /^\s*(\d+)\s+(\d+)\s+(-?\d+)\s+(\S+)\s+([+-]?(?:\d+\.?\d*|\.\d+))\s+(\d+)\s+(\S+)\s+(.+)$/;
+
+  for (const line of output.split(/\r?\n/)) {
+    if (line.trim().length === 0) continue;
+
+    const match = rowPattern.exec(line);
+    if (!match) continue;
+
+    const pidText = match[1];
+    const ppidText = match[2];
+    const pgidText = match[3];
+    const status = match[4];
+    const cpuText = match[5];
+    const rssText = match[6];
+    const elapsed = match[7];
+    const command = match[8];
+    if (
+      pidText === undefined ||
+      ppidText === undefined ||
+      pgidText === undefined ||
+      status === undefined ||
+      cpuText === undefined ||
+      rssText === undefined ||
+      elapsed === undefined ||
+      command === undefined
+    ) {
+      continue;
+    }
+
+    const pid = parsePositiveInt(pidText);
+    const ppid = parseNonNegativeInt(ppidText);
+    const pgid = Number.parseInt(pgidText, 10);
+    const cpuPercent = parseNumber(cpuText);
+    const rssKiB = parseNonNegativeInt(rssText);
+    if (
+      pid === null ||
+      ppid === null ||
+      !Number.isInteger(pgid) ||
+      cpuPercent === null ||
+      rssKiB === null ||
+      !status ||
+      !elapsed ||
+      !command
+    ) {
+      continue;
+    }
+
+    rows.push({
+      pid,
+      ppid,
+      pgid,
+      status,
+      cpuPercent,
+      rssBytes: rssKiB * 1024,
+      elapsed,
+      command,
+    });
+  }
+
+  return rows;
+}
+
+function normalizeWindowsProcessRow(value: unknown): ProcessRow | null {
+  if (typeof value !== "object" || value === null) return null;
+  const record = value as Record<string, unknown>;
+  const pid = typeof record.ProcessId === "number" ? record.ProcessId : null;
+  const ppid = typeof record.ParentProcessId === "number" ? record.ParentProcessId : null;
+  const commandLine =
+    typeof record.CommandLine === "string" && record.CommandLine.trim().length > 0
+      ? record.CommandLine
+      : typeof record.Name === "string"
+        ? record.Name
+        : null;
+  const workingSet =
+    typeof record.WorkingSetSize === "number" && Number.isFinite(record.WorkingSetSize)
+      ? Math.max(0, Math.round(record.WorkingSetSize))
+      : 0;
+  const cpuPercent =
+    typeof record.PercentProcessorTime === "number" && Number.isFinite(record.PercentProcessorTime)
+      ? Math.max(0, record.PercentProcessorTime)
+      : 0;
+
+  if (!pid || pid <= 0 || ppid === null || ppid < 0 || !commandLine) return null;
+  return {
+    pid,
+    ppid,
+    pgid: null,
+    status: typeof record.Status === "string" && record.Status.length > 0 ? record.Status : "Live",
+    cpuPercent,
+    rssBytes: workingSet,
+    elapsed: "",
+    command: commandLine,
+  };
+}
+
+function parseWindowsProcessRows(output: string): ReadonlyArray<ProcessRow> {
+  if (output.trim().length === 0) return [];
+  try {
+    const parsed = JSON.parse(output) as unknown;
+    const records = Array.isArray(parsed) ? parsed : [parsed];
+    return records.flatMap((record) => {
+      const row = normalizeWindowsProcessRow(record);
+      return row ? [row] : [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+export function buildDescendantEntries(
+  rows: ReadonlyArray<ProcessRow>,
+  serverPid: number,
+): ReadonlyArray<ServerProcessDiagnosticsEntry> {
+  const childrenByParent = new Map<number, ProcessRow[]>();
+  for (const row of rows) {
+    const children = childrenByParent.get(row.ppid) ?? [];
+    children.push(row);
+    childrenByParent.set(row.ppid, children);
+  }
+
+  const entries: ServerProcessDiagnosticsEntry[] = [];
+  const visited = new Set<number>();
+  const stack = [...(childrenByParent.get(serverPid) ?? [])]
+    .toSorted((left, right) => left.pid - right.pid)
+    .map((row) => ({ row, depth: 0 }));
+
+  while (stack.length > 0) {
+    const item = stack.shift();
+    if (!item || visited.has(item.row.pid)) continue;
+    visited.add(item.row.pid);
+
+    const children = [...(childrenByParent.get(item.row.pid) ?? [])].toSorted(
+      (left, right) => left.pid - right.pid,
+    );
+    entries.push({
+      pid: item.row.pid,
+      ppid: item.row.ppid,
+      pgid: Option.fromNullishOr(item.row.pgid),
+      status: item.row.status,
+      cpuPercent: item.row.cpuPercent,
+      rssBytes: item.row.rssBytes,
+      elapsed: item.row.elapsed || "n/a",
+      command: item.row.command,
+      depth: item.depth,
+      childPids: children.map((child) => child.pid),
+    });
+
+    stack.unshift(...children.map((row) => ({ row, depth: item.depth + 1 })));
+  }
+
+  return entries;
+}
+
+export function isDiagnosticsQueryProcess(row: ProcessRow, serverPid: number): boolean {
+  if (row.ppid !== serverPid) return false;
+
+  const command = row.command.trim();
+  return (
+    /(?:^|[/\\])ps\s+-axo\s+pid=,ppid=,pgid=,stat=,pcpu=,rss=,etime=,command=/.test(command) ||
+    (/\bpowershell(?:\.exe)?\b/i.test(command) &&
+      /\bGet-CimInstance\s+Win32_Process\b/i.test(command))
+  );
+}
+
+function makeResult(input: {
+  readonly serverPid: number;
+  readonly rows: ReadonlyArray<ProcessRow>;
+  readonly readAt: DateTime.Utc;
+  readonly error?: string;
+}): ServerProcessDiagnosticsResult {
+  const readAt = input.readAt;
+  const rows = input.rows.filter((row) => !isDiagnosticsQueryProcess(row, input.serverPid));
+  const processes = buildDescendantEntries(rows, input.serverPid);
+  const totalRssBytes = processes.reduce((total, process) => total + process.rssBytes, 0);
+  const totalCpuPercent = processes.reduce((total, process) => total + process.cpuPercent, 0);
+
+  return {
+    serverPid: input.serverPid,
+    readAt,
+    processCount: processes.length,
+    totalRssBytes,
+    totalCpuPercent,
+    processes,
+    error: input.error ? Option.some({ message: input.error }) : Option.none(),
+  };
+}
+
+interface ProcessOutput {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+const runProcess = Effect.fn("runProcess")(
+  function* (input: {
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    readonly errorMessage: string;
+  }) {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const child = yield* spawner.spawn(
+      ChildProcess.make(input.command, input.args, {
+        cwd: process.cwd(),
+        shell: process.platform === "win32",
+      }),
+    );
+    const [stdout, stderr, exitCode] = yield* Effect.all(
+      [
+        collectUint8StreamText({
+          stream: child.stdout,
+          maxBytes: PROCESS_QUERY_MAX_OUTPUT_BYTES,
+          truncatedMarker: "\n\n[truncated]",
+        }),
+        collectUint8StreamText({
+          stream: child.stderr,
+          maxBytes: PROCESS_QUERY_MAX_OUTPUT_BYTES,
+          truncatedMarker: "\n\n[truncated]",
+        }),
+        child.exitCode,
+      ],
+      { concurrency: "unbounded" },
+    );
+
+    return {
+      exitCode,
+      stdout: stdout.text,
+      stderr: stderr.text,
+    } satisfies ProcessOutput;
+  },
+  (effect, input) =>
+    effect.pipe(
+      Effect.scoped,
+      Effect.timeoutOption(Duration.millis(PROCESS_QUERY_TIMEOUT_MS)),
+      Effect.flatMap((result) =>
+        Option.match(result, {
+          onNone: () => Effect.fail(toProcessDiagnosticsError(`${input.errorMessage} timed out.`)),
+          onSome: Effect.succeed,
+        }),
+      ),
+      Effect.mapError((cause) =>
+        isProcessDiagnosticsError(cause)
+          ? cause
+          : toProcessDiagnosticsError(input.errorMessage, cause),
+      ),
+    ),
+);
+
+function readPosixProcessRows(): Effect.Effect<
+  ReadonlyArray<ProcessRow>,
+  ProcessDiagnosticsError,
+  ChildProcessSpawner.ChildProcessSpawner
+> {
+  return runProcess({
+    command: "ps",
+    args: ["-axo", POSIX_PROCESS_QUERY_COMMAND],
+    errorMessage: "Failed to query process diagnostics.",
+  }).pipe(
+    Effect.flatMap((result) =>
+      result.exitCode !== 0
+        ? Effect.fail(toProcessDiagnosticsError(result.stderr.trim() || "ps failed."))
+        : Effect.succeed(parsePosixProcessRows(result.stdout)),
+    ),
+  );
+}
+
+function readWindowsProcessRows(): Effect.Effect<
+  ReadonlyArray<ProcessRow>,
+  ProcessDiagnosticsError,
+  ChildProcessSpawner.ChildProcessSpawner
+> {
+  const command = [
+    "$processes = Get-CimInstance Win32_Process | ForEach-Object {",
+    '$perf = Get-CimInstance Win32_PerfFormattedData_PerfProc_Process -Filter "IDProcess = $($_.ProcessId)" -ErrorAction SilentlyContinue;',
+    "[pscustomobject]@{ ProcessId = $_.ProcessId; ParentProcessId = $_.ParentProcessId; Name = $_.Name; CommandLine = $_.CommandLine; Status = $_.Status; WorkingSetSize = $_.WorkingSetSize; PercentProcessorTime = if ($perf) { $perf.PercentProcessorTime } else { 0 } }",
+    "};",
+    "$processes | ConvertTo-Json -Compress -Depth 3",
+  ].join(" ");
+
+  return runProcess({
+    command: "powershell.exe",
+    args: ["-NoProfile", "-NonInteractive", "-Command", command],
+    errorMessage: "Failed to query process diagnostics.",
+  }).pipe(
+    Effect.flatMap((result) =>
+      result.exitCode !== 0
+        ? Effect.fail(
+            toProcessDiagnosticsError(result.stderr.trim() || "PowerShell process query failed."),
+          )
+        : Effect.succeed(parseWindowsProcessRows(result.stdout)),
+    ),
+  );
+}
+
+export const readProcessRows = (platform = process.platform) =>
+  platform === "win32" ? readWindowsProcessRows() : readPosixProcessRows();
+
+export function aggregateProcessDiagnostics(input: {
+  readonly serverPid: number;
+  readonly rows: ReadonlyArray<ProcessRow>;
+  readonly readAt: DateTime.Utc;
+}): ServerProcessDiagnosticsResult {
+  return makeResult(input);
+}
+
+function assertDescendantPid(
+  pid: number,
+): Effect.Effect<void, ProcessDiagnosticsError, ChildProcessSpawner.ChildProcessSpawner> {
+  if (pid === process.pid) {
+    return Effect.fail(toProcessDiagnosticsError("Refusing to signal the T3 server process."));
+  }
+
+  return readProcessRows().pipe(
+    Effect.flatMap((rows) => {
+      const filteredRows = rows.filter((row) => !isDiagnosticsQueryProcess(row, process.pid));
+      const descendant = buildDescendantEntries(filteredRows, process.pid).some(
+        (entry) => entry.pid === pid,
+      );
+      return descendant
+        ? Effect.void
+        : Effect.fail(
+            toProcessDiagnosticsError(`Process ${pid} is not a live descendant of the T3 server.`),
+          );
+    }),
+  );
+}
+
+export const make = Effect.fn("makeProcessDiagnostics")(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+  const read: ProcessDiagnosticsShape["read"] = Effect.gen(function* () {
+    const readAt = yield* DateTime.now;
+    const rows = yield* readProcessRows().pipe(
+      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+    );
+    return makeResult({ serverPid: process.pid, rows, readAt });
+  }).pipe(
+    Effect.catch((error: ProcessDiagnosticsError) =>
+      DateTime.now.pipe(
+        Effect.map((readAt) =>
+          makeResult({ serverPid: process.pid, rows: [], readAt, error: error.message }),
+        ),
+      ),
+    ),
+  );
+
+  const signal: ProcessDiagnosticsShape["signal"] = Effect.fn("ProcessDiagnostics.signal")(
+    function* (input) {
+      return yield* assertDescendantPid(input.pid).pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+        Effect.flatMap(() =>
+          Effect.try({
+            try: () => {
+              process.kill(input.pid, input.signal);
+              return {
+                pid: input.pid,
+                signal: input.signal,
+                signaled: true,
+                message: Option.none(),
+              };
+            },
+            catch: (cause) =>
+              toProcessDiagnosticsError(
+                `Failed to signal process ${input.pid} with ${input.signal}.`,
+                cause,
+              ),
+          }),
+        ),
+        Effect.catch((error: ProcessDiagnosticsError) =>
+          Effect.succeed({
+            pid: input.pid,
+            signal: input.signal,
+            signaled: false,
+            message: Option.some(error.message),
+          }),
+        ),
+      );
+    },
+  );
+
+  return ProcessDiagnostics.of({ read, signal });
+});
+
+export const layer = Layer.effect(ProcessDiagnostics, make());
diff --git a/apps/server/src/diagnostics/ProcessResourceMonitor.test.ts b/apps/server/src/diagnostics/ProcessResourceMonitor.test.ts
new file mode 100644
index 00000000000..11d12c012db
--- /dev/null
+++ b/apps/server/src/diagnostics/ProcessResourceMonitor.test.ts
@@ -0,0 +1,231 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+
+import {
+  aggregateProcessResourceHistory,
+  collectMonitoredSamples,
+} from "./ProcessResourceMonitor.ts";
+
+describe("ProcessResourceMonitor", () => {
+  it.effect("samples the server root process and descendants", () =>
+    Effect.sync(() => {
+      const sampledAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
+      const samples = collectMonitoredSamples({
+        serverPid: 100,
+        sampledAt,
+        sampledAtMs: DateTime.toEpochMillis(sampledAt),
+        rows: [
+          {
+            pid: 100,
+            ppid: 1,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 2,
+            rssBytes: 1_000,
+            elapsed: "01:00",
+            command: "t3 server",
+          },
+          {
+            pid: 101,
+            ppid: 100,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 10,
+            rssBytes: 2_000,
+            elapsed: "00:20",
+            command: "codex app-server",
+          },
+          {
+            pid: 102,
+            ppid: 101,
+            pgid: 100,
+            status: "R",
+            cpuPercent: 50,
+            rssBytes: 3_000,
+            elapsed: "00:05",
+            command: "rg needle",
+          },
+          {
+            pid: 200,
+            ppid: 1,
+            pgid: 200,
+            status: "R",
+            cpuPercent: 99,
+            rssBytes: 9_000,
+            elapsed: "00:05",
+            command: "unrelated",
+          },
+        ],
+      });
+
+      expect(samples.map((sample) => sample.pid)).toEqual([100, 101, 102]);
+      expect(samples.map((sample) => sample.depth)).toEqual([0, 1, 2]);
+      expect(samples[0]?.isServerRoot).toBe(true);
+      expect(samples[1]?.isServerRoot).toBe(false);
+    }),
+  );
+
+  it.effect("rolls samples up by process and CPU time", () =>
+    Effect.sync(() => {
+      const firstAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
+      const secondAt = DateTime.makeUnsafe("2026-05-05T10:00:05.000Z");
+      const samples = [
+        ...collectMonitoredSamples({
+          serverPid: 100,
+          sampledAt: firstAt,
+          sampledAtMs: DateTime.toEpochMillis(firstAt),
+          rows: [
+            {
+              pid: 100,
+              ppid: 1,
+              pgid: 100,
+              status: "S",
+              cpuPercent: 10,
+              rssBytes: 1_000,
+              elapsed: "01:00",
+              command: "t3 server",
+            },
+          ],
+        }),
+        ...collectMonitoredSamples({
+          serverPid: 100,
+          sampledAt: secondAt,
+          sampledAtMs: DateTime.toEpochMillis(secondAt),
+          rows: [
+            {
+              pid: 100,
+              ppid: 1,
+              pgid: 100,
+              status: "S",
+              cpuPercent: 30,
+              rssBytes: 2_000,
+              elapsed: "01:05",
+              command: "t3 server",
+            },
+          ],
+        }),
+      ];
+
+      const result = aggregateProcessResourceHistory({
+        samples,
+        readAt: secondAt,
+        readAtMs: DateTime.toEpochMillis(secondAt),
+        windowMs: 60_000,
+        bucketMs: 10_000,
+        lastError: null,
+      });
+
+      expect(Option.isNone(result.error)).toBe(true);
+      expect(result.topProcesses).toHaveLength(1);
+      expect(result.topProcesses[0]?.avgCpuPercent).toBe(20);
+      expect(result.topProcesses[0]?.maxCpuPercent).toBe(30);
+      expect(result.topProcesses[0]?.cpuSecondsApprox).toBe(2);
+      expect(result.totalCpuSecondsApprox).toBe(2);
+      expect(result.buckets.some((bucket) => bucket.maxCpuPercent === 30)).toBe(true);
+    }),
+  );
+
+  it.effect("keeps a process grouped when elapsed time drifts between samples", () =>
+    Effect.sync(() => {
+      const firstAt = DateTime.makeUnsafe("2026-05-05T10:00:00.400Z");
+      const secondAt = DateTime.makeUnsafe("2026-05-05T10:00:05.900Z");
+      const samples = [
+        ...collectMonitoredSamples({
+          serverPid: 100,
+          sampledAt: firstAt,
+          sampledAtMs: DateTime.toEpochMillis(firstAt),
+          rows: [
+            {
+              pid: 100,
+              ppid: 1,
+              pgid: 100,
+              status: "S",
+              cpuPercent: 1,
+              rssBytes: 1_000,
+              elapsed: "01:00",
+              command: "t3 server",
+            },
+          ],
+        }),
+        ...collectMonitoredSamples({
+          serverPid: 100,
+          sampledAt: secondAt,
+          sampledAtMs: DateTime.toEpochMillis(secondAt),
+          rows: [
+            {
+              pid: 100,
+              ppid: 1,
+              pgid: 100,
+              status: "S",
+              cpuPercent: 2,
+              rssBytes: 2_000,
+              elapsed: "01:06",
+              command: "t3 server",
+            },
+          ],
+        }),
+      ];
+
+      const result = aggregateProcessResourceHistory({
+        samples,
+        readAt: secondAt,
+        readAtMs: DateTime.toEpochMillis(secondAt),
+        windowMs: 60_000,
+        bucketMs: 10_000,
+        lastError: null,
+      });
+
+      expect(result.topProcesses).toHaveLength(1);
+      expect(result.topProcesses[0]?.isServerRoot).toBe(true);
+      expect(result.topProcesses[0]?.sampleCount).toBe(2);
+      expect(result.topProcesses[0]?.maxRssBytes).toBe(2_000);
+    }),
+  );
+
+  it.effect("returns all process summaries in the selected window", () =>
+    Effect.sync(() => {
+      const sampledAt = DateTime.makeUnsafe("2026-05-05T10:00:00.000Z");
+      const samples = collectMonitoredSamples({
+        serverPid: 100,
+        sampledAt,
+        sampledAtMs: DateTime.toEpochMillis(sampledAt),
+        rows: [
+          {
+            pid: 100,
+            ppid: 1,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 1,
+            rssBytes: 1_000,
+            elapsed: "01:00",
+            command: "t3 server",
+          },
+          ...Array.from({ length: 35 }, (_, index) => ({
+            pid: 200 + index,
+            ppid: index === 0 ? 100 : 199 + index,
+            pgid: 100,
+            status: "S",
+            cpuPercent: 35 - index,
+            rssBytes: 2_000 + index,
+            elapsed: "00:10",
+            command: `worker ${index}`,
+          })),
+        ],
+      });
+
+      const result = aggregateProcessResourceHistory({
+        samples,
+        readAt: sampledAt,
+        readAtMs: DateTime.toEpochMillis(sampledAt),
+        windowMs: 60_000,
+        bucketMs: 10_000,
+        lastError: null,
+      });
+
+      expect(result.topProcesses).toHaveLength(36);
+      expect(result.topProcesses.some((process) => process.command === "worker 34")).toBe(true);
+    }),
+  );
+});
diff --git a/apps/server/src/diagnostics/ProcessResourceMonitor.ts b/apps/server/src/diagnostics/ProcessResourceMonitor.ts
new file mode 100644
index 00000000000..2b6dfe8d362
--- /dev/null
+++ b/apps/server/src/diagnostics/ProcessResourceMonitor.ts
@@ -0,0 +1,299 @@
+import type {
+  ServerProcessResourceHistoryBucket,
+  ServerProcessResourceHistoryInput,
+  ServerProcessResourceHistoryResult,
+  ServerProcessResourceHistorySummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  buildDescendantEntries,
+  isDiagnosticsQueryProcess,
+  type ProcessRow,
+  readProcessRows,
+} from "./ProcessDiagnostics.ts";
+
+const SAMPLE_INTERVAL_MS = 5_000;
+const RETENTION_MS = 60 * 60_000;
+const MAX_RETAINED_SAMPLES = 20_000;
+
+export interface ProcessResourceSample {
+  readonly sampledAt: DateTime.Utc;
+  readonly sampledAtMs: number;
+  readonly processKey: string;
+  readonly pid: number;
+  readonly ppid: number;
+  readonly command: string;
+  readonly cpuPercent: number;
+  readonly rssBytes: number;
+  readonly depth: number;
+  readonly isServerRoot: boolean;
+}
+
+interface MonitorState {
+  readonly samples: ReadonlyArray<ProcessResourceSample>;
+  readonly lastError: string | null;
+}
+
+export interface ProcessResourceMonitorShape {
+  readonly readHistory: (
+    input: ServerProcessResourceHistoryInput,
+  ) => Effect.Effect<ServerProcessResourceHistoryResult>;
+}
+
+export class ProcessResourceMonitor extends Context.Service<
+  ProcessResourceMonitor,
+  ProcessResourceMonitorShape
+>()("t3/diagnostics/ProcessResourceMonitor") {}
+
+function dateTimeFromMillis(ms: number): DateTime.Utc {
+  return DateTime.makeUnsafe(ms);
+}
+
+function sampleKey(row: Pick<ProcessRow, "pid" | "command">): string {
+  return `${row.pid}:${row.command}`;
+}
+
+function findServerRootRow(rows: ReadonlyArray<ProcessRow>, serverPid: number): ProcessRow | null {
+  return rows.find((row) => row.pid === serverPid) ?? null;
+}
+
+export function collectMonitoredSamples(input: {
+  readonly rows: ReadonlyArray<ProcessRow>;
+  readonly serverPid: number;
+  readonly sampledAt: DateTime.Utc;
+  readonly sampledAtMs: number;
+}): ReadonlyArray<ProcessResourceSample> {
+  const rows = input.rows.filter((row) => !isDiagnosticsQueryProcess(row, input.serverPid));
+  const root = findServerRootRow(rows, input.serverPid);
+  const descendants = buildDescendantEntries(rows, input.serverPid);
+  const samples: ProcessResourceSample[] = [];
+
+  if (root) {
+    samples.push({
+      sampledAt: input.sampledAt,
+      sampledAtMs: input.sampledAtMs,
+      processKey: sampleKey(root),
+      pid: root.pid,
+      ppid: root.ppid,
+      command: root.command,
+      cpuPercent: root.cpuPercent,
+      rssBytes: root.rssBytes,
+      depth: 0,
+      isServerRoot: true,
+    });
+  }
+
+  for (const process of descendants) {
+    samples.push({
+      sampledAt: input.sampledAt,
+      sampledAtMs: input.sampledAtMs,
+      processKey: sampleKey(process),
+      pid: process.pid,
+      ppid: process.ppid,
+      command: process.command,
+      cpuPercent: process.cpuPercent,
+      rssBytes: process.rssBytes,
+      depth: process.depth + 1,
+      isServerRoot: false,
+    });
+  }
+
+  return samples;
+}
+
+function trimSamples(
+  samples: ReadonlyArray<ProcessResourceSample>,
+  nowMs: number,
+): ReadonlyArray<ProcessResourceSample> {
+  const minSampledAtMs = nowMs - RETENTION_MS;
+  const retained = samples.filter((sample) => sample.sampledAtMs >= minSampledAtMs);
+  return retained.length <= MAX_RETAINED_SAMPLES
+    ? retained
+    : retained.slice(retained.length - MAX_RETAINED_SAMPLES);
+}
+
+function summarizeProcesses(
+  samples: ReadonlyArray<ProcessResourceSample>,
+): ReadonlyArray<ServerProcessResourceHistorySummary> {
+  const groups = new Map<string, ProcessResourceSample[]>();
+  for (const sample of samples) {
+    const processSamples = groups.get(sample.processKey) ?? [];
+    processSamples.push(sample);
+    groups.set(sample.processKey, processSamples);
+  }
+
+  return [...groups.entries()]
+    .map(([processKey, processSamples]) => {
+      const sorted = processSamples.toSorted((left, right) => left.sampledAtMs - right.sampledAtMs);
+      const first = sorted[0]!;
+      const latest = sorted[sorted.length - 1]!;
+      const cpuPercentTotal = sorted.reduce((total, sample) => total + sample.cpuPercent, 0);
+      const maxCpuPercent = Math.max(...sorted.map((sample) => sample.cpuPercent));
+      const maxRssBytes = Math.max(...sorted.map((sample) => sample.rssBytes));
+      const cpuSecondsApprox = sorted.reduce(
+        (total, sample) => total + (sample.cpuPercent / 100) * (SAMPLE_INTERVAL_MS / 1_000),
+        0,
+      );
+
+      return {
+        processKey,
+        pid: latest.pid,
+        ppid: latest.ppid,
+        command: latest.command,
+        depth: latest.depth,
+        isServerRoot: latest.isServerRoot,
+        firstSeenAt: first.sampledAt,
+        lastSeenAt: latest.sampledAt,
+        currentCpuPercent: latest.cpuPercent,
+        avgCpuPercent: cpuPercentTotal / sorted.length,
+        maxCpuPercent,
+        cpuSecondsApprox,
+        currentRssBytes: latest.rssBytes,
+        maxRssBytes,
+        sampleCount: sorted.length,
+      } satisfies ServerProcessResourceHistorySummary;
+    })
+    .toSorted((left, right) => right.cpuSecondsApprox - left.cpuSecondsApprox);
+}
+
+function buildBuckets(input: {
+  readonly samples: ReadonlyArray<ProcessResourceSample>;
+  readonly nowMs: number;
+  readonly windowMs: number;
+  readonly bucketMs: number;
+}): ReadonlyArray<ServerProcessResourceHistoryBucket> {
+  const bucketMs = Math.max(1_000, input.bucketMs);
+  const windowStartMs = input.nowMs - input.windowMs;
+  const buckets: ServerProcessResourceHistoryBucket[] = [];
+
+  for (let startedAtMs = windowStartMs; startedAtMs < input.nowMs; startedAtMs += bucketMs) {
+    const endedAtMs = Math.min(input.nowMs, startedAtMs + bucketMs);
+    const bucketSamples = input.samples.filter(
+      (sample) =>
+        sample.sampledAtMs >= startedAtMs &&
+        (endedAtMs === input.nowMs
+          ? sample.sampledAtMs <= endedAtMs
+          : sample.sampledAtMs < endedAtMs),
+    );
+    const samplesByRead = new Map<number, ProcessResourceSample[]>();
+    for (const sample of bucketSamples) {
+      const samplesAtTime = samplesByRead.get(sample.sampledAtMs) ?? [];
+      samplesAtTime.push(sample);
+      samplesByRead.set(sample.sampledAtMs, samplesAtTime);
+    }
+
+    const readTotals = [...samplesByRead.values()].map((samplesAtTime) => ({
+      cpuPercent: samplesAtTime.reduce((total, sample) => total + sample.cpuPercent, 0),
+      rssBytes: samplesAtTime.reduce((total, sample) => total + sample.rssBytes, 0),
+      processCount: samplesAtTime.length,
+    }));
+    const avgCpuPercent =
+      readTotals.length === 0
+        ? 0
+        : readTotals.reduce((total, read) => total + read.cpuPercent, 0) / readTotals.length;
+
+    buckets.push({
+      startedAt: dateTimeFromMillis(startedAtMs),
+      endedAt: dateTimeFromMillis(endedAtMs),
+      avgCpuPercent,
+      maxCpuPercent: readTotals.length ? Math.max(...readTotals.map((read) => read.cpuPercent)) : 0,
+      maxRssBytes: readTotals.length ? Math.max(...readTotals.map((read) => read.rssBytes)) : 0,
+      maxProcessCount: readTotals.length
+        ? Math.max(...readTotals.map((read) => read.processCount))
+        : 0,
+    });
+  }
+
+  return buckets;
+}
+
+export function aggregateProcessResourceHistory(input: {
+  readonly samples: ReadonlyArray<ProcessResourceSample>;
+  readonly readAt: DateTime.Utc;
+  readonly readAtMs: number;
+  readonly windowMs: number;
+  readonly bucketMs: number;
+  readonly lastError: string | null;
+}): ServerProcessResourceHistoryResult {
+  const windowMs = Math.max(1_000, input.windowMs);
+  const bucketMs = Math.max(1_000, input.bucketMs);
+  const minSampledAtMs = input.readAtMs - windowMs;
+  const samples = input.samples.filter((sample) => sample.sampledAtMs >= minSampledAtMs);
+  const topProcesses = summarizeProcesses(samples);
+  const totalCpuSecondsApprox = samples.reduce(
+    (total, sample) => total + (sample.cpuPercent / 100) * (SAMPLE_INTERVAL_MS / 1_000),
+    0,
+  );
+
+  return {
+    readAt: input.readAt,
+    windowMs,
+    bucketMs,
+    sampleIntervalMs: SAMPLE_INTERVAL_MS,
+    retainedSampleCount: input.samples.length,
+    totalCpuSecondsApprox,
+    buckets: buildBuckets({ samples, nowMs: input.readAtMs, windowMs, bucketMs }),
+    topProcesses,
+    error: input.lastError ? Option.some({ message: input.lastError }) : Option.none(),
+  };
+}
+
+export const make = Effect.fn("makeProcessResourceMonitor")(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const state = yield* Ref.make<MonitorState>({ samples: [], lastError: null });
+
+  const sampleOnce = Effect.gen(function* () {
+    const sampledAt = yield* DateTime.now;
+    const sampledAtMs = DateTime.toEpochMillis(sampledAt);
+    const rows = yield* readProcessRows().pipe(
+      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+    );
+    const samples = collectMonitoredSamples({
+      rows,
+      serverPid: process.pid,
+      sampledAt,
+      sampledAtMs,
+    });
+    yield* Ref.update(state, (current) => ({
+      samples: trimSamples([...current.samples, ...samples], sampledAtMs),
+      lastError: null,
+    }));
+  }).pipe(
+    Effect.catch((error: unknown) =>
+      Ref.update(state, (current) => ({
+        ...current,
+        lastError: error instanceof Error ? error.message : "Failed to sample process resources.",
+      })),
+    ),
+  );
+
+  yield* Effect.forever(sampleOnce.pipe(Effect.andThen(Effect.sleep(SAMPLE_INTERVAL_MS)))).pipe(
+    Effect.forkScoped,
+  );
+
+  const readHistory: ProcessResourceMonitorShape["readHistory"] = (input) =>
+    Effect.gen(function* () {
+      const readAt = yield* DateTime.now;
+      const readAtMs = DateTime.toEpochMillis(readAt);
+      const current = yield* Ref.get(state);
+      return aggregateProcessResourceHistory({
+        samples: current.samples,
+        readAt,
+        readAtMs,
+        windowMs: input.windowMs,
+        bucketMs: input.bucketMs,
+        lastError: current.lastError,
+      });
+    });
+
+  return ProcessResourceMonitor.of({ readHistory });
+});
+
+export const layer = Layer.effect(ProcessResourceMonitor, make());
diff --git a/apps/server/src/diagnostics/TraceDiagnostics.test.ts b/apps/server/src/diagnostics/TraceDiagnostics.test.ts
new file mode 100644
index 00000000000..d4ffa4a5fc2
--- /dev/null
+++ b/apps/server/src/diagnostics/TraceDiagnostics.test.ts
@@ -0,0 +1,258 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+
+import * as TraceDiagnostics from "./TraceDiagnostics.ts";
+
+function ns(ms: number): string {
+  return String(BigInt(ms) * 1_000_000n);
+}
+
+function record(input: {
+  readonly name: string;
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly startMs: number;
+  readonly durationMs: number;
+  readonly exit?: { readonly _tag: "Success" | "Failure" | "Interrupted"; readonly cause?: string };
+  readonly events?: ReadonlyArray<unknown>;
+}) {
+  return JSON.stringify({
+    type: "effect-span",
+    name: input.name,
+    traceId: input.traceId,
+    spanId: input.spanId,
+    sampled: true,
+    kind: "internal",
+    startTimeUnixNano: ns(input.startMs),
+    endTimeUnixNano: ns(input.startMs + input.durationMs),
+    durationMs: input.durationMs,
+    attributes: {},
+    events: input.events ?? [],
+    links: [],
+    exit: input.exit ?? { _tag: "Success" },
+  });
+}
+
+describe("TraceDiagnostics", () => {
+  it.effect("aggregates failures, slow spans, log levels, and parse errors", () =>
+    Effect.sync(() => {
+      const diagnostics = TraceDiagnostics.aggregateTraceDiagnostics({
+        traceFilePath: "/tmp/server.trace.ndjson",
+        readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
+        slowSpanThresholdMs: 1_000,
+        files: [
+          {
+            path: "/tmp/server.trace.ndjson.1",
+            text: [
+              record({
+                name: "server.getConfig",
+                traceId: "trace-a",
+                spanId: "span-a",
+                startMs: 1_000,
+                durationMs: 50,
+              }),
+              "not-json",
+            ].join("\n"),
+          },
+          {
+            path: "/tmp/server.trace.ndjson",
+            text: [
+              record({
+                name: "orchestration.dispatch",
+                traceId: "trace-b",
+                spanId: "span-b",
+                startMs: 2_000,
+                durationMs: 1_500,
+                exit: { _tag: "Failure", cause: "Provider crashed" },
+                events: [
+                  {
+                    name: "provider failed",
+                    timeUnixNano: ns(3_400),
+                    attributes: { "effect.logLevel": "Error" },
+                  },
+                ],
+              }),
+              record({
+                name: "orchestration.dispatch",
+                traceId: "trace-c",
+                spanId: "span-c",
+                startMs: 4_000,
+                durationMs: 250,
+                exit: { _tag: "Failure", cause: "Provider crashed" },
+              }),
+              record({
+                name: "git.status",
+                traceId: "trace-d",
+                spanId: "span-d",
+                startMs: 5_000,
+                durationMs: 25,
+                exit: { _tag: "Interrupted", cause: "Interrupted" },
+                events: [
+                  {
+                    name: "status delayed",
+                    timeUnixNano: ns(5_010),
+                    attributes: { "effect.logLevel": "Warning" },
+                  },
+                ],
+              }),
+            ].join("\n"),
+          },
+        ],
+      });
+
+      assert.equal(diagnostics.recordCount, 4);
+      assert.equal(DateTime.formatIso(diagnostics.readAt), "2026-05-05T10:00:00.000Z");
+      assert.equal(
+        Option.match(diagnostics.firstSpanAt, {
+          onNone: () => null,
+          onSome: DateTime.formatIso,
+        }),
+        "1970-01-01T00:00:01.000Z",
+      );
+      assert.equal(
+        Option.match(diagnostics.lastSpanAt, {
+          onNone: () => null,
+          onSome: DateTime.formatIso,
+        }),
+        "1970-01-01T00:00:05.025Z",
+      );
+      assert.equal(diagnostics.parseErrorCount, 1);
+      assert.equal(diagnostics.failureCount, 2);
+      assert.equal(diagnostics.interruptionCount, 1);
+      assert.equal(diagnostics.slowSpanCount, 1);
+      assert.equal(diagnostics.logLevelCounts.Error, 1);
+      assert.equal(diagnostics.logLevelCounts.Warning, 1);
+      assert.equal(diagnostics.commonFailures[0]?.name, "orchestration.dispatch");
+      assert.equal(diagnostics.commonFailures[0]?.count, 2);
+      assert.equal(diagnostics.latestFailures[0]?.traceId, "trace-c");
+      assert.equal(diagnostics.slowestSpans[0]?.traceId, "trace-b");
+      assert.equal(diagnostics.latestWarningAndErrorLogs[0]?.message, "status delayed");
+      assert.equal(diagnostics.topSpansByCount[0]?.name, "orchestration.dispatch");
+    }),
+  );
+
+  it.effect("returns a not-found diagnostic when no files are available", () =>
+    Effect.sync(() => {
+      const diagnostics = TraceDiagnostics.aggregateTraceDiagnostics({
+        traceFilePath: "/tmp/missing.trace.ndjson",
+        readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
+        files: [],
+      });
+
+      assert.equal(diagnostics.recordCount, 0);
+      assert.equal(Option.getOrUndefined(diagnostics.error)?.kind, "trace-file-not-found");
+    }),
+  );
+
+  it.effect("preserves full failure causes and log messages", () =>
+    Effect.sync(() => {
+      const longCause = `VcsProcessSpawnError: ${"missing executable ".repeat(80)}`.trim();
+      const longMessage = `provider warning: ${"retrying command ".repeat(80)}`.trim();
+      const diagnostics = TraceDiagnostics.aggregateTraceDiagnostics({
+        traceFilePath: "/tmp/server.trace.ndjson",
+        readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
+        files: [
+          {
+            path: "/tmp/server.trace.ndjson",
+            text: record({
+              name: "VcsProcess.run",
+              traceId: "trace-long",
+              spanId: "span-long",
+              startMs: 1_000,
+              durationMs: 25,
+              exit: { _tag: "Failure", cause: longCause },
+              events: [
+                {
+                  name: longMessage,
+                  timeUnixNano: ns(1_010),
+                  attributes: { "effect.logLevel": "Warning" },
+                },
+              ],
+            }),
+          },
+        ],
+      });
+
+      assert.equal(diagnostics.latestFailures[0]?.cause, longCause);
+      assert.equal(diagnostics.commonFailures[0]?.cause, longCause);
+      assert.equal(diagnostics.latestWarningAndErrorLogs[0]?.message, longMessage);
+    }),
+  );
+
+  it.effect("keeps loaded trace data when one rotated trace file fails to read", () =>
+    Effect.gen(function* () {
+      const traceFilePath = "/tmp/server.trace.ndjson";
+      const fileSystemLayer = FileSystem.layerNoop({
+        readFileString: (path) =>
+          path === `${traceFilePath}.1`
+            ? Effect.fail(
+                PlatformError.systemError({
+                  _tag: "PermissionDenied",
+                  module: "FileSystem",
+                  method: "readFileString",
+                  description: "permission denied",
+                  pathOrDescriptor: path,
+                }),
+              )
+            : Effect.succeed(
+                record({
+                  name: "server.getConfig",
+                  traceId: "trace-a",
+                  spanId: "span-a",
+                  startMs: 1_000,
+                  durationMs: 50,
+                }),
+              ),
+      });
+
+      const diagnostics = yield* TraceDiagnostics.readTraceDiagnostics({
+        traceFilePath,
+        maxFiles: 1,
+        readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
+      }).pipe(Effect.provide(TraceDiagnostics.layer.pipe(Layer.provide(fileSystemLayer))));
+
+      assert.equal(diagnostics.recordCount, 1);
+      assert.equal(
+        Option.getOrElse(diagnostics.partialFailure, () => false),
+        true,
+      );
+      assert.equal(Option.getOrUndefined(diagnostics.error)?.kind, "trace-file-read-failed");
+      assert.deepStrictEqual(diagnostics.scannedFilePaths, [`${traceFilePath}.1`, traceFilePath]);
+    }),
+  );
+
+  it.effect("keeps only the slowest span occurrences while aggregating large inputs", () =>
+    Effect.sync(() => {
+      const diagnostics = TraceDiagnostics.aggregateTraceDiagnostics({
+        traceFilePath: "/tmp/server.trace.ndjson",
+        readAt: DateTime.makeUnsafe("2026-05-05T10:00:00.000Z"),
+        files: [
+          {
+            path: "/tmp/server.trace.ndjson",
+            text: Array.from({ length: 25 }, (_, index) =>
+              record({
+                name: `span-${index}`,
+                traceId: `trace-${index}`,
+                spanId: `span-${index}`,
+                startMs: index * 1_000,
+                durationMs: index,
+              }),
+            ).join("\n"),
+          },
+        ],
+      });
+
+      assert.equal(diagnostics.recordCount, 25);
+      assert.equal(diagnostics.slowestSpans.length, 10);
+      assert.deepStrictEqual(
+        diagnostics.slowestSpans.map((span) => span.durationMs),
+        [24, 23, 22, 21, 20, 19, 18, 17, 16, 15],
+      );
+    }),
+  );
+});
diff --git a/apps/server/src/diagnostics/TraceDiagnostics.ts b/apps/server/src/diagnostics/TraceDiagnostics.ts
new file mode 100644
index 00000000000..ff63410b9bc
--- /dev/null
+++ b/apps/server/src/diagnostics/TraceDiagnostics.ts
@@ -0,0 +1,461 @@
+import type {
+  ServerTraceDiagnosticsErrorKind,
+  ServerTraceDiagnosticsFailureSummary,
+  ServerTraceDiagnosticsLogEvent,
+  ServerTraceDiagnosticsRecentFailure,
+  ServerTraceDiagnosticsResult,
+  ServerTraceDiagnosticsSpanOccurrence,
+  ServerTraceDiagnosticsSpanSummary,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+
+interface TraceRecordLike {
+  readonly name?: unknown;
+  readonly traceId?: unknown;
+  readonly spanId?: unknown;
+  readonly startTimeUnixNano?: unknown;
+  readonly endTimeUnixNano?: unknown;
+  readonly durationMs?: unknown;
+  readonly exit?: unknown;
+  readonly events?: unknown;
+}
+
+interface TraceEventLike {
+  readonly name?: unknown;
+  readonly timeUnixNano?: unknown;
+  readonly attributes?: unknown;
+}
+
+export interface TraceDiagnosticsOptions {
+  readonly traceFilePath: string;
+  readonly maxFiles: number;
+  readonly slowSpanThresholdMs?: number;
+  readonly readAt?: DateTime.Utc;
+}
+
+export interface TraceDiagnosticsShape {
+  readonly read: (options: TraceDiagnosticsOptions) => Effect.Effect<ServerTraceDiagnosticsResult>;
+}
+
+export class TraceDiagnostics extends Context.Service<TraceDiagnostics, TraceDiagnosticsShape>()(
+  "t3/diagnostics/TraceDiagnostics",
+) {}
+
+interface TraceDiagnosticsInput {
+  readonly traceFilePath: string;
+  readonly files: ReadonlyArray<{ readonly path: string; readonly text: string }>;
+  readonly scannedFilePaths?: ReadonlyArray<string>;
+  readonly slowSpanThresholdMs?: number;
+  readonly readAt: DateTime.Utc;
+  readonly error?: TraceDiagnosticsErrorSummary;
+  readonly partialFailure?: boolean;
+}
+
+interface TraceDiagnosticsErrorSummary {
+  readonly kind: ServerTraceDiagnosticsErrorKind;
+  readonly message: string;
+}
+
+const DEFAULT_SLOW_SPAN_THRESHOLD_MS = 1_000;
+const TOP_LIMIT = 10;
+const RECENT_LIMIT = 20;
+function toRotatedTracePaths(traceFilePath: string, maxFiles: number): ReadonlyArray<string> {
+  const backupCount = Math.max(0, Math.floor(maxFiles));
+  const backups = Array.from(
+    { length: backupCount },
+    (_, index) => `${traceFilePath}.${backupCount - index}`,
+  );
+  return [...backups, traceFilePath];
+}
+
+function isRecordObject(value: unknown): value is TraceRecordLike {
+  return typeof value === "object" && value !== null;
+}
+
+function toStringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function toNumberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function unixNanoToDateTime(value: unknown): DateTime.Utc | null {
+  const text = toStringValue(value);
+  if (!text) return null;
+  try {
+    const millis = Number(BigInt(text) / 1_000_000n);
+    return Option.getOrNull(DateTime.make(millis));
+  } catch {
+    return null;
+  }
+}
+
+function readExitTag(exit: unknown): string | null {
+  if (!isRecordObject(exit) || !("_tag" in exit)) return null;
+  return toStringValue(exit._tag);
+}
+
+function readExitCause(exit: unknown): string {
+  if (!isRecordObject(exit) || !("cause" in exit)) return "Failure";
+  return toStringValue(exit.cause)?.trim() ?? "Failure";
+}
+
+function isTraceEvent(value: unknown): value is TraceEventLike {
+  return typeof value === "object" && value !== null;
+}
+
+function readEventAttributes(event: TraceEventLike): Readonly<Record<string, unknown>> {
+  return typeof event.attributes === "object" && event.attributes !== null
+    ? (event.attributes as Readonly<Record<string, unknown>>)
+    : {};
+}
+
+function makeEmptyDiagnostics(input: {
+  readonly traceFilePath: string;
+  readonly scannedFilePaths: ReadonlyArray<string>;
+  readonly readAt: DateTime.Utc;
+  readonly slowSpanThresholdMs: number;
+  readonly error?: TraceDiagnosticsErrorSummary;
+  readonly partialFailure?: boolean;
+}): ServerTraceDiagnosticsResult {
+  return {
+    traceFilePath: input.traceFilePath,
+    scannedFilePaths: [...input.scannedFilePaths],
+    readAt: input.readAt,
+    recordCount: 0,
+    parseErrorCount: 0,
+    firstSpanAt: Option.none(),
+    lastSpanAt: Option.none(),
+    failureCount: 0,
+    interruptionCount: 0,
+    slowSpanThresholdMs: input.slowSpanThresholdMs,
+    slowSpanCount: 0,
+    logLevelCounts: {},
+    topSpansByCount: [],
+    slowestSpans: [],
+    commonFailures: [],
+    latestFailures: [],
+    latestWarningAndErrorLogs: [],
+    partialFailure: input.partialFailure ? Option.some(true) : Option.none(),
+    error: Option.fromNullishOr(input.error),
+  };
+}
+
+function isNotFoundError(error: PlatformError.PlatformError): boolean {
+  return error.reason._tag === "NotFound";
+}
+
+function platformErrorMessage(error: PlatformError.PlatformError): string {
+  return error.message || String(error);
+}
+
+function insertBoundedSlowestSpan(
+  slowestSpans: ServerTraceDiagnosticsSpanOccurrence[],
+  span: ServerTraceDiagnosticsSpanOccurrence,
+): void {
+  if (
+    slowestSpans.length >= TOP_LIMIT &&
+    span.durationMs <= slowestSpans[slowestSpans.length - 1]!.durationMs
+  ) {
+    return;
+  }
+
+  slowestSpans.push(span);
+  slowestSpans.sort((left, right) => right.durationMs - left.durationMs);
+  if (slowestSpans.length > TOP_LIMIT) {
+    slowestSpans.length = TOP_LIMIT;
+  }
+}
+
+export function aggregateTraceDiagnostics(
+  input: TraceDiagnosticsInput,
+): ServerTraceDiagnosticsResult {
+  const readAt = input.readAt;
+  const slowSpanThresholdMs = input.slowSpanThresholdMs ?? DEFAULT_SLOW_SPAN_THRESHOLD_MS;
+  const scannedFilePaths = input.scannedFilePaths ?? input.files.map((file) => file.path);
+  if (input.files.length === 0) {
+    return makeEmptyDiagnostics({
+      traceFilePath: input.traceFilePath,
+      scannedFilePaths,
+      readAt,
+      slowSpanThresholdMs,
+      error: input.error ?? {
+        kind: "trace-file-not-found",
+        message: "No local trace files were found.",
+      },
+      ...(input.partialFailure ? { partialFailure: true } : {}),
+    });
+  }
+
+  let parseErrorCount = 0;
+  let recordCount = 0;
+  let failureCount = 0;
+  let interruptionCount = 0;
+  let slowSpanCount = 0;
+  let firstSpanAt: DateTime.Utc | null = null;
+  let lastSpanAt: DateTime.Utc | null = null;
+
+  const spansByName = new Map<
+    string,
+    { count: number; failureCount: number; totalDurationMs: number; maxDurationMs: number }
+  >();
+  const failuresByKey = new Map<string, ServerTraceDiagnosticsFailureSummary>();
+  const latestFailures: ServerTraceDiagnosticsRecentFailure[] = [];
+  const slowestSpans: ServerTraceDiagnosticsSpanOccurrence[] = [];
+  const latestWarningAndErrorLogs: ServerTraceDiagnosticsLogEvent[] = [];
+  const logLevelCounts: Record<string, number> = {};
+
+  for (const file of input.files) {
+    const lines = file.text.split(/\r?\n/);
+    for (const line of lines) {
+      if (line.trim().length === 0) continue;
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        parseErrorCount += 1;
+        continue;
+      }
+
+      if (!isRecordObject(parsed)) {
+        parseErrorCount += 1;
+        continue;
+      }
+
+      const name = toStringValue(parsed.name);
+      const traceId = toStringValue(parsed.traceId);
+      const spanId = toStringValue(parsed.spanId);
+      const durationMs = toNumberValue(parsed.durationMs);
+      const endedAt = unixNanoToDateTime(parsed.endTimeUnixNano);
+      const startedAt = unixNanoToDateTime(parsed.startTimeUnixNano);
+
+      if (!name || !traceId || !spanId || durationMs === null || !endedAt) {
+        parseErrorCount += 1;
+        continue;
+      }
+
+      recordCount += 1;
+      firstSpanAt =
+        startedAt && (firstSpanAt === null || DateTime.isLessThan(startedAt, firstSpanAt))
+          ? startedAt
+          : firstSpanAt;
+      lastSpanAt =
+        lastSpanAt === null || DateTime.isGreaterThan(endedAt, lastSpanAt) ? endedAt : lastSpanAt;
+
+      const exitTag = readExitTag(parsed.exit);
+      const isFailure = exitTag === "Failure";
+      const isInterrupted = exitTag === "Interrupted";
+      if (isFailure) failureCount += 1;
+      if (isInterrupted) interruptionCount += 1;
+
+      const spanSummary = spansByName.get(name) ?? {
+        count: 0,
+        failureCount: 0,
+        totalDurationMs: 0,
+        maxDurationMs: 0,
+      };
+      spanSummary.count += 1;
+      spanSummary.totalDurationMs += durationMs;
+      spanSummary.maxDurationMs = Math.max(spanSummary.maxDurationMs, durationMs);
+      if (isFailure) spanSummary.failureCount += 1;
+      spansByName.set(name, spanSummary);
+
+      const spanItem = { name, durationMs, endedAt, traceId, spanId };
+      if (durationMs >= slowSpanThresholdMs) {
+        slowSpanCount += 1;
+      }
+      insertBoundedSlowestSpan(slowestSpans, spanItem);
+
+      if (isFailure) {
+        const cause = readExitCause(parsed.exit);
+        latestFailures.push({ ...spanItem, cause });
+
+        const failureKey = `${name}\0${cause}`;
+        const existing = failuresByKey.get(failureKey);
+        const isLatestFailure = !existing || DateTime.isGreaterThan(endedAt, existing.lastSeenAt);
+        failuresByKey.set(failureKey, {
+          name,
+          cause,
+          count: (existing?.count ?? 0) + 1,
+          lastSeenAt: isLatestFailure ? endedAt : existing!.lastSeenAt,
+          traceId: isLatestFailure ? traceId : existing!.traceId,
+          spanId: isLatestFailure ? spanId : existing!.spanId,
+        });
+      }
+
+      if (Array.isArray(parsed.events)) {
+        for (const rawEvent of parsed.events) {
+          if (!isTraceEvent(rawEvent)) continue;
+          const attributes = readEventAttributes(rawEvent);
+          const level = toStringValue(attributes["effect.logLevel"]);
+          if (!level) continue;
+
+          logLevelCounts[level] = (logLevelCounts[level] ?? 0) + 1;
+          const normalizedLevel = level.toLowerCase();
+          if (
+            normalizedLevel !== "warning" &&
+            normalizedLevel !== "warn" &&
+            normalizedLevel !== "error" &&
+            normalizedLevel !== "fatal"
+          ) {
+            continue;
+          }
+
+          const seenAt = unixNanoToDateTime(rawEvent.timeUnixNano) ?? endedAt;
+          const message = toStringValue(rawEvent.name)?.trim() ?? "Log event";
+          latestWarningAndErrorLogs.push({
+            spanName: name,
+            level,
+            message,
+            seenAt,
+            traceId,
+            spanId,
+          });
+        }
+      }
+    }
+  }
+
+  const topSpansByCount: ServerTraceDiagnosticsSpanSummary[] = [...spansByName.entries()]
+    .map(([name, span]) => ({
+      name,
+      count: span.count,
+      failureCount: span.failureCount,
+      totalDurationMs: span.totalDurationMs,
+      averageDurationMs: span.count > 0 ? span.totalDurationMs / span.count : 0,
+      maxDurationMs: span.maxDurationMs,
+    }))
+    .toSorted((left, right) => right.count - left.count || right.maxDurationMs - left.maxDurationMs)
+    .slice(0, TOP_LIMIT);
+
+  return {
+    traceFilePath: input.traceFilePath,
+    scannedFilePaths,
+    readAt,
+    recordCount,
+    parseErrorCount,
+    firstSpanAt: Option.fromNullishOr(firstSpanAt),
+    lastSpanAt: Option.fromNullishOr(lastSpanAt),
+    failureCount,
+    interruptionCount,
+    slowSpanThresholdMs,
+    slowSpanCount,
+    logLevelCounts,
+    topSpansByCount,
+    slowestSpans,
+    commonFailures: [...failuresByKey.values()]
+      .toSorted(
+        (left, right) =>
+          right.count - left.count ||
+          DateTime.toEpochMillis(right.lastSeenAt) - DateTime.toEpochMillis(left.lastSeenAt),
+      )
+      .slice(0, TOP_LIMIT),
+    latestFailures: latestFailures
+      .toSorted(
+        (left, right) =>
+          DateTime.toEpochMillis(right.endedAt) - DateTime.toEpochMillis(left.endedAt),
+      )
+      .slice(0, RECENT_LIMIT),
+    latestWarningAndErrorLogs: latestWarningAndErrorLogs
+      .toSorted(
+        (left, right) => DateTime.toEpochMillis(right.seenAt) - DateTime.toEpochMillis(left.seenAt),
+      )
+      .slice(0, RECENT_LIMIT),
+    partialFailure: input.partialFailure ? Option.some(true) : Option.none(),
+    error: Option.fromNullishOr(input.error),
+  };
+}
+
+type TraceFileReadResult =
+  | { readonly _tag: "Loaded"; readonly path: string; readonly text: string }
+  | { readonly _tag: "Missing"; readonly path: string }
+  | { readonly _tag: "Failed"; readonly path: string; readonly message: string };
+
+function readTraceFile(
+  fileSystem: FileSystem.FileSystem,
+  path: string,
+): Effect.Effect<TraceFileReadResult> {
+  return fileSystem.readFileString(path).pipe(
+    Effect.map((text) => ({ _tag: "Loaded" as const, path, text })),
+    Effect.catch((error: PlatformError.PlatformError) =>
+      Effect.succeed(
+        isNotFoundError(error)
+          ? { _tag: "Missing" as const, path }
+          : { _tag: "Failed" as const, path, message: platformErrorMessage(error) },
+      ),
+    ),
+  );
+}
+
+export const make = Effect.fn("makeTraceDiagnostics")(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+
+  const read: TraceDiagnosticsShape["read"] = Effect.fn("TraceDiagnostics.read")(
+    function* (options) {
+      const readAt = options.readAt ?? (yield* DateTime.now);
+      const slowSpanThresholdMs = options.slowSpanThresholdMs ?? DEFAULT_SLOW_SPAN_THRESHOLD_MS;
+      const paths = toRotatedTracePaths(options.traceFilePath, options.maxFiles);
+      const results = yield* Effect.all(
+        paths.map((path) => readTraceFile(fileSystem, path)),
+        {
+          concurrency: 1,
+        },
+      );
+      const files = results.flatMap((result) =>
+        result._tag === "Loaded" ? [{ path: result.path, text: result.text }] : [],
+      );
+      const readFailure = results.find((result) => result._tag === "Failed");
+      const readFailureError = readFailure
+        ? ({
+            kind: "trace-file-read-failed",
+            message: readFailure.message.trim() || `Failed to read ${readFailure.path}.`,
+          } satisfies TraceDiagnosticsErrorSummary)
+        : undefined;
+
+      if (files.length === 0) {
+        return makeEmptyDiagnostics({
+          traceFilePath: options.traceFilePath,
+          scannedFilePaths: paths,
+          readAt,
+          slowSpanThresholdMs,
+          error:
+            readFailureError ??
+            ({
+              kind: "trace-file-not-found",
+              message: "No local trace files were found.",
+            } satisfies TraceDiagnosticsErrorSummary),
+        });
+      }
+
+      return aggregateTraceDiagnostics({
+        traceFilePath: options.traceFilePath,
+        files,
+        scannedFilePaths: paths,
+        readAt,
+        slowSpanThresholdMs,
+        ...(readFailureError ? { partialFailure: true, error: readFailureError } : {}),
+      });
+    },
+  );
+
+  return TraceDiagnostics.of({ read });
+});
+
+export const layer = Layer.effect(TraceDiagnostics, make());
+
+export function readTraceDiagnostics(
+  options: TraceDiagnosticsOptions,
+): Effect.Effect<ServerTraceDiagnosticsResult, never, TraceDiagnostics> {
+  return Effect.gen(function* () {
+    const diagnostics = yield* TraceDiagnostics;
+    return yield* diagnostics.read(options);
+  });
+}
diff --git a/apps/server/src/environment/Layers/ServerEnvironment.test.ts b/apps/server/src/environment/Layers/ServerEnvironment.test.ts
index b899a4f9870..6904c53c847 100644
--- a/apps/server/src/environment/Layers/ServerEnvironment.test.ts
+++ b/apps/server/src/environment/Layers/ServerEnvironment.test.ts
@@ -1,7 +1,12 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import * as nodePath from "node:path";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Effect, Exit, FileSystem, Layer, PlatformError } from "effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as PlatformError from "effect/PlatformError";
 
 import { deriveServerPaths, ServerConfig, type ServerConfigShape } from "../../config.ts";
 import { ServerEnvironment } from "../Services/ServerEnvironment.ts";
@@ -30,6 +35,8 @@ const makeServerConfig = Effect.fn(function* (baseDir: string) {
     mode: "web",
     autoBootstrapProjectFromCwd: false,
     logWebSocketEvents: false,
+    tailscaleServeEnabled: false,
+    tailscaleServePort: 443,
     port: 0,
     host: undefined,
     desktopBootstrapToken: undefined,
diff --git a/apps/server/src/environment/Layers/ServerEnvironment.ts b/apps/server/src/environment/Layers/ServerEnvironment.ts
index 506fc45af79..6972af9b3df 100644
--- a/apps/server/src/environment/Layers/ServerEnvironment.ts
+++ b/apps/server/src/environment/Layers/ServerEnvironment.ts
@@ -1,9 +1,14 @@
 import { EnvironmentId, type ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
-import { Effect, FileSystem, Layer, Path, Random } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Random from "effect/Random";
 
 import { ServerConfig } from "../../config.ts";
+import { layer as ProcessRunnerLive } from "../../processRunner.ts";
 import { ServerEnvironment, type ServerEnvironmentShape } from "../Services/ServerEnvironment.ts";
-import { version } from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json" with { type: "json" };
 import { resolveServerEnvironmentLabel } from "./ServerEnvironmentLabel.ts";
 
 function platformOs(): ExecutionEnvironmentDescriptor["platform"]["os"] {
@@ -77,7 +82,7 @@ export const makeServerEnvironment = Effect.fn("makeServerEnvironment")(function
       os: platformOs(),
       arch: platformArch(),
     },
-    serverVersion: version,
+    serverVersion: packageJson.version,
     capabilities: {
       repositoryIdentity: true,
     },
@@ -89,4 +94,6 @@ export const makeServerEnvironment = Effect.fn("makeServerEnvironment")(function
   } satisfies ServerEnvironmentShape;
 });
 
-export const ServerEnvironmentLive = Layer.effect(ServerEnvironment, makeServerEnvironment());
+export const ServerEnvironmentLive = Layer.effect(ServerEnvironment, makeServerEnvironment()).pipe(
+  Layer.provide(ProcessRunnerLive),
+);
diff --git a/apps/server/src/environment/Layers/ServerEnvironmentLabel.test.ts b/apps/server/src/environment/Layers/ServerEnvironmentLabel.test.ts
index 3d44713510b..1237b7022ba 100644
--- a/apps/server/src/environment/Layers/ServerEnvironmentLabel.test.ts
+++ b/apps/server/src/environment/Layers/ServerEnvironmentLabel.test.ts
@@ -1,19 +1,36 @@
 import { afterEach, describe, expect, it } from "@effect/vitest";
-import { Effect, FileSystem } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
 import { vi } from "vitest";
 
-vi.mock("../../processRunner.ts", () => ({
-  runProcess: vi.fn(),
-}));
-
-import { runProcess } from "../../processRunner.ts";
+import { ProcessRunner, ProcessSpawnError, type ProcessRunnerShape } from "../../processRunner.ts";
 import { resolveServerEnvironmentLabel } from "./ServerEnvironmentLabel.ts";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+const runMock = vi.fn<ProcessRunnerShape["run"]>();
 
-const mockedRunProcess = vi.mocked(runProcess);
+const ProcessRunnerTest = Layer.succeed(
+  ProcessRunner,
+  ProcessRunner.of({
+    run: (input) => runMock(input),
+  }),
+);
 const NoopFileSystemLayer = FileSystem.layerNoop({});
+const TestLayer = Layer.merge(NoopFileSystemLayer, ProcessRunnerTest);
+const LinuxMachineInfoLayer = Layer.merge(
+  ProcessRunnerTest,
+  FileSystem.layerNoop({
+    exists: (path) => Effect.succeed(path === "/etc/machine-info"),
+    readFileString: (path) =>
+      path === "/etc/machine-info"
+        ? Effect.succeed('PRETTY_HOSTNAME="Build Agent 01"\nICON_NAME="computer-vm"\n')
+        : Effect.succeed(""),
+  }),
+);
 
 afterEach(() => {
-  mockedRunProcess.mockReset();
+  runMock.mockReset();
 });
 
 describe("resolveServerEnvironmentLabel", () => {
@@ -23,7 +40,7 @@ describe("resolveServerEnvironmentLabel", () => {
         cwdBaseName: "t3code",
         platform: "win32",
         hostname: "macbook-pro",
-      }).pipe(Effect.provide(NoopFileSystemLayer));
+      }).pipe(Effect.provide(TestLayer));
 
       expect(result).toBe("macbook-pro");
     }),
@@ -31,25 +48,30 @@ describe("resolveServerEnvironmentLabel", () => {
 
   it.effect("prefers the macOS ComputerName", () =>
     Effect.gen(function* () {
-      mockedRunProcess.mockResolvedValueOnce({
-        stdout: " Julius's MacBook Pro \n",
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+      runMock.mockReturnValueOnce(
+        Effect.succeed({
+          stdout: " Julius's MacBook Pro \n",
+          stderr: "",
+          code: ChildProcessSpawner.ExitCode(0),
+          timedOut: false,
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        }),
+      );
 
       const result = yield* resolveServerEnvironmentLabel({
         cwdBaseName: "t3code",
         platform: "darwin",
         hostname: "macbook-pro",
-      }).pipe(Effect.provide(NoopFileSystemLayer));
+      }).pipe(Effect.provide(TestLayer));
 
       expect(result).toBe("Julius's MacBook Pro");
-      expect(mockedRunProcess).toHaveBeenCalledWith(
-        "scutil",
-        ["--get", "ComputerName"],
-        expect.objectContaining({ allowNonZeroExit: true }),
+      expect(runMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "scutil",
+          args: ["--get", "ComputerName"],
+          timeoutBehavior: "timedOutResult",
+        }),
       );
     }),
   );
@@ -60,44 +82,39 @@ describe("resolveServerEnvironmentLabel", () => {
         cwdBaseName: "t3code",
         platform: "linux",
         hostname: "buildbox",
-      }).pipe(
-        Effect.provide(
-          FileSystem.layerNoop({
-            exists: (path) => Effect.succeed(path === "/etc/machine-info"),
-            readFileString: (path) =>
-              path === "/etc/machine-info"
-                ? Effect.succeed('PRETTY_HOSTNAME="Build Agent 01"\nICON_NAME="computer-vm"\n')
-                : Effect.succeed(""),
-          }),
-        ),
-      );
+      }).pipe(Effect.provide(LinuxMachineInfoLayer));
 
       expect(result).toBe("Build Agent 01");
-      expect(mockedRunProcess).not.toHaveBeenCalled();
+      expect(runMock).not.toHaveBeenCalled();
     }),
   );
 
   it.effect("falls back to hostnamectl pretty hostname on Linux", () =>
     Effect.gen(function* () {
-      mockedRunProcess.mockResolvedValueOnce({
-        stdout: "CI Runner\n",
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+      runMock.mockReturnValueOnce(
+        Effect.succeed({
+          stdout: "CI Runner\n",
+          stderr: "",
+          code: ChildProcessSpawner.ExitCode(0),
+          timedOut: false,
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        }),
+      );
 
       const result = yield* resolveServerEnvironmentLabel({
         cwdBaseName: "t3code",
         platform: "linux",
         hostname: "runner-01",
-      }).pipe(Effect.provide(NoopFileSystemLayer));
+      }).pipe(Effect.provide(TestLayer));
 
       expect(result).toBe("CI Runner");
-      expect(mockedRunProcess).toHaveBeenCalledWith(
-        "hostnamectl",
-        ["--pretty"],
-        expect.objectContaining({ allowNonZeroExit: true }),
+      expect(runMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "hostnamectl",
+          args: ["--pretty"],
+          timeoutBehavior: "timedOutResult",
+        }),
       );
     }),
   );
@@ -108,7 +125,7 @@ describe("resolveServerEnvironmentLabel", () => {
         cwdBaseName: "t3code",
         platform: "win32",
         hostname: "JULIUS-LAPTOP",
-      }).pipe(Effect.provide(NoopFileSystemLayer));
+      }).pipe(Effect.provide(TestLayer));
 
       expect(result).toBe("JULIUS-LAPTOP");
     }),
@@ -116,13 +133,21 @@ describe("resolveServerEnvironmentLabel", () => {
 
   it.effect("falls back to the hostname when the friendly-label command is missing", () =>
     Effect.gen(function* () {
-      mockedRunProcess.mockRejectedValueOnce(new Error("spawn scutil ENOENT"));
+      runMock.mockReturnValueOnce(
+        Effect.fail(
+          new ProcessSpawnError({
+            command: "scutil",
+            args: ["--get", "ComputerName"],
+            cause: new Error("spawn scutil ENOENT"),
+          }),
+        ),
+      );
 
       const result = yield* resolveServerEnvironmentLabel({
         cwdBaseName: "t3code",
         platform: "darwin",
         hostname: "macbook-pro",
-      }).pipe(Effect.provide(NoopFileSystemLayer));
+      }).pipe(Effect.provide(TestLayer));
 
       expect(result).toBe("macbook-pro");
     }),
@@ -130,19 +155,22 @@ describe("resolveServerEnvironmentLabel", () => {
 
   it.effect("falls back to the cwd basename when the hostname is blank", () =>
     Effect.gen(function* () {
-      mockedRunProcess.mockResolvedValueOnce({
-        stdout: " ",
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+      runMock.mockReturnValueOnce(
+        Effect.succeed({
+          stdout: " ",
+          stderr: "",
+          code: ChildProcessSpawner.ExitCode(0),
+          timedOut: false,
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        }),
+      );
 
       const result = yield* resolveServerEnvironmentLabel({
         cwdBaseName: "t3code",
         platform: "linux",
         hostname: "   ",
-      }).pipe(Effect.provide(NoopFileSystemLayer));
+      }).pipe(Effect.provide(TestLayer));
 
       expect(result).toBe("t3code");
     }),
diff --git a/apps/server/src/environment/Layers/ServerEnvironmentLabel.ts b/apps/server/src/environment/Layers/ServerEnvironmentLabel.ts
index dc776583262..7dc6bc34a43 100644
--- a/apps/server/src/environment/Layers/ServerEnvironmentLabel.ts
+++ b/apps/server/src/environment/Layers/ServerEnvironmentLabel.ts
@@ -1,8 +1,10 @@
 import * as OS from "node:os";
 
-import { Effect, FileSystem } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
 
-import { runProcess } from "../../processRunner.ts";
+import { ProcessRunner } from "../../processRunner.ts";
 
 interface ResolveServerEnvironmentLabelInput {
   readonly cwdBaseName: string;
@@ -51,19 +53,21 @@ const runFriendlyLabelCommand = Effect.fn("runFriendlyLabelCommand")(function* (
   command: string,
   args: readonly string[],
 ) {
-  const result = yield* Effect.tryPromise({
-    try: () =>
-      runProcess(command, args, {
-        allowNonZeroExit: true,
-      }),
-    catch: () => null,
-  }).pipe(Effect.orElseSucceed(() => null));
-
-  if (!result || result.code !== 0) {
+  const processRunner = yield* ProcessRunner;
+  const result = yield* processRunner
+    .run({
+      command,
+      args,
+      timeoutBehavior: "timedOutResult",
+      shell: process.platform === "win32",
+    })
+    .pipe(Effect.option);
+
+  if (Option.isNone(result) || result.value.code !== 0) {
     return null;
   }
 
-  return normalizeLabel(result.stdout);
+  return normalizeLabel(result.value.stdout);
 });
 
 const resolveFriendlyHostLabel = Effect.fn("resolveFriendlyHostLabel")(function* (
diff --git a/apps/server/src/environment/Services/ServerEnvironment.ts b/apps/server/src/environment/Services/ServerEnvironment.ts
index 48586803332..1e6dea0d05f 100644
--- a/apps/server/src/environment/Services/ServerEnvironment.ts
+++ b/apps/server/src/environment/Services/ServerEnvironment.ts
@@ -1,6 +1,6 @@
 import type { EnvironmentId, ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 export interface ServerEnvironmentShape {
   readonly getEnvironmentId: Effect.Effect<EnvironmentId>;
diff --git a/apps/server/src/git/Layers/GitManager.test.ts b/apps/server/src/git/GitManager.test.ts
similarity index 85%
rename from apps/server/src/git/Layers/GitManager.test.ts
rename to apps/server/src/git/GitManager.test.ts
index fd991273d1a..530e0488cf3 100644
--- a/apps/server/src/git/Layers/GitManager.test.ts
+++ b/apps/server/src/git/GitManager.test.ts
@@ -1,10 +1,16 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, PlatformError, Scope } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as PlatformError from "effect/PlatformError";
+import * as Scope from "effect/Scope";
+import { ChildProcessSpawner } from "effect/unstable/process";
 import { expect } from "vitest";
 import type {
   GitActionProgressEvent,
@@ -13,24 +19,28 @@ import type {
   ThreadId,
 } from "@t3tools/contracts";
 
-import { GitCommandError, GitHubCliError, TextGenerationError } from "@t3tools/contracts";
-import { type GitManagerShape } from "../Services/GitManager.ts";
+import { GitCommandError, TextGenerationError } from "@t3tools/contracts";
+import { type GitManagerShape } from "./GitManager.ts";
 import {
+  GitHubCliError,
   type GitHubCliShape,
   type GitHubPullRequestSummary,
   GitHubCli,
-} from "../Services/GitHubCli.ts";
-import { type TextGenerationShape, TextGeneration } from "../Services/TextGeneration.ts";
-import { GitCoreLive } from "./GitCore.ts";
-import { GitCore } from "../Services/GitCore.ts";
+} from "../sourceControl/GitHubCli.ts";
+import { type TextGenerationShape, TextGeneration } from "../textGeneration/TextGeneration.ts";
+import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as GitHubSourceControlProvider from "../sourceControl/GitHubSourceControlProvider.ts";
+import * as SourceControlProviderRegistry from "../sourceControl/SourceControlProviderRegistry.ts";
 import { makeGitManager } from "./GitManager.ts";
-import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import { ServerConfig } from "../config.ts";
+import { ServerSettingsService } from "../serverSettings.ts";
 import {
   ProjectSetupScriptRunner,
+  ProjectSetupScriptRunnerError,
   type ProjectSetupScriptRunnerInput,
   type ProjectSetupScriptRunnerShape,
-} from "../../project/Services/ProjectSetupScriptRunner.ts";
+} from "../project/Services/ProjectSetupScriptRunner.ts";
 
 interface FakeGhScenario {
   prListSequence?: string[];
@@ -53,6 +63,16 @@ interface FakeGhScenario {
   failWith?: GitHubCliError;
 }
 
+function fakeGhOutput(stdout: string): VcsProcess.VcsProcessOutput {
+  return {
+    exitCode: ChildProcessSpawner.ExitCode(0),
+    stdout,
+    stderr: "",
+    stdoutTruncated: false,
+    stderrTruncated: false,
+  };
+}
+
 interface FakeGitTextGeneration {
   generateCommitMessage: (input: {
     cwd: string;
@@ -209,18 +229,27 @@ function runGit(
   args: readonly string[],
   allowNonZeroExit = false,
 ): Effect.Effect<
-  { readonly code: number; readonly stdout: string; readonly stderr: string },
+  {
+    readonly exitCode: GitVcsDriver.ExecuteGitResult["exitCode"];
+    readonly stdout: string;
+    readonly stderr: string;
+  },
   GitCommandError,
-  GitCore
+  GitVcsDriver.GitVcsDriver
 > {
   return Effect.gen(function* () {
-    const gitCore = yield* GitCore;
-    return yield* gitCore.execute({
+    const git = yield* GitVcsDriver.GitVcsDriver;
+    const result = yield* git.execute({
       operation: "GitManager.test.runGit",
       cwd,
       args,
       allowNonZeroExit,
     });
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
   });
 }
 
@@ -229,7 +258,7 @@ function initRepo(
 ): Effect.Effect<
   void,
   PlatformError.PlatformError | GitCommandError,
-  FileSystem.FileSystem | Scope.Scope | GitCore
+  FileSystem.FileSystem | Scope.Scope | GitVcsDriver.GitVcsDriver
 > {
   return Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
@@ -245,7 +274,7 @@ function initRepo(
 function createBareRemote(): Effect.Effect<
   string,
   PlatformError.PlatformError | GitCommandError,
-  FileSystem.FileSystem | Scope.Scope | GitCore
+  FileSystem.FileSystem | Scope.Scope | GitVcsDriver.GitVcsDriver
 > {
   return Effect.gen(function* () {
     const remoteDir = yield* makeTempDir("t3code-git-remote-");
@@ -259,7 +288,7 @@ function configureRemote(
   remoteName: string,
   remotePath: string,
   fetchNamespace: string,
-): Effect.Effect<void, GitCommandError, GitCore> {
+): Effect.Effect<void, GitCommandError, GitVcsDriver.GitVcsDriver> {
   return Effect.gen(function* () {
     yield* runGit(cwd, ["config", `remote.${remoteName}.url`, remotePath]);
     yield* runGit(cwd, [
@@ -271,6 +300,18 @@ function configureRemote(
   });
 }
 
+function configureVisibleRemoteUrlWithLocalRewrite(
+  cwd: string,
+  remoteName: string,
+  visibleUrl: string,
+  localRemotePath: string,
+): Effect.Effect<void, GitCommandError, GitVcsDriver.GitVcsDriver> {
+  return Effect.gen(function* () {
+    yield* runGit(cwd, ["config", `remote.${remoteName}.url`, visibleUrl]);
+    yield* runGit(cwd, ["config", `url.${localRemotePath}.insteadOf`, visibleUrl]);
+  });
+}
+
 function createTextGeneration(overrides: Partial<FakeGitTextGeneration> = {}): TextGenerationShape {
   const implementation: FakeGitTextGeneration = {
     generateCommitMessage: (input) =>
@@ -379,24 +420,15 @@ function createGitHubCliWithFakeGh(scenario: FakeGhScenario = {}): {
           ? scenario.prListByHeadSelector?.[headSelector]
           : undefined;
       const stdout = (mappedQueue ?? mappedStdout ?? prListQueue.shift() ?? "[]") + "\n";
-      return Effect.succeed({
-        stdout,
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+      return Effect.succeed(fakeGhOutput(stdout));
     }
 
     if (args[0] === "pr" && args[1] === "create") {
-      return Effect.succeed({
-        stdout:
+      return Effect.succeed(
+        fakeGhOutput(
           (scenario.createdPrUrl ?? "https://github.com/pingdotgg/codething-mvp/pull/101") + "\n",
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+        ),
+      );
     }
 
     if (args[0] === "pr" && args[1] === "view") {
@@ -408,8 +440,8 @@ function createGitHubCliWithFakeGh(scenario: FakeGhScenario = {}): {
         headRefName: "feature/pull-request",
         state: "open",
       };
-      return Effect.succeed({
-        stdout:
+      return Effect.succeed(
+        fakeGhOutput(
           JSON.stringify({
             ...pullRequest,
             ...(pullRequest.headRepositoryNameWithOwner
@@ -427,11 +459,8 @@ function createGitHubCliWithFakeGh(scenario: FakeGhScenario = {}): {
                 }
               : {}),
           }) + "\n",
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+        ),
+      );
     }
 
     if (args[0] === "pr" && args[1] === "checkout") {
@@ -453,13 +482,7 @@ function createGitHubCliWithFakeGh(scenario: FakeGhScenario = {}): {
               runGitSyncForFakeGh(input.cwd, ["checkout", "-b", headBranch]);
             }
           }
-          return {
-            stdout: "",
-            stderr: "",
-            code: 0,
-            signal: null,
-            timedOut: false,
-          };
+          return fakeGhOutput("");
         },
         catch: (error) =>
           isGitHubCliError(error)
@@ -486,26 +509,17 @@ function createGitHubCliWithFakeGh(scenario: FakeGhScenario = {}): {
             }),
           );
         }
-        return Effect.succeed({
-          stdout:
+        return Effect.succeed(
+          fakeGhOutput(
             JSON.stringify({
               nameWithOwner: repository,
               url: cloneUrls.url,
               sshUrl: cloneUrls.sshUrl,
             }) + "\n",
-          stderr: "",
-          code: 0,
-          signal: null,
-          timedOut: false,
-        });
+          ),
+        );
       }
-      return Effect.succeed({
-        stdout: `${scenario.defaultBranch ?? "main"}\n`,
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+      return Effect.succeed(fakeGhOutput(`${scenario.defaultBranch ?? "main"}\n`));
     }
 
     return Effect.fail(
@@ -584,6 +598,13 @@ function createGitHubCliWithFakeGh(scenario: FakeGhScenario = {}): {
           cwd: input.cwd,
           args: ["repo", "view", input.repository, "--json", "nameWithOwner,url,sshUrl"],
         }).pipe(Effect.map((result) => JSON.parse(result.stdout))),
+      createRepository: (input) =>
+        Effect.fail(
+          new GitHubCliError({
+            operation: "createRepository",
+            detail: `Unexpected repository create: ${input.repository}`,
+          }),
+        ),
       checkoutPullRequest: (input) =>
         execute({
           cwd: input.cwd,
@@ -639,13 +660,27 @@ function makeManager(input?: {
 
   const serverSettingsLayer = ServerSettingsService.layerTest();
 
-  const gitCoreLayer = GitCoreLive.pipe(
+  const vcsDriverLayer = GitVcsDriver.layer.pipe(
+    Layer.provideMerge(VcsProcess.layer),
     Layer.provideMerge(NodeServices.layer),
     Layer.provideMerge(ServerConfigLayer),
   );
+  const sourceControlRegistryLayer = Layer.effect(
+    SourceControlProviderRegistry.SourceControlProviderRegistry,
+    GitHubSourceControlProvider.make().pipe(
+      Effect.map((provider) =>
+        SourceControlProviderRegistry.SourceControlProviderRegistry.of({
+          get: () => Effect.succeed(provider),
+          resolveHandle: () => Effect.succeed({ provider, context: null }),
+          resolve: () => Effect.succeed(provider),
+          discover: Effect.succeed([]),
+        }),
+      ),
+      Effect.provide(Layer.succeed(GitHubCli, gitHubCli)),
+    ),
+  );
 
   const managerLayer = Layer.mergeAll(
-    Layer.succeed(GitHubCli, gitHubCli),
     Layer.succeed(TextGeneration, textGeneration),
     Layer.succeed(
       ProjectSetupScriptRunner,
@@ -653,9 +688,9 @@ function makeManager(input?: {
         runForThread: () => Effect.succeed({ status: "no-script" as const }),
       },
     ),
-    gitCoreLayer,
+    vcsDriverLayer,
     serverSettingsLayer,
-  ).pipe(Layer.provideMerge(NodeServices.layer));
+  ).pipe(Layer.provideMerge(sourceControlRegistryLayer), Layer.provideMerge(NodeServices.layer));
 
   return makeGitManager().pipe(
     Effect.provide(managerLayer),
@@ -665,8 +700,9 @@ function makeManager(input?: {
 
 const asThreadId = (threadId: string) => threadId as ThreadId;
 
-const GitManagerTestLayer = GitCoreLive.pipe(
+const GitManagerTestLayer = GitVcsDriver.layer.pipe(
   Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "t3-git-manager-test-" })),
+  Layer.provideMerge(VcsProcess.layer),
   Layer.provideMerge(NodeServices.layer),
 );
 
@@ -683,6 +719,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 13,
@@ -698,15 +735,15 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
 
       const status = yield* manager.status({ cwd: repoDir });
       expect(status.isRepo).toBe(true);
-      expect(status.hasOriginRemote).toBe(true);
-      expect(status.isDefaultBranch).toBe(false);
-      expect(status.branch).toBe("feature/status-open-pr");
+      expect(status.hasPrimaryRemote).toBe(true);
+      expect(status.isDefaultRef).toBe(false);
+      expect(status.refName).toBe("feature/status-open-pr");
       expect(status.pr).toEqual({
         number: 13,
         title: "Existing PR",
         url: "https://github.com/pingdotgg/codething-mvp/pull/13",
-        baseBranch: "main",
-        headBranch: "feature/status-open-pr",
+        baseRef: "main",
+        headRef: "feature/status-open-pr",
         state: "open",
       });
     }),
@@ -724,6 +761,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 14,
@@ -743,8 +781,8 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         number: 14,
         title: "Existing PR title",
         url: "https://github.com/pingdotgg/codething-mvp/pull/14",
-        baseBranch: "main",
-        headBranch: "feature/status-trimmed-pr",
+        baseRef: "main",
+        headRef: "feature/status-trimmed-pr",
         state: "open",
       });
     }),
@@ -762,6 +800,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 0,
@@ -794,8 +833,8 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         number: 15,
         title: "Valid PR title",
         url: "https://github.com/pingdotgg/codething-mvp/pull/15",
-        baseBranch: "main",
-        headBranch: "feature/status-valid-pr-entry",
+        baseRef: "main",
+        headRef: "feature/status-valid-pr-entry",
         state: "open",
       });
     }),
@@ -813,6 +852,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 16,
@@ -843,8 +883,8 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         number: 17,
         title: "Merged PR",
         url: "https://github.com/pingdotgg/codething-mvp/pull/17",
-        baseBranch: "main",
-        headBranch: "feature/status-lowercase-state",
+        baseRef: "main",
+        headRef: "feature/status-lowercase-state",
         state: "merged",
       });
     }),
@@ -859,9 +899,9 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
 
       expect(status).toEqual({
         isRepo: false,
-        hasOriginRemote: false,
-        isDefaultBranch: false,
-        branch: null,
+        hasPrimaryRemote: false,
+        isDefaultRef: false,
+        refName: null,
         hasWorkingTreeChanges: false,
         workingTree: {
           files: [],
@@ -871,6 +911,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         hasUpstream: false,
         aheadCount: 0,
         behindCount: 0,
+        aheadOfDefaultCount: 0,
         pr: null,
       });
     }),
@@ -888,9 +929,9 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
 
       expect(status).toEqual({
         isRepo: false,
-        hasOriginRemote: false,
-        isDefaultBranch: false,
-        branch: null,
+        hasPrimaryRemote: false,
+        isDefaultRef: false,
+        refName: null,
         hasWorkingTreeChanges: false,
         workingTree: {
           files: [],
@@ -900,6 +941,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         hasUpstream: false,
         aheadCount: 0,
         behindCount: 0,
+        aheadOfDefaultCount: 0,
         pr: null,
       });
     }),
@@ -923,6 +965,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       };
       const { manager, ghCalls } = yield* makeManager({
         ghScenario: {
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           prListSequence: [JSON.stringify([existingPr]), JSON.stringify([existingPr])],
         },
       });
@@ -949,6 +992,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         const { manager } = yield* makeManager({
           ghScenario: {
             prListSequence: [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([
                 {
                   number: 1661,
@@ -972,7 +1016,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         });
 
         const status = yield* manager.status({ cwd: repoDir });
-        expect(status.branch).toBe("main");
+        expect(status.refName).toBe("main");
         expect(status.pr).toBeNull();
       }),
   );
@@ -992,17 +1036,21 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         yield* runGit(repoDir, ["push", "-u", "fork-seed", "statemachine"]);
         yield* runGit(repoDir, ["checkout", "-b", "t3code/pr-488/statemachine"]);
         yield* runGit(repoDir, ["branch", "--set-upstream-to", "fork-seed/statemachine"]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.fork-seed.url",
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "fork-seed",
           "git@github.com:jasonLaster/codething-mvp.git",
-        ]);
+          forkDir,
+        );
 
         const { manager, ghCalls } = yield* makeManager({
           ghScenario: {
             prListSequence: [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([
                 {
                   number: 488,
@@ -1026,13 +1074,13 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         });
 
         const status = yield* manager.status({ cwd: repoDir });
-        expect(status.branch).toBe("t3code/pr-488/statemachine");
+        expect(status.refName).toBe("t3code/pr-488/statemachine");
         expect(status.pr).toEqual({
           number: 488,
           title: "Rebase this PR on latest main",
           url: "https://github.com/pingdotgg/codething-mvp/pull/488",
-          baseBranch: "main",
-          headBranch: "statemachine",
+          baseRef: "main",
+          headRef: "statemachine",
           state: "open",
         });
         expect(ghCalls).toContain(
@@ -1056,17 +1104,19 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         yield* runGit(repoDir, ["checkout", "-b", "effect-atom"]);
         yield* runGit(repoDir, ["push", "-u", "origin", "effect-atom"]);
         yield* runGit(repoDir, ["push", "-u", "my-org/upstream", "effect-atom"]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.origin.url",
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "origin",
           "git@github.com:pingdotgg/codething-mvp.git",
-        ]);
+          originDir,
+        );
         yield* runGit(repoDir, ["config", "remote.origin.pushurl", originDir]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.my-org/upstream.url",
-          "git@github.com:pingdotgg/codething-mvp.git",
-        ]);
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "my-org/upstream",
+          "ssh://git@github.com/pingdotgg/codething-mvp.git",
+          upstreamDir,
+        );
         yield* runGit(repoDir, ["config", "remote.my-org/upstream.pushurl", upstreamDir]);
         yield* runGit(repoDir, ["checkout", "main"]);
         yield* runGit(repoDir, ["branch", "-D", "effect-atom"]);
@@ -1075,6 +1125,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         const { manager, ghCalls } = yield* makeManager({
           ghScenario: {
             prListByHeadSelector: {
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "effect-atom": JSON.stringify([
                 {
                   number: 1618,
@@ -1086,6 +1137,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   updatedAt: "2026-03-01T10:00:00Z",
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "upstream/effect-atom": JSON.stringify([
                 {
                   number: 1518,
@@ -1097,8 +1149,11 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   updatedAt: "2026-04-01T10:00:00Z",
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "pingdotgg:effect-atom": JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "my-org/upstream:effect-atom": JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "pingdotgg:upstream/effect-atom": JSON.stringify([
                 {
                   number: 1518,
@@ -1110,6 +1165,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   updatedAt: "2026-04-01T10:00:00Z",
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "my-org/upstream:upstream/effect-atom": JSON.stringify([
                 {
                   number: 1518,
@@ -1126,13 +1182,13 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         });
 
         const status = yield* manager.status({ cwd: repoDir });
-        expect(status.branch).toBe("upstream/effect-atom");
+        expect(status.refName).toBe("upstream/effect-atom");
         expect(status.pr).toEqual({
           number: 1618,
           title: "Correct PR",
           url: "https://github.com/pingdotgg/t3code/pull/1618",
-          baseBranch: "main",
-          headBranch: "effect-atom",
+          baseRef: "main",
+          headRef: "effect-atom",
           state: "open",
         });
         expect(ghCalls.some((call) => call.includes("pr list --head upstream/effect-atom "))).toBe(
@@ -1159,6 +1215,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 22,
@@ -1176,18 +1233,49 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       });
 
       const status = yield* manager.status({ cwd: repoDir });
-      expect(status.branch).toBe("feature/status-merged-pr");
+      expect(status.refName).toBe("feature/status-merged-pr");
       expect(status.pr).toEqual({
         number: 22,
         title: "Merged PR",
         url: "https://github.com/pingdotgg/codething-mvp/pull/22",
-        baseBranch: "main",
-        headBranch: "feature/status-merged-pr",
+        baseRef: "main",
+        headRef: "feature/status-merged-pr",
         state: "merged",
       });
     }),
   );
 
+  it.effect("status hides merged PRs on the default branch", () =>
+    Effect.gen(function* () {
+      const repoDir = yield* makeTempDir("t3code-git-manager-");
+      yield* initRepo(repoDir);
+
+      const { manager } = yield* makeManager({
+        ghScenario: {
+          prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify([
+              {
+                number: 23,
+                title: "Merged PR",
+                url: "https://github.com/pingdotgg/codething-mvp/pull/23",
+                baseRefName: "feature/status-default-branch-target",
+                headRefName: "main",
+                state: "MERGED",
+                mergedAt: "2026-01-30T10:00:00Z",
+                updatedAt: "2026-01-30T10:00:00Z",
+              },
+            ]),
+          ],
+        },
+      });
+
+      const status = yield* manager.status({ cwd: repoDir });
+      expect(status.refName).toBe("main");
+      expect(status.pr).toBeNull();
+    }),
+  );
+
   it.effect("status prefers open PR when merged PR has newer updatedAt", () =>
     Effect.gen(function* () {
       const repoDir = yield* makeTempDir("t3code-git-manager-");
@@ -1197,6 +1285,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 45,
@@ -1223,13 +1312,13 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       });
 
       const status = yield* manager.status({ cwd: repoDir });
-      expect(status.branch).toBe("feature/status-open-over-merged");
+      expect(status.refName).toBe("feature/status-open-over-merged");
       expect(status.pr).toEqual({
         number: 46,
         title: "Open PR",
         url: "https://github.com/pingdotgg/codething-mvp/pull/46",
-        baseBranch: "main",
-        headBranch: "feature/status-open-over-merged",
+        baseRef: "main",
+        headRef: "feature/status-open-over-merged",
         state: "open",
       });
     }),
@@ -1254,7 +1343,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       });
 
       const status = yield* manager.status({ cwd: repoDir });
-      expect(status.branch).toBe("feature/status-no-gh");
+      expect(status.refName).toBe("feature/status-no-gh");
       expect(status.pr).toBeNull();
     }),
   );
@@ -1547,6 +1636,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
           ghScenario: {
             prListSequence: [
               "[]",
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([
                 {
                   number: 77,
@@ -1632,6 +1722,41 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
     }),
   );
 
+  it.effect("pushes existing commits without committing dirty worktree changes", () =>
+    Effect.gen(function* () {
+      const repoDir = yield* makeTempDir("t3code-git-manager-");
+      yield* initRepo(repoDir);
+      yield* runGit(repoDir, ["checkout", "-b", "feature/push-dirty"]);
+      const remoteDir = yield* createBareRemote();
+      yield* runGit(repoDir, ["remote", "add", "origin", remoteDir]);
+      fs.writeFileSync(path.join(repoDir, "push-dirty.txt"), "push dirty\n");
+      yield* runGit(repoDir, ["add", "push-dirty.txt"]);
+      yield* runGit(repoDir, ["commit", "-m", "Push dirty branch"]);
+      fs.mkdirSync(path.join(repoDir, ".vercel"));
+      fs.writeFileSync(path.join(repoDir, ".vercel", "project.json"), "{}\n");
+
+      const { manager } = yield* makeManager();
+      const result = yield* runStackedAction(manager, {
+        cwd: repoDir,
+        action: "push",
+      });
+
+      expect(result.commit.status).toBe("skipped_not_requested");
+      expect(result.push.status).toBe("pushed");
+      expect(result.pr.status).toBe("skipped_not_requested");
+      expect(
+        yield* runGit(repoDir, ["status", "--porcelain"]).pipe(
+          Effect.map((output) => output.stdout.trim()),
+        ),
+      ).toContain("?? .vercel/");
+      expect(
+        yield* runGit(remoteDir, ["log", "-1", "--pretty=%s", "feature/push-dirty"]).pipe(
+          Effect.map((output) => output.stdout.trim()),
+        ),
+      ).toBe("Push dirty branch");
+    }),
+  );
+
   it.effect("create_pr pushes a clean branch before creating the PR when needed", () =>
     Effect.gen(function* () {
       const repoDir = yield* makeTempDir("t3code-git-manager-");
@@ -1647,6 +1772,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         ghScenario: {
           prListSequence: [
             "[]",
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 303,
@@ -1678,6 +1804,50 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
     }),
   );
 
+  it.effect("create_pr falls back to main when source control provider detection fails", () =>
+    Effect.gen(function* () {
+      const repoDir = yield* makeTempDir("t3code-git-manager-");
+      yield* initRepo(repoDir);
+      yield* runGit(repoDir, ["checkout", "-b", "feature/provider-fallback"]);
+      fs.writeFileSync(path.join(repoDir, "provider-fallback.txt"), "fallback\n");
+      yield* runGit(repoDir, ["add", "provider-fallback.txt"]);
+      yield* runGit(repoDir, ["commit", "-m", "Provider fallback"]);
+      const remoteDir = yield* createBareRemote();
+      yield* runGit(repoDir, ["remote", "add", "origin", remoteDir]);
+
+      const { manager, ghCalls } = yield* makeManager({
+        ghScenario: {
+          prListSequence: [
+            "[]",
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify([
+              {
+                number: 404,
+                title: "Provider fallback",
+                url: "https://github.com/pingdotgg/codething-mvp/pull/404",
+                baseRefName: "main",
+                headRefName: "feature/provider-fallback",
+              },
+            ]),
+          ],
+        },
+      });
+
+      const result = yield* runStackedAction(manager, {
+        cwd: repoDir,
+        action: "create_pr",
+      });
+
+      expect(result.pr.status).toBe("created");
+      expect(result.pr.number).toBe(404);
+      expect(
+        ghCalls.some((call) =>
+          call.includes("pr create --base main --head feature/provider-fallback"),
+        ),
+      ).toBe(true);
+    }),
+  );
+
   it.effect("returns existing PR metadata for commit/push/pr action", () =>
     Effect.gen(function* () {
       const repoDir = yield* makeTempDir("t3code-git-manager-");
@@ -1690,6 +1860,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager, ghCalls } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 42,
@@ -1733,16 +1904,19 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         const forkDir = yield* createBareRemote();
         yield* runGit(repoDir, ["remote", "add", "fork-seed", forkDir]);
         yield* runGit(repoDir, ["push", "-u", "fork-seed", "statemachine"]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.fork-seed.url",
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "fork-seed",
           "git@github.com:octocat/codething-mvp.git",
-        ]);
+          forkDir,
+        );
 
         const { manager, ghCalls } = yield* makeManager({
           ghScenario: {
             prListSequence: [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([
                 {
                   number: 142,
@@ -1795,17 +1969,19 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         yield* runGit(repoDir, ["checkout", "-b", "effect-atom"]);
         yield* runGit(repoDir, ["push", "-u", "origin", "effect-atom"]);
         yield* runGit(repoDir, ["push", "-u", "my-org/upstream", "effect-atom"]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.origin.url",
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "origin",
           "git@github.com:pingdotgg/codething-mvp.git",
-        ]);
+          originDir,
+        );
         yield* runGit(repoDir, ["config", "remote.origin.pushurl", originDir]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.my-org/upstream.url",
-          "git@github.com:pingdotgg/codething-mvp.git",
-        ]);
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "my-org/upstream",
+          "ssh://git@github.com/pingdotgg/codething-mvp.git",
+          upstreamDir,
+        );
         yield* runGit(repoDir, ["config", "remote.my-org/upstream.pushurl", upstreamDir]);
         yield* runGit(repoDir, ["checkout", "main"]);
         yield* runGit(repoDir, ["branch", "-D", "effect-atom"]);
@@ -1817,6 +1993,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         const { manager, ghCalls } = yield* makeManager({
           ghScenario: {
             prListByHeadSelector: {
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "effect-atom": JSON.stringify([
                 {
                   number: 1618,
@@ -1826,6 +2003,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   headRefName: "effect-atom",
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "upstream/effect-atom": JSON.stringify([
                 {
                   number: 1518,
@@ -1835,8 +2013,11 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   headRefName: "upstream/effect-atom",
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "pingdotgg:effect-atom": JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "my-org/upstream:effect-atom": JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "pingdotgg:upstream/effect-atom": JSON.stringify([
                 {
                   number: 1518,
@@ -1846,6 +2027,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   headRefName: "upstream/effect-atom",
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "my-org/upstream:upstream/effect-atom": JSON.stringify([
                 {
                   number: 1518,
@@ -1885,16 +2067,19 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         yield* runGit(repoDir, ["push", "-u", "fork-seed", "statemachine"]);
         yield* runGit(repoDir, ["checkout", "-b", "t3code/pr-142/statemachine"]);
         yield* runGit(repoDir, ["branch", "--set-upstream-to", "fork-seed/statemachine"]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.fork-seed.url",
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "fork-seed",
           "git@github.com:octocat/codething-mvp.git",
-        ]);
+          forkDir,
+        );
 
         const { manager, ghCalls } = yield* makeManager({
           ghScenario: {
             prListByHeadSelector: {
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "t3code/pr-142/statemachine": JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               statemachine: JSON.stringify([
                 {
                   number: 41,
@@ -1904,6 +2089,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   headRefName: "statemachine",
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "octocat:statemachine": JSON.stringify([
                 {
                   number: 142,
@@ -1921,6 +2107,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   },
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "fork-seed:statemachine": JSON.stringify([]),
             },
           },
@@ -1955,15 +2142,17 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         yield* runGit(repoDir, ["push", "-u", "fork-seed", "statemachine"]);
         yield* runGit(repoDir, ["checkout", "-b", "t3code/pr-142/statemachine"]);
         yield* runGit(repoDir, ["branch", "--set-upstream-to", "fork-seed/statemachine"]);
-        yield* runGit(repoDir, [
-          "config",
-          "remote.fork-seed.url",
+        yield* configureVisibleRemoteUrlWithLocalRewrite(
+          repoDir,
+          "fork-seed",
           "git@github.com:octocat/codething-mvp.git",
-        ]);
+          forkDir,
+        );
 
         const { manager, ghCalls } = yield* makeManager({
           ghScenario: {
             prListByHeadSelector: {
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "octocat:statemachine": JSON.stringify([
                 {
                   number: 142,
@@ -1981,8 +2170,11 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   },
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "fork-seed:statemachine": JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               "t3code/pr-142/statemachine": JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               statemachine: JSON.stringify([]),
             },
           },
@@ -2022,6 +2214,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         ghScenario: {
           prListSequence: [
             "[]",
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 88,
@@ -2067,6 +2260,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         const { manager, ghCalls } = yield* makeManager({
           ghScenario: {
             prListSequence: [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([
                 {
                   number: 1661,
@@ -2084,6 +2278,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                   },
                 },
               ]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([
                 {
                   number: 188,
@@ -2135,17 +2330,20 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       yield* runGit(repoDir, ["push", "-u", "fork-seed", "statemachine"]);
       yield* runGit(repoDir, ["checkout", "-b", "t3code/pr-91/statemachine"]);
       yield* runGit(repoDir, ["branch", "--set-upstream-to", "fork-seed/statemachine"]);
-      yield* runGit(repoDir, [
-        "config",
-        "remote.fork-seed.url",
+      yield* configureVisibleRemoteUrlWithLocalRewrite(
+        repoDir,
+        "fork-seed",
         "git@github.com:octocat/codething-mvp.git",
-      ]);
+        forkDir,
+      );
 
       const { manager, ghCalls } = yield* makeManager({
         ghScenario: {
           prListSequenceByHeadSelector: {
             "octocat:statemachine": [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([]),
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               JSON.stringify([
                 {
                   number: 188,
@@ -2164,7 +2362,9 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
                 },
               ]),
             ],
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             "fork-seed:statemachine": [JSON.stringify([])],
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             statemachine: [JSON.stringify([])],
           },
         },
@@ -2335,6 +2535,113 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
     }),
   );
 
+  it.effect(
+    "restores same-repository upstream tracking after local PR checkout without a remote ref",
+    () =>
+      Effect.gen(function* () {
+        const repoDir = yield* makeTempDir("t3code-git-manager-");
+        yield* initRepo(repoDir);
+        const remoteDir = yield* createBareRemote();
+        yield* runGit(repoDir, ["remote", "add", "origin", remoteDir]);
+        yield* runGit(repoDir, ["push", "-u", "origin", "main"]);
+        yield* runGit(repoDir, ["checkout", "-b", "feature/pr-local-upstream"]);
+        fs.writeFileSync(path.join(repoDir, "upstream.txt"), "upstream\n");
+        yield* runGit(repoDir, ["add", "upstream.txt"]);
+        yield* runGit(repoDir, ["commit", "-m", "Local upstream PR branch"]);
+        yield* runGit(repoDir, ["push", "-u", "origin", "feature/pr-local-upstream"]);
+        yield* runGit(repoDir, ["checkout", "main"]);
+        yield* runGit(repoDir, ["branch", "-D", "feature/pr-local-upstream"]);
+        yield* runGit(repoDir, [
+          "update-ref",
+          "-d",
+          "refs/remotes/origin/feature/pr-local-upstream",
+        ]);
+
+        const { manager } = yield* makeManager({
+          ghScenario: {
+            pullRequest: {
+              number: 65,
+              title: "Local upstream PR",
+              url: "https://github.com/pingdotgg/codething-mvp/pull/65",
+              baseRefName: "main",
+              headRefName: "feature/pr-local-upstream",
+              state: "open",
+              isCrossRepository: false,
+              headRepositoryNameWithOwner: "pingdotgg/codething-mvp",
+              headRepositoryOwnerLogin: "pingdotgg",
+            },
+            repositoryCloneUrls: {
+              "pingdotgg/codething-mvp": {
+                url: remoteDir,
+                sshUrl: remoteDir,
+              },
+            },
+          },
+        });
+
+        const result = yield* preparePullRequestThread(manager, {
+          cwd: repoDir,
+          reference: "65",
+          mode: "local",
+        });
+
+        expect(result.worktreePath).toBeNull();
+        expect(result.branch).toBe("feature/pr-local-upstream");
+        expect(
+          (yield* runGit(repoDir, ["rev-parse", "--abbrev-ref", "@{upstream}"])).stdout.trim(),
+        ).toBe("origin/feature/pr-local-upstream");
+      }),
+  );
+
+  it.effect(
+    "restores same-repository upstream tracking when provider omits head repository metadata",
+    () =>
+      Effect.gen(function* () {
+        const repoDir = yield* makeTempDir("t3code-git-manager-");
+        yield* initRepo(repoDir);
+        const remoteDir = yield* createBareRemote();
+        yield* runGit(repoDir, ["remote", "add", "origin", remoteDir]);
+        yield* runGit(repoDir, ["push", "-u", "origin", "main"]);
+        yield* runGit(repoDir, ["checkout", "-b", "feature/pr-local-no-head-repo"]);
+        fs.writeFileSync(path.join(repoDir, "no-head-repo.txt"), "upstream\n");
+        yield* runGit(repoDir, ["add", "no-head-repo.txt"]);
+        yield* runGit(repoDir, ["commit", "-m", "Local PR branch without repo metadata"]);
+        yield* runGit(repoDir, ["push", "-u", "origin", "feature/pr-local-no-head-repo"]);
+        yield* runGit(repoDir, ["checkout", "main"]);
+        yield* runGit(repoDir, ["branch", "-D", "feature/pr-local-no-head-repo"]);
+        yield* runGit(repoDir, [
+          "update-ref",
+          "-d",
+          "refs/remotes/origin/feature/pr-local-no-head-repo",
+        ]);
+
+        const { manager } = yield* makeManager({
+          ghScenario: {
+            pullRequest: {
+              number: 66,
+              title: "Local upstream PR without repo metadata",
+              url: "https://github.com/pingdotgg/codething-mvp/pull/66",
+              baseRefName: "main",
+              headRefName: "feature/pr-local-no-head-repo",
+              state: "open",
+            },
+          },
+        });
+
+        const result = yield* preparePullRequestThread(manager, {
+          cwd: repoDir,
+          reference: "66",
+          mode: "local",
+        });
+
+        expect(result.worktreePath).toBeNull();
+        expect(result.branch).toBe("feature/pr-local-no-head-repo");
+        expect(
+          (yield* runGit(repoDir, ["rev-parse", "--abbrev-ref", "@{upstream}"])).stdout.trim(),
+        ).toBe("origin/feature/pr-local-no-head-repo");
+      }),
+  );
+
   it.effect("prepares pull request threads in worktree mode on the PR head branch", () =>
     Effect.gen(function* () {
       const repoDir = yield* makeTempDir("t3code-git-manager-");
@@ -2614,7 +2921,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       yield* runGit(repoDir, ["add", "existing.txt"]);
       yield* runGit(repoDir, ["commit", "-m", "Existing worktree branch"]);
       yield* runGit(repoDir, ["checkout", "main"]);
-      const worktreePath = path.join(repoDir, "..", `pr-existing-${Date.now()}`);
+      const worktreePath = path.join(repoDir, "..", `pr-existing-${path.basename(repoDir)}`);
       yield* runGit(repoDir, ["worktree", "add", worktreePath, "feature/pr-existing-worktree"]);
 
       const setupCalls: ProjectSetupScriptRunnerInput[] = [];
@@ -2788,7 +3095,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       yield* runGit(repoDir, ["commit", "-m", "Reused fork PR branch"]);
       yield* runGit(repoDir, ["push", "-u", "fork-seed", "feature/pr-reused-fork"]);
       yield* runGit(repoDir, ["checkout", "main"]);
-      const worktreePath = path.join(repoDir, "..", `pr-reused-fork-${Date.now()}`);
+      const worktreePath = path.join(repoDir, "..", `pr-reused-fork-${path.basename(repoDir)}`);
       yield* runGit(repoDir, ["worktree", "add", worktreePath, "feature/pr-reused-fork"]);
       yield* runGit(worktreePath, ["branch", "--unset-upstream"], true);
 
@@ -2856,7 +3163,8 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
           },
         },
         setupScriptRunner: {
-          runForThread: () => Effect.fail(new Error("terminal start failed")),
+          runForThread: () =>
+            Effect.fail(new ProjectSetupScriptRunnerError({ message: "terminal start failed" })),
         },
       });
 
@@ -2912,7 +3220,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       fs.writeFileSync(path.join(repoDir, "hooked.txt"), "hooked\n");
       fs.writeFileSync(
         path.join(repoDir, ".git", "hooks", "pre-commit"),
-        '#!/bin/sh\necho "hook: start" >&2\nsleep 1\necho "hook: end" >&2\n',
+        '#!/bin/sh\necho "hook: start" >&2\nsleep 0.05\necho "hook: end" >&2\n',
         { mode: 0o755 },
       );
 
@@ -3033,7 +3341,9 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
       const { manager } = yield* makeManager({
         ghScenario: {
           prListSequence: [
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([]),
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
             JSON.stringify([
               {
                 number: 201,
@@ -3089,7 +3399,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         expect.objectContaining({
           kind: "phase_started",
           phase: "pr",
-          label: "Creating GitHub pull request...",
+          label: "Creating pull request...",
         }),
       ]);
     }),
diff --git a/apps/server/src/git/Layers/GitManager.ts b/apps/server/src/git/GitManager.ts
similarity index 83%
rename from apps/server/src/git/Layers/GitManager.ts
rename to apps/server/src/git/GitManager.ts
index a84427a194a..8dfb957b89d 100644
--- a/apps/server/src/git/Layers/GitManager.ts
+++ b/apps/server/src/git/GitManager.ts
@@ -1,54 +1,94 @@
 import { randomUUID } from "node:crypto";
-import { realpathSync } from "node:fs";
 
-import {
-  Cache,
-  Duration,
-  Effect,
-  Exit,
-  FileSystem,
-  Layer,
-  Option,
-  Path,
-  Ref,
-  Result,
-} from "effect";
+import * as Arr from "effect/Array";
+import * as Cache from "effect/Cache";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Order from "effect/Order";
+import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
 import {
   GitActionProgressEvent,
   GitActionProgressPhase,
   GitCommandError,
+  GitPreparePullRequestThreadInput,
+  GitPreparePullRequestThreadResult,
+  GitPullRequestRefInput,
+  GitResolvePullRequestResult,
+  GitRunStackedActionInput,
   GitRunStackedActionResult,
   GitStackedAction,
-  type GitStatusLocalResult,
-  type GitStatusRemoteResult,
+  VcsStatusInput,
+  type VcsStatusLocalResult,
+  type VcsStatusRemoteResult,
+  VcsStatusResult,
   ModelSelection,
 } from "@t3tools/contracts";
 import {
-  detectGitHostingProviderFromRemoteUrl,
+  detectSourceControlProviderFromGitRemoteUrl,
   mergeGitStatusParts,
   resolveAutoFeatureBranchName,
   sanitizeBranchFragment,
   sanitizeFeatureBranchName,
 } from "@t3tools/shared/git";
+import {
+  getChangeRequestTerminologyForKind,
+  type ChangeRequestTerminology,
+} from "@t3tools/shared/sourceControl";
 
 import { GitManagerError } from "@t3tools/contracts";
-import {
-  GitManager,
-  type GitActionProgressReporter,
-  type GitManagerShape,
-  type GitRunStackedActionOptions,
-} from "../Services/GitManager.ts";
-import { GitCore, GitStatusDetails } from "../Services/GitCore.ts";
-import { GitHubCli, type GitHubPullRequestSummary } from "../Services/GitHubCli.ts";
-import { TextGeneration } from "../Services/TextGeneration.ts";
-import { ProjectSetupScriptRunner } from "../../project/Services/ProjectSetupScriptRunner.ts";
-import { extractBranchNameFromRemoteRef } from "../remoteRefs.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import { TextGeneration } from "../textGeneration/TextGeneration.ts";
+import { ProjectSetupScriptRunner } from "../project/Services/ProjectSetupScriptRunner.ts";
+import { extractBranchNameFromRemoteRef } from "./remoteRefs.ts";
+import { ServerSettingsService } from "../serverSettings.ts";
 import type { GitManagerServiceError } from "@t3tools/contracts";
-import {
-  decodeGitHubPullRequestListJson,
-  formatGitHubJsonDecodeError,
-} from "../githubPullRequests.ts";
+import { GitVcsDriver, type GitStatusDetails } from "../vcs/GitVcsDriver.ts";
+import { SourceControlProviderRegistry } from "../sourceControl/SourceControlProviderRegistry.ts";
+import type { ChangeRequest } from "@t3tools/contracts";
+
+export interface GitActionProgressReporter {
+  readonly publish: (event: GitActionProgressEvent) => Effect.Effect<void, never>;
+}
+
+export interface GitRunStackedActionOptions {
+  readonly actionId?: string;
+  readonly progressReporter?: GitActionProgressReporter;
+}
+
+export interface GitManagerShape {
+  readonly status: (
+    input: VcsStatusInput,
+  ) => Effect.Effect<VcsStatusResult, GitManagerServiceError>;
+  readonly localStatus: (
+    input: VcsStatusInput,
+  ) => Effect.Effect<VcsStatusLocalResult, GitManagerServiceError>;
+  readonly remoteStatus: (
+    input: VcsStatusInput,
+  ) => Effect.Effect<VcsStatusRemoteResult | null, GitManagerServiceError>;
+  readonly invalidateLocalStatus: (cwd: string) => Effect.Effect<void, never>;
+  readonly invalidateRemoteStatus: (cwd: string) => Effect.Effect<void, never>;
+  readonly invalidateStatus: (cwd: string) => Effect.Effect<void, never>;
+  readonly resolvePullRequest: (
+    input: GitPullRequestRefInput,
+  ) => Effect.Effect<GitResolvePullRequestResult, GitManagerServiceError>;
+  readonly preparePullRequestThread: (
+    input: GitPreparePullRequestThreadInput,
+  ) => Effect.Effect<GitPreparePullRequestThreadResult, GitManagerServiceError>;
+  readonly runStackedAction: (
+    input: GitRunStackedActionInput,
+    options?: GitRunStackedActionOptions,
+  ) => Effect.Effect<GitRunStackedActionResult, GitManagerServiceError>;
+}
+
+export class GitManager extends Context.Service<GitManager, GitManagerShape>()(
+  "t3/git/GitManager",
+) {}
 
 const COMMIT_TIMEOUT_MS = 10 * 60_000;
 const MAX_PROGRESS_TEXT_LENGTH = 500;
@@ -74,9 +114,14 @@ interface OpenPrInfo {
 
 interface PullRequestInfo extends OpenPrInfo, PullRequestHeadRemoteInfo {
   state: "open" | "closed" | "merged";
-  updatedAt: string | null;
+  updatedAt: Option.Option<DateTime.Utc>;
 }
 
+const pullRequestUpdatedAtDescOrder: Order.Order<PullRequestInfo> = Order.mapInput(
+  Order.flip(Option.makeOrder(DateTime.Order)),
+  (pullRequest) => pullRequest.updatedAt,
+);
+
 interface ResolvedPullRequest {
   number: number;
   title: string;
@@ -87,9 +132,9 @@ interface ResolvedPullRequest {
 }
 
 interface PullRequestHeadRemoteInfo {
-  isCrossRepository?: boolean;
-  headRepositoryNameWithOwner?: string | null;
-  headRepositoryOwnerLogin?: string | null;
+  isCrossRepository?: boolean | undefined;
+  headRepositoryNameWithOwner?: string | null | undefined;
+  headRepositoryOwnerLogin?: string | null | undefined;
 }
 
 interface BranchHeadContext {
@@ -255,7 +300,7 @@ function matchesBranchHeadContext(
   return true;
 }
 
-function toPullRequestInfo(summary: GitHubPullRequestSummary): PullRequestInfo {
+function toPullRequestInfo(summary: ChangeRequest): PullRequestInfo {
   return {
     number: summary.number,
     title: summary.title,
@@ -263,7 +308,7 @@ function toPullRequestInfo(summary: GitHubPullRequestSummary): PullRequestInfo {
     baseRefName: summary.baseRefName,
     headRefName: summary.headRefName,
     state: summary.state ?? "open",
-    updatedAt: null,
+    updatedAt: summary.updatedAt,
     ...(summary.isCrossRepository !== undefined
       ? { isCrossRepository: summary.isCrossRepository }
       : {}),
@@ -310,13 +355,14 @@ function withDescription(title: string, description: string | undefined) {
 
 function summarizeGitActionResult(
   result: Pick<GitRunStackedActionResult, "commit" | "push" | "pr">,
+  terms: ChangeRequestTerminology,
 ): {
   title: string;
   description?: string;
 } {
   if (result.pr.status === "created" || result.pr.status === "opened_existing") {
     const prNumber = result.pr.number ? ` #${result.pr.number}` : "";
-    const title = `${result.pr.status === "created" ? "Created PR" : "Opened PR"}${prNumber}`;
+    const title = `${result.pr.status === "created" ? "Created" : "Opened"} ${terms.shortLabel}${prNumber}`;
     return withDescription(title, truncateText(result.pr.title));
   }
 
@@ -421,16 +467,16 @@ function toStatusPr(pr: PullRequestInfo): {
   number: number;
   title: string;
   url: string;
-  baseBranch: string;
-  headBranch: string;
+  baseRef: string;
+  headRef: string;
   state: "open" | "closed" | "merged";
 } {
   return {
     number: pr.number,
     title: pr.title,
     url: pr.url,
-    baseBranch: pr.baseRefName,
-    headBranch: pr.headRefName,
+    baseRef: pr.baseRefName,
+    headRef: pr.headRefName,
     state: pr.state,
   };
 }
@@ -441,14 +487,6 @@ function normalizePullRequestReference(reference: string): string {
   return hashNumber?.[1] ?? trimmed;
 }
 
-function canonicalizeExistingPath(value: string): string {
-  try {
-    return realpathSync.native(value);
-  } catch {
-    return value;
-  }
-}
-
 function toResolvedPullRequest(pr: {
   number: number;
   title: string;
@@ -474,9 +512,9 @@ function shouldPreferSshRemote(url: string | null): boolean {
 }
 
 function toPullRequestHeadRemoteInfo(pr: {
-  isCrossRepository?: boolean;
-  headRepositoryNameWithOwner?: string | null;
-  headRepositoryOwnerLogin?: string | null;
+  isCrossRepository?: boolean | undefined;
+  headRepositoryNameWithOwner?: string | null | undefined;
+  headRepositoryOwnerLogin?: string | null | undefined;
 }): PullRequestHeadRemoteInfo {
   return {
     ...(pr.isCrossRepository !== undefined ? { isCrossRepository: pr.isCrossRepository } : {}),
@@ -490,10 +528,12 @@ function toPullRequestHeadRemoteInfo(pr: {
 }
 
 export const makeGitManager = Effect.fn("makeGitManager")(function* () {
-  const gitCore = yield* GitCore;
-  const gitHubCli = yield* GitHubCli;
+  const gitCore = yield* GitVcsDriver;
+  const sourceControlProviders = yield* SourceControlProviderRegistry;
   const textGeneration = yield* TextGeneration;
   const projectSetupScriptRunner = yield* ProjectSetupScriptRunner;
+
+  const sourceControlProvider = (cwd: string) => sourceControlProviders.resolve({ cwd });
   const serverSettingsService = yield* ServerSettingsService;
 
   const createProgressEmitter = (
@@ -526,11 +566,27 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
       localBranch = pullRequest.headBranch,
     ) {
       const repositoryNameWithOwner = resolveHeadRepositoryNameWithOwner(pullRequest) ?? "";
+      if (repositoryNameWithOwner.length === 0 && pullRequest.isCrossRepository !== true) {
+        const remoteName = yield* gitCore.resolvePrimaryRemoteName(cwd);
+        yield* gitCore.fetchRemoteTrackingBranch({
+          cwd,
+          remoteName,
+          remoteBranch: pullRequest.headBranch,
+        });
+        yield* gitCore.setBranchUpstream({
+          cwd,
+          branch: localBranch,
+          remoteName,
+          remoteBranch: pullRequest.headBranch,
+        });
+        return;
+      }
+
       if (repositoryNameWithOwner.length === 0) {
         return;
       }
 
-      const cloneUrls = yield* gitHubCli.getRepositoryCloneUrls({
+      const cloneUrls = yield* (yield* sourceControlProvider(cwd)).getRepositoryCloneUrls({
         cwd,
         repository: repositoryNameWithOwner,
       });
@@ -546,6 +602,11 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
         url: remoteUrl,
       });
 
+      yield* gitCore.fetchRemoteTrackingBranch({
+        cwd,
+        remoteName,
+        remoteBranch: pullRequest.headBranch,
+      });
       yield* gitCore.setBranchUpstream({
         cwd,
         branch: localBranch,
@@ -585,7 +646,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
         return;
       }
 
-      const cloneUrls = yield* gitHubCli.getRepositoryCloneUrls({
+      const cloneUrls = yield* (yield* sourceControlProvider(cwd)).getRepositoryCloneUrls({
         cwd,
         repository: repositoryNameWithOwner,
       });
@@ -634,7 +695,9 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
   const path = yield* Path.Path;
 
   const tempDir = process.env.TMPDIR ?? process.env.TEMP ?? process.env.TMP ?? "/tmp";
-  const normalizeStatusCacheKey = (cwd: string) => canonicalizeExistingPath(cwd);
+  const canonicalizeExistingPath = (value: string) =>
+    fileSystem.realPath(value).pipe(Effect.catch(() => Effect.succeed(value)));
+  const normalizeStatusCacheKey = canonicalizeExistingPath;
   const nonRepositoryStatusDetails = {
     isRepo: false,
     hasOriginRemote: false,
@@ -646,6 +709,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     hasUpstream: false,
     aheadCount: 0,
     behindCount: 0,
+    aheadOfDefaultCount: 0,
   } satisfies GitStatusDetails;
   const readLocalStatus = Effect.fn("readLocalStatus")(function* (cwd: string) {
     const details = yield* gitCore
@@ -659,20 +723,22 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
 
     return {
       isRepo: details.isRepo,
-      ...(hostingProvider ? { hostingProvider } : {}),
-      hasOriginRemote: details.hasOriginRemote,
-      isDefaultBranch: details.isDefaultBranch,
-      branch: details.branch,
+      ...(hostingProvider ? { sourceControlProvider: hostingProvider } : {}),
+      hasPrimaryRemote: details.hasOriginRemote,
+      isDefaultRef: details.isDefaultBranch,
+      refName: details.branch,
       hasWorkingTreeChanges: details.hasWorkingTreeChanges,
       workingTree: details.workingTree,
-    } satisfies GitStatusLocalResult;
+    } satisfies VcsStatusLocalResult;
   });
   const localStatusResultCache = yield* Cache.makeWith(readLocalStatus, {
     capacity: STATUS_RESULT_CACHE_CAPACITY,
     timeToLive: (exit) => (Exit.isSuccess(exit) ? STATUS_RESULT_CACHE_TTL : Duration.zero),
   });
   const invalidateLocalStatusResultCache = (cwd: string) =>
-    Cache.invalidate(localStatusResultCache, normalizeStatusCacheKey(cwd));
+    normalizeStatusCacheKey(cwd).pipe(
+      Effect.flatMap((cacheKey) => Cache.invalidate(localStatusResultCache, cacheKey)),
+    );
   const readRemoteStatus = Effect.fn("readRemoteStatus")(function* (cwd: string) {
     const details = yield* gitCore
       .statusDetails(cwd)
@@ -687,7 +753,13 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
             branch: details.branch,
             upstreamRef: details.upstreamRef,
           }).pipe(
-            Effect.map((latest) => (latest ? toStatusPr(latest) : null)),
+            Effect.map((latest) => {
+              if (!latest) return null;
+              // On the default branch, only surface open PRs.
+              // Merged/closed matches are usually reverse-merge history, not the thread's PR context.
+              if (details.isDefaultBranch && latest.state !== "open") return null;
+              return toStatusPr(latest);
+            }),
             Effect.catch(() => Effect.succeed(null)),
           )
         : null;
@@ -696,15 +768,18 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
       hasUpstream: details.hasUpstream,
       aheadCount: details.aheadCount,
       behindCount: details.behindCount,
+      aheadOfDefaultCount: details.aheadOfDefaultCount,
       pr,
-    } satisfies GitStatusRemoteResult;
+    } satisfies VcsStatusRemoteResult;
   });
   const remoteStatusResultCache = yield* Cache.makeWith(readRemoteStatus, {
     capacity: STATUS_RESULT_CACHE_CAPACITY,
     timeToLive: (exit) => (Exit.isSuccess(exit) ? STATUS_RESULT_CACHE_TTL : Duration.zero),
   });
   const invalidateRemoteStatusResultCache = (cwd: string) =>
-    Cache.invalidate(remoteStatusResultCache, normalizeStatusCacheKey(cwd));
+    normalizeStatusCacheKey(cwd).pipe(
+      Effect.flatMap((cacheKey) => Cache.invalidate(remoteStatusResultCache, cacheKey)),
+    );
 
   const readConfigValueNullable = (cwd: string, key: string) =>
     gitCore.readConfigValue(cwd, key).pipe(Effect.catch(() => Effect.succeed(null)));
@@ -721,7 +796,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
       (yield* readConfigValueNullable(cwd, `remote.${preferredRemoteName}.url`)) ??
       (yield* readConfigValueNullable(cwd, "remote.origin.url"));
 
-    return remoteUrl ? detectGitHostingProviderFromRemoteUrl(remoteUrl) : null;
+    return remoteUrl ? detectSourceControlProviderFromGitRemoteUrl(remoteUrl) : null;
   });
 
   const resolveRemoteRepositoryContext = Effect.fn("resolveRemoteRepositoryContext")(function* (
@@ -826,9 +901,10 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     >,
   ) {
     for (const headSelector of headContext.headSelectors) {
-      const pullRequests = yield* gitHubCli.listOpenPullRequests({
+      const pullRequests = yield* (yield* sourceControlProvider(cwd)).listChangeRequests({
         cwd,
         headSelector,
+        state: "open",
         limit: 1,
       });
       const normalizedPullRequests = pullRequests.map(toPullRequestInfo);
@@ -844,7 +920,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
           baseRefName: firstPullRequest.baseRefName,
           headRefName: firstPullRequest.headRefName,
           state: "open",
-          updatedAt: null,
+          updatedAt: Option.none(),
         } satisfies PullRequestInfo;
       }
     }
@@ -860,46 +936,14 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     const parsedByNumber = new Map<number, PullRequestInfo>();
 
     for (const headSelector of headContext.headSelectors) {
-      const stdout = yield* gitHubCli
-        .execute({
-          cwd,
-          args: [
-            "pr",
-            "list",
-            "--head",
-            headSelector,
-            "--state",
-            "all",
-            "--limit",
-            "20",
-            "--json",
-            "number,title,url,baseRefName,headRefName,state,mergedAt,updatedAt,isCrossRepository,headRepository,headRepositoryOwner",
-          ],
-        })
-        .pipe(Effect.map((result) => result.stdout));
-
-      const raw = stdout.trim();
-      if (raw.length === 0) {
-        continue;
-      }
-
-      const pullRequests = yield* Effect.sync(() => decodeGitHubPullRequestListJson(raw)).pipe(
-        Effect.flatMap((decoded) => {
-          if (!Result.isSuccess(decoded)) {
-            return Effect.fail(
-              gitManagerError(
-                "findLatestPr",
-                `GitHub CLI returned invalid PR list JSON: ${formatGitHubJsonDecodeError(decoded.failure)}`,
-                decoded.failure,
-              ),
-            );
-          }
-
-          return Effect.succeed(decoded.success);
-        }),
-      );
+      const pullRequests = yield* (yield* sourceControlProvider(cwd)).listChangeRequests({
+        cwd,
+        headSelector,
+        state: "all",
+        limit: 20,
+      });
 
-      for (const pr of pullRequests) {
+      for (const pr of pullRequests.map(toPullRequestInfo)) {
         if (!matchesBranchHeadContext(pr, headContext)) {
           continue;
         }
@@ -907,11 +951,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
       }
     }
 
-    const parsed = Array.from(parsedByNumber.values()).toSorted((a, b) => {
-      const left = a.updatedAt ? Date.parse(a.updatedAt) : 0;
-      const right = b.updatedAt ? Date.parse(b.updatedAt) : 0;
-      return right - left;
-    });
+    const parsed = Arr.sort(parsedByNumber.values(), pullRequestUpdatedAtDescOrder);
 
     const latestOpenPr = parsed.find((pr) => pr.state === "open");
     if (latestOpenPr) {
@@ -924,7 +964,11 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     cwd: string,
     result: Pick<GitRunStackedActionResult, "action" | "branch" | "commit" | "push" | "pr">,
   ) {
-    const summary = summarizeGitActionResult(result);
+    const terms = yield* sourceControlProvider(cwd).pipe(
+      Effect.map((provider) => getChangeRequestTerminologyForKind(provider.kind)),
+      Effect.catch(() => Effect.succeed(getChangeRequestTerminologyForKind("unknown"))),
+    );
+    const summary = summarizeGitActionResult(result, terms);
     let latestOpenPr: PullRequestInfo | null = null;
     let currentBranchIsDefault = false;
     let finalBranchContext: {
@@ -989,7 +1033,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
               result.pr.status === "opened_existing")
           ? {
               kind: "open_pr" as const,
-              label: "View PR",
+              label: `View ${terms.shortLabel}`,
               url: openPr.url,
             }
           : (result.action === "push" || result.action === "commit_push") &&
@@ -997,7 +1041,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
               !currentBranchIsDefault
             ? {
                 kind: "run_action" as const,
-                label: "Create PR",
+                label: `Create ${terms.shortLabel}`,
                 action: { kind: "create_pr" as const },
               }
             : {
@@ -1028,11 +1072,12 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
       }
     }
 
-    const defaultFromGh = yield* gitHubCli
-      .getDefaultBranch({ cwd })
-      .pipe(Effect.catch(() => Effect.succeed(null)));
-    if (defaultFromGh) {
-      return defaultFromGh;
+    const defaultFromProvider = yield* sourceControlProvider(cwd).pipe(
+      Effect.flatMap((provider) => provider.getDefaultBranch({ cwd })),
+      Effect.catch(() => Effect.succeed(null)),
+    );
+    if (defaultFromProvider) {
+      return defaultFromProvider;
     }
 
     return "main";
@@ -1204,6 +1249,8 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     fallbackBranch: string | null,
     emit: GitActionProgressEmitter,
   ) {
+    const provider = yield* sourceControlProvider(cwd);
+    const terms = getChangeRequestTerminologyForKind(provider.kind);
     const details = yield* gitCore.statusDetails(cwd);
     const branch = details.branch ?? fallbackBranch;
     if (!branch) {
@@ -1240,7 +1287,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     yield* emit({
       kind: "phase_started",
       phase: "pr",
-      label: "Generating PR content...",
+      label: `Generating ${terms.shortLabel} content...`,
     });
     const rangeContext = yield* gitCore.readRangeContext(cwd, baseBranch);
 
@@ -1265,12 +1312,12 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     yield* emit({
       kind: "phase_started",
       phase: "pr",
-      label: "Creating GitHub pull request...",
+      label: `Creating ${terms.singular}...`,
     });
-    yield* gitHubCli
-      .createPullRequest({
+    yield* provider
+      .createChangeRequest({
         cwd,
-        baseBranch,
+        baseRefName: baseBranch,
         headSelector: headContext.preferredHeadSelector,
         title: generated.title,
         bodyFile,
@@ -1298,11 +1345,13 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
   });
 
   const localStatus: GitManagerShape["localStatus"] = Effect.fn("localStatus")(function* (input) {
-    return yield* Cache.get(localStatusResultCache, normalizeStatusCacheKey(input.cwd));
+    const cacheKey = yield* normalizeStatusCacheKey(input.cwd);
+    return yield* Cache.get(localStatusResultCache, cacheKey);
   });
   const remoteStatus: GitManagerShape["remoteStatus"] = Effect.fn("remoteStatus")(
     function* (input) {
-      return yield* Cache.get(remoteStatusResultCache, normalizeStatusCacheKey(input.cwd));
+      const cacheKey = yield* normalizeStatusCacheKey(input.cwd);
+      return yield* Cache.get(remoteStatusResultCache, cacheKey);
     },
   );
   const status: GitManagerShape["status"] = Effect.fn("status")(function* (input) {
@@ -1328,8 +1377,8 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
 
   const resolvePullRequest: GitManagerShape["resolvePullRequest"] = Effect.fn("resolvePullRequest")(
     function* (input) {
-      const pullRequest = yield* gitHubCli
-        .getPullRequest({
+      const pullRequest = yield* (yield* sourceControlProvider(input.cwd))
+        .getChangeRequest({
           cwd: input.cwd,
           reference: normalizePullRequestReference(input.reference),
         })
@@ -1362,15 +1411,15 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     };
     return yield* Effect.gen(function* () {
       const normalizedReference = normalizePullRequestReference(input.reference);
-      const rootWorktreePath = canonicalizeExistingPath(input.cwd);
-      const pullRequestSummary = yield* gitHubCli.getPullRequest({
+      const rootWorktreePath = yield* canonicalizeExistingPath(input.cwd);
+      const pullRequestSummary = yield* (yield* sourceControlProvider(input.cwd)).getChangeRequest({
         cwd: input.cwd,
         reference: normalizedReference,
       });
       const pullRequest = toResolvedPullRequest(pullRequestSummary);
 
       if (input.mode === "local") {
-        yield* gitHubCli.checkoutPullRequest({
+        yield* (yield* sourceControlProvider(input.cwd)).checkoutChangeRequest({
           cwd: input.cwd,
           reference: normalizedReference,
           force: true,
@@ -1412,33 +1461,35 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
       const localPullRequestBranch =
         resolvePullRequestWorktreeLocalBranchName(pullRequestWithRemoteInfo);
 
-      const findLocalHeadBranch = (cwd: string) =>
-        gitCore.listBranches({ cwd }).pipe(
-          Effect.map((result) => {
-            const localBranch = result.branches.find(
-              (branch) => !branch.isRemote && branch.name === localPullRequestBranch,
-            );
-            if (localBranch) {
-              return localBranch;
-            }
-            if (localPullRequestBranch === pullRequest.headBranch) {
-              return null;
-            }
-            return (
-              result.branches.find(
-                (branch) =>
-                  !branch.isRemote &&
-                  branch.name === pullRequest.headBranch &&
-                  branch.worktreePath !== null &&
-                  canonicalizeExistingPath(branch.worktreePath) !== rootWorktreePath,
-              ) ?? null
-            );
-          }),
+      const findLocalHeadBranch = Effect.fn("findLocalHeadBranch")(function* (cwd: string) {
+        const result = yield* gitCore.listRefs({ cwd });
+        const localBranch = result.refs.find(
+          (branch) => !branch.isRemote && branch.name === localPullRequestBranch,
         );
+        if (localBranch) {
+          return localBranch;
+        }
+        if (localPullRequestBranch === pullRequest.headBranch) {
+          return null;
+        }
+
+        for (const branch of result.refs) {
+          if (branch.isRemote || branch.name !== pullRequest.headBranch || !branch.worktreePath) {
+            continue;
+          }
+
+          const worktreePath = yield* canonicalizeExistingPath(branch.worktreePath);
+          if (worktreePath !== rootWorktreePath) {
+            return branch;
+          }
+        }
+
+        return null;
+      });
 
       const existingBranchBeforeFetch = yield* findLocalHeadBranch(input.cwd);
       const existingBranchBeforeFetchPath = existingBranchBeforeFetch?.worktreePath
-        ? canonicalizeExistingPath(existingBranchBeforeFetch.worktreePath)
+        ? yield* canonicalizeExistingPath(existingBranchBeforeFetch.worktreePath)
         : null;
       if (
         existingBranchBeforeFetch?.worktreePath &&
@@ -1466,7 +1517,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
 
       const existingBranchAfterFetch = yield* findLocalHeadBranch(input.cwd);
       const existingBranchAfterFetchPath = existingBranchAfterFetch?.worktreePath
-        ? canonicalizeExistingPath(existingBranchAfterFetch.worktreePath)
+        ? yield* canonicalizeExistingPath(existingBranchAfterFetch.worktreePath)
         : null;
       if (
         existingBranchAfterFetch?.worktreePath &&
@@ -1488,7 +1539,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
 
       const worktree = yield* gitCore.createWorktree({
         cwd: input.cwd,
-        branch: localPullRequestBranch,
+        refName: localPullRequestBranch,
         path: null,
       });
       yield* ensureExistingWorktreeUpstream(worktree.worktree.path);
@@ -1496,7 +1547,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
 
       return {
         pullRequest,
-        branch: worktree.worktree.branch,
+        branch: worktree.worktree.refName,
         worktreePath: worktree.worktree.path,
       };
     }).pipe(Effect.ensuring(invalidateStatus(input.cwd)));
@@ -1528,8 +1579,8 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
     const existingBranchNames = yield* gitCore.listLocalBranchNames(cwd);
     const resolvedBranch = resolveAutoFeatureBranchName(existingBranchNames, preferredBranch);
 
-    yield* gitCore.createBranch({ cwd, branch: resolvedBranch });
-    yield* Effect.scoped(gitCore.checkoutBranch({ cwd, branch: resolvedBranch }));
+    yield* gitCore.createRef({ cwd, refName: resolvedBranch });
+    yield* Effect.scoped(gitCore.switchRef({ cwd, refName: resolvedBranch }));
 
     return {
       branchStep: { status: "created" as const, name: resolvedBranch },
@@ -1563,12 +1614,6 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
             "Feature-branch checkout is only supported for commit actions.",
           );
         }
-        if (input.action === "push" && initialStatus.hasWorkingTreeChanges) {
-          return yield* gitManagerError(
-            "runStackedAction",
-            "Commit or stash local changes before pushing.",
-          );
-        }
         if (input.action === "create_pr" && initialStatus.hasWorkingTreeChanges) {
           return yield* gitManagerError(
             "runStackedAction",
@@ -1632,6 +1677,12 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
 
         const currentBranch = branchStep.name ?? initialStatus.branch;
         const commitAction = isCommitAction(input.action) ? input.action : null;
+        const changeRequestTerms = wantsPr
+          ? yield* sourceControlProvider(input.cwd).pipe(
+              Effect.map((provider) => getChangeRequestTerminologyForKind(provider.kind)),
+              Effect.catch(() => Effect.succeed(getChangeRequestTerminologyForKind("unknown"))),
+            )
+          : null;
 
         const commit = commitAction
           ? yield* Ref.set(currentPhase, Option.some("commit")).pipe(
@@ -1669,7 +1720,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
               .emit({
                 kind: "phase_started",
                 phase: "pr",
-                label: "Preparing PR...",
+                label: `Preparing ${changeRequestTerms?.shortLabel ?? "PR"}...`,
               })
               .pipe(
                 Effect.tap(() => Ref.set(currentPhase, Option.some("pr"))),
@@ -1730,4 +1781,4 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
   } satisfies GitManagerShape;
 });
 
-export const GitManagerLive = Layer.effect(GitManager, makeGitManager());
+export const layer = Layer.effect(GitManager, makeGitManager());
diff --git a/apps/server/src/git/GitWorkflowService.test.ts b/apps/server/src/git/GitWorkflowService.test.ts
new file mode 100644
index 00000000000..9a34680496f
--- /dev/null
+++ b/apps/server/src/git/GitWorkflowService.test.ts
@@ -0,0 +1,133 @@
+import { assert, describe, it, vi } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import * as GitManager from "./GitManager.ts";
+import * as GitWorkflowService from "./GitWorkflowService.ts";
+import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
+import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
+
+function makeLayer(input: { readonly detect: VcsDriverRegistry.VcsDriverRegistryShape["detect"] }) {
+  return GitWorkflowService.layer.pipe(
+    Layer.provide(
+      Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
+        detect: input.detect,
+      }),
+    ),
+    Layer.provide(Layer.mock(GitVcsDriver.GitVcsDriver)({})),
+    Layer.provide(Layer.mock(GitManager.GitManager)({})),
+  );
+}
+
+describe("GitWorkflowService", () => {
+  it.effect("returns an empty local status when no VCS repository is detected", () =>
+    Effect.gen(function* () {
+      const workflow = yield* GitWorkflowService.GitWorkflowService;
+      const status = yield* workflow.localStatus({ cwd: "/not-a-repo" });
+
+      assert.deepStrictEqual(status, {
+        isRepo: false,
+        hasPrimaryRemote: false,
+        isDefaultRef: false,
+        refName: null,
+        hasWorkingTreeChanges: false,
+        workingTree: {
+          files: [],
+          insertions: 0,
+          deletions: 0,
+        },
+      });
+    }).pipe(
+      Effect.provide(
+        makeLayer({
+          detect: () => Effect.succeed(null),
+        }),
+      ),
+    ),
+  );
+
+  it.effect("returns an empty full status when no VCS repository is detected", () =>
+    Effect.gen(function* () {
+      const workflow = yield* GitWorkflowService.GitWorkflowService;
+      const status = yield* workflow.status({ cwd: "/not-a-repo" });
+
+      assert.deepStrictEqual(status, {
+        isRepo: false,
+        hasPrimaryRemote: false,
+        isDefaultRef: false,
+        refName: null,
+        hasWorkingTreeChanges: false,
+        workingTree: {
+          files: [],
+          insertions: 0,
+          deletions: 0,
+        },
+        hasUpstream: false,
+        aheadCount: 0,
+        behindCount: 0,
+        aheadOfDefaultCount: 0,
+        pr: null,
+      });
+    }).pipe(
+      Effect.provide(
+        makeLayer({
+          detect: () => Effect.succeed(null),
+        }),
+      ),
+    ),
+  );
+
+  it.effect("does not call GitManager status methods when no VCS repository is detected", () => {
+    const localStatus = vi.fn();
+    const remoteStatus = vi.fn();
+    const status = vi.fn();
+
+    const testLayer = GitWorkflowService.layer.pipe(
+      Layer.provide(
+        Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
+          detect: () => Effect.succeed(null),
+        }),
+      ),
+      Layer.provide(Layer.mock(GitVcsDriver.GitVcsDriver)({})),
+      Layer.provide(
+        Layer.mock(GitManager.GitManager)({
+          localStatus,
+          remoteStatus,
+          status,
+        }),
+      ),
+    );
+
+    return Effect.gen(function* () {
+      const workflow = yield* GitWorkflowService.GitWorkflowService;
+      yield* workflow.localStatus({ cwd: "/not-a-repo" });
+      yield* workflow.remoteStatus({ cwd: "/not-a-repo" });
+      yield* workflow.status({ cwd: "/not-a-repo" });
+
+      assert.equal(localStatus.mock.calls.length, 0);
+      assert.equal(remoteStatus.mock.calls.length, 0);
+      assert.equal(status.mock.calls.length, 0);
+    }).pipe(Effect.provide(testLayer));
+  });
+
+  it.effect("returns an empty ref list when no VCS repository is detected", () =>
+    Effect.gen(function* () {
+      const workflow = yield* GitWorkflowService.GitWorkflowService;
+      const refs = yield* workflow.listRefs({ cwd: "/not-a-repo" });
+
+      assert.deepStrictEqual(refs, {
+        refs: [],
+        isRepo: false,
+        hasPrimaryRemote: false,
+        nextCursor: null,
+        totalCount: 0,
+      });
+    }).pipe(
+      Effect.provide(
+        makeLayer({
+          detect: () => Effect.succeed(null),
+        }),
+      ),
+    ),
+  );
+});
diff --git a/apps/server/src/git/GitWorkflowService.ts b/apps/server/src/git/GitWorkflowService.ts
new file mode 100644
index 00000000000..74064450fcb
--- /dev/null
+++ b/apps/server/src/git/GitWorkflowService.ts
@@ -0,0 +1,316 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import {
+  GitManagerError,
+  GitCommandError,
+  type VcsSwitchRefInput,
+  type VcsSwitchRefResult,
+  type VcsCreateRefInput,
+  type VcsCreateRefResult,
+  type VcsCreateWorktreeInput,
+  type VcsCreateWorktreeResult,
+  type VcsListRefsInput,
+  type VcsListRefsResult,
+  type GitManagerServiceError,
+  type GitPreparePullRequestThreadInput,
+  type GitPreparePullRequestThreadResult,
+  type GitPullRequestRefInput,
+  type VcsPullResult,
+  type VcsRemoveWorktreeInput,
+  type GitResolvePullRequestResult,
+  type GitRunStackedActionInput,
+  type GitRunStackedActionResult,
+  type VcsStatusInput,
+  type VcsStatusLocalResult,
+  type VcsStatusRemoteResult,
+  type VcsStatusResult,
+} from "@t3tools/contracts";
+
+import { GitManager, type GitRunStackedActionOptions } from "./GitManager.ts";
+import { GitVcsDriver } from "../vcs/GitVcsDriver.ts";
+import { VcsDriverRegistry } from "../vcs/VcsDriverRegistry.ts";
+
+export interface GitWorkflowServiceShape {
+  readonly status: (
+    input: VcsStatusInput,
+  ) => Effect.Effect<VcsStatusResult, GitManagerServiceError>;
+  readonly localStatus: (
+    input: VcsStatusInput,
+  ) => Effect.Effect<VcsStatusLocalResult, GitManagerServiceError>;
+  readonly remoteStatus: (
+    input: VcsStatusInput,
+  ) => Effect.Effect<VcsStatusRemoteResult | null, GitManagerServiceError>;
+  readonly invalidateLocalStatus: (cwd: string) => Effect.Effect<void, never>;
+  readonly invalidateRemoteStatus: (cwd: string) => Effect.Effect<void, never>;
+  readonly invalidateStatus: (cwd: string) => Effect.Effect<void, never>;
+  readonly pullCurrentBranch: (cwd: string) => Effect.Effect<VcsPullResult, GitCommandError>;
+  readonly runStackedAction: (
+    input: GitRunStackedActionInput,
+    options?: GitRunStackedActionOptions,
+  ) => Effect.Effect<GitRunStackedActionResult, GitManagerServiceError>;
+  readonly resolvePullRequest: (
+    input: GitPullRequestRefInput,
+  ) => Effect.Effect<GitResolvePullRequestResult, GitManagerServiceError>;
+  readonly preparePullRequestThread: (
+    input: GitPreparePullRequestThreadInput,
+  ) => Effect.Effect<GitPreparePullRequestThreadResult, GitManagerServiceError>;
+  readonly listRefs: (input: VcsListRefsInput) => Effect.Effect<VcsListRefsResult, GitCommandError>;
+  readonly createWorktree: (
+    input: VcsCreateWorktreeInput,
+  ) => Effect.Effect<VcsCreateWorktreeResult, GitCommandError>;
+  readonly removeWorktree: (input: VcsRemoveWorktreeInput) => Effect.Effect<void, GitCommandError>;
+  readonly createRef: (
+    input: VcsCreateRefInput,
+  ) => Effect.Effect<VcsCreateRefResult, GitCommandError>;
+  readonly switchRef: (
+    input: VcsSwitchRefInput,
+  ) => Effect.Effect<VcsSwitchRefResult, GitCommandError>;
+  readonly renameBranch: (input: {
+    readonly cwd: string;
+    readonly oldBranch: string;
+    readonly newBranch: string;
+  }) => Effect.Effect<{ readonly branch: string }, GitManagerServiceError>;
+}
+
+export class GitWorkflowService extends Context.Service<
+  GitWorkflowService,
+  GitWorkflowServiceShape
+>()("t3/git/GitWorkflowService") {}
+
+const unsupportedGitWorkflow = (operation: string, cwd: string, detail: string) =>
+  new GitManagerError({
+    operation,
+    detail: `${detail} (${cwd})`,
+  });
+
+const unsupportedGitCommand = (operation: string, cwd: string, detail: string) =>
+  new GitCommandError({
+    operation,
+    command: "vcs-route",
+    cwd,
+    detail,
+  });
+
+function nonRepositoryLocalStatus(): VcsStatusLocalResult {
+  return {
+    isRepo: false,
+    hasPrimaryRemote: false,
+    isDefaultRef: false,
+    refName: null,
+    hasWorkingTreeChanges: false,
+    workingTree: {
+      files: [],
+      insertions: 0,
+      deletions: 0,
+    },
+  };
+}
+
+function nonRepositoryStatus(): VcsStatusResult {
+  return {
+    ...nonRepositoryLocalStatus(),
+    hasUpstream: false,
+    aheadCount: 0,
+    behindCount: 0,
+    aheadOfDefaultCount: 0,
+    pr: null,
+  };
+}
+
+function nonRepositoryListRefs(): VcsListRefsResult {
+  return {
+    refs: [],
+    isRepo: false,
+    hasPrimaryRemote: false,
+    nextCursor: null,
+    totalCount: 0,
+  };
+}
+
+export const make = Effect.fn("makeGitWorkflowService")(function* () {
+  const registry = yield* VcsDriverRegistry;
+  const git = yield* GitVcsDriver;
+  const gitManager = yield* GitManager;
+
+  const ensureGit = Effect.fn("GitWorkflowService.ensureGit")(function* (
+    operation: string,
+    cwd: string,
+  ) {
+    const handle = yield* registry
+      .resolve({ cwd })
+      .pipe(
+        Effect.mapError((error) =>
+          unsupportedGitWorkflow(
+            operation,
+            cwd,
+            error instanceof Error ? error.message : String(error),
+          ),
+        ),
+      );
+    if (handle.kind !== "git") {
+      return yield* unsupportedGitWorkflow(
+        operation,
+        cwd,
+        `The ${operation} workflow currently supports Git repositories only; detected ${handle.kind}.`,
+      );
+    }
+  });
+
+  const ensureGitCommand = Effect.fn("GitWorkflowService.ensureGitCommand")(function* (
+    operation: string,
+    cwd: string,
+  ) {
+    const handle = yield* registry
+      .resolve({ cwd })
+      .pipe(
+        Effect.mapError((error) =>
+          unsupportedGitCommand(
+            operation,
+            cwd,
+            error instanceof Error ? error.message : String(error),
+          ),
+        ),
+      );
+    if (handle.kind !== "git") {
+      return yield* unsupportedGitCommand(
+        operation,
+        cwd,
+        `The ${operation} command currently supports Git repositories only; detected ${handle.kind}.`,
+      );
+    }
+  });
+
+  const detectGitRepositoryForStatus = Effect.fn("GitWorkflowService.detectGitRepositoryForStatus")(
+    function* (operation: string, cwd: string) {
+      const handle = yield* registry
+        .detect({ cwd })
+        .pipe(
+          Effect.mapError((error) =>
+            unsupportedGitWorkflow(
+              operation,
+              cwd,
+              error instanceof Error ? error.message : String(error),
+            ),
+          ),
+        );
+      if (!handle) {
+        return false;
+      }
+      if (handle.kind !== "git") {
+        return yield* unsupportedGitWorkflow(
+          operation,
+          cwd,
+          `The ${operation} workflow currently supports Git repositories only; detected ${handle.kind}.`,
+        );
+      }
+      return true;
+    },
+  );
+
+  const detectGitRepositoryForCommand = Effect.fn(
+    "GitWorkflowService.detectGitRepositoryForCommand",
+  )(function* (operation: string, cwd: string) {
+    const handle = yield* registry
+      .detect({ cwd })
+      .pipe(
+        Effect.mapError((error) =>
+          unsupportedGitCommand(
+            operation,
+            cwd,
+            error instanceof Error ? error.message : String(error),
+          ),
+        ),
+      );
+    if (!handle) {
+      return false;
+    }
+    if (handle.kind !== "git") {
+      return yield* unsupportedGitCommand(
+        operation,
+        cwd,
+        `The ${operation} command currently supports Git repositories only; detected ${handle.kind}.`,
+      );
+    }
+    return true;
+  });
+
+  const routeGitManager =
+    <Input extends { readonly cwd: string }, Output>(
+      operation: string,
+      run: (input: Input) => Effect.Effect<Output, GitManagerServiceError>,
+    ) =>
+    (input: Input) =>
+      ensureGit(operation, input.cwd).pipe(Effect.andThen(run(input)));
+
+  return GitWorkflowService.of({
+    status: (input) =>
+      detectGitRepositoryForStatus("GitWorkflowService.status", input.cwd).pipe(
+        Effect.flatMap((isGitRepository) =>
+          isGitRepository ? gitManager.status(input) : Effect.succeed(nonRepositoryStatus()),
+        ),
+      ),
+    localStatus: (input) =>
+      detectGitRepositoryForStatus("GitWorkflowService.localStatus", input.cwd).pipe(
+        Effect.flatMap((isGitRepository) =>
+          isGitRepository
+            ? gitManager.localStatus(input)
+            : Effect.succeed(nonRepositoryLocalStatus()),
+        ),
+      ),
+    remoteStatus: (input) =>
+      detectGitRepositoryForStatus("GitWorkflowService.remoteStatus", input.cwd).pipe(
+        Effect.flatMap((isGitRepository) =>
+          isGitRepository ? gitManager.remoteStatus(input) : Effect.succeed(null),
+        ),
+      ),
+    invalidateLocalStatus: gitManager.invalidateLocalStatus,
+    invalidateRemoteStatus: gitManager.invalidateRemoteStatus,
+    invalidateStatus: gitManager.invalidateStatus,
+    pullCurrentBranch: (cwd) =>
+      ensureGitCommand("GitWorkflowService.pullCurrentBranch", cwd).pipe(
+        Effect.andThen(git.pullCurrentBranch(cwd)),
+      ),
+    runStackedAction: (input, options) =>
+      ensureGit("GitWorkflowService.runStackedAction", input.cwd).pipe(
+        Effect.andThen(gitManager.runStackedAction(input, options)),
+      ),
+    resolvePullRequest: routeGitManager(
+      "GitWorkflowService.resolvePullRequest",
+      gitManager.resolvePullRequest,
+    ),
+    preparePullRequestThread: routeGitManager(
+      "GitWorkflowService.preparePullRequestThread",
+      gitManager.preparePullRequestThread,
+    ),
+    listRefs: (input) =>
+      detectGitRepositoryForCommand("GitWorkflowService.listRefs", input.cwd).pipe(
+        Effect.flatMap((isGitRepository) =>
+          isGitRepository ? git.listRefs(input) : Effect.succeed(nonRepositoryListRefs()),
+        ),
+      ),
+    createWorktree: (input) =>
+      ensureGitCommand("GitWorkflowService.createWorktree", input.cwd).pipe(
+        Effect.andThen(git.createWorktree(input)),
+      ),
+    removeWorktree: (input) =>
+      ensureGitCommand("GitWorkflowService.removeWorktree", input.cwd).pipe(
+        Effect.andThen(git.removeWorktree(input)),
+      ),
+    createRef: (input) =>
+      ensureGitCommand("GitWorkflowService.createRef", input.cwd).pipe(
+        Effect.andThen(git.createRef(input)),
+      ),
+    switchRef: (input) =>
+      ensureGitCommand("GitWorkflowService.switchRef", input.cwd).pipe(
+        Effect.andThen(Effect.scoped(git.switchRef(input))),
+      ),
+    renameBranch: (input) =>
+      ensureGit("GitWorkflowService.renameBranch", input.cwd).pipe(
+        Effect.andThen(git.renameBranch(input)),
+      ),
+  });
+});
+
+export const layer = Layer.effect(GitWorkflowService, make());
diff --git a/apps/server/src/git/Layers/ClaudeTextGeneration.test.ts b/apps/server/src/git/Layers/ClaudeTextGeneration.test.ts
deleted file mode 100644
index 08471346989..00000000000
--- a/apps/server/src/git/Layers/ClaudeTextGeneration.test.ts
+++ /dev/null
@@ -1,309 +0,0 @@
-import * as NodeServices from "@effect/platform-node/NodeServices";
-import { it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path } from "effect";
-import { expect } from "vitest";
-
-import { ServerConfig } from "../../config.ts";
-import { TextGeneration } from "../Services/TextGeneration.ts";
-import { sanitizeThreadTitle } from "../Utils.ts";
-import { ClaudeTextGenerationLive } from "./ClaudeTextGeneration.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-
-const ClaudeTextGenerationTestLayer = ClaudeTextGenerationLive.pipe(
-  Layer.provideMerge(ServerSettingsService.layerTest()),
-  Layer.provideMerge(
-    ServerConfig.layerTest(process.cwd(), {
-      prefix: "t3code-claude-text-generation-test-",
-    }),
-  ),
-  Layer.provideMerge(NodeServices.layer),
-);
-
-function makeFakeClaudeBinary(dir: string) {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = path.join(dir, "bin");
-    const claudePath = path.join(binDir, "claude");
-    yield* fs.makeDirectory(binDir, { recursive: true });
-
-    yield* fs.writeFileString(
-      claudePath,
-      [
-        "#!/bin/sh",
-        'args="$*"',
-        'stdin_content="$(cat)"',
-        'if [ -n "$T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN" ]; then',
-        '  printf "%s" "$args" | grep -F -- "$T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN" >/dev/null || {',
-        '    printf "%s\\n" "args missing expected content" >&2',
-        "    exit 2",
-        "  }",
-        "fi",
-        'if [ -n "$T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN" ]; then',
-        '  if printf "%s" "$args" | grep -F -- "$T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN" >/dev/null; then',
-        '    printf "%s\\n" "args contained forbidden content" >&2',
-        "    exit 3",
-        "  fi",
-        "fi",
-        'if [ -n "$T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN" ]; then',
-        '  printf "%s" "$stdin_content" | grep -F -- "$T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN" >/dev/null || {',
-        '    printf "%s\\n" "stdin missing expected content" >&2',
-        "    exit 4",
-        "  }",
-        "fi",
-        'if [ -n "$T3_FAKE_CLAUDE_STDERR" ]; then',
-        '  printf "%s\\n" "$T3_FAKE_CLAUDE_STDERR" >&2',
-        "fi",
-        'printf "%s" "$T3_FAKE_CLAUDE_OUTPUT"',
-        'exit "${T3_FAKE_CLAUDE_EXIT_CODE:-0}"',
-        "",
-      ].join("\n"),
-    );
-    yield* fs.chmod(claudePath, 0o755);
-    return binDir;
-  });
-}
-
-function withFakeClaudeEnv<A, E, R>(
-  input: {
-    output: string;
-    exitCode?: number;
-    stderr?: string;
-    argsMustContain?: string;
-    argsMustNotContain?: string;
-    stdinMustContain?: string;
-  },
-  effect: Effect.Effect<A, E, R>,
-) {
-  return Effect.acquireUseRelease(
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-claude-text-" });
-      const binDir = yield* makeFakeClaudeBinary(tempDir);
-      const previousPath = process.env.PATH;
-      const previousOutput = process.env.T3_FAKE_CLAUDE_OUTPUT;
-      const previousExitCode = process.env.T3_FAKE_CLAUDE_EXIT_CODE;
-      const previousStderr = process.env.T3_FAKE_CLAUDE_STDERR;
-      const previousArgsMustContain = process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN;
-      const previousArgsMustNotContain = process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN;
-      const previousStdinMustContain = process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN;
-
-      yield* Effect.sync(() => {
-        process.env.PATH = `${binDir}:${previousPath ?? ""}`;
-        process.env.T3_FAKE_CLAUDE_OUTPUT = input.output;
-
-        if (input.exitCode !== undefined) {
-          process.env.T3_FAKE_CLAUDE_EXIT_CODE = String(input.exitCode);
-        } else {
-          delete process.env.T3_FAKE_CLAUDE_EXIT_CODE;
-        }
-
-        if (input.stderr !== undefined) {
-          process.env.T3_FAKE_CLAUDE_STDERR = input.stderr;
-        } else {
-          delete process.env.T3_FAKE_CLAUDE_STDERR;
-        }
-
-        if (input.argsMustContain !== undefined) {
-          process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN = input.argsMustContain;
-        } else {
-          delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN;
-        }
-
-        if (input.argsMustNotContain !== undefined) {
-          process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN = input.argsMustNotContain;
-        } else {
-          delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN;
-        }
-
-        if (input.stdinMustContain !== undefined) {
-          process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN = input.stdinMustContain;
-        } else {
-          delete process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN;
-        }
-      });
-
-      return {
-        previousPath,
-        previousOutput,
-        previousExitCode,
-        previousStderr,
-        previousArgsMustContain,
-        previousArgsMustNotContain,
-        previousStdinMustContain,
-      };
-    }),
-    () => effect,
-    (previous) =>
-      Effect.sync(() => {
-        process.env.PATH = previous.previousPath;
-
-        if (previous.previousOutput === undefined) {
-          delete process.env.T3_FAKE_CLAUDE_OUTPUT;
-        } else {
-          process.env.T3_FAKE_CLAUDE_OUTPUT = previous.previousOutput;
-        }
-
-        if (previous.previousExitCode === undefined) {
-          delete process.env.T3_FAKE_CLAUDE_EXIT_CODE;
-        } else {
-          process.env.T3_FAKE_CLAUDE_EXIT_CODE = previous.previousExitCode;
-        }
-
-        if (previous.previousStderr === undefined) {
-          delete process.env.T3_FAKE_CLAUDE_STDERR;
-        } else {
-          process.env.T3_FAKE_CLAUDE_STDERR = previous.previousStderr;
-        }
-
-        if (previous.previousArgsMustContain === undefined) {
-          delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN;
-        } else {
-          process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN = previous.previousArgsMustContain;
-        }
-
-        if (previous.previousArgsMustNotContain === undefined) {
-          delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN;
-        } else {
-          process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN = previous.previousArgsMustNotContain;
-        }
-
-        if (previous.previousStdinMustContain === undefined) {
-          delete process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN;
-        } else {
-          process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN = previous.previousStdinMustContain;
-        }
-      }),
-  );
-}
-
-it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGenerationLive", (it) => {
-  it.effect("forwards Claude thinking settings for Haiku without passing effort", () =>
-    withFakeClaudeEnv(
-      {
-        output: JSON.stringify({
-          structured_output: {
-            subject: "Add important change",
-            body: "",
-          },
-        }),
-        argsMustContain: '--settings {"alwaysThinkingEnabled":false}',
-        argsMustNotContain: "--effort",
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateCommitMessage({
-          cwd: process.cwd(),
-          branch: "feature/claude-effect",
-          stagedSummary: "M README.md",
-          stagedPatch: "diff --git a/README.md b/README.md",
-          modelSelection: {
-            provider: "claudeAgent",
-            model: "claude-haiku-4-5",
-            options: {
-              thinking: false,
-              effort: "high",
-            },
-          },
-        });
-
-        expect(generated.subject).toBe("Add important change");
-      }),
-    ),
-  );
-
-  it.effect("forwards Claude fast mode and supported effort", () =>
-    withFakeClaudeEnv(
-      {
-        output: JSON.stringify({
-          structured_output: {
-            title: "Improve orchestration flow",
-            body: "Body",
-          },
-        }),
-        argsMustContain: '--effort max --settings {"fastMode":true}',
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generatePrContent({
-          cwd: process.cwd(),
-          baseBranch: "main",
-          headBranch: "feature/claude-effect",
-          commitSummary: "Improve orchestration",
-          diffSummary: "1 file changed",
-          diffPatch: "diff --git a/README.md b/README.md",
-          modelSelection: {
-            provider: "claudeAgent",
-            model: "claude-opus-4-6",
-            options: {
-              effort: "max",
-              fastMode: true,
-            },
-          },
-        });
-
-        expect(generated.title).toBe("Improve orchestration flow");
-      }),
-    ),
-  );
-
-  it.effect("generates thread titles through the Claude provider", () =>
-    withFakeClaudeEnv(
-      {
-        output: JSON.stringify({
-          structured_output: {
-            title:
-              '  "Reconnect failures after restart because the session state does not recover"  ',
-          },
-        }),
-        stdinMustContain: "You write concise thread titles for coding conversations.",
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateThreadTitle({
-          cwd: process.cwd(),
-          message: "Please investigate reconnect failures after restarting the session.",
-          modelSelection: {
-            provider: "claudeAgent",
-            model: "claude-sonnet-4-6",
-          },
-        });
-
-        expect(generated.title).toBe(
-          sanitizeThreadTitle(
-            '"Reconnect failures after restart because the session state does not recover"',
-          ),
-        );
-      }),
-    ),
-  );
-
-  it.effect("falls back when Claude thread title normalization becomes whitespace-only", () =>
-    withFakeClaudeEnv(
-      {
-        output: JSON.stringify({
-          structured_output: {
-            title: '  """   """  ',
-          },
-        }),
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateThreadTitle({
-          cwd: process.cwd(),
-          message: "Name this thread.",
-          modelSelection: {
-            provider: "claudeAgent",
-            model: "claude-sonnet-4-6",
-          },
-        });
-
-        expect(generated.title).toBe("New thread");
-      }),
-    ),
-  );
-});
diff --git a/apps/server/src/git/Layers/GitCore.test.ts b/apps/server/src/git/Layers/GitCore.test.ts
deleted file mode 100644
index 665c4b138f9..00000000000
--- a/apps/server/src/git/Layers/GitCore.test.ts
+++ /dev/null
@@ -1,2333 +0,0 @@
-import { existsSync } from "node:fs";
-import path from "node:path";
-
-import * as NodeServices from "@effect/platform-node/NodeServices";
-import { it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, PlatformError, Scope } from "effect";
-import { describe, expect, vi } from "vitest";
-
-import { GitCoreLive, makeGitCore } from "./GitCore.ts";
-import { GitCore, type GitCoreShape } from "../Services/GitCore.ts";
-import { GitCommandError } from "@t3tools/contracts";
-import { type ProcessRunResult, runProcess } from "../../processRunner.ts";
-import { ServerConfig } from "../../config.ts";
-
-// ── Helpers ──
-
-const ServerConfigLayer = ServerConfig.layerTest(process.cwd(), { prefix: "t3-git-core-test-" });
-const GitCoreTestLayer = GitCoreLive.pipe(
-  Layer.provide(ServerConfigLayer),
-  Layer.provide(NodeServices.layer),
-);
-const TestLayer = Layer.mergeAll(NodeServices.layer, GitCoreTestLayer);
-
-function makeTmpDir(
-  prefix = "git-test-",
-): Effect.Effect<string, PlatformError.PlatformError, FileSystem.FileSystem | Scope.Scope> {
-  return Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    return yield* fileSystem.makeTempDirectoryScoped({ prefix });
-  });
-}
-
-function writeTextFile(
-  filePath: string,
-  contents: string,
-): Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem> {
-  return Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    yield* fileSystem.writeFileString(filePath, contents);
-  });
-}
-
-function removePath(
-  targetPath: string,
-): Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem> {
-  return Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    yield* fileSystem.remove(targetPath, { recursive: true, force: true });
-  });
-}
-
-function makeDirectory(
-  dirPath: string,
-): Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem> {
-  return Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    yield* fileSystem.makeDirectory(dirPath, { recursive: true });
-  });
-}
-
-/** Run a raw git command for test setup (not under test). */
-function git(
-  cwd: string,
-  args: ReadonlyArray<string>,
-  env?: NodeJS.ProcessEnv,
-): Effect.Effect<string, GitCommandError, GitCore> {
-  return Effect.gen(function* () {
-    const gitCore = yield* GitCore;
-    const result = yield* gitCore.execute({
-      operation: "GitCore.test.git",
-      cwd,
-      args,
-      ...(env ? { env } : {}),
-      timeoutMs: 10_000,
-    });
-    return result.stdout.trim();
-  });
-}
-
-function configureRemote(
-  cwd: string,
-  remoteName: string,
-  remotePath: string,
-  fetchNamespace: string,
-): Effect.Effect<string, GitCommandError, GitCore> {
-  return Effect.gen(function* () {
-    yield* git(cwd, ["config", `remote.${remoteName}.url`, remotePath]);
-    return yield* git(cwd, [
-      "config",
-      "--replace-all",
-      `remote.${remoteName}.fetch`,
-      `+refs/heads/*:refs/remotes/${fetchNamespace}/*`,
-    ]);
-  });
-}
-
-function runShellCommand(input: {
-  command: string;
-  cwd: string;
-  timeoutMs?: number;
-  maxOutputBytes?: number;
-}): Effect.Effect<ProcessRunResult, Error> {
-  return Effect.promise(() => {
-    const shellPath =
-      process.platform === "win32"
-        ? (process.env.ComSpec ?? "cmd.exe")
-        : (process.env.SHELL ?? "/bin/sh");
-
-    const args =
-      process.platform === "win32" ? ["/d", "/s", "/c", input.command] : ["-lc", input.command];
-
-    return runProcess(shellPath, args, {
-      cwd: input.cwd,
-      timeoutMs: input.timeoutMs ?? 30_000,
-      allowNonZeroExit: true,
-      maxBufferBytes: input.maxOutputBytes ?? 1_000_000,
-      outputMode: "truncate",
-    });
-  });
-}
-
-const makeIsolatedGitCore = (executeOverride: GitCoreShape["execute"]) =>
-  makeGitCore({ executeOverride }).pipe(
-    Effect.provide(Layer.provideMerge(ServerConfigLayer, NodeServices.layer)),
-  );
-
-/** Create a repo with an initial commit so branches work. */
-function initRepoWithCommit(
-  cwd: string,
-): Effect.Effect<
-  { initialBranch: string },
-  GitCommandError | PlatformError.PlatformError,
-  GitCore | FileSystem.FileSystem
-> {
-  return Effect.gen(function* () {
-    const core = yield* GitCore;
-    yield* core.initRepo({ cwd });
-    yield* git(cwd, ["config", "user.email", "test@test.com"]);
-    yield* git(cwd, ["config", "user.name", "Test"]);
-    yield* writeTextFile(path.join(cwd, "README.md"), "# test\n");
-    yield* git(cwd, ["add", "."]);
-    yield* git(cwd, ["commit", "-m", "initial commit"]);
-    const initialBranch = yield* git(cwd, ["branch", "--show-current"]);
-    return { initialBranch };
-  });
-}
-
-function commitWithDate(
-  cwd: string,
-  fileName: string,
-  fileContents: string,
-  dateIsoString: string,
-  message: string,
-): Effect.Effect<
-  void,
-  GitCommandError | PlatformError.PlatformError,
-  GitCore | FileSystem.FileSystem
-> {
-  return Effect.gen(function* () {
-    yield* writeTextFile(path.join(cwd, fileName), fileContents);
-    yield* git(cwd, ["add", fileName]);
-    yield* git(cwd, ["commit", "-m", message], {
-      ...process.env,
-      GIT_AUTHOR_DATE: dateIsoString,
-      GIT_COMMITTER_DATE: dateIsoString,
-    });
-  });
-}
-
-function buildLargeText(lineCount = 20_000): string {
-  return Array.from({ length: lineCount }, (_, index) => `line ${String(index).padStart(5, "0")}`)
-    .join("\n")
-    .concat("\n");
-}
-
-function splitNullSeparatedPaths(input: string): string[] {
-  return input
-    .split("\0")
-    .map((value) => value.trim())
-    .filter((value) => value.length > 0);
-}
-
-// ── Tests ──
-
-it.layer(TestLayer)("git integration", (it) => {
-  describe("shell process execution", () => {
-    it.effect("caps captured output when maxOutputBytes is exceeded", () =>
-      Effect.gen(function* () {
-        const result = yield* runShellCommand({
-          command: `node -e "process.stdout.write('x'.repeat(2000))"`,
-          cwd: process.cwd(),
-          timeoutMs: 10_000,
-          maxOutputBytes: 128,
-        });
-
-        expect(result.code).toBe(0);
-        expect(result.stdout.length).toBeLessThanOrEqual(128);
-        expect(result.stdoutTruncated || result.stderrTruncated).toBe(true);
-      }),
-    );
-  });
-
-  // ── initGitRepo ──
-
-  describe("initGitRepo", () => {
-    it.effect("creates a valid git repo", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* (yield* GitCore).initRepo({ cwd: tmp });
-        expect(existsSync(path.join(tmp, ".git"))).toBe(true);
-      }),
-    );
-
-    it.effect("listGitBranches reports isRepo: true after init + commit", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.isRepo).toBe(true);
-        expect(result.hasOriginRemote).toBe(false);
-        expect(result.branches.length).toBeGreaterThanOrEqual(1);
-      }),
-    );
-  });
-
-  describe("workspace helpers", () => {
-    it.effect("filterIgnoredPaths chunks large path lists and preserves kept paths", () =>
-      Effect.gen(function* () {
-        const cwd = "/virtual/repo";
-        const relativePaths = Array.from({ length: 340 }, (_, index) => {
-          const prefix = index % 3 === 0 ? "ignored" : "kept";
-          return `${prefix}/segment-${String(index).padStart(4, "0")}/${"x".repeat(900)}.ts`;
-        });
-        const expectedPaths = relativePaths.filter(
-          (relativePath) => !relativePath.startsWith("ignored/"),
-        );
-
-        const seenChunks: string[][] = [];
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (
-            input.args.join(" ") !==
-            "-c core.fsmonitor=false -c core.untrackedCache=false check-ignore --no-index -z --stdin"
-          ) {
-            return Effect.fail(
-              new GitCommandError({
-                operation: input.operation,
-                command: `git ${input.args.join(" ")}`,
-                cwd: input.cwd,
-                detail: "unexpected git command in chunking test",
-              }),
-            );
-          }
-
-          const chunkPaths = splitNullSeparatedPaths(input.stdin ?? "");
-          seenChunks.push(chunkPaths);
-          const ignoredPaths = chunkPaths.filter((relativePath) =>
-            relativePath.startsWith("ignored/"),
-          );
-
-          return Effect.succeed({
-            code: ignoredPaths.length > 0 ? 0 : 1,
-            stdout: ignoredPaths.length > 0 ? `${ignoredPaths.join("\0")}\0` : "",
-            stderr: "",
-            stdoutTruncated: false,
-            stderrTruncated: false,
-          });
-        });
-
-        const result = yield* core.filterIgnoredPaths(cwd, relativePaths);
-
-        expect(seenChunks.length).toBeGreaterThan(1);
-        expect(seenChunks.flat()).toEqual(relativePaths);
-        expect(result).toEqual(expectedPaths);
-      }),
-    );
-
-    it.effect("listWorkspaceFiles disables fsmonitor and untracked cache helpers", () =>
-      Effect.gen(function* () {
-        const core = yield* makeIsolatedGitCore((input) => {
-          expect(input.args).toEqual([
-            "-c",
-            "core.fsmonitor=false",
-            "-c",
-            "core.untrackedCache=false",
-            "ls-files",
-            "--cached",
-            "--others",
-            "--exclude-standard",
-            "-z",
-          ]);
-          return Effect.succeed({
-            code: 0,
-            stdout: "src/index.ts\0README.md\0",
-            stderr: "",
-            stdoutTruncated: false,
-            stderrTruncated: false,
-          });
-        });
-
-        const result = yield* core.listWorkspaceFiles("/virtual/repo");
-        expect(result.paths).toEqual(["src/index.ts", "README.md"]);
-        expect(result.truncated).toBe(false);
-      }),
-    );
-  });
-
-  // ── listGitBranches ──
-
-  describe("listGitBranches", () => {
-    it.effect("returns isRepo: false for non-git directory", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.isRepo).toBe(false);
-        expect(result.hasOriginRemote).toBe(false);
-        expect(result.branches).toEqual([]);
-      }),
-    );
-
-    it.effect("returns isRepo: false for deleted directories", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const deletedDir = path.join(tmp, "deleted-repo");
-        yield* makeDirectory(deletedDir);
-        yield* removePath(deletedDir);
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: deletedDir });
-
-        expect(result.isRepo).toBe(false);
-        expect(result.hasOriginRemote).toBe(false);
-        expect(result.branches).toEqual([]);
-      }),
-    );
-
-    it.effect("returns the current branch with current: true", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const current = result.branches.find((b) => b.current);
-        expect(current).toBeDefined();
-        expect(current!.current).toBe(true);
-      }),
-    );
-
-    it.effect("does not include detached HEAD pseudo-refs as branches", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* git(tmp, ["checkout", "--detach", "HEAD"]);
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.branches.some((branch) => branch.name.startsWith("("))).toBe(false);
-        expect(result.branches.some((branch) => branch.current)).toBe(false);
-      }),
-    );
-
-    it.effect("keeps current branch first and sorts the remaining branches by recency", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const initialBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "older-branch" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "older-branch" });
-        yield* commitWithDate(
-          tmp,
-          "older.txt",
-          "older branch change\n",
-          "Thu, 1 Jan 2037 00:00:00 +0000",
-          "older branch change",
-        );
-
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: initialBranch });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "newer-branch" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "newer-branch" });
-        yield* commitWithDate(
-          tmp,
-          "newer.txt",
-          "newer branch change\n",
-          "Fri, 1 Jan 2038 00:00:00 +0000",
-          "newer branch change",
-        );
-
-        // Switch away to show current branch is pinned, then remaining branches are recency-sorted.
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "older-branch" });
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.branches[0]!.name).toBe("older-branch");
-        expect(result.branches[1]!.name).toBe("newer-branch");
-      }),
-    );
-
-    it.effect("keeps default branch right after current branch", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const remote = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-
-        yield* git(remote, ["init", "--bare"]);
-        yield* git(tmp, ["remote", "add", "origin", remote]);
-        yield* git(tmp, ["push", "-u", "origin", defaultBranch]);
-        yield* git(tmp, ["remote", "set-head", "origin", defaultBranch]);
-
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "current-branch" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "current-branch" });
-        yield* commitWithDate(
-          tmp,
-          "current.txt",
-          "current change\n",
-          "Thu, 1 Jan 2037 00:00:00 +0000",
-          "current change",
-        );
-
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: defaultBranch });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "newer-branch" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "newer-branch" });
-        yield* commitWithDate(
-          tmp,
-          "newer.txt",
-          "newer change\n",
-          "Fri, 1 Jan 2038 00:00:00 +0000",
-          "newer change",
-        );
-
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "current-branch" });
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.branches[0]!.name).toBe("current-branch");
-        expect(result.branches[1]!.name).toBe(defaultBranch);
-        expect(result.branches[2]!.name).toBe("newer-branch");
-      }),
-    );
-
-    it.effect("lists multiple branches after creating them", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature-a" });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature-b" });
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const names = result.branches.map((b) => b.name);
-        expect(names).toContain("feature-a");
-        expect(names).toContain("feature-b");
-      }),
-    );
-
-    it.effect("paginates branch results and returns paging metadata", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const { initialBranch } = yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature-a" });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature-b" });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature-c" });
-
-        const firstPage = yield* (yield* GitCore).listBranches({ cwd: tmp, limit: 2 });
-        expect(firstPage.totalCount).toBe(4);
-        expect(firstPage.nextCursor).toBe(2);
-        expect(firstPage.branches.map((branch) => branch.name)).toEqual([
-          initialBranch,
-          "feature-a",
-        ]);
-
-        const secondPage = yield* (yield* GitCore).listBranches({
-          cwd: tmp,
-          cursor: firstPage.nextCursor ?? 0,
-          limit: 2,
-        });
-        expect(secondPage.totalCount).toBe(4);
-        expect(secondPage.nextCursor).toBeNull();
-        expect(secondPage.branches.map((branch) => branch.name)).toEqual([
-          "feature-b",
-          "feature-c",
-        ]);
-      }),
-    );
-
-    it.effect("parses separate branch names when column.ui is always enabled", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const { initialBranch } = yield* initRepoWithCommit(tmp);
-        const createdBranchNames = [
-          "go-bin",
-          "copilot/rewrite-cli-in-go",
-          "copilot/rewrite-cli-in-rust",
-        ] as const;
-        for (const branchName of createdBranchNames) {
-          yield* (yield* GitCore).createBranch({ cwd: tmp, branch: branchName });
-        }
-        yield* git(tmp, ["config", "column.ui", "always"]);
-
-        const rawBranchOutput = yield* git(tmp, ["branch", "--no-color"], {
-          ...process.env,
-          COLUMNS: "120",
-        });
-        expect(
-          rawBranchOutput
-            .split("\n")
-            .some(
-              (line) =>
-                createdBranchNames.filter((branchName) => line.includes(branchName)).length >= 2,
-            ),
-        ).toBe(true);
-
-        const realGitCore = yield* GitCore;
-        const core = yield* makeIsolatedGitCore((input) =>
-          realGitCore.execute(
-            input.args[0] === "branch"
-              ? {
-                  ...input,
-                  env: { ...input.env, COLUMNS: "120" },
-                }
-              : input,
-          ),
-        );
-
-        const result = yield* core.listBranches({ cwd: tmp });
-        const localBranchNames = result.branches
-          .filter((branch) => !branch.isRemote)
-          .map((branch) => branch.name);
-
-        expect(localBranchNames).toHaveLength(4);
-        expect(localBranchNames).toEqual(
-          expect.arrayContaining([initialBranch, ...createdBranchNames]),
-        );
-        expect(
-          localBranchNames.some(
-            (branchName) =>
-              createdBranchNames.filter((createdBranch) => branchName.includes(createdBranch))
-                .length >= 2,
-          ),
-        ).toBe(false);
-      }),
-    );
-
-    it.effect("isDefault is false when no remote exists", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.branches.every((b) => b.isDefault === false)).toBe(true);
-      }),
-    );
-
-    it.effect("lists local branches first and remote branches last", () =>
-      Effect.gen(function* () {
-        const remote = yield* makeTmpDir();
-        const tmp = yield* makeTmpDir();
-
-        yield* git(remote, ["init", "--bare"]);
-        yield* initRepoWithCommit(tmp);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-
-        yield* git(tmp, ["remote", "add", "origin", remote]);
-        yield* git(tmp, ["push", "-u", "origin", defaultBranch]);
-
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature/local-only" });
-
-        const remoteOnlyBranch = "feature/remote-only";
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: defaultBranch });
-        yield* git(tmp, ["checkout", "-b", remoteOnlyBranch]);
-        yield* git(tmp, ["push", "-u", "origin", remoteOnlyBranch]);
-        yield* git(tmp, ["checkout", defaultBranch]);
-        yield* git(tmp, ["branch", "-D", remoteOnlyBranch]);
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const firstRemoteIndex = result.branches.findIndex((branch) => branch.isRemote);
-
-        expect(result.hasOriginRemote).toBe(true);
-        expect(firstRemoteIndex).toBeGreaterThan(0);
-        expect(result.branches.slice(0, firstRemoteIndex).every((branch) => !branch.isRemote)).toBe(
-          true,
-        );
-        expect(result.branches.slice(firstRemoteIndex).every((branch) => branch.isRemote)).toBe(
-          true,
-        );
-        expect(
-          result.branches.some(
-            (branch) => branch.name === "feature/local-only" && !branch.isRemote,
-          ),
-        ).toBe(true);
-        expect(
-          result.branches.some(
-            (branch) => branch.name === "origin/feature/remote-only" && branch.isRemote,
-          ),
-        ).toBe(true);
-      }),
-    );
-
-    it.effect("includes remoteName metadata for remotes with slash in the name", () =>
-      Effect.gen(function* () {
-        const remote = yield* makeTmpDir();
-        const tmp = yield* makeTmpDir();
-        const remoteName = "my-org/upstream";
-
-        yield* git(remote, ["init", "--bare"]);
-        yield* initRepoWithCommit(tmp);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-
-        yield* git(tmp, ["remote", "add", remoteName, remote]);
-        yield* git(tmp, ["push", "-u", remoteName, defaultBranch]);
-
-        const remoteOnlyBranch = "feature/remote-with-remote-name";
-        yield* git(tmp, ["checkout", "-b", remoteOnlyBranch]);
-        yield* git(tmp, ["push", "-u", remoteName, remoteOnlyBranch]);
-        yield* git(tmp, ["checkout", defaultBranch]);
-        yield* git(tmp, ["branch", "-D", remoteOnlyBranch]);
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const remoteBranch = result.branches.find(
-          (branch) => branch.name === `${remoteName}/${remoteOnlyBranch}`,
-        );
-
-        expect(remoteBranch).toBeDefined();
-        expect(remoteBranch?.isRemote).toBe(true);
-        expect(remoteBranch?.remoteName).toBe(remoteName);
-      }),
-    );
-
-    it.effect(
-      "filters branch queries before pagination and dedupes origin refs with local matches",
-      () =>
-        Effect.gen(function* () {
-          const remote = yield* makeTmpDir();
-          const tmp = yield* makeTmpDir();
-
-          yield* git(remote, ["init", "--bare"]);
-          const { initialBranch } = yield* initRepoWithCommit(tmp);
-          yield* git(tmp, ["remote", "add", "origin", remote]);
-          yield* git(tmp, ["push", "-u", "origin", initialBranch]);
-
-          yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature/demo" });
-          yield* git(tmp, ["push", "-u", "origin", "feature/demo"]);
-
-          yield* git(tmp, ["checkout", "-b", "feature/remote-only"]);
-          yield* git(tmp, ["push", "-u", "origin", "feature/remote-only"]);
-          yield* git(tmp, ["checkout", initialBranch]);
-          yield* git(tmp, ["branch", "-D", "feature/remote-only"]);
-
-          const result = yield* (yield* GitCore).listBranches({
-            cwd: tmp,
-            query: "feature/",
-            limit: 10,
-          });
-
-          expect(result.totalCount).toBe(2);
-          expect(result.nextCursor).toBeNull();
-          expect(result.branches.map((branch) => branch.name)).toEqual([
-            "feature/demo",
-            "origin/feature/remote-only",
-          ]);
-        }),
-    );
-  });
-
-  // ── checkoutGitBranch ──
-
-  describe("checkoutGitBranch", () => {
-    it.effect("checks out an existing branch", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature" });
-
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "feature" });
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const current = result.branches.find((b) => b.current);
-        expect(current!.name).toBe("feature");
-      }),
-    );
-
-    it.effect("refreshes upstream behind count after checkout when remote branch advanced", () =>
-      Effect.gen(function* () {
-        const context = yield* Effect.context<never>();
-        const runPromise = Effect.runPromiseWith(context);
-
-        const remote = yield* makeTmpDir();
-        const source = yield* makeTmpDir();
-        const clone = yield* makeTmpDir();
-        yield* git(remote, ["init", "--bare"]);
-
-        yield* initRepoWithCommit(source);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: source })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-        yield* git(source, ["remote", "add", "origin", remote]);
-        yield* git(source, ["push", "-u", "origin", defaultBranch]);
-
-        const featureBranch = "feature-behind";
-        yield* (yield* GitCore).createBranch({ cwd: source, branch: featureBranch });
-        yield* (yield* GitCore).checkoutBranch({ cwd: source, branch: featureBranch });
-        yield* writeTextFile(path.join(source, "feature.txt"), "feature base\n");
-        yield* git(source, ["add", "feature.txt"]);
-        yield* git(source, ["commit", "-m", "feature base"]);
-        yield* git(source, ["push", "-u", "origin", featureBranch]);
-        yield* (yield* GitCore).checkoutBranch({ cwd: source, branch: defaultBranch });
-
-        yield* git(clone, ["clone", remote, "."]);
-        yield* git(clone, ["config", "user.email", "test@test.com"]);
-        yield* git(clone, ["config", "user.name", "Test"]);
-        yield* git(clone, ["checkout", "-b", featureBranch, "--track", `origin/${featureBranch}`]);
-        yield* writeTextFile(path.join(clone, "feature.txt"), "feature from remote\n");
-        yield* git(clone, ["add", "feature.txt"]);
-        yield* git(clone, ["commit", "-m", "remote feature update"]);
-        yield* git(clone, ["push", "origin", featureBranch]);
-
-        yield* (yield* GitCore).checkoutBranch({ cwd: source, branch: featureBranch });
-        const core = yield* GitCore;
-        yield* Effect.promise(() =>
-          vi.waitFor(
-            async () => {
-              const details = await runPromise(core.statusDetails(source));
-              expect(details.branch).toBe(featureBranch);
-              expect(details.aheadCount).toBe(0);
-              expect(details.behindCount).toBe(1);
-            },
-            {
-              timeout: 10_000,
-              interval: 100,
-            },
-          ),
-        );
-      }),
-    );
-
-    it.effect("statusDetails remains successful when upstream refresh fails after checkout", () =>
-      Effect.gen(function* () {
-        const remote = yield* makeTmpDir();
-        const source = yield* makeTmpDir();
-        yield* git(remote, ["init", "--bare"]);
-
-        yield* initRepoWithCommit(source);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: source })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-        yield* git(source, ["remote", "add", "origin", remote]);
-        yield* git(source, ["push", "-u", "origin", defaultBranch]);
-
-        const featureBranch = "feature-refresh-failure";
-        yield* git(source, ["branch", featureBranch]);
-        yield* git(source, ["checkout", featureBranch]);
-        yield* writeTextFile(path.join(source, "feature.txt"), "feature base\n");
-        yield* git(source, ["add", "feature.txt"]);
-        yield* git(source, ["commit", "-m", "feature base"]);
-        yield* git(source, ["push", "-u", "origin", featureBranch]);
-        yield* git(source, ["checkout", defaultBranch]);
-
-        const realGitCore = yield* GitCore;
-        let refreshFetchAttempts = 0;
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (input.args[0] === "--git-dir" && input.args[2] === "fetch") {
-            refreshFetchAttempts += 1;
-            return Effect.fail(
-              new GitCommandError({
-                operation: "git.test.refreshFailure",
-                command: `git ${input.args.join(" ")}`,
-                cwd: input.cwd,
-                detail: "simulated fetch timeout",
-              }),
-            );
-          }
-          return realGitCore.execute(input);
-        });
-        yield* core.checkoutBranch({ cwd: source, branch: featureBranch });
-        const status = yield* core.statusDetails(source);
-        expect(refreshFetchAttempts).toBe(1);
-        expect(status.branch).toBe(featureBranch);
-        expect(status.upstreamRef).toBe(`origin/${featureBranch}`);
-        expect(yield* git(source, ["branch", "--show-current"])).toBe(featureBranch);
-      }),
-    );
-
-    it.effect("defers upstream refresh until statusDetails is requested", () =>
-      Effect.gen(function* () {
-        const remote = yield* makeTmpDir();
-        const source = yield* makeTmpDir();
-        yield* git(remote, ["init", "--bare"]);
-
-        yield* initRepoWithCommit(source);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: source })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-        yield* git(source, ["remote", "add", "origin", remote]);
-        yield* git(source, ["push", "-u", "origin", defaultBranch]);
-
-        const featureBranch = "feature/scoped-fetch";
-        yield* git(source, ["checkout", "-b", featureBranch]);
-        yield* writeTextFile(path.join(source, "feature.txt"), "feature base\n");
-        yield* git(source, ["add", "feature.txt"]);
-        yield* git(source, ["commit", "-m", "feature base"]);
-        yield* git(source, ["push", "-u", "origin", featureBranch]);
-        yield* git(source, ["checkout", defaultBranch]);
-
-        const realGitCore = yield* GitCore;
-        let refreshFetchAttempts = 0;
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (input.args[0] === "--git-dir" && input.args[2] === "fetch") {
-            refreshFetchAttempts += 1;
-            return Effect.succeed({
-              code: 0,
-              stdout: "",
-              stderr: "",
-              stdoutTruncated: false,
-              stderrTruncated: false,
-            });
-          }
-          return realGitCore.execute(input);
-        });
-        yield* core.checkoutBranch({ cwd: source, branch: featureBranch });
-        yield* Effect.promise(() => new Promise<void>((resolve) => setTimeout(resolve, 50)));
-        expect(refreshFetchAttempts).toBe(0);
-        const status = yield* core.statusDetails(source);
-        expect(status.branch).toBe(featureBranch);
-        expect(refreshFetchAttempts).toBe(1);
-      }),
-    );
-
-    it.effect("coalesces upstream refreshes across sibling worktrees on the same remote", () =>
-      Effect.gen(function* () {
-        const ok = (stdout = "") =>
-          Effect.succeed({
-            code: 0,
-            stdout,
-            stderr: "",
-            stdoutTruncated: false,
-            stderrTruncated: false,
-          });
-
-        let fetchCount = 0;
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (
-            input.args[0] === "rev-parse" &&
-            input.args[1] === "--abbrev-ref" &&
-            input.args[2] === "--symbolic-full-name" &&
-            input.args[3] === "@{upstream}"
-          ) {
-            return ok(
-              input.cwd === "/repo/worktrees/pr-123" ? "origin/feature/pr-123\n" : "origin/main\n",
-            );
-          }
-          if (input.args[0] === "remote") {
-            return ok("origin\n");
-          }
-          if (input.args[0] === "rev-parse" && input.args[1] === "--git-common-dir") {
-            return ok("/repo/.git\n");
-          }
-          if (input.args[0] === "--git-dir" && input.args[2] === "fetch") {
-            fetchCount += 1;
-            expect(input.cwd).toBe("/repo");
-            expect(input.args).toEqual([
-              "--git-dir",
-              "/repo/.git",
-              "fetch",
-              "--quiet",
-              "--no-tags",
-              "origin",
-            ]);
-            return ok();
-          }
-          if (input.operation === "GitCore.statusDetails.status") {
-            return ok(
-              input.cwd === "/repo/worktrees/pr-123"
-                ? "# branch.head feature/pr-123\n# branch.upstream origin/feature/pr-123\n# branch.ab +0 -0\n"
-                : "# branch.head main\n# branch.upstream origin/main\n# branch.ab +0 -0\n",
-            );
-          }
-          if (
-            input.operation === "GitCore.statusDetails.unstagedNumstat" ||
-            input.operation === "GitCore.statusDetails.stagedNumstat"
-          ) {
-            return ok();
-          }
-          if (input.operation === "GitCore.statusDetails.defaultRef") {
-            return ok("refs/remotes/origin/main\n");
-          }
-          return Effect.fail(
-            new GitCommandError({
-              operation: input.operation,
-              command: `git ${input.args.join(" ")}`,
-              cwd: input.cwd,
-              detail: "Unexpected git command in shared refresh cache test.",
-            }),
-          );
-        });
-
-        yield* core.statusDetails("/repo/worktrees/main");
-        yield* core.statusDetails("/repo/worktrees/pr-123");
-        expect(fetchCount).toBe(1);
-      }),
-    );
-
-    it.effect(
-      "briefly backs off failed upstream refreshes across sibling worktrees on one remote",
-      () =>
-        Effect.gen(function* () {
-          const ok = (stdout = "") =>
-            Effect.succeed({
-              code: 0,
-              stdout,
-              stderr: "",
-              stdoutTruncated: false,
-              stderrTruncated: false,
-            });
-
-          let fetchCount = 0;
-          const core = yield* makeIsolatedGitCore((input) => {
-            if (
-              input.args[0] === "rev-parse" &&
-              input.args[1] === "--abbrev-ref" &&
-              input.args[2] === "--symbolic-full-name" &&
-              input.args[3] === "@{upstream}"
-            ) {
-              return ok(
-                input.cwd === "/repo/worktrees/pr-123"
-                  ? "origin/feature/pr-123\n"
-                  : "origin/main\n",
-              );
-            }
-            if (input.args[0] === "remote") {
-              return ok("origin\n");
-            }
-            if (input.args[0] === "rev-parse" && input.args[1] === "--git-common-dir") {
-              return ok("/repo/.git\n");
-            }
-            if (input.args[0] === "--git-dir" && input.args[2] === "fetch") {
-              fetchCount += 1;
-              return Effect.fail(
-                new GitCommandError({
-                  operation: input.operation,
-                  command: `git ${input.args.join(" ")}`,
-                  cwd: input.cwd,
-                  detail: "simulated fetch timeout",
-                }),
-              );
-            }
-            if (input.operation === "GitCore.statusDetails.status") {
-              return ok(
-                input.cwd === "/repo/worktrees/pr-123"
-                  ? "# branch.head feature/pr-123\n# branch.upstream origin/feature/pr-123\n# branch.ab +0 -0\n"
-                  : "# branch.head main\n# branch.upstream origin/main\n# branch.ab +0 -0\n",
-              );
-            }
-            if (
-              input.operation === "GitCore.statusDetails.unstagedNumstat" ||
-              input.operation === "GitCore.statusDetails.stagedNumstat"
-            ) {
-              return ok();
-            }
-            if (input.operation === "GitCore.statusDetails.defaultRef") {
-              return ok("refs/remotes/origin/main\n");
-            }
-            return Effect.fail(
-              new GitCommandError({
-                operation: input.operation,
-                command: `git ${input.args.join(" ")}`,
-                cwd: input.cwd,
-                detail: "Unexpected git command in refresh failure cooldown test.",
-              }),
-            );
-          });
-
-          yield* core.statusDetails("/repo/worktrees/main");
-          yield* core.statusDetails("/repo/worktrees/pr-123");
-          expect(fetchCount).toBe(1);
-        }),
-    );
-
-    it.effect("throws when branch does not exist", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const result = yield* Effect.result(
-          (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "nonexistent" }),
-        );
-        expect(result._tag).toBe("Failure");
-      }),
-    );
-
-    it.effect("does not silently checkout a local branch when a remote ref no longer exists", () =>
-      Effect.gen(function* () {
-        const remote = yield* makeTmpDir();
-        const source = yield* makeTmpDir();
-        yield* git(remote, ["init", "--bare"]);
-
-        yield* initRepoWithCommit(source);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: source })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-        yield* git(source, ["remote", "add", "origin", remote]);
-        yield* git(source, ["push", "-u", "origin", defaultBranch]);
-
-        yield* (yield* GitCore).createBranch({ cwd: source, branch: "feature" });
-
-        const checkoutResult = yield* Effect.result(
-          (yield* GitCore).checkoutBranch({ cwd: source, branch: "origin/feature" }),
-        );
-        expect(checkoutResult._tag).toBe("Failure");
-        expect(yield* git(source, ["branch", "--show-current"])).toBe(defaultBranch);
-      }),
-    );
-
-    it.effect("checks out a remote tracking branch when remote name contains slashes", () =>
-      Effect.gen(function* () {
-        const remote = yield* makeTmpDir();
-        const prefixRemote = yield* makeTmpDir();
-        const source = yield* makeTmpDir();
-        const prefixFetchNamespace = "prefix-my-org";
-        const prefixRemoteName = "my-org";
-        const remoteName = "my-org/upstream";
-        const featureBranch = "feature";
-        yield* git(remote, ["init", "--bare"]);
-        yield* git(prefixRemote, ["init", "--bare"]);
-
-        yield* initRepoWithCommit(source);
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: source })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-        yield* configureRemote(source, prefixRemoteName, prefixRemote, prefixFetchNamespace);
-        yield* configureRemote(source, remoteName, remote, remoteName);
-        yield* git(source, ["push", "-u", remoteName, defaultBranch]);
-
-        yield* git(source, ["checkout", "-b", featureBranch]);
-        yield* writeTextFile(path.join(source, "feature.txt"), "feature content\n");
-        yield* git(source, ["add", "feature.txt"]);
-        yield* git(source, ["commit", "-m", "feature commit"]);
-        yield* git(source, ["push", "-u", remoteName, featureBranch]);
-        yield* git(source, ["checkout", defaultBranch]);
-        yield* git(source, ["branch", "-D", featureBranch]);
-
-        const checkoutResult = yield* (yield* GitCore).checkoutBranch({
-          cwd: source,
-          branch: `${remoteName}/${featureBranch}`,
-        });
-
-        expect(checkoutResult.branch).toBe("upstream/feature");
-        expect(yield* git(source, ["branch", "--show-current"])).toBe("upstream/feature");
-        const realGitCore = yield* GitCore;
-        let fetchArgs: readonly string[] | null = null;
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (input.args[0] === "--git-dir" && input.args[2] === "fetch") {
-            fetchArgs = [...input.args];
-            return Effect.succeed({
-              code: 0,
-              stdout: "",
-              stderr: "",
-              stdoutTruncated: false,
-              stderrTruncated: false,
-            });
-          }
-          return realGitCore.execute(input);
-        });
-
-        const status = yield* core.statusDetails(source);
-        expect(status.branch).toBe("upstream/feature");
-        expect(status.upstreamRef).toBe(`${remoteName}/${featureBranch}`);
-        expect(fetchArgs).toEqual([
-          "--git-dir",
-          path.join(source, ".git"),
-          "fetch",
-          "--quiet",
-          "--no-tags",
-          remoteName,
-        ]);
-      }),
-    );
-
-    it.effect(
-      "falls back to detached checkout when --track would conflict with an existing local branch",
-      () =>
-        Effect.gen(function* () {
-          const remote = yield* makeTmpDir();
-          const source = yield* makeTmpDir();
-          yield* git(remote, ["init", "--bare"]);
-
-          yield* initRepoWithCommit(source);
-          const defaultBranch = (yield* (yield* GitCore).listBranches({
-            cwd: source,
-          })).branches.find((branch) => branch.current)!.name;
-          yield* git(source, ["remote", "add", "origin", remote]);
-          yield* git(source, ["push", "-u", "origin", defaultBranch]);
-
-          // Keep local branch but remove tracking so `--track origin/<branch>`
-          // would attempt to create an already-existing local branch.
-          yield* git(source, ["branch", "--unset-upstream"]);
-
-          yield* (yield* GitCore).checkoutBranch({
-            cwd: source,
-            branch: `origin/${defaultBranch}`,
-          });
-
-          const core = yield* GitCore;
-          const status = yield* core.statusDetails(source);
-          expect(status.branch).toBeNull();
-        }),
-    );
-
-    it.effect("throws when checkout would overwrite uncommitted changes", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "other" });
-
-        // Create a conflicting change: modify README on current branch
-        yield* writeTextFile(path.join(tmp, "README.md"), "modified\n");
-        yield* git(tmp, ["add", "README.md"]);
-
-        // First, checkout other branch cleanly
-        yield* git(tmp, ["stash"]);
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "other" });
-        yield* writeTextFile(path.join(tmp, "README.md"), "other content\n");
-        yield* git(tmp, ["add", "."]);
-        yield* git(tmp, ["commit", "-m", "other change"]);
-
-        // Go back to default branch
-        const defaultBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => !b.current,
-        )!.name;
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: defaultBranch });
-
-        // Make uncommitted changes to the same file
-        yield* writeTextFile(path.join(tmp, "README.md"), "conflicting local\n");
-
-        // Checkout should fail due to uncommitted changes
-        const result = yield* Effect.result(
-          (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "other" }),
-        );
-        expect(result._tag).toBe("Failure");
-      }),
-    );
-  });
-
-  // ── createGitBranch ──
-
-  describe("createGitBranch", () => {
-    it.effect("creates a new branch visible in listGitBranches", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "new-feature" });
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.branches.some((b) => b.name === "new-feature")).toBe(true);
-      }),
-    );
-
-    it.effect("throws when branch already exists", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "dupe" });
-        const result = yield* Effect.result(
-          (yield* GitCore).createBranch({ cwd: tmp, branch: "dupe" }),
-        );
-        expect(result._tag).toBe("Failure");
-      }),
-    );
-  });
-
-  // ── renameGitBranch ──
-
-  describe("renameGitBranch", () => {
-    it.effect("renames the current branch", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature/old-name" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "feature/old-name" });
-
-        const renamed = yield* (yield* GitCore).renameBranch({
-          cwd: tmp,
-          oldBranch: "feature/old-name",
-          newBranch: "feature/new-name",
-        });
-
-        expect(renamed.branch).toBe("feature/new-name");
-
-        const branches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(branches.branches.some((branch) => branch.name === "feature/old-name")).toBe(false);
-        const current = branches.branches.find((branch) => branch.current);
-        expect(current?.name).toBe("feature/new-name");
-      }),
-    );
-
-    it.effect("returns success without git invocation when old/new names match", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const current = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!;
-
-        const renamed = yield* (yield* GitCore).renameBranch({
-          cwd: tmp,
-          oldBranch: current.name,
-          newBranch: current.name,
-        });
-
-        expect(renamed.branch).toBe(current.name);
-      }),
-    );
-
-    it.effect("appends numeric suffix when target branch already exists", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "t3code/feat/session" });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "t3code/tmp-working" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "t3code/tmp-working" });
-
-        const renamed = yield* (yield* GitCore).renameBranch({
-          cwd: tmp,
-          oldBranch: "t3code/tmp-working",
-          newBranch: "t3code/feat/session",
-        });
-
-        expect(renamed.branch).toBe("t3code/feat/session-1");
-        const branches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(branches.branches.some((branch) => branch.name === "t3code/feat/session")).toBe(
-          true,
-        );
-        expect(branches.branches.some((branch) => branch.name === "t3code/feat/session-1")).toBe(
-          true,
-        );
-        const current = branches.branches.find((branch) => branch.current);
-        expect(current?.name).toBe("t3code/feat/session-1");
-      }),
-    );
-
-    it.effect("increments suffix until it finds an available branch name", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "t3code/feat/session" });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "t3code/feat/session-1" });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "t3code/tmp-working" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "t3code/tmp-working" });
-
-        const renamed = yield* (yield* GitCore).renameBranch({
-          cwd: tmp,
-          oldBranch: "t3code/tmp-working",
-          newBranch: "t3code/feat/session",
-        });
-
-        expect(renamed.branch).toBe("t3code/feat/session-2");
-      }),
-    );
-
-    it.effect("uses '--' separator for branch rename arguments", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature/old-name" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "feature/old-name" });
-
-        const realGitCore = yield* GitCore;
-        let renameArgs: ReadonlyArray<string> | null = null;
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (input.args[0] === "branch" && input.args[1] === "-m") {
-            renameArgs = [...input.args];
-          }
-          return realGitCore.execute(input);
-        });
-
-        const renamed = yield* core.renameBranch({
-          cwd: tmp,
-          oldBranch: "feature/old-name",
-          newBranch: "feature/new-name",
-        });
-
-        expect(renamed.branch).toBe("feature/new-name");
-        expect(renameArgs).toEqual(["branch", "-m", "--", "feature/old-name", "feature/new-name"]);
-      }),
-    );
-  });
-
-  // ── createGitWorktree + removeGitWorktree ──
-
-  describe("createGitWorktree", () => {
-    it.effect("creates a worktree with a new branch from the base branch", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-
-        const wtPath = path.join(tmp, "worktree-out");
-        const currentBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!.name;
-
-        const result = yield* (yield* GitCore).createWorktree({
-          cwd: tmp,
-          branch: currentBranch,
-          newBranch: "wt-branch",
-          path: wtPath,
-        });
-
-        expect(result.worktree.path).toBe(wtPath);
-        expect(result.worktree.branch).toBe("wt-branch");
-        expect(existsSync(wtPath)).toBe(true);
-        expect(existsSync(path.join(wtPath, "README.md"))).toBe(true);
-
-        // Clean up worktree before tmp dir disposal
-        yield* (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath });
-      }),
-    );
-
-    it.effect("worktree has the new branch checked out", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-
-        const wtPath = path.join(tmp, "wt-check-dir");
-        const currentBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!.name;
-
-        yield* (yield* GitCore).createWorktree({
-          cwd: tmp,
-          branch: currentBranch,
-          newBranch: "wt-check",
-          path: wtPath,
-        });
-
-        // Verify the worktree is on the new branch
-        const branchOutput = yield* git(wtPath, ["branch", "--show-current"]);
-        expect(branchOutput).toBe("wt-check");
-
-        yield* (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath });
-      }),
-    );
-
-    it.effect("creates a worktree for an existing branch when newBranch is omitted", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature/existing-worktree" });
-
-        const wtPath = path.join(tmp, "wt-existing");
-        const result = yield* (yield* GitCore).createWorktree({
-          cwd: tmp,
-          branch: "feature/existing-worktree",
-          path: wtPath,
-        });
-
-        expect(result.worktree.path).toBe(wtPath);
-        expect(result.worktree.branch).toBe("feature/existing-worktree");
-        const branchOutput = yield* git(wtPath, ["branch", "--show-current"]);
-        expect(branchOutput).toBe("feature/existing-worktree");
-
-        yield* (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath });
-      }),
-    );
-
-    it.effect("throws when new branch name already exists", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "existing" });
-
-        const wtPath = path.join(tmp, "wt-conflict");
-        const currentBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!.name;
-
-        const result = yield* Effect.result(
-          (yield* GitCore).createWorktree({
-            cwd: tmp,
-            branch: currentBranch,
-            newBranch: "existing",
-            path: wtPath,
-          }),
-        );
-        expect(result._tag).toBe("Failure");
-      }),
-    );
-
-    it.effect("listGitBranches from worktree cwd reports worktree branch as current", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-
-        const wtPath = path.join(tmp, "wt-list-dir");
-        const mainBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!.name;
-
-        yield* (yield* GitCore).createWorktree({
-          cwd: tmp,
-          branch: mainBranch,
-          newBranch: "wt-list",
-          path: wtPath,
-        });
-
-        // listGitBranches from the worktree should show wt-list as current
-        const wtBranches = yield* (yield* GitCore).listBranches({ cwd: wtPath });
-        expect(wtBranches.isRepo).toBe(true);
-        const wtCurrent = wtBranches.branches.find((b) => b.current);
-        expect(wtCurrent!.name).toBe("wt-list");
-
-        // Main repo should still show the original branch as current
-        const mainBranches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const mainCurrent = mainBranches.branches.find((b) => b.current);
-        expect(mainCurrent!.name).toBe(mainBranch);
-
-        yield* (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath });
-      }),
-    );
-
-    it.effect("removeGitWorktree cleans up the worktree", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-
-        const wtPath = path.join(tmp, "wt-remove-dir");
-        const currentBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!.name;
-
-        yield* (yield* GitCore).createWorktree({
-          cwd: tmp,
-          branch: currentBranch,
-          newBranch: "wt-remove",
-          path: wtPath,
-        });
-        expect(existsSync(wtPath)).toBe(true);
-
-        yield* (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath });
-        expect(existsSync(wtPath)).toBe(false);
-      }),
-    );
-
-    it.effect("removeGitWorktree force removes a dirty worktree", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-
-        const wtPath = path.join(tmp, "wt-dirty-dir");
-        const currentBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!.name;
-
-        yield* (yield* GitCore).createWorktree({
-          cwd: tmp,
-          branch: currentBranch,
-          newBranch: "wt-dirty",
-          path: wtPath,
-        });
-        expect(existsSync(wtPath)).toBe(true);
-
-        yield* writeTextFile(path.join(wtPath, "README.md"), "dirty change\n");
-
-        const failedRemove = yield* Effect.result(
-          (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath }),
-        );
-        expect(failedRemove._tag).toBe("Failure");
-        expect(existsSync(wtPath)).toBe(true);
-
-        yield* (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath, force: true });
-        expect(existsSync(wtPath)).toBe(false);
-      }),
-    );
-  });
-
-  // ── Full flow: local branch checkout ──
-
-  describe("full flow: local branch checkout", () => {
-    it.effect("init → commit → create branch → checkout → verify current", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature-login" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "feature-login" });
-
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const current = result.branches.find((b) => b.current);
-        expect(current!.name).toBe("feature-login");
-      }),
-    );
-  });
-
-  // ── Full flow: worktree creation from base branch ──
-
-  describe("full flow: worktree creation", () => {
-    it.effect("creates worktree with new branch from current branch", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-
-        const currentBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (b) => b.current,
-        )!.name;
-
-        const wtPath = path.join(tmp, "my-worktree");
-        const result = yield* (yield* GitCore).createWorktree({
-          cwd: tmp,
-          branch: currentBranch,
-          newBranch: "feature-wt",
-          path: wtPath,
-        });
-
-        // Worktree exists
-        expect(existsSync(result.worktree.path)).toBe(true);
-
-        // Main repo still on original branch
-        const mainBranches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const mainCurrent = mainBranches.branches.find((b) => b.current);
-        expect(mainCurrent!.name).toBe(currentBranch);
-
-        // Worktree is on the new branch
-        const wtBranch = yield* git(wtPath, ["branch", "--show-current"]);
-        expect(wtBranch).toBe("feature-wt");
-
-        yield* (yield* GitCore).removeWorktree({ cwd: tmp, path: wtPath });
-      }),
-    );
-  });
-
-  describe("fetchPullRequestBranch", () => {
-    it.effect("fetches a GitHub pull request ref into a local branch without checkout", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const { initialBranch } = yield* initRepoWithCommit(tmp);
-        const remoteDir = yield* makeTmpDir("git-remote-");
-        yield* git(remoteDir, ["init", "--bare"]);
-        yield* git(tmp, ["remote", "add", "origin", remoteDir]);
-        yield* git(tmp, ["push", "-u", "origin", initialBranch]);
-        yield* git(tmp, ["checkout", "-b", "feature/pr-fetch"]);
-        yield* writeTextFile(path.join(tmp, "pr-fetch.txt"), "fetch me\n");
-        yield* git(tmp, ["add", "pr-fetch.txt"]);
-        yield* git(tmp, ["commit", "-m", "Add PR fetch branch"]);
-        yield* git(tmp, ["push", "-u", "origin", "feature/pr-fetch"]);
-        yield* git(tmp, ["push", "origin", "HEAD:refs/pull/55/head"]);
-        yield* git(tmp, ["checkout", initialBranch]);
-
-        yield* (yield* GitCore).fetchPullRequestBranch({
-          cwd: tmp,
-          prNumber: 55,
-          branch: "feature/pr-fetch",
-        });
-
-        const localBranches = yield* git(tmp, ["branch", "--list", "feature/pr-fetch"]);
-        expect(localBranches).toContain("feature/pr-fetch");
-        const currentBranch = yield* git(tmp, ["branch", "--show-current"]);
-        expect(currentBranch).toBe(initialBranch);
-      }),
-    );
-  });
-
-  // ── Full flow: thread switching simulation ──
-
-  describe("full flow: thread switching (checkout toggling)", () => {
-    it.effect("checkout a → checkout b → checkout a → current matches", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "branch-a" });
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "branch-b" });
-
-        // Simulate switching to thread A's branch
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "branch-a" });
-        let branches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(branches.branches.find((b) => b.current)!.name).toBe("branch-a");
-
-        // Simulate switching to thread B's branch
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "branch-b" });
-        branches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(branches.branches.find((b) => b.current)!.name).toBe("branch-b");
-
-        // Switch back to thread A
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "branch-a" });
-        branches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(branches.branches.find((b) => b.current)!.name).toBe("branch-a");
-      }),
-    );
-  });
-
-  // ── Full flow: checkout conflict ──
-
-  describe("full flow: checkout conflict", () => {
-    it.effect("uncommitted changes prevent checkout to a diverged branch", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "diverged" });
-
-        // Make diverged branch have different file content
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "diverged" });
-        yield* writeTextFile(path.join(tmp, "README.md"), "diverged content\n");
-        yield* git(tmp, ["add", "."]);
-        yield* git(tmp, ["commit", "-m", "diverge"]);
-
-        // Actually, let's just get back to the initial branch explicitly
-        const allBranches = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        const initialBranch = allBranches.branches.find((b) => b.name !== "diverged")!.name;
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: initialBranch });
-
-        // Make local uncommitted changes to the same file
-        yield* writeTextFile(path.join(tmp, "README.md"), "local uncommitted\n");
-
-        // Attempt checkout should fail
-        const failedCheckout = yield* Effect.result(
-          (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "diverged" }),
-        );
-        expect(failedCheckout._tag).toBe("Failure");
-
-        // Current branch should still be the initial one
-        const result = yield* (yield* GitCore).listBranches({ cwd: tmp });
-        expect(result.branches.find((b) => b.current)!.name).toBe(initialBranch);
-      }),
-    );
-  });
-
-  describe("GitCore", () => {
-    it.effect("supports branch lifecycle operations through the service API", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const core = yield* GitCore;
-
-        yield* core.initRepo({ cwd: tmp });
-        yield* git(tmp, ["config", "user.email", "test@test.com"]);
-        yield* git(tmp, ["config", "user.name", "Test"]);
-        yield* writeTextFile(path.join(tmp, "README.md"), "# test\n");
-        yield* git(tmp, ["add", "."]);
-        yield* git(tmp, ["commit", "-m", "initial commit"]);
-
-        yield* core.createBranch({ cwd: tmp, branch: "feature/service-api" });
-        yield* core.checkoutBranch({ cwd: tmp, branch: "feature/service-api" });
-        const branches = yield* core.listBranches({ cwd: tmp });
-
-        expect(branches.isRepo).toBe(true);
-        expect(
-          branches.branches.find((branch: { current: boolean; name: string }) => branch.current)
-            ?.name,
-        ).toBe("feature/service-api");
-      }),
-    );
-
-    it.effect(
-      "reuses an existing remote when the target URL only differs by a trailing slash after .git",
-      () =>
-        Effect.gen(function* () {
-          const tmp = yield* makeTmpDir();
-          yield* initRepoWithCommit(tmp);
-          const core = yield* GitCore;
-
-          yield* git(tmp, ["remote", "add", "origin", "git@github.com:pingdotgg/t3code.git"]);
-
-          const remoteName = yield* core.ensureRemote({
-            cwd: tmp,
-            preferredName: "origin",
-            url: "git@github.com:pingdotgg/t3code.git/",
-          });
-
-          expect(remoteName).toBe("origin");
-          expect((yield* git(tmp, ["remote"])).split("\n").filter(Boolean)).toEqual(["origin"]);
-        }),
-    );
-
-    it.effect("reports status details and dirty state", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        const clean = yield* core.status({ cwd: tmp });
-        expect(clean.hasWorkingTreeChanges).toBe(false);
-        expect(clean.branch).toBeTruthy();
-
-        yield* writeTextFile(path.join(tmp, "README.md"), "updated\n");
-        const dirty = yield* core.statusDetails(tmp);
-        expect(dirty.hasWorkingTreeChanges).toBe(true);
-      }),
-    );
-
-    it.effect("returns a non-repo status for deleted directories", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const deletedDir = path.join(tmp, "deleted-repo");
-        yield* makeDirectory(deletedDir);
-        yield* removePath(deletedDir);
-        const core = yield* GitCore;
-
-        const status = yield* core.statusDetails(deletedDir);
-        const localStatus = yield* core.statusDetailsLocal(deletedDir);
-
-        expect(status).toEqual({
-          isRepo: false,
-          hasOriginRemote: false,
-          isDefaultBranch: false,
-          branch: null,
-          upstreamRef: null,
-          hasWorkingTreeChanges: false,
-          workingTree: {
-            files: [],
-            insertions: 0,
-            deletions: 0,
-          },
-          hasUpstream: false,
-          aheadCount: 0,
-          behindCount: 0,
-        });
-        expect(localStatus).toEqual(status);
-      }),
-    );
-
-    it.effect("computes ahead count against base branch when no upstream is configured", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        yield* core.createBranch({ cwd: tmp, branch: "feature/no-upstream-ahead" });
-        yield* core.checkoutBranch({ cwd: tmp, branch: "feature/no-upstream-ahead" });
-        yield* writeTextFile(path.join(tmp, "feature.txt"), "ahead of base\n");
-        yield* git(tmp, ["add", "feature.txt"]);
-        yield* git(tmp, ["commit", "-m", "feature commit"]);
-
-        const details = yield* core.statusDetails(tmp);
-        expect(details.branch).toBe("feature/no-upstream-ahead");
-        expect(details.hasUpstream).toBe(false);
-        expect(details.aheadCount).toBe(1);
-        expect(details.behindCount).toBe(0);
-      }),
-    );
-
-    it.effect(
-      "computes ahead count against origin/default when local default branch is missing",
-      () =>
-        Effect.gen(function* () {
-          const remote = yield* makeTmpDir();
-          const source = yield* makeTmpDir();
-          yield* git(remote, ["init", "--bare"]);
-
-          yield* initRepoWithCommit(source);
-          const initialBranch = (yield* (yield* GitCore).listBranches({
-            cwd: source,
-          })).branches.find((branch) => branch.current)!.name;
-          yield* git(source, ["remote", "add", "origin", remote]);
-          yield* git(source, ["push", "-u", "origin", initialBranch]);
-          yield* git(source, ["checkout", "-b", "feature/remote-base-only"]);
-          yield* writeTextFile(
-            path.join(source, "feature.txt"),
-            `ahead of origin/${initialBranch}\n`,
-          );
-          yield* git(source, ["add", "feature.txt"]);
-          yield* git(source, ["commit", "-m", "feature commit"]);
-          yield* git(source, ["branch", "-D", initialBranch]);
-
-          const core = yield* GitCore;
-          const details = yield* core.statusDetails(source);
-          expect(details.branch).toBe("feature/remote-base-only");
-          expect(details.hasUpstream).toBe(false);
-          expect(details.aheadCount).toBe(1);
-          expect(details.behindCount).toBe(0);
-        }),
-    );
-
-    it.effect(
-      "computes ahead count against a non-origin remote-prefixed gh-merge-base candidate",
-      () =>
-        Effect.gen(function* () {
-          const remote = yield* makeTmpDir();
-          const source = yield* makeTmpDir();
-          const remoteName = "fork-seed";
-          yield* git(remote, ["init", "--bare"]);
-
-          yield* initRepoWithCommit(source);
-          const initialBranch = (yield* (yield* GitCore).listBranches({
-            cwd: source,
-          })).branches.find((branch) => branch.current)!.name;
-          yield* git(source, ["remote", "add", remoteName, remote]);
-          yield* git(source, ["push", "-u", remoteName, initialBranch]);
-          yield* git(source, ["checkout", "-b", "feature/non-origin-merge-base"]);
-          yield* git(source, [
-            "config",
-            "branch.feature/non-origin-merge-base.gh-merge-base",
-            `${remoteName}/${initialBranch}`,
-          ]);
-          yield* writeTextFile(
-            path.join(source, "feature.txt"),
-            `ahead of ${remoteName}/${initialBranch}\n`,
-          );
-          yield* git(source, ["add", "feature.txt"]);
-          yield* git(source, ["commit", "-m", "feature commit"]);
-          yield* git(source, ["branch", "-D", initialBranch]);
-
-          const core = yield* GitCore;
-          const details = yield* core.statusDetails(source);
-          expect(details.branch).toBe("feature/non-origin-merge-base");
-          expect(details.hasUpstream).toBe(false);
-          expect(details.aheadCount).toBe(1);
-          expect(details.behindCount).toBe(0);
-        }),
-    );
-
-    it.effect("skips push when no upstream is configured and branch is not ahead of base", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        yield* core.createBranch({ cwd: tmp, branch: "feature/no-upstream-no-ahead" });
-        yield* core.checkoutBranch({ cwd: tmp, branch: "feature/no-upstream-no-ahead" });
-
-        const pushed = yield* core.pushCurrentBranch(tmp, null);
-        expect(pushed.status).toBe("skipped_up_to_date");
-        expect(pushed.branch).toBe("feature/no-upstream-no-ahead");
-        expect(pushed.setUpstream).toBeUndefined();
-      }),
-    );
-
-    it.effect("pushes with upstream setup when no comparable base branch exists", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const remote = yield* makeTmpDir();
-        yield* git(tmp, ["init", "--initial-branch=trunk"]);
-        yield* git(tmp, ["config", "user.email", "test@test.com"]);
-        yield* git(tmp, ["config", "user.name", "Test"]);
-        yield* writeTextFile(path.join(tmp, "README.md"), "hello\n");
-        yield* git(tmp, ["add", "README.md"]);
-        yield* git(tmp, ["commit", "-m", "initial"]);
-        yield* git(remote, ["init", "--bare"]);
-        yield* git(tmp, ["remote", "add", "origin", remote]);
-        yield* git(tmp, ["checkout", "-b", "feature/no-base"]);
-
-        const core = yield* GitCore;
-        const pushed = yield* core.pushCurrentBranch(tmp, null);
-        expect(pushed.status).toBe("pushed");
-        expect(pushed.setUpstream).toBe(true);
-        expect(pushed.upstreamBranch).toBe("origin/feature/no-base");
-        expect(yield* git(tmp, ["rev-parse", "--abbrev-ref", "@{upstream}"])).toBe(
-          "origin/feature/no-base",
-        );
-      }),
-    );
-
-    it.effect("pushes with upstream setup to the only configured non-origin remote", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const remote = yield* makeTmpDir();
-        yield* git(tmp, ["init", "--initial-branch=main"]);
-        yield* git(tmp, ["config", "user.email", "test@test.com"]);
-        yield* git(tmp, ["config", "user.name", "Test"]);
-        yield* writeTextFile(path.join(tmp, "README.md"), "hello\n");
-        yield* git(tmp, ["add", "README.md"]);
-        yield* git(tmp, ["commit", "-m", "initial"]);
-        yield* git(remote, ["init", "--bare"]);
-        yield* git(tmp, ["remote", "add", "fork", remote]);
-        yield* git(tmp, ["checkout", "-b", "feature/fork-only"]);
-
-        const core = yield* GitCore;
-        const pushed = yield* core.pushCurrentBranch(tmp, null);
-        expect(pushed.status).toBe("pushed");
-        expect(pushed.setUpstream).toBe(true);
-        expect(pushed.upstreamBranch).toBe("fork/feature/fork-only");
-        expect(yield* git(tmp, ["rev-parse", "--abbrev-ref", "@{upstream}"])).toBe(
-          "fork/feature/fork-only",
-        );
-      }),
-    );
-
-    it.effect(
-      "pushes with upstream setup when comparable base exists but remote branch is missing",
-      () =>
-        Effect.gen(function* () {
-          const tmp = yield* makeTmpDir();
-          const remote = yield* makeTmpDir();
-          yield* git(remote, ["init", "--bare"]);
-
-          yield* initRepoWithCommit(tmp);
-          const initialBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-            (branch) => branch.current,
-          )!.name;
-          yield* git(tmp, ["remote", "add", "origin", remote]);
-          yield* git(tmp, ["push", "-u", "origin", initialBranch]);
-
-          yield* writeTextFile(path.join(tmp, "default-ahead.txt"), "ahead on default\n");
-          yield* git(tmp, ["add", "default-ahead.txt"]);
-          yield* git(tmp, ["commit", "-m", "default ahead"]);
-
-          const featureBranch = "feature/publish-no-upstream";
-          yield* git(tmp, ["checkout", "-b", featureBranch]);
-
-          const core = yield* GitCore;
-          const pushed = yield* core.pushCurrentBranch(tmp, null);
-          expect(pushed.status).toBe("pushed");
-          expect(pushed.setUpstream).toBe(true);
-          expect(pushed.upstreamBranch).toBe(`origin/${featureBranch}`);
-          expect(yield* git(tmp, ["rev-parse", "--abbrev-ref", "@{upstream}"])).toBe(
-            `origin/${featureBranch}`,
-          );
-          expect(yield* git(tmp, ["ls-remote", "--heads", "origin", featureBranch])).toContain(
-            featureBranch,
-          );
-        }),
-    );
-
-    it.effect("prefers branch pushRemote over origin when setting upstream", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const origin = yield* makeTmpDir();
-        const fork = yield* makeTmpDir();
-        yield* git(origin, ["init", "--bare"]);
-        yield* git(fork, ["init", "--bare"]);
-
-        yield* initRepoWithCommit(tmp);
-        const initialBranch = (yield* (yield* GitCore).listBranches({ cwd: tmp })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-        yield* git(tmp, ["remote", "add", "origin", origin]);
-        yield* git(tmp, ["remote", "add", "fork", fork]);
-        yield* git(tmp, ["push", "-u", "origin", initialBranch]);
-
-        const featureBranch = "feature/push-remote";
-        yield* git(tmp, ["checkout", "-b", featureBranch]);
-        yield* git(tmp, ["config", `branch.${featureBranch}.pushRemote`, "fork"]);
-        yield* writeTextFile(path.join(tmp, "feature.txt"), "push to fork\n");
-        yield* git(tmp, ["add", "feature.txt"]);
-        yield* git(tmp, ["commit", "-m", "feature commit"]);
-
-        const core = yield* GitCore;
-        const pushed = yield* core.pushCurrentBranch(tmp, null);
-        expect(pushed.status).toBe("pushed");
-        expect(pushed.setUpstream).toBe(true);
-        expect(pushed.upstreamBranch).toBe(`fork/${featureBranch}`);
-        expect(yield* git(tmp, ["rev-parse", "--abbrev-ref", "@{upstream}"])).toBe(
-          `fork/${featureBranch}`,
-        );
-        expect(yield* git(tmp, ["ls-remote", "--heads", "fork", featureBranch])).toContain(
-          featureBranch,
-        );
-      }),
-    );
-
-    it.effect(
-      "pushes renamed PR worktree branches to their tracked upstream branch even when push.default is current",
-      () =>
-        Effect.gen(function* () {
-          const tmp = yield* makeTmpDir();
-          const fork = yield* makeTmpDir();
-          yield* git(fork, ["init", "--bare"]);
-
-          const { initialBranch } = yield* initRepoWithCommit(tmp);
-          yield* git(tmp, ["remote", "add", "jasonLaster", fork]);
-          yield* git(tmp, ["checkout", "-b", "statemachine"]);
-          yield* writeTextFile(path.join(tmp, "fork.txt"), "fork branch\n");
-          yield* git(tmp, ["add", "fork.txt"]);
-          yield* git(tmp, ["commit", "-m", "fork branch"]);
-          yield* git(tmp, ["push", "-u", "jasonLaster", "statemachine"]);
-          yield* git(tmp, ["checkout", initialBranch]);
-          yield* git(tmp, ["branch", "-D", "statemachine"]);
-          yield* git(tmp, [
-            "checkout",
-            "-b",
-            "t3code/pr-488/statemachine",
-            "--track",
-            "jasonLaster/statemachine",
-          ]);
-          yield* git(tmp, ["config", "push.default", "current"]);
-          yield* writeTextFile(path.join(tmp, "fork.txt"), "updated fork branch\n");
-          yield* git(tmp, ["add", "fork.txt"]);
-          yield* git(tmp, ["commit", "-m", "update reviewed PR branch"]);
-
-          const core = yield* GitCore;
-          const pushed = yield* core.pushCurrentBranch(tmp, null);
-
-          expect(pushed.status).toBe("pushed");
-          expect(pushed.setUpstream).toBe(false);
-          expect(pushed.upstreamBranch).toBe("jasonLaster/statemachine");
-          expect(yield* git(tmp, ["rev-parse", "--abbrev-ref", "@{upstream}"])).toBe(
-            "jasonLaster/statemachine",
-          );
-          expect(
-            yield* git(tmp, ["ls-remote", "--heads", "jasonLaster", "statemachine"]),
-          ).toContain("statemachine");
-          expect(
-            yield* git(tmp, ["ls-remote", "--heads", "jasonLaster", "t3code/pr-488/statemachine"]),
-          ).toBe("");
-        }),
-    );
-
-    it.effect("pushes to the tracked upstream when the remote name contains slashes", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const remote = yield* makeTmpDir();
-        const prefixRemote = yield* makeTmpDir();
-        const prefixFetchNamespace = "prefix-my-org";
-        const prefixRemoteName = "my-org";
-        const remoteName = "my-org/upstream";
-        const featureBranch = "feature/slash-remote-push";
-        yield* git(remote, ["init", "--bare"]);
-        yield* git(prefixRemote, ["init", "--bare"]);
-
-        const { initialBranch } = yield* initRepoWithCommit(tmp);
-        yield* configureRemote(tmp, prefixRemoteName, prefixRemote, prefixFetchNamespace);
-        yield* configureRemote(tmp, remoteName, remote, remoteName);
-        yield* git(tmp, ["push", "-u", remoteName, initialBranch]);
-
-        yield* git(tmp, ["checkout", "-b", featureBranch]);
-        yield* writeTextFile(path.join(tmp, "feature.txt"), "first revision\n");
-        yield* git(tmp, ["add", "feature.txt"]);
-        yield* git(tmp, ["commit", "-m", "feature base"]);
-        yield* git(tmp, ["push", "-u", remoteName, featureBranch]);
-
-        yield* writeTextFile(path.join(tmp, "feature.txt"), "second revision\n");
-        yield* git(tmp, ["add", "feature.txt"]);
-        yield* git(tmp, ["commit", "-m", "feature update"]);
-
-        const core = yield* GitCore;
-        const pushed = yield* core.pushCurrentBranch(tmp, null);
-        expect(pushed.status).toBe("pushed");
-        expect(pushed.setUpstream).toBe(false);
-        expect(pushed.upstreamBranch).toBe(`${remoteName}/${featureBranch}`);
-        expect(yield* git(tmp, ["rev-parse", "--abbrev-ref", "@{upstream}"])).toBe(
-          `${remoteName}/${featureBranch}`,
-        );
-        expect(yield* git(tmp, ["ls-remote", "--heads", remoteName, featureBranch])).toContain(
-          featureBranch,
-        );
-      }),
-    );
-
-    it.effect("includes command context when worktree removal fails", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-        const missingWorktreePath = path.join(tmp, "missing-worktree");
-
-        const removeResult = yield* Effect.result(
-          core.removeWorktree({ cwd: tmp, path: missingWorktreePath }),
-        );
-        expect(removeResult._tag).toBe("Failure");
-        if (removeResult._tag !== "Failure") {
-          return;
-        }
-        const message = removeResult.failure.message;
-        expect(message).toContain("git worktree remove");
-        expect(message).toContain(`cwd: ${tmp}`);
-        expect(message).toContain(missingWorktreePath);
-      }),
-    );
-
-    it.effect(
-      "refreshes upstream before statusDetails so behind count reflects remote updates",
-      () =>
-        Effect.gen(function* () {
-          const remote = yield* makeTmpDir();
-          const source = yield* makeTmpDir();
-          const clone = yield* makeTmpDir();
-          yield* git(remote, ["init", "--bare"]);
-
-          yield* initRepoWithCommit(source);
-          const initialBranch = (yield* (yield* GitCore).listBranches({
-            cwd: source,
-          })).branches.find((branch) => branch.current)!.name;
-          yield* git(source, ["remote", "add", "origin", remote]);
-          yield* git(source, ["push", "-u", "origin", initialBranch]);
-
-          yield* git(clone, ["clone", remote, "."]);
-          yield* git(clone, ["config", "user.email", "test@test.com"]);
-          yield* git(clone, ["config", "user.name", "Test"]);
-          yield* git(clone, [
-            "checkout",
-            "-B",
-            initialBranch,
-            "--track",
-            `origin/${initialBranch}`,
-          ]);
-          yield* writeTextFile(path.join(clone, "CHANGELOG.md"), "remote change\n");
-          yield* git(clone, ["add", "CHANGELOG.md"]);
-          yield* git(clone, ["commit", "-m", "remote update"]);
-          yield* git(clone, ["push", "origin", initialBranch]);
-
-          const core = yield* GitCore;
-          const details = yield* core.statusDetails(source);
-          expect(details.branch).toBe(initialBranch);
-          expect(details.aheadCount).toBe(0);
-          expect(details.behindCount).toBe(1);
-        }),
-    );
-
-    it.effect("prepares commit context by auto-staging and creates commit", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        yield* writeTextFile(path.join(tmp, "README.md"), "new content\n");
-        const context = yield* core.prepareCommitContext(tmp);
-        expect(context).not.toBeNull();
-        expect(context!.stagedSummary.length).toBeGreaterThan(0);
-        expect(context!.stagedPatch.length).toBeGreaterThan(0);
-
-        const created = yield* core.commit(tmp, "Add README update", "- include updated content");
-        expect(created.commitSha.length).toBeGreaterThan(0);
-        expect(yield* git(tmp, ["log", "-1", "--pretty=%s"])).toBe("Add README update");
-      }),
-    );
-
-    it.effect("prepareCommitContext stages only selected files when filePaths provided", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        yield* writeTextFile(path.join(tmp, "a.txt"), "file a\n");
-        yield* writeTextFile(path.join(tmp, "b.txt"), "file b\n");
-
-        const context = yield* core.prepareCommitContext(tmp, ["a.txt"]);
-        expect(context).not.toBeNull();
-        expect(context!.stagedSummary).toContain("a.txt");
-        expect(context!.stagedSummary).not.toContain("b.txt");
-
-        yield* core.commit(tmp, "Add only a.txt", "");
-
-        // b.txt should still be untracked after commit
-        const statusAfter = yield* git(tmp, ["status", "--porcelain"]);
-        expect(statusAfter).toContain("b.txt");
-        expect(statusAfter).not.toContain("a.txt");
-      }),
-    );
-
-    it.effect("prepareCommitContext stages everything when filePaths is undefined", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        yield* writeTextFile(path.join(tmp, "a.txt"), "file a\n");
-        yield* writeTextFile(path.join(tmp, "b.txt"), "file b\n");
-
-        const context = yield* core.prepareCommitContext(tmp);
-        expect(context).not.toBeNull();
-        expect(context!.stagedSummary).toContain("a.txt");
-        expect(context!.stagedSummary).toContain("b.txt");
-      }),
-    );
-
-    it.effect("prepareCommitContext truncates oversized staged patches instead of failing", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        yield* writeTextFile(path.join(tmp, "README.md"), buildLargeText());
-
-        const context = yield* core.prepareCommitContext(tmp);
-        expect(context).not.toBeNull();
-        expect(context!.stagedSummary).toContain("README.md");
-        expect(context!.stagedPatch).toContain("[truncated]");
-      }),
-    );
-
-    it.effect("readRangeContext truncates oversized diff patches instead of failing", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const { initialBranch } = yield* initRepoWithCommit(tmp);
-        const core = yield* GitCore;
-
-        yield* core.createBranch({ cwd: tmp, branch: "feature/large-range-context" });
-        yield* core.checkoutBranch({ cwd: tmp, branch: "feature/large-range-context" });
-        yield* writeTextFile(path.join(tmp, "large.txt"), buildLargeText());
-        yield* git(tmp, ["add", "large.txt"]);
-        yield* git(tmp, ["commit", "-m", "Add large range context"]);
-
-        const rangeContext = yield* core.readRangeContext(tmp, initialBranch);
-        expect(rangeContext.commitSummary).toContain("Add large range context");
-        expect(rangeContext.diffSummary).toContain("large.txt");
-        expect(rangeContext.diffPatch).toContain("[truncated]");
-      }),
-    );
-
-    it.effect("pushes with upstream setup and then skips when up to date", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const remote = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* git(remote, ["init", "--bare"]);
-        yield* git(tmp, ["remote", "add", "origin", remote]);
-        yield* (yield* GitCore).createBranch({ cwd: tmp, branch: "feature/core-push" });
-        yield* (yield* GitCore).checkoutBranch({ cwd: tmp, branch: "feature/core-push" });
-
-        yield* writeTextFile(path.join(tmp, "feature.txt"), "push me\n");
-        const core = yield* GitCore;
-        const context = yield* core.prepareCommitContext(tmp);
-        expect(context).not.toBeNull();
-        yield* core.commit(tmp, "Add feature file", "");
-
-        const pushed = yield* core.pushCurrentBranch(tmp, null);
-        expect(pushed.status).toBe("pushed");
-        expect(pushed.setUpstream).toBe(true);
-        expect(yield* git(tmp, ["rev-parse", "--abbrev-ref", "@{upstream}"])).toBe(
-          "origin/feature/core-push",
-        );
-
-        const skipped = yield* core.pushCurrentBranch(tmp, null);
-        expect(skipped.status).toBe("skipped_up_to_date");
-      }),
-    );
-
-    it.effect("pulls behind branch and then reports up-to-date", () =>
-      Effect.gen(function* () {
-        const remote = yield* makeTmpDir();
-        const source = yield* makeTmpDir();
-        const clone = yield* makeTmpDir();
-        yield* git(remote, ["init", "--bare"]);
-
-        yield* initRepoWithCommit(source);
-        const initialBranch = (yield* (yield* GitCore).listBranches({ cwd: source })).branches.find(
-          (branch) => branch.current,
-        )!.name;
-        yield* git(source, ["remote", "add", "origin", remote]);
-        yield* git(source, ["push", "-u", "origin", initialBranch]);
-
-        yield* git(clone, ["clone", remote, "."]);
-        yield* git(clone, ["config", "user.email", "test@test.com"]);
-        yield* git(clone, ["config", "user.name", "Test"]);
-        yield* writeTextFile(path.join(clone, "CHANGELOG.md"), "remote change\n");
-        yield* git(clone, ["add", "CHANGELOG.md"]);
-        yield* git(clone, ["commit", "-m", "remote update"]);
-        yield* git(clone, ["push", "origin", initialBranch]);
-
-        const core = yield* GitCore;
-        const pulled = yield* core.pullCurrentBranch(source);
-        expect(pulled.status).toBe("pulled");
-        expect((yield* core.statusDetails(source)).behindCount).toBe(0);
-
-        const skipped = yield* core.pullCurrentBranch(source);
-        expect(skipped.status).toBe("skipped_up_to_date");
-      }),
-    );
-
-    it.effect("top-level pullGitBranch rejects when no upstream exists", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const result = yield* Effect.result((yield* GitCore).pullCurrentBranch(tmp));
-        expect(result._tag).toBe("Failure");
-        if (result._tag === "Failure") {
-          expect(result.failure.message.toLowerCase()).toContain("no upstream");
-        }
-      }),
-    );
-
-    it.effect("lists branches when recency lookup fails", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        const realGitCore = yield* GitCore;
-        let didFailRecency = false;
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (!didFailRecency && input.args[0] === "for-each-ref") {
-            didFailRecency = true;
-            return Effect.fail(
-              new GitCommandError({
-                operation: "git.test.listBranchesRecency",
-                command: `git ${input.args.join(" ")}`,
-                cwd: input.cwd,
-                detail: "timeout",
-              }),
-            );
-          }
-          return realGitCore.execute(input);
-        });
-
-        const result = yield* core.listBranches({ cwd: tmp });
-
-        expect(result.isRepo).toBe(true);
-        expect(result.branches.length).toBeGreaterThan(0);
-        expect(result.branches[0]?.current).toBe(true);
-        expect(didFailRecency).toBe(true);
-      }),
-    );
-
-    it.effect("falls back to empty remote branch data when remote lookups fail", () =>
-      Effect.gen(function* () {
-        const tmp = yield* makeTmpDir();
-        const remote = yield* makeTmpDir();
-        yield* initRepoWithCommit(tmp);
-        yield* git(remote, ["init", "--bare"]);
-        yield* git(tmp, ["remote", "add", "origin", remote]);
-
-        const realGitCore = yield* GitCore;
-        let didFailRemoteBranches = false;
-        let didFailRemoteNames = false;
-        const core = yield* makeIsolatedGitCore((input) => {
-          if (input.args.join(" ") === "branch --no-color --no-column --remotes") {
-            didFailRemoteBranches = true;
-            return Effect.fail(
-              new GitCommandError({
-                operation: "git.test.listBranchesRemoteBranches",
-                command: `git ${input.args.join(" ")}`,
-                cwd: input.cwd,
-                detail: "remote unavailable",
-              }),
-            );
-          }
-          if (input.args.join(" ") === "remote") {
-            didFailRemoteNames = true;
-            return Effect.fail(
-              new GitCommandError({
-                operation: "git.test.listBranchesRemoteNames",
-                command: `git ${input.args.join(" ")}`,
-                cwd: input.cwd,
-                detail: "remote unavailable",
-              }),
-            );
-          }
-          return realGitCore.execute(input);
-        });
-
-        const result = yield* core.listBranches({ cwd: tmp });
-
-        expect(result.isRepo).toBe(true);
-        expect(result.branches.length).toBeGreaterThan(0);
-        expect(result.branches.every((branch) => !branch.isRemote)).toBe(true);
-        expect(didFailRemoteBranches).toBe(true);
-        expect(didFailRemoteNames).toBe(true);
-      }),
-    );
-  });
-});
diff --git a/apps/server/src/git/Layers/GitHubCli.test.ts b/apps/server/src/git/Layers/GitHubCli.test.ts
deleted file mode 100644
index 0ee4b3f09ac..00000000000
--- a/apps/server/src/git/Layers/GitHubCli.test.ts
+++ /dev/null
@@ -1,227 +0,0 @@
-import { assert, it } from "@effect/vitest";
-import { Effect } from "effect";
-import { afterEach, expect, vi } from "vitest";
-
-vi.mock("../../processRunner", () => ({
-  runProcess: vi.fn(),
-}));
-
-import { runProcess } from "../../processRunner";
-import { GitHubCli } from "../Services/GitHubCli.ts";
-import { GitHubCliLive } from "./GitHubCli.ts";
-
-const mockedRunProcess = vi.mocked(runProcess);
-const layer = it.layer(GitHubCliLive);
-
-afterEach(() => {
-  mockedRunProcess.mockReset();
-});
-
-layer("GitHubCliLive", (it) => {
-  it.effect("parses pull request view output", () =>
-    Effect.gen(function* () {
-      mockedRunProcess.mockResolvedValueOnce({
-        stdout: JSON.stringify({
-          number: 42,
-          title: "Add PR thread creation",
-          url: "https://github.com/pingdotgg/codething-mvp/pull/42",
-          baseRefName: "main",
-          headRefName: "feature/pr-threads",
-          state: "OPEN",
-          mergedAt: null,
-          isCrossRepository: true,
-          headRepository: {
-            nameWithOwner: "octocat/codething-mvp",
-          },
-          headRepositoryOwner: {
-            login: "octocat",
-          },
-        }),
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
-
-      const result = yield* Effect.gen(function* () {
-        const gh = yield* GitHubCli;
-        return yield* gh.getPullRequest({
-          cwd: "/repo",
-          reference: "#42",
-        });
-      });
-
-      assert.deepStrictEqual(result, {
-        number: 42,
-        title: "Add PR thread creation",
-        url: "https://github.com/pingdotgg/codething-mvp/pull/42",
-        baseRefName: "main",
-        headRefName: "feature/pr-threads",
-        state: "open",
-        isCrossRepository: true,
-        headRepositoryNameWithOwner: "octocat/codething-mvp",
-        headRepositoryOwnerLogin: "octocat",
-      });
-      expect(mockedRunProcess).toHaveBeenCalledWith(
-        "gh",
-        [
-          "pr",
-          "view",
-          "#42",
-          "--json",
-          "number,title,url,baseRefName,headRefName,state,mergedAt,isCrossRepository,headRepository,headRepositoryOwner",
-        ],
-        expect.objectContaining({ cwd: "/repo" }),
-      );
-    }),
-  );
-
-  it.effect("trims pull request fields decoded from gh json", () =>
-    Effect.gen(function* () {
-      mockedRunProcess.mockResolvedValueOnce({
-        stdout: JSON.stringify({
-          number: 42,
-          title: "  Add PR thread creation  \n",
-          url: " https://github.com/pingdotgg/codething-mvp/pull/42 ",
-          baseRefName: " main ",
-          headRefName: "\tfeature/pr-threads\t",
-          state: "OPEN",
-          mergedAt: null,
-          isCrossRepository: true,
-          headRepository: {
-            nameWithOwner: " octocat/codething-mvp ",
-          },
-          headRepositoryOwner: {
-            login: " octocat ",
-          },
-        }),
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
-
-      const result = yield* Effect.gen(function* () {
-        const gh = yield* GitHubCli;
-        return yield* gh.getPullRequest({
-          cwd: "/repo",
-          reference: "#42",
-        });
-      });
-
-      assert.deepStrictEqual(result, {
-        number: 42,
-        title: "Add PR thread creation",
-        url: "https://github.com/pingdotgg/codething-mvp/pull/42",
-        baseRefName: "main",
-        headRefName: "feature/pr-threads",
-        state: "open",
-        isCrossRepository: true,
-        headRepositoryNameWithOwner: "octocat/codething-mvp",
-        headRepositoryOwnerLogin: "octocat",
-      });
-    }),
-  );
-
-  it.effect("skips invalid entries when parsing pr lists", () =>
-    Effect.gen(function* () {
-      mockedRunProcess.mockResolvedValueOnce({
-        stdout: JSON.stringify([
-          {
-            number: 0,
-            title: "invalid",
-            url: "https://github.com/pingdotgg/codething-mvp/pull/0",
-            baseRefName: "main",
-            headRefName: "feature/invalid",
-          },
-          {
-            number: 43,
-            title: "  Valid PR  ",
-            url: " https://github.com/pingdotgg/codething-mvp/pull/43 ",
-            baseRefName: " main ",
-            headRefName: " feature/pr-list ",
-            headRepository: {
-              nameWithOwner: "   ",
-            },
-            headRepositoryOwner: {
-              login: "   ",
-            },
-          },
-        ]),
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
-
-      const result = yield* Effect.gen(function* () {
-        const gh = yield* GitHubCli;
-        return yield* gh.listOpenPullRequests({
-          cwd: "/repo",
-          headSelector: "feature/pr-list",
-        });
-      });
-
-      assert.deepStrictEqual(result, [
-        {
-          number: 43,
-          title: "Valid PR",
-          url: "https://github.com/pingdotgg/codething-mvp/pull/43",
-          baseRefName: "main",
-          headRefName: "feature/pr-list",
-          state: "open",
-        },
-      ]);
-    }),
-  );
-
-  it.effect("reads repository clone URLs", () =>
-    Effect.gen(function* () {
-      mockedRunProcess.mockResolvedValueOnce({
-        stdout: JSON.stringify({
-          nameWithOwner: "octocat/codething-mvp",
-          url: "https://github.com/octocat/codething-mvp",
-          sshUrl: "git@github.com:octocat/codething-mvp.git",
-        }),
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
-
-      const result = yield* Effect.gen(function* () {
-        const gh = yield* GitHubCli;
-        return yield* gh.getRepositoryCloneUrls({
-          cwd: "/repo",
-          repository: "octocat/codething-mvp",
-        });
-      });
-
-      assert.deepStrictEqual(result, {
-        nameWithOwner: "octocat/codething-mvp",
-        url: "https://github.com/octocat/codething-mvp",
-        sshUrl: "git@github.com:octocat/codething-mvp.git",
-      });
-    }),
-  );
-
-  it.effect("surfaces a friendly error when the pull request is not found", () =>
-    Effect.gen(function* () {
-      mockedRunProcess.mockRejectedValueOnce(
-        new Error(
-          "GraphQL: Could not resolve to a PullRequest with the number of 4888. (repository.pullRequest)",
-        ),
-      );
-
-      const error = yield* Effect.gen(function* () {
-        const gh = yield* GitHubCli;
-        return yield* gh.getPullRequest({
-          cwd: "/repo",
-          reference: "4888",
-        });
-      }).pipe(Effect.flip);
-
-      assert.equal(error.message.includes("Pull request not found"), true);
-    }),
-  );
-});
diff --git a/apps/server/src/git/Layers/GitHubCli.ts b/apps/server/src/git/Layers/GitHubCli.ts
deleted file mode 100644
index 1a687b0e8dd..00000000000
--- a/apps/server/src/git/Layers/GitHubCli.ts
+++ /dev/null
@@ -1,240 +0,0 @@
-import { Effect, Layer, Result, Schema, SchemaIssue } from "effect";
-import { TrimmedNonEmptyString } from "@t3tools/contracts";
-
-import { runProcess } from "../../processRunner";
-import { GitHubCliError } from "@t3tools/contracts";
-import {
-  GitHubCli,
-  type GitHubRepositoryCloneUrls,
-  type GitHubCliShape,
-} from "../Services/GitHubCli.ts";
-import {
-  decodeGitHubPullRequestJson,
-  decodeGitHubPullRequestListJson,
-  formatGitHubJsonDecodeError,
-} from "../githubPullRequests.ts";
-
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-function normalizeGitHubCliError(operation: "execute" | "stdout", error: unknown): GitHubCliError {
-  if (error instanceof Error) {
-    if (error.message.includes("Command not found: gh")) {
-      return new GitHubCliError({
-        operation,
-        detail: "GitHub CLI (`gh`) is required but not available on PATH.",
-        cause: error,
-      });
-    }
-
-    const lower = error.message.toLowerCase();
-    if (
-      lower.includes("authentication failed") ||
-      lower.includes("not logged in") ||
-      lower.includes("gh auth login") ||
-      lower.includes("no oauth token")
-    ) {
-      return new GitHubCliError({
-        operation,
-        detail: "GitHub CLI is not authenticated. Run `gh auth login` and retry.",
-        cause: error,
-      });
-    }
-
-    if (
-      lower.includes("could not resolve to a pullrequest") ||
-      lower.includes("repository.pullrequest") ||
-      lower.includes("no pull requests found for branch") ||
-      lower.includes("pull request not found")
-    ) {
-      return new GitHubCliError({
-        operation,
-        detail: "Pull request not found. Check the PR number or URL and try again.",
-        cause: error,
-      });
-    }
-
-    return new GitHubCliError({
-      operation,
-      detail: `GitHub CLI command failed: ${error.message}`,
-      cause: error,
-    });
-  }
-
-  return new GitHubCliError({
-    operation,
-    detail: "GitHub CLI command failed.",
-    cause: error,
-  });
-}
-
-const RawGitHubRepositoryCloneUrlsSchema = Schema.Struct({
-  nameWithOwner: TrimmedNonEmptyString,
-  url: TrimmedNonEmptyString,
-  sshUrl: TrimmedNonEmptyString,
-});
-
-function normalizeRepositoryCloneUrls(
-  raw: Schema.Schema.Type<typeof RawGitHubRepositoryCloneUrlsSchema>,
-): GitHubRepositoryCloneUrls {
-  return {
-    nameWithOwner: raw.nameWithOwner,
-    url: raw.url,
-    sshUrl: raw.sshUrl,
-  };
-}
-
-function decodeGitHubJson<S extends Schema.Top>(
-  raw: string,
-  schema: S,
-  operation: "listOpenPullRequests" | "getPullRequest" | "getRepositoryCloneUrls",
-  invalidDetail: string,
-): Effect.Effect<S["Type"], GitHubCliError, S["DecodingServices"]> {
-  return Schema.decodeEffect(Schema.fromJsonString(schema))(raw).pipe(
-    Effect.mapError(
-      (error) =>
-        new GitHubCliError({
-          operation,
-          detail: `${invalidDetail}: ${SchemaIssue.makeFormatterDefault()(error.issue)}`,
-          cause: error,
-        }),
-    ),
-  );
-}
-
-const makeGitHubCli = Effect.sync(() => {
-  const execute: GitHubCliShape["execute"] = (input) =>
-    Effect.tryPromise({
-      try: () =>
-        runProcess("gh", input.args, {
-          cwd: input.cwd,
-          timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-        }),
-      catch: (error) => normalizeGitHubCliError("execute", error),
-    });
-
-  const service = {
-    execute,
-    listOpenPullRequests: (input) =>
-      execute({
-        cwd: input.cwd,
-        args: [
-          "pr",
-          "list",
-          "--head",
-          input.headSelector,
-          "--state",
-          "open",
-          "--limit",
-          String(input.limit ?? 1),
-          "--json",
-          "number,title,url,baseRefName,headRefName,state,mergedAt,isCrossRepository,headRepository,headRepositoryOwner",
-        ],
-      }).pipe(
-        Effect.map((result) => result.stdout.trim()),
-        Effect.flatMap((raw) =>
-          raw.length === 0
-            ? Effect.succeed([])
-            : Effect.sync(() => decodeGitHubPullRequestListJson(raw)).pipe(
-                Effect.flatMap((decoded) => {
-                  if (!Result.isSuccess(decoded)) {
-                    return Effect.fail(
-                      new GitHubCliError({
-                        operation: "listOpenPullRequests",
-                        detail: `GitHub CLI returned invalid PR list JSON: ${formatGitHubJsonDecodeError(decoded.failure)}`,
-                        cause: decoded.failure,
-                      }),
-                    );
-                  }
-
-                  return Effect.succeed(
-                    decoded.success.map(({ updatedAt: _updatedAt, ...summary }) => summary),
-                  );
-                }),
-              ),
-        ),
-      ),
-    getPullRequest: (input) =>
-      execute({
-        cwd: input.cwd,
-        args: [
-          "pr",
-          "view",
-          input.reference,
-          "--json",
-          "number,title,url,baseRefName,headRefName,state,mergedAt,isCrossRepository,headRepository,headRepositoryOwner",
-        ],
-      }).pipe(
-        Effect.map((result) => result.stdout.trim()),
-        Effect.flatMap((raw) =>
-          Effect.sync(() => decodeGitHubPullRequestJson(raw)).pipe(
-            Effect.flatMap((decoded) => {
-              if (!Result.isSuccess(decoded)) {
-                return Effect.fail(
-                  new GitHubCliError({
-                    operation: "getPullRequest",
-                    detail: `GitHub CLI returned invalid pull request JSON: ${formatGitHubJsonDecodeError(decoded.failure)}`,
-                    cause: decoded.failure,
-                  }),
-                );
-              }
-
-              return Effect.succeed(
-                (({ updatedAt: _updatedAt, ...summary }) => summary)(decoded.success),
-              );
-            }),
-          ),
-        ),
-      ),
-    getRepositoryCloneUrls: (input) =>
-      execute({
-        cwd: input.cwd,
-        args: ["repo", "view", input.repository, "--json", "nameWithOwner,url,sshUrl"],
-      }).pipe(
-        Effect.map((result) => result.stdout.trim()),
-        Effect.flatMap((raw) =>
-          decodeGitHubJson(
-            raw,
-            RawGitHubRepositoryCloneUrlsSchema,
-            "getRepositoryCloneUrls",
-            "GitHub CLI returned invalid repository JSON.",
-          ),
-        ),
-        Effect.map(normalizeRepositoryCloneUrls),
-      ),
-    createPullRequest: (input) =>
-      execute({
-        cwd: input.cwd,
-        args: [
-          "pr",
-          "create",
-          "--base",
-          input.baseBranch,
-          "--head",
-          input.headSelector,
-          "--title",
-          input.title,
-          "--body-file",
-          input.bodyFile,
-        ],
-      }).pipe(Effect.asVoid),
-    getDefaultBranch: (input) =>
-      execute({
-        cwd: input.cwd,
-        args: ["repo", "view", "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"],
-      }).pipe(
-        Effect.map((value) => {
-          const trimmed = value.stdout.trim();
-          return trimmed.length > 0 ? trimmed : null;
-        }),
-      ),
-    checkoutPullRequest: (input) =>
-      execute({
-        cwd: input.cwd,
-        args: ["pr", "checkout", input.reference, ...(input.force ? ["--force"] : [])],
-      }).pipe(Effect.asVoid),
-  } satisfies GitHubCliShape;
-
-  return service;
-});
-
-export const GitHubCliLive = Layer.effect(GitHubCli, makeGitHubCli);
diff --git a/apps/server/src/git/Layers/GitStatusBroadcaster.ts b/apps/server/src/git/Layers/GitStatusBroadcaster.ts
deleted file mode 100644
index 3ad7d095d8d..00000000000
--- a/apps/server/src/git/Layers/GitStatusBroadcaster.ts
+++ /dev/null
@@ -1,311 +0,0 @@
-import { realpathSync } from "node:fs";
-
-import {
-  Duration,
-  Effect,
-  Exit,
-  Fiber,
-  Layer,
-  PubSub,
-  Ref,
-  Scope,
-  Stream,
-  SynchronizedRef,
-} from "effect";
-import type {
-  GitStatusInput,
-  GitStatusLocalResult,
-  GitStatusRemoteResult,
-  GitStatusStreamEvent,
-} from "@t3tools/contracts";
-import { mergeGitStatusParts } from "@t3tools/shared/git";
-
-import {
-  GitStatusBroadcaster,
-  type GitStatusBroadcasterShape,
-} from "../Services/GitStatusBroadcaster.ts";
-import { GitManager } from "../Services/GitManager.ts";
-
-const GIT_STATUS_REFRESH_INTERVAL = Duration.seconds(30);
-
-interface GitStatusChange {
-  readonly cwd: string;
-  readonly event: GitStatusStreamEvent;
-}
-
-interface CachedValue<T> {
-  readonly fingerprint: string;
-  readonly value: T;
-}
-
-interface CachedGitStatus {
-  readonly local: CachedValue<GitStatusLocalResult> | null;
-  readonly remote: CachedValue<GitStatusRemoteResult | null> | null;
-}
-
-interface ActiveRemotePoller {
-  readonly fiber: Fiber.Fiber<void, never>;
-  readonly subscriberCount: number;
-}
-
-function normalizeCwd(cwd: string): string {
-  try {
-    return realpathSync.native(cwd);
-  } catch {
-    return cwd;
-  }
-}
-
-function fingerprintStatusPart(status: unknown): string {
-  return JSON.stringify(status);
-}
-
-export const GitStatusBroadcasterLive = Layer.effect(
-  GitStatusBroadcaster,
-  Effect.gen(function* () {
-    const gitManager = yield* GitManager;
-    const changesPubSub = yield* Effect.acquireRelease(
-      PubSub.unbounded<GitStatusChange>(),
-      (pubsub) => PubSub.shutdown(pubsub),
-    );
-    const broadcasterScope = yield* Effect.acquireRelease(Scope.make(), (scope) =>
-      Scope.close(scope, Exit.void),
-    );
-    const cacheRef = yield* Ref.make(new Map<string, CachedGitStatus>());
-    const pollersRef = yield* SynchronizedRef.make(new Map<string, ActiveRemotePoller>());
-
-    const getCachedStatus = Effect.fn("getCachedStatus")(function* (cwd: string) {
-      return yield* Ref.get(cacheRef).pipe(Effect.map((cache) => cache.get(cwd) ?? null));
-    });
-
-    const updateCachedLocalStatus = Effect.fn("updateCachedLocalStatus")(function* (
-      cwd: string,
-      local: GitStatusLocalResult,
-      options?: { publish?: boolean },
-    ) {
-      const nextLocal = {
-        fingerprint: fingerprintStatusPart(local),
-        value: local,
-      } satisfies CachedValue<GitStatusLocalResult>;
-      const shouldPublish = yield* Ref.modify(cacheRef, (cache) => {
-        const previous = cache.get(cwd) ?? { local: null, remote: null };
-        const nextCache = new Map(cache);
-        nextCache.set(cwd, {
-          ...previous,
-          local: nextLocal,
-        });
-        return [previous.local?.fingerprint !== nextLocal.fingerprint, nextCache] as const;
-      });
-
-      if (options?.publish && shouldPublish) {
-        yield* PubSub.publish(changesPubSub, {
-          cwd,
-          event: {
-            _tag: "localUpdated",
-            local,
-          },
-        });
-      }
-
-      return local;
-    });
-
-    const updateCachedRemoteStatus = Effect.fn("updateCachedRemoteStatus")(function* (
-      cwd: string,
-      remote: GitStatusRemoteResult | null,
-      options?: { publish?: boolean },
-    ) {
-      const nextRemote = {
-        fingerprint: fingerprintStatusPart(remote),
-        value: remote,
-      } satisfies CachedValue<GitStatusRemoteResult | null>;
-      const shouldPublish = yield* Ref.modify(cacheRef, (cache) => {
-        const previous = cache.get(cwd) ?? { local: null, remote: null };
-        const nextCache = new Map(cache);
-        nextCache.set(cwd, {
-          ...previous,
-          remote: nextRemote,
-        });
-        return [previous.remote?.fingerprint !== nextRemote.fingerprint, nextCache] as const;
-      });
-
-      if (options?.publish && shouldPublish) {
-        yield* PubSub.publish(changesPubSub, {
-          cwd,
-          event: {
-            _tag: "remoteUpdated",
-            remote,
-          },
-        });
-      }
-
-      return remote;
-    });
-
-    const loadLocalStatus = Effect.fn("loadLocalStatus")(function* (cwd: string) {
-      const local = yield* gitManager.localStatus({ cwd });
-      return yield* updateCachedLocalStatus(cwd, local);
-    });
-
-    const loadRemoteStatus = Effect.fn("loadRemoteStatus")(function* (cwd: string) {
-      const remote = yield* gitManager.remoteStatus({ cwd });
-      return yield* updateCachedRemoteStatus(cwd, remote);
-    });
-
-    const getOrLoadLocalStatus = Effect.fn("getOrLoadLocalStatus")(function* (cwd: string) {
-      const cached = yield* getCachedStatus(cwd);
-      if (cached?.local) {
-        return cached.local.value;
-      }
-      return yield* loadLocalStatus(cwd);
-    });
-
-    const getOrLoadRemoteStatus = Effect.fn("getOrLoadRemoteStatus")(function* (cwd: string) {
-      const cached = yield* getCachedStatus(cwd);
-      if (cached?.remote) {
-        return cached.remote.value;
-      }
-      return yield* loadRemoteStatus(cwd);
-    });
-
-    const getStatus: GitStatusBroadcasterShape["getStatus"] = Effect.fn("getStatus")(function* (
-      input: GitStatusInput,
-    ) {
-      const normalizedCwd = normalizeCwd(input.cwd);
-      const [local, remote] = yield* Effect.all([
-        getOrLoadLocalStatus(normalizedCwd),
-        getOrLoadRemoteStatus(normalizedCwd),
-      ]);
-      return mergeGitStatusParts(local, remote);
-    });
-
-    const refreshLocalStatus: GitStatusBroadcasterShape["refreshLocalStatus"] = Effect.fn(
-      "refreshLocalStatus",
-    )(function* (cwd) {
-      const normalizedCwd = normalizeCwd(cwd);
-      yield* gitManager.invalidateLocalStatus(normalizedCwd);
-      const local = yield* gitManager.localStatus({ cwd: normalizedCwd });
-      return yield* updateCachedLocalStatus(normalizedCwd, local, { publish: true });
-    });
-
-    const refreshRemoteStatus = Effect.fn("refreshRemoteStatus")(function* (cwd: string) {
-      yield* gitManager.invalidateRemoteStatus(cwd);
-      const remote = yield* gitManager.remoteStatus({ cwd });
-      return yield* updateCachedRemoteStatus(cwd, remote, { publish: true });
-    });
-
-    const refreshStatus: GitStatusBroadcasterShape["refreshStatus"] = Effect.fn("refreshStatus")(
-      function* (cwd) {
-        const normalizedCwd = normalizeCwd(cwd);
-        const [local, remote] = yield* Effect.all([
-          refreshLocalStatus(normalizedCwd),
-          refreshRemoteStatus(normalizedCwd),
-        ]);
-        return mergeGitStatusParts(local, remote);
-      },
-    );
-
-    const makeRemoteRefreshLoop = (cwd: string) => {
-      const logRefreshFailure = (error: Error) =>
-        Effect.logWarning("git remote status refresh failed", {
-          cwd,
-          detail: error.message,
-        });
-
-      return refreshRemoteStatus(cwd).pipe(
-        Effect.catch(logRefreshFailure),
-        Effect.andThen(
-          Effect.forever(
-            Effect.sleep(GIT_STATUS_REFRESH_INTERVAL).pipe(
-              Effect.andThen(refreshRemoteStatus(cwd).pipe(Effect.catch(logRefreshFailure))),
-            ),
-          ),
-        ),
-      );
-    };
-
-    const retainRemotePoller = Effect.fn("retainRemotePoller")(function* (cwd: string) {
-      yield* SynchronizedRef.modifyEffect(pollersRef, (activePollers) => {
-        const existing = activePollers.get(cwd);
-        if (existing) {
-          const nextPollers = new Map(activePollers);
-          nextPollers.set(cwd, {
-            ...existing,
-            subscriberCount: existing.subscriberCount + 1,
-          });
-          return Effect.succeed([undefined, nextPollers] as const);
-        }
-
-        return makeRemoteRefreshLoop(cwd).pipe(
-          Effect.forkIn(broadcasterScope),
-          Effect.map((fiber) => {
-            const nextPollers = new Map(activePollers);
-            nextPollers.set(cwd, {
-              fiber,
-              subscriberCount: 1,
-            });
-            return [undefined, nextPollers] as const;
-          }),
-        );
-      });
-    });
-
-    const releaseRemotePoller = Effect.fn("releaseRemotePoller")(function* (cwd: string) {
-      const pollerToInterrupt = yield* SynchronizedRef.modify(pollersRef, (activePollers) => {
-        const existing = activePollers.get(cwd);
-        if (!existing) {
-          return [null, activePollers] as const;
-        }
-
-        if (existing.subscriberCount > 1) {
-          const nextPollers = new Map(activePollers);
-          nextPollers.set(cwd, {
-            ...existing,
-            subscriberCount: existing.subscriberCount - 1,
-          });
-          return [null, nextPollers] as const;
-        }
-
-        const nextPollers = new Map(activePollers);
-        nextPollers.delete(cwd);
-        return [existing.fiber, nextPollers] as const;
-      });
-
-      if (pollerToInterrupt) {
-        yield* Fiber.interrupt(pollerToInterrupt).pipe(Effect.ignore);
-      }
-    });
-
-    const streamStatus: GitStatusBroadcasterShape["streamStatus"] = (input) =>
-      Stream.unwrap(
-        Effect.gen(function* () {
-          const normalizedCwd = normalizeCwd(input.cwd);
-          const subscription = yield* PubSub.subscribe(changesPubSub);
-          const initialLocal = yield* getOrLoadLocalStatus(normalizedCwd);
-          const initialRemote = (yield* getCachedStatus(normalizedCwd))?.remote?.value ?? null;
-          yield* retainRemotePoller(normalizedCwd);
-
-          const release = releaseRemotePoller(normalizedCwd).pipe(Effect.ignore, Effect.asVoid);
-
-          return Stream.concat(
-            Stream.make({
-              _tag: "snapshot" as const,
-              local: initialLocal,
-              remote: initialRemote,
-            }),
-            Stream.fromSubscription(subscription).pipe(
-              Stream.filter((event) => event.cwd === normalizedCwd),
-              Stream.map((event) => event.event),
-            ),
-          ).pipe(Stream.ensuring(release));
-        }),
-      );
-
-    return {
-      getStatus,
-      refreshLocalStatus,
-      refreshStatus,
-      streamStatus,
-    } satisfies GitStatusBroadcasterShape;
-  }),
-);
diff --git a/apps/server/src/git/Layers/RoutingTextGeneration.ts b/apps/server/src/git/Layers/RoutingTextGeneration.ts
deleted file mode 100644
index 5372bc13491..00000000000
--- a/apps/server/src/git/Layers/RoutingTextGeneration.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-/**
- * RoutingTextGeneration – Dispatches text generation requests to either the
- * Codex CLI or Claude CLI implementation based on the provider in each
- * request input.
- *
- * When `modelSelection.provider` is `"claudeAgent"` the request is forwarded to
- * the Claude layer; for any other value (including the default `undefined`) it
- * falls through to the Codex layer.
- *
- * @module RoutingTextGeneration
- */
-import { Effect, Layer, Context } from "effect";
-
-import {
-  TextGeneration,
-  type TextGenerationProvider,
-  type TextGenerationShape,
-} from "../Services/TextGeneration.ts";
-import { CodexTextGenerationLive } from "./CodexTextGeneration.ts";
-import { ClaudeTextGenerationLive } from "./ClaudeTextGeneration.ts";
-
-// ---------------------------------------------------------------------------
-// Internal service tags so both concrete layers can coexist.
-// ---------------------------------------------------------------------------
-
-class CodexTextGen extends Context.Service<CodexTextGen, TextGenerationShape>()(
-  "t3/git/Layers/RoutingTextGeneration/CodexTextGen",
-) {}
-
-class ClaudeTextGen extends Context.Service<ClaudeTextGen, TextGenerationShape>()(
-  "t3/git/Layers/RoutingTextGeneration/ClaudeTextGen",
-) {}
-
-// ---------------------------------------------------------------------------
-// Routing implementation
-// ---------------------------------------------------------------------------
-
-const makeRoutingTextGeneration = Effect.gen(function* () {
-  const codex = yield* CodexTextGen;
-  const claude = yield* ClaudeTextGen;
-
-  const route = (provider?: TextGenerationProvider): TextGenerationShape =>
-    provider === "claudeAgent" ? claude : codex;
-
-  return {
-    generateCommitMessage: (input) =>
-      route(input.modelSelection.provider).generateCommitMessage(input),
-    generatePrContent: (input) => route(input.modelSelection.provider).generatePrContent(input),
-    generateBranchName: (input) => route(input.modelSelection.provider).generateBranchName(input),
-    generateThreadTitle: (input) => route(input.modelSelection.provider).generateThreadTitle(input),
-  } satisfies TextGenerationShape;
-});
-
-const InternalCodexLayer = Layer.effect(
-  CodexTextGen,
-  Effect.gen(function* () {
-    const svc = yield* TextGeneration;
-    return svc;
-  }),
-).pipe(Layer.provide(CodexTextGenerationLive));
-
-const InternalClaudeLayer = Layer.effect(
-  ClaudeTextGen,
-  Effect.gen(function* () {
-    const svc = yield* TextGeneration;
-    return svc;
-  }),
-).pipe(Layer.provide(ClaudeTextGenerationLive));
-
-export const RoutingTextGenerationLive = Layer.effect(
-  TextGeneration,
-  makeRoutingTextGeneration,
-).pipe(Layer.provide(InternalCodexLayer), Layer.provide(InternalClaudeLayer));
diff --git a/apps/server/src/git/Services/GitCore.ts b/apps/server/src/git/Services/GitCore.ts
deleted file mode 100644
index 9f3bc0b9b91..00000000000
--- a/apps/server/src/git/Services/GitCore.ts
+++ /dev/null
@@ -1,313 +0,0 @@
-/**
- * GitCore - Effect service contract for low-level Git operations.
- *
- * Wraps core repository primitives used by higher-level orchestration
- * services and WebSocket routes.
- *
- * @module GitCore
- */
-import { Context } from "effect";
-import type { Effect } from "effect";
-import type {
-  GitCheckoutInput,
-  GitCheckoutResult,
-  GitCreateBranchInput,
-  GitCreateBranchResult,
-  GitCreateWorktreeInput,
-  GitCreateWorktreeResult,
-  GitInitInput,
-  GitListBranchesInput,
-  GitListBranchesResult,
-  GitPullResult,
-  GitRemoveWorktreeInput,
-  GitStatusInput,
-  GitStatusResult,
-} from "@t3tools/contracts";
-
-import type { GitCommandError } from "@t3tools/contracts";
-
-export interface ExecuteGitInput {
-  readonly operation: string;
-  readonly cwd: string;
-  readonly args: ReadonlyArray<string>;
-  readonly stdin?: string;
-  readonly env?: NodeJS.ProcessEnv;
-  readonly allowNonZeroExit?: boolean;
-  readonly timeoutMs?: number;
-  readonly maxOutputBytes?: number;
-  readonly truncateOutputAtMaxBytes?: boolean;
-  readonly progress?: ExecuteGitProgress;
-}
-
-export interface ExecuteGitResult {
-  readonly code: number;
-  readonly stdout: string;
-  readonly stderr: string;
-  readonly stdoutTruncated: boolean;
-  readonly stderrTruncated: boolean;
-}
-
-export interface GitStatusDetails extends Omit<GitStatusResult, "pr"> {
-  upstreamRef: string | null;
-}
-
-export interface GitPreparedCommitContext {
-  stagedSummary: string;
-  stagedPatch: string;
-}
-
-export interface ExecuteGitProgress {
-  readonly onStdoutLine?: (line: string) => Effect.Effect<void, never>;
-  readonly onStderrLine?: (line: string) => Effect.Effect<void, never>;
-  readonly onHookStarted?: (hookName: string) => Effect.Effect<void, never>;
-  readonly onHookFinished?: (input: {
-    hookName: string;
-    exitCode: number | null;
-    durationMs: number | null;
-  }) => Effect.Effect<void, never>;
-}
-
-export interface GitCommitProgress {
-  readonly onOutputLine?: (input: {
-    stream: "stdout" | "stderr";
-    text: string;
-  }) => Effect.Effect<void, never>;
-  readonly onHookStarted?: (hookName: string) => Effect.Effect<void, never>;
-  readonly onHookFinished?: (input: {
-    hookName: string;
-    exitCode: number | null;
-    durationMs: number | null;
-  }) => Effect.Effect<void, never>;
-}
-
-export interface GitCommitOptions {
-  readonly timeoutMs?: number;
-  readonly progress?: GitCommitProgress;
-}
-
-export interface GitPushResult {
-  status: "pushed" | "skipped_up_to_date";
-  branch: string;
-  upstreamBranch?: string | undefined;
-  setUpstream?: boolean | undefined;
-}
-
-export interface GitRangeContext {
-  commitSummary: string;
-  diffSummary: string;
-  diffPatch: string;
-}
-
-export interface GitListWorkspaceFilesResult {
-  readonly paths: ReadonlyArray<string>;
-  readonly truncated: boolean;
-}
-
-export interface GitRenameBranchInput {
-  cwd: string;
-  oldBranch: string;
-  newBranch: string;
-}
-
-export interface GitRenameBranchResult {
-  branch: string;
-}
-
-export interface GitFetchPullRequestBranchInput {
-  cwd: string;
-  prNumber: number;
-  branch: string;
-}
-
-export interface GitEnsureRemoteInput {
-  cwd: string;
-  preferredName: string;
-  url: string;
-}
-
-export interface GitFetchRemoteBranchInput {
-  cwd: string;
-  remoteName: string;
-  remoteBranch: string;
-  localBranch: string;
-}
-
-export interface GitSetBranchUpstreamInput {
-  cwd: string;
-  branch: string;
-  remoteName: string;
-  remoteBranch: string;
-}
-
-/**
- * GitCoreShape - Service API for low-level Git repository interactions.
- */
-export interface GitCoreShape {
-  /**
-   * Execute a raw Git command.
-   */
-  readonly execute: (input: ExecuteGitInput) => Effect.Effect<ExecuteGitResult, GitCommandError>;
-
-  /**
-   * Read Git status for a repository.
-   */
-  readonly status: (input: GitStatusInput) => Effect.Effect<GitStatusResult, GitCommandError>;
-
-  /**
-   * Read detailed working tree / branch status for a repository.
-   */
-  readonly statusDetails: (cwd: string) => Effect.Effect<GitStatusDetails, GitCommandError>;
-
-  /**
-   * Read detailed working tree / branch status without refreshing remote tracking refs.
-   */
-  readonly statusDetailsLocal: (cwd: string) => Effect.Effect<GitStatusDetails, GitCommandError>;
-
-  /**
-   * Build staged change context for commit generation.
-   */
-  readonly prepareCommitContext: (
-    cwd: string,
-    filePaths?: readonly string[],
-  ) => Effect.Effect<GitPreparedCommitContext | null, GitCommandError>;
-
-  /**
-   * Create a commit with provided subject/body.
-   */
-  readonly commit: (
-    cwd: string,
-    subject: string,
-    body: string,
-    options?: GitCommitOptions,
-  ) => Effect.Effect<{ commitSha: string }, GitCommandError>;
-
-  /**
-   * Push current branch, setting upstream if needed.
-   */
-  readonly pushCurrentBranch: (
-    cwd: string,
-    fallbackBranch: string | null,
-  ) => Effect.Effect<GitPushResult, GitCommandError>;
-
-  /**
-   * Collect commit/diff context between base branch and current HEAD.
-   */
-  readonly readRangeContext: (
-    cwd: string,
-    baseBranch: string,
-  ) => Effect.Effect<GitRangeContext, GitCommandError>;
-
-  /**
-   * Read a Git config value from the local repository.
-   */
-  readonly readConfigValue: (
-    cwd: string,
-    key: string,
-  ) => Effect.Effect<string | null, GitCommandError>;
-
-  /**
-   * Determine whether the provided cwd is inside a git work tree.
-   */
-  readonly isInsideWorkTree: (cwd: string) => Effect.Effect<boolean, GitCommandError>;
-
-  /**
-   * List tracked and untracked workspace file paths relative to cwd.
-   */
-  readonly listWorkspaceFiles: (
-    cwd: string,
-  ) => Effect.Effect<GitListWorkspaceFilesResult, GitCommandError>;
-
-  /**
-   * Remove gitignored paths from a relative path list.
-   */
-  readonly filterIgnoredPaths: (
-    cwd: string,
-    relativePaths: ReadonlyArray<string>,
-  ) => Effect.Effect<ReadonlyArray<string>, GitCommandError>;
-
-  /**
-   * List local + remote branches and branch metadata.
-   */
-  readonly listBranches: (
-    input: GitListBranchesInput,
-  ) => Effect.Effect<GitListBranchesResult, GitCommandError>;
-
-  /**
-   * Pull current branch from upstream using fast-forward only.
-   */
-  readonly pullCurrentBranch: (cwd: string) => Effect.Effect<GitPullResult, GitCommandError>;
-
-  /**
-   * Create a worktree and branch from a base branch.
-   */
-  readonly createWorktree: (
-    input: GitCreateWorktreeInput,
-  ) => Effect.Effect<GitCreateWorktreeResult, GitCommandError>;
-
-  /**
-   * Materialize a GitHub pull request head as a local branch without switching checkout.
-   */
-  readonly fetchPullRequestBranch: (
-    input: GitFetchPullRequestBranchInput,
-  ) => Effect.Effect<void, GitCommandError>;
-
-  /**
-   * Ensure a named remote exists for the provided URL, returning the reused or created remote name.
-   */
-  readonly ensureRemote: (input: GitEnsureRemoteInput) => Effect.Effect<string, GitCommandError>;
-
-  /**
-   * Fetch a remote branch into a local branch without checkout.
-   */
-  readonly fetchRemoteBranch: (
-    input: GitFetchRemoteBranchInput,
-  ) => Effect.Effect<void, GitCommandError>;
-
-  /**
-   * Set the upstream tracking branch for a local branch.
-   */
-  readonly setBranchUpstream: (
-    input: GitSetBranchUpstreamInput,
-  ) => Effect.Effect<void, GitCommandError>;
-
-  /**
-   * Remove an existing worktree.
-   */
-  readonly removeWorktree: (input: GitRemoveWorktreeInput) => Effect.Effect<void, GitCommandError>;
-
-  /**
-   * Rename an existing local branch.
-   */
-  readonly renameBranch: (
-    input: GitRenameBranchInput,
-  ) => Effect.Effect<GitRenameBranchResult, GitCommandError>;
-
-  /**
-   * Create a local branch.
-   */
-  readonly createBranch: (
-    input: GitCreateBranchInput,
-  ) => Effect.Effect<GitCreateBranchResult, GitCommandError>;
-
-  /**
-   * Checkout an existing branch and refresh its upstream metadata in background.
-   */
-  readonly checkoutBranch: (
-    input: GitCheckoutInput,
-  ) => Effect.Effect<GitCheckoutResult, GitCommandError>;
-
-  /**
-   * Initialize a repository in the provided directory.
-   */
-  readonly initRepo: (input: GitInitInput) => Effect.Effect<void, GitCommandError>;
-
-  /**
-   * List local branch names (short format).
-   */
-  readonly listLocalBranchNames: (cwd: string) => Effect.Effect<string[], GitCommandError>;
-}
-
-/**
- * GitCore - Service tag for low-level Git repository operations.
- */
-export class GitCore extends Context.Service<GitCore, GitCoreShape>()("t3/git/Services/GitCore") {}
diff --git a/apps/server/src/git/Services/GitHubCli.ts b/apps/server/src/git/Services/GitHubCli.ts
deleted file mode 100644
index 216c24bf7c5..00000000000
--- a/apps/server/src/git/Services/GitHubCli.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-/**
- * GitHubCli - Effect service contract for `gh` process interactions.
- *
- * Provides thin command execution helpers used by Git workflow orchestration.
- *
- * @module GitHubCli
- */
-import { Context } from "effect";
-import type { Effect } from "effect";
-
-import type { ProcessRunResult } from "../../processRunner";
-import type { GitHubCliError } from "@t3tools/contracts";
-
-export interface GitHubPullRequestSummary {
-  readonly number: number;
-  readonly title: string;
-  readonly url: string;
-  readonly baseRefName: string;
-  readonly headRefName: string;
-  readonly state?: "open" | "closed" | "merged";
-  readonly isCrossRepository?: boolean;
-  readonly headRepositoryNameWithOwner?: string | null;
-  readonly headRepositoryOwnerLogin?: string | null;
-}
-
-export interface GitHubRepositoryCloneUrls {
-  readonly nameWithOwner: string;
-  readonly url: string;
-  readonly sshUrl: string;
-}
-
-/**
- * GitHubCliShape - Service API for executing GitHub CLI commands.
- */
-export interface GitHubCliShape {
-  /**
-   * Execute a GitHub CLI command and return full process output.
-   */
-  readonly execute: (input: {
-    readonly cwd: string;
-    readonly args: ReadonlyArray<string>;
-    readonly timeoutMs?: number;
-  }) => Effect.Effect<ProcessRunResult, GitHubCliError>;
-
-  /**
-   * List open pull requests for a head branch.
-   */
-  readonly listOpenPullRequests: (input: {
-    readonly cwd: string;
-    readonly headSelector: string;
-    readonly limit?: number;
-  }) => Effect.Effect<ReadonlyArray<GitHubPullRequestSummary>, GitHubCliError>;
-
-  /**
-   * Resolve a pull request by URL, number, or branch-ish identifier.
-   */
-  readonly getPullRequest: (input: {
-    readonly cwd: string;
-    readonly reference: string;
-  }) => Effect.Effect<GitHubPullRequestSummary, GitHubCliError>;
-
-  /**
-   * Resolve clone URLs for a GitHub repository.
-   */
-  readonly getRepositoryCloneUrls: (input: {
-    readonly cwd: string;
-    readonly repository: string;
-  }) => Effect.Effect<GitHubRepositoryCloneUrls, GitHubCliError>;
-
-  /**
-   * Create a pull request from branch context and body file.
-   */
-  readonly createPullRequest: (input: {
-    readonly cwd: string;
-    readonly baseBranch: string;
-    readonly headSelector: string;
-    readonly title: string;
-    readonly bodyFile: string;
-  }) => Effect.Effect<void, GitHubCliError>;
-
-  /**
-   * Resolve repository default branch through GitHub metadata.
-   */
-  readonly getDefaultBranch: (input: {
-    readonly cwd: string;
-  }) => Effect.Effect<string | null, GitHubCliError>;
-
-  /**
-   * Checkout a pull request into the current repository worktree.
-   */
-  readonly checkoutPullRequest: (input: {
-    readonly cwd: string;
-    readonly reference: string;
-    readonly force?: boolean;
-  }) => Effect.Effect<void, GitHubCliError>;
-}
-
-/**
- * GitHubCli - Service tag for GitHub CLI process execution.
- */
-export class GitHubCli extends Context.Service<GitHubCli, GitHubCliShape>()(
-  "t3/git/Services/GitHubCli",
-) {}
diff --git a/apps/server/src/git/Services/GitManager.ts b/apps/server/src/git/Services/GitManager.ts
deleted file mode 100644
index 29c762195e5..00000000000
--- a/apps/server/src/git/Services/GitManager.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-/**
- * GitManager - Effect service contract for stacked Git workflows.
- *
- * Orchestrates status inspection and commit/push/PR flows by composing
- * lower-level Git and external tool services.
- *
- * @module GitManager
- */
-import {
-  GitActionProgressEvent,
-  GitPreparePullRequestThreadInput,
-  GitPreparePullRequestThreadResult,
-  GitPullRequestRefInput,
-  GitResolvePullRequestResult,
-  GitRunStackedActionInput,
-  GitRunStackedActionResult,
-  GitStatusLocalResult,
-  GitStatusRemoteResult,
-  GitStatusInput,
-  GitStatusResult,
-} from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect } from "effect";
-import type { GitManagerServiceError } from "@t3tools/contracts";
-
-export interface GitActionProgressReporter {
-  readonly publish: (event: GitActionProgressEvent) => Effect.Effect<void, never>;
-}
-
-export interface GitRunStackedActionOptions {
-  readonly actionId?: string;
-  readonly progressReporter?: GitActionProgressReporter;
-}
-
-/**
- * GitManagerShape - Service API for high-level Git workflow actions.
- */
-export interface GitManagerShape {
-  /**
-   * Read current repository Git status plus open PR metadata when available.
-   */
-  readonly status: (
-    input: GitStatusInput,
-  ) => Effect.Effect<GitStatusResult, GitManagerServiceError>;
-
-  /**
-   * Read local repository status without remote hosting enrichment.
-   */
-  readonly localStatus: (
-    input: GitStatusInput,
-  ) => Effect.Effect<GitStatusLocalResult, GitManagerServiceError>;
-
-  /**
-   * Read remote tracking / PR status for a repository.
-   */
-  readonly remoteStatus: (
-    input: GitStatusInput,
-  ) => Effect.Effect<GitStatusRemoteResult | null, GitManagerServiceError>;
-
-  /**
-   * Clear any cached local status snapshot for a repository.
-   */
-  readonly invalidateLocalStatus: (cwd: string) => Effect.Effect<void, never>;
-
-  /**
-   * Clear any cached remote status snapshot for a repository.
-   */
-  readonly invalidateRemoteStatus: (cwd: string) => Effect.Effect<void, never>;
-
-  /**
-   * Clear any cached status snapshot for a repository so the next read is fresh.
-   */
-  readonly invalidateStatus: (cwd: string) => Effect.Effect<void, never>;
-
-  /**
-   * Resolve a pull request by URL/number against the current repository.
-   */
-  readonly resolvePullRequest: (
-    input: GitPullRequestRefInput,
-  ) => Effect.Effect<GitResolvePullRequestResult, GitManagerServiceError>;
-
-  /**
-   * Prepare a new thread workspace from a pull request in local or worktree mode.
-   */
-  readonly preparePullRequestThread: (
-    input: GitPreparePullRequestThreadInput,
-  ) => Effect.Effect<GitPreparePullRequestThreadResult, GitManagerServiceError>;
-
-  /**
-   * Run a Git action (`commit`, `push`, `create_pr`, `commit_push`, `commit_push_pr`).
-   * When `featureBranch` is set, creates and checks out a feature branch first.
-   */
-  readonly runStackedAction: (
-    input: GitRunStackedActionInput,
-    options?: GitRunStackedActionOptions,
-  ) => Effect.Effect<GitRunStackedActionResult, GitManagerServiceError>;
-}
-
-/**
- * GitManager - Service tag for stacked Git workflow orchestration.
- */
-export class GitManager extends Context.Service<GitManager, GitManagerShape>()(
-  "t3/git/Services/GitManager",
-) {}
diff --git a/apps/server/src/git/Services/GitStatusBroadcaster.ts b/apps/server/src/git/Services/GitStatusBroadcaster.ts
deleted file mode 100644
index 647f8408242..00000000000
--- a/apps/server/src/git/Services/GitStatusBroadcaster.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { Context } from "effect";
-import type { Effect, Stream } from "effect";
-import type {
-  GitManagerServiceError,
-  GitStatusInput,
-  GitStatusLocalResult,
-  GitStatusResult,
-  GitStatusStreamEvent,
-} from "@t3tools/contracts";
-
-export interface GitStatusBroadcasterShape {
-  readonly getStatus: (
-    input: GitStatusInput,
-  ) => Effect.Effect<GitStatusResult, GitManagerServiceError>;
-  readonly refreshLocalStatus: (
-    cwd: string,
-  ) => Effect.Effect<GitStatusLocalResult, GitManagerServiceError>;
-  readonly refreshStatus: (cwd: string) => Effect.Effect<GitStatusResult, GitManagerServiceError>;
-  readonly streamStatus: (
-    input: GitStatusInput,
-  ) => Stream.Stream<GitStatusStreamEvent, GitManagerServiceError>;
-}
-
-export class GitStatusBroadcaster extends Context.Service<
-  GitStatusBroadcaster,
-  GitStatusBroadcasterShape
->()("t3/git/Services/GitStatusBroadcaster") {}
diff --git a/apps/server/src/git/Utils.ts b/apps/server/src/git/Utils.ts
index 4a7931c74b2..b414daaa0a4 100644
--- a/apps/server/src/git/Utils.ts
+++ b/apps/server/src/git/Utils.ts
@@ -1,123 +1,7 @@
-/**
- * Shared utilities for text generation layers (Codex, Claude, etc.).
- *
- * @module textGenerationUtils
- */
-import { Schema } from "effect";
-
-import { TextGenerationError } from "@t3tools/contracts";
-
+// @effect-diagnostics nodeBuiltinImport:off
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
 export function isGitRepository(cwd: string): boolean {
   return existsSync(join(cwd, ".git"));
 }
-
-/** Convert an Effect Schema to a flat JSON Schema object, inlining `$defs` when present. */
-export function toJsonSchemaObject(schema: Schema.Top): unknown {
-  const document = Schema.toJsonSchemaDocument(schema);
-  if (document.definitions && Object.keys(document.definitions).length > 0) {
-    return { ...document.schema, $defs: document.definitions };
-  }
-  return document.schema;
-}
-
-/** Truncate a text section to `maxChars`, appending a `[truncated]` marker when needed. */
-export function limitSection(value: string, maxChars: number): string {
-  if (value.length <= maxChars) return value;
-  const truncated = value.slice(0, maxChars);
-  return `${truncated}\n\n[truncated]`;
-}
-
-/** Normalise a raw commit subject to imperative-mood, ≤72 chars, no trailing period. */
-export function sanitizeCommitSubject(raw: string): string {
-  const singleLine = raw.trim().split(/\r?\n/g)[0]?.trim() ?? "";
-  const withoutTrailingPeriod = singleLine.replace(/[.]+$/g, "").trim();
-  if (withoutTrailingPeriod.length === 0) {
-    return "Update project files";
-  }
-
-  if (withoutTrailingPeriod.length <= 72) {
-    return withoutTrailingPeriod;
-  }
-  return withoutTrailingPeriod.slice(0, 72).trimEnd();
-}
-
-/** Normalise a raw PR title to a single line with a sensible fallback. */
-export function sanitizePrTitle(raw: string): string {
-  const singleLine = raw.trim().split(/\r?\n/g)[0]?.trim() ?? "";
-  if (singleLine.length > 0) {
-    return singleLine;
-  }
-  return "Update project changes";
-}
-
-/** Normalise a raw thread title to a compact single-line sidebar-safe label. */
-export function sanitizeThreadTitle(raw: string): string {
-  const normalized = raw
-    .trim()
-    .split(/\r?\n/g)[0]
-    ?.trim()
-    .replace(/^['"`]+|['"`]+$/g, "")
-    .trim()
-    .replace(/\s+/g, " ");
-
-  if (!normalized || normalized.trim().length === 0) {
-    return "New thread";
-  }
-
-  if (normalized.length <= 50) {
-    return normalized;
-  }
-
-  return `${normalized.slice(0, 47).trimEnd()}...`;
-}
-
-/** CLI name to human-readable label, e.g. "codex" → "Codex CLI (`codex`)" */
-function cliLabel(cliName: string): string {
-  const capitalized = cliName.charAt(0).toUpperCase() + cliName.slice(1);
-  return `${capitalized} CLI (\`${cliName}\`)`;
-}
-
-/**
- * Normalize an unknown error from a CLI text generation process into a
- * typed `TextGenerationError`. Parameterized by CLI name so both Codex
- * and Claude (and future providers) can share the same logic.
- */
-export function normalizeCliError(
-  cliName: string,
-  operation: string,
-  error: unknown,
-  fallback: string,
-): TextGenerationError {
-  if (Schema.is(TextGenerationError)(error)) {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    const lower = error.message.toLowerCase();
-    if (
-      error.message.includes(`Command not found: ${cliName}`) ||
-      lower.includes(`spawn ${cliName}`) ||
-      lower.includes("enoent")
-    ) {
-      return new TextGenerationError({
-        operation,
-        detail: `${cliLabel(cliName)} is required but not available on PATH.`,
-        cause: error,
-      });
-    }
-    return new TextGenerationError({
-      operation,
-      detail: `${fallback}: ${error.message}`,
-      cause: error,
-    });
-  }
-
-  return new TextGenerationError({
-    operation,
-    detail: fallback,
-    cause: error,
-  });
-}
diff --git a/apps/server/src/http.ts b/apps/server/src/http.ts
index ed403894291..f287b4c59bf 100644
--- a/apps/server/src/http.ts
+++ b/apps/server/src/http.ts
@@ -1,5 +1,10 @@
 import Mime from "@effect/platform-node/Mime";
-import { Data, Effect, FileSystem, Option, Path } from "effect";
+import { decodeOtlpTraceRecords } from "@t3tools/shared/observability";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
 import { cast } from "effect/Function";
 import {
   HttpBody,
@@ -15,15 +20,19 @@ import {
   ATTACHMENTS_ROUTE_PREFIX,
   normalizeAttachmentRelativePath,
   resolveAttachmentRelativePath,
-} from "./attachmentPaths";
-import { resolveAttachmentPathById } from "./attachmentStore";
-import { resolveStaticDir, ServerConfig } from "./config";
-import { decodeOtlpTraceRecords } from "./observability/TraceRecord.ts";
+} from "./attachmentPaths.ts";
+import { resolveAttachmentPathById } from "./attachmentStore.ts";
+import { resolveStaticDir, ServerConfig } from "./config.ts";
 import { BrowserTraceCollector } from "./observability/Services/BrowserTraceCollector.ts";
-import { ProjectFaviconResolver } from "./project/Services/ProjectFaviconResolver";
+import { ProjectFaviconResolver } from "./project/Services/ProjectFaviconResolver.ts";
 import { ServerAuth } from "./auth/Services/ServerAuth.ts";
 import { respondToAuthError } from "./auth/http.ts";
 import { ServerEnvironment } from "./environment/Services/ServerEnvironment.ts";
+import {
+  browserApiCorsAllowedHeaders,
+  browserApiCorsAllowedMethods,
+  browserApiCorsHeaders,
+} from "./httpCors.ts";
 
 const PROJECT_FAVICON_CACHE_CONTROL = "public, max-age=3600";
 const FALLBACK_PROJECT_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="#6b728080" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" data-fallback="project-favicon"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-8l-2-2H4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2Z"/></svg>`;
@@ -31,8 +40,8 @@ const OTLP_TRACES_PROXY_PATH = "/api/observability/v1/traces";
 const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "::1", "localhost"]);
 
 export const browserApiCorsLayer = HttpRouter.cors({
-  allowedMethods: ["GET", "POST", "OPTIONS"],
-  allowedHeaders: ["authorization", "b3", "traceparent", "content-type"],
+  allowedMethods: [...browserApiCorsAllowedMethods],
+  allowedHeaders: [...browserApiCorsAllowedHeaders],
   maxAge: 600,
 });
 
@@ -65,7 +74,10 @@ export const serverEnvironmentRouteLayer = HttpRouter.add(
     const descriptor = yield* Effect.service(ServerEnvironment).pipe(
       Effect.flatMap((serverEnvironment) => serverEnvironment.getDescriptor),
     );
-    return HttpServerResponse.jsonUnsafe(descriptor, { status: 200 });
+    return HttpServerResponse.jsonUnsafe(descriptor, {
+      status: 200,
+      headers: browserApiCorsHeaders,
+    });
   }),
 );
 
@@ -226,6 +238,7 @@ export const staticAndDevRouteLayer = HttpRouter.add(
   Effect.gen(function* () {
     const request = yield* HttpServerRequest.HttpServerRequest;
     const url = HttpServerRequest.toURL(request);
+
     if (Option.isNone(url)) {
       return HttpServerResponse.text("Bad Request", { status: 400 });
     }
diff --git a/apps/server/src/httpCors.ts b/apps/server/src/httpCors.ts
new file mode 100644
index 00000000000..e44486d3c4b
--- /dev/null
+++ b/apps/server/src/httpCors.ts
@@ -0,0 +1,13 @@
+export const browserApiCorsAllowedMethods = ["GET", "POST", "OPTIONS"] as const;
+export const browserApiCorsAllowedHeaders = [
+  "authorization",
+  "b3",
+  "traceparent",
+  "content-type",
+] as const;
+
+export const browserApiCorsHeaders = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": browserApiCorsAllowedMethods.join(", "),
+  "access-control-allow-headers": browserApiCorsAllowedHeaders.join(", "),
+} as const;
diff --git a/apps/server/src/keybindings.test.ts b/apps/server/src/keybindings.test.ts
index e3f190ff061..188a8d32d18 100644
--- a/apps/server/src/keybindings.test.ts
+++ b/apps/server/src/keybindings.test.ts
@@ -2,8 +2,14 @@ import { KeybindingCommand, KeybindingRule, KeybindingsConfig } from "@t3tools/c
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import { assertFailure } from "@effect/vitest/utils";
-import { Cause, Effect, FileSystem, Layer, Logger, Path, Schema } from "effect";
-import { ServerConfig } from "./config";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { ServerConfig } from "./config.ts";
 
 import {
   DEFAULT_KEYBINDINGS,
@@ -13,10 +19,16 @@ import {
   compileResolvedKeybindingRule,
   compileResolvedKeybindingsConfig,
   parseKeybindingShortcut,
-} from "./keybindings";
+} from "./keybindings.ts";
 import { KeybindingsConfigError } from "@t3tools/contracts";
 
 const KeybindingsConfigJson = Schema.fromJsonString(KeybindingsConfig);
+const encodeKeybindingsConfigJson = Schema.encodeEffect(KeybindingsConfigJson);
+const decodeKeybindingsConfigJson = Schema.decodeUnknownEffect(KeybindingsConfigJson);
+const encodeResolvedKeybindingFromConfig = Schema.encodeEffect(ResolvedKeybindingFromConfig);
+const decodeResolvedKeybindingFromConfigExit = Schema.decodeUnknownExit(
+  ResolvedKeybindingFromConfig,
+);
 const makeKeybindingsLayer = () => {
   return KeybindingsLive.pipe(
     Layer.provideMerge(
@@ -39,7 +51,7 @@ const writeKeybindingsConfig = (configPath: string, rules: readonly KeybindingRu
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const encoded = yield* Schema.encodeEffect(KeybindingsConfigJson)(rules);
+    const encoded = yield* encodeKeybindingsConfigJson(rules);
     yield* fileSystem.makeDirectory(path.dirname(configPath), { recursive: true });
     yield* fileSystem.writeFileString(configPath, encoded);
   });
@@ -48,7 +60,7 @@ const readKeybindingsConfig = (configPath: string) =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const rawConfig = yield* fileSystem.readFileString(configPath);
-    return yield* Schema.decodeUnknownEffect(KeybindingsConfigJson)(rawConfig);
+    return yield* decodeKeybindingsConfigJson(rawConfig);
   });
 
 it.layer(NodeServices.layer)("keybindings", (it) => {
@@ -105,7 +117,7 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
 
   it.effect("encodes resolved plus-key shortcuts", () =>
     Effect.gen(function* () {
-      const encoded = yield* Schema.encodeEffect(ResolvedKeybindingFromConfig)({
+      const encoded = yield* encodeResolvedKeybindingFromConfig({
         command: "terminal.toggle",
         shortcut: {
           key: "+",
@@ -151,7 +163,7 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
 
   it.effect("formats invalid resolved keybinding rules with the custom message", () =>
     Effect.sync(() => {
-      const result = Schema.decodeUnknownExit(ResolvedKeybindingFromConfig)({
+      const result = decodeResolvedKeybindingFromConfigExit({
         key: "mod+shift+d+o",
         command: "terminal.new",
       });
@@ -192,6 +204,9 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
       assert.equal(defaultsByCommand.get("thread.next"), "mod+shift+]");
       assert.equal(defaultsByCommand.get("thread.jump.1"), "mod+1");
       assert.equal(defaultsByCommand.get("thread.jump.9"), "mod+9");
+      assert.equal(defaultsByCommand.get("modelPicker.toggle"), "mod+shift+m");
+      assert.equal(defaultsByCommand.get("modelPicker.jump.1"), "mod+1");
+      assert.equal(defaultsByCommand.get("modelPicker.jump.9"), "mod+9");
     }),
   );
 
@@ -226,6 +241,7 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
       const { keybindingsConfigPath } = yield* ServerConfig;
       yield* fs.writeFileString(
         keybindingsConfigPath,
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         JSON.stringify([
           { key: "mod+j", command: "terminal.toggle" },
           { key: "mod+shift+d+o", command: "terminal.new" },
@@ -351,7 +367,7 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
     }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
-  it.effect("replaces existing custom keybinding for the same command", () =>
+  it.effect("appends additional custom keybindings for the same command", () =>
     Effect.gen(function* () {
       const { keybindingsConfigPath } = yield* ServerConfig;
       yield* writeKeybindingsConfig(keybindingsConfigPath, [
@@ -365,6 +381,55 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
         });
       });
 
+      const persisted = yield* readKeybindingsConfig(keybindingsConfigPath);
+      const persistedView = persisted.map(({ key, command }) => ({ key, command }));
+      assert.deepEqual(persistedView, [
+        { key: "mod+r", command: "script.run-tests.run" },
+        { key: "mod+shift+r", command: "script.run-tests.run" },
+      ]);
+    }).pipe(Effect.provide(makeKeybindingsLayer())),
+  );
+
+  it.effect("replaces only the targeted custom keybinding", () =>
+    Effect.gen(function* () {
+      const { keybindingsConfigPath } = yield* ServerConfig;
+      yield* writeKeybindingsConfig(keybindingsConfigPath, [
+        { key: "mod+r", command: "script.run-tests.run" },
+        { key: "mod+shift+r", command: "script.run-tests.run" },
+      ]);
+      yield* Effect.gen(function* () {
+        const keybindings = yield* Keybindings;
+        return yield* keybindings.upsertKeybindingRule({
+          key: "mod+alt+r",
+          command: "script.run-tests.run",
+          replace: { key: "mod+r", command: "script.run-tests.run" },
+        });
+      });
+
+      const persisted = yield* readKeybindingsConfig(keybindingsConfigPath);
+      const persistedView = persisted.map(({ key, command }) => ({ key, command }));
+      assert.deepEqual(persistedView, [
+        { key: "mod+shift+r", command: "script.run-tests.run" },
+        { key: "mod+alt+r", command: "script.run-tests.run" },
+      ]);
+    }).pipe(Effect.provide(makeKeybindingsLayer())),
+  );
+
+  it.effect("removes only the targeted custom keybinding", () =>
+    Effect.gen(function* () {
+      const { keybindingsConfigPath } = yield* ServerConfig;
+      yield* writeKeybindingsConfig(keybindingsConfigPath, [
+        { key: "mod+r", command: "script.run-tests.run" },
+        { key: "mod+shift+r", command: "script.run-tests.run" },
+      ]);
+      yield* Effect.gen(function* () {
+        const keybindings = yield* Keybindings;
+        return yield* keybindings.removeKeybindingRule({
+          key: "mod+r",
+          command: "script.run-tests.run",
+        });
+      });
+
       const persisted = yield* readKeybindingsConfig(keybindingsConfigPath);
       const persistedView = persisted.map(({ key, command }) => ({ key, command }));
       assert.deepEqual(persistedView, [{ key: "mod+shift+r", command: "script.run-tests.run" }]);
diff --git a/apps/server/src/keybindings.ts b/apps/server/src/keybindings.ts
index b473f77ca1b..a197984f23a 100644
--- a/apps/server/src/keybindings.ts
+++ b/apps/server/src/keybindings.ts
@@ -13,305 +13,50 @@ import {
   KeybindingShortcut,
   KeybindingWhenNode,
   MAX_KEYBINDINGS_COUNT,
-  MAX_WHEN_EXPRESSION_DEPTH,
   ResolvedKeybindingRule,
   ResolvedKeybindingsConfig,
-  THREAD_JUMP_KEYBINDING_COMMANDS,
+  type ServerRemoveKeybindingInput,
+  type ServerUpsertKeybindingInput,
   type ServerConfigIssue,
 } from "@t3tools/contracts";
-import { Mutable } from "effect/Types";
-import {
-  Array,
-  Cache,
-  Cause,
-  Deferred,
-  Duration,
-  Effect,
-  Exit,
-  FileSystem,
-  Path,
-  Layer,
-  Option,
-  Predicate,
-  PubSub,
-  Schema,
-  SchemaGetter,
-  SchemaIssue,
-  SchemaTransformation,
-  Ref,
-  Context,
-  Scope,
-  Stream,
-} from "effect";
+import * as Array from "effect/Array";
+import * as Cache from "effect/Cache";
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as PubSub from "effect/PubSub";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import * as Ref from "effect/Ref";
+import * as Context from "effect/Context";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import * as Semaphore from "effect/Semaphore";
-import { ServerConfig } from "./config";
-import { fromLenientJson } from "@t3tools/shared/schemaJson";
-
-type WhenToken =
-  | { type: "identifier"; value: string }
-  | { type: "not" }
-  | { type: "and" }
-  | { type: "or" }
-  | { type: "lparen" }
-  | { type: "rparen" };
-
-export const DEFAULT_KEYBINDINGS: ReadonlyArray<KeybindingRule> = [
-  { key: "mod+j", command: "terminal.toggle" },
-  { key: "mod+d", command: "terminal.split", when: "terminalFocus" },
-  { key: "mod+n", command: "terminal.new", when: "terminalFocus" },
-  { key: "mod+w", command: "terminal.close", when: "terminalFocus" },
-  { key: "mod+d", command: "diff.toggle", when: "!terminalFocus" },
-  { key: "mod+k", command: "commandPalette.toggle", when: "!terminalFocus" },
-  { key: "mod+n", command: "chat.new", when: "!terminalFocus" },
-  { key: "mod+shift+o", command: "chat.new", when: "!terminalFocus" },
-  { key: "mod+shift+n", command: "chat.newLocal", when: "!terminalFocus" },
-  { key: "mod+o", command: "editor.openFavorite" },
-  { key: "mod+shift+[", command: "thread.previous" },
-  { key: "mod+shift+]", command: "thread.next" },
-  ...THREAD_JUMP_KEYBINDING_COMMANDS.map((command, index) => ({
-    key: `mod+${index + 1}`,
-    command,
-  })),
-];
-
-function normalizeKeyToken(token: string): string {
-  if (token === "space") return " ";
-  if (token === "esc") return "escape";
-  return token;
-}
-
-/** @internal - Exported for testing */
-export function parseKeybindingShortcut(value: string): KeybindingShortcut | null {
-  const rawTokens = value
-    .toLowerCase()
-    .split("+")
-    .map((token) => token.trim());
-  const tokens = [...rawTokens];
-  let trailingEmptyCount = 0;
-  while (tokens[tokens.length - 1] === "") {
-    trailingEmptyCount += 1;
-    tokens.pop();
-  }
-  if (trailingEmptyCount > 0) {
-    tokens.push("+");
-  }
-  if (tokens.some((token) => token.length === 0)) {
-    return null;
-  }
-  if (tokens.length === 0) return null;
-
-  let key: string | null = null;
-  let metaKey = false;
-  let ctrlKey = false;
-  let shiftKey = false;
-  let altKey = false;
-  let modKey = false;
-
-  for (const token of tokens) {
-    switch (token) {
-      case "cmd":
-      case "meta":
-        metaKey = true;
-        break;
-      case "ctrl":
-      case "control":
-        ctrlKey = true;
-        break;
-      case "shift":
-        shiftKey = true;
-        break;
-      case "alt":
-      case "option":
-        altKey = true;
-        break;
-      case "mod":
-        modKey = true;
-        break;
-      default: {
-        if (key !== null) return null;
-        key = normalizeKeyToken(token);
-      }
-    }
-  }
-
-  if (key === null) return null;
-  return {
-    key,
-    metaKey,
-    ctrlKey,
-    shiftKey,
-    altKey,
-    modKey,
-  };
-}
-
-function tokenizeWhenExpression(expression: string): WhenToken[] | null {
-  const tokens: WhenToken[] = [];
-  let index = 0;
-
-  while (index < expression.length) {
-    const current = expression[index];
-    if (!current) break;
-
-    if (/\s/.test(current)) {
-      index += 1;
-      continue;
-    }
-    if (expression.startsWith("&&", index)) {
-      tokens.push({ type: "and" });
-      index += 2;
-      continue;
-    }
-    if (expression.startsWith("||", index)) {
-      tokens.push({ type: "or" });
-      index += 2;
-      continue;
-    }
-    if (current === "!") {
-      tokens.push({ type: "not" });
-      index += 1;
-      continue;
-    }
-    if (current === "(") {
-      tokens.push({ type: "lparen" });
-      index += 1;
-      continue;
-    }
-    if (current === ")") {
-      tokens.push({ type: "rparen" });
-      index += 1;
-      continue;
-    }
-
-    const identifier = /^[A-Za-z_][A-Za-z0-9_.-]*/.exec(expression.slice(index));
-    if (!identifier) {
-      return null;
-    }
-    tokens.push({ type: "identifier", value: identifier[0] });
-    index += identifier[0].length;
-  }
-
-  return tokens;
-}
-
-function parseKeybindingWhenExpression(expression: string): KeybindingWhenNode | null {
-  const tokens = tokenizeWhenExpression(expression);
-  if (!tokens || tokens.length === 0) return null;
-  let index = 0;
-
-  const parsePrimary = (depth: number): KeybindingWhenNode | null => {
-    if (depth > MAX_WHEN_EXPRESSION_DEPTH) {
-      return null;
-    }
-    const token = tokens[index];
-    if (!token) return null;
-
-    if (token.type === "identifier") {
-      index += 1;
-      return { type: "identifier", name: token.value };
-    }
-
-    if (token.type === "lparen") {
-      index += 1;
-      const expressionNode = parseOr(depth + 1);
-      const closeToken = tokens[index];
-      if (!expressionNode || !closeToken || closeToken.type !== "rparen") {
-        return null;
-      }
-      index += 1;
-      return expressionNode;
-    }
-
-    return null;
-  };
-
-  const parseUnary = (depth: number): KeybindingWhenNode | null => {
-    let notCount = 0;
-    while (tokens[index]?.type === "not") {
-      index += 1;
-      notCount += 1;
-      if (notCount > MAX_WHEN_EXPRESSION_DEPTH) {
-        return null;
-      }
-    }
-
-    let node = parsePrimary(depth);
-    if (!node) return null;
-
-    while (notCount > 0) {
-      node = { type: "not", node };
-      notCount -= 1;
-    }
-
-    return node;
-  };
-
-  const parseAnd = (depth: number): KeybindingWhenNode | null => {
-    let left = parseUnary(depth);
-    if (!left) return null;
-
-    while (tokens[index]?.type === "and") {
-      index += 1;
-      const right = parseUnary(depth);
-      if (!right) return null;
-      left = { type: "and", left, right };
-    }
-
-    return left;
-  };
-
-  const parseOr = (depth: number): KeybindingWhenNode | null => {
-    let left = parseAnd(depth);
-    if (!left) return null;
-
-    while (tokens[index]?.type === "or") {
-      index += 1;
-      const right = parseAnd(depth);
-      if (!right) return null;
-      left = { type: "or", left, right };
-    }
-
-    return left;
-  };
-
-  const ast = parseOr(0);
-  if (!ast || index !== tokens.length) return null;
-  return ast;
-}
-
-/** @internal - Exported for testing */
-export function compileResolvedKeybindingRule(rule: KeybindingRule): ResolvedKeybindingRule | null {
-  const shortcut = parseKeybindingShortcut(rule.key);
-  if (!shortcut) return null;
-
-  if (rule.when !== undefined) {
-    const whenAst = parseKeybindingWhenExpression(rule.when);
-    if (!whenAst) return null;
-    return {
-      command: rule.command,
-      shortcut,
-      whenAst,
-    };
-  }
-
-  return {
-    command: rule.command,
-    shortcut,
-  };
-}
-
-export function compileResolvedKeybindingsConfig(
-  config: KeybindingsConfig,
-): ResolvedKeybindingsConfig {
-  const compiled: Mutable<ResolvedKeybindingsConfig> = [];
-  for (const rule of config) {
-    const result = Schema.decodeExit(ResolvedKeybindingFromConfig)(rule);
-    if (result._tag === "Success") {
-      compiled.push(result.value);
-    }
-  }
-  return compiled;
-}
+import { ServerConfig } from "./config.ts";
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { fromJsonStringPretty, fromLenientJson } from "@t3tools/shared/schemaJson";
+import {
+  DEFAULT_KEYBINDINGS,
+  DEFAULT_RESOLVED_KEYBINDINGS,
+  compileResolvedKeybindingRule,
+  compileResolvedKeybindingsConfig,
+  parseKeybindingShortcut,
+} from "@t3tools/shared/keybindings";
+
+export {
+  DEFAULT_KEYBINDINGS,
+  compileResolvedKeybindingRule,
+  compileResolvedKeybindingsConfig,
+  parseKeybindingShortcut,
+};
 
 export const ResolvedKeybindingFromConfig = KeybindingRule.pipe(
   Schema.decodeTo(
@@ -378,6 +123,25 @@ function hasSameShortcutContext(left: KeybindingRule, right: KeybindingRule): bo
   return leftContext === rightContext;
 }
 
+function keybindingRuleFromUpsertInput(input: ServerUpsertKeybindingInput): KeybindingRule {
+  return input.when === undefined
+    ? { key: input.key, command: input.command }
+    : { key: input.key, command: input.command, when: input.when };
+}
+
+function replaceTargetFromUpsertInput(input: ServerUpsertKeybindingInput): KeybindingRule | null {
+  if (!input.replace) return null;
+  return input.replace.when === undefined
+    ? { key: input.replace.key, command: input.replace.command }
+    : { key: input.replace.key, command: input.replace.command, when: input.replace.when };
+}
+
+function keybindingRuleFromRemoveInput(input: ServerRemoveKeybindingInput): KeybindingRule {
+  return input.when === undefined
+    ? { key: input.key, command: input.command }
+    : { key: input.key, command: input.command, when: input.when };
+}
+
 function encodeShortcut(shortcut: KeybindingShortcut): string | null {
   const modifiers: string[] = [];
   if (shortcut.modKey) modifiers.push("mod");
@@ -404,19 +168,12 @@ function encodeWhenAst(node: KeybindingWhenNode): string {
   }
 }
 
-const DEFAULT_RESOLVED_KEYBINDINGS = compileResolvedKeybindingsConfig(DEFAULT_KEYBINDINGS);
-
 const RawKeybindingsEntries = fromLenientJson(Schema.Array(Schema.Unknown));
-const KeybindingsConfigJson = Schema.fromJsonString(KeybindingsConfig);
-const PrettyJsonString = SchemaGetter.parseJson<string>().compose(
-  SchemaGetter.stringifyJson({ space: 2 }),
-);
-const KeybindingsConfigPrettyJson = KeybindingsConfigJson.pipe(
-  Schema.encode({
-    decode: PrettyJsonString,
-    encode: PrettyJsonString,
-  }),
-);
+const KeybindingsConfigPrettyJson = fromJsonStringPretty(KeybindingsConfig);
+const decodeKeybindingRuleExit = Schema.decodeUnknownExit(KeybindingRule);
+const decodeResolvedKeybindingFromConfigExit = Schema.decodeExit(ResolvedKeybindingFromConfig);
+const decodeRawKeybindingsEntriesExit = Schema.decodeUnknownExit(RawKeybindingsEntries);
+const encodeKeybindingsConfigPrettyJson = Schema.encodeEffect(KeybindingsConfigPrettyJson);
 
 export interface KeybindingsConfigState {
   readonly keybindings: ResolvedKeybindingsConfig;
@@ -515,7 +272,14 @@ export interface KeybindingsShape {
    * oldest entries when needed.
    */
   readonly upsertKeybindingRule: (
-    rule: KeybindingRule,
+    input: ServerUpsertKeybindingInput,
+  ) => Effect.Effect<ResolvedKeybindingsConfig, KeybindingsConfigError>;
+
+  /**
+   * Remove a single persisted keybinding rule by exact key/command/when match.
+   */
+  readonly removeKeybindingRule: (
+    input: ServerRemoveKeybindingInput,
   ) => Effect.Effect<ResolvedKeybindingsConfig, KeybindingsConfigError>;
 }
 
@@ -584,7 +348,7 @@ const makeKeybindings = Effect.gen(function* () {
 
     return yield* Effect.forEach(rawConfig, (entry) =>
       Effect.gen(function* () {
-        const decodedRule = Schema.decodeUnknownExit(KeybindingRule)(entry);
+        const decodedRule = decodeKeybindingRuleExit(entry);
         if (decodedRule._tag === "Failure") {
           yield* Effect.logWarning("ignoring invalid keybinding entry", {
             path: keybindingsConfigPath,
@@ -593,7 +357,7 @@ const makeKeybindings = Effect.gen(function* () {
           });
           return null;
         }
-        const resolved = Schema.decodeExit(ResolvedKeybindingFromConfig)(decodedRule.value);
+        const resolved = decodeResolvedKeybindingFromConfigExit(decodedRule.value);
         if (resolved._tag === "Failure") {
           yield* Effect.logWarning("ignoring invalid keybinding entry", {
             path: keybindingsConfigPath,
@@ -619,7 +383,7 @@ const makeKeybindings = Effect.gen(function* () {
     }
 
     const rawConfig = yield* readRawConfig;
-    const decodedEntries = Schema.decodeUnknownExit(RawKeybindingsEntries)(rawConfig);
+    const decodedEntries = decodeRawKeybindingsEntriesExit(rawConfig);
     if (decodedEntries._tag === "Failure") {
       const detail = `expected JSON array (${Cause.pretty(decodedEntries.cause)})`;
       return {
@@ -631,7 +395,7 @@ const makeKeybindings = Effect.gen(function* () {
     const keybindings: KeybindingRule[] = [];
     const issues: ServerConfigIssue[] = [];
     for (const [index, entry] of decodedEntries.value.entries()) {
-      const decodedRule = Schema.decodeUnknownExit(KeybindingRule)(entry);
+      const decodedRule = decodeKeybindingRuleExit(entry);
       if (decodedRule._tag === "Failure") {
         const detail = Cause.pretty(decodedRule.cause);
         issues.push(invalidEntryIssue(index, detail));
@@ -644,7 +408,7 @@ const makeKeybindings = Effect.gen(function* () {
         continue;
       }
 
-      const resolvedRule = Schema.decodeExit(ResolvedKeybindingFromConfig)(decodedRule.value);
+      const resolvedRule = decodeResolvedKeybindingFromConfigExit(decodedRule.value);
       if (resolvedRule._tag === "Failure") {
         const detail = Cause.pretty(resolvedRule.cause);
         issues.push(invalidEntryIssue(index, detail));
@@ -663,14 +427,17 @@ const makeKeybindings = Effect.gen(function* () {
   });
 
   const writeConfigAtomically = (rules: readonly KeybindingRule[]) => {
-    const tempPath = `${keybindingsConfigPath}.${process.pid}.${Date.now()}.tmp`;
-
-    return Schema.encodeEffect(KeybindingsConfigPrettyJson)(rules).pipe(
+    return encodeKeybindingsConfigPrettyJson(rules).pipe(
       Effect.map((encoded) => `${encoded}\n`),
-      Effect.tap(() => fs.makeDirectory(path.dirname(keybindingsConfigPath), { recursive: true })),
-      Effect.tap((encoded) => fs.writeFileString(tempPath, encoded)),
-      Effect.flatMap(() => fs.rename(tempPath, keybindingsConfigPath)),
-      Effect.ensuring(fs.remove(tempPath, { force: true }).pipe(Effect.ignore({ log: true }))),
+      Effect.flatMap((encoded) =>
+        writeFileStringAtomically({
+          filePath: keybindingsConfigPath,
+          contents: encoded,
+        }).pipe(
+          Effect.provideService(FileSystem.FileSystem, fs),
+          Effect.provideService(Path.Path, path),
+        ),
+      ),
       Effect.mapError(
         (cause) =>
           new KeybindingsConfigError({
@@ -869,12 +636,19 @@ const makeKeybindings = Effect.gen(function* () {
     get streamChanges() {
       return Stream.fromPubSub(changesPubSub);
     },
-    upsertKeybindingRule: (rule) =>
+    upsertKeybindingRule: (input) =>
       upsertSemaphore.withPermits(1)(
         Effect.gen(function* () {
           const customConfig = yield* loadWritableCustomKeybindingsConfig();
+          const rule = keybindingRuleFromUpsertInput(input);
+          const replaceTarget = replaceTargetFromUpsertInput(input);
           const nextConfig = [
-            ...customConfig.filter((entry) => entry.command !== rule.command),
+            ...customConfig.filter((entry) => {
+              if (replaceTarget) {
+                return !isSameKeybindingRule(entry, replaceTarget);
+              }
+              return !isSameKeybindingRule(entry, rule);
+            }),
             rule,
           ];
           const cappedConfig =
@@ -902,6 +676,27 @@ const makeKeybindings = Effect.gen(function* () {
           return nextResolved;
         }),
       ),
+    removeKeybindingRule: (input) =>
+      upsertSemaphore.withPermits(1)(
+        Effect.gen(function* () {
+          const customConfig = yield* loadWritableCustomKeybindingsConfig();
+          const target = keybindingRuleFromRemoveInput(input);
+          const nextConfig = customConfig.filter((entry) => !isSameKeybindingRule(entry, target));
+          yield* writeConfigAtomically(nextConfig);
+          const nextResolved = mergeWithDefaultKeybindings(
+            compileResolvedKeybindingsConfig(nextConfig),
+          );
+          yield* Cache.set(resolvedConfigCache, resolvedConfigCacheKey, {
+            keybindings: nextResolved,
+            issues: [],
+          });
+          yield* emitChange({
+            keybindings: nextResolved,
+            issues: [],
+          });
+          return nextResolved;
+        }),
+      ),
   } satisfies KeybindingsShape;
 });
 
diff --git a/apps/server/src/observability/Attributes.test.ts b/apps/server/src/observability/Attributes.test.ts
index 4b495598ea3..d9ed2e1271f 100644
--- a/apps/server/src/observability/Attributes.test.ts
+++ b/apps/server/src/observability/Attributes.test.ts
@@ -1,43 +1,8 @@
 import { assert, describe, it } from "@effect/vitest";
 
-import { compactTraceAttributes, normalizeModelMetricLabel } from "./Attributes.ts";
+import { normalizeModelMetricLabel } from "./Attributes.ts";
 
 describe("Attributes", () => {
-  it("normalizes circular arrays, maps, and sets without recursing forever", () => {
-    const array: Array<unknown> = ["alpha"];
-    array.push(array);
-
-    const map = new Map<string, unknown>();
-    map.set("self", map);
-
-    const set = new Set<unknown>();
-    set.add(set);
-
-    assert.deepStrictEqual(
-      compactTraceAttributes({
-        array,
-        map,
-        set,
-      }),
-      {
-        array: ["alpha", "[Circular]"],
-        map: { self: "[Circular]" },
-        set: ["[Circular]"],
-      },
-    );
-  });
-
-  it("normalizes invalid dates without throwing", () => {
-    assert.deepStrictEqual(
-      compactTraceAttributes({
-        invalidDate: new Date("not-a-real-date"),
-      }),
-      {
-        invalidDate: "Invalid Date",
-      },
-    );
-  });
-
   it("groups GPT-family models under a shared metric label", () => {
     assert.strictEqual(normalizeModelMetricLabel("gpt-4o"), "gpt");
     assert.strictEqual(normalizeModelMetricLabel("gpt-5.4"), "gpt");
diff --git a/apps/server/src/observability/Attributes.ts b/apps/server/src/observability/Attributes.ts
index 2251fcfea69..168fad18897 100644
--- a/apps/server/src/observability/Attributes.ts
+++ b/apps/server/src/observability/Attributes.ts
@@ -1,89 +1,10 @@
-import { Cause, Exit } from "effect";
+import * as Cause from "effect/Cause";
+import * as Exit from "effect/Exit";
 
 export type MetricAttributeValue = string;
 export type MetricAttributes = Readonly<Record<string, MetricAttributeValue>>;
-export type TraceAttributes = Readonly<Record<string, unknown>>;
 export type ObservabilityOutcome = "success" | "failure" | "interrupt";
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function markSeen(value: object, seen: WeakSet<object>): boolean {
-  if (seen.has(value)) {
-    return true;
-  }
-  seen.add(value);
-  return false;
-}
-
-function normalizeJsonValue(value: unknown, seen: WeakSet<object> = new WeakSet()): unknown {
-  if (
-    value === null ||
-    value === undefined ||
-    typeof value === "string" ||
-    typeof value === "number" ||
-    typeof value === "boolean"
-  ) {
-    return value ?? null;
-  }
-  if (typeof value === "bigint") {
-    return value.toString();
-  }
-  if (value instanceof Date) {
-    return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
-  }
-  if (value instanceof Error) {
-    return {
-      name: value.name,
-      message: value.message,
-      ...(value.stack ? { stack: value.stack } : {}),
-    };
-  }
-  if (Array.isArray(value)) {
-    if (markSeen(value, seen)) {
-      return "[Circular]";
-    }
-    return value.map((entry) => normalizeJsonValue(entry, seen));
-  }
-  if (value instanceof Map) {
-    if (markSeen(value, seen)) {
-      return "[Circular]";
-    }
-    return Object.fromEntries(
-      Array.from(value.entries(), ([key, entryValue]) => [
-        String(key),
-        normalizeJsonValue(entryValue, seen),
-      ]),
-    );
-  }
-  if (value instanceof Set) {
-    if (markSeen(value, seen)) {
-      return "[Circular]";
-    }
-    return Array.from(value.values(), (entry) => normalizeJsonValue(entry, seen));
-  }
-  if (!isPlainObject(value)) {
-    return String(value);
-  }
-  if (markSeen(value, seen)) {
-    return "[Circular]";
-  }
-  return Object.fromEntries(
-    Object.entries(value).map(([key, entryValue]) => [key, normalizeJsonValue(entryValue, seen)]),
-  );
-}
-
-export function compactTraceAttributes(
-  attributes: Readonly<Record<string, unknown>>,
-): TraceAttributes {
-  return Object.fromEntries(
-    Object.entries(attributes)
-      .filter(([, value]) => value !== undefined)
-      .map(([key, value]) => [key, normalizeJsonValue(value)]),
-  );
-}
-
 export function compactMetricAttributes(
   attributes: Readonly<Record<string, unknown>>,
 ): MetricAttributes {
diff --git a/apps/server/src/observability/Layers/Observability.ts b/apps/server/src/observability/Layers/Observability.ts
index 7c6a28005f4..94368a45296 100644
--- a/apps/server/src/observability/Layers/Observability.ts
+++ b/apps/server/src/observability/Layers/Observability.ts
@@ -1,11 +1,13 @@
-import { Effect, Layer, References, Tracer } from "effect";
+import { makeLocalFileTracer, makeTraceSink } from "@t3tools/shared/observability";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as References from "effect/References";
+import * as Tracer from "effect/Tracer";
 import { OtlpMetrics, OtlpSerialization, OtlpTracer } from "effect/unstable/observability";
 
 import { ServerConfig } from "../../config.ts";
 import { ServerLoggerLive } from "../../serverLogger.ts";
-import { makeLocalFileTracer } from "../LocalFileTracer.ts";
 import { BrowserTraceCollector } from "../Services/BrowserTraceCollector.ts";
-import { makeTraceSink } from "../TraceSink.ts";
 
 const otlpSerializationLayer = OtlpSerialization.layerJson;
 
diff --git a/apps/server/src/observability/LocalFileTracer.test.ts b/apps/server/src/observability/LocalFileTracer.test.ts
deleted file mode 100644
index 19efffaf10b..00000000000
--- a/apps/server/src/observability/LocalFileTracer.test.ts
+++ /dev/null
@@ -1,117 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-import { assert, describe, it } from "@effect/vitest";
-import { Effect, Layer, Logger, References, Tracer } from "effect";
-
-import type { EffectTraceRecord } from "./TraceRecord.ts";
-import { makeLocalFileTracer } from "./LocalFileTracer.ts";
-
-const makeTestLayer = (tracePath: string) =>
-  Layer.mergeAll(
-    Layer.effect(
-      Tracer.Tracer,
-      makeLocalFileTracer({
-        filePath: tracePath,
-        maxBytes: 1024 * 1024,
-        maxFiles: 2,
-        batchWindowMs: 10_000,
-      }),
-    ),
-    Logger.layer([Logger.tracerLogger], { mergeWithExisting: false }),
-    Layer.succeed(References.MinimumLogLevel, "Info"),
-  );
-
-const readTraceRecords = (tracePath: string): Array<EffectTraceRecord> =>
-  fs
-    .readFileSync(tracePath, "utf8")
-    .trim()
-    .split("\n")
-    .filter((line) => line.length > 0)
-    .map((line) => JSON.parse(line) as EffectTraceRecord);
-
-describe("LocalFileTracer", () => {
-  it.effect("writes nested spans to disk and captures log messages as span events", () =>
-    Effect.gen(function* () {
-      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-local-tracer-"));
-      const tracePath = path.join(tempDir, "server.trace.ndjson");
-
-      try {
-        yield* Effect.scoped(
-          Effect.gen(function* () {
-            const program = Effect.gen(function* () {
-              yield* Effect.annotateCurrentSpan({
-                "demo.parent": true,
-              });
-              yield* Effect.logInfo("parent event");
-              yield* Effect.gen(function* () {
-                yield* Effect.annotateCurrentSpan({
-                  "demo.child": true,
-                });
-                yield* Effect.logInfo("child event");
-              }).pipe(Effect.withSpan("child-span"));
-            }).pipe(Effect.withSpan("parent-span"));
-
-            yield* program.pipe(Effect.provide(makeTestLayer(tracePath)));
-          }),
-        );
-
-        const records = readTraceRecords(tracePath);
-        assert.equal(records.length, 2);
-
-        const parent = records.find((record) => record.name === "parent-span");
-        const child = records.find((record) => record.name === "child-span");
-
-        assert.notEqual(parent, undefined);
-        assert.notEqual(child, undefined);
-        if (!parent || !child) {
-          return;
-        }
-
-        assert.equal(child.parentSpanId, parent.spanId);
-        assert.equal(parent.attributes["demo.parent"], true);
-        assert.equal(child.attributes["demo.child"], true);
-        assert.equal(
-          parent.events.some((event) => event.name === "parent event"),
-          true,
-        );
-        assert.equal(
-          child.events.some((event) => event.name === "child event"),
-          true,
-        );
-        assert.equal(
-          child.events.some((event) => event.attributes["effect.logLevel"] === "INFO"),
-          true,
-        );
-      } finally {
-        fs.rmSync(tempDir, { recursive: true, force: true });
-      }
-    }),
-  );
-
-  it.effect("serializes interrupted spans with an interrupted exit status", () =>
-    Effect.gen(function* () {
-      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-local-tracer-"));
-      const tracePath = path.join(tempDir, "server.trace.ndjson");
-
-      try {
-        yield* Effect.scoped(
-          Effect.exit(
-            Effect.interrupt.pipe(
-              Effect.withSpan("interrupt-span"),
-              Effect.provide(makeTestLayer(tracePath)),
-            ),
-          ),
-        );
-
-        const records = readTraceRecords(tracePath);
-        assert.equal(records.length, 1);
-        assert.equal(records[0]?.name, "interrupt-span");
-        assert.equal(records[0]?.exit._tag, "Interrupted");
-      } finally {
-        fs.rmSync(tempDir, { recursive: true, force: true });
-      }
-    }),
-  );
-});
diff --git a/apps/server/src/observability/LocalFileTracer.ts b/apps/server/src/observability/LocalFileTracer.ts
deleted file mode 100644
index cde5a176e88..00000000000
--- a/apps/server/src/observability/LocalFileTracer.ts
+++ /dev/null
@@ -1,107 +0,0 @@
-import type * as Exit from "effect/Exit";
-import { Effect, Option, Tracer } from "effect";
-
-import { EffectTraceRecord, spanToTraceRecord } from "./TraceRecord.ts";
-import { makeTraceSink, type TraceSink } from "./TraceSink.ts";
-
-export interface LocalFileTracerOptions {
-  readonly filePath: string;
-  readonly maxBytes: number;
-  readonly maxFiles: number;
-  readonly batchWindowMs: number;
-  readonly delegate?: Tracer.Tracer;
-  readonly sink?: TraceSink;
-}
-
-class LocalFileSpan implements Tracer.Span {
-  readonly _tag = "Span";
-  readonly name: string;
-  readonly spanId: string;
-  readonly traceId: string;
-  readonly parent: Option.Option<Tracer.AnySpan>;
-  readonly annotations: Tracer.Span["annotations"];
-  readonly links: Array<Tracer.SpanLink>;
-  readonly sampled: boolean;
-  readonly kind: Tracer.SpanKind;
-
-  status: Tracer.SpanStatus;
-  attributes: Map<string, unknown>;
-  events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]>;
-
-  constructor(
-    options: Parameters<Tracer.Tracer["span"]>[0],
-    private readonly delegate: Tracer.Span,
-    private readonly push: (record: EffectTraceRecord) => void,
-  ) {
-    this.name = delegate.name;
-    this.spanId = delegate.spanId;
-    this.traceId = delegate.traceId;
-    this.parent = options.parent;
-    this.annotations = options.annotations;
-    this.links = [...options.links];
-    this.sampled = delegate.sampled;
-    this.kind = delegate.kind;
-    this.status = {
-      _tag: "Started",
-      startTime: options.startTime,
-    };
-    this.attributes = new Map();
-    this.events = [];
-  }
-
-  end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
-    this.status = {
-      _tag: "Ended",
-      startTime: this.status.startTime,
-      endTime,
-      exit,
-    };
-    this.delegate.end(endTime, exit);
-
-    if (this.sampled) {
-      this.push(spanToTraceRecord(this));
-    }
-  }
-
-  attribute(key: string, value: unknown): void {
-    this.attributes.set(key, value);
-    this.delegate.attribute(key, value);
-  }
-
-  event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void {
-    const nextAttributes = attributes ?? {};
-    this.events.push([name, startTime, nextAttributes]);
-    this.delegate.event(name, startTime, nextAttributes);
-  }
-
-  addLinks(links: ReadonlyArray<Tracer.SpanLink>): void {
-    this.links.push(...links);
-    this.delegate.addLinks(links);
-  }
-}
-
-export const makeLocalFileTracer = Effect.fn("makeLocalFileTracer")(function* (
-  options: LocalFileTracerOptions,
-) {
-  const sink =
-    options.sink ??
-    (yield* makeTraceSink({
-      filePath: options.filePath,
-      maxBytes: options.maxBytes,
-      maxFiles: options.maxFiles,
-      batchWindowMs: options.batchWindowMs,
-    }));
-
-  const delegate =
-    options.delegate ??
-    Tracer.make({
-      span: (spanOptions) => new Tracer.NativeSpan(spanOptions),
-    });
-
-  return Tracer.make({
-    span(spanOptions) {
-      return new LocalFileSpan(spanOptions, delegate.span(spanOptions), sink.push);
-    },
-    ...(delegate.context ? { context: delegate.context } : {}),
-  });
-});
diff --git a/apps/server/src/observability/Metrics.test.ts b/apps/server/src/observability/Metrics.test.ts
index 4604f43b63a..3fe6b9a8cd8 100644
--- a/apps/server/src/observability/Metrics.test.ts
+++ b/apps/server/src/observability/Metrics.test.ts
@@ -1,5 +1,10 @@
 import { assert, describe, it } from "@effect/vitest";
-import { Effect, Metric } from "effect";
+import { ProviderDriverKind } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Metric from "effect/Metric";
+import * as TestClock from "effect/testing/TestClock";
 
 import { withMetrics } from "./Metrics.ts";
 
@@ -14,6 +19,18 @@ const hasMetricSnapshot = (
       Object.entries(attributes).every(([key, value]) => snapshot.attributes?.[key] === value),
   );
 
+const findHistogramSnapshot = (
+  snapshots: ReadonlyArray<Metric.Metric.Snapshot>,
+  id: string,
+  attributes: Readonly<Record<string, string>>,
+) =>
+  snapshots.find(
+    (snapshot): snapshot is Extract<Metric.Metric.Snapshot, { readonly type: "Histogram" }> =>
+      snapshot.type === "Histogram" &&
+      snapshot.id === id &&
+      Object.entries(attributes).every(([key, value]) => snapshot.attributes?.[key] === value),
+  );
+
 describe("withMetrics", () => {
   it.effect("supports pipe-style usage", () =>
     Effect.gen(function* () {
@@ -75,10 +92,11 @@ describe("withMetrics", () => {
     Effect.gen(function* () {
       const counter = Metric.counter("with_metrics_lazy_total");
       const timer = Metric.timer("with_metrics_lazy_duration");
-      let provider = "unknown";
+      let provider = ProviderDriverKind.make("unknown");
+      const lazyInittedProvider = ProviderDriverKind.make("codex");
 
       yield* Effect.sync(() => {
-        provider = "codex";
+        provider = lazyInittedProvider;
       }).pipe(
         withMetrics({
           counter,
@@ -93,7 +111,7 @@ describe("withMetrics", () => {
       const snapshots = yield* Metric.snapshot;
       assert.equal(
         hasMetricSnapshot(snapshots, "with_metrics_lazy_total", {
-          provider: "codex",
+          provider: lazyInittedProvider,
           operation: "lazy",
           outcome: "success",
         }),
@@ -101,11 +119,42 @@ describe("withMetrics", () => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "with_metrics_lazy_duration", {
-          provider: "codex",
+          provider: lazyInittedProvider,
           operation: "lazy",
         }),
         true,
       );
     }),
   );
+
+  it.effect("records timer durations from nanosecond clock readings", () =>
+    Effect.gen(function* () {
+      const duration = Duration.nanos(1_500_000n);
+      const timer = Metric.timer("with_metrics_nanos_duration");
+
+      yield* Effect.gen(function* () {
+        const fiber = yield* Effect.sleep(duration).pipe(
+          withMetrics({
+            timer,
+            attributes: {
+              operation: "nanos",
+            },
+          }),
+          Effect.forkChild,
+        );
+
+        yield* Effect.yieldNow;
+        yield* TestClock.adjust(duration);
+        yield* Fiber.join(fiber);
+      }).pipe(Effect.provide(TestClock.layer()));
+
+      const snapshots = yield* Metric.snapshot;
+      const snapshot = findHistogramSnapshot(snapshots, "with_metrics_nanos_duration", {
+        operation: "nanos",
+      });
+
+      assert.equal(snapshot?.state.count, 1);
+      assert.equal(snapshot?.state.sum, 1.5);
+    }),
+  );
 });
diff --git a/apps/server/src/observability/Metrics.ts b/apps/server/src/observability/Metrics.ts
index 3e527c7cb45..886833d6e2c 100644
--- a/apps/server/src/observability/Metrics.ts
+++ b/apps/server/src/observability/Metrics.ts
@@ -1,4 +1,8 @@
-import { Duration, Effect, Exit, Metric } from "effect";
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Metric from "effect/Metric";
 import { dual } from "effect/Function";
 
 import {
@@ -96,9 +100,11 @@ const withMetricsImpl = <A, E, R>(
   options: WithMetricsOptions,
 ): Effect.Effect<A, E, R> =>
   Effect.gen(function* () {
-    const startedAt = Date.now();
+    const startedAt = yield* Clock.currentTimeNanos;
     const exit = yield* Effect.exit(effect);
-    const duration = Duration.millis(Math.max(0, Date.now() - startedAt));
+    const endedAt = yield* Clock.currentTimeNanos;
+    const elapsedNanos = endedAt > startedAt ? endedAt - startedAt : 0n;
+    const duration = Duration.nanos(elapsedNanos);
     const baseAttributes =
       typeof options.attributes === "function" ? options.attributes() : (options.attributes ?? {});
 
diff --git a/apps/server/src/observability/RpcInstrumentation.test.ts b/apps/server/src/observability/RpcInstrumentation.test.ts
index d29b05f3c2b..c7fb7d12b09 100644
--- a/apps/server/src/observability/RpcInstrumentation.test.ts
+++ b/apps/server/src/observability/RpcInstrumentation.test.ts
@@ -1,5 +1,13 @@
 import { assert, describe, it } from "@effect/vitest";
-import { Effect, Exit, Metric, Stream } from "effect";
+import { WS_METHODS } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Metric from "effect/Metric";
+import * as Stream from "effect/Stream";
+import * as Tracer from "effect/Tracer";
+import * as TestClock from "effect/testing/TestClock";
 
 import {
   observeRpcEffect,
@@ -18,6 +26,44 @@ const hasMetricSnapshot = (
       Object.entries(attributes).every(([key, value]) => snapshot.attributes?.[key] === value),
   );
 
+const findHistogramSnapshot = (
+  snapshots: ReadonlyArray<Metric.Metric.Snapshot>,
+  id: string,
+  attributes: Readonly<Record<string, string>>,
+) =>
+  snapshots.find(
+    (snapshot): snapshot is Extract<Metric.Metric.Snapshot, { readonly type: "Histogram" }> =>
+      snapshot.type === "Histogram" &&
+      snapshot.id === id &&
+      Object.entries(attributes).every(([key, value]) => snapshot.attributes?.[key] === value),
+  );
+
+const collectSpanNames = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<ReadonlyArray<string>, E, R> =>
+  Effect.gen(function* () {
+    const spanNames: Array<string> = [];
+    const tracer = Tracer.make({
+      span: (options) => {
+        const span = new Tracer.NativeSpan(options);
+        const end = span.end.bind(span);
+
+        span.end = (endTime, exit) => {
+          end(endTime, exit);
+          if (span.sampled) {
+            spanNames.push(span.name);
+          }
+        };
+
+        return span;
+      },
+    });
+
+    yield* effect.pipe(Effect.withTracer(tracer));
+
+    return spanNames;
+  });
+
 describe("RpcInstrumentation", () => {
   it.effect("records success metrics for unary RPC handlers", () =>
     Effect.gen(function* () {
@@ -129,6 +175,37 @@ describe("RpcInstrumentation", () => {
     }),
   );
 
+  it.effect("records direct stream durations from nanosecond clock readings", () =>
+    Effect.gen(function* () {
+      const duration = Duration.nanos(1_500_000n);
+      const events = yield* Effect.gen(function* () {
+        const fiber = yield* Stream.runCollect(
+          observeRpcStream(
+            WS_METHODS.serverGetProcessDiagnostics,
+            Stream.fromEffect(Effect.sleep(duration).pipe(Effect.as("ok"))),
+            {
+              "rpc.aggregate": "test",
+            },
+          ),
+        ).pipe(Effect.forkChild);
+
+        yield* Effect.yieldNow;
+        yield* TestClock.adjust(duration);
+        return yield* Fiber.join(fiber);
+      }).pipe(Effect.provide(TestClock.layer()));
+
+      assert.deepStrictEqual(Array.from(events), ["ok"]);
+
+      const snapshots = yield* Metric.snapshot;
+      const snapshot = findHistogramSnapshot(snapshots, "t3_rpc_request_duration", {
+        method: WS_METHODS.serverGetProcessDiagnostics,
+      });
+
+      assert.equal(snapshot?.state.count, 1);
+      assert.equal(snapshot?.state.sum, 1.5);
+    }),
+  );
+
   it.effect("records failure outcomes when a stream RPC effect produces a failing stream", () =>
     Effect.gen(function* () {
       const exit = yield* Stream.runCollect(
@@ -158,4 +235,79 @@ describe("RpcInstrumentation", () => {
       );
     }),
   );
+
+  it.effect("records spans for traced stream RPC handlers", () =>
+    Effect.gen(function* () {
+      const spanNames = yield* collectSpanNames(
+        Stream.runCollect(
+          observeRpcStream(
+            "rpc.instrumentation.traced.stream",
+            Stream.fromEffect(
+              Effect.succeed("ok").pipe(Effect.withSpan("rpc.instrumentation.traced.stream.child")),
+            ),
+            { "rpc.aggregate": "test" },
+          ),
+        ),
+      );
+
+      assert.equal(spanNames.includes("ws.rpc.rpc.instrumentation.traced.stream"), true);
+      assert.equal(spanNames.includes("rpc.instrumentation.traced.stream.child"), true);
+    }),
+  );
+
+  it.effect("does not create spans for disabled unary RPC handlers", () =>
+    Effect.gen(function* () {
+      const spanNames = yield* collectSpanNames(
+        observeRpcEffect(
+          WS_METHODS.serverGetTraceDiagnostics,
+          Effect.succeed("ok").pipe(Effect.withSpan("rpc.instrumentation.disabled.unary.child")),
+          { "rpc.aggregate": "test" },
+        ),
+      );
+
+      assert.deepStrictEqual(spanNames, []);
+    }),
+  );
+
+  it.effect("does not create spans for disabled direct stream RPC handlers", () =>
+    Effect.gen(function* () {
+      const spanNames = yield* collectSpanNames(
+        Stream.runCollect(
+          observeRpcStream(
+            WS_METHODS.serverGetTraceDiagnostics,
+            Stream.fromEffect(
+              Effect.succeed("ok").pipe(
+                Effect.withSpan("rpc.instrumentation.disabled.stream.child"),
+              ),
+            ),
+            { "rpc.aggregate": "test" },
+          ),
+        ),
+      );
+
+      assert.deepStrictEqual(spanNames, []);
+    }),
+  );
+
+  it.effect("does not create spans for disabled stream effect RPC handlers", () =>
+    Effect.gen(function* () {
+      const spanNames = yield* collectSpanNames(
+        Stream.runCollect(
+          observeRpcStreamEffect(
+            WS_METHODS.serverGetTraceDiagnostics,
+            Effect.succeed(
+              Stream.fromEffect(
+                Effect.succeed("ok").pipe(
+                  Effect.withSpan("rpc.instrumentation.disabled.stream.effect.consume"),
+                ),
+              ),
+            ).pipe(Effect.withSpan("rpc.instrumentation.disabled.stream.effect.create")),
+            { "rpc.aggregate": "test" },
+          ),
+        ),
+      );
+
+      assert.deepStrictEqual(spanNames, []);
+    }),
+  );
 });
diff --git a/apps/server/src/observability/RpcInstrumentation.ts b/apps/server/src/observability/RpcInstrumentation.ts
index a3ac29aa02d..edbd705b3ee 100644
--- a/apps/server/src/observability/RpcInstrumentation.ts
+++ b/apps/server/src/observability/RpcInstrumentation.ts
@@ -1,26 +1,78 @@
-import { Duration, Effect, Exit, Metric, Stream } from "effect";
+import { WS_METHODS } from "@t3tools/contracts";
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Metric from "effect/Metric";
+import * as References from "effect/References";
+import * as Stream from "effect/Stream";
 
 import { outcomeFromExit } from "./Attributes.ts";
 import { metricAttributes, rpcRequestDuration, rpcRequestsTotal, withMetrics } from "./Metrics.ts";
 
-const annotateRpcSpan = (
+const RPC_SPAN_PREFIX = "ws.rpc";
+const DEFAULT_RPC_SPAN_ATTRIBUTES = {
+  "rpc.transport": "websocket",
+  "rpc.system": "effect-rpc",
+} as const;
+const RPC_METHODS_WITH_TRACING_DISABLED: ReadonlySet<string> = new Set([
+  WS_METHODS.serverGetTraceDiagnostics,
+  WS_METHODS.serverGetProcessDiagnostics,
+  WS_METHODS.serverGetProcessResourceHistory,
+  WS_METHODS.serverSignalProcess,
+]);
+
+function shouldTraceRpc(method: string): boolean {
+  return !RPC_METHODS_WITH_TRACING_DISABLED.has(method);
+}
+
+const rpcSpanAttributes = (
   method: string,
   traceAttributes?: Readonly<Record<string, unknown>>,
-): Effect.Effect<void, never, never> =>
-  Effect.annotateCurrentSpan({
-    "rpc.method": method,
-    ...traceAttributes,
-  });
+): Record<string, unknown> => ({
+  ...DEFAULT_RPC_SPAN_ATTRIBUTES,
+  "rpc.method": method,
+  ...traceAttributes,
+});
+
+const withRpcEffectTracing = <A, E, R>(
+  method: string,
+  effect: Effect.Effect<A, E, R>,
+  traceAttributes?: Readonly<Record<string, unknown>>,
+): Effect.Effect<A, E, R> =>
+  shouldTraceRpc(method)
+    ? effect.pipe(
+        Effect.withSpan(`${RPC_SPAN_PREFIX}.${method}`, {
+          attributes: rpcSpanAttributes(method, traceAttributes),
+        }),
+      )
+    : effect.pipe(Effect.provideService(References.TracerEnabled, false));
+
+const withRpcStreamTracing = <A, E, R>(
+  method: string,
+  stream: Stream.Stream<A, E, R>,
+  traceAttributes?: Readonly<Record<string, unknown>>,
+): Stream.Stream<A, E, R> =>
+  shouldTraceRpc(method)
+    ? stream.pipe(
+        Stream.withSpan(`${RPC_SPAN_PREFIX}.${method}`, {
+          attributes: rpcSpanAttributes(method, traceAttributes),
+        }),
+      )
+    : stream.pipe(Stream.provideService(References.TracerEnabled, false));
 
 const recordRpcStreamMetrics = <E>(
   method: string,
-  startedAt: number,
+  startedAt: bigint,
   exit: Exit.Exit<unknown, E>,
 ): Effect.Effect<void, never, never> =>
   Effect.gen(function* () {
+    const endedAt = yield* Clock.currentTimeNanos;
+    const elapsedNanos = endedAt > startedAt ? endedAt - startedAt : 0n;
+
     yield* Metric.update(
       Metric.withAttributes(rpcRequestDuration, metricAttributes({ method })),
-      Duration.millis(Math.max(0, Date.now() - startedAt)),
+      Duration.nanos(elapsedNanos),
     );
     yield* Metric.update(
       Metric.withAttributes(
@@ -38,43 +90,43 @@ export const observeRpcEffect = <A, E, R>(
   method: string,
   effect: Effect.Effect<A, E, R>,
   traceAttributes?: Readonly<Record<string, unknown>>,
-): Effect.Effect<A, E, R> =>
-  Effect.gen(function* () {
-    yield* annotateRpcSpan(method, traceAttributes);
+): Effect.Effect<A, E, R> => {
+  const instrumented = effect.pipe(
+    withMetrics({
+      counter: rpcRequestsTotal,
+      timer: rpcRequestDuration,
+      attributes: {
+        method,
+      },
+    }),
+  );
 
-    return yield* effect.pipe(
-      withMetrics({
-        counter: rpcRequestsTotal,
-        timer: rpcRequestDuration,
-        attributes: {
-          method,
-        },
-      }),
-    );
-  });
+  return withRpcEffectTracing(method, instrumented, traceAttributes);
+};
 
 export const observeRpcStream = <A, E, R>(
   method: string,
   stream: Stream.Stream<A, E, R>,
   traceAttributes?: Readonly<Record<string, unknown>>,
-): Stream.Stream<A, E, R> =>
-  Stream.unwrap(
+): Stream.Stream<A, E, R> => {
+  const instrumented = Stream.unwrap(
     Effect.gen(function* () {
-      yield* annotateRpcSpan(method, traceAttributes);
-      const startedAt = Date.now();
+      const startedAt = yield* Clock.currentTimeNanos;
       return stream.pipe(Stream.onExit((exit) => recordRpcStreamMetrics(method, startedAt, exit)));
     }),
   );
 
+  return withRpcStreamTracing(method, instrumented, traceAttributes);
+};
+
 export const observeRpcStreamEffect = <A, StreamError, StreamContext, EffectError, EffectContext>(
   method: string,
   effect: Effect.Effect<Stream.Stream<A, StreamError, StreamContext>, EffectError, EffectContext>,
   traceAttributes?: Readonly<Record<string, unknown>>,
-): Stream.Stream<A, StreamError | EffectError, StreamContext | EffectContext> =>
-  Stream.unwrap(
+): Stream.Stream<A, StreamError | EffectError, StreamContext | EffectContext> => {
+  const instrumented = Stream.unwrap(
     Effect.gen(function* () {
-      yield* annotateRpcSpan(method, traceAttributes);
-      const startedAt = Date.now();
+      const startedAt = yield* Clock.currentTimeNanos;
       const exit = yield* Effect.exit(effect);
 
       if (Exit.isFailure(exit)) {
@@ -87,3 +139,6 @@ export const observeRpcStreamEffect = <A, StreamError, StreamContext, EffectErro
       );
     }),
   );
+
+  return withRpcStreamTracing(method, instrumented, traceAttributes);
+};
diff --git a/apps/server/src/observability/Services/BrowserTraceCollector.ts b/apps/server/src/observability/Services/BrowserTraceCollector.ts
index e27a53c9c34..b704804c963 100644
--- a/apps/server/src/observability/Services/BrowserTraceCollector.ts
+++ b/apps/server/src/observability/Services/BrowserTraceCollector.ts
@@ -1,7 +1,6 @@
-import { Context } from "effect";
-import type { Effect } from "effect";
-
-import type { TraceRecord } from "../TraceRecord.ts";
+import type { TraceRecord } from "@t3tools/shared/observability";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 export interface BrowserTraceCollectorShape {
   readonly record: (records: ReadonlyArray<TraceRecord>) => Effect.Effect<void>;
diff --git a/apps/server/src/observability/TraceSink.test.ts b/apps/server/src/observability/TraceSink.test.ts
deleted file mode 100644
index f4db90516b1..00000000000
--- a/apps/server/src/observability/TraceSink.test.ts
+++ /dev/null
@@ -1,152 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
-
-import type { TraceRecord } from "./TraceRecord.ts";
-import { makeTraceSink } from "./TraceSink.ts";
-
-const makeRecord = (name: string, suffix = ""): TraceRecord => ({
-  type: "effect-span",
-  name,
-  traceId: `trace-${name}-${suffix}`,
-  spanId: `span-${name}-${suffix}`,
-  sampled: true,
-  kind: "internal",
-  startTimeUnixNano: "1",
-  endTimeUnixNano: "2",
-  durationMs: 1,
-  attributes: {
-    payload: suffix,
-  },
-  events: [],
-  links: [],
-  exit: {
-    _tag: "Success",
-  },
-});
-
-describe("TraceSink", () => {
-  it.effect("flushes buffered records on close", () =>
-    Effect.scoped(
-      Effect.gen(function* () {
-        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-trace-sink-"));
-        const tracePath = path.join(tempDir, "server.trace.ndjson");
-
-        try {
-          const sink = yield* makeTraceSink({
-            filePath: tracePath,
-            maxBytes: 1024,
-            maxFiles: 2,
-            batchWindowMs: 10_000,
-          });
-
-          sink.push(makeRecord("alpha"));
-          sink.push(makeRecord("beta"));
-          yield* sink.close();
-
-          const lines = fs
-            .readFileSync(tracePath, "utf8")
-            .trim()
-            .split("\n")
-            .map((line) => JSON.parse(line) as TraceRecord);
-
-          assert.equal(lines.length, 2);
-          assert.equal(lines[0]?.name, "alpha");
-          assert.equal(lines[1]?.name, "beta");
-        } finally {
-          fs.rmSync(tempDir, { recursive: true, force: true });
-        }
-      }),
-    ),
-  );
-
-  it.effect("rotates the trace file when the configured max size is exceeded", () =>
-    Effect.scoped(
-      Effect.gen(function* () {
-        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-trace-sink-"));
-        const tracePath = path.join(tempDir, "server.trace.ndjson");
-
-        try {
-          const sink = yield* makeTraceSink({
-            filePath: tracePath,
-            maxBytes: 180,
-            maxFiles: 2,
-            batchWindowMs: 10_000,
-          });
-
-          for (let index = 0; index < 8; index += 1) {
-            sink.push(makeRecord("rotate", `${index}-${"x".repeat(48)}`));
-            yield* sink.flush;
-          }
-          yield* sink.close();
-
-          const matchingFiles = fs
-            .readdirSync(tempDir)
-            .filter(
-              (entry) =>
-                entry === "server.trace.ndjson" || entry.startsWith("server.trace.ndjson."),
-            )
-            .toSorted();
-
-          assert.equal(
-            matchingFiles.some((entry) => entry === "server.trace.ndjson.1"),
-            true,
-          );
-          assert.equal(
-            matchingFiles.some((entry) => entry === "server.trace.ndjson.3"),
-            false,
-          );
-        } finally {
-          fs.rmSync(tempDir, { recursive: true, force: true });
-        }
-      }),
-    ),
-  );
-
-  it.effect("drops only the invalid record when serialization fails", () =>
-    Effect.scoped(
-      Effect.gen(function* () {
-        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-trace-sink-"));
-        const tracePath = path.join(tempDir, "server.trace.ndjson");
-
-        try {
-          const sink = yield* makeTraceSink({
-            filePath: tracePath,
-            maxBytes: 1024,
-            maxFiles: 2,
-            batchWindowMs: 10_000,
-          });
-
-          const circular: Array<unknown> = [];
-          circular.push(circular);
-
-          sink.push(makeRecord("alpha"));
-          sink.push({
-            ...makeRecord("invalid"),
-            attributes: {
-              circular,
-            },
-          } as TraceRecord);
-          sink.push(makeRecord("beta"));
-          yield* sink.close();
-
-          const lines = fs
-            .readFileSync(tracePath, "utf8")
-            .trim()
-            .split("\n")
-            .map((line) => JSON.parse(line) as TraceRecord);
-
-          assert.deepStrictEqual(
-            lines.map((line) => line.name),
-            ["alpha", "beta"],
-          );
-        } finally {
-          fs.rmSync(tempDir, { recursive: true, force: true });
-        }
-      }),
-    ),
-  );
-});
diff --git a/apps/server/src/observability/TraceSink.ts b/apps/server/src/observability/TraceSink.ts
deleted file mode 100644
index 1bd00b47341..00000000000
--- a/apps/server/src/observability/TraceSink.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import { RotatingFileSink } from "@t3tools/shared/logging";
-import { Effect } from "effect";
-
-import type { TraceRecord } from "./TraceRecord.ts";
-
-const FLUSH_BUFFER_THRESHOLD = 32;
-
-export interface TraceSinkOptions {
-  readonly filePath: string;
-  readonly maxBytes: number;
-  readonly maxFiles: number;
-  readonly batchWindowMs: number;
-}
-
-export interface TraceSink {
-  readonly filePath: string;
-  push: (record: TraceRecord) => void;
-  flush: Effect.Effect<void>;
-  close: () => Effect.Effect<void>;
-}
-
-export const makeTraceSink = Effect.fn("makeTraceSink")(function* (options: TraceSinkOptions) {
-  const sink = new RotatingFileSink({
-    filePath: options.filePath,
-    maxBytes: options.maxBytes,
-    maxFiles: options.maxFiles,
-  });
-
-  let buffer: Array<string> = [];
-
-  const flushUnsafe = () => {
-    if (buffer.length === 0) {
-      return;
-    }
-
-    const chunk = buffer.join("");
-    buffer = [];
-
-    try {
-      sink.write(chunk);
-    } catch {
-      buffer.unshift(chunk);
-    }
-  };
-
-  const flush = Effect.sync(flushUnsafe).pipe(Effect.withTracerEnabled(false));
-
-  yield* Effect.addFinalizer(() => flush.pipe(Effect.ignore));
-  yield* Effect.forkScoped(
-    Effect.sleep(`${options.batchWindowMs} millis`).pipe(Effect.andThen(flush), Effect.forever),
-  );
-
-  return {
-    filePath: options.filePath,
-    push(record) {
-      try {
-        buffer.push(`${JSON.stringify(record)}\n`);
-        if (buffer.length >= FLUSH_BUFFER_THRESHOLD) {
-          flushUnsafe();
-        }
-      } catch {
-        return;
-      }
-    },
-    flush,
-    close: () => flush,
-  } satisfies TraceSink;
-});
diff --git a/apps/server/src/open.test.ts b/apps/server/src/open.test.ts
deleted file mode 100644
index 59b0239c960..00000000000
--- a/apps/server/src/open.test.ts
+++ /dev/null
@@ -1,392 +0,0 @@
-import * as NodeServices from "@effect/platform-node/NodeServices";
-import { assert, it } from "@effect/vitest";
-import { assertSuccess } from "@effect/vitest/utils";
-import { FileSystem, Path, Effect } from "effect";
-
-import {
-  isCommandAvailable,
-  launchDetached,
-  resolveAvailableEditors,
-  resolveEditorLaunch,
-} from "./open";
-
-it.layer(NodeServices.layer)("resolveEditorLaunch", (it) => {
-  it.effect("returns commands for command-based editors", () =>
-    Effect.gen(function* () {
-      const antigravityLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "antigravity" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(antigravityLaunch, {
-        command: "agy",
-        args: ["/tmp/workspace"],
-      });
-
-      const cursorLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "cursor" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(cursorLaunch, {
-        command: "cursor",
-        args: ["/tmp/workspace"],
-      });
-
-      const traeLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "trae" },
-        "darwin",
-      );
-      assert.deepEqual(traeLaunch, {
-        command: "trae",
-        args: ["/tmp/workspace"],
-      });
-
-      const vscodeLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "vscode" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(vscodeLaunch, {
-        command: "code",
-        args: ["/tmp/workspace"],
-      });
-
-      const vscodeInsidersLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "vscode-insiders" },
-        "darwin",
-      );
-      assert.deepEqual(vscodeInsidersLaunch, {
-        command: "code-insiders",
-        args: ["/tmp/workspace"],
-      });
-
-      const vscodiumLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "vscodium" },
-        "darwin",
-      );
-      assert.deepEqual(vscodiumLaunch, {
-        command: "codium",
-        args: ["/tmp/workspace"],
-      });
-
-      const zedLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "zed" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(zedLaunch, {
-        command: "zed",
-        args: ["/tmp/workspace"],
-      });
-
-      const ideaLaunch = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "idea" },
-        "darwin",
-      );
-      assert.deepEqual(ideaLaunch, {
-        command: "idea",
-        args: ["/tmp/workspace"],
-      });
-    }),
-  );
-
-  it.effect("applies launch-style-specific navigation arguments", () =>
-    Effect.gen(function* () {
-      const lineOnly = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/AGENTS.md:48", editor: "cursor" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(lineOnly, {
-        command: "cursor",
-        args: ["--goto", "/tmp/workspace/AGENTS.md:48"],
-      });
-
-      const lineAndColumn = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/src/open.ts:71:5", editor: "cursor" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(lineAndColumn, {
-        command: "cursor",
-        args: ["--goto", "/tmp/workspace/src/open.ts:71:5"],
-      });
-
-      const traeLineAndColumn = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/src/open.ts:71:5", editor: "trae" },
-        "darwin",
-      );
-      assert.deepEqual(traeLineAndColumn, {
-        command: "trae",
-        args: ["--goto", "/tmp/workspace/src/open.ts:71:5"],
-      });
-
-      const vscodeLineAndColumn = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/src/open.ts:71:5", editor: "vscode" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(vscodeLineAndColumn, {
-        command: "code",
-        args: ["--goto", "/tmp/workspace/src/open.ts:71:5"],
-      });
-
-      const vscodeInsidersLineAndColumn = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/src/open.ts:71:5", editor: "vscode-insiders" },
-        "darwin",
-      );
-      assert.deepEqual(vscodeInsidersLineAndColumn, {
-        command: "code-insiders",
-        args: ["--goto", "/tmp/workspace/src/open.ts:71:5"],
-      });
-
-      const vscodiumLineAndColumn = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/src/open.ts:71:5", editor: "vscodium" },
-        "darwin",
-      );
-      assert.deepEqual(vscodiumLineAndColumn, {
-        command: "codium",
-        args: ["--goto", "/tmp/workspace/src/open.ts:71:5"],
-      });
-
-      const zedLineAndColumn = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/src/open.ts:71:5", editor: "zed" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(zedLineAndColumn, {
-        command: "zed",
-        args: ["/tmp/workspace/src/open.ts:71:5"],
-      });
-
-      const zedLineOnly = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/AGENTS.md:48", editor: "zed" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(zedLineOnly, {
-        command: "zed",
-        args: ["/tmp/workspace/AGENTS.md:48"],
-      });
-
-      const ideaLineOnly = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/AGENTS.md:48", editor: "idea" },
-        "darwin",
-      );
-      assert.deepEqual(ideaLineOnly, {
-        command: "idea",
-        args: ["--line", "48", "/tmp/workspace/AGENTS.md"],
-      });
-
-      const ideaLineAndColumn = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace/src/open.ts:71:5", editor: "idea" },
-        "darwin",
-      );
-      assert.deepEqual(ideaLineAndColumn, {
-        command: "idea",
-        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/open.ts"],
-      });
-    }),
-  );
-
-  it.effect("falls back to zeditor when zed is not installed", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-open-test-" });
-      yield* fs.writeFileString(path.join(dir, "zeditor"), "#!/bin/sh\nexit 0\n");
-      yield* fs.chmod(path.join(dir, "zeditor"), 0o755);
-
-      const result = yield* resolveEditorLaunch({ cwd: "/tmp/workspace", editor: "zed" }, "linux", {
-        PATH: dir,
-      });
-
-      assert.deepEqual(result, {
-        command: "zeditor",
-        args: ["/tmp/workspace"],
-      });
-    }),
-  );
-
-  it.effect("falls back to the primary command when no alias is installed", () =>
-    Effect.gen(function* () {
-      const result = yield* resolveEditorLaunch({ cwd: "/tmp/workspace", editor: "zed" }, "linux", {
-        PATH: "",
-      });
-      assert.deepEqual(result, {
-        command: "zed",
-        args: ["/tmp/workspace"],
-      });
-    }),
-  );
-
-  it.effect("maps file-manager editor to OS open commands", () =>
-    Effect.gen(function* () {
-      const launch1 = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "file-manager" },
-        "darwin",
-        { PATH: "" },
-      );
-      assert.deepEqual(launch1, {
-        command: "open",
-        args: ["/tmp/workspace"],
-      });
-
-      const launch2 = yield* resolveEditorLaunch(
-        { cwd: "C:\\workspace", editor: "file-manager" },
-        "win32",
-        { PATH: "" },
-      );
-      assert.deepEqual(launch2, {
-        command: "explorer",
-        args: ["C:\\workspace"],
-      });
-
-      const launch3 = yield* resolveEditorLaunch(
-        { cwd: "/tmp/workspace", editor: "file-manager" },
-        "linux",
-        { PATH: "" },
-      );
-      assert.deepEqual(launch3, {
-        command: "xdg-open",
-        args: ["/tmp/workspace"],
-      });
-    }),
-  );
-});
-
-it.layer(NodeServices.layer)("launchDetached", (it) => {
-  it.effect("resolves when command can be spawned", () =>
-    Effect.gen(function* () {
-      const result = yield* launchDetached({
-        command: process.execPath,
-        args: ["-e", "process.exit(0)"],
-      }).pipe(Effect.result);
-      assertSuccess(result, undefined);
-    }),
-  );
-
-  it.effect("rejects when command does not exist", () =>
-    Effect.gen(function* () {
-      const result = yield* launchDetached({
-        command: `t3code-no-such-command-${Date.now()}`,
-        args: [],
-      }).pipe(Effect.result);
-      assert.equal(result._tag, "Failure");
-    }),
-  );
-});
-
-it.layer(NodeServices.layer)("isCommandAvailable", (it) => {
-  it.effect("resolves win32 commands with PATHEXT", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-open-test-" });
-      yield* fs.writeFileString(path.join(dir, "code.CMD"), "@echo off\r\n");
-      const env = {
-        PATH: dir,
-        PATHEXT: ".COM;.EXE;.BAT;.CMD",
-      } satisfies NodeJS.ProcessEnv;
-      assert.equal(isCommandAvailable("code", { platform: "win32", env }), true);
-    }),
-  );
-
-  it("returns false when a command is not on PATH", () => {
-    const env = {
-      PATH: "",
-      PATHEXT: ".COM;.EXE;.BAT;.CMD",
-    } satisfies NodeJS.ProcessEnv;
-    assert.equal(isCommandAvailable("definitely-not-installed", { platform: "win32", env }), false);
-  });
-
-  it.effect("does not treat bare files without executable extension as available on win32", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-open-test-" });
-      yield* fs.writeFileString(path.join(dir, "npm"), "echo nope\r\n");
-      const env = {
-        PATH: dir,
-        PATHEXT: ".COM;.EXE;.BAT;.CMD",
-      } satisfies NodeJS.ProcessEnv;
-      assert.equal(isCommandAvailable("npm", { platform: "win32", env }), false);
-    }),
-  );
-
-  it.effect("appends PATHEXT for commands with non-executable extensions on win32", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-open-test-" });
-      yield* fs.writeFileString(path.join(dir, "my.tool.CMD"), "@echo off\r\n");
-      const env = {
-        PATH: dir,
-        PATHEXT: ".COM;.EXE;.BAT;.CMD",
-      } satisfies NodeJS.ProcessEnv;
-      assert.equal(isCommandAvailable("my.tool", { platform: "win32", env }), true);
-    }),
-  );
-
-  it.effect("uses platform-specific PATH delimiter for platform overrides", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const firstDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-open-test-" });
-      const secondDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-open-test-" });
-      yield* fs.writeFileString(path.join(firstDir, "code.CMD"), "@echo off\r\n");
-      yield* fs.writeFileString(path.join(secondDir, "code.CMD"), "MZ");
-      const env = {
-        PATH: `${firstDir};${secondDir}`,
-        PATHEXT: ".COM;.EXE;.BAT;.CMD",
-      } satisfies NodeJS.ProcessEnv;
-      assert.equal(isCommandAvailable("code", { platform: "win32", env }), true);
-    }),
-  );
-});
-
-it.layer(NodeServices.layer)("resolveAvailableEditors", (it) => {
-  it.effect("returns installed editors for command launches", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-
-      yield* fs.writeFileString(path.join(dir, "trae.CMD"), "@echo off\r\n");
-      yield* fs.writeFileString(path.join(dir, "code-insiders.CMD"), "@echo off\r\n");
-      yield* fs.writeFileString(path.join(dir, "codium.CMD"), "@echo off\r\n");
-      yield* fs.writeFileString(path.join(dir, "explorer.CMD"), "MZ");
-      const editors = resolveAvailableEditors("win32", {
-        PATH: dir,
-        PATHEXT: ".COM;.EXE;.BAT;.CMD",
-      });
-      assert.deepEqual(editors, ["trae", "vscode-insiders", "vscodium", "file-manager"]);
-    }),
-  );
-
-  it.effect("includes zed when only the zeditor command is installed", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-
-      yield* fs.writeFileString(path.join(dir, "zeditor"), "#!/bin/sh\nexit 0\n");
-      yield* fs.writeFileString(path.join(dir, "xdg-open"), "#!/bin/sh\nexit 0\n");
-      yield* fs.chmod(path.join(dir, "zeditor"), 0o755);
-      yield* fs.chmod(path.join(dir, "xdg-open"), 0o755);
-
-      const editors = resolveAvailableEditors("linux", {
-        PATH: dir,
-      });
-      assert.deepEqual(editors, ["zed", "file-manager"]);
-    }),
-  );
-
-  it("omits file-manager when the platform opener is unavailable", () => {
-    const editors = resolveAvailableEditors("linux", {
-      PATH: "",
-    });
-    assert.deepEqual(editors, []);
-  });
-});
diff --git a/apps/server/src/open.ts b/apps/server/src/open.ts
deleted file mode 100644
index 870da4e55e6..00000000000
--- a/apps/server/src/open.ts
+++ /dev/null
@@ -1,340 +0,0 @@
-/**
- * Open - Browser/editor launch service interface.
- *
- * Owns process launch helpers for opening URLs in a browser and workspace
- * paths in a configured editor.
- *
- * @module Open
- */
-import { spawn } from "node:child_process";
-import { accessSync, constants, statSync } from "node:fs";
-import { extname, join } from "node:path";
-
-import { EDITORS, OpenError, type EditorId } from "@t3tools/contracts";
-import { Context, Effect, Layer } from "effect";
-
-// ==============================
-// Definitions
-// ==============================
-
-export { OpenError };
-
-export interface OpenInEditorInput {
-  readonly cwd: string;
-  readonly editor: EditorId;
-}
-
-interface EditorLaunch {
-  readonly command: string;
-  readonly args: ReadonlyArray<string>;
-}
-
-interface CommandAvailabilityOptions {
-  readonly platform?: NodeJS.Platform;
-  readonly env?: NodeJS.ProcessEnv;
-}
-
-const TARGET_WITH_POSITION_PATTERN = /^(.*?):(\d+)(?::(\d+))?$/;
-
-function parseTargetPathAndPosition(target: string): {
-  path: string;
-  line: string | undefined;
-  column: string | undefined;
-} | null {
-  const match = TARGET_WITH_POSITION_PATTERN.exec(target);
-  if (!match?.[1] || !match[2]) {
-    return null;
-  }
-
-  return {
-    path: match[1],
-    line: match[2],
-    column: match[3],
-  };
-}
-
-function resolveCommandEditorArgs(
-  editor: (typeof EDITORS)[number],
-  target: string,
-): ReadonlyArray<string> {
-  const parsedTarget = parseTargetPathAndPosition(target);
-
-  switch (editor.launchStyle) {
-    case "direct-path":
-      return [target];
-    case "goto":
-      return parsedTarget ? ["--goto", target] : [target];
-    case "line-column": {
-      if (!parsedTarget) {
-        return [target];
-      }
-
-      const { path, line, column } = parsedTarget;
-      return [...(line ? ["--line", line] : []), ...(column ? ["--column", column] : []), path];
-    }
-  }
-}
-
-function resolveAvailableCommand(
-  commands: ReadonlyArray<string>,
-  options: CommandAvailabilityOptions = {},
-): string | null {
-  for (const command of commands) {
-    if (isCommandAvailable(command, options)) {
-      return command;
-    }
-  }
-  return null;
-}
-
-function fileManagerCommandForPlatform(platform: NodeJS.Platform): string {
-  switch (platform) {
-    case "darwin":
-      return "open";
-    case "win32":
-      return "explorer";
-    default:
-      return "xdg-open";
-  }
-}
-
-function stripWrappingQuotes(value: string): string {
-  return value.replace(/^"+|"+$/g, "");
-}
-
-function resolvePathEnvironmentVariable(env: NodeJS.ProcessEnv): string {
-  return env.PATH ?? env.Path ?? env.path ?? "";
-}
-
-function resolveWindowsPathExtensions(env: NodeJS.ProcessEnv): ReadonlyArray<string> {
-  const rawValue = env.PATHEXT;
-  const fallback = [".COM", ".EXE", ".BAT", ".CMD"];
-  if (!rawValue) return fallback;
-
-  const parsed = rawValue
-    .split(";")
-    .map((entry) => entry.trim())
-    .filter((entry) => entry.length > 0)
-    .map((entry) => (entry.startsWith(".") ? entry.toUpperCase() : `.${entry.toUpperCase()}`));
-  return parsed.length > 0 ? Array.from(new Set(parsed)) : fallback;
-}
-
-function resolveCommandCandidates(
-  command: string,
-  platform: NodeJS.Platform,
-  windowsPathExtensions: ReadonlyArray<string>,
-): ReadonlyArray<string> {
-  if (platform !== "win32") return [command];
-  const extension = extname(command);
-  const normalizedExtension = extension.toUpperCase();
-
-  if (extension.length > 0 && windowsPathExtensions.includes(normalizedExtension)) {
-    const commandWithoutExtension = command.slice(0, -extension.length);
-    return Array.from(
-      new Set([
-        command,
-        `${commandWithoutExtension}${normalizedExtension}`,
-        `${commandWithoutExtension}${normalizedExtension.toLowerCase()}`,
-      ]),
-    );
-  }
-
-  const candidates: string[] = [];
-  for (const extension of windowsPathExtensions) {
-    candidates.push(`${command}${extension}`);
-    candidates.push(`${command}${extension.toLowerCase()}`);
-  }
-  return Array.from(new Set(candidates));
-}
-
-function isExecutableFile(
-  filePath: string,
-  platform: NodeJS.Platform,
-  windowsPathExtensions: ReadonlyArray<string>,
-): boolean {
-  try {
-    const stat = statSync(filePath);
-    if (!stat.isFile()) return false;
-    if (platform === "win32") {
-      const extension = extname(filePath);
-      if (extension.length === 0) return false;
-      return windowsPathExtensions.includes(extension.toUpperCase());
-    }
-    accessSync(filePath, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function resolvePathDelimiter(platform: NodeJS.Platform): string {
-  return platform === "win32" ? ";" : ":";
-}
-
-export function isCommandAvailable(
-  command: string,
-  options: CommandAvailabilityOptions = {},
-): boolean {
-  const platform = options.platform ?? process.platform;
-  const env = options.env ?? process.env;
-  const windowsPathExtensions = platform === "win32" ? resolveWindowsPathExtensions(env) : [];
-  const commandCandidates = resolveCommandCandidates(command, platform, windowsPathExtensions);
-
-  if (command.includes("/") || command.includes("\\")) {
-    return commandCandidates.some((candidate) =>
-      isExecutableFile(candidate, platform, windowsPathExtensions),
-    );
-  }
-
-  const pathValue = resolvePathEnvironmentVariable(env);
-  if (pathValue.length === 0) return false;
-  const pathEntries = pathValue
-    .split(resolvePathDelimiter(platform))
-    .map((entry) => stripWrappingQuotes(entry.trim()))
-    .filter((entry) => entry.length > 0);
-
-  for (const pathEntry of pathEntries) {
-    for (const candidate of commandCandidates) {
-      if (isExecutableFile(join(pathEntry, candidate), platform, windowsPathExtensions)) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-export function resolveAvailableEditors(
-  platform: NodeJS.Platform = process.platform,
-  env: NodeJS.ProcessEnv = process.env,
-): ReadonlyArray<EditorId> {
-  const available: EditorId[] = [];
-
-  for (const editor of EDITORS) {
-    if (editor.commands === null) {
-      const command = fileManagerCommandForPlatform(platform);
-      if (isCommandAvailable(command, { platform, env })) {
-        available.push(editor.id);
-      }
-      continue;
-    }
-
-    const command = resolveAvailableCommand(editor.commands, { platform, env });
-    if (command !== null) {
-      available.push(editor.id);
-    }
-  }
-
-  return available;
-}
-
-/**
- * OpenShape - Service API for browser and editor launch actions.
- */
-export interface OpenShape {
-  /**
-   * Open a URL target in the default browser.
-   */
-  readonly openBrowser: (target: string) => Effect.Effect<void, OpenError>;
-
-  /**
-   * Open a workspace path in a selected editor integration.
-   *
-   * Launches the editor as a detached process so server startup is not blocked.
-   */
-  readonly openInEditor: (input: OpenInEditorInput) => Effect.Effect<void, OpenError>;
-}
-
-/**
- * Open - Service tag for browser/editor launch operations.
- */
-export class Open extends Context.Service<Open, OpenShape>()("t3/open") {}
-
-// ==============================
-// Implementations
-// ==============================
-
-export const resolveEditorLaunch = Effect.fn("resolveEditorLaunch")(function* (
-  input: OpenInEditorInput,
-  platform: NodeJS.Platform = process.platform,
-  env: NodeJS.ProcessEnv = process.env,
-): Effect.fn.Return<EditorLaunch, OpenError> {
-  yield* Effect.annotateCurrentSpan({
-    "open.editor": input.editor,
-    "open.cwd": input.cwd,
-    "open.platform": platform,
-  });
-  const editorDef = EDITORS.find((editor) => editor.id === input.editor);
-  if (!editorDef) {
-    return yield* new OpenError({ message: `Unknown editor: ${input.editor}` });
-  }
-
-  if (editorDef.commands) {
-    const command =
-      resolveAvailableCommand(editorDef.commands, { platform, env }) ?? editorDef.commands[0];
-    return {
-      command,
-      args: resolveCommandEditorArgs(editorDef, input.cwd),
-    };
-  }
-
-  if (editorDef.id !== "file-manager") {
-    return yield* new OpenError({ message: `Unsupported editor: ${input.editor}` });
-  }
-
-  return { command: fileManagerCommandForPlatform(platform), args: [input.cwd] };
-});
-
-export const launchDetached = (launch: EditorLaunch) =>
-  Effect.gen(function* () {
-    if (!isCommandAvailable(launch.command)) {
-      return yield* new OpenError({ message: `Editor command not found: ${launch.command}` });
-    }
-
-    yield* Effect.callback<void, OpenError>((resume) => {
-      let child;
-      try {
-        const isWin32 = process.platform === "win32";
-        child = spawn(
-          launch.command,
-          isWin32 ? launch.args.map((a) => `"${a}"`) : [...launch.args],
-          {
-            detached: true,
-            stdio: "ignore",
-            shell: isWin32,
-          },
-        );
-      } catch (error) {
-        return resume(
-          Effect.fail(new OpenError({ message: "failed to spawn detached process", cause: error })),
-        );
-      }
-
-      const handleSpawn = () => {
-        child.unref();
-        resume(Effect.void);
-      };
-
-      child.once("spawn", handleSpawn);
-      child.once("error", (cause) =>
-        resume(Effect.fail(new OpenError({ message: "failed to spawn detached process", cause }))),
-      );
-    });
-  });
-
-const make = Effect.gen(function* () {
-  const open = yield* Effect.tryPromise({
-    try: () => import("open"),
-    catch: (cause) => new OpenError({ message: "failed to load browser opener", cause }),
-  });
-
-  return {
-    openBrowser: (target) =>
-      Effect.tryPromise({
-        try: () => open.default(target),
-        catch: (cause) => new OpenError({ message: "Browser auto-open failed", cause }),
-      }),
-    openInEditor: (input) => Effect.flatMap(resolveEditorLaunch(input), launchDetached),
-  } satisfies OpenShape;
-});
-
-export const OpenLive = Layer.effect(Open, make);
diff --git a/apps/server/src/orchestration/Errors.ts b/apps/server/src/orchestration/Errors.ts
index 1ea038e1d13..888fd4b3c0d 100644
--- a/apps/server/src/orchestration/Errors.ts
+++ b/apps/server/src/orchestration/Errors.ts
@@ -1,4 +1,5 @@
-import { SchemaIssue, Schema } from "effect";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as Schema from "effect/Schema";
 
 import type { ProjectionRepositoryError } from "../persistence/Errors.ts";
 
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
index 12e11450dd3..b610c0abc28 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
@@ -1,9 +1,15 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 
-import type { ProviderKind, ProviderRuntimeEvent, ProviderSession } from "@t3tools/contracts";
+import {
+  ProviderDriverKind,
+  ProviderRuntimeEvent,
+  ProviderSession,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
 import {
   CommandId,
   DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -14,13 +20,21 @@ import {
   TurnId,
 } from "@t3tools/contracts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { Effect, Exit, Layer, ManagedRuntime, PubSub, Scope, Stream } from "effect";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as PubSub from "effect/PubSub";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { CheckpointStoreLive } from "../../checkpointing/Layers/CheckpointStore.ts";
 import { CheckpointStore } from "../../checkpointing/Services/CheckpointStore.ts";
-import { GitCoreLive } from "../../git/Layers/GitCore.ts";
-import { GitStatusBroadcaster } from "../../git/Services/GitStatusBroadcaster.ts";
+import * as VcsDriverRegistry from "../../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../../vcs/VcsProcess.ts";
+import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
 import { RepositoryIdentityResolverLive } from "../../project/Layers/RepositoryIdentityResolver.ts";
 import { CheckpointReactorLive } from "./CheckpointReactor.ts";
 import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
@@ -35,6 +49,7 @@ import {
   type OrchestrationEngineShape,
 } from "../Services/OrchestrationEngine.ts";
 import { CheckpointReactor } from "../Services/CheckpointReactor.ts";
+import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import {
   ProviderService,
   type ProviderServiceShape,
@@ -50,7 +65,7 @@ const asTurnId = (value: string): TurnId => TurnId.make(value);
 type LegacyProviderRuntimeEvent = {
   readonly type: string;
   readonly eventId: EventId;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly createdAt: string;
   readonly threadId: ThreadId;
   readonly turnId?: string | undefined;
@@ -64,9 +79,9 @@ function createProviderServiceHarness(
   cwd: string,
   hasSession = true,
   sessionCwd = cwd,
-  providerName: ProviderSession["provider"] = "codex",
+  providerName: ProviderSession["provider"] = ProviderDriverKind.make("codex"),
 ) {
-  const now = new Date().toISOString();
+  const now = "2026-01-01T00:00:00.000Z";
   const runtimeEventPubSub = Effect.runSync(PubSub.unbounded<ProviderRuntimeEvent>());
   const rollbackConversation = vi.fn(
     (_input: { readonly threadId: ThreadId; readonly numTurns: number }) => Effect.void,
@@ -97,6 +112,17 @@ function createProviderServiceHarness(
     stopSession: () => unsupported(),
     listSessions,
     getCapabilities: () => Effect.succeed({ sessionModelSwitch: "in-session" }),
+    getInstanceInfo: (instanceId) =>
+      Effect.succeed({
+        instanceId,
+        driverKind: ProviderDriverKind.make(providerName),
+        displayName: undefined,
+        enabled: true,
+        continuationIdentity: {
+          driverKind: ProviderDriverKind.make(providerName),
+          continuationKey: `${providerName}:instance:${instanceId}`,
+        },
+      }),
     rollbackConversation,
     get streamEvents() {
       return Stream.fromPubSub(runtimeEventPubSub);
@@ -115,7 +141,14 @@ function createProviderServiceHarness(
 }
 
 async function waitForThread(
-  engine: OrchestrationEngineShape,
+  readModel: () => Promise<{
+    readonly threads: ReadonlyArray<{
+      readonly id: ThreadId;
+      readonly latestTurn: { readonly turnId: string } | null;
+      readonly checkpoints: ReadonlyArray<{ readonly checkpointTurnCount: number }>;
+      readonly activities: ReadonlyArray<{ readonly kind: string }>;
+    }>;
+  }>,
   predicate: (thread: {
     latestTurn: { turnId: string } | null;
     checkpoints: ReadonlyArray<{ checkpointTurnCount: number }>;
@@ -123,21 +156,21 @@ async function waitForThread(
   }) => boolean,
   timeoutMs = 15_000,
 ) {
-  const deadline = Date.now() + timeoutMs;
+  const deadline = (await Effect.runPromise(Clock.currentTimeMillis)) + timeoutMs;
   const poll = async (): Promise<{
     latestTurn: { turnId: string } | null;
     checkpoints: ReadonlyArray<{ checkpointTurnCount: number }>;
     activities: ReadonlyArray<{ kind: string }>;
   }> => {
-    const readModel = await Effect.runPromise(engine.getReadModel());
-    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    const snapshot = await readModel();
+    const thread = snapshot.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     if (thread && predicate(thread)) {
       return thread;
     }
-    if (Date.now() >= deadline) {
+    if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
       throw new Error("Timed out waiting for thread state.");
     }
-    await new Promise((resolve) => setTimeout(resolve, 10));
+    await Effect.runPromise(Effect.sleep("10 millis"));
     return poll();
   };
   return poll();
@@ -148,7 +181,7 @@ async function waitForEvent(
   predicate: (event: { type: string }) => boolean,
   timeoutMs = 15_000,
 ) {
-  const deadline = Date.now() + timeoutMs;
+  const deadline = (await Effect.runPromise(Clock.currentTimeMillis)) + timeoutMs;
   const poll = async () => {
     const events = await Effect.runPromise(
       Stream.runCollect(engine.readEvents(0)).pipe(Effect.map((chunk) => Array.from(chunk))),
@@ -156,10 +189,10 @@ async function waitForEvent(
     if (events.some(predicate)) {
       return events;
     }
-    if (Date.now() >= deadline) {
+    if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
       throw new Error("Timed out waiting for orchestration event.");
     }
-    await new Promise((resolve) => setTimeout(resolve, 10));
+    await Effect.runPromise(Effect.sleep("10 millis"));
     return poll();
   };
   return poll();
@@ -198,15 +231,15 @@ function gitShowFileAtRef(cwd: string, ref: string, filePath: string): string {
 }
 
 async function waitForGitRefExists(cwd: string, ref: string, timeoutMs = 15_000) {
-  const deadline = Date.now() + timeoutMs;
+  const deadline = (await Effect.runPromise(Clock.currentTimeMillis)) + timeoutMs;
   const poll = async (): Promise<void> => {
     if (gitRefExists(cwd, ref)) {
       return;
     }
-    if (Date.now() >= deadline) {
+    if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
       throw new Error(`Timed out waiting for git ref '${ref}'.`);
     }
-    await new Promise((resolve) => setTimeout(resolve, 10));
+    await Effect.runPromise(Effect.sleep("10 millis"));
     return poll();
   };
   return poll();
@@ -214,7 +247,7 @@ async function waitForGitRefExists(cwd: string, ref: string, timeoutMs = 15_000)
 
 describe("CheckpointReactor", () => {
   let runtime: ManagedRuntime.ManagedRuntime<
-    OrchestrationEngineService | CheckpointReactor | CheckpointStore,
+    OrchestrationEngineService | CheckpointReactor | CheckpointStore | ProjectionSnapshotQuery,
     unknown
   > | null = null;
   let scope: Scope.Closeable | null = null;
@@ -243,7 +276,7 @@ describe("CheckpointReactor", () => {
     readonly projectWorkspaceRoot?: string;
     readonly threadWorktreePath?: string | null;
     readonly providerSessionCwd?: string;
-    readonly providerName?: ProviderKind;
+    readonly providerName?: ProviderDriverKind;
     readonly gitStatusRefreshCalls?: Array<string>;
   }) {
     const cwd = createGitRepository();
@@ -252,7 +285,7 @@ describe("CheckpointReactor", () => {
       cwd,
       options?.hasSession ?? true,
       options?.providerSessionCwd ?? cwd,
-      options?.providerName ?? "codex",
+      options?.providerName ?? ProviderDriverKind.make("codex"),
     );
     const orchestrationLayer = OrchestrationEngineLive.pipe(
       Layer.provide(OrchestrationProjectionSnapshotQueryLive),
@@ -262,11 +295,15 @@ describe("CheckpointReactor", () => {
       Layer.provide(RepositoryIdentityResolverLive),
       Layer.provide(SqlitePersistenceMemory),
     );
+    const projectionSnapshotLayer = OrchestrationProjectionSnapshotQueryLive.pipe(
+      Layer.provide(RepositoryIdentityResolverLive),
+      Layer.provide(SqlitePersistenceMemory),
+    );
 
     const ServerConfigLayer = ServerConfig.layerTest(process.cwd(), {
       prefix: "t3-checkpoint-reactor-test-",
     });
-    const gitStatusBroadcasterLayer = Layer.succeed(GitStatusBroadcaster, {
+    const vcsStatusBroadcasterLayer = Layer.succeed(VcsStatusBroadcaster, {
       getStatus: () => Effect.die("getStatus should not be called in this test"),
       refreshLocalStatus: (cwd: string) =>
         Effect.sync(() => {
@@ -274,9 +311,9 @@ describe("CheckpointReactor", () => {
         }).pipe(
           Effect.as({
             isRepo: true,
-            hasOriginRemote: false,
-            isDefaultBranch: true,
-            branch: "main",
+            hasPrimaryRemote: false,
+            isDefaultRef: true,
+            refName: "main",
             hasWorkingTreeChanges: false,
             workingTree: { files: [], insertions: 0, deletions: 0 },
           }),
@@ -287,26 +324,33 @@ describe("CheckpointReactor", () => {
 
     const layer = CheckpointReactorLive.pipe(
       Layer.provideMerge(orchestrationLayer),
+      Layer.provideMerge(projectionSnapshotLayer),
       Layer.provideMerge(RuntimeReceiptBusLive),
       Layer.provideMerge(Layer.succeed(ProviderService, provider.service)),
-      Layer.provideMerge(gitStatusBroadcasterLayer),
-      Layer.provideMerge(CheckpointStoreLive),
-      Layer.provideMerge(WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive))),
+      Layer.provideMerge(vcsStatusBroadcasterLayer),
+      Layer.provideMerge(CheckpointStoreLive.pipe(Layer.provide(VcsDriverRegistry.layer))),
+      Layer.provideMerge(
+        WorkspaceEntriesLive.pipe(
+          Layer.provide(WorkspacePathsLive),
+          Layer.provideMerge(VcsDriverRegistry.layer),
+        ),
+      ),
       Layer.provideMerge(WorkspacePathsLive),
-      Layer.provideMerge(GitCoreLive),
+      Layer.provideMerge(VcsProcess.layer),
       Layer.provideMerge(ServerConfigLayer),
       Layer.provideMerge(NodeServices.layer),
     );
 
     runtime = ManagedRuntime.make(layer);
     const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
+    const snapshotQuery = await runtime.runPromise(Effect.service(ProjectionSnapshotQuery));
     const reactor = await runtime.runPromise(Effect.service(CheckpointReactor));
     const checkpointStore = await runtime.runPromise(Effect.service(CheckpointStore));
     scope = await Effect.runPromise(Scope.make("sequential"));
     await Effect.runPromise(reactor.start().pipe(Scope.provide(scope)));
     const drain = () => Effect.runPromise(reactor.drain);
 
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
     await Effect.runPromise(
       engine.dispatch({
         type: "project.create",
@@ -315,7 +359,7 @@ describe("CheckpointReactor", () => {
         title: "Test Project",
         workspaceRoot: options?.projectWorkspaceRoot ?? cwd,
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -329,7 +373,7 @@ describe("CheckpointReactor", () => {
         projectId: asProjectId("project-1"),
         title: "Thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -365,6 +409,7 @@ describe("CheckpointReactor", () => {
 
     return {
       engine,
+      readModel: () => Effect.runPromise(snapshotQuery.getSnapshot()),
       provider,
       cwd,
       drain,
@@ -373,7 +418,7 @@ describe("CheckpointReactor", () => {
 
   it("captures pre-turn baseline on turn.started and post-turn checkpoint on turn.completed", async () => {
     const harness = await createHarness({ seedFilesystemCheckpoints: false });
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -396,9 +441,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.started",
       eventId: EventId.make("evt-turn-started-1"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-1"),
     });
@@ -411,9 +456,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-1"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-1"),
       payload: { state: "completed" },
@@ -421,7 +466,7 @@ describe("CheckpointReactor", () => {
 
     await waitForEvent(harness.engine, (event) => event.type === "thread.turn-diff-completed");
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) => entry.latestTurn?.turnId === "turn-1" && entry.checkpoints.length === 1,
     );
     expect(thread.checkpoints[0]?.checkpointTurnCount).toBe(1);
@@ -457,8 +502,8 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-refresh-local-status"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-refresh-local-status"),
       payload: { state: "completed" },
@@ -471,7 +516,7 @@ describe("CheckpointReactor", () => {
 
   it("ignores auxiliary thread turn completion while primary turn is active", async () => {
     const harness = await createHarness({ seedFilesystemCheckpoints: false });
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -494,9 +539,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.started",
       eventId: EventId.make("evt-turn-started-main"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-main"),
     });
@@ -510,32 +555,32 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-aux"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-aux"),
       payload: { state: "completed" },
     });
 
     await harness.drain();
-    const midReadModel = await Effect.runPromise(harness.engine.getReadModel());
+    const midReadModel = await harness.readModel();
     const midThread = midReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(midThread?.checkpoints).toHaveLength(0);
 
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-main"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-main"),
       payload: { state: "completed" },
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) => entry.latestTurn?.turnId === "turn-main" && entry.checkpoints.length === 1,
     );
     expect(thread.checkpoints[0]?.checkpointTurnCount).toBe(1);
@@ -544,9 +589,9 @@ describe("CheckpointReactor", () => {
   it("captures pre-turn and completion checkpoints for claude runtime events", async () => {
     const harness = await createHarness({
       seedFilesystemCheckpoints: false,
-      providerName: "claudeAgent",
+      providerName: ProviderDriverKind.make("claudeAgent"),
     });
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -569,8 +614,8 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.started",
       eventId: EventId.make("evt-turn-started-claude-1"),
-      provider: "claudeAgent",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("claudeAgent"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-claude-1"),
     });
@@ -583,8 +628,8 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-claude-1"),
-      provider: "claudeAgent",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("claudeAgent"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-claude-1"),
       payload: { state: "completed" },
@@ -592,7 +637,7 @@ describe("CheckpointReactor", () => {
 
     await waitForEvent(harness.engine, (event) => event.type === "thread.turn-diff-completed");
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) => entry.latestTurn?.turnId === "turn-claude-1" && entry.checkpoints.length === 1,
     );
 
@@ -604,7 +649,7 @@ describe("CheckpointReactor", () => {
 
   it("appends capture failure activity when turn diff summary cannot be derived", async () => {
     const harness = await createHarness({ seedFilesystemCheckpoints: false });
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -627,9 +672,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-missing-baseline"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-missing-baseline"),
       payload: { state: "completed" },
@@ -637,7 +682,7 @@ describe("CheckpointReactor", () => {
 
     await waitForEvent(harness.engine, (event) => event.type === "thread.turn-diff-completed");
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.checkpoints.length === 1 &&
         entry.activities.some((activity) => activity.kind === "checkpoint.capture.failed"),
@@ -669,7 +714,7 @@ describe("CheckpointReactor", () => {
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
       }),
     );
 
@@ -692,7 +737,7 @@ describe("CheckpointReactor", () => {
       seedFilesystemCheckpoints: false,
       threadWorktreePath: null,
     });
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -716,9 +761,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-missing-provider-cwd"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-missing-cwd"),
       payload: { state: "completed" },
@@ -739,7 +784,7 @@ describe("CheckpointReactor", () => {
 
   it("ignores non-v2 checkpoint.captured runtime events", async () => {
     const harness = await createHarness();
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -762,9 +807,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "checkpoint.captured",
       eventId: EventId.make("evt-checkpoint-captured-3"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-3"),
       turnCount: 3,
@@ -772,7 +817,7 @@ describe("CheckpointReactor", () => {
     });
 
     await harness.drain();
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.checkpoints.some((checkpoint) => checkpoint.checkpointTurnCount === 3)).toBe(
       false,
@@ -789,7 +834,7 @@ describe("CheckpointReactor", () => {
       seedFilesystemCheckpoints: false,
       providerSessionCwd: nonRepositorySessionCwd,
     });
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -812,9 +857,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-runtime-capture-failure"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-runtime-failure"),
       payload: { state: "completed" },
@@ -823,9 +868,9 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.started",
       eventId: EventId.make("evt-turn-started-after-runtime-failure"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-after-runtime-failure"),
     });
@@ -841,7 +886,7 @@ describe("CheckpointReactor", () => {
 
   it("executes provider revert and emits thread.reverted for checkpoint revert requests", async () => {
     const harness = await createHarness();
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -901,7 +946,10 @@ describe("CheckpointReactor", () => {
     );
 
     await waitForEvent(harness.engine, (event) => event.type === "thread.reverted");
-    const thread = await waitForThread(harness.engine, (entry) => entry.checkpoints.length === 1);
+    const thread = await waitForThread(
+      harness.readModel,
+      (entry) => entry.checkpoints.length === 1,
+    );
 
     expect(thread.latestTurn?.turnId).toBe("turn-1");
     expect(thread.checkpoints).toHaveLength(1);
@@ -918,8 +966,8 @@ describe("CheckpointReactor", () => {
   });
 
   it("executes provider revert and emits thread.reverted for claude sessions", async () => {
-    const harness = await createHarness({ providerName: "claudeAgent" });
-    const createdAt = new Date().toISOString();
+    const harness = await createHarness({ providerName: ProviderDriverKind.make("claudeAgent") });
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -988,7 +1036,7 @@ describe("CheckpointReactor", () => {
 
   it("processes consecutive revert requests with deterministic rollback sequencing", async () => {
     const harness = await createHarness();
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1071,7 +1119,7 @@ describe("CheckpointReactor", () => {
 
   it("appends an error activity when revert is requested without an active session", async () => {
     const harness = await createHarness({ hasSession: false });
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1083,7 +1131,7 @@ describe("CheckpointReactor", () => {
       }),
     );
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.activities.some((activity) => activity.kind === "checkpoint.revert.failed"),
     );
 
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
index 0b1b203ba24..da135b0c056 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
@@ -8,7 +8,12 @@ import {
   type OrchestrationEvent,
   type ProviderRuntimeEvent,
 } from "@t3tools/contracts";
-import { Cause, Effect, Layer, Option, Stream } from "effect";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
 import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
 
 import { parseTurnDiffFilesFromUnifiedDiff } from "../../checkpointing/Diffs.ts";
@@ -20,13 +25,16 @@ import { CheckpointStore } from "../../checkpointing/Services/CheckpointStore.ts
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { CheckpointReactor, type CheckpointReactorShape } from "../Services/CheckpointReactor.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import { RuntimeReceiptBus } from "../Services/RuntimeReceiptBus.ts";
-import { CheckpointStoreError } from "../../checkpointing/Errors.ts";
-import { OrchestrationDispatchError } from "../Errors.ts";
+import type { CheckpointStoreError } from "../../checkpointing/Errors.ts";
+import type { OrchestrationDispatchError } from "../Errors.ts";
 import { isGitRepository } from "../../git/Utils.ts";
-import { GitStatusBroadcaster } from "../../git/Services/GitStatusBroadcaster.ts";
+import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
 import { WorkspaceEntries } from "../../workspace/Services/WorkspaceEntries.ts";
 
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
 type ReactorInput =
   | {
       readonly source: "runtime";
@@ -66,11 +74,12 @@ const serverCommandId = (tag: string): CommandId =>
 
 const make = Effect.gen(function* () {
   const orchestrationEngine = yield* OrchestrationEngineService;
+  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
   const providerService = yield* ProviderService;
   const checkpointStore = yield* CheckpointStore;
   const receiptBus = yield* RuntimeReceiptBus;
   const workspaceEntries = yield* WorkspaceEntries;
-  const gitStatusBroadcaster = yield* GitStatusBroadcaster;
+  const vcsStatusBroadcaster = yield* VcsStatusBroadcaster;
 
   const appendRevertFailureActivity = (input: {
     readonly threadId: ThreadId;
@@ -124,29 +133,26 @@ const make = Effect.gen(function* () {
   const resolveSessionRuntimeForThread = Effect.fn("resolveSessionRuntimeForThread")(function* (
     threadId: ThreadId,
   ): Effect.fn.Return<Option.Option<{ readonly threadId: ThreadId; readonly cwd: string }>> {
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === threadId);
-
     const sessions = yield* providerService.listSessions();
+    const session = sessions.find((entry) => entry.threadId === threadId);
+    return session?.cwd
+      ? Option.some({ threadId: session.threadId, cwd: session.cwd })
+      : Option.none();
+  });
 
-    const findSessionWithCwd = (
-      session: (typeof sessions)[number] | undefined,
-    ): Option.Option<{ readonly threadId: ThreadId; readonly cwd: string }> => {
-      if (!session?.cwd) {
-        return Option.none();
-      }
-      return Option.some({ threadId: session.threadId, cwd: session.cwd });
-    };
-
-    if (thread) {
-      const projectedSession = sessions.find((session) => session.threadId === thread.id);
-      const fromProjected = findSessionWithCwd(projectedSession);
-      if (Option.isSome(fromProjected)) {
-        return fromProjected;
-      }
-    }
+  const resolveThreadDetail = Effect.fn("resolveThreadDetail")(function* (threadId: ThreadId) {
+    return yield* projectionSnapshotQuery
+      .getThreadDetailById(threadId)
+      .pipe(Effect.map(Option.getOrUndefined));
+  });
 
-    return Option.none();
+  const resolveThreadProjects = Effect.fn("resolveThreadProjects")(function* (
+    projectId: ProjectId,
+  ) {
+    const project = yield* projectionSnapshotQuery
+      .getProjectShellById(projectId)
+      .pipe(Effect.map(Option.getOrUndefined));
+    return project ? [project] : [];
   });
 
   const isGitWorkspace = (cwd: string) => isGitRepository(cwd);
@@ -237,6 +243,7 @@ const make = Effect.gen(function* () {
         fromCheckpointRef,
         toCheckpointRef: targetCheckpointRef,
         fallbackFromToHead: false,
+        ignoreWhitespace: false,
       })
       .pipe(
         Effect.map((diff) =>
@@ -330,8 +337,7 @@ const make = Effect.gen(function* () {
         return;
       }
 
-      const readModel = yield* orchestrationEngine.getReadModel();
-      const thread = readModel.threads.find((entry) => entry.id === event.threadId);
+      const thread = yield* resolveThreadDetail(event.threadId);
       if (!thread) {
         return;
       }
@@ -352,10 +358,11 @@ const make = Effect.gen(function* () {
         return;
       }
 
+      const projects = yield* resolveThreadProjects(thread.projectId);
       const checkpointCwd = yield* resolveCheckpointCwd({
         threadId: thread.id,
         thread,
-        projects: readModel.projects,
+        projects,
         preferSessionRuntime: true,
       });
       if (!checkpointCwd) {
@@ -406,8 +413,7 @@ const make = Effect.gen(function* () {
       return;
     }
 
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === threadId);
+    const thread = yield* resolveThreadDetail(threadId);
     if (!thread) {
       yield* Effect.logWarning("checkpoint capture from placeholder skipped: thread not found", {
         threadId,
@@ -428,10 +434,11 @@ const make = Effect.gen(function* () {
       return;
     }
 
+    const projects = yield* resolveThreadProjects(thread.projectId);
     const checkpointCwd = yield* resolveCheckpointCwd({
       threadId,
       thread,
-      projects: readModel.projects,
+      projects,
       preferSessionRuntime: true,
     });
     if (!checkpointCwd) {
@@ -457,16 +464,16 @@ const make = Effect.gen(function* () {
         return;
       }
 
-      const readModel = yield* orchestrationEngine.getReadModel();
-      const thread = readModel.threads.find((entry) => entry.id === event.threadId);
+      const thread = yield* resolveThreadDetail(event.threadId);
       if (!thread) {
         return;
       }
 
+      const projects = yield* resolveThreadProjects(thread.projectId);
       const checkpointCwd = yield* resolveCheckpointCwd({
         threadId: thread.id,
         thread,
-        projects: readModel.projects,
+        projects,
         preferSessionRuntime: false,
       });
       if (!checkpointCwd) {
@@ -508,7 +515,7 @@ const make = Effect.gen(function* () {
       return;
     }
 
-    yield* gitStatusBroadcaster.refreshLocalStatus(sessionRuntime.value.cwd).pipe(
+    yield* vcsStatusBroadcaster.refreshLocalStatus(sessionRuntime.value.cwd).pipe(
       Effect.catch((error) =>
         Effect.logWarning("failed to refresh local git status after turn completion", {
           threadId: event.threadId,
@@ -539,16 +546,16 @@ const make = Effect.gen(function* () {
     }
 
     const threadId = event.payload.threadId;
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === threadId);
+    const thread = yield* resolveThreadDetail(threadId);
     if (!thread) {
       return;
     }
 
+    const projects = yield* resolveThreadProjects(thread.projectId);
     const checkpointCwd = yield* resolveCheckpointCwd({
       threadId,
       thread,
-      projects: readModel.projects,
+      projects,
       preferSessionRuntime: false,
     });
     if (!checkpointCwd) {
@@ -584,10 +591,9 @@ const make = Effect.gen(function* () {
   const handleRevertRequested = Effect.fn("handleRevertRequested")(function* (
     event: Extract<OrchestrationEvent, { type: "thread.checkpoint-revert-requested" }>,
   ) {
-    const now = new Date().toISOString();
+    const now = DateTime.formatIso(yield* DateTime.now);
 
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === event.payload.threadId);
+    const thread = yield* resolveThreadDetail(event.payload.threadId);
     if (!thread) {
       yield* appendRevertFailureActivity({
         threadId: event.payload.threadId,
@@ -718,12 +724,14 @@ const make = Effect.gen(function* () {
     if (event.type === "thread.checkpoint-revert-requested") {
       yield* handleRevertRequested(event).pipe(
         Effect.catch((error) =>
-          appendRevertFailureActivity({
-            threadId: event.payload.threadId,
-            turnCount: event.payload.turnCount,
-            detail: error.message,
-            createdAt: new Date().toISOString(),
-          }),
+          Effect.flatMap(nowIso, (createdAt) =>
+            appendRevertFailureActivity({
+              threadId: event.payload.threadId,
+              turnCount: event.payload.turnCount,
+              detail: error.message,
+              createdAt,
+            }),
+          ),
         ),
       );
       return;
@@ -737,12 +745,14 @@ const make = Effect.gen(function* () {
     if (event.type === "thread.turn-diff-completed") {
       yield* captureCheckpointFromPlaceholder(event).pipe(
         Effect.catch((error) =>
-          appendCaptureFailureActivity({
-            threadId: event.payload.threadId,
-            turnId: event.payload.turnId,
-            detail: error.message,
-            createdAt: new Date().toISOString(),
-          }).pipe(Effect.catch(() => Effect.void)),
+          Effect.flatMap(nowIso, (createdAt) =>
+            appendCaptureFailureActivity({
+              threadId: event.payload.threadId,
+              turnId: event.payload.turnId,
+              detail: error.message,
+              createdAt,
+            }).pipe(Effect.catch(() => Effect.void)),
+          ),
         ),
       );
     }
@@ -761,12 +771,14 @@ const make = Effect.gen(function* () {
       yield* refreshLocalGitStatusFromTurnCompletion(event);
       yield* captureCheckpointFromTurnCompletion(event).pipe(
         Effect.catch((error) =>
-          appendCaptureFailureActivity({
-            threadId: event.threadId,
-            turnId,
-            detail: error.message,
-            createdAt: new Date().toISOString(),
-          }).pipe(Effect.catch(() => Effect.void)),
+          Effect.flatMap(nowIso, (createdAt) =>
+            appendCaptureFailureActivity({
+              threadId: event.threadId,
+              turnId,
+              detail: error.message,
+              createdAt,
+            }).pipe(Effect.catch(() => Effect.void)),
+          ),
         ),
       );
       return;
diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
index eaf66f3971d..7909d5cd6b1 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
@@ -7,8 +7,16 @@ import {
   ThreadId,
   TurnId,
   type OrchestrationEvent,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
-import { Effect, Layer, ManagedRuntime, Metric, Option, Queue, Stream } from "effect";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Metric from "effect/Metric";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
 import { describe, expect, it } from "vitest";
 
 import { PersistenceSqlError } from "../../persistence/Errors.ts";
@@ -30,7 +38,6 @@ import {
 } from "../Services/ProjectionPipeline.ts";
 import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import { ServerConfig } from "../../config.ts";
-import * as NodeServices from "@effect/platform-node/NodeServices";
 
 const asProjectId = (value: string): ProjectId => ProjectId.make(value);
 const asMessageId = (value: string): MessageId => MessageId.make(value);
@@ -41,9 +48,13 @@ async function createOrchestrationSystem() {
   const ServerConfigLayer = ServerConfig.layerTest(process.cwd(), {
     prefix: "t3-orchestration-engine-test-",
   });
-  const orchestrationLayer = OrchestrationEngineLive.pipe(
-    Layer.provide(OrchestrationProjectionSnapshotQueryLive),
-    Layer.provide(OrchestrationProjectionPipelineLive),
+  const orchestrationLayer = Layer.mergeAll(
+    OrchestrationEngineLive.pipe(
+      Layer.provide(OrchestrationProjectionSnapshotQueryLive),
+      Layer.provide(OrchestrationProjectionPipelineLive),
+    ),
+    OrchestrationProjectionSnapshotQueryLive,
+  ).pipe(
     Layer.provide(OrchestrationEventStoreLive),
     Layer.provide(OrchestrationCommandReceiptRepositoryLive),
     Layer.provide(RepositoryIdentityResolverLive),
@@ -53,15 +64,17 @@ async function createOrchestrationSystem() {
   );
   const runtime = ManagedRuntime.make(orchestrationLayer);
   const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
+  const snapshotQuery = await runtime.runPromise(Effect.service(ProjectionSnapshotQuery));
   return {
     engine,
+    readModel: () => runtime.runPromise(snapshotQuery.getSnapshot()),
     run: <A, E>(effect: Effect.Effect<A, E>) => runtime.runPromise(effect),
     dispose: () => runtime.dispose(),
   };
 }
 
 function now() {
-  return new Date().toISOString();
+  return "2026-01-01T00:00:00.000Z";
 }
 
 const hasMetricSnapshot = (
@@ -76,15 +89,18 @@ const hasMetricSnapshot = (
   );
 
 describe("OrchestrationEngine", () => {
-  it("bootstraps the in-memory read model from persisted projections", async () => {
-    const failOnHistoricalReplayStore: OrchestrationEventStoreShape = {
-      append: () =>
-        Effect.fail(
-          new PersistenceSqlError({
-            operation: "test.append",
-            detail: "append should not be called during bootstrap",
-          }),
-        ),
+  it("bootstraps command handling from persisted projections without reading the full snapshot", async () => {
+    let nextSequence = 8;
+    const eventStore: OrchestrationEventStoreShape = {
+      append: (event) =>
+        Effect.sync(() => {
+          const savedEvent = {
+            ...event,
+            sequence: nextSequence,
+          } as OrchestrationEvent;
+          nextSequence += 1;
+          return savedEvent;
+        }),
       readFromSequence: () => Stream.empty,
       readAll: () =>
         Stream.fail(
@@ -104,7 +120,7 @@ describe("OrchestrationEngine", () => {
           title: "Bootstrap Project",
           workspaceRoot: "/tmp/project-bootstrap",
           defaultModelSelection: {
-            provider: "codex" as const,
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           scripts: [],
@@ -119,7 +135,7 @@ describe("OrchestrationEngine", () => {
           projectId: asProjectId("project-bootstrap"),
           title: "Bootstrap Thread",
           modelSelection: {
-            provider: "codex" as const,
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -139,15 +155,51 @@ describe("OrchestrationEngine", () => {
         },
       ],
     };
+    const commandReadModel = {
+      ...projectionSnapshot,
+      threads: projectionSnapshot.threads.map((thread) => ({
+        ...thread,
+        messages: [],
+        proposedPlans: [],
+        activities: [],
+        checkpoints: [],
+      })),
+    };
+    let fullSnapshotReadCount = 0;
 
     const layer = OrchestrationEngineLive.pipe(
       Layer.provide(
         Layer.succeed(ProjectionSnapshotQuery, {
-          getSnapshot: () => Effect.succeed(projectionSnapshot),
+          getCommandReadModel: () => Effect.succeed(commandReadModel),
+          getSnapshot: () =>
+            Effect.sync(() => {
+              fullSnapshotReadCount += 1;
+              return projectionSnapshot;
+            }),
+          getShellSnapshot: () =>
+            Effect.succeed({
+              snapshotSequence: projectionSnapshot.snapshotSequence,
+              projects: [],
+              threads: [],
+              updatedAt: projectionSnapshot.updatedAt,
+            }),
+          getArchivedShellSnapshot: () =>
+            Effect.succeed({
+              snapshotSequence: projectionSnapshot.snapshotSequence,
+              projects: [],
+              threads: [],
+              updatedAt: projectionSnapshot.updatedAt,
+            }),
+          getSnapshotSequence: () =>
+            Effect.succeed({ snapshotSequence: projectionSnapshot.snapshotSequence }),
           getCounts: () => Effect.succeed({ projectCount: 1, threadCount: 1 }),
           getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.succeed(Option.none()),
           getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
           getThreadCheckpointContext: () => Effect.succeed(Option.none()),
+          getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
         }),
       ),
       Layer.provide(
@@ -156,7 +208,7 @@ describe("OrchestrationEngine", () => {
           projectEvent: () => Effect.void,
         } satisfies OrchestrationProjectionPipelineShape),
       ),
-      Layer.provide(Layer.succeed(OrchestrationEventStore, failOnHistoricalReplayStore)),
+      Layer.provide(Layer.succeed(OrchestrationEventStore, eventStore)),
       Layer.provide(OrchestrationCommandReceiptRepositoryLive),
       Layer.provide(SqlitePersistenceMemory),
     );
@@ -164,18 +216,22 @@ describe("OrchestrationEngine", () => {
     const runtime = ManagedRuntime.make(layer);
 
     const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
-    const readModel = await runtime.runPromise(engine.getReadModel());
+    const result = await runtime.runPromise(
+      engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-bootstrap-thread-update"),
+        threadId: ThreadId.make("thread-bootstrap"),
+        title: "Updated Bootstrap Thread",
+      }),
+    );
 
-    expect(readModel.snapshotSequence).toBe(7);
-    expect(readModel.projects).toHaveLength(1);
-    expect(readModel.projects[0]?.title).toBe("Bootstrap Project");
-    expect(readModel.threads).toHaveLength(1);
-    expect(readModel.threads[0]?.title).toBe("Bootstrap Thread");
+    expect(result.sequence).toBe(8);
+    expect(fullSnapshotReadCount).toBe(0);
 
     await runtime.dispose();
   });
 
-  it("returns deterministic read models for repeated reads", async () => {
+  it("persists deterministic read models for repeated snapshot reads", async () => {
     const createdAt = now();
     const system = await createOrchestrationSystem();
     const { engine } = system;
@@ -188,7 +244,7 @@ describe("OrchestrationEngine", () => {
         title: "Project 1",
         workspaceRoot: "/tmp/project-1",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -202,7 +258,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-1"),
         title: "Thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -229,8 +285,8 @@ describe("OrchestrationEngine", () => {
       }),
     );
 
-    const readModelA = await system.run(engine.getReadModel());
-    const readModelB = await system.run(engine.getReadModel());
+    const readModelA = await system.readModel();
+    const readModelB = await system.readModel();
     expect(readModelB).toEqual(readModelA);
     await system.dispose();
   });
@@ -248,7 +304,7 @@ describe("OrchestrationEngine", () => {
         title: "Project Archive",
         workspaceRoot: "/tmp/project-archive",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -262,7 +318,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-archive"),
         title: "Archive me",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -281,9 +337,8 @@ describe("OrchestrationEngine", () => {
       }),
     );
     expect(
-      (await system.run(engine.getReadModel())).threads.find(
-        (thread) => thread.id === "thread-archive",
-      )?.archivedAt,
+      (await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
+        ?.archivedAt,
     ).not.toBeNull();
 
     await system.run(
@@ -294,9 +349,8 @@ describe("OrchestrationEngine", () => {
       }),
     );
     expect(
-      (await system.run(engine.getReadModel())).threads.find(
-        (thread) => thread.id === "thread-archive",
-      )?.archivedAt,
+      (await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
+        ?.archivedAt,
     ).toBeNull();
 
     await system.dispose();
@@ -315,7 +369,7 @@ describe("OrchestrationEngine", () => {
         title: "Replay Project",
         workspaceRoot: "/tmp/project-replay",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -329,7 +383,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-replay"),
         title: "replay",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -373,7 +427,7 @@ describe("OrchestrationEngine", () => {
         title: "Stream Project",
         workspaceRoot: "/tmp/project-stream",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -397,7 +451,7 @@ describe("OrchestrationEngine", () => {
           projectId: asProjectId("project-stream"),
           title: "domain-stream",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -434,7 +488,7 @@ describe("OrchestrationEngine", () => {
         title: "Ack Project",
         workspaceRoot: "/tmp/project-ack",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -449,7 +503,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-ack"),
         title: "Ack Thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -486,7 +540,7 @@ describe("OrchestrationEngine", () => {
           projectId: asProjectId("project-missing"),
           title: "Missing Project Thread",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -523,7 +577,7 @@ describe("OrchestrationEngine", () => {
         title: "Turn Diff Project",
         workspaceRoot: "/tmp/project-turn-diff",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -537,7 +591,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-turn-diff"),
         title: "Turn diff thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -562,7 +616,7 @@ describe("OrchestrationEngine", () => {
       }),
     );
 
-    const thread = (await system.run(engine.getReadModel())).threads.find(
+    const thread = (await system.readModel()).threads.find(
       (entry) => entry.id === "thread-turn-diff",
     );
     expect(thread?.checkpoints).toEqual([
@@ -642,7 +696,7 @@ describe("OrchestrationEngine", () => {
         title: "Flaky Project",
         workspaceRoot: "/tmp/project-flaky",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -658,7 +712,7 @@ describe("OrchestrationEngine", () => {
           projectId: asProjectId("project-flaky"),
           title: "flaky-fail",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -678,7 +732,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-flaky"),
         title: "flaky-ok",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -690,7 +744,15 @@ describe("OrchestrationEngine", () => {
     );
 
     expect(result.sequence).toBe(2);
-    expect((await runtime.runPromise(engine.getReadModel())).snapshotSequence).toBe(2);
+    const eventsAfterRetry = await runtime.runPromise(
+      Stream.runCollect(engine.readEvents(0)).pipe(
+        Effect.map((chunk): OrchestrationEvent[] => Array.from(chunk)),
+      ),
+    );
+    expect(eventsAfterRetry.map((event) => event.type)).toEqual([
+      "project.created",
+      "thread.created",
+    ]);
     await runtime.dispose();
   });
 
@@ -724,6 +786,7 @@ describe("OrchestrationEngine", () => {
         Layer.provide(OrchestrationCommandReceiptRepositoryLive),
         Layer.provide(RepositoryIdentityResolverLive),
         Layer.provide(SqlitePersistenceMemory),
+        Layer.provide(NodeServices.layer),
       ),
     );
     const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
@@ -737,7 +800,7 @@ describe("OrchestrationEngine", () => {
         title: "Atomic Project",
         workspaceRoot: "/tmp/project-atomic",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -751,7 +814,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-atomic"),
         title: "atomic",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -790,7 +853,6 @@ describe("OrchestrationEngine", () => {
       "project.created",
       "thread.created",
     ]);
-    expect((await runtime.runPromise(engine.getReadModel())).snapshotSequence).toBe(2);
 
     const retryResult = await runtime.runPromise(engine.dispatch(turnStartCommand));
     expect(retryResult.sequence).toBe(4);
@@ -813,7 +875,7 @@ describe("OrchestrationEngine", () => {
     await runtime.dispose();
   });
 
-  it("reconciles in-memory state when append persists but projection fails", async () => {
+  it("reconciles command state when append persists but projection fails", async () => {
     type StoredEvent =
       ReturnType<OrchestrationEventStoreShape["append"]> extends Effect.Effect<infer A, any, any>
         ? A
@@ -845,7 +907,7 @@ describe("OrchestrationEngine", () => {
       projectEvent: (event) => {
         if (
           shouldFailProjection &&
-          event.commandId === CommandId.make("cmd-thread-meta-sync-fail")
+          event.commandId === CommandId.make("cmd-thread-archive-sync-fail")
         ) {
           shouldFailProjection = false;
           return Effect.fail(
@@ -867,6 +929,7 @@ describe("OrchestrationEngine", () => {
         Layer.provide(OrchestrationCommandReceiptRepositoryLive),
         Layer.provide(RepositoryIdentityResolverLive),
         Layer.provide(SqlitePersistenceMemory),
+        Layer.provide(NodeServices.layer),
       ),
     );
     const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
@@ -880,7 +943,7 @@ describe("OrchestrationEngine", () => {
         title: "Sync Project",
         workspaceRoot: "/tmp/project-sync",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -894,7 +957,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-sync"),
         title: "sync-before",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -908,20 +971,22 @@ describe("OrchestrationEngine", () => {
     await expect(
       runtime.runPromise(
         engine.dispatch({
-          type: "thread.meta.update",
-          commandId: CommandId.make("cmd-thread-meta-sync-fail"),
+          type: "thread.archive",
+          commandId: CommandId.make("cmd-thread-archive-sync-fail"),
           threadId: ThreadId.make("thread-sync"),
-          title: "sync-after-failed-projection",
         }),
       ),
     ).rejects.toThrow("projection failed");
 
-    const readModelAfterFailure = await runtime.runPromise(engine.getReadModel());
-    const updatedThread = readModelAfterFailure.threads.find(
-      (thread) => thread.id === "thread-sync",
-    );
-    expect(readModelAfterFailure.snapshotSequence).toBe(3);
-    expect(updatedThread?.title).toBe("sync-after-failed-projection");
+    await expect(
+      runtime.runPromise(
+        engine.dispatch({
+          type: "thread.archive",
+          commandId: CommandId.make("cmd-thread-archive-sync-retry"),
+          threadId: ThreadId.make("thread-sync"),
+        }),
+      ),
+    ).rejects.toThrow("already archived");
 
     await runtime.dispose();
   });
@@ -965,7 +1030,7 @@ describe("OrchestrationEngine", () => {
         title: "Duplicate Project",
         workspaceRoot: "/tmp/project-duplicate",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -980,7 +1045,7 @@ describe("OrchestrationEngine", () => {
         projectId: asProjectId("project-duplicate"),
         title: "duplicate",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -1000,7 +1065,7 @@ describe("OrchestrationEngine", () => {
           projectId: asProjectId("project-duplicate"),
           title: "duplicate",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.ts
index ddd1718faf0..cf8407bd212 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.ts
@@ -5,20 +5,20 @@ import type {
   ThreadId,
 } from "@t3tools/contracts";
 import { OrchestrationCommand } from "@t3tools/contracts";
-import {
-  Cause,
-  Deferred,
-  Duration,
-  Effect,
-  Exit,
-  Layer,
-  Metric,
-  Option,
-  PubSub,
-  Queue,
-  Schema,
-  Stream,
-} from "effect";
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Metric from "effect/Metric";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import {
@@ -34,6 +34,7 @@ import {
   OrchestrationCommandInvariantError,
   OrchestrationCommandPreviouslyRejectedError,
   type OrchestrationDispatchError,
+  type OrchestrationProjectorDecodeError,
 } from "../Errors.ts";
 import { decideOrchestrationCommand } from "../decider.ts";
 import { createEmptyReadModel, projectEvent } from "../projector.ts";
@@ -43,6 +44,10 @@ import {
   OrchestrationEngineService,
   type OrchestrationEngineShape,
 } from "../Services/OrchestrationEngine.ts";
+const isOrchestrationCommandPreviouslyRejectedError = Schema.is(
+  OrchestrationCommandPreviouslyRejectedError,
+);
+const isOrchestrationCommandInvariantError = Schema.is(OrchestrationCommandInvariantError);
 
 interface CommandEnvelope {
   command: OrchestrationCommand;
@@ -77,14 +82,27 @@ const makeOrchestrationEngine = Effect.gen(function* () {
   const projectionPipeline = yield* OrchestrationProjectionPipeline;
   const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
 
-  let readModel = createEmptyReadModel(new Date().toISOString());
+  const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+  let commandReadModel = createEmptyReadModel(yield* nowIso);
 
   const commandQueue = yield* Queue.unbounded<CommandEnvelope>();
   const eventPubSub = yield* PubSub.unbounded<OrchestrationEvent>();
 
+  const projectEventsOntoReadModel = (
+    baseReadModel: OrchestrationReadModel,
+    events: ReadonlyArray<OrchestrationEvent>,
+  ): Effect.Effect<OrchestrationReadModel, OrchestrationProjectorDecodeError, never> =>
+    Effect.gen(function* () {
+      let nextReadModel = baseReadModel;
+      for (const event of events) {
+        nextReadModel = yield* projectEvent(nextReadModel, event);
+      }
+      return nextReadModel;
+    });
+
   const processEnvelope = (envelope: CommandEnvelope): Effect.Effect<void> => {
-    const dispatchStartSequence = readModel.snapshotSequence;
-    const processingStartedAtMs = Date.now();
+    const dispatchStartSequence = commandReadModel.snapshotSequence;
+    let processingStartedAtMs = 0;
     const aggregateRef = commandToAggregateRef(envelope.command);
     const baseMetricAttributes = {
       commandType: envelope.command.type,
@@ -98,11 +116,7 @@ const makeOrchestrationEngine = Effect.gen(function* () {
         return;
       }
 
-      let nextReadModel = readModel;
-      for (const persistedEvent of persistedEvents) {
-        nextReadModel = yield* projectEvent(nextReadModel, persistedEvent);
-      }
-      readModel = nextReadModel;
+      commandReadModel = yield* projectEventsOntoReadModel(commandReadModel, persistedEvents);
 
       for (const persistedEvent of persistedEvents) {
         yield* PubSub.publish(eventPubSub, persistedEvent);
@@ -111,6 +125,7 @@ const makeOrchestrationEngine = Effect.gen(function* () {
 
     return Effect.exit(
       Effect.gen(function* () {
+        processingStartedAtMs = yield* Clock.currentTimeMillis;
         yield* Effect.annotateCurrentSpan({
           "orchestration.command_id": envelope.command.commandId,
           "orchestration.command_type": envelope.command.type,
@@ -135,18 +150,18 @@ const makeOrchestrationEngine = Effect.gen(function* () {
 
         const eventBase = yield* decideOrchestrationCommand({
           command: envelope.command,
-          readModel,
+          readModel: commandReadModel,
         });
         const eventBases = Array.isArray(eventBase) ? eventBase : [eventBase];
         const committedCommand = yield* sql
           .withTransaction(
             Effect.gen(function* () {
               const committedEvents: OrchestrationEvent[] = [];
-              let nextReadModel = readModel;
+              let nextCommandReadModel = commandReadModel;
 
               for (const nextEvent of eventBases) {
                 const savedEvent = yield* eventStore.append(nextEvent);
-                nextReadModel = yield* projectEvent(nextReadModel, savedEvent);
+                nextCommandReadModel = yield* projectEvent(nextCommandReadModel, savedEvent);
                 yield* projectionPipeline.projectEvent(savedEvent);
                 committedEvents.push(savedEvent);
               }
@@ -172,7 +187,7 @@ const makeOrchestrationEngine = Effect.gen(function* () {
               return {
                 committedEvents,
                 lastSequence: lastSavedEvent.sequence,
-                nextReadModel,
+                nextCommandReadModel,
               } as const;
             }),
           )
@@ -184,7 +199,7 @@ const makeOrchestrationEngine = Effect.gen(function* () {
             ),
           );
 
-        readModel = committedCommand.nextReadModel;
+        commandReadModel = committedCommand.nextCommandReadModel;
         for (const [index, event] of committedCommand.committedEvents.entries()) {
           yield* PubSub.publish(eventPubSub, event);
           if (index === 0) {
@@ -196,7 +211,7 @@ const makeOrchestrationEngine = Effect.gen(function* () {
                   ackEventType: event.type,
                 }),
               ),
-              Duration.millis(Math.max(0, Date.now() - envelope.startedAtMs)),
+              Duration.millis(Math.max(0, (yield* Clock.currentTimeMillis) - envelope.startedAtMs)),
             );
           }
         }
@@ -215,7 +230,7 @@ const makeOrchestrationEngine = Effect.gen(function* () {
               orchestrationCommandDuration,
               metricAttributes(baseMetricAttributes),
             ),
-            Duration.millis(Math.max(0, Date.now() - processingStartedAtMs)),
+            Duration.millis(Math.max(0, (yield* Clock.currentTimeMillis) - processingStartedAtMs)),
           );
           yield* Metric.update(
             Metric.withAttributes(
@@ -234,7 +249,7 @@ const makeOrchestrationEngine = Effect.gen(function* () {
           }
 
           const error = Cause.squash(exit.cause) as OrchestrationDispatchError;
-          if (!Schema.is(OrchestrationCommandPreviouslyRejectedError)(error)) {
+          if (!isOrchestrationCommandPreviouslyRejectedError(error)) {
             yield* reconcileReadModelAfterDispatchFailure.pipe(
               Effect.catch(() =>
                 Effect.logWarning(
@@ -242,20 +257,20 @@ const makeOrchestrationEngine = Effect.gen(function* () {
                 ).pipe(
                   Effect.annotateLogs({
                     commandId: envelope.command.commandId,
-                    snapshotSequence: readModel.snapshotSequence,
+                    snapshotSequence: commandReadModel.snapshotSequence,
                   }),
                 ),
               ),
             );
 
-            if (Schema.is(OrchestrationCommandInvariantError)(error)) {
+            if (isOrchestrationCommandInvariantError(error)) {
               yield* commandReceiptRepository
                 .upsert({
                   commandId: envelope.command.commandId,
                   aggregateKind: aggregateRef.aggregateKind,
                   aggregateId: aggregateRef.aggregateId,
-                  acceptedAt: new Date().toISOString(),
-                  resultSequence: readModel.snapshotSequence,
+                  acceptedAt: yield* nowIso,
+                  resultSequence: commandReadModel.snapshotSequence,
                   status: "rejected",
                   error: error.message,
                 })
@@ -270,29 +285,29 @@ const makeOrchestrationEngine = Effect.gen(function* () {
   };
 
   yield* projectionPipeline.bootstrap;
-  readModel = yield* projectionSnapshotQuery.getSnapshot();
+  commandReadModel = yield* projectionSnapshotQuery.getCommandReadModel();
 
   const worker = Effect.forever(Queue.take(commandQueue).pipe(Effect.flatMap(processEnvelope)));
   yield* Effect.forkScoped(worker);
   yield* Effect.logDebug("orchestration engine started").pipe(
-    Effect.annotateLogs({ sequence: readModel.snapshotSequence }),
+    Effect.annotateLogs({ sequence: commandReadModel.snapshotSequence }),
   );
 
-  const getReadModel: OrchestrationEngineShape["getReadModel"] = () =>
-    Effect.sync((): OrchestrationReadModel => readModel);
-
   const readEvents: OrchestrationEngineShape["readEvents"] = (fromSequenceExclusive) =>
     eventStore.readFromSequence(fromSequenceExclusive);
 
   const dispatch: OrchestrationEngineShape["dispatch"] = (command) =>
     Effect.gen(function* () {
       const result = yield* Deferred.make<{ sequence: number }, OrchestrationDispatchError>();
-      yield* Queue.offer(commandQueue, { command, result, startedAtMs: Date.now() });
+      yield* Queue.offer(commandQueue, {
+        command,
+        result,
+        startedAtMs: yield* Clock.currentTimeMillis,
+      });
       return yield* Deferred.await(result);
     });
 
   return {
-    getReadModel,
     readEvents,
     dispatch,
     // Each access creates a fresh PubSub subscription so that multiple
diff --git a/apps/server/src/orchestration/Layers/OrchestrationReactor.test.ts b/apps/server/src/orchestration/Layers/OrchestrationReactor.test.ts
index d60f0cf7220..6155af8858a 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationReactor.test.ts
@@ -1,9 +1,14 @@
-import { Effect, Exit, Layer, ManagedRuntime, Scope } from "effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Scope from "effect/Scope";
 import { afterEach, describe, expect, it } from "vitest";
 
 import { CheckpointReactor } from "../Services/CheckpointReactor.ts";
 import { ProviderCommandReactor } from "../Services/ProviderCommandReactor.ts";
 import { ProviderRuntimeIngestionService } from "../Services/ProviderRuntimeIngestion.ts";
+import { ThreadDeletionReactor } from "../Services/ThreadDeletionReactor.ts";
 import { OrchestrationReactor } from "../Services/OrchestrationReactor.ts";
 import { makeOrchestrationReactor } from "./OrchestrationReactor.ts";
 
@@ -17,7 +22,7 @@ describe("OrchestrationReactor", () => {
     runtime = null;
   });
 
-  it("starts provider ingestion, provider command, and checkpoint reactors", async () => {
+  it("starts provider ingestion, provider command, checkpoint, and thread deletion reactors", async () => {
     const started: string[] = [];
 
     runtime = ManagedRuntime.make(
@@ -49,10 +54,19 @@ describe("OrchestrationReactor", () => {
             drain: Effect.void,
           }),
         ),
+        Layer.provideMerge(
+          Layer.succeed(ThreadDeletionReactor, {
+            start: () => {
+              started.push("thread-deletion-reactor");
+              return Effect.void;
+            },
+            drain: Effect.void,
+          }),
+        ),
       ),
     );
 
-    const reactor = await runtime.runPromise(Effect.service(OrchestrationReactor));
+    const reactor = await runtime!.runPromise(Effect.service(OrchestrationReactor));
     const scope = await Effect.runPromise(Scope.make("sequential"));
     await Effect.runPromise(reactor.start().pipe(Scope.provide(scope)));
 
@@ -60,6 +74,7 @@ describe("OrchestrationReactor", () => {
       "provider-runtime-ingestion",
       "provider-command-reactor",
       "checkpoint-reactor",
+      "thread-deletion-reactor",
     ]);
 
     await Effect.runPromise(Scope.close(scope, Exit.void));
diff --git a/apps/server/src/orchestration/Layers/OrchestrationReactor.ts b/apps/server/src/orchestration/Layers/OrchestrationReactor.ts
index 99d30c57a2e..5e432d9884f 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationReactor.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationReactor.ts
@@ -1,4 +1,5 @@
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import {
   OrchestrationReactor,
@@ -7,16 +8,19 @@ import {
 import { CheckpointReactor } from "../Services/CheckpointReactor.ts";
 import { ProviderCommandReactor } from "../Services/ProviderCommandReactor.ts";
 import { ProviderRuntimeIngestionService } from "../Services/ProviderRuntimeIngestion.ts";
+import { ThreadDeletionReactor } from "../Services/ThreadDeletionReactor.ts";
 
 export const makeOrchestrationReactor = Effect.gen(function* () {
   const providerRuntimeIngestion = yield* ProviderRuntimeIngestionService;
   const providerCommandReactor = yield* ProviderCommandReactor;
   const checkpointReactor = yield* CheckpointReactor;
+  const threadDeletionReactor = yield* ThreadDeletionReactor;
 
   const start: OrchestrationReactorShape["start"] = Effect.fn("start")(function* () {
     yield* providerRuntimeIngestion.start();
     yield* providerCommandReactor.start();
     yield* checkpointReactor.start();
+    yield* threadDeletionReactor.start();
   });
 
   return {
diff --git a/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
index 0796cb49056..369eea0f7a0 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
@@ -7,10 +7,14 @@ import {
   ProjectId,
   ThreadId,
   TurnId,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { OrchestrationCommandReceiptRepositoryLive } from "../../persistence/Layers/OrchestrationCommandReceipts.ts";
@@ -54,7 +58,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
       const eventStore = yield* OrchestrationEventStore;
       const sql = yield* SqlClient.SqlClient;
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
 
       yield* eventStore.append({
         type: "project.created",
@@ -92,7 +96,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           projectId: ProjectId.make("project-1"),
           title: "Thread 1",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "full-access",
@@ -179,7 +183,7 @@ it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-base-")))(
         const projectionPipeline = yield* OrchestrationProjectionPipeline;
         const eventStore = yield* OrchestrationEventStore;
         const sql = yield* SqlClient.SqlClient;
-        const now = new Date().toISOString();
+        const now = "2026-01-01T00:00:00.000Z";
 
         yield* eventStore.append({
           type: "thread.message-sent",
@@ -223,6 +227,7 @@ it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-base-")))(
             WHERE message_id = 'message-attachments'
           `;
         assert.equal(rows.length, 1);
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         assert.deepEqual(JSON.parse(rows[0]?.attachmentsJson ?? "null"), [
           {
             type: "image",
@@ -245,7 +250,7 @@ it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-projection-atta
         const projectionPipeline = yield* OrchestrationProjectionPipeline;
         const eventStore = yield* OrchestrationEventStore;
         const sql = yield* SqlClient.SqlClient;
-        const now = new Date().toISOString();
+        const now = "2026-01-01T00:00:00.000Z";
 
         yield* eventStore.append({
           type: "thread.message-sent",
@@ -296,6 +301,7 @@ it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-projection-atta
             WHERE message_id = 'message-attachments-safe'
           `;
         assert.equal(rows.length, 1);
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         assert.deepEqual(JSON.parse(rows[0]?.attachmentsJson ?? "null"), [
           {
             type: "image",
@@ -325,8 +331,8 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
         const projectionPipeline = yield* OrchestrationProjectionPipeline;
         const eventStore = yield* OrchestrationEventStore;
         const sql = yield* SqlClient.SqlClient;
-        const now = new Date().toISOString();
-        const later = new Date(Date.now() + 1_000).toISOString();
+        const now = "2026-01-01T00:00:00.000Z";
+        const later = "2026-01-01T00:00:01.000Z";
 
         yield* eventStore.append({
           type: "project.created",
@@ -364,7 +370,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
             projectId: ProjectId.make("project-clear-attachments"),
             title: "Thread Clear Attachments",
             modelSelection: {
-              provider: "codex",
+              instanceId: ProviderInstanceId.make("codex"),
               model: "gpt-5-codex",
             },
             runtimeMode: "full-access",
@@ -440,6 +446,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           WHERE message_id = 'message-clear-attachments'
         `;
         assert.equal(rows.length, 1);
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         assert.deepEqual(JSON.parse(rows[0]?.attachmentsJson ?? "null"), []);
       }),
   );
@@ -453,8 +460,8 @@ it.layer(
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
       const eventStore = yield* OrchestrationEventStore;
       const sql = yield* SqlClient.SqlClient;
-      const now = new Date().toISOString();
-      const later = new Date(Date.now() + 1_000).toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
+      const later = "2026-01-01T00:00:01.000Z";
 
       yield* eventStore.append({
         type: "project.created",
@@ -492,7 +499,7 @@ it.layer(
           projectId: ProjectId.make("project-overwrite"),
           title: "Thread Overwrite",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "full-access",
@@ -575,6 +582,7 @@ it.layer(
               WHERE message_id = 'message-overwrite'
             `;
       assert.equal(rows.length, 1);
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
       assert.deepEqual(JSON.parse(rows[0]?.attachmentsJson ?? "null"), [
         {
           type: "image",
@@ -597,7 +605,7 @@ it.layer(
       const eventStore = yield* OrchestrationEventStore;
       const path = yield* Path.Path;
       const sql = yield* SqlClient.SqlClient;
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
 
       const appendAndProject = (event: Parameters<typeof eventStore.append>[0]) =>
         eventStore
@@ -640,7 +648,7 @@ it.layer(
           projectId: ProjectId.make("project-rollback"),
           title: "Thread Rollback",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "full-access",
@@ -721,7 +729,7 @@ it.layer(
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
       const eventStore = yield* OrchestrationEventStore;
       const { attachmentsDir } = yield* ServerConfig;
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
       const threadId = ThreadId.make("Thread Revert.Files");
       const keepAttachmentId = "thread-revert-files-00000000-0000-4000-8000-000000000001";
       const removeAttachmentId = "thread-revert-files-00000000-0000-4000-8000-000000000002";
@@ -769,7 +777,7 @@ it.layer(
           projectId: ProjectId.make("project-revert-files"),
           title: "Thread Revert Files",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "full-access",
@@ -930,7 +938,7 @@ it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-projection-atta
         const projectionPipeline = yield* OrchestrationProjectionPipeline;
         const eventStore = yield* OrchestrationEventStore;
         const { attachmentsDir } = yield* ServerConfig;
-        const now = new Date().toISOString();
+        const now = "2026-01-01T00:00:00.000Z";
         const threadId = ThreadId.make("Thread Delete.Files");
         const attachmentId = "thread-delete-files-00000000-0000-4000-8000-000000000001";
         const otherThreadAttachmentId =
@@ -977,7 +985,7 @@ it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-projection-atta
             projectId: ProjectId.make("project-delete-files"),
             title: "Thread Delete Files",
             modelSelection: {
-              provider: "codex",
+              instanceId: ProviderInstanceId.make("codex"),
               model: "gpt-5-codex",
             },
             runtimeMode: "full-access",
@@ -1062,7 +1070,7 @@ it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-projection-atta
         const path = yield* Path.Path;
         const projectionPipeline = yield* OrchestrationProjectionPipeline;
         const eventStore = yield* OrchestrationEventStore;
-        const now = new Date().toISOString();
+        const now = "2026-01-01T00:00:00.000Z";
         const { attachmentsDir: attachmentsRootDir, stateDir } = yield* ServerConfig;
         const attachmentsSentinelPath = path.join(attachmentsRootDir, "sentinel.txt");
         const stateDirSentinelPath = path.join(stateDir, "state-sentinel.txt");
@@ -1102,7 +1110,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
       const eventStore = yield* OrchestrationEventStore;
       const sql = yield* SqlClient.SqlClient;
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
 
       yield* eventStore.append({
         type: "project.created",
@@ -1140,7 +1148,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           projectId: ProjectId.make("project-a"),
           title: "Thread A",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "full-access",
@@ -1229,7 +1237,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
       const eventStore = yield* OrchestrationEventStore;
       const sql = yield* SqlClient.SqlClient;
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
 
       yield* eventStore.append({
         type: "project.created",
@@ -1267,7 +1275,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           projectId: ProjectId.make("project-empty"),
           title: "Thread Empty",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "full-access",
@@ -1407,7 +1415,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
             projectId: ProjectId.make("project-conflict"),
             title: "Thread Conflict",
             modelSelection: {
-              provider: "codex",
+              instanceId: ProviderInstanceId.make("codex"),
               model: "gpt-5-codex",
             },
             runtimeMode: "full-access",
@@ -1505,6 +1513,329 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
       }),
   );
 
+  it.effect("clears stale pending approvals from projected shell summaries", () =>
+    Effect.gen(function* () {
+      const projectionPipeline = yield* OrchestrationProjectionPipeline;
+      const eventStore = yield* OrchestrationEventStore;
+      const sql = yield* SqlClient.SqlClient;
+      const appendAndProject = (event: Parameters<typeof eventStore.append>[0]) =>
+        eventStore
+          .append(event)
+          .pipe(Effect.flatMap((savedEvent) => projectionPipeline.projectEvent(savedEvent)));
+
+      yield* appendAndProject({
+        type: "project.created",
+        eventId: EventId.make("evt-stale-approval-1"),
+        aggregateKind: "project",
+        aggregateId: ProjectId.make("project-stale-approval"),
+        occurredAt: "2026-02-26T12:30:00.000Z",
+        commandId: CommandId.make("cmd-stale-approval-1"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-stale-approval-1"),
+        metadata: {},
+        payload: {
+          projectId: ProjectId.make("project-stale-approval"),
+          title: "Project Stale Approval",
+          workspaceRoot: "/tmp/project-stale-approval",
+          defaultModelSelection: null,
+          scripts: [],
+          createdAt: "2026-02-26T12:30:00.000Z",
+          updatedAt: "2026-02-26T12:30:00.000Z",
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.created",
+        eventId: EventId.make("evt-stale-approval-2"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-stale-approval"),
+        occurredAt: "2026-02-26T12:30:01.000Z",
+        commandId: CommandId.make("cmd-stale-approval-2"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-stale-approval-2"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-stale-approval"),
+          projectId: ProjectId.make("project-stale-approval"),
+          title: "Thread Stale Approval",
+          modelSelection: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: "gpt-5-codex",
+          },
+          runtimeMode: "approval-required",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt: "2026-02-26T12:30:01.000Z",
+          updatedAt: "2026-02-26T12:30:01.000Z",
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.activity-appended",
+        eventId: EventId.make("evt-stale-approval-3"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-stale-approval"),
+        occurredAt: "2026-02-26T12:30:02.000Z",
+        commandId: CommandId.make("cmd-stale-approval-3"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-stale-approval-3"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-stale-approval"),
+          activity: {
+            id: EventId.make("activity-stale-approval-requested"),
+            tone: "approval",
+            kind: "approval.requested",
+            summary: "Command approval requested",
+            payload: {
+              requestId: "approval-request-stale-1",
+              requestKind: "command",
+            },
+            turnId: null,
+            createdAt: "2026-02-26T12:30:02.000Z",
+          },
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.activity-appended",
+        eventId: EventId.make("evt-stale-approval-4"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-stale-approval"),
+        occurredAt: "2026-02-26T12:30:03.000Z",
+        commandId: CommandId.make("cmd-stale-approval-4"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-stale-approval-4"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-stale-approval"),
+          activity: {
+            id: EventId.make("activity-stale-approval-failed"),
+            tone: "error",
+            kind: "provider.approval.respond.failed",
+            summary: "Provider approval response failed",
+            payload: {
+              requestId: "approval-request-stale-1",
+              detail: "Unknown pending permission request: approval-request-stale-1",
+            },
+            turnId: null,
+            createdAt: "2026-02-26T12:30:03.000Z",
+          },
+        },
+      });
+
+      const approvalRows = yield* sql<{
+        readonly requestId: string;
+        readonly status: string;
+        readonly resolvedAt: string | null;
+      }>`
+        SELECT
+          request_id AS "requestId",
+          status,
+          resolved_at AS "resolvedAt"
+        FROM projection_pending_approvals
+        WHERE request_id = 'approval-request-stale-1'
+      `;
+      assert.deepEqual(approvalRows, [
+        {
+          requestId: "approval-request-stale-1",
+          status: "resolved",
+          resolvedAt: "2026-02-26T12:30:03.000Z",
+        },
+      ]);
+
+      const threadRows = yield* sql<{
+        readonly pendingApprovalCount: number;
+      }>`
+        SELECT pending_approval_count AS "pendingApprovalCount"
+        FROM projection_threads
+        WHERE thread_id = 'thread-stale-approval'
+      `;
+      assert.deepEqual(threadRows, [{ pendingApprovalCount: 0 }]);
+    }),
+  );
+
+  it.effect("ignores non-stale provider approval response failures", () =>
+    Effect.gen(function* () {
+      const projectionPipeline = yield* OrchestrationProjectionPipeline;
+      const eventStore = yield* OrchestrationEventStore;
+      const sql = yield* SqlClient.SqlClient;
+      const appendAndProject = (event: Parameters<typeof eventStore.append>[0]) =>
+        eventStore
+          .append(event)
+          .pipe(Effect.flatMap((savedEvent) => projectionPipeline.projectEvent(savedEvent)));
+
+      yield* appendAndProject({
+        type: "project.created",
+        eventId: EventId.make("evt-nonstale-approval-1"),
+        aggregateKind: "project",
+        aggregateId: ProjectId.make("project-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:00.000Z",
+        commandId: CommandId.make("cmd-nonstale-approval-1"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-1"),
+        metadata: {},
+        payload: {
+          projectId: ProjectId.make("project-nonstale-approval"),
+          title: "Project Non-Stale Approval",
+          workspaceRoot: "/tmp/project-nonstale-approval",
+          defaultModelSelection: null,
+          scripts: [],
+          createdAt: "2026-02-26T12:45:00.000Z",
+          updatedAt: "2026-02-26T12:45:00.000Z",
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.created",
+        eventId: EventId.make("evt-nonstale-approval-2"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:01.000Z",
+        commandId: CommandId.make("cmd-nonstale-approval-2"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-2"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-nonstale-approval"),
+          projectId: ProjectId.make("project-nonstale-approval"),
+          title: "Thread Non-Stale Approval",
+          modelSelection: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: "gpt-5-codex",
+          },
+          runtimeMode: "approval-required",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt: "2026-02-26T12:45:01.000Z",
+          updatedAt: "2026-02-26T12:45:01.000Z",
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.activity-appended",
+        eventId: EventId.make("evt-nonstale-approval-3"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:02.000Z",
+        commandId: CommandId.make("cmd-nonstale-approval-3"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-3"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-nonstale-approval"),
+          activity: {
+            id: EventId.make("activity-nonstale-approval-requested"),
+            tone: "approval",
+            kind: "approval.requested",
+            summary: "Command approval requested",
+            payload: {
+              requestId: "approval-request-nonstale-existing",
+              requestKind: "command",
+            },
+            turnId: null,
+            createdAt: "2026-02-26T12:45:02.000Z",
+          },
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.activity-appended",
+        eventId: EventId.make("evt-nonstale-approval-4"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:03.000Z",
+        commandId: CommandId.make("cmd-nonstale-approval-4"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-4"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-nonstale-approval"),
+          activity: {
+            id: EventId.make("activity-nonstale-approval-failed-existing"),
+            tone: "error",
+            kind: "provider.approval.respond.failed",
+            summary: "Provider approval response failed",
+            payload: {
+              requestId: "approval-request-nonstale-existing",
+              detail: "Provider timed out while responding to approval request",
+            },
+            turnId: TurnId.make("turn-nonstale-failure"),
+            createdAt: "2026-02-26T12:45:03.000Z",
+          },
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.activity-appended",
+        eventId: EventId.make("evt-nonstale-approval-5"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:04.000Z",
+        commandId: CommandId.make("cmd-nonstale-approval-5"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-5"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-nonstale-approval"),
+          activity: {
+            id: EventId.make("activity-nonstale-approval-failed-missing"),
+            tone: "error",
+            kind: "provider.approval.respond.failed",
+            summary: "Provider approval response failed",
+            payload: {
+              requestId: "approval-request-nonstale-missing",
+              detail: "Provider timed out while responding to approval request",
+            },
+            turnId: null,
+            createdAt: "2026-02-26T12:45:04.000Z",
+          },
+        },
+      });
+
+      const approvalRows = yield* sql<{
+        readonly requestId: string;
+        readonly status: string;
+        readonly turnId: string | null;
+        readonly createdAt: string;
+        readonly resolvedAt: string | null;
+      }>`
+        SELECT
+          request_id AS "requestId",
+          status,
+          turn_id AS "turnId",
+          created_at AS "createdAt",
+          resolved_at AS "resolvedAt"
+        FROM projection_pending_approvals
+        WHERE request_id IN (
+          'approval-request-nonstale-existing',
+          'approval-request-nonstale-missing'
+        )
+        ORDER BY request_id
+      `;
+      assert.deepEqual(approvalRows, [
+        {
+          requestId: "approval-request-nonstale-existing",
+          status: "pending",
+          turnId: null,
+          createdAt: "2026-02-26T12:45:02.000Z",
+          resolvedAt: null,
+        },
+      ]);
+
+      const threadRows = yield* sql<{
+        readonly pendingApprovalCount: number;
+      }>`
+        SELECT pending_approval_count AS "pendingApprovalCount"
+        FROM projection_threads
+        WHERE thread_id = 'thread-nonstale-approval'
+      `;
+      assert.deepEqual(threadRows, [{ pendingApprovalCount: 1 }]);
+    }),
+  );
+
   it.effect("does not fallback-retain messages whose turnId is removed by revert", () =>
     Effect.gen(function* () {
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
@@ -1551,7 +1882,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           projectId: ProjectId.make("project-revert"),
           title: "Thread Revert",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "full-access",
@@ -1863,7 +2194,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
     Effect.gen(function* () {
       const engine = yield* OrchestrationEngineService;
       const sql = yield* SqlClient.SqlClient;
-      const createdAt = new Date().toISOString();
+      const createdAt = "2026-01-01T00:00:00.000Z";
 
       yield* engine.dispatch({
         type: "project.create",
@@ -1872,7 +2203,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
         title: "Live Project",
         workspaceRoot: "/tmp/project-live",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -1901,7 +2232,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
     Effect.gen(function* () {
       const engine = yield* OrchestrationEngineService;
       const sql = yield* SqlClient.SqlClient;
-      const createdAt = new Date().toISOString();
+      const createdAt = "2026-01-01T00:00:00.000Z";
 
       yield* engine.dispatch({
         type: "project.create",
@@ -1910,7 +2241,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
         title: "Scripts Project",
         workspaceRoot: "/tmp/project-scripts",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -1930,7 +2261,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
           },
         ],
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
       });
@@ -1949,7 +2280,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
         {
           scriptsJson:
             '[{"id":"script-1","name":"Build","command":"bun run build","icon":"build","runOnWorktreeCreate":false}]',
-          defaultModelSelection: '{"provider":"codex","model":"gpt-5"}',
+          defaultModelSelection: '{"instanceId":"codex","model":"gpt-5"}',
         },
       ]);
     }),
diff --git a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
index bdc6fac6d1c..1161ff6a7d7 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
@@ -2,8 +2,14 @@ import {
   ApprovalRequestId,
   type ChatAttachment,
   type OrchestrationEvent,
+  ThreadId,
 } from "@t3tools/contracts";
-import { Effect, FileSystem, Layer, Option, Path, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Stream from "effect/Stream";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { toPersistenceSqlError, type ProjectionRepositoryError } from "../../persistence/Errors.ts";
@@ -89,6 +95,88 @@ function extractActivityRequestId(payload: unknown): ApprovalRequestId | null {
   return typeof requestId === "string" ? ApprovalRequestId.make(requestId) : null;
 }
 
+function isStalePendingApprovalFailureDetail(detail: string | null): boolean {
+  if (detail === null) {
+    return false;
+  }
+  return (
+    detail.includes("stale pending approval request") ||
+    detail.includes("unknown pending approval request") ||
+    detail.includes("unknown pending permission request")
+  );
+}
+
+function derivePendingUserInputCountFromActivities(
+  activities: ReadonlyArray<ProjectionThreadActivity>,
+): number {
+  const openRequestIds = new Set<string>();
+  const ordered = [...activities].toSorted(
+    (left, right) =>
+      left.createdAt.localeCompare(right.createdAt) ||
+      left.activityId.localeCompare(right.activityId),
+  );
+
+  for (const activity of ordered) {
+    const requestId = extractActivityRequestId(activity.payload);
+    if (requestId === null) {
+      continue;
+    }
+    const payload =
+      typeof activity.payload === "object" && activity.payload !== null
+        ? (activity.payload as Record<string, unknown>)
+        : null;
+    const detail = typeof payload?.detail === "string" ? payload.detail.toLowerCase() : null;
+
+    if (activity.kind === "user-input.requested") {
+      openRequestIds.add(requestId);
+      continue;
+    }
+
+    if (activity.kind === "user-input.resolved") {
+      openRequestIds.delete(requestId);
+      continue;
+    }
+
+    if (
+      activity.kind === "provider.user-input.respond.failed" &&
+      detail !== null &&
+      (detail.includes("stale pending user-input request") ||
+        detail.includes("unknown pending user-input request"))
+    ) {
+      openRequestIds.delete(requestId);
+    }
+  }
+
+  return openRequestIds.size;
+}
+
+function deriveHasActionableProposedPlan(input: {
+  readonly latestTurnId: string | null;
+  readonly proposedPlans: ReadonlyArray<ProjectionThreadProposedPlan>;
+}): boolean {
+  const sorted = [...input.proposedPlans].toSorted(
+    (left, right) =>
+      left.updatedAt.localeCompare(right.updatedAt) || left.planId.localeCompare(right.planId),
+  );
+
+  let latestForTurn: ProjectionThreadProposedPlan | null = null;
+  if (input.latestTurnId !== null) {
+    for (let index = sorted.length - 1; index >= 0; index -= 1) {
+      const plan = sorted[index];
+      if (plan?.turnId === input.latestTurnId) {
+        latestForTurn = plan;
+        break;
+      }
+    }
+  }
+  if (latestForTurn !== null) {
+    return latestForTurn.implementedAt === null;
+  }
+
+  const latestPlan = sorted.at(-1) ?? null;
+  return latestPlan !== null && latestPlan.implementedAt === null;
+}
+
 function retainProjectionMessagesAfterRevert(
   messages: ReadonlyArray<ProjectionThreadMessage>,
   turns: ReadonlyArray<ProjectionTurn>,
@@ -432,6 +520,48 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
       }
     });
 
+    const refreshThreadShellSummary = Effect.fn("refreshThreadShellSummary")(function* (
+      threadId: ThreadId,
+    ) {
+      const existingRow = yield* projectionThreadRepository.getById({
+        threadId,
+      });
+      if (Option.isNone(existingRow)) {
+        return;
+      }
+
+      const [messages, proposedPlans, activities, pendingApprovals] = yield* Effect.all([
+        projectionThreadMessageRepository.listByThreadId({ threadId }),
+        projectionThreadProposedPlanRepository.listByThreadId({ threadId }),
+        projectionThreadActivityRepository.listByThreadId({ threadId }),
+        projectionPendingApprovalRepository.listByThreadId({ threadId }),
+      ]);
+
+      const latestUserMessageAt =
+        messages
+          .filter((message) => message.role === "user")
+          .map((message) => message.createdAt)
+          .toSorted()
+          .at(-1) ?? null;
+
+      const pendingApprovalCount = pendingApprovals.filter(
+        (approval) => approval.status === "pending",
+      ).length;
+      const pendingUserInputCount = derivePendingUserInputCountFromActivities(activities);
+      const hasActionableProposedPlan = deriveHasActionableProposedPlan({
+        latestTurnId: existingRow.value.latestTurnId,
+        proposedPlans,
+      });
+
+      yield* projectionThreadRepository.upsert({
+        ...existingRow.value,
+        latestUserMessageAt,
+        pendingApprovalCount,
+        pendingUserInputCount,
+        hasActionableProposedPlan: hasActionableProposedPlan ? 1 : 0,
+      });
+    });
+
     const applyThreadsProjection: ProjectorDefinition["apply"] = Effect.fn(
       "applyThreadsProjection",
     )(function* (event, attachmentSideEffects) {
@@ -450,6 +580,10 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             createdAt: event.payload.createdAt,
             updatedAt: event.payload.updatedAt,
             archivedAt: null,
+            latestUserMessageAt: null,
+            pendingApprovalCount: 0,
+            pendingUserInputCount: 0,
+            hasActionableProposedPlan: 0,
             deletedAt: null,
           });
           return;
@@ -554,7 +688,9 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
 
         case "thread.message-sent":
         case "thread.proposed-plan-upserted":
-        case "thread.activity-appended": {
+        case "thread.activity-appended":
+        case "thread.approval-response-requested":
+        case "thread.user-input-response-requested": {
           const existingRow = yield* projectionThreadRepository.getById({
             threadId: event.payload.threadId,
           });
@@ -565,6 +701,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             ...existingRow.value,
             updatedAt: event.occurredAt,
           });
+          yield* refreshThreadShellSummary(event.payload.threadId);
           return;
         }
 
@@ -580,6 +717,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             latestTurnId: event.payload.session.activeTurnId,
             updatedAt: event.occurredAt,
           });
+          yield* refreshThreadShellSummary(event.payload.threadId);
           return;
         }
 
@@ -595,6 +733,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             latestTurnId: event.payload.turnId,
             updatedAt: event.occurredAt,
           });
+          yield* refreshThreadShellSummary(event.payload.threadId);
           return;
         }
 
@@ -605,11 +744,34 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
           if (Option.isNone(existingRow)) {
             return;
           }
+
+          const retainedTurns = yield* projectionTurnRepository.listByThreadId({
+            threadId: event.payload.threadId,
+          });
+          let latestTurnId: ProjectionTurn["turnId"] = null;
+          let latestCheckpointTurnCount = -1;
+          for (let index = 0; index < retainedTurns.length; index += 1) {
+            const turn = retainedTurns[index];
+            if (
+              !turn ||
+              turn.turnId === null ||
+              turn.checkpointTurnCount === null ||
+              turn.checkpointTurnCount > event.payload.turnCount
+            ) {
+              continue;
+            }
+            if (turn.checkpointTurnCount > latestCheckpointTurnCount) {
+              latestCheckpointTurnCount = turn.checkpointTurnCount;
+              latestTurnId = turn.turnId;
+            }
+          }
+
           yield* projectionThreadRepository.upsert({
             ...existingRow.value,
-            latestTurnId: null,
+            latestTurnId,
             updatedAt: event.occurredAt,
           });
+          yield* refreshThreadShellSummary(event.payload.threadId);
           return;
         }
 
@@ -810,6 +972,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
         threadId: event.payload.threadId,
         status: event.payload.session.status,
         providerName: event.payload.session.providerName,
+        providerInstanceId: event.payload.session.providerInstanceId ?? null,
         runtimeMode: event.payload.session.runtimeMode,
         activeTurnId: event.payload.session.activeTurnId,
         lastError: event.payload.session.lastError,
@@ -1121,6 +1284,42 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             });
             return;
           }
+          if (event.payload.activity.kind === "provider.approval.respond.failed") {
+            const payload =
+              typeof event.payload.activity.payload === "object" &&
+              event.payload.activity.payload !== null
+                ? (event.payload.activity.payload as Record<string, unknown>)
+                : null;
+            const detail =
+              typeof payload?.detail === "string" ? payload.detail.toLowerCase() : null;
+            if (isStalePendingApprovalFailureDetail(detail)) {
+              if (Option.isNone(existingRow)) {
+                return;
+              }
+              if (existingRow.value.status === "resolved") {
+                return;
+              }
+              yield* projectionPendingApprovalRepository.upsert({
+                requestId,
+                threadId: existingRow.value.threadId,
+                turnId: existingRow.value.turnId,
+                status: "resolved",
+                decision: null,
+                createdAt: existingRow.value.createdAt,
+                resolvedAt: event.payload.activity.createdAt,
+              });
+              return;
+            }
+            return;
+          }
+          // Only approval-requested activities should create pending-approval
+          // rows.  Other activity kinds that happen to carry a requestId
+          // (e.g. user-input.requested / user-input.resolved) must not
+          // pollute this projection — they have their own accounting via
+          // derivePendingUserInputCountFromActivities.
+          if (event.payload.activity.kind !== "approval.requested") {
+            return;
+          }
           if (Option.isSome(existingRow) && existingRow.value.status === "resolved") {
             return;
           }
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
index 0eb312cbfdc..7db2a23e5ec 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
@@ -1,9 +1,20 @@
-import { CheckpointRef, EventId, MessageId, ProjectId, ThreadId, TurnId } from "@t3tools/contracts";
+import {
+  CheckpointRef,
+  EventId,
+  MessageId,
+  ProjectId,
+  ThreadId,
+  TurnId,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
+import { RepositoryIdentityResolver } from "../../project/Services/RepositoryIdentityResolver.ts";
 import { RepositoryIdentityResolverLive } from "../../project/Layers/RepositoryIdentityResolver.ts";
 import { ORCHESTRATION_PROJECTOR_NAMES } from "./ProjectionPipeline.ts";
 import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQuery.ts";
@@ -19,6 +30,7 @@ const projectionSnapshotLayer = it.layer(
   OrchestrationProjectionSnapshotQueryLive.pipe(
     Layer.provideMerge(RepositoryIdentityResolverLive),
     Layer.provideMerge(SqlitePersistenceMemory),
+    Layer.provideMerge(NodeServices.layer),
   ),
 );
 
@@ -62,9 +74,15 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           project_id,
           title,
           model_selection_json,
+          runtime_mode,
+          interaction_mode,
           branch,
           worktree_path,
           latest_turn_id,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
           created_at,
           updated_at,
           deleted_at
@@ -74,9 +92,15 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           'project-1',
           'Thread 1',
           '{"provider":"codex","model":"gpt-5-codex"}',
+          'full-access',
+          'default',
           NULL,
           NULL,
           'turn-1',
+          '2026-02-24T00:00:04.000Z',
+          1,
+          0,
+          0,
           '2026-02-24T00:00:02.000Z',
           '2026-02-24T00:00:03.000Z',
           NULL
@@ -240,7 +264,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           workspaceRoot: "/tmp/project-1",
           repositoryIdentity: null,
           defaultModelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           scripts: [
@@ -263,7 +287,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           projectId: asProjectId("project-1"),
           title: "Thread 1",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: "default",
@@ -341,6 +365,201 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           },
         },
       ]);
+
+      const shellSnapshot = yield* snapshotQuery.getShellSnapshot();
+      assert.equal(shellSnapshot.snapshotSequence, 5);
+      assert.deepEqual(shellSnapshot.projects, [
+        {
+          id: asProjectId("project-1"),
+          title: "Project 1",
+          workspaceRoot: "/tmp/project-1",
+          repositoryIdentity: null,
+          defaultModelSelection: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: "gpt-5-codex",
+          },
+          scripts: [
+            {
+              id: "script-1",
+              name: "Build",
+              command: "bun run build",
+              icon: "build",
+              runOnWorktreeCreate: false,
+            },
+          ],
+          createdAt: "2026-02-24T00:00:00.000Z",
+          updatedAt: "2026-02-24T00:00:01.000Z",
+        },
+      ]);
+      assert.deepEqual(shellSnapshot.threads, [
+        {
+          id: ThreadId.make("thread-1"),
+          projectId: asProjectId("project-1"),
+          title: "Thread 1",
+          modelSelection: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: "gpt-5-codex",
+          },
+          interactionMode: "default",
+          runtimeMode: "full-access",
+          branch: null,
+          worktreePath: null,
+          latestTurn: {
+            turnId: asTurnId("turn-1"),
+            state: "completed",
+            requestedAt: "2026-02-24T00:00:08.000Z",
+            startedAt: "2026-02-24T00:00:08.000Z",
+            completedAt: "2026-02-24T00:00:08.000Z",
+            assistantMessageId: asMessageId("message-1"),
+            sourceProposedPlan: {
+              threadId: ThreadId.make("thread-1"),
+              planId: "plan-1",
+            },
+          },
+          createdAt: "2026-02-24T00:00:02.000Z",
+          updatedAt: "2026-02-24T00:00:03.000Z",
+          archivedAt: null,
+          session: {
+            threadId: ThreadId.make("thread-1"),
+            status: "running",
+            providerName: "codex",
+            runtimeMode: "approval-required",
+            activeTurnId: asTurnId("turn-1"),
+            lastError: null,
+            updatedAt: "2026-02-24T00:00:07.000Z",
+          },
+          latestUserMessageAt: "2026-02-24T00:00:04.000Z",
+          hasPendingApprovals: true,
+          hasPendingUserInput: false,
+          hasActionableProposedPlan: false,
+        },
+      ]);
+
+      const threadDetail = yield* snapshotQuery.getThreadDetailById(ThreadId.make("thread-1"));
+      assert.equal(threadDetail._tag, "Some");
+      if (threadDetail._tag === "Some") {
+        assert.deepEqual(threadDetail.value, snapshot.threads[0]);
+      }
+    }),
+  );
+
+  it.effect("keeps archived threads out of the main shell snapshot", () =>
+    Effect.gen(function* () {
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* sql`DELETE FROM projection_projects`;
+      yield* sql`DELETE FROM projection_threads`;
+      yield* sql`DELETE FROM projection_state`;
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'project-archive-test',
+          'Archive Test',
+          '/tmp/archive-test',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          '[]',
+          '2026-04-06T00:00:00.000Z',
+          '2026-04-06T00:00:01.000Z',
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          created_at,
+          updated_at,
+          archived_at,
+          deleted_at
+        )
+        VALUES
+          (
+            'thread-active',
+            'project-archive-test',
+            'Active Thread',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            'full-access',
+            'default',
+            NULL,
+            NULL,
+            NULL,
+            NULL,
+            0,
+            0,
+            0,
+            '2026-04-06T00:00:02.000Z',
+            '2026-04-06T00:00:03.000Z',
+            NULL,
+            NULL
+          ),
+          (
+            'thread-archived',
+            'project-archive-test',
+            'Archived Thread',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            'full-access',
+            'default',
+            NULL,
+            NULL,
+            NULL,
+            NULL,
+            0,
+            0,
+            0,
+            '2026-04-06T00:00:04.000Z',
+            '2026-04-06T00:00:05.000Z',
+            '2026-04-06T00:00:06.000Z',
+            NULL
+          )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_state (projector, last_applied_sequence, updated_at)
+        VALUES
+          (${ORCHESTRATION_PROJECTOR_NAMES.projects}, 4, '2026-04-06T00:00:07.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threads}, 4, '2026-04-06T00:00:07.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadMessages}, 4, '2026-04-06T00:00:07.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadProposedPlans}, 4, '2026-04-06T00:00:07.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadActivities}, 4, '2026-04-06T00:00:07.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadSessions}, 4, '2026-04-06T00:00:07.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.checkpoints}, 4, '2026-04-06T00:00:07.000Z')
+      `;
+
+      const shellSnapshot = yield* snapshotQuery.getShellSnapshot();
+      assert.deepEqual(
+        shellSnapshot.threads.map((thread) => thread.id),
+        [ThreadId.make("thread-active")],
+      );
+
+      const archivedShellSnapshot = yield* snapshotQuery.getArchivedShellSnapshot();
+      assert.deepEqual(
+        archivedShellSnapshot.threads.map((thread) => thread.id),
+        [ThreadId.make("thread-archived")],
+      );
+      assert.equal(archivedShellSnapshot.threads[0]?.archivedAt, "2026-04-06T00:00:06.000Z");
     }),
   );
 
@@ -629,4 +848,683 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
       }
     }),
   );
-});
+
+  it.effect("keeps thread detail activity ordering consistent with shell snapshot ordering", () =>
+    Effect.gen(function* () {
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* sql`DELETE FROM projection_projects`;
+      yield* sql`DELETE FROM projection_threads`;
+      yield* sql`DELETE FROM projection_thread_activities`;
+      yield* sql`DELETE FROM projection_state`;
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'project-1',
+          'Project 1',
+          '/tmp/project-1',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          '[]',
+          '2026-04-01T00:00:00.000Z',
+          '2026-04-01T00:00:01.000Z',
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'thread-1',
+          'project-1',
+          'Thread 1',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          'full-access',
+          'default',
+          NULL,
+          NULL,
+          NULL,
+          NULL,
+          0,
+          0,
+          0,
+          '2026-04-01T00:00:02.000Z',
+          '2026-04-01T00:00:03.000Z',
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_thread_activities (
+          activity_id,
+          thread_id,
+          turn_id,
+          tone,
+          kind,
+          summary,
+          payload_json,
+          sequence,
+          created_at
+        )
+        VALUES
+          (
+            'activity-unsequenced',
+            'thread-1',
+            NULL,
+            'info',
+            'runtime.note',
+            'unsequenced first',
+            '{"source":"unsequenced"}',
+            NULL,
+            '2026-04-01T00:00:06.000Z'
+          ),
+          (
+            'activity-sequence-2',
+            'thread-1',
+            NULL,
+            'info',
+            'runtime.note',
+            'sequence two',
+            '{"source":"sequence-2"}',
+            2,
+            '2026-04-01T00:00:04.000Z'
+          ),
+          (
+            'activity-sequence-1',
+            'thread-1',
+            NULL,
+            'info',
+            'runtime.note',
+            'sequence one',
+            '{"source":"sequence-1"}',
+            1,
+            '2026-04-01T00:00:05.000Z'
+          )
+      `;
+
+      const snapshot = yield* snapshotQuery.getSnapshot();
+      const threadDetail = yield* snapshotQuery.getThreadDetailById(ThreadId.make("thread-1"));
+
+      assert.equal(threadDetail._tag, "Some");
+      if (threadDetail._tag === "Some") {
+        assert.deepEqual(threadDetail.value.activities, snapshot.threads[0]?.activities ?? []);
+      }
+
+      assert.deepEqual(snapshot.threads[0]?.activities ?? [], [
+        {
+          id: asEventId("activity-unsequenced"),
+          tone: "info",
+          kind: "runtime.note",
+          summary: "unsequenced first",
+          payload: { source: "unsequenced" },
+          turnId: null,
+          createdAt: "2026-04-01T00:00:06.000Z",
+        },
+        {
+          id: asEventId("activity-sequence-1"),
+          tone: "info",
+          kind: "runtime.note",
+          summary: "sequence one",
+          payload: { source: "sequence-1" },
+          turnId: null,
+          sequence: 1,
+          createdAt: "2026-04-01T00:00:05.000Z",
+        },
+        {
+          id: asEventId("activity-sequence-2"),
+          tone: "info",
+          kind: "runtime.note",
+          summary: "sequence two",
+          payload: { source: "sequence-2" },
+          turnId: null,
+          sequence: 2,
+          createdAt: "2026-04-01T00:00:04.000Z",
+        },
+      ]);
+    }),
+  );
+
+  it.effect("uses projection_threads.latest_turn_id for targeted thread latest turn queries", () =>
+    Effect.gen(function* () {
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* sql`DELETE FROM projection_projects`;
+      yield* sql`DELETE FROM projection_threads`;
+      yield* sql`DELETE FROM projection_turns`;
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'project-1',
+          'Project 1',
+          '/tmp/project-1',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          '[]',
+          '2026-04-02T00:00:00.000Z',
+          '2026-04-02T00:00:01.000Z',
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          created_at,
+          updated_at,
+          archived_at,
+          deleted_at
+        )
+        VALUES (
+          'thread-1',
+          'project-1',
+          'Thread 1',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          'full-access',
+          'default',
+          NULL,
+          NULL,
+          'turn-running',
+          '2026-04-02T00:00:04.000Z',
+          0,
+          0,
+          0,
+          '2026-04-02T00:00:02.000Z',
+          '2026-04-02T00:00:03.000Z',
+          NULL,
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_turns (
+          thread_id,
+          turn_id,
+          pending_message_id,
+          source_proposed_plan_thread_id,
+          source_proposed_plan_id,
+          assistant_message_id,
+          state,
+          requested_at,
+          started_at,
+          completed_at,
+          checkpoint_turn_count,
+          checkpoint_ref,
+          checkpoint_status,
+          checkpoint_files_json
+        )
+        VALUES
+          (
+            'thread-1',
+            'turn-completed',
+            'message-user-1',
+            NULL,
+            NULL,
+            'message-assistant-1',
+            'completed',
+            '2026-04-02T00:00:05.000Z',
+            '2026-04-02T00:00:06.000Z',
+            '2026-04-02T00:00:20.000Z',
+            5,
+            'checkpoint-5',
+            'ready',
+            '[]'
+          ),
+          (
+            'thread-1',
+            'turn-running',
+            'message-user-2',
+            NULL,
+            NULL,
+            NULL,
+            'running',
+            '2026-04-02T00:00:30.000Z',
+            '2026-04-02T00:00:30.000Z',
+            NULL,
+            NULL,
+            NULL,
+            NULL,
+            '[]'
+          )
+      `;
+
+      const threadShell = yield* snapshotQuery.getThreadShellById(ThreadId.make("thread-1"));
+      assert.equal(threadShell._tag, "Some");
+      if (threadShell._tag === "Some") {
+        assert.equal(threadShell.value.latestTurn?.turnId, asTurnId("turn-running"));
+        assert.equal(threadShell.value.latestTurn?.state, "running");
+        assert.equal(threadShell.value.latestTurn?.startedAt, "2026-04-02T00:00:30.000Z");
+      }
+
+      const threadDetail = yield* snapshotQuery.getThreadDetailById(ThreadId.make("thread-1"));
+      assert.equal(threadDetail._tag, "Some");
+      if (threadDetail._tag === "Some") {
+        assert.equal(threadDetail.value.latestTurn?.turnId, asTurnId("turn-running"));
+        assert.equal(threadDetail.value.latestTurn?.state, "running");
+        assert.equal(threadDetail.value.latestTurn?.startedAt, "2026-04-02T00:00:30.000Z");
+      }
+    }),
+  );
+
+  it.effect("uses projection_threads.latest_turn_id for bulk command and shell snapshots", () =>
+    Effect.gen(function* () {
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* sql`DELETE FROM projection_projects`;
+      yield* sql`DELETE FROM projection_threads`;
+      yield* sql`DELETE FROM projection_turns`;
+      yield* sql`DELETE FROM projection_state`;
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'project-1',
+          'Project 1',
+          '/tmp/project-1',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          '[]',
+          '2026-04-03T00:00:00.000Z',
+          '2026-04-03T00:00:01.000Z',
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          created_at,
+          updated_at,
+          archived_at,
+          deleted_at
+        )
+        VALUES (
+          'thread-1',
+          'project-1',
+          'Thread 1',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          'full-access',
+          'default',
+          NULL,
+          NULL,
+          'turn-running',
+          '2026-04-03T00:00:04.000Z',
+          0,
+          0,
+          0,
+          '2026-04-03T00:00:02.000Z',
+          '2026-04-03T00:00:03.000Z',
+          NULL,
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_turns (
+          thread_id,
+          turn_id,
+          pending_message_id,
+          source_proposed_plan_thread_id,
+          source_proposed_plan_id,
+          assistant_message_id,
+          state,
+          requested_at,
+          started_at,
+          completed_at,
+          checkpoint_turn_count,
+          checkpoint_ref,
+          checkpoint_status,
+          checkpoint_files_json
+        )
+        VALUES
+          (
+            'thread-1',
+            'turn-running',
+            'message-user-2',
+            NULL,
+            NULL,
+            NULL,
+            'running',
+            '2026-04-03T00:00:30.000Z',
+            '2026-04-03T00:00:30.000Z',
+            NULL,
+            NULL,
+            NULL,
+            NULL,
+            '[]'
+          ),
+          (
+            'thread-1',
+            'turn-completed',
+            'message-user-1',
+            NULL,
+            NULL,
+            'message-assistant-1',
+            'completed',
+            '2026-04-03T00:00:05.000Z',
+            '2026-04-03T00:00:06.000Z',
+            '2026-04-03T00:00:20.000Z',
+            NULL,
+            NULL,
+            NULL,
+            '[]'
+          )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_state (projector, last_applied_sequence, updated_at)
+        VALUES
+          (${ORCHESTRATION_PROJECTOR_NAMES.projects}, 3, '2026-04-03T00:00:40.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threads}, 3, '2026-04-03T00:00:40.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadMessages}, 3, '2026-04-03T00:00:40.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadProposedPlans}, 3, '2026-04-03T00:00:40.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadActivities}, 3, '2026-04-03T00:00:40.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.threadSessions}, 3, '2026-04-03T00:00:40.000Z'),
+          (${ORCHESTRATION_PROJECTOR_NAMES.checkpoints}, 3, '2026-04-03T00:00:40.000Z')
+      `;
+
+      const commandReadModel = yield* snapshotQuery.getCommandReadModel();
+      assert.equal(commandReadModel.threads[0]?.latestTurn?.turnId, asTurnId("turn-running"));
+      assert.equal(commandReadModel.threads[0]?.latestTurn?.state, "running");
+
+      const shellSnapshot = yield* snapshotQuery.getShellSnapshot();
+      assert.equal(shellSnapshot.threads[0]?.latestTurn?.turnId, asTurnId("turn-running"));
+      assert.equal(shellSnapshot.threads[0]?.latestTurn?.state, "running");
+
+      const fullSnapshot = yield* snapshotQuery.getSnapshot();
+      assert.equal(fullSnapshot.threads[0]?.latestTurn?.turnId, asTurnId("turn-running"));
+      assert.equal(fullSnapshot.threads[0]?.latestTurn?.state, "running");
+    }),
+  );
+
+  it.effect("keeps deleted project and thread tombstones in the command read model", () =>
+    Effect.gen(function* () {
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* sql`DELETE FROM projection_projects`;
+      yield* sql`DELETE FROM projection_threads`;
+      yield* sql`DELETE FROM projection_turns`;
+      yield* sql`DELETE FROM projection_state`;
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES (
+          'project-deleted',
+          'Deleted Project',
+          '/tmp/deleted-project',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          '[]',
+          '2026-04-05T00:00:00.000Z',
+          '2026-04-05T00:00:01.000Z',
+          '2026-04-05T00:00:02.000Z'
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          created_at,
+          updated_at,
+          archived_at,
+          deleted_at
+        )
+        VALUES (
+          'thread-deleted',
+          'project-deleted',
+          'Deleted Thread',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          'full-access',
+          'default',
+          NULL,
+          NULL,
+          'turn-deleted',
+          NULL,
+          0,
+          0,
+          0,
+          '2026-04-05T00:00:03.000Z',
+          '2026-04-05T00:00:04.000Z',
+          NULL,
+          '2026-04-05T00:00:05.000Z'
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_turns (
+          thread_id,
+          turn_id,
+          pending_message_id,
+          source_proposed_plan_thread_id,
+          source_proposed_plan_id,
+          assistant_message_id,
+          state,
+          requested_at,
+          started_at,
+          completed_at,
+          checkpoint_turn_count,
+          checkpoint_ref,
+          checkpoint_status,
+          checkpoint_files_json
+        )
+        VALUES (
+          'thread-deleted',
+          'turn-deleted',
+          'message-deleted-user',
+          NULL,
+          NULL,
+          'message-deleted-assistant',
+          'completed',
+          '2026-04-05T00:00:04.100Z',
+          '2026-04-05T00:00:04.200Z',
+          '2026-04-05T00:00:04.300Z',
+          NULL,
+          NULL,
+          NULL,
+          '[]'
+        )
+      `;
+
+      const commandReadModel = yield* snapshotQuery.getCommandReadModel();
+      assert.equal(commandReadModel.projects[0]?.id, asProjectId("project-deleted"));
+      assert.equal(commandReadModel.projects[0]?.deletedAt, "2026-04-05T00:00:02.000Z");
+      assert.equal(commandReadModel.threads[0]?.id, ThreadId.make("thread-deleted"));
+      assert.equal(commandReadModel.threads[0]?.deletedAt, "2026-04-05T00:00:05.000Z");
+      assert.equal(commandReadModel.threads[0]?.latestTurn?.turnId, asTurnId("turn-deleted"));
+      assert.equal(commandReadModel.threads[0]?.latestTurn?.state, "completed");
+
+      const fullSnapshot = yield* snapshotQuery.getSnapshot();
+      assert.equal(fullSnapshot.threads[0]?.id, ThreadId.make("thread-deleted"));
+      assert.equal(fullSnapshot.threads[0]?.latestTurn?.turnId, asTurnId("turn-deleted"));
+      assert.equal(fullSnapshot.threads[0]?.latestTurn?.state, "completed");
+
+      const shellSnapshot = yield* snapshotQuery.getShellSnapshot();
+      assert.equal(shellSnapshot.projects.length, 0);
+      assert.equal(shellSnapshot.threads.length, 0);
+    }),
+  );
+});
+
+it.effect(
+  "ProjectionSnapshotQuery dedupes repository identity resolution by workspace root and skips deleted projects for shell snapshots",
+  () => {
+    const resolveCalls: string[] = [];
+    const layer = OrchestrationProjectionSnapshotQueryLive.pipe(
+      Layer.provideMerge(
+        Layer.succeed(RepositoryIdentityResolver, {
+          resolve: (cwd: string) =>
+            Effect.sync(() => {
+              resolveCalls.push(cwd);
+              return {
+                canonicalKey: `github.com/acme${cwd}`,
+                locator: {
+                  source: "git-remote" as const,
+                  remoteName: "origin",
+                  remoteUrl: `https://github.com/acme${cwd}.git`,
+                },
+                rootPath: cwd,
+              };
+            }),
+        }),
+      ),
+      Layer.provideMerge(SqlitePersistenceMemory),
+    );
+
+    return Effect.gen(function* () {
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* sql`DELETE FROM projection_projects`;
+      yield* sql`DELETE FROM projection_threads`;
+      yield* sql`DELETE FROM projection_turns`;
+      yield* sql`DELETE FROM projection_state`;
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          default_model_selection_json,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at
+        )
+        VALUES
+          (
+            'project-1',
+            'Shared Project 1',
+            '/tmp/shared-root',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            '[]',
+            '2026-04-04T00:00:00.000Z',
+            '2026-04-04T00:00:01.000Z',
+            NULL
+          ),
+          (
+            'project-2',
+            'Shared Project 2',
+            '/tmp/shared-root',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            '[]',
+            '2026-04-04T00:00:02.000Z',
+            '2026-04-04T00:00:03.000Z',
+            NULL
+          ),
+          (
+            'project-3',
+            'Deleted Project',
+            '/tmp/deleted-root',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            '[]',
+            '2026-04-04T00:00:04.000Z',
+            '2026-04-04T00:00:05.000Z',
+            '2026-04-04T00:00:06.000Z'
+          )
+      `;
+
+      const shellSnapshot = yield* snapshotQuery.getShellSnapshot();
+      assert.deepStrictEqual(resolveCalls.toSorted(), ["/tmp/shared-root"]);
+      assert.equal(shellSnapshot.projects.length, 2);
+      assert.equal(shellSnapshot.projects[0]?.repositoryIdentity?.rootPath, "/tmp/shared-root");
+      assert.equal(shellSnapshot.projects[1]?.repositoryIdentity?.rootPath, "/tmp/shared-root");
+
+      resolveCalls.length = 0;
+
+      const fullSnapshot = yield* snapshotQuery.getSnapshot();
+      assert.deepStrictEqual(resolveCalls.toSorted(), ["/tmp/deleted-root", "/tmp/shared-root"]);
+      assert.equal(fullSnapshot.projects.length, 3);
+      assert.equal(fullSnapshot.projects[2]?.repositoryIdentity?.rootPath, "/tmp/deleted-root");
+    }).pipe(Effect.provide(layer));
+  },
+);
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
index b0f883f9402..9b3c0fa7ad4 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
@@ -1,26 +1,34 @@
 import {
   ChatAttachment,
+  CheckpointRef,
   IsoDateTime,
   MessageId,
   NonNegativeInt,
   OrchestrationCheckpointFile,
   OrchestrationProposedPlanId,
   OrchestrationReadModel,
+  OrchestrationShellSnapshot,
+  OrchestrationThread,
   ProjectScript,
   TurnId,
   type OrchestrationCheckpointSummary,
   type OrchestrationLatestTurn,
   type OrchestrationMessage,
+  type OrchestrationProjectShell,
   type OrchestrationProposedPlan,
   type OrchestrationProject,
   type OrchestrationSession,
-  type OrchestrationThread,
   type OrchestrationThreadActivity,
+  type OrchestrationThreadShell,
   ModelSelection,
   ProjectId,
   ThreadId,
 } from "@t3tools/contracts";
-import { Effect, Layer, Option, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
 
@@ -42,12 +50,15 @@ import { RepositoryIdentityResolver } from "../../project/Services/RepositoryIde
 import { ORCHESTRATION_PROJECTOR_NAMES } from "./ProjectionPipeline.ts";
 import {
   ProjectionSnapshotQuery,
+  type ProjectionFullThreadDiffContext,
   type ProjectionSnapshotCounts,
   type ProjectionThreadCheckpointContext,
   type ProjectionSnapshotQueryShape,
 } from "../Services/ProjectionSnapshotQuery.ts";
 
 const decodeReadModel = Schema.decodeUnknownEffect(OrchestrationReadModel);
+const decodeShellSnapshot = Schema.decodeUnknownEffect(OrchestrationShellSnapshot);
+const decodeThread = Schema.decodeUnknownEffect(OrchestrationThread);
 const ProjectionProjectDbRowSchema = ProjectionProject.mapFields(
   Struct.assign({
     defaultModelSelection: Schema.NullOr(Schema.fromJsonString(ModelSelection)),
@@ -113,6 +124,18 @@ const ProjectionThreadCheckpointContextThreadRowSchema = Schema.Struct({
   workspaceRoot: Schema.String,
   worktreePath: Schema.NullOr(Schema.String),
 });
+const FullThreadDiffContextLookupInput = Schema.Struct({
+  threadId: ThreadId,
+  checkpointTurnCount: NonNegativeInt,
+});
+const ProjectionFullThreadDiffContextRowSchema = Schema.Struct({
+  threadId: ThreadId,
+  projectId: ProjectId,
+  workspaceRoot: Schema.String,
+  worktreePath: Schema.NullOr(Schema.String),
+  latestCheckpointTurnCount: Schema.NullOr(NonNegativeInt),
+  toCheckpointRef: Schema.NullOr(CheckpointRef),
+});
 
 const REQUIRED_SNAPSHOT_PROJECTORS = [
   ORCHESTRATION_PROJECTOR_NAMES.projects,
@@ -155,6 +178,79 @@ function computeSnapshotSequence(
   return Number.isFinite(minSequence) ? minSequence : 0;
 }
 
+function mapLatestTurn(
+  row: Schema.Schema.Type<typeof ProjectionLatestTurnDbRowSchema>,
+): OrchestrationLatestTurn {
+  return {
+    turnId: row.turnId,
+    state:
+      row.state === "error"
+        ? "error"
+        : row.state === "interrupted"
+          ? "interrupted"
+          : row.state === "completed"
+            ? "completed"
+            : "running",
+    requestedAt: row.requestedAt,
+    startedAt: row.startedAt,
+    completedAt: row.completedAt,
+    assistantMessageId: row.assistantMessageId,
+    ...(row.sourceProposedPlanThreadId !== null && row.sourceProposedPlanId !== null
+      ? {
+          sourceProposedPlan: {
+            threadId: row.sourceProposedPlanThreadId,
+            planId: row.sourceProposedPlanId,
+          },
+        }
+      : {}),
+  };
+}
+
+function mapSessionRow(
+  row: Schema.Schema.Type<typeof ProjectionThreadSessionDbRowSchema>,
+): OrchestrationSession {
+  return {
+    threadId: row.threadId,
+    status: row.status,
+    providerName: row.providerName,
+    ...(row.providerInstanceId !== null ? { providerInstanceId: row.providerInstanceId } : {}),
+    runtimeMode: row.runtimeMode,
+    activeTurnId: row.activeTurnId,
+    lastError: row.lastError,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function mapProjectShellRow(
+  row: Schema.Schema.Type<typeof ProjectionProjectDbRowSchema>,
+  repositoryIdentity: OrchestrationProject["repositoryIdentity"],
+): OrchestrationProjectShell {
+  return {
+    id: row.projectId,
+    title: row.title,
+    workspaceRoot: row.workspaceRoot,
+    repositoryIdentity,
+    defaultModelSelection: row.defaultModelSelection,
+    scripts: row.scripts,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function mapProposedPlanRow(
+  row: Schema.Schema.Type<typeof ProjectionThreadProposedPlanDbRowSchema>,
+): OrchestrationProposedPlan {
+  return {
+    id: row.planId,
+    turnId: row.turnId,
+    planMarkdown: row.planMarkdown,
+    implementedAt: row.implementedAt,
+    implementationThreadId: row.implementationThreadId,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
 function toPersistenceSqlOrDecodeError(sqlOperation: string, decodeOperation: string) {
   return (cause: unknown): ProjectionRepositoryError =>
     Schema.isSchemaError(cause)
@@ -166,6 +262,37 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
   const sql = yield* SqlClient.SqlClient;
   const repositoryIdentityResolver = yield* RepositoryIdentityResolver;
   const repositoryIdentityResolutionConcurrency = 4;
+  const resolveRepositoryIdentitiesForProjects = Effect.fn(
+    "ProjectionSnapshotQuery.resolveRepositoryIdentitiesForProjects",
+  )(function* (
+    projectRows: ReadonlyArray<Schema.Schema.Type<typeof ProjectionProjectDbRowSchema>>,
+    options?: {
+      readonly includeDeleted?: boolean;
+    },
+  ) {
+    const filteredProjectRows =
+      options?.includeDeleted === true
+        ? projectRows
+        : projectRows.filter((row) => row.deletedAt === null);
+    const uniqueWorkspaceRoots = [...new Set(filteredProjectRows.map((row) => row.workspaceRoot))];
+    const repositoryIdentityByWorkspaceRoot = new Map(
+      yield* Effect.forEach(
+        uniqueWorkspaceRoots,
+        (workspaceRoot) =>
+          repositoryIdentityResolver
+            .resolve(workspaceRoot)
+            .pipe(Effect.map((identity) => [workspaceRoot, identity] as const)),
+        { concurrency: repositoryIdentityResolutionConcurrency },
+      ),
+    );
+
+    return new Map(
+      filteredProjectRows.map((row) => [
+        row.projectId,
+        repositoryIdentityByWorkspaceRoot.get(row.workspaceRoot) ?? null,
+      ]),
+    );
+  });
 
   const listProjectRows = SqlSchema.findAll({
     Request: Schema.Void,
@@ -204,12 +331,76 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           created_at AS "createdAt",
           updated_at AS "updatedAt",
           archived_at AS "archivedAt",
+          latest_user_message_at AS "latestUserMessageAt",
+          pending_approval_count AS "pendingApprovalCount",
+          pending_user_input_count AS "pendingUserInputCount",
+          has_actionable_proposed_plan AS "hasActionableProposedPlan",
           deleted_at AS "deletedAt"
         FROM projection_threads
         ORDER BY created_at ASC, thread_id ASC
       `,
   });
 
+  const listActiveThreadRows = SqlSchema.findAll({
+    Request: Schema.Void,
+    Result: ProjectionThreadDbRowSchema,
+    execute: () =>
+      sql`
+        SELECT
+          thread_id AS "threadId",
+          project_id AS "projectId",
+          title,
+          model_selection_json AS "modelSelection",
+          runtime_mode AS "runtimeMode",
+          interaction_mode AS "interactionMode",
+          branch,
+          worktree_path AS "worktreePath",
+          latest_turn_id AS "latestTurnId",
+          created_at AS "createdAt",
+          updated_at AS "updatedAt",
+          archived_at AS "archivedAt",
+          latest_user_message_at AS "latestUserMessageAt",
+          pending_approval_count AS "pendingApprovalCount",
+          pending_user_input_count AS "pendingUserInputCount",
+          has_actionable_proposed_plan AS "hasActionableProposedPlan",
+          deleted_at AS "deletedAt"
+        FROM projection_threads
+        WHERE deleted_at IS NULL
+          AND archived_at IS NULL
+        ORDER BY project_id ASC, created_at ASC, thread_id ASC
+      `,
+  });
+
+  const listArchivedThreadRows = SqlSchema.findAll({
+    Request: Schema.Void,
+    Result: ProjectionThreadDbRowSchema,
+    execute: () =>
+      sql`
+        SELECT
+          thread_id AS "threadId",
+          project_id AS "projectId",
+          title,
+          model_selection_json AS "modelSelection",
+          runtime_mode AS "runtimeMode",
+          interaction_mode AS "interactionMode",
+          branch,
+          worktree_path AS "worktreePath",
+          latest_turn_id AS "latestTurnId",
+          created_at AS "createdAt",
+          updated_at AS "updatedAt",
+          archived_at AS "archivedAt",
+          latest_user_message_at AS "latestUserMessageAt",
+          pending_approval_count AS "pendingApprovalCount",
+          pending_user_input_count AS "pendingUserInputCount",
+          has_actionable_proposed_plan AS "hasActionableProposedPlan",
+          deleted_at AS "deletedAt"
+        FROM projection_threads
+        WHERE deleted_at IS NULL
+          AND archived_at IS NOT NULL
+        ORDER BY project_id ASC, archived_at DESC, thread_id DESC
+      `,
+  });
+
   const listThreadMessageRows = SqlSchema.findAll({
     Request: Schema.Void,
     Result: ProjectionThreadMessageDbRowSchema,
@@ -267,7 +458,6 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
         FROM projection_thread_activities
         ORDER BY
           thread_id ASC,
-          CASE WHEN sequence IS NULL THEN 0 ELSE 1 END ASC,
           sequence ASC,
           created_at ASC,
           activity_id ASC
@@ -283,6 +473,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
           thread_id AS "threadId",
           status,
           provider_name AS "providerName",
+          provider_instance_id AS "providerInstanceId",
           provider_session_id AS "providerSessionId",
           provider_thread_id AS "providerThreadId",
           runtime_mode AS "runtimeMode",
@@ -294,6 +485,56 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       `,
   });
 
+  const listActiveThreadSessionRows = SqlSchema.findAll({
+    Request: Schema.Void,
+    Result: ProjectionThreadSessionDbRowSchema,
+    execute: () =>
+      sql`
+        SELECT
+          sessions.thread_id AS "threadId",
+          sessions.status,
+          sessions.provider_name AS "providerName",
+          sessions.provider_instance_id AS "providerInstanceId",
+          sessions.provider_session_id AS "providerSessionId",
+          sessions.provider_thread_id AS "providerThreadId",
+          sessions.runtime_mode AS "runtimeMode",
+          sessions.active_turn_id AS "activeTurnId",
+          sessions.last_error AS "lastError",
+          sessions.updated_at AS "updatedAt"
+        FROM projection_thread_sessions sessions
+        INNER JOIN projection_threads threads
+          ON threads.thread_id = sessions.thread_id
+        WHERE threads.deleted_at IS NULL
+          AND threads.archived_at IS NULL
+        ORDER BY sessions.thread_id ASC
+      `,
+  });
+
+  const listArchivedThreadSessionRows = SqlSchema.findAll({
+    Request: Schema.Void,
+    Result: ProjectionThreadSessionDbRowSchema,
+    execute: () =>
+      sql`
+        SELECT
+          sessions.thread_id AS "threadId",
+          sessions.status,
+          sessions.provider_name AS "providerName",
+          sessions.provider_instance_id AS "providerInstanceId",
+          sessions.provider_session_id AS "providerSessionId",
+          sessions.provider_thread_id AS "providerThreadId",
+          sessions.runtime_mode AS "runtimeMode",
+          sessions.active_turn_id AS "activeTurnId",
+          sessions.last_error AS "lastError",
+          sessions.updated_at AS "updatedAt"
+        FROM projection_thread_sessions sessions
+        INNER JOIN projection_threads threads
+          ON threads.thread_id = sessions.thread_id
+        WHERE threads.deleted_at IS NULL
+          AND threads.archived_at IS NOT NULL
+        ORDER BY sessions.thread_id ASC
+      `,
+  });
+
   const listCheckpointRows = SqlSchema.findAll({
     Request: Schema.Void,
     Result: ProjectionCheckpointDbRowSchema,
@@ -320,18 +561,73 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
     execute: () =>
       sql`
         SELECT
-          thread_id AS "threadId",
-          turn_id AS "turnId",
-          state,
-          requested_at AS "requestedAt",
-          started_at AS "startedAt",
-          completed_at AS "completedAt",
-          assistant_message_id AS "assistantMessageId",
-          source_proposed_plan_thread_id AS "sourceProposedPlanThreadId",
-          source_proposed_plan_id AS "sourceProposedPlanId"
-        FROM projection_turns
-        WHERE turn_id IS NOT NULL
-        ORDER BY thread_id ASC, requested_at DESC, turn_id DESC
+          turns.thread_id AS "threadId",
+          turns.turn_id AS "turnId",
+          turns.state,
+          turns.requested_at AS "requestedAt",
+          turns.started_at AS "startedAt",
+          turns.completed_at AS "completedAt",
+          turns.assistant_message_id AS "assistantMessageId",
+          turns.source_proposed_plan_thread_id AS "sourceProposedPlanThreadId",
+          turns.source_proposed_plan_id AS "sourceProposedPlanId"
+        FROM projection_threads threads
+        JOIN projection_turns turns
+          ON turns.thread_id = threads.thread_id
+          AND turns.turn_id = threads.latest_turn_id
+        WHERE threads.latest_turn_id IS NOT NULL
+        ORDER BY turns.thread_id ASC
+      `,
+  });
+
+  const listActiveLatestTurnRows = SqlSchema.findAll({
+    Request: Schema.Void,
+    Result: ProjectionLatestTurnDbRowSchema,
+    execute: () =>
+      sql`
+        SELECT
+          turns.thread_id AS "threadId",
+          turns.turn_id AS "turnId",
+          turns.state,
+          turns.requested_at AS "requestedAt",
+          turns.started_at AS "startedAt",
+          turns.completed_at AS "completedAt",
+          turns.assistant_message_id AS "assistantMessageId",
+          turns.source_proposed_plan_thread_id AS "sourceProposedPlanThreadId",
+          turns.source_proposed_plan_id AS "sourceProposedPlanId"
+        FROM projection_threads threads
+        JOIN projection_turns turns
+          ON turns.thread_id = threads.thread_id
+          AND turns.turn_id = threads.latest_turn_id
+        WHERE threads.deleted_at IS NULL
+          AND threads.archived_at IS NULL
+          AND threads.latest_turn_id IS NOT NULL
+        ORDER BY turns.thread_id ASC
+      `,
+  });
+
+  const listArchivedLatestTurnRows = SqlSchema.findAll({
+    Request: Schema.Void,
+    Result: ProjectionLatestTurnDbRowSchema,
+    execute: () =>
+      sql`
+        SELECT
+          turns.thread_id AS "threadId",
+          turns.turn_id AS "turnId",
+          turns.state,
+          turns.requested_at AS "requestedAt",
+          turns.started_at AS "startedAt",
+          turns.completed_at AS "completedAt",
+          turns.assistant_message_id AS "assistantMessageId",
+          turns.source_proposed_plan_thread_id AS "sourceProposedPlanThreadId",
+          turns.source_proposed_plan_id AS "sourceProposedPlanId"
+        FROM projection_threads threads
+        JOIN projection_turns turns
+          ON turns.thread_id = threads.thread_id
+          AND turns.turn_id = threads.latest_turn_id
+        WHERE threads.deleted_at IS NULL
+          AND threads.archived_at IS NOT NULL
+          AND threads.latest_turn_id IS NOT NULL
+        ORDER BY turns.thread_id ASC
       `,
   });
 
@@ -381,6 +677,27 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       `,
   });
 
+  const getActiveProjectRowById = SqlSchema.findOneOption({
+    Request: ProjectIdLookupInput,
+    Result: ProjectionProjectLookupRowSchema,
+    execute: ({ projectId }) =>
+      sql`
+        SELECT
+          project_id AS "projectId",
+          title,
+          workspace_root AS "workspaceRoot",
+          default_model_selection_json AS "defaultModelSelection",
+          scripts_json AS "scripts",
+          created_at AS "createdAt",
+          updated_at AS "updatedAt",
+          deleted_at AS "deletedAt"
+        FROM projection_projects
+        WHERE project_id = ${projectId}
+          AND deleted_at IS NULL
+        LIMIT 1
+      `,
+  });
+
   const getFirstActiveThreadIdByProject = SqlSchema.findOneOption({
     Request: ProjectIdLookupInput,
     Result: ProjectionThreadIdLookupRowSchema,
@@ -391,6 +708,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
         FROM projection_threads
         WHERE project_id = ${projectId}
           AND deleted_at IS NULL
+          AND archived_at IS NULL
         ORDER BY created_at ASC, thread_id ASC
         LIMIT 1
       `,
@@ -415,6 +733,148 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       `,
   });
 
+  const getActiveThreadRowById = SqlSchema.findOneOption({
+    Request: ThreadIdLookupInput,
+    Result: ProjectionThreadDbRowSchema,
+    execute: ({ threadId }) =>
+      sql`
+        SELECT
+          thread_id AS "threadId",
+          project_id AS "projectId",
+          title,
+          model_selection_json AS "modelSelection",
+          runtime_mode AS "runtimeMode",
+          interaction_mode AS "interactionMode",
+          branch,
+          worktree_path AS "worktreePath",
+          latest_turn_id AS "latestTurnId",
+          created_at AS "createdAt",
+          updated_at AS "updatedAt",
+          archived_at AS "archivedAt",
+          latest_user_message_at AS "latestUserMessageAt",
+          pending_approval_count AS "pendingApprovalCount",
+          pending_user_input_count AS "pendingUserInputCount",
+          has_actionable_proposed_plan AS "hasActionableProposedPlan",
+          deleted_at AS "deletedAt"
+        FROM projection_threads
+        WHERE thread_id = ${threadId}
+          AND deleted_at IS NULL
+          AND archived_at IS NULL
+        LIMIT 1
+      `,
+  });
+
+  const listThreadMessageRowsByThread = SqlSchema.findAll({
+    Request: ThreadIdLookupInput,
+    Result: ProjectionThreadMessageDbRowSchema,
+    execute: ({ threadId }) =>
+      sql`
+        SELECT
+          message_id AS "messageId",
+          thread_id AS "threadId",
+          turn_id AS "turnId",
+          role,
+          text,
+          attachments_json AS "attachments",
+          is_streaming AS "isStreaming",
+          created_at AS "createdAt",
+          updated_at AS "updatedAt"
+        FROM projection_thread_messages
+        WHERE thread_id = ${threadId}
+        ORDER BY created_at ASC, message_id ASC
+      `,
+  });
+
+  const listThreadProposedPlanRowsByThread = SqlSchema.findAll({
+    Request: ThreadIdLookupInput,
+    Result: ProjectionThreadProposedPlanDbRowSchema,
+    execute: ({ threadId }) =>
+      sql`
+        SELECT
+          plan_id AS "planId",
+          thread_id AS "threadId",
+          turn_id AS "turnId",
+          plan_markdown AS "planMarkdown",
+          implemented_at AS "implementedAt",
+          implementation_thread_id AS "implementationThreadId",
+          created_at AS "createdAt",
+          updated_at AS "updatedAt"
+        FROM projection_thread_proposed_plans
+        WHERE thread_id = ${threadId}
+        ORDER BY created_at ASC, plan_id ASC
+      `,
+  });
+
+  const listThreadActivityRowsByThread = SqlSchema.findAll({
+    Request: ThreadIdLookupInput,
+    Result: ProjectionThreadActivityDbRowSchema,
+    execute: ({ threadId }) =>
+      sql`
+        SELECT
+          activity_id AS "activityId",
+          thread_id AS "threadId",
+          turn_id AS "turnId",
+          tone,
+          kind,
+          summary,
+          payload_json AS "payload",
+          sequence,
+          created_at AS "createdAt"
+        FROM projection_thread_activities
+        WHERE thread_id = ${threadId}
+        ORDER BY
+          sequence ASC,
+          created_at ASC,
+          activity_id ASC
+      `,
+  });
+
+  const getThreadSessionRowByThread = SqlSchema.findOneOption({
+    Request: ThreadIdLookupInput,
+    Result: ProjectionThreadSessionDbRowSchema,
+    execute: ({ threadId }) =>
+      sql`
+        SELECT
+          thread_id AS "threadId",
+          status,
+          provider_name AS "providerName",
+          provider_instance_id AS "providerInstanceId",
+          runtime_mode AS "runtimeMode",
+          active_turn_id AS "activeTurnId",
+          last_error AS "lastError",
+          updated_at AS "updatedAt"
+        FROM projection_thread_sessions
+        WHERE thread_id = ${threadId}
+        LIMIT 1
+      `,
+  });
+
+  const getLatestTurnRowByThread = SqlSchema.findOneOption({
+    Request: ThreadIdLookupInput,
+    Result: ProjectionLatestTurnDbRowSchema,
+    execute: ({ threadId }) =>
+      sql`
+        SELECT
+          turns.thread_id AS "threadId",
+          turns.turn_id AS "turnId",
+          turns.state,
+          turns.requested_at AS "requestedAt",
+          turns.started_at AS "startedAt",
+          turns.completed_at AS "completedAt",
+          turns.assistant_message_id AS "assistantMessageId",
+          turns.source_proposed_plan_thread_id AS "sourceProposedPlanThreadId",
+          turns.source_proposed_plan_id AS "sourceProposedPlanId"
+        FROM projection_threads threads
+        JOIN projection_turns turns
+          ON turns.thread_id = threads.thread_id
+          AND turns.turn_id = threads.latest_turn_id
+        WHERE threads.thread_id = ${threadId}
+          AND threads.deleted_at IS NULL
+          AND threads.archived_at IS NULL
+        LIMIT 1
+      `,
+  });
+
   const listCheckpointRowsByThread = SqlSchema.findAll({
     Request: ThreadIdLookupInput,
     Result: ProjectionCheckpointDbRowSchema,
@@ -436,6 +896,38 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       `,
   });
 
+  const getFullThreadDiffContextRow = SqlSchema.findOneOption({
+    Request: FullThreadDiffContextLookupInput,
+    Result: ProjectionFullThreadDiffContextRowSchema,
+    execute: ({ threadId, checkpointTurnCount }) =>
+      sql`
+        SELECT
+          threads.thread_id AS "threadId",
+          threads.project_id AS "projectId",
+          projects.workspace_root AS "workspaceRoot",
+          threads.worktree_path AS "worktreePath",
+          (
+            SELECT MAX(turns.checkpoint_turn_count)
+            FROM projection_turns AS turns
+            WHERE turns.thread_id = threads.thread_id
+              AND turns.checkpoint_turn_count IS NOT NULL
+          ) AS "latestCheckpointTurnCount",
+          (
+            SELECT turns.checkpoint_ref
+            FROM projection_turns AS turns
+            WHERE turns.thread_id = threads.thread_id
+              AND turns.checkpoint_turn_count = ${checkpointTurnCount}
+            LIMIT 1
+          ) AS "toCheckpointRef"
+        FROM projection_threads AS threads
+        INNER JOIN projection_projects AS projects
+          ON projects.project_id = threads.project_id
+        WHERE threads.thread_id = ${threadId}
+          AND threads.deleted_at IS NULL
+        LIMIT 1
+      `,
+  });
+
   const getSnapshot: ProjectionSnapshotQueryShape["getSnapshot"] = () =>
     sql
       .withTransaction(
@@ -651,6 +1143,9 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                   threadId: row.threadId,
                   status: row.status,
                   providerName: row.providerName,
+                  ...(row.providerInstanceId !== null
+                    ? { providerInstanceId: row.providerInstanceId }
+                    : {}),
                   runtimeMode: row.runtimeMode,
                   activeTurnId: row.activeTurnId,
                   lastError: row.lastError,
@@ -658,15 +1153,9 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                 });
               }
 
-              const repositoryIdentities = new Map(
-                yield* Effect.forEach(
-                  projectRows,
-                  (row) =>
-                    repositoryIdentityResolver
-                      .resolve(row.workspaceRoot)
-                      .pipe(Effect.map((identity) => [row.projectId, identity] as const)),
-                  { concurrency: repositoryIdentityResolutionConcurrency },
-                ),
+              const repositoryIdentities = yield* resolveRepositoryIdentitiesForProjects(
+                projectRows,
+                { includeDeleted: true },
               );
 
               const projects: ReadonlyArray<OrchestrationProject> = projectRows.map((row) => ({
@@ -706,7 +1195,7 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
                 snapshotSequence: computeSnapshotSequence(stateRows),
                 projects,
                 threads,
-                updatedAt: updatedAt ?? new Date(0).toISOString(),
+                updatedAt: updatedAt ?? "1970-01-01T00:00:00.000Z",
               };
 
               return yield* decodeReadModel(snapshot).pipe(
@@ -724,8 +1213,477 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
         }),
       );
 
-  const getCounts: ProjectionSnapshotQueryShape["getCounts"] = () =>
-    readProjectionCounts(undefined).pipe(
+  const getCommandReadModel: ProjectionSnapshotQueryShape["getCommandReadModel"] = () =>
+    sql
+      .withTransaction(
+        Effect.all([
+          listProjectRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getCommandReadModel:listProjects:query",
+                "ProjectionSnapshotQuery.getCommandReadModel:listProjects:decodeRows",
+              ),
+            ),
+          ),
+          listThreadRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getCommandReadModel:listThreads:query",
+                "ProjectionSnapshotQuery.getCommandReadModel:listThreads:decodeRows",
+              ),
+            ),
+          ),
+          listThreadProposedPlanRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getCommandReadModel:listThreadProposedPlans:query",
+                "ProjectionSnapshotQuery.getCommandReadModel:listThreadProposedPlans:decodeRows",
+              ),
+            ),
+          ),
+          listThreadSessionRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getCommandReadModel:listThreadSessions:query",
+                "ProjectionSnapshotQuery.getCommandReadModel:listThreadSessions:decodeRows",
+              ),
+            ),
+          ),
+          listLatestTurnRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getCommandReadModel:listLatestTurns:query",
+                "ProjectionSnapshotQuery.getCommandReadModel:listLatestTurns:decodeRows",
+              ),
+            ),
+          ),
+          listProjectionStateRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getCommandReadModel:listProjectionState:query",
+                "ProjectionSnapshotQuery.getCommandReadModel:listProjectionState:decodeRows",
+              ),
+            ),
+          ),
+        ]),
+      )
+      .pipe(
+        Effect.flatMap(
+          ([projectRows, threadRows, proposedPlanRows, sessionRows, latestTurnRows, stateRows]) =>
+            Effect.sync(() => {
+              let updatedAt: string | null = null;
+              const projects: OrchestrationProject[] = [];
+              const threads: OrchestrationThread[] = [];
+
+              for (let index = 0; index < projectRows.length; index += 1) {
+                const row = projectRows[index];
+                if (!row) {
+                  continue;
+                }
+                updatedAt = maxIso(updatedAt, row.updatedAt);
+                projects.push({
+                  id: row.projectId,
+                  title: row.title,
+                  workspaceRoot: row.workspaceRoot,
+                  defaultModelSelection: row.defaultModelSelection,
+                  scripts: row.scripts,
+                  createdAt: row.createdAt,
+                  updatedAt: row.updatedAt,
+                  deletedAt: row.deletedAt,
+                });
+              }
+              for (let index = 0; index < threadRows.length; index += 1) {
+                const row = threadRows[index];
+                if (!row) {
+                  continue;
+                }
+                updatedAt = maxIso(updatedAt, row.updatedAt);
+              }
+              for (let index = 0; index < proposedPlanRows.length; index += 1) {
+                const row = proposedPlanRows[index];
+                if (!row) {
+                  continue;
+                }
+                updatedAt = maxIso(updatedAt, row.updatedAt);
+              }
+              for (let index = 0; index < sessionRows.length; index += 1) {
+                const row = sessionRows[index];
+                if (!row) {
+                  continue;
+                }
+                updatedAt = maxIso(updatedAt, row.updatedAt);
+              }
+              for (let index = 0; index < latestTurnRows.length; index += 1) {
+                const row = latestTurnRows[index];
+                if (!row) {
+                  continue;
+                }
+                updatedAt = maxIso(updatedAt, row.requestedAt);
+                if (row.startedAt !== null) {
+                  updatedAt = maxIso(updatedAt, row.startedAt);
+                }
+                if (row.completedAt !== null) {
+                  updatedAt = maxIso(updatedAt, row.completedAt);
+                }
+              }
+              for (let index = 0; index < stateRows.length; index += 1) {
+                const row = stateRows[index];
+                if (!row) {
+                  continue;
+                }
+                updatedAt = maxIso(updatedAt, row.updatedAt);
+              }
+
+              const latestTurnByThread = new Map<string, OrchestrationLatestTurn>();
+              for (let index = 0; index < latestTurnRows.length; index += 1) {
+                const row = latestTurnRows[index];
+                if (!row) {
+                  continue;
+                }
+                latestTurnByThread.set(row.threadId, mapLatestTurn(row));
+              }
+              const proposedPlansByThread = new Map<string, Array<OrchestrationProposedPlan>>();
+              const sessionByThread = new Map<string, OrchestrationSession>();
+
+              for (let index = 0; index < sessionRows.length; index += 1) {
+                const row = sessionRows[index];
+                if (!row) {
+                  continue;
+                }
+                sessionByThread.set(row.threadId, mapSessionRow(row));
+              }
+
+              for (let index = 0; index < proposedPlanRows.length; index += 1) {
+                const row = proposedPlanRows[index];
+                if (!row) {
+                  continue;
+                }
+                const threadProposedPlans = proposedPlansByThread.get(row.threadId) ?? [];
+                threadProposedPlans.push(mapProposedPlanRow(row));
+                proposedPlansByThread.set(row.threadId, threadProposedPlans);
+              }
+
+              for (let index = 0; index < threadRows.length; index += 1) {
+                const row = threadRows[index];
+                if (!row) {
+                  continue;
+                }
+                threads.push({
+                  id: row.threadId,
+                  projectId: row.projectId,
+                  title: row.title,
+                  modelSelection: row.modelSelection,
+                  runtimeMode: row.runtimeMode,
+                  interactionMode: row.interactionMode,
+                  branch: row.branch,
+                  worktreePath: row.worktreePath,
+                  latestTurn: latestTurnByThread.get(row.threadId) ?? null,
+                  createdAt: row.createdAt,
+                  updatedAt: row.updatedAt,
+                  archivedAt: row.archivedAt,
+                  deletedAt: row.deletedAt,
+                  messages: [],
+                  proposedPlans: proposedPlansByThread.get(row.threadId) ?? [],
+                  activities: [],
+                  checkpoints: [],
+                  session: sessionByThread.get(row.threadId) ?? null,
+                });
+              }
+
+              return {
+                snapshotSequence: computeSnapshotSequence(stateRows),
+                projects,
+                threads,
+                updatedAt: updatedAt ?? "1970-01-01T00:00:00.000Z",
+              } satisfies OrchestrationReadModel;
+            }),
+        ),
+        Effect.mapError((error) => {
+          if (isPersistenceError(error)) {
+            return error;
+          }
+          return toPersistenceSqlError("ProjectionSnapshotQuery.getCommandReadModel:query")(error);
+        }),
+      );
+
+  const getShellSnapshot: ProjectionSnapshotQueryShape["getShellSnapshot"] = () =>
+    sql
+      .withTransaction(
+        Effect.all([
+          listProjectRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getShellSnapshot:listProjects:query",
+                "ProjectionSnapshotQuery.getShellSnapshot:listProjects:decodeRows",
+              ),
+            ),
+          ),
+          listActiveThreadRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getShellSnapshot:listThreads:query",
+                "ProjectionSnapshotQuery.getShellSnapshot:listThreads:decodeRows",
+              ),
+            ),
+          ),
+          listActiveThreadSessionRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getShellSnapshot:listThreadSessions:query",
+                "ProjectionSnapshotQuery.getShellSnapshot:listThreadSessions:decodeRows",
+              ),
+            ),
+          ),
+          listActiveLatestTurnRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getShellSnapshot:listLatestTurns:query",
+                "ProjectionSnapshotQuery.getShellSnapshot:listLatestTurns:decodeRows",
+              ),
+            ),
+          ),
+          listProjectionStateRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getShellSnapshot:listProjectionState:query",
+                "ProjectionSnapshotQuery.getShellSnapshot:listProjectionState:decodeRows",
+              ),
+            ),
+          ),
+        ]),
+      )
+      .pipe(
+        Effect.flatMap(([projectRows, threadRows, sessionRows, latestTurnRows, stateRows]) =>
+          Effect.gen(function* () {
+            let updatedAt: string | null = null;
+            for (const row of projectRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+            for (const row of threadRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+            for (const row of sessionRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+            for (const row of latestTurnRows) {
+              updatedAt = maxIso(updatedAt, row.requestedAt);
+              if (row.startedAt !== null) {
+                updatedAt = maxIso(updatedAt, row.startedAt);
+              }
+              if (row.completedAt !== null) {
+                updatedAt = maxIso(updatedAt, row.completedAt);
+              }
+            }
+            for (const row of stateRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+
+            const repositoryIdentities = yield* resolveRepositoryIdentitiesForProjects(projectRows);
+            const latestTurnByThread = new Map(
+              latestTurnRows.map((row) => [row.threadId, mapLatestTurn(row)] as const),
+            );
+            const sessionByThread = new Map(
+              sessionRows.map((row) => [row.threadId, mapSessionRow(row)] as const),
+            );
+
+            const snapshot = {
+              snapshotSequence: computeSnapshotSequence(stateRows),
+              projects: projectRows
+                .filter((row) => row.deletedAt === null)
+                .map((row) =>
+                  mapProjectShellRow(row, repositoryIdentities.get(row.projectId) ?? null),
+                ),
+              threads: threadRows
+                .filter((row) => row.deletedAt === null)
+                .map(
+                  (row): OrchestrationThreadShell => ({
+                    id: row.threadId,
+                    projectId: row.projectId,
+                    title: row.title,
+                    modelSelection: row.modelSelection,
+                    runtimeMode: row.runtimeMode,
+                    interactionMode: row.interactionMode,
+                    branch: row.branch,
+                    worktreePath: row.worktreePath,
+                    latestTurn: latestTurnByThread.get(row.threadId) ?? null,
+                    createdAt: row.createdAt,
+                    updatedAt: row.updatedAt,
+                    archivedAt: row.archivedAt,
+                    session: sessionByThread.get(row.threadId) ?? null,
+                    latestUserMessageAt: row.latestUserMessageAt,
+                    hasPendingApprovals: row.pendingApprovalCount > 0,
+                    hasPendingUserInput: row.pendingUserInputCount > 0,
+                    hasActionableProposedPlan: row.hasActionableProposedPlan > 0,
+                  }),
+                ),
+              updatedAt: updatedAt ?? "1970-01-01T00:00:00.000Z",
+            };
+
+            return yield* decodeShellSnapshot(snapshot).pipe(
+              Effect.mapError(
+                toPersistenceDecodeError(
+                  "ProjectionSnapshotQuery.getShellSnapshot:decodeShellSnapshot",
+                ),
+              ),
+            );
+          }),
+        ),
+        Effect.mapError((error) => {
+          if (isPersistenceError(error)) {
+            return error;
+          }
+          return toPersistenceSqlError("ProjectionSnapshotQuery.getShellSnapshot:query")(error);
+        }),
+      );
+
+  const getArchivedShellSnapshot: ProjectionSnapshotQueryShape["getArchivedShellSnapshot"] = () =>
+    sql
+      .withTransaction(
+        Effect.all([
+          listProjectRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listProjects:query",
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listProjects:decodeRows",
+              ),
+            ),
+          ),
+          listArchivedThreadRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listThreads:query",
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listThreads:decodeRows",
+              ),
+            ),
+          ),
+          listArchivedThreadSessionRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listThreadSessions:query",
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listThreadSessions:decodeRows",
+              ),
+            ),
+          ),
+          listArchivedLatestTurnRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listLatestTurns:query",
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listLatestTurns:decodeRows",
+              ),
+            ),
+          ),
+          listProjectionStateRows(undefined).pipe(
+            Effect.mapError(
+              toPersistenceSqlOrDecodeError(
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listProjectionState:query",
+                "ProjectionSnapshotQuery.getArchivedShellSnapshot:listProjectionState:decodeRows",
+              ),
+            ),
+          ),
+        ]),
+      )
+      .pipe(
+        Effect.flatMap(([projectRows, threadRows, sessionRows, latestTurnRows, stateRows]) =>
+          Effect.gen(function* () {
+            let updatedAt: string | null = null;
+            for (const row of projectRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+            for (const row of threadRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+            for (const row of sessionRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+            for (const row of latestTurnRows) {
+              updatedAt = maxIso(updatedAt, row.requestedAt);
+              if (row.startedAt !== null) {
+                updatedAt = maxIso(updatedAt, row.startedAt);
+              }
+              if (row.completedAt !== null) {
+                updatedAt = maxIso(updatedAt, row.completedAt);
+              }
+            }
+            for (const row of stateRows) {
+              updatedAt = maxIso(updatedAt, row.updatedAt);
+            }
+
+            const activeProjectIds = new Set(threadRows.map((row) => row.projectId));
+            const repositoryIdentities = yield* resolveRepositoryIdentitiesForProjects(
+              projectRows.filter((row) => activeProjectIds.has(row.projectId)),
+            );
+            const latestTurnByThread = new Map(
+              latestTurnRows.map((row) => [row.threadId, mapLatestTurn(row)] as const),
+            );
+            const sessionByThread = new Map(
+              sessionRows.map((row) => [row.threadId, mapSessionRow(row)] as const),
+            );
+
+            const snapshot = {
+              snapshotSequence: computeSnapshotSequence(stateRows),
+              projects: projectRows
+                .filter((row) => row.deletedAt === null && activeProjectIds.has(row.projectId))
+                .map((row) =>
+                  mapProjectShellRow(row, repositoryIdentities.get(row.projectId) ?? null),
+                ),
+              threads: threadRows.map(
+                (row): OrchestrationThreadShell => ({
+                  id: row.threadId,
+                  projectId: row.projectId,
+                  title: row.title,
+                  modelSelection: row.modelSelection,
+                  runtimeMode: row.runtimeMode,
+                  interactionMode: row.interactionMode,
+                  branch: row.branch,
+                  worktreePath: row.worktreePath,
+                  latestTurn: latestTurnByThread.get(row.threadId) ?? null,
+                  createdAt: row.createdAt,
+                  updatedAt: row.updatedAt,
+                  archivedAt: row.archivedAt,
+                  session: sessionByThread.get(row.threadId) ?? null,
+                  latestUserMessageAt: row.latestUserMessageAt,
+                  hasPendingApprovals: row.pendingApprovalCount > 0,
+                  hasPendingUserInput: row.pendingUserInputCount > 0,
+                  hasActionableProposedPlan: row.hasActionableProposedPlan > 0,
+                }),
+              ),
+              updatedAt: updatedAt ?? "1970-01-01T00:00:00.000Z",
+            };
+
+            return yield* decodeShellSnapshot(snapshot).pipe(
+              Effect.mapError(
+                toPersistenceDecodeError(
+                  "ProjectionSnapshotQuery.getArchivedShellSnapshot:decodeShellSnapshot",
+                ),
+              ),
+            );
+          }),
+        ),
+        Effect.mapError((error) => {
+          if (isPersistenceError(error)) {
+            return error;
+          }
+          return toPersistenceSqlError("ProjectionSnapshotQuery.getArchivedShellSnapshot:query")(
+            error,
+          );
+        }),
+      );
+
+  const getSnapshotSequence: ProjectionSnapshotQueryShape["getSnapshotSequence"] = () =>
+    listProjectionStateRows(undefined).pipe(
+      Effect.mapError(
+        toPersistenceSqlOrDecodeError(
+          "ProjectionSnapshotQuery.getSnapshotSequence:query",
+          "ProjectionSnapshotQuery.getSnapshotSequence:decodeRows",
+        ),
+      ),
+      Effect.map((stateRows) => ({
+        snapshotSequence: computeSnapshotSequence(stateRows),
+      })),
+    );
+
+  const getCounts: ProjectionSnapshotQueryShape["getCounts"] = () =>
+    readProjectionCounts(undefined).pipe(
       Effect.mapError(
         toPersistenceSqlOrDecodeError(
           "ProjectionSnapshotQuery.getCounts:query",
@@ -770,6 +1728,27 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
         ),
       );
 
+  const getProjectShellById: ProjectionSnapshotQueryShape["getProjectShellById"] = (projectId) =>
+    getActiveProjectRowById({ projectId }).pipe(
+      Effect.mapError(
+        toPersistenceSqlOrDecodeError(
+          "ProjectionSnapshotQuery.getProjectShellById:query",
+          "ProjectionSnapshotQuery.getProjectShellById:decodeRow",
+        ),
+      ),
+      Effect.flatMap((option) =>
+        Option.isNone(option)
+          ? Effect.succeed(Option.none<OrchestrationProjectShell>())
+          : repositoryIdentityResolver
+              .resolve(option.value.workspaceRoot)
+              .pipe(
+                Effect.map((repositoryIdentity) =>
+                  Option.some(mapProjectShellRow(option.value, repositoryIdentity)),
+                ),
+              ),
+      ),
+    );
+
   const getFirstActiveThreadIdByProjectId: ProjectionSnapshotQueryShape["getFirstActiveThreadIdByProjectId"] =
     (projectId) =>
       getFirstActiveThreadIdByProject({ projectId }).pipe(
@@ -826,12 +1805,242 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       });
     });
 
+  const getFullThreadDiffContext: NonNullable<
+    ProjectionSnapshotQueryShape["getFullThreadDiffContext"]
+  > = (threadId, toTurnCount) =>
+    Effect.gen(function* () {
+      const row = yield* getFullThreadDiffContextRow({
+        threadId,
+        checkpointTurnCount: toTurnCount,
+      }).pipe(
+        Effect.mapError(
+          toPersistenceSqlOrDecodeError(
+            "ProjectionSnapshotQuery.getFullThreadDiffContext:query",
+            "ProjectionSnapshotQuery.getFullThreadDiffContext:decodeRow",
+          ),
+        ),
+      );
+      if (Option.isNone(row)) {
+        return Option.none<ProjectionFullThreadDiffContext>();
+      }
+
+      return Option.some({
+        threadId: row.value.threadId,
+        projectId: row.value.projectId,
+        workspaceRoot: row.value.workspaceRoot,
+        worktreePath: row.value.worktreePath,
+        latestCheckpointTurnCount: row.value.latestCheckpointTurnCount ?? 0,
+        toCheckpointRef: row.value.toCheckpointRef,
+      });
+    });
+
+  const getThreadShellById: ProjectionSnapshotQueryShape["getThreadShellById"] = (threadId) =>
+    Effect.gen(function* () {
+      const [threadRow, latestTurnRow, sessionRow] = yield* Effect.all([
+        getActiveThreadRowById({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadShellById:getThread:query",
+              "ProjectionSnapshotQuery.getThreadShellById:getThread:decodeRow",
+            ),
+          ),
+        ),
+        getLatestTurnRowByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadShellById:getLatestTurn:query",
+              "ProjectionSnapshotQuery.getThreadShellById:getLatestTurn:decodeRow",
+            ),
+          ),
+        ),
+        getThreadSessionRowByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadShellById:getSession:query",
+              "ProjectionSnapshotQuery.getThreadShellById:getSession:decodeRow",
+            ),
+          ),
+        ),
+      ]);
+
+      if (Option.isNone(threadRow)) {
+        return Option.none<OrchestrationThreadShell>();
+      }
+
+      return Option.some({
+        id: threadRow.value.threadId,
+        projectId: threadRow.value.projectId,
+        title: threadRow.value.title,
+        modelSelection: threadRow.value.modelSelection,
+        runtimeMode: threadRow.value.runtimeMode,
+        interactionMode: threadRow.value.interactionMode,
+        branch: threadRow.value.branch,
+        worktreePath: threadRow.value.worktreePath,
+        latestTurn: Option.isSome(latestTurnRow) ? mapLatestTurn(latestTurnRow.value) : null,
+        createdAt: threadRow.value.createdAt,
+        updatedAt: threadRow.value.updatedAt,
+        archivedAt: threadRow.value.archivedAt,
+        session: Option.isSome(sessionRow) ? mapSessionRow(sessionRow.value) : null,
+        latestUserMessageAt: threadRow.value.latestUserMessageAt,
+        hasPendingApprovals: threadRow.value.pendingApprovalCount > 0,
+        hasPendingUserInput: threadRow.value.pendingUserInputCount > 0,
+        hasActionableProposedPlan: threadRow.value.hasActionableProposedPlan > 0,
+      } satisfies OrchestrationThreadShell);
+    });
+
+  const getThreadDetailById: ProjectionSnapshotQueryShape["getThreadDetailById"] = (threadId) =>
+    Effect.gen(function* () {
+      const [
+        threadRow,
+        messageRows,
+        proposedPlanRows,
+        activityRows,
+        checkpointRows,
+        latestTurnRow,
+        sessionRow,
+      ] = yield* Effect.all([
+        getActiveThreadRowById({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadDetailById:getThread:query",
+              "ProjectionSnapshotQuery.getThreadDetailById:getThread:decodeRow",
+            ),
+          ),
+        ),
+        listThreadMessageRowsByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadDetailById:listMessages:query",
+              "ProjectionSnapshotQuery.getThreadDetailById:listMessages:decodeRows",
+            ),
+          ),
+        ),
+        listThreadProposedPlanRowsByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadDetailById:listPlans:query",
+              "ProjectionSnapshotQuery.getThreadDetailById:listPlans:decodeRows",
+            ),
+          ),
+        ),
+        listThreadActivityRowsByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadDetailById:listActivities:query",
+              "ProjectionSnapshotQuery.getThreadDetailById:listActivities:decodeRows",
+            ),
+          ),
+        ),
+        listCheckpointRowsByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadDetailById:listCheckpoints:query",
+              "ProjectionSnapshotQuery.getThreadDetailById:listCheckpoints:decodeRows",
+            ),
+          ),
+        ),
+        getLatestTurnRowByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadDetailById:getLatestTurn:query",
+              "ProjectionSnapshotQuery.getThreadDetailById:getLatestTurn:decodeRow",
+            ),
+          ),
+        ),
+        getThreadSessionRowByThread({ threadId }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "ProjectionSnapshotQuery.getThreadDetailById:getSession:query",
+              "ProjectionSnapshotQuery.getThreadDetailById:getSession:decodeRow",
+            ),
+          ),
+        ),
+      ]);
+
+      if (Option.isNone(threadRow)) {
+        return Option.none<OrchestrationThread>();
+      }
+
+      const thread = {
+        id: threadRow.value.threadId,
+        projectId: threadRow.value.projectId,
+        title: threadRow.value.title,
+        modelSelection: threadRow.value.modelSelection,
+        runtimeMode: threadRow.value.runtimeMode,
+        interactionMode: threadRow.value.interactionMode,
+        branch: threadRow.value.branch,
+        worktreePath: threadRow.value.worktreePath,
+        latestTurn: Option.isSome(latestTurnRow) ? mapLatestTurn(latestTurnRow.value) : null,
+        createdAt: threadRow.value.createdAt,
+        updatedAt: threadRow.value.updatedAt,
+        archivedAt: threadRow.value.archivedAt,
+        deletedAt: null,
+        messages: messageRows.map((row) => {
+          const message = {
+            id: row.messageId,
+            role: row.role,
+            text: row.text,
+            turnId: row.turnId,
+            streaming: row.isStreaming === 1,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+          };
+          if (row.attachments !== null) {
+            return Object.assign(message, { attachments: row.attachments });
+          }
+          return message;
+        }),
+        proposedPlans: proposedPlanRows.map(mapProposedPlanRow),
+        activities: activityRows.map((row) => {
+          const activity = {
+            id: row.activityId,
+            tone: row.tone,
+            kind: row.kind,
+            summary: row.summary,
+            payload: row.payload,
+            turnId: row.turnId,
+            createdAt: row.createdAt,
+          };
+          if (row.sequence !== null) {
+            return Object.assign(activity, { sequence: row.sequence });
+          }
+          return activity;
+        }),
+        checkpoints: checkpointRows.map((row) => ({
+          turnId: row.turnId,
+          checkpointTurnCount: row.checkpointTurnCount,
+          checkpointRef: row.checkpointRef,
+          status: row.status,
+          files: row.files,
+          assistantMessageId: row.assistantMessageId,
+          completedAt: row.completedAt,
+        })),
+        session: Option.isSome(sessionRow) ? mapSessionRow(sessionRow.value) : null,
+      };
+
+      return Option.some(
+        yield* decodeThread(thread).pipe(
+          Effect.mapError(
+            toPersistenceDecodeError("ProjectionSnapshotQuery.getThreadDetailById:decodeThread"),
+          ),
+        ),
+      );
+    });
+
   return {
+    getCommandReadModel,
     getSnapshot,
+    getShellSnapshot,
+    getArchivedShellSnapshot,
+    getSnapshotSequence,
     getCounts,
     getActiveProjectByWorkspaceRoot,
+    getProjectShellById,
     getFirstActiveThreadIdByProjectId,
     getThreadCheckpointContext,
+    getFullThreadDiffContext,
+    getThreadShellById,
+    getThreadDetailById,
   } satisfies ProjectionSnapshotQueryShape;
 });
 
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
index ded64fb9e6c..571164fad93 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
@@ -1,8 +1,16 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import type { ModelSelection, ProviderRuntimeEvent, ProviderSession } from "@t3tools/contracts";
+import {
+  ModelSelection,
+  ProviderRuntimeEvent,
+  ProviderSession,
+  ProviderDriverKind,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import {
   ApprovalRequestId,
   CommandId,
@@ -13,7 +21,13 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Effect, Exit, Layer, ManagedRuntime, PubSub, Scope, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as PubSub from "effect/PubSub";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { deriveServerPaths, ServerConfig } from "../../config.ts";
@@ -26,17 +40,24 @@ import {
   ProviderService,
   type ProviderServiceShape,
 } from "../../provider/Services/ProviderService.ts";
-import { GitCore, type GitCoreShape } from "../../git/Services/GitCore.ts";
-import { TextGeneration, type TextGenerationShape } from "../../git/Services/TextGeneration.ts";
+import { TextGeneration, type TextGenerationShape } from "../../textGeneration/TextGeneration.ts";
 import { RepositoryIdentityResolverLive } from "../../project/Layers/RepositoryIdentityResolver.ts";
 import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
 import { OrchestrationProjectionPipelineLive } from "./ProjectionPipeline.ts";
 import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQuery.ts";
-import { ProviderCommandReactorLive } from "./ProviderCommandReactor.ts";
+import {
+  providerErrorLabel,
+  providerErrorLabelFromInstanceHint,
+  ProviderCommandReactorLive,
+} from "./ProviderCommandReactor.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import { ProviderCommandReactor } from "../Services/ProviderCommandReactor.ts";
+import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Clock from "effect/Clock";
 import { ServerSettingsService } from "../../serverSettings.ts";
+import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
+import { GitWorkflowService, type GitWorkflowServiceShape } from "../../git/GitWorkflowService.ts";
 
 const asProjectId = (value: string): ProjectId => ProjectId.make(value);
 const asApprovalRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.make(value);
@@ -50,15 +71,15 @@ async function waitFor(
   predicate: () => boolean | Promise<boolean>,
   timeoutMs = 2000,
 ): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
+  const deadline = (await Effect.runPromise(Clock.currentTimeMillis)) + timeoutMs;
   const poll = async (): Promise<void> => {
     if (await predicate()) {
       return;
     }
-    if (Date.now() >= deadline) {
+    if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
       throw new Error("Timed out waiting for expectation.");
     }
-    await new Promise((resolve) => setTimeout(resolve, 10));
+    await Effect.runPromise(Effect.yieldNow);
     return poll();
   };
 
@@ -67,7 +88,7 @@ async function waitFor(
 
 describe("ProviderCommandReactor", () => {
   let runtime: ManagedRuntime.ManagedRuntime<
-    OrchestrationEngineService | ProviderCommandReactor,
+    OrchestrationEngineService | ProviderCommandReactor | ProjectionSnapshotQuery,
     unknown
   > | null = null;
   let scope: Scope.Closeable | null = null;
@@ -93,12 +114,36 @@ describe("ProviderCommandReactor", () => {
     createdBaseDirs.clear();
   });
 
+  describe("provider error attribution", () => {
+    it("uses the current provider instance slug when current instance lookup fails", () => {
+      expect(
+        providerErrorLabelFromInstanceHint({
+          instanceId: "codex_personal",
+          modelSelectionInstanceId: "codex",
+          sessionProvider: "codex",
+        }),
+      ).toBe("codex_personal");
+    });
+
+    it("uses the desired provider instance slug when desired instance lookup fails", () => {
+      expect(
+        providerErrorLabelFromInstanceHint({
+          instanceId: "claude_openrouter",
+        }),
+      ).toBe("claude_openrouter");
+    });
+
+    it("uses the unknown driver kind when the resolved driver is not registered locally", () => {
+      expect(providerErrorLabel("third_party_driver")).toBe("third_party_driver");
+    });
+  });
+
   async function createHarness(input?: {
     readonly baseDir?: string;
     readonly threadModelSelection?: ModelSelection;
     readonly sessionModelSwitch?: "unsupported" | "in-session";
   }) {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const baseDir = input?.baseDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "t3code-reactor-"));
     createdBaseDirs.add(baseDir);
     const { stateDir } = deriveServerPathsSync(baseDir, undefined);
@@ -107,7 +152,7 @@ describe("ProviderCommandReactor", () => {
     let nextSessionIndex = 1;
     const runtimeSessions: Array<ProviderSession> = [];
     const modelSelection = input?.threadModelSelection ?? {
-      provider: "codex",
+      instanceId: ProviderInstanceId.make("codex"),
       model: "gpt-5-codex",
     };
     const startSession = vi.fn((_: unknown, input: unknown) => {
@@ -123,8 +168,24 @@ describe("ProviderCommandReactor", () => {
         typeof input.threadId === "string"
           ? ThreadId.make(input.threadId)
           : ThreadId.make(`thread-${sessionIndex}`);
+      const inputModelSelection =
+        typeof input === "object" && input !== null && "modelSelection" in input
+          ? (input.modelSelection as ModelSelection | undefined)
+          : undefined;
+      const providerInstanceId =
+        typeof input === "object" && input !== null && "providerInstanceId" in input
+          ? (input.providerInstanceId as ProviderInstanceId | undefined)
+          : inputModelSelection?.instanceId;
+      const provider =
+        typeof input === "object" &&
+        input !== null &&
+        "provider" in input &&
+        typeof input.provider === "string"
+          ? (input.provider as ProviderSession["provider"])
+          : ProviderDriverKind.make(inputModelSelection?.instanceId ?? modelSelection.instanceId);
       const session: ProviderSession = {
-        provider: modelSelection.provider,
+        provider,
+        ...(providerInstanceId ? { providerInstanceId } : {}),
         status: "ready" as const,
         runtimeMode:
           typeof input === "object" &&
@@ -133,7 +194,15 @@ describe("ProviderCommandReactor", () => {
           (input.runtimeMode === "approval-required" || input.runtimeMode === "full-access")
             ? input.runtimeMode
             : "full-access",
-        ...(modelSelection.model !== undefined ? { model: modelSelection.model } : {}),
+        ...(typeof input === "object" &&
+        input !== null &&
+        "cwd" in input &&
+        typeof input.cwd === "string"
+          ? { cwd: input.cwd }
+          : {}),
+        ...((inputModelSelection?.model ?? modelSelection.model)
+          ? { model: inputModelSelection?.model ?? modelSelection.model }
+          : {}),
         threadId,
         resumeCursor: resumeCursor ?? { opaque: `resume-${sessionIndex}` },
         createdAt: now,
@@ -177,6 +246,24 @@ describe("ProviderCommandReactor", () => {
             : "renamed-branch",
       }),
     );
+    const refreshStatus = vi.fn((_: string) =>
+      Effect.succeed({
+        isRepo: true,
+        hasPrimaryRemote: true,
+        isDefaultRef: false,
+        refName: "renamed-branch",
+        hasWorkingTreeChanges: false,
+        workingTree: {
+          files: [],
+          insertions: 0,
+          deletions: 0,
+        },
+        hasUpstream: true,
+        aheadCount: 0,
+        behindCount: 0,
+        pr: null,
+      }),
+    );
     const generateBranchName = vi.fn<TextGenerationShape["generateBranchName"]>((_) =>
       Effect.fail(
         new TextGenerationError({
@@ -207,6 +294,25 @@ describe("ProviderCommandReactor", () => {
         Effect.succeed({
           sessionModelSwitch: input?.sessionModelSwitch ?? "in-session",
         }),
+      getInstanceInfo: (instanceId) => {
+        const raw = String(instanceId);
+        const driverKind = ProviderDriverKind.make(
+          raw.startsWith("claude") ? "claudeAgent" : raw.startsWith("codex") ? "codex" : raw,
+        );
+        return Effect.succeed({
+          instanceId,
+          driverKind,
+          displayName: undefined,
+          enabled: true,
+          continuationIdentity: {
+            driverKind,
+            continuationKey:
+              driverKind === ProviderDriverKind.make("codex")
+                ? "codex:home:/shared-codex"
+                : `${driverKind}:instance:${instanceId}`,
+          },
+        });
+      },
       rollbackConversation: () => unsupported(),
       get streamEvents() {
         return Stream.fromPubSub(runtimeEventPubSub);
@@ -221,10 +327,28 @@ describe("ProviderCommandReactor", () => {
       Layer.provide(RepositoryIdentityResolverLive),
       Layer.provide(SqlitePersistenceMemory),
     );
+    const projectionSnapshotLayer = OrchestrationProjectionSnapshotQueryLive.pipe(
+      Layer.provide(RepositoryIdentityResolverLive),
+      Layer.provide(SqlitePersistenceMemory),
+    );
     const layer = ProviderCommandReactorLive.pipe(
       Layer.provideMerge(orchestrationLayer),
+      Layer.provideMerge(projectionSnapshotLayer),
       Layer.provideMerge(Layer.succeed(ProviderService, service)),
-      Layer.provideMerge(Layer.succeed(GitCore, { renameBranch } as unknown as GitCoreShape)),
+      Layer.provideMerge(
+        Layer.mock(GitWorkflowService)({
+          renameBranch,
+        } satisfies Partial<GitWorkflowServiceShape>),
+      ),
+      Layer.provideMerge(
+        Layer.succeed(VcsStatusBroadcaster, {
+          getStatus: () => Effect.die("getStatus should not be called in this test"),
+          refreshLocalStatus: () =>
+            Effect.die("refreshLocalStatus should not be called in this test"),
+          refreshStatus,
+          streamStatus: () => Stream.die("streamStatus should not be called in this test"),
+        }),
+      ),
       Layer.provideMerge(
         Layer.mock(TextGeneration, {
           generateBranchName,
@@ -235,9 +359,10 @@ describe("ProviderCommandReactor", () => {
       Layer.provideMerge(ServerConfig.layerTest(process.cwd(), baseDir)),
       Layer.provideMerge(NodeServices.layer),
     );
-    const runtime = ManagedRuntime.make(layer);
+    runtime = ManagedRuntime.make(layer);
 
     const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
+    const snapshotQuery = await runtime.runPromise(Effect.service(ProjectionSnapshotQuery));
     const reactor = await runtime.runPromise(Effect.service(ProviderCommandReactor));
     scope = await Effect.runPromise(Scope.make("sequential"));
     await Effect.runPromise(reactor.start().pipe(Scope.provide(scope)));
@@ -272,6 +397,7 @@ describe("ProviderCommandReactor", () => {
 
     return {
       engine,
+      readModel: () => Effect.runPromise(snapshotQuery.getSnapshot()),
       startSession,
       sendTurn,
       interruptTurn,
@@ -279,8 +405,10 @@ describe("ProviderCommandReactor", () => {
       respondToUserInput,
       stopSession,
       renameBranch,
+      refreshStatus,
       generateBranchName,
       generateThreadTitle,
+      runtimeSessions,
       stateDir,
       drain,
     };
@@ -288,7 +416,7 @@ describe("ProviderCommandReactor", () => {
 
   it("reacts to thread.turn.start by ensuring session and sending provider turn", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -313,13 +441,13 @@ describe("ProviderCommandReactor", () => {
     expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
       cwd: "/tmp/provider-project",
       modelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
       runtimeMode: "approval-required",
     });
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.session?.threadId).toBe("thread-1");
     expect(thread?.session?.runtimeMode).toBe("approval-required");
@@ -327,7 +455,7 @@ describe("ProviderCommandReactor", () => {
 
   it("generates a thread title on the first turn", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const seededTitle = "Please investigate reconnect failures after restar...";
     harness.generateThreadTitle.mockReturnValue(Effect.succeed({ title: "Generated title" }));
 
@@ -364,20 +492,20 @@ describe("ProviderCommandReactor", () => {
     });
 
     await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
+      const readModel = await harness.readModel();
       return (
         readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"))?.title ===
         "Generated title"
       );
     });
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.title).toBe("Generated title");
   });
 
   it("does not overwrite an existing custom thread title on the first turn", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const seededTitle = "Please investigate reconnect failures after restar...";
 
     await Effect.runPromise(
@@ -410,14 +538,14 @@ describe("ProviderCommandReactor", () => {
     await waitFor(() => harness.sendTurn.mock.calls.length === 1);
     expect(harness.generateThreadTitle).not.toHaveBeenCalled();
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.title).toBe("Keep this custom title");
   });
 
   it("matches the client-seeded title even when the outgoing prompt is reformatted", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const seededTitle = "Fix reconnect spinner on resume";
     harness.generateThreadTitle.mockReturnValue(
       Effect.succeed({
@@ -454,21 +582,21 @@ describe("ProviderCommandReactor", () => {
 
     await waitFor(() => harness.generateThreadTitle.mock.calls.length === 1);
     await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
+      const readModel = await harness.readModel();
       return (
         readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"))?.title ===
         "Reconnect spinner resume bug"
       );
     });
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.title).toBe("Reconnect spinner resume bug");
   });
 
   it("generates a worktree branch name for the first turn", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -513,14 +641,16 @@ describe("ProviderCommandReactor", () => {
     );
 
     await waitFor(() => harness.generateBranchName.mock.calls.length === 1);
+    await waitFor(() => harness.refreshStatus.mock.calls.length === 1);
     expect(harness.generateBranchName.mock.calls[0]?.[0]).toMatchObject({
       message: "Add a safer reconnect backoff.",
     });
+    expect(harness.refreshStatus.mock.calls[0]?.[0]).toBe("/tmp/provider-project-worktree");
   });
 
   it("forwards codex model options through session start and turn send", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -533,14 +663,10 @@ describe("ProviderCommandReactor", () => {
           text: "hello fast mode",
           attachments: [],
         },
-        modelSelection: {
-          provider: "codex",
-          model: "gpt-5.3-codex",
-          options: {
-            reasoningEffort: "high",
-            fastMode: true,
-          },
-        },
+        modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.3-codex", [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ]),
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
         createdAt: now,
@@ -550,33 +676,28 @@ describe("ProviderCommandReactor", () => {
     await waitFor(() => harness.startSession.mock.calls.length === 1);
     await waitFor(() => harness.sendTurn.mock.calls.length === 1);
     expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
-      modelSelection: {
-        provider: "codex",
-        model: "gpt-5.3-codex",
-        options: {
-          reasoningEffort: "high",
-          fastMode: true,
-        },
-      },
+      modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.3-codex", [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ]),
     });
     expect(harness.sendTurn.mock.calls[0]?.[0]).toMatchObject({
       threadId: ThreadId.make("thread-1"),
-      modelSelection: {
-        provider: "codex",
-        model: "gpt-5.3-codex",
-        options: {
-          reasoningEffort: "high",
-          fastMode: true,
-        },
-      },
+      modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.3-codex", [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ]),
     });
   });
 
   it("forwards claude effort options through session start and turn send", async () => {
     const harness = await createHarness({
-      threadModelSelection: { provider: "claudeAgent", model: "claude-sonnet-4-6" },
+      threadModelSelection: {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-sonnet-4-6",
+      },
     });
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -589,13 +710,11 @@ describe("ProviderCommandReactor", () => {
           text: "hello with effort",
           attachments: [],
         },
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            effort: "max",
-          },
-        },
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "effort", value: "max" }],
+        ),
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
         createdAt: now,
@@ -605,31 +724,30 @@ describe("ProviderCommandReactor", () => {
     await waitFor(() => harness.startSession.mock.calls.length === 1);
     await waitFor(() => harness.sendTurn.mock.calls.length === 1);
     expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-sonnet-4-6",
-        options: {
-          effort: "max",
-        },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-sonnet-4-6",
+        [{ id: "effort", value: "max" }],
+      ),
     });
     expect(harness.sendTurn.mock.calls[0]?.[0]).toMatchObject({
       threadId: ThreadId.make("thread-1"),
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-sonnet-4-6",
-        options: {
-          effort: "max",
-        },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-sonnet-4-6",
+        [{ id: "effort", value: "max" }],
+      ),
     });
   });
 
   it("forwards claude fast mode options through session start and turn send", async () => {
     const harness = await createHarness({
-      threadModelSelection: { provider: "claudeAgent", model: "claude-opus-4-6" },
+      threadModelSelection: {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-opus-4-6",
+      },
     });
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -642,13 +760,11 @@ describe("ProviderCommandReactor", () => {
           text: "hello with fast mode",
           attachments: [],
         },
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            fastMode: true,
-          },
-        },
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [{ id: "fastMode", value: true }],
+        ),
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
         createdAt: now,
@@ -658,29 +774,25 @@ describe("ProviderCommandReactor", () => {
     await waitFor(() => harness.startSession.mock.calls.length === 1);
     await waitFor(() => harness.sendTurn.mock.calls.length === 1);
     expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-opus-4-6",
-        options: {
-          fastMode: true,
-        },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-opus-4-6",
+        [{ id: "fastMode", value: true }],
+      ),
     });
     expect(harness.sendTurn.mock.calls[0]?.[0]).toMatchObject({
       threadId: ThreadId.make("thread-1"),
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-opus-4-6",
-        options: {
-          fastMode: true,
-        },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-opus-4-6",
+        [{ id: "fastMode", value: true }],
+      ),
     });
   });
 
   it("forwards plan interaction mode to the provider turn request", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -716,11 +828,62 @@ describe("ProviderCommandReactor", () => {
     });
   });
 
-  it("rejects a first turn when requested provider conflicts with the thread model", async () => {
+  it("preserves the active session model when in-session model switching is unsupported", async () => {
+    const harness = await createHarness({ sessionModelSwitch: "unsupported" });
+    const now = "2026-01-01T00:00:00.000Z";
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-unsupported-1"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-unsupported-1"),
+          role: "user",
+          text: "first",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+
+    await waitFor(() => harness.sendTurn.mock.calls.length === 1);
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-unsupported-2"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-unsupported-2"),
+          role: "user",
+          text: "second",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+
+    await waitFor(() => harness.sendTurn.mock.calls.length === 2);
+
+    expect(harness.sendTurn.mock.calls[1]?.[0]).toMatchObject({
+      threadId: ThreadId.make("thread-1"),
+      modelSelection: {
+        instanceId: ProviderInstanceId.make("codex"),
+        model: "gpt-5-codex",
+      },
+    });
+  });
+
+  it("starts a first turn on the requested provider instance even when it differs from the thread model", async () => {
     const harness = await createHarness({
-      threadModelSelection: { provider: "codex", model: "gpt-5-codex" },
+      threadModelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5-codex" },
     });
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -734,7 +897,7 @@ describe("ProviderCommandReactor", () => {
           attachments: [],
         },
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -743,42 +906,38 @@ describe("ProviderCommandReactor", () => {
       }),
     );
 
-    await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
-      const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
-      return (
-        thread?.activities.some((activity) => activity.kind === "provider.turn.start.failed") ??
-        false
-      );
-    });
+    await waitFor(() => harness.sendTurn.mock.calls.length === 1);
 
-    expect(harness.startSession).not.toHaveBeenCalled();
-    expect(harness.sendTurn).not.toHaveBeenCalled();
+    expect(harness.startSession).toHaveBeenCalledTimes(1);
+    expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
+      provider: ProviderDriverKind.make("claudeAgent"),
+      providerInstanceId: ProviderInstanceId.make("claudeAgent"),
+      modelSelection: {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-opus-4-6",
+      },
+    });
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
-    expect(thread?.session).toBeNull();
+    expect(thread?.session?.providerName).toBe("claudeAgent");
+    expect(thread?.session?.providerInstanceId).toBe(ProviderInstanceId.make("claudeAgent"));
     expect(
       thread?.activities.find((activity) => activity.kind === "provider.turn.start.failed"),
-    ).toMatchObject({
-      summary: "Provider turn start failed",
-      payload: {
-        detail: expect.stringContaining("cannot switch to 'claudeAgent'"),
-      },
-    });
+    ).toBeUndefined();
   });
 
-  it("preserves the active session model when in-session model switching is unsupported", async () => {
-    const harness = await createHarness({ sessionModelSwitch: "unsupported" });
-    const now = new Date().toISOString();
+  it("reuses the same provider session when runtime mode is unchanged", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.start",
-        commandId: CommandId.make("cmd-turn-start-unsupported-1"),
+        commandId: CommandId.make("cmd-turn-start-unchanged-1"),
         threadId: ThreadId.make("thread-1"),
         message: {
-          messageId: asMessageId("user-message-unsupported-1"),
+          messageId: asMessageId("user-message-unchanged-1"),
           role: "user",
           text: "first",
           attachments: [],
@@ -789,15 +948,16 @@ describe("ProviderCommandReactor", () => {
       }),
     );
 
+    await waitFor(() => harness.startSession.mock.calls.length === 1);
     await waitFor(() => harness.sendTurn.mock.calls.length === 1);
 
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.start",
-        commandId: CommandId.make("cmd-turn-start-unsupported-2"),
+        commandId: CommandId.make("cmd-turn-start-unchanged-2"),
         threadId: ThreadId.make("thread-1"),
         message: {
-          messageId: asMessageId("user-message-unsupported-2"),
+          messageId: asMessageId("user-message-unchanged-2"),
           role: "user",
           text: "second",
           attachments: [],
@@ -809,67 +969,153 @@ describe("ProviderCommandReactor", () => {
     );
 
     await waitFor(() => harness.sendTurn.mock.calls.length === 2);
-
-    expect(harness.sendTurn.mock.calls[1]?.[0]).toMatchObject({
-      threadId: ThreadId.make("thread-1"),
-      modelSelection: {
-        provider: "codex",
-        model: "gpt-5-codex",
-      },
-    });
+    expect(harness.startSession.mock.calls.length).toBe(1);
+    expect(harness.stopSession.mock.calls.length).toBe(0);
   });
 
-  it("reuses the same provider session when runtime mode is unchanged", async () => {
+  it("restarts an existing Codex thread on a compatible requested instance", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.start",
-        commandId: CommandId.make("cmd-turn-start-unchanged-1"),
+        commandId: CommandId.make("cmd-turn-start-compatible-codex-1"),
         threadId: ThreadId.make("thread-1"),
         message: {
-          messageId: asMessageId("user-message-unchanged-1"),
+          messageId: asMessageId("user-message-compatible-codex-1"),
           role: "user",
           text: "first",
           attachments: [],
         },
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5-codex",
+        },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
         createdAt: now,
       }),
     );
 
-    await waitFor(() => harness.startSession.mock.calls.length === 1);
     await waitFor(() => harness.sendTurn.mock.calls.length === 1);
 
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.start",
-        commandId: CommandId.make("cmd-turn-start-unchanged-2"),
+        commandId: CommandId.make("cmd-turn-start-compatible-codex-2"),
         threadId: ThreadId.make("thread-1"),
         message: {
-          messageId: asMessageId("user-message-unchanged-2"),
+          messageId: asMessageId("user-message-compatible-codex-2"),
           role: "user",
           text: "second",
           attachments: [],
         },
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex_work"),
+          model: "gpt-5-codex",
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      }),
+    );
+
+    await waitFor(() => harness.sendTurn.mock.calls.length === 2);
+
+    expect(harness.startSession).toHaveBeenCalledTimes(2);
+    expect(harness.startSession.mock.calls[1]?.[1]).toMatchObject({
+      provider: ProviderDriverKind.make("codex"),
+      providerInstanceId: ProviderInstanceId.make("codex_work"),
+      resumeCursor: { opaque: "resume-1" },
+    });
+
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.session?.providerInstanceId).toBe(ProviderInstanceId.make("codex_work"));
+  });
+
+  it("restarts the provider session when the thread workspace changes", async () => {
+    const harness = await createHarness({
+      threadModelSelection: {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-sonnet-4-6",
+      },
+    });
+    const now = "2026-01-01T00:00:00.000Z";
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-workspace-1"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-workspace-1"),
+          role: "user",
+          text: "first in project root",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+
+    await waitFor(() => harness.startSession.mock.calls.length === 1);
+    await waitFor(() => harness.sendTurn.mock.calls.length === 1);
+    expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
+      cwd: "/tmp/provider-project",
+    });
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.meta.update",
+        commandId: CommandId.make("cmd-thread-worktree-change"),
+        threadId: ThreadId.make("thread-1"),
+        worktreePath: "/tmp/provider-project-worktree",
+      }),
+    );
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-workspace-2"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-workspace-2"),
+          role: "user",
+          text: "second in worktree",
+          attachments: [],
+        },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
         createdAt: now,
       }),
     );
 
+    await waitFor(() => harness.startSession.mock.calls.length === 2);
     await waitFor(() => harness.sendTurn.mock.calls.length === 2);
-    expect(harness.startSession.mock.calls.length).toBe(1);
     expect(harness.stopSession.mock.calls.length).toBe(0);
+    expect(harness.startSession.mock.calls[1]?.[1]).toMatchObject({
+      threadId: ThreadId.make("thread-1"),
+      cwd: "/tmp/provider-project-worktree",
+      resumeCursor: { opaque: "resume-1" },
+      modelSelection: {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-sonnet-4-6",
+      },
+      runtimeMode: "approval-required",
+    });
   });
 
   it("restarts claude sessions when claude effort changes", async () => {
     const harness = await createHarness({
-      threadModelSelection: { provider: "claudeAgent", model: "claude-sonnet-4-6" },
+      threadModelSelection: {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-sonnet-4-6",
+      },
     });
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -882,13 +1128,11 @@ describe("ProviderCommandReactor", () => {
           text: "first claude turn",
           attachments: [],
         },
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            effort: "medium",
-          },
-        },
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "effort", value: "medium" }],
+        ),
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
         createdAt: now,
@@ -909,13 +1153,11 @@ describe("ProviderCommandReactor", () => {
           text: "second claude turn",
           attachments: [],
         },
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            effort: "max",
-          },
-        },
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "effort", value: "max" }],
+        ),
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
         createdAt: now,
@@ -926,19 +1168,17 @@ describe("ProviderCommandReactor", () => {
     await waitFor(() => harness.sendTurn.mock.calls.length === 2);
     expect(harness.startSession.mock.calls[1]?.[1]).toMatchObject({
       resumeCursor: { opaque: "resume-1" },
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-sonnet-4-6",
-        options: {
-          effort: "max",
-        },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-sonnet-4-6",
+        [{ id: "effort", value: "max" }],
+      ),
     });
   });
 
   it("restarts the provider session when runtime mode is updated on the thread", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -981,7 +1221,7 @@ describe("ProviderCommandReactor", () => {
     );
 
     await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
+      const readModel = await harness.readModel();
       const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
       return thread?.runtimeMode === "approval-required";
     });
@@ -1015,7 +1255,7 @@ describe("ProviderCommandReactor", () => {
       threadId: ThreadId.make("thread-1"),
     });
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.session?.threadId).toBe("thread-1");
     expect(thread?.session?.runtimeMode).toBe("approval-required");
@@ -1023,9 +1263,12 @@ describe("ProviderCommandReactor", () => {
 
   it("does not inject derived model options when restarting claude on runtime mode changes", async () => {
     const harness = await createHarness({
-      threadModelSelection: { provider: "claudeAgent", model: "claude-opus-4-6" },
+      threadModelSelection: {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-opus-4-6",
+      },
     });
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1059,16 +1302,81 @@ describe("ProviderCommandReactor", () => {
 
     expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
       modelSelection: {
-        provider: "claudeAgent",
+        instanceId: ProviderInstanceId.make("claudeAgent"),
         model: "claude-opus-4-6",
       },
       runtimeMode: "approval-required",
     });
   });
 
+  it("does not stop the active session when restart fails before rebind", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.runtime-mode.set",
+        commandId: CommandId.make("cmd-runtime-mode-set-initial-full-access-2"),
+        threadId: ThreadId.make("thread-1"),
+        runtimeMode: "full-access",
+        createdAt: now,
+      }),
+    );
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-restart-failure-1"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-restart-failure-1"),
+          role: "user",
+          text: "first",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "full-access",
+        createdAt: now,
+      }),
+    );
+
+    await waitFor(() => harness.startSession.mock.calls.length === 1);
+    await waitFor(() => harness.sendTurn.mock.calls.length === 1);
+
+    harness.startSession.mockImplementationOnce(
+      (_: unknown, __: unknown) => Effect.fail("simulated restart failure") as never,
+    );
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.runtime-mode.set",
+        commandId: CommandId.make("cmd-runtime-mode-set-restart-failure"),
+        threadId: ThreadId.make("thread-1"),
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+
+    await waitFor(async () => {
+      const readModel = await harness.readModel();
+      const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+      return thread?.runtimeMode === "approval-required";
+    });
+    await waitFor(() => harness.startSession.mock.calls.length === 2);
+    await harness.drain();
+
+    expect(harness.stopSession.mock.calls.length).toBe(0);
+    expect(harness.sendTurn.mock.calls.length).toBe(1);
+
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.session?.threadId).toBe("thread-1");
+    expect(thread?.session?.runtimeMode).toBe("full-access");
+  });
+
   it("rejects provider changes after a thread is already bound to a session provider", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1102,7 +1410,7 @@ describe("ProviderCommandReactor", () => {
           attachments: [],
         },
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -1112,7 +1420,7 @@ describe("ProviderCommandReactor", () => {
     );
 
     await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
+      const readModel = await harness.readModel();
       const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
       return (
         thread?.activities.some((activity) => activity.kind === "provider.turn.start.failed") ??
@@ -1124,7 +1432,7 @@ describe("ProviderCommandReactor", () => {
     expect(harness.sendTurn.mock.calls.length).toBe(1);
     expect(harness.stopSession.mock.calls.length).toBe(0);
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.session?.threadId).toBe("thread-1");
     expect(thread?.session?.providerName).toBe("codex");
@@ -1138,16 +1446,25 @@ describe("ProviderCommandReactor", () => {
     });
   });
 
-  it("does not stop the active session when restart fails before rebind", async () => {
+  it("rejects cross-driver provider changes after the existing thread session has stopped", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
-        type: "thread.runtime-mode.set",
-        commandId: CommandId.make("cmd-runtime-mode-set-initial-full-access-2"),
+        type: "thread.session.set",
+        commandId: CommandId.make("cmd-session-set-stopped-provider-switch"),
         threadId: ThreadId.make("thread-1"),
-        runtimeMode: "full-access",
+        session: {
+          threadId: ThreadId.make("thread-1"),
+          status: "stopped",
+          providerName: "codex",
+          providerInstanceId: ProviderInstanceId.make("codex"),
+          runtimeMode: "approval-required",
+          activeTurnId: null,
+          lastError: null,
+          updatedAt: now,
+        },
         createdAt: now,
       }),
     );
@@ -1155,57 +1472,49 @@ describe("ProviderCommandReactor", () => {
     await Effect.runPromise(
       harness.engine.dispatch({
         type: "thread.turn.start",
-        commandId: CommandId.make("cmd-turn-start-restart-failure-1"),
+        commandId: CommandId.make("cmd-turn-start-stopped-provider-switch"),
         threadId: ThreadId.make("thread-1"),
         message: {
-          messageId: asMessageId("user-message-restart-failure-1"),
+          messageId: asMessageId("user-message-stopped-provider-switch"),
           role: "user",
-          text: "first",
+          text: "continue with claude",
           attachments: [],
         },
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("claudeAgent"),
+          model: "claude-opus-4-6",
+        },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
-        runtimeMode: "full-access",
-        createdAt: now,
-      }),
-    );
-
-    await waitFor(() => harness.startSession.mock.calls.length === 1);
-    await waitFor(() => harness.sendTurn.mock.calls.length === 1);
-
-    harness.startSession.mockImplementationOnce(
-      (_: unknown, __: unknown) => Effect.fail(new Error("simulated restart failure")) as never,
-    );
-
-    await Effect.runPromise(
-      harness.engine.dispatch({
-        type: "thread.runtime-mode.set",
-        commandId: CommandId.make("cmd-runtime-mode-set-restart-failure"),
-        threadId: ThreadId.make("thread-1"),
         runtimeMode: "approval-required",
         createdAt: now,
       }),
     );
 
     await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
+      const readModel = await harness.readModel();
       const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
-      return thread?.runtimeMode === "approval-required";
+      return (
+        thread?.activities.some((activity) => activity.kind === "provider.turn.start.failed") ??
+        false
+      );
     });
-    await waitFor(() => harness.startSession.mock.calls.length === 2);
-    await harness.drain();
-
-    expect(harness.stopSession.mock.calls.length).toBe(0);
-    expect(harness.sendTurn.mock.calls.length).toBe(1);
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    expect(harness.startSession.mock.calls.length).toBe(0);
+    expect(harness.sendTurn.mock.calls.length).toBe(0);
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
-    expect(thread?.session?.threadId).toBe("thread-1");
-    expect(thread?.session?.runtimeMode).toBe("full-access");
+    expect(
+      thread?.activities.find((activity) => activity.kind === "provider.turn.start.failed"),
+    ).toMatchObject({
+      payload: {
+        detail: expect.stringContaining("cannot switch to 'claudeAgent'"),
+      },
+    });
   });
 
   it("reacts to thread.turn.interrupt-requested by calling provider interrupt", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1241,9 +1550,135 @@ describe("ProviderCommandReactor", () => {
     });
   });
 
+  it("starts a fresh session when only projected session state exists", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.session.set",
+        commandId: CommandId.make("cmd-session-set-stale"),
+        threadId: ThreadId.make("thread-1"),
+        session: {
+          threadId: ThreadId.make("thread-1"),
+          status: "ready",
+          providerName: "codex",
+          runtimeMode: "approval-required",
+          activeTurnId: null,
+          lastError: null,
+          updatedAt: now,
+        },
+        createdAt: now,
+      }),
+    );
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-stale"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-stale"),
+          role: "user",
+          text: "resume codex",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+
+    await waitFor(() => harness.startSession.mock.calls.length === 1);
+    await waitFor(() => harness.sendTurn.mock.calls.length === 1);
+
+    expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
+      threadId: ThreadId.make("thread-1"),
+      modelSelection: {
+        instanceId: ProviderInstanceId.make("codex"),
+        model: "gpt-5-codex",
+      },
+      runtimeMode: "approval-required",
+    });
+    expect(harness.sendTurn.mock.calls[0]?.[0]).toMatchObject({
+      threadId: ThreadId.make("thread-1"),
+    });
+  });
+
+  it("rejects active runtime sessions that are missing provider instance ids", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.session.set",
+        commandId: CommandId.make("cmd-session-set-missing-instance"),
+        threadId: ThreadId.make("thread-1"),
+        session: {
+          threadId: ThreadId.make("thread-1"),
+          status: "ready",
+          providerName: "codex",
+          runtimeMode: "approval-required",
+          activeTurnId: null,
+          lastError: null,
+          updatedAt: now,
+        },
+        createdAt: now,
+      }),
+    );
+    harness.runtimeSessions.push({
+      provider: ProviderDriverKind.make("codex"),
+      status: "ready",
+      runtimeMode: "approval-required",
+      threadId: ThreadId.make("thread-1"),
+      cwd: "/tmp/provider-project",
+      resumeCursor: { opaque: "resume-without-instance" },
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-missing-instance"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-missing-instance"),
+          role: "user",
+          text: "resume codex",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+
+    await waitFor(async () => {
+      const readModel = await harness.readModel();
+      const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+      return (
+        thread?.activities.some((activity) => activity.kind === "provider.turn.start.failed") ??
+        false
+      );
+    });
+
+    expect(harness.startSession.mock.calls.length).toBe(0);
+    expect(harness.sendTurn.mock.calls.length).toBe(0);
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(
+      thread?.activities.find((activity) => activity.kind === "provider.turn.start.failed"),
+    ).toMatchObject({
+      payload: {
+        detail: expect.stringContaining("without a provider instance id"),
+      },
+    });
+  });
+
   it("reacts to thread.approval.respond by forwarding provider approval response", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1284,7 +1719,7 @@ describe("ProviderCommandReactor", () => {
 
   it("reacts to thread.user-input.respond by forwarding structured user input answers", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1329,11 +1764,11 @@ describe("ProviderCommandReactor", () => {
 
   it("surfaces stale provider approval request failures without faking approval resolution", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     harness.respondToRequest.mockImplementation(() =>
       Effect.fail(
         new ProviderAdapterRequestError({
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           method: "session/request_permission",
           detail: "Unknown pending permission request: approval-request-1",
         }),
@@ -1391,7 +1826,7 @@ describe("ProviderCommandReactor", () => {
     );
 
     await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
+      const readModel = await harness.readModel();
       const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
       if (!thread) return false;
       return thread.activities.some(
@@ -1399,7 +1834,7 @@ describe("ProviderCommandReactor", () => {
       );
     });
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread).toBeDefined();
 
@@ -1424,11 +1859,11 @@ describe("ProviderCommandReactor", () => {
 
   it("surfaces stale provider user-input failures without faking user-input resolution", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     harness.respondToUserInput.mockImplementation(() =>
       Effect.fail(
         new ProviderAdapterRequestError({
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           method: "item/tool/respondToUserInput",
           detail: "Unknown pending user-input request: user-input-request-1",
         }),
@@ -1500,7 +1935,7 @@ describe("ProviderCommandReactor", () => {
     );
 
     await waitFor(async () => {
-      const readModel = await Effect.runPromise(harness.engine.getReadModel());
+      const readModel = await harness.readModel();
       const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
       if (!thread) return false;
       return thread.activities.some(
@@ -1508,7 +1943,7 @@ describe("ProviderCommandReactor", () => {
       );
     });
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread).toBeDefined();
 
@@ -1533,7 +1968,7 @@ describe("ProviderCommandReactor", () => {
 
   it("reacts to thread.session.stop by stopping provider session and clearing thread session state", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1544,6 +1979,7 @@ describe("ProviderCommandReactor", () => {
           threadId: ThreadId.make("thread-1"),
           status: "ready",
           providerName: "codex",
+          providerInstanceId: ProviderInstanceId.make("codex_work"),
           runtimeMode: "approval-required",
           activeTurnId: null,
           lastError: null,
@@ -1563,11 +1999,12 @@ describe("ProviderCommandReactor", () => {
     );
 
     await waitFor(() => harness.stopSession.mock.calls.length === 1);
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread?.session).not.toBeNull();
     expect(thread?.session?.status).toBe("stopped");
     expect(thread?.session?.threadId).toBe("thread-1");
+    expect(thread?.session?.providerInstanceId).toBe(ProviderInstanceId.make("codex_work"));
     expect(thread?.session?.activeTurnId).toBeNull();
   });
 });
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index a1a69f0efaa..8b71a976808 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -4,28 +4,43 @@ import {
   EventId,
   type ModelSelection,
   type OrchestrationEvent,
-  ProviderKind,
+  ProviderDriverKind,
+  type ProjectId,
   type OrchestrationSession,
   ThreadId,
   type ProviderSession,
   type RuntimeMode,
   type TurnId,
 } from "@t3tools/contracts";
-import { Cache, Cause, Duration, Effect, Equal, Layer, Option, Schema, Stream } from "effect";
+import { isTemporaryWorktreeBranch, WORKTREE_BRANCH_PREFIX } from "@t3tools/shared/git";
+import * as Cache from "effect/Cache";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
 
 import { resolveThreadWorkspaceCwd } from "../../checkpointing/Utils.ts";
-import { GitCore } from "../../git/Services/GitCore.ts";
 import { increment, orchestrationEventsProcessedTotal } from "../../observability/Metrics.ts";
-import { ProviderAdapterRequestError, ProviderServiceError } from "../../provider/Errors.ts";
-import { TextGeneration } from "../../git/Services/TextGeneration.ts";
+import { ProviderAdapterRequestError } from "../../provider/Errors.ts";
+import type { ProviderServiceError } from "../../provider/Errors.ts";
+import { TextGeneration } from "../../textGeneration/TextGeneration.ts";
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import {
   ProviderCommandReactor,
   type ProviderCommandReactorShape,
 } from "../Services/ProviderCommandReactor.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
+import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
+import { GitWorkflowService } from "../../git/GitWorkflowService.ts";
+const isProviderAdapterRequestError = Schema.is(ProviderAdapterRequestError);
+const isProviderDriverKind = Schema.is(ProviderDriverKind);
 
 type ProviderIntentEvent = Extract<
   OrchestrationEvent,
@@ -72,10 +87,23 @@ const serverCommandId = (tag: string): CommandId =>
 const HANDLED_TURN_START_KEY_MAX = 10_000;
 const HANDLED_TURN_START_KEY_TTL = Duration.minutes(30);
 const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";
-const WORKTREE_BRANCH_PREFIX = "t3code";
-const TEMP_WORKTREE_BRANCH_PATTERN = new RegExp(`^${WORKTREE_BRANCH_PREFIX}\\/[0-9a-f]{8}$`);
 const DEFAULT_THREAD_TITLE = "New thread";
 
+export function providerErrorLabel(value: string | undefined): string {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : "unknown";
+}
+
+export function providerErrorLabelFromInstanceHint(input: {
+  readonly instanceId?: string | undefined;
+  readonly modelSelectionInstanceId?: string | undefined;
+  readonly sessionProvider?: string | undefined;
+}): string {
+  return providerErrorLabel(
+    input.instanceId ?? input.modelSelectionInstanceId ?? input.sessionProvider,
+  );
+}
+
 function canReplaceThreadTitle(currentTitle: string, titleSeed?: string): boolean {
   const trimmedCurrentTitle = currentTitle.trim();
   if (trimmedCurrentTitle === DEFAULT_THREAD_TITLE) {
@@ -88,9 +116,16 @@ function canReplaceThreadTitle(currentTitle: string, titleSeed?: string): boolea
     : false;
 }
 
+function findProviderAdapterRequestError(
+  cause: Cause.Cause<ProviderServiceError>,
+): ProviderAdapterRequestError | undefined {
+  const failReason = cause.reasons.find(Cause.isFailReason);
+  return isProviderAdapterRequestError(failReason?.error) ? failReason.error : undefined;
+}
+
 function isUnknownPendingApprovalRequestError(cause: Cause.Cause<ProviderServiceError>): boolean {
-  const error = Cause.squash(cause);
-  if (Schema.is(ProviderAdapterRequestError)(error)) {
+  const error = findProviderAdapterRequestError(cause);
+  if (error) {
     const detail = error.detail.toLowerCase();
     return (
       detail.includes("unknown pending approval request") ||
@@ -105,8 +140,8 @@ function isUnknownPendingApprovalRequestError(cause: Cause.Cause<ProviderService
 }
 
 function isUnknownPendingUserInputRequestError(cause: Cause.Cause<ProviderServiceError>): boolean {
-  const error = Cause.squash(cause);
-  if (Schema.is(ProviderAdapterRequestError)(error)) {
+  const error = findProviderAdapterRequestError(cause);
+  if (error) {
     return error.detail.toLowerCase().includes("unknown pending user-input request");
   }
   return Cause.pretty(cause).toLowerCase().includes("unknown pending user-input request");
@@ -119,10 +154,6 @@ function stalePendingRequestDetail(
   return `Stale pending ${requestKind} request: ${requestId}. Provider callback state does not survive app restarts or recovered sessions. Restart the turn to continue.`;
 }
 
-function isTemporaryWorktreeBranch(branch: string): boolean {
-  return TEMP_WORKTREE_BRANCH_PATTERN.test(branch.trim().toLowerCase());
-}
-
 function buildGeneratedWorktreeBranchName(raw: string): string {
   const normalized = raw
     .trim()
@@ -148,8 +179,10 @@ function buildGeneratedWorktreeBranchName(raw: string): string {
 
 const make = Effect.gen(function* () {
   const orchestrationEngine = yield* OrchestrationEngineService;
+  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
   const providerService = yield* ProviderService;
-  const git = yield* GitCore;
+  const gitWorkflow = yield* GitWorkflowService;
+  const vcsStatusBroadcaster = yield* VcsStatusBroadcaster;
   const textGeneration = yield* TextGeneration;
   const serverSettingsService = yield* ServerSettingsService;
   const handledTurnStartKeys = yield* Cache.make<string, true>({
@@ -200,6 +233,17 @@ const make = Effect.gen(function* () {
       createdAt: input.createdAt,
     });
 
+  const formatFailureDetail = (cause: Cause.Cause<unknown>): string => {
+    const failReason = cause.reasons.find(Cause.isFailReason);
+    const providerError = isProviderAdapterRequestError(failReason?.error)
+      ? failReason.error
+      : undefined;
+    if (providerError) {
+      return providerError.detail;
+    }
+    return Cause.pretty(cause);
+  };
+
   const setThreadSession = (input: {
     readonly threadId: ThreadId;
     readonly session: OrchestrationSession;
@@ -213,9 +257,39 @@ const make = Effect.gen(function* () {
       createdAt: input.createdAt,
     });
 
-  const resolveThread = Effect.fn("resolveThread")(function* (threadId: ThreadId) {
-    const readModel = yield* orchestrationEngine.getReadModel();
-    return readModel.threads.find((entry) => entry.id === threadId);
+  const setThreadSessionErrorOnTurnStartFailure = Effect.fnUntraced(function* (input: {
+    readonly threadId: ThreadId;
+    readonly detail: string;
+    readonly createdAt: string;
+  }) {
+    const thread = yield* resolveThread(input.threadId);
+    const session = thread?.session;
+    if (!session) {
+      return;
+    }
+    yield* setThreadSession({
+      threadId: input.threadId,
+      session: {
+        ...session,
+        status: session.status === "stopped" ? "stopped" : "ready",
+        activeTurnId: null,
+        lastError: input.detail,
+        updatedAt: input.createdAt,
+      },
+      createdAt: input.createdAt,
+    });
+  });
+
+  const resolveProject = Effect.fnUntraced(function* (projectId: ProjectId) {
+    return yield* projectionSnapshotQuery
+      .getProjectShellById(projectId)
+      .pipe(Effect.map(Option.getOrUndefined));
+  });
+
+  const resolveThread = Effect.fnUntraced(function* (threadId: ThreadId) {
+    return yield* projectionSnapshotQuery
+      .getThreadDetailById(threadId)
+      .pipe(Effect.map(Option.getOrUndefined));
   });
 
   const ensureSessionForThread = Effect.fn("ensureSessionForThread")(function* (
@@ -225,49 +299,115 @@ const make = Effect.gen(function* () {
       readonly modelSelection?: ModelSelection;
     },
   ) {
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === threadId);
+    const thread = yield* resolveThread(threadId);
     if (!thread) {
       return yield* Effect.die(new Error(`Thread '${threadId}' was not found in read model.`));
     }
 
     const desiredRuntimeMode = thread.runtimeMode;
-    const currentProvider: ProviderKind | undefined = Schema.is(ProviderKind)(
-      thread.session?.providerName,
-    )
-      ? thread.session.providerName
-      : undefined;
     const requestedModelSelection = options?.modelSelection;
-    const threadProvider: ProviderKind = currentProvider ?? thread.modelSelection.provider;
+    const resolveActiveSession = (threadId: ThreadId) =>
+      providerService
+        .listSessions()
+        .pipe(Effect.map((sessions) => sessions.find((session) => session.threadId === threadId)));
+
+    const activeSession = yield* resolveActiveSession(threadId);
+    const activeThreadSession =
+      thread.session !== null && thread.session.status !== "stopped" && activeSession
+        ? thread.session
+        : null;
     if (
-      requestedModelSelection !== undefined &&
-      requestedModelSelection.provider !== threadProvider
+      activeThreadSession !== null &&
+      activeSession !== undefined &&
+      (activeThreadSession.providerInstanceId === undefined ||
+        activeSession.providerInstanceId === undefined)
     ) {
       return yield* new ProviderAdapterRequestError({
-        provider: threadProvider,
+        provider: providerErrorLabel(activeThreadSession.providerName ?? undefined),
         method: "thread.turn.start",
-        detail: `Thread '${threadId}' is bound to provider '${threadProvider}' and cannot switch to '${requestedModelSelection.provider}'.`,
+        detail: `Thread '${threadId}' has an active provider session without a provider instance id.`,
       });
     }
-    const preferredProvider: ProviderKind = currentProvider ?? threadProvider;
+    const currentInstanceId =
+      activeThreadSession !== null &&
+      activeSession !== undefined &&
+      activeSession.providerInstanceId !== undefined
+        ? activeSession.providerInstanceId
+        : thread.modelSelection.instanceId;
     const desiredModelSelection = requestedModelSelection ?? thread.modelSelection;
+    const desiredInstanceId = desiredModelSelection.instanceId;
+    const currentInfo = yield* providerService.getInstanceInfo(currentInstanceId).pipe(
+      Effect.mapError(
+        () =>
+          new ProviderAdapterRequestError({
+            provider: providerErrorLabelFromInstanceHint({
+              instanceId: String(currentInstanceId),
+              modelSelectionInstanceId: String(thread.modelSelection.instanceId),
+              sessionProvider: thread.session?.providerName ?? undefined,
+            }),
+            method: "thread.turn.start",
+            detail: `Thread '${threadId}' references unknown provider instance '${currentInstanceId}'. The instance is not configured in this build.`,
+          }),
+      ),
+    );
+    const desiredInfo = yield* providerService.getInstanceInfo(desiredInstanceId).pipe(
+      Effect.mapError(
+        () =>
+          new ProviderAdapterRequestError({
+            provider: providerErrorLabelFromInstanceHint({
+              instanceId: String(desiredModelSelection.instanceId),
+            }),
+            method: "thread.turn.start",
+            detail: `Requested provider instance '${desiredInstanceId}' is not configured in this build.`,
+          }),
+      ),
+    );
+    const desiredDriverKind = desiredInfo.driverKind;
+    if (!isProviderDriverKind(desiredDriverKind)) {
+      return yield* new ProviderAdapterRequestError({
+        provider: providerErrorLabel(String(desiredDriverKind)),
+        method: "thread.turn.start",
+        detail: `Requested provider instance '${desiredInstanceId}' uses unknown provider driver '${desiredDriverKind}'. The driver is not installed in this build.`,
+      });
+    }
+    const preferredProvider: ProviderDriverKind = desiredDriverKind;
+    if (
+      thread.session !== null &&
+      requestedModelSelection !== undefined &&
+      requestedModelSelection.instanceId !== currentInstanceId
+    ) {
+      if (currentInfo.driverKind !== desiredInfo.driverKind) {
+        return yield* new ProviderAdapterRequestError({
+          provider: preferredProvider,
+          method: "thread.turn.start",
+          detail: `Thread '${threadId}' is bound to driver '${currentInfo.driverKind}' and cannot switch to '${desiredInfo.driverKind}'.`,
+        });
+      }
+      if (
+        currentInfo.continuationIdentity.continuationKey !==
+        desiredInfo.continuationIdentity.continuationKey
+      ) {
+        return yield* new ProviderAdapterRequestError({
+          provider: preferredProvider,
+          method: "thread.turn.start",
+          detail: `Thread '${threadId}' cannot switch from instance '${currentInstanceId}' to '${desiredInstanceId}' because their provider resume state is incompatible.`,
+        });
+      }
+    }
+    const project = yield* resolveProject(thread.projectId);
     const effectiveCwd = resolveThreadWorkspaceCwd({
       thread,
-      projects: readModel.projects,
+      projects: project ? [project] : [],
     });
 
-    const resolveActiveSession = (threadId: ThreadId) =>
-      providerService
-        .listSessions()
-        .pipe(Effect.map((sessions) => sessions.find((session) => session.threadId === threadId)));
-
     const startProviderSession = (input?: {
       readonly resumeCursor?: unknown;
-      readonly provider?: ProviderKind;
+      readonly provider?: ProviderDriverKind;
     }) =>
       providerService.startSession(threadId, {
         threadId,
         ...(preferredProvider ? { provider: preferredProvider } : {}),
+        providerInstanceId: desiredInstanceId,
         ...(effectiveCwd ? { cwd: effectiveCwd } : {}),
         modelSelection: desiredModelSelection,
         ...(input?.resumeCursor !== undefined ? { resumeCursor: input.resumeCursor } : {}),
@@ -275,66 +415,79 @@ const make = Effect.gen(function* () {
       });
 
     const bindSessionToThread = (session: ProviderSession) =>
-      setThreadSession({
-        threadId,
-        session: {
+      Effect.gen(function* () {
+        if (session.providerInstanceId === undefined) {
+          return yield* new ProviderAdapterRequestError({
+            provider: providerErrorLabel(session.provider),
+            method: "thread.turn.start",
+            detail: `Provider session '${session.threadId}' started without a provider instance id.`,
+          });
+        }
+        yield* setThreadSession({
           threadId,
-          status: mapProviderSessionStatusToOrchestrationStatus(session.status),
-          providerName: session.provider,
-          runtimeMode: desiredRuntimeMode,
-          // Provider turn ids are not orchestration turn ids.
-          activeTurnId: null,
-          lastError: session.lastError ?? null,
-          updatedAt: session.updatedAt,
-        },
-        createdAt,
+          session: {
+            threadId,
+            status: mapProviderSessionStatusToOrchestrationStatus(session.status),
+            providerName: session.provider,
+            providerInstanceId: session.providerInstanceId,
+            runtimeMode: desiredRuntimeMode,
+            // Provider turn ids are not orchestration turn ids.
+            activeTurnId: null,
+            lastError: session.lastError ?? null,
+            updatedAt: session.updatedAt,
+          },
+          createdAt,
+        });
       });
 
     const existingSessionThreadId =
-      thread.session && thread.session.status !== "stopped" ? thread.id : null;
+      thread.session && thread.session.status !== "stopped" && activeSession ? thread.id : null;
     if (existingSessionThreadId) {
       const runtimeModeChanged = thread.runtimeMode !== thread.session?.runtimeMode;
-      const providerChanged =
-        requestedModelSelection !== undefined &&
-        requestedModelSelection.provider !== currentProvider;
-      const activeSession = yield* resolveActiveSession(existingSessionThreadId);
-      const sessionModelSwitch =
-        currentProvider === undefined
-          ? "in-session"
-          : (yield* providerService.getCapabilities(currentProvider)).sessionModelSwitch;
+      const cwdChanged = effectiveCwd !== activeSession?.cwd;
+      const sessionModelSwitch = (yield* providerService.getCapabilities(desiredInstanceId))
+        .sessionModelSwitch;
       const modelChanged =
         requestedModelSelection !== undefined &&
         requestedModelSelection.model !== activeSession?.model;
-      const shouldRestartForModelChange = modelChanged && sessionModelSwitch === "restart-session";
+      const instanceChanged =
+        requestedModelSelection !== undefined &&
+        activeSession?.providerInstanceId !== requestedModelSelection.instanceId;
+      const shouldRestartForModelChange = modelChanged && sessionModelSwitch === "unsupported";
       const previousModelSelection = threadModelSelections.get(threadId);
       const shouldRestartForModelSelectionChange =
-        currentProvider === "claudeAgent" &&
+        preferredProvider === "claudeAgent" &&
         requestedModelSelection !== undefined &&
         !Equal.equals(previousModelSelection, requestedModelSelection);
 
       if (
         !runtimeModeChanged &&
-        !providerChanged &&
+        !cwdChanged &&
+        !instanceChanged &&
         !shouldRestartForModelChange &&
         !shouldRestartForModelSelectionChange
       ) {
         return existingSessionThreadId;
       }
 
-      const resumeCursor =
-        providerChanged || shouldRestartForModelChange
-          ? undefined
-          : (activeSession?.resumeCursor ?? undefined);
+      const resumeCursor = shouldRestartForModelChange
+        ? undefined
+        : (activeSession?.resumeCursor ?? undefined);
       yield* Effect.logInfo("provider command reactor restarting provider session", {
         threadId,
         existingSessionThreadId,
-        currentProvider,
-        desiredProvider: desiredModelSelection.provider,
+        currentProvider: activeSession?.provider,
+        currentInstanceId,
+        desiredInstanceId,
+        desiredProvider: desiredModelSelection.instanceId,
         currentRuntimeMode: thread.session?.runtimeMode,
         desiredRuntimeMode: thread.runtimeMode,
         runtimeModeChanged,
-        providerChanged,
+        previousCwd: activeSession?.cwd,
+        desiredCwd: effectiveCwd,
+        cwdChanged,
         modelChanged,
+        instanceChanged,
         shouldRestartForModelChange,
         shouldRestartForModelSelectionChange,
         hasResumeCursor: resumeCursor !== undefined,
@@ -348,6 +501,7 @@ const make = Effect.gen(function* () {
         restartedSessionThreadId: restartedSession.threadId,
         provider: restartedSession.provider,
         runtimeMode: restartedSession.runtimeMode,
+        cwd: restartedSession.cwd,
       });
       yield* bindSessionToThread(restartedSession);
       return restartedSession.threadId;
@@ -358,7 +512,7 @@ const make = Effect.gen(function* () {
     return startedSession.threadId;
   });
 
-  const sendTurnForThread = Effect.fn("sendTurnForThread")(function* (input: {
+  const buildSendTurnRequestForThread = Effect.fnUntraced(function* (input: {
     readonly threadId: ThreadId;
     readonly messageText: string;
     readonly attachments?: ReadonlyArray<ChatAttachment>;
@@ -368,7 +522,9 @@ const make = Effect.gen(function* () {
   }) {
     const thread = yield* resolveThread(input.threadId);
     if (!thread) {
-      return;
+      return yield* Effect.die(
+        new Error(`Thread '${input.threadId}' was not found in read model.`),
+      );
     }
     yield* ensureSessionForThread(
       input.threadId,
@@ -388,11 +544,18 @@ const make = Effect.gen(function* () {
     const sessionModelSwitch =
       activeSession === undefined
         ? "in-session"
-        : (yield* providerService.getCapabilities(activeSession.provider)).sessionModelSwitch;
+        : activeSession.providerInstanceId === undefined
+          ? yield* new ProviderAdapterRequestError({
+              provider: providerErrorLabel(activeSession.provider),
+              method: "thread.turn.start",
+              detail: `Active provider session '${activeSession.threadId}' is missing a provider instance id.`,
+            })
+          : (yield* providerService.getCapabilities(activeSession.providerInstanceId))
+              .sessionModelSwitch;
     const requestedModelSelection =
       input.modelSelection ?? threadModelSelections.get(input.threadId) ?? thread.modelSelection;
     const modelForTurn =
-      sessionModelSwitch === "unsupported"
+      sessionModelSwitch === "unsupported" && input.modelSelection === undefined
         ? activeSession?.model !== undefined
           ? {
               ...requestedModelSelection,
@@ -401,13 +564,13 @@ const make = Effect.gen(function* () {
           : requestedModelSelection
         : input.modelSelection;
 
-    yield* providerService.sendTurn({
+    return {
       threadId: input.threadId,
       ...(normalizedInput ? { input: normalizedInput } : {}),
       ...(normalizedAttachments.length > 0 ? { attachments: normalizedAttachments } : {}),
       ...(modelForTurn !== undefined ? { modelSelection: modelForTurn } : {}),
       ...(input.interactionMode !== undefined ? { interactionMode: input.interactionMode } : {}),
-    });
+    };
   });
 
   const maybeGenerateAndRenameWorktreeBranchForFirstTurn = Effect.fn(
@@ -444,7 +607,7 @@ const make = Effect.gen(function* () {
       const targetBranch = buildGeneratedWorktreeBranchName(generated.branch);
       if (targetBranch === oldBranch) return;
 
-      const renamed = yield* git.renameBranch({ cwd, oldBranch, newBranch: targetBranch });
+      const renamed = yield* gitWorkflow.renameBranch({ cwd, oldBranch, newBranch: targetBranch });
       yield* orchestrationEngine.dispatch({
         type: "thread.meta.update",
         commandId: serverCommandId("worktree-branch-rename"),
@@ -452,6 +615,7 @@ const make = Effect.gen(function* () {
         branch: renamed.branch,
         worktreePath: cwd,
       });
+      yield* vcsStatusBroadcaster.refreshStatus(cwd).pipe(Effect.ignoreCause({ log: true }));
     }).pipe(
       Effect.catchCause((cause) =>
         Effect.logWarning("provider command reactor failed to generate or rename worktree branch", {
@@ -538,10 +702,11 @@ const make = Effect.gen(function* () {
     const isFirstUserMessageTurn =
       thread.messages.filter((entry) => entry.role === "user").length === 1;
     if (isFirstUserMessageTurn) {
+      const project = yield* resolveProject(thread.projectId);
       const generationCwd =
         resolveThreadWorkspaceCwd({
           thread,
-          projects: (yield* orchestrationEngine.getReadModel()).projects,
+          projects: project ? [project] : [],
         }) ?? process.cwd();
       const generationInput = {
         messageText: message.text,
@@ -565,7 +730,43 @@ const make = Effect.gen(function* () {
       }
     }
 
-    yield* sendTurnForThread({
+    const handleTurnStartFailure = (cause: Cause.Cause<unknown>) => {
+      if (Cause.hasInterruptsOnly(cause)) {
+        return Effect.void;
+      }
+      const detail = formatFailureDetail(cause);
+      return setThreadSessionErrorOnTurnStartFailure({
+        threadId: event.payload.threadId,
+        detail,
+        createdAt: event.payload.createdAt,
+      }).pipe(
+        Effect.flatMap(() =>
+          appendProviderFailureActivity({
+            threadId: event.payload.threadId,
+            kind: "provider.turn.start.failed",
+            summary: "Provider turn start failed",
+            detail,
+            turnId: null,
+            createdAt: event.payload.createdAt,
+          }),
+        ),
+        Effect.asVoid,
+      );
+    };
+
+    const recoverTurnStartFailure = (cause: Cause.Cause<unknown>) =>
+      handleTurnStartFailure(cause).pipe(
+        Effect.catchCause((recoveryCause) =>
+          Effect.logWarning("provider command reactor failed to recover turn start failure", {
+            eventType: event.type,
+            threadId: event.payload.threadId,
+            cause: Cause.pretty(recoveryCause),
+            originalCause: Cause.pretty(cause),
+          }),
+        ),
+      );
+
+    const sendTurnRequest = yield* buildSendTurnRequestForThread({
       threadId: event.payload.threadId,
       messageText: message.text,
       ...(message.attachments !== undefined ? { attachments: message.attachments } : {}),
@@ -575,17 +776,17 @@ const make = Effect.gen(function* () {
       interactionMode: event.payload.interactionMode,
       createdAt: event.payload.createdAt,
     }).pipe(
-      Effect.catchCause((cause) =>
-        appendProviderFailureActivity({
-          threadId: event.payload.threadId,
-          kind: "provider.turn.start.failed",
-          summary: "Provider turn start failed",
-          detail: Cause.pretty(cause),
-          turnId: null,
-          createdAt: event.payload.createdAt,
-        }),
-      ),
+      Effect.map(Option.some),
+      Effect.catchCause((cause) => handleTurnStartFailure(cause).pipe(Effect.as(Option.none()))),
     );
+
+    if (Option.isNone(sendTurnRequest)) {
+      return;
+    }
+
+    yield* providerService
+      .sendTurn(sendTurnRequest.value)
+      .pipe(Effect.catchCause(recoverTurnStartFailure), Effect.forkScoped);
   });
 
   const processTurnInterruptRequested = Effect.fn("processTurnInterruptRequested")(function* (
@@ -639,20 +840,16 @@ const make = Effect.gen(function* () {
       })
       .pipe(
         Effect.catchCause((cause) =>
-          Effect.gen(function* () {
-            yield* appendProviderFailureActivity({
-              threadId: event.payload.threadId,
-              kind: "provider.approval.respond.failed",
-              summary: "Provider approval response failed",
-              detail: isUnknownPendingApprovalRequestError(cause)
-                ? stalePendingRequestDetail("approval", event.payload.requestId)
-                : Cause.pretty(cause),
-              turnId: null,
-              createdAt: event.payload.createdAt,
-              requestId: event.payload.requestId,
-            });
-
-            if (!isUnknownPendingApprovalRequestError(cause)) return;
+          appendProviderFailureActivity({
+            threadId: event.payload.threadId,
+            kind: "provider.approval.respond.failed",
+            summary: "Provider approval response failed",
+            detail: isUnknownPendingApprovalRequestError(cause)
+              ? stalePendingRequestDetail("approval", event.payload.requestId)
+              : Cause.pretty(cause),
+            turnId: null,
+            createdAt: event.payload.createdAt,
+            requestId: event.payload.requestId,
           }),
         ),
       );
@@ -722,6 +919,9 @@ const make = Effect.gen(function* () {
         threadId: thread.id,
         status: "stopped",
         providerName: thread.session?.providerName ?? null,
+        ...(thread.session?.providerInstanceId !== undefined
+          ? { providerInstanceId: thread.session.providerInstanceId }
+          : {}),
         runtimeMode: thread.session?.runtimeMode ?? DEFAULT_RUNTIME_MODE,
         activeTurnId: null,
         lastError: thread.session?.lastError ?? null,
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
index 2a330a36b53..3b2411cba2a 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
@@ -1,11 +1,14 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import type {
+import {
   OrchestrationReadModel,
+  ProviderDriverKind,
   ProviderRuntimeEvent,
   ProviderSession,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import {
   ApprovalRequestId,
@@ -19,7 +22,14 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Effect, Exit, Layer, ManagedRuntime, PubSub, Scope, Stream } from "effect";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as PubSub from "effect/PubSub";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import { afterEach, describe, expect, it } from "vitest";
 
 import { OrchestrationEventStoreLive } from "../../persistence/Layers/OrchestrationEventStore.ts";
@@ -34,11 +44,9 @@ import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
 import { OrchestrationProjectionPipelineLive } from "./ProjectionPipeline.ts";
 import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQuery.ts";
 import { ProviderRuntimeIngestionLive } from "./ProviderRuntimeIngestion.ts";
-import {
-  OrchestrationEngineService,
-  type OrchestrationEngineShape,
-} from "../Services/OrchestrationEngine.ts";
+import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import { ProviderRuntimeIngestionService } from "../Services/ProviderRuntimeIngestion.ts";
+import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import { ServerConfig } from "../../config.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -98,6 +106,19 @@ function createProviderServiceHarness() {
     stopSession: () => unsupported(),
     listSessions: () => Effect.succeed([...runtimeSessions]),
     getCapabilities: () => Effect.succeed({ sessionModelSwitch: "in-session" }),
+    getInstanceInfo: (instanceId) => {
+      const driverKind = ProviderDriverKind.make(String(instanceId));
+      return Effect.succeed({
+        instanceId,
+        driverKind,
+        displayName: undefined,
+        enabled: true,
+        continuationIdentity: {
+          driverKind,
+          continuationKey: `${driverKind}:instance:${instanceId}`,
+        },
+      });
+    },
     rollbackConversation: () => unsupported(),
     get streamEvents() {
       return Stream.fromPubSub(runtimeEventPubSub);
@@ -139,38 +160,38 @@ function createProviderServiceHarness() {
   };
 }
 
+type ProviderRuntimeTestReadModel = OrchestrationReadModel;
+type ProviderRuntimeTestThread = ProviderRuntimeTestReadModel["threads"][number];
+type ProviderRuntimeTestMessage = ProviderRuntimeTestThread["messages"][number];
+type ProviderRuntimeTestProposedPlan = ProviderRuntimeTestThread["proposedPlans"][number];
+type ProviderRuntimeTestActivity = ProviderRuntimeTestThread["activities"][number];
+type ProviderRuntimeTestCheckpoint = ProviderRuntimeTestThread["checkpoints"][number];
+
 async function waitForThread(
-  engine: OrchestrationEngineShape,
+  readModel: () => Promise<ProviderRuntimeTestReadModel>,
   predicate: (thread: ProviderRuntimeTestThread) => boolean,
   timeoutMs = 2000,
   threadId: ThreadId = asThreadId("thread-1"),
 ) {
-  const deadline = Date.now() + timeoutMs;
+  const deadline = (await Effect.runPromise(Clock.currentTimeMillis)) + timeoutMs;
   const poll = async (): Promise<ProviderRuntimeTestThread> => {
-    const readModel = await Effect.runPromise(engine.getReadModel());
-    const thread = readModel.threads.find((entry) => entry.id === threadId);
+    const snapshot = await readModel();
+    const thread = snapshot.threads.find((entry) => entry.id === threadId);
     if (thread && predicate(thread)) {
       return thread;
     }
-    if (Date.now() >= deadline) {
+    if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
       throw new Error("Timed out waiting for thread state");
     }
-    await new Promise((resolve) => setTimeout(resolve, 10));
+    await Effect.runPromise(Effect.yieldNow);
     return poll();
   };
   return poll();
 }
 
-type ProviderRuntimeTestReadModel = OrchestrationReadModel;
-type ProviderRuntimeTestThread = ProviderRuntimeTestReadModel["threads"][number];
-type ProviderRuntimeTestMessage = ProviderRuntimeTestThread["messages"][number];
-type ProviderRuntimeTestProposedPlan = ProviderRuntimeTestThread["proposedPlans"][number];
-type ProviderRuntimeTestActivity = ProviderRuntimeTestThread["activities"][number];
-type ProviderRuntimeTestCheckpoint = ProviderRuntimeTestThread["checkpoints"][number];
-
 describe("ProviderRuntimeIngestion", () => {
   let runtime: ManagedRuntime.ManagedRuntime<
-    OrchestrationEngineService | ProviderRuntimeIngestionService,
+    OrchestrationEngineService | ProviderRuntimeIngestionService | ProjectionSnapshotQuery,
     unknown
   > | null = null;
   let scope: Scope.Closeable | null = null;
@@ -208,8 +229,13 @@ describe("ProviderRuntimeIngestion", () => {
       Layer.provide(RepositoryIdentityResolverLive),
       Layer.provide(SqlitePersistenceMemory),
     );
+    const projectionSnapshotLayer = OrchestrationProjectionSnapshotQueryLive.pipe(
+      Layer.provide(RepositoryIdentityResolverLive),
+      Layer.provide(SqlitePersistenceMemory),
+    );
     const layer = ProviderRuntimeIngestionLive.pipe(
       Layer.provideMerge(orchestrationLayer),
+      Layer.provideMerge(projectionSnapshotLayer),
       Layer.provideMerge(SqlitePersistenceMemory),
       Layer.provideMerge(Layer.succeed(ProviderService, provider.service)),
       Layer.provideMerge(makeTestServerSettingsLayer(options?.serverSettings)),
@@ -218,12 +244,13 @@ describe("ProviderRuntimeIngestion", () => {
     );
     runtime = ManagedRuntime.make(layer);
     const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
+    const snapshotQuery = await runtime.runPromise(Effect.service(ProjectionSnapshotQuery));
     const ingestion = await runtime.runPromise(Effect.service(ProviderRuntimeIngestionService));
     scope = await Effect.runPromise(Scope.make("sequential"));
     await Effect.runPromise(ingestion.start().pipe(Scope.provide(scope)));
     const drain = () => Effect.runPromise(ingestion.drain);
 
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
     await Effect.runPromise(
       engine.dispatch({
         type: "project.create",
@@ -232,7 +259,7 @@ describe("ProviderRuntimeIngestion", () => {
         title: "Provider Project",
         workspaceRoot,
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -246,7 +273,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -274,7 +301,7 @@ describe("ProviderRuntimeIngestion", () => {
       }),
     );
     provider.setSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "ready",
       runtimeMode: "approval-required",
       threadId: ThreadId.make("thread-1"),
@@ -284,6 +311,7 @@ describe("ProviderRuntimeIngestion", () => {
 
     return {
       engine,
+      readModel: () => Effect.runPromise(snapshotQuery.getSnapshot()),
       emit: provider.emit,
       setProviderSession: provider.setSession,
       drain,
@@ -292,28 +320,28 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("maps turn started/completed events into thread session updates", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
       createdAt: now,
       turnId: asTurnId("turn-1"),
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) => thread.session?.status === "running" && thread.session?.activeTurnId === "turn-1",
     );
 
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       turnId: asTurnId("turn-1"),
       payload: {
         state: "failed",
@@ -322,7 +350,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "error" &&
         entry.session?.activeTurnId === null &&
@@ -334,12 +362,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("applies provider session.state.changed transitions directly", async () => {
     const harness = await createHarness();
-    const waitingAt = new Date().toISOString();
+    const waitingAt = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "session.state.changed",
       eventId: asEventId("evt-session-state-waiting"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
       createdAt: waitingAt,
       payload: {
@@ -349,7 +377,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     let thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) => entry.session?.status === "running" && entry.session?.activeTurnId === null,
     );
     expect(thread.session?.status).toBe("running");
@@ -358,9 +386,9 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "session.state.changed",
       eventId: asEventId("evt-session-state-error"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       payload: {
         state: "error",
         reason: "provider crashed",
@@ -368,7 +396,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "error" &&
         entry.session?.activeTurnId === null &&
@@ -380,16 +408,16 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "session.state.changed",
       eventId: asEventId("evt-session-state-stopped"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       payload: {
         state: "stopped",
       },
     });
 
     thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "stopped" &&
         entry.session?.activeTurnId === null &&
@@ -401,16 +429,16 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "session.state.changed",
       eventId: asEventId("evt-session-state-ready"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
-      createdAt: new Date().toISOString(),
+      createdAt: "2026-01-01T00:00:00.000Z",
       payload: {
         state: "ready",
       },
     });
 
     thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "ready" &&
         entry.session?.activeTurnId === null &&
@@ -422,19 +450,19 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("does not clear active turn when session/thread started arrives mid-turn", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-midturn-lifecycle"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-midturn-lifecycle"),
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" &&
         thread.session?.activeTurnId === "turn-midturn-lifecycle",
@@ -443,20 +471,20 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "thread.started",
       eventId: asEventId("evt-thread-started-midturn-lifecycle"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
     });
     harness.emit({
       type: "session.started",
       eventId: asEventId("evt-session-started-midturn-lifecycle"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
     });
 
     await harness.drain();
-    const midReadModel = await Effect.runPromise(harness.engine.getReadModel());
+    const midReadModel = await harness.readModel();
     const midThread = midReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(midThread?.session?.status).toBe("running");
     expect(midThread?.session?.activeTurnId).toBe("turn-midturn-lifecycle");
@@ -464,22 +492,22 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-midturn-lifecycle"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-midturn-lifecycle"),
       status: "completed",
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) => thread.session?.status === "ready" && thread.session?.activeTurnId === null,
     );
   });
 
   it("accepts claude turn lifecycle when seeded thread id is a synthetic placeholder", async () => {
     const harness = await createHarness();
-    const seededAt = new Date().toISOString();
+    const seededAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -502,14 +530,14 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-claude-placeholder"),
-      provider: "claudeAgent",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("claudeAgent"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-claude-placeholder"),
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" &&
         thread.session?.activeTurnId === "turn-claude-placeholder",
@@ -518,34 +546,34 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-claude-placeholder"),
-      provider: "claudeAgent",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("claudeAgent"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-claude-placeholder"),
       status: "completed",
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) => thread.session?.status === "ready" && thread.session?.activeTurnId === null,
     );
   });
 
   it("ignores auxiliary turn completions from a different provider thread", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-primary"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-primary"),
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" && thread.session?.activeTurnId === "turn-primary",
     );
@@ -553,15 +581,15 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-aux"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-aux"),
       status: "completed",
     });
 
     await harness.drain();
-    const midReadModel = await Effect.runPromise(harness.engine.getReadModel());
+    const midReadModel = await harness.readModel();
     const midThread = midReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(midThread?.session?.status).toBe("running");
     expect(midThread?.session?.activeTurnId).toBe("turn-primary");
@@ -569,34 +597,34 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-primary"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-primary"),
       status: "completed",
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) => thread.session?.status === "ready" && thread.session?.activeTurnId === null,
     );
   });
 
   it("ignores non-active turn completion when runtime omits thread id", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-guarded"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-guarded-main"),
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" &&
         thread.session?.activeTurnId === "turn-guarded-main",
@@ -605,15 +633,15 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-guarded-other"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-guarded-other"),
       status: "completed",
     });
 
     await harness.drain();
-    const midReadModel = await Effect.runPromise(harness.engine.getReadModel());
+    const midReadModel = await harness.readModel();
     const midThread = midReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(midThread?.session?.status).toBe("running");
     expect(midThread?.session?.activeTurnId).toBe("turn-guarded-main");
@@ -621,27 +649,27 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-guarded-main"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-guarded-main"),
       status: "completed",
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) => thread.session?.status === "ready" && thread.session?.activeTurnId === null,
     );
   });
 
   it("maps canonical content delta/item completed into finalized assistant messages", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-1"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-2"),
@@ -654,7 +682,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-2"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-2"),
@@ -667,7 +695,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-message-completed"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-2"),
@@ -678,7 +706,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.messages.some(
         (message: ProviderRuntimeTestMessage) =>
           message.id === "assistant:item-1" && !message.streaming,
@@ -693,12 +721,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("uses assistant item completion detail when no assistant deltas were streamed", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-assistant-item-completed-no-delta"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-no-delta"),
@@ -710,7 +738,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.messages.some(
         (message: ProviderRuntimeTestMessage) =>
           message.id === "assistant:item-no-delta" && !message.streaming,
@@ -723,14 +751,154 @@ describe("ProviderRuntimeIngestion", () => {
     expect(message?.streaming).toBe(false);
   });
 
+  it("preserves completed tool metadata on projected tool activities", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    harness.emit({
+      type: "item.completed",
+      eventId: asEventId("evt-tool-completed-with-data"),
+      provider: ProviderDriverKind.make("cursor"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-tool-completed"),
+      itemId: asItemId("item-tool-completed"),
+      payload: {
+        itemType: "dynamic_tool_call",
+        status: "completed",
+        title: "Read file",
+        data: {
+          toolCallId: "tool-read-1",
+          kind: "read",
+          rawOutput: {
+            content: 'import * as Effect from "effect/Effect"\n',
+          },
+        },
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.activities.some(
+        (activity: ProviderRuntimeTestActivity) => activity.id === "evt-tool-completed-with-data",
+      ),
+    );
+    const activity = thread.activities.find(
+      (entry: ProviderRuntimeTestActivity) => entry.id === "evt-tool-completed-with-data",
+    );
+    const payload =
+      activity?.payload && typeof activity.payload === "object"
+        ? (activity.payload as Record<string, unknown>)
+        : undefined;
+    const data =
+      payload?.data && typeof payload.data === "object"
+        ? (payload.data as Record<string, unknown>)
+        : undefined;
+    const rawOutput =
+      data?.rawOutput && typeof data.rawOutput === "object"
+        ? (data.rawOutput as Record<string, unknown>)
+        : undefined;
+
+    expect(activity?.kind).toBe("tool.completed");
+    expect(activity?.summary).toBe("Read file");
+    expect(payload?.itemType).toBe("dynamic_tool_call");
+    expect(payload?.detail).toBeUndefined();
+    expect(data?.toolCallId).toBe("tool-read-1");
+    expect(data?.kind).toBe("read");
+    expect(rawOutput?.content).toBe('import * as Effect from "effect/Effect"\n');
+  });
+
+  it("normalizes command execution activities to ran-command summaries", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    harness.emit({
+      type: "item.completed",
+      eventId: asEventId("evt-command-completed"),
+      provider: ProviderDriverKind.make("cursor"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-command-completed"),
+      itemId: asItemId("item-command-completed"),
+      payload: {
+        itemType: "command_execution",
+        status: "completed",
+        title: "Ran command",
+        detail: "bun run lint",
+        data: {
+          toolCallId: "tool-command-1",
+          kind: "execute",
+          command: "bun run lint",
+        },
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.activities.some(
+        (activity: ProviderRuntimeTestActivity) => activity.id === "evt-command-completed",
+      ),
+    );
+    const activity = thread.activities.find(
+      (entry: ProviderRuntimeTestActivity) => entry.id === "evt-command-completed",
+    );
+    const payload =
+      activity?.payload && typeof activity.payload === "object"
+        ? (activity.payload as Record<string, unknown>)
+        : undefined;
+
+    expect(activity?.summary).toBe("Ran command");
+    expect(payload?.detail).toBe("bun run lint");
+  });
+
+  it("uses structured read-file paths when available", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    harness.emit({
+      type: "item.completed",
+      eventId: asEventId("evt-read-path-completed"),
+      provider: ProviderDriverKind.make("cursor"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-read-path"),
+      itemId: asItemId("item-read-path"),
+      payload: {
+        itemType: "dynamic_tool_call",
+        status: "completed",
+        title: "Read file",
+        detail: "/tmp/app.ts",
+        data: {
+          toolCallId: "tool-read-path-1",
+          kind: "read",
+          locations: [{ path: "/tmp/app.ts" }],
+        },
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.activities.some(
+        (activity: ProviderRuntimeTestActivity) => activity.id === "evt-read-path-completed",
+      ),
+    );
+    const activity = thread.activities.find(
+      (entry: ProviderRuntimeTestActivity) => entry.id === "evt-read-path-completed",
+    );
+    const payload =
+      activity?.payload && typeof activity.payload === "object"
+        ? (activity.payload as Record<string, unknown>)
+        : undefined;
+
+    expect(activity?.summary).toBe("Read file");
+    expect(payload?.detail).toBe("/tmp/app.ts");
+  });
+
   it("projects completed plan items into first-class proposed plans", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.proposed.completed",
       eventId: asEventId("evt-plan-item-completed"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-plan-final"),
@@ -739,7 +907,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.proposedPlans.some(
         (proposedPlan: ProviderRuntimeTestProposedPlan) =>
           proposedPlan.id === "plan:thread-1:turn:turn-plan-final",
@@ -759,7 +927,7 @@ describe("ProviderRuntimeIngestion", () => {
     const targetThreadId = asThreadId("thread-implement");
     const sourceTurnId = asTurnId("turn-plan-source");
     const targetTurnId = asTurnId("turn-plan-implement");
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -769,7 +937,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Source",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: "plan",
@@ -804,7 +972,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Target",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -832,7 +1000,7 @@ describe("ProviderRuntimeIngestion", () => {
       }),
     );
     harness.setProviderSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "ready",
       runtimeMode: "approval-required",
       threadId: targetThreadId,
@@ -844,7 +1012,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.proposed.completed",
       eventId: asEventId("evt-plan-source-completed"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt,
       threadId: sourceThreadId,
       turnId: sourceTurnId,
@@ -854,7 +1022,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const sourceThreadWithPlan = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.proposedPlans.some(
           (proposedPlan: ProviderRuntimeTestProposedPlan) =>
@@ -890,12 +1058,12 @@ describe("ProviderRuntimeIngestion", () => {
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
       }),
     );
 
     const sourceThreadBeforeStart = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.proposedPlans.some(
           (proposedPlan: ProviderRuntimeTestProposedPlan) =>
@@ -914,14 +1082,14 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-plan-target-started"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: targetThreadId,
       turnId: targetTurnId,
     });
 
     const sourceThreadAfterStart = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.proposedPlans.some(
           (proposedPlan: ProviderRuntimeTestProposedPlan) =>
@@ -946,7 +1114,7 @@ describe("ProviderRuntimeIngestion", () => {
     const sourceTurnId = asTurnId("turn-plan-source");
     const activeTurnId = asTurnId("turn-already-running");
     const staleTurnId = asTurnId("turn-stale-start");
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -956,7 +1124,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Source",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: "plan",
@@ -984,7 +1152,7 @@ describe("ProviderRuntimeIngestion", () => {
       }),
     );
     harness.setProviderSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "running",
       runtimeMode: "approval-required",
       threadId: targetThreadId,
@@ -996,14 +1164,14 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-already-running"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt,
       threadId: targetThreadId,
       turnId: activeTurnId,
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" && thread.session?.activeTurnId === activeTurnId,
       2_000,
@@ -1013,7 +1181,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.proposed.completed",
       eventId: asEventId("evt-plan-source-completed-guarded"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt,
       threadId: sourceThreadId,
       turnId: sourceTurnId,
@@ -1023,7 +1191,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const sourceThreadWithPlan = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.proposedPlans.some(
           (proposedPlan: ProviderRuntimeTestProposedPlan) =>
@@ -1059,22 +1227,22 @@ describe("ProviderRuntimeIngestion", () => {
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
       }),
     );
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-stale-plan-implementation"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: targetThreadId,
       turnId: staleTurnId,
     });
 
     await harness.drain();
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const sourceThreadAfterRejectedStart = readModel.threads.find(
       (entry) => entry.id === sourceThreadId,
     );
@@ -1099,7 +1267,7 @@ describe("ProviderRuntimeIngestion", () => {
     const sourceTurnId = asTurnId("turn-plan-source");
     const expectedTurnId = asTurnId("turn-plan-implement");
     const replayedTurnId = asTurnId("turn-replayed");
-    const createdAt = new Date().toISOString();
+    const createdAt = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1109,7 +1277,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Source",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: "plan",
@@ -1144,7 +1312,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Target",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -1175,7 +1343,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.proposed.completed",
       eventId: asEventId("evt-plan-source-completed-unrelated"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt,
       threadId: sourceThreadId,
       turnId: sourceTurnId,
@@ -1185,7 +1353,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const sourceThreadWithPlan = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.proposedPlans.some(
           (proposedPlan: ProviderRuntimeTestProposedPlan) =>
@@ -1221,12 +1389,12 @@ describe("ProviderRuntimeIngestion", () => {
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
         runtimeMode: "approval-required",
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
       }),
     );
 
     harness.setProviderSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "running",
       runtimeMode: "approval-required",
       threadId: targetThreadId,
@@ -1238,15 +1406,15 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-unrelated-plan-implementation"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: targetThreadId,
       turnId: replayedTurnId,
     });
 
     await harness.drain();
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const sourceThreadAfterUnrelatedStart = readModel.threads.find(
       (entry) => entry.id === sourceThreadId,
     );
@@ -1260,19 +1428,19 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("finalizes buffered proposed-plan deltas into a first-class proposed plan on turn completion", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-plan-buffer"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-plan-buffer"),
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" && thread.session?.activeTurnId === "turn-plan-buffer",
     );
@@ -1280,7 +1448,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.proposed.delta",
       eventId: asEventId("evt-plan-delta-1"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-plan-buffer"),
@@ -1291,7 +1459,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.proposed.delta",
       eventId: asEventId("evt-plan-delta-2"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-plan-buffer"),
@@ -1302,7 +1470,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-plan-buffer"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-plan-buffer"),
@@ -1311,7 +1479,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.proposedPlans.some(
         (proposedPlan: ProviderRuntimeTestProposedPlan) =>
           proposedPlan.id === "plan:thread-1:turn:turn-plan-buffer",
@@ -1326,18 +1494,18 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("buffers assistant deltas by default until completion", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-buffered"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered"),
     });
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" && thread.session?.activeTurnId === "turn-buffered",
     );
@@ -1345,7 +1513,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-buffered"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered"),
@@ -1357,7 +1525,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     await harness.drain();
-    const midReadModel = await Effect.runPromise(harness.engine.getReadModel());
+    const midReadModel = await harness.readModel();
     const midThread = midReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(
       midThread?.messages.some(
@@ -1368,7 +1536,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-message-completed-buffered"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered"),
@@ -1379,7 +1547,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.messages.some(
         (message: ProviderRuntimeTestMessage) =>
           message.id === "assistant:item-buffered" && !message.streaming,
@@ -1392,9 +1560,435 @@ describe("ProviderRuntimeIngestion", () => {
     expect(message?.streaming).toBe(false);
   });
 
+  it("flushes and completes buffered assistant text when an approval request opens", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    harness.emit({
+      type: "turn.started",
+      eventId: asEventId("evt-turn-started-buffered-request-flush"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-flush"),
+    });
+    await waitForThread(
+      harness.readModel,
+      (thread) =>
+        thread.session?.status === "running" &&
+        thread.session?.activeTurnId === "turn-buffered-request-flush",
+    );
+
+    harness.emit({
+      type: "content.delta",
+      eventId: asEventId("evt-message-delta-buffered-request-flush"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-flush"),
+      itemId: asItemId("item-buffered-request-flush"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: "visible before approval",
+      },
+    });
+    harness.emit({
+      type: "request.opened",
+      eventId: asEventId("evt-request-opened-buffered-request-flush"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-flush"),
+      requestId: ApprovalRequestId.make("req-buffered-request-flush"),
+      payload: {
+        requestType: "command_execution_approval",
+        detail: "pwd",
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.messages.some(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-buffered-request-flush" &&
+          !message.streaming &&
+          message.text === "visible before approval",
+      ),
+    );
+    const message = thread.messages.find(
+      (entry: ProviderRuntimeTestMessage) => entry.id === "assistant:item-buffered-request-flush",
+    );
+    expect(message?.streaming).toBe(false);
+  });
+
+  it("flushes and completes buffered assistant text when user input is requested", async () => {
+    const harness = await createHarness();
+    const now = "2026-01-01T00:00:00.000Z";
+
+    harness.emit({
+      type: "turn.started",
+      eventId: asEventId("evt-turn-started-buffered-user-input-flush"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-user-input-flush"),
+    });
+    await waitForThread(
+      harness.readModel,
+      (thread) =>
+        thread.session?.status === "running" &&
+        thread.session?.activeTurnId === "turn-buffered-user-input-flush",
+    );
+
+    harness.emit({
+      type: "content.delta",
+      eventId: asEventId("evt-message-delta-buffered-user-input-flush"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-user-input-flush"),
+      itemId: asItemId("item-buffered-user-input-flush"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: "visible before user input",
+      },
+    });
+    harness.emit({
+      type: "user-input.requested",
+      eventId: asEventId("evt-user-input-requested-buffered-user-input-flush"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: now,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-user-input-flush"),
+      requestId: ApprovalRequestId.make("req-buffered-user-input-flush"),
+      payload: {
+        questions: [
+          {
+            id: "choice",
+            header: "Choice",
+            question: "Pick one",
+            options: [{ label: "A", description: "Option A" }],
+          },
+        ],
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.messages.some(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-buffered-user-input-flush" &&
+          !message.streaming &&
+          message.text === "visible before user input",
+      ),
+    );
+    const message = thread.messages.find(
+      (entry: ProviderRuntimeTestMessage) =>
+        entry.id === "assistant:item-buffered-user-input-flush",
+    );
+    expect(message?.streaming).toBe(false);
+  });
+
+  it("does not create assistant segments for whitespace-only buffered text at approval boundaries", async () => {
+    const harness = await createHarness();
+    const startedAt = "2026-03-28T06:28:00.000Z";
+    const pausedAt = "2026-03-28T06:28:01.000Z";
+
+    harness.emit({
+      type: "turn.started",
+      eventId: asEventId("evt-turn-started-buffered-whitespace-request"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: startedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-whitespace-request"),
+    });
+    await waitForThread(
+      harness.readModel,
+      (thread) =>
+        thread.session?.status === "running" &&
+        thread.session?.activeTurnId === "turn-buffered-whitespace-request",
+    );
+
+    harness.emit({
+      type: "content.delta",
+      eventId: asEventId("evt-message-delta-buffered-whitespace-request"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: startedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-whitespace-request"),
+      itemId: asItemId("item-buffered-whitespace-request"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: "\n\n\n",
+      },
+    });
+    harness.emit({
+      type: "request.opened",
+      eventId: asEventId("evt-request-opened-buffered-whitespace-request"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: pausedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-whitespace-request"),
+      requestId: ApprovalRequestId.make("req-buffered-whitespace-request"),
+      payload: {
+        requestType: "command_execution_approval",
+        detail: "pwd",
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.activities.some(
+        (activity: ProviderRuntimeTestActivity) => activity.kind === "approval.requested",
+      ),
+    );
+    expect(
+      thread.messages.some(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-buffered-whitespace-request",
+      ),
+    ).toBe(false);
+  });
+
+  it("starts a new buffered assistant message segment after approval and completes without duplication", async () => {
+    const harness = await createHarness();
+    const startedAt = "2026-03-28T06:07:00.000Z";
+    const pausedAt = "2026-03-28T06:07:01.000Z";
+    const resumedAt = "2026-03-28T06:07:02.000Z";
+    const completedAt = "2026-03-28T06:07:03.000Z";
+
+    harness.emit({
+      type: "turn.started",
+      eventId: asEventId("evt-turn-started-buffered-request-append"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: startedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-append"),
+    });
+    await waitForThread(
+      harness.readModel,
+      (thread) =>
+        thread.session?.status === "running" &&
+        thread.session?.activeTurnId === "turn-buffered-request-append",
+    );
+
+    harness.emit({
+      type: "content.delta",
+      eventId: asEventId("evt-message-delta-buffered-request-append-initial"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: startedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-append"),
+      itemId: asItemId("item-buffered-request-append"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: "first half",
+      },
+    });
+    harness.emit({
+      type: "request.opened",
+      eventId: asEventId("evt-request-opened-buffered-request-append"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: pausedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-append"),
+      requestId: ApprovalRequestId.make("req-buffered-request-append"),
+      payload: {
+        requestType: "command_execution_approval",
+        detail: "pwd",
+      },
+    });
+
+    await waitForThread(harness.readModel, (entry) =>
+      entry.messages.some(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-buffered-request-append" &&
+          !message.streaming &&
+          message.text === "first half",
+      ),
+    );
+
+    harness.emit({
+      type: "content.delta",
+      eventId: asEventId("evt-message-delta-buffered-request-append-followup"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: resumedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-append"),
+      itemId: asItemId("item-buffered-request-append"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: " second half",
+      },
+    });
+    harness.emit({
+      type: "item.completed",
+      eventId: asEventId("evt-message-completed-buffered-request-append"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: completedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-buffered-request-append"),
+      itemId: asItemId("item-buffered-request-append"),
+      payload: {
+        itemType: "assistant_message",
+        status: "completed",
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.messages.some(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-buffered-request-append:segment:1" &&
+          !message.streaming &&
+          message.text === " second half",
+      ),
+    );
+    const firstMessage = thread.messages.find(
+      (entry: ProviderRuntimeTestMessage) => entry.id === "assistant:item-buffered-request-append",
+    );
+    const resumedMessage = thread.messages.find(
+      (entry: ProviderRuntimeTestMessage) =>
+        entry.id === "assistant:item-buffered-request-append:segment:1",
+    );
+    expect(firstMessage?.text).toBe("first half");
+    expect(firstMessage?.streaming).toBe(false);
+    expect(resumedMessage?.text).toBe(" second half");
+    expect(resumedMessage?.streaming).toBe(false);
+
+    const events = await Effect.runPromise(
+      Stream.runCollect(harness.engine.readEvents(0)).pipe(
+        Effect.map((chunk) => Array.from(chunk)),
+      ),
+    );
+    const assistantEvents = events.filter(
+      (event): event is Extract<(typeof events)[number], { type: "thread.message-sent" }> =>
+        event.type === "thread.message-sent" &&
+        event.payload.messageId.startsWith("assistant:item-buffered-request-append"),
+    );
+    expect(assistantEvents).toHaveLength(4);
+    expect(assistantEvents[0]?.payload.streaming).toBe(true);
+    expect(assistantEvents[0]?.payload.text).toBe("first half");
+    expect(assistantEvents[1]?.payload.streaming).toBe(false);
+    expect(assistantEvents[1]?.payload.text).toBe("");
+    expect(assistantEvents[2]?.payload.messageId).toBe(
+      "assistant:item-buffered-request-append:segment:1",
+    );
+    expect(assistantEvents[2]?.payload.streaming).toBe(true);
+    expect(assistantEvents[2]?.payload.text).toBe(" second half");
+    expect(assistantEvents[3]?.payload.messageId).toBe(
+      "assistant:item-buffered-request-append:segment:1",
+    );
+    expect(assistantEvents[3]?.payload.streaming).toBe(false);
+    expect(assistantEvents[3]?.payload.text).toBe("");
+  });
+
+  it("starts a new streaming assistant message segment after approval", async () => {
+    const harness = await createHarness({ serverSettings: { enableAssistantStreaming: true } });
+    const startedAt = "2026-03-28T07:00:00.000Z";
+    const pausedAt = "2026-03-28T07:00:01.000Z";
+    const resumedAt = "2026-03-28T07:00:02.000Z";
+    const completedAt = "2026-03-28T07:00:03.000Z";
+
+    harness.emit({
+      type: "turn.started",
+      eventId: asEventId("evt-turn-started-streaming-request-segment"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: startedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-streaming-request-segment"),
+    });
+    await waitForThread(
+      harness.readModel,
+      (thread) =>
+        thread.session?.status === "running" &&
+        thread.session?.activeTurnId === "turn-streaming-request-segment",
+    );
+
+    harness.emit({
+      type: "content.delta",
+      eventId: asEventId("evt-message-delta-streaming-request-segment-initial"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: startedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-streaming-request-segment"),
+      itemId: asItemId("item-streaming-request-segment"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: "before approval",
+      },
+    });
+    harness.emit({
+      type: "request.opened",
+      eventId: asEventId("evt-request-opened-streaming-request-segment"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: pausedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-streaming-request-segment"),
+      requestId: ApprovalRequestId.make("req-streaming-request-segment"),
+      payload: {
+        requestType: "command_execution_approval",
+        detail: "pwd",
+      },
+    });
+
+    await waitForThread(harness.readModel, (entry) =>
+      entry.messages.some(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-streaming-request-segment" &&
+          !message.streaming &&
+          message.text === "before approval",
+      ),
+    );
+
+    harness.emit({
+      type: "content.delta",
+      eventId: asEventId("evt-message-delta-streaming-request-segment-followup"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: resumedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-streaming-request-segment"),
+      itemId: asItemId("item-streaming-request-segment"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: " after approval",
+      },
+    });
+    harness.emit({
+      type: "item.completed",
+      eventId: asEventId("evt-message-completed-streaming-request-segment"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: completedAt,
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-streaming-request-segment"),
+      itemId: asItemId("item-streaming-request-segment"),
+      payload: {
+        itemType: "assistant_message",
+        status: "completed",
+      },
+    });
+
+    const thread = await waitForThread(harness.readModel, (entry) =>
+      entry.messages.some(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-streaming-request-segment:segment:1" &&
+          !message.streaming &&
+          message.text === " after approval",
+      ),
+    );
+    expect(
+      thread.messages.find(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-streaming-request-segment",
+      )?.text,
+    ).toBe("before approval");
+    expect(
+      thread.messages.find(
+        (message: ProviderRuntimeTestMessage) =>
+          message.id === "assistant:item-streaming-request-segment:segment:1",
+      )?.text,
+    ).toBe(" after approval");
+  });
+
   it("streams assistant deltas when thread.turn.start requests streaming mode", async () => {
     const harness = await createHarness({ serverSettings: { enableAssistantStreaming: true } });
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
       harness.engine.dispatch({
@@ -1417,13 +2011,13 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-streaming-mode"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-mode"),
     });
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" &&
         thread.session?.activeTurnId === "turn-streaming-mode",
@@ -1432,7 +2026,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-streaming-mode"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-mode"),
@@ -1443,7 +2037,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const liveThread = await waitForThread(harness.engine, (entry) =>
+    const liveThread = await waitForThread(harness.readModel, (entry) =>
       entry.messages.some(
         (message: ProviderRuntimeTestMessage) =>
           message.id === "assistant:item-streaming-mode" &&
@@ -1459,7 +2053,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-message-completed-streaming-mode"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-mode"),
@@ -1471,7 +2065,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const finalThread = await waitForThread(harness.engine, (entry) =>
+    const finalThread = await waitForThread(harness.readModel, (entry) =>
       entry.messages.some(
         (message: ProviderRuntimeTestMessage) =>
           message.id === "assistant:item-streaming-mode" && !message.streaming,
@@ -1486,19 +2080,19 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("spills oversized buffered deltas and still finalizes full assistant text", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const oversizedText = "x".repeat(40_000);
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-buffer-spill"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffer-spill"),
     });
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" &&
         thread.session?.activeTurnId === "turn-buffer-spill",
@@ -1507,7 +2101,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-buffer-spill"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffer-spill"),
@@ -1520,7 +2114,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-message-completed-buffer-spill"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffer-spill"),
@@ -1531,7 +2125,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.messages.some(
         (message: ProviderRuntimeTestMessage) =>
           message.id === "assistant:item-buffer-spill" && !message.streaming,
@@ -1547,19 +2141,19 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("does not duplicate assistant completion when item.completed is followed by turn.completed", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-for-complete-dedup"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-complete-dedup"),
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "running" &&
         thread.session?.activeTurnId === "turn-complete-dedup",
@@ -1568,7 +2162,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-for-complete-dedup"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-complete-dedup"),
@@ -1581,7 +2175,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-message-completed-for-complete-dedup"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-complete-dedup"),
@@ -1594,7 +2188,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-for-complete-dedup"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-complete-dedup"),
@@ -1604,7 +2198,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (thread) =>
         thread.session?.status === "ready" &&
         thread.session?.activeTurnId === null &&
@@ -1633,12 +2227,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("maps canonical request events into approval activities with requestKind", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "request.opened",
       eventId: asEventId("evt-request-opened"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       requestId: ApprovalRequestId.make("req-open"),
@@ -1651,7 +2245,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "request.resolved",
       eventId: asEventId("evt-request-resolved"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       requestId: ApprovalRequestId.make("req-open"),
@@ -1662,7 +2256,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.activities.some(
           (activity: ProviderRuntimeTestActivity) => activity.kind === "approval.requested",
@@ -1672,7 +2266,7 @@ describe("ProviderRuntimeIngestion", () => {
         ),
     );
 
-    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const readModel = await harness.readModel();
     const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(thread).toBeDefined();
 
@@ -1699,12 +2293,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("maps runtime.error into errored session state", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "runtime.error",
       eventId: asEventId("evt-runtime-error"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-3"),
@@ -1714,7 +2308,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "error" &&
         entry.session?.activeTurnId === "turn-3" &&
@@ -1726,12 +2320,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("records runtime.error activities from the typed payload message", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "runtime.error",
       eventId: asEventId("evt-runtime-error-activity"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-runtime-error-activity"),
@@ -1740,7 +2334,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.activities.some((activity) => activity.id === "evt-runtime-error-activity"),
     );
     const activity = thread.activities.find(
@@ -1757,12 +2351,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("keeps the session running when a runtime.warning arrives during an active turn", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-warning-turn-started"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-warning"),
@@ -1772,7 +2366,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "runtime.warning",
       eventId: asEventId("evt-warning-runtime"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-warning"),
@@ -1785,7 +2379,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "running" &&
         entry.session?.activeTurnId === "turn-warning" &&
@@ -1801,12 +2395,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("maps session/thread lifecycle and item.started into session/activity projections", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "session.started",
       eventId: asEventId("evt-session-started"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       message: "session started",
@@ -1814,14 +2408,14 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "thread.started",
       eventId: asEventId("evt-thread-started"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
     });
     harness.emit({
       type: "item.started",
       eventId: asEventId("evt-tool-started"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-9"),
@@ -1834,7 +2428,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "ready" &&
         entry.session?.activeTurnId === null &&
@@ -1853,12 +2447,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("consumes P1 runtime events into thread metadata, diff checkpoints, and activities", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "thread.metadata.updated",
       eventId: asEventId("evt-thread-metadata-updated"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       payload: {
@@ -1870,7 +2464,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.plan.updated",
       eventId: asEventId("evt-turn-plan-updated"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-p1"),
@@ -1886,7 +2480,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.updated",
       eventId: asEventId("evt-item-updated"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-p1"),
@@ -1903,7 +2497,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "runtime.warning",
       eventId: asEventId("evt-runtime-warning"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-p1"),
@@ -1916,7 +2510,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.diff.updated",
       eventId: asEventId("evt-turn-diff-updated"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-p1"),
@@ -1927,7 +2521,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.title === "Renamed by provider" &&
         entry.activities.some(
@@ -1987,12 +2581,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("projects context window updates into normalized thread activities", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "thread.token-usage.updated",
       eventId: asEventId("evt-thread-token-usage-updated"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       payload: {
@@ -2014,7 +2608,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.activities.some(
         (activity: ProviderRuntimeTestActivity) => activity.kind === "context-window.updated",
       ),
@@ -2039,12 +2633,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("projects Codex camelCase token usage payloads into normalized thread activities", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "thread.token-usage.updated",
       eventId: asEventId("evt-thread-token-usage-updated-camel"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       payload: {
@@ -2066,7 +2660,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.activities.some(
         (activity: ProviderRuntimeTestActivity) => activity.kind === "context-window.updated",
       ),
@@ -2092,12 +2686,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("projects Claude usage snapshots with context window into normalized thread activities", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "thread.token-usage.updated",
       eventId: asEventId("evt-thread-token-usage-updated-claude-window"),
-      provider: "claudeAgent",
+      provider: ProviderDriverKind.make("claudeAgent"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       payload: {
@@ -2116,7 +2710,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.activities.some(
         (activity: ProviderRuntimeTestActivity) => activity.kind === "context-window.updated",
       ),
@@ -2136,12 +2730,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("projects compacted thread state into context compaction activities", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "thread.state.changed",
       eventId: asEventId("evt-thread-compacted"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-1"),
@@ -2151,7 +2745,7 @@ describe("ProviderRuntimeIngestion", () => {
       },
     });
 
-    const thread = await waitForThread(harness.engine, (entry) =>
+    const thread = await waitForThread(harness.readModel, (entry) =>
       entry.activities.some(
         (activity: ProviderRuntimeTestActivity) => activity.kind === "context-compaction",
       ),
@@ -2166,12 +2760,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("projects Codex task lifecycle chunks into thread activities", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "task.started",
       eventId: asEventId("evt-task-started"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-task-1"),
@@ -2184,7 +2778,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "task.progress",
       eventId: asEventId("evt-task-progress"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-task-1"),
@@ -2198,7 +2792,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "task.completed",
       eventId: asEventId("evt-task-completed"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-task-1"),
@@ -2211,7 +2805,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.proposed.completed",
       eventId: asEventId("evt-task-proposed-plan-completed"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-task-1"),
@@ -2221,7 +2815,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.activities.some(
           (activity: ProviderRuntimeTestActivity) => activity.kind === "task.completed",
@@ -2269,12 +2863,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("projects structured user input request and resolution as thread activities", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "user-input.requested",
       eventId: asEventId("evt-user-input-requested"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-user-input"),
@@ -2299,8 +2893,8 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "user-input.resolved",
       eventId: asEventId("evt-user-input-resolved"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-user-input"),
       requestId: ApprovalRequestId.make("req-user-input-1"),
@@ -2312,7 +2906,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.activities.some(
           (activity: ProviderRuntimeTestActivity) => activity.kind === "user-input.requested",
@@ -2342,12 +2936,12 @@ describe("ProviderRuntimeIngestion", () => {
 
   it("continues processing runtime events after a single event handler failure", async () => {
     const harness = await createHarness();
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
 
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-invalid-delta"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-invalid"),
@@ -2361,8 +2955,8 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "runtime.error",
       eventId: asEventId("evt-runtime-error-after-failure"),
-      provider: "codex",
-      createdAt: new Date().toISOString(),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-after-failure"),
       payload: {
@@ -2371,7 +2965,7 @@ describe("ProviderRuntimeIngestion", () => {
     });
 
     const thread = await waitForThread(
-      harness.engine,
+      harness.readModel,
       (entry) =>
         entry.session?.status === "error" &&
         entry.session?.activeTurnId === "turn-after-failure" &&
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
index c1241241cce..2c07ac91b1e 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
@@ -4,24 +4,34 @@ import {
   CommandId,
   MessageId,
   type OrchestrationEvent,
+  type OrchestrationMessage,
   type OrchestrationProposedPlanId,
   CheckpointRef,
   isToolLifecycleItemType,
   ThreadId,
   type ThreadTokenUsageSnapshot,
   TurnId,
+  type OrchestrationCheckpointSummary,
+  type OrchestrationProposedPlan,
+  type OrchestrationThread,
   type OrchestrationThreadActivity,
   type ProviderRuntimeEvent,
 } from "@t3tools/contracts";
-import { Cache, Cause, Duration, Effect, Layer, Option, Stream } from "effect";
+import * as Cache from "effect/Cache";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
 import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
 
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { ProjectionTurnRepository } from "../../persistence/Services/ProjectionTurns.ts";
 import { ProjectionTurnRepositoryLive } from "../../persistence/Layers/ProjectionTurns.ts";
-import { resolveThreadWorkspaceCwd } from "../../checkpointing/Utils.ts";
 import { isGitRepository } from "../../git/Utils.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import {
   ProviderRuntimeIngestionService,
   type ProviderRuntimeIngestionShape,
@@ -32,6 +42,12 @@ const providerTurnKey = (threadId: ThreadId, turnId: TurnId) => `${threadId}:${t
 const providerCommandId = (event: ProviderRuntimeEvent, tag: string): CommandId =>
   CommandId.make(`provider:${event.eventId}:${tag}:${crypto.randomUUID()}`);
 
+interface AssistantSegmentState {
+  baseKey: string;
+  nextSegmentIndex: number;
+  activeMessageId: MessageId | null;
+}
+
 const TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY = 10_000;
 const TURN_MESSAGE_IDS_BY_TURN_TTL = Duration.minutes(120);
 const BUFFERED_MESSAGE_TEXT_BY_MESSAGE_ID_CACHE_CAPACITY = 20_000;
@@ -71,6 +87,82 @@ function sameId(left: string | null | undefined, right: string | null | undefine
   return left === right;
 }
 
+function hasAssistantMessageForTurn(
+  messages: ReadonlyArray<OrchestrationMessage>,
+  turnId: TurnId,
+  options?: { readonly streamingOnly?: boolean },
+): boolean {
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index];
+    if (!message) {
+      continue;
+    }
+    if (message.role !== "assistant" || message.turnId !== turnId) {
+      continue;
+    }
+    if (options?.streamingOnly === true && !message.streaming) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+function findMessageById(
+  messages: ReadonlyArray<OrchestrationMessage>,
+  messageId: MessageId,
+): OrchestrationMessage | undefined {
+  for (let index = 0; index < messages.length; index += 1) {
+    const message = messages[index];
+    if (message?.id === messageId) {
+      return message;
+    }
+  }
+  return undefined;
+}
+
+function findProposedPlanById(
+  proposedPlans: ReadonlyArray<
+    Pick<OrchestrationProposedPlan, "id" | "createdAt" | "implementedAt" | "implementationThreadId">
+  >,
+  planId: string,
+):
+  | Pick<OrchestrationProposedPlan, "id" | "createdAt" | "implementedAt" | "implementationThreadId">
+  | undefined {
+  for (let index = 0; index < proposedPlans.length; index += 1) {
+    const proposedPlan = proposedPlans[index];
+    if (proposedPlan?.id === planId) {
+      return proposedPlan;
+    }
+  }
+  return undefined;
+}
+
+function hasCheckpointForTurn(
+  checkpoints: ReadonlyArray<OrchestrationCheckpointSummary>,
+  turnId: TurnId,
+): boolean {
+  for (let index = 0; index < checkpoints.length; index += 1) {
+    if (checkpoints[index]?.turnId === turnId) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function maxCheckpointTurnCount(
+  checkpoints: ReadonlyArray<OrchestrationCheckpointSummary>,
+): number {
+  let maxTurnCount = 0;
+  for (let index = 0; index < checkpoints.length; index += 1) {
+    const checkpoint = checkpoints[index];
+    if (checkpoint && checkpoint.checkpointTurnCount > maxTurnCount) {
+      maxTurnCount = checkpoint.checkpointTurnCount;
+    }
+  }
+  return maxTurnCount;
+}
+
 function truncateDetail(value: string, limit = 180): string {
   return value.length > limit ? `${value.slice(0, limit - 3)}...` : value;
 }
@@ -83,6 +175,10 @@ function normalizeProposedPlanMarkdown(planMarkdown: string | undefined): string
   return trimmed;
 }
 
+function hasRenderableAssistantText(text: string | undefined): boolean {
+  return (text?.trim().length ?? 0) > 0;
+}
+
 function proposedPlanIdForTurn(threadId: ThreadId, turnId: TurnId): string {
   return `plan:${threadId}:turn:${turnId}`;
 }
@@ -98,6 +194,15 @@ function proposedPlanIdFromEvent(event: ProviderRuntimeEvent, threadId: ThreadId
   return `plan:${threadId}:event:${event.eventId}`;
 }
 
+function assistantSegmentBaseKeyFromEvent(event: ProviderRuntimeEvent): string {
+  return String(event.itemId ?? event.turnId ?? event.eventId);
+}
+
+function assistantSegmentMessageId(baseKey: string, segmentIndex: number): MessageId {
+  return MessageId.make(
+    segmentIndex === 0 ? `assistant:${baseKey}` : `assistant:${baseKey}:segment:${segmentIndex}`,
+  );
+}
 function buildContextWindowActivityPayload(
   event: ProviderRuntimeEvent,
 ): ThreadTokenUsageSnapshot | undefined {
@@ -465,6 +570,7 @@ function runtimeEventToActivities(
           payload: {
             itemType: event.payload.itemType,
             ...(event.payload.detail ? { detail: truncateDetail(event.payload.detail) } : {}),
+            ...(event.payload.data !== undefined ? { data: event.payload.data } : {}),
           },
           turnId: toTurnId(event.turnId) ?? null,
           ...maybeSequence,
@@ -500,8 +606,9 @@ function runtimeEventToActivities(
   return [];
 }
 
-const make = Effect.fn("make")(function* () {
+const make = Effect.gen(function* () {
   const orchestrationEngine = yield* OrchestrationEngineService;
+  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
   const providerService = yield* ProviderService;
   const projectionTurnRepository = yield* ProjectionTurnRepository;
   const serverSettingsService = yield* ServerSettingsService;
@@ -518,26 +625,31 @@ const make = Effect.fn("make")(function* () {
     lookup: () => Effect.succeed(""),
   });
 
+  const assistantSegmentStateByTurnKey = yield* Cache.make<string, AssistantSegmentState>({
+    capacity: TURN_MESSAGE_IDS_BY_TURN_CACHE_CAPACITY,
+    timeToLive: TURN_MESSAGE_IDS_BY_TURN_TTL,
+    lookup: () =>
+      Effect.die(
+        new Error("assistant segment state should be read through getOption before initialization"),
+      ),
+  });
+
   const bufferedProposedPlanById = yield* Cache.make<string, { text: string; createdAt: string }>({
     capacity: BUFFERED_PROPOSED_PLAN_BY_ID_CACHE_CAPACITY,
     timeToLive: BUFFERED_PROPOSED_PLAN_BY_ID_TTL,
     lookup: () => Effect.succeed({ text: "", createdAt: "" }),
   });
 
-  const isGitRepoForThread = Effect.fn("isGitRepoForThread")(function* (threadId: ThreadId) {
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === threadId);
-    if (!thread) {
-      return false;
-    }
-    const workspaceCwd = resolveThreadWorkspaceCwd({
-      thread,
-      projects: readModel.projects,
-    });
-    if (!workspaceCwd) {
-      return false;
-    }
-    return isGitRepository(workspaceCwd);
+  const resolveThreadDetail = Effect.fn("resolveThreadDetail")(function* (threadId: ThreadId) {
+    return yield* projectionSnapshotQuery
+      .getThreadDetailById(threadId)
+      .pipe(Effect.map(Option.getOrUndefined));
+  });
+
+  const resolveThreadShell = Effect.fn("resolveThreadShell")(function* (threadId: ThreadId) {
+    return yield* projectionSnapshotQuery
+      .getThreadShellById(threadId)
+      .pipe(Effect.map(Option.getOrUndefined));
   });
 
   const rememberAssistantMessageId = (threadId: ThreadId, turnId: TurnId, messageId: MessageId) =>
@@ -585,10 +697,86 @@ const make = Effect.fn("make")(function* () {
   const clearAssistantMessageIdsForTurn = (threadId: ThreadId, turnId: TurnId) =>
     Cache.invalidate(turnMessageIdsByTurnKey, providerTurnKey(threadId, turnId));
 
+  const getAssistantSegmentStateForTurn = (threadId: ThreadId, turnId: TurnId) =>
+    Cache.getOption(assistantSegmentStateByTurnKey, providerTurnKey(threadId, turnId));
+
+  const setAssistantSegmentStateForTurn = (
+    threadId: ThreadId,
+    turnId: TurnId,
+    state: AssistantSegmentState,
+  ) => Cache.set(assistantSegmentStateByTurnKey, providerTurnKey(threadId, turnId), state);
+
+  const clearAssistantSegmentStateForTurn = (threadId: ThreadId, turnId: TurnId) =>
+    Cache.invalidate(assistantSegmentStateByTurnKey, providerTurnKey(threadId, turnId));
+
+  const getActiveAssistantMessageIdForTurn = (threadId: ThreadId, turnId: TurnId) =>
+    getAssistantSegmentStateForTurn(threadId, turnId).pipe(
+      Effect.map((state) =>
+        Option.flatMap(state, (entry) =>
+          entry.activeMessageId ? Option.some(entry.activeMessageId) : Option.none(),
+        ),
+      ),
+    );
+
+  const startAssistantSegmentForTurn = (input: {
+    threadId: ThreadId;
+    turnId: TurnId;
+    baseKey: string;
+  }) =>
+    getAssistantSegmentStateForTurn(input.threadId, input.turnId).pipe(
+      Effect.flatMap((existingState) =>
+        Effect.gen(function* () {
+          const nextState = Option.match(existingState, {
+            onNone: () => ({
+              baseKey: input.baseKey,
+              nextSegmentIndex: 1,
+              activeMessageId: assistantSegmentMessageId(input.baseKey, 0),
+            }),
+            onSome: (state) => {
+              const segmentIndex = state.baseKey === input.baseKey ? state.nextSegmentIndex : 0;
+              const messageId = assistantSegmentMessageId(input.baseKey, segmentIndex);
+              return {
+                baseKey: input.baseKey,
+                nextSegmentIndex: state.baseKey === input.baseKey ? state.nextSegmentIndex + 1 : 1,
+                activeMessageId: messageId,
+              } satisfies AssistantSegmentState;
+            },
+          });
+          yield* setAssistantSegmentStateForTurn(input.threadId, input.turnId, nextState);
+          return nextState.activeMessageId!;
+        }),
+      ),
+    );
+
+  const getOrCreateAssistantMessageId = (input: {
+    threadId: ThreadId;
+    event: ProviderRuntimeEvent;
+    turnId?: TurnId;
+  }) =>
+    Effect.gen(function* () {
+      if (!input.turnId) {
+        return assistantSegmentMessageId(assistantSegmentBaseKeyFromEvent(input.event), 0);
+      }
+
+      const activeMessageId = yield* getActiveAssistantMessageIdForTurn(
+        input.threadId,
+        input.turnId,
+      );
+      if (Option.isSome(activeMessageId)) {
+        return activeMessageId.value;
+      }
+
+      return yield* startAssistantSegmentForTurn({
+        threadId: input.threadId,
+        turnId: input.turnId,
+        baseKey: assistantSegmentBaseKeyFromEvent(input.event),
+      });
+    });
+
   const appendBufferedAssistantText = (messageId: MessageId, delta: string) =>
     Cache.getOption(bufferedAssistantTextByMessageId, messageId).pipe(
-      Effect.flatMap(
-        Effect.fn("appendBufferedAssistantText")(function* (existingText) {
+      Effect.flatMap((existingText) =>
+        Effect.gen(function* () {
           const nextText = Option.match(existingText, {
             onNone: () => delta,
             onSome: (text) => `${text}${delta}`,
@@ -644,48 +832,154 @@ const make = Effect.fn("make")(function* () {
   const clearAssistantMessageState = (messageId: MessageId) =>
     clearBufferedAssistantText(messageId);
 
-  const finalizeAssistantMessage = Effect.fn("finalizeAssistantMessage")(function* (input: {
+  const flushBufferedAssistantMessage = (input: {
     event: ProviderRuntimeEvent;
     threadId: ThreadId;
     messageId: MessageId;
     turnId?: TurnId;
     createdAt: string;
     commandTag: string;
-    finalDeltaCommandTag: string;
-    fallbackText?: string;
-  }) {
-    const bufferedText = yield* takeBufferedAssistantText(input.messageId);
-    const text =
-      bufferedText.length > 0
-        ? bufferedText
-        : (input.fallbackText?.trim().length ?? 0) > 0
-          ? input.fallbackText!
-          : "";
-
-    if (text.length > 0) {
+  }) =>
+    Effect.gen(function* () {
+      const bufferedText = yield* takeBufferedAssistantText(input.messageId);
+      if (!hasRenderableAssistantText(bufferedText)) {
+        return false;
+      }
+
       yield* orchestrationEngine.dispatch({
         type: "thread.message.assistant.delta",
-        commandId: providerCommandId(input.event, input.finalDeltaCommandTag),
+        commandId: providerCommandId(input.event, input.commandTag),
         threadId: input.threadId,
         messageId: input.messageId,
-        delta: text,
+        delta: bufferedText,
         ...(input.turnId ? { turnId: input.turnId } : {}),
         createdAt: input.createdAt,
       });
-    }
+      return true;
+    });
 
-    yield* orchestrationEngine.dispatch({
-      type: "thread.message.assistant.complete",
-      commandId: providerCommandId(input.event, input.commandTag),
-      threadId: input.threadId,
-      messageId: input.messageId,
-      ...(input.turnId ? { turnId: input.turnId } : {}),
-      createdAt: input.createdAt,
+  const flushBufferedAssistantMessagesForTurn = (input: {
+    event: ProviderRuntimeEvent;
+    threadId: ThreadId;
+    turnId: TurnId;
+    createdAt: string;
+    commandTag: string;
+  }) =>
+    Effect.gen(function* () {
+      const assistantMessageIds = yield* getAssistantMessageIdsForTurn(
+        input.threadId,
+        input.turnId,
+      );
+      const flushedMessageIds = new Set<MessageId>();
+      yield* Effect.forEach(
+        assistantMessageIds,
+        (messageId) =>
+          flushBufferedAssistantMessage({
+            event: input.event,
+            threadId: input.threadId,
+            messageId,
+            turnId: input.turnId,
+            createdAt: input.createdAt,
+            commandTag: input.commandTag,
+          }).pipe(
+            Effect.tap((flushed) =>
+              flushed ? Effect.sync(() => flushedMessageIds.add(messageId)) : Effect.void,
+            ),
+          ),
+        { concurrency: 1 },
+      ).pipe(Effect.asVoid);
+      return flushedMessageIds;
+    });
+
+  const finalizeAssistantMessage = (input: {
+    event: ProviderRuntimeEvent;
+    threadId: ThreadId;
+    messageId: MessageId;
+    turnId?: TurnId;
+    createdAt: string;
+    commandTag: string;
+    finalDeltaCommandTag: string;
+    fallbackText?: string;
+    hasProjectedMessage?: boolean;
+  }) =>
+    Effect.gen(function* () {
+      const bufferedText = yield* takeBufferedAssistantText(input.messageId);
+      const text =
+        bufferedText.length > 0
+          ? bufferedText
+          : (input.fallbackText?.trim().length ?? 0) > 0
+            ? input.fallbackText!
+            : "";
+      const hasRenderableText = hasRenderableAssistantText(text);
+
+      if (hasRenderableText) {
+        yield* orchestrationEngine.dispatch({
+          type: "thread.message.assistant.delta",
+          commandId: providerCommandId(input.event, input.finalDeltaCommandTag),
+          threadId: input.threadId,
+          messageId: input.messageId,
+          delta: text,
+          ...(input.turnId ? { turnId: input.turnId } : {}),
+          createdAt: input.createdAt,
+        });
+      }
+
+      if (input.hasProjectedMessage || hasRenderableText) {
+        yield* orchestrationEngine.dispatch({
+          type: "thread.message.assistant.complete",
+          commandId: providerCommandId(input.event, input.commandTag),
+          threadId: input.threadId,
+          messageId: input.messageId,
+          ...(input.turnId ? { turnId: input.turnId } : {}),
+          createdAt: input.createdAt,
+        });
+      }
+      yield* clearAssistantMessageState(input.messageId);
     });
-    yield* clearAssistantMessageState(input.messageId);
-  });
 
-  const upsertProposedPlan = Effect.fn("upsertProposedPlan")(function* (input: {
+  const finalizeActiveAssistantSegmentForTurn = (input: {
+    event: ProviderRuntimeEvent;
+    threadId: ThreadId;
+    turnId: TurnId;
+    createdAt: string;
+    commandTag: string;
+    finalDeltaCommandTag: string;
+    hasProjectedMessage: boolean;
+    flushedMessageIds?: ReadonlySet<MessageId>;
+  }) =>
+    Effect.gen(function* () {
+      const activeMessageId = yield* getActiveAssistantMessageIdForTurn(
+        input.threadId,
+        input.turnId,
+      );
+      if (Option.isNone(activeMessageId)) {
+        return;
+      }
+
+      yield* finalizeAssistantMessage({
+        event: input.event,
+        threadId: input.threadId,
+        messageId: activeMessageId.value,
+        turnId: input.turnId,
+        createdAt: input.createdAt,
+        commandTag: input.commandTag,
+        finalDeltaCommandTag: input.finalDeltaCommandTag,
+        hasProjectedMessage:
+          input.hasProjectedMessage ||
+          (input.flushedMessageIds?.has(activeMessageId.value) ?? false),
+      });
+      yield* forgetAssistantMessageId(input.threadId, input.turnId, activeMessageId.value);
+
+      const state = yield* getAssistantSegmentStateForTurn(input.threadId, input.turnId);
+      if (Option.isSome(state)) {
+        yield* setAssistantSegmentStateForTurn(input.threadId, input.turnId, {
+          ...state.value,
+          activeMessageId: null,
+        });
+      }
+    });
+
+  const upsertProposedPlan = (input: {
     event: ProviderRuntimeEvent;
     threadId: ThreadId;
     threadProposedPlans: ReadonlyArray<{
@@ -699,31 +993,32 @@ const make = Effect.fn("make")(function* () {
     planMarkdown: string | undefined;
     createdAt: string;
     updatedAt: string;
-  }) {
-    const planMarkdown = normalizeProposedPlanMarkdown(input.planMarkdown);
-    if (!planMarkdown) {
-      return;
-    }
+  }) =>
+    Effect.gen(function* () {
+      const planMarkdown = normalizeProposedPlanMarkdown(input.planMarkdown);
+      if (!planMarkdown) {
+        return;
+      }
 
-    const existingPlan = input.threadProposedPlans.find((entry) => entry.id === input.planId);
-    yield* orchestrationEngine.dispatch({
-      type: "thread.proposed-plan.upsert",
-      commandId: providerCommandId(input.event, "proposed-plan-upsert"),
-      threadId: input.threadId,
-      proposedPlan: {
-        id: input.planId,
-        turnId: input.turnId ?? null,
-        planMarkdown,
-        implementedAt: existingPlan?.implementedAt ?? null,
-        implementationThreadId: existingPlan?.implementationThreadId ?? null,
-        createdAt: existingPlan?.createdAt ?? input.createdAt,
-        updatedAt: input.updatedAt,
-      },
-      createdAt: input.updatedAt,
+      const existingPlan = findProposedPlanById(input.threadProposedPlans, input.planId);
+      yield* orchestrationEngine.dispatch({
+        type: "thread.proposed-plan.upsert",
+        commandId: providerCommandId(input.event, "proposed-plan-upsert"),
+        threadId: input.threadId,
+        proposedPlan: {
+          id: input.planId,
+          turnId: input.turnId ?? null,
+          planMarkdown,
+          implementedAt: existingPlan?.implementedAt ?? null,
+          implementationThreadId: existingPlan?.implementationThreadId ?? null,
+          createdAt: existingPlan?.createdAt ?? input.createdAt,
+          updatedAt: input.updatedAt,
+        },
+        createdAt: input.updatedAt,
+      });
     });
-  });
 
-  const finalizeBufferedProposedPlan = Effect.fn("finalizeBufferedProposedPlan")(function* (input: {
+  const finalizeBufferedProposedPlan = (input: {
     event: ProviderRuntimeEvent;
     threadId: ThreadId;
     threadProposedPlans: ReadonlyArray<{
@@ -736,65 +1031,75 @@ const make = Effect.fn("make")(function* () {
     turnId?: TurnId;
     fallbackMarkdown?: string;
     updatedAt: string;
-  }) {
-    const bufferedPlan = yield* takeBufferedProposedPlan(input.planId);
-    const bufferedMarkdown = normalizeProposedPlanMarkdown(bufferedPlan?.text);
-    const fallbackMarkdown = normalizeProposedPlanMarkdown(input.fallbackMarkdown);
-    const planMarkdown = bufferedMarkdown ?? fallbackMarkdown;
-    if (!planMarkdown) {
-      return;
-    }
+  }) =>
+    Effect.gen(function* () {
+      const bufferedPlan = yield* takeBufferedProposedPlan(input.planId);
+      const bufferedMarkdown = normalizeProposedPlanMarkdown(bufferedPlan?.text);
+      const fallbackMarkdown = normalizeProposedPlanMarkdown(input.fallbackMarkdown);
+      const planMarkdown = bufferedMarkdown ?? fallbackMarkdown;
+      if (!planMarkdown) {
+        return;
+      }
 
-    yield* upsertProposedPlan({
-      event: input.event,
-      threadId: input.threadId,
-      threadProposedPlans: input.threadProposedPlans,
-      planId: input.planId,
-      ...(input.turnId ? { turnId: input.turnId } : {}),
-      planMarkdown,
-      createdAt:
-        bufferedPlan?.createdAt && bufferedPlan.createdAt.length > 0
-          ? bufferedPlan.createdAt
-          : input.updatedAt,
-      updatedAt: input.updatedAt,
+      yield* upsertProposedPlan({
+        event: input.event,
+        threadId: input.threadId,
+        threadProposedPlans: input.threadProposedPlans,
+        planId: input.planId,
+        ...(input.turnId ? { turnId: input.turnId } : {}),
+        planMarkdown,
+        createdAt:
+          bufferedPlan?.createdAt && bufferedPlan.createdAt.length > 0
+            ? bufferedPlan.createdAt
+            : input.updatedAt,
+        updatedAt: input.updatedAt,
+      });
+      yield* clearBufferedProposedPlan(input.planId);
     });
-    yield* clearBufferedProposedPlan(input.planId);
-  });
 
-  const clearTurnStateForSession = Effect.fn("clearTurnStateForSession")(function* (
-    threadId: ThreadId,
-  ) {
-    const prefix = `${threadId}:`;
-    const proposedPlanPrefix = `plan:${threadId}:`;
-    const turnKeys = Array.from(yield* Cache.keys(turnMessageIdsByTurnKey));
-    const proposedPlanKeys = Array.from(yield* Cache.keys(bufferedProposedPlanById));
-    yield* Effect.forEach(
-      turnKeys,
-      Effect.fn(function* (key) {
-        if (!key.startsWith(prefix)) {
-          return;
-        }
+  const clearTurnStateForSession = (threadId: ThreadId) =>
+    Effect.gen(function* () {
+      const prefix = `${threadId}:`;
+      const proposedPlanPrefix = `plan:${threadId}:`;
+      const turnKeys = Array.from(yield* Cache.keys(turnMessageIdsByTurnKey));
+      const assistantSegmentKeys = Array.from(yield* Cache.keys(assistantSegmentStateByTurnKey));
+      const proposedPlanKeys = Array.from(yield* Cache.keys(bufferedProposedPlanById));
+      yield* Effect.forEach(
+        turnKeys,
+        (key) =>
+          Effect.gen(function* () {
+            if (!key.startsWith(prefix)) {
+              return;
+            }
 
-        const messageIds = yield* Cache.getOption(turnMessageIdsByTurnKey, key);
-        if (Option.isSome(messageIds)) {
-          yield* Effect.forEach(messageIds.value, clearAssistantMessageState, {
-            concurrency: 1,
-          }).pipe(Effect.asVoid);
-        }
+            const messageIds = yield* Cache.getOption(turnMessageIdsByTurnKey, key);
+            if (Option.isSome(messageIds)) {
+              yield* Effect.forEach(messageIds.value, clearAssistantMessageState, {
+                concurrency: 1,
+              }).pipe(Effect.asVoid);
+            }
 
-        yield* Cache.invalidate(turnMessageIdsByTurnKey, key);
-      }),
-      { concurrency: 1 },
-    ).pipe(Effect.asVoid);
-    yield* Effect.forEach(
-      proposedPlanKeys,
-      (key) =>
-        key.startsWith(proposedPlanPrefix)
-          ? Cache.invalidate(bufferedProposedPlanById, key)
-          : Effect.void,
-      { concurrency: 1 },
-    ).pipe(Effect.asVoid);
-  });
+            yield* Cache.invalidate(turnMessageIdsByTurnKey, key);
+          }),
+        { concurrency: 1 },
+      ).pipe(Effect.asVoid);
+      yield* Effect.forEach(
+        assistantSegmentKeys,
+        (key) =>
+          key.startsWith(prefix)
+            ? Cache.invalidate(assistantSegmentStateByTurnKey, key)
+            : Effect.void,
+        { concurrency: 1 },
+      ).pipe(Effect.asVoid);
+      yield* Effect.forEach(
+        proposedPlanKeys,
+        (key) =>
+          key.startsWith(proposedPlanPrefix)
+            ? Cache.invalidate(bufferedProposedPlanById, key)
+            : Effect.void,
+        { concurrency: 1 },
+      ).pipe(Effect.asVoid);
+    });
 
   const getSourceProposedPlanReferenceForPendingTurnStart = Effect.fn(
     "getSourceProposedPlanReferenceForPendingTurnStart",
@@ -848,8 +1153,7 @@ const make = Effect.fn("make")(function* () {
       implementationThreadId: ThreadId,
       implementedAt: string,
     ) {
-      const readModel = yield* orchestrationEngine.getReadModel();
-      const sourceThread = readModel.threads.find((entry) => entry.id === sourceThreadId);
+      const sourceThread = yield* resolveThreadDetail(sourceThreadId);
       const sourcePlan = sourceThread?.proposedPlans.find((entry) => entry.id === sourcePlanId);
       if (!sourceThread || !sourcePlan || sourcePlan.implementedAt !== null) {
         return;
@@ -872,353 +1176,452 @@ const make = Effect.fn("make")(function* () {
     },
   );
 
-  const processRuntimeEvent = Effect.fn("processRuntimeEvent")(function* (
-    event: ProviderRuntimeEvent,
-  ) {
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === event.threadId);
-    if (!thread) return;
+  const processRuntimeEvent = (event: ProviderRuntimeEvent) =>
+    Effect.gen(function* () {
+      const thread = yield* resolveThreadShell(event.threadId);
+      if (!thread) return;
 
-    const now = event.createdAt;
-    const eventTurnId = toTurnId(event.turnId);
-    const activeTurnId = thread.session?.activeTurnId ?? null;
+      let loadedThreadDetail: OrchestrationThread | null | undefined;
+      const getLoadedThreadDetail = () =>
+        Effect.gen(function* () {
+          if (loadedThreadDetail !== undefined) {
+            return loadedThreadDetail;
+          }
+          loadedThreadDetail = (yield* resolveThreadDetail(thread.id)) ?? null;
+          return loadedThreadDetail;
+        });
 
-    const conflictsWithActiveTurn =
-      activeTurnId !== null && eventTurnId !== undefined && !sameId(activeTurnId, eventTurnId);
-    const missingTurnForActiveTurn = activeTurnId !== null && eventTurnId === undefined;
+      const now = event.createdAt;
+      const eventTurnId = toTurnId(event.turnId);
+      const activeTurnId = thread.session?.activeTurnId ?? null;
 
-    const shouldApplyThreadLifecycle = (() => {
-      if (!STRICT_PROVIDER_LIFECYCLE_GUARD) {
-        return true;
-      }
-      switch (event.type) {
-        case "session.exited":
-          return true;
-        case "session.started":
-        case "thread.started":
-          return true;
-        case "turn.started":
-          return !conflictsWithActiveTurn;
-        case "turn.completed":
-          if (conflictsWithActiveTurn || missingTurnForActiveTurn) {
-            return false;
-          }
-          // Only the active turn may close the lifecycle state.
-          if (activeTurnId !== null && eventTurnId !== undefined) {
-            return sameId(activeTurnId, eventTurnId);
-          }
-          // If no active turn is tracked, accept completion scoped to this thread.
-          return true;
-        default:
+      const conflictsWithActiveTurn =
+        activeTurnId !== null && eventTurnId !== undefined && !sameId(activeTurnId, eventTurnId);
+      const missingTurnForActiveTurn = activeTurnId !== null && eventTurnId === undefined;
+
+      const shouldApplyThreadLifecycle = (() => {
+        if (!STRICT_PROVIDER_LIFECYCLE_GUARD) {
           return true;
-      }
-    })();
-    const acceptedTurnStartedSourcePlan =
-      event.type === "turn.started" && shouldApplyThreadLifecycle
-        ? yield* getSourceProposedPlanReferenceForAcceptedTurnStart(thread.id, eventTurnId)
-        : null;
-
-    if (
-      event.type === "session.started" ||
-      event.type === "session.state.changed" ||
-      event.type === "session.exited" ||
-      event.type === "thread.started" ||
-      event.type === "turn.started" ||
-      event.type === "turn.completed"
-    ) {
-      const nextActiveTurnId =
-        event.type === "turn.started"
-          ? (eventTurnId ?? null)
-          : event.type === "turn.completed" || event.type === "session.exited"
-            ? null
-            : activeTurnId;
-      const status = (() => {
+        }
         switch (event.type) {
-          case "session.state.changed":
-            return orchestrationSessionStatusFromRuntimeState(event.payload.state);
-          case "turn.started":
-            return "running";
           case "session.exited":
-            return "stopped";
-          case "turn.completed":
-            return normalizeRuntimeTurnState(event.payload.state) === "failed" ? "error" : "ready";
+            return true;
           case "session.started":
           case "thread.started":
-            // Provider thread/session start notifications can arrive during an
-            // active turn; preserve turn-running state in that case.
-            return activeTurnId !== null ? "running" : "ready";
+            return true;
+          case "turn.started":
+            return !conflictsWithActiveTurn;
+          case "turn.completed":
+            if (conflictsWithActiveTurn || missingTurnForActiveTurn) {
+              return false;
+            }
+            // Only the active turn may close the lifecycle state.
+            if (activeTurnId !== null && eventTurnId !== undefined) {
+              return sameId(activeTurnId, eventTurnId);
+            }
+            // If no active turn is tracked, accept completion scoped to this thread.
+            return true;
+          default:
+            return true;
         }
       })();
-      const lastError =
-        event.type === "session.state.changed" && event.payload.state === "error"
-          ? (event.payload.reason ?? thread.session?.lastError ?? "Provider session error")
-          : event.type === "turn.completed" &&
-              normalizeRuntimeTurnState(event.payload.state) === "failed"
-            ? (event.payload.errorMessage ?? thread.session?.lastError ?? "Turn failed")
-            : status === "ready"
+      const acceptedTurnStartedSourcePlan =
+        event.type === "turn.started" && shouldApplyThreadLifecycle
+          ? yield* getSourceProposedPlanReferenceForAcceptedTurnStart(thread.id, eventTurnId)
+          : null;
+
+      if (
+        event.type === "session.started" ||
+        event.type === "session.state.changed" ||
+        event.type === "session.exited" ||
+        event.type === "thread.started" ||
+        event.type === "turn.started" ||
+        event.type === "turn.completed"
+      ) {
+        const nextActiveTurnId =
+          event.type === "turn.started"
+            ? (eventTurnId ?? null)
+            : event.type === "turn.completed" || event.type === "session.exited"
               ? null
-              : (thread.session?.lastError ?? null);
-
-      if (shouldApplyThreadLifecycle) {
-        if (event.type === "turn.started" && acceptedTurnStartedSourcePlan !== null) {
-          yield* markSourceProposedPlanImplemented(
-            acceptedTurnStartedSourcePlan.sourceThreadId,
-            acceptedTurnStartedSourcePlan.sourcePlanId,
-            thread.id,
-            now,
-          ).pipe(
-            Effect.catchCause((cause) =>
-              Effect.logWarning("provider runtime ingestion failed to mark source proposed plan", {
-                eventId: event.eventId,
-                eventType: event.type,
-                cause: Cause.pretty(cause),
-              }),
-            ),
-          );
-        }
+              : activeTurnId;
+        const status = (() => {
+          switch (event.type) {
+            case "session.state.changed":
+              return orchestrationSessionStatusFromRuntimeState(event.payload.state);
+            case "turn.started":
+              return "running";
+            case "session.exited":
+              return "stopped";
+            case "turn.completed":
+              return normalizeRuntimeTurnState(event.payload.state) === "failed"
+                ? "error"
+                : "ready";
+            case "session.started":
+            case "thread.started":
+              // Provider thread/session start notifications can arrive during an
+              // active turn; preserve turn-running state in that case.
+              return activeTurnId !== null ? "running" : "ready";
+          }
+        })();
+        const lastError =
+          event.type === "session.state.changed" && event.payload.state === "error"
+            ? (event.payload.reason ?? thread.session?.lastError ?? "Provider session error")
+            : event.type === "turn.completed" &&
+                normalizeRuntimeTurnState(event.payload.state) === "failed"
+              ? (event.payload.errorMessage ?? thread.session?.lastError ?? "Turn failed")
+              : status === "ready"
+                ? null
+                : (thread.session?.lastError ?? null);
+
+        if (shouldApplyThreadLifecycle) {
+          if (event.type === "turn.started" && acceptedTurnStartedSourcePlan !== null) {
+            yield* markSourceProposedPlanImplemented(
+              acceptedTurnStartedSourcePlan.sourceThreadId,
+              acceptedTurnStartedSourcePlan.sourcePlanId,
+              thread.id,
+              now,
+            ).pipe(
+              Effect.catchCause((cause) =>
+                Effect.logWarning(
+                  "provider runtime ingestion failed to mark source proposed plan",
+                  {
+                    eventId: event.eventId,
+                    eventType: event.type,
+                    cause: Cause.pretty(cause),
+                  },
+                ),
+              ),
+            );
+          }
 
-        yield* orchestrationEngine.dispatch({
-          type: "thread.session.set",
-          commandId: providerCommandId(event, "thread-session-set"),
-          threadId: thread.id,
-          session: {
+          yield* orchestrationEngine.dispatch({
+            type: "thread.session.set",
+            commandId: providerCommandId(event, "thread-session-set"),
             threadId: thread.id,
-            status,
-            providerName: event.provider,
-            runtimeMode: thread.session?.runtimeMode ?? "full-access",
-            activeTurnId: nextActiveTurnId,
-            lastError,
-            updatedAt: now,
-          },
-          createdAt: now,
-        });
+            session: {
+              threadId: thread.id,
+              status,
+              providerName: event.provider,
+              ...(event.providerInstanceId !== undefined
+                ? { providerInstanceId: event.providerInstanceId }
+                : {}),
+              runtimeMode: thread.session?.runtimeMode ?? "full-access",
+              activeTurnId: nextActiveTurnId,
+              lastError,
+              updatedAt: now,
+            },
+            createdAt: now,
+          });
+        }
       }
-    }
 
-    const assistantDelta =
-      event.type === "content.delta" && event.payload.streamKind === "assistant_text"
-        ? event.payload.delta
-        : undefined;
-    const proposedPlanDelta =
-      event.type === "turn.proposed.delta" ? event.payload.delta : undefined;
+      const assistantDelta =
+        event.type === "content.delta" && event.payload.streamKind === "assistant_text"
+          ? event.payload.delta
+          : undefined;
+      const proposedPlanDelta =
+        event.type === "turn.proposed.delta" ? event.payload.delta : undefined;
 
-    if (assistantDelta && assistantDelta.length > 0) {
-      const assistantMessageId = MessageId.make(
-        `assistant:${event.itemId ?? event.turnId ?? event.eventId}`,
-      );
-      const turnId = toTurnId(event.turnId);
-      if (turnId) {
-        yield* rememberAssistantMessageId(thread.id, turnId, assistantMessageId);
-      }
+      if (assistantDelta && assistantDelta.length > 0) {
+        const turnId = toTurnId(event.turnId);
+        const assistantMessageId = yield* getOrCreateAssistantMessageId({
+          threadId: thread.id,
+          event,
+          ...(turnId ? { turnId } : {}),
+        });
+        if (turnId) {
+          yield* rememberAssistantMessageId(thread.id, turnId, assistantMessageId);
+        }
 
-      const assistantDeliveryMode: AssistantDeliveryMode = yield* Effect.map(
-        serverSettingsService.getSettings,
-        (settings) => (settings.enableAssistantStreaming ? "streaming" : "buffered"),
-      );
-      if (assistantDeliveryMode === "buffered") {
-        const spillChunk = yield* appendBufferedAssistantText(assistantMessageId, assistantDelta);
-        if (spillChunk.length > 0) {
+        const assistantDeliveryMode: AssistantDeliveryMode = yield* Effect.map(
+          serverSettingsService.getSettings,
+          (settings) => (settings.enableAssistantStreaming ? "streaming" : "buffered"),
+        );
+        if (assistantDeliveryMode === "buffered") {
+          const spillChunk = yield* appendBufferedAssistantText(assistantMessageId, assistantDelta);
+          if (spillChunk.length > 0) {
+            yield* orchestrationEngine.dispatch({
+              type: "thread.message.assistant.delta",
+              commandId: providerCommandId(event, "assistant-delta-buffer-spill"),
+              threadId: thread.id,
+              messageId: assistantMessageId,
+              delta: spillChunk,
+              ...(turnId ? { turnId } : {}),
+              createdAt: now,
+            });
+          }
+        } else {
           yield* orchestrationEngine.dispatch({
             type: "thread.message.assistant.delta",
-            commandId: providerCommandId(event, "assistant-delta-buffer-spill"),
+            commandId: providerCommandId(event, "assistant-delta"),
             threadId: thread.id,
             messageId: assistantMessageId,
-            delta: spillChunk,
+            delta: assistantDelta,
             ...(turnId ? { turnId } : {}),
             createdAt: now,
           });
         }
-      } else {
-        yield* orchestrationEngine.dispatch({
-          type: "thread.message.assistant.delta",
-          commandId: providerCommandId(event, "assistant-delta"),
+      }
+
+      const pauseForUserTurnId =
+        event.type === "request.opened" || event.type === "user-input.requested"
+          ? toTurnId(event.turnId)
+          : undefined;
+      if (pauseForUserTurnId) {
+        const detailedThread = yield* getLoadedThreadDetail();
+        const assistantDeliveryMode: AssistantDeliveryMode = yield* Effect.map(
+          serverSettingsService.getSettings,
+          (settings) => (settings.enableAssistantStreaming ? "streaming" : "buffered"),
+        );
+        const flushedMessageIds =
+          assistantDeliveryMode === "buffered"
+            ? yield* flushBufferedAssistantMessagesForTurn({
+                event,
+                threadId: thread.id,
+                turnId: pauseForUserTurnId,
+                createdAt: now,
+                commandTag:
+                  event.type === "request.opened"
+                    ? "assistant-delta-flush-on-request-opened"
+                    : "assistant-delta-flush-on-user-input-requested",
+              })
+            : new Set<MessageId>();
+        yield* finalizeActiveAssistantSegmentForTurn({
+          event,
           threadId: thread.id,
-          messageId: assistantMessageId,
-          delta: assistantDelta,
-          ...(turnId ? { turnId } : {}),
+          turnId: pauseForUserTurnId,
           createdAt: now,
+          commandTag:
+            event.type === "request.opened"
+              ? "assistant-complete-on-request-opened"
+              : "assistant-complete-on-user-input-requested",
+          finalDeltaCommandTag:
+            event.type === "request.opened"
+              ? "assistant-delta-finalize-on-request-opened"
+              : "assistant-delta-finalize-on-user-input-requested",
+          hasProjectedMessage:
+            detailedThread !== null &&
+            hasAssistantMessageForTurn(detailedThread.messages, pauseForUserTurnId, {
+              streamingOnly: true,
+            }),
+          flushedMessageIds,
         });
       }
-    }
 
-    if (proposedPlanDelta && proposedPlanDelta.length > 0) {
-      const planId = proposedPlanIdFromEvent(event, thread.id);
-      yield* appendBufferedProposedPlan(planId, proposedPlanDelta, now);
-    }
+      if (proposedPlanDelta && proposedPlanDelta.length > 0) {
+        const planId = proposedPlanIdFromEvent(event, thread.id);
+        yield* appendBufferedProposedPlan(planId, proposedPlanDelta, now);
+      }
 
-    const assistantCompletion =
-      event.type === "item.completed" && event.payload.itemType === "assistant_message"
-        ? {
-            messageId: MessageId.make(`assistant:${event.itemId ?? event.turnId ?? event.eventId}`),
-            fallbackText: event.payload.detail,
-          }
-        : undefined;
-    const proposedPlanCompletion =
-      event.type === "turn.proposed.completed"
-        ? {
-            planId: proposedPlanIdFromEvent(event, thread.id),
-            turnId: toTurnId(event.turnId),
-            planMarkdown: event.payload.planMarkdown,
+      const assistantCompletion =
+        event.type === "item.completed" && event.payload.itemType === "assistant_message"
+          ? {
+              messageId: MessageId.make(
+                `assistant:${event.itemId ?? event.turnId ?? event.eventId}`,
+              ),
+              fallbackText: event.payload.detail,
+            }
+          : undefined;
+      const proposedPlanCompletion =
+        event.type === "turn.proposed.completed"
+          ? {
+              planId: proposedPlanIdFromEvent(event, thread.id),
+              turnId: toTurnId(event.turnId),
+              planMarkdown: event.payload.planMarkdown,
+            }
+          : undefined;
+
+      if (assistantCompletion) {
+        const detailedThread = yield* getLoadedThreadDetail();
+        const messages = detailedThread?.messages ?? [];
+        const turnId = toTurnId(event.turnId);
+        const activeAssistantMessageId = turnId
+          ? yield* getActiveAssistantMessageIdForTurn(thread.id, turnId)
+          : Option.none<MessageId>();
+        const hasAssistantMessagesForTurn =
+          turnId !== undefined ? hasAssistantMessageForTurn(messages, turnId) : false;
+        const assistantMessageId = Option.getOrElse(
+          activeAssistantMessageId,
+          () => assistantCompletion.messageId,
+        );
+        const existingAssistantMessage = findMessageById(messages, assistantMessageId);
+        const shouldApplyFallbackCompletionText =
+          !existingAssistantMessage || existingAssistantMessage.text.length === 0;
+
+        const shouldSkipRedundantCompletion =
+          Option.isNone(activeAssistantMessageId) &&
+          turnId !== undefined &&
+          hasAssistantMessagesForTurn &&
+          (assistantCompletion.fallbackText?.trim().length ?? 0) === 0;
+
+        if (!shouldSkipRedundantCompletion) {
+          if (turnId && Option.isNone(activeAssistantMessageId)) {
+            yield* rememberAssistantMessageId(thread.id, turnId, assistantMessageId);
           }
-        : undefined;
 
-    if (assistantCompletion) {
-      const assistantMessageId = assistantCompletion.messageId;
-      const turnId = toTurnId(event.turnId);
-      const existingAssistantMessage = thread.messages.find(
-        (entry) => entry.id === assistantMessageId,
-      );
-      const shouldApplyFallbackCompletionText =
-        !existingAssistantMessage || existingAssistantMessage.text.length === 0;
-      if (turnId) {
-        yield* rememberAssistantMessageId(thread.id, turnId, assistantMessageId);
-      }
+          yield* finalizeAssistantMessage({
+            event,
+            threadId: thread.id,
+            messageId: assistantMessageId,
+            ...(turnId ? { turnId } : {}),
+            createdAt: now,
+            commandTag: "assistant-complete",
+            finalDeltaCommandTag: "assistant-delta-finalize",
+            hasProjectedMessage: existingAssistantMessage !== undefined,
+            ...(assistantCompletion.fallbackText !== undefined && shouldApplyFallbackCompletionText
+              ? { fallbackText: assistantCompletion.fallbackText }
+              : {}),
+          });
 
-      yield* finalizeAssistantMessage({
-        event,
-        threadId: thread.id,
-        messageId: assistantMessageId,
-        ...(turnId ? { turnId } : {}),
-        createdAt: now,
-        commandTag: "assistant-complete",
-        finalDeltaCommandTag: "assistant-delta-finalize",
-        ...(assistantCompletion.fallbackText !== undefined && shouldApplyFallbackCompletionText
-          ? { fallbackText: assistantCompletion.fallbackText }
-          : {}),
-      });
+          if (turnId) {
+            yield* forgetAssistantMessageId(thread.id, turnId, assistantMessageId);
+          }
+        }
 
-      if (turnId) {
-        yield* forgetAssistantMessageId(thread.id, turnId, assistantMessageId);
+        if (turnId) {
+          yield* clearAssistantSegmentStateForTurn(thread.id, turnId);
+        }
       }
-    }
-
-    if (proposedPlanCompletion) {
-      yield* finalizeBufferedProposedPlan({
-        event,
-        threadId: thread.id,
-        threadProposedPlans: thread.proposedPlans,
-        planId: proposedPlanCompletion.planId,
-        ...(proposedPlanCompletion.turnId ? { turnId: proposedPlanCompletion.turnId } : {}),
-        fallbackMarkdown: proposedPlanCompletion.planMarkdown,
-        updatedAt: now,
-      });
-    }
-
-    if (event.type === "turn.completed") {
-      const turnId = toTurnId(event.turnId);
-      if (turnId) {
-        const assistantMessageIds = yield* getAssistantMessageIdsForTurn(thread.id, turnId);
-        yield* Effect.forEach(
-          assistantMessageIds,
-          (assistantMessageId) =>
-            finalizeAssistantMessage({
-              event,
-              threadId: thread.id,
-              messageId: assistantMessageId,
-              turnId,
-              createdAt: now,
-              commandTag: "assistant-complete-finalize",
-              finalDeltaCommandTag: "assistant-delta-finalize-fallback",
-            }),
-          { concurrency: 1 },
-        ).pipe(Effect.asVoid);
-        yield* clearAssistantMessageIdsForTurn(thread.id, turnId);
 
+      if (proposedPlanCompletion) {
+        const detailedThread = yield* getLoadedThreadDetail();
         yield* finalizeBufferedProposedPlan({
           event,
           threadId: thread.id,
-          threadProposedPlans: thread.proposedPlans,
-          planId: proposedPlanIdForTurn(thread.id, turnId),
-          turnId,
+          threadProposedPlans: detailedThread?.proposedPlans ?? [],
+          planId: proposedPlanCompletion.planId,
+          ...(proposedPlanCompletion.turnId ? { turnId: proposedPlanCompletion.turnId } : {}),
+          fallbackMarkdown: proposedPlanCompletion.planMarkdown,
           updatedAt: now,
         });
       }
-    }
 
-    if (event.type === "session.exited") {
-      yield* clearTurnStateForSession(thread.id);
-    }
-
-    if (event.type === "runtime.error") {
-      const runtimeErrorMessage = event.payload.message;
-
-      const shouldApplyRuntimeError = !STRICT_PROVIDER_LIFECYCLE_GUARD
-        ? true
-        : activeTurnId === null || eventTurnId === undefined || sameId(activeTurnId, eventTurnId);
+      if (event.type === "turn.completed") {
+        const detailedThread = yield* getLoadedThreadDetail();
+        const messages = detailedThread?.messages ?? [];
+        const proposedPlans = detailedThread?.proposedPlans ?? [];
+        const turnId = toTurnId(event.turnId);
+        if (turnId) {
+          const assistantMessageIds = yield* getAssistantMessageIdsForTurn(thread.id, turnId);
+          yield* Effect.forEach(
+            assistantMessageIds,
+            (assistantMessageId) =>
+              finalizeAssistantMessage({
+                event,
+                threadId: thread.id,
+                messageId: assistantMessageId,
+                turnId,
+                createdAt: now,
+                commandTag: "assistant-complete-finalize",
+                finalDeltaCommandTag: "assistant-delta-finalize-fallback",
+                hasProjectedMessage: findMessageById(messages, assistantMessageId) !== undefined,
+              }),
+            { concurrency: 1 },
+          ).pipe(Effect.asVoid);
+          yield* clearAssistantMessageIdsForTurn(thread.id, turnId);
+          yield* clearAssistantSegmentStateForTurn(thread.id, turnId);
 
-      if (shouldApplyRuntimeError) {
-        yield* orchestrationEngine.dispatch({
-          type: "thread.session.set",
-          commandId: providerCommandId(event, "runtime-error-session-set"),
-          threadId: thread.id,
-          session: {
+          yield* finalizeBufferedProposedPlan({
+            event,
             threadId: thread.id,
-            status: "error",
-            providerName: event.provider,
-            runtimeMode: thread.session?.runtimeMode ?? "full-access",
-            activeTurnId: eventTurnId ?? null,
-            lastError: runtimeErrorMessage,
+            threadProposedPlans: proposedPlans,
+            planId: proposedPlanIdForTurn(thread.id, turnId),
+            turnId,
             updatedAt: now,
-          },
-          createdAt: now,
-        });
+          });
+        }
       }
-    }
 
-    if (event.type === "thread.metadata.updated" && event.payload.name) {
-      yield* orchestrationEngine.dispatch({
-        type: "thread.meta.update",
-        commandId: providerCommandId(event, "thread-meta-update"),
-        threadId: thread.id,
-        title: event.payload.name,
-      });
-    }
+      if (event.type === "session.exited") {
+        yield* clearTurnStateForSession(thread.id);
+      }
 
-    if (event.type === "turn.diff.updated") {
-      const turnId = toTurnId(event.turnId);
-      if (turnId && (yield* isGitRepoForThread(thread.id))) {
-        // Skip if a checkpoint already exists for this turn. A real
-        // (non-placeholder) capture from CheckpointReactor should not
-        // be clobbered, and dispatching a duplicate placeholder for the
-        // same turnId would produce an unstable checkpointTurnCount.
-        if (thread.checkpoints.some((c) => c.turnId === turnId)) {
-          // Already tracked; no-op.
-        } else {
-          const assistantMessageId = MessageId.make(
-            `assistant:${event.itemId ?? event.turnId ?? event.eventId}`,
-          );
-          const maxTurnCount = thread.checkpoints.reduce(
-            (max, c) => Math.max(max, c.checkpointTurnCount),
-            0,
-          );
+      if (event.type === "runtime.error") {
+        const runtimeErrorMessage = event.payload.message;
+
+        const shouldApplyRuntimeError = !STRICT_PROVIDER_LIFECYCLE_GUARD
+          ? true
+          : activeTurnId === null || eventTurnId === undefined || sameId(activeTurnId, eventTurnId);
+
+        if (shouldApplyRuntimeError) {
           yield* orchestrationEngine.dispatch({
-            type: "thread.turn.diff.complete",
-            commandId: providerCommandId(event, "thread-turn-diff-complete"),
+            type: "thread.session.set",
+            commandId: providerCommandId(event, "runtime-error-session-set"),
             threadId: thread.id,
-            turnId,
-            completedAt: now,
-            checkpointRef: CheckpointRef.make(`provider-diff:${event.eventId}`),
-            status: "missing",
-            files: [],
-            assistantMessageId,
-            checkpointTurnCount: maxTurnCount + 1,
+            session: {
+              threadId: thread.id,
+              status: "error",
+              providerName: event.provider,
+              ...(event.providerInstanceId !== undefined
+                ? { providerInstanceId: event.providerInstanceId }
+                : {}),
+              runtimeMode: thread.session?.runtimeMode ?? "full-access",
+              activeTurnId: eventTurnId ?? null,
+              lastError: runtimeErrorMessage,
+              updatedAt: now,
+            },
             createdAt: now,
           });
         }
       }
-    }
 
-    const activities = runtimeEventToActivities(event);
-    yield* Effect.forEach(activities, (activity) =>
-      orchestrationEngine.dispatch({
-        type: "thread.activity.append",
-        commandId: providerCommandId(event, "thread-activity-append"),
-        threadId: thread.id,
-        activity,
-        createdAt: activity.createdAt,
-      }),
-    ).pipe(Effect.asVoid);
-  });
+      if (event.type === "thread.metadata.updated" && event.payload.name) {
+        yield* orchestrationEngine.dispatch({
+          type: "thread.meta.update",
+          commandId: providerCommandId(event, "thread-meta-update"),
+          threadId: thread.id,
+          title: event.payload.name,
+        });
+      }
+
+      if (event.type === "turn.diff.updated") {
+        const turnId = toTurnId(event.turnId);
+        const checkpointContext = turnId
+          ? yield* projectionSnapshotQuery
+              .getThreadCheckpointContext(thread.id)
+              .pipe(Effect.map(Option.getOrUndefined))
+          : undefined;
+        const workspaceCwd =
+          checkpointContext?.worktreePath ?? checkpointContext?.workspaceRoot ?? undefined;
+        if (turnId && checkpointContext && workspaceCwd && isGitRepository(workspaceCwd)) {
+          // Skip if a checkpoint already exists for this turn. A real
+          // (non-placeholder) capture from CheckpointReactor should not
+          // be clobbered, and dispatching a duplicate placeholder for the
+          // same turnId would produce an unstable checkpointTurnCount.
+          if (hasCheckpointForTurn(checkpointContext.checkpoints, turnId)) {
+            // Already tracked; no-op.
+          } else {
+            const assistantMessageId = MessageId.make(
+              `assistant:${event.itemId ?? event.turnId ?? event.eventId}`,
+            );
+            yield* orchestrationEngine.dispatch({
+              type: "thread.turn.diff.complete",
+              commandId: providerCommandId(event, "thread-turn-diff-complete"),
+              threadId: thread.id,
+              turnId,
+              completedAt: now,
+              checkpointRef: CheckpointRef.make(`provider-diff:${event.eventId}`),
+              status: "missing",
+              files: [],
+              assistantMessageId,
+              checkpointTurnCount: maxCheckpointTurnCount(checkpointContext.checkpoints) + 1,
+              createdAt: now,
+            });
+          }
+        }
+      }
+
+      const activities = runtimeEventToActivities(event);
+      yield* Effect.forEach(activities, (activity) =>
+        orchestrationEngine.dispatch({
+          type: "thread.activity.append",
+          commandId: providerCommandId(event, "thread-activity-append"),
+          threadId: thread.id,
+          activity,
+          createdAt: activity.createdAt,
+        }),
+      ).pipe(Effect.asVoid);
+    });
 
   const processDomainEvent = (_event: TurnStartRequestedDomainEvent) => Effect.void;
 
@@ -1242,21 +1645,22 @@ const make = Effect.fn("make")(function* () {
 
   const worker = yield* makeDrainableWorker(processInputSafely);
 
-  const start: ProviderRuntimeIngestionShape["start"] = Effect.fn("start")(function* () {
-    yield* Effect.forkScoped(
-      Stream.runForEach(providerService.streamEvents, (event) =>
-        worker.enqueue({ source: "runtime", event }),
-      ),
-    );
-    yield* Effect.forkScoped(
-      Stream.runForEach(orchestrationEngine.streamDomainEvents, (event) => {
-        if (event.type !== "thread.turn-start-requested") {
-          return Effect.void;
-        }
-        return worker.enqueue({ source: "domain", event });
-      }),
-    );
-  });
+  const start: ProviderRuntimeIngestionShape["start"] = () =>
+    Effect.gen(function* () {
+      yield* Effect.forkScoped(
+        Stream.runForEach(providerService.streamEvents, (event) =>
+          worker.enqueue({ source: "runtime", event }),
+        ),
+      );
+      yield* Effect.forkScoped(
+        Stream.runForEach(orchestrationEngine.streamDomainEvents, (event) => {
+          if (event.type !== "thread.turn-start-requested") {
+            return Effect.void;
+          }
+          return worker.enqueue({ source: "domain", event });
+        }),
+      );
+    });
 
   return {
     start,
@@ -1266,5 +1670,5 @@ const make = Effect.fn("make")(function* () {
 
 export const ProviderRuntimeIngestionLive = Layer.effect(
   ProviderRuntimeIngestionService,
-  make(),
+  make,
 ).pipe(Layer.provide(ProjectionTurnRepositoryLive));
diff --git a/apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts b/apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
index 5c3148c9434..586281dc9c6 100644
--- a/apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
+++ b/apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
@@ -8,7 +8,10 @@
  *
  * @module RuntimeReceiptBus
  */
-import { Effect, Layer, PubSub, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Stream from "effect/Stream";
 
 import {
   RuntimeReceiptBus,
diff --git a/apps/server/src/orchestration/Layers/ThreadDeletionReactor.test.ts b/apps/server/src/orchestration/Layers/ThreadDeletionReactor.test.ts
new file mode 100644
index 00000000000..701835da16c
--- /dev/null
+++ b/apps/server/src/orchestration/Layers/ThreadDeletionReactor.test.ts
@@ -0,0 +1,38 @@
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { describe, expect, it } from "vitest";
+
+import { logCleanupCauseUnlessInterrupted } from "./ThreadDeletionReactor.ts";
+
+describe("logCleanupCauseUnlessInterrupted", () => {
+  const threadId = ThreadId.make("thread-deletion-reactor-test");
+
+  it("swallows ordinary cleanup failures", async () => {
+    const exit = await Effect.runPromiseExit(
+      logCleanupCauseUnlessInterrupted({
+        effect: Effect.fail("cleanup failed"),
+        message: "thread deletion cleanup skipped provider session stop",
+        threadId,
+      }),
+    );
+
+    expect(Exit.isSuccess(exit)).toBe(true);
+  });
+
+  it("preserves interrupt causes", async () => {
+    const exit = await Effect.runPromiseExit(
+      logCleanupCauseUnlessInterrupted({
+        effect: Effect.interrupt,
+        message: "thread deletion cleanup skipped provider session stop",
+        threadId,
+      }),
+    );
+
+    expect(Exit.isFailure(exit)).toBe(true);
+    if (Exit.isFailure(exit)) {
+      expect(Cause.hasInterruptsOnly(exit.cause)).toBe(true);
+    }
+  });
+});
diff --git a/apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts b/apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts
new file mode 100644
index 00000000000..4bbf5ca2149
--- /dev/null
+++ b/apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts
@@ -0,0 +1,99 @@
+import type { OrchestrationEvent } from "@t3tools/contracts";
+import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+
+import { ProviderService } from "../../provider/Services/ProviderService.ts";
+import { TerminalManager } from "../../terminal/Services/Manager.ts";
+import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
+import {
+  ThreadDeletionReactor,
+  type ThreadDeletionReactorShape,
+} from "../Services/ThreadDeletionReactor.ts";
+
+type ThreadDeletedEvent = Extract<OrchestrationEvent, { type: "thread.deleted" }>;
+
+export const logCleanupCauseUnlessInterrupted = <R, E>({
+  effect,
+  message,
+  threadId,
+}: {
+  readonly effect: Effect.Effect<void, E, R>;
+  readonly message: string;
+  readonly threadId: ThreadDeletedEvent["payload"]["threadId"];
+}): Effect.Effect<void, E, R> =>
+  effect.pipe(
+    Effect.catchCause((cause) => {
+      if (Cause.hasInterruptsOnly(cause)) {
+        return Effect.failCause(cause);
+      }
+      return Effect.logDebug(message, {
+        threadId,
+        cause: Cause.pretty(cause),
+      });
+    }),
+  );
+
+const make = Effect.gen(function* () {
+  const orchestrationEngine = yield* OrchestrationEngineService;
+  const providerService = yield* ProviderService;
+  const terminalManager = yield* TerminalManager;
+
+  const stopProviderSession = (threadId: ThreadDeletedEvent["payload"]["threadId"]) =>
+    logCleanupCauseUnlessInterrupted({
+      effect: providerService.stopSession({ threadId }),
+      message: "thread deletion cleanup skipped provider session stop",
+      threadId,
+    });
+
+  const closeThreadTerminals = (threadId: ThreadDeletedEvent["payload"]["threadId"]) =>
+    logCleanupCauseUnlessInterrupted({
+      effect: terminalManager.close({ threadId, deleteHistory: true }),
+      message: "thread deletion cleanup skipped terminal close",
+      threadId,
+    });
+
+  const processThreadDeleted = Effect.fn("processThreadDeleted")(function* (
+    event: ThreadDeletedEvent,
+  ) {
+    const { threadId } = event.payload;
+    yield* stopProviderSession(threadId);
+    yield* closeThreadTerminals(threadId);
+  });
+
+  const processThreadDeletedSafely = (event: ThreadDeletedEvent) =>
+    processThreadDeleted(event).pipe(
+      Effect.catchCause((cause) => {
+        if (Cause.hasInterruptsOnly(cause)) {
+          return Effect.failCause(cause);
+        }
+        return Effect.logWarning("thread deletion reactor failed to process event", {
+          eventType: event.type,
+          threadId: event.payload.threadId,
+          cause: Cause.pretty(cause),
+        });
+      }),
+    );
+
+  const worker = yield* makeDrainableWorker(processThreadDeletedSafely);
+
+  const start: ThreadDeletionReactorShape["start"] = Effect.fn("start")(function* () {
+    yield* Effect.forkScoped(
+      Stream.runForEach(orchestrationEngine.streamDomainEvents, (event) => {
+        if (event.type !== "thread.deleted") {
+          return Effect.void;
+        }
+        return worker.enqueue(event);
+      }),
+    );
+  });
+
+  return {
+    start,
+    drain: worker.drain,
+  } satisfies ThreadDeletionReactorShape;
+});
+
+export const ThreadDeletionReactorLive = Layer.effect(ThreadDeletionReactor, make);
diff --git a/apps/server/src/orchestration/Normalizer.ts b/apps/server/src/orchestration/Normalizer.ts
index 69863b7f0ad..95d29e3d6d2 100644
--- a/apps/server/src/orchestration/Normalizer.ts
+++ b/apps/server/src/orchestration/Normalizer.ts
@@ -1,4 +1,6 @@
-import { Effect, FileSystem, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import {
   type ClientOrchestrationCommand,
   type OrchestrationCommand,
@@ -6,10 +8,10 @@ import {
   PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
 } from "@t3tools/contracts";
 
-import { createAttachmentId, resolveAttachmentPath } from "../attachmentStore";
-import { ServerConfig } from "../config";
-import { parseBase64DataUrl } from "../imageMime";
-import { WorkspacePaths } from "../workspace/Services/WorkspacePaths";
+import { createAttachmentId, resolveAttachmentPath } from "../attachmentStore.ts";
+import { ServerConfig } from "../config.ts";
+import { parseBase64DataUrl } from "../imageMime.ts";
+import { WorkspacePaths } from "../workspace/Services/WorkspacePaths.ts";
 
 export const normalizeDispatchCommand = (command: ClientOrchestrationCommand) =>
   Effect.gen(function* () {
@@ -28,10 +30,31 @@ export const normalizeDispatchCommand = (command: ClientOrchestrationCommand) =>
         ),
       );
 
+    const normalizeProjectWorkspaceRootForCreate = (
+      workspaceRoot: string,
+      createIfMissing: boolean | undefined,
+    ) =>
+      workspacePaths
+        .normalizeWorkspaceRoot(workspaceRoot, {
+          createIfMissing: createIfMissing === true,
+        })
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new OrchestrationDispatchCommandError({
+                message: cause.message,
+              }),
+          ),
+        );
+
     if (command.type === "project.create") {
       return {
         ...command,
-        workspaceRoot: yield* normalizeProjectWorkspaceRoot(command.workspaceRoot),
+        workspaceRoot: yield* normalizeProjectWorkspaceRootForCreate(
+          command.workspaceRoot,
+          command.createWorkspaceRootIfMissing,
+        ),
+        createWorkspaceRootIfMissing: command.createWorkspaceRootIfMissing === true,
       } satisfies OrchestrationCommand;
     }
 
diff --git a/apps/server/src/orchestration/Services/CheckpointReactor.ts b/apps/server/src/orchestration/Services/CheckpointReactor.ts
index 9e9c83beb47..bd3ee3e88f9 100644
--- a/apps/server/src/orchestration/Services/CheckpointReactor.ts
+++ b/apps/server/src/orchestration/Services/CheckpointReactor.ts
@@ -6,8 +6,9 @@
  *
  * @module CheckpointReactor
  */
-import { Context } from "effect";
-import type { Effect, Scope } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
 
 /**
  * CheckpointReactorShape - Service API for checkpoint reactor lifecycle.
diff --git a/apps/server/src/orchestration/Services/OrchestrationEngine.ts b/apps/server/src/orchestration/Services/OrchestrationEngine.ts
index 376b87d30a0..acb2b7b042d 100644
--- a/apps/server/src/orchestration/Services/OrchestrationEngine.ts
+++ b/apps/server/src/orchestration/Services/OrchestrationEngine.ts
@@ -10,13 +10,10 @@
  *
  * @module OrchestrationEngineService
  */
-import type {
-  OrchestrationCommand,
-  OrchestrationEvent,
-  OrchestrationReadModel,
-} from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect, Stream } from "effect";
+import type { OrchestrationCommand, OrchestrationEvent } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
 import type { OrchestrationDispatchError } from "../Errors.ts";
 import type { OrchestrationEventStoreError } from "../../persistence/Errors.ts";
@@ -25,13 +22,6 @@ import type { OrchestrationEventStoreError } from "../../persistence/Errors.ts";
  * OrchestrationEngineShape - Service API for orchestration command and event flow.
  */
 export interface OrchestrationEngineShape {
-  /**
-   * Read the current in-memory orchestration read model.
-   *
-   * @returns Effect containing the latest read model.
-   */
-  readonly getReadModel: () => Effect.Effect<OrchestrationReadModel, never, never>;
-
   /**
    * Replay persisted orchestration events from an exclusive sequence cursor.
    *
@@ -70,7 +60,7 @@ export interface OrchestrationEngineShape {
  * ```ts
  * const program = Effect.gen(function* () {
  *   const engine = yield* OrchestrationEngineService
- *   return yield* engine.getReadModel()
+ *   return yield* engine.dispatch(command)
  * })
  * ```
  */
diff --git a/apps/server/src/orchestration/Services/OrchestrationReactor.ts b/apps/server/src/orchestration/Services/OrchestrationReactor.ts
index a3edeaac61d..eb2d95954bb 100644
--- a/apps/server/src/orchestration/Services/OrchestrationReactor.ts
+++ b/apps/server/src/orchestration/Services/OrchestrationReactor.ts
@@ -6,8 +6,9 @@
  *
  * @module OrchestrationReactor
  */
-import { Context } from "effect";
-import type { Effect, Scope } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
 
 /**
  * OrchestrationReactorShape - Service API for orchestration reactor lifecycle.
diff --git a/apps/server/src/orchestration/Services/ProjectionPipeline.ts b/apps/server/src/orchestration/Services/ProjectionPipeline.ts
index 349f3430ad6..bb4736ca57a 100644
--- a/apps/server/src/orchestration/Services/ProjectionPipeline.ts
+++ b/apps/server/src/orchestration/Services/ProjectionPipeline.ts
@@ -7,8 +7,8 @@
  * @module OrchestrationProjectionPipeline
  */
 import type { OrchestrationEvent } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../../persistence/Errors.ts";
 
diff --git a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
index 36bbf5028b4..7d85f0240f7 100644
--- a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
@@ -7,15 +7,20 @@
  * @module ProjectionSnapshotQuery
  */
 import type {
+  CheckpointRef,
   OrchestrationCheckpointSummary,
   OrchestrationProject,
+  OrchestrationProjectShell,
   OrchestrationReadModel,
+  OrchestrationShellSnapshot,
+  OrchestrationThread,
+  OrchestrationThreadShell,
   ProjectId,
   ThreadId,
 } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Option } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Option from "effect/Option";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../../persistence/Errors.ts";
 
@@ -24,6 +29,10 @@ export interface ProjectionSnapshotCounts {
   readonly threadCount: number;
 }
 
+export interface ProjectionSnapshotSequence {
+  readonly snapshotSequence: number;
+}
+
 export interface ProjectionThreadCheckpointContext {
   readonly threadId: ThreadId;
   readonly projectId: ProjectId;
@@ -32,10 +41,28 @@ export interface ProjectionThreadCheckpointContext {
   readonly checkpoints: ReadonlyArray<OrchestrationCheckpointSummary>;
 }
 
+export interface ProjectionFullThreadDiffContext {
+  readonly threadId: ThreadId;
+  readonly projectId: ProjectId;
+  readonly workspaceRoot: string;
+  readonly worktreePath: string | null;
+  readonly latestCheckpointTurnCount: number;
+  readonly toCheckpointRef: CheckpointRef | null;
+}
+
 /**
  * ProjectionSnapshotQueryShape - Service API for read-model snapshots.
  */
 export interface ProjectionSnapshotQueryShape {
+  /**
+   * Read the lightweight command snapshot used to bootstrap the in-memory
+   * orchestration engine without hydrating message/activity/checkpoint bodies.
+   */
+  readonly getCommandReadModel: () => Effect.Effect<
+    OrchestrationReadModel,
+    ProjectionRepositoryError
+  >;
+
   /**
    * Read the latest orchestration projection snapshot.
    *
@@ -44,6 +71,37 @@ export interface ProjectionSnapshotQueryShape {
    */
   readonly getSnapshot: () => Effect.Effect<OrchestrationReadModel, ProjectionRepositoryError>;
 
+  /**
+   * Read the latest orchestration shell snapshot.
+   *
+   * Returns only projects and thread shell summaries so clients can bootstrap
+   * lightweight navigation state without hydrating every thread body.
+   */
+  readonly getShellSnapshot: () => Effect.Effect<
+    OrchestrationShellSnapshot,
+    ProjectionRepositoryError
+  >;
+
+  /**
+   * Read archived thread shell summaries for the archive page.
+   *
+   * This query is separate from the main shell snapshot so archived threads
+   * are never bootstrapped into normal navigation state.
+   */
+  readonly getArchivedShellSnapshot: () => Effect.Effect<
+    OrchestrationShellSnapshot,
+    ProjectionRepositoryError
+  >;
+
+  /**
+   * Read the latest projection snapshot sequence without hydrating read-model
+   * entities.
+   */
+  readonly getSnapshotSequence: () => Effect.Effect<
+    ProjectionSnapshotSequence,
+    ProjectionRepositoryError
+  >;
+
   /**
    * Read aggregate projection counts without hydrating the full read model.
    */
@@ -56,6 +114,13 @@ export interface ProjectionSnapshotQueryShape {
     workspaceRoot: string,
   ) => Effect.Effect<Option.Option<OrchestrationProject>, ProjectionRepositoryError>;
 
+  /**
+   * Read a single active project shell row by id.
+   */
+  readonly getProjectShellById: (
+    projectId: ProjectId,
+  ) => Effect.Effect<Option.Option<OrchestrationProjectShell>, ProjectionRepositoryError>;
+
   /**
    * Read the earliest active thread for a project.
    */
@@ -69,6 +134,29 @@ export interface ProjectionSnapshotQueryShape {
   readonly getThreadCheckpointContext: (
     threadId: ThreadId,
   ) => Effect.Effect<Option.Option<ProjectionThreadCheckpointContext>, ProjectionRepositoryError>;
+
+  /**
+   * Read only the narrow context needed to compute a full-thread diff from
+   * checkpoint 0 to a specific turn count.
+   */
+  readonly getFullThreadDiffContext: (
+    threadId: ThreadId,
+    toTurnCount: number,
+  ) => Effect.Effect<Option.Option<ProjectionFullThreadDiffContext>, ProjectionRepositoryError>;
+
+  /**
+   * Read a single active thread shell row by id.
+   */
+  readonly getThreadShellById: (
+    threadId: ThreadId,
+  ) => Effect.Effect<Option.Option<OrchestrationThreadShell>, ProjectionRepositoryError>;
+
+  /**
+   * Read a single active thread detail snapshot by id.
+   */
+  readonly getThreadDetailById: (
+    threadId: ThreadId,
+  ) => Effect.Effect<Option.Option<OrchestrationThread>, ProjectionRepositoryError>;
 }
 
 /**
diff --git a/apps/server/src/orchestration/Services/ProviderCommandReactor.ts b/apps/server/src/orchestration/Services/ProviderCommandReactor.ts
index c8b8580682a..65aa9949fe1 100644
--- a/apps/server/src/orchestration/Services/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Services/ProviderCommandReactor.ts
@@ -6,8 +6,9 @@
  *
  * @module ProviderCommandReactor
  */
-import { Context } from "effect";
-import type { Effect, Scope } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
 
 /**
  * ProviderCommandReactorShape - Service API for provider command reactors.
diff --git a/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts
index 831ce3a6f0c..b6fa2711b94 100644
--- a/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts
+++ b/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts
@@ -6,8 +6,9 @@
  *
  * @module ProviderRuntimeIngestionService
  */
-import { Context } from "effect";
-import type { Effect, Scope } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
 
 /**
  * ProviderRuntimeIngestionShape - Service API for runtime ingestion lifecycle.
diff --git a/apps/server/src/orchestration/Services/RuntimeReceiptBus.ts b/apps/server/src/orchestration/Services/RuntimeReceiptBus.ts
index 53038006dea..0b880ee6999 100644
--- a/apps/server/src/orchestration/Services/RuntimeReceiptBus.ts
+++ b/apps/server/src/orchestration/Services/RuntimeReceiptBus.ts
@@ -15,8 +15,10 @@
  * @module RuntimeReceiptBus
  */
 import { CheckpointRef, IsoDateTime, NonNegativeInt, ThreadId, TurnId } from "@t3tools/contracts";
-import { Schema, Context } from "effect";
-import type { Effect, Stream } from "effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
 export const CheckpointBaselineCapturedReceipt = Schema.Struct({
   type: Schema.Literal("checkpoint.baseline.captured"),
diff --git a/apps/server/src/orchestration/Services/ThreadDeletionReactor.ts b/apps/server/src/orchestration/Services/ThreadDeletionReactor.ts
new file mode 100644
index 00000000000..7c6718965a6
--- /dev/null
+++ b/apps/server/src/orchestration/Services/ThreadDeletionReactor.ts
@@ -0,0 +1,38 @@
+/**
+ * ThreadDeletionReactor - Thread deletion cleanup reactor service interface.
+ *
+ * Owns background workers that react to thread deletion domain events and
+ * perform best-effort runtime cleanup for provider sessions and terminals.
+ *
+ * @module ThreadDeletionReactor
+ */
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+
+/**
+ * ThreadDeletionReactorShape - Service API for thread deletion cleanup.
+ */
+export interface ThreadDeletionReactorShape {
+  /**
+   * Start reacting to thread.deleted orchestration domain events.
+   *
+   * The returned effect must be run in a scope so all worker fibers can be
+   * finalized on shutdown.
+   */
+  readonly start: () => Effect.Effect<void, never, Scope.Scope>;
+
+  /**
+   * Resolves when the internal processing queue is empty and idle.
+   * Intended for test use to replace timing-sensitive sleeps.
+   */
+  readonly drain: Effect.Effect<void>;
+}
+
+/**
+ * ThreadDeletionReactor - Service tag for thread deletion cleanup workers.
+ */
+export class ThreadDeletionReactor extends Context.Service<
+  ThreadDeletionReactor,
+  ThreadDeletionReactorShape
+>()("t3/orchestration/Services/ThreadDeletionReactor") {}
diff --git a/apps/server/src/orchestration/commandInvariants.test.ts b/apps/server/src/orchestration/commandInvariants.test.ts
index a678bcea166..d52f0535fbb 100644
--- a/apps/server/src/orchestration/commandInvariants.test.ts
+++ b/apps/server/src/orchestration/commandInvariants.test.ts
@@ -7,8 +7,9 @@ import {
   ThreadId,
   type OrchestrationCommand,
   type OrchestrationReadModel,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 
 import {
   findThreadById,
@@ -18,7 +19,7 @@ import {
   requireThreadAbsent,
 } from "./commandInvariants.ts";
 
-const now = new Date().toISOString();
+const now = "2026-01-01T00:00:00.000Z";
 
 const readModel: OrchestrationReadModel = {
   snapshotSequence: 2,
@@ -29,7 +30,7 @@ const readModel: OrchestrationReadModel = {
       title: "Project A",
       workspaceRoot: "/tmp/project-a",
       defaultModelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
       scripts: [],
@@ -42,7 +43,7 @@ const readModel: OrchestrationReadModel = {
       title: "Project B",
       workspaceRoot: "/tmp/project-b",
       defaultModelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
       scripts: [],
@@ -57,7 +58,7 @@ const readModel: OrchestrationReadModel = {
       projectId: ProjectId.make("project-a"),
       title: "Thread A",
       modelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
       interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -80,7 +81,7 @@ const readModel: OrchestrationReadModel = {
       projectId: ProjectId.make("project-b"),
       title: "Thread B",
       modelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
       interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -157,7 +158,7 @@ describe("commandInvariants", () => {
           projectId: ProjectId.make("project-a"),
           title: "new",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -181,7 +182,7 @@ describe("commandInvariants", () => {
             projectId: ProjectId.make("project-a"),
             title: "dup",
             modelSelection: {
-              provider: "codex",
+              instanceId: ProviderInstanceId.make("codex"),
               model: "gpt-5-codex",
             },
             interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
diff --git a/apps/server/src/orchestration/commandInvariants.ts b/apps/server/src/orchestration/commandInvariants.ts
index 009fdb190e5..f5ab794bce7 100644
--- a/apps/server/src/orchestration/commandInvariants.ts
+++ b/apps/server/src/orchestration/commandInvariants.ts
@@ -6,7 +6,7 @@ import type {
   ProjectId,
   ThreadId,
 } from "@t3tools/contracts";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 
 import { OrchestrationCommandInvariantError } from "./Errors.ts";
 
diff --git a/apps/server/src/orchestration/decider.delete.test.ts b/apps/server/src/orchestration/decider.delete.test.ts
new file mode 100644
index 00000000000..dcdaaecc1fb
--- /dev/null
+++ b/apps/server/src/orchestration/decider.delete.test.ts
@@ -0,0 +1,227 @@
+import {
+  CommandId,
+  DEFAULT_PROVIDER_INTERACTION_MODE,
+  EventId,
+  ProjectId,
+  ThreadId,
+  type OrchestrationCommand,
+  type OrchestrationEvent,
+  type OrchestrationReadModel,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import { describe, expect, it } from "vitest";
+
+import { decideOrchestrationCommand } from "./decider.ts";
+import { createEmptyReadModel, projectEvent } from "./projector.ts";
+
+const asCommandId = (value: string): CommandId => CommandId.make(value);
+const asEventId = (value: string): EventId => EventId.make(value);
+const asProjectId = (value: string): ProjectId => ProjectId.make(value);
+const asThreadId = (value: string): ThreadId => ThreadId.make(value);
+
+async function seedReadModel(): Promise<OrchestrationReadModel> {
+  const now = "2026-01-01T00:00:00.000Z";
+  const initial = createEmptyReadModel(now);
+  const withProject = await Effect.runPromise(
+    projectEvent(initial, {
+      sequence: 1,
+      eventId: asEventId("evt-project-create"),
+      aggregateKind: "project",
+      aggregateId: asProjectId("project-delete"),
+      type: "project.created",
+      occurredAt: now,
+      commandId: asCommandId("cmd-project-create"),
+      causationEventId: null,
+      correlationId: asCommandId("cmd-project-create"),
+      metadata: {},
+      payload: {
+        projectId: asProjectId("project-delete"),
+        title: "Project Delete",
+        workspaceRoot: "/tmp/project-delete",
+        defaultModelSelection: null,
+        scripts: [],
+        createdAt: now,
+        updatedAt: now,
+      },
+    }),
+  );
+
+  const withFirstThread = await Effect.runPromise(
+    projectEvent(withProject, {
+      sequence: 2,
+      eventId: asEventId("evt-thread-create-1"),
+      aggregateKind: "thread",
+      aggregateId: asThreadId("thread-delete-1"),
+      type: "thread.created",
+      occurredAt: now,
+      commandId: asCommandId("cmd-thread-create-1"),
+      causationEventId: null,
+      correlationId: asCommandId("cmd-thread-create-1"),
+      metadata: {},
+      payload: {
+        threadId: asThreadId("thread-delete-1"),
+        projectId: asProjectId("project-delete"),
+        title: "Thread Delete 1",
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5-codex",
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        branch: null,
+        worktreePath: null,
+        createdAt: now,
+        updatedAt: now,
+      },
+    }),
+  );
+
+  return Effect.runPromise(
+    projectEvent(withFirstThread, {
+      sequence: 3,
+      eventId: asEventId("evt-thread-create-2"),
+      aggregateKind: "thread",
+      aggregateId: asThreadId("thread-delete-2"),
+      type: "thread.created",
+      occurredAt: now,
+      commandId: asCommandId("cmd-thread-create-2"),
+      causationEventId: null,
+      correlationId: asCommandId("cmd-thread-create-2"),
+      metadata: {},
+      payload: {
+        threadId: asThreadId("thread-delete-2"),
+        projectId: asProjectId("project-delete"),
+        title: "Thread Delete 2",
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5-codex",
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        branch: null,
+        worktreePath: null,
+        createdAt: now,
+        updatedAt: now,
+      },
+    }),
+  );
+}
+
+type PlannedEvent = Omit<OrchestrationEvent, "sequence">;
+
+function normalizeDeleteEvent(event: PlannedEvent | ReadonlyArray<PlannedEvent>) {
+  const events = Array.isArray(event) ? event : [event];
+  return events.map((entry) => {
+    switch (entry.type) {
+      case "thread.deleted":
+        return {
+          type: entry.type,
+          aggregateKind: entry.aggregateKind,
+          aggregateId: entry.aggregateId,
+          commandId: entry.commandId,
+          correlationId: entry.correlationId,
+          payload: {
+            threadId: entry.payload.threadId,
+          },
+        };
+      case "project.deleted":
+        return {
+          type: entry.type,
+          aggregateKind: entry.aggregateKind,
+          aggregateId: entry.aggregateId,
+          commandId: entry.commandId,
+          correlationId: entry.correlationId,
+          payload: {
+            projectId: entry.payload.projectId,
+          },
+        };
+      default:
+        return entry;
+    }
+  });
+}
+
+describe("decider deletion flows", () => {
+  it("rejects deleting a non-empty project without force", async () => {
+    const readModel = await seedReadModel();
+
+    await expect(
+      Effect.runPromise(
+        decideOrchestrationCommand({
+          command: {
+            type: "project.delete",
+            commandId: asCommandId("cmd-project-delete-no-force"),
+            projectId: asProjectId("project-delete"),
+          },
+          readModel,
+        }),
+      ),
+    ).rejects.toThrow("cannot be deleted without force=true");
+  });
+
+  it("reuses thread.delete semantics when force-deleting a non-empty project", async () => {
+    const readModel = await seedReadModel();
+    const projectDeleteCommand: Extract<OrchestrationCommand, { type: "project.delete" }> = {
+      type: "project.delete",
+      commandId: asCommandId("cmd-project-delete-force"),
+      projectId: asProjectId("project-delete"),
+      force: true,
+    };
+
+    const forcedResult = await Effect.runPromise(
+      decideOrchestrationCommand({
+        command: projectDeleteCommand,
+        readModel,
+      }),
+    );
+    const forcedEvents = Array.isArray(forcedResult) ? forcedResult : [forcedResult];
+
+    expect(forcedEvents.map((event) => event.type)).toEqual([
+      "thread.deleted",
+      "thread.deleted",
+      "project.deleted",
+    ]);
+
+    let sequentialReadModel = readModel;
+    let nextSequence = readModel.snapshotSequence;
+    const sequentialEvents: PlannedEvent[] = [];
+    for (const nextCommand of [
+      {
+        type: "thread.delete",
+        commandId: projectDeleteCommand.commandId,
+        threadId: asThreadId("thread-delete-1"),
+      },
+      {
+        type: "thread.delete",
+        commandId: projectDeleteCommand.commandId,
+        threadId: asThreadId("thread-delete-2"),
+      },
+      {
+        type: "project.delete",
+        commandId: projectDeleteCommand.commandId,
+        projectId: asProjectId("project-delete"),
+      },
+    ] satisfies ReadonlyArray<OrchestrationCommand>) {
+      const decided = await Effect.runPromise(
+        decideOrchestrationCommand({
+          command: nextCommand,
+          readModel: sequentialReadModel,
+        }),
+      );
+      const nextEvents = Array.isArray(decided) ? decided : [decided];
+      sequentialEvents.push(...nextEvents);
+      for (const nextEvent of nextEvents) {
+        nextSequence += 1;
+        sequentialReadModel = await Effect.runPromise(
+          projectEvent(sequentialReadModel, {
+            ...nextEvent,
+            sequence: nextSequence,
+          }),
+        );
+      }
+    }
+
+    expect(normalizeDeleteEvent(forcedResult)).toEqual(normalizeDeleteEvent(sequentialEvents));
+  });
+});
diff --git a/apps/server/src/orchestration/decider.projectScripts.test.ts b/apps/server/src/orchestration/decider.projectScripts.test.ts
index a85e21c53f3..c5b7086eb12 100644
--- a/apps/server/src/orchestration/decider.projectScripts.test.ts
+++ b/apps/server/src/orchestration/decider.projectScripts.test.ts
@@ -5,9 +5,11 @@ import {
   MessageId,
   ProjectId,
   ThreadId,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import { describe, expect, it } from "vitest";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 
 import { decideOrchestrationCommand } from "./decider.ts";
 import { createEmptyReadModel, projectEvent } from "./projector.ts";
@@ -18,7 +20,7 @@ const asMessageId = (value: string): MessageId => MessageId.make(value);
 
 describe("decider project scripts", () => {
   it("emits empty scripts on project.create", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const readModel = createEmptyReadModel(now);
 
     const result = await Effect.runPromise(
@@ -41,7 +43,7 @@ describe("decider project scripts", () => {
   });
 
   it("propagates scripts in project.meta.update payload", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const initial = createEmptyReadModel(now);
     const readModel = await Effect.runPromise(
       projectEvent(initial, {
@@ -95,7 +97,7 @@ describe("decider project scripts", () => {
   });
 
   it("emits user message and turn-start-requested events for thread.turn.start", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const initial = createEmptyReadModel(now);
     const withProject = await Effect.runPromise(
       projectEvent(initial, {
@@ -137,7 +139,7 @@ describe("decider project scripts", () => {
           projectId: asProjectId("project-1"),
           title: "Thread",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -162,14 +164,10 @@ describe("decider project scripts", () => {
             text: "hello",
             attachments: [],
           },
-          modelSelection: {
-            provider: "codex",
-            model: "gpt-5.3-codex",
-            options: {
-              reasoningEffort: "high",
-              fastMode: true,
-            },
-          },
+          modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.3-codex", [
+            { id: "reasoningEffort", value: "high" },
+            { id: "fastMode", value: true },
+          ]),
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
           runtimeMode: "approval-required",
           createdAt: now,
@@ -191,20 +189,16 @@ describe("decider project scripts", () => {
     expect(turnStartEvent.payload).toMatchObject({
       threadId: ThreadId.make("thread-1"),
       messageId: asMessageId("message-user-1"),
-      modelSelection: {
-        provider: "codex",
-        model: "gpt-5.3-codex",
-        options: {
-          reasoningEffort: "high",
-          fastMode: true,
-        },
-      },
+      modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.3-codex", [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ]),
       runtimeMode: "approval-required",
     });
   });
 
   it("emits thread.runtime-mode-set from thread.runtime-mode.set", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const initial = createEmptyReadModel(now);
     const withProject = await Effect.runPromise(
       projectEvent(initial, {
@@ -246,7 +240,7 @@ describe("decider project scripts", () => {
           projectId: asProjectId("project-1"),
           title: "Thread",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -286,7 +280,7 @@ describe("decider project scripts", () => {
   });
 
   it("emits thread.interaction-mode-set from thread.interaction-mode.set", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const initial = createEmptyReadModel(now);
     const withProject = await Effect.runPromise(
       projectEvent(initial, {
@@ -328,7 +322,7 @@ describe("decider project scripts", () => {
           projectId: asProjectId("project-1"),
           title: "Thread",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
diff --git a/apps/server/src/orchestration/decider.ts b/apps/server/src/orchestration/decider.ts
index 22f5bcb280d..1004c945dbf 100644
--- a/apps/server/src/orchestration/decider.ts
+++ b/apps/server/src/orchestration/decider.ts
@@ -3,10 +3,12 @@ import type {
   OrchestrationEvent,
   OrchestrationReadModel,
 } from "@t3tools/contracts";
-import { Effect } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
 
 import { OrchestrationCommandInvariantError } from "./Errors.ts";
 import {
+  listThreadsByProjectId,
   requireProject,
   requireProjectAbsent,
   requireThread,
@@ -14,18 +16,9 @@ import {
   requireThreadAbsent,
   requireThreadNotArchived,
 } from "./commandInvariants.ts";
+import { projectEvent } from "./projector.ts";
 
-const nowIso = () => new Date().toISOString();
-const defaultMetadata: Omit<OrchestrationEvent, "sequence" | "type" | "payload"> = {
-  eventId: crypto.randomUUID() as OrchestrationEvent["eventId"],
-  aggregateKind: "thread",
-  aggregateId: "" as OrchestrationEvent["aggregateId"],
-  occurredAt: nowIso(),
-  commandId: null,
-  causationEventId: null,
-  correlationId: null,
-  metadata: {},
-};
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
 
 function withEventBase(
   input: Pick<OrchestrationCommand, "commandId"> & {
@@ -36,27 +29,60 @@ function withEventBase(
   },
 ): Omit<OrchestrationEvent, "sequence" | "type" | "payload"> {
   return {
-    ...defaultMetadata,
     eventId: crypto.randomUUID() as OrchestrationEvent["eventId"],
     aggregateKind: input.aggregateKind,
     aggregateId: input.aggregateId,
     occurredAt: input.occurredAt,
     commandId: input.commandId,
+    causationEventId: null,
     correlationId: input.commandId,
     metadata: input.metadata ?? {},
   };
 }
 
+type PlannedOrchestrationEvent = Omit<OrchestrationEvent, "sequence">;
+
+type DecideOrchestrationCommandResult =
+  | PlannedOrchestrationEvent
+  | ReadonlyArray<PlannedOrchestrationEvent>;
+
+const decideCommandSequence = Effect.fn("decideCommandSequence")(function* ({
+  commands,
+  readModel,
+}: {
+  readonly commands: ReadonlyArray<OrchestrationCommand>;
+  readonly readModel: OrchestrationReadModel;
+}): Effect.fn.Return<ReadonlyArray<PlannedOrchestrationEvent>, OrchestrationCommandInvariantError> {
+  let nextReadModel = readModel;
+  let nextSequence = readModel.snapshotSequence;
+  const plannedEvents: PlannedOrchestrationEvent[] = [];
+
+  for (const nextCommand of commands) {
+    const decided = yield* decideOrchestrationCommand({
+      command: nextCommand,
+      readModel: nextReadModel,
+    });
+    const nextEvents = Array.isArray(decided) ? decided : [decided];
+    for (const nextEvent of nextEvents) {
+      plannedEvents.push(nextEvent);
+      nextSequence += 1;
+      nextReadModel = yield* projectEvent(nextReadModel, {
+        ...nextEvent,
+        sequence: nextSequence,
+      }).pipe(Effect.orDie);
+    }
+  }
+
+  return plannedEvents;
+});
+
 export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand")(function* ({
   command,
   readModel,
 }: {
   readonly command: OrchestrationCommand;
   readonly readModel: OrchestrationReadModel;
-}): Effect.fn.Return<
-  Omit<OrchestrationEvent, "sequence"> | ReadonlyArray<Omit<OrchestrationEvent, "sequence">>,
-  OrchestrationCommandInvariantError
-> {
+}): Effect.fn.Return<DecideOrchestrationCommandResult, OrchestrationCommandInvariantError> {
   switch (command.type) {
     case "project.create": {
       yield* requireProjectAbsent({
@@ -91,7 +117,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         projectId: command.projectId,
       });
-      const occurredAt = nowIso();
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "project",
@@ -119,7 +145,36 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         projectId: command.projectId,
       });
-      const occurredAt = nowIso();
+      const activeThreads = listThreadsByProjectId(readModel, command.projectId).filter(
+        (thread) => thread.deletedAt === null,
+      );
+      if (activeThreads.length > 0 && command.force !== true) {
+        return yield* new OrchestrationCommandInvariantError({
+          commandType: command.type,
+          detail: `Project '${command.projectId}' is not empty and cannot be deleted without force=true.`,
+        });
+      }
+      if (activeThreads.length > 0) {
+        return yield* decideCommandSequence({
+          readModel,
+          commands: [
+            ...activeThreads.map(
+              (thread): Extract<OrchestrationCommand, { type: "thread.delete" }> => ({
+                type: "thread.delete",
+                commandId: command.commandId,
+                threadId: thread.id,
+              }),
+            ),
+            {
+              type: "project.delete",
+              commandId: command.commandId,
+              projectId: command.projectId,
+            },
+          ],
+        });
+      }
+
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "project",
@@ -127,7 +182,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
           occurredAt,
           commandId: command.commandId,
         }),
-        type: "project.deleted",
+        type: "project.deleted" as const,
         payload: {
           projectId: command.projectId,
           deletedAt: occurredAt,
@@ -175,7 +230,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         threadId: command.threadId,
       });
-      const occurredAt = nowIso();
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "thread",
@@ -197,7 +252,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         threadId: command.threadId,
       });
-      const occurredAt = nowIso();
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "thread",
@@ -220,7 +275,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         threadId: command.threadId,
       });
-      const occurredAt = nowIso();
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "thread",
@@ -242,7 +297,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         threadId: command.threadId,
       });
-      const occurredAt = nowIso();
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "thread",
@@ -270,7 +325,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         threadId: command.threadId,
       });
-      const occurredAt = nowIso();
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "thread",
@@ -293,7 +348,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
         command,
         threadId: command.threadId,
       });
-      const occurredAt = nowIso();
+      const occurredAt = yield* nowIso;
       return {
         ...withEventBase({
           aggregateKind: "thread",
diff --git a/apps/server/src/orchestration/http.ts b/apps/server/src/orchestration/http.ts
index 959d841f673..f24f808c6f8 100644
--- a/apps/server/src/orchestration/http.ts
+++ b/apps/server/src/orchestration/http.ts
@@ -4,7 +4,7 @@ import {
   OrchestrationGetSnapshotError,
   type OrchestrationReadModel,
 } from "@t3tools/contracts";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
 import { ServerAuth } from "../auth/Services/ServerAuth.ts";
diff --git a/apps/server/src/orchestration/projector.test.ts b/apps/server/src/orchestration/projector.test.ts
index a61153bb529..01dcb9abeac 100644
--- a/apps/server/src/orchestration/projector.test.ts
+++ b/apps/server/src/orchestration/projector.test.ts
@@ -2,10 +2,11 @@ import {
   CommandId,
   EventId,
   ProjectId,
+  ProviderDriverKind,
   ThreadId,
   type OrchestrationEvent,
 } from "@t3tools/contracts";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 import { describe, expect, it } from "vitest";
 
 import { createEmptyReadModel, projectEvent } from "./projector.ts";
@@ -39,7 +40,7 @@ function makeEvent(input: {
 
 describe("orchestration projector", () => {
   it("applies thread.created events", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const model = createEmptyReadModel(now);
 
     const next = await Effect.runPromise(
@@ -57,7 +58,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "demo",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5-codex",
             },
             runtimeMode: "full-access",
@@ -77,7 +78,7 @@ describe("orchestration projector", () => {
         projectId: "project-1",
         title: "demo",
         modelSelection: {
-          provider: "codex",
+          instanceId: "codex",
           model: "gpt-5-codex",
         },
         runtimeMode: "full-access",
@@ -99,7 +100,7 @@ describe("orchestration projector", () => {
   });
 
   it("fails when event payload cannot be decoded by runtime schema", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const model = createEmptyReadModel(now);
 
     await expect(
@@ -118,7 +119,7 @@ describe("orchestration projector", () => {
               projectId: "project-1",
               title: "demo",
               modelSelection: {
-                provider: "codex",
+                provider: ProviderDriverKind.make("codex"),
                 model: "gpt-5-codex",
               },
               branch: null,
@@ -133,8 +134,8 @@ describe("orchestration projector", () => {
   });
 
   it("applies thread.archived and thread.unarchived events", async () => {
-    const now = new Date().toISOString();
-    const later = new Date(Date.parse(now) + 1_000).toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
+    const later = "2026-01-01T00:00:01.000Z";
     const created = await Effect.runPromise(
       projectEvent(
         createEmptyReadModel(now),
@@ -150,7 +151,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "demo",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5-codex",
             },
             runtimeMode: "full-access",
@@ -205,7 +206,7 @@ describe("orchestration projector", () => {
   });
 
   it("keeps projector forward-compatible for unhandled event types", async () => {
-    const now = new Date().toISOString();
+    const now = "2026-01-01T00:00:00.000Z";
     const model = createEmptyReadModel(now);
 
     const next = await Effect.runPromise(
@@ -253,7 +254,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "demo",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5.3-codex",
             },
             runtimeMode: "full-access",
@@ -319,7 +320,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "demo",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5.3-codex",
             },
             runtimeMode: "full-access",
@@ -376,7 +377,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "demo",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5.3-codex",
             },
             runtimeMode: "full-access",
@@ -463,7 +464,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "demo",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5.3-codex",
             },
             runtimeMode: "full-access",
@@ -678,7 +679,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "demo",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5.3-codex",
             },
             runtimeMode: "full-access",
@@ -831,7 +832,7 @@ describe("orchestration projector", () => {
             projectId: "project-1",
             title: "capped",
             modelSelection: {
-              provider: "codex",
+              provider: ProviderDriverKind.make("codex"),
               model: "gpt-5-codex",
             },
             runtimeMode: "full-access",
diff --git a/apps/server/src/orchestration/projector.ts b/apps/server/src/orchestration/projector.ts
index deb8a6d44d7..0c92f965433 100644
--- a/apps/server/src/orchestration/projector.ts
+++ b/apps/server/src/orchestration/projector.ts
@@ -5,7 +5,8 @@ import {
   OrchestrationSession,
   OrchestrationThread,
 } from "@t3tools/contracts";
-import { Effect, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
 
 import { toProjectorDecodeError, type OrchestrationProjectorDecodeError } from "./Errors.ts";
 import {
@@ -46,15 +47,14 @@ function updateThread(
 }
 
 function decodeForEvent<A>(
-  schema: Schema.Schema<A>,
+  schema: Schema.Decoder<A, never>,
   value: unknown,
   eventType: OrchestrationEvent["type"],
   field: string,
 ): Effect.Effect<A, OrchestrationProjectorDecodeError> {
-  return Effect.try({
-    try: () => Schema.decodeUnknownSync(schema as any)(value),
-    catch: (error) => toProjectorDecodeError(`${eventType}:${field}`)(error as Schema.SchemaError),
-  });
+  return Schema.decodeUnknownEffect(schema)(value).pipe(
+    Effect.mapError(toProjectorDecodeError(`${eventType}:${field}`)),
+  );
 }
 
 function retainThreadMessagesAfterRevert(
diff --git a/apps/server/src/orchestration/runtimeLayer.ts b/apps/server/src/orchestration/runtimeLayer.ts
index 1b964709aec..a2ed5875950 100644
--- a/apps/server/src/orchestration/runtimeLayer.ts
+++ b/apps/server/src/orchestration/runtimeLayer.ts
@@ -1,4 +1,4 @@
-import { Layer } from "effect";
+import * as Layer from "effect/Layer";
 
 import { OrchestrationCommandReceiptRepositoryLive } from "../persistence/Layers/OrchestrationCommandReceipts.ts";
 import { OrchestrationEventStoreLive } from "../persistence/Layers/OrchestrationEventStore.ts";
diff --git a/apps/server/src/os-jank.test.ts b/apps/server/src/os-jank.test.ts
deleted file mode 100644
index ca03ab58682..00000000000
--- a/apps/server/src/os-jank.test.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { fixPath } from "./os-jank";
-
-describe("fixPath", () => {
-  it("hydrates PATH on linux using the resolved login shell", () => {
-    const env: NodeJS.ProcessEnv = {
-      SHELL: "/bin/zsh",
-      PATH: "/usr/bin",
-    };
-    const readPath = vi.fn(() => "/opt/homebrew/bin:/usr/bin");
-
-    fixPath({
-      env,
-      platform: "linux",
-      readPath,
-    });
-
-    expect(readPath).toHaveBeenCalledWith("/bin/zsh");
-    expect(env.PATH).toBe("/opt/homebrew/bin:/usr/bin");
-  });
-
-  it("does nothing outside macOS and linux even when SHELL is set", () => {
-    const env: NodeJS.ProcessEnv = {
-      SHELL: "C:/Program Files/Git/bin/bash.exe",
-      PATH: "C:\\Windows\\System32",
-    };
-    const readPath = vi.fn(() => "/usr/local/bin:/usr/bin");
-
-    fixPath({
-      env,
-      platform: "win32",
-      readPath,
-    });
-
-    expect(readPath).not.toHaveBeenCalled();
-    expect(env.PATH).toBe("C:\\Windows\\System32");
-  });
-});
diff --git a/apps/server/src/os-jank.ts b/apps/server/src/os-jank.ts
index c3629e8fdeb..93a40ae7e19 100644
--- a/apps/server/src/os-jank.ts
+++ b/apps/server/src/os-jank.ts
@@ -1,38 +1,96 @@
-import * as OS from "node:os";
-import { Effect, Path } from "effect";
-import { readPathFromLoginShell, resolveLoginShell } from "@t3tools/shared/shell";
+import * as NodeOS from "node:os";
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import {
+  readPathFromLoginShell,
+  readEnvironmentFromWindowsShell,
+  resolveWindowsEnvironment,
+  type CommandAvailabilityOptions,
+  type WindowsShellEnvironmentReader,
+  listLoginShellCandidates,
+  mergePathEntries,
+  readPathFromLaunchctl,
+} from "@t3tools/shared/shell";
+
+type WindowsCommandAvailabilityChecker = (
+  command: string,
+  options?: CommandAvailabilityOptions,
+) => boolean;
+
+function logPathHydrationWarning(message: string, error?: unknown): void {
+  process.stderr.write(
+    `[server] ${message} ${error instanceof Error ? error.message : (error ?? "")}\n`,
+  );
+}
 
 export function fixPath(
   options: {
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
     readPath?: typeof readPathFromLoginShell;
+    readWindowsEnvironment?: WindowsShellEnvironmentReader;
+    isWindowsCommandAvailable?: WindowsCommandAvailabilityChecker;
+    readLaunchctlPath?: typeof readPathFromLaunchctl;
+    userShell?: string;
+    logWarning?: (message: string, error?: unknown) => void;
   } = {},
 ): void {
   const platform = options.platform ?? process.platform;
-  if (platform !== "darwin" && platform !== "linux") return;
-
   const env = options.env ?? process.env;
+  const logWarning = options.logWarning ?? logPathHydrationWarning;
+  const readPath = options.readPath ?? readPathFromLoginShell;
 
   try {
-    const shell = resolveLoginShell(platform, env.SHELL);
-    if (!shell) return;
-    const result = (options.readPath ?? readPathFromLoginShell)(shell);
-    if (result) {
-      env.PATH = result;
+    if (platform === "win32") {
+      const repairedEnvironment = resolveWindowsEnvironment(env, {
+        readEnvironment: options.readWindowsEnvironment ?? readEnvironmentFromWindowsShell,
+        ...(options.isWindowsCommandAvailable
+          ? { commandAvailable: options.isWindowsCommandAvailable }
+          : {}),
+      });
+      for (const [key, value] of Object.entries(repairedEnvironment)) {
+        if (value !== undefined) {
+          env[key] = value;
+        }
+      }
+      return;
+    }
+
+    if (platform !== "darwin" && platform !== "linux") return;
+
+    let shellPath: string | undefined;
+    for (const shell of listLoginShellCandidates(platform, env.SHELL, options.userShell)) {
+      try {
+        shellPath = readPath(shell);
+      } catch (error) {
+        logWarning(`Failed to read PATH from login shell ${shell}.`, error);
+      }
+
+      if (shellPath) {
+        break;
+      }
+    }
+
+    const launchctlPath =
+      platform === "darwin" && !shellPath
+        ? (options.readLaunchctlPath ?? readPathFromLaunchctl)()
+        : undefined;
+    const mergedPath = mergePathEntries(shellPath ?? launchctlPath, env.PATH, platform);
+    if (mergedPath) {
+      env.PATH = mergedPath;
     }
-  } catch {
-    // Silently ignore — keep default PATH
+  } catch (error) {
+    logWarning("Failed to hydrate PATH from the user environment.", error);
   }
 }
 
 export const expandHomePath = Effect.fn(function* (input: string) {
   const { join } = yield* Path.Path;
   if (input === "~") {
-    return OS.homedir();
+    return NodeOS.homedir();
   }
   if (input.startsWith("~/") || input.startsWith("~\\")) {
-    return join(OS.homedir(), input.slice(2));
+    return join(NodeOS.homedir(), input.slice(2));
   }
   return input;
 });
@@ -40,7 +98,7 @@ export const expandHomePath = Effect.fn(function* (input: string) {
 export const resolveBaseDir = Effect.fn(function* (raw: string | undefined) {
   const { join, resolve } = yield* Path.Path;
   if (!raw || raw.trim().length === 0) {
-    return join(OS.homedir(), ".t3");
+    return join(NodeOS.homedir(), ".t3");
   }
   return resolve(yield* expandHomePath(raw.trim()));
 });
diff --git a/apps/server/src/pathExpansion.test.ts b/apps/server/src/pathExpansion.test.ts
new file mode 100644
index 00000000000..c195490eed9
--- /dev/null
+++ b/apps/server/src/pathExpansion.test.ts
@@ -0,0 +1,34 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { expandHomePath } from "./pathExpansion.ts";
+
+describe("expandHomePath", () => {
+  it("returns an empty string unchanged", () => {
+    expect(expandHomePath("")).toBe("");
+  });
+
+  it("returns paths without a leading tilde unchanged", () => {
+    expect(expandHomePath("/absolute/path")).toBe("/absolute/path");
+    expect(expandHomePath("relative/path")).toBe("relative/path");
+    expect(expandHomePath("some~weird~path")).toBe("some~weird~path");
+  });
+
+  it("expands a lone tilde to the home directory", () => {
+    expect(expandHomePath("~")).toBe(homedir());
+  });
+
+  it("expands ~/ to a subpath of the home directory", () => {
+    expect(expandHomePath("~/.codex-work")).toBe(join(homedir(), ".codex-work"));
+  });
+
+  it("expands a Windows-style ~\\ prefix", () => {
+    expect(expandHomePath("~\\.codex")).toBe(join(homedir(), ".codex"));
+  });
+
+  it("does not expand ~user paths", () => {
+    expect(expandHomePath("~alice/foo")).toBe("~alice/foo");
+  });
+});
diff --git a/apps/server/src/pathExpansion.ts b/apps/server/src/pathExpansion.ts
new file mode 100644
index 00000000000..170d83c54d0
--- /dev/null
+++ b/apps/server/src/pathExpansion.ts
@@ -0,0 +1,24 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Expand a leading `~` (or `~/…`, `~\…`) in a user-supplied path to the
+ * current user's home directory. Spawned processes don't get shell
+ * expansion, so env vars like `CODEX_HOME=~/.codex-work` would be passed
+ * verbatim and treated as relative paths by the receiver.
+ *
+ * Matches the behavior of the other `expandHomePath` helpers in the
+ * workspace layers and CLI bootstrap: `~` alone and both `~/` and `~\`
+ * separators are handled. Returns the input unchanged if it doesn't
+ * start with `~` or is empty. Does not handle `~user` (other-user)
+ * expansion.
+ */
+export function expandHomePath(value: string): string {
+  if (!value) return value;
+  if (value === "~") return homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return join(homedir(), value.slice(2));
+  }
+  return value;
+}
diff --git a/apps/server/src/persistence/Errors.ts b/apps/server/src/persistence/Errors.ts
index eb05bf5ae95..2b702eba5ea 100644
--- a/apps/server/src/persistence/Errors.ts
+++ b/apps/server/src/persistence/Errors.ts
@@ -1,4 +1,5 @@
-import { Schema, SchemaIssue } from "effect";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
 
 // ===============================
 // Core Persistence Errors
@@ -29,6 +30,8 @@ export class PersistenceDecodeError extends Schema.TaggedErrorClass<PersistenceD
     return `Decode error in ${this.operation}: ${this.issue}`;
   }
 }
+const isPersistenceSqlError = Schema.is(PersistenceSqlError);
+const isPersistenceDecodeError = Schema.is(PersistenceDecodeError);
 
 export function toPersistenceSqlError(operation: string) {
   return (cause: unknown): PersistenceSqlError =>
@@ -58,7 +61,7 @@ export function toPersistenceDecodeCauseError(operation: string) {
 }
 
 export const isPersistenceError = (u: unknown) =>
-  Schema.is(PersistenceSqlError)(u) || Schema.is(PersistenceDecodeError)(u);
+  isPersistenceSqlError(u) || isPersistenceDecodeError(u);
 
 // ===============================
 // Provider Session Repository Errors
diff --git a/apps/server/src/persistence/Layers/AuthPairingLinks.ts b/apps/server/src/persistence/Layers/AuthPairingLinks.ts
index 9767f24993a..15c572ad0a1 100644
--- a/apps/server/src/persistence/Layers/AuthPairingLinks.ts
+++ b/apps/server/src/persistence/Layers/AuthPairingLinks.ts
@@ -1,6 +1,8 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
 
 import {
   toPersistenceDecodeError,
diff --git a/apps/server/src/persistence/Layers/AuthSessions.ts b/apps/server/src/persistence/Layers/AuthSessions.ts
index 66e02ed2a72..64b8146f927 100644
--- a/apps/server/src/persistence/Layers/AuthSessions.ts
+++ b/apps/server/src/persistence/Layers/AuthSessions.ts
@@ -1,7 +1,10 @@
 import { AuthSessionId } from "@t3tools/contracts";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Option, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 
 import {
   toPersistenceDecodeError,
diff --git a/apps/server/src/persistence/Layers/OrchestrationCommandReceipts.ts b/apps/server/src/persistence/Layers/OrchestrationCommandReceipts.ts
index 33f28567428..989f5d78f8d 100644
--- a/apps/server/src/persistence/Layers/OrchestrationCommandReceipts.ts
+++ b/apps/server/src/persistence/Layers/OrchestrationCommandReceipts.ts
@@ -1,6 +1,7 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import { toPersistenceSqlError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
index 80526986a70..2bac5de920c 100644
--- a/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
+++ b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
@@ -1,12 +1,16 @@
 import { CommandId, EventId, ProjectId } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
-import { Effect, Layer, Schema, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { PersistenceDecodeError } from "../Errors.ts";
 import { OrchestrationEventStore } from "../Services/OrchestrationEventStore.ts";
 import { OrchestrationEventStoreLive } from "./OrchestrationEventStore.ts";
 import { SqlitePersistenceMemory } from "./Sqlite.ts";
+const isPersistenceDecodeError = Schema.is(PersistenceDecodeError);
 
 const layer = it.layer(
   OrchestrationEventStoreLive.pipe(Layer.provideMerge(SqlitePersistenceMemory)),
@@ -17,7 +21,7 @@ layer("OrchestrationEventStore", (it) => {
     Effect.gen(function* () {
       const eventStore = yield* OrchestrationEventStore;
       const sql = yield* SqlClient.SqlClient;
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
 
       const appended = yield* eventStore.append({
         type: "project.created",
@@ -69,7 +73,7 @@ layer("OrchestrationEventStore", (it) => {
     Effect.gen(function* () {
       const eventStore = yield* OrchestrationEventStore;
       const sql = yield* SqlClient.SqlClient;
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
 
       yield* sql`
         INSERT INTO orchestration_events (
@@ -107,7 +111,7 @@ layer("OrchestrationEventStore", (it) => {
       );
       assert.equal(replayResult._tag, "Failure");
       if (replayResult._tag === "Failure") {
-        assert.ok(Schema.is(PersistenceDecodeError)(replayResult.failure));
+        assert.ok(isPersistenceDecodeError(replayResult.failure));
         assert.ok(
           replayResult.failure.operation.includes(
             "OrchestrationEventStore.readFromSequence:decodeRows",
diff --git a/apps/server/src/persistence/Layers/OrchestrationEventStore.ts b/apps/server/src/persistence/Layers/OrchestrationEventStore.ts
index 4d81cf5e8d7..18d0e9aa578 100644
--- a/apps/server/src/persistence/Layers/OrchestrationEventStore.ts
+++ b/apps/server/src/persistence/Layers/OrchestrationEventStore.ts
@@ -13,7 +13,10 @@ import {
 } from "@t3tools/contracts";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Schema, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 
 import {
   toPersistenceDecodeError,
diff --git a/apps/server/src/persistence/Layers/ProjectionCheckpoints.ts b/apps/server/src/persistence/Layers/ProjectionCheckpoints.ts
index 26ef8fed1b9..cfa5658d0e9 100644
--- a/apps/server/src/persistence/Layers/ProjectionCheckpoints.ts
+++ b/apps/server/src/persistence/Layers/ProjectionCheckpoints.ts
@@ -1,7 +1,11 @@
 import { OrchestrationCheckpointFile } from "@t3tools/contracts";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Option, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 
 import { toPersistenceDecodeError, toPersistenceSqlError } from "../Errors.ts";
 import {
diff --git a/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts b/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts
index 25443a70dca..253f6e13b97 100644
--- a/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts
+++ b/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts
@@ -1,6 +1,7 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import { toPersistenceSqlError } from "../Errors.ts";
 import {
diff --git a/apps/server/src/persistence/Layers/ProjectionProjects.ts b/apps/server/src/persistence/Layers/ProjectionProjects.ts
index 7ff19f55aea..c1ca6d3104e 100644
--- a/apps/server/src/persistence/Layers/ProjectionProjects.ts
+++ b/apps/server/src/persistence/Layers/ProjectionProjects.ts
@@ -1,6 +1,9 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 
 import { ModelSelection, ProjectScript } from "@t3tools/contracts";
 import { toPersistenceSqlError } from "../Errors.ts";
diff --git a/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts b/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
index 08bc2481226..a2069e62a14 100644
--- a/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
+++ b/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
@@ -1,6 +1,8 @@
-import { ProjectId, ThreadId } from "@t3tools/contracts";
+import { ProjectId, ThreadId, ProviderInstanceId } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
-import { Effect, Layer, Option } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { SqlitePersistenceMemory } from "./Sqlite.ts";
@@ -28,7 +30,7 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
         title: "Null options project",
         workspaceRoot: "/tmp/project-null-options",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5.4",
         },
         scripts: [],
@@ -46,13 +48,14 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
       `;
       const row = rows[0];
       if (!row) {
-        return yield* Effect.fail(new Error("Expected projection_projects row to exist."));
+        return yield* Effect.die("Expected projection_projects row to exist.");
       }
 
       assert.strictEqual(
         row.defaultModelSelection,
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         JSON.stringify({
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5.4",
         }),
       );
@@ -61,7 +64,7 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
         projectId: ProjectId.make("project-null-options"),
       });
       assert.deepStrictEqual(Option.getOrNull(persisted)?.defaultModelSelection, {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5.4",
       });
     }),
@@ -77,7 +80,7 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
         projectId: ProjectId.make("project-null-options"),
         title: "Null options thread",
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         },
         runtimeMode: "full-access",
@@ -88,6 +91,10 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
         createdAt: "2026-03-24T00:00:00.000Z",
         updatedAt: "2026-03-24T00:00:00.000Z",
         archivedAt: null,
+        latestUserMessageAt: null,
+        pendingApprovalCount: 0,
+        pendingUserInputCount: 0,
+        hasActionableProposedPlan: 0,
         deletedAt: null,
       });
 
@@ -100,13 +107,14 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
       `;
       const row = rows[0];
       if (!row) {
-        return yield* Effect.fail(new Error("Expected projection_threads row to exist."));
+        return yield* Effect.die("Expected projection_threads row to exist.");
       }
 
       assert.strictEqual(
         row.modelSelection,
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         JSON.stringify({
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         }),
       );
@@ -115,7 +123,7 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
         threadId: ThreadId.make("thread-null-options"),
       });
       assert.deepStrictEqual(Option.getOrNull(persisted)?.modelSelection, {
-        provider: "claudeAgent",
+        instanceId: ProviderInstanceId.make("claudeAgent"),
         model: "claude-opus-4-6",
       });
     }),
diff --git a/apps/server/src/persistence/Layers/ProjectionState.ts b/apps/server/src/persistence/Layers/ProjectionState.ts
index 7c2b8110c70..f630fe51e03 100644
--- a/apps/server/src/persistence/Layers/ProjectionState.ts
+++ b/apps/server/src/persistence/Layers/ProjectionState.ts
@@ -1,7 +1,9 @@
 import { NonNegativeInt } from "@t3tools/contracts";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
 
 import { toPersistenceSqlError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Layers/ProjectionThreadActivities.ts b/apps/server/src/persistence/Layers/ProjectionThreadActivities.ts
index 8e88cfa7853..2f4815f9654 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadActivities.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadActivities.ts
@@ -1,7 +1,10 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
 import { NonNegativeInt } from "@t3tools/contracts";
-import { Effect, Layer, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 
 import { toPersistenceDecodeError, toPersistenceSqlError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts b/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts
index 8bbe723bf37..b1f394a9e57 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts
@@ -1,6 +1,7 @@
 import { MessageId, ThreadId } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import { ProjectionThreadMessageRepository } from "../Services/ProjectionThreadMessages.ts";
 import { ProjectionThreadMessageRepositoryLive } from "./ProjectionThreadMessages.ts";
diff --git a/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts b/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts
index 13b7086cecd..71919166886 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts
@@ -1,6 +1,10 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Option, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 import { ChatAttachment } from "@t3tools/contracts";
 
 import { toPersistenceSqlError } from "../Errors.ts";
diff --git a/apps/server/src/persistence/Layers/ProjectionThreadProposedPlans.ts b/apps/server/src/persistence/Layers/ProjectionThreadProposedPlans.ts
index ccd322feb23..63aed1a1670 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadProposedPlans.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadProposedPlans.ts
@@ -1,4 +1,5 @@
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
 
diff --git a/apps/server/src/persistence/Layers/ProjectionThreadSessions.ts b/apps/server/src/persistence/Layers/ProjectionThreadSessions.ts
index 2499eba1967..dcb750983a0 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadSessions.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadSessions.ts
@@ -1,6 +1,7 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 import { toPersistenceSqlError } from "../Errors.ts";
 
@@ -23,6 +24,7 @@ const makeProjectionThreadSessionRepository = Effect.gen(function* () {
           thread_id,
           status,
           provider_name,
+          provider_instance_id,
           runtime_mode,
           active_turn_id,
           last_error,
@@ -32,6 +34,7 @@ const makeProjectionThreadSessionRepository = Effect.gen(function* () {
           ${row.threadId},
           ${row.status},
           ${row.providerName},
+          ${row.providerInstanceId},
           ${row.runtimeMode},
           ${row.activeTurnId},
           ${row.lastError},
@@ -41,6 +44,7 @@ const makeProjectionThreadSessionRepository = Effect.gen(function* () {
         DO UPDATE SET
           status = excluded.status,
           provider_name = excluded.provider_name,
+          provider_instance_id = excluded.provider_instance_id,
           runtime_mode = excluded.runtime_mode,
           active_turn_id = excluded.active_turn_id,
           last_error = excluded.last_error,
@@ -57,6 +61,7 @@ const makeProjectionThreadSessionRepository = Effect.gen(function* () {
           thread_id AS "threadId",
           status,
           provider_name AS "providerName",
+          provider_instance_id AS "providerInstanceId",
           runtime_mode AS "runtimeMode",
           active_turn_id AS "activeTurnId",
           last_error AS "lastError",
diff --git a/apps/server/src/persistence/Layers/ProjectionThreads.ts b/apps/server/src/persistence/Layers/ProjectionThreads.ts
index 48dd51fdcab..1baeb375c15 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreads.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreads.ts
@@ -1,6 +1,9 @@
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 
 import { toPersistenceSqlError } from "../Errors.ts";
 import {
@@ -40,6 +43,10 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           created_at,
           updated_at,
           archived_at,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
           deleted_at
         )
         VALUES (
@@ -55,6 +62,10 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           ${row.createdAt},
           ${row.updatedAt},
           ${row.archivedAt},
+          ${row.latestUserMessageAt},
+          ${row.pendingApprovalCount},
+          ${row.pendingUserInputCount},
+          ${row.hasActionableProposedPlan},
           ${row.deletedAt}
         )
         ON CONFLICT (thread_id)
@@ -70,6 +81,10 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           created_at = excluded.created_at,
           updated_at = excluded.updated_at,
           archived_at = excluded.archived_at,
+          latest_user_message_at = excluded.latest_user_message_at,
+          pending_approval_count = excluded.pending_approval_count,
+          pending_user_input_count = excluded.pending_user_input_count,
+          has_actionable_proposed_plan = excluded.has_actionable_proposed_plan,
           deleted_at = excluded.deleted_at
       `,
   });
@@ -92,6 +107,10 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           created_at AS "createdAt",
           updated_at AS "updatedAt",
           archived_at AS "archivedAt",
+          latest_user_message_at AS "latestUserMessageAt",
+          pending_approval_count AS "pendingApprovalCount",
+          pending_user_input_count AS "pendingUserInputCount",
+          has_actionable_proposed_plan AS "hasActionableProposedPlan",
           deleted_at AS "deletedAt"
         FROM projection_threads
         WHERE thread_id = ${threadId}
@@ -116,6 +135,10 @@ const makeProjectionThreadRepository = Effect.gen(function* () {
           created_at AS "createdAt",
           updated_at AS "updatedAt",
           archived_at AS "archivedAt",
+          latest_user_message_at AS "latestUserMessageAt",
+          pending_approval_count AS "pendingApprovalCount",
+          pending_user_input_count AS "pendingUserInputCount",
+          has_actionable_proposed_plan AS "hasActionableProposedPlan",
           deleted_at AS "deletedAt"
         FROM projection_threads
         WHERE project_id = ${projectId}
diff --git a/apps/server/src/persistence/Layers/ProjectionTurns.ts b/apps/server/src/persistence/Layers/ProjectionTurns.ts
index 9b6c9c57710..bd57a4eaa30 100644
--- a/apps/server/src/persistence/Layers/ProjectionTurns.ts
+++ b/apps/server/src/persistence/Layers/ProjectionTurns.ts
@@ -1,7 +1,11 @@
 import { OrchestrationCheckpointFile } from "@t3tools/contracts";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Option, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 
 import { toPersistenceDecodeError, toPersistenceSqlError } from "../Errors.ts";
 import {
diff --git a/apps/server/src/persistence/Layers/ProviderSessionRuntime.ts b/apps/server/src/persistence/Layers/ProviderSessionRuntime.ts
index da3e8bce90a..9ee5c82bb53 100644
--- a/apps/server/src/persistence/Layers/ProviderSessionRuntime.ts
+++ b/apps/server/src/persistence/Layers/ProviderSessionRuntime.ts
@@ -1,7 +1,11 @@
 import { ThreadId } from "@t3tools/contracts";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
-import { Effect, Layer, Option, Schema, Struct } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Struct from "effect/Struct";
 
 import {
   toPersistenceDecodeError,
@@ -46,6 +50,7 @@ const makeProviderSessionRuntimeRepository = Effect.gen(function* () {
         INSERT INTO provider_session_runtime (
           thread_id,
           provider_name,
+          provider_instance_id,
           adapter_key,
           runtime_mode,
           status,
@@ -56,6 +61,7 @@ const makeProviderSessionRuntimeRepository = Effect.gen(function* () {
         VALUES (
           ${runtime.threadId},
           ${runtime.providerName},
+          ${runtime.providerInstanceId},
           ${runtime.adapterKey},
           ${runtime.runtimeMode},
           ${runtime.status},
@@ -66,6 +72,7 @@ const makeProviderSessionRuntimeRepository = Effect.gen(function* () {
         ON CONFLICT (thread_id)
         DO UPDATE SET
           provider_name = excluded.provider_name,
+          provider_instance_id = excluded.provider_instance_id,
           adapter_key = excluded.adapter_key,
           runtime_mode = excluded.runtime_mode,
           status = excluded.status,
@@ -83,6 +90,7 @@ const makeProviderSessionRuntimeRepository = Effect.gen(function* () {
         SELECT
           thread_id AS "threadId",
           provider_name AS "providerName",
+          provider_instance_id AS "providerInstanceId",
           adapter_key AS "adapterKey",
           runtime_mode AS "runtimeMode",
           status,
@@ -102,6 +110,7 @@ const makeProviderSessionRuntimeRepository = Effect.gen(function* () {
         SELECT
           thread_id AS "threadId",
           provider_name AS "providerName",
+          provider_instance_id AS "providerInstanceId",
           adapter_key AS "adapterKey",
           runtime_mode AS "runtimeMode",
           status,
diff --git a/apps/server/src/persistence/Layers/Sqlite.ts b/apps/server/src/persistence/Layers/Sqlite.ts
index 58556099db1..3bc1ec4d2d2 100644
--- a/apps/server/src/persistence/Layers/Sqlite.ts
+++ b/apps/server/src/persistence/Layers/Sqlite.ts
@@ -1,4 +1,7 @@
-import { Effect, Layer, FileSystem, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { runMigrations } from "../Migrations.ts";
diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index 8c9fe4d9fd1..cc5024d5f51 100644
--- a/apps/server/src/persistence/Migrations.ts
+++ b/apps/server/src/persistence/Migrations.ts
@@ -35,6 +35,14 @@ import Migration0019 from "./Migrations/019_ProjectionSnapshotLookupIndexes.ts";
 import Migration0020 from "./Migrations/020_AuthAccessManagement.ts";
 import Migration0021 from "./Migrations/021_AuthSessionClientMetadata.ts";
 import Migration0022 from "./Migrations/022_AuthSessionLastConnectedAt.ts";
+import Migration0023 from "./Migrations/023_ProjectionThreadShellSummary.ts";
+import Migration0024 from "./Migrations/024_BackfillProjectionThreadShellSummary.ts";
+import Migration0025 from "./Migrations/025_CleanupInvalidProjectionPendingApprovals.ts";
+import Migration0026 from "./Migrations/026_CanonicalizeModelSelectionOptions.ts";
+import Migration0027 from "./Migrations/027_ProviderSessionRuntimeInstanceId.ts";
+import Migration0028 from "./Migrations/028_ProjectionThreadSessionInstanceId.ts";
+import Migration0029 from "./Migrations/029_ProjectionThreadDetailOrderingIndexes.ts";
+import Migration0030 from "./Migrations/030_ProjectionThreadShellArchiveIndexes.ts";
 
 /**
  * Migration loader with all migrations defined inline.
@@ -69,6 +77,14 @@ export const migrationEntries = [
   [20, "AuthAccessManagement", Migration0020],
   [21, "AuthSessionClientMetadata", Migration0021],
   [22, "AuthSessionLastConnectedAt", Migration0022],
+  [23, "ProjectionThreadShellSummary", Migration0023],
+  [24, "BackfillProjectionThreadShellSummary", Migration0024],
+  [25, "CleanupInvalidProjectionPendingApprovals", Migration0025],
+  [26, "CanonicalizeModelSelectionOptions", Migration0026],
+  [27, "ProviderSessionRuntimeInstanceId", Migration0027],
+  [28, "ProjectionThreadSessionInstanceId", Migration0028],
+  [29, "ProjectionThreadDetailOrderingIndexes", Migration0029],
+  [30, "ProjectionThreadShellArchiveIndexes", Migration0030],
 ] as const;
 
 export const makeMigrationLoader = (throughId?: number) =>
diff --git a/apps/server/src/persistence/Migrations/016_CanonicalizeModelSelections.test.ts b/apps/server/src/persistence/Migrations/016_CanonicalizeModelSelections.test.ts
index d74e9fe08cd..1e64519ff4f 100644
--- a/apps/server/src/persistence/Migrations/016_CanonicalizeModelSelections.test.ts
+++ b/apps/server/src/persistence/Migrations/016_CanonicalizeModelSelections.test.ts
@@ -1,5 +1,6 @@
 import { assert, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { runMigrations } from "../Migrations.ts";
@@ -264,7 +265,7 @@ layer("016_CanonicalizeModelSelections", (it) => {
         FROM orchestration_events
         ORDER BY rowid ASC
       `;
-
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           assert.deepStrictEqual(JSON.parse(eventRows[0]!.payloadJson), {
             projectId: "project-1",
             title: "Project",
@@ -280,7 +281,7 @@ layer("016_CanonicalizeModelSelections", (it) => {
             createdAt: "2026-01-01T00:00:00.000Z",
             updatedAt: "2026-01-01T00:00:00.000Z",
           });
-
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           assert.deepStrictEqual(JSON.parse(eventRows[1]!.payloadJson), {
             projectId: "project-2",
             title: "Fallback Project",
@@ -296,7 +297,7 @@ layer("016_CanonicalizeModelSelections", (it) => {
             createdAt: "2026-01-01T00:00:00.000Z",
             updatedAt: "2026-01-01T00:00:00.000Z",
           });
-
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           assert.deepStrictEqual(JSON.parse(eventRows[2]!.payloadJson), {
             projectId: "project-3",
             title: "Null Model Project",
@@ -306,7 +307,7 @@ layer("016_CanonicalizeModelSelections", (it) => {
             createdAt: "2026-01-01T00:00:00.000Z",
             updatedAt: "2026-01-01T00:00:00.000Z",
           });
-
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           assert.deepStrictEqual(JSON.parse(eventRows[3]!.payloadJson), {
             threadId: "thread-1",
             projectId: "project-1",
@@ -326,7 +327,7 @@ layer("016_CanonicalizeModelSelections", (it) => {
             createdAt: "2026-01-01T00:00:00.000Z",
             updatedAt: "2026-01-01T00:00:00.000Z",
           });
-
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           assert.deepStrictEqual(JSON.parse(eventRows[4]!.payloadJson), {
             threadId: "thread-2",
             projectId: "project-1",
@@ -345,7 +346,7 @@ layer("016_CanonicalizeModelSelections", (it) => {
             createdAt: "2026-01-01T00:00:00.000Z",
             updatedAt: "2026-01-01T00:00:00.000Z",
           });
-
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           assert.deepStrictEqual(JSON.parse(eventRows[5]!.payloadJson), {
             threadId: "thread-1",
             turnId: "turn-1",
@@ -359,7 +360,7 @@ layer("016_CanonicalizeModelSelections", (it) => {
             },
             deliveryMode: "buffered",
           });
-
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           assert.deepStrictEqual(JSON.parse(eventRows[6]!.payloadJson), {
             threadId: "thread-3",
             projectId: "project-1",
diff --git a/apps/server/src/persistence/Migrations/019_ProjectionSnapshotLookupIndexes.test.ts b/apps/server/src/persistence/Migrations/019_ProjectionSnapshotLookupIndexes.test.ts
index 6207a9bcb6a..2011613a9f9 100644
--- a/apps/server/src/persistence/Migrations/019_ProjectionSnapshotLookupIndexes.test.ts
+++ b/apps/server/src/persistence/Migrations/019_ProjectionSnapshotLookupIndexes.test.ts
@@ -1,5 +1,6 @@
 import { assert, it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { runMigrations } from "../Migrations.ts";
diff --git a/apps/server/src/persistence/Migrations/023_ProjectionThreadShellSummary.ts b/apps/server/src/persistence/Migrations/023_ProjectionThreadShellSummary.ts
new file mode 100644
index 00000000000..759f87e8ad7
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/023_ProjectionThreadShellSummary.ts
@@ -0,0 +1,26 @@
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as Effect from "effect/Effect";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  yield* sql`
+    ALTER TABLE projection_threads
+    ADD COLUMN latest_user_message_at TEXT
+  `.pipe(Effect.catch(() => Effect.void));
+
+  yield* sql`
+    ALTER TABLE projection_threads
+    ADD COLUMN pending_approval_count INTEGER NOT NULL DEFAULT 0
+  `.pipe(Effect.catch(() => Effect.void));
+
+  yield* sql`
+    ALTER TABLE projection_threads
+    ADD COLUMN pending_user_input_count INTEGER NOT NULL DEFAULT 0
+  `.pipe(Effect.catch(() => Effect.void));
+
+  yield* sql`
+    ALTER TABLE projection_threads
+    ADD COLUMN has_actionable_proposed_plan INTEGER NOT NULL DEFAULT 0
+  `.pipe(Effect.catch(() => Effect.void));
+});
diff --git a/apps/server/src/persistence/Migrations/024_BackfillProjectionThreadShellSummary.test.ts b/apps/server/src/persistence/Migrations/024_BackfillProjectionThreadShellSummary.test.ts
new file mode 100644
index 00000000000..71dfe6fd004
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/024_BackfillProjectionThreadShellSummary.test.ts
@@ -0,0 +1,219 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+import { runMigrations } from "../Migrations.ts";
+import * as NodeSqliteClient from "../NodeSqliteClient.ts";
+
+const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));
+
+layer("024_BackfillProjectionThreadShellSummary", (it) => {
+  it.effect("backfills thread shell summary fields and clears stale projected approvals", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 23 });
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          created_at,
+          updated_at,
+          archived_at,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          deleted_at
+        )
+        VALUES (
+          'thread-1',
+          'project-1',
+          'Thread 1',
+          '{"provider":"codex","model":"gpt-5-codex"}',
+          'approval-required',
+          'plan',
+          NULL,
+          NULL,
+          'turn-1',
+          '2026-02-24T00:00:00.000Z',
+          '2026-02-24T00:00:00.000Z',
+          NULL,
+          NULL,
+          0,
+          0,
+          0,
+          NULL
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_thread_messages (
+          message_id,
+          thread_id,
+          turn_id,
+          role,
+          text,
+          attachments_json,
+          is_streaming,
+          created_at,
+          updated_at
+        )
+        VALUES (
+          'message-user-1',
+          'thread-1',
+          'turn-1',
+          'user',
+          'Need help',
+          NULL,
+          0,
+          '2026-02-24T00:01:00.000Z',
+          '2026-02-24T00:01:00.000Z'
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_thread_activities (
+          activity_id,
+          thread_id,
+          turn_id,
+          tone,
+          kind,
+          summary,
+          payload_json,
+          sequence,
+          created_at
+        )
+        VALUES
+          (
+            'activity-approval-requested',
+            'thread-1',
+            'turn-1',
+            'approval',
+            'approval.requested',
+            'Command approval requested',
+            '{"requestId":"approval-1","requestKind":"command"}',
+            NULL,
+            '2026-02-24T00:02:00.000Z'
+          ),
+          (
+            'activity-approval-stale',
+            'thread-1',
+            'turn-1',
+            'error',
+            'provider.approval.respond.failed',
+            'Provider approval response failed',
+            '{"requestId":"approval-1","detail":"Unknown pending permission request: approval-1"}',
+            NULL,
+            '2026-02-24T00:03:00.000Z'
+          ),
+          (
+            'activity-user-input-requested',
+            'thread-1',
+            'turn-1',
+            'info',
+            'user-input.requested',
+            'User input requested',
+            '{"requestId":"input-1","questions":[{"id":"area","header":"Area","question":"Which repo area should I inspect next?","options":[{"label":"Server","description":"Server orchestration."}]}]}',
+            NULL,
+            '2026-02-24T00:04:00.000Z'
+          )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_thread_proposed_plans (
+          plan_id,
+          thread_id,
+          turn_id,
+          plan_markdown,
+          implemented_at,
+          implementation_thread_id,
+          created_at,
+          updated_at
+        )
+        VALUES (
+          'plan-1',
+          'thread-1',
+          'turn-1',
+          '# Do the thing',
+          NULL,
+          NULL,
+          '2026-02-24T00:05:00.000Z',
+          '2026-02-24T00:05:00.000Z'
+        )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_pending_approvals (
+          request_id,
+          thread_id,
+          turn_id,
+          status,
+          decision,
+          created_at,
+          resolved_at
+        )
+        VALUES (
+          'approval-1',
+          'thread-1',
+          'turn-1',
+          'pending',
+          NULL,
+          '2026-02-24T00:02:00.000Z',
+          NULL
+        )
+      `;
+
+      yield* runMigrations({ toMigrationInclusive: 24 });
+
+      const threadRows = yield* sql<{
+        readonly latestUserMessageAt: string | null;
+        readonly pendingApprovalCount: number;
+        readonly pendingUserInputCount: number;
+        readonly hasActionableProposedPlan: number;
+      }>`
+        SELECT
+          latest_user_message_at AS "latestUserMessageAt",
+          pending_approval_count AS "pendingApprovalCount",
+          pending_user_input_count AS "pendingUserInputCount",
+          has_actionable_proposed_plan AS "hasActionableProposedPlan"
+        FROM projection_threads
+        WHERE thread_id = 'thread-1'
+      `;
+      assert.deepStrictEqual(threadRows, [
+        {
+          latestUserMessageAt: "2026-02-24T00:01:00.000Z",
+          pendingApprovalCount: 0,
+          pendingUserInputCount: 1,
+          hasActionableProposedPlan: 1,
+        },
+      ]);
+
+      const approvalRows = yield* sql<{
+        readonly status: string;
+        readonly resolvedAt: string | null;
+      }>`
+        SELECT
+          status,
+          resolved_at AS "resolvedAt"
+        FROM projection_pending_approvals
+        WHERE request_id = 'approval-1'
+      `;
+      assert.deepStrictEqual(approvalRows, [
+        {
+          status: "resolved",
+          resolvedAt: "2026-02-24T00:03:00.000Z",
+        },
+      ]);
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/024_BackfillProjectionThreadShellSummary.ts b/apps/server/src/persistence/Migrations/024_BackfillProjectionThreadShellSummary.ts
new file mode 100644
index 00000000000..549906dfb03
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/024_BackfillProjectionThreadShellSummary.ts
@@ -0,0 +1,277 @@
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as Effect from "effect/Effect";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  yield* sql`
+    INSERT OR IGNORE INTO projection_pending_approvals (
+      request_id,
+      thread_id,
+      turn_id,
+      status,
+      decision,
+      created_at,
+      resolved_at
+    )
+    SELECT
+      requested.request_id,
+      requested.thread_id,
+      requested.turn_id,
+      'pending',
+      NULL,
+      requested.created_at,
+      NULL
+    FROM (
+      SELECT
+        json_extract(payload_json, '$.requestId') AS request_id,
+        thread_id,
+        turn_id,
+        created_at,
+        ROW_NUMBER() OVER (
+          PARTITION BY json_extract(payload_json, '$.requestId')
+          ORDER BY created_at ASC, activity_id ASC
+        ) AS row_number
+      FROM projection_thread_activities
+      WHERE kind = 'approval.requested'
+        AND json_extract(payload_json, '$.requestId') IS NOT NULL
+    ) AS requested
+    WHERE requested.row_number = 1
+  `;
+
+  yield* sql`
+    WITH latest_resolutions AS (
+      SELECT
+        resolved.request_id,
+        resolved.resolved_at,
+        resolved.decision
+      FROM (
+        SELECT
+          json_extract(payload_json, '$.requestId') AS request_id,
+          created_at AS resolved_at,
+          CASE
+            WHEN json_extract(payload_json, '$.decision') IN (
+              'accept',
+              'acceptForSession',
+              'decline',
+              'cancel'
+            )
+            THEN json_extract(payload_json, '$.decision')
+            ELSE NULL
+          END AS decision,
+          ROW_NUMBER() OVER (
+            PARTITION BY json_extract(payload_json, '$.requestId')
+            ORDER BY created_at DESC, activity_id DESC
+          ) AS row_number
+        FROM projection_thread_activities
+        WHERE kind = 'approval.resolved'
+          AND json_extract(payload_json, '$.requestId') IS NOT NULL
+      ) AS resolved
+      WHERE resolved.row_number = 1
+    )
+    UPDATE projection_pending_approvals
+    SET
+      status = 'resolved',
+      decision = (
+        SELECT latest_resolutions.decision
+        FROM latest_resolutions
+        WHERE latest_resolutions.request_id = projection_pending_approvals.request_id
+      ),
+      resolved_at = (
+        SELECT latest_resolutions.resolved_at
+        FROM latest_resolutions
+        WHERE latest_resolutions.request_id = projection_pending_approvals.request_id
+      )
+    WHERE EXISTS (
+      SELECT 1
+      FROM latest_resolutions
+      WHERE latest_resolutions.request_id = projection_pending_approvals.request_id
+    )
+  `;
+
+  yield* sql`
+    WITH latest_response_events AS (
+      SELECT
+        response.request_id,
+        response.resolved_at,
+        response.decision
+      FROM (
+        SELECT
+          json_extract(payload_json, '$.requestId') AS request_id,
+          occurred_at AS resolved_at,
+          CASE
+            WHEN json_extract(payload_json, '$.decision') IN (
+              'accept',
+              'acceptForSession',
+              'decline',
+              'cancel'
+            )
+            THEN json_extract(payload_json, '$.decision')
+            ELSE NULL
+          END AS decision,
+          ROW_NUMBER() OVER (
+            PARTITION BY json_extract(payload_json, '$.requestId')
+            ORDER BY occurred_at DESC, sequence DESC
+          ) AS row_number
+        FROM orchestration_events
+        WHERE event_type = 'thread.approval-response-requested'
+          AND json_extract(payload_json, '$.requestId') IS NOT NULL
+      ) AS response
+      WHERE response.row_number = 1
+    )
+    UPDATE projection_pending_approvals
+    SET
+      status = 'resolved',
+      decision = (
+        SELECT latest_response_events.decision
+        FROM latest_response_events
+        WHERE latest_response_events.request_id = projection_pending_approvals.request_id
+      ),
+      resolved_at = (
+        SELECT latest_response_events.resolved_at
+        FROM latest_response_events
+        WHERE latest_response_events.request_id = projection_pending_approvals.request_id
+      )
+    WHERE EXISTS (
+      SELECT 1
+      FROM latest_response_events
+      WHERE latest_response_events.request_id = projection_pending_approvals.request_id
+    )
+  `;
+
+  yield* sql`
+    WITH latest_stale_failures AS (
+      SELECT
+        failure.request_id,
+        failure.resolved_at
+      FROM (
+        SELECT
+          json_extract(payload_json, '$.requestId') AS request_id,
+          created_at AS resolved_at,
+          ROW_NUMBER() OVER (
+            PARTITION BY json_extract(payload_json, '$.requestId')
+            ORDER BY created_at DESC, activity_id DESC
+          ) AS row_number
+        FROM projection_thread_activities
+        WHERE kind = 'provider.approval.respond.failed'
+          AND json_extract(payload_json, '$.requestId') IS NOT NULL
+          AND (
+            lower(COALESCE(json_extract(payload_json, '$.detail'), ''))
+              LIKE '%stale pending approval request%'
+            OR lower(COALESCE(json_extract(payload_json, '$.detail'), ''))
+              LIKE '%unknown pending approval request%'
+            OR lower(COALESCE(json_extract(payload_json, '$.detail'), ''))
+              LIKE '%unknown pending permission request%'
+          )
+      ) AS failure
+      WHERE failure.row_number = 1
+    )
+    UPDATE projection_pending_approvals
+    SET
+      status = 'resolved',
+      decision = NULL,
+      resolved_at = (
+        SELECT latest_stale_failures.resolved_at
+        FROM latest_stale_failures
+        WHERE latest_stale_failures.request_id = projection_pending_approvals.request_id
+      )
+    WHERE status = 'pending'
+      AND EXISTS (
+        SELECT 1
+        FROM latest_stale_failures
+        WHERE latest_stale_failures.request_id = projection_pending_approvals.request_id
+      )
+  `;
+
+  yield* sql`
+    UPDATE projection_threads
+    SET
+      latest_user_message_at = (
+        SELECT MAX(message.created_at)
+        FROM projection_thread_messages AS message
+        WHERE message.thread_id = projection_threads.thread_id
+          AND message.role = 'user'
+      ),
+      pending_approval_count = COALESCE((
+        SELECT COUNT(*)
+        FROM projection_pending_approvals
+        WHERE projection_pending_approvals.thread_id = projection_threads.thread_id
+          AND projection_pending_approvals.status = 'pending'
+      ), 0),
+      pending_user_input_count = COALESCE((
+        WITH latest_user_input_states AS (
+          SELECT
+            latest.request_id,
+            latest.kind,
+            latest.detail
+          FROM (
+            SELECT
+              json_extract(activity.payload_json, '$.requestId') AS request_id,
+              activity.kind,
+              lower(COALESCE(json_extract(activity.payload_json, '$.detail'), '')) AS detail,
+              ROW_NUMBER() OVER (
+                PARTITION BY json_extract(activity.payload_json, '$.requestId')
+                ORDER BY activity.created_at DESC, activity.activity_id DESC
+              ) AS row_number
+            FROM projection_thread_activities AS activity
+            WHERE activity.thread_id = projection_threads.thread_id
+              AND json_extract(activity.payload_json, '$.requestId') IS NOT NULL
+              AND activity.kind IN (
+                'user-input.requested',
+                'user-input.resolved',
+                'provider.user-input.respond.failed'
+              )
+          ) AS latest
+          WHERE latest.row_number = 1
+        )
+        SELECT COUNT(*)
+        FROM latest_user_input_states
+        WHERE latest_user_input_states.kind = 'user-input.requested'
+          OR (
+            latest_user_input_states.kind = 'provider.user-input.respond.failed'
+            AND latest_user_input_states.detail NOT LIKE '%stale pending user-input request%'
+            AND latest_user_input_states.detail NOT LIKE '%unknown pending user-input request%'
+          )
+      ), 0),
+      has_actionable_proposed_plan = COALESCE((
+        SELECT CASE
+          WHEN projection_threads.latest_turn_id IS NOT NULL
+            AND EXISTS (
+              SELECT 1
+              FROM projection_thread_proposed_plans AS latest_turn_plan_exists
+              WHERE latest_turn_plan_exists.thread_id = projection_threads.thread_id
+                AND latest_turn_plan_exists.turn_id = projection_threads.latest_turn_id
+            )
+            THEN CASE
+              WHEN (
+                SELECT latest_turn_plan.implemented_at
+                FROM projection_thread_proposed_plans AS latest_turn_plan
+                WHERE latest_turn_plan.thread_id = projection_threads.thread_id
+                  AND latest_turn_plan.turn_id = projection_threads.latest_turn_id
+                ORDER BY latest_turn_plan.updated_at DESC, latest_turn_plan.plan_id DESC
+                LIMIT 1
+              ) IS NULL
+                THEN 1
+                ELSE 0
+              END
+          WHEN EXISTS (
+            SELECT 1
+            FROM projection_thread_proposed_plans AS any_plan
+            WHERE any_plan.thread_id = projection_threads.thread_id
+          )
+            THEN CASE
+              WHEN (
+                SELECT latest_plan.implemented_at
+                FROM projection_thread_proposed_plans AS latest_plan
+                WHERE latest_plan.thread_id = projection_threads.thread_id
+                ORDER BY latest_plan.updated_at DESC, latest_plan.plan_id DESC
+                LIMIT 1
+              ) IS NULL
+                THEN 1
+                ELSE 0
+              END
+          ELSE 0
+        END
+      ), 0)
+  `;
+});
diff --git a/apps/server/src/persistence/Migrations/025_CleanupInvalidProjectionPendingApprovals.test.ts b/apps/server/src/persistence/Migrations/025_CleanupInvalidProjectionPendingApprovals.test.ts
new file mode 100644
index 00000000000..752b1676efa
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/025_CleanupInvalidProjectionPendingApprovals.test.ts
@@ -0,0 +1,197 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+import { runMigrations } from "../Migrations.ts";
+import * as NodeSqliteClient from "../NodeSqliteClient.ts";
+
+const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));
+
+layer("025_CleanupInvalidProjectionPendingApprovals", (it) => {
+  it.effect("removes pending-approval rows that do not come from approval requests", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 24 });
+
+      yield* sql`
+        INSERT INTO projection_threads (
+          thread_id,
+          project_id,
+          title,
+          model_selection_json,
+          runtime_mode,
+          interaction_mode,
+          branch,
+          worktree_path,
+          latest_turn_id,
+          created_at,
+          updated_at,
+          archived_at,
+          latest_user_message_at,
+          pending_approval_count,
+          pending_user_input_count,
+          has_actionable_proposed_plan,
+          deleted_at
+        )
+        VALUES
+          (
+            'thread-valid',
+            'project-1',
+            'Valid thread',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            'approval-required',
+            'default',
+            NULL,
+            NULL,
+            'turn-valid',
+            '2026-04-13T00:00:00.000Z',
+            '2026-04-13T00:00:00.000Z',
+            NULL,
+            NULL,
+            2,
+            0,
+            0,
+            NULL
+          ),
+          (
+            'thread-invalid',
+            'project-1',
+            'Invalid thread',
+            '{"provider":"codex","model":"gpt-5-codex"}',
+            'approval-required',
+            'default',
+            NULL,
+            NULL,
+            'turn-invalid',
+            '2026-04-13T00:00:00.000Z',
+            '2026-04-13T00:00:00.000Z',
+            NULL,
+            NULL,
+            1,
+            0,
+            0,
+            NULL
+          )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_thread_activities (
+          activity_id,
+          thread_id,
+          turn_id,
+          tone,
+          kind,
+          summary,
+          payload_json,
+          sequence,
+          created_at
+        )
+        VALUES
+          (
+            'activity-approval-requested',
+            'thread-valid',
+            'turn-valid',
+            'approval',
+            'approval.requested',
+            'Command approval requested',
+            '{"requestId":"approval-valid","requestKind":"command"}',
+            NULL,
+            '2026-04-13T00:01:00.000Z'
+          ),
+          (
+            'activity-user-input-requested',
+            'thread-invalid',
+            'turn-invalid',
+            'info',
+            'user-input.requested',
+            'User input requested',
+            '{"requestId":"input-invalid","questions":[{"id":"scope","header":"Scope","question":"What should I inspect?","options":[{"label":"Server","description":"Inspect server code."}]}]}',
+            NULL,
+            '2026-04-13T00:02:00.000Z'
+          )
+      `;
+
+      yield* sql`
+        INSERT INTO projection_pending_approvals (
+          request_id,
+          thread_id,
+          turn_id,
+          status,
+          decision,
+          created_at,
+          resolved_at
+        )
+        VALUES
+          (
+            'approval-valid',
+            'thread-valid',
+            'turn-valid',
+            'pending',
+            NULL,
+            '2026-04-13T00:01:00.000Z',
+            NULL
+          ),
+          (
+            'input-invalid',
+            'thread-invalid',
+            'turn-invalid',
+            'pending',
+            NULL,
+            '2026-04-13T00:02:00.000Z',
+            NULL
+          ),
+          (
+            'input-invalid-resolved',
+            'thread-valid',
+            'turn-valid',
+            'resolved',
+            NULL,
+            '2026-04-13T00:03:00.000Z',
+            '2026-04-13T00:04:00.000Z'
+          )
+      `;
+
+      yield* runMigrations({ toMigrationInclusive: 25 });
+
+      const approvalRows = yield* sql<{
+        readonly requestId: string;
+        readonly status: string;
+      }>`
+        SELECT
+          request_id AS "requestId",
+          status
+        FROM projection_pending_approvals
+        ORDER BY request_id ASC
+      `;
+      assert.deepStrictEqual(approvalRows, [
+        {
+          requestId: "approval-valid",
+          status: "pending",
+        },
+      ]);
+
+      const threadCounts = yield* sql<{
+        readonly threadId: string;
+        readonly pendingApprovalCount: number;
+      }>`
+        SELECT
+          thread_id AS "threadId",
+          pending_approval_count AS "pendingApprovalCount"
+        FROM projection_threads
+        ORDER BY thread_id ASC
+      `;
+      assert.deepStrictEqual(threadCounts, [
+        {
+          threadId: "thread-invalid",
+          pendingApprovalCount: 0,
+        },
+        {
+          threadId: "thread-valid",
+          pendingApprovalCount: 1,
+        },
+      ]);
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/025_CleanupInvalidProjectionPendingApprovals.ts b/apps/server/src/persistence/Migrations/025_CleanupInvalidProjectionPendingApprovals.ts
new file mode 100644
index 00000000000..33a6512c750
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/025_CleanupInvalidProjectionPendingApprovals.ts
@@ -0,0 +1,27 @@
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as Effect from "effect/Effect";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  yield* sql`
+    DELETE FROM projection_pending_approvals
+    WHERE NOT EXISTS (
+      SELECT 1
+      FROM projection_thread_activities AS activity
+      WHERE activity.kind = 'approval.requested'
+        AND json_extract(activity.payload_json, '$.requestId')
+          = projection_pending_approvals.request_id
+    )
+  `;
+
+  yield* sql`
+    UPDATE projection_threads
+    SET pending_approval_count = COALESCE((
+      SELECT COUNT(*)
+      FROM projection_pending_approvals
+      WHERE projection_pending_approvals.thread_id = projection_threads.thread_id
+        AND projection_pending_approvals.status = 'pending'
+    ), 0)
+  `;
+});
diff --git a/apps/server/src/persistence/Migrations/026_CanonicalizeModelSelectionOptions.test.ts b/apps/server/src/persistence/Migrations/026_CanonicalizeModelSelectionOptions.test.ts
new file mode 100644
index 00000000000..5160b4ab34b
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/026_CanonicalizeModelSelectionOptions.test.ts
@@ -0,0 +1,451 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+import { runMigrations } from "../Migrations.ts";
+import * as NodeSqliteClient from "../NodeSqliteClient.ts";
+
+const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));
+
+layer("026_CanonicalizeModelSelectionOptions", (it) => {
+  it.effect("converts legacy object-shape options into array-shape on projections and events", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 25 });
+
+      yield* sql`
+          INSERT INTO projection_projects (
+            project_id,
+            title,
+            workspace_root,
+            default_model_selection_json,
+            scripts_json,
+            created_at,
+            updated_at,
+            deleted_at
+          )
+          VALUES
+            (
+              'project-legacy',
+              'Legacy options project',
+              '/tmp/legacy',
+              '{"provider":"claudeAgent","model":"claude-opus-4-6","options":{"effort":"max","fastMode":true}}',
+              '[]',
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL
+            ),
+            (
+              'project-no-options',
+              'No options project',
+              '/tmp/no-options',
+              '{"provider":"codex","model":"gpt-5.4"}',
+              '[]',
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL
+            ),
+            (
+              'project-null-selection',
+              'Null model selection project',
+              '/tmp/null-selection',
+              NULL,
+              '[]',
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL
+            ),
+            (
+              'project-already-array',
+              'Already-canonical options project',
+              '/tmp/already-array',
+              '{"provider":"codex","model":"gpt-5.4","options":[{"id":"reasoningEffort","value":"high"}]}',
+              '[]',
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL
+            )
+        `;
+
+      yield* sql`
+          INSERT INTO projection_threads (
+            thread_id,
+            project_id,
+            title,
+            model_selection_json,
+            branch,
+            worktree_path,
+            latest_turn_id,
+            created_at,
+            updated_at,
+            archived_at,
+            latest_user_message_at,
+            pending_approval_count,
+            pending_user_input_count,
+            has_actionable_proposed_plan,
+            deleted_at,
+            runtime_mode,
+            interaction_mode
+          )
+          VALUES
+            (
+              'thread-legacy',
+              'project-legacy',
+              'Legacy thread',
+              '{"provider":"claudeAgent","model":"claude-opus-4-6","options":{"effort":"max","thinking":false,"contextWindow":"1m"}}',
+              NULL, NULL, NULL,
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL, NULL, 0, 0, 0, NULL,
+              'full-access', 'default'
+            ),
+            (
+              'thread-empty-options',
+              'project-legacy',
+              'Empty options thread',
+              '{"provider":"codex","model":"gpt-5.4","options":{}}',
+              NULL, NULL, NULL,
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL, NULL, 0, 0, 0, NULL,
+              'full-access', 'default'
+            ),
+            (
+              'thread-drop-garbage',
+              'project-legacy',
+              'Thread with non-scalar entries',
+              '{"provider":"claudeAgent","model":"claude-opus-4-6","options":{"effort":"high","thinking":{"enabled":true,"budgetTokens":2000},"emptyStr":"   ","nullish":null}}',
+              NULL, NULL, NULL,
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL, NULL, 0, 0, 0, NULL,
+              'full-access', 'default'
+            ),
+            (
+              'thread-no-options',
+              'project-legacy',
+              'No options thread',
+              '{"provider":"codex","model":"gpt-5.4"}',
+              NULL, NULL, NULL,
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL, NULL, 0, 0, 0, NULL,
+              'full-access', 'default'
+            ),
+            (
+              'thread-already-array',
+              'project-legacy',
+              'Already array thread',
+              '{"provider":"codex","model":"gpt-5.4","options":[{"id":"fastMode","value":true}]}',
+              NULL, NULL, NULL,
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL, NULL, 0, 0, 0, NULL,
+              'full-access', 'default'
+            )
+        `;
+
+      yield* sql`
+          INSERT INTO orchestration_events (
+            event_id,
+            aggregate_kind,
+            stream_id,
+            stream_version,
+            event_type,
+            occurred_at,
+            command_id,
+            causation_event_id,
+            correlation_id,
+            actor_kind,
+            payload_json,
+            metadata_json
+          )
+          VALUES
+            (
+              'event-project-created',
+              'project',
+              'project-legacy',
+              1,
+              'project.created',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-pc',
+              NULL,
+              'corr-pc',
+              'user',
+              '{"projectId":"project-legacy","title":"Project","workspaceRoot":"/tmp/legacy","defaultModelSelection":{"provider":"claudeAgent","model":"claude-opus-4-6","options":{"effort":"max","fastMode":true}},"scripts":[],"createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z"}',
+              '{}'
+            ),
+            (
+              'event-project-meta-updated',
+              'project',
+              'project-legacy',
+              2,
+              'project.meta-updated',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-pmu',
+              NULL,
+              'corr-pmu',
+              'user',
+              '{"projectId":"project-legacy","defaultModelSelection":{"provider":"codex","model":"gpt-5.4","options":{"reasoningEffort":"low"}},"updatedAt":"2026-01-01T00:00:00.000Z"}',
+              '{}'
+            ),
+            (
+              'event-project-null-selection',
+              'project',
+              'project-legacy',
+              3,
+              'project.meta-updated',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-null',
+              NULL,
+              'corr-null',
+              'user',
+              '{"projectId":"project-legacy","defaultModelSelection":null,"updatedAt":"2026-01-01T00:00:00.000Z"}',
+              '{}'
+            ),
+            (
+              'event-thread-created',
+              'thread',
+              'thread-legacy',
+              1,
+              'thread.created',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-tc',
+              NULL,
+              'corr-tc',
+              'user',
+              '{"threadId":"thread-legacy","projectId":"project-legacy","title":"Thread","modelSelection":{"provider":"claudeAgent","model":"claude-opus-4-6","options":{"effort":"max","thinking":false}},"runtimeMode":"full-access","interactionMode":"default","branch":null,"worktreePath":null,"createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z"}',
+              '{}'
+            ),
+            (
+              'event-thread-meta-updated',
+              'thread',
+              'thread-legacy',
+              2,
+              'thread.meta-updated',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-tmu',
+              NULL,
+              'corr-tmu',
+              'user',
+              '{"threadId":"thread-legacy","modelSelection":{"provider":"codex","model":"gpt-5.4","options":{"fastMode":true}},"updatedAt":"2026-01-01T00:00:00.000Z"}',
+              '{}'
+            ),
+            (
+              'event-thread-turn-start',
+              'thread',
+              'thread-legacy',
+              3,
+              'thread.turn-start-requested',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-tts',
+              NULL,
+              'corr-tts',
+              'user',
+              '{"threadId":"thread-legacy","messageId":"msg-1","modelSelection":{"provider":"claudeAgent","model":"claude-opus-4-6","options":{"effort":"high","contextWindow":"1m"}},"runtimeMode":"full-access","interactionMode":"default","createdAt":"2026-01-01T00:00:00.000Z"}',
+              '{}'
+            ),
+            (
+              'event-thread-already-array',
+              'thread',
+              'thread-legacy',
+              4,
+              'thread.created',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-taa',
+              NULL,
+              'corr-taa',
+              'user',
+              '{"threadId":"thread-already-array","projectId":"project-legacy","title":"Already Array","modelSelection":{"provider":"codex","model":"gpt-5.4","options":[{"id":"reasoningEffort","value":"medium"}]},"runtimeMode":"full-access","interactionMode":"default","branch":null,"worktreePath":null,"createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z"}',
+              '{}'
+            ),
+            (
+              'event-activity-append',
+              'thread',
+              'thread-legacy',
+              5,
+              'thread.activity-appended',
+              '2026-01-01T00:00:00.000Z',
+              'cmd-aa',
+              NULL,
+              'corr-aa',
+              'user',
+              '{"threadId":"thread-legacy","activity":{"id":"a","tone":"info","kind":"k","summary":"s","payload":null,"turnId":null,"createdAt":"2026-01-01T00:00:00.000Z"}}',
+              '{}'
+            )
+        `;
+
+      yield* runMigrations({ toMigrationInclusive: 26 });
+
+      // Projection projects
+      const projectRows = yield* sql<{
+        readonly projectId: string;
+        readonly defaultModelSelection: string | null;
+      }>`
+          SELECT
+            project_id AS "projectId",
+            default_model_selection_json AS "defaultModelSelection"
+          FROM projection_projects
+          ORDER BY project_id
+        `;
+      assert.deepStrictEqual(
+        projectRows.map((row) => ({
+          projectId: row.projectId,
+          selection: row.defaultModelSelection ? JSON.parse(row.defaultModelSelection) : null,
+        })),
+        [
+          {
+            projectId: "project-already-array",
+            selection: {
+              provider: "codex",
+              model: "gpt-5.4",
+              options: [{ id: "reasoningEffort", value: "high" }],
+            },
+          },
+          {
+            projectId: "project-legacy",
+            selection: {
+              provider: "claudeAgent",
+              model: "claude-opus-4-6",
+              options: [
+                { id: "effort", value: "max" },
+                { id: "fastMode", value: true },
+              ],
+            },
+          },
+          {
+            projectId: "project-no-options",
+            selection: { provider: "codex", model: "gpt-5.4" },
+          },
+          { projectId: "project-null-selection", selection: null },
+        ],
+      );
+
+      // Projection threads
+      const threadRows = yield* sql<{
+        readonly threadId: string;
+        readonly modelSelection: string | null;
+      }>`
+          SELECT
+            thread_id AS "threadId",
+            model_selection_json AS "modelSelection"
+          FROM projection_threads
+          ORDER BY thread_id
+        `;
+      assert.deepStrictEqual(
+        threadRows.map((row) => ({
+          threadId: row.threadId,
+          selection: row.modelSelection ? JSON.parse(row.modelSelection) : null,
+        })),
+        [
+          {
+            threadId: "thread-already-array",
+            selection: {
+              provider: "codex",
+              model: "gpt-5.4",
+              options: [{ id: "fastMode", value: true }],
+            },
+          },
+          {
+            threadId: "thread-drop-garbage",
+            selection: {
+              provider: "claudeAgent",
+              model: "claude-opus-4-6",
+              // Only the scalar string survives; nested object, whitespace
+              // string, and null are dropped.
+              options: [{ id: "effort", value: "high" }],
+            },
+          },
+          {
+            threadId: "thread-empty-options",
+            selection: { provider: "codex", model: "gpt-5.4", options: [] },
+          },
+          {
+            threadId: "thread-legacy",
+            selection: {
+              provider: "claudeAgent",
+              model: "claude-opus-4-6",
+              options: [
+                { id: "effort", value: "max" },
+                { id: "thinking", value: false },
+                { id: "contextWindow", value: "1m" },
+              ],
+            },
+          },
+          {
+            threadId: "thread-no-options",
+            selection: { provider: "codex", model: "gpt-5.4" },
+          },
+        ],
+      );
+
+      // Orchestration events
+      const eventRows = yield* sql<{
+        readonly eventId: string;
+        readonly payloadJson: string;
+      }>`
+          SELECT event_id AS "eventId", payload_json AS "payloadJson"
+          FROM orchestration_events
+          ORDER BY event_id
+        `;
+
+      const payloads = Object.fromEntries(
+        eventRows.map((row) => [row.eventId, JSON.parse(row.payloadJson)]),
+      );
+
+      assert.deepStrictEqual(payloads["event-project-created"].defaultModelSelection, {
+        provider: "claudeAgent",
+        model: "claude-opus-4-6",
+        options: [
+          { id: "effort", value: "max" },
+          { id: "fastMode", value: true },
+        ],
+      });
+
+      assert.deepStrictEqual(payloads["event-project-meta-updated"].defaultModelSelection, {
+        provider: "codex",
+        model: "gpt-5.4",
+        options: [{ id: "reasoningEffort", value: "low" }],
+      });
+
+      assert.strictEqual(payloads["event-project-null-selection"].defaultModelSelection, null);
+
+      assert.deepStrictEqual(payloads["event-thread-created"].modelSelection, {
+        provider: "claudeAgent",
+        model: "claude-opus-4-6",
+        options: [
+          { id: "effort", value: "max" },
+          { id: "thinking", value: false },
+        ],
+      });
+
+      assert.deepStrictEqual(payloads["event-thread-meta-updated"].modelSelection, {
+        provider: "codex",
+        model: "gpt-5.4",
+        options: [{ id: "fastMode", value: true }],
+      });
+
+      assert.deepStrictEqual(payloads["event-thread-turn-start"].modelSelection, {
+        provider: "claudeAgent",
+        model: "claude-opus-4-6",
+        options: [
+          { id: "effort", value: "high" },
+          { id: "contextWindow", value: "1m" },
+        ],
+      });
+
+      // Already-array records are left untouched.
+      assert.deepStrictEqual(payloads["event-thread-already-array"].modelSelection, {
+        provider: "codex",
+        model: "gpt-5.4",
+        options: [{ id: "reasoningEffort", value: "medium" }],
+      });
+
+      // Events with no modelSelection at all are untouched.
+      assert.isUndefined(payloads["event-activity-append"].modelSelection);
+      assert.isUndefined(payloads["event-activity-append"].defaultModelSelection);
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/026_CanonicalizeModelSelectionOptions.ts b/apps/server/src/persistence/Migrations/026_CanonicalizeModelSelectionOptions.ts
new file mode 100644
index 00000000000..15c08debf64
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/026_CanonicalizeModelSelectionOptions.ts
@@ -0,0 +1,138 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+/**
+ * Canonicalize `modelSelection.options` / `defaultModelSelection.options` from
+ * the legacy object shape (`{ effort: "max", fastMode: true, ... }`) to the
+ * current array-of-selections shape (`[{ id: "effort", value: "max" }, ...]`).
+ *
+ * Migration 016 introduced `modelSelection` with `options` stored as a
+ * per-provider object. Later the schema was reshaped so that options are a
+ * generic `Array<{ id, value }>` of user-selected option entries. Stored rows
+ * from before the reshape still have the object shape and fail to decode.
+ *
+ * For each value in the legacy object:
+ *   - string values are kept if non-empty after trim
+ *   - boolean values are always kept (true | false)
+ *   - any other value type (number, null, nested object/array) is dropped,
+ *     matching the permissive client-side normalizer in composerDraftStore.
+ *
+ * Touched storage:
+ *   - `projection_threads.model_selection_json.options`
+ *   - `projection_projects.default_model_selection_json.options`
+ *   - `orchestration_events.payload_json.$.modelSelection.options`
+ *     (thread.created | thread.meta-updated | thread.turn-start-requested)
+ *   - `orchestration_events.payload_json.$.defaultModelSelection.options`
+ *     (project.created | project.meta-updated)
+ */
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  yield* sql`
+    UPDATE projection_threads
+    SET model_selection_json = json_set(
+      model_selection_json,
+      '$.options',
+      (
+        SELECT json_group_array(
+          json_object(
+            'id', key,
+            'value',
+            CASE type
+              WHEN 'true' THEN json('true')
+              WHEN 'false' THEN json('false')
+              ELSE atom
+            END
+          )
+        )
+        FROM json_each(json_extract(model_selection_json, '$.options'))
+        WHERE (type = 'text' AND trim(coalesce(atom, '')) != '')
+           OR type IN ('true', 'false')
+      )
+    )
+    WHERE model_selection_json IS NOT NULL
+      AND json_type(model_selection_json, '$.options') = 'object'
+  `;
+
+  yield* sql`
+    UPDATE projection_projects
+    SET default_model_selection_json = json_set(
+      default_model_selection_json,
+      '$.options',
+      (
+        SELECT json_group_array(
+          json_object(
+            'id', key,
+            'value',
+            CASE type
+              WHEN 'true' THEN json('true')
+              WHEN 'false' THEN json('false')
+              ELSE atom
+            END
+          )
+        )
+        FROM json_each(json_extract(default_model_selection_json, '$.options'))
+        WHERE (type = 'text' AND trim(coalesce(atom, '')) != '')
+           OR type IN ('true', 'false')
+      )
+    )
+    WHERE default_model_selection_json IS NOT NULL
+      AND json_type(default_model_selection_json, '$.options') = 'object'
+  `;
+
+  yield* sql`
+    UPDATE orchestration_events
+    SET payload_json = json_set(
+      payload_json,
+      '$.modelSelection.options',
+      (
+        SELECT json_group_array(
+          json_object(
+            'id', key,
+            'value',
+            CASE type
+              WHEN 'true' THEN json('true')
+              WHEN 'false' THEN json('false')
+              ELSE atom
+            END
+          )
+        )
+        FROM json_each(json_extract(payload_json, '$.modelSelection.options'))
+        WHERE (type = 'text' AND trim(coalesce(atom, '')) != '')
+           OR type IN ('true', 'false')
+      )
+    )
+    WHERE event_type IN (
+      'thread.created',
+      'thread.meta-updated',
+      'thread.turn-start-requested'
+    )
+      AND json_type(payload_json, '$.modelSelection.options') = 'object'
+  `;
+
+  yield* sql`
+    UPDATE orchestration_events
+    SET payload_json = json_set(
+      payload_json,
+      '$.defaultModelSelection.options',
+      (
+        SELECT json_group_array(
+          json_object(
+            'id', key,
+            'value',
+            CASE type
+              WHEN 'true' THEN json('true')
+              WHEN 'false' THEN json('false')
+              ELSE atom
+            END
+          )
+        )
+        FROM json_each(json_extract(payload_json, '$.defaultModelSelection.options'))
+        WHERE (type = 'text' AND trim(coalesce(atom, '')) != '')
+           OR type IN ('true', 'false')
+      )
+    )
+    WHERE event_type IN ('project.created', 'project.meta-updated')
+      AND json_type(payload_json, '$.defaultModelSelection.options') = 'object'
+  `;
+});
diff --git a/apps/server/src/persistence/Migrations/027_028_ProviderInstanceIdColumns.test.ts b/apps/server/src/persistence/Migrations/027_028_ProviderInstanceIdColumns.test.ts
new file mode 100644
index 00000000000..5c0d7e2a7a8
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/027_028_ProviderInstanceIdColumns.test.ts
@@ -0,0 +1,75 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+import { runMigrations } from "../Migrations.ts";
+import * as NodeSqliteClient from "../NodeSqliteClient.ts";
+
+const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));
+
+layer("027_028_ProviderInstanceIdColumns", (it) => {
+  it.effect("continues when provider_session_runtime was partially migrated", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 26 });
+      yield* sql`
+        ALTER TABLE provider_session_runtime
+        ADD COLUMN provider_instance_id TEXT
+      `;
+
+      yield* runMigrations({ toMigrationInclusive: 28 });
+
+      const migrations = yield* sql<{
+        readonly migration_id: number;
+        readonly name: string;
+      }>`
+        SELECT migration_id, name
+        FROM effect_sql_migrations
+        WHERE migration_id IN (27, 28)
+        ORDER BY migration_id
+      `;
+      assert.deepStrictEqual(migrations, [
+        {
+          migration_id: 27,
+          name: "ProviderSessionRuntimeInstanceId",
+        },
+        {
+          migration_id: 28,
+          name: "ProjectionThreadSessionInstanceId",
+        },
+      ]);
+
+      const providerSessionColumns = yield* sql<{ readonly name: string }>`
+        PRAGMA table_info(provider_session_runtime)
+      `;
+      assert.ok(providerSessionColumns.some((column) => column.name === "provider_instance_id"));
+
+      const projectionThreadSessionColumns = yield* sql<{ readonly name: string }>`
+        PRAGMA table_info(projection_thread_sessions)
+      `;
+      assert.ok(
+        projectionThreadSessionColumns.some((column) => column.name === "provider_instance_id"),
+      );
+
+      const providerSessionIndexes = yield* sql<{ readonly name: string }>`
+        PRAGMA index_list(provider_session_runtime)
+      `;
+      assert.ok(
+        providerSessionIndexes.some(
+          (index) => index.name === "idx_provider_session_runtime_instance",
+        ),
+      );
+
+      const projectionThreadSessionIndexes = yield* sql<{ readonly name: string }>`
+        PRAGMA index_list(projection_thread_sessions)
+      `;
+      assert.ok(
+        projectionThreadSessionIndexes.some(
+          (index) => index.name === "idx_projection_thread_sessions_instance",
+        ),
+      );
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/027_ProviderSessionRuntimeInstanceId.ts b/apps/server/src/persistence/Migrations/027_ProviderSessionRuntimeInstanceId.ts
new file mode 100644
index 00000000000..7ae0e55b13c
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/027_ProviderSessionRuntimeInstanceId.ts
@@ -0,0 +1,38 @@
+/**
+ * Adds the nullable `provider_instance_id` routing column to
+ * `provider_session_runtime`.
+ *
+ * Slice D of the provider-array refactor splits "driver kind" from
+ * "configured instance". Existing rows have only the driver name in
+ * `provider_name`; new rows additionally carry the user-defined instance
+ * routing key. The column remains nullable so legacy rows can still decode;
+ * the persistence boundary is responsible for materializing a concrete
+ * instance id before any hot routing path sees the binding.
+ *
+ * The column is nullable on purpose — backfilling it during the migration
+ * would require knowing which configured instance "owned" each historical
+ * session, and that mapping is ambiguous when the user later configures
+ * multiple instances of the same driver. Keeping that compatibility at the
+ * persistence boundary keeps the fallback out of active routing code.
+ */
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as Effect from "effect/Effect";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  const columns = yield* sql<{ readonly name: string }>`
+    PRAGMA table_info(provider_session_runtime)
+  `;
+  if (!columns.some((column) => column.name === "provider_instance_id")) {
+    yield* sql`
+      ALTER TABLE provider_session_runtime
+      ADD COLUMN provider_instance_id TEXT
+    `;
+  }
+
+  yield* sql`
+    CREATE INDEX IF NOT EXISTS idx_provider_session_runtime_instance
+    ON provider_session_runtime(provider_instance_id)
+  `;
+});
diff --git a/apps/server/src/persistence/Migrations/028_ProjectionThreadSessionInstanceId.ts b/apps/server/src/persistence/Migrations/028_ProjectionThreadSessionInstanceId.ts
new file mode 100644
index 00000000000..bc4ba98044f
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/028_ProjectionThreadSessionInstanceId.ts
@@ -0,0 +1,21 @@
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import * as Effect from "effect/Effect";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  const columns = yield* sql<{ readonly name: string }>`
+    PRAGMA table_info(projection_thread_sessions)
+  `;
+  if (!columns.some((column) => column.name === "provider_instance_id")) {
+    yield* sql`
+      ALTER TABLE projection_thread_sessions
+      ADD COLUMN provider_instance_id TEXT
+    `;
+  }
+
+  yield* sql`
+    CREATE INDEX IF NOT EXISTS idx_projection_thread_sessions_instance
+    ON projection_thread_sessions(provider_instance_id)
+  `;
+});
diff --git a/apps/server/src/persistence/Migrations/029_ProjectionThreadDetailOrderingIndexes.test.ts b/apps/server/src/persistence/Migrations/029_ProjectionThreadDetailOrderingIndexes.test.ts
new file mode 100644
index 00000000000..4b0aa186cb4
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/029_ProjectionThreadDetailOrderingIndexes.test.ts
@@ -0,0 +1,74 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+import { runMigrations } from "../Migrations.ts";
+import * as NodeSqliteClient from "../NodeSqliteClient.ts";
+
+const layer = it.layer(Layer.mergeAll(NodeSqliteClient.layerMemory()));
+
+layer("029_ProjectionThreadDetailOrderingIndexes", (it) => {
+  it.effect("creates indexes matching thread detail ordering queries", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 28 });
+      yield* runMigrations({ toMigrationInclusive: 29 });
+
+      const activityIndexes = yield* sql<{
+        readonly seq: number;
+        readonly name: string;
+        readonly unique: number;
+        readonly origin: string;
+        readonly partial: number;
+      }>`
+        PRAGMA index_list(projection_thread_activities)
+      `;
+      assert.ok(
+        activityIndexes.some(
+          (index) => index.name === "idx_projection_thread_activities_thread_sequence_created_id",
+        ),
+      );
+
+      const activityIndexColumns = yield* sql<{
+        readonly seqno: number;
+        readonly cid: number;
+        readonly name: string;
+      }>`
+        PRAGMA index_info('idx_projection_thread_activities_thread_sequence_created_id')
+      `;
+      assert.deepStrictEqual(
+        activityIndexColumns.map((column) => column.name),
+        ["thread_id", "sequence", "created_at", "activity_id"],
+      );
+
+      const messageIndexes = yield* sql<{
+        readonly seq: number;
+        readonly name: string;
+        readonly unique: number;
+        readonly origin: string;
+        readonly partial: number;
+      }>`
+        PRAGMA index_list(projection_thread_messages)
+      `;
+      assert.ok(
+        messageIndexes.some(
+          (index) => index.name === "idx_projection_thread_messages_thread_created_id",
+        ),
+      );
+
+      const messageIndexColumns = yield* sql<{
+        readonly seqno: number;
+        readonly cid: number;
+        readonly name: string;
+      }>`
+        PRAGMA index_info('idx_projection_thread_messages_thread_created_id')
+      `;
+      assert.deepStrictEqual(
+        messageIndexColumns.map((column) => column.name),
+        ["thread_id", "created_at", "message_id"],
+      );
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/029_ProjectionThreadDetailOrderingIndexes.ts b/apps/server/src/persistence/Migrations/029_ProjectionThreadDetailOrderingIndexes.ts
new file mode 100644
index 00000000000..4a0595afa9b
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/029_ProjectionThreadDetailOrderingIndexes.ts
@@ -0,0 +1,16 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  yield* sql`
+    CREATE INDEX IF NOT EXISTS idx_projection_thread_activities_thread_sequence_created_id
+    ON projection_thread_activities(thread_id, sequence, created_at, activity_id)
+  `;
+
+  yield* sql`
+    CREATE INDEX IF NOT EXISTS idx_projection_thread_messages_thread_created_id
+    ON projection_thread_messages(thread_id, created_at, message_id)
+  `;
+});
diff --git a/apps/server/src/persistence/Migrations/030_ProjectionThreadShellArchiveIndexes.ts b/apps/server/src/persistence/Migrations/030_ProjectionThreadShellArchiveIndexes.ts
new file mode 100644
index 00000000000..3b7bf51f04b
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/030_ProjectionThreadShellArchiveIndexes.ts
@@ -0,0 +1,16 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  yield* sql`
+    CREATE INDEX IF NOT EXISTS idx_projection_threads_shell_active
+    ON projection_threads(deleted_at, archived_at, project_id, created_at, thread_id)
+  `;
+
+  yield* sql`
+    CREATE INDEX IF NOT EXISTS idx_projection_threads_shell_archived
+    ON projection_threads(deleted_at, archived_at, project_id, thread_id)
+  `;
+});
diff --git a/apps/server/src/persistence/NodeSqliteClient.test.ts b/apps/server/src/persistence/NodeSqliteClient.test.ts
index a055d409ba2..43023abf60a 100644
--- a/apps/server/src/persistence/NodeSqliteClient.test.ts
+++ b/apps/server/src/persistence/NodeSqliteClient.test.ts
@@ -1,5 +1,5 @@
 import { assert, it } from "@effect/vitest";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import * as SqliteClient from "./NodeSqliteClient.ts";
diff --git a/apps/server/src/persistence/Services/AuthPairingLinks.ts b/apps/server/src/persistence/Services/AuthPairingLinks.ts
index d03e67cbb5b..c81ce51a3f4 100644
--- a/apps/server/src/persistence/Services/AuthPairingLinks.ts
+++ b/apps/server/src/persistence/Services/AuthPairingLinks.ts
@@ -1,5 +1,7 @@
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { AuthPairingLinkRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/AuthSessions.ts b/apps/server/src/persistence/Services/AuthSessions.ts
index 567d3cca5c1..a92573f9f9e 100644
--- a/apps/server/src/persistence/Services/AuthSessions.ts
+++ b/apps/server/src/persistence/Services/AuthSessions.ts
@@ -1,6 +1,8 @@
 import { AuthClientMetadataDeviceType, AuthSessionId } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { AuthSessionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts b/apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts
index da8755ae71c..1498984827e 100644
--- a/apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts
+++ b/apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts
@@ -15,8 +15,10 @@ import {
   ProjectId,
   ThreadId,
 } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { OrchestrationCommandReceiptRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/OrchestrationEventStore.ts b/apps/server/src/persistence/Services/OrchestrationEventStore.ts
index beecdcdc656..8b465e7713e 100644
--- a/apps/server/src/persistence/Services/OrchestrationEventStore.ts
+++ b/apps/server/src/persistence/Services/OrchestrationEventStore.ts
@@ -10,8 +10,9 @@
  * @module OrchestrationEventStore
  */
 import { OrchestrationEvent } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect, Stream } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
 import type { OrchestrationEventStoreError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionCheckpoints.ts b/apps/server/src/persistence/Services/ProjectionCheckpoints.ts
index 617f964f333..7796ebec2a8 100644
--- a/apps/server/src/persistence/Services/ProjectionCheckpoints.ts
+++ b/apps/server/src/persistence/Services/ProjectionCheckpoints.ts
@@ -16,8 +16,10 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Option, Context, Schema } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts b/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts
index 82c43c0bb03..967e6da9d3a 100644
--- a/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts
+++ b/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts
@@ -14,8 +14,10 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionProjects.ts b/apps/server/src/persistence/Services/ProjectionProjects.ts
index 0970bb2ead4..5632205a269 100644
--- a/apps/server/src/persistence/Services/ProjectionProjects.ts
+++ b/apps/server/src/persistence/Services/ProjectionProjects.ts
@@ -7,8 +7,10 @@
  * @module ProjectionProjectRepository
  */
 import { IsoDateTime, ModelSelection, ProjectId, ProjectScript } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionState.ts b/apps/server/src/persistence/Services/ProjectionState.ts
index 0b75b817d25..ba1ca151736 100644
--- a/apps/server/src/persistence/Services/ProjectionState.ts
+++ b/apps/server/src/persistence/Services/ProjectionState.ts
@@ -7,8 +7,10 @@
  * @module ProjectionStateRepository
  */
 import { IsoDateTime, NonNegativeInt } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionThreadActivities.ts b/apps/server/src/persistence/Services/ProjectionThreadActivities.ts
index 87daa3c636b..47cb6073c47 100644
--- a/apps/server/src/persistence/Services/ProjectionThreadActivities.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreadActivities.ts
@@ -14,8 +14,9 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionThreadMessages.ts b/apps/server/src/persistence/Services/ProjectionThreadMessages.ts
index 56f8f92dbfe..d50ff320256 100644
--- a/apps/server/src/persistence/Services/ProjectionThreadMessages.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreadMessages.ts
@@ -14,9 +14,10 @@ import {
   TurnId,
   IsoDateTime,
 } from "@t3tools/contracts";
-import { Schema, Context } from "effect";
-import type { Option } from "effect";
-import type { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Option from "effect/Option";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionThreadProposedPlans.ts b/apps/server/src/persistence/Services/ProjectionThreadProposedPlans.ts
index a68bedb8c37..b4bc2bcc328 100644
--- a/apps/server/src/persistence/Services/ProjectionThreadProposedPlans.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreadProposedPlans.ts
@@ -5,8 +5,9 @@ import {
   TrimmedNonEmptyString,
   TurnId,
 } from "@t3tools/contracts";
-import { Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProjectionThreadSessions.ts b/apps/server/src/persistence/Services/ProjectionThreadSessions.ts
index fcd13f068da..7cecac33eb6 100644
--- a/apps/server/src/persistence/Services/ProjectionThreadSessions.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreadSessions.ts
@@ -10,11 +10,14 @@ import {
   RuntimeMode,
   IsoDateTime,
   OrchestrationSessionStatus,
+  ProviderInstanceId,
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
@@ -22,6 +25,7 @@ export const ProjectionThreadSession = Schema.Struct({
   threadId: ThreadId,
   status: OrchestrationSessionStatus,
   providerName: Schema.NullOr(Schema.String),
+  providerInstanceId: Schema.NullOr(ProviderInstanceId),
   runtimeMode: RuntimeMode,
   activeTurnId: Schema.NullOr(TurnId),
   lastError: Schema.NullOr(Schema.String),
diff --git a/apps/server/src/persistence/Services/ProjectionThreads.ts b/apps/server/src/persistence/Services/ProjectionThreads.ts
index 31ec00a6e5e..44fdc147a4a 100644
--- a/apps/server/src/persistence/Services/ProjectionThreads.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreads.ts
@@ -9,14 +9,17 @@
 import {
   IsoDateTime,
   ModelSelection,
+  NonNegativeInt,
   ProjectId,
   ProviderInteractionMode,
   RuntimeMode,
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
@@ -33,6 +36,10 @@ export const ProjectionThread = Schema.Struct({
   createdAt: IsoDateTime,
   updatedAt: IsoDateTime,
   archivedAt: Schema.NullOr(IsoDateTime),
+  latestUserMessageAt: Schema.NullOr(IsoDateTime),
+  pendingApprovalCount: NonNegativeInt,
+  pendingUserInputCount: NonNegativeInt,
+  hasActionableProposedPlan: NonNegativeInt,
   deletedAt: Schema.NullOr(IsoDateTime),
 });
 export type ProjectionThread = typeof ProjectionThread.Type;
diff --git a/apps/server/src/persistence/Services/ProjectionTurns.ts b/apps/server/src/persistence/Services/ProjectionTurns.ts
index 8e37ae09bd9..f3d5d5e4706 100644
--- a/apps/server/src/persistence/Services/ProjectionTurns.ts
+++ b/apps/server/src/persistence/Services/ProjectionTurns.ts
@@ -17,8 +17,10 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectionRepositoryError } from "../Errors.ts";
 
diff --git a/apps/server/src/persistence/Services/ProviderSessionRuntime.ts b/apps/server/src/persistence/Services/ProviderSessionRuntime.ts
index bf8e658e8a6..125f4fa5bbf 100644
--- a/apps/server/src/persistence/Services/ProviderSessionRuntime.ts
+++ b/apps/server/src/persistence/Services/ProviderSessionRuntime.ts
@@ -7,18 +7,29 @@
  */
 import {
   IsoDateTime,
+  ProviderInstanceId,
   ProviderSessionRuntimeStatus,
   RuntimeMode,
   ThreadId,
 } from "@t3tools/contracts";
-import { Option, Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProviderSessionRuntimeRepositoryError } from "../Errors.ts";
 
 export const ProviderSessionRuntime = Schema.Struct({
   threadId: ThreadId,
   providerName: Schema.String,
+  /**
+   * User-defined routing key for the configured provider instance that
+   * owns this session. Nullable only at the storage/migration boundary:
+   * rows persisted before the driver/instance split carry only
+   * `providerName`. Repository consumers must materialize a concrete
+   * instance id before routing.
+   */
+  providerInstanceId: Schema.NullOr(ProviderInstanceId),
   adapterKey: Schema.String,
   runtimeMode: RuntimeMode,
   status: ProviderSessionRuntimeStatus,
diff --git a/apps/server/src/process/externalLauncher.test.ts b/apps/server/src/process/externalLauncher.test.ts
new file mode 100644
index 00000000000..151600c47d9
--- /dev/null
+++ b/apps/server/src/process/externalLauncher.test.ts
@@ -0,0 +1,802 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import { assertSuccess } from "@effect/vitest/utils";
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Random from "effect/Random";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  isCommandAvailable,
+  launchBrowser,
+  launchEditorProcess,
+  resolveAvailableEditors,
+  resolveBrowserLaunch,
+  resolveEditorLaunch,
+} from "./externalLauncher.ts";
+
+function encodeUtf16LeBase64(input: string): string {
+  const bytes = new Uint8Array(input.length * 2);
+  for (let index = 0; index < input.length; index += 1) {
+    const code = input.charCodeAt(index);
+    bytes[index * 2] = code & 0xff;
+    bytes[index * 2 + 1] = code >>> 8;
+  }
+  return Encoding.encodeBase64(bytes);
+}
+
+function makeMockDetachedHandle(onUnref: () => void = () => undefined) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+    isRunning: Effect.succeed(true),
+    kill: () => Effect.void,
+    unref: Effect.sync(() => {
+      onUnref();
+      return Effect.void;
+    }),
+    stdin: Sink.drain,
+    stdout: Stream.empty,
+    stderr: Stream.empty,
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+it.layer(NodeServices.layer)("resolveEditorLaunch", (it) => {
+  it.effect("returns commands for command-based editors", () =>
+    Effect.gen(function* () {
+      const antigravityLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "antigravity" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(antigravityLaunch, {
+        command: "agy",
+        args: ["/tmp/workspace"],
+      });
+
+      const cursorLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "cursor" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(cursorLaunch, {
+        command: "cursor",
+        args: ["/tmp/workspace"],
+      });
+
+      const traeLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "trae" },
+        "darwin",
+      );
+      assert.deepEqual(traeLaunch, {
+        command: "trae",
+        args: ["/tmp/workspace"],
+      });
+
+      const kiroLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "kiro" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(kiroLaunch, {
+        command: "kiro",
+        args: ["ide", "/tmp/workspace"],
+      });
+
+      const vscodeLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "vscode" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(vscodeLaunch, {
+        command: "code",
+        args: ["/tmp/workspace"],
+      });
+
+      const vscodeInsidersLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "vscode-insiders" },
+        "darwin",
+      );
+      assert.deepEqual(vscodeInsidersLaunch, {
+        command: "code-insiders",
+        args: ["/tmp/workspace"],
+      });
+
+      const vscodiumLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "vscodium" },
+        "darwin",
+      );
+      assert.deepEqual(vscodiumLaunch, {
+        command: "codium",
+        args: ["/tmp/workspace"],
+      });
+
+      const zedLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "zed" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(zedLaunch, {
+        command: "zed",
+        args: ["/tmp/workspace"],
+      });
+
+      const ideaLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "idea" },
+        "darwin",
+      );
+      assert.deepEqual(ideaLaunch, {
+        command: "idea",
+        args: ["/tmp/workspace"],
+      });
+
+      const aquaLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "aqua" },
+        "darwin",
+      );
+      assert.deepEqual(aquaLaunch, {
+        command: "aqua",
+        args: ["/tmp/workspace"],
+      });
+
+      const clionLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "clion" },
+        "darwin",
+      );
+      assert.deepEqual(clionLaunch, {
+        command: "clion",
+        args: ["/tmp/workspace"],
+      });
+
+      const datagripLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "datagrip" },
+        "darwin",
+      );
+      assert.deepEqual(datagripLaunch, {
+        command: "datagrip",
+        args: ["/tmp/workspace"],
+      });
+
+      const dataspellLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "dataspell" },
+        "darwin",
+      );
+      assert.deepEqual(dataspellLaunch, {
+        command: "dataspell",
+        args: ["/tmp/workspace"],
+      });
+
+      const golandLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "goland" },
+        "darwin",
+      );
+      assert.deepEqual(golandLaunch, {
+        command: "goland",
+        args: ["/tmp/workspace"],
+      });
+
+      const phpstormLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "phpstorm" },
+        "darwin",
+      );
+      assert.deepEqual(phpstormLaunch, {
+        command: "phpstorm",
+        args: ["/tmp/workspace"],
+      });
+
+      const pycharmLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "pycharm" },
+        "darwin",
+      );
+      assert.deepEqual(pycharmLaunch, {
+        command: "pycharm",
+        args: ["/tmp/workspace"],
+      });
+
+      const riderLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "rider" },
+        "darwin",
+      );
+      assert.deepEqual(riderLaunch, {
+        command: "rider",
+        args: ["/tmp/workspace"],
+      });
+
+      const rubymineLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "rubymine" },
+        "darwin",
+      );
+      assert.deepEqual(rubymineLaunch, {
+        command: "rubymine",
+        args: ["/tmp/workspace"],
+      });
+
+      const rustroverLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "rustrover" },
+        "darwin",
+      );
+      assert.deepEqual(rustroverLaunch, {
+        command: "rustrover",
+        args: ["/tmp/workspace"],
+      });
+
+      const webstormLaunch = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "webstorm" },
+        "darwin",
+      );
+      assert.deepEqual(webstormLaunch, {
+        command: "webstorm",
+        args: ["/tmp/workspace"],
+      });
+    }),
+  );
+
+  it.effect("applies launch-style-specific navigation arguments", () =>
+    Effect.gen(function* () {
+      const lineOnly = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/AGENTS.md:48", editor: "cursor" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(lineOnly, {
+        command: "cursor",
+        args: ["--goto", "/tmp/workspace/AGENTS.md:48"],
+      });
+
+      const lineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "cursor" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(lineAndColumn, {
+        command: "cursor",
+        args: ["--goto", "/tmp/workspace/src/process/externalLauncher.ts:71:5"],
+      });
+
+      const traeLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "trae" },
+        "darwin",
+      );
+      assert.deepEqual(traeLineAndColumn, {
+        command: "trae",
+        args: ["--goto", "/tmp/workspace/src/process/externalLauncher.ts:71:5"],
+      });
+
+      const kiroLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "kiro" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(kiroLineAndColumn, {
+        command: "kiro",
+        args: ["ide", "--goto", "/tmp/workspace/src/process/externalLauncher.ts:71:5"],
+      });
+
+      const vscodeLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "vscode" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(vscodeLineAndColumn, {
+        command: "code",
+        args: ["--goto", "/tmp/workspace/src/process/externalLauncher.ts:71:5"],
+      });
+
+      const vscodeInsidersLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "vscode-insiders" },
+        "darwin",
+      );
+      assert.deepEqual(vscodeInsidersLineAndColumn, {
+        command: "code-insiders",
+        args: ["--goto", "/tmp/workspace/src/process/externalLauncher.ts:71:5"],
+      });
+
+      const vscodiumLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "vscodium" },
+        "darwin",
+      );
+      assert.deepEqual(vscodiumLineAndColumn, {
+        command: "codium",
+        args: ["--goto", "/tmp/workspace/src/process/externalLauncher.ts:71:5"],
+      });
+
+      const zedLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "zed" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(zedLineAndColumn, {
+        command: "zed",
+        args: ["/tmp/workspace/src/process/externalLauncher.ts:71:5"],
+      });
+
+      const zedLineOnly = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/AGENTS.md:48", editor: "zed" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(zedLineOnly, {
+        command: "zed",
+        args: ["/tmp/workspace/AGENTS.md:48"],
+      });
+
+      const ideaLineOnly = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/AGENTS.md:48", editor: "idea" },
+        "darwin",
+      );
+      assert.deepEqual(ideaLineOnly, {
+        command: "idea",
+        args: ["--line", "48", "/tmp/workspace/AGENTS.md"],
+      });
+
+      const ideaLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "idea" },
+        "darwin",
+      );
+      assert.deepEqual(ideaLineAndColumn, {
+        command: "idea",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const aquaLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "aqua" },
+        "darwin",
+      );
+      assert.deepEqual(aquaLineAndColumn, {
+        command: "aqua",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const clionLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "clion" },
+        "darwin",
+      );
+      assert.deepEqual(clionLineAndColumn, {
+        command: "clion",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const datagripLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "datagrip" },
+        "darwin",
+      );
+      assert.deepEqual(datagripLineAndColumn, {
+        command: "datagrip",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const dataspellLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "dataspell" },
+        "darwin",
+      );
+      assert.deepEqual(dataspellLineAndColumn, {
+        command: "dataspell",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const golandLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "goland" },
+        "darwin",
+      );
+      assert.deepEqual(golandLineAndColumn, {
+        command: "goland",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const phpstormLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "phpstorm" },
+        "darwin",
+      );
+      assert.deepEqual(phpstormLineAndColumn, {
+        command: "phpstorm",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const pycharmLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "pycharm" },
+        "darwin",
+      );
+      assert.deepEqual(pycharmLineAndColumn, {
+        command: "pycharm",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const riderLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "rider" },
+        "darwin",
+      );
+      assert.deepEqual(riderLineAndColumn, {
+        command: "rider",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const rubymineLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "rubymine" },
+        "darwin",
+      );
+      assert.deepEqual(rubymineLineAndColumn, {
+        command: "rubymine",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const rustroverLineAndColumn = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/src/process/externalLauncher.ts:71:5", editor: "rustrover" },
+        "darwin",
+      );
+      assert.deepEqual(rustroverLineAndColumn, {
+        command: "rustrover",
+        args: ["--line", "71", "--column", "5", "/tmp/workspace/src/process/externalLauncher.ts"],
+      });
+
+      const webstormLineOnly = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace/AGENTS.md:48", editor: "webstorm" },
+        "darwin",
+      );
+      assert.deepEqual(webstormLineOnly, {
+        command: "webstorm",
+        args: ["--line", "48", "/tmp/workspace/AGENTS.md"],
+      });
+    }),
+  );
+
+  it.effect("falls back to zeditor when zed is not installed", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-external-launcher-test-" });
+      yield* fs.writeFileString(path.join(dir, "zeditor"), "#!/bin/sh\nexit 0\n");
+      yield* fs.chmod(path.join(dir, "zeditor"), 0o755);
+
+      const result = yield* resolveEditorLaunch({ cwd: "/tmp/workspace", editor: "zed" }, "linux", {
+        PATH: dir,
+      });
+
+      assert.deepEqual(result, {
+        command: "zeditor",
+        args: ["/tmp/workspace"],
+      });
+    }),
+  );
+
+  it.effect("falls back to the primary command when no alias is installed", () =>
+    Effect.gen(function* () {
+      const result = yield* resolveEditorLaunch({ cwd: "/tmp/workspace", editor: "zed" }, "linux", {
+        PATH: "",
+      });
+      assert.deepEqual(result, {
+        command: "zed",
+        args: ["/tmp/workspace"],
+      });
+    }),
+  );
+
+  it.effect("maps file-manager editor to OS open commands", () =>
+    Effect.gen(function* () {
+      const launch1 = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "file-manager" },
+        "darwin",
+        { PATH: "" },
+      );
+      assert.deepEqual(launch1, {
+        command: "open",
+        args: ["/tmp/workspace"],
+      });
+
+      const launch2 = yield* resolveEditorLaunch(
+        { cwd: "C:\\workspace", editor: "file-manager" },
+        "win32",
+        { PATH: "" },
+      );
+      assert.deepEqual(launch2, {
+        command: "explorer",
+        args: ["C:\\workspace"],
+      });
+
+      const launch3 = yield* resolveEditorLaunch(
+        { cwd: "/tmp/workspace", editor: "file-manager" },
+        "linux",
+        { PATH: "" },
+      );
+      assert.deepEqual(launch3, {
+        command: "xdg-open",
+        args: ["/tmp/workspace"],
+      });
+    }),
+  );
+});
+
+it("resolveBrowserLaunch maps default browser launchers by platform", () => {
+  const target = "https://example.com/some path?name=o'hara";
+
+  assert.deepEqual(resolveBrowserLaunch(target, "darwin").command, "open");
+  assert.deepEqual(resolveBrowserLaunch(target, "darwin").args, [target]);
+  assert.deepEqual(resolveBrowserLaunch(target, "darwin").options, {
+    detached: true,
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+
+  assert.deepEqual(resolveBrowserLaunch(target, "linux", {}).command, "xdg-open");
+  assert.deepEqual(resolveBrowserLaunch(target, "linux", {}).args, [target]);
+
+  const windows = resolveBrowserLaunch(target, "win32", {
+    SYSTEMROOT: "C:\\Windows",
+  });
+  assert.equal(windows.command, "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe");
+  assert.deepEqual(windows.args, [
+    "-NoProfile",
+    "-NonInteractive",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-EncodedCommand",
+    encodeUtf16LeBase64(
+      "$ProgressPreference = 'SilentlyContinue'; Start 'https://example.com/some path?name=o''hara'",
+    ),
+  ]);
+  assert.deepEqual(windows.options, {
+    detached: true,
+    shell: false,
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+});
+
+it("resolveBrowserLaunch opens through Windows from WSL when not remote", () => {
+  const launch = resolveBrowserLaunch("https://example.com", "linux", {
+    WSL_DISTRO_NAME: "Ubuntu",
+  });
+  assert.equal(launch.command, "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe");
+  assert.equal(launch.options.detached, true);
+});
+
+it("resolveBrowserLaunch keeps xdg-open for WSL over SSH", () => {
+  const launch = resolveBrowserLaunch("https://example.com", "linux", {
+    WSL_DISTRO_NAME: "Ubuntu",
+    SSH_CONNECTION: "client server",
+  });
+  assert.equal(launch.command, "xdg-open");
+});
+
+it.layer(NodeServices.layer)("launchBrowser", (it) => {
+  it.effect("spawns through the ChildProcessSpawner service and unrefs the handle", () =>
+    Effect.gen(function* () {
+      let spawnedCommand: ChildProcess.StandardCommand | undefined;
+      let didUnref = false;
+
+      const spawnerLayer = Layer.mock(ChildProcessSpawner.ChildProcessSpawner, {
+        spawn: (command) =>
+          Effect.sync(() => {
+            assert.equal(ChildProcess.isStandardCommand(command), true);
+            if (!ChildProcess.isStandardCommand(command)) {
+              throw new Error("Expected a standard command");
+            }
+            spawnedCommand = command;
+            return makeMockDetachedHandle(() => {
+              didUnref = true;
+            });
+          }),
+      });
+
+      const result = yield* launchBrowser("https://example.com").pipe(
+        Effect.provide(spawnerLayer),
+        Effect.result,
+      );
+
+      assertSuccess(result, undefined);
+      assert.ok(spawnedCommand);
+      const expectedLaunch = resolveBrowserLaunch("https://example.com");
+      assert.equal(spawnedCommand.command, expectedLaunch.command);
+      assert.deepEqual(spawnedCommand.args, expectedLaunch.args);
+      assert.deepEqual(spawnedCommand.options, expectedLaunch.options);
+      assert.equal(didUnref, true);
+    }),
+  );
+});
+
+it.layer(NodeServices.layer)("launchEditorProcess", (it) => {
+  it.effect("spawns through the ChildProcessSpawner service and unrefs the handle", () =>
+    Effect.gen(function* () {
+      let spawnedCommand: ChildProcess.StandardCommand | undefined;
+      let didUnref = false;
+      const expectedArgs = ["-e", "process.exit(0)"];
+
+      const spawnerLayer = Layer.mock(ChildProcessSpawner.ChildProcessSpawner, {
+        spawn: (command) =>
+          Effect.sync(() => {
+            assert.equal(ChildProcess.isStandardCommand(command), true);
+            if (!ChildProcess.isStandardCommand(command)) {
+              throw new Error("Expected a standard command");
+            }
+            spawnedCommand = command;
+            return makeMockDetachedHandle(() => {
+              didUnref = true;
+            });
+          }),
+      });
+
+      const result = yield* launchEditorProcess({
+        command: process.execPath,
+        args: expectedArgs,
+      }).pipe(Effect.provide(spawnerLayer), Effect.result);
+
+      assertSuccess(result, undefined);
+      assert.ok(spawnedCommand);
+      assert.equal(spawnedCommand.command, process.execPath);
+      assert.deepEqual(
+        spawnedCommand.args,
+        process.platform === "win32" ? expectedArgs.map((arg) => `"${arg}"`) : expectedArgs,
+      );
+      assert.deepEqual(spawnedCommand.options, {
+        detached: true,
+        shell: process.platform === "win32",
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      assert.equal(didUnref, true);
+    }),
+  );
+
+  it.effect("rejects when command does not exist", () =>
+    Effect.gen(function* () {
+      const spawnerLayer = Layer.mock(ChildProcessSpawner.ChildProcessSpawner, {});
+      const result = yield* launchEditorProcess({
+        command: `t3code-no-such-command-${yield* Random.nextUUIDv4}`,
+        args: [],
+      }).pipe(Effect.provide(spawnerLayer), Effect.result);
+      assert.equal(result._tag, "Failure");
+    }),
+  );
+});
+
+it.layer(NodeServices.layer)("isCommandAvailable", (it) => {
+  it.effect("resolves win32 commands with PATHEXT", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-external-launcher-test-" });
+      yield* fs.writeFileString(path.join(dir, "code.CMD"), "@echo off\r\n");
+      const env = {
+        PATH: dir,
+        PATHEXT: ".COM;.EXE;.BAT;.CMD",
+      } satisfies NodeJS.ProcessEnv;
+      assert.equal(isCommandAvailable("code", { platform: "win32", env }), true);
+    }),
+  );
+
+  it("returns false when a command is not on PATH", () => {
+    const env = {
+      PATH: "",
+      PATHEXT: ".COM;.EXE;.BAT;.CMD",
+    } satisfies NodeJS.ProcessEnv;
+    assert.equal(isCommandAvailable("definitely-not-installed", { platform: "win32", env }), false);
+  });
+
+  it.effect("does not treat bare files without executable extension as available on win32", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-external-launcher-test-" });
+      yield* fs.writeFileString(path.join(dir, "npm"), "echo nope\r\n");
+      const env = {
+        PATH: dir,
+        PATHEXT: ".COM;.EXE;.BAT;.CMD",
+      } satisfies NodeJS.ProcessEnv;
+      assert.equal(isCommandAvailable("npm", { platform: "win32", env }), false);
+    }),
+  );
+
+  it.effect("appends PATHEXT for commands with non-executable extensions on win32", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-external-launcher-test-" });
+      yield* fs.writeFileString(path.join(dir, "my.tool.CMD"), "@echo off\r\n");
+      const env = {
+        PATH: dir,
+        PATHEXT: ".COM;.EXE;.BAT;.CMD",
+      } satisfies NodeJS.ProcessEnv;
+      assert.equal(isCommandAvailable("my.tool", { platform: "win32", env }), true);
+    }),
+  );
+
+  it.effect("uses platform-specific PATH delimiter for platform overrides", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const firstDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-external-launcher-test-" });
+      const secondDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-external-launcher-test-" });
+      yield* fs.writeFileString(path.join(firstDir, "code.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(secondDir, "code.CMD"), "MZ");
+      const env = {
+        PATH: `${firstDir};${secondDir}`,
+        PATHEXT: ".COM;.EXE;.BAT;.CMD",
+      } satisfies NodeJS.ProcessEnv;
+      assert.equal(isCommandAvailable("code", { platform: "win32", env }), true);
+    }),
+  );
+});
+
+it.layer(NodeServices.layer)("resolveAvailableEditors", (it) => {
+  it.effect("returns installed editors for command launches", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+
+      yield* fs.writeFileString(path.join(dir, "trae.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "kiro.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "code-insiders.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "codium.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "aqua.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "clion.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "datagrip.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "dataspell.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "goland.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "phpstorm.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "pycharm.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "rider.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "rubymine.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "rustrover.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "webstorm.CMD"), "@echo off\r\n");
+      yield* fs.writeFileString(path.join(dir, "explorer.CMD"), "MZ");
+      const editors = resolveAvailableEditors("win32", {
+        PATH: dir,
+        PATHEXT: ".COM;.EXE;.BAT;.CMD",
+      });
+      assert.deepEqual(editors, [
+        "trae",
+        "kiro",
+        "vscode-insiders",
+        "vscodium",
+        "aqua",
+        "clion",
+        "datagrip",
+        "dataspell",
+        "goland",
+        "phpstorm",
+        "pycharm",
+        "rider",
+        "rubymine",
+        "rustrover",
+        "webstorm",
+        "file-manager",
+      ]);
+    }),
+  );
+
+  it.effect("includes zed when only the zeditor command is installed", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+
+      yield* fs.writeFileString(path.join(dir, "zeditor"), "#!/bin/sh\nexit 0\n");
+      yield* fs.writeFileString(path.join(dir, "xdg-open"), "#!/bin/sh\nexit 0\n");
+      yield* fs.chmod(path.join(dir, "zeditor"), 0o755);
+      yield* fs.chmod(path.join(dir, "xdg-open"), 0o755);
+
+      const editors = resolveAvailableEditors("linux", {
+        PATH: dir,
+      });
+      assert.deepEqual(editors, ["zed", "file-manager"]);
+    }),
+  );
+
+  it("omits file-manager when the platform opener is unavailable", () => {
+    const editors = resolveAvailableEditors("linux", {
+      PATH: "",
+    });
+    assert.deepEqual(editors, []);
+  });
+});
diff --git a/apps/server/src/process/externalLauncher.ts b/apps/server/src/process/externalLauncher.ts
new file mode 100644
index 00000000000..cbfee1d7054
--- /dev/null
+++ b/apps/server/src/process/externalLauncher.ts
@@ -0,0 +1,364 @@
+/**
+ * ExternalLauncher - external application launch service interface.
+ *
+ * Owns process launch helpers for browser URLs and workspace paths
+ * in configured editor integrations.
+ *
+ * @module ExternalLauncher
+ */
+import {
+  EDITORS,
+  ExternalLauncherError,
+  type EditorId,
+  type LaunchEditorInput,
+} from "@t3tools/contracts";
+import { isCommandAvailable, type CommandAvailabilityOptions } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+// ==============================
+// Definitions
+// ==============================
+
+export { ExternalLauncherError };
+export type { LaunchEditorInput };
+export { isCommandAvailable } from "@t3tools/shared/shell";
+
+interface EditorLaunch {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+}
+
+interface ProcessLaunch {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly options: ChildProcess.CommandOptions;
+}
+
+interface TargetPathAndPosition {
+  readonly path: string;
+  readonly line: string;
+  readonly column: Option.Option<string>;
+}
+
+const TARGET_WITH_POSITION_PATTERN = /^(.*?):(\d+)(?::(\d+))?$/;
+const POWERSHELL_ARGUMENTS_PREFIX = [
+  "-NoProfile",
+  "-NonInteractive",
+  "-ExecutionPolicy",
+  "Bypass",
+  "-EncodedCommand",
+] as const;
+
+const DETACHED_IGNORE_STDIO_OPTIONS = {
+  detached: true,
+  stdin: "ignore",
+  stdout: "ignore",
+  stderr: "ignore",
+} as const satisfies ChildProcess.CommandOptions;
+
+function parseTargetPathAndPosition(target: string): Option.Option<TargetPathAndPosition> {
+  const match = TARGET_WITH_POSITION_PATTERN.exec(target);
+  if (!match?.[1] || !match[2]) {
+    return Option.none();
+  }
+
+  return Option.some({
+    path: match[1],
+    line: match[2],
+    column: Option.fromUndefinedOr(match[3]),
+  });
+}
+
+function resolveCommandEditorArgs(
+  editor: (typeof EDITORS)[number],
+  target: string,
+): ReadonlyArray<string> {
+  const parsedTarget = parseTargetPathAndPosition(target);
+
+  switch (editor.launchStyle) {
+    case "direct-path":
+      return [target];
+    case "goto":
+      return Option.isSome(parsedTarget) ? ["--goto", target] : [target];
+    case "line-column":
+      return Option.match(parsedTarget, {
+        onNone: () => [target],
+        onSome: ({ path, line, column }) => [
+          "--line",
+          line,
+          ...Option.match(column, {
+            onNone: () => [],
+            onSome: (value) => ["--column", value],
+          }),
+          path,
+        ],
+      });
+  }
+}
+
+function resolveEditorArgs(
+  editor: (typeof EDITORS)[number],
+  target: string,
+): ReadonlyArray<string> {
+  const baseArgs = "baseArgs" in editor ? editor.baseArgs : [];
+  return [...baseArgs, ...resolveCommandEditorArgs(editor, target)];
+}
+
+function resolveAvailableCommand(
+  commands: ReadonlyArray<string>,
+  options: CommandAvailabilityOptions = {},
+): Option.Option<string> {
+  for (const command of commands) {
+    if (isCommandAvailable(command, options)) {
+      return Option.some(command);
+    }
+  }
+  return Option.none();
+}
+
+function encodeUtf16LeBase64(input: string): string {
+  const bytes = new Uint8Array(input.length * 2);
+  for (let index = 0; index < input.length; index += 1) {
+    const code = input.charCodeAt(index);
+    bytes[index * 2] = code & 0xff;
+    bytes[index * 2 + 1] = code >>> 8;
+  }
+  return Encoding.encodeBase64(bytes);
+}
+
+function escapePowerShellStringLiteral(input: string): string {
+  return `'${input.replaceAll("'", "''")}'`;
+}
+
+function resolvePowerShellPath(env: NodeJS.ProcessEnv = process.env): string {
+  return `${env.SYSTEMROOT || env.windir || String.raw`C:\Windows`}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+}
+
+function resolveWslPowerShellPath(): string {
+  return "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe";
+}
+
+function shouldUseWindowsBrowserFromWsl(
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return (
+    platform === "linux" &&
+    (env.WSL_DISTRO_NAME !== undefined || env.WSL_INTEROP !== undefined) &&
+    env.SSH_CONNECTION === undefined &&
+    env.SSH_TTY === undefined &&
+    env.container === undefined
+  );
+}
+
+function resolveWindowsBrowserLaunch(target: string, command: string): ProcessLaunch {
+  const encodedCommand = encodeUtf16LeBase64(
+    `$ProgressPreference = 'SilentlyContinue'; Start ${escapePowerShellStringLiteral(target)}`,
+  );
+  return {
+    command,
+    args: [...POWERSHELL_ARGUMENTS_PREFIX, encodedCommand],
+    options: {
+      detached: true,
+      shell: false,
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+    },
+  };
+}
+
+function fileManagerCommandForPlatform(platform: NodeJS.Platform): string {
+  switch (platform) {
+    case "darwin":
+      return "open";
+    case "win32":
+      return "explorer";
+    default:
+      return "xdg-open";
+  }
+}
+
+export function resolveBrowserLaunch(
+  target: string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): ProcessLaunch {
+  if (platform === "darwin") {
+    return {
+      command: "open",
+      args: [target],
+      options: DETACHED_IGNORE_STDIO_OPTIONS,
+    };
+  }
+
+  if (platform === "win32") {
+    return resolveWindowsBrowserLaunch(target, resolvePowerShellPath(env));
+  }
+
+  if (shouldUseWindowsBrowserFromWsl(platform, env)) {
+    return resolveWindowsBrowserLaunch(target, resolveWslPowerShellPath());
+  }
+
+  return {
+    command: "xdg-open",
+    args: [target],
+    options: DETACHED_IGNORE_STDIO_OPTIONS,
+  };
+}
+
+export function resolveAvailableEditors(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): ReadonlyArray<EditorId> {
+  const available: EditorId[] = [];
+
+  for (const editor of EDITORS) {
+    if (editor.commands === null) {
+      const command = fileManagerCommandForPlatform(platform);
+      if (isCommandAvailable(command, { platform, env })) {
+        available.push(editor.id);
+      }
+      continue;
+    }
+
+    const command = resolveAvailableCommand(editor.commands, { platform, env });
+    if (Option.isSome(command)) {
+      available.push(editor.id);
+    }
+  }
+
+  return available;
+}
+
+/**
+ * ExternalLauncherShape - Service API for browser and editor launch actions.
+ */
+export interface ExternalLauncherShape {
+  /**
+   * Launch a URL target in the default browser.
+   */
+  readonly launchBrowser: (target: string) => Effect.Effect<void, ExternalLauncherError>;
+
+  /**
+   * Launch a workspace path in a selected editor integration.
+   *
+   * Launches the editor as a detached process so server startup is not blocked.
+   */
+  readonly launchEditor: (input: LaunchEditorInput) => Effect.Effect<void, ExternalLauncherError>;
+}
+
+/**
+ * ExternalLauncher - Service tag for browser/editor launch operations.
+ */
+export class ExternalLauncher extends Context.Service<ExternalLauncher, ExternalLauncherShape>()(
+  "t3/process/ExternalLauncher",
+) {}
+
+// ==============================
+// Implementations
+// ==============================
+
+export const resolveEditorLaunch = Effect.fn("resolveEditorLaunch")(function* (
+  input: LaunchEditorInput,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<EditorLaunch, ExternalLauncherError> {
+  yield* Effect.annotateCurrentSpan({
+    "externalLauncher.editor": input.editor,
+    "externalLauncher.cwd": input.cwd,
+    "externalLauncher.platform": platform,
+  });
+  const editorDef = EDITORS.find((editor) => editor.id === input.editor);
+  if (!editorDef) {
+    return yield* new ExternalLauncherError({ message: `Unknown editor: ${input.editor}` });
+  }
+
+  if (editorDef.commands) {
+    const command = Option.getOrElse(
+      resolveAvailableCommand(editorDef.commands, { platform, env }),
+      () => editorDef.commands[0],
+    );
+    return {
+      command,
+      args: resolveEditorArgs(editorDef, input.cwd),
+    };
+  }
+
+  if (editorDef.id !== "file-manager") {
+    return yield* new ExternalLauncherError({ message: `Unsupported editor: ${input.editor}` });
+  }
+
+  return { command: fileManagerCommandForPlatform(platform), args: [input.cwd] };
+});
+
+const launchAndUnref = Effect.fn("externalLauncher.launchAndUnref")(function* (
+  launch: ProcessLaunch,
+  errorMessage: string,
+): Effect.fn.Return<void, ExternalLauncherError, ChildProcessSpawner.ChildProcessSpawner> {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const command = ChildProcess.make(launch.command, launch.args, launch.options);
+
+  yield* spawner.spawn(command).pipe(
+    Effect.flatMap((handle) => handle.unref),
+    Effect.asVoid,
+    Effect.scoped,
+    Effect.mapError((cause) => new ExternalLauncherError({ message: errorMessage, cause })),
+  );
+});
+
+export const launchBrowser = Effect.fn("externalLauncher.launchBrowser")(function* (
+  target: string,
+): Effect.fn.Return<void, ExternalLauncherError, ChildProcessSpawner.ChildProcessSpawner> {
+  return yield* launchAndUnref(resolveBrowserLaunch(target), "Browser auto-open failed");
+});
+
+export const launchEditorProcess = Effect.fn("externalLauncher.launchEditorProcess")(function* (
+  launch: EditorLaunch,
+): Effect.fn.Return<void, ExternalLauncherError, ChildProcessSpawner.ChildProcessSpawner> {
+  if (!isCommandAvailable(launch.command)) {
+    return yield* new ExternalLauncherError({
+      message: `Editor command not found: ${launch.command}`,
+    });
+  }
+
+  const isWin32 = process.platform === "win32";
+  yield* launchAndUnref(
+    {
+      command: launch.command,
+      args: isWin32 ? launch.args.map((arg) => `"${arg}"`) : [...launch.args],
+      options: {
+        detached: true,
+        shell: isWin32,
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore",
+      },
+    },
+    "failed to spawn detached process",
+  );
+});
+
+const make = Effect.gen(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+  return {
+    launchBrowser: (target) =>
+      launchBrowser(target).pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+      ),
+    launchEditor: (input) =>
+      Effect.flatMap(resolveEditorLaunch(input), (launch) =>
+        launchEditorProcess(launch).pipe(
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+        ),
+      ),
+  } satisfies ExternalLauncherShape;
+});
+
+export const layer = Layer.effect(ExternalLauncher, make);
diff --git a/apps/server/src/processRunner.test.ts b/apps/server/src/processRunner.test.ts
index dd909116d4d..fae9ad574cf 100644
--- a/apps/server/src/processRunner.test.ts
+++ b/apps/server/src/processRunner.test.ts
@@ -1,23 +1,298 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { TestClock } from "effect/testing";
+import { ChildProcessSpawner } from "effect/unstable/process";
 
-import { runProcess } from "./processRunner";
+import {
+  isWindowsCommandNotFound,
+  ProcessOutputLimitError,
+  ProcessRunner,
+  ProcessTimeoutError,
+  layer as ProcessRunnerLive,
+  type ProcessRunInput,
+} from "./processRunner.ts";
+
+type ChildProcessCommand = {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+};
+
+// Accesses private properties of ChildProcessCommand for testing purposes
+function asChildProcessCommand(command: unknown): ChildProcessCommand {
+  return command as ChildProcessCommand;
+}
+
+function makeHandle(input: {
+  readonly stdout?: string | Stream.Stream<Uint8Array>;
+  readonly stderr?: string | Stream.Stream<Uint8Array>;
+  readonly code?: number;
+  readonly stdin?: ChildProcessSpawner.ChildProcessHandle["stdin"];
+  readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+}) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: input.exitCode ?? Effect.succeed(ChildProcessSpawner.ExitCode(input.code ?? 0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: input.stdin ?? Sink.drain,
+    stdout:
+      typeof input.stdout === "string"
+        ? Stream.encodeText(Stream.make(input.stdout))
+        : (input.stdout ?? Stream.empty),
+    stderr:
+      typeof input.stderr === "string"
+        ? Stream.encodeText(Stream.make(input.stderr))
+        : (input.stderr ?? Stream.empty),
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+function makeSpawner(
+  f: (command: ChildProcessCommand) => Effect.Effect<ChildProcessSpawner.ChildProcessHandle>,
+) {
+  return ChildProcessSpawner.make((command) => f(asChildProcessCommand(command)));
+}
+
+const runWith =
+  (spawner: ChildProcessSpawner.ChildProcessSpawner["Service"]) => (input: ProcessRunInput) =>
+    Effect.service(ProcessRunner).pipe(
+      Effect.flatMap((runner) =>
+        runner.run({
+          ...input,
+          shell: input.shell ?? false,
+        }),
+      ),
+      Effect.provide(
+        ProcessRunnerLive.pipe(
+          Layer.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+        ),
+      ),
+    );
 
 describe("runProcess", () => {
-  it("fails when output exceeds max buffer in default mode", async () => {
-    await expect(
-      runProcess("node", ["-e", "process.stdout.write('x'.repeat(2048))"], { maxBufferBytes: 128 }),
-    ).rejects.toThrow("exceeded stdout buffer limit");
+  it.effect("collects stdout through an injected ChildProcessSpawner", () =>
+    Effect.gen(function* () {
+      const spawner = makeSpawner((command) =>
+        Effect.sync(() => {
+          expect(command.command).toBe("fake");
+          expect(command.args).toEqual(["stdout-bytes", "32"]);
+          return makeHandle({ stdout: "x".repeat(32) });
+        }),
+      );
+
+      const result = yield* runWith(spawner)({
+        command: "fake",
+        args: ["stdout-bytes", "32"],
+      });
+
+      expect(result.code).toBe(0);
+      expect(result.stdout).toBe("x".repeat(32));
+      expect(result.timedOut).toBe(false);
+    }),
+  );
+
+  it.effect("runs through the ProcessRunner service", () => {
+    const spawner = makeSpawner((command) =>
+      Effect.sync(() => {
+        expect(command.command).toBe("fake");
+        expect(command.args).toEqual(["--service"]);
+        return makeHandle({ stdout: "service ok" });
+      }),
+    );
+    const layer = ProcessRunnerLive.pipe(
+      Layer.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+    );
+
+    return Effect.gen(function* () {
+      const runner = yield* ProcessRunner;
+      const result = yield* runner.run({
+        command: "fake",
+        args: ["--service"],
+      });
+
+      expect(result.stdout).toBe("service ok");
+    }).pipe(Effect.provide(layer));
   });
 
-  it("truncates output when outputMode is truncate", async () => {
-    const result = await runProcess("node", ["-e", "process.stdout.write('x'.repeat(2048))"], {
-      maxBufferBytes: 128,
-      outputMode: "truncate",
-    });
+  it.effect("fails when output exceeds max buffer in default mode", () =>
+    Effect.gen(function* () {
+      const spawner = makeSpawner(() => Effect.succeed(makeHandle({ stdout: "x".repeat(2048) })));
+
+      const error = yield* runWith(spawner)({
+        command: "fake",
+        args: ["stdout-bytes", "2048"],
+        maxOutputBytes: 128,
+      }).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(ProcessOutputLimitError);
+    }),
+  );
+
+  it.effect("fails fast on output limit before timeout for long-running output", () =>
+    Effect.gen(function* () {
+      const textChunk = "x".repeat(64);
+      const spawner = makeSpawner(() =>
+        Effect.succeed(
+          makeHandle({
+            stdout: Stream.fromIterable(Array.from({ length: 10 }, () => textChunk)).pipe(
+              Stream.encodeText,
+            ),
+            exitCode: Effect.never,
+          }),
+        ),
+      );
+
+      const error = yield* runWith(spawner)({
+        command: "fake",
+        args: ["spam-stdout"],
+        maxOutputBytes: 128,
+        timeout: "2 seconds",
+      }).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(ProcessOutputLimitError);
+    }),
+  );
+
+  it.effect("truncates output when outputMode is truncate", () =>
+    Effect.gen(function* () {
+      const spawner = makeSpawner(() => Effect.succeed(makeHandle({ stdout: "x".repeat(2048) })));
+
+      const result = yield* runWith(spawner)({
+        command: "fake",
+        args: ["stdout-bytes", "2048"],
+        maxOutputBytes: 128,
+        outputMode: "truncate",
+      });
+
+      expect(result.code).toBe(0);
+      expect(result.stdout.length).toBeLessThanOrEqual(128);
+      expect(result.stdoutTruncated).toBe(true);
+      expect(result.stderrTruncated).toBe(false);
+    }),
+  );
+
+  it.effect("writes stdin before waiting for exit", () =>
+    Effect.gen(function* () {
+      const stdinWritten = yield* Deferred.make<void>();
+      const decoder = new TextDecoder();
+      const spawner = makeSpawner(() =>
+        Effect.succeed(
+          makeHandle({
+            stdout: "stdin payload",
+            stdin: Sink.forEach((chunk: Uint8Array) => {
+              const text = decoder.decode(chunk, { stream: true });
+              return text.includes("stdin payload")
+                ? Deferred.succeed(stdinWritten, undefined)
+                : Effect.void;
+            }),
+            exitCode: Deferred.await(stdinWritten).pipe(Effect.as(ChildProcessSpawner.ExitCode(0))),
+          }),
+        ),
+      );
+
+      const result = yield* runWith(spawner)({
+        command: "fake",
+        args: ["stdin-echo"],
+        stdin: "stdin payload",
+      });
+
+      expect(result.stdout).toBe("stdin payload");
+      expect(result.code).toBe(0);
+    }),
+  );
+
+  it.effect("returns output for non-zero exit codes", () =>
+    Effect.gen(function* () {
+      const spawner = makeSpawner(() => Effect.succeed(makeHandle({ stderr: "boom", code: 2 })));
+
+      const result = yield* runWith(spawner)({
+        command: "fake",
+        args: ["stderr-exit", "boom", "2"],
+      });
+
+      expect(result.code).toBe(2);
+      expect(result.stderr).toBe("boom");
+    }),
+  );
+
+  it.effect("fails on timeout", () =>
+    Effect.gen(function* () {
+      const spawner = makeSpawner(() =>
+        Effect.succeed(
+          makeHandle({
+            exitCode: Effect.never,
+          }),
+        ),
+      );
+      const errorFiber = yield* runWith(spawner)({
+        command: "fake",
+        args: ["sleep"],
+        timeout: "50 millis",
+      }).pipe(Effect.flip, Effect.forkScoped);
+
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(50));
+      const error = yield* Fiber.join(errorFiber);
+
+      expect(error).toBeInstanceOf(ProcessTimeoutError);
+    }),
+  );
+
+  it.effect("returns a synthetic timed out result when timeoutBehavior is timedOutResult", () =>
+    Effect.gen(function* () {
+      const spawner = makeSpawner(() =>
+        Effect.succeed(
+          makeHandle({
+            exitCode: Effect.never,
+          }),
+        ),
+      );
+      const resultFiber = yield* runWith(spawner)({
+        command: "fake",
+        args: ["sleep"],
+        timeout: "50 millis",
+        timeoutBehavior: "timedOutResult",
+      }).pipe(Effect.forkScoped);
+
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(50));
+      const result = yield* Fiber.join(resultFiber);
+
+      expect(result).toMatchObject({
+        stdout: "",
+        stderr: "",
+        code: null,
+        timedOut: true,
+        stdoutTruncated: false,
+        stderrTruncated: false,
+      });
+    }),
+  );
+});
+
+describe("isWindowsCommandNotFound", () => {
+  it("matches the localized German cmd.exe error text", () => {
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
 
-    expect(result.code).toBe(0);
-    expect(result.stdout.length).toBeLessThanOrEqual(128);
-    expect(result.stdoutTruncated).toBe(true);
-    expect(result.stderrTruncated).toBe(false);
+    try {
+      expect(
+        isWindowsCommandNotFound(
+          1,
+          "wird nicht als interner oder externer Befehl, betriebsfahiges Programm oder Batch-Datei erkannt",
+        ),
+      ).toBe(true);
+    } finally {
+      Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
+    }
   });
 });
diff --git a/apps/server/src/processRunner.ts b/apps/server/src/processRunner.ts
index 5402612887d..55988a8533a 100644
--- a/apps/server/src/processRunner.ts
+++ b/apps/server/src/processRunner.ts
@@ -1,270 +1,336 @@
-import { type ChildProcess as ChildProcessHandle, spawn, spawnSync } from "node:child_process";
+import * as Data from "effect/Data";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import {
+  collectUint8StreamText,
+  type CollectedUint8StreamText,
+} from "./stream/collectUint8StreamText.ts";
 
-export interface ProcessRunOptions {
-  cwd?: string | undefined;
-  timeoutMs?: number | undefined;
-  env?: NodeJS.ProcessEnv | undefined;
-  stdin?: string | undefined;
-  allowNonZeroExit?: boolean | undefined;
-  maxBufferBytes?: number | undefined;
-  outputMode?: "error" | "truncate" | undefined;
+export interface ProcessRunInput {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string | undefined;
+  readonly spawnCwd?: string | undefined;
+  readonly timeout?: Duration.Input | undefined;
+  readonly env?: NodeJS.ProcessEnv | undefined;
+  readonly stdin?: string | undefined;
+  readonly maxOutputBytes?: number | undefined;
+  readonly outputMode?: "error" | "truncate" | undefined;
+  readonly truncatedMarker?: string | undefined;
+  readonly shell?: boolean | string | undefined;
+  /**
+   * On timeout, return a synthetic timedOut result.
+   * Partial stdout/stderr are not preserved.
+   */
+  readonly timeoutBehavior?: "error" | "timedOutResult" | undefined;
 }
 
-export interface ProcessRunResult {
-  stdout: string;
-  stderr: string;
-  code: number | null;
-  signal: NodeJS.Signals | null;
-  timedOut: boolean;
-  stdoutTruncated?: boolean | undefined;
-  stderrTruncated?: boolean | undefined;
+export interface ProcessRunOutput {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly code: ChildProcessSpawner.ExitCode | null;
+  readonly timedOut: boolean;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
 }
 
-function commandLabel(command: string, args: readonly string[]): string {
-  return [command, ...args].join(" ");
-}
+export class ProcessSpawnError extends Data.TaggedError("ProcessSpawnError")<{
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string | undefined;
+  readonly cause: unknown;
+}> {}
 
-function normalizeSpawnError(command: string, args: readonly string[], error: unknown): Error {
-  if (!(error instanceof Error)) {
-    return new Error(`Failed to run ${commandLabel(command, args)}.`);
-  }
+export class ProcessStdinError extends Data.TaggedError("ProcessStdinError")<{
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string | undefined;
+  readonly cause: unknown;
+}> {}
 
-  const maybeCode = (error as NodeJS.ErrnoException).code;
-  if (maybeCode === "ENOENT") {
-    return new Error(`Command not found: ${command}`);
-  }
+export class ProcessOutputLimitError extends Data.TaggedError("ProcessOutputLimitError")<{
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string | undefined;
+  readonly stream: "stdout" | "stderr";
+  readonly maxBytes: number;
+}> {}
 
-  return new Error(`Failed to run ${commandLabel(command, args)}: ${error.message}`);
-}
+export class ProcessReadError extends Data.TaggedError("ProcessReadError")<{
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string | undefined;
+  readonly stream: "stdout" | "stderr" | "exitCode";
+  readonly cause: unknown;
+}> {}
 
-export function isWindowsCommandNotFound(code: number | null, stderr: string): boolean {
-  if (process.platform !== "win32") return false;
-  if (code === 9009) return true;
-  return /is not recognized as an internal or external command/i.test(stderr);
-}
+export class ProcessTimeoutError extends Data.TaggedError("ProcessTimeoutError")<{
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string | undefined;
+  readonly timeoutMs: number;
+}> {}
 
-function normalizeExitError(
-  command: string,
-  args: readonly string[],
-  result: ProcessRunResult,
-): Error {
-  if (isWindowsCommandNotFound(result.code, result.stderr)) {
-    return new Error(`Command not found: ${command}`);
-  }
+export type ProcessRunError =
+  | ProcessSpawnError
+  | ProcessStdinError
+  | ProcessOutputLimitError
+  | ProcessReadError
+  | ProcessTimeoutError;
 
-  const reason = result.timedOut
-    ? "timed out"
-    : `failed (code=${result.code ?? "null"}, signal=${result.signal ?? "null"})`;
-  const stderr = result.stderr.trim();
-  const detail = stderr.length > 0 ? ` ${stderr}` : "";
-  return new Error(`${commandLabel(command, args)} ${reason}.${detail}`);
+export interface ProcessRunnerShape {
+  readonly run: (input: ProcessRunInput) => Effect.Effect<ProcessRunOutput, ProcessRunError>;
 }
 
-function normalizeStdinError(command: string, args: readonly string[], error: unknown): Error {
-  if (!(error instanceof Error)) {
-    return new Error(`Failed to write stdin for ${commandLabel(command, args)}.`);
-  }
-  return new Error(`Failed to write stdin for ${commandLabel(command, args)}: ${error.message}`);
-}
+export class ProcessRunner extends Context.Service<ProcessRunner, ProcessRunnerShape>()(
+  "t3/process/ProcessRunner",
+) {}
 
-function normalizeBufferError(
-  command: string,
-  args: readonly string[],
-  stream: "stdout" | "stderr",
-  maxBufferBytes: number,
-): Error {
-  return new Error(
-    `${commandLabel(command, args)} exceeded ${stream} buffer limit (${maxBufferBytes} bytes).`,
-  );
-}
+const DEFAULT_TIMEOUT = "60 seconds";
+const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
 
-const DEFAULT_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+const WINDOWS_COMMAND_NOT_FOUND_PATTERNS = [
+  /is not recognized as an internal or external command/i,
+  /n.o . reconhecido como um comando interno/i,
+  /non . riconosciuto come comando interno o esterno/i,
+  /n.est pas reconnu en tant que commande interne/i,
+  /no se reconoce como un comando interno o externo/i,
+  /wird nicht als interner oder externer befehl/i,
+] as const;
 
-/**
- * On Windows with `shell: true`, `child.kill()` only terminates the `cmd.exe`
- * wrapper, leaving the actual command running. Use `taskkill /T` to kill the
- * entire process tree instead.
- */
-function killChild(child: ChildProcessHandle, signal: NodeJS.Signals = "SIGTERM"): void {
-  if (process.platform === "win32" && child.pid !== undefined) {
-    try {
-      spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
-      return;
-    } catch {
-      // fallback to direct kill
-    }
-  }
-  child.kill(signal);
+function hasWindowsCommandNotFoundMessage(output: string): boolean {
+  return WINDOWS_COMMAND_NOT_FOUND_PATTERNS.some((pattern) => pattern.test(output));
 }
 
-function appendChunkWithinLimit(
-  target: string,
-  currentBytes: number,
-  chunk: Buffer,
-  maxBytes: number,
-): {
-  next: string;
-  nextBytes: number;
-  truncated: boolean;
-} {
-  const remaining = maxBytes - currentBytes;
-  if (remaining <= 0) {
-    return { next: target, nextBytes: currentBytes, truncated: true };
-  }
-  if (chunk.length <= remaining) {
-    return {
-      next: `${target}${chunk.toString()}`,
-      nextBytes: currentBytes + chunk.length,
-      truncated: false,
-    };
-  }
-  return {
-    next: `${target}${chunk.subarray(0, remaining).toString()}`,
-    nextBytes: currentBytes + remaining,
-    truncated: true,
-  };
+export function isWindowsCommandNotFound(code: number | null, stderr: string): boolean {
+  if (process.platform !== "win32") return false;
+  if (code === 9009) return true;
+  return hasWindowsCommandNotFoundMessage(stderr);
 }
 
-export async function runProcess(
-  command: string,
-  args: readonly string[],
-  options: ProcessRunOptions = {},
-): Promise<ProcessRunResult> {
-  const timeoutMs = options.timeoutMs ?? 60_000;
-  const maxBufferBytes = options.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
-  const outputMode = options.outputMode ?? "error";
+const collectText = Effect.fn("processRunner.collectText")(function* (input: {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string | undefined;
+  readonly streamName: "stdout" | "stderr";
+  readonly stream: Stream.Stream<Uint8Array, PlatformError.PlatformError>;
+  readonly maxOutputBytes: number;
+  readonly outputMode: "error" | "truncate";
+  readonly truncatedMarker: string;
+}) {
+  const stream = input.stream.pipe(
+    Stream.mapError(
+      (cause) =>
+        new ProcessReadError({
+          command: input.command,
+          args: input.args,
+          cwd: input.cwd,
+          stream: input.streamName,
+          cause,
+        }),
+    ),
+  );
 
-  return new Promise<ProcessRunResult>((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd: options.cwd,
-      env: options.env,
-      stdio: "pipe",
-      shell: process.platform === "win32",
+  if (input.outputMode === "truncate") {
+    return yield* collectUint8StreamText({
+      stream,
+      maxBytes: input.maxOutputBytes,
+      truncatedMarker: input.truncatedMarker,
     });
+  }
 
-    let stdout = "";
-    let stderr = "";
-    let stdoutBytes = 0;
-    let stderrBytes = 0;
-    let stdoutTruncated = false;
-    let stderrTruncated = false;
-    let timedOut = false;
-    let settled = false;
-    let forceKillTimer: ReturnType<typeof setTimeout> | null = null;
+  return yield* stream.pipe(
+    Stream.runFoldEffect<
+      {
+        readonly chunks: Uint8Array<ArrayBufferLike>[];
+        readonly bytes: number;
+      },
+      Uint8Array<ArrayBufferLike>,
+      ProcessOutputLimitError | ProcessReadError,
+      never
+    >(
+      () => ({ chunks: [], bytes: 0 }),
+      (state, chunk) => {
+        const remainingBytes = input.maxOutputBytes - state.bytes;
+        if (remainingBytes <= 0 || chunk.byteLength > remainingBytes) {
+          return Effect.fail(
+            new ProcessOutputLimitError({
+              command: input.command,
+              args: input.args,
+              cwd: input.cwd,
+              stream: input.streamName,
+              maxBytes: input.maxOutputBytes,
+            }),
+          );
+        }
 
-    const timeoutTimer = setTimeout(() => {
-      timedOut = true;
-      killChild(child, "SIGTERM");
-      forceKillTimer = setTimeout(() => {
-        killChild(child, "SIGKILL");
-      }, 1_000);
-    }, timeoutMs);
+        state.chunks.push(chunk);
+        return Effect.succeed({
+          chunks: state.chunks,
+          bytes: state.bytes + chunk.byteLength,
+        });
+      },
+    ),
+    Effect.map(
+      (state): CollectedUint8StreamText => ({
+        text: Buffer.concat(state.chunks, state.bytes).toString("utf8"),
+        bytes: state.bytes,
+        truncated: false,
+      }),
+    ),
+  );
+});
 
-    const finalize = (callback: () => void): void => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeoutTimer);
-      if (forceKillTimer) {
-        clearTimeout(forceKillTimer);
+function finalizeRunProcess<R>(
+  effect: Effect.Effect<ProcessRunOutput, ProcessRunError, R | Scope.Scope>,
+  input: ProcessRunInput,
+): Effect.Effect<ProcessRunOutput, ProcessRunError, Exclude<R, Scope.Scope>> {
+  const timeout = Duration.fromInputUnsafe(input.timeout ?? DEFAULT_TIMEOUT);
+  const timeoutBehavior = input.timeoutBehavior ?? "error";
+
+  return effect.pipe(
+    Effect.scoped,
+    Effect.timeoutOption(timeout),
+    Effect.flatMap((result) => {
+      if (Option.isSome(result)) {
+        return Effect.succeed(result.value);
+      }
+      if (timeoutBehavior === "timedOutResult") {
+        return Effect.succeed({
+          stdout: "",
+          stderr: "",
+          code: null,
+          timedOut: true,
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        } satisfies ProcessRunOutput);
       }
-      callback();
-    };
+      return Effect.fail(
+        new ProcessTimeoutError({
+          command: input.command,
+          args: input.args,
+          cwd: input.cwd,
+          timeoutMs: Duration.toMillis(timeout),
+        }),
+      );
+    }),
+  );
+}
 
-    const fail = (error: Error): void => {
-      killChild(child, "SIGTERM");
-      finalize(() => {
-        reject(error);
-      });
-    };
+const runProcessCore = Effect.fn("processRunner.runProcessCore")(function* (
+  spawner: ChildProcessSpawner.ChildProcessSpawner["Service"],
+  input: ProcessRunInput,
+): Effect.fn.Return<ProcessRunOutput, ProcessRunError, Scope.Scope> {
+  const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const outputMode = input.outputMode ?? "error";
+  const truncatedMarker = input.truncatedMarker ?? "";
 
-    const appendOutput = (stream: "stdout" | "stderr", chunk: Buffer | string): Error | null => {
-      const chunkBuffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
-      const text = chunkBuffer.toString();
-      const byteLength = chunkBuffer.length;
-      if (stream === "stdout") {
-        if (outputMode === "truncate") {
-          const appended = appendChunkWithinLimit(stdout, stdoutBytes, chunkBuffer, maxBufferBytes);
-          stdout = appended.next;
-          stdoutBytes = appended.nextBytes;
-          stdoutTruncated = stdoutTruncated || appended.truncated;
-          return null;
-        }
-        stdout += text;
-        stdoutBytes += byteLength;
-        if (stdoutBytes > maxBufferBytes) {
-          return normalizeBufferError(command, args, "stdout", maxBufferBytes);
-        }
-      } else {
-        if (outputMode === "truncate") {
-          const appended = appendChunkWithinLimit(stderr, stderrBytes, chunkBuffer, maxBufferBytes);
-          stderr = appended.next;
-          stderrBytes = appended.nextBytes;
-          stderrTruncated = stderrTruncated || appended.truncated;
-          return null;
-        }
-        stderr += text;
-        stderrBytes += byteLength;
-        if (stderrBytes > maxBufferBytes) {
-          return normalizeBufferError(command, args, "stderr", maxBufferBytes);
-        }
-      }
-      return null;
-    };
+  const child = yield* spawner
+    .spawn(
+      ChildProcess.make(input.command, [...input.args], {
+        ...((input.spawnCwd ?? input.cwd) ? { cwd: input.spawnCwd ?? input.cwd } : {}),
+        ...(input.env !== undefined
+          ? {
+              env: input.env,
+              extendEnv: true,
+            }
+          : {}),
+        ...(input.shell !== undefined ? { shell: input.shell } : {}),
+      }),
+    )
+    .pipe(
+      Effect.mapError(
+        (cause) =>
+          new ProcessSpawnError({
+            command: input.command,
+            args: input.args,
+            cwd: input.cwd,
+            cause,
+          }),
+      ),
+    );
 
-    child.stdout.on("data", (chunk: Buffer | string) => {
-      const error = appendOutput("stdout", chunk);
-      if (error) {
-        fail(error);
-      }
-    });
+  const writeStdin =
+    input.stdin === undefined
+      ? Effect.void
+      : Stream.run(Stream.encodeText(Stream.make(input.stdin)), child.stdin).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ProcessStdinError({
+                command: input.command,
+                args: input.args,
+                cwd: input.cwd,
+                cause,
+              }),
+          ),
+        );
 
-    child.stderr.on("data", (chunk: Buffer | string) => {
-      const error = appendOutput("stderr", chunk);
-      if (error) {
-        fail(error);
-      }
-    });
+  const [stdout, stderr] = yield* Effect.all(
+    [
+      collectText({
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd,
+        streamName: "stdout",
+        stream: child.stdout,
+        maxOutputBytes,
+        outputMode,
+        truncatedMarker,
+      }),
+      collectText({
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd,
+        streamName: "stderr",
+        stream: child.stderr,
+        maxOutputBytes,
+        outputMode,
+        truncatedMarker,
+      }),
+      writeStdin,
+    ],
+    { concurrency: "unbounded" },
+  );
 
-    child.once("error", (error) => {
-      finalize(() => {
-        reject(normalizeSpawnError(command, args, error));
-      });
-    });
+  const exitCode = yield* child.exitCode.pipe(
+    Effect.mapError(
+      (cause) =>
+        new ProcessReadError({
+          command: input.command,
+          args: input.args,
+          cwd: input.cwd,
+          stream: "exitCode",
+          cause,
+        }),
+    ),
+  );
 
-    child.once("close", (code, signal) => {
-      const result: ProcessRunResult = {
-        stdout,
-        stderr,
-        code,
-        signal,
-        timedOut,
-        stdoutTruncated,
-        stderrTruncated,
-      };
+  return {
+    stdout: stdout.text,
+    stderr: stderr.text,
+    code: exitCode,
+    timedOut: false,
+    stdoutTruncated: stdout.truncated,
+    stderrTruncated: stderr.truncated,
+  } satisfies ProcessRunOutput;
+});
 
-      finalize(() => {
-        if (!options.allowNonZeroExit && (timedOut || (code !== null && code !== 0))) {
-          reject(normalizeExitError(command, args, result));
-          return;
-        }
-        resolve(result);
-      });
-    });
+export const make = Effect.fn("makeProcessRunner")(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 
-    child.stdin.once("error", (error) => {
-      fail(normalizeStdinError(command, args, error));
-    });
+  const run: ProcessRunnerShape["run"] = (input) =>
+    finalizeRunProcess(runProcessCore(spawner, input), input);
 
-    if (options.stdin !== undefined) {
-      child.stdin.write(options.stdin, (error) => {
-        if (error) {
-          fail(normalizeStdinError(command, args, error));
-          return;
-        }
-        child.stdin.end();
-      });
-      return;
-    }
-    child.stdin.end();
+  return ProcessRunner.of({
+    run,
   });
-}
+});
+
+export const layer = Layer.effect(ProcessRunner, make());
diff --git a/apps/server/src/project/Layers/ProjectFaviconResolver.test.ts b/apps/server/src/project/Layers/ProjectFaviconResolver.test.ts
index 29b30739b9c..c983aca4ba7 100644
--- a/apps/server/src/project/Layers/ProjectFaviconResolver.test.ts
+++ b/apps/server/src/project/Layers/ProjectFaviconResolver.test.ts
@@ -1,6 +1,9 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it, describe, expect } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 
 import { ProjectFaviconResolver } from "../Services/ProjectFaviconResolver.ts";
 import { ProjectFaviconResolverLive } from "./ProjectFaviconResolver.ts";
diff --git a/apps/server/src/project/Layers/ProjectFaviconResolver.ts b/apps/server/src/project/Layers/ProjectFaviconResolver.ts
index 3004a7a45cf..ed5412bf138 100644
--- a/apps/server/src/project/Layers/ProjectFaviconResolver.ts
+++ b/apps/server/src/project/Layers/ProjectFaviconResolver.ts
@@ -1,4 +1,7 @@
-import { Effect, FileSystem, Layer, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 
 import {
   ProjectFaviconResolver,
@@ -27,6 +30,7 @@ const FAVICON_CANDIDATES = [
   "assets/icon.png",
   "assets/logo.svg",
   "assets/logo.png",
+  ".idea/icon.svg",
 ] as const;
 
 // Files that may contain a <link rel="icon"> or icon metadata declaration.
diff --git a/apps/server/src/project/Layers/ProjectSetupScriptRunner.test.ts b/apps/server/src/project/Layers/ProjectSetupScriptRunner.test.ts
index 6366a768b75..d0fafd56a01 100644
--- a/apps/server/src/project/Layers/ProjectSetupScriptRunner.test.ts
+++ b/apps/server/src/project/Layers/ProjectSetupScriptRunner.test.ts
@@ -1,53 +1,56 @@
-import { Effect, Layer, Stream } from "effect";
+import { ProjectId, type OrchestrationProject } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import { describe, expect, it, vi } from "vitest";
-import type { OrchestrationReadModel } from "@t3tools/contracts";
 
-import { OrchestrationEngineService } from "../../orchestration/Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
 import { TerminalManager } from "../../terminal/Services/Manager.ts";
 import { ProjectSetupScriptRunner } from "../Services/ProjectSetupScriptRunner.ts";
 import { ProjectSetupScriptRunnerLive } from "./ProjectSetupScriptRunner.ts";
 
-const emptySnapshot = (
-  scripts: OrchestrationReadModel["projects"][number]["scripts"],
-): OrchestrationReadModel =>
-  ({
-    snapshotSequence: 1,
-    updatedAt: "2026-01-01T00:00:00.000Z",
-    projects: [
-      {
-        id: "project-1",
-        title: "Project",
-        workspaceRoot: "/repo/project",
-        defaultModelSelection: null,
-        scripts,
-        createdAt: "2026-01-01T00:00:00.000Z",
-        updatedAt: "2026-01-01T00:00:00.000Z",
-        deletedAt: null,
-      },
-    ],
-    threads: [],
-    providerSessions: [],
-    providerStatuses: [],
-    pendingApprovals: [],
-    latestTurnByThreadId: {},
-  }) as unknown as OrchestrationReadModel;
+const makeProject = (scripts: OrchestrationProject["scripts"]): OrchestrationProject => ({
+  id: ProjectId.make("project-1"),
+  title: "Project",
+  workspaceRoot: "/repo/project",
+  defaultModelSelection: null,
+  scripts,
+  createdAt: "2026-01-01T00:00:00.000Z",
+  updatedAt: "2026-01-01T00:00:00.000Z",
+  deletedAt: null,
+});
+
+const makeProjectionSnapshotQueryLayer = (project: OrchestrationProject) =>
+  Layer.succeed(ProjectionSnapshotQuery, {
+    getCommandReadModel: () => Effect.die("unused"),
+    getSnapshot: () => Effect.die("unused"),
+    getShellSnapshot: () => Effect.die("unused"),
+    getArchivedShellSnapshot: () => Effect.die("unused"),
+    getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 1 }),
+    getCounts: () => Effect.die("unused"),
+    getActiveProjectByWorkspaceRoot: (workspaceRoot) =>
+      Effect.succeed(
+        workspaceRoot === project.workspaceRoot ? Option.some(project) : Option.none(),
+      ),
+    getProjectShellById: (projectId) =>
+      Effect.succeed(projectId === project.id ? Option.some(project) : Option.none()),
+    getFirstActiveThreadIdByProjectId: () => Effect.die("unused"),
+    getThreadCheckpointContext: () => Effect.die("unused"),
+    getFullThreadDiffContext: () => Effect.die("unused"),
+    getThreadShellById: () => Effect.die("unused"),
+    getThreadDetailById: () => Effect.die("unused"),
+  });
 
 describe("ProjectSetupScriptRunner", () => {
   it("returns no-script when no setup script exists", async () => {
     const open = vi.fn();
     const write = vi.fn();
+    const project = makeProject([]);
     const runner = await Effect.runPromise(
       Effect.service(ProjectSetupScriptRunner).pipe(
         Effect.provide(
           ProjectSetupScriptRunnerLive.pipe(
-            Layer.provideMerge(
-              Layer.succeed(OrchestrationEngineService, {
-                getReadModel: () => Effect.succeed(emptySnapshot([])),
-                readEvents: () => Stream.empty,
-                dispatch: () => Effect.die(new Error("unused")),
-                streamDomainEvents: Stream.empty,
-              }),
-            ),
+            Layer.provideMerge(makeProjectionSnapshotQueryLayer(project)),
             Layer.provideMerge(
               Layer.succeed(TerminalManager, {
                 open,
@@ -93,29 +96,20 @@ describe("ProjectSetupScriptRunner", () => {
       }),
     );
     const write = vi.fn(() => Effect.void);
+    const project = makeProject([
+      {
+        id: "setup",
+        name: "Setup",
+        command: "bun install",
+        icon: "configure",
+        runOnWorktreeCreate: true,
+      },
+    ]);
     const runner = await Effect.runPromise(
       Effect.service(ProjectSetupScriptRunner).pipe(
         Effect.provide(
           ProjectSetupScriptRunnerLive.pipe(
-            Layer.provideMerge(
-              Layer.succeed(OrchestrationEngineService, {
-                getReadModel: () =>
-                  Effect.succeed(
-                    emptySnapshot([
-                      {
-                        id: "setup",
-                        name: "Setup",
-                        command: "bun install",
-                        icon: "configure",
-                        runOnWorktreeCreate: true,
-                      },
-                    ]),
-                  ),
-                readEvents: () => Stream.empty,
-                dispatch: () => Effect.die(new Error("unused")),
-                streamDomainEvents: Stream.empty,
-              }),
-            ),
+            Layer.provideMerge(makeProjectionSnapshotQueryLayer(project)),
             Layer.provideMerge(
               Layer.succeed(TerminalManager, {
                 open,
diff --git a/apps/server/src/project/Layers/ProjectSetupScriptRunner.ts b/apps/server/src/project/Layers/ProjectSetupScriptRunner.ts
index 3bac8cf0abf..61cd043b43b 100644
--- a/apps/server/src/project/Layers/ProjectSetupScriptRunner.ts
+++ b/apps/server/src/project/Layers/ProjectSetupScriptRunner.ts
@@ -1,31 +1,40 @@
+import { ProjectId } from "@t3tools/contracts";
 import { projectScriptRuntimeEnv, setupProjectScript } from "@t3tools/shared/projectScripts";
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 
-import { OrchestrationEngineService } from "../../orchestration/Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
 import { TerminalManager } from "../../terminal/Services/Manager.ts";
 import {
   type ProjectSetupScriptRunnerShape,
   ProjectSetupScriptRunner,
+  ProjectSetupScriptRunnerError,
 } from "../Services/ProjectSetupScriptRunner.ts";
 
 const makeProjectSetupScriptRunner = Effect.gen(function* () {
-  const orchestrationEngine = yield* OrchestrationEngineService;
+  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
   const terminalManager = yield* TerminalManager;
 
   const runForThread: ProjectSetupScriptRunnerShape["runForThread"] = (input) =>
     Effect.gen(function* () {
-      const readModel = yield* orchestrationEngine.getReadModel();
       const project =
         (input.projectId
-          ? readModel.projects.find((entry) => entry.id === input.projectId)
+          ? yield* projectionSnapshotQuery
+              .getProjectShellById(ProjectId.make(input.projectId))
+              .pipe(Effect.map(Option.getOrUndefined))
           : null) ??
         (input.projectCwd
-          ? readModel.projects.find((entry) => entry.workspaceRoot === input.projectCwd)
+          ? yield* projectionSnapshotQuery
+              .getActiveProjectByWorkspaceRoot(input.projectCwd)
+              .pipe(Effect.map(Option.getOrUndefined))
           : null) ??
         null;
 
       if (!project) {
-        return yield* Effect.fail(new Error("Project was not found for setup script execution."));
+        return yield* new ProjectSetupScriptRunnerError({
+          message: "Project was not found for setup script execution.",
+        });
       }
 
       const script = setupProjectScript(project.scripts);
@@ -62,7 +71,26 @@ const makeProjectSetupScriptRunner = Effect.gen(function* () {
         terminalId,
         cwd,
       } as const;
-    });
+    }).pipe(
+      Effect.mapError((cause) => {
+        if (
+          typeof cause === "object" &&
+          cause !== null &&
+          "_tag" in cause &&
+          cause._tag === "ProjectSetupScriptRunnerError"
+        ) {
+          return cause as ProjectSetupScriptRunnerError;
+        }
+        const message =
+          typeof cause === "object" &&
+          cause !== null &&
+          "message" in cause &&
+          typeof cause.message === "string"
+            ? cause.message
+            : String(cause);
+        return new ProjectSetupScriptRunnerError({ message });
+      }),
+    );
 
   return {
     runForThread,
diff --git a/apps/server/src/project/Layers/RepositoryIdentityResolver.test.ts b/apps/server/src/project/Layers/RepositoryIdentityResolver.test.ts
index 57f4464804d..a47181c8667 100644
--- a/apps/server/src/project/Layers/RepositoryIdentityResolver.test.ts
+++ b/apps/server/src/project/Layers/RepositoryIdentityResolver.test.ts
@@ -1,17 +1,31 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
-import { Duration, Effect, FileSystem, Layer } from "effect";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 import { TestClock } from "effect/testing";
 
-import { runProcess } from "../../processRunner.ts";
+import * as ProcessRunner from "../../processRunner.ts";
 import { RepositoryIdentityResolver } from "../Services/RepositoryIdentityResolver.ts";
 import {
   makeRepositoryIdentityResolver,
   RepositoryIdentityResolverLive,
 } from "./RepositoryIdentityResolver.ts";
 
+const normalizePathSeparators = (value: string) => value.replaceAll("\\", "/");
+const normalizeResolvedPath = (value: string) => normalizePathSeparators(value);
+
 const git = (cwd: string, args: ReadonlyArray<string>) =>
-  Effect.promise(() => runProcess("git", ["-C", cwd, ...args]));
+  Effect.gen(function* () {
+    const processRunner = yield* ProcessRunner.ProcessRunner;
+    return yield* processRunner.run({
+      command: "git",
+      args: ["-C", cwd, ...args],
+      shell: process.platform === "win32",
+    });
+  }).pipe(Effect.provide(ProcessRunner.layer));
 
 const makeRepositoryIdentityResolverTestLayer = (options: {
   readonly positiveCacheTtl?: Duration.Input;
@@ -23,7 +37,7 @@ const makeRepositoryIdentityResolverTestLayer = (options: {
       cacheCapacity: 16,
       ...options,
     }),
-  );
+  ).pipe(Layer.provide(ProcessRunner.layer));
 
 it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
   it.effect("normalizes equivalent GitHub remotes into a stable repository identity", () =>
@@ -38,9 +52,13 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
 
       const resolver = yield* RepositoryIdentityResolver;
       const identity = yield* resolver.resolve(cwd);
+      const resolvedIdentityRoot =
+        identity?.rootPath === undefined ? "" : yield* fileSystem.realPath(identity.rootPath);
+      const resolvedCwd = yield* fileSystem.realPath(cwd);
 
       expect(identity).not.toBeNull();
       expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
+      expect(normalizeResolvedPath(resolvedIdentityRoot)).toBe(normalizeResolvedPath(resolvedCwd));
       expect(identity?.displayName).toBe("t3tools/t3code");
       expect(identity?.provider).toBe("github");
       expect(identity?.owner).toBe("t3tools");
@@ -48,6 +66,33 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
     }).pipe(Effect.provide(RepositoryIdentityResolverLive)),
   );
 
+  it.effect("returns the git top-level root path when resolving from a nested workspace", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const repoRoot = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-repository-identity-nested-root-test-",
+      });
+      const nestedWorkspace = path.join(repoRoot, "packages", "web");
+
+      yield* fileSystem.makeDirectory(nestedWorkspace, { recursive: true });
+      yield* git(repoRoot, ["init"]);
+      yield* git(repoRoot, ["remote", "add", "origin", "git@github.com:T3Tools/t3code.git"]);
+
+      const resolver = yield* RepositoryIdentityResolver;
+      const identity = yield* resolver.resolve(nestedWorkspace);
+      const resolvedIdentityRoot =
+        identity?.rootPath === undefined ? "" : yield* fileSystem.realPath(identity.rootPath);
+      const resolvedRepoRoot = yield* fileSystem.realPath(repoRoot);
+
+      expect(identity).not.toBeNull();
+      expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
+      expect(normalizeResolvedPath(resolvedIdentityRoot)).toBe(
+        normalizeResolvedPath(resolvedRepoRoot),
+      );
+    }).pipe(Effect.provide(RepositoryIdentityResolverLive)),
+  );
+
   it.effect("returns null for non-git folders and repos without remotes", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
@@ -112,7 +157,7 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
   );
 
   it.effect(
-    "refreshes cached null identities after the negative TTL when a remote is configured later",
+    "keeps null identities cached across repeated resolves until the negative TTL expires",
     () =>
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
@@ -128,8 +173,10 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
 
         yield* git(cwd, ["remote", "add", "origin", "git@github.com:T3Tools/t3code.git"]);
 
-        const cachedIdentity = yield* resolver.resolve(cwd);
-        expect(cachedIdentity).toBeNull();
+        for (const _attempt of [1, 2, 3]) {
+          const cachedIdentity = yield* resolver.resolve(cwd);
+          expect(cachedIdentity).toBeNull();
+        }
 
         yield* TestClock.adjust(Duration.millis(120));
 
diff --git a/apps/server/src/project/Layers/RepositoryIdentityResolver.ts b/apps/server/src/project/Layers/RepositoryIdentityResolver.ts
index 531737ec66c..926c1d0c2ec 100644
--- a/apps/server/src/project/Layers/RepositoryIdentityResolver.ts
+++ b/apps/server/src/project/Layers/RepositoryIdentityResolver.ts
@@ -1,8 +1,15 @@
 import type { RepositoryIdentity } from "@t3tools/contracts";
-import { Cache, Duration, Effect, Exit, Layer } from "effect";
-import { detectGitHostingProviderFromRemoteUrl, normalizeGitRemoteUrl } from "@t3tools/shared/git";
+import * as Cache from "effect/Cache";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import {
+  detectSourceControlProviderFromGitRemoteUrl,
+  normalizeGitRemoteUrl,
+} from "@t3tools/shared/git";
 
-import { runProcess } from "../../processRunner.ts";
+import * as ProcessRunner from "../../processRunner.ts";
 import {
   RepositoryIdentityResolver,
   type RepositoryIdentityResolverShape,
@@ -42,9 +49,10 @@ function pickPrimaryRemote(
 function buildRepositoryIdentity(input: {
   readonly remoteName: string;
   readonly remoteUrl: string;
+  readonly rootPath: string;
 }): RepositoryIdentity {
   const canonicalKey = normalizeGitRemoteUrl(input.remoteUrl);
-  const hostingProvider = detectGitHostingProviderFromRemoteUrl(input.remoteUrl);
+  const sourceControlProvider = detectSourceControlProviderFromGitRemoteUrl(input.remoteUrl);
   const repositoryPath = canonicalKey.split("/").slice(1).join("/");
   const repositoryPathSegments = repositoryPath.split("/").filter((segment) => segment.length > 0);
   const [owner] = repositoryPathSegments;
@@ -57,8 +65,9 @@ function buildRepositoryIdentity(input: {
       remoteName: input.remoteName,
       remoteUrl: input.remoteUrl,
     },
+    rootPath: input.rootPath,
     ...(repositoryPath ? { displayName: repositoryPath } : {}),
-    ...(hostingProvider ? { provider: hostingProvider.kind } : {}),
+    ...(sourceControlProvider ? { provider: sourceControlProvider.kind } : {}),
     ...(owner ? { owner } : {}),
     ...(repositoryName ? { name: repositoryName } : {}),
   };
@@ -66,7 +75,7 @@ function buildRepositoryIdentity(input: {
 
 const DEFAULT_REPOSITORY_IDENTITY_CACHE_CAPACITY = 512;
 const DEFAULT_POSITIVE_CACHE_TTL = Duration.minutes(1);
-const DEFAULT_NEGATIVE_CACHE_TTL = Duration.seconds(10);
+const DEFAULT_NEGATIVE_CACHE_TTL = Duration.minutes(1);
 
 interface RepositoryIdentityResolverOptions {
   readonly cacheCapacity?: number;
@@ -74,50 +83,63 @@ interface RepositoryIdentityResolverOptions {
   readonly negativeCacheTtl?: Duration.Input;
 }
 
-async function resolveRepositoryIdentityCacheKey(cwd: string): Promise<string> {
+const resolveRepositoryIdentityCacheKey = Effect.fn("resolveRepositoryIdentityCacheKey")(function* (
+  cwd: string,
+) {
+  const processRunner = yield* ProcessRunner.ProcessRunner;
   let cacheKey = cwd;
 
-  try {
-    const topLevelResult = await runProcess("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
-      allowNonZeroExit: true,
-    });
-    if (topLevelResult.code !== 0) {
-      return cacheKey;
-    }
-
-    const candidate = topLevelResult.stdout.trim();
-    if (candidate.length > 0) {
-      cacheKey = candidate;
-    }
-  } catch {
+  const topLevelResult = yield* processRunner
+    .run({
+      command: "git",
+      args: ["-C", cwd, "rev-parse", "--show-toplevel"],
+      timeoutBehavior: "timedOutResult",
+      shell: process.platform === "win32",
+    })
+    .pipe(Effect.option);
+  if (topLevelResult._tag === "None" || topLevelResult.value.code !== 0) {
     return cacheKey;
   }
 
-  return cacheKey;
-}
+  const candidate = topLevelResult.value.stdout.trim();
+  if (candidate.length > 0) {
+    cacheKey = candidate;
+  }
 
-async function resolveRepositoryIdentityFromCacheKey(
-  cacheKey: string,
-): Promise<RepositoryIdentity | null> {
-  try {
-    const remoteResult = await runProcess("git", ["-C", cacheKey, "remote", "-v"], {
-      allowNonZeroExit: true,
-    });
-    if (remoteResult.code !== 0) {
+  return cacheKey;
+});
+
+const resolveRepositoryIdentityFromCacheKey = Effect.fn("resolveRepositoryIdentityFromCacheKey")(
+  function* (
+    cacheKey: string,
+  ): Effect.fn.Return<RepositoryIdentity | null, never, ProcessRunner.ProcessRunner> {
+    const processRunner = yield* ProcessRunner.ProcessRunner;
+    const remoteResult = yield* processRunner
+      .run({
+        command: "git",
+        args: ["-C", cacheKey, "remote", "-v"],
+        timeoutBehavior: "timedOutResult",
+        shell: process.platform === "win32",
+      })
+      .pipe(Effect.option);
+    if (remoteResult._tag === "None" || remoteResult.value.code !== 0) {
       return null;
     }
 
-    const remote = pickPrimaryRemote(parseRemoteFetchUrls(remoteResult.stdout));
-    return remote ? buildRepositoryIdentity(remote) : null;
-  } catch {
-    return null;
-  }
-}
+    const remote = pickPrimaryRemote(parseRemoteFetchUrls(remoteResult.value.stdout));
+    return remote ? buildRepositoryIdentity({ ...remote, rootPath: cacheKey }) : null;
+  },
+);
 
 export const makeRepositoryIdentityResolver = Effect.fn("makeRepositoryIdentityResolver")(
   function* (options: RepositoryIdentityResolverOptions = {}) {
+    const processRunner = yield* ProcessRunner.ProcessRunner;
+
     const repositoryIdentityCache = yield* Cache.makeWith<string, RepositoryIdentity | null>(
-      (cacheKey) => Effect.promise(() => resolveRepositoryIdentityFromCacheKey(cacheKey)),
+      (cacheKey) =>
+        resolveRepositoryIdentityFromCacheKey(cacheKey).pipe(
+          Effect.provideService(ProcessRunner.ProcessRunner, processRunner),
+        ),
       {
         capacity: options.cacheCapacity ?? DEFAULT_REPOSITORY_IDENTITY_CACHE_CAPACITY,
         timeToLive: Exit.match({
@@ -133,7 +155,9 @@ export const makeRepositoryIdentityResolver = Effect.fn("makeRepositoryIdentityR
     const resolve: RepositoryIdentityResolverShape["resolve"] = Effect.fn(
       "RepositoryIdentityResolver.resolve",
     )(function* (cwd) {
-      const cacheKey = yield* Effect.promise(() => resolveRepositoryIdentityCacheKey(cwd));
+      const cacheKey = yield* resolveRepositoryIdentityCacheKey(cwd).pipe(
+        Effect.provideService(ProcessRunner.ProcessRunner, processRunner),
+      );
       return yield* Cache.get(repositoryIdentityCache, cacheKey);
     });
 
@@ -146,4 +170,4 @@ export const makeRepositoryIdentityResolver = Effect.fn("makeRepositoryIdentityR
 export const RepositoryIdentityResolverLive = Layer.effect(
   RepositoryIdentityResolver,
   makeRepositoryIdentityResolver(),
-);
+).pipe(Layer.provide(ProcessRunner.layer));
diff --git a/apps/server/src/project/Services/ProjectFaviconResolver.ts b/apps/server/src/project/Services/ProjectFaviconResolver.ts
index c05dfe8f1fd..ad1b466e2c7 100644
--- a/apps/server/src/project/Services/ProjectFaviconResolver.ts
+++ b/apps/server/src/project/Services/ProjectFaviconResolver.ts
@@ -6,8 +6,8 @@
  *
  * @module ProjectFaviconResolver
  */
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 /**
  * ProjectFaviconResolverShape - Service API for project favicon lookup.
diff --git a/apps/server/src/project/Services/ProjectSetupScriptRunner.ts b/apps/server/src/project/Services/ProjectSetupScriptRunner.ts
index acba335a6e7..184c75b5019 100644
--- a/apps/server/src/project/Services/ProjectSetupScriptRunner.ts
+++ b/apps/server/src/project/Services/ProjectSetupScriptRunner.ts
@@ -1,5 +1,6 @@
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import type * as Effect from "effect/Effect";
 
 export interface ProjectSetupScriptRunnerResultNoScript {
   readonly status: "no-script";
@@ -25,10 +26,16 @@ export interface ProjectSetupScriptRunnerInput {
   readonly preferredTerminalId?: string;
 }
 
+export class ProjectSetupScriptRunnerError extends Data.TaggedError(
+  "ProjectSetupScriptRunnerError",
+)<{
+  readonly message: string;
+}> {}
+
 export interface ProjectSetupScriptRunnerShape {
   readonly runForThread: (
     input: ProjectSetupScriptRunnerInput,
-  ) => Effect.Effect<ProjectSetupScriptRunnerResult, Error>;
+  ) => Effect.Effect<ProjectSetupScriptRunnerResult, ProjectSetupScriptRunnerError>;
 }
 
 export class ProjectSetupScriptRunner extends Context.Service<
diff --git a/apps/server/src/project/Services/RepositoryIdentityResolver.ts b/apps/server/src/project/Services/RepositoryIdentityResolver.ts
index d3eea846199..ef0b128c6f7 100644
--- a/apps/server/src/project/Services/RepositoryIdentityResolver.ts
+++ b/apps/server/src/project/Services/RepositoryIdentityResolver.ts
@@ -1,6 +1,6 @@
 import type { RepositoryIdentity } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 export interface RepositoryIdentityResolverShape {
   readonly resolve: (cwd: string) => Effect.Effect<RepositoryIdentity | null>;
diff --git a/apps/server/src/provider/CodexDeveloperInstructions.ts b/apps/server/src/provider/CodexDeveloperInstructions.ts
new file mode 100644
index 00000000000..76055f8b8be
--- /dev/null
+++ b/apps/server/src/provider/CodexDeveloperInstructions.ts
@@ -0,0 +1,134 @@
+export const CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Plan Mode (Conversational)
+
+You work in 3 phases, and you should *chat your way* to a great plan before finalizing it. A great plan is very detailed-intent- and implementation-wise-so that it can be handed to another engineer or agent to be implemented right away. It must be **decision complete**, where the implementer does not need to make any decisions.
+
+## Mode rules (strict)
+
+You are in **Plan Mode** until a developer message explicitly ends it.
+
+Plan Mode is not changed by user intent, tone, or imperative language. If a user asks for execution while still in Plan Mode, treat it as a request to **plan the execution**, not perform it.
+
+## Plan Mode vs update_plan tool
+
+Plan Mode is a collaboration mode that can involve requesting user input and eventually issuing a \`<proposed_plan>\` block.
+
+Separately, \`update_plan\` is a checklist/progress/TODOs tool; it does not enter or exit Plan Mode. Do not confuse it with Plan mode or try to use it while in Plan mode. If you try to use \`update_plan\` in Plan mode, it will return an error.
+
+## Execution vs. mutation in Plan Mode
+
+You may explore and execute **non-mutating** actions that improve the plan. You must not perform **mutating** actions.
+
+### Allowed (non-mutating, plan-improving)
+
+Actions that gather truth, reduce ambiguity, or validate feasibility without changing repo-tracked state. Examples:
+
+* Reading or searching files, configs, schemas, types, manifests, and docs
+* Static analysis, inspection, and repo exploration
+* Dry-run style commands when they do not edit repo-tracked files
+* Tests, builds, or checks that may write to caches or build artifacts (for example, \`target/\`, \`.cache/\`, or snapshots) so long as they do not edit repo-tracked files
+
+### Not allowed (mutating, plan-executing)
+
+Actions that implement the plan or change repo-tracked state. Examples:
+
+* Editing or writing files
+* Running formatters or linters that rewrite files
+* Applying patches, migrations, or codegen that updates repo-tracked files
+* Side-effectful commands whose purpose is to carry out the plan rather than refine it
+
+When in doubt: if the action would reasonably be described as "doing the work" rather than "planning the work," do not do it.
+
+## PHASE 1 - Ground in the environment (explore first, ask second)
+
+Begin by grounding yourself in the actual environment. Eliminate unknowns in the prompt by discovering facts, not by asking the user. Resolve all questions that can be answered through exploration or inspection. Identify missing or ambiguous details only if they cannot be derived from the environment. Silent exploration between turns is allowed and encouraged.
+
+Before asking the user any question, perform at least one targeted non-mutating exploration pass (for example: search relevant files, inspect likely entrypoints/configs, confirm current implementation shape), unless no local environment/repo is available.
+
+Exception: you may ask clarifying questions about the user's prompt before exploring, ONLY if there are obvious ambiguities or contradictions in the prompt itself. However, if ambiguity might be resolved by exploring, always prefer exploring first.
+
+Do not ask questions that can be answered from the repo or system (for example, "where is this struct?" or "which UI component should we use?" when exploration can make it clear). Only ask once you have exhausted reasonable non-mutating exploration.
+
+## PHASE 2 - Intent chat (what they actually want)
+
+* Keep asking until you can clearly state: goal + success criteria, audience, in/out of scope, constraints, current state, and the key preferences/tradeoffs.
+* Bias toward questions over guessing: if any high-impact ambiguity remains, do NOT plan yet-ask.
+
+## PHASE 3 - Implementation chat (what/how we'll build)
+
+* Once intent is stable, keep asking until the spec is decision complete: approach, interfaces (APIs/schemas/I/O), data flow, edge cases/failure modes, testing + acceptance criteria, rollout/monitoring, and any migrations/compat constraints.
+
+## Asking questions
+
+Critical rules:
+
+* Strongly prefer using the \`request_user_input\` tool to ask any questions.
+* Offer only meaningful multiple-choice options; don't include filler choices that are obviously wrong or irrelevant.
+* In rare cases where an unavoidable, important question can't be expressed with reasonable multiple-choice options (due to extreme ambiguity), you may ask it directly without the tool.
+
+You SHOULD ask many questions, but each question must:
+
+* materially change the spec/plan, OR
+* confirm/lock an assumption, OR
+* choose between meaningful tradeoffs.
+* not be answerable by non-mutating commands.
+
+Use the \`request_user_input\` tool only for decisions that materially change the plan, for confirming important assumptions, or for information that cannot be discovered via non-mutating exploration.
+
+## Two kinds of unknowns (treat differently)
+
+1. **Discoverable facts** (repo/system truth): explore first.
+
+   * Before asking, run targeted searches and check likely sources of truth (configs/manifests/entrypoints/schemas/types/constants).
+   * Ask only if: multiple plausible candidates; nothing found but you need a missing identifier/context; or ambiguity is actually product intent.
+   * If asking, present concrete candidates (paths/service names) + recommend one.
+   * Never ask questions you can answer from your environment (e.g., "where is this struct").
+
+2. **Preferences/tradeoffs** (not discoverable): ask early.
+
+   * These are intent or implementation preferences that cannot be derived from exploration.
+   * Provide 2-4 mutually exclusive options + a recommended default.
+   * If unanswered, proceed with the recommended option and record it as an assumption in the final plan.
+
+## Finalization rule
+
+Only output the final plan when it is decision complete and leaves no decisions to the implementer.
+
+When you present the official plan, wrap it in a \`<proposed_plan>\` block so the client can render it specially:
+
+1) The opening tag must be on its own line.
+2) Start the plan content on the next line (no text on the same line as the tag).
+3) The closing tag must be on its own line.
+4) Use Markdown inside the block.
+5) Keep the tags exactly as \`<proposed_plan>\` and \`</proposed_plan>\` (do not translate or rename them), even if the plan content is in another language.
+
+Example:
+
+<proposed_plan>
+plan content
+</proposed_plan>
+
+plan content should be human and agent digestible. The final plan must be plan-only and include:
+
+* A clear title
+* A brief summary section
+* Important changes or additions to public APIs/interfaces/types
+* Test cases and scenarios
+* Explicit assumptions and defaults chosen where needed
+
+Do not ask "should I proceed?" in the final output. The user can easily switch out of Plan mode and request implementation if you have included a \`<proposed_plan>\` block in your response. Alternatively, they can decide to stay in Plan mode and continue refining the plan.
+
+Only produce at most one \`<proposed_plan>\` block per turn, and only when you are presenting a complete spec.
+</collaboration_mode>`;
+
+export const CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Collaboration Mode: Default
+
+You are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.
+
+Your active mode changes only when new developer instructions with a different \`<collaboration_mode>...</collaboration_mode>\` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are Default and Plan.
+
+## request_user_input availability
+
+The \`request_user_input\` tool is unavailable in Default mode. If you call it while in Default mode, it will return an error.
+
+In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.
+</collaboration_mode>`;
diff --git a/apps/server/src/provider/Drivers/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
new file mode 100644
index 00000000000..e3f15d865c9
--- /dev/null
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -0,0 +1,205 @@
+/**
+ * ClaudeDriver — `ProviderDriver` for the Claude Agent SDK runtime.
+ *
+ * Mirrors `CodexDriver`: a plain value whose `create()` returns one
+ * `ProviderInstance` bundling `snapshot` / `adapter` / `textGeneration`
+ * closures captured over the per-instance `ClaudeSettings`.
+ *
+ * Unlike Codex, the Claude snapshot probe may invoke a secondary probe
+ * (`probeClaudeCapabilities`) to read Anthropic account + slash-command
+ * metadata. That probe is per-instance and keyed by binary + resolved HOME so
+ * two concurrent Claude instances don't cross-contaminate account metadata.
+ *
+ * @module provider/Drivers/ClaudeDriver
+ */
+import { ClaudeSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
+import * as Cache from "effect/Cache";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { makeClaudeTextGeneration } from "../../textGeneration/ClaudeTextGeneration.ts";
+import { ServerConfig } from "../../config.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeClaudeAdapter } from "../Layers/ClaudeAdapter.ts";
+import {
+  checkClaudeProviderStatus,
+  makePendingClaudeProvider,
+  probeClaudeCapabilities,
+} from "../Layers/ClaudeProvider.ts";
+import { ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
+import {
+  defaultProviderContinuationIdentity,
+  type ProviderDriver,
+  type ProviderInstance,
+} from "../ProviderDriver.ts";
+import type { ServerProviderDraft } from "../providerSnapshot.ts";
+import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+  enrichProviderSnapshotWithVersionAdvisory,
+  makePackageManagedProviderMaintenanceResolver,
+  normalizeCommandPath,
+  resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
+import { makeClaudeCapabilitiesCacheKey, makeClaudeContinuationGroupKey } from "./ClaudeHome.ts";
+const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
+
+const DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+const CAPABILITIES_PROBE_TTL = Duration.minutes(5);
+
+function isClaudeNativeCommandPath(commandPath: string): boolean {
+  const normalized = normalizeCommandPath(commandPath);
+  return (
+    normalized.endsWith("/.local/bin/claude") ||
+    normalized.endsWith("/.local/bin/claude.exe") ||
+    normalized.includes("/.local/share/claude/")
+  );
+}
+
+const UPDATE = makePackageManagedProviderMaintenanceResolver({
+  provider: DRIVER_KIND,
+  npmPackageName: "@anthropic-ai/claude-code",
+  homebrewFormula: "claude-code",
+  nativeUpdate: {
+    executable: "claude",
+    args: ["update"],
+    lockKey: "claude-native",
+    isCommandPath: isClaudeNativeCommandPath,
+  },
+});
+
+export type ClaudeDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | HttpClient.HttpClient
+  | Path.Path
+  | ProviderEventLoggers
+  | ServerConfig;
+
+const withInstanceIdentity =
+  (input: {
+    readonly instanceId: ProviderInstance["instanceId"];
+    readonly displayName: string | undefined;
+    readonly accentColor: string | undefined;
+    readonly continuationGroupKey: string;
+  }) =>
+  (snapshot: ServerProviderDraft): ServerProvider => ({
+    ...snapshot,
+    instanceId: input.instanceId,
+    driver: DRIVER_KIND,
+    ...(input.displayName ? { displayName: input.displayName } : {}),
+    ...(input.accentColor ? { accentColor: input.accentColor } : {}),
+    continuation: { groupKey: input.continuationGroupKey },
+  });
+
+export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "Claude",
+    supportsMultipleInstances: true,
+  },
+  configSchema: ClaudeSettings,
+  defaultConfig: (): ClaudeSettings => decodeClaudeSettings({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const path = yield* Path.Path;
+      const httpClient = yield* HttpClient.HttpClient;
+      const eventLoggers = yield* ProviderEventLoggers;
+      const processEnv = mergeProviderInstanceEnvironment(environment);
+      const fallbackContinuationIdentity = defaultProviderContinuationIdentity({
+        driverKind: DRIVER_KIND,
+        instanceId,
+      });
+      const effectiveConfig = { ...config, enabled } satisfies ClaudeSettings;
+      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+        binaryPath: effectiveConfig.binaryPath,
+        env: processEnv,
+      });
+      const continuationGroupKey = yield* makeClaudeContinuationGroupKey(effectiveConfig);
+      const stampIdentity = withInstanceIdentity({
+        instanceId,
+        displayName,
+        accentColor,
+        continuationGroupKey,
+      });
+
+      const adapterOptions = {
+        instanceId,
+        environment: processEnv,
+        ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
+      };
+      const adapter = yield* makeClaudeAdapter(effectiveConfig, adapterOptions);
+      const textGeneration = yield* makeClaudeTextGeneration(effectiveConfig, processEnv);
+
+      // Per-instance capabilities cache: keyed on binary + resolved HOME so
+      // account-specific probes never share auth metadata across instances.
+      const capabilitiesProbeCache = yield* Cache.make({
+        capacity: 1,
+        timeToLive: CAPABILITIES_PROBE_TTL,
+        lookup: () =>
+          probeClaudeCapabilities(effectiveConfig, processEnv).pipe(
+            Effect.provideService(Path.Path, path),
+          ),
+      });
+      const capabilitiesCacheKey = yield* makeClaudeCapabilitiesCacheKey(effectiveConfig);
+
+      const checkProvider = checkClaudeProviderStatus(
+        effectiveConfig,
+        () => Cache.get(capabilitiesProbeCache, capabilitiesCacheKey),
+        processEnv,
+      ).pipe(
+        Effect.map(stampIdentity),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+        Effect.provideService(Path.Path, path),
+      );
+
+      const snapshot = yield* makeManagedServerProvider<ClaudeSettings>({
+        maintenanceCapabilities,
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) =>
+          makePendingClaudeProvider(settings).pipe(Effect.map(stampIdentity)),
+        checkProvider,
+        enrichSnapshot: ({ snapshot, publishSnapshot }) =>
+          enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities).pipe(
+            Effect.provideService(HttpClient.HttpClient, httpClient),
+            Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
+          ),
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build Claude snapshot: ${cause.message ?? String(cause)}`,
+              cause,
+            }),
+        ),
+      );
+
+      return {
+        instanceId,
+        driverKind: DRIVER_KIND,
+        continuationIdentity: {
+          ...fallbackContinuationIdentity,
+          continuationKey: continuationGroupKey,
+        },
+        displayName,
+        accentColor,
+        enabled,
+        snapshot,
+        adapter,
+        textGeneration,
+      } satisfies ProviderInstance;
+    }),
+};
diff --git a/apps/server/src/provider/Drivers/ClaudeHome.test.ts b/apps/server/src/provider/Drivers/ClaudeHome.test.ts
new file mode 100644
index 00000000000..87298f80125
--- /dev/null
+++ b/apps/server/src/provider/Drivers/ClaudeHome.test.ts
@@ -0,0 +1,53 @@
+import * as NodeOS from "node:os";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+
+import {
+  makeClaudeCapabilitiesCacheKey,
+  makeClaudeContinuationGroupKey,
+  makeClaudeEnvironment,
+  resolveClaudeHomePath,
+} from "./ClaudeHome.ts";
+
+it.layer(NodeServices.layer)("ClaudeHome", (it) => {
+  describe("Claude home resolution", () => {
+    it.effect("uses the process home when no Claude home override is configured", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const resolved = path.resolve(NodeOS.homedir());
+
+        expect(yield* resolveClaudeHomePath({ homePath: "" })).toBe(resolved);
+        expect(yield* makeClaudeEnvironment({ homePath: "" })).toBe(process.env);
+      }),
+    );
+
+    it.effect("resolves configured Claude HOME and stamps continuation/cache keys with it", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const homePath = "~/.claude-work";
+        const resolved = path.resolve(NodeOS.homedir(), ".claude-work");
+
+        expect(yield* resolveClaudeHomePath({ homePath })).toBe(resolved);
+        expect((yield* makeClaudeEnvironment({ homePath })).HOME).toBe(resolved);
+        expect(yield* makeClaudeContinuationGroupKey({ homePath })).toBe(`claude:home:${resolved}`);
+        expect(yield* makeClaudeCapabilitiesCacheKey({ binaryPath: "claude", homePath })).toBe(
+          `claude\0${resolved}`,
+        );
+      }),
+    );
+
+    it.effect("keeps continuation compatible across instances with the same Claude HOME", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const resolved = path.resolve(NodeOS.homedir());
+
+        expect(yield* makeClaudeContinuationGroupKey({ homePath: "" })).toBe(
+          `claude:home:${resolved}`,
+        );
+      }),
+    );
+  });
+});
diff --git a/apps/server/src/provider/Drivers/ClaudeHome.ts b/apps/server/src/provider/Drivers/ClaudeHome.ts
new file mode 100644
index 00000000000..9a4d1ce9cdf
--- /dev/null
+++ b/apps/server/src/provider/Drivers/ClaudeHome.ts
@@ -0,0 +1,44 @@
+import * as NodeOS from "node:os";
+
+import type { ClaudeSettings } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+
+import { expandHomePath } from "../../pathExpansion.ts";
+
+export const resolveClaudeHomePath = Effect.fn("resolveClaudeHomePath")(function* (
+  config: Pick<ClaudeSettings, "homePath">,
+): Effect.fn.Return<string, never, Path.Path> {
+  const path = yield* Path.Path;
+  const homePath = config.homePath.trim();
+  return path.resolve(homePath.length > 0 ? expandHomePath(homePath) : NodeOS.homedir());
+});
+
+export const makeClaudeEnvironment = Effect.fn("makeClaudeEnvironment")(function* (
+  config: Pick<ClaudeSettings, "homePath">,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<NodeJS.ProcessEnv, never, Path.Path> {
+  const homePath = config.homePath.trim();
+  if (homePath.length === 0) return baseEnv;
+  const resolvedHomePath = yield* resolveClaudeHomePath(config);
+  return {
+    ...baseEnv,
+    HOME: resolvedHomePath,
+  };
+});
+
+export const makeClaudeContinuationGroupKey = Effect.fn("makeClaudeContinuationGroupKey")(
+  function* (config: Pick<ClaudeSettings, "homePath">): Effect.fn.Return<string, never, Path.Path> {
+    const resolvedHomePath = yield* resolveClaudeHomePath(config);
+    return `claude:home:${resolvedHomePath}`;
+  },
+);
+
+export const makeClaudeCapabilitiesCacheKey = Effect.fn("makeClaudeCapabilitiesCacheKey")(
+  function* (
+    config: Pick<ClaudeSettings, "binaryPath" | "homePath">,
+  ): Effect.fn.Return<string, never, Path.Path> {
+    const resolvedHomePath = yield* resolveClaudeHomePath(config);
+    return `${config.binaryPath}\0${resolvedHomePath}`;
+  },
+);
diff --git a/apps/server/src/provider/Drivers/CodexDriver.ts b/apps/server/src/provider/Drivers/CodexDriver.ts
new file mode 100644
index 00000000000..48bc19e5612
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexDriver.ts
@@ -0,0 +1,202 @@
+/**
+ * CodexDriver — first concrete `ProviderDriver` in the new per-instance model.
+ *
+ * A driver is a plain value (not a Context.Service) whose `create()` returns
+ * one `ProviderInstance` bundling:
+ *   - `snapshot`   — the live `ServerProviderShape` for this instance;
+ *   - `adapter`    — the Codex session/turn/approval runtime;
+ *   - `textGeneration` — commit/PR/branch/title generation via `codex exec`.
+ *
+ * Each call to `create()` captures the `codexConfig` argument in closures
+ * owned by the returned instance. Two instances created with different
+ * `homePath`s (e.g. `codex_personal` + `codex_work`) therefore run with
+ * fully independent Codex app-server processes and `CODEX_HOME`
+ * environments — no shared mutable state.
+ *
+ * Resource lifecycle: `create()` runs in a scope handed in by the registry.
+ * Closing that scope releases the adapter's child processes, the managed
+ * snapshot's refresh fibre, and the text-generation binaries' transient
+ * scratch files. The registry uses this to tear down an instance when its
+ * `providerInstances` entry disappears or its config changes.
+ *
+ * @module provider/Drivers/CodexDriver
+ */
+import { CodexSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { makeCodexTextGeneration } from "../../textGeneration/CodexTextGeneration.ts";
+import { ServerConfig } from "../../config.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeCodexAdapter } from "../Layers/CodexAdapter.ts";
+import { checkCodexProviderStatus, makePendingCodexProvider } from "../Layers/CodexProvider.ts";
+import { ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
+import type { ProviderDriver, ProviderInstance } from "../ProviderDriver.ts";
+import type { ServerProviderDraft } from "../providerSnapshot.ts";
+import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+  enrichProviderSnapshotWithVersionAdvisory,
+  makePackageManagedProviderMaintenanceResolver,
+  resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
+import {
+  codexContinuationIdentity,
+  materializeCodexShadowHome,
+  resolveCodexHomeLayout,
+} from "./CodexHomeLayout.ts";
+const decodeCodexSettings = Schema.decodeSync(CodexSettings);
+
+const DRIVER_KIND = ProviderDriverKind.make("codex");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+const UPDATE = makePackageManagedProviderMaintenanceResolver({
+  provider: DRIVER_KIND,
+  npmPackageName: "@openai/codex",
+  homebrewFormula: "codex",
+  nativeUpdate: null,
+});
+
+/**
+ * Services the driver needs to materialize an instance. Surfaced as the
+ * driver's `R` so the registry layer aggregates these across every
+ * registered driver and the runtime satisfies them once.
+ */
+export type CodexDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | HttpClient.HttpClient
+  | Path.Path
+  | ProviderEventLoggers
+  | ServerConfig;
+
+/**
+ * Stamp instance identity onto a `ServerProvider` snapshot produced by the
+ * driver-kind-only codex helpers. Once `buildServerProvider` in
+ * `providerSnapshot.ts` is widened to accept `instanceId`/`driver`, this
+ * wrapper disappears.
+ */
+const withInstanceIdentity =
+  (input: {
+    readonly instanceId: ProviderInstance["instanceId"];
+    readonly displayName: string | undefined;
+    readonly accentColor: string | undefined;
+    readonly continuationGroupKey: string;
+  }) =>
+  (snapshot: ServerProviderDraft): ServerProvider => ({
+    ...snapshot,
+    instanceId: input.instanceId,
+    driver: DRIVER_KIND,
+    ...(input.displayName ? { displayName: input.displayName } : {}),
+    ...(input.accentColor ? { accentColor: input.accentColor } : {}),
+    continuation: { groupKey: input.continuationGroupKey },
+  });
+
+export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "Codex",
+    supportsMultipleInstances: true,
+  },
+  configSchema: CodexSettings,
+  defaultConfig: (): CodexSettings => decodeCodexSettings({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const httpClient = yield* HttpClient.HttpClient;
+      const eventLoggers = yield* ProviderEventLoggers;
+      const processEnv = mergeProviderInstanceEnvironment(environment);
+      const homeLayout = yield* resolveCodexHomeLayout(config);
+      const continuationIdentity = codexContinuationIdentity(homeLayout);
+      const stampIdentity = withInstanceIdentity({
+        instanceId,
+        displayName,
+        accentColor,
+        continuationGroupKey: continuationIdentity.continuationKey,
+      });
+      yield* materializeCodexShadowHome(homeLayout).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: cause.message,
+              cause,
+            }),
+        ),
+      );
+      const effectiveConfig = {
+        ...config,
+        enabled,
+        homePath: homeLayout.effectiveHomePath ?? "",
+      } satisfies CodexSettings;
+      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+        binaryPath: effectiveConfig.binaryPath,
+        env: processEnv,
+      });
+
+      // `makeCodexAdapter` and `makeCodexTextGeneration` have `never` error
+      // channels at construction time — their failure modes are all on the
+      // per-operation closures they return. No `mapError` wrapper is needed
+      // here; the registry only has to worry about snapshot-build and
+      // spawner-availability failures surfaced from `checkCodexProviderStatus`
+      // below.
+      const adapter = yield* makeCodexAdapter(effectiveConfig, {
+        instanceId,
+        environment: processEnv,
+        ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
+      });
+      const textGeneration = yield* makeCodexTextGeneration(effectiveConfig, processEnv);
+
+      // Build a managed snapshot whose settings never change — mutations come
+      // in as instance rebuilds from the registry rather than in-place
+      // updates. Pre-provide `ChildProcessSpawner` so the check fits
+      // `makeManagedServerProvider.checkProvider`'s `R = never`.
+      const checkProvider = checkCodexProviderStatus(effectiveConfig, undefined, processEnv).pipe(
+        Effect.map(stampIdentity),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+      );
+      const snapshot = yield* makeManagedServerProvider<CodexSettings>({
+        maintenanceCapabilities,
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) =>
+          makePendingCodexProvider(settings).pipe(Effect.map(stampIdentity)),
+        checkProvider,
+        enrichSnapshot: ({ snapshot, publishSnapshot }) =>
+          enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities).pipe(
+            Effect.provideService(HttpClient.HttpClient, httpClient),
+            Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
+          ),
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build Codex snapshot: ${cause.message ?? String(cause)}`,
+              cause,
+            }),
+        ),
+      );
+
+      return {
+        instanceId,
+        driverKind: DRIVER_KIND,
+        continuationIdentity,
+        displayName,
+        accentColor,
+        enabled,
+        snapshot,
+        adapter,
+        textGeneration,
+      } satisfies ProviderInstance;
+    }),
+};
diff --git a/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
new file mode 100644
index 00000000000..12e98293b12
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
@@ -0,0 +1,213 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+import { CodexSettings } from "@t3tools/contracts";
+import {
+  CodexShadowHomeError,
+  materializeCodexShadowHome,
+  resolveCodexHomeLayout,
+} from "./CodexHomeLayout.ts";
+const decodeCodexSettingsValue = Schema.decodeSync(CodexSettings);
+
+const decodeCodexSettings = (input: {
+  readonly enabled?: boolean;
+  readonly homePath?: string;
+  readonly shadowHomePath?: string;
+  readonly customModels?: readonly string[];
+  readonly binaryPath?: string;
+}): CodexSettings => decodeCodexSettingsValue(input);
+
+const makeTempDir = Effect.fn("CodexHomeLayout.test.makeTempDir")(function* (prefix: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  return yield* fileSystem.makeTempDirectoryScoped({ prefix });
+});
+
+const writeTextFile = Effect.fn("CodexHomeLayout.test.writeTextFile")(function* (
+  filePath: string,
+  contents: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  yield* fileSystem.makeDirectory(path.dirname(filePath), { recursive: true });
+  yield* fileSystem.writeFileString(filePath, contents);
+});
+
+it.layer(NodeServices.layer)("CodexHomeLayout", (it) => {
+  describe("resolveCodexHomeLayout", () => {
+    it.effect("uses direct CODEX_HOME when no shadow home is configured", () =>
+      Effect.gen(function* () {
+        const homePath = yield* makeTempDir("t3code-codex-home-");
+
+        const layout = yield* resolveCodexHomeLayout(
+          decodeCodexSettings({
+            homePath,
+          }),
+        );
+
+        expect(layout).toMatchObject({
+          mode: "direct",
+          sharedHomePath: homePath,
+          effectiveHomePath: homePath,
+          continuationKey: `codex:home:${homePath}`,
+        });
+      }),
+    );
+
+    it.effect("uses the shared home for continuation and the shadow home for runtime", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+        const shadowHome = path.join(shadowRoot, "shadow");
+
+        const layout = yield* resolveCodexHomeLayout(
+          decodeCodexSettings({
+            homePath: sharedHome,
+            shadowHomePath: shadowHome,
+          }),
+        );
+
+        expect(layout).toMatchObject({
+          mode: "authOverlay",
+          sharedHomePath: sharedHome,
+          effectiveHomePath: shadowHome,
+          continuationKey: `codex:home:${sharedHome}`,
+        });
+      }),
+    );
+  });
+
+  describe("materializeCodexShadowHome", () => {
+    it.effect("materializes a shadow home with shared state links and private auth", () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+        const shadowHome = path.join(shadowRoot, "shadow");
+
+        yield* fileSystem.makeDirectory(path.join(sharedHome, "sessions"));
+        yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
+        yield* writeTextFile(path.join(sharedHome, "models_cache.json"), '{"models":["shared"]}\n');
+        yield* writeTextFile(path.join(sharedHome, "auth.json"), '{"shared":true}\n');
+        yield* fileSystem.makeDirectory(shadowHome, { recursive: true });
+        yield* writeTextFile(path.join(shadowHome, "auth.json"), '{"shadow":true}\n');
+        yield* fileSystem.symlink(
+          path.join(sharedHome, "models_cache.json"),
+          path.join(shadowHome, "models_cache.json"),
+        );
+
+        const layout = yield* resolveCodexHomeLayout(
+          decodeCodexSettings({
+            homePath: sharedHome,
+            shadowHomePath: shadowHome,
+          }),
+        );
+
+        yield* materializeCodexShadowHome(layout);
+
+        const sessionsTarget = yield* fileSystem.readLink(path.join(shadowHome, "sessions"));
+        const configTarget = yield* fileSystem.readLink(path.join(shadowHome, "config.toml"));
+        const modelsCacheExists = yield* fileSystem.exists(
+          path.join(shadowHome, "models_cache.json"),
+        );
+        const authLinkResult = yield* fileSystem
+          .readLink(path.join(shadowHome, "auth.json"))
+          .pipe(Effect.result);
+        const authContents = yield* fileSystem.readFileString(path.join(shadowHome, "auth.json"));
+
+        expect(sessionsTarget).toBe(path.join(sharedHome, "sessions"));
+        expect(configTarget).toBe(path.join(sharedHome, "config.toml"));
+        expect(modelsCacheExists).toBe(false);
+        expect(authLinkResult._tag).toBe("Failure");
+        expect(authContents).toContain("shadow");
+      }),
+    );
+
+    it.effect("accepts Codex-created shadow-local runtime directories", () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+        const shadowHome = path.join(shadowRoot, "shadow");
+
+        yield* fileSystem.makeDirectory(path.join(sharedHome, "log"));
+        yield* fileSystem.makeDirectory(path.join(sharedHome, "memories"));
+        yield* fileSystem.makeDirectory(path.join(sharedHome, "tmp"));
+        yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
+        yield* writeTextFile(path.join(shadowHome, "auth.json"), '{"shadow":true}\n');
+        yield* fileSystem.makeDirectory(path.join(shadowHome, "log"), { recursive: true });
+        yield* fileSystem.makeDirectory(path.join(shadowHome, "memories"), { recursive: true });
+        yield* fileSystem.makeDirectory(path.join(shadowHome, "tmp"), { recursive: true });
+
+        const layout = yield* resolveCodexHomeLayout(
+          decodeCodexSettings({
+            homePath: sharedHome,
+            shadowHomePath: shadowHome,
+          }),
+        );
+
+        yield* materializeCodexShadowHome(layout);
+
+        const configTarget = yield* fileSystem.readLink(path.join(shadowHome, "config.toml"));
+        const logLinkResult = yield* fileSystem
+          .readLink(path.join(shadowHome, "log"))
+          .pipe(Effect.result);
+        const memoriesLinkResult = yield* fileSystem
+          .readLink(path.join(shadowHome, "memories"))
+          .pipe(Effect.result);
+        const tmpLinkResult = yield* fileSystem
+          .readLink(path.join(shadowHome, "tmp"))
+          .pipe(Effect.result);
+
+        expect(configTarget).toBe(path.join(sharedHome, "config.toml"));
+        expect(logLinkResult._tag).toBe("Failure");
+        expect(memoriesLinkResult._tag).toBe("Failure");
+        expect(tmpLinkResult._tag).toBe("Failure");
+      }),
+    );
+
+    it.effect("rejects shadow homes that point at the shared home", () =>
+      Effect.gen(function* () {
+        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+        const layout = yield* resolveCodexHomeLayout(
+          decodeCodexSettings({
+            homePath: sharedHome,
+            shadowHomePath: sharedHome,
+          }),
+        );
+
+        const error = yield* materializeCodexShadowHome(layout).pipe(Effect.flip);
+
+        expect(error).toBeInstanceOf(CodexShadowHomeError);
+      }),
+    );
+
+    it.effect("rejects shared entries that already exist in the shadow home as real files", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+        const shadowRoot = yield* makeTempDir("t3code-codex-shadow-root-");
+        const shadowHome = path.join(shadowRoot, "shadow");
+        yield* writeTextFile(path.join(sharedHome, "config.toml"), 'model = "gpt-5-codex"\n');
+        yield* writeTextFile(path.join(shadowHome, "config.toml"), 'model = "local"\n');
+
+        const layout = yield* resolveCodexHomeLayout(
+          decodeCodexSettings({
+            homePath: sharedHome,
+            shadowHomePath: shadowHome,
+          }),
+        );
+
+        const error = yield* materializeCodexShadowHome(layout).pipe(Effect.flip);
+
+        expect(error.detail).toContain("already exists and is not a symlink");
+      }),
+    );
+  });
+});
diff --git a/apps/server/src/provider/Drivers/CodexHomeLayout.ts b/apps/server/src/provider/Drivers/CodexHomeLayout.ts
new file mode 100644
index 00000000000..5a7132224ef
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.ts
@@ -0,0 +1,267 @@
+import * as NodeOS from "node:os";
+
+import { ProviderDriverKind, type CodexSettings } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as PlatformError from "effect/PlatformError";
+
+import { expandHomePath } from "../../pathExpansion.ts";
+
+export interface CodexHomeLayout {
+  readonly mode: "direct" | "authOverlay";
+  readonly sharedHomePath: string;
+  readonly effectiveHomePath: string | undefined;
+  readonly continuationKey: string;
+}
+
+const KNOWN_SHARED_DIRECTORIES = [
+  "sessions",
+  "archived_sessions",
+  "sqlite",
+  "shell_snapshots",
+  "worktrees",
+  "skills",
+  "plugins",
+  "cache",
+  "logs",
+] as const;
+
+const PRIVATE_ENTRY_NAMES = new Set(["auth.json", "models_cache.json"]);
+const SHADOW_LOCAL_ENTRY_NAMES = new Set(["log", "memories", "tmp"]);
+
+function resolveHomePath(path: Path.Path, value: string | undefined): string {
+  const expanded =
+    value && value.trim().length > 0
+      ? expandHomePath(value)
+      : path.join(NodeOS.homedir(), ".codex");
+  return path.resolve(expanded);
+}
+
+export const resolveCodexHomeLayout = Effect.fn("resolveCodexHomeLayout")(function* (
+  config: CodexSettings,
+): Effect.fn.Return<CodexHomeLayout, never, Path.Path> {
+  const path = yield* Path.Path;
+  const sharedHomePath = resolveHomePath(path, config.homePath);
+  const shadowHomePath = config.shadowHomePath.trim();
+  if (shadowHomePath.length === 0) {
+    return {
+      mode: "direct",
+      sharedHomePath,
+      effectiveHomePath: config.homePath.trim().length > 0 ? sharedHomePath : undefined,
+      continuationKey: `codex:home:${sharedHomePath}`,
+    };
+  }
+
+  const effectiveHomePath = path.resolve(expandHomePath(shadowHomePath));
+  return {
+    mode: "authOverlay",
+    sharedHomePath,
+    effectiveHomePath,
+    continuationKey: `codex:home:${sharedHomePath}`,
+  };
+});
+
+export class CodexShadowHomeError extends Schema.TaggedErrorClass<CodexShadowHomeError>()(
+  "CodexShadowHomeError",
+  {
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+  },
+) {
+  override get message(): string {
+    return this.detail;
+  }
+}
+const isCodexShadowHomeError = Schema.is(CodexShadowHomeError);
+
+type LinkState =
+  | {
+      readonly _tag: "Missing";
+    }
+  | {
+      readonly _tag: "NotSymlink";
+    }
+  | {
+      readonly _tag: "Symlink";
+      readonly target: string;
+    };
+
+function toShadowHomeError(cause: unknown): CodexShadowHomeError {
+  return isCodexShadowHomeError(cause)
+    ? cause
+    : new CodexShadowHomeError({
+        detail: "Failed to materialize Codex shadow home.",
+        cause,
+      });
+}
+
+function normalizeShadowHomeError<A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, CodexShadowHomeError, R> {
+  return effect.pipe(Effect.mapError(toShadowHomeError));
+}
+
+function isNotSymlinkError(error: PlatformError.PlatformError): boolean {
+  const cause = error.reason.cause;
+  return (
+    error.reason._tag === "Unknown" &&
+    typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "EINVAL"
+  );
+}
+
+const readLinkState = Effect.fn("CodexHomeLayout.readLinkState")(function* (
+  fileSystem: FileSystem.FileSystem,
+  linkPath: string,
+): Effect.fn.Return<LinkState, CodexShadowHomeError> {
+  return yield* fileSystem.readLink(linkPath).pipe(
+    Effect.map((target): LinkState => ({ _tag: "Symlink", target })),
+    Effect.catch((error) => {
+      if (error.reason._tag === "NotFound") {
+        return Effect.succeed<LinkState>({ _tag: "Missing" });
+      }
+      if (isNotSymlinkError(error)) {
+        return Effect.succeed<LinkState>({ _tag: "NotSymlink" });
+      }
+      return Effect.fail(toShadowHomeError(error));
+    }),
+  );
+});
+
+const removePrivateSymlink = Effect.fn("CodexHomeLayout.removePrivateSymlink")(function* (input: {
+  readonly fileSystem: FileSystem.FileSystem;
+  readonly shadowPath: string;
+  readonly entryName: string;
+}): Effect.fn.Return<void, CodexShadowHomeError, Path.Path> {
+  const path = yield* Path.Path;
+  const privatePath = path.join(input.shadowPath, input.entryName);
+  const state = yield* readLinkState(input.fileSystem, privatePath);
+  if (state._tag === "Symlink") {
+    yield* normalizeShadowHomeError(input.fileSystem.remove(privatePath));
+  }
+});
+
+const ensureSymlink = Effect.fn("CodexHomeLayout.ensureSymlink")(function* (input: {
+  readonly fileSystem: FileSystem.FileSystem;
+  readonly shadowPath: string;
+  readonly sharedPath: string;
+  readonly entryName: string;
+}): Effect.fn.Return<void, CodexShadowHomeError, Path.Path> {
+  const path = yield* Path.Path;
+  const target = path.join(input.sharedPath, input.entryName);
+  const link = path.join(input.shadowPath, input.entryName);
+  const state = yield* readLinkState(input.fileSystem, link);
+
+  if (state._tag === "NotSymlink") {
+    return yield* new CodexShadowHomeError({
+      detail: `Cannot create Codex shadow home because '${link}' already exists and is not a symlink.`,
+    });
+  }
+
+  if (state._tag === "Missing") {
+    return yield* normalizeShadowHomeError(input.fileSystem.symlink(target, link));
+  }
+
+  const resolvedExisting = path.resolve(path.dirname(link), state.target);
+  if (resolvedExisting !== target) {
+    yield* normalizeShadowHomeError(input.fileSystem.remove(link));
+    yield* normalizeShadowHomeError(input.fileSystem.symlink(target, link));
+  }
+});
+
+const ensureShadowAuthIsPrivate = Effect.fn("CodexHomeLayout.ensureShadowAuthIsPrivate")(function* (
+  fileSystem: FileSystem.FileSystem,
+  shadowPath: string,
+): Effect.fn.Return<void, CodexShadowHomeError, Path.Path> {
+  const path = yield* Path.Path;
+  const authPath = path.join(shadowPath, "auth.json");
+  const state = yield* readLinkState(fileSystem, authPath);
+  if (state._tag === "Symlink") {
+    return yield* new CodexShadowHomeError({
+      detail: `Codex shadow auth file '${authPath}' must be a real file, not a symlink.`,
+    });
+  }
+});
+
+export const materializeCodexShadowHome = Effect.fn("materializeCodexShadowHome")(function* (
+  layout: CodexHomeLayout,
+) {
+  if (layout.mode !== "authOverlay") return;
+  const effectiveHomePath = layout.effectiveHomePath;
+  if (!effectiveHomePath) return;
+  if (layout.sharedHomePath === effectiveHomePath) {
+    return yield* new CodexShadowHomeError({
+      detail: "Codex shadow home path must be different from the shared home path.",
+    });
+  }
+
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  yield* normalizeShadowHomeError(
+    Effect.all(
+      [
+        fileSystem.makeDirectory(layout.sharedHomePath, { recursive: true }),
+        fileSystem.makeDirectory(effectiveHomePath, { recursive: true }),
+        ...KNOWN_SHARED_DIRECTORIES.map((directory) =>
+          fileSystem.makeDirectory(path.join(layout.sharedHomePath, directory), {
+            recursive: true,
+          }),
+        ),
+      ],
+      { concurrency: "unbounded" },
+    ),
+  );
+
+  const sharedEntryNames = yield* normalizeShadowHomeError(
+    fileSystem.readDirectory(layout.sharedHomePath),
+  );
+  const entries = new Set<string>(KNOWN_SHARED_DIRECTORIES);
+  for (const entryName of sharedEntryNames) {
+    if (!PRIVATE_ENTRY_NAMES.has(entryName) && !SHADOW_LOCAL_ENTRY_NAMES.has(entryName)) {
+      entries.add(entryName);
+    }
+  }
+
+  yield* Effect.forEach(
+    PRIVATE_ENTRY_NAMES,
+    (entryName) =>
+      entryName === "auth.json"
+        ? Effect.void
+        : removePrivateSymlink({
+            fileSystem,
+            shadowPath: effectiveHomePath,
+            entryName,
+          }),
+    { discard: true },
+  );
+
+  yield* Effect.forEach(
+    entries,
+    (entryName) => {
+      if (PRIVATE_ENTRY_NAMES.has(entryName)) {
+        return Effect.void;
+      }
+      return ensureSymlink({
+        fileSystem,
+        shadowPath: effectiveHomePath,
+        sharedPath: layout.sharedHomePath,
+        entryName,
+      });
+    },
+    { discard: true },
+  );
+
+  yield* ensureShadowAuthIsPrivate(fileSystem, effectiveHomePath);
+});
+
+export function codexContinuationIdentity(layout: CodexHomeLayout) {
+  return {
+    driverKind: ProviderDriverKind.make("codex"),
+    continuationKey: layout.continuationKey,
+  };
+}
diff --git a/apps/server/src/provider/Drivers/CursorDriver.ts b/apps/server/src/provider/Drivers/CursorDriver.ts
new file mode 100644
index 00000000000..b399f9aa948
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CursorDriver.ts
@@ -0,0 +1,179 @@
+/**
+ * CursorDriver — `ProviderDriver` for the Cursor Agent (`agent`) runtime.
+ *
+ * Cursor exposes an ACP-based CLI. The driver is still a plain value, but
+ * its snapshot uses `makeManagedServerProvider`'s optional `enrichSnapshot`
+ * hook to run the slow ACP model-capability probe in the background without
+ * blocking the initial `ready`-state publish.
+ *
+ * Text generation is supported via the ACP runtime — `makeCursorTextGeneration`
+ * drives `runtime.prompt` with a structured-output schema and collects the
+ * agent's `agent_message_chunk` stream into a single JSON blob.
+ *
+ * @module provider/Drivers/CursorDriver
+ */
+import { CursorSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { ServerConfig } from "../../config.ts";
+import { makeCursorTextGeneration } from "../../textGeneration/CursorTextGeneration.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeCursorAdapter } from "../Layers/CursorAdapter.ts";
+import {
+  buildInitialCursorProviderSnapshot,
+  checkCursorProviderStatus,
+  enrichCursorSnapshot,
+} from "../Layers/CursorProvider.ts";
+import { ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
+import {
+  defaultProviderContinuationIdentity,
+  type ProviderDriver,
+  type ProviderInstance,
+} from "../ProviderDriver.ts";
+import type { ServerProviderDraft } from "../providerSnapshot.ts";
+import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+  makeProviderMaintenanceCapabilities,
+  makeStaticProviderMaintenanceResolver,
+  resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
+const decodeCursorSettings = Schema.decodeSync(CursorSettings);
+
+const DRIVER_KIND = ProviderDriverKind.make("cursor");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+const UPDATE = makeStaticProviderMaintenanceResolver(
+  makeProviderMaintenanceCapabilities({
+    provider: DRIVER_KIND,
+    packageName: null,
+    updateExecutable: "agent",
+    updateArgs: ["update"],
+    updateLockKey: "cursor-agent",
+  }),
+);
+
+export type CursorDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | HttpClient.HttpClient
+  | Path.Path
+  | ProviderEventLoggers
+  | ServerConfig;
+
+const withInstanceIdentity =
+  (input: {
+    readonly instanceId: ProviderInstance["instanceId"];
+    readonly displayName: string | undefined;
+    readonly accentColor: string | undefined;
+    readonly continuationGroupKey: string;
+  }) =>
+  (snapshot: ServerProviderDraft): ServerProvider => ({
+    ...snapshot,
+    instanceId: input.instanceId,
+    driver: DRIVER_KIND,
+    ...(input.displayName ? { displayName: input.displayName } : {}),
+    ...(input.accentColor ? { accentColor: input.accentColor } : {}),
+    continuation: { groupKey: input.continuationGroupKey },
+  });
+
+export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "Cursor",
+    supportsMultipleInstances: true,
+  },
+  configSchema: CursorSettings,
+  defaultConfig: (): CursorSettings => decodeCursorSettings({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const httpClient = yield* HttpClient.HttpClient;
+      const eventLoggers = yield* ProviderEventLoggers;
+      const processEnv = mergeProviderInstanceEnvironment(environment);
+      const continuationIdentity = defaultProviderContinuationIdentity({
+        driverKind: DRIVER_KIND,
+        instanceId,
+      });
+      const stampIdentity = withInstanceIdentity({
+        instanceId,
+        displayName,
+        accentColor,
+        continuationGroupKey: continuationIdentity.continuationKey,
+      });
+      const effectiveConfig = { ...config, enabled } satisfies CursorSettings;
+      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+        binaryPath: effectiveConfig.binaryPath,
+        env: processEnv,
+      });
+
+      const adapter = yield* makeCursorAdapter(effectiveConfig, {
+        environment: processEnv,
+        ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
+        instanceId,
+      });
+      const textGeneration = yield* makeCursorTextGeneration(effectiveConfig, processEnv);
+
+      const checkProvider = checkCursorProviderStatus(effectiveConfig, processEnv).pipe(
+        Effect.map(stampIdentity),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+        Effect.provideService(FileSystem.FileSystem, fileSystem),
+        Effect.provideService(Path.Path, path),
+      );
+
+      const snapshot = yield* makeManagedServerProvider<CursorSettings>({
+        maintenanceCapabilities,
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) =>
+          buildInitialCursorProviderSnapshot(settings).pipe(Effect.map(stampIdentity)),
+        checkProvider,
+        // Preserve the background ACP model-capability probe that used to
+        // live on `CursorProviderLive`. Only fires when the snapshot reports
+        // an authenticated, enabled provider with at least one non-custom
+        // model whose capabilities haven't been captured yet.
+        enrichSnapshot: ({ settings, snapshot: currentSnapshot, publishSnapshot }) =>
+          enrichCursorSnapshot({
+            settings,
+            environment: processEnv,
+            snapshot: currentSnapshot,
+            maintenanceCapabilities,
+            publishSnapshot,
+            stampIdentity,
+            httpClient,
+          }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build Cursor snapshot: ${cause.message ?? String(cause)}`,
+              cause,
+            }),
+        ),
+      );
+
+      return {
+        instanceId,
+        driverKind: DRIVER_KIND,
+        continuationIdentity,
+        displayName,
+        accentColor,
+        enabled,
+        snapshot,
+        adapter,
+        textGeneration,
+      } satisfies ProviderInstance;
+    }),
+};
diff --git a/apps/server/src/provider/Drivers/OpenCodeDriver.ts b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
new file mode 100644
index 00000000000..816e8b70f55
--- /dev/null
+++ b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
@@ -0,0 +1,181 @@
+/**
+ * OpenCodeDriver — `ProviderDriver` for the OpenCode runtime.
+ *
+ * Mirrors the Codex / Claude drivers: a plain value whose `create()`
+ * bundles `snapshot` / `adapter` / `textGeneration` closures over the
+ * per-instance `OpenCodeSettings`.
+ *
+ * Two instances with different `serverUrl`s therefore talk to independent
+ * OpenCode servers; when no `serverUrl` is set, the adapter + text-generation
+ * shares spin up their own scoped child processes, and those child
+ * processes are released when the registry scope closes.
+ *
+ * @module provider/Drivers/OpenCodeDriver
+ */
+import { OpenCodeSettings, ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { makeOpenCodeTextGeneration } from "../../textGeneration/OpenCodeTextGeneration.ts";
+import { ServerConfig } from "../../config.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeOpenCodeAdapter } from "../Layers/OpenCodeAdapter.ts";
+import {
+  checkOpenCodeProviderStatus,
+  makePendingOpenCodeProvider,
+} from "../Layers/OpenCodeProvider.ts";
+import { ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
+import { OpenCodeRuntime } from "../opencodeRuntime.ts";
+import {
+  defaultProviderContinuationIdentity,
+  type ProviderDriver,
+  type ProviderInstance,
+} from "../ProviderDriver.ts";
+import type { ServerProviderDraft } from "../providerSnapshot.ts";
+import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
+import {
+  enrichProviderSnapshotWithVersionAdvisory,
+  makePackageManagedProviderMaintenanceResolver,
+  normalizeCommandPath,
+  resolveProviderMaintenanceCapabilitiesEffect,
+} from "../providerMaintenance.ts";
+const decodeOpenCodeSettings = Schema.decodeSync(OpenCodeSettings);
+
+const DRIVER_KIND = ProviderDriverKind.make("opencode");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+function isOpenCodeNativeCommandPath(commandPath: string): boolean {
+  const normalized = normalizeCommandPath(commandPath);
+  return (
+    normalized.endsWith("/.opencode/bin/opencode") ||
+    normalized.endsWith("/.opencode/bin/opencode.exe")
+  );
+}
+
+const UPDATE = makePackageManagedProviderMaintenanceResolver({
+  provider: DRIVER_KIND,
+  npmPackageName: "opencode-ai",
+  homebrewFormula: "anomalyco/tap/opencode",
+  nativeUpdate: {
+    executable: "opencode",
+    args: ["upgrade"],
+    lockKey: "opencode-native",
+    isCommandPath: isOpenCodeNativeCommandPath,
+  },
+});
+
+export type OpenCodeDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | HttpClient.HttpClient
+  | OpenCodeRuntime
+  | Path.Path
+  | ProviderEventLoggers
+  | ServerConfig;
+
+const withInstanceIdentity =
+  (input: {
+    readonly instanceId: ProviderInstance["instanceId"];
+    readonly displayName: string | undefined;
+    readonly accentColor: string | undefined;
+    readonly continuationGroupKey: string;
+  }) =>
+  (snapshot: ServerProviderDraft): ServerProvider => ({
+    ...snapshot,
+    instanceId: input.instanceId,
+    driver: DRIVER_KIND,
+    ...(input.displayName ? { displayName: input.displayName } : {}),
+    ...(input.accentColor ? { accentColor: input.accentColor } : {}),
+    continuation: { groupKey: input.continuationGroupKey },
+  });
+
+export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "OpenCode",
+    supportsMultipleInstances: true,
+  },
+  configSchema: OpenCodeSettings,
+  defaultConfig: (): OpenCodeSettings => decodeOpenCodeSettings({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const openCodeRuntime = yield* OpenCodeRuntime;
+      const serverConfig = yield* ServerConfig;
+      const httpClient = yield* HttpClient.HttpClient;
+      const eventLoggers = yield* ProviderEventLoggers;
+      const processEnv = mergeProviderInstanceEnvironment(environment);
+      const continuationIdentity = defaultProviderContinuationIdentity({
+        driverKind: DRIVER_KIND,
+        instanceId,
+      });
+      const stampIdentity = withInstanceIdentity({
+        instanceId,
+        displayName,
+        accentColor,
+        continuationGroupKey: continuationIdentity.continuationKey,
+      });
+      const effectiveConfig = { ...config, enabled } satisfies OpenCodeSettings;
+      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+        binaryPath: effectiveConfig.binaryPath,
+        env: processEnv,
+      });
+
+      const adapter = yield* makeOpenCodeAdapter(effectiveConfig, {
+        instanceId,
+        environment: processEnv,
+        ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
+      });
+      const textGeneration = yield* makeOpenCodeTextGeneration(effectiveConfig, processEnv);
+
+      const checkProvider = checkOpenCodeProviderStatus(
+        effectiveConfig,
+        serverConfig.cwd,
+        processEnv,
+      ).pipe(Effect.map(stampIdentity), Effect.provideService(OpenCodeRuntime, openCodeRuntime));
+
+      const snapshot = yield* makeManagedServerProvider<OpenCodeSettings>({
+        maintenanceCapabilities,
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) =>
+          makePendingOpenCodeProvider(settings).pipe(Effect.map(stampIdentity)),
+        checkProvider,
+        enrichSnapshot: ({ snapshot, publishSnapshot }) =>
+          enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities).pipe(
+            Effect.provideService(HttpClient.HttpClient, httpClient),
+            Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
+          ),
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build OpenCode snapshot: ${cause.message ?? String(cause)}`,
+              cause,
+            }),
+        ),
+      );
+
+      return {
+        instanceId,
+        driverKind: DRIVER_KIND,
+        continuationIdentity,
+        displayName,
+        accentColor,
+        enabled,
+        snapshot,
+        adapter,
+        textGeneration,
+      } satisfies ProviderInstance;
+    }),
+};
diff --git a/apps/server/src/provider/Errors.ts b/apps/server/src/provider/Errors.ts
index e4e46d37486..bccc7d5679c 100644
--- a/apps/server/src/provider/Errors.ts
+++ b/apps/server/src/provider/Errors.ts
@@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 
 import type { CheckpointServiceError } from "../checkpointing/Errors.ts";
 
@@ -116,6 +116,46 @@ export class ProviderUnsupportedError extends Schema.TaggedErrorClass<ProviderUn
   }
 }
 
+/**
+ * ProviderInstanceNotFoundError - Lookup against the instance registry failed.
+ *
+ * Distinct from `ProviderUnsupportedError`: the driver is registered, but no
+ * instance with the requested id has been bootstrapped — typically because
+ * the persisted instance id refers to an instance the user removed from
+ * settings, or because routing is asked for an instance before the registry
+ * has finished its first reload.
+ */
+export class ProviderInstanceNotFoundError extends Schema.TaggedErrorClass<ProviderInstanceNotFoundError>()(
+  "ProviderInstanceNotFoundError",
+  {
+    instanceId: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `No provider instance bound to id '${this.instanceId}'`;
+  }
+}
+
+/**
+ * ProviderDriverError - A driver `create` call failed before producing an
+ * instance. Surfaced to the registry, which marks the offending entry as
+ * an "unavailable" shadow snapshot rather than crashing the server.
+ */
+export class ProviderDriverError extends Schema.TaggedErrorClass<ProviderDriverError>()(
+  "ProviderDriverError",
+  {
+    driver: Schema.String,
+    instanceId: Schema.String,
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `Provider driver '${this.driver}' failed to create instance '${this.instanceId}': ${this.detail}`;
+  }
+}
+
 /**
  * ProviderSessionNotFoundError - Provider-facing session not found.
  */
@@ -157,6 +197,7 @@ export type ProviderAdapterError =
 export type ProviderServiceError =
   | ProviderValidationError
   | ProviderUnsupportedError
+  | ProviderInstanceNotFoundError
   | ProviderSessionNotFoundError
   | ProviderSessionDirectoryPersistenceError
   | ProviderAdapterError
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
index 8b1f1389c41..19ed1811760 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -12,20 +13,37 @@ import type {
 } from "@anthropic-ai/claude-agent-sdk";
 import {
   ApprovalRequestId,
+  ClaudeSettings,
+  ProviderDriverKind,
   ProviderItemId,
   ProviderRuntimeEvent,
   type RuntimeMode,
   ThreadId,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import { assert, describe, it } from "@effect/vitest";
-import { Effect, Fiber, Layer, Random, Stream } from "effect";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
 
 import { attachmentRelativePath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { ProviderAdapterValidationError } from "../Errors.ts";
-import { ClaudeAdapter } from "../Services/ClaudeAdapter.ts";
-import { makeClaudeAdapterLive, type ClaudeAdapterLiveOptions } from "./ClaudeAdapter.ts";
+import type { ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
+import { makeClaudeAdapter, type ClaudeAdapterLiveOptions } from "./ClaudeAdapter.ts";
+const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
+
+// Test-local service tag so the rest of the file can keep using `yield* ClaudeAdapter`.
+class ClaudeAdapter extends Context.Service<ClaudeAdapter, ClaudeAdapterShape>()(
+  "test/ClaudeAdapter",
+) {}
 
 class FakeClaudeQuery implements AsyncIterable<SDKMessage> {
   private readonly queue: Array<SDKMessage> = [];
@@ -136,6 +154,8 @@ function makeHarness(config?: {
   readonly nativeEventLogger?: ClaudeAdapterLiveOptions["nativeEventLogger"];
   readonly cwd?: string;
   readonly baseDir?: string;
+  readonly claudeConfig?: Partial<ClaudeSettings>;
+  readonly instanceId?: ProviderInstanceId;
 }) {
   const query = new FakeClaudeQuery();
   let createInput:
@@ -146,6 +166,7 @@ function makeHarness(config?: {
     | undefined;
 
   const adapterOptions: ClaudeAdapterLiveOptions = {
+    ...(config?.instanceId ? { instanceId: config.instanceId } : {}),
     createQuery: (input) => {
       createInput = input;
       return query;
@@ -163,7 +184,13 @@ function makeHarness(config?: {
   };
 
   return {
-    layer: makeClaudeAdapterLive(adapterOptions).pipe(
+    layer: Layer.effect(
+      ClaudeAdapter,
+      Effect.gen(function* () {
+        const claudeConfig = decodeClaudeSettings(config?.claudeConfig ?? {});
+        return yield* makeClaudeAdapter(claudeConfig, adapterOptions);
+      }),
+    ).pipe(
       Layer.provideMerge(
         ServerConfig.layerTest(
           config?.cwd ?? "/tmp/claude-adapter-test",
@@ -246,7 +273,11 @@ describe("ClaudeAdapterLive", () => {
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
       const result = yield* adapter
-        .startSession({ threadId: THREAD_ID, provider: "codex", runtimeMode: "full-access" })
+        .startSession({
+          threadId: THREAD_ID,
+          provider: ProviderDriverKind.make("codex"),
+          runtimeMode: "full-access",
+        })
         .pipe(Effect.result);
 
       assert.equal(result._tag, "Failure");
@@ -256,7 +287,7 @@ describe("ClaudeAdapterLive", () => {
       assert.deepEqual(
         result.failure,
         new ProviderAdapterValidationError({
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "startSession",
           issue: "Expected provider 'claudeAgent' but received 'codex'.",
         }),
@@ -273,7 +304,7 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -293,7 +324,7 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -313,7 +344,7 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -332,13 +363,55 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [{ id: "effort", value: "max" }],
+        ),
+        runtimeMode: "full-access",
+      });
+
+      const createInput = harness.getLastCreateQueryInput();
+      assert.equal(createInput?.options.effort, "max");
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("runs Claude SDK sessions with the configured Claude HOME", () => {
+    const harness = makeHarness({ claudeConfig: { homePath: "~/.claude-work" } });
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+        ),
+        runtimeMode: "full-access",
+      });
+
+      const createInput = harness.getLastCreateQueryInput();
+      assert.equal(createInput?.options.env?.HOME, path.join(os.homedir(), ".claude-work"));
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("maps the Claude Opus 4.7 default effort to the SDK-supported max value", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            effort: "max",
-          },
+          instanceId: ProviderInstanceId.make("claudeAgent"),
+          model: "claude-opus-4-7",
         },
         runtimeMode: "full-access",
       });
@@ -351,20 +424,41 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  it.effect("maps xhigh effort for Claude Opus 4.7 to the SDK-supported max value", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-7",
+          [{ id: "effort", value: "xhigh" }],
+        ),
+        runtimeMode: "full-access",
+      });
+
+      const createInput = harness.getLastCreateQueryInput();
+      assert.equal(createInput?.options.effort, "max");
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
   it.effect("falls back to default effort when unsupported max is requested for Sonnet 4.6", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            effort: "max",
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "effort", value: "max" }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -382,14 +476,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-haiku-4-5",
-          options: {
-            effort: "high",
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-haiku-4-5",
+          [{ id: "effort", value: "high" }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -407,14 +499,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-haiku-4-5",
-          options: {
-            thinking: false,
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-haiku-4-5",
+          [{ id: "thinking", value: false }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -434,14 +524,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            thinking: false,
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "thinking", value: false }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -459,14 +547,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            fastMode: true,
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [{ id: "fastMode", value: true }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -486,14 +572,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            fastMode: true,
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "fastMode", value: true }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -511,14 +595,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            effort: "ultrathink",
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "effort", value: "ultrathink" }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -526,13 +608,11 @@ describe("ClaudeAdapterLive", () => {
         threadId: session.threadId,
         input: "Investigate the edge cases",
         attachments: [],
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-sonnet-4-6",
-          options: {
-            effort: "ultrathink",
-          },
-        },
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-sonnet-4-6",
+          [{ id: "effort", value: "ultrathink" }],
+        ),
       });
 
       const createInput = harness.getLastCreateQueryInput();
@@ -577,7 +657,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -622,9 +702,9 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-sonnet-4-5",
         },
         runtimeMode: "full-access",
@@ -799,7 +879,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -966,6 +1046,97 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  it.effect("falls back to a default plan step label for blank TodoWrite content", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+
+      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 10).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      const session = yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      const turn = yield* adapter.sendTurn({
+        threadId: session.threadId,
+        input: "hello",
+        attachments: [],
+      });
+
+      harness.query.emit({
+        type: "stream_event",
+        session_id: "sdk-session-todo-plan",
+        uuid: "stream-todo-start",
+        parent_tool_use_id: null,
+        event: {
+          type: "content_block_start",
+          index: 1,
+          content_block: {
+            type: "tool_use",
+            id: "tool-todo-1",
+            name: "TodoWrite",
+            input: {},
+          },
+        },
+      } as unknown as SDKMessage);
+
+      harness.query.emit({
+        type: "stream_event",
+        session_id: "sdk-session-todo-plan",
+        uuid: "stream-todo-input",
+        parent_tool_use_id: null,
+        event: {
+          type: "content_block_delta",
+          index: 1,
+          delta: {
+            type: "input_json_delta",
+            partial_json:
+              '{"todos":[{"content":"   ","status":"in_progress"},{"content":"Ship it","status":"completed"}]}',
+          },
+        },
+      } as unknown as SDKMessage);
+
+      harness.query.emit({
+        type: "stream_event",
+        session_id: "sdk-session-todo-plan",
+        uuid: "stream-todo-stop",
+        parent_tool_use_id: null,
+        event: {
+          type: "content_block_stop",
+          index: 1,
+        },
+      } as unknown as SDKMessage);
+
+      harness.query.emit({
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        errors: [],
+        session_id: "sdk-session-todo-plan",
+        uuid: "result-todo-plan",
+      } as unknown as SDKMessage);
+
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+      const planUpdated = runtimeEvents.find((event) => event.type === "turn.plan.updated");
+      assert.equal(planUpdated?.type, "turn.plan.updated");
+      if (planUpdated?.type === "turn.plan.updated") {
+        assert.equal(String(planUpdated.turnId), String(turn.turnId));
+        assert.deepEqual(planUpdated.payload.plan, [
+          { step: "Task", status: "inProgress" },
+          { step: "Ship it", status: "completed" },
+        ]);
+      }
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
   it.effect("classifies Claude Task tool invocations as collaboration agent work", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
@@ -978,7 +1149,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1054,7 +1225,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1120,7 +1291,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1169,6 +1340,77 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  it.effect("closes the previous session before replacing an existing thread session", () => {
+    const queries: FakeClaudeQuery[] = [];
+    const layer = Layer.effect(
+      ClaudeAdapter,
+      Effect.gen(function* () {
+        const claudeConfig = decodeClaudeSettings({});
+        return yield* makeClaudeAdapter(claudeConfig, {
+          createQuery: () => {
+            const query = new FakeClaudeQuery();
+            queries.push(query);
+            return query;
+          },
+        });
+      }),
+    ).pipe(
+      Layer.provideMerge(ServerConfig.layerTest("/tmp/claude-adapter-test", "/tmp")),
+      Layer.provideMerge(ServerSettingsService.layerTest()),
+      Layer.provideMerge(NodeServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+
+      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 6).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      const firstSession = yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      const secondSession = yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+        resumeCursor: firstSession.resumeCursor,
+      });
+
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+      const activeSessions = yield* adapter.listSessions();
+
+      assert.equal(queries.length, 2);
+      assert.equal(queries[0]?.closeCalls, 1);
+      assert.equal(queries[1]?.closeCalls, 0);
+      assert.equal(yield* adapter.hasSession(THREAD_ID), true);
+      assert.equal(activeSessions.length, 1);
+      assert.deepEqual(activeSessions[0]?.resumeCursor, secondSession.resumeCursor);
+      assert.deepEqual(
+        runtimeEvents.map((event) => event.type),
+        [
+          "session.started",
+          "session.configured",
+          "session.state.changed",
+          "session.started",
+          "session.configured",
+          "session.state.changed",
+        ],
+      );
+      assert.equal(
+        runtimeEvents.some((event) => event.type === "session.exited"),
+        false,
+      );
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(layer),
+    );
+  });
+
   it.effect("stopSession does not throw into the SDK prompt consumer", () => {
     // The SDK consumes user messages via `for await (... of prompt)`.
     // Stopping a session must end that loop cleanly — not throw an error.
@@ -1183,21 +1425,27 @@ describe("ClaudeAdapterLive", () => {
 
     let promptConsumerError: unknown = undefined;
 
-    const layer = makeClaudeAdapterLive({
-      createQuery: (input) => {
-        // Simulate the SDK consuming the prompt iterable
-        (async () => {
-          try {
-            for await (const _message of input.prompt) {
-              /* SDK processes user messages */
-            }
-          } catch (error) {
-            promptConsumerError = error;
-          }
-        })();
-        return query;
-      },
-    }).pipe(
+    const layer = Layer.effect(
+      ClaudeAdapter,
+      Effect.gen(function* () {
+        const claudeConfig = decodeClaudeSettings({});
+        return yield* makeClaudeAdapter(claudeConfig, {
+          createQuery: (input) => {
+            // Simulate the SDK consuming the prompt iterable
+            (async () => {
+              try {
+                for await (const _message of input.prompt) {
+                  /* SDK processes user messages */
+                }
+              } catch (error) {
+                promptConsumerError = error;
+              }
+            })();
+            return query;
+          },
+        });
+      }),
+    ).pipe(
       Layer.provideMerge(ServerConfig.layerTest("/tmp/claude-adapter-test", "/tmp")),
       Layer.provideMerge(ServerSettingsService.layerTest()),
       Layer.provideMerge(NodeServices.layer),
@@ -1215,7 +1463,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1224,7 +1472,8 @@ describe("ClaudeAdapterLive", () => {
       yield* Effect.yieldNow;
       yield* Effect.yieldNow;
       yield* Effect.yieldNow;
-      yield* Effect.promise(() => new Promise((resolve) => setTimeout(resolve, 50)));
+      yield* TestClock.adjust("50 millis");
+      yield* Effect.yieldNow;
 
       runtimeEventsFiber.interruptUnsafe();
 
@@ -1252,7 +1501,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1299,7 +1548,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1353,7 +1602,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1420,7 +1669,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1485,7 +1734,7 @@ describe("ClaudeAdapterLive", () => {
 
         yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode: "full-access",
         });
 
@@ -1566,7 +1815,7 @@ describe("ClaudeAdapterLive", () => {
 
         const session = yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode: "full-access",
         });
 
@@ -1657,7 +1906,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1823,7 +2072,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1892,7 +2141,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2114,7 +2363,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
       assert.equal(session.threadId, THREAD_ID);
@@ -2187,7 +2436,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -2296,7 +2545,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -2369,7 +2618,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: RESUME_THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         resumeCursor: {
           threadId: "resume-thread-1",
           resume: "550e8400-e29b-41d4-a716-446655440000",
@@ -2397,6 +2646,96 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  it.effect("preserves durable resume ids across Claude resume hooks", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const durableSessionId = "550e8400-e29b-41d4-a716-446655440000";
+      const transientHookSessionId = "7368d0c7-40a3-4d8a-bcc1-ac80c49f2719";
+
+      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 7).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      yield* adapter.startSession({
+        threadId: RESUME_THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        resumeCursor: {
+          threadId: RESUME_THREAD_ID,
+          resume: durableSessionId,
+          resumeSessionAt: "assistant-99",
+          turnCount: 3,
+        },
+        runtimeMode: "full-access",
+      });
+
+      harness.query.emit({
+        type: "system",
+        subtype: "hook_started",
+        hook_id: "resume-hook-1",
+        hook_name: "SessionStart:resume",
+        hook_event: "SessionStart",
+        session_id: transientHookSessionId,
+        uuid: "resume-hook-started",
+      } as unknown as SDKMessage);
+
+      harness.query.emit({
+        type: "system",
+        subtype: "hook_response",
+        hook_id: "resume-hook-1",
+        hook_name: "SessionStart:resume",
+        hook_event: "SessionStart",
+        output: "",
+        stdout: "",
+        stderr: "",
+        outcome: "success",
+        session_id: transientHookSessionId,
+        uuid: "resume-hook-response",
+      } as unknown as SDKMessage);
+
+      harness.query.emit({
+        type: "system",
+        subtype: "init",
+        apiKeySource: "none",
+        claude_code_version: "test",
+        cwd: "/tmp/claude-adapter-test",
+        tools: [],
+        mcp_servers: [],
+        model: "claude-sonnet-4-5",
+        permissionMode: "bypassPermissions",
+        slash_commands: [],
+        output_style: "default",
+        skills: [],
+        plugins: [],
+        session_id: durableSessionId,
+        uuid: "resume-init",
+      } as unknown as SDKMessage);
+
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+      const threadStartedEvents = runtimeEvents.filter((event) => event.type === "thread.started");
+      assert.equal(threadStartedEvents.length, 1);
+      const threadStarted = threadStartedEvents[0];
+      assert.equal(threadStarted?.type, "thread.started");
+      if (threadStarted?.type === "thread.started") {
+        assert.deepEqual(threadStarted.payload, {
+          providerThreadId: durableSessionId,
+        });
+      }
+
+      const activeSessions = yield* adapter.listSessions();
+      const resumeCursor = activeSessions[0]?.resumeCursor as
+        | {
+            readonly resume?: string;
+          }
+        | undefined;
+      assert.equal(resumeCursor?.resume, durableSessionId);
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
   it.effect("uses an app-generated Claude session id for fresh sessions", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
@@ -2404,7 +2743,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2438,7 +2777,7 @@ describe("ClaudeAdapterLive", () => {
 
         const session = yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode: "full-access",
         });
 
@@ -2518,14 +2857,14 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
       yield* adapter.sendTurn({
         threadId: session.threadId,
         input: "hello",
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         },
         attachments: [],
@@ -2538,6 +2877,34 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  it.effect("updates model on sendTurn for the adapter's bound custom instance id", () => {
+    const customInstanceId = ProviderInstanceId.make("claude_openrouter");
+    const harness = makeHarness({ instanceId: customInstanceId });
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+
+      const session = yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+      yield* adapter.sendTurn({
+        threadId: session.threadId,
+        input: "hello",
+        modelSelection: {
+          instanceId: customInstanceId,
+          model: "openai/gpt-5.5",
+        },
+        attachments: [],
+      });
+
+      assert.deepEqual(harness.query.setModelCalls, ["openai/gpt-5.5"]);
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
   it.effect(
     "does not re-set the Claude model when the session already uses the same effective API model",
     () => {
@@ -2545,13 +2912,13 @@ describe("ClaudeAdapterLive", () => {
       return Effect.gen(function* () {
         const adapter = yield* ClaudeAdapter;
         const modelSelection = {
-          provider: "claudeAgent" as const,
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         };
 
         const session = yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           modelSelection,
           runtimeMode: "full-access",
         });
@@ -2584,27 +2951,25 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
       yield* adapter.sendTurn({
         threadId: session.threadId,
         input: "hello",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            contextWindow: "1m",
-          },
-        },
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [{ id: "contextWindow", value: "1m" }],
+        ),
         attachments: [],
       });
       yield* adapter.sendTurn({
         threadId: session.threadId,
         input: "hello again",
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         },
         attachments: [],
@@ -2624,7 +2989,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
       yield* adapter.sendTurn({
@@ -2654,7 +3019,7 @@ describe("ClaudeAdapterLive", () => {
 
         const session = yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode,
         });
 
@@ -2706,7 +3071,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
       yield* adapter.sendTurn({
@@ -2729,7 +3094,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2795,7 +3160,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2867,7 +3232,7 @@ describe("ClaudeAdapterLive", () => {
       // Start session in approval-required mode so canUseTool fires.
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -2941,6 +3306,9 @@ describe("ClaudeAdapterLive", () => {
       assert.equal(typeof requestId, "string");
       assert.equal(requestedEvent.value.payload.questions.length, 1);
       assert.equal(requestedEvent.value.payload.questions[0]?.question, "Which framework?");
+      // Regression for #2388: `id` must equal the full question text so the
+      // UI's draft-answer key matches what the SDK looks up downstream.
+      assert.equal(requestedEvent.value.payload.questions[0]?.id, "Which framework?");
       assert.deepEqual(requestedEvent.value.providerRefs, {
         providerItemId: ProviderItemId.make("tool-ask-1"),
       });
@@ -2975,6 +3343,34 @@ describe("ClaudeAdapterLive", () => {
       assert.deepEqual(updatedInput.answers, { "Which framework?": "React" });
       // Original questions should be passed through.
       assert.deepEqual(updatedInput.questions, askInput.questions);
+
+      // Compatibility check for #2388: the answers shape we hand to the SDK
+      // must produce a non-empty rendered tool_result on BOTH SDK iteration
+      // patterns we have seen, so we don't regress the issue and we don't
+      // break users still on the older Claude CLI.
+      const sdkAnswers = updatedInput.answers as Record<string, unknown>;
+      const sdkQuestions = updatedInput.questions as ReadonlyArray<{
+        readonly question: string;
+      }>;
+
+      // Claude CLI 2.1.119 — key-agnostic Object.entries iteration. Any key
+      // works here, but it must at least round-trip into a non-empty string.
+      const v119Rendered = Object.entries(sdkAnswers)
+        .map(([key, value]) => `"${key}"="${String(value)}"`)
+        .join(", ");
+      assert.equal(v119Rendered, '"Which framework?"="React"');
+
+      // Claude CLI 2.1.121 — lookup by full question text. This is the path
+      // that regressed in #2388 when the answers were keyed by `header`.
+      const v121Rendered = sdkQuestions
+        .map(({ question }) => {
+          const answer = sdkAnswers[question];
+          return answer === undefined ? null : `"${question}"="${String(answer)}"`;
+        })
+        .filter((entry): entry is string => entry !== null)
+        .join(", ");
+      assert.notEqual(v121Rendered, "", "Expected non-empty SDK 2.1.121 tool_result (#2388)");
+      assert.equal(v121Rendered, '"Which framework?"="React"');
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
       Effect.provide(harness.layer),
@@ -2990,7 +3386,7 @@ describe("ClaudeAdapterLive", () => {
       // AskUserQuestion should still go through the user-input flow.
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -3056,7 +3452,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -3143,7 +3539,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
       const turn = yield* adapter.sendTurn({
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.ts b/apps/server/src/provider/Layers/ClaudeAdapter.ts
index 1a0657c499d..cf97b0a87f0 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.ts
@@ -6,26 +6,28 @@
  *
  * @module ClaudeAdapterLive
  */
-import {
-  type CanUseTool,
-  query,
-  type Options as ClaudeQueryOptions,
-  type PermissionMode,
-  type PermissionResult,
-  type PermissionUpdate,
-  type SDKMessage,
-  type SDKResultMessage,
-  type SettingSource,
-  type SDKUserMessage,
+import type {
+  CanUseTool,
+  Options as ClaudeQueryOptions,
+  PermissionMode,
+  PermissionResult,
+  PermissionUpdate,
+  SDKMessage,
+  SDKResultMessage,
+  SettingSource,
+  SDKUserMessage,
   ModelUsage,
-  NonNullableUsage,
 } from "@anthropic-ai/claude-agent-sdk";
+import { parseCliArgs } from "@t3tools/shared/cliArgs";
 import {
   ApprovalRequestId,
   type CanonicalItemType,
   type CanonicalRequestType,
+  type ClaudeSettings,
   EventId,
   type ProviderApprovalDecision,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ProviderItemId,
   type ProviderRuntimeEvent,
   type ProviderRuntimeTurnStatus,
@@ -40,33 +42,38 @@ import {
   ThreadId,
   TurnId,
   type UserInputQuestion,
-  ClaudeCodeEffort,
 } from "@t3tools/contracts";
 import {
   applyClaudePromptEffortPrefix,
-  resolveApiModelId,
-  resolveEffort,
-  trimOrNull,
+  getModelSelectionBooleanOptionValue,
+  getModelSelectionStringOptionValue,
+  getProviderOptionDescriptors,
+  resolvePromptInjectedEffort,
 } from "@t3tools/shared/model";
-import {
-  Cause,
-  DateTime,
-  Deferred,
-  Effect,
-  Exit,
-  FileSystem,
-  Fiber,
-  Layer,
-  Queue,
-  Random,
-  Ref,
-  Stream,
-} from "effect";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Fiber from "effect/Fiber";
+import * as Path from "effect/Path";
+import * as Queue from "effect/Queue";
+import * as Random from "effect/Random";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { getClaudeModelCapabilities } from "./ClaudeProvider.ts";
+import { makeClaudeCliQuery } from "./ClaudeCliTransport.ts";
+import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
+import {
+  getClaudeModelCapabilities,
+  normalizeClaudeCliEffort,
+  resolveClaudeApiModelId,
+  resolveClaudeEffort,
+} from "./ClaudeProvider.ts";
 import {
   ProviderAdapterProcessError,
   ProviderAdapterRequestError,
@@ -75,15 +82,23 @@ import {
   ProviderAdapterValidationError,
   type ProviderAdapterError,
 } from "../Errors.ts";
-import { ClaudeAdapter, type ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
+import { type ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
 import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
+const encodeUnknownJsonStringExit = Schema.encodeUnknownExit(Schema.UnknownFromJsonString);
+const decodeUnknownJsonStringExit = Schema.decodeUnknownExit(Schema.UnknownFromJsonString);
 
-const PROVIDER = "claudeAgent" as const;
+const PROVIDER = ProviderDriverKind.make("claudeAgent");
 type ClaudeTextStreamKind = Extract<RuntimeContentStreamKind, "assistant_text" | "reasoning_text">;
 type ClaudeToolResultStreamKind = Extract<
   RuntimeContentStreamKind,
   "command_output" | "file_change_output"
 >;
+type ClaudeSdkEffort = NonNullable<ClaudeQueryOptions["effort"]>;
+
+function encodeJsonStringForDiagnostics(input: unknown): string | undefined {
+  const result = encodeUnknownJsonStringExit(input);
+  return Exit.isSuccess(result) ? result.value : undefined;
+}
 
 type PromptQueueItem =
   | {
@@ -176,6 +191,8 @@ interface ClaudeQueryRuntime extends AsyncIterable<SDKMessage> {
 }
 
 export interface ClaudeAdapterLiveOptions {
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
   readonly createQuery?: (input: {
     readonly prompt: AsyncIterable<SDKUserMessage>;
     readonly options: ClaudeQueryOptions;
@@ -192,6 +209,18 @@ function isSyntheticClaudeThreadId(value: string): boolean {
   return value.startsWith("claude-thread-");
 }
 
+function hasDurableClaudeSessionId(message: SDKMessage): boolean {
+  if (message.type !== "system") {
+    return true;
+  }
+
+  return (
+    message.subtype !== "hook_started" &&
+    message.subtype !== "hook_progress" &&
+    message.subtype !== "hook_response"
+  );
+}
+
 function toMessage(cause: unknown, fallback: string): string {
   if (cause instanceof Error && cause.message.length > 0) {
     return cause.message;
@@ -199,11 +228,22 @@ function toMessage(cause: unknown, fallback: string): string {
   return fallback;
 }
 
-function toError(cause: unknown, fallback: string): Error {
-  return cause instanceof Error ? cause : new Error(toMessage(cause, fallback));
+function toProcessError(
+  cause: unknown,
+  fallback: string,
+  threadId: ThreadId,
+): ProviderAdapterProcessError {
+  return new ProviderAdapterProcessError({
+    provider: PROVIDER,
+    threadId,
+    detail: toMessage(cause, fallback),
+    cause,
+  });
 }
 
-function normalizeClaudeStreamMessages(cause: Cause.Cause<Error>): ReadonlyArray<string> {
+function normalizeClaudeStreamMessages(
+  cause: Cause.Cause<{ readonly message: string }>,
+): ReadonlyArray<string> {
   const errors = Cause.prettyErrors(cause)
     .map((error) => error.message.trim())
     .filter((message) => message.length > 0);
@@ -215,13 +255,9 @@ function normalizeClaudeStreamMessages(cause: Cause.Cause<Error>): ReadonlyArray
   return squashed.length > 0 ? [squashed] : [];
 }
 
-function getEffectiveClaudeCodeEffort(
-  effort: ClaudeCodeEffort | null | undefined,
-): Exclude<ClaudeCodeEffort, "ultrathink"> | null {
-  if (!effort) {
-    return null;
-  }
-  return effort === "ultrathink" ? null : effort;
+function getEffectiveClaudeAgentEffort(effort: string | null | undefined): ClaudeSdkEffort | null {
+  const normalized = normalizeClaudeCliEffort(effort);
+  return normalized ? (normalized as ClaudeSdkEffort) : null;
 }
 
 function isClaudeInterruptedMessage(message: string): boolean {
@@ -233,18 +269,23 @@ function isClaudeInterruptedMessage(message: string): boolean {
   );
 }
 
-function isClaudeInterruptedCause(cause: Cause.Cause<Error>): boolean {
+function isClaudeInterruptedCause(cause: Cause.Cause<{ readonly message: string }>): boolean {
   return (
     Cause.hasInterruptsOnly(cause) ||
     normalizeClaudeStreamMessages(cause).some(isClaudeInterruptedMessage)
   );
 }
 
-function messageFromClaudeStreamCause(cause: Cause.Cause<Error>, fallback: string): string {
+function messageFromClaudeStreamCause(
+  cause: Cause.Cause<{ readonly message: string }>,
+  fallback: string,
+): string {
   return normalizeClaudeStreamMessages(cause)[0] ?? fallback;
 }
 
-function interruptionMessageFromClaudeCause(cause: Cause.Cause<Error>): string {
+function interruptionMessageFromClaudeCause(
+  cause: Cause.Cause<{ readonly message: string }>,
+): string {
   const message = messageFromClaudeStreamCause(cause, "Claude runtime interrupted.");
   return isClaudeInterruptedMessage(message) ? "Claude runtime interrupted." : message;
 }
@@ -289,7 +330,7 @@ function maxClaudeContextWindowFromModelUsage(
 }
 
 function normalizeClaudeTokenUsage(
-  value: NonNullableUsage | undefined,
+  value: unknown,
   contextWindow?: number,
 ): ThreadTokenUsageSnapshot | undefined {
   if (!value || typeof value !== "object") {
@@ -459,6 +500,37 @@ function classifyRequestType(toolName: string): CanonicalRequestType {
       : "dynamic_tool_call";
 }
 
+function isTodoTool(toolName: string): boolean {
+  return toolName.toLowerCase().includes("todowrite");
+}
+
+type PlanStep = {
+  step: string;
+  status: "pending" | "inProgress" | "completed";
+};
+
+function extractPlanStepsFromTodoInput(input: Record<string, unknown>): PlanStep[] | null {
+  // TodoWrite format: { todos: [{ content, status, activeForm? }] }
+  const todos = input.todos;
+  if (!Array.isArray(todos) || todos.length === 0) {
+    return null;
+  }
+  return todos
+    .filter((t): t is Record<string, unknown> => t !== null && typeof t === "object")
+    .map((todo) => ({
+      step:
+        typeof todo.content === "string" && todo.content.trim().length > 0
+          ? todo.content.trim()
+          : "Task",
+      status:
+        todo.status === "completed"
+          ? "completed"
+          : todo.status === "in_progress"
+            ? "inProgress"
+            : "pending",
+    }));
+}
+
 function summarizeToolRequest(toolName: string, input: Record<string, unknown>): string {
   const commandValue = input.command ?? input.cmd;
   const command = typeof commandValue === "string" ? commandValue : undefined;
@@ -466,7 +538,21 @@ function summarizeToolRequest(toolName: string, input: Record<string, unknown>):
     return `${toolName}: ${command.trim().slice(0, 400)}`;
   }
 
-  const serialized = JSON.stringify(input);
+  // For agent/subagent tools, prefer human-readable description or prompt over raw JSON
+  const itemType = classifyToolItemType(toolName);
+  if (itemType === "collab_agent_tool_call") {
+    const description =
+      typeof input.description === "string" ? input.description.trim() : undefined;
+    const prompt = typeof input.prompt === "string" ? input.prompt.trim() : undefined;
+    const subagentType =
+      typeof input.subagent_type === "string" ? input.subagent_type.trim() : undefined;
+    const label = description || (prompt ? prompt.slice(0, 200) : undefined);
+    if (label) {
+      return subagentType ? `${subagentType}: ${label}` : label;
+    }
+  }
+
+  const serialized = encodeJsonStringForDiagnostics(input) ?? "[unserializable input]";
   if (serialized.length <= 400) {
     return `${toolName}: ${serialized}`;
   }
@@ -506,18 +592,19 @@ const CLAUDE_SETTING_SOURCES = [
   "local",
 ] as const satisfies ReadonlyArray<SettingSource>;
 
-function buildPromptText(input: ProviderSendTurnInput): string {
+function buildPromptText(
+  input: ProviderSendTurnInput,
+  boundInstanceId: ProviderInstanceId,
+): string {
   const rawEffort =
-    input.modelSelection?.provider === "claudeAgent" ? input.modelSelection.options?.effort : null;
+    input.modelSelection?.instanceId === boundInstanceId
+      ? getModelSelectionStringOptionValue(input.modelSelection, "effort")
+      : null;
   const claudeModel =
-    input.modelSelection?.provider === "claudeAgent" ? input.modelSelection.model : undefined;
+    input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection.model : undefined;
   const caps = getClaudeModelCapabilities(claudeModel);
 
-  // For prompt injection, we check if the raw effort is a prompt-injected level (e.g. "ultrathink").
-  // resolveEffort strips prompt-injected values (returning the default instead), so we check the raw value directly.
-  const trimmedEffort = trimOrNull(rawEffort);
-  const promptEffort =
-    trimmedEffort && caps.promptInjectedEffortLevels.includes(trimmedEffort) ? trimmedEffort : null;
+  const promptEffort = resolvePromptInjectedEffort(caps, rawEffort);
   return applyClaudePromptEffortPrefix(input.input?.trim() ?? "", promptEffort);
 }
 
@@ -554,9 +641,10 @@ const buildUserMessageEffect = Effect.fn("buildUserMessageEffect")(function* (
   dependencies: {
     readonly fileSystem: FileSystem.FileSystem;
     readonly attachmentsDir: string;
+    readonly boundInstanceId: ProviderInstanceId;
   },
 ) {
-  const text = buildPromptText(input);
+  const text = buildPromptText(input, dependencies.boundInstanceId);
   const sdkContent: Array<Record<string, unknown>> = [];
 
   if (text.length > 0) {
@@ -729,22 +817,18 @@ function exitPlanCaptureKey(input: {
 }
 
 function tryParseJsonRecord(value: string): Record<string, unknown> | undefined {
-  try {
-    const parsed = JSON.parse(value);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : undefined;
-  } catch {
+  const result = decodeUnknownJsonStringExit(value);
+  if (!Exit.isSuccess(result)) {
     return undefined;
   }
+  const parsed = result.value;
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : undefined;
 }
 
 function toolInputFingerprint(input: Record<string, unknown>): string | undefined {
-  try {
-    return JSON.stringify(input);
-  } catch {
-    return undefined;
-  }
+  return encodeJsonStringForDiagnostics(input);
 }
 
 function toolResultStreamKind(itemType: CanonicalItemType): ClaudeToolResultStreamKind | undefined {
@@ -906,11 +990,17 @@ function sdkNativeItemId(message: SDKMessage): string | undefined {
   return undefined;
 }
 
-const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
+export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
+  claudeSettings: ClaudeSettings,
   options?: ClaudeAdapterLiveOptions,
 ) {
+  const boundInstanceId = options?.instanceId ?? ProviderInstanceId.make("claudeAgent");
   const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
   const serverConfig = yield* ServerConfig;
+  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
+    Effect.provideService(Path.Path, path),
+  );
   const nativeEventLogger =
     options?.nativeEventLogger ??
     (options?.nativeEventLogPath !== undefined
@@ -924,11 +1014,14 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     ((input: {
       readonly prompt: AsyncIterable<SDKUserMessage>;
       readonly options: ClaudeQueryOptions;
-    }) => query({ prompt: input.prompt, options: input.options }) as ClaudeQueryRuntime);
+    }) =>
+      makeClaudeCliQuery({
+        prompt: input.prompt,
+        options: input.options,
+      }) as ClaudeQueryRuntime);
 
   const sessions = new Map<ThreadId, ClaudeSessionContext>();
   const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
-  const serverSettingsService = yield* ServerSettingsService;
 
   const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
   const nextEventId = Effect.map(Random.nextUUIDv4, (id) => EventId.make(id));
@@ -945,7 +1038,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       return;
     }
 
-    const observedAt = new Date().toISOString();
+    const observedAt = yield* nowIso;
     const itemId = sdkNativeItemId(message);
 
     yield* nativeEventLogger.write(
@@ -955,7 +1048,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           id:
             "uuid" in message && typeof message.uuid === "string"
               ? message.uuid
-              : crypto.randomUUID(),
+              : yield* Random.nextUUIDv4,
           kind: "notification",
           provider: PROVIDER,
           createdAt: observedAt,
@@ -963,7 +1056,11 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           ...(typeof message.session_id === "string"
             ? { providerThreadId: message.session_id }
             : {}),
-          ...(context.turnState ? { turnId: asCanonicalTurnId(context.turnState.turnId) } : {}),
+          ...(context.turnState
+            ? {
+                turnId: asCanonicalTurnId(context.turnState.turnId),
+              }
+            : {}),
           ...(itemId ? { itemId: ProviderItemId.make(itemId) } : {}),
           payload: message,
         },
@@ -1196,6 +1293,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     if (typeof message.session_id !== "string" || message.session_id.length === 0) {
       return;
     }
+    if (!hasDurableClaudeSessionId(message)) {
+      return;
+    }
     const nextThreadId = message.session_id;
     context.resumeSessionId = message.session_id;
     yield* updateResumeCursor(context);
@@ -1352,7 +1452,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           ...(typeof accumulatedTotalProcessedTokens === "number" &&
           Number.isFinite(accumulatedTotalProcessedTokens) &&
           accumulatedTotalProcessedTokens > lastGoodUsage.usedTokens
-            ? { totalProcessedTokens: accumulatedTotalProcessedTokens }
+            ? {
+                totalProcessedTokens: accumulatedTotalProcessedTokens,
+              }
             : {}),
         }
       : accumulatedSnapshot;
@@ -1416,7 +1518,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
             input: tool.input,
           },
         },
-        providerRefs: nativeProviderRefs(context, { providerItemId: tool.itemId }),
+        providerRefs: nativeProviderRefs(context, {
+          providerItemId: tool.itemId,
+        }),
         raw: {
           source: "claude.sdk.message",
           method: "claude/result",
@@ -1538,7 +1642,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           threadId: context.session.threadId,
           turnId: context.turnState.turnId,
           ...(assistantBlockEntry?.block
-            ? { itemId: asRuntimeItemId(assistantBlockEntry.block.itemId) }
+            ? {
+                itemId: asRuntimeItemId(assistantBlockEntry.block.itemId),
+              }
             : {}),
           payload: {
             streamKind,
@@ -1597,7 +1703,11 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           provider: PROVIDER,
           createdAt: stamp.createdAt,
           threadId: context.session.threadId,
-          ...(context.turnState ? { turnId: asCanonicalTurnId(context.turnState.turnId) } : {}),
+          ...(context.turnState
+            ? {
+                turnId: asCanonicalTurnId(context.turnState.turnId),
+              }
+            : {}),
           itemId: asRuntimeItemId(nextTool.itemId),
           payload: {
             itemType: nextTool.itemType,
@@ -1609,13 +1719,39 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
               input: nextTool.input,
             },
           },
-          providerRefs: nativeProviderRefs(context, { providerItemId: nextTool.itemId }),
+          providerRefs: nativeProviderRefs(context, {
+            providerItemId: nextTool.itemId,
+          }),
           raw: {
             source: "claude.sdk.message",
             method: "claude/stream_event/content_block_delta/input_json_delta",
             payload: message,
           },
         });
+
+        // Emit plan update when TodoWrite input is parsed
+        if (parsedInput && isTodoTool(nextTool.toolName)) {
+          const planSteps = extractPlanStepsFromTodoInput(parsedInput);
+          if (planSteps && planSteps.length > 0) {
+            const planStamp = yield* makeEventStamp();
+            yield* offerRuntimeEvent({
+              type: "turn.plan.updated",
+              eventId: planStamp.eventId,
+              provider: PROVIDER,
+              createdAt: planStamp.createdAt,
+              threadId: context.session.threadId,
+              ...(context.turnState
+                ? {
+                    turnId: asCanonicalTurnId(context.turnState.turnId),
+                  }
+                : {}),
+              payload: {
+                plan: planSteps,
+              },
+              providerRefs: nativeProviderRefs(context),
+            });
+          }
+        }
       }
       return;
     }
@@ -1678,7 +1814,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
             input: toolInput,
           },
         },
-        providerRefs: nativeProviderRefs(context, { providerItemId: tool.itemId }),
+        providerRefs: nativeProviderRefs(context, {
+          providerItemId: tool.itemId,
+        }),
         raw: {
           source: "claude.sdk.message",
           method: "claude/stream_event/content_block_start",
@@ -1750,7 +1888,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           ...(tool.detail ? { detail: tool.detail } : {}),
           data: toolData,
         },
-        providerRefs: nativeProviderRefs(context, { providerItemId: tool.itemId }),
+        providerRefs: nativeProviderRefs(context, {
+          providerItemId: tool.itemId,
+        }),
         raw: {
           source: "claude.sdk.message",
           method: "claude/user",
@@ -1773,7 +1913,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
             streamKind,
             delta: toolResult.text,
           },
-          providerRefs: nativeProviderRefs(context, { providerItemId: tool.itemId }),
+          providerRefs: nativeProviderRefs(context, {
+            providerItemId: tool.itemId,
+          }),
           raw: {
             source: "claude.sdk.message",
             method: "claude/user",
@@ -1798,7 +1940,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           ...(tool.detail ? { detail: tool.detail } : {}),
           data: toolData,
         },
-        providerRefs: nativeProviderRefs(context, { providerItemId: tool.itemId }),
+        providerRefs: nativeProviderRefs(context, {
+          providerItemId: tool.itemId,
+        }),
         raw: {
           source: "claude.sdk.message",
           method: "claude/user",
@@ -2154,7 +2298,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         payload: {
           summary: message.summary,
           ...(message.preceding_tool_use_ids.length > 0
-            ? { precedingToolUseIds: message.preceding_tool_use_ids }
+            ? {
+                precedingToolUseIds: message.preceding_tool_use_ids,
+              }
             : {}),
         },
       });
@@ -2225,9 +2371,11 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     }
   });
 
-  const runSdkStream = (context: ClaudeSessionContext): Effect.Effect<void, Error> =>
+  const runSdkStream = (
+    context: ClaudeSessionContext,
+  ): Effect.Effect<void, ProviderAdapterProcessError> =>
     Stream.fromAsyncIterable(context.query, (cause) =>
-      toError(cause, "Claude runtime stream failed."),
+      toProcessError(cause, "Claude runtime stream failed.", context.session.threadId),
     ).pipe(
       Stream.takeWhile(() => !context.stopped),
       Stream.runForEach((message) => handleSdkMessage(context, message)),
@@ -2235,7 +2383,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
 
   const handleStreamExit = Effect.fn("handleStreamExit")(function* (
     context: ClaudeSessionContext,
-    exit: Exit.Exit<void, Error>,
+    exit: Exit.Exit<void, ProviderAdapterProcessError>,
   ) {
     if (context.stopped) {
       return;
@@ -2304,12 +2452,20 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       yield* Fiber.interrupt(streamFiber);
     }
 
-    // @effect-diagnostics-next-line tryCatchInEffectGen:off
-    try {
-      context.query.close();
-    } catch (cause) {
-      yield* emitRuntimeError(context, "Failed to close Claude runtime query.", cause);
-    }
+    yield* Effect.try({
+      try: () => context.query.close(),
+      catch: (cause) =>
+        new ProviderAdapterProcessError({
+          provider: PROVIDER,
+          threadId: context.session.threadId,
+          detail: toMessage(cause, "Failed to close Claude runtime query."),
+          cause,
+        }),
+    }).pipe(
+      Effect.catch((cause) =>
+        emitRuntimeError(context, "Failed to close Claude runtime query.", cause),
+      ),
+    );
 
     const updatedAt = yield* nowIso;
     context.session = {
@@ -2371,6 +2527,27 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         });
       }
 
+      const existingContext = sessions.get(input.threadId);
+      if (existingContext) {
+        yield* Effect.logWarning("claude.session.replacing", {
+          threadId: input.threadId,
+          existingSessionStatus: existingContext.session.status,
+          reason: "startSession called with existing active session",
+        });
+        yield* stopSessionInternal(existingContext, {
+          emitExitEvent: false,
+        }).pipe(
+          // Replacement cleanup is best-effort: never block the new session on
+          // either typed failures or unexpected defects from tearing down the old one.
+          Effect.catchCause((cause) =>
+            Effect.logWarning("claude.session.replace.stop-failed", {
+              threadId: input.threadId,
+              cause,
+            }),
+          ),
+        );
+      }
+
       const startedAt = yield* nowIso;
       const resumeState = readClaudeResumeState(input.resumeCursor);
       const threadId = input.threadId;
@@ -2406,15 +2583,22 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       const handleAskUserQuestion = Effect.fn("handleAskUserQuestion")(function* (
         context: ClaudeSessionContext,
         toolInput: Record<string, unknown>,
-        callbackOptions: { readonly signal: AbortSignal; readonly toolUseID?: string },
+        callbackOptions: {
+          readonly signal: AbortSignal;
+          readonly toolUseID?: string;
+        },
       ) {
         const requestId = ApprovalRequestId.make(yield* Random.nextUUIDv4);
 
         // Parse questions from the SDK's AskUserQuestion input.
+        // `id` MUST equal the full question text — Claude SDK >= 2.1.121 looks
+        // up answers by question text in `mapToolResultToToolResultBlockParam`,
+        // so the key the UI uses to keep its draft answer must match the SDK's
+        // expected lookup key. See https://github.com/pingdotgg/t3code/issues/2388
         const rawQuestions = Array.isArray(toolInput.questions) ? toolInput.questions : [];
         const questions: Array<UserInputQuestion> = rawQuestions.map(
           (q: Record<string, unknown>, idx: number) => ({
-            id: typeof q.header === "string" ? q.header : `q-${idx}`,
+            id: typeof q.question === "string" && q.question.length > 0 ? q.question : `q-${idx}`,
             header: typeof q.header === "string" ? q.header : `Question ${idx + 1}`,
             question: typeof q.question === "string" ? q.question : "",
             options: Array.isArray(q.options)
@@ -2442,7 +2626,11 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           provider: PROVIDER,
           createdAt: requestedStamp.createdAt,
           threadId: context.session.threadId,
-          ...(context.turnState ? { turnId: asCanonicalTurnId(context.turnState.turnId) } : {}),
+          ...(context.turnState
+            ? {
+                turnId: asCanonicalTurnId(context.turnState.turnId),
+              }
+            : {}),
           requestId: asRuntimeRequestId(requestId),
           payload: { questions },
           providerRefs: nativeProviderRefs(context, {
@@ -2451,7 +2639,10 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           raw: {
             source: "claude.sdk.permission",
             method: "canUseTool/AskUserQuestion",
-            payload: { toolName: "AskUserQuestion", input: toolInput },
+            payload: {
+              toolName: "AskUserQuestion",
+              input: toolInput,
+            },
           },
         });
 
@@ -2466,7 +2657,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           pendingUserInputs.delete(requestId);
           runFork(Deferred.succeed(answersDeferred, {} as ProviderUserInputAnswers));
         };
-        callbackOptions.signal.addEventListener("abort", onAbort, { once: true });
+        callbackOptions.signal.addEventListener("abort", onAbort, {
+          once: true,
+        });
 
         // Block until the user provides answers.
         const answers = yield* Deferred.await(answersDeferred);
@@ -2480,7 +2673,11 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           provider: PROVIDER,
           createdAt: resolvedStamp.createdAt,
           threadId: context.session.threadId,
-          ...(context.turnState ? { turnId: asCanonicalTurnId(context.turnState.turnId) } : {}),
+          ...(context.turnState
+            ? {
+                turnId: asCanonicalTurnId(context.turnState.turnId),
+              }
+            : {}),
           requestId: asRuntimeRequestId(requestId),
           payload: { answers },
           providerRefs: nativeProviderRefs(context, {
@@ -2650,7 +2847,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
             behavior: "allow",
             updatedInput: toolInput,
             ...(decision === "acceptForSession" && pendingApproval.suggestions
-              ? { updatedPermissions: [...pendingApproval.suggestions] }
+              ? {
+                  updatedPermissions: [...pendingApproval.suggestions],
+                }
               : {}),
           } satisfies PermissionResult;
         }
@@ -2667,31 +2866,28 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
         runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
-      const claudeSettings = yield* serverSettingsService.getSettings.pipe(
-        Effect.map((settings) => settings.providers.claudeAgent),
-        Effect.mapError(
-          (error) =>
-            new ProviderAdapterProcessError({
-              provider: PROVIDER,
-              threadId: input.threadId,
-              detail: error.message,
-              cause: error,
-            }),
-        ),
-      );
       const claudeBinaryPath = claudeSettings.binaryPath;
+      const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
       const modelSelection =
-        input.modelSelection?.provider === "claudeAgent" ? input.modelSelection : undefined;
+        input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;
       const caps = getClaudeModelCapabilities(modelSelection?.model);
-      const apiModelId = modelSelection ? resolveApiModelId(modelSelection) : undefined;
-      const effort = (resolveEffort(caps, modelSelection?.options?.effort) ??
-        null) as ClaudeCodeEffort | null;
-      const fastMode = modelSelection?.options?.fastMode === true && caps.supportsFastMode;
-      const thinking =
-        typeof modelSelection?.options?.thinking === "boolean" && caps.supportsThinkingToggle
-          ? modelSelection.options.thinking
-          : undefined;
-      const effectiveEffort = getEffectiveClaudeCodeEffort(effort);
+      const descriptors = getProviderOptionDescriptors({ caps });
+      const apiModelId = modelSelection ? resolveClaudeApiModelId(modelSelection) : undefined;
+      const rawEffort = getModelSelectionStringOptionValue(modelSelection, "effort");
+      const effort = resolveClaudeEffort(caps, rawEffort) ?? null;
+      const fastModeSupported = descriptors.some(
+        (descriptor) => descriptor.type === "boolean" && descriptor.id === "fastMode",
+      );
+      const thinkingSupported = descriptors.some(
+        (descriptor) => descriptor.type === "boolean" && descriptor.id === "thinking",
+      );
+      const fastMode =
+        getModelSelectionBooleanOptionValue(modelSelection, "fastMode") === true &&
+        fastModeSupported;
+      const thinking = thinkingSupported
+        ? getModelSelectionBooleanOptionValue(modelSelection, "thinking")
+        : undefined;
+      const effectiveEffort = getEffectiveClaudeAgentEffort(effort);
       const runtimeModeToPermission: Record<string, PermissionMode> = {
         "auto-accept-edits": "acceptEdits",
         "full-access": "bypassPermissions",
@@ -2701,13 +2897,19 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         ...(typeof thinking === "boolean" ? { alwaysThinkingEnabled: thinking } : {}),
         ...(fastMode ? { fastMode: true } : {}),
       };
-
       const queryOptions: ClaudeQueryOptions = {
         ...(input.cwd ? { cwd: input.cwd } : {}),
         ...(apiModelId ? { model: apiModelId } : {}),
         pathToClaudeCodeExecutable: claudeBinaryPath,
+        systemPrompt: { type: "preset", preset: "claude_code" },
         settingSources: [...CLAUDE_SETTING_SOURCES],
-        ...(effectiveEffort ? { effort: effectiveEffort } : {}),
+        // The SDK type lags the CLI here: Opus 4.7 accepts `xhigh` even though
+        // the published `Options["effort"]` union currently stops at `max`.
+        ...(effectiveEffort
+          ? {
+              effort: effectiveEffort as unknown as NonNullable<ClaudeQueryOptions["effort"]>,
+            }
+          : {}),
         ...(permissionMode ? { permissionMode } : {}),
         ...(permissionMode === "bypassPermissions"
           ? { allowDangerouslySkipPermissions: true }
@@ -2717,10 +2919,36 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         ...(newSessionId ? { sessionId: newSessionId } : {}),
         includePartialMessages: true,
         canUseTool,
-        env: process.env,
+        env: claudeEnvironment,
         ...(input.cwd ? { additionalDirectories: [input.cwd] } : {}),
+        ...(Object.keys(extraArgs).length > 0 ? { extraArgs } : {}),
       };
 
+      yield* Effect.annotateCurrentSpan({
+        "provider.kind": PROVIDER,
+        "provider.thread_id": threadId,
+        "provider.runtime_mode": input.runtimeMode,
+        "claude.resume.source":
+          existingResumeSessionId !== undefined ? "resume-session" : "generated-session",
+        "claude.resume.thread_id": resumeState?.threadId ?? "",
+        "claude.resume.session_id": existingResumeSessionId ?? "",
+        "claude.resume.session_at": resumeState?.resumeSessionAt ?? "",
+        "claude.resume.turn_count": resumeState?.turnCount ?? -1,
+        "claude.query.cwd": input.cwd ?? "",
+        "claude.query.model": apiModelId ?? "",
+        "claude.query.effort": effectiveEffort ?? "",
+        "claude.query.permission_mode": permissionMode ?? "",
+        "claude.query.allow_dangerously_skip_permissions": permissionMode === "bypassPermissions",
+        "claude.query.resume": existingResumeSessionId ?? "",
+        "claude.query.session_id": newSessionId ?? "",
+        "claude.query.include_partial_messages": true,
+        "claude.query.additional_directories": input.cwd ? [input.cwd] : [],
+        "claude.query.setting_sources": [...CLAUDE_SETTING_SOURCES],
+        "claude.query.settings_json": encodeJsonStringForDiagnostics(settings) ?? "",
+        "claude.query.extra_args_json": encodeJsonStringForDiagnostics(extraArgs) ?? "",
+        "claude.query.path_to_executable": claudeBinaryPath,
+      });
+
       const queryRuntime = yield* Effect.try({
         try: () =>
           createQuery({
@@ -2739,6 +2967,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       const session: ProviderSession = {
         threadId,
         provider: PROVIDER,
+        providerInstanceId: boundInstanceId,
         status: "ready",
         runtimeMode: input.runtimeMode,
         ...(input.cwd ? { cwd: input.cwd } : {}),
@@ -2850,7 +3079,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
   const sendTurn: ClaudeAdapterShape["sendTurn"] = Effect.fn("sendTurn")(function* (input) {
     const context = yield* requireSession(input.threadId);
     const modelSelection =
-      input.modelSelection?.provider === "claudeAgent" ? input.modelSelection : undefined;
+      input.modelSelection !== undefined && input.modelSelection.instanceId === boundInstanceId
+        ? input.modelSelection
+        : undefined;
 
     if (context.turnState) {
       // Auto-close a stale synthetic turn (from background agent responses
@@ -2859,7 +3090,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     }
 
     if (modelSelection?.model) {
-      const apiModelId = resolveApiModelId(modelSelection);
+      const apiModelId = resolveClaudeApiModelId(modelSelection);
       if (context.currentApiModelId !== apiModelId) {
         yield* Effect.tryPromise({
           try: () => context.query.setModel(apiModelId),
@@ -2924,6 +3155,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     const message = yield* buildUserMessageEffect(input, {
       fileSystem,
       attachmentsDir: serverConfig.attachmentsDir,
+      boundInstanceId,
     });
 
     yield* Queue.offer(context.promptQueue, {
@@ -3061,9 +3293,3 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     },
   } satisfies ClaudeAdapterShape;
 });
-
-export const ClaudeAdapterLive = Layer.effect(ClaudeAdapter, makeClaudeAdapter());
-
-export function makeClaudeAdapterLive(options?: ClaudeAdapterLiveOptions) {
-  return Layer.effect(ClaudeAdapter, makeClaudeAdapter(options));
-}
diff --git a/apps/server/src/provider/Layers/ClaudeCliTransport.test.ts b/apps/server/src/provider/Layers/ClaudeCliTransport.test.ts
new file mode 100644
index 00000000000..8b7ed16e227
--- /dev/null
+++ b/apps/server/src/provider/Layers/ClaudeCliTransport.test.ts
@@ -0,0 +1,221 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { assert, describe, it } from "@effect/vitest";
+
+import { makeClaudeCliQuery } from "./ClaudeCliTransport.ts";
+
+/**
+ * A fake `claude` binary (Node script) that speaks the stream-json control
+ * protocol just enough to exercise the transport end to end:
+ *  - answers the `initialize` control request with account + commands,
+ *  - on a user message, emits one assistant message then a result,
+ *  - answers `interrupt`,
+ *  - when FAKE_EMIT_PERMISSION=1, sends a `can_use_tool` control request and
+ *    echoes the decision back as a system message.
+ */
+const FAKE_CLI = `
+let buffer = "";
+function send(obj) { process.stdout.write(JSON.stringify(obj) + "\\n"); }
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let i;
+  while ((i = buffer.indexOf("\\n")) !== -1) {
+    const line = buffer.slice(0, i).trim();
+    buffer = buffer.slice(i + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    handle(msg);
+  }
+});
+
+function handle(msg) {
+  if (msg.type === "control_request" && msg.request?.subtype === "initialize") {
+    send({
+      type: "control_response",
+      response: {
+        request_id: msg.request_id,
+        subtype: "success",
+        response: {
+          account: { email: "user@example.com", subscriptionType: "claude_pro_subscription", tokenSource: "oauth" },
+          commands: [{ name: "compact", description: "Compact" }],
+        },
+      },
+    });
+    if (process.env.FAKE_EMIT_PERMISSION === "1") {
+      send({
+        type: "control_request",
+        request_id: "perm-1",
+        request: { subtype: "can_use_tool", tool_name: "Bash", input: { command: "ls" } },
+      });
+    }
+    return;
+  }
+  if (msg.type === "control_request" && msg.request?.subtype === "interrupt") {
+    send({ type: "control_response", response: { request_id: msg.request_id, subtype: "success", response: {} } });
+    return;
+  }
+  if (msg.type === "control_response") {
+    // Our answer to the can_use_tool request — echo the decision out.
+    send({ type: "system", subtype: "permission_decision", decision: msg.response?.response });
+    send({ type: "result", subtype: "success", is_error: false, session_id: "s1", uuid: "r-perm" });
+    return;
+  }
+  if (msg.type === "user") {
+    send({ type: "system", subtype: "init", session_id: "s1" });
+    send({ type: "assistant", message: { id: "a1", role: "assistant", content: [{ type: "text", text: "hi" }] }, session_id: "s1" });
+    send({ type: "result", subtype: "success", is_error: false, session_id: "s1", uuid: "r1" });
+    return;
+  }
+}
+`;
+
+function makeFakeCli(): { dir: string; cliPath: string; cleanup: () => void } {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "claude-cli-transport-"));
+  const cliPath = path.join(dir, "fake-cli.mjs");
+  writeFileSync(cliPath, FAKE_CLI, "utf8");
+  return { dir, cliPath, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+async function* once(message: unknown): AsyncGenerator<unknown> {
+  yield message;
+}
+
+async function* never(signal: AbortSignal): AsyncGenerator<unknown> {
+  await new Promise<void>((resolve) => {
+    if (signal.aborted) resolve();
+    else signal.addEventListener("abort", () => resolve(), { once: true });
+  });
+}
+
+describe("ClaudeCliTransport", () => {
+  it("streams assistant + result messages from a user prompt", async () => {
+    const fake = makeFakeCli();
+    try {
+      const query = makeClaudeCliQuery({
+        prompt: once({
+          type: "user",
+          session_id: "",
+          message: { role: "user", content: [{ type: "text", text: "hello" }] },
+          parent_tool_use_id: null,
+        }) as AsyncIterable<never>,
+        options: { pathToClaudeCodeExecutable: fake.cliPath } as never,
+      });
+
+      const types: string[] = [];
+      for await (const message of query) {
+        types.push((message as { type: string }).type);
+        if ((message as { type: string }).type === "result") break;
+      }
+      query.close();
+
+      assert.deepEqual(types, ["system", "assistant", "result"]);
+    } finally {
+      fake.cleanup();
+    }
+  });
+
+  it("resolves initialize() with the account + commands payload", async () => {
+    const fake = makeFakeCli();
+    const abort = new AbortController();
+    try {
+      const query = makeClaudeCliQuery({
+        prompt: never(abort.signal) as AsyncIterable<never>,
+        options: { pathToClaudeCodeExecutable: fake.cliPath } as never,
+      });
+      const init = await query.initialize();
+      abort.abort();
+      query.close();
+
+      assert.equal(init.account?.email, "user@example.com");
+      assert.equal(init.account?.subscriptionType, "claude_pro_subscription");
+      assert.equal(init.account?.tokenSource, "oauth");
+      assert.deepEqual(init.commands, [{ name: "compact", description: "Compact" }]);
+    } finally {
+      fake.cleanup();
+    }
+  });
+
+  it("round-trips an interrupt control request", async () => {
+    const fake = makeFakeCli();
+    const abort = new AbortController();
+    try {
+      const query = makeClaudeCliQuery({
+        prompt: never(abort.signal) as AsyncIterable<never>,
+        options: { pathToClaudeCodeExecutable: fake.cliPath } as never,
+      });
+      await query.initialize();
+      // Resolves only if the fake answered the control request by request_id.
+      await query.interrupt();
+      abort.abort();
+      query.close();
+      assert.ok(true);
+    } finally {
+      fake.cleanup();
+    }
+  });
+
+  it("bridges inbound can_use_tool to the canUseTool callback", async () => {
+    const fake = makeFakeCli();
+    const abort = new AbortController();
+    process.env.FAKE_EMIT_PERMISSION = "1";
+    try {
+      let sawToolName: string | undefined;
+      const query = makeClaudeCliQuery({
+        prompt: never(abort.signal) as AsyncIterable<never>,
+        options: {
+          pathToClaudeCodeExecutable: fake.cliPath,
+          canUseTool: async (toolName: string) => {
+            sawToolName = toolName;
+            return { behavior: "allow", updatedInput: { command: "ls" } };
+          },
+        } as never,
+      });
+
+      let decision: unknown;
+      for await (const message of query) {
+        const m = message as { type: string; subtype?: string; decision?: unknown };
+        if (m.type === "system" && m.subtype === "permission_decision") decision = m.decision;
+        if (m.type === "result") break;
+      }
+      abort.abort();
+      query.close();
+
+      assert.equal(sawToolName, "Bash");
+      assert.deepEqual(decision, { behavior: "allow", updatedInput: { command: "ls" } });
+    } finally {
+      delete process.env.FAKE_EMIT_PERMISSION;
+      fake.cleanup();
+    }
+  });
+
+  it("ends the iterator cleanly when the process exits", async () => {
+    const fake = makeFakeCli();
+    try {
+      const query = makeClaudeCliQuery({
+        prompt: once({
+          type: "user",
+          session_id: "",
+          message: { role: "user", content: [{ type: "text", text: "hi" }] },
+          parent_tool_use_id: null,
+        }) as AsyncIterable<never>,
+        options: { pathToClaudeCodeExecutable: fake.cliPath } as never,
+      });
+
+      let count = 0;
+      for await (const _message of query) {
+        count += 1;
+        if (count > 10) break;
+      }
+      // Iterator returned (process exits after closing stdin) without hanging.
+      assert.ok(count >= 3);
+    } finally {
+      fake.cleanup();
+    }
+  });
+});
diff --git a/apps/server/src/provider/Layers/ClaudeCliTransport.ts b/apps/server/src/provider/Layers/ClaudeCliTransport.ts
new file mode 100644
index 00000000000..0c644a6b7ce
--- /dev/null
+++ b/apps/server/src/provider/Layers/ClaudeCliTransport.ts
@@ -0,0 +1,581 @@
+// @effect-diagnostics nodeBuiltinImport:off
+// @effect-diagnostics globalRandom:off
+// @effect-diagnostics globalTimers:off
+/**
+ * ClaudeCliTransport - SDK-free driver for the native `claude` binary.
+ *
+ * Replaces `@anthropic-ai/claude-agent-sdk`'s `query()` runtime with a direct
+ * child-process spawn that speaks the binary's `stream-json` IPC protocol.
+ * The shape it returns is intentionally identical to the SDK's query object
+ * (`AsyncIterable<SDKMessage>` plus `interrupt/setModel/setPermissionMode/
+ * setMaxThinkingTokens/close`) so it drops straight into the existing
+ * `createQuery` seam in {@link module:ClaudeAdapterLive} with no downstream
+ * changes.
+ *
+ * Billing rationale: the SDK package is a *type-only* dependency after this
+ * change. No SDK runtime code executes, so usage bills against the local
+ * `claude` login (subscription) rather than pay-per-token API credits — as
+ * long as the caller does not inject ANTHROPIC_API_KEY into `options.env`.
+ *
+ * Wire protocol (reverse-engineered from sdk.mjs @ 0.2.111 — the contract we
+ * must match exactly):
+ *
+ *  - Base flags: `--output-format stream-json --verbose --input-format
+ *    stream-json`. With a `canUseTool` callback the SDK adds
+ *    `--permission-prompt-tool stdio`, so permission prompts arrive as
+ *    `control_request{subtype:can_use_tool}` on stdout and are answered with
+ *    a `control_response` on stdin. No separate MCP server is involved.
+ *  - stdin (NDJSON): user messages; our control requests
+ *    `{request_id,type:"control_request",request:{subtype}}`; our permission
+ *    answers `{type:"control_response",response:{subtype:"success",
+ *    request_id,response:<PermissionResult>}}`.
+ *  - stdout (NDJSON): SDKMessage objects; `control_response`; inbound
+ *    `control_request` (can_use_tool); `control_cancel_request`; plus
+ *    `keep_alive` / `transcript_mirror` which are ignored.
+ *
+ * @module ClaudeCliTransport
+ */
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+
+import type {
+  CanUseTool,
+  Options as ClaudeQueryOptions,
+  PermissionResult,
+  SDKMessage,
+  SDKUserMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * The exact interface the Claude adapter expects back from `createQuery`.
+ * Mirrors the SDK's query object.
+ */
+export interface ClaudeCliQueryRuntime extends AsyncIterable<SDKMessage> {
+  readonly interrupt: () => Promise<void>;
+  readonly setModel: (model?: string) => Promise<void>;
+  readonly setPermissionMode: (mode: string) => Promise<void>;
+  readonly setMaxThinkingTokens: (maxThinkingTokens: number | null) => Promise<void>;
+  readonly close: () => void;
+  /**
+   * Resolves with the CLI's `initialize` control-response payload
+   * (`{ account, commands, models, ... }`). The handshake is sent
+   * automatically on startup; this returns the (memoised) result. Used by
+   * the capabilities/auth probe, which never sends a prompt.
+   */
+  readonly initialize: () => Promise<InitializeResult>;
+}
+
+export interface InitializeResult {
+  readonly account?: {
+    readonly email?: string;
+    readonly subscriptionType?: string;
+    readonly tokenSource?: string;
+  };
+  readonly commands?: ReadonlyArray<unknown>;
+  readonly models?: ReadonlyArray<unknown>;
+  readonly [key: string]: unknown;
+}
+
+export interface ClaudeCliQueryInput {
+  readonly prompt: AsyncIterable<SDKUserMessage>;
+  readonly options: ClaudeQueryOptions;
+}
+
+/** Milliseconds to wait after closing stdin before escalating SIGTERM→SIGKILL. */
+const GRACEFUL_SHUTDOWN_MS = 2_000;
+const SIGKILL_ESCALATION_MS = 3_000;
+
+/** Treat a path as a JS entrypoint (needs node/bun) if it has a JS/TS ext. */
+function isJsEntrypoint(path: string): boolean {
+  return [".js", ".mjs", ".cjs", ".tsx", ".ts", ".jsx"].some((ext) => path.endsWith(ext));
+}
+
+function defaultExecutable(): string {
+  return typeof (globalThis as { Bun?: unknown }).Bun !== "undefined" ||
+    process.versions.bun !== undefined
+    ? "bun"
+    : "node";
+}
+
+function newRequestId(): string {
+  return Math.random().toString(36).substring(2, 15);
+}
+
+/**
+ * Build the binary argv from `ClaudeQueryOptions`, mirroring the flag builder
+ * in the SDK. Only the options the Claude adapter actually sets are mapped;
+ * unknown extras flow through `extraArgs`.
+ */
+function buildArgs(options: ClaudeQueryOptions): string[] {
+  const args: string[] = [
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--input-format",
+    "stream-json",
+  ];
+
+  const o = options as ClaudeQueryOptions & {
+    readonly settings?: unknown;
+    readonly extraArgs?: Record<string, string | null>;
+    readonly additionalDirectories?: ReadonlyArray<string>;
+  };
+
+  if (o.effort) args.push("--effort", String(o.effort));
+  if (o.model) args.push("--model", String(o.model));
+  if (o.fallbackModel) args.push("--fallback-model", String(o.fallbackModel));
+
+  // A canUseTool callback routes permission prompts through stdio control IPC.
+  if (typeof o.canUseTool === "function") {
+    args.push("--permission-prompt-tool", "stdio");
+  }
+
+  if (o.resume) args.push("--resume", String(o.resume));
+  if (o.sessionId) args.push("--session-id", String(o.sessionId));
+  if (o.resumeSessionAt) args.push("--resume-session-at", String(o.resumeSessionAt));
+  if (o.forkSession) args.push("--fork-session");
+  if ((o as { persistSession?: boolean }).persistSession === false) {
+    args.push("--no-session-persistence");
+  }
+
+  const settingSources = o.settingSources;
+  if (settingSources !== undefined) {
+    args.push(`--setting-sources=${(settingSources as ReadonlyArray<string>).join(",")}`);
+  }
+
+  if (o.permissionMode) args.push("--permission-mode", String(o.permissionMode));
+  if (o.allowDangerouslySkipPermissions) args.push("--allow-dangerously-skip-permissions");
+  if (o.includePartialMessages) args.push("--include-partial-messages");
+
+  for (const dir of o.additionalDirectories ?? []) {
+    args.push("--add-dir", dir);
+  }
+
+  // `settings` is a JSON blob the CLI accepts via --settings.
+  if (o.settings !== undefined) {
+    args.push(
+      "--settings",
+      typeof o.settings === "string" ? o.settings : JSON.stringify(o.settings),
+    );
+  }
+
+  // Pass-through extra flags: { "flag-name": value | null }. null = boolean flag.
+  for (const [flag, value] of Object.entries(o.extraArgs ?? {})) {
+    if (value === null) args.push(`--${flag}`);
+    else args.push(`--${flag}`, value);
+  }
+
+  return args;
+}
+
+/**
+ * Build the `initialize` control-request payload, mirroring the SDK. We don't
+ * use hooks / sdkMcpServers / jsonSchema, so those stay undefined; the
+ * systemPrompt and related fields flow through from options when present.
+ */
+function buildInitializePayload(options: ClaudeQueryOptions): Record<string, unknown> {
+  const o = options as ClaudeQueryOptions & {
+    readonly systemPrompt?: unknown;
+    readonly appendSystemPrompt?: unknown;
+    readonly appendSubagentSystemPrompt?: unknown;
+    readonly excludeDynamicSections?: unknown;
+    readonly agents?: unknown;
+    readonly promptSuggestions?: unknown;
+    readonly agentProgressSummaries?: unknown;
+  };
+  return {
+    subtype: "initialize",
+    hooks: undefined,
+    sdkMcpServers: undefined,
+    jsonSchema: undefined,
+    systemPrompt: typeof o.systemPrompt === "string" ? [o.systemPrompt] : o.systemPrompt,
+    appendSystemPrompt: o.appendSystemPrompt,
+    appendSubagentSystemPrompt: o.appendSubagentSystemPrompt,
+    excludeDynamicSections: o.excludeDynamicSections,
+    agents: o.agents,
+    promptSuggestions: o.promptSuggestions,
+    agentProgressSummaries: o.agentProgressSummaries,
+  };
+}
+
+interface AsyncQueue<T> {
+  push: (value: T) => void;
+  end: () => void;
+  fail: (error: unknown) => void;
+  iterator: () => AsyncIterator<T>;
+}
+
+/**
+ * Unbounded async queue bridging push-based stdout framing to the pull-based
+ * `for await` the adapter consumes. Matches the buffering semantics of the
+ * SDK's internal message stream (and the test FakeClaudeQuery).
+ */
+function makeAsyncQueue<T>(): AsyncQueue<T> {
+  const buffer: T[] = [];
+  const waiters: Array<{
+    resolve: (r: IteratorResult<T>) => void;
+    reject: (e: unknown) => void;
+  }> = [];
+  let ended = false;
+  let failure: unknown | undefined;
+
+  return {
+    push(value) {
+      if (ended) return;
+      const waiter = waiters.shift();
+      if (waiter) waiter.resolve({ done: false, value });
+      else buffer.push(value);
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      for (const w of waiters.splice(0)) w.resolve({ done: true, value: undefined });
+    },
+    fail(error) {
+      if (ended) return;
+      ended = true;
+      failure = error;
+      for (const w of waiters.splice(0)) w.reject(error);
+    },
+    iterator() {
+      return {
+        next() {
+          if (buffer.length > 0) {
+            return Promise.resolve({ done: false, value: buffer.shift() as T });
+          }
+          if (failure !== undefined) {
+            const err = failure;
+            failure = undefined;
+            return Promise.reject(err);
+          }
+          if (ended) return Promise.resolve({ done: true, value: undefined });
+          return new Promise<IteratorResult<T>>((resolve, reject) => {
+            waiters.push({ resolve, reject });
+          });
+        },
+      };
+    },
+  };
+}
+
+interface ControlRequestEnvelope {
+  readonly type: "control_request";
+  readonly request_id: string;
+  readonly request: {
+    readonly subtype: string;
+    readonly tool_name?: string;
+    readonly input?: Record<string, unknown>;
+    readonly permission_suggestions?: unknown;
+    readonly blocked_path?: string;
+    readonly decision_reason?: unknown;
+    readonly title?: string;
+  };
+}
+
+interface ControlResponseEnvelope {
+  readonly type: "control_response";
+  readonly response: {
+    readonly request_id: string;
+    readonly subtype: "success" | "error";
+    readonly error?: string;
+    readonly response?: unknown;
+  };
+}
+
+/**
+ * Start a `claude` session over stream-json IPC and return a runtime object
+ * shaped like the SDK's query.
+ */
+export function makeClaudeCliQuery(input: ClaudeCliQueryInput): ClaudeCliQueryRuntime {
+  const { options } = input;
+  const o = options as ClaudeQueryOptions & {
+    readonly pathToClaudeCodeExecutable?: string;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly executableArgs?: ReadonlyArray<string>;
+    readonly canUseTool?: CanUseTool;
+  };
+
+  const binaryPath = o.pathToClaudeCodeExecutable ?? "claude";
+  const flags = buildArgs(options);
+  const executableArgs = [...(o.executableArgs ?? [])];
+
+  const isJs = isJsEntrypoint(binaryPath);
+  const command = isJs ? defaultExecutable() : binaryPath;
+  const commandArgs = isJs
+    ? [...executableArgs, binaryPath, ...flags]
+    : [...executableArgs, ...flags];
+
+  const env = { ...(o.env ?? process.env) };
+  // Match the SDK: tag the entrypoint and never leak NODE_OPTIONS into the
+  // child (it can crash the bundled CLI).
+  if (!env.CLAUDE_CODE_ENTRYPOINT) env.CLAUDE_CODE_ENTRYPOINT = "sdk-ts";
+  delete env.NODE_OPTIONS;
+
+  const child: ChildProcessWithoutNullStreams = spawn(command, commandArgs, {
+    cwd: o.cwd,
+    env,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  const messages = makeAsyncQueue<SDKMessage>();
+  const pendingControl = new Map<
+    string,
+    { resolve: (r: ControlResponseEnvelope["response"]) => void; reject: (e: unknown) => void }
+  >();
+  const cancelControllers = new Map<string, AbortController>();
+  let closed = false;
+  let exited = false;
+  let killTimer: NodeJS.Timeout | undefined;
+
+  const writeLine = (obj: unknown): void => {
+    if (closed || exited || !child.stdin.writable) return;
+    try {
+      child.stdin.write(`${JSON.stringify(obj)}\n`);
+    } catch {
+      /* stdin closed underneath us — surfaced via the exit handler */
+    }
+  };
+
+  // ── stdout NDJSON framing ────────────────────────────────────────────
+  let stdoutBuffer = "";
+  const handleParsed = (parsed: unknown): void => {
+    if (!parsed || typeof parsed !== "object") return;
+    const record = parsed as { type?: unknown };
+
+    if (record.type === "control_response") {
+      const env_ = parsed as ControlResponseEnvelope;
+      const pending = pendingControl.get(env_.response.request_id);
+      if (pending) {
+        pendingControl.delete(env_.response.request_id);
+        if (env_.response.subtype === "success") pending.resolve(env_.response);
+        else pending.reject(new Error(env_.response.error ?? "control request failed"));
+      }
+      return;
+    }
+
+    if (record.type === "control_request") {
+      void handleInboundControlRequest(parsed as ControlRequestEnvelope);
+      return;
+    }
+
+    if (record.type === "control_cancel_request") {
+      const reqId = (parsed as { request_id?: string }).request_id;
+      if (reqId) {
+        cancelControllers.get(reqId)?.abort();
+        cancelControllers.delete(reqId);
+      }
+      return;
+    }
+
+    if (record.type === "keep_alive" || record.type === "transcript_mirror") {
+      return;
+    }
+
+    messages.push(parsed as SDKMessage);
+  };
+
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => {
+    stdoutBuffer += chunk;
+    let newlineIndex = stdoutBuffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const line = stdoutBuffer.slice(0, newlineIndex).trim();
+      stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+      if (line.length > 0) {
+        try {
+          handleParsed(JSON.parse(line));
+        } catch {
+          /* tolerate a malformed line rather than tearing down the stream */
+        }
+      }
+      newlineIndex = stdoutBuffer.indexOf("\n");
+    }
+  });
+
+  let stderrTail = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk: string) => {
+    stderrTail = `${stderrTail}${chunk}`.slice(-4_000);
+  });
+
+  // ── inbound can_use_tool → canUseTool callback ───────────────────────
+  const handleInboundControlRequest = async (req: ControlRequestEnvelope): Promise<void> => {
+    if (req.request.subtype !== "can_use_tool") {
+      // Unknown inbound control request: acknowledge with an error so the CLI
+      // does not hang waiting for a response.
+      writeLine({
+        type: "control_response",
+        response: {
+          subtype: "error",
+          request_id: req.request_id,
+          error: `Unsupported control request subtype: ${req.request.subtype}`,
+        },
+      });
+      return;
+    }
+
+    const callback = o.canUseTool;
+    if (typeof callback !== "function") {
+      writeLine({
+        type: "control_response",
+        response: {
+          subtype: "error",
+          request_id: req.request_id,
+          error: "canUseTool callback is not provided.",
+        },
+      });
+      return;
+    }
+
+    const controller = new AbortController();
+    cancelControllers.set(req.request_id, controller);
+    try {
+      const result: PermissionResult = await callback(
+        req.request.tool_name ?? "",
+        req.request.input ?? {},
+        {
+          signal: controller.signal,
+          suggestions: req.request.permission_suggestions,
+          blockedPath: req.request.blocked_path,
+          decisionReason: req.request.decision_reason,
+          title: req.request.title,
+        } as unknown as Parameters<CanUseTool>[2],
+      );
+      writeLine({
+        type: "control_response",
+        response: { subtype: "success", request_id: req.request_id, response: result },
+      });
+    } catch (error) {
+      writeLine({
+        type: "control_response",
+        response: {
+          subtype: "error",
+          request_id: req.request_id,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      });
+    } finally {
+      cancelControllers.delete(req.request_id);
+    }
+  };
+
+  // ── outbound control request (interrupt / set_* / etc.) ───────────────
+  const sendControlRequest = (request: Record<string, unknown>): Promise<unknown> => {
+    if (closed || exited) {
+      return Promise.reject(new Error("Claude CLI session is closed."));
+    }
+    const requestId = newRequestId();
+    return new Promise((resolve, reject) => {
+      pendingControl.set(requestId, {
+        resolve: (r) => resolve(r.response),
+        reject,
+      });
+      try {
+        writeLine({ request_id: requestId, type: "control_request", request });
+      } catch (error) {
+        pendingControl.delete(requestId);
+        reject(error);
+      }
+    });
+  };
+
+  // ── initialize handshake ─────────────────────────────────────────────
+  // Sent synchronously (before the async prompt pump's first write) so the
+  // CLI is configured before any user message is processed, matching the
+  // SDK which always runs `this.initialization = this.initialize()`.
+  const initialization = sendControlRequest(
+    buildInitializePayload(options),
+  ) as Promise<InitializeResult>;
+  // Prevent an unhandled rejection when no one awaits the handshake (the
+  // conversational path ignores it; only the probe consumes the result).
+  initialization.catch(() => {});
+
+  // ── prompt pump: user messages → stdin NDJSON ─────────────────────────
+  void (async () => {
+    try {
+      for await (const message of input.prompt) {
+        if (closed || exited) break;
+        writeLine(message);
+      }
+    } catch {
+      /* prompt iterable ended via interruption — normal shutdown path */
+    } finally {
+      if (!closed && !exited && child.stdin.writable) {
+        try {
+          child.stdin.end();
+        } catch {
+          /* already ended */
+        }
+      }
+    }
+  })();
+
+  // ── lifecycle ─────────────────────────────────────────────────────────
+  child.on("error", (error: Error) => {
+    exited = true;
+    for (const pending of pendingControl.values()) pending.reject(error);
+    pendingControl.clear();
+    messages.fail(error);
+  });
+
+  child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+    exited = true;
+    if (killTimer) clearTimeout(killTimer);
+    for (const pending of pendingControl.values()) {
+      pending.reject(new Error("Claude CLI session closed."));
+    }
+    pendingControl.clear();
+    if (closed || code === 0 || code === null) {
+      messages.end();
+    } else {
+      const detail = stderrTail.trim();
+      messages.fail(
+        new Error(
+          `Claude CLI exited with code ${code}${signal ? ` (signal ${signal})` : ""}${
+            detail ? `: ${detail}` : ""
+          }`,
+        ),
+      );
+    }
+  });
+
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    try {
+      if (child.stdin.writable) child.stdin.end();
+    } catch {
+      /* already ended */
+    }
+    killTimer = setTimeout(() => {
+      if (exited) return;
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (!exited) child.kill("SIGKILL");
+      }, SIGKILL_ESCALATION_MS).unref?.();
+    }, GRACEFUL_SHUTDOWN_MS);
+    killTimer.unref?.();
+  };
+
+  return {
+    [Symbol.asyncIterator]: () => messages.iterator(),
+    interrupt: async () => {
+      await sendControlRequest({ subtype: "interrupt" });
+    },
+    setModel: async (model?: string) => {
+      await sendControlRequest({ subtype: "set_model", model });
+    },
+    setPermissionMode: async (mode: string) => {
+      await sendControlRequest({ subtype: "set_permission_mode", mode });
+    },
+    setMaxThinkingTokens: async (maxThinkingTokens: number | null) => {
+      await sendControlRequest({
+        subtype: "set_max_thinking_tokens",
+        max_thinking_tokens: maxThinkingTokens,
+      });
+    },
+    initialize: () => initialization,
+    close,
+  };
+}
diff --git a/apps/server/src/provider/Layers/ClaudeProvider.ts b/apps/server/src/provider/Layers/ClaudeProvider.ts
index d00be86d3e4..f99f6995378 100644
--- a/apps/server/src/provider/Layers/ClaudeProvider.ts
+++ b/apps/server/src/provider/Layers/ClaudeProvider.ts
@@ -1,101 +1,203 @@
-import type {
-  ClaudeSettings,
-  ModelCapabilities,
-  ServerProvider,
-  ServerProviderModel,
-  ServerProviderAuth,
-  ServerProviderSlashCommand,
-  ServerProviderState,
+import {
+  type ClaudeSettings,
+  type ModelCapabilities,
+  type ModelSelection,
+  ProviderDriverKind,
+  type ServerProviderModel,
+  type ServerProviderSlashCommand,
 } from "@t3tools/contracts";
-import { Cache, Duration, Effect, Equal, Layer, Option, Result, Schema, Stream } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { decodeJsonResult } from "@t3tools/shared/schemaJson";
 import {
-  query as claudeQuery,
-  type SlashCommand as ClaudeSlashCommand,
+  createModelCapabilities,
+  getModelSelectionStringOptionValue,
+  getProviderOptionCurrentValue,
+  getProviderOptionDescriptors,
+} from "@t3tools/shared/model";
+import { compareSemverVersions } from "@t3tools/shared/semver";
+import type {
+  SlashCommand as ClaudeSlashCommand,
+  SDKUserMessage,
 } from "@anthropic-ai/claude-agent-sdk";
 
+import { makeClaudeCliQuery } from "./ClaudeCliTransport.ts";
+
 import {
+  buildBooleanOptionDescriptor,
+  buildSelectOptionDescriptor,
   buildServerProvider,
   DEFAULT_TIMEOUT_MS,
   detailFromResult,
-  extractAuthBoolean,
   isCommandMissingCause,
   parseGenericCliVersion,
   providerModelsFromSettings,
   spawnAndCollect,
-  type CommandResult,
-} from "../providerSnapshot";
-import { makeManagedServerProvider } from "../makeManagedServerProvider";
-import { ClaudeProvider } from "../Services/ClaudeProvider";
-import { ServerSettingsService } from "../../serverSettings";
-import { ServerSettingsError } from "@t3tools/contracts";
-
-const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-};
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
-const PROVIDER = "claudeAgent" as const;
+const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+
+const PROVIDER = ProviderDriverKind.make("claudeAgent");
+const CLAUDE_PRESENTATION = {
+  displayName: "Claude",
+  showInteractionModeToggle: true,
+} as const;
+const MINIMUM_CLAUDE_OPUS_4_7_VERSION = "2.1.111";
 const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = [
+  {
+    slug: "claude-opus-4-7",
+    name: "Claude Opus 4.7",
+    isCustom: false,
+    capabilities: createModelCapabilities({
+      optionDescriptors: [
+        buildSelectOptionDescriptor({
+          id: "effort",
+          label: "Reasoning",
+          options: [
+            { value: "low", label: "Low" },
+            { value: "medium", label: "Medium" },
+            { value: "high", label: "High" },
+            { value: "xhigh", label: "Extra High", isDefault: true },
+            { value: "max", label: "Max" },
+            { value: "ultrathink", label: "Ultrathink" },
+          ],
+          promptInjectedValues: ["ultrathink"],
+        }),
+        buildSelectOptionDescriptor({
+          id: "contextWindow",
+          label: "Context Window",
+          options: [
+            { value: "200k", label: "200k", isDefault: true },
+            { value: "1m", label: "1M" },
+          ],
+        }),
+      ],
+    }),
+  },
   {
     slug: "claude-opus-4-6",
     name: "Claude Opus 4.6",
     isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "max", label: "Max" },
-        { value: "ultrathink", label: "Ultrathink" },
+    capabilities: createModelCapabilities({
+      optionDescriptors: [
+        buildSelectOptionDescriptor({
+          id: "effort",
+          label: "Reasoning",
+          options: [
+            { value: "low", label: "Low" },
+            { value: "medium", label: "Medium" },
+            { value: "high", label: "High", isDefault: true },
+            { value: "max", label: "Max" },
+            { value: "ultrathink", label: "Ultrathink" },
+          ],
+          promptInjectedValues: ["ultrathink"],
+        }),
+        buildBooleanOptionDescriptor({
+          id: "fastMode",
+          label: "Fast Mode",
+        }),
+        buildSelectOptionDescriptor({
+          id: "contextWindow",
+          label: "Context Window",
+          options: [
+            { value: "200k", label: "200k", isDefault: true },
+            { value: "1m", label: "1M" },
+          ],
+        }),
       ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [
-        { value: "200k", label: "200k", isDefault: true },
-        { value: "1m", label: "1M" },
+    }),
+  },
+  {
+    slug: "claude-opus-4-5",
+    name: "Claude Opus 4.5",
+    isCustom: false,
+    capabilities: createModelCapabilities({
+      optionDescriptors: [
+        buildSelectOptionDescriptor({
+          id: "effort",
+          label: "Reasoning",
+          options: [
+            { value: "low", label: "Low" },
+            { value: "medium", label: "Medium" },
+            { value: "high", label: "High", isDefault: true },
+            { value: "max", label: "Max" },
+          ],
+        }),
+        buildBooleanOptionDescriptor({
+          id: "fastMode",
+          label: "Fast Mode",
+        }),
       ],
-      promptInjectedEffortLevels: ["ultrathink"],
-    } satisfies ModelCapabilities,
+    }),
   },
   {
     slug: "claude-sonnet-4-6",
     name: "Claude Sonnet 4.6",
     isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "ultrathink", label: "Ultrathink" },
-      ],
-      supportsFastMode: false,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [
-        { value: "200k", label: "200k", isDefault: true },
-        { value: "1m", label: "1M" },
+    capabilities: createModelCapabilities({
+      optionDescriptors: [
+        buildSelectOptionDescriptor({
+          id: "effort",
+          label: "Reasoning",
+          options: [
+            { value: "low", label: "Low" },
+            { value: "medium", label: "Medium" },
+            { value: "high", label: "High", isDefault: true },
+            { value: "ultrathink", label: "Ultrathink" },
+          ],
+          promptInjectedValues: ["ultrathink"],
+        }),
+        buildSelectOptionDescriptor({
+          id: "contextWindow",
+          label: "Context Window",
+          options: [
+            { value: "200k", label: "200k", isDefault: true },
+            { value: "1m", label: "1M" },
+          ],
+        }),
       ],
-      promptInjectedEffortLevels: ["ultrathink"],
-    } satisfies ModelCapabilities,
+    }),
   },
   {
     slug: "claude-haiku-4-5",
     name: "Claude Haiku 4.5",
     isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [],
-      supportsFastMode: false,
-      supportsThinkingToggle: true,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    } satisfies ModelCapabilities,
+    capabilities: createModelCapabilities({
+      optionDescriptors: [
+        buildBooleanOptionDescriptor({
+          id: "thinking",
+          label: "Thinking",
+        }),
+      ],
+    }),
   },
 ];
 
+function supportsClaudeOpus47(version: string | null | undefined): boolean {
+  return version ? compareSemverVersions(version, MINIMUM_CLAUDE_OPUS_4_7_VERSION) >= 0 : false;
+}
+
+function getBuiltInClaudeModelsForVersion(
+  version: string | null | undefined,
+): ReadonlyArray<ServerProviderModel> {
+  if (supportsClaudeOpus47(version)) {
+    return BUILT_IN_MODELS;
+  }
+  return BUILT_IN_MODELS.filter((model) => model.slug !== "claude-opus-4-7");
+}
+
+function formatClaudeOpus47UpgradeMessage(version: string | null): string {
+  const versionLabel = version ? `v${version}` : "the installed version";
+  return `Claude Code ${versionLabel} is too old for Claude Opus 4.7. Upgrade to v${MINIMUM_CLAUDE_OPUS_4_7_VERSION} or newer to access it.`;
+}
+
 export function getClaudeModelCapabilities(model: string | null | undefined): ModelCapabilities {
   const slug = model?.trim();
   return (
@@ -104,180 +206,46 @@ export function getClaudeModelCapabilities(model: string | null | undefined): Mo
   );
 }
 
-export function parseClaudeAuthStatusFromOutput(result: CommandResult): {
-  readonly status: Exclude<ServerProviderState, "disabled">;
-  readonly auth: Pick<ServerProviderAuth, "status">;
-  readonly message?: string;
-} {
-  const lowerOutput = `${result.stdout}\n${result.stderr}`.toLowerCase();
-
-  if (
-    lowerOutput.includes("unknown command") ||
-    lowerOutput.includes("unrecognized command") ||
-    lowerOutput.includes("unexpected argument")
-  ) {
-    return {
-      status: "warning",
-      auth: { status: "unknown" },
-      message:
-        "Claude Agent authentication status command is unavailable in this version of Claude.",
-    };
-  }
-
-  if (
-    lowerOutput.includes("not logged in") ||
-    lowerOutput.includes("login required") ||
-    lowerOutput.includes("authentication required") ||
-    lowerOutput.includes("run `claude login`") ||
-    lowerOutput.includes("run claude login")
-  ) {
-    return {
-      status: "error",
-      auth: { status: "unauthenticated" },
-      message: "Claude is not authenticated. Run `claude auth login` and try again.",
-    };
-  }
-
-  const parsedAuth = (() => {
-    const trimmed = result.stdout.trim();
-    if (!trimmed || (!trimmed.startsWith("{") && !trimmed.startsWith("["))) {
-      return { attemptedJsonParse: false as const, auth: undefined as boolean | undefined };
-    }
-    try {
-      return {
-        attemptedJsonParse: true as const,
-        auth: extractAuthBoolean(JSON.parse(trimmed)),
-      };
-    } catch {
-      return { attemptedJsonParse: false as const, auth: undefined as boolean | undefined };
-    }
-  })();
-
-  if (parsedAuth.auth === true) {
-    return { status: "ready", auth: { status: "authenticated" } };
-  }
-  if (parsedAuth.auth === false) {
-    return {
-      status: "error",
-      auth: { status: "unauthenticated" },
-      message: "Claude is not authenticated. Run `claude auth login` and try again.",
-    };
-  }
-  if (parsedAuth.attemptedJsonParse) {
-    return {
-      status: "warning",
-      auth: { status: "unknown" },
-      message:
-        "Could not verify Claude authentication status from JSON output (missing auth marker).",
-    };
-  }
-  if (result.code === 0) {
-    return { status: "ready", auth: { status: "authenticated" } };
-  }
-
-  const detail = detailFromResult(result);
-  return {
-    status: "warning",
-    auth: { status: "unknown" },
-    message: detail
-      ? `Could not verify Claude authentication status. ${detail}`
-      : "Could not verify Claude authentication status.",
-  };
+export function resolveClaudeEffort(
+  caps: ModelCapabilities,
+  raw: string | null | undefined,
+): string | undefined {
+  const descriptors = getProviderOptionDescriptors({
+    caps,
+    ...(raw ? { selections: [{ id: "effort", value: raw }] } : {}),
+  });
+  const effortDescriptor = descriptors.find((descriptor) => descriptor.id === "effort");
+  const value = getProviderOptionCurrentValue(effortDescriptor);
+  return typeof value === "string" ? value : undefined;
 }
 
-// ── Subscription type detection ─────────────────────────────────────
-//
-// The SDK probe returns typed `AccountInfo.subscriptionType` directly.
-// This walker is a best-effort fallback for the `claude auth status`
-// JSON output whose shape is not guaranteed.
-
-/** Keys that directly hold a subscription/plan identifier. */
-const SUBSCRIPTION_TYPE_KEYS = [
-  "subscriptionType",
-  "subscription_type",
-  "plan",
-  "tier",
-  "planType",
-  "plan_type",
-] as const;
-
-/** Keys whose value may be a nested object containing subscription info. */
-const SUBSCRIPTION_CONTAINER_KEYS = ["account", "subscription", "user", "billing"] as const;
-const AUTH_METHOD_KEYS = ["authMethod", "auth_method"] as const;
-const AUTH_METHOD_CONTAINER_KEYS = ["auth", "account", "session"] as const;
-
-/** Lift an unknown value into `Option<string>` if it is a non-empty string. */
-const asNonEmptyString = (v: unknown): Option.Option<string> =>
-  typeof v === "string" && v.length > 0 ? Option.some(v) : Option.none();
-
-/** Lift an unknown value into `Option<Record>` if it is a plain object. */
-const asRecord = (v: unknown): Option.Option<Record<string, unknown>> =>
-  typeof v === "object" && v !== null && !globalThis.Array.isArray(v)
-    ? Option.some(v as Record<string, unknown>)
-    : Option.none();
-
 /**
- * Walk an unknown parsed JSON value looking for a subscription/plan
- * identifier, returning the first match as an `Option`.
+ * Normalize a resolved Claude effort value into one suitable for the Claude
+ * CLI's `--effort` flag.
+ *
+ * Mirrors the mapping used when invoking the Claude Agent SDK
+ * ({@link getEffectiveClaudeAgentEffort} in ClaudeAdapter): the Opus 4.7
+ * capability `"xhigh"` is rewritten to the accepted CLI value `"max"`, and
+ * `"ultrathink"` is filtered out because it is a prompt-prefix mode rather
+ * than a CLI-effort value. Returns `undefined` when no flag should be passed.
  */
-function findSubscriptionType(value: unknown): Option.Option<string> {
-  if (globalThis.Array.isArray(value)) {
-    return Option.firstSomeOf(value.map(findSubscriptionType));
+export function normalizeClaudeCliEffort(effort: string | null | undefined): string | undefined {
+  if (!effort || effort === "ultrathink") {
+    return undefined;
   }
-
-  return asRecord(value).pipe(
-    Option.flatMap((record) => {
-      const direct = Option.firstSomeOf(
-        SUBSCRIPTION_TYPE_KEYS.map((key) => asNonEmptyString(record[key])),
-      );
-      if (Option.isSome(direct)) return direct;
-
-      return Option.firstSomeOf(
-        SUBSCRIPTION_CONTAINER_KEYS.map((key) =>
-          asRecord(record[key]).pipe(Option.flatMap(findSubscriptionType)),
-        ),
-      );
-    }),
-  );
-}
-
-function findAuthMethod(value: unknown): Option.Option<string> {
-  if (globalThis.Array.isArray(value)) {
-    return Option.firstSomeOf(value.map(findAuthMethod));
+  if (effort === "xhigh") {
+    return "max";
   }
-
-  return asRecord(value).pipe(
-    Option.flatMap((record) => {
-      const direct = Option.firstSomeOf(
-        AUTH_METHOD_KEYS.map((key) => asNonEmptyString(record[key])),
-      );
-      if (Option.isSome(direct)) return direct;
-
-      return Option.firstSomeOf(
-        AUTH_METHOD_CONTAINER_KEYS.map((key) =>
-          asRecord(record[key]).pipe(Option.flatMap(findAuthMethod)),
-        ),
-      );
-    }),
-  );
-}
-
-/**
- * Try to extract a subscription type from the `claude auth status` JSON
- * output. This is a zero-cost operation on data we already have.
- */
-const decodeUnknownJson = decodeJsonResult(Schema.Unknown);
-
-function extractSubscriptionTypeFromOutput(result: CommandResult): string | undefined {
-  const parsed = decodeUnknownJson(result.stdout.trim());
-  if (Result.isFailure(parsed)) return undefined;
-  return Option.getOrUndefined(findSubscriptionType(parsed.success));
+  return effort;
 }
 
-function extractClaudeAuthMethodFromOutput(result: CommandResult): string | undefined {
-  const parsed = decodeUnknownJson(result.stdout.trim());
-  if (Result.isFailure(parsed)) return undefined;
-  return Option.getOrUndefined(findAuthMethod(parsed.success));
+export function resolveClaudeApiModelId(modelSelection: ModelSelection): string {
+  switch (getModelSelectionStringOptionValue(modelSelection, "contextWindow")) {
+    case "1m":
+      return `${modelSelection.model}[1m]`;
+    default:
+      return modelSelection.model;
+  }
 }
 
 function toTitleCaseWords(value: string): string {
@@ -293,11 +261,27 @@ function claudeSubscriptionLabel(subscriptionType: string | undefined): string |
   if (!normalized) return undefined;
 
   switch (normalized) {
+    case "claudemaxsubscription":
+      return "Max";
+    case "claudemax5xsubscription":
+      return "Max 5x";
+    case "claudemax20xsubscription":
+      return "Max 20x";
+    case "claudeenterprisesubscription":
+      return "Enterprise";
+    case "claudeteamsubscription":
+      return "Team";
+    case "claudeprosubscription":
+      return "Pro";
+    case "claudefreesubscription":
+      return "Free";
     case "max":
     case "maxplan":
+      return "Max";
     case "max5":
+      return "Max 5x";
     case "max20":
-      return "Max";
+      return "Max 20x";
     case "enterprise":
       return "Enterprise";
     case "team":
@@ -314,10 +298,33 @@ function claudeSubscriptionLabel(subscriptionType: string | undefined): string |
 function normalizeClaudeAuthMethod(authMethod: string | undefined): string | undefined {
   const normalized = authMethod?.toLowerCase().replace(/[\s_-]+/g, "");
   if (!normalized) return undefined;
-  if (normalized === "apikey") return "apiKey";
+  if (
+    normalized === "apikey" ||
+    normalized === "anthropicapikey" ||
+    normalized === "anthropicauthtoken"
+  ) {
+    return "apiKey";
+  }
   return undefined;
 }
 
+function formatClaudeSubscriptionAuthLabel(subscriptionType: string): string {
+  const subscriptionLabel =
+    claudeSubscriptionLabel(subscriptionType) ?? toTitleCaseWords(subscriptionType);
+  const normalized = subscriptionLabel.toLowerCase().replace(/[\s_-]+/g, "");
+
+  if (normalized.startsWith("claude") && normalized.endsWith("subscription")) {
+    return subscriptionLabel;
+  }
+  if (normalized.startsWith("claude")) {
+    return `${subscriptionLabel} Subscription`;
+  }
+  if (normalized.endsWith("subscription")) {
+    return `Claude ${subscriptionLabel}`;
+  }
+  return `Claude ${subscriptionLabel} Subscription`;
+}
+
 function claudeAuthMetadata(input: {
   readonly subscriptionType: string | undefined;
   readonly authMethod: string | undefined;
@@ -330,10 +337,9 @@ function claudeAuthMetadata(input: {
   }
 
   if (input.subscriptionType) {
-    const subscriptionLabel = claudeSubscriptionLabel(input.subscriptionType);
     return {
       type: input.subscriptionType,
-      label: `Claude ${subscriptionLabel ?? toTitleCaseWords(input.subscriptionType)} Subscription`,
+      label: formatClaudeSubscriptionAuthLabel(input.subscriptionType),
     };
   }
 
@@ -349,6 +355,13 @@ function nonEmptyProbeString(value: string): string | undefined {
   return candidate ? candidate : undefined;
 }
 
+type ClaudeCapabilitiesProbe = {
+  readonly email: string | undefined;
+  readonly subscriptionType: string | undefined;
+  readonly tokenSource: string | undefined;
+  readonly slashCommands: ReadonlyArray<ServerProviderSlashCommand>;
+};
+
 function parseClaudeInitializationCommands(
   commands: ReadonlyArray<ClaudeSlashCommand> | undefined,
 ): ReadonlyArray<ServerProviderSlashCommand> {
@@ -412,37 +425,66 @@ function dedupeSlashCommands(
   return [...commandsByName.values()];
 }
 
+function waitForAbortSignal(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    signal.addEventListener("abort", () => resolve(), { once: true });
+  });
+}
+
 /**
  * Probe account information by spawning a lightweight Claude Agent SDK
  * session and reading the initialization result.
  *
- * The prompt is never sent to the Anthropic API — we abort immediately
- * after the local initialization phase completes. This gives us the
- * user's subscription type without incurring any token cost.
+ * We pass a never-yielding AsyncIterable as the prompt so that no user
+ * message is ever written to the subprocess stdin. This means the Claude
+ * Code subprocess completes its local initialization IPC (returning
+ * account info and slash commands) but never starts an API request to
+ * Anthropic. We read the init data and then abort the subprocess.
  *
  * This is used as a fallback when `claude auth status` does not include
  * subscription type information.
  */
-const probeClaudeCapabilities = (binaryPath: string) => {
+const probeClaudeCapabilities = (
+  claudeSettings: ClaudeSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
   const abort = new AbortController();
-  return Effect.tryPromise(async () => {
-    const q = claudeQuery({
-      prompt: ".",
-      options: {
-        persistSession: false,
-        pathToClaudeCodeExecutable: binaryPath,
-        abortController: abort,
-        maxTurns: 0,
-        settingSources: ["user", "project", "local"],
-        allowedTools: [],
-        stderr: () => {},
-      },
+  return Effect.gen(function* () {
+    const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+    return yield* Effect.tryPromise(async () => {
+      const q = makeClaudeCliQuery({
+        // Never yield — we only need initialization data, not a conversation.
+        // This prevents any prompt from reaching the Anthropic API.
+        // oxlint-disable-next-line require-yield
+        prompt: (async function* (): AsyncGenerator<SDKUserMessage> {
+          await waitForAbortSignal(abort.signal);
+        })(),
+        options: {
+          persistSession: false,
+          pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+          settingSources: ["user", "project", "local"],
+          allowedTools: [],
+          env: claudeEnvironment,
+        } as unknown as Parameters<typeof makeClaudeCliQuery>[0]["options"],
+      });
+      try {
+        const init = await q.initialize();
+        const account = init.account;
+        return {
+          email: account?.email,
+          subscriptionType: account?.subscriptionType,
+          tokenSource: account?.tokenSource,
+          slashCommands: parseClaudeInitializationCommands(
+            init.commands as ReadonlyArray<ClaudeSlashCommand> | undefined,
+          ),
+        } satisfies ClaudeCapabilitiesProbe;
+      } finally {
+        q.close();
+      }
     });
-    const init = await q.initializationResult();
-    return {
-      subscriptionType: init.account?.subscriptionType,
-      slashCommands: parseClaudeInitializationCommands(init.commands),
-    };
   }).pipe(
     Effect.ensuring(
       Effect.sync(() => {
@@ -458,33 +500,32 @@ const probeClaudeCapabilities = (binaryPath: string) => {
   );
 };
 
-const runClaudeCommand = Effect.fn("runClaudeCommand")(function* (args: ReadonlyArray<string>) {
-  const claudeSettings = yield* Effect.service(ServerSettingsService).pipe(
-    Effect.flatMap((service) => service.getSettings),
-    Effect.map((settings) => settings.providers.claudeAgent),
-  );
+const runClaudeCommand = Effect.fn("runClaudeCommand")(function* (
+  claudeSettings: ClaudeSettings,
+  args: ReadonlyArray<string>,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
   const command = ChildProcess.make(claudeSettings.binaryPath, [...args], {
+    env: claudeEnvironment,
     shell: process.platform === "win32",
   });
   return yield* spawnAndCollect(claudeSettings.binaryPath, command);
 });
 
 export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(function* (
-  resolveSubscriptionType?: (binaryPath: string) => Effect.Effect<string | undefined>,
-  resolveSlashCommands?: (
-    binaryPath: string,
-  ) => Effect.Effect<ReadonlyArray<ServerProviderSlashCommand> | undefined>,
+  claudeSettings: ClaudeSettings,
+  resolveCapabilities?: (
+    claudeSettings: ClaudeSettings,
+  ) => Effect.Effect<ClaudeCapabilitiesProbe | undefined>,
+  environment: NodeJS.ProcessEnv = process.env,
 ): Effect.fn.Return<
-  ServerProvider,
-  ServerSettingsError,
-  ChildProcessSpawner.ChildProcessSpawner | ServerSettingsService
+  ServerProviderDraft,
+  never,
+  ChildProcessSpawner.ChildProcessSpawner | Path.Path
 > {
-  const claudeSettings = yield* Effect.service(ServerSettingsService).pipe(
-    Effect.flatMap((service) => service.getSettings),
-    Effect.map((settings) => settings.providers.claudeAgent),
-  );
-  const checkedAt = new Date().toISOString();
-  const models = providerModelsFromSettings(
+  const checkedAt = DateTime.formatIso(yield* DateTime.now);
+  const allModels = providerModelsFromSettings(
     BUILT_IN_MODELS,
     PROVIDER,
     claudeSettings.customModels,
@@ -493,10 +534,10 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
 
   if (!claudeSettings.enabled) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CLAUDE_PRESENTATION,
       enabled: false,
       checkedAt,
-      models,
+      models: allModels,
       probe: {
         installed: false,
         version: null,
@@ -507,7 +548,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
     });
   }
 
-  const versionProbe = yield* runClaudeCommand(["--version"]).pipe(
+  const versionProbe = yield* runClaudeCommand(claudeSettings, ["--version"], environment).pipe(
     Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
     Effect.result,
   );
@@ -515,10 +556,10 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
   if (Result.isFailure(versionProbe)) {
     const error = versionProbe.failure;
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CLAUDE_PRESENTATION,
       enabled: claudeSettings.enabled,
       checkedAt,
-      models,
+      models: allModels,
       probe: {
         installed: !isCommandMissingCause(error),
         version: null,
@@ -533,10 +574,10 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
 
   if (Option.isNone(versionProbe.success)) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CLAUDE_PRESENTATION,
       enabled: claudeSettings.enabled,
       checkedAt,
-      models,
+      models: allModels,
       probe: {
         installed: true,
         version: null,
@@ -553,10 +594,10 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
   if (version.code !== 0) {
     const detail = detailFromResult(version);
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CLAUDE_PRESENTATION,
       enabled: claudeSettings.enabled,
       checkedAt,
-      models,
+      models: allModels,
       probe: {
         installed: true,
         version: parsedVersion,
@@ -569,65 +610,25 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
     });
   }
 
-  const slashCommands =
-    (resolveSlashCommands
-      ? yield* resolveSlashCommands(claudeSettings.binaryPath).pipe(
-          Effect.orElseSucceed(() => undefined),
-        )
-      : undefined) ?? [];
-  const dedupedSlashCommands = dedupeSlashCommands(slashCommands);
-
-  // ── Auth check + subscription detection ────────────────────────────
-
-  const authProbe = yield* runClaudeCommand(["auth", "status"]).pipe(
-    Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
-    Effect.result,
+  const models = providerModelsFromSettings(
+    getBuiltInClaudeModelsForVersion(parsedVersion),
+    PROVIDER,
+    claudeSettings.customModels,
+    DEFAULT_CLAUDE_MODEL_CAPABILITIES,
   );
+  const opus47UpgradeMessage = supportsClaudeOpus47(parsedVersion)
+    ? undefined
+    : formatClaudeOpus47UpgradeMessage(parsedVersion);
+
+  const capabilities = resolveCapabilities
+    ? yield* resolveCapabilities(claudeSettings).pipe(Effect.orElseSucceed(() => undefined))
+    : undefined;
+  const slashCommands = capabilities?.slashCommands ?? [];
+  const dedupedSlashCommands = dedupeSlashCommands(slashCommands);
 
-  // Determine subscription type from multiple sources (cheapest first):
-  // 1. `claude auth status` JSON output (may or may not contain it)
-  // 2. Cached SDK probe (spawns a Claude process on miss, reads
-  //    `initializationResult()` for account metadata, then aborts
-  //    immediately — no API tokens are consumed)
-
-  let subscriptionType: string | undefined;
-  let authMethod: string | undefined;
-
-  if (Result.isSuccess(authProbe) && Option.isSome(authProbe.success)) {
-    subscriptionType = extractSubscriptionTypeFromOutput(authProbe.success.value);
-    authMethod = extractClaudeAuthMethodFromOutput(authProbe.success.value);
-  }
-
-  if (!subscriptionType && resolveSubscriptionType) {
-    subscriptionType = yield* resolveSubscriptionType(claudeSettings.binaryPath);
-  }
-
-  // ── Handle auth results (same logic as before, adjusted models) ──
-
-  if (Result.isFailure(authProbe)) {
-    const error = authProbe.failure;
-    return buildServerProvider({
-      provider: PROVIDER,
-      enabled: claudeSettings.enabled,
-      checkedAt,
-      models,
-      slashCommands: dedupedSlashCommands,
-      probe: {
-        installed: true,
-        version: parsedVersion,
-        status: "warning",
-        auth: { status: "unknown" },
-        message:
-          error instanceof Error
-            ? `Could not verify Claude authentication status: ${error.message}.`
-            : "Could not verify Claude authentication status.",
-      },
-    });
-  }
-
-  if (Option.isNone(authProbe.success)) {
+  if (!capabilities) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CLAUDE_PRESENTATION,
       enabled: claudeSettings.enabled,
       checkedAt,
       models,
@@ -637,15 +638,17 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
         version: parsedVersion,
         status: "warning",
         auth: { status: "unknown" },
-        message: "Could not verify Claude authentication status. Timed out while running command.",
+        message: "Could not verify Claude authentication status from initialization result.",
       },
     });
   }
 
-  const parsed = parseClaudeAuthStatusFromOutput(authProbe.success.value);
-  const authMetadata = claudeAuthMetadata({ subscriptionType, authMethod });
+  const authMetadata = claudeAuthMetadata({
+    subscriptionType: capabilities.subscriptionType,
+    authMethod: capabilities.tokenSource,
+  });
   return buildServerProvider({
-    provider: PROVIDER,
+    presentation: CLAUDE_PRESENTATION,
     enabled: claudeSettings.enabled,
     checkedAt,
     models,
@@ -653,52 +656,60 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
     probe: {
       installed: true,
       version: parsedVersion,
-      status: parsed.status,
+      status: "ready",
       auth: {
-        ...parsed.auth,
+        status: "authenticated",
+        ...(capabilities.email ? { email: capabilities.email } : {}),
         ...(authMetadata ? authMetadata : {}),
       },
-      ...(parsed.message ? { message: parsed.message } : {}),
+      ...(opus47UpgradeMessage ? { message: opus47UpgradeMessage } : {}),
     },
   });
 });
 
-export const ClaudeProviderLive = Layer.effect(
-  ClaudeProvider,
-  Effect.gen(function* () {
-    const serverSettings = yield* ServerSettingsService;
-    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
 
-    const subscriptionProbeCache = yield* Cache.make({
-      capacity: 1,
-      timeToLive: Duration.minutes(5),
-      lookup: (binaryPath: string) => probeClaudeCapabilities(binaryPath),
-    });
-
-    const checkProvider = checkClaudeProviderStatus(
-      (binaryPath) =>
-        Cache.get(subscriptionProbeCache, binaryPath).pipe(
-          Effect.map((probe) => probe?.subscriptionType),
-        ),
-      (binaryPath) =>
-        Cache.get(subscriptionProbeCache, binaryPath).pipe(
-          Effect.map((probe) => probe?.slashCommands),
-        ),
-    ).pipe(
-      Effect.provideService(ServerSettingsService, serverSettings),
-      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+export const makePendingClaudeProvider = (
+  claudeSettings: ClaudeSettings,
+): Effect.Effect<ServerProviderDraft> =>
+  Effect.gen(function* () {
+    const checkedAt = yield* nowIso;
+    const models = providerModelsFromSettings(
+      BUILT_IN_MODELS,
+      PROVIDER,
+      claudeSettings.customModels,
+      DEFAULT_CLAUDE_MODEL_CAPABILITIES,
     );
 
-    return yield* makeManagedServerProvider<ClaudeSettings>({
-      getSettings: serverSettings.getSettings.pipe(
-        Effect.map((settings) => settings.providers.claudeAgent),
-        Effect.orDie,
-      ),
-      streamSettings: serverSettings.streamChanges.pipe(
-        Stream.map((settings) => settings.providers.claudeAgent),
-      ),
-      haveSettingsChanged: (previous, next) => !Equal.equals(previous, next),
-      checkProvider,
+    if (!claudeSettings.enabled) {
+      return buildServerProvider({
+        presentation: CLAUDE_PRESENTATION,
+        enabled: false,
+        checkedAt,
+        models,
+        probe: {
+          installed: false,
+          version: null,
+          status: "warning",
+          auth: { status: "unknown" },
+          message: "Claude is disabled in T3 Code settings.",
+        },
+      });
+    }
+
+    return buildServerProvider({
+      presentation: CLAUDE_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Claude provider status has not been checked in this session yet.",
+      },
     });
-  }),
-);
+  });
+
+export { probeClaudeCapabilities };
diff --git a/apps/server/src/provider/Layers/CodexAdapter.test.ts b/apps/server/src/provider/Layers/CodexAdapter.test.ts
index c4ee33b7768..c5eaa536c3f 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.test.ts
@@ -1,7 +1,14 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import {
   ApprovalRequestId,
+  CodexSettings,
   EventId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ProviderItemId,
   type ProviderApprovalDecision,
   type ProviderEvent,
@@ -11,146 +18,219 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { afterAll, it, vi } from "@effect/vitest";
+import { it, vi } from "@effect/vitest";
+
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as CodexErrors from "effect-codex-app-server/errors";
 
-import { Effect, Fiber, Layer, Option, Stream } from "effect";
-
-import {
-  CodexAppServerManager,
-  type CodexAppServerStartSessionInput,
-  type CodexAppServerSendTurnInput,
-} from "../../codexAppServerManager.ts";
 import { ServerConfig } from "../../config.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { ProviderAdapterValidationError } from "../Errors.ts";
-import { CodexAdapter } from "../Services/CodexAdapter.ts";
+import type { CodexAdapterShape } from "../Services/CodexAdapter.ts";
 import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
-import { makeCodexAdapterLive } from "./CodexAdapter.ts";
+import {
+  type CodexSessionRuntimeOptions,
+  type CodexSessionRuntimeSendTurnInput,
+  type CodexSessionRuntimeShape,
+  type CodexThreadSnapshot,
+} from "./CodexSessionRuntime.ts";
+import { makeCodexAdapter } from "./CodexAdapter.ts";
+const decodeCodexSettings = Schema.decodeSync(CodexSettings);
+
+// Test-local service tag so the rest of the file can keep using `yield* CodexAdapter`.
+class CodexAdapter extends Context.Service<CodexAdapter, CodexAdapterShape>()(
+  "test/CodexAdapter",
+) {}
 
 const asThreadId = (value: string): ThreadId => ThreadId.make(value);
 const asTurnId = (value: string): TurnId => TurnId.make(value);
 const asEventId = (value: string): EventId => EventId.make(value);
 const asItemId = (value: string): ProviderItemId => ProviderItemId.make(value);
 
-class FakeCodexManager extends CodexAppServerManager {
-  public startSessionImpl = vi.fn(
-    async (input: CodexAppServerStartSessionInput): Promise<ProviderSession> => {
-      const now = new Date().toISOString();
-      return {
-        provider: "codex",
-        status: "ready",
-        runtimeMode: input.runtimeMode,
-        threadId: input.threadId,
-        cwd: input.cwd,
-        createdAt: now,
-        updatedAt: now,
-      };
-    },
+class FakeCodexRuntime implements CodexSessionRuntimeShape {
+  private readonly eventQueue = Effect.runSync(Queue.unbounded<ProviderEvent>());
+  private readonly now = "2026-01-01T00:00:00.000Z";
+
+  public readonly startImpl = vi.fn(() =>
+    Promise.resolve({
+      provider: ProviderDriverKind.make("codex"),
+      status: "ready" as const,
+      runtimeMode: this.options.runtimeMode,
+      threadId: this.options.threadId,
+      cwd: this.options.cwd,
+      ...(this.options.model ? { model: this.options.model } : {}),
+      createdAt: this.now,
+      updatedAt: this.now,
+    } satisfies ProviderSession),
   );
 
-  public sendTurnImpl = vi.fn(
-    async (_input: CodexAppServerSendTurnInput): Promise<ProviderTurnStartResult> => ({
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-1"),
-    }),
+  public readonly sendTurnImpl = vi.fn(
+    (_input: CodexSessionRuntimeSendTurnInput): Promise<ProviderTurnStartResult> =>
+      Promise.resolve({
+        threadId: this.options.threadId,
+        turnId: asTurnId("turn-1"),
+      }),
   );
 
-  public interruptTurnImpl = vi.fn(
-    async (_threadId: ThreadId, _turnId?: TurnId): Promise<void> => undefined,
+  public readonly interruptTurnImpl = vi.fn(
+    (_turnId?: TurnId): Promise<void> => Promise.resolve(undefined),
   );
 
-  public readThreadImpl = vi.fn(async (_threadId: ThreadId) => ({
-    threadId: asThreadId("thread-1"),
-    turns: [],
-  }));
-
-  public rollbackThreadImpl = vi.fn(async (_threadId: ThreadId, _numTurns: number) => ({
-    threadId: asThreadId("thread-1"),
-    turns: [],
-  }));
-
-  public respondToRequestImpl = vi.fn(
-    async (
-      _threadId: ThreadId,
-      _requestId: ApprovalRequestId,
-      _decision: ProviderApprovalDecision,
-    ): Promise<void> => undefined,
+  public readonly readThreadImpl = vi.fn(
+    (): Promise<CodexThreadSnapshot> =>
+      Promise.resolve({
+        threadId: "provider-thread-1",
+        turns: [],
+      }),
   );
 
-  public respondToUserInputImpl = vi.fn(
-    async (
-      _threadId: ThreadId,
-      _requestId: ApprovalRequestId,
-      _answers: ProviderUserInputAnswers,
-    ): Promise<void> => undefined,
+  public readonly rollbackThreadImpl = vi.fn(
+    (_numTurns: number): Promise<CodexThreadSnapshot> =>
+      Promise.resolve({
+        threadId: "provider-thread-1",
+        turns: [],
+      }),
   );
 
-  public stopAllImpl = vi.fn(() => undefined);
+  public readonly respondToRequestImpl = vi.fn(
+    (_requestId: ApprovalRequestId, _decision: ProviderApprovalDecision): Promise<void> =>
+      Promise.resolve(undefined),
+  );
 
-  override startSession(input: CodexAppServerStartSessionInput): Promise<ProviderSession> {
-    return this.startSessionImpl(input);
-  }
+  public readonly respondToUserInputImpl = vi.fn(
+    (_requestId: ApprovalRequestId, _answers: ProviderUserInputAnswers): Promise<void> =>
+      Promise.resolve(undefined),
+  );
 
-  override sendTurn(input: CodexAppServerSendTurnInput): Promise<ProviderTurnStartResult> {
-    return this.sendTurnImpl(input);
-  }
+  public readonly closeImpl = vi.fn(() => Promise.resolve(undefined));
 
-  override interruptTurn(threadId: ThreadId, turnId?: TurnId): Promise<void> {
-    return this.interruptTurnImpl(threadId, turnId);
+  readonly options: CodexSessionRuntimeOptions;
+
+  constructor(options: CodexSessionRuntimeOptions) {
+    this.options = options;
   }
 
-  override readThread(threadId: ThreadId) {
-    return this.readThreadImpl(threadId);
+  start() {
+    return Effect.promise(() => this.startImpl());
   }
 
-  override rollbackThread(threadId: ThreadId, numTurns: number) {
-    return this.rollbackThreadImpl(threadId, numTurns);
+  getSession = Effect.promise(() => this.startImpl());
+
+  sendTurn(input: CodexSessionRuntimeSendTurnInput) {
+    return Effect.promise(() => this.sendTurnImpl(input));
   }
 
-  override respondToRequest(
-    threadId: ThreadId,
-    requestId: ApprovalRequestId,
-    decision: ProviderApprovalDecision,
-  ): Promise<void> {
-    return this.respondToRequestImpl(threadId, requestId, decision);
+  interruptTurn(turnId?: TurnId) {
+    return Effect.promise(() => this.interruptTurnImpl(turnId));
   }
 
-  override respondToUserInput(
-    threadId: ThreadId,
-    requestId: ApprovalRequestId,
-    answers: ProviderUserInputAnswers,
-  ): Promise<void> {
-    return this.respondToUserInputImpl(threadId, requestId, answers);
+  readThread = Effect.promise(() => this.readThreadImpl());
+
+  rollbackThread(numTurns: number) {
+    return Effect.promise(() => this.rollbackThreadImpl(numTurns));
   }
 
-  override stopSession(_threadId: ThreadId): void {}
+  respondToRequest(requestId: ApprovalRequestId, decision: ProviderApprovalDecision) {
+    return Effect.promise(() => this.respondToRequestImpl(requestId, decision));
+  }
 
-  override listSessions(): ProviderSession[] {
-    return [];
+  respondToUserInput(requestId: ApprovalRequestId, answers: ProviderUserInputAnswers) {
+    return Effect.promise(() => this.respondToUserInputImpl(requestId, answers));
   }
 
-  override hasSession(_threadId: ThreadId): boolean {
-    return false;
+  get events() {
+    return Stream.fromQueue(this.eventQueue);
   }
 
-  override stopAll(): void {
-    this.stopAllImpl();
+  close = Effect.promise(() => this.closeImpl());
+
+  emit(event: ProviderEvent) {
+    return Queue.offer(this.eventQueue, event).pipe(Effect.asVoid);
   }
 }
 
+function makeRuntimeFactory() {
+  const runtimes: Array<FakeCodexRuntime> = [];
+  const factory = vi.fn((options: CodexSessionRuntimeOptions) => {
+    const runtime = new FakeCodexRuntime(options);
+    runtimes.push(runtime);
+    return Effect.succeed(runtime);
+  });
+
+  return {
+    factory,
+    get lastRuntime(): FakeCodexRuntime | undefined {
+      return runtimes.at(-1);
+    },
+  };
+}
+
+function makeScopedRuntimeFactory(options?: { readonly failConstruction?: boolean }) {
+  const runtimes: Array<FakeCodexRuntime> = [];
+  const releasedThreadIds: Array<ThreadId> = [];
+
+  const factory = vi.fn((runtimeOptions: CodexSessionRuntimeOptions) =>
+    Effect.gen(function* () {
+      yield* Scope.Scope;
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          releasedThreadIds.push(runtimeOptions.threadId);
+        }),
+      );
+
+      if (options?.failConstruction) {
+        return yield* new CodexErrors.CodexAppServerSpawnError({
+          command: `${runtimeOptions.binaryPath} app-server`,
+          cause: new Error("runtime construction failed"),
+        });
+      }
+
+      const runtime = new FakeCodexRuntime(runtimeOptions);
+      runtimes.push(runtime);
+      return runtime;
+    }),
+  );
+
+  return {
+    factory,
+    releasedThreadIds,
+    get lastRuntime(): FakeCodexRuntime | undefined {
+      return runtimes.at(-1);
+    },
+  };
+}
+
 const providerSessionDirectoryTestLayer = Layer.succeed(ProviderSessionDirectory, {
   upsert: () => Effect.void,
   getProvider: () =>
     Effect.die(new Error("ProviderSessionDirectory.getProvider is not used in test")),
   getBinding: () => Effect.succeed(Option.none()),
-  remove: () => Effect.void,
   listThreadIds: () => Effect.succeed([]),
+  listBindings: () => Effect.succeed([]),
 });
 
-const validationManager = new FakeCodexManager();
+const validationRuntimeFactory = makeRuntimeFactory();
 const validationLayer = it.layer(
-  makeCodexAdapterLive({ manager: validationManager }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = decodeCodexSettings({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: validationRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -164,7 +244,7 @@ validationLayer("CodexAdapterLive validation", (it) => {
       const adapter = yield* CodexAdapter;
       const result = yield* adapter
         .startSession({
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           threadId: asThreadId("thread-1"),
           runtimeMode: "full-access",
         })
@@ -174,50 +254,52 @@ validationLayer("CodexAdapterLive validation", (it) => {
       assert.deepStrictEqual(
         result.failure,
         new ProviderAdapterValidationError({
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           operation: "startSession",
           issue: "Expected provider 'codex' but received 'claudeAgent'.",
         }),
       );
-      assert.equal(validationManager.startSessionImpl.mock.calls.length, 0);
+      assert.equal(validationRuntimeFactory.factory.mock.calls.length, 0);
     }),
   );
   it.effect("maps codex model options before starting a session", () =>
     Effect.gen(function* () {
-      validationManager.startSessionImpl.mockClear();
+      validationRuntimeFactory.factory.mockClear();
       const adapter = yield* CodexAdapter;
 
       yield* adapter.startSession({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        modelSelection: {
-          provider: "codex",
-          model: "gpt-5.3-codex",
-          options: {
-            fastMode: true,
-          },
-        },
+        modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.3-codex", [
+          { id: "fastMode", value: true },
+        ]),
         runtimeMode: "full-access",
       });
 
-      assert.deepStrictEqual(validationManager.startSessionImpl.mock.calls[0]?.[0], {
-        provider: "codex",
-        threadId: asThreadId("thread-1"),
+      assert.deepStrictEqual(validationRuntimeFactory.factory.mock.calls[0]?.[0], {
         binaryPath: "codex",
+        cwd: process.cwd(),
         model: "gpt-5.3-codex",
+        providerInstanceId: ProviderInstanceId.make("codex"),
         serviceTier: "fast",
+        threadId: asThreadId("thread-1"),
         runtimeMode: "full-access",
       });
     }),
   );
 });
 
-const sessionErrorManager = new FakeCodexManager();
-sessionErrorManager.sendTurnImpl.mockImplementation(async () => {
-  throw new Error("Unknown session: sess-missing");
-});
+const sessionRuntimeFactory = makeRuntimeFactory();
 const sessionErrorLayer = it.layer(
-  makeCodexAdapterLive({ manager: sessionErrorManager }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = decodeCodexSettings({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: sessionRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -226,7 +308,7 @@ const sessionErrorLayer = it.layer(
 );
 
 sessionErrorLayer("CodexAdapterLive session errors", (it) => {
-  it.effect("maps unknown-session sendTurn errors to ProviderAdapterSessionNotFoundError", () =>
+  it.effect("maps missing adapter sessions to ProviderAdapterSessionNotFoundError", () =>
     Effect.gen(function* () {
       const adapter = yield* CodexAdapter;
       const result = yield* adapter
@@ -241,33 +323,34 @@ sessionErrorLayer("CodexAdapterLive session errors", (it) => {
       assert.equal(result.failure._tag, "ProviderAdapterSessionNotFoundError");
       assert.equal(result.failure.provider, "codex");
       assert.equal(result.failure.threadId, "sess-missing");
-      assert.equal(result.failure.cause instanceof Error, true);
     }),
   );
 
   it.effect("maps codex model options before sending a turn", () =>
     Effect.gen(function* () {
-      sessionErrorManager.sendTurnImpl.mockClear();
       const adapter = yield* CodexAdapter;
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("sess-missing"),
+        runtimeMode: "full-access",
+      });
+      const runtime = sessionRuntimeFactory.lastRuntime;
+      assert.ok(runtime);
+      runtime.sendTurnImpl.mockClear();
 
       yield* Effect.ignore(
         adapter.sendTurn({
           threadId: asThreadId("sess-missing"),
           input: "hello",
-          modelSelection: {
-            provider: "codex",
-            model: "gpt-5.3-codex",
-            options: {
-              reasoningEffort: "high",
-              fastMode: true,
-            },
-          },
+          modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.3-codex", [
+            { id: "reasoningEffort", value: "high" },
+            { id: "fastMode", value: true },
+          ]),
           attachments: [],
         }),
       );
 
-      assert.deepStrictEqual(sessionErrorManager.sendTurnImpl.mock.calls[0]?.[0], {
-        threadId: asThreadId("sess-missing"),
+      assert.deepStrictEqual(runtime.sendTurnImpl.mock.calls[0]?.[0], {
         input: "hello",
         model: "gpt-5.3-codex",
         effort: "high",
@@ -275,11 +358,74 @@ sessionErrorLayer("CodexAdapterLive session errors", (it) => {
       });
     }),
   );
+
+  it.effect("maps codex model options for the adapter's bound custom instance id", () => {
+    const customInstanceId = ProviderInstanceId.make("codex_personal");
+    const customRuntimeFactory = makeRuntimeFactory();
+    const customLayer = Layer.effect(
+      CodexAdapter,
+      Effect.gen(function* () {
+        const codexConfig = decodeCodexSettings({});
+        return yield* makeCodexAdapter(codexConfig, {
+          instanceId: customInstanceId,
+          makeRuntime: customRuntimeFactory.factory,
+        });
+      }),
+    ).pipe(
+      Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+      Layer.provideMerge(ServerSettingsService.layerTest()),
+      Layer.provideMerge(providerSessionDirectoryTestLayer),
+      Layer.provideMerge(NodeServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const adapter = yield* CodexAdapter;
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("sess-custom-instance"),
+        runtimeMode: "full-access",
+      });
+      const runtime = customRuntimeFactory.lastRuntime;
+      assert.ok(runtime);
+      runtime.sendTurnImpl.mockClear();
+
+      yield* Effect.ignore(
+        adapter.sendTurn({
+          threadId: asThreadId("sess-custom-instance"),
+          input: "hello",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("codex_personal"),
+            "gpt-5.3-codex",
+            [
+              { id: "reasoningEffort", value: "high" },
+              { id: "fastMode", value: true },
+            ],
+          ),
+          attachments: [],
+        }),
+      );
+
+      assert.deepStrictEqual(runtime.sendTurnImpl.mock.calls[0]?.[0], {
+        input: "hello",
+        model: "gpt-5.3-codex",
+        effort: "high",
+        serviceTier: "fast",
+      });
+    }).pipe(Effect.provide(customLayer));
+  });
 });
 
-const lifecycleManager = new FakeCodexManager();
+const lifecycleRuntimeFactory = makeRuntimeFactory();
 const lifecycleLayer = it.layer(
-  makeCodexAdapterLive({ manager: lifecycleManager }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = decodeCodexSettings({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: lifecycleRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -287,30 +433,48 @@ const lifecycleLayer = it.layer(
   ),
 );
 
+function startLifecycleRuntime() {
+  return Effect.gen(function* () {
+    const adapter = yield* CodexAdapter;
+    yield* adapter.startSession({
+      provider: ProviderDriverKind.make("codex"),
+      threadId: asThreadId("thread-1"),
+      runtimeMode: "full-access",
+    });
+    const runtime = lifecycleRuntimeFactory.lastRuntime;
+    assert.ok(runtime);
+    return { adapter, runtime };
+  });
+}
+
 lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
   it.effect("maps completed agent message items to canonical item.completed events", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
       const event: ProviderEvent = {
         id: asEventId("evt-msg-complete"),
         kind: "notification",
-        provider: "codex",
-        createdAt: new Date().toISOString(),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "item/completed",
         threadId: asThreadId("thread-1"),
         turnId: asTurnId("turn-1"),
         itemId: asItemId("msg_1"),
         payload: {
+          completedAtMs: 1_778_000_000_000,
+          threadId: "thread-1",
+          turnId: "turn-1",
           item: {
             type: "agentMessage",
             id: "msg_1",
+            text: "done",
           },
         },
       };
 
-      lifecycleManager.emit("event", event);
+      yield* runtime.emit(event);
       const firstEvent = yield* Fiber.join(firstEventFiber);
 
       assert.equal(firstEvent._tag, "Some");
@@ -329,28 +493,31 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("maps completed plan items to canonical proposed-plan completion events", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
       const event: ProviderEvent = {
         id: asEventId("evt-plan-complete"),
         kind: "notification",
-        provider: "codex",
-        createdAt: new Date().toISOString(),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "item/completed",
         threadId: asThreadId("thread-1"),
         turnId: asTurnId("turn-1"),
         itemId: asItemId("plan_1"),
         payload: {
+          completedAtMs: 1_778_000_000_000,
+          threadId: "thread-1",
+          turnId: "turn-1",
           item: {
-            type: "Plan",
+            type: "plan",
             id: "plan_1",
             text: "## Final plan\n\n- one\n- two",
           },
         },
       };
 
-      lifecycleManager.emit("event", event);
+      yield* runtime.emit(event);
       const firstEvent = yield* Fiber.join(firstEventFiber);
 
       assert.equal(firstEvent._tag, "Some");
@@ -368,19 +535,22 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("maps plan deltas to canonical proposed-plan delta events", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
-      lifecycleManager.emit("event", {
+      yield* runtime.emit({
         id: asEventId("evt-plan-delta"),
         kind: "notification",
-        provider: "codex",
-        createdAt: new Date().toISOString(),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "item/plan/delta",
         threadId: asThreadId("thread-1"),
         turnId: asTurnId("turn-1"),
         itemId: asItemId("plan_1"),
         payload: {
+          threadId: "thread-1",
+          turnId: "turn-1",
+          itemId: "plan_1",
           delta: "## Final plan",
         },
       } satisfies ProviderEvent);
@@ -402,20 +572,20 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("maps session/closed lifecycle events to canonical session.exited runtime events", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
       const event: ProviderEvent = {
         id: asEventId("evt-session-closed"),
         kind: "session",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "session/closed",
         message: "Session stopped",
       };
 
-      lifecycleManager.emit("event", event);
+      yield* runtime.emit(event);
       const firstEvent = yield* Fiber.join(firstEventFiber);
 
       assert.equal(firstEvent._tag, "Some");
@@ -433,18 +603,20 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("maps retryable Codex error notifications to runtime.warning", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
-      lifecycleManager.emit("event", {
+      yield* runtime.emit({
         id: asEventId("evt-retryable-error"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "error",
         turnId: asTurnId("turn-1"),
         payload: {
+          threadId: "thread-1",
+          turnId: "turn-1",
           error: {
             message: "Reconnecting... 2/5",
           },
@@ -469,15 +641,15 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("maps process stderr notifications to runtime.warning", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
-      lifecycleManager.emit("event", {
+      yield* runtime.emit({
         id: asEventId("evt-process-stderr"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "process/stderr",
         turnId: asTurnId("turn-1"),
         message: "The filename or extension is too long. (os error 206)",
@@ -501,17 +673,51 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
     }),
   );
 
+  it.effect("maps realtime started notifications with upstream realtime session ids", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+      yield* runtime.emit({
+        id: asEventId("evt-realtime-started"),
+        kind: "notification",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        createdAt: "2026-01-01T00:00:00.000Z",
+        method: "thread/realtime/started",
+        payload: {
+          threadId: "thread-1",
+          realtimeSessionId: "realtime-session-1",
+          version: "v2",
+        },
+      } satisfies ProviderEvent);
+
+      const firstEvent = yield* Fiber.join(firstEventFiber);
+
+      assert.equal(firstEvent._tag, "Some");
+      if (firstEvent._tag !== "Some") {
+        return;
+      }
+      assert.equal(firstEvent.value.type, "thread.realtime.started");
+      if (firstEvent.value.type !== "thread.realtime.started") {
+        return;
+      }
+      assert.equal(firstEvent.value.threadId, "thread-1");
+      assert.equal(firstEvent.value.payload.realtimeSessionId, "realtime-session-1");
+    }),
+  );
+
   it.effect("maps fatal websocket stderr notifications to runtime.error", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
-      lifecycleManager.emit("event", {
+      yield* runtime.emit({
         id: asEventId("evt-process-stderr-websocket"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "process/stderr",
         turnId: asTurnId("turn-1"),
         message:
@@ -539,26 +745,25 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("preserves request type when mapping serverRequest/resolved", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
       const event: ProviderEvent = {
         id: asEventId("evt-request-resolved"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "serverRequest/resolved",
+        requestKind: "command",
         requestId: ApprovalRequestId.make("req-1"),
         payload: {
-          request: {
-            method: "item/commandExecution/requestApproval",
-          },
-          decision: "accept",
+          threadId: "thread-1",
+          requestId: "req-1",
         },
       };
 
-      lifecycleManager.emit("event", event);
+      yield* runtime.emit(event);
       const firstEvent = yield* Fiber.join(firstEventFiber);
 
       assert.equal(firstEvent._tag, "Some");
@@ -575,26 +780,25 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("preserves file-read request type when mapping serverRequest/resolved", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
       const event: ProviderEvent = {
         id: asEventId("evt-file-read-request-resolved"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "serverRequest/resolved",
+        requestKind: "file-read",
         requestId: ApprovalRequestId.make("req-file-read-1"),
         payload: {
-          request: {
-            method: "item/fileRead/requestApproval",
-          },
-          decision: "accept",
+          threadId: "thread-1",
+          requestId: "req-file-read-1",
         },
       };
 
-      lifecycleManager.emit("event", event);
+      yield* runtime.emit(event);
       const firstEvent = yield* Fiber.join(firstEventFiber);
 
       assert.equal(firstEvent._tag, "Some");
@@ -611,24 +815,26 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("preserves explicit empty multi-select user-input answers", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
       const event: ProviderEvent = {
         id: asEventId("evt-user-input-empty"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "item/tool/requestUserInput/answered",
         payload: {
           answers: {
-            scope: [],
+            scope: {
+              answers: [],
+            },
           },
         },
       };
 
-      lifecycleManager.emit("event", event);
+      yield* runtime.emit(event);
       const firstEvent = yield* Fiber.join(firstEventFiber);
 
       assert.equal(firstEvent._tag, "Some");
@@ -647,7 +853,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
   it.effect("maps windowsSandbox/setupCompleted to session state and warning on failure", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const eventsFiber = yield* Stream.runCollect(Stream.take(adapter.streamEvents, 2)).pipe(
         Effect.forkChild,
       );
@@ -655,18 +861,19 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       const event: ProviderEvent = {
         id: asEventId("evt-windows-sandbox-failed"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "windowsSandbox/setupCompleted",
         message: "Sandbox setup failed",
         payload: {
+          mode: "unelevated",
           success: false,
-          detail: "unsupported environment",
+          error: "unsupported environment",
         },
       };
 
-      lifecycleManager.emit("event", event);
+      yield* runtime.emit(event);
       const events = Array.from(yield* Fiber.join(eventsFiber));
 
       assert.equal(events.length, 2);
@@ -691,20 +898,23 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
     "maps requestUserInput requests and answered notifications to canonical user-input events",
     () =>
       Effect.gen(function* () {
-        const adapter = yield* CodexAdapter;
+        const { adapter, runtime } = yield* startLifecycleRuntime();
         const eventsFiber = yield* Stream.runCollect(Stream.take(adapter.streamEvents, 2)).pipe(
           Effect.forkChild,
         );
 
-        lifecycleManager.emit("event", {
+        yield* runtime.emit({
           id: asEventId("evt-user-input-requested"),
           kind: "request",
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           threadId: asThreadId("thread-1"),
-          createdAt: new Date().toISOString(),
+          createdAt: "2026-01-01T00:00:00.000Z",
           method: "item/tool/requestUserInput",
           requestId: ApprovalRequestId.make("req-user-input-1"),
           payload: {
+            itemId: "item-user-input-1",
+            threadId: "thread-1",
+            turnId: "turn-1",
             questions: [
               {
                 id: "sandbox_mode",
@@ -716,17 +926,16 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
                     description: "Allow workspace writes only",
                   },
                 ],
-                multiSelect: true,
               },
             ],
           },
         } satisfies ProviderEvent);
-        lifecycleManager.emit("event", {
+        yield* runtime.emit({
           id: asEventId("evt-user-input-resolved"),
           kind: "notification",
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           threadId: asThreadId("thread-1"),
-          createdAt: new Date().toISOString(),
+          createdAt: "2026-01-01T00:00:00.000Z",
           method: "item/tool/requestUserInput/answered",
           requestId: ApprovalRequestId.make("req-user-input-1"),
           payload: {
@@ -743,7 +952,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
         if (events[0]?.type === "user-input.requested") {
           assert.equal(events[0].requestId, "req-user-input-1");
           assert.equal(events[0].payload.questions[0]?.id, "sandbox_mode");
-          assert.equal(events[0].payload.questions[0]?.multiSelect, true);
+          assert.equal(events[0].payload.questions[0]?.multiSelect, false);
         }
 
         assert.equal(events[1]?.type, "user-input.resolved");
@@ -756,174 +965,18 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       }),
   );
 
-  it.effect("maps Codex task and reasoning event chunks into canonical runtime events", () =>
-    Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
-      const eventsFiber = yield* Stream.runCollect(Stream.take(adapter.streamEvents, 5)).pipe(
-        Effect.forkChild,
-      );
-
-      lifecycleManager.emit("event", {
-        id: asEventId("evt-codex-task-started"),
-        kind: "notification",
-        provider: "codex",
-        threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
-        method: "codex/event/task_started",
-        payload: {
-          id: "turn-structured-1",
-          msg: {
-            type: "task_started",
-            turn_id: "turn-structured-1",
-            collaboration_mode_kind: "plan",
-          },
-        },
-      } satisfies ProviderEvent);
-
-      lifecycleManager.emit("event", {
-        id: asEventId("evt-codex-agent-reasoning"),
-        kind: "notification",
-        provider: "codex",
-        threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
-        method: "codex/event/agent_reasoning",
-        payload: {
-          id: "turn-structured-1",
-          msg: {
-            type: "agent_reasoning",
-            text: "Need to compare both transport layers before finalizing the plan.",
-          },
-        },
-      } satisfies ProviderEvent);
-
-      lifecycleManager.emit("event", {
-        id: asEventId("evt-codex-reasoning-delta"),
-        kind: "notification",
-        provider: "codex",
-        threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
-        method: "codex/event/reasoning_content_delta",
-        payload: {
-          id: "turn-structured-1",
-          msg: {
-            type: "reasoning_content_delta",
-            turn_id: "turn-structured-1",
-            item_id: "rs_reasoning_1",
-            delta: "**Compare** transport boundaries",
-            summary_index: 0,
-          },
-        },
-      } satisfies ProviderEvent);
-
-      lifecycleManager.emit("event", {
-        id: asEventId("evt-codex-task-complete"),
-        kind: "notification",
-        provider: "codex",
-        threadId: asThreadId("thread-1"),
-        createdAt: new Date().toISOString(),
-        method: "codex/event/task_complete",
-        payload: {
-          id: "turn-structured-1",
-          msg: {
-            type: "task_complete",
-            turn_id: "turn-structured-1",
-            last_agent_message: "<proposed_plan>\n# Ship it\n</proposed_plan>",
-          },
-        },
-      } satisfies ProviderEvent);
-
-      const events = Array.from(yield* Fiber.join(eventsFiber));
-
-      assert.equal(events[0]?.type, "task.started");
-      if (events[0]?.type === "task.started") {
-        assert.equal(events[0].turnId, "turn-structured-1");
-        assert.equal(events[0].payload.taskId, "turn-structured-1");
-        assert.equal(events[0].payload.taskType, "plan");
-      }
-
-      assert.equal(events[1]?.type, "task.progress");
-      if (events[1]?.type === "task.progress") {
-        assert.equal(events[1].payload.taskId, "turn-structured-1");
-        assert.equal(
-          events[1].payload.description,
-          "Need to compare both transport layers before finalizing the plan.",
-        );
-      }
-
-      assert.equal(events[2]?.type, "content.delta");
-      if (events[2]?.type === "content.delta") {
-        assert.equal(events[2].turnId, "turn-structured-1");
-        assert.equal(events[2].itemId, "rs_reasoning_1");
-        assert.equal(events[2].payload.streamKind, "reasoning_summary_text");
-        assert.equal(events[2].payload.summaryIndex, 0);
-      }
-
-      assert.equal(events[3]?.type, "task.completed");
-      if (events[3]?.type === "task.completed") {
-        assert.equal(events[3].turnId, "turn-structured-1");
-        assert.equal(events[3].payload.taskId, "turn-structured-1");
-        assert.equal(events[3].payload.summary, "<proposed_plan>\n# Ship it\n</proposed_plan>");
-      }
-
-      assert.equal(events[4]?.type, "turn.proposed.completed");
-      if (events[4]?.type === "turn.proposed.completed") {
-        assert.equal(events[4].turnId, "turn-structured-1");
-        assert.equal(events[4].payload.planMarkdown, "# Ship it");
-      }
-    }),
-  );
-
-  it.effect("prefers manager-assigned turn ids for Codex task events", () =>
-    Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
-      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
-
-      lifecycleManager.emit("event", {
-        id: asEventId("evt-codex-task-started-parent-turn"),
-        kind: "notification",
-        provider: "codex",
-        threadId: asThreadId("thread-1"),
-        turnId: asTurnId("turn-parent"),
-        createdAt: new Date().toISOString(),
-        method: "codex/event/task_started",
-        payload: {
-          id: "turn-child",
-          msg: {
-            type: "task_started",
-            turn_id: "turn-child",
-            collaboration_mode_kind: "default",
-          },
-          conversationId: "child-provider-thread",
-        },
-      } satisfies ProviderEvent);
-
-      const firstEvent = yield* Fiber.join(firstEventFiber);
-      assert.equal(firstEvent._tag, "Some");
-      if (firstEvent._tag !== "Some") {
-        return;
-      }
-      assert.equal(firstEvent.value.type, "task.started");
-      if (firstEvent.value.type !== "task.started") {
-        return;
-      }
-      assert.equal(firstEvent.value.turnId, "turn-parent");
-      assert.equal(firstEvent.value.providerRefs?.providerTurnId, "turn-parent");
-      assert.equal(firstEvent.value.payload.taskId, "turn-child");
-    }),
-  );
-
   it.effect("unwraps Codex token usage payloads for context window events", () =>
     Effect.gen(function* () {
-      const adapter = yield* CodexAdapter;
+      const { adapter, runtime } = yield* startLifecycleRuntime();
       const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
 
-      lifecycleManager.emit("event", {
+      yield* runtime.emit({
         id: asEventId("evt-codex-thread-token-usage-updated"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
         turnId: asTurnId("turn-1"),
-        createdAt: new Date().toISOString(),
+        createdAt: "2026-01-01T00:00:00.000Z",
         method: "thread/tokenUsage/updated",
         payload: {
           threadId: "thread-1",
@@ -977,9 +1030,152 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
   );
 });
 
-afterAll(() => {
-  if (lifecycleManager.stopAllImpl.mock.calls.length === 0) {
-    lifecycleManager.stopAll();
-  }
-  assert.ok(lifecycleManager.stopAllImpl.mock.calls.length >= 1);
+const scopedLifecycleRuntimeFactory = makeScopedRuntimeFactory();
+const scopedLifecycleLayer = it.layer(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = decodeCodexSettings({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: scopedLifecycleRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
+    Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+    Layer.provideMerge(ServerSettingsService.layerTest()),
+    Layer.provideMerge(providerSessionDirectoryTestLayer),
+    Layer.provideMerge(NodeServices.layer),
+  ),
+);
+
+scopedLifecycleLayer("CodexAdapterLive scoped lifecycle", (it) => {
+  it.effect("closes the externally owned session scope on stopSession", () =>
+    Effect.gen(function* () {
+      scopedLifecycleRuntimeFactory.releasedThreadIds.length = 0;
+      const adapter = yield* CodexAdapter;
+
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-stop"),
+        runtimeMode: "full-access",
+      });
+
+      const runtime = scopedLifecycleRuntimeFactory.lastRuntime;
+      assert.ok(runtime);
+
+      yield* adapter.stopSession(asThreadId("thread-stop"));
+
+      assert.equal(runtime.closeImpl.mock.calls.length, 1);
+      assert.deepStrictEqual(scopedLifecycleRuntimeFactory.releasedThreadIds, [
+        asThreadId("thread-stop"),
+      ]);
+      assert.equal(yield* adapter.hasSession(asThreadId("thread-stop")), false);
+    }),
+  );
+});
+
+const scopedFailureRuntimeFactory = makeScopedRuntimeFactory({ failConstruction: true });
+const scopedFailureLayer = it.layer(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = decodeCodexSettings({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: scopedFailureRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
+    Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+    Layer.provideMerge(ServerSettingsService.layerTest()),
+    Layer.provideMerge(providerSessionDirectoryTestLayer),
+    Layer.provideMerge(NodeServices.layer),
+  ),
+);
+
+scopedFailureLayer("CodexAdapterLive scoped startup failure", (it) => {
+  it.effect("closes the externally owned session scope when startSession fails", () =>
+    Effect.gen(function* () {
+      scopedFailureRuntimeFactory.releasedThreadIds.length = 0;
+      const adapter = yield* CodexAdapter;
+
+      const result = yield* adapter
+        .startSession({
+          provider: ProviderDriverKind.make("codex"),
+          threadId: asThreadId("thread-fail"),
+          runtimeMode: "full-access",
+        })
+        .pipe(Effect.result);
+
+      assert.equal(result._tag, "Failure");
+      assert.equal(result.failure._tag, "ProviderAdapterProcessError");
+      assert.deepStrictEqual(scopedFailureRuntimeFactory.releasedThreadIds, [
+        asThreadId("thread-fail"),
+      ]);
+      assert.equal(yield* adapter.hasSession(asThreadId("thread-fail")), false);
+    }),
+  );
 });
+
+it.effect("flushes managed native logs when the adapter layer shuts down", () =>
+  Effect.gen(function* () {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-codex-adapter-native-log-"));
+    const basePath = path.join(tempDir, "provider-native.ndjson");
+    const runtimeFactory = makeRuntimeFactory();
+    const scope = yield* Scope.make("sequential");
+    let scopeClosed = false;
+
+    try {
+      const layer = Layer.effect(
+        CodexAdapter,
+        Effect.gen(function* () {
+          const codexConfig = decodeCodexSettings({});
+          return yield* makeCodexAdapter(codexConfig, {
+            makeRuntime: runtimeFactory.factory,
+            nativeEventLogPath: basePath,
+          });
+        }),
+      ).pipe(
+        Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+        Layer.provideMerge(ServerSettingsService.layerTest()),
+        Layer.provideMerge(providerSessionDirectoryTestLayer),
+        Layer.provideMerge(NodeServices.layer),
+      );
+      const context = yield* Layer.buildWithScope(layer, scope);
+      const adapter = yield* Effect.service(CodexAdapter).pipe(Effect.provide(context));
+
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-logger"),
+        runtimeMode: "full-access",
+      });
+
+      const runtime = runtimeFactory.lastRuntime;
+      assert.ok(runtime);
+
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+      yield* runtime.emit({
+        id: asEventId("evt-native-log"),
+        kind: "notification",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-logger"),
+        createdAt: "2026-01-01T00:00:00.000Z",
+        method: "process/stderr",
+        message: "native flush test",
+      } satisfies ProviderEvent);
+      yield* Fiber.join(firstEventFiber);
+
+      yield* Scope.close(scope, Exit.void);
+      scopeClosed = true;
+
+      const threadLogPath = path.join(tempDir, "thread-logger.log");
+      assert.equal(fs.existsSync(threadLogPath), true);
+      const contents = fs.readFileSync(threadLogPath, "utf8");
+      assert.match(contents, /NTIVE: .*"message":"native flush test"/);
+    } finally {
+      if (!scopeClosed) {
+        yield* Scope.close(scope, Exit.void);
+      }
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }),
+);
diff --git a/apps/server/src/provider/Layers/CodexAdapter.ts b/apps/server/src/provider/Layers/CodexAdapter.ts
index 60de91b79ac..28af1cda27b 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -1,108 +1,149 @@
 /**
  * CodexAdapterLive - Scoped live implementation for the Codex provider adapter.
  *
- * Wraps `CodexAppServerManager` behind the `CodexAdapter` service contract and
- * maps manager failures into the shared `ProviderAdapterError` algebra.
+ * Wraps the typed Codex session runtime behind the `CodexAdapter` service
+ * contract and maps runtime failures into the shared `ProviderAdapterError`
+ * algebra.
  *
  * @module CodexAdapterLive
  */
 import {
   type CanonicalItemType,
   type CanonicalRequestType,
+  type CodexSettings,
+  ProviderDriverKind,
   type ProviderEvent,
+  ProviderInstanceId,
   type ProviderRuntimeEvent,
+  type ProviderRequestKind,
   type ThreadTokenUsageSnapshot,
   type ProviderUserInputAnswers,
   RuntimeItemId,
   RuntimeRequestId,
-  RuntimeTaskId,
   ProviderApprovalDecision,
-  ProviderItemId,
   ThreadId,
-  TurnId,
   ProviderSendTurnInput,
 } from "@t3tools/contracts";
-import { Effect, FileSystem, Layer, Queue, Schema, Context, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import * as CodexErrors from "effect-codex-app-server/errors";
+import * as EffectCodexSchema from "effect-codex-app-server/schema";
+
+import {
+  getModelSelectionBooleanOptionValue,
+  getModelSelectionStringOptionValue,
+} from "@t3tools/shared/model";
 
 import {
-  ProviderAdapterProcessError,
   ProviderAdapterRequestError,
+  ProviderAdapterProcessError,
   ProviderAdapterSessionClosedError,
   ProviderAdapterSessionNotFoundError,
   ProviderAdapterValidationError,
   type ProviderAdapterError,
 } from "../Errors.ts";
-import { CodexAdapter, type CodexAdapterShape } from "../Services/CodexAdapter.ts";
-import {
-  CodexAppServerManager,
-  type CodexAppServerStartSessionInput,
-} from "../../codexAppServerManager.ts";
+import { type CodexAdapterShape } from "../Services/CodexAdapter.ts";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import {
+  CodexResumeCursorSchema,
+  CodexSessionRuntimeThreadIdMissingError,
+  makeCodexSessionRuntime,
+  type CodexSessionRuntimeError,
+  type CodexSessionRuntimeOptions,
+  type CodexSessionRuntimeShape,
+} from "./CodexSessionRuntime.ts";
 import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
+const isCodexAppServerProcessExitedError = Schema.is(CodexErrors.CodexAppServerProcessExitedError);
+const isCodexAppServerTransportError = Schema.is(CodexErrors.CodexAppServerTransportError);
+const isCodexSessionRuntimeThreadIdMissingError = Schema.is(
+  CodexSessionRuntimeThreadIdMissingError,
+);
+const isCodexResumeCursorSchema = Schema.is(CodexResumeCursorSchema);
 
-const PROVIDER = "codex" as const;
+const PROVIDER = ProviderDriverKind.make("codex");
 
 export interface CodexAdapterLiveOptions {
-  readonly manager?: CodexAppServerManager;
-  readonly makeManager?: (services?: Context.Context<never>) => CodexAppServerManager;
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly makeRuntime?: (
+    options: CodexSessionRuntimeOptions,
+  ) => Effect.Effect<
+    CodexSessionRuntimeShape,
+    CodexSessionRuntimeError,
+    ChildProcessSpawner.ChildProcessSpawner | Scope.Scope
+  >;
   readonly nativeEventLogPath?: string;
   readonly nativeEventLogger?: EventNdjsonLogger;
 }
 
-function toSessionError(
+interface CodexAdapterSessionContext {
+  readonly threadId: ThreadId;
+  readonly scope: Scope.Closeable;
+  readonly runtime: CodexSessionRuntimeShape;
+  readonly eventFiber: Fiber.Fiber<void, never>;
+  stopped: boolean;
+}
+
+function mapCodexRuntimeError(
   threadId: ThreadId,
-  cause: unknown,
-): ProviderAdapterSessionNotFoundError | ProviderAdapterSessionClosedError | undefined {
-  const normalized = cause instanceof Error ? cause.message.toLowerCase() : "";
-  if (normalized.includes("unknown session") || normalized.includes("unknown provider session")) {
-    return new ProviderAdapterSessionNotFoundError({
+  method: string,
+  error: CodexSessionRuntimeError,
+): ProviderAdapterError {
+  if (isCodexAppServerProcessExitedError(error) || isCodexAppServerTransportError(error)) {
+    return new ProviderAdapterSessionClosedError({
       provider: PROVIDER,
       threadId,
-      cause,
+      cause: error,
     });
   }
-  if (normalized.includes("session is closed")) {
-    return new ProviderAdapterSessionClosedError({
+
+  if (isCodexSessionRuntimeThreadIdMissingError(error)) {
+    return new ProviderAdapterSessionNotFoundError({
       provider: PROVIDER,
       threadId,
-      cause,
+      cause: error,
     });
   }
-  return undefined;
-}
 
-function toRequestError(threadId: ThreadId, method: string, cause: unknown): ProviderAdapterError {
-  const sessionError = toSessionError(threadId, cause);
-  if (sessionError) {
-    return sessionError;
-  }
   return new ProviderAdapterRequestError({
     provider: PROVIDER,
     method,
-    detail: cause instanceof Error ? `${method} failed: ${cause.message}` : `${method} failed`,
-    cause,
+    detail: error.message,
+    cause: error,
   });
 }
 
-function asObject(value: unknown): Record<string, unknown> | undefined {
-  if (!value || typeof value !== "object") {
-    return undefined;
-  }
-  return value as Record<string, unknown>;
-}
+type CodexLifecycleItem =
+  | EffectCodexSchema.V2ItemStartedNotification["item"]
+  | EffectCodexSchema.V2ItemCompletedNotification["item"];
 
-function asString(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}
+type CodexToolUserInputQuestion =
+  | EffectCodexSchema.ServerRequest__ToolRequestUserInputQuestion
+  | EffectCodexSchema.ToolRequestUserInputParams__ToolRequestUserInputQuestion;
 
-function asArray(value: unknown): unknown[] | undefined {
-  return Array.isArray(value) ? value : undefined;
+const ApprovalDecisionPayload = Schema.Struct({
+  decision: ProviderApprovalDecision,
+});
+
+function readPayload<A>(
+  schema: Schema.Schema<A>,
+  payload: ProviderEvent["payload"],
+): A | undefined {
+  const isPayload = Schema.is(schema);
+  return isPayload(payload) ? payload : undefined;
 }
 
-function asNumber(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+function trimText(value: string | undefined | null): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : undefined;
 }
 
 const FATAL_CODEX_STDERR_SNIPPETS = ["failed to connect to websocket"];
@@ -112,26 +153,20 @@ function isFatalCodexProcessStderrMessage(message: string): boolean {
   return FATAL_CODEX_STDERR_SNIPPETS.some((snippet) => normalized.includes(snippet));
 }
 
-function normalizeCodexTokenUsage(value: unknown): ThreadTokenUsageSnapshot | undefined {
-  const usage = asObject(value);
-  const totalUsage = asObject(usage?.total_token_usage ?? usage?.total);
-  const lastUsage = asObject(usage?.last_token_usage ?? usage?.last);
-
-  const totalProcessedTokens =
-    asNumber(totalUsage?.total_tokens) ?? asNumber(totalUsage?.totalTokens);
-  const usedTokens =
-    asNumber(lastUsage?.total_tokens) ?? asNumber(lastUsage?.totalTokens) ?? totalProcessedTokens;
+function normalizeCodexTokenUsage(
+  usage: EffectCodexSchema.V2ThreadTokenUsageUpdatedNotification["tokenUsage"],
+): ThreadTokenUsageSnapshot | undefined {
+  const totalProcessedTokens = usage.total.totalTokens;
+  const usedTokens = usage.last.totalTokens;
   if (usedTokens === undefined || usedTokens <= 0) {
     return undefined;
   }
 
-  const maxTokens = asNumber(usage?.model_context_window) ?? asNumber(usage?.modelContextWindow);
-  const inputTokens = asNumber(lastUsage?.input_tokens) ?? asNumber(lastUsage?.inputTokens);
-  const cachedInputTokens =
-    asNumber(lastUsage?.cached_input_tokens) ?? asNumber(lastUsage?.cachedInputTokens);
-  const outputTokens = asNumber(lastUsage?.output_tokens) ?? asNumber(lastUsage?.outputTokens);
-  const reasoningOutputTokens =
-    asNumber(lastUsage?.reasoning_output_tokens) ?? asNumber(lastUsage?.reasoningOutputTokens);
+  const maxTokens = usage.modelContextWindow ?? undefined;
+  const inputTokens = usage.last.inputTokens;
+  const cachedInputTokens = usage.last.cachedInputTokens;
+  const outputTokens = usage.last.outputTokens;
+  const reasoningOutputTokens = usage.last.reasoningOutputTokens;
 
   return {
     usedTokens,
@@ -154,15 +189,9 @@ function normalizeCodexTokenUsage(value: unknown): ThreadTokenUsageSnapshot | un
   };
 }
 
-function toTurnId(value: string | undefined): TurnId | undefined {
-  return value?.trim() ? TurnId.make(value) : undefined;
-}
-
-function toProviderItemId(value: string | undefined): ProviderItemId | undefined {
-  return value?.trim() ? ProviderItemId.make(value) : undefined;
-}
-
-function toTurnStatus(value: unknown): "completed" | "failed" | "cancelled" | "interrupted" {
+function toTurnStatus(
+  value: EffectCodexSchema.V2TurnCompletedNotification["turn"]["status"] | "cancelled",
+): "completed" | "failed" | "cancelled" | "interrupted" {
   switch (value) {
     case "completed":
     case "failed":
@@ -174,8 +203,8 @@ function toTurnStatus(value: unknown): "completed" | "failed" | "cancelled" | "i
   }
 }
 
-function normalizeItemType(raw: unknown): string {
-  const type = asString(raw);
+function normalizeItemType(raw: string | undefined | null): string {
+  const type = trimText(raw);
   if (!type) return "item";
   return type
     .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
@@ -185,7 +214,7 @@ function normalizeItemType(raw: unknown): string {
     .toLowerCase();
 }
 
-function toCanonicalItemType(raw: unknown): CanonicalItemType {
+function toCanonicalItemType(raw: string | undefined | null): CanonicalItemType {
   const type = normalizeItemType(raw);
   if (type.includes("user")) return "user_message";
   if (type.includes("agent message") || type.includes("assistant")) return "assistant_message";
@@ -235,27 +264,18 @@ function itemTitle(itemType: CanonicalItemType): string | undefined {
   }
 }
 
-function itemDetail(
-  item: Record<string, unknown>,
-  payload: Record<string, unknown>,
-): string | undefined {
-  const nestedResult = asObject(item.result);
+function itemDetail(item: CodexLifecycleItem): string | undefined {
   const candidates = [
-    asString(item.command),
-    asString(item.title),
-    asString(item.summary),
-    asString(item.text),
-    asString(item.path),
-    asString(item.prompt),
-    asString(nestedResult?.command),
-    asString(payload.command),
-    asString(payload.message),
-    asString(payload.prompt),
+    "command" in item ? item.command : undefined,
+    "title" in item ? item.title : undefined,
+    "summary" in item ? item.summary : undefined,
+    "text" in item ? item.text : undefined,
+    "path" in item ? item.path : undefined,
+    "prompt" in item ? item.prompt : undefined,
   ];
   for (const candidate of candidates) {
-    if (!candidate) continue;
-    const trimmed = candidate.trim();
-    if (trimmed.length === 0) continue;
+    const trimmed = typeof candidate === "string" ? trimText(candidate) : undefined;
+    if (!trimmed) continue;
     return trimmed;
   }
   return undefined;
@@ -284,7 +304,7 @@ function toRequestTypeFromMethod(method: string): CanonicalRequestType {
   }
 }
 
-function toRequestTypeFromKind(kind: unknown): CanonicalRequestType {
+function toRequestTypeFromKind(kind: ProviderRequestKind | undefined): CanonicalRequestType {
   switch (kind) {
     case "command":
       return "command_execution_approval";
@@ -297,77 +317,36 @@ function toRequestTypeFromKind(kind: unknown): CanonicalRequestType {
   }
 }
 
-function toRequestTypeFromResolvedPayload(
-  payload: Record<string, unknown> | undefined,
-): CanonicalRequestType {
-  const request = asObject(payload?.request);
-  const method = asString(request?.method) ?? asString(payload?.method);
-  if (method) {
-    return toRequestTypeFromMethod(method);
-  }
-  const requestKind = asString(request?.kind) ?? asString(payload?.requestKind);
-  if (requestKind) {
-    return toRequestTypeFromKind(requestKind);
-  }
-  return "unknown";
-}
-
 function toCanonicalUserInputAnswers(
-  answers: ProviderUserInputAnswers | undefined,
+  answers: EffectCodexSchema.ToolRequestUserInputResponse["answers"],
 ): ProviderUserInputAnswers {
-  if (!answers) {
-    return {};
-  }
-
   return Object.fromEntries(
-    Object.entries(answers).flatMap(([questionId, value]) => {
-      if (typeof value === "string") {
-        return [[questionId, value] as const];
-      }
-
-      if (Array.isArray(value)) {
-        const normalized = value.filter((entry): entry is string => typeof entry === "string");
-        return [[questionId, normalized.length === 1 ? normalized[0] : normalized] as const];
-      }
-
-      const answerObject = asObject(value);
-      const answerList = asArray(answerObject?.answers)?.filter(
-        (entry): entry is string => typeof entry === "string",
-      );
-      if (!answerList) {
-        return [];
-      }
-      return [[questionId, answerList.length === 1 ? answerList[0] : answerList] as const];
+    Object.entries(answers).map(([questionId, value]) => {
+      const normalizedAnswers = value.answers.length === 1 ? value.answers[0]! : [...value.answers];
+      return [questionId, normalizedAnswers] as const;
     }),
   );
 }
 
-function toUserInputQuestions(payload: Record<string, unknown> | undefined) {
-  const questions = asArray(payload?.questions);
-  if (!questions) {
-    return undefined;
-  }
-
+function toUserInputQuestions(questions: ReadonlyArray<CodexToolUserInputQuestion>) {
   const parsedQuestions = questions
-    .map((entry) => {
-      const question = asObject(entry);
-      if (!question) return undefined;
-      const options = asArray(question.options)
-        ?.map((option) => {
-          const optionRecord = asObject(option);
-          if (!optionRecord) return undefined;
-          const label = asString(optionRecord.label)?.trim();
-          const description = asString(optionRecord.description)?.trim();
-          if (!label || !description) {
-            return undefined;
-          }
-          return { label, description };
-        })
-        .filter((option): option is { label: string; description: string } => option !== undefined);
-      const id = asString(question.id)?.trim();
-      const header = asString(question.header)?.trim();
-      const prompt = asString(question.question)?.trim();
-      if (!id || !header || !prompt || !options || options.length === 0) {
+    .map((question) => {
+      const options =
+        question.options
+          ?.map((option) => {
+            const label = trimText(option.label);
+            const description = trimText(option.description);
+            if (!label || !description) {
+              return undefined;
+            }
+            return { label, description };
+          })
+          .filter((option) => option !== undefined) ?? [];
+
+      const id = trimText(question.id);
+      const header = trimText(question.header);
+      const prompt = trimText(question.question);
+      if (!id || !header || !prompt || options.length === 0) {
         return undefined;
       }
       return {
@@ -375,38 +354,21 @@ function toUserInputQuestions(payload: Record<string, unknown> | undefined) {
         header,
         question: prompt,
         options,
-        multiSelect: question.multiSelect === true,
+        multiSelect: false,
       };
     })
-    .filter(
-      (
-        question,
-      ): question is {
-        id: string;
-        header: string;
-        question: string;
-        options: Array<{ label: string; description: string }>;
-        multiSelect: boolean;
-      } => question !== undefined,
-    );
+    .filter((question) => question !== undefined);
 
   return parsedQuestions.length > 0 ? parsedQuestions : undefined;
 }
 
 function toThreadState(
-  value: unknown,
+  status: EffectCodexSchema.V2ThreadStatusChangedNotification["status"],
 ): "active" | "idle" | "archived" | "closed" | "compacted" | "error" {
-  switch (value) {
+  switch (status.type) {
     case "idle":
       return "idle";
-    case "archived":
-      return "archived";
-    case "closed":
-      return "closed";
-    case "compacted":
-      return "compacted";
-    case "error":
-    case "failed":
+    case "systemError":
       return "error";
     default:
       return "active";
@@ -438,15 +400,7 @@ function contentStreamKindFromMethod(
   }
 }
 
-const PROPOSED_PLAN_BLOCK_REGEX = /<proposed_plan>\s*([\s\S]*?)\s*<\/proposed_plan>/i;
-
-function extractProposedPlanMarkdown(text: string | undefined): string | undefined {
-  const match = text ? PROPOSED_PLAN_BLOCK_REGEX.exec(text) : null;
-  const planMarkdown = match?.[1]?.trim();
-  return planMarkdown && planMarkdown.length > 0 ? planMarkdown : undefined;
-}
-
-function asRuntimeItemId(itemId: ProviderItemId): RuntimeItemId {
+function asRuntimeItemId(itemId: ProviderEvent["itemId"] & string): RuntimeItemId {
   return RuntimeItemId.make(itemId);
 }
 
@@ -454,48 +408,6 @@ function asRuntimeRequestId(requestId: string): RuntimeRequestId {
   return RuntimeRequestId.make(requestId);
 }
 
-function asRuntimeTaskId(taskId: string): RuntimeTaskId {
-  return RuntimeTaskId.make(taskId);
-}
-
-function codexEventMessage(
-  payload: Record<string, unknown> | undefined,
-): Record<string, unknown> | undefined {
-  return asObject(payload?.msg);
-}
-
-function codexEventBase(
-  event: ProviderEvent,
-  canonicalThreadId: ThreadId,
-): Omit<ProviderRuntimeEvent, "type" | "payload"> {
-  const payload = asObject(event.payload);
-  const msg = codexEventMessage(payload);
-  const turnId = event.turnId ?? toTurnId(asString(msg?.turn_id) ?? asString(msg?.turnId));
-  const itemId = event.itemId ?? toProviderItemId(asString(msg?.item_id) ?? asString(msg?.itemId));
-  const requestId = asString(msg?.request_id) ?? asString(msg?.requestId);
-  const base = runtimeEventBase(event, canonicalThreadId);
-  const providerRefs = base.providerRefs
-    ? {
-        ...base.providerRefs,
-        ...(turnId ? { providerTurnId: turnId } : {}),
-        ...(itemId ? { providerItemId: itemId } : {}),
-        ...(requestId ? { providerRequestId: requestId } : {}),
-      }
-    : {
-        ...(turnId ? { providerTurnId: turnId } : {}),
-        ...(itemId ? { providerItemId: itemId } : {}),
-        ...(requestId ? { providerRequestId: requestId } : {}),
-      };
-
-  return {
-    ...base,
-    ...(turnId ? { turnId } : {}),
-    ...(itemId ? { itemId: asRuntimeItemId(itemId) } : {}),
-    ...(requestId ? { requestId: asRuntimeRequestId(requestId) } : {}),
-    ...(Object.keys(providerRefs).length > 0 ? { providerRefs } : {}),
-  };
-}
-
 function eventRawSource(event: ProviderEvent): NonNullable<ProviderRuntimeEvent["raw"]>["source"] {
   return event.kind === "request" ? "codex.app-server.request" : "codex.app-server.notification";
 }
@@ -538,19 +450,19 @@ function mapItemLifecycle(
   canonicalThreadId: ThreadId,
   lifecycle: "item.started" | "item.updated" | "item.completed",
 ): ProviderRuntimeEvent | undefined {
-  const payload = asObject(event.payload);
-  const item = asObject(payload?.item);
-  const source = item ?? payload;
-  if (!source) {
+  const payload =
+    readPayload(EffectCodexSchema.V2ItemStartedNotification, event.payload) ??
+    readPayload(EffectCodexSchema.V2ItemCompletedNotification, event.payload);
+  const item = payload?.item;
+  if (!item) {
     return undefined;
   }
-
-  const itemType = toCanonicalItemType(source.type ?? source.kind);
+  const itemType = toCanonicalItemType(item.type);
   if (itemType === "unknown" && lifecycle !== "item.updated") {
     return undefined;
   }
 
-  const detail = itemDetail(source, payload ?? {});
+  const detail = itemDetail(item);
   const status =
     lifecycle === "item.started"
       ? "inProgress"
@@ -575,9 +487,6 @@ function mapToRuntimeEvents(
   event: ProviderEvent,
   canonicalThreadId: ThreadId,
 ): ReadonlyArray<ProviderRuntimeEvent> {
-  const payload = asObject(event.payload);
-  const turn = asObject(payload?.turn);
-
   if (event.kind === "error") {
     if (!event.message) {
       return [];
@@ -597,7 +506,10 @@ function mapToRuntimeEvents(
 
   if (event.kind === "request") {
     if (event.method === "item/tool/requestUserInput") {
-      const questions = toUserInputQuestions(payload);
+      const payload =
+        readPayload(EffectCodexSchema.ServerRequest__ToolRequestUserInputParams, event.payload) ??
+        readPayload(EffectCodexSchema.ToolRequestUserInputParams, event.payload);
+      const questions = payload ? toUserInputQuestions(payload.questions) : undefined;
       if (!questions) {
         return [];
       }
@@ -612,8 +524,48 @@ function mapToRuntimeEvents(
       ];
     }
 
-    const detail =
-      asString(payload?.command) ?? asString(payload?.reason) ?? asString(payload?.prompt);
+    const detail = (() => {
+      switch (event.method) {
+        case "item/commandExecution/requestApproval": {
+          const payload = readPayload(
+            EffectCodexSchema.ServerRequest__CommandExecutionRequestApprovalParams,
+            event.payload,
+          );
+          return payload?.command ?? payload?.reason ?? undefined;
+        }
+        case "item/fileChange/requestApproval": {
+          const payload = readPayload(
+            EffectCodexSchema.ServerRequest__FileChangeRequestApprovalParams,
+            event.payload,
+          );
+          return payload?.reason ?? undefined;
+        }
+        case "applyPatchApproval": {
+          const payload = readPayload(
+            EffectCodexSchema.ServerRequest__ApplyPatchApprovalParams,
+            event.payload,
+          );
+          return payload?.reason ?? undefined;
+        }
+        case "execCommandApproval": {
+          const payload = readPayload(
+            EffectCodexSchema.ServerRequest__ExecCommandApprovalParams,
+            event.payload,
+          );
+          return payload?.reason ?? payload?.command.join(" ");
+        }
+        case "item/tool/call": {
+          const payload = readPayload(
+            EffectCodexSchema.ServerRequest__DynamicToolCallParams,
+            event.payload,
+          );
+          return payload?.tool ?? undefined;
+        }
+        default:
+          return undefined;
+      }
+    })();
+
     return [
       {
         ...runtimeEventBase(event, canonicalThreadId),
@@ -628,7 +580,7 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "item/requestApproval/decision" && event.requestId) {
-    const decision = Schema.decodeUnknownSync(ProviderApprovalDecision)(payload?.decision);
+    const payload = readPayload(ApprovalDecisionPayload, event.payload);
     const requestType =
       event.requestKind !== undefined
         ? toRequestTypeFromKind(event.requestKind)
@@ -639,7 +591,7 @@ function mapToRuntimeEvents(
         type: "request.resolved",
         payload: {
           requestType,
-          ...(decision ? { decision } : {}),
+          ...(payload ? { decision: payload.decision } : {}),
           ...(event.payload !== undefined ? { resolution: event.payload } : {}),
         },
       },
@@ -699,9 +651,8 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "thread/started") {
-    const payloadThreadId = asString(asObject(payload?.thread)?.id);
-    const providerThreadId = payloadThreadId ?? asString(payload?.threadId);
-    if (!providerThreadId) {
+    const payload = readPayload(EffectCodexSchema.V2ThreadStartedNotification, event.payload);
+    if (!payload) {
       return [];
     }
     return [
@@ -709,7 +660,7 @@ function mapToRuntimeEvents(
         ...runtimeEventBase(event, canonicalThreadId),
         type: "thread.started",
         payload: {
-          providerThreadId,
+          providerThreadId: payload.thread.id,
         },
       },
     ];
@@ -722,6 +673,10 @@ function mapToRuntimeEvents(
     event.method === "thread/closed" ||
     event.method === "thread/compacted"
   ) {
+    const payload =
+      event.method === "thread/status/changed"
+        ? readPayload(EffectCodexSchema.V2ThreadStatusChangedNotification, event.payload)
+        : undefined;
     return [
       {
         type: "thread.state.changed",
@@ -734,7 +689,9 @@ function mapToRuntimeEvents(
                 ? "closed"
                 : event.method === "thread/compacted"
                   ? "compacted"
-                  : toThreadState(asObject(payload?.thread)?.state ?? payload?.state),
+                  : payload
+                    ? toThreadState(payload.status)
+                    : "active",
           ...(event.payload !== undefined ? { detail: event.payload } : {}),
         },
       },
@@ -742,21 +699,34 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "thread/name/updated") {
+    const payload = readPayload(EffectCodexSchema.V2ThreadNameUpdatedNotification, event.payload);
     return [
       {
         type: "thread.metadata.updated",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          ...(asString(payload?.threadName) ? { name: asString(payload?.threadName) } : {}),
-          ...(event.payload !== undefined ? { metadata: asObject(event.payload) } : {}),
+          ...(trimText(payload?.threadName) ? { name: trimText(payload?.threadName) } : {}),
+          ...(payload
+            ? {
+                metadata: {
+                  threadId: payload.threadId,
+                  ...(payload.threadName !== undefined && payload.threadName !== null
+                    ? { threadName: payload.threadName }
+                    : {}),
+                },
+              }
+            : {}),
         },
       },
     ];
   }
 
   if (event.method === "thread/tokenUsage/updated") {
-    const tokenUsage = asObject(payload?.tokenUsage);
-    const normalizedUsage = normalizeCodexTokenUsage(tokenUsage ?? event.payload);
+    const payload = readPayload(
+      EffectCodexSchema.V2ThreadTokenUsageUpdatedNotification,
+      event.payload,
+    );
+    const normalizedUsage = payload ? normalizeCodexTokenUsage(payload.tokenUsage) : undefined;
     if (!normalizedUsage) {
       return [];
     }
@@ -781,28 +751,23 @@ function mapToRuntimeEvents(
         ...runtimeEventBase(event, canonicalThreadId),
         turnId,
         type: "turn.started",
-        payload: {
-          ...(asString(turn?.model) ? { model: asString(turn?.model) } : {}),
-          ...(asString(turn?.effort) ? { effort: asString(turn?.effort) } : {}),
-        },
+        payload: {},
       },
     ];
   }
 
   if (event.method === "turn/completed") {
-    const errorMessage = asString(asObject(turn?.error)?.message);
+    const payload = readPayload(EffectCodexSchema.V2TurnCompletedNotification, event.payload);
+    if (!payload) {
+      return [];
+    }
+    const errorMessage = trimText(payload.turn.error?.message);
     return [
       {
         ...runtimeEventBase(event, canonicalThreadId),
         type: "turn.completed",
         payload: {
-          state: toTurnStatus(turn?.status),
-          ...(asString(turn?.stopReason) ? { stopReason: asString(turn?.stopReason) } : {}),
-          ...(turn?.usage !== undefined ? { usage: turn.usage } : {}),
-          ...(asObject(turn?.modelUsage) ? { modelUsage: asObject(turn?.modelUsage) } : {}),
-          ...(asNumber(turn?.totalCostUsd) !== undefined
-            ? { totalCostUsd: asNumber(turn?.totalCostUsd) }
-            : {}),
+          state: toTurnStatus(payload.turn.status),
           ...(errorMessage ? { errorMessage } : {}),
         },
       },
@@ -822,41 +787,37 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "turn/plan/updated") {
-    const steps = Array.isArray(payload?.plan) ? payload.plan : [];
+    const payload = readPayload(EffectCodexSchema.V2TurnPlanUpdatedNotification, event.payload);
+    if (!payload) {
+      return [];
+    }
     return [
       {
         ...runtimeEventBase(event, canonicalThreadId),
         type: "turn.plan.updated",
         payload: {
-          ...(asString(payload?.explanation)
-            ? { explanation: asString(payload?.explanation) }
-            : {}),
-          plan: steps
-            .map((entry) => asObject(entry))
-            .filter((entry): entry is Record<string, unknown> => entry !== undefined)
-            .map((entry) => ({
-              step: asString(entry.step) ?? "step",
-              status:
-                entry.status === "completed" || entry.status === "inProgress"
-                  ? entry.status
-                  : "pending",
-            })),
+          ...(trimText(payload.explanation) ? { explanation: trimText(payload.explanation) } : {}),
+          plan: payload.plan.map((step) => ({
+            step: trimText(step.step) ?? "step",
+            status:
+              step.status === "completed" || step.status === "inProgress" ? step.status : "pending",
+          })),
         },
       },
     ];
   }
 
   if (event.method === "turn/diff/updated") {
+    const payload = readPayload(EffectCodexSchema.V2TurnDiffUpdatedNotification, event.payload);
+    if (!payload) {
+      return [];
+    }
     return [
       {
         ...runtimeEventBase(event, canonicalThreadId),
         type: "turn.diff.updated",
         payload: {
-          unifiedDiff:
-            asString(payload?.unifiedDiff) ??
-            asString(payload?.diff) ??
-            asString(payload?.patch) ??
-            "",
+          unifiedDiff: payload.diff,
         },
       },
     ];
@@ -868,15 +829,14 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "item/completed") {
-    const payload = asObject(event.payload);
-    const item = asObject(payload?.item);
-    const source = item ?? payload;
-    if (!source) {
+    const payload = readPayload(EffectCodexSchema.V2ItemCompletedNotification, event.payload);
+    const item = payload?.item;
+    if (!item) {
       return [];
     }
-    const itemType = source ? toCanonicalItemType(source.type ?? source.kind) : "unknown";
+    const itemType = toCanonicalItemType(item.type);
     if (itemType === "plan") {
-      const detail = itemDetail(source, payload ?? {});
+      const detail = itemDetail(item);
       if (!detail) {
         return [];
       }
@@ -898,16 +858,22 @@ function mapToRuntimeEvents(
     event.method === "item/reasoning/summaryPartAdded" ||
     event.method === "item/commandExecution/terminalInteraction"
   ) {
-    const updated = mapItemLifecycle(event, canonicalThreadId, "item.updated");
-    return updated ? [updated] : [];
+    return [
+      {
+        ...runtimeEventBase(event, canonicalThreadId),
+        type: "item.updated",
+        payload: {
+          itemType:
+            event.method === "item/reasoning/summaryPartAdded" ? "reasoning" : "command_execution",
+          ...(event.payload !== undefined ? { data: event.payload } : {}),
+        },
+      },
+    ];
   }
 
   if (event.method === "item/plan/delta") {
-    const delta =
-      event.textDelta ??
-      asString(payload?.delta) ??
-      asString(payload?.text) ??
-      asString(asObject(payload?.content)?.text);
+    const payload = readPayload(EffectCodexSchema.V2PlanDeltaNotification, event.payload);
+    const delta = event.textDelta ?? payload?.delta;
     if (!delta || delta.length === 0) {
       return [];
     }
@@ -922,18 +888,9 @@ function mapToRuntimeEvents(
     ];
   }
 
-  if (
-    event.method === "item/agentMessage/delta" ||
-    event.method === "item/commandExecution/outputDelta" ||
-    event.method === "item/fileChange/outputDelta" ||
-    event.method === "item/reasoning/summaryTextDelta" ||
-    event.method === "item/reasoning/textDelta"
-  ) {
-    const delta =
-      event.textDelta ??
-      asString(payload?.delta) ??
-      asString(payload?.text) ??
-      asString(asObject(payload?.content)?.text);
+  if (event.method === "item/agentMessage/delta") {
+    const payload = readPayload(EffectCodexSchema.V2AgentMessageDeltaNotification, event.payload);
+    const delta = event.textDelta ?? payload?.delta;
     if (!delta || delta.length === 0) {
       return [];
     }
@@ -944,216 +901,207 @@ function mapToRuntimeEvents(
         payload: {
           streamKind: contentStreamKindFromMethod(event.method),
           delta,
-          ...(typeof payload?.contentIndex === "number"
-            ? { contentIndex: payload.contentIndex }
-            : {}),
-          ...(typeof payload?.summaryIndex === "number"
-            ? { summaryIndex: payload.summaryIndex }
-            : {}),
         },
       },
     ];
   }
 
-  if (event.method === "item/mcpToolCall/progress") {
+  if (event.method === "item/commandExecution/outputDelta") {
+    const payload = readPayload(
+      EffectCodexSchema.V2CommandExecutionOutputDeltaNotification,
+      event.payload,
+    );
+    const delta = event.textDelta ?? payload?.delta;
+    if (!delta || delta.length === 0) {
+      return [];
+    }
     return [
       {
         ...runtimeEventBase(event, canonicalThreadId),
-        type: "tool.progress",
+        type: "content.delta",
         payload: {
-          ...(asString(payload?.toolUseId) ? { toolUseId: asString(payload?.toolUseId) } : {}),
-          ...(asString(payload?.toolName) ? { toolName: asString(payload?.toolName) } : {}),
-          ...(asString(payload?.summary) ? { summary: asString(payload?.summary) } : {}),
-          ...(asNumber(payload?.elapsedSeconds) !== undefined
-            ? { elapsedSeconds: asNumber(payload?.elapsedSeconds) }
-            : {}),
+          streamKind: "command_output",
+          delta,
         },
       },
     ];
   }
 
-  if (event.method === "serverRequest/resolved") {
-    const requestType =
-      toRequestTypeFromResolvedPayload(payload) !== "unknown"
-        ? toRequestTypeFromResolvedPayload(payload)
-        : event.requestId && event.requestKind !== undefined
-          ? toRequestTypeFromKind(event.requestKind)
-          : "unknown";
+  if (event.method === "item/fileChange/outputDelta") {
+    const payload = readPayload(
+      EffectCodexSchema.V2FileChangeOutputDeltaNotification,
+      event.payload,
+    );
+    const delta = event.textDelta ?? payload?.delta;
+    if (!delta || delta.length === 0) {
+      return [];
+    }
     return [
       {
         ...runtimeEventBase(event, canonicalThreadId),
-        type: "request.resolved",
+        type: "content.delta",
         payload: {
-          requestType,
-          ...(event.payload !== undefined ? { resolution: event.payload } : {}),
+          streamKind: "file_change_output",
+          delta,
         },
       },
     ];
   }
 
-  if (event.method === "item/tool/requestUserInput/answered") {
+  if (event.method === "item/reasoning/summaryTextDelta") {
+    const payload = readPayload(
+      EffectCodexSchema.V2ReasoningSummaryTextDeltaNotification,
+      event.payload,
+    );
+    const delta = event.textDelta ?? payload?.delta;
+    if (!delta || delta.length === 0) {
+      return [];
+    }
     return [
       {
         ...runtimeEventBase(event, canonicalThreadId),
-        type: "user-input.resolved",
+        type: "content.delta",
         payload: {
-          answers: toCanonicalUserInputAnswers(
-            asObject(event.payload)?.answers as ProviderUserInputAnswers | undefined,
-          ),
+          streamKind: "reasoning_summary_text",
+          delta,
+          ...(payload ? { summaryIndex: payload.summaryIndex } : {}),
         },
       },
     ];
   }
 
-  if (event.method === "codex/event/task_started") {
-    const msg = codexEventMessage(payload);
-    const taskId = asString(payload?.id) ?? asString(msg?.turn_id);
-    if (!taskId) {
+  if (event.method === "item/reasoning/textDelta") {
+    const payload = readPayload(EffectCodexSchema.V2ReasoningTextDeltaNotification, event.payload);
+    const delta = event.textDelta ?? payload?.delta;
+    if (!delta || delta.length === 0) {
       return [];
     }
     return [
       {
-        ...codexEventBase(event, canonicalThreadId),
-        type: "task.started",
+        ...runtimeEventBase(event, canonicalThreadId),
+        type: "content.delta",
         payload: {
-          taskId: asRuntimeTaskId(taskId),
-          ...(asString(msg?.collaboration_mode_kind)
-            ? { taskType: asString(msg?.collaboration_mode_kind) }
-            : {}),
+          streamKind: "reasoning_text",
+          delta,
+          ...(payload ? { contentIndex: payload.contentIndex } : {}),
         },
       },
     ];
   }
 
-  if (event.method === "codex/event/task_complete") {
-    const msg = codexEventMessage(payload);
-    const taskId = asString(payload?.id) ?? asString(msg?.turn_id);
-    const proposedPlanMarkdown = extractProposedPlanMarkdown(asString(msg?.last_agent_message));
-    if (!taskId) {
-      if (!proposedPlanMarkdown) {
-        return [];
-      }
-      return [
-        {
-          ...codexEventBase(event, canonicalThreadId),
-          type: "turn.proposed.completed",
-          payload: {
-            planMarkdown: proposedPlanMarkdown,
-          },
-        },
-      ];
+  if (event.method === "item/mcpToolCall/progress") {
+    const payload = readPayload(EffectCodexSchema.V2McpToolCallProgressNotification, event.payload);
+    if (!payload) {
+      return [];
     }
-    const events: ProviderRuntimeEvent[] = [
+    return [
       {
-        ...codexEventBase(event, canonicalThreadId),
-        type: "task.completed",
+        ...runtimeEventBase(event, canonicalThreadId),
+        type: "tool.progress",
         payload: {
-          taskId: asRuntimeTaskId(taskId),
-          status: "completed",
-          ...(asString(msg?.last_agent_message)
-            ? { summary: asString(msg?.last_agent_message) }
-            : {}),
+          summary: payload.message,
         },
       },
     ];
-    if (proposedPlanMarkdown) {
-      events.push({
-        ...codexEventBase(event, canonicalThreadId),
-        type: "turn.proposed.completed",
-        payload: {
-          planMarkdown: proposedPlanMarkdown,
-        },
-      });
-    }
-    return events;
   }
 
-  if (event.method === "codex/event/agent_reasoning") {
-    const msg = codexEventMessage(payload);
-    const taskId = asString(payload?.id);
-    const description = asString(msg?.text);
-    if (!taskId || !description) {
+  if (event.method === "serverRequest/resolved") {
+    const payload = readPayload(
+      EffectCodexSchema.V2ServerRequestResolvedNotification,
+      event.payload,
+    );
+    if (!payload) {
       return [];
     }
+    const requestType = toRequestTypeFromKind(event.requestKind);
     return [
       {
-        ...codexEventBase(event, canonicalThreadId),
-        type: "task.progress",
+        ...runtimeEventBase(event, canonicalThreadId),
+        type: "request.resolved",
         payload: {
-          taskId: asRuntimeTaskId(taskId),
-          description,
+          requestType,
+          ...(event.payload !== undefined ? { resolution: event.payload } : {}),
         },
       },
     ];
   }
 
-  if (event.method === "codex/event/reasoning_content_delta") {
-    const msg = codexEventMessage(payload);
-    const delta = asString(msg?.delta);
-    if (!delta) {
+  if (event.method === "item/tool/requestUserInput/answered") {
+    const payload = readPayload(EffectCodexSchema.ToolRequestUserInputResponse, event.payload);
+    if (!payload) {
       return [];
     }
     return [
       {
-        ...codexEventBase(event, canonicalThreadId),
-        type: "content.delta",
+        ...runtimeEventBase(event, canonicalThreadId),
+        type: "user-input.resolved",
         payload: {
-          streamKind:
-            asNumber(msg?.summary_index) !== undefined
-              ? "reasoning_summary_text"
-              : "reasoning_text",
-          delta,
-          ...(asNumber(msg?.summary_index) !== undefined
-            ? { summaryIndex: asNumber(msg?.summary_index) }
-            : {}),
+          answers: toCanonicalUserInputAnswers(payload.answers),
         },
       },
     ];
   }
 
   if (event.method === "model/rerouted") {
+    const payload = readPayload(EffectCodexSchema.V2ModelReroutedNotification, event.payload);
+    if (!payload) {
+      return [];
+    }
     return [
       {
         type: "model.rerouted",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          fromModel: asString(payload?.fromModel) ?? "unknown",
-          toModel: asString(payload?.toModel) ?? "unknown",
-          reason: asString(payload?.reason) ?? "unknown",
+          fromModel: payload.fromModel,
+          toModel: payload.toModel,
+          reason: payload.reason,
         },
       },
     ];
   }
 
   if (event.method === "deprecationNotice") {
+    const payload = readPayload(EffectCodexSchema.V2DeprecationNoticeNotification, event.payload);
+    if (!payload) {
+      return [];
+    }
     return [
       {
         type: "deprecation.notice",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          summary: asString(payload?.summary) ?? "Deprecation notice",
-          ...(asString(payload?.details) ? { details: asString(payload?.details) } : {}),
+          summary: payload.summary,
+          ...(trimText(payload.details) ? { details: trimText(payload.details) } : {}),
         },
       },
     ];
   }
 
   if (event.method === "configWarning") {
+    const payload = readPayload(EffectCodexSchema.V2ConfigWarningNotification, event.payload);
+    if (!payload) {
+      return [];
+    }
     return [
       {
         type: "config.warning",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          summary: asString(payload?.summary) ?? "Configuration warning",
-          ...(asString(payload?.details) ? { details: asString(payload?.details) } : {}),
-          ...(asString(payload?.path) ? { path: asString(payload?.path) } : {}),
-          ...(payload?.range !== undefined ? { range: payload.range } : {}),
+          summary: payload.summary,
+          ...(trimText(payload.details) ? { details: trimText(payload.details) } : {}),
+          ...(trimText(payload.path) ? { path: trimText(payload.path) } : {}),
+          ...(payload.range !== undefined && payload.range !== null
+            ? { range: payload.range }
+            : {}),
         },
       },
     ];
   }
 
   if (event.method === "account/updated") {
+    if (!readPayload(EffectCodexSchema.V2AccountUpdatedNotification, event.payload)) {
+      return [];
+    }
     return [
       {
         type: "account.updated",
@@ -1166,6 +1114,9 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "account/rateLimits/updated") {
+    if (!readPayload(EffectCodexSchema.V2AccountRateLimitsUpdatedNotification, event.payload)) {
+      return [];
+    }
     return [
       {
         type: "account.rate-limits.updated",
@@ -1178,58 +1129,86 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "mcpServer/oauthLogin/completed") {
+    const payload = readPayload(
+      EffectCodexSchema.V2McpServerOauthLoginCompletedNotification,
+      event.payload,
+    );
+    if (!payload) {
+      return [];
+    }
     return [
       {
         type: "mcp.oauth.completed",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          success: payload?.success === true,
-          ...(asString(payload?.name) ? { name: asString(payload?.name) } : {}),
-          ...(asString(payload?.error) ? { error: asString(payload?.error) } : {}),
+          success: payload.success,
+          name: payload.name,
+          ...(trimText(payload.error) ? { error: trimText(payload.error) } : {}),
         },
       },
     ];
   }
 
   if (event.method === "thread/realtime/started") {
-    const realtimeSessionId = asString(payload?.realtimeSessionId);
+    const payload = readPayload(
+      EffectCodexSchema.V2ThreadRealtimeStartedNotification,
+      event.payload,
+    );
+    if (!payload) {
+      return [];
+    }
     return [
       {
         type: "thread.realtime.started",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          realtimeSessionId,
+          realtimeSessionId: payload.realtimeSessionId ?? undefined,
         },
       },
     ];
   }
 
   if (event.method === "thread/realtime/itemAdded") {
+    const payload = readPayload(
+      EffectCodexSchema.V2ThreadRealtimeItemAddedNotification,
+      event.payload,
+    );
+    if (!payload) {
+      return [];
+    }
     return [
       {
         type: "thread.realtime.item-added",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          item: event.payload ?? {},
+          item: payload.item,
         },
       },
     ];
   }
 
   if (event.method === "thread/realtime/outputAudio/delta") {
+    const payload = readPayload(
+      EffectCodexSchema.V2ThreadRealtimeOutputAudioDeltaNotification,
+      event.payload,
+    );
+    if (!payload) {
+      return [];
+    }
     return [
       {
         type: "thread.realtime.audio.delta",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          audio: event.payload ?? {},
+          audio: payload.audio,
         },
       },
     ];
   }
 
   if (event.method === "thread/realtime/error") {
-    const message = asString(payload?.message) ?? event.message ?? "Realtime error";
+    const payload = readPayload(EffectCodexSchema.V2ThreadRealtimeErrorNotification, event.payload);
+    const message = payload?.message ?? event.message ?? "Realtime error";
     return [
       {
         type: "thread.realtime.error",
@@ -1242,20 +1221,24 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "thread/realtime/closed") {
+    const payload = readPayload(
+      EffectCodexSchema.V2ThreadRealtimeClosedNotification,
+      event.payload,
+    );
     return [
       {
         type: "thread.realtime.closed",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          reason: event.message,
+          reason: payload?.reason ?? event.message,
         },
       },
     ];
   }
 
   if (event.method === "error") {
-    const message =
-      asString(asObject(payload?.error)?.message) ?? event.message ?? "Provider runtime error";
+    const payload = readPayload(EffectCodexSchema.V2ErrorNotification, event.payload);
+    const message = payload?.error.message ?? event.message ?? "Provider runtime error";
     const willRetry = payload?.willRetry === true;
     return [
       {
@@ -1296,6 +1279,9 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "windows/worldWritableWarning") {
+    if (!readPayload(EffectCodexSchema.V2WindowsWorldWritableWarningNotification, event.payload)) {
+      return [];
+    }
     return [
       {
         type: "runtime.warning",
@@ -1309,8 +1295,13 @@ function mapToRuntimeEvents(
   }
 
   if (event.method === "windowsSandbox/setupCompleted") {
-    const payloadRecord = asObject(event.payload);
-    const success = payloadRecord?.success;
+    const payload = readPayload(
+      EffectCodexSchema.V2WindowsSandboxSetupCompletedNotification,
+      event.payload,
+    );
+    if (!payload) {
+      return [];
+    }
     const successMessage = event.message ?? "Windows sandbox setup completed";
     const failureMessage = event.message ?? "Windows sandbox setup failed";
 
@@ -1319,12 +1310,12 @@ function mapToRuntimeEvents(
         type: "session.state.changed",
         ...runtimeEventBase(event, canonicalThreadId),
         payload: {
-          state: success === false ? "error" : "ready",
-          reason: success === false ? failureMessage : successMessage,
+          state: payload.success === false ? "error" : "ready",
+          reason: payload.success === false ? failureMessage : successMessage,
           ...(event.payload !== undefined ? { detail: event.payload } : {}),
         },
       },
-      ...(success === false
+      ...(payload.success === false
         ? [
             {
               type: "runtime.warning" as const,
@@ -1342,10 +1333,22 @@ function mapToRuntimeEvents(
   return [];
 }
 
-const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
+/**
+ * Build a Codex provider adapter bound to a specific `CodexSettings` payload.
+ *
+ * The adapter is a captured closure over `codexConfig` — the `binaryPath` and
+ * `homePath` are read from that payload, not from `ServerSettingsService`.
+ * This is what makes multi-instance routing possible: each `ProviderInstance`
+ * in the registry owns its own closure with its own config, so two Codex
+ * instances with different `homePath`s cannot step on each other.
+ */
+export const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
+  codexConfig: CodexSettings,
   options?: CodexAdapterLiveOptions,
 ) {
+  const boundInstanceId = options?.instanceId ?? ProviderInstanceId.make("codex");
   const fileSystem = yield* FileSystem.FileSystem;
+  const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const serverConfig = yield* Effect.service(ServerConfig);
   const nativeEventLogger =
     options?.nativeEventLogger ??
@@ -1354,78 +1357,114 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
           stream: "native",
         })
       : undefined);
+  const managedNativeEventLogger =
+    options?.nativeEventLogger === undefined ? nativeEventLogger : undefined;
+  const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
+  const sessions = new Map<ThreadId, CodexAdapterSessionContext>();
 
-  const acquireManager = Effect.fn("acquireManager")(function* () {
-    if (options?.manager) {
-      return options.manager;
-    }
-    const services = yield* Effect.context<never>();
-    return options?.makeManager?.(services) ?? new CodexAppServerManager(services);
-  });
+  const startSession: CodexAdapterShape["startSession"] = (input) =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        if (input.provider !== undefined && input.provider !== PROVIDER) {
+          return yield* new ProviderAdapterValidationError({
+            provider: PROVIDER,
+            operation: "startSession",
+            issue: `Expected provider '${PROVIDER}' but received '${input.provider}'.`,
+          });
+        }
 
-  const manager = yield* Effect.acquireRelease(acquireManager(), (manager) =>
-    Effect.sync(() => {
-      try {
-        manager.stopAll();
-      } catch {
-        // Finalizers should never fail and block shutdown.
-      }
-    }),
-  );
-  const serverSettingsService = yield* ServerSettingsService;
+        const existing = sessions.get(input.threadId);
+        if (existing && !existing.stopped) {
+          yield* Effect.suspend(() => stopSessionInternal(existing));
+        }
 
-  const startSession: CodexAdapterShape["startSession"] = Effect.fn("startSession")(
-    function* (input) {
-      if (input.provider !== undefined && input.provider !== PROVIDER) {
-        return yield* new ProviderAdapterValidationError({
-          provider: PROVIDER,
-          operation: "startSession",
-          issue: `Expected provider '${PROVIDER}' but received '${input.provider}'.`,
-        });
-      }
+        const runtimeInput: CodexSessionRuntimeOptions = {
+          threadId: input.threadId,
+          providerInstanceId: boundInstanceId,
+          cwd: input.cwd ?? process.cwd(),
+          binaryPath: codexConfig.binaryPath,
+          ...(options?.environment ? { environment: options.environment } : {}),
+          ...(codexConfig.homePath ? { homePath: codexConfig.homePath } : {}),
+          ...(isCodexResumeCursorSchema(input.resumeCursor)
+            ? { resumeCursor: input.resumeCursor }
+            : {}),
+          runtimeMode: input.runtimeMode,
+          ...(input.modelSelection?.instanceId === boundInstanceId
+            ? { model: input.modelSelection.model }
+            : {}),
+          ...(input.modelSelection?.instanceId === boundInstanceId &&
+          getModelSelectionBooleanOptionValue(input.modelSelection, "fastMode") === true
+            ? { serviceTier: "fast" }
+            : {}),
+        };
+        const sessionScope = yield* Scope.make("sequential");
+        let sessionScopeTransferred = false;
+        yield* Effect.addFinalizer(() =>
+          sessionScopeTransferred ? Effect.void : Scope.close(sessionScope, Exit.void),
+        );
+        const createRuntime = options?.makeRuntime ?? makeCodexSessionRuntime;
+        const runtime = yield* createRuntime(runtimeInput).pipe(
+          Effect.provideService(Scope.Scope, sessionScope),
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, childProcessSpawner),
+          Effect.mapError(
+            (cause) =>
+              new ProviderAdapterProcessError({
+                provider: PROVIDER,
+                threadId: input.threadId,
+                detail: cause.message,
+                cause,
+              }),
+          ),
+        );
+
+        const eventFiber = yield* Stream.runForEach(runtime.events, (event) =>
+          Effect.gen(function* () {
+            yield* writeNativeEvent(event);
+            const runtimeEvents = mapToRuntimeEvents(event, event.threadId);
+            if (runtimeEvents.length === 0) {
+              yield* Effect.logDebug("ignoring unhandled Codex provider event", {
+                method: event.method,
+                threadId: event.threadId,
+                turnId: event.turnId,
+                itemId: event.itemId,
+              });
+              return;
+            }
+            yield* Queue.offerAll(runtimeEventQueue, runtimeEvents);
+          }),
+        ).pipe(Effect.forkChild);
+
+        const started = yield* runtime.start().pipe(
+          Effect.mapError(
+            (cause) =>
+              new ProviderAdapterProcessError({
+                provider: PROVIDER,
+                threadId: input.threadId,
+                detail: cause.message,
+                cause,
+              }),
+          ),
+          Effect.onError(() =>
+            runtime.close.pipe(
+              Effect.andThen(Effect.ignore(Scope.close(sessionScope, Exit.void))),
+              Effect.andThen(Fiber.interrupt(eventFiber)),
+              Effect.ignore,
+            ),
+          ),
+        );
 
-      const codexSettings = yield* serverSettingsService.getSettings.pipe(
-        Effect.map((settings) => settings.providers.codex),
-        Effect.mapError(
-          (error) =>
-            new ProviderAdapterProcessError({
-              provider: PROVIDER,
-              threadId: input.threadId,
-              detail: error.message,
-              cause: error,
-            }),
-        ),
-      );
-      const binaryPath = codexSettings.binaryPath;
-      const homePath = codexSettings.homePath;
-      const managerInput: CodexAppServerStartSessionInput = {
-        threadId: input.threadId,
-        provider: "codex",
-        ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
-        ...(input.resumeCursor !== undefined ? { resumeCursor: input.resumeCursor } : {}),
-        runtimeMode: input.runtimeMode,
-        binaryPath,
-        ...(homePath ? { homePath } : {}),
-        ...(input.modelSelection?.provider === "codex"
-          ? { model: input.modelSelection.model }
-          : {}),
-        ...(input.modelSelection?.provider === "codex" && input.modelSelection.options?.fastMode
-          ? { serviceTier: "fast" }
-          : {}),
-      };
+        sessions.set(input.threadId, {
+          threadId: input.threadId,
+          scope: sessionScope,
+          runtime,
+          eventFiber,
+          stopped: false,
+        });
+        sessionScopeTransferred = true;
 
-      return yield* Effect.tryPromise({
-        try: () => manager.startSession(managerInput),
-        catch: (cause) =>
-          new ProviderAdapterProcessError({
-            provider: PROVIDER,
-            threadId: input.threadId,
-            detail: `Failed to start Codex adapter session: ${cause instanceof Error ? cause.message : String(cause)}.`,
-            cause,
-          }),
-      });
-    },
-  );
+        return started;
+      }),
+    );
 
   const resolveAttachment = Effect.fn("resolveAttachment")(function* (
     input: ProviderSendTurnInput,
@@ -1436,11 +1475,11 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
       attachment,
     });
     if (!attachmentPath) {
-      return yield* toRequestError(
-        input.threadId,
-        "turn/start",
-        new Error(`Invalid attachment id '${attachment.id}'.`),
-      );
+      return yield* new ProviderAdapterRequestError({
+        provider: PROVIDER,
+        method: "turn/start",
+        detail: `Invalid attachment id '${attachment.id}'.`,
+      });
     }
     const bytes = yield* fileSystem.readFile(attachmentPath).pipe(
       Effect.mapError(
@@ -1466,48 +1505,62 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
       { concurrency: 1 },
     );
 
-    return yield* Effect.tryPromise({
-      try: () => {
-        const managerInput = {
-          threadId: input.threadId,
-          ...(input.input !== undefined ? { input: input.input } : {}),
-          ...(input.modelSelection?.provider === "codex"
-            ? { model: input.modelSelection.model }
-            : {}),
-          ...(input.modelSelection?.provider === "codex" &&
-          input.modelSelection.options?.reasoningEffort !== undefined
-            ? { effort: input.modelSelection.options.reasoningEffort }
-            : {}),
-          ...(input.modelSelection?.provider === "codex" && input.modelSelection.options?.fastMode
-            ? { serviceTier: "fast" }
-            : {}),
-          ...(input.interactionMode !== undefined
-            ? { interactionMode: input.interactionMode }
-            : {}),
-          ...(codexAttachments.length > 0 ? { attachments: codexAttachments } : {}),
-        };
-        return manager.sendTurn(managerInput);
-      },
-      catch: (cause) => toRequestError(input.threadId, "turn/start", cause),
-    }).pipe(
-      Effect.map((result) => ({
-        ...result,
-        threadId: input.threadId,
-      })),
-    );
+    const session = yield* requireSession(input.threadId);
+    const reasoningEffort =
+      input.modelSelection?.instanceId === boundInstanceId
+        ? getModelSelectionStringOptionValue(input.modelSelection, "reasoningEffort")
+        : undefined;
+    const fastMode =
+      input.modelSelection?.instanceId === boundInstanceId
+        ? getModelSelectionBooleanOptionValue(input.modelSelection, "fastMode")
+        : undefined;
+    return yield* session.runtime
+      .sendTurn({
+        ...(input.input !== undefined ? { input: input.input } : {}),
+        ...(input.modelSelection?.instanceId === boundInstanceId
+          ? { model: input.modelSelection.model }
+          : {}),
+        ...(reasoningEffort
+          ? {
+              effort: reasoningEffort as EffectCodexSchema.V2TurnStartParams__ReasoningEffort,
+            }
+          : {}),
+        ...(fastMode === true ? { serviceTier: "fast" } : {}),
+        ...(input.interactionMode !== undefined ? { interactionMode: input.interactionMode } : {}),
+        ...(codexAttachments.length > 0 ? { attachments: codexAttachments } : {}),
+      })
+      .pipe(Effect.mapError((cause) => mapCodexRuntimeError(input.threadId, "turn/start", cause)));
+  });
+
+  const requireSession = Effect.fn("requireSession")(function* (threadId: ThreadId) {
+    const session = sessions.get(threadId);
+    if (!session || session.stopped) {
+      return yield* new ProviderAdapterSessionNotFoundError({
+        provider: PROVIDER,
+        threadId,
+      });
+    }
+    return session;
   });
 
   const interruptTurn: CodexAdapterShape["interruptTurn"] = (threadId, turnId) =>
-    Effect.tryPromise({
-      try: () => manager.interruptTurn(threadId, turnId),
-      catch: (cause) => toRequestError(threadId, "turn/interrupt", cause),
-    });
+    requireSession(threadId).pipe(
+      Effect.flatMap((session) => session.runtime.interruptTurn(turnId)),
+      Effect.mapError((cause) =>
+        cause._tag === "ProviderAdapterSessionNotFoundError"
+          ? cause
+          : mapCodexRuntimeError(threadId, "turn/interrupt", cause),
+      ),
+    );
 
   const readThread: CodexAdapterShape["readThread"] = (threadId) =>
-    Effect.tryPromise({
-      try: () => manager.readThread(threadId),
-      catch: (cause) => toRequestError(threadId, "thread/read", cause),
-    }).pipe(
+    requireSession(threadId).pipe(
+      Effect.flatMap((session) => session.runtime.readThread),
+      Effect.mapError((cause) =>
+        cause._tag === "ProviderAdapterSessionNotFoundError"
+          ? cause
+          : mapCodexRuntimeError(threadId, "thread/read", cause),
+      ),
       Effect.map((snapshot) => ({
         threadId,
         turns: snapshot.turns,
@@ -1525,10 +1578,13 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
       );
     }
 
-    return Effect.tryPromise({
-      try: () => manager.rollbackThread(threadId, numTurns),
-      catch: (cause) => toRequestError(threadId, "thread/rollback", cause),
-    }).pipe(
+    return requireSession(threadId).pipe(
+      Effect.flatMap((session) => session.runtime.rollbackThread(numTurns)),
+      Effect.mapError((cause) =>
+        cause._tag === "ProviderAdapterSessionNotFoundError"
+          ? cause
+          : mapCodexRuntimeError(threadId, "thread/rollback", cause),
+      ),
       Effect.map((snapshot) => ({
         threadId,
         turns: snapshot.turns,
@@ -1537,38 +1593,28 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
   };
 
   const respondToRequest: CodexAdapterShape["respondToRequest"] = (threadId, requestId, decision) =>
-    Effect.tryPromise({
-      try: () => manager.respondToRequest(threadId, requestId, decision),
-      catch: (cause) => toRequestError(threadId, "item/requestApproval/decision", cause),
-    });
+    requireSession(threadId).pipe(
+      Effect.flatMap((session) => session.runtime.respondToRequest(requestId, decision)),
+      Effect.mapError((cause) =>
+        cause._tag === "ProviderAdapterSessionNotFoundError"
+          ? cause
+          : mapCodexRuntimeError(threadId, "item/requestApproval/decision", cause),
+      ),
+    );
 
   const respondToUserInput: CodexAdapterShape["respondToUserInput"] = (
     threadId,
     requestId,
     answers,
   ) =>
-    Effect.tryPromise({
-      try: () => manager.respondToUserInput(threadId, requestId, answers),
-      catch: (cause) => toRequestError(threadId, "item/tool/requestUserInput", cause),
-    });
-
-  const stopSession: CodexAdapterShape["stopSession"] = (threadId) =>
-    Effect.sync(() => {
-      manager.stopSession(threadId);
-    });
-
-  const listSessions: CodexAdapterShape["listSessions"] = () =>
-    Effect.sync(() => manager.listSessions());
-
-  const hasSession: CodexAdapterShape["hasSession"] = (threadId) =>
-    Effect.sync(() => manager.hasSession(threadId));
-
-  const stopAll: CodexAdapterShape["stopAll"] = () =>
-    Effect.sync(() => {
-      manager.stopAll();
-    });
-
-  const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
+    requireSession(threadId).pipe(
+      Effect.flatMap((session) => session.runtime.respondToUserInput(requestId, answers)),
+      Effect.mapError((cause) =>
+        cause._tag === "ProviderAdapterSessionNotFoundError"
+          ? cause
+          : mapCodexRuntimeError(threadId, "item/tool/requestUserInput", cause),
+      ),
+    );
 
   const writeNativeEvent = Effect.fn("writeNativeEvent")(function* (event: ProviderEvent) {
     if (!nativeEventLogger) {
@@ -1577,38 +1623,51 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
     yield* nativeEventLogger.write(event, event.threadId);
   });
 
-  const registerListener = Effect.fn("registerListener")(function* () {
-    const services = yield* Effect.context<never>();
-    const listenerEffect = Effect.fn("listener")(function* (event: ProviderEvent) {
-      yield* writeNativeEvent(event);
-      const runtimeEvents = mapToRuntimeEvents(event, event.threadId);
-      if (runtimeEvents.length === 0) {
-        yield* Effect.logDebug("ignoring unhandled Codex provider event", {
-          method: event.method,
-          threadId: event.threadId,
-          turnId: event.turnId,
-          itemId: event.itemId,
-        });
+  const stopSessionInternal = Effect.fn("stopSessionInternal")(function* (
+    session: CodexAdapterSessionContext,
+  ) {
+    if (session.stopped) {
+      return;
+    }
+    session.stopped = true;
+    sessions.delete(session.threadId);
+    yield* session.runtime.close.pipe(Effect.ignore);
+    yield* Effect.ignore(Scope.close(session.scope, Exit.void));
+    yield* Fiber.interrupt(session.eventFiber).pipe(Effect.ignore);
+  });
+
+  const stopSession: CodexAdapterShape["stopSession"] = (threadId) =>
+    Effect.gen(function* () {
+      const session = sessions.get(threadId);
+      if (!session) {
         return;
       }
-      yield* Queue.offerAll(runtimeEventQueue, runtimeEvents);
+      yield* stopSessionInternal(session);
     });
-    const listener = (event: ProviderEvent) =>
-      listenerEffect(event).pipe(Effect.runPromiseWith(services));
-    manager.on("event", listener);
-    return listener;
-  });
 
-  const unregisterListener = Effect.fn("unregisterListener")(function* (
-    listener: (event: ProviderEvent) => Promise<void>,
-  ) {
-    yield* Effect.sync(() => {
-      manager.off("event", listener);
-    });
-    yield* Queue.shutdown(runtimeEventQueue);
-  });
+  const listSessions: CodexAdapterShape["listSessions"] = () =>
+    Effect.forEach(
+      Array.from(sessions.values()).filter((session) => !session.stopped),
+      (session) => session.runtime.getSession,
+      { concurrency: 1 },
+    );
 
-  yield* Effect.acquireRelease(registerListener(), unregisterListener);
+  const hasSession: CodexAdapterShape["hasSession"] = (threadId) =>
+    Effect.succeed(Boolean(sessions.get(threadId) && !sessions.get(threadId)?.stopped));
+
+  const stopAll: CodexAdapterShape["stopAll"] = () =>
+    Effect.forEach(Array.from(sessions.values()), stopSessionInternal, {
+      concurrency: 1,
+      discard: true,
+    }).pipe(Effect.asVoid);
+
+  yield* Effect.acquireRelease(Effect.void, () =>
+    stopAll().pipe(
+      Effect.andThen(Queue.shutdown(runtimeEventQueue)),
+      Effect.andThen(managedNativeEventLogger?.close() ?? Effect.void),
+      Effect.ignore,
+    ),
+  );
 
   return {
     provider: PROVIDER,
@@ -1632,8 +1691,9 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
   } satisfies CodexAdapterShape;
 });
 
-export const CodexAdapterLive = Layer.effect(CodexAdapter, makeCodexAdapter());
-
-export function makeCodexAdapterLive(options?: CodexAdapterLiveOptions) {
-  return Layer.effect(CodexAdapter, makeCodexAdapter(options));
-}
+// NOTE: the old `CodexAdapterLive` / `makeCodexAdapterLive` singleton Layer
+// exports have been removed as part of the per-instance-driver refactor.
+// `makeCodexAdapter(codexConfig, options?)` is now invoked directly by
+// `CodexDriver.create()` for each configured instance; downstream consumers
+// (server bootstrap, integration harness, this module's tests) will be
+// migrated to the registry in a follow-up pass.
diff --git a/apps/server/src/provider/Layers/CodexProvider.ts b/apps/server/src/provider/Layers/CodexProvider.ts
index 421621c9699..178450fb7fd 100644
--- a/apps/server/src/provider/Layers/CodexProvider.ts
+++ b/apps/server/src/provider/Layers/CodexProvider.ts
@@ -1,372 +1,433 @@
-import * as OS from "node:os";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Types from "effect/Types";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import * as CodexClient from "effect-codex-app-server/client";
+import * as CodexSchema from "effect-codex-app-server/schema";
+import * as CodexErrors from "effect-codex-app-server/errors";
+
 import type {
-  ModelCapabilities,
   CodexSettings,
   ServerProvider,
+  ServerProviderState,
+  ModelCapabilities,
   ServerProviderModel,
-  ServerProviderAuth,
   ServerProviderSkill,
-  ServerProviderState,
 } from "@t3tools/contracts";
-import {
-  Cache,
-  Duration,
-  Effect,
-  Equal,
-  FileSystem,
-  Layer,
-  Option,
-  Path,
-  Result,
-  Stream,
-} from "effect";
-import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { ServerSettingsError } from "@t3tools/contracts";
 
+import { createModelCapabilities } from "@t3tools/shared/model";
 import {
+  AUTH_PROBE_TIMEOUT_MS,
   buildServerProvider,
-  DEFAULT_TIMEOUT_MS,
-  detailFromResult,
-  extractAuthBoolean,
-  isCommandMissingCause,
-  parseGenericCliVersion,
-  providerModelsFromSettings,
-  spawnAndCollect,
-  type CommandResult,
-} from "../providerSnapshot";
-import { makeManagedServerProvider } from "../makeManagedServerProvider";
-import {
-  formatCodexCliUpgradeMessage,
-  isCodexCliVersionSupported,
-  parseCodexCliVersion,
-} from "../codexCliVersion";
-import {
-  adjustCodexModelsForAccount,
-  codexAuthSubLabel,
-  codexAuthSubType,
-  type CodexAccountSnapshot,
-} from "../codexAccount";
-import { probeCodexDiscovery } from "../codexAppServer";
-import { CodexProvider } from "../Services/CodexProvider";
-import { ServerSettingsService } from "../../serverSettings";
-import { ServerSettingsError } from "@t3tools/contracts";
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+import { expandHomePath } from "../../pathExpansion.ts";
+import packageJson from "../../../package.json" with { type: "json" };
+const isCodexAppServerSpawnError = Schema.is(CodexErrors.CodexAppServerSpawnError);
+
+const CODEX_PRESENTATION = {
+  displayName: "Codex",
+  showInteractionModeToggle: true,
+} as const;
+
+export interface CodexAppServerProviderSnapshot {
+  readonly account: CodexSchema.V2GetAccountResponse;
+  readonly version: string | undefined;
+  readonly models: ReadonlyArray<ServerProviderModel>;
+  readonly skills: ReadonlyArray<ServerProviderSkill>;
+}
 
-const DEFAULT_CODEX_MODEL_CAPABILITIES: ModelCapabilities = {
-  reasoningEffortLevels: [
-    { value: "xhigh", label: "Extra High" },
-    { value: "high", label: "High", isDefault: true },
-    { value: "medium", label: "Medium" },
-    { value: "low", label: "Low" },
-  ],
-  supportsFastMode: true,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
+const REASONING_EFFORT_LABELS: Record<CodexSchema.V2ModelListResponse__ReasoningEffort, string> = {
+  none: "None",
+  minimal: "Minimal",
+  low: "Low",
+  medium: "Medium",
+  high: "High",
+  xhigh: "Extra High",
 };
 
-const PROVIDER = "codex" as const;
-const OPENAI_AUTH_PROVIDERS = new Set(["openai"]);
-const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = [
-  {
-    slug: "gpt-5.4",
-    name: "GPT-5.4",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "xhigh", label: "Extra High" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "medium", label: "Medium" },
-        { value: "low", label: "Low" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-  {
-    slug: "gpt-5.4-mini",
-    name: "GPT-5.4 Mini",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "xhigh", label: "Extra High" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "medium", label: "Medium" },
-        { value: "low", label: "Low" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-  {
-    slug: "gpt-5.3-codex",
-    name: "GPT-5.3 Codex",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "xhigh", label: "Extra High" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "medium", label: "Medium" },
-        { value: "low", label: "Low" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-  {
-    slug: "gpt-5.3-codex-spark",
-    name: "GPT-5.3 Codex Spark",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "xhigh", label: "Extra High" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "medium", label: "Medium" },
-        { value: "low", label: "Low" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-  {
-    slug: "gpt-5.2-codex",
-    name: "GPT-5.2 Codex",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "xhigh", label: "Extra High" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "medium", label: "Medium" },
-        { value: "low", label: "Low" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-  {
-    slug: "gpt-5.2",
-    name: "GPT-5.2",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "xhigh", label: "Extra High" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "medium", label: "Medium" },
-        { value: "low", label: "Low" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-];
-
-export function getCodexModelCapabilities(model: string | null | undefined): ModelCapabilities {
-  const slug = model?.trim();
-  return (
-    BUILT_IN_MODELS.find((candidate) => candidate.slug === slug)?.capabilities ??
-    DEFAULT_CODEX_MODEL_CAPABILITIES
+function codexAccountAuthLabel(account: CodexSchema.V2GetAccountResponse["account"]) {
+  if (!account) return undefined;
+  if (account.type === "apiKey") return "OpenAI API Key";
+  if (account.type === "amazonBedrock") return "Amazon Bedrock";
+  if (account.type !== "chatgpt") return undefined;
+
+  switch (account.planType) {
+    case "free":
+      return "ChatGPT Free Subscription";
+    case "go":
+      return "ChatGPT Go Subscription";
+    case "plus":
+      return "ChatGPT Plus Subscription";
+    case "pro":
+      return "ChatGPT Pro 20x Subscription";
+    case "prolite":
+      return "ChatGPT Pro 5x Subscription";
+    case "team":
+      return "ChatGPT Team Subscription";
+    case "self_serve_business_usage_based":
+    case "business":
+      return "ChatGPT Business Subscription";
+    case "enterprise_cbp_usage_based":
+    case "enterprise":
+      return "ChatGPT Enterprise Subscription";
+    case "edu":
+      return "ChatGPT Edu Subscription";
+    case "unknown":
+      return "ChatGPT Subscription";
+    default:
+      account.planType satisfies never;
+      return undefined;
+  }
+}
+
+function codexAccountEmail(account: CodexSchema.V2GetAccountResponse["account"]) {
+  if (!account || account.type !== "chatgpt") return undefined;
+  return account.email;
+}
+
+function mapCodexModelCapabilities(
+  model: CodexSchema.V2ModelListResponse__Model,
+): ModelCapabilities {
+  const reasoningOptions = model.supportedReasoningEfforts.map(({ reasoningEffort }) =>
+    reasoningEffort === model.defaultReasoningEffort
+      ? {
+          id: reasoningEffort,
+          label: REASONING_EFFORT_LABELS[reasoningEffort],
+          isDefault: true,
+        }
+      : {
+          id: reasoningEffort,
+          label: REASONING_EFFORT_LABELS[reasoningEffort],
+        },
   );
+  const defaultReasoning = reasoningOptions.find((option) => option.isDefault)?.id;
+  const supportsFastMode = (model.additionalSpeedTiers ?? []).includes("fast");
+  return createModelCapabilities({
+    optionDescriptors: [
+      ...(reasoningOptions.length > 0
+        ? [
+            {
+              id: "reasoningEffort",
+              label: "Reasoning",
+              type: "select" as const,
+              options: reasoningOptions,
+              ...(defaultReasoning ? { currentValue: defaultReasoning } : {}),
+            },
+          ]
+        : []),
+      ...(supportsFastMode
+        ? [
+            {
+              id: "fastMode",
+              label: "Fast Mode",
+              type: "boolean" as const,
+            },
+          ]
+        : []),
+    ],
+  });
 }
 
-export function parseAuthStatusFromOutput(result: CommandResult): {
-  readonly status: Exclude<ServerProviderState, "disabled">;
-  readonly auth: Pick<ServerProviderAuth, "status">;
-  readonly message?: string;
-} {
-  const lowerOutput = `${result.stdout}\n${result.stderr}`.toLowerCase();
+const toDisplayName = (model: CodexSchema.V2ModelListResponse__Model): string => {
+  // Capitalize 'gpt' to 'GPT-' and capitalize any letter following a dash
+  return model.displayName
+    .replace(/^gpt/i, "GPT") // Handle start with 'gpt' or 'GPT'
+    .replace(/-([a-z])/g, (_, c) => "-" + c.toUpperCase());
+};
 
-  if (
-    lowerOutput.includes("unknown command") ||
-    lowerOutput.includes("unrecognized command") ||
-    lowerOutput.includes("unexpected argument")
-  ) {
-    return {
-      status: "warning",
-      auth: { status: "unknown" },
-      message: "Codex CLI authentication status command is unavailable in this Codex version.",
-    };
-  }
+function parseCodexModelListResponse(
+  response: CodexSchema.V2ModelListResponse,
+): ReadonlyArray<ServerProviderModel> {
+  return response.data.map((model) => ({
+    slug: model.model,
+    name: toDisplayName(model),
+    isCustom: false,
+    capabilities: mapCodexModelCapabilities(model),
+  }));
+}
 
-  if (
-    lowerOutput.includes("not logged in") ||
-    lowerOutput.includes("login required") ||
-    lowerOutput.includes("authentication required") ||
-    lowerOutput.includes("run `codex login`") ||
-    lowerOutput.includes("run codex login")
-  ) {
-    return {
-      status: "error",
-      auth: { status: "unauthenticated" },
-      message: "Codex CLI is not authenticated. Run `codex login` and try again.",
-    };
+function appendCustomCodexModels(
+  models: ReadonlyArray<ServerProviderModel>,
+  customModels: ReadonlyArray<string>,
+): ReadonlyArray<ServerProviderModel> {
+  if (customModels.length === 0) {
+    return models;
   }
 
-  const parsedAuth = (() => {
-    const trimmed = result.stdout.trim();
-    if (!trimmed || (!trimmed.startsWith("{") && !trimmed.startsWith("["))) {
-      return { attemptedJsonParse: false as const, auth: undefined as boolean | undefined };
-    }
-    try {
-      return {
-        attemptedJsonParse: true as const,
-        auth: extractAuthBoolean(JSON.parse(trimmed)),
-      };
-    } catch {
-      return { attemptedJsonParse: false as const, auth: undefined as boolean | undefined };
+  const seen = new Set(models.map((model) => model.slug));
+  const fallbackCapabilities = models.find((model) => model.capabilities)?.capabilities ?? null;
+  const customEntries: ServerProviderModel[] = [];
+  for (const rawModel of customModels) {
+    const slug = rawModel.trim();
+    if (!slug || seen.has(slug)) {
+      continue;
     }
-  })();
-
-  if (parsedAuth.auth === true) {
-    return { status: "ready", auth: { status: "authenticated" } };
-  }
-  if (parsedAuth.auth === false) {
-    return {
-      status: "error",
-      auth: { status: "unauthenticated" },
-      message: "Codex CLI is not authenticated. Run `codex login` and try again.",
-    };
+    seen.add(slug);
+    customEntries.push({
+      slug,
+      name: slug,
+      isCustom: true,
+      capabilities: fallbackCapabilities,
+    });
   }
-  if (parsedAuth.attemptedJsonParse) {
-    return {
-      status: "warning",
-      auth: { status: "unknown" },
-      message:
-        "Could not verify Codex authentication status from JSON output (missing auth marker).",
+  return customEntries.length === 0 ? models : [...models, ...customEntries];
+}
+
+function parseCodexSkillsListResponse(
+  response: CodexSchema.V2SkillsListResponse,
+  cwd: string,
+): ReadonlyArray<ServerProviderSkill> {
+  const matchingEntry = response.data.find((entry) => entry.cwd === cwd);
+  const skills = matchingEntry
+    ? matchingEntry.skills
+    : response.data.flatMap((entry) => entry.skills);
+
+  return skills.map((skill) => {
+    const shortDescription =
+      skill.shortDescription ?? skill.interface?.shortDescription ?? undefined;
+
+    const parsedSkill: Types.Mutable<ServerProviderSkill> = {
+      name: skill.name,
+      path: skill.path,
+      enabled: skill.enabled,
     };
-  }
-  if (result.code === 0) {
-    return { status: "ready", auth: { status: "authenticated" } };
-  }
 
-  const detail = detailFromResult(result);
-  return {
-    status: "warning",
-    auth: { status: "unknown" },
-    message: detail
-      ? `Could not verify Codex authentication status. ${detail}`
-      : "Could not verify Codex authentication status.",
-  };
-}
+    if (skill.description) {
+      parsedSkill.description = skill.description;
+    }
+    if (skill.scope) {
+      parsedSkill.scope = skill.scope;
+    }
+    if (skill.interface?.displayName) {
+      parsedSkill.displayName = skill.interface.displayName;
+    }
+    if (shortDescription) {
+      parsedSkill.shortDescription = shortDescription;
+    }
 
-export const readCodexConfigModelProvider = Effect.fn("readCodexConfigModelProvider")(function* () {
-  const fileSystem = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const settingsService = yield* ServerSettingsService;
-  const codexHome = yield* settingsService.getSettings.pipe(
-    Effect.map(
-      (settings) =>
-        settings.providers.codex.homePath ||
-        process.env.CODEX_HOME ||
-        path.join(OS.homedir(), ".codex"),
-    ),
-  );
-  const configPath = path.join(codexHome, "config.toml");
+    return parsedSkill;
+  });
+}
 
-  const content = yield* fileSystem
-    .readFileString(configPath)
-    .pipe(Effect.orElseSucceed(() => undefined));
-  if (content === undefined) {
-    return undefined;
-  }
+const requestAllCodexModels = Effect.fn("requestAllCodexModels")(function* (
+  client: CodexClient.CodexAppServerClientShape,
+) {
+  const models: ServerProviderModel[] = [];
+  let cursor: string | null | undefined = undefined;
 
-  let inTopLevel = true;
-  for (const line of content.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    if (trimmed.startsWith("[")) {
-      inTopLevel = false;
-      continue;
-    }
-    if (!inTopLevel) continue;
+  do {
+    const response: CodexSchema.V2ModelListResponse = yield* client.request(
+      "model/list",
+      cursor ? { cursor } : {},
+    );
+    models.push(...parseCodexModelListResponse(response));
+    cursor = response.nextCursor;
+  } while (cursor);
 
-    const match = trimmed.match(/^model_provider\s*=\s*["']([^"']+)["']/);
-    if (match) return match[1];
-  }
-  return undefined;
+  return models;
 });
 
-export const hasCustomModelProvider = readCodexConfigModelProvider().pipe(
-  Effect.map((provider) => provider !== undefined && !OPENAI_AUTH_PROVIDERS.has(provider)),
-  Effect.orElseSucceed(() => false),
-);
-
-const CAPABILITIES_PROBE_TIMEOUT_MS = 8_000;
+export function buildCodexInitializeParams(): CodexSchema.V1InitializeParams {
+  return {
+    clientInfo: {
+      name: "t3code_desktop",
+      title: "T3 Code Desktop",
+      version: packageJson.version,
+    },
+    capabilities: {
+      experimentalApi: true,
+    },
+  };
+}
 
-const probeCodexCapabilities = (input: {
+const probeCodexAppServerProvider = Effect.fn("probeCodexAppServerProvider")(function* (input: {
   readonly binaryPath: string;
   readonly homePath?: string;
   readonly cwd: string;
-}) =>
-  Effect.tryPromise((signal) => probeCodexDiscovery({ ...input, signal })).pipe(
-    Effect.timeoutOption(CAPABILITIES_PROBE_TIMEOUT_MS),
-    Effect.result,
-    Effect.map((result) => {
-      if (Result.isFailure(result)) return undefined;
-      return Option.isSome(result.success) ? result.success.value : undefined;
+  readonly customModels?: ReadonlyArray<string>;
+  readonly environment?: NodeJS.ProcessEnv;
+}) {
+  // `~` is not shell-expanded when env vars are set via `child_process.spawn`,
+  // so `CODEX_HOME=~/.codex_work` would reach codex verbatim and trip
+  // "CODEX_HOME points to '~/.codex_work', but that path does not exist".
+  // Expand here for parity with `CodexTextGeneration`/`CodexSessionRuntime`.
+  const resolvedHomePath = input.homePath ? expandHomePath(input.homePath) : undefined;
+  const clientContext = yield* Layer.build(
+    CodexClient.layerCommand({
+      command: input.binaryPath,
+      args: ["app-server"],
+      cwd: input.cwd,
+      env: {
+        ...(input.environment ?? process.env),
+        ...(resolvedHomePath ? { CODEX_HOME: resolvedHomePath } : {}),
+      },
     }),
   );
-
-const runCodexCommand = Effect.fn("runCodexCommand")(function* (args: ReadonlyArray<string>) {
-  const settingsService = yield* ServerSettingsService;
-  const codexSettings = yield* settingsService.getSettings.pipe(
-    Effect.map((settings) => settings.providers.codex),
+  const client = yield* Effect.service(CodexClient.CodexAppServerClient).pipe(
+    Effect.provide(clientContext),
   );
-  const command = ChildProcess.make(codexSettings.binaryPath, [...args], {
-    shell: process.platform === "win32",
-    env: {
-      ...process.env,
-      ...(codexSettings.homePath ? { CODEX_HOME: codexSettings.homePath } : {}),
+
+  const initialize = yield* client.request("initialize", {
+    clientInfo: {
+      name: "t3code_desktop",
+      title: "T3 Code Desktop",
+      version: "0.1.0",
+    },
+    capabilities: {
+      experimentalApi: true,
     },
   });
-  return yield* spawnAndCollect(codexSettings.binaryPath, command);
+  yield* client.notify("initialized", undefined);
+
+  // Extract the version string after the first '/' in userAgent, up to the next space or the end
+  const versionMatch = initialize.userAgent.match(/\/([^\s]+)/);
+  const version = versionMatch ? versionMatch[1] : undefined;
+
+  const accountResponse = yield* client.request("account/read", {});
+  if (!accountResponse.account && accountResponse.requiresOpenaiAuth) {
+    return {
+      account: accountResponse,
+      version,
+      models: appendCustomCodexModels([], input.customModels ?? []),
+      skills: [],
+    } satisfies CodexAppServerProviderSnapshot;
+  }
+
+  const [skillsResponse, models] = yield* Effect.all(
+    [
+      client.request("skills/list", {
+        cwds: [input.cwd],
+      }),
+      requestAllCodexModels(client),
+    ],
+    { concurrency: "unbounded" },
+  );
+
+  return {
+    account: accountResponse,
+    version,
+    models: appendCustomCodexModels(models, input.customModels ?? []),
+    skills: parseCodexSkillsListResponse(skillsResponse, input.cwd),
+  } satisfies CodexAppServerProviderSnapshot;
 });
 
+const emptyCodexModelsFromSettings = (codexSettings: CodexSettings): ServerProvider["models"] =>
+  codexSettings.customModels
+    .map((model) => model.trim())
+    .filter((model, index, models) => model.length > 0 && models.indexOf(model) === index)
+    .map((model) => ({
+      slug: model,
+      name: model,
+      isCustom: true,
+      capabilities: null,
+    }));
+
+const makePendingCodexProvider = (
+  codexSettings: CodexSettings,
+): Effect.Effect<ServerProviderDraft> =>
+  Effect.gen(function* () {
+    const checkedAt = yield* Effect.map(DateTime.now, DateTime.formatIso);
+    const models = emptyCodexModelsFromSettings(codexSettings);
+
+    if (!codexSettings.enabled) {
+      return buildServerProvider({
+        presentation: CODEX_PRESENTATION,
+        enabled: false,
+        checkedAt,
+        models,
+        skills: [],
+        probe: {
+          installed: false,
+          version: null,
+          status: "warning",
+          auth: { status: "unknown" },
+          message: "Codex is disabled in T3 Code settings.",
+        },
+      });
+    }
+
+    return buildServerProvider({
+      presentation: CODEX_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      skills: [],
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Codex provider status has not been checked in this session yet.",
+      },
+    });
+  });
+
+function accountProbeStatus(account: CodexAppServerProviderSnapshot["account"]): {
+  readonly status: Exclude<ServerProviderState, "disabled">;
+  readonly auth: ServerProvider["auth"];
+  readonly message?: string;
+} {
+  const authLabel = codexAccountAuthLabel(account.account);
+  const authEmail = codexAccountEmail(account.account);
+  const auth = {
+    status: account.account ? ("authenticated" as const) : ("unknown" as const),
+    ...(account.account?.type ? { type: account.account?.type } : {}),
+    ...(authLabel ? { label: authLabel } : {}),
+    ...(authEmail ? { email: authEmail } : {}),
+  } satisfies ServerProvider["auth"];
+
+  if (account.account) {
+    return { status: "ready", auth };
+  }
+
+  if (account.requiresOpenaiAuth) {
+    return {
+      status: "error",
+      auth: { status: "unauthenticated" },
+      message: "Codex CLI is not authenticated. Run `codex login` and try again.",
+    };
+  }
+
+  return { status: "ready", auth };
+}
+
 export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(function* (
-  resolveAccount?: (input: {
-    readonly binaryPath: string;
-    readonly homePath?: string;
-  }) => Effect.Effect<CodexAccountSnapshot | undefined>,
-  resolveSkills?: (input: {
+  codexSettings: CodexSettings,
+  probe: (input: {
     readonly binaryPath: string;
     readonly homePath?: string;
     readonly cwd: string;
-  }) => Effect.Effect<ReadonlyArray<ServerProviderSkill> | undefined>,
+    readonly customModels: ReadonlyArray<string>;
+    readonly environment?: NodeJS.ProcessEnv;
+  }) => Effect.Effect<
+    CodexAppServerProviderSnapshot,
+    CodexErrors.CodexAppServerError,
+    ChildProcessSpawner.ChildProcessSpawner | Scope.Scope
+  > = probeCodexAppServerProvider,
+  environment: NodeJS.ProcessEnv = process.env,
 ): Effect.fn.Return<
-  ServerProvider,
+  ServerProviderDraft,
   ServerSettingsError,
-  | ChildProcessSpawner.ChildProcessSpawner
-  | FileSystem.FileSystem
-  | Path.Path
-  | ServerSettingsService
+  ChildProcessSpawner.ChildProcessSpawner
 > {
-  const codexSettings = yield* Effect.service(ServerSettingsService).pipe(
-    Effect.flatMap((service) => service.getSettings),
-    Effect.map((settings) => settings.providers.codex),
-  );
-  const checkedAt = new Date().toISOString();
-  const models = providerModelsFromSettings(
-    BUILT_IN_MODELS,
-    PROVIDER,
-    codexSettings.customModels,
-    DEFAULT_CODEX_MODEL_CAPABILITIES,
-  );
+  const checkedAt = DateTime.formatIso(yield* DateTime.now);
+  const emptyModels = emptyCodexModelsFromSettings(codexSettings);
 
   if (!codexSettings.enabled) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CODEX_PRESENTATION,
       enabled: false,
       checkedAt,
-      models,
+      models: emptyModels,
+      skills: [],
       probe: {
         installed: false,
         version: null,
@@ -377,232 +438,80 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
     });
   }
 
-  const versionProbe = yield* runCodexCommand(["--version"]).pipe(
-    Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
+  const probeResult = yield* probe({
+    binaryPath: codexSettings.binaryPath,
+    homePath: codexSettings.homePath,
+    cwd: process.cwd(),
+    customModels: codexSettings.customModels,
+    environment,
+  }).pipe(
+    Effect.scoped,
+    Effect.timeoutOption(Duration.millis(AUTH_PROBE_TIMEOUT_MS)),
     Effect.result,
   );
 
-  if (Result.isFailure(versionProbe)) {
-    const error = versionProbe.failure;
+  if (Result.isFailure(probeResult)) {
+    const error = probeResult.failure;
+    const installed = !isCodexAppServerSpawnError(error);
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CODEX_PRESENTATION,
       enabled: codexSettings.enabled,
       checkedAt,
-      models,
+      models: emptyModels,
+      skills: [],
       probe: {
-        installed: !isCommandMissingCause(error),
+        installed,
         version: null,
         status: "error",
         auth: { status: "unknown" },
-        message: isCommandMissingCause(error)
-          ? "Codex CLI (`codex`) is not installed or not on PATH."
-          : `Failed to execute Codex CLI health check: ${error.message}.`,
+        message: installed
+          ? `Codex app-server provider probe failed: ${error.message}.`
+          : "Codex CLI (`codex`) is not installed or not on PATH.",
       },
     });
   }
 
-  if (Option.isNone(versionProbe.success)) {
+  if (Option.isNone(probeResult.success)) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CODEX_PRESENTATION,
       enabled: codexSettings.enabled,
       checkedAt,
-      models,
+      models: emptyModels,
+      skills: [],
       probe: {
         installed: true,
         version: null,
         status: "error",
         auth: { status: "unknown" },
-        message: "Codex CLI is installed but failed to run. Timed out while running command.",
-      },
-    });
-  }
-
-  const version = versionProbe.success.value;
-  const parsedVersion =
-    parseCodexCliVersion(`${version.stdout}\n${version.stderr}`) ??
-    parseGenericCliVersion(`${version.stdout}\n${version.stderr}`);
-  if (version.code !== 0) {
-    const detail = detailFromResult(version);
-    return buildServerProvider({
-      provider: PROVIDER,
-      enabled: codexSettings.enabled,
-      checkedAt,
-      models,
-      probe: {
-        installed: true,
-        version: parsedVersion,
-        status: "error",
-        auth: { status: "unknown" },
-        message: detail
-          ? `Codex CLI is installed but failed to run. ${detail}`
-          : "Codex CLI is installed but failed to run.",
-      },
-    });
-  }
-
-  if (parsedVersion && !isCodexCliVersionSupported(parsedVersion)) {
-    return buildServerProvider({
-      provider: PROVIDER,
-      enabled: codexSettings.enabled,
-      checkedAt,
-      models,
-      probe: {
-        installed: true,
-        version: parsedVersion,
-        status: "error",
-        auth: { status: "unknown" },
-        message: formatCodexCliUpgradeMessage(parsedVersion),
+        message: "Timed out while checking Codex app-server provider status.",
       },
     });
   }
 
-  const skills =
-    (resolveSkills
-      ? yield* resolveSkills({
-          binaryPath: codexSettings.binaryPath,
-          homePath: codexSettings.homePath,
-          cwd: process.cwd(),
-        }).pipe(Effect.orElseSucceed(() => undefined))
-      : undefined) ?? [];
-
-  if (yield* hasCustomModelProvider) {
-    return buildServerProvider({
-      provider: PROVIDER,
-      enabled: codexSettings.enabled,
-      checkedAt,
-      models,
-      skills,
-      probe: {
-        installed: true,
-        version: parsedVersion,
-        status: "ready",
-        auth: { status: "unknown" },
-        message: "Using a custom Codex model provider; OpenAI login check skipped.",
-      },
-    });
-  }
+  const snapshot = probeResult.success.value;
+  const accountStatus = accountProbeStatus(snapshot.account);
 
-  const authProbe = yield* runCodexCommand(["login", "status"]).pipe(
-    Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
-    Effect.result,
-  );
-  const account = resolveAccount
-    ? yield* resolveAccount({
-        binaryPath: codexSettings.binaryPath,
-        homePath: codexSettings.homePath,
-      })
-    : undefined;
-  const resolvedModels = adjustCodexModelsForAccount(models, account);
-
-  if (Result.isFailure(authProbe)) {
-    const error = authProbe.failure;
-    return buildServerProvider({
-      provider: PROVIDER,
-      enabled: codexSettings.enabled,
-      checkedAt,
-      models: resolvedModels,
-      skills,
-      probe: {
-        installed: true,
-        version: parsedVersion,
-        status: "warning",
-        auth: { status: "unknown" },
-        message: `Could not verify Codex authentication status: ${error.message}.`,
-      },
-    });
-  }
-
-  if (Option.isNone(authProbe.success)) {
-    return buildServerProvider({
-      provider: PROVIDER,
-      enabled: codexSettings.enabled,
-      checkedAt,
-      models: resolvedModels,
-      skills,
-      probe: {
-        installed: true,
-        version: parsedVersion,
-        status: "warning",
-        auth: { status: "unknown" },
-        message: "Could not verify Codex authentication status. Timed out while running command.",
-      },
-    });
-  }
-
-  const parsed = parseAuthStatusFromOutput(authProbe.success.value);
-  const authType = codexAuthSubType(account);
-  const authLabel = codexAuthSubLabel(account);
   return buildServerProvider({
-    provider: PROVIDER,
+    presentation: CODEX_PRESENTATION,
     enabled: codexSettings.enabled,
     checkedAt,
-    models: resolvedModels,
-    skills,
+    models: snapshot.models,
+    skills: snapshot.skills,
     probe: {
       installed: true,
-      version: parsedVersion,
-      status: parsed.status,
-      auth: {
-        ...parsed.auth,
-        ...(authType ? { type: authType } : {}),
-        ...(authLabel ? { label: authLabel } : {}),
-      },
-      ...(parsed.message ? { message: parsed.message } : {}),
+      version: snapshot.version ?? null,
+      status: accountStatus.status,
+      auth: accountStatus.auth,
+      ...(accountStatus.message ? { message: accountStatus.message } : {}),
     },
   });
 });
 
-export const CodexProviderLive = Layer.effect(
-  CodexProvider,
-  Effect.gen(function* () {
-    const serverSettings = yield* ServerSettingsService;
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-    const accountProbeCache = yield* Cache.make({
-      capacity: 4,
-      timeToLive: Duration.minutes(5),
-      lookup: (key: string) => {
-        const [binaryPath, homePath, cwd] = JSON.parse(key) as [string, string | undefined, string];
-        return probeCodexCapabilities({
-          binaryPath,
-          cwd,
-          ...(homePath ? { homePath } : {}),
-        });
-      },
-    });
-
-    const getDiscovery = (input: {
-      readonly binaryPath: string;
-      readonly homePath?: string;
-      readonly cwd: string;
-    }) =>
-      Cache.get(accountProbeCache, JSON.stringify([input.binaryPath, input.homePath, input.cwd]));
-
-    const checkProvider = checkCodexProviderStatus(
-      (input) =>
-        getDiscovery({
-          ...input,
-          cwd: process.cwd(),
-        }).pipe(Effect.map((discovery) => discovery?.account)),
-      (input) => getDiscovery(input).pipe(Effect.map((discovery) => discovery?.skills)),
-    ).pipe(
-      Effect.provideService(ServerSettingsService, serverSettings),
-      Effect.provideService(FileSystem.FileSystem, fileSystem),
-      Effect.provideService(Path.Path, path),
-      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
-    );
-
-    return yield* makeManagedServerProvider<CodexSettings>({
-      getSettings: serverSettings.getSettings.pipe(
-        Effect.map((settings) => settings.providers.codex),
-        Effect.orDie,
-      ),
-      streamSettings: serverSettings.streamChanges.pipe(
-        Stream.map((settings) => settings.providers.codex),
-      ),
-      haveSettingsChanged: (previous, next) => !Equal.equals(previous, next),
-      checkProvider,
-    });
-  }),
-);
+// NOTE: the singleton `CodexProviderLive` Layer has been removed as part of
+// the per-instance-driver refactor. `CodexDriver.create()` builds a managed
+// snapshot per instance (each with its own `CodexSettings`) and hands the
+// resulting `ServerProviderShape` back as `ProviderInstance.snapshot`.
+//
+// The `makePendingCodexProvider` and `checkCodexProviderStatus` helpers are
+// re-exported for use by `CodexDriver`.
+export { makePendingCodexProvider };
diff --git a/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
new file mode 100644
index 00000000000..82546621d32
--- /dev/null
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
@@ -0,0 +1,277 @@
+import assert from "node:assert/strict";
+
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { describe, it } from "vitest";
+import { ThreadId } from "@t3tools/contracts";
+import * as CodexErrors from "effect-codex-app-server/errors";
+import * as CodexRpc from "effect-codex-app-server/rpc";
+
+import {
+  CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
+  CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
+} from "../CodexDeveloperInstructions.ts";
+import {
+  buildTurnStartParams,
+  isRecoverableThreadResumeError,
+  openCodexThread,
+} from "./CodexSessionRuntime.ts";
+const isCodexAppServerRequestError = Schema.is(CodexErrors.CodexAppServerRequestError);
+
+function makeThreadOpenResponse(
+  threadId: string,
+): CodexRpc.ClientRequestResponsesByMethod["thread/start"] {
+  return {
+    cwd: "/tmp/project",
+    model: "gpt-5.3-codex",
+    modelProvider: "openai",
+    approvalPolicy: "never",
+    approvalsReviewer: "user",
+    sandbox: { type: "danger-full-access" },
+    thread: {
+      id: threadId,
+      createdAt: "2026-04-18T00:00:00.000Z",
+      source: { session: "cli" },
+      turns: [],
+      status: {
+        state: "idle",
+        activeFlags: [],
+      },
+    },
+  } as unknown as CodexRpc.ClientRequestResponsesByMethod["thread/start"];
+}
+
+describe("buildTurnStartParams", () => {
+  it("includes plan collaboration mode when requested", () => {
+    const params = Effect.runSync(
+      buildTurnStartParams({
+        threadId: "provider-thread-1",
+        runtimeMode: "full-access",
+        prompt: "Make a plan",
+        model: "gpt-5.3-codex",
+        effort: "medium",
+        interactionMode: "plan",
+      }),
+    );
+
+    assert.deepStrictEqual(params, {
+      threadId: "provider-thread-1",
+      approvalPolicy: "never",
+      sandboxPolicy: {
+        type: "dangerFullAccess",
+      },
+      input: [
+        {
+          type: "text",
+          text: "Make a plan",
+        },
+      ],
+      model: "gpt-5.3-codex",
+      effort: "medium",
+      collaborationMode: {
+        mode: "plan",
+        settings: {
+          model: "gpt-5.3-codex",
+          reasoning_effort: "medium",
+          developer_instructions: CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
+        },
+      },
+    });
+  });
+
+  it("includes default collaboration mode and image attachments", () => {
+    const params = Effect.runSync(
+      buildTurnStartParams({
+        threadId: "provider-thread-1",
+        runtimeMode: "auto-accept-edits",
+        prompt: "Implement it",
+        model: "gpt-5.3-codex",
+        interactionMode: "default",
+        attachments: [
+          {
+            type: "image",
+            url: "data:image/png;base64,abc",
+          },
+        ],
+      }),
+    );
+
+    assert.deepStrictEqual(params, {
+      threadId: "provider-thread-1",
+      approvalPolicy: "on-request",
+      sandboxPolicy: {
+        type: "workspaceWrite",
+      },
+      input: [
+        {
+          type: "text",
+          text: "Implement it",
+        },
+        {
+          type: "image",
+          url: "data:image/png;base64,abc",
+        },
+      ],
+      model: "gpt-5.3-codex",
+      collaborationMode: {
+        mode: "default",
+        settings: {
+          model: "gpt-5.3-codex",
+          reasoning_effort: "medium",
+          developer_instructions: CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
+        },
+      },
+    });
+  });
+
+  it("omits collaboration mode when interaction mode is absent", () => {
+    const params = Effect.runSync(
+      buildTurnStartParams({
+        threadId: "provider-thread-1",
+        runtimeMode: "approval-required",
+        prompt: "Review",
+      }),
+    );
+
+    assert.deepStrictEqual(params, {
+      threadId: "provider-thread-1",
+      approvalPolicy: "untrusted",
+      sandboxPolicy: {
+        type: "readOnly",
+      },
+      input: [
+        {
+          type: "text",
+          text: "Review",
+        },
+      ],
+    });
+  });
+});
+
+describe("isRecoverableThreadResumeError", () => {
+  it("matches missing thread errors", () => {
+    assert.equal(
+      isRecoverableThreadResumeError(
+        new CodexErrors.CodexAppServerRequestError({
+          code: -32603,
+          errorMessage: "Thread does not exist",
+        }),
+      ),
+      true,
+    );
+  });
+
+  it("ignores non-recoverable resume errors", () => {
+    assert.equal(
+      isRecoverableThreadResumeError(
+        new CodexErrors.CodexAppServerRequestError({
+          code: -32603,
+          errorMessage: "Permission denied",
+        }),
+      ),
+      false,
+    );
+  });
+
+  it("ignores unrelated missing-resource errors that do not mention threads", () => {
+    assert.equal(
+      isRecoverableThreadResumeError(
+        new CodexErrors.CodexAppServerRequestError({
+          code: -32603,
+          errorMessage: "Config file not found",
+        }),
+      ),
+      false,
+    );
+    assert.equal(
+      isRecoverableThreadResumeError(
+        new CodexErrors.CodexAppServerRequestError({
+          code: -32603,
+          errorMessage: "Model does not exist",
+        }),
+      ),
+      false,
+    );
+  });
+});
+
+describe("openCodexThread", () => {
+  it("falls back to thread/start when resume fails recoverably", async () => {
+    const calls: Array<{ method: "thread/start" | "thread/resume"; payload: unknown }> = [];
+    const started = makeThreadOpenResponse("fresh-thread");
+    const client = {
+      request: <M extends "thread/start" | "thread/resume">(
+        method: M,
+        payload: CodexRpc.ClientRequestParamsByMethod[M],
+      ) => {
+        calls.push({ method, payload });
+        if (method === "thread/resume") {
+          return Effect.fail(
+            new CodexErrors.CodexAppServerRequestError({
+              code: -32603,
+              errorMessage: "thread not found",
+            }),
+          );
+        }
+        return Effect.succeed(started as CodexRpc.ClientRequestResponsesByMethod[M]);
+      },
+    };
+
+    const opened = await Effect.runPromise(
+      openCodexThread({
+        client,
+        threadId: ThreadId.make("thread-1"),
+        runtimeMode: "full-access",
+        cwd: "/tmp/project",
+        requestedModel: "gpt-5.3-codex",
+        serviceTier: undefined,
+        resumeThreadId: "stale-thread",
+      }),
+    );
+
+    assert.equal(opened.thread.id, "fresh-thread");
+    assert.deepStrictEqual(
+      calls.map((call) => call.method),
+      ["thread/resume", "thread/start"],
+    );
+  });
+
+  it("propagates non-recoverable resume failures", async () => {
+    const client = {
+      request: <M extends "thread/start" | "thread/resume">(
+        method: M,
+        _payload: CodexRpc.ClientRequestParamsByMethod[M],
+      ) => {
+        if (method === "thread/resume") {
+          return Effect.fail(
+            new CodexErrors.CodexAppServerRequestError({
+              code: -32603,
+              errorMessage: "timed out waiting for server",
+            }),
+          );
+        }
+        return Effect.succeed(
+          makeThreadOpenResponse("fresh-thread") as CodexRpc.ClientRequestResponsesByMethod[M],
+        );
+      },
+    };
+
+    await assert.rejects(
+      Effect.runPromise(
+        openCodexThread({
+          client,
+          threadId: ThreadId.make("thread-1"),
+          runtimeMode: "full-access",
+          cwd: "/tmp/project",
+          requestedModel: "gpt-5.3-codex",
+          serviceTier: undefined,
+          resumeThreadId: "stale-thread",
+        }),
+      ),
+      (error: unknown) =>
+        isCodexAppServerRequestError(error) &&
+        error.errorMessage === "timed out waiting for server",
+    );
+  });
+});
diff --git a/apps/server/src/provider/Layers/CodexSessionRuntime.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
new file mode 100644
index 00000000000..7f71ef46b2c
--- /dev/null
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
@@ -0,0 +1,1371 @@
+import {
+  ApprovalRequestId,
+  DEFAULT_MODEL,
+  EventId,
+  ProviderDriverKind,
+  ProviderItemId,
+  type ProviderInstanceId,
+  type ProviderApprovalDecision,
+  type ProviderEvent,
+  type ProviderInteractionMode,
+  type ProviderRequestKind,
+  type ProviderSession,
+  type ProviderTurnStartResult,
+  type ProviderUserInputAnswers,
+  RuntimeMode,
+  ThreadId,
+  TurnId,
+} from "@t3tools/contracts";
+import { normalizeModelSlug } from "@t3tools/shared/model";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as SchemaIssue from "effect/SchemaIssue";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import * as CodexClient from "effect-codex-app-server/client";
+import * as CodexErrors from "effect-codex-app-server/errors";
+import * as CodexRpc from "effect-codex-app-server/rpc";
+import * as EffectCodexSchema from "effect-codex-app-server/schema";
+
+import { buildCodexInitializeParams } from "./CodexProvider.ts";
+import { expandHomePath } from "../../pathExpansion.ts";
+import {
+  CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
+  CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
+} from "../CodexDeveloperInstructions.ts";
+const decodeV2TurnStartResponse = Schema.decodeUnknownEffect(EffectCodexSchema.V2TurnStartResponse);
+
+const PROVIDER = ProviderDriverKind.make("codex");
+
+const ANSI_ESCAPE_CHAR = String.fromCharCode(27);
+const ANSI_ESCAPE_REGEX = new RegExp(`${ANSI_ESCAPE_CHAR}\\[[0-9;]*m`, "g");
+const CODEX_STDERR_LOG_REGEX =
+  /^\d{4}-\d{2}-\d{2}T\S+\s+(TRACE|DEBUG|INFO|WARN|ERROR)\s+\S+:\s+(.*)$/;
+const BENIGN_ERROR_LOG_SNIPPETS = [
+  "state db missing rollout path for thread",
+  "state db record_discrepancy: find_thread_path_by_id_str_in_subdir, falling_back",
+];
+const CODEX_APP_SERVER_FORCE_KILL_AFTER = "2 seconds" as const;
+const RECOVERABLE_THREAD_RESUME_ERROR_SNIPPETS = [
+  "not found",
+  "missing thread",
+  "no such thread",
+  "unknown thread",
+  "does not exist",
+];
+
+export const CodexResumeCursorSchema = Schema.Struct({
+  threadId: Schema.String,
+});
+const CodexUserInputAnswerObject = Schema.Struct({
+  answers: Schema.Array(Schema.String),
+});
+const isCodexResumeCursorSchema = Schema.is(CodexResumeCursorSchema);
+const isCodexUserInputAnswerObject = Schema.is(CodexUserInputAnswerObject);
+
+// TODO: Verify `packages/effect-codex-app-server/scripts/generate.ts` so the generated
+// `V2TurnStartParams` schema includes `collaborationMode` directly.
+const CodexTurnStartParamsWithCollaborationMode = EffectCodexSchema.V2TurnStartParams.pipe(
+  Schema.fieldsAssign({
+    collaborationMode: Schema.optionalKey(EffectCodexSchema.V2TurnStartParams__CollaborationMode),
+  }),
+);
+const decodeCodexTurnStartParamsWithCollaborationMode = Schema.decodeUnknownEffect(
+  CodexTurnStartParamsWithCollaborationMode,
+);
+
+export type CodexTurnStartParamsWithCollaborationMode =
+  typeof CodexTurnStartParamsWithCollaborationMode.Type;
+const formatSchemaIssue = SchemaIssue.makeFormatterDefault();
+
+export type CodexResumeCursor = typeof CodexResumeCursorSchema.Type;
+type CodexServiceTier = NonNullable<EffectCodexSchema.V2ThreadStartParams["serviceTier"]>;
+type CodexThreadItem =
+  | EffectCodexSchema.V2ThreadReadResponse["thread"]["turns"][number]["items"][number]
+  | EffectCodexSchema.V2ThreadRollbackResponse["thread"]["turns"][number]["items"][number];
+
+export interface CodexSessionRuntimeOptions {
+  readonly threadId: ThreadId;
+  readonly providerInstanceId?: ProviderInstanceId;
+  readonly binaryPath: string;
+  readonly homePath?: string;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly cwd: string;
+  readonly runtimeMode: RuntimeMode;
+  readonly model?: string;
+  readonly serviceTier?: CodexServiceTier | undefined;
+  readonly resumeCursor?: CodexResumeCursor;
+}
+
+export interface CodexSessionRuntimeSendTurnInput {
+  readonly input?: string;
+  readonly attachments?: ReadonlyArray<{
+    readonly type: "image";
+    readonly url: string;
+  }>;
+  readonly model?: string;
+  readonly serviceTier?: CodexServiceTier | undefined;
+  readonly effort?: EffectCodexSchema.V2TurnStartParams__ReasoningEffort | undefined;
+  readonly interactionMode?: ProviderInteractionMode;
+}
+
+export interface CodexThreadTurnSnapshot {
+  readonly id: TurnId;
+  readonly items: ReadonlyArray<CodexThreadItem>;
+}
+
+export interface CodexThreadSnapshot {
+  readonly threadId: string;
+  readonly turns: ReadonlyArray<CodexThreadTurnSnapshot>;
+}
+
+export interface CodexSessionRuntimeShape {
+  readonly start: () => Effect.Effect<ProviderSession, CodexSessionRuntimeError>;
+  readonly getSession: Effect.Effect<ProviderSession>;
+  readonly sendTurn: (
+    input: CodexSessionRuntimeSendTurnInput,
+  ) => Effect.Effect<ProviderTurnStartResult, CodexSessionRuntimeError>;
+  readonly interruptTurn: (turnId?: TurnId) => Effect.Effect<void, CodexSessionRuntimeError>;
+  readonly readThread: Effect.Effect<CodexThreadSnapshot, CodexSessionRuntimeError>;
+  readonly rollbackThread: (
+    numTurns: number,
+  ) => Effect.Effect<CodexThreadSnapshot, CodexSessionRuntimeError>;
+  readonly respondToRequest: (
+    requestId: ApprovalRequestId,
+    decision: ProviderApprovalDecision,
+  ) => Effect.Effect<void, CodexSessionRuntimeError>;
+  readonly respondToUserInput: (
+    requestId: ApprovalRequestId,
+    answers: ProviderUserInputAnswers,
+  ) => Effect.Effect<void, CodexSessionRuntimeError>;
+  readonly events: Stream.Stream<ProviderEvent, never>;
+  readonly close: Effect.Effect<void>;
+}
+
+export type CodexSessionRuntimeError =
+  | CodexErrors.CodexAppServerError
+  | CodexSessionRuntimePendingApprovalNotFoundError
+  | CodexSessionRuntimePendingUserInputNotFoundError
+  | CodexSessionRuntimeInvalidUserInputAnswersError
+  | CodexSessionRuntimeThreadIdMissingError;
+
+export class CodexSessionRuntimePendingApprovalNotFoundError extends Schema.TaggedErrorClass<CodexSessionRuntimePendingApprovalNotFoundError>()(
+  "CodexSessionRuntimePendingApprovalNotFoundError",
+  {
+    requestId: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Unknown pending Codex approval request: ${this.requestId}`;
+  }
+}
+
+export class CodexSessionRuntimePendingUserInputNotFoundError extends Schema.TaggedErrorClass<CodexSessionRuntimePendingUserInputNotFoundError>()(
+  "CodexSessionRuntimePendingUserInputNotFoundError",
+  {
+    requestId: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Unknown pending Codex user input request: ${this.requestId}`;
+  }
+}
+
+export class CodexSessionRuntimeInvalidUserInputAnswersError extends Schema.TaggedErrorClass<CodexSessionRuntimeInvalidUserInputAnswersError>()(
+  "CodexSessionRuntimeInvalidUserInputAnswersError",
+  {
+    questionId: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Invalid Codex user input answers for question '${this.questionId}'`;
+  }
+}
+
+export class CodexSessionRuntimeThreadIdMissingError extends Schema.TaggedErrorClass<CodexSessionRuntimeThreadIdMissingError>()(
+  "CodexSessionRuntimeThreadIdMissingError",
+  {
+    threadId: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Codex session is missing a provider thread id for ${this.threadId}`;
+  }
+}
+
+interface PendingApproval {
+  readonly requestId: ApprovalRequestId;
+  readonly jsonRpcId: string;
+  readonly requestKind: ProviderRequestKind;
+  readonly turnId: TurnId | undefined;
+  readonly itemId: ProviderItemId | undefined;
+  readonly decision: Deferred.Deferred<ProviderApprovalDecision>;
+}
+
+interface ApprovalCorrelation {
+  readonly requestId: ApprovalRequestId;
+  readonly requestKind: ProviderRequestKind;
+  readonly turnId: TurnId | undefined;
+  readonly itemId: ProviderItemId | undefined;
+}
+
+interface PendingUserInput {
+  readonly requestId: ApprovalRequestId;
+  readonly turnId: TurnId | undefined;
+  readonly itemId: ProviderItemId | undefined;
+  readonly answers: Deferred.Deferred<ProviderUserInputAnswers>;
+}
+
+type CodexServerNotification = {
+  readonly [M in CodexRpc.ServerNotificationMethod]: {
+    readonly method: M;
+    readonly params: CodexRpc.ServerNotificationParamsByMethod[M];
+  };
+}[CodexRpc.ServerNotificationMethod];
+
+function makeCodexServerNotification<M extends CodexRpc.ServerNotificationMethod>(
+  method: M,
+  params: CodexRpc.ServerNotificationParamsByMethod[M],
+): CodexServerNotification {
+  return { method, params } as CodexServerNotification;
+}
+
+function normalizeCodexModelSlug(
+  model: string | undefined | null,
+  preferredId?: string,
+): string | undefined {
+  const normalized = normalizeModelSlug(model);
+  if (!normalized) {
+    return undefined;
+  }
+  if (preferredId?.endsWith("-codex") && preferredId !== normalized) {
+    return preferredId;
+  }
+  return normalized;
+}
+
+function readResumeCursorThreadId(
+  resumeCursor: ProviderSession["resumeCursor"],
+): string | undefined {
+  return isCodexResumeCursorSchema(resumeCursor) ? resumeCursor.threadId : undefined;
+}
+
+function runtimeModeToThreadConfig(input: RuntimeMode): {
+  readonly approvalPolicy: EffectCodexSchema.V2ThreadStartParams__AskForApproval;
+  readonly sandbox: EffectCodexSchema.V2ThreadStartParams__SandboxMode;
+} {
+  switch (input) {
+    case "approval-required":
+      return {
+        approvalPolicy: "untrusted",
+        sandbox: "read-only",
+      };
+    case "auto-accept-edits":
+      return {
+        approvalPolicy: "on-request",
+        sandbox: "workspace-write",
+      };
+    case "full-access":
+    default:
+      return {
+        approvalPolicy: "never",
+        sandbox: "danger-full-access",
+      };
+  }
+}
+
+function buildThreadStartParams(input: {
+  readonly cwd: string;
+  readonly runtimeMode: RuntimeMode;
+  readonly model: string | undefined;
+  readonly serviceTier: CodexServiceTier | undefined;
+}): EffectCodexSchema.V2ThreadStartParams {
+  const config = runtimeModeToThreadConfig(input.runtimeMode);
+  return {
+    cwd: input.cwd,
+    approvalPolicy: config.approvalPolicy,
+    sandbox: config.sandbox,
+    ...(input.model ? { model: input.model } : {}),
+    ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
+  };
+}
+
+function runtimeModeToTurnSandboxPolicy(
+  input: RuntimeMode,
+): EffectCodexSchema.V2TurnStartParams__SandboxPolicy {
+  switch (input) {
+    case "approval-required":
+      return {
+        type: "readOnly",
+      };
+    case "auto-accept-edits":
+      return {
+        type: "workspaceWrite",
+      };
+    case "full-access":
+    default:
+      return {
+        type: "dangerFullAccess",
+      };
+  }
+}
+
+function buildCodexCollaborationMode(input: {
+  readonly interactionMode?: ProviderInteractionMode;
+  readonly model?: string;
+  readonly effort?: EffectCodexSchema.V2TurnStartParams__ReasoningEffort;
+}): EffectCodexSchema.V2TurnStartParams__CollaborationMode | undefined {
+  if (input.interactionMode === undefined) {
+    return undefined;
+  }
+  const model = normalizeCodexModelSlug(input.model) ?? DEFAULT_MODEL;
+  return {
+    mode: input.interactionMode,
+    settings: {
+      model,
+      reasoning_effort: input.effort ?? "medium",
+      developer_instructions:
+        input.interactionMode === "plan"
+          ? CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS
+          : CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
+    },
+  };
+}
+
+export function buildTurnStartParams(input: {
+  readonly threadId: string;
+  readonly runtimeMode: RuntimeMode;
+  readonly prompt?: string;
+  readonly attachments?: ReadonlyArray<{
+    readonly type: "image";
+    readonly url: string;
+  }>;
+  readonly model?: string;
+  readonly serviceTier?: CodexServiceTier;
+  readonly effort?: EffectCodexSchema.V2TurnStartParams__ReasoningEffort;
+  readonly interactionMode?: ProviderInteractionMode;
+}): Effect.Effect<
+  CodexTurnStartParamsWithCollaborationMode,
+  CodexErrors.CodexAppServerProtocolParseError
+> {
+  const turnInput: Array<EffectCodexSchema.V2TurnStartParams__UserInput> = [];
+  if (input.prompt) {
+    turnInput.push({
+      type: "text",
+      text: input.prompt,
+    });
+  }
+  for (const attachment of input.attachments ?? []) {
+    turnInput.push(attachment);
+  }
+
+  const config = runtimeModeToThreadConfig(input.runtimeMode);
+  const collaborationMode = buildCodexCollaborationMode({
+    ...(input.interactionMode ? { interactionMode: input.interactionMode } : {}),
+    ...(input.model ? { model: input.model } : {}),
+    ...(input.effort ? { effort: input.effort } : {}),
+  });
+
+  return decodeCodexTurnStartParamsWithCollaborationMode({
+    threadId: input.threadId,
+    input: turnInput,
+    approvalPolicy: config.approvalPolicy,
+    sandboxPolicy: runtimeModeToTurnSandboxPolicy(input.runtimeMode),
+    ...(input.model ? { model: input.model } : {}),
+    ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
+    ...(input.effort ? { effort: input.effort } : {}),
+    ...(collaborationMode ? { collaborationMode } : {}),
+  }).pipe(
+    Effect.mapError((error) => toProtocolParseError("Invalid turn/start request payload", error)),
+  );
+}
+
+function classifyCodexStderrLine(rawLine: string): { readonly message: string } | null {
+  const line = rawLine.replaceAll(ANSI_ESCAPE_REGEX, "").trim();
+  if (!line) {
+    return null;
+  }
+
+  const match = line.match(CODEX_STDERR_LOG_REGEX);
+  if (match) {
+    const level = match[1];
+    if (level && level !== "ERROR") {
+      return null;
+    }
+    if (BENIGN_ERROR_LOG_SNIPPETS.some((snippet) => line.includes(snippet))) {
+      return null;
+    }
+  }
+
+  return { message: line };
+}
+
+export function isRecoverableThreadResumeError(error: unknown): boolean {
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+  if (!message.includes("thread")) {
+    return false;
+  }
+  return RECOVERABLE_THREAD_RESUME_ERROR_SNIPPETS.some((snippet) => message.includes(snippet));
+}
+
+type CodexThreadOpenResponse =
+  | CodexRpc.ClientRequestResponsesByMethod["thread/start"]
+  | CodexRpc.ClientRequestResponsesByMethod["thread/resume"];
+
+type CodexThreadOpenMethod = "thread/start" | "thread/resume";
+
+interface CodexThreadOpenClient {
+  readonly request: <M extends CodexThreadOpenMethod>(
+    method: M,
+    payload: CodexRpc.ClientRequestParamsByMethod[M],
+  ) => Effect.Effect<CodexRpc.ClientRequestResponsesByMethod[M], CodexErrors.CodexAppServerError>;
+}
+
+export const openCodexThread = (input: {
+  readonly client: CodexThreadOpenClient;
+  readonly threadId: ThreadId;
+  readonly runtimeMode: RuntimeMode;
+  readonly cwd: string;
+  readonly requestedModel: string | undefined;
+  readonly serviceTier: CodexServiceTier | undefined;
+  readonly resumeThreadId: string | undefined;
+}): Effect.Effect<CodexThreadOpenResponse, CodexErrors.CodexAppServerError> => {
+  const resumeThreadId = input.resumeThreadId;
+  const startParams = buildThreadStartParams({
+    cwd: input.cwd,
+    runtimeMode: input.runtimeMode,
+    model: input.requestedModel,
+    serviceTier: input.serviceTier,
+  });
+
+  if (resumeThreadId === undefined) {
+    return input.client.request("thread/start", startParams);
+  }
+
+  return input.client
+    .request("thread/resume", {
+      threadId: resumeThreadId,
+      ...startParams,
+    })
+    .pipe(
+      Effect.catchIf(isRecoverableThreadResumeError, (error) =>
+        Effect.logWarning("codex app-server thread resume fell back to fresh start", {
+          threadId: input.threadId,
+          requestedRuntimeMode: input.runtimeMode,
+          resumeThreadId,
+          recoverable: true,
+          cause: error.message,
+        }).pipe(Effect.andThen(input.client.request("thread/start", startParams))),
+      ),
+    );
+};
+
+function readNotificationThreadId(notification: CodexServerNotification): string | undefined {
+  switch (notification.method) {
+    case "thread/started":
+      return notification.params.thread.id;
+    case "error":
+    case "thread/status/changed":
+    case "thread/archived":
+    case "thread/unarchived":
+    case "thread/closed":
+    case "thread/name/updated":
+    case "thread/tokenUsage/updated":
+    case "turn/started":
+    case "hook/started":
+    case "turn/completed":
+    case "hook/completed":
+    case "turn/diff/updated":
+    case "turn/plan/updated":
+    case "item/started":
+    case "item/autoApprovalReview/started":
+    case "item/autoApprovalReview/completed":
+    case "item/completed":
+    case "rawResponseItem/completed":
+    case "item/agentMessage/delta":
+    case "item/plan/delta":
+    case "item/commandExecution/outputDelta":
+    case "item/commandExecution/terminalInteraction":
+    case "item/fileChange/outputDelta":
+    case "item/fileChange/patchUpdated":
+    case "serverRequest/resolved":
+    case "item/mcpToolCall/progress":
+    case "item/reasoning/summaryTextDelta":
+    case "item/reasoning/summaryPartAdded":
+    case "item/reasoning/textDelta":
+    case "thread/compacted":
+    case "thread/realtime/started":
+    case "thread/realtime/itemAdded":
+    case "thread/realtime/transcript/delta":
+    case "thread/realtime/transcript/done":
+    case "thread/realtime/outputAudio/delta":
+    case "thread/realtime/sdp":
+    case "thread/realtime/error":
+    case "thread/realtime/closed":
+      return notification.params.threadId;
+    default:
+      return undefined;
+  }
+}
+
+function readRouteFields(notification: CodexServerNotification): {
+  readonly turnId: TurnId | undefined;
+  readonly itemId: ProviderItemId | undefined;
+} {
+  switch (notification.method) {
+    case "thread/started":
+      return {
+        turnId: undefined,
+        itemId: undefined,
+      };
+    case "turn/started":
+    case "turn/completed":
+      return {
+        turnId: TurnId.make(notification.params.turn.id),
+        itemId: undefined,
+      };
+    case "error":
+      return {
+        turnId: TurnId.make(notification.params.turnId),
+        itemId: undefined,
+      };
+    case "turn/diff/updated":
+    case "turn/plan/updated":
+      return {
+        turnId: TurnId.make(notification.params.turnId),
+        itemId: undefined,
+      };
+    case "serverRequest/resolved":
+      return {
+        turnId: undefined,
+        itemId: undefined,
+      };
+    case "item/started":
+    case "item/completed":
+      return {
+        turnId: TurnId.make(notification.params.turnId),
+        itemId: ProviderItemId.make(notification.params.item.id),
+      };
+    case "item/agentMessage/delta":
+    case "item/plan/delta":
+    case "item/commandExecution/outputDelta":
+    case "item/commandExecution/terminalInteraction":
+    case "item/fileChange/outputDelta":
+    case "item/fileChange/patchUpdated":
+    case "item/reasoning/summaryTextDelta":
+    case "item/reasoning/summaryPartAdded":
+    case "item/reasoning/textDelta":
+      return {
+        turnId: TurnId.make(notification.params.turnId),
+        itemId: ProviderItemId.make(notification.params.itemId),
+      };
+    default:
+      return {
+        turnId: undefined,
+        itemId: undefined,
+      };
+  }
+}
+
+function rememberCollabReceiverTurns(
+  collabReceiverTurns: Map<string, TurnId>,
+  notification: CodexServerNotification,
+  parentTurnId: TurnId | undefined,
+): void {
+  if (!parentTurnId) {
+    return;
+  }
+
+  if (notification.method !== "item/started" && notification.method !== "item/completed") {
+    return;
+  }
+
+  if (notification.params.item.type !== "collabAgentToolCall") {
+    return;
+  }
+
+  for (const receiverThreadId of notification.params.item.receiverThreadIds) {
+    collabReceiverTurns.set(receiverThreadId, parentTurnId);
+  }
+}
+
+function shouldSuppressChildConversationNotification(
+  method: CodexRpc.ServerNotificationMethod,
+): boolean {
+  return (
+    method === "thread/started" ||
+    method === "thread/status/changed" ||
+    method === "thread/archived" ||
+    method === "thread/unarchived" ||
+    method === "thread/closed" ||
+    method === "thread/compacted" ||
+    method === "thread/name/updated" ||
+    method === "thread/tokenUsage/updated" ||
+    method === "turn/started" ||
+    method === "turn/completed" ||
+    method === "turn/plan/updated" ||
+    method === "item/plan/delta"
+  );
+}
+
+function toCodexUserInputAnswer(
+  questionId: string,
+  value: ProviderUserInputAnswers[string],
+): Effect.Effect<
+  EffectCodexSchema.ToolRequestUserInputResponse__ToolRequestUserInputAnswer,
+  CodexSessionRuntimeInvalidUserInputAnswersError
+> {
+  if (typeof value === "string") {
+    return Effect.succeed({ answers: [value] });
+  }
+  if (Array.isArray(value)) {
+    const answers = value.filter((entry): entry is string => typeof entry === "string");
+    return Effect.succeed({ answers });
+  }
+  if (isCodexUserInputAnswerObject(value)) {
+    return Effect.succeed({ answers: value.answers });
+  }
+  return Effect.fail(new CodexSessionRuntimeInvalidUserInputAnswersError({ questionId }));
+}
+
+function toCodexUserInputAnswers(
+  answers: ProviderUserInputAnswers,
+): Effect.Effect<
+  EffectCodexSchema.ToolRequestUserInputResponse["answers"],
+  CodexSessionRuntimeInvalidUserInputAnswersError
+> {
+  return Effect.forEach(
+    Object.entries(answers),
+    ([questionId, value]) =>
+      toCodexUserInputAnswer(questionId, value).pipe(
+        Effect.map((answer) => [questionId, answer] as const),
+      ),
+    { concurrency: 1 },
+  ).pipe(Effect.map((entries) => Object.fromEntries(entries)));
+}
+
+function toProtocolParseError(
+  detail: string,
+  cause: Schema.SchemaError,
+): CodexErrors.CodexAppServerProtocolParseError {
+  return new CodexErrors.CodexAppServerProtocolParseError({
+    detail: `${detail}: ${formatSchemaIssue(cause.issue)}`,
+    cause,
+  });
+}
+
+function currentProviderThreadId(session: ProviderSession): string | undefined {
+  return readResumeCursorThreadId(session.resumeCursor);
+}
+
+function updateSession(
+  sessionRef: Ref.Ref<ProviderSession>,
+  updates: Partial<ProviderSession>,
+): Effect.Effect<void> {
+  return Effect.gen(function* () {
+    const updatedAt = DateTime.formatIso(yield* DateTime.now);
+    yield* Ref.update(sessionRef, (session) => ({
+      ...session,
+      ...updates,
+      updatedAt,
+    }));
+  });
+}
+
+function parseThreadSnapshot(
+  response: EffectCodexSchema.V2ThreadReadResponse | EffectCodexSchema.V2ThreadRollbackResponse,
+): CodexThreadSnapshot {
+  return {
+    threadId: response.thread.id,
+    turns: response.thread.turns.map((turn) => ({
+      id: TurnId.make(turn.id),
+      items: turn.items,
+    })),
+  };
+}
+
+export const makeCodexSessionRuntime = (
+  options: CodexSessionRuntimeOptions,
+): Effect.Effect<
+  CodexSessionRuntimeShape,
+  CodexErrors.CodexAppServerError,
+  ChildProcessSpawner.ChildProcessSpawner | Scope.Scope
+> =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const runtimeScope = yield* Scope.Scope;
+    const events = yield* Queue.unbounded<ProviderEvent>();
+    const pendingApprovalsRef = yield* Ref.make(new Map<ApprovalRequestId, PendingApproval>());
+    const approvalCorrelationsRef = yield* Ref.make(new Map<string, ApprovalCorrelation>());
+    const pendingUserInputsRef = yield* Ref.make(new Map<ApprovalRequestId, PendingUserInput>());
+    const collabReceiverTurnsRef = yield* Ref.make(new Map<string, TurnId>());
+    const closedRef = yield* Ref.make(false);
+
+    // `~` is not shell-expanded when env vars are set via
+    // `child_process.spawn`; `expandHomePath` lets a configured
+    // `CODEX_HOME=~/.codex_work` reach codex as an absolute path.
+    const resolvedHomePath = options.homePath ? expandHomePath(options.homePath) : undefined;
+    const env = {
+      ...(options.environment ?? process.env),
+      ...(resolvedHomePath ? { CODEX_HOME: resolvedHomePath } : {}),
+    };
+    const child = yield* spawner
+      .spawn(
+        ChildProcess.make(options.binaryPath, ["app-server"], {
+          cwd: options.cwd,
+          env,
+          forceKillAfter: CODEX_APP_SERVER_FORCE_KILL_AFTER,
+          shell: process.platform === "win32",
+        }),
+      )
+      .pipe(
+        Effect.provideService(Scope.Scope, runtimeScope),
+        Effect.mapError(
+          (cause) =>
+            new CodexErrors.CodexAppServerSpawnError({
+              command: `${options.binaryPath} app-server`,
+              cause,
+            }),
+        ),
+      );
+
+    const clientContext = yield* CodexClient.layerChildProcess(child).pipe(
+      Layer.build,
+      Effect.provideService(Scope.Scope, runtimeScope),
+    );
+    const client = yield* Effect.service(CodexClient.CodexAppServerClient).pipe(
+      Effect.provide(clientContext),
+    );
+    const serverNotifications = yield* Queue.unbounded<CodexServerNotification>();
+    const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
+    const sessionCreatedAt = yield* nowIso;
+    const initialSession = {
+      provider: PROVIDER,
+      ...(options.providerInstanceId ? { providerInstanceId: options.providerInstanceId } : {}),
+      status: "connecting",
+      runtimeMode: options.runtimeMode,
+      cwd: options.cwd,
+      ...(options.model ? { model: options.model } : {}),
+      threadId: options.threadId,
+      ...(options.resumeCursor !== undefined ? { resumeCursor: options.resumeCursor } : {}),
+      createdAt: sessionCreatedAt,
+      updatedAt: sessionCreatedAt,
+    } satisfies ProviderSession;
+    const sessionRef = yield* Ref.make<ProviderSession>(initialSession);
+    const offerEvent = (event: ProviderEvent) => Queue.offer(events, event).pipe(Effect.asVoid);
+
+    const emitEvent = (event: Omit<ProviderEvent, "id" | "provider" | "createdAt">) =>
+      Effect.gen(function* () {
+        const id = yield* Random.nextUUIDv4;
+        return yield* offerEvent({
+          id: EventId.make(id),
+          provider: PROVIDER,
+          ...(options.providerInstanceId ? { providerInstanceId: options.providerInstanceId } : {}),
+          createdAt: yield* nowIso,
+          ...event,
+        });
+      });
+    const emitSessionEvent = (method: string, message: string) =>
+      emitEvent({
+        kind: "session",
+        threadId: options.threadId,
+        method,
+        message,
+      });
+
+    const settlePendingApprovals = (decision: ProviderApprovalDecision) =>
+      Ref.get(pendingApprovalsRef).pipe(
+        Effect.flatMap((pendingApprovals) =>
+          Effect.forEach(
+            Array.from(pendingApprovals.values()),
+            (pendingApproval) =>
+              Deferred.succeed(pendingApproval.decision, decision).pipe(Effect.ignore),
+            { discard: true },
+          ),
+        ),
+      );
+
+    const settlePendingUserInputs = (answers: ProviderUserInputAnswers) =>
+      Ref.get(pendingUserInputsRef).pipe(
+        Effect.flatMap((pendingUserInputs) =>
+          Effect.forEach(
+            Array.from(pendingUserInputs.values()),
+            (pendingUserInput) =>
+              Deferred.succeed(pendingUserInput.answers, answers).pipe(Effect.ignore),
+            { discard: true },
+          ),
+        ),
+      );
+
+    const handleRawNotification = (notification: CodexServerNotification) =>
+      Effect.gen(function* () {
+        const payload = notification.params;
+        const route = readRouteFields(notification);
+        const collabReceiverTurns = yield* Ref.get(collabReceiverTurnsRef);
+        const childParentTurnId = (() => {
+          const providerConversationId = readNotificationThreadId(notification);
+          return providerConversationId
+            ? collabReceiverTurns.get(providerConversationId)
+            : undefined;
+        })();
+
+        rememberCollabReceiverTurns(collabReceiverTurns, notification, route.turnId);
+        if (childParentTurnId && shouldSuppressChildConversationNotification(notification.method)) {
+          yield* Ref.set(collabReceiverTurnsRef, collabReceiverTurns);
+          return;
+        }
+
+        let requestId: ApprovalRequestId | undefined;
+        let requestKind: ProviderRequestKind | undefined;
+        let turnId = childParentTurnId ?? route.turnId;
+        let itemId = route.itemId;
+
+        if (notification.method === "serverRequest/resolved") {
+          const rawRequestId =
+            typeof notification.params.requestId === "string"
+              ? notification.params.requestId
+              : String(notification.params.requestId);
+          const correlation = rawRequestId
+            ? (yield* Ref.get(approvalCorrelationsRef)).get(rawRequestId)
+            : undefined;
+          if (correlation) {
+            requestId = correlation.requestId;
+            requestKind = correlation.requestKind;
+            turnId = correlation.turnId ?? turnId;
+            itemId = correlation.itemId ?? itemId;
+            yield* Ref.update(approvalCorrelationsRef, (current) => {
+              const next = new Map(current);
+              next.delete(rawRequestId);
+              return next;
+            });
+          }
+        }
+
+        yield* Ref.set(collabReceiverTurnsRef, collabReceiverTurns);
+        yield* emitEvent({
+          kind: "notification",
+          threadId: options.threadId,
+          method: notification.method,
+          ...(turnId ? { turnId } : {}),
+          ...(itemId ? { itemId } : {}),
+          ...(requestId ? { requestId } : {}),
+          ...(requestKind ? { requestKind } : {}),
+          ...(notification.method === "item/agentMessage/delta"
+            ? { textDelta: notification.params.delta }
+            : {}),
+          ...(payload !== undefined ? { payload } : {}),
+        });
+      });
+
+    const currentSessionProviderThreadId = Effect.map(Ref.get(sessionRef), currentProviderThreadId);
+
+    yield* client.handleServerNotification("thread/started", (payload) =>
+      currentSessionProviderThreadId.pipe(
+        Effect.flatMap((providerThreadId) => {
+          if (providerThreadId && payload.thread.id !== providerThreadId) {
+            return Effect.void;
+          }
+          return updateSession(sessionRef, {
+            resumeCursor: { threadId: payload.thread.id },
+          });
+        }),
+      ),
+    );
+
+    yield* client.handleServerNotification("turn/started", (payload) =>
+      currentSessionProviderThreadId.pipe(
+        Effect.flatMap((providerThreadId) => {
+          if (providerThreadId && payload.threadId !== providerThreadId) {
+            return Effect.void;
+          }
+          return updateSession(sessionRef, {
+            status: "running",
+            activeTurnId: TurnId.make(payload.turn.id),
+          });
+        }),
+      ),
+    );
+
+    yield* client.handleServerNotification("turn/completed", (payload) =>
+      currentSessionProviderThreadId.pipe(
+        Effect.flatMap((providerThreadId) => {
+          if (providerThreadId && payload.threadId !== providerThreadId) {
+            return Effect.void;
+          }
+          const lastError =
+            payload.turn.status === "failed" && "error" in payload.turn && payload.turn.error
+              ? payload.turn.error.message
+              : undefined;
+          return updateSession(sessionRef, {
+            status: payload.turn.status === "failed" ? "error" : "ready",
+            activeTurnId: undefined,
+            ...(lastError ? { lastError } : {}),
+          });
+        }),
+      ),
+    );
+
+    yield* client.handleServerNotification("error", (payload) =>
+      currentSessionProviderThreadId.pipe(
+        Effect.flatMap((providerThreadId) => {
+          const payloadThreadId = payload.threadId;
+          if (providerThreadId && payloadThreadId && payloadThreadId !== providerThreadId) {
+            return Effect.void;
+          }
+          const errorMessage = payload.error.message;
+          const willRetry = payload.willRetry;
+          return updateSession(sessionRef, {
+            status: willRetry ? "running" : "error",
+            ...(errorMessage ? { lastError: errorMessage } : {}),
+          });
+        }),
+      ),
+    );
+
+    yield* client.handleServerRequest("item/commandExecution/requestApproval", (payload) =>
+      Effect.gen(function* () {
+        const requestId = ApprovalRequestId.make(yield* Random.nextUUIDv4);
+        const turnId = TurnId.make(payload.turnId);
+        const itemId = ProviderItemId.make(payload.itemId);
+        const decision = yield* Deferred.make<ProviderApprovalDecision>();
+
+        yield* Ref.update(pendingApprovalsRef, (current) => {
+          const next = new Map(current);
+          next.set(requestId, {
+            requestId,
+            jsonRpcId: payload.approvalId ?? payload.itemId,
+            requestKind: "command",
+            turnId,
+            itemId,
+            decision,
+          });
+          return next;
+        });
+        yield* Ref.update(approvalCorrelationsRef, (current) => {
+          const next = new Map(current);
+          next.set(payload.approvalId ?? payload.itemId, {
+            requestId,
+            requestKind: "command",
+            turnId,
+            itemId,
+          });
+          return next;
+        });
+
+        yield* emitEvent({
+          kind: "request",
+          threadId: options.threadId,
+          method: "item/commandExecution/requestApproval",
+          requestId,
+          requestKind: "command",
+          ...(turnId ? { turnId } : {}),
+          ...(itemId ? { itemId } : {}),
+          payload,
+        });
+
+        const resolved = yield* Deferred.await(decision).pipe(
+          Effect.ensuring(
+            Ref.update(pendingApprovalsRef, (current) => {
+              const next = new Map(current);
+              next.delete(requestId);
+              return next;
+            }),
+          ),
+        );
+        return {
+          decision: resolved,
+        } satisfies EffectCodexSchema.CommandExecutionRequestApprovalResponse;
+      }),
+    );
+
+    yield* client.handleServerRequest("item/fileChange/requestApproval", (payload) =>
+      Effect.gen(function* () {
+        const requestId = ApprovalRequestId.make(yield* Random.nextUUIDv4);
+        const turnId = TurnId.make(payload.turnId);
+        const itemId = ProviderItemId.make(payload.itemId);
+        const decision = yield* Deferred.make<ProviderApprovalDecision>();
+
+        yield* Ref.update(pendingApprovalsRef, (current) => {
+          const next = new Map(current);
+          next.set(requestId, {
+            requestId,
+            jsonRpcId: payload.itemId,
+            requestKind: "file-change",
+            turnId,
+            itemId,
+            decision,
+          });
+          return next;
+        });
+        yield* Ref.update(approvalCorrelationsRef, (current) => {
+          const next = new Map(current);
+          next.set(payload.itemId, {
+            requestId,
+            requestKind: "file-change",
+            turnId,
+            itemId,
+          });
+          return next;
+        });
+
+        yield* emitEvent({
+          kind: "request",
+          threadId: options.threadId,
+          method: "item/fileChange/requestApproval",
+          requestId,
+          requestKind: "file-change",
+          ...(turnId ? { turnId } : {}),
+          ...(itemId ? { itemId } : {}),
+          payload,
+        });
+
+        const resolved = yield* Deferred.await(decision).pipe(
+          Effect.ensuring(
+            Ref.update(pendingApprovalsRef, (current) => {
+              const next = new Map(current);
+              next.delete(requestId);
+              return next;
+            }),
+          ),
+        );
+        return {
+          decision: resolved,
+        } satisfies EffectCodexSchema.FileChangeRequestApprovalResponse;
+      }),
+    );
+
+    yield* client.handleServerRequest("item/tool/requestUserInput", (payload) =>
+      Effect.gen(function* () {
+        const requestId = ApprovalRequestId.make(yield* Random.nextUUIDv4);
+        const turnId = TurnId.make(payload.turnId);
+        const itemId = ProviderItemId.make(payload.itemId);
+        const answers = yield* Deferred.make<ProviderUserInputAnswers>();
+
+        yield* Ref.update(pendingUserInputsRef, (current) => {
+          const next = new Map(current);
+          next.set(requestId, {
+            requestId,
+            turnId,
+            itemId,
+            answers,
+          });
+          return next;
+        });
+
+        yield* emitEvent({
+          kind: "request",
+          threadId: options.threadId,
+          method: "item/tool/requestUserInput",
+          requestId,
+          ...(turnId ? { turnId } : {}),
+          ...(itemId ? { itemId } : {}),
+          payload,
+        });
+
+        const resolvedAnswers = yield* Deferred.await(answers).pipe(
+          Effect.ensuring(
+            Ref.update(pendingUserInputsRef, (current) => {
+              const next = new Map(current);
+              next.delete(requestId);
+              return next;
+            }),
+          ),
+        );
+
+        return {
+          answers: yield* toCodexUserInputAnswers(resolvedAnswers).pipe(
+            Effect.mapError((error) =>
+              CodexErrors.CodexAppServerRequestError.invalidParams(error.message, {
+                questionId: error.questionId,
+              }),
+            ),
+          ),
+        } satisfies EffectCodexSchema.ToolRequestUserInputResponse;
+      }),
+    );
+
+    yield* client.handleUnknownServerRequest((method) =>
+      Effect.fail(CodexErrors.CodexAppServerRequestError.methodNotFound(method)),
+    );
+
+    const registerServerNotification = <M extends CodexRpc.ServerNotificationMethod>(method: M) =>
+      client.handleServerNotification(method, (params) =>
+        Queue.offer(serverNotifications, makeCodexServerNotification(method, params)).pipe(
+          Effect.asVoid,
+        ),
+      );
+
+    yield* Effect.forEach(
+      Object.values(
+        CodexRpc.SERVER_NOTIFICATION_METHODS,
+      ) as ReadonlyArray<CodexRpc.ServerNotificationMethod>,
+      registerServerNotification,
+      { concurrency: 1, discard: true },
+    );
+
+    yield* Stream.fromQueue(serverNotifications).pipe(
+      Stream.runForEach(handleRawNotification),
+      Effect.forkIn(runtimeScope),
+    );
+
+    const stderrRemainderRef = yield* Ref.make("");
+    yield* child.stderr.pipe(
+      Stream.decodeText(),
+      Stream.runForEach((chunk) =>
+        Ref.modify(stderrRemainderRef, (current) => {
+          const combined = current + chunk;
+          const lines = combined.split("\n");
+          const remainder = lines.pop() ?? "";
+          return [lines.map((line) => line.replace(/\r$/, "")), remainder] as const;
+        }).pipe(
+          Effect.flatMap((lines) =>
+            Effect.forEach(
+              lines,
+              (line) => {
+                const classified = classifyCodexStderrLine(line);
+                if (!classified) {
+                  return Effect.void;
+                }
+                return emitEvent({
+                  kind: "notification",
+                  threadId: options.threadId,
+                  method: "process/stderr",
+                  message: classified.message,
+                });
+              },
+              { discard: true },
+            ),
+          ),
+        ),
+      ),
+      Effect.forkIn(runtimeScope),
+    );
+
+    yield* child.exitCode.pipe(
+      Effect.flatMap((exitCode) =>
+        Ref.get(closedRef).pipe(
+          Effect.flatMap((closed) => {
+            if (closed) {
+              return Effect.void;
+            }
+            const nextStatus = exitCode === 0 ? "closed" : "error";
+            return updateSession(sessionRef, {
+              status: nextStatus,
+              activeTurnId: undefined,
+            }).pipe(
+              Effect.andThen(
+                emitSessionEvent(
+                  "session/exited",
+                  exitCode === 0
+                    ? "Codex App Server exited."
+                    : `Codex App Server exited with code ${exitCode}.`,
+                ),
+              ),
+            );
+          }),
+        ),
+      ),
+      Effect.forkIn(runtimeScope),
+    );
+
+    const start = Effect.fn("CodexSessionRuntime.start")(function* () {
+      yield* emitSessionEvent("session/connecting", "Starting Codex App Server session.");
+      yield* client.request("initialize", buildCodexInitializeParams());
+      yield* client.notify("initialized", undefined);
+
+      const requestedModel = normalizeCodexModelSlug(options.model);
+
+      const opened = yield* openCodexThread({
+        client,
+        threadId: options.threadId,
+        runtimeMode: options.runtimeMode,
+        cwd: options.cwd,
+        requestedModel,
+        serviceTier: options.serviceTier,
+        resumeThreadId: readResumeCursorThreadId(options.resumeCursor),
+      });
+
+      const providerThreadId = opened.thread.id;
+      const session = {
+        ...(yield* Ref.get(sessionRef)),
+        status: "ready",
+        cwd: opened.cwd,
+        model: opened.model,
+        resumeCursor: { threadId: providerThreadId },
+        updatedAt: yield* nowIso,
+      } satisfies ProviderSession;
+      yield* Ref.set(sessionRef, session);
+      yield* emitSessionEvent("session/ready", "Codex App Server session ready.");
+      return session;
+    });
+
+    const readProviderThreadId = Effect.gen(function* () {
+      const providerThreadId = currentProviderThreadId(yield* Ref.get(sessionRef));
+      if (!providerThreadId) {
+        return yield* new CodexSessionRuntimeThreadIdMissingError({
+          threadId: options.threadId,
+        });
+      }
+      return providerThreadId;
+    });
+
+    const close = Effect.gen(function* () {
+      const alreadyClosed = yield* Ref.getAndSet(closedRef, true);
+      if (alreadyClosed) {
+        return;
+      }
+      yield* settlePendingApprovals("cancel");
+      yield* settlePendingUserInputs({});
+      yield* updateSession(sessionRef, {
+        status: "closed",
+        activeTurnId: undefined,
+      });
+      yield* emitSessionEvent("session/closed", "Session stopped");
+      yield* Scope.close(runtimeScope, Exit.void);
+      yield* Queue.shutdown(serverNotifications);
+      yield* Queue.shutdown(events);
+    });
+
+    return {
+      start,
+      getSession: Ref.get(sessionRef),
+      sendTurn: (input) =>
+        Effect.gen(function* () {
+          const providerThreadId = yield* readProviderThreadId;
+          const normalizedModel = normalizeCodexModelSlug(
+            input.model ?? (yield* Ref.get(sessionRef)).model,
+          );
+          const params = yield* buildTurnStartParams({
+            threadId: providerThreadId,
+            runtimeMode: options.runtimeMode,
+            ...(input.input ? { prompt: input.input } : {}),
+            ...(input.attachments ? { attachments: input.attachments } : {}),
+            ...(normalizedModel ? { model: normalizedModel } : {}),
+            ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
+            ...(input.effort ? { effort: input.effort } : {}),
+            ...(input.interactionMode ? { interactionMode: input.interactionMode } : {}),
+          });
+          const rawResponse = yield* client.raw.request("turn/start", params);
+          const response = yield* decodeV2TurnStartResponse(rawResponse).pipe(
+            Effect.mapError((error) =>
+              toProtocolParseError("Invalid turn/start response payload", error),
+            ),
+          );
+          const turnId = TurnId.make(response.turn.id);
+          yield* updateSession(sessionRef, {
+            status: "running",
+            activeTurnId: turnId,
+            ...(normalizedModel ? { model: normalizedModel } : {}),
+          });
+          const resumedProviderThreadId = currentProviderThreadId(yield* Ref.get(sessionRef));
+          return {
+            threadId: options.threadId,
+            turnId,
+            ...(resumedProviderThreadId
+              ? { resumeCursor: { threadId: resumedProviderThreadId } }
+              : {}),
+          } satisfies ProviderTurnStartResult;
+        }),
+      interruptTurn: (turnId) =>
+        Effect.gen(function* () {
+          const providerThreadId = yield* readProviderThreadId;
+          const session = yield* Ref.get(sessionRef);
+          const effectiveTurnId = turnId ?? session.activeTurnId;
+          if (!effectiveTurnId) {
+            return;
+          }
+          yield* client.request("turn/interrupt", {
+            threadId: providerThreadId,
+            turnId: effectiveTurnId,
+          });
+        }),
+      readThread: Effect.gen(function* () {
+        const providerThreadId = yield* readProviderThreadId;
+        const response = yield* client.request("thread/read", {
+          threadId: providerThreadId,
+          includeTurns: true,
+        });
+        return parseThreadSnapshot(response);
+      }),
+      rollbackThread: (numTurns) =>
+        Effect.gen(function* () {
+          const providerThreadId = yield* readProviderThreadId;
+          const response = yield* client.request("thread/rollback", {
+            threadId: providerThreadId,
+            numTurns,
+          });
+          yield* updateSession(sessionRef, {
+            status: "ready",
+            activeTurnId: undefined,
+          });
+          return parseThreadSnapshot(response);
+        }),
+      respondToRequest: (requestId, decision) =>
+        Effect.gen(function* () {
+          const pending = (yield* Ref.get(pendingApprovalsRef)).get(requestId);
+          if (!pending) {
+            return yield* new CodexSessionRuntimePendingApprovalNotFoundError({
+              requestId,
+            });
+          }
+          yield* Ref.update(pendingApprovalsRef, (current) => {
+            const next = new Map(current);
+            next.delete(requestId);
+            return next;
+          });
+          yield* Deferred.succeed(pending.decision, decision);
+          yield* emitEvent({
+            kind: "notification",
+            threadId: options.threadId,
+            method: "item/requestApproval/decision",
+            requestId: pending.requestId,
+            requestKind: pending.requestKind,
+            ...(pending.turnId ? { turnId: pending.turnId } : {}),
+            ...(pending.itemId ? { itemId: pending.itemId } : {}),
+            payload: {
+              requestId: pending.requestId,
+              requestKind: pending.requestKind,
+              decision,
+            },
+          });
+        }),
+      respondToUserInput: (requestId, answers) =>
+        Effect.gen(function* () {
+          const pending = (yield* Ref.get(pendingUserInputsRef)).get(requestId);
+          if (!pending) {
+            return yield* new CodexSessionRuntimePendingUserInputNotFoundError({
+              requestId,
+            });
+          }
+          const codexAnswers = yield* toCodexUserInputAnswers(answers);
+          yield* Ref.update(pendingUserInputsRef, (current) => {
+            const next = new Map(current);
+            next.delete(requestId);
+            return next;
+          });
+          yield* Deferred.succeed(pending.answers, answers);
+          yield* emitEvent({
+            kind: "notification",
+            threadId: options.threadId,
+            method: "item/tool/requestUserInput/answered",
+            requestId: pending.requestId,
+            ...(pending.turnId ? { turnId: pending.turnId } : {}),
+            ...(pending.itemId ? { itemId: pending.itemId } : {}),
+            payload: {
+              answers: codexAnswers,
+            },
+          });
+        }),
+      events: Stream.fromQueue(events),
+      close,
+    } satisfies CodexSessionRuntimeShape;
+  });
diff --git a/apps/server/src/provider/Layers/CursorAdapter.test.ts b/apps/server/src/provider/Layers/CursorAdapter.test.ts
new file mode 100644
index 00000000000..43644fd6f49
--- /dev/null
+++ b/apps/server/src/provider/Layers/CursorAdapter.test.ts
@@ -0,0 +1,1316 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as path from "node:path";
+import * as os from "node:os";
+import { chmod, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { createModelSelection } from "@t3tools/shared/model";
+
+import {
+  ApprovalRequestId,
+  CursorSettings,
+  ProviderDriverKind,
+  type ProviderRuntimeEvent,
+  ThreadId,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
+
+import { ServerConfig } from "../../config.ts";
+import { ServerSettingsService } from "../../serverSettings.ts";
+import type { CursorAdapterShape } from "../Services/CursorAdapter.ts";
+import { makeCursorAdapter } from "./CursorAdapter.ts";
+const decodeCursorSettings = Schema.decodeSync(CursorSettings);
+
+// Test-local service tag so the rest of the file can keep using `yield* CursorAdapter`.
+class CursorAdapter extends Context.Service<CursorAdapter, CursorAdapterShape>()(
+  "test/CursorAdapter",
+) {}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const mockAgentPath = path.join(__dirname, "../../../scripts/acp-mock-agent.ts");
+const bunExe = "bun";
+
+async function makeMockAgentWrapper(
+  extraEnv?: Record<string, string>,
+  options?: { initialDelaySeconds?: number },
+) {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "cursor-acp-mock-"));
+  const wrapperPath = path.join(dir, "fake-agent.sh");
+  const envExports = Object.entries(extraEnv ?? {})
+    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
+    .join("\n");
+  const script = `#!/bin/sh
+${envExports}
+${options?.initialDelaySeconds ? `sleep ${JSON.stringify(String(options.initialDelaySeconds))}` : ""}
+exec ${JSON.stringify(bunExe)} ${JSON.stringify(mockAgentPath)} "$@"
+`;
+  await writeFile(wrapperPath, script, "utf8");
+  await chmod(wrapperPath, 0o755);
+  return wrapperPath;
+}
+
+async function makeProbeWrapper(
+  requestLogPath: string,
+  argvLogPath: string,
+  extraEnv?: Record<string, string>,
+) {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "cursor-acp-probe-"));
+  const wrapperPath = path.join(dir, "fake-agent.sh");
+  const envExports = Object.entries(extraEnv ?? {})
+    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
+    .join("\n");
+  const script = `#!/bin/sh
+printf '%s\t' "$@" >> ${JSON.stringify(argvLogPath)}
+printf '\n' >> ${JSON.stringify(argvLogPath)}
+export T3_ACP_REQUEST_LOG_PATH=${JSON.stringify(requestLogPath)}
+${envExports}
+exec ${JSON.stringify(bunExe)} ${JSON.stringify(mockAgentPath)} "$@"
+`;
+  await writeFile(wrapperPath, script, "utf8");
+  await chmod(wrapperPath, 0o755);
+  return wrapperPath;
+}
+
+async function readArgvLog(filePath: string) {
+  const raw = await readFile(filePath, "utf8");
+  return raw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => line.split("\t").filter((token) => token.length > 0));
+}
+
+async function readJsonLines(filePath: string) {
+  const raw = await readFile(filePath, "utf8");
+  return raw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as Record<string, unknown>);
+}
+
+async function waitForFileContent(filePath: string, attempts = 40) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      const raw = await readFile(filePath, "utf8");
+      if (raw.trim().length > 0) {
+        return raw;
+      }
+    } catch {}
+    await Effect.runPromise(Effect.yieldNow);
+  }
+  throw new Error(`Timed out waiting for file content at ${filePath}`);
+}
+
+// Tests mutate `ServerSettingsService` mid-flight (e.g. setting
+// `providers.cursor.binaryPath` to a mock ACP wrapper). The adapter
+// captures `cursorSettings` once at construction, so without a resolver
+// the mutation is invisible — sessions would spawn the constructor's
+// (empty) binary path. Wiring `resolveSettings` through
+// `ServerSettingsService.getSettings` makes each session read the latest
+// snapshot, matching the old "always read live" behavior that these
+// tests assumed.
+const makeResolveCursorSettings = Effect.gen(function* () {
+  const serverSettings = yield* ServerSettingsService;
+  return yield* Effect.succeed(
+    serverSettings.getSettings.pipe(
+      Effect.map((snapshot) => snapshot.providers.cursor),
+      Effect.orDie,
+    ),
+  );
+});
+
+const cursorAdapterTestLayer = it.layer(
+  Layer.effect(
+    CursorAdapter,
+    Effect.gen(function* () {
+      const cursorConfig = decodeCursorSettings({});
+      const resolveSettings = yield* makeResolveCursorSettings;
+      return yield* makeCursorAdapter(cursorConfig, { resolveSettings });
+    }),
+  ).pipe(
+    Layer.provideMerge(ServerSettingsService.layerTest()),
+    Layer.provideMerge(
+      ServerConfig.layerTest(process.cwd(), {
+        prefix: "t3code-cursor-adapter-test-",
+      }),
+    ),
+    Layer.provideMerge(NodeServices.layer),
+  ),
+);
+
+cursorAdapterTestLayer("CursorAdapterLive", (it) => {
+  it.effect("starts a session and maps mock ACP prompt flow to runtime events", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const settings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-mock-thread");
+
+      const wrapperPath = yield* Effect.promise(() => makeMockAgentWrapper());
+      yield* settings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 9).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      const session = yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      assert.equal(session.provider, "cursor");
+      assert.deepStrictEqual(session.resumeCursor, {
+        schemaVersion: 1,
+        sessionId: "mock-session-1",
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "hello mock",
+        attachments: [],
+      });
+
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+      const types = runtimeEvents.map((e) => e.type);
+
+      for (const t of [
+        "session.started",
+        "session.state.changed",
+        "thread.started",
+        "turn.started",
+        "turn.plan.updated",
+        "item.started",
+        "content.delta",
+        "item.completed",
+        "turn.completed",
+      ] as const) {
+        assert.include(types, t);
+      }
+
+      const assistantStarted = runtimeEvents.find(
+        (event) => event.type === "item.started" && event.payload.itemType === "assistant_message",
+      );
+      assert.isDefined(assistantStarted);
+
+      const delta = runtimeEvents.find((e) => e.type === "content.delta");
+      assert.isDefined(delta);
+      if (delta?.type === "content.delta") {
+        assert.equal(delta.payload.delta, "hello from mock");
+        assert.match(String(delta.itemId), /^assistant:mock-session-1:segment:0$/);
+      }
+
+      const assistantCompleted = runtimeEvents.find(
+        (event) =>
+          event.type === "item.completed" && event.payload.itemType === "assistant_message",
+      );
+      assert.isDefined(assistantCompleted);
+
+      const planUpdate = runtimeEvents.find((event) => event.type === "turn.plan.updated");
+      assert.isDefined(planUpdate);
+      if (planUpdate?.type === "turn.plan.updated") {
+        assert.deepStrictEqual(planUpdate.payload.plan, [
+          { step: "Inspect mock ACP state", status: "completed" },
+          { step: "Implement the requested change", status: "inProgress" },
+        ]);
+      }
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("closes the ACP child process when a session stops", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const settings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-stop-session-close");
+      const tempDir = yield* Effect.promise(() =>
+        mkdtemp(path.join(os.tmpdir(), "cursor-adapter-exit-log-")),
+      );
+      const exitLogPath = path.join(tempDir, "exit.log");
+
+      const wrapperPath = yield* Effect.promise(() =>
+        makeMockAgentWrapper({
+          T3_ACP_EXIT_LOG_PATH: exitLogPath,
+        }),
+      );
+      yield* settings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      yield* adapter.stopSession(threadId);
+
+      const exitLog = yield* Effect.promise(() => waitForFileContent(exitLogPath));
+      assert.include(exitLog, "SIGTERM");
+    }),
+  );
+
+  it.effect(
+    "serializes concurrent startSession calls for the same thread and closes the replaced ACP session",
+    () =>
+      Effect.gen(function* () {
+        const adapter = yield* CursorAdapter;
+        const settings = yield* ServerSettingsService;
+        const threadId = ThreadId.make("cursor-concurrent-start-session");
+        const tempDir = yield* Effect.promise(() =>
+          mkdtemp(path.join(os.tmpdir(), "cursor-adapter-concurrent-exit-log-")),
+        );
+        const exitLogPath = path.join(tempDir, "exit.log");
+
+        const wrapperPath = yield* Effect.promise(() =>
+          makeMockAgentWrapper(
+            {
+              T3_ACP_EXIT_LOG_PATH: exitLogPath,
+            },
+            { initialDelaySeconds: 0.2 },
+          ),
+        );
+        yield* settings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+        const [firstSession, secondSession] = yield* Effect.all(
+          [
+            adapter.startSession({
+              threadId,
+              provider: ProviderDriverKind.make("cursor"),
+              cwd: process.cwd(),
+              runtimeMode: "full-access",
+              modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+            }),
+            adapter.startSession({
+              threadId,
+              provider: ProviderDriverKind.make("cursor"),
+              cwd: process.cwd(),
+              runtimeMode: "full-access",
+              modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+            }),
+          ],
+          { concurrency: "unbounded" },
+        );
+
+        assert.equal(firstSession.threadId, threadId);
+        assert.equal(secondSession.threadId, threadId);
+
+        yield* adapter.stopSession(threadId);
+
+        const exitLog = yield* Effect.promise(() => waitForFileContent(exitLogPath));
+        assert.equal(exitLog.match(/SIGTERM/g)?.length ?? 0, 2);
+      }),
+  );
+
+  it.effect("rejects startSession when provider mismatches", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const result = yield* adapter
+        .startSession({
+          threadId: ThreadId.make("bad-provider"),
+          provider: ProviderDriverKind.make("codex"),
+          cwd: process.cwd(),
+          runtimeMode: "full-access",
+        })
+        .pipe(Effect.result);
+
+      assert.equal(result._tag, "Failure");
+    }),
+  );
+
+  it.effect("maps app plan mode onto the ACP plan session mode", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-plan-mode-probe");
+      const tempDir = yield* Effect.promise(() => mkdtemp(path.join(os.tmpdir(), "cursor-acp-")));
+      const requestLogPath = path.join(tempDir, "requests.ndjson");
+      const argvLogPath = path.join(tempDir, "argv.txt");
+      yield* Effect.promise(() => writeFile(requestLogPath, "", "utf8"));
+      const wrapperPath = yield* Effect.promise(() =>
+        makeProbeWrapper(requestLogPath, argvLogPath),
+      );
+      yield* serverSettings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "composer-2" },
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "plan this change",
+        attachments: [],
+        interactionMode: "plan",
+      });
+      yield* adapter.stopSession(threadId);
+
+      const requests = yield* Effect.promise(() => readJsonLines(requestLogPath));
+      const modeRequest = requests
+        .toReversed()
+        .find(
+          (entry) =>
+            entry.method === "session/set_mode" ||
+            (entry.method === "session/set_config_option" &&
+              (entry.params as Record<string, unknown> | undefined)?.configId === "mode"),
+        );
+      assert.isDefined(modeRequest);
+      assert.equal(
+        (modeRequest?.params as Record<string, unknown> | undefined)?.sessionId,
+        "mock-session-1",
+      );
+      assert.include(
+        ["architect", "plan"],
+        String(
+          (modeRequest?.params as Record<string, unknown> | undefined)?.modeId ??
+            (modeRequest?.params as Record<string, unknown> | undefined)?.value,
+        ),
+      );
+    }),
+  );
+
+  it.effect(
+    "applies initial model and mode configuration during startSession and skips repeating it on first send",
+    () =>
+      Effect.gen(function* () {
+        const adapter = yield* CursorAdapter;
+        const serverSettings = yield* ServerSettingsService;
+        const threadId = ThreadId.make("cursor-initial-config-probe");
+        const tempDir = yield* Effect.promise(() => mkdtemp(path.join(os.tmpdir(), "cursor-acp-")));
+        const requestLogPath = path.join(tempDir, "requests.ndjson");
+        const argvLogPath = path.join(tempDir, "argv.txt");
+        yield* Effect.promise(() => writeFile(requestLogPath, "", "utf8"));
+        const wrapperPath = yield* Effect.promise(() =>
+          makeProbeWrapper(requestLogPath, argvLogPath),
+        );
+        yield* serverSettings.updateSettings({
+          providers: { cursor: { binaryPath: wrapperPath } },
+        });
+
+        const modelSelection = createModelSelection(ProviderInstanceId.make("cursor"), "gpt-5.4", [
+          { id: "reasoning", value: "xhigh" },
+          { id: "contextWindow", value: "1m" },
+          { id: "fastMode", value: true },
+        ]);
+
+        yield* adapter.startSession({
+          threadId,
+          provider: ProviderDriverKind.make("cursor"),
+          cwd: process.cwd(),
+          runtimeMode: "full-access",
+          modelSelection,
+        });
+
+        yield* Effect.promise(() => waitForFileContent(requestLogPath));
+
+        const requestsAfterStart = yield* Effect.promise(() => readJsonLines(requestLogPath));
+        const configIdsAfterStart = requestsAfterStart.flatMap((entry) =>
+          entry.method === "session/set_config_option" &&
+          typeof (entry.params as Record<string, unknown> | undefined)?.configId === "string"
+            ? [String((entry.params as Record<string, unknown>).configId)]
+            : [],
+        );
+        assert.deepStrictEqual(configIdsAfterStart, [
+          "model",
+          "reasoning",
+          "context",
+          "fast",
+          "mode",
+        ]);
+
+        yield* adapter.sendTurn({
+          threadId,
+          input: "hello mock",
+          attachments: [],
+          modelSelection,
+          interactionMode: "default",
+        });
+        yield* adapter.stopSession(threadId);
+
+        const finalRequests = yield* Effect.promise(() => readJsonLines(requestLogPath));
+        const finalConfigIds = finalRequests.flatMap((entry) =>
+          entry.method === "session/set_config_option" &&
+          typeof (entry.params as Record<string, unknown> | undefined)?.configId === "string"
+            ? [String((entry.params as Record<string, unknown>).configId)]
+            : [],
+        );
+        assert.deepStrictEqual(finalConfigIds, ["model", "reasoning", "context", "fast", "mode"]);
+        assert.equal(finalRequests.filter((entry) => entry.method === "session/prompt").length, 1);
+      }),
+  );
+
+  it.effect(
+    "streams ACP tool calls and approvals on the active turn in approval-required mode",
+    () =>
+      Effect.gen(function* () {
+        const previousEmitToolCalls = process.env.T3_ACP_EMIT_TOOL_CALLS;
+        process.env.T3_ACP_EMIT_TOOL_CALLS = "1";
+
+        const adapter = yield* CursorAdapter;
+        const serverSettings = yield* ServerSettingsService;
+        const threadId = ThreadId.make("cursor-tool-call-probe");
+        const runtimeEvents: Array<ProviderRuntimeEvent> = [];
+        const settledEventTypes = new Set<string>();
+        const settledEventsReady = yield* Deferred.make<void>();
+
+        const wrapperPath = yield* Effect.promise(() =>
+          makeMockAgentWrapper({ T3_ACP_EMIT_TOOL_CALLS: "1" }),
+        );
+        yield* serverSettings.updateSettings({
+          providers: { cursor: { binaryPath: wrapperPath } },
+        });
+
+        yield* Stream.runForEach(adapter.streamEvents, (event) =>
+          Effect.gen(function* () {
+            runtimeEvents.push(event);
+            if (String(event.threadId) !== String(threadId)) {
+              return;
+            }
+            if (event.type === "request.opened" && event.requestId) {
+              yield* adapter.respondToRequest(
+                threadId,
+                ApprovalRequestId.make(String(event.requestId)),
+                "accept",
+              );
+            }
+            if (
+              event.type === "turn.completed" ||
+              (event.type === "item.completed" && event.payload.itemType === "command_execution") ||
+              event.type === "content.delta"
+            ) {
+              settledEventTypes.add(event.type);
+              if (settledEventTypes.size === 3) {
+                yield* Deferred.succeed(settledEventsReady, undefined).pipe(Effect.orDie);
+              }
+            }
+          }),
+        ).pipe(Effect.forkChild);
+
+        const program = Effect.gen(function* () {
+          yield* adapter.startSession({
+            threadId,
+            provider: ProviderDriverKind.make("cursor"),
+            cwd: process.cwd(),
+            runtimeMode: "approval-required",
+            modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+          });
+
+          const turn = yield* adapter.sendTurn({
+            threadId,
+            input: "run a tool call",
+            attachments: [],
+          });
+          yield* Deferred.await(settledEventsReady);
+
+          const threadEvents = runtimeEvents.filter(
+            (event) => String(event.threadId) === String(threadId),
+          );
+          assert.includeMembers(
+            threadEvents.map((event) => event.type),
+            [
+              "session.started",
+              "session.state.changed",
+              "thread.started",
+              "turn.started",
+              "request.opened",
+              "request.resolved",
+              "item.updated",
+              "item.completed",
+              "content.delta",
+              "turn.completed",
+            ],
+          );
+
+          const turnEvents = threadEvents.filter(
+            (event) => String(event.turnId) === String(turn.turnId),
+          );
+          const toolUpdates = turnEvents.filter((event) => event.type === "item.updated");
+          // ACP updates can arrive either as distinct pending + in-progress events
+          // or as a single coalesced in-progress update before approval resolves.
+          assert.isAtLeast(toolUpdates.length, 1);
+          for (const toolUpdate of toolUpdates) {
+            if (toolUpdate.type !== "item.updated") {
+              continue;
+            }
+            assert.equal(toolUpdate.payload.itemType, "command_execution");
+            assert.equal(toolUpdate.payload.status, "inProgress");
+            assert.equal(toolUpdate.payload.detail, "cat server/package.json");
+            assert.equal(String(toolUpdate.itemId), "tool-call-1");
+          }
+
+          const requestOpened = turnEvents.find((event) => event.type === "request.opened");
+          assert.isDefined(requestOpened);
+          if (requestOpened?.type === "request.opened") {
+            assert.equal(String(requestOpened.turnId), String(turn.turnId));
+            assert.equal(requestOpened.payload.requestType, "exec_command_approval");
+            assert.equal(requestOpened.payload.detail, "cat server/package.json");
+          }
+
+          const requestResolved = turnEvents.find((event) => event.type === "request.resolved");
+          assert.isDefined(requestResolved);
+          if (requestResolved?.type === "request.resolved") {
+            assert.equal(String(requestResolved.turnId), String(turn.turnId));
+            assert.equal(requestResolved.payload.requestType, "exec_command_approval");
+            assert.equal(requestResolved.payload.decision, "accept");
+          }
+
+          const toolCompleted = turnEvents.find(
+            (event) =>
+              event.type === "item.completed" && event.payload.itemType === "command_execution",
+          );
+          assert.isDefined(toolCompleted);
+          if (toolCompleted?.type === "item.completed") {
+            assert.equal(String(toolCompleted.turnId), String(turn.turnId));
+            assert.equal(toolCompleted.payload.itemType, "command_execution");
+            assert.equal(toolCompleted.payload.status, "completed");
+            assert.equal(toolCompleted.payload.detail, "cat server/package.json");
+            assert.equal(String(toolCompleted.itemId), "tool-call-1");
+          }
+
+          const contentDelta = turnEvents.find((event) => event.type === "content.delta");
+          assert.isDefined(contentDelta);
+          if (contentDelta?.type === "content.delta") {
+            assert.equal(String(contentDelta.turnId), String(turn.turnId));
+            assert.equal(contentDelta.payload.delta, "hello from mock");
+            assert.equal(String(contentDelta.itemId), "assistant:mock-session-1:segment:0");
+          }
+        });
+
+        yield* program.pipe(
+          Effect.ensuring(
+            Effect.sync(() => {
+              if (previousEmitToolCalls === undefined) {
+                delete process.env.T3_ACP_EMIT_TOOL_CALLS;
+              } else {
+                process.env.T3_ACP_EMIT_TOOL_CALLS = previousEmitToolCalls;
+              }
+            }),
+          ),
+        );
+      }).pipe(
+        Effect.provide(
+          Layer.effect(
+            CursorAdapter,
+            Effect.gen(function* () {
+              const cursorConfig = decodeCursorSettings({});
+              const resolveSettings = yield* makeResolveCursorSettings;
+              return yield* makeCursorAdapter(cursorConfig, { resolveSettings });
+            }),
+          ).pipe(
+            Layer.provideMerge(ServerSettingsService.layerTest()),
+            Layer.provideMerge(
+              ServerConfig.layerTest(process.cwd(), {
+                prefix: "t3code-cursor-adapter-test-",
+              }),
+            ),
+            Layer.provideMerge(NodeServices.layer),
+          ),
+        ),
+      ),
+  );
+
+  it.effect(
+    "auto-approves ACP tool permissions in full-access mode without approval runtime events",
+    () =>
+      Effect.gen(function* () {
+        const adapter = yield* CursorAdapter;
+        const serverSettings = yield* ServerSettingsService;
+        const threadId = ThreadId.make("cursor-full-access-auto-approve");
+        const runtimeEvents: Array<ProviderRuntimeEvent> = [];
+        const settledEventTypes = new Set<string>();
+        const settledEventsReady = yield* Deferred.make<void>();
+        const tempDir = yield* Effect.promise(() => mkdtemp(path.join(os.tmpdir(), "cursor-acp-")));
+        const requestLogPath = path.join(tempDir, "requests.ndjson");
+        const argvLogPath = path.join(tempDir, "argv.txt");
+        yield* Effect.promise(() => writeFile(requestLogPath, "", "utf8"));
+        const wrapperPath = yield* Effect.promise(() =>
+          makeProbeWrapper(requestLogPath, argvLogPath, { T3_ACP_EMIT_TOOL_CALLS: "1" }),
+        );
+        yield* serverSettings.updateSettings({
+          providers: { cursor: { binaryPath: wrapperPath } },
+        });
+
+        const runtimeEventsFiber = yield* Stream.runForEach(adapter.streamEvents, (event) =>
+          Effect.gen(function* () {
+            runtimeEvents.push(event);
+            if (String(event.threadId) !== String(threadId)) {
+              return;
+            }
+            if (
+              event.type === "turn.completed" ||
+              (event.type === "item.completed" && event.payload.itemType === "command_execution") ||
+              event.type === "content.delta"
+            ) {
+              settledEventTypes.add(event.type);
+              if (settledEventTypes.size === 3) {
+                yield* Deferred.succeed(settledEventsReady, undefined).pipe(Effect.orDie);
+              }
+            }
+          }),
+        ).pipe(Effect.forkChild);
+
+        yield* adapter.startSession({
+          threadId,
+          provider: ProviderDriverKind.make("cursor"),
+          cwd: process.cwd(),
+          runtimeMode: "full-access",
+          modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+        });
+
+        const turn = yield* adapter.sendTurn({
+          threadId,
+          input: "run a tool call",
+          attachments: [],
+        });
+
+        yield* Deferred.await(settledEventsReady);
+        yield* Fiber.interrupt(runtimeEventsFiber);
+
+        const turnEvents = runtimeEvents.filter(
+          (event) =>
+            String(event.threadId) === String(threadId) &&
+            String(event.turnId) === String(turn.turnId),
+        );
+        assert.notInclude(
+          turnEvents.map((event) => event.type),
+          "request.opened",
+        );
+        assert.notInclude(
+          turnEvents.map((event) => event.type),
+          "request.resolved",
+        );
+        assert.includeMembers(
+          turnEvents.map((event) => event.type),
+          ["item.updated", "item.completed", "content.delta", "turn.completed"],
+        );
+
+        const requests = yield* Effect.promise(() => readJsonLines(requestLogPath));
+        const permissionResponse = requests.find(
+          (entry) =>
+            !("method" in entry) &&
+            typeof entry.result === "object" &&
+            entry.result !== null &&
+            "outcome" in entry.result &&
+            typeof entry.result.outcome === "object" &&
+            entry.result.outcome !== null &&
+            "outcome" in entry.result.outcome &&
+            entry.result.outcome.outcome === "selected" &&
+            "optionId" in entry.result.outcome &&
+            entry.result.outcome.optionId === "allow-always",
+        );
+        assert.isDefined(permissionResponse);
+
+        yield* adapter.stopSession(threadId);
+      }),
+  );
+
+  it.effect("segments assistant messages around ACP tool activity in full-access mode", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-assistant-tool-segmentation");
+      const runtimeEvents: Array<ProviderRuntimeEvent> = [];
+      const settledEventTypes = new Set<string>();
+      const settledEventsReady = yield* Deferred.make<void>();
+
+      const wrapperPath = yield* Effect.promise(() =>
+        makeMockAgentWrapper({ T3_ACP_EMIT_INTERLEAVED_ASSISTANT_TOOL_CALLS: "1" }),
+      );
+      yield* serverSettings.updateSettings({
+        providers: { cursor: { binaryPath: wrapperPath } },
+      });
+
+      const runtimeEventsFiber = yield* Stream.runForEach(adapter.streamEvents, (event) =>
+        Effect.gen(function* () {
+          runtimeEvents.push(event);
+          if (String(event.threadId) !== String(threadId)) {
+            return;
+          }
+          if (
+            event.type === "content.delta" ||
+            (event.type === "item.completed" && event.payload.itemType === "command_execution") ||
+            event.type === "turn.completed"
+          ) {
+            if (event.type === "content.delta") {
+              settledEventTypes.add(`delta:${event.payload.delta}`);
+            } else {
+              settledEventTypes.add(event.type);
+            }
+            if (
+              settledEventTypes.has("delta:before tool") &&
+              settledEventTypes.has("delta:after tool") &&
+              settledEventTypes.has("item.completed") &&
+              settledEventTypes.has("turn.completed")
+            ) {
+              yield* Deferred.succeed(settledEventsReady, undefined).pipe(Effect.orDie);
+            }
+          }
+        }),
+      ).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      const turn = yield* adapter.sendTurn({
+        threadId,
+        input: "run an interleaved tool call",
+        attachments: [],
+      });
+
+      yield* Deferred.await(settledEventsReady);
+      yield* Fiber.interrupt(runtimeEventsFiber);
+
+      const turnEvents = runtimeEvents.filter(
+        (event) =>
+          String(event.threadId) === String(threadId) &&
+          String(event.turnId) === String(turn.turnId),
+      );
+      const firstAssistantStartIndex = turnEvents.findIndex(
+        (event) => event.type === "item.started" && event.payload.itemType === "assistant_message",
+      );
+      const firstAssistantDeltaIndex = turnEvents.findIndex(
+        (event) => event.type === "content.delta" && event.payload.delta === "before tool",
+      );
+      const assistantBoundaryIndex = turnEvents.findIndex(
+        (event) =>
+          event.type === "item.completed" && event.payload.itemType === "assistant_message",
+      );
+      const toolUpdateIndex = turnEvents.findIndex(
+        (event) => event.type === "item.updated" && event.payload.itemType === "command_execution",
+      );
+      const toolCompletedIndex = turnEvents.findIndex(
+        (event) =>
+          event.type === "item.completed" && event.payload.itemType === "command_execution",
+      );
+      const secondAssistantStartIndex = turnEvents.findIndex(
+        (event, index) =>
+          index > toolCompletedIndex &&
+          event.type === "item.started" &&
+          event.payload.itemType === "assistant_message",
+      );
+      const secondAssistantDeltaIndex = turnEvents.findIndex(
+        (event) => event.type === "content.delta" && event.payload.delta === "after tool",
+      );
+
+      assert.isAtLeast(firstAssistantStartIndex, 0);
+      assert.isAtLeast(firstAssistantDeltaIndex, 0);
+      assert.isAtLeast(assistantBoundaryIndex, 0);
+      assert.isAtLeast(toolUpdateIndex, 0);
+      assert.isAtLeast(toolCompletedIndex, 0);
+      assert.isAtLeast(secondAssistantStartIndex, 0);
+      assert.isAtLeast(secondAssistantDeltaIndex, 0);
+      assert.isBelow(firstAssistantStartIndex, firstAssistantDeltaIndex);
+      assert.isBelow(firstAssistantDeltaIndex, assistantBoundaryIndex);
+      assert.isBelow(assistantBoundaryIndex, toolUpdateIndex);
+      assert.isBelow(toolUpdateIndex, toolCompletedIndex);
+      assert.isBelow(toolCompletedIndex, secondAssistantStartIndex);
+      assert.isBelow(secondAssistantStartIndex, secondAssistantDeltaIndex);
+
+      const assistantStarts = turnEvents.filter(
+        (event) => event.type === "item.started" && event.payload.itemType === "assistant_message",
+      );
+      const assistantDeltas = turnEvents.filter((event) => event.type === "content.delta");
+      assert.lengthOf(assistantStarts, 2);
+      assert.lengthOf(assistantDeltas, 2);
+      if (
+        assistantStarts[0]?.type === "item.started" &&
+        assistantStarts[1]?.type === "item.started" &&
+        assistantDeltas[0]?.type === "content.delta" &&
+        assistantDeltas[1]?.type === "content.delta"
+      ) {
+        assert.notEqual(String(assistantStarts[0].itemId), String(assistantStarts[1].itemId));
+        assert.equal(String(assistantDeltas[0].itemId), String(assistantStarts[0].itemId));
+        assert.equal(String(assistantDeltas[1].itemId), String(assistantStarts[1].itemId));
+      }
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("cancels pending ACP approvals and marks the turn cancelled when interrupted", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-cancel-probe");
+      const tempDir = yield* Effect.promise(() => mkdtemp(path.join(os.tmpdir(), "cursor-acp-")));
+      const requestLogPath = path.join(tempDir, "requests.ndjson");
+      const argvLogPath = path.join(tempDir, "argv.txt");
+      yield* Effect.promise(() => writeFile(requestLogPath, "", "utf8"));
+      const wrapperPath = yield* Effect.promise(() =>
+        makeProbeWrapper(requestLogPath, argvLogPath, { T3_ACP_EMIT_TOOL_CALLS: "1" }),
+      );
+      yield* serverSettings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      const requestResolvedReady = yield* Deferred.make<ProviderRuntimeEvent>();
+      const turnCompletedReady = yield* Deferred.make<ProviderRuntimeEvent>();
+      let interrupted = false;
+
+      const runtimeEventsFiber = yield* Stream.runForEach(adapter.streamEvents, (event) =>
+        Effect.gen(function* () {
+          if (String(event.threadId) !== String(threadId)) {
+            return;
+          }
+          if (event.type === "request.opened" && !interrupted) {
+            interrupted = true;
+            yield* adapter.interruptTurn(threadId);
+            return;
+          }
+          if (event.type === "request.resolved") {
+            yield* Deferred.succeed(requestResolvedReady, event).pipe(Effect.ignore);
+            return;
+          }
+          if (event.type === "turn.completed") {
+            yield* Deferred.succeed(turnCompletedReady, event).pipe(Effect.ignore);
+          }
+        }),
+      ).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "approval-required",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      const sendTurnFiber = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "cancel this turn",
+          attachments: [],
+        })
+        .pipe(Effect.forkChild);
+
+      const requestResolved = yield* Deferred.await(requestResolvedReady);
+      const turnCompleted = yield* Deferred.await(turnCompletedReady);
+      yield* Fiber.join(sendTurnFiber);
+      yield* Fiber.interrupt(runtimeEventsFiber);
+
+      assert.equal(requestResolved.type, "request.resolved");
+      if (requestResolved.type === "request.resolved") {
+        assert.equal(requestResolved.payload.decision, "cancel");
+      }
+
+      assert.equal(turnCompleted.type, "turn.completed");
+      if (turnCompleted.type === "turn.completed") {
+        assert.equal(turnCompleted.payload.state, "cancelled");
+        assert.equal(turnCompleted.payload.stopReason, "cancelled");
+      }
+
+      const requests = yield* Effect.promise(() => readJsonLines(requestLogPath));
+      assert.isTrue(requests.some((entry) => entry.method === "session/cancel"));
+      assert.isTrue(
+        requests.some(
+          (entry) =>
+            !("method" in entry) &&
+            typeof entry.result === "object" &&
+            entry.result !== null &&
+            "outcome" in entry.result &&
+            typeof entry.result.outcome === "object" &&
+            entry.result.outcome !== null &&
+            "outcome" in entry.result.outcome &&
+            entry.result.outcome.outcome === "cancelled",
+        ),
+      );
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+  it.effect("stopping a session settles pending approval waits", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-stop-pending-approval");
+      const approvalRequested = yield* Deferred.make<void>();
+
+      const wrapperPath = yield* Effect.promise(() =>
+        makeMockAgentWrapper({ T3_ACP_EMIT_TOOL_CALLS: "1" }),
+      );
+      yield* serverSettings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      yield* Stream.runForEach(adapter.streamEvents, (event) => {
+        if (String(event.threadId) !== String(threadId) || event.type !== "request.opened") {
+          return Effect.void;
+        }
+        return Deferred.succeed(approvalRequested, undefined).pipe(Effect.ignore);
+      }).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "approval-required",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      const sendTurnFiber = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "run a tool call and then stop",
+          attachments: [],
+        })
+        .pipe(Effect.forkChild);
+
+      yield* Deferred.await(approvalRequested);
+      yield* adapter.stopSession(threadId);
+      yield* Fiber.await(sendTurnFiber);
+
+      assert.equal(yield* adapter.hasSession(threadId), false);
+    }),
+  );
+
+  it.effect("stopping a session settles pending user-input waits", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-stop-pending-user-input");
+      const userInputRequested = yield* Deferred.make<void>();
+
+      const wrapperPath = yield* Effect.promise(() =>
+        makeMockAgentWrapper({ T3_ACP_EMIT_ASK_QUESTION: "1" }),
+      );
+      yield* serverSettings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      yield* Stream.runForEach(adapter.streamEvents, (event) => {
+        if (String(event.threadId) !== String(threadId) || event.type !== "user-input.requested") {
+          return Effect.void;
+        }
+        return Deferred.succeed(userInputRequested, undefined).pipe(Effect.ignore);
+      }).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      const sendTurnFiber = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "ask me a question and then stop",
+          attachments: [],
+        })
+        .pipe(Effect.forkChild);
+
+      yield* Deferred.await(userInputRequested);
+      yield* adapter.stopSession(threadId);
+      yield* Fiber.await(sendTurnFiber);
+
+      assert.equal(yield* adapter.hasSession(threadId), false);
+    }),
+  );
+
+  it.effect("interrupting a session settles pending user-input waits", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-interrupt-pending-user-input");
+      const userInputRequested = yield* Deferred.make<void>();
+
+      const wrapperPath = yield* Effect.promise(() =>
+        makeMockAgentWrapper({ T3_ACP_EMIT_ASK_QUESTION: "1" }),
+      );
+      yield* serverSettings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      yield* Stream.runForEach(adapter.streamEvents, (event) => {
+        if (String(event.threadId) !== String(threadId) || event.type !== "user-input.requested") {
+          return Effect.void;
+        }
+        return Deferred.succeed(userInputRequested, undefined).pipe(Effect.ignore);
+      }).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      const sendTurnFiber = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "ask me a question and then interrupt",
+          attachments: [],
+        })
+        .pipe(Effect.forkChild);
+
+      yield* Deferred.await(userInputRequested);
+      yield* adapter.interruptTurn(threadId);
+      yield* Fiber.await(sendTurnFiber);
+
+      assert.equal(yield* adapter.hasSession(threadId), true);
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("broadcasts runtime events to multiple stream consumers", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const settings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-runtime-event-broadcast");
+
+      const wrapperPath = yield* Effect.promise(() => makeMockAgentWrapper());
+      yield* settings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      const firstConsumer = yield* Stream.take(adapter.streamEvents, 3).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      const secondConsumer = yield* Stream.take(adapter.streamEvents, 3).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
+      });
+
+      const firstEvents = Array.from(yield* Fiber.join(firstConsumer));
+      const secondEvents = Array.from(yield* Fiber.join(secondConsumer));
+
+      assert.deepStrictEqual(
+        firstEvents.map((event) => event.type),
+        ["session.started", "session.state.changed", "thread.started"],
+      );
+      assert.deepStrictEqual(
+        secondEvents.map((event) => event.type),
+        ["session.started", "session.state.changed", "thread.started"],
+      );
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("switches model in-session via session/set_config_option", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-model-switch");
+      const tempDir = yield* Effect.promise(() => mkdtemp(path.join(os.tmpdir(), "cursor-acp-")));
+      const requestLogPath = path.join(tempDir, "requests.ndjson");
+      const argvLogPath = path.join(tempDir, "argv.txt");
+      yield* Effect.promise(() => writeFile(requestLogPath, "", "utf8"));
+      const wrapperPath = yield* Effect.promise(() =>
+        makeProbeWrapper(requestLogPath, argvLogPath),
+      );
+      yield* serverSettings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "composer-2" },
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "first turn",
+        attachments: [],
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "second turn after switching model",
+        attachments: [],
+        modelSelection: createModelSelection(ProviderInstanceId.make("cursor"), "composer-2", [
+          { id: "fastMode", value: true },
+        ]),
+      });
+
+      const argvRuns = yield* Effect.promise(() => readArgvLog(argvLogPath));
+      assert.lengthOf(argvRuns, 1, "session should not restart — only one spawn");
+      assert.deepStrictEqual(argvRuns[0], ["acp"]);
+
+      const requests = yield* Effect.promise(() => readJsonLines(requestLogPath));
+      const setConfigRequests = requests.filter(
+        (entry) =>
+          entry.method === "session/set_config_option" &&
+          (entry.params as Record<string, unknown> | undefined)?.configId === "model",
+      );
+      assert.isAbove(setConfigRequests.length, 0, "should call session/set_config_option");
+      assert.equal((setConfigRequests[0]?.params as Record<string, unknown>)?.value, "composer-2");
+
+      const fastConfigRequests = requests.filter(
+        (entry) =>
+          entry.method === "session/set_config_option" &&
+          (entry.params as Record<string, unknown> | undefined)?.configId === "fast",
+      );
+      assert.isAbove(fastConfigRequests.length, 0, "should apply fast mode as a separate config");
+      const lastFastConfig = fastConfigRequests[fastConfigRequests.length - 1];
+      assert.equal((lastFastConfig?.params as Record<string, unknown>)?.value, "true");
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("clears prior fast mode in-session when the next turn sets fastMode: false", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CursorAdapter;
+      const serverSettings = yield* ServerSettingsService;
+      const threadId = ThreadId.make("cursor-fast-mode-reset");
+      const tempDir = yield* Effect.promise(() => mkdtemp(path.join(os.tmpdir(), "cursor-acp-")));
+      const requestLogPath = path.join(tempDir, "requests.ndjson");
+      const argvLogPath = path.join(tempDir, "argv.txt");
+      yield* Effect.promise(() => writeFile(requestLogPath, "", "utf8"));
+      const wrapperPath = yield* Effect.promise(() =>
+        makeProbeWrapper(requestLogPath, argvLogPath),
+      );
+      yield* serverSettings.updateSettings({ providers: { cursor: { binaryPath: wrapperPath } } });
+
+      yield* adapter.startSession({
+        threadId,
+        provider: ProviderDriverKind.make("cursor"),
+        cwd: process.cwd(),
+        runtimeMode: "full-access",
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "composer-2" },
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "first turn with fast mode",
+        attachments: [],
+        modelSelection: createModelSelection(ProviderInstanceId.make("cursor"), "composer-2", [
+          { id: "fastMode", value: true },
+        ]),
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "second turn without fast mode",
+        attachments: [],
+        modelSelection: createModelSelection(ProviderInstanceId.make("cursor"), "composer-2", [
+          { id: "fastMode", value: false },
+        ]),
+      });
+
+      const requests = yield* Effect.promise(() => readJsonLines(requestLogPath));
+      const fastConfigRequests = requests.filter(
+        (entry) =>
+          entry.method === "session/set_config_option" &&
+          (entry.params as Record<string, unknown> | undefined)?.configId === "fast",
+      );
+      assert.isAtLeast(fastConfigRequests.length, 2, "should set fast mode on and then off");
+
+      const lastFastConfig = fastConfigRequests[fastConfigRequests.length - 1];
+      assert.equal((lastFastConfig?.params as Record<string, unknown>)?.value, "false");
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect(
+    "applies fast mode on the first turn when modelSelection uses a non-default instance id",
+    () => {
+      const customInstanceId = ProviderInstanceId.make("cursor_secondary");
+      // Custom-instance cases can't share the suite-level `CursorAdapter`
+      // layer because that one binds `instanceId: "cursor"`. We build a
+      // fresh layer graph — including a fresh `ServerSettingsService` — so
+      // mid-test `updateSettings` calls target the same service instance the
+      // adapter's `resolveSettings` reads from, and so the outer
+      // `yield* ServerSettingsService` sees the same snapshot as well.
+      const customAdapterLayer = Layer.effect(
+        CursorAdapter,
+        Effect.gen(function* () {
+          const cursorConfig = decodeCursorSettings({});
+          const resolveSettings = yield* makeResolveCursorSettings;
+          return yield* makeCursorAdapter(cursorConfig, {
+            instanceId: customInstanceId,
+            resolveSettings,
+          });
+        }),
+      ).pipe(
+        Layer.provideMerge(ServerSettingsService.layerTest()),
+        Layer.provideMerge(
+          ServerConfig.layerTest(process.cwd(), {
+            prefix: "t3code-cursor-adapter-custom-instance-",
+          }),
+        ),
+        Layer.provideMerge(NodeServices.layer),
+      );
+
+      return Effect.gen(function* () {
+        const adapter = yield* CursorAdapter;
+        const serverSettings = yield* ServerSettingsService;
+        const threadId = ThreadId.make("cursor-fast-mode-custom-instance");
+        const tempDir = yield* Effect.promise(() => mkdtemp(path.join(os.tmpdir(), "cursor-acp-")));
+        const requestLogPath = path.join(tempDir, "requests.ndjson");
+        const argvLogPath = path.join(tempDir, "argv.txt");
+        yield* Effect.promise(() => writeFile(requestLogPath, "", "utf8"));
+        const wrapperPath = yield* Effect.promise(() =>
+          makeProbeWrapper(requestLogPath, argvLogPath),
+        );
+        yield* serverSettings.updateSettings({
+          providers: { cursor: { binaryPath: wrapperPath } },
+        });
+
+        yield* adapter.startSession({
+          threadId,
+          provider: ProviderDriverKind.make("cursor"),
+          cwd: process.cwd(),
+          runtimeMode: "full-access",
+          modelSelection: {
+            instanceId: customInstanceId,
+            model: "composer-2",
+          },
+        });
+
+        yield* adapter.sendTurn({
+          threadId,
+          input: "first turn with fast mode",
+          attachments: [],
+          modelSelection: {
+            ...createModelSelection(ProviderInstanceId.make("cursor"), "composer-2", [
+              { id: "fastMode", value: true },
+            ]),
+            instanceId: customInstanceId,
+          },
+        });
+
+        const requests = yield* Effect.promise(() => readJsonLines(requestLogPath));
+        const fastConfigRequests = requests.filter(
+          (entry) =>
+            entry.method === "session/set_config_option" &&
+            (entry.params as Record<string, unknown> | undefined)?.configId === "fast",
+        );
+        assert.isAbove(
+          fastConfigRequests.length,
+          0,
+          "fast mode should apply when instance id matches the adapter binding",
+        );
+        const lastFastConfig = fastConfigRequests[fastConfigRequests.length - 1];
+        assert.equal((lastFastConfig?.params as Record<string, unknown>)?.value, "true");
+
+        yield* adapter.stopSession(threadId);
+      }).pipe(Effect.provide(customAdapterLayer));
+    },
+  );
+});
diff --git a/apps/server/src/provider/Layers/CursorAdapter.ts b/apps/server/src/provider/Layers/CursorAdapter.ts
new file mode 100644
index 00000000000..efef5f0a83b
--- /dev/null
+++ b/apps/server/src/provider/Layers/CursorAdapter.ts
@@ -0,0 +1,1083 @@
+/**
+ * CursorAdapterLive — Cursor CLI (`agent acp`) via ACP.
+ *
+ * @module CursorAdapterLive
+ */
+
+import {
+  ApprovalRequestId,
+  type CursorSettings,
+  type ProviderOptionSelection,
+  EventId,
+  type ProviderApprovalDecision,
+  type ProviderInteractionMode,
+  type ProviderRuntimeEvent,
+  type ProviderSession,
+  type ProviderUserInputAnswers,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  RuntimeRequestId,
+  type RuntimeMode,
+  type ThreadId,
+  TurnId,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PubSub from "effect/PubSub";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import type * as EffectAcpSchema from "effect-acp/schema";
+
+import { resolveAttachmentPath } from "../../attachmentStore.ts";
+import { ServerConfig } from "../../config.ts";
+import {
+  ProviderAdapterProcessError,
+  ProviderAdapterRequestError,
+  ProviderAdapterSessionNotFoundError,
+  ProviderAdapterValidationError,
+} from "../Errors.ts";
+import { acpPermissionOutcome, mapAcpToAdapterError } from "../acp/AcpAdapterSupport.ts";
+import { type AcpSessionRuntimeShape } from "../acp/AcpSessionRuntime.ts";
+import {
+  makeAcpAssistantItemEvent,
+  makeAcpContentDeltaEvent,
+  makeAcpPlanUpdatedEvent,
+  makeAcpRequestOpenedEvent,
+  makeAcpRequestResolvedEvent,
+  makeAcpToolCallEvent,
+} from "../acp/AcpCoreRuntimeEvents.ts";
+import {
+  type AcpSessionMode,
+  type AcpSessionModeState,
+  parsePermissionRequest,
+} from "../acp/AcpRuntimeModel.ts";
+import { makeAcpNativeLoggers } from "../acp/AcpNativeLogging.ts";
+import { applyCursorAcpModelSelection, makeCursorAcpRuntime } from "../acp/CursorAcpSupport.ts";
+import {
+  CursorAskQuestionRequest,
+  CursorCreatePlanRequest,
+  CursorUpdateTodosRequest,
+  extractAskQuestions,
+  extractPlanMarkdown,
+  extractTodosAsPlan,
+} from "../acp/CursorAcpExtension.ts";
+import { type CursorAdapterShape } from "../Services/CursorAdapter.ts";
+import { resolveCursorAcpBaseModelId } from "./CursorProvider.ts";
+import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
+const encodeUnknownJsonStringExit = Schema.encodeUnknownExit(Schema.UnknownFromJsonString);
+
+const PROVIDER = ProviderDriverKind.make("cursor");
+const CURSOR_RESUME_VERSION = 1 as const;
+const ACP_PLAN_MODE_ALIASES = ["plan", "architect"];
+const ACP_IMPLEMENT_MODE_ALIASES = ["code", "agent", "default", "chat", "implement"];
+const ACP_APPROVAL_MODE_ALIASES = ["ask"];
+
+function encodeJsonStringForDiagnostics(input: unknown): string | undefined {
+  const result = encodeUnknownJsonStringExit(input);
+  return Exit.isSuccess(result) ? result.value : undefined;
+}
+
+export interface CursorAdapterLiveOptions {
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly nativeEventLogPath?: string;
+  readonly nativeEventLogger?: EventNdjsonLogger;
+  /**
+   * Selections are honored when `modelSelection.instanceId` matches this value.
+   * Defaults to the legacy built-in instance id (`cursor`).
+   */
+  readonly instanceId?: typeof ProviderInstanceId.Type;
+  /**
+   * Optional per-session settings resolver. When provided the adapter yields
+   * this effect at the start of every session and uses the result instead of
+   * the `cursorSettings` captured at construction.
+   *
+   * Production instances bind settings to the instance scope (the hydration
+   * layer rebuilds the adapter on config change) and leave this undefined.
+   * Test suites that mutate `ServerSettingsService` mid-flight — e.g. to
+   * swap `binaryPath` to a mock ACP wrapper — pass a resolver that reads
+   * the latest snapshot so the closure isn't stale.
+   */
+  readonly resolveSettings?: Effect.Effect<CursorSettings>;
+}
+
+interface PendingApproval {
+  readonly decision: Deferred.Deferred<ProviderApprovalDecision>;
+  readonly kind: string | "unknown";
+}
+
+interface PendingUserInput {
+  readonly answers: Deferred.Deferred<ProviderUserInputAnswers>;
+}
+
+interface CursorSessionContext {
+  readonly threadId: ThreadId;
+  session: ProviderSession;
+  readonly scope: Scope.Closeable;
+  readonly acp: AcpSessionRuntimeShape;
+  notificationFiber: Fiber.Fiber<void, never> | undefined;
+  readonly pendingApprovals: Map<ApprovalRequestId, PendingApproval>;
+  readonly pendingUserInputs: Map<ApprovalRequestId, PendingUserInput>;
+  readonly turns: Array<{ id: TurnId; items: Array<unknown> }>;
+  lastPlanFingerprint: string | undefined;
+  activeTurnId: TurnId | undefined;
+  stopped: boolean;
+}
+
+function settlePendingApprovalsAsCancelled(
+  pendingApprovals: ReadonlyMap<ApprovalRequestId, PendingApproval>,
+): Effect.Effect<void> {
+  const pendingEntries = Array.from(pendingApprovals.values());
+  return Effect.forEach(
+    pendingEntries,
+    (pending) => Deferred.succeed(pending.decision, "cancel").pipe(Effect.ignore),
+    {
+      discard: true,
+    },
+  );
+}
+
+function settlePendingUserInputsAsEmptyAnswers(
+  pendingUserInputs: ReadonlyMap<ApprovalRequestId, PendingUserInput>,
+): Effect.Effect<void> {
+  const pendingEntries = Array.from(pendingUserInputs.values());
+  return Effect.forEach(
+    pendingEntries,
+    (pending) => Deferred.succeed(pending.answers, {}).pipe(Effect.ignore),
+    {
+      discard: true,
+    },
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseCursorResume(raw: unknown): { sessionId: string } | undefined {
+  if (!isRecord(raw)) return undefined;
+  if (raw.schemaVersion !== CURSOR_RESUME_VERSION) return undefined;
+  if (typeof raw.sessionId !== "string" || !raw.sessionId.trim()) return undefined;
+  return { sessionId: raw.sessionId.trim() };
+}
+
+function normalizeModeSearchText(mode: AcpSessionMode): string {
+  return [mode.id, mode.name, mode.description]
+    .filter((value): value is string => typeof value === "string" && value.length > 0)
+    .join(" ")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function findModeByAliases(
+  modes: ReadonlyArray<AcpSessionMode>,
+  aliases: ReadonlyArray<string>,
+): AcpSessionMode | undefined {
+  const normalizedAliases = aliases.map((alias) => alias.toLowerCase());
+  for (const alias of normalizedAliases) {
+    const exact = modes.find((mode) => {
+      const id = mode.id.toLowerCase();
+      const name = mode.name.toLowerCase();
+      return id === alias || name === alias;
+    });
+    if (exact) {
+      return exact;
+    }
+  }
+  for (const alias of normalizedAliases) {
+    const partial = modes.find((mode) => normalizeModeSearchText(mode).includes(alias));
+    if (partial) {
+      return partial;
+    }
+  }
+  return undefined;
+}
+
+function isPlanMode(mode: AcpSessionMode): boolean {
+  return findModeByAliases([mode], ACP_PLAN_MODE_ALIASES) !== undefined;
+}
+
+function resolveRequestedModeId(input: {
+  readonly interactionMode: ProviderInteractionMode | undefined;
+  readonly runtimeMode: RuntimeMode;
+  readonly modeState: AcpSessionModeState | undefined;
+}): string | undefined {
+  const modeState = input.modeState;
+  if (!modeState) {
+    return undefined;
+  }
+
+  if (input.interactionMode === "plan") {
+    return findModeByAliases(modeState.availableModes, ACP_PLAN_MODE_ALIASES)?.id;
+  }
+
+  if (input.runtimeMode === "approval-required") {
+    return (
+      findModeByAliases(modeState.availableModes, ACP_APPROVAL_MODE_ALIASES)?.id ??
+      findModeByAliases(modeState.availableModes, ACP_IMPLEMENT_MODE_ALIASES)?.id ??
+      modeState.availableModes.find((mode) => !isPlanMode(mode))?.id ??
+      modeState.currentModeId
+    );
+  }
+
+  return (
+    findModeByAliases(modeState.availableModes, ACP_IMPLEMENT_MODE_ALIASES)?.id ??
+    findModeByAliases(modeState.availableModes, ACP_APPROVAL_MODE_ALIASES)?.id ??
+    modeState.availableModes.find((mode) => !isPlanMode(mode))?.id ??
+    modeState.currentModeId
+  );
+}
+
+function applyRequestedSessionConfiguration<E>(input: {
+  readonly runtime: AcpSessionRuntimeShape;
+  readonly runtimeMode: RuntimeMode;
+  readonly interactionMode: ProviderInteractionMode | undefined;
+  readonly modelSelection:
+    | {
+        readonly model: string;
+        readonly options?: ReadonlyArray<ProviderOptionSelection> | null | undefined;
+      }
+    | undefined;
+  readonly mapError: (context: {
+    readonly cause: import("effect-acp/errors").AcpError;
+    readonly method: "session/set_config_option" | "session/set_mode";
+  }) => E;
+}): Effect.Effect<void, E> {
+  return Effect.gen(function* () {
+    if (input.modelSelection) {
+      yield* applyCursorAcpModelSelection({
+        runtime: input.runtime,
+        model: input.modelSelection.model,
+        selections: input.modelSelection.options,
+        mapError: ({ cause }) =>
+          input.mapError({
+            cause,
+            method: "session/set_config_option",
+          }),
+      });
+    }
+
+    const requestedModeId = resolveRequestedModeId({
+      interactionMode: input.interactionMode,
+      runtimeMode: input.runtimeMode,
+      modeState: yield* input.runtime.getModeState,
+    });
+    if (!requestedModeId) {
+      return;
+    }
+
+    yield* input.runtime.setMode(requestedModeId).pipe(
+      Effect.mapError((cause) =>
+        input.mapError({
+          cause,
+          method: "session/set_mode",
+        }),
+      ),
+    );
+  });
+}
+
+function selectAutoApprovedPermissionOption(
+  request: EffectAcpSchema.RequestPermissionRequest,
+): string | undefined {
+  const allowAlwaysOption = request.options.find((option) => option.kind === "allow_always");
+  if (typeof allowAlwaysOption?.optionId === "string" && allowAlwaysOption.optionId.trim()) {
+    return allowAlwaysOption.optionId.trim();
+  }
+
+  const allowOnceOption = request.options.find((option) => option.kind === "allow_once");
+  if (typeof allowOnceOption?.optionId === "string" && allowOnceOption.optionId.trim()) {
+    return allowOnceOption.optionId.trim();
+  }
+
+  return undefined;
+}
+
+export function makeCursorAdapter(
+  cursorSettings: CursorSettings,
+  options?: CursorAdapterLiveOptions,
+) {
+  return Effect.gen(function* () {
+    const boundInstanceId = options?.instanceId ?? ProviderInstanceId.make("cursor");
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const serverConfig = yield* Effect.service(ServerConfig);
+    const nativeEventLogger =
+      options?.nativeEventLogger ??
+      (options?.nativeEventLogPath !== undefined
+        ? yield* makeEventNdjsonLogger(options.nativeEventLogPath, {
+            stream: "native",
+          })
+        : undefined);
+    const managedNativeEventLogger =
+      options?.nativeEventLogger === undefined ? nativeEventLogger : undefined;
+
+    const sessions = new Map<ThreadId, CursorSessionContext>();
+    const threadLocksRef = yield* SynchronizedRef.make(new Map<string, Semaphore.Semaphore>());
+    const runtimeEventPubSub = yield* PubSub.unbounded<ProviderRuntimeEvent>();
+
+    const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+    const nextEventId = Effect.map(Random.nextUUIDv4, (id) => EventId.make(id));
+    const makeEventStamp = () => Effect.all({ eventId: nextEventId, createdAt: nowIso });
+
+    const offerRuntimeEvent = (event: ProviderRuntimeEvent) =>
+      PubSub.publish(runtimeEventPubSub, event).pipe(Effect.asVoid);
+
+    const getThreadSemaphore = (threadId: string) =>
+      SynchronizedRef.modifyEffect(threadLocksRef, (current) => {
+        const existing: Option.Option<Semaphore.Semaphore> = Option.fromNullishOr(
+          current.get(threadId),
+        );
+        return Option.match(existing, {
+          onNone: () =>
+            Semaphore.make(1).pipe(
+              Effect.map((semaphore) => {
+                const next = new Map(current);
+                next.set(threadId, semaphore);
+                return [semaphore, next] as const;
+              }),
+            ),
+          onSome: (semaphore) => Effect.succeed([semaphore, current] as const),
+        });
+      });
+
+    const withThreadLock = <A, E, R>(threadId: string, effect: Effect.Effect<A, E, R>) =>
+      Effect.flatMap(getThreadSemaphore(threadId), (semaphore) => semaphore.withPermit(effect));
+
+    const logNative = (
+      threadId: ThreadId,
+      method: string,
+      payload: unknown,
+      _source: "acp.jsonrpc" | "acp.cursor.extension",
+    ) =>
+      Effect.gen(function* () {
+        if (!nativeEventLogger) return;
+        const observedAt = yield* nowIso;
+        yield* nativeEventLogger.write(
+          {
+            observedAt,
+            event: {
+              id: yield* Random.nextUUIDv4,
+              kind: "notification",
+              provider: PROVIDER,
+              createdAt: observedAt,
+              method,
+              threadId,
+              payload,
+            },
+          },
+          threadId,
+        );
+      });
+
+    const emitPlanUpdate = (
+      ctx: CursorSessionContext,
+      payload: {
+        readonly explanation?: string | null;
+        readonly plan: ReadonlyArray<{
+          readonly step: string;
+          readonly status: "pending" | "inProgress" | "completed";
+        }>;
+      },
+      rawPayload: unknown,
+      source: "acp.jsonrpc" | "acp.cursor.extension",
+      method: string,
+    ) =>
+      Effect.gen(function* () {
+        const fingerprint = `${ctx.activeTurnId ?? "no-turn"}:${encodeJsonStringForDiagnostics(payload) ?? "[unserializable payload]"}`;
+        if (ctx.lastPlanFingerprint === fingerprint) {
+          return;
+        }
+        ctx.lastPlanFingerprint = fingerprint;
+        yield* offerRuntimeEvent(
+          makeAcpPlanUpdatedEvent({
+            stamp: yield* makeEventStamp(),
+            provider: PROVIDER,
+            threadId: ctx.threadId,
+            turnId: ctx.activeTurnId,
+            payload,
+            source,
+            method,
+            rawPayload,
+          }),
+        );
+      });
+
+    const requireSession = (
+      threadId: ThreadId,
+    ): Effect.Effect<CursorSessionContext, ProviderAdapterSessionNotFoundError> => {
+      const ctx = sessions.get(threadId);
+      if (!ctx || ctx.stopped) {
+        return Effect.fail(
+          new ProviderAdapterSessionNotFoundError({ provider: PROVIDER, threadId }),
+        );
+      }
+      return Effect.succeed(ctx);
+    };
+
+    const stopSessionInternal = (ctx: CursorSessionContext) =>
+      Effect.gen(function* () {
+        if (ctx.stopped) return;
+        ctx.stopped = true;
+        yield* settlePendingApprovalsAsCancelled(ctx.pendingApprovals);
+        yield* settlePendingUserInputsAsEmptyAnswers(ctx.pendingUserInputs);
+        if (ctx.notificationFiber) {
+          yield* Fiber.interrupt(ctx.notificationFiber);
+        }
+        yield* Effect.ignore(Scope.close(ctx.scope, Exit.void));
+        sessions.delete(ctx.threadId);
+        yield* offerRuntimeEvent({
+          type: "session.exited",
+          ...(yield* makeEventStamp()),
+          provider: PROVIDER,
+          threadId: ctx.threadId,
+          payload: { exitKind: "graceful" },
+        });
+      });
+
+    const startSession: CursorAdapterShape["startSession"] = (input) =>
+      withThreadLock(
+        input.threadId,
+        Effect.gen(function* () {
+          if (input.provider !== undefined && input.provider !== PROVIDER) {
+            return yield* new ProviderAdapterValidationError({
+              provider: PROVIDER,
+              operation: "startSession",
+              issue: `Expected provider '${PROVIDER}' but received '${input.provider}'.`,
+            });
+          }
+          if (!input.cwd?.trim()) {
+            return yield* new ProviderAdapterValidationError({
+              provider: PROVIDER,
+              operation: "startSession",
+              issue: "cwd is required and must be non-empty.",
+            });
+          }
+
+          const cwd = path.resolve(input.cwd.trim());
+          const cursorModelSelection =
+            input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;
+          const existing = sessions.get(input.threadId);
+          if (existing && !existing.stopped) {
+            yield* stopSessionInternal(existing);
+          }
+
+          const pendingApprovals = new Map<ApprovalRequestId, PendingApproval>();
+          const pendingUserInputs = new Map<ApprovalRequestId, PendingUserInput>();
+          const sessionScope = yield* Scope.make("sequential");
+          let sessionScopeTransferred = false;
+          yield* Effect.addFinalizer(() =>
+            sessionScopeTransferred ? Effect.void : Scope.close(sessionScope, Exit.void),
+          );
+          let ctx!: CursorSessionContext;
+
+          const resumeSessionId = parseCursorResume(input.resumeCursor)?.sessionId;
+          const acpNativeLoggers = makeAcpNativeLoggers({
+            nativeEventLogger,
+            provider: PROVIDER,
+            threadId: input.threadId,
+          });
+
+          // Resolve the CursorSettings used to spawn the ACP child. Production
+          // leaves `options.resolveSettings` undefined so we use the value
+          // captured at adapter construction — per-instance isolation is
+          // enforced by the hydration layer rebuilding this adapter whenever
+          // its config changes. Tests set `resolveSettings` to pull the latest
+          // snapshot from `ServerSettingsService` so that mid-suite
+          // `updateSettings({ providers: { cursor: { binaryPath } } })` calls
+          // actually take effect when the next session spawns.
+          const effectiveCursorSettings = options?.resolveSettings
+            ? yield* options.resolveSettings
+            : cursorSettings;
+
+          const acp = yield* makeCursorAcpRuntime({
+            cursorSettings: effectiveCursorSettings,
+            ...(options?.environment ? { environment: options.environment } : {}),
+            childProcessSpawner,
+            cwd,
+            ...(resumeSessionId ? { resumeSessionId } : {}),
+            clientInfo: { name: "t3-code", version: "0.0.0" },
+            ...acpNativeLoggers,
+          }).pipe(
+            Effect.provideService(Scope.Scope, sessionScope),
+            Effect.mapError(
+              (cause) =>
+                new ProviderAdapterProcessError({
+                  provider: PROVIDER,
+                  threadId: input.threadId,
+                  detail: cause.message,
+                  cause,
+                }),
+            ),
+          );
+          const started = yield* Effect.gen(function* () {
+            yield* acp.handleExtRequest("cursor/ask_question", CursorAskQuestionRequest, (params) =>
+              Effect.gen(function* () {
+                yield* logNative(
+                  input.threadId,
+                  "cursor/ask_question",
+                  params,
+                  "acp.cursor.extension",
+                );
+                const requestId = ApprovalRequestId.make(crypto.randomUUID());
+                const runtimeRequestId = RuntimeRequestId.make(requestId);
+                const answers = yield* Deferred.make<ProviderUserInputAnswers>();
+                pendingUserInputs.set(requestId, { answers });
+                yield* offerRuntimeEvent({
+                  type: "user-input.requested",
+                  ...(yield* makeEventStamp()),
+                  provider: PROVIDER,
+                  threadId: input.threadId,
+                  turnId: ctx?.activeTurnId,
+                  requestId: runtimeRequestId,
+                  payload: { questions: extractAskQuestions(params) },
+                  raw: {
+                    source: "acp.cursor.extension",
+                    method: "cursor/ask_question",
+                    payload: params,
+                  },
+                });
+                const resolved = yield* Deferred.await(answers);
+                pendingUserInputs.delete(requestId);
+                yield* offerRuntimeEvent({
+                  type: "user-input.resolved",
+                  ...(yield* makeEventStamp()),
+                  provider: PROVIDER,
+                  threadId: input.threadId,
+                  turnId: ctx?.activeTurnId,
+                  requestId: runtimeRequestId,
+                  payload: { answers: resolved },
+                });
+                return { answers: resolved };
+              }),
+            );
+            yield* acp.handleExtRequest("cursor/create_plan", CursorCreatePlanRequest, (params) =>
+              Effect.gen(function* () {
+                yield* logNative(
+                  input.threadId,
+                  "cursor/create_plan",
+                  params,
+                  "acp.cursor.extension",
+                );
+                yield* offerRuntimeEvent({
+                  type: "turn.proposed.completed",
+                  ...(yield* makeEventStamp()),
+                  provider: PROVIDER,
+                  threadId: input.threadId,
+                  turnId: ctx?.activeTurnId,
+                  payload: { planMarkdown: extractPlanMarkdown(params) },
+                  raw: {
+                    source: "acp.cursor.extension",
+                    method: "cursor/create_plan",
+                    payload: params,
+                  },
+                });
+                return { accepted: true } as const;
+              }),
+            );
+            yield* acp.handleExtNotification(
+              "cursor/update_todos",
+              CursorUpdateTodosRequest,
+              (params) =>
+                Effect.gen(function* () {
+                  yield* logNative(
+                    input.threadId,
+                    "cursor/update_todos",
+                    params,
+                    "acp.cursor.extension",
+                  );
+                  if (ctx) {
+                    yield* emitPlanUpdate(
+                      ctx,
+                      extractTodosAsPlan(params),
+                      params,
+                      "acp.cursor.extension",
+                      "cursor/update_todos",
+                    );
+                  }
+                }),
+            );
+            yield* acp.handleRequestPermission((params) =>
+              Effect.gen(function* () {
+                yield* logNative(
+                  input.threadId,
+                  "session/request_permission",
+                  params,
+                  "acp.jsonrpc",
+                );
+                if (input.runtimeMode === "full-access") {
+                  const autoApprovedOptionId = selectAutoApprovedPermissionOption(params);
+                  if (autoApprovedOptionId !== undefined) {
+                    return {
+                      outcome: {
+                        outcome: "selected" as const,
+                        optionId: autoApprovedOptionId,
+                      },
+                    };
+                  }
+                }
+                const permissionRequest = parsePermissionRequest(params);
+                const requestId = ApprovalRequestId.make(crypto.randomUUID());
+                const runtimeRequestId = RuntimeRequestId.make(requestId);
+                const decision = yield* Deferred.make<ProviderApprovalDecision>();
+                pendingApprovals.set(requestId, {
+                  decision,
+                  kind: permissionRequest.kind,
+                });
+                yield* offerRuntimeEvent(
+                  makeAcpRequestOpenedEvent({
+                    stamp: yield* makeEventStamp(),
+                    provider: PROVIDER,
+                    threadId: input.threadId,
+                    turnId: ctx?.activeTurnId,
+                    requestId: runtimeRequestId,
+                    permissionRequest,
+                    detail:
+                      permissionRequest.detail ??
+                      encodeJsonStringForDiagnostics(params)?.slice(0, 2000) ??
+                      "[unserializable params]",
+                    args: params,
+                    source: "acp.jsonrpc",
+                    method: "session/request_permission",
+                    rawPayload: params,
+                  }),
+                );
+                const resolved = yield* Deferred.await(decision);
+                pendingApprovals.delete(requestId);
+                yield* offerRuntimeEvent(
+                  makeAcpRequestResolvedEvent({
+                    stamp: yield* makeEventStamp(),
+                    provider: PROVIDER,
+                    threadId: input.threadId,
+                    turnId: ctx?.activeTurnId,
+                    requestId: runtimeRequestId,
+                    permissionRequest,
+                    decision: resolved,
+                  }),
+                );
+                return {
+                  outcome:
+                    resolved === "cancel"
+                      ? ({ outcome: "cancelled" } as const)
+                      : {
+                          outcome: "selected" as const,
+                          optionId: acpPermissionOutcome(resolved),
+                        },
+                };
+              }),
+            );
+            return yield* acp.start();
+          }).pipe(
+            Effect.mapError((error) =>
+              mapAcpToAdapterError(PROVIDER, input.threadId, "session/start", error),
+            ),
+          );
+
+          yield* applyRequestedSessionConfiguration({
+            runtime: acp,
+            runtimeMode: input.runtimeMode,
+            interactionMode: undefined,
+            modelSelection: cursorModelSelection,
+            mapError: ({ cause, method }) =>
+              mapAcpToAdapterError(PROVIDER, input.threadId, method, cause),
+          });
+
+          const now = yield* nowIso;
+          const session: ProviderSession = {
+            provider: PROVIDER,
+            providerInstanceId: boundInstanceId,
+            status: "ready",
+            runtimeMode: input.runtimeMode,
+            cwd,
+            model: cursorModelSelection?.model,
+            threadId: input.threadId,
+            resumeCursor: {
+              schemaVersion: CURSOR_RESUME_VERSION,
+              sessionId: started.sessionId,
+            },
+            createdAt: now,
+            updatedAt: now,
+          };
+
+          ctx = {
+            threadId: input.threadId,
+            session,
+            scope: sessionScope,
+            acp,
+            notificationFiber: undefined,
+            pendingApprovals,
+            pendingUserInputs,
+            turns: [],
+            lastPlanFingerprint: undefined,
+            activeTurnId: undefined,
+            stopped: false,
+          };
+
+          const nf = yield* Stream.runDrain(
+            Stream.mapEffect(acp.getEvents(), (event) =>
+              Effect.gen(function* () {
+                switch (event._tag) {
+                  case "ModeChanged":
+                    return;
+                  case "AssistantItemStarted":
+                    yield* offerRuntimeEvent(
+                      makeAcpAssistantItemEvent({
+                        stamp: yield* makeEventStamp(),
+                        provider: PROVIDER,
+                        threadId: ctx.threadId,
+                        turnId: ctx.activeTurnId,
+                        itemId: event.itemId,
+                        lifecycle: "item.started",
+                      }),
+                    );
+                    return;
+                  case "AssistantItemCompleted":
+                    yield* offerRuntimeEvent(
+                      makeAcpAssistantItemEvent({
+                        stamp: yield* makeEventStamp(),
+                        provider: PROVIDER,
+                        threadId: ctx.threadId,
+                        turnId: ctx.activeTurnId,
+                        itemId: event.itemId,
+                        lifecycle: "item.completed",
+                      }),
+                    );
+                    return;
+                  case "PlanUpdated":
+                    yield* logNative(
+                      ctx.threadId,
+                      "session/update",
+                      event.rawPayload,
+                      "acp.jsonrpc",
+                    );
+                    yield* emitPlanUpdate(
+                      ctx,
+                      event.payload,
+                      event.rawPayload,
+                      "acp.jsonrpc",
+                      "session/update",
+                    );
+                    return;
+                  case "ToolCallUpdated":
+                    yield* logNative(
+                      ctx.threadId,
+                      "session/update",
+                      event.rawPayload,
+                      "acp.jsonrpc",
+                    );
+                    yield* offerRuntimeEvent(
+                      makeAcpToolCallEvent({
+                        stamp: yield* makeEventStamp(),
+                        provider: PROVIDER,
+                        threadId: ctx.threadId,
+                        turnId: ctx.activeTurnId,
+                        toolCall: event.toolCall,
+                        rawPayload: event.rawPayload,
+                      }),
+                    );
+                    return;
+                  case "ContentDelta":
+                    yield* logNative(
+                      ctx.threadId,
+                      "session/update",
+                      event.rawPayload,
+                      "acp.jsonrpc",
+                    );
+                    yield* offerRuntimeEvent(
+                      makeAcpContentDeltaEvent({
+                        stamp: yield* makeEventStamp(),
+                        provider: PROVIDER,
+                        threadId: ctx.threadId,
+                        turnId: ctx.activeTurnId,
+                        ...(event.itemId ? { itemId: event.itemId } : {}),
+                        text: event.text,
+                        rawPayload: event.rawPayload,
+                      }),
+                    );
+                    return;
+                }
+              }),
+            ),
+          ).pipe(Effect.forkChild);
+
+          ctx.notificationFiber = nf;
+          sessions.set(input.threadId, ctx);
+          sessionScopeTransferred = true;
+
+          yield* offerRuntimeEvent({
+            type: "session.started",
+            ...(yield* makeEventStamp()),
+            provider: PROVIDER,
+            threadId: input.threadId,
+            payload: { resume: started.initializeResult },
+          });
+          yield* offerRuntimeEvent({
+            type: "session.state.changed",
+            ...(yield* makeEventStamp()),
+            provider: PROVIDER,
+            threadId: input.threadId,
+            payload: { state: "ready", reason: "Cursor ACP session ready" },
+          });
+          yield* offerRuntimeEvent({
+            type: "thread.started",
+            ...(yield* makeEventStamp()),
+            provider: PROVIDER,
+            threadId: input.threadId,
+            payload: { providerThreadId: started.sessionId },
+          });
+
+          return session;
+        }).pipe(Effect.scoped),
+      );
+
+    const sendTurn: CursorAdapterShape["sendTurn"] = (input) =>
+      Effect.gen(function* () {
+        const ctx = yield* requireSession(input.threadId);
+        const turnId = TurnId.make(crypto.randomUUID());
+        const turnModelSelection =
+          input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;
+        const model = turnModelSelection?.model ?? ctx.session.model;
+        const resolvedModel = resolveCursorAcpBaseModelId(model);
+        yield* applyRequestedSessionConfiguration({
+          runtime: ctx.acp,
+          runtimeMode: ctx.session.runtimeMode,
+          interactionMode: input.interactionMode,
+          modelSelection:
+            model === undefined
+              ? undefined
+              : {
+                  model,
+                  options: turnModelSelection?.options,
+                },
+          mapError: ({ cause, method }) =>
+            mapAcpToAdapterError(PROVIDER, input.threadId, method, cause),
+        });
+        ctx.activeTurnId = turnId;
+        ctx.lastPlanFingerprint = undefined;
+        ctx.session = {
+          ...ctx.session,
+          activeTurnId: turnId,
+          updatedAt: yield* nowIso,
+        };
+
+        yield* offerRuntimeEvent({
+          type: "turn.started",
+          ...(yield* makeEventStamp()),
+          provider: PROVIDER,
+          threadId: input.threadId,
+          turnId,
+          payload: { model: resolvedModel },
+        });
+
+        const promptParts: Array<EffectAcpSchema.ContentBlock> = [];
+        if (input.input?.trim()) {
+          promptParts.push({ type: "text", text: input.input.trim() });
+        }
+        if (input.attachments && input.attachments.length > 0) {
+          for (const attachment of input.attachments) {
+            const attachmentPath = resolveAttachmentPath({
+              attachmentsDir: serverConfig.attachmentsDir,
+              attachment,
+            });
+            if (!attachmentPath) {
+              return yield* new ProviderAdapterRequestError({
+                provider: PROVIDER,
+                method: "session/prompt",
+                detail: `Invalid attachment id '${attachment.id}'.`,
+              });
+            }
+            const bytes = yield* fileSystem.readFile(attachmentPath).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new ProviderAdapterRequestError({
+                    provider: PROVIDER,
+                    method: "session/prompt",
+                    detail: cause.message,
+                    cause,
+                  }),
+              ),
+            );
+            promptParts.push({
+              type: "image",
+              data: Buffer.from(bytes).toString("base64"),
+              mimeType: attachment.mimeType,
+            });
+          }
+        }
+
+        if (promptParts.length === 0) {
+          return yield* new ProviderAdapterValidationError({
+            provider: PROVIDER,
+            operation: "sendTurn",
+            issue: "Turn requires non-empty text or attachments.",
+          });
+        }
+
+        const result = yield* ctx.acp
+          .prompt({
+            prompt: promptParts,
+          })
+          .pipe(
+            Effect.mapError((error) =>
+              mapAcpToAdapterError(PROVIDER, input.threadId, "session/prompt", error),
+            ),
+          );
+
+        ctx.turns.push({ id: turnId, items: [{ prompt: promptParts, result }] });
+        ctx.session = {
+          ...ctx.session,
+          activeTurnId: turnId,
+          updatedAt: yield* nowIso,
+          model: resolvedModel,
+        };
+
+        yield* offerRuntimeEvent({
+          type: "turn.completed",
+          ...(yield* makeEventStamp()),
+          provider: PROVIDER,
+          threadId: input.threadId,
+          turnId,
+          payload: {
+            state: result.stopReason === "cancelled" ? "cancelled" : "completed",
+            stopReason: result.stopReason ?? null,
+          },
+        });
+
+        return {
+          threadId: input.threadId,
+          turnId,
+          resumeCursor: ctx.session.resumeCursor,
+        };
+      });
+
+    const interruptTurn: CursorAdapterShape["interruptTurn"] = (threadId) =>
+      Effect.gen(function* () {
+        const ctx = yield* requireSession(threadId);
+        yield* settlePendingApprovalsAsCancelled(ctx.pendingApprovals);
+        yield* settlePendingUserInputsAsEmptyAnswers(ctx.pendingUserInputs);
+        yield* Effect.ignore(
+          ctx.acp.cancel.pipe(
+            Effect.mapError((error) =>
+              mapAcpToAdapterError(PROVIDER, threadId, "session/cancel", error),
+            ),
+          ),
+        );
+      });
+
+    const respondToRequest: CursorAdapterShape["respondToRequest"] = (
+      threadId,
+      requestId,
+      decision,
+    ) =>
+      Effect.gen(function* () {
+        const ctx = yield* requireSession(threadId);
+        const pending = ctx.pendingApprovals.get(requestId);
+        if (!pending) {
+          return yield* new ProviderAdapterRequestError({
+            provider: PROVIDER,
+            method: "session/request_permission",
+            detail: `Unknown pending approval request: ${requestId}`,
+          });
+        }
+        yield* Deferred.succeed(pending.decision, decision);
+      });
+
+    const respondToUserInput: CursorAdapterShape["respondToUserInput"] = (
+      threadId,
+      requestId,
+      answers,
+    ) =>
+      Effect.gen(function* () {
+        const ctx = yield* requireSession(threadId);
+        const pending = ctx.pendingUserInputs.get(requestId);
+        if (!pending) {
+          return yield* new ProviderAdapterRequestError({
+            provider: PROVIDER,
+            method: "cursor/ask_question",
+            detail: `Unknown pending user-input request: ${requestId}`,
+          });
+        }
+        yield* Deferred.succeed(pending.answers, answers);
+      });
+
+    const readThread: CursorAdapterShape["readThread"] = (threadId) =>
+      Effect.gen(function* () {
+        const ctx = yield* requireSession(threadId);
+        return { threadId, turns: ctx.turns };
+      });
+
+    const rollbackThread: CursorAdapterShape["rollbackThread"] = (threadId, numTurns) =>
+      Effect.gen(function* () {
+        const ctx = yield* requireSession(threadId);
+        if (!Number.isInteger(numTurns) || numTurns < 1) {
+          return yield* new ProviderAdapterValidationError({
+            provider: PROVIDER,
+            operation: "rollbackThread",
+            issue: "numTurns must be an integer >= 1.",
+          });
+        }
+        const nextLength = Math.max(0, ctx.turns.length - numTurns);
+        ctx.turns.splice(nextLength);
+        return { threadId, turns: ctx.turns };
+      });
+
+    const stopSession: CursorAdapterShape["stopSession"] = (threadId) =>
+      withThreadLock(
+        threadId,
+        Effect.gen(function* () {
+          const ctx = yield* requireSession(threadId);
+          yield* stopSessionInternal(ctx);
+        }),
+      );
+
+    const listSessions: CursorAdapterShape["listSessions"] = () =>
+      Effect.sync(() => Array.from(sessions.values(), (c) => ({ ...c.session })));
+
+    const hasSession: CursorAdapterShape["hasSession"] = (threadId) =>
+      Effect.sync(() => {
+        const c = sessions.get(threadId);
+        return c !== undefined && !c.stopped;
+      });
+
+    const stopAll: CursorAdapterShape["stopAll"] = () =>
+      Effect.forEach(sessions.values(), stopSessionInternal, { discard: true });
+
+    yield* Effect.addFinalizer(() =>
+      Effect.forEach(sessions.values(), stopSessionInternal, { discard: true }).pipe(
+        Effect.tap(() => PubSub.shutdown(runtimeEventPubSub)),
+        Effect.tap(() => managedNativeEventLogger?.close() ?? Effect.void),
+      ),
+    );
+
+    const streamEvents = Stream.fromPubSub(runtimeEventPubSub);
+
+    return {
+      provider: PROVIDER,
+      capabilities: { sessionModelSwitch: "in-session" },
+      startSession,
+      sendTurn,
+      interruptTurn,
+      readThread,
+      rollbackThread,
+      respondToRequest,
+      respondToUserInput,
+      stopSession,
+      listSessions,
+      hasSession,
+      stopAll,
+      streamEvents,
+    } satisfies CursorAdapterShape;
+  });
+}
diff --git a/apps/server/src/provider/Layers/CursorProvider.test.ts b/apps/server/src/provider/Layers/CursorProvider.test.ts
new file mode 100644
index 00000000000..90b36e89004
--- /dev/null
+++ b/apps/server/src/provider/Layers/CursorProvider.test.ts
@@ -0,0 +1,783 @@
+import * as NodeOS from "node:os";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { describe, expect, it } from "vitest";
+import type * as EffectAcpSchema from "effect-acp/schema";
+import type { CursorSettings, ServerProviderModel } from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import {
+  buildCursorProviderSnapshot,
+  buildCursorCapabilitiesFromConfigOptions,
+  buildCursorDiscoveredModelsFromConfigOptions,
+  checkCursorProviderStatus,
+  discoverCursorModelCapabilitiesViaAcp,
+  discoverCursorModelsViaAcp,
+  getCursorFallbackModels,
+  getCursorParameterizedModelPickerUnsupportedMessage,
+  parseCursorAboutOutput,
+  parseCursorCliConfigChannel,
+  parseCursorVersionDate,
+  resolveCursorAcpBaseModelId,
+  resolveCursorAcpConfigUpdates,
+} from "./CursorProvider.ts";
+
+const runNode = <A, E>(
+  effect: Effect.Effect<A, E, FileSystem.FileSystem | Path.Path>,
+): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(NodeServices.layer)));
+
+const resolveMockAgentPath = Effect.fn("resolveMockAgentPath")(function* () {
+  const path = yield* Path.Path;
+  return yield* path.fromFileUrl(new URL("../../../scripts/acp-mock-agent.ts", import.meta.url));
+});
+
+function selectDescriptor(
+  id: string,
+  label: string,
+  options: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>,
+) {
+  return {
+    id,
+    label,
+    type: "select" as const,
+    options: [...options],
+    ...(options.find((option) => option.isDefault)?.id
+      ? { currentValue: options.find((option) => option.isDefault)?.id }
+      : {}),
+  };
+}
+
+function booleanDescriptor(id: string, label: string, currentValue?: boolean) {
+  return {
+    id,
+    label,
+    type: "boolean" as const,
+    ...(typeof currentValue === "boolean" ? { currentValue } : {}),
+  };
+}
+
+const makeMockAgentWrapper = Effect.fn("makeMockAgentWrapper")(function* (
+  extraEnv?: Record<string, string>,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const mockAgentPath = yield* resolveMockAgentPath();
+  const dir = yield* fileSystem.makeTempDirectory({
+    directory: NodeOS.tmpdir(),
+    prefix: "cursor-provider-mock-",
+  });
+  const wrapperPath = path.join(dir, "fake-agent.sh");
+  // @effect-diagnostics-next-line preferSchemaOverJson:off
+  const bunCommand = JSON.stringify("bun");
+  // @effect-diagnostics-next-line preferSchemaOverJson:off
+  const mockAgentPathJson = JSON.stringify(mockAgentPath);
+  const envExports = Object.entries(extraEnv ?? {})
+    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
+    .join("\n");
+  const script = `#!/bin/sh
+${envExports}
+exec ${bunCommand} ${mockAgentPathJson} "$@"
+`;
+  yield* fileSystem.writeFileString(wrapperPath, script);
+  yield* fileSystem.chmod(wrapperPath, 0o755);
+  return wrapperPath;
+});
+
+const makeMockAgentWithAboutWrapper = Effect.fn("makeMockAgentWithAboutWrapper")(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const mockAgentPath = yield* resolveMockAgentPath();
+  const dir = yield* fileSystem.makeTempDirectory({
+    directory: NodeOS.tmpdir(),
+    prefix: "cursor-provider-about-mock-",
+  });
+  const wrapperPath = path.join(dir, "fake-agent.sh");
+  // @effect-diagnostics-next-line preferSchemaOverJson:off
+  const bunCommand = JSON.stringify("bun");
+  // @effect-diagnostics-next-line preferSchemaOverJson:off
+  const mockAgentPathJson = JSON.stringify(mockAgentPath);
+  const script = `#!/bin/sh
+if [ "$1" = "about" ]; then
+  printf 'CLI Version         2026.04.09-f2b0fcd\\n'
+  printf 'User Email          cursor@example.com\\n'
+  exit 0
+fi
+exec ${bunCommand} ${mockAgentPathJson} "$@"
+`;
+  yield* fileSystem.writeFileString(wrapperPath, script);
+  yield* fileSystem.chmod(wrapperPath, 0o755);
+  return wrapperPath;
+});
+
+const waitForFileContent = Effect.fn("waitForFileContent")(function* (
+  filePath: string,
+  attempts = 40,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const content = yield* fileSystem
+      .readFileString(filePath)
+      .pipe(Effect.catch(() => Effect.void));
+    if (content !== undefined) {
+      if (content.trim().length > 0) {
+        return content;
+      }
+    }
+    yield* Effect.sleep("50 millis");
+  }
+  return yield* Effect.die(`Timed out waiting for file content at ${filePath}`);
+});
+
+const makeProviderStatusEnvFixture = Effect.fn("makeProviderStatusEnvFixture")(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const tempDir = yield* fileSystem.makeTempDirectory({
+    directory: NodeOS.tmpdir(),
+    prefix: "cursor-provider-status-env-",
+  });
+  return {
+    requestLogPath: path.join(tempDir, "requests.ndjson"),
+    wrapperPath: yield* makeMockAgentWithAboutWrapper(),
+  };
+});
+
+const makeExitLogFixture = Effect.fn("makeExitLogFixture")(function* (prefix: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const tempDir = yield* fileSystem.makeTempDirectory({
+    directory: NodeOS.tmpdir(),
+    prefix,
+  });
+  const exitLogPath = path.join(tempDir, "exit.log");
+  return {
+    exitLogPath,
+    wrapperPath: yield* makeMockAgentWrapper({
+      T3_ACP_EXIT_LOG_PATH: exitLogPath,
+    }),
+  };
+});
+
+const parameterizedGpt54ConfigOptions = [
+  {
+    type: "select",
+    currentValue: "gpt-5.4-medium-fast",
+    options: [{ name: "GPT-5.4", value: "gpt-5.4-medium-fast" }],
+    category: "model",
+    id: "model",
+    name: "Model",
+  },
+  {
+    type: "select",
+    currentValue: "medium",
+    options: [
+      { name: "None", value: "none" },
+      { name: "Low", value: "low" },
+      { name: "Medium", value: "medium" },
+      { name: "High", value: "high" },
+      { name: "Extra High", value: "extra-high" },
+    ],
+    category: "thought_level",
+    id: "reasoning",
+    name: "Reasoning",
+  },
+  {
+    type: "select",
+    currentValue: "272k",
+    options: [
+      { name: "272K", value: "272k" },
+      { name: "1M", value: "1m" },
+    ],
+    category: "model_config",
+    id: "context",
+    name: "Context",
+  },
+  {
+    type: "select",
+    currentValue: "false",
+    options: [
+      { name: "Off", value: "false" },
+      { name: "Fast", value: "true" },
+    ],
+    category: "model_config",
+    id: "fast",
+    name: "Fast",
+  },
+] satisfies ReadonlyArray<EffectAcpSchema.SessionConfigOption>;
+
+const parameterizedClaudeConfigOptions = [
+  {
+    type: "select",
+    currentValue: "claude-4.6-opus-high-thinking",
+    options: [{ name: "Opus 4.6", value: "claude-4.6-opus-high-thinking" }],
+    category: "model",
+    id: "model",
+    name: "Model",
+  },
+  {
+    type: "select",
+    currentValue: "high",
+    options: [
+      { name: "Low", value: "low" },
+      { name: "Medium", value: "medium" },
+      { name: "High", value: "high" },
+    ],
+    category: "thought_level",
+    id: "reasoning",
+    name: "Reasoning",
+  },
+  {
+    type: "boolean",
+    currentValue: true,
+    category: "model_config",
+    id: "thinking",
+    name: "Thinking",
+  },
+] satisfies ReadonlyArray<EffectAcpSchema.SessionConfigOption>;
+
+const parameterizedClaudeModelOptionConfigOptions = [
+  {
+    type: "select",
+    currentValue: "claude-opus-4-6",
+    options: [{ name: "Opus 4.6", value: "claude-opus-4-6" }],
+    category: "model",
+    id: "model",
+    name: "Model",
+  },
+  {
+    type: "select",
+    currentValue: "high",
+    options: [
+      { name: "Low", value: "low" },
+      { name: "Medium", value: "medium" },
+      { name: "High", value: "high" },
+    ],
+    category: "thought_level",
+    id: "reasoning",
+    name: "Reasoning",
+  },
+  {
+    type: "select",
+    currentValue: "max",
+    options: [
+      { name: "Low", value: "low" },
+      { name: "Medium", value: "medium" },
+      { name: "High", value: "high" },
+      { name: "Max", value: "max" },
+    ],
+    category: "model_option",
+    id: "effort",
+    name: "Effort",
+  },
+  {
+    type: "select",
+    currentValue: "true",
+    options: [
+      { name: "Off", value: "false" },
+      { name: "Fast", value: "true" },
+    ],
+    category: "model_config",
+    id: "fast",
+    name: "Fast",
+  },
+  {
+    type: "select",
+    currentValue: "true",
+    options: [
+      { name: "Off", value: "false" },
+      { name: ":icon-brain:", value: "true" },
+    ],
+    category: "model_config",
+    id: "thinking",
+    name: "Thinking",
+  },
+] satisfies ReadonlyArray<EffectAcpSchema.SessionConfigOption>;
+
+const sessionNewCursorConfigOptions = [
+  {
+    type: "select",
+    currentValue: "agent",
+    options: [
+      { name: "Agent", value: "agent", description: "Full agent capabilities with tool access" },
+    ],
+    category: "mode",
+    id: "mode",
+    name: "Mode",
+    description: "Controls how the agent executes tasks",
+  },
+  {
+    type: "select",
+    currentValue: "composer-2",
+    options: [
+      { name: "Auto", value: "default" },
+      { name: "Composer 2", value: "composer-2" },
+      { name: "GPT-5.4", value: "gpt-5.4" },
+      { name: "Sonnet 4.6", value: "claude-sonnet-4-6" },
+      { name: "Opus 4.6", value: "claude-opus-4-6" },
+      { name: "Codex 5.3 Spark", value: "gpt-5.3-codex-spark" },
+    ],
+    category: "model",
+    id: "model",
+    name: "Model",
+    description: "Controls which model is used for responses",
+  },
+  {
+    type: "select",
+    currentValue: "true",
+    options: [
+      { name: "Off", value: "false" },
+      { name: "Fast", value: "true" },
+    ],
+    category: "model_config",
+    id: "fast",
+    name: "Fast",
+    description: "Faster speeds.",
+  },
+] satisfies ReadonlyArray<EffectAcpSchema.SessionConfigOption>;
+
+const baseCursorSettings: CursorSettings = {
+  enabled: true,
+  binaryPath: "agent",
+  apiEndpoint: "",
+  customModels: [],
+};
+
+const emptyCapabilities = createModelCapabilities({ optionDescriptors: [] });
+
+describe("getCursorFallbackModels", () => {
+  it("does not publish any built-in cursor models before ACP discovery", () => {
+    expect(
+      getCursorFallbackModels({
+        customModels: ["internal/cursor-model"],
+      }).map((model) => model.slug),
+    ).toEqual(["internal/cursor-model"]);
+  });
+});
+
+describe("buildCursorProviderSnapshot", () => {
+  it("downgrades ready status to warning when ACP model discovery times out", () => {
+    expect(
+      buildCursorProviderSnapshot({
+        checkedAt: "2026-01-01T00:00:00.000Z",
+        cursorSettings: baseCursorSettings,
+        parsed: {
+          version: "2026.04.09-f2b0fcd",
+          status: "ready",
+          auth: { status: "authenticated", type: "Team", label: "Cursor Team Subscription" },
+        },
+        discoveryWarning: "Cursor ACP model discovery timed out after 15000ms.",
+      }),
+    ).toMatchObject({
+      status: "warning",
+      message: "Cursor ACP model discovery timed out after 15000ms.",
+      models: [],
+    });
+  });
+
+  it("preserves provider error state while appending discovery warnings", () => {
+    expect(
+      buildCursorProviderSnapshot({
+        checkedAt: "2026-01-01T00:00:00.000Z",
+        cursorSettings: {
+          ...baseCursorSettings,
+          customModels: ["claude-sonnet-4-6"],
+        },
+        parsed: {
+          version: "2026.04.09-f2b0fcd",
+          status: "error",
+          auth: { status: "unauthenticated" },
+          message: "Cursor Agent is not authenticated. Run `agent login` and try again.",
+        },
+        discoveryWarning: "Cursor ACP model discovery failed. Check server logs for details.",
+      }),
+    ).toMatchObject({
+      status: "error",
+      message:
+        "Cursor Agent is not authenticated. Run `agent login` and try again. Cursor ACP model discovery failed. Check server logs for details.",
+      models: [
+        {
+          slug: "claude-sonnet-4-6",
+          isCustom: true,
+        },
+      ],
+    });
+  });
+});
+
+describe("buildCursorCapabilitiesFromConfigOptions", () => {
+  it("derives model capabilities from parameterized Cursor ACP config options", () => {
+    expect(buildCursorCapabilitiesFromConfigOptions(parameterizedGpt54ConfigOptions)).toEqual(
+      createModelCapabilities({
+        optionDescriptors: [
+          selectDescriptor("reasoning", "Reasoning", [
+            { id: "low", label: "Low" },
+            { id: "medium", label: "Medium", isDefault: true },
+            { id: "high", label: "High" },
+            { id: "xhigh", label: "Extra High" },
+          ]),
+          selectDescriptor("contextWindow", "Context", [
+            { id: "272k", label: "272K", isDefault: true },
+            { id: "1m", label: "1M" },
+          ]),
+          booleanDescriptor("fastMode", "Fast", false),
+        ],
+      }),
+    );
+  });
+
+  it("detects boolean thinking toggles from model_config options", () => {
+    expect(buildCursorCapabilitiesFromConfigOptions(parameterizedClaudeConfigOptions)).toEqual(
+      createModelCapabilities({
+        optionDescriptors: [
+          selectDescriptor("reasoning", "Reasoning", [
+            { id: "low", label: "Low" },
+            { id: "medium", label: "Medium" },
+            { id: "high", label: "High", isDefault: true },
+          ]),
+          booleanDescriptor("thinking", "Thinking", true),
+        ],
+      }),
+    );
+  });
+
+  it("prefers the newer model_option effort control over legacy thought_level", () => {
+    expect(
+      buildCursorCapabilitiesFromConfigOptions(parameterizedClaudeModelOptionConfigOptions),
+    ).toEqual(
+      createModelCapabilities({
+        optionDescriptors: [
+          selectDescriptor("reasoning", "Effort", [
+            { id: "low", label: "Low" },
+            { id: "medium", label: "Medium" },
+            { id: "high", label: "High" },
+            { id: "max", label: "Max", isDefault: true },
+          ]),
+          booleanDescriptor("fastMode", "Fast", true),
+          booleanDescriptor("thinking", "Thinking", true),
+        ],
+      }),
+    );
+  });
+});
+
+describe("buildCursorDiscoveredModelsFromConfigOptions", () => {
+  it("publishes ACP model choices immediately from session/new config options", () => {
+    expect(buildCursorDiscoveredModelsFromConfigOptions(sessionNewCursorConfigOptions)).toEqual([
+      {
+        slug: "default",
+        name: "Auto",
+        isCustom: false,
+        capabilities: emptyCapabilities,
+      },
+      {
+        slug: "composer-2",
+        name: "Composer 2",
+        isCustom: false,
+        capabilities: createModelCapabilities({
+          optionDescriptors: [booleanDescriptor("fastMode", "Fast", true)],
+        }),
+      },
+      {
+        slug: "gpt-5.4",
+        name: "GPT-5.4",
+        isCustom: false,
+        capabilities: emptyCapabilities,
+      },
+      {
+        slug: "claude-sonnet-4-6",
+        name: "Sonnet 4.6",
+        isCustom: false,
+        capabilities: emptyCapabilities,
+      },
+      {
+        slug: "claude-opus-4-6",
+        name: "Opus 4.6",
+        isCustom: false,
+        capabilities: emptyCapabilities,
+      },
+      {
+        slug: "gpt-5.3-codex-spark",
+        name: "Codex 5.3 Spark",
+        isCustom: false,
+        capabilities: emptyCapabilities,
+      },
+    ]);
+  });
+});
+
+describe("checkCursorProviderStatus", () => {
+  it("passes the injected environment to ACP model discovery", async () => {
+    const { requestLogPath, wrapperPath } = await runNode(makeProviderStatusEnvFixture());
+
+    const provider = await Effect.runPromise(
+      checkCursorProviderStatus(
+        {
+          enabled: true,
+          binaryPath: wrapperPath,
+          apiEndpoint: "",
+          customModels: [],
+        },
+        {
+          ...process.env,
+          T3_ACP_REQUEST_LOG_PATH: requestLogPath,
+        },
+      ).pipe(Effect.provide(NodeServices.layer)),
+    );
+
+    expect(provider.models.map((model) => model.slug)).toEqual([
+      "default",
+      "composer-2",
+      "gpt-5.4",
+      "claude-opus-4-6",
+    ]);
+    await expect(runNode(waitForFileContent(requestLogPath))).resolves.toContain("initialize");
+  });
+});
+
+describe("discoverCursorModelsViaAcp", () => {
+  it("keeps the ACP probe runtime alive long enough to discover models", async () => {
+    const wrapperPath = await runNode(makeMockAgentWrapper());
+
+    const models = await Effect.runPromise(
+      discoverCursorModelsViaAcp({
+        enabled: true,
+        binaryPath: wrapperPath,
+        apiEndpoint: "",
+        customModels: [],
+      }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+    );
+
+    expect(models.map((model) => model.slug)).toEqual([
+      "default",
+      "composer-2",
+      "gpt-5.4",
+      "claude-opus-4-6",
+    ]);
+  });
+
+  it("closes the ACP probe runtime after discovery completes", async () => {
+    const { exitLogPath, wrapperPath } = await runNode(
+      makeExitLogFixture("cursor-provider-exit-log-"),
+    );
+
+    await Effect.runPromise(
+      discoverCursorModelsViaAcp({
+        enabled: true,
+        binaryPath: wrapperPath,
+        apiEndpoint: "",
+        customModels: [],
+      }).pipe(Effect.provide(NodeServices.layer)),
+    );
+
+    const exitLog = await runNode(waitForFileContent(exitLogPath));
+    expect(exitLog).toContain("SIGTERM");
+  });
+});
+
+describe("discoverCursorModelCapabilitiesViaAcp", () => {
+  it("closes all ACP probe runtimes after capability enrichment completes", async () => {
+    const { exitLogPath, wrapperPath } = await runNode(
+      makeExitLogFixture("cursor-capabilities-exit-log-"),
+    );
+    const existingModels: ReadonlyArray<ServerProviderModel> = [
+      { slug: "default", name: "Auto", isCustom: false, capabilities: emptyCapabilities },
+      { slug: "composer-2", name: "Composer 2", isCustom: false, capabilities: emptyCapabilities },
+      { slug: "gpt-5.4", name: "GPT-5.4", isCustom: false, capabilities: emptyCapabilities },
+      {
+        slug: "claude-opus-4-6",
+        name: "Opus 4.6",
+        isCustom: false,
+        capabilities: emptyCapabilities,
+      },
+    ];
+
+    const models = await Effect.runPromise(
+      discoverCursorModelCapabilitiesViaAcp(
+        {
+          enabled: true,
+          binaryPath: wrapperPath,
+          apiEndpoint: "",
+          customModels: [],
+        },
+        existingModels,
+      ).pipe(Effect.provide(NodeServices.layer)),
+    );
+
+    expect(models.map((model) => model.slug)).toEqual([
+      "default",
+      "composer-2",
+      "gpt-5.4",
+      "claude-opus-4-6",
+    ]);
+
+    const exitLog = await runNode(waitForFileContent(exitLogPath));
+    expect(exitLog.match(/SIGTERM/g)?.length ?? 0).toBe(4);
+  });
+});
+
+describe("parseCursorAboutOutput", () => {
+  it("parses json about output and forwards subscription metadata", () => {
+    expect(
+      parseCursorAboutOutput({
+        code: 0,
+        stdout: JSON.stringify({
+          cliVersion: "2026.04.09-f2b0fcd",
+          subscriptionTier: "Team",
+          userEmail: "jmarminge@gmail.com",
+        }),
+        stderr: "",
+      }),
+    ).toEqual({
+      version: "2026.04.09-f2b0fcd",
+      status: "ready",
+      auth: {
+        status: "authenticated",
+        email: "jmarminge@gmail.com",
+        type: "Team",
+        label: "Cursor Team Subscription",
+      },
+    });
+  });
+
+  it("treats json about output with a logged-out email as unauthenticated", () => {
+    expect(
+      parseCursorAboutOutput({
+        code: 0,
+        stdout: JSON.stringify({
+          cliVersion: "2026.04.09-f2b0fcd",
+          subscriptionTier: "Team",
+          userEmail: "Not logged in",
+        }),
+        stderr: "",
+      }),
+    ).toEqual({
+      version: "2026.04.09-f2b0fcd",
+      status: "error",
+      auth: {
+        status: "unauthenticated",
+      },
+      message: "Cursor Agent is not authenticated. Run `agent login` and try again.",
+    });
+  });
+
+  it("treats json about output with a null email as unauthenticated", () => {
+    expect(
+      parseCursorAboutOutput({
+        code: 0,
+        stdout: JSON.stringify({
+          cliVersion: "2026.04.09-f2b0fcd",
+          subscriptionTier: null,
+          userEmail: null,
+        }),
+        stderr: "",
+      }),
+    ).toEqual({
+      version: "2026.04.09-f2b0fcd",
+      status: "error",
+      auth: {
+        status: "unauthenticated",
+      },
+      message: "Cursor Agent is not authenticated. Run `agent login` and try again.",
+    });
+  });
+});
+
+describe("Cursor parameterized model picker preview gating", () => {
+  it("parses Cursor CLI version dates from build versions", () => {
+    expect(parseCursorVersionDate("2026.04.08-c4e73a3")).toBe(20260408);
+    expect(parseCursorVersionDate("2026.04.09")).toBe(20260409);
+    expect(parseCursorVersionDate("not-a-version")).toBeUndefined();
+  });
+
+  it("parses the Cursor CLI channel from cli-config.json", () => {
+    expect(parseCursorCliConfigChannel('{ "channel": "lab" }')).toBe("lab");
+    expect(parseCursorCliConfigChannel('{ "channel": "stable" }')).toBe("stable");
+    expect(parseCursorCliConfigChannel('{ "version": 1 }')).toBeUndefined();
+    expect(parseCursorCliConfigChannel("not-json")).toBeUndefined();
+  });
+
+  it("returns no warning when the preview requirements are met", () => {
+    expect(
+      getCursorParameterizedModelPickerUnsupportedMessage({
+        version: "2026.04.08-c4e73a3",
+        channel: "lab",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("explains when the Cursor Agent version is too old", () => {
+    expect(
+      getCursorParameterizedModelPickerUnsupportedMessage({
+        version: "2026.04.07-c4e73a3",
+        channel: "lab",
+      }),
+    ).toContain("too old");
+  });
+
+  it("explains when the Cursor Agent channel is not lab", () => {
+    expect(
+      getCursorParameterizedModelPickerUnsupportedMessage({
+        version: "2026.04.08-c4e73a3",
+        channel: "stable",
+      }),
+    ).toContain("lab channel");
+  });
+});
+
+describe("resolveCursorAcpBaseModelId", () => {
+  it("drops bracket traits without rewriting raw ACP model ids", () => {
+    expect(resolveCursorAcpBaseModelId("gpt-5.4[reasoning=medium,context=272k]")).toBe("gpt-5.4");
+    expect(resolveCursorAcpBaseModelId("gpt-5.4-medium-fast")).toBe("gpt-5.4-medium-fast");
+    expect(resolveCursorAcpBaseModelId("claude-4.6-opus-high-thinking")).toBe(
+      "claude-4.6-opus-high-thinking",
+    );
+    expect(resolveCursorAcpBaseModelId("composer-2")).toBe("composer-2");
+    expect(resolveCursorAcpBaseModelId("auto")).toBe("auto");
+  });
+});
+
+describe("resolveCursorAcpConfigUpdates", () => {
+  it("maps Cursor model options onto separate ACP config option updates", () => {
+    expect(
+      resolveCursorAcpConfigUpdates(parameterizedGpt54ConfigOptions, [
+        { id: "reasoning", value: "xhigh" },
+        { id: "fastMode", value: true },
+        { id: "contextWindow", value: "1m" },
+      ]),
+    ).toEqual([
+      { configId: "reasoning", value: "extra-high" },
+      { configId: "context", value: "1m" },
+      { configId: "fast", value: "true" },
+    ]);
+  });
+
+  it("maps boolean thinking toggles when the model exposes them separately", () => {
+    expect(
+      resolveCursorAcpConfigUpdates(parameterizedClaudeConfigOptions, [
+        { id: "thinking", value: false },
+      ]),
+    ).toEqual([{ configId: "thinking", value: false }]);
+  });
+
+  it("maps explicit fastMode: false so the adapter can clear a prior fast selection", () => {
+    expect(
+      resolveCursorAcpConfigUpdates(parameterizedGpt54ConfigOptions, [
+        { id: "fastMode", value: false },
+      ]),
+    ).toEqual([{ configId: "fast", value: "false" }]);
+  });
+
+  it("writes Cursor effort changes through the newer model_option config when available", () => {
+    expect(
+      resolveCursorAcpConfigUpdates(parameterizedClaudeModelOptionConfigOptions, [
+        { id: "reasoning", value: "max" },
+        { id: "thinking", value: false },
+      ]),
+    ).toEqual([
+      { configId: "effort", value: "max" },
+      { configId: "thinking", value: "false" },
+    ]);
+  });
+});
diff --git a/apps/server/src/provider/Layers/CursorProvider.ts b/apps/server/src/provider/Layers/CursorProvider.ts
new file mode 100644
index 00000000000..035c08437a9
--- /dev/null
+++ b/apps/server/src/provider/Layers/CursorProvider.ts
@@ -0,0 +1,1296 @@
+import * as NodeOs from "node:os";
+import type {
+  CursorSettings,
+  ModelCapabilities,
+  ProviderOptionSelection,
+  ServerProvider,
+  ServerProviderAuth,
+  ServerProviderModel,
+  ServerProviderState,
+} from "@t3tools/contracts";
+import { ProviderDriverKind } from "@t3tools/contracts";
+import type * as EffectAcpSchema from "effect-acp/schema";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import {
+  createModelCapabilities,
+  getProviderOptionBooleanSelectionValue,
+  getProviderOptionStringSelectionValue,
+} from "@t3tools/shared/model";
+
+import {
+  buildBooleanOptionDescriptor,
+  buildSelectOptionDescriptor,
+  buildServerProvider,
+  collectStreamAsString,
+  isCommandMissingCause,
+  providerModelsFromSettings,
+  type CommandResult,
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+import {
+  enrichProviderSnapshotWithVersionAdvisory,
+  type ProviderMaintenanceCapabilities,
+} from "../providerMaintenance.ts";
+import { AcpSessionRuntime } from "../acp/AcpSessionRuntime.ts";
+
+const PROVIDER = ProviderDriverKind.make("cursor");
+const CURSOR_PRESENTATION = {
+  displayName: "Cursor",
+  badgeLabel: "Early Access",
+  showInteractionModeToggle: true,
+} as const;
+const EMPTY_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+
+const CURSOR_ACP_MODEL_DISCOVERY_TIMEOUT_MS = 15_000;
+const CURSOR_ACP_MODEL_CAPABILITY_TIMEOUT = "4 seconds";
+const CURSOR_ACP_MODEL_DISCOVERY_CONCURRENCY = 4;
+const CURSOR_PARAMETERIZED_MODEL_PICKER_MIN_VERSION_DATE = 2026_04_08;
+export const CURSOR_PARAMETERIZED_MODEL_PICKER_CAPABILITIES = {
+  _meta: {
+    parameterizedModelPicker: true,
+  },
+} satisfies NonNullable<EffectAcpSchema.InitializeRequest["clientCapabilities"]>;
+
+export function buildInitialCursorProviderSnapshot(
+  cursorSettings: CursorSettings,
+): Effect.Effect<ServerProviderDraft> {
+  return Effect.gen(function* () {
+    const checkedAt = yield* Effect.map(DateTime.now, DateTime.formatIso);
+    const models = getCursorFallbackModels(cursorSettings);
+
+    if (!cursorSettings.enabled) {
+      return buildServerProvider({
+        presentation: CURSOR_PRESENTATION,
+        enabled: false,
+        checkedAt,
+        models,
+        probe: {
+          installed: false,
+          version: null,
+          status: "warning",
+          auth: { status: "unknown" },
+          message: "Cursor is disabled in T3 Code settings.",
+        },
+      });
+    }
+
+    return buildServerProvider({
+      presentation: CURSOR_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      probe: {
+        installed: true,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Checking Cursor Agent availability...",
+      },
+    });
+  });
+}
+
+interface CursorSessionSelectOption {
+  readonly value: string;
+  readonly name: string;
+}
+
+interface CursorAcpDiscoveredModel {
+  readonly slug: string;
+  readonly name: string;
+  readonly capabilities: ModelCapabilities;
+}
+
+function flattenSessionConfigSelectOptions(
+  configOption: EffectAcpSchema.SessionConfigOption | undefined,
+): ReadonlyArray<CursorSessionSelectOption> {
+  if (!configOption || configOption.type !== "select") {
+    return [];
+  }
+  return configOption.options.flatMap((entry) =>
+    "value" in entry
+      ? [
+          {
+            value: entry.value.trim(),
+            name: entry.name.trim(),
+          } satisfies CursorSessionSelectOption,
+        ]
+      : entry.options.map(
+          (option) =>
+            ({
+              value: option.value.trim(),
+              name: option.name.trim(),
+            }) satisfies CursorSessionSelectOption,
+        ),
+  );
+}
+
+function normalizeCursorReasoningValue(value: string | null | undefined): string | undefined {
+  const normalized = value?.trim().toLowerCase();
+  switch (normalized) {
+    case "low":
+    case "medium":
+    case "high":
+    case "max":
+      return normalized;
+    case "xhigh":
+    case "extra-high":
+    case "extra high":
+      return "xhigh";
+    default:
+      return undefined;
+  }
+}
+
+function findCursorModelConfigOption(
+  configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption>,
+): EffectAcpSchema.SessionConfigOption | undefined {
+  return configOptions.find((option) => option.category === "model");
+}
+
+function getCursorConfigOptionCategory(option: EffectAcpSchema.SessionConfigOption): string {
+  return option.category?.trim().toLowerCase() ?? "";
+}
+
+function isCursorEffortConfigOption(option: EffectAcpSchema.SessionConfigOption): boolean {
+  const id = option.id.trim().toLowerCase();
+  const name = option.name.trim().toLowerCase();
+  return (
+    id === "effort" ||
+    id === "reasoning" ||
+    name === "effort" ||
+    name === "reasoning" ||
+    name.includes("effort") ||
+    name.includes("reasoning")
+  );
+}
+
+function findCursorEffortConfigOption(
+  configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption>,
+): EffectAcpSchema.SessionConfigOption | undefined {
+  const candidates = configOptions.filter(
+    (option) => option.type === "select" && isCursorEffortConfigOption(option),
+  );
+  return (
+    candidates.find((option) => getCursorConfigOptionCategory(option) === "model_option") ??
+    candidates.find((option) => option.id.trim().toLowerCase() === "effort") ??
+    candidates.find((option) => getCursorConfigOptionCategory(option) === "thought_level") ??
+    candidates[0]
+  );
+}
+
+function isCursorContextConfigOption(option: EffectAcpSchema.SessionConfigOption): boolean {
+  const id = option.id.trim().toLowerCase();
+  const name = option.name.trim().toLowerCase();
+  return id === "context" || id === "context_size" || name.includes("context");
+}
+
+function isCursorFastConfigOption(option: EffectAcpSchema.SessionConfigOption): boolean {
+  const id = option.id.trim().toLowerCase();
+  const name = option.name.trim().toLowerCase();
+  return id === "fast" || name === "fast" || name.includes("fast mode");
+}
+
+function isCursorThinkingConfigOption(option: EffectAcpSchema.SessionConfigOption): boolean {
+  const id = option.id.trim().toLowerCase();
+  const name = option.name.trim().toLowerCase();
+  return id === "thinking" || name.includes("thinking");
+}
+
+function isBooleanLikeConfigOption(option: EffectAcpSchema.SessionConfigOption): boolean {
+  if (option.type === "boolean") {
+    return true;
+  }
+  if (option.type !== "select") {
+    return false;
+  }
+  const values = new Set(
+    flattenSessionConfigSelectOptions(option).map((entry) => entry.value.trim().toLowerCase()),
+  );
+  return values.has("true") && values.has("false");
+}
+
+function getBooleanCurrentValue(
+  option: EffectAcpSchema.SessionConfigOption | undefined,
+): boolean | undefined {
+  if (!option) {
+    return undefined;
+  }
+  if (option.type === "boolean") {
+    return option.currentValue;
+  }
+  if (option.type !== "select") {
+    return undefined;
+  }
+  const normalized = option.currentValue?.trim().toLowerCase();
+  if (normalized === "true") {
+    return true;
+  }
+  if (normalized === "false") {
+    return false;
+  }
+  return undefined;
+}
+
+export function buildCursorCapabilitiesFromConfigOptions(
+  configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption> | null | undefined,
+): ModelCapabilities {
+  if (!configOptions || configOptions.length === 0) {
+    return EMPTY_CAPABILITIES;
+  }
+
+  const reasoningConfig = findCursorEffortConfigOption(configOptions);
+  const reasoningEffortLevels =
+    reasoningConfig?.type === "select"
+      ? flattenSessionConfigSelectOptions(reasoningConfig).flatMap((entry) => {
+          const normalizedValue = normalizeCursorReasoningValue(entry.value);
+          if (!normalizedValue) {
+            return [];
+          }
+          return [
+            {
+              value: normalizedValue,
+              label: entry.name,
+              ...(normalizeCursorReasoningValue(reasoningConfig.currentValue) === normalizedValue
+                ? { isDefault: true }
+                : {}),
+            },
+          ];
+        })
+      : [];
+
+  const contextOption = configOptions.find(
+    (option) => option.category === "model_config" && isCursorContextConfigOption(option),
+  );
+  const contextWindowOptions =
+    contextOption?.type === "select"
+      ? flattenSessionConfigSelectOptions(contextOption).map((entry) => {
+          if (contextOption.currentValue === entry.value) {
+            return {
+              value: entry.value,
+              label: entry.name,
+              isDefault: true,
+            };
+          }
+          return {
+            value: entry.value,
+            label: entry.name,
+          };
+        })
+      : [];
+
+  const fastOption = configOptions.find(
+    (option) => option.category === "model_config" && isCursorFastConfigOption(option),
+  );
+  const thinkingOption = configOptions.find(
+    (option) => option.category === "model_config" && isCursorThinkingConfigOption(option),
+  );
+  const fastCurrentValue = getBooleanCurrentValue(fastOption);
+  const thinkingCurrentValue = getBooleanCurrentValue(thinkingOption);
+  const optionDescriptors = [
+    ...(reasoningEffortLevels.length > 0
+      ? [
+          buildSelectOptionDescriptor({
+            id: "reasoning",
+            label: reasoningConfig?.name?.trim() || "Reasoning",
+            options: reasoningEffortLevels,
+          }),
+        ]
+      : []),
+    ...(contextWindowOptions.length > 0
+      ? [
+          buildSelectOptionDescriptor({
+            id: "contextWindow",
+            label: contextOption?.name?.trim() || "Context Window",
+            options: contextWindowOptions,
+          }),
+        ]
+      : []),
+    ...(fastOption && isBooleanLikeConfigOption(fastOption)
+      ? [
+          typeof fastCurrentValue === "boolean"
+            ? buildBooleanOptionDescriptor({
+                id: "fastMode",
+                label: fastOption.name?.trim() || "Fast Mode",
+                currentValue: fastCurrentValue,
+              })
+            : buildBooleanOptionDescriptor({
+                id: "fastMode",
+                label: fastOption.name?.trim() || "Fast Mode",
+              }),
+        ]
+      : []),
+    ...(thinkingOption && isBooleanLikeConfigOption(thinkingOption)
+      ? [
+          typeof thinkingCurrentValue === "boolean"
+            ? buildBooleanOptionDescriptor({
+                id: "thinking",
+                label: thinkingOption.name?.trim() || "Thinking",
+                currentValue: thinkingCurrentValue,
+              })
+            : buildBooleanOptionDescriptor({
+                id: "thinking",
+                label: thinkingOption.name?.trim() || "Thinking",
+              }),
+        ]
+      : []),
+  ];
+
+  return createModelCapabilities({
+    optionDescriptors,
+  });
+}
+
+function buildCursorDiscoveredModels(
+  discoveredModels: ReadonlyArray<CursorAcpDiscoveredModel>,
+): ReadonlyArray<ServerProviderModel> {
+  const seen = new Set<string>();
+  return discoveredModels.flatMap((model) => {
+    if (!model.slug || seen.has(model.slug)) {
+      return [];
+    }
+    seen.add(model.slug);
+    return [
+      {
+        slug: model.slug,
+        name: model.name,
+        isCustom: false,
+        capabilities: model.capabilities,
+      } satisfies ServerProviderModel,
+    ];
+  });
+}
+
+function hasCursorModelCapabilities(model: Pick<ServerProviderModel, "capabilities">): boolean {
+  return (model.capabilities?.optionDescriptors?.length ?? 0) > 0;
+}
+
+export function buildCursorDiscoveredModelsFromConfigOptions(
+  configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption> | null | undefined,
+): ReadonlyArray<ServerProviderModel> {
+  if (!configOptions || configOptions.length === 0) {
+    return [];
+  }
+
+  const modelOption = findCursorModelConfigOption(configOptions);
+  const modelChoices = flattenSessionConfigSelectOptions(modelOption);
+  if (!modelOption || modelChoices.length === 0) {
+    return [];
+  }
+
+  const currentModelValue =
+    modelOption.type === "select" ? modelOption.currentValue?.trim() || undefined : undefined;
+  const currentModelCapabilities = buildCursorCapabilitiesFromConfigOptions(configOptions);
+
+  return buildCursorDiscoveredModels(
+    modelChoices.map((modelChoice) => ({
+      slug: modelChoice.value.trim(),
+      name: modelChoice.name.trim(),
+      capabilities:
+        currentModelValue === modelChoice.value.trim()
+          ? currentModelCapabilities
+          : EMPTY_CAPABILITIES,
+    })),
+  );
+}
+
+const makeCursorAcpProbeRuntime = (
+  cursorSettings: CursorSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const acpContext = yield* Layer.build(
+      AcpSessionRuntime.layer({
+        spawn: {
+          command: cursorSettings.binaryPath,
+          args: [
+            ...(cursorSettings.apiEndpoint ? (["-e", cursorSettings.apiEndpoint] as const) : []),
+            "acp",
+          ],
+          cwd: process.cwd(),
+          env: environment,
+        },
+        cwd: process.cwd(),
+        clientInfo: { name: "t3-code-provider-probe", version: "0.0.0" },
+        authMethodId: "cursor_login",
+        clientCapabilities: CURSOR_PARAMETERIZED_MODEL_PICKER_CAPABILITIES,
+      }).pipe(Layer.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner))),
+    );
+    return yield* Effect.service(AcpSessionRuntime).pipe(Effect.provide(acpContext));
+  });
+
+const withCursorAcpProbeRuntime = <A, E, R>(
+  cursorSettings: CursorSettings,
+  useRuntime: (acp: AcpSessionRuntime["Service"]) => Effect.Effect<A, E, R>,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  makeCursorAcpProbeRuntime(cursorSettings, environment).pipe(
+    Effect.flatMap(useRuntime),
+    Effect.scoped,
+  );
+
+function normalizeCursorConfigOptionToken(value: string | null | undefined): string {
+  return (
+    value
+      ?.trim()
+      .toLowerCase()
+      .replace(/[\s_-]+/g, "-") ?? ""
+  );
+}
+
+function findCursorSelectOptionValue(
+  configOption: EffectAcpSchema.SessionConfigOption | undefined,
+  matcher: (option: CursorSessionSelectOption) => boolean,
+): string | undefined {
+  return flattenSessionConfigSelectOptions(configOption).find(matcher)?.value;
+}
+
+function findCursorBooleanConfigValue(
+  configOption: EffectAcpSchema.SessionConfigOption | undefined,
+  requested: boolean,
+): string | boolean | undefined {
+  if (!configOption) {
+    return undefined;
+  }
+  if (configOption.type === "boolean") {
+    return requested;
+  }
+  return findCursorSelectOptionValue(
+    configOption,
+    (option) => normalizeCursorConfigOptionToken(option.value) === String(requested),
+  );
+}
+
+export function resolveCursorAcpBaseModelId(model: string | null | undefined): string {
+  const trimmed = model?.trim();
+  const base = trimmed && trimmed.length > 0 ? trimmed : "default";
+  return base.includes("[") ? base.slice(0, base.indexOf("[")) : base;
+}
+
+export function resolveCursorAcpConfigUpdates(
+  configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption> | null | undefined,
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+): ReadonlyArray<{
+  readonly configId: string;
+  readonly value: string | boolean;
+}> {
+  if (!configOptions || configOptions.length === 0) {
+    return [];
+  }
+
+  const updates: Array<{
+    readonly configId: string;
+    readonly value: string | boolean;
+  }> = [];
+
+  const reasoningOption = findCursorEffortConfigOption(configOptions);
+  const requestedReasoning = normalizeCursorReasoningValue(
+    getProviderOptionStringSelectionValue(selections, "reasoning"),
+  );
+  if (reasoningOption && requestedReasoning) {
+    const value = findCursorSelectOptionValue(reasoningOption, (option) => {
+      const normalizedValue = normalizeCursorReasoningValue(option.value);
+      const normalizedName = normalizeCursorReasoningValue(option.name);
+      return normalizedValue === requestedReasoning || normalizedName === requestedReasoning;
+    });
+    if (value) {
+      updates.push({ configId: reasoningOption.id, value });
+    }
+  }
+
+  const contextOption = configOptions.find(
+    (option) => option.category === "model_config" && isCursorContextConfigOption(option),
+  );
+  const requestedContextWindow = getProviderOptionStringSelectionValue(selections, "contextWindow");
+  if (contextOption && requestedContextWindow) {
+    const value = findCursorSelectOptionValue(
+      contextOption,
+      (option) =>
+        normalizeCursorConfigOptionToken(option.value) ===
+          normalizeCursorConfigOptionToken(requestedContextWindow) ||
+        normalizeCursorConfigOptionToken(option.name) ===
+          normalizeCursorConfigOptionToken(requestedContextWindow),
+    );
+    if (value) {
+      updates.push({ configId: contextOption.id, value });
+    }
+  }
+
+  const fastOption = configOptions.find(
+    (option) => option.category === "model_config" && isCursorFastConfigOption(option),
+  );
+  const requestedFastMode = getProviderOptionBooleanSelectionValue(selections, "fastMode");
+  if (fastOption && typeof requestedFastMode === "boolean") {
+    const value = findCursorBooleanConfigValue(fastOption, requestedFastMode);
+    if (value !== undefined) {
+      updates.push({ configId: fastOption.id, value });
+    }
+  }
+
+  const thinkingOption = configOptions.find(
+    (option) => option.category === "model_config" && isCursorThinkingConfigOption(option),
+  );
+  const requestedThinking = getProviderOptionBooleanSelectionValue(selections, "thinking");
+  if (thinkingOption && typeof requestedThinking === "boolean") {
+    const value = findCursorBooleanConfigValue(thinkingOption, requestedThinking);
+    if (value !== undefined) {
+      updates.push({ configId: thinkingOption.id, value });
+    }
+  }
+
+  return updates;
+}
+
+export const discoverCursorModelsViaAcp = (
+  cursorSettings: CursorSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  withCursorAcpProbeRuntime(
+    cursorSettings,
+    (acp) =>
+      Effect.map(acp.start(), (started) =>
+        buildCursorDiscoveredModelsFromConfigOptions(
+          started.sessionSetupResult.configOptions ?? [],
+        ),
+      ),
+    environment,
+  );
+
+export const discoverCursorModelCapabilitiesViaAcp = (
+  cursorSettings: CursorSettings,
+  existingModels: ReadonlyArray<ServerProviderModel>,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  withCursorAcpProbeRuntime(
+    cursorSettings,
+    (acp) =>
+      Effect.gen(function* () {
+        const started = yield* acp.start();
+        const initialConfigOptions = started.sessionSetupResult.configOptions ?? [];
+        const modelOption = findCursorModelConfigOption(initialConfigOptions);
+        const modelChoices = flattenSessionConfigSelectOptions(modelOption);
+        if (!modelOption || modelChoices.length === 0) {
+          return [];
+        }
+
+        const currentModelValue =
+          modelOption.type === "select" ? modelOption.currentValue?.trim() || undefined : undefined;
+        const capabilitiesBySlug = new Map<string, ModelCapabilities>();
+        if (currentModelValue) {
+          capabilitiesBySlug.set(
+            currentModelValue,
+            buildCursorCapabilitiesFromConfigOptions(initialConfigOptions),
+          );
+        }
+
+        const targetModelSlugs = new Set(
+          existingModels
+            .filter((model) => !model.isCustom && !hasCursorModelCapabilities(model))
+            .map((model) => model.slug),
+        );
+        if (targetModelSlugs.size === 0) {
+          return buildCursorDiscoveredModels(
+            modelChoices.map((modelChoice) => ({
+              slug: modelChoice.value.trim(),
+              name: modelChoice.name.trim(),
+              capabilities: capabilitiesBySlug.get(modelChoice.value.trim()) ?? EMPTY_CAPABILITIES,
+            })),
+          );
+        }
+
+        const probedCapabilities = yield* Effect.forEach(
+          modelChoices,
+          (modelChoice) => {
+            const modelSlug = modelChoice.value.trim();
+            if (
+              !modelSlug ||
+              !targetModelSlugs.has(modelSlug) ||
+              capabilitiesBySlug.has(modelSlug)
+            ) {
+              return Effect.void.pipe(
+                Effect.as<readonly [string, ModelCapabilities] | undefined>(undefined),
+              );
+            }
+
+            return withCursorAcpProbeRuntime(
+              cursorSettings,
+              (probeAcp) =>
+                Effect.gen(function* () {
+                  const probeStarted = yield* probeAcp.start();
+                  const probeConfigOptions = probeStarted.sessionSetupResult.configOptions ?? [];
+                  const probeModelOption = findCursorModelConfigOption(probeConfigOptions);
+                  const probeCurrentModelValue =
+                    probeModelOption?.type === "select"
+                      ? probeModelOption.currentValue?.trim() || undefined
+                      : undefined;
+                  yield* Effect.annotateCurrentSpan({
+                    "cursor.acp.model.value": modelSlug,
+                    "cursor.acp.model.currentValue": probeCurrentModelValue,
+                    "cursor.acp.config_option_id": probeModelOption?.id ?? modelOption.id,
+                  });
+                  const nextConfigOptions =
+                    probeCurrentModelValue === modelSlug
+                      ? probeConfigOptions
+                      : yield* probeAcp
+                          .setConfigOption(probeModelOption?.id ?? modelOption.id, modelSlug)
+                          .pipe(
+                            Effect.map((response) => response.configOptions ?? probeConfigOptions),
+                          );
+                  return [
+                    modelSlug,
+                    buildCursorCapabilitiesFromConfigOptions(nextConfigOptions),
+                  ] as const;
+                }),
+              environment,
+            ).pipe(
+              Effect.timeout(CURSOR_ACP_MODEL_CAPABILITY_TIMEOUT),
+              Effect.retry({ times: 3 }),
+              Effect.withSpan("cursor-acp-model-capability-probe"),
+              Effect.catchCause((cause) =>
+                Effect.logWarning("Cursor ACP capability probe failed", {
+                  modelSlug,
+                  cause: Cause.pretty(cause),
+                }),
+              ),
+            );
+          },
+          { concurrency: CURSOR_ACP_MODEL_DISCOVERY_CONCURRENCY },
+        );
+
+        for (const entry of probedCapabilities) {
+          if (!entry) {
+            continue;
+          }
+          capabilitiesBySlug.set(entry[0], entry[1]);
+        }
+
+        return buildCursorDiscoveredModels(
+          modelChoices.map((modelChoice) => ({
+            slug: modelChoice.value.trim(),
+            name: modelChoice.name.trim(),
+            capabilities: capabilitiesBySlug.get(modelChoice.value.trim()) ?? EMPTY_CAPABILITIES,
+          })),
+        );
+      }).pipe(Effect.withSpan("cursor-acp-model-capability-discovery", {})),
+    environment,
+  );
+
+export function getCursorFallbackModels(
+  cursorSettings: Pick<CursorSettings, "customModels">,
+): ReadonlyArray<ServerProviderModel> {
+  return providerModelsFromSettings([], PROVIDER, cursorSettings.customModels, EMPTY_CAPABILITIES);
+}
+
+/** Timeout for `agent about` — it's slower than a simple `--version` probe. */
+const ABOUT_TIMEOUT_MS = 8_000;
+
+/** Strip ANSI escape sequences so we can parse plain key-value lines. */
+function stripAnsi(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\x1b\[[0-9;]*[A-Za-z]|\x1b\].*?\x07/g, "");
+}
+
+/**
+ * Extract a value from `agent about` key-value output.
+ * Lines look like: `CLI Version         2026.03.20-44cb435`
+ */
+function extractAboutField(plain: string, key: string): string | undefined {
+  const regex = new RegExp(`^${key}\\s{2,}(.+)$`, "mi");
+  const match = regex.exec(plain);
+  return match?.[1]?.trim();
+}
+
+export interface CursorAboutResult {
+  readonly version: string | null;
+  readonly status: Exclude<ServerProviderState, "disabled">;
+  readonly auth: ServerProviderAuth;
+  readonly message?: string;
+}
+
+function joinProviderMessages(...messages: ReadonlyArray<string | undefined>): string | undefined {
+  const parts = messages
+    .map((message) => message?.trim())
+    .filter((message): message is string => Boolean(message));
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
+export function buildCursorProviderSnapshot(input: {
+  readonly checkedAt: string;
+  readonly cursorSettings: CursorSettings;
+  readonly parsed: CursorAboutResult;
+  readonly discoveredModels?: ReadonlyArray<ServerProviderModel>;
+  readonly discoveryWarning?: string;
+}): ServerProviderDraft {
+  const message = joinProviderMessages(input.parsed.message, input.discoveryWarning);
+  return buildServerProvider({
+    presentation: CURSOR_PRESENTATION,
+    enabled: input.cursorSettings.enabled,
+    checkedAt: input.checkedAt,
+    models: providerModelsFromSettings(
+      input.discoveredModels ?? [],
+      PROVIDER,
+      input.cursorSettings.customModels,
+      EMPTY_CAPABILITIES,
+    ),
+    probe: {
+      installed: true,
+      version: input.parsed.version,
+      status:
+        input.discoveryWarning && input.parsed.status === "ready" ? "warning" : input.parsed.status,
+      auth: input.parsed.auth,
+      ...(message ? { message } : {}),
+    },
+  });
+}
+
+interface CursorAboutJsonPayload {
+  readonly cliVersion?: unknown;
+  readonly subscriptionTier?: unknown;
+  readonly userEmail?: unknown;
+}
+
+export function parseCursorVersionDate(version: string | null | undefined): number | undefined {
+  const match = version?.trim().match(/^(\d{4})\.(\d{2})\.(\d{2})(?:\b|-|$)/);
+  if (!match) {
+    return undefined;
+  }
+  const [, year, month, day] = match;
+  return Number(`${year}${month}${day}`);
+}
+
+export function parseCursorCliConfigChannel(raw: string): string | undefined {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "channel" in parsed &&
+      typeof parsed.channel === "string"
+    ) {
+      const channel = parsed.channel.trim().toLowerCase();
+      return channel.length > 0 ? channel : undefined;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function toTitleCaseWords(value: string): string {
+  return value
+    .split(/[\s_-]+/g)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join(" ");
+}
+
+function cursorSubscriptionLabel(subscriptionType: string | undefined): string | undefined {
+  const normalized = subscriptionType?.toLowerCase().replace(/[\s_-]+/g, "");
+  if (!normalized) return undefined;
+
+  switch (normalized) {
+    case "team":
+      return "Team";
+    case "pro":
+      return "Pro";
+    case "free":
+      return "Free";
+    case "business":
+      return "Business";
+    case "enterprise":
+      return "Enterprise";
+    default:
+      return toTitleCaseWords(subscriptionType!);
+  }
+}
+
+function cursorAuthMetadata(
+  subscriptionType: string | undefined,
+): Pick<ServerProviderAuth, "label" | "type"> | undefined {
+  if (!subscriptionType) {
+    return undefined;
+  }
+  const subscriptionLabel = cursorSubscriptionLabel(subscriptionType);
+  return {
+    type: subscriptionType,
+    label: `Cursor ${subscriptionLabel ?? toTitleCaseWords(subscriptionType)} Subscription`,
+  };
+}
+
+function parseCursorAboutJsonPayload(raw: string): CursorAboutJsonPayload | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("{")) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(trimmed) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return undefined;
+    }
+    return parsed as CursorAboutJsonPayload;
+  } catch {
+    return undefined;
+  }
+}
+
+function hasOwn(record: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function isCursorAboutJsonFormatUnsupported(result: CommandResult): boolean {
+  const lowerOutput = `${result.stdout}\n${result.stderr}`.toLowerCase();
+  return (
+    lowerOutput.includes("unknown option '--format'") ||
+    lowerOutput.includes("unexpected argument '--format'") ||
+    lowerOutput.includes("unrecognized option '--format'") ||
+    lowerOutput.includes("unknown argument '--format'")
+  );
+}
+
+const readCursorCliConfigChannel = Effect.fn("readCursorCliConfigChannel")(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const configPath = path.join(NodeOs.homedir(), ".cursor", "cli-config.json");
+  const raw = yield* fileSystem.readFileString(configPath).pipe(Effect.orElseSucceed(() => ""));
+  return parseCursorCliConfigChannel(raw);
+});
+
+export function getCursorParameterizedModelPickerUnsupportedMessage(input: {
+  readonly version: string | null | undefined;
+  readonly channel: string | null | undefined;
+}): string | undefined {
+  const reasons: Array<string> = [];
+  const versionDate = parseCursorVersionDate(input.version);
+  if (
+    versionDate !== undefined &&
+    versionDate < CURSOR_PARAMETERIZED_MODEL_PICKER_MIN_VERSION_DATE
+  ) {
+    reasons.push(
+      `Cursor Agent CLI version ${input.version} is too old for Cursor ACP parameterized model picker`,
+    );
+  }
+
+  const normalizedChannel = input.channel?.trim().toLowerCase();
+  if (
+    normalizedChannel !== undefined &&
+    normalizedChannel.length > 0 &&
+    normalizedChannel !== "lab"
+  ) {
+    reasons.push(
+      `Cursor Agent CLI channel is ${JSON.stringify(input.channel)}, but parameterized model picker is only available on the lab channel`,
+    );
+  }
+
+  if (reasons.length === 0) {
+    return undefined;
+  }
+
+  return `${reasons.join(". ")}. Run \`agent set-channel lab && agent update\` and use Cursor Agent CLI 2026.04.08 or newer.`;
+}
+
+/**
+ * Parse the output of `agent about` to extract version and authentication
+ * status in a single probe.
+ *
+ * Example output (logged in):
+ * ```
+ * About Cursor CLI
+ *
+ * CLI Version         2026.03.20-44cb435
+ * User Email          user@example.com
+ * ```
+ *
+ * Example output (logged out):
+ * ```
+ * About Cursor CLI
+ *
+ * CLI Version         2026.03.20-44cb435
+ * User Email          Not logged in
+ * ```
+ */
+export function parseCursorAboutOutput(result: CommandResult): CursorAboutResult {
+  const jsonPayload = parseCursorAboutJsonPayload(result.stdout);
+  if (jsonPayload) {
+    const version =
+      typeof jsonPayload.cliVersion === "string" ? jsonPayload.cliVersion.trim() : null;
+    const hasUserEmailField = hasOwn(jsonPayload, "userEmail");
+    const userEmail =
+      typeof jsonPayload.userEmail === "string" ? jsonPayload.userEmail.trim() : undefined;
+    const subscriptionType =
+      typeof jsonPayload.subscriptionTier === "string"
+        ? jsonPayload.subscriptionTier.trim()
+        : undefined;
+    const authMetadata = cursorAuthMetadata(subscriptionType);
+
+    if (hasUserEmailField && jsonPayload.userEmail == null) {
+      return {
+        version,
+        status: "error",
+        auth: { status: "unauthenticated" },
+        message: "Cursor Agent is not authenticated. Run `agent login` and try again.",
+      };
+    }
+
+    if (!userEmail) {
+      if (result.code === 0) {
+        return {
+          version,
+          status: "ready",
+          auth: {
+            status: "unknown",
+            ...authMetadata,
+          },
+        };
+      }
+      return {
+        version,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Could not verify Cursor Agent authentication status.",
+      };
+    }
+
+    const lowerEmail = userEmail.toLowerCase();
+    if (
+      lowerEmail === "not logged in" ||
+      lowerEmail.includes("login required") ||
+      lowerEmail.includes("authentication required")
+    ) {
+      return {
+        version,
+        status: "error",
+        auth: { status: "unauthenticated" },
+        message: "Cursor Agent is not authenticated. Run `agent login` and try again.",
+      };
+    }
+
+    return {
+      version,
+      status: "ready",
+      auth: {
+        status: "authenticated",
+        email: userEmail,
+        ...authMetadata,
+      },
+    };
+  }
+
+  const combined = `${result.stdout}\n${result.stderr}`;
+  const lowerOutput = combined.toLowerCase();
+
+  // If the command itself isn't recognised, we're on an old CLI version.
+  if (
+    lowerOutput.includes("unknown command") ||
+    lowerOutput.includes("unrecognized command") ||
+    lowerOutput.includes("unexpected argument")
+  ) {
+    return {
+      version: null,
+      status: "warning",
+      auth: { status: "unknown" },
+      message: "The `agent about` command is unavailable in this version of the Cursor Agent CLI.",
+    };
+  }
+
+  const plain = stripAnsi(combined);
+  const version = extractAboutField(plain, "CLI Version") ?? null;
+  const userEmail = extractAboutField(plain, "User Email");
+
+  // Determine auth from the User Email field.
+  if (userEmail === undefined) {
+    // Field missing entirely — can't determine auth.
+    if (result.code === 0) {
+      return { version, status: "ready", auth: { status: "unknown" } };
+    }
+    return {
+      version,
+      status: "warning",
+      auth: { status: "unknown" },
+      message: "Could not verify Cursor Agent authentication status.",
+    };
+  }
+
+  const lowerEmail = userEmail.toLowerCase();
+  if (
+    lowerEmail === "not logged in" ||
+    lowerEmail.includes("login required") ||
+    lowerEmail.includes("authentication required")
+  ) {
+    return {
+      version,
+      status: "error",
+      auth: { status: "unauthenticated" },
+      message: "Cursor Agent is not authenticated. Run `agent login` and try again.",
+    };
+  }
+
+  // Any non-empty email value means authenticated.
+  return {
+    version,
+    status: "ready",
+    auth: { status: "authenticated", email: userEmail },
+  };
+}
+
+const runCursorCommand = (
+  cursorSettings: CursorSettings,
+  args: ReadonlyArray<string>,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const command = ChildProcess.make(cursorSettings.binaryPath, [...args], {
+      env: environment,
+      shell: process.platform === "win32",
+    });
+
+    const child = yield* spawner.spawn(command);
+    const [stdout, stderr, exitCode] = yield* Effect.all(
+      [
+        collectStreamAsString(child.stdout),
+        collectStreamAsString(child.stderr),
+        child.exitCode.pipe(Effect.map(Number)),
+      ],
+      { concurrency: "unbounded" },
+    );
+
+    return { stdout, stderr, code: exitCode } satisfies CommandResult;
+  }).pipe(Effect.scoped);
+
+const runCursorAboutCommand = (
+  cursorSettings: CursorSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  Effect.gen(function* () {
+    const jsonResult = yield* runCursorCommand(
+      cursorSettings,
+      ["about", "--format", "json"],
+      environment,
+    );
+    if (!isCursorAboutJsonFormatUnsupported(jsonResult)) {
+      return jsonResult;
+    }
+    return yield* runCursorCommand(cursorSettings, ["about"], environment);
+  });
+
+export const checkCursorProviderStatus = Effect.fn("checkCursorProviderStatus")(function* (
+  cursorSettings: CursorSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<
+  ServerProviderDraft,
+  never,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const checkedAt = DateTime.formatIso(yield* DateTime.now);
+  const fallbackModels = getCursorFallbackModels(cursorSettings);
+
+  if (!cursorSettings.enabled) {
+    return buildServerProvider({
+      presentation: CURSOR_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models: fallbackModels,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Cursor is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  // Single `agent about` probe: returns version + auth status in one call.
+  const aboutProbe = yield* runCursorAboutCommand(cursorSettings, environment).pipe(
+    Effect.timeoutOption(ABOUT_TIMEOUT_MS),
+    Effect.result,
+  );
+
+  if (Result.isFailure(aboutProbe)) {
+    const error = aboutProbe.failure;
+    return buildServerProvider({
+      presentation: CURSOR_PRESENTATION,
+      enabled: cursorSettings.enabled,
+      checkedAt,
+      models: fallbackModels,
+      probe: {
+        installed: !isCommandMissingCause(error),
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: isCommandMissingCause(error)
+          ? "Cursor Agent CLI (`agent`) is not installed or not on PATH."
+          : `Failed to execute Cursor Agent CLI health check: ${error instanceof Error ? error.message : String(error)}.`,
+      },
+    });
+  }
+
+  if (Option.isNone(aboutProbe.success)) {
+    return buildServerProvider({
+      presentation: CURSOR_PRESENTATION,
+      enabled: cursorSettings.enabled,
+      checkedAt,
+      models: fallbackModels,
+      probe: {
+        installed: true,
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: "Cursor Agent CLI is installed but timed out while running `agent about`.",
+      },
+    });
+  }
+
+  const parsed = parseCursorAboutOutput(aboutProbe.success.value);
+  const cursorCliConfigChannel = yield* readCursorCliConfigChannel();
+  const parameterizedModelPickerUnsupportedMessage =
+    getCursorParameterizedModelPickerUnsupportedMessage({
+      version: parsed.version,
+      channel: cursorCliConfigChannel,
+    });
+  if (parameterizedModelPickerUnsupportedMessage) {
+    return buildServerProvider({
+      presentation: CURSOR_PRESENTATION,
+      enabled: cursorSettings.enabled,
+      checkedAt,
+      models: fallbackModels,
+      probe: {
+        installed: true,
+        version: parsed.version,
+        status: "error",
+        auth: parsed.auth,
+        message:
+          parsed.auth.status === "unauthenticated" && parsed.message
+            ? `${parameterizedModelPickerUnsupportedMessage} ${parsed.message}`
+            : parameterizedModelPickerUnsupportedMessage,
+      },
+    });
+  }
+  let discoveredModels = Option.none<ReadonlyArray<ServerProviderModel>>();
+  let discoveryWarning: string | undefined;
+  if (parsed.auth.status !== "unauthenticated") {
+    const discoveryExit = yield* Effect.exit(
+      discoverCursorModelsViaAcp(cursorSettings, environment).pipe(
+        Effect.timeoutOption(CURSOR_ACP_MODEL_DISCOVERY_TIMEOUT_MS),
+      ),
+    );
+    if (Exit.isFailure(discoveryExit)) {
+      yield* Effect.logWarning("Cursor ACP model discovery failed", {
+        cause: Cause.pretty(discoveryExit.cause),
+      });
+      discoveryWarning = "Cursor ACP model discovery failed. Check server logs for details.";
+    } else if (Option.isNone(discoveryExit.value)) {
+      discoveryWarning = `Cursor ACP model discovery timed out after ${CURSOR_ACP_MODEL_DISCOVERY_TIMEOUT_MS}ms.`;
+    } else if (discoveryExit.value.value.length === 0) {
+      discoveryWarning = "Cursor ACP model discovery returned no built-in models.";
+    } else {
+      discoveredModels = discoveryExit.value;
+    }
+  }
+  return buildCursorProviderSnapshot({
+    checkedAt,
+    cursorSettings,
+    parsed,
+    discoveredModels: Option.getOrElse(
+      Option.filter(discoveredModels, (models) => models.length > 0),
+      () => [] as const,
+    ),
+    ...(discoveryWarning ? { discoveryWarning } : {}),
+  });
+});
+
+export function hasUncapturedCursorModels(snapshot: Pick<ServerProvider, "models">): boolean {
+  return snapshot.models.some((model) => !model.isCustom && !hasCursorModelCapabilities(model));
+}
+
+/**
+ * Background capability enrichment for a Cursor snapshot.
+ *
+ * Used by `CursorDriver` as the `makeManagedServerProvider.enrichSnapshot`
+ * hook: runs the slow ACP per-model capability probe, and republishes the
+ * snapshot through `publishSnapshot` when new capabilities arrive. Skips
+ * the probe when the provider is disabled, unauthenticated, or has no
+ * uncaptured models. Keeps `EMPTY_CAPABILITIES` and the `PROVIDER` literal
+ * private to this module.
+ */
+export const enrichCursorSnapshot = (input: {
+  readonly settings: CursorSettings;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly snapshot: ServerProvider;
+  readonly maintenanceCapabilities: ProviderMaintenanceCapabilities;
+  readonly publishSnapshot: (snapshot: ServerProvider) => Effect.Effect<void>;
+  readonly stampIdentity?: (snapshot: ServerProvider) => ServerProvider;
+  readonly httpClient: HttpClient.HttpClient;
+}): Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner> => {
+  const { settings, snapshot, publishSnapshot } = input;
+  const stampIdentity = input.stampIdentity ?? ((value) => value);
+
+  const enrichVersionAdvisory = enrichProviderSnapshotWithVersionAdvisory(
+    snapshot,
+    input.maintenanceCapabilities,
+  ).pipe(
+    Effect.provideService(HttpClient.HttpClient, input.httpClient),
+    Effect.flatMap((enrichedSnapshot) =>
+      publishSnapshot(stampIdentity(enrichedSnapshot)).pipe(Effect.as(enrichedSnapshot)),
+    ),
+    Effect.catchCause((cause) =>
+      Effect.logWarning("Cursor version advisory enrichment failed", {
+        cause: Cause.pretty(cause),
+      }).pipe(Effect.as(snapshot)),
+    ),
+  );
+
+  return enrichVersionAdvisory.pipe(
+    Effect.flatMap((baseSnapshot) => {
+      if (
+        !settings.enabled ||
+        baseSnapshot.auth.status === "unauthenticated" ||
+        !hasUncapturedCursorModels(baseSnapshot)
+      ) {
+        return Effect.void;
+      }
+
+      return discoverCursorModelCapabilitiesViaAcp(
+        settings,
+        baseSnapshot.models,
+        input.environment,
+      ).pipe(
+        Effect.flatMap((discoveredModels) => {
+          if (discoveredModels.length === 0) {
+            return Effect.void;
+          }
+          return publishSnapshot(
+            stampIdentity({
+              ...baseSnapshot,
+              models: providerModelsFromSettings(
+                discoveredModels,
+                PROVIDER,
+                settings.customModels,
+                EMPTY_CAPABILITIES,
+              ),
+            }),
+          );
+        }),
+        Effect.catchCause((cause) =>
+          Effect.logWarning("Cursor ACP background capability enrichment failed", {
+            models: baseSnapshot.models.map((model) => model.slug),
+            cause: Cause.pretty(cause),
+          }).pipe(Effect.asVoid),
+        ),
+      );
+    }),
+  );
+};
diff --git a/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts b/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
index aa7e5a26927..0b1f99d3c11 100644
--- a/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
+++ b/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
@@ -1,10 +1,11 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import { ThreadId } from "@t3tools/contracts";
 import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 
 import { makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
 
diff --git a/apps/server/src/provider/Layers/EventNdjsonLogger.ts b/apps/server/src/provider/Layers/EventNdjsonLogger.ts
index 2a512efe660..3b36cc20c90 100644
--- a/apps/server/src/provider/Layers/EventNdjsonLogger.ts
+++ b/apps/server/src/provider/Layers/EventNdjsonLogger.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics nodeBuiltinImport:off
 /**
  * Provider event logger helper.
  *
@@ -10,7 +11,11 @@ import path from "node:path";
 
 import type { ThreadId } from "@t3tools/contracts";
 import { RotatingFileSink } from "@t3tools/shared/logging";
-import { Effect, Exit, Logger, Scope, SynchronizedRef } from "effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Logger from "effect/Logger";
+import * as Scope from "effect/Scope";
+import * as SynchronizedRef from "effect/SynchronizedRef";
 
 import { toSafeThreadAttachmentSegment } from "../../attachmentStore.ts";
 
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
new file mode 100644
index 00000000000..66dc5edc671
--- /dev/null
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
@@ -0,0 +1,840 @@
+import assert from "node:assert/strict";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+import { beforeEach } from "vitest";
+
+import {
+  OpenCodeSettings,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ThreadId,
+} from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
+import { ServerConfig } from "../../config.ts";
+import { ServerSettingsService } from "../../serverSettings.ts";
+import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
+import type { OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
+import {
+  OpenCodeRuntime,
+  OpenCodeRuntimeError,
+  type OpenCodeRuntimeShape,
+} from "../opencodeRuntime.ts";
+import {
+  appendOpenCodeAssistantTextDelta,
+  makeOpenCodeAdapter,
+  mergeOpenCodeAssistantText,
+} from "./OpenCodeAdapter.ts";
+
+// Test-local service tag so the rest of the file can keep using `yield* OpenCodeAdapter`.
+class OpenCodeAdapter extends Context.Service<OpenCodeAdapter, OpenCodeAdapterShape>()(
+  "test/OpenCodeAdapter",
+) {}
+
+const asThreadId = (value: string): ThreadId => ThreadId.make(value);
+
+type MessageEntry = {
+  info: {
+    id: string;
+    role: "user" | "assistant";
+  };
+  parts: Array<unknown>;
+};
+
+const runtimeMock = {
+  state: {
+    startCalls: [] as string[],
+    sessionCreateUrls: [] as string[],
+    authHeaders: [] as Array<string | null>,
+    abortCalls: [] as string[],
+    closeCalls: [] as string[],
+    revertCalls: [] as Array<{ sessionID: string; messageID?: string }>,
+    promptCalls: [] as Array<unknown>,
+    promptAsyncError: null as Error | null,
+    closeError: null as Error | null,
+    messages: [] as MessageEntry[],
+    subscribedEvents: [] as unknown[],
+  },
+  reset() {
+    this.state.startCalls.length = 0;
+    this.state.sessionCreateUrls.length = 0;
+    this.state.authHeaders.length = 0;
+    this.state.abortCalls.length = 0;
+    this.state.closeCalls.length = 0;
+    this.state.revertCalls.length = 0;
+    this.state.promptCalls.length = 0;
+    this.state.promptAsyncError = null;
+    this.state.closeError = null;
+    this.state.messages = [];
+    this.state.subscribedEvents = [];
+  },
+};
+
+const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
+  startOpenCodeServerProcess: ({ binaryPath }) =>
+    Effect.gen(function* () {
+      runtimeMock.state.startCalls.push(binaryPath);
+      const url = "http://127.0.0.1:4301";
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          runtimeMock.state.closeCalls.push(url);
+          if (runtimeMock.state.closeError) {
+            throw runtimeMock.state.closeError;
+          }
+        }),
+      );
+      return {
+        url,
+        exitCode: Effect.never,
+      };
+    }),
+  connectToOpenCodeServer: ({ serverUrl }) =>
+    Effect.gen(function* () {
+      const url = serverUrl ?? "http://127.0.0.1:4301";
+      // Unconditionally register a scope finalizer for test observability —
+      // preserves the `closeCalls` / `closeError` probes that the existing
+      // suites rely on. Production code never attaches a finalizer to an
+      // external server (it simply returns `Effect.succeed(...)`).
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          runtimeMock.state.closeCalls.push(url);
+          if (runtimeMock.state.closeError) {
+            throw runtimeMock.state.closeError;
+          }
+        }),
+      );
+      return {
+        url,
+        exitCode: null,
+        external: Boolean(serverUrl),
+      };
+    }),
+  runOpenCodeCommand: () => Effect.succeed({ stdout: "", stderr: "", code: 0 }),
+  createOpenCodeSdkClient: ({ baseUrl, serverPassword }) =>
+    ({
+      session: {
+        create: async () => {
+          runtimeMock.state.sessionCreateUrls.push(baseUrl);
+          runtimeMock.state.authHeaders.push(
+            serverPassword ? `Basic ${btoa(`opencode:${serverPassword}`)}` : null,
+          );
+          return { data: { id: `${baseUrl}/session` } };
+        },
+        abort: async ({ sessionID }: { sessionID: string }) => {
+          runtimeMock.state.abortCalls.push(sessionID);
+        },
+        promptAsync: async (input: unknown) => {
+          runtimeMock.state.promptCalls.push(input);
+          if (runtimeMock.state.promptAsyncError) {
+            throw runtimeMock.state.promptAsyncError;
+          }
+        },
+        messages: async () => ({ data: runtimeMock.state.messages }),
+        revert: async ({ sessionID, messageID }: { sessionID: string; messageID?: string }) => {
+          runtimeMock.state.revertCalls.push({
+            sessionID,
+            ...(messageID ? { messageID } : {}),
+          });
+          if (!messageID) {
+            runtimeMock.state.messages = [];
+            return;
+          }
+
+          const targetIndex = runtimeMock.state.messages.findIndex(
+            (entry) => entry.info.id === messageID,
+          );
+          runtimeMock.state.messages =
+            targetIndex >= 0
+              ? runtimeMock.state.messages.slice(0, targetIndex + 1)
+              : runtimeMock.state.messages;
+        },
+      },
+      event: {
+        subscribe: async () => ({
+          stream: (async function* () {
+            for (const event of runtimeMock.state.subscribedEvents) {
+              yield event;
+            }
+          })(),
+        }),
+      },
+    }) as unknown as ReturnType<OpenCodeRuntimeShape["createOpenCodeSdkClient"]>,
+  loadOpenCodeInventory: () =>
+    Effect.fail(
+      new OpenCodeRuntimeError({
+        operation: "loadOpenCodeInventory",
+        detail: "OpenCodeRuntimeTestDouble.loadOpenCodeInventory not used in this test",
+        cause: null,
+      }),
+    ),
+};
+
+const providerSessionDirectoryTestLayer = Layer.succeed(ProviderSessionDirectory, {
+  upsert: () => Effect.void,
+  getProvider: () =>
+    Effect.die(new Error("ProviderSessionDirectory.getProvider is not used in test")),
+  getBinding: () => Effect.succeed(Option.none()),
+  listThreadIds: () => Effect.succeed([]),
+  listBindings: () => Effect.succeed([]),
+});
+
+// The adapter now receives its settings as a plain argument (the old design
+// read from `ServerSettingsService` internally). The test-only
+// `ServerSettingsService` below is still kept because other dependencies in
+// the layer graph reach for it — but the routing values the assertions
+// probe (serverUrl, serverPassword) must be threaded directly through the
+// decoded `OpenCodeSettings`.
+const openCodeAdapterTestSettings = Schema.decodeSync(OpenCodeSettings)({
+  binaryPath: "fake-opencode",
+  serverUrl: "http://127.0.0.1:9999",
+  serverPassword: "secret-password",
+});
+
+const OpenCodeAdapterTestLayer = Layer.effect(
+  OpenCodeAdapter,
+  makeOpenCodeAdapter(openCodeAdapterTestSettings),
+).pipe(
+  Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
+  Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+  Layer.provideMerge(
+    ServerSettingsService.layerTest({
+      providers: {
+        opencode: {
+          binaryPath: "fake-opencode",
+          serverUrl: "http://127.0.0.1:9999",
+          serverPassword: "secret-password",
+        },
+      },
+    }),
+  ),
+  Layer.provideMerge(providerSessionDirectoryTestLayer),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+beforeEach(() => {
+  runtimeMock.reset();
+});
+
+const advanceTestClock = (ms: number) =>
+  TestClock.adjust(`${ms} millis`).pipe(Effect.andThen(Effect.yieldNow));
+
+it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
+  it.effect("reuses a configured OpenCode server URL instead of spawning a local server", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+
+      const session = yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId: asThreadId("thread-opencode"),
+        runtimeMode: "full-access",
+      });
+
+      assert.equal(session.provider, "opencode");
+      assert.equal(session.threadId, "thread-opencode");
+      assert.deepEqual(runtimeMock.state.startCalls, []);
+      assert.deepEqual(runtimeMock.state.sessionCreateUrls, ["http://127.0.0.1:9999"]);
+      assert.deepEqual(runtimeMock.state.authHeaders, [
+        `Basic ${btoa("opencode:secret-password")}`,
+      ]);
+    }),
+  );
+
+  it.effect("stops a configured-server session without trying to own server lifecycle", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId: asThreadId("thread-opencode"),
+        runtimeMode: "full-access",
+      });
+
+      yield* adapter.stopSession(asThreadId("thread-opencode"));
+
+      assert.deepEqual(runtimeMock.state.startCalls, []);
+      assert.deepEqual(
+        runtimeMock.state.abortCalls.includes("http://127.0.0.1:9999/session"),
+        true,
+      );
+    }),
+  );
+
+  it.effect("emits one session.exited event when stopping a session", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-opencode-stop-event");
+      const eventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.take(3),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      yield* adapter.stopSession(threadId);
+
+      const events = Array.from(yield* Fiber.join(eventsFiber).pipe(Effect.timeout("1 second")));
+      assert.deepEqual(
+        events.map((event) => event.type),
+        ["session.started", "thread.started", "session.exited"],
+      );
+    }),
+  );
+
+  it.effect("clears session state even when cleanup finalizers throw", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId: asThreadId("thread-stop-all-a"),
+        runtimeMode: "full-access",
+      });
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId: asThreadId("thread-stop-all-b"),
+        runtimeMode: "full-access",
+      });
+
+      runtimeMock.state.closeError = new Error("close failed");
+      // `stopAll` relies on `stopOpenCodeContext`, which is typed as
+      // never-failing. A throwing finalizer surfaces as a defect — `Effect.exit`
+      // captures it so the assertions can still run. The key invariant we're
+      // validating is "the sessions map and close-call probes reflect cleanup
+      // attempts regardless of finalizer outcome".
+      yield* Effect.exit(adapter.stopAll());
+      const sessions = yield* adapter.listSessions();
+
+      assert.deepEqual(runtimeMock.state.closeCalls, [
+        "http://127.0.0.1:9999",
+        "http://127.0.0.1:9999",
+      ]);
+      assert.deepEqual(sessions, []);
+    }),
+  );
+
+  it.effect("completes streamEvents when the adapter scope closes", () =>
+    Effect.gen(function* () {
+      const scope = yield* Scope.make("sequential");
+      let scopeClosed = false;
+
+      try {
+        const adapterLayer = Layer.effect(
+          OpenCodeAdapter,
+          makeOpenCodeAdapter(openCodeAdapterTestSettings),
+        ).pipe(
+          Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
+          Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+          Layer.provideMerge(ServerSettingsService.layerTest()),
+          Layer.provideMerge(providerSessionDirectoryTestLayer),
+          Layer.provideMerge(NodeServices.layer),
+        );
+        const context = yield* Layer.buildWithScope(adapterLayer, scope);
+        const adapter = yield* Effect.service(OpenCodeAdapter).pipe(Effect.provide(context));
+        const eventsFiber = yield* adapter.streamEvents.pipe(Stream.runCollect, Effect.forkChild);
+
+        yield* Scope.close(scope, Exit.void);
+        scopeClosed = true;
+
+        const exit = yield* Fiber.await(eventsFiber).pipe(Effect.timeout("1 second"));
+        assert.equal(Exit.hasInterrupts(exit), true);
+      } finally {
+        if (!scopeClosed) {
+          yield* Scope.close(scope, Exit.void).pipe(Effect.ignore);
+        }
+      }
+    }),
+  );
+
+  it.effect("rolls back session state when sendTurn fails before OpenCode accepts the prompt", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId: asThreadId("thread-send-turn-failure"),
+        runtimeMode: "full-access",
+      });
+
+      runtimeMock.state.promptAsyncError = new Error("prompt failed");
+      const error = yield* adapter
+        .sendTurn({
+          threadId: asThreadId("thread-send-turn-failure"),
+          input: "Fix it",
+          modelSelection: {
+            instanceId: ProviderInstanceId.make("opencode"),
+            model: "openai/gpt-5",
+          },
+        })
+        .pipe(Effect.flip);
+      const sessions = yield* adapter.listSessions();
+
+      assert.equal(error._tag, "ProviderAdapterRequestError");
+      if (error._tag !== "ProviderAdapterRequestError") {
+        throw new Error("Unexpected error type");
+      }
+      assert.equal(error.detail, "prompt failed");
+      assert.equal(
+        error.message,
+        "Provider adapter request failed (opencode) for session.promptAsync: prompt failed",
+      );
+      assert.equal(sessions.length, 1);
+      assert.equal(sessions[0]?.status, "ready");
+      assert.equal(sessions[0]?.activeTurnId, undefined);
+      assert.equal(sessions[0]?.lastError, "prompt failed");
+    }),
+  );
+
+  it.effect("passes agent and variant options for the adapter's bound custom instance id", () => {
+    const instanceId = ProviderInstanceId.make("opencode_zen");
+    const adapterLayer = Layer.effect(
+      OpenCodeAdapter,
+      makeOpenCodeAdapter(openCodeAdapterTestSettings, { instanceId }),
+    ).pipe(
+      Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
+      Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+      Layer.provideMerge(ServerSettingsService.layerTest()),
+      Layer.provideMerge(providerSessionDirectoryTestLayer),
+      Layer.provideMerge(NodeServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId: asThreadId("thread-custom-instance"),
+        runtimeMode: "full-access",
+      });
+
+      yield* adapter.sendTurn({
+        threadId: asThreadId("thread-custom-instance"),
+        input: "Fix it",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode_zen"),
+          "anthropic/claude-sonnet-4-5",
+          [
+            { id: "agent", value: "github-copilot" },
+            { id: "variant", value: "high" },
+          ],
+        ),
+      });
+
+      assert.deepEqual(runtimeMock.state.promptCalls.at(-1), {
+        sessionID: "http://127.0.0.1:9999/session",
+        model: {
+          providerID: "anthropic",
+          modelID: "claude-sonnet-4-5",
+        },
+        agent: "github-copilot",
+        variant: "high",
+        parts: [{ type: "text", text: "Fix it" }],
+      });
+    }).pipe(Effect.provide(adapterLayer));
+  });
+
+  it.effect("uses the bound custom instance id for fallback sendTurn model selection", () => {
+    const instanceId = ProviderInstanceId.make("opencode_zen");
+    const adapterLayer = Layer.effect(
+      OpenCodeAdapter,
+      makeOpenCodeAdapter(openCodeAdapterTestSettings, { instanceId }),
+    ).pipe(
+      Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
+      Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+      Layer.provideMerge(ServerSettingsService.layerTest()),
+      Layer.provideMerge(providerSessionDirectoryTestLayer),
+      Layer.provideMerge(NodeServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-custom-instance-fallback-model");
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode_zen"),
+          "anthropic/claude-sonnet-4-5",
+        ),
+      });
+
+      yield* adapter.sendTurn({
+        threadId,
+        input: "Fix it",
+      });
+
+      assert.deepEqual(runtimeMock.state.promptCalls.at(-1), {
+        sessionID: "http://127.0.0.1:9999/session",
+        model: {
+          providerID: "anthropic",
+          modelID: "claude-sonnet-4-5",
+        },
+        parts: [{ type: "text", text: "Fix it" }],
+      });
+    }).pipe(Effect.provide(adapterLayer));
+  });
+
+  it.effect("rejects sendTurn model selections for another instance id", () => {
+    const instanceId = ProviderInstanceId.make("opencode_zen");
+    const adapterLayer = Layer.effect(
+      OpenCodeAdapter,
+      makeOpenCodeAdapter(openCodeAdapterTestSettings, { instanceId }),
+    ).pipe(
+      Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
+      Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+      Layer.provideMerge(ServerSettingsService.layerTest()),
+      Layer.provideMerge(providerSessionDirectoryTestLayer),
+      Layer.provideMerge(NodeServices.layer),
+    );
+
+    return Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-custom-instance-wrong-selection");
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+
+      const error = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "Fix it",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("opencode"),
+            "anthropic/claude-sonnet-4-5",
+          ),
+        })
+        .pipe(Effect.flip);
+
+      assert.equal(error._tag, "ProviderAdapterValidationError");
+      if (error._tag !== "ProviderAdapterValidationError") {
+        throw new Error("Unexpected error type");
+      }
+      assert.equal(
+        error.issue,
+        "OpenCode model selection is bound to instance 'opencode', expected 'opencode_zen'.",
+      );
+      assert.deepEqual(runtimeMock.state.promptCalls, []);
+    }).pipe(Effect.provide(adapterLayer));
+  });
+
+  it.effect("reverts the full thread when rollback removes every assistant turn", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-rollback-all");
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+
+      runtimeMock.state.messages = [
+        {
+          info: { id: "assistant-1", role: "assistant" },
+          parts: [],
+        },
+        {
+          info: { id: "assistant-2", role: "assistant" },
+          parts: [],
+        },
+      ];
+
+      const snapshot = yield* adapter.rollbackThread(threadId, 2);
+
+      assert.deepEqual(runtimeMock.state.revertCalls, [
+        { sessionID: "http://127.0.0.1:9999/session" },
+      ]);
+      assert.deepEqual(snapshot.turns, []);
+    }),
+  );
+
+  it.effect("appends raw assistant text deltas and reconciles part update snapshots", () =>
+    Effect.sync(() => {
+      const firstUpdate = mergeOpenCodeAssistantText(undefined, "Hello");
+      const overlapDelta = appendOpenCodeAssistantTextDelta(firstUpdate.latestText, "lo world");
+      const secondUpdate = mergeOpenCodeAssistantText(overlapDelta.nextText, "Hellolo world");
+
+      assert.deepEqual(
+        [firstUpdate.deltaToEmit, overlapDelta.deltaToEmit, secondUpdate.deltaToEmit],
+        ["Hello", "lo world", ""],
+      );
+      assert.equal(secondUpdate.latestText, "Hellolo world");
+    }),
+  );
+
+  it.effect("does not strip coincidental prefix overlap from OpenCode part deltas", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-opencode-raw-delta");
+      const part = {
+        id: "part-raw-delta",
+        sessionID: "http://127.0.0.1:9999/session",
+        messageID: "msg-raw-delta",
+        type: "text",
+        text: "A B",
+        time: { start: 1 },
+      };
+      runtimeMock.state.subscribedEvents = [
+        {
+          type: "message.updated",
+          properties: {
+            sessionID: "http://127.0.0.1:9999/session",
+            info: {
+              id: "msg-raw-delta",
+              role: "assistant",
+            },
+          },
+        },
+        {
+          type: "message.part.updated",
+          properties: {
+            sessionID: "http://127.0.0.1:9999/session",
+            part,
+            time: 1,
+          },
+        },
+        {
+          type: "message.part.delta",
+          properties: {
+            sessionID: "http://127.0.0.1:9999/session",
+            messageID: "msg-raw-delta",
+            partID: "part-raw-delta",
+            field: "text",
+            delta: "Bonus",
+          },
+        },
+        {
+          type: "message.part.updated",
+          properties: {
+            sessionID: "http://127.0.0.1:9999/session",
+            part: {
+              ...part,
+              text: "A BBonus",
+              time: { start: 1, end: 2 },
+            },
+            time: 2,
+          },
+        },
+      ];
+      const eventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.take(5),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+
+      const events = Array.from(yield* Fiber.join(eventsFiber).pipe(Effect.timeout("1 second")));
+      const deltas = events.filter((event) => event.type === "content.delta");
+      assert.deepEqual(
+        deltas.map((event) => (event.type === "content.delta" ? event.payload.delta : "")),
+        ["A B", "Bonus"],
+      );
+      assert.equal(events.at(-1)?.type, "item.completed");
+      const completed = events.at(-1);
+      if (completed?.type === "item.completed") {
+        assert.equal(completed.payload.detail, "A BBonus");
+      }
+    }),
+  );
+
+  it.effect("writes provider-native observability records using the session thread id", () =>
+    Effect.gen(function* () {
+      const nativeEvents: Array<{
+        readonly event?: {
+          readonly provider?: string;
+          readonly threadId?: string;
+          readonly providerThreadId?: string;
+          readonly type?: string;
+        };
+      }> = [];
+      const nativeThreadIds: Array<string | null> = [];
+      runtimeMock.state.subscribedEvents = [
+        {
+          type: "message.updated",
+          properties: {
+            info: {
+              id: "msg-missing-session",
+              role: "assistant",
+            },
+          },
+        },
+        {
+          type: "message.updated",
+          properties: {
+            sessionID: "http://127.0.0.1:9999/other-session",
+            info: {
+              id: "msg-other-session",
+              role: "assistant",
+            },
+          },
+        },
+        {
+          type: "message.updated",
+          properties: {
+            sessionID: "http://127.0.0.1:9999/session",
+            info: {
+              id: "msg-native-log",
+              role: "assistant",
+            },
+          },
+        },
+      ];
+
+      const nativeEventLogger = {
+        filePath: "memory://opencode-native-events",
+        write: (event: unknown, threadId: ThreadId | null) => {
+          nativeEvents.push(event as (typeof nativeEvents)[number]);
+          nativeThreadIds.push(threadId ?? null);
+          return Effect.void;
+        },
+        close: () => Effect.void,
+      };
+
+      const adapterLayer = Layer.effect(
+        OpenCodeAdapter,
+        makeOpenCodeAdapter(openCodeAdapterTestSettings, {
+          nativeEventLogger,
+        }),
+      ).pipe(
+        Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
+        Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+        Layer.provideMerge(
+          ServerSettingsService.layerTest({
+            providers: {
+              opencode: {
+                binaryPath: "fake-opencode",
+                serverUrl: "http://127.0.0.1:9999",
+                serverPassword: "secret-password",
+              },
+            },
+          }),
+        ),
+        Layer.provideMerge(providerSessionDirectoryTestLayer),
+        Layer.provideMerge(NodeServices.layer),
+      );
+
+      const session = yield* Effect.gen(function* () {
+        const adapter = yield* OpenCodeAdapter;
+        const started = yield* adapter.startSession({
+          provider: ProviderDriverKind.make("opencode"),
+          threadId: asThreadId("thread-native-log"),
+          runtimeMode: "full-access",
+        });
+        yield* advanceTestClock(10);
+        return started;
+      }).pipe(Effect.provide(adapterLayer));
+
+      assert.equal(session.threadId, "thread-native-log");
+      assert.equal(nativeEvents.length, 1);
+      assert.equal(
+        nativeEvents.some((record) => record.event?.provider === "opencode"),
+        true,
+      );
+      assert.equal(
+        nativeEvents.some(
+          (record) => record.event?.providerThreadId === "http://127.0.0.1:9999/session",
+        ),
+        true,
+      );
+      assert.equal(
+        nativeEvents.some((record) => record.event?.threadId === "thread-native-log"),
+        true,
+      );
+      assert.equal(
+        nativeEvents.some((record) => record.event?.type === "message.updated"),
+        true,
+      );
+      assert.equal(
+        nativeThreadIds.every((threadId) => threadId === "thread-native-log"),
+        true,
+      );
+    }),
+  );
+
+  it.effect("keeps the event pump alive when native event logging fails", () =>
+    Effect.gen(function* () {
+      runtimeMock.state.subscribedEvents = [
+        {
+          type: "message.updated",
+          properties: {
+            sessionID: "http://127.0.0.1:9999/session",
+            info: {
+              id: "msg-native-log-failure",
+              role: "assistant",
+            },
+          },
+        },
+      ];
+
+      const nativeEventLogger = {
+        filePath: "memory://opencode-native-events",
+        write: () => Effect.die(new Error("native log write failed")),
+        close: () => Effect.void,
+      };
+
+      const adapterLayer = Layer.effect(
+        OpenCodeAdapter,
+        makeOpenCodeAdapter(openCodeAdapterTestSettings, {
+          nativeEventLogger,
+        }),
+      ).pipe(
+        Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
+        Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+        Layer.provideMerge(
+          ServerSettingsService.layerTest({
+            providers: {
+              opencode: {
+                binaryPath: "fake-opencode",
+                serverUrl: "http://127.0.0.1:9999",
+                serverPassword: "secret-password",
+              },
+            },
+          }),
+        ),
+        Layer.provideMerge(providerSessionDirectoryTestLayer),
+        Layer.provideMerge(NodeServices.layer),
+      );
+
+      // Capture closeCalls *inside* the provided layer scope: the adapter's
+      // layer finalizer now tears down any live sessions when the layer
+      // closes (which is exactly what we want for leak prevention), so
+      // inspecting closeCalls after `Effect.provide` completes would observe
+      // the teardown — not the behavior under test. We care that the event
+      // pump kept the session alive while logging was failing.
+      const { sessions, closeCallsDuringRun } = yield* Effect.gen(function* () {
+        const adapter = yield* OpenCodeAdapter;
+        yield* adapter.startSession({
+          provider: ProviderDriverKind.make("opencode"),
+          threadId: asThreadId("thread-native-log-failure"),
+          runtimeMode: "full-access",
+        });
+        yield* advanceTestClock(10);
+        return {
+          sessions: yield* adapter.listSessions(),
+          closeCallsDuringRun: [...runtimeMock.state.closeCalls],
+        };
+      }).pipe(Effect.provide(adapterLayer));
+
+      assert.equal(sessions.length, 1);
+      assert.equal(sessions[0]?.threadId, "thread-native-log-failure");
+      assert.deepEqual(closeCallsDuringRun, []);
+    }),
+  );
+});
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
new file mode 100644
index 00000000000..512e9ed6bfe
--- /dev/null
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
@@ -0,0 +1,1435 @@
+import {
+  EventId,
+  type OpenCodeSettings,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ProviderRuntimeEvent,
+  type ProviderSession,
+  RuntimeItemId,
+  RuntimeRequestId,
+  ThreadId,
+  type ToolLifecycleItemType,
+  TurnId,
+  type UserInputQuestion,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Queue from "effect/Queue";
+import * as Random from "effect/Random";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import type { OpencodeClient, Part, PermissionRequest, QuestionRequest } from "@opencode-ai/sdk/v2";
+import { getModelSelectionStringOptionValue } from "@t3tools/shared/model";
+
+import { resolveAttachmentPath } from "../../attachmentStore.ts";
+import { ServerConfig } from "../../config.ts";
+import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
+import {
+  ProviderAdapterProcessError,
+  ProviderAdapterRequestError,
+  ProviderAdapterSessionClosedError,
+  ProviderAdapterSessionNotFoundError,
+  ProviderAdapterValidationError,
+} from "../Errors.ts";
+import { type OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
+import {
+  buildOpenCodePermissionRules,
+  OpenCodeRuntime,
+  OpenCodeRuntimeError,
+  openCodeQuestionId,
+  openCodeRuntimeErrorDetail,
+  parseOpenCodeModelSlug,
+  runOpenCodeSdk,
+  toOpenCodeFileParts,
+  toOpenCodePermissionReply,
+  toOpenCodeQuestionAnswers,
+  type OpenCodeServerConnection,
+} from "../opencodeRuntime.ts";
+import * as Option from "effect/Option";
+
+const PROVIDER = ProviderDriverKind.make("opencode");
+
+interface OpenCodeTurnSnapshot {
+  readonly id: TurnId;
+  readonly items: Array<unknown>;
+}
+
+type OpenCodeSubscribedEvent =
+  Awaited<ReturnType<OpencodeClient["event"]["subscribe"]>> extends {
+    readonly stream: AsyncIterable<infer TEvent>;
+  }
+    ? TEvent
+    : never;
+
+interface OpenCodeSessionContext {
+  session: ProviderSession;
+  readonly client: OpencodeClient;
+  readonly server: OpenCodeServerConnection;
+  readonly directory: string;
+  readonly openCodeSessionId: string;
+  readonly pendingPermissions: Map<string, PermissionRequest>;
+  readonly pendingQuestions: Map<string, QuestionRequest>;
+  readonly messageRoleById: Map<string, "user" | "assistant">;
+  readonly partById: Map<string, Part>;
+  readonly emittedTextByPartId: Map<string, string>;
+  readonly completedAssistantPartIds: Set<string>;
+  readonly turns: Array<OpenCodeTurnSnapshot>;
+  activeTurnId: TurnId | undefined;
+  activeAgent: string | undefined;
+  activeVariant: string | undefined;
+  /**
+   * One-shot guard flipped by `stopOpenCodeContext` / `emitUnexpectedExit`.
+   * The session lifecycle is owned by `sessionScope`; this Ref exists only
+   * so concurrent callers can race the transition safely via `getAndSet`.
+   */
+  readonly stopped: Ref.Ref<boolean>;
+  /**
+   * Sole lifecycle handle for the session. Closing this scope:
+   *   - aborts the `AbortController` registered as a finalizer
+   *     (cancels the in-flight `event.subscribe` fetch),
+   *   - interrupts the event-pump and server-exit fibers forked
+   *     via `Effect.forkIn(sessionScope)`,
+   *   - tears down the OpenCode server process for scope-owned servers.
+   */
+  readonly sessionScope: Scope.Closeable;
+}
+
+export interface OpenCodeAdapterLiveOptions {
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly nativeEventLogPath?: string;
+  readonly nativeEventLogger?: EventNdjsonLogger;
+}
+
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
+/**
+ * Map a tagged OpenCodeRuntimeError produced by {@link runOpenCodeSdk} into
+ * the adapter-boundary `ProviderAdapterRequestError`. SDK-method-level call
+ * sites pipe through this in `Effect.mapError` so they never build the error
+ * shape by hand.
+ */
+const toRequestError = (cause: OpenCodeRuntimeError): ProviderAdapterRequestError =>
+  new ProviderAdapterRequestError({
+    provider: PROVIDER,
+    method: cause.operation,
+    detail: cause.detail,
+    cause: cause.cause,
+  });
+
+/**
+ * Map a `Cause.squash`-ed failure into a `ProviderAdapterProcessError`. The
+ * typed cause is usually an `OpenCodeRuntimeError` (from {@link runOpenCodeSdk}),
+ * in which case we preserve its `detail`; otherwise we fall back to
+ * {@link openCodeRuntimeErrorDetail} for unknown causes (defects, etc.).
+ */
+const toProcessError = (threadId: ThreadId, cause: unknown): ProviderAdapterProcessError =>
+  new ProviderAdapterProcessError({
+    provider: PROVIDER,
+    threadId,
+    detail: OpenCodeRuntimeError.is(cause) ? cause.detail : openCodeRuntimeErrorDetail(cause),
+    cause,
+  });
+
+const buildEventBase = (input: {
+  readonly threadId: ThreadId;
+  readonly turnId?: TurnId | undefined;
+  readonly itemId?: string | undefined;
+  readonly requestId?: string | undefined;
+  readonly createdAt?: string | undefined;
+  readonly raw?: unknown;
+}): Effect.Effect<
+  Pick<
+    ProviderRuntimeEvent,
+    "eventId" | "provider" | "threadId" | "createdAt" | "turnId" | "itemId" | "requestId" | "raw"
+  >
+> =>
+  Effect.gen(function* () {
+    const uuid = yield* Random.nextUUIDv4;
+    const createdAt = input.createdAt ?? (yield* nowIso);
+    return {
+      eventId: EventId.make(uuid),
+      provider: PROVIDER,
+      threadId: input.threadId,
+      createdAt,
+      ...(input.turnId ? { turnId: input.turnId } : {}),
+      ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
+      ...(input.requestId ? { requestId: RuntimeRequestId.make(input.requestId) } : {}),
+      ...(input.raw !== undefined
+        ? {
+            raw: {
+              source: "opencode.sdk.event",
+              payload: input.raw,
+            },
+          }
+        : {}),
+    };
+  });
+
+function toToolLifecycleItemType(toolName: string): ToolLifecycleItemType {
+  const normalized = toolName.toLowerCase();
+  if (normalized.includes("bash") || normalized.includes("command")) {
+    return "command_execution";
+  }
+  if (
+    normalized.includes("edit") ||
+    normalized.includes("write") ||
+    normalized.includes("patch") ||
+    normalized.includes("multiedit")
+  ) {
+    return "file_change";
+  }
+  if (normalized.includes("web")) {
+    return "web_search";
+  }
+  if (normalized.includes("mcp")) {
+    return "mcp_tool_call";
+  }
+  if (normalized.includes("image")) {
+    return "image_view";
+  }
+  if (
+    normalized.includes("task") ||
+    normalized.includes("agent") ||
+    normalized.includes("subtask")
+  ) {
+    return "collab_agent_tool_call";
+  }
+  return "dynamic_tool_call";
+}
+
+function mapPermissionToRequestType(
+  permission: string,
+): "command_execution_approval" | "file_read_approval" | "file_change_approval" | "unknown" {
+  switch (permission) {
+    case "bash":
+      return "command_execution_approval";
+    case "read":
+      return "file_read_approval";
+    case "edit":
+      return "file_change_approval";
+    default:
+      return "unknown";
+  }
+}
+
+function mapPermissionDecision(reply: "once" | "always" | "reject"): string {
+  switch (reply) {
+    case "once":
+      return "accept";
+    case "always":
+      return "acceptForSession";
+    case "reject":
+    default:
+      return "decline";
+  }
+}
+
+function resolveTurnSnapshot(
+  context: OpenCodeSessionContext,
+  turnId: TurnId,
+): OpenCodeTurnSnapshot {
+  const existing = context.turns.find((turn) => turn.id === turnId);
+  if (existing) {
+    return existing;
+  }
+
+  const created: OpenCodeTurnSnapshot = { id: turnId, items: [] };
+  context.turns.push(created);
+  return created;
+}
+
+function appendTurnItem(
+  context: OpenCodeSessionContext,
+  turnId: TurnId | undefined,
+  item: unknown,
+): void {
+  if (!turnId) {
+    return;
+  }
+  resolveTurnSnapshot(context, turnId).items.push(item);
+}
+
+function ensureSessionContext(
+  sessions: ReadonlyMap<ThreadId, OpenCodeSessionContext>,
+  threadId: ThreadId,
+): OpenCodeSessionContext {
+  const session = sessions.get(threadId);
+  if (!session) {
+    throw new ProviderAdapterSessionNotFoundError({
+      provider: PROVIDER,
+      threadId,
+    });
+  }
+  // `ensureSessionContext` is a sync gate used from both sync helpers and
+  // Effect bodies. `Ref.getUnsafe` is an atomic read of the backing cell —
+  // no fiber suspension required, which keeps this callable everywhere.
+  if (Ref.getUnsafe(session.stopped)) {
+    throw new ProviderAdapterSessionClosedError({
+      provider: PROVIDER,
+      threadId,
+    });
+  }
+  return session;
+}
+
+function normalizeQuestionRequest(request: QuestionRequest): ReadonlyArray<UserInputQuestion> {
+  return request.questions.map((question, index) => ({
+    id: openCodeQuestionId(index, question),
+    header: question.header,
+    question: question.question,
+    options: question.options.map((option) => ({
+      label: option.label,
+      description: option.description,
+    })),
+    ...(question.multiple ? { multiSelect: true } : {}),
+  }));
+}
+
+function resolveTextStreamKind(part: Part | undefined): "assistant_text" | "reasoning_text" {
+  return part?.type === "reasoning" ? "reasoning_text" : "assistant_text";
+}
+
+function textFromPart(part: Part): string | undefined {
+  switch (part.type) {
+    case "text":
+    case "reasoning":
+      return part.text;
+    default:
+      return undefined;
+  }
+}
+
+function commonPrefixLength(left: string, right: string): number {
+  let index = 0;
+  while (index < left.length && index < right.length && left[index] === right[index]) {
+    index += 1;
+  }
+  return index;
+}
+
+function resolveLatestAssistantText(previousText: string | undefined, nextText: string): string {
+  if (previousText && previousText.length > nextText.length && previousText.startsWith(nextText)) {
+    return previousText;
+  }
+  return nextText;
+}
+
+export function mergeOpenCodeAssistantText(
+  previousText: string | undefined,
+  nextText: string,
+): {
+  readonly latestText: string;
+  readonly deltaToEmit: string;
+} {
+  const latestText = resolveLatestAssistantText(previousText, nextText);
+  return {
+    latestText,
+    deltaToEmit: latestText.slice(commonPrefixLength(previousText ?? "", latestText)),
+  };
+}
+
+export function appendOpenCodeAssistantTextDelta(
+  previousText: string,
+  delta: string,
+): {
+  readonly nextText: string;
+  readonly deltaToEmit: string;
+} {
+  return {
+    nextText: previousText + delta,
+    deltaToEmit: delta,
+  };
+}
+
+const isoFromEpochMs = (value: number) =>
+  DateTime.make(value).pipe(
+    Option.match({
+      onNone: () => undefined,
+      onSome: DateTime.formatIso,
+    }),
+  );
+
+function messageRoleForPart(
+  context: OpenCodeSessionContext,
+  part: Pick<Part, "messageID" | "type">,
+): "assistant" | "user" | undefined {
+  const known = context.messageRoleById.get(part.messageID);
+  if (known) {
+    return known;
+  }
+  return part.type === "tool" ? "assistant" : undefined;
+}
+
+function detailFromToolPart(part: Extract<Part, { type: "tool" }>): string | undefined {
+  switch (part.state.status) {
+    case "completed":
+      return part.state.output;
+    case "error":
+      return part.state.error;
+    case "running":
+      return part.state.title;
+    default:
+      return undefined;
+  }
+}
+
+function toolStateCreatedAt(part: Extract<Part, { type: "tool" }>): string | undefined {
+  switch (part.state.status) {
+    case "running":
+      return isoFromEpochMs(part.state.time.start);
+    case "completed":
+    case "error":
+      return isoFromEpochMs(part.state.time.end);
+    default:
+      return undefined;
+  }
+}
+
+function sessionErrorMessage(error: unknown): string {
+  if (!error || typeof error !== "object") {
+    return "OpenCode session failed.";
+  }
+  const data = "data" in error && error.data && typeof error.data === "object" ? error.data : null;
+  const message = data && "message" in data ? data.message : null;
+  return typeof message === "string" && message.trim().length > 0
+    ? message
+    : "OpenCode session failed.";
+}
+
+function updateProviderSession(
+  context: OpenCodeSessionContext,
+  patch: Partial<ProviderSession>,
+  options?: {
+    readonly clearActiveTurnId?: boolean;
+    readonly clearLastError?: boolean;
+  },
+): Effect.Effect<ProviderSession> {
+  return Effect.gen(function* () {
+    const updatedAt = yield* nowIso;
+    const nextSession = {
+      ...context.session,
+      ...patch,
+      updatedAt,
+    } as ProviderSession & Record<string, unknown>;
+    const mutableSession = nextSession as Record<string, unknown>;
+    if (options?.clearActiveTurnId) {
+      delete mutableSession.activeTurnId;
+    }
+    if (options?.clearLastError) {
+      delete mutableSession.lastError;
+    }
+    context.session = nextSession;
+    return nextSession;
+  });
+}
+
+const stopOpenCodeContext = Effect.fn("stopOpenCodeContext")(function* (
+  context: OpenCodeSessionContext,
+) {
+  // Race-safe one-shot: first caller flips the flag, everyone else no-ops.
+  if (yield* Ref.getAndSet(context.stopped, true)) {
+    return false;
+  }
+
+  // Best-effort remote abort. The scope close below tears down the local
+  // handles (event-pump fiber, server-exit fiber, event-subscribe fetch),
+  // but we still want to tell OpenCode that this session is done.
+  yield* runOpenCodeSdk("session.abort", () =>
+    context.client.session.abort({ sessionID: context.openCodeSessionId }),
+  ).pipe(Effect.ignore({ log: true }));
+
+  // Closing the session scope interrupts every fiber forked into it and
+  // runs each finalizer we registered — the `AbortController.abort()` call,
+  // the child-process termination, etc.
+  yield* Scope.close(context.sessionScope, Exit.void);
+  return true;
+});
+
+export function makeOpenCodeAdapter(
+  openCodeSettings: OpenCodeSettings,
+  options?: OpenCodeAdapterLiveOptions,
+) {
+  return Effect.gen(function* () {
+    const boundInstanceId = options?.instanceId ?? ProviderInstanceId.make("opencode");
+    const serverConfig = yield* ServerConfig;
+    const openCodeRuntime = yield* OpenCodeRuntime;
+    const nativeEventLogger =
+      options?.nativeEventLogger ??
+      (options?.nativeEventLogPath !== undefined
+        ? yield* makeEventNdjsonLogger(options.nativeEventLogPath, {
+            stream: "native",
+          })
+        : undefined);
+    // Only close loggers we created. If the caller passed one in via
+    // `options.nativeEventLogger`, they own its lifecycle.
+    const managedNativeEventLogger =
+      options?.nativeEventLogger === undefined ? nativeEventLogger : undefined;
+    const runtimeEvents = yield* Queue.unbounded<ProviderRuntimeEvent>();
+    const sessions = new Map<ThreadId, OpenCodeSessionContext>();
+
+    // Layer-level finalizer: when the adapter layer shuts down, stop every
+    // session. Each session's `Scope.close` tears down its spawned OpenCode
+    // server (via the `ChildProcessSpawner` finalizer installed in
+    // `startOpenCodeServerProcess`) and interrupts the forked event/exit
+    // fibers. Consumers that can't reason about Effect scopes therefore
+    // cannot leak OpenCode child processes by forgetting to call `stopAll`.
+    yield* Effect.addFinalizer(() =>
+      Effect.gen(function* () {
+        const contexts = [...sessions.values()];
+        sessions.clear();
+        // `ignoreCause` swallows both typed failures (none here) and defects
+        // from throwing scope finalizers so a sibling's death can't interrupt
+        // the remaining cleanups.
+        yield* Effect.forEach(
+          contexts,
+          (context) => Effect.ignoreCause(stopOpenCodeContext(context)),
+          { concurrency: "unbounded", discard: true },
+        );
+        // Close the logger AFTER session teardown so any final lifecycle
+        // events emitted during shutdown still get written. `close` flushes
+        // the `Logger.batched` window and closes each per-thread
+        // `RotatingFileSink` handle owned by the logger's internal scope.
+        if (managedNativeEventLogger !== undefined) {
+          yield* managedNativeEventLogger.close();
+        }
+      }).pipe(Effect.ensuring(Queue.shutdown(runtimeEvents))),
+    );
+
+    const emit = (event: ProviderRuntimeEvent) =>
+      Queue.offer(runtimeEvents, event).pipe(Effect.asVoid);
+    const writeNativeEvent = (
+      threadId: ThreadId,
+      event: {
+        readonly observedAt: string;
+        readonly event: Record<string, unknown>;
+      },
+    ) => (nativeEventLogger ? nativeEventLogger.write(event, threadId) : Effect.void);
+    const writeNativeEventBestEffort = (
+      threadId: ThreadId,
+      event: {
+        readonly observedAt: string;
+        readonly event: Record<string, unknown>;
+      },
+    ) => writeNativeEvent(threadId, event).pipe(Effect.catchCause(() => Effect.void));
+
+    const emitUnexpectedExit = Effect.fn("emitUnexpectedExit")(function* (
+      context: OpenCodeSessionContext,
+      message: string,
+    ) {
+      // Atomic one-shot: two fibers can race here (the event-pump on stream
+      // failure and the server-exit watcher). `getAndSet` flips the flag in
+      // a single step so the loser observes `true` and returns; a plain
+      // `Ref.get` would let both racers slip past and emit duplicates.
+      if (yield* Ref.getAndSet(context.stopped, true)) {
+        return;
+      }
+      const turnId = context.activeTurnId;
+      sessions.delete(context.session.threadId);
+      // Emit lifecycle events BEFORE tearing down the scope. Both call sites
+      // run this inside a fiber forked via `Effect.forkIn(context.sessionScope)`;
+      // closing that scope triggers the fiber-interrupt finalizer, so any
+      // subsequent yield point would unwind and silently drop these emits.
+      yield* emit({
+        ...(yield* buildEventBase({
+          threadId: context.session.threadId,
+          turnId,
+        })),
+        type: "runtime.error",
+        payload: {
+          message,
+          class: "transport_error",
+        },
+      }).pipe(Effect.ignore);
+      yield* emit({
+        ...(yield* buildEventBase({
+          threadId: context.session.threadId,
+          turnId,
+        })),
+        type: "session.exited",
+        payload: {
+          reason: message,
+          recoverable: false,
+          exitKind: "error",
+        },
+      }).pipe(Effect.ignore);
+      // Inline the teardown that `stopOpenCodeContext` would do; we can't
+      // delegate to it because our `getAndSet` above already flipped the
+      // one-shot guard, so the call would no-op.
+      yield* runOpenCodeSdk("session.abort", () =>
+        context.client.session.abort({ sessionID: context.openCodeSessionId }),
+      ).pipe(Effect.ignore({ log: true }));
+      yield* Scope.close(context.sessionScope, Exit.void);
+    });
+
+    /** Emit content.delta and item.completed events for an assistant text part. */
+    const emitAssistantTextDelta = Effect.fn("emitAssistantTextDelta")(function* (
+      context: OpenCodeSessionContext,
+      part: Part,
+      turnId: TurnId | undefined,
+      raw: unknown,
+    ) {
+      const text = textFromPart(part);
+      if (text === undefined) {
+        return;
+      }
+      const previousText = context.emittedTextByPartId.get(part.id);
+      const { latestText, deltaToEmit } = mergeOpenCodeAssistantText(previousText, text);
+      context.emittedTextByPartId.set(part.id, latestText);
+      if (latestText !== text) {
+        context.partById.set(
+          part.id,
+          (part.type === "text" || part.type === "reasoning"
+            ? { ...part, text: latestText }
+            : part) satisfies Part,
+        );
+      }
+      if (deltaToEmit.length > 0) {
+        yield* emit({
+          ...(yield* buildEventBase({
+            threadId: context.session.threadId,
+            turnId,
+            itemId: part.id,
+            createdAt:
+              (part.type === "text" || part.type === "reasoning") && part.time !== undefined
+                ? isoFromEpochMs(part.time.start)
+                : undefined,
+            raw,
+          })),
+          type: "content.delta",
+          payload: {
+            streamKind: resolveTextStreamKind(part),
+            delta: deltaToEmit,
+          },
+        });
+      }
+
+      if (
+        part.type === "text" &&
+        part.time?.end !== undefined &&
+        !context.completedAssistantPartIds.has(part.id)
+      ) {
+        context.completedAssistantPartIds.add(part.id);
+        yield* emit({
+          ...(yield* buildEventBase({
+            threadId: context.session.threadId,
+            turnId,
+            itemId: part.id,
+            createdAt: isoFromEpochMs(part.time.end),
+            raw,
+          })),
+          type: "item.completed",
+          payload: {
+            itemType: "assistant_message",
+            status: "completed",
+            title: "Assistant message",
+            ...(latestText.length > 0 ? { detail: latestText } : {}),
+          },
+        });
+      }
+    });
+
+    const handleSubscribedEvent = Effect.fn("handleSubscribedEvent")(function* (
+      context: OpenCodeSessionContext,
+      event: OpenCodeSubscribedEvent,
+    ) {
+      const payloadSessionId =
+        "properties" in event ? (event.properties as { sessionID?: unknown }).sessionID : undefined;
+      if (payloadSessionId !== context.openCodeSessionId) {
+        return;
+      }
+
+      const turnId = context.activeTurnId;
+      yield* writeNativeEventBestEffort(context.session.threadId, {
+        observedAt: yield* nowIso,
+        event: {
+          provider: PROVIDER,
+          threadId: context.session.threadId,
+          providerThreadId: context.openCodeSessionId,
+          type: event.type,
+          ...(turnId ? { turnId } : {}),
+          payload: event,
+        },
+      });
+
+      switch (event.type) {
+        case "message.updated": {
+          context.messageRoleById.set(event.properties.info.id, event.properties.info.role);
+          if (event.properties.info.role === "assistant") {
+            for (const part of context.partById.values()) {
+              if (part.messageID !== event.properties.info.id) {
+                continue;
+              }
+              yield* emitAssistantTextDelta(context, part, turnId, event);
+            }
+          }
+          break;
+        }
+
+        case "message.removed": {
+          context.messageRoleById.delete(event.properties.messageID);
+          break;
+        }
+
+        case "message.part.delta": {
+          const existingPart = context.partById.get(event.properties.partID);
+          if (!existingPart) {
+            break;
+          }
+          const role = messageRoleForPart(context, existingPart);
+          if (role !== "assistant") {
+            break;
+          }
+          const streamKind = resolveTextStreamKind(existingPart);
+          const delta = event.properties.delta;
+          if (delta.length === 0) {
+            break;
+          }
+          const previousText =
+            context.emittedTextByPartId.get(event.properties.partID) ??
+            textFromPart(existingPart) ??
+            "";
+          const { nextText, deltaToEmit } = appendOpenCodeAssistantTextDelta(previousText, delta);
+          if (deltaToEmit.length === 0) {
+            break;
+          }
+          context.emittedTextByPartId.set(event.properties.partID, nextText);
+          if (existingPart.type === "text" || existingPart.type === "reasoning") {
+            context.partById.set(event.properties.partID, {
+              ...existingPart,
+              text: nextText,
+            });
+          }
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              turnId,
+              itemId: event.properties.partID,
+              raw: event,
+            })),
+            type: "content.delta",
+            payload: {
+              streamKind,
+              delta: deltaToEmit,
+            },
+          });
+          break;
+        }
+
+        case "message.part.updated": {
+          const part = event.properties.part;
+          context.partById.set(part.id, part);
+          const messageRole = messageRoleForPart(context, part);
+
+          if (messageRole === "assistant") {
+            yield* emitAssistantTextDelta(context, part, turnId, event);
+          }
+
+          if (part.type === "tool") {
+            const itemType = toToolLifecycleItemType(part.tool);
+            const title =
+              part.state.status === "running" ? (part.state.title ?? part.tool) : part.tool;
+            const detail = detailFromToolPart(part);
+            const payload = {
+              itemType,
+              ...(part.state.status === "error"
+                ? { status: "failed" as const }
+                : part.state.status === "completed"
+                  ? { status: "completed" as const }
+                  : { status: "inProgress" as const }),
+              ...(title ? { title } : {}),
+              ...(detail ? { detail } : {}),
+              data: {
+                tool: part.tool,
+                state: part.state,
+              },
+            };
+            const runtimeEvent: ProviderRuntimeEvent = {
+              ...(yield* buildEventBase({
+                threadId: context.session.threadId,
+                turnId,
+                itemId: part.callID,
+                createdAt: toolStateCreatedAt(part),
+                raw: event,
+              })),
+              type:
+                part.state.status === "pending"
+                  ? "item.started"
+                  : part.state.status === "completed" || part.state.status === "error"
+                    ? "item.completed"
+                    : "item.updated",
+              payload,
+            };
+            appendTurnItem(context, turnId, part);
+            yield* emit(runtimeEvent);
+          }
+          break;
+        }
+
+        case "permission.asked": {
+          context.pendingPermissions.set(event.properties.id, event.properties);
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              turnId,
+              requestId: event.properties.id,
+              raw: event,
+            })),
+            type: "request.opened",
+            payload: {
+              requestType: mapPermissionToRequestType(event.properties.permission),
+              detail:
+                event.properties.patterns.length > 0
+                  ? event.properties.patterns.join("\n")
+                  : event.properties.permission,
+              args: event.properties.metadata,
+            },
+          });
+          break;
+        }
+
+        case "permission.replied": {
+          context.pendingPermissions.delete(event.properties.requestID);
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              turnId,
+              requestId: event.properties.requestID,
+              raw: event,
+            })),
+            type: "request.resolved",
+            payload: {
+              requestType: "unknown",
+              decision: mapPermissionDecision(event.properties.reply),
+            },
+          });
+          break;
+        }
+
+        case "question.asked": {
+          context.pendingQuestions.set(event.properties.id, event.properties);
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              turnId,
+              requestId: event.properties.id,
+              raw: event,
+            })),
+            type: "user-input.requested",
+            payload: {
+              questions: normalizeQuestionRequest(event.properties),
+            },
+          });
+          break;
+        }
+
+        case "question.replied": {
+          const request = context.pendingQuestions.get(event.properties.requestID);
+          context.pendingQuestions.delete(event.properties.requestID);
+          const answers = Object.fromEntries(
+            (request?.questions ?? []).map((question, index) => [
+              openCodeQuestionId(index, question),
+              event.properties.answers[index]?.join(", ") ?? "",
+            ]),
+          );
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              turnId,
+              requestId: event.properties.requestID,
+              raw: event,
+            })),
+            type: "user-input.resolved",
+            payload: { answers },
+          });
+          break;
+        }
+
+        case "question.rejected": {
+          context.pendingQuestions.delete(event.properties.requestID);
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              turnId,
+              requestId: event.properties.requestID,
+              raw: event,
+            })),
+            type: "user-input.resolved",
+            payload: { answers: {} },
+          });
+          break;
+        }
+
+        case "session.status": {
+          if (event.properties.status.type === "busy") {
+            yield* updateProviderSession(context, {
+              status: "running",
+              activeTurnId: turnId,
+            });
+          }
+
+          if (event.properties.status.type === "retry") {
+            yield* emit({
+              ...(yield* buildEventBase({
+                threadId: context.session.threadId,
+                turnId,
+                raw: event,
+              })),
+              type: "runtime.warning",
+              payload: {
+                message: event.properties.status.message,
+                detail: event.properties.status,
+              },
+            });
+            break;
+          }
+
+          if (event.properties.status.type === "idle" && turnId) {
+            context.activeTurnId = undefined;
+            yield* updateProviderSession(context, { status: "ready" }, { clearActiveTurnId: true });
+            yield* emit({
+              ...(yield* buildEventBase({
+                threadId: context.session.threadId,
+                turnId,
+                raw: event,
+              })),
+              type: "turn.completed",
+              payload: {
+                state: "completed",
+              },
+            });
+          }
+          break;
+        }
+
+        case "session.error": {
+          const message = sessionErrorMessage(event.properties.error);
+          const activeTurnId = context.activeTurnId;
+          context.activeTurnId = undefined;
+          yield* updateProviderSession(
+            context,
+            {
+              status: "error",
+              lastError: message,
+            },
+            { clearActiveTurnId: true },
+          );
+          if (activeTurnId) {
+            yield* emit({
+              ...(yield* buildEventBase({
+                threadId: context.session.threadId,
+                turnId: activeTurnId,
+                raw: event,
+              })),
+              type: "turn.completed",
+              payload: {
+                state: "failed",
+                errorMessage: message,
+              },
+            });
+          }
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              raw: event,
+            })),
+            type: "runtime.error",
+            payload: {
+              message,
+              class: "provider_error",
+              detail: event.properties.error,
+            },
+          });
+          break;
+        }
+
+        default:
+          break;
+      }
+    });
+
+    const startEventPump = Effect.fn("startEventPump")(function* (context: OpenCodeSessionContext) {
+      // One AbortController per session scope. The finalizer fires when
+      // the scope closes (explicit stop, unexpected exit, or layer
+      // shutdown) and cancels the in-flight `event.subscribe` fetch so
+      // the async iterable unwinds cleanly.
+      const eventsAbortController = new AbortController();
+      yield* Scope.addFinalizer(
+        context.sessionScope,
+        Effect.sync(() => eventsAbortController.abort()),
+      );
+
+      // Fibers forked into `context.sessionScope` are interrupted
+      // automatically when the scope closes — no bookkeeping required.
+      yield* Effect.flatMap(
+        runOpenCodeSdk("event.subscribe", () =>
+          context.client.event.subscribe(undefined, {
+            signal: eventsAbortController.signal,
+          }),
+        ),
+        (subscription) =>
+          Stream.fromAsyncIterable(
+            subscription.stream,
+            (cause) =>
+              new OpenCodeRuntimeError({
+                operation: "event.subscribe",
+                detail: openCodeRuntimeErrorDetail(cause),
+                cause,
+              }),
+          ).pipe(Stream.runForEach((event) => handleSubscribedEvent(context, event))),
+      ).pipe(
+        Effect.exit,
+        Effect.flatMap((exit) =>
+          Effect.gen(function* () {
+            // Expected paths: caller aborted the fetch or the session
+            // has already been marked stopped. Treat as a clean exit.
+            if (eventsAbortController.signal.aborted || (yield* Ref.get(context.stopped))) {
+              return;
+            }
+            if (Exit.isFailure(exit)) {
+              yield* emitUnexpectedExit(
+                context,
+                openCodeRuntimeErrorDetail(Cause.squash(exit.cause)),
+              );
+            }
+          }),
+        ),
+        Effect.forkIn(context.sessionScope),
+      );
+
+      if (!context.server.external && context.server.exitCode !== null) {
+        yield* context.server.exitCode.pipe(
+          Effect.flatMap((code) =>
+            Effect.gen(function* () {
+              if (yield* Ref.get(context.stopped)) {
+                return;
+              }
+              yield* emitUnexpectedExit(context, `OpenCode server exited unexpectedly (${code}).`);
+            }),
+          ),
+          Effect.forkIn(context.sessionScope),
+        );
+      }
+    });
+
+    const startSession: OpenCodeAdapterShape["startSession"] = Effect.fn("startSession")(
+      function* (input) {
+        const binaryPath = openCodeSettings.binaryPath;
+        const serverUrl = openCodeSettings.serverUrl;
+        const serverPassword = openCodeSettings.serverPassword;
+        const directory = input.cwd ?? serverConfig.cwd;
+        const existing = sessions.get(input.threadId);
+        if (existing) {
+          yield* stopOpenCodeContext(existing);
+          sessions.delete(input.threadId);
+        }
+
+        const started = yield* Effect.gen(function* () {
+          const sessionScope = yield* Scope.make();
+          const startedExit = yield* Effect.exit(
+            Effect.gen(function* () {
+              // The runtime binds the server's lifetime to the Scope.Scope
+              // we provide below — closing `sessionScope` kills the child
+              // process automatically. No manual `server.close()` needed.
+              const server = yield* openCodeRuntime.connectToOpenCodeServer({
+                binaryPath,
+                serverUrl,
+                ...(options?.environment ? { environment: options.environment } : {}),
+              });
+              const client = openCodeRuntime.createOpenCodeSdkClient({
+                baseUrl: server.url,
+                directory,
+                ...(server.external && serverPassword ? { serverPassword } : {}),
+              });
+              const openCodeSession = yield* runOpenCodeSdk("session.create", () =>
+                client.session.create({
+                  title: `T3 Code ${input.threadId}`,
+                  permission: buildOpenCodePermissionRules(input.runtimeMode),
+                }),
+              );
+              if (!openCodeSession.data) {
+                return yield* new OpenCodeRuntimeError({
+                  operation: "session.create",
+                  detail: "OpenCode session.create returned no session payload.",
+                });
+              }
+              return {
+                sessionScope,
+                server,
+                client,
+                openCodeSession: openCodeSession.data,
+              };
+            }).pipe(Effect.provideService(Scope.Scope, sessionScope)),
+          );
+          if (Exit.isFailure(startedExit)) {
+            yield* Scope.close(sessionScope, Exit.void).pipe(Effect.ignore);
+            return yield* toProcessError(input.threadId, Cause.squash(startedExit.cause));
+          }
+          return startedExit.value;
+        });
+
+        // Guard against a concurrent startSession call that may have raced
+        // and already inserted a session while we were awaiting async work.
+        const raceWinner = sessions.get(input.threadId);
+        if (raceWinner) {
+          // Another call won the race – clean up the session we just created
+          // (including the remote SDK session) and return the existing one.
+          yield* runOpenCodeSdk("session.abort", () =>
+            started.client.session.abort({
+              sessionID: started.openCodeSession.id,
+            }),
+          ).pipe(Effect.ignore);
+          yield* Scope.close(started.sessionScope, Exit.void).pipe(Effect.ignore);
+          return raceWinner.session;
+        }
+
+        const createdAt = yield* nowIso;
+        const session: ProviderSession = {
+          provider: PROVIDER,
+          providerInstanceId: boundInstanceId,
+          status: "ready",
+          runtimeMode: input.runtimeMode,
+          cwd: directory,
+          ...(input.modelSelection ? { model: input.modelSelection.model } : {}),
+          threadId: input.threadId,
+          createdAt,
+          updatedAt: createdAt,
+        };
+
+        const context: OpenCodeSessionContext = {
+          session,
+          client: started.client,
+          server: started.server,
+          directory,
+          openCodeSessionId: started.openCodeSession.id,
+          pendingPermissions: new Map(),
+          pendingQuestions: new Map(),
+          partById: new Map(),
+          emittedTextByPartId: new Map(),
+          messageRoleById: new Map(),
+          completedAssistantPartIds: new Set(),
+          turns: [],
+          activeTurnId: undefined,
+          activeAgent: undefined,
+          activeVariant: undefined,
+          stopped: yield* Ref.make(false),
+          sessionScope: started.sessionScope,
+        };
+        sessions.set(input.threadId, context);
+        yield* startEventPump(context);
+
+        yield* emit({
+          ...(yield* buildEventBase({ threadId: input.threadId })),
+          type: "session.started",
+          payload: {
+            message: "OpenCode session started",
+          },
+        });
+        yield* emit({
+          ...(yield* buildEventBase({ threadId: input.threadId })),
+          type: "thread.started",
+          payload: {
+            providerThreadId: started.openCodeSession.id,
+          },
+        });
+
+        return session;
+      },
+    );
+
+    const sendTurn: OpenCodeAdapterShape["sendTurn"] = Effect.fn("sendTurn")(function* (input) {
+      const context = ensureSessionContext(sessions, input.threadId);
+      const turnId = TurnId.make(`opencode-turn-${yield* Random.nextUUIDv4}`);
+      const modelSelection =
+        input.modelSelection ??
+        (context.session.model
+          ? { instanceId: boundInstanceId, model: context.session.model }
+          : undefined);
+      if (modelSelection !== undefined && modelSelection.instanceId !== boundInstanceId) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "sendTurn",
+          issue: `OpenCode model selection is bound to instance '${modelSelection?.instanceId}', expected '${boundInstanceId}'.`,
+        });
+      }
+      const parsedModel = parseOpenCodeModelSlug(modelSelection?.model);
+      if (!parsedModel) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "sendTurn",
+          issue: "OpenCode model selection must use the 'provider/model' format.",
+        });
+      }
+
+      const text = input.input?.trim();
+      const fileParts = toOpenCodeFileParts({
+        attachments: input.attachments,
+        resolveAttachmentPath: (attachment) =>
+          resolveAttachmentPath({
+            attachmentsDir: serverConfig.attachmentsDir,
+            attachment,
+          }),
+      });
+      if ((!text || text.length === 0) && fileParts.length === 0) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "sendTurn",
+          issue: "OpenCode turns require text input or at least one attachment.",
+        });
+      }
+
+      const agent = getModelSelectionStringOptionValue(modelSelection, "agent");
+      const variant = getModelSelectionStringOptionValue(modelSelection, "variant");
+
+      context.activeTurnId = turnId;
+      context.activeAgent = agent ?? (input.interactionMode === "plan" ? "plan" : undefined);
+      context.activeVariant = variant;
+      yield* updateProviderSession(
+        context,
+        {
+          status: "running",
+          activeTurnId: turnId,
+          model: modelSelection?.model ?? context.session.model,
+        },
+        { clearLastError: true },
+      );
+
+      yield* emit({
+        ...(yield* buildEventBase({ threadId: input.threadId, turnId })),
+        type: "turn.started",
+        payload: {
+          model: modelSelection?.model ?? context.session.model,
+          ...(variant ? { effort: variant } : {}),
+        },
+      });
+
+      yield* runOpenCodeSdk("session.promptAsync", () =>
+        context.client.session.promptAsync({
+          sessionID: context.openCodeSessionId,
+          model: parsedModel,
+          ...(context.activeAgent ? { agent: context.activeAgent } : {}),
+          ...(context.activeVariant ? { variant: context.activeVariant } : {}),
+          parts: [...(text ? [{ type: "text" as const, text }] : []), ...fileParts],
+        }),
+      ).pipe(
+        Effect.mapError(toRequestError),
+        // On failure: clear active-turn state, flip the session back to ready
+        // with lastError set, emit turn.aborted, then let the typed error
+        // propagate. We don't need to rebuild the error here — `toRequestError`
+        // already produced the right shape.
+        Effect.tapError((requestError) =>
+          Effect.gen(function* () {
+            context.activeTurnId = undefined;
+            context.activeAgent = undefined;
+            context.activeVariant = undefined;
+            yield* updateProviderSession(
+              context,
+              {
+                status: "ready",
+                model: modelSelection?.model ?? context.session.model,
+                lastError: requestError.detail,
+              },
+              { clearActiveTurnId: true },
+            );
+            yield* emit({
+              ...(yield* buildEventBase({
+                threadId: input.threadId,
+                turnId,
+              })),
+              type: "turn.aborted",
+              payload: {
+                reason: requestError.detail,
+              },
+            });
+          }),
+        ),
+      );
+
+      return {
+        threadId: input.threadId,
+        turnId,
+      };
+    });
+
+    const interruptTurn: OpenCodeAdapterShape["interruptTurn"] = Effect.fn("interruptTurn")(
+      function* (threadId, turnId) {
+        const context = ensureSessionContext(sessions, threadId);
+        yield* runOpenCodeSdk("session.abort", () =>
+          context.client.session.abort({ sessionID: context.openCodeSessionId }),
+        ).pipe(Effect.mapError(toRequestError));
+        if (turnId ?? context.activeTurnId) {
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId,
+              turnId: turnId ?? context.activeTurnId,
+            })),
+            type: "turn.aborted",
+            payload: {
+              reason: "Interrupted by user.",
+            },
+          });
+        }
+      },
+    );
+
+    const respondToRequest: OpenCodeAdapterShape["respondToRequest"] = Effect.fn(
+      "respondToRequest",
+    )(function* (threadId, requestId, decision) {
+      const context = ensureSessionContext(sessions, threadId);
+      if (!context.pendingPermissions.has(requestId)) {
+        return yield* new ProviderAdapterRequestError({
+          provider: PROVIDER,
+          method: "permission.reply",
+          detail: `Unknown pending permission request: ${requestId}`,
+        });
+      }
+
+      yield* runOpenCodeSdk("permission.reply", () =>
+        context.client.permission.reply({
+          requestID: requestId,
+          reply: toOpenCodePermissionReply(decision),
+        }),
+      ).pipe(Effect.mapError(toRequestError));
+    });
+
+    const respondToUserInput: OpenCodeAdapterShape["respondToUserInput"] = Effect.fn(
+      "respondToUserInput",
+    )(function* (threadId, requestId, answers) {
+      const context = ensureSessionContext(sessions, threadId);
+      const request = context.pendingQuestions.get(requestId);
+      if (!request) {
+        return yield* new ProviderAdapterRequestError({
+          provider: PROVIDER,
+          method: "question.reply",
+          detail: `Unknown pending user-input request: ${requestId}`,
+        });
+      }
+
+      yield* runOpenCodeSdk("question.reply", () =>
+        context.client.question.reply({
+          requestID: requestId,
+          answers: toOpenCodeQuestionAnswers(request, answers),
+        }),
+      ).pipe(Effect.mapError(toRequestError));
+    });
+
+    const stopSession: OpenCodeAdapterShape["stopSession"] = Effect.fn("stopSession")(
+      function* (threadId) {
+        const context = sessions.get(threadId);
+        if (!context) {
+          throw new ProviderAdapterSessionNotFoundError({
+            provider: PROVIDER,
+            threadId,
+          });
+        }
+        const stopped = yield* stopOpenCodeContext(context);
+        sessions.delete(threadId);
+        if (!stopped) {
+          return;
+        }
+        yield* emit({
+          ...(yield* buildEventBase({ threadId })),
+          type: "session.exited",
+          payload: {
+            reason: "Session stopped.",
+            recoverable: false,
+            exitKind: "graceful",
+          },
+        });
+      },
+    );
+
+    const listSessions: OpenCodeAdapterShape["listSessions"] = () =>
+      Effect.sync(() => [...sessions.values()].map((context) => context.session));
+
+    const hasSession: OpenCodeAdapterShape["hasSession"] = (threadId) =>
+      Effect.sync(() => sessions.has(threadId));
+
+    const readThread: OpenCodeAdapterShape["readThread"] = Effect.fn("readThread")(
+      function* (threadId) {
+        const context = ensureSessionContext(sessions, threadId);
+        const messages = yield* runOpenCodeSdk("session.messages", () =>
+          context.client.session.messages({
+            sessionID: context.openCodeSessionId,
+          }),
+        ).pipe(Effect.mapError(toRequestError));
+
+        const turns = (messages.data ?? [])
+          .filter((entry) => entry.info.role === "assistant")
+          .map((entry) => ({
+            id: TurnId.make(entry.info.id),
+            items: [entry.info, ...entry.parts],
+          }));
+
+        return {
+          threadId,
+          turns,
+        };
+      },
+    );
+
+    const rollbackThread: OpenCodeAdapterShape["rollbackThread"] = Effect.fn("rollbackThread")(
+      function* (threadId, numTurns) {
+        const context = ensureSessionContext(sessions, threadId);
+        const messages = yield* runOpenCodeSdk("session.messages", () =>
+          context.client.session.messages({
+            sessionID: context.openCodeSessionId,
+          }),
+        ).pipe(Effect.mapError(toRequestError));
+
+        const assistantMessages = (messages.data ?? []).filter(
+          (entry) => entry.info.role === "assistant",
+        );
+        const targetIndex = assistantMessages.length - numTurns - 1;
+        const target = targetIndex >= 0 ? assistantMessages[targetIndex] : null;
+        yield* runOpenCodeSdk("session.revert", () =>
+          context.client.session.revert({
+            sessionID: context.openCodeSessionId,
+            ...(target ? { messageID: target.info.id } : {}),
+          }),
+        ).pipe(Effect.mapError(toRequestError));
+
+        return yield* readThread(threadId);
+      },
+    );
+
+    const stopAll: OpenCodeAdapterShape["stopAll"] = () =>
+      Effect.gen(function* () {
+        const contexts = [...sessions.values()];
+        sessions.clear();
+        // `stopOpenCodeContext` is typed as never-failing — SDK aborts are
+        // already `Effect.ignore`'d inside it. `ignoreCause` here also
+        // swallows defects from throwing finalizers so one bad close can't
+        // interrupt the sibling fibers. Same pattern as the layer finalizer.
+        yield* Effect.forEach(
+          contexts,
+          (context) => Effect.ignoreCause(stopOpenCodeContext(context)),
+          { concurrency: "unbounded", discard: true },
+        );
+      });
+
+    return {
+      provider: PROVIDER,
+      capabilities: {
+        sessionModelSwitch: "in-session",
+      },
+      startSession,
+      sendTurn,
+      interruptTurn,
+      respondToRequest,
+      respondToUserInput,
+      stopSession,
+      listSessions,
+      hasSession,
+      readThread,
+      rollbackThread,
+      stopAll,
+      get streamEvents() {
+        return Stream.fromQueue(runtimeEvents);
+      },
+    } satisfies OpenCodeAdapterShape;
+  });
+}
diff --git a/apps/server/src/provider/Layers/OpenCodeProvider.test.ts b/apps/server/src/provider/Layers/OpenCodeProvider.test.ts
new file mode 100644
index 00000000000..e56806e26b5
--- /dev/null
+++ b/apps/server/src/provider/Layers/OpenCodeProvider.test.ts
@@ -0,0 +1,248 @@
+import assert from "node:assert/strict";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { beforeEach } from "vitest";
+
+import { OpenCodeSettings } from "@t3tools/contracts";
+import { ServerConfig } from "../../config.ts";
+import {
+  OpenCodeRuntime,
+  OpenCodeRuntimeError,
+  type OpenCodeRuntimeShape,
+} from "../opencodeRuntime.ts";
+import { checkOpenCodeProviderStatus } from "./OpenCodeProvider.ts";
+import type { OpenCodeInventory } from "../opencodeRuntime.ts";
+const decodeOpenCodeSettings = Schema.decodeSync(OpenCodeSettings);
+
+const DEFAULT_VERSION_STDOUT = "opencode 1.14.19\n";
+
+/**
+ * The legacy `OpenCodeProviderLive` Layer + `OpenCodeProvider` service tag
+ * are deleted. The snapshot-producing logic they wrapped now lives in the
+ * standalone `checkOpenCodeProviderStatus(settings, cwd)` Effect, which
+ * drivers call directly when building their per-instance snapshot
+ * `ServerProviderShape`. Tests mirror that shape: build a settings payload,
+ * invoke the check, assert on the returned snapshot.
+ */
+
+const runtimeMock = {
+  state: {
+    runVersionError: null as Error | null,
+    versionStdout: DEFAULT_VERSION_STDOUT,
+    inventoryError: null as Error | null,
+    closeCalls: 0,
+    inventory: {
+      providerList: { connected: [] as string[], all: [] as unknown[], default: {} },
+      agents: [] as unknown[],
+    } as unknown,
+  },
+  reset() {
+    this.state.runVersionError = null;
+    this.state.versionStdout = DEFAULT_VERSION_STDOUT;
+    this.state.inventoryError = null;
+    this.state.closeCalls = 0;
+    this.state.inventory = {
+      providerList: { connected: [], all: [] as unknown[], default: {} },
+      agents: [] as unknown[],
+    };
+  },
+};
+
+const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
+  startOpenCodeServerProcess: () =>
+    Effect.succeed({
+      url: "http://127.0.0.1:4301",
+      exitCode: Effect.never,
+    }),
+  connectToOpenCodeServer: ({ serverUrl }) =>
+    Effect.gen(function* () {
+      if (!serverUrl) {
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => {
+            runtimeMock.state.closeCalls += 1;
+          }),
+        );
+      }
+      return {
+        url: serverUrl ?? "http://127.0.0.1:4301",
+        exitCode: null,
+        external: Boolean(serverUrl),
+      };
+    }),
+  runOpenCodeCommand: () =>
+    runtimeMock.state.runVersionError
+      ? Effect.fail(
+          new OpenCodeRuntimeError({
+            operation: "runOpenCodeCommand",
+            detail: runtimeMock.state.runVersionError.message,
+            cause: runtimeMock.state.runVersionError,
+          }),
+        )
+      : Effect.succeed({ stdout: runtimeMock.state.versionStdout, stderr: "", code: 0 }),
+  createOpenCodeSdkClient: () =>
+    ({}) as unknown as ReturnType<OpenCodeRuntimeShape["createOpenCodeSdkClient"]>,
+  loadOpenCodeInventory: () =>
+    runtimeMock.state.inventoryError
+      ? Effect.fail(
+          new OpenCodeRuntimeError({
+            operation: "loadOpenCodeInventory",
+            detail: runtimeMock.state.inventoryError.message,
+            cause: runtimeMock.state.inventoryError,
+          }),
+        )
+      : Effect.succeed(runtimeMock.state.inventory as OpenCodeInventory),
+};
+
+beforeEach(() => {
+  runtimeMock.reset();
+});
+
+const testLayer = Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble).pipe(
+  Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+const makeOpenCodeSettings = (overrides?: Partial<OpenCodeSettings>): OpenCodeSettings =>
+  decodeOpenCodeSettings({
+    enabled: true,
+    binaryPath: "opencode",
+    serverUrl: "",
+    serverPassword: "",
+    customModels: [],
+    ...overrides,
+  });
+
+it.layer(testLayer)("checkOpenCodeProviderStatus", (it) => {
+  it.effect("shows a codex-style missing binary message", () =>
+    Effect.gen(function* () {
+      runtimeMock.state.runVersionError = new Error("spawn opencode ENOENT");
+      const snapshot = yield* checkOpenCodeProviderStatus(makeOpenCodeSettings(), process.cwd());
+
+      assert.equal(snapshot.status, "error");
+      assert.equal(snapshot.installed, false);
+      assert.equal(snapshot.message, "OpenCode CLI (`opencode`) is not installed or not on PATH.");
+    }),
+  );
+
+  it.effect("hides generic Effect.tryPromise text for local CLI probe failures", () =>
+    Effect.gen(function* () {
+      runtimeMock.state.runVersionError = new Error("An error occurred in Effect.tryPromise");
+      const snapshot = yield* checkOpenCodeProviderStatus(makeOpenCodeSettings(), process.cwd());
+
+      assert.equal(snapshot.status, "error");
+      assert.equal(snapshot.installed, true);
+      assert.equal(snapshot.message, "Failed to execute OpenCode CLI health check.");
+    }),
+  );
+
+  it.effect("emits OpenCode variant defaults so trait picker can resolve a visible selection", () =>
+    Effect.gen(function* () {
+      runtimeMock.state.inventory = {
+        providerList: {
+          connected: ["openai"],
+          all: [
+            {
+              id: "openai",
+              name: "OpenAI",
+              models: {
+                "gpt-5.4": {
+                  id: "gpt-5.4",
+                  name: "GPT-5.4",
+                  variants: {
+                    none: {},
+                    low: {},
+                    medium: {},
+                    high: {},
+                    xhigh: {},
+                  },
+                },
+              },
+            },
+          ],
+          default: {},
+        },
+        agents: [
+          { name: "build", hidden: false, mode: "primary" },
+          { name: "plan", hidden: false, mode: "primary" },
+        ],
+      };
+
+      const snapshot = yield* checkOpenCodeProviderStatus(makeOpenCodeSettings(), process.cwd());
+      const model = snapshot.models.find((entry) => entry.slug === "openai/gpt-5.4");
+
+      assert.ok(model);
+      const variantDescriptor = model.capabilities?.optionDescriptors?.find(
+        (descriptor) => descriptor.id === "variant" && descriptor.type === "select",
+      );
+      assert.ok(variantDescriptor && variantDescriptor.type === "select");
+      assert.equal(
+        variantDescriptor.options.find((option) => option.isDefault === true)?.id,
+        "medium",
+      );
+      const agentDescriptor = model.capabilities?.optionDescriptors?.find(
+        (descriptor) => descriptor.id === "agent" && descriptor.type === "select",
+      );
+      assert.ok(agentDescriptor && agentDescriptor.type === "select");
+      assert.equal(
+        agentDescriptor.options.find((option) => option.isDefault === true)?.id,
+        "build",
+      );
+    }),
+  );
+
+  it.effect("closes the local OpenCode server scope after provider refresh", () =>
+    Effect.gen(function* () {
+      yield* checkOpenCodeProviderStatus(makeOpenCodeSettings(), process.cwd());
+
+      assert.equal(runtimeMock.state.closeCalls, 1);
+    }),
+  );
+});
+
+it.layer(testLayer)("checkOpenCodeProviderStatus with configured server URL", (it) => {
+  it.effect("surfaces a friendly auth error for configured servers", () =>
+    Effect.gen(function* () {
+      runtimeMock.state.inventoryError = new Error("401 Unauthorized");
+      const snapshot = yield* checkOpenCodeProviderStatus(
+        makeOpenCodeSettings({
+          serverUrl: "http://127.0.0.1:9999",
+          serverPassword: "secret-password",
+        }),
+        process.cwd(),
+      );
+
+      assert.equal(snapshot.status, "error");
+      assert.equal(snapshot.installed, true);
+      assert.equal(
+        snapshot.message,
+        "OpenCode server rejected authentication. Check the server URL and password.",
+      );
+    }),
+  );
+
+  it.effect("surfaces a friendly connection error for configured servers", () =>
+    Effect.gen(function* () {
+      runtimeMock.state.inventoryError = new Error(
+        "fetch failed: connect ECONNREFUSED 127.0.0.1:9999",
+      );
+      const snapshot = yield* checkOpenCodeProviderStatus(
+        makeOpenCodeSettings({
+          serverUrl: "http://127.0.0.1:9999",
+          serverPassword: "secret-password",
+        }),
+        process.cwd(),
+      );
+
+      assert.equal(snapshot.status, "error");
+      assert.equal(snapshot.installed, true);
+      assert.equal(
+        snapshot.message,
+        "Couldn't reach the configured OpenCode server at http://127.0.0.1:9999. Check that the server is running and the URL is correct.",
+      );
+    }),
+  );
+});
diff --git a/apps/server/src/provider/Layers/OpenCodeProvider.ts b/apps/server/src/provider/Layers/OpenCodeProvider.ts
new file mode 100644
index 00000000000..dea95c990d2
--- /dev/null
+++ b/apps/server/src/provider/Layers/OpenCodeProvider.ts
@@ -0,0 +1,474 @@
+import {
+  ProviderDriverKind,
+  type ModelCapabilities,
+  type OpenCodeSettings,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+
+import { createModelCapabilities } from "@t3tools/shared/model";
+import { compareSemverVersions } from "@t3tools/shared/semver";
+import {
+  buildServerProvider,
+  nonEmptyTrimmed,
+  parseGenericCliVersion,
+  providerModelsFromSettings,
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+import {
+  OpenCodeRuntime,
+  openCodeRuntimeErrorDetail,
+  type OpenCodeInventory,
+} from "../opencodeRuntime.ts";
+import type { Agent, ProviderListResponse } from "@opencode-ai/sdk/v2";
+
+const PROVIDER = ProviderDriverKind.make("opencode");
+const OPENCODE_PRESENTATION = {
+  displayName: "OpenCode",
+  showInteractionModeToggle: false,
+} as const;
+const MINIMUM_OPENCODE_VERSION = "1.14.19";
+
+class OpenCodeProbeError extends Data.TaggedError("OpenCodeProbeError")<{
+  readonly cause: unknown;
+  readonly detail: string;
+}> {}
+
+function normalizeProbeMessage(message: string): string | undefined {
+  const trimmed = message.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  if (
+    trimmed === "An error occurred in Effect.tryPromise" ||
+    trimmed === "An error occurred in Effect.try"
+  ) {
+    return undefined;
+  }
+  return trimmed;
+}
+
+function normalizedErrorMessage(cause: unknown): string | undefined {
+  if (cause instanceof OpenCodeProbeError) {
+    return normalizeProbeMessage(cause.detail);
+  }
+
+  if (!(cause instanceof Error)) {
+    return undefined;
+  }
+
+  return normalizeProbeMessage(cause.message);
+}
+
+function formatOpenCodeProbeError(input: {
+  readonly cause: unknown;
+  readonly isExternalServer: boolean;
+  readonly serverUrl: string;
+}): { readonly installed: boolean; readonly message: string } {
+  const detail = normalizedErrorMessage(input.cause);
+  const lower = detail?.toLowerCase() ?? "";
+
+  if (input.isExternalServer) {
+    if (
+      lower.includes("401") ||
+      lower.includes("403") ||
+      lower.includes("unauthorized") ||
+      lower.includes("forbidden")
+    ) {
+      return {
+        installed: true,
+        message: "OpenCode server rejected authentication. Check the server URL and password.",
+      };
+    }
+
+    if (
+      lower.includes("econnrefused") ||
+      lower.includes("enotfound") ||
+      lower.includes("fetch failed") ||
+      lower.includes("networkerror") ||
+      lower.includes("timed out") ||
+      lower.includes("timeout") ||
+      lower.includes("socket hang up")
+    ) {
+      return {
+        installed: true,
+        message: `Couldn't reach the configured OpenCode server at ${input.serverUrl}. Check that the server is running and the URL is correct.`,
+      };
+    }
+
+    return {
+      installed: true,
+      message: detail ?? "Failed to connect to the configured OpenCode server.",
+    };
+  }
+
+  if (lower.includes("enoent") || lower.includes("notfound")) {
+    return {
+      installed: false,
+      message: "OpenCode CLI (`opencode`) is not installed or not on PATH.",
+    };
+  }
+
+  if (lower.includes("quarantine")) {
+    return {
+      installed: true,
+      message:
+        "macOS is blocking the OpenCode binary (quarantine). Run `xattr -d com.apple.quarantine $(which opencode)` to fix this.",
+    };
+  }
+
+  if (lower.includes("invalid code signature") || lower.includes("corrupted")) {
+    return {
+      installed: true,
+      message:
+        "macOS killed the OpenCode process due to an invalid code signature. The binary may be corrupted — try reinstalling OpenCode.",
+    };
+  }
+
+  return {
+    installed: true,
+    message: detail
+      ? `Failed to execute OpenCode CLI health check: ${detail}`
+      : "Failed to execute OpenCode CLI health check.",
+  };
+}
+
+function titleCaseSlug(value: string): string {
+  return value
+    .split(/[-_/]+/)
+    .filter((segment) => segment.length > 0)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(" ");
+}
+
+function inferDefaultVariant(
+  providerID: string,
+  variants: ReadonlyArray<string>,
+): string | undefined {
+  if (variants.length === 1) {
+    return variants[0];
+  }
+  if (providerID === "anthropic" || providerID.startsWith("google")) {
+    return variants.includes("high") ? "high" : undefined;
+  }
+  if (providerID === "openai" || providerID === "opencode") {
+    return variants.includes("medium") ? "medium" : variants.includes("high") ? "high" : undefined;
+  }
+  return undefined;
+}
+
+function inferDefaultAgent(agents: ReadonlyArray<Agent>): string | undefined {
+  return agents.find((agent) => agent.name === "build")?.name ?? agents[0]?.name ?? undefined;
+}
+
+const DEFAULT_OPENCODE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+
+function openCodeCapabilitiesForModel(input: {
+  readonly providerID: string;
+  readonly model: ProviderListResponse["all"][number]["models"][string];
+  readonly agents: ReadonlyArray<Agent>;
+}): ModelCapabilities {
+  const variantValues = Object.keys(input.model.variants ?? {});
+  const defaultVariant = inferDefaultVariant(input.providerID, variantValues);
+  const variantOptions = variantValues.map((value) =>
+    defaultVariant === value
+      ? { id: value, label: titleCaseSlug(value), isDefault: true as const }
+      : { id: value, label: titleCaseSlug(value) },
+  );
+  const primaryAgents = input.agents.filter(
+    (agent) => !agent.hidden && (agent.mode === "primary" || agent.mode === "all"),
+  );
+  const defaultAgent = inferDefaultAgent(primaryAgents);
+  const agentOptions = primaryAgents.map((agent) =>
+    defaultAgent === agent.name
+      ? { id: agent.name, label: titleCaseSlug(agent.name), isDefault: true as const }
+      : { id: agent.name, label: titleCaseSlug(agent.name) },
+  );
+  return createModelCapabilities({
+    optionDescriptors: [
+      ...(variantOptions.length > 0
+        ? [
+            {
+              id: "variant",
+              label: "Variant",
+              type: "select" as const,
+              options: variantOptions,
+              ...(defaultVariant ? { currentValue: defaultVariant } : {}),
+            },
+          ]
+        : []),
+      ...(agentOptions.length > 0
+        ? [
+            {
+              id: "agent",
+              label: "Agent",
+              type: "select" as const,
+              options: agentOptions,
+              ...(defaultAgent ? { currentValue: defaultAgent } : {}),
+            },
+          ]
+        : []),
+    ],
+  });
+}
+
+function flattenOpenCodeModels(input: OpenCodeInventory): ReadonlyArray<ServerProviderModel> {
+  const connected = new Set(input.providerList.connected);
+  const models: Array<ServerProviderModel> = [];
+
+  for (const provider of input.providerList.all) {
+    if (!connected.has(provider.id)) {
+      continue;
+    }
+
+    for (const model of Object.values(provider.models)) {
+      const name = nonEmptyTrimmed(model.name);
+      if (!name) {
+        continue;
+      }
+
+      const subProvider = nonEmptyTrimmed(provider.name);
+      models.push({
+        slug: `${provider.id}/${model.id}`,
+        name,
+        ...(subProvider ? { subProvider } : {}),
+        isCustom: false,
+        capabilities: openCodeCapabilitiesForModel({
+          providerID: provider.id,
+          model,
+          agents: input.agents,
+        }),
+      });
+    }
+  }
+
+  return models.toSorted((left, right) => left.name.localeCompare(right.name));
+}
+
+export const makePendingOpenCodeProvider = (
+  openCodeSettings: OpenCodeSettings,
+): Effect.Effect<ServerProviderDraft> =>
+  Effect.gen(function* () {
+    const checkedAt = yield* Effect.map(DateTime.now, DateTime.formatIso);
+    const models = providerModelsFromSettings(
+      [],
+      PROVIDER,
+      openCodeSettings.customModels,
+      DEFAULT_OPENCODE_MODEL_CAPABILITIES,
+    );
+
+    if (!openCodeSettings.enabled) {
+      return buildServerProvider({
+        presentation: OPENCODE_PRESENTATION,
+        enabled: false,
+        checkedAt,
+        models,
+        probe: {
+          installed: false,
+          version: null,
+          status: "warning",
+          auth: { status: "unknown" },
+          message:
+            openCodeSettings.serverUrl.trim().length > 0
+              ? "OpenCode is disabled in T3 Code settings. A server URL is configured."
+              : "OpenCode is disabled in T3 Code settings.",
+        },
+      });
+    }
+
+    return buildServerProvider({
+      presentation: OPENCODE_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "OpenCode provider status has not been checked in this session yet.",
+      },
+    });
+  });
+
+export const checkOpenCodeProviderStatus = Effect.fn("checkOpenCodeProviderStatus")(function* (
+  openCodeSettings: OpenCodeSettings,
+  cwd: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<ServerProviderDraft, never, OpenCodeRuntime> {
+  const openCodeRuntime = yield* OpenCodeRuntime;
+  const checkedAt = DateTime.formatIso(yield* DateTime.now);
+  const customModels = openCodeSettings.customModels;
+  const isExternalServer = openCodeSettings.serverUrl.trim().length > 0;
+
+  const fallback = (cause: unknown, version: string | null = null) => {
+    const failure = formatOpenCodeProbeError({
+      cause,
+      isExternalServer,
+      serverUrl: openCodeSettings.serverUrl,
+    });
+    return buildServerProvider({
+      presentation: OPENCODE_PRESENTATION,
+      enabled: openCodeSettings.enabled,
+      checkedAt,
+      models: providerModelsFromSettings(
+        [],
+        PROVIDER,
+        customModels,
+        DEFAULT_OPENCODE_MODEL_CAPABILITIES,
+      ),
+      probe: {
+        installed: failure.installed,
+        version,
+        status: "error",
+        auth: { status: "unknown" },
+        message: failure.message,
+      },
+    });
+  };
+
+  if (!openCodeSettings.enabled) {
+    return buildServerProvider({
+      presentation: OPENCODE_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models: providerModelsFromSettings(
+        [],
+        PROVIDER,
+        customModels,
+        DEFAULT_OPENCODE_MODEL_CAPABILITIES,
+      ),
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: isExternalServer
+          ? "OpenCode is disabled in T3 Code settings. A server URL is configured."
+          : "OpenCode is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  let version: string | null = null;
+  if (!isExternalServer) {
+    const versionExit = yield* Effect.exit(
+      openCodeRuntime
+        .runOpenCodeCommand({
+          binaryPath: openCodeSettings.binaryPath,
+          args: ["--version"],
+          environment,
+        })
+        .pipe(
+          Effect.mapError(
+            (cause) => new OpenCodeProbeError({ cause, detail: openCodeRuntimeErrorDetail(cause) }),
+          ),
+        ),
+    );
+    if (versionExit._tag === "Failure") {
+      return fallback(Cause.squash(versionExit.cause));
+    }
+    version = parseGenericCliVersion(versionExit.value.stdout) ?? null;
+
+    if (!version) {
+      return fallback(
+        new Error(
+          `Unable to determine OpenCode version from \`opencode --version\` output. T3 Code requires OpenCode v${MINIMUM_OPENCODE_VERSION} or newer.`,
+        ),
+        null,
+      );
+    }
+    if (compareSemverVersions(version, MINIMUM_OPENCODE_VERSION) < 0) {
+      return buildServerProvider({
+        presentation: OPENCODE_PRESENTATION,
+        enabled: openCodeSettings.enabled,
+        checkedAt,
+        models: providerModelsFromSettings(
+          [],
+          PROVIDER,
+          customModels,
+          DEFAULT_OPENCODE_MODEL_CAPABILITIES,
+        ),
+        probe: {
+          installed: true,
+          version,
+          status: "error",
+          auth: { status: "unknown" },
+          message: `OpenCode v${version} is too old. Upgrade to v${MINIMUM_OPENCODE_VERSION} or newer.`,
+        },
+      });
+    }
+  }
+
+  const inventoryExit = yield* Effect.exit(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* openCodeRuntime
+          .connectToOpenCodeServer({
+            binaryPath: openCodeSettings.binaryPath,
+            serverUrl: openCodeSettings.serverUrl,
+            environment,
+          })
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new OpenCodeProbeError({ cause, detail: openCodeRuntimeErrorDetail(cause) }),
+            ),
+          );
+        return yield* openCodeRuntime
+          .loadOpenCodeInventory(
+            openCodeRuntime.createOpenCodeSdkClient({
+              baseUrl: server.url,
+              directory: cwd,
+              ...(isExternalServer && openCodeSettings.serverPassword
+                ? { serverPassword: openCodeSettings.serverPassword }
+                : {}),
+            }),
+          )
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new OpenCodeProbeError({ cause, detail: openCodeRuntimeErrorDetail(cause) }),
+            ),
+          );
+      }),
+    ),
+  );
+  if (inventoryExit._tag === "Failure") {
+    return fallback(Cause.squash(inventoryExit.cause), version);
+  }
+
+  const models = providerModelsFromSettings(
+    flattenOpenCodeModels(inventoryExit.value),
+    PROVIDER,
+    customModels,
+    DEFAULT_OPENCODE_MODEL_CAPABILITIES,
+  );
+  const connectedCount = inventoryExit.value.providerList.connected.length;
+  return buildServerProvider({
+    presentation: OPENCODE_PRESENTATION,
+    enabled: true,
+    checkedAt,
+    models,
+    probe: {
+      installed: true,
+      version,
+      status: connectedCount > 0 ? "ready" : "warning",
+      auth: {
+        status: connectedCount > 0 ? "authenticated" : "unknown",
+        type: "opencode",
+      },
+      message:
+        connectedCount > 0
+          ? `${connectedCount} upstream provider${connectedCount === 1 ? "" : "s"} connected through ${isExternalServer ? "the configured OpenCode server" : "OpenCode"}.`
+          : isExternalServer
+            ? "Connected to the configured OpenCode server, but it did not report any connected upstream providers."
+            : "OpenCode is available, but it did not report any connected upstream providers.",
+    },
+  });
+});
diff --git a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
index db0293f0fea..7fb545b2bed 100644
--- a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
@@ -1,18 +1,34 @@
-import type { ProviderKind } from "@t3tools/contracts";
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  type ServerProvider,
+} from "@t3tools/contracts";
 import { it, assert, vi } from "@effect/vitest";
-import { assertFailure } from "@effect/vitest/utils";
 
-import { Effect, Layer, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Stream from "effect/Stream";
 
-import { ClaudeAdapter, ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
-import { CodexAdapter, CodexAdapterShape } from "../Services/CodexAdapter.ts";
+import type { ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
+import type { CodexAdapterShape } from "../Services/CodexAdapter.ts";
+import type { CursorAdapterShape } from "../Services/CursorAdapter.ts";
+import type { OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
 import { ProviderAdapterRegistry } from "../Services/ProviderAdapterRegistry.ts";
+import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
+import type { ProviderInstance } from "../ProviderDriver.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
+import type { TextGenerationShape } from "../../textGeneration/TextGeneration.ts";
 import { ProviderAdapterRegistryLive } from "./ProviderAdapterRegistry.ts";
-import { ProviderUnsupportedError } from "../Errors.ts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 
+const CODEX_DRIVER = ProviderDriverKind.make("codex");
+const CLAUDE_AGENT_DRIVER = ProviderDriverKind.make("claudeAgent");
+const OPENCODE_DRIVER = ProviderDriverKind.make("opencode");
+const CURSOR_DRIVER = ProviderDriverKind.make("cursor");
+
 const fakeCodexAdapter: CodexAdapterShape = {
-  provider: "codex",
+  provider: CODEX_DRIVER,
   capabilities: { sessionModelSwitch: "in-session" },
   startSession: vi.fn(),
   sendTurn: vi.fn(),
@@ -29,7 +45,41 @@ const fakeCodexAdapter: CodexAdapterShape = {
 };
 
 const fakeClaudeAdapter: ClaudeAdapterShape = {
-  provider: "claudeAgent",
+  provider: CLAUDE_AGENT_DRIVER,
+  capabilities: { sessionModelSwitch: "in-session" },
+  startSession: vi.fn(),
+  sendTurn: vi.fn(),
+  interruptTurn: vi.fn(),
+  respondToRequest: vi.fn(),
+  respondToUserInput: vi.fn(),
+  stopSession: vi.fn(),
+  listSessions: vi.fn(),
+  hasSession: vi.fn(),
+  readThread: vi.fn(),
+  rollbackThread: vi.fn(),
+  stopAll: vi.fn(),
+  streamEvents: Stream.empty,
+};
+
+const fakeOpenCodeAdapter: OpenCodeAdapterShape = {
+  provider: OPENCODE_DRIVER,
+  capabilities: { sessionModelSwitch: "in-session" },
+  startSession: vi.fn(),
+  sendTurn: vi.fn(),
+  interruptTurn: vi.fn(),
+  respondToRequest: vi.fn(),
+  respondToUserInput: vi.fn(),
+  stopSession: vi.fn(),
+  listSessions: vi.fn(),
+  hasSession: vi.fn(),
+  readThread: vi.fn(),
+  rollbackThread: vi.fn(),
+  stopAll: vi.fn(),
+  streamEvents: Stream.empty,
+};
+
+const fakeCursorAdapter: CursorAdapterShape = {
+  provider: CURSOR_DRIVER,
   capabilities: { sessionModelSwitch: "in-session" },
   startSession: vi.fn(),
   sendTurn: vi.fn(),
@@ -45,38 +95,98 @@ const fakeClaudeAdapter: ClaudeAdapterShape = {
   streamEvents: Stream.empty,
 };
 
-const layer = it.layer(
-  Layer.mergeAll(
-    Layer.provide(
-      ProviderAdapterRegistryLive,
-      Layer.mergeAll(
-        Layer.succeed(CodexAdapter, fakeCodexAdapter),
-        Layer.succeed(ClaudeAdapter, fakeClaudeAdapter),
-      ),
-    ),
-    NodeServices.layer,
-  ),
+// ProviderAdapterRegistryLive is now a facade over ProviderInstanceRegistry —
+// it walks `listInstances` once at boot and surfaces the default-instance
+// adapter keyed by its driver kind. To test the facade we supply four fake
+// instances whose `instanceId === defaultInstanceIdForDriver(driverKind)` so
+// they pass the default-instance filter.
+const makeFakeInstance = (
+  driverKindString: "codex" | "claudeAgent" | "cursor" | "opencode",
+  adapter: ProviderInstance["adapter"],
+): ProviderInstance => {
+  const driverKind = ProviderDriverKind.make(driverKindString);
+  return {
+    instanceId: defaultInstanceIdForDriver(driverKind),
+    driverKind,
+    continuationIdentity: {
+      driverKind,
+      continuationKey: `${driverKind}:instance:${defaultInstanceIdForDriver(driverKind)}`,
+    },
+    displayName: undefined,
+    enabled: true,
+    snapshot: {
+      maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+        provider: driverKind,
+        packageName: null,
+      }),
+      getSnapshot: Effect.succeed({} as unknown as ServerProvider),
+      refresh: Effect.succeed({} as unknown as ServerProvider),
+      streamChanges: Stream.empty,
+    },
+    adapter,
+    textGeneration: {} as unknown as TextGenerationShape,
+  };
+};
+
+const fakeInstances: ReadonlyArray<ProviderInstance> = [
+  makeFakeInstance("codex", fakeCodexAdapter),
+  makeFakeInstance("claudeAgent", fakeClaudeAdapter),
+  makeFakeInstance("opencode", fakeOpenCodeAdapter),
+  makeFakeInstance("cursor", fakeCursorAdapter),
+];
+
+const fakeInstanceRegistryLayer = Layer.succeed(ProviderInstanceRegistry, {
+  getInstance: (instanceId) =>
+    Effect.succeed(fakeInstances.find((instance) => instance.instanceId === instanceId)),
+  listInstances: Effect.succeed(fakeInstances),
+  listUnavailable: Effect.succeed([]),
+  streamChanges: Stream.empty,
+  // Tests never drive changes through this fake; acquire a throwaway
+  // subscription on an unused PubSub so the shape is satisfied.
+  subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) => PubSub.subscribe(pubsub)),
+});
+
+const layer = Layer.mergeAll(
+  Layer.provide(ProviderAdapterRegistryLive, fakeInstanceRegistryLayer),
+  NodeServices.layer,
 );
 
-layer("ProviderAdapterRegistryLive", (it) => {
-  it.effect("resolves a registered provider adapter", () =>
+it.layer(layer)("ProviderAdapterRegistryLive", (it) => {
+  it("resolves adapters and routing metadata from provider instances", () =>
     Effect.gen(function* () {
       const registry = yield* ProviderAdapterRegistry;
-      const codex = yield* registry.getByProvider("codex");
-      const claude = yield* registry.getByProvider("claudeAgent");
-      assert.equal(codex, fakeCodexAdapter);
-      assert.equal(claude, fakeClaudeAdapter);
+      const claudeInstanceId = defaultInstanceIdForDriver(CLAUDE_AGENT_DRIVER);
 
-      const providers = yield* registry.listProviders();
-      assert.deepEqual(providers, ["codex", "claudeAgent"]);
-    }),
-  );
+      const adapter = yield* registry.getByInstance(claudeInstanceId);
+      assert.strictEqual(adapter, fakeClaudeAdapter);
 
-  it.effect("fails with ProviderUnsupportedError for unknown providers", () =>
-    Effect.gen(function* () {
-      const registry = yield* ProviderAdapterRegistry;
-      const adapter = yield* registry.getByProvider("unknown" as ProviderKind).pipe(Effect.result);
-      assertFailure(adapter, new ProviderUnsupportedError({ provider: "unknown" }));
-    }),
-  );
+      const info = yield* registry.getInstanceInfo(claudeInstanceId);
+      assert.deepStrictEqual(info, {
+        instanceId: claudeInstanceId,
+        driverKind: CLAUDE_AGENT_DRIVER,
+        displayName: undefined,
+        accentColor: undefined,
+        enabled: true,
+        continuationIdentity: {
+          driverKind: CLAUDE_AGENT_DRIVER,
+          continuationKey: "claudeAgent:instance:claudeAgent",
+        },
+      });
+
+      const instances = yield* registry.listInstances();
+      assert.deepStrictEqual(instances, [
+        defaultInstanceIdForDriver(CODEX_DRIVER),
+        claudeInstanceId,
+        defaultInstanceIdForDriver(OPENCODE_DRIVER),
+        defaultInstanceIdForDriver(CURSOR_DRIVER),
+      ]);
+
+      const providers = yield* registry.listProviders();
+      assert.deepStrictEqual(providers, [
+        CODEX_DRIVER,
+        CLAUDE_AGENT_DRIVER,
+        OPENCODE_DRIVER,
+        CURSOR_DRIVER,
+      ]);
+    }));
 });
diff --git a/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts b/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts
index b6c987c64c3..b492399b10b 100644
--- a/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts
+++ b/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts
@@ -1,50 +1,102 @@
 /**
- * ProviderAdapterRegistryLive - In-memory provider adapter lookup layer.
+ * ProviderAdapterRegistryLive — facade over `ProviderInstanceRegistry`.
  *
- * Binds provider kinds (codex/claudeAgent/...) to concrete adapter services.
- * This layer only performs adapter lookup; it does not route session-scoped
- * calls or own provider lifecycle workflows.
+ * `ProviderAdapterRegistry` historically mapped one `ProviderDriverKind` to one
+ * adapter via the four `<X>AdapterLive` singleton Layers. The per-instance
+ * refactor moved adapter construction inside each `ProviderDriver.create()`:
+ * adapters are now bundled on the `ProviderInstance` that the
+ * `ProviderInstanceRegistry` owns.
+ *
+ * This facade fulfills the `ProviderAdapterRegistryShape` contract by doing
+ * dynamic look-ups against `ProviderInstanceRegistry` on every call. That
+ * means settings-driven hot-reload shows up here automatically — adding a
+ * new instance via settings makes `getByInstance` resolve immediately
+ * without rebuilding the facade.
  *
  * @module ProviderAdapterRegistryLive
  */
-import { Effect, Layer } from "effect";
+import {
+  defaultInstanceIdForDriver,
+  ProviderInstanceId,
+  type ProviderDriverKind,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
-import { ProviderUnsupportedError, type ProviderAdapterError } from "../Errors.ts";
-import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
+import { ProviderUnsupportedError } from "../Errors.ts";
+import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
 import {
   ProviderAdapterRegistry,
   type ProviderAdapterRegistryShape,
 } from "../Services/ProviderAdapterRegistry.ts";
-import { ClaudeAdapter } from "../Services/ClaudeAdapter.ts";
-import { CodexAdapter } from "../Services/CodexAdapter.ts";
-
-export interface ProviderAdapterRegistryLiveOptions {
-  readonly adapters?: ReadonlyArray<ProviderAdapterShape<ProviderAdapterError>>;
-}
-
-const makeProviderAdapterRegistry = Effect.fn("makeProviderAdapterRegistry")(function* (
-  options?: ProviderAdapterRegistryLiveOptions,
-) {
-  const adapters =
-    options?.adapters !== undefined
-      ? options.adapters
-      : [yield* CodexAdapter, yield* ClaudeAdapter];
-  const byProvider = new Map(adapters.map((adapter) => [adapter.provider, adapter]));
-
-  const getByProvider: ProviderAdapterRegistryShape["getByProvider"] = (provider) => {
-    const adapter = byProvider.get(provider);
-    if (!adapter) {
-      return Effect.fail(new ProviderUnsupportedError({ provider }));
-    }
-    return Effect.succeed(adapter);
-  };
+
+const makeProviderAdapterRegistry = Effect.fn("makeProviderAdapterRegistry")(function* () {
+  const registry = yield* ProviderInstanceRegistry;
+
+  const getByInstance: ProviderAdapterRegistryShape["getByInstance"] = (instanceId) =>
+    registry.getInstance(instanceId).pipe(
+      Effect.flatMap((instance) =>
+        instance === undefined
+          ? Effect.fail(
+              new ProviderUnsupportedError({
+                provider: instanceId,
+              }),
+            )
+          : Effect.succeed(instance.adapter),
+      ),
+    );
+
+  const getInstanceInfo: ProviderAdapterRegistryShape["getInstanceInfo"] = (instanceId) =>
+    registry.getInstance(instanceId).pipe(
+      Effect.flatMap((instance) =>
+        instance === undefined
+          ? Effect.fail(
+              new ProviderUnsupportedError({
+                provider: instanceId,
+              }),
+            )
+          : Effect.succeed({
+              instanceId: instance.instanceId,
+              driverKind: instance.driverKind,
+              displayName: instance.displayName,
+              accentColor: instance.accentColor,
+              enabled: instance.enabled,
+              continuationIdentity: instance.continuationIdentity,
+            }),
+      ),
+    );
+
+  const listInstances: ProviderAdapterRegistryShape["listInstances"] = () =>
+    registry.listInstances.pipe(
+      Effect.map((instances) => instances.map((instance) => instance.instanceId)),
+    );
 
   const listProviders: ProviderAdapterRegistryShape["listProviders"] = () =>
-    Effect.sync(() => Array.from(byProvider.keys()));
+    registry.listInstances.pipe(
+      Effect.map((instances) => {
+        const kinds = new Set<ProviderDriverKind>();
+        for (const instance of instances) {
+          const defaultId = defaultInstanceIdForDriver(instance.driverKind);
+          if (instance.instanceId === defaultId) {
+            // Only the default-instance rows show up through the legacy
+            // shim — custom instances like `codex_personal` have no
+            // `ProviderDriverKind` equivalent.
+            kinds.add(instance.driverKind);
+          }
+        }
+        return Array.from(kinds);
+      }),
+    );
 
   return {
-    getByProvider,
+    getByInstance,
+    getInstanceInfo,
+    listInstances,
     listProviders,
+    // Proxy directly — the facade has no state of its own; the instance
+    // registry already coalesces adds/removes/rebuilds into one emission.
+    streamChanges: registry.streamChanges,
+    subscribeChanges: registry.subscribeChanges,
   } satisfies ProviderAdapterRegistryShape;
 });
 
@@ -52,3 +104,14 @@ export const ProviderAdapterRegistryLive = Layer.effect(
   ProviderAdapterRegistry,
   makeProviderAdapterRegistry(),
 );
+
+// Exposed for tests that want to build a facade over a pre-assembled
+// `ProviderInstanceRegistry` without pulling in the whole boot graph.
+export { makeProviderAdapterRegistry };
+
+// Re-export for consumers that need the accessor shape. The service tag
+// itself lives in `Services/ProviderAdapterRegistry.ts`.
+export { ProviderAdapterRegistry } from "../Services/ProviderAdapterRegistry.ts";
+// Re-export for consumers (including tests) that construct a
+// `ProviderInstanceId` before calling `getByInstance`.
+export { ProviderInstanceId };
diff --git a/apps/server/src/provider/Layers/ProviderEventLoggers.ts b/apps/server/src/provider/Layers/ProviderEventLoggers.ts
new file mode 100644
index 00000000000..14e9a1075d5
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderEventLoggers.ts
@@ -0,0 +1,85 @@
+/**
+ * ProviderEventLoggers — single observability service that owns the two
+ * shared NDJSON streams the provider runtime writes:
+ *
+ *   - `native`    — provider-protocol events as the SDK emits them, written
+ *                   from inside each `<X>Adapter` factory.
+ *   - `canonical` — runtime events after `ProviderService` has normalized
+ *                   them onto `ProviderRuntimeEvent`.
+ *
+ * Why a service tag and not constructor options?
+ *
+ *   - Adapters are now constructed *inside* drivers (`<X>Driver.create()`),
+ *     not at the boot Layer. There is no longer a single `make<X>AdapterLive(options)`
+ *     call site where we can hand an `EventNdjsonLogger` in by hand.
+ *   - Multiple driver instances per kind (`codex_personal`, `codex_work`)
+ *     should share one underlying log writer per stream — opening N writers
+ *     against the same rotating file would race the rotation logic. Owning
+ *     the loggers on a single tag keeps that invariant intact.
+ *   - Tests can swap one (or both) loggers with in-memory recorders by
+ *     `Layer.succeed(ProviderEventLoggers, { native, canonical })` instead of
+ *     juggling per-Layer option threading.
+ *
+ * Both fields are optional. `makeEventNdjsonLogger` returns `undefined` when
+ * the target directory cannot be created; we forward that as `undefined`
+ * rather than failing the boot Layer, matching the previous best-effort
+ * behavior of `server.ts`.
+ *
+ * @module provider/Layers/ProviderEventLoggers
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import { ServerConfig } from "../../config.ts";
+import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
+
+export interface ProviderEventLoggersShape {
+  readonly native: EventNdjsonLogger | undefined;
+  readonly canonical: EventNdjsonLogger | undefined;
+}
+
+/**
+ * Shared logger pair for native + canonical provider event streams.
+ *
+ * Service value is intentionally a struct of two optional loggers rather
+ * than two parallel tags. Construction site is one place
+ * (`ProviderEventLoggersLive`); consumers (drivers, `ProviderService`) read
+ * one tag and pluck the field they need.
+ */
+export class ProviderEventLoggers extends Context.Service<
+  ProviderEventLoggers,
+  ProviderEventLoggersShape
+>()("t3/provider/ProviderEventLoggers") {}
+
+/**
+ * Constant value used by tests / boot layers that want to opt out of native
+ * + canonical logging entirely. Keeps the tag non-optional in the type
+ * system while letting the runtime treat absence as a no-op.
+ */
+export const NoOpProviderEventLoggers: ProviderEventLoggersShape = {
+  native: undefined,
+  canonical: undefined,
+};
+
+/**
+ * Live Layer that builds both loggers from `ServerConfig.providerEventLogPath`.
+ * If the directory create fails for either stream, the corresponding field
+ * is `undefined` and writes from that stream become no-ops downstream.
+ */
+export const ProviderEventLoggersLive = Layer.effect(
+  ProviderEventLoggers,
+  Effect.gen(function* () {
+    const { providerEventLogPath } = yield* ServerConfig;
+    const native = yield* makeEventNdjsonLogger(providerEventLogPath, {
+      stream: "native",
+    });
+    const canonical = yield* makeEventNdjsonLogger(providerEventLogPath, {
+      stream: "canonical",
+    });
+    return {
+      native,
+      canonical,
+    } satisfies ProviderEventLoggersShape;
+  }),
+);
diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts
new file mode 100644
index 00000000000..4e43e04cb7c
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts
@@ -0,0 +1,178 @@
+/**
+ * ProviderInstanceRegistryHydration — derive a `ProviderInstanceConfigMap`
+ * from `ServerSettings` and keep `ProviderInstanceRegistry` in sync with it.
+ *
+ * The server still reads two shapes:
+ *
+ *   1. `settings.providerInstances` — the new driver-agnostic map the
+ *      registry expects. Keyed by `ProviderInstanceId`, values are
+ *      `ProviderInstanceConfig` envelopes.
+ *   2. `settings.providers.<kind>` — the legacy single-instance-per-driver
+ *      fields (`providers.codex`, `providers.claudeAgent`, …). These are
+ *      the source of truth for every deployment that hasn't been migrated
+ *      yet to an explicit `providerInstances` entry.
+ *
+ * This module bridges (2) into (1) and wires the resulting map into a
+ * mutable registry. For every built-in driver whose id is not already
+ * present in `providerInstances` (keyed on
+ * `defaultInstanceIdForDriver(driverKind)` — literally the driver kind as a
+ * routing slug), we synthesize an envelope from the legacy field. The
+ * registry decodes both flavours through the same `configSchema` and ends
+ * up with one uniform `ProviderInstance` per entry.
+ *
+ * Explicit `providerInstances` entries always win — users can already
+ * override the legacy `providers.<kind>` blob by authoring a
+ * `providerInstances.codex` entry with a matching driver, and we don't
+ * want the synthesized envelope to silently stomp their config.
+ *
+ * Hot-reload
+ * ----------
+ * On layer build we:
+ *   1. Read the current `ServerSettings` once and use it to seed the
+ *      registry's initial state via `ProviderInstanceRegistryMutableLayer`.
+ *   2. Fork a daemon fiber (lifetime tied to the layer's scope) that
+ *      subscribes to `ServerSettingsService.streamChanges` and calls
+ *      `ProviderInstanceRegistryMutator.reconcile` on every emission.
+ *
+ * Failures inside the watcher are logged and swallowed so a single bad
+ * settings emission cannot kill the registry. Unknown drivers and invalid
+ * configs already round-trip through the registry's own "unavailable"
+ * shadow bucket.
+ *
+ * @module provider/Layers/ProviderInstanceRegistryHydration
+ */
+import {
+  defaultInstanceIdForDriver,
+  type ProviderInstanceConfig,
+  type ProviderInstanceConfigMap,
+  ServerSettings,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+
+import { ServerSettingsService } from "../../serverSettings.ts";
+import { BUILT_IN_DRIVERS, type BuiltInDriversEnv } from "../builtInDrivers.ts";
+import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
+import { ProviderInstanceRegistryMutator } from "../Services/ProviderInstanceRegistryMutator.ts";
+import { ProviderInstanceRegistryMutableLayer } from "./ProviderInstanceRegistryLive.ts";
+
+/**
+ * Synthesize a `ProviderInstanceConfigMap` from a `ServerSettings` snapshot.
+ *
+ * Strategy:
+ *   1. Copy all explicit `settings.providerInstances` entries verbatim.
+ *   2. For each built-in driver whose `defaultInstanceIdForDriver(id)` key
+ *      is *not* already in the explicit map, synthesize an entry from the
+ *      matching legacy `settings.providers.<kind>` blob.
+ *
+ * The returned map is the input the registry consumes; pure & exported
+ * separately so the hydration logic can be exercised by unit tests
+ * without layering.
+ */
+export const deriveProviderInstanceConfigMap = (
+  settings: ServerSettings,
+): ProviderInstanceConfigMap => {
+  const merged: Record<string, ProviderInstanceConfig> = { ...settings.providerInstances };
+
+  for (const driver of BUILT_IN_DRIVERS) {
+    const instanceId = defaultInstanceIdForDriver(driver.driverKind);
+    if (instanceId in merged) {
+      // Explicit `providerInstances` entry for this slot — user-authored
+      // config always wins over the legacy mirror.
+      continue;
+    }
+
+    // Only built-in drivers have a legacy mirror; the registry's
+    // `providers` struct is keyed on the same literal slug as
+    // `driverKind`. Access is dynamic (the driver kind is a branded string),
+    // but it's constrained to `keyof settings.providers` by the union of
+    // built-in driver kinds.
+    const legacyKey = driver.driverKind as keyof ServerSettings["providers"];
+    const legacyConfig = settings.providers[legacyKey];
+    if (legacyConfig === undefined) {
+      continue;
+    }
+
+    merged[instanceId] = {
+      driver: driver.driverKind,
+      config: legacyConfig,
+    };
+  }
+
+  return merged as ProviderInstanceConfigMap;
+};
+
+/**
+ * Layer that consumes `ProviderInstanceRegistryMutator` and forks a
+ * settings-watcher fiber. The fiber's lifetime is tied to the enclosing
+ * layer scope (process lifetime in production), so it is interrupted on
+ * shutdown without leaking.
+ *
+ * Errors inside the watcher are logged and swallowed — the registry's own
+ * "unavailable" bucket already absorbs unknown drivers and invalid
+ * configs, so the only way the watcher could fail is a settings stream
+ * tear-down, which logs and exits cleanly.
+ */
+const SettingsWatcherLive: Layer.Layer<
+  never,
+  never,
+  ProviderInstanceRegistryMutator | ServerSettingsService
+> = Layer.effectDiscard(
+  Effect.gen(function* () {
+    const mutator = yield* ProviderInstanceRegistryMutator;
+    const serverSettings = yield* ServerSettingsService;
+    yield* serverSettings.streamChanges.pipe(
+      Stream.runForEach((next) =>
+        mutator
+          .reconcile(deriveProviderInstanceConfigMap(next))
+          .pipe(
+            Effect.catchCause((cause) =>
+              Effect.logError("ProviderInstanceRegistry reconcile failed", cause),
+            ),
+          ),
+      ),
+      Effect.forkScoped,
+    );
+  }),
+);
+
+/**
+ * Hydrate `ProviderInstanceRegistry` from `ServerSettings` and keep it in
+ * sync with subsequent `streamChanges` emissions.
+ *
+ * The Layer's two halves:
+ *   - `ProviderInstanceRegistryMutableLayer` produces the registry +
+ *     mutator from the initial config map. Its scope owns every
+ *     per-instance child scope created during reconcile.
+ *   - `SettingsWatcherLive` consumes the mutator and runs a daemon fiber
+ *     in the same scope.
+ *
+ * Composing via `Layer.provideMerge` makes the watcher's deps available
+ * from the mutable layer while still surfacing the registry as an output.
+ * The mutator tag is technically also exposed; only this module imports
+ * it, so the visibility leak is harmless in practice.
+ */
+export const ProviderInstanceRegistryHydrationLive: Layer.Layer<
+  ProviderInstanceRegistry,
+  never,
+  BuiltInDriversEnv | ServerSettingsService
+> = Layer.unwrap(
+  Effect.gen(function* () {
+    const serverSettings = yield* ServerSettingsService;
+    const initialSettings: ServerSettings | undefined = yield* serverSettings.getSettings.pipe(
+      Effect.orElseSucceed(() => undefined),
+    );
+    const initialConfigMap =
+      initialSettings === undefined
+        ? ({} as ProviderInstanceConfigMap)
+        : deriveProviderInstanceConfigMap(initialSettings);
+
+    const mutableLayer = ProviderInstanceRegistryMutableLayer({
+      drivers: BUILT_IN_DRIVERS,
+      configMap: initialConfigMap,
+    });
+
+    return SettingsWatcherLive.pipe(Layer.provideMerge(mutableLayer));
+  }),
+) as Layer.Layer<ProviderInstanceRegistry, never, BuiltInDriversEnv | ServerSettingsService>;
diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
new file mode 100644
index 00000000000..86f99c97326
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
@@ -0,0 +1,368 @@
+/**
+ * Multi-instance validation slices for `ProviderInstanceRegistryLive`.
+ *
+ * Two axes of the driver/registry refactor are exercised here:
+ *
+ *  1. **Same driver, many instances** — the "multi-instance codex slice"
+ *     describe block below configures two independent `codex` instances and
+ *     asserts each gets its own closures and identity. This is the
+ *     multi-codex capability the refactor exists to unlock.
+ *
+ *  2. **Many drivers, one registry** — the "all drivers slice" describe
+ *     block below configures one instance of every shipped driver
+ *     (`codex`, `claudeAgent`, `cursor`, `opencode`) in a single
+ *     `ProviderInstanceConfigMap` and asserts the registry boots them all
+ *     without cross-contamination. This proves the driver SPI is uniform
+ *     across every provider — any driver plugs into the registry through
+ *     the same `ProviderDriver` value contract.
+ *
+ * Every instance in these tests is configured with `enabled: false` so the
+ * provider-status checks short-circuit to pending/disabled snapshots
+ * without trying to spawn real `codex` / `claude` / `agent` / `opencode`
+ * binaries. That keeps the assertions focused on registry routing
+ * behaviour rather than the runtime details of each provider.
+ */
+import { describe, expect, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import {
+  type ClaudeSettings,
+  type CodexSettings,
+  type CursorSettings,
+  type OpenCodeSettings,
+  ProviderDriverKind,
+  type ProviderInstanceConfigMap,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+
+import { ServerConfig } from "../../config.ts";
+import { ClaudeDriver } from "../Drivers/ClaudeDriver.ts";
+import { CodexDriver } from "../Drivers/CodexDriver.ts";
+import { CursorDriver } from "../Drivers/CursorDriver.ts";
+import { OpenCodeDriver } from "../Drivers/OpenCodeDriver.ts";
+import { OpenCodeRuntimeLive } from "../opencodeRuntime.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "./ProviderEventLoggers.ts";
+import { makeProviderInstanceRegistry } from "./ProviderInstanceRegistryLive.ts";
+
+const TestHttpClientLive = Layer.succeed(
+  HttpClient.HttpClient,
+  HttpClient.make((request) =>
+    Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ version: "0.0.0" }))),
+  ),
+);
+
+const makeCodexConfig = (overrides: Partial<CodexSettings>): CodexSettings => ({
+  enabled: false,
+  binaryPath: "codex",
+  homePath: "",
+  shadowHomePath: "",
+  customModels: [],
+  ...overrides,
+});
+
+const makeClaudeConfig = (overrides: Partial<ClaudeSettings>): ClaudeSettings => ({
+  enabled: false,
+  binaryPath: "claude",
+  homePath: "",
+  customModels: [],
+  launchArgs: "",
+  ...overrides,
+});
+
+const makeCursorConfig = (overrides: Partial<CursorSettings>): CursorSettings => ({
+  enabled: false,
+  binaryPath: "agent",
+  apiEndpoint: "",
+  customModels: [],
+  ...overrides,
+});
+
+const makeOpenCodeConfig = (overrides: Partial<OpenCodeSettings>): OpenCodeSettings => ({
+  enabled: false,
+  binaryPath: "opencode",
+  serverUrl: "",
+  serverPassword: "",
+  customModels: [],
+  ...overrides,
+});
+
+describe("ProviderInstanceRegistryLive — multi-instance codex slice", () => {
+  // `ServerConfig.layerTest` needs `FileSystem` to materialize its scratch
+  // directory. `Layer.merge` just unions requirements, so we have to push
+  // `NodeServices.layer` through `Layer.provideMerge` to satisfy that
+  // dependency while still surfacing NodeServices to the test body (the
+  // codex driver's `create` yields `ChildProcessSpawner` directly).
+  const testLayer = ServerConfig.layerTest(process.cwd(), {
+    prefix: "provider-instance-registry-test",
+  }).pipe(
+    Layer.provideMerge(NodeServices.layer),
+    Layer.provideMerge(TestHttpClientLive),
+    Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+  );
+
+  it.live("boots two independent codex instances from a ProviderInstanceConfigMap", () =>
+    Effect.gen(function* () {
+      const personalId = ProviderInstanceId.make("codex_personal");
+      const workId = ProviderInstanceId.make("codex_work");
+      const codexDriverKind = ProviderDriverKind.make("codex");
+
+      const configMap: ProviderInstanceConfigMap = {
+        [personalId]: {
+          driver: codexDriverKind,
+          displayName: "Codex (personal)",
+          enabled: false,
+          config: makeCodexConfig({
+            binaryPath: "/opt/codex-personal/bin/codex",
+            homePath: "/home/julius/.codex_personal",
+            customModels: ["personal-preview"],
+          }),
+        },
+        [workId]: {
+          driver: codexDriverKind,
+          displayName: "Codex (work)",
+          enabled: false,
+          config: makeCodexConfig({
+            binaryPath: "/opt/codex-work/bin/codex",
+            homePath: "/home/julius/.codex",
+            customModels: ["work-preview"],
+          }),
+        },
+      };
+
+      const { registry } = yield* makeProviderInstanceRegistry({
+        drivers: [CodexDriver],
+        configMap,
+      });
+
+      const instances = yield* registry.listInstances;
+      expect(instances.map((instance) => instance.instanceId).toSorted()).toEqual(
+        [personalId, workId].toSorted(),
+      );
+      expect(instances.every((instance) => instance.driverKind === codexDriverKind)).toBe(true);
+      expect(instances.map((instance) => instance.displayName).toSorted()).toEqual(
+        ["Codex (personal)", "Codex (work)"].toSorted(),
+      );
+
+      // Each instance must be retrievable by id and carry its *own* closures.
+      const personal = yield* registry.getInstance(personalId);
+      const work = yield* registry.getInstance(workId);
+      expect(personal).toBeDefined();
+      expect(work).toBeDefined();
+      expect(personal!.adapter).not.toBe(work!.adapter);
+      expect(personal!.textGeneration).not.toBe(work!.textGeneration);
+      expect(personal!.snapshot).not.toBe(work!.snapshot);
+
+      // Snapshots identify themselves by instanceId + driver — this is
+      // what makes per-instance routing distinguishable downstream.
+      const personalSnapshot = yield* personal!.snapshot.getSnapshot;
+      expect(personalSnapshot.instanceId).toBe(personalId);
+      expect(personalSnapshot.driver).toBe(codexDriverKind);
+      expect(personalSnapshot.enabled).toBe(false);
+      expect(personalSnapshot.continuation?.groupKey).toBe(
+        "codex:home:/home/julius/.codex_personal",
+      );
+
+      const workSnapshot = yield* work!.snapshot.getSnapshot;
+      expect(workSnapshot.instanceId).toBe(workId);
+      expect(workSnapshot.driver).toBe(codexDriverKind);
+      expect(workSnapshot.enabled).toBe(false);
+      expect(workSnapshot.continuation?.groupKey).toBe("codex:home:/home/julius/.codex");
+
+      // Nothing goes to the unavailable bucket — both drivers are registered.
+      const unavailable = yield* registry.listUnavailable;
+      expect(unavailable).toEqual([]);
+    }).pipe(Effect.provide(testLayer)),
+  );
+
+  it.live(
+    "shadows instances whose driver is not registered in this build without failing boot",
+    () =>
+      Effect.gen(function* () {
+        const codexId = ProviderInstanceId.make("codex_main");
+        const ghostId = ProviderInstanceId.make("ghost_main");
+
+        const configMap: ProviderInstanceConfigMap = {
+          [codexId]: {
+            driver: ProviderDriverKind.make("codex"),
+            enabled: false,
+            config: makeCodexConfig({}),
+          },
+          [ghostId]: {
+            driver: ProviderDriverKind.make("ghostDriver"),
+            displayName: "A fork-only driver we don't ship",
+            enabled: false,
+            config: { arbitrary: "payload", preserved: true },
+          },
+        };
+
+        const { registry } = yield* makeProviderInstanceRegistry({
+          drivers: [CodexDriver],
+          configMap,
+        });
+
+        const instances = yield* registry.listInstances;
+        expect(instances).toHaveLength(1);
+        expect(instances[0]!.instanceId).toBe(codexId);
+
+        const unavailable = yield* registry.listUnavailable;
+        expect(unavailable).toHaveLength(1);
+        const ghost = unavailable[0]!;
+        expect(ghost.instanceId).toBe(ghostId);
+        expect(ghost.driver).toBe("ghostDriver");
+        expect(ghost.availability).toBe("unavailable");
+        expect(ghost.unavailableReason).toMatch(/ghostDriver/);
+      }).pipe(Effect.provide(testLayer)),
+  );
+});
+
+describe("ProviderInstanceRegistryLive — all drivers slice", () => {
+  // All four drivers need `NodeServices` (ChildProcessSpawner + FileSystem +
+  // Path). `OpenCodeDriver.create` additionally yields `OpenCodeRuntime`
+  // at construction time, so we wire `OpenCodeRuntimeLive` into the stack.
+  // `OpenCodeRuntimeLive` bundles its own `NetService.layer` via
+  // `Layer.provide`, so the only external requirement it still exposes is
+  // `ChildProcessSpawner` — resolved here by piping it through
+  // `provideMerge(NodeServices.layer)`.
+  //
+  // The nested `provideMerge`s read bottom-up: `NodeServices.layer`
+  // provides `OpenCodeRuntimeLive`'s deps while keeping its own outputs
+  // surfaced; that merged layer then provides `ServerConfig.layerTest`'s
+  // `FileSystem` dep while keeping everything else surfaced to the test.
+  const infraLayer = OpenCodeRuntimeLive.pipe(Layer.provideMerge(NodeServices.layer));
+  const testLayer = ServerConfig.layerTest(process.cwd(), {
+    prefix: "provider-instance-registry-all-drivers-test",
+  }).pipe(
+    Layer.provideMerge(infraLayer),
+    Layer.provideMerge(TestHttpClientLive),
+    Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+  );
+
+  it.live("boots one instance of every shipped driver from a single config map", () =>
+    Effect.gen(function* () {
+      const codexId = ProviderInstanceId.make("codex_default");
+      const claudeId = ProviderInstanceId.make("claude_default");
+      const cursorId = ProviderInstanceId.make("cursor_default");
+      const openCodeId = ProviderInstanceId.make("opencode_default");
+
+      const codexDriverKind = ProviderDriverKind.make("codex");
+      const claudeDriverKind = ProviderDriverKind.make("claudeAgent");
+      const cursorDriverKind = ProviderDriverKind.make("cursor");
+      const openCodeDriverKind = ProviderDriverKind.make("opencode");
+
+      const configMap: ProviderInstanceConfigMap = {
+        [codexId]: {
+          driver: codexDriverKind,
+          displayName: "Codex",
+          enabled: false,
+          config: makeCodexConfig({ homePath: "/home/julius/.codex" }),
+        },
+        [claudeId]: {
+          driver: claudeDriverKind,
+          displayName: "Claude",
+          enabled: false,
+          config: makeClaudeConfig({
+            homePath: "/home/julius/.claude-work",
+            launchArgs: "--verbose",
+          }),
+        },
+        [cursorId]: {
+          driver: cursorDriverKind,
+          displayName: "Cursor",
+          enabled: false,
+          config: makeCursorConfig({}),
+        },
+        [openCodeId]: {
+          driver: openCodeDriverKind,
+          displayName: "OpenCode",
+          enabled: false,
+          config: makeOpenCodeConfig({}),
+        },
+      };
+
+      const { registry } = yield* makeProviderInstanceRegistry({
+        drivers: [CodexDriver, ClaudeDriver, CursorDriver, OpenCodeDriver],
+        configMap,
+      });
+
+      // Every configured instance must materialize — none downgraded to a
+      // shadow snapshot, because every driver in the map is registered.
+      const unavailable = yield* registry.listUnavailable;
+      expect(unavailable).toEqual([]);
+
+      const instances = yield* registry.listInstances;
+      expect(instances).toHaveLength(4);
+      expect(instances.map((instance) => instance.instanceId).toSorted()).toEqual(
+        [codexId, claudeId, cursorId, openCodeId].toSorted(),
+      );
+
+      // Instance lookup by id resolves each instance to its own bundle —
+      // this is how rest-of-server routes turn/session calls in the new
+      // model. Each driver's bundle carries its advertised `driverKind`.
+      const codex = yield* registry.getInstance(codexId);
+      const claude = yield* registry.getInstance(claudeId);
+      const cursor = yield* registry.getInstance(cursorId);
+      const openCode = yield* registry.getInstance(openCodeId);
+      expect(codex?.driverKind).toBe(codexDriverKind);
+      expect(claude?.driverKind).toBe(claudeDriverKind);
+      expect(cursor?.driverKind).toBe(cursorDriverKind);
+      expect(openCode?.driverKind).toBe(openCodeDriverKind);
+      expect(codex?.displayName).toBe("Codex");
+      expect(claude?.displayName).toBe("Claude");
+      expect(cursor?.displayName).toBe("Cursor");
+      expect(openCode?.displayName).toBe("OpenCode");
+
+      // Every instance owns its own set of closures — no sharing across
+      // drivers. `adapter` / `textGeneration` / `snapshot` are all
+      // distinct references even when two instances happen to share a
+      // trait (e.g. Cursor + others all use a stub-or-real
+      // `textGeneration`; they must still be different object values).
+      const adapters = [codex!.adapter, claude!.adapter, cursor!.adapter, openCode!.adapter];
+      expect(new Set(adapters).size).toBe(adapters.length);
+      const textGenerations = [
+        codex!.textGeneration,
+        claude!.textGeneration,
+        cursor!.textGeneration,
+        openCode!.textGeneration,
+      ];
+      expect(new Set(textGenerations).size).toBe(textGenerations.length);
+      const snapshots = [codex!.snapshot, claude!.snapshot, cursor!.snapshot, openCode!.snapshot];
+      expect(new Set(snapshots).size).toBe(snapshots.length);
+
+      // Snapshots identify themselves by `instanceId` + `driver` so
+      // downstream aggregation in `ProviderRegistry` can tell instances
+      // apart even when two share a driver. With `enabled: false`, the
+      // check short-circuits and we get a disabled/pending snapshot back
+      // — that's enough signal to validate the stamping wrapper without
+      // spawning real binaries.
+      const codexSnapshot = yield* codex!.snapshot.getSnapshot;
+      expect(codexSnapshot.instanceId).toBe(codexId);
+      expect(codexSnapshot.driver).toBe(codexDriverKind);
+      expect(codexSnapshot.enabled).toBe(false);
+      expect(codexSnapshot.continuation?.groupKey).toBe("codex:home:/home/julius/.codex");
+
+      const claudeSnapshot = yield* claude!.snapshot.getSnapshot;
+      expect(claudeSnapshot.instanceId).toBe(claudeId);
+      expect(claudeSnapshot.driver).toBe(claudeDriverKind);
+      expect(claudeSnapshot.enabled).toBe(false);
+      expect(claudeSnapshot.continuation?.groupKey).toBe("claude:home:/home/julius/.claude-work");
+
+      const cursorSnapshot = yield* cursor!.snapshot.getSnapshot;
+      expect(cursorSnapshot.instanceId).toBe(cursorId);
+      expect(cursorSnapshot.driver).toBe(cursorDriverKind);
+      expect(cursorSnapshot.enabled).toBe(false);
+      expect(cursorSnapshot.continuation?.groupKey).toBe(
+        `${cursorDriverKind}:instance:${cursorId}`,
+      );
+
+      const openCodeSnapshot = yield* openCode!.snapshot.getSnapshot;
+      expect(openCodeSnapshot.instanceId).toBe(openCodeId);
+      expect(openCodeSnapshot.driver).toBe(openCodeDriverKind);
+      expect(openCodeSnapshot.enabled).toBe(false);
+      expect(openCodeSnapshot.continuation?.groupKey).toBe(
+        `${openCodeDriverKind}:instance:${openCodeId}`,
+      );
+    }).pipe(Effect.provide(testLayer)),
+  );
+});
diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.ts
new file mode 100644
index 00000000000..b51dc67793e
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.ts
@@ -0,0 +1,443 @@
+/**
+ * ProviderInstanceRegistryLive — runtime implementation of
+ * `ProviderInstanceRegistry` plus its sibling mutator.
+ *
+ * Materializes every entry in a `ProviderInstanceConfigMap`:
+ *
+ *   - When the entry's `driver` matches a registered driver, the registry
+ *     decodes the opaque `config` envelope through `driver.configSchema`
+ *     and calls `driver.create()` inside a fresh child scope. The
+ *     resulting `ProviderInstance` is stored keyed by instance id,
+ *     alongside its scope so the entry can be torn down independently.
+ *   - When the entry's `driver` is unknown to this build (fork, rollback,
+ *     in-flight PR branch), the registry emits an `"unavailable"` shadow
+ *     `ServerProvider` snapshot instead of failing. This is what makes
+ *     downgrades and fork-hopping safe per the
+ *     `forward/backward compatibility invariant` in
+ *     `packages/contracts/src/providerInstance.ts`.
+ *   - When the entry's config fails schema decode, the registry logs and
+ *     emits a shadow snapshot with the schema detail — same bucket as an
+ *     unknown driver.
+ *
+ * Unlike the pre-Slice-D layer, the registry now holds mutable state
+ * (`Ref`s + `PubSub`) and exposes an internal mutator
+ * (`ProviderInstanceRegistryMutator`) whose `reconcile` method diffs a
+ * fresh config map against the live state, tearing down removed instances
+ * and building new ones without disturbing unaffected instances.
+ *
+ * Every live instance runs inside its own child `Scope`. The registry's
+ * own scope owns all child scopes via finalizers, so closing the registry
+ * tears every instance down in reverse order; closing a single instance
+ * (via `reconcile` removing it) leaves the rest untouched.
+ *
+ * @module provider/Layers/ProviderInstanceRegistryLive
+ */
+import {
+  defaultInstanceIdForDriver,
+  ProviderInstanceId,
+  type ProviderInstanceConfig,
+  type ProviderInstanceConfigMap,
+  type ProviderDriverKind,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+
+import { buildUnavailableProviderSnapshot } from "../unavailableProviderSnapshot.ts";
+import {
+  ProviderInstanceRegistry,
+  type ProviderInstanceRegistryShape,
+} from "../Services/ProviderInstanceRegistry.ts";
+import {
+  ProviderInstanceRegistryMutator,
+  type ProviderInstanceRegistryMutatorShape,
+} from "../Services/ProviderInstanceRegistryMutator.ts";
+import type { AnyProviderDriver, ProviderInstance } from "../ProviderDriver.ts";
+
+/**
+ * Live registry entry: the materialized `ProviderInstance` + the fresh
+ * child scope its `create` effect ran in + the original `entry` envelope
+ * so `reconcile` can cheaply detect "no-op" updates.
+ */
+interface LiveEntry {
+  readonly instance: ProviderInstance;
+  readonly scope: Scope.Closeable;
+  readonly entry: ProviderInstanceConfig;
+}
+
+/**
+ * Internal state shared between the public registry service and the
+ * mutator service. Both services are thin shells around these refs.
+ */
+interface RegistryState {
+  readonly entries: Ref.Ref<ReadonlyMap<ProviderInstanceId, LiveEntry>>;
+  readonly unavailable: Ref.Ref<ReadonlyMap<ProviderInstanceId, ServerProvider>>;
+  readonly changes: PubSub.PubSub<void>;
+}
+
+/**
+ * Structural equality on `ProviderInstanceConfig` envelopes. Used by
+ * `reconcile` to skip rebuilds when settings arrive unchanged. Config
+ * payloads are opaque `unknown` at the envelope layer; `Equal.equals`
+ * falls back to structural equality for plain records, which matches how
+ * the schema decode output is constructed.
+ */
+const entryEqual = (a: ProviderInstanceConfig, b: ProviderInstanceConfig): boolean =>
+  Equal.equals(a, b);
+
+const decodedConfigEnabled = (config: unknown): boolean | undefined => {
+  if (!config || typeof config !== "object" || globalThis.Array.isArray(config)) {
+    return undefined;
+  }
+  const enabled = (config as { readonly enabled?: unknown }).enabled;
+  return typeof enabled === "boolean" ? enabled : undefined;
+};
+
+/**
+ * Build one live entry from a raw config envelope. Returns either a
+ * `LiveEntry` plus undefined unavailable shadow, or a shadow snapshot and
+ * undefined entry — callers dispatch to the appropriate Ref bucket.
+ */
+const buildEntry = <R>(input: {
+  readonly driversById: ReadonlyMap<ProviderDriverKind, AnyProviderDriver<R>>;
+  readonly parentScope: Scope.Scope;
+  readonly instanceId: ProviderInstanceId;
+  readonly rawInstanceId: string;
+  readonly entry: ProviderInstanceConfig;
+}): Effect.Effect<
+  | { readonly kind: "live"; readonly live: LiveEntry }
+  | { readonly kind: "unavailable"; readonly snapshot: ServerProvider },
+  never,
+  R
+> =>
+  Effect.gen(function* () {
+    const { driversById, parentScope, instanceId, rawInstanceId, entry } = input;
+    const driver = driversById.get(entry.driver);
+    if (!driver) {
+      return {
+        kind: "unavailable" as const,
+        snapshot: yield* buildUnavailableProviderSnapshot({
+          driverKind: entry.driver,
+          instanceId,
+          displayName: entry.displayName,
+          accentColor: entry.accentColor,
+          reason: `Driver '${entry.driver}' is not registered in this build.`,
+        }),
+      };
+    }
+
+    const decoder = Schema.decodeUnknownEffect(driver.configSchema);
+    const decodeResult = yield* decoder(entry.config ?? driver.defaultConfig()).pipe(Effect.result);
+    if (decodeResult._tag === "Failure") {
+      const issue = decodeResult.failure;
+      const detail = issue.message ?? String(issue);
+      yield* Effect.logError("Failed to decode provider instance config", {
+        instanceId: rawInstanceId,
+        driver: entry.driver,
+        detail,
+      });
+      return {
+        kind: "unavailable" as const,
+        snapshot: yield* buildUnavailableProviderSnapshot({
+          driverKind: entry.driver,
+          instanceId,
+          displayName: entry.displayName,
+          accentColor: entry.accentColor,
+          reason: `Invalid config for instance '${rawInstanceId}': ${detail}`,
+        }),
+      };
+    }
+
+    const typedConfig = decodeResult.success;
+    const childScope = yield* Scope.make();
+    // Attach the child scope to the registry's parent scope: if the
+    // registry scope closes, each surviving instance's child scope is
+    // closed through this finalizer. `reconcile` manually closes the
+    // child scope on remove/replace; subsequent close via the parent's
+    // finalizer is a no-op because `Scope.close` is idempotent.
+    yield* Scope.addFinalizer(parentScope, Scope.close(childScope, Exit.void).pipe(Effect.ignore));
+
+    const createResult = yield* driver
+      .create({
+        instanceId,
+        displayName: entry.displayName,
+        accentColor: entry.accentColor,
+        environment: entry.environment ?? [],
+        enabled: entry.enabled ?? decodedConfigEnabled(typedConfig) ?? true,
+        config: typedConfig,
+      })
+      .pipe(Effect.provideService(Scope.Scope, childScope), Effect.result);
+    if (createResult._tag === "Failure") {
+      yield* Effect.logError("Failed to create provider instance", {
+        instanceId: rawInstanceId,
+        driver: entry.driver,
+        detail: createResult.failure.detail,
+      });
+      yield* Scope.close(childScope, Exit.void).pipe(Effect.ignore);
+      return {
+        kind: "unavailable" as const,
+        snapshot: yield* buildUnavailableProviderSnapshot({
+          driverKind: entry.driver,
+          instanceId,
+          displayName: entry.displayName,
+          accentColor: entry.accentColor,
+          reason: `Driver '${entry.driver}' failed to create instance: ${createResult.failure.detail}`,
+        }),
+      };
+    }
+
+    return {
+      kind: "live" as const,
+      live: {
+        instance: createResult.success,
+        scope: childScope,
+        entry,
+      },
+    };
+  });
+
+/**
+ * Reconcile-only implementation of the mutator. Exposed to the hydration
+ * layer; never called directly by the rest of the server.
+ */
+const makeReconcile = <R>(input: {
+  readonly state: RegistryState;
+  readonly driversById: ReadonlyMap<ProviderDriverKind, AnyProviderDriver<R>>;
+  readonly parentScope: Scope.Scope;
+}): ((configMap: ProviderInstanceConfigMap) => Effect.Effect<void, never, R>) => {
+  const { state, driversById, parentScope } = input;
+  return (configMap: ProviderInstanceConfigMap) =>
+    Effect.gen(function* () {
+      const previousEntries = yield* Ref.get(state.entries);
+      const previousUnavailable = yield* Ref.get(state.unavailable);
+      const nextRaw = Object.entries(configMap);
+      const nextKeys = new Set<ProviderInstanceId>(
+        nextRaw.map(([raw]) => ProviderInstanceId.make(raw)),
+      );
+
+      // 1. Close scopes for instances that disappeared or whose config
+      //    changed. Do this BEFORE creating replacements so ids map 1-to-1
+      //    to live scopes at all times.
+      const removedIds: Array<ProviderInstanceId> = [];
+      const replacedIds = new Set<ProviderInstanceId>();
+      for (const [instanceId, live] of previousEntries) {
+        if (!nextKeys.has(instanceId)) {
+          removedIds.push(instanceId);
+          continue;
+        }
+        const nextEntry = configMap[instanceId];
+        if (nextEntry !== undefined && !entryEqual(live.entry, nextEntry)) {
+          replacedIds.add(instanceId);
+        }
+      }
+      for (const id of [...removedIds, ...replacedIds]) {
+        const live = previousEntries.get(id);
+        if (live) {
+          yield* Scope.close(live.scope, Exit.void).pipe(Effect.ignore);
+        }
+      }
+
+      // 2. Build additions and replacements. Walk `nextRaw` so the final
+      //    entry order follows settings-author order.
+      const builtEntries = new Map<ProviderInstanceId, LiveEntry>();
+      const builtUnavailable = new Map<ProviderInstanceId, ServerProvider>();
+      let orderChanged = false;
+      const previousOrder = [...previousEntries.keys()];
+      const nextOrder: Array<ProviderInstanceId> = [];
+
+      for (const [rawInstanceId, entry] of nextRaw) {
+        const instanceId = ProviderInstanceId.make(rawInstanceId);
+        nextOrder.push(instanceId);
+
+        const existing = previousEntries.get(instanceId);
+        if (existing !== undefined && !replacedIds.has(instanceId)) {
+          // No-op update: keep the existing live entry and scope.
+          builtEntries.set(instanceId, existing);
+          continue;
+        }
+
+        const result = yield* buildEntry({
+          driversById,
+          parentScope,
+          instanceId,
+          rawInstanceId,
+          entry,
+        });
+        if (result.kind === "live") {
+          builtEntries.set(instanceId, result.live);
+        } else {
+          builtUnavailable.set(instanceId, result.snapshot);
+        }
+      }
+
+      if (previousOrder.length === nextOrder.length) {
+        for (let i = 0; i < previousOrder.length; i++) {
+          if (previousOrder[i] !== nextOrder[i]) {
+            orderChanged = true;
+            break;
+          }
+        }
+      } else {
+        orderChanged = true;
+      }
+
+      const entriesChanged =
+        orderChanged ||
+        removedIds.length > 0 ||
+        replacedIds.size > 0 ||
+        builtEntries.size !== previousEntries.size;
+      const unavailableChanged =
+        builtUnavailable.size !== previousUnavailable.size ||
+        [...builtUnavailable].some(([id, snapshot]) => {
+          const prev = previousUnavailable.get(id);
+          return prev === undefined || !Equal.equals(prev, snapshot);
+        }) ||
+        [...previousUnavailable].some(([id]) => !builtUnavailable.has(id));
+
+      yield* Ref.set(state.entries, builtEntries);
+      yield* Ref.set(state.unavailable, builtUnavailable);
+
+      if (entriesChanged || unavailableChanged) {
+        yield* PubSub.publish(state.changes, undefined);
+      }
+    });
+};
+
+/**
+ * Build the registry's runtime state from a concrete configMap. Returns a
+ * record containing:
+ *
+ *   - `registry`: the read-only `ProviderInstanceRegistryShape` to expose
+ *     under `ProviderInstanceRegistry`.
+ *   - `mutator`: the `ProviderInstanceRegistryMutatorShape` to expose
+ *     under `ProviderInstanceRegistryMutator`.
+ *   - `reconcile`: the raw reconcile function, provided for convenience so
+ *     boot-time layers can hydrate an initial map before publishing the
+ *     services.
+ *
+ * The scope that this effect runs in owns every per-instance child scope
+ * created during `reconcile`. Closing that scope closes every live
+ * instance.
+ */
+export const makeProviderInstanceRegistry = <R>(input: {
+  readonly drivers: ReadonlyArray<AnyProviderDriver<R>>;
+  readonly configMap: ProviderInstanceConfigMap;
+}): Effect.Effect<
+  {
+    readonly registry: ProviderInstanceRegistryShape;
+    readonly mutator: ProviderInstanceRegistryMutatorShape;
+  },
+  never,
+  R | Scope.Scope
+> =>
+  Effect.gen(function* () {
+    const driversById = new Map<ProviderDriverKind, AnyProviderDriver<R>>(
+      input.drivers.map((driver) => [driver.driverKind, driver]),
+    );
+
+    // Capture the enclosing scope so per-instance child scopes can be
+    // attached to it at `reconcile` time. Without this, `reconcile`
+    // called later (e.g. from the hydration layer) would attach child
+    // scopes to the *caller's* scope instead of the registry's.
+    const parentScope = yield* Scope.Scope;
+
+    // Capture the driver R context at construction time so `reconcile`
+    // can be invoked later without re-providing driver dependencies.
+    // The service tag's declared `reconcile: Effect<void>` hides R from
+    // consumers — we materialize that here.
+    const driverContext = yield* Effect.context<R>();
+
+    const entries = yield* Ref.make<ReadonlyMap<ProviderInstanceId, LiveEntry>>(new Map());
+    const unavailable = yield* Ref.make<ReadonlyMap<ProviderInstanceId, ServerProvider>>(new Map());
+    const changes = yield* PubSub.unbounded<void>();
+    yield* Effect.addFinalizer(() => PubSub.shutdown(changes));
+
+    const state: RegistryState = { entries, unavailable, changes };
+    const reconcileWithR = makeReconcile({ state, driversById, parentScope });
+    const reconcile: ProviderInstanceRegistryMutatorShape["reconcile"] = (configMap) =>
+      reconcileWithR(configMap).pipe(Effect.provideContext(driverContext));
+
+    // Hydrate the initial configMap synchronously so callers can read
+    // `listInstances` immediately after this effect completes.
+    yield* reconcile(input.configMap);
+
+    const registry: ProviderInstanceRegistryShape = {
+      getInstance: (id) => Ref.get(entries).pipe(Effect.map((map) => map.get(id)?.instance)),
+      listInstances: Ref.get(entries).pipe(
+        Effect.map(
+          (map) =>
+            Array.from(map.values(), (live) => live.instance) as ReadonlyArray<ProviderInstance>,
+        ),
+      ),
+      listUnavailable: Ref.get(unavailable).pipe(
+        Effect.map((map) => Array.from(map.values()) as ReadonlyArray<ServerProvider>),
+      ),
+      // Getters: each read constructs a fresh Stream / Effect descriptor
+      // so multiple consumers don't share a single already-started
+      // Channel or subscription. Matches the pattern `ProviderRegistry`
+      // uses for its own `streamChanges`.
+      get streamChanges() {
+        return Stream.fromPubSub(changes);
+      },
+      // Synchronous subscribe — callers that need to consume changes
+      // from a forked fibre must acquire the subscription in their own
+      // fibre first (via `yield* registry.subscribeChanges`) and only
+      // then fork a consumer loop on `Stream.fromSubscription(...)` /
+      // `PubSub.take(...)`. See the shape docs for the race this avoids.
+      get subscribeChanges() {
+        return PubSub.subscribe(changes);
+      },
+    };
+
+    const mutator: ProviderInstanceRegistryMutatorShape = { reconcile };
+
+    return { registry, mutator };
+  });
+
+/**
+ * Assemble a `ProviderInstanceRegistry` Layer bound to a fixed set of
+ * drivers and a pre-resolved `ProviderInstanceConfigMap`. Used by tests
+ * that want explicit control over the registry's source-of-truth without
+ * wiring up the settings watcher.
+ *
+ * Only exposes the public registry tag — hot-reload consumers should use
+ * `ProviderInstanceRegistryMutableLayer` (below) or the hydration layer.
+ */
+export const ProviderInstanceRegistryLayer = <R>(input: {
+  readonly drivers: ReadonlyArray<AnyProviderDriver<R>>;
+  readonly configMap: ProviderInstanceConfigMap;
+}): Layer.Layer<ProviderInstanceRegistry, never, R> =>
+  Layer.effect(
+    ProviderInstanceRegistry,
+    makeProviderInstanceRegistry(input).pipe(Effect.map((built) => built.registry)),
+  ) as Layer.Layer<ProviderInstanceRegistry, never, R>;
+
+/**
+ * Layer variant that also exposes the mutator tag. Consumed by
+ * `ProviderInstanceRegistryHydrationLive` to reconcile on settings
+ * changes. Tests that exercise the mutator directly can pair this Layer
+ * with a test-local `ServerSettingsService`.
+ */
+export const ProviderInstanceRegistryMutableLayer = <R>(input: {
+  readonly drivers: ReadonlyArray<AnyProviderDriver<R>>;
+  readonly configMap: ProviderInstanceConfigMap;
+}): Layer.Layer<ProviderInstanceRegistry | ProviderInstanceRegistryMutator, never, R> =>
+  Layer.effectContext(
+    makeProviderInstanceRegistry(input).pipe(
+      Effect.map(({ registry, mutator }) =>
+        Context.make(ProviderInstanceRegistry, registry).pipe(
+          Context.add(ProviderInstanceRegistryMutator, mutator),
+        ),
+      ),
+    ),
+  ) as Layer.Layer<ProviderInstanceRegistry | ProviderInstanceRegistryMutator, never, R>;
+
+export { defaultInstanceIdForDriver };
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index 9c12048e45e..fb6eb3b443d 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -1,43 +1,122 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { describe, it, assert } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+import * as CodexErrors from "effect-codex-app-server/errors";
 import {
-  Effect,
-  Exit,
-  FileSystem,
-  Layer,
-  Path,
-  PubSub,
-  Ref,
-  Schema,
-  Scope,
-  Sink,
-  Stream,
-} from "effect";
-import {
+  ClaudeSettings,
+  CodexSettings,
   DEFAULT_SERVER_SETTINGS,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ServerSettings,
   type ServerProvider,
+  type ServerProviderSlashCommand,
   type ServerSettings as ContractServerSettings,
 } from "@t3tools/contracts";
 import * as PlatformError from "effect/PlatformError";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { deepMerge } from "@t3tools/shared/Struct";
-
+import { createModelCapabilities } from "@t3tools/shared/model";
+import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
+
+import { checkCodexProviderStatus, type CodexAppServerProviderSnapshot } from "./CodexProvider.ts";
+import { checkClaudeProviderStatus } from "./ClaudeProvider.ts";
+import { OpenCodeRuntimeLive } from "../opencodeRuntime.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "./ProviderEventLoggers.ts";
+import { ProviderInstanceRegistryHydrationLive } from "./ProviderInstanceRegistryHydration.ts";
 import {
-  checkCodexProviderStatus,
-  hasCustomModelProvider,
-  parseAuthStatusFromOutput,
-  readCodexConfigModelProvider,
-} from "./CodexProvider";
-import { checkClaudeProviderStatus, parseClaudeAuthStatusFromOutput } from "./ClaudeProvider";
-import { haveProvidersChanged, ProviderRegistryLive } from "./ProviderRegistry";
-import { ServerSettingsService, type ServerSettingsShape } from "../../serverSettings";
-import { ProviderRegistry } from "../Services/ProviderRegistry";
+  haveProvidersChanged,
+  mergeProviderSnapshot,
+  mergeProviderSnapshots,
+  ProviderRegistryLive,
+  selectProvidersByKind,
+} from "./ProviderRegistry.ts";
+import { ServerConfig } from "../../config.ts";
+import { ServerSettingsService, type ServerSettingsShape } from "../../serverSettings.ts";
+import { readProviderStatusCache, resolveProviderStatusCachePath } from "../providerStatusCache.ts";
+import type { ProviderInstance } from "../ProviderDriver.ts";
+import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
+import { ProviderRegistry } from "../Services/ProviderRegistry.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
+const decodeServerSettings = Schema.decodeSync(ServerSettings);
+const encodeServerSettings = Schema.encodeSync(ServerSettings);
+const encodedDefaultServerSettings = encodeServerSettings(DEFAULT_SERVER_SETTINGS);
+
+const defaultClaudeSettings: ClaudeSettings = Schema.decodeSync(ClaudeSettings)({});
+const defaultCodexSettings: CodexSettings = Schema.decodeSync(CodexSettings)({});
+const disabledCodexSettings: CodexSettings = Schema.decodeSync(CodexSettings)({
+  enabled: false,
+});
+
+process.env.T3CODE_CURSOR_ENABLED = "1";
 
 // ── Test helpers ────────────────────────────────────────────────────
 
 const encoder = new TextEncoder();
 
+const TestHttpClientLive = Layer.succeed(
+  HttpClient.HttpClient,
+  HttpClient.make((request) =>
+    Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ version: "0.0.0" }))),
+  ),
+);
+
+function selectDescriptor(
+  id: string,
+  label: string,
+  options: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>,
+) {
+  return {
+    id,
+    label,
+    type: "select" as const,
+    options: [...options],
+    ...(options.find((option) => option.isDefault)?.id
+      ? { currentValue: options.find((option) => option.isDefault)?.id }
+      : {}),
+  };
+}
+
+function booleanDescriptor(id: string, label: string) {
+  return {
+    id,
+    label,
+    type: "boolean" as const,
+  };
+}
+
+type TestClaudeCapabilities = {
+  readonly email: string | undefined;
+  readonly subscriptionType: string | undefined;
+  readonly tokenSource: string | undefined;
+  readonly slashCommands: ReadonlyArray<ServerProviderSlashCommand>;
+};
+
+function claudeCapabilities(overrides: Partial<TestClaudeCapabilities> = {}) {
+  return () =>
+    Effect.succeed({
+      email: undefined,
+      subscriptionType: undefined,
+      tokenSource: undefined,
+      slashCommands: [],
+      ...overrides,
+    });
+}
+
+const noClaudeCapabilities = () =>
+  Effect.sync(() => undefined as TestClaudeCapabilities | undefined);
+
 function mockHandle(result: { stdout: string; stderr: string; code: number }) {
   return ChildProcessSpawner.makeHandle({
     pid: ChildProcessSpawner.ProcessId(1),
@@ -55,7 +134,11 @@ function mockHandle(result: { stdout: string; stderr: string; code: number }) {
 }
 
 function mockSpawnerLayer(
-  handler: (args: ReadonlyArray<string>) => { stdout: string; stderr: string; code: number },
+  handler: (args: ReadonlyArray<string>) => {
+    stdout: string;
+    stderr: string;
+    code: number;
+  },
 ) {
   return Layer.succeed(
     ChildProcessSpawner.ChildProcessSpawner,
@@ -66,6 +149,33 @@ function mockSpawnerLayer(
   );
 }
 
+function recordingMockSpawnerLayer(
+  handler: (args: ReadonlyArray<string>) => {
+    stdout: string;
+    stderr: string;
+    code: number;
+  },
+) {
+  const commands: Array<{
+    readonly args: ReadonlyArray<string>;
+    readonly env: NodeJS.ProcessEnv | undefined;
+  }> = [];
+  const layer = Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make((command) => {
+      const cmd = command as unknown as {
+        args: ReadonlyArray<string>;
+        options?: {
+          readonly env?: NodeJS.ProcessEnv;
+        };
+      };
+      commands.push({ args: cmd.args, env: cmd.options?.env });
+      return Effect.succeed(mockHandle(handler(cmd.args)));
+    }),
+  );
+  return { layer, commands };
+}
+
 function mockCommandSpawnerLayer(
   handler: (
     command: string,
@@ -75,7 +185,10 @@ function mockCommandSpawnerLayer(
   return Layer.succeed(
     ChildProcessSpawner.ChildProcessSpawner,
     ChildProcessSpawner.make((command) => {
-      const cmd = command as unknown as { command: string; args: ReadonlyArray<string> };
+      const cmd = command as unknown as {
+        command: string;
+        args: ReadonlyArray<string>;
+      };
       return Effect.succeed(mockHandle(handler(cmd.command, cmd.args)));
     }),
   );
@@ -97,6 +210,67 @@ function failingSpawnerLayer(description: string) {
   );
 }
 
+function hangingScopedSpawnerLayer(killCalls: Ref.Ref<number>) {
+  return Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make(() =>
+      Effect.gen(function* () {
+        const handle = ChildProcessSpawner.makeHandle({
+          pid: ChildProcessSpawner.ProcessId(1),
+          exitCode: Effect.never,
+          isRunning: Effect.succeed(true),
+          kill: () => Ref.update(killCalls, (current) => current + 1),
+          unref: Effect.succeed(Effect.void),
+          stdin: Sink.drain,
+          stdout: Stream.never,
+          stderr: Stream.never,
+          all: Stream.never,
+          getInputFd: () => Sink.drain,
+          getOutputFd: () => Stream.empty,
+        });
+        yield* Effect.addFinalizer(() => handle.kill().pipe(Effect.ignore));
+        return handle;
+      }),
+    ),
+  );
+}
+
+const codexModelCapabilities = createModelCapabilities({
+  optionDescriptors: [
+    selectDescriptor("reasoningEffort", "Reasoning", [
+      { id: "high", label: "High", isDefault: true },
+      { id: "low", label: "Low" },
+    ]),
+    booleanDescriptor("fastMode", "Fast Mode"),
+  ],
+}) satisfies NonNullable<ServerProvider["models"][number]["capabilities"]>;
+
+function makeCodexProbeSnapshot(
+  input: Partial<CodexAppServerProviderSnapshot> = {},
+): CodexAppServerProviderSnapshot {
+  return {
+    version: "1.0.0",
+    account: {
+      account: {
+        type: "chatgpt",
+        email: "test@example.com",
+        planType: "pro",
+      },
+      requiresOpenaiAuth: false,
+    },
+    models: [
+      {
+        slug: "gpt-live-codex",
+        name: "GPT Live Codex",
+        isCustom: false,
+        capabilities: codexModelCapabilities,
+      },
+    ],
+    skills: [],
+    ...input,
+  };
+}
+
 function makeMutableServerSettingsService(
   initial: ContractServerSettings = DEFAULT_SERVER_SETTINGS,
 ) {
@@ -111,7 +285,8 @@ function makeMutableServerSettingsService(
       updateSettings: (patch) =>
         Effect.gen(function* () {
           const current = yield* Ref.get(settingsRef);
-          const next = Schema.decodeSync(ServerSettings)(deepMerge(current, patch));
+          const next = applyServerSettingsPatch(current, patch);
+          encodeServerSettings(next);
           yield* Ref.set(settingsRef, next);
           yield* PubSub.publish(changes, next);
           return next;
@@ -123,126 +298,42 @@ function makeMutableServerSettingsService(
   });
 }
 
-/**
- * Create a temporary CODEX_HOME scoped to the current Effect test.
- * Cleanup is registered in the test scope rather than via Vitest hooks.
- */
-function withTempCodexHome(configContent?: string) {
-  return Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const tmpDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-test-codex-" });
-
-    yield* Effect.acquireRelease(
-      Effect.sync(() => {
-        const originalCodexHome = process.env.CODEX_HOME;
-        process.env.CODEX_HOME = tmpDir;
-        return originalCodexHome;
-      }),
-      (originalCodexHome) =>
-        Effect.sync(() => {
-          if (originalCodexHome !== undefined) {
-            process.env.CODEX_HOME = originalCodexHome;
-          } else {
-            delete process.env.CODEX_HOME;
-          }
-        }),
-    );
-
-    if (configContent !== undefined) {
-      yield* fileSystem.writeFileString(path.join(tmpDir, "config.toml"), configContent);
-    }
-
-    return { tmpDir } as const;
-  });
-}
-
-it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
+it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest(), TestHttpClientLive))(
   "ProviderRegistry",
   (it) => {
-    // ── checkCodexProviderStatus tests ────────────────────────────────
-    //
-    // These tests control CODEX_HOME to ensure the custom-provider detection
-    // in hasCustomModelProvider() does not interfere with the auth-probe
-    // path being tested.
-
     describe("checkCodexProviderStatus", () => {
-      it.effect("returns ready when codex is installed and authenticated", () =>
-        Effect.gen(function* () {
-          // Point CODEX_HOME at an empty tmp dir (no config.toml) so the
-          // default code path (OpenAI provider, auth probe runs) is exercised.
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus();
-          assert.strictEqual(status.provider, "codex");
-          assert.strictEqual(status.status, "ready");
-          assert.strictEqual(status.installed, true);
-          assert.strictEqual(status.auth.status, "authenticated");
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") return { stdout: "Logged in\n", stderr: "", code: 0 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
-      );
-
-      it.effect("returns the codex plan type in auth and keeps spark for supported plans", () =>
+      it.effect("uses the app-server account and model list for provider status", () =>
         Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus(() =>
-            Effect.succeed({
-              type: "chatgpt" as const,
-              planType: "pro" as const,
-              sparkEnabled: true,
-            }),
+          const status = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
+            Effect.succeed(
+              makeCodexProbeSnapshot({
+                skills: [
+                  {
+                    name: "github:gh-fix-ci",
+                    path: "/Users/test/.codex/skills/gh-fix-ci/SKILL.md",
+                    enabled: true,
+                    displayName: "CI Debug",
+                    shortDescription: "Debug failing GitHub Actions checks",
+                  },
+                ],
+              }),
+            ),
           );
-
-          assert.strictEqual(status.provider, "codex");
           assert.strictEqual(status.status, "ready");
+          assert.strictEqual(status.installed, true);
+          assert.strictEqual(status.version, "1.0.0");
           assert.strictEqual(status.auth.status, "authenticated");
-          assert.strictEqual(status.auth.type, "pro");
-          assert.strictEqual(status.auth.label, "ChatGPT Pro Subscription");
-          assert.deepStrictEqual(
-            status.models.some((model) => model.slug === "gpt-5.3-codex-spark"),
-            true,
-          );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") return { stdout: "Logged in\n", stderr: "", code: 0 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
-      );
-
-      it.effect("includes probed codex skills in the provider snapshot", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus(
-            () =>
-              Effect.succeed({
-                type: "chatgpt" as const,
-                planType: "pro" as const,
-                sparkEnabled: true,
-              }),
-            () =>
-              Effect.succeed([
-                {
-                  name: "github:gh-fix-ci",
-                  path: "/Users/test/.codex/skills/gh-fix-ci/SKILL.md",
-                  enabled: true,
-                  displayName: "CI Debug",
-                  shortDescription: "Debug failing GitHub Actions checks",
-                },
-              ]),
-          );
-
+          assert.strictEqual(status.auth.type, "chatgpt");
+          assert.strictEqual(status.auth.label, "ChatGPT Pro 20x Subscription");
+          assert.strictEqual(status.auth.email, "test@example.com");
+          assert.deepStrictEqual(status.models, [
+            {
+              slug: "gpt-live-codex",
+              name: "GPT Live Codex",
+              isCustom: false,
+              capabilities: codexModelCapabilities,
+            },
+          ]);
           assert.deepStrictEqual(status.skills, [
             {
               name: "github:gh-fix-ci",
@@ -252,173 +343,101 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
               shortDescription: "Debug failing GitHub Actions checks",
             },
           ]);
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") return { stdout: "Logged in\n", stderr: "", code: 0 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
+        }),
       );
 
-      it.effect("hides spark from codex models for unsupported chatgpt plans", () =>
+      it.effect("returns unauthenticated when app-server requires OpenAI auth", () =>
         Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus(() =>
-            Effect.succeed({
-              type: "chatgpt" as const,
-              planType: "plus" as const,
-              sparkEnabled: false,
-            }),
+          const status = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
+            Effect.succeed(
+              makeCodexProbeSnapshot({
+                account: {
+                  account: null,
+                  requiresOpenaiAuth: true,
+                },
+              }),
+            ),
           );
 
-          assert.strictEqual(status.provider, "codex");
-          assert.strictEqual(status.status, "ready");
-          assert.strictEqual(status.auth.status, "authenticated");
-          assert.strictEqual(status.auth.type, "plus");
-          assert.strictEqual(status.auth.label, "ChatGPT Plus Subscription");
-          assert.deepStrictEqual(
-            status.models.some((model) => model.slug === "gpt-5.3-codex-spark"),
-            false,
+          assert.strictEqual(status.status, "error");
+          assert.strictEqual(status.auth.status, "unauthenticated");
+          assert.strictEqual(
+            status.message,
+            "Codex CLI is not authenticated. Run `codex login` and try again.",
           );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") return { stdout: "Logged in\n", stderr: "", code: 0 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
+        }),
       );
 
-      it.effect("hides spark from codex models for non-pro chatgpt subscriptions", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus(() =>
-            Effect.succeed({
-              type: "chatgpt" as const,
-              planType: "team" as const,
-              sparkEnabled: false,
-            }),
-          );
+      it.effect(
+        "returns ready with unknown auth when app-server does not require OpenAI auth",
+        () =>
+          Effect.gen(function* () {
+            const status = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
+              Effect.succeed(
+                makeCodexProbeSnapshot({
+                  account: {
+                    account: null,
+                    requiresOpenaiAuth: false,
+                  },
+                }),
+              ),
+            );
 
-          assert.strictEqual(status.provider, "codex");
-          assert.strictEqual(status.auth.type, "team");
-          assert.strictEqual(status.auth.label, "ChatGPT Team Subscription");
-          assert.deepStrictEqual(
-            status.models.some((model) => model.slug === "gpt-5.3-codex-spark"),
-            false,
-          );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") return { stdout: "Logged in\n", stderr: "", code: 0 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
+            assert.strictEqual(status.status, "ready");
+            assert.strictEqual(status.auth.status, "unknown");
+          }),
       );
 
       it.effect("returns an api key label for codex api key auth", () =>
         Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus(() =>
-            Effect.succeed({
-              type: "apiKey" as const,
-              planType: null,
-              sparkEnabled: false,
-            }),
+          const status = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
+            Effect.succeed(
+              makeCodexProbeSnapshot({
+                account: {
+                  account: { type: "apiKey" },
+                  requiresOpenaiAuth: false,
+                },
+              }),
+            ),
           );
 
-          assert.strictEqual(status.provider, "codex");
           assert.strictEqual(status.status, "ready");
           assert.strictEqual(status.auth.status, "authenticated");
           assert.strictEqual(status.auth.type, "apiKey");
           assert.strictEqual(status.auth.label, "OpenAI API Key");
-          assert.deepStrictEqual(
-            status.models.some((model) => model.slug === "gpt-5.3-codex-spark"),
-            false,
-          );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") return { stdout: "Logged in\n", stderr: "", code: 0 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
+        }),
       );
 
-      it.effect.skipIf(process.platform === "win32")(
-        "inherits PATH when launching the codex probe with a CODEX_HOME override",
-        () =>
-          Effect.gen(function* () {
-            const fileSystem = yield* FileSystem.FileSystem;
-            const path = yield* Path.Path;
-            const binDir = yield* fileSystem.makeTempDirectoryScoped({
-              prefix: "t3-test-codex-bin-",
-            });
-            const codexPath = path.join(binDir, "codex");
-            yield* fileSystem.writeFileString(
-              codexPath,
-              [
-                "#!/bin/sh",
-                'if [ "$1" = "--version" ]; then',
-                '  echo "codex-cli 1.0.0"',
-                "  exit 0",
-                "fi",
-                'if [ "$1" = "login" ] && [ "$2" = "status" ]; then',
-                '  echo "Logged in using ChatGPT"',
-                "  exit 0",
-                "fi",
-                'echo "unexpected args: $*" >&2',
-                "exit 1",
-                "",
-              ].join("\n"),
-            );
-            yield* fileSystem.chmod(codexPath, 0o755);
-            const customCodexHome = yield* fileSystem.makeTempDirectoryScoped({
-              prefix: "t3-test-codex-home-",
-            });
-            const previousPath = process.env.PATH;
-            process.env.PATH = binDir;
-
-            try {
-              const serverSettingsLayer = ServerSettingsService.layerTest({
-                providers: {
-                  codex: {
-                    homePath: customCodexHome,
-                  },
+      it.effect("returns an Amazon Bedrock label for codex Bedrock auth", () =>
+        Effect.gen(function* () {
+          const status = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
+            Effect.succeed(
+              makeCodexProbeSnapshot({
+                account: {
+                  account: { type: "amazonBedrock" },
+                  requiresOpenaiAuth: false,
                 },
-              });
+              }),
+            ),
+          );
 
-              const status = yield* checkCodexProviderStatus().pipe(
-                Effect.provide(serverSettingsLayer),
-              );
-              assert.strictEqual(status.provider, "codex");
-              assert.strictEqual(status.installed, true);
-              assert.strictEqual(status.status, "ready");
-              assert.strictEqual(status.auth.status, "authenticated");
-            } finally {
-              process.env.PATH = previousPath;
-            }
-          }),
+          assert.strictEqual(status.status, "ready");
+          assert.strictEqual(status.auth.status, "authenticated");
+          assert.strictEqual(status.auth.type, "amazonBedrock");
+          assert.strictEqual(status.auth.label, "Amazon Bedrock");
+        }),
       );
 
       it.effect("returns unavailable when codex is missing", () =>
         Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus();
-          assert.strictEqual(status.provider, "codex");
+          const status = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
+            Effect.fail(
+              new CodexErrors.CodexAppServerSpawnError({
+                command: "codex app-server",
+                cause: new Error("spawn codex ENOENT"),
+              }),
+            ),
+          );
           assert.strictEqual(status.status, "error");
           assert.strictEqual(status.installed, false);
           assert.strictEqual(status.auth.status, "unknown");
@@ -426,107 +445,29 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
             status.message,
             "Codex CLI (`codex`) is not installed or not on PATH.",
           );
-        }).pipe(Effect.provide(failingSpawnerLayer("spawn codex ENOENT"))),
+        }),
       );
 
-      it.effect("returns unavailable when codex is below the minimum supported version", () =>
+      it.effect("closes the app-server probe scope when provider status times out", () =>
         Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus();
-          assert.strictEqual(status.provider, "codex");
-          assert.strictEqual(status.status, "error");
-          assert.strictEqual(status.installed, true);
-          assert.strictEqual(status.auth.status, "unknown");
-          assert.strictEqual(
-            status.message,
-            "Codex CLI v0.36.0 is too old for T3 Code. Upgrade to v0.37.0 or newer and restart T3 Code.",
+          const killCalls = yield* Ref.make(0);
+          const statusFiber = yield* checkCodexProviderStatus(defaultCodexSettings).pipe(
+            Effect.provide(hangingScopedSpawnerLayer(killCalls)),
+            Effect.forkChild,
           );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 0.36.0\n", stderr: "", code: 0 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
-      );
 
-      it.effect("returns unauthenticated when auth probe reports login required", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus();
-          assert.strictEqual(status.provider, "codex");
-          assert.strictEqual(status.status, "error");
-          assert.strictEqual(status.installed, true);
-          assert.strictEqual(status.auth.status, "unauthenticated");
-          assert.strictEqual(
-            status.message,
-            "Codex CLI is not authenticated. Run `codex login` and try again.",
-          );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") {
-                return { stdout: "", stderr: "Not logged in. Run codex login.", code: 1 };
-              }
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
-      );
+          yield* Effect.yieldNow;
+          yield* TestClock.adjust("11 seconds");
+          yield* Effect.yieldNow;
 
-      it.effect("returns unauthenticated when login status output includes 'not logged in'", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus();
-          assert.strictEqual(status.provider, "codex");
+          const status = yield* Fiber.join(statusFiber);
           assert.strictEqual(status.status, "error");
-          assert.strictEqual(status.installed, true);
-          assert.strictEqual(status.auth.status, "unauthenticated");
           assert.strictEqual(
             status.message,
-            "Codex CLI is not authenticated. Run `codex login` and try again.",
+            "Timed out while checking Codex app-server provider status.",
           );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status")
-                return { stdout: "Not logged in\n", stderr: "", code: 1 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
-      );
-
-      it.effect("returns warning when login status command is unsupported", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome();
-          const status = yield* checkCodexProviderStatus();
-          assert.strictEqual(status.provider, "codex");
-          assert.strictEqual(status.status, "warning");
-          assert.strictEqual(status.installed, true);
-          assert.strictEqual(status.auth.status, "unknown");
-          assert.strictEqual(
-            status.message,
-            "Codex CLI authentication status command is unavailable in this Codex version.",
-          );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status") {
-                return { stdout: "", stderr: "error: unknown command 'login'", code: 2 };
-              }
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
+          assert.strictEqual(yield* Ref.get(killCalls), 1);
+        }),
       );
     });
 
@@ -534,7 +475,8 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
       it("treats equal provider snapshots as unchanged", () => {
         const providers = [
           {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
+            driver: ProviderDriverKind.make("codex"),
             status: "ready",
             enabled: true,
             installed: true,
@@ -546,7 +488,8 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
             skills: [],
           },
           {
-            provider: "claudeAgent",
+            instanceId: ProviderInstanceId.make("claudeAgent"),
+            driver: ProviderDriverKind.make("claudeAgent"),
             status: "warning",
             enabled: true,
             installed: true,
@@ -562,86 +505,819 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
         assert.strictEqual(haveProvidersChanged(providers, [...providers]), false);
       });
 
-      it.effect("reruns codex health when codex provider settings change", () =>
+      it("preserves previously discovered provider models when a refresh returns none", () => {
+        const previousProvider = {
+          instanceId: ProviderInstanceId.make("cursor"),
+          driver: ProviderDriverKind.make("cursor"),
+          status: "ready",
+          enabled: true,
+          installed: true,
+          auth: { status: "authenticated" },
+          checkedAt: "2026-04-14T00:00:00.000Z",
+          version: "2026.04.09-f2b0fcd",
+          models: [
+            {
+              slug: "claude-opus-4-6",
+              name: "Opus 4.6",
+              isCustom: false,
+              capabilities: createModelCapabilities({
+                optionDescriptors: [
+                  selectDescriptor("reasoning", "Reasoning", [
+                    { id: "high", label: "High", isDefault: true },
+                  ]),
+                  booleanDescriptor("fastMode", "Fast Mode"),
+                  booleanDescriptor("thinking", "Thinking"),
+                ],
+              }),
+            },
+          ],
+          slashCommands: [],
+          skills: [],
+        } as const satisfies ServerProvider;
+        const refreshedProvider = {
+          ...previousProvider,
+          checkedAt: "2026-04-14T00:01:00.000Z",
+          models: [],
+        } satisfies ServerProvider;
+
+        assert.deepStrictEqual(mergeProviderSnapshot(previousProvider, refreshedProvider).models, [
+          ...previousProvider.models,
+        ]);
+      });
+
+      it("fills missing capabilities from the previous provider snapshot", () => {
+        const previousProvider = {
+          instanceId: ProviderInstanceId.make("cursor"),
+          driver: ProviderDriverKind.make("cursor"),
+          status: "ready",
+          enabled: true,
+          installed: true,
+          auth: { status: "authenticated" },
+          checkedAt: "2026-04-14T00:00:00.000Z",
+          version: "2026.04.09-f2b0fcd",
+          models: [
+            {
+              slug: "claude-opus-4-6",
+              name: "Opus 4.6",
+              isCustom: false,
+              capabilities: createModelCapabilities({
+                optionDescriptors: [
+                  selectDescriptor("reasoning", "Reasoning", [
+                    { id: "high", label: "High", isDefault: true },
+                  ]),
+                  booleanDescriptor("fastMode", "Fast Mode"),
+                  booleanDescriptor("thinking", "Thinking"),
+                ],
+              }),
+            },
+          ],
+          slashCommands: [],
+          skills: [],
+        } as const satisfies ServerProvider;
+        const refreshedProvider = {
+          ...previousProvider,
+          checkedAt: "2026-04-14T00:01:00.000Z",
+          models: [
+            {
+              slug: "claude-opus-4-6",
+              name: "Opus 4.6",
+              isCustom: false,
+              capabilities: createModelCapabilities({
+                optionDescriptors: [],
+              }),
+            },
+          ],
+        } satisfies ServerProvider;
+
+        assert.deepStrictEqual(mergeProviderSnapshot(previousProvider, refreshedProvider).models, [
+          ...previousProvider.models,
+        ]);
+      });
+
+      it("persists merged provider snapshots for the providers that were refreshed", () => {
+        const previousProviders = [
+          {
+            instanceId: ProviderInstanceId.make("cursor"),
+            driver: ProviderDriverKind.make("cursor"),
+            status: "ready",
+            enabled: true,
+            installed: true,
+            auth: { status: "authenticated" },
+            checkedAt: "2026-04-14T00:00:00.000Z",
+            version: "2026.04.09-f2b0fcd",
+            models: [
+              {
+                slug: "claude-opus-4-6",
+                name: "Opus 4.6",
+                isCustom: false,
+                capabilities: createModelCapabilities({
+                  optionDescriptors: [
+                    selectDescriptor("reasoning", "Reasoning", [
+                      { id: "high", label: "High", isDefault: true },
+                    ]),
+                    booleanDescriptor("fastMode", "Fast Mode"),
+                    booleanDescriptor("thinking", "Thinking"),
+                  ],
+                }),
+              },
+            ],
+            slashCommands: [],
+            skills: [],
+          },
+          {
+            instanceId: ProviderInstanceId.make("codex"),
+            driver: ProviderDriverKind.make("codex"),
+            status: "ready",
+            enabled: true,
+            installed: true,
+            auth: { status: "authenticated" },
+            checkedAt: "2026-04-14T00:00:00.000Z",
+            version: "1.0.0",
+            models: [],
+            slashCommands: [],
+            skills: [],
+          },
+        ] as const satisfies ReadonlyArray<ServerProvider>;
+        const refreshedCursor = {
+          ...previousProviders[0],
+          checkedAt: "2026-04-14T00:01:00.000Z",
+          models: [],
+        } satisfies ServerProvider;
+
+        const mergedProviders = mergeProviderSnapshots(previousProviders, [refreshedCursor]);
+        const persistedProviders = selectProvidersByKind(
+          mergedProviders,
+          new Set([ProviderDriverKind.make("cursor")]),
+        );
+
+        assert.deepStrictEqual(persistedProviders, [
+          {
+            ...refreshedCursor,
+            models: [...previousProviders[0].models],
+          },
+        ]);
+      });
+
+      it.effect("persists the merged snapshot when a live update has empty models", () =>
         Effect.gen(function* () {
-          const serverSettings = yield* makeMutableServerSettingsService();
+          const cursorDriver = ProviderDriverKind.make("cursor");
+          const cursorInstanceId = ProviderInstanceId.make("cursor");
+          const initialProvider = {
+            instanceId: cursorInstanceId,
+            driver: cursorDriver,
+            status: "ready",
+            enabled: true,
+            installed: true,
+            auth: { status: "authenticated" },
+            checkedAt: "2026-04-14T00:00:00.000Z",
+            version: "2026.04.09-f2b0fcd",
+            models: [
+              {
+                slug: "claude-opus-4-6",
+                name: "Opus 4.6",
+                isCustom: false,
+                capabilities: createModelCapabilities({
+                  optionDescriptors: [
+                    selectDescriptor("reasoning", "Reasoning", [
+                      { id: "high", label: "High", isDefault: true },
+                    ]),
+                  ],
+                }),
+              },
+            ],
+            slashCommands: [],
+            skills: [],
+          } as const satisfies ServerProvider;
+          const refreshedProvider = {
+            ...initialProvider,
+            checkedAt: "2026-04-14T00:01:00.000Z",
+            models: [],
+          } satisfies ServerProvider;
+          const changes = yield* PubSub.unbounded<ServerProvider>();
+          const instance = {
+            instanceId: cursorInstanceId,
+            driverKind: cursorDriver,
+            continuationIdentity: {
+              driverKind: cursorDriver,
+              continuationKey: "cursor:instance:cursor",
+            },
+            displayName: undefined,
+            enabled: true,
+            snapshot: {
+              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+                provider: cursorDriver,
+                packageName: null,
+              }),
+              getSnapshot: Effect.succeed(initialProvider),
+              refresh: Effect.succeed(refreshedProvider),
+              streamChanges: Stream.fromPubSub(changes),
+            },
+            adapter: {} as ProviderInstance["adapter"],
+            textGeneration: {} as ProviderInstance["textGeneration"],
+          } satisfies ProviderInstance;
+          const instanceRegistryLayer = Layer.succeed(ProviderInstanceRegistry, {
+            getInstance: (instanceId) =>
+              Effect.succeed(instanceId === cursorInstanceId ? instance : undefined),
+            listInstances: Effect.succeed([instance]),
+            listUnavailable: Effect.succeed([]),
+            streamChanges: Stream.empty,
+            subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+              PubSub.subscribe(pubsub),
+            ),
+          });
           const scope = yield* Scope.make();
           yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
-          const providerRegistryLayer = ProviderRegistryLive.pipe(
-            Layer.provideMerge(Layer.succeed(ServerSettingsService, serverSettings)),
-            Layer.provideMerge(
-              mockCommandSpawnerLayer((command, args) => {
-                const joined = args.join(" ");
-                if (joined === "--version") {
-                  if (command === "codex") {
-                    return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-                  }
-                  return { stdout: "", stderr: "spawn ENOENT", code: 1 };
-                }
-                if (joined === "login status") {
-                  return { stdout: "Logged in\n", stderr: "", code: 0 };
-                }
-                throw new Error(`Unexpected args: ${joined}`);
+          const runtimeServices = yield* Layer.build(
+            ProviderRegistryLive.pipe(
+              Layer.provideMerge(instanceRegistryLayer),
+              Layer.provideMerge(
+                ServerConfig.layerTest(process.cwd(), {
+                  prefix: "t3-provider-registry-merged-persist-",
+                }),
+              ),
+              Layer.provideMerge(NodeServices.layer),
+            ),
+          ).pipe(Scope.provide(scope));
+
+          yield* Effect.gen(function* () {
+            const registry = yield* ProviderRegistry;
+            const config = yield* ServerConfig;
+            const filePath = yield* resolveProviderStatusCachePath({
+              cacheDir: config.providerStatusCacheDir,
+              instanceId: cursorInstanceId,
+            });
+
+            assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, [
+              ...initialProvider.models,
+            ]);
+            yield* PubSub.publish(changes, refreshedProvider);
+
+            let cachedProvider = yield* readProviderStatusCache(filePath);
+            for (
+              let attempt = 0;
+              attempt < 50 && cachedProvider?.checkedAt !== refreshedProvider.checkedAt;
+              attempt += 1
+            ) {
+              yield* TestClock.adjust("10 millis");
+              yield* Effect.yieldNow;
+              cachedProvider = yield* readProviderStatusCache(filePath);
+            }
+
+            assert.deepStrictEqual(cachedProvider, {
+              ...refreshedProvider,
+              models: [...initialProvider.models],
+            });
+          }).pipe(Effect.provide(runtimeServices));
+        }),
+      );
+
+      it.effect("returns the cached provider list when a manual refresh fails", () =>
+        Effect.gen(function* () {
+          const codexDriver = ProviderDriverKind.make("codex");
+          const codexInstanceId = ProviderInstanceId.make("codex");
+          const cachedProvider = {
+            instanceId: codexInstanceId,
+            driver: codexDriver,
+            status: "ready",
+            enabled: true,
+            installed: true,
+            auth: { status: "authenticated" },
+            checkedAt: "2026-04-29T10:00:00.000Z",
+            version: "1.0.0",
+            models: [],
+            slashCommands: [],
+            skills: [],
+          } as const satisfies ServerProvider;
+          const instance = {
+            instanceId: codexInstanceId,
+            driverKind: codexDriver,
+            continuationIdentity: {
+              driverKind: codexDriver,
+              continuationKey: "codex:instance:codex",
+            },
+            displayName: undefined,
+            enabled: true,
+            snapshot: {
+              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+                provider: codexDriver,
+                packageName: null,
               }),
+              getSnapshot: Effect.succeed(cachedProvider),
+              refresh: Effect.die(new Error("simulated refresh failure")),
+              streamChanges: Stream.empty,
+            },
+            adapter: {} as ProviderInstance["adapter"],
+            textGeneration: {} as ProviderInstance["textGeneration"],
+          } satisfies ProviderInstance;
+          const instanceRegistryLayer = Layer.succeed(ProviderInstanceRegistry, {
+            getInstance: (instanceId) =>
+              Effect.succeed(instanceId === codexInstanceId ? instance : undefined),
+            listInstances: Effect.succeed([instance]),
+            listUnavailable: Effect.succeed([]),
+            streamChanges: Stream.empty,
+            subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+              PubSub.subscribe(pubsub),
             ),
-          );
+          });
+          const scope = yield* Scope.make();
+          yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
           const runtimeServices = yield* Layer.build(
-            Layer.mergeAll(
-              Layer.succeed(ServerSettingsService, serverSettings),
-              providerRegistryLayer,
+            ProviderRegistryLive.pipe(
+              Layer.provideMerge(instanceRegistryLayer),
+              Layer.provideMerge(
+                ServerConfig.layerTest(process.cwd(), {
+                  prefix: "t3-provider-registry-refresh-failure-",
+                }),
+              ),
+              Layer.provideMerge(NodeServices.layer),
             ),
           ).pipe(Scope.provide(scope));
 
           yield* Effect.gen(function* () {
             const registry = yield* ProviderRegistry;
 
-            const initial = yield* registry.getProviders;
+            assert.deepStrictEqual(yield* registry.getProviders, [cachedProvider]);
+            assert.deepStrictEqual(yield* registry.refresh(codexDriver), [cachedProvider]);
+            assert.deepStrictEqual(yield* registry.refreshInstance(codexInstanceId), [
+              cachedProvider,
+            ]);
+          }).pipe(Effect.provide(runtimeServices));
+        }),
+      );
+
+      it.effect("keeps consuming registry changes after one sync fails", () =>
+        Effect.gen(function* () {
+          const codexDriver = ProviderDriverKind.make("codex");
+          const codexInstanceId = ProviderInstanceId.make("codex");
+          const claudeDriver = ProviderDriverKind.make("claudeAgent");
+          const claudeInstanceId = ProviderInstanceId.make("claudeAgent");
+          const codexProvider = {
+            instanceId: codexInstanceId,
+            driver: codexDriver,
+            status: "ready",
+            enabled: true,
+            installed: true,
+            auth: { status: "authenticated" },
+            checkedAt: "2026-04-29T10:00:00.000Z",
+            version: "1.0.0",
+            models: [],
+            slashCommands: [],
+            skills: [],
+          } as const satisfies ServerProvider;
+          const claudeProvider = {
+            instanceId: claudeInstanceId,
+            driver: claudeDriver,
+            status: "ready",
+            enabled: true,
+            installed: true,
+            auth: { status: "authenticated" },
+            checkedAt: "2026-04-29T10:01:00.000Z",
+            version: "1.0.0",
+            models: [],
+            slashCommands: [],
+            skills: [],
+          } as const satisfies ServerProvider;
+          const makeInstance = (provider: ServerProvider): ProviderInstance => ({
+            instanceId: provider.instanceId,
+            driverKind: provider.driver,
+            continuationIdentity: {
+              driverKind: provider.driver,
+              continuationKey: `${provider.driver}:instance:${provider.instanceId}`,
+            },
+            displayName: undefined,
+            enabled: true,
+            snapshot: {
+              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
+                provider: provider.driver,
+                packageName: null,
+              }),
+              getSnapshot: Effect.succeed(provider),
+              refresh: Effect.succeed(provider),
+              streamChanges: Stream.empty,
+            },
+            adapter: {} as ProviderInstance["adapter"],
+            textGeneration: {} as ProviderInstance["textGeneration"],
+          });
+          const codexInstance = makeInstance(codexProvider);
+          const claudeInstance = makeInstance(claudeProvider);
+          const changes = yield* PubSub.unbounded<void>();
+          const instancesRef = yield* Ref.make<ReadonlyArray<ProviderInstance>>([codexInstance]);
+          const failNextList = yield* Ref.make(false);
+          const wait = () => Effect.yieldNow;
+          const instanceRegistryLayer = Layer.succeed(ProviderInstanceRegistry, {
+            getInstance: (instanceId) =>
+              Ref.get(instancesRef).pipe(
+                Effect.map((instances) =>
+                  instances.find((instance) => instance.instanceId === instanceId),
+                ),
+              ),
+            listInstances: Effect.gen(function* () {
+              const shouldFail = yield* Ref.get(failNextList);
+              if (shouldFail) {
+                yield* Ref.set(failNextList, false);
+                return yield* Effect.die(new Error("simulated registry list failure"));
+              }
+              return yield* Ref.get(instancesRef);
+            }),
+            listUnavailable: Effect.succeed([]),
+            streamChanges: Stream.fromPubSub(changes),
+            subscribeChanges: PubSub.subscribe(changes),
+          });
+          const scope = yield* Scope.make();
+          yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
+          const runtimeServices = yield* Layer.build(
+            ProviderRegistryLive.pipe(
+              Layer.provideMerge(instanceRegistryLayer),
+              Layer.provideMerge(
+                ServerConfig.layerTest(process.cwd(), {
+                  prefix: "t3-provider-registry-sync-failure-",
+                }),
+              ),
+              Layer.provideMerge(NodeServices.layer),
+            ),
+          ).pipe(Scope.provide(scope));
+
+          yield* Effect.gen(function* () {
+            const registry = yield* ProviderRegistry;
+            assert.deepStrictEqual(yield* registry.getProviders, [codexProvider]);
+
+            yield* Ref.set(failNextList, true);
+            yield* PubSub.publish(changes, undefined);
+
+            yield* Ref.set(instancesRef, [codexInstance, claudeInstance]);
+            yield* PubSub.publish(changes, undefined);
+
+            let providers = yield* registry.getProviders;
+            for (
+              let attempt = 0;
+              attempt < 50 &&
+              !providers.some((provider) => provider.instanceId === claudeInstanceId);
+              attempt += 1
+            ) {
+              yield* wait();
+              providers = yield* registry.getProviders;
+            }
+
+            assert.deepStrictEqual(
+              providers.map((provider) => provider.instanceId).toSorted(),
+              [codexInstanceId, claudeInstanceId].toSorted(),
+            );
+          }).pipe(Effect.provide(runtimeServices));
+        }),
+      );
+
+      // This test intentionally avoids `mockCommandSpawnerLayer` so the real
+      // `probeCodexAppServerProvider` path runs — including the full
+      // `codex app-server` RPC handshake via `CodexClient.layerCommand`.
+      // We point `binaryPath` at a name that cannot exist on any machine so
+      // the real `ChildProcessSpawner` deterministically returns ENOENT; the
+      // probe wraps that as `CodexAppServerSpawnError` and
+      // `checkCodexProviderStatus` turns it into the user-visible "not
+      // installed" error snapshot. If the aggregator's `syncLiveSources`
+      // breaks — the `codex_personal`-never-probes bug we are guarding
+      // against — that snapshot never lands in `getProviders` and the
+      // assertions below fail.
+      it.effect("propagates real Codex probe failures to the aggregator at boot", () =>
+        Effect.gen(function* () {
+          const missingBinary = `t3code_codex_missing_`;
+          const serverSettings = yield* makeMutableServerSettingsService(
+            decodeServerSettings(
+              deepMerge(encodedDefaultServerSettings, {
+                providers: {
+                  // Disable every built-in probe that would otherwise spawn
+                  // on the CI host. `enabled: false` short-circuits each
+                  // driver's probe *before* it touches the spawner, so the
+                  // test environment stays isolated from the dev
+                  // machine's PATH.
+                  codex: { enabled: false },
+                  claudeAgent: { enabled: false },
+                  cursor: { enabled: false },
+                  opencode: { enabled: false },
+                },
+                // `providerInstances` keys are branded `ProviderInstanceId`;
+                // the branded index signature rejects plain string literals
+                // at the TS level even though the runtime schema happily
+                // accepts + decodes them. Cast the patch to `unknown` so
+                // the `Schema.decodeSync` below does the real validation.
+                providerInstances: {
+                  // Matches the shape the user had in `.t3/dev/settings.json`
+                  // when the bug was reported: a custom enabled Codex instance
+                  // pointing at a binary the server has to actually spawn.
+                  codex_personal: {
+                    driver: "codex",
+                    displayName: "Codex Personal",
+                    enabled: true,
+                    config: {
+                      binaryPath: missingBinary,
+                      homePath: `/tmp/${missingBinary}_home`,
+                    },
+                  },
+                } as unknown as ContractServerSettings["providerInstances"],
+              }),
+            ),
+          );
+          const scope = yield* Scope.make();
+          yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
+          const providerRegistryLayer = ProviderRegistryLive.pipe(
+            Layer.provideMerge(ProviderInstanceRegistryHydrationLive),
+            Layer.provideMerge(Layer.succeed(ServerSettingsService, serverSettings)),
+            Layer.provideMerge(
+              ServerConfig.layerTest(process.cwd(), {
+                prefix: "t3-provider-registry-",
+              }),
+            ),
+            Layer.provideMerge(TestHttpClientLive),
+            Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+            Layer.provideMerge(OpenCodeRuntimeLive),
+            // NO spawner mock — `ChildProcessSpawner` is supplied by the
+            // outer `NodeServices.layer` on `it.layer(...)` and will
+            // genuinely spawn a subprocess. The missing-binary ENOENT is
+            // what exercises the same failure mode as a misconfigured
+            // production `binaryPath`.
+          );
+          const runtimeServices = yield* Layer.build(providerRegistryLayer).pipe(
+            Scope.provide(scope),
+          );
+
+          yield* Effect.gen(function* () {
+            const registry = yield* ProviderRegistry;
+            const providers = yield* registry.getProviders;
+            const codexPersonal = providers.find(
+              (provider) => provider.instanceId === "codex_personal",
+            );
+            assert.notStrictEqual(
+              codexPersonal,
+              undefined,
+              `Expected the aggregator to know about codex_personal; instead saw: ${providers
+                .map((provider) => provider.instanceId)
+                .join(", ")}`,
+            );
+            assert.strictEqual(
+              codexPersonal?.status,
+              "error",
+              "Real Codex probe against a missing binary should surface as 'error' in the aggregator",
+            );
+            assert.strictEqual(codexPersonal?.installed, false);
             assert.strictEqual(
-              initial.find((status) => status.provider === "codex")?.status,
-              "ready",
+              codexPersonal?.message,
+              "Codex CLI (`codex`) is not installed or not on PATH.",
             );
+          }).pipe(Effect.provide(runtimeServices));
+        }),
+      );
+
+      // Guards the second half of the reported bug: changing
+      // `providers.codex.binaryPath` in settings must tear down the live
+      // instance and rebuild it so a fresh probe runs with the new binary.
+      // This test drives the real settings stream → registry reconcile →
+      // aggregator sync pipeline and asserts that `getProviders` reflects
+      // the new probe's outcome. If `syncLiveSources` stops awaiting the
+      // rebuilt instance's refresh (previous bug mode), the aggregator
+      // keeps the old snapshot and this test fails.
+      //
+      it.effect("re-probes when settings change the codex binaryPath", () =>
+        Effect.gen(function* () {
+          const firstMissing = `t3code_codex_first_`;
+          const secondMissing = `t3code_codex_second_`;
+          const serverSettings = yield* makeMutableServerSettingsService(
+            decodeServerSettings(
+              deepMerge(encodedDefaultServerSettings, {
+                providers: {
+                  codex: { enabled: true, binaryPath: firstMissing },
+                  claudeAgent: { enabled: false },
+                  cursor: { enabled: false },
+                  opencode: { enabled: false },
+                },
+              }),
+            ),
+          );
+          const scope = yield* Scope.make();
+          yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
+          const providerRegistryLayer = ProviderRegistryLive.pipe(
+            Layer.provideMerge(ProviderInstanceRegistryHydrationLive),
+            Layer.provideMerge(Layer.succeed(ServerSettingsService, serverSettings)),
+            Layer.provideMerge(
+              ServerConfig.layerTest(process.cwd(), {
+                prefix: "t3-provider-registry-",
+              }),
+            ),
+            Layer.provideMerge(TestHttpClientLive),
+            Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+            Layer.provideMerge(OpenCodeRuntimeLive),
+            // `it.live` does not inherit layers from the outer `it.layer`
+            // wrapper, so provide `NodeServices.layer` inline. This is the
+            // same real `ChildProcessSpawner` + `FileSystem` + `Path`
+            // services that production uses.
+            Layer.provideMerge(NodeServices.layer),
+          );
+          const runtimeServices = yield* Layer.build(providerRegistryLayer).pipe(
+            Scope.provide(scope),
+          );
 
+          yield* Effect.gen(function* () {
+            const registry = yield* ProviderRegistry;
+            // Boot-time probe: the default codex instance is enabled with
+            // `firstMissing`, so the real spawner yields ENOENT and the
+            // snapshot should be `status: "error"`. What *distinguishes*
+            // the two probe runs is `checkedAt` — each probe stamps a
+            // fresh DateTime, so we capture it and assert it advances
+            // after the settings mutation.
+            const initialProviders = yield* registry.getProviders;
+            const initialCodex = initialProviders.find(
+              (provider) => provider.instanceId === "codex",
+            );
+            assert.strictEqual(initialCodex?.status, "error");
+            assert.strictEqual(initialCodex?.installed, false);
+            const initialCheckedAt = initialCodex?.checkedAt;
+            assert.notStrictEqual(initialCheckedAt, undefined);
+
+            // Drive a settings change. The Hydration layer's
+            // `SettingsWatcherLive` consumes this via `streamChanges`,
+            // calls `reconcile`, which rebuilds the codex instance (the
+            // envelope changed because `binaryPath` differs → `entryEqual`
+            // is false). The registry's `Stream.runForEach(
+            // instanceRegistry.streamChanges, () => syncLiveSources)`
+            // fires `syncLiveSources`, which subscribes + awaits a fresh
+            // refresh on the rebuilt instance.
             yield* serverSettings.updateSettings({
               providers: {
-                codex: {
-                  binaryPath: "/custom/codex",
-                },
+                codex: { enabled: true, binaryPath: secondMissing },
               },
             });
 
-            for (let attempt = 0; attempt < 20; attempt += 1) {
-              const updated = yield* registry.getProviders;
-              if (updated.find((status) => status.provider === "codex")?.status === "error") {
-                return;
+            // Poll with TestClock until `checkedAt` advances or we hit a
+            // generous virtual 3-second ceiling.
+            const refreshed = yield* Effect.gen(function* () {
+              for (let attempts = 0; attempts < 60; attempts += 1) {
+                const providers = yield* registry.getProviders;
+                const codex = providers.find((provider) => provider.instanceId === "codex");
+                if (codex !== undefined && codex.checkedAt !== initialCheckedAt) {
+                  return providers;
+                }
+                yield* TestClock.adjust("50 millis");
+                yield* Effect.yieldNow;
               }
-              yield* Effect.promise(() => new Promise((resolve) => setTimeout(resolve, 0)));
-            }
+              return yield* registry.getProviders;
+            });
 
-            const updated = yield* registry.getProviders;
-            assert.strictEqual(
-              updated.find((status) => status.provider === "codex")?.status,
-              "error",
+            const reprobedCodex = refreshed.find((provider) => provider.instanceId === "codex");
+            assert.notStrictEqual(
+              reprobedCodex?.checkedAt,
+              initialCheckedAt,
+              "Expected a fresh probe after settings change, got the stale snapshot",
             );
+            assert.strictEqual(reprobedCodex?.status, "error");
+            assert.strictEqual(reprobedCodex?.installed, false);
           }).pipe(Effect.provide(runtimeServices));
         }),
       );
 
-      it.effect("skips codex probes entirely when the provider is disabled", () =>
+      it.effect("includes unavailable instance snapshots in getProviders", () =>
         Effect.gen(function* () {
-          const serverSettingsLayer = ServerSettingsService.layerTest({
-            providers: {
-              codex: {
-                enabled: false,
-              },
-            },
-          });
+          const serverSettings = yield* makeMutableServerSettingsService(
+            decodeServerSettings(
+              deepMerge(encodedDefaultServerSettings, {
+                providers: {
+                  codex: { enabled: false },
+                  claudeAgent: { enabled: false },
+                  cursor: { enabled: false },
+                  opencode: { enabled: false },
+                },
+                providerInstances: {
+                  ghost_main: {
+                    driver: "ghostDriver",
+                    displayName: "A fork-only driver we don't ship",
+                    enabled: false,
+                    config: { arbitrary: "payload" },
+                  },
+                } as unknown as ContractServerSettings["providerInstances"],
+              }),
+            ),
+          );
+          const scope = yield* Scope.make();
+          yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
+          const providerRegistryLayer = ProviderRegistryLive.pipe(
+            Layer.provideMerge(ProviderInstanceRegistryHydrationLive),
+            Layer.provideMerge(Layer.succeed(ServerSettingsService, serverSettings)),
+            Layer.provideMerge(
+              ServerConfig.layerTest(process.cwd(), {
+                prefix: "t3-provider-registry-",
+              }),
+            ),
+            Layer.provideMerge(TestHttpClientLive),
+            Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+            Layer.provideMerge(OpenCodeRuntimeLive),
+            Layer.provideMerge(NodeServices.layer),
+          );
+          const runtimeServices = yield* Layer.build(providerRegistryLayer).pipe(
+            Scope.provide(scope),
+          );
+
+          yield* Effect.gen(function* () {
+            const registry = yield* ProviderRegistry;
+            const providers = yield* registry.getProviders;
+            const ghost = providers.find((provider) => provider.instanceId === "ghost_main");
+
+            assert.notStrictEqual(ghost, undefined);
+            assert.strictEqual(ghost?.driver, "ghostDriver");
+            assert.strictEqual(ghost?.availability, "unavailable");
+            assert.match(ghost?.unavailableReason ?? "", /ghostDriver/);
+          }).pipe(Effect.provide(runtimeServices));
+        }),
+      );
+
+      it.effect(
+        "keeps cursor disabled and skips probing when the provider setting is disabled",
+        () =>
+          Effect.gen(function* () {
+            const serverSettings = yield* makeMutableServerSettingsService(
+              decodeServerSettings(
+                deepMerge(encodedDefaultServerSettings, {
+                  providers: {
+                    codex: {
+                      enabled: false,
+                    },
+                    cursor: {
+                      enabled: false,
+                    },
+                  },
+                }),
+              ),
+            );
+            let cursorSpawned = false;
+            const scope = yield* Scope.make();
+            yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void));
+            const providerRegistryLayer = ProviderRegistryLive.pipe(
+              Layer.provideMerge(ProviderInstanceRegistryHydrationLive),
+              Layer.provideMerge(Layer.succeed(ServerSettingsService, serverSettings)),
+              Layer.provideMerge(
+                ServerConfig.layerTest(process.cwd(), {
+                  prefix: "t3-provider-registry-",
+                }),
+              ),
+              Layer.provideMerge(TestHttpClientLive),
+              Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+              Layer.provideMerge(OpenCodeRuntimeLive),
+              Layer.provideMerge(
+                mockCommandSpawnerLayer((command, args) => {
+                  if (command === "agent") {
+                    cursorSpawned = true;
+                  }
+                  const joined = args.join(" ");
+                  if (joined === "--version") {
+                    return {
+                      stdout: `${command} 1.0.0\n`,
+                      stderr: "",
+                      code: 0,
+                    };
+                  }
+                  if (joined === "auth status") {
+                    return {
+                      stdout: '{"authenticated":true}\n',
+                      stderr: "",
+                      code: 0,
+                    };
+                  }
+                  throw new Error(`Unexpected args: ${command} ${joined}`);
+                }),
+              ),
+            );
+            const runtimeServices = yield* Layer.build(
+              Layer.mergeAll(
+                Layer.succeed(ServerSettingsService, serverSettings),
+                providerRegistryLayer,
+              ),
+            ).pipe(Scope.provide(scope));
+
+            yield* Effect.gen(function* () {
+              const registry = yield* ProviderRegistry;
+              const providers = yield* registry.getProviders;
+              const cursorProvider = providers.find(
+                (provider) => provider.instanceId === ProviderInstanceId.make("cursor"),
+              );
+
+              assert.deepStrictEqual(providers.map((provider) => provider.instanceId).toSorted(), [
+                "claudeAgent",
+                "codex",
+                "cursor",
+                "opencode",
+              ]);
+              assert.strictEqual(cursorProvider?.enabled, false);
+              assert.strictEqual(cursorProvider?.status, "disabled");
+              assert.strictEqual(
+                cursorProvider?.message,
+                "Cursor is disabled in T3 Code settings.",
+              );
+              assert.strictEqual(cursorSpawned, false);
+            }).pipe(Effect.provide(runtimeServices));
+          }),
+      );
 
-          const status = yield* checkCodexProviderStatus().pipe(
-            Effect.provide(
-              Layer.mergeAll(serverSettingsLayer, failingSpawnerLayer("spawn codex ENOENT")),
-            ),
+      it.effect("skips codex probes entirely when the provider is disabled", () =>
+        Effect.gen(function* () {
+          const status = yield* checkCodexProviderStatus(disabledCodexSettings).pipe(
+            Effect.provide(failingSpawnerLayer("spawn codex ENOENT")),
           );
-          assert.strictEqual(status.provider, "codex");
           assert.strictEqual(status.enabled, false);
           assert.strictEqual(status.status, "disabled");
           assert.strictEqual(status.installed, false);
@@ -650,248 +1326,119 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
       );
     });
 
-    // ── Custom model provider: checkCodexProviderStatus integration ───
+    // ── checkClaudeProviderStatus tests ──────────────────────────
+
+    describe("checkClaudeProviderStatus", () => {
+      it.effect("returns ready when claude is installed and authenticated", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities(),
+          );
+          assert.strictEqual(status.status, "ready");
+          assert.strictEqual(status.installed, true);
+          assert.strictEqual(status.auth.status, "authenticated");
+        }).pipe(
+          Effect.provide(
+            mockSpawnerLayer((args) => {
+              const joined = args.join(" ");
+              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
+              if (joined === "auth status")
+                return {
+                  stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
+                  stderr: "",
+                  code: 0,
+                };
+              throw new Error(`Unexpected args: ${joined}`);
+            }),
+          ),
+        ),
+      );
 
-    describe("checkCodexProviderStatus with custom model provider", () => {
       it.effect(
-        "skips auth probe and returns ready when a custom model provider is configured",
+        "includes Claude Opus 4.7 with xhigh as the default effort on supported versions",
         () =>
           Effect.gen(function* () {
-            yield* withTempCodexHome(
-              [
-                'model_provider = "portkey"',
-                "",
-                "[model_providers.portkey]",
-                'base_url = "https://api.portkey.ai/v1"',
-                'env_key = "PORTKEY_API_KEY"',
-              ].join("\n"),
+            const status = yield* checkClaudeProviderStatus(
+              defaultClaudeSettings,
+              claudeCapabilities(),
             );
-            const status = yield* checkCodexProviderStatus();
-            assert.strictEqual(status.provider, "codex");
-            assert.strictEqual(status.status, "ready");
-            assert.strictEqual(status.installed, true);
-            assert.strictEqual(status.auth.status, "unknown");
-            assert.strictEqual(
-              status.message,
-              "Using a custom Codex model provider; OpenAI login check skipped.",
+            const opus47 = status.models.find((model) => model.slug === "claude-opus-4-7");
+            if (!opus47) {
+              assert.fail("Expected Claude Opus 4.7 to be present for Claude Code v2.1.111.");
+            }
+            if (!opus47.capabilities) {
+              assert.fail(
+                "Expected Claude Opus 4.7 capabilities to be present for Claude Code v2.1.111.",
+              );
+            }
+            const effortDescriptor = opus47.capabilities.optionDescriptors?.find(
+              (descriptor) => descriptor.type === "select" && descriptor.id === "effort",
+            );
+            assert.deepStrictEqual(
+              effortDescriptor?.type === "select"
+                ? effortDescriptor.options.find((option) => option.isDefault)
+                : undefined,
+              { id: "xhigh", label: "Extra High", isDefault: true },
             );
           }).pipe(
             Effect.provide(
-              // The spawner only handles --version; if the test attempts
-              // "login status" the throw proves the auth probe was NOT skipped.
               mockSpawnerLayer((args) => {
                 const joined = args.join(" ");
-                if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-                throw new Error(`Auth probe should have been skipped but got args: ${joined}`);
+                if (joined === "--version") return { stdout: "2.1.111\n", stderr: "", code: 0 };
+                if (joined === "auth status")
+                  return {
+                    stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
+                    stderr: "",
+                    code: 0,
+                  };
+                throw new Error(`Unexpected args: ${joined}`);
               }),
             ),
           ),
       );
 
-      it.effect("still reports error when codex CLI is missing even with custom provider", () =>
+      it.effect("hides Claude Opus 4.7 on older Claude Code versions", () =>
         Effect.gen(function* () {
-          yield* withTempCodexHome(
-            [
-              'model_provider = "portkey"',
-              "",
-              "[model_providers.portkey]",
-              'base_url = "https://api.portkey.ai/v1"',
-              'env_key = "PORTKEY_API_KEY"',
-            ].join("\n"),
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities(),
+          );
+          assert.strictEqual(
+            status.models.some((model) => model.slug === "claude-opus-4-7"),
+            false,
+          );
+          assert.strictEqual(
+            status.message,
+            "Claude Code v2.1.110 is too old for Claude Opus 4.7. Upgrade to v2.1.111 or newer to access it.",
           );
-          const status = yield* checkCodexProviderStatus();
-          assert.strictEqual(status.status, "error");
-          assert.strictEqual(status.installed, false);
-        }).pipe(Effect.provide(failingSpawnerLayer("spawn codex ENOENT"))),
-      );
-    });
-
-    describe("checkCodexProviderStatus with openai model provider", () => {
-      it.effect("still runs auth probe when model_provider is openai", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model_provider = "openai"\n');
-          const status = yield* checkCodexProviderStatus();
-          // The auth probe runs and sees "not logged in" → error
-          assert.strictEqual(status.status, "error");
-          assert.strictEqual(status.auth.status, "unauthenticated");
         }).pipe(
           Effect.provide(
             mockSpawnerLayer((args) => {
               const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-              if (joined === "login status")
-                return { stdout: "Not logged in\n", stderr: "", code: 1 };
+              if (joined === "--version") return { stdout: "2.1.110\n", stderr: "", code: 0 };
+              if (joined === "auth status")
+                return {
+                  stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
+                  stderr: "",
+                  code: 0,
+                };
               throw new Error(`Unexpected args: ${joined}`);
             }),
           ),
         ),
       );
-    });
-
-    // ── parseAuthStatusFromOutput pure tests ──────────────────────────
-
-    describe("parseAuthStatusFromOutput", () => {
-      it("exit code 0 with no auth markers is ready", () => {
-        const parsed = parseAuthStatusFromOutput({ stdout: "OK\n", stderr: "", code: 0 });
-        assert.strictEqual(parsed.status, "ready");
-        assert.strictEqual(parsed.auth.status, "authenticated");
-      });
-
-      it("JSON with authenticated=false is unauthenticated", () => {
-        const parsed = parseAuthStatusFromOutput({
-          stdout: '[{"authenticated":false}]\n',
-          stderr: "",
-          code: 0,
-        });
-        assert.strictEqual(parsed.status, "error");
-        assert.strictEqual(parsed.auth.status, "unauthenticated");
-      });
-
-      it("JSON without auth marker is warning", () => {
-        const parsed = parseAuthStatusFromOutput({
-          stdout: '[{"ok":true}]\n',
-          stderr: "",
-          code: 0,
-        });
-        assert.strictEqual(parsed.status, "warning");
-        assert.strictEqual(parsed.auth.status, "unknown");
-      });
-    });
-
-    // ── readCodexConfigModelProvider tests ─────────────────────────────
-
-    describe("readCodexConfigModelProvider", () => {
-      it.effect("returns undefined when config file does not exist", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome();
-          assert.strictEqual(yield* readCodexConfigModelProvider(), undefined);
-        }),
-      );
-
-      it.effect("returns undefined when config has no model_provider key", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model = "gpt-5-codex"\n');
-          assert.strictEqual(yield* readCodexConfigModelProvider(), undefined);
-        }),
-      );
 
-      it.effect("returns the provider when model_provider is set at top level", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model = "gpt-5-codex"\nmodel_provider = "portkey"\n');
-          assert.strictEqual(yield* readCodexConfigModelProvider(), "portkey");
-        }),
-      );
-
-      it.effect("returns openai when model_provider is openai", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model_provider = "openai"\n');
-          assert.strictEqual(yield* readCodexConfigModelProvider(), "openai");
-        }),
-      );
-
-      it.effect("ignores model_provider inside section headers", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome(
-            [
-              'model = "gpt-5-codex"',
-              "",
-              "[model_providers.portkey]",
-              'base_url = "https://api.portkey.ai/v1"',
-              'model_provider = "should-be-ignored"',
-              "",
-            ].join("\n"),
-          );
-          assert.strictEqual(yield* readCodexConfigModelProvider(), undefined);
-        }),
-      );
-
-      it.effect("handles comments and whitespace", () =>
+      it.effect("returns a display label for claude subscription types", () =>
         Effect.gen(function* () {
-          yield* withTempCodexHome(
-            [
-              "# This is a comment",
-              "",
-              '  model_provider = "azure"  ',
-              "",
-              "[profiles.deep-review]",
-              'model = "gpt-5-pro"',
-            ].join("\n"),
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({ subscriptionType: "maxplan" }),
           );
-          assert.strictEqual(yield* readCodexConfigModelProvider(), "azure");
-        }),
-      );
-
-      it.effect("handles single-quoted values in TOML", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome("model_provider = 'mistral'\n");
-          assert.strictEqual(yield* readCodexConfigModelProvider(), "mistral");
-        }),
-      );
-    });
-
-    // ── hasCustomModelProvider tests ───────────────────────────────────
-
-    describe("hasCustomModelProvider", () => {
-      it.effect("returns false when no config file exists", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome();
-          assert.strictEqual(yield* hasCustomModelProvider, false);
-        }),
-      );
-
-      it.effect("returns false when model_provider is not set", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model = "gpt-5-codex"\n');
-          assert.strictEqual(yield* hasCustomModelProvider, false);
-        }),
-      );
-
-      it.effect("returns false when model_provider is openai", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model_provider = "openai"\n');
-          assert.strictEqual(yield* hasCustomModelProvider, false);
-        }),
-      );
-
-      it.effect("returns true when model_provider is portkey", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model_provider = "portkey"\n');
-          assert.strictEqual(yield* hasCustomModelProvider, true);
-        }),
-      );
-
-      it.effect("returns true when model_provider is azure", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model_provider = "azure"\n');
-          assert.strictEqual(yield* hasCustomModelProvider, true);
-        }),
-      );
-
-      it.effect("returns true when model_provider is ollama", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model_provider = "ollama"\n');
-          assert.strictEqual(yield* hasCustomModelProvider, true);
-        }),
-      );
-
-      it.effect("returns true when model_provider is a custom proxy", () =>
-        Effect.gen(function* () {
-          yield* withTempCodexHome('model_provider = "my-company-proxy"\n');
-          assert.strictEqual(yield* hasCustomModelProvider, true);
-        }),
-      );
-    });
-
-    // ── checkClaudeProviderStatus tests ──────────────────────────
-
-    describe("checkClaudeProviderStatus", () => {
-      it.effect("returns ready when claude is installed and authenticated", () =>
-        Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          assert.strictEqual(status.provider, "claudeAgent");
           assert.strictEqual(status.status, "ready");
-          assert.strictEqual(status.installed, true);
           assert.strictEqual(status.auth.status, "authenticated");
+          assert.strictEqual(status.auth.type, "maxplan");
+          assert.strictEqual(status.auth.label, "Claude Max Subscription");
         }).pipe(
           Effect.provide(
             mockSpawnerLayer((args) => {
@@ -909,14 +1456,58 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
         ),
       );
 
-      it.effect("returns a display label for claude subscription types", () =>
+      it.effect("does not duplicate Claude in full subscription labels", () =>
         Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus(() => Effect.succeed("maxplan"));
-          assert.strictEqual(status.provider, "claudeAgent");
-          assert.strictEqual(status.status, "ready");
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "Claude Max Subscription",
+            }),
+          );
           assert.strictEqual(status.auth.status, "authenticated");
-          assert.strictEqual(status.auth.type, "maxplan");
+          assert.strictEqual(status.auth.type, "Claude Max Subscription");
+          assert.strictEqual(status.auth.label, "Claude Max Subscription");
+        }).pipe(
+          Effect.provide(
+            mockSpawnerLayer((args) => {
+              const joined = args.join(" ");
+              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
+              throw new Error(`Unexpected args: ${joined}`);
+            }),
+          ),
+        ),
+      );
+
+      it.effect("does not duplicate Claude in provider-prefixed subscription names", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "Claude Max",
+            }),
+          );
+          assert.strictEqual(status.auth.status, "authenticated");
+          assert.strictEqual(status.auth.type, "Claude Max");
           assert.strictEqual(status.auth.label, "Claude Max Subscription");
+        }).pipe(
+          Effect.provide(
+            mockSpawnerLayer((args) => {
+              const joined = args.join(" ");
+              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
+              throw new Error(`Unexpected args: ${joined}`);
+            }),
+          ),
+        ),
+      );
+
+      it.effect("returns claude auth email from initialization result", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({ email: "claude@example.com" }),
+          );
+          assert.strictEqual(status.auth.status, "authenticated");
+          assert.strictEqual(status.auth.email, "claude@example.com");
         }).pipe(
           Effect.provide(
             mockSpawnerLayer((args) => {
@@ -924,7 +1515,8 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
               if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
               if (joined === "auth status")
                 return {
-                  stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
+                  stdout:
+                    '{"loggedIn":true,"authMethod":"claude.ai","account":{"email":"claude@example.com"}}\n',
                   stderr: "",
                   code: 0,
                 };
@@ -934,18 +1526,50 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
         ),
       );
 
+      it.effect("runs Claude status probes with the configured Claude HOME", () => {
+        const claudeHome = "/tmp/t3code-claude-home";
+        const recorded = recordingMockSpawnerLayer((args) => {
+          const joined = args.join(" ");
+          if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
+          if (joined === "auth status")
+            return {
+              stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
+              stderr: "",
+              code: 0,
+            };
+          throw new Error(`Unexpected args: ${joined}`);
+        });
+
+        return Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            {
+              ...defaultClaudeSettings,
+              homePath: claudeHome,
+            },
+            claudeCapabilities(),
+          );
+          assert.strictEqual(status.status, "ready");
+          assert.deepStrictEqual(
+            recorded.commands.map((command) => command.env?.HOME),
+            [claudeHome],
+          );
+        }).pipe(Effect.provide(recorded.layer));
+      });
+
       it.effect("includes probed claude slash commands in the provider snapshot", () =>
         Effect.gen(function* () {
           const status = yield* checkClaudeProviderStatus(
-            () => Effect.succeed("maxplan"),
-            () =>
-              Effect.succeed([
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "maxplan",
+              slashCommands: [
                 {
                   name: "review",
                   description: "Review a pull request",
                   input: { hint: "pr-or-branch" },
                 },
-              ]),
+              ],
+            }),
           );
 
           assert.deepStrictEqual(status.slashCommands, [
@@ -975,9 +1599,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
       it.effect("deduplicates probed claude slash commands by name", () =>
         Effect.gen(function* () {
           const status = yield* checkClaudeProviderStatus(
-            () => Effect.succeed("maxplan"),
-            () =>
-              Effect.succeed([
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "maxplan",
+              slashCommands: [
                 {
                   name: "ui",
                   description: "Explore and refine UI",
@@ -986,7 +1611,8 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
                   name: "ui",
                   input: { hint: "component-or-screen" },
                 },
-              ]),
+              ],
+            }),
           );
 
           assert.deepStrictEqual(status.slashCommands, [
@@ -1015,8 +1641,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
 
       it.effect("returns an api key label for claude api key auth", () =>
         Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          assert.strictEqual(status.provider, "claudeAgent");
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({ tokenSource: "ANTHROPIC_AUTH_TOKEN" }),
+          );
           assert.strictEqual(status.status, "ready");
           assert.strictEqual(status.auth.status, "authenticated");
           assert.strictEqual(status.auth.type, "apiKey");
@@ -1040,8 +1668,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
 
       it.effect("returns unavailable when claude is missing", () =>
         Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          assert.strictEqual(status.provider, "claudeAgent");
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities(),
+          );
           assert.strictEqual(status.status, "error");
           assert.strictEqual(status.installed, false);
           assert.strictEqual(status.auth.status, "unknown");
@@ -1054,8 +1684,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
 
       it.effect("returns error when version check fails with non-zero exit code", () =>
         Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          assert.strictEqual(status.provider, "claudeAgent");
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities(),
+          );
           assert.strictEqual(status.status, "error");
           assert.strictEqual(status.installed, true);
         }).pipe(
@@ -1063,33 +1695,9 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
             mockSpawnerLayer((args) => {
               const joined = args.join(" ");
               if (joined === "--version")
-                return { stdout: "", stderr: "Something went wrong", code: 1 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
-      );
-
-      it.effect("returns unauthenticated when auth status reports not logged in", () =>
-        Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          assert.strictEqual(status.provider, "claudeAgent");
-          assert.strictEqual(status.status, "error");
-          assert.strictEqual(status.installed, true);
-          assert.strictEqual(status.auth.status, "unauthenticated");
-          assert.strictEqual(
-            status.message,
-            "Claude is not authenticated. Run `claude auth login` and try again.",
-          );
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
-              if (joined === "auth status")
                 return {
-                  stdout: '{"loggedIn":false}\n',
-                  stderr: "",
+                  stdout: "",
+                  stderr: "Something went wrong",
                   code: 1,
                 };
               throw new Error(`Unexpected args: ${joined}`);
@@ -1098,36 +1706,18 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
         ),
       );
 
-      it.effect("returns unauthenticated when output includes 'not logged in'", () =>
-        Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          assert.strictEqual(status.provider, "claudeAgent");
-          assert.strictEqual(status.status, "error");
-          assert.strictEqual(status.installed, true);
-          assert.strictEqual(status.auth.status, "unauthenticated");
-        }).pipe(
-          Effect.provide(
-            mockSpawnerLayer((args) => {
-              const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
-              if (joined === "auth status")
-                return { stdout: "Not logged in\n", stderr: "", code: 1 };
-              throw new Error(`Unexpected args: ${joined}`);
-            }),
-          ),
-        ),
-      );
-
-      it.effect("returns warning when auth status command is unsupported", () =>
+      it.effect("returns warning when the Claude initialization result is unavailable", () =>
         Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          assert.strictEqual(status.provider, "claudeAgent");
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            noClaudeCapabilities,
+          );
           assert.strictEqual(status.status, "warning");
           assert.strictEqual(status.installed, true);
           assert.strictEqual(status.auth.status, "unknown");
           assert.strictEqual(
             status.message,
-            "Claude Agent authentication status command is unavailable in this version of Claude.",
+            "Could not verify Claude authentication status from initialization result.",
           );
         }).pipe(
           Effect.provide(
@@ -1135,52 +1725,16 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
               const joined = args.join(" ");
               if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
               if (joined === "auth status")
-                return { stdout: "", stderr: "error: unknown command 'auth'", code: 2 };
+                return {
+                  stdout: '{"loggedIn":false}\n',
+                  stderr: "",
+                  code: 1,
+                };
               throw new Error(`Unexpected args: ${joined}`);
             }),
           ),
         ),
       );
     });
-
-    // ── parseClaudeAuthStatusFromOutput pure tests ────────────────────
-
-    describe("parseClaudeAuthStatusFromOutput", () => {
-      it("exit code 0 with no auth markers is ready", () => {
-        const parsed = parseClaudeAuthStatusFromOutput({ stdout: "OK\n", stderr: "", code: 0 });
-        assert.strictEqual(parsed.status, "ready");
-        assert.strictEqual(parsed.auth.status, "authenticated");
-      });
-
-      it("JSON with loggedIn=true is authenticated", () => {
-        const parsed = parseClaudeAuthStatusFromOutput({
-          stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
-          stderr: "",
-          code: 0,
-        });
-        assert.strictEqual(parsed.status, "ready");
-        assert.strictEqual(parsed.auth.status, "authenticated");
-      });
-
-      it("JSON with loggedIn=false is unauthenticated", () => {
-        const parsed = parseClaudeAuthStatusFromOutput({
-          stdout: '{"loggedIn":false}\n',
-          stderr: "",
-          code: 0,
-        });
-        assert.strictEqual(parsed.status, "error");
-        assert.strictEqual(parsed.auth.status, "unauthenticated");
-      });
-
-      it("JSON without auth marker is warning", () => {
-        const parsed = parseClaudeAuthStatusFromOutput({
-          stdout: '{"ok":true}\n',
-          stderr: "",
-          code: 0,
-        });
-        assert.strictEqual(parsed.status, "warning");
-        assert.strictEqual(parsed.auth.status, "unknown");
-      });
-    });
   },
 );
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.ts b/apps/server/src/provider/Layers/ProviderRegistry.ts
index fb2f33c2932..22a120f0a52 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.ts
@@ -1,96 +1,695 @@
 /**
- * ProviderRegistryLive - Aggregates provider-specific snapshot services.
+ * ProviderRegistryLive — aggregates per-instance snapshot streams into a
+ * single materialized list.
+ *
+ * Historically this Layer composed four per-kind Live Layers
+ * (`CodexProviderLive`, `ClaudeProviderLive`, …) that each exposed a
+ * `ServerProviderShape`. Those Lives were deleted during the driver /
+ * instance refactor — every driver now carries its `snapshot: ServerProviderShape`
+ * bundled onto the `ProviderInstance` the registry produces.
+ *
+ * Each configured instance (including multi-instance setups like
+ * `codex_personal` + `codex_work`) contributes one `ProviderSnapshotSource`,
+ * keyed by `instanceId`. Instances whose driver is unavailable or whose
+ * config failed to decode are merged from `instanceRegistry.listUnavailable`
+ * as shadow snapshots so the UI can render their exact unavailable reason.
+ *
+ * Cache paths on disk are now keyed by `instanceId`. Because
+ * `defaultInstanceIdForDriver(kind) === kind` for built-in kinds, existing
+ * `<kind>.json` files remain the on-disk location for that driver's default
+ * instance. Identity-less legacy cache contents are ignored and replaced by
+ * the first live refresh.
  *
  * @module ProviderRegistryLive
  */
-import type { ProviderKind, ServerProvider } from "@t3tools/contracts";
-import { Effect, Equal, Layer, PubSub, Ref, Stream } from "effect";
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProvider,
+  type ServerProviderUpdateState,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+import * as Semaphore from "effect/Semaphore";
 
-import { ClaudeProviderLive } from "./ClaudeProvider";
-import { CodexProviderLive } from "./CodexProvider";
-import type { ClaudeProviderShape } from "../Services/ClaudeProvider";
-import { ClaudeProvider } from "../Services/ClaudeProvider";
-import type { CodexProviderShape } from "../Services/CodexProvider";
-import { CodexProvider } from "../Services/CodexProvider";
-import { ProviderRegistry, type ProviderRegistryShape } from "../Services/ProviderRegistry";
+import { ServerConfig } from "../../config.ts";
+import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
+import { ProviderRegistry, type ProviderRegistryShape } from "../Services/ProviderRegistry.ts";
+import {
+  hydrateCachedProvider,
+  isCachedProviderCorrelated,
+  orderProviderSnapshots,
+  readProviderStatusCache,
+  resolveProviderStatusCachePath,
+  writeProviderStatusCache,
+} from "../providerStatusCache.ts";
+import type { ProviderInstance } from "../ProviderDriver.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
+import type { ProviderSnapshotSource } from "../builtInProviderCatalog.ts";
 
 const loadProviders = (
-  codexProvider: CodexProviderShape,
-  claudeProvider: ClaudeProviderShape,
-): Effect.Effect<readonly [ServerProvider, ServerProvider]> =>
-  Effect.all([codexProvider.getSnapshot, claudeProvider.getSnapshot], {
-    concurrency: "unbounded",
+  providerSources: ReadonlyArray<ProviderSnapshotSource>,
+): Effect.Effect<ReadonlyArray<ServerProvider>> =>
+  Effect.forEach(
+    providerSources,
+    (providerSource) =>
+      providerSource.getSnapshot.pipe(
+        Effect.flatMap((snapshot) => correlateSnapshotWithSource(providerSource, snapshot)),
+      ),
+    {
+      concurrency: "unbounded",
+    },
+  );
+
+const makeManualProviderMaintenanceCapabilities = (provider: ProviderDriverKind) =>
+  makeManualOnlyProviderMaintenanceCapabilities({
+    provider,
+    packageName: null,
   });
 
+const hasModelCapabilities = (model: ServerProvider["models"][number]): boolean =>
+  (model.capabilities?.optionDescriptors?.length ?? 0) > 0;
+
+const mergeProviderModels = (
+  previousModels: ReadonlyArray<ServerProvider["models"][number]>,
+  nextModels: ReadonlyArray<ServerProvider["models"][number]>,
+): ReadonlyArray<ServerProvider["models"][number]> => {
+  if (nextModels.length === 0 && previousModels.length > 0) {
+    return previousModels;
+  }
+
+  const previousBySlug = new Map(previousModels.map((model) => [model.slug, model] as const));
+  const mergedModels = nextModels.map((model) => {
+    const previousModel = previousBySlug.get(model.slug);
+    if (!previousModel || hasModelCapabilities(model) || !hasModelCapabilities(previousModel)) {
+      return model;
+    }
+    return {
+      ...model,
+      capabilities: previousModel.capabilities,
+    };
+  });
+  const nextSlugs = new Set(nextModels.map((model) => model.slug));
+  return [...mergedModels, ...previousModels.filter((model) => !nextSlugs.has(model.slug))];
+};
+
+export const mergeProviderSnapshot = (
+  previousProvider: ServerProvider | undefined,
+  nextProvider: ServerProvider,
+): ServerProvider =>
+  !previousProvider
+    ? nextProvider
+    : {
+        ...nextProvider,
+        models: mergeProviderModels(previousProvider.models, nextProvider.models),
+      };
+
+export const mergeProviderSnapshots = (
+  previousProviders: ReadonlyArray<ServerProvider>,
+  nextProviders: ReadonlyArray<ServerProvider>,
+): ReadonlyArray<ServerProvider> => {
+  const mergedProviders = new Map(
+    previousProviders.map((provider) => [snapshotInstanceKey(provider), provider] as const),
+  );
+
+  for (const provider of nextProviders) {
+    mergedProviders.set(
+      snapshotInstanceKey(provider),
+      mergeProviderSnapshot(mergedProviders.get(snapshotInstanceKey(provider)), provider),
+    );
+  }
+
+  return orderProviderSnapshots([...mergedProviders.values()]);
+};
+
+export const selectProvidersByKind = (
+  providers: ReadonlyArray<ServerProvider>,
+  providerKinds: ReadonlySet<ProviderDriverKind>,
+): ReadonlyArray<ServerProvider> =>
+  providers.filter((provider) => providerKinds.has(provider.driver));
+
 export const haveProvidersChanged = (
   previousProviders: ReadonlyArray<ServerProvider>,
   nextProviders: ReadonlyArray<ServerProvider>,
 ): boolean => !Equal.equals(previousProviders, nextProviders);
 
+const correlateSnapshotWithSource = (
+  source: ProviderSnapshotSource,
+  snapshot: ServerProvider,
+): Effect.Effect<ServerProvider> => {
+  if (snapshot.instanceId !== source.instanceId) {
+    return Effect.die(
+      new Error(
+        `Provider snapshot instance mismatch: source '${source.instanceId}' emitted '${snapshot.instanceId}'.`,
+      ),
+    );
+  }
+  if (snapshot.driver !== source.driverKind) {
+    return Effect.die(
+      new Error(
+        `Provider snapshot driver mismatch for instance '${source.instanceId}': source '${source.driverKind}' emitted '${snapshot.driver}'.`,
+      ),
+    );
+  }
+  return Effect.succeed(snapshot);
+};
+
+/**
+ * Key a snapshot for aggregation and persistence. Snapshot sources
+ * must be correlated by instance id before reaching this map; missing
+ * identities are defects, not runtime routing fallbacks.
+ */
+const snapshotInstanceKey = (provider: ServerProvider): ProviderInstanceId => {
+  return provider.instanceId;
+};
+
+// Project a live `ProviderInstance` into the aggregator's consumption
+// shape. Each call re-captures the instance's `snapshot` closures, so
+// after `ProviderInstanceRegistry` rebuilds an instance (e.g. because
+// its settings changed), a fresh source rides the new PubSub instead
+// of a closed one.
+const buildSnapshotSource = (instance: ProviderInstance): ProviderSnapshotSource => ({
+  instanceId: instance.instanceId,
+  driverKind: instance.driverKind,
+  getSnapshot: instance.snapshot.getSnapshot,
+  refresh: instance.snapshot.refresh,
+  streamChanges: instance.snapshot.streamChanges,
+});
+
 export const ProviderRegistryLive = Layer.effect(
   ProviderRegistry,
   Effect.gen(function* () {
-    const codexProvider = yield* CodexProvider;
-    const claudeProvider = yield* ClaudeProvider;
+    const instanceRegistry = yield* ProviderInstanceRegistry;
+    const config = yield* ServerConfig;
+    const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+
+    // Aggregator PubSub — consumers (WS gateway, etc.) subscribe here for
+    // coalesced updates across every instance.
     const changesPubSub = yield* Effect.acquireRelease(
       PubSub.unbounded<ReadonlyArray<ServerProvider>>(),
       PubSub.shutdown,
     );
-    const providersRef = yield* Ref.make<ReadonlyArray<ServerProvider>>(
-      yield* loadProviders(codexProvider, claudeProvider),
+
+    // Boot-only: hydrate `providersRef` from the on-disk per-instance
+    // cache so the UI has something to render during the first refresh.
+    // Instances added post-boot skip this path; their first entry in
+    // `providersRef` comes from the reactive `syncLiveSources` pass
+    // below.
+    const bootInstances = yield* instanceRegistry.listInstances;
+    const bootSources = bootInstances.map(buildSnapshotSource);
+    const fallbackProviders = yield* loadProviders(bootSources);
+    const fallbackByInstance = new Map<ProviderInstanceId, ServerProvider>();
+    for (let index = 0; index < fallbackProviders.length; index++) {
+      const provider = fallbackProviders[index];
+      const source = bootSources[index];
+      if (provider === undefined || source === undefined) {
+        continue;
+      }
+      fallbackByInstance.set(source.instanceId, provider);
+    }
+
+    const cachedProviders = yield* Effect.forEach(
+      bootSources,
+      (source) =>
+        Effect.gen(function* () {
+          // One cache file per configured instance. For the default
+          // instance of a built-in kind the path equals `<kind>.json` —
+          // identical to the legacy filename. We still require the cache
+          // payload to carry matching instance id + driver kind; old
+          // identity-less payloads are discarded and the awaited refresh
+          // below repopulates the cache.
+          const filePath = yield* resolveProviderStatusCachePath({
+            cacheDir: config.providerStatusCacheDir,
+            instanceId: source.instanceId,
+          }).pipe(Effect.provideService(Path.Path, path));
+          const fallbackProvider = fallbackByInstance.get(source.instanceId);
+          if (fallbackProvider === undefined) {
+            return undefined;
+          }
+          return yield* readProviderStatusCache(filePath).pipe(
+            Effect.provideService(FileSystem.FileSystem, fileSystem),
+            Effect.flatMap((cachedProvider) => {
+              if (cachedProvider === undefined) {
+                return Effect.void.pipe(Effect.as(undefined as ServerProvider | undefined));
+              }
+              const correlation = {
+                cachedProvider,
+                fallbackProvider,
+              } as const;
+              if (!isCachedProviderCorrelated(correlation)) {
+                return Effect.logWarning("provider status cache identity mismatch, ignoring", {
+                  path: filePath,
+                  instanceId: source.instanceId,
+                  cachedInstanceId: cachedProvider.instanceId ?? null,
+                  driver: source.driverKind,
+                  cachedDriver: cachedProvider.driver ?? null,
+                }).pipe(Effect.as(undefined as ServerProvider | undefined));
+              }
+              return Effect.succeed(hydrateCachedProvider(correlation));
+            }),
+          );
+        }),
+      { concurrency: "unbounded" },
+    ).pipe(
+      Effect.map((providers) =>
+        orderProviderSnapshots(
+          providers.filter((provider): provider is ServerProvider => provider !== undefined),
+        ),
+      ),
+    );
+    const providersRef = yield* Ref.make<ReadonlyArray<ServerProvider>>(cachedProviders);
+    const maintenanceActionStatesRef = yield* Ref.make<
+      ReadonlyMap<ProviderInstanceId, { readonly update?: ServerProviderUpdateState | undefined }>
+    >(new Map());
+
+    // Live-source registry — the dynamic counterpart to the boot-time
+    // `bootSources`. Keyed by `instanceId`; the stored `ProviderInstance`
+    // reference is used for identity equality so "no-op" reconciles
+    // (settings unchanged) skip re-subscribing + re-probing.
+    const liveSubsRef = yield* Ref.make<ReadonlyMap<ProviderInstanceId, ProviderInstance>>(
+      new Map(),
     );
+    // Serialize `syncLiveSources` so a rapid burst of reconciles doesn't
+    // interleave two passes clobbering each other's fiber bookkeeping.
+    const syncSemaphore = yield* Semaphore.make(1);
+
+    const getLiveSources: Effect.Effect<ReadonlyArray<ProviderSnapshotSource>> = Ref.get(
+      liveSubsRef,
+    ).pipe(Effect.map((map) => Array.from(map.values(), buildSnapshotSource)));
 
-    const syncProviders = Effect.fn("syncProviders")(function* (options?: {
-      readonly publish?: boolean;
-    }) {
-      const previousProviders = yield* Ref.get(providersRef);
-      const providers = yield* loadProviders(codexProvider, claudeProvider);
-      yield* Ref.set(providersRef, providers);
+    const persistProvider = (provider: ServerProvider) =>
+      Effect.gen(function* () {
+        // Persist every instance — the file name is the instance id, so
+        // multi-instance setups (e.g. `codex_personal`, `codex_work`) each
+        // get their own cache. We resolve the path fresh so snapshots
+        // produced by newly-added instances post-boot still land on disk
+        // without the aggregator holding a stale `cachePathByInstance`
+        // entry.
+        const key = snapshotInstanceKey(provider);
+        const filePath = yield* resolveProviderStatusCachePath({
+          cacheDir: config.providerStatusCacheDir,
+          instanceId: key,
+        }).pipe(Effect.provideService(Path.Path, path));
+        yield* writeProviderStatusCache({ filePath, provider }).pipe(
+          Effect.provideService(FileSystem.FileSystem, fileSystem),
+          Effect.provideService(Path.Path, path),
+          Effect.tapError(Effect.logError),
+          Effect.ignore,
+        );
+      });
 
-      if (options?.publish !== false && haveProvidersChanged(previousProviders, providers)) {
-        yield* PubSub.publish(changesPubSub, providers);
+    const applyProviderUpdateState = Effect.fn("applyProviderUpdateState")(function* (
+      provider: ServerProvider,
+    ) {
+      const maintenanceActionStates = yield* Ref.get(maintenanceActionStatesRef);
+      const updateState = maintenanceActionStates.get(provider.instanceId)?.update;
+      if (!updateState) {
+        const { updateState: _updateState, ...providerWithoutUpdateState } = provider;
+        return providerWithoutUpdateState;
+      }
+      return {
+        ...provider,
+        updateState,
+      };
+    });
+
+    const upsertProviders = Effect.fn("upsertProviders")(function* (
+      nextProviders: ReadonlyArray<ServerProvider>,
+      options?: {
+        readonly publish?: boolean;
+        readonly persist?: boolean;
+        readonly replace?: boolean;
+      },
+    ) {
+      const nextProvidersWithUpdateState = yield* Effect.forEach(
+        nextProviders,
+        applyProviderUpdateState,
+        {
+          concurrency: "unbounded",
+        },
+      );
+      const [previousProviders, providers, providersToPersist] = yield* Ref.modify(
+        providersRef,
+        (previousProviders) => {
+          const mergedProviders = new Map(
+            previousProviders.map((provider) => [snapshotInstanceKey(provider), provider] as const),
+          );
+          const updatedKeys = new Set<ProviderInstanceId>();
+
+          for (const provider of nextProvidersWithUpdateState) {
+            const key = snapshotInstanceKey(provider);
+            updatedKeys.add(key);
+            mergedProviders.set(
+              key,
+              options?.replace === true
+                ? provider
+                : mergeProviderSnapshot(mergedProviders.get(key), provider),
+            );
+          }
+
+          const providers = orderProviderSnapshots([...mergedProviders.values()]);
+          const providersToPersist = providers.filter((provider) =>
+            updatedKeys.has(snapshotInstanceKey(provider)),
+          );
+          return [[previousProviders, providers, providersToPersist] as const, providers];
+        },
+      );
+
+      if (haveProvidersChanged(previousProviders, providers)) {
+        if (options?.persist !== false) {
+          yield* Effect.forEach(providersToPersist, persistProvider, {
+            concurrency: "unbounded",
+            discard: true,
+          });
+        }
+        if (options?.publish !== false) {
+          yield* PubSub.publish(changesPubSub, providers);
+        }
       }
 
       return providers;
     });
 
-    yield* Stream.runForEach(codexProvider.streamChanges, () => syncProviders()).pipe(
-      Effect.forkScoped,
+    const syncProvider = Effect.fn("syncProvider")(function* (
+      provider: ServerProvider,
+      options?: {
+        readonly publish?: boolean;
+      },
+    ) {
+      return yield* upsertProviders([provider], options);
+    });
+
+    const setProviderMaintenanceActionState = Effect.fn("setProviderMaintenanceActionState")(
+      function* (input: {
+        readonly instanceId: ProviderInstanceId;
+        readonly action: "update";
+        readonly state: ServerProviderUpdateState | null;
+      }) {
+        yield* Ref.update(maintenanceActionStatesRef, (previous) => {
+          const previousActions = previous.get(input.instanceId);
+          const nextActions = { ...previousActions };
+          if (input.state === null || input.state.status === "idle") {
+            delete nextActions[input.action];
+          } else {
+            nextActions[input.action] = input.state;
+          }
+
+          const next = new Map(previous);
+          if (Object.keys(nextActions).length === 0) {
+            next.delete(input.instanceId);
+          } else {
+            next.set(input.instanceId, nextActions);
+          }
+          return next;
+        });
+
+        const existingProviders = yield* Ref.get(providersRef);
+        const matchingProvider = existingProviders.find(
+          (candidate) => candidate.instanceId === input.instanceId,
+        );
+        if (!matchingProvider) {
+          return existingProviders;
+        }
+
+        const nextProvider = yield* applyProviderUpdateState(matchingProvider);
+        return yield* upsertProviders([nextProvider], {
+          persist: false,
+        });
+      },
+    );
+
+    const refreshOneSource = Effect.fn("refreshOneSource")(function* (
+      providerSource: ProviderSnapshotSource,
+    ) {
+      return yield* providerSource.refresh.pipe(
+        Effect.flatMap((nextProvider) =>
+          correlateSnapshotWithSource(providerSource, nextProvider).pipe(
+            Effect.flatMap(syncProvider),
+          ),
+        ),
+      );
+    });
+
+    const refreshAll = Effect.fn("refreshAll")(function* () {
+      const sources = yield* getLiveSources;
+      return yield* Effect.forEach(sources, (source) => refreshOneSource(source), {
+        concurrency: "unbounded",
+        discard: true,
+      }).pipe(Effect.andThen(Ref.get(providersRef)));
+    });
+
+    const refresh = Effect.fn("refresh")(function* (provider?: ProviderDriverKind) {
+      if (provider === undefined) {
+        return yield* refreshAll();
+      }
+      // Kind-scoped refreshes target the default instance for that driver.
+      const defaultInstanceId = defaultInstanceIdForDriver(provider);
+      const sources = yield* getLiveSources;
+      const providerSource = sources.find(
+        (candidate) => candidate.instanceId === defaultInstanceId,
+      );
+      if (!providerSource) {
+        return yield* Ref.get(providersRef);
+      }
+      return yield* refreshOneSource(providerSource);
+    });
+
+    const refreshInstance = Effect.fn("refreshInstance")(function* (
+      instanceId: ProviderInstanceId,
+    ) {
+      const sources = yield* getLiveSources;
+      const providerSource = sources.find((candidate) => candidate.instanceId === instanceId);
+      if (!providerSource) {
+        return yield* Ref.get(providersRef);
+      }
+      return yield* refreshOneSource(providerSource);
+    });
+
+    const getProviderMaintenanceCapabilitiesForInstance = Effect.fn(
+      "getProviderMaintenanceCapabilitiesForInstance",
+    )(function* (instanceId: ProviderInstanceId, provider: ProviderDriverKind) {
+      const instance = Array.from((yield* Ref.get(liveSubsRef)).values()).find(
+        (candidate) => candidate.instanceId === instanceId,
+      );
+      return (
+        instance?.snapshot.maintenanceCapabilities ??
+        makeManualProviderMaintenanceCapabilities(provider)
+      );
+    });
+
+    /**
+     * Diff the aggregator's live-source set against the current
+     * `ProviderInstanceRegistry` and:
+     *   - subscribe to each newly-added or rebuilt instance's
+     *     `streamChanges` (so periodic + enrichment refreshes land in
+     *     `providersRef`);
+     *   - force-refresh each newly-added/rebuilt instance and feed the
+     *     result directly into `providersRef`, bypassing the PubSub
+     *     attachment race that otherwise drops the initial probe;
+     *   - prune `providersRef` of instances that no longer exist.
+     *
+     * Initial refreshes are awaited in parallel rather than forked, so
+     * callers (layer build; `streamChanges` watcher) see fully-probed
+     * state on return. This matters for layer build in particular:
+     * consumers reading `getProviders` immediately after layer build
+     * expect the probe to have already landed.
+     *
+     * Per-instance subscription fibers are not tracked explicitly. When
+     * a rebuilt instance's old child scope closes, its PubSub shuts
+     * down and our `Stream.runForEach` fiber exits naturally.
+     */
+    const syncLiveSources = syncSemaphore.withPermits(1)(
+      Effect.gen(function* () {
+        const instances = yield* instanceRegistry.listInstances;
+        const unavailableProviders = yield* instanceRegistry.listUnavailable;
+        const nextByInstance = new Map<ProviderInstanceId, ProviderInstance>(
+          instances.map((instance) => [instance.instanceId, instance] as const),
+        );
+        const knownInstanceIds = new Set<ProviderInstanceId>(nextByInstance.keys());
+        for (const provider of unavailableProviders) {
+          knownInstanceIds.add(snapshotInstanceKey(provider));
+        }
+        const previousSubs = yield* Ref.get(liveSubsRef);
+
+        // Carry over subscriptions for instances whose identity is
+        // unchanged (reconcile treated them as no-op). Instances that
+        // disappeared, or were rebuilt with a different reference,
+        // fall through to the "newly-added" branch below.
+        const carriedOver = new Map<ProviderInstanceId, ProviderInstance>();
+        for (const [instanceId, previousInstance] of previousSubs) {
+          const nextInstance = nextByInstance.get(instanceId);
+          if (nextInstance !== undefined && nextInstance === previousInstance) {
+            carriedOver.set(instanceId, previousInstance);
+          }
+        }
+
+        // Collect new/rebuilt instances in `nextByInstance` insertion
+        // order (which preserves settings-author order).
+        const newlyAdded: Array<readonly [ProviderInstanceId, ProviderInstance]> = [];
+        for (const [instanceId, instance] of nextByInstance) {
+          if (carriedOver.has(instanceId)) {
+            continue;
+          }
+          newlyAdded.push([instanceId, instance] as const);
+        }
+
+        // Fork long-lived subscriptions to each new/rebuilt instance's
+        // change stream BEFORE kicking off refreshes — if the driver's
+        // own initial probe (line 140 in `makeManagedServerProvider`)
+        // wins the refreshSemaphore race, its PubSub publish must land
+        // in an active subscriber or the result is dropped.
+        for (const [, instance] of newlyAdded) {
+          const source = buildSnapshotSource(instance);
+          yield* Stream.runForEach(source.streamChanges, (provider) =>
+            correlateSnapshotWithSource(source, provider).pipe(Effect.flatMap(syncProvider)),
+          ).pipe(Effect.forkScoped);
+        }
+
+        // Force-refresh every new/rebuilt instance in parallel and wait
+        // for them all to complete. The refresh's result is piped
+        // directly into `syncProvider`, so `providersRef` is populated
+        // deterministically by the time this block returns — regardless
+        // of PubSub subscription timing. Failures are logged and
+        // swallowed so one bad driver can't wedge the whole registry.
+        yield* Effect.forEach(
+          newlyAdded,
+          ([, instance]) =>
+            refreshOneSource(buildSnapshotSource(instance)).pipe(Effect.ignoreCause({ log: true })),
+          { concurrency: "unbounded", discard: true },
+        );
+        yield* upsertProviders(unavailableProviders, {
+          persist: false,
+          replace: true,
+        });
+
+        const nextSubs = new Map(carriedOver);
+        for (const [instanceId, instance] of newlyAdded) {
+          nextSubs.set(instanceId, instance);
+        }
+        yield* Ref.set(liveSubsRef, nextSubs);
+
+        // Drop aggregator state for instances that have disappeared —
+        // otherwise the UI would keep rendering ghosts.
+        const [previousProviders, providers] = yield* Ref.modify(
+          providersRef,
+          (previousProviders) => {
+            const providers = orderProviderSnapshots(
+              previousProviders.filter((provider) =>
+                knownInstanceIds.has(snapshotInstanceKey(provider)),
+              ),
+            );
+            return [[previousProviders, providers] as const, providers];
+          },
+        );
+        if (haveProvidersChanged(previousProviders, providers)) {
+          yield* PubSub.publish(changesPubSub, providers);
+        }
+        yield* Ref.update(maintenanceActionStatesRef, (previous) => {
+          const next = new Map(previous);
+          for (const instanceId of previous.keys()) {
+            if (!knownInstanceIds.has(instanceId)) {
+              next.delete(instanceId);
+            }
+          }
+          return next;
+        });
+      }),
     );
-    yield* Stream.runForEach(claudeProvider.streamChanges, () => syncProviders()).pipe(
-      Effect.forkScoped,
+    const syncLiveSourcesAndContinue = syncLiveSources.pipe(
+      Effect.catchCause((cause) => {
+        if (Cause.hasInterruptsOnly(cause)) {
+          return Effect.interrupt;
+        }
+        return Effect.logError(
+          "provider registry instance sync failed; keeping subscription alive",
+          {
+            cause: Cause.pretty(cause),
+          },
+        );
+      }),
     );
 
-    const refresh = Effect.fn("refresh")(function* (provider?: ProviderKind) {
-      switch (provider) {
-        case "codex":
-          yield* codexProvider.refresh;
-          break;
-        case "claudeAgent":
-          yield* claudeProvider.refresh;
-          break;
-        default:
-          yield* Effect.all([codexProvider.refresh, claudeProvider.refresh], {
-            concurrency: "unbounded",
-          });
-          break;
+    // Seed `providersRef` with the boot-time fallback snapshots so
+    // consumers calling `getProviders` immediately after layer build see
+    // a populated list — even before the first `syncLiveSources` refresh
+    // resolves. Cached snapshots (already in `providersRef`) merge with
+    // these via `upsertProviders` so on-disk state wins where present
+    // and pending fallbacks fill the gaps.
+    yield* upsertProviders(fallbackProviders, { publish: false });
+    // Subscribe to registry mutations BEFORE running the initial sync.
+    // `subscribeChanges` acquires the dequeue synchronously in this
+    // fibre; the subscription is active the instant this `yield*`
+    // returns. Forking the consumer loop later cannot lose a publish
+    // because no publish can reach a not-yet-subscribed dequeue.
+    //
+    // (Contrast with the pre-fix code that did
+    // `Stream.runForEach(instanceRegistry.streamChanges, …).pipe(Effect.forkScoped)`.
+    // `Stream.fromPubSub` defers `PubSub.subscribe` to stream start,
+    // and `forkScoped` only schedules the fibre — so a reconcile that
+    // published between "fibre scheduled" and "fibre starts running"
+    // was dropped, which made any settings change that replaced an
+    // instance never propagate to the aggregator's `providersRef`.)
+    // Subscribe to registry mutations BEFORE running the initial sync.
+    // `subscribeChanges` acquires the `PubSub.Subscription` synchronously
+    // in this fibre; the subscription is registered with the PubSub the
+    // instant this `yield*` returns, so any subsequent publish is
+    // buffered in the subscription regardless of when the consumer
+    // fibre below actually starts running.
+    //
+    // (Contrast with the pre-fix code that did
+    // `Stream.runForEach(instanceRegistry.streamChanges, …).pipe(Effect.forkScoped)`.
+    // `instanceRegistry.streamChanges` is `Stream.fromPubSub(changes)`,
+    // which defers `PubSub.subscribe` to stream start. `forkScoped` only
+    // schedules the consumer fibre — so a reconcile that published
+    // between "fibre scheduled" and "fibre starts running + subscribes"
+    // was dropped, which made any settings change that replaced an
+    // instance never propagate to the aggregator's `providersRef`.)
+    const instanceChanges = yield* instanceRegistry.subscribeChanges;
+    // Initial sync: subscribe + kick off refreshes for every instance
+    // present at boot. Run synchronously so consumers pulling immediately
+    // after the layer build see the correct aggregator state.
+    yield* syncLiveSources;
+    // React to registry mutations — instance added / removed / rebuilt.
+    // `Stream.fromSubscription` builds a stream over the pre-acquired
+    // subscription rather than subscribing on stream start, which is
+    // what closes the race.
+    yield* Stream.runForEach(
+      Stream.fromSubscription(instanceChanges),
+      () => syncLiveSourcesAndContinue,
+    ).pipe(Effect.forkScoped);
+
+    const recoverRefreshFailure = Effect.fn("recoverRefreshFailure")(function* (
+      cause: Cause.Cause<unknown>,
+    ) {
+      if (Cause.hasInterruptsOnly(cause)) {
+        return yield* Effect.interrupt;
       }
-      return yield* syncProviders();
+      yield* Effect.logError("provider registry refresh failed; preserving cached providers", {
+        cause: Cause.pretty(cause),
+      });
+      return yield* Ref.get(providersRef);
     });
 
     return {
-      getProviders: syncProviders({ publish: false }).pipe(
-        Effect.tapError(Effect.logError),
-        Effect.orElseSucceed(() => []),
-      ),
-      refresh: (provider?: ProviderKind) =>
-        refresh(provider).pipe(
-          Effect.tapError(Effect.logError),
-          Effect.orElseSucceed(() => []),
-        ),
+      getProviders: Ref.get(providersRef),
+      refresh: (provider?: ProviderDriverKind) =>
+        refresh(provider).pipe(Effect.catchCause(recoverRefreshFailure)),
+      refreshInstance: (instanceId: ProviderInstanceId) =>
+        refreshInstance(instanceId).pipe(Effect.catchCause(recoverRefreshFailure)),
+      getProviderMaintenanceCapabilitiesForInstance,
+      setProviderMaintenanceActionState,
       get streamChanges() {
         return Stream.fromPubSub(changesPubSub);
       },
     } satisfies ProviderRegistryShape;
   }),
-).pipe(Layer.provideMerge(CodexProviderLive), Layer.provideMerge(ClaudeProviderLive));
+);
diff --git a/apps/server/src/provider/Layers/ProviderService.test.ts b/apps/server/src/provider/Layers/ProviderService.test.ts
index 56f9f8d65c4..fc0450b8b69 100644
--- a/apps/server/src/provider/Layers/ProviderService.test.ts
+++ b/apps/server/src/provider/Layers/ProviderService.test.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -12,28 +13,44 @@ import type {
 import {
   ApprovalRequestId,
   EventId,
-  type ProviderKind,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ProviderSessionStartInput,
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import { it, assert, vi } from "@effect/vitest";
-import { assertFailure } from "@effect/vitest/utils";
 
-import { Effect, Fiber, Layer, Metric, Option, PubSub, Ref, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Metric from "effect/Metric";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import {
+  ProviderAdapterRequestError,
   ProviderAdapterSessionNotFoundError,
   ProviderUnsupportedError,
   ProviderValidationError,
   type ProviderAdapterError,
 } from "../Errors.ts";
 import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
-import { ProviderAdapterRegistry } from "../Services/ProviderAdapterRegistry.ts";
+import {
+  ProviderAdapterRegistry,
+  type ProviderAdapterRegistryShape,
+} from "../Services/ProviderAdapterRegistry.ts";
 import { ProviderService } from "../Services/ProviderService.ts";
 import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
 import { makeProviderServiceLive } from "./ProviderService.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "./ProviderEventLoggers.ts";
 import { ProviderSessionDirectoryLive } from "./ProviderSessionDirectory.ts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { ProviderSessionRuntimeRepositoryLive } from "../../persistence/Layers/ProviderSessionRuntime.ts";
@@ -44,6 +61,7 @@ import {
 } from "../../persistence/Layers/Sqlite.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { AnalyticsService } from "../../telemetry/Services/AnalyticsService.ts";
+import { makeAdapterRegistryMock } from "../testUtils/providerAdapterRegistryMock.ts";
 
 const defaultServerSettingsLayer = ServerSettingsService.layerTest();
 
@@ -51,11 +69,16 @@ const asRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.make
 const asEventId = (value: string): EventId => EventId.make(value);
 const asThreadId = (value: string): ThreadId => ThreadId.make(value);
 const asTurnId = (value: string): TurnId => TurnId.make(value);
+const codexInstanceId = ProviderInstanceId.make("codex");
+const claudeAgentInstanceId = ProviderInstanceId.make("claudeAgent");
+const CODEX_DRIVER = ProviderDriverKind.make("codex");
+const CLAUDE_AGENT_DRIVER = ProviderDriverKind.make("claudeAgent");
+const CURSOR_DRIVER = ProviderDriverKind.make("cursor");
 
 type LegacyProviderRuntimeEvent = {
   readonly type: string;
   readonly eventId: EventId;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly createdAt: string;
   readonly threadId: ThreadId;
   readonly turnId?: string | undefined;
@@ -65,19 +88,24 @@ type LegacyProviderRuntimeEvent = {
   readonly [key: string]: unknown;
 };
 
-function makeFakeCodexAdapter(provider: ProviderKind = "codex") {
+function makeFakeCodexAdapter(provider: ProviderDriverKind = CODEX_DRIVER) {
   const sessions = new Map<ThreadId, ProviderSession>();
   const runtimeEventPubSub = Effect.runSync(PubSub.unbounded<ProviderRuntimeEvent>());
 
   const startSession = vi.fn((input: ProviderSessionStartInput) =>
     Effect.sync(() => {
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
       const session: ProviderSession = {
         provider,
+        ...(input.providerInstanceId !== undefined
+          ? { providerInstanceId: input.providerInstanceId }
+          : {}),
         status: "ready",
         runtimeMode: input.runtimeMode,
         threadId: input.threadId,
-        resumeCursor: input.resumeCursor ?? { opaque: `resume-${String(input.threadId)}` },
+        resumeCursor: input.resumeCursor ?? {
+          opaque: `resume-${String(input.threadId)}`,
+        },
         cwd: input.cwd ?? process.cwd(),
         createdAt: now,
         updatedAt: now,
@@ -229,8 +257,8 @@ function makeFakeCodexAdapter(provider: ProviderKind = "codex") {
   };
 }
 
-const sleep = (ms: number) =>
-  Effect.promise(() => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+const advanceTestClock = (ms: number) =>
+  TestClock.adjust(`${ms} millis`).pipe(Effect.andThen(Effect.yieldNow));
 
 const hasMetricSnapshot = (
   snapshots: ReadonlyArray<Metric.Metric.Snapshot>,
@@ -245,16 +273,13 @@ const hasMetricSnapshot = (
 
 function makeProviderServiceLayer() {
   const codex = makeFakeCodexAdapter();
-  const claude = makeFakeCodexAdapter("claudeAgent");
-  const registry: typeof ProviderAdapterRegistry.Service = {
-    getByProvider: (provider) =>
-      provider === "codex"
-        ? Effect.succeed(codex.adapter)
-        : provider === "claudeAgent"
-          ? Effect.succeed(claude.adapter)
-          : Effect.fail(new ProviderUnsupportedError({ provider })),
-    listProviders: () => Effect.succeed(["codex", "claudeAgent"]),
-  };
+  const claude = makeFakeCodexAdapter(CLAUDE_AGENT_DRIVER);
+  const cursor = makeFakeCodexAdapter(CURSOR_DRIVER);
+  const registry = makeAdapterRegistryMock({
+    [ProviderDriverKind.make("codex")]: codex.adapter,
+    [ProviderDriverKind.make("claudeAgent")]: claude.adapter,
+    [ProviderDriverKind.make("cursor")]: cursor.adapter,
+  });
 
   const providerAdapterLayer = Layer.succeed(ProviderAdapterRegistry, registry);
   const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
@@ -269,6 +294,7 @@ function makeProviderServiceLayer() {
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provideMerge(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
       ),
       directoryLayer,
 
@@ -280,31 +306,81 @@ function makeProviderServiceLayer() {
   return {
     codex,
     claude,
+    cursor,
     layer,
   };
 }
 
+it.effect("ProviderServiceLive catches stopAll failures during shutdown", () =>
+  Effect.gen(function* () {
+    const codex = makeFakeCodexAdapter();
+    codex.stopAll.mockImplementation(() =>
+      Effect.fail(
+        new ProviderAdapterRequestError({
+          provider: String(CODEX_DRIVER),
+          method: "stopAll",
+          detail: "simulated stopAll failure",
+        }),
+      ),
+    );
+    const registry = makeAdapterRegistryMock({
+      [CODEX_DRIVER]: codex.adapter,
+    });
+    const providerAdapterLayer = Layer.succeed(ProviderAdapterRegistry, registry);
+    const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
+      Layer.provide(SqlitePersistenceMemory),
+    );
+    const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
+    const providerLayer = Layer.mergeAll(
+      makeProviderServiceLive().pipe(
+        Layer.provide(providerAdapterLayer),
+        Layer.provide(directoryLayer),
+        Layer.provide(defaultServerSettingsLayer),
+        Layer.provideMerge(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+      ),
+      directoryLayer,
+      runtimeRepositoryLayer,
+      NodeServices.layer,
+    );
+    const scope = yield* Scope.make();
+    const runtimeServices = yield* Layer.build(providerLayer).pipe(Scope.provide(scope));
+
+    yield* Effect.gen(function* () {
+      yield* ProviderService;
+    }).pipe(Effect.provide(runtimeServices));
+    const closeExit = yield* Scope.close(scope, Exit.void).pipe(Effect.exit);
+
+    assert.equal(Exit.isSuccess(closeExit), true);
+    assert.equal(codex.stopAll.mock.calls.length, 1);
+  }),
+);
+
 it.effect("ProviderServiceLive rejects new sessions for disabled providers", () =>
   Effect.gen(function* () {
     const codex = makeFakeCodexAdapter();
-    const claude = makeFakeCodexAdapter("claudeAgent");
-    const registry: typeof ProviderAdapterRegistry.Service = {
-      getByProvider: (provider) =>
-        provider === "codex"
-          ? Effect.succeed(codex.adapter)
-          : provider === "claudeAgent"
-            ? Effect.succeed(claude.adapter)
-            : Effect.fail(new ProviderUnsupportedError({ provider })),
-      listProviders: () => Effect.succeed(["codex", "claudeAgent"]),
+    const claude = makeFakeCodexAdapter(CLAUDE_AGENT_DRIVER);
+    const registryBase = makeAdapterRegistryMock({
+      [CODEX_DRIVER]: codex.adapter,
+      [CLAUDE_AGENT_DRIVER]: claude.adapter,
+    });
+    const registry: ProviderAdapterRegistryShape = {
+      ...registryBase,
+      getInstanceInfo: (instanceId) =>
+        instanceId === claudeAgentInstanceId
+          ? Effect.succeed({
+              instanceId,
+              driverKind: CLAUDE_AGENT_DRIVER,
+              displayName: undefined,
+              enabled: false,
+              continuationIdentity: {
+                driverKind: CLAUDE_AGENT_DRIVER,
+                continuationKey: "claudeAgent:instance:claudeAgent",
+              },
+            })
+          : registryBase.getInstanceInfo(instanceId),
     };
     const providerAdapterLayer = Layer.succeed(ProviderAdapterRegistry, registry);
-    const serverSettingsLayer = ServerSettingsService.layerTest({
-      providers: {
-        claudeAgent: {
-          enabled: false,
-        },
-      },
-    });
     const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
       Layer.provide(SqlitePersistenceMemory),
     );
@@ -312,15 +388,17 @@ it.effect("ProviderServiceLive rejects new sessions for disabled providers", ()
     const providerLayer = makeProviderServiceLive().pipe(
       Layer.provide(providerAdapterLayer),
       Layer.provide(directoryLayer),
-      Layer.provide(serverSettingsLayer),
+      Layer.provide(defaultServerSettingsLayer),
       Layer.provide(AnalyticsService.layerTest),
+      Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
     );
 
     const failure = yield* Effect.flip(
       Effect.gen(function* () {
         const provider = yield* ProviderService;
         return yield* provider.startSession(asThreadId("thread-disabled"), {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
+          providerInstanceId: claudeAgentInstanceId,
           threadId: asThreadId("thread-disabled"),
           runtimeMode: "full-access",
         });
@@ -328,25 +406,212 @@ it.effect("ProviderServiceLive rejects new sessions for disabled providers", ()
     );
 
     assert.instanceOf(failure, ProviderValidationError);
-    assert.include(failure.issue, "Provider 'claudeAgent' is disabled in T3 Code settings.");
+    assert.include(failure.issue, "Provider instance 'claudeAgent' is disabled");
     assert.equal(claude.startSession.mock.calls.length, 0);
   }).pipe(Effect.provide(NodeServices.layer)),
 );
 
+it.effect(
+  "ProviderServiceLive allows enabled custom instances when legacy driver is disabled",
+  () =>
+    Effect.gen(function* () {
+      const instanceId = ProviderInstanceId.make("codex_personal");
+      const driverKind = CODEX_DRIVER;
+      const codex = makeFakeCodexAdapter();
+      const unsupported = () =>
+        new ProviderUnsupportedError({
+          provider: driverKind,
+        });
+      const registry: ProviderAdapterRegistryShape = {
+        getByInstance: (requestedInstanceId) =>
+          requestedInstanceId === instanceId
+            ? Effect.succeed(codex.adapter)
+            : Effect.fail(unsupported()),
+        getInstanceInfo: (requestedInstanceId) =>
+          requestedInstanceId === instanceId
+            ? Effect.succeed({
+                instanceId,
+                driverKind,
+                displayName: "Codex Personal",
+                enabled: true,
+                continuationIdentity: {
+                  driverKind,
+                  continuationKey: "codex:/Users/example/.codex",
+                },
+              })
+            : Effect.fail(unsupported()),
+        listInstances: () => Effect.succeed([instanceId]),
+        listProviders: () => Effect.succeed([driverKind] as const),
+        streamChanges: Stream.empty,
+        subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+          PubSub.subscribe(pubsub),
+        ),
+      };
+      const providerAdapterLayer = Layer.succeed(ProviderAdapterRegistry, registry);
+      const serverSettingsLayer = ServerSettingsService.layerTest({
+        providers: {
+          codex: {
+            enabled: false,
+          },
+        },
+      });
+      const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
+        Layer.provide(SqlitePersistenceMemory),
+      );
+      const directoryLayer = ProviderSessionDirectoryLive.pipe(
+        Layer.provide(runtimeRepositoryLayer),
+      );
+      const providerLayer = makeProviderServiceLive().pipe(
+        Layer.provide(providerAdapterLayer),
+        Layer.provide(directoryLayer),
+        Layer.provide(serverSettingsLayer),
+        Layer.provide(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+      );
+
+      const session = yield* Effect.gen(function* () {
+        const provider = yield* ProviderService;
+        return yield* provider.startSession(asThreadId("thread-enabled-custom"), {
+          provider: driverKind,
+          providerInstanceId: instanceId,
+          threadId: asThreadId("thread-enabled-custom"),
+          runtimeMode: "full-access",
+        });
+      }).pipe(Effect.provide(providerLayer));
+
+      assert.equal(session.providerInstanceId, instanceId);
+      assert.equal(codex.startSession.mock.calls.length, 1);
+    }).pipe(Effect.provide(NodeServices.layer)),
+);
+
+it.effect("ProviderServiceLive rejects new sessions for disabled custom instances", () =>
+  Effect.gen(function* () {
+    const instanceId = ProviderInstanceId.make("codex_personal");
+    const driverKind = ProviderDriverKind.make("codex");
+    const codex = makeFakeCodexAdapter();
+    const unsupported = () =>
+      new ProviderUnsupportedError({
+        provider: ProviderDriverKind.make("codex"),
+      });
+    const registry: ProviderAdapterRegistryShape = {
+      getByInstance: (requestedInstanceId) =>
+        requestedInstanceId === instanceId
+          ? Effect.succeed(codex.adapter)
+          : Effect.fail(unsupported()),
+      getInstanceInfo: (requestedInstanceId) =>
+        requestedInstanceId === instanceId
+          ? Effect.succeed({
+              instanceId,
+              driverKind,
+              displayName: "Codex Personal",
+              enabled: false,
+              continuationIdentity: {
+                driverKind,
+                continuationKey: "codex:/Users/example/.codex",
+              },
+            })
+          : Effect.fail(unsupported()),
+      listInstances: () => Effect.succeed([instanceId]),
+      listProviders: () => Effect.succeed([CODEX_DRIVER] as const),
+      streamChanges: Stream.empty,
+      subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+        PubSub.subscribe(pubsub),
+      ),
+    };
+    const providerAdapterLayer = Layer.succeed(ProviderAdapterRegistry, registry);
+    const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
+      Layer.provide(SqlitePersistenceMemory),
+    );
+    const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
+    const providerLayer = makeProviderServiceLive().pipe(
+      Layer.provide(providerAdapterLayer),
+      Layer.provide(directoryLayer),
+      Layer.provide(defaultServerSettingsLayer),
+      Layer.provide(AnalyticsService.layerTest),
+      Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+    );
+
+    const failure = yield* Effect.flip(
+      Effect.gen(function* () {
+        const provider = yield* ProviderService;
+        return yield* provider.startSession(asThreadId("thread-disabled-instance"), {
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: instanceId,
+          threadId: asThreadId("thread-disabled-instance"),
+          runtimeMode: "full-access",
+        });
+      }).pipe(Effect.provide(providerLayer)),
+    );
+
+    assert.instanceOf(failure, ProviderValidationError);
+    assert.include(failure.issue, "Provider instance 'codex_personal' is disabled");
+    assert.equal(codex.startSession.mock.calls.length, 0);
+  }).pipe(Effect.provide(NodeServices.layer)),
+);
+
 const routing = makeProviderServiceLayer();
+
+it.effect("ProviderServiceLive writes canonical events to the emitting thread segment", () =>
+  Effect.gen(function* () {
+    const codex = makeFakeCodexAdapter();
+    const canonicalEvents: ProviderRuntimeEvent[] = [];
+    const canonicalThreadIds: Array<string | null> = [];
+    const registry = makeAdapterRegistryMock({
+      [ProviderDriverKind.make("codex")]: codex.adapter,
+    });
+    const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
+      Layer.provide(SqlitePersistenceMemory),
+    );
+    const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
+    const providerLayer = makeProviderServiceLive({
+      canonicalEventLogger: {
+        filePath: "memory://provider-canonical-events",
+        write: (event, threadId) => {
+          canonicalEvents.push(event as ProviderRuntimeEvent);
+          canonicalThreadIds.push(threadId ?? null);
+          return Effect.void;
+        },
+        close: () => Effect.void,
+      },
+    }).pipe(
+      Layer.provide(Layer.succeed(ProviderAdapterRegistry, registry)),
+      Layer.provide(directoryLayer),
+      Layer.provide(defaultServerSettingsLayer),
+      Layer.provide(AnalyticsService.layerTest),
+      Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+    );
+
+    yield* Effect.gen(function* () {
+      yield* ProviderService;
+      yield* advanceTestClock(10);
+      codex.emit({
+        eventId: asEventId("evt-canonical-thread-segment"),
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-canonical-thread-segment"),
+        createdAt: "2026-01-01T00:00:00.000Z",
+        type: "turn.completed",
+        payload: {
+          state: "completed",
+        },
+      });
+      yield* advanceTestClock(20);
+    }).pipe(Effect.provide(providerLayer));
+
+    assert.equal(canonicalEvents.length, 1);
+    assert.equal(canonicalEvents[0]?.threadId, "thread-canonical-thread-segment");
+    assert.deepEqual(canonicalThreadIds, ["thread-canonical-thread-segment"]);
+  }).pipe(Effect.provide(NodeServices.layer)),
+);
+
 it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", () =>
   Effect.gen(function* () {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-provider-service-"));
     const dbPath = path.join(tempDir, "orchestration.sqlite");
 
     const codex = makeFakeCodexAdapter();
-    const registry: typeof ProviderAdapterRegistry.Service = {
-      getByProvider: (provider) =>
-        provider === "codex"
-          ? Effect.succeed(codex.adapter)
-          : Effect.fail(new ProviderUnsupportedError({ provider })),
-      listProviders: () => Effect.succeed(["codex"]),
-    };
+    const registry = makeAdapterRegistryMock({
+      [ProviderDriverKind.make("codex")]: codex.adapter,
+    });
 
     const persistenceLayer = makeSqlitePersistenceLive(dbPath);
     const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
@@ -357,7 +622,8 @@ it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", (
     yield* Effect.gen(function* () {
       const directory = yield* ProviderSessionDirectory;
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: ThreadId.make("thread-stale"),
       });
     }).pipe(Effect.provide(directoryLayer));
@@ -367,6 +633,7 @@ it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", (
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
       Layer.provide(AnalyticsService.layerTest),
+      Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
     );
 
     yield* Effect.gen(function* () {
@@ -381,7 +648,9 @@ it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", (
 
     const runtime = yield* Effect.gen(function* () {
       const repository = yield* ProviderSessionRuntimeRepository;
-      return yield* repository.getByThreadId({ threadId: asThreadId("thread-stale") });
+      return yield* repository.getByThreadId({
+        threadId: asThreadId("thread-stale"),
+      });
     }).pipe(Effect.provide(runtimeRepositoryLayer));
     assert.equal(Option.isSome(runtime), true);
 
@@ -411,13 +680,9 @@ it.effect(
       );
 
       const firstCodex = makeFakeCodexAdapter();
-      const firstRegistry: typeof ProviderAdapterRegistry.Service = {
-        getByProvider: (provider) =>
-          provider === "codex"
-            ? Effect.succeed(firstCodex.adapter)
-            : Effect.fail(new ProviderUnsupportedError({ provider })),
-        listProviders: () => Effect.succeed(["codex"]),
-      };
+      const firstRegistry = makeAdapterRegistryMock({
+        [ProviderDriverKind.make("codex")]: firstCodex.adapter,
+      });
 
       const firstDirectoryLayer = ProviderSessionDirectoryLive.pipe(
         Layer.provide(runtimeRepositoryLayer),
@@ -427,6 +692,7 @@ it.effect(
         Layer.provide(firstDirectoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provide(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
       );
       const updatedResumeCursor = {
         threadId: asThreadId("thread-1"),
@@ -439,7 +705,8 @@ it.effect(
         const provider = yield* ProviderService;
         const threadId = asThreadId("thread-1");
         const session = yield* provider.startSession(threadId, {
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: codexInstanceId,
           cwd: "/tmp/project",
           runtimeMode: "full-access",
           threadId,
@@ -448,14 +715,16 @@ it.effect(
           ...existing,
           status: "ready",
           resumeCursor: updatedResumeCursor,
-          updatedAt: new Date(Date.now() + 1_000).toISOString(),
+          updatedAt: "2026-01-01T00:00:01.000Z",
         }));
         return session;
       }).pipe(Effect.provide(firstProviderLayer));
 
       const persistedAfterStopAll = yield* Effect.gen(function* () {
         const repository = yield* ProviderSessionRuntimeRepository;
-        return yield* repository.getByThreadId({ threadId: startedSession.threadId });
+        return yield* repository.getByThreadId({
+          threadId: startedSession.threadId,
+        });
       }).pipe(Effect.provide(runtimeRepositoryLayer));
       assert.equal(Option.isSome(persistedAfterStopAll), true);
       if (Option.isSome(persistedAfterStopAll)) {
@@ -464,13 +733,9 @@ it.effect(
       }
 
       const secondCodex = makeFakeCodexAdapter();
-      const secondRegistry: typeof ProviderAdapterRegistry.Service = {
-        getByProvider: (provider) =>
-          provider === "codex"
-            ? Effect.succeed(secondCodex.adapter)
-            : Effect.fail(new ProviderUnsupportedError({ provider })),
-        listProviders: () => Effect.succeed(["codex"]),
-      };
+      const secondRegistry = makeAdapterRegistryMock({
+        [ProviderDriverKind.make("codex")]: secondCodex.adapter,
+      });
       const secondDirectoryLayer = ProviderSessionDirectoryLive.pipe(
         Layer.provide(runtimeRepositoryLayer),
       );
@@ -479,6 +744,7 @@ it.effect(
         Layer.provide(secondDirectoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provide(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
       );
 
       secondCodex.startSession.mockClear();
@@ -522,7 +788,8 @@ routing.layer("ProviderServiceLive routing", (it) => {
       const provider = yield* ProviderService;
 
       const session = yield* provider.startSession(asThreadId("thread-1"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
         cwd: "/tmp/project",
         runtimeMode: "full-access",
@@ -574,20 +841,31 @@ routing.layer("ProviderServiceLive routing", (it) => {
       });
 
       yield* provider.stopSession({ threadId: session.threadId });
-      const sendAfterStop = yield* Effect.result(
-        provider.sendTurn({
-          threadId: session.threadId,
-          input: "after-stop",
-          attachments: [],
-        }),
-      );
-      assertFailure(
-        sendAfterStop,
-        new ProviderValidationError({
-          operation: "ProviderService.sendTurn",
-          issue: `Cannot route thread '${session.threadId}' because no persisted provider binding exists.`,
-        }),
-      );
+      routing.codex.startSession.mockClear();
+      routing.codex.sendTurn.mockClear();
+
+      yield* provider.sendTurn({
+        threadId: session.threadId,
+        input: "after-stop",
+        attachments: [],
+      });
+
+      assert.equal(routing.codex.startSession.mock.calls.length, 1);
+      const resumedStartInput = routing.codex.startSession.mock.calls[0]?.[0];
+      assert.equal(typeof resumedStartInput === "object" && resumedStartInput !== null, true);
+      if (resumedStartInput && typeof resumedStartInput === "object") {
+        const startPayload = resumedStartInput as {
+          provider?: string;
+          cwd?: string;
+          resumeCursor?: unknown;
+          threadId?: string;
+        };
+        assert.equal(startPayload.provider, "codex");
+        assert.equal(startPayload.cwd, "/tmp/project");
+        assert.deepEqual(startPayload.resumeCursor, session.resumeCursor);
+        assert.equal(startPayload.threadId, session.threadId);
+      }
+      assert.equal(routing.codex.sendTurn.mock.calls.length, 1);
     }),
   );
 
@@ -596,7 +874,8 @@ routing.layer("ProviderServiceLive routing", (it) => {
       const provider = yield* ProviderService;
 
       const initial = yield* provider.startSession(asThreadId("thread-1"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
         cwd: "/tmp/project",
         runtimeMode: "full-access",
@@ -631,12 +910,65 @@ routing.layer("ProviderServiceLive routing", (it) => {
     }),
   );
 
+  it.effect("preserves the persisted binding when stopping a session", () =>
+    Effect.gen(function* () {
+      const provider = yield* ProviderService;
+      const runtimeRepository = yield* ProviderSessionRuntimeRepository;
+
+      const initial = yield* provider.startSession(asThreadId("thread-reap-preserve"), {
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
+        threadId: asThreadId("thread-reap-preserve"),
+        cwd: "/tmp/project-reap-preserve",
+        runtimeMode: "full-access",
+      });
+
+      yield* provider.stopSession({ threadId: initial.threadId });
+
+      const persistedAfterStop = yield* runtimeRepository.getByThreadId({
+        threadId: initial.threadId,
+      });
+      assert.equal(Option.isSome(persistedAfterStop), true);
+      if (Option.isSome(persistedAfterStop)) {
+        assert.equal(persistedAfterStop.value.status, "stopped");
+        assert.deepEqual(persistedAfterStop.value.resumeCursor, initial.resumeCursor);
+      }
+
+      routing.codex.startSession.mockClear();
+      routing.codex.sendTurn.mockClear();
+
+      yield* provider.sendTurn({
+        threadId: initial.threadId,
+        input: "resume after reap",
+        attachments: [],
+      });
+
+      assert.equal(routing.codex.startSession.mock.calls.length, 1);
+      const resumedStartInput = routing.codex.startSession.mock.calls[0]?.[0];
+      assert.equal(typeof resumedStartInput === "object" && resumedStartInput !== null, true);
+      if (resumedStartInput && typeof resumedStartInput === "object") {
+        const startPayload = resumedStartInput as {
+          provider?: string;
+          cwd?: string;
+          resumeCursor?: unknown;
+          threadId?: string;
+        };
+        assert.equal(startPayload.provider, "codex");
+        assert.equal(startPayload.cwd, "/tmp/project-reap-preserve");
+        assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
+        assert.equal(startPayload.threadId, initial.threadId);
+      }
+      assert.equal(routing.codex.sendTurn.mock.calls.length, 1);
+    }),
+  );
+
   it.effect("routes explicit claudeAgent provider session starts to the claude adapter", () =>
     Effect.gen(function* () {
       const provider = yield* ProviderService;
 
       const session = yield* provider.startSession(asThreadId("thread-claude"), {
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-claude"),
         cwd: "/tmp/project-claude",
         runtimeMode: "full-access",
@@ -647,19 +979,95 @@ routing.layer("ProviderServiceLive routing", (it) => {
       const startInput = routing.claude.startSession.mock.calls[0]?.[0];
       assert.equal(typeof startInput === "object" && startInput !== null, true);
       if (startInput && typeof startInput === "object") {
-        const startPayload = startInput as { provider?: string; cwd?: string };
+        const startPayload = startInput as {
+          provider?: string;
+          providerInstanceId?: ProviderInstanceId;
+          cwd?: string;
+        };
         assert.equal(startPayload.provider, "claudeAgent");
+        assert.equal(startPayload.providerInstanceId, claudeAgentInstanceId);
         assert.equal(startPayload.cwd, "/tmp/project-claude");
       }
     }),
   );
 
+  it.effect("dies when an active session conflicts with its persisted binding", () =>
+    Effect.gen(function* () {
+      const provider = yield* ProviderService;
+      const directory = yield* ProviderSessionDirectory;
+      const threadId = asThreadId("thread-binding-mismatch");
+
+      yield* provider.startSession(threadId, {
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
+        threadId,
+        cwd: "/tmp/project-binding-mismatch",
+        runtimeMode: "full-access",
+      });
+      yield* directory.upsert({
+        threadId,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: claudeAgentInstanceId,
+        runtimeMode: "full-access",
+      });
+
+      const exit = yield* Effect.exit(provider.listSessions());
+      assert.equal(Exit.hasDies(exit), true);
+      yield* directory.upsert({
+        threadId,
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
+        runtimeMode: "full-access",
+      });
+    }),
+  );
+
+  it.effect("stops stale sessions in other providers after a successful replacement start", () =>
+    Effect.gen(function* () {
+      const provider = yield* ProviderService;
+      const threadId = asThreadId("thread-provider-replacement");
+
+      const codexSession = yield* provider.startSession(threadId, {
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
+        threadId,
+        cwd: "/tmp/project-provider-replacement",
+        runtimeMode: "full-access",
+      });
+
+      routing.codex.stopSession.mockClear();
+      routing.claude.stopSession.mockClear();
+
+      const claudeSession = yield* provider.startSession(threadId, {
+        provider: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: claudeAgentInstanceId,
+        threadId,
+        cwd: "/tmp/project-provider-replacement",
+        runtimeMode: "full-access",
+      });
+
+      assert.equal(codexSession.provider, "codex");
+      assert.equal(claudeSession.provider, "claudeAgent");
+      assert.deepEqual(routing.codex.stopSession.mock.calls, [[threadId]]);
+      assert.equal(routing.claude.stopSession.mock.calls.length, 0);
+
+      const sessions = yield* provider.listSessions();
+      assert.deepEqual(
+        sessions
+          .filter((session) => session.threadId === threadId)
+          .map((session) => session.provider),
+        ["claudeAgent"],
+      );
+    }),
+  );
+
   it.effect("recovers stale sessions for sendTurn using persisted cwd", () =>
     Effect.gen(function* () {
       const provider = yield* ProviderService;
 
       const initial = yield* provider.startSession(asThreadId("thread-1"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
         cwd: "/tmp/project-send-turn",
         runtimeMode: "full-access",
@@ -699,16 +1107,15 @@ routing.layer("ProviderServiceLive routing", (it) => {
       const provider = yield* ProviderService;
 
       const initial = yield* provider.startSession(asThreadId("thread-claude-send-turn"), {
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-claude-send-turn"),
         cwd: "/tmp/project-claude-send-turn",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            effort: "max",
-          },
-        },
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [{ id: "effort", value: "max" }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -735,13 +1142,12 @@ routing.layer("ProviderServiceLive routing", (it) => {
         };
         assert.equal(startPayload.provider, "claudeAgent");
         assert.equal(startPayload.cwd, "/tmp/project-claude-send-turn");
-        assert.deepEqual(startPayload.modelSelection, {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            effort: "max",
-          },
-        });
+        assert.deepEqual(
+          startPayload.modelSelection,
+          createModelSelection(ProviderInstanceId.make("claudeAgent"), "claude-opus-4-6", [
+            { id: "effort", value: "max" },
+          ]),
+        );
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -754,12 +1160,14 @@ routing.layer("ProviderServiceLive routing", (it) => {
       const provider = yield* ProviderService;
 
       yield* provider.startSession(asThreadId("thread-1"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
         runtimeMode: "full-access",
       });
       yield* provider.startSession(asThreadId("thread-2"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-2"),
         runtimeMode: "full-access",
       });
@@ -777,9 +1185,11 @@ routing.layer("ProviderServiceLive routing", (it) => {
       const provider = yield* ProviderService;
       const runtimeRepository = yield* ProviderSessionRuntimeRepository;
 
-      const session = yield* provider.startSession(asThreadId("thread-1"), {
-        provider: "codex",
-        threadId: asThreadId("thread-1"),
+      const threadId = asThreadId("thread-runtime-status");
+      const session = yield* provider.startSession(threadId, {
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
+        threadId,
         runtimeMode: "full-access",
       });
       yield* provider.sendTurn({
@@ -805,7 +1215,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
             lastError: string | null;
             lastRuntimeEvent: string | null;
           };
-          assert.equal(runtimePayload.cwd, process.cwd());
+          assert.equal(runtimePayload.cwd, session.cwd);
           assert.equal(runtimePayload.model, null);
           assert.equal(runtimePayload.activeTurnId, `turn-${String(session.threadId)}`);
           assert.equal(runtimePayload.lastError, null);
@@ -824,14 +1234,10 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(persistenceLayer),
       );
 
-      const firstClaude = makeFakeCodexAdapter("claudeAgent");
-      const firstRegistry: typeof ProviderAdapterRegistry.Service = {
-        getByProvider: (provider) =>
-          provider === "claudeAgent"
-            ? Effect.succeed(firstClaude.adapter)
-            : Effect.fail(new ProviderUnsupportedError({ provider })),
-        listProviders: () => Effect.succeed(["claudeAgent"]),
-      };
+      const firstClaude = makeFakeCodexAdapter(CLAUDE_AGENT_DRIVER);
+      const firstRegistry = makeAdapterRegistryMock({
+        [ProviderDriverKind.make("claudeAgent")]: firstClaude.adapter,
+      });
       const firstDirectoryLayer = ProviderSessionDirectoryLive.pipe(
         Layer.provide(runtimeRepositoryLayer),
       );
@@ -840,12 +1246,14 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(firstDirectoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provide(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
       );
 
       const initial = yield* Effect.gen(function* () {
         const provider = yield* ProviderService;
         return yield* provider.startSession(asThreadId("thread-claude-start"), {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
+          providerInstanceId: claudeAgentInstanceId,
           threadId: asThreadId("thread-claude-start"),
           cwd: "/tmp/project-claude-start",
           runtimeMode: "full-access",
@@ -857,14 +1265,10 @@ routing.layer("ProviderServiceLive routing", (it) => {
         yield* provider.listSessions();
       }).pipe(Effect.provide(firstProviderLayer));
 
-      const secondClaude = makeFakeCodexAdapter("claudeAgent");
-      const secondRegistry: typeof ProviderAdapterRegistry.Service = {
-        getByProvider: (provider) =>
-          provider === "claudeAgent"
-            ? Effect.succeed(secondClaude.adapter)
-            : Effect.fail(new ProviderUnsupportedError({ provider })),
-        listProviders: () => Effect.succeed(["claudeAgent"]),
-      };
+      const secondClaude = makeFakeCodexAdapter(CLAUDE_AGENT_DRIVER);
+      const secondRegistry = makeAdapterRegistryMock({
+        [ProviderDriverKind.make("claudeAgent")]: secondClaude.adapter,
+      });
       const secondDirectoryLayer = ProviderSessionDirectoryLive.pipe(
         Layer.provide(runtimeRepositoryLayer),
       );
@@ -873,6 +1277,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(secondDirectoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provide(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
       );
 
       secondClaude.startSession.mockClear();
@@ -880,7 +1285,8 @@ routing.layer("ProviderServiceLive routing", (it) => {
       yield* Effect.gen(function* () {
         const provider = yield* ProviderService;
         yield* provider.startSession(initial.threadId, {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
+          providerInstanceId: claudeAgentInstanceId,
           threadId: initial.threadId,
           cwd: "/tmp/project-claude-start",
           runtimeMode: "full-access",
@@ -906,6 +1312,90 @@ routing.layer("ProviderServiceLive routing", (it) => {
       fs.rmSync(tempDir, { recursive: true, force: true });
     }).pipe(Effect.provide(NodeServices.layer)),
   );
+
+  it.effect(
+    "reuses persisted cwd when startSession resumes a claude session without cwd input",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3-provider-service-cwd-"));
+        const dbPath = path.join(tempDir, "orchestration.sqlite");
+        const persistenceLayer = makeSqlitePersistenceLive(dbPath);
+        const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
+          Layer.provide(persistenceLayer),
+        );
+
+        const firstClaude = makeFakeCodexAdapter(CLAUDE_AGENT_DRIVER);
+        const firstRegistry = makeAdapterRegistryMock({
+          [ProviderDriverKind.make("claudeAgent")]: firstClaude.adapter,
+        });
+        const firstDirectoryLayer = ProviderSessionDirectoryLive.pipe(
+          Layer.provide(runtimeRepositoryLayer),
+        );
+        const firstProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(Layer.succeed(ProviderAdapterRegistry, firstRegistry)),
+          Layer.provide(firstDirectoryLayer),
+          Layer.provide(defaultServerSettingsLayer),
+          Layer.provide(AnalyticsService.layerTest),
+          Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+        );
+
+        const initial = yield* Effect.gen(function* () {
+          const provider = yield* ProviderService;
+          return yield* provider.startSession(asThreadId("thread-claude-cwd"), {
+            provider: ProviderDriverKind.make("claudeAgent"),
+            providerInstanceId: claudeAgentInstanceId,
+            threadId: asThreadId("thread-claude-cwd"),
+            cwd: "/tmp/project-claude-cwd",
+            runtimeMode: "full-access",
+          });
+        }).pipe(Effect.provide(firstProviderLayer));
+
+        const secondClaude = makeFakeCodexAdapter(CLAUDE_AGENT_DRIVER);
+        const secondRegistry = makeAdapterRegistryMock({
+          [ProviderDriverKind.make("claudeAgent")]: secondClaude.adapter,
+        });
+        const secondDirectoryLayer = ProviderSessionDirectoryLive.pipe(
+          Layer.provide(runtimeRepositoryLayer),
+        );
+        const secondProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(Layer.succeed(ProviderAdapterRegistry, secondRegistry)),
+          Layer.provide(secondDirectoryLayer),
+          Layer.provide(defaultServerSettingsLayer),
+          Layer.provide(AnalyticsService.layerTest),
+          Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+        );
+
+        secondClaude.startSession.mockClear();
+
+        yield* Effect.gen(function* () {
+          const provider = yield* ProviderService;
+          yield* provider.startSession(initial.threadId, {
+            provider: ProviderDriverKind.make("claudeAgent"),
+            providerInstanceId: claudeAgentInstanceId,
+            threadId: initial.threadId,
+            runtimeMode: "full-access",
+          });
+        }).pipe(Effect.provide(secondProviderLayer));
+
+        assert.equal(secondClaude.startSession.mock.calls.length, 1);
+        const resumedStartInput = secondClaude.startSession.mock.calls[0]?.[0];
+        assert.equal(typeof resumedStartInput === "object" && resumedStartInput !== null, true);
+        if (resumedStartInput && typeof resumedStartInput === "object") {
+          const startPayload = resumedStartInput as {
+            provider?: string;
+            cwd?: string;
+            resumeCursor?: unknown;
+            threadId?: string;
+          };
+          assert.equal(startPayload.provider, "claudeAgent");
+          assert.equal(startPayload.cwd, "/tmp/project-claude-cwd");
+          assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
+          assert.equal(startPayload.threadId, initial.threadId);
+        }
+
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }).pipe(Effect.provide(NodeServices.layer)),
+  );
 });
 
 const fanout = makeProviderServiceLayer();
@@ -914,7 +1404,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
     Effect.gen(function* () {
       const provider = yield* ProviderService;
       const session = yield* provider.startSession(asThreadId("thread-1"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
         runtimeMode: "full-access",
       });
@@ -923,20 +1414,20 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       const consumer = yield* Stream.runForEach(provider.streamEvents, (event) =>
         Ref.update(eventsRef, (current) => [...current, event]),
       ).pipe(Effect.forkChild);
-      yield* sleep(50);
+      yield* advanceTestClock(50);
 
       const completedEvent: LegacyProviderRuntimeEvent = {
         type: "turn.completed",
         eventId: asEventId("evt-1"),
-        provider: "codex",
-        createdAt: new Date().toISOString(),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
         status: "completed",
       };
 
       fanout.codex.emit(completedEvent);
-      yield* sleep(50);
+      yield* advanceTestClock(50);
 
       const events = yield* Ref.get(eventsRef);
       yield* Fiber.interrupt(consumer);
@@ -945,6 +1436,13 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         events.some((entry) => entry.type === "turn.completed"),
         true,
       );
+      assert.equal(
+        events.some(
+          (entry) =>
+            entry.type === "turn.completed" && entry.providerInstanceId === codexInstanceId,
+        ),
+        true,
+      );
     }),
   );
 
@@ -952,7 +1450,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
     Effect.gen(function* () {
       const provider = yield* ProviderService;
       const session = yield* provider.startSession(asThreadId("thread-seq"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-seq"),
         runtimeMode: "full-access",
       });
@@ -962,13 +1461,13 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         Stream.runForEach((event) => Ref.update(receivedRef, (current) => [...current, event])),
         Effect.forkChild,
       );
-      yield* sleep(50);
+      yield* advanceTestClock(50);
 
       fanout.codex.emit({
         type: "tool.started",
         eventId: asEventId("evt-seq-1"),
-        provider: "codex",
-        createdAt: new Date().toISOString(),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
         toolKind: "command",
@@ -977,8 +1476,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       fanout.codex.emit({
         type: "tool.completed",
         eventId: asEventId("evt-seq-2"),
-        provider: "codex",
-        createdAt: new Date().toISOString(),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
         toolKind: "command",
@@ -987,8 +1486,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       fanout.codex.emit({
         type: "turn.completed",
         eventId: asEventId("evt-seq-3"),
-        provider: "codex",
-        createdAt: new Date().toISOString(),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
         status: "completed",
@@ -1007,7 +1506,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
     Effect.gen(function* () {
       const provider = yield* ProviderService;
       const session = yield* provider.startSession(asThreadId("thread-1"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
         runtimeMode: "full-access",
       });
@@ -1026,14 +1526,14 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         Stream.runForEach(() => Effect.fail("listener crash")),
         Effect.forkChild,
       );
-      yield* sleep(50);
+      yield* advanceTestClock(50);
 
       const events: ReadonlyArray<LegacyProviderRuntimeEvent> = [
         {
           type: "tool.completed",
           eventId: asEventId("evt-ordered-1"),
-          provider: "codex",
-          createdAt: new Date().toISOString(),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt: "2026-01-01T00:00:00.000Z",
           threadId: session.threadId,
           turnId: asTurnId("turn-1"),
           toolKind: "command",
@@ -1043,8 +1543,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         {
           type: "message.delta",
           eventId: asEventId("evt-ordered-2"),
-          provider: "codex",
-          createdAt: new Date().toISOString(),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt: "2026-01-01T00:00:00.000Z",
           threadId: session.threadId,
           turnId: asTurnId("turn-1"),
           delta: "hello",
@@ -1052,8 +1552,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         {
           type: "turn.completed",
           eventId: asEventId("evt-ordered-3"),
-          provider: "codex",
-          createdAt: new Date().toISOString(),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt: "2026-01-01T00:00:00.000Z",
           threadId: session.threadId,
           turnId: asTurnId("turn-1"),
           status: "completed",
@@ -1079,7 +1579,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       const provider = yield* ProviderService;
 
       const session = yield* provider.startSession(asThreadId("thread-metrics"), {
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-metrics"),
         cwd: "/tmp/project",
         runtimeMode: "full-access",
@@ -1108,7 +1609,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
 
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "interrupt",
           outcome: "success",
         }),
@@ -1116,7 +1617,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "approval-response",
           outcome: "success",
         }),
@@ -1124,7 +1625,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "user-input-response",
           outcome: "success",
         }),
@@ -1132,7 +1633,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "rollback",
           outcome: "success",
         }),
@@ -1140,7 +1641,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_sessions_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "stop",
           outcome: "success",
         }),
@@ -1156,7 +1657,8 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         const provider = yield* ProviderService;
 
         const session = yield* provider.startSession(asThreadId("thread-send-metrics"), {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
+          providerInstanceId: claudeAgentInstanceId,
           threadId: asThreadId("thread-send-metrics"),
           cwd: "/tmp/project-send-metrics",
           runtimeMode: "full-access",
@@ -1172,7 +1674,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
 
         assert.equal(
           hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-            provider: "claudeAgent",
+            provider: ProviderDriverKind.make("claudeAgent"),
             operation: "send",
             outcome: "success",
           }),
@@ -1180,7 +1682,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         );
         assert.equal(
           hasMetricSnapshot(snapshots, "t3_provider_turn_duration", {
-            provider: "claudeAgent",
+            provider: ProviderDriverKind.make("claudeAgent"),
             operation: "send",
           }),
           true,
@@ -1191,6 +1693,50 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
 
 const validation = makeProviderServiceLayer();
 validation.layer("ProviderServiceLive validation", (it) => {
+  it.effect("rejects session starts without an explicit provider instance id", () =>
+    Effect.gen(function* () {
+      const provider = yield* ProviderService;
+
+      validation.codex.startSession.mockClear();
+      const failure = yield* Effect.flip(
+        provider.startSession(asThreadId("thread-missing-instance-id"), {
+          provider: ProviderDriverKind.make("codex"),
+          threadId: asThreadId("thread-missing-instance-id"),
+          runtimeMode: "full-access",
+        }),
+      );
+
+      assert.instanceOf(failure, ProviderValidationError);
+      assert.include(failure.issue, "Provider instance id is required for provider 'codex'.");
+      assert.equal(validation.codex.startSession.mock.calls.length, 0);
+    }),
+  );
+
+  it.effect("rejects mismatched provider kind and provider instance id", () =>
+    Effect.gen(function* () {
+      const provider = yield* ProviderService;
+
+      validation.codex.startSession.mockClear();
+      validation.claude.startSession.mockClear();
+      const failure = yield* Effect.flip(
+        provider.startSession(asThreadId("thread-instance-mismatch"), {
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: claudeAgentInstanceId,
+          threadId: asThreadId("thread-instance-mismatch"),
+          runtimeMode: "full-access",
+        }),
+      );
+
+      assert.instanceOf(failure, ProviderValidationError);
+      assert.include(
+        failure.issue,
+        "Provider instance 'claudeAgent' belongs to driver 'claudeAgent', not 'codex'.",
+      );
+      assert.equal(validation.codex.startSession.mock.calls.length, 0);
+      assert.equal(validation.claude.startSession.mock.calls.length, 0);
+    }),
+  );
+
   it.effect("returns ProviderValidationError for invalid input payloads", () =>
     Effect.gen(function* () {
       const provider = yield* ProviderService;
@@ -1223,9 +1769,9 @@ validation.layer("ProviderServiceLive validation", (it) => {
 
       validation.codex.startSession.mockImplementationOnce((input: ProviderSessionStartInput) =>
         Effect.sync(() => {
-          const now = new Date().toISOString();
+          const now = "2026-01-01T00:00:00.000Z";
           return {
-            provider: "codex",
+            provider: ProviderDriverKind.make("codex"),
             status: "ready",
             threadId: input.threadId,
             runtimeMode: input.runtimeMode,
@@ -1237,7 +1783,8 @@ validation.layer("ProviderServiceLive validation", (it) => {
       );
 
       const session = yield* provider.startSession(asThreadId("thread-missing"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-missing"),
         cwd: "/tmp/project",
         runtimeMode: "full-access",
diff --git a/apps/server/src/provider/Layers/ProviderService.ts b/apps/server/src/provider/Layers/ProviderService.ts
index 85fe9fbc326..2bce1f483b7 100644
--- a/apps/server/src/provider/Layers/ProviderService.ts
+++ b/apps/server/src/provider/Layers/ProviderService.ts
@@ -19,10 +19,21 @@ import {
   ProviderSendTurnInput,
   ProviderSessionStartInput,
   ProviderStopSessionInput,
+  type ProviderInstanceId,
+  type ProviderDriverKind,
   type ProviderRuntimeEvent,
   type ProviderSession,
 } from "@t3tools/contracts";
-import { Effect, Layer, Option, PubSub, Schema, SchemaIssue, Stream } from "effect";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as Stream from "effect/Stream";
 
 import {
   increment,
@@ -34,19 +45,25 @@ import {
   providerTurnMetricAttributes,
   withMetrics,
 } from "../../observability/Metrics.ts";
-import { ProviderValidationError } from "../Errors.ts";
+import { type ProviderAdapterError, ProviderValidationError } from "../Errors.ts";
+import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
 import { ProviderAdapterRegistry } from "../Services/ProviderAdapterRegistry.ts";
 import { ProviderService, type ProviderServiceShape } from "../Services/ProviderService.ts";
 import {
   ProviderSessionDirectory,
   type ProviderRuntimeBinding,
 } from "../Services/ProviderSessionDirectory.ts";
-import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
+import { type EventNdjsonLogger } from "./EventNdjsonLogger.ts";
+import { ProviderEventLoggers } from "./ProviderEventLoggers.ts";
 import { AnalyticsService } from "../../telemetry/Services/AnalyticsService.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+const isModelSelection = Schema.is(ModelSelection);
 
+/**
+ * Hook for tests that want to override the canonical event logger pulled
+ * from `ProviderEventLoggers`. Production wiring leaves this undefined and
+ * reads the logger off the tag.
+ */
 export interface ProviderServiceLiveOptions {
-  readonly canonicalEventLogPath?: string;
   readonly canonicalEventLogger?: EventNdjsonLogger;
 }
 
@@ -71,8 +88,9 @@ const decodeInputOrValidationError = <S extends Schema.Top>(input: {
   readonly operation: string;
   readonly schema: S;
   readonly payload: unknown;
-}) =>
-  Schema.decodeUnknownEffect(input.schema)(input.payload).pipe(
+}) => {
+  const decodeProviderRequestInput = Schema.decodeUnknownEffect(input.schema);
+  return decodeProviderRequestInput(input.payload).pipe(
     Effect.mapError(
       (schemaError) =>
         new ProviderValidationError({
@@ -82,6 +100,7 @@ const decodeInputOrValidationError = <S extends Schema.Top>(input: {
         }),
     ),
   );
+};
 
 function toRuntimeStatus(session: ProviderSession): "starting" | "running" | "stopped" | "error" {
   switch (session.status) {
@@ -126,7 +145,7 @@ function readPersistedModelSelection(
     return undefined;
   }
   const raw = "modelSelection" in runtimePayload ? runtimePayload.modelSelection : undefined;
-  return Schema.is(ModelSelection)(raw) ? raw : undefined;
+  return isModelSelection(raw) ? raw : undefined;
 }
 
 function readPersistedCwd(
@@ -141,32 +160,88 @@ function readPersistedCwd(
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+const dieOnMissingBindingInstanceId = (
+  operation: string,
+  payload: {
+    readonly providerInstanceId?: ProviderInstanceId | undefined;
+    readonly provider?: ProviderDriverKind | undefined;
+  },
+): ProviderInstanceId => {
+  if (payload.providerInstanceId !== undefined) {
+    return payload.providerInstanceId;
+  }
+  throw new Error(
+    payload.provider
+      ? `${operation}: provider instance id is required for provider '${payload.provider}'.`
+      : `${operation}: provider instance id is required.`,
+  );
+};
+
+const correlateRuntimeEventWithInstance = (
+  source: {
+    readonly instanceId: ProviderInstanceId;
+    readonly provider: ProviderDriverKind;
+  },
+  event: ProviderRuntimeEvent,
+): ProviderRuntimeEvent => {
+  if (event.provider !== source.provider) {
+    throw new Error(
+      `ProviderService.streamEvents: provider instance '${source.instanceId}' is backed by driver '${source.provider}' but emitted driver '${event.provider}'.`,
+    );
+  }
+  if (event.providerInstanceId !== undefined && event.providerInstanceId !== source.instanceId) {
+    throw new Error(
+      `ProviderService.streamEvents: provider instance '${source.instanceId}' emitted event for instance '${event.providerInstanceId}'.`,
+    );
+  }
+  return { ...event, providerInstanceId: source.instanceId };
+};
+
 const makeProviderService = Effect.fn("makeProviderService")(function* (
   options?: ProviderServiceLiveOptions,
 ) {
   const analytics = yield* Effect.service(AnalyticsService);
-  const serverSettings = yield* ServerSettingsService;
-  const canonicalEventLogger =
-    options?.canonicalEventLogger ??
-    (options?.canonicalEventLogPath !== undefined
-      ? yield* makeEventNdjsonLogger(options.canonicalEventLogPath, {
-          stream: "canonical",
-        })
-      : undefined);
+  const eventLoggers = yield* ProviderEventLoggers;
+  // Options-provided logger wins (test overrides); otherwise we take whatever
+  // the `ProviderEventLoggers` tag exposes — `undefined` means "no canonical
+  // log writer is attached", which downstream code already handles as a
+  // no-op.
+  const canonicalEventLogger = options?.canonicalEventLogger ?? eventLoggers.canonical;
 
   const registry = yield* ProviderAdapterRegistry;
   const directory = yield* ProviderSessionDirectory;
   const runtimeEventPubSub = yield* PubSub.unbounded<ProviderRuntimeEvent>();
+  const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
 
   const publishRuntimeEvent = (event: ProviderRuntimeEvent): Effect.Effect<void> =>
     Effect.succeed(event).pipe(
       Effect.tap((canonicalEvent) =>
-        canonicalEventLogger ? canonicalEventLogger.write(canonicalEvent, null) : Effect.void,
+        canonicalEventLogger
+          ? canonicalEventLogger.write(canonicalEvent, canonicalEvent.threadId)
+          : Effect.void,
       ),
       Effect.flatMap((canonicalEvent) => PubSub.publish(runtimeEventPubSub, canonicalEvent)),
       Effect.asVoid,
     );
 
+  const requireBindingInstanceId = (
+    operation: string,
+    payload: {
+      readonly providerInstanceId?: ProviderInstanceId | undefined;
+      readonly provider?: ProviderDriverKind | undefined;
+    },
+  ): Effect.Effect<ProviderInstanceId, ProviderValidationError> =>
+    payload.providerInstanceId !== undefined
+      ? Effect.succeed(payload.providerInstanceId)
+      : Effect.fail(
+          toValidationError(
+            operation,
+            payload.provider
+              ? `Provider instance id is required for provider '${payload.provider}'.`
+              : "Provider instance id is required.",
+          ),
+        );
+
   const upsertSessionBinding = (
     session: ProviderSession,
     threadId: ThreadId,
@@ -176,38 +251,106 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
       readonly lastRuntimeEventAt?: string;
     },
   ) =>
-    directory.upsert({
-      threadId,
-      provider: session.provider,
-      runtimeMode: session.runtimeMode,
-      status: toRuntimeStatus(session),
-      ...(session.resumeCursor !== undefined ? { resumeCursor: session.resumeCursor } : {}),
-      runtimePayload: toRuntimePayloadFromSession(session, extra),
+    Effect.gen(function* () {
+      const providerInstanceId = yield* requireBindingInstanceId(
+        "ProviderService.upsertSessionBinding",
+        session,
+      );
+      yield* directory.upsert({
+        threadId,
+        provider: session.provider,
+        providerInstanceId,
+        runtimeMode: session.runtimeMode,
+        status: toRuntimeStatus(session),
+        ...(session.resumeCursor !== undefined ? { resumeCursor: session.resumeCursor } : {}),
+        runtimePayload: toRuntimePayloadFromSession(session, extra),
+      });
     });
 
-  const providers = yield* registry.listProviders();
-  const adapters = yield* Effect.forEach(providers, (provider) => registry.getByProvider(provider));
-  const processRuntimeEvent = (event: ProviderRuntimeEvent): Effect.Effect<void> =>
-    increment(providerRuntimeEventsTotal, {
-      provider: event.provider,
-      eventType: event.type,
-    }).pipe(Effect.andThen(publishRuntimeEvent(event)));
+  const processRuntimeEvent = (
+    source: {
+      readonly instanceId: ProviderInstanceId;
+      readonly provider: ProviderDriverKind;
+    },
+    event: ProviderRuntimeEvent,
+  ): Effect.Effect<void> =>
+    Effect.sync(() => correlateRuntimeEventWithInstance(source, event)).pipe(
+      Effect.flatMap((canonicalEvent) =>
+        increment(providerRuntimeEventsTotal, {
+          provider: canonicalEvent.provider,
+          eventType: canonicalEvent.type,
+        }).pipe(Effect.andThen(publishRuntimeEvent(canonicalEvent))),
+      ),
+    );
+
+  // `subscribedAdapters` is our source-of-truth for "which instance adapters
+  // are currently wired into the runtime event bus". It both tracks the set
+  // of live subscriptions (so `reconcileInstanceSubscriptions` can diff and
+  // fork only the *new* or *rebuilt* ones) and serves as the dynamic adapter
+  // list consumed by `stopStaleSessionsForThread`, `listSessions`, and
+  // `runStopAll` — replacing the pre-Slice-D startup snapshot so hot-added
+  // instances become visible to those call sites as soon as settings edits
+  // land.
+  const subscribedAdapters = yield* Ref.make(
+    new Map<ProviderInstanceId, ProviderAdapterShape<ProviderAdapterError>>(),
+  );
+
+  const getAdapterEntries = Ref.get(subscribedAdapters).pipe(
+    Effect.map((map) => Array.from(map.entries())),
+  );
+
+  // Rebuild the map of id → adapter from the registry and fork a new event
+  // subscription for every instance that is either brand new or whose adapter
+  // identity changed (indicating the underlying `ProviderInstance` was torn
+  // down and rebuilt by `ProviderInstanceRegistry.reconcile`). Orphaned
+  // fibers for removed/replaced instances exit on their own because their
+  // adapter's `streamEvents` source terminates when the old scope closes.
+  const reconcileInstanceSubscriptions = Effect.gen(function* () {
+    const previous = yield* Ref.get(subscribedAdapters);
+    const currentIds = yield* registry.listInstances();
+    const next = new Map<ProviderInstanceId, ProviderAdapterShape<ProviderAdapterError>>();
+    for (const id of currentIds) {
+      const adapterOption = yield* registry
+        .getByInstance(id)
+        .pipe(Effect.tapError(Effect.logWarning), Effect.option);
+      if (Option.isNone(adapterOption)) continue;
+      const adapter = adapterOption.value;
+      next.set(id, adapter);
+      if (previous.get(id) !== adapter) {
+        yield* Stream.runForEach(adapter.streamEvents, (event) =>
+          processRuntimeEvent(
+            {
+              instanceId: id,
+              provider: adapter.provider,
+            },
+            event,
+          ),
+        ).pipe(Effect.forkScoped);
+      }
+    }
+    yield* Ref.set(subscribedAdapters, next);
+  });
 
-  yield* Effect.forEach(adapters, (adapter) =>
-    Stream.runForEach(adapter.streamEvents, processRuntimeEvent).pipe(Effect.forkScoped),
-  ).pipe(Effect.asVoid);
+  const instanceChanges = yield* registry.subscribeChanges;
+  yield* reconcileInstanceSubscriptions;
+  yield* Stream.runForEach(
+    Stream.fromSubscription(instanceChanges),
+    () => reconcileInstanceSubscriptions,
+  ).pipe(Effect.forkScoped);
 
   const recoverSessionForThread = Effect.fn("recoverSessionForThread")(function* (input: {
     readonly binding: ProviderRuntimeBinding;
     readonly operation: string;
   }) {
+    const bindingInstanceId = yield* requireBindingInstanceId(input.operation, input.binding);
     yield* Effect.annotateCurrentSpan({
       "provider.operation": "recover-session",
       "provider.kind": input.binding.provider,
+      "provider.instance_id": bindingInstanceId,
       "provider.thread_id": input.binding.threadId,
     });
     return yield* Effect.gen(function* () {
-      const adapter = yield* registry.getByProvider(input.binding.provider);
+      const adapter = yield* registry.getByInstance(bindingInstanceId);
       const hasResumeCursor =
         input.binding.resumeCursor !== null && input.binding.resumeCursor !== undefined;
       const hasActiveSession = yield* adapter.hasSession(input.binding.threadId);
@@ -217,7 +360,10 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
           (session) => session.threadId === input.binding.threadId,
         );
         if (existing) {
-          yield* upsertSessionBinding(existing, input.binding.threadId);
+          yield* upsertSessionBinding(
+            { ...existing, providerInstanceId: bindingInstanceId },
+            input.binding.threadId,
+          );
           yield* analytics.record("provider.session.recovered", {
             provider: existing.provider,
             strategy: "adopt-existing",
@@ -240,6 +386,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
       const resumed = yield* adapter.startSession({
         threadId: input.binding.threadId,
         provider: input.binding.provider,
+        providerInstanceId: bindingInstanceId,
         ...(persistedCwd ? { cwd: persistedCwd } : {}),
         ...(persistedModelSelection ? { modelSelection: persistedModelSelection } : {}),
         ...(hasResumeCursor ? { resumeCursor: input.binding.resumeCursor } : {}),
@@ -252,7 +399,10 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         );
       }
 
-      yield* upsertSessionBinding(resumed, input.binding.threadId);
+      yield* upsertSessionBinding(
+        { ...resumed, providerInstanceId: bindingInstanceId },
+        input.binding.threadId,
+      );
       yield* analytics.record("provider.session.recovered", {
         provider: resumed.provider,
         strategy: "resume-thread",
@@ -282,19 +432,73 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         `Cannot route thread '${input.threadId}' because no persisted provider binding exists.`,
       );
     }
-    const adapter = yield* registry.getByProvider(binding.provider);
+    const instanceId = yield* requireBindingInstanceId(input.operation, binding);
+    const adapter = yield* registry.getByInstance(instanceId);
 
     const hasRequestedSession = yield* adapter.hasSession(input.threadId);
     if (hasRequestedSession) {
-      return { adapter, threadId: input.threadId, isActive: true } as const;
+      return {
+        adapter,
+        instanceId,
+        threadId: input.threadId,
+        isActive: true,
+      } as const;
     }
 
     if (!input.allowRecovery) {
-      return { adapter, threadId: input.threadId, isActive: false } as const;
+      return {
+        adapter,
+        instanceId,
+        threadId: input.threadId,
+        isActive: false,
+      } as const;
     }
 
-    const recovered = yield* recoverSessionForThread({ binding, operation: input.operation });
-    return { adapter: recovered.adapter, threadId: input.threadId, isActive: true } as const;
+    const recovered = yield* recoverSessionForThread({
+      binding,
+      operation: input.operation,
+    });
+    return {
+      adapter: recovered.adapter,
+      instanceId,
+      threadId: input.threadId,
+      isActive: true,
+    } as const;
+  });
+
+  const stopStaleSessionsForThread = Effect.fn("stopStaleSessionsForThread")(function* (input: {
+    readonly threadId: ThreadId;
+    readonly currentInstanceId: ProviderInstanceId;
+  }) {
+    const currentAdapters = yield* getAdapterEntries;
+    yield* Effect.forEach(
+      currentAdapters,
+      ([instanceId, adapter]) =>
+        instanceId === input.currentInstanceId
+          ? Effect.void
+          : Effect.gen(function* () {
+              const hasSession = yield* adapter.hasSession(input.threadId);
+              if (!hasSession) {
+                return;
+              }
+
+              yield* adapter.stopSession(input.threadId).pipe(
+                Effect.tap(() =>
+                  analytics.record("provider.session.stopped", {
+                    provider: adapter.provider,
+                  }),
+                ),
+                Effect.catchCause((cause) =>
+                  Effect.logWarning("provider.session.stop-stale-failed", {
+                    threadId: input.threadId,
+                    provider: adapter.provider,
+                    cause,
+                  }),
+                ),
+              );
+            }),
+      { discard: true },
+    );
   });
 
   const startSession: ProviderServiceShape["startSession"] = Effect.fn("startSession")(
@@ -305,42 +509,73 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         payload: rawInput,
       });
 
-      const input = {
-        ...parsed,
-        threadId,
-        provider: parsed.provider ?? "codex",
-      };
+      const resolvedInstanceId = yield* requireBindingInstanceId(
+        "ProviderService.startSession",
+        parsed,
+      );
+      let metricProvider = parsed.provider ?? String(resolvedInstanceId);
       yield* Effect.annotateCurrentSpan({
         "provider.operation": "start-session",
-        "provider.kind": input.provider,
+        "provider.instance_id": resolvedInstanceId,
         "provider.thread_id": threadId,
-        "provider.runtime_mode": input.runtimeMode,
+        "provider.runtime_mode": parsed.runtimeMode,
       });
       return yield* Effect.gen(function* () {
-        const settings = yield* serverSettings.getSettings.pipe(
-          Effect.mapError((error) =>
-            toValidationError(
-              "ProviderService.startSession",
-              `Failed to load provider settings: ${error.message}`,
-              error,
-            ),
-          ),
-        );
-        if (!settings.providers[input.provider].enabled) {
+        const instanceInfo = yield* registry.getInstanceInfo(resolvedInstanceId);
+        const resolvedProvider = instanceInfo.driverKind;
+        metricProvider = resolvedProvider;
+        if (parsed.provider !== undefined && parsed.provider !== resolvedProvider) {
           return yield* toValidationError(
             "ProviderService.startSession",
-            `Provider '${input.provider}' is disabled in T3 Code settings.`,
+            `Provider instance '${resolvedInstanceId}' belongs to driver '${resolvedProvider}', not '${parsed.provider}'.`,
+          );
+        }
+        const input = {
+          ...parsed,
+          threadId,
+          provider: resolvedProvider,
+        };
+        if (!instanceInfo.enabled) {
+          return yield* toValidationError(
+            "ProviderService.startSession",
+            `Provider instance '${resolvedInstanceId}' is disabled in T3 Code settings.`,
           );
         }
         const persistedBinding = Option.getOrUndefined(yield* directory.getBinding(threadId));
         const effectiveResumeCursor =
           input.resumeCursor ??
-          (persistedBinding?.provider === input.provider
+          (persistedBinding?.providerInstanceId === resolvedInstanceId
             ? persistedBinding.resumeCursor
             : undefined);
-        const adapter = yield* registry.getByProvider(input.provider);
+        const effectiveCwd =
+          input.cwd ??
+          (persistedBinding?.providerInstanceId === resolvedInstanceId
+            ? readPersistedCwd(persistedBinding.runtimePayload)
+            : undefined);
+        yield* Effect.annotateCurrentSpan({
+          "provider.kind": resolvedProvider,
+          "provider.resume_cursor.source":
+            input.resumeCursor !== undefined
+              ? "request"
+              : effectiveResumeCursor !== undefined &&
+                  persistedBinding?.providerInstanceId === resolvedInstanceId
+                ? "persisted"
+                : "none",
+          "provider.resume_cursor.present": effectiveResumeCursor !== undefined,
+          "provider.cwd.source":
+            input.cwd !== undefined
+              ? "request"
+              : effectiveCwd !== undefined &&
+                  persistedBinding?.providerInstanceId === resolvedInstanceId
+                ? "persisted"
+                : "none",
+          "provider.cwd.effective": effectiveCwd ?? "",
+        });
+        const adapter = yield* registry.getByInstance(resolvedInstanceId);
         const session = yield* adapter.startSession({
           ...input,
+          providerInstanceId: resolvedInstanceId,
+          ...(effectiveCwd !== undefined ? { cwd: effectiveCwd } : {}),
           ...(effectiveResumeCursor !== undefined ? { resumeCursor: effectiveResumeCursor } : {}),
         });
 
@@ -350,27 +585,36 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
             `Adapter/provider mismatch: requested '${adapter.provider}', received '${session.provider}'.`,
           );
         }
+        const sessionWithInstance = {
+          ...session,
+          providerInstanceId: resolvedInstanceId,
+        };
 
-        yield* upsertSessionBinding(session, threadId, {
+        yield* stopStaleSessionsForThread({
+          threadId,
+          currentInstanceId: resolvedInstanceId,
+        });
+        yield* upsertSessionBinding(sessionWithInstance, threadId, {
           modelSelection: input.modelSelection,
         });
         yield* analytics.record("provider.session.started", {
-          provider: session.provider,
+          provider: sessionWithInstance.provider,
           runtimeMode: input.runtimeMode,
-          hasResumeCursor: session.resumeCursor !== undefined,
-          hasCwd: typeof input.cwd === "string" && input.cwd.trim().length > 0,
+          hasResumeCursor: sessionWithInstance.resumeCursor !== undefined,
+          hasCwd: typeof effectiveCwd === "string" && effectiveCwd.trim().length > 0,
           hasModel:
             typeof input.modelSelection?.model === "string" &&
             input.modelSelection.model.trim().length > 0,
         });
 
-        return session;
+        return sessionWithInstance;
       }).pipe(
         withMetrics({
           counter: providerSessionsTotal,
-          attributes: providerMetricAttributes(input.provider, {
-            operation: "start",
-          }),
+          attributes: () =>
+            providerMetricAttributes(metricProvider, {
+              operation: "start",
+            }),
         }),
       );
     },
@@ -417,13 +661,14 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
       yield* directory.upsert({
         threadId: input.threadId,
         provider: routed.adapter.provider,
+        providerInstanceId: routed.instanceId,
         status: "running",
         ...(turn.resumeCursor !== undefined ? { resumeCursor: turn.resumeCursor } : {}),
         runtimePayload: {
           ...(input.modelSelection !== undefined ? { modelSelection: input.modelSelection } : {}),
           activeTurnId: turn.turnId,
           lastRuntimeEvent: "provider.sendTurn",
-          lastRuntimeEventAt: new Date().toISOString(),
+          lastRuntimeEventAt: yield* nowIso,
         },
       });
       yield* analytics.record("provider.turn.sent", {
@@ -582,7 +827,15 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         if (routed.isActive) {
           yield* routed.adapter.stopSession(routed.threadId);
         }
-        yield* directory.remove(input.threadId);
+        yield* directory.upsert({
+          threadId: input.threadId,
+          provider: routed.adapter.provider,
+          providerInstanceId: routed.instanceId,
+          status: "stopped",
+          runtimePayload: {
+            activeTurnId: null,
+          },
+        });
         yield* analytics.record("provider.session.stopped", {
           provider: routed.adapter.provider,
         });
@@ -600,8 +853,16 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
 
   const listSessions: ProviderServiceShape["listSessions"] = Effect.fn("listSessions")(
     function* () {
-      const sessionsByProvider = yield* Effect.forEach(adapters, (adapter) =>
-        adapter.listSessions(),
+      const currentAdapters = yield* getAdapterEntries;
+      const sessionsByProvider = yield* Effect.forEach(currentAdapters, ([instanceId, adapter]) =>
+        adapter.listSessions().pipe(
+          Effect.map((sessions) =>
+            sessions.map((session) => ({
+              ...session,
+              providerInstanceId: instanceId,
+            })),
+          ),
+        ),
       );
       const activeSessions = sessionsByProvider.flatMap((sessions) => sessions);
       const persistedBindings = yield* directory.listThreadIds().pipe(
@@ -625,29 +886,54 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         }
       }
 
-      return activeSessions.map((session) => {
+      const sessions: ProviderSession[] = [];
+      for (const session of activeSessions) {
         const binding = bindingsByThreadId.get(session.threadId);
         if (!binding) {
-          return session;
+          sessions.push(session);
+          continue;
         }
 
         const overrides: {
           resumeCursor?: ProviderSession["resumeCursor"];
           runtimeMode?: ProviderSession["runtimeMode"];
+          providerInstanceId?: ProviderSession["providerInstanceId"];
         } = {};
+        overrides.providerInstanceId = dieOnMissingBindingInstanceId(
+          "ProviderService.listSessions",
+          binding,
+        );
+        if (binding.provider !== session.provider) {
+          return yield* Effect.die(
+            new Error(
+              `ProviderService.listSessions: thread '${session.threadId}' is active on provider '${session.provider}' but persisted binding names provider '${binding.provider}'.`,
+            ),
+          );
+        }
+        if (overrides.providerInstanceId !== session.providerInstanceId) {
+          return yield* Effect.die(
+            new Error(
+              `ProviderService.listSessions: thread '${session.threadId}' is active on provider instance '${session.providerInstanceId}' but persisted binding names '${overrides.providerInstanceId}'.`,
+            ),
+          );
+        }
         if (session.resumeCursor === undefined && binding.resumeCursor !== undefined) {
           overrides.resumeCursor = binding.resumeCursor;
         }
         if (binding.runtimeMode !== undefined) {
           overrides.runtimeMode = binding.runtimeMode;
         }
-        return Object.assign({}, session, overrides);
-      });
+        sessions.push(Object.assign({}, session, overrides));
+      }
+      return sessions;
     },
   );
 
-  const getCapabilities: ProviderServiceShape["getCapabilities"] = (provider) =>
-    registry.getByProvider(provider).pipe(Effect.map((adapter) => adapter.capabilities));
+  const getCapabilities: ProviderServiceShape["getCapabilities"] = (instanceId) =>
+    registry.getByInstance(instanceId).pipe(Effect.map((adapter) => adapter.capabilities));
+
+  const getInstanceInfo: ProviderServiceShape["getInstanceInfo"] = (instanceId) =>
+    registry.getInstanceInfo(instanceId);
 
   const rollbackConversation: ProviderServiceShape["rollbackConversation"] = Effect.fn(
     "rollbackConversation",
@@ -692,32 +978,46 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
 
   const runStopAll = Effect.fn("runStopAll")(function* () {
     const threadIds = yield* directory.listThreadIds();
-    const activeSessions = yield* Effect.forEach(adapters, (adapter) =>
-      adapter.listSessions(),
+    const currentAdapters = yield* getAdapterEntries;
+    const activeSessions = yield* Effect.forEach(currentAdapters, ([instanceId, adapter]) =>
+      adapter.listSessions().pipe(
+        Effect.map((sessions) =>
+          sessions.map((session) => ({
+            ...session,
+            providerInstanceId: instanceId,
+          })),
+        ),
+      ),
     ).pipe(Effect.map((sessionsByAdapter) => sessionsByAdapter.flatMap((sessions) => sessions)));
     yield* Effect.forEach(activeSessions, (session) =>
-      upsertSessionBinding(session, session.threadId, {
-        lastRuntimeEvent: "provider.stopAll",
-        lastRuntimeEventAt: new Date().toISOString(),
-      }),
-    ).pipe(Effect.asVoid);
-    yield* Effect.forEach(adapters, (adapter) => adapter.stopAll()).pipe(Effect.asVoid);
-    yield* Effect.forEach(threadIds, (threadId) =>
-      directory.getProvider(threadId).pipe(
-        Effect.flatMap((provider) =>
-          directory.upsert({
-            threadId,
-            provider,
-            status: "stopped",
-            runtimePayload: {
-              activeTurnId: null,
-              lastRuntimeEvent: "provider.stopAll",
-              lastRuntimeEventAt: new Date().toISOString(),
-            },
-          }),
-        ),
+      Effect.flatMap(nowIso, (lastRuntimeEventAt) =>
+        upsertSessionBinding(session, session.threadId, {
+          lastRuntimeEvent: "provider.stopAll",
+          lastRuntimeEventAt,
+        }),
       ),
     ).pipe(Effect.asVoid);
+    yield* Effect.forEach(currentAdapters, ([, adapter]) => adapter.stopAll()).pipe(Effect.asVoid);
+    const bindings = yield* directory.listBindings().pipe(Effect.orElseSucceed(() => []));
+    yield* Effect.forEach(bindings, (binding) =>
+      Effect.gen(function* () {
+        const providerInstanceId = dieOnMissingBindingInstanceId(
+          "ProviderService.stopAll",
+          binding,
+        );
+        return yield* directory.upsert({
+          threadId: binding.threadId,
+          provider: binding.provider,
+          providerInstanceId,
+          status: "stopped",
+          runtimePayload: {
+            activeTurnId: null,
+            lastRuntimeEvent: "provider.stopAll",
+            lastRuntimeEventAt: yield* nowIso,
+          },
+        });
+      }),
+    ).pipe(Effect.asVoid);
     yield* analytics.record("provider.sessions.stopped_all", {
       sessionCount: threadIds.length,
     });
@@ -725,8 +1025,10 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
   });
 
   yield* Effect.addFinalizer(() =>
-    Effect.catch(runStopAll(), (cause) =>
-      Effect.logWarning("failed to stop provider service", { cause }),
+    runStopAll().pipe(
+      Effect.catchCause((cause) =>
+        Effect.logWarning("failed to stop provider service", { cause: Cause.pretty(cause) }),
+      ),
     ),
   );
 
@@ -739,6 +1041,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     stopSession,
     listSessions,
     getCapabilities,
+    getInstanceInfo,
     rollbackConversation,
     // Each access creates a fresh PubSub subscription so that multiple
     // consumers (ProviderRuntimeIngestion, CheckpointReactor, etc.) each
diff --git a/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts b/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
index 3ffd6941ade..f9793ca9d1f 100644
--- a/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
@@ -1,12 +1,15 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { ThreadId } from "@t3tools/contracts";
+import { ProviderDriverKind, ThreadId } from "@t3tools/contracts";
 import { it, assert } from "@effect/vitest";
-import { assertFailure, assertSome } from "@effect/vitest/utils";
-import { Effect, Layer, Option } from "effect";
+import { assertSome } from "@effect/vitest/utils";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import {
@@ -15,7 +18,6 @@ import {
 } from "../../persistence/Layers/Sqlite.ts";
 import { ProviderSessionRuntimeRepositoryLive } from "../../persistence/Layers/ProviderSessionRuntime.ts";
 import { ProviderSessionRuntimeRepository } from "../../persistence/Services/ProviderSessionRuntime.ts";
-import { ProviderSessionDirectoryPersistenceError } from "../Errors.ts";
 import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
 import { ProviderSessionDirectoryLive } from "./ProviderSessionDirectory.ts";
 
@@ -31,7 +33,7 @@ function makeDirectoryLayer<E, R>(persistenceLayer: Layer.Layer<SqlClient.SqlCli
 }
 
 it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryLive", (it) => {
-  it("upserts, reads, and removes thread bindings", () =>
+  it("upserts and reads thread bindings", () =>
     Effect.gen(function* () {
       const directory = yield* ProviderSessionDirectory;
       const runtimeRepository = yield* ProviderSessionRuntimeRepository;
@@ -39,7 +41,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const initialThreadId = ThreadId.make("thread-1");
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: initialThreadId,
       });
 
@@ -48,7 +50,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const resolvedBinding = yield* directory.getBinding(initialThreadId);
       assertSome(resolvedBinding, {
         threadId: initialThreadId,
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
       });
       if (Option.isSome(resolvedBinding)) {
         assert.equal(resolvedBinding.value.threadId, initialThreadId);
@@ -57,7 +59,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const nextThreadId = ThreadId.make("thread-2");
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: nextThreadId,
       });
       const updatedBinding = yield* directory.getBinding(nextThreadId);
@@ -76,16 +78,6 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
 
       const threadIds = yield* directory.listThreadIds();
       assert.deepEqual(threadIds, [nextThreadId]);
-
-      yield* directory.remove(nextThreadId);
-      const missingProvider = yield* directory.getProvider(nextThreadId).pipe(Effect.result);
-      assertFailure(
-        missingProvider,
-        new ProviderSessionDirectoryPersistenceError({
-          operation: "ProviderSessionDirectory.getProvider",
-          detail: `No persisted provider binding found for thread '${nextThreadId}'.`,
-        }),
-      );
     }));
 
   it("persists runtime fields and merges payload updates", () =>
@@ -96,7 +88,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const threadId = ThreadId.make("thread-runtime");
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId,
         status: "starting",
         resumeCursor: {
@@ -109,7 +101,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       });
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId,
         status: "running",
         runtimePayload: {
@@ -133,6 +125,80 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       }
     }));
 
+  it("lists persisted bindings with metadata in oldest-first order", () =>
+    Effect.gen(function* () {
+      const directory = yield* ProviderSessionDirectory;
+      const runtimeRepository = yield* ProviderSessionRuntimeRepository;
+
+      const olderThreadId = ThreadId.make("thread-runtime-older");
+      const newerThreadId = ThreadId.make("thread-runtime-newer");
+
+      yield* runtimeRepository.upsert({
+        threadId: newerThreadId,
+        providerName: "codex",
+        providerInstanceId: null,
+        adapterKey: "codex",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: "2026-04-14T12:05:00.000Z",
+        resumeCursor: {
+          opaque: "resume-newer",
+        },
+        runtimePayload: {
+          cwd: "/tmp/newer",
+        },
+      });
+
+      yield* runtimeRepository.upsert({
+        threadId: olderThreadId,
+        providerName: "claudeAgent",
+        providerInstanceId: null,
+        adapterKey: "claudeAgent",
+        runtimeMode: "approval-required",
+        status: "starting",
+        lastSeenAt: "2026-04-14T12:00:00.000Z",
+        resumeCursor: {
+          opaque: "resume-older",
+        },
+        runtimePayload: {
+          cwd: "/tmp/older",
+        },
+      });
+
+      const bindings = yield* directory.listBindings();
+
+      assert.deepEqual(bindings, [
+        {
+          threadId: olderThreadId,
+          provider: ProviderDriverKind.make("claudeAgent"),
+          adapterKey: "claudeAgent",
+          runtimeMode: "approval-required",
+          status: "starting",
+          lastSeenAt: "2026-04-14T12:00:00.000Z",
+          resumeCursor: {
+            opaque: "resume-older",
+          },
+          runtimePayload: {
+            cwd: "/tmp/older",
+          },
+        },
+        {
+          threadId: newerThreadId,
+          provider: ProviderDriverKind.make("codex"),
+          adapterKey: "codex",
+          runtimeMode: "full-access",
+          status: "running",
+          lastSeenAt: "2026-04-14T12:05:00.000Z",
+          resumeCursor: {
+            opaque: "resume-newer",
+          },
+          runtimePayload: {
+            cwd: "/tmp/newer",
+          },
+        },
+      ]);
+    }));
+
   it("resets adapterKey to the new provider when provider changes without an explicit adapter key", () =>
     Effect.gen(function* () {
       const directory = yield* ProviderSessionDirectory;
@@ -142,16 +208,17 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       yield* runtimeRepository.upsert({
         threadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "running",
-        lastSeenAt: new Date().toISOString(),
+        lastSeenAt: "2026-01-01T00:00:00.000Z",
         resumeCursor: null,
         runtimePayload: null,
       });
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId,
       });
 
@@ -174,7 +241,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       yield* Effect.gen(function* () {
         const directory = yield* ProviderSessionDirectory;
         yield* directory.upsert({
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           threadId,
         });
       }).pipe(Effect.provide(directoryLayer));
@@ -188,7 +255,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
         const resolvedBinding = yield* directory.getBinding(threadId);
         assertSome(resolvedBinding, {
           threadId,
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
         });
         if (Option.isSome(resolvedBinding)) {
           assert.equal(resolvedBinding.value.threadId, threadId);
diff --git a/apps/server/src/provider/Layers/ProviderSessionDirectory.ts b/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
index 961c63d6961..0508f6c8cb3 100644
--- a/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
@@ -1,13 +1,20 @@
-import { type ProviderKind, type ThreadId } from "@t3tools/contracts";
-import { Effect, Layer, Option } from "effect";
-
+import { defaultInstanceIdForDriver, ProviderDriverKind, type ThreadId } from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import type { ProviderSessionRuntime } from "../../persistence/Services/ProviderSessionRuntime.ts";
 import { ProviderSessionRuntimeRepository } from "../../persistence/Services/ProviderSessionRuntime.ts";
 import { ProviderSessionDirectoryPersistenceError, ProviderValidationError } from "../Errors.ts";
 import {
   ProviderSessionDirectory,
   type ProviderRuntimeBinding,
+  type ProviderRuntimeBindingWithMetadata,
   type ProviderSessionDirectoryShape,
 } from "../Services/ProviderSessionDirectory.ts";
+const decodeProviderDriverKindValue = Schema.decodeUnknownEffect(ProviderDriverKind);
 
 function toPersistenceError(operation: string) {
   return (cause: unknown) =>
@@ -18,18 +25,19 @@ function toPersistenceError(operation: string) {
     });
 }
 
-function decodeProviderKind(
+function decodeProviderDriverKind(
   providerName: string,
   operation: string,
-): Effect.Effect<ProviderKind, ProviderSessionDirectoryPersistenceError> {
-  if (providerName === "codex" || providerName === "claudeAgent") {
-    return Effect.succeed(providerName);
-  }
-  return Effect.fail(
-    new ProviderSessionDirectoryPersistenceError({
-      operation,
-      detail: `Unknown persisted provider '${providerName}'.`,
-    }),
+): Effect.Effect<ProviderDriverKind, ProviderSessionDirectoryPersistenceError> {
+  return decodeProviderDriverKindValue(providerName).pipe(
+    Effect.mapError(
+      (cause) =>
+        new ProviderSessionDirectoryPersistenceError({
+          operation,
+          detail: `Unknown persisted provider '${providerName}'.`,
+          cause,
+        }),
+    ),
   );
 }
 
@@ -50,6 +58,32 @@ function mergeRuntimePayload(
   return next;
 }
 
+function toRuntimeBinding(
+  runtime: ProviderSessionRuntime,
+  operation: string,
+): Effect.Effect<ProviderRuntimeBindingWithMetadata, ProviderSessionDirectoryPersistenceError> {
+  return decodeProviderDriverKind(runtime.providerName, operation).pipe(
+    Effect.map(
+      (provider) =>
+        ({
+          threadId: runtime.threadId,
+          provider,
+          // Migration boundary only: rows written before the instance split
+          // have a null provider_instance_id. Promote them as they leave
+          // persistence so hot routing code never has to infer an instance
+          // from a driver kind.
+          providerInstanceId: runtime.providerInstanceId ?? defaultInstanceIdForDriver(provider),
+          adapterKey: runtime.adapterKey,
+          runtimeMode: runtime.runtimeMode,
+          status: runtime.status,
+          resumeCursor: runtime.resumeCursor,
+          runtimePayload: runtime.runtimePayload,
+          lastSeenAt: runtime.lastSeenAt,
+        }) satisfies ProviderRuntimeBindingWithMetadata,
+    ),
+  );
+}
+
 const makeProviderSessionDirectory = Effect.gen(function* () {
   const repository = yield* ProviderSessionRuntimeRepository;
 
@@ -60,18 +94,8 @@ const makeProviderSessionDirectory = Effect.gen(function* () {
         Option.match(runtime, {
           onNone: () => Effect.succeed(Option.none<ProviderRuntimeBinding>()),
           onSome: (value) =>
-            decodeProviderKind(value.providerName, "ProviderSessionDirectory.getBinding").pipe(
-              Effect.map((provider) =>
-                Option.some({
-                  threadId: value.threadId,
-                  provider,
-                  adapterKey: value.adapterKey,
-                  runtimeMode: value.runtimeMode,
-                  status: value.status,
-                  resumeCursor: value.resumeCursor,
-                  runtimePayload: value.runtimePayload,
-                }),
-              ),
+            toRuntimeBinding(value, "ProviderSessionDirectory.getBinding").pipe(
+              Effect.map((binding) => Option.some(binding)),
             ),
         }),
       ),
@@ -91,13 +115,22 @@ const makeProviderSessionDirectory = Effect.gen(function* () {
       });
     }
 
-    const now = new Date().toISOString();
+    const now = DateTime.formatIso(yield* DateTime.now);
     const providerChanged =
       existingRuntime !== undefined && existingRuntime.providerName !== binding.provider;
+    const providerInstanceId =
+      binding.providerInstanceId ?? (!providerChanged ? existingRuntime?.providerInstanceId : null);
+    if (providerInstanceId === null || providerInstanceId === undefined) {
+      return yield* new ProviderValidationError({
+        operation: "ProviderSessionDirectory.upsert",
+        issue: "providerInstanceId is required for provider session runtime bindings.",
+      });
+    }
     yield* repository
       .upsert({
         threadId: resolvedThreadId,
         providerName: binding.provider,
+        providerInstanceId,
         adapterKey:
           binding.adapterKey ??
           (providerChanged ? binding.provider : (existingRuntime?.adapterKey ?? binding.provider)),
@@ -132,25 +165,30 @@ const makeProviderSessionDirectory = Effect.gen(function* () {
       ),
     );
 
-  const remove: ProviderSessionDirectoryShape["remove"] = (threadId) =>
-    repository
-      .deleteByThreadId({ threadId })
-      .pipe(
-        Effect.mapError(toPersistenceError("ProviderSessionDirectory.remove:deleteByThreadId")),
-      );
-
   const listThreadIds: ProviderSessionDirectoryShape["listThreadIds"] = () =>
     repository.list().pipe(
       Effect.mapError(toPersistenceError("ProviderSessionDirectory.listThreadIds:list")),
       Effect.map((rows) => rows.map((row) => row.threadId)),
     );
 
+  const listBindings: ProviderSessionDirectoryShape["listBindings"] = () =>
+    repository.list().pipe(
+      Effect.mapError(toPersistenceError("ProviderSessionDirectory.listBindings:list")),
+      Effect.flatMap((rows) =>
+        Effect.forEach(
+          rows,
+          (row) => toRuntimeBinding(row, "ProviderSessionDirectory.listBindings"),
+          { concurrency: "unbounded" },
+        ),
+      ),
+    );
+
   return {
     upsert,
     getProvider,
     getBinding,
-    remove,
     listThreadIds,
+    listBindings,
   } satisfies ProviderSessionDirectoryShape;
 });
 
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
new file mode 100644
index 00000000000..6bd90e283e6
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
@@ -0,0 +1,577 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import {
+  ProjectId,
+  ThreadId,
+  TurnId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Option from "effect/Option";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
+import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
+import { ProviderSessionRuntimeRepositoryLive } from "../../persistence/Layers/ProviderSessionRuntime.ts";
+import { ProviderSessionRuntimeRepository } from "../../persistence/Services/ProviderSessionRuntime.ts";
+import { ProviderValidationError } from "../Errors.ts";
+import { ProviderSessionReaper } from "../Services/ProviderSessionReaper.ts";
+import { ProviderService, type ProviderServiceShape } from "../Services/ProviderService.ts";
+import { ProviderSessionDirectoryLive } from "./ProviderSessionDirectory.ts";
+import { makeProviderSessionReaperLive } from "./ProviderSessionReaper.ts";
+
+const defaultModelSelection = {
+  instanceId: ProviderInstanceId.make("codex"),
+  model: "gpt-5-codex",
+} as const;
+
+async function waitFor(
+  predicate: () => boolean | Promise<boolean>,
+  timeoutMs = 2_000,
+): Promise<void> {
+  const deadline = (await Effect.runPromise(Clock.currentTimeMillis)) + timeoutMs;
+  const poll = async (): Promise<void> => {
+    if (await predicate()) {
+      return;
+    }
+    if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
+      throw new Error("Timed out waiting for expectation.");
+    }
+    await Effect.runPromise(Effect.yieldNow);
+    return poll();
+  };
+
+  return poll();
+}
+
+const drainFibers = Effect.forEach(Array.from({ length: 10 }), () => Effect.yieldNow, {
+  discard: true,
+});
+
+const unsupported = () => Effect.die(new Error("Unsupported provider call in test")) as never;
+
+function makeReadModel(
+  threads: ReadonlyArray<{
+    readonly id: ThreadId;
+    readonly session: {
+      readonly threadId: ThreadId;
+      readonly status: "starting" | "running" | "ready" | "interrupted" | "stopped" | "error";
+      readonly providerName: "codex" | "claudeAgent";
+      readonly runtimeMode: "approval-required" | "full-access" | "auto-accept-edits";
+      readonly activeTurnId: TurnId | null;
+      readonly lastError: string | null;
+      readonly updatedAt: string;
+    } | null;
+  }>,
+) {
+  const now = "2026-01-01T00:00:00.000Z";
+  const projectId = ProjectId.make("project-provider-session-reaper");
+
+  return {
+    snapshotSequence: 0,
+    updatedAt: now,
+    projects: [
+      {
+        id: projectId,
+        title: "Provider Reaper Project",
+        workspaceRoot: "/tmp/provider-reaper-project",
+        defaultModelSelection,
+        scripts: [],
+        createdAt: now,
+        updatedAt: now,
+        deletedAt: null,
+      },
+    ],
+    threads: threads.map((thread) => ({
+      id: thread.id,
+      projectId,
+      title: `Thread ${thread.id}`,
+      modelSelection: defaultModelSelection,
+      interactionMode: "default" as const,
+      runtimeMode: "full-access" as const,
+      branch: null,
+      worktreePath: null,
+      createdAt: now,
+      updatedAt: now,
+      archivedAt: null,
+      latestUserMessageAt: null,
+      hasPendingApprovals: false,
+      hasPendingUserInput: false,
+      hasActionableProposedPlan: false,
+      latestTurn: null,
+      messages: [],
+      session: thread.session,
+      activities: [],
+      proposedPlans: [],
+      checkpoints: [],
+      deletedAt: null,
+    })),
+  };
+}
+
+describe("ProviderSessionReaper", () => {
+  let runtime: ManagedRuntime.ManagedRuntime<
+    ProviderSessionReaper | ProviderSessionRuntimeRepository,
+    unknown
+  > | null = null;
+  let scope: Scope.Closeable | null = null;
+
+  afterEach(async () => {
+    if (scope) {
+      await Effect.runPromise(Scope.close(scope, Exit.void));
+    }
+    scope = null;
+    if (runtime) {
+      await runtime.dispose();
+    }
+    runtime = null;
+  });
+
+  async function createHarness(input: {
+    readonly readModel: ReturnType<typeof makeReadModel>;
+    readonly stopSessionImplementation?: (input: {
+      readonly threadId: ThreadId;
+    }) => ReturnType<ProviderServiceShape["stopSession"]>;
+  }) {
+    const stoppedThreadIds = new Set<ThreadId>();
+    const stopSession = vi.fn<ProviderServiceShape["stopSession"]>(
+      (request) =>
+        (input.stopSessionImplementation
+          ? input.stopSessionImplementation(request)
+          : Effect.sync(() => {
+              stoppedThreadIds.add(request.threadId);
+            })) as ReturnType<ProviderServiceShape["stopSession"]>,
+    );
+
+    const providerService: ProviderServiceShape = {
+      startSession: () => unsupported(),
+      sendTurn: () => unsupported(),
+      interruptTurn: () => unsupported(),
+      respondToRequest: () => unsupported(),
+      respondToUserInput: () => unsupported(),
+      stopSession,
+      listSessions: () => Effect.succeed([]),
+      getCapabilities: () => Effect.succeed({ sessionModelSwitch: "in-session" }),
+      getInstanceInfo: (instanceId) => {
+        const driverKind = ProviderDriverKind.make(String(instanceId));
+        return Effect.succeed({
+          instanceId,
+          driverKind,
+          displayName: undefined,
+          enabled: true,
+          continuationIdentity: {
+            driverKind,
+            continuationKey: `${driverKind}:instance:${instanceId}`,
+          },
+        });
+      },
+      rollbackConversation: () => unsupported(),
+      streamEvents: Stream.empty,
+    };
+
+    const runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
+      Layer.provide(SqlitePersistenceMemory),
+    );
+    const providerSessionDirectoryLayer = ProviderSessionDirectoryLive.pipe(
+      Layer.provide(runtimeRepositoryLayer),
+    );
+    const layer = makeProviderSessionReaperLive({
+      inactivityThresholdMs: 1_000,
+      sweepIntervalMs: 60_000,
+    }).pipe(
+      Layer.provideMerge(providerSessionDirectoryLayer),
+      Layer.provideMerge(runtimeRepositoryLayer),
+      Layer.provideMerge(Layer.succeed(ProviderService, providerService)),
+      Layer.provideMerge(
+        Layer.succeed(ProjectionSnapshotQuery, {
+          getCommandReadModel: () => Effect.die("unused"),
+          getSnapshot: () => Effect.die("unused"),
+          getShellSnapshot: () => Effect.die("unused"),
+          getArchivedShellSnapshot: () => Effect.die("unused"),
+          getSnapshotSequence: () =>
+            Effect.succeed({ snapshotSequence: input.readModel.snapshotSequence }),
+          getCounts: () => Effect.die("unused"),
+          getActiveProjectByWorkspaceRoot: () => Effect.die("unused"),
+          getProjectShellById: () => Effect.die("unused"),
+          getFirstActiveThreadIdByProjectId: () => Effect.die("unused"),
+          getThreadCheckpointContext: () => Effect.die("unused"),
+          getFullThreadDiffContext: () => Effect.die("unused"),
+          getThreadShellById: (threadId) =>
+            Effect.succeed(
+              input.readModel.threads.find((thread) => thread.id === threadId)
+                ? Option.some(input.readModel.threads.find((thread) => thread.id === threadId)!)
+                : Option.none(),
+            ),
+          getThreadDetailById: () => Effect.die("unused"),
+        }),
+      ),
+      Layer.provideMerge(NodeServices.layer),
+    );
+
+    runtime = ManagedRuntime.make(layer);
+    return { stopSession, stoppedThreadIds };
+  }
+
+  it("reaps stale persisted sessions without active turns", async () => {
+    const threadId = ThreadId.make("thread-reaper-stale");
+    const now = "2026-01-01T00:00:00.000Z";
+    const harness = await createHarness({
+      readModel: makeReadModel([
+        {
+          id: threadId,
+          session: {
+            threadId,
+            status: "ready",
+            providerName: "claudeAgent",
+            runtimeMode: "full-access",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+      ]),
+    });
+    const repository = await runtime!.runPromise(Effect.service(ProviderSessionRuntimeRepository));
+
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId,
+        providerName: "claudeAgent",
+        providerInstanceId: null,
+        adapterKey: "claudeAgent",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: "2026-04-14T00:00:00.000Z",
+        resumeCursor: {
+          opaque: "resume-stale",
+        },
+        runtimePayload: null,
+      }),
+    );
+
+    const reaper = await runtime!.runPromise(Effect.service(ProviderSessionReaper));
+    scope = await Effect.runPromise(Scope.make("sequential"));
+    await Effect.runPromise(reaper.start().pipe(Scope.provide(scope)));
+
+    await waitFor(() => harness.stopSession.mock.calls.length === 1);
+
+    expect(harness.stopSession.mock.calls[0]?.[0]).toEqual({ threadId });
+    expect(harness.stoppedThreadIds.has(threadId)).toBe(true);
+  });
+
+  it("skips stale sessions when the thread still has an active turn", async () => {
+    const threadId = ThreadId.make("thread-reaper-active-turn");
+    const turnId = TurnId.make("turn-reaper-active");
+    const now = "2026-01-01T00:00:00.000Z";
+    const harness = await createHarness({
+      readModel: makeReadModel([
+        {
+          id: threadId,
+          session: {
+            threadId,
+            status: "running",
+            providerName: "claudeAgent",
+            runtimeMode: "full-access",
+            activeTurnId: turnId,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+      ]),
+    });
+    const repository = await runtime!.runPromise(Effect.service(ProviderSessionRuntimeRepository));
+
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId,
+        providerName: "claudeAgent",
+        providerInstanceId: null,
+        adapterKey: "claudeAgent",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: "2026-04-14T00:00:00.000Z",
+        resumeCursor: {
+          opaque: "resume-active-turn",
+        },
+        runtimePayload: null,
+      }),
+    );
+
+    const reaper = await runtime!.runPromise(Effect.service(ProviderSessionReaper));
+    scope = await Effect.runPromise(Scope.make("sequential"));
+    await Effect.runPromise(reaper.start().pipe(Scope.provide(scope)));
+    await Effect.runPromise(drainFibers);
+
+    expect(harness.stopSession).not.toHaveBeenCalled();
+    const remaining = await runtime!.runPromise(repository.getByThreadId({ threadId }));
+    expect(Option.isSome(remaining)).toBe(true);
+  });
+
+  it("does not reap sessions that are still within the inactivity threshold", async () => {
+    const threadId = ThreadId.make("thread-reaper-fresh");
+    const now = DateTime.formatIso(await Effect.runPromise(DateTime.now));
+    const harness = await createHarness({
+      readModel: makeReadModel([
+        {
+          id: threadId,
+          session: {
+            threadId,
+            status: "ready",
+            providerName: "claudeAgent",
+            runtimeMode: "full-access",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+      ]),
+    });
+    const repository = await runtime!.runPromise(Effect.service(ProviderSessionRuntimeRepository));
+
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId,
+        providerName: "claudeAgent",
+        providerInstanceId: null,
+        adapterKey: "claudeAgent",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: now,
+        resumeCursor: {
+          opaque: "resume-fresh",
+        },
+        runtimePayload: null,
+      }),
+    );
+
+    const reaper = await runtime!.runPromise(Effect.service(ProviderSessionReaper));
+    scope = await Effect.runPromise(Scope.make("sequential"));
+    await Effect.runPromise(reaper.start().pipe(Scope.provide(scope)));
+    await Effect.runPromise(drainFibers);
+
+    expect(harness.stopSession).not.toHaveBeenCalled();
+    const remaining = await runtime!.runPromise(repository.getByThreadId({ threadId }));
+    expect(Option.isSome(remaining)).toBe(true);
+  });
+
+  it("skips persisted sessions that are already marked stopped", async () => {
+    const threadId = ThreadId.make("thread-reaper-stopped");
+    const now = "2026-01-01T00:00:00.000Z";
+    const harness = await createHarness({
+      readModel: makeReadModel([
+        {
+          id: threadId,
+          session: {
+            threadId,
+            status: "stopped",
+            providerName: "claudeAgent",
+            runtimeMode: "full-access",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+      ]),
+    });
+    const repository = await runtime!.runPromise(Effect.service(ProviderSessionRuntimeRepository));
+
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId,
+        providerName: "claudeAgent",
+        providerInstanceId: null,
+        adapterKey: "claudeAgent",
+        runtimeMode: "full-access",
+        status: "stopped",
+        lastSeenAt: "2026-04-14T00:00:00.000Z",
+        resumeCursor: {
+          opaque: "resume-stopped",
+        },
+        runtimePayload: null,
+      }),
+    );
+
+    const reaper = await runtime!.runPromise(Effect.service(ProviderSessionReaper));
+    scope = await Effect.runPromise(Scope.make("sequential"));
+    await Effect.runPromise(reaper.start().pipe(Scope.provide(scope)));
+    await Effect.runPromise(drainFibers);
+
+    expect(harness.stopSession).not.toHaveBeenCalled();
+    const remaining = await runtime!.runPromise(repository.getByThreadId({ threadId }));
+    expect(Option.isSome(remaining)).toBe(true);
+  });
+
+  it("continues reaping other sessions when one stop attempt fails", async () => {
+    const failedThreadId = ThreadId.make("thread-reaper-stop-failure");
+    const reapedThreadId = ThreadId.make("thread-reaper-stop-success");
+    const now = "2026-01-01T00:00:00.000Z";
+    const harness = await createHarness({
+      readModel: makeReadModel([
+        {
+          id: failedThreadId,
+          session: {
+            threadId: failedThreadId,
+            status: "ready",
+            providerName: "claudeAgent",
+            runtimeMode: "full-access",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+        {
+          id: reapedThreadId,
+          session: {
+            threadId: reapedThreadId,
+            status: "ready",
+            providerName: "codex",
+            runtimeMode: "full-access",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+      ]),
+      stopSessionImplementation: (request) =>
+        request.threadId === failedThreadId
+          ? Effect.fail(
+              new ProviderValidationError({
+                operation: "ProviderSessionReaper.test",
+                issue: "simulated stop failure",
+              }),
+            )
+          : Effect.void,
+    });
+    const repository = await runtime!.runPromise(Effect.service(ProviderSessionRuntimeRepository));
+
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId: failedThreadId,
+        providerName: "claudeAgent",
+        providerInstanceId: null,
+        adapterKey: "claudeAgent",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: "2026-04-14T00:00:00.000Z",
+        resumeCursor: {
+          opaque: "resume-failure",
+        },
+        runtimePayload: null,
+      }),
+    );
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId: reapedThreadId,
+        providerName: "codex",
+        providerInstanceId: null,
+        adapterKey: "codex",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: "2026-04-14T00:01:00.000Z",
+        resumeCursor: {
+          opaque: "resume-success",
+        },
+        runtimePayload: null,
+      }),
+    );
+
+    const reaper = await runtime!.runPromise(Effect.service(ProviderSessionReaper));
+    scope = await Effect.runPromise(Scope.make("sequential"));
+    await Effect.runPromise(reaper.start().pipe(Scope.provide(scope)));
+
+    await waitFor(() => harness.stopSession.mock.calls.length === 2);
+
+    expect(harness.stopSession.mock.calls.map(([request]) => request.threadId)).toEqual([
+      failedThreadId,
+      reapedThreadId,
+    ]);
+  });
+
+  it("continues reaping other sessions when one stop attempt defects", async () => {
+    const defectThreadId = ThreadId.make("thread-reaper-stop-defect");
+    const reapedThreadId = ThreadId.make("thread-reaper-stop-after-defect");
+    const now = "2026-01-01T00:00:00.000Z";
+    const harness = await createHarness({
+      readModel: makeReadModel([
+        {
+          id: defectThreadId,
+          session: {
+            threadId: defectThreadId,
+            status: "ready",
+            providerName: "claudeAgent",
+            runtimeMode: "full-access",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+        {
+          id: reapedThreadId,
+          session: {
+            threadId: reapedThreadId,
+            status: "ready",
+            providerName: "codex",
+            runtimeMode: "full-access",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: now,
+          },
+        },
+      ]),
+      stopSessionImplementation: (request) =>
+        request.threadId === defectThreadId
+          ? Effect.die(new Error("simulated stop defect"))
+          : Effect.void,
+    });
+    const repository = await runtime!.runPromise(Effect.service(ProviderSessionRuntimeRepository));
+
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId: defectThreadId,
+        providerName: "claudeAgent",
+        providerInstanceId: null,
+        adapterKey: "claudeAgent",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: "2026-04-14T00:00:00.000Z",
+        resumeCursor: {
+          opaque: "resume-defect",
+        },
+        runtimePayload: null,
+      }),
+    );
+    await runtime!.runPromise(
+      repository.upsert({
+        threadId: reapedThreadId,
+        providerName: "codex",
+        providerInstanceId: null,
+        adapterKey: "codex",
+        runtimeMode: "full-access",
+        status: "running",
+        lastSeenAt: "2026-04-14T00:01:00.000Z",
+        resumeCursor: {
+          opaque: "resume-after-defect",
+        },
+        runtimePayload: null,
+      }),
+    );
+
+    const reaper = await runtime!.runPromise(Effect.service(ProviderSessionReaper));
+    scope = await Effect.runPromise(Scope.make("sequential"));
+    await Effect.runPromise(reaper.start().pipe(Scope.provide(scope)));
+
+    await waitFor(() => harness.stopSession.mock.calls.length === 2);
+
+    expect(harness.stopSession.mock.calls.map(([request]) => request.threadId)).toEqual([
+      defectThreadId,
+      reapedThreadId,
+    ]);
+  });
+});
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.ts
new file mode 100644
index 00000000000..ca396b40596
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.ts
@@ -0,0 +1,138 @@
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schedule from "effect/Schedule";
+
+import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
+import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
+import {
+  ProviderSessionReaper,
+  type ProviderSessionReaperShape,
+} from "../Services/ProviderSessionReaper.ts";
+import { ProviderService } from "../Services/ProviderService.ts";
+
+const DEFAULT_INACTIVITY_THRESHOLD_MS = 30 * 60 * 1000;
+const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+
+export interface ProviderSessionReaperLiveOptions {
+  readonly inactivityThresholdMs?: number;
+  readonly sweepIntervalMs?: number;
+}
+
+const makeProviderSessionReaper = (options?: ProviderSessionReaperLiveOptions) =>
+  Effect.gen(function* () {
+    const providerService = yield* ProviderService;
+    const directory = yield* ProviderSessionDirectory;
+    const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
+
+    const inactivityThresholdMs = Math.max(
+      1,
+      options?.inactivityThresholdMs ?? DEFAULT_INACTIVITY_THRESHOLD_MS,
+    );
+    const sweepIntervalMs = Math.max(1, options?.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS);
+
+    const sweep = Effect.gen(function* () {
+      const bindings = yield* directory.listBindings();
+      const now = yield* Clock.currentTimeMillis;
+      let reapedCount = 0;
+
+      for (const binding of bindings) {
+        if (binding.status === "stopped") {
+          continue;
+        }
+
+        const lastSeenMs = Date.parse(binding.lastSeenAt);
+        if (Number.isNaN(lastSeenMs)) {
+          yield* Effect.logWarning("provider.session.reaper.invalid-last-seen", {
+            threadId: binding.threadId,
+            provider: binding.provider,
+            lastSeenAt: binding.lastSeenAt,
+          });
+          continue;
+        }
+
+        const idleDurationMs = now - lastSeenMs;
+        if (idleDurationMs < inactivityThresholdMs) {
+          continue;
+        }
+
+        const thread = yield* projectionSnapshotQuery
+          .getThreadShellById(binding.threadId)
+          .pipe(Effect.map(Option.getOrUndefined));
+        if (thread?.session?.activeTurnId != null) {
+          yield* Effect.logDebug("provider.session.reaper.skipped-active-turn", {
+            threadId: binding.threadId,
+            activeTurnId: thread.session.activeTurnId,
+            idleDurationMs,
+          });
+          continue;
+        }
+
+        const reaped = yield* providerService.stopSession({ threadId: binding.threadId }).pipe(
+          Effect.tap(() =>
+            Effect.logInfo("provider.session.reaped", {
+              threadId: binding.threadId,
+              provider: binding.provider,
+              idleDurationMs,
+              reason: "inactivity_threshold",
+            }),
+          ),
+          Effect.as(true),
+          Effect.catchCause((cause) =>
+            Effect.logWarning("provider.session.reaper.stop-failed", {
+              threadId: binding.threadId,
+              provider: binding.provider,
+              idleDurationMs,
+              cause,
+            }).pipe(Effect.as(false)),
+          ),
+        );
+
+        if (reaped) {
+          reapedCount += 1;
+        }
+      }
+
+      if (reapedCount > 0) {
+        yield* Effect.logInfo("provider.session.reaper.sweep-complete", {
+          reapedCount,
+          totalBindings: bindings.length,
+        });
+      }
+    });
+
+    const start: ProviderSessionReaperShape["start"] = () =>
+      Effect.gen(function* () {
+        yield* Effect.forkScoped(
+          sweep.pipe(
+            Effect.catch((error: unknown) =>
+              Effect.logWarning("provider.session.reaper.sweep-failed", {
+                error,
+              }),
+            ),
+            Effect.catchDefect((defect: unknown) =>
+              Effect.logWarning("provider.session.reaper.sweep-defect", {
+                defect,
+              }),
+            ),
+            Effect.repeat(Schedule.spaced(Duration.millis(sweepIntervalMs))),
+          ),
+        );
+
+        yield* Effect.logInfo("provider.session.reaper.started", {
+          inactivityThresholdMs,
+          sweepIntervalMs,
+        });
+      });
+
+    return {
+      start,
+    } satisfies ProviderSessionReaperShape;
+  });
+
+export const makeProviderSessionReaperLive = (options?: ProviderSessionReaperLiveOptions) =>
+  Layer.effect(ProviderSessionReaper, makeProviderSessionReaper(options));
+
+export const ProviderSessionReaperLive = makeProviderSessionReaperLive();
diff --git a/apps/server/src/provider/ProviderDriver.ts b/apps/server/src/provider/ProviderDriver.ts
new file mode 100644
index 00000000000..3a57f374de4
--- /dev/null
+++ b/apps/server/src/provider/ProviderDriver.ts
@@ -0,0 +1,169 @@
+/**
+ * ProviderDriver / ProviderInstance — driver SPI as plain values.
+ *
+ * `ProviderDriver` is a record, not a Context.Service. The thing it produces
+ * (`ProviderInstance`) is also a record — three captured closures
+ * (`snapshot`, `adapter`, `textGeneration`), an id, and a driver kind. There
+ * are intentionally no per-driver Context tags because tags are
+ * singleton-per-runtime and we need many instances of the same driver.
+ *
+ * The only Effect service involved is `ProviderInstanceRegistry`, which
+ * owns the live `Map<InstanceId, ProviderInstance>` and is itself a
+ * singleton.
+ *
+ * Driver factories are functions of `(typed config, env)` where:
+ *   - `typed config` is decoded once by the registry via `configSchema`,
+ *     so drivers never deal with raw `unknown`.
+ *   - `env` flows through Effect's R channel. Each driver declares the
+ *     subset of infrastructure services it needs (FileSystem,
+ *     ChildProcessSpawner, …) on its `create` return type; the registry
+ *     layer's R is the union of those, and the runtime layer satisfies it.
+ *
+ * @module provider/ProviderDriver
+ */
+import type {
+  ProviderDriverKind,
+  ProviderInstanceEnvironment,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
+import type * as Effect from "effect/Effect";
+import type * as Schema from "effect/Schema";
+import type * as Scope from "effect/Scope";
+
+import type { TextGenerationShape } from "../textGeneration/TextGeneration.ts";
+import type { ProviderAdapterError, ProviderDriverError } from "./Errors.ts";
+import type { ProviderAdapterShape } from "./Services/ProviderAdapter.ts";
+import type { ServerProviderShape } from "./Services/ServerProvider.ts";
+
+/**
+ * Static metadata advertised by a driver. Used for default presentation
+ * and (later) settings UI. Doesn't need to be Effect-typed because nothing
+ * about it is dynamic — drivers are registered at startup.
+ */
+export interface ProviderDriverMetadata {
+  /** Human-readable name for the driver itself (e.g. "Codex"). */
+  readonly displayName: string;
+  /**
+   * Whether the driver may be instantiated more than once concurrently.
+   * Defaults to `true`. Set to `false` for drivers that wrap a global
+   * resource (e.g. a single desktop app socket) — the registry then
+   * rejects multi-instance configurations with a clear error.
+   */
+  readonly supportsMultipleInstances?: boolean;
+}
+
+/**
+ * One materialized provider instance. Held by the registry, looked up by
+ * `instanceId`, torn down by closing the scope it was created in.
+ *
+ * The three "shape" fields are captured closures owned by this instance —
+ * stopping one instance cannot affect another, and starting a second
+ * instance of the same driver does not reach into the first instance's
+ * state.
+ */
+export interface ProviderInstance {
+  readonly instanceId: ProviderInstanceId;
+  readonly driverKind: ProviderDriverKind;
+  readonly continuationIdentity: ProviderContinuationIdentity;
+  readonly displayName: string | undefined;
+  readonly accentColor?: string | undefined;
+  readonly enabled: boolean;
+  readonly snapshot: ServerProviderShape;
+  readonly adapter: ProviderAdapterShape<ProviderAdapterError>;
+  readonly textGeneration: TextGenerationShape;
+}
+
+export interface ProviderContinuationIdentity {
+  readonly driverKind: ProviderDriverKind;
+  readonly continuationKey: string;
+}
+
+export function defaultProviderContinuationIdentity(input: {
+  readonly driverKind: ProviderDriverKind;
+  readonly instanceId: ProviderInstanceId;
+}): ProviderContinuationIdentity {
+  return {
+    driverKind: input.driverKind,
+    continuationKey: `${input.driverKind}:instance:${input.instanceId}`,
+  };
+}
+
+/**
+ * Inputs the registry passes to a driver's `create` function.
+ *
+ * `config` is the typed payload — already decoded by the registry through
+ * `driver.configSchema`. Drivers never decode their own raw envelope.
+ */
+export interface ProviderDriverCreateInput<Config> {
+  readonly instanceId: ProviderInstanceId;
+  readonly displayName: string | undefined;
+  readonly accentColor?: string | undefined;
+  readonly environment: ProviderInstanceEnvironment;
+  readonly enabled: boolean;
+  readonly config: Config;
+}
+
+/**
+ * Driver SPI — registered as a plain value, not a Layer.
+ *
+ * `Config` is whatever the driver decoded from
+ * `ProviderInstanceConfig.config`. `R` is the union of infrastructure
+ * services the driver depends on; the registry layer aggregates `R` across
+ * all registered drivers and the runtime supplies them.
+ *
+ * `create` is responsible for *all* per-instance state — process handles,
+ * pubsub topics, refs, file watchers — and must release them when its
+ * scope closes. Two calls to `create` with different `instanceId` /
+ * `config` MUST yield instances with no shared mutable state.
+ */
+export interface ProviderDriver<Config, R = never> {
+  readonly driverKind: ProviderDriverKind;
+  readonly metadata: ProviderDriverMetadata;
+  /**
+   * Decoder for the opaque `ProviderInstanceConfig.config` envelope. The
+   * registry runs this exactly once per (re)load of an instance; a decode
+   * failure is surfaced as `ProviderDriverError` and downgraded to an
+   * unavailable shadow snapshot.
+   *
+   * The `Encoded` parameter is intentionally left as `unknown` (not
+   * `Config`) so schemas with `withDecodingDefault` / transformations — where
+   * the encoded shape differs from the decoded shape — satisfy the SPI
+   * without casts. The registry only ever decodes `unknown` envelopes here,
+   * so the precise encoded type is irrelevant at this boundary.
+   *
+   * Using `Codec` rather than `Schema` pins `DecodingServices = never` — if
+   * we used `Schema<Config>`, the erased `any` in `AnyProviderDriver` would
+   * widen `DecodingServices` to `unknown` and poison the R channel of every
+   * caller of `decodeUnknownEffect`.
+   */
+  readonly configSchema: Schema.Codec<Config, unknown>;
+  /**
+   * Default config payload used when the legacy
+   * `ServerSettings.providers.<kind>` entry is empty or when the driver
+   * is auto-bootstrapped without user configuration. Returning a typed
+   * default keeps the migration path simple — no special-casing needed
+   * to construct a "blank" instance.
+   */
+  readonly defaultConfig: () => Config;
+  /**
+   * Materialize one instance. The returned effect runs in a scope owned
+   * by the registry; closing that scope releases every resource the
+   * driver opened. Failures become unavailable shadow snapshots — the
+   * driver MUST NOT throw defects.
+   */
+  readonly create: (
+    input: ProviderDriverCreateInput<Config>,
+  ) => Effect.Effect<ProviderInstance, ProviderDriverError, R | Scope.Scope>;
+}
+
+/**
+ * Heterogeneous-array convenience: the registry stores drivers as
+ * `ReadonlyArray<AnyProviderDriver<R>>` where `R` is the union of all
+ * registered drivers' env requirements.
+ */
+// `any` here intentionally erases the per-driver Config; the registry
+// already decoded it before invoking `create`, so downstream code never
+// needs the original `Config` type. Using `unknown` instead would force
+// `create` callers into casts since `unknown` is not assignable to a
+// concrete `Config` from inside the driver body.
+export type AnyProviderDriver<R = never> = ProviderDriver<any, R>;
diff --git a/apps/server/src/provider/ProviderInstanceEnvironment.test.ts b/apps/server/src/provider/ProviderInstanceEnvironment.test.ts
new file mode 100644
index 00000000000..f37b328b150
--- /dev/null
+++ b/apps/server/src/provider/ProviderInstanceEnvironment.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+
+import { mergeProviderInstanceEnvironment } from "./ProviderInstanceEnvironment.ts";
+
+describe("mergeProviderInstanceEnvironment", () => {
+  it("overrides inherited environment values and preserves empty strings", () => {
+    expect(
+      mergeProviderInstanceEnvironment(
+        [
+          { name: "OPENROUTER_API_KEY", value: "sk-or-test", sensitive: true },
+          { name: "ANTHROPIC_API_KEY", value: "", sensitive: false },
+        ],
+        { ANTHROPIC_API_KEY: "inherited", PATH: "/bin" },
+      ),
+    ).toMatchObject({
+      OPENROUTER_API_KEY: "sk-or-test",
+      ANTHROPIC_API_KEY: "",
+      PATH: "/bin",
+    });
+  });
+});
diff --git a/apps/server/src/provider/ProviderInstanceEnvironment.ts b/apps/server/src/provider/ProviderInstanceEnvironment.ts
new file mode 100644
index 00000000000..e469253604e
--- /dev/null
+++ b/apps/server/src/provider/ProviderInstanceEnvironment.ts
@@ -0,0 +1,16 @@
+import type { ProviderInstanceEnvironment } from "@t3tools/contracts";
+
+export function mergeProviderInstanceEnvironment(
+  environment: ProviderInstanceEnvironment | undefined,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  if (!environment || environment.length === 0) {
+    return baseEnv;
+  }
+
+  const next: NodeJS.ProcessEnv = { ...baseEnv };
+  for (const variable of environment) {
+    next[variable.name] = variable.value;
+  }
+  return next;
+}
diff --git a/apps/server/src/provider/Services/ClaudeAdapter.ts b/apps/server/src/provider/Services/ClaudeAdapter.ts
index e8c33bd8e40..ed9bd7081bc 100644
--- a/apps/server/src/provider/Services/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Services/ClaudeAdapter.ts
@@ -1,30 +1,19 @@
 /**
- * ClaudeAdapter - Claude Agent implementation of the generic provider adapter contract.
+ * ClaudeAdapter — shape type for the Claude provider adapter.
  *
- * This service owns Claude runtime/session semantics and emits canonical
- * provider runtime events. It does not perform cross-provider routing, shared
- * event fan-out, or checkpoint orchestration.
- *
- * Uses Effect `Context.Service` for dependency injection and returns the
- * shared provider-adapter error channel with `provider: "claudeAgent"` context.
+ * Historically this module exposed a `Context.Service` tag so consumers
+ * could inject the adapter through the Effect layer graph. The driver
+ * model ({@link ../Drivers/ClaudeDriver}) bundles one adapter per
+ * instance as a captured closure instead, so the tag is gone — we only
+ * retain the shape interface as a naming anchor for the driver bundle.
  *
  * @module ClaudeAdapter
  */
-import { Context } from "effect";
-
 import type { ProviderAdapterError } from "../Errors.ts";
 import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
 
 /**
- * ClaudeAdapterShape - Service API for the Claude Agent provider adapter.
- */
-export interface ClaudeAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {
-  readonly provider: "claudeAgent";
-}
-
-/**
- * ClaudeAdapter - Service tag for Claude Agent provider adapter operations.
+ * ClaudeAdapterShape — per-instance Claude adapter contract. Carries
+ * a branded driver kind as the nominal discriminant.
  */
-export class ClaudeAdapter extends Context.Service<ClaudeAdapter, ClaudeAdapterShape>()(
-  "t3/provider/Services/ClaudeAdapter",
-) {}
+export interface ClaudeAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {}
diff --git a/apps/server/src/provider/Services/ClaudeProvider.ts b/apps/server/src/provider/Services/ClaudeProvider.ts
deleted file mode 100644
index 7f90c549c63..00000000000
--- a/apps/server/src/provider/Services/ClaudeProvider.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Context } from "effect";
-
-import type { ServerProviderShape } from "./ServerProvider";
-
-export interface ClaudeProviderShape extends ServerProviderShape {}
-
-export class ClaudeProvider extends Context.Service<ClaudeProvider, ClaudeProviderShape>()(
-  "t3/provider/Services/ClaudeProvider",
-) {}
diff --git a/apps/server/src/provider/Services/CodexAdapter.ts b/apps/server/src/provider/Services/CodexAdapter.ts
index e7a5508c9c7..33fe0fa12be 100644
--- a/apps/server/src/provider/Services/CodexAdapter.ts
+++ b/apps/server/src/provider/Services/CodexAdapter.ts
@@ -1,30 +1,19 @@
 /**
- * CodexAdapter - Codex implementation of the generic provider adapter contract.
+ * CodexAdapter — shape type for the Codex provider adapter.
  *
- * This service owns Codex app-server process / JSON-RPC semantics and emits
- * Codex provider events. It does not perform cross-provider routing, shared
- * event fan-out, or checkpoint orchestration.
- *
- * Uses Effect `Context.Service` for dependency injection and returns the
- * shared provider-adapter error channel with `provider: "codex"` context.
+ * Historically this module exposed a `Context.Service` tag so consumers
+ * could inject the adapter through the Effect layer graph. The driver
+ * model ({@link ../Drivers/CodexDriver}) bundles one adapter per
+ * instance as a captured closure instead, so the tag is gone — we only
+ * retain the shape interface as a naming anchor for the driver bundle.
  *
  * @module CodexAdapter
  */
-import { Context } from "effect";
-
 import type { ProviderAdapterError } from "../Errors.ts";
 import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
 
 /**
- * CodexAdapterShape - Service API for the Codex provider adapter.
- */
-export interface CodexAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {
-  readonly provider: "codex";
-}
-
-/**
- * CodexAdapter - Service tag for Codex provider adapter operations.
+ * CodexAdapterShape — per-instance Codex adapter contract. Carries
+ * a branded driver kind as the nominal discriminant.
  */
-export class CodexAdapter extends Context.Service<CodexAdapter, CodexAdapterShape>()(
-  "t3/provider/Services/CodexAdapter",
-) {}
+export interface CodexAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {}
diff --git a/apps/server/src/provider/Services/CodexProvider.ts b/apps/server/src/provider/Services/CodexProvider.ts
deleted file mode 100644
index 6820d4cb4f9..00000000000
--- a/apps/server/src/provider/Services/CodexProvider.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Context } from "effect";
-
-import type { ServerProviderShape } from "./ServerProvider";
-
-export interface CodexProviderShape extends ServerProviderShape {}
-
-export class CodexProvider extends Context.Service<CodexProvider, CodexProviderShape>()(
-  "t3/provider/Services/CodexProvider",
-) {}
diff --git a/apps/server/src/provider/Services/CursorAdapter.ts b/apps/server/src/provider/Services/CursorAdapter.ts
new file mode 100644
index 00000000000..83581f0a454
--- /dev/null
+++ b/apps/server/src/provider/Services/CursorAdapter.ts
@@ -0,0 +1,19 @@
+/**
+ * CursorAdapter — shape type for the Cursor provider adapter.
+ *
+ * Historically this module exposed a `Context.Service` tag so consumers
+ * could inject the adapter through the Effect layer graph. The driver
+ * model ({@link ../Drivers/CursorDriver}) bundles one adapter per
+ * instance as a captured closure instead, so the tag is gone — we only
+ * retain the shape interface as a naming anchor for the driver bundle.
+ *
+ * @module CursorAdapter
+ */
+import type { ProviderAdapterError } from "../Errors.ts";
+import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
+
+/**
+ * CursorAdapterShape — per-instance Cursor adapter contract. Carries
+ * a branded driver kind as the nominal discriminant.
+ */
+export interface CursorAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {}
diff --git a/apps/server/src/provider/Services/OpenCodeAdapter.ts b/apps/server/src/provider/Services/OpenCodeAdapter.ts
new file mode 100644
index 00000000000..e3ad97904d1
--- /dev/null
+++ b/apps/server/src/provider/Services/OpenCodeAdapter.ts
@@ -0,0 +1,19 @@
+/**
+ * OpenCodeAdapter — shape type for the OpenCode provider adapter.
+ *
+ * Historically this module exposed a `Context.Service` tag so consumers
+ * could inject the adapter through the Effect layer graph. The driver
+ * model ({@link ../Drivers/OpenCodeDriver}) bundles one adapter per
+ * instance as a captured closure instead, so the tag is gone — we only
+ * retain the shape interface as a naming anchor for the driver bundle.
+ *
+ * @module OpenCodeAdapter
+ */
+import type { ProviderAdapterError } from "../Errors.ts";
+import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
+
+/**
+ * OpenCodeAdapterShape — per-instance OpenCode adapter contract. Carries
+ * a branded driver kind as the nominal discriminant.
+ */
+export interface OpenCodeAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {}
diff --git a/apps/server/src/provider/Services/ProviderAdapter.ts b/apps/server/src/provider/Services/ProviderAdapter.ts
index 38a05f75748..01eeae7b7bd 100644
--- a/apps/server/src/provider/Services/ProviderAdapter.ts
+++ b/apps/server/src/provider/Services/ProviderAdapter.ts
@@ -10,7 +10,7 @@
 import type {
   ApprovalRequestId,
   ProviderApprovalDecision,
-  ProviderKind,
+  ProviderDriverKind,
   ProviderUserInputAnswers,
   ProviderRuntimeEvent,
   ProviderSendTurnInput,
@@ -20,10 +20,10 @@ import type {
   ProviderTurnStartResult,
   TurnId,
 } from "@t3tools/contracts";
-import type { Effect } from "effect";
-import type { Stream } from "effect";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
-export type ProviderSessionModelSwitchMode = "in-session" | "restart-session" | "unsupported";
+export type ProviderSessionModelSwitchMode = "in-session" | "unsupported";
 
 export interface ProviderAdapterCapabilities {
   /**
@@ -46,7 +46,7 @@ export interface ProviderAdapterShape<TError> {
   /**
    * Provider kind implemented by this adapter.
    */
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly capabilities: ProviderAdapterCapabilities;
 
   /**
diff --git a/apps/server/src/provider/Services/ProviderAdapterRegistry.ts b/apps/server/src/provider/Services/ProviderAdapterRegistry.ts
index b8e9d4b21c3..5b755c42eed 100644
--- a/apps/server/src/provider/Services/ProviderAdapterRegistry.ts
+++ b/apps/server/src/provider/Services/ProviderAdapterRegistry.ts
@@ -1,34 +1,94 @@
 /**
  * ProviderAdapterRegistry - Lookup boundary for provider adapter implementations.
  *
- * Maps a provider kind to the concrete adapter service (Codex, Claude, etc).
- * It does not own session lifecycle or routing rules; `ProviderService` uses
- * this registry together with `ProviderSessionDirectory`.
+ * Maps a `ProviderInstanceId` (the new per-instance routing key) or a
+ * `ProviderDriverKind` (legacy single-instance-per-driver key) to the concrete
+ * adapter service (Codex, Claude, etc). It does not own session lifecycle
+ * or routing rules; `ProviderService` uses this registry together with
+ * `ProviderSessionDirectory`.
+ *
+ * During the driver/instance migration this tag exposes both flavours:
+ *
+ *   - `getByInstance` / `listInstances` — new per-instance routing. Callers
+ *     that already know an `instanceId` (threads, sessions, events)
+ *     should prefer these.
+ *     (`defaultInstanceIdForDriver(kind) === kind`), matching the pre-Slice-D
+ *     behaviour. New code should not grow additional callers of the kind-keyed
+ *     methods; they exist so the settings UI, WS refresh RPC, and a handful
+ *     of legacy persisted rows can still be routed during the rollout.
  *
  * @module ProviderAdapterRegistry
  */
-import type { ProviderKind } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect } from "effect";
+import type { ProviderDriverKind, ProviderInstanceId } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as PubSub from "effect/PubSub";
+import type * as Scope from "effect/Scope";
+import type * as Stream from "effect/Stream";
 
 import type { ProviderAdapterError, ProviderUnsupportedError } from "../Errors.ts";
 import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
+import type { ProviderContinuationIdentity } from "../ProviderDriver.ts";
+
+export interface ProviderInstanceRoutingInfo {
+  readonly instanceId: ProviderInstanceId;
+  readonly driverKind: ProviderDriverKind;
+  readonly displayName: string | undefined;
+  readonly accentColor?: string | undefined;
+  readonly enabled: boolean;
+  readonly continuationIdentity: ProviderContinuationIdentity;
+}
 
 /**
- * ProviderAdapterRegistryShape - Service API for adapter lookup by provider kind.
+ * ProviderAdapterRegistryShape - Service API for adapter lookup.
  */
 export interface ProviderAdapterRegistryShape {
   /**
-   * Resolve the adapter for a provider kind.
+   * Resolve the adapter for a specific instance id. Returns
+   * `ProviderUnsupportedError` if no such instance is currently registered
+   * (which covers "never configured" *and* "configured but the driver is
+   * unavailable in this build" — both surface the same failure to callers
+   * that expect a working adapter).
    */
-  readonly getByProvider: (
-    provider: ProviderKind,
+  readonly getByInstance: (
+    instanceId: ProviderInstanceId,
   ) => Effect.Effect<ProviderAdapterShape<ProviderAdapterError>, ProviderUnsupportedError>;
 
+  readonly getInstanceInfo: (
+    instanceId: ProviderInstanceId,
+  ) => Effect.Effect<ProviderInstanceRoutingInfo, ProviderUnsupportedError>;
+
+  /**
+   * List all live instance ids. Excludes unavailable/shadow instances —
+   * callers of this method want something they can pass to `getByInstance`.
+   */
+  readonly listInstances: () => Effect.Effect<ReadonlyArray<ProviderInstanceId>>;
+
   /**
-   * List provider kinds currently registered.
+   * Legacy: list provider kinds whose default instance is currently
+   * registered.
+   *
+   * @deprecated Prefer `listInstances`. Retained for migration-era call
+   * sites that iterate providers to build UI/metrics.
    */
-  readonly listProviders: () => Effect.Effect<ReadonlyArray<ProviderKind>>;
+  readonly listProviders: () => Effect.Effect<ReadonlyArray<ProviderDriverKind>>;
+
+  /**
+   * Change notification stream mirroring `ProviderInstanceRegistry.streamChanges`.
+   * Emits one `void` tick whenever the set of live instances changes
+   * (instance added, removed, or rebuilt after a settings edit). Consumers
+   * that fan out `adapter.streamEvents` per instance — e.g. `ProviderService`'s
+   * runtime event bus — re-pull `listInstances` on each tick and fork new
+   * subscriptions for instances they haven't seen yet.
+   */
+  readonly streamChanges: Stream.Stream<void>;
+
+  /**
+   * Acquire a change subscription synchronously in the caller's current fiber.
+   * Consumers that must avoid missing a publish between initial reconciliation
+   * and watcher startup should use this, then fork `Stream.fromSubscription`.
+   */
+  readonly subscribeChanges: Effect.Effect<PubSub.Subscription<void>, never, Scope.Scope>;
 }
 
 /**
@@ -38,5 +98,3 @@ export class ProviderAdapterRegistry extends Context.Service<
   ProviderAdapterRegistry,
   ProviderAdapterRegistryShape
 >()("t3/provider/Services/ProviderAdapterRegistry") {}
-
-// Dummy comment for workflow testing.
diff --git a/apps/server/src/provider/Services/ProviderInstanceRegistry.ts b/apps/server/src/provider/Services/ProviderInstanceRegistry.ts
new file mode 100644
index 00000000000..cfea1142666
--- /dev/null
+++ b/apps/server/src/provider/Services/ProviderInstanceRegistry.ts
@@ -0,0 +1,87 @@
+/**
+ * ProviderInstanceRegistry — the single Effect service in the new model.
+ *
+ * Owns a `Map<ProviderInstanceId, ProviderInstance>` produced by running
+ * registered driver factories against `ServerSettings.providerInstances`.
+ * The registry watches settings; when an instance's config changes (or
+ * the entry disappears), the registry tears down the affected instance's
+ * scope and rebuilds — that's the entire hot-reload story.
+ *
+ * What rest-of-server reads from here:
+ *   - `getInstance(instanceId)` — for routing turn/session calls.
+ *   - `listInstances` — for snapshot aggregation in `ProviderRegistry`.
+ *   - `listUnavailable` — `ServerProvider` shadows for instances whose
+ *     driver is not registered in this build (rollback / fork tolerance).
+ *   - `streamChanges` — coalesced "registry mutated" pings so consumers
+ *     can re-pull lists or re-broadcast.
+ *
+ * @module provider/Services/ProviderInstanceRegistry
+ */
+import type { ProviderInstanceId, ServerProvider } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as PubSub from "effect/PubSub";
+import type * as Scope from "effect/Scope";
+import type * as Stream from "effect/Stream";
+
+import type { ProviderInstance } from "../ProviderDriver.ts";
+
+export interface ProviderInstanceRegistryShape {
+  /**
+   * Look up one instance by id. Returns `undefined` (not Option) when the
+   * id is unknown — callers branch on falsy and emit
+   * `ProviderInstanceNotFoundError`.
+   */
+  readonly getInstance: (
+    instanceId: ProviderInstanceId,
+  ) => Effect.Effect<ProviderInstance | undefined>;
+  /**
+   * Every available (driver-registered, successfully created) instance,
+   * in stable settings-author order.
+   */
+  readonly listInstances: Effect.Effect<ReadonlyArray<ProviderInstance>>;
+  /**
+   * Wire-shape shadow snapshots for instances whose driver is unknown to
+   * this build (or whose config failed to decode). Suitable for merging
+   * directly into `ProviderRegistry` output.
+   */
+  readonly listUnavailable: Effect.Effect<ReadonlyArray<ServerProvider>>;
+  /**
+   * Push notification stream emitted whenever the registry's contents
+   * change — instance added, removed, or rebuilt. The payload is `void`
+   * because consumers always want to re-pull `listInstances` /
+   * `listUnavailable` together.
+   *
+   * NOTE: because `Stream.fromPubSub` defers `PubSub.subscribe` until the
+   * stream starts running, forking a consumer via
+   * `Stream.runForEach(...).pipe(Effect.forkScoped)` races the next
+   * publish — the forked fiber may not have subscribed yet when the
+   * publish lands. Hot-reload consumers that must not miss a publish
+   * should use `subscribeChanges` below instead, which acquires the
+   * subscription synchronously in the caller's fiber before the consumer
+   * loop is forked.
+   */
+  readonly streamChanges: Stream.Stream<void>;
+  /**
+   * Acquire a subscription to the registry's change channel synchronously
+   * in the caller's fiber. Returns a `PubSub.Subscription<void>` whose
+   * lifetime is scoped to the provided `Scope` (the subscription is
+   * released when the scope closes). Consumers typically `yield*` this
+   * in the same fiber that forks their consumer loop, then drain with
+   * `PubSub.take(subscription)` inside `Effect.forever`. Because the
+   * subscription is registered with the PubSub before this `yield*`
+   * returns, no subsequent publish can land in a gap.
+   *
+   * This exists because the `ProviderInstanceRegistry` publishes on a
+   * PubSub and `Stream.fromPubSub` defers subscription until the stream
+   * starts executing — a consumer that `forkScoped`s the stream
+   * consumption can miss a publish that lands in the narrow window
+   * between "fiber scheduled" and "fiber starts running".
+   */
+  readonly subscribeChanges: Effect.Effect<PubSub.Subscription<void>, never, Scope.Scope>;
+}
+
+export class ProviderInstanceRegistry extends Context.Service<
+  ProviderInstanceRegistry,
+  ProviderInstanceRegistryShape
+>()("t3/provider/Services/ProviderInstanceRegistry") {}
diff --git a/apps/server/src/provider/Services/ProviderInstanceRegistryMutator.ts b/apps/server/src/provider/Services/ProviderInstanceRegistryMutator.ts
new file mode 100644
index 00000000000..98d45080237
--- /dev/null
+++ b/apps/server/src/provider/Services/ProviderInstanceRegistryMutator.ts
@@ -0,0 +1,52 @@
+/**
+ * ProviderInstanceRegistryMutator — internal handle used by the hydration
+ * layer to reconcile the live registry with a fresh
+ * `ProviderInstanceConfigMap`.
+ *
+ * Kept separate from the public `ProviderInstanceRegistry` service tag so
+ * downstream consumers (drivers, reactors, `ProviderService`) can only read
+ * from the registry. Only the hydration layer — which watches
+ * `ServerSettingsService.streamChanges` and applies diffs — imports this
+ * tag.
+ *
+ * The mutator exposes a single entry point, `reconcile(configMap)`, which:
+ *
+ *   1. Diffs the incoming map against the live one keyed by instance id.
+ *   2. Closes the per-instance `Scope` of every removed or replaced entry
+ *      (tearing down adapter processes, refresh fibres, temp files) BEFORE
+ *      creating the replacement — `reconcile` guarantees "at most one live
+ *      instance per id" at all times.
+ *   3. Opens a fresh child `Scope` for every added or replaced entry, runs
+ *      the driver's `create`, and stores the resulting `ProviderInstance`
+ *      plus its scope.
+ *   4. Publishes one `void` tick on the registry's `streamChanges` PubSub at
+ *      the end of the batch — consumers re-pull `listInstances` /
+ *      `listUnavailable`.
+ *
+ * `reconcile` is idempotent: calling it with an unchanged config map is a
+ * no-op (no scope churn, no pubsub emission).
+ *
+ * @module provider/Services/ProviderInstanceRegistryMutator
+ */
+import type { ProviderInstanceConfigMap } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+
+export interface ProviderInstanceRegistryMutatorShape {
+  /**
+   * Bring the live registry in line with the supplied config map. See
+   * module docs for the add / remove / replace semantics.
+   *
+   * The effect never fails: individual driver `create` failures are
+   * captured as "unavailable" shadow snapshots inside the registry, the
+   * same way boot-time failures are handled by
+   * `makeProviderInstanceRegistry`. This keeps settings-watcher loops from
+   * erroring out on a single bad entry.
+   */
+  readonly reconcile: (configMap: ProviderInstanceConfigMap) => Effect.Effect<void>;
+}
+
+export class ProviderInstanceRegistryMutator extends Context.Service<
+  ProviderInstanceRegistryMutator,
+  ProviderInstanceRegistryMutatorShape
+>()("t3/provider/Services/ProviderInstanceRegistryMutator") {}
diff --git a/apps/server/src/provider/Services/ProviderRegistry.ts b/apps/server/src/provider/Services/ProviderRegistry.ts
index 2e04fa253b0..b7426b30338 100644
--- a/apps/server/src/provider/Services/ProviderRegistry.ts
+++ b/apps/server/src/provider/Services/ProviderRegistry.ts
@@ -6,23 +6,72 @@
  *
  * @module ProviderRegistry
  */
-import type { ProviderKind, ServerProvider } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect, Stream } from "effect";
+import type {
+  ProviderInstanceId,
+  ProviderDriverKind,
+  ServerProvider,
+  ServerProviderUpdateState,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
+import type { ProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
+
+export type ProviderMaintenanceActionKind = "update";
 
 export interface ProviderRegistryShape {
   /**
-   * Read the latest provider snapshots.
+   * Read the latest provider snapshots for every configured instance.
+   * Multiple snapshots may share the same `provider` kind (multiple
+   * instances of the same driver) and disambiguate via `instanceId`.
    */
   readonly getProviders: Effect.Effect<ReadonlyArray<ServerProvider>>;
 
   /**
-   * Refresh all providers, or a single provider when specified.
+   * Refresh all providers, or the default instance of the specified
+   * kind when supplied.
+   *
+   * Retained for back-compat with legacy call sites (WS refresh RPC,
+   * orchestration metrics). New code should prefer `refreshInstance`.
+   *
+   * @deprecated prefer `refreshInstance` for new call sites.
+   */
+  readonly refresh: (provider?: ProviderDriverKind) => Effect.Effect<ReadonlyArray<ServerProvider>>;
+
+  /**
+   * Refresh the specific configured instance. Returns the updated snapshot
+   * list. When the instance id is unknown the call resolves with the
+   * currently cached list (no error) — matching the legacy `refresh` shim
+   * behaviour so transport layers don't have to special-case unknowns.
+   */
+  readonly refreshInstance: (
+    instanceId: ProviderInstanceId,
+  ) => Effect.Effect<ReadonlyArray<ServerProvider>>;
+
+  /**
+   * Resolve the maintenance capabilities owned by one live provider instance.
+   * Falls back to manual-only capabilities when the instance is not live.
+   */
+  readonly getProviderMaintenanceCapabilitiesForInstance: (
+    instanceId: ProviderInstanceId,
+    provider: ProviderDriverKind,
+  ) => Effect.Effect<ProviderMaintenanceCapabilities>;
+
+  /**
+   * Apply volatile maintenance-action state to one configured instance.
+   * This state is never persisted to disk. Today only update actions are
+   * projected onto `ServerProvider.updateState`; install/auth actions can
+   * extend this action map without adding driver-scoped APIs.
    */
-  readonly refresh: (provider?: ProviderKind) => Effect.Effect<ReadonlyArray<ServerProvider>>;
+  readonly setProviderMaintenanceActionState: (input: {
+    readonly instanceId: ProviderInstanceId;
+    readonly action: ProviderMaintenanceActionKind;
+    readonly state: ServerProviderUpdateState | null;
+  }) => Effect.Effect<ReadonlyArray<ServerProvider>>;
 
   /**
-   * Stream of provider snapshot updates.
+   * Stream of provider snapshot updates — one emission per aggregated
+   * change. The array contains the full current state.
    */
   readonly streamChanges: Stream.Stream<ReadonlyArray<ServerProvider>>;
 }
diff --git a/apps/server/src/provider/Services/ProviderService.ts b/apps/server/src/provider/Services/ProviderService.ts
index 1e461fcd1c6..4d4cb4fa01a 100644
--- a/apps/server/src/provider/Services/ProviderService.ts
+++ b/apps/server/src/provider/Services/ProviderService.ts
@@ -13,7 +13,7 @@
  */
 import type {
   ProviderInterruptTurnInput,
-  ProviderKind,
+  ProviderInstanceId,
   ProviderRespondToRequestInput,
   ProviderRespondToUserInputInput,
   ProviderRuntimeEvent,
@@ -24,11 +24,13 @@ import type {
   ThreadId,
   ProviderTurnStartResult,
 } from "@t3tools/contracts";
-import { Context } from "effect";
-import type { Effect, Stream } from "effect";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
 
 import type { ProviderServiceError } from "../Errors.ts";
 import type { ProviderAdapterCapabilities } from "./ProviderAdapter.ts";
+import type { ProviderInstanceRoutingInfo } from "./ProviderAdapterRegistry.ts";
 
 /**
  * ProviderServiceShape - Service API for provider session and turn orchestration.
@@ -85,12 +87,16 @@ export interface ProviderServiceShape {
   readonly listSessions: () => Effect.Effect<ReadonlyArray<ProviderSession>>;
 
   /**
-   * Read static capabilities for a provider adapter.
+   * Read capabilities for the adapter bound to a configured provider instance.
    */
   readonly getCapabilities: (
-    provider: ProviderKind,
+    instanceId: ProviderInstanceId,
   ) => Effect.Effect<ProviderAdapterCapabilities, ProviderServiceError>;
 
+  readonly getInstanceInfo: (
+    instanceId: ProviderInstanceId,
+  ) => Effect.Effect<ProviderInstanceRoutingInfo, ProviderServiceError>;
+
   /**
    * Roll back provider conversation state by a number of turns.
    */
diff --git a/apps/server/src/provider/Services/ProviderSessionDirectory.ts b/apps/server/src/provider/Services/ProviderSessionDirectory.ts
index aa0483620b4..f2dd4323f7a 100644
--- a/apps/server/src/provider/Services/ProviderSessionDirectory.ts
+++ b/apps/server/src/provider/Services/ProviderSessionDirectory.ts
@@ -1,11 +1,13 @@
 import type {
-  ProviderKind,
+  ProviderInstanceId,
+  ProviderDriverKind,
   ProviderSessionRuntimeStatus,
   RuntimeMode,
   ThreadId,
 } from "@t3tools/contracts";
-import { Option, Context } from "effect";
-import type { Effect } from "effect";
+import * as Option from "effect/Option";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type {
   ProviderSessionDirectoryPersistenceError,
@@ -14,7 +16,13 @@ import type {
 
 export interface ProviderRuntimeBinding {
   readonly threadId: ThreadId;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
+  /**
+   * Routing key for the configured provider instance that owns this
+   * session. The persistence layer promotes legacy null rows before
+   * exposing bindings; runtime callers must not infer this from `provider`.
+   */
+  readonly providerInstanceId?: ProviderInstanceId;
   readonly adapterKey?: string;
   readonly status?: ProviderSessionRuntimeStatus;
   readonly resumeCursor?: unknown | null;
@@ -22,6 +30,10 @@ export interface ProviderRuntimeBinding {
   readonly runtimeMode?: RuntimeMode;
 }
 
+export interface ProviderRuntimeBindingWithMetadata extends ProviderRuntimeBinding {
+  readonly lastSeenAt: string;
+}
+
 export type ProviderSessionDirectoryReadError = ProviderSessionDirectoryPersistenceError;
 
 export type ProviderSessionDirectoryWriteError =
@@ -35,20 +47,21 @@ export interface ProviderSessionDirectoryShape {
 
   readonly getProvider: (
     threadId: ThreadId,
-  ) => Effect.Effect<ProviderKind, ProviderSessionDirectoryReadError>;
+  ) => Effect.Effect<ProviderDriverKind, ProviderSessionDirectoryReadError>;
 
   readonly getBinding: (
     threadId: ThreadId,
   ) => Effect.Effect<Option.Option<ProviderRuntimeBinding>, ProviderSessionDirectoryReadError>;
 
-  readonly remove: (
-    threadId: ThreadId,
-  ) => Effect.Effect<void, ProviderSessionDirectoryPersistenceError>;
-
   readonly listThreadIds: () => Effect.Effect<
     ReadonlyArray<ThreadId>,
     ProviderSessionDirectoryPersistenceError
   >;
+
+  readonly listBindings: () => Effect.Effect<
+    ReadonlyArray<ProviderRuntimeBindingWithMetadata>,
+    ProviderSessionDirectoryPersistenceError
+  >;
 }
 
 export class ProviderSessionDirectory extends Context.Service<
diff --git a/apps/server/src/provider/Services/ProviderSessionReaper.ts b/apps/server/src/provider/Services/ProviderSessionReaper.ts
new file mode 100644
index 00000000000..7c4627eca89
--- /dev/null
+++ b/apps/server/src/provider/Services/ProviderSessionReaper.ts
@@ -0,0 +1,15 @@
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+
+export interface ProviderSessionReaperShape {
+  /**
+   * Start the background provider session reaper within the provided scope.
+   */
+  readonly start: () => Effect.Effect<void, never, Scope.Scope>;
+}
+
+export class ProviderSessionReaper extends Context.Service<
+  ProviderSessionReaper,
+  ProviderSessionReaperShape
+>()("t3/provider/Services/ProviderSessionReaper") {}
diff --git a/apps/server/src/provider/Services/ServerProvider.ts b/apps/server/src/provider/Services/ServerProvider.ts
index 4df0bc8fc2f..12162512927 100644
--- a/apps/server/src/provider/Services/ServerProvider.ts
+++ b/apps/server/src/provider/Services/ServerProvider.ts
@@ -1,7 +1,10 @@
 import type { ServerProvider } from "@t3tools/contracts";
-import type { Effect, Stream } from "effect";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
+import type { ProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
 
 export interface ServerProviderShape {
+  readonly maintenanceCapabilities: ProviderMaintenanceCapabilities;
   readonly getSnapshot: Effect.Effect<ServerProvider>;
   readonly refresh: Effect.Effect<ServerProvider>;
   readonly streamChanges: Stream.Stream<ServerProvider>;
diff --git a/apps/server/src/provider/acp/AcpAdapterSupport.test.ts b/apps/server/src/provider/acp/AcpAdapterSupport.test.ts
new file mode 100644
index 00000000000..a7fcdc4c827
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpAdapterSupport.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import * as EffectAcpErrors from "effect-acp/errors";
+import { ProviderDriverKind } from "@t3tools/contracts";
+
+import { acpPermissionOutcome, mapAcpToAdapterError } from "./AcpAdapterSupport.ts";
+
+describe("AcpAdapterSupport", () => {
+  it("maps ACP approval decisions to permission outcomes", () => {
+    expect(acpPermissionOutcome("accept")).toBe("allow-once");
+    expect(acpPermissionOutcome("acceptForSession")).toBe("allow-always");
+    expect(acpPermissionOutcome("decline")).toBe("reject-once");
+  });
+
+  it("maps ACP request errors to provider adapter request errors", () => {
+    const error = mapAcpToAdapterError(
+      ProviderDriverKind.make("cursor"),
+      "thread-1" as never,
+      "session/prompt",
+      new EffectAcpErrors.AcpRequestError({
+        code: -32602,
+        errorMessage: "Invalid params",
+      }),
+    );
+
+    expect(error._tag).toBe("ProviderAdapterRequestError");
+    expect(error.message).toContain("Invalid params");
+  });
+});
diff --git a/apps/server/src/provider/acp/AcpAdapterSupport.ts b/apps/server/src/provider/acp/AcpAdapterSupport.ts
new file mode 100644
index 00000000000..cde110e6dd9
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpAdapterSupport.ts
@@ -0,0 +1,56 @@
+import {
+  type ProviderApprovalDecision,
+  type ProviderDriverKind,
+  type ThreadId,
+} from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+import * as EffectAcpErrors from "effect-acp/errors";
+
+import {
+  ProviderAdapterRequestError,
+  ProviderAdapterSessionClosedError,
+  type ProviderAdapterError,
+} from "../Errors.ts";
+const isAcpProcessExitedError = Schema.is(EffectAcpErrors.AcpProcessExitedError);
+const isAcpRequestError = Schema.is(EffectAcpErrors.AcpRequestError);
+
+export function mapAcpToAdapterError(
+  provider: ProviderDriverKind,
+  threadId: ThreadId,
+  method: string,
+  error: EffectAcpErrors.AcpError,
+): ProviderAdapterError {
+  if (isAcpProcessExitedError(error)) {
+    return new ProviderAdapterSessionClosedError({
+      provider,
+      threadId,
+      cause: error,
+    });
+  }
+  if (isAcpRequestError(error)) {
+    return new ProviderAdapterRequestError({
+      provider,
+      method,
+      detail: error.message,
+      cause: error,
+    });
+  }
+  return new ProviderAdapterRequestError({
+    provider,
+    method,
+    detail: error.message,
+    cause: error,
+  });
+}
+
+export function acpPermissionOutcome(decision: ProviderApprovalDecision): string {
+  switch (decision) {
+    case "acceptForSession":
+      return "allow-always";
+    case "accept":
+      return "allow-once";
+    case "decline":
+    default:
+      return "reject-once";
+  }
+}
diff --git a/apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts
new file mode 100644
index 00000000000..713d0668928
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts
@@ -0,0 +1,155 @@
+import { ProviderDriverKind, RuntimeRequestId, TurnId } from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+
+import {
+  makeAcpAssistantItemEvent,
+  makeAcpContentDeltaEvent,
+  makeAcpPlanUpdatedEvent,
+  makeAcpRequestOpenedEvent,
+  makeAcpRequestResolvedEvent,
+  makeAcpToolCallEvent,
+} from "./AcpCoreRuntimeEvents.ts";
+
+describe("AcpCoreRuntimeEvents", () => {
+  it("maps ACP permission requests to canonical runtime events", () => {
+    const stamp = { eventId: "event-1" as never, createdAt: "2026-03-27T00:00:00.000Z" };
+    const turnId = TurnId.make("turn-1");
+    const permissionRequest = {
+      kind: "execute" as const,
+      detail: "cat package.json",
+      toolCall: {
+        toolCallId: "tool-1",
+        kind: "execute",
+        status: "pending" as const,
+        command: "cat package.json",
+        detail: "cat package.json",
+        data: { toolCallId: "tool-1", kind: "execute" },
+      },
+    };
+
+    expect(
+      makeAcpRequestOpenedEvent({
+        stamp,
+        provider: ProviderDriverKind.make("cursor"),
+        threadId: "thread-1" as never,
+        turnId,
+        requestId: RuntimeRequestId.make("request-1"),
+        permissionRequest,
+        detail: "cat package.json",
+        args: { command: ["cat", "package.json"] },
+        source: "acp.jsonrpc",
+        method: "session/request_permission",
+        rawPayload: { sessionId: "session-1" },
+      }),
+    ).toMatchObject({
+      type: "request.opened",
+      payload: {
+        requestType: "exec_command_approval",
+        detail: "cat package.json",
+      },
+    });
+
+    expect(
+      makeAcpRequestResolvedEvent({
+        stamp,
+        provider: ProviderDriverKind.make("cursor"),
+        threadId: "thread-1" as never,
+        turnId,
+        requestId: RuntimeRequestId.make("request-1"),
+        permissionRequest,
+        decision: "accept",
+      }),
+    ).toMatchObject({
+      type: "request.resolved",
+      payload: {
+        requestType: "exec_command_approval",
+        decision: "accept",
+      },
+    });
+  });
+
+  it("maps ACP core plan, tool-call, and content updates", () => {
+    const stamp = { eventId: "event-1" as never, createdAt: "2026-03-27T00:00:00.000Z" };
+    const turnId = TurnId.make("turn-1");
+
+    expect(
+      makeAcpPlanUpdatedEvent({
+        stamp,
+        provider: ProviderDriverKind.make("cursor"),
+        threadId: "thread-1" as never,
+        turnId,
+        payload: {
+          plan: [{ step: "Inspect state", status: "inProgress" }],
+        },
+        source: "acp.cursor.extension",
+        method: "cursor/update_todos",
+        rawPayload: { todos: [] },
+      }),
+    ).toMatchObject({
+      type: "turn.plan.updated",
+      raw: {
+        method: "cursor/update_todos",
+      },
+    });
+
+    expect(
+      makeAcpToolCallEvent({
+        stamp,
+        provider: ProviderDriverKind.make("cursor"),
+        threadId: "thread-1" as never,
+        turnId,
+        toolCall: {
+          toolCallId: "tool-1",
+          kind: "execute",
+          status: "completed",
+          title: "Terminal",
+          detail: "bun run test",
+          data: { command: "bun run test" },
+        },
+        rawPayload: { sessionId: "session-1" },
+      }),
+    ).toMatchObject({
+      type: "item.completed",
+      payload: {
+        itemType: "command_execution",
+        status: "completed",
+      },
+    });
+
+    expect(
+      makeAcpContentDeltaEvent({
+        stamp,
+        provider: ProviderDriverKind.make("cursor"),
+        threadId: "thread-1" as never,
+        turnId,
+        itemId: "assistant:session-1:segment:0",
+        text: "hello",
+        rawPayload: { sessionId: "session-1" },
+      }),
+    ).toMatchObject({
+      type: "content.delta",
+      itemId: "assistant:session-1:segment:0",
+      payload: {
+        delta: "hello",
+      },
+    });
+
+    expect(
+      makeAcpAssistantItemEvent({
+        stamp,
+        provider: ProviderDriverKind.make("cursor"),
+        threadId: "thread-1" as never,
+        turnId,
+        itemId: "assistant:session-1:segment:0",
+        lifecycle: "item.started",
+      }),
+    ).toMatchObject({
+      type: "item.started",
+      itemId: "assistant:session-1:segment:0",
+      payload: {
+        itemType: "assistant_message",
+        status: "inProgress",
+      },
+    });
+  });
+});
diff --git a/apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts
new file mode 100644
index 00000000000..c93e61dc37b
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts
@@ -0,0 +1,242 @@
+import {
+  type RuntimeEventRawSource,
+  RuntimeItemId,
+  type CanonicalRequestType,
+  type EventId,
+  type ProviderApprovalDecision,
+  type ProviderDriverKind,
+  type ProviderRuntimeEvent,
+  type RuntimeRequestId,
+  type ThreadId,
+  type ToolLifecycleItemType,
+  type TurnId,
+} from "@t3tools/contracts";
+
+import type { AcpPermissionRequest, AcpPlanUpdate, AcpToolCallState } from "./AcpRuntimeModel.ts";
+
+type AcpAdapterRawSource = Extract<
+  RuntimeEventRawSource,
+  "acp.jsonrpc" | `acp.${string}.extension`
+>;
+
+interface AcpEventStamp {
+  readonly eventId: EventId;
+  readonly createdAt: string;
+}
+
+type AcpCanonicalRequestType = Extract<
+  CanonicalRequestType,
+  "exec_command_approval" | "file_read_approval" | "file_change_approval" | "unknown"
+>;
+
+function canonicalRequestTypeFromAcpKind(kind: string | "unknown"): AcpCanonicalRequestType {
+  switch (kind) {
+    case "execute":
+      return "exec_command_approval";
+    case "read":
+      return "file_read_approval";
+    case "edit":
+    case "delete":
+    case "move":
+      return "file_change_approval";
+    default:
+      return "unknown";
+  }
+}
+
+function canonicalItemTypeFromAcpToolKind(kind: string | undefined): ToolLifecycleItemType {
+  switch (kind) {
+    case "execute":
+      return "command_execution";
+    case "edit":
+    case "delete":
+    case "move":
+      return "file_change";
+    case "search":
+    case "fetch":
+      return "web_search";
+    default:
+      return "dynamic_tool_call";
+  }
+}
+
+function runtimeItemStatusFromAcpToolStatus(
+  status: AcpToolCallState["status"],
+): "inProgress" | "completed" | "failed" | undefined {
+  switch (status) {
+    case "pending":
+    case "inProgress":
+      return "inProgress";
+    case "completed":
+      return "completed";
+    case "failed":
+      return "failed";
+    default:
+      return undefined;
+  }
+}
+
+export function makeAcpRequestOpenedEvent(input: {
+  readonly stamp: AcpEventStamp;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+  readonly turnId: TurnId | undefined;
+  readonly requestId: RuntimeRequestId;
+  readonly permissionRequest: AcpPermissionRequest;
+  readonly detail: string;
+  readonly args: unknown;
+  readonly source: AcpAdapterRawSource;
+  readonly method: string;
+  readonly rawPayload: unknown;
+}): ProviderRuntimeEvent {
+  return {
+    type: "request.opened",
+    ...input.stamp,
+    provider: input.provider,
+    threadId: input.threadId,
+    turnId: input.turnId,
+    requestId: input.requestId,
+    payload: {
+      requestType: canonicalRequestTypeFromAcpKind(input.permissionRequest.kind),
+      detail: input.detail,
+      args: input.args,
+    },
+    raw: {
+      source: input.source,
+      method: input.method,
+      payload: input.rawPayload,
+    },
+  };
+}
+
+export function makeAcpRequestResolvedEvent(input: {
+  readonly stamp: AcpEventStamp;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+  readonly turnId: TurnId | undefined;
+  readonly requestId: RuntimeRequestId;
+  readonly permissionRequest: AcpPermissionRequest;
+  readonly decision: ProviderApprovalDecision;
+}): ProviderRuntimeEvent {
+  return {
+    type: "request.resolved",
+    ...input.stamp,
+    provider: input.provider,
+    threadId: input.threadId,
+    turnId: input.turnId,
+    requestId: input.requestId,
+    payload: {
+      requestType: canonicalRequestTypeFromAcpKind(input.permissionRequest.kind),
+      decision: input.decision,
+    },
+  };
+}
+
+export function makeAcpPlanUpdatedEvent(input: {
+  readonly stamp: AcpEventStamp;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+  readonly turnId: TurnId | undefined;
+  readonly payload: AcpPlanUpdate;
+  readonly source: AcpAdapterRawSource;
+  readonly method: string;
+  readonly rawPayload: unknown;
+}): ProviderRuntimeEvent {
+  return {
+    type: "turn.plan.updated",
+    ...input.stamp,
+    provider: input.provider,
+    threadId: input.threadId,
+    turnId: input.turnId,
+    payload: input.payload,
+    raw: {
+      source: input.source,
+      method: input.method,
+      payload: input.rawPayload,
+    },
+  };
+}
+
+export function makeAcpToolCallEvent(input: {
+  readonly stamp: AcpEventStamp;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+  readonly turnId: TurnId | undefined;
+  readonly toolCall: AcpToolCallState;
+  readonly rawPayload: unknown;
+}): ProviderRuntimeEvent {
+  const runtimeStatus = runtimeItemStatusFromAcpToolStatus(input.toolCall.status);
+  return {
+    type:
+      input.toolCall.status === "completed" || input.toolCall.status === "failed"
+        ? "item.completed"
+        : "item.updated",
+    ...input.stamp,
+    provider: input.provider,
+    threadId: input.threadId,
+    turnId: input.turnId,
+    itemId: RuntimeItemId.make(input.toolCall.toolCallId),
+    payload: {
+      itemType: canonicalItemTypeFromAcpToolKind(input.toolCall.kind),
+      ...(runtimeStatus ? { status: runtimeStatus } : {}),
+      ...(input.toolCall.title ? { title: input.toolCall.title } : {}),
+      ...(input.toolCall.detail ? { detail: input.toolCall.detail } : {}),
+      ...(Object.keys(input.toolCall.data).length > 0 ? { data: input.toolCall.data } : {}),
+    },
+    raw: {
+      source: "acp.jsonrpc",
+      method: "session/update",
+      payload: input.rawPayload,
+    },
+  };
+}
+
+export function makeAcpAssistantItemEvent(input: {
+  readonly stamp: AcpEventStamp;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+  readonly turnId: TurnId | undefined;
+  readonly itemId: string;
+  readonly lifecycle: "item.started" | "item.completed";
+}): ProviderRuntimeEvent {
+  return {
+    type: input.lifecycle,
+    ...input.stamp,
+    provider: input.provider,
+    threadId: input.threadId,
+    turnId: input.turnId,
+    itemId: RuntimeItemId.make(input.itemId),
+    payload: {
+      itemType: "assistant_message",
+      status: input.lifecycle === "item.completed" ? "completed" : "inProgress",
+    },
+  };
+}
+
+export function makeAcpContentDeltaEvent(input: {
+  readonly stamp: AcpEventStamp;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+  readonly turnId: TurnId | undefined;
+  readonly itemId?: string;
+  readonly text: string;
+  readonly rawPayload: unknown;
+}): ProviderRuntimeEvent {
+  return {
+    type: "content.delta",
+    ...input.stamp,
+    provider: input.provider,
+    threadId: input.threadId,
+    turnId: input.turnId,
+    ...(input.itemId ? { itemId: RuntimeItemId.make(input.itemId) } : {}),
+    payload: {
+      streamKind: "assistant_text",
+      delta: input.text,
+    },
+    raw: {
+      source: "acp.jsonrpc",
+      method: "session/update",
+      payload: input.rawPayload,
+    },
+  };
+}
diff --git a/apps/server/src/provider/acp/AcpJsonRpcConnection.test.ts b/apps/server/src/provider/acp/AcpJsonRpcConnection.test.ts
new file mode 100644
index 00000000000..1b8f7be5d7d
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpJsonRpcConnection.test.ts
@@ -0,0 +1,397 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as path from "node:path";
+import * as os from "node:os";
+import { fileURLToPath } from "node:url";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { describe, expect } from "vitest";
+
+import { AcpSessionRuntime, type AcpSessionRequestLogEvent } from "./AcpSessionRuntime.ts";
+import type * as EffectAcpProtocol from "effect-acp/protocol";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const mockAgentPath = path.join(__dirname, "../../../scripts/acp-mock-agent.ts");
+const bunExe = "bun";
+
+describe("AcpSessionRuntime", () => {
+  it.effect("merges custom initialize client capabilities into the ACP handshake", () => {
+    const requestEvents: Array<AcpSessionRequestLogEvent> = [];
+    return Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      yield* runtime.start();
+
+      const initializeStarted = requestEvents.find(
+        (event) => event.method === "initialize" && event.status === "started",
+      );
+      expect(initializeStarted?.payload).toMatchObject({
+        protocolVersion: 1,
+        clientCapabilities: {
+          fs: { readTextFile: false, writeTextFile: false },
+          terminal: false,
+          _meta: { parameterizedModelPicker: true },
+        },
+      });
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+          },
+          cwd: process.cwd(),
+          clientCapabilities: {
+            _meta: {
+              parameterizedModelPicker: true,
+            },
+          },
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+          authMethodId: "test",
+          requestLogger: (event) =>
+            Effect.sync(() => {
+              requestEvents.push(event);
+            }),
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    );
+  });
+
+  it.effect("starts a session, prompts, and emits normalized events against the mock agent", () =>
+    Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      const started = yield* runtime.start();
+
+      expect(started.initializeResult).toMatchObject({ protocolVersion: 1 });
+      expect(started.sessionId).toBe("mock-session-1");
+
+      const promptResult = yield* runtime.prompt({
+        prompt: [{ type: "text", text: "hi" }],
+      });
+      expect(promptResult).toMatchObject({ stopReason: "end_turn" });
+
+      const notes = Array.from(yield* Stream.runCollect(Stream.take(runtime.getEvents(), 4)));
+      expect(notes).toHaveLength(4);
+      expect(notes.map((note) => note._tag)).toEqual([
+        "PlanUpdated",
+        "AssistantItemStarted",
+        "ContentDelta",
+        "AssistantItemCompleted",
+      ]);
+      const planUpdate = notes.find((note) => note._tag === "PlanUpdated");
+      expect(planUpdate?._tag).toBe("PlanUpdated");
+      if (planUpdate?._tag === "PlanUpdated") {
+        expect(planUpdate.payload.plan).toHaveLength(2);
+      }
+      const assistantStart = notes[1];
+      const assistantDelta = notes[2];
+      if (
+        assistantStart?._tag === "AssistantItemStarted" &&
+        assistantDelta?._tag === "ContentDelta"
+      ) {
+        expect(assistantDelta.itemId).toBe(assistantStart.itemId);
+      }
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+          },
+          cwd: process.cwd(),
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+          authMethodId: "test",
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    ),
+  );
+
+  it.effect("segments assistant text around ACP tool calls", () =>
+    Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      yield* runtime.start();
+
+      const promptResult = yield* runtime.prompt({
+        prompt: [{ type: "text", text: "hi" }],
+      });
+      expect(promptResult).toMatchObject({ stopReason: "end_turn" });
+
+      const notes = Array.from(yield* Stream.runCollect(Stream.take(runtime.getEvents(), 7)));
+      expect(notes.map((note) => note._tag)).toEqual([
+        "AssistantItemStarted",
+        "ContentDelta",
+        "AssistantItemCompleted",
+        "ToolCallUpdated",
+        "ToolCallUpdated",
+        "AssistantItemStarted",
+        "ContentDelta",
+      ]);
+
+      const firstStarted = notes[0];
+      const firstDelta = notes[1];
+      const firstCompleted = notes[2];
+      const secondStarted = notes[5];
+      const secondDelta = notes[6];
+      expect(firstStarted?._tag).toBe("AssistantItemStarted");
+      expect(firstCompleted?._tag).toBe("AssistantItemCompleted");
+      expect(secondStarted?._tag).toBe("AssistantItemStarted");
+      if (
+        firstStarted?._tag === "AssistantItemStarted" &&
+        firstDelta?._tag === "ContentDelta" &&
+        firstCompleted?._tag === "AssistantItemCompleted" &&
+        secondStarted?._tag === "AssistantItemStarted" &&
+        secondDelta?._tag === "ContentDelta"
+      ) {
+        expect(firstDelta.itemId).toBe(firstStarted.itemId);
+        expect(firstCompleted.itemId).toBe(firstStarted.itemId);
+        expect(secondStarted.itemId).not.toBe(firstStarted.itemId);
+        expect(secondDelta.itemId).toBe(secondStarted.itemId);
+      }
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+            env: {
+              T3_ACP_EMIT_INTERLEAVED_ASSISTANT_TOOL_CALLS: "1",
+            },
+          },
+          cwd: process.cwd(),
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+          authMethodId: "test",
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    ),
+  );
+
+  it.effect("suppresses generic placeholder tool updates until completion", () =>
+    Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      yield* runtime.start();
+
+      const promptResult = yield* runtime.prompt({
+        prompt: [{ type: "text", text: "hi" }],
+      });
+      expect(promptResult).toMatchObject({ stopReason: "end_turn" });
+
+      const notes = Array.from(yield* Stream.runCollect(Stream.take(runtime.getEvents(), 1)));
+      expect(notes.map((note) => note._tag)).toEqual(["ToolCallUpdated"]);
+      const toolCall = notes[0];
+      expect(toolCall?._tag).toBe("ToolCallUpdated");
+      if (toolCall?._tag === "ToolCallUpdated") {
+        expect(toolCall.toolCall.status).toBe("completed");
+        expect(toolCall.toolCall.title).toBe("Read file");
+      }
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+            env: {
+              T3_ACP_EMIT_GENERIC_TOOL_PLACEHOLDERS: "1",
+            },
+          },
+          cwd: process.cwd(),
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+          authMethodId: "test",
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    ),
+  );
+
+  it.effect("logs ACP requests from the shared runtime", () => {
+    const requestEvents: Array<AcpSessionRequestLogEvent> = [];
+    return Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      yield* runtime.start();
+
+      yield* runtime.setModel("composer-2");
+      yield* runtime.prompt({
+        prompt: [{ type: "text", text: "hi" }],
+      });
+
+      expect(
+        requestEvents.some(
+          (event) => event.method === "session/set_config_option" && event.status === "started",
+        ),
+      ).toBe(true);
+      expect(
+        requestEvents.some(
+          (event) => event.method === "session/set_config_option" && event.status === "succeeded",
+        ),
+      ).toBe(true);
+      expect(
+        requestEvents.some(
+          (event) => event.method === "session/prompt" && event.status === "started",
+        ),
+      ).toBe(true);
+      expect(
+        requestEvents.some(
+          (event) => event.method === "session/prompt" && event.status === "succeeded",
+        ),
+      ).toBe(true);
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          authMethodId: "test",
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+          },
+          cwd: process.cwd(),
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+          requestLogger: (event) =>
+            Effect.sync(() => {
+              requestEvents.push(event);
+            }),
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    );
+  });
+
+  it.effect("skips no-op session config writes when the requested value is already active", () => {
+    const requestEvents: Array<AcpSessionRequestLogEvent> = [];
+    return Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      yield* runtime.start();
+
+      yield* runtime.setConfigOption("model", "default");
+      yield* runtime.setMode("ask");
+
+      expect(
+        requestEvents.some(
+          (event) => event.method === "session/set_config_option" && event.status === "started",
+        ),
+      ).toBe(false);
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          authMethodId: "test",
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+          },
+          cwd: process.cwd(),
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+          requestLogger: (event) =>
+            Effect.sync(() => {
+              requestEvents.push(event);
+            }),
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    );
+  });
+
+  it.effect("emits low-level ACP protocol logs for raw and decoded messages", () => {
+    const protocolEvents: Array<EffectAcpProtocol.AcpProtocolLogEvent> = [];
+    return Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      yield* runtime.start();
+
+      yield* runtime.prompt({
+        prompt: [{ type: "text", text: "hi" }],
+      });
+
+      expect(
+        protocolEvents.some((event) => event.direction === "outgoing" && event.stage === "raw"),
+      ).toBe(true);
+      expect(
+        protocolEvents.some((event) => event.direction === "outgoing" && event.stage === "decoded"),
+      ).toBe(true);
+      expect(
+        protocolEvents.some((event) => event.direction === "incoming" && event.stage === "raw"),
+      ).toBe(true);
+      expect(
+        protocolEvents.some((event) => event.direction === "incoming" && event.stage === "decoded"),
+      ).toBe(true);
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          authMethodId: "test",
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+          },
+          cwd: process.cwd(),
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+          protocolLogging: {
+            logIncoming: true,
+            logOutgoing: true,
+            logger: (event) =>
+              Effect.sync(() => {
+                protocolEvents.push(event);
+              }),
+          },
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    );
+  });
+
+  it.effect("rejects invalid config option values before sending session/set_config_option", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "acp-runtime-"));
+    const requestLogPath = path.join(tempDir, "requests.ndjson");
+    return Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      yield* runtime.start();
+
+      const error = yield* runtime.setModel("composer-2[fast=false]").pipe(Effect.flip);
+      expect(error._tag).toBe("AcpRequestError");
+      if (error._tag === "AcpRequestError") {
+        expect(error.code).toBe(-32602);
+        expect(error.message).toContain(
+          'Invalid value "composer-2[fast=false]" for session config option "model"',
+        );
+        expect(error.message).toContain("composer-2[fast=true]");
+      }
+
+      const recordedRequests = readFileSync(requestLogPath, "utf8")
+        .trim()
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line) as { method?: string; params?: { value?: unknown } });
+      expect(
+        recordedRequests.some(
+          (message) =>
+            message.method === "session/set_config_option" &&
+            message.params?.value === "composer-2[fast=false]",
+        ),
+      ).toBe(false);
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          authMethodId: "test",
+          spawn: {
+            command: bunExe,
+            args: [mockAgentPath],
+            env: {
+              T3_ACP_REQUEST_LOG_PATH: requestLogPath,
+            },
+          },
+          cwd: process.cwd(),
+          clientInfo: { name: "t3-test", version: "0.0.0" },
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+      Effect.ensuring(Effect.sync(() => rmSync(tempDir, { recursive: true, force: true }))),
+    );
+  });
+});
diff --git a/apps/server/src/provider/acp/AcpNativeLogging.ts b/apps/server/src/provider/acp/AcpNativeLogging.ts
new file mode 100644
index 00000000000..f00ffcb6655
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpNativeLogging.ts
@@ -0,0 +1,79 @@
+import type { ProviderDriverKind, ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Random from "effect/Random";
+import type * as EffectAcpProtocol from "effect-acp/protocol";
+
+import type { EventNdjsonLogger } from "../Layers/EventNdjsonLogger.ts";
+import type { AcpSessionRequestLogEvent, AcpSessionRuntimeOptions } from "./AcpSessionRuntime.ts";
+
+function writeNativeAcpLog(input: {
+  readonly nativeEventLogger: EventNdjsonLogger | undefined;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+  readonly kind: "request" | "protocol";
+  readonly payload: unknown;
+}): Effect.Effect<void, never> {
+  return Effect.gen(function* () {
+    if (!input.nativeEventLogger) return;
+    const observedAt = DateTime.formatIso(yield* DateTime.now);
+    yield* input.nativeEventLogger.write(
+      {
+        observedAt,
+        event: {
+          id: yield* Random.nextUUIDv4,
+          kind: input.kind,
+          provider: input.provider,
+          createdAt: observedAt,
+          threadId: input.threadId,
+          payload: input.payload,
+        },
+      },
+      input.threadId,
+    );
+  });
+}
+
+function formatRequestLogPayload(event: AcpSessionRequestLogEvent) {
+  return {
+    method: event.method,
+    status: event.status,
+    request: event.payload,
+    ...(event.result !== undefined ? { result: event.result } : {}),
+    ...(event.cause !== undefined ? { cause: Cause.pretty(event.cause) } : {}),
+  };
+}
+
+export function makeAcpNativeLoggers(input: {
+  readonly nativeEventLogger: EventNdjsonLogger | undefined;
+  readonly provider: ProviderDriverKind;
+  readonly threadId: ThreadId;
+}): Pick<AcpSessionRuntimeOptions, "requestLogger" | "protocolLogging"> {
+  return {
+    requestLogger: (event) =>
+      writeNativeAcpLog({
+        nativeEventLogger: input.nativeEventLogger,
+        provider: input.provider,
+        threadId: input.threadId,
+        kind: "request",
+        payload: formatRequestLogPayload(event),
+      }),
+    ...(input.nativeEventLogger
+      ? {
+          protocolLogging: {
+            logIncoming: true,
+            logOutgoing: true,
+            logger: (event: EffectAcpProtocol.AcpProtocolLogEvent) =>
+              writeNativeAcpLog({
+                nativeEventLogger: input.nativeEventLogger,
+                provider: input.provider,
+                threadId: input.threadId,
+                kind: "protocol",
+                payload: event,
+              }),
+          } satisfies NonNullable<AcpSessionRuntimeOptions["protocolLogging"]>,
+        }
+      : {}),
+  };
+}
diff --git a/apps/server/src/provider/acp/AcpRuntimeModel.test.ts b/apps/server/src/provider/acp/AcpRuntimeModel.test.ts
new file mode 100644
index 00000000000..ae12d3112aa
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpRuntimeModel.test.ts
@@ -0,0 +1,286 @@
+import { describe, expect, it } from "vitest";
+
+import type * as EffectAcpSchema from "effect-acp/schema";
+
+import {
+  extractModelConfigId,
+  mergeToolCallState,
+  parsePermissionRequest,
+  parseSessionModeState,
+  parseSessionUpdateEvent,
+} from "./AcpRuntimeModel.ts";
+
+describe("AcpRuntimeModel", () => {
+  it("parses session mode state from typed ACP session setup responses", () => {
+    const modeState = parseSessionModeState({
+      sessionId: "session-1",
+      modes: {
+        currentModeId: " code ",
+        availableModes: [
+          { id: " ask ", name: " Ask ", description: " Request approval " },
+          { id: " code ", name: " Code " },
+        ],
+      },
+      configOptions: [],
+    } satisfies EffectAcpSchema.NewSessionResponse);
+
+    expect(modeState).toEqual({
+      currentModeId: "code",
+      availableModes: [
+        { id: "ask", name: "Ask", description: "Request approval" },
+        { id: "code", name: "Code" },
+      ],
+    });
+  });
+
+  it("extracts the model config id from typed ACP config options", () => {
+    const modelConfigId = extractModelConfigId({
+      sessionId: "session-1",
+      configOptions: [
+        {
+          id: "approval",
+          name: "Approval Mode",
+          category: "permission",
+          type: "select",
+          currentValue: "ask",
+          options: [{ value: "ask", name: "Ask" }],
+        },
+        {
+          id: "model",
+          name: "Model",
+          category: "model",
+          type: "select",
+          currentValue: "default",
+          options: [{ value: "default", name: "Auto" }],
+        },
+      ],
+    } satisfies EffectAcpSchema.NewSessionResponse);
+
+    expect(modelConfigId).toBe("model");
+  });
+
+  it("projects typed ACP tool call updates into runtime events", () => {
+    const created = parseSessionUpdateEvent({
+      sessionId: "session-1",
+      update: {
+        sessionUpdate: "tool_call",
+        toolCallId: "tool-1",
+        title: "Terminal",
+        kind: "execute",
+        status: "pending",
+        rawInput: {
+          executable: "bun",
+          args: ["run", "typecheck"],
+        },
+        content: [
+          {
+            type: "content",
+            content: {
+              type: "text",
+              text: "Running checks",
+            },
+          },
+        ],
+      },
+    } satisfies EffectAcpSchema.SessionNotification);
+
+    expect(created.events).toEqual([
+      {
+        _tag: "ToolCallUpdated",
+        toolCall: {
+          toolCallId: "tool-1",
+          kind: "execute",
+          title: "Ran command",
+          status: "pending",
+          command: "bun run typecheck",
+          detail: "bun run typecheck",
+          data: {
+            toolCallId: "tool-1",
+            kind: "execute",
+            command: "bun run typecheck",
+            rawInput: {
+              executable: "bun",
+              args: ["run", "typecheck"],
+            },
+            content: [
+              {
+                type: "content",
+                content: {
+                  type: "text",
+                  text: "Running checks",
+                },
+              },
+            ],
+          },
+        },
+        rawPayload: {
+          sessionId: "session-1",
+          update: {
+            sessionUpdate: "tool_call",
+            toolCallId: "tool-1",
+            title: "Terminal",
+            kind: "execute",
+            status: "pending",
+            rawInput: {
+              executable: "bun",
+              args: ["run", "typecheck"],
+            },
+            content: [
+              {
+                type: "content",
+                content: {
+                  type: "text",
+                  text: "Running checks",
+                },
+              },
+            ],
+          },
+        },
+      },
+    ]);
+
+    const updated = parseSessionUpdateEvent({
+      sessionId: "session-1",
+      update: {
+        sessionUpdate: "tool_call_update",
+        toolCallId: "tool-1",
+        status: "completed",
+        rawOutput: { exitCode: 0 },
+      },
+    } satisfies EffectAcpSchema.SessionNotification);
+
+    expect(updated.events).toHaveLength(1);
+    expect(updated.events[0]?._tag).toBe("ToolCallUpdated");
+    const createdEvent = created.events[0];
+    const updatedEvent = updated.events[0];
+    if (createdEvent?._tag === "ToolCallUpdated" && updatedEvent?._tag === "ToolCallUpdated") {
+      expect(mergeToolCallState(createdEvent.toolCall, updatedEvent.toolCall)).toMatchObject({
+        toolCallId: "tool-1",
+        status: "completed",
+        title: "Ran command",
+        detail: "bun run typecheck",
+        command: "bun run typecheck",
+      });
+    }
+  });
+
+  it("trims padded current mode updates before emitting a mode change", () => {
+    const result = parseSessionUpdateEvent({
+      sessionId: "session-1",
+      update: {
+        sessionUpdate: "current_mode_update",
+        currentModeId: " code ",
+      },
+    } satisfies EffectAcpSchema.SessionNotification);
+
+    expect(result.modeId).toBe("code");
+    expect(result.events).toEqual([
+      {
+        _tag: "ModeChanged",
+        modeId: "code",
+      },
+    ]);
+  });
+
+  it("projects typed ACP plan and content updates", () => {
+    const planResult = parseSessionUpdateEvent({
+      sessionId: "session-1",
+      update: {
+        sessionUpdate: "plan",
+        entries: [
+          { content: " Inspect state ", priority: "high", status: "completed" },
+          { content: "", priority: "medium", status: "in_progress" },
+        ],
+      },
+    } satisfies EffectAcpSchema.SessionNotification);
+
+    expect(planResult.events).toEqual([
+      {
+        _tag: "PlanUpdated",
+        payload: {
+          plan: [
+            { step: "Inspect state", status: "completed" },
+            { step: "Step 2", status: "inProgress" },
+          ],
+        },
+        rawPayload: {
+          sessionId: "session-1",
+          update: {
+            sessionUpdate: "plan",
+            entries: [
+              { content: " Inspect state ", priority: "high", status: "completed" },
+              { content: "", priority: "medium", status: "in_progress" },
+            ],
+          },
+        },
+      },
+    ]);
+
+    const contentResult = parseSessionUpdateEvent({
+      sessionId: "session-1",
+      update: {
+        sessionUpdate: "agent_message_chunk",
+        content: {
+          type: "text",
+          text: "hello from acp",
+        },
+      },
+    } satisfies EffectAcpSchema.SessionNotification);
+
+    expect(contentResult.events).toEqual([
+      {
+        _tag: "ContentDelta",
+        text: "hello from acp",
+        rawPayload: {
+          sessionId: "session-1",
+          update: {
+            sessionUpdate: "agent_message_chunk",
+            content: {
+              type: "text",
+              text: "hello from acp",
+            },
+          },
+        },
+      },
+    ]);
+  });
+
+  it("keeps permission request parsing compatible with loose extension payloads", () => {
+    const request = parsePermissionRequest({
+      sessionId: "session-1",
+      options: [
+        {
+          optionId: "allow-once",
+          name: "Allow once",
+          kind: "allow_once",
+        },
+      ],
+      toolCall: {
+        toolCallId: "tool-1",
+        title: "`cat package.json`",
+        kind: "execute",
+        status: "pending",
+        content: [
+          {
+            type: "content",
+            content: {
+              type: "text",
+              text: "Not in allowlist",
+            },
+          },
+        ],
+      },
+    });
+
+    expect(request).toMatchObject({
+      kind: "execute",
+      detail: "cat package.json",
+      toolCall: {
+        toolCallId: "tool-1",
+        kind: "execute",
+        status: "pending",
+        command: "cat package.json",
+      },
+    });
+  });
+});
diff --git a/apps/server/src/provider/acp/AcpRuntimeModel.ts b/apps/server/src/provider/acp/AcpRuntimeModel.ts
new file mode 100644
index 00000000000..ffd214a5bf1
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpRuntimeModel.ts
@@ -0,0 +1,482 @@
+import type * as EffectAcpSchema from "effect-acp/schema";
+import { deriveToolActivityPresentation } from "@t3tools/shared/toolActivity";
+import type { ToolLifecycleItemType } from "@t3tools/contracts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export interface AcpSessionMode {
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string;
+}
+
+export interface AcpSessionModeState {
+  readonly currentModeId: string;
+  readonly availableModes: ReadonlyArray<AcpSessionMode>;
+}
+
+export interface AcpToolCallState {
+  readonly toolCallId: string;
+  readonly kind?: string;
+  readonly title?: string;
+  readonly status?: "pending" | "inProgress" | "completed" | "failed";
+  readonly command?: string;
+  readonly detail?: string;
+  readonly data: Record<string, unknown>;
+}
+
+export interface AcpPlanUpdate {
+  readonly explanation?: string | null;
+  readonly plan: ReadonlyArray<{
+    readonly step: string;
+    readonly status: "pending" | "inProgress" | "completed";
+  }>;
+}
+
+export interface AcpPermissionRequest {
+  readonly kind: string | "unknown";
+  readonly detail?: string;
+  readonly toolCall?: AcpToolCallState;
+}
+
+export type AcpParsedSessionEvent =
+  | {
+      readonly _tag: "ModeChanged";
+      readonly modeId: string;
+    }
+  | {
+      readonly _tag: "AssistantItemStarted";
+      readonly itemId: string;
+    }
+  | {
+      readonly _tag: "AssistantItemCompleted";
+      readonly itemId: string;
+    }
+  | {
+      readonly _tag: "PlanUpdated";
+      readonly payload: AcpPlanUpdate;
+      readonly rawPayload: unknown;
+    }
+  | {
+      readonly _tag: "ToolCallUpdated";
+      readonly toolCall: AcpToolCallState;
+      readonly rawPayload: unknown;
+    }
+  | {
+      readonly _tag: "ContentDelta";
+      readonly itemId?: string;
+      readonly text: string;
+      readonly rawPayload: unknown;
+    };
+
+type AcpSessionSetupResponse =
+  | EffectAcpSchema.LoadSessionResponse
+  | EffectAcpSchema.NewSessionResponse
+  | EffectAcpSchema.ResumeSessionResponse;
+
+type AcpToolCallUpdate = Extract<
+  EffectAcpSchema.SessionNotification["update"],
+  { readonly sessionUpdate: "tool_call" | "tool_call_update" }
+>;
+
+export function extractModelConfigId(sessionResponse: AcpSessionSetupResponse): string | undefined {
+  const configOptions = sessionResponse.configOptions;
+  if (!configOptions) return undefined;
+  for (const opt of configOptions) {
+    if (opt.category === "model" && opt.id.trim().length > 0) {
+      return opt.id.trim();
+    }
+  }
+  return undefined;
+}
+
+export function findSessionConfigOption(
+  configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption> | null | undefined,
+  configId: string,
+): EffectAcpSchema.SessionConfigOption | undefined {
+  if (!configOptions) {
+    return undefined;
+  }
+  const normalizedConfigId = configId.trim();
+  if (!normalizedConfigId) {
+    return undefined;
+  }
+  return configOptions.find((option) => option.id.trim() === normalizedConfigId);
+}
+
+export function collectSessionConfigOptionValues(
+  configOption: EffectAcpSchema.SessionConfigOption,
+): ReadonlyArray<string> {
+  if (configOption.type !== "select") {
+    return [];
+  }
+  return configOption.options.flatMap((entry) =>
+    "value" in entry ? [entry.value] : entry.options.map((option) => option.value),
+  );
+}
+
+export function parseSessionModeState(
+  sessionResponse: AcpSessionSetupResponse,
+): AcpSessionModeState | undefined {
+  const modes = sessionResponse.modes;
+  if (!modes) return undefined;
+  const currentModeId = modes.currentModeId.trim();
+  if (!currentModeId) {
+    return undefined;
+  }
+  const availableModes = modes.availableModes
+    .map((mode) => {
+      const id = mode.id.trim();
+      const name = mode.name.trim();
+      if (!id || !name) {
+        return undefined;
+      }
+      const description = mode.description?.trim() || undefined;
+      return description !== undefined
+        ? ({ id, name, description } satisfies AcpSessionMode)
+        : ({ id, name } satisfies AcpSessionMode);
+    })
+    .filter((mode): mode is AcpSessionMode => mode !== undefined);
+  if (availableModes.length === 0) {
+    return undefined;
+  }
+  return {
+    currentModeId,
+    availableModes,
+  };
+}
+
+function normalizePlanStepStatus(raw: unknown): "pending" | "inProgress" | "completed" {
+  switch (raw) {
+    case "completed":
+      return "completed";
+    case "in_progress":
+    case "inProgress":
+      return "inProgress";
+    default:
+      return "pending";
+  }
+}
+
+function normalizeToolCallStatus(
+  raw: unknown,
+  fallback?: "pending" | "inProgress" | "completed" | "failed",
+): "pending" | "inProgress" | "completed" | "failed" | undefined {
+  switch (raw) {
+    case "pending":
+      return "pending";
+    case "in_progress":
+    case "inProgress":
+      return "inProgress";
+    case "completed":
+      return "completed";
+    case "failed":
+      return "failed";
+    default:
+      return fallback;
+  }
+}
+
+function normalizeCommandValue(value: unknown): string | undefined {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const parts = value
+    .map((entry) => (typeof entry === "string" && entry.trim().length > 0 ? entry.trim() : null))
+    .filter((entry): entry is string => entry !== null);
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
+function extractCommandFromTitle(title: string | undefined): string | undefined {
+  if (!title) {
+    return undefined;
+  }
+  const match = /`([^`]+)`/.exec(title);
+  return match?.[1]?.trim() || undefined;
+}
+
+function extractToolCallCommand(rawInput: unknown, title: string | undefined): string | undefined {
+  if (isRecord(rawInput)) {
+    const directCommand = normalizeCommandValue(rawInput.command);
+    if (directCommand) {
+      return directCommand;
+    }
+    const executable = typeof rawInput.executable === "string" ? rawInput.executable.trim() : "";
+    const args = normalizeCommandValue(rawInput.args);
+    if (executable && args) {
+      return `${executable} ${args}`;
+    }
+    if (executable) {
+      return executable;
+    }
+  }
+  return extractCommandFromTitle(title);
+}
+
+function extractTextContentFromToolCallContent(
+  content: ReadonlyArray<EffectAcpSchema.ToolCallContent> | null | undefined,
+): string | undefined {
+  if (!content) return undefined;
+  const chunks = content
+    .map((entry) => {
+      if (entry.type !== "content") {
+        return undefined;
+      }
+      const nestedContent = entry.content;
+      if (nestedContent.type !== "text") {
+        return undefined;
+      }
+      return nestedContent.text.trim().length > 0 ? nestedContent.text.trim() : undefined;
+    })
+    .filter((entry): entry is string => entry !== undefined);
+  return chunks.length > 0 ? chunks.join("\n") : undefined;
+}
+
+function normalizeToolKind(kind: unknown): string | undefined {
+  return typeof kind === "string" && kind.trim().length > 0 ? kind.trim() : undefined;
+}
+
+function canonicalItemTypeFromAcpToolKind(kind: string | undefined): ToolLifecycleItemType {
+  switch (kind) {
+    case "execute":
+      return "command_execution";
+    case "edit":
+    case "delete":
+    case "move":
+      return "file_change";
+    case "search":
+    case "fetch":
+      return "web_search";
+    default:
+      return "dynamic_tool_call";
+  }
+}
+
+function makeToolCallState(
+  input: {
+    readonly toolCallId: string;
+    readonly title?: string | null | undefined;
+    readonly kind?: EffectAcpSchema.ToolKind | null | undefined;
+    readonly status?: EffectAcpSchema.ToolCallStatus | null | undefined;
+    readonly rawInput?: unknown;
+    readonly rawOutput?: unknown;
+    readonly content?: ReadonlyArray<EffectAcpSchema.ToolCallContent> | null | undefined;
+    readonly locations?: ReadonlyArray<EffectAcpSchema.ToolCallLocation> | null | undefined;
+  },
+  options?: {
+    readonly fallbackStatus?: "pending" | "inProgress" | "completed" | "failed";
+  },
+): AcpToolCallState | undefined {
+  const toolCallId = input.toolCallId.trim();
+  if (!toolCallId) {
+    return undefined;
+  }
+  const title = input.title?.trim() || undefined;
+  const command = extractToolCallCommand(input.rawInput, title);
+  const textContent = extractTextContentFromToolCallContent(input.content);
+  const normalizedTitle =
+    title && title.toLowerCase() !== "terminal" && title.toLowerCase() !== "tool call"
+      ? title
+      : undefined;
+  const data: Record<string, unknown> = { toolCallId };
+  const kind = normalizeToolKind(input.kind);
+  if (kind) {
+    data.kind = kind;
+  }
+  if (command) {
+    data.command = command;
+  }
+  if (input.rawInput !== undefined) {
+    data.rawInput = input.rawInput;
+  }
+  if (input.rawOutput !== undefined) {
+    data.rawOutput = input.rawOutput;
+  }
+  if (input.content !== undefined) {
+    data.content = input.content;
+  }
+  if (input.locations !== undefined) {
+    data.locations = input.locations;
+  }
+  const fallbackDetail = command ?? normalizedTitle ?? textContent;
+  const hasPresentationSeed =
+    title !== undefined ||
+    kind !== undefined ||
+    command !== undefined ||
+    normalizedTitle !== undefined ||
+    textContent !== undefined;
+  const presentation = hasPresentationSeed
+    ? deriveToolActivityPresentation({
+        itemType: canonicalItemTypeFromAcpToolKind(kind),
+        title,
+        detail: fallbackDetail,
+        data,
+        fallbackSummary: title ?? "Tool",
+      })
+    : undefined;
+  const status = normalizeToolCallStatus(input.status, options?.fallbackStatus);
+  return {
+    toolCallId,
+    ...(kind ? { kind } : {}),
+    ...(presentation?.summary ? { title: presentation.summary } : {}),
+    ...(status ? { status } : {}),
+    ...(command ? { command } : {}),
+    ...(presentation?.detail ? { detail: presentation.detail } : {}),
+    data,
+  };
+}
+
+function parseTypedToolCallState(
+  event: AcpToolCallUpdate,
+  options?: {
+    readonly fallbackStatus?: "pending" | "inProgress" | "completed" | "failed";
+  },
+): AcpToolCallState | undefined {
+  return makeToolCallState(
+    {
+      toolCallId: event.toolCallId,
+      title: event.title,
+      kind: event.kind,
+      status: event.status,
+      rawInput: event.rawInput,
+      rawOutput: event.rawOutput,
+      content: event.content,
+      locations: event.locations,
+    },
+    options,
+  );
+}
+
+export function mergeToolCallState(
+  previous: AcpToolCallState | undefined,
+  next: AcpToolCallState,
+): AcpToolCallState {
+  const nextKind = typeof next.data.kind === "string" ? next.data.kind : undefined;
+  const kind = nextKind ?? previous?.kind;
+  const title = next.title ?? previous?.title;
+  const status = next.status ?? previous?.status;
+  const command = next.command ?? previous?.command;
+  const detail = next.detail ?? previous?.detail;
+  return {
+    toolCallId: next.toolCallId,
+    ...(kind ? { kind } : {}),
+    ...(title ? { title } : {}),
+    ...(status ? { status } : {}),
+    ...(command ? { command } : {}),
+    ...(detail ? { detail } : {}),
+    data: {
+      ...previous?.data,
+      ...next.data,
+    },
+  };
+}
+
+export function parsePermissionRequest(
+  params: EffectAcpSchema.RequestPermissionRequest,
+): AcpPermissionRequest {
+  const toolCall = makeToolCallState(
+    {
+      toolCallId: params.toolCall.toolCallId,
+      title: params.toolCall.title,
+      kind: params.toolCall.kind,
+      status: params.toolCall.status,
+      rawInput: params.toolCall.rawInput,
+      rawOutput: params.toolCall.rawOutput,
+      content: params.toolCall.content,
+      locations: params.toolCall.locations,
+    },
+    { fallbackStatus: "pending" },
+  );
+  const kind = normalizeToolKind(params.toolCall.kind) ?? "unknown";
+  const detail =
+    toolCall?.command ??
+    toolCall?.title ??
+    toolCall?.detail ??
+    (typeof params.sessionId === "string" ? `Session ${params.sessionId}` : undefined);
+  return {
+    kind,
+    ...(detail ? { detail } : {}),
+    ...(toolCall ? { toolCall } : {}),
+  };
+}
+
+export function parseSessionUpdateEvent(params: EffectAcpSchema.SessionNotification): {
+  readonly modeId?: string;
+  readonly events: ReadonlyArray<AcpParsedSessionEvent>;
+} {
+  const upd = params.update;
+  const events: Array<AcpParsedSessionEvent> = [];
+  let modeId: string | undefined;
+
+  switch (upd.sessionUpdate) {
+    case "current_mode_update": {
+      modeId = upd.currentModeId.trim();
+      if (modeId) {
+        events.push({
+          _tag: "ModeChanged",
+          modeId,
+        });
+      }
+      break;
+    }
+    case "plan": {
+      const plan = upd.entries.map((entry, index) => ({
+        step: entry.content.trim().length > 0 ? entry.content.trim() : `Step ${index + 1}`,
+        status: normalizePlanStepStatus(entry.status),
+      }));
+      if (plan.length > 0) {
+        events.push({
+          _tag: "PlanUpdated",
+          payload: {
+            plan,
+          },
+          rawPayload: params,
+        });
+      }
+      break;
+    }
+    case "tool_call": {
+      const toolCall = parseTypedToolCallState(upd, {
+        fallbackStatus: "pending",
+      });
+      if (toolCall) {
+        events.push({
+          _tag: "ToolCallUpdated",
+          toolCall,
+          rawPayload: params,
+        });
+      }
+      break;
+    }
+    case "tool_call_update": {
+      const toolCall = parseTypedToolCallState(upd);
+      if (toolCall) {
+        events.push({
+          _tag: "ToolCallUpdated",
+          toolCall,
+          rawPayload: params,
+        });
+      }
+      break;
+    }
+    case "agent_message_chunk": {
+      if (upd.content.type === "text" && upd.content.text.length > 0) {
+        events.push({
+          _tag: "ContentDelta",
+          text: upd.content.text,
+          rawPayload: params,
+        });
+      }
+      break;
+    }
+    default:
+      break;
+  }
+
+  return { ...(modeId !== undefined ? { modeId } : {}), events };
+}
diff --git a/apps/server/src/provider/acp/AcpSessionRuntime.ts b/apps/server/src/provider/acp/AcpSessionRuntime.ts
new file mode 100644
index 00000000000..8652b2cfeaf
--- /dev/null
+++ b/apps/server/src/provider/acp/AcpSessionRuntime.ts
@@ -0,0 +1,735 @@
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Context from "effect/Context";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import * as EffectAcpClient from "effect-acp/client";
+import * as EffectAcpErrors from "effect-acp/errors";
+import type * as EffectAcpSchema from "effect-acp/schema";
+import type * as EffectAcpProtocol from "effect-acp/protocol";
+
+import {
+  collectSessionConfigOptionValues,
+  extractModelConfigId,
+  findSessionConfigOption,
+  mergeToolCallState,
+  parseSessionModeState,
+  parseSessionUpdateEvent,
+  type AcpParsedSessionEvent,
+  type AcpSessionModeState,
+  type AcpToolCallState,
+} from "./AcpRuntimeModel.ts";
+
+function formatConfigOptionValue(value: string | boolean): string {
+  return JSON.stringify(value);
+}
+
+export interface AcpSpawnInput {
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd?: string;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface AcpSessionRuntimeOptions {
+  readonly spawn: AcpSpawnInput;
+  readonly cwd: string;
+  readonly resumeSessionId?: string;
+  readonly clientCapabilities?: EffectAcpSchema.InitializeRequest["clientCapabilities"];
+  readonly clientInfo: {
+    readonly name: string;
+    readonly version: string;
+  };
+  readonly authMethodId: string;
+  readonly requestLogger?: (event: AcpSessionRequestLogEvent) => Effect.Effect<void, never>;
+  readonly protocolLogging?: {
+    readonly logIncoming?: boolean;
+    readonly logOutgoing?: boolean;
+    readonly logger?: (event: EffectAcpProtocol.AcpProtocolLogEvent) => Effect.Effect<void, never>;
+  };
+}
+
+export interface AcpSessionRequestLogEvent {
+  readonly method: string;
+  readonly payload: unknown;
+  readonly status: "started" | "succeeded" | "failed";
+  readonly result?: unknown;
+  readonly cause?: Cause.Cause<EffectAcpErrors.AcpError>;
+}
+
+export interface AcpSessionRuntimeStartResult {
+  readonly sessionId: string;
+  readonly initializeResult: EffectAcpSchema.InitializeResponse;
+  readonly sessionSetupResult:
+    | EffectAcpSchema.LoadSessionResponse
+    | EffectAcpSchema.NewSessionResponse
+    | EffectAcpSchema.ResumeSessionResponse;
+  readonly modelConfigId: string | undefined;
+}
+
+export interface AcpSessionRuntimeShape {
+  readonly handleRequestPermission: EffectAcpClient.AcpClientShape["handleRequestPermission"];
+  readonly handleElicitation: EffectAcpClient.AcpClientShape["handleElicitation"];
+  readonly handleReadTextFile: EffectAcpClient.AcpClientShape["handleReadTextFile"];
+  readonly handleWriteTextFile: EffectAcpClient.AcpClientShape["handleWriteTextFile"];
+  readonly handleCreateTerminal: EffectAcpClient.AcpClientShape["handleCreateTerminal"];
+  readonly handleTerminalOutput: EffectAcpClient.AcpClientShape["handleTerminalOutput"];
+  readonly handleTerminalWaitForExit: EffectAcpClient.AcpClientShape["handleTerminalWaitForExit"];
+  readonly handleTerminalKill: EffectAcpClient.AcpClientShape["handleTerminalKill"];
+  readonly handleTerminalRelease: EffectAcpClient.AcpClientShape["handleTerminalRelease"];
+  readonly handleSessionUpdate: EffectAcpClient.AcpClientShape["handleSessionUpdate"];
+  readonly handleElicitationComplete: EffectAcpClient.AcpClientShape["handleElicitationComplete"];
+  readonly handleUnknownExtRequest: EffectAcpClient.AcpClientShape["handleUnknownExtRequest"];
+  readonly handleUnknownExtNotification: EffectAcpClient.AcpClientShape["handleUnknownExtNotification"];
+  readonly handleExtRequest: EffectAcpClient.AcpClientShape["handleExtRequest"];
+  readonly handleExtNotification: EffectAcpClient.AcpClientShape["handleExtNotification"];
+  readonly start: () => Effect.Effect<AcpSessionRuntimeStartResult, EffectAcpErrors.AcpError>;
+  readonly getEvents: () => Stream.Stream<AcpParsedSessionEvent, never>;
+  readonly getModeState: Effect.Effect<AcpSessionModeState | undefined>;
+  readonly getConfigOptions: Effect.Effect<ReadonlyArray<EffectAcpSchema.SessionConfigOption>>;
+  readonly prompt: (
+    payload: Omit<EffectAcpSchema.PromptRequest, "sessionId">,
+  ) => Effect.Effect<EffectAcpSchema.PromptResponse, EffectAcpErrors.AcpError>;
+  readonly cancel: Effect.Effect<void, EffectAcpErrors.AcpError>;
+  readonly setMode: (
+    modeId: string,
+  ) => Effect.Effect<EffectAcpSchema.SetSessionModeResponse, EffectAcpErrors.AcpError>;
+  readonly setConfigOption: (
+    configId: string,
+    value: string | boolean,
+  ) => Effect.Effect<EffectAcpSchema.SetSessionConfigOptionResponse, EffectAcpErrors.AcpError>;
+  readonly setModel: (model: string) => Effect.Effect<void, EffectAcpErrors.AcpError>;
+  readonly request: (
+    method: string,
+    payload: unknown,
+  ) => Effect.Effect<unknown, EffectAcpErrors.AcpError>;
+  readonly notify: (
+    method: string,
+    payload: unknown,
+  ) => Effect.Effect<void, EffectAcpErrors.AcpError>;
+}
+
+interface AcpStartedState extends AcpSessionRuntimeStartResult {}
+
+type AcpStartState =
+  | { readonly _tag: "NotStarted" }
+  | {
+      readonly _tag: "Starting";
+      readonly deferred: Deferred.Deferred<AcpSessionRuntimeStartResult, EffectAcpErrors.AcpError>;
+    }
+  | { readonly _tag: "Started"; readonly result: AcpStartedState };
+
+interface AcpAssistantSegmentState {
+  readonly nextSegmentIndex: number;
+  readonly activeItemId?: string;
+}
+
+interface EnsureActiveAssistantSegmentResult {
+  readonly itemId: string;
+  readonly startedEvent?: Extract<AcpParsedSessionEvent, { readonly _tag: "AssistantItemStarted" }>;
+}
+
+export class AcpSessionRuntime extends Context.Service<AcpSessionRuntime, AcpSessionRuntimeShape>()(
+  "t3/provider/acp/AcpSessionRuntime",
+) {
+  static layer(
+    options: AcpSessionRuntimeOptions,
+  ): Layer.Layer<
+    AcpSessionRuntime,
+    EffectAcpErrors.AcpError,
+    ChildProcessSpawner.ChildProcessSpawner
+  > {
+    return Layer.effect(AcpSessionRuntime, makeAcpSessionRuntime(options));
+  }
+}
+
+const makeAcpSessionRuntime = (
+  options: AcpSessionRuntimeOptions,
+): Effect.Effect<
+  AcpSessionRuntimeShape,
+  EffectAcpErrors.AcpError,
+  ChildProcessSpawner.ChildProcessSpawner | Scope.Scope
+> =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const runtimeScope = yield* Scope.Scope;
+    const eventQueue = yield* Queue.unbounded<AcpParsedSessionEvent>();
+    const modeStateRef = yield* Ref.make<AcpSessionModeState | undefined>(undefined);
+    const toolCallsRef = yield* Ref.make(new Map<string, AcpToolCallState>());
+    const assistantSegmentRef = yield* Ref.make<AcpAssistantSegmentState>({ nextSegmentIndex: 0 });
+    const configOptionsRef = yield* Ref.make(sessionConfigOptionsFromSetup(undefined));
+    const startStateRef = yield* Ref.make<AcpStartState>({ _tag: "NotStarted" });
+
+    const logRequest = (event: AcpSessionRequestLogEvent) =>
+      options.requestLogger ? options.requestLogger(event) : Effect.void;
+
+    const runLoggedRequest = <A>(
+      method: string,
+      payload: unknown,
+      effect: Effect.Effect<A, EffectAcpErrors.AcpError>,
+    ): Effect.Effect<A, EffectAcpErrors.AcpError> =>
+      logRequest({ method, payload, status: "started" }).pipe(
+        Effect.flatMap(() =>
+          effect.pipe(
+            Effect.tap((result) =>
+              logRequest({
+                method,
+                payload,
+                status: "succeeded",
+                result,
+              }),
+            ),
+            Effect.onError((cause) =>
+              logRequest({
+                method,
+                payload,
+                status: "failed",
+                cause,
+              }),
+            ),
+          ),
+        ),
+      );
+
+    const child = yield* spawner
+      .spawn(
+        ChildProcess.make(options.spawn.command, [...options.spawn.args], {
+          ...(options.spawn.cwd ? { cwd: options.spawn.cwd } : {}),
+          ...(options.spawn.env ? { env: { ...process.env, ...options.spawn.env } } : {}),
+          shell: process.platform === "win32",
+        }),
+      )
+      .pipe(
+        Effect.provideService(Scope.Scope, runtimeScope),
+        Effect.mapError(
+          (cause) =>
+            new EffectAcpErrors.AcpSpawnError({
+              command: options.spawn.command,
+              cause,
+            }),
+        ),
+      );
+
+    const acpContext = yield* Layer.build(
+      EffectAcpClient.layerChildProcess(child, {
+        ...(options.protocolLogging?.logIncoming !== undefined
+          ? { logIncoming: options.protocolLogging.logIncoming }
+          : {}),
+        ...(options.protocolLogging?.logOutgoing !== undefined
+          ? { logOutgoing: options.protocolLogging.logOutgoing }
+          : {}),
+        ...(options.protocolLogging?.logger ? { logger: options.protocolLogging.logger } : {}),
+      }),
+    ).pipe(Effect.provideService(Scope.Scope, runtimeScope));
+
+    const acp = yield* Effect.service(EffectAcpClient.AcpClient).pipe(Effect.provide(acpContext));
+
+    yield* acp.handleSessionUpdate((notification) =>
+      handleSessionUpdate({
+        queue: eventQueue,
+        modeStateRef,
+        toolCallsRef,
+        assistantSegmentRef,
+        params: notification,
+      }),
+    );
+
+    const initializeClientCapabilities = {
+      fs: {
+        readTextFile: false,
+        writeTextFile: false,
+        ...options.clientCapabilities?.fs,
+      },
+      terminal: options.clientCapabilities?.terminal ?? false,
+      ...(options.clientCapabilities?.auth ? { auth: options.clientCapabilities.auth } : {}),
+      ...(options.clientCapabilities?.elicitation
+        ? { elicitation: options.clientCapabilities.elicitation }
+        : {}),
+      ...(options.clientCapabilities?._meta ? { _meta: options.clientCapabilities._meta } : {}),
+    } satisfies NonNullable<EffectAcpSchema.InitializeRequest["clientCapabilities"]>;
+
+    const getStartedState = Effect.gen(function* () {
+      const state = yield* Ref.get(startStateRef);
+      if (state._tag === "Started") {
+        return state.result;
+      }
+      return yield* new EffectAcpErrors.AcpTransportError({
+        detail: "ACP session runtime has not been started",
+        cause: "ACP session runtime has not been started",
+      });
+    });
+
+    const validateConfigOptionValue = (
+      configId: string,
+      value: string | boolean,
+    ): Effect.Effect<void, EffectAcpErrors.AcpError> =>
+      Effect.gen(function* () {
+        const configOption = findSessionConfigOption(yield* Ref.get(configOptionsRef), configId);
+        if (!configOption) {
+          return;
+        }
+        if (configOption.type === "boolean") {
+          if (typeof value === "boolean") {
+            return;
+          }
+          return yield* new EffectAcpErrors.AcpRequestError({
+            code: -32602,
+            errorMessage: `Invalid value ${formatConfigOptionValue(value)} for session config option "${configOption.id}": expected boolean`,
+            data: {
+              configId: configOption.id,
+              expectedType: "boolean",
+              receivedValue: value,
+            },
+          });
+        }
+        if (typeof value !== "string") {
+          return yield* new EffectAcpErrors.AcpRequestError({
+            code: -32602,
+            errorMessage: `Invalid value ${formatConfigOptionValue(value)} for session config option "${configOption.id}": expected string`,
+            data: {
+              configId: configOption.id,
+              expectedType: "string",
+              receivedValue: value,
+            },
+          });
+        }
+        const allowedValues = collectSessionConfigOptionValues(configOption);
+        if (allowedValues.includes(value)) {
+          return;
+        }
+        return yield* new EffectAcpErrors.AcpRequestError({
+          code: -32602,
+          errorMessage: `Invalid value ${formatConfigOptionValue(value)} for session config option "${configOption.id}": expected one of ${allowedValues.join(", ")}`,
+          data: {
+            configId: configOption.id,
+            allowedValues,
+            receivedValue: value,
+          },
+        });
+      });
+
+    const updateConfigOptions = (
+      response:
+        | EffectAcpSchema.SetSessionConfigOptionResponse
+        | EffectAcpSchema.LoadSessionResponse
+        | EffectAcpSchema.NewSessionResponse
+        | EffectAcpSchema.ResumeSessionResponse,
+    ): Effect.Effect<void> => Ref.set(configOptionsRef, sessionConfigOptionsFromSetup(response));
+
+    const updateCurrentModeId = (modeId: string): Effect.Effect<void> =>
+      Ref.update(modeStateRef, (current) =>
+        current ? { ...current, currentModeId: modeId } : current,
+      );
+
+    const setConfigOption = (
+      configId: string,
+      value: string | boolean,
+    ): Effect.Effect<EffectAcpSchema.SetSessionConfigOptionResponse, EffectAcpErrors.AcpError> =>
+      validateConfigOptionValue(configId, value).pipe(
+        Effect.flatMap(() => getStartedState),
+        Effect.flatMap((started) =>
+          Ref.get(configOptionsRef).pipe(
+            Effect.flatMap((configOptions) => {
+              const existing = findSessionConfigOption(configOptions, configId);
+              if (existing && configOptionCurrentValueMatches(existing, value)) {
+                return Effect.succeed({
+                  configOptions,
+                } satisfies EffectAcpSchema.SetSessionConfigOptionResponse);
+              }
+              const requestPayload =
+                typeof value === "boolean"
+                  ? ({
+                      sessionId: started.sessionId,
+                      configId,
+                      type: "boolean",
+                      value,
+                    } satisfies EffectAcpSchema.SetSessionConfigOptionRequest)
+                  : ({
+                      sessionId: started.sessionId,
+                      configId,
+                      value: String(value),
+                    } satisfies EffectAcpSchema.SetSessionConfigOptionRequest);
+              return runLoggedRequest(
+                "session/set_config_option",
+                requestPayload,
+                acp.agent.setSessionConfigOption(requestPayload),
+              ).pipe(Effect.tap((response) => updateConfigOptions(response)));
+            }),
+          ),
+        ),
+      );
+
+    const startOnce = Effect.gen(function* () {
+      const initializePayload = {
+        protocolVersion: 1,
+        clientCapabilities: initializeClientCapabilities,
+        clientInfo: options.clientInfo,
+      } satisfies EffectAcpSchema.InitializeRequest;
+
+      const initializeResult = yield* runLoggedRequest(
+        "initialize",
+        initializePayload,
+        acp.agent.initialize(initializePayload),
+      );
+
+      const authenticatePayload = {
+        methodId: options.authMethodId,
+      } satisfies EffectAcpSchema.AuthenticateRequest;
+
+      yield* runLoggedRequest(
+        "authenticate",
+        authenticatePayload,
+        acp.agent.authenticate(authenticatePayload),
+      );
+
+      let sessionId: string;
+      let sessionSetupResult:
+        | EffectAcpSchema.LoadSessionResponse
+        | EffectAcpSchema.NewSessionResponse
+        | EffectAcpSchema.ResumeSessionResponse;
+      if (options.resumeSessionId) {
+        const loadPayload = {
+          sessionId: options.resumeSessionId,
+          cwd: options.cwd,
+          mcpServers: [],
+        } satisfies EffectAcpSchema.LoadSessionRequest;
+        const resumed = yield* runLoggedRequest(
+          "session/load",
+          loadPayload,
+          acp.agent.loadSession(loadPayload),
+        ).pipe(Effect.exit);
+        if (Exit.isSuccess(resumed)) {
+          sessionId = options.resumeSessionId;
+          sessionSetupResult = resumed.value;
+        } else {
+          const createPayload = {
+            cwd: options.cwd,
+            mcpServers: [],
+          } satisfies EffectAcpSchema.NewSessionRequest;
+          const created = yield* runLoggedRequest(
+            "session/new",
+            createPayload,
+            acp.agent.createSession(createPayload),
+          );
+          sessionId = created.sessionId;
+          sessionSetupResult = created;
+        }
+      } else {
+        const createPayload = {
+          cwd: options.cwd,
+          mcpServers: [],
+        } satisfies EffectAcpSchema.NewSessionRequest;
+        const created = yield* runLoggedRequest(
+          "session/new",
+          createPayload,
+          acp.agent.createSession(createPayload),
+        );
+        sessionId = created.sessionId;
+        sessionSetupResult = created;
+      }
+
+      yield* Ref.set(modeStateRef, parseSessionModeState(sessionSetupResult));
+      yield* Ref.set(configOptionsRef, sessionConfigOptionsFromSetup(sessionSetupResult));
+
+      const nextState = {
+        sessionId,
+        initializeResult,
+        sessionSetupResult,
+        modelConfigId: extractModelConfigId(sessionSetupResult),
+      } satisfies AcpStartedState;
+      return nextState;
+    });
+
+    const start = Effect.gen(function* () {
+      const deferred = yield* Deferred.make<
+        AcpSessionRuntimeStartResult,
+        EffectAcpErrors.AcpError
+      >();
+      const effect = yield* Ref.modify(startStateRef, (state) => {
+        switch (state._tag) {
+          case "Started":
+            return [Effect.succeed(state.result), state] as const;
+          case "Starting":
+            return [Deferred.await(state.deferred), state] as const;
+          case "NotStarted":
+            return [
+              startOnce.pipe(
+                Effect.tap((result) =>
+                  Ref.set(startStateRef, { _tag: "Started", result }).pipe(
+                    Effect.andThen(Deferred.succeed(deferred, result)),
+                  ),
+                ),
+                Effect.onError((cause) =>
+                  Deferred.failCause(deferred, cause).pipe(
+                    Effect.andThen(Ref.set(startStateRef, { _tag: "NotStarted" })),
+                  ),
+                ),
+              ),
+              { _tag: "Starting", deferred } satisfies AcpStartState,
+            ] as const;
+        }
+      });
+      return yield* effect;
+    });
+
+    return {
+      handleRequestPermission: acp.handleRequestPermission,
+      handleElicitation: acp.handleElicitation,
+      handleReadTextFile: acp.handleReadTextFile,
+      handleWriteTextFile: acp.handleWriteTextFile,
+      handleCreateTerminal: acp.handleCreateTerminal,
+      handleTerminalOutput: acp.handleTerminalOutput,
+      handleTerminalWaitForExit: acp.handleTerminalWaitForExit,
+      handleTerminalKill: acp.handleTerminalKill,
+      handleTerminalRelease: acp.handleTerminalRelease,
+      handleSessionUpdate: acp.handleSessionUpdate,
+      handleElicitationComplete: acp.handleElicitationComplete,
+      handleUnknownExtRequest: acp.handleUnknownExtRequest,
+      handleUnknownExtNotification: acp.handleUnknownExtNotification,
+      handleExtRequest: acp.handleExtRequest,
+      handleExtNotification: acp.handleExtNotification,
+      start: () => start,
+      getEvents: () => Stream.fromQueue(eventQueue),
+      getModeState: Ref.get(modeStateRef),
+      getConfigOptions: Ref.get(configOptionsRef),
+      prompt: (payload) =>
+        getStartedState.pipe(
+          Effect.flatMap((started) => {
+            const requestPayload = {
+              sessionId: started.sessionId,
+              ...payload,
+            } satisfies EffectAcpSchema.PromptRequest;
+            return closeActiveAssistantSegment({
+              queue: eventQueue,
+              assistantSegmentRef,
+            }).pipe(
+              Effect.andThen(
+                runLoggedRequest(
+                  "session/prompt",
+                  requestPayload,
+                  acp.agent.prompt(requestPayload),
+                ),
+              ),
+              Effect.tap(() =>
+                closeActiveAssistantSegment({
+                  queue: eventQueue,
+                  assistantSegmentRef,
+                }),
+              ),
+            );
+          }),
+        ),
+      cancel: getStartedState.pipe(
+        Effect.flatMap((started) => acp.agent.cancel({ sessionId: started.sessionId })),
+      ),
+      setMode: (modeId) =>
+        Ref.get(modeStateRef).pipe(
+          Effect.flatMap((modeState) => {
+            if (modeState?.currentModeId === modeId) {
+              return Effect.succeed({} satisfies EffectAcpSchema.SetSessionModeResponse);
+            }
+            return setConfigOption("mode", modeId).pipe(
+              Effect.tap(() => updateCurrentModeId(modeId)),
+              Effect.as({} satisfies EffectAcpSchema.SetSessionModeResponse),
+            );
+          }),
+        ),
+      setConfigOption,
+      setModel: (model) =>
+        getStartedState.pipe(
+          Effect.flatMap((started) => setConfigOption(started.modelConfigId ?? "model", model)),
+          Effect.asVoid,
+        ),
+      request: (method, payload) =>
+        runLoggedRequest(method, payload, acp.raw.request(method, payload)),
+      notify: acp.raw.notify,
+    } satisfies AcpSessionRuntimeShape;
+  });
+
+function sessionConfigOptionsFromSetup(
+  response:
+    | {
+        readonly configOptions?: ReadonlyArray<EffectAcpSchema.SessionConfigOption> | null;
+      }
+    | undefined,
+): ReadonlyArray<EffectAcpSchema.SessionConfigOption> {
+  return response?.configOptions ?? [];
+}
+
+function configOptionCurrentValueMatches(
+  configOption: EffectAcpSchema.SessionConfigOption,
+  value: string | boolean,
+): boolean {
+  const currentValue = configOption.currentValue;
+  if (configOption.type === "boolean") {
+    return currentValue === value;
+  }
+  if (typeof currentValue !== "string") {
+    return false;
+  }
+  return currentValue.trim() === String(value).trim();
+}
+
+const handleSessionUpdate = ({
+  queue,
+  modeStateRef,
+  toolCallsRef,
+  assistantSegmentRef,
+  params,
+}: {
+  readonly queue: Queue.Queue<AcpParsedSessionEvent>;
+  readonly modeStateRef: Ref.Ref<AcpSessionModeState | undefined>;
+  readonly toolCallsRef: Ref.Ref<Map<string, AcpToolCallState>>;
+  readonly assistantSegmentRef: Ref.Ref<AcpAssistantSegmentState>;
+  readonly params: EffectAcpSchema.SessionNotification;
+}): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const parsed = parseSessionUpdateEvent(params);
+    if (parsed.modeId) {
+      yield* Ref.update(modeStateRef, (current) =>
+        current === undefined ? current : updateModeState(current, parsed.modeId!),
+      );
+    }
+    for (const event of parsed.events) {
+      if (event._tag === "ToolCallUpdated") {
+        yield* closeActiveAssistantSegment({
+          queue,
+          assistantSegmentRef,
+        });
+        const { previous, merged } = yield* Ref.modify(toolCallsRef, (current) => {
+          const previous = current.get(event.toolCall.toolCallId);
+          const nextToolCall = mergeToolCallState(previous, event.toolCall);
+          const next = new Map(current);
+          if (nextToolCall.status === "completed" || nextToolCall.status === "failed") {
+            next.delete(nextToolCall.toolCallId);
+          } else {
+            next.set(nextToolCall.toolCallId, nextToolCall);
+          }
+          return [{ previous, merged: nextToolCall }, next] as const;
+        });
+        if (!shouldEmitToolCallUpdate(previous, merged)) {
+          continue;
+        }
+        yield* Queue.offer(queue, {
+          _tag: "ToolCallUpdated",
+          toolCall: merged,
+          rawPayload: event.rawPayload,
+        });
+        continue;
+      }
+      if (event._tag === "ContentDelta") {
+        if (event.text.trim().length === 0) {
+          const assistantSegmentState = yield* Ref.get(assistantSegmentRef);
+          if (!assistantSegmentState.activeItemId) {
+            continue;
+          }
+        }
+        const itemId = yield* ensureActiveAssistantSegment({
+          queue,
+          assistantSegmentRef,
+          sessionId: params.sessionId,
+        });
+        yield* Queue.offer(queue, {
+          ...event,
+          itemId,
+        });
+        continue;
+      }
+      yield* Queue.offer(queue, event);
+    }
+  });
+
+function updateModeState(modeState: AcpSessionModeState, nextModeId: string): AcpSessionModeState {
+  const normalized = nextModeId.trim();
+  if (!normalized) {
+    return modeState;
+  }
+  return modeState.availableModes.some((mode) => mode.id === normalized)
+    ? {
+        ...modeState,
+        currentModeId: normalized,
+      }
+    : modeState;
+}
+
+function shouldEmitToolCallUpdate(
+  previous: AcpToolCallState | undefined,
+  next: AcpToolCallState,
+): boolean {
+  if (next.status === "completed" || next.status === "failed") {
+    return true;
+  }
+  if (!next.detail) {
+    return false;
+  }
+  return previous === undefined || previous.title !== next.title || previous.detail !== next.detail;
+}
+
+const assistantItemId = (sessionId: string, segmentIndex: number) =>
+  `assistant:${sessionId}:segment:${segmentIndex}`;
+
+const ensureActiveAssistantSegment = ({
+  queue,
+  assistantSegmentRef,
+  sessionId,
+}: {
+  readonly queue: Queue.Queue<AcpParsedSessionEvent>;
+  readonly assistantSegmentRef: Ref.Ref<AcpAssistantSegmentState>;
+  readonly sessionId: string;
+}) =>
+  Ref.modify<AcpAssistantSegmentState, EnsureActiveAssistantSegmentResult>(
+    assistantSegmentRef,
+    (current) => {
+      if (current.activeItemId) {
+        return [{ itemId: current.activeItemId }, current] as const;
+      }
+      const itemId = assistantItemId(sessionId, current.nextSegmentIndex);
+      return [
+        {
+          itemId,
+          startedEvent: {
+            _tag: "AssistantItemStarted",
+            itemId,
+          } satisfies Extract<AcpParsedSessionEvent, { readonly _tag: "AssistantItemStarted" }>,
+        },
+        {
+          nextSegmentIndex: current.nextSegmentIndex + 1,
+          activeItemId: itemId,
+        } satisfies AcpAssistantSegmentState,
+      ] as const;
+    },
+  ).pipe(
+    Effect.flatMap((result) =>
+      result.startedEvent
+        ? Queue.offer(queue, result.startedEvent).pipe(Effect.as(result.itemId))
+        : Effect.succeed(result.itemId),
+    ),
+  );
+
+const closeActiveAssistantSegment = ({
+  queue,
+  assistantSegmentRef,
+}: {
+  readonly queue: Queue.Queue<AcpParsedSessionEvent>;
+  readonly assistantSegmentRef: Ref.Ref<AcpAssistantSegmentState>;
+}) =>
+  Ref.modify(assistantSegmentRef, (current) => {
+    if (!current.activeItemId) {
+      return [undefined, current] as const;
+    }
+    return [
+      {
+        _tag: "AssistantItemCompleted",
+        itemId: current.activeItemId,
+      } satisfies AcpParsedSessionEvent,
+      {
+        nextSegmentIndex: current.nextSegmentIndex,
+      } satisfies AcpAssistantSegmentState,
+    ] as const;
+  }).pipe(Effect.flatMap((event) => (event ? Queue.offer(queue, event) : Effect.void)));
diff --git a/apps/server/src/provider/acp/CursorAcpCliProbe.test.ts b/apps/server/src/provider/acp/CursorAcpCliProbe.test.ts
new file mode 100644
index 00000000000..30fbb1842fc
--- /dev/null
+++ b/apps/server/src/provider/acp/CursorAcpCliProbe.test.ts
@@ -0,0 +1,153 @@
+/**
+ * Optional integration check against a real `agent acp` install.
+ * Enable with: T3_CURSOR_ACP_PROBE=1 bun run test --filter CursorAcpCliProbe
+ */
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import { describe, expect } from "vitest";
+import type * as EffectAcpSchema from "effect-acp/schema";
+
+import { AcpSessionRuntime } from "./AcpSessionRuntime.ts";
+
+describe.runIf(process.env.T3_CURSOR_ACP_PROBE === "1")("Cursor ACP CLI probe", () => {
+  it.effect("initialize and authenticate against real agent acp", () =>
+    Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      const started = yield* runtime.start();
+      expect(started.initializeResult).toBeDefined();
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          spawn: {
+            command: "agent",
+            args: ["acp"],
+            cwd: process.cwd(),
+          },
+          cwd: process.cwd(),
+          clientCapabilities: {
+            _meta: {
+              parameterizedModelPicker: true,
+            },
+          },
+          clientInfo: { name: "t3-probe", version: "0.0.0" },
+          authMethodId: "cursor_login",
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    ),
+  );
+
+  it.effect("session/new returns configOptions with a model selector", () =>
+    Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      const started = yield* runtime.start();
+      const result = started.sessionSetupResult;
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
+      yield* Console.log("session/new result:", JSON.stringify(result, null, 2));
+
+      expect(typeof started.sessionId).toBe("string");
+
+      const configOptions = result.configOptions;
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
+      yield* Console.log("session/new configOptions:", JSON.stringify(configOptions, null, 2));
+
+      if (Array.isArray(configOptions)) {
+        const modelConfig = configOptions.find((opt) => opt.category === "model");
+        const parameterizedOptions = configOptions.filter(
+          (opt) =>
+            opt.category === "thought_level" ||
+            opt.category === "model_option" ||
+            opt.category === "model_config",
+        );
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
+        yield* Console.log("Model config option:", JSON.stringify(modelConfig, null, 2));
+        yield* Console.log(
+          "Parameterized model config options:",
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
+          JSON.stringify(parameterizedOptions, null, 2),
+        );
+        expect(modelConfig).toBeDefined();
+        expect(typeof modelConfig?.id).toBe("string");
+      }
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          authMethodId: "cursor_login",
+          spawn: {
+            command: "agent",
+            args: ["acp"],
+            cwd: process.cwd(),
+          },
+          cwd: process.cwd(),
+          clientCapabilities: {
+            _meta: {
+              parameterizedModelPicker: true,
+            },
+          },
+          clientInfo: { name: "t3-probe", version: "0.0.0" },
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    ),
+  );
+
+  it.effect("session/set_config_option switches the model in-session", () =>
+    Effect.gen(function* () {
+      const runtime = yield* AcpSessionRuntime;
+      const started = yield* runtime.start();
+      const newResult = started.sessionSetupResult;
+
+      const configOptions = newResult.configOptions;
+      let modelConfigId = "model";
+      if (Array.isArray(configOptions)) {
+        const modelConfig = configOptions.find((opt) => opt.category === "model");
+        if (typeof modelConfig?.id === "string") {
+          modelConfigId = modelConfig.id;
+        }
+      }
+
+      const setResult: EffectAcpSchema.SetSessionConfigOptionResponse =
+        yield* runtime.setConfigOption(modelConfigId, "gpt-5.4");
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
+      yield* Console.log("session/set_config_option result:", JSON.stringify(setResult, null, 2));
+
+      if (Array.isArray(setResult.configOptions)) {
+        const modelConfig = setResult.configOptions.find((opt) => opt.category === "model");
+        const parameterizedOptions = setResult.configOptions.filter(
+          (opt) =>
+            opt.category === "thought_level" ||
+            opt.category === "model_option" ||
+            opt.category === "model_config",
+        );
+        if (modelConfig?.type === "select") {
+          expect(modelConfig.currentValue).toBe("gpt-5.4");
+        }
+        expect(parameterizedOptions.length).toBeGreaterThan(0);
+      }
+    }).pipe(
+      Effect.provide(
+        AcpSessionRuntime.layer({
+          authMethodId: "cursor_login",
+          spawn: {
+            command: "agent",
+            args: ["acp"],
+            cwd: process.cwd(),
+          },
+          cwd: process.cwd(),
+          clientCapabilities: {
+            _meta: {
+              parameterizedModelPicker: true,
+            },
+          },
+          clientInfo: { name: "t3-probe", version: "0.0.0" },
+        }),
+      ),
+      Effect.scoped,
+      Effect.provide(NodeServices.layer),
+    ),
+  );
+});
diff --git a/apps/server/src/provider/acp/CursorAcpExtension.test.ts b/apps/server/src/provider/acp/CursorAcpExtension.test.ts
new file mode 100644
index 00000000000..91d50c4a9b8
--- /dev/null
+++ b/apps/server/src/provider/acp/CursorAcpExtension.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  extractAskQuestions,
+  extractPlanMarkdown,
+  extractTodosAsPlan,
+} from "./CursorAcpExtension.ts";
+
+describe("CursorAcpExtension", () => {
+  it("extracts ask-question prompts from the real Cursor ACP payload shape", () => {
+    const questions = extractAskQuestions({
+      toolCallId: "ask-1",
+      title: "Need input",
+      questions: [
+        {
+          id: "language",
+          prompt: "Which language should I use?",
+          options: [
+            { id: "ts", label: "TypeScript" },
+            { id: "rs", label: "Rust" },
+          ],
+          allowMultiple: false,
+        },
+      ],
+    });
+
+    expect(questions).toEqual([
+      {
+        id: "language",
+        header: "Question",
+        question: "Which language should I use?",
+        multiSelect: false,
+        options: [
+          { label: "TypeScript", description: "TypeScript" },
+          { label: "Rust", description: "Rust" },
+        ],
+      },
+    ]);
+  });
+
+  it("defaults ask-question multi-select to false when Cursor omits allowMultiple", () => {
+    const questions = extractAskQuestions({
+      toolCallId: "ask-2",
+      questions: [
+        {
+          id: "mode",
+          prompt: "Which mode should I use?",
+          options: [
+            { id: "agent", label: "Agent" },
+            { id: "plan", label: "Plan" },
+          ],
+        },
+      ],
+    });
+
+    expect(questions).toEqual([
+      {
+        id: "mode",
+        header: "Question",
+        question: "Which mode should I use?",
+        multiSelect: false,
+        options: [
+          { label: "Agent", description: "Agent" },
+          { label: "Plan", description: "Plan" },
+        ],
+      },
+    ]);
+  });
+
+  it("extracts plan markdown from the real Cursor create-plan payload shape", () => {
+    const planMarkdown = extractPlanMarkdown({
+      toolCallId: "plan-1",
+      name: "Refactor parser",
+      overview: "Tighten ACP parsing",
+      plan: "# Plan\n\n1. Add schemas\n2. Remove casts",
+      todos: [
+        { id: "t1", content: "Add schemas", status: "in_progress" },
+        { id: "t2", content: "Remove casts", status: "pending" },
+      ],
+      isProject: false,
+    });
+
+    expect(planMarkdown).toBe("# Plan\n\n1. Add schemas\n2. Remove casts");
+  });
+
+  it("projects todo updates into a plan shape and drops invalid entries", () => {
+    expect(
+      extractTodosAsPlan({
+        toolCallId: "todos-1",
+        todos: [
+          { id: "1", content: "Inspect state", status: "completed" },
+          { id: "2", content: "  Apply fix  ", status: "in_progress" },
+          { id: "3", title: "Fallback title", status: "pending" },
+          { id: "4", content: "Unknown status", status: "weird_status" },
+          { id: "5", content: "   " },
+        ],
+        merge: true,
+      }),
+    ).toEqual({
+      plan: [
+        { step: "Inspect state", status: "completed" },
+        { step: "Apply fix", status: "inProgress" },
+        { step: "Fallback title", status: "pending" },
+        { step: "Unknown status", status: "pending" },
+      ],
+    });
+  });
+});
diff --git a/apps/server/src/provider/acp/CursorAcpExtension.ts b/apps/server/src/provider/acp/CursorAcpExtension.ts
new file mode 100644
index 00000000000..4ab36636fb9
--- /dev/null
+++ b/apps/server/src/provider/acp/CursorAcpExtension.ts
@@ -0,0 +1,99 @@
+/**
+ * Public Docs: https://cursor.com/docs/cli/acp#cursor-extension-methods
+ * Additional reference provided by the Cursor team: https://anysphere.enterprise.slack.com/files/U068SSJE141/F0APT1HSZRP/cursor-acp-extension-method-schemas.md
+ */
+import type { UserInputQuestion } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+
+const CursorAskQuestionOption = Schema.Struct({
+  id: Schema.String,
+  label: Schema.String,
+});
+
+const CursorAskQuestion = Schema.Struct({
+  id: Schema.String,
+  prompt: Schema.String,
+  options: Schema.Array(CursorAskQuestionOption),
+  allowMultiple: Schema.optional(Schema.Boolean),
+});
+
+export const CursorAskQuestionRequest = Schema.Struct({
+  toolCallId: Schema.String,
+  title: Schema.optional(Schema.String),
+  questions: Schema.Array(CursorAskQuestion),
+});
+
+const CursorTodoStatus = Schema.String;
+
+const CursorTodo = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  content: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  status: Schema.optional(CursorTodoStatus),
+});
+
+const CursorPlanPhase = Schema.Struct({
+  name: Schema.String,
+  todos: Schema.Array(CursorTodo),
+});
+
+export const CursorCreatePlanRequest = Schema.Struct({
+  toolCallId: Schema.String,
+  name: Schema.optional(Schema.String),
+  overview: Schema.optional(Schema.String),
+  plan: Schema.String,
+  todos: Schema.Array(CursorTodo),
+  isProject: Schema.optional(Schema.Boolean),
+  phases: Schema.optional(Schema.Array(CursorPlanPhase)),
+});
+
+export const CursorUpdateTodosRequest = Schema.Struct({
+  toolCallId: Schema.String,
+  todos: Schema.Array(CursorTodo),
+  merge: Schema.Boolean,
+});
+
+export function extractAskQuestions(
+  params: typeof CursorAskQuestionRequest.Type,
+): ReadonlyArray<UserInputQuestion> {
+  return params.questions.map((question) => ({
+    id: question.id,
+    header: "Question",
+    question: question.prompt,
+    multiSelect: question.allowMultiple === true,
+    options:
+      question.options.length > 0
+        ? question.options.map((option) => ({
+            label: option.label,
+            description: option.label,
+          }))
+        : [{ label: "OK", description: "Continue" }],
+  }));
+}
+
+export function extractPlanMarkdown(params: typeof CursorCreatePlanRequest.Type): string {
+  return params.plan || "# Plan\n\n(Cursor did not supply plan text.)";
+}
+
+export function extractTodosAsPlan(params: typeof CursorUpdateTodosRequest.Type): {
+  readonly explanation?: string;
+  readonly plan: ReadonlyArray<{
+    readonly step: string;
+    readonly status: "pending" | "inProgress" | "completed";
+  }>;
+} {
+  const plan = params.todos.flatMap((todo) => {
+    const step = todo.content?.trim() ?? todo.title?.trim() ?? "";
+    if (step === "") {
+      return [];
+    }
+    const status: "pending" | "inProgress" | "completed" =
+      todo.status === "completed"
+        ? "completed"
+        : todo.status === "in_progress" || todo.status === "inProgress"
+          ? "inProgress"
+          : "pending";
+    return [{ step, status }];
+  });
+  return { plan };
+}
diff --git a/apps/server/src/provider/acp/CursorAcpSupport.test.ts b/apps/server/src/provider/acp/CursorAcpSupport.test.ts
new file mode 100644
index 00000000000..89422d865ad
--- /dev/null
+++ b/apps/server/src/provider/acp/CursorAcpSupport.test.ts
@@ -0,0 +1,121 @@
+import * as Effect from "effect/Effect";
+import type * as EffectAcpSchema from "effect-acp/schema";
+import { describe, expect, it } from "vitest";
+
+import { applyCursorAcpModelSelection, buildCursorAcpSpawnInput } from "./CursorAcpSupport.ts";
+
+const parameterizedGpt54ConfigOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption> = [
+  {
+    id: "model",
+    name: "Model",
+    category: "model",
+    type: "select",
+    currentValue: "gpt-5.4-medium-fast",
+    options: [{ value: "gpt-5.4-medium-fast", name: "GPT-5.4" }],
+  },
+  {
+    id: "reasoning",
+    name: "Reasoning",
+    category: "thought_level",
+    type: "select",
+    currentValue: "medium",
+    options: [
+      { value: "low", name: "Low" },
+      { value: "medium", name: "Medium" },
+      { value: "high", name: "High" },
+      { value: "extra-high", name: "Extra High" },
+    ],
+  },
+  {
+    id: "context",
+    name: "Context",
+    category: "model_config",
+    type: "select",
+    currentValue: "272k",
+    options: [
+      { value: "272k", name: "272K" },
+      { value: "1m", name: "1M" },
+    ],
+  },
+  {
+    id: "fast",
+    name: "Fast",
+    category: "model_config",
+    type: "select",
+    currentValue: "false",
+    options: [
+      { value: "false", name: "Off" },
+      { value: "true", name: "Fast" },
+    ],
+  },
+];
+
+describe("buildCursorAcpSpawnInput", () => {
+  it("builds the default Cursor ACP command", () => {
+    expect(buildCursorAcpSpawnInput(undefined, "/tmp/project")).toEqual({
+      command: "agent",
+      args: ["acp"],
+      cwd: "/tmp/project",
+    });
+  });
+
+  it("includes the configured api endpoint when present", () => {
+    expect(
+      buildCursorAcpSpawnInput(
+        {
+          binaryPath: "/usr/local/bin/agent",
+          apiEndpoint: "http://localhost:3000",
+        },
+        "/tmp/project",
+      ),
+    ).toEqual({
+      command: "/usr/local/bin/agent",
+      args: ["-e", "http://localhost:3000", "acp"],
+      cwd: "/tmp/project",
+    });
+  });
+});
+
+describe("applyCursorAcpModelSelection", () => {
+  it("sets the base model before applying separate config options", async () => {
+    const calls: Array<
+      | { readonly type: "model"; readonly value: string }
+      | { readonly type: "config"; readonly configId: string; readonly value: string | boolean }
+    > = [];
+
+    const runtime = {
+      getConfigOptions: Effect.succeed(parameterizedGpt54ConfigOptions),
+      setModel: (value: string) =>
+        Effect.sync(() => {
+          calls.push({ type: "model", value });
+        }),
+      setConfigOption: (configId: string, value: string | boolean) =>
+        Effect.sync(() => {
+          calls.push({ type: "config", configId, value });
+        }),
+    };
+
+    await Effect.runPromise(
+      applyCursorAcpModelSelection({
+        runtime,
+        model: "gpt-5.4-medium-fast[reasoning=medium,context=272k]",
+        selections: [
+          { id: "reasoning", value: "xhigh" },
+          { id: "contextWindow", value: "1m" },
+          { id: "fastMode", value: true },
+        ],
+        mapError: ({ step, configId, cause }) =>
+          step === "set-config-option"
+            ? `failed to set config option ${configId}: ${cause.message}`
+            : `failed to set model: ${cause.message}`,
+      }),
+    );
+
+    expect(calls).toEqual([
+      { type: "model", value: "gpt-5.4-medium-fast" },
+      { type: "config", configId: "reasoning", value: "extra-high" },
+      { type: "config", configId: "context", value: "1m" },
+      { type: "config", configId: "fast", value: "true" },
+    ]);
+  });
+});
diff --git a/apps/server/src/provider/acp/CursorAcpSupport.ts b/apps/server/src/provider/acp/CursorAcpSupport.ts
new file mode 100644
index 00000000000..5893c33215d
--- /dev/null
+++ b/apps/server/src/provider/acp/CursorAcpSupport.ts
@@ -0,0 +1,113 @@
+import { type CursorSettings, type ProviderOptionSelection } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import type * as EffectAcpErrors from "effect-acp/errors";
+
+import {
+  CURSOR_PARAMETERIZED_MODEL_PICKER_CAPABILITIES,
+  resolveCursorAcpBaseModelId,
+  resolveCursorAcpConfigUpdates,
+} from "../Layers/CursorProvider.ts";
+import {
+  AcpSessionRuntime,
+  type AcpSessionRuntimeOptions,
+  type AcpSessionRuntimeShape,
+  type AcpSpawnInput,
+} from "./AcpSessionRuntime.ts";
+
+type CursorAcpRuntimeCursorSettings = Pick<CursorSettings, "apiEndpoint" | "binaryPath">;
+
+export interface CursorAcpRuntimeInput extends Omit<
+  AcpSessionRuntimeOptions,
+  "authMethodId" | "clientCapabilities" | "spawn"
+> {
+  readonly childProcessSpawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
+  readonly cursorSettings: CursorAcpRuntimeCursorSettings | null | undefined;
+  readonly environment?: NodeJS.ProcessEnv;
+}
+
+export interface CursorAcpModelSelectionErrorContext {
+  readonly cause: EffectAcpErrors.AcpError;
+  readonly step: "set-config-option" | "set-model";
+  readonly configId?: string;
+}
+
+export function buildCursorAcpSpawnInput(
+  cursorSettings: CursorAcpRuntimeCursorSettings | null | undefined,
+  cwd: string,
+  environment?: NodeJS.ProcessEnv,
+): AcpSpawnInput {
+  return {
+    command: cursorSettings?.binaryPath || "agent",
+    args: [
+      ...(cursorSettings?.apiEndpoint ? (["-e", cursorSettings.apiEndpoint] as const) : []),
+      "acp",
+    ],
+    cwd,
+    ...(environment ? { env: environment } : {}),
+  };
+}
+
+export const makeCursorAcpRuntime = (
+  input: CursorAcpRuntimeInput,
+): Effect.Effect<AcpSessionRuntimeShape, EffectAcpErrors.AcpError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const acpContext = yield* Layer.build(
+      AcpSessionRuntime.layer({
+        ...input,
+        spawn: buildCursorAcpSpawnInput(input.cursorSettings, input.cwd, input.environment),
+        authMethodId: "cursor_login",
+        clientCapabilities: CURSOR_PARAMETERIZED_MODEL_PICKER_CAPABILITIES,
+      }).pipe(
+        Layer.provide(
+          Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, input.childProcessSpawner),
+        ),
+      ),
+    );
+    return yield* Effect.service(AcpSessionRuntime).pipe(Effect.provide(acpContext));
+  });
+
+interface CursorAcpModelSelectionRuntime {
+  readonly getConfigOptions: AcpSessionRuntimeShape["getConfigOptions"];
+  readonly setConfigOption: (
+    configId: string,
+    value: string | boolean,
+  ) => Effect.Effect<unknown, EffectAcpErrors.AcpError>;
+  readonly setModel: (model: string) => Effect.Effect<unknown, EffectAcpErrors.AcpError>;
+}
+
+export function applyCursorAcpModelSelection<E>(input: {
+  readonly runtime: CursorAcpModelSelectionRuntime;
+  readonly model: string | null | undefined;
+  readonly selections: ReadonlyArray<ProviderOptionSelection> | null | undefined;
+  readonly mapError: (context: CursorAcpModelSelectionErrorContext) => E;
+}): Effect.Effect<void, E> {
+  return Effect.gen(function* () {
+    yield* input.runtime.setModel(resolveCursorAcpBaseModelId(input.model)).pipe(
+      Effect.mapError((cause) =>
+        input.mapError({
+          cause,
+          step: "set-model",
+        }),
+      ),
+    );
+
+    const configUpdates = resolveCursorAcpConfigUpdates(
+      yield* input.runtime.getConfigOptions,
+      input.selections,
+    );
+    for (const update of configUpdates) {
+      yield* input.runtime.setConfigOption(update.configId, update.value).pipe(
+        Effect.mapError((cause) =>
+          input.mapError({
+            cause,
+            step: "set-config-option",
+            configId: update.configId,
+          }),
+        ),
+      );
+    }
+  });
+}
diff --git a/apps/server/src/provider/builtInDrivers.ts b/apps/server/src/provider/builtInDrivers.ts
new file mode 100644
index 00000000000..5af56dc6b0e
--- /dev/null
+++ b/apps/server/src/provider/builtInDrivers.ts
@@ -0,0 +1,50 @@
+/**
+ * BUILT_IN_DRIVERS — the static set of `ProviderDriver`s this build ships
+ * with.
+ *
+ * Every driver that the server knows how to instantiate from settings is
+ * listed here. The `ProviderInstanceRegistry` iterates this array when
+ * resolving `providerInstances` entries; anything not in the array surfaces
+ * as an `"unavailable"` shadow snapshot at runtime (see
+ * `buildUnavailableProviderSnapshot`).
+ *
+ * Adding a new first-party driver means:
+ *   1. implement `ProviderDriver` in a sibling `Drivers/<Name>Driver.ts`,
+ *   2. add it to this array,
+ *   3. ensure the runtime layer satisfies its declared `R`.
+ *
+ * The aggregated `BuiltInDriversEnv` type is the union of every driver's
+ * env requirement — the registry layer's `R` is this type, and the runtime
+ * layer (ChildProcessSpawner, FileSystem, Path, ServerConfig,
+ * OpenCodeRuntime, …) must satisfy it.
+ *
+ * @module provider/builtInDrivers
+ */
+import { ClaudeDriver, type ClaudeDriverEnv } from "./Drivers/ClaudeDriver.ts";
+import { CodexDriver, type CodexDriverEnv } from "./Drivers/CodexDriver.ts";
+import { CursorDriver, type CursorDriverEnv } from "./Drivers/CursorDriver.ts";
+import { OpenCodeDriver, type OpenCodeDriverEnv } from "./Drivers/OpenCodeDriver.ts";
+import type { AnyProviderDriver } from "./ProviderDriver.ts";
+
+/**
+ * Union of infrastructure services required to construct any built-in
+ * driver. The registry layer declares `R = BuiltInDriversEnv`; the runtime
+ * layer must provide every service in this union.
+ */
+export type BuiltInDriversEnv =
+  | ClaudeDriverEnv
+  | CodexDriverEnv
+  | CursorDriverEnv
+  | OpenCodeDriverEnv;
+
+/**
+ * Ordered list of built-in drivers. Order matters only for tie-breaking in
+ * UI presentation — the registry itself is keyed by `driverKind`, so
+ * iteration order has no functional effect on instance lookup.
+ */
+export const BUILT_IN_DRIVERS: ReadonlyArray<AnyProviderDriver<BuiltInDriversEnv>> = [
+  CodexDriver,
+  ClaudeDriver,
+  CursorDriver,
+  OpenCodeDriver,
+];
diff --git a/apps/server/src/provider/builtInProviderCatalog.ts b/apps/server/src/provider/builtInProviderCatalog.ts
new file mode 100644
index 00000000000..559726c65ea
--- /dev/null
+++ b/apps/server/src/provider/builtInProviderCatalog.ts
@@ -0,0 +1,17 @@
+import type { ProviderDriverKind, ProviderInstanceId, ServerProvider } from "@t3tools/contracts";
+import type * as Stream from "effect/Stream";
+import type { ServerProviderShape } from "./Services/ServerProvider.ts";
+
+export type ProviderSnapshotSource = {
+  /**
+   * Routing key — uniquely identifies this instance in the aggregated
+   * snapshot list. Two different snapshot sources may share the same
+   * driver kind (multiple instances of the same driver).
+   */
+  readonly instanceId: ProviderInstanceId;
+  /** Driver implementation kind. */
+  readonly driverKind: ProviderDriverKind;
+  readonly getSnapshot: ServerProviderShape["getSnapshot"];
+  readonly refresh: ServerProviderShape["refresh"];
+  readonly streamChanges: Stream.Stream<ServerProvider>;
+};
diff --git a/apps/server/src/provider/codexAccount.ts b/apps/server/src/provider/codexAccount.ts
deleted file mode 100644
index 1db00250f6d..00000000000
--- a/apps/server/src/provider/codexAccount.ts
+++ /dev/null
@@ -1,123 +0,0 @@
-import type { ServerProviderModel } from "@t3tools/contracts";
-
-export type CodexPlanType =
-  | "free"
-  | "go"
-  | "plus"
-  | "pro"
-  | "team"
-  | "business"
-  | "enterprise"
-  | "edu"
-  | "unknown";
-
-export interface CodexAccountSnapshot {
-  readonly type: "apiKey" | "chatgpt" | "unknown";
-  readonly planType: CodexPlanType | null;
-  readonly sparkEnabled: boolean;
-}
-
-export const CODEX_DEFAULT_MODEL = "gpt-5.3-codex";
-export const CODEX_SPARK_MODEL = "gpt-5.3-codex-spark";
-const CODEX_SPARK_ENABLED_PLAN_TYPES = new Set<CodexPlanType>(["pro"]);
-
-function asObject(value: unknown): Record<string, unknown> | undefined {
-  if (!value || typeof value !== "object") {
-    return undefined;
-  }
-  return value as Record<string, unknown>;
-}
-
-function asString(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}
-
-export function readCodexAccountSnapshot(response: unknown): CodexAccountSnapshot {
-  const record = asObject(response);
-  const account = asObject(record?.account) ?? record;
-  const accountType = asString(account?.type);
-
-  if (accountType === "apiKey") {
-    return {
-      type: "apiKey",
-      planType: null,
-      sparkEnabled: false,
-    };
-  }
-
-  if (accountType === "chatgpt") {
-    const planType = (account?.planType as CodexPlanType | null) ?? "unknown";
-    return {
-      type: "chatgpt",
-      planType,
-      sparkEnabled: CODEX_SPARK_ENABLED_PLAN_TYPES.has(planType),
-    };
-  }
-
-  return {
-    type: "unknown",
-    planType: null,
-    sparkEnabled: false,
-  };
-}
-
-export function codexAuthSubType(account: CodexAccountSnapshot | undefined): string | undefined {
-  if (account?.type === "apiKey") {
-    return "apiKey";
-  }
-
-  if (account?.type !== "chatgpt") {
-    return undefined;
-  }
-
-  return account.planType && account.planType !== "unknown" ? account.planType : "chatgpt";
-}
-
-export function codexAuthSubLabel(account: CodexAccountSnapshot | undefined): string | undefined {
-  switch (codexAuthSubType(account)) {
-    case "apiKey":
-      return "OpenAI API Key";
-    case "chatgpt":
-      return "ChatGPT Subscription";
-    case "free":
-      return "ChatGPT Free Subscription";
-    case "go":
-      return "ChatGPT Go Subscription";
-    case "plus":
-      return "ChatGPT Plus Subscription";
-    case "pro":
-      return "ChatGPT Pro Subscription";
-    case "team":
-      return "ChatGPT Team Subscription";
-    case "business":
-      return "ChatGPT Business Subscription";
-    case "enterprise":
-      return "ChatGPT Enterprise Subscription";
-    case "edu":
-      return "ChatGPT Edu Subscription";
-    default:
-      return undefined;
-  }
-}
-
-export function adjustCodexModelsForAccount(
-  baseModels: ReadonlyArray<ServerProviderModel>,
-  account: CodexAccountSnapshot | undefined,
-): ReadonlyArray<ServerProviderModel> {
-  if (account?.sparkEnabled !== false) {
-    return baseModels;
-  }
-
-  return baseModels.filter((model) => model.isCustom || model.slug !== CODEX_SPARK_MODEL);
-}
-
-export function resolveCodexModelForAccount(
-  model: string | undefined,
-  account: CodexAccountSnapshot,
-): string | undefined {
-  if (model !== CODEX_SPARK_MODEL || account.sparkEnabled) {
-    return model;
-  }
-
-  return CODEX_DEFAULT_MODEL;
-}
diff --git a/apps/server/src/provider/codexAppServer.ts b/apps/server/src/provider/codexAppServer.ts
deleted file mode 100644
index 7b3c9eeb79f..00000000000
--- a/apps/server/src/provider/codexAppServer.ts
+++ /dev/null
@@ -1,241 +0,0 @@
-import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from "node:child_process";
-import readline from "node:readline";
-import type { ServerProviderSkill } from "@t3tools/contracts";
-import { readCodexAccountSnapshot, type CodexAccountSnapshot } from "./codexAccount";
-
-interface JsonRpcProbeResponse {
-  readonly id?: unknown;
-  readonly result?: unknown;
-  readonly error?: {
-    readonly message?: unknown;
-  };
-}
-
-export interface CodexDiscoverySnapshot {
-  readonly account: CodexAccountSnapshot;
-  readonly skills: ReadonlyArray<ServerProviderSkill>;
-}
-
-function readErrorMessage(response: JsonRpcProbeResponse): string | undefined {
-  return typeof response.error?.message === "string" ? response.error.message : undefined;
-}
-
-function readObject(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
-}
-
-function readArray(value: unknown): ReadonlyArray<unknown> | undefined {
-  return Array.isArray(value) ? value : undefined;
-}
-
-function readString(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}
-
-function nonEmptyTrimmed(value: unknown): string | undefined {
-  const candidate = readString(value)?.trim();
-  return candidate ? candidate : undefined;
-}
-
-function parseCodexSkillsResult(result: unknown, cwd: string): ReadonlyArray<ServerProviderSkill> {
-  const resultRecord = readObject(result);
-  const dataBuckets = readArray(resultRecord?.data) ?? [];
-  const matchingBucket = dataBuckets.find(
-    (value) => nonEmptyTrimmed(readObject(value)?.cwd) === cwd,
-  );
-  const rawSkills =
-    readArray(readObject(matchingBucket)?.skills) ?? readArray(resultRecord?.skills) ?? [];
-
-  return rawSkills.flatMap((value) => {
-    const skill = readObject(value);
-    const display = readObject(skill?.interface);
-    const name = nonEmptyTrimmed(skill?.name);
-    const path = nonEmptyTrimmed(skill?.path);
-    if (!name || !path) {
-      return [];
-    }
-
-    return [
-      {
-        name,
-        path,
-        enabled: skill?.enabled !== false,
-        ...(nonEmptyTrimmed(skill?.description)
-          ? { description: nonEmptyTrimmed(skill?.description) }
-          : {}),
-        ...(nonEmptyTrimmed(skill?.scope) ? { scope: nonEmptyTrimmed(skill?.scope) } : {}),
-        ...(nonEmptyTrimmed(display?.displayName)
-          ? { displayName: nonEmptyTrimmed(display?.displayName) }
-          : {}),
-        ...(nonEmptyTrimmed(skill?.shortDescription) || nonEmptyTrimmed(display?.shortDescription)
-          ? {
-              shortDescription:
-                nonEmptyTrimmed(skill?.shortDescription) ??
-                nonEmptyTrimmed(display?.shortDescription),
-            }
-          : {}),
-      } satisfies ServerProviderSkill,
-    ];
-  });
-}
-
-export function buildCodexInitializeParams() {
-  return {
-    clientInfo: {
-      name: "t3code_desktop",
-      title: "T3 Code Desktop",
-      version: "0.1.0",
-    },
-    capabilities: {
-      experimentalApi: true,
-    },
-  } as const;
-}
-
-export function killCodexChildProcess(child: ChildProcessWithoutNullStreams): void {
-  if (process.platform === "win32" && child.pid !== undefined) {
-    try {
-      spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
-      return;
-    } catch {
-      // Fall through to direct kill when taskkill is unavailable.
-    }
-  }
-
-  child.kill();
-}
-
-export async function probeCodexDiscovery(input: {
-  readonly binaryPath: string;
-  readonly homePath?: string;
-  readonly cwd: string;
-  readonly signal?: AbortSignal;
-}): Promise<CodexDiscoverySnapshot> {
-  return await new Promise((resolve, reject) => {
-    const child = spawn(input.binaryPath, ["app-server"], {
-      env: {
-        ...process.env,
-        ...(input.homePath ? { CODEX_HOME: input.homePath } : {}),
-      },
-      stdio: ["pipe", "pipe", "pipe"],
-      shell: process.platform === "win32",
-    });
-    const output = readline.createInterface({ input: child.stdout });
-
-    let completed = false;
-    let account: CodexAccountSnapshot | undefined;
-    let skills: ReadonlyArray<ServerProviderSkill> | undefined;
-
-    const cleanup = () => {
-      output.removeAllListeners();
-      output.close();
-      child.removeAllListeners();
-      if (!child.killed) {
-        killCodexChildProcess(child);
-      }
-    };
-
-    const finish = (callback: () => void) => {
-      if (completed) return;
-      completed = true;
-      cleanup();
-      callback();
-    };
-
-    const fail = (error: unknown) =>
-      finish(() =>
-        reject(
-          error instanceof Error
-            ? error
-            : new Error(`Codex discovery probe failed: ${String(error)}.`),
-        ),
-      );
-
-    const maybeResolve = () => {
-      if (account && skills !== undefined) {
-        const resolvedAccount = account;
-        const resolvedSkills = skills;
-        finish(() => resolve({ account: resolvedAccount, skills: resolvedSkills }));
-      }
-    };
-
-    if (input.signal?.aborted) {
-      fail(new Error("Codex discovery probe aborted."));
-      return;
-    }
-    input.signal?.addEventListener("abort", () =>
-      fail(new Error("Codex discovery probe aborted.")),
-    );
-
-    const writeMessage = (message: unknown) => {
-      if (!child.stdin.writable) {
-        fail(new Error("Cannot write to codex app-server stdin."));
-        return;
-      }
-
-      child.stdin.write(`${JSON.stringify(message)}\n`);
-    };
-
-    output.on("line", (line) => {
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(line);
-      } catch {
-        fail(new Error("Received invalid JSON from codex app-server during discovery probe."));
-        return;
-      }
-
-      if (!parsed || typeof parsed !== "object") {
-        return;
-      }
-
-      const response = parsed as JsonRpcProbeResponse;
-      if (response.id === 1) {
-        const errorMessage = readErrorMessage(response);
-        if (errorMessage) {
-          fail(new Error(`initialize failed: ${errorMessage}`));
-          return;
-        }
-
-        writeMessage({ method: "initialized" });
-        writeMessage({ id: 2, method: "skills/list", params: { cwds: [input.cwd] } });
-        writeMessage({ id: 3, method: "account/read", params: {} });
-        return;
-      }
-
-      if (response.id === 2) {
-        const errorMessage = readErrorMessage(response);
-        skills = errorMessage ? [] : parseCodexSkillsResult(response.result, input.cwd);
-        maybeResolve();
-        return;
-      }
-
-      if (response.id === 3) {
-        const errorMessage = readErrorMessage(response);
-        if (errorMessage) {
-          fail(new Error(`account/read failed: ${errorMessage}`));
-          return;
-        }
-
-        account = readCodexAccountSnapshot(response.result);
-        maybeResolve();
-      }
-    });
-
-    child.once("error", fail);
-    child.once("exit", (code, signal) => {
-      if (completed) return;
-      fail(
-        new Error(
-          `codex app-server exited before probe completed (code=${code ?? "null"}, signal=${signal ?? "null"}).`,
-        ),
-      );
-    });
-
-    writeMessage({
-      id: 1,
-      method: "initialize",
-      params: buildCodexInitializeParams(),
-    });
-  });
-}
diff --git a/apps/server/src/provider/codexCliVersion.ts b/apps/server/src/provider/codexCliVersion.ts
deleted file mode 100644
index 544020016c6..00000000000
--- a/apps/server/src/provider/codexCliVersion.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-const CODEX_VERSION_PATTERN = /\bv?(\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?)\b/;
-
-export const MINIMUM_CODEX_CLI_VERSION = "0.37.0";
-
-interface ParsedSemver {
-  readonly major: number;
-  readonly minor: number;
-  readonly patch: number;
-  readonly prerelease: ReadonlyArray<string>;
-}
-
-function normalizeCodexVersion(version: string): string {
-  const [main, prerelease] = version.trim().split("-", 2);
-  const segments = (main ?? "")
-    .split(".")
-    .map((segment) => segment.trim())
-    .filter((segment) => segment.length > 0);
-
-  if (segments.length === 2) {
-    segments.push("0");
-  }
-
-  return prerelease ? `${segments.join(".")}-${prerelease}` : segments.join(".");
-}
-
-function parseSemver(version: string): ParsedSemver | null {
-  const normalized = normalizeCodexVersion(version);
-  const [main = "", prerelease] = normalized.split("-", 2);
-  const segments = main.split(".");
-  if (segments.length !== 3) {
-    return null;
-  }
-
-  const [majorSegment, minorSegment, patchSegment] = segments;
-  if (majorSegment === undefined || minorSegment === undefined || patchSegment === undefined) {
-    return null;
-  }
-
-  const major = Number.parseInt(majorSegment, 10);
-  const minor = Number.parseInt(minorSegment, 10);
-  const patch = Number.parseInt(patchSegment, 10);
-  if (![major, minor, patch].every(Number.isInteger)) {
-    return null;
-  }
-
-  return {
-    major,
-    minor,
-    patch,
-    prerelease:
-      prerelease
-        ?.split(".")
-        .map((segment) => segment.trim())
-        .filter((segment) => segment.length > 0) ?? [],
-  };
-}
-
-function comparePrereleaseIdentifier(left: string, right: string): number {
-  const leftNumeric = /^\d+$/.test(left);
-  const rightNumeric = /^\d+$/.test(right);
-
-  if (leftNumeric && rightNumeric) {
-    return Number.parseInt(left, 10) - Number.parseInt(right, 10);
-  }
-  if (leftNumeric) {
-    return -1;
-  }
-  if (rightNumeric) {
-    return 1;
-  }
-  return left.localeCompare(right);
-}
-
-export function compareCodexCliVersions(left: string, right: string): number {
-  const parsedLeft = parseSemver(left);
-  const parsedRight = parseSemver(right);
-  if (!parsedLeft || !parsedRight) {
-    return left.localeCompare(right);
-  }
-
-  if (parsedLeft.major !== parsedRight.major) {
-    return parsedLeft.major - parsedRight.major;
-  }
-  if (parsedLeft.minor !== parsedRight.minor) {
-    return parsedLeft.minor - parsedRight.minor;
-  }
-  if (parsedLeft.patch !== parsedRight.patch) {
-    return parsedLeft.patch - parsedRight.patch;
-  }
-
-  if (parsedLeft.prerelease.length === 0 && parsedRight.prerelease.length === 0) {
-    return 0;
-  }
-  if (parsedLeft.prerelease.length === 0) {
-    return 1;
-  }
-  if (parsedRight.prerelease.length === 0) {
-    return -1;
-  }
-
-  const length = Math.max(parsedLeft.prerelease.length, parsedRight.prerelease.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftIdentifier = parsedLeft.prerelease[index];
-    const rightIdentifier = parsedRight.prerelease[index];
-    if (leftIdentifier === undefined) {
-      return -1;
-    }
-    if (rightIdentifier === undefined) {
-      return 1;
-    }
-    const comparison = comparePrereleaseIdentifier(leftIdentifier, rightIdentifier);
-    if (comparison !== 0) {
-      return comparison;
-    }
-  }
-
-  return 0;
-}
-
-export function parseCodexCliVersion(output: string): string | null {
-  const match = CODEX_VERSION_PATTERN.exec(output);
-  if (!match?.[1]) {
-    return null;
-  }
-
-  const parsed = parseSemver(match[1]);
-  if (!parsed) {
-    return null;
-  }
-
-  return normalizeCodexVersion(match[1]);
-}
-
-export function isCodexCliVersionSupported(version: string): boolean {
-  return compareCodexCliVersions(version, MINIMUM_CODEX_CLI_VERSION) >= 0;
-}
-
-export function formatCodexCliUpgradeMessage(version: string | null): string {
-  const versionLabel = version ? `v${version}` : "the installed version";
-  return `Codex CLI ${versionLabel} is too old for T3 Code. Upgrade to v${MINIMUM_CODEX_CLI_VERSION} or newer and restart T3 Code.`;
-}
diff --git a/apps/server/src/provider/makeManagedServerProvider.test.ts b/apps/server/src/provider/makeManagedServerProvider.test.ts
new file mode 100644
index 00000000000..1f3ebeab089
--- /dev/null
+++ b/apps/server/src/provider/makeManagedServerProvider.test.ts
@@ -0,0 +1,288 @@
+import { describe, it, assert } from "@effect/vitest";
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+
+import { makeManagedServerProvider } from "./makeManagedServerProvider.ts";
+
+const emptyCapabilities = createModelCapabilities({ optionDescriptors: [] });
+const fastModeCapabilities = createModelCapabilities({
+  optionDescriptors: [
+    {
+      id: "fastMode",
+      label: "Fast Mode",
+      type: "boolean",
+    },
+  ],
+});
+
+interface TestSettings {
+  readonly enabled: boolean;
+}
+
+const maintenanceCapabilities = {
+  provider: ProviderDriverKind.make("codex"),
+  packageName: "@openai/codex",
+  update: {
+    command: "npm install -g @openai/codex@latest",
+
+    executable: "npm",
+
+    args: ["install", "-g", "@openai/codex@latest"],
+
+    lockKey: "npm-global",
+  },
+} as const;
+
+const initialSnapshot: ServerProvider = {
+  instanceId: ProviderInstanceId.make("codex"),
+  driver: ProviderDriverKind.make("codex"),
+  enabled: true,
+  installed: true,
+  version: null,
+  status: "warning",
+  auth: { status: "unknown" },
+  checkedAt: "2026-04-10T00:00:00.000Z",
+  message: "Checking provider availability...",
+  models: [],
+  slashCommands: [],
+  skills: [],
+};
+
+const refreshedSnapshot: ServerProvider = {
+  instanceId: ProviderInstanceId.make("codex"),
+  driver: ProviderDriverKind.make("codex"),
+  enabled: true,
+  installed: true,
+  version: "1.0.0",
+  status: "ready",
+  auth: { status: "authenticated" },
+  checkedAt: "2026-04-10T00:00:01.000Z",
+  models: [],
+  slashCommands: [],
+  skills: [],
+};
+
+const enrichedSnapshot: ServerProvider = {
+  ...refreshedSnapshot,
+  checkedAt: "2026-04-10T00:00:02.000Z",
+  models: [
+    {
+      slug: "composer-2",
+      name: "Composer 2",
+      isCustom: false,
+      capabilities: fastModeCapabilities,
+    },
+  ],
+};
+
+const refreshedSnapshotSecond: ServerProvider = {
+  ...refreshedSnapshot,
+  checkedAt: "2026-04-10T00:00:03.000Z",
+  message: "Refreshed provider availability again.",
+};
+
+const enrichedSnapshotSecond: ServerProvider = {
+  ...refreshedSnapshotSecond,
+  checkedAt: "2026-04-10T00:00:04.000Z",
+  models: [
+    {
+      slug: "gpt-5.4",
+      name: "GPT-5.4",
+      isCustom: false,
+      capabilities: emptyCapabilities,
+    },
+  ],
+};
+
+describe("makeManagedServerProvider", () => {
+  it.effect(
+    "runs the initial provider check in the background and streams the refreshed snapshot",
+    () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const checkCalls = yield* Ref.make(0);
+          const releaseCheck = yield* Deferred.make<void>();
+          const provider = yield* makeManagedServerProvider<TestSettings>({
+            maintenanceCapabilities,
+            getSettings: Effect.succeed({ enabled: true }),
+            streamSettings: Stream.empty,
+            haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
+            initialSnapshot: () => Effect.succeed(initialSnapshot),
+            checkProvider: Ref.update(checkCalls, (count) => count + 1).pipe(
+              Effect.flatMap(() => Deferred.await(releaseCheck)),
+              Effect.as(refreshedSnapshot),
+            ),
+            refreshInterval: "1 hour",
+          });
+
+          const initial = yield* provider.getSnapshot;
+          assert.deepStrictEqual(initial, initialSnapshot);
+
+          const updatesFiber = yield* Stream.take(provider.streamChanges, 1).pipe(
+            Stream.runCollect,
+            Effect.forkChild,
+          );
+          yield* Effect.yieldNow;
+
+          yield* Deferred.succeed(releaseCheck, undefined);
+
+          const updates = Array.from(yield* Fiber.join(updatesFiber));
+          const latest = yield* provider.getSnapshot;
+
+          assert.deepStrictEqual(updates, [refreshedSnapshot]);
+          assert.deepStrictEqual(latest, refreshedSnapshot);
+          assert.strictEqual(yield* Ref.get(checkCalls), 1);
+        }),
+      ),
+  );
+
+  it.effect("reruns the provider check when streamed settings change", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const settingsRef = yield* Ref.make<TestSettings>({ enabled: true });
+        const settingsChanges = yield* PubSub.unbounded<TestSettings>();
+        const checkCalls = yield* Ref.make(0);
+        const releaseInitialCheck = yield* Deferred.make<void>();
+        const releaseSettingsCheck = yield* Deferred.make<void>();
+        const provider = yield* makeManagedServerProvider<TestSettings>({
+          maintenanceCapabilities,
+          getSettings: Ref.get(settingsRef),
+          streamSettings: Stream.fromPubSub(settingsChanges),
+          haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
+          initialSnapshot: () => Effect.succeed(initialSnapshot),
+          checkProvider: Ref.updateAndGet(checkCalls, (count) => count + 1).pipe(
+            Effect.flatMap((count) =>
+              count === 1
+                ? Deferred.await(releaseInitialCheck).pipe(Effect.as(refreshedSnapshot))
+                : Deferred.await(releaseSettingsCheck).pipe(Effect.as(refreshedSnapshotSecond)),
+            ),
+          ),
+          refreshInterval: "1 hour",
+        });
+
+        const updatesFiber = yield* Stream.take(provider.streamChanges, 2).pipe(
+          Stream.runCollect,
+          Effect.forkChild,
+        );
+        yield* Effect.yieldNow;
+
+        yield* Deferred.succeed(releaseInitialCheck, undefined);
+        yield* Ref.set(settingsRef, { enabled: false });
+        yield* PubSub.publish(settingsChanges, { enabled: false });
+        yield* Deferred.succeed(releaseSettingsCheck, undefined);
+
+        const updates = Array.from(yield* Fiber.join(updatesFiber));
+        const latest = yield* provider.getSnapshot;
+
+        assert.deepStrictEqual(updates, [refreshedSnapshot, refreshedSnapshotSecond]);
+        assert.deepStrictEqual(latest, refreshedSnapshotSecond);
+        assert.strictEqual(yield* Ref.get(checkCalls), 2);
+      }),
+    ),
+  );
+
+  it.effect("streams supplemental snapshot updates after the base provider check completes", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const releaseEnrichment = yield* Deferred.make<void>();
+        const releaseCheck = yield* Deferred.make<void>();
+        const provider = yield* makeManagedServerProvider<TestSettings>({
+          maintenanceCapabilities,
+          getSettings: Effect.succeed({ enabled: true }),
+          streamSettings: Stream.empty,
+          haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
+          initialSnapshot: () => Effect.succeed(initialSnapshot),
+          checkProvider: Deferred.await(releaseCheck).pipe(Effect.as(refreshedSnapshot)),
+          enrichSnapshot: ({ publishSnapshot }) =>
+            Deferred.await(releaseEnrichment).pipe(
+              Effect.flatMap(() => publishSnapshot(enrichedSnapshot)),
+            ),
+          refreshInterval: "1 hour",
+        });
+
+        const updatesFiber = yield* Stream.take(provider.streamChanges, 2).pipe(
+          Stream.runCollect,
+          Effect.forkChild,
+        );
+        yield* Effect.yieldNow;
+
+        yield* Deferred.succeed(releaseCheck, undefined);
+
+        yield* Deferred.succeed(releaseEnrichment, undefined);
+
+        const updates = Array.from(yield* Fiber.join(updatesFiber));
+        const latest = yield* provider.getSnapshot;
+
+        assert.deepStrictEqual(updates, [refreshedSnapshot, enrichedSnapshot]);
+        assert.deepStrictEqual(latest, enrichedSnapshot);
+      }),
+    ),
+  );
+
+  it.effect("ignores stale enrichment callbacks after a newer refresh advances generation", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const publishCallbacks: Array<(snapshot: ServerProvider) => Effect.Effect<void>> = [];
+        const refreshCount = yield* Ref.make(0);
+        const firstCallbackReady = yield* Deferred.make<void>();
+        const secondCallbackReady = yield* Deferred.make<void>();
+        const allowFirstRefresh = yield* Deferred.make<void>();
+        const provider = yield* makeManagedServerProvider<TestSettings>({
+          maintenanceCapabilities,
+          getSettings: Effect.succeed({ enabled: true }),
+          streamSettings: Stream.empty,
+          haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
+          initialSnapshot: () => Effect.succeed(initialSnapshot),
+          checkProvider: Ref.updateAndGet(refreshCount, (count) => count + 1).pipe(
+            Effect.flatMap((count) =>
+              count === 1
+                ? Deferred.await(allowFirstRefresh).pipe(Effect.as(refreshedSnapshot))
+                : Effect.succeed(refreshedSnapshotSecond),
+            ),
+          ),
+          enrichSnapshot: ({ publishSnapshot }) =>
+            Effect.gen(function* () {
+              publishCallbacks.push(publishSnapshot);
+              if (publishCallbacks.length === 1) {
+                yield* Deferred.succeed(firstCallbackReady, undefined).pipe(Effect.ignore);
+              } else if (publishCallbacks.length === 2) {
+                yield* Deferred.succeed(secondCallbackReady, undefined).pipe(Effect.ignore);
+              }
+            }),
+          refreshInterval: "1 hour",
+        });
+
+        const updatesFiber = yield* Stream.take(provider.streamChanges, 3).pipe(
+          Stream.runCollect,
+          Effect.forkChild,
+        );
+        yield* Effect.yieldNow;
+
+        yield* Deferred.succeed(allowFirstRefresh, undefined);
+        yield* Deferred.await(firstCallbackReady);
+
+        yield* provider.refresh;
+        yield* Deferred.await(secondCallbackReady);
+
+        yield* publishCallbacks[0]!(enrichedSnapshot);
+        yield* publishCallbacks[1]!(enrichedSnapshotSecond);
+
+        const updates = Array.from(yield* Fiber.join(updatesFiber));
+        const latest = yield* provider.getSnapshot;
+
+        assert.deepStrictEqual(updates, [
+          refreshedSnapshot,
+          refreshedSnapshotSecond,
+          enrichedSnapshotSecond,
+        ]);
+        assert.deepStrictEqual(latest, enrichedSnapshotSecond);
+      }),
+    ),
+  );
+});
diff --git a/apps/server/src/provider/makeManagedServerProvider.ts b/apps/server/src/provider/makeManagedServerProvider.ts
index 59aeac1ab5f..2f07c5d508c 100644
--- a/apps/server/src/provider/makeManagedServerProvider.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.ts
@@ -1,17 +1,37 @@
 import type { ServerProvider } from "@t3tools/contracts";
-import { Duration, Effect, PubSub, Ref, Scope, Stream } from "effect";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as Fiber from "effect/Fiber";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import * as Semaphore from "effect/Semaphore";
 
-import type { ServerProviderShape } from "./Services/ServerProvider";
+import type { ServerProviderShape } from "./Services/ServerProvider.ts";
 import { ServerSettingsError } from "@t3tools/contracts";
 
+interface ProviderSnapshotState {
+  readonly snapshot: ServerProvider;
+  readonly enrichmentGeneration: number;
+}
+
 export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(function* <
   Settings,
 >(input: {
+  readonly maintenanceCapabilities: ServerProviderShape["maintenanceCapabilities"];
   readonly getSettings: Effect.Effect<Settings>;
   readonly streamSettings: Stream.Stream<Settings>;
   readonly haveSettingsChanged: (previous: Settings, next: Settings) => boolean;
+  readonly initialSnapshot: (settings: Settings) => Effect.Effect<ServerProvider>;
   readonly checkProvider: Effect.Effect<ServerProvider, ServerSettingsError>;
+  readonly enrichSnapshot?: (input: {
+    readonly settings: Settings;
+    readonly snapshot: ServerProvider;
+    readonly getSnapshot: Effect.Effect<ServerProvider>;
+    readonly publishSnapshot: (snapshot: ServerProvider) => Effect.Effect<void>;
+  }) => Effect.Effect<void>;
   readonly refreshInterval?: Duration.Input;
 }): Effect.fn.Return<ServerProviderShape, ServerSettingsError, Scope.Scope> {
   const refreshSemaphore = yield* Semaphore.make(1);
@@ -20,9 +40,62 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
     PubSub.shutdown,
   );
   const initialSettings = yield* input.getSettings;
-  const initialSnapshot = yield* input.checkProvider;
-  const snapshotRef = yield* Ref.make(initialSnapshot);
+  const initialSnapshot = yield* input.initialSnapshot(initialSettings);
+  const snapshotStateRef = yield* Ref.make<ProviderSnapshotState>({
+    snapshot: initialSnapshot,
+    enrichmentGeneration: 0,
+  });
   const settingsRef = yield* Ref.make(initialSettings);
+  const enrichmentFiberRef = yield* Ref.make<Fiber.Fiber<void, unknown> | null>(null);
+  const scope = yield* Effect.scope;
+
+  const publishEnrichedSnapshot = Effect.fn("publishEnrichedSnapshot")(function* (
+    generation: number,
+    nextSnapshot: ServerProvider,
+  ) {
+    const snapshotToPublish = yield* Ref.modify(snapshotStateRef, (state) => {
+      if (state.enrichmentGeneration !== generation || Equal.equals(state.snapshot, nextSnapshot)) {
+        return [null, state] as const;
+      }
+      return [
+        nextSnapshot,
+        {
+          ...state,
+          snapshot: nextSnapshot,
+        },
+      ] as const;
+    });
+    if (snapshotToPublish === null) {
+      return;
+    }
+    yield* PubSub.publish(changesPubSub, snapshotToPublish);
+  });
+
+  const restartSnapshotEnrichment = Effect.fn("restartSnapshotEnrichment")(function* (
+    settings: Settings,
+    snapshot: ServerProvider,
+    generation: number,
+  ) {
+    const previousFiber = yield* Ref.getAndSet(enrichmentFiberRef, null);
+    if (previousFiber) {
+      yield* Fiber.interrupt(previousFiber).pipe(Effect.ignore);
+    }
+
+    if (!input.enrichSnapshot) {
+      return;
+    }
+
+    const fiber = yield* input
+      .enrichSnapshot({
+        settings,
+        snapshot,
+        getSnapshot: Ref.get(snapshotStateRef).pipe(Effect.map((state) => state.snapshot)),
+        publishSnapshot: (nextSnapshot) => publishEnrichedSnapshot(generation, nextSnapshot),
+      })
+      .pipe(Effect.ignoreCause({ log: true }), Effect.forkIn(scope));
+
+    yield* Ref.set(enrichmentFiberRef, fiber);
+  });
 
   const applySnapshotBase = Effect.fn("applySnapshot")(function* (
     nextSettings: Settings,
@@ -32,13 +105,25 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
     const previousSettings = yield* Ref.get(settingsRef);
     if (!forceRefresh && !input.haveSettingsChanged(previousSettings, nextSettings)) {
       yield* Ref.set(settingsRef, nextSettings);
-      return yield* Ref.get(snapshotRef);
+      return yield* Ref.get(snapshotStateRef).pipe(Effect.map((state) => state.snapshot));
     }
 
     const nextSnapshot = yield* input.checkProvider;
+    const nextGeneration = yield* Ref.modify(snapshotStateRef, (state) => {
+      const generation = input.enrichSnapshot
+        ? state.enrichmentGeneration + 1
+        : state.enrichmentGeneration;
+      return [
+        generation,
+        {
+          snapshot: nextSnapshot,
+          enrichmentGeneration: generation,
+        },
+      ] as const;
+    });
     yield* Ref.set(settingsRef, nextSettings);
-    yield* Ref.set(snapshotRef, nextSnapshot);
     yield* PubSub.publish(changesPubSub, nextSnapshot);
+    yield* restartSnapshotEnrichment(nextSettings, nextSnapshot, nextGeneration);
     return nextSnapshot;
   });
   const applySnapshot = (nextSettings: Settings, options?: { readonly forceRefresh?: boolean }) =>
@@ -60,7 +145,13 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
     ),
   ).pipe(Effect.forkScoped);
 
+  yield* applySnapshot(initialSettings, { forceRefresh: true }).pipe(
+    Effect.ignoreCause({ log: true }),
+    Effect.forkScoped,
+  );
+
   return {
+    maintenanceCapabilities: input.maintenanceCapabilities,
     getSnapshot: input.getSettings.pipe(
       Effect.flatMap(applySnapshot),
       Effect.tapError(Effect.logError),
diff --git a/apps/server/src/provider/opencodeRuntime.ts b/apps/server/src/provider/opencodeRuntime.ts
new file mode 100644
index 00000000000..ddeb9f26431
--- /dev/null
+++ b/apps/server/src/provider/opencodeRuntime.ts
@@ -0,0 +1,552 @@
+import { pathToFileURL } from "node:url";
+
+import type { ChatAttachment, ProviderApprovalDecision, RuntimeMode } from "@t3tools/contracts";
+import {
+  createOpencodeClient,
+  type Agent,
+  type FilePartInput,
+  type OpencodeClient,
+  type PermissionRuleset,
+  type ProviderListResponse,
+  type QuestionAnswer,
+  type QuestionRequest,
+} from "@opencode-ai/sdk/v2";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as P from "effect/Predicate";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Scope from "effect/Scope";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { isWindowsCommandNotFound } from "../processRunner.ts";
+import { collectStreamAsString } from "./providerSnapshot.ts";
+import * as NetService from "@t3tools/shared/Net";
+const encodeUnknownJsonStringExit = Schema.encodeUnknownExit(Schema.UnknownFromJsonString);
+const OPENCODE_EMPTY_CONFIG_CONTENT = "{}";
+
+const OPENCODE_SERVER_READY_PREFIX = "opencode server listening";
+const DEFAULT_OPENCODE_SERVER_TIMEOUT_MS = 5_000;
+const DEFAULT_HOSTNAME = "127.0.0.1";
+export interface OpenCodeServerProcess {
+  readonly url: string;
+  readonly exitCode: Effect.Effect<number, never>;
+}
+
+export interface OpenCodeServerConnection {
+  readonly url: string;
+  readonly exitCode: Effect.Effect<number, never> | null;
+  readonly external: boolean;
+}
+
+const OPENCODE_RUNTIME_ERROR_TAG = "OpenCodeRuntimeError";
+export class OpenCodeRuntimeError extends Data.TaggedError(OPENCODE_RUNTIME_ERROR_TAG)<{
+  readonly operation: string;
+  readonly cause?: unknown;
+  readonly detail: string;
+}> {
+  static readonly is = (u: unknown): u is OpenCodeRuntimeError =>
+    P.isTagged(u, OPENCODE_RUNTIME_ERROR_TAG);
+}
+
+function encodeJsonStringForDiagnostics(input: unknown): string | undefined {
+  const result = encodeUnknownJsonStringExit(input);
+  return Exit.isSuccess(result) ? result.value : undefined;
+}
+
+export function openCodeRuntimeErrorDetail(cause: unknown): string {
+  if (OpenCodeRuntimeError.is(cause)) return cause.detail;
+  if (cause instanceof Error && cause.message.trim().length > 0) return cause.message.trim();
+  if (cause && typeof cause === "object") {
+    // SDK v2 throws { response, request, error? } shapes — extract what's useful
+    const anyCause = cause as Record<string, unknown>;
+    const status = (anyCause.response as { status?: number } | undefined)?.status;
+    const body = anyCause.error ?? anyCause.data ?? anyCause.body;
+    const encodedBody = encodeJsonStringForDiagnostics(body ?? cause);
+    if (encodedBody) {
+      return `status=${status ?? "?"} body=${encodedBody}`;
+    }
+  }
+  return String(cause);
+}
+
+export const runOpenCodeSdk = <A>(
+  operation: string,
+  fn: () => Promise<A>,
+): Effect.Effect<A, OpenCodeRuntimeError> =>
+  Effect.tryPromise({
+    try: fn,
+    catch: (cause) =>
+      new OpenCodeRuntimeError({ operation, detail: openCodeRuntimeErrorDetail(cause), cause }),
+  }).pipe(Effect.withSpan(`opencode.${operation}`));
+
+export interface OpenCodeCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly code: number;
+}
+
+export interface OpenCodeInventory {
+  readonly providerList: ProviderListResponse;
+  readonly agents: ReadonlyArray<Agent>;
+}
+
+export interface ParsedOpenCodeModelSlug {
+  readonly providerID: string;
+  readonly modelID: string;
+}
+
+export interface OpenCodeRuntimeShape {
+  /**
+   * Spawns a local OpenCode server process. Its lifetime is bound to the caller's
+   * `Scope.Scope` — the child is killed automatically when that scope closes.
+   * Consumers that want a long-lived server must create and hold a scope explicitly
+   * (see {@link Scope.make}) and close it when done.
+   */
+  readonly startOpenCodeServerProcess: (input: {
+    readonly binaryPath: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly port?: number;
+    readonly hostname?: string;
+    readonly timeoutMs?: number;
+  }) => Effect.Effect<OpenCodeServerProcess, OpenCodeRuntimeError, Scope.Scope>;
+  /**
+   * Returns a handle to either an externally-managed OpenCode server (when
+   * `serverUrl` is provided — no lifetime is attached to the caller's scope) or a
+   * freshly spawned local server whose lifetime is bound to the caller's scope.
+   */
+  readonly connectToOpenCodeServer: (input: {
+    readonly binaryPath: string;
+    readonly serverUrl?: string | null;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly port?: number;
+    readonly hostname?: string;
+    readonly timeoutMs?: number;
+  }) => Effect.Effect<OpenCodeServerConnection, OpenCodeRuntimeError, Scope.Scope>;
+  readonly runOpenCodeCommand: (input: {
+    readonly binaryPath: string;
+    readonly args: ReadonlyArray<string>;
+    readonly environment?: NodeJS.ProcessEnv;
+  }) => Effect.Effect<OpenCodeCommandResult, OpenCodeRuntimeError>;
+  readonly createOpenCodeSdkClient: (input: {
+    readonly baseUrl: string;
+    readonly directory: string;
+    readonly serverPassword?: string;
+  }) => OpencodeClient;
+  readonly loadOpenCodeInventory: (
+    client: OpencodeClient,
+  ) => Effect.Effect<OpenCodeInventory, OpenCodeRuntimeError>;
+}
+
+function parseServerUrlFromOutput(output: string): string | null {
+  for (const line of output.split("\n")) {
+    if (!line.startsWith(OPENCODE_SERVER_READY_PREFIX)) {
+      continue;
+    }
+    const match = line.match(/on\s+(https?:\/\/[^\s]+)/);
+    return match?.[1] ?? null;
+  }
+  return null;
+}
+
+export function parseOpenCodeModelSlug(
+  slug: string | null | undefined,
+): ParsedOpenCodeModelSlug | null {
+  if (typeof slug !== "string") {
+    return null;
+  }
+
+  const trimmed = slug.trim();
+  const separator = trimmed.indexOf("/");
+  if (separator <= 0 || separator === trimmed.length - 1) {
+    return null;
+  }
+
+  return {
+    providerID: trimmed.slice(0, separator),
+    modelID: trimmed.slice(separator + 1),
+  };
+}
+
+export function openCodeQuestionId(
+  index: number,
+  question: QuestionRequest["questions"][number],
+): string {
+  const header = question.header
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-");
+  return header.length > 0 ? `question-${index}-${header}` : `question-${index}`;
+}
+
+export function toOpenCodeFileParts(input: {
+  readonly attachments: ReadonlyArray<ChatAttachment> | undefined;
+  readonly resolveAttachmentPath: (attachment: ChatAttachment) => string | null;
+}): Array<FilePartInput> {
+  const parts: Array<FilePartInput> = [];
+
+  for (const attachment of input.attachments ?? []) {
+    const attachmentPath = input.resolveAttachmentPath(attachment);
+    if (!attachmentPath) {
+      continue;
+    }
+
+    parts.push({
+      type: "file",
+      mime: attachment.mimeType,
+      filename: attachment.name,
+      url: pathToFileURL(attachmentPath).href,
+    });
+  }
+
+  return parts;
+}
+
+export function buildOpenCodePermissionRules(runtimeMode: RuntimeMode): PermissionRuleset {
+  if (runtimeMode === "full-access") {
+    return [{ permission: "*", pattern: "*", action: "allow" }];
+  }
+
+  return [
+    { permission: "*", pattern: "*", action: "ask" },
+    { permission: "bash", pattern: "*", action: "ask" },
+    { permission: "edit", pattern: "*", action: "ask" },
+    { permission: "webfetch", pattern: "*", action: "ask" },
+    { permission: "websearch", pattern: "*", action: "ask" },
+    { permission: "codesearch", pattern: "*", action: "ask" },
+    { permission: "external_directory", pattern: "*", action: "ask" },
+    { permission: "doom_loop", pattern: "*", action: "ask" },
+    { permission: "question", pattern: "*", action: "allow" },
+  ];
+}
+
+export function toOpenCodePermissionReply(
+  decision: ProviderApprovalDecision,
+): "once" | "always" | "reject" {
+  switch (decision) {
+    case "accept":
+      return "once";
+    case "acceptForSession":
+      return "always";
+    case "decline":
+    case "cancel":
+    default:
+      return "reject";
+  }
+}
+
+export function toOpenCodeQuestionAnswers(
+  request: QuestionRequest,
+  answers: Record<string, unknown>,
+): Array<QuestionAnswer> {
+  return request.questions.map((question, index) => {
+    const raw =
+      answers[openCodeQuestionId(index, question)] ??
+      answers[question.header] ??
+      answers[question.question];
+    if (Array.isArray(raw)) {
+      return raw.filter((value): value is string => typeof value === "string");
+    }
+    if (typeof raw === "string") {
+      return raw.trim().length > 0 ? [raw] : [];
+    }
+    return [];
+  });
+}
+
+function ensureRuntimeError(
+  operation: OpenCodeRuntimeError["operation"],
+  detail: string,
+  cause: unknown,
+): OpenCodeRuntimeError {
+  return OpenCodeRuntimeError.is(cause)
+    ? cause
+    : new OpenCodeRuntimeError({ operation, detail, cause });
+}
+
+const makeOpenCodeRuntime = Effect.gen(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const netService = yield* NetService.NetService;
+
+  const runOpenCodeCommand: OpenCodeRuntimeShape["runOpenCodeCommand"] = (input) =>
+    Effect.gen(function* () {
+      const child = yield* spawner.spawn(
+        ChildProcess.make(input.binaryPath, [...input.args], {
+          shell: process.platform === "win32",
+          env: input.environment ?? process.env,
+        }),
+      );
+      const [stdout, stderr, code] = yield* Effect.all(
+        [collectStreamAsString(child.stdout), collectStreamAsString(child.stderr), child.exitCode],
+        { concurrency: "unbounded" },
+      );
+      const exitCode = Number(code);
+      if (isWindowsCommandNotFound(exitCode, stderr)) {
+        return yield* new OpenCodeRuntimeError({
+          operation: "runOpenCodeCommand",
+          detail: `spawn ${input.binaryPath} ENOENT`,
+        });
+      }
+      return {
+        stdout,
+        stderr,
+        code: exitCode,
+      } satisfies OpenCodeCommandResult;
+    }).pipe(
+      Effect.scoped,
+      Effect.mapError((cause) =>
+        ensureRuntimeError(
+          "runOpenCodeCommand",
+          `Failed to execute '${input.binaryPath} ${input.args.join(" ")}': ${openCodeRuntimeErrorDetail(cause)}`,
+          cause,
+        ),
+      ),
+    );
+
+  const startOpenCodeServerProcess: OpenCodeRuntimeShape["startOpenCodeServerProcess"] = (input) =>
+    Effect.gen(function* () {
+      // Bind this server's lifetime to the caller's scope. When the caller's
+      // scope closes, the spawned child is killed and all associated fibers
+      // are interrupted automatically — no `close()` method needed.
+      const runtimeScope = yield* Scope.Scope;
+
+      const hostname = input.hostname ?? DEFAULT_HOSTNAME;
+      const port =
+        input.port ??
+        (yield* netService.findAvailablePort(0).pipe(
+          Effect.mapError(
+            (cause) =>
+              new OpenCodeRuntimeError({
+                operation: "startOpenCodeServerProcess",
+                detail: `Failed to find available port: ${openCodeRuntimeErrorDetail(cause)}`,
+                cause,
+              }),
+          ),
+        ));
+      const timeoutMs = input.timeoutMs ?? DEFAULT_OPENCODE_SERVER_TIMEOUT_MS;
+      const args = ["serve", `--hostname=${hostname}`, `--port=${port}`];
+
+      const child = yield* spawner
+        .spawn(
+          ChildProcess.make(input.binaryPath, args, {
+            detached: process.platform !== "win32",
+            shell: process.platform === "win32",
+            env: {
+              ...(input.environment ?? process.env),
+              OPENCODE_CONFIG_CONTENT: OPENCODE_EMPTY_CONFIG_CONTENT,
+            },
+          }),
+        )
+        .pipe(
+          Effect.provideService(Scope.Scope, runtimeScope),
+          Effect.mapError(
+            (cause) =>
+              new OpenCodeRuntimeError({
+                operation: "startOpenCodeServerProcess",
+                detail: `Failed to spawn OpenCode server process: ${openCodeRuntimeErrorDetail(cause)}`,
+                cause,
+              }),
+          ),
+        );
+
+      const killOpenCodeProcessGroup = (signal: NodeJS.Signals) =>
+        process.platform === "win32"
+          ? child.kill({ killSignal: signal, forceKillAfter: "1 second" }).pipe(Effect.asVoid)
+          : Effect.sync(() => {
+              try {
+                process.kill(-Number(child.pid), signal);
+              } catch {
+                // The direct child may already have exited after starting the
+                // server; the process group kill is best-effort cleanup for
+                // any serve process left in that group.
+              }
+            });
+      const terminateChild = killOpenCodeProcessGroup("SIGTERM").pipe(
+        Effect.andThen(Effect.sleep("1 second")),
+        Effect.andThen(killOpenCodeProcessGroup("SIGKILL")),
+        Effect.ignore,
+      );
+      yield* Scope.addFinalizer(runtimeScope, terminateChild);
+
+      const stdoutRef = yield* Ref.make("");
+      const stderrRef = yield* Ref.make("");
+      const readyDeferred = yield* Deferred.make<string, OpenCodeRuntimeError>();
+
+      const setReadyFromStdoutChunk = (chunk: string) =>
+        Ref.updateAndGet(stdoutRef, (stdout) => `${stdout}${chunk}`).pipe(
+          Effect.flatMap((nextStdout) => {
+            const parsed = parseServerUrlFromOutput(nextStdout);
+            return parsed
+              ? Deferred.succeed(readyDeferred, parsed).pipe(Effect.ignore)
+              : Effect.void;
+          }),
+        );
+
+      const stdoutFiber = yield* child.stdout.pipe(
+        Stream.decodeText(),
+        Stream.runForEach(setReadyFromStdoutChunk),
+        Effect.ignore,
+        Effect.forkIn(runtimeScope),
+      );
+      const stderrFiber = yield* child.stderr.pipe(
+        Stream.decodeText(),
+        Stream.runForEach((chunk) => Ref.update(stderrRef, (stderr) => `${stderr}${chunk}`)),
+        Effect.ignore,
+        Effect.forkIn(runtimeScope),
+      );
+
+      const exitFiber = yield* child.exitCode.pipe(
+        Effect.flatMap((code) =>
+          Effect.gen(function* () {
+            const stdout = yield* Ref.get(stdoutRef);
+            const stderr = yield* Ref.get(stderrRef);
+            const exitCode = Number(code);
+            yield* Deferred.fail(
+              readyDeferred,
+              new OpenCodeRuntimeError({
+                operation: "startOpenCodeServerProcess",
+                detail: [
+                  `OpenCode server exited before startup completed (code: ${String(exitCode)}).`,
+                  stdout.trim() ? `stdout:\n${stdout.trim()}` : null,
+                  stderr.trim() ? `stderr:\n${stderr.trim()}` : null,
+                ]
+                  .filter(Boolean)
+                  .join("\n\n"),
+                cause: { exitCode, stdout, stderr },
+              }),
+            ).pipe(Effect.ignore);
+          }),
+        ),
+        Effect.ignore,
+        Effect.forkIn(runtimeScope),
+      );
+
+      const readyExit = yield* Effect.exit(
+        Deferred.await(readyDeferred).pipe(Effect.timeoutOption(timeoutMs)),
+      );
+
+      // Startup-time fibers are no longer needed once ready has resolved (either
+      // way). The exit fiber is only interrupted on failure; on success it keeps
+      // the caller's `exitCode` effect observable until the scope closes.
+      yield* Fiber.interrupt(stdoutFiber).pipe(Effect.ignore);
+      yield* Fiber.interrupt(stderrFiber).pipe(Effect.ignore);
+
+      if (Exit.isFailure(readyExit)) {
+        yield* Fiber.interrupt(exitFiber).pipe(Effect.ignore);
+        const squashed = Cause.squash(readyExit.cause);
+        return yield* ensureRuntimeError(
+          "startOpenCodeServerProcess",
+          `Failed while waiting for OpenCode server startup: ${openCodeRuntimeErrorDetail(squashed)}`,
+          squashed,
+        );
+      }
+
+      const readyOption = readyExit.value;
+      if (Option.isNone(readyOption)) {
+        yield* Fiber.interrupt(exitFiber).pipe(Effect.ignore);
+        return yield* new OpenCodeRuntimeError({
+          operation: "startOpenCodeServerProcess",
+          detail: `Timed out waiting for OpenCode server start after ${timeoutMs}ms.`,
+        });
+      }
+
+      return {
+        url: readyOption.value,
+        exitCode: child.exitCode.pipe(
+          Effect.map(Number),
+          Effect.orElseSucceed(() => 0),
+        ),
+      } satisfies OpenCodeServerProcess;
+    });
+
+  const connectToOpenCodeServer: OpenCodeRuntimeShape["connectToOpenCodeServer"] = (input) => {
+    const serverUrl = input.serverUrl?.trim();
+    if (serverUrl) {
+      // We don't own externally-configured servers — no scope interaction.
+      return Effect.succeed({
+        url: serverUrl,
+        exitCode: null,
+        external: true,
+      });
+    }
+
+    return startOpenCodeServerProcess({
+      binaryPath: input.binaryPath,
+      ...(input.environment !== undefined ? { environment: input.environment } : {}),
+      ...(input.port !== undefined ? { port: input.port } : {}),
+      ...(input.hostname !== undefined ? { hostname: input.hostname } : {}),
+      ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+    }).pipe(
+      Effect.map((server) => ({
+        url: server.url,
+        exitCode: server.exitCode,
+        external: false,
+      })),
+    );
+  };
+
+  const createOpenCodeSdkClient: OpenCodeRuntimeShape["createOpenCodeSdkClient"] = (input) =>
+    createOpencodeClient({
+      baseUrl: input.baseUrl,
+      directory: input.directory,
+      ...(input.serverPassword
+        ? {
+            headers: {
+              Authorization: `Basic ${Buffer.from(`opencode:${input.serverPassword}`, "utf8").toString("base64")}`,
+            },
+          }
+        : {}),
+      throwOnError: true,
+    });
+
+  const loadProviders = (client: OpencodeClient) =>
+    runOpenCodeSdk("provider.list", () => client.provider.list()).pipe(
+      Effect.filterMapOrFail(
+        (list) =>
+          list.data
+            ? Result.succeed(list.data)
+            : Result.fail(
+                new OpenCodeRuntimeError({
+                  operation: "provider.list",
+                  detail: "OpenCode provider list was empty.",
+                }),
+              ),
+        (result) => result,
+      ),
+    );
+
+  const loadAgents = (client: OpencodeClient) =>
+    runOpenCodeSdk("app.agents", () => client.app.agents()).pipe(
+      Effect.map((result) => result.data ?? []),
+    );
+
+  const loadOpenCodeInventory: OpenCodeRuntimeShape["loadOpenCodeInventory"] = (client) =>
+    Effect.all([loadProviders(client), loadAgents(client)], { concurrency: "unbounded" }).pipe(
+      Effect.map(([providerList, agents]) => ({ providerList, agents })),
+    );
+
+  return {
+    startOpenCodeServerProcess,
+    connectToOpenCodeServer,
+    runOpenCodeCommand,
+    createOpenCodeSdkClient,
+    loadOpenCodeInventory,
+  } satisfies OpenCodeRuntimeShape;
+});
+
+export class OpenCodeRuntime extends Context.Service<OpenCodeRuntime, OpenCodeRuntimeShape>()(
+  "t3/provider/OpenCodeRuntime",
+) {}
+
+export const OpenCodeRuntimeLive = Layer.effect(OpenCodeRuntime, makeOpenCodeRuntime).pipe(
+  Layer.provide(NetService.layer),
+);
diff --git a/apps/server/src/provider/providerMaintenance.test.ts b/apps/server/src/provider/providerMaintenance.test.ts
new file mode 100644
index 00000000000..e032b87a4d0
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenance.test.ts
@@ -0,0 +1,489 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import { afterEach, describe, expect, it } from "@effect/vitest";
+import { chmodSync, mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import os from "node:os";
+import path from "node:path";
+import { ProviderDriverKind } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Random from "effect/Random";
+import {
+  clearLatestProviderVersionCacheForTests,
+  createProviderVersionAdvisory,
+  makePackageManagedProviderMaintenanceResolver,
+  makeProviderMaintenanceCapabilities,
+  makeStaticProviderMaintenanceResolver,
+  normalizeCommandPath,
+  resolveProviderMaintenanceCapabilitiesEffect,
+} from "./providerMaintenance.ts";
+
+const driver = (value: string) => ProviderDriverKind.make(value);
+const makeTempDir = Effect.fn("makeTempDir")(function* (name: string) {
+  const id = yield* Random.nextUUIDv4;
+  return path.join(os.tmpdir(), `${name}-${id}`);
+});
+const isNativeTestCommandPath =
+  (expectedPathSegment: string) =>
+  (commandPath: string): boolean =>
+    normalizeCommandPath(commandPath).includes(expectedPathSegment);
+const packageToolUpdate = makePackageManagedProviderMaintenanceResolver({
+  provider: driver("packageTool"),
+  npmPackageName: "@example/package-tool",
+  homebrewFormula: "package-tool",
+  nativeUpdate: null,
+});
+const nativePackageToolUpdate = makePackageManagedProviderMaintenanceResolver({
+  provider: driver("nativePackageTool"),
+  npmPackageName: "@example/native-package-tool",
+  homebrewFormula: "native-package-tool",
+  nativeUpdate: {
+    executable: "native-package-tool",
+    args: ["update"],
+    lockKey: "native-package-tool-native",
+    isCommandPath: isNativeTestCommandPath("/.local/bin/native-package-tool"),
+  },
+});
+const scopedPackageToolUpdate = makePackageManagedProviderMaintenanceResolver({
+  provider: driver("scopedPackageTool"),
+  npmPackageName: "@example/scoped-package-tool",
+  homebrewFormula: "example/tap/scoped-package-tool",
+  nativeUpdate: {
+    executable: "scoped-package-tool",
+    args: ["upgrade"],
+    lockKey: "scoped-package-tool-native",
+    isCommandPath: isNativeTestCommandPath("/.scoped-package-tool/bin/scoped-package-tool"),
+  },
+});
+const staticToolUpdate = makeStaticProviderMaintenanceResolver(
+  makeProviderMaintenanceCapabilities({
+    provider: driver("staticTool"),
+    packageName: null,
+    updateExecutable: "static-tool",
+    updateArgs: ["update"],
+    updateLockKey: "static-tool",
+  }),
+);
+
+afterEach(() => {
+  clearLatestProviderVersionCacheForTests();
+});
+
+describe("providerMaintenance", () => {
+  it("marks providers with unknown current versions as unknown", () => {
+    expect(
+      createProviderVersionAdvisory({
+        driver: driver("packageTool"),
+        currentVersion: null,
+        latestVersion: "9.9.9",
+      }),
+    ).toMatchObject({
+      status: "unknown",
+      currentVersion: null,
+      latestVersion: "9.9.9",
+    });
+  });
+
+  it("marks providers with unknown latest versions as unknown", () => {
+    expect(
+      createProviderVersionAdvisory({
+        driver: driver("packageTool"),
+        currentVersion: "1.0.0",
+        latestVersion: null,
+      }),
+    ).toMatchObject({
+      status: "unknown",
+      currentVersion: "1.0.0",
+      latestVersion: null,
+      message: null,
+    });
+  });
+
+  it("marks installed providers behind latest when a newer provider version is available", () => {
+    expect(
+      createProviderVersionAdvisory({
+        driver: driver("nativePackageTool"),
+        currentVersion: "2.1.110",
+        latestVersion: "2.1.117",
+        maintenanceCapabilities: nativePackageToolUpdate.resolve(),
+      }),
+    ).toMatchObject({
+      status: "behind_latest",
+      currentVersion: "2.1.110",
+      latestVersion: "2.1.117",
+      updateCommand: "npm install -g @example/native-package-tool@latest",
+      canUpdate: true,
+      message: "Install the update now or review provider settings.",
+    });
+  });
+
+  it("keeps update commands owned by provider maintenance capabilities", () => {
+    expect(staticToolUpdate.resolve()).toEqual({
+      provider: driver("staticTool"),
+      packageName: null,
+      update: {
+        command: "static-tool update",
+
+        executable: "static-tool",
+
+        args: ["update"],
+
+        lockKey: "static-tool",
+      },
+    });
+  });
+
+  it.effect(
+    "switches package-managed providers to vite-plus updates when the resolved binary lives in vite-plus global bin",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-vite-plus-capabilities");
+        const vitePlusBinDir = path.join(tempDir, ".vite-plus", "bin");
+        mkdirSync(vitePlusBinDir, { recursive: true });
+        const packageToolPath = path.join(vitePlusBinDir, "package-tool");
+        writeFileSync(packageToolPath, "#!/bin/sh\n");
+        chmodSync(packageToolPath, 0o755);
+
+        expect(
+          packageToolUpdate.resolve({
+            binaryPath: "package-tool",
+            platform: "darwin",
+            env: {
+              PATH: vitePlusBinDir,
+            },
+          }),
+        ).toEqual({
+          provider: driver("packageTool"),
+          packageName: "@example/package-tool",
+          update: {
+            command: "vp i -g @example/package-tool",
+
+            executable: "vp",
+
+            args: ["i", "-g", "@example/package-tool"],
+
+            lockKey: "vite-plus-global",
+          },
+        });
+      }),
+  );
+
+  it.effect(
+    "switches package-managed providers to bun updates when the resolved binary lives in bun's global bin",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-bun-capabilities");
+        const bunBinDir = path.join(tempDir, ".bun", "bin");
+        mkdirSync(bunBinDir, { recursive: true });
+        writeFileSync(path.join(bunBinDir, "native-package-tool.exe"), "MZ");
+
+        expect(
+          nativePackageToolUpdate.resolve({
+            binaryPath: "native-package-tool",
+            platform: "win32",
+            env: {
+              PATH: bunBinDir,
+              PATHEXT: ".COM;.EXE;.BAT;.CMD",
+            },
+          }),
+        ).toEqual({
+          provider: driver("nativePackageTool"),
+          packageName: "@example/native-package-tool",
+          update: {
+            command: "bun i -g @example/native-package-tool@latest",
+
+            executable: "bun",
+
+            args: ["i", "-g", "@example/native-package-tool@latest"],
+
+            lockKey: "bun-global",
+          },
+        });
+      }),
+  );
+
+  it.effect(
+    "switches package-managed providers to pnpm updates when the resolved binary lives in pnpm's global bin",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-pnpm-capabilities");
+        const pnpmHomeDir = path.join(tempDir, ".local", "share", "pnpm");
+        mkdirSync(pnpmHomeDir, { recursive: true });
+        const scopedPackageToolPath = path.join(pnpmHomeDir, "scoped-package-tool");
+        writeFileSync(scopedPackageToolPath, "#!/bin/sh\n");
+        chmodSync(scopedPackageToolPath, 0o755);
+
+        expect(
+          scopedPackageToolUpdate.resolve({
+            binaryPath: "scoped-package-tool",
+            platform: "darwin",
+            env: {
+              PATH: pnpmHomeDir,
+            },
+          }),
+        ).toEqual({
+          provider: driver("scopedPackageTool"),
+          packageName: "@example/scoped-package-tool",
+          update: {
+            command: "pnpm add -g @example/scoped-package-tool@latest",
+
+            executable: "pnpm",
+
+            args: ["add", "-g", "@example/scoped-package-tool@latest"],
+
+            lockKey: "pnpm-global",
+          },
+        });
+      }),
+  );
+
+  it("switches package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
+    expect(
+      packageToolUpdate.resolve({
+        binaryPath: "/opt/homebrew/bin/package-tool",
+        platform: "darwin",
+        env: {
+          PATH: "",
+        },
+      }),
+    ).toEqual({
+      provider: driver("packageTool"),
+      packageName: "@example/package-tool",
+      update: {
+        command: "brew upgrade package-tool",
+
+        executable: "brew",
+
+        args: ["upgrade", "package-tool"],
+
+        lockKey: "homebrew",
+      },
+    });
+  });
+
+  it.effect(
+    "switches native-package-tool to native updates when the binary resolves through the native installer",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-native-package-tool-native-capabilities");
+        const nativeBinDir = path.join(tempDir, ".local", "bin");
+        mkdirSync(nativeBinDir, { recursive: true });
+        const nativePackageToolPath = path.join(nativeBinDir, "native-package-tool");
+        writeFileSync(nativePackageToolPath, "#!/bin/sh\n");
+        chmodSync(nativePackageToolPath, 0o755);
+
+        expect(
+          nativePackageToolUpdate.resolve({
+            binaryPath: "native-package-tool",
+            platform: "darwin",
+            env: {
+              PATH: nativeBinDir,
+            },
+          }),
+        ).toEqual({
+          provider: driver("nativePackageTool"),
+          packageName: "@example/native-package-tool",
+          update: {
+            command: "native-package-tool update",
+
+            executable: "native-package-tool",
+
+            args: ["update"],
+
+            lockKey: "native-package-tool-native",
+          },
+        });
+      }),
+  );
+
+  it.effect(
+    "switches scoped-package-tool to native upgrades when the binary resolves through the standalone installer",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-scoped-package-tool-native-capabilities");
+        const nativeBinDir = path.join(tempDir, ".scoped-package-tool", "bin");
+        mkdirSync(nativeBinDir, { recursive: true });
+        const scopedPackageToolPath = path.join(nativeBinDir, "scoped-package-tool");
+        writeFileSync(scopedPackageToolPath, "#!/bin/sh\n");
+        chmodSync(scopedPackageToolPath, 0o755);
+
+        expect(
+          scopedPackageToolUpdate.resolve({
+            binaryPath: "scoped-package-tool",
+            platform: "darwin",
+            env: {
+              PATH: nativeBinDir,
+            },
+          }),
+        ).toEqual({
+          provider: driver("scopedPackageTool"),
+          packageName: "@example/scoped-package-tool",
+          update: {
+            command: "scoped-package-tool upgrade",
+
+            executable: "scoped-package-tool",
+
+            args: ["upgrade"],
+
+            lockKey: "scoped-package-tool-native",
+          },
+        });
+      }),
+  );
+
+  it("switches native-package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
+    expect(
+      nativePackageToolUpdate.resolve({
+        binaryPath: "/opt/homebrew/bin/native-package-tool",
+        platform: "darwin",
+        env: {
+          PATH: "",
+        },
+      }),
+    ).toEqual({
+      provider: driver("nativePackageTool"),
+      packageName: "@example/native-package-tool",
+      update: {
+        command: "brew upgrade native-package-tool",
+
+        executable: "brew",
+
+        args: ["upgrade", "native-package-tool"],
+
+        lockKey: "homebrew",
+      },
+    });
+  });
+
+  it("switches scoped-package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
+    expect(
+      scopedPackageToolUpdate.resolve({
+        binaryPath: "/opt/homebrew/bin/scoped-package-tool",
+        platform: "darwin",
+        env: {
+          PATH: "",
+        },
+      }),
+    ).toEqual({
+      provider: driver("scopedPackageTool"),
+      packageName: "@example/scoped-package-tool",
+      update: {
+        command: "brew upgrade example/tap/scoped-package-tool",
+
+        executable: "brew",
+
+        args: ["upgrade", "example/tap/scoped-package-tool"],
+
+        lockKey: "homebrew",
+      },
+    });
+  });
+
+  it.effect("keeps npm updates for binaries symlinked into npm's global node_modules tree", () =>
+    Effect.gen(function* () {
+      const tempDir = yield* makeTempDir("t3-npm-capabilities");
+      const binDir = path.join(tempDir, "bin");
+      const packageBinDir = path.join(
+        tempDir,
+        "lib",
+        "node_modules",
+        "@example",
+        "package-tool",
+        "bin",
+      );
+      mkdirSync(binDir, { recursive: true });
+      mkdirSync(packageBinDir, { recursive: true });
+      const packageBinPath = path.join(packageBinDir, "package-tool.js");
+      const symlinkPath = path.join(binDir, "package-tool");
+      writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
+      chmodSync(packageBinPath, 0o755);
+      symlinkSync(packageBinPath, symlinkPath);
+
+      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
+        binaryPath: symlinkPath,
+        platform: "darwin",
+        env: {
+          PATH: "",
+        },
+      }).pipe(Effect.provide(NodeServices.layer));
+
+      expect(capabilities).toEqual({
+        provider: driver("packageTool"),
+        packageName: "@example/package-tool",
+        update: {
+          command: "npm install -g @example/package-tool@latest",
+
+          executable: "npm",
+
+          args: ["install", "-g", "@example/package-tool@latest"],
+
+          lockKey: "npm-global",
+        },
+      });
+    }),
+  );
+
+  it.effect("uses Effect FileSystem realPath when detecting pnpm global symlinks", () =>
+    Effect.gen(function* () {
+      const tempDir = yield* makeTempDir("t3-pnpm-realpath-capabilities");
+      const binDir = path.join(tempDir, "bin");
+      const packageBinDir = path.join(
+        tempDir,
+        ".local",
+        "share",
+        "pnpm",
+        "global",
+        "5",
+        "node_modules",
+        "@example",
+        "package-tool",
+        "bin",
+      );
+      mkdirSync(binDir, { recursive: true });
+      mkdirSync(packageBinDir, { recursive: true });
+      const packageBinPath = path.join(packageBinDir, "package-tool.js");
+      const symlinkPath = path.join(binDir, "package-tool");
+      writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
+      chmodSync(packageBinPath, 0o755);
+      symlinkSync(packageBinPath, symlinkPath);
+
+      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
+        binaryPath: symlinkPath,
+        platform: "darwin",
+        env: {
+          PATH: "",
+        },
+      }).pipe(Effect.provide(NodeServices.layer));
+
+      expect(capabilities).toEqual({
+        provider: driver("packageTool"),
+        packageName: "@example/package-tool",
+        update: {
+          command: "pnpm add -g @example/package-tool@latest",
+
+          executable: "pnpm",
+
+          args: ["add", "-g", "@example/package-tool@latest"],
+
+          lockKey: "pnpm-global",
+        },
+      });
+    }),
+  );
+
+  it("disables one-click updates for explicit custom binary paths it cannot safely map", () => {
+    expect(
+      packageToolUpdate.resolve({
+        binaryPath: "C:\\Tools\\package-tool\\package-tool.exe",
+        platform: "win32",
+        env: {
+          PATH: "",
+          PATHEXT: ".COM;.EXE;.BAT;.CMD",
+        },
+      }),
+    ).toEqual({
+      provider: driver("packageTool"),
+      packageName: "@example/package-tool",
+      update: null,
+    });
+  });
+});
diff --git a/apps/server/src/provider/providerMaintenance.ts b/apps/server/src/provider/providerMaintenance.ts
new file mode 100644
index 00000000000..7f5e9d94dc5
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenance.ts
@@ -0,0 +1,475 @@
+import {
+  ProviderDriverKind,
+  type ServerProvider,
+  type ServerProviderVersionAdvisory,
+} from "@t3tools/contracts";
+import { compareSemverVersions } from "@t3tools/shared/semver";
+import { resolveCommandPath } from "@t3tools/shared/shell";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+
+const LATEST_VERSION_CACHE_TTL_MS = 60 * 60 * 1_000;
+const LATEST_VERSION_TIMEOUT_MS = 4_000;
+const PROVIDER_UPDATE_ACTION_TOAST_MESSAGE = "Install the update now or review provider settings.";
+
+export interface ProviderMaintenanceCapabilities {
+  readonly provider: ProviderDriverKind;
+  readonly packageName: string | null;
+  readonly update: ProviderMaintenanceCommandAction | null;
+}
+
+export interface ProviderMaintenanceCommandAction {
+  readonly command: string;
+  readonly executable: string;
+  readonly args: ReadonlyArray<string>;
+  readonly lockKey: string;
+}
+
+export interface ProviderMaintenanceCapabilityResolutionOptions {
+  readonly binaryPath?: string | null;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly platform?: NodeJS.Platform;
+  readonly realCommandPath?: string | null;
+}
+
+export interface ProviderMaintenanceCapabilitiesResolver {
+  readonly resolve: (
+    options?: ProviderMaintenanceCapabilityResolutionOptions,
+  ) => ProviderMaintenanceCapabilities;
+}
+
+export interface PackageManagedProviderMaintenanceDefinition {
+  readonly provider: ProviderDriverKind;
+  readonly npmPackageName: string;
+  readonly homebrewFormula: string | null;
+  readonly nativeUpdate: {
+    readonly executable: string;
+    readonly args: ReadonlyArray<string>;
+    readonly lockKey: string;
+    readonly isCommandPath: (commandPath: string) => boolean;
+  } | null;
+}
+
+interface LatestVersionCacheEntry {
+  readonly expiresAt: number;
+  readonly version: string | null;
+}
+
+const latestVersionCache = new Map<string, LatestVersionCacheEntry>();
+const NpmLatestVersionResponse = Schema.Struct({
+  version: Schema.optional(Schema.String),
+});
+
+export function clearLatestProviderVersionCacheForTests(): void {
+  latestVersionCache.clear();
+}
+
+function nonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function makeProviderMaintenanceCapabilities(input: {
+  readonly provider: ProviderDriverKind;
+  readonly packageName: string | null;
+  readonly updateExecutable: string | null;
+  readonly updateArgs: ReadonlyArray<string>;
+  readonly updateLockKey: string | null;
+}): ProviderMaintenanceCapabilities {
+  const update =
+    input.updateExecutable === null || input.updateLockKey === null
+      ? null
+      : {
+          command: [input.updateExecutable, ...input.updateArgs].join(" "),
+          executable: input.updateExecutable,
+          args: input.updateArgs,
+          lockKey: input.updateLockKey,
+        };
+  return {
+    provider: input.provider,
+    packageName: input.packageName,
+    update,
+  };
+}
+
+export function makeManualOnlyProviderMaintenanceCapabilities(input: {
+  readonly provider: ProviderDriverKind;
+  readonly packageName: string | null;
+}): ProviderMaintenanceCapabilities {
+  return makeProviderMaintenanceCapabilities({
+    provider: input.provider,
+    packageName: input.packageName,
+    updateExecutable: null,
+    updateArgs: [],
+    updateLockKey: null,
+  });
+}
+
+function makeNpmGlobalProviderMaintenanceCapabilities(
+  definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+  return makeProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+    updateExecutable: "npm",
+    updateArgs: ["install", "-g", `${definition.npmPackageName}@latest`],
+    updateLockKey: "npm-global",
+  });
+}
+
+function makeBunGlobalProviderMaintenanceCapabilities(
+  definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+  return makeProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+    updateExecutable: "bun",
+    updateArgs: ["i", "-g", `${definition.npmPackageName}@latest`],
+    updateLockKey: "bun-global",
+  });
+}
+
+function makePnpmGlobalProviderMaintenanceCapabilities(
+  definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+  return makeProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+    updateExecutable: "pnpm",
+    updateArgs: ["add", "-g", `${definition.npmPackageName}@latest`],
+    updateLockKey: "pnpm-global",
+  });
+}
+
+function makeVitePlusGlobalProviderMaintenanceCapabilities(
+  definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+  return makeProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+    updateExecutable: "vp",
+    updateArgs: ["i", "-g", definition.npmPackageName],
+    updateLockKey: "vite-plus-global",
+  });
+}
+
+function makeHomebrewProviderMaintenanceCapabilities(
+  definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities {
+  if (!definition.homebrewFormula) {
+    return makeManualOnlyProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      packageName: definition.npmPackageName,
+    });
+  }
+
+  return makeProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+    updateExecutable: "brew",
+    updateArgs: ["upgrade", definition.homebrewFormula],
+    updateLockKey: "homebrew",
+  });
+}
+
+function makeNativeProviderMaintenanceCapabilities(
+  definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilities | null {
+  if (!definition.nativeUpdate) {
+    return null;
+  }
+
+  return makeProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+    updateExecutable: definition.nativeUpdate.executable,
+    updateArgs: definition.nativeUpdate.args,
+    updateLockKey: definition.nativeUpdate.lockKey,
+  });
+}
+
+export function hasPathSeparator(value: string): boolean {
+  return value.includes("/") || value.includes("\\");
+}
+
+export function normalizeCommandPath(commandPath: string): string {
+  return commandPath.replaceAll("\\", "/").toLowerCase();
+}
+
+function isBunGlobalCommandPath(commandPath: string): boolean {
+  return normalizeCommandPath(commandPath).includes("/.bun/bin/");
+}
+
+function isVitePlusGlobalCommandPath(commandPath: string): boolean {
+  return normalizeCommandPath(commandPath).includes("/.vite-plus/bin/");
+}
+
+function isPnpmGlobalCommandPath(commandPath: string): boolean {
+  const normalized = normalizeCommandPath(commandPath);
+  return (
+    normalized.includes("/.local/share/pnpm/") ||
+    normalized.includes("/library/pnpm/") ||
+    normalized.includes("/local/share/pnpm/") ||
+    normalized.includes("/appdata/local/pnpm/") ||
+    normalized.includes("/pnpm/global/")
+  );
+}
+
+function isNpmGlobalCommandPath(commandPath: string): boolean {
+  const normalized = normalizeCommandPath(commandPath);
+  return (
+    normalized.includes("/node_modules/.bin/") ||
+    normalized.includes("/lib/node_modules/") ||
+    normalized.includes("/npm/node_modules/")
+  );
+}
+
+function isHomebrewCommandPath(commandPath: string): boolean {
+  const normalized = normalizeCommandPath(commandPath);
+  return (
+    normalized.includes("/opt/homebrew/cellar/") ||
+    normalized.includes("/usr/local/cellar/") ||
+    normalized.includes("/homebrew/cellar/") ||
+    normalized.includes("/opt/homebrew/caskroom/") ||
+    normalized.includes("/usr/local/caskroom/") ||
+    normalized.includes("/homebrew/caskroom/") ||
+    normalized.startsWith("/opt/homebrew/bin/") ||
+    normalized.startsWith("/usr/local/bin/")
+  );
+}
+
+export function resolvePackageManagedProviderMaintenance(
+  definition: PackageManagedProviderMaintenanceDefinition,
+  options?: ProviderMaintenanceCapabilityResolutionOptions,
+): ProviderMaintenanceCapabilities {
+  const binaryPath = nonEmptyString(options?.binaryPath);
+  if (!binaryPath) {
+    return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+  }
+
+  const resolvedCommandPath =
+    resolveCommandPath(binaryPath, {
+      ...(options?.platform ? { platform: options.platform } : {}),
+      ...(options?.env ? { env: options.env } : {}),
+    }) ?? (hasPathSeparator(binaryPath) ? binaryPath : null);
+
+  if (resolvedCommandPath) {
+    const commandPaths = [
+      resolvedCommandPath,
+      ...(options?.realCommandPath ? [options.realCommandPath] : []),
+    ];
+
+    const nativeUpdate = definition.nativeUpdate;
+    if (
+      nativeUpdate &&
+      commandPaths.some((commandPath) => nativeUpdate.isCommandPath(commandPath))
+    ) {
+      return (
+        makeNativeProviderMaintenanceCapabilities(definition) ??
+        makeNpmGlobalProviderMaintenanceCapabilities(definition)
+      );
+    }
+    if (commandPaths.some(isVitePlusGlobalCommandPath)) {
+      return makeVitePlusGlobalProviderMaintenanceCapabilities(definition);
+    }
+    if (commandPaths.some(isBunGlobalCommandPath)) {
+      return makeBunGlobalProviderMaintenanceCapabilities(definition);
+    }
+    if (commandPaths.some(isPnpmGlobalCommandPath)) {
+      return makePnpmGlobalProviderMaintenanceCapabilities(definition);
+    }
+    if (commandPaths.some(isNpmGlobalCommandPath)) {
+      return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+    }
+    if (commandPaths.some(isHomebrewCommandPath)) {
+      return makeHomebrewProviderMaintenanceCapabilities(definition);
+    }
+  }
+
+  if (!hasPathSeparator(binaryPath)) {
+    return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+  }
+
+  return makeManualOnlyProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+  });
+}
+
+export function makePackageManagedProviderMaintenanceResolver(
+  definition: PackageManagedProviderMaintenanceDefinition,
+): ProviderMaintenanceCapabilitiesResolver {
+  return {
+    resolve: (options) => resolvePackageManagedProviderMaintenance(definition, options),
+  };
+}
+
+export function makeStaticProviderMaintenanceResolver(
+  capabilities: ProviderMaintenanceCapabilities,
+): ProviderMaintenanceCapabilitiesResolver {
+  return {
+    resolve: () => capabilities,
+  };
+}
+
+function makeManualProviderMaintenanceCapabilities(
+  provider: ProviderDriverKind,
+): ProviderMaintenanceCapabilities {
+  return makeManualOnlyProviderMaintenanceCapabilities({
+    provider,
+    packageName: null,
+  });
+}
+
+export const resolveProviderMaintenanceCapabilitiesEffect = Effect.fn(
+  "resolveProviderMaintenanceCapabilitiesEffect",
+)(function* (
+  resolver: ProviderMaintenanceCapabilitiesResolver,
+  options?: Omit<ProviderMaintenanceCapabilityResolutionOptions, "realCommandPath">,
+) {
+  const binaryPath = nonEmptyString(options?.binaryPath);
+  if (!binaryPath) {
+    return resolver.resolve(options);
+  }
+
+  const resolvedCommandPath =
+    resolveCommandPath(binaryPath, {
+      ...(options?.platform ? { platform: options.platform } : {}),
+      ...(options?.env ? { env: options.env } : {}),
+    }) ?? (hasPathSeparator(binaryPath) ? binaryPath : null);
+  if (!resolvedCommandPath) {
+    return resolver.resolve(options);
+  }
+
+  const fileSystem = yield* FileSystem.FileSystem;
+  const realCommandPath = yield* fileSystem
+    .realPath(resolvedCommandPath)
+    .pipe(Effect.catch(() => Effect.succeed(resolvedCommandPath)));
+  return resolver.resolve({
+    ...options,
+    realCommandPath,
+  });
+});
+
+function deriveVersionAdvisory(input: {
+  readonly currentVersion: string | null;
+  readonly latestVersion: string | null;
+}): Pick<ServerProviderVersionAdvisory, "status" | "message"> {
+  if (!input.currentVersion) {
+    return { status: "unknown", message: null };
+  }
+  if (!input.latestVersion) {
+    return { status: "unknown", message: null };
+  }
+  if (compareSemverVersions(input.currentVersion, input.latestVersion) < 0) {
+    return {
+      status: "behind_latest",
+      message: PROVIDER_UPDATE_ACTION_TOAST_MESSAGE,
+    };
+  }
+  return { status: "current", message: null };
+}
+
+export function createProviderVersionAdvisory(input: {
+  readonly driver: ProviderDriverKind;
+  readonly currentVersion: string | null;
+  readonly latestVersion?: string | null;
+  readonly checkedAt?: string | null;
+  readonly maintenanceCapabilities?: ProviderMaintenanceCapabilities;
+}): ServerProviderVersionAdvisory {
+  const capabilities =
+    input.maintenanceCapabilities ?? makeManualProviderMaintenanceCapabilities(input.driver);
+  const latestVersion = input.latestVersion ?? null;
+  const advisory = deriveVersionAdvisory({
+    currentVersion: input.currentVersion,
+    latestVersion,
+  });
+
+  return {
+    status: advisory.status,
+    currentVersion: input.currentVersion,
+    latestVersion,
+    updateCommand: capabilities.update?.command ?? null,
+    canUpdate: capabilities.update !== null,
+    checkedAt: input.checkedAt ?? null,
+    message: advisory.message,
+  };
+}
+
+const fetchNpmLatestVersion = Effect.fn("fetchNpmLatestVersion")(function* (packageName: string) {
+  const client = yield* HttpClient.HttpClient;
+  const request = HttpClientRequest.get(
+    `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`,
+  ).pipe(HttpClientRequest.setHeader("accept", "application/json"));
+  const response = yield* client.execute(request).pipe(
+    Effect.timeoutOption(LATEST_VERSION_TIMEOUT_MS),
+    Effect.catch(() => Effect.succeed(Option.none())),
+  );
+  if (Option.isNone(response)) {
+    return null;
+  }
+  const httpResponse = response.value;
+  if (httpResponse.status < 200 || httpResponse.status >= 300) {
+    return null;
+  }
+  const payload = yield* httpResponse.json.pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(NpmLatestVersionResponse)),
+    Effect.catch(() => Effect.succeed(null)),
+  );
+  return payload ? nonEmptyString(payload.version) : null;
+});
+
+export const resolveLatestProviderVersion = Effect.fn("resolveLatestProviderVersion")(function* (
+  maintenanceCapabilities: ProviderMaintenanceCapabilities,
+) {
+  const packageName = maintenanceCapabilities.packageName;
+  if (!packageName) {
+    return null;
+  }
+
+  const cached = latestVersionCache.get(packageName);
+  const now = DateTime.toEpochMillis(yield* DateTime.now);
+  if (cached && cached.expiresAt > now) {
+    return cached.version;
+  }
+
+  const version = yield* fetchNpmLatestVersion(packageName);
+  latestVersionCache.set(packageName, {
+    expiresAt: now + LATEST_VERSION_CACHE_TTL_MS,
+    version,
+  });
+  return version;
+});
+
+export const enrichProviderSnapshotWithVersionAdvisory = Effect.fn(
+  "enrichProviderSnapshotWithVersionAdvisory",
+)(function* (snapshot: ServerProvider, maintenanceCapabilities?: ProviderMaintenanceCapabilities) {
+  const capabilities =
+    maintenanceCapabilities ?? makeManualProviderMaintenanceCapabilities(snapshot.driver);
+  if (!snapshot.enabled || !snapshot.installed || !snapshot.version) {
+    return {
+      ...snapshot,
+      versionAdvisory: createProviderVersionAdvisory({
+        driver: snapshot.driver,
+        currentVersion: snapshot.version,
+        checkedAt: snapshot.checkedAt,
+        maintenanceCapabilities: capabilities,
+      }),
+    };
+  }
+
+  const latestVersion = yield* resolveLatestProviderVersion(capabilities);
+  return {
+    ...snapshot,
+    versionAdvisory: createProviderVersionAdvisory({
+      driver: snapshot.driver,
+      currentVersion: snapshot.version,
+      latestVersion,
+      checkedAt: DateTime.formatIso(yield* DateTime.now),
+      maintenanceCapabilities: capabilities,
+    }),
+  };
+});
diff --git a/apps/server/src/provider/providerMaintenanceCommandCoordinator.ts b/apps/server/src/provider/providerMaintenanceCommandCoordinator.ts
new file mode 100644
index 00000000000..7c456c3c484
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenanceCommandCoordinator.ts
@@ -0,0 +1,80 @@
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
+
+export interface ProviderMaintenanceCommandCoordinatorShape<E> {
+  readonly withCommandLock: <A, R>(input: {
+    readonly targetKey: string;
+    readonly lockKey: string;
+    readonly onQueued?: Effect.Effect<void, E, R>;
+    readonly run: Effect.Effect<A, E, R>;
+  }) => Effect.Effect<A, E, R>;
+}
+
+export const makeProviderMaintenanceCommandCoordinator = Effect.fn(
+  "makeProviderMaintenanceCommandCoordinator",
+)(function* <E>(input: { readonly makeAlreadyRunningError: (targetKey: string) => E }) {
+  const runningTargetsRef = yield* Ref.make<ReadonlySet<string>>(new Set());
+  const locksRef = yield* Ref.make<ReadonlyMap<string, Semaphore.Semaphore>>(new Map());
+
+  const acquireTarget = Effect.fn("acquireTarget")(function* (targetKey: string) {
+    return yield* Ref.modify(runningTargetsRef, (runningTargets) => {
+      if (runningTargets.has(targetKey)) {
+        return [false, runningTargets] as const;
+      }
+      const next = new Set(runningTargets);
+      next.add(targetKey);
+      return [true, next] as const;
+    });
+  });
+
+  const releaseTarget = (targetKey: string) =>
+    Ref.update(runningTargetsRef, (runningTargets) => {
+      const next = new Set(runningTargets);
+      next.delete(targetKey);
+      return next;
+    });
+
+  const getLock = Effect.fn("getProviderMaintenanceCommandLock")(function* (lockKey: string) {
+    const existing = (yield* Ref.get(locksRef)).get(lockKey);
+    if (existing) {
+      return existing;
+    }
+
+    const lock = yield* Semaphore.make(1);
+    return yield* Ref.modify(locksRef, (locks) => {
+      const current = locks.get(lockKey);
+      if (current) {
+        return [current, locks] as const;
+      }
+      const next = new Map(locks);
+      next.set(lockKey, lock);
+      return [lock, next] as const;
+    });
+  });
+
+  const withCommandLock: ProviderMaintenanceCommandCoordinatorShape<E>["withCommandLock"] = ({
+    targetKey,
+    lockKey,
+    onQueued,
+    run,
+  }) =>
+    Effect.gen(function* () {
+      const acquired = yield* acquireTarget(targetKey);
+      if (!acquired) {
+        return yield* Effect.fail(input.makeAlreadyRunningError(targetKey));
+      }
+
+      return yield* Effect.gen(function* () {
+        const lock = yield* getLock(lockKey);
+        if (onQueued) {
+          yield* onQueued;
+        }
+        return yield* lock.withPermits(1)(run);
+      }).pipe(Effect.ensuring(releaseTarget(targetKey)));
+    });
+
+  return {
+    withCommandLock,
+  } satisfies ProviderMaintenanceCommandCoordinatorShape<E>;
+});
diff --git a/apps/server/src/provider/providerMaintenanceRunner.test.ts b/apps/server/src/provider/providerMaintenanceRunner.test.ts
new file mode 100644
index 00000000000..5f5f975a4e3
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenanceRunner.test.ts
@@ -0,0 +1,649 @@
+import { afterEach, describe, it, assert } from "@effect/vitest";
+import {
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+  type ServerProviderUpdateState,
+} from "@t3tools/contracts";
+import { ServerProviderUpdateError } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { ProviderRegistry, type ProviderRegistryShape } from "./Services/ProviderRegistry.ts";
+import * as ProviderMaintenanceRunner from "./providerMaintenanceRunner.ts";
+import {
+  clearLatestProviderVersionCacheForTests,
+  makeProviderMaintenanceCapabilities,
+  type ProviderMaintenanceCapabilities,
+} from "./providerMaintenance.ts";
+const isServerProviderUpdateError = Schema.is(ServerProviderUpdateError);
+
+const CODEX_DRIVER = ProviderDriverKind.make("codex");
+const CURSOR_DRIVER = ProviderDriverKind.make("cursor");
+const OPENCODE_DRIVER = ProviderDriverKind.make("opencode");
+const CODEX_INSTANCE_ID = ProviderInstanceId.make("codex");
+const CURSOR_INSTANCE_ID = ProviderInstanceId.make("cursor");
+const OPENCODE_INSTANCE_ID = ProviderInstanceId.make("opencode");
+const encoder = new TextEncoder();
+
+afterEach(() => {
+  clearLatestProviderVersionCacheForTests();
+});
+
+function lifecycleFor(provider: ProviderDriverKind): ProviderMaintenanceCapabilities {
+  if (provider === CURSOR_DRIVER) {
+    return makeProviderMaintenanceCapabilities({
+      provider,
+      packageName: null,
+      updateExecutable: "agent",
+      updateArgs: ["update"],
+      updateLockKey: "cursor-agent",
+    });
+  }
+  return makeProviderMaintenanceCapabilities({
+    provider,
+    packageName: provider === OPENCODE_DRIVER ? "opencode-ai" : "@openai/codex",
+    updateExecutable: "npm",
+    updateArgs:
+      provider === OPENCODE_DRIVER
+        ? ["install", "-g", "opencode-ai@latest"]
+        : ["install", "-g", "@openai/codex@latest"],
+    updateLockKey: "npm-global",
+  });
+}
+
+const baseProvider: ServerProvider = {
+  instanceId: CODEX_INSTANCE_ID,
+  driver: CODEX_DRIVER,
+  enabled: true,
+  installed: true,
+  version: null,
+  status: "ready",
+  auth: { status: "authenticated" },
+  checkedAt: "2026-04-10T00:00:00.000Z",
+  models: [],
+  slashCommands: [],
+  skills: [],
+};
+
+const baseCursorProvider: ServerProvider = {
+  ...baseProvider,
+  instanceId: CURSOR_INSTANCE_ID,
+  driver: CURSOR_DRIVER,
+};
+
+const baseOpenCodeProvider: ServerProvider = {
+  ...baseProvider,
+  instanceId: OPENCODE_INSTANCE_ID,
+  driver: OPENCODE_DRIVER,
+};
+
+const latestVersionHttpClient = (version: string) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.succeed(
+        HttpClientResponse.fromWeb(
+          request,
+          Response.json({ version }, { headers: { "content-type": "application/json" } }),
+        ),
+      ),
+    ),
+  );
+
+function mockHandle(result: {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly code?: number;
+  readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+}) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: result.exitCode ?? Effect.succeed(ChildProcessSpawner.ExitCode(result.code ?? 0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: Sink.drain,
+    stdout: Stream.make(encoder.encode(result.stdout ?? "")),
+    stderr: Stream.make(encoder.encode(result.stderr ?? "")),
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+function mockSpawnerLayer(
+  handler: (
+    command: string,
+    args: ReadonlyArray<string>,
+  ) => {
+    readonly stdout?: string;
+    readonly stderr?: string;
+    readonly code?: number;
+    readonly exitCode?: Effect.Effect<ChildProcessSpawner.ExitCode>;
+  },
+) {
+  return Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make((command) => {
+      const childProcess = command as unknown as {
+        readonly command: string;
+        readonly args: ReadonlyArray<string>;
+      };
+      return Effect.succeed(mockHandle(handler(childProcess.command, childProcess.args)));
+    }),
+  );
+}
+
+function makeRegistry(
+  initialProviders: ServerProvider | ReadonlyArray<ServerProvider> = baseProvider,
+) {
+  return Effect.gen(function* () {
+    const providersRef = yield* Ref.make<ReadonlyArray<ServerProvider>>(
+      Array.isArray(initialProviders) ? initialProviders : [initialProviders],
+    );
+    const updateStatesRef = yield* Ref.make<ReadonlyArray<ServerProviderUpdateState>>([]);
+
+    const setProviderMaintenanceActionState = Effect.fn(
+      "providerMaintenanceRunner.test.setProviderMaintenanceActionState",
+    )(function* (input: {
+      readonly instanceId: ProviderInstanceId;
+      readonly action: "update";
+      readonly state: ServerProviderUpdateState | null;
+    }) {
+      const updateState = input.state;
+      if (updateState) {
+        yield* Ref.update(updateStatesRef, (states) => [...states, updateState]);
+      }
+      return yield* Ref.updateAndGet(providersRef, (providers) =>
+        providers.map((candidate) => {
+          if (candidate.instanceId !== input.instanceId) {
+            return candidate;
+          }
+          if (!updateState) {
+            const { updateState: _updateState, ...providerWithoutUpdateState } = candidate;
+            return providerWithoutUpdateState;
+          }
+          return {
+            ...candidate,
+            updateState,
+          };
+        }),
+      );
+    });
+
+    const registry: ProviderRegistryShape = {
+      getProviders: Ref.get(providersRef),
+      refresh: () => Ref.get(providersRef),
+      refreshInstance: () => Ref.get(providersRef),
+      getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+        Effect.succeed(lifecycleFor(provider)),
+      setProviderMaintenanceActionState,
+      streamChanges: Stream.empty,
+    };
+
+    return {
+      registry,
+      updateStatesRef,
+    };
+  });
+}
+
+const makeTestRunner = (registry: ProviderRegistryShape) =>
+  Effect.service(ProviderMaintenanceRunner.ProviderMaintenanceRunner).pipe(
+    Effect.provide(
+      ProviderMaintenanceRunner.layer.pipe(
+        Layer.provide(Layer.succeed(ProviderRegistry, registry)),
+      ),
+    ),
+  );
+
+describe("providerMaintenanceRunner", () => {
+  it.effect("runs the allowlisted provider update command and records success", () => {
+    const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+    return Effect.gen(function* () {
+      const { registry, updateStatesRef } = yield* makeRegistry(baseCursorProvider);
+      const updater = yield* makeTestRunner(registry);
+
+      const result = yield* updater.updateProvider(CURSOR_DRIVER);
+      assert.deepStrictEqual(calls, [
+        {
+          command: "agent",
+          args: ["update"],
+        },
+      ]);
+      assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+      assert.deepStrictEqual(
+        (yield* Ref.get(updateStatesRef)).map((state) => state.status),
+        ["queued", "running", "succeeded"],
+      );
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer((command, args) => {
+            calls.push({ command, args });
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect("uses the resolved provider capabilities when choosing the update executable", () => {
+    const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+    return Effect.gen(function* () {
+      const { registry } = yield* makeRegistry({
+        ...baseProvider,
+        versionAdvisory: {
+          status: "behind_latest",
+          currentVersion: "2.0.14",
+          latestVersion: "2.1.123",
+          updateCommand: "bun i -g @anthropic-ai/claude-code@latest",
+          canUpdate: true,
+          checkedAt: "2026-04-30T12:00:00.000Z",
+          message: "Update available.",
+        },
+      });
+      const updater = yield* makeTestRunner({
+        ...registry,
+        getProviderMaintenanceCapabilitiesForInstance: () =>
+          Effect.succeed(
+            makeProviderMaintenanceCapabilities({
+              provider: CODEX_DRIVER,
+              packageName: "@openai/codex",
+              updateExecutable: "bun",
+              updateArgs: ["i", "-g", "@openai/codex@latest"],
+              updateLockKey: "bun-global",
+            }),
+          ),
+      });
+
+      yield* updater.updateProvider(CODEX_DRIVER);
+      assert.deepStrictEqual(calls, [
+        {
+          command: "bun",
+          args: ["i", "-g", "@openai/codex@latest"],
+        },
+      ]);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer((command, args) => {
+            calls.push({ command, args });
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect(
+    "runs update commands through Effect ChildProcess when no test runner is injected",
+    () => {
+      const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+      return Effect.gen(function* () {
+        const { registry } = yield* makeRegistry(baseProvider);
+        const runner = yield* makeTestRunner(registry);
+
+        const result = yield* runner.updateProvider(CODEX_DRIVER);
+
+        assert.deepStrictEqual(calls, [
+          {
+            command: "npm",
+            args: ["install", "-g", "@openai/codex@latest"],
+          },
+        ]);
+        assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+      }).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            latestVersionHttpClient("0.0.0"),
+            mockSpawnerLayer((command, args) => {
+              calls.push({ command, args });
+              return { stdout: "updated" };
+            }),
+          ),
+        ),
+      );
+    },
+  );
+
+  it.effect("updates a single provider instance without touching sibling instances", () => {
+    const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+    return Effect.gen(function* () {
+      const personalInstanceId = ProviderInstanceId.make("codex_personal");
+      const workInstanceId = ProviderInstanceId.make("codex_work");
+      const refreshedInstanceIds: Array<ProviderInstanceId> = [];
+      const { registry } = yield* makeRegistry([
+        {
+          ...baseProvider,
+          instanceId: personalInstanceId,
+          version: "0.124.0-alpha.3",
+        },
+        {
+          ...baseProvider,
+          instanceId: workInstanceId,
+          version: "0.124.0-alpha.3",
+        },
+      ]);
+      const updater = yield* makeTestRunner({
+        ...registry,
+        getProviderMaintenanceCapabilitiesForInstance: (instanceId, provider) =>
+          Effect.succeed(
+            makeProviderMaintenanceCapabilities({
+              provider,
+              packageName: "@openai/codex-instance-test",
+              updateExecutable: "vp",
+              updateArgs: ["i", "-g", "@openai/codex"],
+              updateLockKey: "vite-plus-global",
+            }),
+          ).pipe(
+            Effect.tap(() => Effect.sync(() => assert.strictEqual(instanceId, personalInstanceId))),
+          ),
+        refreshInstance: (instanceId) =>
+          registry.refreshInstance(instanceId).pipe(
+            Effect.tap(() =>
+              Effect.sync(() => {
+                refreshedInstanceIds.push(instanceId);
+              }),
+            ),
+          ),
+      });
+
+      const result = yield* updater.updateProvider({
+        provider: CODEX_DRIVER,
+        instanceId: personalInstanceId,
+      });
+
+      assert.deepStrictEqual(calls, [
+        {
+          command: "vp",
+          args: ["i", "-g", "@openai/codex"],
+        },
+      ]);
+      assert.deepStrictEqual(refreshedInstanceIds, [personalInstanceId]);
+      assert.strictEqual(result.providers[0]?.instanceId, personalInstanceId);
+      assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+      assert.strictEqual(result.providers[1]?.instanceId, workInstanceId);
+      assert.strictEqual(result.providers[1]?.updateState, undefined);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          latestVersionHttpClient("0.124.0-alpha.3"),
+          mockSpawnerLayer((command, args) => {
+            calls.push({ command, args });
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect("records command failure output in provider update state", () =>
+    Effect.gen(function* () {
+      const { registry } = yield* makeRegistry();
+      const updater = yield* makeTestRunner(registry);
+
+      const result = yield* updater.updateProvider(CODEX_DRIVER);
+      const updateState = result.providers[0]?.updateState;
+
+      assert.strictEqual(updateState?.status, "failed");
+      assert.strictEqual(updateState?.message, "Update command exited with code 1.");
+      assert.include(updateState?.output ?? "", "permission denied");
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer(() => ({ stderr: "permission denied", code: 1 })),
+        ),
+      ),
+    ),
+  );
+
+  it.effect(
+    "marks successful commands as unchanged when the refreshed provider is still outdated",
+    () =>
+      Effect.gen(function* () {
+        const { registry } = yield* makeRegistry({
+          ...baseProvider,
+          installed: true,
+          version: "0.1.0",
+        });
+        const updater = yield* makeTestRunner(registry);
+
+        const result = yield* updater.updateProvider(CODEX_DRIVER);
+
+        assert.strictEqual(result.providers[0]?.updateState?.status, "unchanged");
+        assert.include(result.providers[0]?.updateState?.message ?? "", "still detects");
+      }).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            latestVersionHttpClient("9.9.9"),
+            mockSpawnerLayer(() => ({ stdout: "updated" })),
+          ),
+        ),
+      ),
+  );
+
+  it.effect("prevents concurrent updates for the same provider", () => {
+    const startedLatch: { resolve: () => void } = { resolve: () => {} };
+    const releaseLatch: { resolve: () => void } = { resolve: () => {} };
+    const started = new Promise<void>((resolve) => {
+      startedLatch.resolve = resolve;
+    });
+    const release = new Promise<void>((resolve) => {
+      releaseLatch.resolve = resolve;
+    });
+    return Effect.gen(function* () {
+      const { registry } = yield* makeRegistry();
+      const updater = yield* makeTestRunner(registry);
+
+      const first = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.forkScoped);
+      yield* Effect.promise(() => started);
+
+      const second = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.exit);
+      assert.strictEqual(Exit.isFailure(second), true);
+      if (Exit.isFailure(second)) {
+        const error = Cause.squash(second.cause);
+        assert.strictEqual(isServerProviderUpdateError(error), true);
+        if (isServerProviderUpdateError(error)) {
+          assert.include(error.reason, "already running");
+        }
+      }
+
+      releaseLatch.resolve();
+      yield* Fiber.join(first);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer(() => {
+            startedLatch.resolve();
+            return {
+              stdout: "updated",
+              exitCode: Effect.promise(() => release).pipe(
+                Effect.as(ChildProcessSpawner.ExitCode(0)),
+              ),
+            };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect("serializes different providers that share the same update lock key", () => {
+    const firstStartedLatch: { resolve: () => void } = { resolve: () => {} };
+    const releaseFirstLatch: { resolve: () => void } = { resolve: () => {} };
+    const firstStarted = new Promise<void>((resolve) => {
+      firstStartedLatch.resolve = resolve;
+    });
+    const releaseFirst = new Promise<void>((resolve) => {
+      releaseFirstLatch.resolve = resolve;
+    });
+    const calls: Array<string> = [];
+    return Effect.gen(function* () {
+      const { registry } = yield* makeRegistry([baseProvider, baseOpenCodeProvider]);
+      const updater = yield* makeTestRunner({
+        ...registry,
+        getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+          Effect.succeed(
+            makeProviderMaintenanceCapabilities({
+              provider,
+              packageName: provider === OPENCODE_DRIVER ? "opencode-ai" : "@openai/codex",
+              updateExecutable: "npm",
+              updateArgs:
+                provider === OPENCODE_DRIVER
+                  ? ["install", "-g", "opencode-ai@latest"]
+                  : ["install", "-g", "@openai/codex@latest"],
+              updateLockKey: "npm-global",
+            }),
+          ),
+      });
+
+      const first = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.forkScoped);
+      yield* Effect.promise(() => firstStarted);
+
+      const second = yield* updater.updateProvider(OPENCODE_DRIVER).pipe(Effect.forkScoped);
+      let providersWhileQueued: ReadonlyArray<ServerProvider> = [];
+      for (let attempt = 0; attempt < 20; attempt += 1) {
+        providersWhileQueued = yield* registry.getProviders;
+        const queuedStatus = providersWhileQueued.find(
+          (provider) => provider.instanceId === OPENCODE_INSTANCE_ID,
+        )?.updateState?.status;
+        if (queuedStatus === "queued") {
+          break;
+        }
+        yield* Effect.yieldNow;
+      }
+      assert.deepStrictEqual(calls, ["install -g @openai/codex@latest"]);
+      assert.strictEqual(
+        providersWhileQueued.find((provider) => provider.instanceId === OPENCODE_INSTANCE_ID)
+          ?.updateState?.status,
+        "queued",
+      );
+
+      releaseFirstLatch.resolve();
+      yield* Fiber.join(first);
+      yield* Fiber.join(second);
+      assert.deepStrictEqual(calls, [
+        "install -g @openai/codex@latest",
+        "install -g opencode-ai@latest",
+      ]);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer((_command, args) => {
+            calls.push(args.join(" "));
+            if (calls.length === 1) {
+              firstStartedLatch.resolve();
+              return {
+                stdout: "updated",
+                exitCode: Effect.promise(() => releaseFirst).pipe(
+                  Effect.as(ChildProcessSpawner.ExitCode(0)),
+                ),
+              };
+            }
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect("accepts arbitrary driver-provided update lock keys", () => {
+    const calls: Array<string> = [];
+    return Effect.gen(function* () {
+      const { registry } = yield* makeRegistry(baseProvider);
+      const updater = yield* makeTestRunner({
+        ...registry,
+        getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+          Effect.succeed(
+            makeProviderMaintenanceCapabilities({
+              provider,
+              packageName: "@openai/codex",
+              updateExecutable: "npm",
+              updateArgs: ["install", "-g", "@openai/codex@latest"],
+              updateLockKey: "unknown-lock-key",
+            }),
+          ),
+      });
+
+      const result = yield* updater.updateProvider(CODEX_DRIVER);
+      assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+      assert.deepStrictEqual(calls, ["install -g @openai/codex@latest"]);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer((_command, args) => {
+            calls.push(args.join(" "));
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect(
+    "releases the running-provider marker when interrupted after queuing but before the lock run starts",
+    () =>
+      Effect.gen(function* () {
+        const { registry } = yield* makeRegistry(baseProvider);
+        let blockQueuedState = true;
+        const queuedStateWrittenLatch: { resolve: () => void } = { resolve: () => {} };
+        const releaseQueuedStateLatch: { resolve: () => void } = { resolve: () => {} };
+        const queuedStateWritten = new Promise<void>((resolve) => {
+          queuedStateWrittenLatch.resolve = resolve;
+        });
+        const releaseQueuedState = new Promise<void>((resolve) => {
+          releaseQueuedStateLatch.resolve = resolve;
+        });
+
+        const updater = yield* makeTestRunner({
+          ...registry,
+          setProviderMaintenanceActionState: Effect.fn(
+            "providerMaintenanceRunner.test.blockQueuedState",
+          )(function* (input) {
+            const providers = yield* registry.setProviderMaintenanceActionState(input);
+            if (input.state?.status === "queued" && blockQueuedState) {
+              queuedStateWrittenLatch.resolve();
+              yield* Effect.promise(() => releaseQueuedState);
+            }
+            return providers;
+          }),
+        });
+
+        const first = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.forkScoped);
+        yield* Effect.promise(() => queuedStateWritten);
+        blockQueuedState = false;
+
+        yield* Fiber.interrupt(first);
+        releaseQueuedStateLatch.resolve();
+
+        const second = yield* updater.updateProvider(CODEX_DRIVER).pipe(Effect.exit);
+        assert.strictEqual(Exit.isSuccess(second), true);
+        if (Exit.isSuccess(second)) {
+          assert.strictEqual(second.value.providers[0]?.updateState?.status, "succeeded");
+        }
+      }).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            latestVersionHttpClient("0.0.0"),
+            mockSpawnerLayer(() => ({ stdout: "updated" })),
+          ),
+        ),
+      ),
+  );
+});
diff --git a/apps/server/src/provider/providerMaintenanceRunner.ts b/apps/server/src/provider/providerMaintenanceRunner.ts
new file mode 100644
index 00000000000..5f76afb34d3
--- /dev/null
+++ b/apps/server/src/provider/providerMaintenanceRunner.ts
@@ -0,0 +1,416 @@
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  ServerProviderUpdateError,
+  type ProviderInstanceId,
+  type ServerProvider,
+  type ServerProviderUpdatedPayload,
+  type ServerProviderUpdateState,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import { HttpClient } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { ProviderRegistry } from "./Services/ProviderRegistry.ts";
+import { makeProviderMaintenanceCommandCoordinator } from "./providerMaintenanceCommandCoordinator.ts";
+import { enrichProviderSnapshotWithVersionAdvisory } from "./providerMaintenance.ts";
+import type { ProviderMaintenanceCapabilities } from "./providerMaintenance.ts";
+import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
+const isServerProviderUpdateError = Schema.is(ServerProviderUpdateError);
+
+const UPDATE_TIMEOUT_MS = 5 * 60_000;
+const UPDATE_OUTPUT_MAX_BYTES = 10_000;
+
+export interface ProviderMaintenanceCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number | null;
+  readonly timedOut: boolean;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+}
+
+export interface ProviderMaintenanceRunnerShape {
+  readonly updateProvider: (
+    target:
+      | ProviderDriverKind
+      | {
+          readonly provider: ProviderDriverKind;
+          readonly instanceId?: ProviderInstanceId | undefined;
+        },
+  ) => Effect.Effect<ServerProviderUpdatedPayload, ServerProviderUpdateError>;
+}
+
+export class ProviderMaintenanceRunner extends Context.Service<
+  ProviderMaintenanceRunner,
+  ProviderMaintenanceRunnerShape
+>()("t3/provider/ProviderMaintenanceRunner") {}
+
+class ProviderMaintenanceCommandError extends Data.TaggedError("ProviderMaintenanceCommandError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+interface VerifiedProviderRefresh {
+  readonly providers: ReadonlyArray<ServerProvider>;
+  readonly verifiedProviders: ReadonlyArray<ServerProvider>;
+}
+
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
+const runProviderMaintenanceCommandWithSpawner = Effect.fn("ProviderMaintenanceRunner.runCommand")(
+  function* (input: {
+    readonly spawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+  }) {
+    const collectCommandResult = Effect.fn("ProviderMaintenanceRunner.collectCommandResult")(
+      function* () {
+        const child = yield* input.spawner
+          .spawn(ChildProcess.make(input.command, [...input.args]))
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new ProviderMaintenanceCommandError({
+                  message: `Failed to run update command ${input.command}: ${cause.message}`,
+                  cause,
+                }),
+            ),
+          );
+        yield* Effect.addFinalizer(() => child.kill().pipe(Effect.ignore));
+
+        const [stdout, stderr, exitCode] = yield* Effect.all(
+          [
+            collectUint8StreamText({
+              stream: child.stdout,
+              maxBytes: UPDATE_OUTPUT_MAX_BYTES,
+            }),
+            collectUint8StreamText({
+              stream: child.stderr,
+              maxBytes: UPDATE_OUTPUT_MAX_BYTES,
+            }),
+            child.exitCode,
+          ],
+          { concurrency: "unbounded" },
+        ).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ProviderMaintenanceCommandError({
+                message: cause instanceof Error ? cause.message : "Update command failed to run.",
+                cause,
+              }),
+          ),
+        );
+
+        return {
+          stdout: stdout.text,
+          stderr: stderr.text,
+          exitCode: Number(exitCode),
+          timedOut: false,
+          stdoutTruncated: stdout.truncated,
+          stderrTruncated: stderr.truncated,
+        } satisfies ProviderMaintenanceCommandResult;
+      },
+    );
+
+    return yield* collectCommandResult().pipe(
+      Effect.scoped,
+      Effect.timeoutOption(Duration.millis(UPDATE_TIMEOUT_MS)),
+      Effect.map((result) =>
+        Option.match(result, {
+          onSome: (value) => value,
+          onNone: () =>
+            ({
+              stdout: "",
+              stderr: "",
+              exitCode: null,
+              timedOut: true,
+              stdoutTruncated: false,
+              stderrTruncated: false,
+            }) satisfies ProviderMaintenanceCommandResult,
+        }),
+      ),
+    );
+  },
+);
+
+function trimNullable(value: string): string | null {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function truncateText(value: string, maxLength: number): string {
+  return value.length <= maxLength ? value : value.slice(0, maxLength);
+}
+
+function commandOutput(result: ProviderMaintenanceCommandResult): string | null {
+  const output = trimNullable([result.stderr, result.stdout].filter(Boolean).join("\n\n"));
+  if (!output) {
+    return null;
+  }
+  return truncateText(output, UPDATE_OUTPUT_MAX_BYTES);
+}
+
+function failureMessage(result: ProviderMaintenanceCommandResult): string {
+  if (result.timedOut) {
+    return "Update timed out.";
+  }
+  if (result.exitCode !== null && result.exitCode !== 0) {
+    return `Update command exited with code ${result.exitCode}.`;
+  }
+  return "Update command failed.";
+}
+
+function isOutdatedProvider(provider: ServerProvider | undefined): boolean {
+  return provider?.versionAdvisory?.status === "behind_latest";
+}
+
+function makeUpdateState(input: {
+  readonly status: ServerProviderUpdateState["status"];
+  readonly startedAt: string | null;
+  readonly finishedAt: string | null;
+  readonly message: string | null;
+  readonly output?: string | null;
+}): ServerProviderUpdateState {
+  return {
+    status: input.status,
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    message: input.message,
+    output: input.output ?? null,
+  };
+}
+
+export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
+  const providerRegistry = yield* ProviderRegistry;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const httpClient = yield* HttpClient.HttpClient;
+  const runMaintenanceCommand = (command: string, args: ReadonlyArray<string>) =>
+    runProviderMaintenanceCommandWithSpawner({
+      spawner,
+      command,
+      args,
+    });
+  const commandCoordinator = yield* makeProviderMaintenanceCommandCoordinator({
+    makeAlreadyRunningError: () =>
+      new ServerProviderUpdateError({
+        provider: ProviderDriverKind.make("unknown"),
+        reason: "An update is already running for this provider.",
+      }),
+  });
+
+  const verifyRefreshedProvider = (
+    provider: ProviderDriverKind,
+    maintenanceCapabilities: ProviderMaintenanceCapabilities,
+    instanceId: ProviderInstanceId,
+  ): Effect.Effect<VerifiedProviderRefresh> =>
+    providerRegistry.getProviders.pipe(
+      Effect.map((providers) =>
+        providers
+          .filter(
+            (candidate) => candidate.driver === provider && candidate.instanceId === instanceId,
+          )
+          .map((candidate) => candidate.instanceId),
+      ),
+      Effect.flatMap((instanceIds) =>
+        instanceIds.length === 0
+          ? providerRegistry.refreshInstance(instanceId)
+          : Effect.forEach(
+              instanceIds,
+              (instanceId) => providerRegistry.refreshInstance(instanceId),
+              {
+                concurrency: "unbounded",
+                discard: true,
+              },
+            ).pipe(Effect.andThen(providerRegistry.getProviders)),
+      ),
+      Effect.flatMap((providers) => {
+        const refreshedProviders = providers.filter(
+          (candidate) => candidate.driver === provider && candidate.instanceId === instanceId,
+        );
+        if (refreshedProviders.length === 0) {
+          return Effect.succeed<VerifiedProviderRefresh>({
+            providers,
+            verifiedProviders: [],
+          });
+        }
+        return Effect.forEach(
+          refreshedProviders,
+          (refreshedProvider) =>
+            enrichProviderSnapshotWithVersionAdvisory(
+              refreshedProvider,
+              maintenanceCapabilities,
+            ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient)),
+          {
+            concurrency: "unbounded",
+          },
+        ).pipe(
+          Effect.map(
+            (verifiedProviders): VerifiedProviderRefresh => ({
+              providers,
+              verifiedProviders,
+            }),
+          ),
+          Effect.catchCause((cause) =>
+            Effect.logWarning("Provider post-update version verification failed", {
+              provider,
+              cause: Cause.pretty(cause),
+            }).pipe(
+              Effect.as<VerifiedProviderRefresh>({
+                providers,
+                verifiedProviders: refreshedProviders,
+              }),
+            ),
+          ),
+        );
+      }),
+    );
+
+  const updateProvider: ProviderMaintenanceRunnerShape["updateProvider"] = Effect.fn(
+    "ProviderMaintenanceRunner.updateProvider",
+  )(function* (target) {
+    const provider = typeof target === "string" ? target : target.provider;
+    const instanceId =
+      typeof target === "string"
+        ? defaultInstanceIdForDriver(provider)
+        : (target.instanceId ?? defaultInstanceIdForDriver(provider));
+    const targetKey = `instance:${instanceId}`;
+    const capabilities = yield* providerRegistry.getProviderMaintenanceCapabilitiesForInstance(
+      instanceId,
+      provider,
+    );
+    const update = capabilities.update;
+    if (!update) {
+      return yield* new ServerProviderUpdateError({
+        provider,
+        reason: "This provider does not support one-click updates.",
+      });
+    }
+
+    const setUpdateState = (state: ServerProviderUpdateState | null) =>
+      providerRegistry.setProviderMaintenanceActionState({
+        instanceId,
+        action: "update",
+        state,
+      });
+    const setQueuedState = setUpdateState(
+      makeUpdateState({
+        status: "queued",
+        startedAt: null,
+        finishedAt: null,
+        message: "Waiting for another provider update to finish.",
+      }),
+    ).pipe(Effect.asVoid);
+
+    const runProviderUpdate = Effect.fn("ProviderMaintenanceRunner.runProviderUpdate")(
+      function* () {
+        const finish = (state: ServerProviderUpdateState) =>
+          setUpdateState(state).pipe(Effect.map((providers) => ({ providers })));
+        const startedAtRef = yield* Ref.make<string | null>(null);
+
+        const runCommandAndVerify = Effect.fn("ProviderMaintenanceRunner.runCommandAndVerify")(
+          function* () {
+            const startedAt = yield* nowIso;
+            yield* Ref.set(startedAtRef, startedAt);
+            yield* setUpdateState(
+              makeUpdateState({
+                status: "running",
+                startedAt,
+                finishedAt: null,
+                message: "Updating provider.",
+              }),
+            );
+
+            const result = yield* runMaintenanceCommand(update.executable, update.args);
+            const finishedAt = yield* nowIso;
+            if (result.timedOut || result.exitCode !== 0) {
+              return yield* finish(
+                makeUpdateState({
+                  status: "failed",
+                  startedAt,
+                  finishedAt,
+                  message: failureMessage(result),
+                  output: commandOutput(result),
+                }),
+              );
+            }
+
+            const { verifiedProviders } = yield* verifyRefreshedProvider(
+              provider,
+              capabilities,
+              instanceId,
+            );
+            const couldNotVerify = verifiedProviders.length === 0;
+            const stillOutdated =
+              couldNotVerify ||
+              verifiedProviders.some((verifiedProvider) => isOutdatedProvider(verifiedProvider));
+            return yield* finish(
+              makeUpdateState({
+                status: stillOutdated ? "unchanged" : "succeeded",
+                startedAt,
+                finishedAt,
+                message: couldNotVerify
+                  ? "Update command completed, but T3 Code could not verify the provider version."
+                  : stillOutdated
+                    ? "Update command completed, but T3 Code still detects an outdated provider version."
+                    : "Provider updated.",
+                output: commandOutput(result),
+              }),
+            );
+          },
+        );
+
+        const recordFailedUpdate = Effect.fn("ProviderMaintenanceRunner.recordFailedUpdate")(
+          function* (cause: Cause.Cause<unknown>) {
+            const failure = Cause.squash(cause);
+            const startedAt = yield* Ref.get(startedAtRef);
+            return yield* finish(
+              makeUpdateState({
+                status: "failed",
+                startedAt,
+                finishedAt: yield* nowIso,
+                message: failure instanceof Error ? failure.message : "Update command failed.",
+                output: null,
+              }),
+            );
+          },
+        );
+
+        return yield* runCommandAndVerify().pipe(Effect.catchCause(recordFailedUpdate));
+      },
+    );
+
+    return yield* commandCoordinator
+      .withCommandLock({
+        targetKey,
+        lockKey: update.lockKey,
+        onQueued: setQueuedState,
+        run: runProviderUpdate(),
+      })
+      .pipe(
+        Effect.mapError((error) =>
+          isServerProviderUpdateError(error)
+            ? new ServerProviderUpdateError({
+                provider,
+                reason: error.reason,
+              })
+            : error,
+        ),
+      );
+  });
+
+  return ProviderMaintenanceRunner.of({
+    updateProvider,
+  });
+});
+
+export const layer = Layer.effect(ProviderMaintenanceRunner, make());
diff --git a/apps/server/src/provider/providerSnapshot.test.ts b/apps/server/src/provider/providerSnapshot.test.ts
new file mode 100644
index 00000000000..449dca8fc5a
--- /dev/null
+++ b/apps/server/src/provider/providerSnapshot.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { ProviderDriverKind, type ModelCapabilities } from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import { providerModelsFromSettings } from "./providerSnapshot.ts";
+
+const OPENCODE_CUSTOM_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [
+    {
+      id: "variant",
+      label: "Reasoning",
+      type: "select",
+      options: [{ id: "medium", label: "Medium", isDefault: true }],
+      currentValue: "medium",
+    },
+    {
+      id: "agent",
+      label: "Agent",
+      type: "select",
+      options: [{ id: "build", label: "Build", isDefault: true }],
+      currentValue: "build",
+    },
+  ],
+});
+
+describe("providerModelsFromSettings", () => {
+  it("applies the provided capabilities to custom models", () => {
+    const models = providerModelsFromSettings(
+      [],
+      ProviderDriverKind.make("opencode"),
+      ["openai/gpt-5"],
+      OPENCODE_CUSTOM_MODEL_CAPABILITIES,
+    );
+
+    expect(models).toEqual([
+      {
+        slug: "openai/gpt-5",
+        name: "openai/gpt-5",
+        isCustom: true,
+        capabilities: OPENCODE_CUSTOM_MODEL_CAPABILITIES,
+      },
+    ]);
+  });
+});
diff --git a/apps/server/src/provider/providerSnapshot.ts b/apps/server/src/provider/providerSnapshot.ts
index 40246563aef..c40903e1b45 100644
--- a/apps/server/src/provider/providerSnapshot.ts
+++ b/apps/server/src/provider/providerSnapshot.ts
@@ -1,4 +1,5 @@
 import type {
+  ProviderDriverKind,
   ModelCapabilities,
   ServerProvider,
   ServerProviderAuth,
@@ -7,12 +8,18 @@ import type {
   ServerProviderModel,
   ServerProviderState,
 } from "@t3tools/contracts";
-import { Effect, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Data from "effect/Data";
+import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { normalizeModelSlug } from "@t3tools/shared/model";
-import { isWindowsCommandNotFound } from "../processRunner";
+import { isWindowsCommandNotFound } from "../processRunner.ts";
+import { createProviderVersionAdvisory } from "./providerMaintenance.ts";
+import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
 
 export const DEFAULT_TIMEOUT_MS = 4_000;
+// Auth status checks involve disk/network lookups and can be slow on first run (especially Windows)
+export const AUTH_PROBE_TIMEOUT_MS = 10_000;
 
 export interface CommandResult {
   readonly stdout: string;
@@ -20,6 +27,12 @@ export interface CommandResult {
   readonly code: number;
 }
 
+export class ProviderCommandExecutionError extends Data.TaggedError(
+  "ProviderCommandExecutionError",
+)<{
+  readonly message: string;
+}> {}
+
 export interface ProviderProbeResult {
   readonly installed: boolean;
   readonly version: string | null;
@@ -28,13 +41,21 @@ export interface ProviderProbeResult {
   readonly message?: string;
 }
 
+export interface ServerProviderPresentation {
+  readonly displayName: string;
+  readonly badgeLabel?: string;
+  readonly showInteractionModeToggle?: boolean;
+}
+
+export type ServerProviderDraft = Omit<ServerProvider, "instanceId" | "driver">;
+
 export function nonEmptyTrimmed(value: string | undefined): string | undefined {
   if (!value) return undefined;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
-export function isCommandMissingCause(error: Error): boolean {
+export function isCommandMissingCause(error: { readonly message: string }): boolean {
   const lower = error.message.toLowerCase();
   return lower.includes("enoent") || lower.includes("notfound");
 }
@@ -54,7 +75,7 @@ export const spawnAndCollect = (binaryPath: string, command: ChildProcess.Comman
 
     const result: CommandResult = { stdout, stderr, code: exitCode };
     if (isWindowsCommandNotFound(exitCode, stderr)) {
-      return yield* Effect.fail(new Error(`spawn ${binaryPath} ENOENT`));
+      return yield* new ProviderCommandExecutionError({ message: `spawn ${binaryPath} ENOENT` });
     }
     return result;
   }).pipe(Effect.scoped);
@@ -102,7 +123,7 @@ export function parseGenericCliVersion(output: string): string | null {
 
 export function providerModelsFromSettings(
   builtInModels: ReadonlyArray<ServerProviderModel>,
-  provider: ServerProvider["provider"],
+  provider: ProviderDriverKind,
   customModels: ReadonlyArray<string>,
   customModelCapabilities: ModelCapabilities,
 ): ReadonlyArray<ServerProviderModel> {
@@ -127,17 +148,72 @@ export function providerModelsFromSettings(
   return [...resolvedBuiltInModels, ...customEntries];
 }
 
+export function buildSelectOptionDescriptor(input: {
+  readonly id: string;
+  readonly label: string;
+  readonly options:
+    | ReadonlyArray<{ value: string; label: string; isDefault?: boolean | undefined }>
+    | undefined;
+  readonly description?: string;
+  readonly promptInjectedValues?: ReadonlyArray<string>;
+}) {
+  const options = (input.options ?? []).map((option) =>
+    option.isDefault
+      ? { id: option.value, label: option.label, isDefault: true }
+      : { id: option.value, label: option.label },
+  );
+  const currentValue = options.find((option) => option.isDefault)?.id;
+  return {
+    id: input.id,
+    label: input.label,
+    type: "select" as const,
+    options,
+    ...(currentValue ? { currentValue } : {}),
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.promptInjectedValues && input.promptInjectedValues.length > 0
+      ? { promptInjectedValues: [...input.promptInjectedValues] }
+      : {}),
+  };
+}
+
+export function buildBooleanOptionDescriptor(input: {
+  readonly id: string;
+  readonly label: string;
+  readonly currentValue?: boolean;
+  readonly description?: string;
+}) {
+  return {
+    id: input.id,
+    label: input.label,
+    type: "boolean" as const,
+    ...(input.description ? { description: input.description } : {}),
+    ...(typeof input.currentValue === "boolean" ? { currentValue: input.currentValue } : {}),
+  };
+}
+
 export function buildServerProvider(input: {
-  provider: ServerProvider["provider"];
+  driver?: ProviderDriverKind;
+  presentation: ServerProviderPresentation;
   enabled: boolean;
   checkedAt: string;
   models: ReadonlyArray<ServerProviderModel>;
   slashCommands?: ReadonlyArray<ServerProviderSlashCommand>;
   skills?: ReadonlyArray<ServerProviderSkill>;
   probe: ProviderProbeResult;
-}): ServerProvider {
+}): ServerProviderDraft {
+  const versionAdvisory = input.driver
+    ? createProviderVersionAdvisory({
+        driver: input.driver,
+        currentVersion: input.probe.version,
+        checkedAt: input.checkedAt,
+      })
+    : undefined;
   return {
-    provider: input.provider,
+    displayName: input.presentation.displayName,
+    ...(input.presentation.badgeLabel ? { badgeLabel: input.presentation.badgeLabel } : {}),
+    ...(typeof input.presentation.showInteractionModeToggle === "boolean"
+      ? { showInteractionModeToggle: input.presentation.showInteractionModeToggle }
+      : {}),
     enabled: input.enabled,
     installed: input.probe.installed,
     version: input.probe.version,
@@ -148,16 +224,11 @@ export function buildServerProvider(input: {
     models: input.models,
     slashCommands: [...(input.slashCommands ?? [])],
     skills: [...(input.skills ?? [])],
+    ...(versionAdvisory ? { versionAdvisory } : {}),
   };
 }
 
 export const collectStreamAsString = <E>(
   stream: Stream.Stream<Uint8Array, E>,
 ): Effect.Effect<string, E> =>
-  stream.pipe(
-    Stream.decodeText(),
-    Stream.runFold(
-      () => "",
-      (acc, chunk) => acc + chunk,
-    ),
-  );
+  collectUint8StreamText({ stream }).pipe(Effect.map((collected) => collected.text));
diff --git a/apps/server/src/provider/providerStatusCache.test.ts b/apps/server/src/provider/providerStatusCache.test.ts
new file mode 100644
index 00000000000..64cb9ccd417
--- /dev/null
+++ b/apps/server/src/provider/providerStatusCache.test.ts
@@ -0,0 +1,237 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+
+import {
+  hydrateCachedProvider,
+  isCachedProviderCorrelated,
+  readProviderStatusCache,
+  resolveProviderStatusCachePath,
+  writeProviderStatusCache,
+} from "./providerStatusCache.ts";
+
+const emptyCapabilities = createModelCapabilities({ optionDescriptors: [] });
+const CODEX_DRIVER = ProviderDriverKind.make("codex");
+const CLAUDE_AGENT_DRIVER = ProviderDriverKind.make("claudeAgent");
+const OPENCODE_DRIVER = ProviderDriverKind.make("opencode");
+
+const makeProvider = (
+  provider: ProviderDriverKind,
+  overrides?: Partial<ServerProvider>,
+): ServerProvider => ({
+  instanceId: defaultInstanceIdForDriver(provider),
+  driver: provider,
+  enabled: true,
+  installed: true,
+  version: "1.0.0",
+  status: "ready",
+  auth: { status: "authenticated" },
+  checkedAt: "2026-04-11T00:00:00.000Z",
+  models: [],
+  slashCommands: [],
+  skills: [],
+  ...overrides,
+});
+
+it.layer(NodeServices.layer)("providerStatusCache", (it) => {
+  it.effect("writes and reads provider status snapshots", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-provider-cache-" });
+      const codexProvider = makeProvider(CODEX_DRIVER);
+      const claudeProvider = makeProvider(CLAUDE_AGENT_DRIVER, {
+        status: "warning",
+        auth: { status: "unknown" },
+      });
+      const openCodeProvider = makeProvider(OPENCODE_DRIVER, {
+        status: "warning",
+        auth: { status: "unknown", type: "opencode" },
+      });
+      const codexPath = yield* resolveProviderStatusCachePath({
+        cacheDir: tempDir,
+        instanceId: defaultInstanceIdForDriver(ProviderDriverKind.make("codex")),
+      });
+      const claudePath = yield* resolveProviderStatusCachePath({
+        cacheDir: tempDir,
+        instanceId: defaultInstanceIdForDriver(ProviderDriverKind.make("claudeAgent")),
+      });
+      const openCodePath = yield* resolveProviderStatusCachePath({
+        cacheDir: tempDir,
+        instanceId: defaultInstanceIdForDriver(ProviderDriverKind.make("opencode")),
+      });
+
+      yield* writeProviderStatusCache({
+        filePath: codexPath,
+        provider: codexProvider,
+      });
+      yield* writeProviderStatusCache({
+        filePath: claudePath,
+        provider: claudeProvider,
+      });
+      yield* writeProviderStatusCache({
+        filePath: openCodePath,
+        provider: openCodeProvider,
+      });
+
+      assert.deepStrictEqual(yield* readProviderStatusCache(codexPath), codexProvider);
+      assert.deepStrictEqual(yield* readProviderStatusCache(claudePath), claudeProvider);
+      assert.deepStrictEqual(yield* readProviderStatusCache(openCodePath), openCodeProvider);
+    }),
+  );
+
+  it("hydrates cached provider status while preserving current settings-derived models", () => {
+    const cachedCodex = makeProvider(CODEX_DRIVER, {
+      checkedAt: "2026-04-10T12:00:00.000Z",
+      models: [
+        {
+          slug: "gpt-5-mini",
+          name: "GPT-5 Mini",
+          isCustom: false,
+          capabilities: emptyCapabilities,
+        },
+      ],
+      message: "Cached message",
+      skills: [
+        {
+          name: "github:gh-fix-ci",
+          path: "/tmp/skills/gh-fix-ci/SKILL.md",
+          enabled: true,
+          displayName: "CI Debug",
+        },
+      ],
+    });
+    const fallbackCodex = makeProvider(CODEX_DRIVER, {
+      models: [
+        {
+          slug: "gpt-5.4",
+          name: "GPT-5.4",
+          isCustom: false,
+          capabilities: emptyCapabilities,
+        },
+      ],
+      message: "Pending refresh",
+    });
+
+    assert.deepStrictEqual(
+      hydrateCachedProvider({
+        cachedProvider: cachedCodex,
+        fallbackProvider: fallbackCodex,
+      }),
+      {
+        ...fallbackCodex,
+        models: [
+          ...fallbackCodex.models,
+          {
+            slug: "gpt-5-mini",
+            name: "GPT-5 Mini",
+            isCustom: false,
+            capabilities: emptyCapabilities,
+          },
+        ],
+        installed: cachedCodex.installed,
+        version: cachedCodex.version,
+        status: cachedCodex.status,
+        auth: cachedCodex.auth,
+        checkedAt: cachedCodex.checkedAt,
+        slashCommands: cachedCodex.slashCommands,
+        skills: cachedCodex.skills,
+        message: cachedCodex.message,
+      },
+    );
+  });
+
+  it("ignores stale cached enabled state when the provider is now disabled", () => {
+    const cachedCodex = makeProvider(CODEX_DRIVER, {
+      checkedAt: "2026-04-10T12:00:00.000Z",
+      message: "Cached ready status",
+    });
+    const disabledFallback = makeProvider(CODEX_DRIVER, {
+      enabled: false,
+      installed: false,
+      version: null,
+      status: "disabled",
+      auth: { status: "unknown" },
+      message: "Codex is disabled in T3 Code settings.",
+    });
+
+    assert.deepStrictEqual(
+      hydrateCachedProvider({
+        cachedProvider: cachedCodex,
+        fallbackProvider: disabledFallback,
+      }),
+      disabledFallback,
+    );
+  });
+
+  it("rejects cached snapshots that are not correlated to the fallback instance", () => {
+    const fallbackCodex = makeProvider(CODEX_DRIVER, {
+      models: [
+        {
+          slug: "gpt-5.4",
+          name: "GPT-5.4",
+          isCustom: false,
+          capabilities: emptyCapabilities,
+        },
+      ],
+    });
+    const legacyCachedCodex = {
+      provider: ProviderDriverKind.make("codex"),
+      enabled: true,
+      installed: true,
+      version: "1.0.0",
+      status: "ready",
+      auth: { status: "authenticated" },
+      checkedAt: "2026-04-10T12:00:00.000Z",
+      models: [
+        {
+          slug: "cached-legacy-model",
+          name: "Cached Legacy Model",
+          isCustom: false,
+          capabilities: emptyCapabilities,
+        },
+      ],
+      slashCommands: [],
+      skills: [],
+    } as unknown as ServerProvider;
+    const mismatchedCachedCodex = makeProvider(CODEX_DRIVER, {
+      instanceId: ProviderInstanceId.make("codex_personal"),
+    });
+
+    assert.strictEqual(
+      isCachedProviderCorrelated({
+        cachedProvider: legacyCachedCodex,
+        fallbackProvider: fallbackCodex,
+      }),
+      false,
+    );
+    assert.deepStrictEqual(
+      hydrateCachedProvider({
+        cachedProvider: legacyCachedCodex,
+        fallbackProvider: fallbackCodex,
+      }),
+      fallbackCodex,
+    );
+    assert.strictEqual(
+      isCachedProviderCorrelated({
+        cachedProvider: mismatchedCachedCodex,
+        fallbackProvider: fallbackCodex,
+      }),
+      false,
+    );
+    assert.deepStrictEqual(
+      hydrateCachedProvider({
+        cachedProvider: mismatchedCachedCodex,
+        fallbackProvider: fallbackCodex,
+      }),
+      fallbackCodex,
+    );
+  });
+});
diff --git a/apps/server/src/provider/providerStatusCache.ts b/apps/server/src/provider/providerStatusCache.ts
new file mode 100644
index 00000000000..0b9b365f360
--- /dev/null
+++ b/apps/server/src/provider/providerStatusCache.ts
@@ -0,0 +1,153 @@
+import {
+  type ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProvider,
+  ServerProvider as ServerProviderSchema,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+import { writeFileStringAtomically } from "../atomicWrite.ts";
+
+const decodeProviderStatusCache = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(ServerProviderSchema),
+);
+
+const mergeProviderModels = (
+  fallbackModels: ReadonlyArray<ServerProvider["models"][number]>,
+  cachedModels: ReadonlyArray<ServerProvider["models"][number]>,
+): ReadonlyArray<ServerProvider["models"][number]> => {
+  const fallbackSlugs = new Set(fallbackModels.map((model) => model.slug));
+  return [...fallbackModels, ...cachedModels.filter((model) => !fallbackSlugs.has(model.slug))];
+};
+
+export const orderProviderSnapshots = (
+  providers: ReadonlyArray<ServerProvider>,
+): ReadonlyArray<ServerProvider> =>
+  [...providers].toSorted(
+    (left, right) =>
+      (left.displayName ?? "").localeCompare(right.displayName ?? "") ||
+      left.driver.localeCompare(right.driver) ||
+      left.instanceId.localeCompare(right.instanceId),
+  );
+
+export const isCachedProviderCorrelated = (input: {
+  readonly cachedProvider: ServerProvider;
+  readonly fallbackProvider: ServerProvider;
+}): boolean =>
+  input.cachedProvider.instanceId === input.fallbackProvider.instanceId &&
+  input.cachedProvider.driver === input.fallbackProvider.driver;
+
+export const hydrateCachedProvider = (input: {
+  readonly cachedProvider: ServerProvider;
+  readonly fallbackProvider: ServerProvider;
+}): ServerProvider => {
+  if (!isCachedProviderCorrelated(input)) {
+    return input.fallbackProvider;
+  }
+
+  if (
+    !input.fallbackProvider.enabled ||
+    input.cachedProvider.enabled !== input.fallbackProvider.enabled
+  ) {
+    return input.fallbackProvider;
+  }
+
+  const { message: _fallbackMessage, ...fallbackWithoutMessage } = input.fallbackProvider;
+  const hydratedProvider: ServerProvider = {
+    ...fallbackWithoutMessage,
+    models: mergeProviderModels(input.fallbackProvider.models, input.cachedProvider.models),
+    installed: input.cachedProvider.installed,
+    version: input.cachedProvider.version,
+    status: input.cachedProvider.status,
+    auth: input.cachedProvider.auth,
+    checkedAt: input.cachedProvider.checkedAt,
+    slashCommands: input.cachedProvider.slashCommands,
+    skills: input.cachedProvider.skills,
+  };
+
+  return input.cachedProvider.message
+    ? { ...hydratedProvider, message: input.cachedProvider.message }
+    : hydratedProvider;
+};
+
+/**
+ * Resolve the on-disk cache path for a provider instance snapshot.
+ *
+ * File naming: `<cacheDir>/<instanceId>.json`. For the default instance of
+ * a built-in kind this equals the legacy `<kind>.json` path (because
+ * `defaultInstanceIdForDriver(kind).toString() === kind`), so existing
+ * cached snapshots remain readable without any rename step.
+ *
+ * Non-default instances (e.g. `codex_personal`) land in their own files and
+ * never collide with other instances.
+ *
+ * Cache contents must still carry matching `instanceId` + `driver` identity
+ * before hydration. The filename alone is not trusted as a routing key.
+ */
+export const resolveProviderStatusCachePath = Effect.fn("resolveProviderStatusCachePath")(
+  function* (input: {
+    readonly cacheDir: string;
+    readonly instanceId: ProviderInstanceId;
+  }): Effect.fn.Return<string, never, Path.Path> {
+    const path = yield* Path.Path;
+    return path.join(input.cacheDir, `${input.instanceId}.json`);
+  },
+);
+
+/**
+ * Legacy kind-keyed path resolver retained for callers that still think in
+ * terms of `ProviderDriverKind`. Prefer `resolveProviderStatusCachePath` with an
+ * `instanceId`; new code should route through the instance registry.
+ *
+ * @deprecated use `resolveProviderStatusCachePath` with an instance id.
+ */
+export const resolveLegacyProviderStatusCachePath = Effect.fn(
+  "resolveLegacyProviderStatusCachePath",
+)(function* (input: {
+  readonly cacheDir: string;
+  readonly provider: ProviderDriverKind;
+}): Effect.fn.Return<string, never, Path.Path> {
+  const path = yield* Path.Path;
+  return path.join(input.cacheDir, `${input.provider}.json`);
+});
+
+export const readProviderStatusCache = (filePath: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const exists = yield* fs.exists(filePath).pipe(Effect.orElseSucceed(() => false));
+    if (!exists) {
+      return undefined;
+    }
+
+    const raw = yield* fs.readFileString(filePath).pipe(Effect.orElseSucceed(() => ""));
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      return undefined;
+    }
+
+    return yield* decodeProviderStatusCache(trimmed).pipe(
+      Effect.matchCauseEffect({
+        onFailure: (cause) =>
+          Effect.logWarning("failed to parse provider status cache, ignoring", {
+            path: filePath,
+            issues: Cause.pretty(cause),
+          }).pipe(Effect.as(undefined)),
+        onSuccess: Effect.succeed,
+      }),
+    );
+  });
+
+export const writeProviderStatusCache = (input: {
+  readonly filePath: string;
+  readonly provider: ServerProvider;
+}) => {
+  const { updateState: _updateState, ...cacheableProvider } = input.provider;
+  return writeFileStringAtomically({
+    filePath: input.filePath,
+    contents: `${JSON.stringify(cacheableProvider, null, 2)}\n`,
+  });
+};
diff --git a/apps/server/src/provider/testUtils/providerAdapterRegistryMock.ts b/apps/server/src/provider/testUtils/providerAdapterRegistryMock.ts
new file mode 100644
index 00000000000..c696a51c37e
--- /dev/null
+++ b/apps/server/src/provider/testUtils/providerAdapterRegistryMock.ts
@@ -0,0 +1,99 @@
+/**
+ * Test helpers for constructing a `ProviderAdapterRegistryShape` mock from a
+ * kind-keyed adapter map.
+ *
+ * Tests historically assembled a `registry` object with only `getByProvider`
+ * + `listProviders` populated. Slice D grew the shape with `getByInstance`
+ * and `listInstances`; this helper fills both in from a single kind-keyed
+ * input so individual fixtures can stay concise.
+ *
+ * Non-default instance ids (e.g. `codex_personal`) are not addressable via
+ * the shim returned here — the legacy test fixtures only ever had
+ * single-instance-per-driver data anyway.
+ *
+ * @module provider/testUtils/providerAdapterRegistryMock
+ */
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  type ProviderInstanceId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as PubSub from "effect/PubSub";
+import * as Record from "effect/Record";
+import * as Result from "effect/Result";
+import * as Stream from "effect/Stream";
+
+import { ProviderUnsupportedError, type ProviderAdapterError } from "../Errors.ts";
+import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
+import type { ProviderAdapterRegistryShape } from "../Services/ProviderAdapterRegistry.ts";
+
+export type KindAdapterMap = Partial<
+  Record<ProviderDriverKind, ProviderAdapterShape<ProviderAdapterError>>
+>;
+
+/**
+ * Build a `ProviderAdapterRegistryShape` from a kind-keyed adapter map.
+ * Every adapter present in the map is addressable via both the legacy
+ * `getByProvider(kind)` path and the new `getByInstance(id)` path (where
+ * `id = defaultInstanceIdForDriver(kind)`).
+ */
+export const makeAdapterRegistryMock = (adapters: KindAdapterMap): ProviderAdapterRegistryShape => {
+  const byInstanceId = new Map<ProviderInstanceId, ProviderAdapterShape<ProviderAdapterError>>();
+  for (const [kind, adapter] of Object.entries(adapters)) {
+    if (!adapter) continue;
+    const driverKind = ProviderDriverKind.make(kind);
+    byInstanceId.set(defaultInstanceIdForDriver(driverKind), adapter);
+  }
+
+  const getByInstance: ProviderAdapterRegistryShape["getByInstance"] = (instanceId) => {
+    const adapter = byInstanceId.get(instanceId);
+    return adapter
+      ? Effect.succeed(adapter)
+      : Effect.fail(
+          new ProviderUnsupportedError({
+            provider: ProviderDriverKind.make(instanceId),
+          }),
+        );
+  };
+
+  return {
+    getByInstance,
+    getInstanceInfo: (instanceId) => {
+      const adapter = byInstanceId.get(instanceId);
+      if (!adapter) {
+        return Effect.fail(
+          new ProviderUnsupportedError({
+            provider: ProviderDriverKind.make(instanceId),
+          }),
+        );
+      }
+      return Effect.succeed({
+        instanceId,
+        driverKind: ProviderDriverKind.make(adapter.provider),
+        displayName: undefined,
+        enabled: true,
+        continuationIdentity: {
+          driverKind: ProviderDriverKind.make(adapter.provider),
+          continuationKey: `${adapter.provider}:instance:${instanceId}`,
+        },
+      });
+    },
+    listInstances: () => Effect.succeed(Array.from(byInstanceId.keys())),
+    listProviders: () =>
+      Effect.succeed(
+        Record.keys(
+          Record.filterMap(adapters, (adapter, kind) =>
+            adapter !== undefined ? Result.succeed(kind) : Result.failVoid,
+          ),
+        ),
+      ),
+    // Static test fixtures don't reload; an empty stream is enough to
+    // satisfy the shape. Tests exercising hot-reload build their own
+    // stream via the real `ProviderInstanceRegistry`.
+    streamChanges: Stream.empty,
+    subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+      PubSub.subscribe(pubsub),
+    ),
+  };
+};
diff --git a/apps/server/src/provider/unavailableProviderSnapshot.ts b/apps/server/src/provider/unavailableProviderSnapshot.ts
new file mode 100644
index 00000000000..de0c799a8cd
--- /dev/null
+++ b/apps/server/src/provider/unavailableProviderSnapshot.ts
@@ -0,0 +1,79 @@
+/**
+ * Helpers for synthesizing "unavailable" `ServerProvider` snapshots.
+ *
+ * When `ServerSettings.providerInstances` (or persisted thread/session
+ * state) references a driver this build does not ship — typical after a
+ * downgrade from a fork or a feature-branch test session — the runtime
+ * needs to surface the entry to the UI without crashing. This module
+ * produces shadow snapshots that satisfy `ServerProvider`'s wire shape
+ * while signalling unavailability.
+ *
+ * @module unavailableProviderSnapshot
+ */
+import {
+  ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+
+import { buildServerProvider } from "./providerSnapshot.ts";
+
+export interface UnavailableProviderSnapshotInput {
+  readonly driverKind: ProviderDriverKind | string;
+  readonly instanceId: ProviderInstanceId;
+  readonly displayName?: string | undefined;
+  readonly accentColor?: string | undefined;
+  readonly reason: string;
+  /**
+   * Optional override for `checkedAt`. Defaulted to the current Effect
+   * `DateTime` so callers
+   * (notably tests) don't have to pass it.
+   */
+  readonly checkedAt?: string;
+}
+
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
+/**
+ * Produce a `ServerProvider` snapshot representing a configured instance
+ * whose driver the running build does not implement. The result is safe
+ * to broadcast over the wire and is structured so the web UI can render
+ * a "missing driver" affordance without special-casing.
+ */
+export function buildUnavailableProviderSnapshot(
+  input: UnavailableProviderSnapshotInput,
+): Effect.Effect<ServerProvider> {
+  return Effect.gen(function* () {
+    const checkedAt = input.checkedAt ?? (yield* nowIso);
+    const displayName = input.displayName?.trim() || (input.driverKind as string);
+
+    const base = buildServerProvider({
+      presentation: { displayName },
+      enabled: false,
+      checkedAt,
+      models: [],
+      skills: [],
+      probe: {
+        installed: false,
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: input.reason,
+      },
+    });
+
+    return {
+      ...base,
+      instanceId: input.instanceId,
+      ...(input.accentColor ? { accentColor: input.accentColor } : {}),
+      driver:
+        typeof input.driverKind === "string"
+          ? ProviderDriverKind.make(input.driverKind)
+          : input.driverKind,
+      availability: "unavailable",
+      unavailableReason: input.reason,
+    };
+  });
+}
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index fbbab1c84a2..3ae2885f024 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -10,12 +10,15 @@ import {
   GitCommandError,
   KeybindingRule,
   MessageId,
-  OpenError,
+  ExternalLauncherError,
+  type OrchestrationThreadShell,
   TerminalNotRunningError,
   type OrchestrationCommand,
   type OrchestrationEvent,
   ORCHESTRATION_WS_METHODS,
   ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ResolvedKeybindingRule,
   ThreadId,
   WS_METHODS,
@@ -24,16 +27,18 @@ import {
 } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
 import { assertFailure, assertInclude, assertTrue } from "@effect/vitest/utils";
-import {
-  Deferred,
-  Duration,
-  Effect,
-  FileSystem,
-  Layer,
-  ManagedRuntime,
-  Path,
-  Stream,
-} from "effect";
+import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
 import {
   FetchHttpClient,
   HttpBody,
@@ -46,6 +51,8 @@ import { RpcClient, RpcSerialization } from "effect/unstable/rpc";
 import * as Socket from "effect/unstable/socket/Socket";
 import { vi } from "vitest";
 
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
+
 import type { ServerConfigShape } from "./config.ts";
 import { deriveServerPaths, ServerConfig } from "./config.ts";
 import { makeRoutesLayer } from "./server.ts";
@@ -54,11 +61,9 @@ import {
   CheckpointDiffQuery,
   type CheckpointDiffQueryShape,
 } from "./checkpointing/Services/CheckpointDiffQuery.ts";
-import { GitCore, type GitCoreShape } from "./git/Services/GitCore.ts";
-import { GitManager, type GitManagerShape } from "./git/Services/GitManager.ts";
-import { GitStatusBroadcasterLive } from "./git/Layers/GitStatusBroadcaster.ts";
+import { GitManager, type GitManagerShape } from "./git/GitManager.ts";
 import { Keybindings, type KeybindingsShape } from "./keybindings.ts";
-import { Open, type OpenShape } from "./open.ts";
+import * as ExternalLauncher from "./process/externalLauncher.ts";
 import {
   OrchestrationEngineService,
   type OrchestrationEngineShape,
@@ -68,12 +73,13 @@ import {
   ProjectionSnapshotQuery,
   type ProjectionSnapshotQueryShape,
 } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
-import { PersistenceSqlError } from "./persistence/Errors.ts";
 import { SqlitePersistenceMemory } from "./persistence/Layers/Sqlite.ts";
+import { PersistenceSqlError } from "./persistence/Errors.ts";
 import {
   ProviderRegistry,
   type ProviderRegistryShape,
 } from "./provider/Services/ProviderRegistry.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "./provider/providerMaintenance.ts";
 import { ServerLifecycleEvents, type ServerLifecycleEventsShape } from "./serverLifecycleEvents.ts";
 import { ServerRuntimeStartup, type ServerRuntimeStartupShape } from "./serverRuntimeStartup.ts";
 import { ServerSettingsService, type ServerSettingsShape } from "./serverSettings.ts";
@@ -85,6 +91,7 @@ import {
 import { ProjectFaviconResolverLive } from "./project/Layers/ProjectFaviconResolver.ts";
 import {
   ProjectSetupScriptRunner,
+  ProjectSetupScriptRunnerError,
   type ProjectSetupScriptRunnerShape,
 } from "./project/Services/ProjectSetupScriptRunner.ts";
 import {
@@ -98,14 +105,25 @@ import {
 import { WorkspaceEntriesLive } from "./workspace/Layers/WorkspaceEntries.ts";
 import { WorkspaceFileSystemLive } from "./workspace/Layers/WorkspaceFileSystem.ts";
 import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
+import * as GitVcsDriver from "./vcs/GitVcsDriver.ts";
+import * as VcsDriver from "./vcs/VcsDriver.ts";
+import * as VcsStatusBroadcaster from "./vcs/VcsStatusBroadcaster.ts";
+import * as VcsDriverRegistry from "./vcs/VcsDriverRegistry.ts";
+import * as VcsProvisioningService from "./vcs/VcsProvisioningService.ts";
+import * as GitWorkflowService from "./git/GitWorkflowService.ts";
+import * as SourceControlRepositoryService from "./sourceControl/SourceControlRepositoryService.ts";
 import { ServerSecretStoreLive } from "./auth/Layers/ServerSecretStore.ts";
 import { ServerAuthLive } from "./auth/Layers/ServerAuth.ts";
+import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
+import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
+import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
+import * as Data from "effect/Data";
 
 const defaultProjectId = ProjectId.make("project-default");
 const defaultThreadId = ThreadId.make("thread-default");
 const defaultDesktopBootstrapToken = "test-desktop-bootstrap-token";
 const defaultModelSelection = {
-  provider: "codex",
+  instanceId: ProviderInstanceId.make("codex"),
   model: "gpt-5-codex",
 } as const;
 const testEnvironmentDescriptor = {
@@ -121,7 +139,7 @@ const testEnvironmentDescriptor = {
   },
 };
 const makeDefaultOrchestrationReadModel = () => {
-  const now = new Date().toISOString();
+  const now = "2026-01-01T00:00:00.000Z";
   return {
     snapshotSequence: 0,
     updatedAt: now,
@@ -162,15 +180,31 @@ const makeDefaultOrchestrationReadModel = () => {
   };
 };
 
-const workspaceAndProjectServicesLayer = Layer.mergeAll(
-  WorkspacePathsLive,
-  WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive)),
-  WorkspaceFileSystemLive.pipe(
-    Layer.provide(WorkspacePathsLive),
-    Layer.provide(WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive))),
-  ),
-  ProjectFaviconResolverLive,
-);
+const makeDefaultOrchestrationThreadShell = (
+  overrides: Partial<OrchestrationThreadShell> = {},
+): OrchestrationThreadShell => {
+  const now = "2026-01-01T00:00:00.000Z";
+  return {
+    id: defaultThreadId,
+    projectId: defaultProjectId,
+    title: "Default Thread",
+    modelSelection: defaultModelSelection,
+    runtimeMode: "full-access",
+    interactionMode: "default",
+    branch: null,
+    worktreePath: null,
+    latestTurn: null,
+    createdAt: now,
+    updatedAt: now,
+    archivedAt: null,
+    session: null,
+    latestUserMessageAt: null,
+    hasPendingApprovals: false,
+    hasPendingUserInput: false,
+    hasActionableProposedPlan: false,
+    ...overrides,
+  };
+};
 
 const browserOtlpTracingLayer = Layer.mergeAll(
   FetchHttpClient.layer,
@@ -178,10 +212,8 @@ const browserOtlpTracingLayer = Layer.mergeAll(
   Layer.succeed(HttpClient.TracerDisabledWhen, () => true),
 );
 
-const authTestLayer = ServerAuthLive.pipe(
-  Layer.provide(SqlitePersistenceMemory),
-  Layer.provide(ServerSecretStoreLive),
-);
+const makeAuthTestLayer = () =>
+  ServerAuthLive.pipe(Layer.provide(SqlitePersistenceMemory), Layer.provide(ServerSecretStoreLive));
 
 const makeBrowserOtlpPayload = (spanName: string) =>
   Effect.gen(function* () {
@@ -272,15 +304,13 @@ const makeBrowserOtlpPayload = (spanName: string) =>
       yield* Effect.promise(() => runtime.dispose());
     }
 
-    const request = yield* Effect.promise(() =>
-      Promise.race([
-        collector.firstRequest,
-        new Promise<never>((_, reject) => {
-          setTimeout(() => reject(new Error("Timed out waiting for OTLP trace export")), 1_000);
-        }),
-      ]),
+    const request = yield* Effect.raceFirst(
+      Effect.promise(() => collector.firstRequest).pipe(Effect.orDie),
+      Effect.sleep(Duration.seconds(1)).pipe(
+        Effect.andThen(Effect.die(new Error("Timed out waiting for OTLP trace export"))),
+      ),
     );
-
+    // @effect-diagnostics-next-line preferSchemaOverJson:off
     return JSON.parse(request.body) as OtlpTracer.TraceData;
   });
 
@@ -290,9 +320,13 @@ const buildAppUnderTest = (options?: {
     keybindings?: Partial<KeybindingsShape>;
     providerRegistry?: Partial<ProviderRegistryShape>;
     serverSettings?: Partial<ServerSettingsShape>;
-    open?: Partial<OpenShape>;
-    gitCore?: Partial<GitCoreShape>;
+    externalLauncher?: Partial<ExternalLauncher.ExternalLauncherShape>;
+    vcsDriver?: Partial<VcsDriver.VcsDriverShape>;
+    vcsDriverRegistry?: Partial<VcsDriverRegistry.VcsDriverRegistryShape>;
+    gitVcsDriver?: Partial<GitVcsDriver.GitVcsDriverShape>;
     gitManager?: Partial<GitManagerShape>;
+    sourceControlRepositoryService?: Partial<SourceControlRepositoryService.SourceControlRepositoryServiceShape>;
+    vcsStatusBroadcaster?: Partial<VcsStatusBroadcaster.VcsStatusBroadcasterShape>;
     projectSetupScriptRunner?: Partial<ProjectSetupScriptRunnerShape>;
     terminalManager?: Partial<TerminalManagerShape>;
     orchestrationEngine?: Partial<OrchestrationEngineShape>;
@@ -335,13 +369,138 @@ const buildAppUnderTest = (options?: {
       desktopBootstrapToken: defaultDesktopBootstrapToken,
       autoBootstrapProjectFromCwd: false,
       logWebSocketEvents: false,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       ...options?.config,
     };
     const layerConfig = Layer.succeed(ServerConfig, config);
+    const defaultVcsDriver: VcsDriver.VcsDriverShape = {
+      capabilities: {
+        kind: "git",
+        supportsWorktrees: true,
+        supportsBookmarks: false,
+        supportsAtomicSnapshot: false,
+        supportsPushDefaultRemote: true,
+        ignoreClassifier: "native",
+      },
+      execute: () =>
+        Effect.succeed({
+          exitCode: ChildProcessSpawner.ExitCode(0),
+          stdout: "",
+          stderr: "",
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        }),
+      detectRepository: () => Effect.succeed(null),
+      isInsideWorkTree: () => Effect.succeed(false),
+      listWorkspaceFiles: () =>
+        Effect.succeed({
+          paths: [],
+          truncated: false,
+          freshness: {
+            source: "live-local",
+            observedAt: TEST_EPOCH,
+            expiresAt: Option.none(),
+          },
+        }),
+      listRemotes: () =>
+        Effect.succeed({
+          remotes: [],
+          freshness: {
+            source: "live-local",
+            observedAt: TEST_EPOCH,
+            expiresAt: Option.none(),
+          },
+        }),
+      filterIgnoredPaths: (_cwd, relativePaths) => Effect.succeed(relativePaths),
+      initRepository: () => Effect.void,
+      ...options?.layers?.vcsDriver,
+    };
+    const vcsDriverRegistryLayer = Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
+      get: () => Effect.succeed(defaultVcsDriver),
+      detect: (input) =>
+        defaultVcsDriver.detectRepository(input.cwd).pipe(
+          Effect.flatMap((repository) =>
+            repository
+              ? Effect.succeed(repository)
+              : defaultVcsDriver.isInsideWorkTree(input.cwd).pipe(
+                  Effect.map((isInsideWorkTree) =>
+                    isInsideWorkTree
+                      ? {
+                          kind: "git" as const,
+                          rootPath: input.cwd,
+                          metadataPath: null,
+                          freshness: {
+                            source: "live-local" as const,
+                            observedAt: TEST_EPOCH,
+                            expiresAt: Option.none(),
+                          },
+                        }
+                      : null,
+                  ),
+                ),
+          ),
+          Effect.map((repository) =>
+            repository
+              ? ({
+                  kind: repository.kind,
+                  repository,
+                  driver: defaultVcsDriver,
+                } satisfies VcsDriverRegistry.VcsDriverHandle)
+              : null,
+          ),
+        ),
+      resolve: (input) =>
+        Effect.succeed({
+          kind:
+            input.requestedKind === "auto" || !input.requestedKind ? "git" : input.requestedKind,
+          repository: {
+            kind:
+              input.requestedKind === "auto" || !input.requestedKind ? "git" : input.requestedKind,
+            rootPath: input.cwd,
+            metadataPath: null,
+            freshness: {
+              source: "live-local",
+              observedAt: TEST_EPOCH,
+              expiresAt: Option.none(),
+            },
+          },
+          driver: defaultVcsDriver,
+        }),
+      ...options?.layers?.vcsDriverRegistry,
+    });
+    const gitVcsDriverLayer = Layer.mock(GitVcsDriver.GitVcsDriver)({
+      ...options?.layers?.gitVcsDriver,
+    });
     const gitManagerLayer = Layer.mock(GitManager)({
       ...options?.layers?.gitManager,
     });
-    const gitStatusBroadcasterLayer = GitStatusBroadcasterLive.pipe(Layer.provide(gitManagerLayer));
+    const workspaceEntriesLayer = WorkspaceEntriesLive.pipe(
+      Layer.provide(WorkspacePathsLive),
+      Layer.provideMerge(vcsDriverRegistryLayer),
+    );
+    const workspaceAndProjectServicesLayer = Layer.mergeAll(
+      WorkspacePathsLive,
+      workspaceEntriesLayer,
+      WorkspaceFileSystemLive.pipe(
+        Layer.provide(WorkspacePathsLive),
+        Layer.provide(workspaceEntriesLayer),
+      ),
+      ProjectFaviconResolverLive,
+    );
+    const gitWorkflowLayer = GitWorkflowService.layer.pipe(
+      Layer.provideMerge(vcsDriverRegistryLayer),
+      Layer.provideMerge(gitVcsDriverLayer),
+      Layer.provideMerge(gitManagerLayer),
+    );
+    const vcsProvisioningLayer = VcsProvisioningService.layer.pipe(
+      Layer.provide(vcsDriverRegistryLayer),
+    );
+    const vcsStatusBroadcasterLayer = options?.layers?.vcsStatusBroadcaster
+      ? Layer.mock(VcsStatusBroadcaster.VcsStatusBroadcaster)({
+          ...options.layers.vcsStatusBroadcaster,
+        })
+      : VcsStatusBroadcaster.layer.pipe(Layer.provide(gitWorkflowLayer));
 
     const servedRoutesLayer = HttpRouter.serve(makeRoutesLayer, {
       disableListenLog: true,
@@ -361,6 +520,12 @@ const buildAppUnderTest = (options?: {
         Layer.mock(ProviderRegistry)({
           getProviders: Effect.succeed([]),
           refresh: () => Effect.succeed([]),
+          refreshInstance: () => Effect.succeed([]),
+          getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+            Effect.succeed(
+              makeManualOnlyProviderMaintenanceCapabilities({ provider, packageName: null }),
+            ),
+          setProviderMaintenanceActionState: () => Effect.succeed([]),
           streamChanges: Stream.empty,
           ...options?.layers?.providerRegistry,
         }),
@@ -376,17 +541,82 @@ const buildAppUnderTest = (options?: {
         }),
       ),
       Layer.provide(
-        Layer.mock(Open)({
-          ...options?.layers?.open,
+        Layer.mock(ExternalLauncher.ExternalLauncher)({
+          ...options?.layers?.externalLauncher,
+        }),
+      ),
+      Layer.provide(
+        Layer.mock(ProcessDiagnostics.ProcessDiagnostics)({
+          read: Effect.succeed({
+            serverPid: process.pid,
+            readAt: TEST_EPOCH,
+            processCount: 0,
+            totalRssBytes: 0,
+            totalCpuPercent: 0,
+            processes: [],
+            error: Option.none(),
+          }),
+          signal: (input) =>
+            Effect.succeed({
+              pid: input.pid,
+              signal: input.signal,
+              signaled: true,
+              message: Option.none(),
+            }),
+        }),
+      ),
+      Layer.provide(
+        Layer.mock(ProcessResourceMonitor.ProcessResourceMonitor)({
+          readHistory: (input) =>
+            Effect.succeed({
+              readAt: TEST_EPOCH,
+              windowMs: input.windowMs,
+              bucketMs: input.bucketMs,
+              sampleIntervalMs: 5_000,
+              retainedSampleCount: 0,
+              totalCpuSecondsApprox: 0,
+              buckets: [],
+              topProcesses: [],
+              error: Option.none(),
+            }),
         }),
       ),
       Layer.provide(
-        Layer.mock(GitCore)({
-          ...options?.layers?.gitCore,
+        Layer.mock(TraceDiagnostics.TraceDiagnostics)({
+          read: () =>
+            Effect.succeed({
+              traceFilePath: "",
+              scannedFilePaths: [],
+              readAt: TEST_EPOCH,
+              recordCount: 0,
+              parseErrorCount: 0,
+              firstSpanAt: Option.none(),
+              lastSpanAt: Option.none(),
+              failureCount: 0,
+              interruptionCount: 0,
+              slowSpanThresholdMs: 1_000,
+              slowSpanCount: 0,
+              logLevelCounts: {},
+              topSpansByCount: [],
+              slowestSpans: [],
+              commonFailures: [],
+              latestFailures: [],
+              latestWarningAndErrorLogs: [],
+              partialFailure: Option.none(),
+              error: Option.none(),
+            }),
         }),
       ),
       Layer.provide(gitManagerLayer),
-      Layer.provideMerge(gitStatusBroadcasterLayer),
+      Layer.provide(gitVcsDriverLayer),
+      Layer.provide(gitWorkflowLayer),
+      Layer.provide(vcsProvisioningLayer),
+      Layer.provide(
+        Layer.mock(SourceControlRepositoryService.SourceControlRepositoryService)({
+          ...options?.layers?.sourceControlRepositoryService,
+        }),
+      ),
+      Layer.provideMerge(vcsStatusBroadcasterLayer),
       Layer.provide(
         Layer.mock(ProjectSetupScriptRunner)({
           runForThread: () => Effect.succeed({ status: "no-script" as const }),
@@ -400,7 +630,6 @@ const buildAppUnderTest = (options?: {
       ),
       Layer.provide(
         Layer.mock(OrchestrationEngineService)({
-          getReadModel: () => Effect.succeed(makeDefaultOrchestrationReadModel()),
           readEvents: () => Stream.empty,
           dispatch: () => Effect.succeed({ sequence: 0 }),
           streamDomainEvents: Stream.empty,
@@ -409,7 +638,30 @@ const buildAppUnderTest = (options?: {
       ),
       Layer.provide(
         Layer.mock(ProjectionSnapshotQuery)({
+          getCommandReadModel: () => Effect.succeed(makeDefaultOrchestrationReadModel()),
           getSnapshot: () => Effect.succeed(makeDefaultOrchestrationReadModel()),
+          getShellSnapshot: () =>
+            Effect.succeed({
+              snapshotSequence: 0,
+              projects: [],
+              threads: [],
+              updatedAt: "1970-01-01T00:00:00.000Z",
+            }),
+          getArchivedShellSnapshot: () =>
+            Effect.succeed({
+              snapshotSequence: 0,
+              projects: [],
+              threads: [],
+              updatedAt: "1970-01-01T00:00:00.000Z",
+            }),
+          getSnapshotSequence: () => Effect.succeed({ snapshotSequence: 0 }),
+          getProjectShellById: () => Effect.succeed(Option.none()),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
+          getCounts: () => Effect.succeed({ projectCount: 0, threadCount: 0 }),
+          getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+          getThreadCheckpointContext: () => Effect.succeed(Option.none()),
           ...options?.layers?.projectionSnapshotQuery,
         }),
       ),
@@ -470,7 +722,7 @@ const buildAppUnderTest = (options?: {
           ...options?.layers?.repositoryIdentityResolver,
         }),
       ),
-      Layer.provideMerge(authTestLayer),
+      Layer.provideMerge(makeAuthTestLayer()),
       Layer.provide(workspaceAndProjectServicesLayer),
       Layer.provideMerge(FetchHttpClient.layer),
       Layer.provide(layerConfig),
@@ -567,7 +819,12 @@ const bootstrapBrowserSession = (
     };
   });
 
-const bootstrapBearerSession = (credential = defaultDesktopBootstrapToken) =>
+const bootstrapBearerSession = (
+  credential = defaultDesktopBootstrapToken,
+  options?: {
+    readonly headers?: Record<string, string>;
+  },
+) =>
   Effect.gen(function* () {
     const bootstrapUrl = yield* getHttpServerUrl("/api/auth/bootstrap/bearer");
     const response = yield* Effect.promise(() =>
@@ -575,6 +832,7 @@ const bootstrapBearerSession = (credential = defaultDesktopBootstrapToken) =>
         method: "POST",
         headers: {
           "content-type": "application/json",
+          ...options?.headers,
         },
         body: JSON.stringify({
           credential,
@@ -594,17 +852,23 @@ const bootstrapBearerSession = (credential = defaultDesktopBootstrapToken) =>
     };
   });
 
+class AuthenticationGetterError extends Data.TaggedError("AuthenticationGetterError")<{
+  readonly message: string;
+}> {}
+
 const getAuthenticatedSessionCookieHeader = (credential = defaultDesktopBootstrapToken) =>
   Effect.gen(function* () {
     const { response, cookie } = yield* bootstrapBrowserSession(credential);
     if (!response.ok) {
-      return yield* Effect.fail(
-        new Error(`Expected bootstrap session response to succeed, got ${response.status}`),
-      );
+      return yield* new AuthenticationGetterError({
+        message: `Expected bootstrap session response to succeed, got ${response.status}`,
+      });
     }
 
     if (!cookie) {
-      return yield* Effect.fail(new Error("Expected bootstrap session response to set a cookie."));
+      return yield* new AuthenticationGetterError({
+        message: "Expected bootstrap session response to set a cookie.",
+      });
     }
 
     return cookie.split(";")[0] ?? cookie;
@@ -614,15 +878,15 @@ const getAuthenticatedBearerSessionToken = (credential = defaultDesktopBootstrap
   Effect.gen(function* () {
     const { response, body } = yield* bootstrapBearerSession(credential);
     if (!response.ok) {
-      return yield* Effect.fail(
-        new Error(`Expected bearer bootstrap response to succeed, got ${response.status}`),
-      );
+      return yield* new AuthenticationGetterError({
+        message: `Expected bearer bootstrap response to succeed, got ${response.status}`,
+      });
     }
 
     if (!body.sessionToken) {
-      return yield* Effect.fail(
-        new Error("Expected bearer bootstrap response to include a session token."),
-      );
+      return yield* new AuthenticationGetterError({
+        message: "Expected bearer bootstrap response to include a session token.",
+      });
     }
 
     return body.sessionToken;
@@ -644,6 +908,22 @@ const splitHeaderTokens = (value: string | null) =>
     .filter((token) => token.length > 0)
     .toSorted();
 
+const assertBrowserApiCorsHeaders = (headers: Headers) => {
+  assert.equal(headers.get("access-control-allow-origin"), "*");
+  assert.deepEqual(splitHeaderTokens(headers.get("access-control-allow-methods")), [
+    "GET",
+    "OPTIONS",
+    "POST",
+  ]);
+  assert.deepEqual(splitHeaderTokens(headers.get("access-control-allow-headers")), [
+    "authorization",
+    "b3",
+    "content-type",
+    "traceparent",
+  ]);
+};
+const crossOriginClientOrigin = "http://remote-client.test:3773";
+
 const getWsServerUrl = (
   pathname = "",
   options?: { authenticated?: boolean; credential?: string },
@@ -765,6 +1045,28 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("includes CORS headers on public environment descriptor responses", () =>
+    Effect.gen(function* () {
+      yield* buildAppUnderTest();
+
+      const url = yield* getHttpServerUrl("/.well-known/t3/environment");
+      const response = yield* Effect.promise(() =>
+        fetch(url, {
+          headers: {
+            origin: crossOriginClientOrigin,
+          },
+        }),
+      );
+      const body = (yield* Effect.promise(() =>
+        response.json(),
+      )) as typeof testEnvironmentDescriptor;
+
+      assert.equal(response.status, 200);
+      assertBrowserApiCorsHeaders(response.headers);
+      assert.deepEqual(body, testEnvironmentDescriptor);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("reports unauthenticated session state without requiring auth", () =>
     Effect.gen(function* () {
       yield* buildAppUnderTest();
@@ -888,6 +1190,62 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("includes CORS headers on remote auth success responses", () =>
+    Effect.gen(function* () {
+      yield* buildAppUnderTest();
+
+      const origin = crossOriginClientOrigin;
+      const { response: bootstrapResponse, body: bootstrapBody } = yield* bootstrapBearerSession(
+        defaultDesktopBootstrapToken,
+        {
+          headers: { origin },
+        },
+      );
+
+      assert.equal(bootstrapResponse.status, 200);
+      assertBrowserApiCorsHeaders(bootstrapResponse.headers);
+      assert.equal(bootstrapBody.authenticated, true);
+      assert.equal(typeof bootstrapBody.sessionToken, "string");
+
+      const sessionUrl = yield* getHttpServerUrl("/api/auth/session");
+      const sessionResponse = yield* Effect.promise(() =>
+        fetch(sessionUrl, {
+          headers: {
+            authorization: `Bearer ${bootstrapBody.sessionToken ?? ""}`,
+            origin,
+          },
+        }),
+      );
+      const sessionBody = (yield* Effect.promise(() => sessionResponse.json())) as {
+        readonly authenticated: boolean;
+        readonly sessionMethod?: string;
+      };
+
+      assert.equal(sessionResponse.status, 200);
+      assertBrowserApiCorsHeaders(sessionResponse.headers);
+      assert.equal(sessionBody.authenticated, true);
+      assert.equal(sessionBody.sessionMethod, "bearer-session-token");
+
+      const wsTokenUrl = yield* getHttpServerUrl("/api/auth/ws-token");
+      const wsTokenResponse = yield* Effect.promise(() =>
+        fetch(wsTokenUrl, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${bootstrapBody.sessionToken ?? ""}`,
+            origin,
+          },
+        }),
+      );
+      const wsTokenBody = (yield* Effect.promise(() => wsTokenResponse.json())) as {
+        readonly token: string;
+      };
+
+      assert.equal(wsTokenResponse.status, 200);
+      assertBrowserApiCorsHeaders(wsTokenResponse.headers);
+      assert.equal(typeof wsTokenBody.token, "string");
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect(
     "responds to remote auth websocket-token preflight requests with authorization CORS headers",
     () =>
@@ -899,7 +1257,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
           fetch(wsTokenUrl, {
             method: "OPTIONS",
             headers: {
-              origin: "http://192.168.86.35:3773",
+              origin: crossOriginClientOrigin,
               "access-control-request-method": "POST",
               "access-control-request-headers": "authorization",
             },
@@ -907,18 +1265,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         );
 
         assert.equal(response.status, 204);
-        assert.equal(response.headers.get("access-control-allow-origin"), "*");
-        assert.deepEqual(splitHeaderTokens(response.headers.get("access-control-allow-methods")), [
-          "GET",
-          "OPTIONS",
-          "POST",
-        ]);
-        assert.deepEqual(splitHeaderTokens(response.headers.get("access-control-allow-headers")), [
-          "authorization",
-          "b3",
-          "content-type",
-          "traceparent",
-        ]);
+        assertBrowserApiCorsHeaders(response.headers);
       }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
@@ -931,7 +1278,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         fetch(wsTokenUrl, {
           method: "POST",
           headers: {
-            origin: "http://192.168.86.35:3773",
+            origin: crossOriginClientOrigin,
           },
         }),
       );
@@ -940,7 +1287,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       };
 
       assert.equal(response.status, 401);
-      assert.equal(response.headers.get("access-control-allow-origin"), "*");
+      assertBrowserApiCorsHeaders(response.headers);
       assert.equal(body.error, "Authentication required.");
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
@@ -1529,6 +1876,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
           "content-type": "application/json",
           origin: "http://localhost:5733",
         },
+        // @effect-diagnostics-next-line preferSchemaOverJson:off
         body: HttpBody.text(JSON.stringify(payload), "application/json"),
       });
 
@@ -1574,6 +1922,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       ]);
       assert.deepEqual(upstreamRequests, [
         {
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           body: JSON.stringify(payload),
           contentType: "application/json",
         },
@@ -1646,6 +1995,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             cookie: yield* getAuthenticatedSessionCookieHeader(),
             "content-type": "application/json",
           },
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
           body: HttpBody.text(JSON.stringify(payload), "application/json"),
         });
 
@@ -1737,6 +2087,42 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("routes websocket rpc server.removeKeybinding", () =>
+    Effect.gen(function* () {
+      const rule: KeybindingRule = {
+        command: "terminal.toggle",
+        key: "ctrl+k",
+      };
+      const resolved: ResolvedKeybindingRule = {
+        command: "terminal.toggle",
+        shortcut: {
+          key: "j",
+          metaKey: false,
+          ctrlKey: false,
+          shiftKey: false,
+          altKey: false,
+          modKey: true,
+        },
+      };
+
+      yield* buildAppUnderTest({
+        layers: {
+          keybindings: {
+            removeKeybindingRule: () => Effect.succeed([resolved]),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const response = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.serverRemoveKeybinding](rule)),
+      );
+
+      assert.deepEqual(response.issues, []);
+      assert.deepEqual(response.keybindings, [resolved]);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("rejects websocket rpc handshake when session authentication is missing", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
@@ -1761,13 +2147,34 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       );
 
       assertTrue(result._tag === "Failure");
-      assertInclude(String(result.failure), "SocketOpenError");
+      const failureMessage = String(result.failure);
+      assertTrue(
+        failureMessage.includes("SocketOpenError") || failureMessage.includes("SocketCloseError"),
+      );
+      assertTrue(
+        failureMessage.includes("Unauthorized") ||
+          failureMessage.includes("An error occurred during Open"),
+      );
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
   it.effect("routes websocket rpc subscribeServerConfig streams snapshot then update", () =>
     Effect.gen(function* () {
-      const providers = [] as const;
+      const providers = [
+        {
+          instanceId: ProviderInstanceId.make("codex"),
+          driver: ProviderDriverKind.make("codex"),
+          enabled: true,
+          installed: true,
+          version: "1.0.0",
+          status: "ready" as const,
+          auth: { status: "authenticated" as const },
+          checkedAt: "2026-04-11T00:00:00.000Z",
+          models: [],
+          slashCommands: [],
+          skills: [],
+        },
+      ] as const;
       const changeEvent = {
         keybindings: [],
         issues: [],
@@ -1817,14 +2224,28 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       assert.deepEqual(second, {
         version: 1,
         type: "keybindingsUpdated",
-        payload: { issues: [] },
+        payload: { keybindings: [], issues: [] },
       });
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
   it.effect("routes websocket rpc subscribeServerConfig emits provider status updates", () =>
     Effect.gen(function* () {
-      const providers = [] as const;
+      const nextProviders = [
+        {
+          instanceId: ProviderInstanceId.make("codex"),
+          driver: ProviderDriverKind.make("codex"),
+          enabled: true,
+          installed: true,
+          version: "1.0.0",
+          status: "ready" as const,
+          auth: { status: "authenticated" as const },
+          checkedAt: "2026-04-11T00:00:00.000Z",
+          models: [],
+          slashCommands: [],
+          skills: [],
+        },
+      ] as const;
 
       yield* buildAppUnderTest({
         layers: {
@@ -1837,7 +2258,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
           },
           providerRegistry: {
             getProviders: Effect.succeed([]),
-            streamChanges: Stream.succeed(providers),
+            streamChanges: Stream.succeed(nextProviders),
           },
         },
       });
@@ -1851,10 +2272,13 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
       const [first, second] = Array.from(events);
       assert.equal(first?.type, "snapshot");
+      if (first?.type === "snapshot") {
+        assert.deepEqual(first.config.providers, []);
+      }
       assert.deepEqual(second, {
         version: 1,
         type: "providerStatuses",
-        payload: { providers },
+        payload: { providers: nextProviders },
       });
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
@@ -1879,7 +2303,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
           version: 1 as const,
           sequence: 2,
           type: "ready" as const,
-          payload: { at: new Date().toISOString(), environment: testEnvironmentDescriptor },
+          payload: { at: "2026-01-01T00:00:00.000Z", environment: testEnvironmentDescriptor },
         });
 
         yield* buildAppUnderTest({
@@ -1938,6 +2362,63 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("routes websocket rpc projects.searchEntries excludes gitignored files", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const workspaceDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "t3-ws-project-search-gitignored-",
+      });
+      yield* fs.writeFileString(path.join(workspaceDir, ".gitignore"), ".venv/\n");
+      yield* fs.makeDirectory(path.join(workspaceDir, ".venv", "lib"), { recursive: true });
+      yield* fs.writeFileString(
+        path.join(workspaceDir, ".venv", "lib", "ignored-search-target.ts"),
+        "export const ignored = true;",
+      );
+      yield* fs.makeDirectory(path.join(workspaceDir, "src"), { recursive: true });
+      yield* fs.writeFileString(
+        path.join(workspaceDir, "src", "tracked.ts"),
+        "export const ok = 1;",
+      );
+
+      yield* buildAppUnderTest({
+        layers: {
+          vcsDriver: {
+            isInsideWorkTree: () => Effect.succeed(true),
+            listWorkspaceFiles: () =>
+              Effect.succeed({
+                paths: ["src/tracked.ts"],
+                truncated: false,
+                freshness: {
+                  source: "live-local",
+                  observedAt: TEST_EPOCH,
+                  expiresAt: Option.none(),
+                },
+              }),
+            filterIgnoredPaths: (_cwd, relativePaths) =>
+              Effect.succeed(
+                relativePaths.filter((relativePath) => !relativePath.startsWith(".venv/")),
+              ),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const response = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[WS_METHODS.projectsSearchEntries]({
+            cwd: workspaceDir,
+            query: "ignored-search-target",
+            limit: 10,
+          }),
+        ),
+      );
+
+      assert.equal(response.entries.length, 0);
+      assert.equal(response.truncated, false);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("routes websocket rpc projects.searchEntries errors", () =>
     Effect.gen(function* () {
       yield* buildAppUnderTest();
@@ -1987,6 +2468,40 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("creates a missing workspace root during websocket project.create dispatch", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const parentDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-ws-project-create-" });
+      const missingWorkspaceRoot = path.join(parentDir, "nested", "new-project");
+
+      yield* buildAppUnderTest();
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const response = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
+            type: "project.create",
+            commandId: CommandId.make("cmd-project-create-missing-root"),
+            projectId: ProjectId.make("project-create-missing-root"),
+            title: "New Project",
+            workspaceRoot: missingWorkspaceRoot,
+            createWorkspaceRootIfMissing: true,
+            defaultModelSelection: {
+              instanceId: ProviderInstanceId.make("codex"),
+              model: "gpt-5-codex",
+            },
+            createdAt: "2026-01-01T00:00:00.000Z",
+          }),
+        ),
+      );
+      const stat = yield* fs.stat(missingWorkspaceRoot);
+
+      assert.isAtLeast(response.sequence, 0);
+      assert.equal(stat.type, "Directory");
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("routes websocket rpc projects.writeFile errors", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
@@ -2019,8 +2534,8 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       let openedInput: { cwd: string; editor: EditorId } | null = null;
       yield* buildAppUnderTest({
         layers: {
-          open: {
-            openInEditor: (input) =>
+          externalLauncher: {
+            launchEditor: (input) =>
               Effect.sync(() => {
                 openedInput = input;
               }),
@@ -2044,11 +2559,13 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
   it.effect("routes websocket rpc shell.openInEditor errors", () =>
     Effect.gen(function* () {
-      const openError = new OpenError({ message: "Editor command not found: cursor" });
+      const externalLauncherError = new ExternalLauncherError({
+        message: "Editor command not found: cursor",
+      });
       yield* buildAppUnderTest({
         layers: {
-          open: {
-            openInEditor: () => Effect.fail(openError),
+          externalLauncher: {
+            launchEditor: () => Effect.fail(externalLauncherError),
           },
         },
       });
@@ -2063,7 +2580,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         ).pipe(Effect.result),
       );
 
-      assertFailure(result, openError);
+      assertFailure(result, externalLauncherError);
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
@@ -2078,9 +2595,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             localStatus: () =>
               Effect.succeed({
                 isRepo: true,
-                hasOriginRemote: true,
-                isDefaultBranch: true,
-                branch: "main",
+                hasPrimaryRemote: true,
+                isDefaultRef: true,
+                refName: "main",
                 hasWorkingTreeChanges: false,
                 workingTree: { files: [], insertions: 0, deletions: 0 },
               }),
@@ -2094,9 +2611,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             status: () =>
               Effect.succeed({
                 isRepo: true,
-                hasOriginRemote: true,
-                isDefaultBranch: true,
-                branch: "main",
+                hasPrimaryRemote: true,
+                isDefaultRef: true,
+                refName: "main",
                 hasWorkingTreeChanges: false,
                 workingTree: { files: [], insertions: 0, deletions: 0 },
                 hasUpstream: true,
@@ -2177,16 +2694,16 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                 worktreePath: null,
               }),
           },
-          gitCore: {
+          gitVcsDriver: {
             pullCurrentBranch: () =>
               Effect.succeed({
                 status: "pulled",
-                branch: "main",
-                upstreamBranch: "origin/main",
+                refName: "main",
+                upstreamRef: "origin/main",
               }),
-            listBranches: () =>
+            listRefs: () =>
               Effect.succeed({
-                branches: [
+                refs: [
                   {
                     name: "main",
                     current: true,
@@ -2195,18 +2712,20 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                   },
                 ],
                 isRepo: true,
-                hasOriginRemote: true,
+                hasPrimaryRemote: true,
                 nextCursor: null,
                 totalCount: 1,
               }),
             createWorktree: () =>
               Effect.succeed({
-                worktree: { path: "/tmp/wt", branch: "feature/demo" },
+                worktree: { path: "/tmp/wt", refName: "feature/demo" },
               }),
             removeWorktree: () => Effect.void,
-            createBranch: (input) => Effect.succeed({ branch: input.branch }),
-            checkoutBranch: (input) => Effect.succeed({ branch: input.branch }),
-            initRepo: () => Effect.void,
+            createRef: (input) => Effect.succeed({ refName: input.refName }),
+            switchRef: (input) => Effect.succeed({ refName: input.refName }),
+          },
+          vcsDriver: {
+            isInsideWorkTree: () => Effect.succeed(true),
           },
         },
       });
@@ -2214,13 +2733,13 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       const wsUrl = yield* getWsServerUrl("/ws");
 
       const pull = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.gitPull]({ cwd: "/tmp/repo" })),
+        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.vcsPull]({ cwd: "/tmp/repo" })),
       );
       assert.equal(pull.status, "pulled");
 
       const refreshedStatus = yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.gitRefreshStatus]({ cwd: "/tmp/repo" }),
+          client[WS_METHODS.vcsRefreshStatus]({ cwd: "/tmp/repo" }),
         ),
       );
       assert.equal(refreshedStatus.isRepo, true);
@@ -2264,27 +2783,25 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       );
       assert.equal(prepared.branch, "feature/demo");
 
-      const branches = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.gitListBranches]({ cwd: "/tmp/repo" }),
-        ),
+      const refs = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.vcsListRefs]({ cwd: "/tmp/repo" })),
       );
-      assert.equal(branches.branches[0]?.name, "main");
+      assert.equal(refs.refs[0]?.name, "main");
 
       const worktree = yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.gitCreateWorktree]({
+          client[WS_METHODS.vcsCreateWorktree]({
             cwd: "/tmp/repo",
-            branch: "main",
+            refName: "main",
             path: null,
           }),
         ),
       );
-      assert.equal(worktree.worktree.branch, "feature/demo");
+      assert.equal(worktree.worktree.refName, "feature/demo");
 
       yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.gitRemoveWorktree]({
+          client[WS_METHODS.vcsRemoveWorktree]({
             cwd: "/tmp/repo",
             path: "/tmp/wt",
           }),
@@ -2293,25 +2810,25 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
       yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.gitCreateBranch]({
+          client[WS_METHODS.vcsCreateRef]({
             cwd: "/tmp/repo",
-            branch: "feature/new",
+            refName: "feature/new",
           }),
         ),
       );
 
       yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.gitCheckout]({
+          client[WS_METHODS.vcsSwitchRef]({
             cwd: "/tmp/repo",
-            branch: "main",
+            refName: "main",
           }),
         ),
       );
 
       yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.gitInit]({
+          client[WS_METHODS.vcsInit]({
             cwd: "/tmp/repo",
           }),
         ),
@@ -2331,7 +2848,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       let statusCalls = 0;
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             pullCurrentBranch: () => Effect.fail(gitError),
           },
           gitManager: {
@@ -2350,9 +2867,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             localStatus: () =>
               Effect.succeed({
                 isRepo: true,
-                hasOriginRemote: true,
-                isDefaultBranch: true,
-                branch: "main",
+                hasPrimaryRemote: true,
+                isDefaultRef: true,
+                refName: "main",
                 hasWorkingTreeChanges: true,
                 workingTree: { files: [], insertions: 0, deletions: 0 },
               }),
@@ -2371,9 +2888,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                 statusCalls += 1;
                 return {
                   isRepo: true,
-                  hasOriginRemote: true,
-                  isDefaultBranch: true,
-                  branch: "main",
+                  hasPrimaryRemote: true,
+                  isDefaultRef: true,
+                  refName: "main",
                   hasWorkingTreeChanges: true,
                   workingTree: { files: [], insertions: 0, deletions: 0 },
                   hasUpstream: true,
@@ -2388,7 +2905,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
       const wsUrl = yield* getWsServerUrl("/ws");
       const result = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.gitPull]({ cwd: "/tmp/repo" })).pipe(
+        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.vcsPull]({ cwd: "/tmp/repo" })).pipe(
           Effect.result,
         ),
       );
@@ -2427,9 +2944,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             localStatus: () =>
               Effect.succeed({
                 isRepo: true,
-                hasOriginRemote: true,
-                isDefaultBranch: false,
-                branch: "feature/demo",
+                hasPrimaryRemote: true,
+                isDefaultRef: false,
+                refName: "feature/demo",
                 hasWorkingTreeChanges: true,
                 workingTree: { files: [], insertions: 0, deletions: 0 },
               }),
@@ -2448,9 +2965,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                 statusCalls += 1;
                 return {
                   isRepo: true,
-                  hasOriginRemote: true,
-                  isDefaultBranch: false,
-                  branch: "feature/demo",
+                  hasPrimaryRemote: true,
+                  isDefaultRef: false,
+                  refName: "feature/demo",
                   hasWorkingTreeChanges: true,
                   workingTree: { files: [], insertions: 0, deletions: 0 },
                   hasUpstream: true,
@@ -2485,12 +3002,12 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     Effect.gen(function* () {
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             pullCurrentBranch: () =>
               Effect.succeed({
                 status: "pulled" as const,
-                branch: "main",
-                upstreamBranch: "origin/main",
+                refName: "main",
+                upstreamRef: "origin/main",
               }),
           },
           gitManager: {
@@ -2499,9 +3016,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             localStatus: () =>
               Effect.succeed({
                 isRepo: true,
-                hasOriginRemote: true,
-                isDefaultBranch: true,
-                branch: "main",
+                hasPrimaryRemote: true,
+                isDefaultRef: true,
+                refName: "main",
                 hasWorkingTreeChanges: false,
                 workingTree: { files: [], insertions: 0, deletions: 0 },
               }),
@@ -2519,11 +3036,11 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       });
 
       const wsUrl = yield* getWsServerUrl("/ws");
-      const startedAt = Date.now();
+      const startedAt = yield* Clock.currentTimeMillis;
       const result = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.gitPull]({ cwd: "/tmp/repo" })),
+        withWsRpcClient(wsUrl, (client) => client[WS_METHODS.vcsPull]({ cwd: "/tmp/repo" })),
       );
-      const elapsedMs = Date.now() - startedAt;
+      const elapsedMs = (yield* Clock.currentTimeMillis) - startedAt;
 
       assert.equal(result.status, "pulled");
       assertTrue(elapsedMs < 1_000);
@@ -2536,15 +3053,18 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       Effect.gen(function* () {
         yield* buildAppUnderTest({
           layers: {
+            vcsDriver: {
+              isInsideWorkTree: () => Effect.succeed(true),
+            },
             gitManager: {
               invalidateLocalStatus: () => Effect.void,
               invalidateRemoteStatus: () => Effect.void,
               localStatus: () =>
                 Effect.succeed({
                   isRepo: true,
-                  hasOriginRemote: true,
-                  isDefaultBranch: false,
-                  branch: "feature/demo",
+                  hasPrimaryRemote: true,
+                  isDefaultRef: false,
+                  refName: "feature/demo",
                   hasWorkingTreeChanges: false,
                   workingTree: { files: [], insertions: 0, deletions: 0 },
                 }),
@@ -2585,7 +3105,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         });
 
         const wsUrl = yield* getWsServerUrl("/ws");
-        const startedAt = Date.now();
+        const startedAt = yield* Clock.currentTimeMillis;
         yield* Effect.scoped(
           withWsRpcClient(wsUrl, (client) =>
             client[WS_METHODS.gitRunStackedAction]({
@@ -2595,7 +3115,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             }).pipe(Stream.runCollect),
           ),
         );
-        const elapsedMs = Date.now() - startedAt;
+        const elapsedMs = (yield* Clock.currentTimeMillis) - startedAt;
 
         assertTrue(elapsedMs < 1_000);
       }).pipe(Effect.provide(NodeHttpServer.layerTest)),
@@ -2609,6 +3129,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
         yield* buildAppUnderTest({
           layers: {
+            vcsDriver: {
+              isInsideWorkTree: () => Effect.succeed(true),
+            },
             gitManager: {
               invalidateLocalStatus: () => Effect.void,
               invalidateRemoteStatus: () => Effect.void,
@@ -2618,9 +3141,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                   Effect.andThen(
                     Effect.succeed({
                       isRepo: true,
-                      hasOriginRemote: true,
-                      isDefaultBranch: false,
-                      branch: "feature/demo",
+                      hasPrimaryRemote: true,
+                      isDefaultRef: false,
+                      refName: "feature/demo",
                       hasWorkingTreeChanges: false,
                       workingTree: { files: [], insertions: 0, deletions: 0 },
                     }),
@@ -2679,7 +3202,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
   it.effect("routes websocket rpc orchestration methods", () =>
     Effect.gen(function* () {
-      const now = new Date().toISOString();
+      const now = "2026-01-01T00:00:00.000Z";
       const snapshot = {
         snapshotSequence: 1,
         updatedAt: now,
@@ -2748,11 +3271,6 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       });
 
       const wsUrl = yield* getWsServerUrl("/ws");
-      const snapshotResult = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) => client[ORCHESTRATION_WS_METHODS.getSnapshot]({})),
-      );
-      assert.equal(snapshotResult.snapshotSequence, 1);
-
       const dispatchResult = yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
           client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
@@ -2797,16 +3315,44 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
-  it.effect("enriches replayed project events with repository identity metadata", () =>
+  it.effect("routes websocket rpc orchestration shell snapshot errors", () =>
     Effect.gen(function* () {
-      const repositoryIdentity = {
-        canonicalKey: "github.com/t3tools/t3code",
-        locator: {
-          source: "git-remote" as const,
-          remoteName: "origin",
-          remoteUrl: "git@github.com:T3Tools/t3code.git",
-        },
-        displayName: "T3Tools/t3code",
+      const projectionError = new PersistenceSqlError({
+        operation: "ProjectionSnapshotQuery.getShellSnapshot:test",
+        detail: "failed to read projection shell snapshot",
+      });
+      yield* buildAppUnderTest({
+        layers: {
+          projectionSnapshotQuery: {
+            getShellSnapshot: () => Effect.fail(projectionError),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const result = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.subscribeShell]({}).pipe(Stream.runCollect),
+        ).pipe(Effect.result),
+      );
+
+      assertTrue(result._tag === "Failure");
+      assertTrue(result.failure._tag === "OrchestrationGetSnapshotError");
+      assertTrue(result.failure.cause instanceof Error);
+      assert.include(result.failure.cause.message, projectionError.message);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("enriches replayed project events with repository identity metadata", () =>
+    Effect.gen(function* () {
+      const repositoryIdentity = {
+        canonicalKey: "github.com/t3tools/t3code",
+        locator: {
+          source: "git-remote" as const,
+          remoteName: "origin",
+          remoteUrl: "git@github.com:T3Tools/t3code.git",
+        },
+        displayName: "T3Tools/t3code",
         provider: "github",
         owner: "T3Tools",
         name: "t3code",
@@ -2864,21 +3410,48 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
-  it.effect("closes thread terminals after a successful archive command", () =>
+  it.effect("stops the provider session and closes thread terminals after archive", () =>
     Effect.gen(function* () {
       const threadId = ThreadId.make("thread-archive");
-      const closeInputs: Array<Parameters<TerminalManagerShape["close"]>[0]> = [];
+      const effects: string[] = [];
+      const dispatchedCommands: Array<OrchestrationCommand> = [];
+      const now = "2026-01-01T00:00:00.000Z";
 
       yield* buildAppUnderTest({
         layers: {
           terminalManager: {
             close: (input) =>
               Effect.sync(() => {
-                closeInputs.push(input);
+                effects.push(`terminal.close:${input.threadId}`);
               }),
           },
           orchestrationEngine: {
-            dispatch: () => Effect.succeed({ sequence: 8 }),
+            dispatch: (command) =>
+              Effect.sync(() => {
+                dispatchedCommands.push(command);
+                effects.push(`dispatch:${command.type}`);
+                return { sequence: dispatchedCommands.length };
+              }),
+          },
+          projectionSnapshotQuery: {
+            getThreadShellById: () =>
+              Effect.succeed(
+                Option.some(
+                  makeDefaultOrchestrationThreadShell({
+                    id: threadId,
+                    updatedAt: now,
+                    session: {
+                      threadId,
+                      status: "ready",
+                      providerName: "claudeAgent",
+                      runtimeMode: "full-access",
+                      activeTurnId: null,
+                      lastError: null,
+                      updatedAt: now,
+                    },
+                  }),
+                ),
+              ),
           },
         },
       });
@@ -2894,8 +3467,363 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         ),
       );
 
-      assert.equal(dispatchResult.sequence, 8);
-      assert.deepEqual(closeInputs, [{ threadId }]);
+      assert.equal(dispatchResult.sequence, 1);
+      assert.deepEqual(effects, [
+        "dispatch:thread.archive",
+        "dispatch:thread.session.stop",
+        `terminal.close:${threadId}`,
+      ]);
+      const sessionStopCommand = dispatchedCommands[1];
+      assert.equal(sessionStopCommand?.type, "thread.session.stop");
+      if (sessionStopCommand?.type === "thread.session.stop") {
+        assert.equal(sessionStopCommand.threadId, threadId);
+      }
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("checks session status before archiving removes the thread from active lookups", () =>
+    Effect.gen(function* () {
+      const threadId = ThreadId.make("thread-archive-precheck");
+      const effects: string[] = [];
+      const dispatchedCommands: Array<OrchestrationCommand> = [];
+      const now = "2026-01-01T00:00:00.000Z";
+      let archived = false;
+
+      yield* buildAppUnderTest({
+        layers: {
+          terminalManager: {
+            close: (input) =>
+              Effect.sync(() => {
+                effects.push(`terminal.close:${input.threadId}`);
+              }),
+          },
+          orchestrationEngine: {
+            dispatch: (command) =>
+              Effect.sync(() => {
+                dispatchedCommands.push(command);
+                effects.push(`dispatch:${command.type}`);
+                if (command.type === "thread.archive") {
+                  archived = true;
+                }
+                return { sequence: dispatchedCommands.length };
+              }),
+          },
+          projectionSnapshotQuery: {
+            getThreadShellById: () =>
+              Effect.sync(() => {
+                effects.push(`query:thread-shell:${archived ? "archived" : "active"}`);
+                return archived
+                  ? Option.none()
+                  : Option.some(
+                      makeDefaultOrchestrationThreadShell({
+                        id: threadId,
+                        updatedAt: now,
+                        session: {
+                          threadId,
+                          status: "ready",
+                          providerName: "claudeAgent",
+                          runtimeMode: "full-access",
+                          activeTurnId: null,
+                          lastError: null,
+                          updatedAt: now,
+                        },
+                      }),
+                    );
+              }),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const dispatchResult = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
+            type: "thread.archive",
+            commandId: CommandId.make("cmd-thread-archive-precheck"),
+            threadId,
+          }),
+        ),
+      );
+
+      assert.equal(dispatchResult.sequence, 1);
+      assert.deepEqual(effects, [
+        "query:thread-shell:active",
+        "dispatch:thread.archive",
+        "dispatch:thread.session.stop",
+        `terminal.close:${threadId}`,
+      ]);
+      assert.deepEqual(
+        dispatchedCommands.map((command) => command.type),
+        ["thread.archive", "thread.session.stop"],
+      );
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("archives without dispatching session stop when the thread has no session", () =>
+    Effect.gen(function* () {
+      const threadId = ThreadId.make("thread-archive-no-session");
+      const effects: string[] = [];
+      const dispatchedCommands: Array<OrchestrationCommand> = [];
+
+      yield* buildAppUnderTest({
+        layers: {
+          terminalManager: {
+            close: (input) =>
+              Effect.sync(() => {
+                effects.push(`terminal.close:${input.threadId}`);
+              }),
+          },
+          orchestrationEngine: {
+            dispatch: (command) =>
+              Effect.sync(() => {
+                dispatchedCommands.push(command);
+                effects.push(`dispatch:${command.type}`);
+                return { sequence: dispatchedCommands.length };
+              }),
+          },
+          projectionSnapshotQuery: {
+            getThreadShellById: () =>
+              Effect.succeed(
+                Option.some(makeDefaultOrchestrationThreadShell({ id: threadId, session: null })),
+              ),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const dispatchResult = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
+            type: "thread.archive",
+            commandId: CommandId.make("cmd-thread-archive-no-session"),
+            threadId,
+          }),
+        ),
+      );
+
+      assert.equal(dispatchResult.sequence, 1);
+      assert.deepEqual(effects, ["dispatch:thread.archive", `terminal.close:${threadId}`]);
+      assert.deepEqual(
+        dispatchedCommands.map((command) => command.type),
+        ["thread.archive"],
+      );
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect(
+    "archives without dispatching session stop when the thread session is already stopped",
+    () =>
+      Effect.gen(function* () {
+        const threadId = ThreadId.make("thread-archive-stopped-session");
+        const effects: string[] = [];
+        const dispatchedCommands: Array<OrchestrationCommand> = [];
+        const now = "2026-01-01T00:00:00.000Z";
+
+        yield* buildAppUnderTest({
+          layers: {
+            terminalManager: {
+              close: (input) =>
+                Effect.sync(() => {
+                  effects.push(`terminal.close:${input.threadId}`);
+                }),
+            },
+            orchestrationEngine: {
+              dispatch: (command) =>
+                Effect.sync(() => {
+                  dispatchedCommands.push(command);
+                  effects.push(`dispatch:${command.type}`);
+                  return { sequence: dispatchedCommands.length };
+                }),
+            },
+            projectionSnapshotQuery: {
+              getThreadShellById: () =>
+                Effect.succeed(
+                  Option.some(
+                    makeDefaultOrchestrationThreadShell({
+                      id: threadId,
+                      updatedAt: now,
+                      session: {
+                        threadId,
+                        status: "stopped",
+                        providerName: "claudeAgent",
+                        runtimeMode: "full-access",
+                        activeTurnId: null,
+                        lastError: null,
+                        updatedAt: now,
+                      },
+                    }),
+                  ),
+                ),
+            },
+          },
+        });
+
+        const wsUrl = yield* getWsServerUrl("/ws");
+        const dispatchResult = yield* Effect.scoped(
+          withWsRpcClient(wsUrl, (client) =>
+            client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
+              type: "thread.archive",
+              commandId: CommandId.make("cmd-thread-archive-stopped-session"),
+              threadId,
+            }),
+          ),
+        );
+
+        assert.equal(dispatchResult.sequence, 1);
+        assert.deepEqual(effects, ["dispatch:thread.archive", `terminal.close:${threadId}`]);
+        assert.deepEqual(
+          dispatchedCommands.map((command) => command.type),
+          ["thread.archive"],
+        );
+      }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("archives and still closes terminals when session stop fails", () =>
+    Effect.gen(function* () {
+      const threadId = ThreadId.make("thread-archive-stop-failure");
+      const effects: string[] = [];
+      const dispatchedCommands: Array<OrchestrationCommand> = [];
+      const now = "2026-01-01T00:00:00.000Z";
+
+      yield* buildAppUnderTest({
+        layers: {
+          terminalManager: {
+            close: (input) =>
+              Effect.sync(() => {
+                effects.push(`terminal.close:${input.threadId}`);
+              }),
+          },
+          orchestrationEngine: {
+            dispatch: (command) => {
+              dispatchedCommands.push(command);
+              effects.push(`dispatch:${command.type}`);
+              if (command.type === "thread.session.stop") {
+                return Effect.fail(
+                  new OrchestrationListenerCallbackError({
+                    listener: "domain-event",
+                    detail: "simulated archive stop failure",
+                  }),
+                );
+              }
+              return Effect.succeed({ sequence: dispatchedCommands.length });
+            },
+          },
+          projectionSnapshotQuery: {
+            getThreadShellById: () =>
+              Effect.succeed(
+                Option.some(
+                  makeDefaultOrchestrationThreadShell({
+                    id: threadId,
+                    updatedAt: now,
+                    session: {
+                      threadId,
+                      status: "ready",
+                      providerName: "claudeAgent",
+                      runtimeMode: "full-access",
+                      activeTurnId: null,
+                      lastError: null,
+                      updatedAt: now,
+                    },
+                  }),
+                ),
+              ),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const dispatchResult = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
+            type: "thread.archive",
+            commandId: CommandId.make("cmd-thread-archive-stop-failure"),
+            threadId,
+          }),
+        ),
+      );
+
+      assert.equal(dispatchResult.sequence, 1);
+      assert.deepEqual(effects, [
+        "dispatch:thread.archive",
+        "dispatch:thread.session.stop",
+        `terminal.close:${threadId}`,
+      ]);
+      assert.deepEqual(
+        dispatchedCommands.map((command) => command.type),
+        ["thread.archive", "thread.session.stop"],
+      );
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("archives and still closes terminals when session stop defects", () =>
+    Effect.gen(function* () {
+      const threadId = ThreadId.make("thread-archive-stop-defect");
+      const effects: string[] = [];
+      const dispatchedCommands: Array<OrchestrationCommand> = [];
+      const now = "2026-01-01T00:00:00.000Z";
+
+      yield* buildAppUnderTest({
+        layers: {
+          terminalManager: {
+            close: (input) =>
+              Effect.sync(() => {
+                effects.push(`terminal.close:${input.threadId}`);
+              }),
+          },
+          orchestrationEngine: {
+            dispatch: (command) => {
+              dispatchedCommands.push(command);
+              effects.push(`dispatch:${command.type}`);
+              if (command.type === "thread.session.stop") {
+                return Effect.die(new Error("simulated archive stop defect"));
+              }
+              return Effect.succeed({ sequence: dispatchedCommands.length });
+            },
+          },
+          projectionSnapshotQuery: {
+            getThreadShellById: () =>
+              Effect.succeed(
+                Option.some(
+                  makeDefaultOrchestrationThreadShell({
+                    id: threadId,
+                    updatedAt: now,
+                    session: {
+                      threadId,
+                      status: "ready",
+                      providerName: "claudeAgent",
+                      runtimeMode: "full-access",
+                      activeTurnId: null,
+                      lastError: null,
+                      updatedAt: now,
+                    },
+                  }),
+                ),
+              ),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const dispatchResult = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
+            type: "thread.archive",
+            commandId: CommandId.make("cmd-thread-archive-stop-defect"),
+            threadId,
+          }),
+        ),
+      );
+
+      assert.equal(dispatchResult.sequence, 1);
+      assert.deepEqual(effects, [
+        "dispatch:thread.archive",
+        "dispatch:thread.session.stop",
+        `terminal.close:${threadId}`,
+      ]);
+      assert.deepEqual(
+        dispatchedCommands.map((command) => command.type),
+        ["thread.archive", "thread.session.stop"],
+      );
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
@@ -2904,14 +3832,33 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     () =>
       Effect.gen(function* () {
         const dispatchedCommands: Array<OrchestrationCommand> = [];
-        const createWorktree = vi.fn((_: Parameters<GitCoreShape["createWorktree"]>[0]) =>
+        const refreshStatus = vi.fn((_: string) =>
           Effect.succeed({
-            worktree: {
-              branch: "t3code/bootstrap-branch",
-              path: "/tmp/bootstrap-worktree",
+            isRepo: true,
+            hasPrimaryRemote: true,
+            isDefaultRef: false,
+            refName: "t3code/bootstrap-refName",
+            hasWorkingTreeChanges: false,
+            workingTree: {
+              files: [],
+              insertions: 0,
+              deletions: 0,
             },
+            hasUpstream: true,
+            aheadCount: 0,
+            behindCount: 0,
+            pr: null,
           }),
         );
+        const createWorktree = vi.fn(
+          (_: Parameters<GitVcsDriver.GitVcsDriverShape["createWorktree"]>[0]) =>
+            Effect.succeed({
+              worktree: {
+                refName: "t3code/bootstrap-refName",
+                path: "/tmp/bootstrap-worktree",
+              },
+            }),
+        );
         const runForThread = vi.fn(
           (_: Parameters<ProjectSetupScriptRunnerShape["runForThread"]>[0]) =>
             Effect.succeed({
@@ -2925,9 +3872,12 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
         yield* buildAppUnderTest({
           layers: {
-            gitCore: {
+            gitVcsDriver: {
               createWorktree,
             },
+            vcsStatusBroadcaster: {
+              refreshStatus,
+            },
             orchestrationEngine: {
               dispatch: (command) =>
                 Effect.sync(() => {
@@ -2942,7 +3892,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
           },
         });
 
-        const createdAt = new Date().toISOString();
+        const createdAt = "2026-01-01T00:00:00.000Z";
         const wsUrl = yield* getWsServerUrl("/ws");
         const response = yield* Effect.scoped(
           withWsRpcClient(wsUrl, (client) =>
@@ -2973,7 +3923,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                 prepareWorktree: {
                   projectCwd: "/tmp/project",
                   baseBranch: "main",
-                  branch: "t3code/bootstrap-branch",
+                  branch: "t3code/bootstrap-refName",
                 },
                 runSetupScript: true,
               },
@@ -2995,8 +3945,8 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         );
         assert.deepEqual(createWorktree.mock.calls[0]?.[0], {
           cwd: "/tmp/project",
-          branch: "main",
-          newBranch: "t3code/bootstrap-branch",
+          refName: "main",
+          newRefName: "t3code/bootstrap-refName",
           path: null,
         });
         assert.deepEqual(runForThread.mock.calls[0]?.[0], {
@@ -3005,6 +3955,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
           projectCwd: "/tmp/project",
           worktreePath: "/tmp/bootstrap-worktree",
         });
+        assert.deepEqual(refreshStatus.mock.calls[0]?.[0], "/tmp/bootstrap-worktree");
 
         const setupActivities = dispatchedCommands.filter(
           (command): command is Extract<OrchestrationCommand, { type: "thread.activity.append" }> =>
@@ -3025,22 +3976,23 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
   it.effect("records setup-script failures without aborting bootstrap turn start", () =>
     Effect.gen(function* () {
       const dispatchedCommands: Array<OrchestrationCommand> = [];
-      const createWorktree = vi.fn((_: Parameters<GitCoreShape["createWorktree"]>[0]) =>
-        Effect.succeed({
-          worktree: {
-            branch: "t3code/bootstrap-branch",
-            path: "/tmp/bootstrap-worktree",
-          },
-        }),
+      const createWorktree = vi.fn(
+        (_: Parameters<GitVcsDriver.GitVcsDriverShape["createWorktree"]>[0]) =>
+          Effect.succeed({
+            worktree: {
+              refName: "t3code/bootstrap-refName",
+              path: "/tmp/bootstrap-worktree",
+            },
+          }),
       );
       const runForThread = vi.fn(
         (_: Parameters<ProjectSetupScriptRunnerShape["runForThread"]>[0]) =>
-          Effect.fail(new Error("pty unavailable")),
+          Effect.fail(new ProjectSetupScriptRunnerError({ message: "pty unavailable" })),
       );
 
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             createWorktree,
           },
           orchestrationEngine: {
@@ -3057,7 +4009,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         },
       });
 
-      const createdAt = new Date().toISOString();
+      const createdAt = "2026-01-01T00:00:00.000Z";
       const wsUrl = yield* getWsServerUrl("/ws");
       const response = yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
@@ -3088,7 +4040,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
               prepareWorktree: {
                 projectCwd: "/tmp/project",
                 baseBranch: "main",
-                branch: "t3code/bootstrap-branch",
+                branch: "t3code/bootstrap-refName",
               },
               runSetupScript: true,
             },
@@ -3118,13 +4070,14 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
   it.effect("does not misattribute setup activity dispatch failures as setup launch failures", () =>
     Effect.gen(function* () {
       const dispatchedCommands: Array<OrchestrationCommand> = [];
-      const createWorktree = vi.fn((_: Parameters<GitCoreShape["createWorktree"]>[0]) =>
-        Effect.succeed({
-          worktree: {
-            branch: "t3code/bootstrap-branch",
-            path: "/tmp/bootstrap-worktree",
-          },
-        }),
+      const createWorktree = vi.fn(
+        (_: Parameters<GitVcsDriver.GitVcsDriverShape["createWorktree"]>[0]) =>
+          Effect.succeed({
+            worktree: {
+              refName: "t3code/bootstrap-refName",
+              path: "/tmp/bootstrap-worktree",
+            },
+          }),
       );
       const runForThread = vi.fn(
         (_: Parameters<ProjectSetupScriptRunnerShape["runForThread"]>[0]) =>
@@ -3140,7 +4093,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             createWorktree,
           },
           orchestrationEngine: {
@@ -3173,7 +4126,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         },
       });
 
-      const createdAt = new Date().toISOString();
+      const createdAt = "2026-01-01T00:00:00.000Z";
       const wsUrl = yield* getWsServerUrl("/ws");
       const response = yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
@@ -3204,7 +4157,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
               prepareWorktree: {
                 projectCwd: "/tmp/project",
                 baseBranch: "main",
-                branch: "t3code/bootstrap-branch",
+                branch: "t3code/bootstrap-refName",
               },
               runSetupScript: true,
             },
@@ -3236,13 +4189,14 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
   it.effect("cleans up created bootstrap threads when worktree creation defects", () =>
     Effect.gen(function* () {
       const dispatchedCommands: Array<OrchestrationCommand> = [];
-      const createWorktree = vi.fn((_: Parameters<GitCoreShape["createWorktree"]>[0]) =>
-        Effect.die(new Error("worktree exploded")),
+      const createWorktree = vi.fn(
+        (_: Parameters<GitVcsDriver.GitVcsDriverShape["createWorktree"]>[0]) =>
+          Effect.die(new Error("worktree exploded")),
       );
 
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             createWorktree,
           },
           orchestrationEngine: {
@@ -3256,7 +4210,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         },
       });
 
-      const createdAt = new Date().toISOString();
+      const createdAt = "2026-01-01T00:00:00.000Z";
       const wsUrl = yield* getWsServerUrl("/ws");
       const result = yield* Effect.scoped(
         withWsRpcClient(wsUrl, (client) =>
@@ -3287,7 +4241,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
               prepareWorktree: {
                 projectCwd: "/tmp/project",
                 baseBranch: "main",
-                branch: "t3code/bootstrap-branch",
+                branch: "t3code/bootstrap-refName",
               },
               runSetupScript: false,
             },
@@ -3306,234 +4260,6 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
-  it.effect(
-    "routes websocket rpc subscribeOrchestrationDomainEvents with replay/live overlap resilience",
-    () =>
-      Effect.gen(function* () {
-        const now = new Date().toISOString();
-        const threadId = ThreadId.make("thread-1");
-        let replayCursor: number | null = null;
-        const makeEvent = (sequence: number): OrchestrationEvent =>
-          ({
-            sequence,
-            eventId: `event-${sequence}`,
-            aggregateKind: "thread",
-            aggregateId: threadId,
-            occurredAt: now,
-            commandId: null,
-            causationEventId: null,
-            correlationId: null,
-            metadata: {},
-            type: "thread.reverted",
-            payload: {
-              threadId,
-              turnCount: sequence,
-            },
-          }) as OrchestrationEvent;
-
-        yield* buildAppUnderTest({
-          layers: {
-            orchestrationEngine: {
-              getReadModel: () =>
-                Effect.succeed({
-                  ...makeDefaultOrchestrationReadModel(),
-                  snapshotSequence: 1,
-                }),
-              readEvents: (fromSequenceExclusive) => {
-                replayCursor = fromSequenceExclusive;
-                return Stream.make(makeEvent(2), makeEvent(3));
-              },
-              streamDomainEvents: Stream.make(makeEvent(3), makeEvent(4)),
-            },
-          },
-        });
-
-        const wsUrl = yield* getWsServerUrl("/ws");
-        const events = yield* Effect.scoped(
-          withWsRpcClient(wsUrl, (client) =>
-            client[WS_METHODS.subscribeOrchestrationDomainEvents]({}).pipe(
-              Stream.take(3),
-              Stream.runCollect,
-            ),
-          ),
-        );
-
-        assert.equal(replayCursor, 1);
-        assert.deepEqual(
-          Array.from(events).map((event) => event.sequence),
-          [2, 3, 4],
-        );
-      }).pipe(Effect.provide(NodeHttpServer.layerTest)),
-  );
-
-  it.effect("enriches replayed project events only once before streaming them to subscribers", () =>
-    Effect.gen(function* () {
-      let resolveCalls = 0;
-      const repositoryIdentity = {
-        canonicalKey: "github.com/t3tools/t3code",
-        locator: {
-          source: "git-remote" as const,
-          remoteName: "origin",
-          remoteUrl: "git@github.com:t3tools/t3code.git",
-        },
-        displayName: "t3tools/t3code",
-        provider: "github" as const,
-        owner: "t3tools",
-        name: "t3code",
-      };
-
-      yield* buildAppUnderTest({
-        layers: {
-          orchestrationEngine: {
-            getReadModel: () =>
-              Effect.succeed({
-                ...makeDefaultOrchestrationReadModel(),
-                snapshotSequence: 0,
-              }),
-            readEvents: () =>
-              Stream.make({
-                sequence: 1,
-                eventId: EventId.make("event-1"),
-                aggregateKind: "project",
-                aggregateId: defaultProjectId,
-                occurredAt: "2026-04-06T00:00:00.000Z",
-                commandId: null,
-                causationEventId: null,
-                correlationId: null,
-                metadata: {},
-                type: "project.meta-updated",
-                payload: {
-                  projectId: defaultProjectId,
-                  title: "Replayed Project",
-                  updatedAt: "2026-04-06T00:00:00.000Z",
-                },
-              } satisfies Extract<OrchestrationEvent, { type: "project.meta-updated" }>),
-            streamDomainEvents: Stream.empty,
-          },
-          repositoryIdentityResolver: {
-            resolve: () => {
-              resolveCalls += 1;
-              return Effect.succeed(repositoryIdentity);
-            },
-          },
-        },
-      });
-
-      const wsUrl = yield* getWsServerUrl("/ws");
-      const events = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.subscribeOrchestrationDomainEvents]({}).pipe(
-            Stream.take(1),
-            Stream.runCollect,
-          ),
-        ),
-      );
-
-      const event = Array.from(events)[0];
-      assert.equal(resolveCalls, 1);
-      assert.equal(event?.type, "project.meta-updated");
-      assert.deepEqual(
-        event && event.type === "project.meta-updated" ? event.payload.repositoryIdentity : null,
-        repositoryIdentity,
-      );
-    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
-  );
-
-  it.effect("enriches subscribed project meta updates with repository identity metadata", () =>
-    Effect.gen(function* () {
-      const repositoryIdentity = {
-        canonicalKey: "github.com/t3tools/t3code",
-        locator: {
-          source: "git-remote" as const,
-          remoteName: "upstream",
-          remoteUrl: "git@github.com:T3Tools/t3code.git",
-        },
-        displayName: "T3Tools/t3code",
-        provider: "github",
-        owner: "T3Tools",
-        name: "t3code",
-      };
-
-      yield* buildAppUnderTest({
-        layers: {
-          orchestrationEngine: {
-            getReadModel: () =>
-              Effect.succeed({
-                ...makeDefaultOrchestrationReadModel(),
-                snapshotSequence: 0,
-              }),
-            streamDomainEvents: Stream.make({
-              sequence: 1,
-              eventId: EventId.make("event-1"),
-              aggregateKind: "project",
-              aggregateId: defaultProjectId,
-              occurredAt: "2026-04-05T00:00:00.000Z",
-              commandId: null,
-              causationEventId: null,
-              correlationId: null,
-              metadata: {},
-              type: "project.meta-updated",
-              payload: {
-                projectId: defaultProjectId,
-                title: "Renamed Project",
-                updatedAt: "2026-04-05T00:00:00.000Z",
-              },
-            } satisfies Extract<OrchestrationEvent, { type: "project.meta-updated" }>),
-          },
-          repositoryIdentityResolver: {
-            resolve: () => Effect.succeed(repositoryIdentity),
-          },
-        },
-      });
-
-      const wsUrl = yield* getWsServerUrl("/ws");
-      const events = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) =>
-          client[WS_METHODS.subscribeOrchestrationDomainEvents]({}).pipe(
-            Stream.take(1),
-            Stream.runCollect,
-          ),
-        ),
-      );
-
-      const event = Array.from(events)[0];
-      assert.equal(event?.type, "project.meta-updated");
-      assert.deepEqual(
-        event && event.type === "project.meta-updated" ? event.payload.repositoryIdentity : null,
-        repositoryIdentity,
-      );
-    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
-  );
-
-  it.effect("routes websocket rpc orchestration.getSnapshot errors", () =>
-    Effect.gen(function* () {
-      yield* buildAppUnderTest({
-        layers: {
-          projectionSnapshotQuery: {
-            getSnapshot: () =>
-              Effect.fail(
-                new PersistenceSqlError({
-                  operation: "ProjectionSnapshotQuery.getSnapshot",
-                  detail: "projection unavailable",
-                }),
-              ),
-          },
-        },
-      });
-
-      const wsUrl = yield* getWsServerUrl("/ws");
-      const result = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) => client[ORCHESTRATION_WS_METHODS.getSnapshot]({})).pipe(
-          Effect.result,
-        ),
-      );
-
-      assertTrue(result._tag === "Failure");
-      assertTrue(result.failure._tag === "OrchestrationGetSnapshotError");
-      assertInclude(result.failure.message, "Failed to load orchestration snapshot");
-    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
-  );
-
   it.effect("routes websocket rpc terminal methods", () =>
     Effect.gen(function* () {
       const snapshot = {
@@ -3546,7 +4272,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         history: "",
         exitCode: null,
         exitSignal: null,
-        updatedAt: new Date().toISOString(),
+        updatedAt: "2026-01-01T00:00:00.000Z",
       };
 
       yield* buildAppUnderTest({
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 23c53ad07fd..c6780559204 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -1,7 +1,8 @@
-import { Effect, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import { FetchHttpClient, HttpRouter, HttpServer } from "effect/unstable/http";
 
-import { ServerConfig } from "./config";
+import { ServerConfig } from "./config.ts";
 import {
   attachmentsRouteLayer,
   otlpTracesProxyRouteLayer,
@@ -9,45 +10,57 @@ import {
   serverEnvironmentRouteLayer,
   staticAndDevRouteLayer,
   browserApiCorsLayer,
-} from "./http";
-import { fixPath } from "./os-jank";
-import { websocketRpcRouteLayer } from "./ws";
-import { OpenLive } from "./open";
-import { layerConfig as SqlitePersistenceLayerLive } from "./persistence/Layers/Sqlite";
-import { ServerLifecycleEventsLive } from "./serverLifecycleEvents";
-import { AnalyticsServiceLayerLive } from "./telemetry/Layers/AnalyticsService";
-import { makeEventNdjsonLogger } from "./provider/Layers/EventNdjsonLogger";
-import { ProviderSessionDirectoryLive } from "./provider/Layers/ProviderSessionDirectory";
-import { ProviderSessionRuntimeRepositoryLive } from "./persistence/Layers/ProviderSessionRuntime";
-import { makeCodexAdapterLive } from "./provider/Layers/CodexAdapter";
-import { makeClaudeAdapterLive } from "./provider/Layers/ClaudeAdapter";
-import { ProviderAdapterRegistryLive } from "./provider/Layers/ProviderAdapterRegistry";
-import { makeProviderServiceLive } from "./provider/Layers/ProviderService";
-import { CheckpointDiffQueryLive } from "./checkpointing/Layers/CheckpointDiffQuery";
-import { CheckpointStoreLive } from "./checkpointing/Layers/CheckpointStore";
-import { GitCoreLive } from "./git/Layers/GitCore";
-import { GitHubCliLive } from "./git/Layers/GitHubCli";
-import { GitStatusBroadcasterLive } from "./git/Layers/GitStatusBroadcaster";
-import { RoutingTextGenerationLive } from "./git/Layers/RoutingTextGeneration";
-import { TerminalManagerLive } from "./terminal/Layers/Manager";
-import { GitManagerLive } from "./git/Layers/GitManager";
-import { KeybindingsLive } from "./keybindings";
-import { ServerRuntimeStartup, ServerRuntimeStartupLive } from "./serverRuntimeStartup";
-import { OrchestrationReactorLive } from "./orchestration/Layers/OrchestrationReactor";
-import { RuntimeReceiptBusLive } from "./orchestration/Layers/RuntimeReceiptBus";
-import { ProviderRuntimeIngestionLive } from "./orchestration/Layers/ProviderRuntimeIngestion";
-import { ProviderCommandReactorLive } from "./orchestration/Layers/ProviderCommandReactor";
-import { CheckpointReactorLive } from "./orchestration/Layers/CheckpointReactor";
-import { ProviderRegistryLive } from "./provider/Layers/ProviderRegistry";
-import { ServerSettingsLive } from "./serverSettings";
-import { ProjectFaviconResolverLive } from "./project/Layers/ProjectFaviconResolver";
-import { RepositoryIdentityResolverLive } from "./project/Layers/RepositoryIdentityResolver";
-import { WorkspaceEntriesLive } from "./workspace/Layers/WorkspaceEntries";
-import { WorkspaceFileSystemLive } from "./workspace/Layers/WorkspaceFileSystem";
-import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths";
-import { ProjectSetupScriptRunnerLive } from "./project/Layers/ProjectSetupScriptRunner";
-import { ObservabilityLive } from "./observability/Layers/Observability";
-import { ServerEnvironmentLive } from "./environment/Layers/ServerEnvironment";
+} from "./http.ts";
+import { fixPath } from "./os-jank.ts";
+import { websocketRpcRouteLayer } from "./ws.ts";
+import * as ExternalLauncher from "./process/externalLauncher.ts";
+import { layerConfig as SqlitePersistenceLayerLive } from "./persistence/Layers/Sqlite.ts";
+import { ServerLifecycleEventsLive } from "./serverLifecycleEvents.ts";
+import { AnalyticsServiceLayerLive } from "./telemetry/Layers/AnalyticsService.ts";
+import { ProviderSessionDirectoryLive } from "./provider/Layers/ProviderSessionDirectory.ts";
+import { ProviderSessionRuntimeRepositoryLive } from "./persistence/Layers/ProviderSessionRuntime.ts";
+import { ProviderAdapterRegistryLive } from "./provider/Layers/ProviderAdapterRegistry.ts";
+import { ProviderEventLoggersLive } from "./provider/Layers/ProviderEventLoggers.ts";
+import { ProviderServiceLive } from "./provider/Layers/ProviderService.ts";
+import { ProviderSessionReaperLive } from "./provider/Layers/ProviderSessionReaper.ts";
+import { OpenCodeRuntimeLive } from "./provider/opencodeRuntime.ts";
+import { CheckpointDiffQueryLive } from "./checkpointing/Layers/CheckpointDiffQuery.ts";
+import { CheckpointStoreLive } from "./checkpointing/Layers/CheckpointStore.ts";
+import * as AzureDevOpsCli from "./sourceControl/AzureDevOpsCli.ts";
+import * as BitbucketApi from "./sourceControl/BitbucketApi.ts";
+import * as GitHubCli from "./sourceControl/GitHubCli.ts";
+import * as GitLabCli from "./sourceControl/GitLabCli.ts";
+import * as TextGeneration from "./textGeneration/TextGeneration.ts";
+import { ProviderInstanceRegistryHydrationLive } from "./provider/Layers/ProviderInstanceRegistryHydration.ts";
+import { TerminalManagerLive } from "./terminal/Layers/Manager.ts";
+import * as GitManager from "./git/GitManager.ts";
+import { KeybindingsLive } from "./keybindings.ts";
+import { ServerRuntimeStartup, ServerRuntimeStartupLive } from "./serverRuntimeStartup.ts";
+import { OrchestrationReactorLive } from "./orchestration/Layers/OrchestrationReactor.ts";
+import { RuntimeReceiptBusLive } from "./orchestration/Layers/RuntimeReceiptBus.ts";
+import { ProviderRuntimeIngestionLive } from "./orchestration/Layers/ProviderRuntimeIngestion.ts";
+import { ProviderCommandReactorLive } from "./orchestration/Layers/ProviderCommandReactor.ts";
+import { CheckpointReactorLive } from "./orchestration/Layers/CheckpointReactor.ts";
+import { ThreadDeletionReactorLive } from "./orchestration/Layers/ThreadDeletionReactor.ts";
+import { ProviderRegistryLive } from "./provider/Layers/ProviderRegistry.ts";
+import { ServerSettingsLive } from "./serverSettings.ts";
+import { ProjectFaviconResolverLive } from "./project/Layers/ProjectFaviconResolver.ts";
+import { RepositoryIdentityResolverLive } from "./project/Layers/RepositoryIdentityResolver.ts";
+import { WorkspaceEntriesLive } from "./workspace/Layers/WorkspaceEntries.ts";
+import { WorkspaceFileSystemLive } from "./workspace/Layers/WorkspaceFileSystem.ts";
+import { WorkspacePathsLive } from "./workspace/Layers/WorkspacePaths.ts";
+import * as GitVcsDriver from "./vcs/GitVcsDriver.ts";
+import * as VcsDriverRegistry from "./vcs/VcsDriverRegistry.ts";
+import * as VcsProjectConfig from "./vcs/VcsProjectConfig.ts";
+import * as VcsProcess from "./vcs/VcsProcess.ts";
+import * as VcsProvisioningService from "./vcs/VcsProvisioningService.ts";
+import * as VcsStatusBroadcaster from "./vcs/VcsStatusBroadcaster.ts";
+import * as GitWorkflowService from "./git/GitWorkflowService.ts";
+import * as SourceControlProviderRegistry from "./sourceControl/SourceControlProviderRegistry.ts";
+import * as SourceControlRepositoryService from "./sourceControl/SourceControlRepositoryService.ts";
+import { ProjectSetupScriptRunnerLive } from "./project/Layers/ProjectSetupScriptRunner.ts";
+import { ObservabilityLive } from "./observability/Layers/Observability.ts";
+import { ServerEnvironmentLive } from "./environment/Layers/ServerEnvironment.ts";
 import {
   authBearerBootstrapRouteLayer,
   authBootstrapRouteLayer,
@@ -59,27 +72,32 @@ import {
   authPairingCredentialRouteLayer,
   authSessionRouteLayer,
   authWebSocketTokenRouteLayer,
-} from "./auth/http";
-import { ServerSecretStoreLive } from "./auth/Layers/ServerSecretStore";
-import { ServerAuthLive } from "./auth/Layers/ServerAuth";
-import { OrchestrationLayerLive } from "./orchestration/runtimeLayer";
+} from "./auth/http.ts";
+import { ServerSecretStoreLive } from "./auth/Layers/ServerSecretStore.ts";
+import { ServerAuthLive } from "./auth/Layers/ServerAuth.ts";
+import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
+import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
+import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
+import { OrchestrationLayerLive } from "./orchestration/runtimeLayer.ts";
 import {
   clearPersistedServerRuntimeState,
   makePersistedServerRuntimeState,
   persistServerRuntimeState,
-} from "./serverRuntimeState";
+} from "./serverRuntimeState.ts";
 import {
   orchestrationDispatchRouteLayer,
   orchestrationSnapshotRouteLayer,
-} from "./orchestration/http";
+} from "./orchestration/http.ts";
+import * as NetService from "@t3tools/shared/Net";
+import { disableTailscaleServe, ensureTailscaleServe } from "@t3tools/tailscale";
 
 const PtyAdapterLive = Layer.unwrap(
   Effect.gen(function* () {
     if (typeof Bun !== "undefined") {
-      const BunPTY = yield* Effect.promise(() => import("./terminal/Layers/BunPTY"));
+      const BunPTY = yield* Effect.promise(() => import("./terminal/Layers/BunPTY.ts"));
       return BunPTY.layer;
     } else {
-      const NodePTY = yield* Effect.promise(() => import("./terminal/Layers/NodePTY"));
+      const NodePTY = yield* Effect.promise(() => import("./terminal/Layers/NodePTY.ts"));
       return NodePTY.layer;
     }
   }),
@@ -126,67 +144,91 @@ const ReactorLayerLive = Layer.empty.pipe(
   Layer.provideMerge(ProviderRuntimeIngestionLive),
   Layer.provideMerge(ProviderCommandReactorLive),
   Layer.provideMerge(CheckpointReactorLive),
+  Layer.provideMerge(ThreadDeletionReactorLive),
   Layer.provideMerge(RuntimeReceiptBusLive),
 );
 
-const CheckpointingLayerLive = Layer.empty.pipe(
-  Layer.provideMerge(CheckpointDiffQueryLive),
-  Layer.provideMerge(CheckpointStoreLive),
+const ProviderSessionDirectoryLayerLive = ProviderSessionDirectoryLive.pipe(
+  Layer.provide(ProviderSessionRuntimeRepositoryLive),
 );
 
-const ProviderLayerLive = Layer.unwrap(
-  Effect.gen(function* () {
-    const { providerEventLogPath } = yield* ServerConfig;
-    const nativeEventLogger = yield* makeEventNdjsonLogger(providerEventLogPath, {
-      stream: "native",
-    });
-    const canonicalEventLogger = yield* makeEventNdjsonLogger(providerEventLogPath, {
-      stream: "canonical",
-    });
-    const providerSessionDirectoryLayer = ProviderSessionDirectoryLive.pipe(
-      Layer.provide(ProviderSessionRuntimeRepositoryLive),
-    );
-    const codexAdapterLayer = makeCodexAdapterLive(
-      nativeEventLogger ? { nativeEventLogger } : undefined,
-    );
-    const claudeAdapterLayer = makeClaudeAdapterLive(
-      nativeEventLogger ? { nativeEventLogger } : undefined,
-    );
-    const adapterRegistryLayer = ProviderAdapterRegistryLive.pipe(
-      Layer.provide(codexAdapterLayer),
-      Layer.provide(claudeAdapterLayer),
-      Layer.provideMerge(providerSessionDirectoryLayer),
-    );
-    return makeProviderServiceLive(
-      canonicalEventLogger ? { canonicalEventLogger } : undefined,
-    ).pipe(Layer.provide(adapterRegistryLayer), Layer.provide(providerSessionDirectoryLayer));
-  }),
+// `ProviderAdapterRegistryLive` is now a facade that resolves kind → adapter
+// by looking up the default `ProviderInstance` per driver in the instance
+// registry. Adapter construction itself moved inside each driver's
+// `create()`; `ProviderEventLoggersLive` owns the shared native/canonical
+// NDJSON writers and is provided at the outer runtime layer so both
+// `ProviderService` and the per-instance drivers read the same logger pair.
+const ProviderLayerLive = ProviderServiceLive.pipe(
+  Layer.provide(ProviderAdapterRegistryLive),
+  Layer.provideMerge(ProviderSessionDirectoryLayerLive),
 );
 
 const PersistenceLayerLive = Layer.empty.pipe(Layer.provideMerge(SqlitePersistenceLayerLive));
 
-const GitManagerLayerLive = GitManagerLive.pipe(
+const VcsDriverRegistryLayerLive = VcsDriverRegistry.layer.pipe(
+  Layer.provide(VcsProjectConfig.layer),
+);
+
+const SourceControlProviderRegistryLayerLive = SourceControlProviderRegistry.layer.pipe(
+  Layer.provide(
+    Layer.mergeAll(AzureDevOpsCli.layer, BitbucketApi.layer, GitHubCli.layer, GitLabCli.layer),
+  ),
+  Layer.provideMerge(GitVcsDriver.layer),
+  Layer.provideMerge(VcsDriverRegistryLayerLive),
+);
+
+const GitManagerLayerLive = GitManager.layer.pipe(
   Layer.provideMerge(ProjectSetupScriptRunnerLive),
-  Layer.provideMerge(GitCoreLive),
-  Layer.provideMerge(GitHubCliLive),
-  Layer.provideMerge(RoutingTextGenerationLive),
+  Layer.provideMerge(GitVcsDriver.layer),
+  Layer.provideMerge(SourceControlProviderRegistryLayerLive),
+  Layer.provideMerge(TextGeneration.layer),
 );
 
 const GitLayerLive = Layer.empty.pipe(
   Layer.provideMerge(GitManagerLayerLive),
-  Layer.provideMerge(GitStatusBroadcasterLive.pipe(Layer.provide(GitManagerLayerLive))),
-  Layer.provideMerge(GitCoreLive),
+  Layer.provideMerge(GitVcsDriver.layer),
+);
+
+const GitWorkflowLayerLive = GitWorkflowService.layer.pipe(
+  Layer.provideMerge(VcsDriverRegistryLayerLive),
+  Layer.provideMerge(GitLayerLive),
+);
+
+const SourceControlRepositoryServiceLayerLive = SourceControlRepositoryService.layer.pipe(
+  Layer.provideMerge(GitVcsDriver.layer),
+  Layer.provideMerge(SourceControlProviderRegistryLayerLive),
+);
+
+const VcsLayerLive = Layer.empty.pipe(
+  Layer.provideMerge(VcsProjectConfig.layer),
+  Layer.provideMerge(VcsDriverRegistryLayerLive),
+  Layer.provideMerge(VcsProvisioningService.layer.pipe(Layer.provide(VcsDriverRegistryLayerLive))),
+  Layer.provideMerge(GitWorkflowLayerLive),
+  Layer.provideMerge(SourceControlRepositoryServiceLayerLive),
+  Layer.provideMerge(VcsStatusBroadcaster.layer.pipe(Layer.provide(GitWorkflowLayerLive))),
+);
+
+const CheckpointingLayerLive = Layer.empty.pipe(
+  Layer.provideMerge(CheckpointDiffQueryLive),
+  Layer.provideMerge(CheckpointStoreLive.pipe(Layer.provide(VcsDriverRegistryLayerLive))),
 );
 
 const TerminalLayerLive = TerminalManagerLive.pipe(Layer.provide(PtyAdapterLive));
 
+const WorkspaceEntriesLayerLive = WorkspaceEntriesLive.pipe(
+  Layer.provide(WorkspacePathsLive),
+  Layer.provideMerge(VcsDriverRegistryLayerLive),
+);
+
+const WorkspaceFileSystemLayerLive = WorkspaceFileSystemLive.pipe(
+  Layer.provide(WorkspacePathsLive),
+  Layer.provide(WorkspaceEntriesLayerLive),
+);
+
 const WorkspaceLayerLive = Layer.mergeAll(
   WorkspacePathsLive,
-  WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive)),
-  WorkspaceFileSystemLive.pipe(
-    Layer.provide(WorkspacePathsLive),
-    Layer.provide(WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive))),
-  ),
+  WorkspaceEntriesLayerLive,
+  WorkspaceFileSystemLayerLive,
 );
 
 const AuthLayerLive = ServerAuthLive.pipe(
@@ -194,27 +236,57 @@ const AuthLayerLive = ServerAuthLive.pipe(
   Layer.provide(ServerSecretStoreLive),
 );
 
-const RuntimeDependenciesLive = ReactorLayerLive.pipe(
+const ProviderRuntimeLayerLive = ProviderSessionReaperLive.pipe(
+  Layer.provideMerge(ProviderLayerLive),
+  Layer.provideMerge(OrchestrationLayerLive),
+);
+
+const RuntimeCoreDependenciesLive = ReactorLayerLive.pipe(
   // Core Services
   Layer.provideMerge(CheckpointingLayerLive),
+  Layer.provideMerge(SourceControlProviderRegistryLayerLive),
   Layer.provideMerge(GitLayerLive),
-  Layer.provideMerge(OrchestrationLayerLive),
-  Layer.provideMerge(ProviderLayerLive),
+  Layer.provideMerge(VcsLayerLive),
+  Layer.provideMerge(ProviderRuntimeLayerLive),
   Layer.provideMerge(TerminalLayerLive),
   Layer.provideMerge(PersistenceLayerLive),
   Layer.provideMerge(KeybindingsLive),
   Layer.provideMerge(ProviderRegistryLive),
+  // The instance registry is the new routing keystone — text generation,
+  // adapter lookup, and runtime ingestion all resolve `ProviderInstanceId`
+  // through this layer. Built-in drivers come from `BUILT_IN_DRIVERS`;
+  // `providerInstances` hydration merges `settings.providers.<kind>`
+  // with explicit `providerInstances` entries on boot.
+  Layer.provideMerge(ProviderInstanceRegistryHydrationLive),
+  // Shared native/canonical NDJSON writers used by both the per-instance
+  // drivers (native stream, written from inside each `<X>Adapter`) and
+  // `ProviderService` (canonical stream, written after event normalization).
+  // Provided once at the runtime level so every consumer sees the same
+  // logger instances.
+  Layer.provideMerge(ProviderEventLoggersLive),
+  // `OpenCodeDriver.create()` yields `OpenCodeRuntime`; previously the old
+  // `ProviderRegistryLive` pulled `OpenCodeRuntimeLive` in for itself, but
+  // the rewritten registry reads snapshots off the instance registry and
+  // no longer transitively provides it. Exposing it at the runtime level
+  // keeps a single Live for all opencode consumers.
+  Layer.provideMerge(OpenCodeRuntimeLive),
   Layer.provideMerge(ServerSettingsLive),
   Layer.provideMerge(WorkspaceLayerLive),
   Layer.provideMerge(ProjectFaviconResolverLive),
   Layer.provideMerge(RepositoryIdentityResolverLive),
   Layer.provideMerge(ServerEnvironmentLive),
   Layer.provideMerge(AuthLayerLive),
+);
 
+const RuntimeDependenciesLive = RuntimeCoreDependenciesLive.pipe(
   // Misc.
+  Layer.provideMerge(ProcessDiagnostics.layer),
+  Layer.provideMerge(ProcessResourceMonitor.layer),
+  Layer.provideMerge(TraceDiagnostics.layer),
   Layer.provideMerge(AnalyticsServiceLayerLive),
-  Layer.provideMerge(OpenLive),
+  Layer.provideMerge(ExternalLauncher.layer),
   Layer.provideMerge(ServerLifecycleEventsLive),
+  Layer.provide(NetService.layer),
 );
 
 const RuntimeServicesLive = ServerRuntimeStartupLive.pipe(
@@ -264,7 +336,7 @@ export const makeServerLayer = Layer.unwrap(
             return;
           }
 
-          const state = makePersistedServerRuntimeState({
+          const state = yield* makePersistedServerRuntimeState({
             config,
             port: address.port,
           });
@@ -276,6 +348,57 @@ export const makeServerLayer = Layer.unwrap(
         () => clearPersistedServerRuntimeState(config.serverRuntimeStatePath),
       ),
     );
+    const tailscaleServeLayer = config.tailscaleServeEnabled
+      ? Layer.effectDiscard(
+          Effect.acquireRelease(
+            Effect.gen(function* () {
+              const server = yield* HttpServer.HttpServer;
+              const address = server.address;
+              if (typeof address === "string" || !("port" in address)) {
+                return null;
+              }
+
+              const localPort = address.port;
+              return yield* ensureTailscaleServe({
+                localPort,
+                servePort: config.tailscaleServePort,
+                localHost: "127.0.0.1",
+              }).pipe(
+                Effect.as({ localPort, servePort: config.tailscaleServePort }),
+                Effect.tap(() =>
+                  Effect.logInfo("Tailscale Serve configured", {
+                    localPort,
+                    servePort: config.tailscaleServePort,
+                  }),
+                ),
+                Effect.catch((cause) =>
+                  Effect.logWarning("Failed to configure Tailscale Serve", {
+                    cause,
+                    localPort,
+                    servePort: config.tailscaleServePort,
+                  }).pipe(Effect.as(null)),
+                ),
+              );
+            }),
+            (configured) =>
+              configured
+                ? disableTailscaleServe({ servePort: configured.servePort }).pipe(
+                    Effect.tap(() =>
+                      Effect.logInfo("Tailscale Serve disabled", {
+                        servePort: configured.servePort,
+                      }),
+                    ),
+                    Effect.catch((cause) =>
+                      Effect.logWarning("Failed to disable Tailscale Serve", {
+                        cause,
+                        servePort: configured.servePort,
+                      }),
+                    ),
+                  )
+                : Effect.void,
+          ),
+        )
+      : Layer.empty;
 
     const serverApplicationLayer = Layer.mergeAll(
       HttpRouter.serve(makeRoutesLayer, {
@@ -283,6 +406,7 @@ export const makeServerLayer = Layer.unwrap(
       }),
       httpListeningLayer,
       runtimeStateLayer,
+      tailscaleServeLayer,
     );
 
     return serverApplicationLayer.pipe(
@@ -290,14 +414,11 @@ export const makeServerLayer = Layer.unwrap(
       Layer.provideMerge(HttpServerLive),
       Layer.provide(ObservabilityLive),
       Layer.provideMerge(FetchHttpClient.layer),
+      Layer.provideMerge(VcsProcess.layer),
       Layer.provideMerge(PlatformServicesLive),
     );
   }),
 );
 
 // Important: Only `ServerConfig` should be provided by the CLI layer!!! Don't let other requirements leak into the launch layer.
-export const runServer = Layer.launch(makeServerLayer) satisfies Effect.Effect<
-  never,
-  any,
-  ServerConfig
->;
+export const runServer = Layer.launch(makeServerLayer);
diff --git a/apps/server/src/serverLifecycleEvents.test.ts b/apps/server/src/serverLifecycleEvents.test.ts
index 47e24c1b87c..14fbba9e238 100644
--- a/apps/server/src/serverLifecycleEvents.test.ts
+++ b/apps/server/src/serverLifecycleEvents.test.ts
@@ -1,7 +1,8 @@
 import { EnvironmentId } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
 import { assertTrue } from "@effect/vitest/utils";
-import { Effect, Option } from "effect";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 
 import { ServerLifecycleEvents, ServerLifecycleEventsLive } from "./serverLifecycleEvents.ts";
 
@@ -37,7 +38,7 @@ it.effect(
           version: 1,
           type: "ready",
           payload: {
-            at: new Date().toISOString(),
+            at: "2026-01-01T00:00:00.000Z",
             environment,
           },
         })
diff --git a/apps/server/src/serverLifecycleEvents.ts b/apps/server/src/serverLifecycleEvents.ts
index 145d1cbaa4e..88661b1593a 100644
--- a/apps/server/src/serverLifecycleEvents.ts
+++ b/apps/server/src/serverLifecycleEvents.ts
@@ -1,5 +1,10 @@
 import type { ServerLifecycleStreamEvent } from "@t3tools/contracts";
-import { Effect, Layer, PubSub, Ref, Context, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Context from "effect/Context";
+import * as Stream from "effect/Stream";
 
 type LifecycleEventInput =
   | Omit<Extract<ServerLifecycleStreamEvent, { type: "welcome" }>, "sequence">
diff --git a/apps/server/src/serverLogger.ts b/apps/server/src/serverLogger.ts
index ea098dcbbea..a7cb1d6a26e 100644
--- a/apps/server/src/serverLogger.ts
+++ b/apps/server/src/serverLogger.ts
@@ -1,6 +1,9 @@
-import { Effect, Logger, References, Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Logger from "effect/Logger";
+import * as References from "effect/References";
+import * as Layer from "effect/Layer";
 
-import { ServerConfig } from "./config";
+import { ServerConfig } from "./config.ts";
 
 export const ServerLoggerLive = Effect.gen(function* () {
   const config = yield* ServerConfig;
diff --git a/apps/server/src/serverRuntimeStartup.test.ts b/apps/server/src/serverRuntimeStartup.test.ts
index c3159cc9d8c..33b9abcb98a 100644
--- a/apps/server/src/serverRuntimeStartup.test.ts
+++ b/apps/server/src/serverRuntimeStartup.test.ts
@@ -1,20 +1,33 @@
-import { DEFAULT_MODEL_BY_PROVIDER } from "@t3tools/contracts";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { DEFAULT_MODEL, ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
-import { Deferred, Effect, Fiber, Option, Ref } from "effect";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
 
-import { AnalyticsService } from "./telemetry/Services/AnalyticsService.ts";
+import { ServerConfig } from "./config.ts";
+import {
+  OrchestrationEngineService,
+  type OrchestrationEngineShape,
+} from "./orchestration/Services/OrchestrationEngine.ts";
 import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
+import { AnalyticsService } from "./telemetry/Services/AnalyticsService.ts";
 import {
   getAutoBootstrapDefaultModelSelection,
   launchStartupHeartbeat,
   makeCommandGate,
+  resolveAutoBootstrapWelcomeTargets,
+  resolveWelcomeBase,
   ServerRuntimeStartupError,
 } from "./serverRuntimeStartup.ts";
 
 it("uses the canonical Codex default for auto-bootstrapped model selection", () => {
   assert.deepStrictEqual(getAutoBootstrapDefaultModelSelection(), {
-    provider: "codex",
-    model: DEFAULT_MODEL_BY_PROVIDER.codex,
+    instanceId: ProviderInstanceId.make("codex"),
+    model: DEFAULT_MODEL,
   });
 });
 
@@ -69,7 +82,11 @@ it.effect("launchStartupHeartbeat does not block the caller while counts are loa
 
       yield* launchStartupHeartbeat.pipe(
         Effect.provideService(ProjectionSnapshotQuery, {
+          getCommandReadModel: () => Effect.die("unused"),
           getSnapshot: () => Effect.die("unused"),
+          getShellSnapshot: () => Effect.die("unused"),
+          getArchivedShellSnapshot: () => Effect.die("unused"),
+          getSnapshotSequence: () => Effect.die("unused"),
           getCounts: () =>
             Deferred.await(releaseCounts).pipe(
               Effect.as({
@@ -78,8 +95,12 @@ it.effect("launchStartupHeartbeat does not block the caller while counts are loa
               }),
             ),
           getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.succeed(Option.none()),
           getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
           getThreadCheckpointContext: () => Effect.succeed(Option.none()),
+          getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+          getThreadShellById: () => Effect.succeed(Option.none()),
+          getThreadDetailById: () => Effect.succeed(Option.none()),
         }),
         Effect.provideService(AnalyticsService, {
           record: () => Effect.void,
@@ -89,3 +110,115 @@ it.effect("launchStartupHeartbeat does not block the caller while counts are loa
     }),
   ),
 );
+
+it.effect("resolveWelcomeBase derives cwd and project name from server config", () =>
+  Effect.gen(function* () {
+    const welcome = yield* resolveWelcomeBase.pipe(
+      Effect.provideService(ServerConfig, {
+        cwd: "/tmp/startup-project",
+      } as never),
+    );
+
+    assert.deepStrictEqual(welcome, {
+      cwd: "/tmp/startup-project",
+      projectName: "startup-project",
+    });
+  }),
+);
+
+it.effect("resolveAutoBootstrapWelcomeTargets returns existing project and thread ids", () => {
+  const bootstrapProjectId = ProjectId.make("project-startup-bootstrap");
+  const bootstrapThreadId = ThreadId.make("thread-startup-bootstrap");
+
+  return Effect.gen(function* () {
+    const dispatchCalls = yield* Ref.make<ReadonlyArray<string>>([]);
+    const targets = yield* resolveAutoBootstrapWelcomeTargets.pipe(
+      Effect.provideService(ServerConfig, {
+        cwd: "/tmp/startup-project",
+        autoBootstrapProjectFromCwd: true,
+      } as never),
+      Effect.provideService(ProjectionSnapshotQuery, {
+        getCommandReadModel: () => Effect.die("unused"),
+        getSnapshot: () => Effect.die("unused"),
+        getShellSnapshot: () => Effect.die("unused"),
+        getArchivedShellSnapshot: () => Effect.die("unused"),
+        getSnapshotSequence: () => Effect.die("unused"),
+        getCounts: () => Effect.die("unused"),
+        getActiveProjectByWorkspaceRoot: () =>
+          Effect.succeed(
+            Option.some({
+              id: bootstrapProjectId,
+              title: "Startup Project",
+              workspaceRoot: "/tmp/startup-project",
+              defaultModelSelection: getAutoBootstrapDefaultModelSelection(),
+              scripts: [],
+              createdAt: "2026-01-01T00:00:00.000Z",
+              updatedAt: "2026-01-01T00:00:00.000Z",
+              deletedAt: null,
+            }),
+          ),
+        getProjectShellById: () => Effect.die("unused"),
+        getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.some(bootstrapThreadId)),
+        getThreadCheckpointContext: () => Effect.succeed(Option.none()),
+        getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+        getThreadShellById: () => Effect.die("unused"),
+        getThreadDetailById: () => Effect.die("unused"),
+      }),
+      Effect.provideService(OrchestrationEngineService, {
+        readEvents: () => Stream.empty,
+        dispatch: (command) =>
+          Ref.update(dispatchCalls, (calls) => [...calls, command.type]).pipe(
+            Effect.as({ sequence: 1 }),
+          ),
+        streamDomainEvents: Stream.empty,
+      } satisfies OrchestrationEngineShape),
+      Effect.provide(NodeServices.layer),
+    );
+
+    assert.deepStrictEqual(targets, {
+      bootstrapProjectId,
+      bootstrapThreadId,
+    });
+    assert.deepStrictEqual(yield* Ref.get(dispatchCalls), []);
+  });
+});
+
+it.effect("resolveAutoBootstrapWelcomeTargets creates a project and thread when missing", () =>
+  Effect.gen(function* () {
+    const dispatchCalls = yield* Ref.make<ReadonlyArray<string>>([]);
+    const targets = yield* resolveAutoBootstrapWelcomeTargets.pipe(
+      Effect.provideService(ServerConfig, {
+        cwd: "/tmp/startup-project",
+        autoBootstrapProjectFromCwd: true,
+      } as never),
+      Effect.provideService(ProjectionSnapshotQuery, {
+        getCommandReadModel: () => Effect.die("unused"),
+        getSnapshot: () => Effect.die("unused"),
+        getShellSnapshot: () => Effect.die("unused"),
+        getArchivedShellSnapshot: () => Effect.die("unused"),
+        getSnapshotSequence: () => Effect.die("unused"),
+        getCounts: () => Effect.die("unused"),
+        getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+        getProjectShellById: () => Effect.die("unused"),
+        getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+        getThreadCheckpointContext: () => Effect.succeed(Option.none()),
+        getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+        getThreadShellById: () => Effect.die("unused"),
+        getThreadDetailById: () => Effect.die("unused"),
+      }),
+      Effect.provideService(OrchestrationEngineService, {
+        readEvents: () => Stream.empty,
+        dispatch: (command) =>
+          Ref.update(dispatchCalls, (calls) => [...calls, command.type]).pipe(
+            Effect.as({ sequence: 1 }),
+          ),
+        streamDomainEvents: Stream.empty,
+      } satisfies OrchestrationEngineShape),
+      Effect.provide(NodeServices.layer),
+    );
+
+    assert.equal(typeof targets.bootstrapProjectId, "string");
+    assert.equal(typeof targets.bootstrapThreadId, "string");
+    assert.deepStrictEqual(yield* Ref.get(dispatchCalls), ["project.create", "thread.create"]);
+  }),
+);
diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
index 441df3395d9..9ec536105c8 100644
--- a/apps/server/src/serverRuntimeStartup.ts
+++ b/apps/server/src/serverRuntimeStartup.ts
@@ -1,43 +1,44 @@
 import {
   CommandId,
-  DEFAULT_MODEL_BY_PROVIDER,
+  DEFAULT_MODEL,
   DEFAULT_PROVIDER_INTERACTION_MODE,
   type ModelSelection,
   ProjectId,
+  ProviderInstanceId,
   ThreadId,
 } from "@t3tools/contracts";
-import {
-  Data,
-  Deferred,
-  Effect,
-  Exit,
-  Layer,
-  Option,
-  Path,
-  Queue,
-  Ref,
-  Scope,
-  Context,
-  Console,
-} from "effect";
-
-import { ServerConfig } from "./config";
-import { Keybindings } from "./keybindings";
-import { Open } from "./open";
-import { OrchestrationEngineService } from "./orchestration/Services/OrchestrationEngine";
-import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery";
-import { OrchestrationReactor } from "./orchestration/Services/OrchestrationReactor";
-import { ServerLifecycleEvents } from "./serverLifecycleEvents";
-import { ServerSettingsService } from "./serverSettings";
-import { ServerEnvironment } from "./environment/Services/ServerEnvironment";
-import { AnalyticsService } from "./telemetry/Services/AnalyticsService";
-import { ServerAuth } from "./auth/Services/ServerAuth";
+import * as Data from "effect/Data";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Context from "effect/Context";
+import * as Console from "effect/Console";
+import * as DateTime from "effect/DateTime";
+
+import { ServerConfig } from "./config.ts";
+import { Keybindings } from "./keybindings.ts";
+import * as ExternalLauncher from "./process/externalLauncher.ts";
+import { OrchestrationEngineService } from "./orchestration/Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
+import { OrchestrationReactor } from "./orchestration/Services/OrchestrationReactor.ts";
+import { ServerLifecycleEvents } from "./serverLifecycleEvents.ts";
+import { ServerSettingsService } from "./serverSettings.ts";
+import { ServerEnvironment } from "./environment/Services/ServerEnvironment.ts";
+import { AnalyticsService } from "./telemetry/Services/AnalyticsService.ts";
+import { ServerAuth } from "./auth/Services/ServerAuth.ts";
+import { ProviderSessionReaper } from "./provider/Services/ProviderSessionReaper.ts";
 import {
   formatHeadlessServeOutput,
   formatHostForUrl,
   isWildcardHost,
   issueHeadlessServeAccessInfo,
-} from "./startupAccess";
+} from "./startupAccess.ts";
 
 export class ServerRuntimeStartupError extends Data.TaggedError("ServerRuntimeStartupError")<{
   readonly message: string;
@@ -153,11 +154,22 @@ export const launchStartupHeartbeat = recordStartupHeartbeat.pipe(
 );
 
 export const getAutoBootstrapDefaultModelSelection = (): ModelSelection => ({
-  provider: "codex",
-  model: DEFAULT_MODEL_BY_PROVIDER.codex,
+  instanceId: ProviderInstanceId.make("codex"),
+  model: DEFAULT_MODEL,
 });
 
-const autoBootstrapWelcome = Effect.gen(function* () {
+export const resolveWelcomeBase = Effect.gen(function* () {
+  const serverConfig = yield* ServerConfig;
+  const segments = serverConfig.cwd.split(/[/\\]/).filter(Boolean);
+  const projectName = segments[segments.length - 1] ?? "project";
+
+  return {
+    cwd: serverConfig.cwd,
+    projectName,
+  } as const;
+});
+
+export const resolveAutoBootstrapWelcomeTargets = Effect.gen(function* () {
   const serverConfig = yield* ServerConfig;
   const projectionReadModelQuery = yield* ProjectionSnapshotQuery;
   const orchestrationEngine = yield* OrchestrationEngineService;
@@ -175,7 +187,7 @@ const autoBootstrapWelcome = Effect.gen(function* () {
       let nextProjectDefaultModelSelection: ModelSelection;
 
       if (Option.isNone(existingProject)) {
-        const createdAt = new Date().toISOString();
+        const createdAt = DateTime.formatIso(yield* DateTime.now);
         nextProjectId = ProjectId.make(crypto.randomUUID());
         const bootstrapProjectTitle = path.basename(serverConfig.cwd) || "project";
         nextProjectDefaultModelSelection = getAutoBootstrapDefaultModelSelection();
@@ -197,7 +209,7 @@ const autoBootstrapWelcome = Effect.gen(function* () {
       const existingThreadId =
         yield* projectionReadModelQuery.getFirstActiveThreadIdByProjectId(nextProjectId);
       if (Option.isNone(existingThreadId)) {
-        const createdAt = new Date().toISOString();
+        const createdAt = DateTime.formatIso(yield* DateTime.now);
         const createdThreadId = ThreadId.make(crypto.randomUUID());
         yield* orchestrationEngine.dispatch({
           type: "thread.create",
@@ -221,12 +233,7 @@ const autoBootstrapWelcome = Effect.gen(function* () {
     });
   }
 
-  const segments = serverConfig.cwd.split(/[/\\]/).filter(Boolean);
-  const projectName = segments[segments.length - 1] ?? "project";
-
   return {
-    cwd: serverConfig.cwd,
-    projectName,
     ...(bootstrapProjectId ? { bootstrapProjectId } : {}),
     ...(bootstrapThreadId ? { bootstrapThreadId } : {}),
   } as const;
@@ -254,9 +261,9 @@ const maybeOpenBrowser = (target: string) =>
     if (serverConfig.noBrowser) {
       return;
     }
-    const { openBrowser } = yield* Open;
+    const externalLauncher = yield* ExternalLauncher.ExternalLauncher;
 
-    yield* openBrowser(target).pipe(
+    yield* externalLauncher.launchBrowser(target).pipe(
       Effect.catch(() =>
         Effect.logInfo("browser auto-open unavailable", {
           hint: `Open ${target} in your browser.`,
@@ -271,10 +278,11 @@ const runStartupPhase = <A, E, R>(phase: string, effect: Effect.Effect<A, E, R>)
     Effect.withSpan(`server.startup.${phase}`),
   );
 
-const makeServerRuntimeStartup = Effect.gen(function* () {
+export const makeServerRuntimeStartup = Effect.gen(function* () {
   const serverConfig = yield* ServerConfig;
   const keybindings = yield* Keybindings;
   const orchestrationReactor = yield* OrchestrationReactor;
+  const providerSessionReaper = yield* ProviderSessionReaper;
   const lifecycleEvents = yield* ServerLifecycleEvents;
   const serverSettings = yield* ServerSettingsService;
   const serverEnvironment = yield* ServerEnvironment;
@@ -319,18 +327,19 @@ const makeServerRuntimeStartup = Effect.gen(function* () {
     yield* Effect.logDebug("startup phase: starting orchestration reactors");
     yield* runStartupPhase(
       "reactors.start",
-      orchestrationReactor.start().pipe(Scope.provide(reactorScope)),
+      Effect.gen(function* () {
+        yield* orchestrationReactor.start().pipe(Scope.provide(reactorScope));
+        yield* providerSessionReaper.start().pipe(Scope.provide(reactorScope));
+      }),
     );
 
-    yield* Effect.logDebug("startup phase: preparing welcome payload");
-    const welcome = yield* runStartupPhase("welcome.prepare", autoBootstrapWelcome);
+    const welcomeBase = yield* resolveWelcomeBase;
     const environment = yield* serverEnvironment.getDescriptor;
+    yield* Effect.logDebug("startup phase: preparing welcome payload");
     yield* Effect.logDebug("startup phase: publishing welcome event", {
       environmentId: environment.environmentId,
-      cwd: welcome.cwd,
-      projectName: welcome.projectName,
-      bootstrapProjectId: welcome.bootstrapProjectId,
-      bootstrapThreadId: welcome.bootstrapThreadId,
+      cwd: welcomeBase.cwd,
+      projectName: welcomeBase.projectName,
     });
     yield* runStartupPhase(
       "welcome.publish",
@@ -339,10 +348,47 @@ const makeServerRuntimeStartup = Effect.gen(function* () {
         type: "welcome",
         payload: {
           environment,
-          ...welcome,
+          ...welcomeBase,
         },
       }),
     );
+
+    if (serverConfig.autoBootstrapProjectFromCwd) {
+      yield* Effect.forkScoped(
+        runStartupPhase(
+          "welcome.autobootstrap",
+          Effect.gen(function* () {
+            const bootstrapTargets = yield* resolveAutoBootstrapWelcomeTargets;
+            if (!bootstrapTargets.bootstrapProjectId && !bootstrapTargets.bootstrapThreadId) {
+              return;
+            }
+
+            yield* Effect.logDebug("startup phase: publishing bootstrapped welcome event", {
+              environmentId: environment.environmentId,
+              cwd: welcomeBase.cwd,
+              projectName: welcomeBase.projectName,
+              bootstrapProjectId: bootstrapTargets.bootstrapProjectId,
+              bootstrapThreadId: bootstrapTargets.bootstrapThreadId,
+            });
+            yield* lifecycleEvents.publish({
+              version: 1,
+              type: "welcome",
+              payload: {
+                environment,
+                ...welcomeBase,
+                ...bootstrapTargets,
+              },
+            });
+          }).pipe(
+            Effect.catch((cause) =>
+              Effect.logWarning("startup auto-bootstrap welcome failed", {
+                cause,
+              }),
+            ),
+          ),
+        ),
+      );
+    }
   }).pipe(
     Effect.annotateSpans({
       "server.mode": serverConfig.mode,
@@ -376,7 +422,7 @@ const makeServerRuntimeStartup = Effect.gen(function* () {
           version: 1,
           type: "ready",
           payload: {
-            at: new Date().toISOString(),
+            at: DateTime.formatIso(yield* DateTime.now),
             environment: yield* serverEnvironment.getDescriptor,
           },
         }),
diff --git a/apps/server/src/serverRuntimeState.ts b/apps/server/src/serverRuntimeState.ts
index 00c83844682..996f9a2bfc9 100644
--- a/apps/server/src/serverRuntimeState.ts
+++ b/apps/server/src/serverRuntimeState.ts
@@ -1,7 +1,12 @@
-import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 
-import { type ServerConfigShape } from "./config";
-import { formatHostForUrl, isWildcardHost } from "./startupAccess";
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { type ServerConfigShape } from "./config.ts";
+import { formatHostForUrl, isWildcardHost } from "./startupAccess.ts";
 
 export const PersistedServerRuntimeState = Schema.Struct({
   version: Schema.Literal(1),
@@ -29,28 +34,23 @@ const runtimeOriginForConfig = (
 export const makePersistedServerRuntimeState = (input: {
   readonly config: Pick<ServerConfigShape, "host">;
   readonly port: number;
-}): PersistedServerRuntimeState => ({
-  version: 1,
-  pid: process.pid,
-  ...(input.config.host ? { host: input.config.host } : {}),
-  port: input.port,
-  origin: runtimeOriginForConfig(input.config, input.port),
-  startedAt: new Date().toISOString(),
-});
+}): Effect.Effect<PersistedServerRuntimeState> =>
+  Effect.map(DateTime.now, (now) => ({
+    version: 1,
+    pid: process.pid,
+    ...(input.config.host ? { host: input.config.host } : {}),
+    port: input.port,
+    origin: runtimeOriginForConfig(input.config, input.port),
+    startedAt: DateTime.formatIso(now),
+  }));
 
 export const persistServerRuntimeState = (input: {
   readonly path: string;
   readonly state: PersistedServerRuntimeState;
 }) =>
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const pathService = yield* Path.Path;
-    const tempPath = `${input.path}.${process.pid}.${Date.now()}.tmp`;
-    return yield* fs.makeDirectory(pathService.dirname(input.path), { recursive: true }).pipe(
-      Effect.flatMap(() => fs.writeFileString(tempPath, `${JSON.stringify(input.state)}\n`)),
-      Effect.flatMap(() => fs.rename(tempPath, input.path)),
-      Effect.ensuring(fs.remove(tempPath, { force: true }).pipe(Effect.ignore({ log: true }))),
-    );
+  writeFileStringAtomically({
+    filePath: input.path,
+    contents: `${JSON.stringify(input.state)}\n`,
   });
 
 export const clearPersistedServerRuntimeState = (path: string) =>
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index 289bc689617..7af27f0b7cf 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -1,9 +1,20 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { DEFAULT_SERVER_SETTINGS, ServerSettingsPatch } from "@t3tools/contracts";
+import {
+  DEFAULT_SERVER_SETTINGS,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ServerSettings,
+  ServerSettingsPatch,
+} from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import { assert, it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Schema } from "effect";
-import { ServerConfig } from "./config";
-import { ServerSettingsLive, ServerSettingsService } from "./serverSettings";
+import * as Effect from "effect/Effect";
+import * as Duration from "effect/Duration";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { ServerConfig } from "./config.ts";
+import { ServerSettingsLive, ServerSettingsService } from "./serverSettings.ts";
 
 const makeServerSettingsLayer = () =>
   ServerSettingsLive.pipe(
@@ -28,22 +39,40 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       assert.deepEqual(
         decodePatch({
           textGenerationModelSelection: {
-            options: {
-              fastMode: false,
-            },
+            options: [{ id: "fastMode", value: false }],
           },
         }),
         {
           textGenerationModelSelection: {
-            options: {
-              fastMode: false,
-            },
+            options: [{ id: "fastMode", value: false }],
           },
         },
       );
     }),
   );
 
+  it.effect(
+    "decodes legacy object-shaped textGenerationModelSelection.options from settings.json",
+    () =>
+      Effect.sync(() => {
+        const decode = Schema.decodeUnknownSync(ServerSettings);
+
+        const decoded = decode({
+          textGenerationModelSelection: {
+            provider: ProviderDriverKind.make("codex"),
+            model: "gpt-5.4-mini",
+            options: { reasoningEffort: "low" },
+          },
+        });
+
+        assert.deepEqual(decoded.textGenerationModelSelection, {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5.4-mini",
+          options: [{ id: "reasoningEffort", value: "low" }],
+        });
+      }),
+  );
+
   it.effect("deep merges nested settings updates without dropping siblings", () =>
     Effect.gen(function* () {
       const serverSettings = yield* ServerSettingsService;
@@ -60,12 +89,16 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           },
         },
         textGenerationModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
-          options: {
-            reasoningEffort: "high",
-            fastMode: true,
-          },
+          options: createModelSelection(
+            ProviderInstanceId.make("codex"),
+            DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
+            [
+              { id: "reasoningEffort", value: "high" },
+              { id: "fastMode", value: true },
+            ],
+          ).options!,
         },
       });
 
@@ -76,9 +109,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           },
         },
         textGenerationModelSelection: {
-          options: {
-            fastMode: false,
-          },
+          options: [{ id: "fastMode", value: false }],
         },
       });
 
@@ -86,21 +117,27 @@ it.layer(NodeServices.layer)("server settings", (it) => {
         enabled: true,
         binaryPath: "/opt/homebrew/bin/codex",
         homePath: "/Users/julius/.codex",
+        shadowHomePath: "",
         customModels: [],
       });
       assert.deepEqual(next.providers.claudeAgent, {
         enabled: true,
         binaryPath: "/usr/local/bin/claude",
+        homePath: "",
         customModels: ["claude-custom"],
+        launchArgs: "",
       });
-      assert.deepEqual(next.textGenerationModelSelection, {
-        provider: "codex",
-        model: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
-        options: {
-          reasoningEffort: "high",
-          fastMode: false,
-        },
-      });
+      assert.deepEqual(
+        next.textGenerationModelSelection,
+        createModelSelection(
+          ProviderInstanceId.make("codex"),
+          DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
+          [
+            { id: "reasoningEffort", value: "high" },
+            { id: "fastMode", value: false },
+          ],
+        ),
+      );
     }).pipe(Effect.provide(makeServerSettingsLayer())),
   );
 
@@ -111,11 +148,13 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       // Start with Claude text generation selection
       yield* serverSettings.updateSettings({
         textGenerationModelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-sonnet-4-6",
-          options: {
-            effort: "high",
-          },
+          options: createModelSelection(
+            ProviderInstanceId.make("claudeAgent"),
+            "claude-sonnet-4-6",
+            [{ id: "effort", value: "high" }],
+          ).options!,
         },
       });
 
@@ -123,21 +162,174 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       // cause the update to lose the selected model.
       const next = yield* serverSettings.updateSettings({
         textGenerationModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5.4",
-          options: {
-            reasoningEffort: "high",
+          options: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+            { id: "reasoningEffort", value: "high" },
+          ]).options!,
+        },
+      });
+
+      assert.deepEqual(
+        next.textGenerationModelSelection,
+        createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+          { id: "reasoningEffort", value: "high" },
+        ]),
+      );
+    }).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
+
+  it.effect("preserves custom provider instance text generation selections", () =>
+    Effect.gen(function* () {
+      const serverSettings = yield* ServerSettingsService;
+
+      const next = yield* serverSettings.updateSettings({
+        providerInstances: {
+          [ProviderInstanceId.make("claude_openrouter")]: {
+            driver: ProviderDriverKind.make("claudeAgent"),
+            enabled: true,
+            config: { customModels: ["openai/gpt-5.5"] },
           },
         },
+        textGenerationModelSelection: {
+          instanceId: ProviderInstanceId.make("claude_openrouter"),
+          model: "openai/gpt-5.5",
+        },
       });
 
       assert.deepEqual(next.textGenerationModelSelection, {
-        provider: "codex",
-        model: "gpt-5.4",
-        options: {
-          reasoningEffort: "high",
+        instanceId: ProviderInstanceId.make("claude_openrouter"),
+        model: "openai/gpt-5.5",
+      });
+    }).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
+
+  it.effect(
+    "uses explicit provider instance enabled state over legacy provider enabled state",
+    () =>
+      Effect.gen(function* () {
+        const serverSettings = yield* ServerSettingsService;
+        const instanceId = ProviderInstanceId.make("claude_openrouter");
+
+        const next = yield* serverSettings.updateSettings({
+          providers: {
+            claudeAgent: {
+              enabled: false,
+            },
+          },
+          providerInstances: {
+            [instanceId]: {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              enabled: true,
+              config: { customModels: ["openai/gpt-5.5"] },
+            },
+          },
+          textGenerationModelSelection: {
+            instanceId,
+            model: "openai/gpt-5.5",
+          },
+        });
+
+        assert.deepEqual(next.textGenerationModelSelection, {
+          instanceId,
+          model: "openai/gpt-5.5",
+        });
+      }).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
+
+  it.effect("preserves enabled text generation selections for non-built-in drivers", () =>
+    Effect.gen(function* () {
+      const serverSettings = yield* ServerSettingsService;
+      const instanceId = ProviderInstanceId.make("openrouter_text");
+
+      const next = yield* serverSettings.updateSettings({
+        providerInstances: {
+          [instanceId]: {
+            driver: ProviderDriverKind.make("openrouter"),
+            enabled: true,
+            config: { customModels: ["openai/gpt-5.5"] },
+          },
+        },
+        textGenerationModelSelection: {
+          instanceId,
+          model: "openai/gpt-5.5",
         },
       });
+
+      assert.deepEqual(next.textGenerationModelSelection, {
+        instanceId,
+        model: "openai/gpt-5.5",
+      });
+    }).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
+
+  it.effect("drops stale text generation options when resetting model selection", () =>
+    Effect.gen(function* () {
+      const serverSettings = yield* ServerSettingsService;
+
+      yield* serverSettings.updateSettings({
+        textGenerationModelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
+          options: createModelSelection(
+            ProviderInstanceId.make("codex"),
+            DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
+            [
+              { id: "reasoningEffort", value: "high" },
+              { id: "fastMode", value: true },
+            ],
+          ).options!,
+        },
+      });
+
+      const next = yield* serverSettings.updateSettings({
+        textGenerationModelSelection: {
+          instanceId: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.instanceId,
+          model: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
+        },
+      });
+
+      assert.deepEqual(next.textGenerationModelSelection, {
+        instanceId: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.instanceId,
+        model: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
+      });
+    }).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
+
+  it.effect("replaces provider instance maps when clearing optional fields", () =>
+    Effect.gen(function* () {
+      const serverSettings = yield* ServerSettingsService;
+      const codexId = ProviderInstanceId.make("codex");
+
+      yield* serverSettings.updateSettings({
+        providerInstances: {
+          [codexId]: {
+            driver: ProviderDriverKind.make("codex"),
+            displayName: "Codex Work",
+            accentColor: "#7c3aed",
+            enabled: true,
+            config: { homePath: "~/.codex" },
+          },
+        },
+      });
+
+      const next = yield* serverSettings.updateSettings({
+        providerInstances: {
+          [codexId]: {
+            driver: ProviderDriverKind.make("codex"),
+            displayName: "Codex Work",
+            enabled: true,
+            config: { homePath: "~/.codex" },
+          },
+        },
+      });
+
+      assert.deepEqual(next.providerInstances[codexId], {
+        driver: ProviderDriverKind.make("codex"),
+        displayName: "Codex Work",
+        enabled: true,
+        config: { homePath: "~/.codex" },
+      });
     }).pipe(Effect.provide(makeServerSettingsLayer())),
   );
 
@@ -154,6 +346,11 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           claudeAgent: {
             binaryPath: "  /opt/homebrew/bin/claude  ",
           },
+          opencode: {
+            binaryPath: "  /opt/homebrew/bin/opencode  ",
+            serverUrl: "  http://127.0.0.1:4096  ",
+            serverPassword: "  secret-password  ",
+          },
         },
       });
 
@@ -161,11 +358,21 @@ it.layer(NodeServices.layer)("server settings", (it) => {
         enabled: true,
         binaryPath: "/opt/homebrew/bin/codex",
         homePath: "",
+        shadowHomePath: "",
         customModels: [],
       });
       assert.deepEqual(next.providers.claudeAgent, {
         enabled: true,
         binaryPath: "/opt/homebrew/bin/claude",
+        homePath: "",
+        customModels: [],
+        launchArgs: "",
+      });
+      assert.deepEqual(next.providers.opencode, {
+        enabled: true,
+        binaryPath: "/opt/homebrew/bin/opencode",
+        serverUrl: "http://127.0.0.1:4096",
+        serverPassword: "secret-password",
         customModels: [],
       });
     }).pipe(Effect.provide(makeServerSettingsLayer())),
@@ -176,12 +383,14 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       const serverSettings = yield* ServerSettingsService;
 
       const next = yield* serverSettings.updateSettings({
+        addProjectBaseDirectory: "  ~/Development  ",
         observability: {
           otlpTracesUrl: "  http://localhost:4318/v1/traces  ",
           otlpMetricsUrl: "  http://localhost:4318/v1/metrics  ",
         },
       });
 
+      assert.equal(next.addProjectBaseDirectory, "~/Development");
       assert.deepEqual(next.observability, {
         otlpTracesUrl: "http://localhost:4318/v1/traces",
         otlpMetricsUrl: "http://localhost:4318/v1/metrics",
@@ -215,6 +424,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       const serverConfig = yield* ServerConfig;
       const fileSystem = yield* FileSystem.FileSystem;
       const next = yield* serverSettings.updateSettings({
+        addProjectBaseDirectory: "~/Development",
         observability: {
           otlpTracesUrl: "http://localhost:4318/v1/traces",
           otlpMetricsUrl: "http://localhost:4318/v1/metrics",
@@ -223,13 +433,20 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           codex: {
             binaryPath: "/opt/homebrew/bin/codex",
           },
+          opencode: {
+            serverUrl: "http://127.0.0.1:4096",
+            serverPassword: "secret-password",
+          },
         },
+        automaticGitFetchInterval: Duration.seconds(10),
       });
 
       assert.equal(next.providers.codex.binaryPath, "/opt/homebrew/bin/codex");
 
       const raw = yield* fileSystem.readFileString(serverConfig.settingsPath);
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
       assert.deepEqual(JSON.parse(raw), {
+        addProjectBaseDirectory: "~/Development",
         observability: {
           otlpTracesUrl: "http://localhost:4318/v1/traces",
           otlpMetricsUrl: "http://localhost:4318/v1/metrics",
@@ -238,8 +455,77 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           codex: {
             binaryPath: "/opt/homebrew/bin/codex",
           },
+          opencode: {
+            serverUrl: "http://127.0.0.1:4096",
+            serverPassword: "secret-password",
+          },
         },
+        automaticGitFetchInterval: 10_000,
       });
     }).pipe(Effect.provide(makeServerSettingsLayer())),
   );
+
+  it.effect("stores sensitive provider instance environment values outside settings.json", () =>
+    Effect.gen(function* () {
+      const serverSettings = yield* ServerSettingsService;
+      const serverConfig = yield* ServerConfig;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const instanceId = ProviderInstanceId.make("codex_personal");
+
+      const next = yield* serverSettings.updateSettings({
+        providerInstances: {
+          [instanceId]: {
+            driver: ProviderDriverKind.make("codex"),
+            environment: [
+              { name: "OPENROUTER_API_KEY", value: "sk-or-secret", sensitive: true },
+              { name: "ANTHROPIC_BASE_URL", value: "https://openrouter.ai/api", sensitive: false },
+            ],
+            config: {},
+          },
+        },
+      });
+
+      assert.deepEqual(next.providerInstances[instanceId]?.environment, [
+        {
+          name: "OPENROUTER_API_KEY",
+          value: "sk-or-secret",
+          sensitive: true,
+          valueRedacted: true,
+        },
+        { name: "ANTHROPIC_BASE_URL", value: "https://openrouter.ai/api", sensitive: false },
+      ]);
+
+      const raw = yield* fileSystem.readFileString(serverConfig.settingsPath);
+      assert.notInclude(raw, "sk-or-secret");
+      // @effect-diagnostics-next-line preferSchemaOverJson:off
+      assert.deepEqual(JSON.parse(raw).providerInstances.codex_personal.environment, [
+        {
+          name: "OPENROUTER_API_KEY",
+          value: "",
+          sensitive: true,
+          valueRedacted: true,
+        },
+        { name: "ANTHROPIC_BASE_URL", value: "https://openrouter.ai/api", sensitive: false },
+      ]);
+
+      const roundTripped = yield* serverSettings.updateSettings({
+        providerInstances: {
+          [instanceId]: {
+            driver: ProviderDriverKind.make("codex"),
+            displayName: "Codex Personal",
+            environment: [
+              { name: "OPENROUTER_API_KEY", value: "", sensitive: true, valueRedacted: true },
+              { name: "ANTHROPIC_BASE_URL", value: "https://openrouter.ai/api", sensitive: false },
+            ],
+            config: {},
+          },
+        },
+      });
+
+      assert.equal(
+        roundTripped.providerInstances[instanceId]?.environment?.[0]?.value,
+        "sk-or-secret",
+      );
+    }).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
 });
diff --git a/apps/server/src/serverSettings.ts b/apps/server/src/serverSettings.ts
index 5a708d5c230..5ea2e03813f 100644
--- a/apps/server/src/serverSettings.ts
+++ b/apps/server/src/serverSettings.ts
@@ -11,37 +11,102 @@
  * @module ServerSettings
  */
 import {
+  DEFAULT_GIT_TEXT_GENERATION_MODEL,
   DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER,
   DEFAULT_SERVER_SETTINGS,
+  isProviderDriverKind,
   type ModelSelection,
-  type ProviderKind,
+  type ProviderInstanceConfig,
+  type ProviderInstanceEnvironmentVariable,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ServerSettings,
   ServerSettingsError,
   type ServerSettingsPatch,
 } from "@t3tools/contracts";
-import {
-  Cache,
-  Deferred,
-  Duration,
-  Effect,
-  Exit,
-  FileSystem,
-  Layer,
-  Path,
-  Equal,
-  PubSub,
-  Ref,
-  Schema,
-  SchemaIssue,
-  Scope,
-  Context,
-  Stream,
-  Cause,
-} from "effect";
+import * as Cache from "effect/Cache";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Equal from "effect/Equal";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as Scope from "effect/Scope";
+import * as Context from "effect/Context";
+import * as Stream from "effect/Stream";
+import * as Cause from "effect/Cause";
 import * as Semaphore from "effect/Semaphore";
-import { ServerConfig } from "./config";
+import { writeFileStringAtomically } from "./atomicWrite.ts";
+import { ServerConfig } from "./config.ts";
 import { type DeepPartial, deepMerge } from "@t3tools/shared/Struct";
-import { fromLenientJson } from "@t3tools/shared/schemaJson";
+import { fromJsonStringPretty, fromLenientJson } from "@t3tools/shared/schemaJson";
+import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
+import { ServerSecretStoreLive } from "./auth/Layers/ServerSecretStore.ts";
+import { ServerSecretStore } from "./auth/Services/ServerSecretStore.ts";
+
+const encodeServerSettings = Schema.encodeEffect(ServerSettings);
+const encodeServerSettingsJson = Schema.encodeUnknownEffect(fromJsonStringPretty(ServerSettings));
+const decodeServerSettings = Schema.decodeUnknownEffect(ServerSettings);
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+const normalizeServerSettings = (
+  settings: ServerSettings,
+): Effect.Effect<ServerSettings, ServerSettingsError> =>
+  encodeServerSettings(settings).pipe(
+    Effect.flatMap(decodeServerSettings),
+    Effect.mapError(
+      (cause) =>
+        new ServerSettingsError({
+          settingsPath: "<memory>",
+          detail: `failed to normalize server settings: ${SchemaIssue.makeFormatterDefault()(cause.issue)}`,
+          cause,
+        }),
+    ),
+  );
+
+function providerEnvironmentSecretName(input: {
+  readonly instanceId: string;
+  readonly name: string;
+}): string {
+  return `provider-env-${Buffer.from(input.instanceId, "utf8").toString("base64url")}-${Buffer.from(input.name, "utf8").toString("base64url")}`;
+}
+
+function redactProviderEnvironmentVariable(
+  variable: ProviderInstanceEnvironmentVariable,
+): ProviderInstanceEnvironmentVariable {
+  if (!variable.sensitive) {
+    const { valueRedacted: _omit, ...rest } = variable;
+    return rest;
+  }
+  return {
+    ...variable,
+    value: "",
+    ...(variable.value.length > 0 || variable.valueRedacted ? { valueRedacted: true } : {}),
+  };
+}
+
+export function redactServerSettingsForClient(settings: ServerSettings): ServerSettings {
+  const providerInstances = Object.fromEntries(
+    Object.entries(settings.providerInstances).map(([instanceId, instance]) => [
+      instanceId,
+      instance.environment
+        ? {
+            ...instance,
+            environment: instance.environment.map(redactProviderEnvironmentVariable),
+          }
+        : instance,
+    ]),
+  );
+  return { ...settings, providerInstances };
+}
 
 export interface ServerSettingsShape {
   /** Start the settings runtime and attach file watching. */
@@ -70,9 +135,15 @@ export class ServerSettingsService extends Context.Service<
     Layer.effect(
       ServerSettingsService,
       Effect.gen(function* () {
-        const currentSettingsRef = yield* Ref.make<ServerSettings>(
-          deepMerge(DEFAULT_SERVER_SETTINGS, overrides),
-        );
+        const { automaticGitFetchInterval, ...overridesForMerge } = overrides;
+        const merged = deepMerge(DEFAULT_SERVER_SETTINGS, overridesForMerge);
+        const initialSettings = yield* normalizeServerSettings({
+          ...merged,
+          ...(automaticGitFetchInterval !== undefined
+            ? { automaticGitFetchInterval: automaticGitFetchInterval as Duration.Duration }
+            : {}),
+        });
+        const currentSettingsRef = yield* Ref.make<ServerSettings>(initialSettings);
 
         return {
           start: Effect.void,
@@ -80,7 +151,8 @@ export class ServerSettingsService extends Context.Service<
           getSettings: Ref.get(currentSettingsRef),
           updateSettings: (patch) =>
             Ref.get(currentSettingsRef).pipe(
-              Effect.map((currentSettings) => deepMerge(currentSettings, patch)),
+              Effect.map((currentSettings) => applyServerSettingsPatch(currentSettings, patch)),
+              Effect.flatMap(normalizeServerSettings),
               Effect.tap((nextSettings) => Ref.set(currentSettingsRef, nextSettings)),
             ),
           streamChanges: Stream.empty,
@@ -90,8 +162,15 @@ export class ServerSettingsService extends Context.Service<
 }
 
 const ServerSettingsJson = fromLenientJson(ServerSettings);
+const decodeServerSettingsJsonExit = Schema.decodeUnknownExit(ServerSettingsJson);
 
-const PROVIDER_ORDER: readonly ProviderKind[] = ["codex", "claudeAgent"];
+type LegacyProviderSettings = ServerSettings["providers"][keyof ServerSettings["providers"]];
+
+const getLegacyProviderSettings = (
+  settings: ServerSettings,
+  provider: ProviderDriverKind,
+): LegacyProviderSettings | undefined =>
+  (settings.providers as Record<string, LegacyProviderSettings | undefined>)[provider];
 
 /**
  * Ensure the `textGenerationModelSelection` points to an enabled provider.
@@ -101,27 +180,44 @@ const PROVIDER_ORDER: readonly ProviderKind[] = ["codex", "claudeAgent"];
  */
 function resolveTextGenerationProvider(settings: ServerSettings): ServerSettings {
   const selection = settings.textGenerationModelSelection;
-  if (settings.providers[selection.provider].enabled) {
+  const instanceConfig = settings.providerInstances[selection.instanceId];
+  if (instanceConfig !== undefined) {
+    return (instanceConfig.enabled ?? true) ? settings : fallbackTextGenerationProvider(settings);
+  }
+
+  if (
+    isProviderDriverKind(selection.instanceId) &&
+    getLegacyProviderSettings(settings, selection.instanceId)?.enabled
+  ) {
     return settings;
   }
 
-  const fallback = PROVIDER_ORDER.find((p) => settings.providers[p].enabled);
+  return fallbackTextGenerationProvider(settings);
+}
+
+function fallbackTextGenerationProvider(settings: ServerSettings): ServerSettings {
+  const fallbackEntry = Object.entries(settings.providers).find(([, provider]) => provider.enabled);
+  const fallback = fallbackEntry ? ProviderDriverKind.make(fallbackEntry[0]) : undefined;
   if (!fallback) {
-    // No providers enabled — return as-is; callers will report the error.
     return settings;
   }
 
   return {
     ...settings,
     textGenerationModelSelection: {
-      provider: fallback,
-      model: DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER[fallback],
-    } as ModelSelection,
+      instanceId: ProviderInstanceId.make(fallback),
+      model:
+        DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER[fallback] ??
+        DEFAULT_GIT_TEXT_GENERATION_MODEL,
+    } satisfies ModelSelection,
   };
 }
 
 // Values under these keys are compared as a whole — never stripped field-by-field.
-const ATOMIC_SETTINGS_KEYS: ReadonlySet<string> = new Set(["textGenerationModelSelection"]);
+const ATOMIC_SETTINGS_KEYS: ReadonlySet<string> = new Set([
+  "automaticGitFetchInterval",
+  "textGenerationModelSelection",
+]);
 
 function stripDefaultServerSettings(current: unknown, defaults: unknown): unknown | undefined {
   if (Array.isArray(current) || Array.isArray(defaults)) {
@@ -161,6 +257,7 @@ const makeServerSettings = Effect.gen(function* () {
   const { settingsPath } = yield* ServerConfig;
   const fs = yield* FileSystem.FileSystem;
   const pathService = yield* Path.Path;
+  const secretStore = yield* ServerSecretStore;
   const writeSemaphore = yield* Semaphore.make(1);
   const cacheKey = "settings" as const;
   const changesPubSub = yield* PubSub.unbounded<ServerSettings>();
@@ -200,7 +297,7 @@ const makeServerSettings = Effect.gen(function* () {
     }
 
     const raw = yield* readRawConfig;
-    const decoded = Schema.decodeUnknownExit(ServerSettingsJson)(raw);
+    const decoded = decodeServerSettingsJsonExit(raw);
     if (decoded._tag === "Failure") {
       yield* Effect.logWarning("failed to parse settings.json, using defaults", {
         path: settingsPath,
@@ -218,25 +315,161 @@ const makeServerSettings = Effect.gen(function* () {
 
   const getSettingsFromCache = Cache.get(settingsCache, cacheKey);
 
-  const writeSettingsAtomically = (settings: ServerSettings) => {
-    const tempPath = `${settingsPath}.${process.pid}.${Date.now()}.tmp`;
-    const sparseSettings = stripDefaultServerSettings(settings, DEFAULT_SERVER_SETTINGS) ?? {};
+  const toSettingsError = (detail: string, cause: unknown) =>
+    new ServerSettingsError({
+      settingsPath,
+      detail,
+      cause,
+    });
 
-    return Effect.succeed(`${JSON.stringify(sparseSettings, null, 2)}\n`).pipe(
-      Effect.tap(() => fs.makeDirectory(pathService.dirname(settingsPath), { recursive: true })),
-      Effect.tap((encoded) => fs.writeFileString(tempPath, encoded)),
-      Effect.flatMap(() => fs.rename(tempPath, settingsPath)),
-      Effect.ensuring(fs.remove(tempPath, { force: true }).pipe(Effect.ignore({ log: true }))),
-      Effect.mapError(
-        (cause) =>
-          new ServerSettingsError({
-            settingsPath,
-            detail: "failed to write settings file",
-            cause,
-          }),
-      ),
-    );
-  };
+  const materializeProviderEnvironmentSecrets = (
+    settings: ServerSettings,
+  ): Effect.Effect<ServerSettings, ServerSettingsError> =>
+    Effect.gen(function* () {
+      const providerInstances: Record<string, ProviderInstanceConfig> = {
+        ...settings.providerInstances,
+      };
+      for (const [instanceId, instance] of Object.entries(settings.providerInstances)) {
+        if (!instance.environment) continue;
+        const environment: ProviderInstanceEnvironmentVariable[] = [];
+        for (const variable of instance.environment) {
+          if (!variable.sensitive || !variable.valueRedacted) {
+            environment.push(variable);
+            continue;
+          }
+          const secret = yield* secretStore
+            .get(providerEnvironmentSecretName({ instanceId, name: variable.name }))
+            .pipe(
+              Effect.mapError((cause) =>
+                toSettingsError(
+                  `failed to read sensitive environment variable ${variable.name}`,
+                  cause,
+                ),
+              ),
+            );
+          environment.push({
+            ...variable,
+            value: secret ? textDecoder.decode(secret) : "",
+          });
+        }
+        providerInstances[instanceId] = {
+          ...instance,
+          environment,
+        } satisfies ProviderInstanceConfig;
+      }
+      return {
+        ...settings,
+        providerInstances: providerInstances as ServerSettings["providerInstances"],
+      };
+    });
+
+  const persistProviderEnvironmentSecrets = (
+    current: ServerSettings,
+    next: ServerSettings,
+  ): Effect.Effect<ServerSettings, ServerSettingsError> =>
+    Effect.gen(function* () {
+      const providerInstances: Record<string, ProviderInstanceConfig> = {
+        ...next.providerInstances,
+      };
+
+      const nextSecretKeys = new Set<string>();
+      for (const [instanceId, instance] of Object.entries(next.providerInstances)) {
+        if (!instance.environment) continue;
+        const environment: ProviderInstanceEnvironmentVariable[] = [];
+        for (const variable of instance.environment) {
+          const secretName = providerEnvironmentSecretName({ instanceId, name: variable.name });
+          if (!variable.sensitive) {
+            yield* secretStore
+              .remove(secretName)
+              .pipe(
+                Effect.mapError((cause) =>
+                  toSettingsError(`failed to remove environment secret ${variable.name}`, cause),
+                ),
+              );
+            environment.push(redactProviderEnvironmentVariable(variable));
+            continue;
+          }
+
+          nextSecretKeys.add(secretName);
+          if (!variable.valueRedacted) {
+            if (variable.value.length > 0) {
+              yield* secretStore
+                .set(secretName, textEncoder.encode(variable.value))
+                .pipe(
+                  Effect.mapError((cause) =>
+                    toSettingsError(`failed to persist environment secret ${variable.name}`, cause),
+                  ),
+                );
+              environment.push({ ...variable, value: "", valueRedacted: true });
+            } else {
+              yield* secretStore
+                .remove(secretName)
+                .pipe(
+                  Effect.mapError((cause) =>
+                    toSettingsError(`failed to remove environment secret ${variable.name}`, cause),
+                  ),
+                );
+              const { valueRedacted: _omit, ...rest } = variable;
+              environment.push(rest);
+            }
+            continue;
+          }
+
+          environment.push(redactProviderEnvironmentVariable(variable));
+        }
+        providerInstances[instanceId] = {
+          ...instance,
+          environment,
+        } satisfies ProviderInstanceConfig;
+      }
+
+      for (const [instanceId, instance] of Object.entries(current.providerInstances)) {
+        for (const variable of instance.environment ?? []) {
+          if (!variable.sensitive) continue;
+          const secretName = providerEnvironmentSecretName({ instanceId, name: variable.name });
+          if (nextSecretKeys.has(secretName)) continue;
+          yield* secretStore
+            .remove(secretName)
+            .pipe(
+              Effect.mapError((cause) =>
+                toSettingsError(
+                  `failed to remove stale environment secret ${variable.name}`,
+                  cause,
+                ),
+              ),
+            );
+        }
+      }
+
+      return {
+        ...next,
+        providerInstances: providerInstances as ServerSettings["providerInstances"],
+      };
+    });
+
+  const writeSettingsAtomically = Effect.fnUntraced(
+    function* (settings: ServerSettings) {
+      const sparseSettingsJson = yield* encodeServerSettingsJson(
+        stripDefaultServerSettings(settings, DEFAULT_SERVER_SETTINGS) ?? {},
+      );
+
+      return yield* writeFileStringAtomically({
+        filePath: settingsPath,
+        contents: `${sparseSettingsJson}\n`,
+      }).pipe(
+        Effect.provideService(FileSystem.FileSystem, fs),
+        Effect.provideService(Path.Path, pathService),
+      );
+    },
+    Effect.mapError(
+      (cause) =>
+        new ServerSettingsError({
+          settingsPath,
+          detail: "failed to write settings file",
+          cause,
+        }),
+    ),
+  );
 
   const revalidateAndEmit = writeSemaphore.withPermits(1)(
     Effect.gen(function* () {
@@ -309,31 +542,43 @@ const makeServerSettings = Effect.gen(function* () {
   return {
     start,
     ready: Deferred.await(startedDeferred),
-    getSettings: getSettingsFromCache.pipe(Effect.map(resolveTextGenerationProvider)),
+    getSettings: getSettingsFromCache.pipe(
+      Effect.flatMap(materializeProviderEnvironmentSecrets),
+      Effect.map(resolveTextGenerationProvider),
+    ),
     updateSettings: (patch) =>
       writeSemaphore.withPermits(1)(
         Effect.gen(function* () {
           const current = yield* getSettingsFromCache;
-          const next = yield* Schema.decodeEffect(ServerSettings)(deepMerge(current, patch)).pipe(
-            Effect.mapError(
-              (cause) =>
-                new ServerSettingsError({
-                  settingsPath: "<memory>",
-                  detail: `failed to normalize server settings: ${SchemaIssue.makeFormatterDefault()(cause.issue)}`,
-                  cause,
-                }),
-            ),
+          const nextPersisted = yield* persistProviderEnvironmentSecrets(
+            current,
+            applyServerSettingsPatch(current, patch),
           );
+          const next = yield* normalizeServerSettings(nextPersisted);
           yield* writeSettingsAtomically(next);
           yield* Cache.set(settingsCache, cacheKey, next);
           yield* emitChange(next);
-          return resolveTextGenerationProvider(next);
+          const materialized = yield* materializeProviderEnvironmentSecrets(next);
+          return resolveTextGenerationProvider(materialized);
         }),
       ),
     get streamChanges() {
-      return Stream.fromPubSub(changesPubSub).pipe(Stream.map(resolveTextGenerationProvider));
+      return Stream.fromPubSub(changesPubSub).pipe(
+        Stream.mapEffect((settings) =>
+          materializeProviderEnvironmentSecrets(settings).pipe(
+            Effect.catch((error: ServerSettingsError) =>
+              Effect.logWarning("failed to materialize provider environment secrets", {
+                detail: error.detail,
+              }).pipe(Effect.as(settings)),
+            ),
+          ),
+        ),
+        Stream.map(resolveTextGenerationProvider),
+      );
     },
   } satisfies ServerSettingsShape;
 });
 
-export const ServerSettingsLive = Layer.effect(ServerSettingsService, makeServerSettings);
+export const ServerSettingsLive = Layer.effect(ServerSettingsService, makeServerSettings).pipe(
+  Layer.provide(ServerSecretStoreLive),
+);
diff --git a/apps/server/src/sourceControl/AzureDevOpsCli.test.ts b/apps/server/src/sourceControl/AzureDevOpsCli.test.ts
new file mode 100644
index 00000000000..6958f42fb13
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsCli.test.ts
@@ -0,0 +1,294 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it, afterEach, describe, expect, vi } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as AzureDevOpsCli from "./AzureDevOpsCli.ts";
+
+const processOutput = (stdout: string): VcsProcess.VcsProcessOutput => ({
+  exitCode: ChildProcessSpawner.ExitCode(0),
+  stdout,
+  stderr: "",
+  stdoutTruncated: false,
+  stderrTruncated: false,
+});
+
+const mockRun = vi.fn<VcsProcess.VcsProcessShape["run"]>();
+
+const supportLayer = Layer.mergeAll(
+  Layer.mock(VcsProcess.VcsProcess)({
+    run: mockRun,
+  }),
+  NodeServices.layer,
+);
+const layer = Layer.mergeAll(AzureDevOpsCli.layer.pipe(Layer.provide(supportLayer)), supportLayer);
+
+afterEach(() => {
+  mockRun.mockReset();
+});
+
+describe("AzureDevOpsCli.layer", () => {
+  it.effect("parses pull request view output", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              pullRequestId: 42,
+              title: "Add Azure provider",
+              sourceRefName: "refs/heads/feature/source-control",
+              targetRefName: "refs/heads/main",
+              status: "active",
+              creationDate: "2026-01-02T00:00:00.000Z",
+              closedDate: null,
+              _links: {
+                web: {
+                  href: "https://dev.azure.com/acme/project/_git/repo/pullrequest/42",
+                },
+              },
+            }),
+          ),
+        ),
+      );
+
+      const az = yield* AzureDevOpsCli.AzureDevOpsCli;
+      const result = yield* az.getPullRequest({
+        cwd: "/repo",
+        reference: "#42",
+      });
+
+      assert.strictEqual(result.number, 42);
+      assert.strictEqual(result.title, "Add Azure provider");
+      assert.strictEqual(result.baseRefName, "main");
+      assert.strictEqual(result.headRefName, "feature/source-control");
+      assert.strictEqual(result.state, "open");
+      assert.deepStrictEqual(result.updatedAt._tag, Option.some(1)._tag);
+      assert.deepStrictEqual(mockRun.mock.calls.at(-1)?.[0], {
+        operation: "AzureDevOpsCli.execute",
+        command: "az",
+        args: [
+          "repos",
+          "pr",
+          "show",
+          "--detect",
+          "true",
+          "--id",
+          "42",
+          "--only-show-errors",
+          "--output",
+          "json",
+        ],
+        cwd: "/repo",
+        timeoutMs: 30_000,
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("lists pull requests with Azure status and source branch arguments", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify([
+              {
+                pullRequestId: 7,
+                title: "Merged work",
+                sourceRefName: "refs/heads/feature/merged",
+                targetRefName: "refs/heads/main",
+                status: "completed",
+                closedDate: "2026-01-03T00:00:00.000Z",
+                _links: {
+                  web: {
+                    href: "https://dev.azure.com/acme/project/_git/repo/pullrequest/7",
+                  },
+                },
+              },
+            ]),
+          ),
+        ),
+      );
+
+      const az = yield* AzureDevOpsCli.AzureDevOpsCli;
+      const result = yield* az.listPullRequests({
+        cwd: "/repo",
+        headSelector: "origin:feature/merged",
+        state: "merged",
+        limit: 10,
+      });
+
+      assert.strictEqual(result[0]?.state, "merged");
+      expect(mockRun).toHaveBeenCalledWith({
+        operation: "AzureDevOpsCli.execute",
+        command: "az",
+        args: [
+          "repos",
+          "pr",
+          "list",
+          "--detect",
+          "true",
+          "--source-branch",
+          "feature/merged",
+          "--status",
+          "completed",
+          "--top",
+          "10",
+          "--only-show-errors",
+          "--output",
+          "json",
+        ],
+        cwd: "/repo",
+        timeoutMs: 30_000,
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("reads repository clone URLs", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              name: "repo",
+              webUrl: "https://dev.azure.com/acme/project/_git/repo",
+              remoteUrl: "https://dev.azure.com/acme/project/_git/repo",
+              sshUrl: "git@ssh.dev.azure.com:v3/acme/project/repo",
+              project: {
+                name: "project",
+              },
+            }),
+          ),
+        ),
+      );
+
+      const az = yield* AzureDevOpsCli.AzureDevOpsCli;
+      const result = yield* az.getRepositoryCloneUrls({
+        cwd: "/repo",
+        repository: "repo",
+      });
+
+      assert.deepStrictEqual(result, {
+        nameWithOwner: "project/repo",
+        url: "https://dev.azure.com/acme/project/_git/repo",
+        sshUrl: "git@ssh.dev.azure.com:v3/acme/project/repo",
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("creates repositories through Azure Repos", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              name: "repo",
+              webUrl: "https://dev.azure.com/acme/project/_git/repo",
+              remoteUrl: "https://dev.azure.com/acme/project/_git/repo",
+              sshUrl: "git@ssh.dev.azure.com:v3/acme/project/repo",
+              project: {
+                name: "project",
+              },
+            }),
+          ),
+        ),
+      );
+
+      const az = yield* AzureDevOpsCli.AzureDevOpsCli;
+      const result = yield* az.createRepository({
+        cwd: "/repo",
+        repository: "project/repo",
+        visibility: "private",
+      });
+
+      assert.deepStrictEqual(result, {
+        nameWithOwner: "project/repo",
+        url: "https://dev.azure.com/acme/project/_git/repo",
+        sshUrl: "git@ssh.dev.azure.com:v3/acme/project/repo",
+      });
+      expect(mockRun).toHaveBeenCalledWith({
+        operation: "AzureDevOpsCli.execute",
+        command: "az",
+        args: [
+          "repos",
+          "create",
+          "--detect",
+          "true",
+          "--name",
+          "repo",
+          "--project",
+          "project",
+          "--only-show-errors",
+          "--output",
+          "json",
+        ],
+        cwd: "/repo",
+        timeoutMs: 30_000,
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("creates pull requests using the body file as the Azure description", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const bodyFile = `/tmp/t3code-azure-devops-cli-.md`;
+      yield* fileSystem.writeFileString(bodyFile, "Generated body");
+      mockRun.mockReturnValueOnce(Effect.succeed(processOutput("{}")));
+
+      const az = yield* AzureDevOpsCli.AzureDevOpsCli;
+      yield* az.createPullRequest({
+        cwd: "/repo",
+        baseBranch: "main",
+        headSelector: "feature/provider",
+        title: "Provider PR",
+        bodyFile,
+      });
+
+      expect(mockRun).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "az",
+          cwd: "/repo",
+          args: expect.arrayContaining(["--description", `@${bodyFile}`]),
+        }),
+      );
+      expect(mockRun.mock.calls[0]?.[0].args).not.toContain("--output");
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("does not force JSON output on checkout side-effect commands", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(Effect.succeed(processOutput("")));
+
+      const az = yield* AzureDevOpsCli.AzureDevOpsCli;
+      yield* az.checkoutPullRequest({
+        cwd: "/repo",
+        reference: "42",
+      });
+
+      expect(mockRun).toHaveBeenCalledWith({
+        operation: "AzureDevOpsCli.execute",
+        command: "az",
+        args: [
+          "repos",
+          "pr",
+          "checkout",
+          "--only-show-errors",
+          "--detect",
+          "true",
+          "--id",
+          "42",
+          "--remote-name",
+          "origin",
+        ],
+        cwd: "/repo",
+        timeoutMs: 30_000,
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+});
diff --git a/apps/server/src/sourceControl/AzureDevOpsCli.ts b/apps/server/src/sourceControl/AzureDevOpsCli.ts
new file mode 100644
index 00000000000..d4a4d69267b
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsCli.ts
@@ -0,0 +1,434 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import {
+  TrimmedNonEmptyString,
+  type SourceControlRepositoryVisibility,
+  type VcsError,
+} from "@t3tools/contracts";
+
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as AzureDevOpsPullRequests from "./azureDevOpsPullRequests.ts";
+import * as SourceControlProvider from "./SourceControlProvider.ts";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class AzureDevOpsCliError extends Schema.TaggedErrorClass<AzureDevOpsCliError>()(
+  "AzureDevOpsCliError",
+  {
+    operation: Schema.String,
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `Azure DevOps CLI failed in ${this.operation}: ${this.detail}`;
+  }
+}
+
+export interface AzureDevOpsRepositoryCloneUrls {
+  readonly nameWithOwner: string;
+  readonly url: string;
+  readonly sshUrl: string;
+}
+
+export interface AzureDevOpsCliShape {
+  readonly execute: (input: {
+    readonly cwd: string;
+    readonly args: ReadonlyArray<string>;
+    readonly timeoutMs?: number;
+  }) => Effect.Effect<VcsProcess.VcsProcessOutput, AzureDevOpsCliError>;
+
+  readonly listPullRequests: (input: {
+    readonly cwd: string;
+    readonly headSelector: string;
+    readonly source?: SourceControlProvider.SourceControlRefSelector;
+    readonly state: "open" | "closed" | "merged" | "all";
+    readonly limit?: number;
+  }) => Effect.Effect<
+    ReadonlyArray<AzureDevOpsPullRequests.NormalizedAzureDevOpsPullRequestRecord>,
+    AzureDevOpsCliError
+  >;
+
+  readonly getPullRequest: (input: {
+    readonly cwd: string;
+    readonly reference: string;
+  }) => Effect.Effect<
+    AzureDevOpsPullRequests.NormalizedAzureDevOpsPullRequestRecord,
+    AzureDevOpsCliError
+  >;
+
+  readonly getRepositoryCloneUrls: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+  }) => Effect.Effect<AzureDevOpsRepositoryCloneUrls, AzureDevOpsCliError>;
+
+  readonly createRepository: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+    readonly visibility: SourceControlRepositoryVisibility;
+  }) => Effect.Effect<AzureDevOpsRepositoryCloneUrls, AzureDevOpsCliError>;
+
+  readonly createPullRequest: (input: {
+    readonly cwd: string;
+    readonly baseBranch: string;
+    readonly headSelector: string;
+    readonly source?: SourceControlProvider.SourceControlRefSelector;
+    readonly target?: SourceControlProvider.SourceControlRefSelector;
+    readonly title: string;
+    readonly bodyFile: string;
+  }) => Effect.Effect<void, AzureDevOpsCliError>;
+
+  readonly getDefaultBranch: (input: {
+    readonly cwd: string;
+  }) => Effect.Effect<string | null, AzureDevOpsCliError>;
+
+  readonly checkoutPullRequest: (input: {
+    readonly cwd: string;
+    readonly reference: string;
+    readonly remoteName?: string;
+  }) => Effect.Effect<void, AzureDevOpsCliError>;
+}
+
+export class AzureDevOpsCli extends Context.Service<AzureDevOpsCli, AzureDevOpsCliShape>()(
+  "t3/source-control/AzureDevOpsCli",
+) {}
+
+function errorText(error: VcsError | unknown): string {
+  if (typeof error === "object" && error !== null) {
+    const tag = "_tag" in error && typeof error._tag === "string" ? error._tag : "";
+    const detail = "detail" in error && typeof error.detail === "string" ? error.detail : "";
+    const message = "message" in error && typeof error.message === "string" ? error.message : "";
+    return [tag, detail, message].filter(Boolean).join("\n");
+  }
+
+  return String(error);
+}
+
+function normalizeAzureDevOpsCliError(
+  operation: "execute",
+  error: VcsError | unknown,
+): AzureDevOpsCliError {
+  const text = errorText(error);
+  const lower = text.toLowerCase();
+
+  if (lower.includes("command not found: az") || lower.includes("enoent")) {
+    return new AzureDevOpsCliError({
+      operation,
+      detail:
+        "Azure CLI (`az`) with the Azure DevOps extension is required but not available on PATH.",
+      cause: error,
+    });
+  }
+
+  if (
+    lower.includes("az devops login") ||
+    lower.includes("please run az login") ||
+    lower.includes("not logged in") ||
+    lower.includes("authentication failed") ||
+    lower.includes("unauthorized")
+  ) {
+    return new AzureDevOpsCliError({
+      operation,
+      detail: "Azure DevOps CLI is not authenticated. Run `az devops login` and retry.",
+      cause: error,
+    });
+  }
+
+  if (
+    lower.includes("pull request") &&
+    (lower.includes("not found") || lower.includes("does not exist"))
+  ) {
+    return new AzureDevOpsCliError({
+      operation,
+      detail: "Pull request not found. Check the PR number or URL and try again.",
+      cause: error,
+    });
+  }
+
+  return new AzureDevOpsCliError({
+    operation,
+    detail: text,
+    cause: error,
+  });
+}
+
+function normalizeChangeRequestId(reference: string): string {
+  const trimmed = reference.trim().replace(/^#/, "");
+  const urlMatch = /(?:pullrequest|pull-request|pull|_pulls?)\/(\d+)(?:\D.*)?$/i.exec(trimmed);
+  return urlMatch?.[1] ?? trimmed;
+}
+
+function toAzureStatus(state: "open" | "closed" | "merged" | "all"): string {
+  switch (state) {
+    case "open":
+      return "active";
+    case "closed":
+      return "abandoned";
+    case "merged":
+      return "completed";
+    case "all":
+      return "all";
+  }
+}
+
+const RawAzureDevOpsRepositorySchema = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  webUrl: TrimmedNonEmptyString,
+  remoteUrl: TrimmedNonEmptyString,
+  sshUrl: TrimmedNonEmptyString,
+  project: Schema.optional(
+    Schema.Struct({
+      name: TrimmedNonEmptyString,
+    }),
+  ),
+  defaultBranch: Schema.optional(Schema.NullOr(Schema.String)),
+});
+
+function normalizeDefaultBranch(value: string | null | undefined): string | null {
+  const trimmed = value?.trim().replace(/^refs\/heads\//, "") ?? "";
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeRepositoryCloneUrls(
+  raw: Schema.Schema.Type<typeof RawAzureDevOpsRepositorySchema>,
+): AzureDevOpsRepositoryCloneUrls {
+  const projectName = raw.project?.name.trim();
+  return {
+    nameWithOwner: projectName ? `${projectName}/${raw.name}` : raw.name,
+    url: raw.remoteUrl,
+    sshUrl: raw.sshUrl,
+  };
+}
+
+function parseRepositorySpecifier(repository: string): {
+  readonly project: string | null;
+  readonly name: string;
+} {
+  const parts = repository
+    .split("/")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  return {
+    project: parts.length > 1 ? (parts.at(-2) ?? null) : null,
+    name: parts.at(-1) ?? repository.trim(),
+  };
+}
+
+function decodeAzureDevOpsJson<S extends Schema.Top>(
+  raw: string,
+  schema: S,
+  operation: "getRepositoryCloneUrls" | "getDefaultBranch" | "createRepository",
+  invalidDetail: string,
+): Effect.Effect<S["Type"], AzureDevOpsCliError, S["DecodingServices"]> {
+  return Schema.decodeEffect(Schema.fromJsonString(schema))(raw).pipe(
+    Effect.mapError(
+      (error) =>
+        new AzureDevOpsCliError({
+          operation,
+          detail: `${invalidDetail}: ${SchemaIssue.makeFormatterDefault()(error.issue)}`,
+          cause: error,
+        }),
+    ),
+  );
+}
+
+export const make = Effect.fn("makeAzureDevOpsCli")(function* () {
+  const process = yield* VcsProcess.VcsProcess;
+
+  const execute: AzureDevOpsCliShape["execute"] = (input) =>
+    process
+      .run({
+        operation: "AzureDevOpsCli.execute",
+        command: "az",
+        args: input.args,
+        cwd: input.cwd,
+        timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      })
+      .pipe(Effect.mapError((error) => normalizeAzureDevOpsCliError("execute", error)));
+
+  const executeJson = (input: Parameters<AzureDevOpsCliShape["execute"]>[0]) =>
+    execute({
+      ...input,
+      args: [...input.args, "--only-show-errors", "--output", "json"],
+    });
+
+  return AzureDevOpsCli.of({
+    execute,
+    listPullRequests: (input) =>
+      executeJson({
+        cwd: input.cwd,
+        args: [
+          "repos",
+          "pr",
+          "list",
+          "--detect",
+          "true",
+          "--source-branch",
+          SourceControlProvider.sourceBranch(input),
+          "--status",
+          toAzureStatus(input.state),
+          "--top",
+          String(input.limit ?? 20),
+        ],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          raw.length === 0
+            ? Effect.succeed([])
+            : Effect.sync(() =>
+                AzureDevOpsPullRequests.decodeAzureDevOpsPullRequestListJson(raw),
+              ).pipe(
+                Effect.flatMap((decoded) => {
+                  if (!Result.isSuccess(decoded)) {
+                    return Effect.fail(
+                      new AzureDevOpsCliError({
+                        operation: "listPullRequests",
+                        detail: `Azure DevOps CLI returned invalid PR list JSON: ${AzureDevOpsPullRequests.formatAzureDevOpsJsonDecodeError(decoded.failure)}`,
+                        cause: decoded.failure,
+                      }),
+                    );
+                  }
+
+                  return Effect.succeed(decoded.success);
+                }),
+              ),
+        ),
+      ),
+    getPullRequest: (input) =>
+      executeJson({
+        cwd: input.cwd,
+        args: [
+          "repos",
+          "pr",
+          "show",
+          "--detect",
+          "true",
+          "--id",
+          normalizeChangeRequestId(input.reference),
+        ],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          Effect.sync(() => AzureDevOpsPullRequests.decodeAzureDevOpsPullRequestJson(raw)).pipe(
+            Effect.flatMap((decoded) => {
+              if (!Result.isSuccess(decoded)) {
+                return Effect.fail(
+                  new AzureDevOpsCliError({
+                    operation: "getPullRequest",
+                    detail: `Azure DevOps CLI returned invalid pull request JSON: ${AzureDevOpsPullRequests.formatAzureDevOpsJsonDecodeError(decoded.failure)}`,
+                    cause: decoded.failure,
+                  }),
+                );
+              }
+
+              return Effect.succeed(decoded.success);
+            }),
+          ),
+        ),
+      ),
+    getRepositoryCloneUrls: (input) =>
+      executeJson({
+        cwd: input.cwd,
+        args: ["repos", "show", "--detect", "true", "--repository", input.repository],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          decodeAzureDevOpsJson(
+            raw,
+            RawAzureDevOpsRepositorySchema,
+            "getRepositoryCloneUrls",
+            "Azure DevOps CLI returned invalid repository JSON.",
+          ),
+        ),
+        Effect.map(normalizeRepositoryCloneUrls),
+      ),
+    createRepository: (input) => {
+      const repository = parseRepositorySpecifier(input.repository);
+      // Azure Repos access is governed by project/organization permissions.
+      // `az repos create` does not expose a per-repository visibility flag, so
+      // the generic source-control visibility input is intentionally not
+      // translated into CLI args for this provider.
+      return executeJson({
+        cwd: input.cwd,
+        args: [
+          "repos",
+          "create",
+          "--detect",
+          "true",
+          "--name",
+          repository.name,
+          ...(repository.project ? ["--project", repository.project] : []),
+        ],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          decodeAzureDevOpsJson(
+            raw,
+            RawAzureDevOpsRepositorySchema,
+            "createRepository",
+            "Azure DevOps CLI returned invalid repository JSON.",
+          ),
+        ),
+        Effect.map(normalizeRepositoryCloneUrls),
+      );
+    },
+    createPullRequest: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: [
+          "repos",
+          "pr",
+          "create",
+          "--only-show-errors",
+          "--detect",
+          "true",
+          "--target-branch",
+          input.target?.refName ?? input.baseBranch,
+          "--source-branch",
+          SourceControlProvider.sourceBranch(input),
+          "--title",
+          input.title,
+          "--description",
+          `@${input.bodyFile}`,
+        ],
+      }).pipe(Effect.asVoid),
+    getDefaultBranch: (input) =>
+      executeJson({
+        cwd: input.cwd,
+        args: ["repos", "show", "--detect", "true"],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          decodeAzureDevOpsJson(
+            raw,
+            RawAzureDevOpsRepositorySchema,
+            "getDefaultBranch",
+            "Azure DevOps CLI returned invalid repository JSON.",
+          ),
+        ),
+        Effect.map((repo) => normalizeDefaultBranch(repo.defaultBranch)),
+      ),
+    checkoutPullRequest: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: [
+          "repos",
+          "pr",
+          "checkout",
+          "--only-show-errors",
+          "--detect",
+          "true",
+          "--id",
+          normalizeChangeRequestId(input.reference),
+          "--remote-name",
+          input.remoteName ?? "origin",
+        ],
+      }).pipe(Effect.asVoid),
+  });
+});
+
+export const layer = Layer.effect(AzureDevOpsCli, make());
diff --git a/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.test.ts b/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.test.ts
new file mode 100644
index 00000000000..4ba3777159b
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.test.ts
@@ -0,0 +1,93 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as AzureDevOpsCli from "./AzureDevOpsCli.ts";
+import * as AzureDevOpsSourceControlProvider from "./AzureDevOpsSourceControlProvider.ts";
+
+function makeProvider(azure: Partial<AzureDevOpsCli.AzureDevOpsCliShape>) {
+  return AzureDevOpsSourceControlProvider.make().pipe(
+    Effect.provide(Layer.mock(AzureDevOpsCli.AzureDevOpsCli)(azure)),
+  );
+}
+
+it.effect("maps Azure DevOps PR summaries into provider-neutral change requests", () =>
+  Effect.gen(function* () {
+    const provider = yield* makeProvider({
+      getPullRequest: () =>
+        Effect.succeed({
+          number: 42,
+          title: "Add Azure provider",
+          url: "https://dev.azure.com/acme/project/_git/repo/pullrequest/42",
+          baseRefName: "main",
+          headRefName: "feature/source-control",
+          state: "open",
+          updatedAt: Option.none(),
+        }),
+    });
+
+    const changeRequest = yield* provider.getChangeRequest({
+      cwd: "/repo",
+      reference: "42",
+    });
+
+    assert.deepStrictEqual(changeRequest, {
+      provider: "azure-devops",
+      number: 42,
+      title: "Add Azure provider",
+      url: "https://dev.azure.com/acme/project/_git/repo/pullrequest/42",
+      baseRefName: "main",
+      headRefName: "feature/source-control",
+      state: "open",
+      updatedAt: Option.none(),
+      isCrossRepository: false,
+    });
+  }),
+);
+
+it.effect("creates Azure DevOps PRs through provider-neutral input names", () =>
+  Effect.gen(function* () {
+    let createInput: Parameters<AzureDevOpsCli.AzureDevOpsCliShape["createPullRequest"]>[0] | null =
+      null;
+    const provider = yield* makeProvider({
+      createPullRequest: (input) => {
+        createInput = input;
+        return Effect.void;
+      },
+    });
+
+    yield* provider.createChangeRequest({
+      cwd: "/repo",
+      baseRefName: "main",
+      headSelector: "feature/provider",
+      title: "Provider PR",
+      bodyFile: "/tmp/body.md",
+    });
+
+    assert.deepStrictEqual(createInput, {
+      cwd: "/repo",
+      baseBranch: "main",
+      headSelector: "feature/provider",
+      title: "Provider PR",
+      bodyFile: "/tmp/body.md",
+    });
+  }),
+);
+
+it.effect("uses Azure CLI repository detection for default branch lookup", () =>
+  Effect.gen(function* () {
+    let cwdInput: string | null = null;
+    const provider = yield* makeProvider({
+      getDefaultBranch: (input) => {
+        cwdInput = input.cwd;
+        return Effect.succeed("main");
+      },
+    });
+
+    const defaultBranch = yield* provider.getDefaultBranch({ cwd: "/repo" });
+
+    assert.strictEqual(defaultBranch, "main");
+    assert.strictEqual(cwdInput, "/repo");
+  }),
+);
diff --git a/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.ts b/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.ts
new file mode 100644
index 00000000000..8d8e081cb89
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.ts
@@ -0,0 +1,145 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { SourceControlProviderError, type ChangeRequest } from "@t3tools/contracts";
+
+import * as AzureDevOpsCli from "./AzureDevOpsCli.ts";
+import * as SourceControlProvider from "./SourceControlProvider.ts";
+import * as SourceControlProviderDiscovery from "./SourceControlProviderDiscovery.ts";
+
+function providerError(
+  operation: string,
+  cause: AzureDevOpsCli.AzureDevOpsCliError,
+): SourceControlProviderError {
+  return new SourceControlProviderError({
+    provider: "azure-devops",
+    operation,
+    detail: cause.detail,
+    cause,
+  });
+}
+
+function parseAzureAuth(input: SourceControlProviderDiscovery.SourceControlAuthProbeInput) {
+  const account = input.stdout.trim().split(/\r?\n/)[0]?.trim();
+
+  if (input.exitCode !== 0) {
+    return SourceControlProviderDiscovery.providerAuth({
+      status: "unauthenticated",
+      detail:
+        SourceControlProviderDiscovery.firstSafeAuthLine(
+          SourceControlProviderDiscovery.combinedAuthOutput(input),
+        ) ?? "Run `az login` to authenticate Azure CLI.",
+    });
+  }
+
+  if (account !== undefined && account.length > 0) {
+    return SourceControlProviderDiscovery.providerAuth({
+      status: "authenticated",
+      account,
+      host: "dev.azure.com",
+    });
+  }
+
+  return SourceControlProviderDiscovery.providerAuth({
+    status: "unknown",
+    host: "dev.azure.com",
+    detail: "Azure CLI account status could not be parsed.",
+  });
+}
+
+export const discovery = {
+  type: "cli",
+  kind: "azure-devops",
+  label: "Azure DevOps",
+  executable: "az",
+  versionArgs: ["--version"],
+  authArgs: ["account", "show", "--query", "user.name", "-o", "tsv"],
+  parseAuth: parseAzureAuth,
+  installHint:
+    "Install the Azure command-line tools (`az`), then enable Azure DevOps support with `az extension add --name azure-devops`.",
+} satisfies SourceControlProviderDiscovery.SourceControlCliDiscoverySpec;
+
+function toChangeRequest(summary: {
+  readonly number: number;
+  readonly title: string;
+  readonly url: string;
+  readonly baseRefName: string;
+  readonly headRefName: string;
+  readonly state: "open" | "closed" | "merged";
+  readonly updatedAt: ChangeRequest["updatedAt"];
+}): ChangeRequest {
+  return {
+    provider: "azure-devops",
+    number: summary.number,
+    title: summary.title,
+    url: summary.url,
+    baseRefName: summary.baseRefName,
+    headRefName: summary.headRefName,
+    state: summary.state,
+    updatedAt: summary.updatedAt,
+    isCrossRepository: false,
+  };
+}
+
+export const make = Effect.fn("makeAzureDevOpsSourceControlProvider")(function* () {
+  const azure = yield* AzureDevOpsCli.AzureDevOpsCli;
+
+  return SourceControlProvider.SourceControlProvider.of({
+    kind: "azure-devops",
+    listChangeRequests: (input) => {
+      const source = SourceControlProvider.sourceControlRefFromInput(input);
+      return azure
+        .listPullRequests({
+          cwd: input.cwd,
+          headSelector: input.headSelector,
+          ...(source !== undefined ? { source } : {}),
+          state: input.state,
+          ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        })
+        .pipe(
+          Effect.map((items) => items.map(toChangeRequest)),
+          Effect.mapError((error) => providerError("listChangeRequests", error)),
+        );
+    },
+    getChangeRequest: (input) =>
+      azure.getPullRequest(input).pipe(
+        Effect.map(toChangeRequest),
+        Effect.mapError((error) => providerError("getChangeRequest", error)),
+      ),
+    createChangeRequest: (input) => {
+      const source = SourceControlProvider.sourceControlRefFromInput(input);
+      return azure
+        .createPullRequest({
+          cwd: input.cwd,
+          baseBranch: input.baseRefName,
+          headSelector: input.headSelector,
+          ...(source !== undefined ? { source } : {}),
+          ...(input.target !== undefined ? { target: input.target } : {}),
+          title: input.title,
+          bodyFile: input.bodyFile,
+        })
+        .pipe(Effect.mapError((error) => providerError("createChangeRequest", error)));
+    },
+    getRepositoryCloneUrls: (input) =>
+      azure
+        .getRepositoryCloneUrls(input)
+        .pipe(Effect.mapError((error) => providerError("getRepositoryCloneUrls", error))),
+    createRepository: (input) =>
+      azure
+        .createRepository(input)
+        .pipe(Effect.mapError((error) => providerError("createRepository", error))),
+    getDefaultBranch: (input) =>
+      azure
+        .getDefaultBranch({ cwd: input.cwd })
+        .pipe(Effect.mapError((error) => providerError("getDefaultBranch", error))),
+    checkoutChangeRequest: (input) =>
+      azure
+        .checkoutPullRequest({
+          cwd: input.cwd,
+          reference: input.reference,
+          ...(input.context !== undefined ? { remoteName: input.context.remoteName } : {}),
+        })
+        .pipe(Effect.mapError((error) => providerError("checkoutChangeRequest", error))),
+  });
+});
+
+export const layer = Layer.effect(SourceControlProvider.SourceControlProvider, make());
diff --git a/apps/server/src/sourceControl/BitbucketApi.test.ts b/apps/server/src/sourceControl/BitbucketApi.test.ts
new file mode 100644
index 00000000000..e93362b8423
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketApi.test.ts
@@ -0,0 +1,611 @@
+import { assert, it, vi } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+
+import * as BitbucketApi from "./BitbucketApi.ts";
+import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
+import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
+import type * as VcsDriver from "../vcs/VcsDriver.ts";
+
+const bitbucketPullRequest = {
+  id: 42,
+  title: "Add Bitbucket provider",
+  state: "OPEN",
+  updated_on: "2026-01-02T00:00:00.000Z",
+  links: {
+    html: {
+      href: "https://bitbucket.org/pingdotgg/t3code/pull-requests/42",
+    },
+  },
+  source: {
+    branch: { name: "feature/source-control" },
+    repository: {
+      full_name: "octocat/t3code",
+      workspace: { slug: "octocat" },
+    },
+  },
+  destination: {
+    branch: { name: "main" },
+    repository: {
+      full_name: "pingdotgg/t3code",
+      workspace: { slug: "pingdotgg" },
+    },
+  },
+};
+
+const repositoryJson = {
+  full_name: "pingdotgg/t3code",
+  links: {
+    html: { href: "https://bitbucket.org/pingdotgg/t3code" },
+    clone: [
+      { name: "https", href: "https://bitbucket.org/pingdotgg/t3code.git" },
+      { name: "ssh", href: "git@bitbucket.org:pingdotgg/t3code.git" },
+    ],
+  },
+  mainbranch: { name: "main" },
+};
+
+function makeLayer(input: {
+  readonly response: (request: HttpClientRequest.HttpClientRequest) => Response;
+  readonly git?: Partial<GitVcsDriver.GitVcsDriverShape>;
+}) {
+  const execute = vi.fn((request: HttpClientRequest.HttpClientRequest) =>
+    Effect.succeed(HttpClientResponse.fromWeb(request, input.response(request))),
+  );
+  const gitMock = {
+    readConfigValue: vi.fn<GitVcsDriver.GitVcsDriverShape["readConfigValue"]>(() =>
+      Effect.succeed<string | null>("git@bitbucket.org:pingdotgg/t3code.git"),
+    ),
+    resolvePrimaryRemoteName: vi.fn<GitVcsDriver.GitVcsDriverShape["resolvePrimaryRemoteName"]>(
+      () => Effect.succeed("origin"),
+    ),
+    ensureRemote: vi.fn<GitVcsDriver.GitVcsDriverShape["ensureRemote"]>(() =>
+      Effect.succeed("octocat"),
+    ),
+    fetchRemoteBranch: vi.fn<GitVcsDriver.GitVcsDriverShape["fetchRemoteBranch"]>(
+      () => Effect.void,
+    ),
+    fetchRemoteTrackingBranch: vi.fn<GitVcsDriver.GitVcsDriverShape["fetchRemoteTrackingBranch"]>(
+      () => Effect.void,
+    ),
+    setBranchUpstream: vi.fn<GitVcsDriver.GitVcsDriverShape["setBranchUpstream"]>(
+      () => Effect.void,
+    ),
+    switchRef: vi.fn<GitVcsDriver.GitVcsDriverShape["switchRef"]>((request) =>
+      Effect.succeed({ refName: request.refName }),
+    ),
+    listLocalBranchNames: vi.fn<GitVcsDriver.GitVcsDriverShape["listLocalBranchNames"]>(() =>
+      Effect.succeed([]),
+    ),
+  };
+  const git = {
+    ...gitMock,
+    ...input.git,
+  } satisfies Partial<GitVcsDriver.GitVcsDriverShape>;
+
+  const driver = {
+    listRemotes: () =>
+      Effect.succeed({
+        remotes: [
+          {
+            name: "origin",
+            url: "git@bitbucket.org:pingdotgg/t3code.git",
+            pushUrl: Option.none(),
+            isPrimary: true,
+          },
+        ],
+        freshness: {
+          source: "live-local" as const,
+          observedAt: DateTime.makeUnsafe("1970-01-01T00:00:00.000Z"),
+          expiresAt: Option.none(),
+        },
+      }),
+  } satisfies Partial<VcsDriver.VcsDriverShape>;
+
+  const layer = BitbucketApi.layer.pipe(
+    Layer.provide(
+      Layer.succeed(
+        HttpClient.HttpClient,
+        HttpClient.make((request) => execute(request)),
+      ),
+    ),
+    Layer.provide(
+      Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
+        resolve: () =>
+          Effect.succeed({
+            kind: "git",
+            repository: {
+              kind: "git",
+              rootPath: "/repo",
+              metadataPath: null,
+              freshness: {
+                source: "live-local" as const,
+                observedAt: DateTime.makeUnsafe("1970-01-01T00:00:00.000Z"),
+                expiresAt: Option.none(),
+              },
+            },
+            driver: driver as unknown as VcsDriver.VcsDriverShape,
+          }),
+      }),
+    ),
+    Layer.provide(Layer.mock(GitVcsDriver.GitVcsDriver)(git)),
+    Layer.provide(
+      ConfigProvider.layer(
+        ConfigProvider.fromEnv({
+          env: {
+            T3CODE_BITBUCKET_API_BASE_URL: "https://api.test.local/2.0",
+            T3CODE_BITBUCKET_EMAIL: "user@example.com",
+            T3CODE_BITBUCKET_API_TOKEN: "token",
+          },
+        }),
+      ),
+    ),
+    Layer.provideMerge(NodeServices.layer),
+  );
+
+  return { execute, git: gitMock, layer };
+}
+
+it.effect("parses pull request responses from the Bitbucket REST API", () => {
+  const { execute, layer } = makeLayer({
+    response: () =>
+      Response.json({
+        ...bitbucketPullRequest,
+      }),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    const result = yield* bitbucket.getPullRequest({
+      cwd: "/repo",
+      reference: "#42",
+    });
+
+    assert.deepStrictEqual(result, {
+      number: 42,
+      title: "Add Bitbucket provider",
+      url: "https://bitbucket.org/pingdotgg/t3code/pull-requests/42",
+      baseRefName: "main",
+      headRefName: "feature/source-control",
+      state: "open",
+      updatedAt: Option.some(DateTime.makeUnsafe("2026-01-02T00:00:00.000Z")),
+      isCrossRepository: true,
+      headRepositoryNameWithOwner: "octocat/t3code",
+      headRepositoryOwnerLogin: "octocat",
+    });
+    assert.strictEqual(
+      execute.mock.calls[0]?.[0].url,
+      "https://api.test.local/2.0/repositories/pingdotgg/t3code/pullrequests/42",
+    );
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect("lists pull requests with Bitbucket state and source branch query params", () => {
+  const { execute, layer } = makeLayer({
+    response: () =>
+      Response.json({
+        values: [
+          {
+            ...bitbucketPullRequest,
+            id: 7,
+            state: "MERGED",
+            source: {
+              branch: { name: "feature/merged" },
+              repository: { full_name: "pingdotgg/t3code" },
+            },
+          },
+        ],
+      }),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    const result = yield* bitbucket.listPullRequests({
+      cwd: "/repo",
+      headSelector: "origin:feature/merged",
+      state: "merged",
+      limit: 10,
+    });
+
+    assert.strictEqual(result[0]?.state, "merged");
+    const request = execute.mock.calls[0]?.[0];
+    assert.strictEqual(
+      request?.url,
+      "https://api.test.local/2.0/repositories/pingdotgg/t3code/pullrequests",
+    );
+    assert.deepStrictEqual(request?.urlParams.params, [
+      ["pagelen", "10"],
+      ["sort", "-updated_on"],
+      ["q", 'source.branch.name = "feature/merged" AND state = "MERGED"'],
+      ["state", "MERGED"],
+    ]);
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect("lists closed pull requests with both closed Bitbucket states", () => {
+  const { execute, layer } = makeLayer({
+    response: () =>
+      Response.json({
+        values: [],
+      }),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    yield* bitbucket.listPullRequests({
+      cwd: "/repo",
+      headSelector: "feature/closed",
+      state: "closed",
+      limit: 10,
+    });
+
+    assert.deepStrictEqual(execute.mock.calls[0]?.[0].urlParams.params, [
+      ["pagelen", "10"],
+      ["sort", "-updated_on"],
+      [
+        "q",
+        'source.branch.name = "feature/closed" AND (state = "DECLINED" OR state = "SUPERSEDED")',
+      ],
+      ["state", "DECLINED"],
+      ["state", "SUPERSEDED"],
+    ]);
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect("expands all-state pull request listing instead of relying on Bitbucket defaults", () => {
+  const { execute, layer } = makeLayer({
+    response: () =>
+      Response.json({
+        values: [],
+      }),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    yield* bitbucket.listPullRequests({
+      cwd: "/repo",
+      headSelector: "feature/all",
+      state: "all",
+      limit: 10,
+    });
+
+    assert.deepStrictEqual(execute.mock.calls[0]?.[0].urlParams.params, [
+      ["pagelen", "10"],
+      ["sort", "-updated_on"],
+      [
+        "q",
+        'source.branch.name = "feature/all" AND (state = "OPEN" OR state = "MERGED" OR state = "DECLINED" OR state = "SUPERSEDED")',
+      ],
+      ["state", "OPEN"],
+      ["state", "MERGED"],
+      ["state", "DECLINED"],
+      ["state", "SUPERSEDED"],
+    ]);
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect("reads repository clone URLs and default branch", () => {
+  const { layer } = makeLayer({
+    response: (request) =>
+      Response.json(
+        request.url.endsWith("/branching-model")
+          ? {
+              development: {
+                branch: { name: "main" },
+                name: "main",
+                use_mainbranch: true,
+              },
+            }
+          : repositoryJson,
+      ),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    const cloneUrls = yield* bitbucket.getRepositoryCloneUrls({
+      cwd: "/repo",
+      repository: "pingdotgg/t3code",
+    });
+    const defaultBranch = yield* bitbucket.getDefaultBranch({ cwd: "/repo" });
+
+    assert.deepStrictEqual(cloneUrls, {
+      nameWithOwner: "pingdotgg/t3code",
+      url: "https://bitbucket.org/pingdotgg/t3code.git",
+      sshUrl: "git@bitbucket.org:pingdotgg/t3code.git",
+    });
+    assert.strictEqual(defaultBranch, "main");
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect(
+  "prefers the Bitbucket branching model development branch as the default PR target",
+  () => {
+    const { execute, layer } = makeLayer({
+      response: (request) =>
+        Response.json(
+          request.url.endsWith("/branching-model")
+            ? {
+                development: {
+                  branch: { name: "develop" },
+                  name: "develop",
+                  use_mainbranch: false,
+                },
+              }
+            : repositoryJson,
+        ),
+    });
+
+    return Effect.gen(function* () {
+      const bitbucket = yield* BitbucketApi.BitbucketApi;
+      const defaultBranch = yield* bitbucket.getDefaultBranch({ cwd: "/repo" });
+
+      assert.strictEqual(defaultBranch, "develop");
+      assert.deepStrictEqual(
+        execute.mock.calls.map((call) => call[0].url).toSorted(),
+        [
+          "https://api.test.local/2.0/repositories/pingdotgg/t3code",
+          "https://api.test.local/2.0/repositories/pingdotgg/t3code/branching-model",
+        ].toSorted(),
+      );
+    }).pipe(Effect.provide(layer));
+  },
+);
+
+it.effect(
+  "falls back to the repository main branch when the Bitbucket development branch is invalid",
+  () => {
+    const { layer } = makeLayer({
+      response: (request) =>
+        Response.json(
+          request.url.endsWith("/branching-model")
+            ? {
+                development: {
+                  name: "develop",
+                  use_mainbranch: false,
+                  is_valid: false,
+                },
+              }
+            : repositoryJson,
+        ),
+    });
+
+    return Effect.gen(function* () {
+      const bitbucket = yield* BitbucketApi.BitbucketApi;
+      const defaultBranch = yield* bitbucket.getDefaultBranch({ cwd: "/repo" });
+
+      assert.strictEqual(defaultBranch, "main");
+    }).pipe(Effect.provide(layer));
+  },
+);
+
+it.effect(
+  "falls back to the repository main branch when the Bitbucket branching model is unavailable",
+  () => {
+    const { layer } = makeLayer({
+      response: (request) =>
+        request.url.endsWith("/branching-model")
+          ? Response.json({ error: { message: "Not found" } }, { status: 404 })
+          : Response.json(repositoryJson),
+    });
+
+    return Effect.gen(function* () {
+      const bitbucket = yield* BitbucketApi.BitbucketApi;
+      const defaultBranch = yield* bitbucket.getDefaultBranch({ cwd: "/repo" });
+
+      assert.strictEqual(defaultBranch, "main");
+    }).pipe(Effect.provide(layer));
+  },
+);
+
+it.effect("creates repositories through the Bitbucket REST API", () => {
+  const { execute, layer } = makeLayer({
+    response: () => Response.json(repositoryJson),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    const cloneUrls = yield* bitbucket.createRepository({
+      cwd: "/repo",
+      repository: "pingdotgg/t3code",
+      visibility: "private",
+    });
+
+    assert.deepStrictEqual(cloneUrls, {
+      nameWithOwner: "pingdotgg/t3code",
+      url: "https://bitbucket.org/pingdotgg/t3code.git",
+      sshUrl: "git@bitbucket.org:pingdotgg/t3code.git",
+    });
+
+    const request = execute.mock.calls[0]?.[0];
+    assert.strictEqual(request?.url, "https://api.test.local/2.0/repositories/pingdotgg/t3code");
+    assert.strictEqual(request?.method, "POST");
+    assert.ok(request);
+    const rawBody = (request.body as { readonly body?: Uint8Array }).body;
+    assert.ok(rawBody);
+    // @effect-diagnostics-next-line preferSchemaOverJson:off
+    assert.deepStrictEqual(JSON.parse(new TextDecoder().decode(rawBody)), {
+      scm: "git",
+      is_private: true,
+    });
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect("creates pull requests using the official REST payload shape", () => {
+  const { execute, layer } = makeLayer({
+    response: () => Response.json(bitbucketPullRequest),
+  });
+
+  return Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const bodyFile = yield* fileSystem.makeTempFileScoped({ prefix: "bitbucket-pr-body-" });
+    yield* fileSystem.writeFileString(bodyFile, "PR body");
+
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    yield* bitbucket.createPullRequest({
+      cwd: "/repo",
+      baseBranch: "main",
+      headSelector: "owner:feature/provider",
+      title: "Provider PR",
+      bodyFile,
+    });
+
+    const request = execute.mock.calls[0]?.[0];
+    assert.strictEqual(
+      request?.url,
+      "https://api.test.local/2.0/repositories/pingdotgg/t3code/pullrequests",
+    );
+    assert.strictEqual(request?.method, "POST");
+    assert.ok(request);
+    const rawBody = (request.body as { readonly body?: Uint8Array }).body;
+    assert.ok(rawBody);
+    // @effect-diagnostics-next-line preferSchemaOverJson:off
+    assert.deepStrictEqual(JSON.parse(new TextDecoder().decode(rawBody)), {
+      title: "Provider PR",
+      description: "PR body",
+      source: {
+        branch: { name: "feature/provider" },
+        repository: { full_name: "owner/t3code" },
+      },
+      destination: {
+        branch: { name: "main" },
+      },
+    });
+  }).pipe(Effect.provide(layer), Effect.scoped);
+});
+
+it.effect("reports auth status through the Bitbucket REST /user endpoint", () => {
+  const { layer } = makeLayer({
+    response: () => Response.json({ username: "bitbucket-user" }),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    const auth = yield* bitbucket.probeAuth;
+
+    assert.deepStrictEqual(auth, {
+      status: "authenticated",
+      account: Option.some("bitbucket-user"),
+      host: Option.some("bitbucket.org"),
+      detail: Option.none(),
+    });
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect("checks out same-repository pull requests with the existing Bitbucket remote", () => {
+  const { git, layer } = makeLayer({
+    response: () =>
+      Response.json({
+        ...bitbucketPullRequest,
+        source: {
+          branch: { name: "feature/source-control" },
+          repository: {
+            full_name: "pingdotgg/t3code",
+            workspace: { slug: "pingdotgg" },
+          },
+        },
+      }),
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    yield* bitbucket.checkoutPullRequest({
+      cwd: "/repo",
+      context: {
+        provider: {
+          kind: "bitbucket",
+          name: "Bitbucket",
+          baseUrl: "https://bitbucket.org",
+        },
+        remoteName: "origin",
+        remoteUrl: "git@bitbucket.org:pingdotgg/t3code.git",
+      },
+      reference: "42",
+      force: true,
+    });
+
+    assert.strictEqual(git.ensureRemote.mock.calls.length, 0);
+    assert.deepStrictEqual(git.fetchRemoteBranch.mock.calls[0]?.[0], {
+      cwd: "/repo",
+      remoteName: "origin",
+      remoteBranch: "feature/source-control",
+      localBranch: "feature/source-control",
+    });
+    assert.deepStrictEqual(git.setBranchUpstream.mock.calls[0]?.[0], {
+      cwd: "/repo",
+      branch: "feature/source-control",
+      remoteName: "origin",
+      remoteBranch: "feature/source-control",
+    });
+    assert.deepStrictEqual(git.switchRef.mock.calls[0]?.[0], {
+      cwd: "/repo",
+      refName: "feature/source-control",
+    });
+  }).pipe(Effect.provide(layer));
+});
+
+it.effect("checks out fork pull requests through an ensured fork remote", () => {
+  const { git, layer } = makeLayer({
+    response: (request) => {
+      if (request.url.endsWith("/repositories/octocat/t3code")) {
+        return Response.json({
+          ...repositoryJson,
+          full_name: "octocat/t3code",
+          links: {
+            html: { href: "https://bitbucket.org/octocat/t3code" },
+            clone: [
+              { name: "https", href: "https://bitbucket.org/octocat/t3code.git" },
+              { name: "ssh", href: "git@bitbucket.org:octocat/t3code.git" },
+            ],
+          },
+        });
+      }
+      return Response.json({
+        ...bitbucketPullRequest,
+        source: {
+          branch: { name: "main" },
+          repository: {
+            full_name: "octocat/t3code",
+            workspace: { slug: "octocat" },
+          },
+        },
+      });
+    },
+  });
+
+  return Effect.gen(function* () {
+    const bitbucket = yield* BitbucketApi.BitbucketApi;
+    yield* bitbucket.checkoutPullRequest({
+      cwd: "/repo",
+      reference: "42",
+      force: true,
+    });
+
+    assert.deepStrictEqual(git.ensureRemote.mock.calls[0]?.[0], {
+      cwd: "/repo",
+      preferredName: "octocat",
+      url: "git@bitbucket.org:octocat/t3code.git",
+    });
+    assert.deepStrictEqual(git.fetchRemoteBranch.mock.calls[0]?.[0], {
+      cwd: "/repo",
+      remoteName: "octocat",
+      remoteBranch: "main",
+      localBranch: "t3code/pr-42/main",
+    });
+    assert.deepStrictEqual(git.setBranchUpstream.mock.calls[0]?.[0], {
+      cwd: "/repo",
+      branch: "t3code/pr-42/main",
+      remoteName: "octocat",
+      remoteBranch: "main",
+    });
+    assert.deepStrictEqual(git.switchRef.mock.calls[0]?.[0], {
+      cwd: "/repo",
+      refName: "t3code/pr-42/main",
+    });
+  }).pipe(Effect.provide(layer));
+});
diff --git a/apps/server/src/sourceControl/BitbucketApi.ts b/apps/server/src/sourceControl/BitbucketApi.ts
new file mode 100644
index 00000000000..748113ba04f
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketApi.ts
@@ -0,0 +1,769 @@
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import {
+  TrimmedNonEmptyString,
+  type SourceControlProviderAuth,
+  type SourceControlRepositoryCloneUrls,
+  type SourceControlRepositoryVisibility,
+} from "@t3tools/contracts";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+import { sanitizeBranchFragment } from "@t3tools/shared/git";
+import { detectSourceControlProviderFromRemoteUrl } from "@t3tools/shared/sourceControl";
+
+import * as BitbucketPullRequests from "./bitbucketPullRequests.ts";
+import * as SourceControlProvider from "./SourceControlProvider.ts";
+import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
+import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
+
+const DEFAULT_API_BASE_URL = "https://api.bitbucket.org/2.0";
+
+const BitbucketApiEnvConfig = Config.all({
+  baseUrl: Config.string("T3CODE_BITBUCKET_API_BASE_URL").pipe(
+    Config.withDefault(DEFAULT_API_BASE_URL),
+  ),
+  accessToken: Config.string("T3CODE_BITBUCKET_ACCESS_TOKEN").pipe(Config.option),
+  email: Config.string("T3CODE_BITBUCKET_EMAIL").pipe(Config.option),
+  apiToken: Config.string("T3CODE_BITBUCKET_API_TOKEN").pipe(Config.option),
+});
+
+export class BitbucketApiError extends Schema.TaggedErrorClass<BitbucketApiError>()(
+  "BitbucketApiError",
+  {
+    operation: Schema.String,
+    detail: Schema.String,
+    status: Schema.optional(Schema.Number),
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `Bitbucket API failed in ${this.operation}: ${this.detail}`;
+  }
+}
+const isBitbucketApiErrorValue = Schema.is(BitbucketApiError);
+
+const RawBitbucketRepositorySchema = Schema.Struct({
+  full_name: TrimmedNonEmptyString,
+  links: Schema.Struct({
+    html: Schema.optional(
+      Schema.Struct({
+        href: TrimmedNonEmptyString,
+      }),
+    ),
+    clone: Schema.optional(
+      Schema.Array(
+        Schema.Struct({
+          name: TrimmedNonEmptyString,
+          href: TrimmedNonEmptyString,
+        }),
+      ),
+    ),
+  }),
+  mainbranch: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        name: TrimmedNonEmptyString,
+      }),
+    ),
+  ),
+});
+
+const RawBitbucketBranchingModelSchema = Schema.Struct({
+  development: Schema.optional(
+    Schema.Struct({
+      branch: Schema.optional(
+        Schema.NullOr(
+          Schema.Struct({
+            name: Schema.optional(TrimmedNonEmptyString),
+          }),
+        ),
+      ),
+      is_valid: Schema.optional(Schema.Boolean),
+      name: Schema.optional(Schema.NullOr(Schema.String)),
+      use_mainbranch: Schema.optional(Schema.Boolean),
+    }),
+  ),
+});
+
+const BitbucketUserSchema = Schema.Struct({
+  username: Schema.optional(TrimmedNonEmptyString),
+  display_name: Schema.optional(TrimmedNonEmptyString),
+  account_id: Schema.optional(TrimmedNonEmptyString),
+});
+
+export interface BitbucketRepositoryLocator {
+  readonly workspace: string;
+  readonly repoSlug: string;
+}
+
+export interface BitbucketApiShape {
+  readonly probeAuth: Effect.Effect<SourceControlProviderAuth, never>;
+  readonly listPullRequests: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly headSelector: string;
+    readonly source?: SourceControlProvider.SourceControlRefSelector;
+    readonly state: "open" | "closed" | "merged" | "all";
+    readonly limit?: number;
+  }) => Effect.Effect<
+    ReadonlyArray<BitbucketPullRequests.NormalizedBitbucketPullRequestRecord>,
+    BitbucketApiError
+  >;
+  readonly getPullRequest: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly reference: string;
+  }) => Effect.Effect<
+    BitbucketPullRequests.NormalizedBitbucketPullRequestRecord,
+    BitbucketApiError
+  >;
+  readonly getRepositoryCloneUrls: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly repository: string;
+  }) => Effect.Effect<SourceControlRepositoryCloneUrls, BitbucketApiError>;
+  readonly createRepository: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+    readonly visibility: SourceControlRepositoryVisibility;
+  }) => Effect.Effect<SourceControlRepositoryCloneUrls, BitbucketApiError>;
+  readonly createPullRequest: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly baseBranch: string;
+    readonly headSelector: string;
+    readonly source?: SourceControlProvider.SourceControlRefSelector;
+    readonly target?: SourceControlProvider.SourceControlRefSelector;
+    readonly title: string;
+    readonly bodyFile: string;
+  }) => Effect.Effect<void, BitbucketApiError>;
+  readonly getDefaultBranch: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+  }) => Effect.Effect<string | null, BitbucketApiError>;
+  readonly checkoutPullRequest: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly reference: string;
+    readonly force?: boolean;
+  }) => Effect.Effect<void, BitbucketApiError>;
+}
+
+export class BitbucketApi extends Context.Service<BitbucketApi, BitbucketApiShape>()(
+  "t3/source-control/BitbucketApi",
+) {}
+
+function nonEmpty(value: string | undefined): Option.Option<string> {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? Option.none() : Option.some(trimmed);
+}
+
+function normalizeChangeRequestId(reference: string): string {
+  const trimmed = reference.trim().replace(/^#/, "");
+  const urlMatch = /(?:pull-requests|pullrequests|pull-request|pull|pr)\/(\d+)(?:\D.*)?$/i.exec(
+    trimmed,
+  );
+  return urlMatch?.[1] ?? trimmed;
+}
+
+function sourceWorkspace(input: {
+  readonly headSelector: string;
+  readonly source?: SourceControlProvider.SourceControlRefSelector;
+}): string | undefined {
+  if (input.source?.owner) return input.source.owner;
+  return SourceControlProvider.parseSourceControlOwnerRef(input.headSelector)?.owner;
+}
+
+function toBitbucketStates(state: "open" | "closed" | "merged" | "all"): ReadonlyArray<string> {
+  switch (state) {
+    case "open":
+      return ["OPEN"];
+    case "closed":
+      return ["DECLINED", "SUPERSEDED"];
+    case "merged":
+      return ["MERGED"];
+    case "all":
+      return ["OPEN", "MERGED", "DECLINED", "SUPERSEDED"];
+  }
+}
+
+function bitbucketQueryString(filters: ReadonlyArray<string>): string {
+  return filters.join(" AND ");
+}
+
+function bitbucketStateFilter(states: ReadonlyArray<string>): string {
+  return states.length === 1
+    ? `state = "${states[0]}"`
+    : `(${states.map((state) => `state = "${state}"`).join(" OR ")})`;
+}
+
+function parseBitbucketRepositorySlug(value: string): BitbucketRepositoryLocator | null {
+  const normalized = value.trim().replace(/\.git$/u, "");
+  const parts = normalized.split("/").filter((part) => part.length > 0);
+  if (parts.length < 2) return null;
+  const workspace = parts.at(-2);
+  const repoSlug = parts.at(-1);
+  return workspace && repoSlug ? { workspace, repoSlug } : null;
+}
+
+function requireRepositoryLocator(
+  operation: string,
+  repository: string,
+): Effect.Effect<BitbucketRepositoryLocator, BitbucketApiError> {
+  const locator = parseBitbucketRepositorySlug(repository);
+  return locator
+    ? Effect.succeed(locator)
+    : Effect.fail(
+        new BitbucketApiError({
+          operation,
+          detail: "Bitbucket repositories must be specified as workspace/repository.",
+        }),
+      );
+}
+
+function parseBitbucketRemoteUrl(remoteUrl: string): BitbucketRepositoryLocator | null {
+  const trimmed = remoteUrl.trim();
+  if (trimmed.startsWith("git@")) {
+    const pathStart = trimmed.indexOf(":");
+    return pathStart < 0 ? null : parseBitbucketRepositorySlug(trimmed.slice(pathStart + 1));
+  }
+
+  try {
+    return parseBitbucketRepositorySlug(new URL(trimmed).pathname);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRepositoryCloneUrls(
+  raw: typeof RawBitbucketRepositorySchema.Type,
+): SourceControlRepositoryCloneUrls {
+  const httpClone =
+    raw.links.clone?.find((entry) => entry.name.toLowerCase() === "https")?.href ??
+    raw.links.html?.href;
+  const sshClone = raw.links.clone?.find((entry) => entry.name.toLowerCase() === "ssh")?.href;
+
+  return {
+    nameWithOwner: raw.full_name,
+    url: httpClone ?? raw.links.html?.href ?? raw.full_name,
+    sshUrl: sshClone ?? httpClone ?? raw.full_name,
+  };
+}
+
+function defaultChangeRequestTargetBranch(input: {
+  readonly repository: typeof RawBitbucketRepositorySchema.Type;
+  readonly branchingModel: typeof RawBitbucketBranchingModelSchema.Type | null;
+}): string | null {
+  const repositoryMainBranch = input.repository.mainbranch?.name ?? null;
+  const development = input.branchingModel?.development;
+  if (!development || development.use_mainbranch === true || development.is_valid === false) {
+    return repositoryMainBranch;
+  }
+
+  const developmentBranch = development.branch?.name?.trim() ?? development.name?.trim() ?? "";
+  if (developmentBranch.length === 0 || developmentBranch === "null") {
+    return repositoryMainBranch;
+  }
+
+  return developmentBranch;
+}
+
+function shouldPreferSshRemote(originRemoteUrl: string | null): boolean {
+  const trimmed = originRemoteUrl?.trim() ?? "";
+  return trimmed.startsWith("git@") || trimmed.startsWith("ssh://");
+}
+
+function selectCloneUrl(input: {
+  readonly cloneUrls: SourceControlRepositoryCloneUrls;
+  readonly originRemoteUrl: string | null;
+}): string {
+  return shouldPreferSshRemote(input.originRemoteUrl)
+    ? input.cloneUrls.sshUrl
+    : input.cloneUrls.url;
+}
+
+function checkoutBranchName(input: {
+  readonly pullRequestId: number;
+  readonly headBranch: string;
+  readonly isCrossRepository: boolean;
+}): string {
+  if (!input.isCrossRepository) {
+    return input.headBranch;
+  }
+
+  return `t3code/pr-${input.pullRequestId}/${sanitizeBranchFragment(input.headBranch)}`;
+}
+
+function repositoryNameWithOwner(
+  repository: Schema.Schema.Type<
+    typeof BitbucketPullRequests.BitbucketPullRequestSchema
+  >["source"]["repository"],
+): string | null {
+  const fullName = repository?.full_name?.trim() ?? "";
+  return fullName.length > 0 ? fullName : null;
+}
+
+function repositoryOwnerName(repositoryName: string): string {
+  return repositoryName.split("/")[0]?.trim() || "bitbucket";
+}
+
+function authFromConfig(
+  config: Config.Success<typeof BitbucketApiEnvConfig>,
+): SourceControlProviderAuth {
+  if (Option.isSome(config.accessToken)) {
+    return {
+      status: "unknown",
+      account: Option.none(),
+      host: Option.some("bitbucket.org"),
+      detail: Option.some("Bitbucket access token is configured."),
+    };
+  }
+
+  if (Option.isSome(config.email) && Option.isSome(config.apiToken)) {
+    return {
+      status: "unknown",
+      account: config.email,
+      host: Option.some("bitbucket.org"),
+      detail: Option.some("Bitbucket API token is configured."),
+    };
+  }
+
+  return {
+    status: "unauthenticated",
+    account: Option.none(),
+    host: Option.some("bitbucket.org"),
+    detail: Option.some(
+      "Set T3CODE_BITBUCKET_EMAIL and T3CODE_BITBUCKET_API_TOKEN, or T3CODE_BITBUCKET_ACCESS_TOKEN.",
+    ),
+  };
+}
+
+function requestError(operation: string, cause: unknown): BitbucketApiError {
+  return new BitbucketApiError({
+    operation,
+    detail: cause instanceof Error ? cause.message : String(cause),
+    cause,
+  });
+}
+
+function isBitbucketApiError(cause: unknown): cause is BitbucketApiError {
+  return isBitbucketApiErrorValue(cause);
+}
+
+function responseError(
+  operation: string,
+  response: HttpClientResponse.HttpClientResponse,
+): Effect.Effect<never, BitbucketApiError> {
+  return response.text.pipe(
+    Effect.catch(() => Effect.succeed("")),
+    Effect.flatMap((body) =>
+      Effect.fail(
+        new BitbucketApiError({
+          operation,
+          status: response.status,
+          detail:
+            body.trim().length > 0
+              ? `Bitbucket returned HTTP ${response.status}: ${body.trim()}`
+              : `Bitbucket returned HTTP ${response.status}.`,
+        }),
+      ),
+    ),
+  );
+}
+
+export const make = Effect.fn("makeBitbucketApi")(function* () {
+  const config = yield* BitbucketApiEnvConfig;
+  const httpClient = yield* HttpClient.HttpClient;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const git = yield* GitVcsDriver.GitVcsDriver;
+  const vcsRegistry = yield* VcsDriverRegistry.VcsDriverRegistry;
+
+  const apiUrl = (path: string) => `${config.baseUrl.replace(/\/+$/u, "")}${path}`;
+
+  const withAuth = (request: HttpClientRequest.HttpClientRequest) => {
+    if (Option.isSome(config.accessToken)) {
+      return request.pipe(HttpClientRequest.bearerToken(config.accessToken.value));
+    }
+    if (Option.isSome(config.email) && Option.isSome(config.apiToken)) {
+      return request.pipe(HttpClientRequest.basicAuth(config.email.value, config.apiToken.value));
+    }
+    return request;
+  };
+
+  const decodeResponse = <S extends Schema.Top>(
+    operation: string,
+    schema: S,
+    response: HttpClientResponse.HttpClientResponse,
+  ): Effect.Effect<S["Type"], BitbucketApiError, S["DecodingServices"]> =>
+    HttpClientResponse.matchStatus({
+      "2xx": (success) =>
+        HttpClientResponse.schemaBodyJson(schema)(success).pipe(
+          Effect.mapError(
+            (cause) =>
+              new BitbucketApiError({
+                operation,
+                detail: "Bitbucket returned invalid JSON for the requested resource.",
+                cause,
+              }),
+          ),
+        ),
+      orElse: (failed) => responseError(operation, failed),
+    })(response);
+
+  const executeJson = <S extends Schema.Top>(
+    operation: string,
+    request: HttpClientRequest.HttpClientRequest,
+    schema: S,
+  ): Effect.Effect<S["Type"], BitbucketApiError, S["DecodingServices"]> =>
+    httpClient.execute(withAuth(request.pipe(HttpClientRequest.acceptJson))).pipe(
+      Effect.mapError((cause) => requestError(operation, cause)),
+      Effect.flatMap((response) => decodeResponse(operation, schema, response)),
+    );
+
+  const resolveRepository = Effect.fn("BitbucketApi.resolveRepository")(function* (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly repository?: string;
+  }) {
+    const fromRepository =
+      input.repository !== undefined ? parseBitbucketRepositorySlug(input.repository) : null;
+    if (fromRepository) return fromRepository;
+
+    const fromContext =
+      input.context?.provider.kind === "bitbucket"
+        ? parseBitbucketRemoteUrl(input.context.remoteUrl)
+        : null;
+    if (fromContext) return fromContext;
+
+    const handle = yield* vcsRegistry.resolve({ cwd: input.cwd }).pipe(
+      Effect.mapError(
+        (cause) =>
+          new BitbucketApiError({
+            operation: "resolveRepository",
+            detail: `Failed to resolve VCS repository for ${input.cwd}.`,
+            cause,
+          }),
+      ),
+    );
+    const remotes = yield* handle.driver.listRemotes(input.cwd).pipe(
+      Effect.mapError(
+        (cause) =>
+          new BitbucketApiError({
+            operation: "resolveRepository",
+            detail: `Failed to list remotes for ${input.cwd}.`,
+            cause,
+          }),
+      ),
+    );
+
+    for (const remote of remotes.remotes) {
+      if (detectSourceControlProviderFromRemoteUrl(remote.url)?.kind !== "bitbucket") continue;
+      const parsed = parseBitbucketRemoteUrl(remote.url);
+      if (parsed) return parsed;
+    }
+
+    return yield* new BitbucketApiError({
+      operation: "resolveRepository",
+      detail: `No Bitbucket repository remote was detected for ${input.cwd}.`,
+    });
+  });
+
+  const getRepositoryFromLocator = (repository: BitbucketRepositoryLocator) =>
+    executeJson(
+      "getRepository",
+      HttpClientRequest.get(
+        apiUrl(
+          `/repositories/${encodeURIComponent(repository.workspace)}/${encodeURIComponent(repository.repoSlug)}`,
+        ),
+      ),
+      RawBitbucketRepositorySchema,
+    );
+
+  const getRepository = (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly repository?: string;
+  }) => resolveRepository(input).pipe(Effect.flatMap(getRepositoryFromLocator));
+
+  const getBranchingModelFromLocator = (repository: BitbucketRepositoryLocator) =>
+    executeJson(
+      "getBranchingModel",
+      HttpClientRequest.get(
+        apiUrl(
+          `/repositories/${encodeURIComponent(repository.workspace)}/${encodeURIComponent(repository.repoSlug)}/branching-model`,
+        ),
+      ),
+      RawBitbucketBranchingModelSchema,
+    );
+
+  const getRawPullRequestFromRepository = (
+    repository: BitbucketRepositoryLocator,
+    reference: string,
+  ) =>
+    executeJson(
+      "getPullRequest",
+      HttpClientRequest.get(
+        apiUrl(
+          `/repositories/${encodeURIComponent(repository.workspace)}/${encodeURIComponent(repository.repoSlug)}/pullrequests/${encodeURIComponent(normalizeChangeRequestId(reference))}`,
+        ),
+      ),
+      BitbucketPullRequests.BitbucketPullRequestSchema,
+    );
+
+  const getRawPullRequest = (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly reference: string;
+  }) =>
+    resolveRepository(input).pipe(
+      Effect.flatMap((repository) => getRawPullRequestFromRepository(repository, input.reference)),
+    );
+
+  const readConfigValueNullable = (cwd: string, key: string) =>
+    git.readConfigValue(cwd, key).pipe(Effect.catch(() => Effect.succeed(null)));
+
+  const resolveCheckoutRemote = Effect.fn("BitbucketApi.resolveCheckoutRemote")(function* (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly destinationRepository: BitbucketRepositoryLocator;
+    readonly sourceRepositoryName: string;
+    readonly isCrossRepository: boolean;
+  }) {
+    if (
+      input.context?.provider.kind === "bitbucket" &&
+      !input.isCrossRepository &&
+      parseBitbucketRemoteUrl(input.context.remoteUrl) !== null
+    ) {
+      return input.context.remoteName;
+    }
+
+    if (!input.isCrossRepository) {
+      const remoteName = yield* git
+        .resolvePrimaryRemoteName(input.cwd)
+        .pipe(Effect.catch(() => Effect.succeed(null)));
+      if (remoteName) return remoteName;
+    }
+
+    const cloneUrls = yield* getRepository({
+      cwd: input.cwd,
+      repository: input.sourceRepositoryName,
+      ...(input.context ? { context: input.context } : {}),
+    }).pipe(Effect.map(normalizeRepositoryCloneUrls));
+    const originRemoteUrl = yield* readConfigValueNullable(input.cwd, "remote.origin.url");
+    return yield* git.ensureRemote({
+      cwd: input.cwd,
+      preferredName: input.isCrossRepository
+        ? repositoryOwnerName(input.sourceRepositoryName)
+        : input.destinationRepository.workspace,
+      url: selectCloneUrl({ cloneUrls, originRemoteUrl }),
+    });
+  });
+
+  return BitbucketApi.of({
+    probeAuth: executeJson(
+      "probeAuth",
+      HttpClientRequest.get(apiUrl("/user")),
+      BitbucketUserSchema,
+    ).pipe(
+      Effect.map((user) => ({
+        status: "authenticated" as const,
+        account: nonEmpty(user.username ?? user.display_name ?? user.account_id),
+        host: Option.some("bitbucket.org"),
+        detail: Option.none<string>(),
+      })),
+      Effect.catch(() => Effect.succeed(authFromConfig(config))),
+    ),
+    listPullRequests: (input) =>
+      resolveRepository(input).pipe(
+        Effect.flatMap((repository) => {
+          const states = toBitbucketStates(input.state);
+          const query: Record<string, string | ReadonlyArray<string>> = {
+            pagelen: String(Math.max(1, Math.min(input.limit ?? 20, 50))),
+            sort: "-updated_on",
+            q: bitbucketQueryString([
+              `source.branch.name = "${SourceControlProvider.sourceBranch(input).replaceAll('"', '\\"')}"`,
+              bitbucketStateFilter(states),
+            ]),
+            state: states,
+          };
+
+          return executeJson(
+            "listPullRequests",
+            HttpClientRequest.get(
+              apiUrl(
+                `/repositories/${encodeURIComponent(repository.workspace)}/${encodeURIComponent(repository.repoSlug)}/pullrequests`,
+              ),
+              { urlParams: query },
+            ),
+            BitbucketPullRequests.BitbucketPullRequestListSchema,
+          );
+        }),
+        Effect.map((list) =>
+          list.values.map(BitbucketPullRequests.normalizeBitbucketPullRequestRecord),
+        ),
+      ),
+    getPullRequest: (input) =>
+      getRawPullRequest(input).pipe(
+        Effect.map(BitbucketPullRequests.normalizeBitbucketPullRequestRecord),
+      ),
+    getRepositoryCloneUrls: (input) =>
+      getRepository(input).pipe(Effect.map(normalizeRepositoryCloneUrls)),
+    createRepository: (input) =>
+      requireRepositoryLocator("createRepository", input.repository).pipe(
+        Effect.flatMap((repository) =>
+          executeJson(
+            "createRepository",
+            HttpClientRequest.post(
+              apiUrl(
+                `/repositories/${encodeURIComponent(repository.workspace)}/${encodeURIComponent(repository.repoSlug)}`,
+              ),
+            ).pipe(
+              HttpClientRequest.bodyJsonUnsafe({
+                scm: "git",
+                is_private: input.visibility === "private",
+              }),
+            ),
+            RawBitbucketRepositorySchema,
+          ),
+        ),
+        Effect.map(normalizeRepositoryCloneUrls),
+      ),
+    createPullRequest: (input) =>
+      Effect.gen(function* () {
+        const repository = yield* resolveRepository(input);
+        const description = yield* fileSystem.readFileString(input.bodyFile).pipe(
+          Effect.mapError(
+            (cause) =>
+              new BitbucketApiError({
+                operation: "createPullRequest",
+                detail: `Failed to read pull request body file ${input.bodyFile}.`,
+                cause,
+              }),
+          ),
+        );
+        const sourceOwner = sourceWorkspace(input);
+        const body = {
+          title: input.title,
+          description,
+          source: {
+            branch: {
+              name: SourceControlProvider.sourceBranch(input),
+            },
+            ...(sourceOwner
+              ? {
+                  repository: {
+                    full_name: `${sourceOwner}/${input.source?.repository ?? repository.repoSlug}`,
+                  },
+                }
+              : {}),
+          },
+          destination: {
+            branch: {
+              name: input.target?.refName ?? input.baseBranch,
+            },
+          },
+        };
+
+        yield* executeJson(
+          "createPullRequest",
+          HttpClientRequest.post(
+            apiUrl(
+              `/repositories/${encodeURIComponent(repository.workspace)}/${encodeURIComponent(repository.repoSlug)}/pullrequests`,
+            ),
+          ).pipe(HttpClientRequest.bodyJsonUnsafe(body)),
+          BitbucketPullRequests.BitbucketPullRequestSchema,
+        );
+      }),
+    getDefaultBranch: (input) =>
+      resolveRepository(input).pipe(
+        Effect.flatMap((locator) =>
+          Effect.all(
+            {
+              repository: getRepositoryFromLocator(locator),
+              branchingModel: getBranchingModelFromLocator(locator).pipe(
+                Effect.catch(() =>
+                  Effect.succeed<typeof RawBitbucketBranchingModelSchema.Type | null>(null),
+                ),
+              ),
+            },
+            { concurrency: "unbounded" },
+          ),
+        ),
+        Effect.map(defaultChangeRequestTargetBranch),
+      ),
+    // Bitbucket Cloud pull requests are Git-backed and Bitbucket does not provide
+    // an official checkout CLI. This provider-local path uses GitVcsDriver as a
+    // narrow escape hatch to materialize Bitbucket PR refs. Do not generalize this
+    // as the source-control provider model: if we support non-Git-compatible
+    // hosting providers or native JJ/Sapling checkout flows, move this into a
+    // VCS-specific change-request checkout capability.
+    checkoutPullRequest: (input) =>
+      Effect.gen(function* () {
+        const destinationRepository = yield* resolveRepository(input);
+        const pullRequest = yield* getRawPullRequestFromRepository(
+          destinationRepository,
+          input.reference,
+        );
+        const destinationRepositoryName =
+          repositoryNameWithOwner(pullRequest.destination.repository) ??
+          `${destinationRepository.workspace}/${destinationRepository.repoSlug}`;
+        const sourceRepositoryName =
+          repositoryNameWithOwner(pullRequest.source.repository) ?? destinationRepositoryName;
+        const isCrossRepository = sourceRepositoryName !== destinationRepositoryName;
+        const remoteName = yield* resolveCheckoutRemote({
+          cwd: input.cwd,
+          destinationRepository,
+          sourceRepositoryName,
+          isCrossRepository,
+          ...(input.context ? { context: input.context } : {}),
+        });
+        const remoteBranch = pullRequest.source.branch.name;
+        const localBranch = checkoutBranchName({
+          pullRequestId: pullRequest.id,
+          headBranch: remoteBranch,
+          isCrossRepository,
+        });
+        const localBranchNames = yield* git.listLocalBranchNames(input.cwd);
+        const localBranchExists = localBranchNames.includes(localBranch);
+
+        if (input.force === true || !localBranchExists) {
+          yield* git.fetchRemoteBranch({
+            cwd: input.cwd,
+            remoteName,
+            remoteBranch,
+            localBranch,
+          });
+        } else {
+          yield* git.fetchRemoteTrackingBranch({
+            cwd: input.cwd,
+            remoteName,
+            remoteBranch,
+          });
+        }
+
+        yield* git.setBranchUpstream({
+          cwd: input.cwd,
+          branch: localBranch,
+          remoteName,
+          remoteBranch,
+        });
+        yield* Effect.scoped(git.switchRef({ cwd: input.cwd, refName: localBranch }));
+      }).pipe(
+        Effect.mapError((cause) =>
+          isBitbucketApiError(cause)
+            ? cause
+            : new BitbucketApiError({
+                operation: "checkoutPullRequest",
+                detail: cause instanceof Error ? cause.message : String(cause),
+                cause,
+              }),
+        ),
+      ),
+  });
+});
+
+export const layer = Layer.effect(BitbucketApi, make());
diff --git a/apps/server/src/sourceControl/BitbucketSourceControlProvider.test.ts b/apps/server/src/sourceControl/BitbucketSourceControlProvider.test.ts
new file mode 100644
index 00000000000..07a3d386a35
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketSourceControlProvider.test.ts
@@ -0,0 +1,128 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as BitbucketApi from "./BitbucketApi.ts";
+import * as BitbucketSourceControlProvider from "./BitbucketSourceControlProvider.ts";
+
+function makeProvider(bitbucket: Partial<BitbucketApi.BitbucketApiShape>) {
+  return BitbucketSourceControlProvider.make().pipe(
+    Effect.provide(Layer.mock(BitbucketApi.BitbucketApi)(bitbucket)),
+  );
+}
+
+it.effect("maps Bitbucket PR summaries into provider-neutral change requests", () =>
+  Effect.gen(function* () {
+    const provider = yield* makeProvider({
+      getPullRequest: () =>
+        Effect.succeed({
+          number: 42,
+          title: "Add Bitbucket provider",
+          url: "https://bitbucket.org/pingdotgg/t3code/pull-requests/42",
+          baseRefName: "main",
+          headRefName: "feature/source-control",
+          state: "open",
+          updatedAt: Option.none(),
+          isCrossRepository: true,
+          headRepositoryNameWithOwner: "fork/t3code",
+          headRepositoryOwnerLogin: "fork",
+        }),
+    });
+
+    const changeRequest = yield* provider.getChangeRequest({
+      cwd: "/repo",
+      reference: "42",
+    });
+
+    assert.deepStrictEqual(changeRequest, {
+      provider: "bitbucket",
+      number: 42,
+      title: "Add Bitbucket provider",
+      url: "https://bitbucket.org/pingdotgg/t3code/pull-requests/42",
+      baseRefName: "main",
+      headRefName: "feature/source-control",
+      state: "open",
+      updatedAt: Option.none(),
+      isCrossRepository: true,
+      headRepositoryNameWithOwner: "fork/t3code",
+      headRepositoryOwnerLogin: "fork",
+    });
+  }),
+);
+
+it.effect("lists Bitbucket PRs through provider-neutral input names", () =>
+  Effect.gen(function* () {
+    let listInput: Parameters<BitbucketApi.BitbucketApiShape["listPullRequests"]>[0] | null = null;
+    const provider = yield* makeProvider({
+      listPullRequests: (input) => {
+        listInput = input;
+        return Effect.succeed([]);
+      },
+    });
+
+    yield* provider.listChangeRequests({
+      cwd: "/repo",
+      headSelector: "feature/provider",
+      state: "all",
+      limit: 10,
+    });
+
+    assert.deepStrictEqual(listInput, {
+      cwd: "/repo",
+      headSelector: "feature/provider",
+      state: "all",
+      limit: 10,
+    });
+  }),
+);
+
+it.effect("creates Bitbucket PRs through provider-neutral input names", () =>
+  Effect.gen(function* () {
+    let createInput: Parameters<BitbucketApi.BitbucketApiShape["createPullRequest"]>[0] | null =
+      null;
+    const provider = yield* makeProvider({
+      createPullRequest: (input) => {
+        createInput = input;
+        return Effect.void;
+      },
+    });
+
+    yield* provider.createChangeRequest({
+      cwd: "/repo",
+      baseRefName: "main",
+      headSelector: "owner:feature/provider",
+      title: "Provider PR",
+      bodyFile: "/tmp/body.md",
+    });
+
+    assert.deepStrictEqual(createInput, {
+      cwd: "/repo",
+      baseBranch: "main",
+      headSelector: "owner:feature/provider",
+      source: {
+        owner: "owner",
+        refName: "feature/provider",
+      },
+      title: "Provider PR",
+      bodyFile: "/tmp/body.md",
+    });
+  }),
+);
+
+it.effect("uses Bitbucket API repository detection for default branch lookup", () =>
+  Effect.gen(function* () {
+    let cwdInput: string | null = null;
+    const provider = yield* makeProvider({
+      getDefaultBranch: (input) => {
+        cwdInput = input.cwd;
+        return Effect.succeed("main");
+      },
+    });
+
+    const defaultBranch = yield* provider.getDefaultBranch({ cwd: "/repo" });
+
+    assert.strictEqual(defaultBranch, "main");
+    assert.strictEqual(cwdInput, "/repo");
+  }),
+);
diff --git a/apps/server/src/sourceControl/BitbucketSourceControlProvider.ts b/apps/server/src/sourceControl/BitbucketSourceControlProvider.ts
new file mode 100644
index 00000000000..f3fd502f7fb
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketSourceControlProvider.ts
@@ -0,0 +1,128 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { SourceControlProviderError, type ChangeRequest } from "@t3tools/contracts";
+
+import * as BitbucketApi from "./BitbucketApi.ts";
+import * as BitbucketPullRequests from "./bitbucketPullRequests.ts";
+import * as SourceControlProvider from "./SourceControlProvider.ts";
+import type * as SourceControlProviderDiscovery from "./SourceControlProviderDiscovery.ts";
+
+function providerError(
+  operation: string,
+  cause: BitbucketApi.BitbucketApiError,
+): SourceControlProviderError {
+  return new SourceControlProviderError({
+    provider: "bitbucket",
+    operation,
+    detail: cause.detail,
+    cause,
+  });
+}
+
+function toChangeRequest(
+  summary: BitbucketPullRequests.NormalizedBitbucketPullRequestRecord,
+): ChangeRequest {
+  return {
+    provider: "bitbucket",
+    number: summary.number,
+    title: summary.title,
+    url: summary.url,
+    baseRefName: summary.baseRefName,
+    headRefName: summary.headRefName,
+    state: summary.state,
+    updatedAt: summary.updatedAt ?? Option.none(),
+    ...(summary.isCrossRepository !== undefined
+      ? { isCrossRepository: summary.isCrossRepository }
+      : {}),
+    ...(summary.headRepositoryNameWithOwner !== undefined
+      ? { headRepositoryNameWithOwner: summary.headRepositoryNameWithOwner }
+      : {}),
+    ...(summary.headRepositoryOwnerLogin !== undefined
+      ? { headRepositoryOwnerLogin: summary.headRepositoryOwnerLogin }
+      : {}),
+  };
+}
+
+export const make = Effect.fn("makeBitbucketSourceControlProvider")(function* () {
+  const bitbucket = yield* BitbucketApi.BitbucketApi;
+
+  return SourceControlProvider.SourceControlProvider.of({
+    kind: "bitbucket",
+    listChangeRequests: (input) => {
+      const source = SourceControlProvider.sourceControlRefFromInput(input);
+      return bitbucket
+        .listPullRequests({
+          cwd: input.cwd,
+          ...(input.context ? { context: input.context } : {}),
+          headSelector: input.headSelector,
+          ...(source ? { source } : {}),
+          state: input.state,
+          ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        })
+        .pipe(
+          Effect.map((items) => items.map(toChangeRequest)),
+          Effect.mapError((error) => providerError("listChangeRequests", error)),
+        );
+    },
+    getChangeRequest: (input) =>
+      bitbucket.getPullRequest(input).pipe(
+        Effect.map(toChangeRequest),
+        Effect.mapError((error) => providerError("getChangeRequest", error)),
+      ),
+    createChangeRequest: (input) => {
+      const source = SourceControlProvider.sourceControlRefFromInput(input);
+      return bitbucket
+        .createPullRequest({
+          cwd: input.cwd,
+          ...(input.context ? { context: input.context } : {}),
+          baseBranch: input.baseRefName,
+          headSelector: input.headSelector,
+          ...(source ? { source } : {}),
+          ...(input.target ? { target: input.target } : {}),
+          title: input.title,
+          bodyFile: input.bodyFile,
+        })
+        .pipe(Effect.mapError((error) => providerError("createChangeRequest", error)));
+    },
+    getRepositoryCloneUrls: (input) =>
+      bitbucket
+        .getRepositoryCloneUrls(input)
+        .pipe(Effect.mapError((error) => providerError("getRepositoryCloneUrls", error))),
+    createRepository: (input) =>
+      bitbucket
+        .createRepository(input)
+        .pipe(Effect.mapError((error) => providerError("createRepository", error))),
+    getDefaultBranch: (input) =>
+      bitbucket
+        .getDefaultBranch({
+          cwd: input.cwd,
+          ...(input.context ? { context: input.context } : {}),
+        })
+        .pipe(Effect.mapError((error) => providerError("getDefaultBranch", error))),
+    checkoutChangeRequest: (input) =>
+      bitbucket
+        .checkoutPullRequest({
+          cwd: input.cwd,
+          ...(input.context ? { context: input.context } : {}),
+          reference: input.reference,
+          ...(input.force !== undefined ? { force: input.force } : {}),
+        })
+        .pipe(Effect.mapError((error) => providerError("checkoutChangeRequest", error))),
+  });
+});
+
+export const layer = Layer.effect(SourceControlProvider.SourceControlProvider, make());
+
+export const makeDiscovery = Effect.fn("makeBitbucketSourceControlProviderDiscovery")(function* () {
+  const bitbucket = yield* BitbucketApi.BitbucketApi;
+
+  return {
+    type: "api",
+    kind: "bitbucket",
+    label: "Bitbucket",
+    installHint:
+      "Set T3CODE_BITBUCKET_EMAIL and T3CODE_BITBUCKET_API_TOKEN on the server (use a Bitbucket API token with pull request and repository scopes).",
+    probeAuth: bitbucket.probeAuth,
+  } satisfies SourceControlProviderDiscovery.SourceControlApiDiscoverySpec;
+});
diff --git a/apps/server/src/sourceControl/GitHubCli.test.ts b/apps/server/src/sourceControl/GitHubCli.test.ts
new file mode 100644
index 00000000000..fb765b352c2
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubCli.test.ts
@@ -0,0 +1,296 @@
+import { assert, it, afterEach, describe, expect, vi } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { VcsProcessExitError } from "@t3tools/contracts";
+
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as GitHubCli from "./GitHubCli.ts";
+
+const processOutput = (stdout: string): VcsProcess.VcsProcessOutput => ({
+  exitCode: ChildProcessSpawner.ExitCode(0),
+  stdout,
+  stderr: "",
+  stdoutTruncated: false,
+  stderrTruncated: false,
+});
+
+const mockRun = vi.fn<VcsProcess.VcsProcessShape["run"]>();
+
+const layer = GitHubCli.layer.pipe(
+  Layer.provide(
+    Layer.mock(VcsProcess.VcsProcess)({
+      run: mockRun,
+    }),
+  ),
+);
+
+afterEach(() => {
+  mockRun.mockReset();
+});
+
+describe("GitHubCli.layer", () => {
+  it.effect("parses pull request view output", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              number: 42,
+              title: "Add PR thread creation",
+              url: "https://github.com/pingdotgg/codething-mvp/pull/42",
+              baseRefName: "main",
+              headRefName: "feature/pr-threads",
+              state: "OPEN",
+              mergedAt: null,
+              isCrossRepository: true,
+              headRepository: {
+                nameWithOwner: "octocat/codething-mvp",
+              },
+              headRepositoryOwner: {
+                login: "octocat",
+              },
+            }),
+          ),
+        ),
+      );
+
+      const gh = yield* GitHubCli.GitHubCli;
+      const result = yield* gh.getPullRequest({
+        cwd: "/repo",
+        reference: "#42",
+      });
+
+      assert.deepStrictEqual(result, {
+        number: 42,
+        title: "Add PR thread creation",
+        url: "https://github.com/pingdotgg/codething-mvp/pull/42",
+        baseRefName: "main",
+        headRefName: "feature/pr-threads",
+        state: "open",
+        isCrossRepository: true,
+        headRepositoryNameWithOwner: "octocat/codething-mvp",
+        headRepositoryOwnerLogin: "octocat",
+      });
+      expect(mockRun).toHaveBeenCalledWith({
+        operation: "GitHubCli.execute",
+        command: "gh",
+        args: [
+          "pr",
+          "view",
+          "#42",
+          "--json",
+          "number,title,url,baseRefName,headRefName,state,mergedAt,isCrossRepository,headRepository,headRepositoryOwner",
+        ],
+        cwd: "/repo",
+        timeoutMs: 30_000,
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("trims pull request fields decoded from gh json", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              number: 42,
+              title: "  Add PR thread creation  \n",
+              url: " https://github.com/pingdotgg/codething-mvp/pull/42 ",
+              baseRefName: " main ",
+              headRefName: "\tfeature/pr-threads\t",
+              state: "OPEN",
+              mergedAt: null,
+              isCrossRepository: true,
+              headRepository: {
+                nameWithOwner: " octocat/codething-mvp ",
+              },
+              headRepositoryOwner: {
+                login: " octocat ",
+              },
+            }),
+          ),
+        ),
+      );
+
+      const gh = yield* GitHubCli.GitHubCli;
+      const result = yield* gh.getPullRequest({
+        cwd: "/repo",
+        reference: "#42",
+      });
+
+      assert.deepStrictEqual(result, {
+        number: 42,
+        title: "Add PR thread creation",
+        url: "https://github.com/pingdotgg/codething-mvp/pull/42",
+        baseRefName: "main",
+        headRefName: "feature/pr-threads",
+        state: "open",
+        isCrossRepository: true,
+        headRepositoryNameWithOwner: "octocat/codething-mvp",
+        headRepositoryOwnerLogin: "octocat",
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("skips invalid entries when parsing pr lists", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify([
+              {
+                number: 0,
+                title: "invalid",
+                url: "https://github.com/pingdotgg/codething-mvp/pull/0",
+                baseRefName: "main",
+                headRefName: "feature/invalid",
+              },
+              {
+                number: 43,
+                title: "  Valid PR  ",
+                url: " https://github.com/pingdotgg/codething-mvp/pull/43 ",
+                baseRefName: " main ",
+                headRefName: " feature/pr-list ",
+                headRepository: {
+                  nameWithOwner: "   ",
+                },
+                headRepositoryOwner: {
+                  login: "   ",
+                },
+              },
+            ]),
+          ),
+        ),
+      );
+
+      const gh = yield* GitHubCli.GitHubCli;
+      const result = yield* gh.listOpenPullRequests({
+        cwd: "/repo",
+        headSelector: "feature/pr-list",
+      });
+
+      assert.deepStrictEqual(result, [
+        {
+          number: 43,
+          title: "Valid PR",
+          url: "https://github.com/pingdotgg/codething-mvp/pull/43",
+          baseRefName: "main",
+          headRefName: "feature/pr-list",
+          state: "open",
+        },
+      ]);
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("reads repository clone URLs", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              nameWithOwner: "octocat/codething-mvp",
+              url: "https://github.com/octocat/codething-mvp",
+              sshUrl: "git@github.com:octocat/codething-mvp.git",
+            }),
+          ),
+        ),
+      );
+
+      const gh = yield* GitHubCli.GitHubCli;
+      const result = yield* gh.getRepositoryCloneUrls({
+        cwd: "/repo",
+        repository: "octocat/codething-mvp",
+      });
+
+      assert.deepStrictEqual(result, {
+        nameWithOwner: "octocat/codething-mvp",
+        url: "https://github.com/octocat/codething-mvp",
+        sshUrl: "git@github.com:octocat/codething-mvp.git",
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("creates repositories and parses clone URLs from create output", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            "✓ Created repository octocat/codething-mvp on github.com\nhttps://github.com/octocat/codething-mvp\n",
+          ),
+        ),
+      );
+
+      const gh = yield* GitHubCli.GitHubCli;
+      const result = yield* gh.createRepository({
+        cwd: "/repo",
+        repository: "octocat/codething-mvp",
+        visibility: "private",
+      });
+
+      assert.deepStrictEqual(result, {
+        nameWithOwner: "octocat/codething-mvp",
+        url: "https://github.com/octocat/codething-mvp",
+        sshUrl: "git@github.com:octocat/codething-mvp.git",
+      });
+      expect(mockRun).toHaveBeenCalledTimes(1);
+      expect(mockRun).toHaveBeenNthCalledWith(1, {
+        operation: "GitHubCli.execute",
+        command: "gh",
+        args: ["repo", "create", "octocat/codething-mvp", "--private"],
+        cwd: "/repo",
+        timeoutMs: 30_000,
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("falls back to constructed URLs when create output omits a URL", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(Effect.succeed(processOutput("")));
+
+      const gh = yield* GitHubCli.GitHubCli;
+      const result = yield* gh.createRepository({
+        cwd: "/repo",
+        repository: "octocat/codething-mvp",
+        visibility: "private",
+      });
+
+      assert.deepStrictEqual(result, {
+        nameWithOwner: "octocat/codething-mvp",
+        url: "https://github.com/octocat/codething-mvp",
+        sshUrl: "git@github.com:octocat/codething-mvp.git",
+      });
+    }).pipe(Effect.provide(layer)),
+  );
+
+  it.effect("surfaces a friendly error when the pull request is not found", () =>
+    Effect.gen(function* () {
+      mockRun.mockReturnValueOnce(
+        Effect.fail(
+          new VcsProcessExitError({
+            operation: "GitHubCli.execute",
+            command: "gh pr view",
+            cwd: "/repo",
+            exitCode: 1,
+            detail:
+              "GraphQL: Could not resolve to a PullRequest with the number of 4888. (repository.pullRequest)",
+          }),
+        ),
+      );
+
+      const gh = yield* GitHubCli.GitHubCli;
+      const error = yield* gh
+        .getPullRequest({
+          cwd: "/repo",
+          reference: "4888",
+        })
+        .pipe(Effect.flip);
+
+      assert.equal(error.message.includes("Pull request not found"), true);
+    }).pipe(Effect.provide(layer)),
+  );
+});
diff --git a/apps/server/src/sourceControl/GitHubCli.ts b/apps/server/src/sourceControl/GitHubCli.ts
new file mode 100644
index 00000000000..14d01aab2ed
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubCli.ts
@@ -0,0 +1,375 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+
+import {
+  TrimmedNonEmptyString,
+  type SourceControlRepositoryVisibility,
+  type VcsError,
+} from "@t3tools/contracts";
+
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as GitHubPullRequests from "./gitHubPullRequests.ts";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class GitHubCliError extends Schema.TaggedErrorClass<GitHubCliError>()("GitHubCliError", {
+  operation: Schema.String,
+  detail: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {
+  override get message(): string {
+    return `GitHub CLI failed in ${this.operation}: ${this.detail}`;
+  }
+}
+
+export interface GitHubPullRequestSummary {
+  readonly number: number;
+  readonly title: string;
+  readonly url: string;
+  readonly baseRefName: string;
+  readonly headRefName: string;
+  readonly state?: "open" | "closed" | "merged";
+  readonly isCrossRepository?: boolean;
+  readonly headRepositoryNameWithOwner?: string | null;
+  readonly headRepositoryOwnerLogin?: string | null;
+}
+
+export interface GitHubRepositoryCloneUrls {
+  readonly nameWithOwner: string;
+  readonly url: string;
+  readonly sshUrl: string;
+}
+
+export interface GitHubCliShape {
+  readonly execute: (input: {
+    readonly cwd: string;
+    readonly args: ReadonlyArray<string>;
+    readonly timeoutMs?: number;
+  }) => Effect.Effect<VcsProcess.VcsProcessOutput, GitHubCliError>;
+
+  readonly listOpenPullRequests: (input: {
+    readonly cwd: string;
+    readonly headSelector: string;
+    readonly limit?: number;
+  }) => Effect.Effect<ReadonlyArray<GitHubPullRequestSummary>, GitHubCliError>;
+
+  readonly getPullRequest: (input: {
+    readonly cwd: string;
+    readonly reference: string;
+  }) => Effect.Effect<GitHubPullRequestSummary, GitHubCliError>;
+
+  readonly getRepositoryCloneUrls: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+  }) => Effect.Effect<GitHubRepositoryCloneUrls, GitHubCliError>;
+
+  readonly createRepository: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+    readonly visibility: SourceControlRepositoryVisibility;
+  }) => Effect.Effect<GitHubRepositoryCloneUrls, GitHubCliError>;
+
+  readonly createPullRequest: (input: {
+    readonly cwd: string;
+    readonly baseBranch: string;
+    readonly headSelector: string;
+    readonly title: string;
+    readonly bodyFile: string;
+  }) => Effect.Effect<void, GitHubCliError>;
+
+  readonly getDefaultBranch: (input: {
+    readonly cwd: string;
+  }) => Effect.Effect<string | null, GitHubCliError>;
+
+  readonly checkoutPullRequest: (input: {
+    readonly cwd: string;
+    readonly reference: string;
+    readonly force?: boolean;
+  }) => Effect.Effect<void, GitHubCliError>;
+}
+
+export class GitHubCli extends Context.Service<GitHubCli, GitHubCliShape>()(
+  "t3/source-control/GitHubCli",
+) {}
+
+function errorText(error: VcsError | unknown): string {
+  if (typeof error === "object" && error !== null) {
+    const tag = "_tag" in error && typeof error._tag === "string" ? error._tag : "";
+    const detail = "detail" in error && typeof error.detail === "string" ? error.detail : "";
+    const message = "message" in error && typeof error.message === "string" ? error.message : "";
+    return [tag, detail, message].filter(Boolean).join("\n");
+  }
+
+  return String(error);
+}
+
+function normalizeGitHubCliError(
+  operation: "execute" | "stdout",
+  error: VcsError | unknown,
+): GitHubCliError {
+  const text = errorText(error);
+  const lower = text.toLowerCase();
+
+  if (lower.includes("command not found: gh") || lower.includes("enoent")) {
+    return new GitHubCliError({
+      operation,
+      detail: "GitHub CLI (`gh`) is required but not available on PATH.",
+      cause: error,
+    });
+  }
+
+  if (
+    lower.includes("authentication failed") ||
+    lower.includes("not logged in") ||
+    lower.includes("gh auth login") ||
+    lower.includes("no oauth token")
+  ) {
+    return new GitHubCliError({
+      operation,
+      detail: "GitHub CLI is not authenticated. Run `gh auth login` and retry.",
+      cause: error,
+    });
+  }
+
+  if (
+    lower.includes("could not resolve to a pullrequest") ||
+    lower.includes("repository.pullrequest") ||
+    lower.includes("no pull requests found for branch") ||
+    lower.includes("pull request not found")
+  ) {
+    return new GitHubCliError({
+      operation,
+      detail: "Pull request not found. Check the PR number or URL and try again.",
+      cause: error,
+    });
+  }
+
+  return new GitHubCliError({
+    operation,
+    detail: text,
+    cause: error,
+  });
+}
+
+const RawGitHubRepositoryCloneUrlsSchema = Schema.Struct({
+  nameWithOwner: TrimmedNonEmptyString,
+  url: TrimmedNonEmptyString,
+  sshUrl: TrimmedNonEmptyString,
+});
+
+function normalizeRepositoryCloneUrls(
+  raw: Schema.Schema.Type<typeof RawGitHubRepositoryCloneUrlsSchema>,
+): GitHubRepositoryCloneUrls {
+  return {
+    nameWithOwner: raw.nameWithOwner,
+    url: raw.url,
+    sshUrl: raw.sshUrl,
+  };
+}
+
+/**
+ * `gh repo create` prints the canonical URL of the new repository on stdout
+ * (e.g. `https://github.com/owner/repo`). Reading it back here avoids a
+ * follow-up `gh repo view`, which can race GitHub's GraphQL eventual
+ * consistency window and falsely report the just-created repo as missing.
+ */
+function deriveRepositoryCloneUrlsFromCreateOutput(
+  stdout: string,
+  repository: string,
+): GitHubRepositoryCloneUrls {
+  const fallbackHost = "github.com";
+  const match = stdout.match(/https?:\/\/[^\s]+/);
+  if (match) {
+    const cleaned = match[0].replace(/\.git$/, "");
+    try {
+      const parsed = new URL(cleaned);
+      const pathname = parsed.pathname.replace(/^\/+|\/+$/g, "");
+      const segments = pathname.split("/").filter(Boolean);
+      if (segments.length === 2) {
+        const nameWithOwner = `${segments[0]}/${segments[1]}`;
+        return {
+          nameWithOwner,
+          url: `${parsed.origin}/${nameWithOwner}`,
+          sshUrl: `git@${parsed.host}:${nameWithOwner}.git`,
+        };
+      }
+    } catch {
+      // Fall through to the input-derived defaults below.
+    }
+  }
+  return {
+    nameWithOwner: repository,
+    url: `https://${fallbackHost}/${repository}`,
+    sshUrl: `git@${fallbackHost}:${repository}.git`,
+  };
+}
+
+function decodeGitHubJson<S extends Schema.Top>(
+  raw: string,
+  schema: S,
+  operation: "listOpenPullRequests" | "getPullRequest" | "getRepositoryCloneUrls",
+  invalidDetail: string,
+): Effect.Effect<S["Type"], GitHubCliError, S["DecodingServices"]> {
+  return Schema.decodeEffect(Schema.fromJsonString(schema))(raw).pipe(
+    Effect.mapError(
+      (error) =>
+        new GitHubCliError({
+          operation,
+          detail: `${invalidDetail}: ${SchemaIssue.makeFormatterDefault()(error.issue)}`,
+          cause: error,
+        }),
+    ),
+  );
+}
+
+export const make = Effect.fn("makeGitHubCli")(function* () {
+  const process = yield* VcsProcess.VcsProcess;
+
+  const execute: GitHubCliShape["execute"] = (input) =>
+    process
+      .run({
+        operation: "GitHubCli.execute",
+        command: "gh",
+        args: input.args,
+        cwd: input.cwd,
+        timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      })
+      .pipe(Effect.mapError((error) => normalizeGitHubCliError("execute", error)));
+
+  return GitHubCli.of({
+    execute,
+    listOpenPullRequests: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: [
+          "pr",
+          "list",
+          "--head",
+          input.headSelector,
+          "--state",
+          "open",
+          "--limit",
+          String(input.limit ?? 1),
+          "--json",
+          "number,title,url,baseRefName,headRefName,state,mergedAt,isCrossRepository,headRepository,headRepositoryOwner",
+        ],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          raw.length === 0
+            ? Effect.succeed([])
+            : Effect.sync(() => GitHubPullRequests.decodeGitHubPullRequestListJson(raw)).pipe(
+                Effect.flatMap((decoded) => {
+                  if (!Result.isSuccess(decoded)) {
+                    return Effect.fail(
+                      new GitHubCliError({
+                        operation: "listOpenPullRequests",
+                        detail: `GitHub CLI returned invalid PR list JSON: ${GitHubPullRequests.formatGitHubJsonDecodeError(decoded.failure)}`,
+                        cause: decoded.failure,
+                      }),
+                    );
+                  }
+
+                  return Effect.succeed(
+                    decoded.success.map(({ updatedAt: _updatedAt, ...summary }) => summary),
+                  );
+                }),
+              ),
+        ),
+      ),
+    getPullRequest: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: [
+          "pr",
+          "view",
+          input.reference,
+          "--json",
+          "number,title,url,baseRefName,headRefName,state,mergedAt,isCrossRepository,headRepository,headRepositoryOwner",
+        ],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          Effect.sync(() => GitHubPullRequests.decodeGitHubPullRequestJson(raw)).pipe(
+            Effect.flatMap((decoded) => {
+              if (!Result.isSuccess(decoded)) {
+                return Effect.fail(
+                  new GitHubCliError({
+                    operation: "getPullRequest",
+                    detail: `GitHub CLI returned invalid pull request JSON: ${GitHubPullRequests.formatGitHubJsonDecodeError(decoded.failure)}`,
+                    cause: decoded.failure,
+                  }),
+                );
+              }
+
+              return Effect.succeed(
+                (({ updatedAt: _updatedAt, ...summary }) => summary)(decoded.success),
+              );
+            }),
+          ),
+        ),
+      ),
+    getRepositoryCloneUrls: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["repo", "view", input.repository, "--json", "nameWithOwner,url,sshUrl"],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          decodeGitHubJson(
+            raw,
+            RawGitHubRepositoryCloneUrlsSchema,
+            "getRepositoryCloneUrls",
+            "GitHub CLI returned invalid repository JSON.",
+          ),
+        ),
+        Effect.map(normalizeRepositoryCloneUrls),
+      ),
+    createRepository: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["repo", "create", input.repository, `--${input.visibility}`],
+      }).pipe(
+        Effect.map((result) =>
+          deriveRepositoryCloneUrlsFromCreateOutput(result.stdout, input.repository),
+        ),
+      ),
+    createPullRequest: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: [
+          "pr",
+          "create",
+          "--base",
+          input.baseBranch,
+          "--head",
+          input.headSelector,
+          "--title",
+          input.title,
+          "--body-file",
+          input.bodyFile,
+        ],
+      }).pipe(Effect.asVoid),
+    getDefaultBranch: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["repo", "view", "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"],
+      }).pipe(
+        Effect.map((value) => {
+          const trimmed = value.stdout.trim();
+          return trimmed.length > 0 ? trimmed : null;
+        }),
+      ),
+    checkoutPullRequest: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["pr", "checkout", input.reference, ...(input.force ? ["--force"] : [])],
+      }).pipe(Effect.asVoid),
+  });
+});
+
+export const layer = Layer.effect(GitHubCli, make());
diff --git a/apps/server/src/sourceControl/GitHubSourceControlProvider.test.ts b/apps/server/src/sourceControl/GitHubSourceControlProvider.test.ts
new file mode 100644
index 00000000000..a480f3bec86
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubSourceControlProvider.test.ts
@@ -0,0 +1,159 @@
+import { assert, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as GitHubCli from "./GitHubCli.ts";
+import * as GitHubSourceControlProvider from "./GitHubSourceControlProvider.ts";
+
+const processResult = (stdout: string): VcsProcess.VcsProcessOutput => ({
+  exitCode: ChildProcessSpawner.ExitCode(0),
+  stdout,
+  stderr: "",
+  stdoutTruncated: false,
+  stderrTruncated: false,
+});
+
+function makeProvider(github: Partial<GitHubCli.GitHubCliShape>) {
+  return GitHubSourceControlProvider.make().pipe(
+    Effect.provide(Layer.mock(GitHubCli.GitHubCli)(github)),
+  );
+}
+
+it.effect("maps GitHub PR summaries into provider-neutral change requests", () =>
+  Effect.gen(function* () {
+    const provider = yield* makeProvider({
+      getPullRequest: () =>
+        Effect.succeed({
+          number: 42,
+          title: "Add GitHub provider",
+          url: "https://github.com/pingdotgg/t3code/pull/42",
+          baseRefName: "main",
+          headRefName: "feature/source-control",
+          state: "open",
+          isCrossRepository: true,
+          headRepositoryNameWithOwner: "fork/t3code",
+          headRepositoryOwnerLogin: "fork",
+        }),
+    });
+
+    const changeRequest = yield* provider.getChangeRequest({
+      cwd: "/repo",
+      reference: "42",
+    });
+
+    assert.deepStrictEqual(changeRequest, {
+      provider: "github",
+      number: 42,
+      title: "Add GitHub provider",
+      url: "https://github.com/pingdotgg/t3code/pull/42",
+      baseRefName: "main",
+      headRefName: "feature/source-control",
+      state: "open",
+      updatedAt: Option.none(),
+      isCrossRepository: true,
+      headRepositoryNameWithOwner: "fork/t3code",
+      headRepositoryOwnerLogin: "fork",
+    });
+  }),
+);
+
+it.effect("uses gh json listing for non-open change request state queries", () =>
+  Effect.gen(function* () {
+    let executeArgs: ReadonlyArray<string> = [];
+    const provider = yield* makeProvider({
+      execute: (input) => {
+        executeArgs = input.args;
+        return Effect.succeed(
+          processResult(
+            JSON.stringify([
+              {
+                number: 7,
+                title: "Merged work",
+                url: "https://github.com/pingdotgg/t3code/pull/7",
+                baseRefName: "main",
+                headRefName: "feature/merged",
+                state: "merged",
+                updatedAt: "2026-01-02T00:00:00.000Z",
+              },
+            ]),
+          ),
+        );
+      },
+    });
+
+    const changeRequests = yield* provider.listChangeRequests({
+      cwd: "/repo",
+      headSelector: "feature/merged",
+      state: "all",
+      limit: 10,
+    });
+
+    assert.deepStrictEqual(executeArgs, [
+      "pr",
+      "list",
+      "--head",
+      "feature/merged",
+      "--state",
+      "all",
+      "--limit",
+      "10",
+      "--json",
+      "number,title,url,baseRefName,headRefName,state,mergedAt,updatedAt,isCrossRepository,headRepository,headRepositoryOwner",
+    ]);
+    assert.strictEqual(changeRequests[0]?.provider, "github");
+    assert.strictEqual(changeRequests[0]?.state, "merged");
+    assert.deepStrictEqual(
+      changeRequests[0]?.updatedAt,
+      Option.some(DateTime.makeUnsafe("2026-01-02T00:00:00.000Z")),
+    );
+  }),
+);
+
+it.effect("treats empty non-open change request listing output as no results", () =>
+  Effect.gen(function* () {
+    const provider = yield* makeProvider({
+      execute: () => Effect.succeed(processResult("")),
+    });
+
+    const changeRequests = yield* provider.listChangeRequests({
+      cwd: "/repo",
+      headSelector: "feature/empty",
+      state: "all",
+      limit: 10,
+    });
+
+    assert.deepStrictEqual(changeRequests, []);
+  }),
+);
+
+it.effect("creates GitHub PRs through provider-neutral input names", () =>
+  Effect.gen(function* () {
+    let createInput: Parameters<GitHubCli.GitHubCliShape["createPullRequest"]>[0] | null = null;
+    const provider = yield* makeProvider({
+      createPullRequest: (input) => {
+        createInput = input;
+        return Effect.void;
+      },
+    });
+
+    yield* provider.createChangeRequest({
+      cwd: "/repo",
+      baseRefName: "main",
+      headSelector: "owner:feature/provider",
+      title: "Provider PR",
+      bodyFile: "/tmp/body.md",
+    });
+
+    assert.deepStrictEqual(createInput, {
+      cwd: "/repo",
+      baseBranch: "main",
+      headSelector: "owner:feature/provider",
+      title: "Provider PR",
+      bodyFile: "/tmp/body.md",
+    });
+  }),
+);
diff --git a/apps/server/src/sourceControl/GitHubSourceControlProvider.ts b/apps/server/src/sourceControl/GitHubSourceControlProvider.ts
new file mode 100644
index 00000000000..cc892015fce
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubSourceControlProvider.ts
@@ -0,0 +1,201 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import {
+  SourceControlProviderError,
+  type ChangeRequest,
+  type ChangeRequestState,
+} from "@t3tools/contracts";
+
+import * as GitHubCli from "./GitHubCli.ts";
+import * as GitHubPullRequests from "./gitHubPullRequests.ts";
+import * as SourceControlProvider from "./SourceControlProvider.ts";
+import * as SourceControlProviderDiscovery from "./SourceControlProviderDiscovery.ts";
+const isSourceControlProviderError = Schema.is(SourceControlProviderError);
+
+function providerError(
+  operation: string,
+  cause: GitHubCli.GitHubCliError,
+): SourceControlProviderError {
+  return new SourceControlProviderError({
+    provider: "github",
+    operation,
+    detail: cause.detail,
+    cause,
+  });
+}
+
+function toChangeRequest(summary: GitHubCli.GitHubPullRequestSummary): ChangeRequest {
+  return {
+    provider: "github",
+    number: summary.number,
+    title: summary.title,
+    url: summary.url,
+    baseRefName: summary.baseRefName,
+    headRefName: summary.headRefName,
+    state: summary.state ?? "open",
+    updatedAt: Option.none(),
+    ...(summary.isCrossRepository !== undefined
+      ? { isCrossRepository: summary.isCrossRepository }
+      : {}),
+    ...(summary.headRepositoryNameWithOwner !== undefined
+      ? { headRepositoryNameWithOwner: summary.headRepositoryNameWithOwner }
+      : {}),
+    ...(summary.headRepositoryOwnerLogin !== undefined
+      ? { headRepositoryOwnerLogin: summary.headRepositoryOwnerLogin }
+      : {}),
+  };
+}
+
+function parseGitHubAuth(input: SourceControlProviderDiscovery.SourceControlAuthProbeInput) {
+  const output = SourceControlProviderDiscovery.combinedAuthOutput(input);
+  const account = SourceControlProviderDiscovery.matchFirst(output, [
+    /Logged in to .* account\s+([^\s(]+)/iu,
+    /Logged in to .* as\s+([^\s(]+)/iu,
+  ]);
+  const host = SourceControlProviderDiscovery.parseCliHost(output);
+
+  if (input.exitCode !== 0) {
+    return SourceControlProviderDiscovery.providerAuth({
+      status: "unauthenticated",
+      host,
+      detail:
+        SourceControlProviderDiscovery.firstSafeAuthLine(output) ??
+        "Run `gh auth login` to authenticate GitHub CLI.",
+    });
+  }
+
+  if (account) {
+    return SourceControlProviderDiscovery.providerAuth({ status: "authenticated", account, host });
+  }
+
+  return SourceControlProviderDiscovery.providerAuth({
+    status: "unknown",
+    host,
+    detail:
+      SourceControlProviderDiscovery.firstSafeAuthLine(output) ??
+      "GitHub CLI auth status could not be parsed.",
+  });
+}
+
+export const discovery = {
+  type: "cli",
+  kind: "github",
+  label: "GitHub",
+  executable: "gh",
+  versionArgs: ["--version"],
+  authArgs: ["auth", "status"],
+  parseAuth: parseGitHubAuth,
+  installHint:
+    "Install the GitHub command-line tool (`gh`) via https://cli.github.com/ or your package manager (for example `brew install gh`).",
+} satisfies SourceControlProviderDiscovery.SourceControlCliDiscoverySpec;
+
+export const make = Effect.fn("makeGitHubSourceControlProvider")(function* () {
+  const github = yield* GitHubCli.GitHubCli;
+
+  const listChangeRequests: SourceControlProvider.SourceControlProviderShape["listChangeRequests"] =
+    (input) => {
+      if (input.state === "open") {
+        return github
+          .listOpenPullRequests({
+            cwd: input.cwd,
+            headSelector: input.headSelector,
+            ...(input.limit !== undefined ? { limit: input.limit } : {}),
+          })
+          .pipe(
+            Effect.map((items) => items.map(toChangeRequest)),
+            Effect.mapError((error) => providerError("listChangeRequests", error)),
+          );
+      }
+
+      const stateArg: ChangeRequestState | "all" = input.state;
+      return github
+        .execute({
+          cwd: input.cwd,
+          args: [
+            "pr",
+            "list",
+            "--head",
+            input.headSelector,
+            "--state",
+            stateArg,
+            "--limit",
+            String(input.limit ?? 20),
+            "--json",
+            "number,title,url,baseRefName,headRefName,state,mergedAt,updatedAt,isCrossRepository,headRepository,headRepositoryOwner",
+          ],
+        })
+        .pipe(
+          Effect.flatMap((result) => {
+            const raw = result.stdout.trim();
+            if (raw.length === 0) {
+              return Effect.succeed([]);
+            }
+            return Effect.sync(() => GitHubPullRequests.decodeGitHubPullRequestListJson(raw)).pipe(
+              Effect.flatMap((decoded) =>
+                Result.isSuccess(decoded)
+                  ? Effect.succeed(
+                      decoded.success.map((item) => ({
+                        ...toChangeRequest(item),
+                        updatedAt: item.updatedAt,
+                      })),
+                    )
+                  : Effect.fail(
+                      new SourceControlProviderError({
+                        provider: "github",
+                        operation: "listChangeRequests",
+                        detail: "GitHub CLI returned invalid change request JSON.",
+                        cause: decoded.failure,
+                      }),
+                    ),
+              ),
+            );
+          }),
+          Effect.mapError((error) =>
+            isSourceControlProviderError(error)
+              ? error
+              : providerError("listChangeRequests", error),
+          ),
+        );
+    };
+
+  return SourceControlProvider.SourceControlProvider.of({
+    kind: "github",
+    listChangeRequests,
+    getChangeRequest: (input) =>
+      github.getPullRequest(input).pipe(
+        Effect.map(toChangeRequest),
+        Effect.mapError((error) => providerError("getChangeRequest", error)),
+      ),
+    createChangeRequest: (input) =>
+      github
+        .createPullRequest({
+          cwd: input.cwd,
+          baseBranch: input.baseRefName,
+          headSelector: input.headSelector,
+          title: input.title,
+          bodyFile: input.bodyFile,
+        })
+        .pipe(Effect.mapError((error) => providerError("createChangeRequest", error))),
+    getRepositoryCloneUrls: (input) =>
+      github
+        .getRepositoryCloneUrls(input)
+        .pipe(Effect.mapError((error) => providerError("getRepositoryCloneUrls", error))),
+    createRepository: (input) =>
+      github
+        .createRepository(input)
+        .pipe(Effect.mapError((error) => providerError("createRepository", error))),
+    getDefaultBranch: (input) =>
+      github
+        .getDefaultBranch(input)
+        .pipe(Effect.mapError((error) => providerError("getDefaultBranch", error))),
+    checkoutChangeRequest: (input) =>
+      github
+        .checkoutPullRequest(input)
+        .pipe(Effect.mapError((error) => providerError("checkoutChangeRequest", error))),
+  });
+});
+
+export const layer = Layer.effect(SourceControlProvider.SourceControlProvider, make());
diff --git a/apps/server/src/sourceControl/GitLabCli.test.ts b/apps/server/src/sourceControl/GitLabCli.test.ts
new file mode 100644
index 00000000000..c075027151a
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabCli.test.ts
@@ -0,0 +1,339 @@
+import { assert, it, afterEach, expect, vi } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { VcsProcessExitError } from "@t3tools/contracts";
+
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as GitLabCli from "./GitLabCli.ts";
+
+const mockedRun = vi.fn<VcsProcess.VcsProcessShape["run"]>();
+const layer = it.layer(
+  GitLabCli.layer.pipe(
+    Layer.provide(
+      Layer.mock(VcsProcess.VcsProcess)({
+        run: mockedRun,
+      }),
+    ),
+  ),
+);
+
+function processOutput(stdout: string): VcsProcess.VcsProcessOutput {
+  return {
+    exitCode: ChildProcessSpawner.ExitCode(0),
+    stdout,
+    stderr: "",
+    stdoutTruncated: false,
+    stderrTruncated: false,
+  };
+}
+
+afterEach(() => {
+  mockedRun.mockReset();
+});
+
+layer("GitLabCli.layer", (it) => {
+  it.effect("parses merge request view output", () =>
+    Effect.gen(function* () {
+      mockedRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              iid: 42,
+              title: "Add MR thread creation",
+              web_url: "https://gitlab.com/pingdotgg/t3code/-/merge_requests/42",
+              target_branch: "main",
+              source_branch: "feature/mr-threads",
+              state: "opened",
+              source_project_id: 101,
+              target_project_id: 100,
+              source_project: {
+                path_with_namespace: "octocat/t3code",
+              },
+            }),
+          ),
+        ),
+      );
+
+      const result = yield* Effect.gen(function* () {
+        const glab = yield* GitLabCli.GitLabCli;
+        return yield* glab.getMergeRequest({
+          cwd: "/repo",
+          reference: "42",
+        });
+      });
+
+      assert.deepStrictEqual(result, {
+        number: 42,
+        title: "Add MR thread creation",
+        url: "https://gitlab.com/pingdotgg/t3code/-/merge_requests/42",
+        baseRefName: "main",
+        headRefName: "feature/mr-threads",
+        state: "open",
+        isCrossRepository: true,
+        headRepositoryNameWithOwner: "octocat/t3code",
+        headRepositoryOwnerLogin: "octocat",
+      });
+      expect(mockedRun).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "glab",
+          cwd: "/repo",
+          args: ["mr", "view", "42", "--output", "json"],
+        }),
+      );
+    }),
+  );
+
+  it.effect("skips invalid entries when parsing MR lists", () =>
+    Effect.gen(function* () {
+      mockedRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify([
+              {
+                iid: 0,
+                title: "invalid",
+                web_url: "https://gitlab.com/pingdotgg/t3code/-/merge_requests/0",
+                target_branch: "main",
+                source_branch: "feature/invalid",
+              },
+              {
+                iid: 43,
+                title: "  Valid MR  ",
+                web_url: " https://gitlab.com/pingdotgg/t3code/-/merge_requests/43 ",
+                target_branch: " main ",
+                source_branch: " feature/mr-list ",
+                state: "merged",
+              },
+            ]),
+          ),
+        ),
+      );
+
+      const result = yield* Effect.gen(function* () {
+        const glab = yield* GitLabCli.GitLabCli;
+        return yield* glab.listMergeRequests({
+          cwd: "/repo",
+          headSelector: "feature/mr-list",
+          state: "all",
+        });
+      });
+
+      assert.deepStrictEqual(result, [
+        {
+          number: 43,
+          title: "Valid MR",
+          url: "https://gitlab.com/pingdotgg/t3code/-/merge_requests/43",
+          baseRefName: "main",
+          headRefName: "feature/mr-list",
+          state: "merged",
+        },
+      ]);
+      expect(mockedRun).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "glab",
+          cwd: "/repo",
+          args: [
+            "mr",
+            "list",
+            "--source-branch",
+            "feature/mr-list",
+            "--all",
+            "--per-page",
+            "20",
+            "--output",
+            "json",
+          ],
+        }),
+      );
+    }),
+  );
+
+  it.effect("reads repository clone URLs", () =>
+    Effect.gen(function* () {
+      mockedRun.mockReturnValueOnce(
+        Effect.succeed(
+          processOutput(
+            // @effect-diagnostics-next-line preferSchemaOverJson:off
+            JSON.stringify({
+              path_with_namespace: "octocat/t3code",
+              web_url: "https://gitlab.com/octocat/t3code",
+              http_url_to_repo: "https://gitlab.com/octocat/t3code.git",
+              ssh_url_to_repo: "git@gitlab.com:octocat/t3code.git",
+            }),
+          ),
+        ),
+      );
+
+      const result = yield* Effect.gen(function* () {
+        const glab = yield* GitLabCli.GitLabCli;
+        return yield* glab.getRepositoryCloneUrls({
+          cwd: "/repo",
+          repository: "octocat/t3code",
+        });
+      });
+
+      assert.deepStrictEqual(result, {
+        nameWithOwner: "octocat/t3code",
+        url: "https://gitlab.com/octocat/t3code",
+        sshUrl: "git@gitlab.com:octocat/t3code.git",
+      });
+    }),
+  );
+
+  it.effect("creates merge requests through the GitLab API without placing the body in argv", () =>
+    Effect.gen(function* () {
+      mockedRun.mockReturnValueOnce(Effect.succeed(processOutput("{}")));
+
+      const glab = yield* GitLabCli.GitLabCli;
+      yield* glab.createMergeRequest({
+        cwd: "/repo",
+        baseBranch: "main",
+        headSelector: "owner:feature/provider",
+        title: "Provider MR",
+        bodyFile: "/tmp/t3-mr-body.md",
+      });
+
+      expect(mockedRun).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "glab",
+          cwd: "/repo",
+          args: [
+            "api",
+            "--method",
+            "POST",
+            "projects/:fullpath/merge_requests",
+            "--raw-field",
+            "source_branch=feature/provider",
+            "--raw-field",
+            "target_branch=main",
+            "--raw-field",
+            "title=Provider MR",
+            "--field",
+            "description=@/tmp/t3-mr-body.md",
+          ],
+        }),
+      );
+    }),
+  );
+
+  it.effect("creates repositories under an explicit namespace", () =>
+    Effect.gen(function* () {
+      mockedRun
+
+        .mockReturnValueOnce(
+          Effect.succeed(
+            processOutput(
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
+              JSON.stringify({ id: 1234 }),
+            ),
+          ),
+        )
+        .mockReturnValueOnce(
+          Effect.succeed(
+            processOutput(
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
+              JSON.stringify({
+                path_with_namespace: "octocat/t3code",
+                web_url: "https://gitlab.com/octocat/t3code",
+                http_url_to_repo: "https://gitlab.com/octocat/t3code.git",
+                ssh_url_to_repo: "git@gitlab.com:octocat/t3code.git",
+              }),
+            ),
+          ),
+        );
+
+      const glab = yield* GitLabCli.GitLabCli;
+      const result = yield* glab.createRepository({
+        cwd: "/repo",
+        repository: "octocat/t3code",
+        visibility: "public",
+      });
+
+      assert.deepStrictEqual(result, {
+        nameWithOwner: "octocat/t3code",
+        url: "https://gitlab.com/octocat/t3code",
+        sshUrl: "git@gitlab.com:octocat/t3code.git",
+      });
+      expect(mockedRun).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          command: "glab",
+          cwd: "/repo",
+          args: ["api", "namespaces/octocat"],
+        }),
+      );
+      expect(mockedRun).toHaveBeenNthCalledWith(
+        2,
+        expect.objectContaining({
+          command: "glab",
+          cwd: "/repo",
+          args: [
+            "api",
+            "--method",
+            "POST",
+            "projects",
+            "--raw-field",
+            "path=t3code",
+            "--raw-field",
+            "name=t3code",
+            "--raw-field",
+            "visibility=public",
+            "--raw-field",
+            "namespace_id=1234",
+          ],
+        }),
+      );
+    }),
+  );
+
+  it.effect("does not pass unsupported force flags when checking out merge requests", () =>
+    Effect.gen(function* () {
+      mockedRun.mockReturnValueOnce(Effect.succeed(processOutput("")));
+
+      const glab = yield* GitLabCli.GitLabCli;
+      yield* glab.checkoutMergeRequest({
+        cwd: "/repo",
+        reference: "42",
+        force: true,
+      });
+
+      expect(mockedRun).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "glab",
+          cwd: "/repo",
+          args: ["mr", "checkout", "42"],
+        }),
+      );
+    }),
+  );
+
+  it.effect("surfaces a friendly error when the merge request is not found", () =>
+    Effect.gen(function* () {
+      mockedRun.mockReturnValueOnce(
+        Effect.fail(
+          new VcsProcessExitError({
+            operation: "GitLabCli.execute",
+            command: "glab mr view 4888",
+            cwd: "/repo",
+            exitCode: 1,
+            detail: "GET 404 merge request not found",
+          }),
+        ),
+      );
+
+      const error = yield* Effect.gen(function* () {
+        const glab = yield* GitLabCli.GitLabCli;
+        return yield* glab.getMergeRequest({
+          cwd: "/repo",
+          reference: "4888",
+        });
+      }).pipe(Effect.flip);
+
+      assert.equal(error.message.includes("Merge request not found"), true);
+    }),
+  );
+});
diff --git a/apps/server/src/sourceControl/GitLabCli.ts b/apps/server/src/sourceControl/GitLabCli.ts
new file mode 100644
index 00000000000..faabe87263d
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabCli.ts
@@ -0,0 +1,449 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import type * as DateTime from "effect/DateTime";
+
+import { TrimmedNonEmptyString, type SourceControlRepositoryVisibility } from "@t3tools/contracts";
+
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as GitLabMergeRequests from "./gitLabMergeRequests.ts";
+import type * as SourceControlProvider from "./SourceControlProvider.ts";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class GitLabCliError extends Schema.TaggedErrorClass<GitLabCliError>()("GitLabCliError", {
+  operation: Schema.String,
+  detail: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {
+  override get message(): string {
+    return `GitLab CLI failed in ${this.operation}: ${this.detail}`;
+  }
+}
+
+export interface GitLabMergeRequestSummary {
+  readonly number: number;
+  readonly title: string;
+  readonly url: string;
+  readonly baseRefName: string;
+  readonly headRefName: string;
+  readonly state?: "open" | "closed" | "merged";
+  readonly updatedAt?: Option.Option<DateTime.Utc>;
+  readonly isCrossRepository?: boolean;
+  readonly headRepositoryNameWithOwner?: string | null;
+  readonly headRepositoryOwnerLogin?: string | null;
+}
+
+export interface GitLabRepositoryCloneUrls {
+  readonly nameWithOwner: string;
+  readonly url: string;
+  readonly sshUrl: string;
+}
+
+export interface GitLabCliShape {
+  readonly execute: (input: {
+    readonly cwd: string;
+    readonly args: ReadonlyArray<string>;
+    readonly timeoutMs?: number;
+  }) => Effect.Effect<VcsProcess.VcsProcessOutput, GitLabCliError>;
+
+  readonly listMergeRequests: (input: {
+    readonly cwd: string;
+    readonly headSelector: string;
+    readonly source?: SourceControlProvider.SourceControlRefSelector;
+    readonly state: "open" | "closed" | "merged" | "all";
+    readonly limit?: number;
+  }) => Effect.Effect<ReadonlyArray<GitLabMergeRequestSummary>, GitLabCliError>;
+
+  readonly getMergeRequest: (input: {
+    readonly cwd: string;
+    readonly reference: string;
+  }) => Effect.Effect<GitLabMergeRequestSummary, GitLabCliError>;
+
+  readonly getRepositoryCloneUrls: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+  }) => Effect.Effect<GitLabRepositoryCloneUrls, GitLabCliError>;
+
+  readonly createRepository: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+    readonly visibility: SourceControlRepositoryVisibility;
+  }) => Effect.Effect<GitLabRepositoryCloneUrls, GitLabCliError>;
+
+  readonly createMergeRequest: (input: {
+    readonly cwd: string;
+    readonly baseBranch: string;
+    readonly headSelector: string;
+    readonly source?: SourceControlProvider.SourceControlRefSelector;
+    readonly target?: SourceControlProvider.SourceControlRefSelector;
+    readonly title: string;
+    readonly bodyFile: string;
+  }) => Effect.Effect<void, GitLabCliError>;
+
+  readonly getDefaultBranch: (input: {
+    readonly cwd: string;
+  }) => Effect.Effect<string | null, GitLabCliError>;
+
+  readonly checkoutMergeRequest: (input: {
+    readonly cwd: string;
+    readonly reference: string;
+    readonly force?: boolean;
+  }) => Effect.Effect<void, GitLabCliError>;
+}
+
+export class GitLabCli extends Context.Service<GitLabCli, GitLabCliShape>()(
+  "t3/source-control/GitLabCli",
+) {}
+
+function isVcsProcessSpawnError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "_tag" in error &&
+    error._tag === "VcsProcessSpawnError"
+  );
+}
+
+function normalizeGitLabCliError(operation: "execute" | "stdout", error: unknown): GitLabCliError {
+  if (error instanceof Error) {
+    if (error.message.includes("Command not found: glab") || isVcsProcessSpawnError(error)) {
+      return new GitLabCliError({
+        operation,
+        detail: "GitLab CLI (`glab`) is required but not available on PATH.",
+        cause: error,
+      });
+    }
+
+    const lower = error.message.toLowerCase();
+    if (
+      lower.includes("authentication failed") ||
+      lower.includes("not logged in") ||
+      lower.includes("glab auth login") ||
+      lower.includes("token")
+    ) {
+      return new GitLabCliError({
+        operation,
+        detail: "GitLab CLI is not authenticated. Run `glab auth login` and retry.",
+        cause: error,
+      });
+    }
+
+    if (
+      lower.includes("merge request not found") ||
+      lower.includes("not found") ||
+      lower.includes("404")
+    ) {
+      return new GitLabCliError({
+        operation,
+        detail: "Merge request not found. Check the MR number or URL and try again.",
+        cause: error,
+      });
+    }
+
+    return new GitLabCliError({
+      operation,
+      detail: `GitLab CLI command failed: ${error.message}`,
+      cause: error,
+    });
+  }
+
+  return new GitLabCliError({
+    operation,
+    detail: "GitLab CLI command failed.",
+    cause: error,
+  });
+}
+
+const RawGitLabRepositoryCloneUrlsSchema = Schema.Struct({
+  path_with_namespace: TrimmedNonEmptyString,
+  web_url: TrimmedNonEmptyString,
+  http_url_to_repo: TrimmedNonEmptyString,
+  ssh_url_to_repo: TrimmedNonEmptyString,
+});
+
+const RawGitLabDefaultBranchSchema = Schema.Struct({
+  default_branch: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
+});
+
+const RawGitLabNamespaceSchema = Schema.Struct({
+  id: Schema.Number,
+});
+
+function normalizeRepositoryCloneUrls(
+  raw: Schema.Schema.Type<typeof RawGitLabRepositoryCloneUrlsSchema>,
+): GitLabRepositoryCloneUrls {
+  return {
+    nameWithOwner: raw.path_with_namespace,
+    url: raw.web_url,
+    sshUrl: raw.ssh_url_to_repo,
+  };
+}
+
+function decodeGitLabJson<S extends Schema.Top>(
+  raw: string,
+  schema: S,
+  operation: "getRepositoryCloneUrls" | "getDefaultBranch" | "createRepository",
+  invalidDetail: string,
+): Effect.Effect<S["Type"], GitLabCliError, S["DecodingServices"]> {
+  return Schema.decodeEffect(Schema.fromJsonString(schema))(raw).pipe(
+    Effect.mapError(
+      (error) =>
+        new GitLabCliError({
+          operation,
+          detail: `${invalidDetail}: ${SchemaIssue.makeFormatterDefault()(error.issue)}`,
+          cause: error,
+        }),
+    ),
+  );
+}
+
+function stateArgs(state: "open" | "closed" | "merged" | "all"): ReadonlyArray<string> {
+  switch (state) {
+    case "open":
+      return [];
+    case "closed":
+      return ["--closed"];
+    case "merged":
+      return ["--merged"];
+    case "all":
+      return ["--all"];
+  }
+}
+
+function normalizeHeadSelector(headSelector: string): string {
+  const trimmed = headSelector.trim();
+  const ownerBranch = /^[^:]+:(.+)$/.exec(trimmed);
+  return ownerBranch?.[1]?.trim() || trimmed;
+}
+
+function sourceRefName(input: {
+  readonly headSelector: string;
+  readonly source?: SourceControlProvider.SourceControlRefSelector;
+}): string {
+  return input.source?.refName ?? normalizeHeadSelector(input.headSelector);
+}
+
+function sourceProjectIdentifier(
+  source: SourceControlProvider.SourceControlRefSelector | undefined,
+): string | null {
+  return source?.repository ?? source?.owner ?? null;
+}
+
+function toSummaryWithOptionalUpdatedAt(
+  record: GitLabMergeRequestSummary & {
+    readonly updatedAt: Option.Option<DateTime.Utc>;
+  },
+): GitLabMergeRequestSummary {
+  const { updatedAt, ...summary } = record;
+  return Option.isSome(updatedAt) ? { ...summary, updatedAt } : summary;
+}
+
+function parseRepositoryPath(repository: string): {
+  readonly namespacePath: string | null;
+  readonly projectPath: string;
+} {
+  const parts = repository
+    .split("/")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  const projectPath = parts.at(-1) ?? repository.trim();
+  const namespacePath = parts.length > 1 ? parts.slice(0, -1).join("/") : null;
+  return { namespacePath, projectPath };
+}
+
+export const make = Effect.fn("makeGitLabCli")(function* () {
+  const process = yield* VcsProcess.VcsProcess;
+
+  const execute: GitLabCliShape["execute"] = (input) =>
+    process
+      .run({
+        operation: "GitLabCli.execute",
+        command: "glab",
+        args: input.args,
+        cwd: input.cwd,
+        timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      })
+      .pipe(Effect.mapError((error) => normalizeGitLabCliError("execute", error)));
+
+  return GitLabCli.of({
+    execute,
+    listMergeRequests: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: [
+          "mr",
+          "list",
+          "--source-branch",
+          sourceRefName(input),
+          ...stateArgs(input.state),
+          "--per-page",
+          String(input.limit ?? 20),
+          "--output",
+          "json",
+        ],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          raw.length === 0
+            ? Effect.succeed([])
+            : Effect.sync(() => GitLabMergeRequests.decodeGitLabMergeRequestListJson(raw)).pipe(
+                Effect.flatMap((decoded) => {
+                  if (!Result.isSuccess(decoded)) {
+                    return Effect.fail(
+                      new GitLabCliError({
+                        operation: "listMergeRequests",
+                        detail: `GitLab CLI returned invalid MR list JSON: ${GitLabMergeRequests.formatGitLabJsonDecodeError(decoded.failure)}`,
+                        cause: decoded.failure,
+                      }),
+                    );
+                  }
+
+                  return Effect.succeed(decoded.success.map(toSummaryWithOptionalUpdatedAt));
+                }),
+              ),
+        ),
+      ),
+    getMergeRequest: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["mr", "view", input.reference, "--output", "json"],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          Effect.sync(() => GitLabMergeRequests.decodeGitLabMergeRequestJson(raw)).pipe(
+            Effect.flatMap((decoded) => {
+              if (!Result.isSuccess(decoded)) {
+                return Effect.fail(
+                  new GitLabCliError({
+                    operation: "getMergeRequest",
+                    detail: `GitLab CLI returned invalid merge request JSON: ${GitLabMergeRequests.formatGitLabJsonDecodeError(decoded.failure)}`,
+                    cause: decoded.failure,
+                  }),
+                );
+              }
+
+              return Effect.succeed(toSummaryWithOptionalUpdatedAt(decoded.success));
+            }),
+          ),
+        ),
+      ),
+    getRepositoryCloneUrls: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["api", `projects/${encodeURIComponent(input.repository)}`],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          decodeGitLabJson(
+            raw,
+            RawGitLabRepositoryCloneUrlsSchema,
+            "getRepositoryCloneUrls",
+            "GitLab CLI returned invalid repository JSON.",
+          ),
+        ),
+        Effect.map(normalizeRepositoryCloneUrls),
+      ),
+    createRepository: (input) => {
+      const { namespacePath, projectPath } = parseRepositoryPath(input.repository);
+      const namespaceId: Effect.Effect<number | null, GitLabCliError> = namespacePath
+        ? execute({
+            cwd: input.cwd,
+            args: ["api", `namespaces/${encodeURIComponent(namespacePath)}`],
+          }).pipe(
+            Effect.map((result) => result.stdout.trim()),
+            Effect.flatMap((raw) =>
+              decodeGitLabJson(
+                raw,
+                RawGitLabNamespaceSchema,
+                "createRepository",
+                "GitLab CLI returned invalid namespace JSON.",
+              ),
+            ),
+            Effect.map((namespace) => namespace.id),
+          )
+        : Effect.succeed(null);
+
+      return namespaceId.pipe(
+        Effect.flatMap((resolvedNamespaceId) =>
+          execute({
+            cwd: input.cwd,
+            args: [
+              "api",
+              "--method",
+              "POST",
+              "projects",
+              "--raw-field",
+              `path=${projectPath}`,
+              "--raw-field",
+              `name=${projectPath}`,
+              "--raw-field",
+              `visibility=${input.visibility}`,
+              ...(resolvedNamespaceId === null
+                ? []
+                : ["--raw-field", `namespace_id=${resolvedNamespaceId}`]),
+            ],
+          }),
+        ),
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          decodeGitLabJson(
+            raw,
+            RawGitLabRepositoryCloneUrlsSchema,
+            "createRepository",
+            "GitLab CLI returned invalid repository JSON.",
+          ),
+        ),
+        Effect.map(normalizeRepositoryCloneUrls),
+      );
+    },
+    createMergeRequest: (input) => {
+      const sourceProject = sourceProjectIdentifier(input.source);
+      return execute({
+        cwd: input.cwd,
+        args: [
+          "api",
+          "--method",
+          "POST",
+          "projects/:fullpath/merge_requests",
+          "--raw-field",
+          `source_branch=${sourceRefName(input)}`,
+          "--raw-field",
+          `target_branch=${input.target?.refName ?? input.baseBranch}`,
+          ...(sourceProject ? ["--raw-field", `source_project_id=${sourceProject}`] : []),
+          "--raw-field",
+          `title=${input.title}`,
+          "--field",
+          `description=@${input.bodyFile}`,
+        ],
+      }).pipe(Effect.asVoid);
+    },
+    getDefaultBranch: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["api", "projects/:fullpath"],
+      }).pipe(
+        Effect.map((result) => result.stdout.trim()),
+        Effect.flatMap((raw) =>
+          decodeGitLabJson(
+            raw,
+            RawGitLabDefaultBranchSchema,
+            "getDefaultBranch",
+            "GitLab CLI returned invalid repository JSON.",
+          ),
+        ),
+        Effect.map((value) => value.default_branch ?? null),
+      ),
+    checkoutMergeRequest: (input) =>
+      execute({
+        cwd: input.cwd,
+        args: ["mr", "checkout", input.reference],
+      }).pipe(Effect.asVoid),
+  });
+});
+
+export const layer = Layer.effect(GitLabCli, make());
diff --git a/apps/server/src/sourceControl/GitLabSourceControlProvider.test.ts b/apps/server/src/sourceControl/GitLabSourceControlProvider.test.ts
new file mode 100644
index 00000000000..94d363d1c1b
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabSourceControlProvider.test.ts
@@ -0,0 +1,109 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import * as GitLabCli from "./GitLabCli.ts";
+import * as GitLabSourceControlProvider from "./GitLabSourceControlProvider.ts";
+
+function makeProvider(gitlab: Partial<GitLabCli.GitLabCliShape>) {
+  return GitLabSourceControlProvider.make().pipe(
+    Effect.provide(Layer.mock(GitLabCli.GitLabCli)(gitlab)),
+  );
+}
+
+it.effect("maps GitLab MR summaries into provider-neutral change requests", () =>
+  Effect.gen(function* () {
+    const provider = yield* makeProvider({
+      getMergeRequest: () =>
+        Effect.succeed({
+          number: 42,
+          title: "Add GitLab provider",
+          url: "https://gitlab.com/pingdotgg/t3code/-/merge_requests/42",
+          baseRefName: "main",
+          headRefName: "feature/source-control",
+          state: "open",
+          isCrossRepository: true,
+          headRepositoryNameWithOwner: "fork/t3code",
+          headRepositoryOwnerLogin: "fork",
+        }),
+    });
+
+    const changeRequest = yield* provider.getChangeRequest({
+      cwd: "/repo",
+      reference: "42",
+    });
+
+    assert.deepStrictEqual(changeRequest, {
+      provider: "gitlab",
+      number: 42,
+      title: "Add GitLab provider",
+      url: "https://gitlab.com/pingdotgg/t3code/-/merge_requests/42",
+      baseRefName: "main",
+      headRefName: "feature/source-control",
+      state: "open",
+      updatedAt: Option.none(),
+      isCrossRepository: true,
+      headRepositoryNameWithOwner: "fork/t3code",
+      headRepositoryOwnerLogin: "fork",
+    });
+  }),
+);
+
+it.effect("lists GitLab MRs through provider-neutral input names", () =>
+  Effect.gen(function* () {
+    let listInput: Parameters<GitLabCli.GitLabCliShape["listMergeRequests"]>[0] | null = null;
+    const provider = yield* makeProvider({
+      listMergeRequests: (input) => {
+        listInput = input;
+        return Effect.succeed([]);
+      },
+    });
+
+    yield* provider.listChangeRequests({
+      cwd: "/repo",
+      headSelector: "feature/provider",
+      state: "all",
+      limit: 10,
+    });
+
+    assert.deepStrictEqual(listInput, {
+      cwd: "/repo",
+      headSelector: "feature/provider",
+      state: "all",
+      limit: 10,
+    });
+  }),
+);
+
+it.effect("creates GitLab MRs through provider-neutral input names", () =>
+  Effect.gen(function* () {
+    let createInput: Parameters<GitLabCli.GitLabCliShape["createMergeRequest"]>[0] | null = null;
+    const provider = yield* makeProvider({
+      createMergeRequest: (input) => {
+        createInput = input;
+        return Effect.void;
+      },
+    });
+
+    yield* provider.createChangeRequest({
+      cwd: "/repo",
+      baseRefName: "main",
+      headSelector: "owner:feature/provider",
+      title: "Provider MR",
+      bodyFile: "/tmp/body.md",
+    });
+
+    assert.deepStrictEqual(createInput, {
+      cwd: "/repo",
+      baseBranch: "main",
+      headSelector: "owner:feature/provider",
+      source: {
+        owner: "owner",
+        refName: "feature/provider",
+      },
+      title: "Provider MR",
+      bodyFile: "/tmp/body.md",
+    });
+  }),
+);
diff --git a/apps/server/src/sourceControl/GitLabSourceControlProvider.ts b/apps/server/src/sourceControl/GitLabSourceControlProvider.ts
new file mode 100644
index 00000000000..ccab2bd1f76
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabSourceControlProvider.ts
@@ -0,0 +1,146 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { SourceControlProviderError, type ChangeRequest } from "@t3tools/contracts";
+
+import * as GitLabCli from "./GitLabCli.ts";
+import * as SourceControlProvider from "./SourceControlProvider.ts";
+import * as SourceControlProviderDiscovery from "./SourceControlProviderDiscovery.ts";
+
+function providerError(
+  operation: string,
+  cause: GitLabCli.GitLabCliError,
+): SourceControlProviderError {
+  return new SourceControlProviderError({
+    provider: "gitlab",
+    operation,
+    detail: cause.detail,
+    cause,
+  });
+}
+
+function toChangeRequest(summary: GitLabCli.GitLabMergeRequestSummary): ChangeRequest {
+  return {
+    provider: "gitlab",
+    number: summary.number,
+    title: summary.title,
+    url: summary.url,
+    baseRefName: summary.baseRefName,
+    headRefName: summary.headRefName,
+    state: summary.state ?? "open",
+    updatedAt: summary.updatedAt ?? Option.none(),
+    ...(summary.isCrossRepository !== undefined
+      ? { isCrossRepository: summary.isCrossRepository }
+      : {}),
+    ...(summary.headRepositoryNameWithOwner !== undefined
+      ? { headRepositoryNameWithOwner: summary.headRepositoryNameWithOwner }
+      : {}),
+    ...(summary.headRepositoryOwnerLogin !== undefined
+      ? { headRepositoryOwnerLogin: summary.headRepositoryOwnerLogin }
+      : {}),
+  };
+}
+
+function parseGitLabAuth(input: SourceControlProviderDiscovery.SourceControlAuthProbeInput) {
+  const output = SourceControlProviderDiscovery.combinedAuthOutput(input);
+  const account = SourceControlProviderDiscovery.matchFirst(output, [
+    /Logged in to .* as\s+([^\s(]+)/iu,
+    /Logged in to .* account\s+([^\s(]+)/iu,
+    /account:\s*([^\s(]+)/iu,
+  ]);
+  const host = SourceControlProviderDiscovery.parseCliHost(output);
+
+  if (input.exitCode !== 0) {
+    return SourceControlProviderDiscovery.providerAuth({
+      status: "unauthenticated",
+      host,
+      detail:
+        SourceControlProviderDiscovery.firstSafeAuthLine(output) ??
+        "Run `glab auth login` to authenticate GitLab CLI.",
+    });
+  }
+
+  if (account) {
+    return SourceControlProviderDiscovery.providerAuth({ status: "authenticated", account, host });
+  }
+
+  return SourceControlProviderDiscovery.providerAuth({
+    status: "unknown",
+    host,
+    detail:
+      SourceControlProviderDiscovery.firstSafeAuthLine(output) ??
+      "GitLab CLI auth status could not be parsed.",
+  });
+}
+
+export const discovery = {
+  type: "cli",
+  kind: "gitlab",
+  label: "GitLab",
+  executable: "glab",
+  versionArgs: ["--version"],
+  authArgs: ["auth", "status"],
+  parseAuth: parseGitLabAuth,
+  installHint:
+    "Install the GitLab command-line tool (`glab`) from https://gitlab.com/gitlab-org/cli or your package manager (for example `brew install glab`).",
+} satisfies SourceControlProviderDiscovery.SourceControlCliDiscoverySpec;
+
+export const make = Effect.fn("makeGitLabSourceControlProvider")(function* () {
+  const gitlab = yield* GitLabCli.GitLabCli;
+
+  return SourceControlProvider.SourceControlProvider.of({
+    kind: "gitlab",
+    listChangeRequests: (input) => {
+      const source = SourceControlProvider.sourceControlRefFromInput(input);
+      return gitlab
+        .listMergeRequests({
+          cwd: input.cwd,
+          headSelector: input.headSelector,
+          ...(source ? { source } : {}),
+          state: input.state,
+          ...(input.limit !== undefined ? { limit: input.limit } : {}),
+        })
+        .pipe(
+          Effect.map((items) => items.map(toChangeRequest)),
+          Effect.mapError((error) => providerError("listChangeRequests", error)),
+        );
+    },
+    getChangeRequest: (input) =>
+      gitlab.getMergeRequest(input).pipe(
+        Effect.map(toChangeRequest),
+        Effect.mapError((error) => providerError("getChangeRequest", error)),
+      ),
+    createChangeRequest: (input) => {
+      const source = SourceControlProvider.sourceControlRefFromInput(input);
+      return gitlab
+        .createMergeRequest({
+          cwd: input.cwd,
+          baseBranch: input.baseRefName,
+          headSelector: input.headSelector,
+          ...(source ? { source } : {}),
+          ...(input.target ? { target: input.target } : {}),
+          title: input.title,
+          bodyFile: input.bodyFile,
+        })
+        .pipe(Effect.mapError((error) => providerError("createChangeRequest", error)));
+    },
+    getRepositoryCloneUrls: (input) =>
+      gitlab
+        .getRepositoryCloneUrls(input)
+        .pipe(Effect.mapError((error) => providerError("getRepositoryCloneUrls", error))),
+    createRepository: (input) =>
+      gitlab
+        .createRepository(input)
+        .pipe(Effect.mapError((error) => providerError("createRepository", error))),
+    getDefaultBranch: (input) =>
+      gitlab
+        .getDefaultBranch(input)
+        .pipe(Effect.mapError((error) => providerError("getDefaultBranch", error))),
+    checkoutChangeRequest: (input) =>
+      gitlab
+        .checkoutMergeRequest(input)
+        .pipe(Effect.mapError((error) => providerError("checkoutChangeRequest", error))),
+  });
+});
+
+export const layer = Layer.effect(SourceControlProvider.SourceControlProvider, make());
diff --git a/apps/server/src/sourceControl/SourceControlDiscovery.test.ts b/apps/server/src/sourceControl/SourceControlDiscovery.test.ts
new file mode 100644
index 00000000000..d1c6c65c752
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlDiscovery.test.ts
@@ -0,0 +1,259 @@
+import { assert, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { VcsProcessSpawnError } from "@t3tools/contracts";
+
+import { ServerConfig } from "../config.ts";
+import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as AzureDevOpsCli from "./AzureDevOpsCli.ts";
+import * as BitbucketApi from "./BitbucketApi.ts";
+import * as GitHubCli from "./GitHubCli.ts";
+import * as GitLabCli from "./GitLabCli.ts";
+import * as SourceControlDiscovery from "./SourceControlDiscovery.ts";
+import * as SourceControlProviderRegistry from "./SourceControlProviderRegistry.ts";
+
+const sourceControlProviderRegistryTestLayer = (input: {
+  readonly bitbucket: Partial<BitbucketApi.BitbucketApiShape>;
+  readonly process: Partial<VcsProcess.VcsProcessShape>;
+}) =>
+  SourceControlProviderRegistry.layer.pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        ServerConfig.layerTest(process.cwd(), { prefix: "t3-source-control-registry-test-" }).pipe(
+          Layer.provide(NodeServices.layer),
+        ),
+        Layer.mock(AzureDevOpsCli.AzureDevOpsCli)({}),
+        Layer.mock(BitbucketApi.BitbucketApi)(input.bitbucket),
+        Layer.mock(GitHubCli.GitHubCli)({}),
+        Layer.mock(GitLabCli.GitLabCli)({}),
+        Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({}),
+        Layer.mock(VcsProcess.VcsProcess)(input.process),
+      ),
+    ),
+  );
+
+const processOutput = (
+  stdout: string,
+  options?: {
+    readonly stderr?: string;
+    readonly exitCode?: ChildProcessSpawner.ExitCode;
+  },
+): VcsProcess.VcsProcessOutput => ({
+  exitCode: options?.exitCode ?? ChildProcessSpawner.ExitCode(0),
+  stdout,
+  stderr: options?.stderr ?? "",
+  stdoutTruncated: false,
+  stderrTruncated: false,
+});
+
+it.effect("reports implemented tools separately from locally available executables", () => {
+  const processMock = {
+    run: (input: VcsProcess.VcsProcessInput) => {
+      if (input.command === "git") {
+        return Effect.succeed(processOutput("git version 2.51.0\n"));
+      }
+      if (input.command === "gh" && input.args[0] === "--version") {
+        return Effect.succeed(processOutput("gh version 2.83.0\n"));
+      }
+      if (input.command === "gh" && input.args.join(" ") === "auth status") {
+        return Effect.succeed(
+          processOutput(`github.com
+Logged in to github.com account juliusmarminge (keyring)
+- Active account: true
+- Git operations protocol: ssh
+- Token: gho_************************************
+- Token scopes: 'admin:public_key', 'gist', 'read:org', 'repo'
+`),
+        );
+      }
+      return Effect.fail(
+        new VcsProcessSpawnError({
+          operation: input.operation,
+          command: input.command,
+          cwd: input.cwd,
+          cause: new Error(`${input.command} not found`),
+        }),
+      );
+    },
+  } satisfies Partial<VcsProcess.VcsProcessShape>;
+  const testLayer = SourceControlDiscovery.layer.pipe(
+    Layer.provide(
+      ServerConfig.layerTest(process.cwd(), { prefix: "t3-source-control-discovery-" }),
+    ),
+    Layer.provide(Layer.mock(VcsProcess.VcsProcess)(processMock)),
+    Layer.provide(
+      sourceControlProviderRegistryTestLayer({
+        process: processMock,
+        bitbucket: {
+          probeAuth: Effect.succeed({
+            status: "unauthenticated",
+            account: Option.none(),
+            host: Option.some("bitbucket.org"),
+            detail: Option.some(
+              "Set T3CODE_BITBUCKET_EMAIL and T3CODE_BITBUCKET_API_TOKEN, or T3CODE_BITBUCKET_ACCESS_TOKEN.",
+            ),
+          }),
+        },
+      }),
+    ),
+    Layer.provideMerge(NodeServices.layer),
+  );
+
+  return Effect.gen(function* () {
+    const discovery = yield* SourceControlDiscovery.SourceControlDiscovery;
+    const result = yield* discovery.discover;
+
+    assert.deepStrictEqual(
+      result.versionControlSystems.map((item) => ({
+        kind: item.kind,
+        implemented: item.implemented,
+        status: item.status,
+      })),
+      [
+        { kind: "git", implemented: true, status: "available" },
+        { kind: "jj", implemented: false, status: "missing" },
+      ],
+    );
+    assert.deepStrictEqual(
+      result.sourceControlProviders.map((item) => ({
+        kind: item.kind,
+        status: item.status,
+        auth: item.auth.status,
+        account: item.auth.account,
+      })),
+      [
+        {
+          kind: "github",
+          status: "available",
+          auth: "authenticated",
+          account: Option.some("juliusmarminge"),
+        },
+        {
+          kind: "gitlab",
+          status: "missing",
+          auth: "unknown",
+          account: Option.none(),
+        },
+        {
+          kind: "azure-devops",
+          status: "missing",
+          auth: "unknown",
+          account: Option.none(),
+        },
+        {
+          kind: "bitbucket",
+          status: "available",
+          auth: "unauthenticated",
+          account: Option.none(),
+        },
+      ],
+    );
+    const bitbucket = result.sourceControlProviders.find((item) => item.kind === "bitbucket");
+    assert.ok(bitbucket);
+    assert.strictEqual(bitbucket.executable, undefined);
+  }).pipe(Effect.provide(testLayer));
+});
+
+it.effect("probes provider authentication without exposing token details", () => {
+  const processMock = {
+    run: (input: VcsProcess.VcsProcessInput) => {
+      if (input.args[0] === "--version") {
+        return Effect.succeed(processOutput(`${input.command} version test\n`));
+      }
+      if (input.command === "gh" && input.args.join(" ") === "auth status") {
+        return Effect.succeed(
+          processOutput(`github.com
+Logged in to github.com account octocat (keyring)
+- Token: gho_************************************
+- Token scopes: 'repo'
+`),
+        );
+      }
+      if (input.command === "glab" && input.args.join(" ") === "auth status") {
+        return Effect.succeed(
+          processOutput(`gitlab.com
+Logged in to gitlab.com as gitlab-user
+`),
+        );
+      }
+      if (
+        input.command === "az" &&
+        input.args.join(" ") === "account show --query user.name -o tsv"
+      ) {
+        return Effect.succeed(processOutput("azure-user@example.com\n"));
+      }
+      return Effect.fail(
+        new VcsProcessSpawnError({
+          operation: input.operation,
+          command: input.command,
+          cwd: input.cwd,
+          cause: new Error(`${input.command} not found`),
+        }),
+      );
+    },
+  } satisfies Partial<VcsProcess.VcsProcessShape>;
+  const testLayer = SourceControlDiscovery.layer.pipe(
+    Layer.provide(
+      ServerConfig.layerTest(process.cwd(), { prefix: "t3-source-control-auth-discovery-" }),
+    ),
+    Layer.provide(Layer.mock(VcsProcess.VcsProcess)(processMock)),
+    Layer.provide(
+      sourceControlProviderRegistryTestLayer({
+        process: processMock,
+        bitbucket: {
+          probeAuth: Effect.succeed({
+            status: "authenticated",
+            account: Option.some("bitbucket-user"),
+            host: Option.some("bitbucket.org"),
+            detail: Option.none(),
+          }),
+        },
+      }),
+    ),
+    Layer.provideMerge(NodeServices.layer),
+  );
+
+  return Effect.gen(function* () {
+    const discovery = yield* SourceControlDiscovery.SourceControlDiscovery;
+    const result = yield* discovery.discover;
+
+    assert.deepStrictEqual(
+      result.sourceControlProviders.map((item) => ({
+        kind: item.kind,
+        auth: item.auth.status,
+        account: item.auth.account,
+        detail: item.auth.detail,
+      })),
+      [
+        {
+          kind: "github",
+          auth: "authenticated",
+          account: Option.some("octocat"),
+          detail: Option.none(),
+        },
+        {
+          kind: "gitlab",
+          auth: "authenticated",
+          account: Option.some("gitlab-user"),
+          detail: Option.none(),
+        },
+        {
+          kind: "azure-devops",
+          auth: "authenticated",
+          account: Option.some("azure-user@example.com"),
+          detail: Option.none(),
+        },
+        {
+          kind: "bitbucket",
+          auth: "authenticated",
+          account: Option.some("bitbucket-user"),
+          detail: Option.none(),
+        },
+      ],
+    );
+  }).pipe(Effect.provide(testLayer));
+});
diff --git a/apps/server/src/sourceControl/SourceControlDiscovery.ts b/apps/server/src/sourceControl/SourceControlDiscovery.ts
new file mode 100644
index 00000000000..6b00cf779fa
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlDiscovery.ts
@@ -0,0 +1,147 @@
+import {
+  type SourceControlDiscoveryResult,
+  type VcsDiscoveryItem,
+  type VcsDriverKind,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import { ServerConfig } from "../config.ts";
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as SourceControlProviderDiscovery from "./SourceControlProviderDiscovery.ts";
+import * as SourceControlProviderRegistry from "./SourceControlProviderRegistry.ts";
+
+interface DiscoveryProbe {
+  readonly label: string;
+  readonly executable?: string;
+  readonly versionArgs?: ReadonlyArray<string>;
+  readonly implemented: boolean;
+  readonly installHint: string;
+}
+
+type VcsProbe = DiscoveryProbe & {
+  readonly kind: VcsDriverKind;
+  readonly executable: string;
+  readonly versionArgs: ReadonlyArray<string>;
+};
+
+interface DiscoveryProbeResult<Kind extends string> {
+  readonly kind: Kind;
+  readonly label: string;
+  readonly executable?: string;
+  readonly implemented: boolean;
+  readonly status: "available" | "missing";
+  readonly version: Option.Option<string>;
+  readonly installHint: string;
+  readonly detail: Option.Option<string>;
+}
+
+const VCS_PROBES: ReadonlyArray<VcsProbe> = [
+  {
+    kind: "git",
+    label: "Git",
+    executable: "git",
+    versionArgs: ["--version"],
+    implemented: true,
+    installHint: "Install Git from https://git-scm.com/downloads or with your package manager.",
+  },
+  {
+    kind: "jj",
+    label: "Jujutsu",
+    executable: "jj",
+    versionArgs: ["--version"],
+    implemented: false,
+    installHint: "Install Jujutsu with `brew install jj` or from https://github.com/jj-vcs/jj.",
+  },
+];
+
+export interface SourceControlDiscoveryShape {
+  readonly discover: Effect.Effect<SourceControlDiscoveryResult>;
+}
+
+export class SourceControlDiscovery extends Context.Service<
+  SourceControlDiscovery,
+  SourceControlDiscoveryShape
+>()("t3/source-control/SourceControlDiscovery") {}
+
+export const layer = Layer.effect(
+  SourceControlDiscovery,
+  Effect.gen(function* () {
+    const config = yield* ServerConfig;
+    const process = yield* VcsProcess.VcsProcess;
+    const sourceControlProviders =
+      yield* SourceControlProviderRegistry.SourceControlProviderRegistry;
+
+    const probe = <Kind extends VcsDriverKind>(
+      input: DiscoveryProbe & { readonly kind: Kind },
+    ): Effect.Effect<DiscoveryProbeResult<Kind>> => {
+      const executable = input.executable;
+      const versionArgs = input.versionArgs;
+
+      if (!executable || !versionArgs) {
+        return Effect.succeed({
+          kind: input.kind,
+          label: input.label,
+          implemented: input.implemented,
+          status: "missing" as const,
+          version: Option.none<string>(),
+          installHint: input.installHint,
+          detail: Option.some(input.installHint),
+        } satisfies DiscoveryProbeResult<Kind>);
+      }
+
+      return process
+        .run({
+          operation: "source-control.discovery.probe",
+          command: executable,
+          args: versionArgs,
+          cwd: config.cwd,
+          timeoutMs: 5_000,
+          maxOutputBytes: 8_000,
+          appendTruncationMarker: true,
+        })
+        .pipe(
+          Effect.map(
+            (result) =>
+              ({
+                kind: input.kind,
+                label: input.label,
+                executable,
+                implemented: input.implemented,
+                status: "available" as const,
+                version: Option.orElse(
+                  SourceControlProviderDiscovery.firstNonEmptyLine(result.stdout),
+                  () => SourceControlProviderDiscovery.firstNonEmptyLine(result.stderr),
+                ),
+                installHint: input.installHint,
+                detail: Option.none<string>(),
+              }) satisfies DiscoveryProbeResult<Kind>,
+          ),
+          Effect.catch((cause) =>
+            Effect.succeed({
+              kind: input.kind,
+              label: input.label,
+              executable,
+              implemented: input.implemented,
+              status: "missing" as const,
+              version: Option.none<string>(),
+              installHint: input.installHint,
+              detail: SourceControlProviderDiscovery.detailFromCause(cause),
+            } satisfies DiscoveryProbeResult<Kind>),
+          ),
+        );
+    };
+
+    return SourceControlDiscovery.of({
+      discover: Effect.all({
+        versionControlSystems: Effect.all(
+          VCS_PROBES.map((entry) => probe(entry)) as ReadonlyArray<Effect.Effect<VcsDiscoveryItem>>,
+          { concurrency: "unbounded" },
+        ),
+        sourceControlProviders: sourceControlProviders.discover,
+      }),
+    });
+  }),
+);
diff --git a/apps/server/src/sourceControl/SourceControlProvider.ts b/apps/server/src/sourceControl/SourceControlProvider.ts
new file mode 100644
index 00000000000..a0465008212
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProvider.ts
@@ -0,0 +1,102 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type {
+  ChangeRequest,
+  ChangeRequestState,
+  SourceControlProviderError,
+  SourceControlProviderInfo,
+  SourceControlProviderKind,
+  SourceControlRepositoryCloneUrls,
+  SourceControlRepositoryVisibility,
+} from "@t3tools/contracts";
+
+export interface SourceControlProviderContext {
+  readonly provider: SourceControlProviderInfo;
+  readonly remoteName: string;
+  readonly remoteUrl: string;
+}
+
+export interface SourceControlRefSelector {
+  readonly refName: string;
+  readonly owner?: string;
+  readonly repository?: string;
+}
+
+export function parseSourceControlOwnerRef(
+  headSelector: string,
+): SourceControlRefSelector | undefined {
+  const match = /^([^:/\s]+):(.+)$/u.exec(headSelector.trim());
+  const owner = match?.[1]?.trim();
+  const refName = match?.[2]?.trim();
+  return owner && refName ? { owner, refName } : undefined;
+}
+
+export function normalizeSourceBranch(headSelector: string): string {
+  return parseSourceControlOwnerRef(headSelector)?.refName ?? headSelector.trim();
+}
+
+export function sourceBranch(input: {
+  readonly headSelector: string;
+  readonly source?: SourceControlRefSelector;
+}): string {
+  return input.source?.refName ?? normalizeSourceBranch(input.headSelector);
+}
+
+export function sourceControlRefFromInput(input: {
+  readonly headSelector: string;
+  readonly source?: SourceControlRefSelector;
+}): SourceControlRefSelector | undefined {
+  return input.source ?? parseSourceControlOwnerRef(input.headSelector);
+}
+
+export interface SourceControlProviderShape {
+  readonly kind: SourceControlProviderKind;
+  readonly listChangeRequests: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProviderContext;
+    readonly source?: SourceControlRefSelector;
+    readonly headSelector: string;
+    readonly state: ChangeRequestState | "all";
+    readonly limit?: number;
+  }) => Effect.Effect<ReadonlyArray<ChangeRequest>, SourceControlProviderError>;
+  readonly getChangeRequest: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProviderContext;
+    readonly reference: string;
+  }) => Effect.Effect<ChangeRequest, SourceControlProviderError>;
+  readonly createChangeRequest: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProviderContext;
+    readonly source?: SourceControlRefSelector;
+    readonly target?: SourceControlRefSelector;
+    readonly baseRefName: string;
+    readonly headSelector: string;
+    readonly title: string;
+    readonly bodyFile: string;
+  }) => Effect.Effect<void, SourceControlProviderError>;
+  readonly getRepositoryCloneUrls: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProviderContext;
+    readonly repository: string;
+  }) => Effect.Effect<SourceControlRepositoryCloneUrls, SourceControlProviderError>;
+  readonly createRepository: (input: {
+    readonly cwd: string;
+    readonly repository: string;
+    readonly visibility: SourceControlRepositoryVisibility;
+  }) => Effect.Effect<SourceControlRepositoryCloneUrls, SourceControlProviderError>;
+  readonly getDefaultBranch: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProviderContext;
+  }) => Effect.Effect<string | null, SourceControlProviderError>;
+  readonly checkoutChangeRequest: (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProviderContext;
+    readonly reference: string;
+    readonly force?: boolean;
+  }) => Effect.Effect<void, SourceControlProviderError>;
+}
+
+export class SourceControlProvider extends Context.Service<
+  SourceControlProvider,
+  SourceControlProviderShape
+>()("t3/source-control/SourceControlProvider") {}
diff --git a/apps/server/src/sourceControl/SourceControlProviderDiscovery.ts b/apps/server/src/sourceControl/SourceControlProviderDiscovery.ts
new file mode 100644
index 00000000000..23bbada043a
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProviderDiscovery.ts
@@ -0,0 +1,238 @@
+import type {
+  SourceControlProviderAuth,
+  SourceControlProviderDiscoveryItem,
+  SourceControlProviderKind,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+
+import type * as VcsProcess from "../vcs/VcsProcess.ts";
+
+export interface SourceControlAuthProbeInput {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: VcsProcess.VcsProcessOutput["exitCode"];
+}
+
+interface SourceControlDiscoverySpecBase {
+  readonly kind: SourceControlProviderKind;
+  readonly label: string;
+  readonly installHint: string;
+}
+
+export type SourceControlCliDiscoverySpec = SourceControlDiscoverySpecBase & {
+  readonly type: "cli";
+  readonly executable: string;
+  readonly versionArgs: ReadonlyArray<string>;
+  readonly authArgs: ReadonlyArray<string>;
+  readonly parseAuth: (input: SourceControlAuthProbeInput) => SourceControlProviderAuth;
+};
+
+export type SourceControlApiDiscoverySpec = SourceControlDiscoverySpecBase & {
+  readonly type: "api";
+  readonly probeAuth: Effect.Effect<SourceControlProviderAuth, never>;
+};
+
+export type SourceControlProviderDiscoverySpec =
+  | SourceControlCliDiscoverySpec
+  | SourceControlApiDiscoverySpec;
+
+interface DiscoveryProbeResult {
+  readonly kind: SourceControlProviderKind;
+  readonly label: string;
+  readonly executable: string;
+  readonly status: "available" | "missing";
+  readonly version: Option.Option<string>;
+  readonly installHint: string;
+  readonly detail: Option.Option<string>;
+}
+
+export function firstNonEmptyLine(text: string): Option.Option<string> {
+  const line = text
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .find((entry) => entry.length > 0);
+  return line === undefined ? Option.none() : Option.some(line);
+}
+
+export function detailFromCause(cause: unknown): Option.Option<string> {
+  if (cause instanceof Error && cause.message.trim().length > 0) {
+    return Option.some(cause.message.trim());
+  }
+  return Option.none();
+}
+
+function authAccount(account: string | undefined): Option.Option<string> {
+  const trimmed = account?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? Option.none() : Option.some(trimmed);
+}
+
+function authHost(host: string | undefined): Option.Option<string> {
+  const trimmed = host?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? Option.none() : Option.some(trimmed);
+}
+
+function authDetail(detail: string | undefined): Option.Option<string> {
+  const trimmed = detail?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? Option.none() : Option.some(trimmed);
+}
+
+export function providerAuth(input: {
+  readonly status: SourceControlProviderAuth["status"];
+  readonly account?: string | undefined;
+  readonly host?: string | undefined;
+  readonly detail?: string | undefined;
+}): SourceControlProviderAuth {
+  return {
+    status: input.status,
+    account: authAccount(input.account),
+    host: authHost(input.host),
+    detail: authDetail(input.detail),
+  };
+}
+
+export function unknownAuth(detail?: string): SourceControlProviderAuth {
+  return providerAuth({ status: "unknown", detail });
+}
+
+export function combinedAuthOutput(input: SourceControlAuthProbeInput): string {
+  return [input.stdout, input.stderr].filter((entry) => entry.trim().length > 0).join("\n");
+}
+
+function sanitizedAuthLines(text: string): ReadonlyArray<string> {
+  return text
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .filter((entry) => !/^[-\s]*token(?:\s+scopes?)?:/iu.test(entry));
+}
+
+export function firstSafeAuthLine(text: string): string | undefined {
+  return sanitizedAuthLines(text)[0];
+}
+
+export function parseCliHost(text: string): string | undefined {
+  return sanitizedAuthLines(text)
+    .map((line) => line.replace(/^[^a-z0-9]+/iu, ""))
+    .find((line) => /^[a-z0-9][a-z0-9.-]*(?::\d+)?$/iu.test(line));
+}
+
+export function matchFirst(text: string, patterns: ReadonlyArray<RegExp>): string | undefined {
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    const value = match?.[1]?.trim();
+    if (value && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+function probeCli(input: {
+  readonly spec: SourceControlCliDiscoverySpec;
+  readonly process: VcsProcess.VcsProcessShape;
+  readonly cwd: string;
+}): Effect.Effect<DiscoveryProbeResult> {
+  return input.process
+    .run({
+      operation: "source-control.discovery.probe",
+      command: input.spec.executable,
+      args: input.spec.versionArgs,
+      cwd: input.cwd,
+      timeoutMs: 5_000,
+      maxOutputBytes: 8_000,
+      appendTruncationMarker: true,
+    })
+    .pipe(
+      Effect.map(
+        (result) =>
+          ({
+            kind: input.spec.kind,
+            label: input.spec.label,
+            executable: input.spec.executable,
+            status: "available" as const,
+            version: Option.orElse(firstNonEmptyLine(result.stdout), () =>
+              firstNonEmptyLine(result.stderr),
+            ),
+            installHint: input.spec.installHint,
+            detail: Option.none<string>(),
+          }) satisfies DiscoveryProbeResult,
+      ),
+      Effect.catch((cause) =>
+        Effect.succeed({
+          kind: input.spec.kind,
+          label: input.spec.label,
+          executable: input.spec.executable,
+          status: "missing" as const,
+          version: Option.none<string>(),
+          installHint: input.spec.installHint,
+          detail: detailFromCause(cause),
+        } satisfies DiscoveryProbeResult),
+      ),
+    );
+}
+
+export function probeSourceControlProvider(input: {
+  readonly spec: SourceControlProviderDiscoverySpec;
+  readonly process: VcsProcess.VcsProcessShape;
+  readonly cwd: string;
+}): Effect.Effect<SourceControlProviderDiscoveryItem> {
+  if (input.spec.type === "api") {
+    return input.spec.probeAuth.pipe(
+      Effect.map(
+        (auth) =>
+          ({
+            kind: input.spec.kind,
+            label: input.spec.label,
+            status: "available" as const,
+            version: Option.none<string>(),
+            installHint: input.spec.installHint,
+            detail: Option.none<string>(),
+            auth,
+          }) satisfies SourceControlProviderDiscoveryItem,
+      ),
+    );
+  }
+
+  const spec = input.spec;
+
+  return probeCli({
+    spec,
+    process: input.process,
+    cwd: input.cwd,
+  }).pipe(
+    Effect.flatMap((item) => {
+      if (item.status !== "available") {
+        return Effect.succeed({
+          ...item,
+          auth: unknownAuth("Hosting integration command was not found on the server PATH."),
+        } satisfies SourceControlProviderDiscoveryItem);
+      }
+
+      return input.process
+        .run({
+          operation: "source-control.discovery.auth",
+          command: spec.executable,
+          args: spec.authArgs,
+          cwd: input.cwd,
+          allowNonZeroExit: true,
+          timeoutMs: 5_000,
+          maxOutputBytes: 8_000,
+          appendTruncationMarker: true,
+        })
+        .pipe(
+          Effect.map(
+            (result) =>
+              ({
+                ...item,
+                auth: spec.parseAuth(result),
+              }) satisfies SourceControlProviderDiscoveryItem,
+          ),
+          Effect.catch((cause) =>
+            Effect.succeed({
+              ...item,
+              auth: unknownAuth(Option.getOrUndefined(detailFromCause(cause))),
+            } satisfies SourceControlProviderDiscoveryItem),
+          ),
+        );
+    }),
+  );
+}
diff --git a/apps/server/src/sourceControl/SourceControlProviderRegistry.test.ts b/apps/server/src/sourceControl/SourceControlProviderRegistry.test.ts
new file mode 100644
index 00000000000..829f6be1eb9
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProviderRegistry.test.ts
@@ -0,0 +1,148 @@
+import { assert, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+
+import { ServerConfig } from "../config.ts";
+import type * as VcsDriver from "../vcs/VcsDriver.ts";
+import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+import * as AzureDevOpsCli from "./AzureDevOpsCli.ts";
+import * as BitbucketApi from "./BitbucketApi.ts";
+import * as GitHubCli from "./GitHubCli.ts";
+import * as GitLabCli from "./GitLabCli.ts";
+import * as SourceControlProviderRegistry from "./SourceControlProviderRegistry.ts";
+
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
+
+function makeRegistry(input: {
+  readonly remotes: ReadonlyArray<{
+    readonly name: string;
+    readonly url: string;
+  }>;
+}) {
+  const driver = {
+    listRemotes: () =>
+      Effect.succeed({
+        remotes: input.remotes.map((remote) => ({
+          ...remote,
+          pushUrl: Option.none(),
+          isPrimary: remote.name === "origin",
+        })),
+        freshness: {
+          source: "live-local" as const,
+          observedAt: TEST_EPOCH,
+          expiresAt: Option.none(),
+        },
+      }),
+  } satisfies Partial<VcsDriver.VcsDriverShape>;
+
+  const registryLayer = Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
+    get: () => Effect.succeed(driver as unknown as VcsDriver.VcsDriverShape),
+    resolve: () =>
+      Effect.succeed({
+        kind: "git",
+        repository: {
+          kind: "git",
+          rootPath: "/repo",
+          metadataPath: null,
+          freshness: {
+            source: "live-local" as const,
+            observedAt: TEST_EPOCH,
+            expiresAt: Option.none(),
+          },
+        },
+        driver: driver as unknown as VcsDriver.VcsDriverShape,
+      }),
+  });
+
+  return SourceControlProviderRegistry.make().pipe(
+    Effect.provide(
+      Layer.mergeAll(
+        registryLayer,
+        Layer.mock(AzureDevOpsCli.AzureDevOpsCli)({}),
+        Layer.mock(BitbucketApi.BitbucketApi)({}),
+        Layer.mock(GitHubCli.GitHubCli)({}),
+        Layer.mock(GitLabCli.GitLabCli)({}),
+        Layer.mock(VcsProcess.VcsProcess)({}),
+        ServerConfig.layerTest(process.cwd(), { prefix: "t3-source-control-registry-test-" }).pipe(
+          Layer.provide(NodeServices.layer),
+        ),
+      ),
+    ),
+  );
+}
+
+it.effect("routes GitHub remotes to the GitHub provider", () =>
+  Effect.gen(function* () {
+    const registry = yield* makeRegistry({
+      remotes: [{ name: "origin", url: "git@github.com:pingdotgg/t3code.git" }],
+    });
+
+    const provider = yield* registry.resolve({ cwd: "/repo" });
+
+    assert.strictEqual(provider.kind, "github");
+  }),
+);
+
+it.effect("routes directly by provider kind for remote-first workflows", () =>
+  Effect.gen(function* () {
+    const registry = yield* makeRegistry({
+      remotes: [],
+    });
+
+    const provider = yield* registry.get("github");
+
+    assert.strictEqual(provider.kind, "github");
+  }),
+);
+
+it.effect("routes GitLab remotes to the GitLab provider", () =>
+  Effect.gen(function* () {
+    const registry = yield* makeRegistry({
+      remotes: [{ name: "origin", url: "git@gitlab.com:group/project.git" }],
+    });
+
+    const provider = yield* registry.resolve({ cwd: "/repo" });
+
+    assert.strictEqual(provider.kind, "gitlab");
+  }),
+);
+
+it.effect("routes Bitbucket remotes to the Bitbucket provider", () =>
+  Effect.gen(function* () {
+    const registry = yield* makeRegistry({
+      remotes: [{ name: "origin", url: "git@bitbucket.org:pingdotgg/t3code.git" }],
+    });
+
+    const provider = yield* registry.resolve({ cwd: "/repo" });
+
+    assert.strictEqual(provider.kind, "bitbucket");
+  }),
+);
+
+it.effect("routes Azure DevOps remotes to the Azure DevOps provider", () =>
+  Effect.gen(function* () {
+    const registry = yield* makeRegistry({
+      remotes: [{ name: "origin", url: "https://dev.azure.com/acme/project/_git/repo" }],
+    });
+
+    const provider = yield* registry.resolve({ cwd: "/repo" });
+
+    assert.strictEqual(provider.kind, "azure-devops");
+  }),
+);
+
+it.effect("falls back to a non-origin remote when origin is not configured", () =>
+  Effect.gen(function* () {
+    const registry = yield* makeRegistry({
+      remotes: [{ name: "upstream", url: "https://dev.azure.com/acme/project/_git/repo" }],
+    });
+
+    const provider = yield* registry.resolve({ cwd: "/repo" });
+
+    assert.strictEqual(provider.kind, "azure-devops");
+  }),
+);
diff --git a/apps/server/src/sourceControl/SourceControlProviderRegistry.ts b/apps/server/src/sourceControl/SourceControlProviderRegistry.ts
new file mode 100644
index 00000000000..28826e764b0
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProviderRegistry.ts
@@ -0,0 +1,256 @@
+import * as Cache from "effect/Cache";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import {
+  SourceControlProviderError,
+  type SourceControlProviderDiscoveryItem,
+} from "@t3tools/contracts";
+import type { SourceControlProviderKind } from "@t3tools/contracts";
+import { detectSourceControlProviderFromRemoteUrl } from "@t3tools/shared/sourceControl";
+
+import * as AzureDevOpsSourceControlProvider from "./AzureDevOpsSourceControlProvider.ts";
+import * as BitbucketSourceControlProvider from "./BitbucketSourceControlProvider.ts";
+import * as GitHubSourceControlProvider from "./GitHubSourceControlProvider.ts";
+import * as GitLabSourceControlProvider from "./GitLabSourceControlProvider.ts";
+import * as SourceControlProvider from "./SourceControlProvider.ts";
+import * as SourceControlProviderDiscovery from "./SourceControlProviderDiscovery.ts";
+import { ServerConfig } from "../config.ts";
+import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../vcs/VcsProcess.ts";
+
+const PROVIDER_DETECTION_CACHE_CAPACITY = 2_048;
+const PROVIDER_DETECTION_CACHE_TTL = Duration.seconds(5);
+
+export interface SourceControlProviderRegistration {
+  readonly kind: SourceControlProviderKind;
+  readonly provider: SourceControlProvider.SourceControlProviderShape;
+  readonly discovery: SourceControlProviderDiscovery.SourceControlProviderDiscoverySpec;
+}
+
+export interface SourceControlProviderHandle {
+  readonly provider: SourceControlProvider.SourceControlProviderShape;
+  readonly context: SourceControlProvider.SourceControlProviderContext | null;
+}
+
+export interface SourceControlProviderRegistryShape {
+  readonly get: (
+    kind: SourceControlProviderKind,
+  ) => Effect.Effect<SourceControlProvider.SourceControlProviderShape, SourceControlProviderError>;
+  readonly resolveHandle: (input: {
+    readonly cwd: string;
+  }) => Effect.Effect<SourceControlProviderHandle, SourceControlProviderError>;
+  readonly resolve: (input: {
+    readonly cwd: string;
+  }) => Effect.Effect<SourceControlProvider.SourceControlProviderShape, SourceControlProviderError>;
+  readonly discover: Effect.Effect<ReadonlyArray<SourceControlProviderDiscoveryItem>>;
+}
+
+export class SourceControlProviderRegistry extends Context.Service<
+  SourceControlProviderRegistry,
+  SourceControlProviderRegistryShape
+>()("t3/source-control/SourceControlProviderRegistry") {}
+
+function unsupportedProvider(
+  kind: SourceControlProviderKind,
+): SourceControlProvider.SourceControlProviderShape {
+  const unsupported = (operation: string) =>
+    Effect.fail(
+      new SourceControlProviderError({
+        provider: kind,
+        operation,
+        detail: `No ${kind} source control provider is registered.`,
+      }),
+    );
+
+  return SourceControlProvider.SourceControlProvider.of({
+    kind,
+    listChangeRequests: () => unsupported("listChangeRequests"),
+    getChangeRequest: () => unsupported("getChangeRequest"),
+    createChangeRequest: () => unsupported("createChangeRequest"),
+    getRepositoryCloneUrls: () => unsupported("getRepositoryCloneUrls"),
+    createRepository: () => unsupported("createRepository"),
+    getDefaultBranch: () => unsupported("getDefaultBranch"),
+    checkoutChangeRequest: () => unsupported("checkoutChangeRequest"),
+  });
+}
+
+function providerDetectionError(operation: string, cwd: string, cause: unknown) {
+  return new SourceControlProviderError({
+    provider: "unknown",
+    operation,
+    detail: `Failed to detect source control provider for ${cwd}.`,
+    cause,
+  });
+}
+
+function selectProviderContext(
+  remotes: ReadonlyArray<{
+    readonly name: string;
+    readonly url: string;
+  }>,
+): SourceControlProvider.SourceControlProviderContext | null {
+  const candidates = remotes
+    .map((remote) => {
+      const provider = detectSourceControlProviderFromRemoteUrl(remote.url);
+      return provider
+        ? {
+            provider,
+            remoteName: remote.name,
+            remoteUrl: remote.url,
+          }
+        : null;
+    })
+    .filter((value): value is SourceControlProvider.SourceControlProviderContext => value !== null);
+
+  return (
+    candidates.find((candidate) => candidate.remoteName === "origin") ??
+    candidates.find((candidate) => candidate.provider.kind !== "unknown") ??
+    candidates[0] ??
+    null
+  );
+}
+
+function bindProviderContext(
+  provider: SourceControlProvider.SourceControlProviderShape,
+  context: SourceControlProvider.SourceControlProviderContext | null,
+): SourceControlProvider.SourceControlProviderShape {
+  if (context === null) {
+    return provider;
+  }
+
+  return SourceControlProvider.SourceControlProvider.of({
+    kind: provider.kind,
+    listChangeRequests: (input) =>
+      provider.listChangeRequests({
+        ...input,
+        context: input.context ?? context,
+      }),
+    getChangeRequest: (input) =>
+      provider.getChangeRequest({
+        ...input,
+        context: input.context ?? context,
+      }),
+    createChangeRequest: (input) =>
+      provider.createChangeRequest({
+        ...input,
+        context: input.context ?? context,
+      }),
+    getRepositoryCloneUrls: (input) =>
+      provider.getRepositoryCloneUrls({
+        ...input,
+        context: input.context ?? context,
+      }),
+    createRepository: (input) => provider.createRepository(input),
+    getDefaultBranch: (input) =>
+      provider.getDefaultBranch({
+        ...input,
+        context: input.context ?? context,
+      }),
+    checkoutChangeRequest: (input) =>
+      provider.checkoutChangeRequest({
+        ...input,
+        context: input.context ?? context,
+      }),
+  });
+}
+
+export const makeWithProviders = Effect.fn("makeSourceControlProviderRegistryWithProviders")(
+  function* (registrations: ReadonlyArray<SourceControlProviderRegistration>) {
+    const config = yield* ServerConfig;
+    const process = yield* VcsProcess.VcsProcess;
+    const vcsRegistry = yield* VcsDriverRegistry.VcsDriverRegistry;
+    const providers = new Map<
+      SourceControlProviderKind,
+      SourceControlProvider.SourceControlProviderShape
+    >(registrations.map((registration) => [registration.kind, registration.provider]));
+    const discoverySpecs = registrations.map((registration) => registration.discovery);
+
+    const get: SourceControlProviderRegistryShape["get"] = (kind) =>
+      Effect.succeed(providers.get(kind) ?? unsupportedProvider(kind));
+
+    const detectProviderContext = Effect.fn("SourceControlProviderRegistry.detectProviderContext")(
+      function* (cwd: string) {
+        const handle = yield* vcsRegistry
+          .resolve({ cwd })
+          .pipe(Effect.mapError((error) => providerDetectionError("detectProvider", cwd, error)));
+        const remotes = yield* handle.driver
+          .listRemotes(cwd)
+          .pipe(Effect.mapError((error) => providerDetectionError("detectProvider", cwd, error)));
+
+        return selectProviderContext(remotes.remotes);
+      },
+    );
+
+    const providerContextCache = yield* Cache.makeWith<
+      string,
+      SourceControlProvider.SourceControlProviderContext | null,
+      SourceControlProviderError
+    >(detectProviderContext, {
+      capacity: PROVIDER_DETECTION_CACHE_CAPACITY,
+      timeToLive: (exit) => (Exit.isSuccess(exit) ? PROVIDER_DETECTION_CACHE_TTL : Duration.zero),
+    });
+
+    const resolveHandle: SourceControlProviderRegistryShape["resolveHandle"] = (input) =>
+      Cache.get(providerContextCache, input.cwd).pipe(
+        Effect.map((context) => {
+          const kind = context?.provider.kind ?? "unknown";
+          const provider = providers.get(kind) ?? unsupportedProvider(kind);
+          return {
+            provider: bindProviderContext(provider, context),
+            context,
+          } satisfies SourceControlProviderHandle;
+        }),
+      );
+
+    return SourceControlProviderRegistry.of({
+      get,
+      resolveHandle,
+      resolve: (input) => resolveHandle(input).pipe(Effect.map((handle) => handle.provider)),
+      discover: Effect.all(
+        discoverySpecs.map((spec) =>
+          SourceControlProviderDiscovery.probeSourceControlProvider({
+            spec,
+            process,
+            cwd: config.cwd,
+          }),
+        ),
+        { concurrency: "unbounded" },
+      ),
+    });
+  },
+);
+
+export const make = Effect.fn("makeSourceControlProviderRegistry")(function* () {
+  const github = yield* GitHubSourceControlProvider.make();
+  const gitlab = yield* GitLabSourceControlProvider.make();
+  const bitbucket = yield* BitbucketSourceControlProvider.make();
+  const bitbucketDiscovery = yield* BitbucketSourceControlProvider.makeDiscovery();
+  const azureDevOps = yield* AzureDevOpsSourceControlProvider.make();
+  return yield* makeWithProviders([
+    {
+      kind: "github",
+      provider: github,
+      discovery: GitHubSourceControlProvider.discovery,
+    },
+    {
+      kind: "gitlab",
+      provider: gitlab,
+      discovery: GitLabSourceControlProvider.discovery,
+    },
+    {
+      kind: "azure-devops",
+      provider: azureDevOps,
+      discovery: AzureDevOpsSourceControlProvider.discovery,
+    },
+    {
+      kind: "bitbucket",
+      provider: bitbucket,
+      discovery: bitbucketDiscovery,
+    },
+  ]);
+});
+
+export const layer = Layer.effect(SourceControlProviderRegistry, make());
diff --git a/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts b/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
new file mode 100644
index 00000000000..811b55c70a3
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
@@ -0,0 +1,320 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { GitCommandError, type SourceControlProviderError } from "@t3tools/contracts";
+
+import { ServerConfig } from "../config.ts";
+import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
+import type * as SourceControlProvider from "./SourceControlProvider.ts";
+import * as SourceControlProviderRegistry from "./SourceControlProviderRegistry.ts";
+import * as SourceControlRepositoryService from "./SourceControlRepositoryService.ts";
+
+const CLONE_URLS = {
+  nameWithOwner: "octocat/t3code",
+  url: "https://github.com/octocat/t3code",
+  sshUrl: "git@github.com:octocat/t3code.git",
+};
+
+function makeProvider(
+  overrides: Partial<SourceControlProvider.SourceControlProviderShape> = {},
+): SourceControlProvider.SourceControlProviderShape {
+  const unsupported = (operation: string) =>
+    Effect.die(`unexpected provider operation ${operation}`) as Effect.Effect<
+      never,
+      SourceControlProviderError
+    >;
+
+  return {
+    kind: "github",
+    listChangeRequests: () => unsupported("listChangeRequests"),
+    getChangeRequest: () => unsupported("getChangeRequest"),
+    createChangeRequest: () => unsupported("createChangeRequest"),
+    getRepositoryCloneUrls: () => Effect.succeed(CLONE_URLS),
+    createRepository: () => Effect.succeed(CLONE_URLS),
+    getDefaultBranch: () => Effect.succeed(null),
+    checkoutChangeRequest: () => unsupported("checkoutChangeRequest"),
+    ...overrides,
+  };
+}
+
+function processOutput(): GitVcsDriver.ExecuteGitResult {
+  return {
+    exitCode: ChildProcessSpawner.ExitCode(0),
+    stdout: "",
+    stderr: "",
+    stdoutTruncated: false,
+    stderrTruncated: false,
+  };
+}
+
+function makeLayer(input: {
+  readonly provider?: SourceControlProvider.SourceControlProviderShape;
+  readonly git?: Partial<GitVcsDriver.GitVcsDriverShape>;
+}) {
+  return SourceControlRepositoryService.layer.pipe(
+    Layer.provide(
+      Layer.mock(SourceControlProviderRegistry.SourceControlProviderRegistry)({
+        get: () => Effect.succeed(input.provider ?? makeProvider()),
+      }),
+    ),
+    Layer.provide(
+      Layer.mock(GitVcsDriver.GitVcsDriver)({
+        execute: () => Effect.succeed(processOutput()),
+        ensureRemote: () => Effect.succeed("origin"),
+        pushCurrentBranch: () =>
+          Effect.succeed({
+            status: "pushed" as const,
+            branch: "feature/remote-v1",
+            upstreamBranch: "origin/feature/remote-v1",
+            setUpstream: true,
+          }),
+        ...input.git,
+      }),
+    ),
+    Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "t3-source-control-repos-" })),
+    Layer.provideMerge(NodeServices.layer),
+  );
+}
+
+it.effect("looks up repositories through the requested provider without search", () => {
+  const calls: Array<{ cwd: string; repository: string }> = [];
+  const provider = makeProvider({
+    getRepositoryCloneUrls: (input) =>
+      Effect.sync(() => {
+        calls.push({ cwd: input.cwd, repository: input.repository });
+        return CLONE_URLS;
+      }),
+  });
+
+  return Effect.gen(function* () {
+    const service = yield* SourceControlRepositoryService.SourceControlRepositoryService;
+    const result = yield* service.lookupRepository({
+      provider: "github",
+      repository: "octocat/t3code",
+      cwd: "/workspace",
+    });
+
+    assert.deepStrictEqual(result, { provider: "github", ...CLONE_URLS });
+    assert.deepStrictEqual(calls, [{ cwd: "/workspace", repository: "octocat/t3code" }]);
+  }).pipe(Effect.provide(makeLayer({ provider })));
+});
+
+it.effect("clones a looked-up repository into the requested destination", () =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const parent = yield* fs.makeTempDirectoryScoped({
+      prefix: "t3-source-control-clone-parent-",
+    });
+    const destinationPath = `${parent}/t3code`;
+    const cloneCalls: Array<{ cwd: string; args: ReadonlyArray<string> }> = [];
+
+    yield* Effect.gen(function* () {
+      const service = yield* SourceControlRepositoryService.SourceControlRepositoryService;
+      const result = yield* service.cloneRepository({
+        provider: "github",
+        repository: "octocat/t3code",
+        destinationPath,
+        protocol: "https",
+      });
+
+      assert.deepStrictEqual(result, {
+        cwd: destinationPath,
+        remoteUrl: CLONE_URLS.url,
+        repository: { provider: "github", ...CLONE_URLS },
+      });
+      assert.deepStrictEqual(cloneCalls, [
+        {
+          cwd: parent,
+          args: ["clone", CLONE_URLS.url, "t3code"],
+        },
+      ]);
+    }).pipe(
+      Effect.provide(
+        makeLayer({
+          git: {
+            execute: (input) =>
+              Effect.sync(() => {
+                cloneCalls.push({ cwd: input.cwd, args: input.args });
+                return processOutput();
+              }),
+          },
+        }),
+      ),
+    );
+  }).pipe(Effect.provide(NodeServices.layer)),
+);
+
+it.effect("publishes by creating the repository, adding a remote, and pushing upstream", () => {
+  const createCalls: Array<{ cwd: string; repository: string; visibility: string }> = [];
+  const remoteCalls: Array<{ cwd: string; preferredName: string; url: string }> = [];
+  const pushCalls: Array<{ cwd: string; remoteName: string | null | undefined }> = [];
+  const provider = makeProvider({
+    createRepository: (input) =>
+      Effect.sync(() => {
+        createCalls.push({
+          cwd: input.cwd,
+          repository: input.repository,
+          visibility: input.visibility,
+        });
+        return CLONE_URLS;
+      }),
+  });
+
+  return Effect.gen(function* () {
+    const service = yield* SourceControlRepositoryService.SourceControlRepositoryService;
+    const result = yield* service.publishRepository({
+      cwd: "/workspace",
+      provider: "github",
+      repository: "octocat/t3code",
+      visibility: "private",
+      remoteName: "origin",
+      protocol: "ssh",
+    });
+
+    assert.deepStrictEqual(result, {
+      repository: { provider: "github", ...CLONE_URLS },
+      remoteName: "origin",
+      remoteUrl: CLONE_URLS.sshUrl,
+      branch: "feature/remote-v1",
+      upstreamBranch: "origin/feature/remote-v1",
+      status: "pushed",
+    });
+    assert.deepStrictEqual(createCalls, [
+      { cwd: "/workspace", repository: "octocat/t3code", visibility: "private" },
+    ]);
+    assert.deepStrictEqual(remoteCalls, [
+      { cwd: "/workspace", preferredName: "origin", url: CLONE_URLS.sshUrl },
+    ]);
+    assert.deepStrictEqual(pushCalls, [{ cwd: "/workspace", remoteName: "origin" }]);
+  }).pipe(
+    Effect.provide(
+      makeLayer({
+        provider,
+        git: {
+          ensureRemote: (input) =>
+            Effect.sync(() => {
+              remoteCalls.push(input);
+              return "origin";
+            }),
+          pushCurrentBranch: (cwd, _fallbackBranch, options) =>
+            Effect.sync(() => {
+              pushCalls.push({ cwd, remoteName: options?.remoteName });
+              return {
+                status: "pushed" as const,
+                branch: "feature/remote-v1",
+                upstreamBranch: "origin/feature/remote-v1",
+                setUpstream: true,
+              };
+            }),
+        },
+      }),
+    ),
+  );
+});
+
+it.effect("publishes to the remote name returned by ensureRemote", () => {
+  const pushCalls: Array<{ cwd: string; remoteName: string | null | undefined }> = [];
+
+  return Effect.gen(function* () {
+    const service = yield* SourceControlRepositoryService.SourceControlRepositoryService;
+    const result = yield* service.publishRepository({
+      cwd: "/workspace",
+      provider: "github",
+      repository: "octocat/t3code",
+      visibility: "private",
+      remoteName: "origin",
+      protocol: "ssh",
+    });
+
+    assert.equal(result.remoteName, "origin-1");
+    assert.deepStrictEqual(pushCalls, [{ cwd: "/workspace", remoteName: "origin-1" }]);
+  }).pipe(
+    Effect.provide(
+      makeLayer({
+        git: {
+          ensureRemote: () => Effect.succeed("origin-1"),
+          pushCurrentBranch: (cwd, _fallbackBranch, options) =>
+            Effect.sync(() => {
+              pushCalls.push({ cwd, remoteName: options?.remoteName });
+              return {
+                status: "pushed" as const,
+                branch: "feature/remote-v1",
+                upstreamBranch: `${options?.remoteName ?? "missing"}/feature/remote-v1`,
+                setUpstream: true,
+              };
+            }),
+        },
+      }),
+    ),
+  );
+});
+
+it.effect("publish succeeds with status remote_added when the local repo has no commits", () => {
+  let pushCalls = 0;
+  return Effect.gen(function* () {
+    const service = yield* SourceControlRepositoryService.SourceControlRepositoryService;
+    const result = yield* service.publishRepository({
+      cwd: "/workspace",
+      provider: "github",
+      repository: "octocat/t3code",
+      visibility: "private",
+      remoteName: "origin",
+      protocol: "ssh",
+    });
+
+    assert.deepStrictEqual(result, {
+      repository: { provider: "github", ...CLONE_URLS },
+      remoteName: "origin",
+      remoteUrl: CLONE_URLS.sshUrl,
+      branch: "main",
+      status: "remote_added",
+    });
+    assert.strictEqual(pushCalls, 0);
+  }).pipe(
+    Effect.provide(
+      makeLayer({
+        git: {
+          execute: (input) =>
+            input.args[0] === "rev-parse"
+              ? Effect.fail(
+                  new GitCommandError({
+                    operation: input.operation,
+                    command: "git rev-parse --verify HEAD",
+                    cwd: input.cwd,
+                    detail: "fatal: Needed a single revision",
+                  }),
+                )
+              : Effect.succeed(processOutput()),
+          statusDetails: () =>
+            Effect.succeed({
+              isRepo: true,
+              hasOriginRemote: true,
+              isDefaultBranch: true,
+              branch: "main",
+              upstreamRef: null,
+              hasWorkingTreeChanges: false,
+              workingTree: { files: [], insertions: 0, deletions: 0 },
+              hasUpstream: false,
+              aheadCount: 0,
+              behindCount: 0,
+              aheadOfDefaultCount: 0,
+            }),
+          pushCurrentBranch: () =>
+            Effect.sync(() => {
+              pushCalls += 1;
+              return {
+                status: "pushed" as const,
+                branch: "main",
+                upstreamBranch: "origin/main",
+                setUpstream: true,
+              };
+            }),
+        },
+      }),
+    ),
+  );
+});
diff --git a/apps/server/src/sourceControl/SourceControlRepositoryService.ts b/apps/server/src/sourceControl/SourceControlRepositoryService.ts
new file mode 100644
index 00000000000..f1ee1940390
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlRepositoryService.ts
@@ -0,0 +1,320 @@
+import * as NodeOS from "node:os";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+import {
+  SourceControlRepositoryError,
+  type SourceControlCloneRepositoryInput,
+  type SourceControlCloneRepositoryResult,
+  type SourceControlCloneProtocol,
+  type SourceControlProviderKind,
+  type SourceControlPublishRepositoryInput,
+  type SourceControlPublishRepositoryResult,
+  type SourceControlRepositoryCloneUrls,
+  type SourceControlRepositoryInfo,
+  type SourceControlRepositoryLookupInput,
+} from "@t3tools/contracts";
+
+import { ServerConfig } from "../config.ts";
+import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
+import * as SourceControlProviderRegistry from "./SourceControlProviderRegistry.ts";
+const isSourceControlRepositoryError = Schema.is(SourceControlRepositoryError);
+
+export interface SourceControlRepositoryServiceShape {
+  readonly lookupRepository: (
+    input: SourceControlRepositoryLookupInput,
+  ) => Effect.Effect<SourceControlRepositoryInfo, SourceControlRepositoryError>;
+  readonly cloneRepository: (
+    input: SourceControlCloneRepositoryInput,
+  ) => Effect.Effect<SourceControlCloneRepositoryResult, SourceControlRepositoryError>;
+  readonly publishRepository: (
+    input: SourceControlPublishRepositoryInput,
+  ) => Effect.Effect<SourceControlPublishRepositoryResult, SourceControlRepositoryError>;
+}
+
+export class SourceControlRepositoryService extends Context.Service<
+  SourceControlRepositoryService,
+  SourceControlRepositoryServiceShape
+>()("t3/source-control/SourceControlRepositoryService") {}
+
+function detailFromUnknown(cause: unknown): string {
+  if (typeof cause === "object" && cause !== null) {
+    if ("detail" in cause && typeof cause.detail === "string" && cause.detail.length > 0) {
+      return cause.detail;
+    }
+    if ("message" in cause && typeof cause.message === "string" && cause.message.length > 0) {
+      return cause.message;
+    }
+  }
+
+  return "An unexpected source control error occurred.";
+}
+
+function repositoryError(input: {
+  readonly operation: string;
+  readonly provider: SourceControlProviderKind;
+  readonly detail: string;
+  readonly cause?: unknown;
+}): SourceControlRepositoryError {
+  return new SourceControlRepositoryError({
+    provider: input.provider,
+    operation: input.operation,
+    detail: input.detail,
+    ...(input.cause === undefined ? {} : { cause: input.cause }),
+  });
+}
+
+function mapRepositoryError(operation: string, provider: SourceControlProviderKind) {
+  return Effect.mapError((cause: unknown) =>
+    isSourceControlRepositoryError(cause)
+      ? cause
+      : repositoryError({
+          operation,
+          provider,
+          detail: detailFromUnknown(cause),
+          cause,
+        }),
+  );
+}
+
+function toRepositoryInfo(
+  provider: SourceControlProviderKind,
+  urls: SourceControlRepositoryCloneUrls,
+): SourceControlRepositoryInfo {
+  return {
+    provider,
+    nameWithOwner: urls.nameWithOwner,
+    url: urls.url,
+    sshUrl: urls.sshUrl,
+  };
+}
+
+function selectRemoteUrl(
+  urls: SourceControlRepositoryCloneUrls,
+  protocol: SourceControlCloneProtocol | undefined,
+): string {
+  switch (protocol ?? "auto") {
+    case "https":
+      return urls.url;
+    case "ssh":
+    case "auto":
+      return urls.sshUrl;
+  }
+}
+
+function expandHomePath(input: string, path: Path.Path): string {
+  if (input === "~") {
+    return NodeOS.homedir();
+  }
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return path.join(NodeOS.homedir(), input.slice(2));
+  }
+  return input;
+}
+
+export const make = Effect.fn("makeSourceControlRepositoryService")(function* () {
+  const config = yield* ServerConfig;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const git = yield* GitVcsDriver.GitVcsDriver;
+  const path = yield* Path.Path;
+  const providers = yield* SourceControlProviderRegistry.SourceControlProviderRegistry;
+
+  const ensureConcreteProvider = (input: {
+    readonly operation: string;
+    readonly provider: SourceControlProviderKind;
+  }) => {
+    if (input.provider !== "unknown") {
+      return Effect.succeed(input.provider);
+    }
+
+    return Effect.fail(
+      repositoryError({
+        operation: input.operation,
+        provider: input.provider,
+        detail: "Choose a source control provider before continuing.",
+      }),
+    );
+  };
+
+  const lookupRepository = Effect.fn("SourceControlRepositoryService.lookupRepository")(function* (
+    input: SourceControlRepositoryLookupInput,
+  ) {
+    const providerKind = yield* ensureConcreteProvider({
+      operation: "lookupRepository",
+      provider: input.provider,
+    });
+    const provider = yield* providers.get(providerKind);
+    const urls = yield* provider.getRepositoryCloneUrls({
+      cwd: input.cwd ?? config.cwd,
+      repository: input.repository.trim(),
+    });
+    return toRepositoryInfo(providerKind, urls);
+  });
+
+  const normalizeDestinationPath = Effect.fn("SourceControlRepositoryService.normalizeDestination")(
+    function* (destinationPath: string) {
+      const trimmed = destinationPath.trim();
+      if (trimmed.length === 0) {
+        return yield* repositoryError({
+          operation: "cloneRepository",
+          provider: "unknown",
+          detail: "Choose a destination path before cloning.",
+        });
+      }
+
+      return path.resolve(expandHomePath(trimmed, path));
+    },
+  );
+
+  const prepareDestination = Effect.fn("SourceControlRepositoryService.prepareDestination")(
+    function* (destinationPath: string) {
+      const normalizedDestination = yield* normalizeDestinationPath(destinationPath);
+      if (yield* fileSystem.exists(normalizedDestination).pipe(Effect.orElseSucceed(() => false))) {
+        const entries = yield* fileSystem
+          .readDirectory(normalizedDestination, { recursive: false })
+          .pipe(
+            Effect.mapError((cause) =>
+              repositoryError({
+                operation: "cloneRepository",
+                provider: "unknown",
+                detail: "Destination path already exists and is not a directory.",
+                cause,
+              }),
+            ),
+          );
+        if (entries.length > 0) {
+          return yield* repositoryError({
+            operation: "cloneRepository",
+            provider: "unknown",
+            detail: "Destination path already exists and is not empty.",
+          });
+        }
+      } else {
+        yield* fileSystem.makeDirectory(path.dirname(normalizedDestination), { recursive: true });
+      }
+
+      return {
+        destinationPath: normalizedDestination,
+        parentPath: path.dirname(normalizedDestination),
+        directoryName: path.basename(normalizedDestination),
+      };
+    },
+  );
+
+  const cloneRepository = Effect.fn("SourceControlRepositoryService.cloneRepository")(function* (
+    input: SourceControlCloneRepositoryInput,
+  ) {
+    const preparedDestination = yield* prepareDestination(input.destinationPath);
+    let repository: SourceControlRepositoryInfo | null = null;
+    let remoteUrl = input.remoteUrl?.trim() ?? null;
+    let provider: SourceControlProviderKind = input.provider ?? "unknown";
+
+    if (input.provider && input.repository) {
+      repository = yield* lookupRepository({
+        provider: input.provider,
+        repository: input.repository,
+        cwd: preparedDestination.parentPath,
+      });
+      remoteUrl = selectRemoteUrl(repository, input.protocol);
+      provider = input.provider;
+    }
+
+    if (!remoteUrl) {
+      return yield* repositoryError({
+        operation: "cloneRepository",
+        provider,
+        detail: "Enter a repository path or clone URL before cloning.",
+      });
+    }
+
+    yield* git.execute({
+      operation: "SourceControlRepositoryService.cloneRepository",
+      cwd: preparedDestination.parentPath,
+      args: ["clone", remoteUrl, preparedDestination.directoryName],
+      timeoutMs: 120_000,
+      maxOutputBytes: 256 * 1024,
+    });
+
+    return {
+      cwd: preparedDestination.destinationPath,
+      remoteUrl,
+      repository,
+    };
+  });
+
+  const publishRepository = Effect.fn("SourceControlRepositoryService.publishRepository")(
+    function* (input: SourceControlPublishRepositoryInput) {
+      const providerKind = yield* ensureConcreteProvider({
+        operation: "publishRepository",
+        provider: input.provider,
+      });
+      const provider = yield* providers.get(providerKind);
+      const urls = yield* provider.createRepository({
+        cwd: input.cwd,
+        repository: input.repository.trim(),
+        visibility: input.visibility,
+      });
+      const remoteUrl = selectRemoteUrl(urls, input.protocol);
+      const remoteName = yield* git.ensureRemote({
+        cwd: input.cwd,
+        preferredName: input.remoteName?.trim() || "origin",
+        url: remoteUrl,
+      });
+
+      // An empty local repo (no commits) would make `git push HEAD:...` fail
+      // with an opaque "src refspec HEAD does not match any". Treat this as a
+      // partial success: the remote was created and wired up, but there is
+      // nothing to push yet.
+      const hasCommits = yield* git
+        .execute({
+          operation: "SourceControlRepositoryService.publishRepository.headCheck",
+          cwd: input.cwd,
+          args: ["rev-parse", "--verify", "HEAD"],
+        })
+        .pipe(
+          Effect.map(() => true),
+          Effect.catch(() => Effect.succeed(false)),
+        );
+      if (!hasCommits) {
+        const details = yield* git
+          .statusDetails(input.cwd)
+          .pipe(Effect.catch(() => Effect.succeed(null)));
+        return {
+          repository: toRepositoryInfo(providerKind, urls),
+          remoteName,
+          remoteUrl,
+          branch: details?.branch ?? "main",
+          status: "remote_added" as const,
+        };
+      }
+
+      const pushResult = yield* git.pushCurrentBranch(input.cwd, null, { remoteName });
+
+      return {
+        repository: toRepositoryInfo(providerKind, urls),
+        remoteName,
+        remoteUrl,
+        branch: pushResult.branch,
+        ...(pushResult.upstreamBranch ? { upstreamBranch: pushResult.upstreamBranch } : {}),
+        status: "pushed" as const,
+      };
+    },
+  );
+
+  return SourceControlRepositoryService.of({
+    lookupRepository: (input) =>
+      lookupRepository(input).pipe(mapRepositoryError("lookupRepository", input.provider)),
+    cloneRepository: (input) =>
+      cloneRepository(input).pipe(
+        mapRepositoryError("cloneRepository", input.provider ?? "unknown"),
+      ),
+    publishRepository: (input) =>
+      publishRepository(input).pipe(mapRepositoryError("publishRepository", input.provider)),
+  });
+});
+
+export const layer = Layer.effect(SourceControlRepositoryService, make());
diff --git a/apps/server/src/sourceControl/azureDevOpsPullRequests.ts b/apps/server/src/sourceControl/azureDevOpsPullRequests.ts
new file mode 100644
index 00000000000..e8f138e0e32
--- /dev/null
+++ b/apps/server/src/sourceControl/azureDevOpsPullRequests.ts
@@ -0,0 +1,111 @@
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { PositiveInt, TrimmedNonEmptyString } from "@t3tools/contracts";
+import { decodeJsonResult, formatSchemaError } from "@t3tools/shared/schemaJson";
+
+export interface NormalizedAzureDevOpsPullRequestRecord {
+  readonly number: number;
+  readonly title: string;
+  readonly url: string;
+  readonly baseRefName: string;
+  readonly headRefName: string;
+  readonly state: "open" | "closed" | "merged";
+  readonly updatedAt: Option.Option<DateTime.Utc>;
+}
+
+const AzureDevOpsPullRequestSchema = Schema.Struct({
+  pullRequestId: PositiveInt,
+  title: TrimmedNonEmptyString,
+  url: Schema.optional(Schema.String),
+  sourceRefName: TrimmedNonEmptyString,
+  targetRefName: TrimmedNonEmptyString,
+  status: Schema.String,
+  creationDate: Schema.optional(Schema.OptionFromNullOr(Schema.DateTimeUtcFromString)),
+  closedDate: Schema.optional(Schema.OptionFromNullOr(Schema.DateTimeUtcFromString)),
+  _links: Schema.optional(
+    Schema.Struct({
+      web: Schema.optional(
+        Schema.Struct({
+          href: Schema.String,
+        }),
+      ),
+    }),
+  ),
+});
+
+function trimOptionalString(value: string | null | undefined): string | null {
+  const trimmed = value?.trim() ?? "";
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeRefName(refName: string): string {
+  return refName.trim().replace(/^refs\/heads\//, "");
+}
+
+function normalizeAzureDevOpsPullRequestState(status: string): "open" | "closed" | "merged" {
+  switch (status.trim().toLowerCase()) {
+    case "completed":
+      return "merged";
+    case "abandoned":
+      return "closed";
+    default:
+      return "open";
+  }
+}
+
+function normalizeAzureDevOpsPullRequestRecord(
+  raw: Schema.Schema.Type<typeof AzureDevOpsPullRequestSchema>,
+): NormalizedAzureDevOpsPullRequestRecord {
+  return {
+    number: raw.pullRequestId,
+    title: raw.title,
+    url: trimOptionalString(raw._links?.web?.href) ?? trimOptionalString(raw.url) ?? "",
+    baseRefName: normalizeRefName(raw.targetRefName),
+    headRefName: normalizeRefName(raw.sourceRefName),
+    state: normalizeAzureDevOpsPullRequestState(raw.status),
+    updatedAt: (raw.closedDate ?? Option.none()).pipe(
+      Option.orElse(() => raw.creationDate ?? Option.none()),
+    ),
+  };
+}
+
+const decodeAzureDevOpsPullRequestList = decodeJsonResult(Schema.Array(Schema.Unknown));
+const decodeAzureDevOpsPullRequest = decodeJsonResult(AzureDevOpsPullRequestSchema);
+const decodeAzureDevOpsPullRequestEntry = Schema.decodeUnknownExit(AzureDevOpsPullRequestSchema);
+
+export const formatAzureDevOpsJsonDecodeError = formatSchemaError;
+
+export function decodeAzureDevOpsPullRequestListJson(
+  raw: string,
+): Result.Result<
+  ReadonlyArray<NormalizedAzureDevOpsPullRequestRecord>,
+  Cause.Cause<Schema.SchemaError>
+> {
+  const result = decodeAzureDevOpsPullRequestList(raw);
+  if (Result.isSuccess(result)) {
+    const pullRequests: NormalizedAzureDevOpsPullRequestRecord[] = [];
+    for (const entry of result.success) {
+      const decodedEntry = decodeAzureDevOpsPullRequestEntry(entry);
+      if (Exit.isFailure(decodedEntry)) {
+        continue;
+      }
+      pullRequests.push(normalizeAzureDevOpsPullRequestRecord(decodedEntry.value));
+    }
+    return Result.succeed(pullRequests);
+  }
+  return Result.fail(result.failure);
+}
+
+export function decodeAzureDevOpsPullRequestJson(
+  raw: string,
+): Result.Result<NormalizedAzureDevOpsPullRequestRecord, Cause.Cause<Schema.SchemaError>> {
+  const result = decodeAzureDevOpsPullRequest(raw);
+  if (Result.isSuccess(result)) {
+    return Result.succeed(normalizeAzureDevOpsPullRequestRecord(result.success));
+  }
+  return Result.fail(result.failure);
+}
diff --git a/apps/server/src/sourceControl/bitbucketPullRequests.ts b/apps/server/src/sourceControl/bitbucketPullRequests.ts
new file mode 100644
index 00000000000..6d67477bca7
--- /dev/null
+++ b/apps/server/src/sourceControl/bitbucketPullRequests.ts
@@ -0,0 +1,106 @@
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { PositiveInt, TrimmedNonEmptyString } from "@t3tools/contracts";
+
+export interface NormalizedBitbucketPullRequestRecord {
+  readonly number: number;
+  readonly title: string;
+  readonly url: string;
+  readonly baseRefName: string;
+  readonly headRefName: string;
+  readonly state: "open" | "closed" | "merged";
+  readonly updatedAt: Option.Option<DateTime.Utc>;
+  readonly isCrossRepository?: boolean;
+  readonly headRepositoryNameWithOwner?: string | null;
+  readonly headRepositoryOwnerLogin?: string | null;
+}
+
+export const BitbucketRepositoryRefSchema = Schema.Struct({
+  full_name: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
+  workspace: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        slug: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
+      }),
+    ),
+  ),
+});
+
+export const BitbucketPullRequestBranchSchema = Schema.Struct({
+  repository: Schema.optional(Schema.NullOr(BitbucketRepositoryRefSchema)),
+  branch: Schema.Struct({
+    name: TrimmedNonEmptyString,
+  }),
+});
+
+export const BitbucketPullRequestSchema = Schema.Struct({
+  id: PositiveInt,
+  title: TrimmedNonEmptyString,
+  state: Schema.optional(Schema.NullOr(Schema.String)),
+  updated_on: Schema.optional(Schema.OptionFromNullOr(Schema.DateTimeUtcFromString)),
+  links: Schema.Struct({
+    html: Schema.Struct({
+      href: TrimmedNonEmptyString,
+    }),
+  }),
+  source: BitbucketPullRequestBranchSchema,
+  destination: BitbucketPullRequestBranchSchema,
+});
+
+export const BitbucketPullRequestListSchema = Schema.Struct({
+  values: Schema.Array(BitbucketPullRequestSchema),
+  next: Schema.optional(TrimmedNonEmptyString),
+});
+
+function trimOptionalString(value: string | null | undefined): string | null {
+  const trimmed = value?.trim() ?? "";
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function repositoryOwner(repository: Schema.Schema.Type<typeof BitbucketRepositoryRefSchema>) {
+  return (
+    trimOptionalString(repository.workspace?.slug) ??
+    (repository.full_name?.includes("/") ? (repository.full_name.split("/")[0] ?? null) : null)
+  );
+}
+
+function normalizeBitbucketPullRequestState(state: string | null | undefined) {
+  switch (state?.trim().toUpperCase()) {
+    case "MERGED":
+      return "merged" as const;
+    case "DECLINED":
+    case "SUPERSEDED":
+      return "closed" as const;
+    case "OPEN":
+    default:
+      return "open" as const;
+  }
+}
+
+export function normalizeBitbucketPullRequestRecord(
+  raw: Schema.Schema.Type<typeof BitbucketPullRequestSchema>,
+): NormalizedBitbucketPullRequestRecord {
+  const headRepositoryNameWithOwner = trimOptionalString(raw.source.repository?.full_name);
+  const baseRepositoryNameWithOwner = trimOptionalString(raw.destination.repository?.full_name);
+  const headRepositoryOwnerLogin = raw.source.repository
+    ? repositoryOwner(raw.source.repository)
+    : null;
+  const isCrossRepository =
+    headRepositoryNameWithOwner !== null &&
+    baseRepositoryNameWithOwner !== null &&
+    headRepositoryNameWithOwner !== baseRepositoryNameWithOwner;
+
+  return {
+    number: raw.id,
+    title: raw.title,
+    url: raw.links.html.href,
+    baseRefName: raw.destination.branch.name,
+    headRefName: raw.source.branch.name,
+    state: normalizeBitbucketPullRequestState(raw.state),
+    updatedAt: raw.updated_on ?? Option.none(),
+    ...(isCrossRepository ? { isCrossRepository: true } : {}),
+    ...(headRepositoryNameWithOwner ? { headRepositoryNameWithOwner } : {}),
+    ...(headRepositoryOwnerLogin ? { headRepositoryOwnerLogin } : {}),
+  };
+}
diff --git a/apps/server/src/git/githubPullRequests.ts b/apps/server/src/sourceControl/gitHubPullRequests.ts
similarity index 90%
rename from apps/server/src/git/githubPullRequests.ts
rename to apps/server/src/sourceControl/gitHubPullRequests.ts
index d137a46d6fa..d9dcb7f9ad1 100644
--- a/apps/server/src/git/githubPullRequests.ts
+++ b/apps/server/src/sourceControl/gitHubPullRequests.ts
@@ -1,4 +1,9 @@
-import { Cause, Exit, Result, Schema } from "effect";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
 import { PositiveInt, TrimmedNonEmptyString } from "@t3tools/contracts";
 import { decodeJsonResult, formatSchemaError } from "@t3tools/shared/schemaJson";
 
@@ -9,7 +14,7 @@ export interface NormalizedGitHubPullRequestRecord {
   readonly baseRefName: string;
   readonly headRefName: string;
   readonly state: "open" | "closed" | "merged";
-  readonly updatedAt: string | null;
+  readonly updatedAt: Option.Option<DateTime.Utc>;
   readonly isCrossRepository?: boolean;
   readonly headRepositoryNameWithOwner?: string | null;
   readonly headRepositoryOwnerLogin?: string | null;
@@ -23,7 +28,7 @@ const GitHubPullRequestSchema = Schema.Struct({
   headRefName: TrimmedNonEmptyString,
   state: Schema.optional(Schema.NullOr(Schema.String)),
   mergedAt: Schema.optional(Schema.NullOr(Schema.String)),
-  updatedAt: Schema.optional(Schema.NullOr(Schema.String)),
+  updatedAt: Schema.optional(Schema.OptionFromNullOr(Schema.DateTimeUtcFromString)),
   isCrossRepository: Schema.optional(Schema.Boolean),
   headRepository: Schema.optional(
     Schema.NullOr(
@@ -80,8 +85,7 @@ function normalizeGitHubPullRequestRecord(
     baseRefName: raw.baseRefName,
     headRefName: raw.headRefName,
     state: normalizeGitHubPullRequestState(raw),
-    updatedAt:
-      typeof raw.updatedAt === "string" && raw.updatedAt.trim().length > 0 ? raw.updatedAt : null,
+    updatedAt: raw.updatedAt ?? Option.none(),
     ...(typeof raw.isCrossRepository === "boolean"
       ? { isCrossRepository: raw.isCrossRepository }
       : {}),
diff --git a/apps/server/src/sourceControl/gitLabMergeRequests.ts b/apps/server/src/sourceControl/gitLabMergeRequests.ts
new file mode 100644
index 00000000000..afd1eceaeed
--- /dev/null
+++ b/apps/server/src/sourceControl/gitLabMergeRequests.ts
@@ -0,0 +1,153 @@
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { PositiveInt, TrimmedNonEmptyString } from "@t3tools/contracts";
+import { decodeJsonResult, formatSchemaError } from "@t3tools/shared/schemaJson";
+
+export interface NormalizedGitLabMergeRequestRecord {
+  readonly number: number;
+  readonly title: string;
+  readonly url: string;
+  readonly baseRefName: string;
+  readonly headRefName: string;
+  readonly state: "open" | "closed" | "merged";
+  readonly updatedAt: Option.Option<DateTime.Utc>;
+  readonly isCrossRepository?: boolean;
+  readonly headRepositoryNameWithOwner?: string | null;
+  readonly headRepositoryOwnerLogin?: string | null;
+}
+
+const GitLabProjectReferenceSchema = Schema.Struct({
+  path_with_namespace: Schema.optional(Schema.String),
+  pathWithNamespace: Schema.optional(Schema.String),
+  namespace: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        path: Schema.optional(Schema.String),
+        full_path: Schema.optional(Schema.String),
+        fullPath: Schema.optional(Schema.String),
+      }),
+    ),
+  ),
+});
+
+const GitLabMergeRequestSchema = Schema.Struct({
+  iid: PositiveInt,
+  title: TrimmedNonEmptyString,
+  web_url: TrimmedNonEmptyString,
+  source_branch: TrimmedNonEmptyString,
+  target_branch: TrimmedNonEmptyString,
+  state: Schema.optional(Schema.NullOr(Schema.String)),
+  updated_at: Schema.optional(Schema.OptionFromNullOr(Schema.DateTimeUtcFromString)),
+  source_project_id: Schema.optional(Schema.NullOr(Schema.Number)),
+  target_project_id: Schema.optional(Schema.NullOr(Schema.Number)),
+  source_project: Schema.optional(Schema.NullOr(GitLabProjectReferenceSchema)),
+  target_project: Schema.optional(Schema.NullOr(GitLabProjectReferenceSchema)),
+});
+
+function trimOptionalString(value: string | null | undefined): string | null {
+  const trimmed = value?.trim() ?? "";
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeGitLabMergeRequestState(
+  state: string | null | undefined,
+): "open" | "closed" | "merged" {
+  const normalized = state?.trim().toLowerCase();
+  if (normalized === "merged") {
+    return "merged";
+  }
+  if (normalized === "closed") {
+    return "closed";
+  }
+  return "open";
+}
+
+function projectPathWithNamespace(
+  project: Schema.Schema.Type<typeof GitLabProjectReferenceSchema> | null | undefined,
+): string | null {
+  const explicit =
+    trimOptionalString(project?.path_with_namespace) ??
+    trimOptionalString(project?.pathWithNamespace);
+  if (explicit) {
+    return explicit;
+  }
+
+  const namespacePath =
+    trimOptionalString(project?.namespace?.full_path) ??
+    trimOptionalString(project?.namespace?.fullPath) ??
+    trimOptionalString(project?.namespace?.path);
+  return namespacePath;
+}
+
+function ownerLoginFromPathWithNamespace(pathWithNamespace: string | null): string | null {
+  const [owner] = pathWithNamespace?.split("/") ?? [];
+  return trimOptionalString(owner);
+}
+
+function normalizeGitLabMergeRequestRecord(
+  raw: Schema.Schema.Type<typeof GitLabMergeRequestSchema>,
+): NormalizedGitLabMergeRequestRecord {
+  const sourceProjectPath = projectPathWithNamespace(raw.source_project);
+  const targetProjectPath = projectPathWithNamespace(raw.target_project);
+  const isCrossRepository =
+    typeof raw.source_project_id === "number" && typeof raw.target_project_id === "number"
+      ? raw.source_project_id !== raw.target_project_id
+      : sourceProjectPath !== null && targetProjectPath !== null
+        ? sourceProjectPath.toLowerCase() !== targetProjectPath.toLowerCase()
+        : undefined;
+  const headRepositoryOwnerLogin = ownerLoginFromPathWithNamespace(sourceProjectPath);
+
+  return {
+    number: raw.iid,
+    title: raw.title,
+    url: raw.web_url,
+    baseRefName: raw.target_branch,
+    headRefName: raw.source_branch,
+    state: normalizeGitLabMergeRequestState(raw.state),
+    updatedAt: raw.updated_at ?? Option.none(),
+    ...(typeof isCrossRepository === "boolean" ? { isCrossRepository } : {}),
+    ...(sourceProjectPath ? { headRepositoryNameWithOwner: sourceProjectPath } : {}),
+    ...(headRepositoryOwnerLogin ? { headRepositoryOwnerLogin } : {}),
+  };
+}
+
+const decodeGitLabMergeRequestList = decodeJsonResult(Schema.Array(Schema.Unknown));
+const decodeGitLabMergeRequest = decodeJsonResult(GitLabMergeRequestSchema);
+const decodeGitLabMergeRequestEntry = Schema.decodeUnknownExit(GitLabMergeRequestSchema);
+
+export const formatGitLabJsonDecodeError = formatSchemaError;
+
+export function decodeGitLabMergeRequestListJson(
+  raw: string,
+): Result.Result<
+  ReadonlyArray<NormalizedGitLabMergeRequestRecord>,
+  Cause.Cause<Schema.SchemaError>
+> {
+  const result = decodeGitLabMergeRequestList(raw);
+  if (Result.isSuccess(result)) {
+    const mergeRequests: NormalizedGitLabMergeRequestRecord[] = [];
+    for (const entry of result.success) {
+      const decodedEntry = decodeGitLabMergeRequestEntry(entry);
+      if (Exit.isFailure(decodedEntry)) {
+        continue;
+      }
+      mergeRequests.push(normalizeGitLabMergeRequestRecord(decodedEntry.value));
+    }
+    return Result.succeed(mergeRequests);
+  }
+  return Result.fail(result.failure);
+}
+
+export function decodeGitLabMergeRequestJson(
+  raw: string,
+): Result.Result<NormalizedGitLabMergeRequestRecord, Cause.Cause<Schema.SchemaError>> {
+  const result = decodeGitLabMergeRequest(raw);
+  if (Result.isSuccess(result)) {
+    return Result.succeed(normalizeGitLabMergeRequestRecord(result.success));
+  }
+  return Result.fail(result.failure);
+}
diff --git a/apps/server/src/startupAccess.test.ts b/apps/server/src/startupAccess.test.ts
index ef6ece31e28..03c01170f15 100644
--- a/apps/server/src/startupAccess.test.ts
+++ b/apps/server/src/startupAccess.test.ts
@@ -7,7 +7,7 @@ import {
   resolveHeadlessConnectionHost,
   resolveHeadlessConnectionString,
   resolveListeningPort,
-} from "./startupAccess";
+} from "./startupAccess.ts";
 
 it("prefers localhost when no explicit host is configured", () => {
   expect(resolveHeadlessConnectionHost(undefined)).toBe("localhost");
diff --git a/apps/server/src/startupAccess.ts b/apps/server/src/startupAccess.ts
index a350d729d01..d3b6898d75b 100644
--- a/apps/server/src/startupAccess.ts
+++ b/apps/server/src/startupAccess.ts
@@ -1,11 +1,11 @@
 import { networkInterfaces } from "node:os";
 
 import { QrCode } from "@t3tools/shared/qrCode";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 import { HttpServer } from "effect/unstable/http";
 
-import { ServerConfig } from "./config";
-import { ServerAuth } from "./auth/Services/ServerAuth";
+import { ServerConfig } from "./config.ts";
+import { ServerAuth } from "./auth/Services/ServerAuth.ts";
 
 export interface HeadlessServeAccessInfo {
   readonly connectionString: string;
diff --git a/apps/server/src/stream/collectUint8StreamText.test.ts b/apps/server/src/stream/collectUint8StreamText.test.ts
new file mode 100644
index 00000000000..d6715294cce
--- /dev/null
+++ b/apps/server/src/stream/collectUint8StreamText.test.ts
@@ -0,0 +1,39 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+
+import { collectUint8StreamText } from "./collectUint8StreamText.ts";
+
+const encoder = new TextEncoder();
+
+describe("collectUint8StreamText", () => {
+  it.effect("collects Uint8Array chunks into decoded text", () =>
+    Effect.gen(function* () {
+      const result = yield* collectUint8StreamText({
+        stream: Stream.make(encoder.encode("hello "), encoder.encode("world")),
+      });
+
+      assert.deepStrictEqual(result, {
+        text: "hello world",
+        bytes: 11,
+        truncated: false,
+      });
+    }),
+  );
+
+  it.effect("truncates by bytes and appends an optional marker once", () =>
+    Effect.gen(function* () {
+      const result = yield* collectUint8StreamText({
+        stream: Stream.make(encoder.encode("abcdef"), encoder.encode("ghij")),
+        maxBytes: 5,
+        truncatedMarker: "[truncated]",
+      });
+
+      assert.deepStrictEqual(result, {
+        text: "abcde[truncated]",
+        bytes: 5,
+        truncated: true,
+      });
+    }),
+  );
+});
diff --git a/apps/server/src/stream/collectUint8StreamText.ts b/apps/server/src/stream/collectUint8StreamText.ts
new file mode 100644
index 00000000000..7ac5530474e
--- /dev/null
+++ b/apps/server/src/stream/collectUint8StreamText.ts
@@ -0,0 +1,70 @@
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+
+export interface CollectedUint8StreamText {
+  readonly text: string;
+  readonly truncated: boolean;
+  readonly bytes: number;
+}
+
+interface CollectState {
+  chunks: Uint8Array[];
+  readonly bytes: number;
+  readonly truncated: boolean;
+}
+
+export const collectUint8StreamText = <E>(input: {
+  readonly stream: Stream.Stream<Uint8Array, E>;
+  readonly maxBytes?: number | undefined;
+  readonly truncatedMarker?: string | null | undefined;
+}): Effect.Effect<CollectedUint8StreamText, E> => {
+  const maxBytes = input.maxBytes ?? Number.POSITIVE_INFINITY;
+  const truncatedMarker = input.truncatedMarker ?? "";
+
+  return input.stream.pipe(
+    Stream.runFold(
+      (): CollectState => ({
+        chunks: [],
+        bytes: 0,
+        truncated: false,
+      }),
+      (state, chunk): CollectState => {
+        /*
+         * keep draining after truncation so the child process can exit normally.
+         * its a know issue that on windows killing after the output cap can force an expensive taskkill operation and hurt performance
+         */
+        if (state.truncated) {
+          return state;
+        }
+
+        const remainingBytes = maxBytes - state.bytes;
+        if (remainingBytes <= 0) {
+          return {
+            ...state,
+            truncated: true,
+          };
+        }
+
+        const nextChunk =
+          chunk.byteLength > remainingBytes ? chunk.slice(0, remainingBytes) : chunk;
+        state.chunks.push(nextChunk);
+        const bytes = state.bytes + nextChunk.byteLength;
+        const truncated = chunk.byteLength > remainingBytes;
+
+        return {
+          chunks: state.chunks,
+          bytes,
+          truncated,
+        };
+      },
+    ),
+    Effect.map((state): CollectedUint8StreamText => {
+      const text = Buffer.concat(state.chunks, state.bytes).toString("utf8");
+      return {
+        text: state.truncated && truncatedMarker.length > 0 ? `${text}${truncatedMarker}` : text,
+        bytes: state.bytes,
+        truncated: state.truncated,
+      };
+    }),
+  );
+};
diff --git a/apps/server/src/telemetry/Identify.ts b/apps/server/src/telemetry/Identify.ts
index d7784eb88b4..ed8e98a87a4 100644
--- a/apps/server/src/telemetry/Identify.ts
+++ b/apps/server/src/telemetry/Identify.ts
@@ -1,7 +1,11 @@
-import { Effect, FileSystem, Path, Random, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
 import * as Crypto from "node:crypto";
 import { homedir } from "node:os";
-import { ServerConfig } from "../config";
+import { ServerConfig } from "../config.ts";
 
 const CodexAuthJsonSchema = Schema.Struct({
   tokens: Schema.Struct({
diff --git a/apps/server/src/telemetry/Layers/AnalyticsService.test.ts b/apps/server/src/telemetry/Layers/AnalyticsService.test.ts
index 5fe0795ce48..03ebd2fdc65 100644
--- a/apps/server/src/telemetry/Layers/AnalyticsService.test.ts
+++ b/apps/server/src/telemetry/Layers/AnalyticsService.test.ts
@@ -1,7 +1,9 @@
 import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
-import { ConfigProvider, Effect, Layer } from "effect";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as HttpServer from "effect/unstable/http/HttpServer";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
diff --git a/apps/server/src/telemetry/Layers/AnalyticsService.ts b/apps/server/src/telemetry/Layers/AnalyticsService.ts
index e933576dffa..ec859fb18f5 100644
--- a/apps/server/src/telemetry/Layers/AnalyticsService.ts
+++ b/apps/server/src/telemetry/Layers/AnalyticsService.ts
@@ -7,13 +7,17 @@
  * @module AnalyticsServiceLive
  */
 
-import { Config, DateTime, Effect, Layer, Ref } from "effect";
+import * as Config from "effect/Config";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 
 import { ServerConfig } from "../../config.ts";
 import { AnalyticsService, type AnalyticsServiceShape } from "../Services/AnalyticsService.ts";
 import { getTelemetryIdentifier } from "../Identify.ts";
-import { version } from "../../../package.json" with { type: "json" };
+import packageJson from "../../../package.json" with { type: "json" };
 
 interface BufferedAnalyticsEvent {
   readonly event: string;
@@ -86,7 +90,7 @@ const makeAnalyticsService = Effect.gen(function* () {
           platform: process.platform,
           wsl: process.env.WSL_DISTRO_NAME,
           arch: process.arch,
-          t3CodeVersion: version,
+          t3CodeVersion: packageJson.version,
           clientType,
         },
         timestamp: event.capturedAt,
diff --git a/apps/server/src/telemetry/Services/AnalyticsService.ts b/apps/server/src/telemetry/Services/AnalyticsService.ts
index 0e703573d46..a2717c790dc 100644
--- a/apps/server/src/telemetry/Services/AnalyticsService.ts
+++ b/apps/server/src/telemetry/Services/AnalyticsService.ts
@@ -6,7 +6,9 @@
  *
  * @module AnalyticsService
  */
-import { Effect, Layer, Context } from "effect";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Context from "effect/Context";
 
 export interface AnalyticsServiceShape {
   /**
diff --git a/apps/server/src/terminal/Layers/BunPTY.ts b/apps/server/src/terminal/Layers/BunPTY.ts
index 1fb4bdd6367..40113a1915c 100644
--- a/apps/server/src/terminal/Layers/BunPTY.ts
+++ b/apps/server/src/terminal/Layers/BunPTY.ts
@@ -1,13 +1,17 @@
-import { Effect, Layer } from "effect";
-import { PtyAdapter, PtyAdapterShape, PtyExitEvent, PtyProcess } from "../Services/PTY";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { PtyAdapter } from "../Services/PTY.ts";
+import type { PtyAdapterShape, PtyExitEvent, PtyProcess } from "../Services/PTY.ts";
 
 class BunPtyProcess implements PtyProcess {
   private readonly dataListeners = new Set<(data: string) => void>();
   private readonly exitListeners = new Set<(event: PtyExitEvent) => void>();
   private readonly decoder = new TextDecoder();
+  private readonly process: Bun.Subprocess;
   private didExit = false;
 
-  constructor(private readonly process: Bun.Subprocess) {
+  constructor(process: Bun.Subprocess) {
+    this.process = process;
     void this.process.exited
       .then((exitCode) => {
         this.emitExit({
diff --git a/apps/server/src/terminal/Layers/Manager.test.ts b/apps/server/src/terminal/Layers/Manager.test.ts
index 8207861e206..b81d6596592 100644
--- a/apps/server/src/terminal/Layers/Manager.test.ts
+++ b/apps/server/src/terminal/Layers/Manager.test.ts
@@ -1,5 +1,3 @@
-import path from "node:path";
-
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import {
@@ -8,41 +6,50 @@ import {
   type TerminalOpenInput,
   type TerminalRestartInput,
 } from "@t3tools/contracts";
-import {
-  Duration,
-  Effect,
-  Encoding,
-  Exit,
-  Fiber,
-  FileSystem,
-  Option,
-  PlatformError,
-  Ref,
-  Schedule,
-  Scope,
-} from "effect";
+import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as PlatformError from "effect/PlatformError";
+import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as Scope from "effect/Scope";
 import { TestClock } from "effect/testing";
 import { expect } from "vitest";
 
-import type { TerminalManagerShape } from "../Services/Manager";
+import * as ProcessRunner from "../../processRunner.ts";
+import type { TerminalManagerShape } from "../Services/Manager.ts";
 import {
   type PtyAdapterShape,
   type PtyExitEvent,
   type PtyProcess,
   type PtySpawnInput,
   PtySpawnError,
-} from "../Services/PTY";
-import { makeTerminalManagerWithOptions } from "./Manager";
+} from "../Services/PTY.ts";
+import { makeTerminalManagerWithOptions } from "./Manager.ts";
+
+class WaitForConditionError extends Data.TaggedError("WaitForConditionError")<{
+  readonly message: string;
+}> {}
 
 class FakePtyProcess implements PtyProcess {
   readonly writes: string[] = [];
   readonly resizeCalls: Array<{ cols: number; rows: number }> = [];
   readonly killSignals: Array<string | undefined> = [];
+  readonly pid: number;
   private readonly dataListeners = new Set<(data: string) => void>();
   private readonly exitListeners = new Set<(event: PtyExitEvent) => void>();
   killed = false;
 
-  constructor(readonly pid: number) {}
+  constructor(pid: number) {
+    this.pid = pid;
+  }
 
   write(data: string): void {
     this.writes.push(data);
@@ -88,9 +95,12 @@ class FakePtyAdapter implements PtyAdapterShape {
   readonly spawnInputs: PtySpawnInput[] = [];
   readonly processes: FakePtyProcess[] = [];
   readonly spawnFailures: Error[] = [];
+  private readonly mode: "sync" | "async";
   private nextPid = 9000;
 
-  constructor(private readonly mode: "sync" | "async" = "sync") {}
+  constructor(mode: "sync" | "async" = "sync") {
+    this.mode = mode;
+  }
 
   spawn(input: PtySpawnInput): Effect.Effect<PtyProcess, PtySpawnError> {
     this.spawnInputs.push(input);
@@ -124,17 +134,18 @@ class FakePtyAdapter implements PtyAdapterShape {
 const waitFor = <E, R>(
   predicate: Effect.Effect<boolean, E, R>,
   timeout: Duration.Input = 800,
-): Effect.Effect<void, Error | E, R> =>
+): Effect.Effect<void, WaitForConditionError | E, R> =>
   predicate.pipe(
     Effect.filterOrFail(
       (done) => done,
-      () => new Error("Condition not met"),
+      () => new WaitForConditionError({ message: "Condition not met" }),
     ),
     Effect.retry(Schedule.spaced("15 millis")),
     Effect.timeoutOption(timeout),
     Effect.flatMap((result) =>
       Option.match(result, {
-        onNone: () => Effect.fail(new Error("Timed out waiting for condition")),
+        onNone: () =>
+          Effect.fail(new WaitForConditionError({ message: "Timed out waiting for condition" })),
         onSome: () => Effect.void,
       }),
     ),
@@ -162,32 +173,32 @@ function restartInput(overrides: Partial<TerminalRestartInput> = {}): TerminalRe
   };
 }
 
-function historyLogName(threadId: string): string {
-  return `terminal_${Encoding.encodeBase64Url(threadId)}.log`;
-}
-
-function multiTerminalHistoryLogName(threadId: string, terminalId: string): string {
-  const threadPart = `terminal_${Encoding.encodeBase64Url(threadId)}`;
-  if (terminalId === DEFAULT_TERMINAL_ID) {
-    return `${threadPart}.log`;
-  }
-  return `${threadPart}_${Encoding.encodeBase64Url(terminalId)}.log`;
-}
-
-function historyLogPath(logsDir: string, threadId = "thread-1"): string {
-  return path.join(logsDir, historyLogName(threadId));
-}
+const historyLogPath = (logsDir: string, threadId = "thread-1") =>
+  Effect.service(Path.Path).pipe(
+    Effect.map(({ join }) => join(logsDir, `terminal_${Encoding.encodeBase64Url(threadId)}.log`)),
+  );
 
-function multiTerminalHistoryLogPath(
+const multiTerminalHistoryLogPath = (
   logsDir: string,
   threadId = "thread-1",
-  terminalId = "default",
-): string {
-  return path.join(logsDir, multiTerminalHistoryLogName(threadId, terminalId));
-}
+  terminalId = DEFAULT_TERMINAL_ID,
+) =>
+  Effect.service(Path.Path).pipe(
+    Effect.map(({ join }) => {
+      const threadPart = `terminal_${Encoding.encodeBase64Url(threadId)}`;
+      return join(
+        logsDir,
+        terminalId === DEFAULT_TERMINAL_ID
+          ? `${threadPart}.log`
+          : `${threadPart}_${Encoding.encodeBase64Url(terminalId)}.log`,
+      );
+    }),
+  );
 
 interface CreateManagerOptions {
   shellResolver?: () => string;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
   subprocessChecker?: (terminalPid: number) => Effect.Effect<boolean>;
   subprocessPollIntervalMs?: number;
   processKillGraceMs?: number;
@@ -209,12 +220,13 @@ const createManager = (
 ): Effect.Effect<
   ManagerFixture,
   PlatformError.PlatformError,
-  FileSystem.FileSystem | Scope.Scope
+  FileSystem.FileSystem | Path.Path | Scope.Scope | ProcessRunner.ProcessRunner
 > =>
   Effect.flatMap(Effect.service(FileSystem.FileSystem), (fs) =>
     Effect.gen(function* () {
+      const { join } = yield* Path.Path;
       const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-terminal-" });
-      const logsDir = path.join(baseDir, "userdata", "logs", "terminals");
+      const logsDir = join(baseDir, "userdata", "logs", "terminals");
       const ptyAdapter = options.ptyAdapter ?? new FakePtyAdapter();
 
       const manager = yield* makeTerminalManagerWithOptions({
@@ -222,15 +234,15 @@ const createManager = (
         historyLineLimit,
         ptyAdapter,
         ...(options.shellResolver !== undefined ? { shellResolver: options.shellResolver } : {}),
+        ...(options.platform !== undefined ? { platform: options.platform } : {}),
+        ...(options.env !== undefined ? { env: options.env } : {}),
         ...(options.subprocessChecker !== undefined
           ? { subprocessChecker: options.subprocessChecker }
           : {}),
         ...(options.subprocessPollIntervalMs !== undefined
           ? { subprocessPollIntervalMs: options.subprocessPollIntervalMs }
           : {}),
-        ...(options.processKillGraceMs !== undefined
-          ? { processKillGraceMs: options.processKillGraceMs }
-          : {}),
+        processKillGraceMs: options.processKillGraceMs ?? 1,
         ...(options.maxRetainedInactiveSessions !== undefined
           ? { maxRetainedInactiveSessions: options.maxRetainedInactiveSessions }
           : {}),
@@ -245,6 +257,7 @@ const createManager = (
       return {
         baseDir,
         logsDir,
+        join,
         ptyAdapter,
         manager,
         getEvents: Ref.get(eventsRef),
@@ -252,7 +265,12 @@ const createManager = (
     }),
   );
 
-it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (it) => {
+it.layer(
+  Layer.merge(NodeServices.layer, ProcessRunner.layer.pipe(Layer.provide(NodeServices.layer))),
+  { excludeTestServices: true },
+)("TerminalManager", (it) => {
+  const itEffectSkipOnWindows = process.platform === "win32" ? it.effect.skip : it.effect;
+
   it.effect("spawns lazily and reuses running terminal per thread", () =>
     Effect.gen(function* () {
       const { manager, ptyAdapter } = yield* createManager();
@@ -289,8 +307,10 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
       fs.writeFileString(filePath, contents),
     );
 
-  it.effect("preserves non-notFound cwd stat failures", () =>
+  itEffectSkipOnWindows("preserves non-notFound cwd stat failures", () =>
     Effect.gen(function* () {
+      const path = yield* Path.Path;
+
       const { manager, baseDir } = yield* createManager();
       const blockedRoot = path.join(baseDir, "blocked-root");
       const blockedCwd = path.join(blockedRoot, "cwd");
@@ -387,15 +407,27 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
   it.effect("clears transcript and emits cleared event", () =>
     Effect.gen(function* () {
       const { manager, ptyAdapter, logsDir, getEvents } = yield* createManager();
+      const path = yield* Path.Path;
       yield* manager.open(openInput());
       const process = ptyAdapter.processes[0];
       expect(process).toBeDefined();
       if (!process) return;
 
       process.emitData("hello\n");
-      yield* waitFor(pathExists(historyLogPath(logsDir)));
+      yield* waitFor(
+        historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      );
       yield* manager.clear({ threadId: "thread-1", terminalId: DEFAULT_TERMINAL_ID });
-      yield* waitFor(Effect.map(readFileString(historyLogPath(logsDir)), (text) => text === ""));
+      yield* waitFor(
+        historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(readFileString),
+          Effect.map((text) => text === ""),
+        ),
+      );
 
       const events = yield* getEvents;
       expect(events.some((event) => event.type === "cleared")).toBe(true);
@@ -418,19 +450,32 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
       expect(firstProcess).toBeDefined();
       if (!firstProcess) return;
       firstProcess.emitData("before restart\n");
-      yield* waitFor(pathExists(historyLogPath(logsDir)));
+      const path = yield* Path.Path;
+      yield* waitFor(
+        historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      );
 
       const snapshot = yield* manager.restart(restartInput());
       assert.equal(snapshot.history, "");
       assert.equal(snapshot.status, "running");
       expect(ptyAdapter.spawnInputs).toHaveLength(2);
-      yield* waitFor(Effect.map(readFileString(historyLogPath(logsDir)), (text) => text === ""));
+      yield* waitFor(
+        historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(readFileString),
+          Effect.map((text) => text === ""),
+        ),
+      );
     }),
   );
 
   it.effect("propagates explicit worktree metadata through snapshots and lifecycle events", () =>
     Effect.gen(function* () {
       const { manager, getEvents, baseDir } = yield* createManager();
+      const path = yield* Path.Path;
       const firstWorktreePath = path.join(baseDir, "worktrees", "feature-a");
       const secondWorktreePath = path.join(baseDir, "worktrees", "feature-b");
       yield* makeDirectory(firstWorktreePath);
@@ -468,6 +513,7 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
   it.effect("preserves worktree metadata when reopening an exited session", () =>
     Effect.gen(function* () {
       const { manager, ptyAdapter, getEvents, baseDir } = yield* createManager();
+      const path = yield* Path.Path;
       const worktreePath = path.join(baseDir, "worktrees", "feature-a");
       yield* makeDirectory(worktreePath);
 
@@ -510,12 +556,18 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
   it.effect("emits exited event and reopens with clean transcript after exit", () =>
     Effect.gen(function* () {
       const { manager, ptyAdapter, logsDir, getEvents } = yield* createManager();
+      const path = yield* Path.Path;
       yield* manager.open(openInput());
       const process = ptyAdapter.processes[0];
       expect(process).toBeDefined();
       if (!process) return;
       process.emitData("old data\n");
-      yield* waitFor(pathExists(historyLogPath(logsDir)));
+      yield* waitFor(
+        historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      );
       process.emitExit({ exitCode: 0, signal: 0 });
 
       yield* waitFor(
@@ -525,7 +577,12 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
 
       assert.equal(reopened.history, "");
       expect(ptyAdapter.spawnInputs).toHaveLength(2);
-      expect(yield* readFileString(historyLogPath(logsDir))).toBe("");
+      expect(
+        yield* historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(readFileString),
+        ),
+      ).toBe("");
     }),
   );
 
@@ -712,10 +769,21 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
       expect(process).toBeDefined();
       if (!process) return;
       process.emitData("bye\n");
-      yield* waitFor(pathExists(historyLogPath(logsDir)));
+      const path = yield* Path.Path;
+      yield* waitFor(
+        historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      );
 
       yield* manager.close({ threadId: "thread-1", deleteHistory: true });
-      expect(yield* pathExists(historyLogPath(logsDir))).toBe(false);
+      expect(
+        yield* historyLogPath(logsDir).pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      ).toBe(false);
     }),
   );
 
@@ -732,19 +800,36 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
 
       defaultProcess.emitData("default\n");
       sidecarProcess.emitData("sidecar\n");
-      yield* waitFor(pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "default")));
-      yield* waitFor(pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar")));
+      const path = yield* Path.Path;
+      yield* waitFor(
+        multiTerminalHistoryLogPath(logsDir, "thread-1", "default").pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      );
+      yield* waitFor(
+        multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar").pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      );
 
       yield* manager.close({ threadId: "thread-1", deleteHistory: true });
 
       assert.equal(defaultProcess.killed, true);
       assert.equal(sidecarProcess.killed, true);
-      expect(yield* pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "default"))).toBe(
-        false,
-      );
-      expect(yield* pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar"))).toBe(
-        false,
-      );
+      expect(
+        yield* multiTerminalHistoryLogPath(logsDir, "thread-1", "default").pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      ).toBe(false);
+      expect(
+        yield* multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar").pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      ).toBe(false);
     }),
   );
 
@@ -783,7 +868,13 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
 
       first.emitData("first-history\n");
       second.emitData("second-history\n");
-      yield* waitFor(pathExists(historyLogPath(logsDir, "thread-1")));
+      const path = yield* Path.Path;
+      yield* waitFor(
+        historyLogPath(logsDir, "thread-1").pipe(
+          Effect.provideService(Path.Path, path),
+          Effect.flatMap(pathExists),
+        ),
+      );
       first.emitExit({ exitCode: 0, signal: 0 });
       yield* Effect.sleep(Duration.millis(5));
       second.emitExit({ exitCode: 0, signal: 0 });
@@ -806,8 +897,9 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
   it.effect("migrates legacy transcript filenames to terminal-scoped history path on open", () =>
     Effect.gen(function* () {
       const { manager, logsDir } = yield* createManager();
+      const path = yield* Path.Path;
       const legacyPath = path.join(logsDir, "thread-1.log");
-      const nextPath = historyLogPath(logsDir);
+      const nextPath = yield* historyLogPath(logsDir);
       yield* writeFileString(legacyPath, "legacy-line\n");
 
       const snapshot = yield* manager.open(openInput());
@@ -821,8 +913,12 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
 
   it.effect("retries with fallback shells when preferred shell spawn fails", () =>
     Effect.gen(function* () {
+      const missingShell =
+        process.platform === "win32"
+          ? "C:\\definitely\\missing-shell.exe"
+          : "/definitely/missing-shell -l";
       const { manager, ptyAdapter } = yield* createManager(5, {
-        shellResolver: () => "/definitely/missing-shell -l",
+        shellResolver: () => missingShell,
       });
       ptyAdapter.spawnFailures.push(new Error("posix_spawnp failed."));
 
@@ -830,12 +926,17 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
 
       assert.equal(snapshot.status, "running");
       expect(ptyAdapter.spawnInputs.length).toBeGreaterThanOrEqual(2);
-      expect(ptyAdapter.spawnInputs[0]?.shell).toBe("/definitely/missing-shell");
+      expect(ptyAdapter.spawnInputs[0]?.shell).toBe(
+        process.platform === "win32" ? missingShell : "/definitely/missing-shell",
+      );
 
       if (process.platform === "win32") {
         expect(
           ptyAdapter.spawnInputs.some(
-            (input) => input.shell === "cmd.exe" || input.shell === "powershell.exe",
+            (input) =>
+              input.shell === "pwsh.exe" ||
+              input.shell === "powershell.exe" ||
+              input.shell === "cmd.exe",
           ),
         ).toBe(true);
       } else {
@@ -848,6 +949,56 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (
     }),
   );
 
+  it.effect("prefers PowerShell over ComSpec for Windows terminals", () =>
+    Effect.gen(function* () {
+      const { manager, ptyAdapter } = yield* createManager(5, {
+        platform: "win32",
+        env: {
+          ComSpec: "C:\\Windows\\System32\\cmd.exe",
+          PATH: "C:\\Windows\\System32",
+          SystemRoot: "C:\\Windows",
+        },
+      });
+
+      yield* manager.open(openInput());
+
+      expect(ptyAdapter.spawnInputs[0]).toEqual(
+        expect.objectContaining({
+          shell: "pwsh.exe",
+          args: ["-NoLogo"],
+        }),
+      );
+    }),
+  );
+
+  it.effect("falls back to built-in PowerShell by absolute path on Windows", () =>
+    Effect.gen(function* () {
+      const { manager, ptyAdapter } = yield* createManager(5, {
+        platform: "win32",
+        env: {
+          ComSpec: "C:\\Windows\\System32\\cmd.exe",
+          PATH: "C:\\Windows\\System32",
+          SystemRoot: "C:\\Windows",
+        },
+        shellResolver: () => "C:\\missing\\custom-shell.exe",
+      });
+      ptyAdapter.spawnFailures.push(
+        new Error("spawn custom-shell.exe ENOENT"),
+        new Error("spawn pwsh.exe ENOENT"),
+      );
+
+      yield* manager.open(openInput());
+
+      expect(ptyAdapter.spawnInputs.map((input) => input.shell)).toEqual([
+        "C:\\missing\\custom-shell.exe",
+        "pwsh.exe",
+        "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
+      ]);
+      expect(ptyAdapter.spawnInputs[1]?.args).toEqual(["-NoLogo"]);
+      expect(ptyAdapter.spawnInputs[2]?.args).toEqual(["-NoLogo"]);
+    }),
+  );
+
   it.effect("filters app runtime env variables from terminal sessions", () =>
     Effect.gen(function* () {
       const originalValues = new Map<string, string | undefined>();
diff --git a/apps/server/src/terminal/Layers/Manager.ts b/apps/server/src/terminal/Layers/Manager.ts
index 4bdeba68e16..9f20ebc8315 100644
--- a/apps/server/src/terminal/Layers/Manager.ts
+++ b/apps/server/src/terminal/Layers/Manager.ts
@@ -1,5 +1,3 @@
-import path from "node:path";
-
 import {
   DEFAULT_TERMINAL_ID,
   type TerminalEvent,
@@ -7,28 +5,28 @@ import {
   type TerminalSessionStatus,
 } from "@t3tools/contracts";
 import { makeKeyedCoalescingWorker } from "@t3tools/shared/KeyedCoalescingWorker";
-import {
-  Effect,
-  Encoding,
-  Equal,
-  Exit,
-  Fiber,
-  FileSystem,
-  Layer,
-  Option,
-  Schema,
-  Scope,
-  Semaphore,
-  SynchronizedRef,
-} from "effect";
-
-import { ServerConfig } from "../../config";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as Equal from "effect/Equal";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+
+import { ServerConfig } from "../../config.ts";
 import {
   increment,
   terminalRestartsTotal,
   terminalSessionsTotal,
-} from "../../observability/Metrics";
-import { runProcess } from "../../processRunner";
+} from "../../observability/Metrics.ts";
+import * as ProcessRunner from "../../processRunner.ts";
 import {
   TerminalCwdError,
   TerminalHistoryError,
@@ -36,14 +34,14 @@ import {
   TerminalNotRunningError,
   TerminalSessionLookupError,
   type TerminalManagerShape,
-} from "../Services/Manager";
+} from "../Services/Manager.ts";
 import {
   PtyAdapter,
   PtySpawnError,
   type PtyAdapterShape,
   type PtyExitEvent,
   type PtyProcess,
-} from "../Services/PTY";
+} from "../Services/PTY.ts";
 
 const DEFAULT_HISTORY_LINE_LIMIT = 5_000;
 const DEFAULT_PERSIST_DEBOUNCE_MS = 40;
@@ -53,6 +51,7 @@ const DEFAULT_MAX_RETAINED_INACTIVE_SESSIONS = 128;
 const DEFAULT_OPEN_COLS = 120;
 const DEFAULT_OPEN_ROWS = 30;
 const TERMINAL_ENV_BLOCKLIST = new Set(["PORT", "ELECTRON_RENDERER_PORT", "ELECTRON_RUN_AS_NODE"]);
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
 
 class TerminalSubprocessCheckError extends Schema.TaggedErrorClass<TerminalSubprocessCheckError>()(
   "TerminalSubprocessCheckError",
@@ -74,7 +73,9 @@ class TerminalProcessSignalError extends Schema.TaggedErrorClass<TerminalProcess
 ) {}
 
 interface TerminalSubprocessChecker {
-  (terminalPid: number): Effect.Effect<boolean, TerminalSubprocessCheckError>;
+  (
+    terminalPid: number,
+  ): Effect.Effect<boolean, TerminalSubprocessCheckError, ProcessRunner.ProcessRunner>;
 }
 
 interface ShellCandidate {
@@ -186,19 +187,25 @@ function enqueueProcessEvent(
   return true;
 }
 
-function defaultShellResolver(): string {
-  if (process.platform === "win32") {
-    return process.env.ComSpec ?? "cmd.exe";
+function defaultShellResolver(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  if (platform === "win32") {
+    return "pwsh.exe";
   }
-  return process.env.SHELL ?? "bash";
+  return env.SHELL ?? "bash";
 }
 
-function normalizeShellCommand(value: string | undefined): string | null {
+function normalizeShellCommand(
+  value: string | undefined,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
   if (!value) return null;
   const trimmed = value.trim();
   if (trimmed.length === 0) return null;
 
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     return trimmed;
   }
 
@@ -207,15 +214,58 @@ function normalizeShellCommand(value: string | undefined): string | null {
   return firstToken.replace(/^['"]|['"]$/g, "");
 }
 
-function shellCandidateFromCommand(command: string | null): ShellCandidate | null {
+function basenameForPlatform(command: string, platform: NodeJS.Platform): string {
+  const normalized =
+    platform === "win32" ? command.replaceAll("/", "\\") : command.replaceAll("\\", "/");
+  const parts = normalized
+    .split(platform === "win32" ? /\\+/ : /\/+/)
+    .filter((part) => part.length > 0);
+  return parts.at(-1) ?? normalized;
+}
+
+function joinWindowsPath(...parts: ReadonlyArray<string>): string {
+  return parts
+    .map((part, index) => {
+      if (index === 0) return part.replace(/[\\/]+$/g, "");
+      return part.replace(/^[\\/]+|[\\/]+$/g, "");
+    })
+    .filter((part) => part.length > 0)
+    .join("\\");
+}
+
+function shellCandidateFromCommand(
+  command: string | null,
+  platform: NodeJS.Platform = process.platform,
+): ShellCandidate | null {
   if (!command || command.length === 0) return null;
-  const shellName = path.basename(command).toLowerCase();
-  if (process.platform !== "win32" && shellName === "zsh") {
+  const shellName = basenameForPlatform(command, platform).toLowerCase();
+  if (platform === "win32" && (shellName === "pwsh.exe" || shellName === "powershell.exe")) {
+    return { shell: command, args: ["-NoLogo"] };
+  }
+  if (platform !== "win32" && shellName === "zsh") {
     return { shell: command, args: ["-o", "nopromptsp"] };
   }
   return { shell: command };
 }
 
+function windowsSystemRoot(env: NodeJS.ProcessEnv): string {
+  return env.SystemRoot?.trim() || env.windir?.trim() || "C:\\Windows";
+}
+
+function windowsPowerShellPath(env: NodeJS.ProcessEnv): string {
+  return joinWindowsPath(
+    windowsSystemRoot(env),
+    "System32",
+    "WindowsPowerShell",
+    "v1.0",
+    "powershell.exe",
+  );
+}
+
+function windowsCmdPath(env: NodeJS.ProcessEnv): string {
+  return joinWindowsPath(windowsSystemRoot(env), "System32", "cmd.exe");
+}
+
 function formatShellCandidate(candidate: ShellCandidate): string {
   if (!candidate.args || candidate.args.length === 0) return candidate.shell;
   return `${candidate.shell} ${candidate.args.join(" ")}`;
@@ -234,27 +284,37 @@ function uniqueShellCandidates(candidates: Array<ShellCandidate | null>): ShellC
   return ordered;
 }
 
-function resolveShellCandidates(shellResolver: () => string): ShellCandidate[] {
-  const requested = shellCandidateFromCommand(normalizeShellCommand(shellResolver()));
+function resolveShellCandidates(
+  shellResolver: () => string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): ShellCandidate[] {
+  const requested = shellCandidateFromCommand(
+    normalizeShellCommand(shellResolver(), platform),
+    platform,
+  );
 
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     return uniqueShellCandidates([
       requested,
-      shellCandidateFromCommand(process.env.ComSpec ?? null),
-      shellCandidateFromCommand("powershell.exe"),
-      shellCandidateFromCommand("cmd.exe"),
+      shellCandidateFromCommand("pwsh.exe", platform),
+      shellCandidateFromCommand(windowsPowerShellPath(env), platform),
+      shellCandidateFromCommand("powershell.exe", platform),
+      shellCandidateFromCommand(env.ComSpec ?? null, platform),
+      shellCandidateFromCommand(windowsCmdPath(env), platform),
+      shellCandidateFromCommand("cmd.exe", platform),
     ]);
   }
 
   return uniqueShellCandidates([
     requested,
-    shellCandidateFromCommand(normalizeShellCommand(process.env.SHELL)),
-    shellCandidateFromCommand("/bin/zsh"),
-    shellCandidateFromCommand("/bin/bash"),
-    shellCandidateFromCommand("/bin/sh"),
-    shellCandidateFromCommand("zsh"),
-    shellCandidateFromCommand("bash"),
-    shellCandidateFromCommand("sh"),
+    shellCandidateFromCommand(normalizeShellCommand(env.SHELL, platform), platform),
+    shellCandidateFromCommand("/bin/zsh", platform),
+    shellCandidateFromCommand("/bin/bash", platform),
+    shellCandidateFromCommand("/bin/sh", platform),
+    shellCandidateFromCommand("zsh", platform),
+    shellCandidateFromCommand("bash", platform),
+    shellCandidateFromCommand("sh", platform),
   ]);
 }
 
@@ -306,66 +366,82 @@ function isRetryableShellSpawnError(error: PtySpawnError): boolean {
 
 function checkWindowsSubprocessActivity(
   terminalPid: number,
-): Effect.Effect<boolean, TerminalSubprocessCheckError> {
+): Effect.Effect<boolean, TerminalSubprocessCheckError, ProcessRunner.ProcessRunner> {
   const command = [
     `$children = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue`,
     "if ($children) { exit 0 }",
     "exit 1",
   ].join("; ");
-  return Effect.tryPromise({
-    try: () =>
-      runProcess("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], {
-        timeoutMs: 1_500,
-        allowNonZeroExit: true,
-        maxBufferBytes: 32_768,
-        outputMode: "truncate",
-      }),
-    catch: (cause) =>
-      new TerminalSubprocessCheckError({
-        message: "Failed to check Windows terminal subprocess activity.",
-        cause,
-        terminalPid,
-        command: "powershell",
-      }),
-  }).pipe(Effect.map((result) => result.code === 0));
+  return Effect.gen(function* () {
+    const processRunner = yield* ProcessRunner.ProcessRunner;
+    return yield* processRunner.run({
+      command: "powershell.exe",
+      args: ["-NoProfile", "-NonInteractive", "-Command", command],
+      timeout: "1500 millis",
+      maxOutputBytes: 32_768,
+      outputMode: "truncate",
+      shell: process.platform === "win32",
+      timeoutBehavior: "timedOutResult",
+    });
+  }).pipe(
+    Effect.map((result) => result.code === 0),
+    Effect.mapError(
+      (cause) =>
+        new TerminalSubprocessCheckError({
+          message: "Failed to check Windows terminal subprocess activity.",
+          cause,
+          terminalPid,
+          command: "powershell",
+        }),
+    ),
+  );
 }
 
 const checkPosixSubprocessActivity = Effect.fn("terminal.checkPosixSubprocessActivity")(function* (
   terminalPid: number,
-): Effect.fn.Return<boolean, TerminalSubprocessCheckError> {
-  const runPgrep = Effect.tryPromise({
-    try: () =>
-      runProcess("pgrep", ["-P", String(terminalPid)], {
-        timeoutMs: 1_000,
-        allowNonZeroExit: true,
-        maxBufferBytes: 32_768,
-        outputMode: "truncate",
-      }),
-    catch: (cause) =>
-      new TerminalSubprocessCheckError({
-        message: "Failed to inspect terminal subprocesses with pgrep.",
-        cause,
-        terminalPid,
-        command: "pgrep",
-      }),
-  });
+): Effect.fn.Return<boolean, TerminalSubprocessCheckError, ProcessRunner.ProcessRunner> {
+  const processRunner = yield* ProcessRunner.ProcessRunner;
+  const runPgrep = processRunner
+    .run({
+      command: "pgrep",
+      args: ["-P", String(terminalPid)],
+      timeout: "1 second",
+      maxOutputBytes: 32_768,
+      outputMode: "truncate",
+      timeoutBehavior: "timedOutResult",
+    })
+    .pipe(
+      Effect.mapError(
+        (cause) =>
+          new TerminalSubprocessCheckError({
+            message: "Failed to inspect terminal subprocesses with pgrep.",
+            cause,
+            terminalPid,
+            command: "pgrep",
+          }),
+      ),
+    );
 
-  const runPs = Effect.tryPromise({
-    try: () =>
-      runProcess("ps", ["-eo", "pid=,ppid="], {
-        timeoutMs: 1_000,
-        allowNonZeroExit: true,
-        maxBufferBytes: 262_144,
-        outputMode: "truncate",
-      }),
-    catch: (cause) =>
-      new TerminalSubprocessCheckError({
-        message: "Failed to inspect terminal subprocesses with ps.",
-        cause,
-        terminalPid,
-        command: "ps",
-      }),
-  });
+  const runPs = processRunner
+    .run({
+      command: "ps",
+      args: ["-eo", "pid=,ppid="],
+      timeout: "1 second",
+      maxOutputBytes: 262_144,
+      outputMode: "truncate",
+      timeoutBehavior: "timedOutResult",
+    })
+    .pipe(
+      Effect.mapError(
+        (cause) =>
+          new TerminalSubprocessCheckError({
+            message: "Failed to inspect terminal subprocesses with ps.",
+            cause,
+            terminalPid,
+            command: "ps",
+          }),
+      ),
+    );
 
   const pgrepResult = yield* Effect.exit(runPgrep);
   if (pgrepResult._tag === "Success") {
@@ -396,7 +472,7 @@ const checkPosixSubprocessActivity = Effect.fn("terminal.checkPosixSubprocessAct
 
 const defaultSubprocessChecker = Effect.fn("terminal.defaultSubprocessChecker")(function* (
   terminalPid: number,
-): Effect.fn.Return<boolean, TerminalSubprocessCheckError> {
+): Effect.fn.Return<boolean, TerminalSubprocessCheckError, ProcessRunner.ProcessRunner> {
   if (!Number.isInteger(terminalPid) || terminalPid <= 0) {
     return false;
   }
@@ -651,6 +727,8 @@ interface TerminalManagerOptions {
   historyLineLimit?: number;
   ptyAdapter: PtyAdapterShape;
   shellResolver?: () => string;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
   subprocessChecker?: TerminalSubprocessChecker;
   subprocessPollIntervalMs?: number;
   processKillGraceMs?: number;
@@ -669,13 +747,22 @@ const makeTerminalManager = Effect.fn("makeTerminalManager")(function* () {
 export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWithOptions")(
   function* (options: TerminalManagerOptions) {
     const fileSystem = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
     const context = yield* Effect.context<never>();
     const runFork = Effect.runForkWith(context);
 
     const logsDir = options.logsDir;
     const historyLineLimit = options.historyLineLimit ?? DEFAULT_HISTORY_LINE_LIMIT;
-    const shellResolver = options.shellResolver ?? defaultShellResolver;
-    const subprocessChecker = options.subprocessChecker ?? defaultSubprocessChecker;
+    const platform = options.platform ?? process.platform;
+    const baseEnv = options.env ?? process.env;
+    const shellResolver = options.shellResolver ?? (() => defaultShellResolver(platform, baseEnv));
+    const processRunner = yield* ProcessRunner.ProcessRunner;
+    const subprocessChecker =
+      options.subprocessChecker ??
+      ((terminalPid) =>
+        defaultSubprocessChecker(terminalPid).pipe(
+          Effect.provideService(ProcessRunner.ProcessRunner, processRunner),
+        ));
     const subprocessPollIntervalMs =
       options.subprocessPollIntervalMs ?? DEFAULT_SUBPROCESS_POLL_INTERVAL_MS;
     const processKillGraceMs = options.processKillGraceMs ?? DEFAULT_PROCESS_KILL_GRACE_MS;
@@ -1113,6 +1200,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
       expectedPid: number,
     ) {
       while (true) {
+        const updatedAt = yield* nowIso;
         const action: DrainProcessEventAction = yield* Effect.sync(() => {
           if (session.pid !== expectedPid || !session.process || session.status !== "running") {
             session.pendingProcessEvents = [];
@@ -1147,7 +1235,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
                 historyLineLimit,
               );
             }
-            session.updatedAt = new Date().toISOString();
+            session.updatedAt = updatedAt;
 
             return {
               type: "output",
@@ -1174,7 +1262,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
           session.exitSignal = Number.isInteger(nextEvent.event.signal)
             ? nextEvent.event.signal
             : null;
-          session.updatedAt = new Date().toISOString();
+          session.updatedAt = updatedAt;
 
           return {
             type: "exit",
@@ -1195,22 +1283,24 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
             yield* queuePersist(action.threadId, action.terminalId, action.history);
           }
 
+          const createdAt = yield* nowIso;
           yield* publishEvent({
             type: "output",
             threadId: action.threadId,
             terminalId: action.terminalId,
-            createdAt: new Date().toISOString(),
+            createdAt,
             data: action.data,
           });
           continue;
         }
 
         yield* clearKillFiber(action.process);
+        const createdAt = yield* nowIso;
         yield* publishEvent({
           type: "exited",
           threadId: action.threadId,
           terminalId: action.terminalId,
-          createdAt: new Date().toISOString(),
+          createdAt,
           exitCode: action.exitCode,
           exitSignal: action.exitSignal,
         });
@@ -1225,6 +1315,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
       const process = session.process;
       if (!process) return;
 
+      const updatedAt = yield* nowIso;
       yield* modifyManagerState((state) => {
         cleanupProcessHandles(session);
         session.process = null;
@@ -1235,7 +1326,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         session.pendingProcessEvents = [];
         session.pendingProcessEventIndex = 0;
         session.processEventDrainRunning = false;
-        session.updatedAt = new Date().toISOString();
+        session.updatedAt = updatedAt;
         return [undefined, state] as const;
       });
 
@@ -1314,6 +1405,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         "terminal.cwd": input.cwd,
       });
 
+      const startingAt = yield* nowIso;
       yield* modifyManagerState((state) => {
         session.status = "starting";
         session.cwd = input.cwd;
@@ -1326,7 +1418,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         session.pendingProcessEvents = [];
         session.pendingProcessEventIndex = 0;
         session.processEventDrainRunning = false;
-        session.updatedAt = new Date().toISOString();
+        session.updatedAt = startingAt;
         return [undefined, state] as const;
       });
 
@@ -1337,8 +1429,8 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         increment(terminalSessionsTotal, { lifecycle: eventType }).pipe(
           Effect.andThen(
             Effect.gen(function* () {
-              const shellCandidates = resolveShellCandidates(shellResolver);
-              const terminalEnv = createTerminalSpawnEnv(process.env, session.runtimeEnv);
+              const shellCandidates = resolveShellCandidates(shellResolver, platform, baseEnv);
+              const terminalEnv = createTerminalSpawnEnv(baseEnv, session.runtimeEnv);
               const spawnResult = yield* trySpawn(shellCandidates, terminalEnv, session);
               ptyProcess = spawnResult.process;
               startedShell = spawnResult.shellLabel;
@@ -1357,21 +1449,23 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
                 runFork(drainProcessEvents(session, processPid));
               });
 
+              const runningAt = yield* nowIso;
               yield* modifyManagerState((state) => {
                 session.process = ptyProcess;
                 session.pid = processPid;
                 session.status = "running";
-                session.updatedAt = new Date().toISOString();
+                session.updatedAt = runningAt;
                 session.unsubscribeData = unsubscribeData;
                 session.unsubscribeExit = unsubscribeExit;
                 return [undefined, state] as const;
               });
 
+              const createdAt = yield* nowIso;
               yield* publishEvent({
                 type: eventType,
                 threadId: session.threadId,
                 terminalId: session.terminalId,
-                createdAt: new Date().toISOString(),
+                createdAt,
                 snapshot: snapshot(session),
               });
             }),
@@ -1388,6 +1482,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         if (ptyProcess) {
           yield* startKillEscalation(ptyProcess, session.threadId, session.terminalId);
         }
+        const erroredAt = yield* nowIso;
 
         yield* modifyManagerState((state) => {
           session.status = "error";
@@ -1399,18 +1494,19 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
           session.pendingProcessEvents = [];
           session.pendingProcessEventIndex = 0;
           session.processEventDrainRunning = false;
-          session.updatedAt = new Date().toISOString();
+          session.updatedAt = erroredAt;
           return [undefined, state] as const;
         });
 
         yield* evictInactiveSessionsIfNeeded();
 
         const message = error.message;
+        const createdAt = yield* nowIso;
         yield* publishEvent({
           type: "error",
           threadId: session.threadId,
           terminalId: session.terminalId,
-          createdAt: new Date().toISOString(),
+          createdAt,
           message,
         });
         yield* Effect.logError("failed to start terminal", {
@@ -1482,6 +1578,8 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
           return;
         }
 
+        const updatedAt = yield* nowIso;
+        const createdAt = yield* nowIso;
         const event = yield* modifyManagerState((state) => {
           const liveSession: Option.Option<TerminalSessionState> = Option.fromNullishOr(
             state.sessions.get(toSessionKey(session.threadId, session.terminalId)),
@@ -1496,14 +1594,14 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
           }
 
           liveSession.value.hasRunningSubprocess = hasRunningSubprocess.value;
-          liveSession.value.updatedAt = new Date().toISOString();
+          liveSession.value.updatedAt = updatedAt;
 
           return [
             Option.some({
               type: "activity" as const,
               threadId: liveSession.value.threadId,
               terminalId: liveSession.value.terminalId,
-              createdAt: new Date().toISOString(),
+              createdAt,
               hasRunningSubprocess: hasRunningSubprocess.value,
             }),
             state,
@@ -1582,6 +1680,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
             const history = yield* readHistory(input.threadId, terminalId);
             const cols = input.cols ?? DEFAULT_OPEN_COLS;
             const rows = input.rows ?? DEFAULT_OPEN_ROWS;
+            const createdAt = yield* nowIso;
             const session: TerminalSessionState = {
               threadId: input.threadId,
               terminalId,
@@ -1596,7 +1695,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
               processEventDrainRunning: false,
               exitCode: null,
               exitSignal: null,
-              updatedAt: new Date().toISOString(),
+              updatedAt: createdAt,
               cols,
               rows,
               process: null,
@@ -1687,7 +1786,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
           if (liveSession.cols !== targetCols || liveSession.rows !== targetRows) {
             liveSession.cols = targetCols;
             liveSession.rows = targetRows;
-            liveSession.updatedAt = new Date().toISOString();
+            liveSession.updatedAt = yield* nowIso;
             liveSession.process.resize(targetCols, targetRows);
           }
 
@@ -1721,7 +1820,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
       }
       session.cols = input.cols;
       session.rows = input.rows;
-      session.updatedAt = new Date().toISOString();
+      session.updatedAt = yield* nowIso;
       yield* Effect.sync(() => process.resize(input.cols, input.rows));
     });
 
@@ -1731,18 +1830,20 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
         Effect.gen(function* () {
           const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;
           const session = yield* requireSession(input.threadId, terminalId);
+          const updatedAt = yield* nowIso;
           session.history = "";
           session.pendingHistoryControlSequence = "";
           session.pendingProcessEvents = [];
           session.pendingProcessEventIndex = 0;
           session.processEventDrainRunning = false;
-          session.updatedAt = new Date().toISOString();
+          session.updatedAt = updatedAt;
           yield* persistHistory(input.threadId, terminalId, session.history);
+          const createdAt = yield* nowIso;
           yield* publishEvent({
             type: "cleared",
             threadId: input.threadId,
             terminalId,
-            createdAt: new Date().toISOString(),
+            createdAt,
           });
         }),
       );
@@ -1761,6 +1862,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
           if (Option.isNone(existingSession)) {
             const cols = input.cols ?? DEFAULT_OPEN_COLS;
             const rows = input.rows ?? DEFAULT_OPEN_ROWS;
+            const createdAt = yield* nowIso;
             session = {
               threadId: input.threadId,
               terminalId,
@@ -1775,7 +1877,7 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
               processEventDrainRunning: false,
               exitCode: null,
               exitSignal: null,
-              updatedAt: new Date().toISOString(),
+              updatedAt: createdAt,
               cols,
               rows,
               process: null,
@@ -1865,4 +1967,6 @@ export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWith
   },
 );
 
-export const TerminalManagerLive = Layer.effect(TerminalManager, makeTerminalManager());
+export const TerminalManagerLive = Layer.effect(TerminalManager, makeTerminalManager()).pipe(
+  Layer.provide(ProcessRunner.layer),
+);
diff --git a/apps/server/src/terminal/Layers/NodePTY.test.ts b/apps/server/src/terminal/Layers/NodePTY.test.ts
index 58fcc70e4e5..15d24360f7e 100644
--- a/apps/server/src/terminal/Layers/NodePTY.test.ts
+++ b/apps/server/src/terminal/Layers/NodePTY.test.ts
@@ -1,7 +1,9 @@
-import { FileSystem, Path, Effect } from "effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
 import { assert, it } from "@effect/vitest";
 
-import { ensureNodePtySpawnHelperExecutable } from "./NodePTY";
+import { ensureNodePtySpawnHelperExecutable } from "./NodePTY.ts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 
 it.layer(NodeServices.layer)("ensureNodePtySpawnHelperExecutable", (it) => {
diff --git a/apps/server/src/terminal/Layers/NodePTY.ts b/apps/server/src/terminal/Layers/NodePTY.ts
index cf1fdd21982..c81d76f5d1e 100644
--- a/apps/server/src/terminal/Layers/NodePTY.ts
+++ b/apps/server/src/terminal/Layers/NodePTY.ts
@@ -1,7 +1,16 @@
 import { createRequire } from "node:module";
 
-import { Effect, FileSystem, Layer, Path } from "effect";
-import { PtyAdapter, PtyAdapterShape, PtyExitEvent, PtyProcess } from "../Services/PTY";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { PtyAdapter } from "../Services/PTY.ts";
+import {
+  PtySpawnError,
+  type PtyAdapterShape,
+  type PtyExitEvent,
+  type PtyProcess,
+} from "../Services/PTY.ts";
 
 let didEnsureSpawnHelperExecutable = false;
 
@@ -46,7 +55,11 @@ export const ensureNodePtySpawnHelperExecutable = Effect.fn(function* (explicitP
 });
 
 class NodePtyProcess implements PtyProcess {
-  constructor(private readonly process: import("node-pty").IPty) {}
+  private readonly process: import("node-pty").IPty;
+
+  constructor(process: import("node-pty").IPty) {
+    this.process = process;
+  }
 
   get pid(): number {
     return this.process.pid;
@@ -103,12 +116,21 @@ export const layer = Layer.effect(
     return {
       spawn: Effect.fn(function* (input) {
         yield* ensureNodePtySpawnHelperExecutableCached;
-        const ptyProcess = nodePty.spawn(input.shell, input.args ?? [], {
-          cwd: input.cwd,
-          cols: input.cols,
-          rows: input.rows,
-          env: input.env,
-          name: globalThis.process.platform === "win32" ? "xterm-color" : "xterm-256color",
+        const ptyProcess = yield* Effect.try({
+          try: () =>
+            nodePty.spawn(input.shell, input.args ?? [], {
+              cwd: input.cwd,
+              cols: input.cols,
+              rows: input.rows,
+              env: input.env,
+              name: globalThis.process.platform === "win32" ? "xterm-color" : "xterm-256color",
+            }),
+          catch: (cause) =>
+            new PtySpawnError({
+              adapter: "node-pty",
+              message: cause instanceof Error ? cause.message : "Failed to spawn PTY process",
+              cause,
+            }),
         });
         return new NodePtyProcess(ptyProcess);
       }),
diff --git a/apps/server/src/terminal/Services/Manager.ts b/apps/server/src/terminal/Services/Manager.ts
index b59c4721cd3..6db23d571b2 100644
--- a/apps/server/src/terminal/Services/Manager.ts
+++ b/apps/server/src/terminal/Services/Manager.ts
@@ -22,8 +22,9 @@ import {
   TerminalSessionStatus,
   TerminalWriteInput,
 } from "@t3tools/contracts";
-import { PtyProcess } from "./PTY";
-import { Effect, Context } from "effect";
+import type { PtyProcess } from "./PTY.ts";
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
 
 export {
   TerminalCwdError,
diff --git a/apps/server/src/terminal/Services/PTY.ts b/apps/server/src/terminal/Services/PTY.ts
index 091e527ef2b..93cd1b0d47b 100644
--- a/apps/server/src/terminal/Services/PTY.ts
+++ b/apps/server/src/terminal/Services/PTY.ts
@@ -6,7 +6,9 @@
  *
  * @module PtyAdapter
  */
-import { Effect, Schema, Context } from "effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
 
 /**
  * PtyError - Error type for PTY adapter operations.
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
new file mode 100644
index 00000000000..9ee546728d0
--- /dev/null
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
@@ -0,0 +1,345 @@
+import { ClaudeSettings, ProviderInstanceId } from "@t3tools/contracts";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { createModelSelection } from "@t3tools/shared/model";
+import { expect } from "vitest";
+
+import { ServerConfig } from "../config.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
+import { sanitizeThreadTitle } from "./TextGenerationUtils.ts";
+import { makeClaudeTextGeneration } from "./ClaudeTextGeneration.ts";
+const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
+
+const ClaudeTextGenerationTestLayer = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3code-claude-text-generation-test-",
+}).pipe(Layer.provideMerge(NodeServices.layer));
+
+function makeFakeClaudeBinary(dir: string) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const binDir = path.join(dir, "bin");
+    const claudePath = path.join(binDir, "claude");
+    yield* fs.makeDirectory(binDir, { recursive: true });
+
+    yield* fs.writeFileString(
+      claudePath,
+      [
+        "#!/bin/sh",
+        'args="$*"',
+        'stdin_content="$(cat)"',
+        'if [ -n "$T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN" ]; then',
+        '  printf "%s" "$args" | grep -F -- "$T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN" >/dev/null || {',
+        '    printf "%s\\n" "args missing expected content" >&2',
+        "    exit 2",
+        "  }",
+        "fi",
+        'if [ -n "$T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN" ]; then',
+        '  if printf "%s" "$args" | grep -F -- "$T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN" >/dev/null; then',
+        '    printf "%s\\n" "args contained forbidden content" >&2',
+        "    exit 3",
+        "  fi",
+        "fi",
+        'if [ -n "$T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN" ]; then',
+        '  printf "%s" "$stdin_content" | grep -F -- "$T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN" >/dev/null || {',
+        '    printf "%s\\n" "stdin missing expected content" >&2',
+        "    exit 4",
+        "  }",
+        "fi",
+        'if [ -n "$T3_FAKE_CLAUDE_HOME_MUST_BE" ] && [ "$HOME" != "$T3_FAKE_CLAUDE_HOME_MUST_BE" ]; then',
+        '  printf "%s\\n" "HOME was $HOME" >&2',
+        "  exit 5",
+        "fi",
+        'if [ -n "$T3_FAKE_CLAUDE_STDERR" ]; then',
+        '  printf "%s\\n" "$T3_FAKE_CLAUDE_STDERR" >&2',
+        "fi",
+        'printf "%s" "$T3_FAKE_CLAUDE_OUTPUT"',
+        'exit "${T3_FAKE_CLAUDE_EXIT_CODE:-0}"',
+        "",
+      ].join("\n"),
+    );
+    yield* fs.chmod(claudePath, 0o755);
+    return binDir;
+  });
+}
+
+function withFakeClaudeEnv<A, E, R>(
+  input: {
+    output: string;
+    exitCode?: number;
+    stderr?: string;
+    argsMustContain?: string;
+    argsMustNotContain?: string;
+    stdinMustContain?: string;
+    homeMustBe?: string;
+    claudeConfig?: Partial<ClaudeSettings>;
+  },
+  effectFn: (textGeneration: TextGenerationShape) => Effect.Effect<A, E, R>,
+) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-claude-text-" });
+    const binDir = yield* makeFakeClaudeBinary(tempDir);
+    const previousPath = process.env.PATH;
+    const previousOutput = process.env.T3_FAKE_CLAUDE_OUTPUT;
+    const previousExitCode = process.env.T3_FAKE_CLAUDE_EXIT_CODE;
+    const previousStderr = process.env.T3_FAKE_CLAUDE_STDERR;
+    const previousArgsMustContain = process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN;
+    const previousArgsMustNotContain = process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN;
+    const previousStdinMustContain = process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN;
+    const previousHomeMustBe = process.env.T3_FAKE_CLAUDE_HOME_MUST_BE;
+
+    yield* Effect.acquireRelease(
+      Effect.sync(() => {
+        process.env.PATH = `${binDir}:${previousPath ?? ""}`;
+        process.env.T3_FAKE_CLAUDE_OUTPUT = input.output;
+
+        if (input.exitCode !== undefined) {
+          process.env.T3_FAKE_CLAUDE_EXIT_CODE = String(input.exitCode);
+        } else {
+          delete process.env.T3_FAKE_CLAUDE_EXIT_CODE;
+        }
+
+        if (input.stderr !== undefined) {
+          process.env.T3_FAKE_CLAUDE_STDERR = input.stderr;
+        } else {
+          delete process.env.T3_FAKE_CLAUDE_STDERR;
+        }
+
+        if (input.argsMustContain !== undefined) {
+          process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN = input.argsMustContain;
+        } else {
+          delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN;
+        }
+
+        if (input.argsMustNotContain !== undefined) {
+          process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN = input.argsMustNotContain;
+        } else {
+          delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN;
+        }
+
+        if (input.stdinMustContain !== undefined) {
+          process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN = input.stdinMustContain;
+        } else {
+          delete process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN;
+        }
+
+        if (input.homeMustBe !== undefined) {
+          process.env.T3_FAKE_CLAUDE_HOME_MUST_BE = input.homeMustBe;
+        } else {
+          delete process.env.T3_FAKE_CLAUDE_HOME_MUST_BE;
+        }
+      }),
+      () =>
+        Effect.sync(() => {
+          process.env.PATH = previousPath;
+
+          if (previousOutput === undefined) {
+            delete process.env.T3_FAKE_CLAUDE_OUTPUT;
+          } else {
+            process.env.T3_FAKE_CLAUDE_OUTPUT = previousOutput;
+          }
+
+          if (previousExitCode === undefined) {
+            delete process.env.T3_FAKE_CLAUDE_EXIT_CODE;
+          } else {
+            process.env.T3_FAKE_CLAUDE_EXIT_CODE = previousExitCode;
+          }
+
+          if (previousStderr === undefined) {
+            delete process.env.T3_FAKE_CLAUDE_STDERR;
+          } else {
+            process.env.T3_FAKE_CLAUDE_STDERR = previousStderr;
+          }
+
+          if (previousArgsMustContain === undefined) {
+            delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN;
+          } else {
+            process.env.T3_FAKE_CLAUDE_ARGS_MUST_CONTAIN = previousArgsMustContain;
+          }
+
+          if (previousArgsMustNotContain === undefined) {
+            delete process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN;
+          } else {
+            process.env.T3_FAKE_CLAUDE_ARGS_MUST_NOT_CONTAIN = previousArgsMustNotContain;
+          }
+
+          if (previousStdinMustContain === undefined) {
+            delete process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN;
+          } else {
+            process.env.T3_FAKE_CLAUDE_STDIN_MUST_CONTAIN = previousStdinMustContain;
+          }
+
+          if (previousHomeMustBe === undefined) {
+            delete process.env.T3_FAKE_CLAUDE_HOME_MUST_BE;
+          } else {
+            process.env.T3_FAKE_CLAUDE_HOME_MUST_BE = previousHomeMustBe;
+          }
+        }),
+    );
+
+    const config = decodeClaudeSettings(input.claudeConfig ?? {});
+    const textGeneration = yield* makeClaudeTextGeneration(config);
+    return yield* effectFn(textGeneration);
+  }).pipe(Effect.scoped);
+}
+
+it.layer(ClaudeTextGenerationTestLayer)("ClaudeTextGeneration", (it) => {
+  it.effect("forwards Claude thinking settings for Haiku without passing effort", () =>
+    withFakeClaudeEnv(
+      {
+        output: JSON.stringify({
+          structured_output: {
+            subject: "Add important change",
+            body: "",
+          },
+        }),
+        argsMustContain: '--settings {"alwaysThinkingEnabled":false}',
+        argsMustNotContain: "--effort",
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/claude-effect",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            modelSelection: {
+              ...createModelSelection(ProviderInstanceId.make("claudeAgent"), "claude-haiku-4-5", [
+                { id: "thinking", value: false },
+                { id: "effort", value: "high" },
+              ]),
+            },
+          });
+
+          expect(generated.subject).toBe("Add important change");
+        }),
+    ),
+  );
+
+  it.effect("forwards Claude fast mode and supported effort", () =>
+    withFakeClaudeEnv(
+      {
+        output: JSON.stringify({
+          structured_output: {
+            title: "Improve orchestration flow",
+            body: "Body",
+          },
+        }),
+        argsMustContain: '--effort max --settings {"fastMode":true}',
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generatePrContent({
+            cwd: process.cwd(),
+            baseBranch: "main",
+            headBranch: "feature/claude-effect",
+            commitSummary: "Improve orchestration",
+            diffSummary: "1 file changed",
+            diffPatch: "diff --git a/README.md b/README.md",
+            modelSelection: {
+              ...createModelSelection(ProviderInstanceId.make("claudeAgent"), "claude-opus-4-6", [
+                { id: "effort", value: "max" },
+                { id: "fastMode", value: true },
+              ]),
+            },
+          });
+
+          expect(generated.title).toBe("Improve orchestration flow");
+        }),
+    ),
+  );
+
+  it.effect("generates thread titles through the Claude provider", () =>
+    withFakeClaudeEnv(
+      {
+        output: JSON.stringify({
+          structured_output: {
+            title:
+              '  "Reconnect failures after restart because the session state does not recover"  ',
+          },
+        }),
+        stdinMustContain: "You write concise thread titles for coding conversations.",
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateThreadTitle({
+            cwd: process.cwd(),
+            message: "Please investigate reconnect failures after restarting the session.",
+            modelSelection: {
+              instanceId: ProviderInstanceId.make("claudeAgent"),
+              model: "claude-sonnet-4-6",
+            },
+          });
+
+          expect(generated.title).toBe(
+            sanitizeThreadTitle(
+              '"Reconnect failures after restart because the session state does not recover"',
+            ),
+          );
+        }),
+    ),
+  );
+
+  it.effect("runs Claude text generation with the configured Claude HOME", () =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const claudeHome = path.join(process.cwd(), ".claude-work-test");
+      return yield* withFakeClaudeEnv(
+        {
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
+          output: JSON.stringify({
+            structured_output: {
+              title: "Use Claude home",
+            },
+          }),
+          homeMustBe: claudeHome,
+          claudeConfig: { homePath: claudeHome },
+        },
+        (textGeneration) =>
+          Effect.gen(function* () {
+            const generated = yield* textGeneration.generateThreadTitle({
+              cwd: process.cwd(),
+              message: "thread title",
+              modelSelection: {
+                instanceId: ProviderInstanceId.make("claudeAgent"),
+                model: "claude-sonnet-4-6",
+              },
+            });
+
+            expect(generated.title).toBe(sanitizeThreadTitle("Use Claude home"));
+          }),
+      );
+    }),
+  );
+
+  it.effect("falls back when Claude thread title normalization becomes whitespace-only", () =>
+    withFakeClaudeEnv(
+      {
+        output: JSON.stringify({
+          structured_output: {
+            title: '  """   """  ',
+          },
+        }),
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateThreadTitle({
+            cwd: process.cwd(),
+            message: "Name this thread.",
+            modelSelection: {
+              instanceId: ProviderInstanceId.make("claudeAgent"),
+              model: "claude-sonnet-4-6",
+            },
+          });
+
+          expect(generated.title).toBe("New thread");
+        }),
+    ),
+  );
+});
diff --git a/apps/server/src/git/Layers/ClaudeTextGeneration.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
similarity index 69%
rename from apps/server/src/git/Layers/ClaudeTextGeneration.ts
rename to apps/server/src/textGeneration/ClaudeTextGeneration.ts
index 99ca21b06d4..3c1e8c69673 100644
--- a/apps/server/src/git/Layers/ClaudeTextGeneration.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
@@ -7,31 +7,41 @@
  *
  * @module ClaudeTextGeneration
  */
-import { Effect, Layer, Option, Schema, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
-import { ClaudeModelSelection } from "@t3tools/contracts";
-import { resolveApiModelId } from "@t3tools/shared/model";
+import { type ClaudeSettings, type ModelSelection } from "@t3tools/contracts";
 import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
 
 import { TextGenerationError } from "@t3tools/contracts";
-import { type TextGenerationShape, TextGeneration } from "../Services/TextGeneration.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
 import {
   buildBranchNamePrompt,
   buildCommitMessagePrompt,
   buildPrContentPrompt,
   buildThreadTitlePrompt,
-} from "../Prompts.ts";
+} from "./TextGenerationPrompts.ts";
 import {
   normalizeCliError,
   sanitizeCommitSubject,
   sanitizePrTitle,
   sanitizeThreadTitle,
   toJsonSchemaObject,
-} from "../Utils.ts";
-import { normalizeClaudeModelOptionsWithCapabilities } from "@t3tools/shared/model";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { getClaudeModelCapabilities } from "../../provider/Layers/ClaudeProvider.ts";
+} from "./TextGenerationUtils.ts";
+import {
+  getModelSelectionStringOptionValue,
+  getProviderOptionDescriptors,
+} from "@t3tools/shared/model";
+import {
+  getClaudeModelCapabilities,
+  normalizeClaudeCliEffort,
+  resolveClaudeApiModelId,
+  resolveClaudeEffort,
+} from "../provider/Layers/ClaudeProvider.ts";
+import { makeClaudeEnvironment } from "../provider/Drivers/ClaudeHome.ts";
 
 const CLAUDE_TIMEOUT_MS = 180_000;
 
@@ -43,9 +53,15 @@ const ClaudeOutputEnvelope = Schema.Struct({
   structured_output: Schema.Unknown,
 });
 
-const makeClaudeTextGeneration = Effect.gen(function* () {
+const encodeJsonString = Schema.encodeEffect(Schema.UnknownFromJsonString);
+const decodeClaudeOutputEnvelope = Schema.decodeEffect(Schema.fromJsonString(ClaudeOutputEnvelope));
+
+export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(function* (
+  claudeSettings: ClaudeSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
   const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-  const serverSettingsService = yield* Effect.service(ServerSettingsService);
+  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
 
   const readStreamAsString = <E>(
     operation: string,
@@ -62,6 +78,26 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
       ),
     );
 
+  const encodeJsonForOperation = (
+    operation:
+      | "generateCommitMessage"
+      | "generatePrContent"
+      | "generateBranchName"
+      | "generateThreadTitle",
+    value: unknown,
+    detail: string,
+  ): Effect.Effect<string, TextGenerationError> =>
+    encodeJsonString(value).pipe(
+      Effect.mapError(
+        (cause) =>
+          new TextGenerationError({
+            operation,
+            detail,
+            cause,
+          }),
+      ),
+    );
+
   /**
    * Spawn the Claude CLI with structured JSON output and return the parsed,
    * schema-validated result.
@@ -81,28 +117,44 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
     cwd: string;
     prompt: string;
     outputSchemaJson: S;
-    modelSelection: ClaudeModelSelection;
+    modelSelection: ModelSelection;
   }): Effect.fn.Return<S["Type"], TextGenerationError, S["DecodingServices"]> {
-    const jsonSchemaStr = JSON.stringify(toJsonSchemaObject(outputSchemaJson));
-    const normalizedOptions = normalizeClaudeModelOptionsWithCapabilities(
-      getClaudeModelCapabilities(modelSelection.model),
-      modelSelection.options,
+    const jsonSchemaStr = yield* encodeJsonForOperation(
+      operation,
+      toJsonSchemaObject(outputSchemaJson),
+      "Failed to encode structured output schema.",
     );
+    const caps = getClaudeModelCapabilities(modelSelection.model);
+    const descriptors = getProviderOptionDescriptors({
+      caps,
+      selections: modelSelection.options,
+    });
+    const findDescriptor = (id: string) => descriptors.find((descriptor) => descriptor.id === id);
+    const rawEffortSelection = getModelSelectionStringOptionValue(modelSelection, "effort");
+    const resolvedEffort = resolveClaudeEffort(caps, rawEffortSelection);
+    const cliEffort = normalizeClaudeCliEffort(resolvedEffort);
+    const thinkingDescriptor = findDescriptor("thinking");
+    const fastModeDescriptor = findDescriptor("fastMode");
+    const thinking =
+      thinkingDescriptor?.type === "boolean" ? thinkingDescriptor.currentValue : undefined;
+    const fastMode =
+      fastModeDescriptor?.type === "boolean" ? fastModeDescriptor.currentValue : undefined;
     const settings = {
-      ...(typeof normalizedOptions?.thinking === "boolean"
-        ? { alwaysThinkingEnabled: normalizedOptions.thinking }
-        : {}),
-      ...(normalizedOptions?.fastMode ? { fastMode: true } : {}),
+      ...(typeof thinking === "boolean" ? { alwaysThinkingEnabled: thinking } : {}),
+      ...(fastMode ? { fastMode: true } : {}),
     };
-
-    const claudeSettings = yield* Effect.map(
-      serverSettingsService.getSettings,
-      (settings) => settings.providers.claudeAgent,
-    ).pipe(Effect.catch(() => Effect.undefined));
+    const settingsJson =
+      Object.keys(settings).length > 0
+        ? yield* encodeJsonForOperation(
+            operation,
+            settings,
+            "Failed to encode Claude CLI settings.",
+          )
+        : undefined;
 
     const runClaudeCommand = Effect.fn("runClaudeJson.runClaudeCommand")(function* () {
       const command = ChildProcess.make(
-        claudeSettings?.binaryPath || "claude",
+        claudeSettings.binaryPath || "claude",
         [
           "-p",
           "--output-format",
@@ -110,12 +162,13 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
           "--json-schema",
           jsonSchemaStr,
           "--model",
-          resolveApiModelId(modelSelection),
-          ...(normalizedOptions?.effort ? ["--effort", normalizedOptions.effort] : []),
-          ...(Object.keys(settings).length > 0 ? ["--settings", JSON.stringify(settings)] : []),
+          resolveClaudeApiModelId(modelSelection),
+          ...(cliEffort ? ["--effort", cliEffort] : []),
+          ...(settingsJson ? ["--settings", settingsJson] : []),
           "--dangerously-skip-permissions",
         ],
         {
+          env: claudeEnvironment,
           cwd,
           shell: process.platform === "win32",
           stdin: {
@@ -175,9 +228,7 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
       ),
     );
 
-    const envelope = yield* Schema.decodeEffect(Schema.fromJsonString(ClaudeOutputEnvelope))(
-      rawStdout,
-    ).pipe(
+    const envelope = yield* decodeClaudeOutputEnvelope(rawStdout).pipe(
       Effect.catchTag("SchemaError", (cause) =>
         Effect.fail(
           new TextGenerationError({
@@ -189,7 +240,8 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
       ),
     );
 
-    return yield* Schema.decodeEffect(outputSchemaJson)(envelope.structured_output).pipe(
+    const decodeOutput = Schema.decodeEffect(outputSchemaJson);
+    return yield* decodeOutput(envelope.structured_output).pipe(
       Effect.catchTag("SchemaError", (cause) =>
         Effect.fail(
           new TextGenerationError({
@@ -216,13 +268,6 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
       includeBranch: input.includeBranch === true,
     });
 
-    if (input.modelSelection.provider !== "claudeAgent") {
-      return yield* new TextGenerationError({
-        operation: "generateCommitMessage",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runClaudeJson({
       operation: "generateCommitMessage",
       cwd: input.cwd,
@@ -251,13 +296,6 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
       diffPatch: input.diffPatch,
     });
 
-    if (input.modelSelection.provider !== "claudeAgent") {
-      return yield* new TextGenerationError({
-        operation: "generatePrContent",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runClaudeJson({
       operation: "generatePrContent",
       cwd: input.cwd,
@@ -280,13 +318,6 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
       attachments: input.attachments,
     });
 
-    if (input.modelSelection.provider !== "claudeAgent") {
-      return yield* new TextGenerationError({
-        operation: "generateBranchName",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runClaudeJson({
       operation: "generateBranchName",
       cwd: input.cwd,
@@ -308,13 +339,6 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
       attachments: input.attachments,
     });
 
-    if (input.modelSelection.provider !== "claudeAgent") {
-      return yield* new TextGenerationError({
-        operation: "generateThreadTitle",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runClaudeJson({
       operation: "generateThreadTitle",
       cwd: input.cwd,
@@ -335,5 +359,3 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
     generateThreadTitle,
   } satisfies TextGenerationShape;
 });
-
-export const ClaudeTextGenerationLive = Layer.effect(TextGeneration, makeClaudeTextGeneration);
diff --git a/apps/server/src/git/Layers/CodexTextGeneration.test.ts b/apps/server/src/textGeneration/CodexTextGeneration.test.ts
similarity index 50%
rename from apps/server/src/git/Layers/CodexTextGeneration.test.ts
rename to apps/server/src/textGeneration/CodexTextGeneration.test.ts
index a07505f025c..87a2f95fbf5 100644
--- a/apps/server/src/git/Layers/CodexTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/CodexTextGeneration.test.ts
@@ -1,29 +1,30 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path, Result } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { createModelSelection } from "@t3tools/shared/model";
 import { expect } from "vitest";
 
-import { ServerConfig } from "../../config.ts";
-import { CodexTextGenerationLive } from "./CodexTextGeneration.ts";
-import { TextGenerationError } from "@t3tools/contracts";
-import { TextGeneration } from "../Services/TextGeneration.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-
-const DEFAULT_TEST_MODEL_SELECTION = {
-  provider: "codex" as const,
-  model: "gpt-5.4-mini",
-};
-
-const CodexTextGenerationTestLayer = CodexTextGenerationLive.pipe(
-  Layer.provideMerge(ServerSettingsService.layerTest()),
-  Layer.provideMerge(
-    ServerConfig.layerTest(process.cwd(), {
-      prefix: "t3code-codex-text-generation-test-",
-    }),
-  ),
-  Layer.provideMerge(NodeServices.layer),
+import { CodexSettings, ProviderInstanceId, TextGenerationError } from "@t3tools/contracts";
+
+import { ServerConfig } from "../config.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
+import { makeCodexTextGeneration } from "./CodexTextGeneration.ts";
+const decodeCodexSettings = Schema.decodeSync(CodexSettings);
+
+const DEFAULT_TEST_MODEL_SELECTION = createModelSelection(
+  ProviderInstanceId.make("codex"),
+  "gpt-5.4-mini",
 );
 
+const CodexTextGenerationTestLayer = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3code-codex-text-generation-test-",
+}).pipe(Layer.provideMerge(NodeServices.layer));
+
 function makeFakeCodexBinary(
   dir: string,
   input: {
@@ -118,6 +119,7 @@ function makeFakeCodexBinary(
           : []),
         ...(input.stdinMustContain !== undefined
           ? [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               `if ! printf "%s" "$stdin_content" | grep -F -- ${JSON.stringify(input.stdinMustContain)} >/dev/null; then`,
               '  printf "%s\\n" "stdin missing expected content" >&2',
               `  exit 3`,
@@ -126,6 +128,7 @@ function makeFakeCodexBinary(
           : []),
         ...(input.stdinMustNotContain !== undefined
           ? [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
               `if printf "%s" "$stdin_content" | grep -F -- ${JSON.stringify(input.stdinMustNotContain)} >/dev/null; then`,
               '  printf "%s\\n" "stdin contained forbidden content" >&2',
               `  exit 4`,
@@ -133,7 +136,10 @@ function makeFakeCodexBinary(
             ]
           : []),
         ...(input.stderr !== undefined
-          ? [`printf "%s\\n" ${JSON.stringify(input.stderr)} >&2`]
+          ? [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
+              `printf "%s\\n" ${JSON.stringify(input.stderr)} >&2`,
+            ]
           : []),
         'if [ -n "$output_path" ]; then',
         "  cat > \"$output_path\" <<'__T3CODE_FAKE_CODEX_OUTPUT__'",
@@ -161,39 +167,19 @@ function withFakeCodexEnv<A, E, R>(
     stdinMustContain?: string;
     stdinMustNotContain?: string;
   },
-  effect: Effect.Effect<A, E, R>,
+  effectFn: (textGeneration: TextGenerationShape) => Effect.Effect<A, E, R>,
 ) {
-  return Effect.acquireUseRelease(
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-codex-text-" });
-      const codexPath = yield* makeFakeCodexBinary(tempDir, input);
-      const serverSettings = yield* ServerSettingsService;
-      const previousSettings = yield* serverSettings.getSettings;
-      yield* serverSettings.updateSettings({
-        providers: {
-          codex: {
-            binaryPath: codexPath,
-          },
-        },
-      });
-      return { serverSettings, previousBinaryPath: previousSettings.providers.codex.binaryPath };
-    }),
-    () => effect,
-    ({ serverSettings, previousBinaryPath }) =>
-      serverSettings
-        .updateSettings({
-          providers: {
-            codex: {
-              binaryPath: previousBinaryPath,
-            },
-          },
-        })
-        .pipe(Effect.asVoid),
-  );
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-codex-text-" });
+    const codexPath = yield* makeFakeCodexBinary(tempDir, input);
+    const config = decodeCodexSettings({ binaryPath: codexPath });
+    const textGeneration = yield* makeCodexTextGeneration(config);
+    return yield* effectFn(textGeneration);
+  }).pipe(Effect.scoped);
 }
 
-it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
+it.layer(CodexTextGenerationTestLayer)("CodexTextGeneration", (it) => {
   it.effect("generates and sanitizes commit messages without branch by default", () =>
     withFakeCodexEnv(
       {
@@ -204,22 +190,21 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         }),
         stdinMustNotContain: "branch must be a short semantic git branch fragment",
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateCommitMessage({
-          cwd: process.cwd(),
-          branch: "feature/codex-effect",
-          stagedSummary: "M README.md",
-          stagedPatch: "diff --git a/README.md b/README.md",
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/codex-effect",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.subject.length).toBeLessThanOrEqual(72);
-        expect(generated.subject.endsWith(".")).toBe(false);
-        expect(generated.body).toBe("- added migration\n- updated tests");
-        expect(generated.branch).toBeUndefined();
-      }),
+          expect(generated.subject.length).toBeLessThanOrEqual(72);
+          expect(generated.subject.endsWith(".")).toBe(false);
+          expect(generated.body).toBe("- added migration\n- updated tests");
+          expect(generated.branch).toBeUndefined();
+        }),
     ),
   );
 
@@ -236,24 +221,17 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
           requireReasoningEffort: "xhigh",
           stdinMustNotContain: "branch must be a short semantic git branch fragment",
         },
-        Effect.gen(function* () {
-          const textGeneration = yield* TextGeneration;
-
-          yield* textGeneration.generateCommitMessage({
+        (textGeneration) =>
+          textGeneration.generateCommitMessage({
             cwd: process.cwd(),
             branch: "feature/codex-effect",
             stagedSummary: "M README.md",
             stagedPatch: "diff --git a/README.md b/README.md",
-            modelSelection: {
-              provider: "codex",
-              model: "gpt-5.4",
-              options: {
-                reasoningEffort: "xhigh",
-                fastMode: true,
-              },
-            },
-          });
-        }),
+            modelSelection: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+              { id: "reasoningEffort", value: "xhigh" },
+              { id: "fastMode", value: true },
+            ]),
+          }),
       ),
   );
 
@@ -266,17 +244,14 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         }),
         requireReasoningEffort: "low",
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        yield* textGeneration.generateCommitMessage({
+      (textGeneration) =>
+        textGeneration.generateCommitMessage({
           cwd: process.cwd(),
           branch: "feature/codex-effect",
           stagedSummary: "M README.md",
           stagedPatch: "diff --git a/README.md b/README.md",
           modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
-      }),
+        }),
     ),
   );
 
@@ -290,21 +265,20 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         }),
         stdinMustContain: "branch must be a short semantic git branch fragment",
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateCommitMessage({
-          cwd: process.cwd(),
-          branch: "feature/codex-effect",
-          stagedSummary: "M README.md",
-          stagedPatch: "diff --git a/README.md b/README.md",
-          includeBranch: true,
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/codex-effect",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            includeBranch: true,
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.subject).toBe("Add important change");
-        expect(generated.branch).toBe("feature/fix/important-system-change");
-      }),
+          expect(generated.subject).toBe("Add important change");
+          expect(generated.branch).toBe("feature/fix/important-system-change");
+        }),
     ),
   );
 
@@ -316,23 +290,22 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
           body: "\n## Summary\n- improve flow\n\n## Testing\n- bun test\n\n",
         }),
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generatePrContent({
-          cwd: process.cwd(),
-          baseBranch: "main",
-          headBranch: "feature/codex-effect",
-          commitSummary: "feat: improve orchestration flow",
-          diffSummary: "2 files changed",
-          diffPatch: "diff --git a/a.ts b/a.ts",
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generatePrContent({
+            cwd: process.cwd(),
+            baseBranch: "main",
+            headBranch: "feature/codex-effect",
+            commitSummary: "feat: improve orchestration flow",
+            diffSummary: "2 files changed",
+            diffPatch: "diff --git a/a.ts b/a.ts",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.title).toBe("Improve orchestration flow");
-        expect(generated.body.startsWith("## Summary")).toBe(true);
-        expect(generated.body.endsWith("\n\n")).toBe(false);
-      }),
+          expect(generated.title).toBe("Improve orchestration flow");
+          expect(generated.body.startsWith("## Summary")).toBe(true);
+          expect(generated.body.endsWith("\n\n")).toBe(false);
+        }),
     ),
   );
 
@@ -344,17 +317,16 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         }),
         stdinMustNotContain: "Image attachments supplied to the model",
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateBranchName({
-          cwd: process.cwd(),
-          message: "Please update session handling.",
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateBranchName({
+            cwd: process.cwd(),
+            message: "Please update session handling.",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.branch).toBe("feat/session");
-      }),
+          expect(generated.branch).toBe("feat/session");
+        }),
     ),
   );
 
@@ -366,17 +338,16 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
             '  "Investigate websocket reconnect regressions after worktree restore"  \nignored line',
         }),
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateThreadTitle({
-          cwd: process.cwd(),
-          message: "Please investigate websocket reconnect regressions after a worktree restore.",
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateThreadTitle({
+            cwd: process.cwd(),
+            message: "Please investigate websocket reconnect regressions after a worktree restore.",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.title).toBe("Investigate websocket reconnect regressions aft...");
-      }),
+          expect(generated.title).toBe("Investigate websocket reconnect regressions aft...");
+        }),
     ),
   );
 
@@ -387,17 +358,16 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
           title: '  """   """  ',
         }),
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateThreadTitle({
-          cwd: process.cwd(),
-          message: "Name this thread.",
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateThreadTitle({
+            cwd: process.cwd(),
+            message: "Name this thread.",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.title).toBe("New thread");
-      }),
+          expect(generated.title).toBe("New thread");
+        }),
     ),
   );
 
@@ -408,17 +378,16 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
           title: `  "' hello world '"  `,
         }),
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateThreadTitle({
-          cwd: process.cwd(),
-          message: "Name this thread.",
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateThreadTitle({
+            cwd: process.cwd(),
+            message: "Name this thread.",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.title).toBe("hello world");
-      }),
+          expect(generated.title).toBe("hello world");
+        }),
     ),
   );
 
@@ -430,17 +399,16 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         }),
         stdinMustNotContain: "Attachment metadata:",
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateBranchName({
-          cwd: process.cwd(),
-          message: "Fix timeout behavior.",
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-        });
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateBranchName({
+            cwd: process.cwd(),
+            message: "Fix timeout behavior.",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
 
-        expect(generated.branch).toBe("fix/session-timeout");
-      }),
+          expect(generated.branch).toBe("fix/session-timeout");
+        }),
     ),
   );
 
@@ -453,56 +421,17 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         requireImage: true,
         stdinMustContain: "Attachment metadata:",
       },
-      Effect.gen(function* () {
-        const fs = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const { attachmentsDir } = yield* ServerConfig;
-        const attachmentId = `thread-branch-image-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-        const attachmentPath = path.join(attachmentsDir, `${attachmentId}.png`);
-        yield* fs.makeDirectory(attachmentsDir, { recursive: true });
-        yield* fs.writeFile(attachmentPath, Buffer.from("hello"));
-
-        const textGeneration = yield* TextGeneration;
-        const generated = yield* textGeneration.generateBranchName({
-          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-          cwd: process.cwd(),
-          message: "Fix layout bug from screenshot.",
-          attachments: [
-            {
-              type: "image",
-              id: attachmentId,
-              name: "bug.png",
-              mimeType: "image/png",
-              sizeBytes: 5,
-            },
-          ],
-        });
-
-        expect(generated.branch).toBe("fix/ui-regression");
-      }),
-    ),
-  );
-
-  it.effect("resolves persisted attachment ids to files for codex image inputs", () =>
-    withFakeCodexEnv(
-      {
-        output: JSON.stringify({
-          branch: "fix/ui-regression",
-        }),
-        requireImage: true,
-      },
-      Effect.gen(function* () {
-        const fs = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const { attachmentsDir } = yield* ServerConfig;
-        const attachmentId = `thread-1-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-        const imagePath = path.join(attachmentsDir, `${attachmentId}.png`);
-        yield* fs.makeDirectory(attachmentsDir, { recursive: true });
-        yield* fs.writeFile(imagePath, Buffer.from("hello"));
-
-        const textGeneration = yield* TextGeneration;
-        const generated = yield* textGeneration
-          .generateBranchName({
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const fs = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const { attachmentsDir } = yield* ServerConfig;
+          const attachmentId = "thread-branch-image-attachment";
+          const attachmentPath = path.join(attachmentsDir, `${attachmentId}.png`);
+          yield* fs.makeDirectory(attachmentsDir, { recursive: true });
+          yield* fs.writeFile(attachmentPath, Buffer.from("hello"));
+
+          const generated = yield* textGeneration.generateBranchName({
             modelSelection: DEFAULT_TEST_MODEL_SELECTION,
             cwd: process.cwd(),
             message: "Fix layout bug from screenshot.",
@@ -515,24 +444,14 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
                 sizeBytes: 5,
               },
             ],
-          })
-          .pipe(
-            Effect.tap(() =>
-              fs.stat(imagePath).pipe(
-                Effect.map((fileInfo) => {
-                  expect(fileInfo.type).toBe("File");
-                }),
-              ),
-            ),
-            Effect.ensuring(fs.remove(imagePath).pipe(Effect.catch(() => Effect.void))),
-          );
+          });
 
-        expect(generated.branch).toBe("fix/ui-regression");
-      }),
+          expect(generated.branch).toBe("fix/ui-regression");
+        }),
     ),
   );
 
-  it.effect("ignores missing attachment ids for codex image inputs", () =>
+  it.effect("resolves persisted attachment ids to files for codex image inputs", () =>
     withFakeCodexEnv(
       {
         output: JSON.stringify({
@@ -540,67 +459,115 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         }),
         requireImage: true,
       },
-      Effect.gen(function* () {
-        const fs = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const { attachmentsDir } = yield* ServerConfig;
-        const missingAttachmentId = `thread-missing-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-        const missingPath = path.join(attachmentsDir, `${missingAttachmentId}.png`);
-        yield* fs.remove(missingPath).pipe(Effect.catch(() => Effect.void));
-
-        const textGeneration = yield* TextGeneration;
-        const result = yield* textGeneration
-          .generateBranchName({
-            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-            cwd: process.cwd(),
-            message: "Fix layout bug from screenshot.",
-            attachments: [
-              {
-                type: "image",
-                id: missingAttachmentId,
-                name: "outside.png",
-                mimeType: "image/png",
-                sizeBytes: 5,
-              },
-            ],
-          })
-          .pipe(Effect.result);
-
-        expect(Result.isFailure(result)).toBe(true);
-        if (Result.isFailure(result)) {
-          expect(result.failure).toBeInstanceOf(TextGenerationError);
-          expect(result.failure.message).toContain("missing --image input");
-        }
-      }),
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const fs = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const { attachmentsDir } = yield* ServerConfig;
+          const attachmentId = "thread-1-attachment";
+          const imagePath = path.join(attachmentsDir, `${attachmentId}.png`);
+          yield* fs.makeDirectory(attachmentsDir, { recursive: true });
+          yield* fs.writeFile(imagePath, Buffer.from("hello"));
+
+          const generated = yield* textGeneration
+            .generateBranchName({
+              modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+              cwd: process.cwd(),
+              message: "Fix layout bug from screenshot.",
+              attachments: [
+                {
+                  type: "image",
+                  id: attachmentId,
+                  name: "bug.png",
+                  mimeType: "image/png",
+                  sizeBytes: 5,
+                },
+              ],
+            })
+            .pipe(
+              Effect.tap(() =>
+                fs.stat(imagePath).pipe(
+                  Effect.map((fileInfo) => {
+                    expect(fileInfo.type).toBe("File");
+                  }),
+                ),
+              ),
+              Effect.ensuring(fs.remove(imagePath).pipe(Effect.catch(() => Effect.void))),
+            );
+
+          expect(generated.branch).toBe("fix/ui-regression");
+        }),
     ),
   );
 
-  it.effect(
-    "fails with typed TextGenerationError when codex returns wrong branch payload shape",
-    () =>
-      withFakeCodexEnv(
-        {
-          output: JSON.stringify({
-            title: "This is not a branch payload",
-          }),
-        },
+  it.effect("ignores missing attachment ids for codex image inputs", () =>
+    withFakeCodexEnv(
+      {
+        output: JSON.stringify({
+          branch: "fix/ui-regression",
+        }),
+        requireImage: true,
+      },
+      (textGeneration) =>
         Effect.gen(function* () {
-          const textGeneration = yield* TextGeneration;
+          const fs = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const { attachmentsDir } = yield* ServerConfig;
+          const missingAttachmentId = "thread-missing-attachment";
+          const missingPath = path.join(attachmentsDir, `${missingAttachmentId}.png`);
+          yield* fs.remove(missingPath).pipe(Effect.catch(() => Effect.void));
 
           const result = yield* textGeneration
             .generateBranchName({
-              cwd: process.cwd(),
-              message: "Fix websocket reconnect flake",
               modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+              cwd: process.cwd(),
+              message: "Fix layout bug from screenshot.",
+              attachments: [
+                {
+                  type: "image",
+                  id: missingAttachmentId,
+                  name: "outside.png",
+                  mimeType: "image/png",
+                  sizeBytes: 5,
+                },
+              ],
             })
             .pipe(Effect.result);
 
           expect(Result.isFailure(result)).toBe(true);
           if (Result.isFailure(result)) {
             expect(result.failure).toBeInstanceOf(TextGenerationError);
-            expect(result.failure.message).toContain("Codex returned invalid structured output");
+            expect(result.failure.message).toContain("missing --image input");
           }
         }),
+    ),
+  );
+
+  it.effect(
+    "fails with typed TextGenerationError when codex returns wrong branch payload shape",
+    () =>
+      withFakeCodexEnv(
+        {
+          output: JSON.stringify({
+            title: "This is not a branch payload",
+          }),
+        },
+        (textGeneration) =>
+          Effect.gen(function* () {
+            const result = yield* textGeneration
+              .generateBranchName({
+                cwd: process.cwd(),
+                message: "Fix websocket reconnect flake",
+                modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+              })
+              .pipe(Effect.result);
+
+            expect(Result.isFailure(result)).toBe(true);
+            if (Result.isFailure(result)) {
+              expect(result.failure).toBeInstanceOf(TextGenerationError);
+              expect(result.failure.message).toContain("Codex returned invalid structured output");
+            }
+          }),
       ),
   );
 
@@ -611,27 +578,26 @@ it.layer(CodexTextGenerationTestLayer)("CodexTextGenerationLive", (it) => {
         exitCode: 1,
         stderr: "codex execution failed",
       },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const result = yield* textGeneration
+            .generateCommitMessage({
+              cwd: process.cwd(),
+              branch: "feature/codex-error",
+              stagedSummary: "M README.md",
+              stagedPatch: "diff --git a/README.md b/README.md",
+              modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+            })
+            .pipe(Effect.result);
 
-        const result = yield* textGeneration
-          .generateCommitMessage({
-            cwd: process.cwd(),
-            branch: "feature/codex-error",
-            stagedSummary: "M README.md",
-            stagedPatch: "diff --git a/README.md b/README.md",
-            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
-          })
-          .pipe(Effect.result);
-
-        expect(Result.isFailure(result)).toBe(true);
-        if (Result.isFailure(result)) {
-          expect(result.failure).toBeInstanceOf(TextGenerationError);
-          expect(result.failure.message).toContain(
-            "Codex CLI command failed: codex execution failed",
-          );
-        }
-      }),
+          expect(Result.isFailure(result)).toBe(true);
+          if (Result.isFailure(result)) {
+            expect(result.failure).toBeInstanceOf(TextGenerationError);
+            expect(result.failure.message).toContain(
+              "Codex CLI command failed: codex execution failed",
+            );
+          }
+        }),
     ),
   );
 });
diff --git a/apps/server/src/git/Layers/CodexTextGeneration.ts b/apps/server/src/textGeneration/CodexTextGeneration.ts
similarity index 76%
rename from apps/server/src/git/Layers/CodexTextGeneration.ts
rename to apps/server/src/textGeneration/CodexTextGeneration.ts
index 52ddf554532..3d1637a7fc0 100644
--- a/apps/server/src/git/Layers/CodexTextGeneration.ts
+++ b/apps/server/src/textGeneration/CodexTextGeneration.ts
@@ -1,45 +1,58 @@
-import { randomUUID } from "node:crypto";
-
-import { Effect, FileSystem, Layer, Option, Path, Schema, Scope, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Random from "effect/Random";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
-import { CodexModelSelection } from "@t3tools/contracts";
+import { type CodexSettings, type ModelSelection } from "@t3tools/contracts";
 import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
 
-import { resolveAttachmentPath } from "../../attachmentStore.ts";
-import { ServerConfig } from "../../config.ts";
+import { resolveAttachmentPath } from "../attachmentStore.ts";
+import { ServerConfig } from "../config.ts";
+import { expandHomePath } from "../pathExpansion.ts";
 import { TextGenerationError } from "@t3tools/contracts";
 import {
   type BranchNameGenerationInput,
   type ThreadTitleGenerationResult,
   type TextGenerationShape,
-  TextGeneration,
-} from "../Services/TextGeneration.ts";
+} from "./TextGeneration.ts";
 import {
   buildBranchNamePrompt,
   buildCommitMessagePrompt,
   buildPrContentPrompt,
   buildThreadTitlePrompt,
-} from "../Prompts.ts";
+} from "./TextGenerationPrompts.ts";
 import {
   normalizeCliError,
   sanitizeCommitSubject,
   sanitizePrTitle,
   sanitizeThreadTitle,
   toJsonSchemaObject,
-} from "../Utils.ts";
-import { getCodexModelCapabilities } from "../../provider/Layers/CodexProvider.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { normalizeCodexModelOptionsWithCapabilities } from "@t3tools/shared/model";
+} from "./TextGenerationUtils.ts";
+import {
+  getModelSelectionBooleanOptionValue,
+  getModelSelectionStringOptionValue,
+} from "@t3tools/shared/model";
 
 const CODEX_GIT_TEXT_GENERATION_REASONING_EFFORT = "low";
 const CODEX_TIMEOUT_MS = 180_000;
-const makeCodexTextGeneration = Effect.gen(function* () {
+const encodeJsonString = Schema.encodeEffect(Schema.UnknownFromJsonString);
+/**
+ * Build a Codex text-generation closure bound to a specific `CodexSettings`
+ * payload. See `makeCodexAdapter` for the overall per-instance rationale.
+ */
+export const makeCodexTextGeneration = Effect.fn("makeCodexTextGeneration")(function* (
+  codexConfig: CodexSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const serverConfig = yield* Effect.service(ServerConfig);
-  const serverSettingsService = yield* Effect.service(ServerSettingsService);
 
   type MaterializedImageAttachments = {
     readonly imagePaths: ReadonlyArray<string>;
@@ -65,26 +78,47 @@ const makeCodexTextGeneration = Effect.gen(function* () {
     prefix: string,
     content: string,
   ): Effect.Effect<string, TextGenerationError, Scope.Scope> => {
-    return fileSystem
-      .makeTempFileScoped({
-        prefix: `t3code-${prefix}-${process.pid}-${randomUUID()}.tmp`,
-      })
-      .pipe(
-        Effect.tap((filePath) => fileSystem.writeFileString(filePath, content)),
-        Effect.mapError(
-          (cause) =>
-            new TextGenerationError({
-              operation,
-              detail: `Failed to write temp file`,
-              cause,
-            }),
-        ),
-      );
+    return Effect.gen(function* () {
+      const tempFileId = yield* Random.nextUUIDv4;
+      return yield* fileSystem
+        .makeTempFileScoped({
+          prefix: `t3code-${prefix}-${process.pid}-${tempFileId}.tmp`,
+        })
+        .pipe(Effect.tap((filePath) => fileSystem.writeFileString(filePath, content)));
+    }).pipe(
+      Effect.mapError(
+        (cause) =>
+          new TextGenerationError({
+            operation,
+            detail: `Failed to write temp file`,
+            cause,
+          }),
+      ),
+    );
   };
 
   const safeUnlink = (filePath: string): Effect.Effect<void, never> =>
     fileSystem.remove(filePath).pipe(Effect.catch(() => Effect.void));
 
+  const encodeJsonForOperation = (
+    operation:
+      | "generateCommitMessage"
+      | "generatePrContent"
+      | "generateBranchName"
+      | "generateThreadTitle",
+    value: unknown,
+  ): Effect.Effect<string, TextGenerationError> =>
+    encodeJsonString(value).pipe(
+      Effect.mapError(
+        (cause) =>
+          new TextGenerationError({
+            operation,
+            detail: "Failed to encode structured output schema.",
+            cause,
+          }),
+      ),
+    );
+
   const materializeImageAttachments = Effect.fn("materializeImageAttachments")(function* (
     _operation:
       | "generateCommitMessage"
@@ -140,39 +174,34 @@ const makeCodexTextGeneration = Effect.gen(function* () {
     outputSchemaJson: S;
     imagePaths?: ReadonlyArray<string>;
     cleanupPaths?: ReadonlyArray<string>;
-    modelSelection: CodexModelSelection;
+    modelSelection: ModelSelection;
   }): Effect.fn.Return<S["Type"], TextGenerationError, S["DecodingServices"]> {
-    const schemaPath = yield* writeTempFile(
+    const schemaJson = yield* encodeJsonForOperation(
       operation,
-      "codex-schema",
-      JSON.stringify(toJsonSchemaObject(outputSchemaJson)),
+      toJsonSchemaObject(outputSchemaJson),
     );
+    const schemaPath = yield* writeTempFile(operation, "codex-schema", schemaJson);
     const outputPath = yield* writeTempFile(operation, "codex-output", "");
 
-    const codexSettings = yield* Effect.map(
-      serverSettingsService.getSettings,
-      (settings) => settings.providers.codex,
-    ).pipe(Effect.catch(() => Effect.undefined));
-
     const runCodexCommand = Effect.fn("runCodexJson.runCodexCommand")(function* () {
-      const normalizedOptions = normalizeCodexModelOptionsWithCapabilities(
-        getCodexModelCapabilities(modelSelection.model),
-        modelSelection.options,
-      );
       const reasoningEffort =
-        modelSelection.options?.reasoningEffort ?? CODEX_GIT_TEXT_GENERATION_REASONING_EFFORT;
+        getModelSelectionStringOptionValue(modelSelection, "reasoningEffort") ??
+        CODEX_GIT_TEXT_GENERATION_REASONING_EFFORT;
       const command = ChildProcess.make(
-        codexSettings?.binaryPath || "codex",
+        codexConfig.binaryPath || "codex",
         [
           "exec",
           "--ephemeral",
+          "--skip-git-repo-check",
           "-s",
           "read-only",
           "--model",
           modelSelection.model,
           "--config",
           `model_reasoning_effort="${reasoningEffort}"`,
-          ...(normalizedOptions?.fastMode ? ["--config", `service_tier="fast"`] : []),
+          ...(getModelSelectionBooleanOptionValue(modelSelection, "fastMode") === true
+            ? ["--config", `service_tier="fast"`]
+            : []),
           "--output-schema",
           schemaPath,
           "--output-last-message",
@@ -182,8 +211,8 @@ const makeCodexTextGeneration = Effect.gen(function* () {
         ],
         {
           env: {
-            ...process.env,
-            ...(codexSettings?.homePath ? { CODEX_HOME: codexSettings.homePath } : {}),
+            ...environment,
+            ...(codexConfig.homePath ? { CODEX_HOME: expandHomePath(codexConfig.homePath) } : {}),
           },
           cwd,
           shell: process.platform === "win32",
@@ -250,6 +279,8 @@ const makeCodexTextGeneration = Effect.gen(function* () {
         ),
       );
 
+      const decodeOutput = Schema.decodeEffect(Schema.fromJsonString(outputSchemaJson));
+
       return yield* fileSystem.readFileString(outputPath).pipe(
         Effect.mapError(
           (cause) =>
@@ -259,7 +290,7 @@ const makeCodexTextGeneration = Effect.gen(function* () {
               cause,
             }),
         ),
-        Effect.flatMap(Schema.decodeEffect(Schema.fromJsonString(outputSchemaJson))),
+        Effect.flatMap(decodeOutput),
         Effect.catchTag("SchemaError", (cause) =>
           Effect.fail(
             new TextGenerationError({
@@ -283,13 +314,6 @@ const makeCodexTextGeneration = Effect.gen(function* () {
       includeBranch: input.includeBranch === true,
     });
 
-    if (input.modelSelection.provider !== "codex") {
-      return yield* new TextGenerationError({
-        operation: "generateCommitMessage",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCodexJson({
       operation: "generateCommitMessage",
       cwd: input.cwd,
@@ -318,13 +342,6 @@ const makeCodexTextGeneration = Effect.gen(function* () {
       diffPatch: input.diffPatch,
     });
 
-    if (input.modelSelection.provider !== "codex") {
-      return yield* new TextGenerationError({
-        operation: "generatePrContent",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCodexJson({
       operation: "generatePrContent",
       cwd: input.cwd,
@@ -351,13 +368,6 @@ const makeCodexTextGeneration = Effect.gen(function* () {
       attachments: input.attachments,
     });
 
-    if (input.modelSelection.provider !== "codex") {
-      return yield* new TextGenerationError({
-        operation: "generateBranchName",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCodexJson({
       operation: "generateBranchName",
       cwd: input.cwd,
@@ -384,13 +394,6 @@ const makeCodexTextGeneration = Effect.gen(function* () {
       attachments: input.attachments,
     });
 
-    if (input.modelSelection.provider !== "codex") {
-      return yield* new TextGenerationError({
-        operation: "generateThreadTitle",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCodexJson({
       operation: "generateThreadTitle",
       cwd: input.cwd,
@@ -412,5 +415,3 @@ const makeCodexTextGeneration = Effect.gen(function* () {
     generateThreadTitle,
   } satisfies TextGenerationShape;
 });
-
-export const CodexTextGenerationLive = Layer.effect(TextGeneration, makeCodexTextGeneration);
diff --git a/apps/server/src/textGeneration/CursorTextGeneration.test.ts b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
new file mode 100644
index 00000000000..c784530cd9b
--- /dev/null
+++ b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
@@ -0,0 +1,272 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as path from "node:path";
+import * as os from "node:os";
+import { fileURLToPath } from "node:url";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { createModelSelection } from "@t3tools/shared/model";
+import { expect } from "vitest";
+
+import { CursorSettings, ProviderInstanceId } from "@t3tools/contracts";
+
+import { ServerConfig } from "../config.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
+import { makeCursorTextGeneration } from "./CursorTextGeneration.ts";
+const decodeCursorSettings = Schema.decodeSync(CursorSettings);
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const mockAgentPath = path.join(__dirname, "../../scripts/acp-mock-agent.ts");
+
+function shellSingleQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+const CursorTextGenerationTestLayer = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3code-cursor-text-generation-test-",
+}).pipe(Layer.provideMerge(NodeServices.layer));
+
+function makeAcpAgentWrapper(dir: string, env: Record<string, string>): string {
+  const binDir = path.join(dir, "bin");
+  const agentPath = path.join(binDir, "agent");
+  mkdirSync(binDir, { recursive: true });
+  writeFileSync(
+    agentPath,
+    [
+      "#!/bin/sh",
+      ...Object.entries(env).map(([key, value]) => `export ${key}=${shellSingleQuote(value)}`),
+      'if [ "$1" != "acp" ]; then',
+      '  printf "%s\\n" "unexpected args: $*" >&2',
+      "  exit 11",
+      "fi",
+      `exec bun ${JSON.stringify(mockAgentPath)}`,
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  chmodSync(agentPath, 0o755);
+  return agentPath;
+}
+
+function withFakeAcpAgent<A, E, R>(
+  env: Record<string, string>,
+  effectFn: (textGeneration: TextGenerationShape) => Effect.Effect<A, E, R>,
+) {
+  return Effect.gen(function* () {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "t3code-cursor-text-acp-"));
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        rmSync(tempDir, { recursive: true, force: true });
+      }),
+    );
+    const agentPath = makeAcpAgentWrapper(tempDir, env);
+    const config = decodeCursorSettings({ binaryPath: agentPath });
+    const textGeneration = yield* makeCursorTextGeneration(config);
+    return yield* effectFn(textGeneration);
+  }).pipe(Effect.scoped);
+}
+
+function waitForFileContent(path: string): Effect.Effect<string> {
+  return Effect.gen(function* () {
+    const deadline = (yield* Clock.currentTimeMillis) + 5_000;
+    for (;;) {
+      const result = yield* Effect.exit(Effect.sync(() => readFileSync(path, "utf8")));
+      if (Exit.isSuccess(result)) {
+        return result.value;
+      }
+      {
+        if ((yield* Clock.currentTimeMillis) >= deadline) {
+          return yield* Effect.die(result.cause);
+        }
+      }
+      yield* Effect.sleep(25);
+    }
+  });
+}
+
+it.layer(CursorTextGenerationTestLayer)("CursorTextGeneration", (it) => {
+  it.effect("uses ACP model config options instead of raw CLI model ids", () => {
+    const requestLogDir = mkdtempSync(path.join(os.tmpdir(), "t3code-cursor-text-log-"));
+    const requestLogPath = path.join(requestLogDir, "requests.ndjson");
+
+    return withFakeAcpAgent(
+      {
+        T3_ACP_REQUEST_LOG_PATH: requestLogPath,
+        T3_ACP_PROMPT_RESPONSE_TEXT: JSON.stringify({
+          subject: "Add generated commit message",
+          body: "- verify cursor acp model config path",
+        }),
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/cursor-text-generation",
+            stagedSummary: "M apps/server/src/textGeneration/CursorTextGeneration.ts",
+            stagedPatch:
+              "diff --git a/apps/server/src/textGeneration/CursorTextGeneration.ts b/apps/server/src/textGeneration/CursorTextGeneration.ts",
+            modelSelection: {
+              ...createModelSelection(ProviderInstanceId.make("cursor"), "gpt-5.4", [
+                { id: "reasoning", value: "xhigh" },
+                { id: "fastMode", value: true },
+                { id: "contextWindow", value: "1m" },
+              ]),
+            },
+          });
+
+          expect(generated.subject).toBe("Add generated commit message");
+          expect(generated.body).toBe("- verify cursor acp model config path");
+
+          const requests = readFileSync(requestLogPath, "utf8")
+            .trim()
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map(
+              (line) => JSON.parse(line) as { method?: string; params?: Record<string, unknown> },
+            );
+
+          expect(
+            requests.find((request) => request.method === "initialize")?.params?.clientCapabilities,
+          ).toMatchObject({
+            _meta: {
+              parameterizedModelPicker: true,
+            },
+          });
+          expect(
+            requests.some(
+              (request) =>
+                request.method === "session/set_config_option" &&
+                request.params?.configId === "model" &&
+                request.params?.value === "gpt-5.4",
+            ),
+          ).toBe(true);
+          expect(
+            requests.some(
+              (request) =>
+                request.method === "session/set_config_option" &&
+                request.params?.configId === "reasoning" &&
+                request.params?.value === "extra-high",
+            ),
+          ).toBe(true);
+          expect(
+            requests.some(
+              (request) =>
+                request.method === "session/set_config_option" &&
+                request.params?.configId === "context" &&
+                request.params?.value === "1m",
+            ),
+          ).toBe(true);
+          expect(
+            requests.some(
+              (request) =>
+                request.method === "session/set_config_option" &&
+                request.params?.configId === "fast" &&
+                request.params?.value === "true",
+            ),
+          ).toBe(true);
+          expect(
+            requests.find((request) => request.method === "session/prompt")?.params?.prompt,
+          ).toEqual(
+            expect.arrayContaining([
+              expect.objectContaining({
+                type: "text",
+                text: expect.stringContaining("Staged patch:"),
+              }),
+            ]),
+          );
+
+          rmSync(requestLogDir, { recursive: true, force: true });
+        }),
+    );
+  });
+
+  it.effect("accepts json objects with extra assistant text around them", () =>
+    withFakeAcpAgent(
+      {
+        T3_ACP_PROMPT_RESPONSE_TEXT:
+          'Sure, here is the JSON:\n```json\n{\n  "subject": "Update README dummy comment with attribution and date",\n  "body": ""\n}\n```\nDone.',
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/cursor-noisy-json",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            modelSelection: {
+              instanceId: ProviderInstanceId.make("cursor"),
+              model: "composer-2",
+            },
+          });
+
+          expect(generated.subject).toBe("Update README dummy comment with attribution and date");
+          expect(generated.body).toBe("");
+        }),
+    ),
+  );
+
+  it.effect("generates thread titles through Cursor ACP text generation", () =>
+    withFakeAcpAgent(
+      {
+        T3_ACP_PROMPT_RESPONSE_TEXT: JSON.stringify({
+          title: '"Trim reconnect spinner status after resume."',
+        }),
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateThreadTitle({
+            cwd: process.cwd(),
+            message: "Fix the reconnect spinner after a resumed session.",
+            modelSelection: {
+              instanceId: ProviderInstanceId.make("cursor"),
+              model: "composer-2",
+            },
+          });
+
+          expect(generated.title).toBe("Trim reconnect spinner status after resume.");
+        }),
+    ),
+  );
+
+  it.effect("closes the ACP child process after text generation completes", () => {
+    const exitLogDir = mkdtempSync(path.join(os.tmpdir(), "t3code-cursor-text-exit-log-"));
+    const exitLogPath = path.join(exitLogDir, "exit.log");
+
+    return withFakeAcpAgent(
+      {
+        T3_ACP_EXIT_LOG_PATH: exitLogPath,
+        T3_ACP_PROMPT_RESPONSE_TEXT: JSON.stringify({
+          subject: "Close runtime after generation",
+          body: "",
+        }),
+      },
+      (textGeneration) =>
+        Effect.gen(function* () {
+          const generated = yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/cursor-runtime-close",
+            stagedSummary: "M apps/server/src/textGeneration/CursorTextGeneration.ts",
+            stagedPatch:
+              "diff --git a/apps/server/src/textGeneration/CursorTextGeneration.ts b/apps/server/src/textGeneration/CursorTextGeneration.ts",
+            modelSelection: {
+              instanceId: ProviderInstanceId.make("cursor"),
+              model: "composer-2",
+            },
+          });
+
+          expect(generated.subject).toBe("Close runtime after generation");
+
+          const exitLog = yield* waitForFileContent(exitLogPath);
+          expect(exitLog).toContain("exit:0");
+
+          rmSync(exitLogDir, { recursive: true, force: true });
+        }),
+    );
+  });
+});
diff --git a/apps/server/src/textGeneration/CursorTextGeneration.ts b/apps/server/src/textGeneration/CursorTextGeneration.ts
new file mode 100644
index 00000000000..c4ef1af21d1
--- /dev/null
+++ b/apps/server/src/textGeneration/CursorTextGeneration.ts
@@ -0,0 +1,278 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { type CursorSettings, type ModelSelection } from "@t3tools/contracts";
+import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
+import { extractJsonObject } from "@t3tools/shared/schemaJson";
+
+import { TextGenerationError } from "@t3tools/contracts";
+import { type ThreadTitleGenerationResult, type TextGenerationShape } from "./TextGeneration.ts";
+import {
+  buildBranchNamePrompt,
+  buildCommitMessagePrompt,
+  buildPrContentPrompt,
+  buildThreadTitlePrompt,
+} from "./TextGenerationPrompts.ts";
+import {
+  sanitizeCommitSubject,
+  sanitizePrTitle,
+  sanitizeThreadTitle,
+} from "./TextGenerationUtils.ts";
+import {
+  applyCursorAcpModelSelection,
+  makeCursorAcpRuntime,
+} from "../provider/acp/CursorAcpSupport.ts";
+
+const CURSOR_TIMEOUT_MS = 180_000;
+
+function mapCursorAcpError(
+  operation:
+    | "generateCommitMessage"
+    | "generatePrContent"
+    | "generateBranchName"
+    | "generateThreadTitle",
+  detail: string,
+  cause: unknown,
+): TextGenerationError {
+  return new TextGenerationError({
+    operation,
+    detail,
+    ...(cause !== undefined ? { cause } : {}),
+  });
+}
+
+function isTextGenerationError(error: unknown): error is TextGenerationError {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "_tag" in error &&
+    error._tag === "TextGenerationError"
+  );
+}
+
+/**
+ * Build a Cursor text-generation closure bound to a specific `CursorSettings`
+ * payload. See `makeCodexAdapter` for the overall per-instance rationale.
+ */
+export const makeCursorTextGeneration = Effect.fn("makeCursorTextGeneration")(function* (
+  cursorSettings: CursorSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+  const runCursorJson = <S extends Schema.Top>({
+    operation,
+    cwd,
+    prompt,
+    outputSchemaJson,
+    modelSelection,
+  }: {
+    operation:
+      | "generateCommitMessage"
+      | "generatePrContent"
+      | "generateBranchName"
+      | "generateThreadTitle";
+    cwd: string;
+    prompt: string;
+    outputSchemaJson: S;
+    modelSelection: ModelSelection;
+  }): Effect.Effect<S["Type"], TextGenerationError, S["DecodingServices"]> =>
+    Effect.gen(function* () {
+      const outputRef = yield* Ref.make("");
+      const runtime = yield* makeCursorAcpRuntime({
+        cursorSettings,
+        environment,
+        childProcessSpawner: commandSpawner,
+        cwd,
+        clientInfo: { name: "t3-code-git-text", version: "0.0.0" },
+      });
+
+      yield* runtime.handleSessionUpdate((notification) => {
+        const update = notification.update;
+        if (update.sessionUpdate !== "agent_message_chunk") {
+          return Effect.void;
+        }
+        const content = update.content;
+        if (content.type !== "text") {
+          return Effect.void;
+        }
+        return Ref.update(outputRef, (current) => current + content.text);
+      });
+
+      const promptResult = yield* Effect.gen(function* () {
+        yield* runtime.start();
+        yield* Effect.ignore(runtime.setMode("ask"));
+        yield* applyCursorAcpModelSelection({
+          runtime,
+          model: modelSelection.model,
+          selections: modelSelection.options,
+          mapError: ({ cause, configId, step }) =>
+            mapCursorAcpError(
+              operation,
+              step === "set-config-option"
+                ? `Failed to set Cursor ACP config option "${configId}" for text generation.`
+                : "Failed to set Cursor ACP base model for text generation.",
+              cause,
+            ),
+        });
+
+        return yield* runtime.prompt({
+          prompt: [{ type: "text", text: prompt }],
+        });
+      }).pipe(
+        Effect.timeoutOption(CURSOR_TIMEOUT_MS),
+        Effect.flatMap(
+          Option.match({
+            onNone: () =>
+              Effect.fail(
+                new TextGenerationError({
+                  operation,
+                  detail: "Cursor Agent request timed out.",
+                }),
+              ),
+            onSome: (value) => Effect.succeed(value),
+          }),
+        ),
+        Effect.mapError((cause) =>
+          isTextGenerationError(cause)
+            ? cause
+            : mapCursorAcpError(operation, "Cursor ACP request failed.", cause),
+        ),
+      );
+
+      const rawResult = (yield* Ref.get(outputRef)).trim();
+      if (!rawResult) {
+        return yield* new TextGenerationError({
+          operation,
+          detail:
+            promptResult.stopReason === "cancelled"
+              ? "Cursor ACP request was cancelled."
+              : "Cursor Agent returned empty output.",
+        });
+      }
+
+      const decodeOutput = Schema.decodeEffect(Schema.fromJsonString(outputSchemaJson));
+      return yield* decodeOutput(extractJsonObject(rawResult)).pipe(
+        Effect.catchTag("SchemaError", (cause) =>
+          Effect.fail(
+            new TextGenerationError({
+              operation,
+              detail: "Cursor Agent returned invalid structured output.",
+              cause,
+            }),
+          ),
+        ),
+      );
+    }).pipe(
+      Effect.mapError((cause) =>
+        isTextGenerationError(cause)
+          ? cause
+          : mapCursorAcpError(operation, "Cursor ACP text generation failed.", cause),
+      ),
+      Effect.scoped,
+    );
+
+  const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = Effect.fn(
+    "CursorTextGeneration.generateCommitMessage",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildCommitMessagePrompt({
+      branch: input.branch,
+      stagedSummary: input.stagedSummary,
+      stagedPatch: input.stagedPatch,
+      includeBranch: input.includeBranch === true,
+    });
+
+    const generated = yield* runCursorJson({
+      operation: "generateCommitMessage",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+    });
+
+    return {
+      subject: sanitizeCommitSubject(generated.subject),
+      body: generated.body.trim(),
+      ...("branch" in generated && typeof generated.branch === "string"
+        ? { branch: sanitizeFeatureBranchName(generated.branch) }
+        : {}),
+    };
+  });
+
+  const generatePrContent: TextGenerationShape["generatePrContent"] = Effect.fn(
+    "CursorTextGeneration.generatePrContent",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildPrContentPrompt({
+      baseBranch: input.baseBranch,
+      headBranch: input.headBranch,
+      commitSummary: input.commitSummary,
+      diffSummary: input.diffSummary,
+      diffPatch: input.diffPatch,
+    });
+
+    const generated = yield* runCursorJson({
+      operation: "generatePrContent",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+    });
+
+    return {
+      title: sanitizePrTitle(generated.title),
+      body: generated.body.trim(),
+    };
+  });
+
+  const generateBranchName: TextGenerationShape["generateBranchName"] = Effect.fn(
+    "CursorTextGeneration.generateBranchName",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildBranchNamePrompt({
+      message: input.message,
+      attachments: input.attachments,
+    });
+
+    const generated = yield* runCursorJson({
+      operation: "generateBranchName",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+    });
+
+    return {
+      branch: sanitizeBranchFragment(generated.branch),
+    };
+  });
+
+  const generateThreadTitle: TextGenerationShape["generateThreadTitle"] = Effect.fn(
+    "CursorTextGeneration.generateThreadTitle",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildThreadTitlePrompt({
+      message: input.message,
+      attachments: input.attachments,
+    });
+
+    const generated = yield* runCursorJson({
+      operation: "generateThreadTitle",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+    });
+
+    return {
+      title: sanitizeThreadTitle(generated.title),
+    } satisfies ThreadTitleGenerationResult;
+  });
+
+  return {
+    generateCommitMessage,
+    generatePrContent,
+    generateBranchName,
+    generateThreadTitle,
+  } satisfies TextGenerationShape;
+});
diff --git a/apps/server/src/textGeneration/OpenCodeTextGeneration.test.ts b/apps/server/src/textGeneration/OpenCodeTextGeneration.test.ts
new file mode 100644
index 00000000000..8a5deacdb79
--- /dev/null
+++ b/apps/server/src/textGeneration/OpenCodeTextGeneration.test.ts
@@ -0,0 +1,349 @@
+import { OpenCodeSettings, ProviderInstanceId } from "@t3tools/contracts";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as TestClock from "effect/testing/TestClock";
+import * as NetService from "@t3tools/shared/Net";
+import { beforeEach, expect } from "vitest";
+
+import { ServerConfig } from "../config.ts";
+import {
+  OpenCodeRuntime,
+  OpenCodeRuntimeError,
+  type OpenCodeRuntimeShape,
+} from "../provider/opencodeRuntime.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
+import { makeOpenCodeTextGeneration } from "./OpenCodeTextGeneration.ts";
+
+const runtimeMock = {
+  state: {
+    startCalls: [] as string[],
+    promptUrls: [] as string[],
+    authHeaders: [] as Array<string | null>,
+    closeCalls: [] as string[],
+    promptResult: undefined as
+      | { data?: { info?: { error?: unknown }; parts?: Array<{ type: string; text?: string }> } }
+      | undefined,
+  },
+  reset() {
+    this.state.startCalls.length = 0;
+    this.state.promptUrls.length = 0;
+    this.state.authHeaders.length = 0;
+    this.state.closeCalls.length = 0;
+    this.state.promptResult = undefined;
+  },
+};
+
+const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
+  startOpenCodeServerProcess: ({ binaryPath }) =>
+    Effect.gen(function* () {
+      const index = runtimeMock.state.startCalls.length + 1;
+      const url = `http://127.0.0.1:${4_300 + index}`;
+      runtimeMock.state.startCalls.push(binaryPath);
+      // The production runtime binds server lifetime to the caller's scope.
+      // Mirror that here so the closeCalls probe observes scope close.
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          runtimeMock.state.closeCalls.push(url);
+        }),
+      );
+      return {
+        url,
+        exitCode: Effect.never,
+      };
+    }),
+  connectToOpenCodeServer: ({ serverUrl }) =>
+    Effect.succeed({
+      url: serverUrl ?? "http://127.0.0.1:4301",
+      exitCode: null,
+      external: Boolean(serverUrl),
+    }),
+  runOpenCodeCommand: () => Effect.succeed({ stdout: "", stderr: "", code: 0 }),
+  createOpenCodeSdkClient: ({ baseUrl, serverPassword }) =>
+    ({
+      session: {
+        create: async () => ({ data: { id: `${baseUrl}/session` } }),
+        prompt: async () => {
+          runtimeMock.state.promptUrls.push(baseUrl);
+          runtimeMock.state.authHeaders.push(
+            serverPassword ? `Basic ${btoa(`opencode:${serverPassword}`)}` : null,
+          );
+          return (
+            runtimeMock.state.promptResult ?? {
+              data: {
+                parts: [
+                  {
+                    type: "text",
+                    text: JSON.stringify({
+                      subject: "Improve OpenCode reuse",
+                      body: "Reuse one server for the full action.",
+                    }),
+                  },
+                ],
+              },
+            }
+          );
+        },
+      },
+    }) as unknown as ReturnType<OpenCodeRuntimeShape["createOpenCodeSdkClient"]>,
+  loadOpenCodeInventory: () =>
+    Effect.fail(
+      new OpenCodeRuntimeError({
+        operation: "loadOpenCodeInventory",
+        detail: "OpenCodeRuntimeTestDouble.loadOpenCodeInventory not used in this test",
+        cause: null,
+      }),
+    ),
+};
+
+const DEFAULT_TEST_MODEL_SELECTION = {
+  instanceId: ProviderInstanceId.make("opencode"),
+  model: "openai/gpt-5",
+};
+
+const OPENCODE_TEXT_GENERATION_IDLE_TTL_MS = 30_000;
+
+const OpenCodeTextGenerationTestLayer = Layer.succeed(
+  OpenCodeRuntime,
+  OpenCodeRuntimeTestDouble,
+).pipe(
+  Layer.provideMerge(
+    ServerConfig.layerTest(process.cwd(), {
+      prefix: "t3code-opencode-text-generation-test-",
+    }),
+  ),
+  Layer.provideMerge(NetService.layer),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+const OpenCodeTextGenerationExistingServerTestLayer = Layer.succeed(
+  OpenCodeRuntime,
+  OpenCodeRuntimeTestDouble,
+).pipe(
+  Layer.provideMerge(
+    ServerConfig.layerTest(process.cwd(), {
+      prefix: "t3code-opencode-text-generation-existing-server-test-",
+    }),
+  ),
+  Layer.provideMerge(NetService.layer),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+const DEFAULT_OPENCODE_SETTINGS = Schema.decodeSync(OpenCodeSettings)({
+  binaryPath: "fake-opencode",
+});
+const EXISTING_SERVER_OPENCODE_SETTINGS = Schema.decodeSync(OpenCodeSettings)({
+  binaryPath: "fake-opencode",
+  serverUrl: "http://127.0.0.1:9999",
+  serverPassword: "secret-password",
+});
+
+function withOpenCodeTextGeneration<A, E, R>(
+  settings: OpenCodeSettings,
+  effectFn: (textGeneration: TextGenerationShape) => Effect.Effect<A, E, R>,
+) {
+  return Effect.gen(function* () {
+    const textGeneration = yield* makeOpenCodeTextGeneration(settings);
+    return yield* effectFn(textGeneration);
+  }).pipe(Effect.scoped);
+}
+
+beforeEach(() => {
+  runtimeMock.reset();
+});
+
+const advanceIdleClock = Effect.gen(function* () {
+  yield* Effect.yieldNow;
+  yield* TestClock.adjust(Duration.millis(OPENCODE_TEXT_GENERATION_IDLE_TTL_MS + 1));
+  yield* Effect.yieldNow;
+});
+
+it.layer(OpenCodeTextGenerationTestLayer)("OpenCodeTextGeneration", (it) => {
+  it.effect("reuses a warm server across back-to-back requests and closes it after idling", () =>
+    withOpenCodeTextGeneration(DEFAULT_OPENCODE_SETTINGS, (textGeneration) =>
+      Effect.gen(function* () {
+        yield* textGeneration.generateCommitMessage({
+          cwd: process.cwd(),
+          branch: "feature/opencode-reuse",
+          stagedSummary: "M README.md",
+          stagedPatch: "diff --git a/README.md b/README.md",
+          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+        });
+        yield* textGeneration.generateCommitMessage({
+          cwd: process.cwd(),
+          branch: "feature/opencode-reuse",
+          stagedSummary: "M README.md",
+          stagedPatch: "diff --git a/README.md b/README.md",
+          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+        });
+
+        expect(runtimeMock.state.startCalls).toEqual(["fake-opencode"]);
+        expect(runtimeMock.state.promptUrls).toEqual([
+          "http://127.0.0.1:4301",
+          "http://127.0.0.1:4301",
+        ]);
+        expect(runtimeMock.state.closeCalls).toEqual([]);
+
+        yield* advanceIdleClock;
+
+        expect(runtimeMock.state.closeCalls).toEqual(["http://127.0.0.1:4301"]);
+      }),
+    ).pipe(Effect.provide(TestClock.layer())),
+  );
+
+  it.effect("starts a new server after the warm server idles out", () =>
+    withOpenCodeTextGeneration(DEFAULT_OPENCODE_SETTINGS, (textGeneration) =>
+      Effect.gen(function* () {
+        yield* textGeneration.generateCommitMessage({
+          cwd: process.cwd(),
+          branch: "feature/opencode-reuse",
+          stagedSummary: "M README.md",
+          stagedPatch: "diff --git a/README.md b/README.md",
+          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+        });
+
+        yield* advanceIdleClock;
+
+        yield* textGeneration.generateCommitMessage({
+          cwd: process.cwd(),
+          branch: "feature/opencode-reuse",
+          stagedSummary: "M README.md",
+          stagedPatch: "diff --git a/README.md b/README.md",
+          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+        });
+
+        expect(runtimeMock.state.startCalls).toEqual(["fake-opencode", "fake-opencode"]);
+        expect(runtimeMock.state.promptUrls).toEqual([
+          "http://127.0.0.1:4301",
+          "http://127.0.0.1:4302",
+        ]);
+        expect(runtimeMock.state.closeCalls).toEqual(["http://127.0.0.1:4301"]);
+      }),
+    ).pipe(Effect.provide(TestClock.layer())),
+  );
+
+  it.effect("returns a typed empty-output error when OpenCode returns no text parts", () =>
+    withOpenCodeTextGeneration(DEFAULT_OPENCODE_SETTINGS, (textGeneration) =>
+      Effect.gen(function* () {
+        runtimeMock.state.promptResult = { data: {} };
+
+        const error = yield* textGeneration
+          .generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/opencode-reuse",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          })
+          .pipe(Effect.flip);
+
+        expect(error.message).toContain("OpenCode returned empty output.");
+      }),
+    ),
+  );
+
+  it.effect("parses JSON returned as plain text output", () =>
+    withOpenCodeTextGeneration(DEFAULT_OPENCODE_SETTINGS, (textGeneration) =>
+      Effect.gen(function* () {
+        runtimeMock.state.promptResult = {
+          data: {
+            parts: [
+              {
+                type: "text",
+                text: 'Here is the result:\n{"subject":"Tighten OpenCode parsing","body":"Handle JSON text output locally."}',
+              },
+            ],
+          },
+        };
+
+        const result = yield* textGeneration.generateCommitMessage({
+          cwd: process.cwd(),
+          branch: "feature/opencode-reuse",
+          stagedSummary: "M README.md",
+          stagedPatch: "diff --git a/README.md b/README.md",
+          modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+        });
+
+        expect(result).toEqual({
+          subject: "Tighten OpenCode parsing",
+          body: "Handle JSON text output locally.",
+        });
+      }),
+    ),
+  );
+
+  it.effect("surfaces the upstream OpenCode structured-output error message", () =>
+    withOpenCodeTextGeneration(DEFAULT_OPENCODE_SETTINGS, (textGeneration) =>
+      Effect.gen(function* () {
+        runtimeMock.state.promptResult = {
+          data: {
+            info: {
+              error: {
+                name: "StructuredOutputError",
+                data: {
+                  message: "Model did not produce structured output",
+                  retries: 2,
+                },
+              },
+            },
+          },
+        };
+
+        const error = yield* textGeneration
+          .generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/opencode-reuse",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          })
+          .pipe(Effect.flip);
+
+        expect(error.message).toContain("Model did not produce structured output");
+      }),
+    ),
+  );
+});
+
+it.layer(OpenCodeTextGenerationExistingServerTestLayer)(
+  "OpenCodeTextGeneration with configured server URL",
+  (it) => {
+    it.effect("reuses a configured OpenCode server URL without spawning or applying idle TTL", () =>
+      withOpenCodeTextGeneration(EXISTING_SERVER_OPENCODE_SETTINGS, (textGeneration) =>
+        Effect.gen(function* () {
+          yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/opencode-reuse",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
+          yield* textGeneration.generateCommitMessage({
+            cwd: process.cwd(),
+            branch: "feature/opencode-reuse",
+            stagedSummary: "M README.md",
+            stagedPatch: "diff --git a/README.md b/README.md",
+            modelSelection: DEFAULT_TEST_MODEL_SELECTION,
+          });
+
+          expect(runtimeMock.state.startCalls).toEqual([]);
+          expect(runtimeMock.state.promptUrls).toEqual([
+            "http://127.0.0.1:9999",
+            "http://127.0.0.1:9999",
+          ]);
+          expect(runtimeMock.state.authHeaders).toEqual([
+            `Basic ${btoa("opencode:secret-password")}`,
+            `Basic ${btoa("opencode:secret-password")}`,
+          ]);
+
+          yield* advanceIdleClock;
+
+          expect(runtimeMock.state.closeCalls).toEqual([]);
+        }),
+      ).pipe(Effect.provide(TestClock.layer())),
+    );
+  },
+);
diff --git a/apps/server/src/textGeneration/OpenCodeTextGeneration.ts b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
new file mode 100644
index 00000000000..b865b2e5ef5
--- /dev/null
+++ b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
@@ -0,0 +1,467 @@
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+
+import {
+  TextGenerationError,
+  type ChatAttachment,
+  type ModelSelection,
+  type OpenCodeSettings,
+} from "@t3tools/contracts";
+import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
+import { getModelSelectionStringOptionValue } from "@t3tools/shared/model";
+import { extractJsonObject } from "@t3tools/shared/schemaJson";
+
+import { ServerConfig } from "../config.ts";
+import { resolveAttachmentPath } from "../attachmentStore.ts";
+import {
+  buildBranchNamePrompt,
+  buildCommitMessagePrompt,
+  buildPrContentPrompt,
+  buildThreadTitlePrompt,
+} from "./TextGenerationPrompts.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
+import {
+  sanitizeCommitSubject,
+  sanitizePrTitle,
+  sanitizeThreadTitle,
+} from "./TextGenerationUtils.ts";
+import {
+  OpenCodeRuntime,
+  type OpenCodeServerConnection,
+  type OpenCodeServerProcess,
+  openCodeRuntimeErrorDetail,
+  parseOpenCodeModelSlug,
+  toOpenCodeFileParts,
+} from "../provider/opencodeRuntime.ts";
+
+const OPENCODE_TEXT_GENERATION_IDLE_TTL = "30 seconds";
+
+function getOpenCodePromptErrorMessage(error: unknown): string | null {
+  if (!error || typeof error !== "object") {
+    return null;
+  }
+
+  const message =
+    "data" in error &&
+    error.data &&
+    typeof error.data === "object" &&
+    "message" in error.data &&
+    typeof error.data.message === "string"
+      ? error.data.message.trim()
+      : "";
+  if (message.length > 0) {
+    return message;
+  }
+
+  if ("name" in error && typeof error.name === "string") {
+    const name = error.name.trim();
+    return name.length > 0 ? name : null;
+  }
+
+  return null;
+}
+
+function getOpenCodeTextResponse(parts: ReadonlyArray<unknown> | undefined): string {
+  return (parts ?? [])
+    .flatMap((part) => {
+      if (!part || typeof part !== "object") {
+        return [];
+      }
+      if (!("type" in part) || part.type !== "text") {
+        return [];
+      }
+      if (!("text" in part) || typeof part.text !== "string") {
+        return [];
+      }
+      return [part.text];
+    })
+    .join("")
+    .trim();
+}
+
+interface SharedOpenCodeTextGenerationServerState {
+  server: OpenCodeServerProcess | null;
+  /**
+   * The scope that owns the shared server's lifetime. Closing this scope
+   * terminates the OpenCode child process and interrupts any fibers the
+   * runtime forked during startup. We don't hold a `close()` function on
+   * the server handle anymore — the scope is the only lifecycle handle.
+   */
+  serverScope: Scope.Closeable | null;
+  binaryPath: string | null;
+  activeRequests: number;
+  idleCloseFiber: Fiber.Fiber<void, never> | null;
+}
+
+export const makeOpenCodeTextGeneration = Effect.fn("makeOpenCodeTextGeneration")(function* (
+  openCodeSettings: OpenCodeSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const serverConfig = yield* ServerConfig;
+  const openCodeRuntime = yield* OpenCodeRuntime;
+  const idleFiberScope = yield* Effect.acquireRelease(Scope.make(), (scope) =>
+    Scope.close(scope, Exit.void),
+  );
+  const sharedServerMutex = yield* Semaphore.make(1);
+  const sharedServerState: SharedOpenCodeTextGenerationServerState = {
+    server: null,
+    serverScope: null,
+    binaryPath: null,
+    activeRequests: 0,
+    idleCloseFiber: null,
+  };
+
+  const closeSharedServer = Effect.fn("closeSharedServer")(function* () {
+    const scope = sharedServerState.serverScope;
+    sharedServerState.server = null;
+    sharedServerState.serverScope = null;
+    sharedServerState.binaryPath = null;
+    if (scope !== null) {
+      yield* Scope.close(scope, Exit.void).pipe(Effect.ignore);
+    }
+  });
+
+  const cancelIdleCloseFiber = Effect.fn("cancelIdleCloseFiber")(function* () {
+    const idleCloseFiber = sharedServerState.idleCloseFiber;
+    sharedServerState.idleCloseFiber = null;
+    if (idleCloseFiber !== null) {
+      yield* Fiber.interrupt(idleCloseFiber).pipe(Effect.ignore);
+    }
+  });
+
+  const scheduleIdleClose = Effect.fn("scheduleIdleClose")(function* (
+    server: OpenCodeServerProcess,
+  ) {
+    yield* cancelIdleCloseFiber();
+    const fiber = yield* Effect.sleep(OPENCODE_TEXT_GENERATION_IDLE_TTL).pipe(
+      Effect.andThen(
+        sharedServerMutex.withPermit(
+          Effect.gen(function* () {
+            if (sharedServerState.server !== server || sharedServerState.activeRequests > 0) {
+              return;
+            }
+            sharedServerState.idleCloseFiber = null;
+            yield* closeSharedServer();
+          }),
+        ),
+      ),
+      Effect.forkIn(idleFiberScope),
+    );
+    sharedServerState.idleCloseFiber = fiber;
+  });
+
+  const acquireSharedServer = (input: {
+    readonly binaryPath: string;
+    readonly operation:
+      | "generateCommitMessage"
+      | "generatePrContent"
+      | "generateBranchName"
+      | "generateThreadTitle";
+  }) =>
+    sharedServerMutex.withPermit(
+      Effect.gen(function* () {
+        yield* cancelIdleCloseFiber();
+
+        const existingServer = sharedServerState.server;
+        if (existingServer !== null) {
+          if (
+            sharedServerState.binaryPath !== input.binaryPath &&
+            sharedServerState.activeRequests === 0
+          ) {
+            yield* closeSharedServer();
+          } else {
+            if (sharedServerState.binaryPath !== input.binaryPath) {
+              yield* Effect.logWarning(
+                "OpenCode shared server binary path mismatch: requested " +
+                  input.binaryPath +
+                  " but active server uses " +
+                  sharedServerState.binaryPath +
+                  "; reusing existing server because there are active requests",
+              );
+            }
+            sharedServerState.activeRequests += 1;
+            return existingServer;
+          }
+        }
+
+        // Create a fresh scope that owns this shared server. The runtime
+        // will attach its child-process and fiber finalizers to this scope;
+        // closing it kills the server and interrupts those fibers.
+        //
+        // The `Scope.make` / spawn / record-or-close transitions run inside
+        // `uninterruptibleMask` so an interrupt arriving between any two
+        // steps can't orphan the scope (and the child process attached to
+        // it) before we either close it on failure or hand ownership to
+        // `sharedServerState`. `restore` keeps the actual spawn
+        // interruptible; an interrupt during the spawn is captured by
+        // `Effect.exit` and drives us through the failure branch that
+        // closes the fresh scope.
+        return yield* Effect.uninterruptibleMask((restore) =>
+          Effect.gen(function* () {
+            const serverScope = yield* Scope.make();
+            const startedExit = yield* Effect.exit(
+              restore(
+                openCodeRuntime
+                  .startOpenCodeServerProcess({
+                    binaryPath: input.binaryPath,
+                    environment,
+                  })
+                  .pipe(
+                    Effect.provideService(Scope.Scope, serverScope),
+                    Effect.mapError(
+                      (cause) =>
+                        new TextGenerationError({
+                          operation: input.operation,
+                          detail: openCodeRuntimeErrorDetail(cause),
+                          cause,
+                        }),
+                    ),
+                  ),
+              ),
+            );
+            if (startedExit._tag === "Failure") {
+              yield* Scope.close(serverScope, Exit.void).pipe(Effect.ignore);
+              return yield* Effect.failCause(startedExit.cause);
+            }
+
+            const server = startedExit.value;
+            sharedServerState.server = server;
+            sharedServerState.serverScope = serverScope;
+            sharedServerState.binaryPath = input.binaryPath;
+            sharedServerState.activeRequests = 1;
+            return server;
+          }),
+        );
+      }),
+    );
+
+  const releaseSharedServer = (server: OpenCodeServerProcess) =>
+    sharedServerMutex.withPermit(
+      Effect.gen(function* () {
+        if (sharedServerState.server !== server) {
+          return;
+        }
+        sharedServerState.activeRequests = Math.max(0, sharedServerState.activeRequests - 1);
+        if (sharedServerState.activeRequests === 0) {
+          yield* scheduleIdleClose(server);
+        }
+      }),
+    );
+
+  // Module-level finalizer: on layer shutdown, cancel the idle close fiber
+  // and close the shared server scope. Consumers therefore cannot leak
+  // the shared OpenCode server by forgetting to call anything.
+  yield* Effect.addFinalizer(() =>
+    sharedServerMutex.withPermit(
+      Effect.gen(function* () {
+        yield* cancelIdleCloseFiber();
+        sharedServerState.activeRequests = 0;
+        yield* closeSharedServer();
+      }),
+    ),
+  );
+
+  const runOpenCodeJson = Effect.fn("runOpenCodeJson")(function* <S extends Schema.Top>(input: {
+    readonly operation:
+      | "generateCommitMessage"
+      | "generatePrContent"
+      | "generateBranchName"
+      | "generateThreadTitle";
+    readonly cwd: string;
+    readonly prompt: string;
+    readonly outputSchemaJson: S;
+    readonly modelSelection: ModelSelection;
+    readonly attachments?: ReadonlyArray<ChatAttachment> | undefined;
+  }) {
+    const parsedModel = parseOpenCodeModelSlug(input.modelSelection.model);
+    if (!parsedModel) {
+      return yield* new TextGenerationError({
+        operation: input.operation,
+        detail: "OpenCode model selection must use the 'provider/model' format.",
+      });
+    }
+
+    const fileParts = toOpenCodeFileParts({
+      attachments: input.attachments,
+      resolveAttachmentPath: (attachment) =>
+        resolveAttachmentPath({ attachmentsDir: serverConfig.attachmentsDir, attachment }),
+    });
+
+    const runAgainstServer = (server: Pick<OpenCodeServerConnection, "url">) =>
+      Effect.tryPromise({
+        try: async () => {
+          const client = openCodeRuntime.createOpenCodeSdkClient({
+            baseUrl: server.url,
+            directory: input.cwd,
+            ...(openCodeSettings.serverUrl.length > 0 && openCodeSettings.serverPassword
+              ? { serverPassword: openCodeSettings.serverPassword }
+              : {}),
+          });
+          const session = await client.session.create({
+            title: `T3 Code ${input.operation}`,
+            permission: [{ permission: "*", pattern: "*", action: "deny" }],
+          });
+          if (!session.data) {
+            throw new Error("OpenCode session.create returned no session payload.");
+          }
+          const selectedAgent = getModelSelectionStringOptionValue(input.modelSelection, "agent");
+          const selectedVariant = getModelSelectionStringOptionValue(
+            input.modelSelection,
+            "variant",
+          );
+
+          const result = await client.session.prompt({
+            sessionID: session.data.id,
+            model: parsedModel,
+            ...(selectedAgent ? { agent: selectedAgent } : {}),
+            ...(selectedVariant ? { variant: selectedVariant } : {}),
+            parts: [{ type: "text", text: input.prompt }, ...fileParts],
+          });
+          const info = result.data?.info;
+          const errorMessage = getOpenCodePromptErrorMessage(info?.error);
+          if (errorMessage) {
+            throw new Error(errorMessage);
+          }
+          const rawText = getOpenCodeTextResponse(result.data?.parts);
+          if (rawText.length === 0) {
+            throw new Error("OpenCode returned empty output.");
+          }
+          return rawText;
+        },
+        catch: (cause) =>
+          new TextGenerationError({
+            operation: input.operation,
+            detail: openCodeRuntimeErrorDetail(cause),
+            cause,
+          }),
+      });
+
+    const rawOutput =
+      openCodeSettings.serverUrl.length > 0
+        ? yield* runAgainstServer({ url: openCodeSettings.serverUrl })
+        : yield* Effect.acquireUseRelease(
+            acquireSharedServer({
+              binaryPath: openCodeSettings.binaryPath,
+              operation: input.operation,
+            }),
+            runAgainstServer,
+            releaseSharedServer,
+          );
+
+    const decodeOutput = Schema.decodeEffect(Schema.fromJsonString(input.outputSchemaJson));
+    return yield* decodeOutput(extractJsonObject(rawOutput)).pipe(
+      Effect.catchTag("SchemaError", (cause) =>
+        Effect.fail(
+          new TextGenerationError({
+            operation: input.operation,
+            detail: "OpenCode returned invalid structured output.",
+            cause,
+          }),
+        ),
+      ),
+    );
+  });
+
+  const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = Effect.fn(
+    "OpenCodeTextGeneration.generateCommitMessage",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildCommitMessagePrompt({
+      branch: input.branch,
+      stagedSummary: input.stagedSummary,
+      stagedPatch: input.stagedPatch,
+      includeBranch: input.includeBranch === true,
+    });
+    const generated = yield* runOpenCodeJson({
+      operation: "generateCommitMessage",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+    });
+
+    return {
+      subject: sanitizeCommitSubject(generated.subject),
+      body: generated.body.trim(),
+      ...("branch" in generated && typeof generated.branch === "string"
+        ? { branch: sanitizeFeatureBranchName(generated.branch) }
+        : {}),
+    };
+  });
+
+  const generatePrContent: TextGenerationShape["generatePrContent"] = Effect.fn(
+    "OpenCodeTextGeneration.generatePrContent",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildPrContentPrompt({
+      baseBranch: input.baseBranch,
+      headBranch: input.headBranch,
+      commitSummary: input.commitSummary,
+      diffSummary: input.diffSummary,
+      diffPatch: input.diffPatch,
+    });
+    const generated = yield* runOpenCodeJson({
+      operation: "generatePrContent",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+    });
+
+    return {
+      title: sanitizePrTitle(generated.title),
+      body: generated.body.trim(),
+    };
+  });
+
+  const generateBranchName: TextGenerationShape["generateBranchName"] = Effect.fn(
+    "OpenCodeTextGeneration.generateBranchName",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildBranchNamePrompt({
+      message: input.message,
+      attachments: input.attachments,
+    });
+    const generated = yield* runOpenCodeJson({
+      operation: "generateBranchName",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+      attachments: input.attachments,
+    });
+
+    return {
+      branch: sanitizeBranchFragment(generated.branch),
+    };
+  });
+
+  const generateThreadTitle: TextGenerationShape["generateThreadTitle"] = Effect.fn(
+    "OpenCodeTextGeneration.generateThreadTitle",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildThreadTitlePrompt({
+      message: input.message,
+      attachments: input.attachments,
+    });
+    const generated = yield* runOpenCodeJson({
+      operation: "generateThreadTitle",
+      cwd: input.cwd,
+      prompt,
+      outputSchemaJson: outputSchema,
+      modelSelection: input.modelSelection,
+      attachments: input.attachments,
+    });
+
+    return {
+      title: sanitizeThreadTitle(generated.title),
+    };
+  });
+
+  return {
+    generateCommitMessage,
+    generatePrContent,
+    generateBranchName,
+    generateThreadTitle,
+  } satisfies TextGenerationShape;
+});
diff --git a/apps/server/src/textGeneration/TextGeneration.test.ts b/apps/server/src/textGeneration/TextGeneration.test.ts
new file mode 100644
index 00000000000..2f518f1656d
--- /dev/null
+++ b/apps/server/src/textGeneration/TextGeneration.test.ts
@@ -0,0 +1,120 @@
+import { it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as PubSub from "effect/PubSub";
+import * as Result from "effect/Result";
+import * as Stream from "effect/Stream";
+import { describe, expect } from "vitest";
+
+import { ProviderInstanceId } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
+
+import type { ProviderInstance } from "../provider/ProviderDriver.ts";
+import type { ProviderInstanceRegistryShape } from "../provider/Services/ProviderInstanceRegistry.ts";
+import type { TextGenerationShape } from "./TextGeneration.ts";
+
+import { makeTextGenerationFromRegistry } from "./TextGeneration.ts";
+
+const makeStubTextGeneration = (overrides: Partial<TextGenerationShape>): TextGenerationShape => ({
+  generateCommitMessage: () =>
+    Effect.die("generateCommitMessage stub not configured for this test"),
+  generatePrContent: () => Effect.die("generatePrContent stub not configured for this test"),
+  generateBranchName: () => Effect.die("generateBranchName stub not configured for this test"),
+  generateThreadTitle: () => Effect.die("generateThreadTitle stub not configured for this test"),
+  ...overrides,
+});
+
+const makeStubInstance = (
+  instanceId: ProviderInstanceId,
+  textGeneration: TextGenerationShape,
+): ProviderInstance =>
+  ({
+    instanceId,
+    driverKind: instanceId as unknown as ProviderInstance["driverKind"],
+    continuationIdentity: {
+      driverKind: instanceId as unknown as ProviderInstance["driverKind"],
+      continuationKey: `${instanceId}:test`,
+    },
+    displayName: undefined,
+    enabled: true,
+    snapshot: {} as ProviderInstance["snapshot"],
+    adapter: {} as ProviderInstance["adapter"],
+    textGeneration,
+  }) satisfies ProviderInstance;
+
+const makeStubRegistry = (
+  instances: ReadonlyArray<ProviderInstance>,
+): ProviderInstanceRegistryShape => {
+  const byId = new Map(instances.map((instance) => [instance.instanceId, instance] as const));
+  return {
+    getInstance: (id) => Effect.succeed(byId.get(id)),
+    listInstances: Effect.succeed(instances),
+    listUnavailable: Effect.succeed([]),
+    streamChanges: Stream.empty,
+    // Tests never drive changes through this stub; acquire a throwaway
+    // subscription on an unused PubSub so the shape is satisfied.
+    subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+      PubSub.subscribe(pubsub),
+    ),
+  };
+};
+
+describe("makeTextGenerationFromRegistry", () => {
+  it.effect("delegates to the matching instance's textGeneration closure", () =>
+    Effect.gen(function* () {
+      const personalId = ProviderInstanceId.make("codex_personal");
+      const personalCalls: string[] = [];
+      const personal = makeStubInstance(
+        personalId,
+        makeStubTextGeneration({
+          generateBranchName: (input) => {
+            personalCalls.push(input.message);
+            return Effect.succeed({ branch: "personal-branch" });
+          },
+        }),
+      );
+
+      const workId = ProviderInstanceId.make("codex_work");
+      const work = makeStubInstance(
+        workId,
+        makeStubTextGeneration({
+          generateBranchName: () => Effect.succeed({ branch: "work-branch" }),
+        }),
+      );
+
+      const tg = makeTextGenerationFromRegistry(makeStubRegistry([personal, work]));
+
+      const result = yield* tg.generateBranchName({
+        cwd: process.cwd(),
+        message: "Refactor the routing layer",
+        modelSelection: createModelSelection(ProviderInstanceId.make("codex_personal"), "gpt-5"),
+      });
+
+      expect(result.branch).toBe("personal-branch");
+      expect(personalCalls).toEqual(["Refactor the routing layer"]);
+    }),
+  );
+
+  it.effect("fails with TextGenerationError when the instance is unknown", () =>
+    Effect.gen(function* () {
+      const tg = makeTextGenerationFromRegistry(makeStubRegistry([]));
+
+      const result = yield* tg
+        .generateBranchName({
+          cwd: process.cwd(),
+          message: "anything",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("missing_instance"),
+            "gpt-5",
+          ),
+        })
+        .pipe(Effect.result);
+
+      expect(Result.isFailure(result)).toBe(true);
+      if (Result.isFailure(result)) {
+        expect(result.failure._tag).toBe("TextGenerationError");
+        expect(result.failure.operation).toBe("generateBranchName");
+        expect(result.failure.detail).toContain("missing_instance");
+      }
+    }),
+  );
+});
diff --git a/apps/server/src/git/Services/TextGeneration.ts b/apps/server/src/textGeneration/TextGeneration.ts
similarity index 55%
rename from apps/server/src/git/Services/TextGeneration.ts
rename to apps/server/src/textGeneration/TextGeneration.ts
index 6062d552d95..36a23d509db 100644
--- a/apps/server/src/git/Services/TextGeneration.ts
+++ b/apps/server/src/textGeneration/TextGeneration.ts
@@ -1,19 +1,16 @@
-/**
- * TextGeneration - Effect service contract for AI-generated Git content.
- *
- * Generates commit messages and pull request titles/bodies from repository
- * context prepared by Git services.
- *
- * @module TextGeneration
- */
-import { Context } from "effect";
-import type { Effect } from "effect";
-import type { ChatAttachment, ModelSelection } from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { ChatAttachment, ModelSelection, ProviderInstanceId } from "@t3tools/contracts";
+import { TextGenerationError } from "@t3tools/contracts";
 
-import type { TextGenerationError } from "@t3tools/contracts";
+import {
+  ProviderInstanceRegistry,
+  type ProviderInstanceRegistryShape,
+} from "../provider/Services/ProviderInstanceRegistry.ts";
+import type { ProviderInstance } from "../provider/ProviderDriver.ts";
 
-/** Providers that support git text generation (commit messages, PR content, branch names). */
-export type TextGenerationProvider = "codex" | "claudeAgent";
+export type TextGenerationProvider = "codex" | "claudeAgent" | "cursor" | "opencode";
 
 export interface CommitMessageGenerationInput {
   cwd: string;
@@ -119,5 +116,58 @@ export interface TextGenerationShape {
  * TextGeneration - Service tag for commit and PR text generation.
  */
 export class TextGeneration extends Context.Service<TextGeneration, TextGenerationShape>()(
-  "t3/git/Services/TextGeneration",
+  "t3/text-generation/TextGeneration",
 ) {}
+
+type TextGenerationOp =
+  | "generateCommitMessage"
+  | "generatePrContent"
+  | "generateBranchName"
+  | "generateThreadTitle";
+
+const resolveInstance = (
+  registry: ProviderInstanceRegistryShape,
+  operation: TextGenerationOp,
+  instanceId: ProviderInstanceId,
+): Effect.Effect<ProviderInstance["textGeneration"], TextGenerationError> =>
+  registry.getInstance(instanceId).pipe(
+    Effect.flatMap((instance) =>
+      instance
+        ? Effect.succeed(instance.textGeneration)
+        : Effect.fail(
+            new TextGenerationError({
+              operation,
+              detail: `No provider instance registered for id '${instanceId}'.`,
+            }),
+          ),
+    ),
+  );
+
+export const makeTextGenerationFromRegistry = (
+  registry: ProviderInstanceRegistryShape,
+): TextGenerationShape => ({
+  generateCommitMessage: (input) =>
+    resolveInstance(registry, "generateCommitMessage", input.modelSelection.instanceId).pipe(
+      Effect.flatMap((textGeneration) => textGeneration.generateCommitMessage(input)),
+    ),
+  generatePrContent: (input) =>
+    resolveInstance(registry, "generatePrContent", input.modelSelection.instanceId).pipe(
+      Effect.flatMap((textGeneration) => textGeneration.generatePrContent(input)),
+    ),
+  generateBranchName: (input) =>
+    resolveInstance(registry, "generateBranchName", input.modelSelection.instanceId).pipe(
+      Effect.flatMap((textGeneration) => textGeneration.generateBranchName(input)),
+    ),
+  generateThreadTitle: (input) =>
+    resolveInstance(registry, "generateThreadTitle", input.modelSelection.instanceId).pipe(
+      Effect.flatMap((textGeneration) => textGeneration.generateThreadTitle(input)),
+    ),
+});
+
+export const layer = Layer.effect(
+  TextGeneration,
+  Effect.gen(function* () {
+    const registry = yield* ProviderInstanceRegistry;
+    return makeTextGenerationFromRegistry(registry);
+  }),
+);
diff --git a/apps/server/src/textGeneration/TextGenerationPolicy.ts b/apps/server/src/textGeneration/TextGenerationPolicy.ts
new file mode 100644
index 00000000000..422927373d3
--- /dev/null
+++ b/apps/server/src/textGeneration/TextGenerationPolicy.ts
@@ -0,0 +1,19 @@
+import * as Schema from "effect/Schema";
+
+export const TextGenerationPolicyKind = Schema.Literals([
+  "default",
+  "conventional_commits",
+  "repo_conventions",
+  "custom",
+]);
+export type TextGenerationPolicyKind = typeof TextGenerationPolicyKind.Type;
+
+export const TextGenerationPolicy = Schema.Struct({
+  kind: TextGenerationPolicyKind,
+  commitInstructions: Schema.optional(Schema.String),
+  changeRequestInstructions: Schema.optional(Schema.String),
+  branchInstructions: Schema.optional(Schema.String),
+  threadTitleInstructions: Schema.optional(Schema.String),
+  inferRepositoryConventions: Schema.Boolean,
+});
+export type TextGenerationPolicy = typeof TextGenerationPolicy.Type;
diff --git a/apps/server/src/textGeneration/TextGenerationPresets.ts b/apps/server/src/textGeneration/TextGenerationPresets.ts
new file mode 100644
index 00000000000..70955742148
--- /dev/null
+++ b/apps/server/src/textGeneration/TextGenerationPresets.ts
@@ -0,0 +1,41 @@
+import type { TextGenerationPolicy, TextGenerationPolicyKind } from "./TextGenerationPolicy.ts";
+
+export const defaultTextGenerationPolicy: TextGenerationPolicy = {
+  kind: "default",
+  inferRepositoryConventions: false,
+};
+
+export const conventionalCommitsTextGenerationPolicy: TextGenerationPolicy = {
+  kind: "conventional_commits",
+  commitInstructions:
+    "Use Conventional Commits when generating commit subjects. Prefer the narrowest accurate type and include a scope only when it is obvious from the diff.",
+  changeRequestInstructions:
+    "Keep the change request title concise. Do not force Conventional Commit syntax into the title unless the repository already uses it.",
+  inferRepositoryConventions: false,
+};
+
+export const repositoryConventionsTextGenerationPolicy: TextGenerationPolicy = {
+  kind: "repo_conventions",
+  commitInstructions:
+    "Follow the repository's established commit message style when examples are available.",
+  changeRequestInstructions:
+    "Follow the repository's established change request title and body style when examples are available.",
+  inferRepositoryConventions: true,
+};
+
+export const customTextGenerationPolicy = (
+  overrides: Omit<Partial<TextGenerationPolicy>, "kind">,
+): TextGenerationPolicy => ({
+  kind: "custom",
+  inferRepositoryConventions: false,
+  ...overrides,
+});
+
+export const textGenerationPresets: Record<
+  Exclude<TextGenerationPolicyKind, "custom">,
+  TextGenerationPolicy
+> = {
+  default: defaultTextGenerationPolicy,
+  conventional_commits: conventionalCommitsTextGenerationPolicy,
+  repo_conventions: repositoryConventionsTextGenerationPolicy,
+};
diff --git a/apps/server/src/git/Prompts.test.ts b/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
similarity index 98%
rename from apps/server/src/git/Prompts.test.ts
rename to apps/server/src/textGeneration/TextGenerationPrompts.test.ts
index d8d079c0cf3..25fed642270 100644
--- a/apps/server/src/git/Prompts.test.ts
+++ b/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
@@ -5,8 +5,8 @@ import {
   buildCommitMessagePrompt,
   buildPrContentPrompt,
   buildThreadTitlePrompt,
-} from "./Prompts.ts";
-import { normalizeCliError, sanitizeThreadTitle } from "./Utils.ts";
+} from "./TextGenerationPrompts.ts";
+import { normalizeCliError, sanitizeThreadTitle } from "./TextGenerationUtils.ts";
 import { TextGenerationError } from "@t3tools/contracts";
 
 describe("buildCommitMessagePrompt", () => {
diff --git a/apps/server/src/git/Prompts.ts b/apps/server/src/textGeneration/TextGenerationPrompts.ts
similarity index 86%
rename from apps/server/src/git/Prompts.ts
rename to apps/server/src/textGeneration/TextGenerationPrompts.ts
index 4092358825c..6015e83b5d4 100644
--- a/apps/server/src/git/Prompts.ts
+++ b/apps/server/src/textGeneration/TextGenerationPrompts.ts
@@ -6,10 +6,16 @@
  *
  * @module textGenerationPrompts
  */
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 import type { ChatAttachment } from "@t3tools/contracts";
 
-import { limitSection } from "./Utils.ts";
+import { limitSection } from "./TextGenerationUtils.ts";
+import type { TextGenerationPolicy } from "./TextGenerationPolicy.ts";
+
+function policyInstruction(instruction: string | undefined): ReadonlyArray<string> {
+  const trimmed = instruction?.trim();
+  return trimmed ? ["", "Additional instructions:", limitSection(trimmed, 4_000)] : [];
+}
 
 // ---------------------------------------------------------------------------
 // Commit message
@@ -20,6 +26,7 @@ export interface CommitMessagePromptInput {
   stagedSummary: string;
   stagedPatch: string;
   includeBranch: boolean;
+  policy?: TextGenerationPolicy | undefined;
 }
 
 export function buildCommitMessagePrompt(input: CommitMessagePromptInput) {
@@ -37,6 +44,7 @@ export function buildCommitMessagePrompt(input: CommitMessagePromptInput) {
       ? ["- branch must be a short semantic git branch fragment for this change"]
       : []),
     "- capture the primary user-visible or developer-visible change",
+    ...policyInstruction(input.policy?.commitInstructions),
     "",
     `Branch: ${input.branch ?? "(detached)"}`,
     "",
@@ -77,6 +85,7 @@ export interface PrContentPromptInput {
   commitSummary: string;
   diffSummary: string;
   diffPatch: string;
+  policy?: TextGenerationPolicy | undefined;
 }
 
 export function buildPrContentPrompt(input: PrContentPromptInput) {
@@ -88,6 +97,7 @@ export function buildPrContentPrompt(input: PrContentPromptInput) {
     "- body must be markdown and include headings '## Summary' and '## Testing'",
     "- under Summary, provide short bullet points",
     "- under Testing, include bullet points with concrete checks or 'Not run' where appropriate",
+    ...policyInstruction(input.policy?.changeRequestInstructions),
     "",
     `Base branch: ${input.baseBranch}`,
     `Head branch: ${input.headBranch}`,
@@ -117,6 +127,7 @@ export function buildPrContentPrompt(input: PrContentPromptInput) {
 export interface BranchNamePromptInput {
   message: string;
   attachments?: ReadonlyArray<ChatAttachment> | undefined;
+  policy?: TextGenerationPolicy | undefined;
 }
 
 interface PromptFromMessageInput {
@@ -125,6 +136,7 @@ interface PromptFromMessageInput {
   rules: ReadonlyArray<string>;
   message: string;
   attachments?: ReadonlyArray<ChatAttachment> | undefined;
+  additionalInstructions?: string | undefined;
 }
 
 function buildPromptFromMessage(input: PromptFromMessageInput): string {
@@ -140,6 +152,7 @@ function buildPromptFromMessage(input: PromptFromMessageInput): string {
     "",
     "User message:",
     limitSection(input.message, 8_000),
+    ...policyInstruction(input.additionalInstructions),
   ];
   if (attachmentLines.length > 0) {
     promptSections.push(
@@ -164,6 +177,7 @@ export function buildBranchNamePrompt(input: BranchNamePromptInput) {
     ],
     message: input.message,
     attachments: input.attachments,
+    additionalInstructions: input.policy?.branchInstructions,
   });
   const outputSchema = Schema.Struct({
     branch: Schema.String,
@@ -179,6 +193,7 @@ export function buildBranchNamePrompt(input: BranchNamePromptInput) {
 export interface ThreadTitlePromptInput {
   message: string;
   attachments?: ReadonlyArray<ChatAttachment> | undefined;
+  policy?: TextGenerationPolicy | undefined;
 }
 
 export function buildThreadTitlePrompt(input: ThreadTitlePromptInput) {
@@ -193,6 +208,7 @@ export function buildThreadTitlePrompt(input: ThreadTitlePromptInput) {
     ],
     message: input.message,
     attachments: input.attachments,
+    additionalInstructions: input.policy?.threadTitleInstructions,
   });
   const outputSchema = Schema.Struct({
     title: Schema.String,
diff --git a/apps/server/src/textGeneration/TextGenerationUtils.ts b/apps/server/src/textGeneration/TextGenerationUtils.ts
new file mode 100644
index 00000000000..a786f81b2c8
--- /dev/null
+++ b/apps/server/src/textGeneration/TextGenerationUtils.ts
@@ -0,0 +1,112 @@
+import { TextGenerationError } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+
+const isTextGenerationError = Schema.is(TextGenerationError);
+
+/** Convert an Effect Schema to a flat JSON Schema object, inlining `$defs` when present. */
+export function toJsonSchemaObject(schema: Schema.Top): unknown {
+  const document = Schema.toJsonSchemaDocument(schema);
+  if (document.definitions && Object.keys(document.definitions).length > 0) {
+    return { ...document.schema, $defs: document.definitions };
+  }
+  return document.schema;
+}
+
+/** Truncate a text section to `maxChars`, appending a `[truncated]` marker when needed. */
+export function limitSection(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  const truncated = value.slice(0, maxChars);
+  return `${truncated}\n\n[truncated]`;
+}
+
+/** Normalise a raw commit subject to imperative-mood, ≤72 chars, no trailing period. */
+export function sanitizeCommitSubject(raw: string): string {
+  const singleLine = raw.trim().split(/\r?\n/g)[0]?.trim() ?? "";
+  const withoutTrailingPeriod = singleLine.replace(/[.]+$/g, "").trim();
+  if (withoutTrailingPeriod.length === 0) {
+    return "Update project files";
+  }
+
+  if (withoutTrailingPeriod.length <= 72) {
+    return withoutTrailingPeriod;
+  }
+  return withoutTrailingPeriod.slice(0, 72).trimEnd();
+}
+
+/** Normalise a raw PR title to a single line with a sensible fallback. */
+export function sanitizePrTitle(raw: string): string {
+  const singleLine = raw.trim().split(/\r?\n/g)[0]?.trim() ?? "";
+  if (singleLine.length > 0) {
+    return singleLine;
+  }
+  return "Update project changes";
+}
+
+/** Normalise a raw thread title to a compact single-line sidebar-safe label. */
+export function sanitizeThreadTitle(raw: string): string {
+  const normalized = raw
+    .trim()
+    .split(/\r?\n/g)[0]
+    ?.trim()
+    .replace(/^['"`]+|['"`]+$/g, "")
+    .trim()
+    .replace(/\s+/g, " ");
+
+  if (!normalized || normalized.trim().length === 0) {
+    return "New thread";
+  }
+
+  if (normalized.length <= 50) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, 47).trimEnd()}...`;
+}
+
+/** CLI name to human-readable label, e.g. "codex" → "Codex CLI (`codex`)" */
+function cliLabel(cliName: string): string {
+  const capitalized = cliName.charAt(0).toUpperCase() + cliName.slice(1);
+  return `${capitalized} CLI (\`${cliName}\`)`;
+}
+
+/**
+ * Normalize an unknown error from a CLI text generation process into a
+ * typed `TextGenerationError`. Parameterized by CLI name so both Codex
+ * and Claude (and future providers) can share the same logic.
+ */
+export function normalizeCliError(
+  cliName: string,
+  operation: string,
+  error: unknown,
+  fallback: string,
+): TextGenerationError {
+  if (isTextGenerationError(error)) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    const lower = error.message.toLowerCase();
+    if (
+      error.message.includes(`Command not found: ${cliName}`) ||
+      lower.includes(`spawn ${cliName}`) ||
+      lower.includes("enoent")
+    ) {
+      return new TextGenerationError({
+        operation,
+        detail: `${cliLabel(cliName)} is required but not available on PATH.`,
+        cause: error,
+      });
+    }
+    return new TextGenerationError({
+      operation,
+      detail: `${fallback}: ${error.message}`,
+      cause: error,
+    });
+  }
+
+  return new TextGenerationError({
+    operation,
+    detail: fallback,
+    cause: error,
+  });
+}
diff --git a/apps/server/src/vcs/GitVcsDriver.test.ts b/apps/server/src/vcs/GitVcsDriver.test.ts
new file mode 100644
index 00000000000..70bb8655ea1
--- /dev/null
+++ b/apps/server/src/vcs/GitVcsDriver.test.ts
@@ -0,0 +1,110 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { assert, it } from "@effect/vitest";
+
+import { GitCommandError } from "@t3tools/contracts";
+import { ServerConfig } from "../config.ts";
+import * as GitVcsDriver from "./GitVcsDriver.ts";
+import * as VcsProcess from "./VcsProcess.ts";
+import { runVcsDriverContractSuite } from "./testing/VcsDriverContractHarness.ts";
+
+const ServerConfigLayer = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3-git-vcs-contract-",
+});
+const GitContractLayer = Layer.mergeAll(GitVcsDriver.vcsLayer, GitVcsDriver.layer).pipe(
+  Layer.provide(ServerConfigLayer),
+  Layer.provideMerge(VcsProcess.layer),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+const runGit = (cwd: string, args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const driver = yield* GitVcsDriver.GitVcsDriver;
+    yield* driver.execute({
+      operation: "GitVcsDriver.contract.git",
+      cwd,
+      args,
+      timeoutMs: 10_000,
+    });
+  });
+
+type GitContractError = GitCommandError | PlatformError.PlatformError;
+
+runVcsDriverContractSuite<GitVcsDriver.GitVcsDriver, GitContractError>({
+  name: "Git",
+  kind: "git",
+  layer: GitContractLayer,
+  fixture: {
+    createRepo: (cwd) =>
+      Effect.gen(function* () {
+        yield* runGit(cwd, ["init"]);
+        yield* runGit(cwd, ["config", "user.email", "test@test.com"]);
+        yield* runGit(cwd, ["config", "user.name", "Test"]);
+      }),
+    writeFile: (cwd, relativePath, contents) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const absolutePath = path.join(cwd, relativePath);
+        yield* fileSystem.makeDirectory(path.dirname(absolutePath), { recursive: true });
+        yield* fileSystem.writeFileString(absolutePath, contents);
+      }),
+    trackFile: (cwd, relativePath) => runGit(cwd, ["add", relativePath]),
+    commit: (cwd, message) => runGit(cwd, ["commit", "-m", message]),
+    ignorePath: (cwd, pattern) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        yield* fileSystem.writeFileString(path.join(cwd, ".gitignore"), `${pattern}\n`);
+      }),
+  },
+});
+
+it.effect("GitVcsDriver forwards execute env to the VCS process", () => {
+  let observedEnv: NodeJS.ProcessEnv | undefined;
+  let observedAppendTruncationMarker: boolean | undefined;
+
+  return Effect.gen(function* () {
+    const driver = yield* GitVcsDriver.makeVcsDriverShape();
+
+    yield* driver.execute({
+      operation: "GitVcsDriver.test.env",
+      cwd: "/repo",
+      args: ["status"],
+      env: {
+        GIT_INDEX_FILE: "/tmp/t3-index",
+      },
+      appendTruncationMarker: true,
+    });
+
+    assert.deepStrictEqual(observedEnv, {
+      GIT_INDEX_FILE: "/tmp/t3-index",
+    });
+    assert.strictEqual(observedAppendTruncationMarker, true);
+  }).pipe(
+    Effect.provide(
+      Layer.mergeAll(
+        NodeServices.layer,
+        Layer.mock(VcsProcess.VcsProcess)({
+          run: (input) =>
+            Effect.sync(() => {
+              observedEnv = input.env;
+              observedAppendTruncationMarker = input.appendTruncationMarker;
+              return {
+                exitCode: ChildProcessSpawner.ExitCode(0),
+                stdout: "",
+                stderr: "",
+                stdoutTruncated: false,
+                stderrTruncated: false,
+              };
+            }),
+        }),
+      ),
+    ),
+  );
+});
diff --git a/apps/server/src/vcs/GitVcsDriver.ts b/apps/server/src/vcs/GitVcsDriver.ts
new file mode 100644
index 00000000000..c07aeaa09f0
--- /dev/null
+++ b/apps/server/src/vcs/GitVcsDriver.ts
@@ -0,0 +1,827 @@
+import { randomUUID } from "node:crypto";
+
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  GitCommandError,
+  VcsProcessExitError,
+  type VcsSwitchRefInput,
+  type VcsSwitchRefResult,
+  type VcsCreateRefInput,
+  type VcsCreateRefResult,
+  type VcsCreateWorktreeInput,
+  type VcsCreateWorktreeResult,
+  type VcsInitInput,
+  type VcsListRefsInput,
+  type VcsListRefsResult,
+  type VcsPullResult,
+  type VcsRemoveWorktreeInput,
+  type VcsStatusInput,
+  type VcsStatusResult,
+} from "@t3tools/contracts";
+import * as GitVcsDriverCore from "./GitVcsDriverCore.ts";
+import * as VcsDriver from "./VcsDriver.ts";
+import * as VcsProcess from "./VcsProcess.ts";
+
+export interface ExecuteGitInput {
+  readonly operation: string;
+  readonly cwd: string;
+  readonly args: ReadonlyArray<string>;
+  readonly stdin?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly allowNonZeroExit?: boolean;
+  readonly timeoutMs?: number;
+  readonly maxOutputBytes?: number;
+  readonly appendTruncationMarker?: boolean;
+  readonly progress?: ExecuteGitProgress;
+}
+
+export interface ExecuteGitResult {
+  readonly exitCode: ChildProcessSpawner.ExitCode;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+}
+
+export interface GitStatusDetails {
+  isRepo: boolean;
+  sourceControlProvider?: VcsStatusResult["sourceControlProvider"];
+  hasOriginRemote: boolean;
+  isDefaultBranch: boolean;
+  branch: string | null;
+  upstreamRef: string | null;
+  hasWorkingTreeChanges: boolean;
+  workingTree: VcsStatusResult["workingTree"];
+  hasUpstream: boolean;
+  aheadCount: number;
+  behindCount: number;
+  aheadOfDefaultCount: number;
+}
+
+export interface GitPreparedCommitContext {
+  stagedSummary: string;
+  stagedPatch: string;
+}
+
+export interface ExecuteGitProgress {
+  readonly onStdoutLine?: (line: string) => Effect.Effect<void, never>;
+  readonly onStderrLine?: (line: string) => Effect.Effect<void, never>;
+  readonly onHookStarted?: (hookName: string) => Effect.Effect<void, never>;
+  readonly onHookFinished?: (input: {
+    hookName: string;
+    exitCode: number | null;
+    durationMs: number | null;
+  }) => Effect.Effect<void, never>;
+}
+
+export interface GitCommitProgress {
+  readonly onOutputLine?: (input: {
+    stream: "stdout" | "stderr";
+    text: string;
+  }) => Effect.Effect<void, never>;
+  readonly onHookStarted?: (hookName: string) => Effect.Effect<void, never>;
+  readonly onHookFinished?: (input: {
+    hookName: string;
+    exitCode: number | null;
+    durationMs: number | null;
+  }) => Effect.Effect<void, never>;
+}
+
+export interface GitCommitOptions {
+  readonly timeoutMs?: number;
+  readonly progress?: GitCommitProgress;
+}
+
+export interface GitPushResult {
+  status: "pushed" | "skipped_up_to_date";
+  branch: string;
+  upstreamBranch?: string | undefined;
+  setUpstream?: boolean | undefined;
+}
+
+export interface GitRangeContext {
+  commitSummary: string;
+  diffSummary: string;
+  diffPatch: string;
+}
+
+export interface GitRenameBranchInput {
+  cwd: string;
+  oldBranch: string;
+  newBranch: string;
+}
+
+export interface GitRenameBranchResult {
+  branch: string;
+}
+
+export interface GitFetchPullRequestBranchInput {
+  cwd: string;
+  prNumber: number;
+  branch: string;
+}
+
+export interface GitEnsureRemoteInput {
+  cwd: string;
+  preferredName: string;
+  url: string;
+}
+
+export interface GitFetchRemoteBranchInput {
+  cwd: string;
+  remoteName: string;
+  remoteBranch: string;
+  localBranch: string;
+}
+
+export interface GitFetchRemoteTrackingBranchInput {
+  cwd: string;
+  remoteName: string;
+  remoteBranch: string;
+}
+
+export interface GitSetBranchUpstreamInput {
+  cwd: string;
+  branch: string;
+  remoteName: string;
+  remoteBranch: string;
+}
+
+export interface GitVcsDriverShape {
+  readonly execute: (input: ExecuteGitInput) => Effect.Effect<ExecuteGitResult, GitCommandError>;
+  readonly status: (input: VcsStatusInput) => Effect.Effect<VcsStatusResult, GitCommandError>;
+  readonly statusDetails: (cwd: string) => Effect.Effect<GitStatusDetails, GitCommandError>;
+  readonly statusDetailsLocal: (cwd: string) => Effect.Effect<GitStatusDetails, GitCommandError>;
+  readonly prepareCommitContext: (
+    cwd: string,
+    filePaths?: readonly string[],
+  ) => Effect.Effect<GitPreparedCommitContext | null, GitCommandError>;
+  readonly commit: (
+    cwd: string,
+    subject: string,
+    body: string,
+    options?: GitCommitOptions,
+  ) => Effect.Effect<{ commitSha: string }, GitCommandError>;
+  readonly pushCurrentBranch: (
+    cwd: string,
+    fallbackBranch: string | null,
+    options?: { readonly remoteName?: string | null },
+  ) => Effect.Effect<GitPushResult, GitCommandError>;
+  readonly readRangeContext: (
+    cwd: string,
+    baseRef: string,
+  ) => Effect.Effect<GitRangeContext, GitCommandError>;
+  readonly readConfigValue: (
+    cwd: string,
+    key: string,
+  ) => Effect.Effect<string | null, GitCommandError>;
+  readonly listRefs: (input: VcsListRefsInput) => Effect.Effect<VcsListRefsResult, GitCommandError>;
+  readonly pullCurrentBranch: (cwd: string) => Effect.Effect<VcsPullResult, GitCommandError>;
+  readonly createWorktree: (
+    input: VcsCreateWorktreeInput,
+  ) => Effect.Effect<VcsCreateWorktreeResult, GitCommandError>;
+  readonly fetchPullRequestBranch: (
+    input: GitFetchPullRequestBranchInput,
+  ) => Effect.Effect<void, GitCommandError>;
+  readonly ensureRemote: (input: GitEnsureRemoteInput) => Effect.Effect<string, GitCommandError>;
+  readonly resolvePrimaryRemoteName: (cwd: string) => Effect.Effect<string, GitCommandError>;
+  readonly fetchRemoteBranch: (
+    input: GitFetchRemoteBranchInput,
+  ) => Effect.Effect<void, GitCommandError>;
+  readonly fetchRemoteTrackingBranch: (
+    input: GitFetchRemoteTrackingBranchInput,
+  ) => Effect.Effect<void, GitCommandError>;
+  readonly setBranchUpstream: (
+    input: GitSetBranchUpstreamInput,
+  ) => Effect.Effect<void, GitCommandError>;
+  readonly removeWorktree: (input: VcsRemoveWorktreeInput) => Effect.Effect<void, GitCommandError>;
+  readonly renameBranch: (
+    input: GitRenameBranchInput,
+  ) => Effect.Effect<GitRenameBranchResult, GitCommandError>;
+  readonly createRef: (
+    input: VcsCreateRefInput,
+  ) => Effect.Effect<VcsCreateRefResult, GitCommandError>;
+  readonly switchRef: (
+    input: VcsSwitchRefInput,
+  ) => Effect.Effect<VcsSwitchRefResult, GitCommandError>;
+  readonly initRepo: (input: VcsInitInput) => Effect.Effect<void, GitCommandError>;
+  readonly listLocalBranchNames: (cwd: string) => Effect.Effect<string[], GitCommandError>;
+}
+
+export class GitVcsDriver extends Context.Service<GitVcsDriver, GitVcsDriverShape>()(
+  "t3/vcs/GitVcsDriver",
+) {}
+
+const WORKSPACE_FILES_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+const GIT_CHECK_IGNORE_MAX_STDIN_BYTES = 256 * 1024;
+const CHECKPOINT_DIFF_MAX_OUTPUT_BYTES = 10_000_000;
+const WORKSPACE_GIT_HARDENED_CONFIG_ARGS = [
+  "-c",
+  "core.fsmonitor=false",
+  "-c",
+  "core.untrackedCache=false",
+] as const;
+
+const nowFreshness = Effect.fn("GitVcsDriver.nowFreshness")(function* () {
+  const now = yield* DateTime.now;
+  return {
+    source: "live-local" as const,
+    observedAt: now,
+    expiresAt: Option.none(),
+  };
+});
+
+function splitNullSeparatedPaths(input: string, truncated: boolean): string[] {
+  const parts = input.split("\0");
+  if (parts.length === 0) return [];
+
+  if (truncated && parts[parts.length - 1]?.length) {
+    parts.pop();
+  }
+
+  return parts.filter((value) => value.length > 0);
+}
+
+function chunkPathsForGitCheckIgnore(relativePaths: ReadonlyArray<string>): string[][] {
+  const chunks: string[][] = [];
+  let chunk: string[] = [];
+  let chunkBytes = 0;
+
+  for (const relativePath of relativePaths) {
+    const relativePathBytes = Buffer.byteLength(relativePath) + 1;
+    if (chunk.length > 0 && chunkBytes + relativePathBytes > GIT_CHECK_IGNORE_MAX_STDIN_BYTES) {
+      chunks.push(chunk);
+      chunk = [];
+      chunkBytes = 0;
+    }
+
+    chunk.push(relativePath);
+    chunkBytes += relativePathBytes;
+
+    if (chunkBytes >= GIT_CHECK_IGNORE_MAX_STDIN_BYTES) {
+      chunks.push(chunk);
+      chunk = [];
+      chunkBytes = 0;
+    }
+  }
+
+  if (chunk.length > 0) {
+    chunks.push(chunk);
+  }
+
+  return chunks;
+}
+
+function parseGitRemoteVerboseOutput(
+  output: string,
+): Map<string, { url?: string; pushUrl?: string }> {
+  const remotes = new Map<string, { url?: string; pushUrl?: string }>();
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+
+    const match = /^(\S+)\s+(\S+)\s+\((fetch|push)\)$/.exec(trimmed);
+    if (!match) {
+      continue;
+    }
+
+    const name = match[1];
+    const url = match[2];
+    const direction = match[3];
+    if (!name || !url || !direction) {
+      continue;
+    }
+    const remote = remotes.get(name) ?? {};
+    if (direction === "fetch") {
+      remote.url = url;
+    } else {
+      remote.pushUrl = url;
+    }
+    remotes.set(name, remote);
+  }
+  return remotes;
+}
+
+const gitCommand = (
+  process: VcsProcess.VcsProcessShape,
+  operation: string,
+  cwd: string,
+  args: ReadonlyArray<string>,
+  options?: {
+    readonly stdin?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly allowNonZeroExit?: boolean;
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+    readonly appendTruncationMarker?: boolean;
+  },
+) =>
+  process.run({
+    operation,
+    command: "git",
+    args: ["-C", cwd, ...args],
+    cwd,
+    spawnCwd: globalThis.process.cwd(),
+    ...(options?.stdin !== undefined ? { stdin: options.stdin } : {}),
+    ...(options?.env !== undefined ? { env: options.env } : {}),
+    ...(options?.allowNonZeroExit !== undefined
+      ? { allowNonZeroExit: options.allowNonZeroExit }
+      : {}),
+    ...(options?.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    ...(options?.maxOutputBytes !== undefined ? { maxOutputBytes: options.maxOutputBytes } : {}),
+    ...(options?.appendTruncationMarker !== undefined
+      ? { appendTruncationMarker: options.appendTruncationMarker }
+      : {}),
+  });
+
+export const makeVcsDriverShape = Effect.fn("makeGitVcsDriverShape")(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const vcsProcess = yield* VcsProcess.VcsProcess;
+  const capabilities = {
+    kind: "git" as const,
+    supportsWorktrees: true,
+    supportsBookmarks: false,
+    supportsAtomicSnapshot: false,
+    supportsPushDefaultRemote: true,
+    ignoreClassifier: "native" as const,
+  };
+
+  const isInsideWorkTree: VcsDriver.VcsDriverShape["isInsideWorkTree"] = (cwd) =>
+    gitCommand(
+      vcsProcess,
+      "GitVcsDriver.isInsideWorkTree",
+      cwd,
+      ["rev-parse", "--is-inside-work-tree"],
+      {
+        allowNonZeroExit: true,
+        timeoutMs: 5_000,
+        maxOutputBytes: 4_096,
+      },
+    ).pipe(Effect.map((result) => result.exitCode === 0 && result.stdout.trim() === "true"));
+
+  const execute: VcsDriver.VcsDriverShape["execute"] = (input) =>
+    gitCommand(vcsProcess, input.operation, input.cwd, input.args, {
+      ...(input.stdin !== undefined ? { stdin: input.stdin } : {}),
+      ...(input.env !== undefined ? { env: input.env } : {}),
+      ...(input.allowNonZeroExit !== undefined ? { allowNonZeroExit: input.allowNonZeroExit } : {}),
+      ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+      ...(input.maxOutputBytes !== undefined ? { maxOutputBytes: input.maxOutputBytes } : {}),
+      ...(input.appendTruncationMarker !== undefined
+        ? { appendTruncationMarker: input.appendTruncationMarker }
+        : {}),
+    });
+
+  const detectRepository: VcsDriver.VcsDriverShape["detectRepository"] = Effect.fn(
+    "detectRepository",
+  )(function* (cwd) {
+    if (!(yield* isInsideWorkTree(cwd))) {
+      return null;
+    }
+
+    const root = yield* gitCommand(vcsProcess, "GitVcsDriver.detectRepository.root", cwd, [
+      "rev-parse",
+      "--show-toplevel",
+    ]);
+    const gitCommonDir = yield* gitCommand(
+      vcsProcess,
+      "GitVcsDriver.detectRepository.commonDir",
+      cwd,
+      ["rev-parse", "--git-common-dir"],
+    ).pipe(Effect.catch(() => Effect.succeed(null)));
+
+    return {
+      kind: "git" as const,
+      rootPath: root.stdout.trim(),
+      metadataPath: gitCommonDir?.stdout.trim() || null,
+      freshness: yield* nowFreshness(),
+    };
+  });
+
+  const listWorkspaceFiles: VcsDriver.VcsDriverShape["listWorkspaceFiles"] = (cwd) =>
+    gitCommand(
+      vcsProcess,
+      "GitVcsDriver.listWorkspaceFiles",
+      cwd,
+      [
+        ...WORKSPACE_GIT_HARDENED_CONFIG_ARGS,
+        "ls-files",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "-z",
+      ],
+      {
+        allowNonZeroExit: true,
+        timeoutMs: 20_000,
+        maxOutputBytes: WORKSPACE_FILES_MAX_OUTPUT_BYTES,
+        appendTruncationMarker: true,
+      },
+    ).pipe(
+      Effect.flatMap((result) =>
+        result.exitCode === 0
+          ? Effect.gen(function* () {
+              const freshness = yield* nowFreshness();
+              return {
+                paths: splitNullSeparatedPaths(result.stdout, result.stdoutTruncated),
+                truncated: result.stdoutTruncated,
+                freshness,
+              };
+            })
+          : Effect.fail(
+              new VcsProcessExitError({
+                operation: "GitVcsDriver.listWorkspaceFiles",
+                command: "git ls-files",
+                cwd,
+                exitCode: result.exitCode,
+                detail: result.stderr.trim() || "git ls-files failed",
+              }),
+            ),
+      ),
+    );
+
+  const listRemotes: VcsDriver.VcsDriverShape["listRemotes"] = Effect.fn("listRemotes")(
+    function* (cwd) {
+      const result = yield* gitCommand(
+        vcsProcess,
+        "GitVcsDriver.listRemotes",
+        cwd,
+        ["remote", "-v"],
+        {
+          allowNonZeroExit: true,
+          timeoutMs: 5_000,
+          maxOutputBytes: 64 * 1024,
+        },
+      );
+
+      if (result.exitCode !== 0) {
+        return yield* new VcsProcessExitError({
+          operation: "GitVcsDriver.listRemotes",
+          command: "git remote -v",
+          cwd,
+          exitCode: result.exitCode,
+          detail: result.stderr.trim() || "git remote -v failed",
+        });
+      }
+
+      const parsed = parseGitRemoteVerboseOutput(result.stdout);
+      const remotes = Array.from(parsed.entries()).flatMap(([name, remote]) => {
+        if (!remote.url) {
+          return [];
+        }
+        return [
+          {
+            name,
+            url: remote.url,
+            pushUrl: remote.pushUrl ? Option.some(remote.pushUrl) : Option.none(),
+            isPrimary: name === "origin",
+          },
+        ];
+      });
+
+      return {
+        remotes,
+        freshness: yield* nowFreshness(),
+      };
+    },
+  );
+
+  const filterIgnoredPaths: VcsDriver.VcsDriverShape["filterIgnoredPaths"] = Effect.fn(
+    "filterIgnoredPaths",
+  )(function* (cwd, relativePaths) {
+    if (relativePaths.length === 0) {
+      return relativePaths;
+    }
+
+    const ignoredPaths = new Set<string>();
+    const chunks = chunkPathsForGitCheckIgnore(relativePaths);
+
+    for (const chunk of chunks) {
+      const result = yield* gitCommand(
+        vcsProcess,
+        "GitVcsDriver.filterIgnoredPaths",
+        cwd,
+        [...WORKSPACE_GIT_HARDENED_CONFIG_ARGS, "check-ignore", "--no-index", "-z", "--stdin"],
+        {
+          stdin: `${chunk.join("\0")}\0`,
+          allowNonZeroExit: true,
+          timeoutMs: 20_000,
+          maxOutputBytes: WORKSPACE_FILES_MAX_OUTPUT_BYTES,
+          appendTruncationMarker: true,
+        },
+      );
+
+      if (result.exitCode !== 0 && result.exitCode !== 1) {
+        return yield* new VcsProcessExitError({
+          operation: "GitVcsDriver.filterIgnoredPaths",
+          command: "git check-ignore",
+          cwd,
+          exitCode: result.exitCode,
+          detail: result.stderr.trim() || "git check-ignore failed",
+        });
+      }
+
+      for (const ignoredPath of splitNullSeparatedPaths(result.stdout, result.stdoutTruncated)) {
+        ignoredPaths.add(ignoredPath);
+      }
+    }
+
+    if (ignoredPaths.size === 0) {
+      return relativePaths;
+    }
+
+    return relativePaths.filter((relativePath) => !ignoredPaths.has(relativePath));
+  });
+
+  const initRepository: VcsDriver.VcsDriverShape["initRepository"] = (input) =>
+    gitCommand(vcsProcess, "GitVcsDriver.initRepository", input.cwd, ["init"], {
+      timeoutMs: 10_000,
+      maxOutputBytes: 64 * 1024,
+    }).pipe(Effect.asVoid);
+
+  const resolveHeadCommit = (cwd: string) =>
+    execute({
+      operation: "GitVcsDriver.checkpoints.resolveHeadCommit",
+      cwd,
+      args: ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"],
+      allowNonZeroExit: true,
+    }).pipe(
+      Effect.map((result) => {
+        if (result.exitCode !== 0) {
+          return null;
+        }
+        const commit = result.stdout.trim();
+        return commit.length > 0 ? commit : null;
+      }),
+    );
+
+  const hasHeadCommit = (cwd: string) =>
+    execute({
+      operation: "GitVcsDriver.checkpoints.hasHeadCommit",
+      cwd,
+      args: ["rev-parse", "--verify", "HEAD"],
+      allowNonZeroExit: true,
+    }).pipe(Effect.map((result) => result.exitCode === 0));
+
+  const resolveCheckpointCommit = (cwd: string, checkpointRef: string) =>
+    execute({
+      operation: "GitVcsDriver.checkpoints.resolveCheckpointCommit",
+      cwd,
+      args: ["rev-parse", "--verify", "--quiet", `${checkpointRef}^{commit}`],
+      allowNonZeroExit: true,
+    }).pipe(
+      Effect.map((result) => {
+        if (result.exitCode !== 0) {
+          return null;
+        }
+        const commit = result.stdout.trim();
+        return commit.length > 0 ? commit : null;
+      }),
+    );
+
+  const resolveGitCommonDir = (cwd: string) =>
+    Effect.gen(function* () {
+      const result = yield* execute({
+        operation: "GitVcsDriver.checkpoints.resolveGitCommonDir",
+        cwd,
+        args: ["rev-parse", "--git-common-dir"],
+      });
+      const gitCommonDir = result.stdout.trim();
+      return path.isAbsolute(gitCommonDir) ? gitCommonDir : path.resolve(cwd, gitCommonDir);
+    });
+
+  const checkpoints: VcsDriver.VcsCheckpointOps = {
+    captureCheckpoint: Effect.fn("GitVcsDriver.checkpoints.captureCheckpoint")(function* (input) {
+      const operation = "GitVcsDriver.checkpoints.captureCheckpoint";
+      const gitCommonDir = yield* resolveGitCommonDir(input.cwd);
+      const tempIndexPath = path.join(gitCommonDir, `t3-checkpoint-index-${randomUUID()}`);
+      const commitEnv: NodeJS.ProcessEnv = {
+        ...process.env,
+        GIT_INDEX_FILE: tempIndexPath,
+        GIT_AUTHOR_NAME: "T3 Code",
+        GIT_AUTHOR_EMAIL: "t3code@users.noreply.github.com",
+        GIT_COMMITTER_NAME: "T3 Code",
+        GIT_COMMITTER_EMAIL: "t3code@users.noreply.github.com",
+      };
+
+      const cleanupTempIndex = fileSystem
+        .remove(tempIndexPath, { force: true })
+        .pipe(Effect.ignore);
+
+      yield* Effect.gen(function* () {
+        const headExists = yield* hasHeadCommit(input.cwd);
+        if (headExists) {
+          yield* execute({
+            operation,
+            cwd: input.cwd,
+            args: ["read-tree", "HEAD"],
+            env: commitEnv,
+          });
+        }
+
+        yield* execute({
+          operation,
+          cwd: input.cwd,
+          args: ["add", "-A", "--", "."],
+          env: commitEnv,
+        });
+
+        const writeTreeResult = yield* execute({
+          operation,
+          cwd: input.cwd,
+          args: ["write-tree"],
+          env: commitEnv,
+        });
+        const treeOid = writeTreeResult.stdout.trim();
+        if (treeOid.length === 0) {
+          return yield* new VcsProcessExitError({
+            operation,
+            command: "git write-tree",
+            cwd: input.cwd,
+            exitCode: 0,
+            detail: "git write-tree returned an empty tree oid.",
+          });
+        }
+
+        const message = `t3 checkpoint ref=${input.checkpointRef}`;
+        const commitTreeResult = yield* execute({
+          operation,
+          cwd: input.cwd,
+          args: ["commit-tree", treeOid, "-m", message],
+          env: commitEnv,
+        });
+        const commitOid = commitTreeResult.stdout.trim();
+        if (commitOid.length === 0) {
+          return yield* new VcsProcessExitError({
+            operation,
+            command: "git commit-tree",
+            cwd: input.cwd,
+            exitCode: 0,
+            detail: "git commit-tree returned an empty commit oid.",
+          });
+        }
+
+        yield* execute({
+          operation,
+          cwd: input.cwd,
+          args: ["update-ref", input.checkpointRef, commitOid],
+        });
+      }).pipe(Effect.ensuring(cleanupTempIndex));
+    }),
+
+    hasCheckpointRef: (input) =>
+      resolveCheckpointCommit(input.cwd, input.checkpointRef).pipe(
+        Effect.map((commit) => commit !== null),
+      ),
+
+    restoreCheckpoint: Effect.fn("GitVcsDriver.checkpoints.restoreCheckpoint")(function* (input) {
+      const operation = "GitVcsDriver.checkpoints.restoreCheckpoint";
+
+      let commitOid = yield* resolveCheckpointCommit(input.cwd, input.checkpointRef);
+
+      if (!commitOid && input.fallbackToHead === true) {
+        commitOid = yield* resolveHeadCommit(input.cwd);
+      }
+
+      if (!commitOid) {
+        return false;
+      }
+
+      yield* execute({
+        operation,
+        cwd: input.cwd,
+        args: ["restore", "--source", commitOid, "--worktree", "--staged", "--", "."],
+      });
+      yield* execute({
+        operation,
+        cwd: input.cwd,
+        args: ["clean", "-fd", "--", "."],
+      });
+
+      const headExists = yield* hasHeadCommit(input.cwd);
+      if (headExists) {
+        yield* execute({
+          operation,
+          cwd: input.cwd,
+          args: ["reset", "--quiet", "--", "."],
+        });
+      }
+
+      return true;
+    }),
+
+    diffCheckpoints: Effect.fn("GitVcsDriver.checkpoints.diffCheckpoints")(function* (input) {
+      const operation = "GitVcsDriver.checkpoints.diffCheckpoints";
+      yield* Effect.annotateCurrentSpan({
+        "checkpoint.cwd": input.cwd,
+        "checkpoint.from_ref": input.fromCheckpointRef,
+        "checkpoint.to_ref": input.toCheckpointRef,
+        "checkpoint.ignore_whitespace": input.ignoreWhitespace,
+        "checkpoint.fallback_from_to_head": input.fallbackFromToHead,
+      });
+
+      let fromRevision: string = input.fromCheckpointRef;
+      if (input.fallbackFromToHead === true) {
+        const resolvedFromCommit = yield* resolveCheckpointCommit(
+          input.cwd,
+          input.fromCheckpointRef,
+        );
+        if (resolvedFromCommit) {
+          fromRevision = resolvedFromCommit;
+        } else {
+          const headCommit = yield* resolveHeadCommit(input.cwd);
+          if (!headCommit) {
+            return yield* new VcsProcessExitError({
+              operation,
+              command: "git diff",
+              cwd: input.cwd,
+              exitCode: 1,
+              detail: "Checkpoint ref is unavailable for diff operation.",
+            });
+          }
+          fromRevision = headCommit;
+        }
+      }
+
+      const result = yield* execute({
+        operation,
+        cwd: input.cwd,
+        args: [
+          "diff",
+          "--patch",
+          "--no-color",
+          "--no-ext-diff",
+          "--no-textconv",
+          ...(input.ignoreWhitespace ? ["--ignore-all-space"] : []),
+          `${fromRevision}^{commit}`,
+          `${input.toCheckpointRef}^{commit}`,
+        ],
+        allowNonZeroExit: true,
+        maxOutputBytes: CHECKPOINT_DIFF_MAX_OUTPUT_BYTES,
+      });
+
+      if (result.exitCode !== 0) {
+        return yield* new VcsProcessExitError({
+          operation,
+          command: "git diff",
+          cwd: input.cwd,
+          exitCode: result.exitCode,
+          detail: result.stderr.trim() || "Checkpoint ref is unavailable for diff operation.",
+        });
+      }
+
+      return result.stdout;
+    }),
+
+    deleteCheckpointRefs: Effect.fn("GitVcsDriver.checkpoints.deleteCheckpointRefs")(
+      function* (input) {
+        yield* Effect.forEach(
+          input.checkpointRefs,
+          (checkpointRef) =>
+            execute({
+              operation: "GitVcsDriver.checkpoints.deleteCheckpointRefs",
+              cwd: input.cwd,
+              args: ["update-ref", "-d", checkpointRef],
+              allowNonZeroExit: true,
+            }),
+          { discard: true },
+        );
+      },
+    ),
+  };
+
+  return VcsDriver.VcsDriver.of({
+    capabilities,
+    execute,
+    checkpoints,
+    detectRepository,
+    isInsideWorkTree,
+    listWorkspaceFiles,
+    listRemotes,
+    filterIgnoredPaths,
+    initRepository,
+  });
+});
+
+export const makeVcsDriver = Effect.fn("makeGitVcsDriver")(function* () {
+  const driver = yield* makeVcsDriverShape();
+  return VcsDriver.VcsDriver.of(driver);
+});
+
+export const make = Effect.fn("makeGitVcsDriverService")(function* () {
+  const git = yield* GitVcsDriverCore.makeGitVcsDriverCore();
+  return GitVcsDriver.of(git);
+});
+
+export const vcsLayer = Layer.effect(VcsDriver.VcsDriver, makeVcsDriver());
+export const layer = Layer.effect(GitVcsDriver, make());
diff --git a/apps/server/src/vcs/GitVcsDriverCore.test.ts b/apps/server/src/vcs/GitVcsDriverCore.test.ts
new file mode 100644
index 00000000000..00f40a69aa7
--- /dev/null
+++ b/apps/server/src/vcs/GitVcsDriverCore.test.ts
@@ -0,0 +1,429 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it, describe } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Scope from "effect/Scope";
+
+import { GitCommandError } from "@t3tools/contracts";
+import { ServerConfig } from "../config.ts";
+import * as GitVcsDriver from "./GitVcsDriver.ts";
+
+const ServerConfigLayer = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3-git-vcs-driver-test-",
+});
+const TestLayer = GitVcsDriver.layer.pipe(
+  Layer.provide(ServerConfigLayer),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+const makeTmpDir = (
+  prefix = "git-vcs-driver-test-",
+): Effect.Effect<string, PlatformError.PlatformError, FileSystem.FileSystem | Scope.Scope> =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    return yield* fileSystem.makeTempDirectoryScoped({ prefix });
+  });
+
+const writeTextFile = (
+  cwd: string,
+  relativePath: string,
+  contents: string,
+): Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const pathService = yield* Path.Path;
+    const filePath = pathService.join(cwd, relativePath);
+    yield* fileSystem.makeDirectory(pathService.dirname(filePath), { recursive: true });
+    yield* fileSystem.writeFileString(filePath, contents);
+  });
+
+const git = (
+  cwd: string,
+  args: ReadonlyArray<string>,
+  env?: NodeJS.ProcessEnv,
+): Effect.Effect<string, GitCommandError, GitVcsDriver.GitVcsDriver> =>
+  Effect.gen(function* () {
+    const driver = yield* GitVcsDriver.GitVcsDriver;
+    const result = yield* driver.execute({
+      operation: "GitVcsDriver.test.git",
+      cwd,
+      args,
+      ...(env ? { env } : {}),
+      timeoutMs: 10_000,
+    });
+    return result.stdout.trim();
+  });
+
+const initRepoWithCommit = (
+  cwd: string,
+): Effect.Effect<
+  { readonly initialBranch: string },
+  GitCommandError | PlatformError.PlatformError,
+  GitVcsDriver.GitVcsDriver | FileSystem.FileSystem | Path.Path
+> =>
+  Effect.gen(function* () {
+    const driver = yield* GitVcsDriver.GitVcsDriver;
+    yield* driver.initRepo({ cwd });
+    yield* git(cwd, ["config", "user.email", "test@test.com"]);
+    yield* git(cwd, ["config", "user.name", "Test"]);
+    yield* writeTextFile(cwd, "README.md", "# test\n");
+    yield* git(cwd, ["add", "."]);
+    yield* git(cwd, ["commit", "-m", "initial commit"]);
+    const initialBranch = yield* git(cwd, ["branch", "--show-current"]);
+    return { initialBranch };
+  });
+
+it.layer(TestLayer)("GitVcsDriver core integration", (it) => {
+  describe("repository status", () => {
+    it.effect("reports non-repository directories without failing", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        const refs = yield* driver.listRefs({ cwd });
+        assert.equal(refs.isRepo, false);
+        assert.deepStrictEqual(refs.refs, []);
+      }),
+    );
+
+    it.effect("reports refName and dirty state for a repository", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        yield* writeTextFile(cwd, "feature.ts", "export const value = 1;\n");
+
+        const status = yield* (yield* GitVcsDriver.GitVcsDriver).statusDetails(cwd);
+
+        assert.equal(status.isRepo, true);
+        assert.equal(status.branch, initialBranch);
+        assert.equal(status.hasWorkingTreeChanges, true);
+        assert.include(
+          status.workingTree.files.map((file) => file.path),
+          "feature.ts",
+        );
+      }),
+    );
+
+    it.effect("reports default-branch delta separately from upstream delta", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const remote = yield* makeTmpDir("git-vcs-driver-remote-");
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        yield* git(remote, ["init", "--bare"]);
+        yield* git(cwd, ["remote", "add", "origin", remote]);
+        yield* git(cwd, ["push", "-u", "origin", initialBranch]);
+        yield* git(cwd, ["checkout", "-b", "feature/synced"]);
+        yield* writeTextFile(cwd, "feature.txt", "feature\n");
+        yield* git(cwd, ["add", "feature.txt"]);
+        yield* git(cwd, ["commit", "-m", "feature commit"]);
+        yield* git(cwd, ["push", "-u", "origin", "feature/synced"]);
+
+        const status = yield* (yield* GitVcsDriver.GitVcsDriver).statusDetails(cwd);
+
+        assert.equal(status.hasUpstream, true);
+        assert.equal(status.aheadCount, 0);
+        assert.equal(status.behindCount, 0);
+        assert.equal(status.aheadOfDefaultCount, 1);
+      }),
+    );
+
+    it.effect("disables SSH askpass for background upstream status fetches", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const tempDir = yield* makeTmpDir("git-vcs-driver-ssh-env-");
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        const fileSystem = yield* FileSystem.FileSystem;
+        const pathService = yield* Path.Path;
+        const sshLogPath = pathService.join(tempDir, "ssh-env.txt");
+        const sshWrapperPath = pathService.join(tempDir, "ssh-wrapper.sh");
+        const previousGitSsh = process.env.GIT_SSH;
+        const previousAskpassRequire = process.env.SSH_ASKPASS_REQUIRE;
+        const previousAskpassLog = process.env.T3_TEST_SSH_ASKPASS_LOG;
+
+        yield* fileSystem.writeFileString(
+          sshWrapperPath,
+          [
+            "#!/bin/sh",
+            'printf "%s\\n" "${SSH_ASKPASS_REQUIRE:-}" > "$T3_TEST_SSH_ASKPASS_LOG"',
+            "exit 1",
+            "",
+          ].join("\n"),
+        );
+        yield* fileSystem.chmod(sshWrapperPath, 0o755);
+        yield* git(cwd, ["remote", "add", "origin", "ssh://example.invalid/repo.git"]);
+        yield* git(cwd, ["update-ref", `refs/remotes/origin/${initialBranch}`, "HEAD"]);
+        yield* git(cwd, ["branch", "--set-upstream-to", `origin/${initialBranch}`]);
+
+        yield* Effect.gen(function* () {
+          process.env.GIT_SSH = sshWrapperPath;
+          process.env.SSH_ASKPASS_REQUIRE = "force";
+          process.env.T3_TEST_SSH_ASKPASS_LOG = sshLogPath;
+
+          yield* (yield* GitVcsDriver.GitVcsDriver).statusDetails(cwd);
+
+          assert.equal((yield* fileSystem.readFileString(sshLogPath)).trim(), "never");
+        }).pipe(
+          Effect.ensuring(
+            Effect.sync(() => {
+              if (previousGitSsh === undefined) {
+                delete process.env.GIT_SSH;
+              } else {
+                process.env.GIT_SSH = previousGitSsh;
+              }
+              if (previousAskpassRequire === undefined) {
+                delete process.env.SSH_ASKPASS_REQUIRE;
+              } else {
+                process.env.SSH_ASKPASS_REQUIRE = previousAskpassRequire;
+              }
+              if (previousAskpassLog === undefined) {
+                delete process.env.T3_TEST_SSH_ASKPASS_LOG;
+              } else {
+                process.env.T3_TEST_SSH_ASKPASS_LOG = previousAskpassLog;
+              }
+            }),
+          ),
+        );
+      }),
+    );
+
+    it.effect("reuses the no-upstream fallback ahead count for default-branch delta", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const remote = yield* makeTmpDir("git-vcs-driver-remote-");
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        yield* git(remote, ["init", "--bare"]);
+        yield* git(cwd, ["remote", "add", "origin", remote]);
+        yield* git(cwd, ["push", "-u", "origin", initialBranch]);
+        yield* git(cwd, ["checkout", "-b", "feature/no-upstream"]);
+        yield* writeTextFile(cwd, "feature.txt", "feature\n");
+        yield* git(cwd, ["add", "feature.txt"]);
+        yield* git(cwd, ["commit", "-m", "feature commit"]);
+
+        const status = yield* (yield* GitVcsDriver.GitVcsDriver).statusDetails(cwd);
+
+        assert.equal(status.hasUpstream, false);
+        assert.equal(status.aheadCount, 1);
+        assert.equal(status.behindCount, 0);
+        assert.equal(status.aheadOfDefaultCount, 1);
+      }),
+    );
+  });
+
+  describe("refName operations", () => {
+    it.effect("creates, checks out, renames, and lists refs", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        yield* driver.createRef({ cwd, refName: "feature/original" });
+        const switchRef = yield* driver.switchRef({ cwd, refName: "feature/original" });
+        assert.equal(switchRef.refName, "feature/original");
+
+        const renamed = yield* driver.renameBranch({
+          cwd,
+          oldBranch: "feature/original",
+          newBranch: "feature/renamed",
+        });
+        assert.equal(renamed.branch, "feature/renamed");
+        assert.equal(yield* git(cwd, ["branch", "--show-current"]), "feature/renamed");
+
+        const refs = yield* driver.listRefs({ cwd });
+        assert.equal(
+          refs.refs.find((refName) => refName.name === "feature/renamed")?.current,
+          true,
+        );
+      }),
+    );
+
+    it.effect("returns the existing refName when rename source and target match", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        const current = yield* git(cwd, ["branch", "--show-current"]);
+        const result = yield* driver.renameBranch({
+          cwd,
+          oldBranch: current,
+          newBranch: current,
+        });
+
+        assert.equal(result.branch, current);
+      }),
+    );
+  });
+
+  describe("worktree operations", () => {
+    it.effect("creates and removes a worktree for a new refName", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        const pathService = yield* Path.Path;
+        const worktreePath = pathService.join(
+          yield* makeTmpDir("git-worktrees-"),
+          "feature-worktree",
+        );
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        const created = yield* driver.createWorktree({
+          cwd,
+          path: worktreePath,
+          refName: initialBranch,
+          newRefName: "feature/worktree",
+        });
+
+        assert.equal(created.worktree.path, worktreePath);
+        assert.equal(created.worktree.refName, "feature/worktree");
+        assert.equal(yield* git(worktreePath, ["branch", "--show-current"]), "feature/worktree");
+
+        yield* driver.removeWorktree({ cwd, path: worktreePath });
+        const fileSystem = yield* FileSystem.FileSystem;
+        assert.equal(yield* fileSystem.exists(worktreePath), false);
+      }),
+    );
+  });
+
+  describe("commit context", () => {
+    it.effect("stages selected files and commits only those files", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        yield* writeTextFile(cwd, "a.txt", "a\n");
+        yield* writeTextFile(cwd, "b.txt", "b\n");
+
+        const context = yield* driver.prepareCommitContext(cwd, ["a.txt"]);
+        assert.include(context?.stagedSummary ?? "", "a.txt");
+        assert.notInclude(context?.stagedSummary ?? "", "b.txt");
+
+        const commit = yield* driver.commit(cwd, "Add a", "");
+        assert.match(commit.commitSha, /^[a-f0-9]{40}$/);
+        assert.equal(yield* git(cwd, ["log", "-1", "--pretty=%s"]), "Add a");
+
+        const status = yield* git(cwd, ["status", "--porcelain"]);
+        assert.include(status, "?? b.txt");
+        assert.notInclude(status, "a.txt");
+      }),
+    );
+  });
+
+  describe("remote operations", () => {
+    it.effect("pushes with upstream setup and skips when already up to date", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const remote = yield* makeTmpDir("git-remote-");
+        yield* initRepoWithCommit(cwd);
+        yield* git(remote, ["init", "--bare"]);
+        yield* git(cwd, ["remote", "add", "origin", remote]);
+        yield* (yield* GitVcsDriver.GitVcsDriver).createRef({
+          cwd,
+          refName: "feature/push",
+        });
+        yield* (yield* GitVcsDriver.GitVcsDriver).switchRef({
+          cwd,
+          refName: "feature/push",
+        });
+        yield* writeTextFile(cwd, "feature.txt", "feature\n");
+        yield* (yield* GitVcsDriver.GitVcsDriver).prepareCommitContext(cwd);
+        yield* (yield* GitVcsDriver.GitVcsDriver).commit(cwd, "Add feature", "");
+
+        const pushed = yield* (yield* GitVcsDriver.GitVcsDriver).pushCurrentBranch(cwd, null);
+        assert.deepInclude(pushed, {
+          status: "pushed",
+          branch: "feature/push",
+          setUpstream: true,
+        });
+        assert.equal(
+          yield* git(cwd, ["rev-parse", "--abbrev-ref", "@{upstream}"]),
+          "origin/feature/push",
+        );
+
+        const skipped = yield* (yield* GitVcsDriver.GitVcsDriver).pushCurrentBranch(cwd, null);
+        assert.deepInclude(skipped, {
+          status: "skipped_up_to_date",
+          branch: "feature/push",
+        });
+      }),
+    );
+
+    it.effect(
+      "pushes upstream branches to the remote branch name, not the upstream shorthand",
+      () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          const remote = yield* makeTmpDir("git-remote-");
+          yield* initRepoWithCommit(cwd);
+          const driver = yield* GitVcsDriver.GitVcsDriver;
+          yield* git(cwd, ["branch", "-M", "main"]);
+          yield* git(remote, ["init", "--bare"]);
+          yield* git(cwd, ["remote", "add", "origin", remote]);
+          yield* git(cwd, ["push", "-u", "origin", "main"]);
+          yield* writeTextFile(cwd, "upstream.txt", "upstream\n");
+          yield* driver.prepareCommitContext(cwd);
+          yield* driver.commit(cwd, "Add upstream update", "");
+
+          const pushed = yield* driver.pushCurrentBranch(cwd, null);
+
+          assert.deepInclude(pushed, {
+            status: "pushed",
+            branch: "main",
+            upstreamBranch: "origin/main",
+            setUpstream: false,
+          });
+          assert.equal(
+            yield* git(remote, ["log", "-1", "--pretty=%s", "main"]),
+            "Add upstream update",
+          );
+          const badBranch = yield* driver.execute({
+            operation: "GitVcsDriver.test.showBadRemoteBranch",
+            cwd: remote,
+            args: ["show-ref", "--verify", "--quiet", "refs/heads/origin/main"],
+            allowNonZeroExit: true,
+            timeoutMs: 10_000,
+          });
+          assert.notEqual(badBranch.exitCode, 0);
+        }),
+    );
+
+    it.effect("pushes to the requested remote instead of the primary remote", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const originRemote = yield* makeTmpDir("git-origin-remote-");
+        const publishRemote = yield* makeTmpDir("git-publish-remote-");
+        yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+        yield* git(cwd, ["branch", "-M", "main"]);
+        yield* git(originRemote, ["init", "--bare"]);
+        yield* git(publishRemote, ["init", "--bare"]);
+        yield* git(cwd, ["remote", "add", "origin", originRemote]);
+        yield* git(cwd, ["remote", "add", "origin-1", publishRemote]);
+
+        const pushed = yield* driver.pushCurrentBranch(cwd, null, { remoteName: "origin-1" });
+
+        assert.deepInclude(pushed, {
+          status: "pushed",
+          branch: "main",
+          upstreamBranch: "origin-1/main",
+          setUpstream: true,
+        });
+        assert.equal(
+          yield* git(publishRemote, ["log", "-1", "--pretty=%s", "main"]),
+          "initial commit",
+        );
+        const originMain = yield* driver.execute({
+          operation: "GitVcsDriver.test.originMainMissing",
+          cwd: originRemote,
+          args: ["show-ref", "--verify", "--quiet", "refs/heads/main"],
+          allowNonZeroExit: true,
+          timeoutMs: 10_000,
+        });
+        assert.notEqual(originMain.exitCode, 0);
+      }),
+    );
+  });
+});
diff --git a/apps/server/src/git/Layers/GitCore.ts b/apps/server/src/vcs/GitVcsDriverCore.ts
similarity index 57%
rename from apps/server/src/git/Layers/GitCore.ts
rename to apps/server/src/vcs/GitVcsDriverCore.ts
index 3e9df316f1e..19f12862dad 100644
--- a/apps/server/src/git/Layers/GitCore.ts
+++ b/apps/server/src/vcs/GitVcsDriverCore.ts
@@ -1,43 +1,34 @@
-import {
-  Cache,
-  Data,
-  Duration,
-  Effect,
-  Exit,
-  FileSystem,
-  Layer,
-  Option,
-  Path,
-  PlatformError,
-  Ref,
-  Result,
-  Schema,
-  Scope,
-  Semaphore,
-  Stream,
-} from "effect";
+import * as Cache from "effect/Cache";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
-import { GitCommandError, type GitBranch } from "@t3tools/contracts";
+import { GitCommandError, type VcsRef } from "@t3tools/contracts";
 import { dedupeRemoteBranchesWithLocalMatches } from "@t3tools/shared/git";
-import { compactTraceAttributes } from "../../observability/Attributes.ts";
-import { gitCommandDuration, gitCommandsTotal, withMetrics } from "../../observability/Metrics.ts";
-import {
-  GitCore,
-  type ExecuteGitProgress,
-  type GitCommitOptions,
-  type GitCoreShape,
-  type GitStatusDetails,
-  type ExecuteGitInput,
-  type ExecuteGitResult,
-} from "../Services/GitCore.ts";
+import { compactTraceAttributes } from "@t3tools/shared/observability";
+import { decodeJsonResult } from "@t3tools/shared/schemaJson";
+import { gitCommandDuration, gitCommandsTotal, withMetrics } from "../observability/Metrics.ts";
+import * as GitVcsDriver from "./GitVcsDriver.ts";
 import {
   parseRemoteNames,
   parseRemoteNamesInGitOrder,
   parseRemoteRefWithRemoteNames,
-} from "../remoteRefs.ts";
-import { ServerConfig } from "../../config.ts";
-import { decodeJsonResult } from "@t3tools/shared/schemaJson";
+} from "../git/remoteRefs.ts";
+import { ServerConfig } from "../config.ts";
+const isGitCommandError = Schema.is(GitCommandError);
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
@@ -46,21 +37,16 @@ const PREPARED_COMMIT_PATCH_MAX_OUTPUT_BYTES = 49_000;
 const RANGE_COMMIT_SUMMARY_MAX_OUTPUT_BYTES = 19_000;
 const RANGE_DIFF_SUMMARY_MAX_OUTPUT_BYTES = 19_000;
 const RANGE_DIFF_PATCH_MAX_OUTPUT_BYTES = 59_000;
-const WORKSPACE_FILES_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
-const GIT_CHECK_IGNORE_MAX_STDIN_BYTES = 256 * 1024;
-const WORKSPACE_GIT_HARDENED_CONFIG_ARGS = [
-  "-c",
-  "core.fsmonitor=false",
-  "-c",
-  "core.untrackedCache=false",
-] as const;
 const STATUS_UPSTREAM_REFRESH_INTERVAL = Duration.seconds(15);
 const STATUS_UPSTREAM_REFRESH_TIMEOUT = Duration.seconds(5);
 const STATUS_UPSTREAM_REFRESH_FAILURE_COOLDOWN = Duration.seconds(5);
 const STATUS_UPSTREAM_REFRESH_CACHE_CAPACITY = 2_048;
+const STATUS_UPSTREAM_REFRESH_ENV = Object.freeze({
+  SSH_ASKPASS_REQUIRE: "never",
+} satisfies NodeJS.ProcessEnv);
 const DEFAULT_BASE_BRANCH_CANDIDATES = ["main", "master"] as const;
 const GIT_LIST_BRANCHES_DEFAULT_LIMIT = 100;
-const NON_REPOSITORY_STATUS_DETAILS = Object.freeze<GitStatusDetails>({
+const NON_REPOSITORY_STATUS_DETAILS = Object.freeze<GitVcsDriver.GitStatusDetails>({
   isRepo: false,
   hasOriginRemote: false,
   isDefaultBranch: false,
@@ -71,6 +57,7 @@ const NON_REPOSITORY_STATUS_DETAILS = Object.freeze<GitStatusDetails>({
   hasUpstream: false,
   aheadCount: 0,
   behindCount: 0,
+  aheadOfDefaultCount: 0,
 });
 
 type TraceTailState = {
@@ -88,9 +75,10 @@ interface ExecuteGitOptions {
   timeoutMs?: number | undefined;
   allowNonZeroExit?: boolean | undefined;
   fallbackErrorMessage?: string | undefined;
+  env?: NodeJS.ProcessEnv | undefined;
   maxOutputBytes?: number | undefined;
-  truncateOutputAtMaxBytes?: boolean | undefined;
-  progress?: ExecuteGitProgress | undefined;
+  appendTruncationMarker?: boolean | undefined;
+  progress?: GitVcsDriver.ExecuteGitProgress | undefined;
 }
 
 function parseBranchAb(value: string): { ahead: number; behind: number } {
@@ -126,47 +114,6 @@ function parseNumstatEntries(
   return entries;
 }
 
-function splitNullSeparatedPaths(input: string, truncated: boolean): string[] {
-  const parts = input.split("\0");
-  if (parts.length === 0) return [];
-
-  if (truncated && parts[parts.length - 1]?.length) {
-    parts.pop();
-  }
-
-  return parts.filter((value) => value.length > 0);
-}
-
-function chunkPathsForGitCheckIgnore(relativePaths: readonly string[]): string[][] {
-  const chunks: string[][] = [];
-  let chunk: string[] = [];
-  let chunkBytes = 0;
-
-  for (const relativePath of relativePaths) {
-    const relativePathBytes = Buffer.byteLength(relativePath) + 1;
-    if (chunk.length > 0 && chunkBytes + relativePathBytes > GIT_CHECK_IGNORE_MAX_STDIN_BYTES) {
-      chunks.push(chunk);
-      chunk = [];
-      chunkBytes = 0;
-    }
-
-    chunk.push(relativePath);
-    chunkBytes += relativePathBytes;
-
-    if (chunkBytes >= GIT_CHECK_IGNORE_MAX_STDIN_BYTES) {
-      chunks.push(chunk);
-      chunk = [];
-      chunkBytes = 0;
-    }
-  }
-
-  if (chunk.length > 0) {
-    chunks.push(chunk);
-  }
-
-  return chunks;
-}
-
 function parsePorcelainPath(line: string): string | null {
   if (line.startsWith("? ") || line.startsWith("! ")) {
     const simple = line.slice(2).trim();
@@ -205,34 +152,34 @@ function parseBranchLine(line: string): { name: string; current: boolean } | nul
 }
 
 function filterBranchesForListQuery(
-  branches: ReadonlyArray<GitBranch>,
+  refs: ReadonlyArray<VcsRef>,
   query?: string,
-): ReadonlyArray<GitBranch> {
+): ReadonlyArray<VcsRef> {
   if (!query) {
-    return branches;
+    return refs;
   }
 
   const normalizedQuery = query.toLowerCase();
-  return branches.filter((branch) => branch.name.toLowerCase().includes(normalizedQuery));
+  return refs.filter((refName) => refName.name.toLowerCase().includes(normalizedQuery));
 }
 
 function paginateBranches(input: {
-  branches: ReadonlyArray<GitBranch>;
+  refs: ReadonlyArray<VcsRef>;
   cursor?: number | undefined;
   limit?: number | undefined;
 }): {
-  branches: ReadonlyArray<GitBranch>;
+  refs: ReadonlyArray<VcsRef>;
   nextCursor: number | null;
   totalCount: number;
 } {
   const cursor = input.cursor ?? 0;
   const limit = input.limit ?? GIT_LIST_BRANCHES_DEFAULT_LIMIT;
-  const totalCount = input.branches.length;
-  const branches = input.branches.slice(cursor, cursor + limit);
-  const nextCursor = cursor + branches.length < totalCount ? cursor + branches.length : null;
+  const totalCount = input.refs.length;
+  const refs = input.refs.slice(cursor, cursor + limit);
+  const nextCursor = cursor + refs.length < totalCount ? cursor + refs.length : null;
 
   return {
-    branches,
+    refs,
     nextCursor,
     totalCount,
   };
@@ -273,7 +220,7 @@ function parseRemoteFetchUrls(stdout: string): Map<string, string> {
 function parseUpstreamRefWithRemoteNames(
   upstreamRef: string,
   remoteNames: ReadonlyArray<string>,
-): { upstreamRef: string; remoteName: string; upstreamBranch: string } | null {
+): { upstreamRef: string; remoteName: string; branchName: string } | null {
   const parsed = parseRemoteRefWithRemoteNames(upstreamRef, remoteNames);
   if (!parsed) {
     return null;
@@ -282,28 +229,28 @@ function parseUpstreamRefWithRemoteNames(
   return {
     upstreamRef,
     remoteName: parsed.remoteName,
-    upstreamBranch: parsed.branchName,
+    branchName: parsed.branchName,
   };
 }
 
 function parseUpstreamRefByFirstSeparator(
   upstreamRef: string,
-): { upstreamRef: string; remoteName: string; upstreamBranch: string } | null {
+): { upstreamRef: string; remoteName: string; branchName: string } | null {
   const separatorIndex = upstreamRef.indexOf("/");
   if (separatorIndex <= 0 || separatorIndex === upstreamRef.length - 1) {
     return null;
   }
 
   const remoteName = upstreamRef.slice(0, separatorIndex).trim();
-  const upstreamBranch = upstreamRef.slice(separatorIndex + 1).trim();
-  if (remoteName.length === 0 || upstreamBranch.length === 0) {
+  const branchName = upstreamRef.slice(separatorIndex + 1).trim();
+  if (remoteName.length === 0 || branchName.length === 0) {
     return null;
   }
 
   return {
     upstreamRef,
     remoteName,
-    upstreamBranch,
+    branchName,
   };
 }
 
@@ -315,11 +262,11 @@ function parseTrackingBranchByUpstreamRef(stdout: string, upstreamRef: string):
     }
     const [branchNameRaw, upstreamBranchRaw = ""] = trimmedLine.split("\t");
     const branchName = branchNameRaw?.trim() ?? "";
-    const upstreamBranch = upstreamBranchRaw.trim();
-    if (branchName.length === 0 || upstreamBranch.length === 0) {
+    const candidateUpstreamRef = upstreamBranchRaw.trim();
+    if (branchName.length === 0 || candidateUpstreamRef.length === 0) {
       continue;
     }
-    if (upstreamBranch === upstreamRef) {
+    if (candidateUpstreamRef === upstreamRef) {
       return branchName;
     }
   }
@@ -346,8 +293,8 @@ function parseDefaultBranchFromRemoteHeadRef(value: string, remoteName: string):
   if (!trimmed.startsWith(prefix)) {
     return null;
   }
-  const branch = trimmed.slice(prefix.length).trim();
-  return branch.length > 0 ? branch : null;
+  const refName = trimmed.slice(prefix.length).trim();
+  return refName.length > 0 ? refName : null;
 }
 
 function createGitCommandError(
@@ -381,11 +328,11 @@ function isMissingGitCwdError(error: GitCommandError): boolean {
 }
 
 function toGitCommandError(
-  input: Pick<ExecuteGitInput, "operation" | "cwd" | "args">,
+  input: Pick<GitVcsDriver.ExecuteGitInput, "operation" | "cwd" | "args">,
   detail: string,
 ) {
   return (cause: unknown) =>
-    Schema.is(GitCommandError)(cause)
+    isGitCommandError(cause)
       ? cause
       : new GitCommandError({
           operation: input.operation,
@@ -401,17 +348,18 @@ interface Trace2Monitor {
   readonly flush: Effect.Effect<void, never>;
 }
 
-const nowUnixNano = (): bigint => BigInt(Date.now()) * 1_000_000n;
+const nowUnixNano = DateTime.now.pipe(
+  Effect.map((now) => BigInt(DateTime.toEpochMillis(now)) * 1_000_000n),
+);
 
 const addCurrentSpanEvent = (name: string, attributes: Record<string, unknown>) =>
-  Effect.currentSpan.pipe(
-    Effect.tap((span) =>
-      Effect.sync(() => {
-        span.event(name, nowUnixNano(), compactTraceAttributes(attributes));
-      }),
-    ),
-    Effect.catch(() => Effect.void),
-  );
+  Effect.gen(function* () {
+    const span = yield* Effect.currentSpan;
+    const timestamp = yield* nowUnixNano;
+    yield* Effect.sync(() => {
+      span.event(name, timestamp, compactTraceAttributes(attributes));
+    });
+  }).pipe(Effect.catch(() => Effect.void));
 
 function trace2ChildKey(record: Record<string, unknown>): string | null {
   const childId = record.child_id;
@@ -425,8 +373,8 @@ function trace2ChildKey(record: Record<string, unknown>): string | null {
 const Trace2Record = Schema.Record(Schema.String, Schema.Unknown);
 
 const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
-  input: Pick<ExecuteGitInput, "operation" | "cwd" | "args">,
-  progress: ExecuteGitProgress | undefined,
+  input: Pick<GitVcsDriver.ExecuteGitInput, "operation" | "cwd" | "args">,
+  progress: GitVcsDriver.ExecuteGitProgress | undefined,
 ): Effect.fn.Return<
   Trace2Monitor,
   PlatformError.PlatformError,
@@ -460,7 +408,7 @@ const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
     const traceRecord = decodeJsonResult(Trace2Record)(trimmedLine);
     if (Result.isFailure(traceRecord)) {
       yield* Effect.logDebug(
-        `GitCore.trace2: failed to parse trace line for ${quoteGitCommand(input.args)} in ${input.cwd}`,
+        `GitVcsDriver.trace2: failed to parse trace line for ${quoteGitCommand(input.args)} in ${input.cwd}`,
         traceRecord.failure,
       );
       return;
@@ -484,7 +432,8 @@ const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
     }
 
     if (event === "child_start") {
-      hookStartByChildKey.set(childKey, { hookName, startedAtMs: Date.now() });
+      const now = yield* DateTime.now;
+      hookStartByChildKey.set(childKey, { hookName, startedAtMs: DateTime.toEpochMillis(now) });
       yield* addCurrentSpanEvent("git.hook.started", {
         hookName,
       });
@@ -496,9 +445,12 @@ const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
 
     if (event === "child_exit") {
       hookStartByChildKey.delete(childKey);
-      const code = traceRecord.success.code;
+      const code = traceRecord.success.exitCode;
       const exitCode = typeof code === "number" && Number.isInteger(code) ? code : null;
-      const durationMs = started ? Math.max(0, Date.now() - started.startedAtMs) : null;
+      const now = yield* DateTime.now;
+      const durationMs = started
+        ? Math.max(0, DateTime.toEpochMillis(now) - started.startedAtMs)
+        : null;
       yield* addCurrentSpanEvent("git.hook.finished", {
         hookName: started?.hookName ?? hookName,
         exitCode,
@@ -579,11 +531,11 @@ const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
   };
 });
 
-const collectOutput = Effect.fn("collectOutput")(function* <E>(
-  input: Pick<ExecuteGitInput, "operation" | "cwd" | "args">,
+const collectOutput = Effect.fnUntraced(function* <E>(
+  input: Pick<GitVcsDriver.ExecuteGitInput, "operation" | "cwd" | "args">,
   stream: Stream.Stream<Uint8Array, E>,
   maxOutputBytes: number,
-  truncateOutputAtMaxBytes: boolean,
+  appendTruncationMarker: boolean,
   onLine: ((line: string) => Effect.Effect<void, never>) | undefined,
 ): Effect.fn.Return<{ readonly text: string; readonly truncated: boolean }, GitCommandError> {
   const decoder = new TextDecoder();
@@ -592,7 +544,7 @@ const collectOutput = Effect.fn("collectOutput")(function* <E>(
   let lineBuffer = "";
   let truncated = false;
 
-  const emitCompleteLines = Effect.fn("emitCompleteLines")(function* (flush: boolean) {
+  const emitCompleteLines = Effect.fnUntraced(function* (flush: boolean) {
     let newlineIndex = lineBuffer.indexOf("\n");
     while (newlineIndex >= 0) {
       const line = lineBuffer.slice(0, newlineIndex).replace(/\r$/, "");
@@ -612,12 +564,12 @@ const collectOutput = Effect.fn("collectOutput")(function* <E>(
     }
   });
 
-  const processChunk = Effect.fn("processChunk")(function* (chunk: Uint8Array) {
-    if (truncateOutputAtMaxBytes && truncated) {
+  const processChunk = Effect.fnUntraced(function* (chunk: Uint8Array) {
+    if (appendTruncationMarker && truncated) {
       return;
     }
     const nextBytes = bytes + chunk.byteLength;
-    if (!truncateOutputAtMaxBytes && nextBytes > maxOutputBytes) {
+    if (!appendTruncationMarker && nextBytes > maxOutputBytes) {
       return yield* new GitCommandError({
         operation: input.operation,
         command: quoteGitCommand(input.args),
@@ -627,11 +579,11 @@ const collectOutput = Effect.fn("collectOutput")(function* <E>(
     }
 
     const chunkToDecode =
-      truncateOutputAtMaxBytes && nextBytes > maxOutputBytes
+      appendTruncationMarker && nextBytes > maxOutputBytes
         ? chunk.subarray(0, Math.max(0, maxOutputBytes - bytes))
         : chunk;
     bytes += chunkToDecode.byteLength;
-    truncated = truncateOutputAtMaxBytes && nextBytes > maxOutputBytes;
+    truncated = appendTruncationMarker && nextBytes > maxOutputBytes;
 
     const decoded = decoder.decode(chunkToDecode, { stream: !truncated });
     text += decoded;
@@ -653,27 +605,21 @@ const collectOutput = Effect.fn("collectOutput")(function* <E>(
   };
 });
 
-export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
-  executeOverride?: GitCoreShape["execute"];
-}) {
+export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function* () {
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
+  const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const { worktreesDir } = yield* ServerConfig;
 
-  let executeRaw: GitCoreShape["execute"];
-
-  if (options?.executeOverride) {
-    executeRaw = options.executeOverride;
-  } else {
-    const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-    executeRaw = Effect.fnUntraced(function* (input) {
+  const executeRaw: GitVcsDriver.GitVcsDriverShape["execute"] = Effect.fnUntraced(
+    function* (input) {
       const commandInput = {
         ...input,
         args: [...input.args],
       } as const;
       const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
       const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
-      const truncateOutputAtMaxBytes = input.truncateOutputAtMaxBytes ?? false;
+      const appendTruncationMarker = input.appendTruncationMarker ?? false;
 
       const runGitCommand = Effect.fn("runGitCommand")(function* () {
         const trace2Monitor = yield* createTrace2Monitor(commandInput, input.progress).pipe(
@@ -700,18 +646,17 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
               commandInput,
               child.stdout,
               maxOutputBytes,
-              truncateOutputAtMaxBytes,
+              appendTruncationMarker,
               input.progress?.onStdoutLine,
             ),
             collectOutput(
               commandInput,
               child.stderr,
               maxOutputBytes,
-              truncateOutputAtMaxBytes,
+              appendTruncationMarker,
               input.progress?.onStderrLine,
             ),
             child.exitCode.pipe(
-              Effect.map((value) => Number(value)),
               Effect.mapError(toGitCommandError(commandInput, "failed to report exit code.")),
             ),
             input.stdin === undefined
@@ -738,12 +683,12 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
         }
 
         return {
-          code: exitCode,
+          exitCode,
           stdout: stdout.text,
           stderr: stderr.text,
           stdoutTruncated: stdout.truncated,
           stderrTruncated: stderr.truncated,
-        } satisfies ExecuteGitResult;
+        } satisfies GitVcsDriver.ExecuteGitResult;
       });
 
       return yield* runGitCommand().pipe(
@@ -764,10 +709,10 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
           }),
         ),
       );
-    });
-  }
+    },
+  );
 
-  const execute: GitCoreShape["execute"] = (input) =>
+  const execute: GitVcsDriver.GitVcsDriverShape["execute"] = (input) =>
     executeRaw(input).pipe(
       withMetrics({
         counter: gitCommandsTotal,
@@ -791,22 +736,23 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     cwd: string,
     args: readonly string[],
     options: ExecuteGitOptions = {},
-  ): Effect.Effect<ExecuteGitResult, GitCommandError> =>
+  ): Effect.Effect<GitVcsDriver.ExecuteGitResult, GitCommandError> =>
     execute({
       operation,
       cwd,
       args,
       ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
+      ...(options.env !== undefined ? { env: options.env } : {}),
       allowNonZeroExit: true,
       ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
       ...(options.maxOutputBytes !== undefined ? { maxOutputBytes: options.maxOutputBytes } : {}),
-      ...(options.truncateOutputAtMaxBytes !== undefined
-        ? { truncateOutputAtMaxBytes: options.truncateOutputAtMaxBytes }
+      ...(options.appendTruncationMarker !== undefined
+        ? { appendTruncationMarker: options.appendTruncationMarker }
         : {}),
       ...(options.progress ? { progress: options.progress } : {}),
     }).pipe(
       Effect.flatMap((result) => {
-        if (options.allowNonZeroExit || result.code === 0) {
+        if (options.allowNonZeroExit || result.exitCode === 0) {
           return Effect.succeed(result);
         }
         const stderr = result.stderr.trim();
@@ -823,7 +769,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
             operation,
             cwd,
             args,
-            `${commandLabel(args)} failed: code=${result.code ?? "null"}`,
+            `${commandLabel(args)} failed: code=${result.exitCode ?? "null"}`,
           ),
         );
       }),
@@ -859,16 +805,16 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       ),
     );
 
-  const branchExists = (cwd: string, branch: string): Effect.Effect<boolean, GitCommandError> =>
+  const branchExists = (cwd: string, refName: string): Effect.Effect<boolean, GitCommandError> =>
     executeGit(
-      "GitCore.branchExists",
+      "GitVcsDriver.branchExists",
       cwd,
-      ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
+      ["show-ref", "--verify", "--quiet", `refs/heads/${refName}`],
       {
         allowNonZeroExit: true,
         timeoutMs: 5_000,
       },
-    ).pipe(Effect.map((result) => result.code === 0));
+    ).pipe(Effect.map((result) => result.exitCode === 0));
 
   const resolveAvailableBranchName = Effect.fn("resolveAvailableBranchName")(function* (
     cwd: string,
@@ -888,7 +834,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     }
 
     return yield* createGitCommandError(
-      "GitCore.renameBranch",
+      "GitVcsDriver.renameBranch",
       cwd,
       ["branch", "-m", "--", desiredBranch],
       `Could not find an available branch name for '${desiredBranch}'.`,
@@ -897,7 +843,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
 
   const resolveCurrentUpstream = Effect.fn("resolveCurrentUpstream")(function* (cwd: string) {
     const upstreamRef = yield* runGitStdout(
-      "GitCore.resolveCurrentUpstream",
+      "GitVcsDriver.resolveCurrentUpstream",
       cwd,
       ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"],
       true,
@@ -907,7 +853,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       return null;
     }
 
-    const remoteNames = yield* runGitStdout("GitCore.listRemoteNames", cwd, ["remote"]).pipe(
+    const remoteNames = yield* runGitStdout("GitVcsDriver.listRemoteNames", cwd, ["remote"]).pipe(
       Effect.map(parseRemoteNames),
       Effect.catch(() => Effect.succeed<ReadonlyArray<string>>([])),
     );
@@ -924,18 +870,19 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     const fetchCwd =
       path.basename(gitCommonDir) === ".git" ? path.dirname(gitCommonDir) : gitCommonDir;
     return executeGit(
-      "GitCore.fetchRemoteForStatus",
+      "GitVcsDriver.fetchRemoteForStatus",
       fetchCwd,
       ["--git-dir", gitCommonDir, "fetch", "--quiet", "--no-tags", remoteName],
       {
         allowNonZeroExit: true,
+        env: STATUS_UPSTREAM_REFRESH_ENV,
         timeoutMs: Duration.toMillis(STATUS_UPSTREAM_REFRESH_TIMEOUT),
       },
     ).pipe(Effect.asVoid);
   };
 
   const resolveGitCommonDir = Effect.fn("resolveGitCommonDir")(function* (cwd: string) {
-    const gitCommonDir = yield* runGitStdout("GitCore.resolveGitCommonDir", cwd, [
+    const gitCommonDir = yield* runGitStdout("GitVcsDriver.resolveGitCommonDir", cwd, [
       "rev-parse",
       "--git-common-dir",
     ]).pipe(Effect.map((stdout) => stdout.trim()));
@@ -978,13 +925,13 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     remoteName: string,
   ): Effect.Effect<string | null, GitCommandError> =>
     executeGit(
-      "GitCore.resolveDefaultBranchName",
+      "GitVcsDriver.resolveDefaultBranchName",
       cwd,
       ["symbolic-ref", `refs/remotes/${remoteName}/HEAD`],
       { allowNonZeroExit: true },
     ).pipe(
       Effect.map((result) => {
-        if (result.code !== 0) {
+        if (result.exitCode !== 0) {
           return null;
         }
         return parseDefaultBranchFromRemoteHeadRef(result.stdout, remoteName);
@@ -994,27 +941,36 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
   const remoteBranchExists = (
     cwd: string,
     remoteName: string,
-    branch: string,
+    refName: string,
   ): Effect.Effect<boolean, GitCommandError> =>
     executeGit(
-      "GitCore.remoteBranchExists",
+      "GitVcsDriver.remoteBranchExists",
       cwd,
-      ["show-ref", "--verify", "--quiet", `refs/remotes/${remoteName}/${branch}`],
+      ["show-ref", "--verify", "--quiet", `refs/remotes/${remoteName}/${refName}`],
       {
         allowNonZeroExit: true,
       },
-    ).pipe(Effect.map((result) => result.code === 0));
+    ).pipe(Effect.map((result) => result.exitCode === 0));
 
   const originRemoteExists = (cwd: string): Effect.Effect<boolean, GitCommandError> =>
-    executeGit("GitCore.originRemoteExists", cwd, ["remote", "get-url", "origin"], {
+    executeGit("GitVcsDriver.originRemoteExists", cwd, ["remote", "get-url", "origin"], {
       allowNonZeroExit: true,
-    }).pipe(Effect.map((result) => result.code === 0));
+    }).pipe(Effect.map((result) => result.exitCode === 0));
 
   const listRemoteNames = (cwd: string): Effect.Effect<ReadonlyArray<string>, GitCommandError> =>
-    runGitStdout("GitCore.listRemoteNames", cwd, ["remote"]).pipe(
+    runGitStdout("GitVcsDriver.listRemoteNames", cwd, ["remote"]).pipe(
       Effect.map(parseRemoteNamesInGitOrder),
     );
 
+  const resolvePublishBranchName = Effect.fn("resolvePublishBranchName")(function* (
+    cwd: string,
+    branchName: string,
+  ) {
+    const remoteNames = yield* listRemoteNames(cwd).pipe(Effect.catch(() => Effect.succeed([])));
+    const parsedRemoteRef = parseRemoteRefWithRemoteNames(branchName, remoteNames);
+    return parsedRemoteRef?.branchName ?? branchName;
+  });
+
   const resolvePrimaryRemoteName = Effect.fn("resolvePrimaryRemoteName")(function* (cwd: string) {
     if (yield* originRemoteExists(cwd)) {
       return "origin";
@@ -1025,7 +981,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       return firstRemote;
     }
     return yield* createGitCommandError(
-      "GitCore.resolvePrimaryRemoteName",
+      "GitVcsDriver.resolvePrimaryRemoteName",
       cwd,
       ["remote"],
       "No git remote is configured for this repository.",
@@ -1034,12 +990,12 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
 
   const resolvePushRemoteName = Effect.fn("resolvePushRemoteName")(function* (
     cwd: string,
-    branch: string,
+    refName: string,
   ) {
     const branchPushRemote = yield* runGitStdout(
-      "GitCore.resolvePushRemoteName.branchPushRemote",
+      "GitVcsDriver.resolvePushRemoteName.branchPushRemote",
       cwd,
-      ["config", "--get", `branch.${branch}.pushRemote`],
+      ["config", "--get", `branch.${refName}.pushRemote`],
       true,
     ).pipe(Effect.map((stdout) => stdout.trim()));
     if (branchPushRemote.length > 0) {
@@ -1047,7 +1003,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     }
 
     const pushDefaultRemote = yield* runGitStdout(
-      "GitCore.resolvePushRemoteName.remotePushDefault",
+      "GitVcsDriver.resolvePushRemoteName.remotePushDefault",
       cwd,
       ["config", "--get", "remote.pushDefault"],
       true,
@@ -1059,39 +1015,47 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     return yield* resolvePrimaryRemoteName(cwd).pipe(Effect.catch(() => Effect.succeed(null)));
   });
 
-  const ensureRemote: GitCoreShape["ensureRemote"] = Effect.fn("ensureRemote")(function* (input) {
-    const preferredName = sanitizeRemoteName(input.preferredName);
-    const normalizedTargetUrl = normalizeRemoteUrl(input.url);
-    const remoteFetchUrls = yield* runGitStdout("GitCore.ensureRemote.listRemoteUrls", input.cwd, [
-      "remote",
-      "-v",
-    ]).pipe(Effect.map((stdout) => parseRemoteFetchUrls(stdout)));
-
-    for (const [remoteName, remoteUrl] of remoteFetchUrls.entries()) {
-      if (normalizeRemoteUrl(remoteUrl) === normalizedTargetUrl) {
-        return remoteName;
+  const ensureRemote: GitVcsDriver.GitVcsDriverShape["ensureRemote"] = Effect.fn("ensureRemote")(
+    function* (input) {
+      const preferredName = sanitizeRemoteName(input.preferredName);
+      const normalizedTargetUrl = normalizeRemoteUrl(input.url);
+      const remoteFetchUrls = yield* runGitStdout(
+        "GitVcsDriver.ensureRemote.listRemoteUrls",
+        input.cwd,
+        ["remote", "-v"],
+      ).pipe(Effect.map((stdout) => parseRemoteFetchUrls(stdout)));
+
+      for (const [remoteName, remoteUrl] of remoteFetchUrls.entries()) {
+        if (normalizeRemoteUrl(remoteUrl) === normalizedTargetUrl) {
+          return remoteName;
+        }
       }
-    }
 
-    let remoteName = preferredName;
-    let suffix = 1;
-    while (remoteFetchUrls.has(remoteName)) {
-      remoteName = `${preferredName}-${suffix}`;
-      suffix += 1;
-    }
+      let remoteName = preferredName;
+      let suffix = 1;
+      while (remoteFetchUrls.has(remoteName)) {
+        remoteName = `${preferredName}-${suffix}`;
+        suffix += 1;
+      }
 
-    yield* runGit("GitCore.ensureRemote.add", input.cwd, ["remote", "add", remoteName, input.url]);
-    return remoteName;
-  });
+      yield* runGit("GitVcsDriver.ensureRemote.add", input.cwd, [
+        "remote",
+        "add",
+        remoteName,
+        input.url,
+      ]);
+      return remoteName;
+    },
+  );
 
   const resolveBaseBranchForNoUpstream = Effect.fn("resolveBaseBranchForNoUpstream")(function* (
     cwd: string,
-    branch: string,
+    refName: string,
   ) {
     const configuredBaseBranch = yield* runGitStdout(
-      "GitCore.resolveBaseBranchForNoUpstream.config",
+      "GitVcsDriver.resolveBaseBranchForNoUpstream.config",
       cwd,
-      ["config", "--get", `branch.${branch}.gh-merge-base`],
+      ["config", "--get", `branch.${refName}.gh-merge-base`],
       true,
     ).pipe(Effect.map((stdout) => stdout.trim()));
 
@@ -1118,7 +1082,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
         : remotePrefix && candidate.startsWith(remotePrefix)
           ? candidate.slice(remotePrefix.length)
           : candidate;
-      if (normalizedCandidate.length === 0 || normalizedCandidate === branch) {
+      if (normalizedCandidate.length === 0 || normalizedCandidate === refName) {
         continue;
       }
 
@@ -1139,20 +1103,20 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
 
   const computeAheadCountAgainstBase = Effect.fn("computeAheadCountAgainstBase")(function* (
     cwd: string,
-    branch: string,
+    refName: string,
   ) {
-    const baseBranch = yield* resolveBaseBranchForNoUpstream(cwd, branch);
-    if (!baseBranch) {
+    const baseRef = yield* resolveBaseBranchForNoUpstream(cwd, refName);
+    if (!baseRef) {
       return 0;
     }
 
     const result = yield* executeGit(
-      "GitCore.computeAheadCountAgainstBase",
+      "GitVcsDriver.computeAheadCountAgainstBase",
       cwd,
-      ["rev-list", "--count", `${baseBranch}..HEAD`],
+      ["rev-list", "--count", `${baseRef}..HEAD`],
       { allowNonZeroExit: true },
     );
-    if (result.code !== 0) {
+    if (result.exitCode !== 0) {
       return 0;
     }
 
@@ -1162,7 +1126,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
 
   const readBranchRecency = Effect.fn("readBranchRecency")(function* (cwd: string) {
     const branchRecency = yield* executeGit(
-      "GitCore.readBranchRecency",
+      "GitVcsDriver.readBranchRecency",
       cwd,
       [
         "for-each-ref",
@@ -1177,7 +1141,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     );
 
     const branchLastCommit = new Map<string, number>();
-    if (branchRecency.code !== 0) {
+    if (branchRecency.exitCode !== 0) {
       return branchLastCommit;
     }
 
@@ -1198,7 +1162,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
 
   const readStatusDetailsLocal = Effect.fn("readStatusDetailsLocal")(function* (cwd: string) {
     const statusResult = yield* executeGit(
-      "GitCore.statusDetails.status",
+      "GitVcsDriver.statusDetails.status",
       cwd,
       ["status", "--porcelain=2", "--branch"],
       {
@@ -1210,27 +1174,27 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       return NON_REPOSITORY_STATUS_DETAILS;
     }
 
-    if (statusResult.code !== 0) {
+    if (statusResult.exitCode !== 0) {
       const stderr = statusResult.stderr.trim();
       return yield* createGitCommandError(
-        "GitCore.statusDetails.status",
+        "GitVcsDriver.statusDetails.status",
         cwd,
         ["status", "--porcelain=2", "--branch"],
         stderr || "git status failed",
       );
     }
 
-    const [unstagedNumstatStdout, stagedNumstatStdout, defaultRefResult, hasOriginRemote] =
+    const [unstagedNumstatStdout, stagedNumstatStdout, defaultRefResult, hasPrimaryRemote] =
       yield* Effect.all(
         [
-          runGitStdout("GitCore.statusDetails.unstagedNumstat", cwd, ["diff", "--numstat"]),
-          runGitStdout("GitCore.statusDetails.stagedNumstat", cwd, [
+          runGitStdout("GitVcsDriver.statusDetails.unstagedNumstat", cwd, ["diff", "--numstat"]),
+          runGitStdout("GitVcsDriver.statusDetails.stagedNumstat", cwd, [
             "diff",
             "--cached",
             "--numstat",
           ]),
           executeGit(
-            "GitCore.statusDetails.defaultRef",
+            "GitVcsDriver.statusDetails.defaultRef",
             cwd,
             ["symbolic-ref", "refs/remotes/origin/HEAD"],
             {
@@ -1243,21 +1207,22 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       );
     const statusStdout = statusResult.stdout;
     const defaultBranch =
-      defaultRefResult.code === 0
+      defaultRefResult.exitCode === 0
         ? defaultRefResult.stdout.trim().replace(/^refs\/remotes\/origin\//, "")
         : null;
 
-    let branch: string | null = null;
+    let refName: string | null = null;
     let upstreamRef: string | null = null;
     let aheadCount = 0;
     let behindCount = 0;
+    let aheadOfDefaultCount = 0;
     let hasWorkingTreeChanges = false;
     const changedFilesWithoutNumstat = new Set<string>();
 
     for (const line of statusStdout.split(/\r?\n/g)) {
       if (line.startsWith("# branch.head ")) {
         const value = line.slice("# branch.head ".length).trim();
-        branch = value.startsWith("(") ? null : value;
+        refName = value.startsWith("(") ? null : value;
         continue;
       }
       if (line.startsWith("# branch.upstream ")) {
@@ -1279,13 +1244,31 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       }
     }
 
-    if (!upstreamRef && branch) {
-      aheadCount = yield* computeAheadCountAgainstBase(cwd, branch).pipe(
-        Effect.catch(() => Effect.succeed(0)),
-      );
+    const fallbackAheadCount =
+      !upstreamRef && refName
+        ? yield* computeAheadCountAgainstBase(cwd, refName).pipe(
+            Effect.catch(() => Effect.succeed(0)),
+          )
+        : null;
+
+    if (fallbackAheadCount !== null) {
+      aheadCount = fallbackAheadCount;
       behindCount = 0;
     }
 
+    const isDefaultBranch =
+      refName !== null &&
+      (refName === defaultBranch ||
+        (defaultBranch === null && (refName === "main" || refName === "master")));
+    if (refName && !isDefaultBranch) {
+      aheadOfDefaultCount =
+        fallbackAheadCount !== null
+          ? fallbackAheadCount
+          : yield* computeAheadCountAgainstBase(cwd, refName).pipe(
+              Effect.catch(() => Effect.succeed(0)),
+            );
+    }
+
     const stagedEntries = parseNumstatEntries(stagedNumstatStdout);
     const unstagedEntries = parseNumstatEntries(unstagedNumstatStdout);
     const fileStatMap = new Map<string, { insertions: number; deletions: number }>();
@@ -1314,12 +1297,9 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
 
     return {
       isRepo: true,
-      hasOriginRemote,
-      isDefaultBranch:
-        branch !== null &&
-        (branch === defaultBranch ||
-          (defaultBranch === null && (branch === "main" || branch === "master"))),
-      branch,
+      hasOriginRemote: hasPrimaryRemote,
+      isDefaultBranch,
+      branch: refName,
       upstreamRef,
       hasWorkingTreeChanges,
       workingTree: {
@@ -1330,72 +1310,76 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       hasUpstream: upstreamRef !== null,
       aheadCount,
       behindCount,
+      aheadOfDefaultCount,
     };
   });
 
-  const statusDetailsLocal: GitCoreShape["statusDetailsLocal"] = Effect.fn("statusDetailsLocal")(
+  const statusDetailsLocal: GitVcsDriver.GitVcsDriverShape["statusDetailsLocal"] = Effect.fn(
+    "statusDetailsLocal",
+  )(function* (cwd) {
+    return yield* readStatusDetailsLocal(cwd);
+  });
+
+  const statusDetails: GitVcsDriver.GitVcsDriverShape["statusDetails"] = Effect.fn("statusDetails")(
     function* (cwd) {
+      yield* refreshStatusUpstreamIfStale(cwd).pipe(
+        Effect.catchIf(isMissingGitCwdError, () => Effect.void),
+        Effect.ignoreCause({ log: true }),
+      );
       return yield* readStatusDetailsLocal(cwd);
     },
   );
 
-  const statusDetails: GitCoreShape["statusDetails"] = Effect.fn("statusDetails")(function* (cwd) {
-    yield* refreshStatusUpstreamIfStale(cwd).pipe(
-      Effect.catchIf(isMissingGitCwdError, () => Effect.void),
-      Effect.ignoreCause({ log: true }),
-    );
-    return yield* readStatusDetailsLocal(cwd);
-  });
-
-  const status: GitCoreShape["status"] = (input) =>
+  const status: GitVcsDriver.GitVcsDriverShape["status"] = (input) =>
     statusDetails(input.cwd).pipe(
       Effect.map((details) => ({
         isRepo: details.isRepo,
-        hasOriginRemote: details.hasOriginRemote,
-        isDefaultBranch: details.isDefaultBranch,
-        branch: details.branch,
+        hasPrimaryRemote: details.hasOriginRemote,
+        isDefaultRef: details.isDefaultBranch,
+        refName: details.branch,
         hasWorkingTreeChanges: details.hasWorkingTreeChanges,
         workingTree: details.workingTree,
         hasUpstream: details.hasUpstream,
         aheadCount: details.aheadCount,
         behindCount: details.behindCount,
+        aheadOfDefaultCount: details.aheadOfDefaultCount,
         pr: null,
       })),
     );
 
-  const prepareCommitContext: GitCoreShape["prepareCommitContext"] = Effect.fn(
+  const prepareCommitContext: GitVcsDriver.GitVcsDriverShape["prepareCommitContext"] = Effect.fn(
     "prepareCommitContext",
   )(function* (cwd, filePaths) {
     if (filePaths && filePaths.length > 0) {
-      yield* runGit("GitCore.prepareCommitContext.reset", cwd, ["reset"]).pipe(
+      yield* runGit("GitVcsDriver.prepareCommitContext.reset", cwd, ["reset"]).pipe(
         Effect.catch(() => Effect.void),
       );
-      yield* runGit("GitCore.prepareCommitContext.addSelected", cwd, [
+      yield* runGit("GitVcsDriver.prepareCommitContext.addSelected", cwd, [
         "add",
         "-A",
         "--",
         ...filePaths,
       ]);
     } else {
-      yield* runGit("GitCore.prepareCommitContext.addAll", cwd, ["add", "-A"]);
+      yield* runGit("GitVcsDriver.prepareCommitContext.addAll", cwd, ["add", "-A"]);
     }
 
-    const stagedSummary = yield* runGitStdout("GitCore.prepareCommitContext.stagedSummary", cwd, [
-      "diff",
-      "--cached",
-      "--name-status",
-    ]).pipe(Effect.map((stdout) => stdout.trim()));
+    const stagedSummary = yield* runGitStdout(
+      "GitVcsDriver.prepareCommitContext.stagedSummary",
+      cwd,
+      ["diff", "--cached", "--name-status"],
+    ).pipe(Effect.map((stdout) => stdout.trim()));
     if (stagedSummary.length === 0) {
       return null;
     }
 
     const stagedPatch = yield* runGitStdoutWithOptions(
-      "GitCore.prepareCommitContext.stagedPatch",
+      "GitVcsDriver.prepareCommitContext.stagedPatch",
       cwd,
       ["diff", "--cached", "--patch", "--minimal"],
       {
         maxOutputBytes: PREPARED_COMMIT_PATCH_MAX_OUTPUT_BYTES,
-        truncateOutputAtMaxBytes: true,
+        appendTruncationMarker: true,
       },
     );
 
@@ -1405,11 +1389,11 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     };
   });
 
-  const commit: GitCoreShape["commit"] = Effect.fn("commit")(function* (
+  const commit: GitVcsDriver.GitVcsDriverShape["commit"] = Effect.fn("commit")(function* (
     cwd,
     subject,
     body,
-    options?: GitCommitOptions,
+    options?: GitVcsDriver.GitCommitOptions,
   ) {
     const args = ["commit", "-m", subject];
     const trimmedBody = body.trim();
@@ -1426,11 +1410,11 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
             onStderrLine: (line: string) =>
               options.progress?.onOutputLine?.({ stream: "stderr", text: line }) ?? Effect.void,
           };
-    yield* executeGit("GitCore.commit.commit", cwd, args, {
+    yield* executeGit("GitVcsDriver.commit.commit", cwd, args, {
       ...(options?.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
       ...(progress ? { progress } : {}),
     }).pipe(Effect.asVoid);
-    const commitSha = yield* runGitStdout("GitCore.commit.revParseHead", cwd, [
+    const commitSha = yield* runGitStdout("GitVcsDriver.commit.revParseHead", cwd, [
       "rev-parse",
       "HEAD",
     ]).pipe(Effect.map((stdout) => stdout.trim()));
@@ -1438,656 +1422,610 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     return { commitSha };
   });
 
-  const pushCurrentBranch: GitCoreShape["pushCurrentBranch"] = Effect.fn("pushCurrentBranch")(
-    function* (cwd, fallbackBranch) {
-      const details = yield* statusDetails(cwd);
-      const branch = details.branch ?? fallbackBranch;
-      if (!branch) {
-        return yield* createGitCommandError(
-          "GitCore.pushCurrentBranch",
-          cwd,
-          ["push"],
-          "Cannot push from detached HEAD.",
-        );
-      }
-
-      const hasNoLocalDelta = details.aheadCount === 0 && details.behindCount === 0;
-      if (hasNoLocalDelta) {
-        if (details.hasUpstream) {
-          return {
-            status: "skipped_up_to_date" as const,
-            branch,
-            ...(details.upstreamRef ? { upstreamBranch: details.upstreamRef } : {}),
-          };
-        }
-
-        const comparableBaseBranch = yield* resolveBaseBranchForNoUpstream(cwd, branch).pipe(
-          Effect.catch(() => Effect.succeed(null)),
-        );
-        if (comparableBaseBranch) {
-          const publishRemoteName = yield* resolvePushRemoteName(cwd, branch).pipe(
-            Effect.catch(() => Effect.succeed(null)),
-          );
-          if (!publishRemoteName) {
-            return {
-              status: "skipped_up_to_date" as const,
-              branch,
-            };
-          }
+  const pushCurrentBranch: GitVcsDriver.GitVcsDriverShape["pushCurrentBranch"] = Effect.fn(
+    "pushCurrentBranch",
+  )(function* (cwd, fallbackBranch, options) {
+    const details = yield* statusDetails(cwd);
+    const branch = details.branch ?? fallbackBranch;
+    if (!branch) {
+      return yield* createGitCommandError(
+        "GitVcsDriver.pushCurrentBranch",
+        cwd,
+        ["push"],
+        "Cannot push from detached HEAD.",
+      );
+    }
 
-          const hasRemoteBranch = yield* remoteBranchExists(cwd, publishRemoteName, branch).pipe(
-            Effect.catch(() => Effect.succeed(false)),
-          );
-          if (hasRemoteBranch) {
-            return {
-              status: "skipped_up_to_date" as const,
-              branch,
-            };
-          }
-        }
-      }
+    const requestedRemoteName = options?.remoteName?.trim() || null;
+    if (requestedRemoteName) {
+      const publishBranch = yield* resolvePublishBranchName(cwd, branch);
+      yield* runGit("GitVcsDriver.pushCurrentBranch.pushWithRequestedRemote", cwd, [
+        "push",
+        "-u",
+        requestedRemoteName,
+        `HEAD:refs/heads/${publishBranch}`,
+      ]);
+      return {
+        status: "pushed" as const,
+        branch,
+        upstreamBranch: `${requestedRemoteName}/${publishBranch}`,
+        setUpstream: true,
+      };
+    }
 
-      if (!details.hasUpstream) {
-        const publishRemoteName = yield* resolvePushRemoteName(cwd, branch);
-        if (!publishRemoteName) {
-          return yield* createGitCommandError(
-            "GitCore.pushCurrentBranch",
-            cwd,
-            ["push"],
-            "Cannot push because no git remote is configured for this repository.",
-          );
-        }
-        yield* runGit("GitCore.pushCurrentBranch.pushWithUpstream", cwd, [
-          "push",
-          "-u",
-          publishRemoteName,
-          `HEAD:refs/heads/${branch}`,
-        ]);
+    const hasNoLocalDelta = details.aheadCount === 0 && details.behindCount === 0;
+    if (hasNoLocalDelta) {
+      if (details.hasUpstream) {
         return {
-          status: "pushed" as const,
+          status: "skipped_up_to_date" as const,
           branch,
-          upstreamBranch: `${publishRemoteName}/${branch}`,
-          setUpstream: true,
+          ...(details.upstreamRef ? { upstreamBranch: details.upstreamRef } : {}),
         };
       }
 
-      const currentUpstream = yield* resolveCurrentUpstream(cwd).pipe(
+      const comparableBaseBranch = yield* resolveBaseBranchForNoUpstream(cwd, branch).pipe(
         Effect.catch(() => Effect.succeed(null)),
       );
-      if (currentUpstream) {
-        yield* runGit("GitCore.pushCurrentBranch.pushUpstream", cwd, [
-          "push",
-          currentUpstream.remoteName,
-          `HEAD:${currentUpstream.upstreamBranch}`,
-        ]);
-        return {
-          status: "pushed" as const,
-          branch,
-          upstreamBranch: currentUpstream.upstreamRef,
-          setUpstream: false,
-        };
-      }
-
-      yield* runGit("GitCore.pushCurrentBranch.push", cwd, ["push"]);
-      return {
-        status: "pushed" as const,
-        branch,
-        ...(details.upstreamRef ? { upstreamBranch: details.upstreamRef } : {}),
-        setUpstream: false,
-      };
-    },
-  );
+      if (comparableBaseBranch) {
+        const publishRemoteName = yield* resolvePushRemoteName(cwd, branch).pipe(
+          Effect.catch(() => Effect.succeed(null)),
+        );
+        if (!publishRemoteName) {
+          return {
+            status: "skipped_up_to_date" as const,
+            branch,
+          };
+        }
 
-  const pullCurrentBranch: GitCoreShape["pullCurrentBranch"] = Effect.fn("pullCurrentBranch")(
-    function* (cwd) {
-      const details = yield* statusDetails(cwd);
-      const branch = details.branch;
-      if (!branch) {
-        return yield* createGitCommandError(
-          "GitCore.pullCurrentBranch",
-          cwd,
-          ["pull", "--ff-only"],
-          "Cannot pull from detached HEAD.",
+        const hasRemoteBranch = yield* remoteBranchExists(cwd, publishRemoteName, branch).pipe(
+          Effect.catch(() => Effect.succeed(false)),
         );
+        if (hasRemoteBranch) {
+          return {
+            status: "skipped_up_to_date" as const,
+            branch,
+          };
+        }
       }
-      if (!details.hasUpstream) {
+    }
+
+    if (!details.hasUpstream) {
+      const publishRemoteName = yield* resolvePushRemoteName(cwd, branch);
+      if (!publishRemoteName) {
         return yield* createGitCommandError(
-          "GitCore.pullCurrentBranch",
+          "GitVcsDriver.pushCurrentBranch",
           cwd,
-          ["pull", "--ff-only"],
-          "Current branch has no upstream configured. Push with upstream first.",
+          ["push"],
+          "Cannot push because no git remote is configured for this repository.",
         );
       }
-      const beforeSha = yield* runGitStdout(
-        "GitCore.pullCurrentBranch.beforeSha",
-        cwd,
-        ["rev-parse", "HEAD"],
-        true,
-      ).pipe(Effect.map((stdout) => stdout.trim()));
-      yield* executeGit("GitCore.pullCurrentBranch.pull", cwd, ["pull", "--ff-only"], {
-        timeoutMs: 30_000,
-        fallbackErrorMessage: "git pull failed",
-      });
-      const afterSha = yield* runGitStdout(
-        "GitCore.pullCurrentBranch.afterSha",
-        cwd,
-        ["rev-parse", "HEAD"],
-        true,
-      ).pipe(Effect.map((stdout) => stdout.trim()));
-
-      const refreshed = yield* statusDetails(cwd);
+      const publishBranch = yield* resolvePublishBranchName(cwd, branch);
+      yield* runGit("GitVcsDriver.pushCurrentBranch.pushWithUpstream", cwd, [
+        "push",
+        "-u",
+        publishRemoteName,
+        `HEAD:refs/heads/${publishBranch}`,
+      ]);
       return {
-        status: beforeSha.length > 0 && beforeSha === afterSha ? "skipped_up_to_date" : "pulled",
+        status: "pushed" as const,
         branch,
-        upstreamBranch: refreshed.upstreamRef,
+        upstreamBranch: `${publishRemoteName}/${publishBranch}`,
+        setUpstream: true,
       };
-    },
-  );
-
-  const readRangeContext: GitCoreShape["readRangeContext"] = Effect.fn("readRangeContext")(
-    function* (cwd, baseBranch) {
-      const range = `${baseBranch}..HEAD`;
-      const [commitSummary, diffSummary, diffPatch] = yield* Effect.all(
-        [
-          runGitStdoutWithOptions(
-            "GitCore.readRangeContext.log",
-            cwd,
-            ["log", "--oneline", range],
-            {
-              maxOutputBytes: RANGE_COMMIT_SUMMARY_MAX_OUTPUT_BYTES,
-              truncateOutputAtMaxBytes: true,
-            },
-          ),
-          runGitStdoutWithOptions(
-            "GitCore.readRangeContext.diffStat",
-            cwd,
-            ["diff", "--stat", range],
-            {
-              maxOutputBytes: RANGE_DIFF_SUMMARY_MAX_OUTPUT_BYTES,
-              truncateOutputAtMaxBytes: true,
-            },
-          ),
-          runGitStdoutWithOptions(
-            "GitCore.readRangeContext.diffPatch",
-            cwd,
-            ["diff", "--patch", "--minimal", range],
-            {
-              maxOutputBytes: RANGE_DIFF_PATCH_MAX_OUTPUT_BYTES,
-              truncateOutputAtMaxBytes: true,
-            },
-          ),
-        ],
-        { concurrency: "unbounded" },
-      );
+    }
 
+    const currentUpstream = yield* resolveCurrentUpstream(cwd).pipe(
+      Effect.catch(() => Effect.succeed(null)),
+    );
+    if (currentUpstream) {
+      yield* runGit("GitVcsDriver.pushCurrentBranch.pushUpstream", cwd, [
+        "push",
+        currentUpstream.remoteName,
+        `HEAD:refs/heads/${currentUpstream.branchName}`,
+      ]);
       return {
-        commitSummary,
-        diffSummary,
-        diffPatch,
+        status: "pushed" as const,
+        branch,
+        upstreamBranch: currentUpstream.upstreamRef,
+        setUpstream: false,
       };
-    },
-  );
-
-  const readConfigValue: GitCoreShape["readConfigValue"] = (cwd, key) =>
-    runGitStdout("GitCore.readConfigValue", cwd, ["config", "--get", key], true).pipe(
-      Effect.map((stdout) => stdout.trim()),
-      Effect.map((trimmed) => (trimmed.length > 0 ? trimmed : null)),
-    );
+    }
 
-  const isInsideWorkTree: GitCoreShape["isInsideWorkTree"] = (cwd) =>
-    executeGit("GitCore.isInsideWorkTree", cwd, ["rev-parse", "--is-inside-work-tree"], {
-      allowNonZeroExit: true,
-      timeoutMs: 5_000,
-      maxOutputBytes: 4_096,
-    }).pipe(Effect.map((result) => result.code === 0 && result.stdout.trim() === "true"));
+    yield* runGit("GitVcsDriver.pushCurrentBranch.push", cwd, ["push"]);
+    return {
+      status: "pushed" as const,
+      branch,
+      ...(details.upstreamRef ? { upstreamBranch: details.upstreamRef } : {}),
+      setUpstream: false,
+    };
+  });
 
-  const listWorkspaceFiles: GitCoreShape["listWorkspaceFiles"] = (cwd) =>
-    executeGit(
-      "GitCore.listWorkspaceFiles",
+  const pullCurrentBranch: GitVcsDriver.GitVcsDriverShape["pullCurrentBranch"] = Effect.fn(
+    "pullCurrentBranch",
+  )(function* (cwd) {
+    const details = yield* statusDetails(cwd);
+    const refName = details.branch;
+    if (!refName) {
+      return yield* createGitCommandError(
+        "GitVcsDriver.pullCurrentBranch",
+        cwd,
+        ["pull", "--ff-only"],
+        "Cannot pull from detached HEAD.",
+      );
+    }
+    if (!details.hasUpstream) {
+      return yield* createGitCommandError(
+        "GitVcsDriver.pullCurrentBranch",
+        cwd,
+        ["pull", "--ff-only"],
+        "Current branch has no upstream configured. Push with upstream first.",
+      );
+    }
+    const beforeSha = yield* runGitStdout(
+      "GitVcsDriver.pullCurrentBranch.beforeSha",
       cwd,
-      [
-        ...WORKSPACE_GIT_HARDENED_CONFIG_ARGS,
-        "ls-files",
-        "--cached",
-        "--others",
-        "--exclude-standard",
-        "-z",
-      ],
-      {
-        allowNonZeroExit: true,
-        timeoutMs: 20_000,
-        maxOutputBytes: WORKSPACE_FILES_MAX_OUTPUT_BYTES,
-        truncateOutputAtMaxBytes: true,
-      },
-    ).pipe(
-      Effect.flatMap((result) =>
-        result.code === 0
-          ? Effect.succeed({
-              paths: splitNullSeparatedPaths(result.stdout, result.stdoutTruncated),
-              truncated: result.stdoutTruncated,
-            })
-          : Effect.fail(
-              createGitCommandError(
-                "GitCore.listWorkspaceFiles",
-                cwd,
-                [
-                  ...WORKSPACE_GIT_HARDENED_CONFIG_ARGS,
-                  "ls-files",
-                  "--cached",
-                  "--others",
-                  "--exclude-standard",
-                  "-z",
-                ],
-                result.stderr.trim().length > 0 ? result.stderr.trim() : "git ls-files failed",
-              ),
-            ),
-      ),
-    );
-
-  const filterIgnoredPaths: GitCoreShape["filterIgnoredPaths"] = (cwd, relativePaths) =>
-    Effect.gen(function* () {
-      if (relativePaths.length === 0) {
-        return relativePaths;
-      }
+      ["rev-parse", "HEAD"],
+      true,
+    ).pipe(Effect.map((stdout) => stdout.trim()));
+    yield* executeGit("GitVcsDriver.pullCurrentBranch.pull", cwd, ["pull", "--ff-only"], {
+      timeoutMs: 30_000,
+      fallbackErrorMessage: "git pull failed",
+    });
+    const afterSha = yield* runGitStdout(
+      "GitVcsDriver.pullCurrentBranch.afterSha",
+      cwd,
+      ["rev-parse", "HEAD"],
+      true,
+    ).pipe(Effect.map((stdout) => stdout.trim()));
 
-      const ignoredPaths = new Set<string>();
-      const chunks = chunkPathsForGitCheckIgnore(relativePaths);
+    const refreshed = yield* statusDetails(cwd);
+    return {
+      status: beforeSha.length > 0 && beforeSha === afterSha ? "skipped_up_to_date" : "pulled",
+      refName,
+      upstreamRef: refreshed.upstreamRef,
+    };
+  });
 
-      for (const chunk of chunks) {
-        const result = yield* executeGit(
-          "GitCore.filterIgnoredPaths",
+  const readRangeContext: GitVcsDriver.GitVcsDriverShape["readRangeContext"] = Effect.fn(
+    "readRangeContext",
+  )(function* (cwd, baseRef) {
+    const range = `${baseRef}..HEAD`;
+    const [commitSummary, diffSummary, diffPatch] = yield* Effect.all(
+      [
+        runGitStdoutWithOptions(
+          "GitVcsDriver.readRangeContext.log",
           cwd,
-          [...WORKSPACE_GIT_HARDENED_CONFIG_ARGS, "check-ignore", "--no-index", "-z", "--stdin"],
+          ["log", "--oneline", range],
           {
-            stdin: `${chunk.join("\0")}\0`,
-            allowNonZeroExit: true,
-            timeoutMs: 20_000,
-            maxOutputBytes: WORKSPACE_FILES_MAX_OUTPUT_BYTES,
-            truncateOutputAtMaxBytes: true,
+            maxOutputBytes: RANGE_COMMIT_SUMMARY_MAX_OUTPUT_BYTES,
+            appendTruncationMarker: true,
           },
-        );
-
-        if (result.code !== 0 && result.code !== 1) {
-          return yield* createGitCommandError(
-            "GitCore.filterIgnoredPaths",
-            cwd,
-            [...WORKSPACE_GIT_HARDENED_CONFIG_ARGS, "check-ignore", "--no-index", "-z", "--stdin"],
-            result.stderr.trim().length > 0 ? result.stderr.trim() : "git check-ignore failed",
-          );
-        }
-
-        for (const ignoredPath of splitNullSeparatedPaths(result.stdout, result.stdoutTruncated)) {
-          ignoredPaths.add(ignoredPath);
-        }
-      }
-
-      if (ignoredPaths.size === 0) {
-        return relativePaths;
-      }
+        ),
+        runGitStdoutWithOptions(
+          "GitVcsDriver.readRangeContext.diffStat",
+          cwd,
+          ["diff", "--stat", range],
+          {
+            maxOutputBytes: RANGE_DIFF_SUMMARY_MAX_OUTPUT_BYTES,
+            appendTruncationMarker: true,
+          },
+        ),
+        runGitStdoutWithOptions(
+          "GitVcsDriver.readRangeContext.diffPatch",
+          cwd,
+          ["diff", "--patch", "--minimal", range],
+          {
+            maxOutputBytes: RANGE_DIFF_PATCH_MAX_OUTPUT_BYTES,
+            appendTruncationMarker: true,
+          },
+        ),
+      ],
+      { concurrency: "unbounded" },
+    );
 
-      return relativePaths.filter((relativePath) => !ignoredPaths.has(relativePath));
-    });
+    return {
+      commitSummary,
+      diffSummary,
+      diffPatch,
+    };
+  });
 
-  const listBranches: GitCoreShape["listBranches"] = Effect.fn("listBranches")(function* (input) {
-    const branchRecencyPromise = readBranchRecency(input.cwd).pipe(
-      Effect.catch(() => Effect.succeed(new Map<string, number>())),
-    );
-    const localBranchResult = yield* executeGit(
-      "GitCore.listBranches.branchNoColor",
-      input.cwd,
-      ["branch", "--no-color", "--no-column"],
-      {
-        timeoutMs: 10_000,
-        allowNonZeroExit: true,
-      },
-    ).pipe(
-      Effect.catchIf(isMissingGitCwdError, () =>
-        Effect.succeed({
-          code: 128,
-          stdout: "",
-          stderr: "fatal: not a git repository",
-          stdoutTruncated: false,
-          stderrTruncated: false,
-        }),
-      ),
+  const readConfigValue: GitVcsDriver.GitVcsDriverShape["readConfigValue"] = (cwd, key) =>
+    runGitStdout("GitVcsDriver.readConfigValue", cwd, ["config", "--get", key], true).pipe(
+      Effect.map((stdout) => stdout.trim()),
+      Effect.map((trimmed) => (trimmed.length > 0 ? trimmed : null)),
     );
 
-    if (localBranchResult.code !== 0) {
-      const stderr = localBranchResult.stderr.trim();
-      if (stderr.toLowerCase().includes("not a git repository")) {
-        return {
-          branches: [],
-          isRepo: false,
-          hasOriginRemote: false,
-          nextCursor: null,
-          totalCount: 0,
-        };
-      }
-      return yield* createGitCommandError(
-        "GitCore.listBranches",
+  const listRefs: GitVcsDriver.GitVcsDriverShape["listRefs"] = Effect.fn("listRefs")(
+    function* (input) {
+      const branchRecencyPromise = readBranchRecency(input.cwd).pipe(
+        Effect.catch(() => Effect.succeed(new Map<string, number>())),
+      );
+      const localBranchResult = yield* executeGit(
+        "GitVcsDriver.listRefs.branchNoColor",
         input.cwd,
         ["branch", "--no-color", "--no-column"],
-        stderr || "git branch failed",
+        {
+          timeoutMs: 10_000,
+          allowNonZeroExit: true,
+        },
+      ).pipe(
+        Effect.catchIf(isMissingGitCwdError, () =>
+          Effect.succeed({
+            exitCode: ChildProcessSpawner.ExitCode(128),
+            stdout: "",
+            stderr: "fatal: not a git repository",
+            stdoutTruncated: false,
+            stderrTruncated: false,
+          }),
+        ),
       );
-    }
 
-    const remoteBranchResultEffect = executeGit(
-      "GitCore.listBranches.remoteBranches",
-      input.cwd,
-      ["branch", "--no-color", "--no-column", "--remotes"],
-      {
-        timeoutMs: 10_000,
-        allowNonZeroExit: true,
-      },
-    ).pipe(
-      Effect.catch((error) =>
-        Effect.logWarning(
-          `GitCore.listBranches: remote branch lookup failed for ${input.cwd}: ${error.message}. Falling back to an empty remote branch list.`,
-        ).pipe(Effect.as({ code: 1, stdout: "", stderr: "" })),
-      ),
-    );
-
-    const remoteNamesResultEffect = executeGit(
-      "GitCore.listBranches.remoteNames",
-      input.cwd,
-      ["remote"],
-      {
-        timeoutMs: 5_000,
-        allowNonZeroExit: true,
-      },
-    ).pipe(
-      Effect.catch((error) =>
-        Effect.logWarning(
-          `GitCore.listBranches: remote name lookup failed for ${input.cwd}: ${error.message}. Falling back to an empty remote name list.`,
-        ).pipe(Effect.as({ code: 1, stdout: "", stderr: "" })),
-      ),
-    );
+      if (localBranchResult.exitCode !== 0) {
+        const stderr = localBranchResult.stderr.trim();
+        if (stderr.toLowerCase().includes("not a git repository")) {
+          return {
+            refs: [],
+            isRepo: false,
+            hasPrimaryRemote: false,
+            nextCursor: null,
+            totalCount: 0,
+          };
+        }
+        return yield* createGitCommandError(
+          "GitVcsDriver.listRefs",
+          input.cwd,
+          ["branch", "--no-color", "--no-column"],
+          stderr || "git branch failed",
+        );
+      }
 
-    const [defaultRef, worktreeList, remoteBranchResult, remoteNamesResult, branchLastCommit] =
-      yield* Effect.all(
-        [
-          executeGit(
-            "GitCore.listBranches.defaultRef",
-            input.cwd,
-            ["symbolic-ref", "refs/remotes/origin/HEAD"],
-            {
-              timeoutMs: 5_000,
-              allowNonZeroExit: true,
-            },
-          ),
-          executeGit(
-            "GitCore.listBranches.worktreeList",
-            input.cwd,
-            ["worktree", "list", "--porcelain"],
-            {
-              timeoutMs: 5_000,
-              allowNonZeroExit: true,
-            },
+      const remoteBranchResultEffect = executeGit(
+        "GitVcsDriver.listRefs.remoteBranches",
+        input.cwd,
+        ["branch", "--no-color", "--no-column", "--remotes"],
+        {
+          timeoutMs: 10_000,
+          allowNonZeroExit: true,
+        },
+      ).pipe(
+        Effect.catch((error) =>
+          Effect.logWarning(
+            `GitVcsDriver.listRefs: remote refName lookup failed for ${input.cwd}: ${error.message}. Falling back to an empty remote refName list.`,
+          ).pipe(
+            Effect.as({
+              exitCode: ChildProcessSpawner.ExitCode(1),
+              stdout: "",
+              stderr: "",
+              stdoutTruncated: false,
+              stderrTruncated: false,
+            } satisfies GitVcsDriver.ExecuteGitResult),
           ),
-          remoteBranchResultEffect,
-          remoteNamesResultEffect,
-          branchRecencyPromise,
-        ],
-        { concurrency: "unbounded" },
+        ),
       );
 
-    const remoteNames =
-      remoteNamesResult.code === 0 ? parseRemoteNames(remoteNamesResult.stdout) : [];
-    if (remoteBranchResult.code !== 0 && remoteBranchResult.stderr.trim().length > 0) {
-      yield* Effect.logWarning(
-        `GitCore.listBranches: remote branch lookup returned code ${remoteBranchResult.code} for ${input.cwd}: ${remoteBranchResult.stderr.trim()}. Falling back to an empty remote branch list.`,
-      );
-    }
-    if (remoteNamesResult.code !== 0 && remoteNamesResult.stderr.trim().length > 0) {
-      yield* Effect.logWarning(
-        `GitCore.listBranches: remote name lookup returned code ${remoteNamesResult.code} for ${input.cwd}: ${remoteNamesResult.stderr.trim()}. Falling back to an empty remote name list.`,
+      const remoteNamesResultEffect = executeGit(
+        "GitVcsDriver.listRefs.remoteNames",
+        input.cwd,
+        ["remote"],
+        {
+          timeoutMs: 5_000,
+          allowNonZeroExit: true,
+        },
+      ).pipe(
+        Effect.catch((error) =>
+          Effect.logWarning(
+            `GitVcsDriver.listRefs: remote name lookup failed for ${input.cwd}: ${error.message}. Falling back to an empty remote name list.`,
+          ).pipe(
+            Effect.as({
+              exitCode: ChildProcessSpawner.ExitCode(1),
+              stdout: "",
+              stderr: "",
+              stdoutTruncated: false,
+              stderrTruncated: false,
+            } satisfies GitVcsDriver.ExecuteGitResult),
+          ),
+        ),
       );
-    }
 
-    const defaultBranch =
-      defaultRef.code === 0
-        ? defaultRef.stdout.trim().replace(/^refs\/remotes\/origin\//, "")
-        : null;
+      const [defaultRef, worktreeList, remoteBranchResult, remoteNamesResult, branchLastCommit] =
+        yield* Effect.all(
+          [
+            executeGit(
+              "GitVcsDriver.listRefs.defaultRef",
+              input.cwd,
+              ["symbolic-ref", "refs/remotes/origin/HEAD"],
+              {
+                timeoutMs: 5_000,
+                allowNonZeroExit: true,
+              },
+            ),
+            executeGit(
+              "GitVcsDriver.listRefs.worktreeList",
+              input.cwd,
+              ["worktree", "list", "--porcelain"],
+              {
+                timeoutMs: 5_000,
+                allowNonZeroExit: true,
+              },
+            ),
+            remoteBranchResultEffect,
+            remoteNamesResultEffect,
+            branchRecencyPromise,
+          ],
+          { concurrency: "unbounded" },
+        );
 
-    const worktreeMap = new Map<string, string>();
-    if (worktreeList.code === 0) {
-      let currentPath: string | null = null;
-      for (const line of worktreeList.stdout.split("\n")) {
-        if (line.startsWith("worktree ")) {
-          const candidatePath = line.slice("worktree ".length);
-          const exists = yield* fileSystem.stat(candidatePath).pipe(
-            Effect.map(() => true),
-            Effect.catch(() => Effect.succeed(false)),
-          );
-          currentPath = exists ? candidatePath : null;
-        } else if (line.startsWith("branch refs/heads/") && currentPath) {
-          worktreeMap.set(line.slice("branch refs/heads/".length), currentPath);
-        } else if (line === "") {
-          currentPath = null;
+      const remoteNames =
+        remoteNamesResult.exitCode === 0 ? parseRemoteNames(remoteNamesResult.stdout) : [];
+      if (remoteBranchResult.exitCode !== 0 && remoteBranchResult.stderr.trim().length > 0) {
+        yield* Effect.logWarning(
+          `GitVcsDriver.listRefs: remote refName lookup returned code ${remoteBranchResult.exitCode} for ${input.cwd}: ${remoteBranchResult.stderr.trim()}. Falling back to an empty remote refName list.`,
+        );
+      }
+      if (remoteNamesResult.exitCode !== 0 && remoteNamesResult.stderr.trim().length > 0) {
+        yield* Effect.logWarning(
+          `GitVcsDriver.listRefs: remote name lookup returned code ${remoteNamesResult.exitCode} for ${input.cwd}: ${remoteNamesResult.stderr.trim()}. Falling back to an empty remote name list.`,
+        );
+      }
+
+      const defaultBranch =
+        defaultRef.exitCode === 0
+          ? defaultRef.stdout.trim().replace(/^refs\/remotes\/origin\//, "")
+          : null;
+
+      const worktreeMap = new Map<string, string>();
+      if (worktreeList.exitCode === 0) {
+        let currentPath: string | null = null;
+        for (const line of worktreeList.stdout.split("\n")) {
+          if (line.startsWith("worktree ")) {
+            const candidatePath = line.slice("worktree ".length);
+            const exists = yield* fileSystem.stat(candidatePath).pipe(
+              Effect.map(() => true),
+              Effect.catch(() => Effect.succeed(false)),
+            );
+            currentPath = exists ? candidatePath : null;
+          } else if (line.startsWith("branch refs/heads/") && currentPath) {
+            worktreeMap.set(line.slice("branch refs/heads/".length), currentPath);
+          } else if (line === "") {
+            currentPath = null;
+          }
         }
       }
-    }
 
-    const localBranches = localBranchResult.stdout
-      .split("\n")
-      .map(parseBranchLine)
-      .filter((branch): branch is { name: string; current: boolean } => branch !== null)
-      .map((branch) => ({
-        name: branch.name,
-        current: branch.current,
-        isRemote: false,
-        isDefault: branch.name === defaultBranch,
-        worktreePath: worktreeMap.get(branch.name) ?? null,
-      }))
-      .toSorted((a, b) => {
-        const aPriority = a.current ? 0 : a.isDefault ? 1 : 2;
-        const bPriority = b.current ? 0 : b.isDefault ? 1 : 2;
-        if (aPriority !== bPriority) return aPriority - bPriority;
-
-        const aLastCommit = branchLastCommit.get(a.name) ?? 0;
-        const bLastCommit = branchLastCommit.get(b.name) ?? 0;
-        if (aLastCommit !== bLastCommit) return bLastCommit - aLastCommit;
-        return a.name.localeCompare(b.name);
+      const localBranches = localBranchResult.stdout
+        .split("\n")
+        .map(parseBranchLine)
+        .filter((refName): refName is { name: string; current: boolean } => refName !== null)
+        .map((refName) => ({
+          name: refName.name,
+          current: refName.current,
+          isRemote: false,
+          isDefault: refName.name === defaultBranch,
+          worktreePath: worktreeMap.get(refName.name) ?? null,
+        }))
+        .toSorted((a, b) => {
+          const aPriority = a.current ? 0 : a.isDefault ? 1 : 2;
+          const bPriority = b.current ? 0 : b.isDefault ? 1 : 2;
+          if (aPriority !== bPriority) return aPriority - bPriority;
+
+          const aLastCommit = branchLastCommit.get(a.name) ?? 0;
+          const bLastCommit = branchLastCommit.get(b.name) ?? 0;
+          if (aLastCommit !== bLastCommit) return bLastCommit - aLastCommit;
+          return a.name.localeCompare(b.name);
+        });
+
+      const remoteBranches =
+        remoteBranchResult.exitCode === 0
+          ? remoteBranchResult.stdout
+              .split("\n")
+              .map(parseBranchLine)
+              .filter((refName): refName is { name: string; current: boolean } => refName !== null)
+              .map((refName) => {
+                const parsedRemoteRef = parseRemoteRefWithRemoteNames(refName.name, remoteNames);
+                const remoteBranch: {
+                  name: string;
+                  current: boolean;
+                  isRemote: boolean;
+                  remoteName?: string;
+                  isDefault: boolean;
+                  worktreePath: string | null;
+                } = {
+                  name: refName.name,
+                  current: false,
+                  isRemote: true,
+                  isDefault: false,
+                  worktreePath: null,
+                };
+                if (parsedRemoteRef) {
+                  remoteBranch.remoteName = parsedRemoteRef.remoteName;
+                }
+                return remoteBranch;
+              })
+              .toSorted((a, b) => {
+                const aLastCommit = branchLastCommit.get(a.name) ?? 0;
+                const bLastCommit = branchLastCommit.get(b.name) ?? 0;
+                if (aLastCommit !== bLastCommit) return bLastCommit - aLastCommit;
+                return a.name.localeCompare(b.name);
+              })
+          : [];
+
+      const refs = paginateBranches({
+        refs: filterBranchesForListQuery(
+          dedupeRemoteBranchesWithLocalMatches([...localBranches, ...remoteBranches]),
+          input.query,
+        ),
+        cursor: input.cursor,
+        limit: input.limit,
       });
 
-    const remoteBranches =
-      remoteBranchResult.code === 0
-        ? remoteBranchResult.stdout
-            .split("\n")
-            .map(parseBranchLine)
-            .filter((branch): branch is { name: string; current: boolean } => branch !== null)
-            .map((branch) => {
-              const parsedRemoteRef = parseRemoteRefWithRemoteNames(branch.name, remoteNames);
-              const remoteBranch: {
-                name: string;
-                current: boolean;
-                isRemote: boolean;
-                remoteName?: string;
-                isDefault: boolean;
-                worktreePath: string | null;
-              } = {
-                name: branch.name,
-                current: false,
-                isRemote: true,
-                isDefault: false,
-                worktreePath: null,
-              };
-              if (parsedRemoteRef) {
-                remoteBranch.remoteName = parsedRemoteRef.remoteName;
-              }
-              return remoteBranch;
-            })
-            .toSorted((a, b) => {
-              const aLastCommit = branchLastCommit.get(a.name) ?? 0;
-              const bLastCommit = branchLastCommit.get(b.name) ?? 0;
-              if (aLastCommit !== bLastCommit) return bLastCommit - aLastCommit;
-              return a.name.localeCompare(b.name);
-            })
-        : [];
-
-    const branches = paginateBranches({
-      branches: filterBranchesForListQuery(
-        dedupeRemoteBranchesWithLocalMatches([...localBranches, ...remoteBranches]),
-        input.query,
-      ),
-      cursor: input.cursor,
-      limit: input.limit,
+      return {
+        refs: [...refs.refs],
+        isRepo: true,
+        hasPrimaryRemote: remoteNames.includes("origin"),
+        nextCursor: refs.nextCursor,
+        totalCount: refs.totalCount,
+      };
+    },
+  );
+
+  const createWorktree: GitVcsDriver.GitVcsDriverShape["createWorktree"] = Effect.fn(
+    "createWorktree",
+  )(function* (input) {
+    const targetBranch = input.newRefName ?? input.refName;
+    const sanitizedBranch = targetBranch.replace(/\//g, "-");
+    const repoName = path.basename(input.cwd);
+    const worktreePath = input.path ?? path.join(worktreesDir, repoName, sanitizedBranch);
+    const args = input.newRefName
+      ? ["worktree", "add", "-b", input.newRefName, worktreePath, input.refName]
+      : ["worktree", "add", worktreePath, input.refName];
+
+    yield* executeGit("GitVcsDriver.createWorktree", input.cwd, args, {
+      fallbackErrorMessage: "git worktree add failed",
     });
 
     return {
-      branches: [...branches.branches],
-      isRepo: true,
-      hasOriginRemote: remoteNames.includes("origin"),
-      nextCursor: branches.nextCursor,
-      totalCount: branches.totalCount,
+      worktree: {
+        path: worktreePath,
+        refName: targetBranch,
+      },
     };
   });
 
-  const createWorktree: GitCoreShape["createWorktree"] = Effect.fn("createWorktree")(
-    function* (input) {
-      const targetBranch = input.newBranch ?? input.branch;
-      const sanitizedBranch = targetBranch.replace(/\//g, "-");
-      const repoName = path.basename(input.cwd);
-      const worktreePath = input.path ?? path.join(worktreesDir, repoName, sanitizedBranch);
-      const args = input.newBranch
-        ? ["worktree", "add", "-b", input.newBranch, worktreePath, input.branch]
-        : ["worktree", "add", worktreePath, input.branch];
-
-      yield* executeGit("GitCore.createWorktree", input.cwd, args, {
-        fallbackErrorMessage: "git worktree add failed",
-      });
-
-      return {
-        worktree: {
-          path: worktreePath,
-          branch: targetBranch,
+  const fetchPullRequestBranch: GitVcsDriver.GitVcsDriverShape["fetchPullRequestBranch"] =
+    Effect.fn("fetchPullRequestBranch")(function* (input) {
+      const remoteName = yield* resolvePrimaryRemoteName(input.cwd);
+      yield* executeGit(
+        "GitVcsDriver.fetchPullRequestBranch",
+        input.cwd,
+        [
+          "fetch",
+          "--quiet",
+          "--no-tags",
+          remoteName,
+          `+refs/pull/${input.prNumber}/head:refs/heads/${input.branch}`,
+        ],
+        {
+          fallbackErrorMessage: "git fetch pull request branch failed",
         },
-      };
-    },
-  );
+      );
+    });
 
-  const fetchPullRequestBranch: GitCoreShape["fetchPullRequestBranch"] = Effect.fn(
-    "fetchPullRequestBranch",
+  const fetchRemoteBranch: GitVcsDriver.GitVcsDriverShape["fetchRemoteBranch"] = Effect.fn(
+    "fetchRemoteBranch",
   )(function* (input) {
-    const remoteName = yield* resolvePrimaryRemoteName(input.cwd);
-    yield* executeGit(
-      "GitCore.fetchPullRequestBranch",
+    yield* runGit("GitVcsDriver.fetchRemoteBranch.fetch", input.cwd, [
+      "fetch",
+      "--quiet",
+      "--no-tags",
+      input.remoteName,
+      `+refs/heads/${input.remoteBranch}:refs/remotes/${input.remoteName}/${input.remoteBranch}`,
+    ]);
+
+    const localBranchAlreadyExists = yield* branchExists(input.cwd, input.localBranch);
+    const targetRef = `${input.remoteName}/${input.remoteBranch}`;
+    yield* runGit(
+      "GitVcsDriver.fetchRemoteBranch.materialize",
       input.cwd,
-      [
-        "fetch",
-        "--quiet",
-        "--no-tags",
-        remoteName,
-        `+refs/pull/${input.prNumber}/head:refs/heads/${input.branch}`,
-      ],
-      {
-        fallbackErrorMessage: "git fetch pull request branch failed",
-      },
+      localBranchAlreadyExists
+        ? ["branch", "--force", input.localBranch, targetRef]
+        : ["branch", input.localBranch, targetRef],
     );
   });
 
-  const fetchRemoteBranch: GitCoreShape["fetchRemoteBranch"] = Effect.fn("fetchRemoteBranch")(
-    function* (input) {
-      yield* runGit("GitCore.fetchRemoteBranch.fetch", input.cwd, [
+  const fetchRemoteTrackingBranch: GitVcsDriver.GitVcsDriverShape["fetchRemoteTrackingBranch"] =
+    Effect.fn("fetchRemoteTrackingBranch")(function* (input) {
+      yield* runGit("GitVcsDriver.fetchRemoteTrackingBranch", input.cwd, [
         "fetch",
         "--quiet",
         "--no-tags",
         input.remoteName,
         `+refs/heads/${input.remoteBranch}:refs/remotes/${input.remoteName}/${input.remoteBranch}`,
       ]);
+    });
 
-      const localBranchAlreadyExists = yield* branchExists(input.cwd, input.localBranch);
-      const targetRef = `${input.remoteName}/${input.remoteBranch}`;
-      yield* runGit(
-        "GitCore.fetchRemoteBranch.materialize",
-        input.cwd,
-        localBranchAlreadyExists
-          ? ["branch", "--force", input.localBranch, targetRef]
-          : ["branch", input.localBranch, targetRef],
-      );
-    },
-  );
-
-  const setBranchUpstream: GitCoreShape["setBranchUpstream"] = (input) =>
-    runGit("GitCore.setBranchUpstream", input.cwd, [
+  const setBranchUpstream: GitVcsDriver.GitVcsDriverShape["setBranchUpstream"] = (input) =>
+    runGit("GitVcsDriver.setBranchUpstream", input.cwd, [
       "branch",
       "--set-upstream-to",
       `${input.remoteName}/${input.remoteBranch}`,
       input.branch,
     ]);
 
-  const removeWorktree: GitCoreShape["removeWorktree"] = Effect.fn("removeWorktree")(
+  const removeWorktree: GitVcsDriver.GitVcsDriverShape["removeWorktree"] = Effect.fn(
+    "removeWorktree",
+  )(function* (input) {
+    const args = ["worktree", "remove"];
+    if (input.force) {
+      args.push("--force");
+    }
+    args.push(input.path);
+    yield* executeGit("GitVcsDriver.removeWorktree", input.cwd, args, {
+      timeoutMs: 15_000,
+      fallbackErrorMessage: "git worktree remove failed",
+    }).pipe(
+      Effect.mapError((error) =>
+        createGitCommandError(
+          "GitVcsDriver.removeWorktree",
+          input.cwd,
+          args,
+          `${commandLabel(args)} failed (cwd: ${input.cwd}): ${error.message}`,
+          error,
+        ),
+      ),
+    );
+  });
+
+  const renameBranch: GitVcsDriver.GitVcsDriverShape["renameBranch"] = Effect.fn("renameBranch")(
     function* (input) {
-      const args = ["worktree", "remove"];
-      if (input.force) {
-        args.push("--force");
+      if (input.oldBranch === input.newBranch) {
+        return { branch: input.newBranch };
       }
-      args.push(input.path);
-      yield* executeGit("GitCore.removeWorktree", input.cwd, args, {
-        timeoutMs: 15_000,
-        fallbackErrorMessage: "git worktree remove failed",
-      }).pipe(
-        Effect.mapError((error) =>
-          createGitCommandError(
-            "GitCore.removeWorktree",
-            input.cwd,
-            args,
-            `${commandLabel(args)} failed (cwd: ${input.cwd}): ${error.message}`,
-            error,
-          ),
-        ),
+      const targetBranch = yield* resolveAvailableBranchName(input.cwd, input.newBranch);
+
+      yield* executeGit(
+        "GitVcsDriver.renameBranch",
+        input.cwd,
+        ["branch", "-m", "--", input.oldBranch, targetBranch],
+        {
+          timeoutMs: 10_000,
+          fallbackErrorMessage: "git branch rename failed",
+        },
       );
+
+      return { branch: targetBranch };
     },
   );
 
-  const renameBranch: GitCoreShape["renameBranch"] = Effect.fn("renameBranch")(function* (input) {
-    if (input.oldBranch === input.newBranch) {
-      return { branch: input.newBranch };
-    }
-    const targetBranch = yield* resolveAvailableBranchName(input.cwd, input.newBranch);
-
-    yield* executeGit(
-      "GitCore.renameBranch",
-      input.cwd,
-      ["branch", "-m", "--", input.oldBranch, targetBranch],
-      {
-        timeoutMs: 10_000,
-        fallbackErrorMessage: "git branch rename failed",
-      },
-    );
-
-    return { branch: targetBranch };
-  });
-
-  const checkoutBranch: GitCoreShape["checkoutBranch"] = Effect.fn("checkoutBranch")(
+  const switchRef: GitVcsDriver.GitVcsDriverShape["switchRef"] = Effect.fn("switchRef")(
     function* (input) {
       const [localInputExists, remoteExists] = yield* Effect.all(
         [
           executeGit(
-            "GitCore.checkoutBranch.localInputExists",
+            "GitVcsDriver.switchRef.localInputExists",
             input.cwd,
-            ["show-ref", "--verify", "--quiet", `refs/heads/${input.branch}`],
+            ["show-ref", "--verify", "--quiet", `refs/heads/${input.refName}`],
             {
               timeoutMs: 5_000,
               allowNonZeroExit: true,
             },
-          ).pipe(Effect.map((result) => result.code === 0)),
+          ).pipe(Effect.map((result) => result.exitCode === 0)),
           executeGit(
-            "GitCore.checkoutBranch.remoteExists",
+            "GitVcsDriver.switchRef.remoteExists",
             input.cwd,
-            ["show-ref", "--verify", "--quiet", `refs/remotes/${input.branch}`],
+            ["show-ref", "--verify", "--quiet", `refs/remotes/${input.refName}`],
             {
               timeoutMs: 5_000,
               allowNonZeroExit: true,
             },
-          ).pipe(Effect.map((result) => result.code === 0)),
+          ).pipe(Effect.map((result) => result.exitCode === 0)),
         ],
         { concurrency: "unbounded" },
       );
 
       const localTrackingBranch = remoteExists
         ? yield* executeGit(
-            "GitCore.checkoutBranch.localTrackingBranch",
+            "GitVcsDriver.switchRef.localTrackingBranch",
             input.cwd,
             ["for-each-ref", "--format=%(refname:short)\t%(upstream:short)", "refs/heads"],
             {
@@ -2096,71 +2034,73 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
             },
           ).pipe(
             Effect.map((result) =>
-              result.code === 0
-                ? parseTrackingBranchByUpstreamRef(result.stdout, input.branch)
+              result.exitCode === 0
+                ? parseTrackingBranchByUpstreamRef(result.stdout, input.refName)
                 : null,
             ),
           )
         : null;
 
-      const localTrackedBranchCandidate = deriveLocalBranchNameFromRemoteRef(input.branch);
+      const localTrackedBranchCandidate = deriveLocalBranchNameFromRemoteRef(input.refName);
       const localTrackedBranchTargetExists =
         remoteExists && localTrackedBranchCandidate
           ? yield* executeGit(
-              "GitCore.checkoutBranch.localTrackedBranchTargetExists",
+              "GitVcsDriver.switchRef.localTrackedBranchTargetExists",
               input.cwd,
               ["show-ref", "--verify", "--quiet", `refs/heads/${localTrackedBranchCandidate}`],
               {
                 timeoutMs: 5_000,
                 allowNonZeroExit: true,
               },
-            ).pipe(Effect.map((result) => result.code === 0))
+            ).pipe(Effect.map((result) => result.exitCode === 0))
           : false;
 
       const checkoutArgs = localInputExists
-        ? ["checkout", input.branch]
+        ? ["checkout", input.refName]
         : remoteExists && !localTrackingBranch && localTrackedBranchTargetExists
-          ? ["checkout", input.branch]
+          ? ["checkout", input.refName]
           : remoteExists && !localTrackingBranch
-            ? ["checkout", "--track", input.branch]
+            ? ["checkout", "--track", input.refName]
             : remoteExists && localTrackingBranch
               ? ["checkout", localTrackingBranch]
-              : ["checkout", input.branch];
+              : ["checkout", input.refName];
 
-      yield* executeGit("GitCore.checkoutBranch.checkout", input.cwd, checkoutArgs, {
+      yield* executeGit("GitVcsDriver.switchRef.checkout", input.cwd, checkoutArgs, {
         timeoutMs: 10_000,
         fallbackErrorMessage: "git checkout failed",
       });
 
-      const branch = yield* runGitStdout("GitCore.checkoutBranch.currentBranch", input.cwd, [
+      const refName = yield* runGitStdout("GitVcsDriver.switchRef.currentBranch", input.cwd, [
         "branch",
         "--show-current",
       ]).pipe(Effect.map((stdout) => stdout.trim() || null));
 
-      return { branch };
+      return { refName };
     },
   );
 
-  const createBranch: GitCoreShape["createBranch"] = Effect.fn("createBranch")(function* (input) {
-    yield* executeGit("GitCore.createBranch", input.cwd, ["branch", input.branch], {
-      timeoutMs: 10_000,
-      fallbackErrorMessage: "git branch create failed",
-    });
-    if (input.checkout) {
-      yield* checkoutBranch({ cwd: input.cwd, branch: input.branch });
-    }
+  const createRef: GitVcsDriver.GitVcsDriverShape["createRef"] = Effect.fn("createRef")(
+    function* (input) {
+      yield* executeGit("GitVcsDriver.createRef", input.cwd, ["branch", input.refName], {
+        timeoutMs: 10_000,
+        fallbackErrorMessage: "git branch create failed",
+      });
+      if (input.switchRef) {
+        yield* switchRef({ cwd: input.cwd, refName: input.refName });
+      }
 
-    return { branch: input.branch };
-  });
+      return { refName: input.refName };
+    },
+  );
 
-  const initRepo: GitCoreShape["initRepo"] = (input) =>
-    executeGit("GitCore.initRepo", input.cwd, ["init"], {
+  const initRepo: GitVcsDriver.GitVcsDriverShape["initRepo"] = (input) =>
+    executeGit("GitVcsDriver.initRepo", input.cwd, ["init"], {
       timeoutMs: 10_000,
       fallbackErrorMessage: "git init failed",
     }).pipe(Effect.asVoid);
 
-  const listLocalBranchNames: GitCoreShape["listLocalBranchNames"] = (cwd) =>
-    runGitStdout("GitCore.listLocalBranchNames", cwd, [
+  const listLocalBranchNames: GitVcsDriver.GitVcsDriverShape["listLocalBranchNames"] = (cwd) =>
+    runGitStdout("GitVcsDriver.listLocalBranchNames", cwd, [
       "branch",
       "--list",
       "--no-column",
@@ -2174,7 +2114,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       ),
     );
 
-  return {
+  return GitVcsDriver.GitVcsDriver.of({
     execute,
     status,
     statusDetails,
@@ -2185,22 +2125,19 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
     pullCurrentBranch,
     readRangeContext,
     readConfigValue,
-    isInsideWorkTree,
-    listWorkspaceFiles,
-    filterIgnoredPaths,
-    listBranches,
+    listRefs,
     createWorktree,
     fetchPullRequestBranch,
     ensureRemote,
+    resolvePrimaryRemoteName,
     fetchRemoteBranch,
+    fetchRemoteTrackingBranch,
     setBranchUpstream,
     removeWorktree,
     renameBranch,
-    createBranch,
-    checkoutBranch,
+    createRef,
+    switchRef,
     initRepo,
     listLocalBranchNames,
-  } satisfies GitCoreShape;
+  });
 });
-
-export const GitCoreLive = Layer.effect(GitCore, makeGitCore());
diff --git a/apps/server/src/vcs/VcsDriver.ts b/apps/server/src/vcs/VcsDriver.ts
new file mode 100644
index 00000000000..9e6a6a4021c
--- /dev/null
+++ b/apps/server/src/vcs/VcsDriver.ts
@@ -0,0 +1,72 @@
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+
+import type {
+  VcsDriverCapabilities,
+  VcsError,
+  VcsInitInput,
+  VcsListRemotesResult,
+  VcsListWorkspaceFilesResult,
+  VcsRepositoryIdentity,
+} from "@t3tools/contracts";
+import { CheckpointRef } from "@t3tools/contracts";
+import * as VcsProcess from "./VcsProcess.ts";
+
+export interface VcsCaptureCheckpointInput {
+  readonly cwd: string;
+  readonly checkpointRef: CheckpointRef;
+}
+
+export interface VcsRestoreCheckpointInput {
+  readonly cwd: string;
+  readonly checkpointRef: CheckpointRef;
+  readonly fallbackToHead?: boolean;
+}
+
+export interface VcsDiffCheckpointsInput {
+  readonly cwd: string;
+  readonly fromCheckpointRef: CheckpointRef;
+  readonly toCheckpointRef: CheckpointRef;
+  readonly fallbackFromToHead?: boolean;
+  readonly ignoreWhitespace: boolean;
+}
+
+export interface VcsDeleteCheckpointRefsInput {
+  readonly cwd: string;
+  readonly checkpointRefs: ReadonlyArray<CheckpointRef>;
+}
+
+export interface VcsCheckpointOps {
+  readonly captureCheckpoint: (input: VcsCaptureCheckpointInput) => Effect.Effect<void, VcsError>;
+  readonly hasCheckpointRef: (
+    input: Omit<VcsRestoreCheckpointInput, "fallbackToHead">,
+  ) => Effect.Effect<boolean, VcsError>;
+  readonly restoreCheckpoint: (
+    input: VcsRestoreCheckpointInput,
+  ) => Effect.Effect<boolean, VcsError>;
+  readonly diffCheckpoints: (input: VcsDiffCheckpointsInput) => Effect.Effect<string, VcsError>;
+  readonly deleteCheckpointRefs: (
+    input: VcsDeleteCheckpointRefsInput,
+  ) => Effect.Effect<void, VcsError>;
+}
+
+export interface VcsDriverShape {
+  readonly capabilities: VcsDriverCapabilities;
+  readonly execute: (
+    input: Omit<VcsProcess.VcsProcessInput, "command">,
+  ) => Effect.Effect<VcsProcess.VcsProcessOutput, VcsError>;
+  readonly checkpoints?: VcsCheckpointOps;
+  readonly detectRepository: (cwd: string) => Effect.Effect<VcsRepositoryIdentity | null, VcsError>;
+  readonly isInsideWorkTree: (cwd: string) => Effect.Effect<boolean, VcsError>;
+  readonly listWorkspaceFiles: (
+    cwd: string,
+  ) => Effect.Effect<VcsListWorkspaceFilesResult, VcsError>;
+  readonly listRemotes: (cwd: string) => Effect.Effect<VcsListRemotesResult, VcsError>;
+  readonly filterIgnoredPaths: (
+    cwd: string,
+    relativePaths: ReadonlyArray<string>,
+  ) => Effect.Effect<ReadonlyArray<string>, VcsError>;
+  readonly initRepository: (input: VcsInitInput) => Effect.Effect<void, VcsError>;
+}
+
+export class VcsDriver extends Context.Service<VcsDriver, VcsDriverShape>()("t3/vcs/VcsDriver") {}
diff --git a/apps/server/src/vcs/VcsDriverRegistry.test.ts b/apps/server/src/vcs/VcsDriverRegistry.test.ts
new file mode 100644
index 00000000000..03c09c16be8
--- /dev/null
+++ b/apps/server/src/vcs/VcsDriverRegistry.test.ts
@@ -0,0 +1,95 @@
+import { assert, it, describe } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as VcsProcess from "./VcsProcess.ts";
+import * as VcsProjectConfig from "./VcsProjectConfig.ts";
+import * as VcsDriverRegistry from "./VcsDriverRegistry.ts";
+
+const processOutput = (stdout: string): VcsProcess.VcsProcessOutput => ({
+  exitCode: ChildProcessSpawner.ExitCode(0),
+  stdout,
+  stderr: "",
+  stdoutTruncated: false,
+  stderrTruncated: false,
+});
+
+const normalizeGitArgs = (args: ReadonlyArray<string>): ReadonlyArray<string> =>
+  args[0] === "-C" && args.length >= 2 ? args.slice(2) : args;
+
+describe("VcsDriverRegistry", () => {
+  it.effect("routes directly by VCS driver kind for non-repository workflows", () => {
+    const layer = Layer.effect(VcsDriverRegistry.VcsDriverRegistry, VcsDriverRegistry.make()).pipe(
+      Layer.provide(NodeServices.layer),
+      Layer.provide(
+        Layer.mock(VcsProjectConfig.VcsProjectConfig)({
+          resolveKind: (input) => Effect.succeed(input.requestedKind ?? "auto"),
+        }),
+      ),
+      Layer.provide(
+        Layer.mock(VcsProcess.VcsProcess)({
+          run: () => Effect.succeed(processOutput("")),
+        }),
+      ),
+    );
+
+    return Effect.gen(function* () {
+      const registry = yield* VcsDriverRegistry.VcsDriverRegistry;
+      const driver = yield* registry.get("git");
+
+      assert.strictEqual(driver.capabilities.kind, "git");
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.effect("caches repository detection for repeated resolves in the same cwd and kind", () => {
+    const calls: VcsProcess.VcsProcessInput[] = [];
+    const layer = Layer.effect(VcsDriverRegistry.VcsDriverRegistry, VcsDriverRegistry.make()).pipe(
+      Layer.provide(NodeServices.layer),
+      Layer.provide(
+        Layer.mock(VcsProjectConfig.VcsProjectConfig)({
+          resolveKind: (input) => Effect.succeed(input.requestedKind ?? "auto"),
+        }),
+      ),
+      Layer.provide(
+        Layer.mock(VcsProcess.VcsProcess)({
+          run: (input) =>
+            Effect.sync(() => {
+              calls.push(input);
+              const normalizedArgs =
+                input.args[0] === "-C" && input.args.length >= 2 ? input.args.slice(2) : input.args;
+              const command = normalizedArgs.join(" ");
+              if (command === "rev-parse --is-inside-work-tree") {
+                return processOutput("true\n");
+              }
+              if (command === "rev-parse --show-toplevel") {
+                return processOutput("/repo\n");
+              }
+              if (command === "rev-parse --git-common-dir") {
+                return processOutput("/repo/.git\n");
+              }
+              return processOutput("");
+            }),
+        }),
+      ),
+    );
+
+    return Effect.gen(function* () {
+      const registry = yield* VcsDriverRegistry.VcsDriverRegistry;
+      const first = yield* registry.resolve({ cwd: "/repo", requestedKind: "git" });
+      const second = yield* registry.resolve({ cwd: "/repo", requestedKind: "git" });
+
+      assert.equal(first.repository.rootPath, "/repo");
+      assert.equal(second.repository.rootPath, "/repo");
+      assert.deepStrictEqual(
+        calls.map((call) => normalizeGitArgs(call.args).join(" ")),
+        [
+          "rev-parse --is-inside-work-tree",
+          "rev-parse --show-toplevel",
+          "rev-parse --git-common-dir",
+        ],
+      );
+    }).pipe(Effect.provide(layer));
+  });
+});
diff --git a/apps/server/src/vcs/VcsDriverRegistry.ts b/apps/server/src/vcs/VcsDriverRegistry.ts
new file mode 100644
index 00000000000..22868855737
--- /dev/null
+++ b/apps/server/src/vcs/VcsDriverRegistry.ts
@@ -0,0 +1,160 @@
+import * as Cache from "effect/Cache";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+
+import type { VcsDriverKind, VcsError, VcsRepositoryIdentity } from "@t3tools/contracts";
+import { VcsUnsupportedOperationError } from "@t3tools/contracts";
+import * as GitVcsDriver from "./GitVcsDriver.ts";
+import * as VcsProjectConfig from "./VcsProjectConfig.ts";
+import * as VcsDriver from "./VcsDriver.ts";
+
+const DETECTION_CACHE_CAPACITY = 2_048;
+const DETECTION_CACHE_TTL = Duration.seconds(2);
+
+export interface VcsDriverResolveInput {
+  readonly cwd: string;
+  readonly requestedKind?: VcsDriverKind | "auto";
+}
+
+export interface VcsDriverHandle {
+  readonly kind: VcsDriverKind;
+  readonly repository: VcsRepositoryIdentity;
+  readonly driver: VcsDriver.VcsDriverShape;
+}
+
+export interface VcsDriverRegistryShape {
+  readonly get: (kind: VcsDriverKind) => Effect.Effect<VcsDriver.VcsDriverShape, VcsError>;
+  readonly detect: (
+    input: VcsDriverResolveInput,
+  ) => Effect.Effect<VcsDriverHandle | null, VcsError>;
+  readonly resolve: (input: VcsDriverResolveInput) => Effect.Effect<VcsDriverHandle, VcsError>;
+}
+
+export class VcsDriverRegistry extends Context.Service<VcsDriverRegistry, VcsDriverRegistryShape>()(
+  "t3/vcs/VcsDriverRegistry",
+) {}
+
+const unsupported = (operation: string, kind: VcsDriverKind, detail: string) =>
+  new VcsUnsupportedOperationError({
+    operation,
+    kind,
+    detail,
+  });
+
+function detectionCacheKey(input: {
+  readonly cwd: string;
+  readonly requestedKind: VcsDriverKind | "auto";
+}): string {
+  return `${input.requestedKind}\0${input.cwd}`;
+}
+
+function parseDetectionCacheKey(key: string): {
+  readonly cwd: string;
+  readonly requestedKind: VcsDriverKind | "auto";
+} {
+  const separatorIndex = key.indexOf("\0");
+  if (separatorIndex === -1) {
+    return {
+      cwd: key,
+      requestedKind: "auto",
+    };
+  }
+  return {
+    requestedKind: key.slice(0, separatorIndex) as VcsDriverKind | "auto",
+    cwd: key.slice(separatorIndex + 1),
+  };
+}
+
+export const make = Effect.fn("makeVcsDriverRegistry")(function* () {
+  const projectConfig = yield* VcsProjectConfig.VcsProjectConfig;
+  const git = yield* GitVcsDriver.makeVcsDriverShape();
+  const drivers: Partial<Record<VcsDriverKind, VcsDriver.VcsDriverShape>> = {
+    git,
+  };
+
+  const get: VcsDriverRegistryShape["get"] = (kind) => {
+    const driver = drivers[kind];
+    if (!driver) {
+      return Effect.fail(
+        unsupported("VcsDriverRegistry.get", kind, `No ${kind} VCS driver is registered.`),
+      );
+    }
+    return Effect.succeed(driver);
+  };
+
+  const detectWithDriver = Effect.fn("VcsDriverRegistry.detectWithDriver")(function* (
+    kind: VcsDriverKind,
+    driver: VcsDriver.VcsDriverShape,
+    cwd: string,
+  ) {
+    const repository = yield* driver.detectRepository(cwd);
+    if (!repository) {
+      return null;
+    }
+    return {
+      kind,
+      repository,
+      driver,
+    } satisfies VcsDriverHandle;
+  });
+
+  const detectResolvedKind = Effect.fn("VcsDriverRegistry.detectResolvedKind")(function* (input: {
+    readonly cwd: string;
+    readonly requestedKind: VcsDriverKind | "auto";
+  }) {
+    const requestedKind = input.requestedKind;
+
+    if (requestedKind !== "auto" && requestedKind !== "unknown") {
+      const driver = yield* get(requestedKind);
+      return yield* detectWithDriver(requestedKind, driver, input.cwd);
+    }
+
+    return yield* detectWithDriver("git", git, input.cwd);
+  });
+
+  const detectionCache = yield* Cache.makeWith<string, VcsDriverHandle | null, VcsError>(
+    (key) => detectResolvedKind(parseDetectionCacheKey(key)),
+    {
+      capacity: DETECTION_CACHE_CAPACITY,
+      timeToLive: (exit) => (Exit.isSuccess(exit) ? DETECTION_CACHE_TTL : Duration.zero),
+    },
+  );
+
+  const detect: VcsDriverRegistryShape["detect"] = Effect.fn("VcsDriverRegistry.detect")(
+    function* (input) {
+      const requestedKind = yield* projectConfig.resolveKind(input);
+      return yield* Cache.get(detectionCache, detectionCacheKey({ cwd: input.cwd, requestedKind }));
+    },
+  );
+
+  const resolve: VcsDriverRegistryShape["resolve"] = Effect.fn("VcsDriverRegistry.resolve")(
+    function* (input) {
+      const detected = yield* detect(input);
+      if (detected) {
+        return detected;
+      }
+
+      const requestedKind = input.requestedKind ?? "auto";
+      return yield* unsupported(
+        "VcsDriverRegistry.resolve",
+        requestedKind === "auto" ? "unknown" : requestedKind,
+        requestedKind === "auto"
+          ? `No supported VCS repository was detected at ${input.cwd}.`
+          : `No ${requestedKind} repository was detected at ${input.cwd}.`,
+      );
+    },
+  );
+
+  return VcsDriverRegistry.of({
+    get,
+    detect,
+    resolve,
+  });
+});
+
+export const layer = Layer.effect(VcsDriverRegistry, make()).pipe(
+  Layer.provide(VcsProjectConfig.layer),
+);
diff --git a/apps/server/src/vcs/VcsProcess.test.ts b/apps/server/src/vcs/VcsProcess.test.ts
new file mode 100644
index 00000000000..b58d64e435a
--- /dev/null
+++ b/apps/server/src/vcs/VcsProcess.test.ts
@@ -0,0 +1,138 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import { TestClock } from "effect/testing";
+
+import { VcsProcessExitError, VcsProcessTimeoutError } from "@t3tools/contracts";
+import * as VcsProcess from "./VcsProcess.ts";
+
+const run = (input: VcsProcess.VcsProcessInput) =>
+  Effect.gen(function* () {
+    const process = yield* VcsProcess.VcsProcess;
+    return yield* process.run(input);
+  });
+
+const liveLayer = VcsProcess.layer.pipe(Layer.provide(NodeServices.layer));
+
+const provideLive = <A, E, R>(effect: Effect.Effect<A, E, R | VcsProcess.VcsProcess>) =>
+  effect.pipe(Effect.provide(liveLayer));
+
+describe("VcsProcess.run", () => {
+  it.effect("collects stdout", () =>
+    Effect.gen(function* () {
+      const result = yield* run({
+        operation: "test.stdout",
+        command: "node",
+        args: ["-e", "process.stdout.write('hello')"],
+        cwd: process.cwd(),
+      });
+
+      expect(result.stdout).toBe("hello");
+      expect(result.stderr).toBe("");
+      expect(result.stdoutTruncated).toBe(false);
+      expect(result.stderrTruncated).toBe(false);
+    }).pipe(provideLive),
+  );
+
+  it.effect("writes stdin before waiting for exit", () =>
+    Effect.gen(function* () {
+      const result = yield* run({
+        operation: "test.stdin",
+        command: "node",
+        args: [
+          "-e",
+          [
+            "process.stdin.setEncoding('utf8');",
+            "let data='';",
+            "process.stdin.on('data', chunk => { data += chunk; });",
+            "process.stdin.on('end', () => { process.stdout.write(data); });",
+          ].join(""),
+        ],
+        cwd: process.cwd(),
+        stdin: "stdin payload",
+      });
+
+      expect(result.stdout).toBe("stdin payload");
+    }).pipe(provideLive),
+  );
+
+  it.effect("fails with VcsProcessExitError for non-zero exits by default", () =>
+    Effect.gen(function* () {
+      const error = yield* run({
+        operation: "test.exit",
+        command: "node",
+        args: ["-e", "process.stderr.write('boom'); process.exit(2)"],
+        cwd: process.cwd(),
+      }).pipe(Effect.flip);
+
+      expect(error).toBeInstanceOf(VcsProcessExitError);
+    }).pipe(provideLive),
+  );
+
+  it.effect("returns output when non-zero exits are allowed", () =>
+    Effect.gen(function* () {
+      const result = yield* run({
+        operation: "test.allowed-exit",
+        command: "node",
+        args: ["-e", "process.stderr.write('boom'); process.exit(2)"],
+        cwd: process.cwd(),
+        allowNonZeroExit: true,
+      });
+
+      expect(result.exitCode).toBe(2);
+      expect(result.stderr).toBe("boom");
+    }).pipe(provideLive),
+  );
+
+  it.effect("truncates output and appends the marker when requested", () =>
+    Effect.gen(function* () {
+      const result = yield* run({
+        operation: "test.truncate-marker",
+        command: "node",
+        args: ["-e", "process.stdout.write('x'.repeat(2048))"],
+        cwd: process.cwd(),
+        maxOutputBytes: 128,
+        appendTruncationMarker: true,
+      });
+
+      expect(result.stdoutTruncated).toBe(true);
+      expect(result.stdout).toContain("[truncated]");
+      expect(result.stderrTruncated).toBe(false);
+    }).pipe(provideLive),
+  );
+
+  it.effect("truncates without the marker when truncation markers are disabled", () =>
+    Effect.gen(function* () {
+      const result = yield* run({
+        operation: "test.truncate-silent",
+        command: "node",
+        args: ["-e", "process.stdout.write('x'.repeat(2048))"],
+        cwd: process.cwd(),
+        maxOutputBytes: 128,
+      });
+
+      expect(result.stdoutTruncated).toBe(true);
+      expect(result.stdout).not.toContain("[truncated]");
+    }).pipe(provideLive),
+  );
+
+  it.effect("fails with VcsProcessTimeoutError on timeout", () =>
+    Effect.gen(function* () {
+      const errorFiber = yield* run({
+        operation: "test.timeout",
+        command: "node",
+        args: ["-e", "setTimeout(() => {}, 5000)"],
+        cwd: process.cwd(),
+        timeoutMs: 50,
+      }).pipe(Effect.flip, Effect.forkScoped);
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(50));
+      const error = yield* Fiber.join(errorFiber);
+
+      expect(error).toBeInstanceOf(VcsProcessTimeoutError);
+    }).pipe(provideLive),
+  );
+});
diff --git a/apps/server/src/vcs/VcsProcess.ts b/apps/server/src/vcs/VcsProcess.ts
new file mode 100644
index 00000000000..a4caf7d3230
--- /dev/null
+++ b/apps/server/src/vcs/VcsProcess.ts
@@ -0,0 +1,122 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  VcsOutputDecodeError,
+  type VcsError,
+  VcsProcessExitError,
+  VcsProcessSpawnError,
+  VcsProcessTimeoutError,
+} from "@t3tools/contracts";
+import { ProcessRunner, layer as ProcessRunnerLive } from "../processRunner.ts";
+import * as Match from "effect/Match";
+
+export interface VcsProcessInput {
+  readonly operation: string;
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd: string;
+  readonly spawnCwd?: string;
+  readonly stdin?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly allowNonZeroExit?: boolean;
+  readonly timeoutMs?: number;
+  readonly maxOutputBytes?: number;
+  readonly appendTruncationMarker?: boolean;
+}
+
+export interface VcsProcessOutput {
+  readonly exitCode: ChildProcessSpawner.ExitCode;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+}
+
+export interface VcsProcessShape {
+  readonly run: (input: VcsProcessInput) => Effect.Effect<VcsProcessOutput, VcsError>;
+}
+
+export class VcsProcess extends Context.Service<VcsProcess, VcsProcessShape>()(
+  "t3/vcs/VcsProcess",
+) {}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
+const OUTPUT_TRUNCATED_MARKER = "\n\n[truncated]";
+
+function commandLabel(command: string, args: ReadonlyArray<string>): string {
+  return [command, ...args].join(" ");
+}
+
+export const make = Effect.fn("makeVcsProcess")(function* () {
+  const processRunner = yield* ProcessRunner;
+
+  const run = Effect.fn("VcsProcess.run")(function* (input: VcsProcessInput) {
+    const label = commandLabel(input.command, input.args);
+    const baseError = {
+      operation: input.operation,
+      command: label,
+      cwd: input.cwd,
+    };
+
+    const result = yield* processRunner
+      .run({
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd,
+        ...(input.spawnCwd !== undefined ? { spawnCwd: input.spawnCwd } : {}),
+        ...(input.stdin !== undefined ? { stdin: input.stdin } : {}),
+        ...(input.env !== undefined ? { env: input.env } : {}),
+        timeout: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxOutputBytes: input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+        outputMode: "truncate",
+        truncatedMarker: input.appendTruncationMarker ? OUTPUT_TRUNCATED_MARKER : "",
+        timeoutBehavior: "error",
+      })
+      .pipe(
+        Effect.mapError(
+          Match.valueTags({
+            ProcessSpawnError: (error) =>
+              VcsProcessSpawnError.fromProcessSpawnError(baseError, error),
+            ProcessOutputLimitError: (error) =>
+              VcsOutputDecodeError.fromProcessOutputLimitError(baseError, error),
+            ProcessTimeoutError: (error) =>
+              VcsProcessTimeoutError.fromProcessTimeoutError(baseError, error),
+            ProcessStdinError: (error) =>
+              VcsOutputDecodeError.fromProcessStdinError(baseError, error),
+            ProcessReadError: (error) =>
+              VcsOutputDecodeError.fromProcessReadError(baseError, error),
+          }),
+        ),
+      );
+
+    if (result.code === null) {
+      return yield* VcsOutputDecodeError.missingExitCode(baseError);
+    }
+
+    if (!input.allowNonZeroExit && result.code !== 0) {
+      return yield* new VcsProcessExitError({
+        operation: input.operation,
+        command: label,
+        cwd: input.cwd,
+        exitCode: result.code,
+        detail: result.stderr.trim() || `${label} exited with code ${result.code}.`,
+      });
+    }
+
+    return {
+      exitCode: result.code,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      stdoutTruncated: result.stdoutTruncated,
+      stderrTruncated: result.stderrTruncated,
+    } satisfies VcsProcessOutput;
+  });
+
+  return VcsProcess.of({ run });
+});
+
+export const layer = Layer.effect(VcsProcess, make()).pipe(Layer.provide(ProcessRunnerLive));
diff --git a/apps/server/src/vcs/VcsProjectConfig.test.ts b/apps/server/src/vcs/VcsProjectConfig.test.ts
new file mode 100644
index 00000000000..aac4beb7e32
--- /dev/null
+++ b/apps/server/src/vcs/VcsProjectConfig.test.ts
@@ -0,0 +1,70 @@
+import { assert, it, describe } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+
+import * as VcsProjectConfig from "./VcsProjectConfig.ts";
+
+const TestLayer = VcsProjectConfig.layer.pipe(
+  Layer.provide(NodeServices.layer),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+describe("VcsProjectConfig", () => {
+  it.layer(TestLayer)("uses an explicit requested VCS kind before config", (it) => {
+    it.effect("returns the requested kind", () =>
+      Effect.gen(function* () {
+        const config = yield* VcsProjectConfig.VcsProjectConfig;
+        const kind = yield* config.resolveKind({
+          cwd: "/repo",
+          requestedKind: "jj",
+        });
+
+        assert.equal(kind, "jj");
+      }),
+    );
+  });
+
+  it.layer(TestLayer)("discovers .t3code/vcs.json from nested workspaces", (it) => {
+    it.effect("returns the configured kind", () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-vcs-config-test-",
+        });
+        const configDir = path.join(root, ".t3code");
+        const nested = path.join(root, "packages", "app");
+        yield* fileSystem.makeDirectory(configDir, { recursive: true });
+        yield* fileSystem.makeDirectory(nested, { recursive: true });
+        yield* fileSystem.writeFileString(
+          path.join(configDir, "vcs.json"),
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
+          JSON.stringify({ vcs: { kind: "jj" } }),
+        );
+
+        const config = yield* VcsProjectConfig.VcsProjectConfig;
+        const kind = yield* config.resolveKind({ cwd: nested });
+
+        assert.equal(kind, "jj");
+      }),
+    );
+  });
+
+  it.layer(TestLayer)("falls back to auto when no config exists", (it) => {
+    it.effect("returns auto", () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const root = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-vcs-config-test-",
+        });
+        const config = yield* VcsProjectConfig.VcsProjectConfig;
+        const kind = yield* config.resolveKind({ cwd: root });
+
+        assert.equal(kind, "auto");
+      }),
+    );
+  });
+});
diff --git a/apps/server/src/vcs/VcsProjectConfig.ts b/apps/server/src/vcs/VcsProjectConfig.ts
new file mode 100644
index 00000000000..3e5ee2347ce
--- /dev/null
+++ b/apps/server/src/vcs/VcsProjectConfig.ts
@@ -0,0 +1,123 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+
+import { VcsDriverKind, type VcsDriverKind as VcsDriverKindType } from "@t3tools/contracts";
+
+const ProjectVcsConfig = Schema.Struct({
+  vcs: Schema.optional(
+    Schema.Struct({
+      kind: Schema.optional(VcsDriverKind),
+    }),
+  ),
+  vcsKind: Schema.optional(VcsDriverKind),
+});
+const isProjectVcsConfig = Schema.is(ProjectVcsConfig);
+
+interface ProjectVcsConfigFile {
+  readonly vcs?:
+    | {
+        readonly kind?: VcsDriverKindType | undefined;
+      }
+    | undefined;
+  readonly vcsKind?: VcsDriverKindType | undefined;
+}
+
+export interface VcsProjectConfigResolveInput {
+  readonly cwd: string;
+  readonly requestedKind?: VcsDriverKindType | "auto";
+}
+
+export interface VcsProjectConfigShape {
+  readonly resolveKind: (
+    input: VcsProjectConfigResolveInput,
+  ) => Effect.Effect<VcsDriverKindType | "auto">;
+}
+
+export class VcsProjectConfig extends Context.Service<VcsProjectConfig, VcsProjectConfigShape>()(
+  "t3/vcs/VcsProjectConfig",
+) {}
+
+function configuredKind(config: ProjectVcsConfigFile): VcsDriverKindType | "auto" {
+  return config.vcs?.kind ?? config.vcsKind ?? "auto";
+}
+
+function parseConfig(raw: string): ProjectVcsConfigFile | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return isProjectVcsConfig(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export const make = Effect.fn("makeVcsProjectConfig")(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  const findConfigPath = Effect.fn("VcsProjectConfig.findConfigPath")(function* (cwd: string) {
+    let current = cwd;
+    while (true) {
+      const candidate = path.join(current, ".t3code", "vcs.json");
+      if (yield* fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false))) {
+        return candidate;
+      }
+
+      const parent = path.dirname(current);
+      if (parent === current) {
+        return null;
+      }
+      current = parent;
+    }
+  });
+
+  const readConfiguredKind = Effect.fn("VcsProjectConfig.readConfiguredKind")(function* (
+    configPath: string,
+  ) {
+    const raw = yield* fileSystem.readFileString(configPath).pipe(
+      Effect.catch((error) =>
+        Effect.logWarning("failed to read VCS project config", {
+          configPath,
+          error,
+        }).pipe(Effect.as(null)),
+      ),
+    );
+    if (raw === null) {
+      return "auto" as const;
+    }
+
+    const parsed = parseConfig(raw);
+    if (parsed === null) {
+      yield* Effect.logWarning("invalid VCS project config", {
+        configPath,
+      });
+      return "auto" as const;
+    }
+
+    return configuredKind(parsed);
+  });
+
+  const resolveKind: VcsProjectConfigShape["resolveKind"] = Effect.fn(
+    "VcsProjectConfig.resolveKind",
+  )(function* (input) {
+    if (input.requestedKind !== undefined && input.requestedKind !== "auto") {
+      return input.requestedKind;
+    }
+
+    const configPath = yield* findConfigPath(input.cwd);
+    if (configPath === null) {
+      return "auto";
+    }
+
+    return yield* readConfiguredKind(configPath);
+  });
+
+  return VcsProjectConfig.of({
+    resolveKind,
+  });
+});
+
+export const layer = Layer.effect(VcsProjectConfig, make());
diff --git a/apps/server/src/vcs/VcsProvisioningService.test.ts b/apps/server/src/vcs/VcsProvisioningService.test.ts
new file mode 100644
index 00000000000..ba919a5f435
--- /dev/null
+++ b/apps/server/src/vcs/VcsProvisioningService.test.ts
@@ -0,0 +1,97 @@
+import { assert, it } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as VcsDriver from "./VcsDriver.ts";
+import * as VcsDriverRegistry from "./VcsDriverRegistry.ts";
+import * as VcsProvisioningService from "./VcsProvisioningService.ts";
+
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
+
+function makeDriver(calls: string[]): VcsDriver.VcsDriverShape {
+  return {
+    capabilities: {
+      kind: "git",
+      supportsWorktrees: true,
+      supportsBookmarks: false,
+      supportsAtomicSnapshot: false,
+      supportsPushDefaultRemote: true,
+      ignoreClassifier: "native",
+    },
+    execute: () =>
+      Effect.succeed({
+        exitCode: ChildProcessSpawner.ExitCode(0),
+        stdout: "",
+        stderr: "",
+        stdoutTruncated: false,
+        stderrTruncated: false,
+      }),
+    detectRepository: () => Effect.succeed(null),
+    isInsideWorkTree: () => Effect.succeed(false),
+    listWorkspaceFiles: () =>
+      Effect.succeed({
+        paths: [],
+        truncated: false,
+        freshness: {
+          source: "live-local",
+          observedAt: TEST_EPOCH,
+          expiresAt: Option.none(),
+        },
+      }),
+    listRemotes: () =>
+      Effect.succeed({
+        remotes: [],
+        freshness: {
+          source: "live-local",
+          observedAt: TEST_EPOCH,
+          expiresAt: Option.none(),
+        },
+      }),
+    filterIgnoredPaths: (_cwd, relativePaths) => Effect.succeed(relativePaths),
+    initRepository: (input) =>
+      Effect.sync(() => {
+        calls.push(`${input.kind ?? "default"}:${input.cwd}`);
+      }),
+  };
+}
+
+it.effect("routes repository initialization through an explicit VCS driver kind", () => {
+  const calls: string[] = [];
+  const driver = makeDriver(calls);
+  const testLayer = VcsProvisioningService.layer.pipe(
+    Layer.provide(
+      Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
+        get: (kind) => (kind === "git" ? Effect.succeed(driver) : Effect.die("unexpected kind")),
+      }),
+    ),
+  );
+
+  return Effect.gen(function* () {
+    const provisioning = yield* VcsProvisioningService.VcsProvisioningService;
+    yield* provisioning.initRepository({ cwd: "/repo", kind: "git" });
+
+    assert.deepStrictEqual(calls, ["git:/repo"]);
+  }).pipe(Effect.provide(testLayer));
+});
+
+it.effect("defaults repository initialization to Git until callers choose a VCS kind", () => {
+  const calls: string[] = [];
+  const driver = makeDriver(calls);
+  const testLayer = VcsProvisioningService.layer.pipe(
+    Layer.provide(
+      Layer.mock(VcsDriverRegistry.VcsDriverRegistry)({
+        get: (kind) => (kind === "git" ? Effect.succeed(driver) : Effect.die("unexpected kind")),
+      }),
+    ),
+  );
+
+  return Effect.gen(function* () {
+    const provisioning = yield* VcsProvisioningService.VcsProvisioningService;
+    yield* provisioning.initRepository({ cwd: "/repo" });
+
+    assert.deepStrictEqual(calls, ["default:/repo"]);
+  }).pipe(Effect.provide(testLayer));
+});
diff --git a/apps/server/src/vcs/VcsProvisioningService.ts b/apps/server/src/vcs/VcsProvisioningService.ts
new file mode 100644
index 00000000000..38006b4b603
--- /dev/null
+++ b/apps/server/src/vcs/VcsProvisioningService.ts
@@ -0,0 +1,56 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import {
+  type VcsDriverKind,
+  type VcsError,
+  type VcsInitInput,
+  VcsUnsupportedOperationError,
+} from "@t3tools/contracts";
+import * as VcsDriverRegistry from "./VcsDriverRegistry.ts";
+
+export interface VcsProvisioningServiceShape {
+  readonly initRepository: (input: VcsInitInput) => Effect.Effect<void, VcsError>;
+}
+
+export class VcsProvisioningService extends Context.Service<
+  VcsProvisioningService,
+  VcsProvisioningServiceShape
+>()("t3/vcs/VcsProvisioningService") {}
+
+function resolveRequestedKind(
+  kind: VcsDriverKind | undefined,
+): Effect.Effect<VcsDriverKind, VcsUnsupportedOperationError> {
+  if (kind === undefined) {
+    return Effect.succeed("git");
+  }
+  if (kind === "unknown") {
+    return Effect.fail(
+      new VcsUnsupportedOperationError({
+        operation: "VcsProvisioningService.resolveRequestedKind",
+        kind,
+        detail: "A concrete VCS driver kind is required for repository provisioning.",
+      }),
+    );
+  }
+  return Effect.succeed(kind);
+}
+
+export const make = Effect.fn("makeVcsProvisioningService")(function* () {
+  const registry = yield* VcsDriverRegistry.VcsDriverRegistry;
+
+  const initRepository: VcsProvisioningServiceShape["initRepository"] = Effect.fn(
+    "VcsProvisioningService.initRepository",
+  )(function* (input) {
+    const kind = yield* resolveRequestedKind(input.kind);
+    const driver = yield* registry.get(kind);
+    return yield* driver.initRepository(input);
+  });
+
+  return VcsProvisioningService.of({
+    initRepository,
+  });
+});
+
+export const layer = Layer.effect(VcsProvisioningService, make());
diff --git a/apps/server/src/git/Layers/GitStatusBroadcaster.test.ts b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
similarity index 52%
rename from apps/server/src/git/Layers/GitStatusBroadcaster.test.ts
rename to apps/server/src/vcs/VcsStatusBroadcaster.test.ts
index 72a0c24e27b..d47dda29bf0 100644
--- a/apps/server/src/git/Layers/GitStatusBroadcaster.test.ts
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
@@ -1,83 +1,88 @@
-import { assert, it } from "@effect/vitest";
-import { Deferred, Effect, Exit, Layer, Option, Scope, Stream } from "effect";
+import { assert, it, describe } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import type {
-  GitStatusLocalResult,
-  GitStatusRemoteResult,
-  GitStatusResult,
-  GitStatusStreamEvent,
+  VcsStatusLocalResult,
+  VcsStatusRemoteResult,
+  VcsStatusResult,
+  VcsStatusStreamEvent,
 } from "@t3tools/contracts";
-import { describe } from "vitest";
 
-import { GitStatusBroadcaster } from "../Services/GitStatusBroadcaster.ts";
-import { GitStatusBroadcasterLive } from "./GitStatusBroadcaster.ts";
-import { type GitManagerShape, GitManager } from "../Services/GitManager.ts";
+import * as VcsStatusBroadcaster from "./VcsStatusBroadcaster.ts";
+import * as GitWorkflowService from "../git/GitWorkflowService.ts";
 
-const baseLocalStatus: GitStatusLocalResult = {
+const baseLocalStatus: VcsStatusLocalResult = {
   isRepo: true,
-  hostingProvider: {
+  sourceControlProvider: {
     kind: "github",
     name: "GitHub",
     baseUrl: "https://github.com",
   },
-  hasOriginRemote: true,
-  isDefaultBranch: false,
-  branch: "feature/status-broadcast",
+  hasPrimaryRemote: true,
+  isDefaultRef: false,
+  refName: "feature/status-broadcast",
   hasWorkingTreeChanges: false,
   workingTree: { files: [], insertions: 0, deletions: 0 },
 };
 
-const baseRemoteStatus: GitStatusRemoteResult = {
+const baseRemoteStatus: VcsStatusRemoteResult = {
   hasUpstream: true,
   aheadCount: 0,
   behindCount: 0,
   pr: null,
 };
 
-const baseStatus: GitStatusResult = {
+const baseStatus: VcsStatusResult = {
   ...baseLocalStatus,
   ...baseRemoteStatus,
 };
 
 function makeTestLayer(state: {
-  currentLocalStatus: GitStatusLocalResult;
-  currentRemoteStatus: GitStatusRemoteResult | null;
+  currentLocalStatus: VcsStatusLocalResult;
+  currentRemoteStatus: VcsStatusRemoteResult | null;
   localStatusCalls: number;
   remoteStatusCalls: number;
   localInvalidationCalls: number;
   remoteInvalidationCalls: number;
 }) {
-  const gitManager: GitManagerShape = {
-    localStatus: () =>
-      Effect.sync(() => {
-        state.localStatusCalls += 1;
-        return state.currentLocalStatus;
+  return VcsStatusBroadcaster.layer.pipe(
+    Layer.provideMerge(NodeServices.layer),
+    Layer.provide(
+      Layer.mock(GitWorkflowService.GitWorkflowService)({
+        localStatus: () =>
+          Effect.sync(() => {
+            state.localStatusCalls += 1;
+            return state.currentLocalStatus;
+          }),
+        remoteStatus: () =>
+          Effect.sync(() => {
+            state.remoteStatusCalls += 1;
+            return state.currentRemoteStatus;
+          }),
+        invalidateLocalStatus: () =>
+          Effect.sync(() => {
+            state.localInvalidationCalls += 1;
+          }),
+        invalidateRemoteStatus: () =>
+          Effect.sync(() => {
+            state.remoteInvalidationCalls += 1;
+          }),
       }),
-    remoteStatus: () =>
-      Effect.sync(() => {
-        state.remoteStatusCalls += 1;
-        return state.currentRemoteStatus;
-      }),
-    status: () => Effect.die("status should not be called in this test"),
-    invalidateLocalStatus: () =>
-      Effect.sync(() => {
-        state.localInvalidationCalls += 1;
-      }),
-    invalidateRemoteStatus: () =>
-      Effect.sync(() => {
-        state.remoteInvalidationCalls += 1;
-      }),
-    invalidateStatus: () => Effect.die("invalidateStatus should not be called in this test"),
-    resolvePullRequest: () => Effect.die("resolvePullRequest should not be called in this test"),
-    preparePullRequestThread: () =>
-      Effect.die("preparePullRequestThread should not be called in this test"),
-    runStackedAction: () => Effect.die("runStackedAction should not be called in this test"),
-  };
-
-  return GitStatusBroadcasterLive.pipe(Layer.provide(Layer.succeed(GitManager, gitManager)));
+    ),
+  );
 }
 
-describe("GitStatusBroadcasterLive", () => {
-  it.effect("reuses the cached git status across repeated reads", () => {
+describe("VcsStatusBroadcaster", () => {
+  it.effect("reuses the cached VCS status across repeated reads", () => {
     const state = {
       currentLocalStatus: baseLocalStatus,
       currentRemoteStatus: baseRemoteStatus,
@@ -88,7 +93,7 @@ describe("GitStatusBroadcasterLive", () => {
     };
 
     return Effect.gen(function* () {
-      const broadcaster = yield* GitStatusBroadcaster;
+      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
 
       const first = yield* broadcaster.getStatus({ cwd: "/repo" });
       const second = yield* broadcaster.getStatus({ cwd: "/repo" });
@@ -113,12 +118,12 @@ describe("GitStatusBroadcasterLive", () => {
     };
 
     return Effect.gen(function* () {
-      const broadcaster = yield* GitStatusBroadcaster;
+      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
       const initial = yield* broadcaster.getStatus({ cwd: "/repo" });
 
       state.currentLocalStatus = {
         ...baseLocalStatus,
-        branch: "feature/updated-status",
+        refName: "feature/updated-status",
       };
       state.currentRemoteStatus = {
         ...baseRemoteStatus,
@@ -154,12 +159,12 @@ describe("GitStatusBroadcasterLive", () => {
     };
 
     return Effect.gen(function* () {
-      const broadcaster = yield* GitStatusBroadcaster;
+      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
       const initial = yield* broadcaster.getStatus({ cwd: "/repo" });
 
       state.currentLocalStatus = {
         ...baseLocalStatus,
-        branch: "feature/local-only-refresh",
+        refName: "feature/local-only-refresh",
         hasWorkingTreeChanges: true,
       };
 
@@ -179,6 +184,67 @@ describe("GitStatusBroadcasterLive", () => {
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
 
+  it.effect("normalizes symlinked CWDs before cache lookup and workflow calls", () => {
+    const seenCwds: string[] = [];
+    const state = {
+      currentLocalStatus: baseLocalStatus,
+      currentRemoteStatus: baseRemoteStatus,
+      localStatusCalls: 0,
+      remoteStatusCalls: 0,
+      localInvalidationCalls: 0,
+      remoteInvalidationCalls: 0,
+    };
+    const testLayer = VcsStatusBroadcaster.layer.pipe(
+      Layer.provideMerge(NodeServices.layer),
+      Layer.provide(
+        Layer.mock(GitWorkflowService.GitWorkflowService)({
+          localStatus: (input) =>
+            Effect.sync(() => {
+              seenCwds.push(input.cwd);
+              state.localStatusCalls += 1;
+              return state.currentLocalStatus;
+            }),
+          remoteStatus: (input) =>
+            Effect.sync(() => {
+              seenCwds.push(input.cwd);
+              state.remoteStatusCalls += 1;
+              return state.currentRemoteStatus;
+            }),
+          invalidateLocalStatus: () =>
+            Effect.sync(() => {
+              state.localInvalidationCalls += 1;
+            }),
+          invalidateRemoteStatus: () =>
+            Effect.sync(() => {
+              state.remoteInvalidationCalls += 1;
+            }),
+        } satisfies Partial<GitWorkflowService.GitWorkflowServiceShape>),
+      ),
+    );
+
+    return Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const realDir = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-vcs-status-real-",
+      });
+      const linkParent = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-vcs-status-link-",
+      });
+      const linkDir = path.join(linkParent, "repo-link");
+      yield* fileSystem.symlink(realDir, linkDir);
+      const realPath = yield* fileSystem.realPath(realDir);
+
+      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
+      yield* broadcaster.getStatus({ cwd: linkDir });
+      yield* broadcaster.getStatus({ cwd: realDir });
+
+      assert.deepStrictEqual(seenCwds, [realPath, realPath]);
+      assert.equal(state.localStatusCalls, 1);
+      assert.equal(state.remoteStatusCalls, 1);
+    }).pipe(Effect.provide(testLayer));
+  });
+
   it.effect("streams a local snapshot first and remote updates later", () => {
     const state = {
       currentLocalStatus: baseLocalStatus,
@@ -190,9 +256,9 @@ describe("GitStatusBroadcasterLive", () => {
     };
 
     return Effect.gen(function* () {
-      const broadcaster = yield* GitStatusBroadcaster;
-      const snapshotDeferred = yield* Deferred.make<GitStatusStreamEvent>();
-      const remoteUpdatedDeferred = yield* Deferred.make<GitStatusStreamEvent>();
+      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
+      const snapshotDeferred = yield* Deferred.make<VcsStatusStreamEvent>();
+      const remoteUpdatedDeferred = yield* Deferred.make<VcsStatusStreamEvent>();
       yield* Stream.runForEach(broadcaster.streamStatus({ cwd: "/repo" }), (event) => {
         if (event._tag === "snapshot") {
           return Deferred.succeed(snapshotDeferred, event).pipe(Effect.ignore);
@@ -211,14 +277,62 @@ describe("GitStatusBroadcasterLive", () => {
         _tag: "snapshot",
         local: baseLocalStatus,
         remote: null,
-      } satisfies GitStatusStreamEvent);
+      } satisfies VcsStatusStreamEvent);
       assert.deepStrictEqual(remoteUpdated, {
         _tag: "remoteUpdated",
         remote: baseRemoteStatus,
-      } satisfies GitStatusStreamEvent);
+      } satisfies VcsStatusStreamEvent);
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
 
+  it.effect("does not start automatic remote refreshes when disabled", () => {
+    const state = {
+      currentLocalStatus: baseLocalStatus,
+      currentRemoteStatus: baseRemoteStatus,
+      localStatusCalls: 0,
+      remoteStatusCalls: 0,
+      localInvalidationCalls: 0,
+      remoteInvalidationCalls: 0,
+    };
+
+    return Effect.gen(function* () {
+      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
+      const snapshot = yield* Stream.runHead(
+        broadcaster.streamStatus(
+          { cwd: "/repo" },
+          { automaticRemoteRefreshInterval: Effect.succeed(Duration.zero) },
+        ),
+      );
+
+      assert.isTrue(Option.isSome(snapshot));
+      assert.equal(state.remoteStatusCalls, 0);
+      assert.equal(state.remoteInvalidationCalls, 0);
+    }).pipe(Effect.provide(makeTestLayer(state)));
+  });
+
+  it("backs off remote refresh failures exponentially and honors larger configured intervals", () => {
+    assert.equal(
+      Duration.toMillis(VcsStatusBroadcaster.remoteRefreshFailureDelay(1, Duration.seconds(1))),
+      30_000,
+    );
+    assert.equal(
+      Duration.toMillis(VcsStatusBroadcaster.remoteRefreshFailureDelay(2, Duration.seconds(1))),
+      60_000,
+    );
+    assert.equal(
+      Duration.toMillis(VcsStatusBroadcaster.remoteRefreshFailureDelay(3, Duration.seconds(1))),
+      120_000,
+    );
+    assert.equal(
+      Duration.toMillis(VcsStatusBroadcaster.remoteRefreshFailureDelay(1, Duration.minutes(5))),
+      300_000,
+    );
+    assert.equal(
+      Duration.toMillis(VcsStatusBroadcaster.remoteRefreshFailureDelay(20, Duration.seconds(1))),
+      900_000,
+    );
+  });
+
   it.effect("stops the remote poller after the last stream subscriber disconnects", () => {
     const state = {
       currentLocalStatus: baseLocalStatus,
@@ -230,9 +344,10 @@ describe("GitStatusBroadcasterLive", () => {
     };
     let remoteInterruptedDeferred: Deferred.Deferred<void, never> | null = null;
     let remoteStartedDeferred: Deferred.Deferred<void, never> | null = null;
-    const testLayer = GitStatusBroadcasterLive.pipe(
+    const testLayer = VcsStatusBroadcaster.layer.pipe(
+      Layer.provideMerge(NodeServices.layer),
       Layer.provide(
-        Layer.succeed(GitManager, {
+        Layer.mock(GitWorkflowService.GitWorkflowService)({
           localStatus: () =>
             Effect.sync(() => {
               state.localStatusCalls += 1;
@@ -247,14 +362,13 @@ describe("GitStatusBroadcasterLive", () => {
                   ? Deferred.succeed(remoteStartedDeferred, undefined).pipe(Effect.ignore)
                   : Effect.void,
               ),
-              Effect.andThen(Effect.never as Effect.Effect<GitStatusRemoteResult | null, never>),
+              Effect.andThen(Effect.never as Effect.Effect<VcsStatusRemoteResult | null, never>),
               Effect.onInterrupt(() =>
                 remoteInterruptedDeferred
                   ? Deferred.succeed(remoteInterruptedDeferred, undefined).pipe(Effect.ignore)
                   : Effect.void,
               ),
             ),
-          status: () => Effect.die("status should not be called in this test"),
           invalidateLocalStatus: () =>
             Effect.sync(() => {
               state.localInvalidationCalls += 1;
@@ -263,13 +377,7 @@ describe("GitStatusBroadcasterLive", () => {
             Effect.sync(() => {
               state.remoteInvalidationCalls += 1;
             }),
-          invalidateStatus: () => Effect.die("invalidateStatus should not be called in this test"),
-          resolvePullRequest: () =>
-            Effect.die("resolvePullRequest should not be called in this test"),
-          preparePullRequestThread: () =>
-            Effect.die("preparePullRequestThread should not be called in this test"),
-          runStackedAction: () => Effect.die("runStackedAction should not be called in this test"),
-        } satisfies GitManagerShape),
+        } satisfies Partial<GitWorkflowService.GitWorkflowServiceShape>),
       ),
     );
 
@@ -279,9 +387,9 @@ describe("GitStatusBroadcasterLive", () => {
       remoteInterruptedDeferred = remoteInterrupted;
       remoteStartedDeferred = remoteStarted;
 
-      const broadcaster = yield* GitStatusBroadcaster;
-      const firstSnapshot = yield* Deferred.make<GitStatusStreamEvent>();
-      const secondSnapshot = yield* Deferred.make<GitStatusStreamEvent>();
+      const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
+      const firstSnapshot = yield* Deferred.make<VcsStatusStreamEvent>();
+      const secondSnapshot = yield* Deferred.make<VcsStatusStreamEvent>();
       const firstScope = yield* Scope.make();
       const secondScope = yield* Scope.make();
       yield* Stream.runForEach(broadcaster.streamStatus({ cwd: "/repo" }), (event) =>
@@ -302,11 +410,11 @@ describe("GitStatusBroadcasterLive", () => {
       assert.equal(state.remoteStatusCalls, 1);
 
       yield* Scope.close(firstScope, Exit.void);
-      assert.equal(Option.isNone(yield* Deferred.poll(remoteInterrupted)), true);
+      assert.isTrue(Option.isNone(yield* Deferred.poll(remoteInterrupted)));
 
       yield* Scope.close(secondScope, Exit.void).pipe(Effect.forkScoped);
       yield* Deferred.await(remoteInterrupted);
-      assert.equal(Option.isSome(yield* Deferred.poll(remoteInterrupted)), true);
+      assert.isTrue(Option.isSome(yield* Deferred.poll(remoteInterrupted)));
     }).pipe(Effect.provide(testLayer));
   });
 });
diff --git a/apps/server/src/vcs/VcsStatusBroadcaster.ts b/apps/server/src/vcs/VcsStatusBroadcaster.ts
new file mode 100644
index 00000000000..40cdcf2c809
--- /dev/null
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.ts
@@ -0,0 +1,396 @@
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+import type {
+  GitManagerServiceError,
+  VcsStatusInput,
+  VcsStatusLocalResult,
+  VcsStatusRemoteResult,
+  VcsStatusResult,
+  VcsStatusStreamEvent,
+} from "@t3tools/contracts";
+import { mergeGitStatusParts } from "@t3tools/shared/git";
+
+import * as GitWorkflowService from "../git/GitWorkflowService.ts";
+
+const DEFAULT_VCS_STATUS_REFRESH_INTERVAL = Duration.seconds(30);
+const VCS_STATUS_REFRESH_FAILURE_BASE_DELAY = Duration.seconds(30);
+const VCS_STATUS_REFRESH_FAILURE_MAX_DELAY = Duration.minutes(15);
+
+interface VcsStatusChange {
+  readonly cwd: string;
+  readonly event: VcsStatusStreamEvent;
+}
+
+interface CachedValue<T> {
+  readonly fingerprint: string;
+  readonly value: T;
+}
+
+interface CachedVcsStatus {
+  readonly local: CachedValue<VcsStatusLocalResult> | null;
+  readonly remote: CachedValue<VcsStatusRemoteResult | null> | null;
+}
+
+interface ActiveRemotePoller {
+  readonly fiber: Fiber.Fiber<void, never>;
+  readonly subscriberCount: number;
+}
+
+interface StreamStatusOptions {
+  readonly automaticRemoteRefreshInterval?: Effect.Effect<Duration.Duration, never>;
+}
+
+export function remoteRefreshFailureDelay(
+  consecutiveFailures: number,
+  configuredInterval: Duration.Duration,
+) {
+  const exponent = Math.max(0, consecutiveFailures - 1);
+  const backoffMs =
+    Duration.toMillis(VCS_STATUS_REFRESH_FAILURE_BASE_DELAY) * Math.pow(2, exponent);
+  const cappedBackoff = Duration.min(
+    Duration.millis(backoffMs),
+    VCS_STATUS_REFRESH_FAILURE_MAX_DELAY,
+  );
+  return Duration.max(configuredInterval, cappedBackoff);
+}
+
+export interface VcsStatusBroadcasterShape {
+  readonly getStatus: (
+    input: VcsStatusInput,
+  ) => Effect.Effect<VcsStatusResult, GitManagerServiceError>;
+  readonly refreshLocalStatus: (
+    cwd: string,
+  ) => Effect.Effect<VcsStatusLocalResult, GitManagerServiceError>;
+  readonly refreshStatus: (cwd: string) => Effect.Effect<VcsStatusResult, GitManagerServiceError>;
+  readonly streamStatus: (
+    input: VcsStatusInput,
+    options?: StreamStatusOptions,
+  ) => Stream.Stream<VcsStatusStreamEvent, GitManagerServiceError>;
+}
+
+export class VcsStatusBroadcaster extends Context.Service<
+  VcsStatusBroadcaster,
+  VcsStatusBroadcasterShape
+>()("t3/vcs/VcsStatusBroadcaster") {}
+
+function fingerprintStatusPart(status: unknown): string {
+  return JSON.stringify(status);
+}
+
+const normalizeCwd = (cwd: string) =>
+  Effect.service(FileSystem.FileSystem).pipe(
+    Effect.flatMap((fs) => fs.realPath(cwd)),
+    Effect.orElseSucceed(() => cwd),
+  );
+
+export const layer = Layer.effect(
+  VcsStatusBroadcaster,
+  Effect.gen(function* () {
+    const workflow = yield* GitWorkflowService.GitWorkflowService;
+    const fs = yield* FileSystem.FileSystem;
+    const changesPubSub = yield* Effect.acquireRelease(
+      PubSub.unbounded<VcsStatusChange>(),
+      (pubsub) => PubSub.shutdown(pubsub),
+    );
+    const broadcasterScope = yield* Effect.acquireRelease(Scope.make(), (scope) =>
+      Scope.close(scope, Exit.void),
+    );
+    const cacheRef = yield* Ref.make(new Map<string, CachedVcsStatus>());
+    const pollersRef = yield* SynchronizedRef.make(new Map<string, ActiveRemotePoller>());
+
+    const getCachedStatus = Effect.fn("VcsStatusBroadcaster.getCachedStatus")(function* (
+      cwd: string,
+    ) {
+      return yield* Ref.get(cacheRef).pipe(Effect.map((cache) => cache.get(cwd) ?? null));
+    });
+
+    const updateCachedLocalStatus = Effect.fn("VcsStatusBroadcaster.updateCachedLocalStatus")(
+      function* (cwd: string, local: VcsStatusLocalResult, options?: { publish?: boolean }) {
+        const nextLocal = {
+          fingerprint: fingerprintStatusPart(local),
+          value: local,
+        } satisfies CachedValue<VcsStatusLocalResult>;
+        const shouldPublish = yield* Ref.modify(cacheRef, (cache) => {
+          const previous = cache.get(cwd) ?? { local: null, remote: null };
+          const nextCache = new Map(cache);
+          nextCache.set(cwd, {
+            ...previous,
+            local: nextLocal,
+          });
+          return [previous.local?.fingerprint !== nextLocal.fingerprint, nextCache] as const;
+        });
+
+        if (options?.publish && shouldPublish) {
+          yield* PubSub.publish(changesPubSub, {
+            cwd,
+            event: {
+              _tag: "localUpdated",
+              local,
+            },
+          });
+        }
+
+        return local;
+      },
+    );
+
+    const updateCachedRemoteStatus = Effect.fn("VcsStatusBroadcaster.updateCachedRemoteStatus")(
+      function* (
+        cwd: string,
+        remote: VcsStatusRemoteResult | null,
+        options?: { publish?: boolean },
+      ) {
+        const nextRemote = {
+          fingerprint: fingerprintStatusPart(remote),
+          value: remote,
+        } satisfies CachedValue<VcsStatusRemoteResult | null>;
+        const shouldPublish = yield* Ref.modify(cacheRef, (cache) => {
+          const previous = cache.get(cwd) ?? { local: null, remote: null };
+          const nextCache = new Map(cache);
+          nextCache.set(cwd, {
+            ...previous,
+            remote: nextRemote,
+          });
+          return [previous.remote?.fingerprint !== nextRemote.fingerprint, nextCache] as const;
+        });
+
+        if (options?.publish && shouldPublish) {
+          yield* PubSub.publish(changesPubSub, {
+            cwd,
+            event: {
+              _tag: "remoteUpdated",
+              remote,
+            },
+          });
+        }
+
+        return remote;
+      },
+    );
+
+    const loadLocalStatus = Effect.fn("VcsStatusBroadcaster.loadLocalStatus")(function* (
+      cwd: string,
+    ) {
+      const local = yield* workflow.localStatus({ cwd });
+      return yield* updateCachedLocalStatus(cwd, local);
+    });
+
+    const loadRemoteStatus = Effect.fn("VcsStatusBroadcaster.loadRemoteStatus")(function* (
+      cwd: string,
+    ) {
+      const remote = yield* workflow.remoteStatus({ cwd });
+      return yield* updateCachedRemoteStatus(cwd, remote);
+    });
+
+    const getOrLoadLocalStatus = Effect.fn("VcsStatusBroadcaster.getOrLoadLocalStatus")(function* (
+      cwd: string,
+    ) {
+      const cached = yield* getCachedStatus(cwd);
+      if (cached?.local) {
+        return cached.local.value;
+      }
+      return yield* loadLocalStatus(cwd);
+    });
+
+    const getOrLoadRemoteStatus = Effect.fn("VcsStatusBroadcaster.getOrLoadRemoteStatus")(
+      function* (cwd: string) {
+        const cached = yield* getCachedStatus(cwd);
+        if (cached?.remote) {
+          return cached.remote.value;
+        }
+        return yield* loadRemoteStatus(cwd);
+      },
+    );
+
+    const withFileSystem = Effect.provideService(FileSystem.FileSystem, fs);
+
+    const getStatus: VcsStatusBroadcasterShape["getStatus"] = Effect.fn(
+      "VcsStatusBroadcaster.getStatus",
+    )(function* (input) {
+      const cwd = yield* withFileSystem(normalizeCwd(input.cwd));
+      const [local, remote] = yield* Effect.all([
+        getOrLoadLocalStatus(cwd),
+        getOrLoadRemoteStatus(cwd),
+      ]);
+      return mergeGitStatusParts(local, remote);
+    });
+
+    const refreshLocalStatus: VcsStatusBroadcasterShape["refreshLocalStatus"] = Effect.fn(
+      "VcsStatusBroadcaster.refreshLocalStatus",
+    )(function* (rawCwd) {
+      const cwd = yield* withFileSystem(normalizeCwd(rawCwd));
+      yield* workflow.invalidateLocalStatus(cwd);
+      const local = yield* workflow.localStatus({ cwd });
+      return yield* updateCachedLocalStatus(cwd, local, { publish: true });
+    });
+
+    const refreshRemoteStatus = Effect.fn("VcsStatusBroadcaster.refreshRemoteStatus")(function* (
+      cwd: string,
+    ) {
+      yield* workflow.invalidateRemoteStatus(cwd);
+      const remote = yield* workflow.remoteStatus({ cwd });
+      return yield* updateCachedRemoteStatus(cwd, remote, { publish: true });
+    });
+
+    const refreshStatus: VcsStatusBroadcasterShape["refreshStatus"] = Effect.fn(
+      "VcsStatusBroadcaster.refreshStatus",
+    )(function* (rawCwd) {
+      const cwd = yield* withFileSystem(normalizeCwd(rawCwd));
+      const [local, remote] = yield* Effect.all([
+        refreshLocalStatus(cwd),
+        refreshRemoteStatus(cwd),
+      ]);
+      return mergeGitStatusParts(local, remote);
+    });
+
+    const makeRemoteRefreshLoop = (
+      cwd: string,
+      automaticRemoteRefreshInterval: Effect.Effect<Duration.Duration, never>,
+    ) => {
+      return Effect.gen(function* () {
+        const consecutiveFailuresRef = yield* Ref.make(0);
+        const refreshRemoteStatusIfEnabled = Effect.gen(function* () {
+          const configuredInterval = yield* automaticRemoteRefreshInterval;
+          const activeInterval = Duration.isZero(configuredInterval)
+            ? DEFAULT_VCS_STATUS_REFRESH_INTERVAL
+            : configuredInterval;
+          if (Duration.isZero(configuredInterval)) {
+            return activeInterval;
+          }
+
+          const exit = yield* refreshRemoteStatus(cwd).pipe(Effect.exit);
+          if (Exit.isSuccess(exit)) {
+            yield* Ref.set(consecutiveFailuresRef, 0);
+            return activeInterval;
+          }
+
+          const consecutiveFailures = yield* Ref.updateAndGet(
+            consecutiveFailuresRef,
+            (count) => count + 1,
+          );
+          const nextDelay = remoteRefreshFailureDelay(consecutiveFailures, activeInterval);
+          yield* Effect.logWarning("VCS remote status refresh failed", {
+            cwd,
+            detail: exit.cause.toString(),
+            consecutiveFailures,
+            nextDelayMs: Duration.toMillis(nextDelay),
+          });
+          return nextDelay;
+        });
+
+        return yield* refreshRemoteStatusIfEnabled.pipe(
+          Effect.repeat(
+            Schedule.identity<Duration.Duration>().pipe(
+              Schedule.addDelay((delay) => Effect.succeed(delay)),
+            ),
+          ),
+          Effect.asVoid,
+        );
+      });
+    };
+
+    const retainRemotePoller = Effect.fn("VcsStatusBroadcaster.retainRemotePoller")(function* (
+      cwd: string,
+      automaticRemoteRefreshInterval: Effect.Effect<Duration.Duration, never>,
+    ) {
+      yield* SynchronizedRef.modifyEffect(pollersRef, (activePollers) => {
+        const existing = activePollers.get(cwd);
+        if (existing) {
+          const nextPollers = new Map(activePollers);
+          nextPollers.set(cwd, {
+            ...existing,
+            subscriberCount: existing.subscriberCount + 1,
+          });
+          return Effect.succeed([undefined, nextPollers] as const);
+        }
+
+        return makeRemoteRefreshLoop(cwd, automaticRemoteRefreshInterval).pipe(
+          Effect.forkIn(broadcasterScope),
+          Effect.map((fiber) => {
+            const nextPollers = new Map(activePollers);
+            nextPollers.set(cwd, {
+              fiber,
+              subscriberCount: 1,
+            });
+            return [undefined, nextPollers] as const;
+          }),
+        );
+      });
+    });
+
+    const releaseRemotePoller = Effect.fn("VcsStatusBroadcaster.releaseRemotePoller")(function* (
+      cwd: string,
+    ) {
+      const pollerToInterrupt = yield* SynchronizedRef.modify(pollersRef, (activePollers) => {
+        const existing = activePollers.get(cwd);
+        if (!existing) {
+          return [null, activePollers] as const;
+        }
+
+        if (existing.subscriberCount > 1) {
+          const nextPollers = new Map(activePollers);
+          nextPollers.set(cwd, {
+            ...existing,
+            subscriberCount: existing.subscriberCount - 1,
+          });
+          return [null, nextPollers] as const;
+        }
+
+        const nextPollers = new Map(activePollers);
+        nextPollers.delete(cwd);
+        return [existing.fiber, nextPollers] as const;
+      });
+
+      if (pollerToInterrupt) {
+        yield* Fiber.interrupt(pollerToInterrupt).pipe(Effect.ignore);
+      }
+    });
+
+    const streamStatus: VcsStatusBroadcasterShape["streamStatus"] = (input, options) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          const cwd = yield* withFileSystem(normalizeCwd(input.cwd));
+          const subscription = yield* PubSub.subscribe(changesPubSub);
+          const initialLocal = yield* getOrLoadLocalStatus(cwd);
+          const initialRemote = (yield* getCachedStatus(cwd))?.remote?.value ?? null;
+          yield* retainRemotePoller(
+            cwd,
+            options?.automaticRemoteRefreshInterval ??
+              Effect.succeed(DEFAULT_VCS_STATUS_REFRESH_INTERVAL),
+          );
+
+          const release = releaseRemotePoller(cwd).pipe(Effect.ignore, Effect.asVoid);
+
+          return Stream.concat(
+            Stream.make({
+              _tag: "snapshot" as const,
+              local: initialLocal,
+              remote: initialRemote,
+            }),
+            Stream.fromSubscription(subscription).pipe(
+              Stream.filter((event) => event.cwd === cwd),
+              Stream.map((event) => event.event),
+            ),
+          ).pipe(Stream.ensuring(release));
+        }),
+      );
+
+    return VcsStatusBroadcaster.of({
+      getStatus,
+      refreshLocalStatus,
+      refreshStatus,
+      streamStatus,
+    });
+  }),
+);
diff --git a/apps/server/src/vcs/testing/VcsDriverContractHarness.ts b/apps/server/src/vcs/testing/VcsDriverContractHarness.ts
new file mode 100644
index 00000000000..fd474283590
--- /dev/null
+++ b/apps/server/src/vcs/testing/VcsDriverContractHarness.ts
@@ -0,0 +1,169 @@
+import { assert, it, describe } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import type * as PlatformError from "effect/PlatformError";
+import type * as Scope from "effect/Scope";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+
+import type { VcsDriverKind } from "@t3tools/contracts";
+import * as VcsDriver from "../VcsDriver.ts";
+
+function normalizePathForComparison(value: string): string {
+  return value.replaceAll("\\", "/");
+}
+
+export interface VcsDriverFixture<R, E> {
+  readonly createRepo: (cwd: string) => Effect.Effect<void, E, R>;
+  readonly writeFile: (
+    cwd: string,
+    relativePath: string,
+    contents: string,
+  ) => Effect.Effect<void, E, R | FileSystem.FileSystem | Path.Path>;
+  readonly trackFile?: (cwd: string, relativePath: string) => Effect.Effect<void, E, R>;
+  readonly commit?: (cwd: string, message: string) => Effect.Effect<void, E, R>;
+  readonly ignorePath: (
+    cwd: string,
+    pattern: string,
+  ) => Effect.Effect<void, E, R | FileSystem.FileSystem | Path.Path>;
+}
+
+export interface VcsDriverContractSuiteInput<R, E> {
+  readonly name: string;
+  readonly kind: VcsDriverKind;
+  readonly layer: Layer.Layer<
+    VcsDriver.VcsDriver | R | FileSystem.FileSystem | Path.Path,
+    E,
+    never
+  >;
+  readonly fixture: VcsDriverFixture<R, E>;
+}
+
+export function runVcsDriverContractSuite<R, E>(input: VcsDriverContractSuiteInput<R, E>) {
+  const makeTmpDir = (
+    prefix = `t3-${input.kind}-vcs-contract-`,
+  ): Effect.Effect<string, PlatformError.PlatformError, FileSystem.FileSystem | Scope.Scope> =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      return yield* fileSystem.makeTempDirectoryScoped({ prefix });
+    });
+
+  it.layer(input.layer)(`${input.name} VCS driver contract`, (it) => {
+    describe("repository detection", () => {
+      it.effect("returns null outside a repository", () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          const driver = yield* VcsDriver.VcsDriver;
+
+          assert.equal(yield* driver.detectRepository(cwd), null);
+          assert.equal(yield* driver.isInsideWorkTree(cwd), false);
+        }),
+      );
+
+      it.effect("detects repository identity inside a repository and nested directories", () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          const driver = yield* VcsDriver.VcsDriver;
+
+          yield* input.fixture.createRepo(cwd);
+          yield* input.fixture.writeFile(cwd, "src/index.ts", "export const value = 1;\n");
+          const identity = yield* driver.detectRepository(cwd);
+          assert.equal(identity?.kind, input.kind);
+          assert.isTrue(
+            normalizePathForComparison(identity?.rootPath ?? "").endsWith(
+              normalizePathForComparison(cwd),
+            ),
+          );
+          assert.equal(identity?.freshness.source, "live-local");
+          assert.isTrue(DateTime.isDateTime(identity?.freshness.observedAt));
+          assert.isTrue(Option.isNone(identity?.freshness.expiresAt ?? Option.none()));
+          assert.equal(yield* driver.isInsideWorkTree(cwd), true);
+
+          const path = yield* Path.Path;
+          const nestedDir = path.join(cwd, "src");
+          const nestedIdentity = yield* driver.detectRepository(nestedDir);
+          assert.equal(nestedIdentity?.rootPath, identity?.rootPath);
+          assert.equal(yield* driver.isInsideWorkTree(nestedDir), true);
+        }),
+      );
+    });
+
+    describe("workspace files", () => {
+      it.effect("lists tracked and untracked non-ignored files", () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          const driver = yield* VcsDriver.VcsDriver;
+
+          yield* input.fixture.createRepo(cwd);
+          yield* input.fixture.writeFile(cwd, "tracked.ts", "export const tracked = true;\n");
+          if (input.fixture.trackFile && input.fixture.commit) {
+            yield* input.fixture.trackFile(cwd, "tracked.ts");
+            yield* input.fixture.commit(cwd, "Track file");
+          }
+          yield* input.fixture.writeFile(cwd, "untracked.ts", "export const untracked = true;\n");
+
+          const result = yield* driver.listWorkspaceFiles(cwd);
+
+          assert.include(result.paths, "tracked.ts");
+          assert.include(result.paths, "untracked.ts");
+          assert.equal(result.truncated, false);
+          assert.equal(result.freshness.source, "live-local");
+          assert.isTrue(DateTime.isDateTime(result.freshness.observedAt));
+          assert.isTrue(Option.isNone(result.freshness.expiresAt));
+        }),
+      );
+
+      it.effect("excludes ignored files from workspace listing", () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          const driver = yield* VcsDriver.VcsDriver;
+
+          yield* input.fixture.createRepo(cwd);
+          yield* input.fixture.ignorePath(cwd, "*.log");
+          yield* input.fixture.writeFile(cwd, "included.ts", "export const included = true;\n");
+          yield* input.fixture.writeFile(cwd, "debug.log", "ignore me\n");
+          yield* input.fixture.writeFile(cwd, "nested/error.log", "ignore me too\n");
+
+          const result = yield* driver.listWorkspaceFiles(cwd);
+
+          assert.include(result.paths, "included.ts");
+          assert.notInclude(result.paths, "debug.log");
+          assert.notInclude(result.paths, "nested/error.log");
+        }),
+      );
+    });
+
+    describe("ignored path filtering", () => {
+      it.effect("filters ignored paths", () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          const driver = yield* VcsDriver.VcsDriver;
+
+          yield* input.fixture.createRepo(cwd);
+          yield* input.fixture.ignorePath(cwd, "*.log");
+
+          const result = yield* driver.filterIgnoredPaths(cwd, [
+            "keep.ts",
+            "debug.log",
+            "nested/error.log",
+          ]);
+
+          assert.deepStrictEqual(result, ["keep.ts"]);
+        }),
+      );
+
+      it.effect("returns empty input unchanged", () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          const driver = yield* VcsDriver.VcsDriver;
+
+          yield* input.fixture.createRepo(cwd);
+
+          assert.deepStrictEqual(yield* driver.filterIgnoredPaths(cwd, []), []);
+        }),
+      );
+    });
+  });
+}
diff --git a/apps/server/src/workspace/Layers/WorkspaceEntries.test.ts b/apps/server/src/workspace/Layers/WorkspaceEntries.test.ts
index 09f6905ce98..84ea5c51937 100644
--- a/apps/server/src/workspace/Layers/WorkspaceEntries.test.ts
+++ b/apps/server/src/workspace/Layers/WorkspaceEntries.test.ts
@@ -1,12 +1,17 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fsPromises from "node:fs/promises";
-
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it, afterEach, describe, expect, vi } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path, PlatformError } from "effect";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
 
 import { ServerConfig } from "../../config.ts";
-import { GitCoreLive } from "../../git/Layers/GitCore.ts";
-import { GitCore } from "../../git/Services/GitCore.ts";
+import * as VcsDriverRegistry from "../../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../../vcs/VcsProcess.ts";
 import { WorkspaceEntries } from "../Services/WorkspaceEntries.ts";
 import { WorkspaceEntriesLive } from "./WorkspaceEntries.ts";
 import { WorkspacePathsLive } from "./WorkspacePaths.ts";
@@ -14,7 +19,8 @@ import { WorkspacePathsLive } from "./WorkspacePaths.ts";
 const TestLayer = Layer.empty.pipe(
   Layer.provideMerge(WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive))),
   Layer.provideMerge(WorkspacePathsLive),
-  Layer.provideMerge(GitCoreLive),
+  Layer.provideMerge(VcsProcess.layer),
+  Layer.provideMerge(VcsDriverRegistry.layer.pipe(Layer.provide(VcsProcess.layer))),
   Layer.provide(
     ServerConfig.layerTest(process.cwd(), {
       prefix: "t3-workspace-entries-test-",
@@ -25,12 +31,11 @@ const TestLayer = Layer.empty.pipe(
 
 const makeTempDir = Effect.fn(function* (opts?: { prefix?: string; git?: boolean }) {
   const fileSystem = yield* FileSystem.FileSystem;
-  const gitCore = yield* GitCore;
   const dir = yield* fileSystem.makeTempDirectoryScoped({
     prefix: opts?.prefix ?? "t3code-workspace-entries-",
   });
   if (opts?.git) {
-    yield* gitCore.initRepo({ cwd: dir });
+    yield* git(dir, ["init"]);
   }
   return dir;
 });
@@ -51,9 +56,10 @@ function writeTextFile(
 
 const git = (cwd: string, args: ReadonlyArray<string>, env?: NodeJS.ProcessEnv) =>
   Effect.gen(function* () {
-    const gitCore = yield* GitCore;
-    const result = yield* gitCore.execute({
+    const process = yield* VcsProcess.VcsProcess;
+    const result = yield* process.run({
       operation: "WorkspaceEntries.test.git",
+      command: "git",
       cwd,
       args,
       ...(env ? { env } : {}),
@@ -68,6 +74,11 @@ const searchWorkspaceEntries = (input: { cwd: string; query: string; limit: numb
     return yield* workspaceEntries.search(input);
   });
 
+const appendSeparator = (input: string) =>
+  input.endsWith("/") || input.endsWith("\\")
+    ? input
+    : `${input}${process.platform === "win32" ? "\\" : "/"}`;
+
 it.layer(TestLayer)("WorkspaceEntriesLive", (it) => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -216,25 +227,37 @@ it.layer(TestLayer)("WorkspaceEntriesLive", (it) => {
         yield* writeTextFile(cwd, "src/components/Composer.tsx");
 
         let rootReadCount = 0;
+        let releaseRootRead: (() => void) | undefined;
+        const rootReadGate = new Promise<void>((resolve) => {
+          releaseRootRead = resolve;
+        });
         const originalReaddir = fsPromises.readdir.bind(fsPromises);
         vi.spyOn(fsPromises, "readdir").mockImplementation((async (
           ...args: Parameters<typeof fsPromises.readdir>
         ) => {
           if (args[0] === cwd) {
             rootReadCount += 1;
-            await new Promise((resolve) => setTimeout(resolve, 20));
+            await rootReadGate;
           }
           return originalReaddir(...args);
         }) as typeof fsPromises.readdir);
 
-        yield* Effect.all(
+        const searches = yield* Effect.all(
           [
             searchWorkspaceEntries({ cwd, query: "", limit: 100 }),
             searchWorkspaceEntries({ cwd, query: "comp", limit: 100 }),
             searchWorkspaceEntries({ cwd, query: "src", limit: 100 }),
           ],
           { concurrency: "unbounded" },
-        );
+        ).pipe(Effect.forkScoped);
+        for (let attempt = 0; attempt < 50; attempt += 1) {
+          if (rootReadCount > 0) {
+            break;
+          }
+          yield* Effect.yieldNow;
+        }
+        releaseRootRead?.();
+        yield* Fiber.join(searches);
 
         expect(rootReadCount).toBe(1);
       }),
@@ -251,6 +274,10 @@ it.layer(TestLayer)("WorkspaceEntriesLive", (it) => {
 
         let activeReads = 0;
         let peakReads = 0;
+        let releaseReads: (() => void) | undefined;
+        const readsGate = new Promise<void>((resolve) => {
+          releaseReads = resolve;
+        });
         const originalReaddir = fsPromises.readdir.bind(fsPromises);
         vi.spyOn(fsPromises, "readdir").mockImplementation((async (
           ...args: Parameters<typeof fsPromises.readdir>
@@ -259,7 +286,7 @@ it.layer(TestLayer)("WorkspaceEntriesLive", (it) => {
           if (typeof target === "string" && target.startsWith(cwd)) {
             activeReads += 1;
             peakReads = Math.max(peakReads, activeReads);
-            await new Promise((resolve) => setTimeout(resolve, 4));
+            await readsGate;
             try {
               return await originalReaddir(...args);
             } finally {
@@ -269,10 +296,101 @@ it.layer(TestLayer)("WorkspaceEntriesLive", (it) => {
           return originalReaddir(...args);
         }) as typeof fsPromises.readdir);
 
-        yield* searchWorkspaceEntries({ cwd, query: "", limit: 200 });
+        const search = yield* searchWorkspaceEntries({ cwd, query: "", limit: 200 }).pipe(
+          Effect.forkScoped,
+        );
+        for (let attempt = 0; attempt < 50; attempt += 1) {
+          if (activeReads > 0) {
+            break;
+          }
+          yield* Effect.yieldNow;
+        }
+        releaseReads?.();
+        yield* Fiber.join(search);
 
         expect(peakReads).toBeLessThanOrEqual(32);
       }),
     );
   });
+
+  describe("browse", () => {
+    it.effect("returns matching directories and excludes files", () =>
+      Effect.gen(function* () {
+        const workspaceEntries = yield* WorkspaceEntries;
+        const path = yield* Path.Path;
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-browse-prefix-" });
+        yield* writeTextFile(cwd, "alphabet.txt", "ignore me");
+        yield* writeTextFile(cwd, "alpha/index.ts", "export {};\n");
+        yield* writeTextFile(cwd, "alpine/index.ts", "export {};\n");
+
+        const result = yield* workspaceEntries.browse({
+          partialPath: path.join(cwd, "alp"),
+        });
+
+        expect(result).toEqual({
+          parentPath: cwd,
+          entries: [
+            { name: "alpha", fullPath: path.join(cwd, "alpha") },
+            { name: "alpine", fullPath: path.join(cwd, "alpine") },
+          ],
+        });
+      }),
+    );
+
+    it.effect("shows dot directories in directory mode and hidden-prefix mode", () =>
+      Effect.gen(function* () {
+        const workspaceEntries = yield* WorkspaceEntries;
+        const path = yield* Path.Path;
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-browse-hidden-" });
+        yield* writeTextFile(cwd, ".config/settings.json", "{}");
+        yield* writeTextFile(cwd, "config/settings.json", "{}");
+
+        const directoryResult = yield* workspaceEntries.browse({
+          partialPath: appendSeparator(cwd),
+        });
+        const hiddenPrefixResult = yield* workspaceEntries.browse({
+          partialPath: `${appendSeparator(cwd)}.c`,
+        });
+
+        expect(directoryResult.entries.map((entry) => entry.name)).toEqual([".config", "config"]);
+        expect(hiddenPrefixResult).toEqual({
+          parentPath: cwd,
+          entries: [{ name: ".config", fullPath: path.join(cwd, ".config") }],
+        });
+      }),
+    );
+
+    it.effect("supports relative paths when cwd is provided", () =>
+      Effect.gen(function* () {
+        const workspaceEntries = yield* WorkspaceEntries;
+        const path = yield* Path.Path;
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-browse-relative-" });
+        yield* writeTextFile(cwd, "packages/pkg.json", "{}");
+
+        const result = yield* workspaceEntries.browse({
+          cwd,
+          partialPath: "./pack",
+        });
+
+        expect(result).toEqual({
+          parentPath: cwd,
+          entries: [{ name: "packages", fullPath: path.join(cwd, "packages") }],
+        });
+      }),
+    );
+
+    it.effect("rejects relative paths without cwd", () =>
+      Effect.gen(function* () {
+        const workspaceEntries = yield* WorkspaceEntries;
+
+        const error = yield* workspaceEntries
+          .browse({
+            partialPath: "./src",
+          })
+          .pipe(Effect.flip);
+
+        expect(error.detail).toBe("Relative filesystem browse paths require a current project.");
+      }),
+    );
+  });
 });
diff --git a/apps/server/src/workspace/Layers/WorkspaceEntries.ts b/apps/server/src/workspace/Layers/WorkspaceEntries.ts
index c4d3c3c81f3..0c0ab638207 100644
--- a/apps/server/src/workspace/Layers/WorkspaceEntries.ts
+++ b/apps/server/src/workspace/Layers/WorkspaceEntries.ts
@@ -1,9 +1,18 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as OS from "node:os";
 import fsPromises from "node:fs/promises";
 import type { Dirent } from "node:fs";
 
-import { Cache, Duration, Effect, Exit, Layer, Option, Path } from "effect";
+import * as Cache from "effect/Cache";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 
-import { type ProjectEntry } from "@t3tools/contracts";
+import { type FilesystemBrowseInput, type ProjectEntry } from "@t3tools/contracts";
+import { isExplicitRelativePath, isWindowsAbsolutePath } from "@t3tools/shared/path";
 import {
   insertRankedSearchResult,
   normalizeSearchQuery,
@@ -11,9 +20,10 @@ import {
   type RankedSearchResult,
 } from "@t3tools/shared/searchRanking";
 
-import { GitCore } from "../../git/Services/GitCore.ts";
+import { VcsDriverRegistry } from "../../vcs/VcsDriverRegistry.ts";
 import {
   WorkspaceEntries,
+  WorkspaceEntriesBrowseError,
   WorkspaceEntriesError,
   type WorkspaceEntriesShape,
 } from "../Services/WorkspaceEntries.ts";
@@ -52,6 +62,16 @@ function toPosixPath(input: string): string {
   return input.replaceAll("\\", "/");
 }
 
+function expandHomePath(input: string, path: Path.Path): string {
+  if (input === "~") {
+    return OS.homedir();
+  }
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return path.join(OS.homedir(), input.slice(2));
+  }
+  return input;
+}
+
 function parentPathOf(input: string): string | undefined {
   const separatorIndex = input.lastIndexOf("/");
   if (separatorIndex === -1) {
@@ -129,40 +149,71 @@ function directoryAncestorsOf(relativePath: string): string[] {
   return directories;
 }
 
+const resolveBrowseTarget = (
+  input: FilesystemBrowseInput,
+  pathService: Path.Path,
+): Effect.Effect<string, WorkspaceEntriesBrowseError> =>
+  Effect.gen(function* () {
+    if (process.platform !== "win32" && isWindowsAbsolutePath(input.partialPath)) {
+      return yield* new WorkspaceEntriesBrowseError({
+        cwd: input.cwd,
+        partialPath: input.partialPath,
+        operation: "workspaceEntries.resolveBrowseTarget",
+        detail: "Windows-style paths are only supported on Windows.",
+      });
+    }
+
+    if (!isExplicitRelativePath(input.partialPath)) {
+      return pathService.resolve(expandHomePath(input.partialPath, pathService));
+    }
+
+    if (!input.cwd) {
+      return yield* new WorkspaceEntriesBrowseError({
+        cwd: input.cwd,
+        partialPath: input.partialPath,
+        operation: "workspaceEntries.resolveBrowseTarget",
+        detail: "Relative filesystem browse paths require a current project.",
+      });
+    }
+
+    return pathService.resolve(expandHomePath(input.cwd, pathService), input.partialPath);
+  });
+
 export const makeWorkspaceEntries = Effect.gen(function* () {
   const path = yield* Path.Path;
-  const gitOption = yield* Effect.serviceOption(GitCore);
+  const vcsRegistry = yield* VcsDriverRegistry;
   const workspacePaths = yield* WorkspacePaths;
 
-  const isInsideGitWorkTree = (cwd: string): Effect.Effect<boolean> =>
-    Option.match(gitOption, {
-      onSome: (git) => git.isInsideWorkTree(cwd).pipe(Effect.catch(() => Effect.succeed(false))),
-      onNone: () => Effect.succeed(false),
-    });
+  const isInsideVcsWorkTree = (cwd: string): Effect.Effect<boolean> =>
+    vcsRegistry.detect({ cwd }).pipe(
+      Effect.map((handle) => handle !== null),
+      Effect.catch(() => Effect.succeed(false)),
+    );
 
-  const filterGitIgnoredPaths = (
+  const filterVcsIgnoredPaths = (
     cwd: string,
     relativePaths: string[],
   ): Effect.Effect<string[], never> =>
-    Option.match(gitOption, {
-      onSome: (git) =>
-        git.filterIgnoredPaths(cwd, relativePaths).pipe(
-          Effect.map((paths) => [...paths]),
-          Effect.catch(() => Effect.succeed(relativePaths)),
-        ),
-      onNone: () => Effect.succeed(relativePaths),
-    });
-
-  const buildWorkspaceIndexFromGit = Effect.fn("WorkspaceEntries.buildWorkspaceIndexFromGit")(
+    vcsRegistry.detect({ cwd }).pipe(
+      Effect.flatMap((handle) =>
+        handle
+          ? handle.driver.filterIgnoredPaths(cwd, relativePaths).pipe(
+              Effect.map((paths) => [...paths]),
+              Effect.catch(() => Effect.succeed(relativePaths)),
+            )
+          : Effect.succeed(relativePaths),
+      ),
+      Effect.catch(() => Effect.succeed(relativePaths)),
+    );
+
+  const buildWorkspaceIndexFromVcs = Effect.fn("WorkspaceEntries.buildWorkspaceIndexFromVcs")(
     function* (cwd: string) {
-      if (Option.isNone(gitOption)) {
-        return null;
-      }
-      if (!(yield* isInsideGitWorkTree(cwd))) {
+      const vcs = yield* vcsRegistry.detect({ cwd }).pipe(Effect.catch(() => Effect.succeed(null)));
+      if (!vcs) {
         return null;
       }
 
-      const listedFiles = yield* gitOption.value
+      const listedFiles = yield* vcs.driver
         .listWorkspaceFiles(cwd)
         .pipe(Effect.catch(() => Effect.succeed(null)));
 
@@ -173,7 +224,10 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
       const listedPaths = [...listedFiles.paths]
         .map((entry) => toPosixPath(entry))
         .filter((entry) => entry.length > 0 && !isPathInIgnoredDirectory(entry));
-      const filePaths = yield* filterGitIgnoredPaths(cwd, listedPaths);
+      const filePaths = yield* vcs.driver.filterIgnoredPaths(cwd, listedPaths).pipe(
+        Effect.map((paths) => [...paths]),
+        Effect.catch(() => filterVcsIgnoredPaths(cwd, listedPaths)),
+      );
 
       const directorySet = new Set<string>();
       for (const filePath of filePaths) {
@@ -205,9 +259,10 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
         )
         .map(toSearchableWorkspaceEntry);
 
+      const now = yield* DateTime.now;
       const entries = [...directoryEntries, ...fileEntries];
       return {
-        scannedAt: Date.now(),
+        scannedAt: now.epochMilliseconds,
         entries: entries.slice(0, WORKSPACE_INDEX_MAX_ENTRIES),
         truncated: listedFiles.truncated || entries.length > WORKSPACE_INDEX_MAX_ENTRIES,
       };
@@ -245,7 +300,7 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
   const buildWorkspaceIndexFromFilesystem = Effect.fn(
     "WorkspaceEntries.buildWorkspaceIndexFromFilesystem",
   )(function* (cwd: string): Effect.fn.Return<WorkspaceIndex, WorkspaceEntriesError> {
-    const shouldFilterWithGitIgnore = yield* isInsideGitWorkTree(cwd);
+    const shouldFilterWithGitIgnore = yield* isInsideVcsWorkTree(cwd);
 
     let pendingDirectories: string[] = [""];
     const entries: SearchableWorkspaceEntry[] = [];
@@ -293,7 +348,7 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
         candidateEntries.map((entry) => entry.relativePath),
       );
       const allowedPathSet = shouldFilterWithGitIgnore
-        ? new Set(yield* filterGitIgnoredPaths(cwd, candidatePaths))
+        ? new Set(yield* filterVcsIgnoredPaths(cwd, candidatePaths))
         : null;
 
       for (const candidateEntries of candidateEntriesByDirectory) {
@@ -325,8 +380,9 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
       }
     }
 
+    const now = yield* DateTime.now;
     return {
-      scannedAt: Date.now(),
+      scannedAt: now.epochMilliseconds,
       entries,
       truncated,
     };
@@ -335,9 +391,9 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
   const buildWorkspaceIndex = Effect.fn("WorkspaceEntries.buildWorkspaceIndex")(function* (
     cwd: string,
   ): Effect.fn.Return<WorkspaceIndex, WorkspaceEntriesError> {
-    const gitIndexed = yield* buildWorkspaceIndexFromGit(cwd);
-    if (gitIndexed) {
-      return gitIndexed;
+    const vcsIndexed = yield* buildWorkspaceIndexFromVcs(cwd);
+    if (vcsIndexed) {
+      return vcsIndexed;
     }
     return yield* buildWorkspaceIndexFromFilesystem(cwd);
   });
@@ -379,6 +435,46 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
     },
   );
 
+  const browse: WorkspaceEntriesShape["browse"] = Effect.fn("WorkspaceEntries.browse")(
+    function* (input) {
+      const resolvedInputPath = yield* resolveBrowseTarget(input, path);
+      const endsWithSeparator = /[\\/]$/.test(input.partialPath) || input.partialPath === "~";
+      const parentPath = endsWithSeparator ? resolvedInputPath : path.dirname(resolvedInputPath);
+      const prefix = endsWithSeparator ? "" : path.basename(resolvedInputPath);
+
+      const dirents = yield* Effect.tryPromise({
+        try: () => fsPromises.readdir(parentPath, { withFileTypes: true }),
+        catch: (cause) =>
+          new WorkspaceEntriesBrowseError({
+            cwd: input.cwd,
+            partialPath: input.partialPath,
+            operation: "workspaceEntries.browse.readDirectory",
+            detail: `Unable to browse '${parentPath}': ${cause instanceof Error ? cause.message : String(cause)}`,
+            cause,
+          }),
+      });
+
+      const showHidden = endsWithSeparator || prefix.startsWith(".");
+      const lowerPrefix = prefix.toLowerCase();
+
+      return {
+        parentPath,
+        entries: dirents
+          .filter(
+            (dirent) =>
+              dirent.isDirectory() &&
+              dirent.name.toLowerCase().startsWith(lowerPrefix) &&
+              (showHidden || !dirent.name.startsWith(".")),
+          )
+          .map((dirent) => ({
+            name: dirent.name,
+            fullPath: path.join(parentPath, dirent.name),
+          }))
+          .toSorted((left, right) => left.name.localeCompare(right.name)),
+      };
+    },
+  );
+
   const search: WorkspaceEntriesShape["search"] = Effect.fn("WorkspaceEntries.search")(
     function* (input) {
       const normalizedCwd = yield* normalizeWorkspaceRoot(input.cwd);
@@ -415,6 +511,7 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
   );
 
   return {
+    browse,
     invalidate,
     search,
   } satisfies WorkspaceEntriesShape;
diff --git a/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts b/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts
index fcfd13c912e..e748a27a58a 100644
--- a/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts
+++ b/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts
@@ -1,9 +1,13 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it, describe, expect } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 
 import { ServerConfig } from "../../config.ts";
-import { GitCoreLive } from "../../git/Layers/GitCore.ts";
+import * as VcsDriverRegistry from "../../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../../vcs/VcsProcess.ts";
 import { WorkspaceEntries } from "../Services/WorkspaceEntries.ts";
 import { WorkspaceFileSystem } from "../Services/WorkspaceFileSystem.ts";
 import { WorkspaceEntriesLive } from "./WorkspaceEntries.ts";
@@ -19,7 +23,7 @@ const TestLayer = Layer.empty.pipe(
   Layer.provideMerge(ProjectLayer),
   Layer.provideMerge(WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive))),
   Layer.provideMerge(WorkspacePathsLive),
-  Layer.provideMerge(GitCoreLive),
+  Layer.provideMerge(VcsDriverRegistry.layer.pipe(Layer.provide(VcsProcess.layer))),
   Layer.provide(
     ServerConfig.layerTest(process.cwd(), {
       prefix: "t3-workspace-files-test-",
diff --git a/apps/server/src/workspace/Layers/WorkspaceFileSystem.ts b/apps/server/src/workspace/Layers/WorkspaceFileSystem.ts
index 84e5d9c6d12..9f53ade1bb9 100644
--- a/apps/server/src/workspace/Layers/WorkspaceFileSystem.ts
+++ b/apps/server/src/workspace/Layers/WorkspaceFileSystem.ts
@@ -1,4 +1,7 @@
-import { Effect, FileSystem, Layer, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 
 import {
   WorkspaceFileSystem,
diff --git a/apps/server/src/workspace/Layers/WorkspacePaths.test.ts b/apps/server/src/workspace/Layers/WorkspacePaths.test.ts
index d02a5929d27..0a9252a7def 100644
--- a/apps/server/src/workspace/Layers/WorkspacePaths.test.ts
+++ b/apps/server/src/workspace/Layers/WorkspacePaths.test.ts
@@ -1,6 +1,9 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it, describe, expect } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 
 import { WorkspacePaths } from "../Services/WorkspacePaths.ts";
 import { WorkspacePathsLive } from "./WorkspacePaths.ts";
@@ -58,6 +61,24 @@ it.layer(TestLayer)("WorkspacePathsLive", (it) => {
       }),
     );
 
+    it.effect("creates missing directories when createIfMissing is enabled", () =>
+      Effect.gen(function* () {
+        const workspacePaths = yield* WorkspacePaths;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const cwd = yield* makeTempDir();
+        const path = yield* Path.Path;
+        const missingPath = path.join(cwd, "nested", "new-project");
+
+        const resolved = yield* workspacePaths.normalizeWorkspaceRoot(missingPath, {
+          createIfMissing: true,
+        });
+        const stat = yield* fileSystem.stat(resolved);
+
+        expect(resolved).toBe(missingPath);
+        expect(stat.type).toBe("Directory");
+      }),
+    );
+
     it.effect("rejects file paths", () =>
       Effect.gen(function* () {
         const workspacePaths = yield* WorkspacePaths;
diff --git a/apps/server/src/workspace/Layers/WorkspacePaths.ts b/apps/server/src/workspace/Layers/WorkspacePaths.ts
index fa7a90cf07d..9dd33aaac7d 100644
--- a/apps/server/src/workspace/Layers/WorkspacePaths.ts
+++ b/apps/server/src/workspace/Layers/WorkspacePaths.ts
@@ -1,9 +1,13 @@
 import * as OS from "node:os";
-import { Effect, FileSystem, Layer, Path } from "effect";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 
 import {
   WorkspacePaths,
   WorkspacePathOutsideRootError,
+  WorkspaceRootCreateFailedError,
   WorkspaceRootNotDirectoryError,
   WorkspaceRootNotExistsError,
   type WorkspacePathsShape,
@@ -29,11 +33,25 @@ export const makeWorkspacePaths = Effect.gen(function* () {
 
   const normalizeWorkspaceRoot: WorkspacePathsShape["normalizeWorkspaceRoot"] = Effect.fn(
     "WorkspacePaths.normalizeWorkspaceRoot",
-  )(function* (workspaceRoot) {
+  )(function* (workspaceRoot, options) {
     const normalizedWorkspaceRoot = path.resolve(expandHomePath(workspaceRoot.trim(), path));
-    const workspaceStat = yield* fileSystem
+    let workspaceStat = yield* fileSystem
       .stat(normalizedWorkspaceRoot)
       .pipe(Effect.catch(() => Effect.succeed(null)));
+    if (!workspaceStat && options?.createIfMissing) {
+      yield* fileSystem.makeDirectory(normalizedWorkspaceRoot, { recursive: true }).pipe(
+        Effect.mapError(
+          () =>
+            new WorkspaceRootCreateFailedError({
+              workspaceRoot,
+              normalizedWorkspaceRoot,
+            }),
+        ),
+      );
+      workspaceStat = yield* fileSystem
+        .stat(normalizedWorkspaceRoot)
+        .pipe(Effect.catch(() => Effect.succeed(null)));
+    }
     if (!workspaceStat) {
       return yield* new WorkspaceRootNotExistsError({
         workspaceRoot,
diff --git a/apps/server/src/workspace/Services/WorkspaceEntries.ts b/apps/server/src/workspace/Services/WorkspaceEntries.ts
index c0011a9dc9a..a5d7ed8c082 100644
--- a/apps/server/src/workspace/Services/WorkspaceEntries.ts
+++ b/apps/server/src/workspace/Services/WorkspaceEntries.ts
@@ -6,10 +6,16 @@
  *
  * @module WorkspaceEntries
  */
-import { Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
-import type { ProjectSearchEntriesInput, ProjectSearchEntriesResult } from "@t3tools/contracts";
+import type {
+  FilesystemBrowseInput,
+  FilesystemBrowseResult,
+  ProjectSearchEntriesInput,
+  ProjectSearchEntriesResult,
+} from "@t3tools/contracts";
 
 export class WorkspaceEntriesError extends Schema.TaggedErrorClass<WorkspaceEntriesError>()(
   "WorkspaceEntriesError",
@@ -21,11 +27,29 @@ export class WorkspaceEntriesError extends Schema.TaggedErrorClass<WorkspaceEntr
   },
 ) {}
 
+export class WorkspaceEntriesBrowseError extends Schema.TaggedErrorClass<WorkspaceEntriesBrowseError>()(
+  "WorkspaceEntriesBrowseError",
+  {
+    cwd: Schema.optional(Schema.String),
+    partialPath: Schema.String,
+    operation: Schema.String,
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {}
+
 /**
  * WorkspaceEntriesShape - Service API for workspace entry search and cache
  * invalidation.
  */
 export interface WorkspaceEntriesShape {
+  /**
+   * Browse matching directories for the provided partial path.
+   */
+  readonly browse: (
+    input: FilesystemBrowseInput,
+  ) => Effect.Effect<FilesystemBrowseResult, WorkspaceEntriesBrowseError>;
+
   /**
    * Search indexed workspace entries for files and directories matching the
    * provided query.
diff --git a/apps/server/src/workspace/Services/WorkspaceFileSystem.ts b/apps/server/src/workspace/Services/WorkspaceFileSystem.ts
index dc6cc6e9d85..b448a8ab505 100644
--- a/apps/server/src/workspace/Services/WorkspaceFileSystem.ts
+++ b/apps/server/src/workspace/Services/WorkspaceFileSystem.ts
@@ -6,8 +6,9 @@
  *
  * @module WorkspaceFileSystem
  */
-import { Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 import type { ProjectWriteFileInput, ProjectWriteFileResult } from "@t3tools/contracts";
 import { WorkspacePathOutsideRootError } from "./WorkspacePaths.ts";
diff --git a/apps/server/src/workspace/Services/WorkspacePaths.ts b/apps/server/src/workspace/Services/WorkspacePaths.ts
index 86cef907359..7c57ca19bd2 100644
--- a/apps/server/src/workspace/Services/WorkspacePaths.ts
+++ b/apps/server/src/workspace/Services/WorkspacePaths.ts
@@ -6,8 +6,9 @@
  *
  * @module WorkspacePaths
  */
-import { Schema, Context } from "effect";
-import type { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
 
 export class WorkspaceRootNotExistsError extends Schema.TaggedErrorClass<WorkspaceRootNotExistsError>()(
   "WorkspaceRootNotExistsError",
@@ -21,6 +22,18 @@ export class WorkspaceRootNotExistsError extends Schema.TaggedErrorClass<Workspa
   }
 }
 
+export class WorkspaceRootCreateFailedError extends Schema.TaggedErrorClass<WorkspaceRootCreateFailedError>()(
+  "WorkspaceRootCreateFailedError",
+  {
+    workspaceRoot: Schema.String,
+    normalizedWorkspaceRoot: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Failed to create workspace root: ${this.normalizedWorkspaceRoot}`;
+  }
+}
+
 export class WorkspaceRootNotDirectoryError extends Schema.TaggedErrorClass<WorkspaceRootNotDirectoryError>()(
   "WorkspaceRootNotDirectoryError",
   {
@@ -47,6 +60,7 @@ export class WorkspacePathOutsideRootError extends Schema.TaggedErrorClass<Works
 
 export const WorkspacePathsError = Schema.Union([
   WorkspaceRootNotExistsError,
+  WorkspaceRootCreateFailedError,
   WorkspaceRootNotDirectoryError,
   WorkspacePathOutsideRootError,
 ]);
@@ -61,7 +75,11 @@ export interface WorkspacePathsShape {
    */
   readonly normalizeWorkspaceRoot: (
     workspaceRoot: string,
-  ) => Effect.Effect<string, WorkspaceRootNotExistsError | WorkspaceRootNotDirectoryError>;
+    options?: { readonly createIfMissing?: boolean },
+  ) => Effect.Effect<
+    string,
+    WorkspaceRootNotExistsError | WorkspaceRootCreateFailedError | WorkspaceRootNotDirectoryError
+  >;
 
   /**
    * Resolve a relative path within a validated workspace root.
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 3ef4a864697..e99672161c9 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -1,5 +1,15 @@
-import { Cause, Effect, Layer, Queue, Ref, Schema, Stream } from "effect";
+import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import {
+  DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL,
   type AuthAccessStreamEvent,
   AuthSessionId,
   CommandId,
@@ -9,6 +19,7 @@ import {
   type GitManagerServiceError,
   OrchestrationDispatchCommandError,
   type OrchestrationEvent,
+  type OrchestrationShellStreamEvent,
   OrchestrationGetFullThreadDiffError,
   OrchestrationGetSnapshotError,
   OrchestrationGetTurnDiffError,
@@ -16,6 +27,7 @@ import {
   ProjectSearchEntriesError,
   ProjectWriteFileError,
   OrchestrationReplayEventsError,
+  FilesystemBrowseError,
   ThreadId,
   type TerminalEvent,
   WS_METHODS,
@@ -25,42 +37,85 @@ import { clamp } from "effect/Number";
 import { HttpRouter, HttpServerRequest } from "effect/unstable/http";
 import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
 
-import { CheckpointDiffQuery } from "./checkpointing/Services/CheckpointDiffQuery";
-import { ServerConfig } from "./config";
-import { GitCore } from "./git/Services/GitCore";
-import { GitManager } from "./git/Services/GitManager";
-import { GitStatusBroadcaster } from "./git/Services/GitStatusBroadcaster";
-import { Keybindings } from "./keybindings";
-import { Open, resolveAvailableEditors } from "./open";
-import { normalizeDispatchCommand } from "./orchestration/Normalizer";
-import { OrchestrationEngineService } from "./orchestration/Services/OrchestrationEngine";
-import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery";
+import { CheckpointDiffQuery } from "./checkpointing/Services/CheckpointDiffQuery.ts";
+import { ServerConfig } from "./config.ts";
+import { Keybindings } from "./keybindings.ts";
+import * as ExternalLauncher from "./process/externalLauncher.ts";
+import { normalizeDispatchCommand } from "./orchestration/Normalizer.ts";
+import { OrchestrationEngineService } from "./orchestration/Services/OrchestrationEngine.ts";
+import { ProjectionSnapshotQuery } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
 import {
   observeRpcEffect,
   observeRpcStream,
   observeRpcStreamEffect,
-} from "./observability/RpcInstrumentation";
-import { ProviderRegistry } from "./provider/Services/ProviderRegistry";
-import { ServerLifecycleEvents } from "./serverLifecycleEvents";
-import { ServerRuntimeStartup } from "./serverRuntimeStartup";
-import { ServerSettingsService } from "./serverSettings";
-import { TerminalManager } from "./terminal/Services/Manager";
-import { WorkspaceEntries } from "./workspace/Services/WorkspaceEntries";
-import { WorkspaceFileSystem } from "./workspace/Services/WorkspaceFileSystem";
-import { WorkspacePathOutsideRootError } from "./workspace/Services/WorkspacePaths";
-import { ProjectSetupScriptRunner } from "./project/Services/ProjectSetupScriptRunner";
-import { RepositoryIdentityResolver } from "./project/Services/RepositoryIdentityResolver";
-import { ServerEnvironment } from "./environment/Services/ServerEnvironment";
-import { ServerAuth } from "./auth/Services/ServerAuth";
+} from "./observability/RpcInstrumentation.ts";
+import { ProviderRegistry } from "./provider/Services/ProviderRegistry.ts";
+import * as ProviderMaintenanceRunner from "./provider/providerMaintenanceRunner.ts";
+import { ServerLifecycleEvents } from "./serverLifecycleEvents.ts";
+import { ServerRuntimeStartup } from "./serverRuntimeStartup.ts";
+import { redactServerSettingsForClient, ServerSettingsService } from "./serverSettings.ts";
+import { TerminalManager } from "./terminal/Services/Manager.ts";
+import { WorkspaceEntries } from "./workspace/Services/WorkspaceEntries.ts";
+import { WorkspaceFileSystem } from "./workspace/Services/WorkspaceFileSystem.ts";
+import { WorkspacePathOutsideRootError } from "./workspace/Services/WorkspacePaths.ts";
+import { VcsStatusBroadcaster } from "./vcs/VcsStatusBroadcaster.ts";
+import { VcsProvisioningService } from "./vcs/VcsProvisioningService.ts";
+import { GitWorkflowService } from "./git/GitWorkflowService.ts";
+import { ProjectSetupScriptRunner } from "./project/Services/ProjectSetupScriptRunner.ts";
+import { RepositoryIdentityResolver } from "./project/Services/RepositoryIdentityResolver.ts";
+import { ServerEnvironment } from "./environment/Services/ServerEnvironment.ts";
+import { ServerAuth } from "./auth/Services/ServerAuth.ts";
+import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
+import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
+import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
+import * as SourceControlDiscoveryLayer from "./sourceControl/SourceControlDiscovery.ts";
+import { SourceControlRepositoryService } from "./sourceControl/SourceControlRepositoryService.ts";
+import * as AzureDevOpsCli from "./sourceControl/AzureDevOpsCli.ts";
+import * as BitbucketApi from "./sourceControl/BitbucketApi.ts";
+import * as GitHubCli from "./sourceControl/GitHubCli.ts";
+import * as GitLabCli from "./sourceControl/GitLabCli.ts";
+import * as SourceControlProviderRegistry from "./sourceControl/SourceControlProviderRegistry.ts";
+import * as GitVcsDriver from "./vcs/GitVcsDriver.ts";
+import * as VcsDriverRegistry from "./vcs/VcsDriverRegistry.ts";
+import * as VcsProjectConfig from "./vcs/VcsProjectConfig.ts";
+import * as VcsProcess from "./vcs/VcsProcess.ts";
 import {
   BootstrapCredentialService,
   type BootstrapCredentialChange,
-} from "./auth/Services/BootstrapCredentialService";
+} from "./auth/Services/BootstrapCredentialService.ts";
 import {
   SessionCredentialService,
   type SessionCredentialChange,
-} from "./auth/Services/SessionCredentialService";
-import { respondToAuthError } from "./auth/http";
+} from "./auth/Services/SessionCredentialService.ts";
+import { respondToAuthError } from "./auth/http.ts";
+const isOrchestrationDispatchCommandError = Schema.is(OrchestrationDispatchCommandError);
+const isWorkspacePathOutsideRootError = Schema.is(WorkspacePathOutsideRootError);
+
+const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
+function isThreadDetailEvent(event: OrchestrationEvent): event is Extract<
+  OrchestrationEvent,
+  {
+    type:
+      | "thread.message-sent"
+      | "thread.proposed-plan-upserted"
+      | "thread.activity-appended"
+      | "thread.turn-diff-completed"
+      | "thread.reverted"
+      | "thread.session-set";
+  }
+> {
+  return (
+    event.type === "thread.message-sent" ||
+    event.type === "thread.proposed-plan-upserted" ||
+    event.type === "thread.activity-appended" ||
+    event.type === "thread.turn-diff-completed" ||
+    event.type === "thread.reverted" ||
+    event.type === "thread.session-set"
+  );
+}
+
+const PROVIDER_STATUS_DEBOUNCE_MS = 200;
 
 function toAuthAccessStreamEvent(
   change: BootstrapCredentialChange | SessionCredentialChange,
@@ -109,12 +164,13 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       const orchestrationEngine = yield* OrchestrationEngineService;
       const checkpointDiffQuery = yield* CheckpointDiffQuery;
       const keybindings = yield* Keybindings;
-      const open = yield* Open;
-      const gitManager = yield* GitManager;
-      const git = yield* GitCore;
-      const gitStatusBroadcaster = yield* GitStatusBroadcaster;
+      const externalLauncher = yield* ExternalLauncher.ExternalLauncher;
+      const gitWorkflow = yield* GitWorkflowService;
+      const vcsProvisioning = yield* VcsProvisioningService;
+      const vcsStatusBroadcaster = yield* VcsStatusBroadcaster;
       const terminalManager = yield* TerminalManager;
       const providerRegistry = yield* ProviderRegistry;
+      const providerMaintenanceRunner = yield* ProviderMaintenanceRunner.ProviderMaintenanceRunner;
       const config = yield* ServerConfig;
       const lifecycleEvents = yield* ServerLifecycleEvents;
       const serverSettings = yield* ServerSettingsService;
@@ -125,8 +181,20 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       const repositoryIdentityResolver = yield* RepositoryIdentityResolver;
       const serverEnvironment = yield* ServerEnvironment;
       const serverAuth = yield* ServerAuth;
+      const sourceControlDiscovery = yield* SourceControlDiscoveryLayer.SourceControlDiscovery;
+      const automaticGitFetchInterval = serverSettings.getSettings.pipe(
+        Effect.map((settings) => settings.automaticGitFetchInterval),
+        Effect.catch((cause) =>
+          Effect.logWarning("Failed to read automatic Git fetch interval setting", {
+            detail: cause.message,
+          }).pipe(Effect.as(DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL)),
+        ),
+      );
+      const sourceControlRepositories = yield* SourceControlRepositoryService;
       const bootstrapCredentials = yield* BootstrapCredentialService;
       const sessions = yield* SessionCredentialService;
+      const processDiagnostics = yield* ProcessDiagnostics.ProcessDiagnostics;
+      const processResourceMonitor = yield* ProcessResourceMonitor.ProcessResourceMonitor;
       const serverCommandId = (tag: string) =>
         CommandId.make(`server:${tag}:${crypto.randomUUID()}`);
 
@@ -161,7 +229,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
         });
 
       const toDispatchCommandError = (cause: unknown, fallbackMessage: string) =>
-        Schema.is(OrchestrationDispatchCommandError)(cause)
+        isOrchestrationDispatchCommandError(cause)
           ? cause
           : new OrchestrationDispatchCommandError({
               message: cause instanceof Error ? cause.message : fallbackMessage,
@@ -170,7 +238,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
 
       const toBootstrapDispatchCommandCauseError = (cause: Cause.Cause<unknown>) => {
         const error = Cause.squash(cause);
-        return Schema.is(OrchestrationDispatchCommandError)(error)
+        return isOrchestrationDispatchCommandError(error)
           ? error
           : new OrchestrationDispatchCommandError({
               message:
@@ -197,9 +265,13 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             return Effect.gen(function* () {
               const workspaceRoot =
                 event.payload.workspaceRoot ??
-                (yield* orchestrationEngine.getReadModel()).projects.find(
-                  (project) => project.id === event.payload.projectId,
-                )?.workspaceRoot ??
+                Option.match(
+                  yield* projectionSnapshotQuery.getProjectShellById(event.payload.projectId),
+                  {
+                    onNone: () => null,
+                    onSome: (project) => project.workspaceRoot,
+                  },
+                ) ??
                 null;
               if (workspaceRoot === null) {
                 return event;
@@ -213,7 +285,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                   repositoryIdentity,
                 },
               } satisfies OrchestrationEvent;
-            });
+            }).pipe(Effect.catch(() => Effect.succeed(event)));
           default:
             return Effect.succeed(event);
         }
@@ -222,6 +294,69 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       const enrichOrchestrationEvents = (events: ReadonlyArray<OrchestrationEvent>) =>
         Effect.forEach(events, enrichProjectEvent, { concurrency: 4 });
 
+      const toShellStreamEvent = (
+        event: OrchestrationEvent,
+      ): Effect.Effect<Option.Option<OrchestrationShellStreamEvent>, never, never> => {
+        switch (event.type) {
+          case "project.created":
+          case "project.meta-updated":
+            return projectionSnapshotQuery.getProjectShellById(event.payload.projectId).pipe(
+              Effect.map((project) =>
+                Option.map(project, (nextProject) => ({
+                  kind: "project-upserted" as const,
+                  sequence: event.sequence,
+                  project: nextProject,
+                })),
+              ),
+              Effect.catch(() => Effect.succeed(Option.none())),
+            );
+          case "project.deleted":
+            return Effect.succeed(
+              Option.some({
+                kind: "project-removed" as const,
+                sequence: event.sequence,
+                projectId: event.payload.projectId,
+              }),
+            );
+          case "thread.deleted":
+          case "thread.archived":
+            return Effect.succeed(
+              Option.some({
+                kind: "thread-removed" as const,
+                sequence: event.sequence,
+                threadId: event.payload.threadId,
+              }),
+            );
+          case "thread.unarchived":
+            return projectionSnapshotQuery.getThreadShellById(event.payload.threadId).pipe(
+              Effect.map((thread) =>
+                Option.map(thread, (nextThread) => ({
+                  kind: "thread-upserted" as const,
+                  sequence: event.sequence,
+                  thread: nextThread,
+                })),
+              ),
+              Effect.catch(() => Effect.succeed(Option.none())),
+            );
+          default:
+            if (event.aggregateKind !== "thread") {
+              return Effect.succeed(Option.none());
+            }
+            return projectionSnapshotQuery
+              .getThreadShellById(ThreadId.make(event.aggregateId))
+              .pipe(
+                Effect.map((thread) =>
+                  Option.map(thread, (nextThread) => ({
+                    kind: "thread-upserted" as const,
+                    sequence: event.sequence,
+                    thread: nextThread,
+                  })),
+                ),
+                Effect.catch(() => Effect.succeed(Option.none())),
+              );
+        }
+      };
+
       const dispatchBootstrapTurnStart = (
         command: Extract<OrchestrationCommand, { type: "thread.turn.start" }>,
       ): Effect.Effect<{ readonly sequence: number }, OrchestrationDispatchCommandError> =>
@@ -279,83 +414,86 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             readonly scriptId: string;
             readonly scriptName: string;
             readonly terminalId: string;
-          }) => {
-            const payload = {
-              scriptId: input.scriptId,
-              scriptName: input.scriptName,
-              terminalId: input.terminalId,
-              worktreePath: input.worktreePath,
-            };
-            return Effect.all([
-              appendSetupScriptActivity({
-                threadId: command.threadId,
-                kind: "setup-script.requested",
-                summary: "Starting setup script",
-                createdAt: input.requestedAt,
-                payload,
-                tone: "info",
-              }),
-              appendSetupScriptActivity({
-                threadId: command.threadId,
-                kind: "setup-script.started",
-                summary: "Setup script started",
-                createdAt: new Date().toISOString(),
-                payload,
-                tone: "info",
-              }),
-            ]).pipe(
-              Effect.asVoid,
-              Effect.catch((error) =>
-                Effect.logWarning(
-                  "bootstrap turn start launched setup script but failed to record setup activity",
-                  {
-                    threadId: command.threadId,
-                    worktreePath: input.worktreePath,
-                    scriptId: input.scriptId,
-                    terminalId: input.terminalId,
-                    detail: error.message,
-                  },
+          }) =>
+            Effect.gen(function* () {
+              const startedAt = yield* nowIso;
+              const payload = {
+                scriptId: input.scriptId,
+                scriptName: input.scriptName,
+                terminalId: input.terminalId,
+                worktreePath: input.worktreePath,
+              };
+              yield* Effect.all([
+                appendSetupScriptActivity({
+                  threadId: command.threadId,
+                  kind: "setup-script.requested",
+                  summary: "Starting setup script",
+                  createdAt: input.requestedAt,
+                  payload,
+                  tone: "info",
+                }),
+                appendSetupScriptActivity({
+                  threadId: command.threadId,
+                  kind: "setup-script.started",
+                  summary: "Setup script started",
+                  createdAt: startedAt,
+                  payload,
+                  tone: "info",
+                }),
+              ]).pipe(
+                Effect.asVoid,
+                Effect.catch((error) =>
+                  Effect.logWarning(
+                    "bootstrap turn start launched setup script but failed to record setup activity",
+                    {
+                      threadId: command.threadId,
+                      worktreePath: input.worktreePath,
+                      scriptId: input.scriptId,
+                      terminalId: input.terminalId,
+                      detail: error.message,
+                    },
+                  ),
                 ),
-              ),
-            );
-          };
+              );
+            });
 
           const runSetupProgram = () =>
-            bootstrap?.runSetupScript && targetWorktreePath
-              ? (() => {
-                  const worktreePath = targetWorktreePath;
-                  const requestedAt = new Date().toISOString();
-                  return projectSetupScriptRunner
-                    .runForThread({
-                      threadId: command.threadId,
-                      ...(targetProjectId ? { projectId: targetProjectId } : {}),
-                      ...(targetProjectCwd ? { projectCwd: targetProjectCwd } : {}),
-                      worktreePath,
-                    })
-                    .pipe(
-                      Effect.matchEffect({
-                        onFailure: (error) =>
-                          recordSetupScriptLaunchFailure({
-                            error,
-                            requestedAt,
-                            worktreePath,
-                          }),
-                        onSuccess: (setupResult) => {
-                          if (setupResult.status !== "started") {
-                            return Effect.void;
-                          }
-                          return recordSetupScriptStarted({
-                            requestedAt,
-                            worktreePath,
-                            scriptId: setupResult.scriptId,
-                            scriptName: setupResult.scriptName,
-                            terminalId: setupResult.terminalId,
-                          });
-                        },
+            Effect.gen(function* () {
+              if (!bootstrap?.runSetupScript || !targetWorktreePath) {
+                return;
+              }
+              const worktreePath = targetWorktreePath;
+              const requestedAt = yield* nowIso;
+              yield* projectSetupScriptRunner
+                .runForThread({
+                  threadId: command.threadId,
+                  ...(targetProjectId ? { projectId: targetProjectId } : {}),
+                  ...(targetProjectCwd ? { projectCwd: targetProjectCwd } : {}),
+                  worktreePath,
+                })
+                .pipe(
+                  Effect.matchEffect({
+                    onFailure: (error) =>
+                      recordSetupScriptLaunchFailure({
+                        error,
+                        requestedAt,
+                        worktreePath,
                       }),
-                    );
-                })()
-              : Effect.void;
+                    onSuccess: (setupResult) => {
+                      if (setupResult.status !== "started") {
+                        return Effect.void;
+                      }
+                      return recordSetupScriptStarted({
+                        requestedAt,
+                        worktreePath,
+                        scriptId: setupResult.scriptId,
+                        scriptName: setupResult.scriptName,
+                        terminalId: setupResult.terminalId,
+                      });
+                    },
+                  }),
+                );
+            });
 
           const bootstrapProgram = Effect.gen(function* () {
             if (bootstrap?.createThread) {
@@ -376,10 +514,10 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             }
 
             if (bootstrap?.prepareWorktree) {
-              const worktree = yield* git.createWorktree({
+              const worktree = yield* gitWorkflow.createWorktree({
                 cwd: bootstrap.prepareWorktree.projectCwd,
-                branch: bootstrap.prepareWorktree.baseBranch,
-                newBranch: bootstrap.prepareWorktree.branch,
+                refName: bootstrap.prepareWorktree.baseBranch,
+                newRefName: bootstrap.prepareWorktree.branch,
                 path: null,
               });
               targetWorktreePath = worktree.worktree.path;
@@ -387,9 +525,10 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                 type: "thread.meta.update",
                 commandId: serverCommandId("bootstrap-thread-meta-update"),
                 threadId: command.threadId,
-                branch: worktree.worktree.branch,
+                branch: worktree.worktree.refName,
                 worktreePath: targetWorktreePath,
               });
+              yield* refreshGitStatus(targetWorktreePath);
             }
 
             yield* runSetupProgram();
@@ -434,7 +573,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       const loadServerConfig = Effect.gen(function* () {
         const keybindingsConfig = yield* keybindings.loadConfigState;
         const providers = yield* providerRegistry.getProviders;
-        const settings = yield* serverSettings.getSettings;
+        const settings = redactServerSettingsForClient(yield* serverSettings.getSettings);
         const environment = yield* serverEnvironment.getDescriptor;
         const auth = yield* serverAuth.getDescriptor();
 
@@ -446,7 +585,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
           keybindings: keybindingsConfig.keybindings,
           issues: keybindingsConfig.issues,
           providers,
-          availableEditors: resolveAvailableEditors(),
+          availableEditors: ExternalLauncher.resolveAvailableEditors(),
           observability: {
             logsDirectoryPath: config.logsDir,
             localTracingEnabled: true,
@@ -462,32 +601,55 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       });
 
       const refreshGitStatus = (cwd: string) =>
-        gitStatusBroadcaster
+        vcsStatusBroadcaster
           .refreshStatus(cwd)
           .pipe(Effect.ignoreCause({ log: true }), Effect.forkDetach, Effect.asVoid);
 
       return WsRpcGroup.of({
-        [ORCHESTRATION_WS_METHODS.getSnapshot]: (_input) =>
-          observeRpcEffect(
-            ORCHESTRATION_WS_METHODS.getSnapshot,
-            projectionSnapshotQuery.getSnapshot().pipe(
-              Effect.mapError(
-                (cause) =>
-                  new OrchestrationGetSnapshotError({
-                    message: "Failed to load orchestration snapshot",
-                    cause,
-                  }),
-              ),
-            ),
-            { "rpc.aggregate": "orchestration" },
-          ),
         [ORCHESTRATION_WS_METHODS.dispatchCommand]: (command) =>
           observeRpcEffect(
             ORCHESTRATION_WS_METHODS.dispatchCommand,
             Effect.gen(function* () {
               const normalizedCommand = yield* normalizeDispatchCommand(command);
+              const shouldStopSessionAfterArchive =
+                normalizedCommand.type === "thread.archive"
+                  ? yield* projectionSnapshotQuery
+                      .getThreadShellById(normalizedCommand.threadId)
+                      .pipe(
+                        Effect.map(
+                          Option.match({
+                            onNone: () => false,
+                            onSome: (thread) =>
+                              thread.session !== null && thread.session.status !== "stopped",
+                          }),
+                        ),
+                        Effect.catch(() => Effect.succeed(false)),
+                      )
+                  : false;
               const result = yield* dispatchNormalizedCommand(normalizedCommand);
               if (normalizedCommand.type === "thread.archive") {
+                if (shouldStopSessionAfterArchive) {
+                  yield* Effect.gen(function* () {
+                    const stopCommand = yield* normalizeDispatchCommand({
+                      type: "thread.session.stop",
+                      commandId: CommandId.make(
+                        `session-stop-for-archive:${normalizedCommand.commandId}`,
+                      ),
+                      threadId: normalizedCommand.threadId,
+                      createdAt: yield* nowIso,
+                    });
+
+                    yield* dispatchNormalizedCommand(stopCommand);
+                  }).pipe(
+                    Effect.catchCause((cause) =>
+                      Effect.logWarning("failed to stop provider session during archive", {
+                        threadId: normalizedCommand.threadId,
+                        cause,
+                      }),
+                    ),
+                  );
+                }
+
                 yield* terminalManager.close({ threadId: normalizedCommand.threadId }).pipe(
                   Effect.catch((error) =>
                     Effect.logWarning("failed to close thread terminals after archive", {
@@ -500,7 +662,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
               return result;
             }).pipe(
               Effect.mapError((cause) =>
-                Schema.is(OrchestrationDispatchCommandError)(cause)
+                isOrchestrationDispatchCommandError(cause)
                   ? cause
                   : new OrchestrationDispatchCommandError({
                       message: "Failed to dispatch orchestration command",
@@ -561,65 +723,112 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             ),
             { "rpc.aggregate": "orchestration" },
           ),
-        [WS_METHODS.subscribeOrchestrationDomainEvents]: (_input) =>
+        [ORCHESTRATION_WS_METHODS.subscribeShell]: (_input) =>
           observeRpcStreamEffect(
-            WS_METHODS.subscribeOrchestrationDomainEvents,
+            ORCHESTRATION_WS_METHODS.subscribeShell,
             Effect.gen(function* () {
-              const snapshot = yield* orchestrationEngine.getReadModel();
-              const fromSequenceExclusive = snapshot.snapshotSequence;
-              const replayEvents: Array<OrchestrationEvent> = yield* Stream.runCollect(
-                orchestrationEngine.readEvents(fromSequenceExclusive),
-              ).pipe(
-                Effect.map((events) => Array.from(events)),
-                Effect.flatMap(enrichOrchestrationEvents),
-                Effect.catch(() => Effect.succeed([] as Array<OrchestrationEvent>)),
+              const snapshot = yield* projectionSnapshotQuery.getShellSnapshot().pipe(
+                Effect.tapError((cause) =>
+                  Effect.logError("orchestration shell snapshot load failed", { cause }),
+                ),
+                Effect.mapError(
+                  (cause) =>
+                    new OrchestrationGetSnapshotError({
+                      message: "Failed to load orchestration shell snapshot",
+                      cause,
+                    }),
+                ),
               );
-              const replayStream = Stream.fromIterable(replayEvents);
+
               const liveStream = orchestrationEngine.streamDomainEvents.pipe(
-                Stream.mapEffect(enrichProjectEvent),
+                Stream.mapEffect(toShellStreamEvent),
+                Stream.flatMap((event) =>
+                  Option.isSome(event) ? Stream.succeed(event.value) : Stream.empty,
+                ),
               );
-              const source = Stream.merge(replayStream, liveStream);
-              type SequenceState = {
-                readonly nextSequence: number;
-                readonly pendingBySequence: Map<number, OrchestrationEvent>;
-              };
-              const state = yield* Ref.make<SequenceState>({
-                nextSequence: fromSequenceExclusive + 1,
-                pendingBySequence: new Map<number, OrchestrationEvent>(),
-              });
 
-              return source.pipe(
-                Stream.mapEffect((event) =>
-                  Ref.modify(
-                    state,
-                    ({
-                      nextSequence,
-                      pendingBySequence,
-                    }): [Array<OrchestrationEvent>, SequenceState] => {
-                      if (event.sequence < nextSequence || pendingBySequence.has(event.sequence)) {
-                        return [[], { nextSequence, pendingBySequence }];
-                      }
+              return Stream.concat(
+                Stream.make({
+                  kind: "snapshot" as const,
+                  snapshot,
+                }),
+                liveStream,
+              );
+            }),
+            { "rpc.aggregate": "orchestration" },
+          ),
+        [ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot]: (_input) =>
+          observeRpcEffect(
+            ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot,
+            projectionSnapshotQuery.getArchivedShellSnapshot().pipe(
+              Effect.tapError((cause) =>
+                Effect.logError("orchestration archived shell snapshot load failed", { cause }),
+              ),
+              Effect.mapError(
+                (cause) =>
+                  new OrchestrationGetSnapshotError({
+                    message: "Failed to load archived orchestration shell snapshot",
+                    cause,
+                  }),
+              ),
+            ),
+            { "rpc.aggregate": "orchestration" },
+          ),
+        [ORCHESTRATION_WS_METHODS.subscribeThread]: (input) =>
+          observeRpcStreamEffect(
+            ORCHESTRATION_WS_METHODS.subscribeThread,
+            Effect.gen(function* () {
+              const [threadDetail, snapshotSequence] = yield* Effect.all([
+                projectionSnapshotQuery.getThreadDetailById(input.threadId).pipe(
+                  Effect.mapError(
+                    (cause) =>
+                      new OrchestrationGetSnapshotError({
+                        message: `Failed to load thread ${input.threadId}`,
+                        cause,
+                      }),
+                  ),
+                ),
+                projectionSnapshotQuery.getSnapshotSequence().pipe(
+                  Effect.map(({ snapshotSequence }) => snapshotSequence),
+                  Effect.mapError(
+                    (cause) =>
+                      new OrchestrationGetSnapshotError({
+                        message: "Failed to load orchestration snapshot sequence",
+                        cause,
+                      }),
+                  ),
+                ),
+              ]);
 
-                      const updatedPending = new Map(pendingBySequence);
-                      updatedPending.set(event.sequence, event);
-
-                      const emit: Array<OrchestrationEvent> = [];
-                      let expected = nextSequence;
-                      for (;;) {
-                        const expectedEvent = updatedPending.get(expected);
-                        if (!expectedEvent) {
-                          break;
-                        }
-                        emit.push(expectedEvent);
-                        updatedPending.delete(expected);
-                        expected += 1;
-                      }
+              if (Option.isNone(threadDetail)) {
+                return yield* new OrchestrationGetSnapshotError({
+                  message: `Thread ${input.threadId} was not found`,
+                  cause: input.threadId,
+                });
+              }
 
-                      return [emit, { nextSequence: expected, pendingBySequence: updatedPending }];
-                    },
-                  ),
+              const liveStream = orchestrationEngine.streamDomainEvents.pipe(
+                Stream.filter(
+                  (event) =>
+                    event.aggregateKind === "thread" &&
+                    event.aggregateId === input.threadId &&
+                    isThreadDetailEvent(event),
                 ),
-                Stream.flatMap((events) => Stream.fromIterable(events)),
+                Stream.map((event) => ({
+                  kind: "event" as const,
+                  event,
+                })),
+              );
+
+              return Stream.concat(
+                Stream.make({
+                  kind: "snapshot" as const,
+                  snapshot: {
+                    snapshotSequence,
+                    thread: threadDetail.value,
+                  },
+                }),
+                liveStream,
               );
             }),
             { "rpc.aggregate": "orchestration" },
@@ -628,12 +837,23 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
           observeRpcEffect(WS_METHODS.serverGetConfig, loadServerConfig, {
             "rpc.aggregate": "server",
           }),
-        [WS_METHODS.serverRefreshProviders]: (_input) =>
+        [WS_METHODS.serverRefreshProviders]: (input) =>
           observeRpcEffect(
             WS_METHODS.serverRefreshProviders,
-            providerRegistry.refresh().pipe(Effect.map((providers) => ({ providers }))),
+            (input.instanceId !== undefined
+              ? providerRegistry.refreshInstance(input.instanceId)
+              : providerRegistry.refresh()
+            ).pipe(Effect.map((providers) => ({ providers }))),
             { "rpc.aggregate": "server" },
           ),
+        [WS_METHODS.serverUpdateProvider]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.serverUpdateProvider,
+            providerMaintenanceRunner.updateProvider(input),
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
         [WS_METHODS.serverUpsertKeybinding]: (rule) =>
           observeRpcEffect(
             WS_METHODS.serverUpsertKeybinding,
@@ -643,14 +863,92 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             }),
             { "rpc.aggregate": "server" },
           ),
+        [WS_METHODS.serverRemoveKeybinding]: (rule) =>
+          observeRpcEffect(
+            WS_METHODS.serverRemoveKeybinding,
+            Effect.gen(function* () {
+              const keybindingsConfig = yield* keybindings.removeKeybindingRule(rule);
+              return { keybindings: keybindingsConfig, issues: [] };
+            }),
+            { "rpc.aggregate": "server" },
+          ),
         [WS_METHODS.serverGetSettings]: (_input) =>
-          observeRpcEffect(WS_METHODS.serverGetSettings, serverSettings.getSettings, {
+          observeRpcEffect(
+            WS_METHODS.serverGetSettings,
+            serverSettings.getSettings.pipe(Effect.map(redactServerSettingsForClient)),
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
+        [WS_METHODS.serverUpdateSettings]: ({ patch }) =>
+          observeRpcEffect(
+            WS_METHODS.serverUpdateSettings,
+            serverSettings.updateSettings(patch).pipe(Effect.map(redactServerSettingsForClient)),
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
+        [WS_METHODS.serverDiscoverSourceControl]: (_input) =>
+          observeRpcEffect(
+            WS_METHODS.serverDiscoverSourceControl,
+            sourceControlDiscovery.discover,
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
+        [WS_METHODS.serverGetTraceDiagnostics]: (_input) =>
+          observeRpcEffect(
+            WS_METHODS.serverGetTraceDiagnostics,
+            TraceDiagnostics.readTraceDiagnostics({
+              traceFilePath: config.serverTracePath,
+              maxFiles: config.traceMaxFiles,
+            }),
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
+        [WS_METHODS.serverGetProcessDiagnostics]: (_input) =>
+          observeRpcEffect(WS_METHODS.serverGetProcessDiagnostics, processDiagnostics.read, {
             "rpc.aggregate": "server",
           }),
-        [WS_METHODS.serverUpdateSettings]: ({ patch }) =>
-          observeRpcEffect(WS_METHODS.serverUpdateSettings, serverSettings.updateSettings(patch), {
+        [WS_METHODS.serverGetProcessResourceHistory]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.serverGetProcessResourceHistory,
+            processResourceMonitor.readHistory(input),
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
+        [WS_METHODS.serverSignalProcess]: (input) =>
+          observeRpcEffect(WS_METHODS.serverSignalProcess, processDiagnostics.signal(input), {
             "rpc.aggregate": "server",
           }),
+        [WS_METHODS.sourceControlLookupRepository]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.sourceControlLookupRepository,
+            sourceControlRepositories.lookupRepository(input),
+            {
+              "rpc.aggregate": "source-control",
+            },
+          ),
+        [WS_METHODS.sourceControlCloneRepository]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.sourceControlCloneRepository,
+            sourceControlRepositories.cloneRepository(input),
+            {
+              "rpc.aggregate": "source-control",
+            },
+          ),
+        [WS_METHODS.sourceControlPublishRepository]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.sourceControlPublishRepository,
+            sourceControlRepositories
+              .publishRepository(input)
+              .pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
+            {
+              "rpc.aggregate": "source-control",
+            },
+          ),
         [WS_METHODS.projectsSearchEntries]: (input) =>
           observeRpcEffect(
             WS_METHODS.projectsSearchEntries,
@@ -670,7 +968,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             WS_METHODS.projectsWriteFile,
             workspaceFileSystem.writeFile(input).pipe(
               Effect.mapError((cause) => {
-                const message = Schema.is(WorkspacePathOutsideRootError)(cause)
+                const message = isWorkspacePathOutsideRootError(cause)
                   ? "Workspace file path must stay within the project root."
                   : "Failed to write workspace file";
                 return new ProjectWriteFileError({
@@ -682,29 +980,45 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             { "rpc.aggregate": "workspace" },
           ),
         [WS_METHODS.shellOpenInEditor]: (input) =>
-          observeRpcEffect(WS_METHODS.shellOpenInEditor, open.openInEditor(input), {
+          observeRpcEffect(WS_METHODS.shellOpenInEditor, externalLauncher.launchEditor(input), {
             "rpc.aggregate": "workspace",
           }),
-        [WS_METHODS.subscribeGitStatus]: (input) =>
+        [WS_METHODS.filesystemBrowse]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.filesystemBrowse,
+            workspaceEntries.browse(input).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new FilesystemBrowseError({
+                    message: cause.detail,
+                    cause,
+                  }),
+              ),
+            ),
+            { "rpc.aggregate": "workspace" },
+          ),
+        [WS_METHODS.subscribeVcsStatus]: (input) =>
           observeRpcStream(
-            WS_METHODS.subscribeGitStatus,
-            gitStatusBroadcaster.streamStatus(input),
+            WS_METHODS.subscribeVcsStatus,
+            vcsStatusBroadcaster.streamStatus(input, {
+              automaticRemoteRefreshInterval: automaticGitFetchInterval,
+            }),
             {
-              "rpc.aggregate": "git",
+              "rpc.aggregate": "vcs",
             },
           ),
-        [WS_METHODS.gitRefreshStatus]: (input) =>
+        [WS_METHODS.vcsRefreshStatus]: (input) =>
           observeRpcEffect(
-            WS_METHODS.gitRefreshStatus,
-            gitStatusBroadcaster.refreshStatus(input.cwd),
+            WS_METHODS.vcsRefreshStatus,
+            vcsStatusBroadcaster.refreshStatus(input.cwd),
             {
-              "rpc.aggregate": "git",
+              "rpc.aggregate": "vcs",
             },
           ),
-        [WS_METHODS.gitPull]: (input) =>
+        [WS_METHODS.vcsPull]: (input) =>
           observeRpcEffect(
-            WS_METHODS.gitPull,
-            git.pullCurrentBranch(input.cwd).pipe(
+            WS_METHODS.vcsPull,
+            gitWorkflow.pullCurrentBranch(input.cwd).pipe(
               Effect.matchCauseEffect({
                 onFailure: (cause) => Effect.failCause(cause),
                 onSuccess: (result) =>
@@ -717,7 +1031,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
           observeRpcStream(
             WS_METHODS.gitRunStackedAction,
             Stream.callback<GitActionProgressEvent, GitManagerServiceError>((queue) =>
-              gitManager
+              gitWorkflow
                 .runStackedAction(input, {
                   actionId: input.actionId,
                   progressReporter: {
@@ -734,55 +1048,59 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                   }),
                 ),
             ),
-            { "rpc.aggregate": "git" },
+            { "rpc.aggregate": "vcs" },
           ),
         [WS_METHODS.gitResolvePullRequest]: (input) =>
-          observeRpcEffect(WS_METHODS.gitResolvePullRequest, gitManager.resolvePullRequest(input), {
-            "rpc.aggregate": "git",
-          }),
+          observeRpcEffect(
+            WS_METHODS.gitResolvePullRequest,
+            gitWorkflow.resolvePullRequest(input),
+            {
+              "rpc.aggregate": "git",
+            },
+          ),
         [WS_METHODS.gitPreparePullRequestThread]: (input) =>
           observeRpcEffect(
             WS_METHODS.gitPreparePullRequestThread,
-            gitManager
+            gitWorkflow
               .preparePullRequestThread(input)
               .pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
             { "rpc.aggregate": "git" },
           ),
-        [WS_METHODS.gitListBranches]: (input) =>
-          observeRpcEffect(WS_METHODS.gitListBranches, git.listBranches(input), {
-            "rpc.aggregate": "git",
+        [WS_METHODS.vcsListRefs]: (input) =>
+          observeRpcEffect(WS_METHODS.vcsListRefs, gitWorkflow.listRefs(input), {
+            "rpc.aggregate": "vcs",
           }),
-        [WS_METHODS.gitCreateWorktree]: (input) =>
+        [WS_METHODS.vcsCreateWorktree]: (input) =>
           observeRpcEffect(
-            WS_METHODS.gitCreateWorktree,
-            git.createWorktree(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
-            { "rpc.aggregate": "git" },
+            WS_METHODS.vcsCreateWorktree,
+            gitWorkflow.createWorktree(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
+            { "rpc.aggregate": "vcs" },
           ),
-        [WS_METHODS.gitRemoveWorktree]: (input) =>
+        [WS_METHODS.vcsRemoveWorktree]: (input) =>
           observeRpcEffect(
-            WS_METHODS.gitRemoveWorktree,
-            git.removeWorktree(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
-            { "rpc.aggregate": "git" },
+            WS_METHODS.vcsRemoveWorktree,
+            gitWorkflow.removeWorktree(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
+            { "rpc.aggregate": "vcs" },
           ),
-        [WS_METHODS.gitCreateBranch]: (input) =>
+        [WS_METHODS.vcsCreateRef]: (input) =>
           observeRpcEffect(
-            WS_METHODS.gitCreateBranch,
-            git.createBranch(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
-            { "rpc.aggregate": "git" },
+            WS_METHODS.vcsCreateRef,
+            gitWorkflow.createRef(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
+            { "rpc.aggregate": "vcs" },
           ),
-        [WS_METHODS.gitCheckout]: (input) =>
+        [WS_METHODS.vcsSwitchRef]: (input) =>
           observeRpcEffect(
-            WS_METHODS.gitCheckout,
-            Effect.scoped(git.checkoutBranch(input)).pipe(
-              Effect.tap(() => refreshGitStatus(input.cwd)),
-            ),
-            { "rpc.aggregate": "git" },
+            WS_METHODS.vcsSwitchRef,
+            gitWorkflow.switchRef(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
+            { "rpc.aggregate": "vcs" },
           ),
-        [WS_METHODS.gitInit]: (input) =>
+        [WS_METHODS.vcsInit]: (input) =>
           observeRpcEffect(
-            WS_METHODS.gitInit,
-            git.initRepo(input).pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
-            { "rpc.aggregate": "git" },
+            WS_METHODS.vcsInit,
+            vcsProvisioning
+              .initRepository(input)
+              .pipe(Effect.tap(() => refreshGitStatus(input.cwd))),
+            { "rpc.aggregate": "vcs" },
           ),
         [WS_METHODS.terminalOpen]: (input) =>
           observeRpcEffect(WS_METHODS.terminalOpen, terminalManager.open(input), {
@@ -828,6 +1146,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                   version: 1 as const,
                   type: "keybindingsUpdated" as const,
                   payload: {
+                    keybindings: event.keybindings,
                     issues: event.issues,
                   },
                 })),
@@ -838,8 +1157,10 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                   type: "providerStatuses" as const,
                   payload: { providers },
                 })),
+                Stream.debounce(Duration.millis(PROVIDER_STATUS_DEBOUNCE_MS)),
               );
               const settingsUpdates = serverSettings.streamChanges.pipe(
+                Stream.map((settings) => redactServerSettingsForClient(settings)),
                 Stream.map((settings) => ({
                   version: 1 as const,
                   type: "settingsUpdated" as const,
@@ -847,13 +1168,22 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                 })),
               );
 
+              yield* providerRegistry
+                .refresh()
+                .pipe(Effect.ignoreCause({ log: true }), Effect.forkScoped);
+
+              const liveUpdates = Stream.merge(
+                keybindingsUpdates,
+                Stream.merge(providerStatuses, settingsUpdates),
+              );
+
               return Stream.concat(
                 Stream.make({
                   version: 1 as const,
                   type: "snapshot" as const,
                   config: yield* loadServerConfig,
                 }),
-                Stream.merge(keybindingsUpdates, Stream.merge(providerStatuses, settingsUpdates)),
+                liveUpdates,
               );
             }),
             { "rpc.aggregate": "server" },
@@ -920,14 +1250,34 @@ export const websocketRpcRouteLayer = Layer.unwrap(
         const sessions = yield* SessionCredentialService;
         const session = yield* serverAuth.authenticateWebSocketUpgrade(request);
         const rpcWebSocketHttpEffect = yield* RpcServer.toHttpEffectWebsocket(WsRpcGroup, {
-          spanPrefix: "ws.rpc",
-          spanAttributes: {
-            "rpc.transport": "websocket",
-            "rpc.system": "effect-rpc",
-          },
+          disableTracing: true,
         }).pipe(
           Effect.provide(
-            makeWsRpcLayer(session.sessionId).pipe(Layer.provideMerge(RpcSerialization.layerJson)),
+            makeWsRpcLayer(session.sessionId).pipe(
+              Layer.provideMerge(RpcSerialization.layerJson),
+              Layer.provide(ProviderMaintenanceRunner.layer),
+              Layer.provide(
+                SourceControlDiscoveryLayer.layer.pipe(
+                  Layer.provide(
+                    SourceControlProviderRegistry.layer.pipe(
+                      Layer.provide(
+                        Layer.mergeAll(
+                          AzureDevOpsCli.layer,
+                          BitbucketApi.layer,
+                          GitHubCli.layer,
+                          GitLabCli.layer,
+                        ),
+                      ),
+                      Layer.provideMerge(GitVcsDriver.layer),
+                      Layer.provide(
+                        VcsDriverRegistry.layer.pipe(Layer.provide(VcsProjectConfig.layer)),
+                      ),
+                    ),
+                  ),
+                  Layer.provide(VcsProcess.layer),
+                ),
+              ),
+            ),
           ),
         );
         return yield* Effect.acquireUseRelease(
diff --git a/apps/server/tsconfig.json b/apps/server/tsconfig.json
index 07d52467f51..b86bbf1f16c 100644
--- a/apps/server/tsconfig.json
+++ b/apps/server/tsconfig.json
@@ -3,23 +3,7 @@
   "compilerOptions": {
     "composite": true,
     "types": ["node", "bun"],
-    "lib": ["ES2023", "esnext.disposable"],
-    "noEmit": true,
-    "allowImportingTsExtensions": true,
-    "plugins": [
-      {
-        "name": "@effect/language-service",
-        "namespaceImportPackages": ["@effect/platform-node"],
-        "diagnosticSeverity": {
-          "importFromBarrel": "error",
-          "anyUnknownInErrorContext": "warning",
-          "instanceOfSchema": "warning",
-          "deterministicKeys": "warning",
-          "preferSchemaOverJson": "off",
-          "globalErrorInEffectFailure": "off"
-        }
-      }
-    ]
+    "lib": ["ESNext", "esnext.disposable"]
   },
   "include": ["src", "tsdown.config.ts", "scripts", "integration", "../../scripts/lib"]
 }
diff --git a/apps/server/tsdown.config.ts b/apps/server/tsdown.config.ts
index f11dd37869b..8f1cfc2136f 100644
--- a/apps/server/tsdown.config.ts
+++ b/apps/server/tsdown.config.ts
@@ -1,15 +1,13 @@
 import { defineConfig } from "tsdown";
 
+const internalPackagePrefixes = ["@t3tools/", "effect-acp", "effect-codex-app-server"];
+
 export default defineConfig({
   entry: ["src/bin.ts"],
-  format: ["esm", "cjs"],
-  checks: {
-    legacyCjs: false,
-  },
   outDir: "dist",
   sourcemap: true,
   clean: true,
-  noExternal: (id) => id.startsWith("@t3tools/"),
+  noExternal: (id) => internalPackagePrefixes.some((prefix) => id.startsWith(prefix)),
   inlineOnly: false,
   banner: {
     js: "#!/usr/bin/env node\n",
diff --git a/apps/server/vitest.config.ts b/apps/server/vitest.config.ts
index 1c5b2f0d38d..660d69423d9 100644
--- a/apps/server/vitest.config.ts
+++ b/apps/server/vitest.config.ts
@@ -1,6 +1,6 @@
 import { defineConfig, mergeConfig } from "vitest/config";
 
-import baseConfig from "../../vitest.config";
+import baseConfig from "../../vitest.config.ts";
 
 export default mergeConfig(
   baseConfig,
diff --git a/apps/web/index.html b/apps/web/index.html
index 9f0329b6020..88e1c8b4f23 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -2,7 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, viewport-fit=cover, interactive-widget=resizes-content"
+    />
     <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)" />
     <meta name="theme-color" content="#161616" media="(prefers-color-scheme: dark)" />
     <meta name="theme-color" content="#161616" />
diff --git a/apps/web/package.json b/apps/web/package.json
index a447b3e0efa..03f77c3aba8 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -1,12 +1,11 @@
 {
   "name": "@t3tools/web",
-  "version": "0.0.17",
+  "version": "0.0.24",
   "private": true,
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "prepare": "effect-language-service patch",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
@@ -14,30 +13,30 @@
     "test:browser:install": "playwright install --with-deps chromium"
   },
   "dependencies": {
-    "@base-ui/react": "^1.2.0",
+    "@base-ui/react": "^1.4.1",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@effect/atom-react": "catalog:",
     "@formkit/auto-animate": "^0.9.0",
+    "@legendapp/list": "3.0.0-beta.44",
     "@lexical/react": "^0.41.0",
-    "@pierre/diffs": "^1.1.0-beta.16",
+    "@pierre/diffs": "catalog:",
     "@t3tools/client-runtime": "workspace:*",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
     "@tanstack/react-pacer": "^0.19.4",
     "@tanstack/react-query": "^5.90.0",
     "@tanstack/react-router": "^1.160.2",
-    "@tanstack/react-virtual": "^3.13.18",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "effect": "catalog:",
     "lexical": "^0.41.0",
     "lucide-react": "^0.564.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.4.0",
@@ -49,11 +48,12 @@
     "@tailwindcss/vite": "^4.0.0",
     "@tanstack/router-plugin": "^1.161.0",
     "@types/babel__core": "^7.20.5",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
+    "@types/react": "~19.2.14",
+    "@types/react-dom": "~19.2.3",
+    "@vercel/config": "^0.3.0",
     "@vitejs/plugin-react": "^6.0.0",
     "@vitest/browser-playwright": "^4.0.18",
-    "babel-plugin-react-compiler": "^19.0.0-beta-e552027-20250112",
+    "babel-plugin-react-compiler": "1.0.0",
     "msw": "2.12.11",
     "playwright": "^1.58.2",
     "tailwindcss": "^4.0.0",
diff --git a/apps/web/src/authBootstrap.test.ts b/apps/web/src/authBootstrap.test.ts
index f86d7c5a792..e6f08f147ca 100644
--- a/apps/web/src/authBootstrap.test.ts
+++ b/apps/web/src/authBootstrap.test.ts
@@ -353,6 +353,34 @@ describe("resolveInitialServerAuthGateState", () => {
     expect(fetchMock).toHaveBeenCalledTimes(3);
   });
 
+  it("surfaces a friendly error message when an invalid pairing token is submitted", async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValueOnce(
+      jsonResponse(
+        {
+          error: "Invalid bootstrap credential.",
+        },
+        {
+          status: 401,
+        },
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { submitServerAuthCredential } = await import("./environments/primary");
+
+    await expect(submitServerAuthCredential("bad-token")).rejects.toThrow(
+      "Invalid pairing token. Check the token and try again.",
+    );
+    expect(fetchMock).toHaveBeenCalledWith("http://localhost/api/auth/bootstrap", {
+      body: JSON.stringify({ credential: "bad-token" }),
+      credentials: "include",
+      headers: {
+        "content-type": "application/json",
+      },
+      method: "POST",
+    });
+  });
+
   it("waits for the authenticated session to become observable after silent desktop bootstrap", async () => {
     vi.useFakeTimers();
     const fetchMock = vi
@@ -424,7 +452,7 @@ describe("resolveInitialServerAuthGateState", () => {
     expect(fetchMock.mock.calls[3]?.[0]).toBe("http://localhost:3773/api/auth/session");
   });
 
-  it("revalidates the server session state after a previous authenticated result", async () => {
+  it("memoizes the authenticated gate state after the first successful read", async () => {
     const fetchMock = vi
       .fn<typeof fetch>()
       .mockResolvedValueOnce(
@@ -459,15 +487,9 @@ describe("resolveInitialServerAuthGateState", () => {
       status: "authenticated",
     });
     await expect(resolveInitialServerAuthGateState()).resolves.toEqual({
-      status: "requires-auth",
-      auth: {
-        policy: "loopback-browser",
-        bootstrapMethods: ["one-time-token"],
-        sessionMethods: ["browser-session-cookie"],
-        sessionCookieName: "t3_session",
-      },
+      status: "authenticated",
     });
-    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
   });
 
   it("creates a pairing credential from the authenticated auth endpoint", async () => {
diff --git a/apps/web/src/branding.test.ts b/apps/web/src/branding.test.ts
new file mode 100644
index 00000000000..096fc16ecc0
--- /dev/null
+++ b/apps/web/src/branding.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const originalWindow = globalThis.window;
+
+afterEach(() => {
+  vi.resetModules();
+
+  if (originalWindow === undefined) {
+    Reflect.deleteProperty(globalThis, "window");
+    return;
+  }
+
+  globalThis.window = originalWindow;
+});
+
+describe("branding", () => {
+  it("uses injected desktop branding when available", async () => {
+    Object.defineProperty(globalThis, "window", {
+      configurable: true,
+      value: {
+        desktopBridge: {
+          getAppBranding: () => ({
+            baseName: "T3 Code",
+            stageLabel: "Nightly",
+            displayName: "T3 Code (Nightly)",
+          }),
+        },
+      },
+    });
+
+    const branding = await import("./branding");
+
+    expect(branding.APP_BASE_NAME).toBe("T3 Code");
+    expect(branding.APP_STAGE_LABEL).toBe("Nightly");
+    expect(branding.APP_DISPLAY_NAME).toBe("T3 Code (Nightly)");
+  });
+
+  it("normalizes hosted app channel metadata", async () => {
+    vi.stubEnv("VITE_HOSTED_APP_CHANNEL", "nightly");
+
+    const branding = await import("./branding");
+
+    expect(branding.HOSTED_APP_CHANNEL).toBe("nightly");
+    expect(branding.HOSTED_APP_CHANNEL_LABEL).toBe("Nightly");
+    expect(branding.APP_STAGE_LABEL).toBe("Nightly");
+    expect(branding.APP_DISPLAY_NAME).toBe("T3 Code (Nightly)");
+  });
+
+  it("ignores unknown hosted app channels", async () => {
+    vi.stubEnv("VITE_HOSTED_APP_CHANNEL", "preview");
+
+    const branding = await import("./branding");
+
+    expect(branding.HOSTED_APP_CHANNEL).toBeNull();
+    expect(branding.HOSTED_APP_CHANNEL_LABEL).toBeNull();
+  });
+});
diff --git a/apps/web/src/branding.ts b/apps/web/src/branding.ts
index bffd9838158..5c1309ca06b 100644
--- a/apps/web/src/branding.ts
+++ b/apps/web/src/branding.ts
@@ -1,4 +1,25 @@
-export const APP_BASE_NAME = "T3 Code";
-export const APP_STAGE_LABEL = import.meta.env.DEV ? "Dev" : "Alpha";
-export const APP_DISPLAY_NAME = `${APP_BASE_NAME} (${APP_STAGE_LABEL})`;
+import type { DesktopAppBranding } from "@t3tools/contracts";
+
+function readInjectedDesktopAppBranding(): DesktopAppBranding | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  return window.desktopBridge?.getAppBranding?.() ?? null;
+}
+
+const injectedDesktopAppBranding = readInjectedDesktopAppBranding();
+const hostedAppChannel = import.meta.env.VITE_HOSTED_APP_CHANNEL?.trim().toLowerCase();
+
+export const HOSTED_APP_CHANNEL =
+  hostedAppChannel === "latest" || hostedAppChannel === "nightly" ? hostedAppChannel : null;
+export const HOSTED_APP_CHANNEL_LABEL =
+  HOSTED_APP_CHANNEL === "nightly" ? "Nightly" : HOSTED_APP_CHANNEL === "latest" ? "Latest" : null;
+export const APP_BASE_NAME = injectedDesktopAppBranding?.baseName ?? "T3 Code";
+export const APP_STAGE_LABEL =
+  injectedDesktopAppBranding?.stageLabel ??
+  HOSTED_APP_CHANNEL_LABEL ??
+  (import.meta.env.DEV ? "Dev" : "Alpha");
+export const APP_DISPLAY_NAME =
+  injectedDesktopAppBranding?.displayName ?? `${APP_BASE_NAME} (${APP_STAGE_LABEL})`;
 export const APP_VERSION = import.meta.env.APP_VERSION || "0.0.0";
diff --git a/apps/web/src/chat-scroll.test.ts b/apps/web/src/chat-scroll.test.ts
deleted file mode 100644
index 5311fb40aed..00000000000
--- a/apps/web/src/chat-scroll.test.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { AUTO_SCROLL_BOTTOM_THRESHOLD_PX, isScrollContainerNearBottom } from "./chat-scroll";
-
-describe("isScrollContainerNearBottom", () => {
-  it("returns true when already at bottom", () => {
-    expect(
-      isScrollContainerNearBottom({
-        scrollTop: 600,
-        clientHeight: 400,
-        scrollHeight: 1_000,
-      }),
-    ).toBe(true);
-  });
-
-  it("returns true when within the auto-scroll threshold", () => {
-    expect(
-      isScrollContainerNearBottom({
-        scrollTop: 540,
-        clientHeight: 400,
-        scrollHeight: 1_000,
-      }),
-    ).toBe(true);
-  });
-
-  it("returns false when the user is meaningfully above the bottom", () => {
-    expect(
-      isScrollContainerNearBottom({
-        scrollTop: 520,
-        clientHeight: 400,
-        scrollHeight: 1_000,
-      }),
-    ).toBe(false);
-  });
-
-  it("clamps negative thresholds to zero", () => {
-    expect(
-      isScrollContainerNearBottom(
-        {
-          scrollTop: 539,
-          clientHeight: 400,
-          scrollHeight: 1_000,
-        },
-        -1,
-      ),
-    ).toBe(false);
-  });
-
-  it("falls back to the default threshold for non-finite values", () => {
-    expect(
-      isScrollContainerNearBottom(
-        {
-          scrollTop: 540,
-          clientHeight: 400,
-          scrollHeight: 1_000,
-        },
-        Number.NaN,
-      ),
-    ).toBe(true);
-    expect(AUTO_SCROLL_BOTTOM_THRESHOLD_PX).toBe(64);
-  });
-});
diff --git a/apps/web/src/chat-scroll.ts b/apps/web/src/chat-scroll.ts
deleted file mode 100644
index 35190ab1b94..00000000000
--- a/apps/web/src/chat-scroll.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-export const AUTO_SCROLL_BOTTOM_THRESHOLD_PX = 64;
-
-interface ScrollPosition {
-  scrollTop: number;
-  clientHeight: number;
-  scrollHeight: number;
-}
-
-export function isScrollContainerNearBottom(
-  position: ScrollPosition,
-  thresholdPx = AUTO_SCROLL_BOTTOM_THRESHOLD_PX,
-): boolean {
-  const threshold = Number.isFinite(thresholdPx)
-    ? Math.max(0, thresholdPx)
-    : AUTO_SCROLL_BOTTOM_THRESHOLD_PX;
-
-  const { scrollTop, clientHeight, scrollHeight } = position;
-  if (![scrollTop, clientHeight, scrollHeight].every(Number.isFinite)) {
-    return true;
-  }
-
-  const distanceFromBottom = scrollHeight - clientHeight - scrollTop;
-  return distanceFromBottom <= threshold;
-}
diff --git a/apps/web/src/clientPersistenceStorage.test.ts b/apps/web/src/clientPersistenceStorage.test.ts
index a74ce18ac30..e02168e09b3 100644
--- a/apps/web/src/clientPersistenceStorage.test.ts
+++ b/apps/web/src/clientPersistenceStorage.test.ts
@@ -10,6 +10,12 @@ const savedRegistryRecord: PersistedSavedEnvironmentRecord = {
   wsBaseUrl: "wss://remote.example.com/",
   createdAt: "2026-04-09T00:00:00.000Z",
   lastConnectedAt: null,
+  desktopSsh: {
+    alias: "devbox",
+    hostname: "devbox.example.com",
+    username: "julius",
+    port: 22,
+  },
 };
 
 function createLocalStorageStub(): Storage {
diff --git a/apps/web/src/clientPersistenceStorage.ts b/apps/web/src/clientPersistenceStorage.ts
index 70f51d5c30a..30c949b37ac 100644
--- a/apps/web/src/clientPersistenceStorage.ts
+++ b/apps/web/src/clientPersistenceStorage.ts
@@ -19,6 +19,14 @@ const BrowserSavedEnvironmentRecordSchema = Schema.Struct({
   wsBaseUrl: Schema.String,
   createdAt: Schema.String,
   lastConnectedAt: Schema.NullOr(Schema.String),
+  desktopSsh: Schema.optionalKey(
+    Schema.Struct({
+      alias: Schema.String,
+      hostname: Schema.String,
+      username: Schema.NullOr(Schema.String),
+      port: Schema.NullOr(Schema.Number),
+    }),
+  ),
   bearerToken: Schema.optionalKey(Schema.String),
 });
 type BrowserSavedEnvironmentRecord = typeof BrowserSavedEnvironmentRecordSchema.Type;
@@ -37,7 +45,7 @@ function hasWindow(): boolean {
 function toPersistedSavedEnvironmentRecord(
   record: PersistedSavedEnvironmentRecord,
 ): PersistedSavedEnvironmentRecord {
-  return {
+  const nextRecord = {
     environmentId: record.environmentId,
     label: record.label,
     httpBaseUrl: record.httpBaseUrl,
@@ -45,6 +53,7 @@ function toPersistedSavedEnvironmentRecord(
     createdAt: record.createdAt,
     lastConnectedAt: record.lastConnectedAt,
   };
+  return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
 }
 
 export function readBrowserClientSettings(): ClientSettings | null {
@@ -135,6 +144,7 @@ export function writeBrowserSavedEnvironmentRegistry(
             wsBaseUrl: record.wsBaseUrl,
             createdAt: record.createdAt,
             lastConnectedAt: record.lastConnectedAt,
+            ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
             bearerToken,
           }
         : toPersistedSavedEnvironmentRecord(record);
@@ -166,7 +176,7 @@ export function writeBrowserSavedEnvironmentSecret(
         return record;
       }
       found = true;
-      return {
+      const nextRecord = {
         environmentId: record.environmentId,
         label: record.label,
         httpBaseUrl: record.httpBaseUrl,
@@ -174,7 +184,8 @@ export function writeBrowserSavedEnvironmentSecret(
         createdAt: record.createdAt,
         lastConnectedAt: record.lastConnectedAt,
         bearerToken: secret,
-      } satisfies BrowserSavedEnvironmentRecord;
+      };
+      return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
     }),
   });
   return found;
diff --git a/apps/web/src/commandPaletteStore.ts b/apps/web/src/commandPaletteStore.ts
index 4f291d5a480..04b25529f2f 100644
--- a/apps/web/src/commandPaletteStore.ts
+++ b/apps/web/src/commandPaletteStore.ts
@@ -1,13 +1,32 @@
 import { create } from "zustand";
 
+interface CommandPaletteOpenIntent {
+  kind: "add-project";
+  requestId: number;
+}
+
 interface CommandPaletteStore {
   open: boolean;
+  openIntent: CommandPaletteOpenIntent | null;
   setOpen: (open: boolean) => void;
   toggleOpen: () => void;
+  openAddProject: () => void;
+  clearOpenIntent: () => void;
 }
 
 export const useCommandPaletteStore = create<CommandPaletteStore>((set) => ({
   open: false,
-  setOpen: (open) => set({ open }),
-  toggleOpen: () => set((state) => ({ open: !state.open })),
+  openIntent: null,
+  setOpen: (open) => set({ open, ...(open ? {} : { openIntent: null }) }),
+  toggleOpen: () =>
+    set((state) => ({ open: !state.open, ...(state.open ? { openIntent: null } : {}) })),
+  openAddProject: () =>
+    set((state) => ({
+      open: true,
+      openIntent: {
+        kind: "add-project",
+        requestId: (state.openIntent?.requestId ?? 0) + 1,
+      },
+    })),
+  clearOpenIntent: () => set({ openIntent: null }),
 }));
diff --git a/apps/web/src/components/AnimatedHeight.tsx b/apps/web/src/components/AnimatedHeight.tsx
new file mode 100644
index 00000000000..d0e21b3907e
--- /dev/null
+++ b/apps/web/src/components/AnimatedHeight.tsx
@@ -0,0 +1,91 @@
+"use client";
+
+import { type ReactNode, useEffect, useLayoutEffect, useRef, useState } from "react";
+
+const HEIGHT_TRANSITION_FALLBACK_MS = 250;
+
+export function AnimatedHeight({ children }: { readonly children: ReactNode }) {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [heightState, setHeightState] = useState<{
+    readonly height: number | null;
+    readonly isClipping: boolean;
+  }>({ height: null, isClipping: false });
+
+  useEffect(() => {
+    if (!heightState.isClipping) return;
+    const timeoutId = window.setTimeout(() => {
+      setHeightState((currentState) =>
+        currentState.isClipping ? { ...currentState, isClipping: false } : currentState,
+      );
+    }, HEIGHT_TRANSITION_FALLBACK_MS);
+    return () => window.clearTimeout(timeoutId);
+  }, [heightState.height, heightState.isClipping]);
+
+  useLayoutEffect(() => {
+    const element = contentRef.current;
+    if (!element) return;
+    let firstFrameId: number | null = null;
+    let secondFrameId: number | null = null;
+
+    const updateHeight = () => {
+      const nextHeight = Math.ceil(element.scrollHeight || element.getBoundingClientRect().height);
+      setHeightState((currentState) => {
+        if (currentState.height === nextHeight) return currentState;
+        return {
+          height: nextHeight,
+          isClipping: currentState.height !== null,
+        };
+      });
+    };
+    const cancelPendingFrames = () => {
+      if (firstFrameId !== null) {
+        window.cancelAnimationFrame(firstFrameId);
+        firstFrameId = null;
+      }
+      if (secondFrameId !== null) {
+        window.cancelAnimationFrame(secondFrameId);
+        secondFrameId = null;
+      }
+    };
+    const updateHeightAfterPaint = () => {
+      cancelPendingFrames();
+      updateHeight();
+      firstFrameId = window.requestAnimationFrame(() => {
+        firstFrameId = null;
+        updateHeight();
+        secondFrameId = window.requestAnimationFrame(() => {
+          secondFrameId = null;
+          updateHeight();
+        });
+      });
+    };
+
+    updateHeightAfterPaint();
+    const resizeObserver = new ResizeObserver(updateHeightAfterPaint);
+    resizeObserver.observe(element);
+    return () => {
+      resizeObserver.disconnect();
+      cancelPendingFrames();
+    };
+  }, []);
+
+  return (
+    <div
+      data-slot="animated-height"
+      className="transition-[height] duration-200 ease-out motion-reduce:transition-none"
+      style={
+        heightState.height === null
+          ? undefined
+          : { height: heightState.height, overflow: heightState.isClipping ? "hidden" : "visible" }
+      }
+      onTransitionEnd={(event) => {
+        if (event.target !== event.currentTarget || event.propertyName !== "height") return;
+        setHeightState((currentState) =>
+          currentState.isClipping ? { ...currentState, isClipping: false } : currentState,
+        );
+      }}
+    >
+      <div ref={contentRef}>{children}</div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/AppSidebarLayout.tsx b/apps/web/src/components/AppSidebarLayout.tsx
index a2b27bb1e96..d98f30a1e5c 100644
--- a/apps/web/src/components/AppSidebarLayout.tsx
+++ b/apps/web/src/components/AppSidebarLayout.tsx
@@ -3,14 +3,39 @@ import { useNavigate } from "@tanstack/react-router";
 
 import ThreadSidebar from "./Sidebar";
 import { Sidebar, SidebarProvider, SidebarRail } from "./ui/sidebar";
+import {
+  clearShortcutModifierState,
+  syncShortcutModifierStateFromKeyboardEvent,
+} from "../shortcutModifierState";
 
 const THREAD_SIDEBAR_WIDTH_STORAGE_KEY = "chat_thread_sidebar_width";
 const THREAD_SIDEBAR_MIN_WIDTH = 13 * 16;
 const THREAD_MAIN_CONTENT_MIN_WIDTH = 40 * 16;
-
 export function AppSidebarLayout({ children }: { children: ReactNode }) {
   const navigate = useNavigate();
 
+  useEffect(() => {
+    const onWindowKeyDown = (event: KeyboardEvent) => {
+      syncShortcutModifierStateFromKeyboardEvent(event);
+    };
+    const onWindowKeyUp = (event: KeyboardEvent) => {
+      syncShortcutModifierStateFromKeyboardEvent(event);
+    };
+    const onWindowBlur = () => {
+      clearShortcutModifierState();
+    };
+
+    window.addEventListener("keydown", onWindowKeyDown, true);
+    window.addEventListener("keyup", onWindowKeyUp, true);
+    window.addEventListener("blur", onWindowBlur);
+
+    return () => {
+      window.removeEventListener("keydown", onWindowKeyDown, true);
+      window.removeEventListener("keyup", onWindowKeyUp, true);
+      window.removeEventListener("blur", onWindowBlur);
+    };
+  }, []);
+
   useEffect(() => {
     const onMenuAction = window.desktopBridge?.onMenuAction;
     if (typeof onMenuAction !== "function") {
@@ -18,8 +43,9 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
     }
 
     const unsubscribe = onMenuAction((action) => {
-      if (action !== "open-settings") return;
-      void navigate({ to: "/settings" });
+      if (action === "open-settings") {
+        void navigate({ to: "/settings" });
+      }
     });
 
     return () => {
@@ -28,7 +54,7 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
   }, [navigate]);
 
   return (
-    <SidebarProvider defaultOpen>
+    <SidebarProvider className="h-dvh! min-h-0!" defaultOpen>
       <Sidebar
         side="left"
         collapsible="offcanvas"
diff --git a/apps/web/src/components/BranchToolbar.logic.test.ts b/apps/web/src/components/BranchToolbar.logic.test.ts
index faf21d636cf..3db5237373a 100644
--- a/apps/web/src/components/BranchToolbar.logic.test.ts
+++ b/apps/web/src/components/BranchToolbar.logic.test.ts
@@ -1,4 +1,4 @@
-import { EnvironmentId, type GitBranch } from "@t3tools/contracts";
+import { EnvironmentId, type VcsRef } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 import {
   dedupeRemoteBranchesWithLocalMatches,
@@ -10,6 +10,7 @@ import {
   resolveEffectiveEnvMode,
   resolveEnvModeLabel,
   resolveBranchToolbarValue,
+  resolveLockedWorkspaceLabel,
   shouldIncludeBranchPickerItem,
 } from "./BranchToolbar.logic";
 
@@ -27,7 +28,7 @@ describe("resolveDraftEnvModeAfterBranchChange", () => {
     ).toBe("local");
   });
 
-  it("keeps new-worktree mode when selecting a base branch before worktree creation", () => {
+  it("keeps new-worktree mode when selecting a base ref before worktree creation", () => {
     expect(
       resolveDraftEnvModeAfterBranchChange({
         nextWorktreePath: null,
@@ -37,7 +38,7 @@ describe("resolveDraftEnvModeAfterBranchChange", () => {
     ).toBe("worktree");
   });
 
-  it("uses worktree mode when selecting a branch already attached to a worktree", () => {
+  it("uses worktree mode when selecting a ref already attached to a worktree", () => {
     expect(
       resolveDraftEnvModeAfterBranchChange({
         nextWorktreePath: "/repo/.t3/worktrees/feature-a",
@@ -49,7 +50,7 @@ describe("resolveDraftEnvModeAfterBranchChange", () => {
 });
 
 describe("resolveBranchToolbarValue", () => {
-  it("defaults new-worktree mode to current git branch when no explicit base branch is set", () => {
+  it("defaults new-worktree mode to current git ref when no explicit base ref is set", () => {
     expect(
       resolveBranchToolbarValue({
         envMode: "worktree",
@@ -60,7 +61,7 @@ describe("resolveBranchToolbarValue", () => {
     ).toBe("main");
   });
 
-  it("keeps an explicitly selected worktree base branch", () => {
+  it("keeps an explicitly selected worktree base ref", () => {
     expect(
       resolveBranchToolbarValue({
         envMode: "worktree",
@@ -71,7 +72,7 @@ describe("resolveBranchToolbarValue", () => {
     ).toBe("feature/base");
   });
 
-  it("shows the actual checked-out branch when not selecting a new worktree base", () => {
+  it("shows the actual checked-out ref when not selecting a new worktree base", () => {
     expect(
       resolveBranchToolbarValue({
         envMode: "local",
@@ -157,6 +158,16 @@ describe("resolveCurrentWorkspaceLabel", () => {
   });
 });
 
+describe("resolveLockedWorkspaceLabel", () => {
+  it("uses a shorter label for the main repo checkout", () => {
+    expect(resolveLockedWorkspaceLabel(null)).toBe("Local checkout");
+  });
+
+  it("uses a shorter label for an attached worktree", () => {
+    expect(resolveLockedWorkspaceLabel("/repo/.t3/worktrees/feature-a")).toBe("Worktree");
+  });
+});
+
 describe("deriveLocalBranchNameFromRemoteRef", () => {
   it("strips the remote prefix from a remote ref", () => {
     expect(deriveLocalBranchNameFromRemoteRef("origin/feature/demo")).toBe("feature/demo");
@@ -175,8 +186,8 @@ describe("deriveLocalBranchNameFromRemoteRef", () => {
 });
 
 describe("dedupeRemoteBranchesWithLocalMatches", () => {
-  it("hides remote refs when the matching local branch exists", () => {
-    const input: GitBranch[] = [
+  it("hides remote refs when the matching local ref exists", () => {
+    const input: VcsRef[] = [
       {
         name: "feature/demo",
         current: false,
@@ -201,14 +212,14 @@ describe("dedupeRemoteBranchesWithLocalMatches", () => {
       },
     ];
 
-    expect(dedupeRemoteBranchesWithLocalMatches(input).map((branch) => branch.name)).toEqual([
+    expect(dedupeRemoteBranchesWithLocalMatches(input).map((ref) => ref.name)).toEqual([
       "feature/demo",
       "origin/feature/remote-only",
     ]);
   });
 
   it("keeps all entries when no local match exists for a remote ref", () => {
-    const input: GitBranch[] = [
+    const input: VcsRef[] = [
       {
         name: "feature/local",
         current: false,
@@ -225,14 +236,14 @@ describe("dedupeRemoteBranchesWithLocalMatches", () => {
       },
     ];
 
-    expect(dedupeRemoteBranchesWithLocalMatches(input).map((branch) => branch.name)).toEqual([
+    expect(dedupeRemoteBranchesWithLocalMatches(input).map((ref) => ref.name)).toEqual([
       "feature/local",
       "origin/feature/remote-only",
     ]);
   });
 
-  it("keeps non-origin remote refs visible even when a matching local branch exists", () => {
-    const input: GitBranch[] = [
+  it("keeps non-origin remote refs visible even when a matching local ref exists", () => {
+    const input: VcsRef[] = [
       {
         name: "feature/demo",
         current: false,
@@ -249,14 +260,14 @@ describe("dedupeRemoteBranchesWithLocalMatches", () => {
       },
     ];
 
-    expect(dedupeRemoteBranchesWithLocalMatches(input).map((branch) => branch.name)).toEqual([
+    expect(dedupeRemoteBranchesWithLocalMatches(input).map((ref) => ref.name)).toEqual([
       "feature/demo",
       "my-org/upstream/feature/demo",
     ]);
   });
 
   it("keeps non-origin remote refs visible when git tracks with first-slash local naming", () => {
-    const input: GitBranch[] = [
+    const input: VcsRef[] = [
       {
         name: "upstream/feature",
         current: false,
@@ -273,7 +284,7 @@ describe("dedupeRemoteBranchesWithLocalMatches", () => {
       },
     ];
 
-    expect(dedupeRemoteBranchesWithLocalMatches(input).map((branch) => branch.name)).toEqual([
+    expect(dedupeRemoteBranchesWithLocalMatches(input).map((ref) => ref.name)).toEqual([
       "upstream/feature",
       "my-org/upstream/feature",
     ]);
@@ -281,12 +292,12 @@ describe("dedupeRemoteBranchesWithLocalMatches", () => {
 });
 
 describe("resolveBranchSelectionTarget", () => {
-  it("reuses an existing secondary worktree for the selected branch", () => {
+  it("reuses an existing secondary worktree for the selected ref", () => {
     expect(
       resolveBranchSelectionTarget({
         activeProjectCwd: "/repo",
         activeWorktreePath: "/repo/.t3/worktrees/feature-a",
-        branch: {
+        refName: {
           isDefault: false,
           worktreePath: "/repo/.t3/worktrees/feature-b",
         },
@@ -298,12 +309,12 @@ describe("resolveBranchSelectionTarget", () => {
     });
   });
 
-  it("switches back to the main repo when the branch already lives there", () => {
+  it("switches back to the main repo when the ref already lives there", () => {
     expect(
       resolveBranchSelectionTarget({
         activeProjectCwd: "/repo",
         activeWorktreePath: "/repo/.t3/worktrees/feature-a",
-        branch: {
+        refName: {
           isDefault: true,
           worktreePath: "/repo",
         },
@@ -315,12 +326,12 @@ describe("resolveBranchSelectionTarget", () => {
     });
   });
 
-  it("checks out the default branch in the main repo when leaving a secondary worktree", () => {
+  it("checks out the default ref in the main repo when leaving a secondary worktree", () => {
     expect(
       resolveBranchSelectionTarget({
         activeProjectCwd: "/repo",
         activeWorktreePath: "/repo/.t3/worktrees/feature-a",
-        branch: {
+        refName: {
           isDefault: true,
           worktreePath: null,
         },
@@ -332,12 +343,12 @@ describe("resolveBranchSelectionTarget", () => {
     });
   });
 
-  it("keeps checkout in the current worktree for non-default branches", () => {
+  it("keeps checkout in the current worktree for non-default refs", () => {
     expect(
       resolveBranchSelectionTarget({
         activeProjectCwd: "/repo",
         activeWorktreePath: "/repo/.t3/worktrees/feature-a",
-        branch: {
+        refName: {
           isDefault: false,
           worktreePath: null,
         },
@@ -362,7 +373,7 @@ describe("shouldIncludeBranchPickerItem", () => {
     ).toBe(true);
   });
 
-  it("keeps the synthetic create-branch item visible for arbitrary branch input", () => {
+  it("keeps the synthetic create-ref item visible for arbitrary ref input", () => {
     expect(
       shouldIncludeBranchPickerItem({
         itemValue: "__create_new_branch__:feature/demo",
@@ -373,7 +384,7 @@ describe("shouldIncludeBranchPickerItem", () => {
     ).toBe(true);
   });
 
-  it("still filters ordinary branch items by query text", () => {
+  it("still filters ordinary ref items by query text", () => {
     expect(
       shouldIncludeBranchPickerItem({
         itemValue: "main",
diff --git a/apps/web/src/components/BranchToolbar.logic.ts b/apps/web/src/components/BranchToolbar.logic.ts
index 54ec4370f4e..65388962c08 100644
--- a/apps/web/src/components/BranchToolbar.logic.ts
+++ b/apps/web/src/components/BranchToolbar.logic.ts
@@ -1,5 +1,5 @@
-import type { EnvironmentId, GitBranch, ProjectId } from "@t3tools/contracts";
-import { Schema } from "effect";
+import type { EnvironmentId, VcsRef, ProjectId } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
 export {
   dedupeRemoteBranchesWithLocalMatches,
   deriveLocalBranchNameFromRemoteRef,
@@ -50,6 +50,10 @@ export function resolveCurrentWorkspaceLabel(activeWorktreePath: string | null):
   return activeWorktreePath ? "Current worktree" : resolveEnvModeLabel("local");
 }
 
+export function resolveLockedWorkspaceLabel(activeWorktreePath: string | null): string {
+  return activeWorktreePath ? "Worktree" : "Local checkout";
+}
+
 export function resolveEffectiveEnvMode(input: {
   activeWorktreePath: string | null;
   hasServerThread: boolean;
@@ -96,24 +100,24 @@ export function resolveBranchToolbarValue(input: {
 export function resolveBranchSelectionTarget(input: {
   activeProjectCwd: string;
   activeWorktreePath: string | null;
-  branch: Pick<GitBranch, "isDefault" | "worktreePath">;
+  refName: Pick<VcsRef, "isDefault" | "worktreePath">;
 }): {
   checkoutCwd: string;
   nextWorktreePath: string | null;
   reuseExistingWorktree: boolean;
 } {
-  const { activeProjectCwd, activeWorktreePath, branch } = input;
+  const { activeProjectCwd, activeWorktreePath, refName } = input;
 
-  if (branch.worktreePath) {
+  if (refName.worktreePath) {
     return {
-      checkoutCwd: branch.worktreePath,
-      nextWorktreePath: branch.worktreePath === activeProjectCwd ? null : branch.worktreePath,
+      checkoutCwd: refName.worktreePath,
+      nextWorktreePath: refName.worktreePath === activeProjectCwd ? null : refName.worktreePath,
       reuseExistingWorktree: true,
     };
   }
 
   const nextWorktreePath =
-    activeWorktreePath !== null && branch.isDefault ? null : activeWorktreePath;
+    activeWorktreePath !== null && refName.isDefault ? null : activeWorktreePath;
 
   return {
     checkoutCwd: nextWorktreePath ?? activeProjectCwd,
diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx
index e91266d65fc..27c5c311c60 100644
--- a/apps/web/src/components/BranchToolbar.tsx
+++ b/apps/web/src/components/BranchToolbar.tsx
@@ -1,18 +1,41 @@
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime";
 import type { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import {
+  ChevronDownIcon,
+  CloudIcon,
+  FolderGit2Icon,
+  FolderGitIcon,
+  FolderIcon,
+  MonitorIcon,
+} from "lucide-react";
 import { memo, useMemo } from "react";
 
 import { useComposerDraftStore, type DraftId } from "../composerDraftStore";
+import { useIsMobile } from "../hooks/useMediaQuery";
 import { useStore } from "../store";
 import { createProjectSelectorByRef, createThreadSelectorByRef } from "../storeSelectors";
 import {
   type EnvMode,
   type EnvironmentOption,
+  resolveCurrentWorkspaceLabel,
+  resolveEnvModeLabel,
   resolveEffectiveEnvMode,
+  resolveLockedWorkspaceLabel,
 } from "./BranchToolbar.logic";
 import { BranchToolbarBranchSelector } from "./BranchToolbarBranchSelector";
 import { BranchToolbarEnvironmentSelector } from "./BranchToolbarEnvironmentSelector";
 import { BranchToolbarEnvModeSelector } from "./BranchToolbarEnvModeSelector";
+import { Button } from "./ui/button";
+import {
+  Menu,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuPopup,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuTrigger,
+} from "./ui/menu";
 import { Separator } from "./ui/separator";
 
 interface BranchToolbarProps {
@@ -20,6 +43,9 @@ interface BranchToolbarProps {
   threadId: ThreadId;
   draftId?: DraftId;
   onEnvModeChange: (mode: EnvMode) => void;
+  effectiveEnvModeOverride?: EnvMode;
+  activeThreadBranchOverride?: string | null;
+  onActiveThreadBranchOverrideChange?: (branch: string | null) => void;
   envLocked: boolean;
   onCheckoutPullRequestRequest?: (reference: string) => void;
   onComposerFocusRequest?: () => void;
@@ -27,11 +53,150 @@ interface BranchToolbarProps {
   onEnvironmentChange?: (environmentId: EnvironmentId) => void;
 }
 
+interface MobileRunContextSelectorProps {
+  envLocked: boolean;
+  envModeLocked: boolean;
+  environmentId: EnvironmentId;
+  availableEnvironments: readonly EnvironmentOption[] | undefined;
+  showEnvironmentPicker: boolean;
+  onEnvironmentChange: ((environmentId: EnvironmentId) => void) | undefined;
+  effectiveEnvMode: EnvMode;
+  activeWorktreePath: string | null;
+  onEnvModeChange: (mode: EnvMode) => void;
+}
+
+const MobileRunContextSelector = memo(function MobileRunContextSelector({
+  envLocked,
+  envModeLocked,
+  environmentId,
+  availableEnvironments,
+  showEnvironmentPicker,
+  onEnvironmentChange,
+  effectiveEnvMode,
+  activeWorktreePath,
+  onEnvModeChange,
+}: MobileRunContextSelectorProps) {
+  const activeEnvironment = useMemo(
+    () => availableEnvironments?.find((env) => env.environmentId === environmentId) ?? null,
+    [availableEnvironments, environmentId],
+  );
+  const WorkspaceIcon =
+    effectiveEnvMode === "worktree"
+      ? FolderGit2Icon
+      : activeWorktreePath
+        ? FolderGitIcon
+        : FolderIcon;
+  const workspaceLabel = envModeLocked
+    ? resolveLockedWorkspaceLabel(activeWorktreePath)
+    : effectiveEnvMode === "worktree"
+      ? resolveEnvModeLabel("worktree")
+      : resolveCurrentWorkspaceLabel(activeWorktreePath);
+  const isLocked = envLocked || envModeLocked;
+  const EnvironmentIcon = activeEnvironment?.isPrimary ? MonitorIcon : CloudIcon;
+  const icon = showEnvironmentPicker ? (
+    // Button's base styles apply `-mx-0.5` to descendant SVGs, which eats 4px
+    // out of whatever gap we set. mx-0! cancels that so gap-0.5 reads as 2px.
+    <span className="inline-flex shrink-0 items-center gap-0.5">
+      <EnvironmentIcon className="size-3 shrink-0 mx-0!" />
+      <WorkspaceIcon className="size-3 shrink-0 mx-0!" />
+    </span>
+  ) : (
+    <WorkspaceIcon className="size-3 shrink-0" />
+  );
+  const triggerContent = (
+    <>
+      {icon}
+      <span className="min-w-0 truncate">
+        {showEnvironmentPicker ? (activeEnvironment?.label ?? "Run on") : workspaceLabel}
+      </span>
+    </>
+  );
+
+  if (isLocked) {
+    return (
+      <span className="inline-flex min-w-0 max-w-[48%] flex-1 items-center justify-start gap-1 rounded-md border border-transparent px-[calc(--spacing(2)-1px)] text-sm font-medium text-muted-foreground/70 md:hidden">
+        {triggerContent}
+      </span>
+    );
+  }
+
+  return (
+    <Menu>
+      <MenuTrigger
+        render={<Button variant="ghost" size="xs" />}
+        className="min-w-0 max-w-[48%] flex-1 justify-start text-muted-foreground/70 hover:text-foreground/80 md:hidden"
+      >
+        {triggerContent}
+        <ChevronDownIcon className="size-3 shrink-0 opacity-50" />
+      </MenuTrigger>
+      <MenuPopup align="start" side="top" className="w-64">
+        {showEnvironmentPicker && availableEnvironments && onEnvironmentChange ? (
+          <>
+            <MenuGroup>
+              <MenuGroupLabel>Run on</MenuGroupLabel>
+              <MenuRadioGroup
+                value={environmentId}
+                onValueChange={(value) => onEnvironmentChange(value as EnvironmentId)}
+              >
+                {availableEnvironments.map((env) => {
+                  const Icon = env.isPrimary ? MonitorIcon : CloudIcon;
+                  return (
+                    <MenuRadioItem
+                      key={env.environmentId}
+                      disabled={envLocked}
+                      value={env.environmentId}
+                    >
+                      <span className="flex min-w-0 items-center gap-1.5">
+                        <Icon className="size-3" />
+                        <span className="min-w-0 truncate">{env.label}</span>
+                      </span>
+                    </MenuRadioItem>
+                  );
+                })}
+              </MenuRadioGroup>
+            </MenuGroup>
+            <MenuSeparator />
+          </>
+        ) : null}
+        <MenuGroup>
+          <MenuGroupLabel>Workspace</MenuGroupLabel>
+          <MenuRadioGroup
+            value={effectiveEnvMode}
+            onValueChange={(value) => onEnvModeChange(value as EnvMode)}
+          >
+            <MenuRadioItem disabled={envModeLocked} value="local">
+              <span className="flex min-w-0 items-center gap-1.5">
+                {activeWorktreePath ? (
+                  <FolderGitIcon className="size-3" />
+                ) : (
+                  <FolderIcon className="size-3" />
+                )}
+                <span className="min-w-0 truncate">
+                  {resolveCurrentWorkspaceLabel(activeWorktreePath)}
+                </span>
+              </span>
+            </MenuRadioItem>
+            <MenuRadioItem disabled={envModeLocked} value="worktree">
+              <span className="flex min-w-0 items-center gap-1.5">
+                <FolderGit2Icon className="size-3" />
+                <span className="min-w-0 truncate">{resolveEnvModeLabel("worktree")}</span>
+              </span>
+            </MenuRadioItem>
+          </MenuRadioGroup>
+        </MenuGroup>
+      </MenuPopup>
+    </Menu>
+  );
+});
+
 export const BranchToolbar = memo(function BranchToolbar({
   environmentId,
   threadId,
   draftId,
   onEnvModeChange,
+  effectiveEnvModeOverride,
+  activeThreadBranchOverride,
+  onActiveThreadBranchOverrideChange,
   envLocked,
   onCheckoutPullRequestRequest,
   onComposerFocusRequest,
@@ -59,45 +224,67 @@ export const BranchToolbar = memo(function BranchToolbar({
   const activeProject = useStore(activeProjectSelector);
   const hasActiveThread = serverThread !== undefined || draftThread !== null;
   const activeWorktreePath = serverThread?.worktreePath ?? draftThread?.worktreePath ?? null;
-  const effectiveEnvMode = resolveEffectiveEnvMode({
-    activeWorktreePath,
-    hasServerThread: serverThread !== undefined,
-    draftThreadEnvMode: draftThread?.envMode,
-  });
+  const effectiveEnvMode =
+    effectiveEnvModeOverride ??
+    resolveEffectiveEnvMode({
+      activeWorktreePath,
+      hasServerThread: serverThread !== undefined,
+      draftThreadEnvMode: draftThread?.envMode,
+    });
   const envModeLocked = envLocked || (serverThread !== undefined && activeWorktreePath !== null);
 
-  const showEnvironmentPicker =
-    availableEnvironments && availableEnvironments.length > 1 && onEnvironmentChange;
+  const showEnvironmentPicker = Boolean(
+    availableEnvironments && availableEnvironments.length > 1 && onEnvironmentChange,
+  );
+  const isMobile = useIsMobile();
 
   if (!hasActiveThread || !activeProject) return null;
 
   return (
-    <div className="mx-auto flex w-full max-w-208 items-center justify-between px-2.5 pb-3 pt-1 sm:px-3">
-      <div className="flex items-center gap-1">
-        {showEnvironmentPicker && (
-          <>
-            <BranchToolbarEnvironmentSelector
-              envLocked={envLocked}
-              environmentId={environmentId}
-              availableEnvironments={availableEnvironments}
-              onEnvironmentChange={onEnvironmentChange}
-            />
-            <Separator orientation="vertical" className="mx-0.5 h-3.5!" />
-          </>
-        )}
-        <BranchToolbarEnvModeSelector
-          envLocked={envModeLocked}
+    <div className="mx-auto flex w-full max-w-208 items-center gap-2 px-2.5 pb-3 pt-1 sm:px-3">
+      {isMobile ? (
+        <MobileRunContextSelector
+          envLocked={envLocked}
+          envModeLocked={envModeLocked}
+          environmentId={environmentId}
+          availableEnvironments={availableEnvironments}
+          showEnvironmentPicker={showEnvironmentPicker}
+          onEnvironmentChange={onEnvironmentChange}
           effectiveEnvMode={effectiveEnvMode}
           activeWorktreePath={activeWorktreePath}
           onEnvModeChange={onEnvModeChange}
         />
-      </div>
+      ) : (
+        <div className="flex min-w-0 shrink-0 items-center gap-1">
+          {showEnvironmentPicker && availableEnvironments && onEnvironmentChange && (
+            <>
+              <BranchToolbarEnvironmentSelector
+                envLocked={envLocked}
+                environmentId={environmentId}
+                availableEnvironments={availableEnvironments}
+                onEnvironmentChange={onEnvironmentChange}
+              />
+              <Separator orientation="vertical" className="mx-0.5 h-3.5!" />
+            </>
+          )}
+          <BranchToolbarEnvModeSelector
+            envLocked={envModeLocked}
+            effectiveEnvMode={effectiveEnvMode}
+            activeWorktreePath={activeWorktreePath}
+            onEnvModeChange={onEnvModeChange}
+          />
+        </div>
+      )}
 
       <BranchToolbarBranchSelector
+        className="min-w-0 flex-1 justify-end md:ml-auto md:flex-none"
         environmentId={environmentId}
         threadId={threadId}
         {...(draftId ? { draftId } : {})}
         envLocked={envLocked}
+        {...(effectiveEnvModeOverride ? { effectiveEnvModeOverride } : {})}
+        {...(activeThreadBranchOverride !== undefined ? { activeThreadBranchOverride } : {})}
+        {...(onActiveThreadBranchOverrideChange ? { onActiveThreadBranchOverrideChange } : {})}
         {...(onCheckoutPullRequestRequest ? { onCheckoutPullRequestRequest } : {})}
         {...(onComposerFocusRequest ? { onComposerFocusRequest } : {})}
       />
diff --git a/apps/web/src/components/BranchToolbarBranchSelector.tsx b/apps/web/src/components/BranchToolbarBranchSelector.tsx
index 76f64d93fe1..2e30edfc02c 100644
--- a/apps/web/src/components/BranchToolbarBranchSelector.tsx
+++ b/apps/web/src/components/BranchToolbarBranchSelector.tsx
@@ -1,10 +1,9 @@
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime";
-import type { EnvironmentId, GitBranch, ThreadId } from "@t3tools/contracts";
+import type { EnvironmentId, VcsRef, ThreadId } from "@t3tools/contracts";
 import { useInfiniteQuery, useQueryClient } from "@tanstack/react-query";
-import { useVirtualizer } from "@tanstack/react-virtual";
+import { LegendList, type LegendListRef } from "@legendapp/list/react";
 import { ChevronDownIcon } from "lucide-react";
 import {
-  type CSSProperties,
   useCallback,
   useDeferredValue,
   useEffect,
@@ -20,7 +19,9 @@ import { readEnvironmentApi } from "../environmentApi";
 import { gitBranchSearchInfiniteQueryOptions, gitQueryKeys } from "../lib/gitReactQuery";
 import { useGitStatus } from "../lib/gitStatusState";
 import { newCommandId } from "../lib/utils";
+import { cn } from "../lib/utils";
 import { parsePullRequestReference } from "../pullRequestReference";
+import { getSourceControlPresentation } from "../sourceControlPresentation";
 import { useStore } from "../store";
 import { createProjectSelectorByRef, createThreadSelectorByRef } from "../storeSelectors";
 import {
@@ -38,17 +39,22 @@ import {
   ComboboxInput,
   ComboboxItem,
   ComboboxList,
+  ComboboxListVirtualized,
   ComboboxPopup,
   ComboboxStatus,
   ComboboxTrigger,
 } from "./ui/combobox";
-import { toastManager } from "./ui/toast";
+import { stackedThreadToast, toastManager } from "./ui/toast";
 
 interface BranchToolbarBranchSelectorProps {
+  className?: string;
   environmentId: EnvironmentId;
   threadId: ThreadId;
   draftId?: DraftId;
   envLocked: boolean;
+  effectiveEnvModeOverride?: "local" | "worktree";
+  activeThreadBranchOverride?: string | null;
+  onActiveThreadBranchOverrideChange?: (refName: string | null) => void;
   onCheckoutPullRequestRequest?: (reference: string) => void;
   onComposerFocusRequest?: () => void;
 }
@@ -64,7 +70,7 @@ function getBranchTriggerLabel(input: {
 }): string {
   const { activeWorktreePath, effectiveEnvMode, resolvedActiveBranch } = input;
   if (!resolvedActiveBranch) {
-    return "Select branch";
+    return "Select ref";
   }
   if (effectiveEnvMode === "worktree" && !activeWorktreePath) {
     return `From ${resolvedActiveBranch}`;
@@ -73,10 +79,14 @@ function getBranchTriggerLabel(input: {
 }
 
 export function BranchToolbarBranchSelector({
+  className,
   environmentId,
   threadId,
   draftId,
   envLocked,
+  effectiveEnvModeOverride,
+  activeThreadBranchOverride,
+  onActiveThreadBranchOverrideChange,
   onCheckoutPullRequestRequest,
   onComposerFocusRequest,
 }: BranchToolbarBranchSelectorProps) {
@@ -108,16 +118,21 @@ export function BranchToolbarBranchSelector({
   const activeProject = useStore(activeProjectSelector);
 
   const activeThreadId = serverThread?.id ?? (draftThread ? threadId : undefined);
-  const activeThreadBranch = serverThread?.branch ?? draftThread?.branch ?? null;
+  const activeThreadBranch =
+    activeThreadBranchOverride !== undefined
+      ? activeThreadBranchOverride
+      : (serverThread?.branch ?? draftThread?.branch ?? null);
   const activeWorktreePath = serverThread?.worktreePath ?? draftThread?.worktreePath ?? null;
   const activeProjectCwd = activeProject?.cwd ?? null;
   const branchCwd = activeWorktreePath ?? activeProjectCwd;
   const hasServerThread = serverThread !== undefined;
-  const effectiveEnvMode = resolveEffectiveEnvMode({
-    activeWorktreePath,
-    hasServerThread,
-    draftThreadEnvMode: draftThread?.envMode,
-  });
+  const effectiveEnvMode =
+    effectiveEnvModeOverride ??
+    resolveEffectiveEnvMode({
+      activeWorktreePath,
+      hasServerThread,
+      draftThreadEnvMode: draftThread?.envMode,
+    });
 
   // ---------------------------------------------------------------------------
   // Thread branch mutation (colocated — only this component calls it)
@@ -146,6 +161,7 @@ export function BranchToolbarBranchSelector({
         });
       }
       if (hasServerThread) {
+        onActiveThreadBranchOverrideChange?.(branch);
         setThreadBranchAction(threadRef, branch, worktreePath);
         return;
       }
@@ -167,6 +183,7 @@ export function BranchToolbarBranchSelector({
       serverSession,
       activeWorktreePath,
       hasServerThread,
+      onActiveThreadBranchOverrideChange,
       setThreadBranchAction,
       setDraftThreadContext,
       draftId,
@@ -177,7 +194,7 @@ export function BranchToolbarBranchSelector({
   );
 
   // ---------------------------------------------------------------------------
-  // Git branch queries
+  // Git ref queries
   // ---------------------------------------------------------------------------
   const queryClient = useQueryClient();
   const [isBranchMenuOpen, setIsBranchMenuOpen] = useState(false);
@@ -208,22 +225,27 @@ export function BranchToolbarBranchSelector({
       query: deferredTrimmedBranchQuery,
     }),
   );
-  const branches = useMemo(
-    () => branchesSearchData?.pages.flatMap((page) => page.branches) ?? [],
+  const refs = useMemo(
+    () => branchesSearchData?.pages.flatMap((page) => page.refs) ?? [],
     [branchesSearchData?.pages],
   );
   const currentGitBranch =
-    branchStatusQuery.data?.branch ?? branches.find((branch) => branch.current)?.name ?? null;
+    branchStatusQuery.data?.refName ?? refs.find((refName) => refName.current)?.name ?? null;
+  const sourceControlPresentation = useMemo(
+    () => getSourceControlPresentation(branchStatusQuery.data?.sourceControlProvider),
+    [branchStatusQuery.data?.sourceControlProvider],
+  );
+  const SourceControlIcon = sourceControlPresentation.Icon;
   const canonicalActiveBranch = resolveBranchToolbarValue({
     envMode: effectiveEnvMode,
     activeWorktreePath,
     activeThreadBranch,
     currentGitBranch,
   });
-  const branchNames = useMemo(() => branches.map((branch) => branch.name), [branches]);
+  const branchNames = useMemo(() => refs.map((refName) => refName.name), [refs]);
   const branchByName = useMemo(
-    () => new Map(branches.map((branch) => [branch.name, branch] as const)),
-    [branches],
+    () => new Map(refs.map((refName) => [refName.name, refName] as const)),
+    [refs],
   );
   const normalizedDeferredBranchQuery = deferredTrimmedBranchQuery.toLowerCase();
   const prReference = parsePullRequestReference(trimmedBranchQuery);
@@ -273,11 +295,11 @@ export function BranchToolbarBranchSelector({
   const shouldVirtualizeBranchList = filteredBranchPickerItems.length > 40;
   const totalBranchCount = branchesSearchData?.pages[0]?.totalCount ?? 0;
   const branchStatusText = isBranchesSearchPending
-    ? "Loading branches..."
+    ? "Loading refs..."
     : isFetchingNextPage
-      ? "Loading more branches..."
+      ? "Loading more refs..."
       : hasNextPage
-        ? `Showing ${branches.length} of ${totalBranchCount} branches`
+        ? `Showing ${refs.length} of ${totalBranchCount} refs`
         : null;
 
   // ---------------------------------------------------------------------------
@@ -287,17 +309,17 @@ export function BranchToolbarBranchSelector({
     startBranchActionTransition(async () => {
       await action().catch(() => undefined);
       await queryClient
-        .invalidateQueries({ queryKey: gitQueryKeys.branches(environmentId, branchCwd) })
+        .invalidateQueries({ queryKey: gitQueryKeys.refs(environmentId, branchCwd) })
         .catch(() => undefined);
     });
   };
 
-  const selectBranch = (branch: GitBranch) => {
+  const selectBranch = (refName: VcsRef) => {
     const api = readEnvironmentApi(environmentId);
     if (!api || !branchCwd || !activeProjectCwd || isBranchActionPending) return;
 
     if (isSelectingWorktreeBase) {
-      setThreadBranch(branch.name, null);
+      setThreadBranch(refName.name, null);
       setIsBranchMenuOpen(false);
       onComposerFocusRequest?.();
       return;
@@ -306,19 +328,19 @@ export function BranchToolbarBranchSelector({
     const selectionTarget = resolveBranchSelectionTarget({
       activeProjectCwd,
       activeWorktreePath,
-      branch,
+      refName,
     });
 
     if (selectionTarget.reuseExistingWorktree) {
-      setThreadBranch(branch.name, selectionTarget.nextWorktreePath);
+      setThreadBranch(refName.name, selectionTarget.nextWorktreePath);
       setIsBranchMenuOpen(false);
       onComposerFocusRequest?.();
       return;
     }
 
-    const selectedBranchName = branch.isRemote
-      ? deriveLocalBranchNameFromRemoteRef(branch.name)
-      : branch.name;
+    const selectedBranchName = refName.isRemote
+      ? deriveLocalBranchNameFromRemoteRef(refName.name)
+      : refName.name;
 
     setIsBranchMenuOpen(false);
     onComposerFocusRequest?.();
@@ -327,27 +349,29 @@ export function BranchToolbarBranchSelector({
       const previousBranch = resolvedActiveBranch;
       setOptimisticBranch(selectedBranchName);
       try {
-        const checkoutResult = await api.git.checkout({
+        const checkoutResult = await api.vcs.switchRef({
           cwd: selectionTarget.checkoutCwd,
-          branch: branch.name,
+          refName: refName.name,
         });
-        const nextBranchName = branch.isRemote
-          ? (checkoutResult.branch ?? selectedBranchName)
+        const nextBranchName = refName.isRemote
+          ? (checkoutResult.refName ?? selectedBranchName)
           : selectedBranchName;
         setOptimisticBranch(nextBranchName);
         setThreadBranch(nextBranchName, selectionTarget.nextWorktreePath);
       } catch (error) {
         setOptimisticBranch(previousBranch);
-        toastManager.add({
-          type: "error",
-          title: "Failed to checkout branch.",
-          description: toBranchActionErrorMessage(error),
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to switch ref.",
+            description: toBranchActionErrorMessage(error),
+          }),
+        );
       }
     });
   };
 
-  const createBranch = (rawName: string) => {
+  const createRef = (rawName: string) => {
     const name = rawName.trim();
     const api = readEnvironmentApi(environmentId);
     if (!api || !branchCwd || !name || isBranchActionPending) return;
@@ -359,20 +383,22 @@ export function BranchToolbarBranchSelector({
       const previousBranch = resolvedActiveBranch;
       setOptimisticBranch(name);
       try {
-        const createBranchResult = await api.git.createBranch({
+        const createBranchResult = await api.vcs.createRef({
           cwd: branchCwd,
-          branch: name,
-          checkout: true,
+          refName: name,
+          switchRef: true,
         });
-        setOptimisticBranch(createBranchResult.branch);
-        setThreadBranch(createBranchResult.branch, activeWorktreePath);
+        setOptimisticBranch(createBranchResult.refName);
+        setThreadBranch(createBranchResult.refName, activeWorktreePath);
       } catch (error) {
         setOptimisticBranch(previousBranch);
-        toastManager.add({
-          type: "error",
-          title: "Failed to create and checkout branch.",
-          description: toBranchActionErrorMessage(error),
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to create and switch ref.",
+            description: toBranchActionErrorMessage(error),
+          }),
+        );
       }
     });
   };
@@ -390,7 +416,7 @@ export function BranchToolbarBranchSelector({
   }, [activeThreadBranch, activeWorktreePath, currentGitBranch, effectiveEnvMode, setThreadBranch]);
 
   // ---------------------------------------------------------------------------
-  // Combobox / virtualizer plumbing
+  // Combobox / list plumbing
   // ---------------------------------------------------------------------------
   const handleOpenChange = useCallback(
     (open: boolean) => {
@@ -400,7 +426,7 @@ export function BranchToolbarBranchSelector({
         return;
       }
       void queryClient.invalidateQueries({
-        queryKey: gitQueryKeys.branches(environmentId, branchCwd),
+        queryKey: gitQueryKeys.refs(environmentId, branchCwd),
       });
     },
     [branchCwd, environmentId, queryClient],
@@ -425,49 +451,22 @@ export function BranchToolbarBranchSelector({
 
     void fetchNextPage().catch(() => undefined);
   }, [fetchNextPage, hasNextPage, isBranchMenuOpen, isFetchingNextPage]);
-  const branchListVirtualizer = useVirtualizer({
-    count: filteredBranchPickerItems.length,
-    estimateSize: (index) =>
-      filteredBranchPickerItems[index] === checkoutPullRequestItemValue ? 44 : 28,
-    getScrollElement: () => branchListScrollElementRef.current,
-    overscan: 12,
-    enabled: isBranchMenuOpen && shouldVirtualizeBranchList,
-    initialRect: {
-      height: 224,
-      width: 0,
-    },
-  });
-  const virtualBranchRows = branchListVirtualizer.getVirtualItems();
-  const setBranchListRef = useCallback(
-    (element: HTMLDivElement | null) => {
-      branchListScrollElementRef.current =
-        (element?.parentElement as HTMLDivElement | null) ?? null;
-      if (element) {
-        branchListVirtualizer.measure();
-      }
-    },
-    [branchListVirtualizer],
-  );
-
-  useEffect(() => {
-    if (!isBranchMenuOpen || !shouldVirtualizeBranchList) return;
-    queueMicrotask(() => {
-      branchListVirtualizer.measure();
-    });
-  }, [
-    branchListVirtualizer,
-    filteredBranchPickerItems.length,
-    isBranchMenuOpen,
-    shouldVirtualizeBranchList,
-  ]);
+  const branchListRef = useRef<LegendListRef | null>(null);
+  const setBranchListRef = useCallback((element: HTMLDivElement | null) => {
+    branchListScrollElementRef.current = (element?.parentElement as HTMLDivElement | null) ?? null;
+  }, []);
 
   useEffect(() => {
     if (!isBranchMenuOpen) {
       return;
     }
 
-    branchListScrollElementRef.current?.scrollTo({ top: 0 });
-  }, [deferredTrimmedBranchQuery, isBranchMenuOpen]);
+    if (shouldVirtualizeBranchList) {
+      branchListRef.current?.scrollToOffset?.({ offset: 0, animated: false });
+    } else {
+      branchListScrollElementRef.current?.scrollTo({ top: 0 });
+    }
+  }, [deferredTrimmedBranchQuery, isBranchMenuOpen, shouldVirtualizeBranchList]);
 
   useEffect(() => {
     const scrollElement = branchListScrollElementRef.current;
@@ -487,8 +486,9 @@ export function BranchToolbarBranchSelector({
   }, [isBranchMenuOpen, maybeFetchNextBranchPage]);
 
   useEffect(() => {
+    if (shouldVirtualizeBranchList) return;
     maybeFetchNextBranchPage();
-  }, [branches.length, maybeFetchNextBranchPage]);
+  }, [refs.length, maybeFetchNextBranchPage, shouldVirtualizeBranchList]);
 
   const triggerLabel = getBranchTriggerLabel({
     activeWorktreePath,
@@ -496,7 +496,7 @@ export function BranchToolbarBranchSelector({
     resolvedActiveBranch,
   });
 
-  function renderPickerItem(itemValue: string, index: number, style?: CSSProperties) {
+  function renderPickerItem(itemValue: string, index: number) {
     if (checkoutPullRequestItemValue && itemValue === checkoutPullRequestItemValue) {
       return (
         <ComboboxItem
@@ -504,7 +504,6 @@ export function BranchToolbarBranchSelector({
           key={itemValue}
           index={index}
           value={itemValue}
-          style={style}
           onClick={() => {
             if (!prReference || !onCheckoutPullRequestRequest) {
               return;
@@ -515,9 +514,14 @@ export function BranchToolbarBranchSelector({
             onCheckoutPullRequestRequest(prReference);
           }}
         >
-          <div className="flex min-w-0 flex-col items-start py-1">
-            <span className="truncate font-medium">Checkout Pull Request</span>
-            <span className="truncate text-muted-foreground text-xs">{prReference}</span>
+          <div className="flex min-w-0 items-center gap-2 py-1">
+            <SourceControlIcon className="size-3.5 shrink-0 text-muted-foreground" />
+            <span className="flex min-w-0 flex-col items-start">
+              <span className="truncate font-medium">
+                Checkout {sourceControlPresentation.terminology.singular}
+              </span>
+              <span className="truncate text-muted-foreground text-xs">{prReference}</span>
+            </span>
           </div>
         </ComboboxItem>
       );
@@ -529,26 +533,25 @@ export function BranchToolbarBranchSelector({
           key={itemValue}
           index={index}
           value={itemValue}
-          style={style}
-          onClick={() => createBranch(trimmedBranchQuery)}
+          onClick={() => createRef(trimmedBranchQuery)}
         >
-          <span className="truncate">Create new branch &quot;{trimmedBranchQuery}&quot;</span>
+          <span className="truncate">Create new ref &quot;{trimmedBranchQuery}&quot;</span>
         </ComboboxItem>
       );
     }
 
-    const branch = branchByName.get(itemValue);
-    if (!branch) return null;
+    const refName = branchByName.get(itemValue);
+    if (!refName) return null;
 
     const hasSecondaryWorktree =
-      branch.worktreePath && activeProjectCwd && branch.worktreePath !== activeProjectCwd;
-    const badge = branch.current
+      refName.worktreePath && activeProjectCwd && refName.worktreePath !== activeProjectCwd;
+    const badge = refName.current
       ? "current"
       : hasSecondaryWorktree
         ? "worktree"
-        : branch.isRemote
+        : refName.isRemote
           ? "remote"
-          : branch.isDefault
+          : refName.isDefault
             ? "default"
             : null;
     return (
@@ -557,8 +560,7 @@ export function BranchToolbarBranchSelector({
         key={itemValue}
         index={index}
         value={itemValue}
-        style={style}
-        onClick={() => selectBranch(branch)}
+        onClick={() => selectBranch(refName)}
       >
         <div className="flex w-full items-center justify-between gap-2">
           <span className="truncate">{itemValue}</span>
@@ -575,8 +577,13 @@ export function BranchToolbarBranchSelector({
       autoHighlight
       virtualized={shouldVirtualizeBranchList}
       onItemHighlighted={(_value, eventDetails) => {
-        if (!isBranchMenuOpen || eventDetails.index < 0) return;
-        branchListVirtualizer.scrollToIndex(eventDetails.index, { align: "auto" });
+        if (!isBranchMenuOpen || eventDetails.index < 0 || eventDetails.reason !== "keyboard") {
+          return;
+        }
+        branchListRef.current?.scrollIndexIntoView?.({
+          index: eventDetails.index,
+          animated: false,
+        });
       }}
       onOpenChange={handleOpenChange}
       open={isBranchMenuOpen}
@@ -584,50 +591,50 @@ export function BranchToolbarBranchSelector({
     >
       <ComboboxTrigger
         render={<Button variant="ghost" size="xs" />}
-        className="text-muted-foreground/70 hover:text-foreground/80"
-        disabled={(isBranchesSearchPending && branches.length === 0) || isBranchActionPending}
+        className={cn("min-w-0 text-muted-foreground/70 hover:text-foreground/80", className)}
+        disabled={(isBranchesSearchPending && refs.length === 0) || isBranchActionPending}
       >
-        <span className="max-w-[240px] truncate">{triggerLabel}</span>
-        <ChevronDownIcon />
+        <span className="min-w-0 max-w-[240px] truncate">{triggerLabel}</span>
+        <ChevronDownIcon className="shrink-0" />
       </ComboboxTrigger>
       <ComboboxPopup align="end" side="top" className="w-80">
         <div className="border-b p-1">
           <ComboboxInput
             className="[&_input]:font-sans rounded-md"
             inputClassName="ring-0"
-            placeholder="Search branches..."
+            placeholder="Search refs..."
             showTrigger={false}
             size="sm"
             value={branchQuery}
             onChange={(event) => setBranchQuery(event.target.value)}
           />
         </div>
-        <ComboboxEmpty>No branches found.</ComboboxEmpty>
-
-        <ComboboxList ref={setBranchListRef} className="max-h-56">
-          {shouldVirtualizeBranchList ? (
-            <div
-              className="relative"
-              style={{
-                height: `${branchListVirtualizer.getTotalSize()}px`,
+        <ComboboxEmpty>No refs found.</ComboboxEmpty>
+
+        {shouldVirtualizeBranchList ? (
+          <ComboboxListVirtualized>
+            <LegendList<string>
+              ref={branchListRef}
+              data={filteredBranchPickerItems}
+              keyExtractor={(item) => item}
+              renderItem={({ item, index }) => renderPickerItem(item, index)}
+              estimatedItemSize={28}
+              drawDistance={336}
+              onEndReached={() => {
+                if (hasNextPage && !isFetchingNextPage) {
+                  void fetchNextPage().catch(() => undefined);
+                }
               }}
-            >
-              {virtualBranchRows.map((virtualRow) => {
-                const itemValue = filteredBranchPickerItems[virtualRow.index];
-                if (!itemValue) return null;
-                return renderPickerItem(itemValue, virtualRow.index, {
-                  position: "absolute",
-                  top: 0,
-                  left: 0,
-                  width: "100%",
-                  transform: `translateY(${virtualRow.start}px)`,
-                });
-              })}
-            </div>
-          ) : (
-            filteredBranchPickerItems.map((itemValue, index) => renderPickerItem(itemValue, index))
-          )}
-        </ComboboxList>
+              style={{ maxHeight: "14rem" }}
+            />
+          </ComboboxListVirtualized>
+        ) : (
+          <ComboboxList ref={setBranchListRef} className="max-h-56">
+            {filteredBranchPickerItems.map((itemValue, index) =>
+              renderPickerItem(itemValue, index),
+            )}
+          </ComboboxList>
+        )}
         {branchStatusText ? <ComboboxStatus>{branchStatusText}</ComboboxStatus> : null}
       </ComboboxPopup>
     </Combobox>
diff --git a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
index 39bf50359dc..6d06882662f 100644
--- a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
+++ b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
@@ -4,6 +4,7 @@ import { memo, useMemo } from "react";
 import {
   resolveCurrentWorkspaceLabel,
   resolveEnvModeLabel,
+  resolveLockedWorkspaceLabel,
   type EnvMode,
 } from "./BranchToolbar.logic";
 import {
@@ -43,12 +44,12 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe
         {activeWorktreePath ? (
           <>
             <FolderGitIcon className="size-3" />
-            {resolveCurrentWorkspaceLabel(activeWorktreePath)}
+            {resolveLockedWorkspaceLabel(activeWorktreePath)}
           </>
         ) : (
           <>
             <FolderIcon className="size-3" />
-            {resolveCurrentWorkspaceLabel(activeWorktreePath)}
+            {resolveLockedWorkspaceLabel(activeWorktreePath)}
           </>
         )}
       </span>
@@ -57,6 +58,7 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe
 
   return (
     <Select
+      modal={false}
       value={effectiveEnvMode}
       onValueChange={(value) => onEnvModeChange(value as EnvMode)}
       items={envModeItems}
diff --git a/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx b/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
index abfa21365e1..35fc8b6a190 100644
--- a/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
+++ b/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
@@ -54,6 +54,7 @@ export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvir
 
   return (
     <Select
+      modal={false}
       value={environmentId}
       onValueChange={(value) => onEnvironmentChange(value as EnvironmentId)}
       items={environmentItems}
diff --git a/apps/web/src/components/ChatMarkdown.browser.tsx b/apps/web/src/components/ChatMarkdown.browser.tsx
index 48f345bd2f9..4e8698d4b1e 100644
--- a/apps/web/src/components/ChatMarkdown.browser.tsx
+++ b/apps/web/src/components/ChatMarkdown.browser.tsx
@@ -63,9 +63,9 @@ describe("ChatMarkdown", () => {
     );
 
     try {
-      const link = page.getByRole("link", { name: "PermissionRule.ts:1" });
+      const link = page.getByRole("link", { name: "PermissionRule.ts · L1" });
       await expect.element(link).toBeInTheDocument();
-      await expect.element(link).toHaveAttribute("href", `${filePath}#L1`);
+      await expect.element(link).toHaveAttribute("href", `${filePath}:1`);
 
       await link.click();
 
@@ -76,4 +76,66 @@ describe("ChatMarkdown", () => {
       await screen.unmount();
     }
   });
+
+  it("shows column information inline when present", async () => {
+    const filePath =
+      "/Users/yashsingh/p/sco/claude-code-extract/src/utils/permissions/PermissionRule.ts";
+    const screen = await render(
+      <ChatMarkdown text={`[PermissionRule.ts](file://${filePath}#L1C7)`} cwd="/repo/project" />,
+    );
+
+    try {
+      const link = page.getByRole("link", { name: "PermissionRule.ts · L1:C7" });
+      await expect.element(link).toBeInTheDocument();
+      await expect.element(link).toHaveAttribute("href", `${filePath}:1:7`);
+
+      await link.click();
+
+      await vi.waitFor(() => {
+        expect(openInPreferredEditorMock).toHaveBeenCalledWith(
+          expect.anything(),
+          `${filePath}:1:7`,
+        );
+      });
+    } finally {
+      await screen.unmount();
+    }
+  });
+
+  it("disambiguates duplicate file basenames inline", async () => {
+    const firstPath = "/Users/yashsingh/p/t3code/apps/web/src/components/chat/MessagesTimeline.tsx";
+    const secondPath = "/Users/yashsingh/p/t3code/apps/web/src/components/MessagesTimeline.tsx";
+    const screen = await render(
+      <ChatMarkdown
+        text={`See [MessagesTimeline.tsx](file://${firstPath}) and [MessagesTimeline.tsx](file://${secondPath}).`}
+        cwd="/repo/project"
+      />,
+    );
+
+    try {
+      await expect
+        .element(page.getByRole("link", { name: "MessagesTimeline.tsx · components/chat" }))
+        .toBeInTheDocument();
+      await expect
+        .element(page.getByRole("link", { name: "MessagesTimeline.tsx · src/components" }))
+        .toBeInTheDocument();
+    } finally {
+      await screen.unmount();
+    }
+  });
+
+  it("keeps normal web links unchanged", async () => {
+    const screen = await render(
+      <ChatMarkdown text="[OpenAI](https://openai.com/docs)" cwd="/repo/project" />,
+    );
+
+    try {
+      const link = page.getByRole("link", { name: "OpenAI" });
+      await expect.element(link).toBeInTheDocument();
+      await expect.element(link).toHaveAttribute("href", "https://openai.com/docs");
+      await expect.element(link).toHaveAttribute("target", "_blank");
+    } finally {
+      await screen.unmount();
+    }
+  });
 });
diff --git a/apps/web/src/components/ChatMarkdown.tsx b/apps/web/src/components/ChatMarkdown.tsx
index 366f9231579..6a85ccee96a 100644
--- a/apps/web/src/components/ChatMarkdown.tsx
+++ b/apps/web/src/components/ChatMarkdown.tsx
@@ -1,8 +1,10 @@
 import { DiffsHighlighter, getSharedHighlighter, SupportedLanguages } from "@pierre/diffs";
 import { CheckIcon, CopyIcon } from "lucide-react";
+import type { ServerProviderSkill } from "@t3tools/contracts";
 import React, {
   Children,
   Suspense,
+  type MouseEvent as ReactMouseEvent,
   isValidElement,
   use,
   useCallback,
@@ -17,13 +19,22 @@ import type { Components } from "react-markdown";
 import ReactMarkdown from "react-markdown";
 import { defaultUrlTransform } from "react-markdown";
 import remarkGfm from "remark-gfm";
+import { VscodeEntryIcon } from "./chat/VscodeEntryIcon";
+import { renderSkillInlineMarkdownChildren } from "./chat/SkillInlineText";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+import { stackedThreadToast, toastManager } from "./ui/toast";
 import { openInPreferredEditor } from "../editorPreferences";
 import { resolveDiffThemeName, type DiffThemeName } from "../lib/diffRendering";
 import { fnv1a32 } from "../lib/diffRendering";
 import { LRUCache } from "../lib/lruCache";
 import { useTheme } from "../hooks/useTheme";
-import { resolveMarkdownFileLinkTarget, rewriteMarkdownFileUriHref } from "../markdown-links";
+import {
+  normalizeMarkdownLinkDestination,
+  resolveMarkdownFileLinkMeta,
+  rewriteMarkdownFileUriHref,
+} from "../markdown-links";
 import { readLocalApi } from "../localApi";
+import { cn } from "../lib/utils";
 
 class CodeHighlightErrorBoundary extends React.Component<
   { fallback: ReactNode; children: ReactNode },
@@ -50,8 +61,11 @@ interface ChatMarkdownProps {
   text: string;
   cwd: string | undefined;
   isStreaming?: boolean;
+  skills?: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
 }
 
+const EMPTY_MARKDOWN_SKILLS: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">> = [];
+
 const CODE_FENCE_LANGUAGE_REGEX = /(?:^|\s)language-([^\s]+)/;
 const MAX_HIGHLIGHT_CACHE_ENTRIES = 500;
 const MAX_HIGHLIGHT_CACHE_MEMORY_BYTES = 50 * 1024 * 1024;
@@ -206,6 +220,32 @@ function SuspenseShikiCodeBlock({
     );
   }
 
+  return (
+    <UncachedShikiCodeBlock
+      code={code}
+      language={language}
+      themeName={themeName}
+      cacheKey={cacheKey}
+      isStreaming={isStreaming}
+    />
+  );
+}
+
+interface UncachedShikiCodeBlockProps {
+  code: string;
+  language: string;
+  themeName: DiffThemeName;
+  cacheKey: string;
+  isStreaming: boolean;
+}
+
+function UncachedShikiCodeBlock({
+  code,
+  language,
+  themeName,
+  cacheKey,
+  isStreaming,
+}: UncachedShikiCodeBlockProps) {
   const highlighter = use(getHighlighterPromise(language));
   const highlightedHtml = useMemo(() => {
     try {
@@ -236,34 +276,307 @@ function SuspenseShikiCodeBlock({
   );
 }
 
-function ChatMarkdown({ text, cwd, isStreaming = false }: ChatMarkdownProps) {
+interface MarkdownFileLinkProps {
+  href: string;
+  targetPath: string;
+  displayPath: string;
+  filePath: string;
+  label: string;
+  theme: "light" | "dark";
+  className?: string | undefined;
+}
+
+const MARKDOWN_LINK_HREF_PATTERN = /\[[^\]]*]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
+const MARKDOWN_FILE_LINK_CLASS_NAME =
+  "chat-markdown-file-link relative top-[2px] max-w-full no-underline";
+const MARKDOWN_FILE_LINK_ICON_CLASS_NAME = "chat-markdown-file-link-icon size-3.5 shrink-0";
+const MARKDOWN_FILE_LINK_LABEL_CLASS_NAME = "chat-markdown-file-link-label truncate";
+
+function pathParentSegments(path: string): string[] {
+  const normalized = path.replaceAll("\\", "/");
+  const segments = normalized.split("/").filter((segment) => segment.length > 0);
+  return segments.slice(0, -1);
+}
+
+function buildFileLinkParentSuffixByPath(filePaths: ReadonlyArray<string>): Map<string, string> {
+  const groups = new Map<string, Set<string>>();
+  for (const filePath of filePaths) {
+    const pathSegments = filePath
+      .replaceAll("\\", "/")
+      .split("/")
+      .filter((segment) => segment.length > 0);
+    const basename = pathSegments[pathSegments.length - 1];
+    if (!basename) continue;
+    const group = groups.get(basename) ?? new Set<string>();
+    group.add(filePath);
+    groups.set(basename, group);
+  }
+
+  const suffixByPath = new Map<string, string>();
+  for (const group of groups.values()) {
+    const uniquePaths = [...group];
+    if (uniquePaths.length < 2) continue;
+
+    const parentSegmentsByPath = new Map(
+      uniquePaths.map((filePath) => [filePath, pathParentSegments(filePath)]),
+    );
+    const minUniqueDepthByPath = new Map<string, number>();
+
+    for (const filePath of uniquePaths) {
+      const segments = parentSegmentsByPath.get(filePath) ?? [];
+      let resolvedDepth = segments.length;
+      for (let depth = 1; depth <= segments.length; depth += 1) {
+        const candidate = segments.slice(-depth).join("/");
+        const collision = uniquePaths.some((otherPath) => {
+          if (otherPath === filePath) return false;
+          const otherSegments = parentSegmentsByPath.get(otherPath) ?? [];
+          return otherSegments.slice(-depth).join("/") === candidate;
+        });
+        if (!collision) {
+          resolvedDepth = depth;
+          break;
+        }
+      }
+      minUniqueDepthByPath.set(filePath, resolvedDepth);
+    }
+
+    for (const filePath of uniquePaths) {
+      const segments = parentSegmentsByPath.get(filePath) ?? [];
+      if (segments.length === 0) continue;
+      const minUniqueDepth = minUniqueDepthByPath.get(filePath) ?? 1;
+      const suffixDepth = Math.min(segments.length, Math.max(minUniqueDepth, 2));
+      suffixByPath.set(filePath, segments.slice(-suffixDepth).join("/"));
+    }
+  }
+
+  return suffixByPath;
+}
+
+function extractMarkdownLinkHrefs(text: string): string[] {
+  const hrefs: string[] = [];
+  for (const match of text.matchAll(MARKDOWN_LINK_HREF_PATTERN)) {
+    const href = match[1]?.trim();
+    if (!href) continue;
+    hrefs.push(href);
+  }
+  return hrefs;
+}
+
+function normalizeMarkdownLinkHrefKey(href: string): string {
+  const normalizedHref = normalizeMarkdownLinkDestination(href);
+  return rewriteMarkdownFileUriHref(normalizedHref) ?? normalizedHref;
+}
+
+const MarkdownFileLink = memo(function MarkdownFileLink({
+  href,
+  targetPath,
+  displayPath,
+  filePath,
+  label,
+  theme,
+  className,
+}: MarkdownFileLinkProps) {
+  const handleOpen = useCallback(() => {
+    const api = readLocalApi();
+    if (!api) {
+      toastManager.add({
+        type: "error",
+        title: "Open in editor is unavailable",
+      });
+      return;
+    }
+
+    void openInPreferredEditor(api, targetPath).catch((error) => {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Unable to open file",
+          description: error instanceof Error ? error.message : "An error occurred.",
+        }),
+      );
+    });
+  }, [targetPath]);
+
+  const handleCopy = useCallback((value: string, title: string) => {
+    if (typeof window === "undefined" || !navigator.clipboard?.writeText) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: `Failed to copy ${title.toLowerCase()}`,
+          description: "Clipboard API unavailable.",
+        }),
+      );
+      return;
+    }
+
+    void navigator.clipboard.writeText(value).then(
+      () => {
+        toastManager.add({
+          type: "success",
+          title: `${title} copied`,
+          description: value,
+        });
+      },
+      (error) => {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: `Failed to copy ${title.toLowerCase()}`,
+            description: error instanceof Error ? error.message : "An error occurred.",
+          }),
+        );
+      },
+    );
+  }, []);
+
+  const handleContextMenu = useCallback(
+    async (event: ReactMouseEvent<HTMLAnchorElement>) => {
+      event.preventDefault();
+      event.stopPropagation();
+
+      const api = readLocalApi();
+      if (!api) return;
+
+      const clicked = await api.contextMenu.show(
+        [
+          { id: "open", label: "Open in editor" },
+          { id: "copy-relative", label: "Copy relative path" },
+          { id: "copy-full", label: "Copy full path" },
+        ] as const,
+        { x: event.clientX, y: event.clientY },
+      );
+
+      if (clicked === "open") {
+        handleOpen();
+        return;
+      }
+      if (clicked === "copy-relative") {
+        handleCopy(displayPath, "Relative path");
+        return;
+      }
+      if (clicked === "copy-full") {
+        handleCopy(targetPath, "Full path");
+      }
+    },
+    [displayPath, handleCopy, handleOpen, targetPath],
+  );
+
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <a
+            href={href}
+            className={cn(MARKDOWN_FILE_LINK_CLASS_NAME, className)}
+            onClick={(event) => {
+              event.preventDefault();
+              event.stopPropagation();
+              handleOpen();
+            }}
+            onContextMenu={handleContextMenu}
+          >
+            <VscodeEntryIcon
+              pathValue={filePath}
+              kind="file"
+              theme={theme}
+              className={cn(MARKDOWN_FILE_LINK_ICON_CLASS_NAME, "text-current")}
+            />
+            <span className={MARKDOWN_FILE_LINK_LABEL_CLASS_NAME}>{label}</span>
+          </a>
+        }
+      />
+      <TooltipPopup
+        side="top"
+        className="max-w-[min(40rem,calc(100vw-2rem))] font-mono text-[11px] leading-tight"
+      >
+        <div className="markdown-file-link-tooltip-scroll overflow-x-auto whitespace-nowrap">
+          {displayPath}
+        </div>
+      </TooltipPopup>
+    </Tooltip>
+  );
+}, areMarkdownFileLinkPropsEqual);
+
+function areMarkdownFileLinkPropsEqual(
+  previous: Readonly<MarkdownFileLinkProps>,
+  next: Readonly<MarkdownFileLinkProps>,
+): boolean {
+  return (
+    previous.href === next.href &&
+    previous.targetPath === next.targetPath &&
+    previous.displayPath === next.displayPath &&
+    previous.filePath === next.filePath &&
+    previous.label === next.label &&
+    previous.theme === next.theme &&
+    previous.className === next.className
+  );
+}
+
+function ChatMarkdown({
+  text,
+  cwd,
+  isStreaming = false,
+  skills = EMPTY_MARKDOWN_SKILLS,
+}: ChatMarkdownProps) {
   const { resolvedTheme } = useTheme();
   const diffThemeName = resolveDiffThemeName(resolvedTheme);
+  const markdownFileLinkMetaByHref = useMemo(() => {
+    const metaByHref = new Map<
+      string,
+      NonNullable<ReturnType<typeof resolveMarkdownFileLinkMeta>>
+    >();
+    for (const href of extractMarkdownLinkHrefs(text)) {
+      const normalizedHref = normalizeMarkdownLinkHrefKey(href);
+      if (metaByHref.has(normalizedHref)) continue;
+      const meta = resolveMarkdownFileLinkMeta(normalizedHref, cwd);
+      if (meta) {
+        metaByHref.set(normalizedHref, meta);
+      }
+    }
+    return metaByHref;
+  }, [cwd, text]);
+  const fileLinkParentSuffixByPath = useMemo(() => {
+    const filePaths = [...markdownFileLinkMetaByHref.values()].map((meta) => meta.filePath);
+    return buildFileLinkParentSuffixByPath(filePaths);
+  }, [markdownFileLinkMetaByHref]);
   const markdownUrlTransform = useCallback((href: string) => {
     return rewriteMarkdownFileUriHref(href) ?? defaultUrlTransform(href);
   }, []);
   const markdownComponents = useMemo<Components>(
     () => ({
+      p({ node: _node, children, ...props }) {
+        return <p {...props}>{renderSkillInlineMarkdownChildren(children, skills)}</p>;
+      },
+      li({ node: _node, children, ...props }) {
+        return <li {...props}>{renderSkillInlineMarkdownChildren(children, skills)}</li>;
+      },
       a({ node: _node, href, ...props }) {
-        const targetPath = resolveMarkdownFileLinkTarget(href, cwd);
-        if (!targetPath) {
+        const normalizedHref = href ? normalizeMarkdownLinkHrefKey(href) : "";
+        const fileLinkMeta = normalizedHref ? markdownFileLinkMetaByHref.get(normalizedHref) : null;
+        if (!fileLinkMeta) {
           return <a {...props} href={href} target="_blank" rel="noopener noreferrer" />;
         }
 
+        const parentSuffix = fileLinkParentSuffixByPath.get(fileLinkMeta.filePath);
+        const labelParts = [fileLinkMeta.basename];
+        if (typeof parentSuffix === "string" && parentSuffix.length > 0) {
+          labelParts.push(parentSuffix);
+        }
+        if (fileLinkMeta.line) {
+          labelParts.push(
+            `L${fileLinkMeta.line}${fileLinkMeta.column ? `:C${fileLinkMeta.column}` : ""}`,
+          );
+        }
+
         return (
-          <a
-            {...props}
-            href={href}
-            onClick={(event) => {
-              event.preventDefault();
-              event.stopPropagation();
-              const api = readLocalApi();
-              if (api) {
-                void openInPreferredEditor(api, targetPath);
-              } else {
-                console.warn("Native API not found. Unable to open file in editor.");
-              }
-            }}
+          <MarkdownFileLink
+            href={fileLinkMeta.targetPath}
+            targetPath={fileLinkMeta.targetPath}
+            displayPath={fileLinkMeta.displayPath}
+            filePath={fileLinkMeta.filePath}
+            label={labelParts.join(" · ")}
+            theme={resolvedTheme}
+            className={props.className}
           />
         );
       },
@@ -289,7 +602,14 @@ function ChatMarkdown({ text, cwd, isStreaming = false }: ChatMarkdownProps) {
         );
       },
     }),
-    [cwd, diffThemeName, isStreaming],
+    [
+      diffThemeName,
+      fileLinkParentSuffixByPath,
+      isStreaming,
+      markdownFileLinkMetaByHref,
+      resolvedTheme,
+      skills,
+    ],
   );
 
   return (
diff --git a/apps/web/src/components/ChatView.browser.tsx b/apps/web/src/components/ChatView.browser.tsx
index a65f5755f9a..bb62d8edbc0 100644
--- a/apps/web/src/components/ChatView.browser.tsx
+++ b/apps/web/src/components/ChatView.browser.tsx
@@ -5,10 +5,12 @@ import {
   EventId,
   ORCHESTRATION_WS_METHODS,
   EnvironmentId,
+  type EnvironmentApi,
   type MessageId,
-  type OrchestrationEvent,
   type OrchestrationReadModel,
   type ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerConfig,
   type ServerLifecycleWelcomePayload,
   type ThreadId,
@@ -16,14 +18,13 @@ import {
   WS_METHODS,
   OrchestrationSessionStatus,
   DEFAULT_SERVER_SETTINGS,
+  ServerConfig as ServerConfigSchema,
 } from "@t3tools/contracts";
-import {
-  scopedProjectKey,
-  scopedThreadKey,
-  scopeProjectRef,
-  scopeThreadRef,
-} from "@t3tools/client-runtime";
+import { scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
+import { createModelCapabilities, createModelSelection } from "@t3tools/shared/model";
 import { RouterProvider, createMemoryHistory } from "@tanstack/react-router";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 import { HttpResponse, http, ws } from "msw";
 import { setupWorker } from "msw/browser";
 import { page } from "vitest/browser";
@@ -32,6 +33,16 @@ import { render } from "vitest-browser-react";
 
 import { useCommandPaletteStore } from "../commandPaletteStore";
 import { useComposerDraftStore, DraftId } from "../composerDraftStore";
+import {
+  __resetEnvironmentApiOverridesForTests,
+  __setEnvironmentApiOverrideForTests,
+} from "../environmentApi";
+import {
+  resetSavedEnvironmentRegistryStoreForTests,
+  resetSavedEnvironmentRuntimeStoreForTests,
+  useSavedEnvironmentRegistryStore,
+  useSavedEnvironmentRuntimeStore,
+} from "../environments/runtime";
 import {
   INLINE_TERMINAL_CONTEXT_PLACEHOLDER,
   removeInlineTerminalContextPlaceholder,
@@ -42,12 +53,13 @@ import { __resetLocalApiForTests } from "../localApi";
 import { AppAtomRegistryProvider } from "../rpc/atomRegistry";
 import { getServerConfig } from "../rpc/serverState";
 import { getRouter } from "../router";
+import { deriveLogicalProjectKeyFromSettings } from "../logicalProject";
 import { selectBootstrapCompleteForActiveEnvironment, useStore } from "../store";
 import { useTerminalStateStore } from "../terminalStateStore";
 import { useUiStateStore } from "../uiStateStore";
 import { createAuthenticatedSessionHandlers } from "../../test/authHttpHandlers";
 import { BrowserWsRpcHarness, type NormalizedWsRpcRequestBody } from "../../test/wsRpcHarness";
-import { estimateTimelineMessageHeight } from "./timelineHeight";
+
 import { DEFAULT_CLIENT_SETTINGS } from "@t3tools/contracts/settings";
 
 vi.mock("../lib/gitStatusState", () => ({
@@ -58,18 +70,32 @@ vi.mock("../lib/gitStatusState", () => ({
 }));
 
 const THREAD_ID = "thread-browser-test" as ThreadId;
+const THREAD_TITLE = "Browser test thread";
 const ARCHIVED_SECONDARY_THREAD_ID = "thread-secondary-project-archived" as ThreadId;
 const PROJECT_ID = "project-1" as ProjectId;
 const SECOND_PROJECT_ID = "project-2" as ProjectId;
 const LOCAL_ENVIRONMENT_ID = EnvironmentId.make("environment-local");
+const REMOTE_ENVIRONMENT_ID = EnvironmentId.make("environment-remote");
 const THREAD_REF = scopeThreadRef(LOCAL_ENVIRONMENT_ID, THREAD_ID);
 const THREAD_KEY = scopedThreadKey(THREAD_REF);
 const UUID_ROUTE_RE = /^\/draft\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const PROJECT_DRAFT_KEY = `${LOCAL_ENVIRONMENT_ID}:${PROJECT_ID}`;
-const PROJECT_KEY = scopedProjectKey(scopeProjectRef(LOCAL_ENVIRONMENT_ID, PROJECT_ID));
+const PROJECT_LOGICAL_KEY = deriveLogicalProjectKeyFromSettings(
+  {
+    environmentId: LOCAL_ENVIRONMENT_ID,
+    id: PROJECT_ID,
+    cwd: "/repo/project",
+    repositoryIdentity: null,
+  },
+  {
+    sidebarProjectGroupingMode: DEFAULT_CLIENT_SETTINGS.sidebarProjectGroupingMode,
+    sidebarProjectGroupingOverrides: DEFAULT_CLIENT_SETTINGS.sidebarProjectGroupingOverrides,
+  },
+);
 const NOW_ISO = "2026-03-04T12:00:00.000Z";
 const BASE_TIME_MS = Date.parse(NOW_ISO);
 const ATTACHMENT_SVG = "<svg xmlns='http://www.w3.org/2000/svg' width='120' height='120'></svg>";
+const ADD_PROJECT_SUBMENU_PLACEHOLDER = "Enter path (e.g. ~/projects/my-app)";
 
 interface TestFixture {
   snapshot: OrchestrationReadModel;
@@ -82,6 +108,7 @@ const rpcHarness = new BrowserWsRpcHarness();
 const wsRequests = rpcHarness.requests;
 let customWsRpcResolver: ((body: NormalizedWsRpcRequestBody) => unknown | undefined) | null = null;
 const wsLink = ws.link(/ws(s)?:\/\/.*/);
+const encodeServerConfig = Schema.encodeSync(ServerConfigSchema);
 
 interface ViewportSpec {
   name: string;
@@ -112,28 +139,10 @@ const COMPACT_FOOTER_VIEWPORT: ViewportSpec = {
   textTolerancePx: 56,
   attachmentTolerancePx: 56,
 };
-const TEXT_VIEWPORT_MATRIX = [
-  DEFAULT_VIEWPORT,
-  { name: "tablet", width: 720, height: 1_024, textTolerancePx: 44, attachmentTolerancePx: 56 },
-  { name: "mobile", width: 430, height: 932, textTolerancePx: 56, attachmentTolerancePx: 56 },
-  { name: "narrow", width: 320, height: 700, textTolerancePx: 84, attachmentTolerancePx: 56 },
-] as const satisfies readonly ViewportSpec[];
-const ATTACHMENT_VIEWPORT_MATRIX = [
-  { ...DEFAULT_VIEWPORT, attachmentTolerancePx: 120 },
-  { name: "mobile", width: 430, height: 932, textTolerancePx: 56, attachmentTolerancePx: 120 },
-  { name: "narrow", width: 320, height: 700, textTolerancePx: 84, attachmentTolerancePx: 120 },
-] as const satisfies readonly ViewportSpec[];
-
-interface UserRowMeasurement {
-  measuredRowHeightPx: number;
-  timelineWidthMeasuredPx: number;
-  renderedInVirtualizedRegion: boolean;
-}
 
 interface MountedChatView {
   [Symbol.asyncDispose]: () => Promise<void>;
   cleanup: () => Promise<void>;
-  measureUserRow: (targetMessageId: MessageId) => Promise<UserRowMeasurement>;
   setViewport: (viewport: ViewportSpec) => Promise<void>;
   setContainerSize: (viewport: Pick<ViewportSpec, "width" | "height">) => Promise<void>;
   router: ReturnType<typeof getRouter>;
@@ -164,7 +173,8 @@ function createBaseServerConfig(): ServerConfig {
     issues: [],
     providers: [
       {
-        provider: "codex",
+        driver: ProviderDriverKind.make("codex"),
+        instanceId: ProviderInstanceId.make("codex"),
         enabled: true,
         installed: true,
         version: "0.116.0",
@@ -190,6 +200,37 @@ function createBaseServerConfig(): ServerConfig {
   };
 }
 
+function createMockEnvironmentApi(input: {
+  browse: EnvironmentApi["filesystem"]["browse"];
+  dispatchCommand: EnvironmentApi["orchestration"]["dispatchCommand"];
+}): EnvironmentApi {
+  return {
+    terminal: {} as EnvironmentApi["terminal"],
+    projects: {} as EnvironmentApi["projects"],
+    filesystem: {
+      browse: input.browse,
+    },
+    sourceControl: {} as EnvironmentApi["sourceControl"],
+    vcs: {} as EnvironmentApi["vcs"],
+    git: {} as EnvironmentApi["git"],
+    orchestration: {
+      dispatchCommand: input.dispatchCommand,
+      getTurnDiff: (() => {
+        throw new Error("Not implemented in browser test.");
+      }) as EnvironmentApi["orchestration"]["getTurnDiff"],
+      getFullThreadDiff: (() => {
+        throw new Error("Not implemented in browser test.");
+      }) as EnvironmentApi["orchestration"]["getFullThreadDiff"],
+      getArchivedShellSnapshot: (() => {
+        throw new Error("Not implemented in browser test.");
+      }) as EnvironmentApi["orchestration"]["getArchivedShellSnapshot"],
+      subscribeShell: (() => () => undefined) as EnvironmentApi["orchestration"]["subscribeShell"],
+      subscribeThread: (() => () =>
+        undefined) as EnvironmentApi["orchestration"]["subscribeThread"],
+    },
+  };
+}
+
 function createUserMessage(options: {
   id: MessageId;
   text: string;
@@ -294,7 +335,7 @@ function createSnapshotForTargetUser(options: {
         title: "Project",
         workspaceRoot: "/repo/project",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         scripts: [],
@@ -307,9 +348,9 @@ function createSnapshotForTargetUser(options: {
       {
         id: THREAD_ID,
         projectId: PROJECT_ID,
-        title: "Browser test thread",
+        title: THREAD_TITLE,
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         interactionMode: "default",
@@ -374,7 +415,7 @@ function addThreadToSnapshot(
         projectId: PROJECT_ID,
         title: "New thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         interactionMode: "default",
@@ -404,74 +445,94 @@ function addThreadToSnapshot(
   };
 }
 
-function createThreadCreatedEvent(threadId: ThreadId, sequence: number): OrchestrationEvent {
+function toShellThread(thread: OrchestrationReadModel["threads"][number]) {
   return {
-    sequence,
-    eventId: EventId.make(`event-thread-created-${sequence}`),
-    aggregateKind: "thread",
-    aggregateId: threadId,
-    occurredAt: NOW_ISO,
-    commandId: null,
-    causationEventId: null,
-    correlationId: null,
-    metadata: {},
-    type: "thread.created",
-    payload: {
-      threadId,
-      projectId: PROJECT_ID,
-      title: "New thread",
-      modelSelection: {
-        provider: "codex",
-        model: "gpt-5",
-      },
-      runtimeMode: "full-access",
-      interactionMode: "default",
-      branch: "main",
-      worktreePath: null,
-      createdAt: NOW_ISO,
-      updatedAt: NOW_ISO,
-    },
+    id: thread.id,
+    projectId: thread.projectId,
+    title: thread.title,
+    modelSelection: thread.modelSelection,
+    runtimeMode: thread.runtimeMode,
+    interactionMode: thread.interactionMode,
+    branch: thread.branch,
+    worktreePath: thread.worktreePath,
+    latestTurn: thread.latestTurn,
+    createdAt: thread.createdAt,
+    updatedAt: thread.updatedAt,
+    archivedAt: thread.archivedAt,
+    session: thread.session,
+    latestUserMessageAt:
+      thread.messages.findLast((message) => message.role === "user")?.createdAt ?? null,
+    hasPendingApprovals: false,
+    hasPendingUserInput: false,
+    hasActionableProposedPlan: false,
   };
 }
 
-function createThreadSessionSetEvent(threadId: ThreadId, sequence: number): OrchestrationEvent {
+function toShellSnapshot(snapshot: OrchestrationReadModel) {
   return {
-    sequence,
-    eventId: EventId.make(`event-thread-session-set-${sequence}`),
-    aggregateKind: "thread",
-    aggregateId: threadId,
-    occurredAt: NOW_ISO,
-    commandId: null,
-    causationEventId: null,
-    correlationId: null,
-    metadata: {},
-    type: "thread.session-set",
-    payload: {
-      threadId,
-      session: {
-        threadId,
-        status: "running",
-        providerName: "codex",
-        runtimeMode: "full-access",
-        activeTurnId: `turn-${threadId}` as TurnId,
-        lastError: null,
-        updatedAt: NOW_ISO,
-      },
-    },
+    snapshotSequence: snapshot.snapshotSequence,
+    projects: snapshot.projects.map((project) => ({
+      id: project.id,
+      title: project.title,
+      workspaceRoot: project.workspaceRoot,
+      repositoryIdentity: project.repositoryIdentity ?? null,
+      defaultModelSelection: project.defaultModelSelection,
+      scripts: project.scripts,
+      createdAt: project.createdAt,
+      updatedAt: project.updatedAt,
+    })),
+    threads: snapshot.threads.map(toShellThread),
+    updatedAt: snapshot.updatedAt,
+  };
+}
+
+function updateThreadSessionInSnapshot(
+  snapshot: OrchestrationReadModel,
+  threadId: ThreadId,
+  session: OrchestrationReadModel["threads"][number]["session"],
+): OrchestrationReadModel {
+  return {
+    ...snapshot,
+    snapshotSequence: snapshot.snapshotSequence + 1,
+    threads: snapshot.threads.map((thread) =>
+      thread.id === threadId
+        ? {
+            ...thread,
+            session,
+            updatedAt: NOW_ISO,
+          }
+        : thread,
+    ),
   };
 }
 
-function sendOrchestrationDomainEvent(event: OrchestrationEvent): void {
-  rpcHarness.emitStreamValue(WS_METHODS.subscribeOrchestrationDomainEvents, event);
+function sendShellThreadUpsert(
+  threadId: ThreadId,
+  options?: {
+    readonly session?: OrchestrationReadModel["threads"][number]["session"];
+  },
+): void {
+  const thread = fixture.snapshot.threads.find((entry) => entry.id === threadId);
+  if (!thread) {
+    throw new Error(`Expected thread ${threadId} in snapshot.`);
+  }
+
+  const shellThread =
+    options?.session !== undefined
+      ? toShellThread({ ...thread, session: options.session })
+      : toShellThread(thread);
+  rpcHarness.emitStreamValue(ORCHESTRATION_WS_METHODS.subscribeShell, {
+    kind: "thread-upserted",
+    sequence: fixture.snapshot.snapshotSequence,
+    thread: shellThread,
+  });
 }
 
 async function waitForWsClient(): Promise<void> {
   await vi.waitFor(
     () => {
       expect(
-        wsRequests.some(
-          (request) => request._tag === WS_METHODS.subscribeOrchestrationDomainEvents,
-        ),
+        wsRequests.some((request) => request._tag === ORCHESTRATION_WS_METHODS.subscribeShell),
       ).toBe(true);
       expect(
         wsRequests.some((request) => request._tag === WS_METHODS.subscribeServerLifecycle),
@@ -531,15 +592,21 @@ async function waitForAppBootstrap(): Promise<void> {
 async function materializePromotedDraftThreadViaDomainEvent(threadId: ThreadId): Promise<void> {
   await waitForWsClient();
   fixture.snapshot = addThreadToSnapshot(fixture.snapshot, threadId);
-  sendOrchestrationDomainEvent(
-    createThreadCreatedEvent(threadId, fixture.snapshot.snapshotSequence),
-  );
+  fixture.snapshot = updateThreadSessionInSnapshot(fixture.snapshot, threadId, null);
+  sendShellThreadUpsert(threadId, { session: null });
 }
 
 async function startPromotedServerThreadViaDomainEvent(threadId: ThreadId): Promise<void> {
-  sendOrchestrationDomainEvent(
-    createThreadSessionSetEvent(threadId, fixture.snapshot.snapshotSequence + 1),
-  );
+  fixture.snapshot = updateThreadSessionInSnapshot(fixture.snapshot, threadId, {
+    threadId,
+    status: "running",
+    providerName: "codex",
+    runtimeMode: "full-access",
+    activeTurnId: `turn-${threadId}` as TurnId,
+    lastError: null,
+    updatedAt: NOW_ISO,
+  });
+  sendShellThreadUpsert(threadId);
 }
 
 async function promoteDraftThreadViaDomainEvent(threadId: ThreadId): Promise<void> {
@@ -685,7 +752,7 @@ function createSnapshotWithSecondaryProject(options?: {
           id: "thread-secondary-project" as ThreadId,
           projectId: SECOND_PROJECT_ID,
           title: "Release checklist",
-          modelSelection: { provider: "codex", model: "gpt-5" },
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
           interactionMode: "default",
           runtimeMode: "full-access",
           branch: "release/docs-portal",
@@ -717,7 +784,7 @@ function createSnapshotWithSecondaryProject(options?: {
           id: ARCHIVED_SECONDARY_THREAD_ID,
           projectId: SECOND_PROJECT_ID,
           title: "Archived Docs Notes",
-          modelSelection: { provider: "codex", model: "gpt-5" },
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
           interactionMode: "default",
           runtimeMode: "full-access",
           branch: "release/docs-archive",
@@ -752,7 +819,7 @@ function createSnapshotWithSecondaryProject(options?: {
         id: SECOND_PROJECT_ID,
         title: "Docs Portal",
         workspaceRoot: "/repo/clients/docs-portal",
-        defaultModelSelection: { provider: "codex", model: "gpt-5" },
+        defaultModelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
         scripts: [],
         createdAt: NOW_ISO,
         updatedAt: NOW_ISO,
@@ -829,7 +896,7 @@ function createSnapshotWithPendingUserInput(): OrchestrationReadModel {
 }
 
 function createSnapshotWithPlanFollowUpPrompt(options?: {
-  modelSelection?: { provider: "codex"; model: string };
+  modelSelection?: { instanceId: ProviderInstanceId; model: string };
   planMarkdown?: string;
 }): OrchestrationReadModel {
   const snapshot = createSnapshotForTargetUser({
@@ -837,7 +904,7 @@ function createSnapshotWithPlanFollowUpPrompt(options?: {
     targetText: "plan follow-up thread",
   });
   const modelSelection = options?.modelSelection ?? {
-    provider: "codex" as const,
+    instanceId: ProviderInstanceId.make("codex"),
     model: "gpt-5",
   };
   const planMarkdown =
@@ -890,19 +957,83 @@ function resolveWsRpc(body: NormalizedWsRpcRequestBody): unknown {
     return customResult;
   }
   const tag = body._tag;
-  if (tag === ORCHESTRATION_WS_METHODS.getSnapshot) {
-    return fixture.snapshot;
-  }
   if (tag === WS_METHODS.serverGetConfig) {
-    return fixture.serverConfig;
+    return encodeServerConfig(fixture.serverConfig);
+  }
+  if (tag === WS_METHODS.serverDiscoverSourceControl) {
+    return {
+      versionControlSystems: [],
+      sourceControlProviders: [
+        {
+          kind: "github",
+          label: "GitHub",
+          executable: "gh",
+          status: "available",
+          version: Option.some("gh version 2.0.0"),
+          installHint: "Install GitHub CLI.",
+          detail: Option.none(),
+          auth: {
+            status: "authenticated",
+            account: Option.some("t3-oss"),
+            host: Option.some("github.com"),
+            detail: Option.none(),
+          },
+        },
+        {
+          kind: "gitlab",
+          label: "GitLab",
+          executable: "glab",
+          status: "available",
+          version: Option.some("glab version 1.0.0"),
+          installHint: "Install GitLab CLI.",
+          detail: Option.none(),
+          auth: {
+            status: "authenticated",
+            account: Option.some("t3-oss"),
+            host: Option.some("gitlab.com"),
+            detail: Option.none(),
+          },
+        },
+        {
+          kind: "bitbucket",
+          label: "Bitbucket",
+          executable: "Bitbucket REST API",
+          status: "available",
+          version: Option.none(),
+          installHint: "Set Bitbucket API token environment variables.",
+          detail: Option.none(),
+          auth: {
+            status: "authenticated",
+            account: Option.some("t3-oss"),
+            host: Option.some("bitbucket.org"),
+            detail: Option.none(),
+          },
+        },
+        {
+          kind: "azure-devops",
+          label: "Azure DevOps",
+          executable: "az",
+          status: "available",
+          version: Option.some("azure-cli 2.0.0"),
+          installHint: "Install Azure CLI.",
+          detail: Option.none(),
+          auth: {
+            status: "authenticated",
+            account: Option.some("t3-oss"),
+            host: Option.some("dev.azure.com"),
+            detail: Option.none(),
+          },
+        },
+      ],
+    };
   }
-  if (tag === WS_METHODS.gitListBranches) {
+  if (tag === WS_METHODS.vcsListRefs) {
     return {
       isRepo: true,
-      hasOriginRemote: true,
+      hasPrimaryRemote: true,
       nextCursor: null,
       totalCount: 1,
-      branches: [
+      refs: [
         {
           name: "main",
           current: true,
@@ -1333,6 +1464,18 @@ function dispatchChatNewShortcut(): void {
   );
 }
 
+function releaseModShortcut(key?: string): void {
+  window.dispatchEvent(
+    new KeyboardEvent("keyup", {
+      key: key ?? (isMacPlatform(navigator.platform) ? "Meta" : "Control"),
+      metaKey: false,
+      ctrlKey: false,
+      bubbles: true,
+      cancelable: true,
+    }),
+  );
+}
+
 async function triggerChatNewShortcutUntilPath(
   router: ReturnType<typeof getRouter>,
   predicate: (pathname: string) => boolean,
@@ -1378,89 +1521,42 @@ async function waitForCommandPaletteShortcutLabel(): Promise<void> {
   );
 }
 
-async function waitForImagesToLoad(scope: ParentNode): Promise<void> {
-  const images = Array.from(scope.querySelectorAll("img"));
-  if (images.length === 0) {
-    return;
-  }
-  await Promise.all(
-    images.map(
-      (image) =>
-        new Promise<void>((resolve) => {
-          if (image.complete) {
-            resolve();
-            return;
-          }
-          image.addEventListener("load", () => resolve(), { once: true });
-          image.addEventListener("error", () => resolve(), { once: true });
-        }),
-    ),
+async function waitForCommandPaletteInput(placeholder: string): Promise<HTMLInputElement> {
+  return waitForElement(
+    () => document.querySelector(`input[placeholder="${placeholder}"]`) as HTMLInputElement | null,
+    `Command palette input with placeholder "${placeholder}" did not render.`,
   );
-  await waitForLayout();
 }
 
-async function measureUserRow(options: {
-  host: HTMLElement;
-  targetMessageId: MessageId;
-}): Promise<UserRowMeasurement> {
-  const { host, targetMessageId } = options;
-  const rowSelector = `[data-message-id="${targetMessageId}"][data-message-role="user"]`;
-
-  const scrollContainer = await waitForElement(
-    () => host.querySelector<HTMLDivElement>("div.overflow-y-auto.overscroll-y-contain"),
-    "Unable to find ChatView message scroll container.",
-  );
-
-  let row: HTMLElement | null = null;
-  await vi.waitFor(
-    async () => {
-      scrollContainer.scrollTop = 0;
-      scrollContainer.dispatchEvent(new Event("scroll"));
-      await waitForLayout();
-      row = host.querySelector<HTMLElement>(rowSelector);
-      expect(row, "Unable to locate targeted user message row.").toBeTruthy();
-    },
-    {
-      timeout: 8_000,
-      interval: 16,
-    },
-  );
-
-  await waitForImagesToLoad(row!);
-  scrollContainer.scrollTop = 0;
-  scrollContainer.dispatchEvent(new Event("scroll"));
-  await nextFrame();
-
-  const timelineRoot =
-    row!.closest<HTMLElement>('[data-timeline-root="true"]') ??
-    host.querySelector<HTMLElement>('[data-timeline-root="true"]');
-  if (!(timelineRoot instanceof HTMLElement)) {
-    throw new Error("Unable to locate timeline root container.");
+function getCommandPaletteLegendEntries(): string[] {
+  const footer = document.querySelector('[data-slot="command-footer"]');
+  if (!footer) {
+    return [];
   }
 
-  let timelineWidthMeasuredPx = 0;
-  let measuredRowHeightPx = 0;
-  let renderedInVirtualizedRegion = false;
-  await vi.waitFor(
-    async () => {
-      scrollContainer.scrollTop = 0;
-      scrollContainer.dispatchEvent(new Event("scroll"));
-      await nextFrame();
-      const measuredRow = host.querySelector<HTMLElement>(rowSelector);
-      expect(measuredRow, "Unable to measure targeted user row height.").toBeTruthy();
-      timelineWidthMeasuredPx = timelineRoot.getBoundingClientRect().width;
-      measuredRowHeightPx = measuredRow!.getBoundingClientRect().height;
-      renderedInVirtualizedRegion = measuredRow!.closest("[data-index]") instanceof HTMLElement;
-      expect(timelineWidthMeasuredPx, "Unable to measure timeline width.").toBeGreaterThan(0);
-      expect(measuredRowHeightPx, "Unable to measure targeted user row height.").toBeGreaterThan(0);
-    },
-    {
-      timeout: 4_000,
-      interval: 16,
-    },
-  );
+  return Array.from(footer.querySelectorAll('[data-slot="kbd-group"]'))
+    .map((group) =>
+      Array.from(group.children)
+        .map((child) => child.textContent?.trim() ?? "")
+        .filter((value) => value.length > 0)
+        .join(" "),
+    )
+    .filter((value) => value.length > 0);
+}
 
-  return { measuredRowHeightPx, timelineWidthMeasuredPx, renderedInVirtualizedRegion };
+async function dispatchInputKey(
+  input: HTMLInputElement,
+  init: Pick<KeyboardEventInit, "key" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey">,
+): Promise<void> {
+  input.focus();
+  input.dispatchEvent(
+    new KeyboardEvent("keydown", {
+      bubbles: true,
+      cancelable: true,
+      ...init,
+    }),
+  );
+  await waitForLayout();
 }
 
 async function mountChatView(options: {
@@ -1515,7 +1611,6 @@ async function mountChatView(options: {
   return {
     [Symbol.asyncDispose]: cleanup,
     cleanup,
-    measureUserRow: async (targetMessageId: MessageId) => measureUserRow({ host, targetMessageId }),
     setViewport: async (viewport: ViewportSpec) => {
       await setViewport(viewport);
       await waitForProductionStyles();
@@ -1529,23 +1624,6 @@ async function mountChatView(options: {
   };
 }
 
-async function measureUserRowAtViewport(options: {
-  snapshot: OrchestrationReadModel;
-  targetMessageId: MessageId;
-  viewport: ViewportSpec;
-}): Promise<UserRowMeasurement> {
-  const mounted = await mountChatView({
-    viewport: options.viewport,
-    snapshot: options.snapshot,
-  });
-
-  try {
-    return await mounted.measureUserRow(options.targetMessageId);
-  } finally {
-    await mounted.cleanup();
-  }
-}
-
 describe("ChatView timeline estimator parity (full app)", () => {
   beforeAll(async () => {
     fixture = buildFixture(
@@ -1587,10 +1665,32 @@ describe("ChatView timeline estimator parity (full app)", () => {
             {
               version: 1,
               type: "snapshot",
-              config: fixture.serverConfig,
+              config: encodeServerConfig(fixture.serverConfig),
+            },
+          ];
+        }
+        if (request._tag === ORCHESTRATION_WS_METHODS.subscribeShell) {
+          return [
+            {
+              kind: "snapshot",
+              snapshot: toShellSnapshot(fixture.snapshot),
             },
           ];
         }
+        if (request._tag === ORCHESTRATION_WS_METHODS.subscribeThread) {
+          const thread = fixture.snapshot.threads.find((entry) => entry.id === request.threadId);
+          return thread
+            ? [
+                {
+                  kind: "snapshot",
+                  snapshot: {
+                    snapshotSequence: fixture.snapshot.snapshotSequence,
+                    thread,
+                  },
+                },
+              ]
+            : [];
+        }
         return [];
       },
     });
@@ -1600,6 +1700,10 @@ describe("ChatView timeline estimator parity (full app)", () => {
     document.body.innerHTML = "";
     wsRequests.length = 0;
     customWsRpcResolver = null;
+    __resetEnvironmentApiOverridesForTests();
+    resetSavedEnvironmentRegistryStoreForTests();
+    resetSavedEnvironmentRuntimeStoreForTests();
+    Reflect.deleteProperty(window, "desktopBridge");
     useComposerDraftStore.setState({
       draftsByThreadKey: {},
       draftThreadsByThreadKey: {},
@@ -1609,6 +1713,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
     });
     useCommandPaletteStore.setState({
       open: false,
+      openIntent: null,
     });
     useStore.setState({
       activeEnvironmentId: null,
@@ -1633,45 +1738,79 @@ describe("ChatView timeline estimator parity (full app)", () => {
     document.body.innerHTML = "";
   });
 
-  it.each(TEXT_VIEWPORT_MATRIX)(
-    "keeps long user message estimate close at the $name viewport",
-    async (viewport) => {
-      const userText = "x".repeat(3_200);
-      const targetMessageId = `msg-user-target-long-${viewport.name}` as MessageId;
-      const mounted = await mountChatView({
-        viewport,
-        snapshot: createSnapshotForTargetUser({
-          targetMessageId,
-          targetText: userText,
-        }),
-      });
+  it("renders locked single-environment mobile run context as a static workspace label", async () => {
+    const mounted = await mountChatView({
+      viewport: COMPACT_FOOTER_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-mobile-locked-workspace" as MessageId,
+        targetText: "locked mobile workspace",
+      }),
+    });
+
+    try {
+      await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll<HTMLElement>("span")).find(
+            (element) => element.textContent?.trim() === "Local checkout",
+          ) ?? null,
+        "Unable to find static mobile workspace label.",
+      );
 
-      try {
-        const { measuredRowHeightPx, timelineWidthMeasuredPx, renderedInVirtualizedRegion } =
-          await mounted.measureUserRow(targetMessageId);
+      expect(findButtonByText("Local checkout")).toBeNull();
+    } finally {
+      await mounted.cleanup();
+    }
+  });
 
-        expect(renderedInVirtualizedRegion).toBe(true);
+  it("keeps dismiss-only composer banners aligned on mobile", async () => {
+    const mounted = await mountChatView({
+      viewport: COMPACT_FOOTER_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-mobile-version-banner" as MessageId,
+        targetText: "mobile version banner",
+      }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          environment: {
+            ...nextFixture.serverConfig.environment,
+            serverVersion: "9.9.9",
+          },
+        };
+      },
+    });
 
-        const estimatedHeightPx = estimateTimelineMessageHeight(
-          { role: "user", text: userText, attachments: [] },
-          { timelineWidthPx: timelineWidthMeasuredPx },
-        );
+    try {
+      const banner = await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll<HTMLElement>('[data-slot="alert"]')).find(
+            (element) => element.textContent?.includes("Client and server versions differ"),
+          ) ?? null,
+        "Unable to find version mismatch banner.",
+      );
+      const title = banner.querySelector<HTMLElement>('[data-slot="alert-title"]');
+      const description = banner.querySelector<HTMLElement>('[data-slot="alert-description"]');
+      const dismissButton = banner.querySelector<HTMLButtonElement>(
+        'button[aria-label="Dismiss version mismatch warning"]',
+      );
 
-        expect(Math.abs(measuredRowHeightPx - estimatedHeightPx)).toBeLessThanOrEqual(
-          viewport.textTolerancePx,
-        );
-      } finally {
-        await mounted.cleanup();
-      }
-    },
-  );
+      expect(title).toBeTruthy();
+      expect(description).toBeTruthy();
+      expect(dismissButton).toBeTruthy();
+      expect(dismissButton!.getBoundingClientRect().top).toBeLessThan(
+        description!.getBoundingClientRect().top,
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
 
-  it("re-expands the bootstrap project using its scoped key", async () => {
+  it("re-expands the bootstrap project using its logical key", async () => {
     useUiStateStore.setState({
       projectExpandedById: {
-        [PROJECT_KEY]: false,
+        [PROJECT_LOGICAL_KEY]: false,
       },
-      projectOrder: [PROJECT_KEY],
+      projectOrder: [PROJECT_LOGICAL_KEY],
       threadLastVisitedAtById: {},
     });
 
@@ -1686,7 +1825,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
     try {
       await vi.waitFor(
         () => {
-          expect(useUiStateStore.getState().projectExpandedById[PROJECT_KEY]).toBe(true);
+          expect(useUiStateStore.getState().projectExpandedById[PROJECT_LOGICAL_KEY]).toBe(true);
         },
         { timeout: 8_000, interval: 16 },
       );
@@ -1695,130 +1834,6 @@ describe("ChatView timeline estimator parity (full app)", () => {
     }
   });
 
-  it("tracks wrapping parity while resizing an existing ChatView across the viewport matrix", async () => {
-    const userText = "x".repeat(3_200);
-    const targetMessageId = "msg-user-target-resize" as MessageId;
-    const mounted = await mountChatView({
-      viewport: TEXT_VIEWPORT_MATRIX[0],
-      snapshot: createSnapshotForTargetUser({
-        targetMessageId,
-        targetText: userText,
-      }),
-    });
-
-    try {
-      const measurements: Array<
-        UserRowMeasurement & { viewport: ViewportSpec; estimatedHeightPx: number }
-      > = [];
-
-      for (const viewport of TEXT_VIEWPORT_MATRIX) {
-        await mounted.setViewport(viewport);
-        const measurement = await mounted.measureUserRow(targetMessageId);
-        const estimatedHeightPx = estimateTimelineMessageHeight(
-          { role: "user", text: userText, attachments: [] },
-          { timelineWidthPx: measurement.timelineWidthMeasuredPx },
-        );
-
-        expect(measurement.renderedInVirtualizedRegion).toBe(true);
-        expect(Math.abs(measurement.measuredRowHeightPx - estimatedHeightPx)).toBeLessThanOrEqual(
-          viewport.textTolerancePx,
-        );
-        measurements.push({ ...measurement, viewport, estimatedHeightPx });
-      }
-
-      expect(
-        new Set(measurements.map((measurement) => Math.round(measurement.timelineWidthMeasuredPx)))
-          .size,
-      ).toBeGreaterThanOrEqual(3);
-
-      const byMeasuredWidth = measurements.toSorted(
-        (left, right) => left.timelineWidthMeasuredPx - right.timelineWidthMeasuredPx,
-      );
-      const narrowest = byMeasuredWidth[0]!;
-      const widest = byMeasuredWidth.at(-1)!;
-      expect(narrowest.timelineWidthMeasuredPx).toBeLessThan(widest.timelineWidthMeasuredPx);
-      expect(narrowest.measuredRowHeightPx).toBeGreaterThan(widest.measuredRowHeightPx);
-      expect(narrowest.estimatedHeightPx).toBeGreaterThan(widest.estimatedHeightPx);
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-
-  it("tracks additional rendered wrapping when ChatView width narrows between desktop and mobile viewports", async () => {
-    const userText = "x".repeat(2_400);
-    const targetMessageId = "msg-user-target-wrap" as MessageId;
-    const snapshot = createSnapshotForTargetUser({
-      targetMessageId,
-      targetText: userText,
-    });
-    const desktopMeasurement = await measureUserRowAtViewport({
-      viewport: TEXT_VIEWPORT_MATRIX[0],
-      snapshot,
-      targetMessageId,
-    });
-    const mobileMeasurement = await measureUserRowAtViewport({
-      viewport: TEXT_VIEWPORT_MATRIX[2],
-      snapshot,
-      targetMessageId,
-    });
-
-    const estimatedDesktopPx = estimateTimelineMessageHeight(
-      { role: "user", text: userText, attachments: [] },
-      { timelineWidthPx: desktopMeasurement.timelineWidthMeasuredPx },
-    );
-    const estimatedMobilePx = estimateTimelineMessageHeight(
-      { role: "user", text: userText, attachments: [] },
-      { timelineWidthPx: mobileMeasurement.timelineWidthMeasuredPx },
-    );
-
-    const measuredDeltaPx =
-      mobileMeasurement.measuredRowHeightPx - desktopMeasurement.measuredRowHeightPx;
-    const estimatedDeltaPx = estimatedMobilePx - estimatedDesktopPx;
-    expect(measuredDeltaPx).toBeGreaterThan(0);
-    expect(estimatedDeltaPx).toBeGreaterThan(0);
-    const ratio = estimatedDeltaPx / measuredDeltaPx;
-    expect(ratio).toBeGreaterThan(0.65);
-    expect(ratio).toBeLessThan(1.35);
-  });
-
-  it.each(ATTACHMENT_VIEWPORT_MATRIX)(
-    "keeps user attachment estimate close at the $name viewport",
-    async (viewport) => {
-      const targetMessageId = `msg-user-target-attachments-${viewport.name}` as MessageId;
-      const userText = "message with image attachments";
-      const mounted = await mountChatView({
-        viewport,
-        snapshot: createSnapshotForTargetUser({
-          targetMessageId,
-          targetText: userText,
-          targetAttachmentCount: 2,
-        }),
-      });
-
-      try {
-        const { measuredRowHeightPx, timelineWidthMeasuredPx, renderedInVirtualizedRegion } =
-          await mounted.measureUserRow(targetMessageId);
-
-        expect(renderedInVirtualizedRegion).toBe(true);
-
-        const estimatedHeightPx = estimateTimelineMessageHeight(
-          {
-            role: "user",
-            text: userText,
-            attachments: [{ id: "attachment-1" }, { id: "attachment-2" }],
-          },
-          { timelineWidthPx: timelineWidthMeasuredPx },
-        );
-
-        expect(Math.abs(measuredRowHeightPx - estimatedHeightPx)).toBeLessThanOrEqual(
-          viewport.attachmentTolerancePx,
-        );
-      } finally {
-        await mounted.cleanup();
-      }
-    },
-  );
-
   it("shows an explicit empty state for projects without threads in the sidebar", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
@@ -2038,6 +2053,55 @@ describe("ChatView timeline estimator parity (full app)", () => {
     }
   });
 
+  it("shows Kiro in the open picker menu and opens the project cwd with it", async () => {
+    setDraftThreadWithoutWorktree();
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createDraftOnlySnapshot(),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          availableEditors: ["kiro"],
+        };
+      },
+    });
+
+    try {
+      await waitForServerConfigToApply();
+      const menuButton = await waitForElement(
+        () => document.querySelector('button[aria-label="Copy options"]'),
+        "Unable to find Open picker button.",
+      );
+      (menuButton as HTMLButtonElement).click();
+
+      const kiroItem = await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll('[data-slot="menu-item"]')).find((item) =>
+            item.textContent?.includes("Kiro"),
+          ) ?? null,
+        "Unable to find Kiro menu item.",
+      );
+      (kiroItem as HTMLElement).click();
+
+      await vi.waitFor(
+        () => {
+          const openRequest = wsRequests.find(
+            (request) => request._tag === WS_METHODS.shellOpenInEditor,
+          );
+          expect(openRequest).toMatchObject({
+            _tag: WS_METHODS.shellOpenInEditor,
+            cwd: "/repo/project",
+            editor: "kiro",
+          });
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
   it("filters the open picker menu and opens VSCodium from the menu", async () => {
     setDraftThreadWithoutWorktree();
 
@@ -2367,16 +2431,16 @@ describe("ChatView timeline estimator parity (full app)", () => {
       branchButton.click();
 
       const branchInput = await waitForElement(
-        () => document.querySelector<HTMLInputElement>('input[placeholder="Search branches..."]'),
-        "Unable to find branch search input.",
+        () => document.querySelector<HTMLInputElement>('input[placeholder="Search refs..."]'),
+        "Unable to find ref search input.",
       );
       branchInput.focus();
-      await page.getByPlaceholder("Search branches...").fill("1359");
+      await page.getByPlaceholder("Search refs...").fill("1359");
 
       const checkoutItem = await waitForElement(
         () =>
           Array.from(document.querySelectorAll("span")).find(
-            (element) => element.textContent?.trim() === "Checkout Pull Request",
+            (element) => element.textContent?.trim() === "Checkout pull request",
           ) as HTMLSpanElement | null,
         "Unable to find checkout pull request option.",
       );
@@ -2505,7 +2569,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
         { timeout: 8_000, interval: 16 },
       );
 
-      expect(wsRequests.some((request) => request._tag === WS_METHODS.gitCreateWorktree)).toBe(
+      expect(wsRequests.some((request) => request._tag === WS_METHODS.vcsCreateWorktree)).toBe(
         false,
       );
       expect(
@@ -2521,56 +2585,87 @@ describe("ChatView timeline estimator parity (full app)", () => {
     }
   });
 
-  it("shows the send state once bootstrap dispatch is in flight", async () => {
-    useTerminalStateStore.setState({
-      terminalStateByThreadKey: {},
-    });
-    useComposerDraftStore.setState({
-      draftThreadsByThreadKey: {
-        [THREAD_KEY]: {
-          threadId: THREAD_ID,
-          environmentId: LOCAL_ENVIRONMENT_ID,
-          projectId: PROJECT_ID,
-          logicalProjectKey: PROJECT_DRAFT_KEY,
-          createdAt: NOW_ISO,
-          runtimeMode: "full-access",
-          interactionMode: "default",
-          branch: "main",
-          worktreePath: null,
-          envMode: "worktree",
-        },
-      },
-      logicalProjectDraftThreadKeyByLogicalProjectKey: {
-        [PROJECT_DRAFT_KEY]: THREAD_KEY,
-      },
-    });
-
-    let resolveDispatch!: (value: { sequence: number }) => void;
-    const dispatchPromise = new Promise<{ sequence: number }>((resolve) => {
-      resolveDispatch = resolve;
-    });
+  it("keeps custom provider instance ids when bootstrapping a local draft thread", async () => {
+    setDraftThreadWithoutWorktree();
+    const openRouterInstanceId = ProviderInstanceId.make("claude_openrouter");
+    const openRouterSelection = createModelSelection(openRouterInstanceId, "openai/gpt-5.5");
+    useComposerDraftStore.getState().setModelSelection(THREAD_REF, openRouterSelection);
 
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
-      snapshot: withProjectScripts(createDraftOnlySnapshot(), [
-        {
-          id: "setup",
-          name: "Setup",
-          command: "bun install",
-          icon: "configure",
-          runOnWorktreeCreate: true,
-        },
-      ]),
+      snapshot: createDraftOnlySnapshot(),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          providers: [
+            ...nextFixture.serverConfig.providers,
+            {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              instanceId: ProviderInstanceId.make("claudeAgent"),
+              enabled: true,
+              installed: true,
+              version: "2.1.117",
+              status: "ready",
+              auth: { status: "authenticated" },
+              checkedAt: NOW_ISO,
+              models: [
+                {
+                  slug: "claude-opus-4-7",
+                  name: "Claude Opus 4.7",
+                  isCustom: false,
+                  capabilities: createModelCapabilities({ optionDescriptors: [] }),
+                },
+              ],
+              slashCommands: [],
+              skills: [],
+            },
+            {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              instanceId: openRouterInstanceId,
+              displayName: "Claude OpenRouter",
+              enabled: true,
+              installed: true,
+              version: "2.1.117",
+              status: "ready",
+              auth: { status: "authenticated" },
+              checkedAt: NOW_ISO,
+              models: [
+                {
+                  slug: "claude-opus-4-7",
+                  name: "Claude Opus 4.7",
+                  isCustom: false,
+                  capabilities: createModelCapabilities({ optionDescriptors: [] }),
+                },
+              ],
+              slashCommands: [],
+              skills: [],
+            },
+          ],
+          settings: {
+            ...nextFixture.serverConfig.settings,
+            providerInstances: {
+              ...nextFixture.serverConfig.settings.providerInstances,
+              [openRouterInstanceId]: {
+                driver: ProviderDriverKind.make("claudeAgent"),
+                displayName: "Claude OpenRouter",
+                config: { customModels: ["openai/gpt-5.5"] },
+              },
+            },
+          },
+        };
+      },
       resolveRpc: (body) => {
         if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
-          return dispatchPromise;
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
         }
         return undefined;
       },
     });
 
     try {
-      useComposerDraftStore.getState().setPrompt(THREAD_REF, "Ship it");
+      useComposerDraftStore.getState().setPrompt(THREAD_REF, "Hello there");
       await waitForLayout();
 
       const sendButton = await waitForSendButton();
@@ -2579,77 +2674,122 @@ describe("ChatView timeline estimator parity (full app)", () => {
 
       await vi.waitFor(
         () => {
-          expect(
-            wsRequests.some((request) => request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand),
-          ).toBe(true);
-          expect(document.querySelector('button[aria-label="Sending"]')).toBeTruthy();
-          expect(document.querySelector('button[aria-label="Preparing worktree"]')).toBeNull();
+          const turnStartRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "thread.turn.start",
+          ) as
+            | {
+                modelSelection?: { instanceId?: string; model?: string };
+                bootstrap?: {
+                  createThread?: {
+                    modelSelection?: { instanceId?: string; model?: string };
+                  };
+                };
+              }
+            | undefined;
+
+          expect(turnStartRequest?.modelSelection).toMatchObject({
+            instanceId: openRouterInstanceId,
+            model: "openai/gpt-5.5",
+          });
+          expect(turnStartRequest?.bootstrap?.createThread?.modelSelection).toMatchObject({
+            instanceId: openRouterInstanceId,
+            model: "openai/gpt-5.5",
+          });
         },
         { timeout: 8_000, interval: 16 },
       );
     } finally {
-      resolveDispatch({ sequence: fixture.snapshot.snapshotSequence + 1 });
       await mounted.cleanup();
     }
   });
 
-  it("toggles plan mode with Shift+Tab only while the composer is focused", async () => {
+  it("keeps new-worktree mode on empty server threads and bootstraps the first send", async () => {
+    const snapshot = addThreadToSnapshot(createDraftOnlySnapshot(), THREAD_ID);
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
-      snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-target-hotkey" as MessageId,
-        targetText: "hotkey target",
-      }),
+      snapshot: {
+        ...snapshot,
+        threads: snapshot.threads.map((thread) =>
+          thread.id === THREAD_ID ? Object.assign({}, thread, { session: null }) : thread,
+        ),
+      },
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.vcsListRefs) {
+          return {
+            isRepo: true,
+            hasPrimaryRemote: true,
+            nextCursor: null,
+            totalCount: 1,
+            refs: [
+              {
+                name: "main",
+                current: true,
+                isDefault: true,
+                worktreePath: null,
+              },
+            ],
+          };
+        }
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+        return undefined;
+      },
     });
 
     try {
-      const initialModeButton = await waitForInteractionModeButton("Build");
-      expect(initialModeButton.title).toContain("enter plan mode");
-
-      window.dispatchEvent(
-        new KeyboardEvent("keydown", {
-          key: "Tab",
-          shiftKey: true,
-          bubbles: true,
-          cancelable: true,
-        }),
-      );
-      await waitForLayout();
-
-      expect((await waitForInteractionModeButton("Build")).title).toContain("enter plan mode");
-
-      const composerEditor = await waitForComposerEditor();
-      composerEditor.focus();
-      composerEditor.dispatchEvent(
-        new KeyboardEvent("keydown", {
-          key: "Tab",
-          shiftKey: true,
-          bubbles: true,
-          cancelable: true,
-        }),
-      );
+      (await waitForButtonByText("Current checkout")).click();
+      await page.getByText("New worktree", { exact: true }).click();
 
       await vi.waitFor(
-        async () => {
-          expect((await waitForInteractionModeButton("Plan")).title).toContain(
-            "return to normal build mode",
-          );
+        () => {
+          expect(findButtonByText("New worktree")).toBeTruthy();
         },
         { timeout: 8_000, interval: 16 },
       );
 
-      composerEditor.dispatchEvent(
-        new KeyboardEvent("keydown", {
-          key: "Tab",
-          shiftKey: true,
-          bubbles: true,
-          cancelable: true,
-        }),
-      );
+      useComposerDraftStore.getState().setPrompt(THREAD_REF, "Ship it");
+      await waitForLayout();
+
+      const sendButton = await waitForSendButton();
+      expect(sendButton.disabled).toBe(false);
+      sendButton.click();
 
       await vi.waitFor(
-        async () => {
-          expect((await waitForInteractionModeButton("Build")).title).toContain("enter plan mode");
+        () => {
+          const turnStartRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "thread.turn.start",
+          ) as
+            | {
+                _tag: string;
+                type?: string;
+                bootstrap?: {
+                  createThread?: { projectId?: string };
+                  prepareWorktree?: { projectCwd?: string; baseBranch?: string; branch?: string };
+                  runSetupScript?: boolean;
+                };
+              }
+            | undefined;
+
+          expect(turnStartRequest).toMatchObject({
+            _tag: ORCHESTRATION_WS_METHODS.dispatchCommand,
+            type: "thread.turn.start",
+            bootstrap: {
+              prepareWorktree: {
+                projectCwd: "/repo/project",
+                baseBranch: "main",
+                branch: expect.stringMatching(/^t3code\/[0-9a-f]{8}$/),
+              },
+              runSetupScript: true,
+            },
+          });
+          expect(turnStartRequest?.bootstrap?.createThread).toBeUndefined();
         },
         { timeout: 8_000, interval: 16 },
       );
@@ -2658,55 +2798,24 @@ describe("ChatView timeline estimator parity (full app)", () => {
     }
   });
 
-  it("uses the active draft route session when changing the base branch", async () => {
-    const staleDraftId = draftIdFromPath("/draft/draft-stale-branch-session");
-    const activeDraftId = draftIdFromPath("/draft/draft-active-branch-session");
-
-    useComposerDraftStore.setState({
-      draftThreadsByThreadKey: {
-        [staleDraftId]: {
-          threadId: THREAD_ID,
-          environmentId: LOCAL_ENVIRONMENT_ID,
-          projectId: PROJECT_ID,
-          logicalProjectKey: `${PROJECT_DRAFT_KEY}:stale`,
-          createdAt: NOW_ISO,
-          runtimeMode: "full-access",
-          interactionMode: "default",
-          branch: "main",
-          worktreePath: null,
-          envMode: "worktree",
-        },
-        [activeDraftId]: {
-          threadId: THREAD_ID,
-          environmentId: LOCAL_ENVIRONMENT_ID,
-          projectId: PROJECT_ID,
-          logicalProjectKey: PROJECT_DRAFT_KEY,
-          createdAt: NOW_ISO,
-          runtimeMode: "full-access",
-          interactionMode: "default",
-          branch: "main",
-          worktreePath: null,
-          envMode: "worktree",
-        },
-      },
-      logicalProjectDraftThreadKeyByLogicalProjectKey: {
-        [`${PROJECT_DRAFT_KEY}:stale`]: staleDraftId,
-        [PROJECT_DRAFT_KEY]: activeDraftId,
-      },
-    });
-
+  it("updates the selected worktree base branch on empty server threads", async () => {
+    const snapshot = addThreadToSnapshot(createDraftOnlySnapshot(), THREAD_ID);
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
-      snapshot: createDraftOnlySnapshot(),
-      initialPath: `/draft/${activeDraftId}`,
+      snapshot: {
+        ...snapshot,
+        threads: snapshot.threads.map((thread) =>
+          thread.id === THREAD_ID ? Object.assign({}, thread, { session: null }) : thread,
+        ),
+      },
       resolveRpc: (body) => {
-        if (body._tag === WS_METHODS.gitListBranches) {
+        if (body._tag === WS_METHODS.vcsListRefs) {
           return {
             isRepo: true,
-            hasOriginRemote: true,
+            hasPrimaryRemote: true,
             nextCursor: null,
             totalCount: 2,
-            branches: [
+            refs: [
               {
                 name: "main",
                 current: true,
@@ -2722,190 +2831,648 @@ describe("ChatView timeline estimator parity (full app)", () => {
             ],
           };
         }
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
         return undefined;
       },
     });
 
     try {
-      const branchButton = await waitForElement(
-        () =>
-          Array.from(document.querySelectorAll("button")).find(
-            (button) => button.textContent?.trim() === "From main",
-          ) as HTMLButtonElement | null,
-        'Unable to find branch selector button with "From main".',
-      );
-      branchButton.click();
-
-      const branchOption = await waitForElement(
-        () =>
-          Array.from(document.querySelectorAll("span")).find(
-            (element) => element.textContent?.trim() === "release/next",
-          ) as HTMLSpanElement | null,
-        'Unable to find the "release/next" branch option.',
-      );
-      branchOption.click();
+      (await waitForButtonByText("Current checkout")).click();
+      await page.getByText("New worktree", { exact: true }).click();
+      await page.getByText("From main", { exact: true }).click();
+      await page.getByText("release/next", { exact: true }).click();
 
       await vi.waitFor(
         () => {
-          expect(useComposerDraftStore.getState().getDraftSession(activeDraftId)?.branch).toBe(
-            "release/next",
-          );
-          expect(useComposerDraftStore.getState().getDraftSession(staleDraftId)?.branch).toBe(
-            "main",
-          );
+          expect(findButtonByText("From release/next")).toBeTruthy();
         },
         { timeout: 8_000, interval: 16 },
       );
 
+      useComposerDraftStore.getState().setPrompt(THREAD_REF, "Ship it");
+      await waitForLayout();
+
+      const sendButton = await waitForSendButton();
+      expect(sendButton.disabled).toBe(false);
+      sendButton.click();
+
       await vi.waitFor(
         () => {
-          const updatedButton = Array.from(document.querySelectorAll("button")).find((button) =>
-            button.textContent?.trim().includes("From release/next"),
-          );
-          expect(updatedButton).toBeTruthy();
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-
-  it("surrounds selected plain text and preserves the inner selection for repeated wrapping", async () => {
-    const mounted = await mountChatView({
-      viewport: DEFAULT_VIEWPORT,
-      snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-surround-basic" as MessageId,
-        targetText: "surround basic",
-      }),
-    });
-
-    try {
-      useComposerDraftStore.getState().setPrompt(THREAD_REF, "selected");
-      await waitForComposerText("selected");
-      await setComposerSelectionByTextOffsets({ start: 0, end: "selected".length });
-      await pressComposerKey("(");
-      await waitForComposerText("(selected)");
+          const turnStartRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "thread.turn.start",
+          ) as
+            | {
+                _tag: string;
+                type?: string;
+                bootstrap?: {
+                  prepareWorktree?: { baseBranch?: string };
+                };
+              }
+            | undefined;
 
-      await pressComposerKey("[");
-      await waitForComposerText("([selected])");
+          expect(turnStartRequest?.bootstrap?.prepareWorktree?.baseBranch).toBe("release/next");
+        },
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("leaves collapsed-caret typing unchanged for surround symbols", async () => {
-    useComposerDraftStore.getState().setPrompt(THREAD_REF, "selected");
-
+  it("clears pending worktree overrides when switching empty server threads", async () => {
+    const secondThreadId = "thread-browser-test-second" as ThreadId;
+    const snapshot = addThreadToSnapshot(createDraftOnlySnapshot(), THREAD_ID);
+    const snapshotWithSecondThread = addThreadToSnapshot(snapshot, secondThreadId);
+    const snapshotWithTwoThreads = {
+      ...snapshotWithSecondThread,
+      threads: snapshotWithSecondThread.threads.map((thread) => {
+        if (thread.id === THREAD_ID) {
+          return Object.assign({}, thread, { session: null, title: "Thread alpha" });
+        }
+        if (thread.id === secondThreadId) {
+          return Object.assign({}, thread, { session: null, title: "Thread beta" });
+        }
+        return thread;
+      }),
+    };
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
-      snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-surround-collapsed" as MessageId,
-        targetText: "surround collapsed",
-      }),
+      snapshot: snapshotWithTwoThreads,
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.vcsListRefs) {
+          return {
+            isRepo: true,
+            hasPrimaryRemote: true,
+            nextCursor: null,
+            totalCount: 2,
+            refs: [
+              {
+                name: "main",
+                current: true,
+                isDefault: true,
+                worktreePath: null,
+              },
+              {
+                name: "release/next",
+                current: false,
+                isDefault: false,
+                worktreePath: null,
+              },
+            ],
+          };
+        }
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+        return undefined;
+      },
     });
 
     try {
-      await waitForComposerText("selected");
-      await setComposerSelectionByTextOffsets({
-        start: "selected".length,
-        end: "selected".length,
+      (await waitForButtonByText("Current checkout")).click();
+      await page.getByText("New worktree", { exact: true }).click();
+      await page.getByText("From main", { exact: true }).click();
+      await page.getByText("release/next", { exact: true }).click();
+
+      await vi.waitFor(
+        () => {
+          expect(findButtonByText("From release/next")).toBeTruthy();
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      await mounted.router.navigate({
+        to: "/$environmentId/$threadId",
+        params: {
+          environmentId: LOCAL_ENVIRONMENT_ID,
+          threadId: secondThreadId,
+        },
       });
-      await pressComposerKey("(");
-      await waitForComposerText("selected(");
-    } finally {
-      await mounted.cleanup();
-    }
-  });
 
-  it("supports symmetric and backward-selection surrounds", async () => {
-    useComposerDraftStore.getState().setPrompt(THREAD_REF, "backward");
+      await waitForURL(
+        mounted.router,
+        (path) => path === serverThreadPath(secondThreadId),
+        "Route should switch to the second empty server thread.",
+      );
 
-    const mounted = await mountChatView({
-      viewport: DEFAULT_VIEWPORT,
-      snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-surround-backward" as MessageId,
-        targetText: "surround backward",
-      }),
-    });
+      await vi.waitFor(
+        () => {
+          expect(findButtonByText("Current checkout")).toBeTruthy();
+          expect(findButtonByText("From release/next")).toBeNull();
+        },
+        { timeout: 8_000, interval: 16 },
+      );
 
-    try {
-      await waitForComposerText("backward");
-      await setComposerSelectionByTextOffsets({
-        start: 0,
-        end: "backward".length,
-        direction: "backward",
-      });
-      await pressComposerKey("*");
-      await waitForComposerText("*backward*");
+      (await waitForButtonByText("Current checkout")).click();
+      await page.getByText("New worktree", { exact: true }).click();
+
+      await vi.waitFor(
+        () => {
+          expect(findButtonByText("From main")).toBeTruthy();
+          expect(findButtonByText("From release/next")).toBeNull();
+        },
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("supports option-produced surround symbols like guillemets", async () => {
-    useComposerDraftStore.getState().setPrompt(THREAD_REF, "quoted");
+  it("shows the send state once bootstrap dispatch is in flight", async () => {
+    useTerminalStateStore.setState({
+      terminalStateByThreadKey: {},
+    });
+    useComposerDraftStore.setState({
+      draftThreadsByThreadKey: {
+        [THREAD_KEY]: {
+          threadId: THREAD_ID,
+          environmentId: LOCAL_ENVIRONMENT_ID,
+          projectId: PROJECT_ID,
+          logicalProjectKey: PROJECT_DRAFT_KEY,
+          createdAt: NOW_ISO,
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: "main",
+          worktreePath: null,
+          envMode: "worktree",
+        },
+      },
+      logicalProjectDraftThreadKeyByLogicalProjectKey: {
+        [PROJECT_DRAFT_KEY]: THREAD_KEY,
+      },
+    });
+
+    let resolveDispatch!: (value: { sequence: number }) => void;
+    const dispatchPromise = new Promise<{ sequence: number }>((resolve) => {
+      resolveDispatch = resolve;
+    });
 
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
-      snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-surround-guillemet" as MessageId,
-        targetText: "surround guillemet",
-      }),
+      snapshot: withProjectScripts(createDraftOnlySnapshot(), [
+        {
+          id: "setup",
+          name: "Setup",
+          command: "bun install",
+          icon: "configure",
+          runOnWorktreeCreate: true,
+        },
+      ]),
+      resolveRpc: (body) => {
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return dispatchPromise;
+        }
+        return undefined;
+      },
     });
 
     try {
-      await waitForComposerText("quoted");
-      await setComposerSelectionByTextOffsets({ start: 0, end: "quoted".length });
-      await pressComposerKey("«");
-      await waitForComposerText("«quoted»");
+      useComposerDraftStore.getState().setPrompt(THREAD_REF, "Ship it");
+      await waitForLayout();
+
+      const sendButton = await waitForSendButton();
+      expect(sendButton.disabled).toBe(false);
+      sendButton.click();
+
+      await vi.waitFor(
+        () => {
+          expect(
+            wsRequests.some((request) => request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand),
+          ).toBe(true);
+          expect(document.querySelector('button[aria-label="Sending"]')).toBeTruthy();
+          expect(document.querySelector('button[aria-label="Preparing worktree"]')).toBeNull();
+        },
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
+      resolveDispatch({ sequence: fixture.snapshot.snapshotSequence + 1 });
       await mounted.cleanup();
     }
   });
 
-  it("supports dead-key composition that resolves to another surround symbol without an extra undo step", async () => {
-    useComposerDraftStore.getState().setPrompt(THREAD_REF, "quoted");
-
+  it("toggles plan mode with Shift+Tab only while the composer is focused", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-surround-dead-quote" as MessageId,
-        targetText: "surround dead quote",
+        targetMessageId: "msg-user-target-hotkey" as MessageId,
+        targetText: "hotkey target",
       }),
     });
 
     try {
-      await waitForComposerText("quoted");
-      await setComposerSelectionByTextOffsets({ start: 0, end: "quoted".length });
+      const initialModeButton = await waitForInteractionModeButton("Build");
+      expect(initialModeButton.title).toContain("enter plan mode");
+
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "Tab",
+          shiftKey: true,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+      await waitForLayout();
+
+      expect((await waitForInteractionModeButton("Build")).title).toContain("enter plan mode");
+
       const composerEditor = await waitForComposerEditor();
       composerEditor.focus();
       composerEditor.dispatchEvent(
         new KeyboardEvent("keydown", {
-          key: "Dead",
+          key: "Tab",
+          shiftKey: true,
           bubbles: true,
           cancelable: true,
         }),
       );
+
+      await vi.waitFor(
+        async () => {
+          expect((await waitForInteractionModeButton("Plan")).title).toContain(
+            "return to normal build mode",
+          );
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
       composerEditor.dispatchEvent(
-        new InputEvent("beforeinput", {
-          data: "'",
-          inputType: "insertCompositionText",
+        new KeyboardEvent("keydown", {
+          key: "Tab",
+          shiftKey: true,
           bubbles: true,
           cancelable: true,
         }),
       );
-      const resolvedInputEvent = new InputEvent("beforeinput", {
-        data: "'",
-        inputType: "insertText",
-        bubbles: true,
-        cancelable: true,
-      });
-      composerEditor.dispatchEvent(resolvedInputEvent);
-      expect(resolvedInputEvent.defaultPrevented).toBe(true);
-      await waitForComposerText("'quoted'");
-      await pressComposerUndo();
-      await waitForComposerText("quoted");
+
+      await vi.waitFor(
+        async () => {
+          expect((await waitForInteractionModeButton("Build")).title).toContain("enter plan mode");
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("uses the active draft route session when changing the base branch", async () => {
+    const staleDraftId = draftIdFromPath("/draft/draft-stale-branch-session");
+    const activeDraftId = draftIdFromPath("/draft/draft-active-branch-session");
+
+    useComposerDraftStore.setState({
+      draftThreadsByThreadKey: {
+        [staleDraftId]: {
+          threadId: THREAD_ID,
+          environmentId: LOCAL_ENVIRONMENT_ID,
+          projectId: PROJECT_ID,
+          logicalProjectKey: `${PROJECT_DRAFT_KEY}:stale`,
+          createdAt: NOW_ISO,
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: "main",
+          worktreePath: null,
+          envMode: "worktree",
+        },
+        [activeDraftId]: {
+          threadId: THREAD_ID,
+          environmentId: LOCAL_ENVIRONMENT_ID,
+          projectId: PROJECT_ID,
+          logicalProjectKey: PROJECT_DRAFT_KEY,
+          createdAt: NOW_ISO,
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: "main",
+          worktreePath: null,
+          envMode: "worktree",
+        },
+      },
+      logicalProjectDraftThreadKeyByLogicalProjectKey: {
+        [`${PROJECT_DRAFT_KEY}:stale`]: staleDraftId,
+        [PROJECT_DRAFT_KEY]: activeDraftId,
+      },
+    });
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createDraftOnlySnapshot(),
+      initialPath: `/draft/${activeDraftId}`,
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.vcsListRefs) {
+          return {
+            isRepo: true,
+            hasPrimaryRemote: true,
+            nextCursor: null,
+            totalCount: 2,
+            refs: [
+              {
+                name: "main",
+                current: true,
+                isDefault: true,
+                worktreePath: null,
+              },
+              {
+                name: "release/next",
+                current: false,
+                isDefault: false,
+                worktreePath: null,
+              },
+            ],
+          };
+        }
+        return undefined;
+      },
+    });
+
+    try {
+      const branchButton = await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll("button")).find(
+            (button) => button.textContent?.trim() === "From main",
+          ) as HTMLButtonElement | null,
+        'Unable to find branch selector button with "From main".',
+      );
+      branchButton.click();
+
+      const branchOption = await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll("span")).find(
+            (element) => element.textContent?.trim() === "release/next",
+          ) as HTMLSpanElement | null,
+        'Unable to find the "release/next" branch option.',
+      );
+      branchOption.click();
+
+      await vi.waitFor(
+        () => {
+          expect(useComposerDraftStore.getState().getDraftSession(activeDraftId)?.branch).toBe(
+            "release/next",
+          );
+          expect(useComposerDraftStore.getState().getDraftSession(staleDraftId)?.branch).toBe(
+            "main",
+          );
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      await vi.waitFor(
+        () => {
+          const updatedButton = Array.from(document.querySelectorAll("button")).find((button) =>
+            button.textContent?.trim().includes("From release/next"),
+          );
+          expect(updatedButton).toBeTruthy();
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("keeps the new worktree branch picker anchored at the top when opening with a preselected branch", async () => {
+    const draftId = DraftId.make("draft-branch-picker-scroll-regression");
+    const branches = [
+      {
+        name: "feature/current",
+        current: true,
+        isDefault: false,
+        worktreePath: null,
+      },
+      {
+        name: "main",
+        current: false,
+        isDefault: true,
+        worktreePath: null,
+      },
+      ...Array.from({ length: 48 }, (_, index) => ({
+        name: `feature/${String(index).padStart(2, "0")}`,
+        current: false,
+        isDefault: false,
+        worktreePath: null,
+      })),
+      {
+        name: "feature/selected",
+        current: false,
+        isDefault: false,
+        worktreePath: null,
+      },
+    ];
+
+    useComposerDraftStore.setState({
+      draftThreadsByThreadKey: {
+        [draftId]: {
+          threadId: THREAD_ID,
+          environmentId: LOCAL_ENVIRONMENT_ID,
+          projectId: PROJECT_ID,
+          logicalProjectKey: PROJECT_DRAFT_KEY,
+          createdAt: NOW_ISO,
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: "feature/selected",
+          worktreePath: null,
+          envMode: "worktree",
+        },
+      },
+      logicalProjectDraftThreadKeyByLogicalProjectKey: {
+        [PROJECT_DRAFT_KEY]: draftId,
+      },
+    });
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createDraftOnlySnapshot(),
+      initialPath: `/draft/${draftId}`,
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.vcsListRefs) {
+          return {
+            isRepo: true,
+            hasPrimaryRemote: true,
+            nextCursor: null,
+            totalCount: branches.length,
+            refs: branches,
+          };
+        }
+        return undefined;
+      },
+    });
+
+    try {
+      const branchButton = await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll("button")).find(
+            (button) => button.textContent?.trim() === "From feature/selected",
+          ) as HTMLButtonElement | null,
+        'Unable to find branch selector button with "From feature/selected".',
+      );
+      branchButton.click();
+
+      await waitForElement(
+        () => document.querySelector<HTMLInputElement>('input[placeholder="Search refs..."]'),
+        "Unable to find ref search input.",
+      );
+
+      const popup = await waitForElement(
+        () => document.querySelector<HTMLElement>('[data-slot="combobox-popup"]'),
+        "Unable to find the branch picker popup.",
+      );
+
+      await vi.waitFor(
+        () => {
+          const popupSpans = Array.from(popup.querySelectorAll("span"));
+          expect(
+            popupSpans.some((element) => element.textContent?.trim() === "feature/current"),
+          ).toBe(true);
+          expect(popupSpans.some((element) => element.textContent?.trim() === "main")).toBe(true);
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("surrounds selected plain text and preserves the inner selection for repeated wrapping", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-surround-basic" as MessageId,
+        targetText: "surround basic",
+      }),
+    });
+
+    try {
+      useComposerDraftStore.getState().setPrompt(THREAD_REF, "selected");
+      await waitForComposerText("selected");
+      await setComposerSelectionByTextOffsets({ start: 0, end: "selected".length });
+      await pressComposerKey("(");
+      await waitForComposerText("(selected)");
+
+      await pressComposerKey("[");
+      await waitForComposerText("([selected])");
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("leaves collapsed-caret typing unchanged for surround symbols", async () => {
+    useComposerDraftStore.getState().setPrompt(THREAD_REF, "selected");
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-surround-collapsed" as MessageId,
+        targetText: "surround collapsed",
+      }),
+    });
+
+    try {
+      await waitForComposerText("selected");
+      await setComposerSelectionByTextOffsets({
+        start: "selected".length,
+        end: "selected".length,
+      });
+      await pressComposerKey("(");
+      await waitForComposerText("selected(");
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("supports symmetric and backward-selection surrounds", async () => {
+    useComposerDraftStore.getState().setPrompt(THREAD_REF, "backward");
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-surround-backward" as MessageId,
+        targetText: "surround backward",
+      }),
+    });
+
+    try {
+      await waitForComposerText("backward");
+      await setComposerSelectionByTextOffsets({
+        start: 0,
+        end: "backward".length,
+        direction: "backward",
+      });
+      await pressComposerKey("*");
+      await waitForComposerText("*backward*");
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("supports option-produced surround symbols like guillemets", async () => {
+    useComposerDraftStore.getState().setPrompt(THREAD_REF, "quoted");
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-surround-guillemet" as MessageId,
+        targetText: "surround guillemet",
+      }),
+    });
+
+    try {
+      await waitForComposerText("quoted");
+      await setComposerSelectionByTextOffsets({ start: 0, end: "quoted".length });
+      await pressComposerKey("«");
+      await waitForComposerText("«quoted»");
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("supports dead-key composition that resolves to another surround symbol without an extra undo step", async () => {
+    useComposerDraftStore.getState().setPrompt(THREAD_REF, "quoted");
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-surround-dead-quote" as MessageId,
+        targetText: "surround dead quote",
+      }),
+    });
+
+    try {
+      await waitForComposerText("quoted");
+      await setComposerSelectionByTextOffsets({ start: 0, end: "quoted".length });
+      const composerEditor = await waitForComposerEditor();
+      composerEditor.focus();
+      composerEditor.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "Dead",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+      composerEditor.dispatchEvent(
+        new InputEvent("beforeinput", {
+          data: "'",
+          inputType: "insertCompositionText",
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+      const resolvedInputEvent = new InputEvent("beforeinput", {
+        data: "'",
+        inputType: "insertText",
+        bubbles: true,
+        cancelable: true,
+      });
+      composerEditor.dispatchEvent(resolvedInputEvent);
+      expect(resolvedInputEvent.defaultPrevented).toBe(true);
+      await waitForComposerText("'quoted'");
+      await pressComposerUndo();
+      await waitForComposerText("quoted");
     } finally {
       await mounted.cleanup();
     }
@@ -2917,808 +3484,1734 @@ describe("ChatView timeline estimator parity (full app)", () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-surround-after-mention" as MessageId,
-        targetText: "surround after mention",
+        targetMessageId: "msg-user-surround-after-mention" as MessageId,
+        targetText: "surround after mention",
+      }),
+    });
+
+    try {
+      await vi.waitFor(
+        () => {
+          expect(document.body.textContent).toContain("package.json");
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+      await waitForComposerText("hi @package.json there");
+      await setComposerSelectionByTextOffsets({
+        start: "hi package.json ".length,
+        end: "hi package.json there".length,
+      });
+      await pressComposerKey("(");
+      await waitForComposerText("hi @package.json (there)");
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("falls back to normal replacement when the selection includes a mention token", async () => {
+    useComposerDraftStore.getState().setPrompt(THREAD_REF, "hi @package.json there ");
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-surround-token" as MessageId,
+        targetText: "surround token",
+      }),
+    });
+
+    try {
+      await vi.waitFor(
+        () => {
+          expect(document.body.textContent).toContain("package.json");
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+      await selectAllComposerContent();
+      await pressComposerKey("(");
+      await waitForComposerText("(");
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("shows runtime mode descriptions in the desktop composer access select", async () => {
+    setDraftThreadWithoutWorktree();
+
+    const mounted = await mountChatView({
+      viewport: WIDE_FOOTER_VIEWPORT,
+      snapshot: createDraftOnlySnapshot(),
+    });
+
+    try {
+      const runtimeModeSelect = await waitForButtonByText("Full access");
+      runtimeModeSelect.click();
+
+      expect((await waitForSelectItemContainingText("Supervised")).textContent).toContain(
+        "Ask before commands and file changes",
+      );
+
+      const autoAcceptItem = await waitForSelectItemContainingText("Auto-accept edits");
+      expect(autoAcceptItem.textContent).toContain("Auto-approve edits");
+      expect((await waitForSelectItemContainingText("Full access")).textContent).toContain(
+        "Allow commands and edits without prompts",
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("keeps removed terminal context pills removed when a new one is added", async () => {
+    const removedLabel = "Terminal 1 lines 1-2";
+    const addedLabel = "Terminal 2 lines 9-10";
+    useComposerDraftStore.getState().addTerminalContext(
+      THREAD_REF,
+      createTerminalContext({
+        id: "ctx-removed",
+        terminalLabel: "Terminal 1",
+        lineStart: 1,
+        lineEnd: 2,
+        text: "bun i\nno changes",
+      }),
+    );
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-terminal-pill-backspace" as MessageId,
+        targetText: "terminal pill backspace target",
+      }),
+    });
+
+    try {
+      await vi.waitFor(
+        () => {
+          expect(document.body.textContent).toContain(removedLabel);
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      const store = useComposerDraftStore.getState();
+      const currentPrompt = store.draftsByThreadKey[THREAD_KEY]?.prompt ?? "";
+      const nextPrompt = removeInlineTerminalContextPlaceholder(currentPrompt, 0);
+      store.setPrompt(THREAD_REF, nextPrompt.prompt);
+      store.removeTerminalContext(THREAD_REF, "ctx-removed");
+
+      await vi.waitFor(
+        () => {
+          expect(useComposerDraftStore.getState().draftsByThreadKey[THREAD_KEY]).toBeUndefined();
+          expect(document.body.textContent).not.toContain(removedLabel);
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      useComposerDraftStore.getState().addTerminalContext(
+        THREAD_REF,
+        createTerminalContext({
+          id: "ctx-added",
+          terminalLabel: "Terminal 2",
+          lineStart: 9,
+          lineEnd: 10,
+          text: "git status\nOn branch main",
+        }),
+      );
+
+      await vi.waitFor(
+        () => {
+          const draft = useComposerDraftStore.getState().draftsByThreadKey[THREAD_KEY];
+          expect(draft?.terminalContexts.map((context) => context.id)).toEqual(["ctx-added"]);
+          expect(document.body.textContent).toContain(addedLabel);
+          expect(document.body.textContent).not.toContain(removedLabel);
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("disables send when the composer only contains an expired terminal pill", async () => {
+    const expiredLabel = "Terminal 1 line 4";
+    useComposerDraftStore.getState().addTerminalContext(
+      THREAD_REF,
+      createTerminalContext({
+        id: "ctx-expired-only",
+        terminalLabel: "Terminal 1",
+        lineStart: 4,
+        lineEnd: 4,
+        text: "",
+      }),
+    );
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-expired-pill-disabled" as MessageId,
+        targetText: "expired pill disabled target",
+      }),
+    });
+
+    try {
+      await vi.waitFor(
+        () => {
+          expect(document.body.textContent).toContain(expiredLabel);
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      const sendButton = await waitForSendButton();
+      expect(sendButton.disabled).toBe(true);
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("warns when sending text while omitting expired terminal pills", async () => {
+    const expiredLabel = "Terminal 1 line 4";
+    useComposerDraftStore.getState().addTerminalContext(
+      THREAD_REF,
+      createTerminalContext({
+        id: "ctx-expired-send-warning",
+        terminalLabel: "Terminal 1",
+        lineStart: 4,
+        lineEnd: 4,
+        text: "",
+      }),
+    );
+    useComposerDraftStore
+      .getState()
+      .setPrompt(THREAD_REF, `yoo${INLINE_TERMINAL_CONTEXT_PLACEHOLDER}waddup`);
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-expired-pill-warning" as MessageId,
+        targetText: "expired pill warning target",
+      }),
+    });
+
+    try {
+      await vi.waitFor(
+        () => {
+          expect(document.body.textContent).toContain(expiredLabel);
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      const sendButton = await waitForSendButton();
+      expect(sendButton.disabled).toBe(false);
+      sendButton.click();
+
+      await vi.waitFor(
+        () => {
+          expect(document.body.textContent).toContain(
+            "Expired terminal context omitted from message",
+          );
+          expect(document.body.textContent).not.toContain(expiredLabel);
+          expect(document.body.textContent).toContain("yoowaddup");
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("shows a pointer cursor for the running stop button", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-stop-button-cursor" as MessageId,
+        targetText: "stop button cursor target",
+        sessionStatus: "running",
+      }),
+    });
+
+    try {
+      const stopButton = await waitForElement(
+        () => document.querySelector<HTMLButtonElement>('button[aria-label="Stop generation"]'),
+        "Unable to find stop generation button.",
+      );
+
+      expect(getComputedStyle(stopButton).cursor).toBe("pointer");
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("hides the archive action when the pointer leaves a thread row", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-archive-hover-test" as MessageId,
+        targetText: "archive hover target",
+      }),
+    });
+
+    try {
+      const threadRow = page.getByTestId(`thread-row-${THREAD_ID}`);
+
+      await expect.element(threadRow).toBeInTheDocument();
+      const archiveButton = await waitForElement(
+        () =>
+          document.querySelector<HTMLButtonElement>(`[data-testid="thread-archive-${THREAD_ID}"]`),
+        "Unable to find archive button.",
+      );
+      const archiveAction = archiveButton.parentElement;
+      expect(
+        archiveAction,
+        "Archive button should render inside a visibility wrapper.",
+      ).not.toBeNull();
+      expect(getComputedStyle(archiveAction!).opacity).toBe("0");
+
+      await threadRow.hover();
+      await vi.waitFor(
+        () => {
+          expect(getComputedStyle(archiveAction!).opacity).toBe("1");
+        },
+        { timeout: 4_000, interval: 16 },
+      );
+
+      await page.getByTestId("composer-editor").hover();
+      await vi.waitFor(
+        () => {
+          expect(getComputedStyle(archiveAction!).opacity).toBe("0");
+        },
+        { timeout: 4_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("exposes the full thread title on the sidebar row tooltip", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-thread-tooltip-target" as MessageId,
+        targetText: "thread tooltip target",
+      }),
+    });
+
+    try {
+      const threadTitle = page.getByTestId(`thread-title-${THREAD_ID}`);
+
+      await expect.element(threadTitle).toBeInTheDocument();
+      await threadTitle.hover();
+
+      await vi.waitFor(
+        () => {
+          const tooltip = document.querySelector<HTMLElement>('[data-slot="tooltip-popup"]');
+          expect(tooltip).not.toBeNull();
+          expect(tooltip?.textContent).toContain(THREAD_TITLE);
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("shows the confirm archive action after clicking the archive button", async () => {
+    localStorage.setItem(
+      "t3code:client-settings:v1",
+      JSON.stringify({
+        ...DEFAULT_CLIENT_SETTINGS,
+        confirmThreadArchive: true,
+      }),
+    );
+
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-archive-confirm-test" as MessageId,
+        targetText: "archive confirm target",
+      }),
+    });
+
+    try {
+      const threadRow = page.getByTestId(`thread-row-${THREAD_ID}`);
+
+      await expect.element(threadRow).toBeInTheDocument();
+      await threadRow.hover();
+
+      const archiveButton = page.getByTestId(`thread-archive-${THREAD_ID}`);
+      await expect.element(archiveButton).toBeInTheDocument();
+      await archiveButton.click();
+
+      const confirmButton = page.getByTestId(`thread-archive-confirm-${THREAD_ID}`);
+      await expect.element(confirmButton).toBeInTheDocument();
+      await expect.element(confirmButton).toBeVisible();
+    } finally {
+      localStorage.removeItem("t3code:client-settings:v1");
+      await mounted.cleanup();
+    }
+  });
+
+  it("canonicalizes promoted draft threads to the server thread route", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-new-thread-test" as MessageId,
+        targetText: "new thread selection test",
+      }),
+    });
+
+    try {
+      // Wait for the sidebar to render with the project.
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
+
+      await newThreadButton.click();
+
+      // The route should change to a new draft thread ID.
+      const newThreadPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread UUID.",
+      );
+      const newDraftId = draftIdFromPath(newThreadPath);
+      const newThreadId = draftThreadIdFor(newDraftId);
+
+      // The composer editor should be present for the new draft thread.
+      await waitForComposerEditor();
+
+      // `thread.created` should only mark the draft as promoting; it should
+      // not navigate away until the server thread has actual runtime state.
+      await materializePromotedDraftThreadViaDomainEvent(newThreadId);
+      expect(mounted.router.state.location.pathname).toBe(newThreadPath);
+      await expect.element(page.getByTestId("composer-editor")).toBeInTheDocument();
+
+      // Once the server thread starts, the route should canonicalize.
+      await startPromotedServerThreadViaDomainEvent(newThreadId);
+      await vi.waitFor(
+        () => {
+          expect(useComposerDraftStore.getState().draftThreadsByThreadKey[newDraftId]).toBe(
+            undefined,
+          );
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      // The route should switch to the canonical server thread path.
+      await waitForURL(
+        mounted.router,
+        (path) => path === serverThreadPath(newThreadId),
+        "Promoted drafts should canonicalize to the server thread route.",
+      );
+
+      // The composer should remain usable after canonicalization, regardless of
+      // whether the promoted thread is still visibly empty or has already
+      // entered the running state.
+      await expect.element(page.getByTestId("composer-editor")).toBeInTheDocument();
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("canonicalizes stale promoted draft routes to the server thread route", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-draft-hydration-race-test" as MessageId,
+        targetText: "draft hydration race test",
+      }),
+    });
+
+    try {
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
+
+      await newThreadButton.click();
+
+      const newThreadPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread UUID.",
+      );
+      const newDraftId = draftIdFromPath(newThreadPath);
+      const newThreadId = draftThreadIdFor(newDraftId);
+
+      await promoteDraftThreadViaDomainEvent(newThreadId);
+
+      await mounted.router.navigate({
+        to: "/draft/$draftId",
+        params: { draftId: newDraftId },
+      });
+
+      await waitForURL(
+        mounted.router,
+        (path) => path === serverThreadPath(newThreadId),
+        "Stale promoted draft routes should canonicalize to the server thread path.",
+      );
+
+      await expect.element(page.getByTestId("composer-editor")).toBeInTheDocument();
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("creates a fresh worktree draft from an existing worktree thread when the default mode is worktree", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: {
+        ...createSnapshotForTargetUser({
+          targetMessageId: "msg-user-new-thread-worktree-default-test" as MessageId,
+          targetText: "new thread worktree default test",
+        }),
+        threads: createSnapshotForTargetUser({
+          targetMessageId: "msg-user-new-thread-worktree-default-test" as MessageId,
+          targetText: "new thread worktree default test",
+        }).threads.map((thread) =>
+          thread.id === THREAD_ID
+            ? Object.assign({}, thread, {
+                branch: "feature/existing",
+                worktreePath: "/repo/.t3/worktrees/existing",
+              })
+            : thread,
+        ),
+      },
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          settings: {
+            ...nextFixture.serverConfig.settings,
+            defaultThreadEnvMode: "worktree",
+          },
+        };
+      },
+    });
+
+    try {
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
+
+      await newThreadButton.click();
+
+      const newThreadPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should change to a new draft thread.",
+      );
+      const newDraftId = draftIdFromPath(newThreadPath);
+
+      expect(useComposerDraftStore.getState().getDraftSession(newDraftId)).toMatchObject({
+        envMode: "worktree",
+        worktreePath: null,
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("creates a new draft instead of reusing a promoting draft thread", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-promoting-draft-new-thread-test" as MessageId,
+        targetText: "promoting draft new thread test",
       }),
     });
 
     try {
-      await vi.waitFor(
-        () => {
-          expect(document.body.textContent).toContain("package.json");
-        },
-        { timeout: 8_000, interval: 16 },
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
+
+      await newThreadButton.click();
+
+      const firstDraftPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should change to the first draft thread.",
       );
-      await waitForComposerText("hi @package.json there");
-      await setComposerSelectionByTextOffsets({
-        start: "hi package.json ".length,
-        end: "hi package.json there".length,
-      });
-      await pressComposerKey("(");
-      await waitForComposerText("hi @package.json (there)");
+      const firstDraftId = draftIdFromPath(firstDraftPath);
+      const firstThreadId = draftThreadIdFor(firstDraftId);
+
+      await materializePromotedDraftThreadViaDomainEvent(firstThreadId);
+      expect(mounted.router.state.location.pathname).toBe(firstDraftPath);
+
+      await newThreadButton.click();
+
+      const secondDraftPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path) && path !== firstDraftPath,
+        "Route should change to a second draft thread instead of reusing the promoting draft.",
+      );
+      expect(draftIdFromPath(secondDraftPath)).not.toBe(firstDraftId);
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("falls back to normal replacement when the selection includes a mention token", async () => {
-    useComposerDraftStore.getState().setPrompt(THREAD_REF, "hi @package.json there ");
+  it("snapshots sticky codex settings into a new draft thread", async () => {
+    useComposerDraftStore.setState({
+      stickyModelSelectionByProvider: {
+        [ProviderInstanceId.make("codex")]: createModelSelection(
+          ProviderInstanceId.make("codex"),
+          "gpt-5.3-codex",
+          [
+            { id: "reasoningEffort", value: "medium" },
+            { id: "fastMode", value: true },
+          ],
+        ),
+      },
+      stickyActiveProvider: ProviderInstanceId.make("codex"),
+    });
 
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-surround-token" as MessageId,
-        targetText: "surround token",
+        targetMessageId: "msg-user-sticky-codex-traits-test" as MessageId,
+        targetText: "sticky codex traits test",
       }),
     });
 
     try {
-      await vi.waitFor(
-        () => {
-          expect(document.body.textContent).toContain("package.json");
-        },
-        { timeout: 8_000, interval: 16 },
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
+
+      await newThreadButton.click();
+
+      const newThreadPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread UUID.",
       );
-      await selectAllComposerContent();
-      await pressComposerKey("(");
-      await waitForComposerText("(");
+      const newDraftId = draftIdFromPath(newThreadPath);
+
+      // `toMatchObject` matches objects loosely (extras ignored) but compares
+      // arrays strictly, so wrap `options` in `arrayContaining` to keep the
+      // assertion focused on sticky `fastMode` carrying over without asserting
+      // on exactly which other options are preserved.
+      expect(composerDraftFor(newDraftId)).toMatchObject({
+        modelSelectionByProvider: {
+          codex: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: "gpt-5.3-codex",
+            options: expect.arrayContaining([{ id: "fastMode", value: true }]),
+          },
+        },
+        activeProvider: "codex",
+      });
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("shows runtime mode descriptions in the desktop composer access select", async () => {
-    setDraftThreadWithoutWorktree();
+  it("hydrates the provider alongside a sticky claude model", async () => {
+    useComposerDraftStore.setState({
+      stickyModelSelectionByProvider: {
+        [ProviderInstanceId.make("claudeAgent")]: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [
+            { id: "effort", value: "max" },
+            { id: "fastMode", value: true },
+          ],
+        ),
+      },
+      stickyActiveProvider: ProviderInstanceId.make("claudeAgent"),
+    });
 
     const mounted = await mountChatView({
-      viewport: WIDE_FOOTER_VIEWPORT,
-      snapshot: createDraftOnlySnapshot(),
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-sticky-claude-model-test" as MessageId,
+        targetText: "sticky claude model test",
+      }),
     });
 
     try {
-      const runtimeModeSelect = await waitForButtonByText("Full access");
-      runtimeModeSelect.click();
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
 
-      expect((await waitForSelectItemContainingText("Supervised")).textContent).toContain(
-        "Ask before commands and file changes",
-      );
+      await newThreadButton.click();
 
-      const autoAcceptItem = await waitForSelectItemContainingText("Auto-accept edits");
-      expect(autoAcceptItem.textContent).toContain("Auto-approve edits");
-      expect((await waitForSelectItemContainingText("Full access")).textContent).toContain(
-        "Allow commands and edits without prompts",
+      const newThreadPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new sticky claude draft thread UUID.",
       );
+      const newDraftId = draftIdFromPath(newThreadPath);
+
+      expect(composerDraftFor(newDraftId)).toMatchObject({
+        modelSelectionByProvider: {
+          claudeAgent: createModelSelection(
+            ProviderInstanceId.make("claudeAgent"),
+            "claude-opus-4-6",
+            [
+              { id: "effort", value: "max" },
+              { id: "fastMode", value: true },
+            ],
+          ),
+        },
+        activeProvider: "claudeAgent",
+      });
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("keeps removed terminal context pills removed when a new one is added", async () => {
-    const removedLabel = "Terminal 1 lines 1-2";
-    const addedLabel = "Terminal 2 lines 9-10";
-    useComposerDraftStore.getState().addTerminalContext(
-      THREAD_REF,
-      createTerminalContext({
-        id: "ctx-removed",
-        terminalLabel: "Terminal 1",
-        lineStart: 1,
-        lineEnd: 2,
-        text: "bun i\nno changes",
-      }),
-    );
-
+  it("falls back to defaults when no sticky composer settings exist", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-terminal-pill-backspace" as MessageId,
-        targetText: "terminal pill backspace target",
+        targetMessageId: "msg-user-default-codex-traits-test" as MessageId,
+        targetText: "default codex traits test",
       }),
     });
 
     try {
-      await vi.waitFor(
-        () => {
-          expect(document.body.textContent).toContain(removedLabel);
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-
-      const store = useComposerDraftStore.getState();
-      const currentPrompt = store.draftsByThreadKey[THREAD_KEY]?.prompt ?? "";
-      const nextPrompt = removeInlineTerminalContextPlaceholder(currentPrompt, 0);
-      store.setPrompt(THREAD_REF, nextPrompt.prompt);
-      store.removeTerminalContext(THREAD_REF, "ctx-removed");
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
 
-      await vi.waitFor(
-        () => {
-          expect(useComposerDraftStore.getState().draftsByThreadKey[THREAD_KEY]).toBeUndefined();
-          expect(document.body.textContent).not.toContain(removedLabel);
-        },
-        { timeout: 8_000, interval: 16 },
-      );
+      await newThreadButton.click();
 
-      useComposerDraftStore.getState().addTerminalContext(
-        THREAD_REF,
-        createTerminalContext({
-          id: "ctx-added",
-          terminalLabel: "Terminal 2",
-          lineStart: 9,
-          lineEnd: 10,
-          text: "git status\nOn branch main",
-        }),
+      const newThreadPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread UUID.",
       );
+      const newDraftId = draftIdFromPath(newThreadPath);
 
-      await vi.waitFor(
-        () => {
-          const draft = useComposerDraftStore.getState().draftsByThreadKey[THREAD_KEY];
-          expect(draft?.terminalContexts.map((context) => context.id)).toEqual(["ctx-added"]);
-          expect(document.body.textContent).toContain(addedLabel);
-          expect(document.body.textContent).not.toContain(removedLabel);
-        },
-        { timeout: 8_000, interval: 16 },
-      );
+      expect(composerDraftFor(newDraftId)).toBe(undefined);
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("disables send when the composer only contains an expired terminal pill", async () => {
-    const expiredLabel = "Terminal 1 line 4";
-    useComposerDraftStore.getState().addTerminalContext(
-      THREAD_REF,
-      createTerminalContext({
-        id: "ctx-expired-only",
-        terminalLabel: "Terminal 1",
-        lineStart: 4,
-        lineEnd: 4,
-        text: "",
-      }),
-    );
+  it("prefers draft state over sticky composer settings and defaults", async () => {
+    useComposerDraftStore.setState({
+      stickyModelSelectionByProvider: {
+        [ProviderInstanceId.make("codex")]: createModelSelection(
+          ProviderInstanceId.make("codex"),
+          "gpt-5.3-codex",
+          [
+            { id: "reasoningEffort", value: "medium" },
+            { id: "fastMode", value: true },
+          ],
+        ),
+      },
+      stickyActiveProvider: ProviderInstanceId.make("codex"),
+    });
 
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-expired-pill-disabled" as MessageId,
-        targetText: "expired pill disabled target",
+        targetMessageId: "msg-user-draft-codex-traits-precedence-test" as MessageId,
+        targetText: "draft codex traits precedence test",
       }),
     });
 
     try {
-      await vi.waitFor(
-        () => {
-          expect(document.body.textContent).toContain(expiredLabel);
+      const newThreadButton = page.getByTestId("new-thread-button");
+      await expect.element(newThreadButton).toBeInTheDocument();
+
+      await newThreadButton.click();
+
+      const threadPath = await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a sticky draft thread UUID.",
+      );
+      const draftId = draftIdFromPath(threadPath);
+
+      // See the note on the sibling sticky-codex test: arrays match strictly
+      // under `toMatchObject`, so use `arrayContaining` to keep the assertion
+      // scoped to the sticky trait (`fastMode`) that must carry over.
+      expect(composerDraftFor(draftId)).toMatchObject({
+        modelSelectionByProvider: {
+          codex: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: "gpt-5.3-codex",
+            options: expect.arrayContaining([{ id: "fastMode", value: true }]),
+          },
         },
-        { timeout: 8_000, interval: 16 },
+        activeProvider: "codex",
+      });
+
+      useComposerDraftStore.getState().setModelSelection(
+        draftId,
+        createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+          { id: "reasoningEffort", value: "low" },
+          { id: "fastMode", value: true },
+        ]),
+      );
+
+      await newThreadButton.click();
+
+      await waitForURL(
+        mounted.router,
+        (path) => path === threadPath,
+        "New-thread should reuse the existing project draft thread.",
       );
-
-      const sendButton = await waitForSendButton();
-      expect(sendButton.disabled).toBe(true);
+      expect(composerDraftFor(draftId)).toMatchObject({
+        modelSelectionByProvider: {
+          codex: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+            { id: "reasoningEffort", value: "low" },
+            { id: "fastMode", value: true },
+          ]),
+        },
+        activeProvider: "codex",
+      });
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("warns when sending text while omitting expired terminal pills", async () => {
-    const expiredLabel = "Terminal 1 line 4";
-    useComposerDraftStore.getState().addTerminalContext(
-      THREAD_REF,
-      createTerminalContext({
-        id: "ctx-expired-send-warning",
-        terminalLabel: "Terminal 1",
-        lineStart: 4,
-        lineEnd: 4,
-        text: "",
-      }),
-    );
-    useComposerDraftStore
-      .getState()
-      .setPrompt(THREAD_REF, `yoo${INLINE_TERMINAL_CONTEXT_PLACEHOLDER}waddup`);
-
+  it("creates a new thread from the global chat.new shortcut", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-expired-pill-warning" as MessageId,
-        targetText: "expired pill warning target",
+        targetMessageId: "msg-user-chat-shortcut-test" as MessageId,
+        targetText: "chat shortcut test",
       }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          keybindings: [
+            {
+              command: "chat.new",
+              shortcut: {
+                key: "o",
+                metaKey: false,
+                ctrlKey: false,
+                shiftKey: true,
+                altKey: false,
+                modKey: true,
+              },
+              whenAst: {
+                type: "not",
+                node: { type: "identifier", name: "terminalFocus" },
+              },
+            },
+            {
+              command: "thread.jump.1",
+              shortcut: {
+                key: "1",
+                metaKey: true,
+                ctrlKey: false,
+                shiftKey: false,
+                altKey: false,
+                modKey: false,
+              },
+            },
+            {
+              command: "modelPicker.jump.1",
+              shortcut: {
+                key: "1",
+                metaKey: true,
+                ctrlKey: false,
+                shiftKey: false,
+                altKey: false,
+                modKey: false,
+              },
+              whenAst: { type: "identifier", name: "modelPickerOpen" },
+            },
+          ],
+        };
+      },
     });
 
     try {
-      await vi.waitFor(
-        () => {
-          expect(document.body.textContent).toContain(expiredLabel);
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-
-      const sendButton = await waitForSendButton();
-      expect(sendButton.disabled).toBe(false);
-      sendButton.click();
-
-      await vi.waitFor(
-        () => {
-          expect(document.body.textContent).toContain(
-            "Expired terminal context omitted from message",
-          );
-          expect(document.body.textContent).not.toContain(expiredLabel);
-          expect(document.body.textContent).toContain("yoowaddup");
-        },
-        { timeout: 8_000, interval: 16 },
+      await waitForNewThreadShortcutLabel();
+      await waitForServerConfigToApply();
+      const composerEditor = await waitForComposerEditor();
+      composerEditor.focus();
+      await waitForLayout();
+      await triggerChatNewShortcutUntilPath(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread UUID from the shortcut.",
       );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("shows a pointer cursor for the running stop button", async () => {
+  it("does not consume chat.new when there is no project context", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
-      snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-stop-button-cursor" as MessageId,
-        targetText: "stop button cursor target",
-        sessionStatus: "running",
-      }),
+      snapshot: createProjectlessSnapshot(),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          keybindings: [
+            {
+              command: "chat.new",
+              shortcut: {
+                key: "o",
+                metaKey: false,
+                ctrlKey: false,
+                shiftKey: true,
+                altKey: false,
+                modKey: true,
+              },
+              whenAst: {
+                type: "not",
+                node: { type: "identifier", name: "terminalFocus" },
+              },
+            },
+          ],
+        };
+      },
     });
 
     try {
-      const stopButton = await waitForElement(
-        () => document.querySelector<HTMLButtonElement>('button[aria-label="Stop generation"]'),
-        "Unable to find stop generation button.",
-      );
+      await waitForServerConfigToApply();
+      dispatchChatNewShortcut();
+      await waitForLayout();
 
-      expect(getComputedStyle(stopButton).cursor).toBe("pointer");
+      expect(mounted.router.state.location.pathname).toBe(serverThreadPath(THREAD_ID));
+      expect(Object.keys(useComposerDraftStore.getState().draftThreadsByThreadKey)).toHaveLength(0);
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("hides the archive action when the pointer leaves a thread row", async () => {
+  it("renders the configurable shortcut and runs a command from the sidebar trigger", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-archive-hover-test" as MessageId,
-        targetText: "archive hover target",
+        targetMessageId: "msg-user-command-palette-shortcut-test" as MessageId,
+        targetText: "command palette shortcut test",
       }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          keybindings: [
+            {
+              command: "commandPalette.toggle",
+              shortcut: {
+                key: "k",
+                metaKey: false,
+                ctrlKey: false,
+                shiftKey: false,
+                altKey: false,
+                modKey: true,
+              },
+              whenAst: {
+                type: "not",
+                node: { type: "identifier", name: "terminalFocus" },
+              },
+            },
+          ],
+        };
+      },
     });
 
     try {
-      const threadRow = page.getByTestId(`thread-row-${THREAD_ID}`);
-
-      await expect.element(threadRow).toBeInTheDocument();
-      const archiveButton = await waitForElement(
-        () =>
-          document.querySelector<HTMLButtonElement>(`[data-testid="thread-archive-${THREAD_ID}"]`),
-        "Unable to find archive button.",
-      );
-      const archiveAction = archiveButton.parentElement;
-      expect(
-        archiveAction,
-        "Archive button should render inside a visibility wrapper.",
-      ).not.toBeNull();
-      expect(getComputedStyle(archiveAction!).opacity).toBe("0");
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
+      const palette = page.getByTestId("command-palette");
+      await openCommandPaletteFromTrigger();
 
-      await threadRow.hover();
-      await vi.waitFor(
-        () => {
-          expect(getComputedStyle(archiveAction!).opacity).toBe("1");
-        },
-        { timeout: 4_000, interval: 16 },
-      );
+      await expect.element(palette).toBeInTheDocument();
+      await expect
+        .element(palette.getByText("New thread in Project", { exact: true }))
+        .toBeInTheDocument();
+      await palette.getByText("New thread in Project", { exact: true }).click();
 
-      await page.getByTestId("composer-editor").hover();
-      await vi.waitFor(
-        () => {
-          expect(getComputedStyle(archiveAction!).opacity).toBe("0");
-        },
-        { timeout: 4_000, interval: 16 },
+      await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread UUID from the command palette.",
       );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("shows the confirm archive action after clicking the archive button", async () => {
-    localStorage.setItem(
-      "t3code:client-settings:v1",
-      JSON.stringify({
-        ...DEFAULT_CLIENT_SETTINGS,
-        confirmThreadArchive: true,
-      }),
-    );
-
+  it("filters command palette results as the user types", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-archive-confirm-test" as MessageId,
-        targetText: "archive confirm target",
+        targetMessageId: "msg-user-command-palette-search-test" as MessageId,
+        targetText: "command palette search test",
       }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          keybindings: [
+            {
+              command: "commandPalette.toggle",
+              shortcut: {
+                key: "k",
+                metaKey: false,
+                ctrlKey: false,
+                shiftKey: false,
+                altKey: false,
+                modKey: true,
+              },
+              whenAst: {
+                type: "not",
+                node: { type: "identifier", name: "terminalFocus" },
+              },
+            },
+          ],
+        };
+      },
     });
 
     try {
-      const threadRow = page.getByTestId(`thread-row-${THREAD_ID}`);
-
-      await expect.element(threadRow).toBeInTheDocument();
-      await threadRow.hover();
-
-      const archiveButton = page.getByTestId(`thread-archive-${THREAD_ID}`);
-      await expect.element(archiveButton).toBeInTheDocument();
-      await archiveButton.click();
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
+      const palette = page.getByTestId("command-palette");
+      await openCommandPaletteFromTrigger();
 
-      const confirmButton = page.getByTestId(`thread-archive-confirm-${THREAD_ID}`);
-      await expect.element(confirmButton).toBeInTheDocument();
-      await expect.element(confirmButton).toBeVisible();
+      await expect.element(palette).toBeInTheDocument();
+      await page.getByPlaceholder("Search commands, projects, and threads...").fill("settings");
+      await expect.element(palette.getByText("Open settings", { exact: true })).toBeInTheDocument();
+      await expect
+        .element(palette.getByText("New thread in Project", { exact: true }))
+        .not.toBeInTheDocument();
     } finally {
-      localStorage.removeItem("t3code:client-settings:v1");
       await mounted.cleanup();
     }
   });
 
-  it("canonicalizes promoted draft threads to the server thread route", async () => {
+  it("adds a project from browse mode with Enter when no directory is highlighted", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-new-thread-test" as MessageId,
-        targetText: "new thread selection test",
+        targetMessageId: "msg-user-command-palette-add-project-enter" as MessageId,
+        targetText: "command palette add project enter",
       }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          keybindings: [
+            {
+              command: "commandPalette.toggle",
+              shortcut: {
+                key: "k",
+                metaKey: false,
+                ctrlKey: false,
+                shiftKey: false,
+                altKey: false,
+                modKey: true,
+              },
+              whenAst: {
+                type: "not",
+                node: { type: "identifier", name: "terminalFocus" },
+              },
+            },
+          ],
+        };
+      },
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          if (body.partialPath === "~/Development/") {
+            return {
+              parentPath: "~/Development/",
+              entries: [
+                { name: "alpha", fullPath: "~/Development/alpha" },
+                { name: "beta", fullPath: "~/Development/beta" },
+              ],
+            };
+          }
+
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Development", fullPath: "~/Development" }],
+          };
+        }
+
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+
+        return undefined;
+      },
     });
 
     try {
-      // Wait for the sidebar to render with the project.
-      const newThreadButton = page.getByTestId("new-thread-button");
-      await expect.element(newThreadButton).toBeInTheDocument();
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
+      const palette = page.getByTestId("command-palette");
+      await openCommandPaletteFromTrigger();
 
-      await newThreadButton.click();
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Add project", { exact: true }).click();
+      await palette.getByText("Local folder", { exact: true }).click();
 
-      // The route should change to a new draft thread ID.
-      const newThreadPath = await waitForURL(
-        mounted.router,
-        (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a new draft thread UUID.",
-      );
-      const newDraftId = draftIdFromPath(newThreadPath);
-      const newThreadId = draftThreadIdFor(newDraftId);
+      const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await page.getByPlaceholder(ADD_PROJECT_SUBMENU_PLACEHOLDER).fill("~/Development/");
+      await expect.element(palette.getByText("alpha", { exact: true })).toBeInTheDocument();
 
-      // The composer editor should be present for the new draft thread.
-      await waitForComposerEditor();
+      await expect
+        .element(palette.getByRole("button", { name: "Add (Enter)" }))
+        .toBeInTheDocument();
 
-      // `thread.created` should only mark the draft as promoting; it should
-      // not navigate away until the server thread has actual runtime state.
-      await materializePromotedDraftThreadViaDomainEvent(newThreadId);
-      expect(mounted.router.state.location.pathname).toBe(newThreadPath);
-      await expect.element(page.getByTestId("composer-editor")).toBeInTheDocument();
+      await dispatchInputKey(browseInput, { key: "Enter" });
 
-      // Once the server thread starts, the route should canonicalize.
-      await startPromotedServerThreadViaDomainEvent(newThreadId);
       await vi.waitFor(
         () => {
-          expect(useComposerDraftStore.getState().draftThreadsByThreadKey[newDraftId]).toBe(
-            undefined,
-          );
+          const dispatchRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "project.create",
+          ) as
+            | {
+                _tag: string;
+                type?: string;
+                workspaceRoot?: string;
+                title?: string;
+              }
+            | undefined;
+
+          expect(dispatchRequest).toMatchObject({
+            _tag: ORCHESTRATION_WS_METHODS.dispatchCommand,
+            type: "project.create",
+            workspaceRoot: "~/Development",
+            title: "Development",
+          });
         },
         { timeout: 8_000, interval: 16 },
       );
 
-      // The route should switch to the canonical server thread path.
       await waitForURL(
         mounted.router,
-        (path) => path === serverThreadPath(newThreadId),
-        "Promoted drafts should canonicalize to the server thread route.",
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread after adding a project with Enter.",
       );
-
-      // The composer should remain usable after canonicalization, regardless of
-      // whether the promoted thread is still visibly empty or has already
-      // entered the running state.
-      await expect.element(page.getByTestId("composer-editor")).toBeInTheDocument();
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("canonicalizes stale promoted draft routes to the server thread route", async () => {
+  it("shows clone destination controls after resolving an add project repository", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-draft-hydration-race-test" as MessageId,
-        targetText: "draft hydration race test",
+        targetMessageId: "msg-user-command-palette-add-project-remote" as MessageId,
+        targetText: "command palette add project remote",
       }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          keybindings: [
+            {
+              command: "commandPalette.toggle",
+              shortcut: {
+                key: "k",
+                metaKey: false,
+                ctrlKey: false,
+                shiftKey: false,
+                altKey: false,
+                modKey: true,
+              },
+              whenAst: {
+                type: "not",
+                node: { type: "identifier", name: "terminalFocus" },
+              },
+            },
+          ],
+        };
+      },
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Development", fullPath: "~/Development" }],
+          };
+        }
+
+        if (body._tag === WS_METHODS.sourceControlLookupRepository) {
+          return {
+            provider: "github",
+            nameWithOwner: "t3-oss/t3-env",
+            url: "https://github.com/t3-oss/t3-env",
+            sshUrl: "git@github.com:t3-oss/t3-env.git",
+          };
+        }
+
+        if (body._tag === WS_METHODS.sourceControlCloneRepository) {
+          return {
+            cwd: body.destinationPath,
+            remoteUrl: body.remoteUrl,
+            repository: null,
+          };
+        }
+
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+
+        return undefined;
+      },
     });
 
     try {
-      const newThreadButton = page.getByTestId("new-thread-button");
-      await expect.element(newThreadButton).toBeInTheDocument();
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
+      const palette = page.getByTestId("command-palette");
+      await openCommandPaletteFromTrigger();
 
-      await newThreadButton.click();
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Add project", { exact: true }).click();
+      await palette.getByText("GitHub repository", { exact: true }).click();
 
-      const newThreadPath = await waitForURL(
-        mounted.router,
-        (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a new draft thread UUID.",
+      const repositoryInput = await waitForCommandPaletteInput(
+        "Enter GitHub repository (owner/repo)",
       );
-      const newDraftId = draftIdFromPath(newThreadPath);
-      const newThreadId = draftThreadIdFor(newDraftId);
-
-      await promoteDraftThreadViaDomainEvent(newThreadId);
+      await page.getByPlaceholder("Enter GitHub repository (owner/repo)").fill("t3-oss/t3-env");
+      await dispatchInputKey(repositoryInput, { key: "Enter" });
 
-      await mounted.router.navigate({
-        to: "/draft/$draftId",
-        params: { draftId: newDraftId },
-      });
+      await vi.waitFor(
+        () => {
+          const clonePathInput = document.querySelector<HTMLInputElement>(
+            'input[placeholder="Enter path (e.g. ~/projects/my-app)"]',
+          );
+          expect(clonePathInput?.value).toBe("~/");
+          expect(document.body.textContent).toContain("Repository");
+          expect(document.body.textContent).toContain("t3-oss/t3-env");
+          expect(document.body.textContent).toContain("https://github.com/t3-oss/t3-env");
+          expect(document.body.textContent).toContain("Select where to clone");
+          expect(document.body.textContent).toContain("Development");
+          expect(document.body.textContent).toContain("Clone");
+        },
+        { timeout: 8_000, interval: 16 },
+      );
 
-      await waitForURL(
-        mounted.router,
-        (path) => path === serverThreadPath(newThreadId),
-        "Stale promoted draft routes should canonicalize to the server thread path.",
+      await page
+        .getByPlaceholder("Enter path (e.g. ~/projects/my-app)")
+        .fill("~/Development/t3env");
+      const clonePathInput = await waitForCommandPaletteInput(
+        "Enter path (e.g. ~/projects/my-app)",
       );
+      await dispatchInputKey(clonePathInput, { key: "Enter" });
 
-      await expect.element(page.getByTestId("composer-editor")).toBeInTheDocument();
+      await vi.waitFor(
+        () => {
+          const cloneRequest = wsRequests.find(
+            (request) => request._tag === WS_METHODS.sourceControlCloneRepository,
+          ) as { destinationPath?: string; remoteUrl?: string } | undefined;
+          expect(cloneRequest).toMatchObject({
+            remoteUrl: "git@github.com:t3-oss/t3-env.git",
+            destinationPath: "~/Development/t3env",
+          });
+        },
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("snapshots sticky codex settings into a new draft thread", async () => {
-    useComposerDraftStore.setState({
-      stickyModelSelectionByProvider: {
-        codex: {
-          provider: "codex",
-          model: "gpt-5.3-codex",
-          options: {
-            reasoningEffort: "medium",
-            fastMode: true,
-          },
-        },
-      },
-      stickyActiveProvider: "codex",
-    });
-
+  it("opens add project browse mode from the sidebar add button", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-sticky-codex-traits-test" as MessageId,
-        targetText: "sticky codex traits test",
+        targetMessageId: "msg-user-sidebar-add-project-trigger" as MessageId,
+        targetText: "sidebar add project trigger",
       }),
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Development", fullPath: "~/Development" }],
+          };
+        }
+
+        return undefined;
+      },
     });
 
     try {
-      const newThreadButton = page.getByTestId("new-thread-button");
-      await expect.element(newThreadButton).toBeInTheDocument();
+      await waitForServerConfigToApply();
 
-      await newThreadButton.click();
+      await page.getByTestId("sidebar-add-project-trigger").click();
 
-      const newThreadPath = await waitForURL(
-        mounted.router,
-        (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a new draft thread UUID.",
-      );
-      const newDraftId = draftIdFromPath(newThreadPath);
+      const palette = page.getByTestId("command-palette");
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Local folder", { exact: true }).click();
 
-      expect(composerDraftFor(newDraftId)).toMatchObject({
-        modelSelectionByProvider: {
-          codex: {
-            provider: "codex",
-            model: "gpt-5.3-codex",
-            options: {
-              fastMode: true,
-            },
-          },
+      const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await expect.element(browseInput).toHaveValue("~/");
+
+      await vi.waitFor(
+        () => {
+          expect(
+            wsRequests.some(
+              (request) =>
+                request._tag === WS_METHODS.filesystemBrowse && request.partialPath === "~/",
+            ),
+          ).toBe(true);
         },
-        activeProvider: "codex",
-      });
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("hydrates the provider alongside a sticky claude model", async () => {
-    useComposerDraftStore.setState({
-      stickyModelSelectionByProvider: {
-        claudeAgent: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            effort: "max",
-            fastMode: true,
-          },
-        },
-      },
-      stickyActiveProvider: "claudeAgent",
-    });
-
+  it("starts add project browse mode from the configured base directory", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-sticky-claude-model-test" as MessageId,
-        targetText: "sticky claude model test",
+        targetMessageId: "msg-user-sidebar-add-project-custom-base-dir" as MessageId,
+        targetText: "sidebar add project custom base directory",
       }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          settings: {
+            ...nextFixture.serverConfig.settings,
+            addProjectBaseDirectory: "~/Development",
+          },
+        };
+      },
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          if (body.partialPath === "~/Development/") {
+            return {
+              parentPath: "~/Development/",
+              entries: [{ name: "codething", fullPath: "~/Development/codething" }],
+            };
+          }
+
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Development", fullPath: "~/Development" }],
+          };
+        }
+
+        return undefined;
+      },
     });
 
     try {
-      const newThreadButton = page.getByTestId("new-thread-button");
-      await expect.element(newThreadButton).toBeInTheDocument();
+      await waitForServerConfigToApply();
 
-      await newThreadButton.click();
+      await page.getByTestId("sidebar-add-project-trigger").click();
 
-      const newThreadPath = await waitForURL(
-        mounted.router,
-        (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a new sticky claude draft thread UUID.",
-      );
-      const newDraftId = draftIdFromPath(newThreadPath);
+      const palette = page.getByTestId("command-palette");
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Local folder", { exact: true }).click();
 
-      expect(composerDraftFor(newDraftId)).toMatchObject({
-        modelSelectionByProvider: {
-          claudeAgent: {
-            provider: "claudeAgent",
-            model: "claude-opus-4-6",
-            options: {
-              effort: "max",
-              fastMode: true,
-            },
-          },
+      const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await expect.element(browseInput).toHaveValue("~/Development/");
+
+      await vi.waitFor(
+        () => {
+          expect(
+            wsRequests.some(
+              (request) =>
+                request._tag === WS_METHODS.filesystemBrowse &&
+                request.partialPath === "~/Development/",
+            ),
+          ).toBe(true);
         },
-        activeProvider: "claudeAgent",
-      });
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("falls back to defaults when no sticky composer settings exist", async () => {
+  it("shows create-folder affordances for missing project paths", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-default-codex-traits-test" as MessageId,
-        targetText: "default codex traits test",
+        targetMessageId: "msg-user-command-palette-create-missing-project" as MessageId,
+        targetText: "command palette create missing project",
       }),
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          if (body.partialPath === "~/Desktop/") {
+            return {
+              parentPath: "~/Desktop/",
+              entries: [{ name: "existing", fullPath: "~/Desktop/existing" }],
+            };
+          }
+
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Desktop", fullPath: "~/Desktop" }],
+          };
+        }
+
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+
+        return undefined;
+      },
     });
 
     try {
-      const newThreadButton = page.getByTestId("new-thread-button");
-      await expect.element(newThreadButton).toBeInTheDocument();
+      await waitForServerConfigToApply();
+      const palette = page.getByTestId("command-palette");
+      await page.getByTestId("sidebar-add-project-trigger").click();
 
-      await newThreadButton.click();
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Local folder", { exact: true }).click();
+      const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await page.getByPlaceholder(ADD_PROJECT_SUBMENU_PLACEHOLDER).fill("~/Desktop/fresh-project");
 
-      const newThreadPath = await waitForURL(
-        mounted.router,
-        (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a new draft thread UUID.",
-      );
-      const newDraftId = draftIdFromPath(newThreadPath);
+      await expect
+        .element(palette.getByRole("button", { name: "Create & Add (Enter)" }))
+        .toBeInTheDocument();
+      await expect.element(palette.getByText("Will create this folder")).not.toBeInTheDocument();
 
-      expect(composerDraftFor(newDraftId)).toBe(undefined);
+      await dispatchInputKey(browseInput, { key: "Enter" });
+
+      await vi.waitFor(
+        () => {
+          const dispatchRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "project.create",
+          ) as
+            | {
+                _tag: string;
+                type?: string;
+                workspaceRoot?: string;
+                title?: string;
+                createWorkspaceRootIfMissing?: boolean;
+              }
+            | undefined;
+
+          expect(dispatchRequest).toMatchObject({
+            _tag: ORCHESTRATION_WS_METHODS.dispatchCommand,
+            type: "project.create",
+            workspaceRoot: "~/Desktop/fresh-project",
+            title: "fresh-project",
+            createWorkspaceRootIfMissing: true,
+          });
+        },
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("prefers draft state over sticky composer settings and defaults", async () => {
-    useComposerDraftStore.setState({
-      stickyModelSelectionByProvider: {
-        codex: {
-          provider: "codex",
-          model: "gpt-5.3-codex",
-          options: {
-            reasoningEffort: "medium",
-            fastMode: true,
-          },
-        },
-      },
-      stickyActiveProvider: "codex",
-    });
-
+  it("does not show create affordances for an existing directory with a trailing slash", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-draft-codex-traits-precedence-test" as MessageId,
-        targetText: "draft codex traits precedence test",
+        targetMessageId: "msg-user-command-palette-existing-trailing-directory" as MessageId,
+        targetText: "command palette existing trailing directory",
       }),
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          if (body.partialPath === "~/Development/codex/") {
+            return {
+              parentPath: "~/Development/codex/",
+              entries: [{ name: "Codex.app", fullPath: "~/Development/codex/Codex.app" }],
+            };
+          }
+
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Development", fullPath: "~/Development" }],
+          };
+        }
+
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+
+        return undefined;
+      },
     });
 
     try {
-      const newThreadButton = page.getByTestId("new-thread-button");
-      await expect.element(newThreadButton).toBeInTheDocument();
+      await waitForServerConfigToApply();
+      const palette = page.getByTestId("command-palette");
+      await page.getByTestId("sidebar-add-project-trigger").click();
 
-      await newThreadButton.click();
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Local folder", { exact: true }).click();
+      const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await page.getByPlaceholder(ADD_PROJECT_SUBMENU_PLACEHOLDER).fill("~/Development/codex/");
 
-      const threadPath = await waitForURL(
-        mounted.router,
-        (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a sticky draft thread UUID.",
+      await vi.waitFor(
+        () => {
+          expect(
+            wsRequests.some(
+              (request) =>
+                request._tag === WS_METHODS.filesystemBrowse &&
+                request.partialPath === "~/Development/codex/",
+            ),
+          ).toBe(true);
+        },
+        { timeout: 8_000, interval: 16 },
       );
-      const draftId = draftIdFromPath(threadPath);
 
-      expect(composerDraftFor(draftId)).toMatchObject({
-        modelSelectionByProvider: {
-          codex: {
-            provider: "codex",
-            model: "gpt-5.3-codex",
-            options: {
-              fastMode: true,
-            },
-          },
-        },
-        activeProvider: "codex",
-      });
+      await expect
+        .element(palette.getByRole("button", { name: "Add (Enter)" }))
+        .toBeInTheDocument();
+      await expect
+        .element(palette.getByRole("button", { name: "Create & Add (Enter)" }))
+        .not.toBeInTheDocument();
 
-      useComposerDraftStore.getState().setModelSelection(draftId, {
-        provider: "codex",
-        model: "gpt-5.4",
-        options: {
-          reasoningEffort: "low",
-          fastMode: true,
-        },
-      });
+      await dispatchInputKey(browseInput, { key: "Enter" });
 
-      await newThreadButton.click();
+      await vi.waitFor(
+        () => {
+          const dispatchRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "project.create",
+          ) as
+            | {
+                _tag: string;
+                type?: string;
+                workspaceRoot?: string;
+                title?: string;
+              }
+            | undefined;
 
-      await waitForURL(
-        mounted.router,
-        (path) => path === threadPath,
-        "New-thread should reuse the existing project draft thread.",
-      );
-      expect(composerDraftFor(draftId)).toMatchObject({
-        modelSelectionByProvider: {
-          codex: {
-            provider: "codex",
-            model: "gpt-5.4",
-            options: {
-              reasoningEffort: "low",
-              fastMode: true,
-            },
-          },
+          expect(dispatchRequest).toMatchObject({
+            _tag: ORCHESTRATION_WS_METHODS.dispatchCommand,
+            type: "project.create",
+            workspaceRoot: "~/Development/codex",
+            title: "codex",
+          });
         },
-        activeProvider: "codex",
-      });
+        { timeout: 8_000, interval: 16 },
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("creates a new thread from the global chat.new shortcut", async () => {
+  it("selects an environment before browsing when multiple environments are available", async () => {
+    const remoteBrowseMock = vi.fn(async ({ partialPath }: { partialPath: string }) => {
+      if (partialPath === "~/workspaces/") {
+        return {
+          parentPath: "~/workspaces/",
+          entries: [{ name: "codething", fullPath: "~/workspaces/codething" }],
+        };
+      }
+
+      return {
+        parentPath: "~/",
+        entries: [{ name: "workspaces", fullPath: "~/workspaces" }],
+      };
+    });
+    const remoteDispatchMock = vi.fn(async () => ({
+      sequence: fixture.snapshot.snapshotSequence + 1,
+    }));
+
+    __setEnvironmentApiOverrideForTests(
+      REMOTE_ENVIRONMENT_ID,
+      createMockEnvironmentApi({
+        browse: remoteBrowseMock,
+        dispatchCommand: remoteDispatchMock,
+      }),
+    );
+
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-chat-shortcut-test" as MessageId,
-        targetText: "chat shortcut test",
+        targetMessageId: "msg-user-command-palette-add-project-multi-env" as MessageId,
+        targetText: "command palette add project multi env",
       }),
-      configureFixture: (nextFixture) => {
-        nextFixture.serverConfig = {
-          ...nextFixture.serverConfig,
-          keybindings: [
-            {
-              command: "chat.new",
-              shortcut: {
-                key: "o",
-                metaKey: false,
-                ctrlKey: false,
-                shiftKey: true,
-                altKey: false,
-                modKey: true,
-              },
-              whenAst: {
-                type: "not",
-                node: { type: "identifier", name: "terminalFocus" },
-              },
-            },
-          ],
-        };
-      },
     });
 
     try {
-      await waitForNewThreadShortcutLabel();
       await waitForServerConfigToApply();
-      const composerEditor = await waitForComposerEditor();
-      composerEditor.focus();
-      await waitForLayout();
-      await triggerChatNewShortcutUntilPath(
-        mounted.router,
-        (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a new draft thread UUID from the shortcut.",
+      useSavedEnvironmentRegistryStore.getState().upsert({
+        environmentId: REMOTE_ENVIRONMENT_ID,
+        label: "Staging",
+        httpBaseUrl: "https://staging.example.test",
+        wsBaseUrl: "wss://staging.example.test/ws",
+        createdAt: NOW_ISO,
+        lastConnectedAt: NOW_ISO,
+      });
+      useSavedEnvironmentRuntimeStore.getState().patch(REMOTE_ENVIRONMENT_ID, {
+        connectionState: "connected",
+        authState: "authenticated",
+        descriptor: {
+          ...fixture.serverConfig.environment,
+          environmentId: REMOTE_ENVIRONMENT_ID,
+          label: "Staging",
+        },
+        serverConfig: {
+          ...fixture.serverConfig,
+          environment: {
+            ...fixture.serverConfig.environment,
+            environmentId: REMOTE_ENVIRONMENT_ID,
+            label: "Staging",
+          },
+          settings: {
+            ...fixture.serverConfig.settings,
+            addProjectBaseDirectory: "~/workspaces",
+          },
+        },
+        connectedAt: NOW_ISO,
+      });
+
+      const palette = page.getByTestId("command-palette");
+      await openCommandPaletteFromTrigger();
+
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Add project", { exact: true }).click();
+      await expect.element(palette.getByText("Environments", { exact: true })).toBeInTheDocument();
+      await expect
+        .element(palette.getByText("This device", { exact: true }).first())
+        .toBeInTheDocument();
+      await palette.getByText("Staging", { exact: true }).click();
+      await palette.getByText("Local folder", { exact: true }).click();
+
+      const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await expect.element(browseInput).toHaveValue("~/workspaces/");
+
+      await vi.waitFor(
+        () => {
+          expect(remoteBrowseMock).toHaveBeenCalledWith({ partialPath: "~/workspaces/" });
+        },
+        { timeout: 8_000, interval: 16 },
       );
-    } finally {
-      await mounted.cleanup();
-    }
-  });
 
-  it("does not consume chat.new when there is no project context", async () => {
-    const mounted = await mountChatView({
-      viewport: DEFAULT_VIEWPORT,
-      snapshot: createProjectlessSnapshot(),
-      configureFixture: (nextFixture) => {
-        nextFixture.serverConfig = {
-          ...nextFixture.serverConfig,
-          keybindings: [
-            {
-              command: "chat.new",
-              shortcut: {
-                key: "o",
-                metaKey: false,
-                ctrlKey: false,
-                shiftKey: true,
-                altKey: false,
-                modKey: true,
-              },
-              whenAst: {
-                type: "not",
-                node: { type: "identifier", name: "terminalFocus" },
-              },
-            },
-          ],
-        };
-      },
-    });
+      await page.getByPlaceholder(ADD_PROJECT_SUBMENU_PLACEHOLDER).fill("~/workspaces/");
+      await vi.waitFor(
+        () => {
+          expect(remoteBrowseMock).toHaveBeenCalledWith({ partialPath: "~/workspaces/" });
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+      await expect.element(palette.getByText("codething", { exact: true })).toBeInTheDocument();
+      await expect
+        .element(palette.getByRole("button", { name: "Add (Enter)" }))
+        .toBeInTheDocument();
 
-    try {
-      await waitForServerConfigToApply();
-      dispatchChatNewShortcut();
-      await waitForLayout();
+      await dispatchInputKey(browseInput, { key: "Enter" });
 
-      expect(mounted.router.state.location.pathname).toBe(serverThreadPath(THREAD_ID));
-      expect(Object.keys(useComposerDraftStore.getState().draftThreadsByThreadKey)).toHaveLength(0);
+      await vi.waitFor(
+        () => {
+          expect(remoteDispatchMock).toHaveBeenCalledWith(
+            expect.objectContaining({
+              type: "project.create",
+              workspaceRoot: "~/workspaces",
+              title: "workspaces",
+            }),
+          );
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread after adding a remote project.",
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("renders the configurable shortcut and runs a command from the sidebar trigger", async () => {
+  it("picks a local project from the native file manager", async () => {
+    const pickFolder = vi.fn().mockResolvedValue("/Users/julius/Projects/finder-picked");
+
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-command-palette-shortcut-test" as MessageId,
-        targetText: "command palette shortcut test",
+        targetMessageId: "msg-user-command-palette-add-project-file-manager" as MessageId,
+        targetText: "command palette add project file manager",
       }),
-      configureFixture: (nextFixture) => {
-        nextFixture.serverConfig = {
-          ...nextFixture.serverConfig,
-          keybindings: [
-            {
-              command: "commandPalette.toggle",
-              shortcut: {
-                key: "k",
-                metaKey: false,
-                ctrlKey: false,
-                shiftKey: false,
-                altKey: false,
-                modKey: true,
-              },
-              whenAst: {
-                type: "not",
-                node: { type: "identifier", name: "terminalFocus" },
-              },
-            },
-          ],
-        };
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          if (body.partialPath === "~/Applications/") {
+            return {
+              parentPath: "~/Applications/",
+              entries: [{ name: "Utilities", fullPath: "~/Applications/Utilities" }],
+            };
+          }
+
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Applications", fullPath: "~/Applications" }],
+          };
+        }
+
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+
+        return undefined;
       },
     });
 
     try {
       await waitForServerConfigToApply();
-      await waitForCommandPaletteShortcutLabel();
-      const palette = page.getByTestId("command-palette");
-      await openCommandPaletteFromTrigger();
+      window.desktopBridge = {
+        pickFolder,
+        setTheme: vi.fn().mockResolvedValue(undefined),
+      } as unknown as NonNullable<typeof window.desktopBridge>;
+
+      await page.getByTestId("sidebar-add-project-trigger").click();
 
+      const palette = page.getByTestId("command-palette");
       await expect.element(palette).toBeInTheDocument();
-      await expect
-        .element(palette.getByText("New thread in Project", { exact: true }))
-        .toBeInTheDocument();
-      await palette.getByText("New thread in Project", { exact: true }).click();
+      await palette.getByText("Local folder", { exact: true }).click();
+      const browseInput = palette.getByPlaceholder(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await browseInput.fill("~/Applications/access");
+
+      const fileManagerLabel = isMacPlatform(navigator.platform)
+        ? "Open in Finder"
+        : navigator.platform.toLowerCase().startsWith("win")
+          ? "Open in Explorer"
+          : "Open in Files";
+      await palette.getByRole("button", { name: fileManagerLabel }).click();
+
+      await vi.waitFor(
+        () => {
+          expect(pickFolder).toHaveBeenCalledWith({ initialPath: "~/Applications" });
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      await vi.waitFor(
+        () => {
+          const dispatchRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "project.create",
+          ) as
+            | {
+                _tag: string;
+                type?: string;
+                workspaceRoot?: string;
+                title?: string;
+              }
+            | undefined;
+
+          expect(dispatchRequest).toMatchObject({
+            _tag: ORCHESTRATION_WS_METHODS.dispatchCommand,
+            type: "project.create",
+            workspaceRoot: "/Users/julius/Projects/finder-picked",
+            title: "finder-picked",
+          });
+        },
+        { timeout: 8_000, interval: 16 },
+      );
 
       await waitForURL(
         mounted.router,
         (path) => UUID_ROUTE_RE.test(path),
-        "Route should have changed to a new draft thread UUID from the command palette.",
+        "Route should have changed to a new draft thread after adding a project from the native file manager.",
       );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("filters command palette results as the user types", async () => {
+  it("adds a project from browse mode with Mod+Enter when a directory is highlighted", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
-        targetMessageId: "msg-user-command-palette-search-test" as MessageId,
-        targetText: "command palette search test",
+        targetMessageId: "msg-user-command-palette-add-project-mod-enter" as MessageId,
+        targetText: "command palette add project mod enter",
       }),
       configureFixture: (nextFixture) => {
         nextFixture.serverConfig = {
@@ -3742,6 +5235,32 @@ describe("ChatView timeline estimator parity (full app)", () => {
           ],
         };
       },
+      resolveRpc: (body) => {
+        if (body._tag === WS_METHODS.filesystemBrowse) {
+          if (body.partialPath === "~/Development/") {
+            return {
+              parentPath: "~/Development/",
+              entries: [
+                { name: "alpha", fullPath: "~/Development/alpha" },
+                { name: "beta", fullPath: "~/Development/beta" },
+              ],
+            };
+          }
+
+          return {
+            parentPath: "~/",
+            entries: [{ name: "Development", fullPath: "~/Development" }],
+          };
+        }
+
+        if (body._tag === ORCHESTRATION_WS_METHODS.dispatchCommand) {
+          return {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+
+        return undefined;
+      },
     });
 
     try {
@@ -3751,11 +5270,65 @@ describe("ChatView timeline estimator parity (full app)", () => {
       await openCommandPaletteFromTrigger();
 
       await expect.element(palette).toBeInTheDocument();
-      await page.getByPlaceholder("Search commands, projects, and threads...").fill("settings");
-      await expect.element(palette.getByText("Open settings", { exact: true })).toBeInTheDocument();
+      await palette.getByText("Add project", { exact: true }).click();
+      await palette.getByText("Local folder", { exact: true }).click();
+
+      const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
+      await page.getByPlaceholder(ADD_PROJECT_SUBMENU_PLACEHOLDER).fill("~/Development/");
+      await expect.element(palette.getByText("alpha", { exact: true })).toBeInTheDocument();
+
+      await dispatchInputKey(browseInput, { key: "ArrowDown" });
+
+      const addButtonLabel = isMacPlatform(navigator.platform)
+        ? "Add (\u2318 Enter)"
+        : "Add (Ctrl Enter)";
+      await vi.waitFor(
+        () => {
+          const legendEntries = getCommandPaletteLegendEntries();
+          expect(legendEntries).toContain("Enter Select");
+        },
+        { timeout: 8_000, interval: 16 },
+      );
       await expect
-        .element(palette.getByText("New thread in Project", { exact: true }))
-        .not.toBeInTheDocument();
+        .element(palette.getByRole("button", { name: addButtonLabel }))
+        .toBeInTheDocument();
+
+      await dispatchInputKey(browseInput, {
+        key: "Enter",
+        metaKey: isMacPlatform(navigator.platform),
+        ctrlKey: !isMacPlatform(navigator.platform),
+      });
+
+      await vi.waitFor(
+        () => {
+          const dispatchRequest = wsRequests.find(
+            (request) =>
+              request._tag === ORCHESTRATION_WS_METHODS.dispatchCommand &&
+              request.type === "project.create",
+          ) as
+            | {
+                _tag: string;
+                type?: string;
+                workspaceRoot?: string;
+                title?: string;
+              }
+            | undefined;
+
+          expect(dispatchRequest).toMatchObject({
+            _tag: ORCHESTRATION_WS_METHODS.dispatchCommand,
+            type: "project.create",
+            workspaceRoot: "~/Development",
+            title: "Development",
+          });
+        },
+        { timeout: 8_000, interval: 16 },
+      );
+
+      await waitForURL(
+        mounted.router,
+        (path) => UUID_ROUTE_RE.test(path),
+        "Route should have changed to a new draft thread after adding a project with Mod+Enter.",
+      );
     } finally {
       await mounted.cleanup();
     }
@@ -4270,7 +5843,10 @@ describe("ChatView timeline estimator parity (full app)", () => {
     const mounted = await mountChatView({
       viewport: WIDE_FOOTER_VIEWPORT,
       snapshot: createSnapshotWithPlanFollowUpPrompt({
-        modelSelection: { provider: "codex", model: "gpt-5.3-codex-spark" },
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5.3-codex-spark",
+        },
         planMarkdown:
           "# Imaginary Long-Range Plan: T3 Code Adaptive Orchestration and Safe-Delay Execution Initiative",
       }),
@@ -4300,7 +5876,10 @@ describe("ChatView timeline estimator parity (full app)", () => {
     const mounted = await mountChatView({
       viewport: WIDE_FOOTER_VIEWPORT,
       snapshot: createSnapshotWithPlanFollowUpPrompt({
-        modelSelection: { provider: "codex", model: "gpt-5.3-codex-spark" },
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5.3-codex-spark",
+        },
         planMarkdown:
           "# Imaginary Long-Range Plan: T3 Code Adaptive Orchestration and Safe-Delay Execution Initiative",
       }),
@@ -4373,6 +5952,204 @@ describe("ChatView timeline estimator parity (full app)", () => {
     }
   });
 
+  it("opens the model picker when selecting /model", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-model-command-target" as MessageId,
+        targetText: "model command thread",
+      }),
+    });
+
+    try {
+      await waitForComposerEditor();
+      await page.getByTestId("composer-editor").fill("/mod");
+
+      const menuItem = await waitForComposerMenuItem("slash:model");
+      await menuItem.click();
+
+      await vi.waitFor(() => {
+        expect(document.querySelector(".model-picker-list")).not.toBeNull();
+        expect(findComposerProviderModelPicker()?.textContent).not.toContain("/model");
+      });
+
+      await new Promise<void>((resolve) => {
+        requestAnimationFrame(() => {
+          requestAnimationFrame(() => resolve());
+        });
+      });
+
+      await vi.waitFor(() => {
+        const searchInput = document.querySelector<HTMLInputElement>(
+          'input[placeholder="Search models..."]',
+        );
+        expect(searchInput).not.toBeNull();
+        expect(document.activeElement).toBe(searchInput);
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("toggles the model picker and shows jump keys immediately from the shortcut", async () => {
+    const snapshot = createSnapshotForTargetUser({
+      targetMessageId: "msg-user-model-picker-shortcut-target" as MessageId,
+      targetText: "model picker shortcut thread",
+    });
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: {
+        ...snapshot,
+        projects: snapshot.projects.map((project) =>
+          project.id === PROJECT_ID
+            ? Object.assign({}, project, {
+                defaultModelSelection: {
+                  instanceId: ProviderInstanceId.make("codex"),
+                  model: "gpt-5.4",
+                },
+              })
+            : project,
+        ),
+        threads: snapshot.threads.map((thread) =>
+          thread.id === THREAD_ID
+            ? Object.assign({}, thread, {
+                modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
+              })
+            : thread,
+        ),
+      },
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          keybindings: [
+            {
+              command: "modelPicker.toggle",
+              shortcut: {
+                key: "m",
+                metaKey: false,
+                ctrlKey: true,
+                shiftKey: true,
+                altKey: false,
+                modKey: false,
+              },
+              whenAst: {
+                type: "not",
+                node: { type: "identifier", name: "terminalFocus" },
+              },
+            },
+            {
+              command: "thread.jump.1",
+              shortcut: {
+                key: "1",
+                metaKey: false,
+                ctrlKey: true,
+                shiftKey: false,
+                altKey: false,
+                modKey: false,
+              },
+            },
+            {
+              command: "modelPicker.jump.1",
+              shortcut: {
+                key: "1",
+                metaKey: false,
+                ctrlKey: true,
+                shiftKey: false,
+                altKey: false,
+                modKey: false,
+              },
+              whenAst: { type: "identifier", name: "modelPickerOpen" },
+            },
+          ],
+          providers: [
+            {
+              ...nextFixture.serverConfig.providers[0]!,
+              models: [
+                {
+                  slug: "gpt-5.1-codex-max",
+                  name: "GPT-5.1 Codex Max",
+                  isCustom: false,
+                  capabilities: createModelCapabilities({
+                    optionDescriptors: [
+                      { id: "fastMode", label: "Fast Mode", type: "boolean" as const },
+                    ],
+                  }),
+                },
+                {
+                  slug: "gpt-5.3-codex",
+                  name: "GPT-5.3 Codex",
+                  isCustom: false,
+                  capabilities: createModelCapabilities({
+                    optionDescriptors: [
+                      { id: "fastMode", label: "Fast Mode", type: "boolean" as const },
+                    ],
+                  }),
+                },
+                {
+                  slug: "gpt-5.4",
+                  name: "GPT-5.4",
+                  isCustom: false,
+                  capabilities: createModelCapabilities({
+                    optionDescriptors: [
+                      { id: "fastMode", label: "Fast Mode", type: "boolean" as const },
+                    ],
+                  }),
+                },
+              ],
+            },
+          ],
+        };
+      },
+    });
+
+    try {
+      await waitForServerConfigToApply();
+      await waitForComposerEditor();
+
+      const initialPath = mounted.router.state.location.pathname;
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "m",
+          ctrlKey: true,
+          shiftKey: true,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+
+      await vi.waitFor(() => {
+        expect(document.querySelector(".model-picker-list")).not.toBeNull();
+      });
+
+      const jumpLabel = isMacPlatform(navigator.platform) ? "⌃1" : "Ctrl+1";
+      await vi.waitFor(() => {
+        expect(
+          Array.from(
+            document.querySelectorAll<HTMLElement>('.model-picker-list [data-slot="kbd"]'),
+          ).some((element) => element.textContent?.trim() === jumpLabel),
+        ).toBe(true);
+      });
+      expect(mounted.router.state.location.pathname).toBe(initialPath);
+
+      window.dispatchEvent(
+        new KeyboardEvent("keydown", {
+          key: "m",
+          ctrlKey: true,
+          shiftKey: true,
+          bubbles: true,
+          cancelable: true,
+        }),
+      );
+
+      await vi.waitFor(() => {
+        expect(document.querySelector(".model-picker-list")).toBeNull();
+      });
+    } finally {
+      releaseModShortcut("Control");
+      await mounted.cleanup();
+    }
+  });
+
   it("shows a tooltip with the skill description when hovering a skill pill", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
diff --git a/apps/web/src/components/ChatView.logic.test.ts b/apps/web/src/components/ChatView.logic.test.ts
index 1b96265a40e..83c90edaddc 100644
--- a/apps/web/src/components/ChatView.logic.test.ts
+++ b/apps/web/src/components/ChatView.logic.test.ts
@@ -1,5 +1,12 @@
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { EnvironmentId, ProjectId, ThreadId, TurnId } from "@t3tools/contracts";
+import {
+  EnvironmentId,
+  ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ThreadId,
+  TurnId,
+} from "@t3tools/contracts";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { type EnvironmentState, useStore } from "../store";
 import { type Thread } from "../types";
@@ -11,6 +18,7 @@ import {
   deriveComposerSendState,
   hasServerAcknowledgedLocalDispatch,
   reconcileMountedTerminalThreadIds,
+  resolveSendEnvMode,
   shouldWriteThreadErrorToCurrentServerThread,
   waitForStartedServerThread,
 } from "./ChatView.logic";
@@ -82,6 +90,17 @@ describe("buildExpiredTerminalContextToastCopy", () => {
   });
 });
 
+describe("resolveSendEnvMode", () => {
+  it("keeps worktree mode for git repositories", () => {
+    expect(resolveSendEnvMode({ requestedEnvMode: "worktree", isGitRepo: true })).toBe("worktree");
+  });
+
+  it("forces local mode for non-git repositories", () => {
+    expect(resolveSendEnvMode({ requestedEnvMode: "worktree", isGitRepo: false })).toBe("local");
+    expect(resolveSendEnvMode({ requestedEnvMode: "local", isGitRepo: false })).toBe("local");
+  });
+});
+
 describe("reconcileMountedTerminalThreadIds", () => {
   it("keeps previously mounted open threads and adds the active open thread", () => {
     expect(
@@ -208,7 +227,7 @@ const makeThread = (input?: {
   codexThreadId: null,
   projectId: ProjectId.make("project-1"),
   title: "Thread",
-  modelSelection: { provider: "codex" as const, model: "gpt-5.4" },
+  modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
   runtimeMode: "full-access" as const,
   interactionMode: "default" as const,
   session: null,
@@ -241,7 +260,7 @@ function setStoreThreads(threads: ReadonlyArray<ReturnType<typeof makeThread>>)
         name: "Project",
         cwd: "/tmp/project",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5.4",
         },
         createdAt: "2026-03-29T00:00:00.000Z",
@@ -440,7 +459,7 @@ describe("hasServerAcknowledgedLocalDispatch", () => {
   };
 
   const previousSession = {
-    provider: "codex" as const,
+    provider: ProviderDriverKind.make("codex"),
     status: "ready" as const,
     createdAt: "2026-03-29T00:00:00.000Z",
     updatedAt: "2026-03-29T00:00:10.000Z",
@@ -454,7 +473,7 @@ describe("hasServerAcknowledgedLocalDispatch", () => {
       codexThreadId: null,
       projectId,
       title: "Thread",
-      modelSelection: { provider: "codex", model: "gpt-5.4" },
+      modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
       runtimeMode: "full-access",
       interactionMode: "default",
       session: previousSession,
@@ -491,7 +510,7 @@ describe("hasServerAcknowledgedLocalDispatch", () => {
       codexThreadId: null,
       projectId,
       title: "Thread",
-      modelSelection: { provider: "codex", model: "gpt-5.4" },
+      modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
       runtimeMode: "full-access",
       interactionMode: "default",
       session: previousSession,
@@ -530,6 +549,142 @@ describe("hasServerAcknowledgedLocalDispatch", () => {
     ).toBe(true);
   });
 
+  it("does not clear local dispatch while the session is running a newer turn than latestTurn", () => {
+    const localDispatch = createLocalDispatchSnapshot({
+      id: ThreadId.make("thread-1"),
+      environmentId: localEnvironmentId,
+      codexThreadId: null,
+      projectId,
+      title: "Thread",
+      modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
+      runtimeMode: "full-access",
+      interactionMode: "default",
+      session: previousSession,
+      messages: [],
+      proposedPlans: [],
+      error: null,
+      createdAt: "2026-03-29T00:00:00.000Z",
+      archivedAt: null,
+      updatedAt: "2026-03-29T00:00:10.000Z",
+      latestTurn: previousLatestTurn,
+      branch: null,
+      worktreePath: null,
+      turnDiffSummaries: [],
+      activities: [],
+    });
+
+    expect(
+      hasServerAcknowledgedLocalDispatch({
+        localDispatch,
+        phase: "running",
+        latestTurn: previousLatestTurn,
+        session: {
+          ...previousSession,
+          status: "running",
+          orchestrationStatus: "running",
+          activeTurnId: TurnId.make("turn-2"),
+          updatedAt: "2026-03-29T00:01:00.000Z",
+        },
+        hasPendingApproval: false,
+        hasPendingUserInput: false,
+        threadError: null,
+      }),
+    ).toBe(false);
+  });
+
+  it("does not clear local dispatch while the session is running but latestTurn has not advanced yet", () => {
+    const localDispatch = createLocalDispatchSnapshot({
+      id: ThreadId.make("thread-1"),
+      environmentId: localEnvironmentId,
+      codexThreadId: null,
+      projectId,
+      title: "Thread",
+      modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
+      runtimeMode: "full-access",
+      interactionMode: "default",
+      session: previousSession,
+      messages: [],
+      proposedPlans: [],
+      error: null,
+      createdAt: "2026-03-29T00:00:00.000Z",
+      archivedAt: null,
+      updatedAt: "2026-03-29T00:00:10.000Z",
+      latestTurn: previousLatestTurn,
+      branch: null,
+      worktreePath: null,
+      turnDiffSummaries: [],
+      activities: [],
+    });
+
+    expect(
+      hasServerAcknowledgedLocalDispatch({
+        localDispatch,
+        phase: "running",
+        latestTurn: previousLatestTurn,
+        session: {
+          ...previousSession,
+          status: "running",
+          orchestrationStatus: "running",
+          activeTurnId: undefined,
+          updatedAt: "2026-03-29T00:01:00.000Z",
+        },
+        hasPendingApproval: false,
+        hasPendingUserInput: false,
+        threadError: null,
+      }),
+    ).toBe(false);
+  });
+
+  it("clears local dispatch once the running latestTurn matches the active session turn", () => {
+    const localDispatch = createLocalDispatchSnapshot({
+      id: ThreadId.make("thread-1"),
+      environmentId: localEnvironmentId,
+      codexThreadId: null,
+      projectId,
+      title: "Thread",
+      modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
+      runtimeMode: "full-access",
+      interactionMode: "default",
+      session: previousSession,
+      messages: [],
+      proposedPlans: [],
+      error: null,
+      createdAt: "2026-03-29T00:00:00.000Z",
+      archivedAt: null,
+      updatedAt: "2026-03-29T00:00:10.000Z",
+      latestTurn: previousLatestTurn,
+      branch: null,
+      worktreePath: null,
+      turnDiffSummaries: [],
+      activities: [],
+    });
+
+    expect(
+      hasServerAcknowledgedLocalDispatch({
+        localDispatch,
+        phase: "running",
+        latestTurn: {
+          ...previousLatestTurn,
+          turnId: TurnId.make("turn-2"),
+          state: "running",
+          requestedAt: "2026-03-29T00:01:00.000Z",
+          startedAt: "2026-03-29T00:01:01.000Z",
+          completedAt: null,
+        },
+        session: {
+          ...previousSession,
+          status: "running",
+          orchestrationStatus: "running",
+          activeTurnId: TurnId.make("turn-2"),
+          updatedAt: "2026-03-29T00:01:01.000Z",
+        },
+        hasPendingApproval: false,
+        hasPendingUserInput: false,
+        threadError: null,
+      }),
+    ).toBe(true);
+  });
+
   it("clears local dispatch when the session changes without an observed running phase", () => {
     const localDispatch = createLocalDispatchSnapshot({
       id: ThreadId.make("thread-1"),
@@ -537,7 +692,7 @@ describe("hasServerAcknowledgedLocalDispatch", () => {
       codexThreadId: null,
       projectId,
       title: "Thread",
-      modelSelection: { provider: "codex", model: "gpt-5.4" },
+      modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
       runtimeMode: "full-access",
       interactionMode: "default",
       session: previousSession,
diff --git a/apps/web/src/components/ChatView.logic.ts b/apps/web/src/components/ChatView.logic.ts
index a753a71b390..bf87add28d9 100644
--- a/apps/web/src/components/ChatView.logic.ts
+++ b/apps/web/src/components/ChatView.logic.ts
@@ -1,26 +1,26 @@
 import {
   type EnvironmentId,
+  isProviderDriverKind,
   ProjectId,
   type ModelSelection,
-  type ProviderKind,
+  type ProviderDriverKind,
   type ScopedThreadRef,
   type ThreadId,
   type TurnId,
 } from "@t3tools/contracts";
 import { type ChatMessage, type SessionPhase, type Thread, type ThreadSession } from "../types";
-import { randomUUID } from "~/lib/utils";
 import { type ComposerImageAttachment, type DraftThreadState } from "../composerDraftStore";
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 import { selectThreadByRef, useStore } from "../store";
 import {
   filterTerminalContextsWithText,
   stripInlineTerminalContextPlaceholders,
   type TerminalContextDraft,
 } from "../lib/terminalContext";
+import type { DraftThreadEnvMode } from "../composerDraftStore";
 
 export const LAST_INVOKED_SCRIPT_BY_PROJECT_KEY = "t3code:last-invoked-script-by-project";
 export const MAX_HIDDEN_MOUNTED_TERMINAL_THREADS = 10;
-const WORKTREE_BRANCH_PREFIX = "t3code";
 
 export const LastInvokedScriptByProjectSchema = Schema.Record(ProjectId, Schema.String);
 
@@ -157,10 +157,11 @@ export function readFileAsDataUrl(file: File): Promise<string> {
   });
 }
 
-export function buildTemporaryWorktreeBranchName(): string {
-  // Keep the 8-hex suffix shape for backend temporary-branch detection.
-  const token = randomUUID().slice(0, 8).toLowerCase();
-  return `${WORKTREE_BRANCH_PREFIX}/${token}`;
+export function resolveSendEnvMode(input: {
+  requestedEnvMode: DraftThreadEnvMode;
+  isGitRepo: boolean;
+}): DraftThreadEnvMode {
+  return input.isGitRepo ? input.requestedEnvMode : "local";
 }
 
 export function cloneComposerImageForRetry(
@@ -226,15 +227,39 @@ export function threadHasStarted(thread: Thread | null | undefined): boolean {
   );
 }
 
+// `threadProvider` is the open branded driver kind carried by the session.
+// Unknown driver kinds degrade to `null` (i.e. "unlocked"), which is the safe
+// rollback / fork behavior — the routing layer is the right place to surface
+// "driver not installed" errors, not the lock state.
+//
+// `selectedProvider` takes the same open-string shape because the composer
+// now tracks the picker selection as a `ProviderInstanceId` (e.g.
+// `codex_personal`). Custom instance ids that don't directly match a
+// registered driver resolve to `null` here, which matches the existing
+// "unknown driver -> unlocked" semantics. Callers that want the lock to track
+// a custom instance's underlying driver kind should resolve the instance id
+// upstream and pass the correlated kind.
 export function deriveLockedProvider(input: {
   thread: Thread | null | undefined;
-  selectedProvider: ProviderKind | null;
-  threadProvider: ProviderKind | null;
-}): ProviderKind | null {
+  selectedProvider: string | null;
+  threadProvider: string | null;
+}): ProviderDriverKind | null {
   if (!threadHasStarted(input.thread)) {
     return null;
   }
-  return input.thread?.session?.provider ?? input.threadProvider ?? input.selectedProvider ?? null;
+  const sessionProvider = input.thread?.session?.provider ?? null;
+  if (sessionProvider) {
+    return sessionProvider;
+  }
+  const narrowedThreadProvider =
+    input.threadProvider && isProviderDriverKind(input.threadProvider)
+      ? input.threadProvider
+      : null;
+  const narrowedSelectedProvider =
+    input.selectedProvider && isProviderDriverKind(input.selectedProvider)
+      ? input.selectedProvider
+      : null;
+  return narrowedThreadProvider ?? narrowedSelectedProvider ?? null;
 }
 
 export async function waitForStartedServerThread(
@@ -322,23 +347,37 @@ export function hasServerAcknowledgedLocalDispatch(input: {
   if (!input.localDispatch) {
     return false;
   }
-  if (
-    input.phase === "running" ||
-    input.hasPendingApproval ||
-    input.hasPendingUserInput ||
-    Boolean(input.threadError)
-  ) {
+  if (input.hasPendingApproval || input.hasPendingUserInput || Boolean(input.threadError)) {
     return true;
   }
 
   const latestTurn = input.latestTurn ?? null;
   const session = input.session ?? null;
-
-  return (
+  const latestTurnChanged =
     input.localDispatch.latestTurnTurnId !== (latestTurn?.turnId ?? null) ||
     input.localDispatch.latestTurnRequestedAt !== (latestTurn?.requestedAt ?? null) ||
     input.localDispatch.latestTurnStartedAt !== (latestTurn?.startedAt ?? null) ||
-    input.localDispatch.latestTurnCompletedAt !== (latestTurn?.completedAt ?? null) ||
+    input.localDispatch.latestTurnCompletedAt !== (latestTurn?.completedAt ?? null);
+
+  if (input.phase === "running") {
+    if (!latestTurnChanged) {
+      return false;
+    }
+    if (latestTurn?.startedAt === null || latestTurn === null) {
+      return false;
+    }
+    if (
+      session?.activeTurnId !== undefined &&
+      session.activeTurnId !== null &&
+      latestTurn?.turnId !== session.activeTurnId
+    ) {
+      return false;
+    }
+    return true;
+  }
+
+  return (
+    latestTurnChanged ||
     input.localDispatch.sessionOrchestrationStatus !== (session?.orchestrationStatus ?? null) ||
     input.localDispatch.sessionUpdatedAt !== (session?.updatedAt ?? null)
   );
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 7a5a2875ccc..d66d2487ce3 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -1,21 +1,23 @@
 import {
   type ApprovalRequestId,
-  DEFAULT_MODEL_BY_PROVIDER,
-  type ClaudeCodeEffort,
+  DEFAULT_MODEL,
+  defaultInstanceIdForDriver,
   type EnvironmentId,
   type MessageId,
   type ModelSelection,
   type ProjectScript,
-  type ProviderKind,
   type ProjectId,
   type ProviderApprovalDecision,
+  ProviderInstanceId,
   type ServerProvider,
+  type ResolvedKeybindingsConfig,
   type ScopedThreadRef,
   type ThreadId,
   type TurnId,
   type KeybindingCommand,
   OrchestrationThreadActivity,
   ProviderInteractionMode,
+  ProviderDriverKind,
   RuntimeMode,
   TerminalOpenInput,
 } from "@t3tools/contracts";
@@ -25,10 +27,15 @@ import {
   scopeProjectRef,
   scopeThreadRef,
 } from "@t3tools/client-runtime";
-import { applyClaudePromptEffortPrefix } from "@t3tools/shared/model";
+import {
+  applyClaudePromptEffortPrefix,
+  createModelSelection,
+  resolvePromptInjectedEffort,
+} from "@t3tools/shared/model";
 import { projectScriptCwd, projectScriptRuntimeEnv } from "@t3tools/shared/projectScripts";
 import { truncate } from "@t3tools/shared/String";
-import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Debouncer } from "@tanstack/react-pacer";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useNavigate, useSearch } from "@tanstack/react-router";
 import { useShallow } from "zustand/react/shallow";
 import { useGitStatus } from "~/lib/gitStatusState";
@@ -57,7 +64,7 @@ import {
   isLatestTurnSettled,
   formatElapsed,
 } from "../session-logic";
-import { isScrollContainerNearBottom } from "../chat-scroll";
+import { type LegendListRef } from "@legendapp/list/react";
 import {
   buildPendingUserInputAnswers,
   derivePendingUserInputProgress,
@@ -90,13 +97,16 @@ import {
 import { useTheme } from "../hooks/useTheme";
 import { useTurnDiffSummaries } from "../hooks/useTurnDiffSummaries";
 import { useCommandPaletteStore } from "../commandPaletteStore";
+import { buildTemporaryWorktreeBranchName } from "@t3tools/shared/git";
+import { useMediaQuery } from "../hooks/useMediaQuery";
+import { RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY } from "../rightPanelLayout";
 import { BranchToolbar } from "./BranchToolbar";
 import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings";
 import PlanSidebar from "./PlanSidebar";
 import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
-import { ChevronDownIcon } from "lucide-react";
+import { ChevronDownIcon, TriangleAlertIcon, WifiOffIcon } from "lucide-react";
 import { cn, randomUUID } from "~/lib/utils";
-import { toastManager } from "./ui/toast";
+import { stackedThreadToast, toastManager } from "./ui/toast";
 import { decodeProjectScriptKeybindingRule } from "~/lib/projectScriptKeybindings";
 import { type NewProjectScriptInput } from "./ProjectScriptsControl";
 import {
@@ -107,10 +117,14 @@ import {
 import { newCommandId, newDraftId, newMessageId, newThreadId } from "~/lib/utils";
 import { getProviderModelCapabilities, resolveSelectableProvider } from "../providerModels";
 import { useSettings } from "../hooks/useSettings";
-import { resolveAppModelSelection } from "../modelSelection";
+import { resolveAppModelSelectionForInstance } from "../modelSelection";
 import { isTerminalFocused } from "../lib/terminalFocus";
-import { deriveLogicalProjectKey } from "../logicalProject";
 import {
+  deriveLogicalProjectKeyFromSettings,
+  selectProjectGroupingSettings,
+} from "../logicalProject";
+import {
+  reconnectSavedEnvironment,
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
 } from "../environments/runtime";
@@ -138,11 +152,11 @@ import { NoActiveThreadState } from "./NoActiveThreadState";
 import { resolveEffectiveEnvMode, resolveEnvironmentOptionLabel } from "./BranchToolbar.logic";
 import { ProviderStatusBanner } from "./chat/ProviderStatusBanner";
 import { ThreadErrorBanner } from "./chat/ThreadErrorBanner";
+import { ComposerBannerStack, type ComposerBannerStackItem } from "./chat/ComposerBannerStack";
 import {
   MAX_HIDDEN_MOUNTED_TERMINAL_THREADS,
   buildExpiredTerminalContextToastCopy,
   buildLocalDraftThread,
-  buildTemporaryWorktreeBranchName,
   collectUserMessageBlobPreviewUrls,
   createLocalDispatchSnapshot,
   deriveComposerSendState,
@@ -155,6 +169,7 @@ import {
   deriveLockedProvider,
   readFileAsDataUrl,
   reconcileMountedTerminalThreadIds,
+  resolveSendEnvMode,
   revokeBlobPreviewUrl,
   revokeUserMessagePreviewUrls,
   shouldWriteThreadErrorToCurrentServerThread,
@@ -168,14 +183,28 @@ import {
   useServerKeybindings,
 } from "~/rpc/serverState";
 import { sanitizeThreadErrorMessage } from "~/rpc/transportError";
+import { retainThreadDetailSubscription } from "../environments/runtime/service";
+import { RightPanelSheet } from "./RightPanelSheet";
+import { Button } from "./ui/button";
+import {
+  buildVersionMismatchDismissalKey,
+  dismissVersionMismatch,
+  isVersionMismatchDismissed,
+  resolveServerConfigVersionMismatch,
+} from "../versionSkew";
 
 const IMAGE_ONLY_BOOTSTRAP_PROMPT =
   "[User attached one or more images without additional text. Respond using the conversation context and the attached image(s).]";
 const EMPTY_ACTIVITIES: OrchestrationThreadActivity[] = [];
 const EMPTY_PROPOSED_PLANS: Thread["proposedPlans"] = [];
 const EMPTY_PROVIDERS: ServerProvider[] = [];
-const EMPTY_CHANGED_FILES_EXPANDED_BY_TURN_ID: Record<string, boolean> = {};
+const EMPTY_PROVIDER_SKILLS: ServerProvider["skills"] = [];
 const EMPTY_PENDING_USER_INPUT_ANSWERS: Record<string, PendingUserInputDraftAnswer> = {};
+type EnvironmentUnavailableState = {
+  readonly environmentId: EnvironmentId;
+  readonly label: string;
+  readonly connectionState: "connecting" | "disconnected" | "error";
+};
 
 type ThreadPlanCatalogEntry = Pick<Thread, "id" | "proposedPlans">;
 
@@ -293,17 +322,15 @@ function useThreadPlanCatalog(threadIds: readonly ThreadId[]): ThreadPlanCatalog
 }
 
 function formatOutgoingPrompt(params: {
-  provider: ProviderKind;
+  provider: ProviderDriverKind;
   model: string | null;
   models: ReadonlyArray<ServerProvider["models"][number]>;
   effort: string | null;
   text: string;
 }): string {
   const caps = getProviderModelCapabilities(params.models, params.model, params.provider);
-  if (params.effort && caps.promptInjectedEffortLevels.includes(params.effort)) {
-    return applyClaudePromptEffortPrefix(params.text, params.effort as ClaudeCodeEffort | null);
-  }
-  return params.text;
+  const promptEffort = resolvePromptInjectedEffort(caps, params.effort);
+  return applyClaudePromptEffortPrefix(params.text, promptEffort);
 }
 const SCRIPT_TERMINAL_COLS = 120;
 const SCRIPT_TERMINAL_ROWS = 30;
@@ -313,6 +340,7 @@ type ChatViewProps =
       environmentId: EnvironmentId;
       threadId: ThreadId;
       onDiffPanelOpen?: () => void;
+      reserveTitleBarControlInset?: boolean;
       routeKind: "server";
       draftId?: never;
     }
@@ -320,6 +348,7 @@ type ChatViewProps =
       environmentId: EnvironmentId;
       threadId: ThreadId;
       onDiffPanelOpen?: () => void;
+      reserveTitleBarControlInset?: boolean;
       routeKind: "draft";
       draftId: DraftId;
     };
@@ -408,6 +437,7 @@ interface PersistentThreadTerminalDrawerProps {
   splitShortcutLabel: string | undefined;
   newShortcutLabel: string | undefined;
   closeShortcutLabel: string | undefined;
+  keybindings: ResolvedKeybindingsConfig;
   onAddTerminalContext: (selection: TerminalContextSelection) => void;
 }
 
@@ -420,6 +450,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
   splitShortcutLabel,
   newShortcutLabel,
   closeShortcutLabel,
+  keybindings,
   onAddTerminalContext,
 }: PersistentThreadTerminalDrawerProps) {
   const serverThread = useStore(useMemo(() => createThreadSelectorByRef(threadRef), [threadRef]));
@@ -563,6 +594,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
         splitShortcutLabel={visible ? splitShortcutLabel : undefined}
         newShortcutLabel={visible ? newShortcutLabel : undefined}
         closeShortcutLabel={visible ? closeShortcutLabel : undefined}
+        keybindings={keybindings}
         onActiveTerminalChange={activateTerminal}
         onCloseTerminal={closeTerminal}
         onHeightChange={setTerminalHeight}
@@ -573,7 +605,13 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
 });
 
 export default function ChatView(props: ChatViewProps) {
-  const { environmentId, threadId, routeKind, onDiffPanelOpen } = props;
+  const {
+    environmentId,
+    threadId,
+    routeKind,
+    onDiffPanelOpen,
+    reserveTitleBarControlInset = true,
+  } = props;
   const draftId = routeKind === "draft" ? props.draftId : null;
   const routeThreadRef = useMemo(
     () => scopeThreadRef(environmentId, threadId),
@@ -590,23 +628,15 @@ export default function ChatView(props: ChatViewProps) {
   );
   const setStoreThreadError = useStore((store) => store.setError);
   const markThreadVisited = useUiStateStore((store) => store.markThreadVisited);
-  const setThreadChangedFilesExpanded = useUiStateStore(
-    (store) => store.setThreadChangedFilesExpanded,
-  );
   const activeThreadLastVisitedAt = useUiStateStore((store) =>
     routeKind === "server" ? store.threadLastVisitedAtById[routeThreadKey] : undefined,
   );
-  const changedFilesExpandedByTurnId = useUiStateStore((store) =>
-    routeKind === "server"
-      ? (store.threadChangedFilesExpandedById[routeThreadKey] ??
-        EMPTY_CHANGED_FILES_EXPANDED_BY_TURN_ID)
-      : EMPTY_CHANGED_FILES_EXPANDED_BY_TURN_ID,
-  );
   const settings = useSettings();
   const setStickyComposerModelSelection = useComposerDraftStore(
     (store) => store.setStickyModelSelection,
   );
   const timestampFormat = settings.timestampFormat;
+  const autoOpenPlanSidebar = settings.autoOpenPlanSidebar;
   const navigate = useNavigate();
   const rawSearch = useSearch({
     strict: false,
@@ -673,14 +703,13 @@ export default function ChatView(props: ChatViewProps) {
   >({});
   const [pendingUserInputQuestionIndexByRequestId, setPendingUserInputQuestionIndexByRequestId] =
     useState<Record<string, number>>({});
-  const [expandedWorkGroups, setExpandedWorkGroups] = useState<Record<string, boolean>>({});
   const [planSidebarOpen, setPlanSidebarOpen] = useState(false);
+  const shouldUsePlanSidebarSheet = useMediaQuery(RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY);
   // Tracks whether the user explicitly dismissed the sidebar for the active turn.
   const planSidebarDismissedForTurnRef = useRef<string | null>(null);
   // When set, the thread-change reset effect will open the sidebar instead of closing it.
   // Used by "Implement in a new thread" to carry the sidebar-open intent across navigation.
   const planSidebarOpenOnNextThreadRef = useRef(false);
-  const [nowTick, setNowTick] = useState(() => Date.now());
   const [terminalFocusRequestId, setTerminalFocusRequestId] = useState(0);
   const [pullRequestDialogState, setPullRequestDialogState] =
     useState<PullRequestDialogState | null>(null);
@@ -690,32 +719,20 @@ export default function ChatView(props: ChatViewProps) {
   const [attachmentPreviewHandoffByMessageId, setAttachmentPreviewHandoffByMessageId] = useState<
     Record<string, string[]>
   >({});
+  const [pendingServerThreadEnvMode, setPendingServerThreadEnvMode] =
+    useState<DraftThreadEnvMode | null>(null);
+  const [pendingServerThreadBranch, setPendingServerThreadBranch] = useState<string | null>();
   const [lastInvokedScriptByProjectId, setLastInvokedScriptByProjectId] = useLocalStorage(
     LAST_INVOKED_SCRIPT_BY_PROJECT_KEY,
     {},
     LastInvokedScriptByProjectSchema,
   );
-  const messagesScrollRef = useRef<HTMLDivElement>(null);
-  const [messagesScrollElement, setMessagesScrollElement] = useState<HTMLDivElement | null>(null);
-  const shouldAutoScrollRef = useRef(true);
-  const lastKnownScrollTopRef = useRef(0);
-  const isPointerScrollActiveRef = useRef(false);
-  const lastTouchClientYRef = useRef<number | null>(null);
-  const pendingUserScrollUpIntentRef = useRef(false);
-  const pendingAutoScrollFrameRef = useRef<number | null>(null);
-  const pendingInteractionAnchorRef = useRef<{
-    element: HTMLElement;
-    top: number;
-  } | null>(null);
-  const pendingInteractionAnchorFrameRef = useRef<number | null>(null);
+  const legendListRef = useRef<LegendListRef | null>(null);
+  const isAtEndRef = useRef(true);
   const attachmentPreviewHandoffByMessageIdRef = useRef<Record<string, string[]>>({});
   const attachmentPreviewPromotionInFlightByMessageIdRef = useRef<Record<string, true>>({});
   const sendInFlightRef = useRef(false);
   const terminalOpenByThreadRef = useRef<Record<string, boolean>>({});
-  const setMessagesScrollContainerRef = useCallback((element: HTMLDivElement | null) => {
-    messagesScrollRef.current = element;
-    setMessagesScrollElement(element);
-  }, []);
 
   const terminalState = useTerminalStateStore((state) =>
     selectThreadTerminalState(state.terminalStateByThreadKey, routeThreadRef),
@@ -780,8 +797,8 @@ export default function ChatView(props: ChatViewProps) {
             threadId,
             draftThread,
             fallbackDraftProject?.defaultModelSelection ?? {
-              provider: "codex",
-              model: DEFAULT_MODEL_BY_PROVIDER.codex,
+              instanceId: ProviderInstanceId.make("codex"),
+              model: DEFAULT_MODEL,
             },
             localDraftError,
           )
@@ -843,16 +860,98 @@ export default function ChatView(props: ChatViewProps) {
     useMemo(() => createProjectSelectorByRef(activeProjectRef), [activeProjectRef]),
   );
 
+  useEffect(() => {
+    if (routeKind !== "server") {
+      return;
+    }
+    return retainThreadDetailSubscription(environmentId, threadId);
+  }, [environmentId, routeKind, threadId]);
+
   // Compute the list of environments this logical project spans, used to
   // drive the environment picker in BranchToolbar.
   const allProjects = useStore(useShallow(selectProjectsAcrossEnvironments));
   const primaryEnvironmentId = usePrimaryEnvironmentId();
   const savedEnvironmentRegistry = useSavedEnvironmentRegistryStore((s) => s.byId);
   const savedEnvironmentRuntimeById = useSavedEnvironmentRuntimeStore((s) => s.byId);
+  const activeSavedEnvironmentRecord =
+    activeThread && activeThread.environmentId !== primaryEnvironmentId
+      ? (savedEnvironmentRegistry[activeThread.environmentId] ?? null)
+      : null;
+  const activeSavedEnvironmentRuntime = activeSavedEnvironmentRecord
+    ? (savedEnvironmentRuntimeById[activeSavedEnvironmentRecord.environmentId] ?? null)
+    : null;
+  const activeSavedEnvironmentConnectionState = activeSavedEnvironmentRecord
+    ? (activeSavedEnvironmentRuntime?.connectionState ?? "disconnected")
+    : "connected";
+  const activeEnvironmentUnavailable =
+    activeSavedEnvironmentRecord !== null && activeSavedEnvironmentConnectionState !== "connected";
+  const activeSavedEnvironmentId = activeSavedEnvironmentRecord?.environmentId ?? null;
+  const activeEnvironmentUnavailableLabel = activeSavedEnvironmentRecord
+    ? resolveEnvironmentOptionLabel({
+        isPrimary: false,
+        environmentId: activeSavedEnvironmentRecord.environmentId,
+        runtimeLabel: activeSavedEnvironmentRuntime?.descriptor?.label ?? null,
+        savedLabel: activeSavedEnvironmentRecord.label,
+      })
+    : null;
+  const activeEnvironmentUnavailableState = useMemo<EnvironmentUnavailableState | null>(() => {
+    if (
+      !activeEnvironmentUnavailable ||
+      !activeEnvironmentUnavailableLabel ||
+      !activeSavedEnvironmentId
+    ) {
+      return null;
+    }
+
+    return {
+      environmentId: activeSavedEnvironmentId,
+      label: activeEnvironmentUnavailableLabel,
+      connectionState:
+        activeSavedEnvironmentConnectionState === "connecting" ||
+        activeSavedEnvironmentConnectionState === "error"
+          ? activeSavedEnvironmentConnectionState
+          : "disconnected",
+    };
+  }, [
+    activeEnvironmentUnavailable,
+    activeEnvironmentUnavailableLabel,
+    activeSavedEnvironmentConnectionState,
+    activeSavedEnvironmentId,
+  ]);
+  const [reconnectingEnvironmentId, setReconnectingEnvironmentId] = useState<EnvironmentId | null>(
+    null,
+  );
+  const handleReconnectActiveEnvironment = useCallback(
+    async (environmentId: EnvironmentId, label: string) => {
+      setReconnectingEnvironmentId(environmentId);
+      try {
+        await reconnectSavedEnvironment(environmentId);
+        toastManager.add({
+          type: "success",
+          title: "Environment reconnected",
+          description: `${label} is ready.`,
+        });
+      } catch (error) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not reconnect environment",
+            description: error instanceof Error ? error.message : "Failed to reconnect.",
+          }),
+        );
+      } finally {
+        setReconnectingEnvironmentId(null);
+      }
+    },
+    [],
+  );
+  const projectGroupingSettings = useSettings(selectProjectGroupingSettings);
   const logicalProjectEnvironments = useMemo(() => {
     if (!activeProject) return [];
-    const logicalKey = deriveLogicalProjectKey(activeProject);
-    const memberProjects = allProjects.filter((p) => deriveLogicalProjectKey(p) === logicalKey);
+    const logicalKey = deriveLogicalProjectKeyFromSettings(activeProject, projectGroupingSettings);
+    const memberProjects = allProjects.filter(
+      (p) => deriveLogicalProjectKeyFromSettings(p, projectGroupingSettings) === logicalKey,
+    );
     const seen = new Set<string>();
     const envs: Array<{
       environmentId: EnvironmentId;
@@ -888,6 +987,7 @@ export default function ChatView(props: ChatViewProps) {
   }, [
     activeProject,
     allProjects,
+    projectGroupingSettings,
     primaryEnvironmentId,
     savedEnvironmentRegistry,
     savedEnvironmentRuntimeById,
@@ -917,7 +1017,10 @@ export default function ChatView(props: ChatViewProps) {
         throw new Error("No active project is available for this pull request.");
       }
       const activeProjectRef = scopeProjectRef(activeProject.environmentId, activeProject.id);
-      const logicalProjectKey = deriveLogicalProjectKey(activeProject);
+      const logicalProjectKey = deriveLogicalProjectKeyFromSettings(
+        activeProject,
+        projectGroupingSettings,
+      );
       const storedDraftSession = getDraftSessionByLogicalProjectKey(logicalProjectKey);
       if (storedDraftSession) {
         setDraftThreadContext(storedDraftSession.draftId, input);
@@ -978,6 +1081,7 @@ export default function ChatView(props: ChatViewProps) {
       getDraftSessionByLogicalProjectKey,
       isServerThread,
       navigate,
+      projectGroupingSettings,
       routeKind,
       setDraftThreadContext,
       setLogicalProjectDraftThreadId,
@@ -995,16 +1099,6 @@ export default function ChatView(props: ChatViewProps) {
     [openOrReuseProjectDraftThread],
   );
 
-  const handleSetChangedFilesExpanded = useCallback(
-    (turnId: TurnId, expanded: boolean) => {
-      if (routeKind !== "server") {
-        return;
-      }
-      setThreadChangedFilesExpanded(routeThreadKey, turnId, expanded);
-    },
-    [routeKind, routeThreadKey, setThreadChangedFilesExpanded],
-  );
-
   useEffect(() => {
     if (!serverThread?.id) return;
     if (!latestTurnSettled) return;
@@ -1014,7 +1108,10 @@ export default function ChatView(props: ChatViewProps) {
     const lastVisitedAt = activeThreadLastVisitedAt ? Date.parse(activeThreadLastVisitedAt) : NaN;
     if (!Number.isNaN(lastVisitedAt) && lastVisitedAt >= turnCompletedAt) return;
 
-    markThreadVisited(scopedThreadKey(scopeThreadRef(serverThread.environmentId, serverThread.id)));
+    markThreadVisited(
+      scopedThreadKey(scopeThreadRef(serverThread.environmentId, serverThread.id)),
+      activeLatestTurn.completedAt,
+    );
   }, [
     activeLatestTurn?.completedAt,
     activeThreadLastVisitedAt,
@@ -1026,7 +1123,9 @@ export default function ChatView(props: ChatViewProps) {
 
   const selectedProviderByThreadId = composerActiveProvider ?? null;
   const threadProvider =
-    activeThread?.modelSelection.provider ?? activeProject?.defaultModelSelection?.provider ?? null;
+    activeThread?.modelSelection.instanceId ??
+    activeProject?.defaultModelSelection?.instanceId ??
+    null;
   const lockedProvider = deriveLockedProvider({
     thread: activeThread,
     selectedProvider: selectedProviderByThreadId,
@@ -1043,12 +1142,126 @@ export default function ChatView(props: ChatViewProps) {
     primaryEnvironmentId && activeThread?.environmentId === primaryEnvironmentId
       ? primaryServerConfig
       : (activeEnvRuntimeState?.serverConfig ?? primaryServerConfig);
+  const versionMismatch = resolveServerConfigVersionMismatch(serverConfig);
+  const versionMismatchDismissKey =
+    versionMismatch && activeThread
+      ? buildVersionMismatchDismissalKey(activeThread.environmentId, versionMismatch)
+      : null;
+  const [dismissedVersionMismatchKey, setDismissedVersionMismatchKey] = useState<string | null>(
+    null,
+  );
+  const versionMismatchDismissed =
+    versionMismatchDismissKey === dismissedVersionMismatchKey ||
+    isVersionMismatchDismissed(versionMismatchDismissKey);
+  const showVersionMismatchBanner =
+    versionMismatch !== null && versionMismatchDismissKey !== null && !versionMismatchDismissed;
+  const hasMultipleRegisteredEnvironments = Object.keys(savedEnvironmentRegistry).length > 0;
+  const versionMismatchServerLabel = useMemo(() => {
+    if (!hasMultipleRegisteredEnvironments || !activeThread) {
+      return "server";
+    }
+
+    const isPrimary = activeThread.environmentId === primaryEnvironmentId;
+    const savedRecord = savedEnvironmentRegistry[activeThread.environmentId];
+    const runtimeState = savedEnvironmentRuntimeById[activeThread.environmentId];
+    return `${resolveEnvironmentOptionLabel({
+      isPrimary,
+      environmentId: activeThread.environmentId,
+      runtimeLabel: runtimeState?.descriptor?.label ?? serverConfig?.environment.label ?? null,
+      savedLabel: savedRecord?.label ?? null,
+    })} server`;
+  }, [
+    activeThread,
+    hasMultipleRegisteredEnvironments,
+    primaryEnvironmentId,
+    savedEnvironmentRegistry,
+    savedEnvironmentRuntimeById,
+    serverConfig?.environment.label,
+  ]);
+  const composerBannerItems = useMemo<ComposerBannerStackItem[]>(() => {
+    const items: ComposerBannerStackItem[] = [];
+    if (activeEnvironmentUnavailableState) {
+      items.push({
+        id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
+        variant:
+          activeEnvironmentUnavailableState.connectionState === "error" ? "error" : "warning",
+        icon: <WifiOffIcon />,
+        title: (
+          <>
+            {activeEnvironmentUnavailableState.label} is{" "}
+            {activeEnvironmentUnavailableState.connectionState === "connecting"
+              ? "connecting"
+              : "disconnected"}
+          </>
+        ),
+        description: "Reconnect this environment before sending messages or running actions.",
+        actions: (
+          <>
+            <Button
+              size="xs"
+              disabled={
+                activeEnvironmentUnavailableState.connectionState === "connecting" ||
+                reconnectingEnvironmentId === activeEnvironmentUnavailableState.environmentId
+              }
+              onClick={() =>
+                void handleReconnectActiveEnvironment(
+                  activeEnvironmentUnavailableState.environmentId,
+                  activeEnvironmentUnavailableState.label,
+                )
+              }
+            >
+              {activeEnvironmentUnavailableState.connectionState === "connecting" ||
+              reconnectingEnvironmentId === activeEnvironmentUnavailableState.environmentId
+                ? "Reconnecting..."
+                : "Reconnect"}
+            </Button>
+            <Button
+              size="xs"
+              variant="outline"
+              onClick={() => void navigate({ to: "/settings/connections" })}
+            >
+              Connections
+            </Button>
+          </>
+        ),
+      });
+    }
+    if (showVersionMismatchBanner && versionMismatch && versionMismatchDismissKey) {
+      items.push({
+        id: `version-mismatch:${versionMismatchDismissKey}`,
+        variant: "warning",
+        icon: <TriangleAlertIcon />,
+        title: "Client and server versions differ",
+        description: (
+          <>
+            Client {versionMismatch.clientVersion} is connected to {versionMismatchServerLabel}{" "}
+            {versionMismatch.serverVersion}. Sync them if RPC calls or reconnects fail.
+          </>
+        ),
+        dismissLabel: "Dismiss version mismatch warning",
+        onDismiss: () => {
+          dismissVersionMismatch(versionMismatchDismissKey);
+          setDismissedVersionMismatchKey(versionMismatchDismissKey);
+        },
+      });
+    }
+    return items;
+  }, [
+    activeEnvironmentUnavailableState,
+    handleReconnectActiveEnvironment,
+    navigate,
+    reconnectingEnvironmentId,
+    showVersionMismatchBanner,
+    versionMismatch,
+    versionMismatchDismissKey,
+    versionMismatchServerLabel,
+  ]);
   const providerStatuses = serverConfig?.providers ?? EMPTY_PROVIDERS;
   const unlockedSelectedProvider = resolveSelectableProvider(
     providerStatuses,
-    selectedProviderByThreadId ?? threadProvider ?? "codex",
+    selectedProviderByThreadId ?? threadProvider ?? ProviderDriverKind.make("codex"),
   );
-  const selectedProvider: ProviderKind = lockedProvider ?? unlockedSelectedProvider;
+  const selectedProvider: ProviderDriverKind = lockedProvider ?? unlockedSelectedProvider;
   const phase = derivePhase(activeThread?.session ?? null);
   const threadActivities = activeThread?.activities ?? EMPTY_ACTIVITIES;
   const workLogEntries = useMemo(
@@ -1123,6 +1336,7 @@ export default function ChatView(props: ChatViewProps) {
     () => deriveActivePlanState(threadActivities, activeLatestTurn?.turnId ?? undefined),
     [activeLatestTurn?.turnId, threadActivities],
   );
+  const planSidebarLabel = sidebarProposedPlan || interactionMode === "plan" ? "Plan" : "Tasks";
   const showPlanFollowUpPrompt =
     pendingUserInputs.length === 0 &&
     interactionMode === "plan" &&
@@ -1144,7 +1358,6 @@ export default function ChatView(props: ChatViewProps) {
     threadError: activeThread?.error,
   });
   const isWorking = phase === "running" || isSendBusy || isConnecting || isRevertingCheckpoint;
-  const nowIso = new Date(nowTick).toISOString();
   const activeWorkStartedAt = deriveActiveWorkStartedAt(
     activeLatestTurn,
     activeThread?.session ?? null,
@@ -1420,10 +1633,24 @@ export default function ChatView(props: ChatViewProps) {
   const gitStatusQuery = useGitStatus({ environmentId, cwd: gitCwd });
   const keybindings = useServerKeybindings();
   const availableEditors = useServerAvailableEditors();
-  const activeProviderStatus = useMemo(
-    () => providerStatuses.find((status) => status.provider === selectedProvider) ?? null,
-    [selectedProvider, providerStatuses],
-  );
+  // Prefer an instance-id match so a custom Codex instance (e.g.
+  // `codex_personal`) surfaces its own status/message in the banner rather
+  // than the default Codex's. Falls back to first-match-by-kind when no
+  // saved instance id is available or the instance no longer exists.
+  const activeProviderInstanceId =
+    activeThread?.session?.providerInstanceId ??
+    activeThread?.modelSelection.instanceId ??
+    activeProject?.defaultModelSelection?.instanceId ??
+    null;
+  const activeProviderStatus = useMemo(() => {
+    if (activeProviderInstanceId) {
+      return (
+        providerStatuses.find((status) => status.instanceId === activeProviderInstanceId) ?? null
+      );
+    }
+    const defaultInstanceId = defaultInstanceIdForDriver(selectedProvider);
+    return providerStatuses.find((status) => status.instanceId === defaultInstanceId) ?? null;
+  }, [activeProviderInstanceId, providerStatuses, selectedProvider]);
   const activeProjectCwd = activeProject?.cwd ?? null;
   const activeThreadWorktreePath = activeThread?.worktreePath ?? null;
   const activeWorkspaceRoot = activeThreadWorktreePath ?? activeProjectCwd ?? undefined;
@@ -1852,11 +2079,13 @@ export default function ChatView(props: ChatViewProps) {
           title: `Deleted action "${deletedName ?? "Unknown"}"`,
         });
       } catch (error) {
-        toastManager.add({
-          type: "error",
-          title: "Could not delete action",
-          description: error instanceof Error ? error.message : "An unexpected error occurred.",
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not delete action",
+            description: error instanceof Error ? error.message : "An unexpected error occurred.",
+          }),
+        );
       }
     },
     [activeProject, persistProjectScripts],
@@ -1905,16 +2134,19 @@ export default function ChatView(props: ChatViewProps) {
   const togglePlanSidebar = useCallback(() => {
     setPlanSidebarOpen((open) => {
       if (open) {
-        const turnKey = activePlan?.turnId ?? sidebarProposedPlan?.turnId ?? null;
-        if (turnKey) {
-          planSidebarDismissedForTurnRef.current = turnKey;
-        }
+        planSidebarDismissedForTurnRef.current =
+          activePlan?.turnId ?? sidebarProposedPlan?.turnId ?? "__dismissed__";
       } else {
         planSidebarDismissedForTurnRef.current = null;
       }
       return !open;
     });
   }, [activePlan?.turnId, sidebarProposedPlan?.turnId]);
+  const closePlanSidebar = useCallback(() => {
+    setPlanSidebarOpen(false);
+    planSidebarDismissedForTurnRef.current =
+      activePlan?.turnId ?? sidebarProposedPlan?.turnId ?? "__dismissed__";
+  }, [activePlan?.turnId, sidebarProposedPlan?.turnId]);
 
   const persistThreadSettingsForNextTurn = useCallback(
     async (input: {
@@ -1935,7 +2167,7 @@ export default function ChatView(props: ChatViewProps) {
       if (
         input.modelSelection !== undefined &&
         (input.modelSelection.model !== serverThread.modelSelection.model ||
-          input.modelSelection.provider !== serverThread.modelSelection.provider ||
+          input.modelSelection.instanceId !== serverThread.modelSelection.instanceId ||
           JSON.stringify(input.modelSelection.options ?? null) !==
             JSON.stringify(serverThread.modelSelection.options ?? null))
       ) {
@@ -1970,178 +2202,62 @@ export default function ChatView(props: ChatViewProps) {
     [environmentId, serverThread],
   );
 
-  // Auto-scroll on new messages
-  const messageCount = timelineMessages.length;
-  const scrollMessagesToBottom = useCallback((behavior: ScrollBehavior = "auto") => {
-    const scrollContainer = messagesScrollRef.current;
-    if (!scrollContainer) return;
-    scrollContainer.scrollTo({ top: scrollContainer.scrollHeight, behavior });
-    lastKnownScrollTopRef.current = scrollContainer.scrollTop;
-    shouldAutoScrollRef.current = true;
-  }, []);
-  const cancelPendingStickToBottom = useCallback(() => {
-    const pendingFrame = pendingAutoScrollFrameRef.current;
-    if (pendingFrame === null) return;
-    pendingAutoScrollFrameRef.current = null;
-    window.cancelAnimationFrame(pendingFrame);
+  // Scroll helpers — LegendList handles auto-scroll via maintainScrollAtEnd.
+  const scrollToEnd = useCallback((animated = false) => {
+    legendListRef.current?.scrollToEnd?.({ animated });
   }, []);
-  const cancelPendingInteractionAnchorAdjustment = useCallback(() => {
-    const pendingFrame = pendingInteractionAnchorFrameRef.current;
-    if (pendingFrame === null) return;
-    pendingInteractionAnchorFrameRef.current = null;
-    window.cancelAnimationFrame(pendingFrame);
-  }, []);
-  const scheduleStickToBottom = useCallback(() => {
-    if (pendingAutoScrollFrameRef.current !== null) return;
-    pendingAutoScrollFrameRef.current = window.requestAnimationFrame(() => {
-      pendingAutoScrollFrameRef.current = null;
-      scrollMessagesToBottom();
-    });
-  }, [scrollMessagesToBottom]);
-  const onMessagesClickCapture = useCallback(
-    (event: React.MouseEvent<HTMLDivElement>) => {
-      const scrollContainer = messagesScrollRef.current;
-      if (!scrollContainer || !(event.target instanceof Element)) return;
-
-      const trigger = event.target.closest<HTMLElement>(
-        "button, summary, [role='button'], [data-scroll-anchor-target]",
-      );
-      if (!trigger || !scrollContainer.contains(trigger)) return;
-      if (trigger.closest("[data-scroll-anchor-ignore]")) return;
-
-      pendingInteractionAnchorRef.current = {
-        element: trigger,
-        top: trigger.getBoundingClientRect().top,
-      };
 
-      cancelPendingInteractionAnchorAdjustment();
-      pendingInteractionAnchorFrameRef.current = window.requestAnimationFrame(() => {
-        pendingInteractionAnchorFrameRef.current = null;
-        const anchor = pendingInteractionAnchorRef.current;
-        pendingInteractionAnchorRef.current = null;
-        const activeScrollContainer = messagesScrollRef.current;
-        if (!anchor || !activeScrollContainer) return;
-        if (!anchor.element.isConnected || !activeScrollContainer.contains(anchor.element)) return;
-
-        const nextTop = anchor.element.getBoundingClientRect().top;
-        const delta = nextTop - anchor.top;
-        if (Math.abs(delta) < 0.5) return;
-
-        activeScrollContainer.scrollTop += delta;
-        lastKnownScrollTopRef.current = activeScrollContainer.scrollTop;
-      });
-    },
-    [cancelPendingInteractionAnchorAdjustment],
-  );
-  const forceStickToBottom = useCallback(() => {
-    cancelPendingStickToBottom();
-    scrollMessagesToBottom();
-    scheduleStickToBottom();
-  }, [cancelPendingStickToBottom, scheduleStickToBottom, scrollMessagesToBottom]);
-  const onMessagesScroll = useCallback(() => {
-    const scrollContainer = messagesScrollRef.current;
-    if (!scrollContainer) return;
-    const currentScrollTop = scrollContainer.scrollTop;
-    const isNearBottom = isScrollContainerNearBottom(scrollContainer);
-
-    if (!shouldAutoScrollRef.current && isNearBottom) {
-      shouldAutoScrollRef.current = true;
-      pendingUserScrollUpIntentRef.current = false;
-    } else if (shouldAutoScrollRef.current && pendingUserScrollUpIntentRef.current) {
-      const scrolledUp = currentScrollTop < lastKnownScrollTopRef.current - 1;
-      if (scrolledUp && !isNearBottom) {
-        shouldAutoScrollRef.current = false;
-      }
-      pendingUserScrollUpIntentRef.current = false;
-    } else if (shouldAutoScrollRef.current && isPointerScrollActiveRef.current) {
-      const scrolledUp = currentScrollTop < lastKnownScrollTopRef.current - 1;
-      if (scrolledUp && !isNearBottom) {
-        shouldAutoScrollRef.current = false;
-      }
-    } else if (shouldAutoScrollRef.current && !isNearBottom) {
-      // Catch-all for keyboard/assistive scroll interactions.
-      const scrolledUp = currentScrollTop < lastKnownScrollTopRef.current - 1;
-      if (scrolledUp) {
-        shouldAutoScrollRef.current = false;
-      }
-    }
-
-    setShowScrollToBottom(!shouldAutoScrollRef.current);
-    lastKnownScrollTopRef.current = currentScrollTop;
-  }, []);
-  const onMessagesWheel = useCallback((event: React.WheelEvent<HTMLDivElement>) => {
-    if (event.deltaY < 0) {
-      pendingUserScrollUpIntentRef.current = true;
-    }
-  }, []);
-  const onMessagesPointerDown = useCallback((_event: React.PointerEvent<HTMLDivElement>) => {
-    isPointerScrollActiveRef.current = true;
-  }, []);
-  const onMessagesPointerUp = useCallback((_event: React.PointerEvent<HTMLDivElement>) => {
-    isPointerScrollActiveRef.current = false;
-  }, []);
-  const onMessagesPointerCancel = useCallback((_event: React.PointerEvent<HTMLDivElement>) => {
-    isPointerScrollActiveRef.current = false;
-  }, []);
-  const onMessagesTouchStart = useCallback((event: React.TouchEvent<HTMLDivElement>) => {
-    const touch = event.touches[0];
-    if (!touch) return;
-    lastTouchClientYRef.current = touch.clientY;
-  }, []);
-  const onMessagesTouchMove = useCallback((event: React.TouchEvent<HTMLDivElement>) => {
-    const touch = event.touches[0];
-    if (!touch) return;
-    const previousTouchY = lastTouchClientYRef.current;
-    if (previousTouchY !== null && touch.clientY > previousTouchY + 1) {
-      pendingUserScrollUpIntentRef.current = true;
+  // Debounce *showing* the scroll-to-bottom pill so it doesn't flash during
+  // thread switches.  LegendList fires scroll events with isAtEnd=false while
+  // initialScrollAtEnd is settling; hiding is always immediate.
+  const showScrollDebouncer = useRef(
+    new Debouncer(() => setShowScrollToBottom(true), { wait: 150 }),
+  );
+  const onIsAtEndChange = useCallback((isAtEnd: boolean) => {
+    if (isAtEndRef.current === isAtEnd) return;
+    isAtEndRef.current = isAtEnd;
+    if (isAtEnd) {
+      showScrollDebouncer.current.cancel();
+      setShowScrollToBottom(false);
+    } else {
+      showScrollDebouncer.current.maybeExecute();
     }
-    lastTouchClientYRef.current = touch.clientY;
-  }, []);
-  const onMessagesTouchEnd = useCallback((_event: React.TouchEvent<HTMLDivElement>) => {
-    lastTouchClientYRef.current = null;
   }, []);
-  useEffect(() => {
-    return () => {
-      cancelPendingStickToBottom();
-      cancelPendingInteractionAnchorAdjustment();
-    };
-  }, [cancelPendingInteractionAnchorAdjustment, cancelPendingStickToBottom]);
-  useLayoutEffect(() => {
-    if (!activeThread?.id) return;
-    shouldAutoScrollRef.current = true;
-    scheduleStickToBottom();
-    const timeout = window.setTimeout(() => {
-      const scrollContainer = messagesScrollRef.current;
-      if (!scrollContainer) return;
-      if (isScrollContainerNearBottom(scrollContainer)) return;
-      scheduleStickToBottom();
-    }, 96);
-    return () => {
-      window.clearTimeout(timeout);
-    };
-  }, [activeThread?.id, scheduleStickToBottom]);
-  useEffect(() => {
-    if (!shouldAutoScrollRef.current) return;
-    scheduleStickToBottom();
-  }, [messageCount, scheduleStickToBottom]);
-  useEffect(() => {
-    if (phase !== "running") return;
-    if (!shouldAutoScrollRef.current) return;
-    scheduleStickToBottom();
-  }, [phase, scheduleStickToBottom, timelineEntries]);
 
   useEffect(() => {
-    setExpandedWorkGroups({});
     setPullRequestDialogState(null);
+    isAtEndRef.current = true;
+    showScrollDebouncer.current.cancel();
+    setShowScrollToBottom(false);
     if (planSidebarOpenOnNextThreadRef.current) {
       planSidebarOpenOnNextThreadRef.current = false;
       setPlanSidebarOpen(true);
     } else {
+      planSidebarOpenOnNextThreadRef.current = false;
       setPlanSidebarOpen(false);
     }
     planSidebarDismissedForTurnRef.current = null;
   }, [activeThread?.id]);
 
+  // Auto-open the plan sidebar when plan/todo steps arrive for the current turn.
+  // Don't auto-open for plans carried over from a previous turn (the user can open manually).
+  useEffect(() => {
+    if (!autoOpenPlanSidebar) return;
+    if (!activePlan) return;
+    if (planSidebarOpen) return;
+    const latestTurnId = activeLatestTurn?.turnId ?? null;
+    if (latestTurnId && activePlan.turnId !== latestTurnId) return;
+    const turnKey = activePlan.turnId ?? sidebarProposedPlan?.turnId ?? "__dismissed__";
+    if (planSidebarDismissedForTurnRef.current === turnKey) return;
+    setPlanSidebarOpen(true);
+  }, [
+    activePlan,
+    activeLatestTurn?.turnId,
+    autoOpenPlanSidebar,
+    planSidebarOpen,
+    sidebarProposedPlan?.turnId,
+  ]);
+
   useEffect(() => {
     setIsRevertingCheckpoint(false);
   }, [activeThread?.id]);
@@ -2200,11 +2316,42 @@ export default function ChatView(props: ChatViewProps) {
   }, []);
 
   const activeWorktreePath = activeThread?.worktreePath ?? null;
-  const envMode: DraftThreadEnvMode = resolveEffectiveEnvMode({
+  const derivedEnvMode: DraftThreadEnvMode = resolveEffectiveEnvMode({
     activeWorktreePath,
     hasServerThread: isServerThread,
     draftThreadEnvMode: isLocalDraftThread ? draftThread?.envMode : undefined,
   });
+  const canOverrideServerThreadEnvMode = Boolean(
+    isServerThread &&
+    activeThread &&
+    activeThread.messages.length === 0 &&
+    activeThread.worktreePath === null &&
+    !envLocked,
+  );
+  const envMode: DraftThreadEnvMode = canOverrideServerThreadEnvMode
+    ? (pendingServerThreadEnvMode ?? draftThread?.envMode ?? derivedEnvMode)
+    : derivedEnvMode;
+  const activeThreadBranch =
+    canOverrideServerThreadEnvMode && pendingServerThreadBranch !== undefined
+      ? pendingServerThreadBranch
+      : (activeThread?.branch ?? null);
+  const sendEnvMode = resolveSendEnvMode({
+    requestedEnvMode: envMode,
+    isGitRepo,
+  });
+
+  useEffect(() => {
+    setPendingServerThreadEnvMode(null);
+    setPendingServerThreadBranch(undefined);
+  }, [activeThread?.id]);
+
+  useEffect(() => {
+    if (canOverrideServerThreadEnvMode) {
+      return;
+    }
+    setPendingServerThreadEnvMode(null);
+    setPendingServerThreadBranch(undefined);
+  }, [canOverrideServerThreadEnvMode]);
 
   useEffect(() => {
     if (!activeThreadId) {
@@ -2290,16 +2437,6 @@ export default function ChatView(props: ChatViewProps) {
     terminalState.terminalOpen,
   ]);
 
-  useEffect(() => {
-    if (phase !== "running") return;
-    const timer = window.setInterval(() => {
-      setNowTick(Date.now());
-    }, 1000);
-    return () => {
-      window.clearInterval(timer);
-    };
-  }, [phase]);
-
   useEffect(() => {
     if (!activeThreadKey) return;
     const previous = terminalOpenByThreadRef.current[activeThreadKey] ?? false;
@@ -2330,6 +2467,7 @@ export default function ChatView(props: ChatViewProps) {
       const shortcutContext = {
         terminalFocus: isTerminalFocused(),
         terminalOpen: Boolean(terminalState.terminalOpen),
+        modelPickerOpen: composerRef.current?.isModelPickerOpen() ?? false,
       };
 
       const command = resolveShortcutCommand(event, keybindings, {
@@ -2379,6 +2517,13 @@ export default function ChatView(props: ChatViewProps) {
         return;
       }
 
+      if (command === "modelPicker.toggle") {
+        event.preventDefault();
+        event.stopPropagation();
+        composerRef.current?.toggleModelPicker();
+        return;
+      }
+
       const scriptId = projectScriptIdFromCommand(command);
       if (!scriptId || !activeProject) return;
       const script = activeProject.scripts.find((entry) => entry.id === scriptId);
@@ -2387,8 +2532,8 @@ export default function ChatView(props: ChatViewProps) {
       event.stopPropagation();
       void runProjectScript(script);
     };
-    window.addEventListener("keydown", handler);
-    return () => window.removeEventListener("keydown", handler);
+    window.addEventListener("keydown", handler, true);
+    return () => window.removeEventListener("keydown", handler, true);
   }, [
     activeProject,
     terminalState.terminalOpen,
@@ -2410,6 +2555,13 @@ export default function ChatView(props: ChatViewProps) {
       const localApi = readLocalApi();
       if (!api || !localApi || !activeThread || isRevertingCheckpoint) return;
 
+      if (activeEnvironmentUnavailable && activeEnvironmentUnavailableLabel) {
+        setThreadError(
+          activeThread.id,
+          `Reconnect ${activeEnvironmentUnavailableLabel} before reverting checkpoints.`,
+        );
+        return;
+      }
       if (phase === "running" || isSendBusy || isConnecting) {
         setThreadError(activeThread.id, "Interrupt the current turn before reverting checkpoints.");
         return;
@@ -2445,6 +2597,8 @@ export default function ChatView(props: ChatViewProps) {
     },
     [
       activeThread,
+      activeEnvironmentUnavailable,
+      activeEnvironmentUnavailableLabel,
       environmentId,
       isConnecting,
       isRevertingCheckpoint,
@@ -2457,7 +2611,15 @@ export default function ChatView(props: ChatViewProps) {
   const onSend = async (e?: { preventDefault: () => void }) => {
     e?.preventDefault();
     const api = readEnvironmentApi(environmentId);
-    if (!api || !activeThread || isSendBusy || isConnecting || sendInFlightRef.current) return;
+    if (
+      !api ||
+      !activeThread ||
+      isSendBusy ||
+      isConnecting ||
+      activeEnvironmentUnavailable ||
+      sendInFlightRef.current
+    )
+      return;
     if (activePendingProgress) {
       onAdvanceActivePendingUserInput();
       return;
@@ -2515,11 +2677,13 @@ export default function ChatView(props: ChatViewProps) {
           expiredTerminalContextCount,
           "empty",
         );
-        toastManager.add({
-          type: "warning",
-          title: toastCopy.title,
-          description: toastCopy.description,
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "warning",
+            title: toastCopy.title,
+            description: toastCopy.description,
+          }),
+        );
       }
       return;
     }
@@ -2527,15 +2691,15 @@ export default function ChatView(props: ChatViewProps) {
     const threadIdForSend = activeThread.id;
     const isFirstMessage = !isServerThread || activeThread.messages.length === 0;
     const baseBranchForWorktree =
-      isFirstMessage && envMode === "worktree" && !activeThread.worktreePath
-        ? activeThread.branch
+      isFirstMessage && sendEnvMode === "worktree" && !activeThread.worktreePath
+        ? activeThreadBranch
         : null;
 
     // In worktree mode, require an explicit base branch so we don't silently
     // fall back to local execution when branch selection is missing.
     const shouldCreateWorktree =
-      isFirstMessage && envMode === "worktree" && !activeThread.worktreePath;
-    if (shouldCreateWorktree && !activeThread.branch) {
+      isFirstMessage && sendEnvMode === "worktree" && !activeThread.worktreePath;
+    if (shouldCreateWorktree && !activeThreadBranch) {
       setThreadError(threadIdForSend, "Select a base branch before sending in New worktree mode.");
       return;
     }
@@ -2575,6 +2739,14 @@ export default function ChatView(props: ChatViewProps) {
       sizeBytes: image.sizeBytes,
       previewUrl: image.previewUrl,
     }));
+    // Scroll to the current end *before* adding the optimistic message.
+    // This sets LegendList's internal isAtEnd=true so maintainScrollAtEnd
+    // automatically pins to the new item when the data changes.
+    isAtEndRef.current = true;
+    showScrollDebouncer.current.cancel();
+    setShowScrollToBottom(false);
+    await legendListRef.current?.scrollToEnd?.({ animated: false });
+
     setOptimisticUserMessages((existing) => [
       ...existing,
       {
@@ -2586,9 +2758,6 @@ export default function ChatView(props: ChatViewProps) {
         streaming: false,
       },
     ]);
-    // Sending a message should always bring the latest user turn into view.
-    shouldAutoScrollRef.current = true;
-    forceStickToBottom();
 
     setThreadError(threadIdForSend, null);
     if (expiredTerminalContextCount > 0) {
@@ -2596,11 +2765,13 @@ export default function ChatView(props: ChatViewProps) {
         expiredTerminalContextCount,
         "omitted",
       );
-      toastManager.add({
-        type: "warning",
-        title: toastCopy.title,
-        description: toastCopy.description,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "warning",
+          title: toastCopy.title,
+          description: toastCopy.description,
+        }),
+      );
     }
     promptRef.current = "";
     clearComposerDraftContent(composerDraftTarget);
@@ -2626,16 +2797,11 @@ export default function ChatView(props: ChatViewProps) {
         }
       }
       const title = truncate(titleSeed);
-      const threadCreateModelSelection: ModelSelection = {
-        provider: ctxSelectedProvider,
-        model:
-          ctxSelectedModel ||
-          activeProject.defaultModelSelection?.model ||
-          DEFAULT_MODEL_BY_PROVIDER.codex,
-        ...(ctxSelectedModelSelection.options
-          ? { options: ctxSelectedModelSelection.options }
-          : {}),
-      };
+      const threadCreateModelSelection = createModelSelection(
+        ctxSelectedModelSelection.instanceId,
+        ctxSelectedModel || activeProject.defaultModelSelection?.model || DEFAULT_MODEL,
+        ctxSelectedModelSelection.options,
+      );
 
       // Auto-title from first message
       if (isFirstMessage && isServerThread) {
@@ -2669,7 +2835,7 @@ export default function ChatView(props: ChatViewProps) {
                       modelSelection: threadCreateModelSelection,
                       runtimeMode,
                       interactionMode,
-                      branch: activeThread.branch,
+                      branch: activeThreadBranch,
                       worktreePath: activeThread.worktreePath,
                       createdAt: activeThread.createdAt,
                     },
@@ -2969,6 +3135,13 @@ export default function ChatView(props: ChatViewProps) {
       sendInFlightRef.current = true;
       beginLocalDispatch({ preparingWorktree: false });
       setThreadError(threadIdForSend, null);
+
+      // Scroll to the current end *before* adding the optimistic message.
+      isAtEndRef.current = true;
+      showScrollDebouncer.current.cancel();
+      setShowScrollToBottom(false);
+      await legendListRef.current?.scrollToEnd?.({ animated: false });
+
       setOptimisticUserMessages((existing) => [
         ...existing,
         {
@@ -2979,8 +3152,6 @@ export default function ChatView(props: ChatViewProps) {
           streaming: false,
         },
       ]);
-      shouldAutoScrollRef.current = true;
-      forceStickToBottom();
 
       try {
         await persistThreadSettingsForNextTurn({
@@ -3025,7 +3196,7 @@ export default function ChatView(props: ChatViewProps) {
         // Optimistically open the plan sidebar when implementing (not refining).
         // "default" mode here means the agent is executing the plan, which produces
         // step-tracking activities that the sidebar will display.
-        if (nextInteractionMode === "default") {
+        if (nextInteractionMode === "default" && autoOpenPlanSidebar) {
           planSidebarDismissedForTurnRef.current = null;
           setPlanSidebarOpen(true);
         }
@@ -3046,7 +3217,6 @@ export default function ChatView(props: ChatViewProps) {
       activeThread,
       activeProposedPlan,
       beginLocalDispatch,
-      forceStickToBottom,
       isConnecting,
       isSendBusy,
       isServerThread,
@@ -3055,6 +3225,7 @@ export default function ChatView(props: ChatViewProps) {
       runtimeMode,
       setComposerDraftInteractionMode,
       setThreadError,
+      autoOpenPlanSidebar,
       environmentId,
     ],
   );
@@ -3069,6 +3240,7 @@ export default function ChatView(props: ChatViewProps) {
       !isServerThread ||
       isSendBusy ||
       isConnecting ||
+      activeEnvironmentUnavailable ||
       sendInFlightRef.current
     ) {
       return;
@@ -3117,7 +3289,7 @@ export default function ChatView(props: ChatViewProps) {
         modelSelection: nextThreadModelSelection,
         runtimeMode,
         interactionMode: "default",
-        branch: activeThread.branch,
+        branch: activeThreadBranch,
         worktreePath: activeThread.worktreePath,
         createdAt,
       })
@@ -3147,8 +3319,8 @@ export default function ChatView(props: ChatViewProps) {
         return waitForStartedServerThread(scopeThreadRef(activeThread.environmentId, nextThreadId));
       })
       .then(() => {
-        // Signal that the plan sidebar should open on the new thread.
-        planSidebarOpenOnNextThreadRef.current = true;
+        // Signal that the plan sidebar should open on the new thread when enabled.
+        planSidebarOpenOnNextThreadRef.current = autoOpenPlanSidebar;
         return navigate({
           to: "/$environmentId/$threadId",
           params: {
@@ -3165,44 +3337,76 @@ export default function ChatView(props: ChatViewProps) {
             threadId: nextThreadId,
           })
           .catch(() => undefined);
-        toastManager.add({
-          type: "error",
-          title: "Could not start implementation thread",
-          description:
-            err instanceof Error ? err.message : "An error occurred while creating the new thread.",
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not start implementation thread",
+            description:
+              err instanceof Error
+                ? err.message
+                : "An error occurred while creating the new thread.",
+          }),
+        );
       })
       .then(finish, finish);
   }, [
     activeProject,
     activeProposedPlan,
+    activeThreadBranch,
     activeThread,
     beginLocalDispatch,
+    activeEnvironmentUnavailable,
     isConnecting,
     isSendBusy,
     isServerThread,
     navigate,
     resetLocalDispatch,
     runtimeMode,
+    autoOpenPlanSidebar,
     environmentId,
   ]);
 
   const onProviderModelSelect = useCallback(
-    (provider: ProviderKind, model: string) => {
+    (instanceId: ProviderInstanceId, model: string) => {
       if (!activeThread) return;
-      if (lockedProvider !== null && provider !== lockedProvider) {
+      // Look up the configured instance so model normalization and custom
+      // model lookup stay scoped to that exact instance. Unknown instance ids
+      // are rejected by returning early; the server remains authoritative too.
+      const entry = providerStatuses.find((snapshot) => snapshot.instanceId === instanceId);
+      const resolvedDriverKind = entry?.driver ?? null;
+      if (
+        lockedProvider !== null &&
+        resolvedDriverKind !== null &&
+        resolvedDriverKind !== lockedProvider
+      ) {
         scheduleComposerFocus();
         return;
       }
-      const resolvedProvider = resolveSelectableProvider(providerStatuses, provider);
-      const resolvedModel = resolveAppModelSelection(
-        resolvedProvider,
+      if (lockedProvider !== null && activeThread.session?.providerInstanceId) {
+        const currentEntry = providerStatuses.find(
+          (snapshot) => snapshot.instanceId === activeThread.session?.providerInstanceId,
+        );
+        if (
+          currentEntry?.continuation?.groupKey &&
+          entry?.continuation?.groupKey &&
+          currentEntry.continuation.groupKey !== entry.continuation.groupKey
+        ) {
+          scheduleComposerFocus();
+          return;
+        }
+      }
+      const resolvedModel = resolveAppModelSelectionForInstance(
+        instanceId,
         settings,
         providerStatuses,
         model,
       );
+      if (!resolvedModel) {
+        scheduleComposerFocus();
+        return;
+      }
       const nextModelSelection: ModelSelection = {
-        provider: resolvedProvider,
+        instanceId,
         model: resolvedModel,
       };
       setComposerDraftModelSelection(
@@ -3224,6 +3428,11 @@ export default function ChatView(props: ChatViewProps) {
   );
   const onEnvModeChange = useCallback(
     (mode: DraftThreadEnvMode) => {
+      if (canOverrideServerThreadEnvMode) {
+        setPendingServerThreadEnvMode(mode);
+        scheduleComposerFocus();
+        return;
+      }
       if (isLocalDraftThread) {
         setDraftThreadContext(composerDraftTarget, {
           envMode: mode,
@@ -3233,20 +3442,16 @@ export default function ChatView(props: ChatViewProps) {
       scheduleComposerFocus();
     },
     [
+      canOverrideServerThreadEnvMode,
       composerDraftTarget,
       draftThread?.worktreePath,
       isLocalDraftThread,
+      setPendingServerThreadEnvMode,
       scheduleComposerFocus,
       setDraftThreadContext,
     ],
   );
 
-  const onToggleWorkGroup = useCallback((groupId: string) => {
-    setExpandedWorkGroups((existing) => ({
-      ...existing,
-      [groupId]: !existing[groupId],
-    }));
-  }, []);
   const onExpandTimelineImage = useCallback((preview: ExpandedImagePreview) => {
     setExpandedImage(preview);
   }, []);
@@ -3272,16 +3477,19 @@ export default function ChatView(props: ChatViewProps) {
     },
     [environmentId, isServerThread, navigate, onDiffPanelOpen, threadId],
   );
-  const onRevertUserMessage = useCallback(
-    (messageId: MessageId) => {
-      const targetTurnCount = revertTurnCountByUserMessageId.get(messageId);
-      if (typeof targetTurnCount !== "number") {
-        return;
-      }
-      void onRevertToTurnCount(targetTurnCount);
-    },
-    [onRevertToTurnCount, revertTurnCountByUserMessageId],
-  );
+  // Both the Map and the revert handler are read from refs at call-time so
+  // the callback reference is fully stable and never busts context identity.
+  const revertTurnCountRef = useRef(revertTurnCountByUserMessageId);
+  revertTurnCountRef.current = revertTurnCountByUserMessageId;
+  const onRevertToTurnCountRef = useRef(onRevertToTurnCount);
+  onRevertToTurnCountRef.current = onRevertToTurnCount;
+  const onRevertUserMessage = useCallback((messageId: MessageId) => {
+    const targetTurnCount = revertTurnCountRef.current.get(messageId);
+    if (typeof targetTurnCount !== "number") {
+      return;
+    }
+    void onRevertToTurnCountRef.current(targetTurnCount);
+  }, []);
 
   // Empty state: no active thread
   if (!activeThread) {
@@ -3293,8 +3501,14 @@ export default function ChatView(props: ChatViewProps) {
       {/* Top bar */}
       <header
         className={cn(
-          "border-b border-border px-3 sm:px-5",
-          isElectron ? "drag-region flex h-[52px] items-center" : "py-2 sm:py-3",
+          "border-b border-border",
+          isElectron
+            ? cn(
+                "drag-region flex h-[52px] items-center px-3 sm:px-5 wco:h-[env(titlebar-area-height)]",
+                reserveTitleBarControlInset &&
+                  "wco:pr-[calc(100vw-env(titlebar-area-width)-env(titlebar-area-x)+1em)]",
+              )
+            : "pb-2 pl-[calc(env(safe-area-inset-left)+0.75rem)] pr-[calc(env(safe-area-inset-right)+0.75rem)] pt-2 sm:pb-3 sm:pl-[calc(env(safe-area-inset-left)+1.25rem)] sm:pr-[calc(env(safe-area-inset-right)+1.25rem)] sm:pt-3",
         )}
       >
         <ChatHeader
@@ -3338,57 +3552,39 @@ export default function ChatView(props: ChatViewProps) {
         <div className="flex min-h-0 min-w-0 flex-1 flex-col">
           {/* Messages Wrapper */}
           <div className="relative flex min-h-0 flex-1 flex-col">
-            {/* Messages */}
-            <div
-              ref={setMessagesScrollContainerRef}
-              className="min-h-0 flex-1 overflow-x-hidden overflow-y-auto overscroll-y-contain px-3 py-3 sm:px-5 sm:py-4"
-              onScroll={onMessagesScroll}
-              onClickCapture={onMessagesClickCapture}
-              onWheel={onMessagesWheel}
-              onPointerDown={onMessagesPointerDown}
-              onPointerUp={onMessagesPointerUp}
-              onPointerCancel={onMessagesPointerCancel}
-              onTouchStart={onMessagesTouchStart}
-              onTouchMove={onMessagesTouchMove}
-              onTouchEnd={onMessagesTouchEnd}
-              onTouchCancel={onMessagesTouchEnd}
-            >
-              <MessagesTimeline
-                key={activeThread.id}
-                hasMessages={timelineEntries.length > 0}
-                isWorking={isWorking}
-                activeTurnInProgress={isWorking || !latestTurnSettled}
-                activeTurnId={activeLatestTurn?.turnId ?? null}
-                activeTurnStartedAt={activeWorkStartedAt}
-                scrollContainer={messagesScrollElement}
-                timelineEntries={timelineEntries}
-                completionDividerBeforeEntryId={completionDividerBeforeEntryId}
-                completionSummary={completionSummary}
-                turnDiffSummaryByAssistantMessageId={turnDiffSummaryByAssistantMessageId}
-                nowIso={nowIso}
-                activeThreadEnvironmentId={activeThread.environmentId}
-                expandedWorkGroups={expandedWorkGroups}
-                onToggleWorkGroup={onToggleWorkGroup}
-                changedFilesExpandedByTurnId={changedFilesExpandedByTurnId}
-                onSetChangedFilesExpanded={handleSetChangedFilesExpanded}
-                onOpenTurnDiff={onOpenTurnDiff}
-                revertTurnCountByUserMessageId={revertTurnCountByUserMessageId}
-                onRevertUserMessage={onRevertUserMessage}
-                isRevertingCheckpoint={isRevertingCheckpoint}
-                onImageExpand={onExpandTimelineImage}
-                markdownCwd={gitCwd ?? undefined}
-                resolvedTheme={resolvedTheme}
-                timestampFormat={timestampFormat}
-                workspaceRoot={activeWorkspaceRoot}
-              />
-            </div>
+            {/* Messages — LegendList handles virtualization and scrolling internally */}
+            <MessagesTimeline
+              key={activeThread.id}
+              isWorking={isWorking}
+              activeTurnInProgress={isWorking || !latestTurnSettled}
+              activeTurnId={activeLatestTurn?.turnId ?? null}
+              activeTurnStartedAt={activeWorkStartedAt}
+              listRef={legendListRef}
+              timelineEntries={timelineEntries}
+              completionDividerBeforeEntryId={completionDividerBeforeEntryId}
+              completionSummary={completionSummary}
+              turnDiffSummaryByAssistantMessageId={turnDiffSummaryByAssistantMessageId}
+              activeThreadEnvironmentId={activeThread.environmentId}
+              routeThreadKey={routeThreadKey}
+              onOpenTurnDiff={onOpenTurnDiff}
+              revertTurnCountByUserMessageId={revertTurnCountByUserMessageId}
+              onRevertUserMessage={onRevertUserMessage}
+              isRevertingCheckpoint={isRevertingCheckpoint}
+              onImageExpand={onExpandTimelineImage}
+              markdownCwd={gitCwd ?? undefined}
+              resolvedTheme={resolvedTheme}
+              timestampFormat={timestampFormat}
+              workspaceRoot={activeWorkspaceRoot}
+              skills={activeProviderStatus?.skills ?? EMPTY_PROVIDER_SKILLS}
+              onIsAtEndChange={onIsAtEndChange}
+            />
 
             {/* scroll to bottom pill — shown when user has scrolled away from the bottom */}
             {showScrollToBottom && (
               <div className="pointer-events-none absolute bottom-1 left-1/2 z-30 flex -translate-x-1/2 justify-center py-1.5">
                 <button
                   type="button"
-                  onClick={() => scrollMessagesToBottom("smooth")}
+                  onClick={() => scrollToEnd(true)}
                   className="pointer-events-auto flex items-center gap-1.5 rounded-full border border-border/60 bg-card px-3 py-1 text-muted-foreground text-xs shadow-sm transition-colors hover:border-border hover:text-foreground hover:cursor-pointer"
                 >
                   <ChevronDownIcon className="size-3.5" />
@@ -3399,93 +3595,114 @@ export default function ChatView(props: ChatViewProps) {
           </div>
 
           {/* Input bar */}
-          <div className={cn("px-3 pt-1.5 sm:px-5 sm:pt-2", isGitRepo ? "pb-1" : "pb-3 sm:pb-4")}>
-            <ChatComposer
-              ref={composerRef}
-              composerDraftTarget={composerDraftTarget}
-              environmentId={environmentId}
-              routeKind={routeKind}
-              routeThreadRef={routeThreadRef}
-              draftId={draftId}
-              activeThreadId={activeThreadId}
-              activeThreadEnvironmentId={activeThread?.environmentId}
-              activeThread={activeThread}
-              isServerThread={isServerThread}
-              isLocalDraftThread={isLocalDraftThread}
-              phase={phase}
-              isConnecting={isConnecting}
-              isSendBusy={isSendBusy}
-              isPreparingWorktree={isPreparingWorktree}
-              activePendingApproval={activePendingApproval}
-              pendingApprovals={pendingApprovals}
-              pendingUserInputs={pendingUserInputs}
-              activePendingProgress={activePendingProgress}
-              activePendingResolvedAnswers={activePendingResolvedAnswers}
-              activePendingIsResponding={activePendingIsResponding}
-              activePendingDraftAnswers={activePendingDraftAnswers}
-              activePendingQuestionIndex={activePendingQuestionIndex}
-              respondingRequestIds={respondingRequestIds}
-              showPlanFollowUpPrompt={showPlanFollowUpPrompt}
-              activeProposedPlan={activeProposedPlan}
-              activePlan={activePlan as { turnId?: TurnId } | null}
-              sidebarProposedPlan={sidebarProposedPlan as { turnId?: TurnId } | null}
-              planSidebarOpen={planSidebarOpen}
-              runtimeMode={runtimeMode}
-              interactionMode={interactionMode}
-              lockedProvider={lockedProvider}
-              providerStatuses={providerStatuses as ServerProvider[]}
-              activeProjectDefaultModelSelection={activeProject?.defaultModelSelection}
-              activeThreadModelSelection={activeThread?.modelSelection}
-              activeThreadActivities={activeThread?.activities}
-              resolvedTheme={resolvedTheme}
-              settings={settings}
-              gitCwd={gitCwd}
-              promptRef={promptRef}
-              composerImagesRef={composerImagesRef}
-              composerTerminalContextsRef={composerTerminalContextsRef}
-              shouldAutoScrollRef={shouldAutoScrollRef}
-              scheduleStickToBottom={scheduleStickToBottom}
-              onSend={onSend}
-              onInterrupt={onInterrupt}
-              onImplementPlanInNewThread={onImplementPlanInNewThread}
-              onRespondToApproval={onRespondToApproval}
-              onSelectActivePendingUserInputOption={onSelectActivePendingUserInputOption}
-              onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
-              onPreviousActivePendingUserInputQuestion={onPreviousActivePendingUserInputQuestion}
-              onChangeActivePendingUserInputCustomAnswer={
-                onChangeActivePendingUserInputCustomAnswer
-              }
-              onProviderModelSelect={onProviderModelSelect}
-              toggleInteractionMode={toggleInteractionMode}
-              handleRuntimeModeChange={handleRuntimeModeChange}
-              handleInteractionModeChange={handleInteractionModeChange}
-              togglePlanSidebar={togglePlanSidebar}
-              focusComposer={focusComposer}
-              scheduleComposerFocus={scheduleComposerFocus}
-              setThreadError={setThreadError}
-              onExpandImage={onExpandTimelineImage}
-            />
+          <div
+            className={cn(
+              "pl-[calc(env(safe-area-inset-left)+0.75rem)] pr-[calc(env(safe-area-inset-right)+0.75rem)] pt-1.5 sm:pl-[calc(env(safe-area-inset-left)+1.25rem)] sm:pr-[calc(env(safe-area-inset-right)+1.25rem)] sm:pt-2",
+              isGitRepo
+                ? "pb-[calc(env(safe-area-inset-bottom)+0.25rem)]"
+                : "pb-[calc(env(safe-area-inset-bottom)+0.75rem)] sm:pb-[calc(env(safe-area-inset-bottom)+1rem)]",
+            )}
+          >
+            <div className="relative isolate">
+              <ComposerBannerStack className="relative z-0" items={composerBannerItems} />
+              <div className="relative z-10">
+                <ChatComposer
+                  composerRef={composerRef}
+                  composerDraftTarget={composerDraftTarget}
+                  environmentId={environmentId}
+                  routeKind={routeKind}
+                  routeThreadRef={routeThreadRef}
+                  draftId={draftId}
+                  activeThreadId={activeThreadId}
+                  activeThreadEnvironmentId={activeThread?.environmentId}
+                  activeThread={activeThread}
+                  isServerThread={isServerThread}
+                  isLocalDraftThread={isLocalDraftThread}
+                  phase={phase}
+                  isConnecting={isConnecting}
+                  isSendBusy={isSendBusy}
+                  isPreparingWorktree={isPreparingWorktree}
+                  environmentUnavailable={activeEnvironmentUnavailableState}
+                  activePendingApproval={activePendingApproval}
+                  pendingApprovals={pendingApprovals}
+                  pendingUserInputs={pendingUserInputs}
+                  activePendingProgress={activePendingProgress}
+                  activePendingResolvedAnswers={activePendingResolvedAnswers}
+                  activePendingIsResponding={activePendingIsResponding}
+                  activePendingDraftAnswers={activePendingDraftAnswers}
+                  activePendingQuestionIndex={activePendingQuestionIndex}
+                  respondingRequestIds={respondingRequestIds}
+                  showPlanFollowUpPrompt={showPlanFollowUpPrompt}
+                  activeProposedPlan={activeProposedPlan}
+                  activePlan={activePlan as { turnId?: TurnId } | null}
+                  sidebarProposedPlan={sidebarProposedPlan as { turnId?: TurnId } | null}
+                  planSidebarLabel={planSidebarLabel}
+                  planSidebarOpen={planSidebarOpen}
+                  runtimeMode={runtimeMode}
+                  interactionMode={interactionMode}
+                  lockedProvider={lockedProvider}
+                  providerStatuses={providerStatuses as ServerProvider[]}
+                  activeProjectDefaultModelSelection={activeProject?.defaultModelSelection}
+                  activeThreadModelSelection={activeThread?.modelSelection}
+                  activeThreadActivities={activeThread?.activities}
+                  resolvedTheme={resolvedTheme}
+                  settings={settings}
+                  keybindings={keybindings}
+                  terminalOpen={Boolean(terminalState.terminalOpen)}
+                  gitCwd={gitCwd}
+                  promptRef={promptRef}
+                  composerImagesRef={composerImagesRef}
+                  composerTerminalContextsRef={composerTerminalContextsRef}
+                  shouldAutoScrollRef={isAtEndRef}
+                  scheduleStickToBottom={scrollToEnd}
+                  onSend={onSend}
+                  onInterrupt={onInterrupt}
+                  onImplementPlanInNewThread={onImplementPlanInNewThread}
+                  onRespondToApproval={onRespondToApproval}
+                  onSelectActivePendingUserInputOption={onSelectActivePendingUserInputOption}
+                  onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
+                  onPreviousActivePendingUserInputQuestion={
+                    onPreviousActivePendingUserInputQuestion
+                  }
+                  onChangeActivePendingUserInputCustomAnswer={
+                    onChangeActivePendingUserInputCustomAnswer
+                  }
+                  onProviderModelSelect={onProviderModelSelect}
+                  toggleInteractionMode={toggleInteractionMode}
+                  handleRuntimeModeChange={handleRuntimeModeChange}
+                  handleInteractionModeChange={handleInteractionModeChange}
+                  togglePlanSidebar={togglePlanSidebar}
+                  focusComposer={focusComposer}
+                  scheduleComposerFocus={scheduleComposerFocus}
+                  setThreadError={setThreadError}
+                  onExpandImage={onExpandTimelineImage}
+                />
+              </div>
+            </div>
+            {isGitRepo && (
+              <BranchToolbar
+                environmentId={activeThread.environmentId}
+                threadId={activeThread.id}
+                {...(routeKind === "draft" && draftId ? { draftId } : {})}
+                onEnvModeChange={onEnvModeChange}
+                {...(canOverrideServerThreadEnvMode ? { effectiveEnvModeOverride: envMode } : {})}
+                {...(canOverrideServerThreadEnvMode
+                  ? {
+                      activeThreadBranchOverride: activeThreadBranch,
+                      onActiveThreadBranchOverrideChange: setPendingServerThreadBranch,
+                    }
+                  : {})}
+                envLocked={envLocked}
+                onComposerFocusRequest={scheduleComposerFocus}
+                {...(canCheckoutPullRequestIntoThread
+                  ? { onCheckoutPullRequestRequest: openPullRequestDialog }
+                  : {})}
+                {...(hasMultipleEnvironments ? { onEnvironmentChange } : {})}
+                availableEnvironments={logicalProjectEnvironments}
+              />
+            )}
           </div>
 
-          {isGitRepo && (
-            <BranchToolbar
-              environmentId={activeThread.environmentId}
-              threadId={activeThread.id}
-              {...(routeKind === "draft" && draftId ? { draftId } : {})}
-              onEnvModeChange={onEnvModeChange}
-              envLocked={envLocked}
-              onComposerFocusRequest={scheduleComposerFocus}
-              {...(canCheckoutPullRequestIntoThread
-                ? { onCheckoutPullRequestRequest: openPullRequestDialog }
-                : {})}
-              {...(hasMultipleEnvironments
-                ? {
-                    availableEnvironments: logicalProjectEnvironments,
-                    onEnvironmentChange,
-                  }
-                : {})}
-            />
-          )}
           {pullRequestDialogState ? (
             <PullRequestThreadDialog
               key={pullRequestDialogState.key}
@@ -3506,22 +3723,17 @@ export default function ChatView(props: ChatViewProps) {
         {/* end chat column */}
 
         {/* Plan sidebar */}
-        {planSidebarOpen ? (
+        {planSidebarOpen && !shouldUsePlanSidebarSheet ? (
           <PlanSidebar
             activePlan={activePlan}
             activeProposedPlan={sidebarProposedPlan}
+            label={planSidebarLabel}
             environmentId={environmentId}
             markdownCwd={gitCwd ?? undefined}
             workspaceRoot={activeWorkspaceRoot}
             timestampFormat={timestampFormat}
-            onClose={() => {
-              setPlanSidebarOpen(false);
-              // Track that the user explicitly dismissed for this turn so auto-open won't fight them.
-              const turnKey = activePlan?.turnId ?? sidebarProposedPlan?.turnId ?? null;
-              if (turnKey) {
-                planSidebarDismissedForTurnRef.current = turnKey;
-              }
-            }}
+            mode="sidebar"
+            onClose={closePlanSidebar}
           />
         ) : null}
       </div>
@@ -3540,9 +3752,25 @@ export default function ChatView(props: ChatViewProps) {
           splitShortcutLabel={splitTerminalShortcutLabel ?? undefined}
           newShortcutLabel={newTerminalShortcutLabel ?? undefined}
           closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}
+          keybindings={keybindings}
           onAddTerminalContext={addTerminalContextToDraft}
         />
       ))}
+      {shouldUsePlanSidebarSheet ? (
+        <RightPanelSheet open={planSidebarOpen} onClose={closePlanSidebar}>
+          <PlanSidebar
+            activePlan={activePlan}
+            activeProposedPlan={sidebarProposedPlan}
+            label={planSidebarLabel}
+            environmentId={environmentId}
+            markdownCwd={gitCwd ?? undefined}
+            workspaceRoot={activeWorkspaceRoot}
+            timestampFormat={timestampFormat}
+            mode="sheet"
+            onClose={closePlanSidebar}
+          />
+        </RightPanelSheet>
+      ) : null}
 
       {expandedImage && (
         <ExpandedImageDialog preview={expandedImage} onClose={closeExpandedImage} />
diff --git a/apps/web/src/components/CommandPalette.logic.test.ts b/apps/web/src/components/CommandPalette.logic.test.ts
index a49dadc851f..38b44f3f6a7 100644
--- a/apps/web/src/components/CommandPalette.logic.test.ts
+++ b/apps/web/src/components/CommandPalette.logic.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { EnvironmentId, ProjectId, ThreadId } from "@t3tools/contracts";
+import { EnvironmentId, ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 import type { Thread } from "../types";
 import {
   buildThreadActionItems,
@@ -17,7 +17,7 @@ function makeThread(overrides: Partial<Thread> = {}): Thread {
     codexThreadId: null,
     projectId: PROJECT_ID,
     title: "Thread",
-    modelSelection: { provider: "codex", model: "gpt-5" },
+    modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
     runtimeMode: "full-access",
     interactionMode: "default",
     session: null,
diff --git a/apps/web/src/components/CommandPalette.logic.ts b/apps/web/src/components/CommandPalette.logic.ts
index c29f1271087..3f4997e215c 100644
--- a/apps/web/src/components/CommandPalette.logic.ts
+++ b/apps/web/src/components/CommandPalette.logic.ts
@@ -1,4 +1,4 @@
-import { type KeybindingCommand } from "@t3tools/contracts";
+import { type KeybindingCommand, type FilesystemBrowseEntry } from "@t3tools/contracts";
 import type { SidebarThreadSortOrder } from "@t3tools/contracts/settings";
 import { type ReactNode } from "react";
 import { sortThreads } from "../lib/threadSort";
@@ -17,6 +17,11 @@ export interface CommandPaletteItem {
   readonly description?: string;
   readonly timestamp?: string;
   readonly icon: ReactNode;
+  readonly disabled?: boolean;
+  /** Optional content rendered inline before the title text. */
+  readonly titleLeadingContent?: ReactNode;
+  /** Optional content rendered inline after the title text (before the timestamp). */
+  readonly titleTrailingContent?: ReactNode;
   readonly shortcutCommand?: KeybindingCommand;
 }
 
@@ -45,7 +50,39 @@ export interface CommandPaletteView {
   readonly initialQuery?: string;
 }
 
-export type CommandPaletteMode = "root" | "submenu";
+export type CommandPaletteMode = "root" | "root-browse" | "submenu" | "submenu-browse";
+
+export function filterBrowseEntries(input: {
+  browseEntries: ReadonlyArray<FilesystemBrowseEntry>;
+  browseFilterQuery: string;
+  highlightedItemValue: string | null;
+}): {
+  filteredEntries: FilesystemBrowseEntry[];
+  highlightedEntry: FilesystemBrowseEntry | null;
+  exactEntry: FilesystemBrowseEntry | null;
+} {
+  const lowerFilter = input.browseFilterQuery.toLowerCase();
+  const showHidden = input.browseFilterQuery.startsWith(".");
+
+  const filteredEntries = input.browseEntries.filter(
+    (entry) =>
+      entry.name.toLowerCase().startsWith(lowerFilter) &&
+      (showHidden || !entry.name.startsWith(".")),
+  );
+
+  let highlightedEntry: FilesystemBrowseEntry | null = null;
+  if (input.highlightedItemValue?.startsWith("browse:")) {
+    const highlightedPath = input.highlightedItemValue.slice("browse:".length);
+    highlightedEntry = filteredEntries.find((entry) => entry.fullPath === highlightedPath) ?? null;
+  }
+
+  const exactEntry =
+    input.browseFilterQuery.length > 0
+      ? (filteredEntries.find((entry) => entry.name === input.browseFilterQuery) ?? null)
+      : null;
+
+  return { filteredEntries, highlightedEntry, exactEntry };
+}
 
 export function normalizeSearchText(value: string): string {
   return value.trim().toLowerCase().replace(/\s+/g, " ");
@@ -70,20 +107,24 @@ export function buildProjectActionItems(input: {
   }));
 }
 
-export function buildThreadActionItems(input: {
-  threads: ReadonlyArray<
-    Pick<
-      SidebarThreadSummary,
-      "archivedAt" | "branch" | "createdAt" | "environmentId" | "id" | "projectId" | "title"
-    > & {
-      updatedAt?: string | undefined;
-      latestUserMessageAt?: string | null;
-    }
-  >;
+export type BuildThreadActionItemsThread = Pick<
+  SidebarThreadSummary,
+  "archivedAt" | "branch" | "createdAt" | "environmentId" | "id" | "projectId" | "title"
+> & {
+  updatedAt?: string | undefined;
+  latestUserMessageAt?: string | null;
+};
+
+export function buildThreadActionItems<TThread extends BuildThreadActionItemsThread>(input: {
+  threads: ReadonlyArray<TThread>;
   activeThreadId?: Thread["id"];
   projectTitleById: ReadonlyMap<Project["id"], string>;
   sortOrder: SidebarThreadSortOrder;
   icon: ReactNode;
+  /** Optional content rendered inline before the title text per-thread. */
+  renderLeadingContent?: (thread: TThread) => ReactNode;
+  /** Optional content rendered inline after the title text per-thread. */
+  renderTrailingContent?: (thread: TThread) => ReactNode;
   runThread: (thread: Pick<SidebarThreadSummary, "environmentId" | "id">) => Promise<void>;
   limit?: number;
 }): CommandPaletteActionItem[] {
@@ -108,18 +149,29 @@ export function buildThreadActionItems(input: {
       descriptionParts.push("Current thread");
     }
 
-    return {
-      kind: "action",
-      value: `thread:${thread.id}`,
-      searchTerms: [thread.title, projectTitle ?? "", thread.branch ?? ""],
-      title: thread.title,
-      description: descriptionParts.join(" · "),
-      timestamp: formatRelativeTimeLabel(thread.updatedAt ?? thread.createdAt),
-      icon: input.icon,
-      run: async () => {
-        await input.runThread(thread);
+    const leadingContent = input.renderLeadingContent?.(thread);
+    const trailingContent = input.renderTrailingContent?.(thread);
+
+    return Object.assign(
+      {
+        kind: "action" as const,
+        value: `thread:${thread.id}`,
+        searchTerms: [thread.title, projectTitle ?? ``, thread.branch ?? ``],
+        title: thread.title,
+        description: descriptionParts.join(` · `),
+        timestamp: formatRelativeTimeLabel(
+          thread.latestUserMessageAt ?? thread.updatedAt ?? thread.createdAt,
+        ),
+        icon: input.icon,
+      },
+      leadingContent ? { titleLeadingContent: leadingContent } : {},
+      trailingContent ? { titleTrailingContent: trailingContent } : {},
+      {
+        run: async () => {
+          await input.runThread(thread);
+        },
       },
-    };
+    );
   });
 }
 
@@ -228,10 +280,56 @@ export function filterCommandPaletteGroups(input: {
   });
 }
 
+export function buildBrowseGroups(input: {
+  browseEntries: ReadonlyArray<FilesystemBrowseEntry>;
+  browseQuery: string;
+  canBrowseUp: boolean;
+  upIcon: ReactNode;
+  directoryIcon: ReactNode;
+  browseUp: () => void;
+  browseTo: (name: string) => void;
+}): CommandPaletteGroup[] {
+  const items: CommandPaletteActionItem[] = [];
+
+  if (input.canBrowseUp) {
+    items.push({
+      kind: "action",
+      value: "browse:up",
+      searchTerms: [input.browseQuery, ".."],
+      title: "..",
+      icon: input.upIcon,
+      keepOpen: true,
+      run: async () => {
+        input.browseUp();
+      },
+    });
+  }
+
+  for (const entry of input.browseEntries) {
+    items.push({
+      kind: "action",
+      value: `browse:${entry.fullPath}`,
+      searchTerms: [input.browseQuery, entry.fullPath, entry.name],
+      title: entry.name,
+      icon: input.directoryIcon,
+      keepOpen: true,
+      run: async () => {
+        input.browseTo(entry.name);
+      },
+    });
+  }
+
+  return [{ value: "directories", label: "Directories", items }];
+}
+
 export function getCommandPaletteMode(input: {
   currentView: CommandPaletteView | null;
+  isBrowsing: boolean;
 }): CommandPaletteMode {
-  return input.currentView ? "submenu" : "root";
+  if (input.currentView) {
+    return input.isBrowsing ? "submenu-browse" : "submenu";
+  }
+  return input.isBrowsing ? "root-browse" : "root";
 }
 
 export function buildRootGroups(input: {
@@ -256,7 +354,11 @@ export function getCommandPaletteInputPlaceholder(mode: CommandPaletteMode): str
   switch (mode) {
     case "root":
       return "Search commands, projects, and threads...";
+    case "root-browse":
+      return "Enter project path (e.g. ~/projects/my-app)";
     case "submenu":
       return "Search...";
+    case "submenu-browse":
+      return "Enter path (e.g. ~/projects/my-app)";
   }
 }
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index 4028043f196..7862191d40b 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -1,19 +1,36 @@
 "use client";
 
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime";
-import type { ProjectId } from "@t3tools/contracts";
+import {
+  DEFAULT_MODEL,
+  type EnvironmentId,
+  type FilesystemBrowseResult,
+  type ProjectId,
+  ProviderInstanceId,
+  type SourceControlDiscoveryResult,
+  type SourceControlProviderKind,
+  type SourceControlRepositoryInfo,
+} from "@t3tools/contracts";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useParams } from "@tanstack/react-router";
+import * as Option from "effect/Option";
 import {
   ArrowDownIcon,
   ArrowLeftIcon,
   ArrowUpIcon,
+  CornerLeftUpIcon,
+  FolderIcon,
+  FolderPlusIcon,
+  LinkIcon,
   MessageSquareIcon,
   SettingsIcon,
   SquarePenIcon,
 } from "lucide-react";
 import {
+  useCallback,
   useDeferredValue,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -22,15 +39,41 @@ import {
 } from "react";
 import { useShallow } from "zustand/react/shallow";
 import { useCommandPaletteStore } from "../commandPaletteStore";
+import { readEnvironmentApi } from "../environmentApi";
+import { readPrimaryEnvironmentDescriptor, usePrimaryEnvironmentId } from "../environments/primary";
+import {
+  useSavedEnvironmentRegistryStore,
+  useSavedEnvironmentRuntimeStore,
+} from "../environments/runtime";
 import { useHandleNewThread } from "../hooks/useHandleNewThread";
 import { useSettings } from "../hooks/useSettings";
+import { readLocalApi } from "../localApi";
+import {
+  getSourceControlDiscoverySnapshot,
+  refreshSourceControlDiscovery,
+} from "../lib/sourceControlDiscoveryState";
 import {
   startNewThreadInProjectFromContext,
   startNewThreadFromContext,
 } from "../lib/chatThreadActions";
+import {
+  appendBrowsePathSegment,
+  canNavigateUp,
+  ensureBrowseDirectoryPath,
+  findProjectByPath,
+  getBrowseDirectoryPath,
+  getBrowseLeafPathSegment,
+  getBrowseParentPath,
+  hasTrailingPathSeparator,
+  inferProjectTitleFromPath,
+  isExplicitRelativeProjectPath,
+  isFilesystemBrowseQuery,
+  isUnsupportedWindowsProjectPath,
+  resolveProjectPathForDispatch,
+} from "../lib/projectPaths";
 import { isTerminalFocused } from "../lib/terminalFocus";
 import { getLatestThreadForProject } from "../lib/threadSort";
-import { cn } from "../lib/utils";
+import { cn, isMacPlatform, isWindowsPlatform, newCommandId, newProjectId } from "../lib/utils";
 import {
   selectProjectsAcrossEnvironments,
   selectSidebarThreadsAcrossEnvironments,
@@ -40,20 +83,25 @@ import { selectThreadTerminalState, useTerminalStateStore } from "../terminalSta
 import { buildThreadRouteParams, resolveThreadRouteTarget } from "../threadRoutes";
 import {
   ADDON_ICON_CLASS,
+  buildBrowseGroups,
   buildProjectActionItems,
   buildRootGroups,
   buildThreadActionItems,
   type CommandPaletteActionItem,
   type CommandPaletteSubmenuItem,
   type CommandPaletteView,
+  filterBrowseEntries,
   filterCommandPaletteGroups,
   getCommandPaletteInputPlaceholder,
   getCommandPaletteMode,
   ITEM_ICON_CLASS,
   RECENT_THREAD_LIMIT,
 } from "./CommandPalette.logic";
+import { resolveEnvironmentOptionLabel } from "./BranchToolbar.logic";
 import { CommandPaletteResults } from "./CommandPaletteResults";
+import { AzureDevOpsIcon, BitbucketIcon, GitHubIcon, GitLabIcon } from "./Icons";
 import { ProjectFavicon } from "./ProjectFavicon";
+import { ThreadRowLeadingStatus, ThreadRowTrailingStatus } from "./ThreadStatusIndicators";
 import { useServerKeybindings } from "../rpc/serverState";
 import { resolveShortcutCommand } from "../keybindings";
 import {
@@ -64,11 +112,220 @@ import {
   CommandInput,
   CommandPanel,
 } from "./ui/command";
+import { Button } from "./ui/button";
 import { Kbd, KbdGroup } from "./ui/kbd";
-import { toastManager } from "./ui/toast";
+import { stackedThreadToast, toastManager } from "./ui/toast";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
 import { ComposerHandleContext, useComposerHandleContext } from "../composerHandleContext";
 import type { ChatComposerHandle } from "./chat/ChatComposer";
 
+const EMPTY_BROWSE_ENTRIES: FilesystemBrowseResult["entries"] = [];
+const BROWSE_STALE_TIME_MS = 30_000;
+
+function getLocalFileManagerName(platform: string): string {
+  if (isMacPlatform(platform)) {
+    return "Finder";
+  }
+  if (isWindowsPlatform(platform)) {
+    return "Explorer";
+  }
+  return "Files";
+}
+
+function getEnvironmentBrowsePlatform(os: string | null | undefined): string {
+  if (os === "windows") {
+    return "Win32";
+  }
+  if (os === "darwin") {
+    return "MacIntel";
+  }
+  if (os === "linux") {
+    return "Linux";
+  }
+  return typeof navigator === "undefined" ? "" : navigator.platform;
+}
+
+interface AddProjectEnvironmentOption {
+  readonly environmentId: EnvironmentId;
+  readonly label: string;
+  readonly isPrimary: boolean;
+}
+
+type AddProjectRemoteProviderKind = Extract<
+  SourceControlProviderKind,
+  "github" | "gitlab" | "bitbucket" | "azure-devops"
+>;
+type AddProjectRemoteSource = AddProjectRemoteProviderKind | "url";
+
+type AddProjectCloneFlow =
+  | {
+      readonly step: "repository";
+      readonly environmentId: EnvironmentId;
+      readonly source: AddProjectRemoteSource;
+    }
+  | {
+      readonly step: "confirm";
+      readonly environmentId: EnvironmentId;
+      readonly source: AddProjectRemoteSource;
+      readonly repositoryInput: string;
+      readonly repository: SourceControlRepositoryInfo | null;
+      readonly remoteUrl: string;
+    };
+
+const REMOTE_PROJECT_SOURCES: ReadonlyArray<AddProjectRemoteSource> = [
+  "url",
+  "github",
+  "gitlab",
+  "bitbucket",
+  "azure-devops",
+];
+const REMOTE_PROJECT_PROVIDER_SOURCES: ReadonlyArray<AddProjectRemoteProviderKind> = [
+  "github",
+  "gitlab",
+  "bitbucket",
+  "azure-devops",
+];
+
+function remoteProjectSourceLabel(source: AddProjectRemoteSource): string {
+  switch (source) {
+    case "github":
+      return "GitHub";
+    case "gitlab":
+      return "GitLab";
+    case "bitbucket":
+      return "Bitbucket";
+    case "azure-devops":
+      return "Azure DevOps";
+    case "url":
+      return "Git URL";
+  }
+}
+
+function remoteProjectSourcePathHint(source: AddProjectRemoteSource): string {
+  switch (source) {
+    case "github":
+      return "owner/repo";
+    case "gitlab":
+      return "group/project";
+    case "bitbucket":
+      return "workspace/repository";
+    case "azure-devops":
+      return "project/repository";
+    case "url":
+      return "URL";
+  }
+}
+
+function remoteProjectSourceProvider(
+  source: AddProjectRemoteSource,
+): AddProjectRemoteProviderKind | null {
+  return source === "url" ? null : source;
+}
+
+function remoteProjectSourceIcon(source: AddProjectRemoteSource, className: string): ReactNode {
+  switch (source) {
+    case "github":
+      return <GitHubIcon className={className} />;
+    case "gitlab":
+      return <GitLabIcon className={className} />;
+    case "bitbucket":
+      return <BitbucketIcon className={className} />;
+    case "azure-devops":
+      return <AzureDevOpsIcon className={className} />;
+    case "url":
+      return <LinkIcon className={className} />;
+  }
+}
+
+function remoteProjectInputPlaceholder(flow: AddProjectCloneFlow | null): string | null {
+  if (!flow) return null;
+  if (flow.step === "confirm") return null;
+  if (flow.source === "url") {
+    return "Enter Git clone URL";
+  }
+  return `Enter ${remoteProjectSourceLabel(flow.source)} repository (${remoteProjectSourcePathHint(flow.source)})`;
+}
+
+function sourceProviderKind(source: AddProjectRemoteSource): AddProjectRemoteProviderKind | null {
+  return source === "url" ? null : source;
+}
+
+function sortAddProjectProviderSources(
+  readinessBySource: AddProjectRemoteSourceReadiness,
+): ReadonlyArray<AddProjectRemoteProviderKind> {
+  return REMOTE_PROJECT_PROVIDER_SOURCES.toSorted((left, right) => {
+    const leftReady = readinessBySource[left].ready;
+    const rightReady = readinessBySource[right].ready;
+    if (leftReady !== rightReady) {
+      return leftReady ? -1 : 1;
+    }
+    return remoteProjectSourceLabel(left).localeCompare(remoteProjectSourceLabel(right));
+  });
+}
+
+type AddProjectRemoteSourceReadiness = Record<
+  AddProjectRemoteSource,
+  { readonly ready: boolean; readonly hint: string | null }
+>;
+
+function buildAddProjectRemoteSourceReadiness(
+  discovery: SourceControlDiscoveryResult | null,
+): AddProjectRemoteSourceReadiness {
+  const unavailable = {
+    ready: false,
+    hint: "Provider status unavailable. Open Settings -> Source Control and rescan.",
+  } as const;
+  const defaultReadiness: AddProjectRemoteSourceReadiness = {
+    url: { ready: true, hint: null },
+    github: unavailable,
+    gitlab: unavailable,
+    bitbucket: unavailable,
+    "azure-devops": unavailable,
+  };
+
+  if (!discovery) {
+    return defaultReadiness;
+  }
+
+  const providerByKind = new Map(
+    discovery.sourceControlProviders.map((provider) => [provider.kind, provider]),
+  );
+  const readiness = { ...defaultReadiness };
+
+  for (const source of REMOTE_PROJECT_SOURCES) {
+    const kind = sourceProviderKind(source);
+    if (!kind) continue;
+    const provider = providerByKind.get(kind);
+    if (!provider) {
+      readiness[source] = unavailable;
+      continue;
+    }
+    if (provider.status !== "available") {
+      readiness[source] = { ready: false, hint: provider.installHint };
+      continue;
+    }
+    if (provider.auth.status === "unauthenticated") {
+      readiness[source] = {
+        ready: false,
+        hint:
+          Option.getOrNull(provider.auth.detail) ??
+          `${provider.label} is not authenticated. Open Settings -> Source Control for setup guidance.`,
+      };
+      continue;
+    }
+    readiness[source] = { ready: true, hint: null };
+  }
+
+  return readiness;
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+  return "An error occurred.";
+}
+
 export function CommandPalette({ children }: { children: ReactNode }) {
   const open = useCommandPaletteStore((store) => store.open);
   const setOpen = useCommandPaletteStore((store) => store.setOpen);
@@ -107,12 +364,12 @@ export function CommandPalette({ children }: { children: ReactNode }) {
   }, [keybindings, terminalOpen, toggleOpen]);
 
   return (
-    <ComposerHandleContext.Provider value={composerHandleRef}>
+    <ComposerHandleContext value={composerHandleRef}>
       <CommandDialog open={open} onOpenChange={setOpen}>
         {children}
         <CommandPaletteDialog />
       </CommandDialog>
-    </ComposerHandleContext.Provider>
+    </ComposerHandleContext>
   );
 }
 
@@ -136,10 +393,14 @@ function CommandPaletteDialog() {
 function OpenCommandPaletteDialog() {
   const navigate = useNavigate();
   const setOpen = useCommandPaletteStore((store) => store.setOpen);
+  const openIntent = useCommandPaletteStore((store) => store.openIntent);
+  const clearOpenIntent = useCommandPaletteStore((store) => store.clearOpenIntent);
   const composerHandleRef = useComposerHandleContext();
   const [query, setQuery] = useState("");
   const deferredQuery = useDeferredValue(query);
   const isActionsOnly = deferredQuery.startsWith(">");
+  const queryClient = useQueryClient();
+  const [highlightedItemValue, setHighlightedItemValue] = useState<string | null>(null);
   const settings = useSettings();
   const { activeDraftThread, activeThread, defaultProjectRef, handleNewThread } =
     useHandleNewThread();
@@ -148,15 +409,205 @@ function OpenCommandPaletteDialog() {
   const keybindings = useServerKeybindings();
   const [viewStack, setViewStack] = useState<CommandPaletteView[]>([]);
   const currentView = viewStack.at(-1) ?? null;
-  const paletteMode = getCommandPaletteMode({ currentView });
+  const [browseGeneration, setBrowseGeneration] = useState(0);
+  const [addProjectEnvironmentId, setAddProjectEnvironmentId] = useState<EnvironmentId | null>(
+    null,
+  );
+  const [isPickingProjectFolder, setIsPickingProjectFolder] = useState(false);
+  const [addProjectCloneFlow, setAddProjectCloneFlow] = useState<AddProjectCloneFlow | null>(null);
+  const [isRemoteProjectLookingUp, setIsRemoteProjectLookingUp] = useState(false);
+  const [isRemoteProjectCloning, setIsRemoteProjectCloning] = useState(false);
+  const primaryEnvironmentId = usePrimaryEnvironmentId();
+  const primaryEnvironmentLabel = readPrimaryEnvironmentDescriptor()?.label ?? null;
+  const savedEnvironmentRegistry = useSavedEnvironmentRegistryStore((state) => state.byId);
+  const savedEnvironmentRuntimeById = useSavedEnvironmentRuntimeStore((state) => state.byId);
+
+  const addProjectEnvironmentOptions = useMemo(() => {
+    const options: AddProjectEnvironmentOption[] = [];
+    const seenEnvironmentIds = new Set<EnvironmentId>();
+
+    if (primaryEnvironmentId) {
+      seenEnvironmentIds.add(primaryEnvironmentId);
+      options.push({
+        environmentId: primaryEnvironmentId,
+        label: resolveEnvironmentOptionLabel({
+          isPrimary: true,
+          environmentId: primaryEnvironmentId,
+          runtimeLabel: primaryEnvironmentLabel,
+        }),
+        isPrimary: true,
+      });
+    }
+
+    for (const record of Object.values(savedEnvironmentRegistry)) {
+      if (seenEnvironmentIds.has(record.environmentId)) {
+        continue;
+      }
+
+      const runtimeState = savedEnvironmentRuntimeById[record.environmentId];
+      options.push({
+        environmentId: record.environmentId,
+        label: resolveEnvironmentOptionLabel({
+          isPrimary: false,
+          environmentId: record.environmentId,
+          runtimeLabel: runtimeState?.descriptor?.label ?? null,
+          savedLabel: record.label,
+        }),
+        isPrimary: false,
+      });
+    }
 
+    options.sort((left, right) => {
+      if (left.isPrimary !== right.isPrimary) {
+        return left.isPrimary ? -1 : 1;
+      }
+      return left.label.localeCompare(right.label);
+    });
+
+    return options;
+  }, [
+    primaryEnvironmentId,
+    primaryEnvironmentLabel,
+    savedEnvironmentRegistry,
+    savedEnvironmentRuntimeById,
+  ]);
+  const defaultAddProjectEnvironmentId = addProjectEnvironmentOptions[0]?.environmentId ?? null;
+  const browseEnvironmentId = addProjectEnvironmentId ?? defaultAddProjectEnvironmentId;
+  const browseEnvironmentPlatform = useMemo(() => {
+    const os =
+      browseEnvironmentId && primaryEnvironmentId && browseEnvironmentId === primaryEnvironmentId
+        ? (readPrimaryEnvironmentDescriptor()?.platform.os ?? null)
+        : browseEnvironmentId
+          ? (savedEnvironmentRuntimeById[browseEnvironmentId]?.descriptor?.platform.os ??
+            savedEnvironmentRuntimeById[browseEnvironmentId]?.serverConfig?.environment.platform
+              .os ??
+            null)
+          : null;
+    return getEnvironmentBrowsePlatform(os);
+  }, [browseEnvironmentId, primaryEnvironmentId, savedEnvironmentRuntimeById]);
+  const isRemoteProjectCloneFlow = addProjectCloneFlow !== null;
+  const isRemoteProjectRepositoryStep = addProjectCloneFlow?.step === "repository";
+  const isBrowsing =
+    !isRemoteProjectRepositoryStep && isFilesystemBrowseQuery(query, browseEnvironmentPlatform);
+  const paletteMode = getCommandPaletteMode({ currentView, isBrowsing });
+  const getAddProjectInitialQueryForEnvironment = useCallback(
+    (environmentId: EnvironmentId | null): string => {
+      const environmentSettings =
+        environmentId && primaryEnvironmentId && environmentId === primaryEnvironmentId
+          ? settings
+          : environmentId
+            ? savedEnvironmentRuntimeById[environmentId]?.serverConfig?.settings
+            : null;
+      const baseDirectory = environmentSettings?.addProjectBaseDirectory?.trim() ?? "";
+      if (baseDirectory.length === 0) {
+        return "~/";
+      }
+      return ensureBrowseDirectoryPath(baseDirectory);
+    },
+    [primaryEnvironmentId, savedEnvironmentRuntimeById, settings],
+  );
+
+  const projectCwdById = useMemo(
+    () => new Map<ProjectId, string>(projects.map((project) => [project.id, project.cwd])),
+    [projects],
+  );
   const projectTitleById = useMemo(
     () => new Map<ProjectId, string>(projects.map((project) => [project.id, project.name])),
     [projects],
   );
 
   const activeThreadId = activeThread?.id;
+  const currentProjectEnvironmentId =
+    activeThread?.environmentId ?? activeDraftThread?.environmentId ?? null;
   const currentProjectId = activeThread?.projectId ?? activeDraftThread?.projectId ?? null;
+  const currentProjectCwd = currentProjectId
+    ? (projectCwdById.get(currentProjectId) ?? null)
+    : null;
+  const currentProjectCwdForBrowse =
+    browseEnvironmentId && currentProjectEnvironmentId === browseEnvironmentId
+      ? currentProjectCwd
+      : null;
+  const relativePathNeedsActiveProject =
+    isExplicitRelativeProjectPath(query.trim()) && currentProjectCwdForBrowse === null;
+  const browseDirectoryPath = isBrowsing ? getBrowseDirectoryPath(query) : "";
+  const browseFilterQuery =
+    isBrowsing && !hasTrailingPathSeparator(query) ? getBrowseLeafPathSegment(query) : "";
+
+  const fetchBrowseResult = useCallback(
+    async (partialPath: string): Promise<FilesystemBrowseResult | null> => {
+      if (!browseEnvironmentId) return null;
+      const api = readEnvironmentApi(browseEnvironmentId);
+      if (!api) return null;
+      return api.filesystem.browse({
+        partialPath,
+        ...(currentProjectCwdForBrowse ? { cwd: currentProjectCwdForBrowse } : {}),
+      });
+    },
+    [browseEnvironmentId, currentProjectCwdForBrowse],
+  );
+
+  const { data: browseResult, isPending: isBrowsePending } = useQuery({
+    queryKey: [
+      "filesystemBrowse",
+      browseEnvironmentId,
+      browseDirectoryPath,
+      currentProjectCwdForBrowse,
+    ],
+    queryFn: () => fetchBrowseResult(browseDirectoryPath),
+    staleTime: BROWSE_STALE_TIME_MS,
+    enabled:
+      isBrowsing &&
+      browseDirectoryPath.length > 0 &&
+      browseEnvironmentId !== null &&
+      !relativePathNeedsActiveProject,
+  });
+  const browseEntries = browseResult?.entries ?? EMPTY_BROWSE_ENTRIES;
+  const {
+    filteredEntries: filteredBrowseEntries,
+    highlightedEntry: highlightedBrowseEntry,
+    exactEntry: exactBrowseEntry,
+  } = useMemo(
+    () => filterBrowseEntries({ browseEntries, browseFilterQuery, highlightedItemValue }),
+    [browseEntries, browseFilterQuery, highlightedItemValue],
+  );
+
+  const prefetchBrowsePath = useCallback(
+    (partialPath: string) => {
+      void queryClient.prefetchQuery({
+        queryKey: [
+          "filesystemBrowse",
+          browseEnvironmentId,
+          partialPath,
+          currentProjectCwdForBrowse,
+        ],
+        queryFn: () => fetchBrowseResult(partialPath),
+        staleTime: BROWSE_STALE_TIME_MS,
+      });
+    },
+    [browseEnvironmentId, currentProjectCwdForBrowse, fetchBrowseResult, queryClient],
+  );
+
+  // Prefetch the parent and the most likely next child so browse navigation
+  // stays warm without scanning every child directory in large trees.
+  useEffect(() => {
+    if (!isBrowsing || filteredBrowseEntries.length === 0) return;
+
+    if (canNavigateUp(query)) {
+      prefetchBrowsePath(getBrowseParentPath(query)!);
+    }
+
+    const nextChild = highlightedBrowseEntry ?? exactBrowseEntry;
+    if (nextChild) {
+      prefetchBrowsePath(appendBrowsePathSegment(query, nextChild.name));
+    }
+  }, [
+    exactBrowseEntry,
+    filteredBrowseEntries.length,
+    highlightedBrowseEntry,
+    isBrowsing,
+    prefetchBrowsePath,
+    query,
+  ]);
 
   const openProjectFromSearch = useMemo(
     () => async (project: (typeof projects)[number]) => {
@@ -248,6 +699,8 @@ function OpenCommandPaletteDialog() {
         projectTitleById,
         sortOrder: settings.sidebarThreadSortOrder,
         icon: <MessageSquareIcon className={ITEM_ICON_CLASS} />,
+        renderLeadingContent: (thread) => <ThreadRowLeadingStatus thread={thread} />,
+        renderTrailingContent: (thread) => <ThreadRowTrailingStatus thread={thread} />,
         runThread: async (thread) => {
           await navigate({
             to: "/$environmentId/$threadId",
@@ -259,30 +712,273 @@ function OpenCommandPaletteDialog() {
   );
   const recentThreadItems = allThreadItems.slice(0, RECENT_THREAD_LIMIT);
 
-  function pushView(item: CommandPaletteSubmenuItem): void {
+  function pushPaletteView(view: CommandPaletteView): void {
     setViewStack((previousViews) => [
       ...previousViews,
       {
-        addonIcon: item.addonIcon,
-        groups: item.groups,
-        ...(item.initialQuery ? { initialQuery: item.initialQuery } : {}),
+        addonIcon: view.addonIcon,
+        groups: view.groups,
+        ...(view.initialQuery ? { initialQuery: view.initialQuery } : {}),
       },
     ]);
-    setQuery(item.initialQuery ?? "");
+    setHighlightedItemValue(null);
+    setQuery(view.initialQuery ?? "");
+  }
+
+  function pushView(item: CommandPaletteSubmenuItem): void {
+    pushPaletteView({
+      addonIcon: item.addonIcon,
+      groups: item.groups,
+      ...(item.initialQuery ? { initialQuery: item.initialQuery } : {}),
+    });
   }
 
   function popView(): void {
+    setAddProjectCloneFlow(null);
+    if (viewStack.length <= 1) {
+      setAddProjectEnvironmentId(null);
+    }
     setViewStack((previousViews) => previousViews.slice(0, -1));
+    setHighlightedItemValue(null);
     setQuery("");
   }
 
   function handleQueryChange(nextQuery: string): void {
+    setHighlightedItemValue(null);
     setQuery(nextQuery);
     if (nextQuery === "" && currentView?.initialQuery) {
       popView();
     }
   }
 
+  const startAddProjectBrowse = useCallback(
+    (environmentId: EnvironmentId): void => {
+      setAddProjectEnvironmentId(environmentId);
+      setAddProjectCloneFlow(null);
+      pushPaletteView({
+        addonIcon: <FolderPlusIcon className={ADDON_ICON_CLASS} />,
+        groups: [],
+        initialQuery: getAddProjectInitialQueryForEnvironment(environmentId),
+      });
+    },
+    [getAddProjectInitialQueryForEnvironment],
+  );
+
+  const startAddProjectClone = useCallback(
+    (environmentId: EnvironmentId, source: AddProjectRemoteSource): void => {
+      setAddProjectEnvironmentId(environmentId);
+      setAddProjectCloneFlow({ step: "repository", environmentId, source });
+      pushPaletteView({
+        addonIcon: remoteProjectSourceIcon(source, ADDON_ICON_CLASS),
+        groups: [],
+        initialQuery: "",
+      });
+    },
+    [],
+  );
+
+  const openSourceControlSettings = useCallback(() => {
+    setOpen(false);
+    void navigate({ to: "/settings/source-control" });
+  }, [navigate, setOpen]);
+
+  const buildAddProjectSourceGroups = useCallback(
+    (
+      environmentId: EnvironmentId,
+      readinessBySource: AddProjectRemoteSourceReadiness,
+    ): CommandPaletteView["groups"] => {
+      const sourceItems: Array<CommandPaletteActionItem | CommandPaletteSubmenuItem> = [
+        {
+          kind: "action",
+          value: `action:add-project:${environmentId}:local`,
+          searchTerms: ["local", "folder", "directory", "browse"],
+          title: "Local folder",
+          description: "Browse a folder on disk",
+          icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
+          keepOpen: true,
+          run: async () => {
+            startAddProjectBrowse(environmentId);
+          },
+        },
+      ];
+
+      const orderedSources: ReadonlyArray<AddProjectRemoteSource> = [
+        "url",
+        ...sortAddProjectProviderSources(readinessBySource),
+      ];
+
+      for (const source of orderedSources) {
+        const label = remoteProjectSourceLabel(source);
+        const title = source === "url" ? "Git URL" : `${label} repository`;
+        const description =
+          source === "url"
+            ? "Clone from a remote URL"
+            : `Clone ${label} ${remoteProjectSourcePathHint(source)}`;
+        const readiness = readinessBySource[source];
+        const disabledHint = readiness.hint;
+
+        const titleTrailingContent = readiness.ready ? undefined : (
+          <span className="ml-auto">
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <Button
+                    variant="outline"
+                    size="xs"
+                    className="h-5 rounded-[.25rem] px-1.5 text-[10px] text-warning-foreground"
+                    onClick={() => {
+                      openSourceControlSettings();
+                    }}
+                  >
+                    Setup Required
+                  </Button>
+                }
+              />
+              <TooltipPopup align="end" side="left">
+                {disabledHint ?? "Open Settings -> Source Control to configure this provider."}
+              </TooltipPopup>
+            </Tooltip>
+          </span>
+        );
+
+        if (!readiness.ready) {
+          sourceItems.push({
+            kind: "action",
+            value: `action:add-project:${environmentId}:${source}:not-ready`,
+            searchTerms: ["clone", "remote", "repository", "repo", "git", label, "setup required"],
+            title,
+            description,
+            disabled: true,
+            icon: remoteProjectSourceIcon(source, ITEM_ICON_CLASS),
+            ...(titleTrailingContent ? { titleTrailingContent } : {}),
+            run: async () => {},
+          });
+          continue;
+        }
+
+        sourceItems.push({
+          kind: "action",
+          value: `action:add-project:${environmentId}:${source}`,
+          searchTerms: ["clone", "remote", "repository", "repo", "git", label],
+          title,
+          description,
+          icon: remoteProjectSourceIcon(source, ITEM_ICON_CLASS),
+          ...(titleTrailingContent ? { titleTrailingContent } : {}),
+          keepOpen: true,
+          run: async () => {
+            startAddProjectClone(environmentId, source);
+          },
+        });
+      }
+
+      return [{ value: `sources:${environmentId}`, label: "Sources", items: sourceItems }];
+    },
+    [openSourceControlSettings, startAddProjectBrowse, startAddProjectClone],
+  );
+
+  const startAddProjectSourceSelection = useCallback(
+    (environmentId: EnvironmentId): void => {
+      setAddProjectEnvironmentId(environmentId);
+      setAddProjectCloneFlow(null);
+      const target = { environmentId };
+      const initialDiscovery = getSourceControlDiscoverySnapshot(target).data;
+      pushPaletteView({
+        addonIcon: <FolderPlusIcon className={ADDON_ICON_CLASS} />,
+        groups: buildAddProjectSourceGroups(
+          environmentId,
+          buildAddProjectRemoteSourceReadiness(initialDiscovery),
+        ),
+      });
+
+      if (initialDiscovery) {
+        return;
+      }
+
+      void refreshSourceControlDiscovery(target).then((discovery) => {
+        setViewStack((previousViews) => {
+          const currentTopView = previousViews.at(-1);
+          if (currentTopView?.groups[0]?.value !== `sources:${environmentId}`) {
+            return previousViews;
+          }
+          return [
+            ...previousViews.slice(0, -1),
+            {
+              addonIcon: <FolderPlusIcon className={ADDON_ICON_CLASS} />,
+              groups: buildAddProjectSourceGroups(
+                environmentId,
+                buildAddProjectRemoteSourceReadiness(discovery),
+              ),
+            },
+          ];
+        });
+      });
+    },
+    [buildAddProjectSourceGroups],
+  );
+
+  const addProjectEnvironmentItems: CommandPaletteActionItem[] = addProjectEnvironmentOptions.map(
+    (option) => ({
+      kind: "action",
+      value: `action:add-project:environment:${option.environmentId}`,
+      searchTerms: [option.label, option.environmentId, option.isPrimary ? "this device" : ""],
+      title: option.label,
+      description: option.isPrimary ? "This device" : option.environmentId,
+      icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
+      keepOpen: true,
+      run: async () => {
+        startAddProjectSourceSelection(option.environmentId);
+      },
+    }),
+  );
+
+  const addProjectEnvironmentGroups = useMemo<CommandPaletteView["groups"]>(
+    () => [
+      {
+        value: "environments",
+        label: "Environments",
+        items: addProjectEnvironmentItems,
+      },
+    ],
+    [addProjectEnvironmentItems],
+  );
+
+  const openAddProjectFlow = useCallback(() => {
+    if (addProjectEnvironmentOptions.length > 1) {
+      pushPaletteView({
+        addonIcon: <FolderPlusIcon className={ADDON_ICON_CLASS} />,
+        groups: addProjectEnvironmentGroups,
+      });
+      return;
+    }
+
+    const environmentId = defaultAddProjectEnvironmentId;
+    if (!environmentId) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Unable to browse projects",
+          description: "No environment is available.",
+        }),
+      );
+      return;
+    }
+
+    void startAddProjectSourceSelection(environmentId);
+  }, [
+    addProjectEnvironmentGroups,
+    addProjectEnvironmentOptions.length,
+    defaultAddProjectEnvironmentId,
+    startAddProjectSourceSelection,
+  ]);
+
+  useLayoutEffect(() => {
+    if (openIntent?.kind !== "add-project") {
+      return;
+    }
+    clearOpenIntent();
+    openAddProjectFlow();
+  }, [clearOpenIntent, openAddProjectFlow, openIntent]);
+
   const actionItems: Array<CommandPaletteActionItem | CommandPaletteSubmenuItem> = [];
 
   if (projects.length > 0) {
@@ -325,6 +1021,35 @@ function OpenCommandPaletteDialog() {
     });
   }
 
+  actionItems.push({
+    kind: "action",
+    value: "action:add-project",
+    searchTerms: [
+      "add project",
+      "folder",
+      "directory",
+      "browse",
+      "clone",
+      "remote",
+      "repository",
+      "repo",
+      "git",
+      "github",
+      "gitlab",
+      "bitbucket",
+      "azure",
+      "devops",
+      "url",
+      "environment",
+    ],
+    title: "Add project",
+    icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
+    keepOpen: true,
+    run: async () => {
+      openAddProjectFlow();
+    },
+  });
+
   actionItems.push({
     kind: "action",
     value: "action:settings",
@@ -339,7 +1064,7 @@ function OpenCommandPaletteDialog() {
   const rootGroups = buildRootGroups({ actionItems, recentThreadItems });
   const activeGroups = currentView ? currentView.groups : rootGroups;
 
-  const displayedGroups = filterCommandPaletteGroups({
+  const filteredGroups = filterCommandPaletteGroups({
     activeGroups,
     query: deferredQuery,
     isInSubmenu: currentView !== null,
@@ -347,10 +1072,395 @@ function OpenCommandPaletteDialog() {
     threadSearchItems: allThreadItems,
   });
 
-  const inputPlaceholder = getCommandPaletteInputPlaceholder(paletteMode);
-  const isSubmenu = paletteMode === "submenu";
+  const handleAddProject = useCallback(
+    async (rawCwd: string) => {
+      if (!browseEnvironmentId) return;
+      const api = readEnvironmentApi(browseEnvironmentId);
+      if (!api) return;
+
+      if (isUnsupportedWindowsProjectPath(rawCwd.trim(), browseEnvironmentPlatform)) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to add project",
+            description: "Windows-style paths are only supported on Windows.",
+          }),
+        );
+        return;
+      }
+
+      if (isExplicitRelativeProjectPath(rawCwd.trim()) && !currentProjectCwdForBrowse) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to add project",
+            description: "Relative paths require an active project.",
+          }),
+        );
+        return;
+      }
+
+      const cwd = resolveProjectPathForDispatch(rawCwd, currentProjectCwdForBrowse);
+      if (cwd.length === 0) return;
+
+      const existing = findProjectByPath(
+        projects.filter((project) => project.environmentId === browseEnvironmentId),
+        cwd,
+      );
+      if (existing) {
+        const latestThread = getLatestThreadForProject(
+          threads.filter((thread) => thread.environmentId === existing.environmentId),
+          existing.id,
+          settings.sidebarThreadSortOrder,
+        );
+        if (latestThread) {
+          await navigate({
+            to: "/$environmentId/$threadId",
+            params: buildThreadRouteParams(
+              scopeThreadRef(latestThread.environmentId, latestThread.id),
+            ),
+          });
+        } else {
+          await handleNewThread(scopeProjectRef(existing.environmentId, existing.id), {
+            envMode: settings.defaultThreadEnvMode,
+          }).catch(() => undefined);
+        }
+        setOpen(false);
+        return;
+      }
+
+      try {
+        const projectId = newProjectId();
+        await api.orchestration.dispatchCommand({
+          type: "project.create",
+          commandId: newCommandId(),
+          projectId,
+          title: inferProjectTitleFromPath(cwd),
+          workspaceRoot: cwd,
+          createWorkspaceRootIfMissing: true,
+          defaultModelSelection: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: DEFAULT_MODEL,
+          },
+          createdAt: new Date().toISOString(),
+        });
+        await handleNewThread(scopeProjectRef(browseEnvironmentId, projectId), {
+          envMode: settings.defaultThreadEnvMode,
+        }).catch(() => undefined);
+        setOpen(false);
+      } catch (error) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to add project",
+            description: error instanceof Error ? error.message : "An error occurred.",
+          }),
+        );
+      }
+    },
+    [
+      browseEnvironmentId,
+      browseEnvironmentPlatform,
+      currentProjectCwdForBrowse,
+      handleNewThread,
+      navigate,
+      projects,
+      setOpen,
+      settings.defaultThreadEnvMode,
+      settings.sidebarThreadSortOrder,
+      threads,
+    ],
+  );
+
+  function getDefaultCloneParentPath(environmentId: EnvironmentId): string {
+    return getAddProjectInitialQueryForEnvironment(environmentId);
+  }
+
+  async function submitAddProjectCloneFlow(destinationPathInput?: string): Promise<void> {
+    if (!addProjectCloneFlow) {
+      return;
+    }
+
+    const api = readEnvironmentApi(addProjectCloneFlow.environmentId);
+    if (!api) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Unable to clone project",
+          description: "Environment API is not available.",
+        }),
+      );
+      return;
+    }
+
+    if (addProjectCloneFlow.step === "repository") {
+      const rawRepository = query.trim();
+      if (rawRepository.length === 0 || isRemoteProjectLookingUp) {
+        return;
+      }
+
+      const provider = remoteProjectSourceProvider(addProjectCloneFlow.source);
+      if (!provider) {
+        const destinationPath = getDefaultCloneParentPath(addProjectCloneFlow.environmentId);
+        setAddProjectCloneFlow({
+          step: "confirm",
+          environmentId: addProjectCloneFlow.environmentId,
+          source: addProjectCloneFlow.source,
+          repositoryInput: rawRepository,
+          repository: null,
+          remoteUrl: rawRepository,
+        });
+        setHighlightedItemValue(null);
+        setQuery(destinationPath);
+        setBrowseGeneration((generation) => generation + 1);
+        return;
+      }
+
+      setIsRemoteProjectLookingUp(true);
+      try {
+        const repository = await api.sourceControl.lookupRepository({
+          provider,
+          repository: rawRepository,
+        });
+        const destinationPath = getDefaultCloneParentPath(addProjectCloneFlow.environmentId);
+        setAddProjectCloneFlow({
+          step: "confirm",
+          environmentId: addProjectCloneFlow.environmentId,
+          source: addProjectCloneFlow.source,
+          repositoryInput: rawRepository,
+          repository,
+          remoteUrl: repository.sshUrl,
+        });
+        setHighlightedItemValue(null);
+        setQuery(destinationPath);
+        setBrowseGeneration((generation) => generation + 1);
+      } catch (error) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Repository lookup failed",
+            description: errorMessage(error),
+          }),
+        );
+      } finally {
+        setIsRemoteProjectLookingUp(false);
+      }
+      return;
+    }
+
+    const rawDestination = (destinationPathInput ?? query).trim();
+    if (rawDestination.length === 0 || isRemoteProjectCloning) {
+      return;
+    }
+
+    if (isUnsupportedWindowsProjectPath(rawDestination, browseEnvironmentPlatform)) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Clone failed",
+          description: "Windows-style paths are only supported on Windows.",
+        }),
+      );
+      return;
+    }
+
+    if (isExplicitRelativeProjectPath(rawDestination) && !currentProjectCwdForBrowse) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Clone failed",
+          description: "Relative paths require an active project.",
+        }),
+      );
+      return;
+    }
+
+    const destinationPath = resolveProjectPathForDispatch(
+      rawDestination,
+      currentProjectCwdForBrowse,
+    );
+    if (destinationPath.length === 0) {
+      return;
+    }
+
+    setIsRemoteProjectCloning(true);
+    try {
+      const result = await api.sourceControl.cloneRepository({
+        remoteUrl: addProjectCloneFlow.remoteUrl,
+        destinationPath,
+      });
+      await handleAddProject(result.cwd);
+    } catch (error) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Clone failed",
+          description: errorMessage(error),
+        }),
+      );
+    } finally {
+      setIsRemoteProjectCloning(false);
+    }
+  }
+
+  function browseTo(name: string): void {
+    const nextQuery = appendBrowsePathSegment(query, name);
+    setHighlightedItemValue(null);
+    setQuery(nextQuery);
+    setBrowseGeneration((generation) => generation + 1);
+  }
+
+  function browseUp(): void {
+    const parentPath = getBrowseParentPath(query);
+    if (parentPath === null) {
+      return;
+    }
+
+    setHighlightedItemValue(null);
+    setQuery(parentPath);
+    setBrowseGeneration((generation) => generation + 1);
+  }
+
+  // Resolve the add-project path from browse data when available. When the
+  // query has a trailing separator (e.g. "~/projects/foo/"), parentPath is the
+  // directory itself. Otherwise the user typed a partial leaf name, so we need
+  // the exact browse entry's fullPath or fall back to the raw query.
+  const resolvedAddProjectPath = hasTrailingPathSeparator(query)
+    ? (browseResult?.parentPath ?? query.trim())
+    : (exactBrowseEntry?.fullPath ?? query.trim());
+
+  const canBrowseUp =
+    isBrowsing && !relativePathNeedsActiveProject && canNavigateUp(browseDirectoryPath);
+
+  const browseGroups = buildBrowseGroups({
+    browseEntries: filteredBrowseEntries,
+    browseQuery: query,
+    canBrowseUp,
+    upIcon: <CornerLeftUpIcon className={ITEM_ICON_CLASS} />,
+    directoryIcon: <FolderIcon className={ITEM_ICON_CLASS} />,
+    browseUp,
+    browseTo,
+  });
+  const cloneDestinationBrowseGroups = useMemo(
+    () =>
+      browseGroups.map((group) =>
+        group.value === "directories" ? { ...group, label: "Select where to clone" } : group,
+      ),
+    [browseGroups],
+  );
+
+  const remoteProjectContext = useMemo(() => {
+    if (addProjectCloneFlow?.step !== "confirm") {
+      return null;
+    }
+
+    return {
+      title: addProjectCloneFlow.repository?.nameWithOwner ?? addProjectCloneFlow.repositoryInput,
+      description: addProjectCloneFlow.repository?.url ?? addProjectCloneFlow.remoteUrl,
+      icon: remoteProjectSourceIcon(addProjectCloneFlow.source, ITEM_ICON_CLASS),
+    };
+  }, [addProjectCloneFlow]);
+
+  let displayedGroups: CommandPaletteView["groups"] = filteredGroups;
+  if (addProjectCloneFlow?.step === "repository") {
+    displayedGroups = [];
+  } else if (addProjectCloneFlow?.step === "confirm") {
+    displayedGroups = relativePathNeedsActiveProject ? [] : cloneDestinationBrowseGroups;
+  } else if (isBrowsing) {
+    displayedGroups = relativePathNeedsActiveProject ? [] : browseGroups;
+  }
+
+  const inputPlaceholder =
+    remoteProjectInputPlaceholder(addProjectCloneFlow) ??
+    getCommandPaletteInputPlaceholder(paletteMode);
+  const isSubmenu = paletteMode === "submenu" || paletteMode === "submenu-browse";
+  const hasHighlightedBrowseItem = highlightedItemValue?.startsWith("browse:") ?? false;
+  const canSubmitBrowsePath = isBrowsing && !relativePathNeedsActiveProject;
+  const willCreateProjectPath =
+    canSubmitBrowsePath &&
+    !isBrowsePending &&
+    query.trim().length > 0 &&
+    !hasHighlightedBrowseItem &&
+    (hasTrailingPathSeparator(query) ? !browseResult : exactBrowseEntry === null);
+  const useMetaForMod = isMacPlatform(navigator.platform);
+  const submitModifierLabel = useMetaForMod ? "\u2318" : "Ctrl";
+  const isCloneDestinationStep = addProjectCloneFlow?.step === "confirm";
+  const submitActionLabel = isCloneDestinationStep
+    ? willCreateProjectPath
+      ? "Create & Clone"
+      : "Clone"
+    : willCreateProjectPath
+      ? "Create & Add"
+      : "Add";
+  const addShortcutLabel = hasHighlightedBrowseItem ? `${submitModifierLabel} Enter` : "Enter";
+  const remoteProjectButtonLabel = addProjectCloneFlow
+    ? addProjectCloneFlow.source === "url"
+      ? "Continue"
+      : "Lookup"
+    : null;
+  const isRemoteProjectPending = isRemoteProjectLookingUp || isRemoteProjectCloning;
+  const canSubmitRemoteProjectFlow =
+    addProjectCloneFlow?.step === "repository" &&
+    query.trim().length > 0 &&
+    !isRemoteProjectPending;
+  const fileManagerName = getLocalFileManagerName(navigator.platform);
+  const canOpenProjectFromFileManager =
+    isBrowsing &&
+    browseEnvironmentId !== null &&
+    primaryEnvironmentId !== null &&
+    browseEnvironmentId === primaryEnvironmentId &&
+    typeof window !== "undefined" &&
+    window.desktopBridge !== undefined;
+  const fileManagerInitialPath = useMemo(() => {
+    if (!canOpenProjectFromFileManager) {
+      return undefined;
+    }
+
+    const trimmedQuery = query.trim();
+    if (trimmedQuery.length === 0) {
+      return undefined;
+    }
+
+    const initialPath = hasTrailingPathSeparator(query)
+      ? (browseResult?.parentPath ?? trimmedQuery)
+      : browseDirectoryPath || trimmedQuery;
+
+    const resolvedPath = resolveProjectPathForDispatch(initialPath, currentProjectCwdForBrowse);
+    return resolvedPath.length > 0 ? resolvedPath : undefined;
+  }, [
+    browseDirectoryPath,
+    browseResult?.parentPath,
+    canOpenProjectFromFileManager,
+    currentProjectCwdForBrowse,
+    query,
+  ]);
+
+  function isPrimaryModifierPressed(event: KeyboardEvent<HTMLInputElement>): boolean {
+    return useMetaForMod ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey;
+  }
 
   function handleKeyDown(event: KeyboardEvent<HTMLInputElement>): void {
+    if (addProjectCloneFlow?.step === "repository" && event.key === "Enter") {
+      event.preventDefault();
+      void submitAddProjectCloneFlow();
+      return;
+    }
+
+    const shouldSubmitBrowsePath =
+      canSubmitBrowsePath &&
+      event.key === "Enter" &&
+      (!hasHighlightedBrowseItem || isPrimaryModifierPressed(event));
+
+    if (shouldSubmitBrowsePath) {
+      event.preventDefault();
+      if (isCloneDestinationStep) {
+        void submitAddProjectCloneFlow(resolvedAddProjectPath);
+      } else {
+        void handleAddProject(resolvedAddProjectPath);
+      }
+      return;
+    }
+
     if (event.key === "Backspace" && query === "" && isSubmenu) {
       event.preventDefault();
       popView();
@@ -358,6 +1468,10 @@ function OpenCommandPaletteDialog() {
   }
 
   function executeItem(item: CommandPaletteActionItem | CommandPaletteSubmenuItem): void {
+    if (item.disabled) {
+      return;
+    }
+
     if (item.kind === "submenu") {
       pushView(item);
       return;
@@ -368,14 +1482,48 @@ function OpenCommandPaletteDialog() {
     }
 
     void item.run().catch((error: unknown) => {
-      toastManager.add({
-        type: "error",
-        title: "Unable to run command",
-        description: error instanceof Error ? error.message : "An unexpected error occurred.",
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Unable to run command",
+          description: error instanceof Error ? error.message : "An unexpected error occurred.",
+        }),
+      );
     });
   }
 
+  const handleOpenProjectFromFileManager = useCallback(async () => {
+    if (!canOpenProjectFromFileManager || isPickingProjectFolder) {
+      return;
+    }
+    const api = readLocalApi();
+    if (!api) {
+      return;
+    }
+
+    setIsPickingProjectFolder(true);
+    let pickedPath: string | null = null;
+    try {
+      pickedPath = await api.dialogs.pickFolder(
+        fileManagerInitialPath ? { initialPath: fileManagerInitialPath } : undefined,
+      );
+    } catch {
+      // Ignore picker failures and leave the palette open.
+      setIsPickingProjectFolder(false);
+      return;
+    }
+    setIsPickingProjectFolder(false);
+    if (!pickedPath) {
+      return;
+    }
+    await handleAddProject(pickedPath);
+  }, [
+    canOpenProjectFromFileManager,
+    fileManagerInitialPath,
+    handleAddProject,
+    isPickingProjectFolder,
+  ]);
+
   return (
     <CommandDialogPopup
       aria-label="Command palette"
@@ -385,44 +1533,156 @@ function OpenCommandPaletteDialog() {
         composerHandleRef?.current?.focusAtEnd();
         return false;
       }}
+      onBackdropPointerDown={() => {
+        setOpen(false);
+      }}
     >
       <Command
-        key={viewStack.length}
+        key={`${viewStack.length}-${browseGeneration}-${isBrowsing}-${addProjectCloneFlow?.step ?? "none"}`}
         aria-label="Command palette"
-        autoHighlight="always"
+        autoHighlight={isBrowsing || isRemoteProjectCloneFlow ? false : "always"}
         mode="none"
+        onItemHighlighted={(value) => {
+          setHighlightedItemValue(typeof value === "string" ? value : null);
+        }}
         onValueChange={handleQueryChange}
         value={query}
       >
-        <CommandInput
-          placeholder={inputPlaceholder}
-          wrapperClassName={
-            isSubmenu
-              ? "[&_[data-slot=autocomplete-start-addon]]:pointer-events-auto [&_[data-slot=autocomplete-start-addon]]:cursor-pointer"
-              : undefined
-          }
-          {...(isSubmenu
-            ? {
-                startAddon: (
-                  <button
-                    type="button"
-                    className="flex cursor-pointer items-center"
-                    aria-label="Back"
-                    onClick={popView}
-                  >
-                    <ArrowLeftIcon />
-                  </button>
-                ),
+        <div className="relative">
+          <CommandInput
+            className={
+              addProjectCloneFlow?.step === "repository"
+                ? "pe-32"
+                : isBrowsing
+                  ? willCreateProjectPath
+                    ? "pe-36"
+                    : "pe-16"
+                  : undefined
+            }
+            placeholder={inputPlaceholder}
+            wrapperClassName={
+              isSubmenu ? "[&_[data-slot=autocomplete-start-addon]]:pointer-events-auto" : undefined
+            }
+            {...(isSubmenu
+              ? {
+                  startAddon: (
+                    <button
+                      type="button"
+                      className="flex cursor-pointer items-center"
+                      aria-label="Back"
+                      onClick={popView}
+                    >
+                      <ArrowLeftIcon />
+                    </button>
+                  ),
+                }
+              : isBrowsing && !isSubmenu
+                ? {
+                    startAddon: <FolderPlusIcon />,
+                  }
+                : {})}
+            onKeyDown={handleKeyDown}
+          />
+          {addProjectCloneFlow?.step === "repository" ? (
+            <Button
+              variant="outline"
+              size="xs"
+              tabIndex={-1}
+              className="absolute inset-e-2.5 top-1/2 gap-1.5 pe-1 ps-2 -translate-y-1/2"
+              aria-label={`${remoteProjectButtonLabel ?? "Continue"} (Enter)`}
+              disabled={!canSubmitRemoteProjectFlow}
+              onMouseDown={(event) => {
+                event.preventDefault();
+              }}
+              onClick={() => {
+                void submitAddProjectCloneFlow();
+              }}
+              title={`${remoteProjectButtonLabel ?? "Continue"} (Enter)`}
+            >
+              <span>{isRemoteProjectPending ? "Working" : remoteProjectButtonLabel}</span>
+              <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
+                <Kbd>Enter</Kbd>
+              </KbdGroup>
+            </Button>
+          ) : isBrowsing ? (
+            <Button
+              variant="outline"
+              size="xs"
+              tabIndex={-1}
+              className={cn(
+                "absolute inset-e-2.5 top-1/2 pe-1 ps-2 -translate-y-1/2",
+                hasHighlightedBrowseItem ? "gap-1" : "gap-1.5",
+              )}
+              aria-label={`${submitActionLabel} (${addShortcutLabel})`}
+              disabled={
+                relativePathNeedsActiveProject || (isCloneDestinationStep && isRemoteProjectPending)
               }
-            : {})}
-          onKeyDown={handleKeyDown}
-        />
+              onMouseDown={(event) => {
+                event.preventDefault();
+              }}
+              onClick={() => {
+                if (relativePathNeedsActiveProject) {
+                  return;
+                }
+                if (isCloneDestinationStep) {
+                  void submitAddProjectCloneFlow(resolvedAddProjectPath);
+                } else {
+                  void handleAddProject(resolvedAddProjectPath);
+                }
+              }}
+              title={`${submitActionLabel} (${addShortcutLabel})`}
+            >
+              <span>
+                {isCloneDestinationStep && isRemoteProjectPending ? "Cloning" : submitActionLabel}
+              </span>
+              <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
+                <Kbd>{hasHighlightedBrowseItem ? `${submitModifierLabel} Enter` : "Enter"}</Kbd>
+              </KbdGroup>
+            </Button>
+          ) : null}
+        </div>
         <CommandPanel className="max-h-[min(28rem,70vh)]">
+          {remoteProjectContext ? (
+            <div className="p-2 pb-0">
+              <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">
+                Repository
+              </div>
+              <div className="flex min-h-8 items-center gap-2 rounded-sm px-2 py-1.5">
+                {remoteProjectContext.icon}
+                <span className="flex min-w-0 flex-1 flex-col">
+                  <span className="truncate text-foreground text-sm">
+                    {remoteProjectContext.title}
+                  </span>
+                  <span className="truncate text-muted-foreground/70 text-xs">
+                    {remoteProjectContext.description}
+                  </span>
+                </span>
+              </div>
+            </div>
+          ) : null}
           <CommandPaletteResults
             groups={displayedGroups}
+            highlightedItemValue={highlightedItemValue}
             isActionsOnly={isActionsOnly}
             keybindings={keybindings}
             onExecuteItem={executeItem}
+            {...(addProjectCloneFlow?.step === "repository"
+              ? {
+                  emptyStateMessage:
+                    addProjectCloneFlow.source === "url"
+                      ? "Enter a Git clone URL and press Enter to continue."
+                      : "Enter a repository path and press Enter to look it up.",
+                }
+              : addProjectCloneFlow?.step === "confirm"
+                ? { emptyStateMessage: "Choose a destination path and press Enter to clone." }
+                : relativePathNeedsActiveProject
+                  ? { emptyStateMessage: "Relative paths require an active project." }
+                  : willCreateProjectPath
+                    ? {
+                        emptyStateMessage:
+                          "Press Enter to create this folder and add it as a project.",
+                      }
+                    : {})}
           />
         </CommandPanel>
         <CommandFooter className="gap-3 max-sm:flex-col max-sm:items-start">
@@ -436,10 +1696,19 @@ function OpenCommandPaletteDialog() {
               </Kbd>
               <span className={cn("text-muted-foreground/80")}>Navigate</span>
             </KbdGroup>
-            <KbdGroup className="items-center gap-1.5">
-              <Kbd>Enter</Kbd>
-              <span className={cn("text-muted-foreground/80")}>Select</span>
-            </KbdGroup>
+            {addProjectCloneFlow?.step === "repository" ? (
+              <KbdGroup className="items-center gap-1.5">
+                <Kbd>Enter</Kbd>
+                <span className={cn("text-muted-foreground/80")}>
+                  {remoteProjectButtonLabel ?? "Continue"}
+                </span>
+              </KbdGroup>
+            ) : !canSubmitBrowsePath || hasHighlightedBrowseItem ? (
+              <KbdGroup className="items-center gap-1.5">
+                <Kbd>Enter</Kbd>
+                <span className={cn("text-muted-foreground/80")}>Select</span>
+              </KbdGroup>
+            ) : null}
             {isSubmenu ? (
               <KbdGroup className="items-center gap-1.5">
                 <Kbd>Backspace</Kbd>
@@ -451,6 +1720,19 @@ function OpenCommandPaletteDialog() {
               <span className={cn("text-muted-foreground/80")}>Close</span>
             </KbdGroup>
           </div>
+          {canOpenProjectFromFileManager ? (
+            <Button
+              variant="ghost"
+              size="xs"
+              className="h-auto px-2 text-xs text-muted-foreground/80 hover:bg-transparent hover:text-foreground"
+              disabled={isPickingProjectFolder}
+              onClick={() => {
+                void handleOpenProjectFromFileManager();
+              }}
+            >
+              {`Open in ${fileManagerName}`}
+            </Button>
+          ) : null}
         </CommandFooter>
       </Command>
     </CommandDialogPopup>
diff --git a/apps/web/src/components/CommandPaletteResults.tsx b/apps/web/src/components/CommandPaletteResults.tsx
index 72700471bac..4ad08db0824 100644
--- a/apps/web/src/components/CommandPaletteResults.tsx
+++ b/apps/web/src/components/CommandPaletteResults.tsx
@@ -14,10 +14,12 @@ import {
   CommandList,
   CommandShortcut,
 } from "./ui/command";
+import { cn } from "~/lib/utils";
 
 interface CommandPaletteResultsProps {
   emptyStateMessage?: string;
   groups: ReadonlyArray<CommandPaletteGroup>;
+  highlightedItemValue?: string | null;
   isActionsOnly: boolean;
   keybindings: ResolvedKeybindingsConfig;
   onExecuteItem: (item: CommandPaletteActionItem | CommandPaletteSubmenuItem) => void;
@@ -41,14 +43,19 @@ export function CommandPaletteResults(props: CommandPaletteResultsProps) {
         <CommandGroup items={group.items} key={group.value}>
           <CommandGroupLabel>{group.label}</CommandGroupLabel>
           <CommandCollection>
-            {(item) => (
-              <CommandPaletteResultRow
-                item={item}
-                key={item.value}
-                keybindings={props.keybindings}
-                onExecuteItem={props.onExecuteItem}
-              />
-            )}
+            {(item) =>
+              item.disabled ? (
+                <DisabledCommandPaletteResultRow item={item} key={item.value} />
+              ) : (
+                <CommandPaletteResultRow
+                  item={item}
+                  key={item.value}
+                  keybindings={props.keybindings}
+                  isActive={props.highlightedItemValue === item.value}
+                  onExecuteItem={props.onExecuteItem}
+                />
+              )
+            }
           </CommandCollection>
         </CommandGroup>
       ))}
@@ -56,8 +63,36 @@ export function CommandPaletteResults(props: CommandPaletteResultsProps) {
   );
 }
 
+function DisabledCommandPaletteResultRow(props: {
+  item: CommandPaletteActionItem | CommandPaletteSubmenuItem;
+}) {
+  return (
+    <div className="flex min-h-8 select-none items-center gap-2 rounded-sm px-2 py-1.5 text-base opacity-64 sm:min-h-7 sm:text-sm">
+      {props.item.icon}
+      {props.item.description ? (
+        <span className="flex min-w-0 flex-1 flex-col">
+          <span className="flex min-w-0 items-center gap-1.5 text-sm text-foreground">
+            {props.item.titleLeadingContent}
+            <span className="truncate">{props.item.title}</span>
+          </span>
+          <span className="truncate text-muted-foreground/70 text-xs">
+            {props.item.description}
+          </span>
+        </span>
+      ) : (
+        <span className="flex min-w-0 flex-1 items-center gap-1.5 text-sm text-foreground">
+          {props.item.titleLeadingContent}
+          <span className="truncate">{props.item.title}</span>
+        </span>
+      )}
+      {props.item.titleTrailingContent}
+    </div>
+  );
+}
+
 function CommandPaletteResultRow(props: {
   item: CommandPaletteActionItem | CommandPaletteSubmenuItem;
+  isActive: boolean;
   keybindings: ResolvedKeybindingsConfig;
   onExecuteItem: (item: CommandPaletteActionItem | CommandPaletteSubmenuItem) => void;
 }) {
@@ -68,7 +103,10 @@ function CommandPaletteResultRow(props: {
   return (
     <CommandItem
       value={props.item.value}
-      className="cursor-pointer gap-2"
+      className={cn(
+        "cursor-pointer gap-2 hover:bg-transparent hover:text-inherit data-highlighted:bg-transparent data-highlighted:text-inherit data-selected:bg-transparent data-selected:text-inherit [&[data-highlighted][data-selected]]:bg-transparent [&[data-highlighted][data-selected]]:text-inherit",
+        props.isActive && "bg-accent! text-accent-foreground!",
+      )}
       onMouseDown={(event) => {
         event.preventDefault();
       }}
@@ -79,16 +117,21 @@ function CommandPaletteResultRow(props: {
       {props.item.icon}
       {props.item.description ? (
         <span className="flex min-w-0 flex-1 flex-col">
-          <span className="truncate text-sm text-foreground">{props.item.title}</span>
+          <span className="flex min-w-0 items-center gap-1.5 text-sm text-foreground">
+            {props.item.titleLeadingContent}
+            <span className="truncate">{props.item.title}</span>
+          </span>
           <span className="truncate text-muted-foreground/70 text-xs">
             {props.item.description}
           </span>
         </span>
       ) : (
-        <span className="flex min-w-0 items-center gap-1.5 truncate text-sm text-foreground">
+        <span className="flex min-w-0 flex-1 items-center gap-1.5 text-sm text-foreground">
+          {props.item.titleLeadingContent}
           <span className="truncate">{props.item.title}</span>
         </span>
       )}
+      {props.item.titleTrailingContent}
       {props.item.timestamp ? (
         <span className="min-w-12 shrink-0 text-right text-[10px] tabular-nums text-muted-foreground/70">
           {props.item.timestamp}
diff --git a/apps/web/src/components/ComposerPromptEditor.tsx b/apps/web/src/components/ComposerPromptEditor.tsx
index 95157d787f3..6f17c866306 100644
--- a/apps/web/src/components/ComposerPromptEditor.tsx
+++ b/apps/web/src/components/ComposerPromptEditor.tsx
@@ -32,26 +32,20 @@ import {
   type ElementNode,
   type LexicalNode,
   type SerializedLexicalNode,
-  TextNode,
-  type EditorConfig,
   type EditorState,
   type NodeKey,
-  type SerializedTextNode,
   type Spread,
 } from "lexical";
 import {
   createContext,
-  forwardRef,
+  use,
   useCallback,
-  useContext,
   useEffect,
+  useEffectEvent,
   useImperativeHandle,
   useLayoutEffect,
   useMemo,
   useRef,
-  type ClipboardEventHandler,
-  type ReactElement,
-  type Ref,
 } from "react";
 
 import {
@@ -75,6 +69,7 @@ import {
   COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
   COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
   COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
 } from "./composerInlineChip";
 import { ComposerPendingTerminalContextChip } from "./chat/ComposerPendingTerminalContexts";
 import { formatProviderSkillDisplayName } from "~/providerSkillPresentation";
@@ -103,7 +98,7 @@ type SerializedComposerMentionNode = Spread<
     type: "composer-mention";
     version: 1;
   },
-  SerializedTextNode
+  SerializedLexicalNode
 >;
 
 type SerializedComposerSkillNode = Spread<
@@ -132,7 +127,37 @@ const ComposerTerminalContextActionsContext = createContext<{
   onRemoveTerminalContext: () => {},
 });
 
-class ComposerMentionNode extends TextNode {
+function ComposerMentionDecorator(props: { path: string }) {
+  const theme = resolvedThemeFromDocument();
+  const chip = (
+    <span
+      className={COMPOSER_INLINE_CHIP_CLASS_NAME}
+      contentEditable={false}
+      spellCheck={false}
+      data-composer-mention-chip="true"
+    >
+      <img
+        alt=""
+        aria-hidden="true"
+        className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+        loading="lazy"
+        src={getVscodeIconUrlForEntry(props.path, inferEntryKindFromPath(props.path), theme)}
+      />
+      <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>{basenameOfPath(props.path)}</span>
+    </span>
+  );
+
+  return (
+    <Tooltip>
+      <TooltipTrigger render={chip} />
+      <TooltipPopup side="top" className="max-w-120 whitespace-normal leading-tight wrap-anywhere">
+        {props.path}
+      </TooltipPopup>
+    </Tooltip>
+  );
+}
+
+class ComposerMentionNode extends DecoratorNode<React.ReactElement> {
   __path: string;
 
   static override getType(): string {
@@ -144,12 +169,12 @@ class ComposerMentionNode extends TextNode {
   }
 
   static override importJSON(serializedNode: SerializedComposerMentionNode): ComposerMentionNode {
-    return $createComposerMentionNode(serializedNode.path);
+    return $createComposerMentionNode(serializedNode.path).updateFromJSON(serializedNode);
   }
 
   constructor(path: string, key?: NodeKey) {
+    super(key);
     const normalizedPath = path.startsWith("@") ? path.slice(1) : path;
-    super(`@${normalizedPath}`, key);
     this.__path = normalizedPath;
   }
 
@@ -162,41 +187,26 @@ class ComposerMentionNode extends TextNode {
     };
   }
 
-  override createDOM(_config: EditorConfig): HTMLElement {
+  override createDOM(): HTMLElement {
     const dom = document.createElement("span");
-    dom.className = COMPOSER_INLINE_CHIP_CLASS_NAME;
-    dom.contentEditable = "false";
-    dom.setAttribute("spellcheck", "false");
-    renderMentionChipDom(dom, this.__path);
+    dom.className = "inline-flex align-middle leading-none";
     return dom;
   }
 
-  override updateDOM(
-    prevNode: ComposerMentionNode,
-    dom: HTMLElement,
-    _config: EditorConfig,
-  ): boolean {
-    dom.contentEditable = "false";
-    if (prevNode.__text !== this.__text || prevNode.__path !== this.__path) {
-      renderMentionChipDom(dom, this.__path);
-    }
-    return false;
-  }
-
-  override canInsertTextBefore(): false {
+  override updateDOM(): false {
     return false;
   }
 
-  override canInsertTextAfter(): false {
-    return false;
+  override getTextContent(): string {
+    return `@${this.__path}`;
   }
 
-  override isTextEntity(): true {
+  override isInline(): true {
     return true;
   }
 
-  override isToken(): true {
-    return true;
+  override decorate(): React.ReactElement {
+    return <ComposerMentionDecorator path={this.__path} />;
   }
 }
 
@@ -204,8 +214,6 @@ function $createComposerMentionNode(path: string): ComposerMentionNode {
   return $applyNodeReplacement(new ComposerMentionNode(path));
 }
 
-const SKILL_CHIP_ICON_SVG = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round"><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></svg>`;
-
 function resolveSkillDescription(
   skill: Pick<ServerProviderSkill, "shortDescription" | "description">,
 ): string | null {
@@ -260,14 +268,14 @@ function ComposerSkillDecorator(props: { skillLabel: string; skillDescription: s
   return (
     <Tooltip>
       <TooltipTrigger render={chip} />
-      <TooltipPopup side="top" className="max-w-[30rem] whitespace-normal leading-tight">
+      <TooltipPopup side="top" className="max-w-120 whitespace-normal leading-tight">
         {props.skillDescription}
       </TooltipPopup>
     </Tooltip>
   );
 }
 
-class ComposerSkillNode extends DecoratorNode<ReactElement> {
+class ComposerSkillNode extends DecoratorNode<React.ReactElement> {
   __skillName: string;
   __skillLabel: string;
   __skillDescription: string | null;
@@ -335,7 +343,7 @@ class ComposerSkillNode extends DecoratorNode<ReactElement> {
     return true;
   }
 
-  override decorate(): ReactElement {
+  override decorate(): React.ReactElement {
     return (
       <ComposerSkillDecorator
         skillLabel={this.__skillLabel}
@@ -357,7 +365,7 @@ function ComposerTerminalContextDecorator(props: { context: TerminalContextDraft
   return <ComposerPendingTerminalContextChip context={props.context} />;
 }
 
-class ComposerTerminalContextNode extends DecoratorNode<ReactElement> {
+class ComposerTerminalContextNode extends DecoratorNode<React.ReactElement> {
   __context: TerminalContextDraft;
 
   static override getType(): string {
@@ -406,7 +414,7 @@ class ComposerTerminalContextNode extends DecoratorNode<ReactElement> {
     return true;
   }
 
-  override decorate(): ReactElement {
+  override decorate(): React.ReactElement {
     return <ComposerTerminalContextDecorator context={this.__context} />;
   }
 }
@@ -434,26 +442,6 @@ function resolvedThemeFromDocument(): "light" | "dark" {
   return document.documentElement.classList.contains("dark") ? "dark" : "light";
 }
 
-function renderMentionChipDom(container: HTMLElement, pathValue: string): void {
-  container.textContent = "";
-  container.style.setProperty("user-select", "none");
-  container.style.setProperty("-webkit-user-select", "none");
-
-  const theme = resolvedThemeFromDocument();
-  const icon = document.createElement("img");
-  icon.alt = "";
-  icon.ariaHidden = "true";
-  icon.className = COMPOSER_INLINE_CHIP_ICON_CLASS_NAME;
-  icon.loading = "lazy";
-  icon.src = getVscodeIconUrlForEntry(pathValue, inferEntryKindFromPath(pathValue), theme);
-
-  const label = document.createElement("span");
-  label.className = COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME;
-  label.textContent = basenameOfPath(pathValue);
-
-  container.append(icon, label);
-}
-
 function terminalContextSignature(contexts: ReadonlyArray<TerminalContextDraft>): string {
   return contexts
     .map((context) =>
@@ -595,12 +583,9 @@ function getAbsoluteOffsetForPoint(node: LexicalNode, pointOffset: number): numb
   }
 
   if ($isTextNode(node)) {
-    if (node instanceof ComposerMentionNode) {
-      return getAbsoluteOffsetForInlineTokenPoint(node, offset, pointOffset);
-    }
     return offset + Math.min(pointOffset, node.getTextContentSize());
   }
-  if (node instanceof ComposerSkillNode || node instanceof ComposerTerminalContextNode) {
+  if (isComposerInlineTokenNode(node)) {
     return getAbsoluteOffsetForInlineTokenPoint(node, offset, pointOffset);
   }
 
@@ -642,12 +627,9 @@ function getExpandedAbsoluteOffsetForPoint(node: LexicalNode, pointOffset: numbe
   }
 
   if ($isTextNode(node)) {
-    if (node instanceof ComposerMentionNode) {
-      return getExpandedAbsoluteOffsetForInlineTokenPoint(node, offset, pointOffset);
-    }
     return offset + Math.min(pointOffset, node.getTextContentSize());
   }
-  if (node instanceof ComposerSkillNode || node instanceof ComposerTerminalContextNode) {
+  if (isComposerInlineTokenNode(node)) {
     return getExpandedAbsoluteOffsetForInlineTokenPoint(node, offset, pointOffset);
   }
 
@@ -673,10 +655,7 @@ function findSelectionPointAtOffset(
   node: LexicalNode,
   remainingRef: { value: number },
 ): { key: string; offset: number; type: "text" | "element" } | null {
-  if (node instanceof ComposerMentionNode || node instanceof ComposerSkillNode) {
-    return findSelectionPointForInlineToken(node, remainingRef);
-  }
-  if (node instanceof ComposerTerminalContextNode) {
+  if (isComposerInlineTokenNode(node)) {
     return findSelectionPointForInlineToken(node, remainingRef);
   }
 
@@ -918,11 +897,8 @@ interface ComposerPromptEditorProps {
     key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
     event: KeyboardEvent,
   ) => boolean;
-  onPaste: ClipboardEventHandler<HTMLElement>;
-}
-
-interface ComposerPromptEditorInnerProps extends ComposerPromptEditorProps {
-  editorRef: Ref<ComposerPromptEditorHandle>;
+  onPaste: React.ClipboardEventHandler<HTMLElement>;
+  editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
 }
 
 function ComposerCommandKeyPlugin(props: {
@@ -1077,7 +1053,7 @@ function ComposerInlineTokenSelectionNormalizePlugin() {
 
 function ComposerInlineTokenBackspacePlugin() {
   const [editor] = useLexicalComposerContext();
-  const { onRemoveTerminalContext } = useContext(ComposerTerminalContextActionsContext);
+  const { onRemoveTerminalContext } = use(ComposerTerminalContextActionsContext);
 
   useEffect(() => {
     return editor.registerCommand(
@@ -1168,68 +1144,65 @@ function ComposerSurroundSelectionPlugin(props: {
     skillMetadataRef.current = skillMetadataByName(props.skills);
   }, [props.skills]);
 
-  const applySurroundInsertion = useCallback(
-    (inputData: string): boolean => {
-      const surroundCloseSymbol = SURROUND_SYMBOLS_MAP.get(inputData);
-      const pendingSurroundSelection = pendingSurroundSelectionRef.current;
-      if (!surroundCloseSymbol) {
-        pendingSurroundSelectionRef.current = null;
-        return false;
-      }
+  const applySurroundInsertion = useEffectEvent((inputData: string): boolean => {
+    const surroundCloseSymbol = SURROUND_SYMBOLS_MAP.get(inputData);
+    const pendingSurroundSelection = pendingSurroundSelectionRef.current;
+    if (!surroundCloseSymbol) {
+      pendingSurroundSelectionRef.current = null;
+      return false;
+    }
 
-      let handled = false;
-      editor.update(() => {
-        const selectionSnapshot =
-          pendingSurroundSelection ??
-          (() => {
-            const selection = $getSelection();
-            if (!$isRangeSelection(selection) || selection.isCollapsed()) {
-              return null;
-            }
-            if ($selectionTouchesInlineToken(selection)) {
-              return null;
-            }
-            const range = getSelectionRangeForExpandedComposerOffsets(selection);
-            if (!range || range.start === range.end) {
-              return null;
-            }
-            const value = $getRoot().getTextContent();
-            if (selectionTouchesMentionBoundary(value, range.start, range.end)) {
-              return null;
-            }
-            return {
-              value,
-              expandedStart: range.start,
-              expandedEnd: range.end,
-            };
-          })();
-
-        if (!selectionSnapshot || !surroundCloseSymbol) {
-          return;
-        }
+    let handled = false;
+    editor.update(() => {
+      const selectionSnapshot =
+        pendingSurroundSelection ??
+        (() => {
+          const selection = $getSelection();
+          if (!$isRangeSelection(selection) || selection.isCollapsed()) {
+            return null;
+          }
+          if ($selectionTouchesInlineToken(selection)) {
+            return null;
+          }
+          const range = getSelectionRangeForExpandedComposerOffsets(selection);
+          if (!range || range.start === range.end) {
+            return null;
+          }
+          const value = $getRoot().getTextContent();
+          if (selectionTouchesMentionBoundary(value, range.start, range.end)) {
+            return null;
+          }
+          return {
+            value,
+            expandedStart: range.start,
+            expandedEnd: range.end,
+          };
+        })();
+
+      if (!selectionSnapshot || !surroundCloseSymbol) {
+        return;
+      }
 
-        const selectedText = selectionSnapshot.value.slice(
-          selectionSnapshot.expandedStart,
-          selectionSnapshot.expandedEnd,
-        );
-        const nextValue = `${selectionSnapshot.value.slice(0, selectionSnapshot.expandedStart)}${inputData}${selectedText}${surroundCloseSymbol}${selectionSnapshot.value.slice(selectionSnapshot.expandedEnd)}`;
-        $setComposerEditorPrompt(nextValue, terminalContextsRef.current, skillMetadataRef.current);
-        const selectionStart = collapseExpandedComposerCursor(
-          nextValue,
-          selectionSnapshot.expandedStart,
-        );
-        $setSelectionRangeAtComposerOffsets(
-          selectionStart + inputData.length,
-          selectionStart + inputData.length + selectedText.length,
-        );
-        handled = true;
-        pendingSurroundSelectionRef.current = null;
-      });
+      const selectedText = selectionSnapshot.value.slice(
+        selectionSnapshot.expandedStart,
+        selectionSnapshot.expandedEnd,
+      );
+      const nextValue = `${selectionSnapshot.value.slice(0, selectionSnapshot.expandedStart)}${inputData}${selectedText}${surroundCloseSymbol}${selectionSnapshot.value.slice(selectionSnapshot.expandedEnd)}`;
+      $setComposerEditorPrompt(nextValue, terminalContextsRef.current, skillMetadataRef.current);
+      const selectionStart = collapseExpandedComposerCursor(
+        nextValue,
+        selectionSnapshot.expandedStart,
+      );
+      $setSelectionRangeAtComposerOffsets(
+        selectionStart + inputData.length,
+        selectionStart + inputData.length + selectedText.length,
+      );
+      handled = true;
+      pendingSurroundSelectionRef.current = null;
+    });
 
-      return handled;
-    },
-    [editor],
-  );
+    return handled;
+  });
 
   useEffect(() => {
     const onKeyDown = (event: KeyboardEvent) => {
@@ -1406,7 +1379,7 @@ function ComposerSurroundSelectionPlugin(props: {
       }
       unregisterRootListener();
     };
-  }, [applySurroundInsertion, editor]);
+  }, [editor]);
 
   return null;
 }
@@ -1424,7 +1397,7 @@ function ComposerPromptEditorInner({
   onCommandKeyDown,
   onPaste,
   editorRef,
-}: ComposerPromptEditorInnerProps) {
+}: ComposerPromptEditorProps) {
   const [editor] = useLexicalComposerContext();
   const onChangeRef = useRef(onChange);
   const initialCursor = clampCollapsedComposerCursor(value, cursor);
@@ -1507,7 +1480,7 @@ function ComposerPromptEditorInner({
       const rootElement = editor.getRootElement();
       if (!rootElement) return;
       const boundedCursor = clampCollapsedComposerCursor(snapshotRef.current.value, nextCursor);
-      rootElement.focus();
+      rootElement.focus({ preventScroll: true });
       editor.update(() => {
         $setSelectionAtComposerOffset(boundedCursor);
       });
@@ -1632,13 +1605,13 @@ function ComposerPromptEditorInner({
   }, []);
 
   return (
-    <ComposerTerminalContextActionsContext.Provider value={terminalContextActions}>
+    <ComposerTerminalContextActionsContext value={terminalContextActions}>
       <div className="relative">
         <PlainTextPlugin
           contentEditable={
             <ContentEditable
               className={cn(
-                "block max-h-[200px] min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap break-words bg-transparent text-[14px] leading-relaxed text-foreground focus:outline-none",
+                "block max-h-50 min-h-17.5 w-full overflow-y-auto whitespace-pre-wrap wrap-break-word bg-transparent text-[16px] leading-relaxed text-foreground focus:outline-none sm:text-[14px]",
                 className,
               )}
               data-testid="composer-editor"
@@ -1649,7 +1622,7 @@ function ComposerPromptEditorInner({
           }
           placeholder={
             terminalContexts.length > 0 ? null : (
-              <div className="pointer-events-none absolute inset-0 text-[14px] leading-relaxed text-muted-foreground/35">
+              <div className="pointer-events-none absolute inset-0 text-[16px] leading-relaxed text-muted-foreground/35 sm:text-[14px]">
                 {placeholder}
               </div>
             )
@@ -1664,29 +1637,24 @@ function ComposerPromptEditorInner({
         <ComposerInlineTokenBackspacePlugin />
         <HistoryPlugin />
       </div>
-    </ComposerTerminalContextActionsContext.Provider>
+    </ComposerTerminalContextActionsContext>
   );
 }
 
-export const ComposerPromptEditor = forwardRef<
-  ComposerPromptEditorHandle,
-  ComposerPromptEditorProps
->(function ComposerPromptEditor(
-  {
-    value,
-    cursor,
-    terminalContexts,
-    skills,
-    disabled,
-    placeholder,
-    className,
-    onRemoveTerminalContext,
-    onChange,
-    onCommandKeyDown,
-    onPaste,
-  },
-  ref,
-) {
+export function ComposerPromptEditor({
+  value,
+  cursor,
+  terminalContexts,
+  skills,
+  disabled,
+  placeholder,
+  className,
+  onRemoveTerminalContext,
+  onChange,
+  onCommandKeyDown,
+  onPaste,
+  editorRef,
+}: ComposerPromptEditorProps) {
   const initialValueRef = useRef(value);
   const initialTerminalContextsRef = useRef(terminalContexts);
   const initialSkillMetadataRef = useRef(skillMetadataByName(skills));
@@ -1721,10 +1689,10 @@ export const ComposerPromptEditor = forwardRef<
         onRemoveTerminalContext={onRemoveTerminalContext}
         onChange={onChange}
         onPaste={onPaste}
-        editorRef={ref}
+        editorRef={editorRef}
         {...(onCommandKeyDown ? { onCommandKeyDown } : {})}
         {...(className ? { className } : {})}
       />
     </LexicalComposer>
   );
-});
+}
diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index 63a5231f73b..f178a69fb43 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -5,9 +5,11 @@ import { useNavigate, useParams, useSearch } from "@tanstack/react-router";
 import { scopeThreadRef } from "@t3tools/client-runtime";
 import type { TurnId } from "@t3tools/contracts";
 import {
+  ChevronDownIcon,
   ChevronLeftIcon,
   ChevronRightIcon,
   Columns2Icon,
+  PilcrowIcon,
   Rows3Icon,
   TextWrapIcon,
 } from "lucide-react";
@@ -160,6 +162,21 @@ function buildFileDiffRenderKey(fileDiff: FileDiffMetadata): string {
   return fileDiff.cacheKey ?? `${fileDiff.prevName ?? "none"}:${fileDiff.name}`;
 }
 
+function getDiffCollapseIconClassName(fileDiff: FileDiffMetadata): string {
+  switch (fileDiff.type) {
+    case "new":
+      return "text-[var(--diffs-addition-base)]";
+    case "deleted":
+      return "text-[var(--diffs-deletion-base)]";
+    case "change":
+    case "rename-pure":
+    case "rename-changed":
+      return "text-[var(--diffs-modified-base)]";
+    default:
+      return "text-muted-foreground/80";
+  }
+}
+
 interface DiffPanelProps {
   mode?: DiffPanelMode;
 }
@@ -172,6 +189,10 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
   const settings = useSettings();
   const [diffRenderMode, setDiffRenderMode] = useState<DiffRenderMode>("stacked");
   const [diffWordWrap, setDiffWordWrap] = useState(settings.diffWordWrap);
+  const [diffIgnoreWhitespace, setDiffIgnoreWhitespace] = useState(settings.diffIgnoreWhitespace);
+  const [collapsedDiffFileKeys, setCollapsedDiffFileKeys] = useState<ReadonlySet<string>>(
+    () => new Set(),
+  );
   const patchViewportRef = useRef<HTMLDivElement>(null);
   const turnStripRef = useRef<HTMLDivElement>(null);
   const previousDiffOpenRef = useRef(false);
@@ -277,6 +298,7 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
       threadId: activeThreadId,
       fromTurnCount: activeCheckpointRange?.fromTurnCount ?? null,
       toTurnCount: activeCheckpointRange?.toTurnCount ?? null,
+      ignoreWhitespace: diffIgnoreWhitespace,
       cacheScope: selectedTurn ? `turn:${selectedTurn.turnId}` : conversationCacheScope,
       enabled: isGitRepo,
     }),
@@ -314,12 +336,26 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
     );
   }, [renderablePatch]);
 
+  useEffect(() => {
+    if (renderableFiles.length === 0) {
+      setCollapsedDiffFileKeys((current) => (current.size === 0 ? current : new Set()));
+      return;
+    }
+
+    const visibleFileKeys = new Set(renderableFiles.map(buildFileDiffRenderKey));
+    setCollapsedDiffFileKeys((current) => {
+      const next = new Set([...current].filter((fileKey) => visibleFileKeys.has(fileKey)));
+      return next.size === current.size ? current : next;
+    });
+  }, [renderableFiles]);
+
   useEffect(() => {
     if (diffOpen && !previousDiffOpenRef.current) {
       setDiffWordWrap(settings.diffWordWrap);
+      setDiffIgnoreWhitespace(settings.diffIgnoreWhitespace);
     }
     previousDiffOpenRef.current = diffOpen;
-  }, [diffOpen, settings.diffWordWrap]);
+  }, [diffOpen, settings.diffIgnoreWhitespace, settings.diffWordWrap]);
 
   useEffect(() => {
     if (!selectedFilePath || !patchViewportRef.current) {
@@ -342,6 +378,17 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
     },
     [activeCwd],
   );
+  const toggleDiffFileCollapsed = useCallback((fileKey: string) => {
+    setCollapsedDiffFileKeys((current) => {
+      const next = new Set(current);
+      if (next.has(fileKey)) {
+        next.delete(fileKey);
+      } else {
+        next.add(fileKey);
+      }
+      return next;
+    });
+  }, []);
 
   const selectTurn = (turnId: TurnId) => {
     if (!activeThread) return;
@@ -429,12 +476,6 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
   const headerRow = (
     <>
       <div className="relative min-w-0 flex-1 [-webkit-app-region:no-drag]">
-        {canScrollTurnStripLeft && (
-          <div className="pointer-events-none absolute inset-y-0 left-8 z-10 w-7 bg-linear-to-r from-card to-transparent" />
-        )}
-        {canScrollTurnStripRight && (
-          <div className="pointer-events-none absolute inset-y-0 right-8 z-10 w-7 bg-linear-to-l from-card to-transparent" />
-        )}
         <button
           type="button"
           className={cn(
@@ -466,6 +507,13 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
         <div
           ref={turnStripRef}
           className="turn-chip-strip flex gap-1 overflow-x-auto px-8 py-0.5"
+          style={
+            canScrollTurnStripLeft || canScrollTurnStripRight
+              ? {
+                  maskImage: `linear-gradient(to right, ${canScrollTurnStripLeft ? "transparent 24px, black 72px" : "black"}, ${canScrollTurnStripRight ? "black calc(100% - 72px), transparent calc(100% - 24px)" : "black"})`,
+                }
+              : undefined
+          }
           onWheel={onTurnStripWheel}
         >
           <button
@@ -550,6 +598,18 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
         >
           <TextWrapIcon className="size-3" />
         </Toggle>
+        <Toggle
+          aria-label={diffIgnoreWhitespace ? "Show whitespace changes" : "Hide whitespace changes"}
+          title={diffIgnoreWhitespace ? "Show whitespace changes" : "Hide whitespace changes"}
+          variant="outline"
+          size="xs"
+          pressed={diffIgnoreWhitespace}
+          onPressedChange={(pressed) => {
+            setDiffIgnoreWhitespace(Boolean(pressed));
+          }}
+        >
+          <PilcrowIcon className="size-3" />
+        </Toggle>
       </div>
     </>
   );
@@ -603,11 +663,12 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
                   const filePath = resolveFileDiffPath(fileDiff);
                   const fileKey = buildFileDiffRenderKey(fileDiff);
                   const themedFileKey = `${fileKey}:${resolvedTheme}`;
+                  const collapsed = collapsedDiffFileKeys.has(fileKey);
                   return (
                     <div
                       key={themedFileKey}
                       data-diff-file-path={filePath}
-                      className="diff-render-file mb-2 rounded-md first:mt-2 last:mb-0"
+                      className="diff-render-file group/diff-file mb-2 rounded-md first:mt-2 last:mb-0"
                       onClickCapture={(event) => {
                         const nativeEvent = event.nativeEvent as MouseEvent;
                         const composedPath = nativeEvent.composedPath?.() ?? [];
@@ -621,7 +682,30 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
                     >
                       <FileDiff
                         fileDiff={fileDiff}
+                        renderHeaderPrefix={() => (
+                          <button
+                            type="button"
+                            className={cn(
+                              "inline-flex size-5 shrink-0 cursor-pointer items-center justify-center rounded-sm border-0 bg-transparent p-0 transition-colors hover:bg-foreground/10 focus-visible:outline-hidden",
+                              getDiffCollapseIconClassName(fileDiff),
+                            )}
+                            aria-label={collapsed ? `Expand ${filePath}` : `Collapse ${filePath}`}
+                            aria-expanded={!collapsed}
+                            title={collapsed ? "Expand diff" : "Collapse diff"}
+                            onClick={(event) => {
+                              event.stopPropagation();
+                              toggleDiffFileCollapsed(fileKey);
+                            }}
+                          >
+                            {collapsed ? (
+                              <ChevronRightIcon className="size-4" />
+                            ) : (
+                              <ChevronDownIcon className="size-4" />
+                            )}
+                          </button>
+                        )}
                         options={{
+                          collapsed,
                           diffStyle: diffRenderMode === "split" ? "split" : "unified",
                           lineDiffType: "none",
                           overflow: diffWordWrap ? "wrap" : "scroll",
diff --git a/apps/web/src/components/DiffPanelShell.tsx b/apps/web/src/components/DiffPanelShell.tsx
index c08c53325d7..829ed4159d4 100644
--- a/apps/web/src/components/DiffPanelShell.tsx
+++ b/apps/web/src/components/DiffPanelShell.tsx
@@ -11,7 +11,9 @@ function getDiffPanelHeaderRowClassName(mode: DiffPanelMode) {
   const shouldUseDragRegion = isElectron && mode !== "sheet";
   return cn(
     "flex items-center justify-between gap-2 px-4",
-    shouldUseDragRegion ? "drag-region h-[52px] border-b border-border" : "h-12",
+    shouldUseDragRegion
+      ? "drag-region h-[52px] border-b border-border wco:h-[env(titlebar-area-height)] wco:pr-[calc(100vw-env(titlebar-area-width)-env(titlebar-area-x)+1em)]"
+      : "h-12 wco:max-h-[env(titlebar-area-height)]",
   );
 }
 
diff --git a/apps/web/src/components/GitActionsControl.browser.tsx b/apps/web/src/components/GitActionsControl.browser.tsx
index 651b383fa08..a2a801d54af 100644
--- a/apps/web/src/components/GitActionsControl.browser.tsx
+++ b/apps/web/src/components/GitActionsControl.browser.tsx
@@ -90,6 +90,7 @@ vi.mock("~/components/ui/toast", () => ({
     promise: toastPromiseSpy,
     update: toastUpdateSpy,
   },
+  stackedThreadToast: vi.fn((options: unknown) => options),
 }));
 
 vi.mock("~/editorPreferences", () => ({
@@ -99,12 +100,14 @@ vi.mock("~/editorPreferences", () => ({
 vi.mock("~/lib/gitReactQuery", () => ({
   gitInitMutationOptions: vi.fn(() => ({ __kind: "init" })),
   gitMutationKeys: {
+    publishRepository: vi.fn(() => ["publish-repository"]),
     pull: vi.fn(() => ["pull"]),
     runStackedAction: vi.fn(() => ["run-stacked-action"]),
   },
   gitPullMutationOptions: vi.fn(() => ({ __kind: "pull" })),
   gitRunStackedActionMutationOptions: vi.fn(() => ({ __kind: "run-stacked-action" })),
   invalidateGitQueries: invalidateGitQueriesSpy,
+  sourceControlPublishRepositoryMutationOptions: vi.fn(() => ({ __kind: "publish-repository" })),
 }));
 
 vi.mock("~/lib/gitStatusState", () => ({
@@ -112,7 +115,15 @@ vi.mock("~/lib/gitStatusState", () => ({
   resetGitStatusStateForTests: () => undefined,
   useGitStatus: vi.fn(() => ({
     data: {
-      branch: BRANCH_NAME,
+      isRepo: true,
+      sourceControlProvider: {
+        kind: "github",
+        name: "GitHub",
+        baseUrl: "https://github.com",
+      },
+      hasPrimaryRemote: true,
+      isDefaultRef: false,
+      refName: BRANCH_NAME,
       hasWorkingTreeChanges: false,
       workingTree: { files: [], insertions: 0, deletions: 0 },
       hasUpstream: true,
diff --git a/apps/web/src/components/GitActionsControl.logic.test.ts b/apps/web/src/components/GitActionsControl.logic.test.ts
index 267cbec180d..7950753330e 100644
--- a/apps/web/src/components/GitActionsControl.logic.test.ts
+++ b/apps/web/src/components/GitActionsControl.logic.test.ts
@@ -1,4 +1,4 @@
-import type { GitStatusResult } from "@t3tools/contracts";
+import type { VcsStatusResult } from "@t3tools/contracts";
 import { assert, describe, it } from "vitest";
 import {
   buildGitActionProgressStages,
@@ -11,12 +11,12 @@ import {
   resolveThreadBranchUpdate,
 } from "./GitActionsControl.logic";
 
-function status(overrides: Partial<GitStatusResult> = {}): GitStatusResult {
+function status(overrides: Partial<VcsStatusResult> = {}): VcsStatusResult {
   return {
     isRepo: true,
-    hasOriginRemote: true,
-    isDefaultBranch: false,
-    branch: "feature/test",
+    hasPrimaryRemote: true,
+    isDefaultRef: false,
+    refName: "feature/test",
     hasWorkingTreeChanges: false,
     workingTree: {
       files: [],
@@ -31,7 +31,7 @@ function status(overrides: Partial<GitStatusResult> = {}): GitStatusResult {
   };
 }
 
-describe("when: branch is clean and has an open PR", () => {
+describe("when: ref is clean and has an open PR", () => {
   it("resolveQuickAction opens the existing PR", () => {
     const quick = resolveQuickAction(
       status({
@@ -39,8 +39,8 @@ describe("when: branch is clean and has an open PR", () => {
           number: 10,
           title: "Open PR",
           url: "https://example.com/pr/10",
-          baseBranch: "main",
-          headBranch: "feature/test",
+          baseRef: "main",
+          headRef: "feature/test",
           state: "open",
         },
       }),
@@ -56,8 +56,8 @@ describe("when: branch is clean and has an open PR", () => {
           number: 11,
           title: "Existing PR",
           url: "https://example.com/pr/11",
-          baseBranch: "main",
-          headBranch: "feature/test",
+          baseRef: "main",
+          headRef: "feature/test",
           state: "open",
         },
       }),
@@ -150,7 +150,7 @@ describe("when: git status is unavailable", () => {
   });
 });
 
-describe("when: branch is clean, ahead, and has an open PR", () => {
+describe("when: ref is clean, ahead, and has an open PR", () => {
   it("resolveQuickAction prefers push", () => {
     const quick = resolveQuickAction(
       status({
@@ -159,8 +159,8 @@ describe("when: branch is clean, ahead, and has an open PR", () => {
           number: 13,
           title: "Open PR",
           url: "https://example.com/pr/13",
-          baseBranch: "main",
-          headBranch: "feature/test",
+          baseRef: "main",
+          headRef: "feature/test",
           state: "open",
         },
       }),
@@ -177,8 +177,8 @@ describe("when: branch is clean, ahead, and has an open PR", () => {
           number: 12,
           title: "Existing PR",
           url: "https://example.com/pr/12",
-          baseBranch: "main",
-          headBranch: "feature/test",
+          baseRef: "main",
+          headRef: "feature/test",
           state: "open",
         },
       }),
@@ -212,7 +212,7 @@ describe("when: branch is clean, ahead, and has an open PR", () => {
   });
 });
 
-describe("when: branch is clean, ahead, and has no open PR", () => {
+describe("when: ref is clean, ahead, and has no open PR", () => {
   it("resolveQuickAction pushes and creates a PR", () => {
     const quick = resolveQuickAction(status({ aheadCount: 2, pr: null }), false);
     assert.deepInclude(quick, {
@@ -253,7 +253,53 @@ describe("when: branch is clean, ahead, and has no open PR", () => {
   });
 });
 
-describe("when: branch is clean, up to date, and has no open PR", () => {
+describe("when: source control provider uses merge requests", () => {
+  it("uses GitLab MR terminology in quick actions and menu items", () => {
+    const gitlabStatus = status({
+      aheadCount: 2,
+      sourceControlProvider: {
+        kind: "gitlab",
+        name: "GitLab",
+        baseUrl: "https://gitlab.com",
+      },
+    });
+
+    const quick = resolveQuickAction(gitlabStatus, false);
+    const items = buildMenuItems(gitlabStatus, false);
+
+    assert.deepInclude(quick, {
+      kind: "run_action",
+      action: "create_pr",
+      label: "Push & create MR",
+    });
+    assert.deepInclude(items[2], {
+      id: "pr",
+      label: "Create MR",
+    });
+  });
+});
+
+describe("when: ref is clean, up to date, and has no open PR", () => {
+  it("enables create PR when synced with upstream but ahead of default", () => {
+    const syncedFeature = status({
+      aheadCount: 0,
+      behindCount: 0,
+      aheadOfDefaultCount: 1,
+      pr: null,
+    });
+
+    const quick = resolveQuickAction(syncedFeature, false);
+    assert.deepInclude(quick, {
+      label: "Create PR",
+      disabled: false,
+      kind: "run_action",
+      action: "create_pr",
+    });
+
+    const items = buildMenuItems(syncedFeature, false);
+    assert.equal(items.find((item) => item.id === "pr")?.disabled, false);
+  });
+
   it("resolveQuickAction returns disabled no-action state", () => {
     const quick = resolveQuickAction(
       status({ aheadCount: 0, behindCount: 0, hasWorkingTreeChanges: false, pr: null }),
@@ -293,7 +339,7 @@ describe("when: branch is clean, up to date, and has no open PR", () => {
   });
 });
 
-describe("when: branch is behind upstream", () => {
+describe("when: ref is behind upstream", () => {
   it("resolveQuickAction returns pull", () => {
     const quick = resolveQuickAction(status({ behindCount: 2 }), false);
     assert.deepInclude(quick, { kind: "run_pull", label: "Pull", disabled: false });
@@ -330,11 +376,11 @@ describe("when: branch is behind upstream", () => {
   });
 });
 
-describe("when: branch has diverged from upstream", () => {
+describe("when: ref has diverged from upstream", () => {
   it("resolveQuickAction returns a disabled sync hint", () => {
     const quick = resolveQuickAction(status({ aheadCount: 2, behindCount: 1 }), false);
     assert.deepEqual(quick, {
-      label: "Sync branch",
+      label: "Sync ref",
       disabled: true,
       kind: "show_hint",
       hint: "Branch has diverged from upstream. Rebase/merge first.",
@@ -375,8 +421,8 @@ describe("when: working tree has local changes", () => {
           number: 16,
           title: "Existing PR",
           url: "https://example.com/pr/16",
-          baseBranch: "main",
-          headBranch: "feature/test",
+          baseRef: "main",
+          headRef: "feature/test",
           state: "open",
         },
       }),
@@ -418,12 +464,54 @@ describe("when: working tree has local changes", () => {
       },
     ]);
   });
+
+  it("buildMenuItems enables push for ahead commits while local changes remain uncommitted", () => {
+    const items = buildMenuItems(
+      status({
+        refName: "feature/test",
+        hasWorkingTreeChanges: true,
+        aheadCount: 1,
+        workingTree: {
+          files: [{ path: ".vercel/project.json", insertions: 1, deletions: 0 }],
+          insertions: 1,
+          deletions: 0,
+        },
+      }),
+      false,
+    );
+    assert.deepEqual(items, [
+      {
+        id: "commit",
+        label: "Commit",
+        disabled: false,
+        icon: "commit",
+        kind: "open_dialog",
+        dialogAction: "commit",
+      },
+      {
+        id: "push",
+        label: "Push",
+        disabled: false,
+        icon: "push",
+        kind: "open_dialog",
+        dialogAction: "push",
+      },
+      {
+        id: "pr",
+        label: "Create PR",
+        disabled: true,
+        icon: "pr",
+        kind: "open_dialog",
+        dialogAction: "create_pr",
+      },
+    ]);
+  });
 });
 
-describe("when: on default branch without open PR", () => {
+describe("when: on default ref without open PR", () => {
   it("resolveQuickAction returns commit and push when local changes exist", () => {
     const quick = resolveQuickAction(
-      status({ branch: "main", hasWorkingTreeChanges: true }),
+      status({ refName: "main", hasWorkingTreeChanges: true }),
       false,
       true,
     );
@@ -435,9 +523,9 @@ describe("when: on default branch without open PR", () => {
     });
   });
 
-  it("resolveQuickAction returns push when branch is ahead", () => {
+  it("resolveQuickAction returns push when ref is ahead", () => {
     const quick = resolveQuickAction(
-      status({ branch: "main", aheadCount: 2, pr: null }),
+      status({ refName: "main", aheadCount: 2, pr: null }),
       false,
       true,
     );
@@ -450,7 +538,7 @@ describe("when: on default branch without open PR", () => {
   });
 });
 
-describe("when: working tree has local changes and branch is behind upstream", () => {
+describe("when: working tree has local changes and ref is behind upstream", () => {
   it("resolveQuickAction still prefers commit, push, and create PR", () => {
     const quick = resolveQuickAction(
       status({ hasWorkingTreeChanges: true, behindCount: 1 }),
@@ -497,14 +585,14 @@ describe("when: working tree has local changes and branch is behind upstream", (
 describe("when: HEAD is detached and there are no local changes", () => {
   it("resolveQuickAction shows detached head hint", () => {
     const quick = resolveQuickAction(
-      status({ branch: null, hasWorkingTreeChanges: false, hasUpstream: false }),
+      status({ refName: null, hasWorkingTreeChanges: false, hasUpstream: false }),
       false,
     );
     assert.deepInclude(quick, { kind: "show_hint", label: "Commit", disabled: true });
   });
 
   it("buildMenuItems keeps commit, push, and PR disabled", () => {
-    const items = buildMenuItems(status({ branch: null, hasWorkingTreeChanges: false }), false);
+    const items = buildMenuItems(status({ refName: null, hasWorkingTreeChanges: false }), false);
     assert.deepEqual(items, [
       {
         id: "commit",
@@ -534,7 +622,7 @@ describe("when: HEAD is detached and there are no local changes", () => {
   });
 });
 
-describe("when: branch has no upstream configured", () => {
+describe("when: ref has no upstream configured", () => {
   it("resolveQuickAction is disabled when clean, no upstream, and no local commits are ahead", () => {
     const quick = resolveQuickAction(
       status({ hasUpstream: false, pr: null, aheadCount: 0 }),
@@ -557,8 +645,8 @@ describe("when: branch has no upstream configured", () => {
           number: 14,
           title: "Existing PR",
           url: "https://example.com/pr/14",
-          baseBranch: "main",
-          headBranch: "feature/test",
+          baseRef: "main",
+          headRef: "feature/test",
           state: "open",
         },
       }),
@@ -580,8 +668,8 @@ describe("when: branch has no upstream configured", () => {
           number: 15,
           title: "Existing PR",
           url: "https://example.com/pr/15",
-          baseBranch: "main",
-          headBranch: "feature/test",
+          baseRef: "main",
+          headRef: "feature/test",
           state: "open",
         },
       }),
@@ -642,7 +730,7 @@ describe("when: branch has no upstream configured", () => {
     });
   });
 
-  it("resolveQuickAction disables push-and-pr flows when no origin remote exists", () => {
+  it("resolveQuickAction publishes when no origin remote exists", () => {
     const quick = resolveQuickAction(
       status({
         hasUpstream: false,
@@ -654,10 +742,9 @@ describe("when: branch has no upstream configured", () => {
       false,
     );
     assert.deepEqual(quick, {
-      kind: "show_hint",
-      label: "Push",
-      hint: 'Add an "origin" remote before pushing or creating a PR.',
-      disabled: true,
+      kind: "open_publish",
+      label: "Publish repository",
+      disabled: false,
     });
   });
 
@@ -691,7 +778,7 @@ describe("when: branch has no upstream configured", () => {
     ]);
   });
 
-  it("buildMenuItems disables push and create PR when no origin remote exists", () => {
+  it("buildMenuItems hides push and create PR when no origin remote exists", () => {
     const items = buildMenuItems(
       status({ hasUpstream: false, pr: null, aheadCount: 2 }),
       false,
@@ -706,29 +793,13 @@ describe("when: branch has no upstream configured", () => {
         kind: "open_dialog",
         dialogAction: "commit",
       },
-      {
-        id: "push",
-        label: "Push",
-        disabled: true,
-        icon: "push",
-        kind: "open_dialog",
-        dialogAction: "push",
-      },
-      {
-        id: "pr",
-        label: "Create PR",
-        disabled: true,
-        icon: "pr",
-        kind: "open_dialog",
-        dialogAction: "create_pr",
-      },
     ]);
   });
 
-  it("resolveQuickAction is disabled on default branch when no upstream exists and no commits are ahead", () => {
+  it("resolveQuickAction is disabled on default ref when no upstream exists and no commits are ahead", () => {
     const quick = resolveQuickAction(
       status({
-        branch: "main",
+        refName: "main",
         hasUpstream: false,
         aheadCount: 0,
         pr: null,
@@ -744,10 +815,10 @@ describe("when: branch has no upstream configured", () => {
     });
   });
 
-  it("resolveQuickAction uses push-only on default branch when no upstream exists and commits are ahead", () => {
+  it("resolveQuickAction uses push-only on default ref when no upstream exists and commits are ahead", () => {
     const quick = resolveQuickAction(
       status({
-        branch: "main",
+        refName: "main",
         hasUpstream: false,
         aheadCount: 1,
         pr: null,
@@ -763,7 +834,7 @@ describe("when: branch has no upstream configured", () => {
     });
   });
 
-  it("buildMenuItems still disables push and create PR when branch is behind", () => {
+  it("buildMenuItems still disables push and create PR when ref is behind", () => {
     const items = buildMenuItems(
       status({
         hasUpstream: false,
@@ -803,7 +874,7 @@ describe("when: branch has no upstream configured", () => {
 });
 
 describe("requiresDefaultBranchConfirmation", () => {
-  it("requires confirmation for push actions on default branch", () => {
+  it("requires confirmation for push actions on default ref", () => {
     assert.isFalse(requiresDefaultBranchConfirmation("commit", true));
     assert.isTrue(requiresDefaultBranchConfirmation("push", true));
     assert.isTrue(requiresDefaultBranchConfirmation("create_pr", true));
@@ -823,9 +894,9 @@ describe("resolveDefaultBranchActionDialogCopy", () => {
     });
 
     assert.deepEqual(copy, {
-      title: "Push to default branch?",
+      title: "Push to default ref?",
       description:
-        'This action will push local commits on "main". You can continue on this branch or create a feature branch and run the same action there.',
+        'This action will push local commits on "main". You can continue on this ref or create a feature ref and run the same action there.',
       continueLabel: "Push to main",
     });
   });
@@ -838,9 +909,9 @@ describe("resolveDefaultBranchActionDialogCopy", () => {
     });
 
     assert.deepEqual(copy, {
-      title: "Push & create PR from default branch?",
+      title: "Push & create PR from default ref?",
       description:
-        'This action will push local commits and create a PR on "main". You can continue on this branch or create a feature branch and run the same action there.',
+        'This action will push local commits and create a pull request on "main". You can continue on this ref or create a feature ref and run the same action there.',
       continueLabel: "Push & create PR",
     });
   });
@@ -853,9 +924,9 @@ describe("resolveDefaultBranchActionDialogCopy", () => {
     });
 
     assert.deepEqual(copy, {
-      title: "Commit, push & create PR from default branch?",
+      title: "Commit, push & create PR from default ref?",
       description:
-        'This action will commit, push, and create a PR on "main". You can continue on this branch or create a feature branch and run the same action there.',
+        'This action will commit, push, and create a pull request on "main". You can continue on this ref or create a feature ref and run the same action there.',
       continueLabel: "Commit, push & create PR",
     });
   });
@@ -884,7 +955,7 @@ describe("buildGitActionProgressStages", () => {
       "Pushing to origin/feature/test...",
       "Preparing PR...",
       "Generating PR content...",
-      "Creating GitHub pull request...",
+      "Creating pull request...",
     ]);
   });
 
@@ -898,7 +969,7 @@ describe("buildGitActionProgressStages", () => {
     assert.deepEqual(stages, [
       "Preparing PR...",
       "Generating PR content...",
-      "Creating GitHub pull request...",
+      "Creating pull request...",
     ]);
   });
 
@@ -928,7 +999,7 @@ describe("buildGitActionProgressStages", () => {
       "Pushing to origin/feature/test...",
       "Preparing PR...",
       "Generating PR content...",
-      "Creating GitHub pull request...",
+      "Creating pull request...",
     ]);
   });
 });
@@ -944,7 +1015,7 @@ describe("resolveThreadBranchUpdate", () => {
       commit: {
         status: "created",
         commitSha: "89abcdef01234567",
-        subject: "feat: add branch sync",
+        subject: "feat: add ref sync",
       },
       push: { status: "pushed", branch: "feature/fix-toast-copy" },
       pr: { status: "skipped_not_requested" },
@@ -968,7 +1039,7 @@ describe("resolveThreadBranchUpdate", () => {
       commit: {
         status: "created",
         commitSha: "89abcdef01234567",
-        subject: "feat: add branch sync",
+        subject: "feat: add ref sync",
       },
       push: { status: "pushed", branch: "feature/fix-toast-copy" },
       pr: { status: "skipped_not_requested" },
@@ -985,8 +1056,8 @@ describe("resolveThreadBranchUpdate", () => {
 describe("resolveLiveThreadBranchUpdate", () => {
   it("returns a branch update when live git status differs from stored thread metadata", () => {
     const update = resolveLiveThreadBranchUpdate({
-      threadBranch: "feature/old-branch",
-      gitStatus: status({ branch: "effect-atom" }),
+      threadBranch: "feature/old-ref",
+      gitStatus: status({ refName: "effect-atom" }),
     });
 
     assert.deepEqual(update, {
@@ -996,26 +1067,35 @@ describe("resolveLiveThreadBranchUpdate", () => {
 
   it("returns null when live git status is unavailable", () => {
     const update = resolveLiveThreadBranchUpdate({
-      threadBranch: "feature/old-branch",
+      threadBranch: "feature/old-ref",
       gitStatus: null,
     });
 
     assert.equal(update, null);
   });
 
-  it("returns null when the stored thread branch already matches git status", () => {
+  it("returns null when the stored thread ref already matches git status", () => {
     const update = resolveLiveThreadBranchUpdate({
       threadBranch: "effect-atom",
-      gitStatus: status({ branch: "effect-atom" }),
+      gitStatus: status({ refName: "effect-atom" }),
     });
 
     assert.equal(update, null);
   });
 
-  it("returns null when git status is detached HEAD but the thread already has a branch", () => {
+  it("returns null when git status is detached HEAD but the thread already has a ref", () => {
     const update = resolveLiveThreadBranchUpdate({
       threadBranch: "effect-atom",
-      gitStatus: status({ branch: null }),
+      gitStatus: status({ refName: null }),
+    });
+
+    assert.equal(update, null);
+  });
+
+  it("does not regress a semantic thread ref back to a temporary worktree ref", () => {
+    const update = resolveLiveThreadBranchUpdate({
+      threadBranch: "t3code/github-query-rate-limit",
+      gitStatus: status({ refName: "t3code/bda76797" }),
     });
 
     assert.equal(update, null);
@@ -1023,31 +1103,31 @@ describe("resolveLiveThreadBranchUpdate", () => {
 });
 
 describe("resolveAutoFeatureBranchName", () => {
-  it("uses semantic preferred branch names when available", () => {
-    const branch = resolveAutoFeatureBranchName(["main", "feature/other"], "fix toast copy");
-    assert.equal(branch, "feature/fix-toast-copy");
+  it("uses semantic preferred ref names when available", () => {
+    const ref = resolveAutoFeatureBranchName(["main", "feature/other"], "fix toast copy");
+    assert.equal(ref, "feature/fix-toast-copy");
   });
 
-  it("normalizes preferred names that already include a branch namespace", () => {
-    const branch = resolveAutoFeatureBranchName(["main"], "feature/refine-toolbar-actions");
-    assert.equal(branch, "feature/refine-toolbar-actions");
+  it("normalizes preferred names that already include a ref namespace", () => {
+    const ref = resolveAutoFeatureBranchName(["main"], "feature/refine-toolbar-actions");
+    assert.equal(ref, "feature/refine-toolbar-actions");
   });
 
-  it("increments suffix when the preferred branch name already exists", () => {
-    const branch = resolveAutoFeatureBranchName(
+  it("increments suffix when the preferred ref name already exists", () => {
+    const ref = resolveAutoFeatureBranchName(
       ["main", "feature/fix-toast-copy", "feature/fix-toast-copy-2"],
       "fix toast copy",
     );
-    assert.equal(branch, "feature/fix-toast-copy-3");
+    assert.equal(ref, "feature/fix-toast-copy-3");
   });
 
-  it("treats existing branch names as case-insensitive for collision checks", () => {
-    const branch = resolveAutoFeatureBranchName(["Feature/Ticket-1"], "feature/ticket-1");
-    assert.equal(branch, "feature/ticket-1-2");
+  it("treats existing ref names as case-insensitive for collision checks", () => {
+    const ref = resolveAutoFeatureBranchName(["Feature/Ticket-1"], "feature/ticket-1");
+    assert.equal(ref, "feature/ticket-1-2");
   });
 
   it("falls back to feature/update when no preferred name is provided", () => {
-    const branch = resolveAutoFeatureBranchName(["main"]);
-    assert.equal(branch, "feature/update");
+    const ref = resolveAutoFeatureBranchName(["main"]);
+    assert.equal(ref, "feature/update");
   });
 });
diff --git a/apps/web/src/components/GitActionsControl.logic.ts b/apps/web/src/components/GitActionsControl.logic.ts
index b4b0b98b0b1..3f6bae61cdd 100644
--- a/apps/web/src/components/GitActionsControl.logic.ts
+++ b/apps/web/src/components/GitActionsControl.logic.ts
@@ -1,8 +1,14 @@
 import type {
   GitRunStackedActionResult,
   GitStackedAction,
-  GitStatusResult,
+  VcsStatusResult,
 } from "@t3tools/contracts";
+import { isTemporaryWorktreeBranch } from "@t3tools/shared/git";
+import {
+  DEFAULT_CHANGE_REQUEST_TERMINOLOGY,
+  getChangeRequestTerminology,
+  type ChangeRequestTerminology,
+} from "../sourceControlPresentation";
 
 export type GitActionIconName = "commit" | "push" | "pr";
 
@@ -20,7 +26,7 @@ export interface GitActionMenuItem {
 export interface GitQuickAction {
   label: string;
   disabled: boolean;
-  kind: "run_action" | "run_pull" | "open_pr" | "show_hint";
+  kind: "run_action" | "run_pull" | "open_pr" | "open_publish" | "show_hint";
   action?: GitStackedAction;
   hint?: string;
 }
@@ -37,6 +43,14 @@ export type DefaultBranchConfirmableAction =
   | "commit_push"
   | "commit_push_pr";
 
+function resolveChangeRequestTerminology(
+  gitStatus: VcsStatusResult | null,
+): ChangeRequestTerminology {
+  return gitStatus?.sourceControlProvider
+    ? getChangeRequestTerminology(gitStatus.sourceControlProvider)
+    : DEFAULT_CHANGE_REQUEST_TERMINOLOGY;
+}
+
 export function buildGitActionProgressStages(input: {
   action: GitStackedAction;
   hasCustomCommitMessage: boolean;
@@ -44,13 +58,15 @@ export function buildGitActionProgressStages(input: {
   pushTarget?: string;
   featureBranch?: boolean;
   shouldPushBeforePr?: boolean;
+  terminology?: ChangeRequestTerminology;
 }): string[] {
-  const branchStages = input.featureBranch ? ["Preparing feature branch..."] : [];
+  const terminology = input.terminology ?? DEFAULT_CHANGE_REQUEST_TERMINOLOGY;
+  const branchStages = input.featureBranch ? ["Preparing feature ref..."] : [];
   const pushStage = input.pushTarget ? `Pushing to ${input.pushTarget}...` : "Pushing...";
   const prStages = [
-    "Preparing PR...",
-    "Generating PR content...",
-    "Creating GitHub pull request...",
+    `Preparing ${terminology.shortLabel}...`,
+    `Generating ${terminology.shortLabel} content...`,
+    `Creating ${terminology.singular}...`,
   ];
 
   if (input.action === "push") {
@@ -76,22 +92,23 @@ export function buildGitActionProgressStages(input: {
 }
 
 export function buildMenuItems(
-  gitStatus: GitStatusResult | null,
+  gitStatus: VcsStatusResult | null,
   isBusy: boolean,
-  hasOriginRemote = true,
+  hasPrimaryRemote = true,
 ): GitActionMenuItem[] {
   if (!gitStatus) return [];
+  const terminology = resolveChangeRequestTerminology(gitStatus);
 
-  const hasBranch = gitStatus.branch !== null;
+  const hasBranch = gitStatus.refName !== null;
   const hasChanges = gitStatus.hasWorkingTreeChanges;
   const hasOpenPr = gitStatus.pr?.state === "open";
   const isBehind = gitStatus.behindCount > 0;
-  const canPushWithoutUpstream = hasOriginRemote && !gitStatus.hasUpstream;
+  const hasDefaultBranchDelta = (gitStatus.aheadOfDefaultCount ?? gitStatus.aheadCount) > 0;
+  const canPushWithoutUpstream = hasPrimaryRemote && !gitStatus.hasUpstream;
   const canCommit = !isBusy && hasChanges;
   const canPush =
     !isBusy &&
     hasBranch &&
-    !hasChanges &&
     !isBehind &&
     gitStatus.aheadCount > 0 &&
     (gitStatus.hasUpstream || canPushWithoutUpstream);
@@ -100,20 +117,26 @@ export function buildMenuItems(
     hasBranch &&
     !hasChanges &&
     !hasOpenPr &&
-    gitStatus.aheadCount > 0 &&
+    hasDefaultBranchDelta &&
     !isBehind &&
     (gitStatus.hasUpstream || canPushWithoutUpstream);
   const canOpenPr = !isBusy && hasOpenPr;
 
+  const commitItem: GitActionMenuItem = {
+    id: "commit",
+    label: "Commit",
+    disabled: !canCommit,
+    icon: "commit",
+    kind: "open_dialog",
+    dialogAction: "commit",
+  };
+
+  if (!hasPrimaryRemote) {
+    return [commitItem];
+  }
+
   return [
-    {
-      id: "commit",
-      label: "Commit",
-      disabled: !canCommit,
-      icon: "commit",
-      kind: "open_dialog",
-      dialogAction: "commit",
-    },
+    commitItem,
     {
       id: "push",
       label: "Push",
@@ -125,14 +148,14 @@ export function buildMenuItems(
     hasOpenPr
       ? {
           id: "pr",
-          label: "View PR",
+          label: `View ${terminology.shortLabel}`,
           disabled: !canOpenPr,
           icon: "pr",
           kind: "open_pr",
         }
       : {
           id: "pr",
-          label: "Create PR",
+          label: `Create ${terminology.shortLabel}`,
           disabled: !canCreatePr,
           icon: "pr",
           kind: "open_dialog",
@@ -142,10 +165,10 @@ export function buildMenuItems(
 }
 
 export function resolveQuickAction(
-  gitStatus: GitStatusResult | null,
+  gitStatus: VcsStatusResult | null,
   isBusy: boolean,
-  isDefaultBranch = false,
-  hasOriginRemote = true,
+  isDefaultRef = false,
+  hasPrimaryRemote = true,
 ): GitQuickAction {
   if (isBusy) {
     return { label: "Commit", disabled: true, kind: "show_hint", hint: "Git action in progress." };
@@ -160,31 +183,33 @@ export function resolveQuickAction(
     };
   }
 
-  const hasBranch = gitStatus.branch !== null;
+  const hasBranch = gitStatus.refName !== null;
   const hasChanges = gitStatus.hasWorkingTreeChanges;
   const hasOpenPr = gitStatus.pr?.state === "open";
   const isAhead = gitStatus.aheadCount > 0;
+  const hasDefaultBranchDelta = (gitStatus.aheadOfDefaultCount ?? gitStatus.aheadCount) > 0;
   const isBehind = gitStatus.behindCount > 0;
   const isDiverged = isAhead && isBehind;
+  const terminology = resolveChangeRequestTerminology(gitStatus);
 
   if (!hasBranch) {
     return {
       label: "Commit",
       disabled: true,
       kind: "show_hint",
-      hint: "Create and checkout a branch before pushing or opening a PR.",
+      hint: `Create and checkout a ref before pushing or opening a ${terminology.singular}.`,
     };
   }
 
   if (hasChanges) {
-    if (!gitStatus.hasUpstream && !hasOriginRemote) {
+    if (!gitStatus.hasUpstream && !hasPrimaryRemote) {
       return { label: "Commit", disabled: false, kind: "run_action", action: "commit" };
     }
-    if (hasOpenPr || isDefaultBranch) {
+    if (hasOpenPr || isDefaultRef) {
       return { label: "Commit & push", disabled: false, kind: "run_action", action: "commit_push" };
     }
     return {
-      label: "Commit, push & PR",
+      label: `Commit, push & ${terminology.shortLabel}`,
       disabled: false,
       kind: "run_action",
       action: "commit_push_pr",
@@ -192,20 +217,19 @@ export function resolveQuickAction(
   }
 
   if (!gitStatus.hasUpstream) {
-    if (!hasOriginRemote) {
+    if (!hasPrimaryRemote) {
       if (hasOpenPr && !isAhead) {
-        return { label: "View PR", disabled: false, kind: "open_pr" };
+        return { label: `View ${terminology.shortLabel}`, disabled: false, kind: "open_pr" };
       }
       return {
-        label: "Push",
-        disabled: true,
-        kind: "show_hint",
-        hint: 'Add an "origin" remote before pushing or creating a PR.',
+        label: "Publish repository",
+        disabled: false,
+        kind: "open_publish",
       };
     }
     if (!isAhead) {
       if (hasOpenPr) {
-        return { label: "View PR", disabled: false, kind: "open_pr" };
+        return { label: `View ${terminology.shortLabel}`, disabled: false, kind: "open_pr" };
       }
       return {
         label: "Push",
@@ -214,16 +238,16 @@ export function resolveQuickAction(
         hint: "No local commits to push.",
       };
     }
-    if (hasOpenPr || isDefaultBranch) {
+    if (hasOpenPr || isDefaultRef) {
       return {
         label: "Push",
         disabled: false,
         kind: "run_action",
-        action: isDefaultBranch ? "commit_push" : "push",
+        action: isDefaultRef ? "commit_push" : "push",
       };
     }
     return {
-      label: "Push & create PR",
+      label: `Push & create ${terminology.shortLabel}`,
       disabled: false,
       kind: "run_action",
       action: "create_pr",
@@ -232,7 +256,7 @@ export function resolveQuickAction(
 
   if (isDiverged) {
     return {
-      label: "Sync branch",
+      label: "Sync ref",
       disabled: true,
       kind: "show_hint",
       hint: "Branch has diverged from upstream. Rebase/merge first.",
@@ -248,16 +272,16 @@ export function resolveQuickAction(
   }
 
   if (isAhead) {
-    if (hasOpenPr || isDefaultBranch) {
+    if (hasOpenPr || isDefaultRef) {
       return {
         label: "Push",
         disabled: false,
         kind: "run_action",
-        action: isDefaultBranch ? "commit_push" : "push",
+        action: isDefaultRef ? "commit_push" : "push",
       };
     }
     return {
-      label: "Push & create PR",
+      label: `Push & create ${terminology.shortLabel}`,
       disabled: false,
       kind: "run_action",
       action: "create_pr",
@@ -265,7 +289,16 @@ export function resolveQuickAction(
   }
 
   if (hasOpenPr && gitStatus.hasUpstream) {
-    return { label: "View PR", disabled: false, kind: "open_pr" };
+    return { label: `View ${terminology.shortLabel}`, disabled: false, kind: "open_pr" };
+  }
+
+  if (hasDefaultBranchDelta && !isDefaultRef) {
+    return {
+      label: `Create ${terminology.shortLabel}`,
+      disabled: false,
+      kind: "run_action",
+      action: "create_pr",
+    };
   }
 
   return {
@@ -278,9 +311,9 @@ export function resolveQuickAction(
 
 export function requiresDefaultBranchConfirmation(
   action: GitStackedAction,
-  isDefaultBranch: boolean,
+  isDefaultRef: boolean,
 ): boolean {
-  if (!isDefaultBranch) return false;
+  if (!isDefaultRef) return false;
   return (
     action === "push" ||
     action === "create_pr" ||
@@ -293,20 +326,22 @@ export function resolveDefaultBranchActionDialogCopy(input: {
   action: DefaultBranchConfirmableAction;
   branchName: string;
   includesCommit: boolean;
+  terminology?: ChangeRequestTerminology;
 }): DefaultBranchActionDialogCopy {
   const branchLabel = input.branchName;
-  const suffix = ` on "${branchLabel}". You can continue on this branch or create a feature branch and run the same action there.`;
+  const suffix = ` on "${branchLabel}". You can continue on this ref or create a feature ref and run the same action there.`;
+  const terminology = input.terminology ?? DEFAULT_CHANGE_REQUEST_TERMINOLOGY;
 
   if (input.action === "push" || input.action === "commit_push") {
     if (input.includesCommit) {
       return {
-        title: "Commit & push to default branch?",
+        title: "Commit & push to default ref?",
         description: `This action will commit and push changes${suffix}`,
         continueLabel: `Commit & push to ${branchLabel}`,
       };
     }
     return {
-      title: "Push to default branch?",
+      title: "Push to default ref?",
       description: `This action will push local commits${suffix}`,
       continueLabel: `Push to ${branchLabel}`,
     };
@@ -314,15 +349,15 @@ export function resolveDefaultBranchActionDialogCopy(input: {
 
   if (input.includesCommit) {
     return {
-      title: "Commit, push & create PR from default branch?",
-      description: `This action will commit, push, and create a PR${suffix}`,
-      continueLabel: `Commit, push & create PR`,
+      title: `Commit, push & create ${terminology.shortLabel} from default ref?`,
+      description: `This action will commit, push, and create a ${terminology.singular}${suffix}`,
+      continueLabel: `Commit, push & create ${terminology.shortLabel}`,
     };
   }
   return {
-    title: "Push & create PR from default branch?",
-    description: `This action will push local commits and create a PR${suffix}`,
-    continueLabel: "Push & create PR",
+    title: `Push & create ${terminology.shortLabel} from default ref?`,
+    description: `This action will push local commits and create a ${terminology.singular}${suffix}`,
+    continueLabel: `Push & create ${terminology.shortLabel}`,
   };
 }
 
@@ -340,22 +375,31 @@ export function resolveThreadBranchUpdate(
 
 export function resolveLiveThreadBranchUpdate(input: {
   threadBranch: string | null;
-  gitStatus: GitStatusResult | null;
+  gitStatus: VcsStatusResult | null;
 }): { branch: string | null } | null {
   if (!input.gitStatus) {
     return null;
   }
 
-  if (input.gitStatus.branch === null && input.threadBranch !== null) {
+  if (input.gitStatus.refName === null && input.threadBranch !== null) {
+    return null;
+  }
+
+  if (input.threadBranch === input.gitStatus.refName) {
     return null;
   }
 
-  if (input.threadBranch === input.gitStatus.branch) {
+  if (
+    input.threadBranch !== null &&
+    input.gitStatus.refName !== null &&
+    !isTemporaryWorktreeBranch(input.threadBranch) &&
+    isTemporaryWorktreeBranch(input.gitStatus.refName)
+  ) {
     return null;
   }
 
   return {
-    branch: input.gitStatus.branch,
+    branch: input.gitStatus.refName,
   };
 }
 
diff --git a/apps/web/src/components/GitActionsControl.tsx b/apps/web/src/components/GitActionsControl.tsx
index 6d2312e4aac..341aaed9f1b 100644
--- a/apps/web/src/components/GitActionsControl.tsx
+++ b/apps/web/src/components/GitActionsControl.tsx
@@ -3,12 +3,33 @@ import type {
   GitActionProgressEvent,
   GitRunStackedActionResult,
   GitStackedAction,
-  GitStatusResult,
+  SourceControlCloneProtocol,
+  SourceControlProviderDiscoveryItem,
+  SourceControlProviderKind,
+  SourceControlPublishRepositoryResult,
+  SourceControlRepositoryVisibility,
+  VcsStatusResult,
 } from "@t3tools/contracts";
 import { useIsMutating, useMutation, useQueryClient } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import * as Option from "effect/Option";
 import { useCallback, useEffect, useEffectEvent, useMemo, useRef, useState } from "react";
-import { ChevronDownIcon, CloudUploadIcon, GitCommitIcon, InfoIcon } from "lucide-react";
-import { GitHubIcon } from "./Icons";
+import { flushSync } from "react-dom";
+import {
+  CheckIcon,
+  ChevronDownIcon,
+  CloudUploadIcon,
+  ExternalLinkIcon,
+  GitCommitIcon,
+  InfoIcon,
+  LockIcon,
+  GlobeIcon,
+} from "lucide-react";
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+import { AzureDevOpsIcon, BitbucketIcon, GitHubIcon, GitLabIcon } from "~/components/Icons";
+import { RadioGroup } from "~/components/ui/radio-group";
+import { Spinner } from "~/components/ui/spinner";
+import { cn } from "~/lib/utils";
 import {
   buildGitActionProgressStages,
   buildMenuItems,
@@ -22,6 +43,7 @@ import {
   resolveQuickAction,
   resolveThreadBranchUpdate,
 } from "./GitActionsControl.logic";
+import { AnimatedHeight } from "./AnimatedHeight";
 import { Button } from "~/components/ui/button";
 import { Checkbox } from "~/components/ui/checkbox";
 import {
@@ -34,24 +56,29 @@ import {
   DialogTitle,
 } from "~/components/ui/dialog";
 import { Group, GroupSeparator } from "~/components/ui/group";
+import { Input } from "~/components/ui/input";
 import { Menu, MenuItem, MenuPopup, MenuTrigger } from "~/components/ui/menu";
 import { Popover, PopoverPopup, PopoverTrigger } from "~/components/ui/popover";
 import { ScrollArea } from "~/components/ui/scroll-area";
 import { Textarea } from "~/components/ui/textarea";
-import { toastManager, type ThreadToastData } from "~/components/ui/toast";
+import { stackedThreadToast, toastManager, type ThreadToastData } from "~/components/ui/toast";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "~/components/ui/tooltip";
 import { openInPreferredEditor } from "~/editorPreferences";
 import {
   gitInitMutationOptions,
   gitMutationKeys,
   gitPullMutationOptions,
   gitRunStackedActionMutationOptions,
+  sourceControlPublishRepositoryMutationOptions,
 } from "~/lib/gitReactQuery";
 import { refreshGitStatus, useGitStatus } from "~/lib/gitStatusState";
+import { useSourceControlDiscovery } from "~/lib/sourceControlDiscoveryState";
 import { newCommandId, randomUUID } from "~/lib/utils";
 import { resolvePathLinkTarget } from "~/terminal-links";
 import { type DraftId, useComposerDraftStore } from "~/composerDraftStore";
 import { readEnvironmentApi } from "~/environmentApi";
 import { readLocalApi } from "~/localApi";
+import { getSourceControlPresentation } from "~/sourceControlPresentation";
 import { useStore } from "~/store";
 import { createThreadSelectorByRef } from "~/storeSelectors";
 
@@ -70,6 +97,11 @@ interface PendingDefaultBranchAction {
   filePaths?: string[];
 }
 
+type PublishProviderKind = Extract<
+  SourceControlProviderKind,
+  "github" | "gitlab" | "bitbucket" | "azure-devops"
+>;
+
 type GitActionToastId = ReturnType<typeof toastManager.add>;
 
 interface ActiveGitActionProgress {
@@ -89,7 +121,7 @@ interface RunGitActionWithToastInput {
   commitMessage?: string;
   onConfirmed?: () => void;
   skipDefaultBranchPrompt?: boolean;
-  statusOverride?: GitStatusResult | null;
+  statusOverride?: VcsStatusResult | null;
   featureBranch?: boolean;
   progressToastId?: GitActionToastId;
   filePaths?: string[];
@@ -97,6 +129,88 @@ interface RunGitActionWithToastInput {
 
 const GIT_STATUS_WINDOW_REFRESH_DEBOUNCE_MS = 250;
 
+const PUBLISH_PROVIDER_OPTIONS = [
+  {
+    value: "github",
+    label: "GitHub",
+    description: "github.com",
+    host: "github.com",
+    pathPlaceholder: "owner/repo",
+    Icon: GitHubIcon,
+  },
+  {
+    value: "gitlab",
+    label: "GitLab",
+    description: "gitlab.com",
+    host: "gitlab.com",
+    pathPlaceholder: "group/project",
+    Icon: GitLabIcon,
+  },
+  {
+    value: "bitbucket",
+    label: "Bitbucket",
+    description: "bitbucket.org",
+    host: "bitbucket.org",
+    pathPlaceholder: "workspace/repository",
+    Icon: BitbucketIcon,
+  },
+  {
+    value: "azure-devops",
+    label: "Azure DevOps",
+    description: "dev.azure.com",
+    host: "dev.azure.com",
+    pathPlaceholder: "project/repository",
+    Icon: AzureDevOpsIcon,
+  },
+] as const satisfies ReadonlyArray<{
+  readonly value: PublishProviderKind;
+  readonly label: string;
+  readonly description: string;
+  readonly host: string;
+  readonly pathPlaceholder: string;
+  readonly Icon: typeof GitHubIcon;
+}>;
+
+function publishProviderOption(provider: PublishProviderKind) {
+  return (
+    PUBLISH_PROVIDER_OPTIONS.find((option) => option.value === provider) ??
+    PUBLISH_PROVIDER_OPTIONS[0]
+  );
+}
+
+function isPublishProviderKind(
+  provider: SourceControlProviderKind,
+): provider is PublishProviderKind {
+  return PUBLISH_PROVIDER_OPTIONS.some((option) => option.value === provider);
+}
+
+function getPublishProviderReadiness(input: {
+  provider: PublishProviderKind;
+  sourceControlProviders: ReadonlyArray<SourceControlProviderDiscoveryItem>;
+}): { readonly ready: boolean; readonly hint: string | null } {
+  const discovered = input.sourceControlProviders.find(
+    (provider) => provider.kind === input.provider,
+  );
+  if (!discovered) {
+    return {
+      ready: false,
+      hint: "Provider status unavailable. Open Settings -> Source Control and rescan.",
+    };
+  }
+  if (discovered.status !== "available") {
+    return { ready: false, hint: discovered.installHint };
+  }
+  if (discovered.auth.status === "unauthenticated") {
+    return {
+      ready: false,
+      hint:
+        Option.getOrNull(discovered.auth.detail) ??
+        `${discovered.label} is not authenticated. Open Settings -> Source Control for setup guidance.`,
+    };
+  }
+  return { ready: true, hint: null };
+}
+
 function formatElapsedDescription(startedAtMs: number | null): string | undefined {
   if (startedAtMs === null) {
     return undefined;
@@ -121,22 +235,23 @@ function getMenuActionDisabledReason({
   item,
   gitStatus,
   isBusy,
-  hasOriginRemote,
+  hasPrimaryRemote,
 }: {
   item: GitActionMenuItem;
-  gitStatus: GitStatusResult | null;
+  gitStatus: VcsStatusResult | null;
   isBusy: boolean;
-  hasOriginRemote: boolean;
+  hasPrimaryRemote: boolean;
 }): string | null {
   if (!item.disabled) return null;
   if (isBusy) return "Git action in progress.";
   if (!gitStatus) return "Git status is unavailable.";
 
-  const hasBranch = gitStatus.branch !== null;
+  const hasBranch = gitStatus.refName !== null;
   const hasChanges = gitStatus.hasWorkingTreeChanges;
   const hasOpenPr = gitStatus.pr?.state === "open";
   const isAhead = gitStatus.aheadCount > 0;
   const isBehind = gitStatus.behindCount > 0;
+  const terminology = getSourceControlPresentation(gitStatus.sourceControlProvider).terminology;
 
   if (item.id === "commit") {
     if (!hasChanges) {
@@ -147,7 +262,7 @@ function getMenuActionDisabledReason({
 
   if (item.id === "push") {
     if (!hasBranch) {
-      return "Detached HEAD: checkout a branch before pushing.";
+      return "Detached HEAD: checkout a refName before pushing.";
     }
     if (hasChanges) {
       return "Commit or stash local changes before pushing.";
@@ -155,7 +270,7 @@ function getMenuActionDisabledReason({
     if (isBehind) {
       return "Branch is behind upstream. Pull/rebase before pushing.";
     }
-    if (!gitStatus.hasUpstream && !hasOriginRemote) {
+    if (!gitStatus.hasUpstream && !hasPrimaryRemote) {
       return 'Add an "origin" remote before pushing.';
     }
     if (!isAhead) {
@@ -165,51 +280,671 @@ function getMenuActionDisabledReason({
   }
 
   if (hasOpenPr) {
-    return "View PR is currently unavailable.";
+    return `View ${terminology.singular} is currently unavailable.`;
   }
   if (!hasBranch) {
-    return "Detached HEAD: checkout a branch before creating a PR.";
+    return `Detached HEAD: checkout a refName before creating a ${terminology.singular}.`;
   }
   if (hasChanges) {
-    return "Commit local changes before creating a PR.";
+    return `Commit local changes before creating a ${terminology.singular}.`;
   }
-  if (!gitStatus.hasUpstream && !hasOriginRemote) {
-    return 'Add an "origin" remote before creating a PR.';
+  if (!gitStatus.hasUpstream && !hasPrimaryRemote) {
+    return `Add an "origin" remote before creating a ${terminology.singular}.`;
   }
   if (!isAhead) {
-    return "No local commits to include in a PR.";
+    return `No local commits to include in a ${terminology.singular}.`;
   }
   if (isBehind) {
-    return "Branch is behind upstream. Pull/rebase before creating a PR.";
+    return `Branch is behind upstream. Pull/rebase before creating a ${terminology.singular}.`;
   }
-  return "Create PR is currently unavailable.";
+  return `Create ${terminology.singular} is currently unavailable.`;
 }
 
 const COMMIT_DIALOG_TITLE = "Commit changes";
 const COMMIT_DIALOG_DESCRIPTION =
   "Review and confirm your commit. Leave the message blank to auto-generate one.";
 
-function GitActionItemIcon({ icon }: { icon: GitActionIconName }) {
+function GitActionItemIcon({
+  icon,
+  SourceControlIcon,
+}: {
+  icon: GitActionIconName;
+  SourceControlIcon: ReturnType<typeof getSourceControlPresentation>["Icon"];
+}) {
   if (icon === "commit") return <GitCommitIcon />;
   if (icon === "push") return <CloudUploadIcon />;
-  return <GitHubIcon />;
+  return <SourceControlIcon />;
 }
 
-function GitQuickActionIcon({ quickAction }: { quickAction: GitQuickAction }) {
+function GitQuickActionIcon({
+  quickAction,
+  SourceControlIcon,
+}: {
+  quickAction: GitQuickAction;
+  SourceControlIcon: ReturnType<typeof getSourceControlPresentation>["Icon"];
+}) {
   const iconClassName = "size-3.5";
-  if (quickAction.kind === "open_pr") return <GitHubIcon className={iconClassName} />;
+  if (quickAction.kind === "open_pr") return <SourceControlIcon className={iconClassName} />;
+  if (quickAction.kind === "open_publish") return <CloudUploadIcon className={iconClassName} />;
   if (quickAction.kind === "run_pull") return <InfoIcon className={iconClassName} />;
   if (quickAction.kind === "run_action") {
     if (quickAction.action === "commit") return <GitCommitIcon className={iconClassName} />;
     if (quickAction.action === "push" || quickAction.action === "commit_push") {
       return <CloudUploadIcon className={iconClassName} />;
     }
-    return <GitHubIcon className={iconClassName} />;
+    return <SourceControlIcon className={iconClassName} />;
   }
   if (quickAction.label === "Commit") return <GitCommitIcon className={iconClassName} />;
   return <InfoIcon className={iconClassName} />;
 }
 
+interface PublishRepositoryDialogProps {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly environmentId: ScopedThreadRef["environmentId"] | null;
+  readonly gitCwd: string;
+}
+
+function PublishRepositoryDialog(props: PublishRepositoryDialogProps) {
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const sourceControlDiscovery = useSourceControlDiscovery();
+  const [publishProvider, setPublishProvider] = useState<PublishProviderKind>("github");
+  const [publishRepository, setPublishRepository] = useState("");
+  const [publishVisibility, setPublishVisibility] =
+    useState<SourceControlRepositoryVisibility>("private");
+  const [publishRemoteName, setPublishRemoteName] = useState("origin");
+  const [publishProtocol, setPublishProtocol] = useState<SourceControlCloneProtocol>("ssh");
+  const [publishWizardStep, setPublishWizardStep] = useState(0);
+  const [publishAdvancedOpen, setPublishAdvancedOpen] = useState(false);
+  const [publishError, setPublishError] = useState<string | null>(null);
+  const [publishResult, setPublishResult] = useState<SourceControlPublishRepositoryResult | null>(
+    null,
+  );
+  const [hasUserEditedPublishRepository, setHasUserEditedPublishRepository] = useState(false);
+  const publishRepositoryMutation = useMutation(
+    sourceControlPublishRepositoryMutationOptions({
+      environmentId: props.environmentId,
+      cwd: props.gitCwd,
+      queryClient,
+    }),
+  );
+  const publishAccountByProvider = useMemo(() => {
+    const accounts: Record<PublishProviderKind, string | null> = {
+      github: null,
+      gitlab: null,
+      bitbucket: null,
+      "azure-devops": null,
+    };
+    for (const provider of sourceControlDiscovery.data?.sourceControlProviders ?? []) {
+      if (isPublishProviderKind(provider.kind)) {
+        accounts[provider.kind] = Option.getOrNull(provider.auth.account);
+      }
+    }
+    return accounts;
+  }, [sourceControlDiscovery.data]);
+  const publishProviderReadiness = useMemo(() => {
+    const sourceControlProviders = sourceControlDiscovery.data?.sourceControlProviders ?? [];
+    return Object.fromEntries(
+      PUBLISH_PROVIDER_OPTIONS.map((option) => [
+        option.value,
+        getPublishProviderReadiness({
+          provider: option.value,
+          sourceControlProviders,
+        }),
+      ]),
+    ) as Record<PublishProviderKind, { readonly ready: boolean; readonly hint: string | null }>;
+  }, [sourceControlDiscovery.data]);
+  const hasReadyPublishProvider = useMemo(
+    () => PUBLISH_PROVIDER_OPTIONS.some((option) => publishProviderReadiness[option.value].ready),
+    [publishProviderReadiness],
+  );
+  const sortedPublishProviderOptions = useMemo(
+    () =>
+      PUBLISH_PROVIDER_OPTIONS.toSorted((left, right) => {
+        const leftReady = publishProviderReadiness[left.value].ready;
+        const rightReady = publishProviderReadiness[right.value].ready;
+        if (leftReady !== rightReady) {
+          return leftReady ? -1 : 1;
+        }
+        return left.label.localeCompare(right.label);
+      }),
+    [publishProviderReadiness],
+  );
+  const selectedPublishProviderReadiness = publishProviderReadiness[publishProvider];
+  const publishRepositoryPrefill = publishAccountByProvider[publishProvider]
+    ? `${publishAccountByProvider[publishProvider]}/`
+    : "";
+  const currentPublishProvider = publishProviderOption(publishProvider);
+  const publishHost = currentPublishProvider.host;
+  const publishPathPlaceholder = currentPublishProvider.pathPlaceholder;
+  const publishProviderLabel = currentPublishProvider.label;
+  const publishWizardSteps = ["Provider", "Repository", "Summary"] as const;
+  const publishWizardStepSummaries = [
+    publishProviderLabel,
+    publishResult?.repository.nameWithOwner ?? null,
+    null,
+  ] as const;
+
+  useEffect(() => {
+    if (!props.open || hasUserEditedPublishRepository) {
+      return;
+    }
+    setPublishRepository(publishRepositoryPrefill);
+  }, [hasUserEditedPublishRepository, props.open, publishRepositoryPrefill]);
+
+  const canSubmitPublishRepository = useMemo(() => {
+    if (!selectedPublishProviderReadiness.ready) return false;
+    if (publishRepositoryMutation.isPending) return false;
+    const repositoryParts = publishRepository.trim().split("/");
+    const owner = repositoryParts[0]?.trim() ?? "";
+    const rest = repositoryParts.slice(1);
+    const name = rest.join("/").trim();
+    return owner.length > 0 && name.length > 0;
+  }, [publishRepository, publishRepositoryMutation.isPending, selectedPublishProviderReadiness]);
+
+  useEffect(() => {
+    if (!props.open) {
+      return;
+    }
+    if (publishProviderReadiness[publishProvider].ready) {
+      return;
+    }
+    const firstReadyProvider = PUBLISH_PROVIDER_OPTIONS.find(
+      (option) => publishProviderReadiness[option.value].ready,
+    );
+    if (firstReadyProvider) {
+      setPublishProvider(firstReadyProvider.value);
+    }
+  }, [props.open, publishProvider, publishProviderReadiness]);
+
+  const submitPublishRepository = useCallback(() => {
+    if (!canSubmitPublishRepository) {
+      return;
+    }
+
+    setPublishError(null);
+
+    void publishRepositoryMutation
+      .mutateAsync({
+        provider: publishProvider,
+        repository: publishRepository.trim(),
+        visibility: publishVisibility,
+        remoteName: publishRemoteName.trim() || "origin",
+        protocol: publishProtocol,
+      })
+      .then((result) => {
+        flushSync(() => {
+          setPublishResult(result);
+          setPublishWizardStep(2);
+        });
+        void refreshGitStatus({ environmentId: props.environmentId, cwd: props.gitCwd }).catch(
+          () => undefined,
+        );
+      })
+      .catch((err: unknown) => {
+        setPublishError(err instanceof Error ? err.message : "An error occurred.");
+      });
+  }, [
+    canSubmitPublishRepository,
+    props.environmentId,
+    props.gitCwd,
+    publishProtocol,
+    publishProvider,
+    publishRemoteName,
+    publishRepository,
+    publishRepositoryMutation,
+    publishVisibility,
+  ]);
+
+  const resetState = useCallback(() => {
+    setPublishRemoteName("origin");
+    setPublishRepository("");
+    setHasUserEditedPublishRepository(false);
+    setPublishWizardStep(0);
+    setPublishAdvancedOpen(false);
+    setPublishError(null);
+    setPublishResult(null);
+  }, []);
+
+  const handleOpenChange = useCallback(
+    (open: boolean) => {
+      props.onOpenChange(open);
+      if (!open) {
+        resetState();
+      }
+    },
+    [props, resetState],
+  );
+
+  const openSourceControlSettings = useCallback(() => {
+    handleOpenChange(false);
+    void navigate({ to: "/settings/source-control" });
+  }, [handleOpenChange, navigate]);
+
+  return (
+    <Dialog open={props.open} onOpenChange={handleOpenChange}>
+      <DialogPopup className="max-w-xl overflow-hidden">
+        <div className="flex min-h-0 flex-col overflow-hidden border-foreground/10 bg-background shadow-2xl">
+          <DialogHeader className="border-b border-border/70 bg-background">
+            <DialogTitle>Publish repository</DialogTitle>
+            <DialogDescription>
+              Pick where to host it, then point us at a repo to push to.
+            </DialogDescription>
+            <div className="grid grid-cols-3 gap-2">
+              {publishWizardSteps.map((label, index) => {
+                const isComplete = index < publishWizardStep;
+                const isClickable =
+                  publishWizardStep !== 2 &&
+                  index < publishWizardSteps.length - 1 &&
+                  index <= publishWizardStep;
+                return (
+                  <button
+                    key={label}
+                    type="button"
+                    onClick={isClickable ? () => setPublishWizardStep(index) : undefined}
+                    disabled={!isClickable}
+                    className={cn(
+                      "grid min-w-0 grid-cols-[1rem_minmax(0,1fr)] gap-x-2 rounded-lg border px-3 py-2 text-left",
+                      index === publishWizardStep
+                        ? "border-primary bg-primary/10 ring-1 ring-primary/25"
+                        : isComplete
+                          ? "border-border bg-background"
+                          : "border-border bg-muted/40",
+                      !isClickable && "cursor-default",
+                    )}
+                  >
+                    <span
+                      aria-hidden
+                      className={cn(
+                        "row-span-2 mt-0.5 grid size-4 place-items-center rounded-full border",
+                        isComplete
+                          ? "border-primary bg-primary text-primary-foreground"
+                          : index === publishWizardStep
+                            ? "border-primary bg-background"
+                            : "border-muted-foreground/35 bg-background",
+                      )}
+                    >
+                      {isComplete ? <CheckIcon className="size-3" /> : null}
+                    </span>
+                    <span className="text-[10px] font-medium uppercase text-muted-foreground">
+                      Step {index + 1}
+                    </span>
+                    <span className="truncate text-xs font-semibold text-foreground">
+                      {label}
+                      {isComplete && publishWizardStepSummaries[index]
+                        ? `: ${publishWizardStepSummaries[index]}`
+                        : ""}
+                    </span>
+                  </button>
+                );
+              })}
+            </div>
+          </DialogHeader>
+
+          <DialogPanel className="space-y-5 border-b border-border/70 bg-muted/20 px-6 py-5">
+            <AnimatedHeight>
+              <div className={cn("space-y-2", publishWizardStep !== 0 && "hidden")}>
+                <span
+                  id="publish-provider-cards-label"
+                  className="text-xs font-medium text-foreground"
+                >
+                  Provider
+                </span>
+                <RadioGroup
+                  value={publishProvider}
+                  onValueChange={(value) => setPublishProvider(value as PublishProviderKind)}
+                  aria-labelledby="publish-provider-cards-label"
+                  className="grid grid-cols-2 gap-2.5"
+                >
+                  {sortedPublishProviderOptions.map((option) => {
+                    const readiness = publishProviderReadiness[option.value];
+                    const isSelected = publishProvider === option.value && readiness.ready;
+                    if (!readiness.ready) {
+                      return (
+                        <div
+                          key={option.value}
+                          className="relative flex cursor-not-allowed items-center gap-3 rounded-lg border border-border bg-background px-3 py-3 text-left opacity-55"
+                        >
+                          <option.Icon
+                            className="size-5 shrink-0 text-muted-foreground"
+                            aria-hidden
+                          />
+                          <span className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">
+                            {option.label}
+                          </span>
+                          <Tooltip>
+                            <TooltipTrigger
+                              render={
+                                <Button
+                                  variant="outline"
+                                  size="xs"
+                                  className="h-5 rounded-[.25rem] px-1.5 text-[10px] text-warning-foreground"
+                                  onClick={(event) => {
+                                    event.preventDefault();
+                                    event.stopPropagation();
+                                    openSourceControlSettings();
+                                  }}
+                                >
+                                  Setup Required
+                                </Button>
+                              }
+                            />
+                            <TooltipPopup side="top" align="end" className="max-w-72">
+                              {readiness.hint ??
+                                "Open Settings -> Source Control to configure this provider."}
+                            </TooltipPopup>
+                          </Tooltip>
+                        </div>
+                      );
+                    }
+
+                    return (
+                      <RadioPrimitive.Root
+                        key={option.value}
+                        value={option.value}
+                        className={cn(
+                          "relative flex cursor-pointer items-center gap-3 rounded-lg border px-3 py-3 text-left outline-none transition-[background-color,border-color,box-shadow]",
+                          "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                          isSelected
+                            ? "border-primary bg-background shadow-sm ring-2 ring-primary/35"
+                            : "border-border bg-background hover:border-foreground/20 hover:bg-muted/50",
+                        )}
+                      >
+                        <option.Icon className="size-5 shrink-0" aria-hidden />
+                        <span className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">
+                          {option.label}
+                        </span>
+                      </RadioPrimitive.Root>
+                    );
+                  })}
+                </RadioGroup>
+              </div>
+
+              <div className={cn("space-y-5", publishWizardStep !== 1 && "hidden")}>
+                <div className="space-y-2">
+                  <label
+                    htmlFor="publish-repository-path"
+                    className="text-xs font-medium text-foreground"
+                  >
+                    Repository
+                  </label>
+                  <div className="flex items-stretch overflow-hidden rounded-md border border-input bg-background focus-within:outline-2 focus-within:-outline-offset-1 focus-within:outline-ring">
+                    <span className="flex shrink-0 items-center gap-1.5 border-r border-input bg-muted/50 px-2.5 font-mono text-xs text-muted-foreground">
+                      <currentPublishProvider.Icon className="size-3.5" />
+                      {publishHost}/
+                    </span>
+                    <input
+                      id="publish-repository-path"
+                      name="publish-repository-path"
+                      value={publishRepository}
+                      onChange={(event) => {
+                        setPublishRepository(event.target.value);
+                        setHasUserEditedPublishRepository(true);
+                      }}
+                      onKeyDown={(event) => {
+                        if (event.key === "Enter") {
+                          event.preventDefault();
+                          submitPublishRepository();
+                        }
+                      }}
+                      placeholder={publishPathPlaceholder}
+                      disabled={publishRepositoryMutation.isPending}
+                      className="w-full bg-transparent px-3 py-2 font-mono text-sm placeholder:text-muted-foreground/60 focus:outline-none"
+                    />
+                  </div>
+                </div>
+
+                <div className="space-y-2">
+                  <span
+                    id="publish-visibility-cards-label"
+                    className="text-xs font-medium text-foreground"
+                  >
+                    Visibility
+                  </span>
+                  <RadioGroup
+                    value={publishVisibility}
+                    onValueChange={(value) =>
+                      setPublishVisibility(value as SourceControlRepositoryVisibility)
+                    }
+                    aria-labelledby="publish-visibility-cards-label"
+                    disabled={publishRepositoryMutation.isPending}
+                    className="grid grid-cols-2 gap-2.5"
+                  >
+                    {[
+                      {
+                        value: "private" as const,
+                        label: "Private",
+                        description: "Only invited people",
+                        Icon: LockIcon,
+                      },
+                      {
+                        value: "public" as const,
+                        label: "Public",
+                        description: "Anyone on the web",
+                        Icon: GlobeIcon,
+                      },
+                    ].map((option) => {
+                      const isSelected = publishVisibility === option.value;
+                      return (
+                        <RadioPrimitive.Root
+                          key={option.value}
+                          value={option.value}
+                          className={cn(
+                            "relative flex cursor-pointer items-center gap-3 rounded-lg border px-3 py-2.5 text-left outline-none transition-[background-color,border-color,box-shadow]",
+                            "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                            isSelected
+                              ? "border-primary bg-background shadow-sm ring-2 ring-primary/35"
+                              : "border-border bg-background hover:border-foreground/20 hover:bg-muted/50",
+                          )}
+                        >
+                          <option.Icon
+                            className="size-4 shrink-0 text-muted-foreground"
+                            aria-hidden
+                          />
+                          <span className="min-w-0 flex-1">
+                            <span className="block text-sm font-medium text-foreground">
+                              {option.label}
+                            </span>
+                            <span className="block text-xs text-muted-foreground">
+                              {option.description}
+                            </span>
+                          </span>
+                        </RadioPrimitive.Root>
+                      );
+                    })}
+                  </RadioGroup>
+                </div>
+
+                <div>
+                  <button
+                    type="button"
+                    onClick={() => setPublishAdvancedOpen((prev) => !prev)}
+                    aria-expanded={publishAdvancedOpen}
+                    className="flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground"
+                  >
+                    <ChevronDownIcon
+                      className={cn(
+                        "size-3.5 transition-transform",
+                        publishAdvancedOpen ? "" : "-rotate-90",
+                      )}
+                    />
+                    Advanced
+                  </button>
+                  {publishAdvancedOpen ? (
+                    <div className="mt-3 grid gap-3 sm:grid-cols-2">
+                      <label className="space-y-1.5" htmlFor="publish-remote-name">
+                        <span className="text-xs font-medium text-foreground">Remote</span>
+                        <Input
+                          id="publish-remote-name"
+                          value={publishRemoteName}
+                          onChange={(event) => setPublishRemoteName(event.target.value)}
+                          placeholder="origin"
+                          disabled={publishRepositoryMutation.isPending}
+                        />
+                      </label>
+                      <div className="space-y-1.5">
+                        <span
+                          id="publish-protocol-label"
+                          className="text-xs font-medium text-foreground"
+                        >
+                          Protocol
+                        </span>
+                        <RadioGroup
+                          value={publishProtocol}
+                          onValueChange={(value) =>
+                            setPublishProtocol(value as SourceControlCloneProtocol)
+                          }
+                          aria-labelledby="publish-protocol-label"
+                          disabled={publishRepositoryMutation.isPending}
+                          className="grid grid-cols-2 gap-2"
+                        >
+                          {(["ssh", "https"] as const).map((value) => {
+                            const isSelected = publishProtocol === value;
+                            return (
+                              <RadioPrimitive.Root
+                                key={value}
+                                value={value}
+                                className={cn(
+                                  "rounded-md border px-3 py-1.5 text-center text-sm font-medium outline-none transition",
+                                  "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                                  isSelected
+                                    ? "border-primary bg-background ring-2 ring-primary/35 text-foreground"
+                                    : "border-border bg-background text-muted-foreground hover:border-foreground/20 hover:text-foreground",
+                                )}
+                              >
+                                {value === "ssh" ? "SSH" : "HTTPS"}
+                              </RadioPrimitive.Root>
+                            );
+                          })}
+                        </RadioGroup>
+                      </div>
+                    </div>
+                  ) : null}
+                </div>
+
+                {publishRepositoryMutation.isPending ? (
+                  <div
+                    role="status"
+                    aria-live="polite"
+                    className="flex items-center gap-2 rounded-md border border-input bg-muted/40 px-3 py-2 text-xs text-muted-foreground"
+                  >
+                    <Spinner className="size-3.5" aria-hidden />
+                    Publishing repository to {publishProviderLabel}...
+                  </div>
+                ) : null}
+                {publishError && !publishRepositoryMutation.isPending ? (
+                  <div
+                    role="alert"
+                    className="rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive"
+                  >
+                    <p className="font-medium">Publish failed</p>
+                    <p className="mt-0.5 text-destructive/90">{publishError}</p>
+                  </div>
+                ) : null}
+              </div>
+
+              <div className={cn("space-y-4", publishWizardStep !== 2 && "hidden")}>
+                {publishResult ? (
+                  <>
+                    <div className="flex flex-col items-center gap-2 py-1 text-center">
+                      <span className="grid size-8 place-items-center rounded-full bg-success/15 text-success">
+                        <CheckIcon className="size-4" aria-hidden />
+                      </span>
+                      <h3 className="text-sm font-semibold text-foreground">
+                        {publishResult.status === "pushed"
+                          ? "Repository published"
+                          : "Repository created"}
+                      </h3>
+                      <p className="max-w-xs text-pretty text-xs text-muted-foreground">
+                        {publishResult.status === "pushed"
+                          ? `${publishResult.branch} is now live on ${publishProviderLabel}.`
+                          : `Remote "${publishResult.remoteName}" is set up. Make a commit and push it to share your code.`}
+                      </p>
+                    </div>
+                    <div className="flex items-center gap-2 rounded-lg border border-input bg-muted/40 px-3 py-2">
+                      <currentPublishProvider.Icon className="size-3.5 shrink-0 text-muted-foreground" />
+                      <span className="min-w-0 flex-1 truncate font-mono text-xs text-foreground">
+                        {publishResult.repository.nameWithOwner}
+                      </span>
+                    </div>
+                    <Button
+                      variant="outline"
+                      size="sm"
+                      className="w-full"
+                      onClick={() => {
+                        const api = readLocalApi();
+                        if (!api) return;
+                        void api.shell.openExternal(publishResult.repository.url);
+                      }}
+                    >
+                      <ExternalLinkIcon className="size-3.5" aria-hidden />
+                      Open on {publishProviderLabel}
+                    </Button>
+                  </>
+                ) : (
+                  <div className="rounded-md border border-input bg-background px-3 py-2 text-xs text-muted-foreground">
+                    Publish result unavailable.
+                  </div>
+                )}
+              </div>
+            </AnimatedHeight>
+          </DialogPanel>
+
+          <DialogFooter>
+            {publishWizardStep === 2 ? (
+              <Button size="sm" onClick={() => handleOpenChange(false)}>
+                Done
+              </Button>
+            ) : (
+              <>
+                <Button
+                  variant="outline"
+                  size="sm"
+                  disabled={publishRepositoryMutation.isPending}
+                  onClick={() => {
+                    if (publishWizardStep === 0) {
+                      handleOpenChange(false);
+                      return;
+                    }
+                    setPublishWizardStep((step) => Math.max(0, step - 1));
+                  }}
+                >
+                  {publishWizardStep === 0 ? "Cancel" : "Back"}
+                </Button>
+                {publishWizardStep < 1 ? (
+                  <Button
+                    size="sm"
+                    disabled={!hasReadyPublishProvider || !selectedPublishProviderReadiness.ready}
+                    onClick={() => setPublishWizardStep((step) => Math.min(1, step + 1))}
+                  >
+                    Next
+                  </Button>
+                ) : (
+                  <Button
+                    size="sm"
+                    disabled={!canSubmitPublishRepository}
+                    onClick={submitPublishRepository}
+                  >
+                    {publishRepositoryMutation.isPending ? (
+                      <>
+                        <Spinner className="size-3.5" aria-hidden />
+                        Publishing...
+                      </>
+                    ) : (
+                      "Publish"
+                    )}
+                  </Button>
+                )}
+              </>
+            )}
+          </DialogFooter>
+        </div>
+      </DialogPopup>
+    </Dialog>
+  );
+}
+
 export default function GitActionsControl({
   gitCwd,
   activeThreadRef,
@@ -239,6 +974,7 @@ export default function GitActionsControl({
   const [dialogCommitMessage, setDialogCommitMessage] = useState("");
   const [excludedFiles, setExcludedFiles] = useState<ReadonlySet<string>>(new Set());
   const [isEditingFiles, setIsEditingFiles] = useState(false);
+  const [isPublishDialogOpen, setIsPublishDialogOpen] = useState(false);
   const [pendingDefaultBranchAction, setPendingDefaultBranchAction] =
     useState<PendingDefaultBranchAction | null>(null);
   const activeGitActionProgressRef = useRef<ActiveGitActionProgress | null>(null);
@@ -322,9 +1058,15 @@ export default function GitActionsControl({
     environmentId: activeEnvironmentId,
     cwd: gitCwd,
   });
+  const sourceControlPresentation = useMemo(
+    () => getSourceControlPresentation(gitStatus?.sourceControlProvider),
+    [gitStatus?.sourceControlProvider],
+  );
+  const changeRequestTerminology = sourceControlPresentation.terminology;
+  const SourceControlIcon = sourceControlPresentation.Icon;
   // Default to true while loading so we don't flash init controls.
   const isRepo = gitStatus?.isRepo ?? true;
-  const hasOriginRemote = gitStatus?.hasOriginRemote ?? false;
+  const hasPrimaryRemote = gitStatus?.hasPrimaryRemote ?? false;
   const gitStatusForActions = gitStatus;
 
   const allFiles = gitStatusForActions?.workingTree.files ?? [];
@@ -353,7 +1095,11 @@ export default function GitActionsControl({
     }) > 0;
   const isPullRunning =
     useIsMutating({ mutationKey: gitMutationKeys.pull(activeEnvironmentId, gitCwd) }) > 0;
-  const isGitActionRunning = isRunStackedActionRunning || isPullRunning;
+  const isPublishRunning =
+    useIsMutating({
+      mutationKey: gitMutationKeys.publishRepository(activeEnvironmentId, gitCwd),
+    }) > 0;
+  const isGitActionRunning = isRunStackedActionRunning || isPullRunning || isPublishRunning;
   const isSelectingWorktreeBase =
     !activeServerThread &&
     activeDraftThread?.envMode === "worktree" &&
@@ -382,18 +1128,18 @@ export default function GitActionsControl({
     persistThreadBranchSync,
   ]);
 
-  const isDefaultBranch = useMemo(() => {
-    return gitStatusForActions?.isDefaultBranch ?? false;
-  }, [gitStatusForActions?.isDefaultBranch]);
+  const isDefaultRef = useMemo(() => {
+    return gitStatusForActions?.isDefaultRef ?? false;
+  }, [gitStatusForActions?.isDefaultRef]);
 
   const gitActionMenuItems = useMemo(
-    () => buildMenuItems(gitStatusForActions, isGitActionRunning, hasOriginRemote),
-    [gitStatusForActions, hasOriginRemote, isGitActionRunning],
+    () => buildMenuItems(gitStatusForActions, isGitActionRunning, hasPrimaryRemote),
+    [gitStatusForActions, hasPrimaryRemote, isGitActionRunning],
   );
   const quickAction = useMemo(
     () =>
-      resolveQuickAction(gitStatusForActions, isGitActionRunning, isDefaultBranch, hasOriginRemote),
-    [gitStatusForActions, hasOriginRemote, isDefaultBranch, isGitActionRunning],
+      resolveQuickAction(gitStatusForActions, isGitActionRunning, isDefaultRef, hasPrimaryRemote),
+    [gitStatusForActions, hasPrimaryRemote, isDefaultRef, isGitActionRunning],
   );
   const quickActionDisabledReason = quickAction.disabled
     ? (quickAction.hint ?? "This action is currently unavailable.")
@@ -403,6 +1149,7 @@ export default function GitActionsControl({
         action: pendingDefaultBranchAction.action,
         branchName: pendingDefaultBranchAction.branchName,
         includesCommit: pendingDefaultBranchAction.includesCommit,
+        terminology: changeRequestTerminology,
       })
     : null;
 
@@ -468,18 +1215,20 @@ export default function GitActionsControl({
     if (!prUrl) {
       toastManager.add({
         type: "error",
-        title: "No open PR found.",
+        title: "No open pull request found.",
         data: threadToastData,
       });
       return;
     }
     void api.shell.openExternal(prUrl).catch((err: unknown) => {
-      toastManager.add({
-        type: "error",
-        title: "Unable to open PR link",
-        description: err instanceof Error ? err.message : "An error occurred.",
-        data: threadToastData,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Unable to open pull request link",
+          description: err instanceof Error ? err.message : "An error occurred.",
+          ...(threadToastData !== undefined ? { data: threadToastData } : {}),
+        }),
+      );
     });
   }, [gitStatusForActions, threadToastData]);
 
@@ -495,8 +1244,8 @@ export default function GitActionsControl({
       filePaths,
     }: RunGitActionWithToastInput) => {
       const actionStatus = statusOverride ?? gitStatusForActions;
-      const actionBranch = actionStatus?.branch ?? null;
-      const actionIsDefaultBranch = featureBranch ? false : isDefaultBranch;
+      const actionBranch = actionStatus?.refName ?? null;
+      const actionIsDefaultBranch = featureBranch ? false : isDefaultRef;
       const actionCanCommit =
         action === "commit" || action === "commit_push" || action === "commit_push_pr";
       const includesCommit =
@@ -532,6 +1281,7 @@ export default function GitActionsControl({
         hasCustomCommitMessage: !!commitMessage?.trim(),
         hasWorkingTreeChanges: !!actionStatus?.hasWorkingTreeChanges,
         featureBranch,
+        terminology: changeRequestTerminology,
         shouldPushBeforePr:
           action === "create_pr" &&
           (!actionStatus?.hasUpstream || (actionStatus?.aheadCount ?? 0) > 0),
@@ -670,33 +1420,43 @@ export default function GitActionsControl({
           };
         }
 
-        const successToastBase = {
-          type: "success",
-          title: result.toast.title,
-          description: result.toast.description,
-          timeout: 0,
-          data: {
-            ...scopedToastData,
-            dismissAfterVisibleMs: 10_000,
-          },
-        } as const;
+        const successToastData = {
+          ...scopedToastData,
+          dismissAfterVisibleMs: 10_000,
+        };
 
         if (toastActionProps) {
+          toastManager.update(
+            resolvedProgressToastId,
+            stackedThreadToast({
+              type: "success",
+              title: result.toast.title,
+              description: result.toast.description,
+              timeout: 0,
+              actionProps: toastActionProps,
+              data: successToastData,
+            }),
+          );
+        } else {
           toastManager.update(resolvedProgressToastId, {
-            ...successToastBase,
-            actionProps: toastActionProps,
+            type: "success",
+            title: result.toast.title,
+            description: result.toast.description,
+            timeout: 0,
+            data: successToastData,
           });
-        } else {
-          toastManager.update(resolvedProgressToastId, successToastBase);
         }
       } catch (err) {
         activeGitActionProgressRef.current = null;
-        toastManager.update(resolvedProgressToastId, {
-          type: "error",
-          title: "Action failed",
-          description: err instanceof Error ? err.message : "An error occurred.",
-          data: scopedToastData,
-        });
+        toastManager.update(
+          resolvedProgressToastId,
+          stackedThreadToast({
+            type: "error",
+            title: "Action failed",
+            description: err instanceof Error ? err.message : "An error occurred.",
+            ...(scopedToastData !== undefined ? { data: scopedToastData } : {}),
+          }),
+        );
       }
     },
   );
@@ -751,16 +1511,23 @@ export default function GitActionsControl({
       void openExistingPr();
       return;
     }
+    if (quickAction.kind === "open_publish") {
+      setIsPublishDialogOpen(true);
+      return;
+    }
     if (quickAction.kind === "run_pull") {
       const promise = pullMutation.mutateAsync();
-      toastManager.promise(promise, {
+      void toastManager.promise<
+        Awaited<ReturnType<typeof pullMutation.mutateAsync>>,
+        ThreadToastData
+      >(promise, {
         loading: { title: "Pulling...", data: threadToastData },
         success: (result) => ({
           title: result.status === "pulled" ? "Pulled" : "Already up to date",
           description:
             result.status === "pulled"
-              ? `Updated ${result.branch} from ${result.upstreamBranch ?? "upstream"}`
-              : `${result.branch} is already synchronized.`,
+              ? `Updated ${result.refName} from ${result.upstreamRef ?? "upstream"}`
+              : `${result.refName} is already synchronized.`,
           data: threadToastData,
         }),
         error: (err) => ({
@@ -832,17 +1599,21 @@ export default function GitActionsControl({
       }
       const target = resolvePathLinkTarget(filePath, gitCwd);
       void openInPreferredEditor(api, target).catch((error) => {
-        toastManager.add({
-          type: "error",
-          title: "Unable to open file",
-          description: error instanceof Error ? error.message : "An error occurred.",
-          data: threadToastData,
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Unable to open file",
+            description: error instanceof Error ? error.message : "An error occurred.",
+            ...(threadToastData !== undefined ? { data: threadToastData } : {}),
+          }),
+        );
       });
     },
     [gitCwd, threadToastData],
   );
 
+  const canPublishRepository = isRepo && gitStatusForActions !== null && !hasPrimaryRemote;
+
   if (!gitCwd) return null;
 
   return (
@@ -871,7 +1642,10 @@ export default function GitActionsControl({
                   />
                 }
               >
-                <GitQuickActionIcon quickAction={quickAction} />
+                <GitQuickActionIcon
+                  quickAction={quickAction}
+                  SourceControlIcon={SourceControlIcon}
+                />
                 <span className="sr-only @3xl/header-actions:not-sr-only @3xl/header-actions:ml-0.5">
                   {quickAction.label}
                 </span>
@@ -887,7 +1661,7 @@ export default function GitActionsControl({
               disabled={isGitActionRunning || quickAction.disabled}
               onClick={runQuickAction}
             >
-              <GitQuickActionIcon quickAction={quickAction} />
+              <GitQuickActionIcon quickAction={quickAction} SourceControlIcon={SourceControlIcon} />
               <span className="sr-only @3xl/header-actions:not-sr-only @3xl/header-actions:ml-0.5">
                 {quickAction.label}
               </span>
@@ -916,7 +1690,7 @@ export default function GitActionsControl({
                   item,
                   gitStatus: gitStatusForActions,
                   isBusy: isGitActionRunning,
-                  hasOriginRemote,
+                  hasPrimaryRemote,
                 });
                 if (item.disabled && disabledReason) {
                   return (
@@ -927,7 +1701,10 @@ export default function GitActionsControl({
                         render={<span className="block w-max cursor-not-allowed" />}
                       >
                         <MenuItem className="w-full" disabled>
-                          <GitActionItemIcon icon={item.icon} />
+                          <GitActionItemIcon
+                            icon={item.icon}
+                            SourceControlIcon={SourceControlIcon}
+                          />
                           {item.label}
                         </MenuItem>
                       </PopoverTrigger>
@@ -946,18 +1723,30 @@ export default function GitActionsControl({
                       openDialogForMenuItem(item);
                     }}
                   >
-                    <GitActionItemIcon icon={item.icon} />
+                    <GitActionItemIcon icon={item.icon} SourceControlIcon={SourceControlIcon} />
                     {item.label}
                   </MenuItem>
                 );
               })}
-              {gitStatusForActions?.branch === null && (
+              {canPublishRepository ? (
+                <MenuItem
+                  disabled={isGitActionRunning}
+                  onClick={() => {
+                    setIsPublishDialogOpen(true);
+                  }}
+                >
+                  <CloudUploadIcon />
+                  Publish repository...
+                </MenuItem>
+              ) : null}
+              {gitStatusForActions?.refName === null && (
                 <p className="px-2 py-1.5 text-xs text-warning">
-                  Detached HEAD: create and checkout a branch to enable push and PR actions.
+                  Detached HEAD: create and checkout a refName to enable push and pull request
+                  actions.
                 </p>
               )}
               {gitStatusForActions &&
-                gitStatusForActions.branch !== null &&
+                gitStatusForActions.refName !== null &&
                 !gitStatusForActions.hasWorkingTreeChanges &&
                 gitStatusForActions.behindCount > 0 &&
                 gitStatusForActions.aheadCount === 0 && (
@@ -995,10 +1784,12 @@ export default function GitActionsControl({
                 <span className="text-muted-foreground">Branch</span>
                 <span className="flex items-center justify-between gap-2">
                   <span className="font-medium">
-                    {gitStatusForActions?.branch ?? "(detached HEAD)"}
+                    {gitStatusForActions?.refName ?? "(detached HEAD)"}
                   </span>
-                  {isDefaultBranch && (
-                    <span className="text-right text-warning text-xs">Warning: default branch</span>
+                  {isDefaultRef && (
+                    <span className="text-right text-warning text-xs">
+                      Warning: default refName
+                    </span>
                   )}
                 </span>
               </div>
@@ -1131,7 +1922,7 @@ export default function GitActionsControl({
               disabled={noneSelected}
               onClick={runDialogActionOnNewBranch}
             >
-              Commit on new branch
+              Commit on new refName
             </Button>
             <Button size="sm" disabled={noneSelected} onClick={runDialogAction}>
               Commit
@@ -1140,6 +1931,13 @@ export default function GitActionsControl({
         </DialogPopup>
       </Dialog>
 
+      <PublishRepositoryDialog
+        open={isPublishDialogOpen}
+        onOpenChange={setIsPublishDialogOpen}
+        environmentId={activeEnvironmentId}
+        gitCwd={gitCwd}
+      />
+
       <Dialog
         open={pendingDefaultBranchAction !== null}
         onOpenChange={(open) => {
@@ -1151,18 +1949,32 @@ export default function GitActionsControl({
         <DialogPopup className="max-w-xl">
           <DialogHeader>
             <DialogTitle>
-              {pendingDefaultBranchActionCopy?.title ?? "Run action on default branch?"}
+              {pendingDefaultBranchActionCopy?.title ?? "Run action on default refName?"}
             </DialogTitle>
             <DialogDescription>{pendingDefaultBranchActionCopy?.description}</DialogDescription>
           </DialogHeader>
-          <DialogFooter>
-            <Button variant="outline" size="sm" onClick={() => setPendingDefaultBranchAction(null)}>
+          <DialogFooter className="sm:flex-wrap sm:items-center">
+            <Button
+              className="w-full sm:mr-auto sm:w-auto"
+              variant="outline"
+              size="sm"
+              onClick={() => setPendingDefaultBranchAction(null)}
+            >
               Abort
             </Button>
-            <Button variant="outline" size="sm" onClick={continuePendingDefaultBranchAction}>
+            <Button
+              className="min-h-8 w-full max-w-full whitespace-normal py-1.5 leading-snug sm:min-h-7 sm:w-auto"
+              variant="outline"
+              size="sm"
+              onClick={continuePendingDefaultBranchAction}
+            >
               {pendingDefaultBranchActionCopy?.continueLabel ?? "Continue"}
             </Button>
-            <Button size="sm" onClick={checkoutFeatureBranchAndContinuePendingAction}>
+            <Button
+              className="min-h-8 w-full max-w-full whitespace-normal py-1.5 leading-snug sm:min-h-7 sm:w-auto"
+              size="sm"
+              onClick={checkoutFeatureBranchAndContinuePendingAction}
+            >
               Checkout feature branch & continue
             </Button>
           </DialogFooter>
diff --git a/apps/web/src/components/Icons.tsx b/apps/web/src/components/Icons.tsx
index 37a47bb01b0..b3211e17753 100644
--- a/apps/web/src/components/Icons.tsx
+++ b/apps/web/src/components/Icons.tsx
@@ -1,4 +1,5 @@
-import { type SVGProps, useId } from "react";
+import React, { type SVGProps, useId } from "react";
+import { cn } from "~/lib/utils";
 
 export type Icon = React.FC<SVGProps<SVGSVGElement>>;
 
@@ -14,8 +15,186 @@ export const GitHubIcon: Icon = (props) => (
   </svg>
 );
 
-export const CursorIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 466.73 532.09" fill="currentColor">
+export const GitIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 256 256">
+    <path
+      d="M251.17 116.6 139.4 4.82a16.49 16.49 0 0 0-23.31 0l-23.21 23.2 29.44 29.45a19.57 19.57 0 0 1 24.8 24.96l28.37 28.38a19.61 19.61 0 1 1-11.75 11.06L137.28 95.4v69.64a19.62 19.62 0 1 1-16.13-.57V94.2a19.61 19.61 0 0 1-10.65-25.73L81.46 39.44 4.83 116.08a16.49 16.49 0 0 0 0 23.32L116.6 251.17a16.49 16.49 0 0 0 23.32 0l111.25-111.25a16.5 16.5 0 0 0 0-23.33"
+      fill="#DE4C36"
+    />
+  </svg>
+);
+
+export const JujutsuIcon: Icon = (props) => {
+  const groupId = `${useId().replaceAll(":", "")}-jj-a`;
+
+  return (
+    <svg {...props} viewBox="0 0 1024 1024">
+      <defs>
+        <g id={groupId}>
+          <path
+            d="M380.7 632.3s-14.3 56-50.3 55.5c-12.1-.2-29-10.9-47.1-26.8-34.2 82.7-98.5 239-108.5 268.6-8.9 26.5 13 52 38.2 56 36.4 5.7 49-18.1 49-18.1s13.6 40.7 37.6 39.7c29.9-1.2 34.6-33 34.6-33s11.4 23.8 26.8 23.2c38.4-1.4 41.7-102.9 43.8-135.6 3.8-57.5 6.3-135.4 7.8-190.1-9 6.7-16.5 10.7-21.3 9.9-16.1-2.7-10.6-49.3-10.6-49.3z"
+            fill="#42acde"
+          />
+          <path
+            d="M403.7 75.1c-89.7-.3-201.5 32.6-200.6 99.6 1.3 87.4 52.2 62.4 41.2 111.2-4.9 21.6-59.9 49.8-65.5 153.8 2.8.7 5.3 1 7.2 1.2 14.2.7 29.9-26.3 29.9-26.3s9.5 38 35 38 50.7-26.3 50.7-26.3 15 30.3 39.6 32c20 1.6 34-8 34-8s.8 15 14.6 14c13.9-1.2 37.6-27.8 37.6-27.8 16.5 30.3 31.9 21 54.7 5.1 0 0 6.2 26.6 36.8 23.7 6-.6 12.3-1 18.5-1.5l.9-11.6c2-58.8-20.4-129.8-50.4-183-21.7-38.7-52.5-83.4-49.6-107.3 3.5-28.3 46.7-28.4 46.7-28.4l-48.5-16 24-37a279.7 279.7 0 0 0-56.8-5.4Z"
+            fill="#2f9fdf"
+          />
+          <path
+            d="M215.9 414.6s-15.7 27-30 26.3c-1.8-.1-4.3-.5-7-1.2l-.3 3c-2.3 52 7.7 100.3 29.7 132 35.1 50.7 92.6 112.6 122 113 36.1.6 50.4-55.4 50.4-55.4s-5.5 46.6 10.6 49.3c16 2.6 62.4-46.7 87.9-79.5 15.8-20.5 52-82.3 58.2-138.3-6.2.4-12.4 1-18.5 1.5-30.6 3-36.8-23.7-36.8-23.7-22.8 16-38.2 25.2-54.7-5 0 0-23.7 26.5-37.6 27.6-13.8 1.1-14.6-13.8-14.6-13.8s-14 9.5-34 8c-24.5-1.8-39.6-32.1-39.6-32.1s-25.2 26.3-50.7 26.3c-25.5 0-35-38-35-38z"
+            fill="#0e254f"
+          />
+          <path
+            d="M309.5 418.5a1.5 1.5 0 0 0-.7 0c-.6.2-1.1.8-1.5 1.8a34.7 34.7 0 0 0 4 16.6c5.5 10.6 12.4 22 23.3 27.6 4 2 8.5 3.5 12.5 3.3a36 36 0 0 0 12.5-2.3c4-2 7.6-3.8 10.8-6.2 6-4.4 7.6-6.5 7.6-9.8 0-3.3-2.7-3.5-7.6-.5-5 3-14.6 6.1-18.8 6.1-11.2 0-21.2-8-33.1-26.4-4.3-6.6-7.1-9.9-9-10.2zm174 5c-1.2-.2-2.4.4-3.8 1.7-2.3 2.3-2.7 4-2.6 10.7.5 9 4.8 19.2 11.8 24.6 4.4 3.3 13.2 6 20.4 5.8 6.8-1.1 18.8-6.6 15.3-10.3-2-1.6-5 .7-9.9.7-10.6 0-15.3-3.4-19.6-9-3.8-5-5.4-8.7-7.2-16.8-1.1-4.6-2.6-7.1-4.4-7.4zm-67.5 2.2a1 1 0 0 0-.4 0c-.4.1-.7.4-1.2.9-2.4 2-2.5 5.1-.2 12.6a41.4 41.4 0 0 0 25.3 22c7.6 1.7 14.5.6 20.3-2.7 3.8-2.4 5.3-5 4.4-7.3-4.8-2.9-7.7-1-13.3-1A39.5 39.5 0 0 1 424 435c-4.8-5.9-7-9.3-8-9.4zm-199 .8c-1 .3-1.4 2.7-1 7.2.3 5.3 1.3 8.2 4 12 3 4.5 11.5 11 14.7 11.7 2.5 1 6.9 2.3 10.7 2.3 3.8 0 8-.6 11.2-1.3 3.2-.7 6.8-2 10.3-4l1.3-.7c4-2.1 8-5.1 10.9-7.9l1.4-1.2c6.3-5.4 9.9-10.7 9.9-14.6 0-2.4-5.3-.5-14 5-16 9.8-31.1 13.2-40.9 9l-2.2-1.3-8.8-7.7a32.9 32.9 0 0 1-3.6-4.8c-1.4-2.2-2.5-3.4-3.3-3.7a1 1 0 0 0-.5 0z"
+            fill="#71beea"
+          />
+          <path
+            d="M221.6 468.8c-.5 0-.8.1-1.1.4-.3.2-.5.6-.6 1.2a10 10 0 0 0 .6 5.1 55 55 0 0 0 28.3 28.9 42.4 42.4 0 0 0 16.4 2c6.1-.2 12.3-1.4 16.6-3.4a48.3 48.3 0 0 0 13.7-10.6c.9-1 1.3-2 1.3-2.3 0-.6 0-.9-.3-1-.3-.3-.7-.4-1.6-.4-1.8 0-4.9.8-9.7 2.3-6.2 1.9-12.7 3-18.5 3.1-7.8.2-10.2-.4-17-3.7-4.5-2.2-12-7.7-17.7-12.8a232 232 0 0 0-7.2-6.3 63 63 0 0 0-2.4-2 12 12 0 0 0-.7-.4h-.1zm214.8 13.6c-.2 0-.5.7-.7 1.8v4a32 32 0 0 0 2.7 9.9 38.5 38.5 0 0 0 49.1 19.3c5.2-2.3 10-6.4 13-10.5 1.4-2.1 2.5-4.3 3-6.2.5-1.9.4-3.6-.3-4.9-.4-.8-.9-1.4-1.3-1.7-.3-.3-.6-.3-1-.2-.9.2-2.3 1.4-4.3 3.8-5 6.2-12.8 9.5-22.6 9.4-6.2 0-11-1.1-16-4.4-5-3.2-10.4-8.6-18-17.3-.8-1-1.7-2-2.5-2.4l-1-.6c-.1 0-.2 0 0 0zm-33.6 4.2-.6.2-1.4.7a53.5 53.5 0 0 0-4 2.5c-8 5.5-15.6 8.3-23.9 8.4-8.3 0-17.2-2.7-28-8.2a42 42 0 0 0-7.3-3c-2-.5-3.1-.5-3.6-.2-.2.1-.3.3-.4.6 0 .3 0 .8.2 1.5.4 1.3 1.4 3.1 3.1 5.5 4 5.4 10.5 10.1 19.7 14 9.3 3.9 23.8 3.5 32.4-1a42 42 0 0 0 9.1-6.5c2.6-2.6 4.5-6.5 5.3-9.6.5-1.5.6-3 .4-3.8 0-.4-.2-.7-.4-.9-.1-.2-.3-.2-.6-.2zm-132.5 30.8c-.3 0-.4 0-.5.2l-.1.5c0 .5.4 1.7 1.2 3.1a87.3 87.3 0 0 0 13.5 16.2c17 15.6 34.6 20.7 49 14.4a33.3 33.3 0 0 0 19-23c.4-2 .1-3.1-.2-3.5-.2-.2-.5-.3-1-.3l-1.7.5a24 24 0 0 0-5.7 4.6c-7.7 8-14.6 12-23 11.4-8.3-.4-18-5.2-31.7-14.3-5.2-3.4-9.4-6-12.5-7.6a15.5 15.5 0 0 0-6.3-2.2zm109.4 0c-.2 0-.3 0-.5.2-.1 0-.3.3-.4.7a9 9 0 0 0 0 3.3c.4 2.9 1.6 6.7 3.5 10.3 11 20.5 29.4 30.5 46.8 25.7a37.3 37.3 0 0 0 15.6-10c4.4-4.6 7.4-9.9 7.4-13.8 0-1.3-.1-2.3-.4-2.7 0-.3-.2-.4-.3-.4h-.5c-.6 0-1.5.4-2.7 1.2a57 57 0 0 0-4.7 3.7c-9 7.7-16.9 11.2-25.1 10-8.2-1.3-16.7-7.1-27-17.7a159.8 159.8 0 0 0-10.6-9.8 9.8 9.8 0 0 0-.9-.6l-.2-.1zm-140.2 43.5c-1 0-1.6.2-1.8.5-.2.4-.3 1 0 2.1.8 2.2 3.1 5.6 7.1 9.6a78.2 78.2 0 0 0 27.4 17.9c9.7 3.8 16.7 4.1 23.4 1.1 5.5-2.5 8.4-6.1 8.4-10.4a4 4 0 0 0-.4-2c-.3-.4-.6-.6-1-.7-.9-.1-2.5.4-4.6 1.8-2.7 2-6.4 2.3-11.3 1.2-5-1.2-11.3-3.8-19.5-8-8-4-17.5-9-21.3-11-2.9-1.4-5-2-6.4-2.1zm160.1 2.8c-.6-.1-1.7.2-3.1 1-1.4 1-3.2 2.3-5.2 4.1a58 58 0 0 1-12.7 8.7c-5.9 2.7-8.6 3.2-18.3 3.2-12.6 0-17.2-1.6-29.9-11.2a21 21 0 0 0-6.4-3.8c-.5 0-.5 0-.7.2-.2.3-.3 1-.3 2 0 2.2 1.5 5.7 3.8 9.2 2.4 3.4 5.7 7 9.2 9.5 8.1 6 14.3 7.8 26.2 7.4a34 34 0 0 0 18.3-4.1 51 51 0 0 0 13.1-9.8c3.8-3.8 6.5-8 7-10.7.4-2 .4-3.5.2-4.5a2 2 0 0 0-.5-1 1 1 0 0 0-.7-.2zm-2 21.4c-.5 0-.6 0-.8.4-.2.4-.3 1.2-.3 2.4 0 3.2 1.7 7.3 4.4 11 2.7 4 6.3 7.4 10 9.5a35 35 0 0 0 21.3 4.8c11-.9 17.8-3.4 23.8-12.6 1.5-2.5 2-4.8 1.4-6.7-.2-.7-.4-1.1-.8-1.4-.3-.2-.6-.3-1.2-.3-1 0-2.6.7-4.7 2.1-6 4.3-12 6.1-19.9 6.2-8.8 0-16.3-3-26.2-11-3.6-2.8-6-4.3-7-4.4zM290 605.5c-.6.3-.9.5-1 1a9 9 0 0 0 .1 3.3c1.8 11 13 25 24.4 30.2 8.5 4 20 4 28.5 0 7.7-3.5 16-11.1 19-17.3a25 25 0 0 0 2.2-6.3c.1-.7.1-1.3 0-1.6 0-.4-.2-.6-.4-.7-.3-.2-1.3-.2-2.8.5-1.6.7-3.6 2-6 4-10 8.2-18.6 12.1-27 11.4-8.6-.7-16.9-6-26.4-15.9a82.6 82.6 0 0 0-7.6-7.1 10 10 0 0 0-2-1.4c-.5-.2-.8-.2-1-.1z"
+            fill="#309fdf"
+          />
+          <path
+            d="M290 125.7a61.4 61.4 0 0 0-19 2.3c-19.9 5.7-33.5 15.8-36.5 52.2-3 36.6-18 45.5-20.3 46.7 14.7 26.7 38 24.5 30.1 59-2.4 11-17.6 23.5-32.8 46.5 34-27 56.4-48 99.6-100.5 0 0 39-47.6 25.1-77a52 52 0 0 0-46.1-29.2z"
+            fill="#e9f2f1"
+          />
+          <path
+            d="M288.5 120.8c-8.1 0-16.7 1.4-25.6 5.3-22.5 9.9-25 20.3-29.1 37a96.8 96.8 0 0 0-1.4 24.6 178 178 0 0 0-16.5-31.6s-19 19.8-36.5 18.6c-22.9-1.7-34 2-44.8 9.8-25.4 18.5-21.2 43.8-21.2 43.8s17.6-1.8 40.5 1c20.3 2.7 37.4 4.3 61.3 2.6 8.5-.6 15.8-10 19.3-19 4.5-4 2.9-22 4.8-24.5 3-3.4 8-4.7 10.6-5.2 3.7-.7 4.3 1.5 4.7 2.8a31 31 0 0 0 60.5-3.2c1-4.4 9-5 15.9-4.5 7 0 .9 15.9-1.7 22.3-5.4 13.2-24.9 39-24.9 39l124.3-85s-45.8 22-61.5 20c-19.7-2.3-25.7-34.8-43.2-44-9.9-5.1-22-9.6-35.5-9.8zm1.4 9.4a48.2 48.2 0 0 1 40.6 23.5c3.7 7.1 6.2 17-.3 20.2-7.6 3.7-14.7.7-15.5-2.8a31 31 0 0 0-30.2-24.1 30 30 0 0 0-30.8 27.4c-.4 5.2-9.1 7.7-12.7 3.7-2.7-3 1.7-16.8 3.7-22 6.2-16.2 27.8-25.7 45.2-26zm5.6 27.8a5.5 5.5 0 1 1 0 11 5.5 5.5 0 0 1 0-11zm-22 29a5.5 5.5 0 1 1 0 11 5.5 5.5 0 0 1 0-11zm40 523.4c-2.6-1.8-15.1 23.5-20 59-6.8 49-8.3 63.2-14.2 96-6 32.7-12.6 66.3-13.4 73.7-.6 4.8-1.7 19-.6 20.1 3.2 3.3 14.7-31.7 16.8-42 2-10.3 7.7-40.7 14.2-86.9 6.4-46.1 8.5-69.6 13.1-91.5 4.7-22 6.7-26.6 4.2-28.4zm66.3-27c-4.1-1.3-10.5 24.6-13.1 37.8-5.6 28.6-6.2 64-8.4 87a1099 1099 0 0 1-12 87.4c-2.7 15-8 29.4-9.8 44.6-1 9-5.2 26-.2 27.3 5.2 1.5 15.4-36.5 20-55.7 8.1-32.9 10.7-65.6 14.2-99.3 3.3-30.7 4.6-62.8 6.5-93.6.7-18.5 5.1-34.5 2.8-35.6z"
+            fill="#0e254f"
+          />
+        </g>
+      </defs>
+      <rect width="1024" height="1024" rx="270" fill="#a7bcd9" />
+      <use href={`#${groupId}`} transform="matrix(-1 0 0 1 1024 0)" />
+      <use href={`#${groupId}`} />
+    </svg>
+  );
+};
+
+export const GitLabIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 32 32" fill="none">
+    <path
+      d="m31.46 12.78-.04-.12-4.35-11.35A1.14 1.14 0 0 0 25.94.6c-.24 0-.47.1-.66.24-.19.15-.33.36-.39.6l-2.94 9h-11.9l-2.94-9A1.14 1.14 0 0 0 6.07.58a1.15 1.15 0 0 0-1.14.72L.58 12.68l-.05.11a8.1 8.1 0 0 0 2.68 9.34l.02.01.04.03 6.63 4.97 3.28 2.48 2 1.52a1.35 1.35 0 0 0 1.62 0l2-1.52 3.28-2.48 6.67-5h.02a8.09 8.09 0 0 0 2.7-9.36Z"
+      fill="#E24329"
+    />
+    <path
+      d="m31.46 12.78-.04-.12a14.75 14.75 0 0 0-5.86 2.64l-9.55 7.24 6.09 4.6 6.67-5h.02a8.09 8.09 0 0 0 2.67-9.36Z"
+      fill="#FC6D26"
+    />
+    <path
+      d="m9.9 27.14 3.28 2.48 2 1.52a1.35 1.35 0 0 0 1.62 0l2-1.52 3.28-2.48-6.1-4.6-6.07 4.6Z"
+      fill="#FCA326"
+    />
+    <path
+      d="M6.44 15.3a14.71 14.71 0 0 0-5.86-2.63l-.05.12a8.1 8.1 0 0 0 2.68 9.34l.02.01.04.03 6.63 4.97 6.1-4.6-9.56-7.24Z"
+      fill="#FC6D26"
+    />
+  </svg>
+);
+
+export const AzureDevOpsIcon: Icon = (props) => {
+  const id = useId().replaceAll(":", "");
+  const gradientA = `${id}-azure-a`;
+  const gradientB = `${id}-azure-b`;
+  const gradientC = `${id}-azure-c`;
+
+  return (
+    <svg {...props} viewBox="0 0 96 96">
+      <defs>
+        <linearGradient
+          id={gradientA}
+          x1="-1032.17"
+          x2="-1059.21"
+          y1="145.31"
+          y2="65.43"
+          gradientTransform="matrix(1 0 0 -1 1075 158)"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#114a8b" />
+          <stop offset="1" stopColor="#0669bc" />
+        </linearGradient>
+        <linearGradient
+          id={gradientB}
+          x1="-1023.73"
+          x2="-1029.98"
+          y1="108.08"
+          y2="105.97"
+          gradientTransform="matrix(1 0 0 -1 1075 158)"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopOpacity=".3" />
+          <stop offset=".07" stopOpacity=".2" />
+          <stop offset=".32" stopOpacity=".1" />
+          <stop offset=".62" stopOpacity=".05" />
+          <stop offset="1" stopOpacity="0" />
+        </linearGradient>
+        <linearGradient
+          id={gradientC}
+          x1="-1027.16"
+          x2="-997.48"
+          y1="147.64"
+          y2="68.56"
+          gradientTransform="matrix(1 0 0 -1 1075 158)"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#3ccbf4" />
+          <stop offset="1" stopColor="#2892df" />
+        </linearGradient>
+      </defs>
+      <path
+        fill={`url(#${gradientA})`}
+        d="M33.34 6.54h26.04l-27.03 80.1a4.15 4.15 0 0 1-3.94 2.81H8.15a4.14 4.14 0 0 1-3.93-5.47L29.4 9.38a4.15 4.15 0 0 1 3.94-2.83z"
+      />
+      <path
+        fill="#0078d4"
+        d="M71.17 60.26H29.88a1.91 1.91 0 0 0-1.3 3.31l26.53 24.76a4.17 4.17 0 0 0 2.85 1.13h23.38z"
+      />
+      <path
+        fill={`url(#${gradientB})`}
+        d="M33.34 6.54a4.12 4.12 0 0 0-3.95 2.88L4.25 83.92a4.14 4.14 0 0 0 3.91 5.54h20.79a4.44 4.44 0 0 0 3.4-2.9l5.02-14.78 17.91 16.7a4.24 4.24 0 0 0 2.67.97h23.29L71.02 60.26H41.24L59.47 6.55z"
+      />
+      <path
+        fill={`url(#${gradientC})`}
+        d="M66.6 9.36a4.14 4.14 0 0 0-3.93-2.82H33.65a4.15 4.15 0 0 1 3.93 2.82l25.18 74.62a4.15 4.15 0 0 1-3.93 5.48h29.02a4.15 4.15 0 0 0 3.93-5.48z"
+      />
+    </svg>
+  );
+};
+
+export const BitbucketIcon: Icon = (props) => {
+  const id = useId().replaceAll(":", "");
+  const gradientId = `${id}-bitbucket-a`;
+
+  return (
+    <svg {...props} viewBox="8.4 14.39 2481.29 2231.21">
+      <path fill="none" d="M989.97,1493.09h518.05l125.04-730.04H852.22L989.97,1493.09z" />
+      <path
+        fill="#2684FF"
+        d="M88.92,14.4C45.02,13.83,8.97,48.96,8.41,92.86c-0.06,4.61,0.28,9.22,1.02,13.77l337.48,2048.72 c8.68,51.75,53.26,89.8,105.74,90.24h1619.03c39.38,0.5,73.19-27.9,79.49-66.78l337.49-2071.78c7.03-43.34-22.41-84.17-65.75-91.2 c-4.55-0.74-9.15-1.08-13.76-1.02L88.92,14.4z M1509.99,1495.09H993.24l-139.92-731h781.89L1509.99,1495.09z"
+      />
+      <linearGradient
+        id={gradientId}
+        gradientUnits="userSpaceOnUse"
+        x1="945.1094"
+        y1="1524.8389"
+        x2="944.4923"
+        y2="1524.1893"
+        gradientTransform="matrix(1996.6343 0 0 -1480.3047 -1884485.625 2258195)"
+      >
+        <stop offset="0.18" stopColor="#0052CC" />
+        <stop offset="1" stopColor="#2684FF" />
+      </linearGradient>
+      <path
+        fill={`url(#${gradientId})`}
+        d="M2379.27,763.06h-745.5l-125.12,730.42H992.31l-609.67,723.67c19.32,16.71,43.96,26,69.5,26.21h1618.13 c39.35,0.51,73.14-27.88,79.44-66.72L2379.27,763.06z"
+      />
+    </svg>
+  );
+};
+
+export const CursorIcon: Icon = ({ className, ...props }) => (
+  <svg
+    {...props}
+    viewBox="0 0 466.73 532.09"
+    className={cn("fill-[#26251E] dark:fill-[#EDECEC]", className)}
+  >
     <path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z" />
   </svg>
 );
@@ -34,6 +213,24 @@ export const TraeIcon: Icon = (props) => (
   </svg>
 );
 
+export const KiroIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 1200 1200" fill="none">
+    <rect width="1200" height="1200" rx="260" fill="#9046FF" />
+    <path
+      d="M398.554 818.914C316.315 1001.03 491.477 1046.74 620.672 940.156C658.687 1059.66 801.052 970.473 852.234 877.795C964.787 673.567 919.318 465.357 907.64 422.374C827.637 129.443 427.623 128.946 358.8 423.865C342.651 475.544 342.402 534.18 333.458 595.051C328.986 625.86 325.507 645.488 313.83 677.785C306.873 696.424 297.68 712.819 282.773 740.645C259.915 783.881 269.604 867.113 387.87 823.883L399.051 818.914H398.554Z"
+      fill="#fff"
+    />
+    <path
+      d="M636.123 549.353C603.328 549.353 598.359 510.097 598.359 486.742C598.359 465.623 602.086 448.977 609.293 438.293C615.504 428.852 624.697 424.131 636.123 424.131C647.555 424.131 657.492 428.852 664.447 438.541C672.398 449.474 676.623 466.12 676.623 486.742C676.623 525.998 661.471 549.353 636.375 549.353H636.123Z"
+      fill="#000"
+    />
+    <path
+      d="M771.24 549.353C738.445 549.353 733.477 510.097 733.477 486.742C733.477 465.623 737.203 448.977 744.41 438.293C750.621 428.852 759.814 424.131 771.24 424.131C782.672 424.131 792.609 428.852 799.564 438.541C807.516 449.474 811.74 466.12 811.74 486.742C811.74 525.998 796.588 549.353 771.492 549.353H771.24Z"
+      fill="#000"
+    />
+  </svg>
+);
+
 export const VisualStudioCode: Icon = (props) => {
   const id = useId();
   const maskId = `${id}-vscode-a`;
@@ -272,18 +469,25 @@ export const Zed: Icon = (props) => {
   );
 };
 
-export const OpenAI: Icon = (props) => (
-  <svg {...props} preserveAspectRatio="xMidYMid" viewBox="0 0 256 260" fill="currentColor">
+export const OpenAI: Icon = ({ className, ...props }) => (
+  <svg
+    {...props}
+    preserveAspectRatio="xMidYMid"
+    viewBox="0 0 256 260"
+    className={cn("fill-black dark:fill-white", className)}
+  >
     <path d="M239.184 106.203a64.716 64.716 0 0 0-5.576-53.103C219.452 28.459 191 15.784 163.213 21.74A65.586 65.586 0 0 0 52.096 45.22a64.716 64.716 0 0 0-43.23 31.36c-14.31 24.602-11.061 55.634 8.033 76.74a64.665 64.665 0 0 0 5.525 53.102c14.174 24.65 42.644 37.324 70.446 31.36a64.72 64.72 0 0 0 48.754 21.744c28.481.025 53.714-18.361 62.414-45.481a64.767 64.767 0 0 0 43.229-31.36c14.137-24.558 10.875-55.423-8.083-76.483Zm-97.56 136.338a48.397 48.397 0 0 1-31.105-11.255l1.535-.87 51.67-29.825a8.595 8.595 0 0 0 4.247-7.367v-72.85l21.845 12.636c.218.111.37.32.409.563v60.367c-.056 26.818-21.783 48.545-48.601 48.601Zm-104.466-44.61a48.345 48.345 0 0 1-5.781-32.589l1.534.921 51.722 29.826a8.339 8.339 0 0 0 8.441 0l63.181-36.425v25.221a.87.87 0 0 1-.358.665l-52.335 30.184c-23.257 13.398-52.97 5.431-66.404-17.803ZM23.549 85.38a48.499 48.499 0 0 1 25.58-21.333v61.39a8.288 8.288 0 0 0 4.195 7.316l62.874 36.272-21.845 12.636a.819.819 0 0 1-.767 0L41.353 151.53c-23.211-13.454-31.171-43.144-17.804-66.405v.256Zm179.466 41.695-63.08-36.63L161.73 77.86a.819.819 0 0 1 .768 0l52.233 30.184a48.6 48.6 0 0 1-7.316 87.635v-61.391a8.544 8.544 0 0 0-4.4-7.213Zm21.742-32.69-1.535-.922-51.619-30.081a8.39 8.39 0 0 0-8.492 0L99.98 99.808V74.587a.716.716 0 0 1 .307-.665l52.233-30.133a48.652 48.652 0 0 1 72.236 50.391v.205ZM88.061 139.097l-21.845-12.585a.87.87 0 0 1-.41-.614V65.685a48.652 48.652 0 0 1 79.757-37.346l-1.535.87-51.67 29.825a8.595 8.595 0 0 0-4.246 7.367l-.051 72.697Zm11.868-25.58 28.138-16.217 28.188 16.218v32.434l-28.086 16.218-28.188-16.218-.052-32.434Z" />
   </svg>
 );
 
-export const ClaudeAI: Icon = (props) => (
-  <svg {...props} preserveAspectRatio="xMidYMid" viewBox="0 0 256 257">
-    <path
-      fill="currentColor"
-      d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"
-    />
+export const ClaudeAI: Icon = ({ className, ...props }) => (
+  <svg
+    {...props}
+    preserveAspectRatio="xMidYMid"
+    viewBox="0 0 256 257"
+    className={cn("fill-[#d97757]", className)}
+  >
+    <path d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z" />
   </svg>
 );
 
@@ -431,112 +635,13 @@ export const AntigravityIcon: Icon = (props) => (
   </svg>
 );
 
-export const IntelliJIdeaIcon: Icon = (props) => {
-  const id = useId();
-  const gradientAId = `${id}-idea-a`;
-  const gradientBId = `${id}-idea-b`;
-  const gradientCId = `${id}-idea-c`;
-  const gradientDId = `${id}-idea-d`;
-
-  return (
-    <svg {...props} viewBox="0 0 70 70" fill="none">
-      <defs>
-        <linearGradient
-          id={gradientAId}
-          x1="0.7898"
-          y1="40.0893"
-          x2="33.3172"
-          y2="40.0893"
-          gradientUnits="userSpaceOnUse"
-        >
-          <stop offset="0.2581" stopColor="#F97A12" />
-          <stop offset="0.4591" stopColor="#B07B58" />
-          <stop offset="0.7241" stopColor="#577BAE" />
-          <stop offset="0.9105" stopColor="#1E7CE5" />
-          <stop offset="1" stopColor="#087CFA" />
-        </linearGradient>
-        <linearGradient
-          id={gradientBId}
-          x1="25.7674"
-          y1="24.88"
-          x2="79.424"
-          y2="54.57"
-          gradientUnits="userSpaceOnUse"
-        >
-          <stop stopColor="#F97A12" />
-          <stop offset="0.07179946" stopColor="#CB7A3E" />
-          <stop offset="0.1541" stopColor="#9E7B6A" />
-          <stop offset="0.242" stopColor="#757B91" />
-          <stop offset="0.3344" stopColor="#537BB1" />
-          <stop offset="0.4324" stopColor="#387CCC" />
-          <stop offset="0.5381" stopColor="#237CE0" />
-          <stop offset="0.6552" stopColor="#147CEF" />
-          <stop offset="0.7925" stopColor="#0B7CF7" />
-          <stop offset="1" stopColor="#087CFA" />
-        </linearGradient>
-        <linearGradient
-          id={gradientCId}
-          x1="63.2277"
-          y1="42.9153"
-          x2="48.2903"
-          y2="-1.7191"
-          gradientUnits="userSpaceOnUse"
-        >
-          <stop stopColor="#FE315D" />
-          <stop offset="0.07840246" stopColor="#CB417E" />
-          <stop offset="0.1601" stopColor="#9E4E9B" />
-          <stop offset="0.2474" stopColor="#755BB4" />
-          <stop offset="0.3392" stopColor="#5365CA" />
-          <stop offset="0.4365" stopColor="#386DDB" />
-          <stop offset="0.5414" stopColor="#2374E9" />
-          <stop offset="0.6576" stopColor="#1478F3" />
-          <stop offset="0.794" stopColor="#0B7BF8" />
-          <stop offset="1" stopColor="#087CFA" />
-        </linearGradient>
-        <linearGradient
-          id={gradientDId}
-          x1="10.7204"
-          y1="16.473"
-          x2="55.5237"
-          y2="90.58"
-          gradientUnits="userSpaceOnUse"
-        >
-          <stop stopColor="#FE315D" />
-          <stop offset="0.04023279" stopColor="#F63462" />
-          <stop offset="0.1037" stopColor="#DF3A71" />
-          <stop offset="0.1667" stopColor="#C24383" />
-          <stop offset="0.2912" stopColor="#AD4A91" />
-          <stop offset="0.5498" stopColor="#755BB4" />
-          <stop offset="0.9175" stopColor="#1D76ED" />
-          <stop offset="1" stopColor="#087CFA" />
-        </linearGradient>
-      </defs>
-      <polygon points="17.7,54.6 0.8,41.2 9.2,25.6 33.3,35" fill={`url(#${gradientAId})`} />
-      <path
-        d="M70 18.7 68.7 59.2 41.8 70 25.6 59.6 49.3 35 38.9 12.3 48.2 1.1Z"
-        fill={`url(#${gradientBId})`}
-      />
-      <polygon points="70,18.7 48.7,43.9 38.9,12.3 48.2,1.1" fill={`url(#${gradientCId})`} />
-      <path
-        d="M33.7 58.1 5.6 68.3 10.1 52.5 16 33.1 0 27.7 10.1 0 32.1 2.7 53.7 27.4Z"
-        fill={`url(#${gradientDId})`}
-      />
-      <rect x="13.7" y="13.5" width="43.2" height="43.2" fill="#000" />
-      <rect x="17.7" y="48.6" width="16.2" height="2.7" fill="#fff" />
-      <path d="M29.4 22.4v-3.3h-9v3.3h2.6v11.3h-2.6V37h9v-3.3h-2.5V22.4h2.5Z" fill="#fff" />
-      <path
-        d="M38 37.3c-1.4 0-2.6-.3-3.5-.8-.9-.5-1.7-1.2-2.3-1.9l2.5-2.8c.5.6 1 1 1.5 1.3.5.3 1.1.5 1.7.5.7 0 1.3-.2 1.8-.7.4-.5.6-1.2.6-2.3V19.1h4v11.7c0 1.1-.1 2-.4 2.8-.3.8-.7 1.4-1.3 2-.5.5-1.2 1-2 1.2-.8.3-1.6.5-2.6.5Z"
-        fill="#fff"
-      />
-    </svg>
-  );
-};
-
 export const OpenCodeIcon: Icon = (props) => (
   <svg {...props} viewBox="0 0 32 40" fill="none" xmlns="http://www.w3.org/2000/svg">
     <g clipPath="url(#opencode__clip0_1311_94969)">
-      <path d="M24 32H8V16H24V32Z" fill="#BCBBBB" />
-      <path d="M24 8H8V32H24V8ZM32 40H0V0H32V40Z" fill="#211E1E" />
+      <path className="dark:hidden" d="M24 32H8V16H24V32Z" fill="#CFCECD" />
+      <path className="dark:hidden" d="M24 8H8V32H24V8ZM32 40H0V0H32V40Z" fill="#211E1E" />
+      <path className="hidden dark:block" d="M24 32H8V16H24V32Z" fill="#4B4646" />
+      <path className="hidden dark:block" d="M24 8H8V32H24V8ZM32 40H0V0H32V40Z" fill="#F1ECEC" />
     </g>
     <defs>
       <clipPath id="opencode__clip0_1311_94969">
@@ -545,3 +650,37 @@ export const OpenCodeIcon: Icon = (props) => (
     </defs>
   </svg>
 );
+
+export const GithubCopilotIcon: Icon = ({ className, ...props }) => (
+  <svg
+    {...props}
+    preserveAspectRatio="xMidYMid"
+    viewBox="0 0 256 208"
+    className={cn("fill-black dark:fill-white", className)}
+  >
+    <path d="M205.3 31.4c14 14.8 20 35.2 22.5 63.6 6.6 0 12.8 1.5 17 7.2l7.8 10.6c2.2 3 3.4 6.6 3.4 10.4v28.7a12 12 0 0 1-4.8 9.5C215.9 187.2 172.3 208 128 208c-49 0-98.2-28.3-123.2-46.6a12 12 0 0 1-4.8-9.5v-28.7c0-3.8 1.2-7.4 3.4-10.5l7.8-10.5c4.2-5.7 10.4-7.2 17-7.2 2.5-28.4 8.4-48.8 22.5-63.6C77.3 3.2 112.6 0 127.6 0h.4c14.7 0 50.4 2.9 77.3 31.4ZM128 78.7c-3 0-6.5.2-10.3.6a27.1 27.1 0 0 1-6 12.1 45 45 0 0 1-32 13c-6.8 0-13.9-1.5-19.7-5.2-5.5 1.9-10.8 4.5-11.2 11-.5 12.2-.6 24.5-.6 36.8 0 6.1 0 12.3-.2 18.5 0 3.6 2.2 6.9 5.5 8.4C79.9 185.9 105 192 128 192s48-6 74.5-18.1a9.4 9.4 0 0 0 5.5-8.4c.3-18.4 0-37-.8-55.3-.4-6.6-5.7-9.1-11.2-11-5.8 3.7-13 5.1-19.7 5.1a45 45 0 0 1-32-12.9 27.1 27.1 0 0 1-6-12.1c-3.4-.4-6.9-.5-10.3-.6Zm-27 44c5.8 0 10.5 4.6 10.5 10.4v19.2a10.4 10.4 0 0 1-20.8 0V133c0-5.8 4.6-10.4 10.4-10.4Zm53.4 0c5.8 0 10.4 4.6 10.4 10.4v19.2a10.4 10.4 0 0 1-20.8 0V133c0-5.8 4.7-10.4 10.4-10.4Zm-73-94.4c-11.2 1.1-20.6 4.8-25.4 10-10.4 11.3-8.2 40.1-2.2 46.2A31.2 31.2 0 0 0 75 91.7c6.8 0 19.6-1.5 30.1-12.2 4.7-4.5 7.5-15.7 7.2-27-.3-9.1-2.9-16.7-6.7-19.9-4.2-3.6-13.6-5.2-24.2-4.3Zm69 4.3c-3.8 3.2-6.4 10.8-6.7 19.9-.3 11.3 2.5 22.5 7.2 27a41.7 41.7 0 0 0 30 12.2c8.9 0 17-2.9 21.3-7.2 6-6.1 8.2-34.9-2.2-46.3-4.8-5-14.2-8.8-25.4-9.9-10.6-1-20 .7-24.2 4.3ZM128 56c-2.6 0-5.6.2-9 .5.4 1.7.5 3.7.7 5.7 0 1.5 0 3-.2 4.5 3.2-.3 6-.3 8.5-.3 2.6 0 5.3 0 8.5.3-.2-1.6-.2-3-.2-4.5.2-2 .3-4 .7-5.7-3.4-.3-6.4-.5-9-.5Z" />
+  </svg>
+);
+
+export const ACPRegistryIcon: Icon = ({ className, ...props }) => (
+  <svg
+    {...props}
+    viewBox="0 0 576 220"
+    fill="none"
+    className={cn("fill-black dark:fill-white", className)}
+  >
+    <path d="M568.003 115.821L517.278 27.9661C507.183 10.4816 489.084 0.0227367 468.894 0.0227367C448.727 0.0227367 430.674 10.4361 420.556 27.8752L343.251 161.749H242.755C236.23 161.749 230.386 158.384 227.135 152.745C223.861 147.106 223.861 140.376 227.135 134.715L277.861 46.8603C281.112 41.2216 286.955 37.8338 293.481 37.8338C300.006 37.8338 305.827 41.1988 309.101 46.8603L312.125 52.0897C313.353 54.2042 315.604 55.5002 318.036 55.5002C320.469 55.5002 322.743 54.1815 323.948 52.067L337.385 28.5118C338.795 26.0335 338.522 22.9413 336.703 20.7586C325.699 7.57131 309.874 0 293.322 0C292.662 0 292.003 0 291.321 0.0454733C272.04 0.75031 254.76 11.1864 245.074 27.9434L200.215 105.657L155.81 29.1484C145.465 11.2092 126.594 0.0227367 106.608 0.0227367C105.949 0.0227367 105.289 0.0227367 104.607 0.06821C85.3265 0.773047 68.0467 11.2092 58.3608 27.9661L7.65806 115.821C-6.25678 139.899 -0.868187 168.82 21.05 187.759C29.8945 195.422 41.6039 199.628 54.0181 199.628H148.648C151.081 199.628 153.332 198.332 154.56 196.217L168.52 172.026C169.748 169.911 169.748 167.319 168.52 165.205C167.292 163.09 165.041 161.794 162.608 161.794H56.0417C49.5163 161.794 43.6729 158.429 40.4216 152.79C37.1475 147.152 37.1475 140.422 40.4216 134.76L91.1471 46.9057C94.3985 41.2671 100.242 37.8793 106.767 37.8793C113.293 37.8793 119.113 41.2443 122.387 46.9057L194.826 172.526C195.031 172.89 195.258 173.208 195.531 173.526C198.76 178.665 202.83 183.485 207.786 187.782C216.631 195.444 228.34 199.651 240.754 199.651H321.424L315.581 209.769C314.353 211.883 314.353 214.475 315.581 216.59C316.809 218.704 319.059 220 321.492 220H349.436C351.868 220 354.119 218.704 355.347 216.59L364.396 200.901L367.17 196.468C367.17 196.468 367.261 196.331 367.284 196.263L453.274 46.9285C456.525 41.2898 462.369 37.902 468.894 37.902C475.42 37.902 481.263 41.2671 484.514 46.9285L535.24 134.783C538.491 140.422 538.514 147.174 535.24 152.813C531.988 158.452 526.145 161.84 519.62 161.84H418.669C416.236 161.84 413.985 163.136 412.757 165.25L398.774 189.442C397.546 191.556 397.546 194.148 398.774 196.263C400.002 198.377 402.253 199.673 404.686 199.673H518.21C539.81 199.673 559.295 188.237 569.026 169.843C578.053 152.79 577.666 132.623 567.981 115.843L568.003 115.821Z" />
+  </svg>
+);
+
+export const PiAgentIcon: Icon = ({ className, ...props }) => (
+  <svg {...props} viewBox="0 0 800 800" className={cn("fill-none", className)}>
+    <rect width="800" height="800" rx="160" fill="#000" />
+    <path
+      fill="#fff"
+      fillRule="evenodd"
+      d="M165.29 165.29H517.36V400H400V517.36H282.65V634.72H165.29ZM282.65 282.65V400H400V282.65Z"
+    />
+    <path fill="#fff" d="M517.36 400H634.72V634.72H517.36Z" />
+  </svg>
+);
diff --git a/apps/web/src/components/JetBrainsIcons.tsx b/apps/web/src/components/JetBrainsIcons.tsx
new file mode 100644
index 00000000000..85efa50bedc
--- /dev/null
+++ b/apps/web/src/components/JetBrainsIcons.tsx
@@ -0,0 +1,610 @@
+import { useId } from "react";
+import type { Icon } from "./Icons";
+
+const useSvgGradientIds = (prefix: string, count: number) => {
+  const id = useId();
+  return Array.from(
+    { length: count },
+    (_, index) => `${id}-${prefix}-${String.fromCharCode(97 + index)}`,
+  );
+};
+
+export const AquaIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("aqua", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="59.932"
+          x2="1.336"
+          y1="59.676"
+          y2="1.079"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".25" stopColor="#7256FF" />
+          <stop offset=".73" stopColor="#007DFE" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="7.671"
+          x2="61.125"
+          y1="64.392"
+          y2="39.609"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".3" stopColor="#00D886" />
+          <stop offset=".54" stopColor="#7256FF" />
+        </linearGradient>
+      </defs>
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M0 4.125v34.128c0 1.658.993 3.154 2.52 3.8L39.943 57.85c.518.219 1.075.33 1.638.324l18.329-.15A4.125 4.125 0 0 0 64 53.9V36.234c0-.806-.236-1.593-.678-2.267L42.213 1.86A4.13 4.13 0 0 0 38.766 0H4.125A4.125 4.125 0 0 0 0 4.125"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M6 49.015v10.862a4.125 4.125 0 0 0 4.125 4.125h12.566q.3 0 .598-.044l37.185-5.448A4.125 4.125 0 0 0 64 54.429V39.03a4.125 4.125 0 0 0-4.127-4.125l-18.504.005c-.426 0-.849.066-1.254.195L8.871 45.085A4.13 4.13 0 0 0 6 49.015z"
+      />
+      <path
+        fill="#00D886"
+        d="M6 47.55v12.259a4.125 4.125 0 0 0 4.19 4.124L21 64c1.181-.019 2.531-.786 3.3-1.683l32.707-38.158c.64-.748.993-1.7.993-2.685V10.125A4.125 4.125 0 0 0 53.875 6H42.872c-1.19 0-2.321.514-3.105 1.409L7.021 44.834A4.12 4.12 0 0 0 6 47.55"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM20.746 31.243a7.3 7.3 0 0 1-2.755-2.787q-1.002-1.774-1.003-3.961c0-2.187.334-2.778 1.003-3.96a7.3 7.3 0 0 1 2.755-2.787q1.752-1.013 3.917-1.014c1.443 0 2.739.338 3.907 1.013a7.3 7.3 0 0 1 2.75 2.787q.996 1.774.996 3.961c0 2.187-.332 2.778-.997 3.96a7.3 7.3 0 0 1-2.749 2.788q-1.752 1.013-3.907 1.013c-1.436 0-2.75-.338-3.917-1.013m6.308-2.23q1.06-.67 1.661-1.854.6-1.185.6-2.664t-.6-2.664a4.6 4.6 0 0 0-1.661-1.854q-1.061-.67-2.39-.67t-2.396.67a4.6 4.6 0 0 0-1.672 1.854q-.605 1.185-.605 2.664t.605 2.664 1.672 1.854q1.067.67 2.396.67 1.33 0 2.39-.67m-2.16 6.034a2.67 2.67 0 0 1-1.126-1.077q-.391-.696-.391-1.64l-.01-1.94h2.743v1.811q0 .332.129.573.128.242.37.365.24.123.574.123h1.833v2.165h-2.412q-.975 0-1.71-.38M38.233 16.992h3.173l5.563 15.006h-2.947l-1.212-3.483h-5.842l-1.136 3.483H32.82zm3.805 9.261-2.025-5.723-.225-.954-.215.954-1.908 5.723z"
+      />
+    </svg>
+  );
+};
+
+export const CLionIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("clion", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="4.067"
+          x2="62.664"
+          y1="4.327"
+          y2="62.923"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".29" stopColor="#009AE5" />
+          <stop offset=".7" stopColor="#00D980" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="56.329"
+          x2="2.874"
+          y1="-.391"
+          y2="24.393"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".3" stopColor="#FF2D90" />
+          <stop offset=".54" stopColor="#009AE5" />
+        </linearGradient>
+      </defs>
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M64 59.878V25.75a4.13 4.13 0 0 0-2.52-3.8L24.057 6.153a4.1 4.1 0 0 0-1.638-.325l-18.329.15A4.124 4.124 0 0 0 0 10.103v17.665c0 .806.236 1.593.678 2.267l21.109 32.109a4.12 4.12 0 0 0 3.447 1.859h34.641A4.125 4.125 0 0 0 64 59.878"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M58 14.988V4.125A4.125 4.125 0 0 0 53.875 0H41.309q-.3 0-.598.044L3.527 5.492A4.125 4.125 0 0 0 0 9.573v15.398a4.125 4.125 0 0 0 4.126 4.125l18.505-.005c.425 0 .848-.066 1.253-.195l31.246-9.98A4.13 4.13 0 0 0 58 14.988"
+      />
+      <path
+        fill="#FF2D90"
+        d="M58 16.453V4.194A4.125 4.125 0 0 0 53.81.07L43.003.008c-1.18.019-2.535.781-3.304 1.678L6.993 39.844c-.64.748-.993 1.7-.993 2.684v11.35a4.125 4.125 0 0 0 4.125 4.125h11.003c1.19 0 2.321-.514 3.105-1.409L56.979 19.17A4.12 4.12 0 0 0 58 16.453"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM20.747 31.243a7.3 7.3 0 0 1-2.744-2.787q-.997-1.774-.997-3.961c0-2.187.332-2.778.997-3.96a7.3 7.3 0 0 1 2.744-2.787q1.747-1.013 3.901-1.014 1.823 0 3.345.675a6.86 6.86 0 0 1 2.535 1.892 6.44 6.44 0 0 1 1.355 2.793h-3.065a4.05 4.05 0 0 0-.895-1.431 4 4 0 0 0-1.431-.95 4.9 4.9 0 0 0-1.822-.332q-1.33 0-2.402.665a4.6 4.6 0 0 0-1.677 1.827q-.606 1.164-.606 2.62 0 1.459.606 2.621a4.6 4.6 0 0 0 1.677 1.828q1.072.664 2.402.664a4.9 4.9 0 0 0 1.822-.332 4.02 4.02 0 0 0 2.326-2.38h3.065a6.44 6.44 0 0 1-1.355 2.792 6.86 6.86 0 0 1-2.535 1.892q-1.522.675-3.345.675-2.154 0-3.901-1.013zM37.33 16.992v12.37h7.117v2.636H34.414V16.992z"
+      />
+    </svg>
+  );
+};
+
+export const DataGripIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("datagrip", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="59.676"
+          x2="1.08"
+          y1="4.067"
+          y2="62.663"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".28" stopColor="#7256FF" />
+          <stop offset=".66" stopColor="#00D980" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="64.391"
+          x2="39.607"
+          y1="56.329"
+          y2="2.874"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".3" stopColor="#FF43F2" />
+          <stop offset=".54" stopColor="#7256FF" />
+        </linearGradient>
+      </defs>
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M4.125 64h34.128a4.13 4.13 0 0 0 3.8-2.52L57.85 24.057c.219-.518.33-1.076.324-1.638l-.15-18.329A4.125 4.125 0 0 0 53.9 0H36.234c-.806 0-1.593.236-2.267.678L1.86 21.787A4.13 4.13 0 0 0 0 25.234v34.641A4.125 4.125 0 0 0 4.125 64"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M49.013 58h10.862A4.125 4.125 0 0 0 64 53.875V41.309q0-.3-.044-.598L58.508 3.527A4.125 4.125 0 0 0 54.427 0H39.029a4.125 4.125 0 0 0-4.125 4.126l.005 18.505c0 .425.066.848.195 1.253l9.979 31.246a4.13 4.13 0 0 0 3.93 2.87"
+      />
+      <path
+        fill="#FF43F2"
+        d="M47.55 58h12.259a4.125 4.125 0 0 0 4.124-4.19L64 43c-.018-1.181-.785-2.531-1.682-3.3L24.159 6.993A4.13 4.13 0 0 0 21.474 6H10.125A4.125 4.125 0 0 0 6 10.125v11.003c0 1.19.514 2.321 1.409 3.105l37.425 32.746A4.12 4.12 0 0 0 47.55 58"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM17.012 16.992h5.713q2.133 0 3.821.965a6.9 6.9 0 0 1 2.642 2.674q.954 1.71.954 3.864t-.954 3.865a6.9 6.9 0 0 1-2.642 2.674q-1.688.964-3.821.964h-5.713zm8.028 11.876q1.008-.6 1.554-1.72.547-1.12.547-2.653 0-1.534-.547-2.653-.546-1.12-1.554-1.721-1.008-.6-2.348-.6h-2.755v9.947h2.755q1.34 0 2.348-.6M35.426 31.243a7.3 7.3 0 0 1-2.744-2.787q-.997-1.774-.997-3.961c0-2.187.333-2.778.997-3.96s1.58-2.112 2.744-2.787q1.747-1.013 3.902-1.014 1.746 0 3.221.622a6.9 6.9 0 0 1 2.487 1.747 6.36 6.36 0 0 1 1.42 2.594h-3.13a3.9 3.9 0 0 0-.927-1.228q-.585-.52-1.367-.803c-.782-.283-1.082-.284-1.683-.284q-1.329 0-2.401.664a4.6 4.6 0 0 0-1.678 1.828q-.605 1.163-.605 2.62c0 1.457.202 1.846.605 2.621a4.6 4.6 0 0 0 1.678 1.828q1.072.664 2.401.664 1.233 0 2.235-.461t1.592-1.276a3.3 3.3 0 0 0 .633-1.833l.01.31h-3.526v-2.304h6.356v1.18q0 1.982-.96 3.585a6.9 6.9 0 0 1-2.625 2.525q-1.668.921-3.736.921c-1.38 0-2.737-.337-3.902-1.013z"
+      />
+    </svg>
+  );
+};
+
+export const DataSpellIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("dataspell", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="4.067"
+          x2="62.664"
+          y1="4.327"
+          y2="62.923"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".28" stopColor="#007DFE" />
+          <stop offset=".73" stopColor="#00D980" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="56.329"
+          x2="2.875"
+          y1="-.391"
+          y2="24.392"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".32" stopColor="#F0EB18" />
+          <stop offset=".55" stopColor="#007DFE" />
+        </linearGradient>
+      </defs>
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M64 59.878V25.75a4.13 4.13 0 0 0-2.52-3.8L24.057 6.153a4.1 4.1 0 0 0-1.638-.325l-18.329.15A4.124 4.124 0 0 0 0 10.103v17.665c0 .806.236 1.593.678 2.267l21.109 32.109a4.12 4.12 0 0 0 3.447 1.859h34.641A4.125 4.125 0 0 0 64 59.878"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M58 14.988V4.125A4.125 4.125 0 0 0 53.875 0H41.309q-.3 0-.598.044L3.527 5.492A4.125 4.125 0 0 0 0 9.573v15.398a4.125 4.125 0 0 0 4.126 4.125l18.505-.005c.425 0 .848-.066 1.253-.195l31.246-9.98A4.13 4.13 0 0 0 58 14.988"
+      />
+      <path
+        fill="#F0EB18"
+        d="M58 16.45V4.191A4.125 4.125 0 0 0 53.81.067L43 0c-1.181.019-2.531.786-3.3 1.683L6.993 39.84c-.64.748-.993 1.7-.993 2.685v11.349A4.125 4.125 0 0 0 10.125 58h11.003c1.19 0 2.321-.514 3.105-1.409l32.746-37.425A4.12 4.12 0 0 0 58 16.45"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM17.012 16.992h5.713q2.133 0 3.821.965a6.9 6.9 0 0 1 2.642 2.674q.954 1.71.954 3.864t-.954 3.865a6.9 6.9 0 0 1-2.642 2.674q-1.688.964-3.821.964h-5.713zm8.028 11.876q1.008-.6 1.554-1.72.547-1.12.547-2.653 0-1.534-.547-2.653-.546-1.12-1.554-1.721-1.008-.6-2.348-.6h-2.755v9.947h2.755q1.34 0 2.348-.6M34.713 31.664q-1.26-.59-1.973-1.65t-.734-2.444h2.937q0 .654.343 1.147t.954.772q.61.278 1.404.278c.53 0 .952-.083 1.334-.251q.574-.252.89-.702t.316-1.029q0-.718-.434-1.19-.435-.471-1.195-.654l-2.648-.59q-1.071-.234-1.865-.809a4 4 0 0 1-1.232-1.42q-.44-.846-.44-1.908 0-1.286.665-2.31.664-1.023 1.854-1.597 1.19-.573 2.701-.573c1.511 0 1.933.186 2.733.558s1.424.888 1.871 1.549q.67.99.68 2.277h-2.926q0-.546-.289-.98c-.289-.435-.466-.515-.82-.676a2.9 2.9 0 0 0-1.217-.24q-.686 0-1.205.23a1.9 1.9 0 0 0-.81.643q-.29.412-.29.96 0 .621.403 1.028.402.407 1.098.579l2.552.557q1.103.226 1.967.852a4.45 4.45 0 0 1 1.345 1.544q.481.917.482 1.999 0 1.329-.702 2.385-.702 1.054-1.967 1.656-1.265.6-2.894.6t-2.889-.59"
+      />
+    </svg>
+  );
+};
+
+export const GoLandIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("goland", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="64.391"
+          x2="39.607"
+          y1="56.329"
+          y2="2.874"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".24" stopColor="#00D886" />
+          <stop offset=".51" stopColor="#007DFE" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="59.676"
+          x2="1.08"
+          y1="4.067"
+          y2="62.663"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".27" stopColor="#007DFE" />
+          <stop offset=".7" stopColor="#D249FC" />
+        </linearGradient>
+      </defs>
+      <path
+        fill="#00D886"
+        d="M47.55 58h12.259a4.125 4.125 0 0 0 4.124-4.19l-.176-11.044a4.13 4.13 0 0 0-1.44-3.066L24.159 6.993A4.13 4.13 0 0 0 21.474 6H10.125A4.125 4.125 0 0 0 6 10.125v11.003c0 1.19.514 2.321 1.409 3.105l37.425 32.746A4.12 4.12 0 0 0 47.55 58"
+      />
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M49.013 58h10.862A4.125 4.125 0 0 0 64 53.875V41.309q0-.3-.044-.598L58.508 3.527A4.124 4.124 0 0 0 54.427 0H39.029a4.125 4.125 0 0 0-4.125 4.126l.005 18.505c0 .425.066.848.195 1.253l9.979 31.246a4.13 4.13 0 0 0 3.93 2.87"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M4.125 64h34.128a4.13 4.13 0 0 0 3.8-2.52L57.85 24.057c.219-.518.33-1.076.324-1.638l-.15-18.329A4.124 4.124 0 0 0 53.9 0H36.234c-.805 0-1.593.236-2.266.678L1.86 21.787A4.13 4.13 0 0 0 0 25.234v34.641A4.125 4.125 0 0 0 4.125 64"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M19.748 31.243a7.3 7.3 0 0 1-2.743-2.787q-.997-1.774-.997-3.961c0-2.187.332-2.778.997-3.96s1.58-2.112 2.743-2.787q1.747-1.013 3.902-1.014 1.747 0 3.222.622a6.9 6.9 0 0 1 2.486 1.747 6.4 6.4 0 0 1 1.42 2.594h-3.13a3.9 3.9 0 0 0-.926-1.228q-.584-.52-1.367-.803c-.783-.283-1.083-.284-1.683-.284q-1.33 0-2.402.664a4.6 4.6 0 0 0-1.677 1.828q-.606 1.163-.606 2.62c0 1.457.202 1.846.606 2.621a4.6 4.6 0 0 0 1.677 1.828q1.072.664 2.402.664 1.232 0 2.235-.461t1.591-1.276a3.3 3.3 0 0 0 .633-1.833l.01.31h-3.526v-2.304h6.357v1.18q0 1.982-.96 3.585a6.9 6.9 0 0 1-2.626 2.525q-1.666.921-3.736.921c-2.07 0-2.737-.337-3.902-1.013zM36.271 31.243a7.3 7.3 0 0 1-2.755-2.787q-1.002-1.774-1.002-3.961c0-2.187.333-2.778 1.002-3.96a7.3 7.3 0 0 1 2.755-2.787q1.752-1.013 3.918-1.014c1.443 0 2.738.338 3.907 1.013a7.3 7.3 0 0 1 2.749 2.787q.996 1.774.997 3.961c0 2.187-.333 2.778-.997 3.96s-1.581 2.113-2.75 2.788q-1.752 1.013-3.906 1.013c-1.437 0-2.75-.338-3.918-1.013m6.308-2.23q1.062-.67 1.662-1.854t.6-2.664-.6-2.664-1.662-1.854-2.39-.67-2.395.67a4.6 4.6 0 0 0-1.672 1.854q-.606 1.185-.606 2.664t.606 2.664 1.672 1.854 2.395.67q1.33 0 2.39-.67M33 44H17v3h16z"
+      />
+    </svg>
+  );
+};
+
+export const IntelliJIdeaIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("intellij-idea", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="-.391"
+          x2="24.392"
+          y1="7.671"
+          y2="61.126"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".1" stopColor="#FC801D" />
+          <stop offset=".59" stopColor="#FE2857" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="4.325"
+          x2="62.921"
+          y1="59.932"
+          y2="1.336"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".21" stopColor="#FE2857" />
+          <stop offset=".7" stopColor="#007EFF" />
+        </linearGradient>
+      </defs>
+      <path
+        fill="#FF8100"
+        d="M16.45 6H4.191a4.125 4.125 0 0 0-4.124 4.19l.176 11.044a4.13 4.13 0 0 0 1.44 3.066l38.159 32.707c.747.64 1.7.993 2.684.993h11.35A4.125 4.125 0 0 0 58 53.875V42.872c0-1.19-.514-2.321-1.41-3.105L19.167 7.021A4.12 4.12 0 0 0 16.45 6"
+      />
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M14.988 6H4.125A4.125 4.125 0 0 0 0 10.125v12.566q0 .3.044.598l5.448 37.185A4.125 4.125 0 0 0 9.573 64h15.398a4.125 4.125 0 0 0 4.125-4.127L29.09 41.37c0-.426-.066-.849-.195-1.254l-9.98-31.245A4.13 4.13 0 0 0 14.988 6z"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M59.876 0H25.748a4.13 4.13 0 0 0-3.8 2.52L6.151 39.943a4.1 4.1 0 0 0-.325 1.638l.15 18.329A4.125 4.125 0 0 0 10.101 64h17.666c.806 0 1.593-.236 2.266-.678l32.11-21.109A4.12 4.12 0 0 0 64 38.766V4.125A4.125 4.125 0 0 0 59.876 0"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM17 29.383h2.98v-9.775H17v-2.616h8.843v2.616h-2.98v9.775h2.98V32H17zM27.643 29.298h2.154a2.4 2.4 0 0 0 1.163-.279q.51-.279.788-.788.279-.51.279-1.163V16.992h2.926v10.28q0 1.35-.622 2.427a4.45 4.45 0 0 1-1.715 1.688q-1.092.612-2.454.611h-2.519z"
+      />
+    </svg>
+  );
+};
+
+export const PhpStormIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("phpstorm", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="56.329"
+          x2="2.874"
+          y1="-.391"
+          y2="24.392"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".16" stopColor="#D249FC" />
+          <stop offset=".55" stopColor="#FF2D90" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="4.067"
+          x2="62.664"
+          y1="4.326"
+          y2="62.923"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".3" stopColor="#FF2D90" />
+          <stop offset=".7" stopColor="#7256FF" />
+        </linearGradient>
+      </defs>
+      <path
+        fill="#D249FC"
+        d="M58 16.446V4.187A4.125 4.125 0 0 0 53.81.063L42.765.239A4.13 4.13 0 0 0 39.7 1.68L6.993 39.837c-.64.748-.993 1.7-.993 2.685v11.35a4.125 4.125 0 0 0 4.125 4.124h11.003c1.19 0 2.321-.514 3.105-1.409l32.746-37.425A4.12 4.12 0 0 0 58 16.446"
+      />
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M58 14.988V4.125A4.125 4.125 0 0 0 53.875 0H41.309q-.3 0-.598.044L3.527 5.492A4.125 4.125 0 0 0 0 9.573v15.398a4.125 4.125 0 0 0 4.126 4.125l18.505-.005c.425 0 .848-.066 1.253-.195l31.246-9.98A4.13 4.13 0 0 0 58 14.988"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M64 59.878V25.75a4.13 4.13 0 0 0-2.52-3.8L24.057 6.153a4.1 4.1 0 0 0-1.638-.325l-18.329.15A4.124 4.124 0 0 0 0 10.103v17.665c0 .806.236 1.593.678 2.267l21.109 32.109a4.12 4.12 0 0 0 3.447 1.859h34.641A4.125 4.125 0 0 0 64 59.878"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM16.993 16.992h6.442q1.586 0 2.78.579 1.196.579 1.845 1.63.648 1.05.648 2.432c0 .922-.22 1.759-.659 2.466q-.66 1.062-1.87 1.646-1.212.584-2.83.584h-3.43V32h-2.927zm7.54 6.63q.553-.273.852-.782.3-.51.3-1.195c0-.685-.1-.842-.3-1.174q-.3-.5-.852-.772-.552-.273-1.291-.273h-3.323v4.47h3.323q.74 0 1.291-.273M32.572 31.664q-1.26-.59-1.972-1.65t-.735-2.444h2.937q0 .654.343 1.147t.954.772q.611.278 1.404.278c.53 0 .952-.083 1.335-.251q.572-.252.89-.702c.317-.45.315-.643.315-1.029q0-.718-.434-1.19-.435-.471-1.195-.654l-2.647-.59q-1.073-.234-1.866-.809a4 4 0 0 1-1.232-1.42q-.44-.846-.44-1.908 0-1.286.665-2.31.665-1.023 1.854-1.597 1.19-.573 2.702-.573c1.512 0 1.933.186 2.733.558q1.2.558 1.87 1.549t.681 2.277h-2.926q0-.546-.29-.98a1.9 1.9 0 0 0-.82-.676 2.9 2.9 0 0 0-1.216-.24q-.687 0-1.206.23a1.9 1.9 0 0 0-.81.643q-.29.412-.289.96 0 .621.402 1.028t1.099.579l2.551.557q1.104.226 1.967.852a4.45 4.45 0 0 1 1.345 1.544q.482.917.482 1.999 0 1.329-.701 2.385-.703 1.054-1.967 1.656-1.264.6-2.895.6-1.63 0-2.888-.59"
+      />
+    </svg>
+  );
+};
+
+export const PyCharmIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("pycharm", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="7.671"
+          x2="61.126"
+          y1="64.393"
+          y2="39.609"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".1" stopColor="#00D886" />
+          <stop offset=".59" stopColor="#F0EB18" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="59.933"
+          x2="1.337"
+          y1="59.676"
+          y2="1.08"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".3" stopColor="#F0EB18" />
+          <stop offset=".7" stopColor="#00C4F4" />
+        </linearGradient>
+      </defs>
+      <path
+        fill="#00D886"
+        d="M6 47.55v12.259a4.125 4.125 0 0 0 4.19 4.124l11.044-.176a4.13 4.13 0 0 0 3.066-1.44l32.707-38.158c.64-.748.993-1.7.993-2.685V10.125A4.125 4.125 0 0 0 53.875 6H42.872c-1.19 0-2.321.514-3.105 1.409L7.021 44.834A4.12 4.12 0 0 0 6 47.55"
+      />
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M6 49.015v10.862a4.125 4.125 0 0 0 4.125 4.125h12.566q.3 0 .598-.044l37.185-5.448A4.125 4.125 0 0 0 64 54.429V39.03a4.125 4.125 0 0 0-4.127-4.125l-18.504.005c-.426 0-.849.066-1.254.195L8.871 45.085A4.13 4.13 0 0 0 6 49.015z"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M0 4.125v34.128c0 1.658.993 3.154 2.52 3.8L39.943 57.85c.518.219 1.075.33 1.638.324l18.329-.15A4.125 4.125 0 0 0 64 53.9V36.234c0-.806-.236-1.593-.678-2.267L42.213 1.86A4.13 4.13 0 0 0 38.766 0H4.125A4.125 4.125 0 0 0 0 4.125"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM16.993 16.992h6.442q1.586 0 2.78.579 1.196.579 1.845 1.63.648 1.05.648 2.432c0 .922-.22 1.759-.659 2.466q-.66 1.062-1.87 1.646-1.212.584-2.83.584h-3.43V32h-2.927zm7.54 6.63q.553-.273.852-.782.3-.51.3-1.195c0-.685-.1-.842-.3-1.174q-.3-.5-.852-.772-.552-.273-1.291-.273h-3.324v4.47h3.324q.74 0 1.291-.273M33.713 31.243a7.3 7.3 0 0 1-2.744-2.787q-.996-1.774-.996-3.961c0-2.187.332-2.778.996-3.96a7.3 7.3 0 0 1 2.744-2.787q1.748-1.013 3.902-1.014 1.823 0 3.344.675a6.86 6.86 0 0 1 2.535 1.892 6.44 6.44 0 0 1 1.356 2.793h-3.066a4.05 4.05 0 0 0-.895-1.431 4 4 0 0 0-1.43-.95 4.9 4.9 0 0 0-1.823-.332q-1.33 0-2.402.665a4.6 4.6 0 0 0-1.677 1.827q-.606 1.164-.606 2.62 0 1.459.606 2.621a4.6 4.6 0 0 0 1.677 1.828q1.072.664 2.402.664.986 0 1.822-.332a4.02 4.02 0 0 0 2.326-2.38h3.066a6.44 6.44 0 0 1-1.356 2.792 6.86 6.86 0 0 1-2.535 1.892q-1.522.675-3.344.675-2.154 0-3.902-1.013z"
+      />
+    </svg>
+  );
+};
+
+export const RiderIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("rider", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="64.391"
+          x2="39.607"
+          y1="56.329"
+          y2="2.874"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".21" stopColor="#007DFE" />
+          <stop offset=".55" stopColor="#FFB700" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="59.676"
+          x2="1.08"
+          y1="4.067"
+          y2="62.663"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".23" stopColor="#FFB700" />
+          <stop offset=".73" stopColor="#FF0A67" />
+        </linearGradient>
+      </defs>
+      <path
+        fill="#007DFE"
+        d="M47.55 58h12.258a4.125 4.125 0 0 0 4.124-4.19l-.176-11.044a4.12 4.12 0 0 0-1.44-3.066L24.158 6.993A4.13 4.13 0 0 0 21.474 6H10.125A4.125 4.125 0 0 0 6 10.125v11.003c0 1.19.514 2.321 1.409 3.105l37.425 32.746A4.12 4.12 0 0 0 47.55 58"
+      />
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M49.013 58h10.862A4.125 4.125 0 0 0 64 53.875V41.309q0-.3-.044-.598L58.508 3.527A4.125 4.125 0 0 0 54.427 0H39.029a4.125 4.125 0 0 0-4.125 4.126l.005 18.505c0 .425.066.848.195 1.253l9.979 31.246a4.13 4.13 0 0 0 3.93 2.87"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M4.125 64h34.128a4.13 4.13 0 0 0 3.8-2.52L57.85 24.057c.219-.518.33-1.076.324-1.638l-.15-18.329A4.124 4.124 0 0 0 53.9 0H36.234c-.805 0-1.593.236-2.266.678L1.86 21.787A4.13 4.13 0 0 0 0 25.234v34.641A4.125 4.125 0 0 0 4.125 64"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM16.992 16.992h6.442q1.576 0 2.776.579t1.85 1.63.648 2.432c0 .922-.22 1.75-.66 2.46q-.66 1.068-1.875 1.651-1.217.584-2.825.584h-3.43v5.67h-2.926zm7.54 6.63q.553-.274.853-.783.3-.51.3-1.184c0-.45-.1-.852-.3-1.185q-.3-.498-.852-.772-.552-.273-1.292-.273h-3.323v4.47h3.323q.74 0 1.292-.273m-2.63 1.763h3.194L29.03 32h-3.355zM31.613 16.992h5.713q2.133 0 3.822.965a6.9 6.9 0 0 1 2.641 2.674q.954 1.71.954 3.864t-.953 3.865a6.9 6.9 0 0 1-2.642 2.674q-1.688.964-3.822.964h-5.713zm8.028 11.876q1.008-.6 1.555-1.72t.547-2.653q0-1.534-.547-2.653-.547-1.12-1.555-1.721-1.008-.6-2.347-.6h-2.755v9.947h2.755q1.34 0 2.347-.6"
+      />
+    </svg>
+  );
+};
+
+export const RubyMineIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("rubymine", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="4.325"
+          x2="62.921"
+          y1="59.932"
+          y2="1.337"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".29" stopColor="#FF2358" />
+          <stop offset=".75" stopColor="#7256FF" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="-.391"
+          x2="24.393"
+          y1="7.671"
+          y2="61.125"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".29" stopColor="#FF8100" />
+          <stop offset=".56" stopColor="#FF2358" />
+        </linearGradient>
+      </defs>
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M59.875 0H25.748a4.13 4.13 0 0 0-3.8 2.52L6.151 39.942a4.1 4.1 0 0 0-.325 1.639l.15 18.328A4.125 4.125 0 0 0 10.101 64h17.666c.805 0 1.593-.235 2.266-.678l32.109-21.108A4.12 4.12 0 0 0 64 38.766V4.125A4.125 4.125 0 0 0 59.875 0"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M14.987 6H4.126A4.125 4.125 0 0 0 0 10.125v12.566q0 .3.044.598l5.448 37.184A4.125 4.125 0 0 0 9.572 64H24.97a4.125 4.125 0 0 0 4.125-4.126l-.004-18.504c0-.426-.067-.85-.196-1.254L18.917 8.87A4.13 4.13 0 0 0 14.987 6z"
+      />
+      <path
+        fill="#FF8100"
+        d="M16.45 6H4.19a4.125 4.125 0 0 0-4.124 4.19L0 21c.019 1.181.786 2.531 1.683 3.3l38.158 32.706c.748.641 1.7.993 2.684.993h11.35A4.125 4.125 0 0 0 58 53.875V42.872c0-1.189-.514-2.32-1.41-3.104L19.167 7.021A4.12 4.12 0 0 0 16.45 6"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM17.012 16.992h6.442q1.575 0 2.776.579t1.849 1.63.648 2.432c0 .922-.22 1.75-.66 2.46q-.658 1.068-1.875 1.651-1.216.584-2.824.584h-3.43v5.67h-2.926zm7.54 6.63q.552-.274.852-.783.3-.51.3-1.184c0-.45-.1-.852-.3-1.185q-.3-.498-.852-.772-.552-.273-1.292-.273h-3.323v4.47h3.323q.74 0 1.292-.273m-2.631 1.763h3.194L29.05 32h-3.355zM31.633 16.992h4.073l3.087 9.85.257 1.287.225-1.286 2.98-9.85h4.138v15.005h-2.894V21.29l.043-.782-3.494 11.49h-2.123l-3.451-11.415.043.707v10.708h-2.883V16.992z"
+      />
+    </svg>
+  );
+};
+
+export const RustRoverIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("rustrover", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="7.671"
+          x2="61.125"
+          y1="64.393"
+          y2="39.609"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".08" stopColor="#00D886" />
+          <stop offset=".46" stopColor="#FFAB00" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="59.932"
+          x2="1.336"
+          y1="59.676"
+          y2="1.08"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".19" stopColor="#FFAB00" />
+          <stop offset=".83" stopColor="#FF004C" />
+        </linearGradient>
+      </defs>
+      <path
+        fill="#00D886"
+        d="M6 47.55v12.258a4.125 4.125 0 0 0 4.19 4.124l11.044-.176a4.12 4.12 0 0 0 3.066-1.44l32.707-38.158c.64-.747.993-1.7.993-2.684V10.125A4.125 4.125 0 0 0 53.875 6H42.872c-1.19 0-2.321.514-3.105 1.409L7.021 44.833A4.12 4.12 0 0 0 6 47.55"
+      />
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M6 49.015v10.862a4.125 4.125 0 0 0 4.125 4.125h12.566q.3 0 .598-.044l37.185-5.448A4.125 4.125 0 0 0 64 54.429V39.03a4.125 4.125 0 0 0-4.127-4.125l-18.504.005c-.426 0-.849.066-1.254.195L8.871 45.085A4.13 4.13 0 0 0 6 49.015z"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M0 4.125v34.128c0 1.658.993 3.154 2.52 3.8L39.943 57.85c.518.219 1.075.33 1.638.324l18.329-.15A4.125 4.125 0 0 0 64 53.9V36.234c0-.806-.236-1.593-.678-2.267L42.213 1.86A4.13 4.13 0 0 0 38.766 0H4.125A4.125 4.125 0 0 0 0 4.125"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM16.992 16.992h6.442q1.576 0 2.776.579t1.85 1.63.648 2.432c0 .922-.22 1.75-.66 2.46q-.66 1.068-1.875 1.651-1.217.584-2.825.584h-3.43v5.67h-2.926zm7.54 6.63q.553-.274.853-.783.3-.51.3-1.184c0-.45-.1-.852-.3-1.185q-.3-.498-.852-.772-.552-.273-1.292-.273h-3.323v4.47h3.323q.74 0 1.292-.273m-2.63 1.763h3.194L29.03 32h-3.355zM31.613 16.992h6.442q1.575 0 2.776.579t1.85 1.63.648 2.432c0 .922-.22 1.75-.66 2.46q-.659 1.068-1.875 1.651-1.217.584-2.824.584h-3.43v5.67h-2.927zm7.54 6.63q.553-.274.853-.783.3-.51.3-1.184c0-.45-.1-.852-.3-1.185q-.3-.498-.852-.772-.552-.273-1.292-.273h-3.323v4.47h3.323q.74 0 1.292-.273m-2.63 1.763h3.194L43.651 32h-3.355z"
+      />
+    </svg>
+  );
+};
+
+export const WebStormIcon: Icon = (props) => {
+  const [gradientAId, gradientBId] = useSvgGradientIds("webstorm", 2);
+
+  return (
+    <svg {...props} viewBox="0 0 64 64" fill="none">
+      <defs>
+        <linearGradient
+          id={gradientAId}
+          x1="7.671"
+          x2="61.126"
+          y1="64.392"
+          y2="39.609"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".22" stopColor="#F0EB18" />
+          <stop offset=".59" stopColor="#00C4F4" />
+        </linearGradient>
+        <linearGradient
+          id={gradientBId}
+          x1="59.932"
+          x2="1.337"
+          y1="59.676"
+          y2="1.079"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset=".19" stopColor="#00C4F4" />
+          <stop offset=".83" stopColor="#007DFE" />
+        </linearGradient>
+      </defs>
+      <path
+        fill="#F0EB18"
+        d="M6 47.55v12.258a4.125 4.125 0 0 0 4.19 4.124l11.044-.176a4.12 4.12 0 0 0 3.066-1.44l32.707-38.158c.64-.747.993-1.7.993-2.684V10.125A4.125 4.125 0 0 0 53.875 6H42.872c-1.19 0-2.321.514-3.105 1.409L7.021 44.833A4.12 4.12 0 0 0 6 47.55"
+      />
+      <path
+        fill={`url(#${gradientAId})`}
+        d="M6 49.015v10.862a4.125 4.125 0 0 0 4.125 4.125h12.566q.3 0 .598-.044l37.185-5.448A4.125 4.125 0 0 0 64 54.429V39.03a4.125 4.125 0 0 0-4.127-4.125l-18.504.005c-.426 0-.849.066-1.254.195L8.871 45.085A4.13 4.13 0 0 0 6 49.015z"
+      />
+      <path
+        fill={`url(#${gradientBId})`}
+        d="M0 4.125v34.128c0 1.658.993 3.154 2.52 3.8L39.943 57.85c.518.219 1.075.33 1.638.324l18.329-.15A4.125 4.125 0 0 0 64 53.9V36.234c0-.806-.236-1.593-.678-2.267L42.213 1.86A4.13 4.13 0 0 0 38.766 0H4.125A4.125 4.125 0 0 0 0 4.125"
+      />
+      <path fill="#000" d="M52 12H12v40h40z" />
+      <path
+        fill="#fff"
+        d="M33 44H17v3h16zM19.051 16.992l2.423 10.955 2.583-10.955h2.958l2.701 10.955 2.348-10.955h2.97l-3.645 15.006h-3.334l-2.53-10.9-2.561 10.9H19.64l-3.623-15.006zM38.662 31.664q-1.26-.59-1.972-1.65t-.735-2.444h2.937q0 .654.343 1.147t.954.772q.61.278 1.404.278c.53 0 .952-.083 1.335-.251q.573-.252.889-.702t.316-1.029q0-.718-.434-1.19-.435-.471-1.195-.654l-2.648-.59q-1.071-.234-1.865-.809a4 4 0 0 1-1.232-1.42q-.44-.846-.44-1.908 0-1.286.665-2.31.664-1.023 1.854-1.597 1.19-.573 2.701-.573c1.008 0 1.934.186 2.734.558q1.2.558 1.87 1.549t.68 2.277h-2.925q0-.546-.29-.98c-.29-.435-.466-.515-.82-.676a2.9 2.9 0 0 0-1.217-.24q-.686 0-1.205.23a1.9 1.9 0 0 0-.81.643q-.29.412-.289.96 0 .621.402 1.028t1.099.579l2.55.557q1.105.226 1.968.852a4.45 4.45 0 0 1 1.345 1.544 4.2 4.2 0 0 1 .482 1.999q0 1.329-.702 2.385-.702 1.054-1.966 1.656-1.266.6-2.894.6-1.63 0-2.889-.59"
+      />
+    </svg>
+  );
+};
diff --git a/apps/web/src/components/KeybindingsToast.browser.tsx b/apps/web/src/components/KeybindingsToast.browser.tsx
index 223f5d8ebdc..611eaf572d0 100644
--- a/apps/web/src/components/KeybindingsToast.browser.tsx
+++ b/apps/web/src/components/KeybindingsToast.browser.tsx
@@ -7,14 +7,19 @@ import {
   type MessageId,
   type OrchestrationReadModel,
   type ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerConfig,
   type ServerLifecycleWelcomePayload,
+  ServerConfig as ServerConfigSchema,
+  ServerSettings,
   type ThreadId,
   WS_METHODS,
 } from "@t3tools/contracts";
 import { RouterProvider, createMemoryHistory } from "@tanstack/react-router";
 import { ws, http, HttpResponse } from "msw";
 import { setupWorker } from "msw/browser";
+import * as Schema from "effect/Schema";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { render } from "vitest-browser-react";
 
@@ -48,6 +53,8 @@ interface TestFixture {
 
 let fixture: TestFixture;
 const rpcHarness = new BrowserWsRpcHarness();
+const encodeServerConfig = Schema.encodeSync(ServerConfigSchema);
+const encodeServerSettings = Schema.encodeSync(ServerSettings);
 
 const wsLink = ws.link(/ws(s)?:\/\/.*/);
 
@@ -72,7 +79,8 @@ function createBaseServerConfig(): ServerConfig {
     issues: [],
     providers: [
       {
-        provider: "codex",
+        driver: ProviderDriverKind.make("codex"),
+        instanceId: ProviderInstanceId.make("codex"),
         enabled: true,
         installed: true,
         version: "0.116.0",
@@ -95,10 +103,33 @@ function createBaseServerConfig(): ServerConfig {
       ...DEFAULT_SERVER_SETTINGS,
       enableAssistantStreaming: false,
       defaultThreadEnvMode: "local" as const,
-      textGenerationModelSelection: { provider: "codex" as const, model: "gpt-5.4-mini" },
+      textGenerationModelSelection: {
+        instanceId: ProviderInstanceId.make("codex"),
+        model: "gpt-5.4-mini",
+      },
       providers: {
-        codex: { enabled: true, binaryPath: "", homePath: "", customModels: [] },
-        claudeAgent: { enabled: true, binaryPath: "", customModels: [] },
+        codex: {
+          enabled: true,
+          binaryPath: "",
+          homePath: "",
+          shadowHomePath: "",
+          customModels: [],
+        },
+        claudeAgent: {
+          enabled: true,
+          binaryPath: "",
+          homePath: "",
+          customModels: [],
+          launchArgs: "",
+        },
+        cursor: { enabled: true, binaryPath: "", apiEndpoint: "", customModels: [] },
+        opencode: {
+          enabled: true,
+          binaryPath: "",
+          serverUrl: "",
+          serverPassword: "",
+          customModels: [],
+        },
       },
     },
   };
@@ -113,7 +144,7 @@ function createMinimalSnapshot(): OrchestrationReadModel {
         title: "Project",
         workspaceRoot: "/repo/project",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         scripts: [],
@@ -128,7 +159,7 @@ function createMinimalSnapshot(): OrchestrationReadModel {
         projectId: PROJECT_ID,
         title: "Test thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         interactionMode: "default",
@@ -169,6 +200,43 @@ function createMinimalSnapshot(): OrchestrationReadModel {
   };
 }
 
+function toShellSnapshot(snapshot: OrchestrationReadModel) {
+  return {
+    snapshotSequence: snapshot.snapshotSequence,
+    projects: snapshot.projects.map((project) => ({
+      id: project.id,
+      title: project.title,
+      workspaceRoot: project.workspaceRoot,
+      repositoryIdentity: project.repositoryIdentity ?? null,
+      defaultModelSelection: project.defaultModelSelection,
+      scripts: project.scripts,
+      createdAt: project.createdAt,
+      updatedAt: project.updatedAt,
+    })),
+    threads: snapshot.threads.map((thread) => ({
+      id: thread.id,
+      projectId: thread.projectId,
+      title: thread.title,
+      modelSelection: thread.modelSelection,
+      runtimeMode: thread.runtimeMode,
+      interactionMode: thread.interactionMode,
+      branch: thread.branch,
+      worktreePath: thread.worktreePath,
+      latestTurn: thread.latestTurn,
+      createdAt: thread.createdAt,
+      updatedAt: thread.updatedAt,
+      archivedAt: thread.archivedAt,
+      session: thread.session,
+      latestUserMessageAt:
+        thread.messages.findLast((message) => message.role === "user")?.createdAt ?? null,
+      hasPendingApprovals: false,
+      hasPendingUserInput: false,
+      hasActionableProposedPlan: false,
+    })),
+    updatedAt: snapshot.updatedAt,
+  };
+}
+
 function buildFixture(): TestFixture {
   return {
     snapshot: createMinimalSnapshot(),
@@ -190,19 +258,16 @@ function buildFixture(): TestFixture {
 }
 
 function resolveWsRpc(tag: string): unknown {
-  if (tag === ORCHESTRATION_WS_METHODS.getSnapshot) {
-    return fixture.snapshot;
-  }
   if (tag === WS_METHODS.serverGetConfig) {
-    return fixture.serverConfig;
+    return encodeServerConfig(fixture.serverConfig);
   }
-  if (tag === WS_METHODS.gitListBranches) {
+  if (tag === WS_METHODS.vcsListRefs) {
     return {
       isRepo: true,
-      hasOriginRemote: true,
+      hasPrimaryRemote: true,
       nextCursor: null,
       totalCount: 1,
-      branches: [{ name: "main", current: true, isDefault: true, worktreePath: null }],
+      refs: [{ name: "main", current: true, isDefault: true, worktreePath: null }],
     };
   }
   if (tag === WS_METHODS.projectsSearchEntries) {
@@ -229,7 +294,7 @@ function sendServerConfigUpdatedPush(issues: ServerConfig["issues"]) {
   rpcHarness.emitStreamValue(WS_METHODS.subscribeServerConfig, {
     version: 1,
     type: "keybindingsUpdated",
-    payload: { issues },
+    payload: { keybindings: fixture.serverConfig.keybindings, issues },
   });
 }
 
@@ -334,7 +399,7 @@ async function waitForServerConfigStreamReady(): Promise<void> {
     rpcHarness.emitStreamValue(WS_METHODS.subscribeServerConfig, {
       version: 1,
       type: "settingsUpdated",
-      payload: { settings: fixture.serverConfig.settings },
+      payload: { settings: encodeServerSettings(fixture.serverConfig.settings) },
     });
 
     try {
@@ -425,7 +490,29 @@ describe("Keybindings update toast", () => {
             {
               version: 1,
               type: "snapshot",
-              config: fixture.serverConfig,
+              config: encodeServerConfig(fixture.serverConfig),
+            },
+          ];
+        }
+        if (request._tag === ORCHESTRATION_WS_METHODS.subscribeShell) {
+          return [
+            {
+              kind: "snapshot",
+              snapshot: toShellSnapshot(fixture.snapshot),
+            },
+          ];
+        }
+        if (
+          request._tag === ORCHESTRATION_WS_METHODS.subscribeThread &&
+          request.threadId === THREAD_ID
+        ) {
+          return [
+            {
+              kind: "snapshot",
+              snapshot: {
+                snapshotSequence: fixture.snapshot.snapshotSequence,
+                thread: fixture.snapshot.threads[0],
+              },
             },
           ];
         }
@@ -450,16 +537,20 @@ describe("Keybindings update toast", () => {
     document.body.innerHTML = "";
   });
 
-  it("shows a toast for each consecutive keybinding update with no issues", async () => {
+  it("coalesces rapid consecutive keybinding update toasts with no issues", async () => {
     const mounted = await mountApp();
 
     try {
       sendServerConfigUpdatedPush([]);
       await waitForToast("Keybindings updated", 1);
 
-      // Each server push represents a distinct file change, so it should produce its own toast.
+      // A single edit can produce several reload notifications as the direct update and
+      // filesystem watcher settle, so avoid stacking identical success toasts.
       sendServerConfigUpdatedPush([]);
-      await waitForToast("Keybindings updated", 2);
+      await new Promise((resolve) => setTimeout(resolve, 250));
+
+      const titles = queryToastTitles();
+      expect(titles.filter((title) => title === "Keybindings updated")).toHaveLength(1);
     } finally {
       await mounted.cleanup();
     }
diff --git a/apps/web/src/components/NoActiveThreadState.tsx b/apps/web/src/components/NoActiveThreadState.tsx
index 39aa4e2f728..cd1f76ed2c2 100644
--- a/apps/web/src/components/NoActiveThreadState.tsx
+++ b/apps/web/src/components/NoActiveThreadState.tsx
@@ -10,11 +10,15 @@ export function NoActiveThreadState() {
         <header
           className={cn(
             "border-b border-border px-3 sm:px-5",
-            isElectron ? "drag-region flex h-[52px] items-center" : "py-2 sm:py-3",
+            isElectron
+              ? "drag-region flex h-[52px] items-center wco:h-[env(titlebar-area-height)]"
+              : "py-2 sm:py-3",
           )}
         >
           {isElectron ? (
-            <span className="text-xs text-muted-foreground/50">No active thread</span>
+            <span className="text-xs text-muted-foreground/50 wco:pr-[calc(100vw-env(titlebar-area-width)-env(titlebar-area-x)+1em)]">
+              No active thread
+            </span>
           ) : (
             <div className="flex items-center gap-2">
               <SidebarTrigger className="size-7 shrink-0 md:hidden" />
diff --git a/apps/web/src/components/PlanSidebar.tsx b/apps/web/src/components/PlanSidebar.tsx
index 134ca2e6f3f..afd4bb2e0bc 100644
--- a/apps/web/src/components/PlanSidebar.tsx
+++ b/apps/web/src/components/PlanSidebar.tsx
@@ -26,7 +26,7 @@ import {
 } from "../proposedPlan";
 import { Menu, MenuItem, MenuPopup, MenuTrigger } from "./ui/menu";
 import { readEnvironmentApi } from "~/environmentApi";
-import { toastManager } from "./ui/toast";
+import { stackedThreadToast, toastManager } from "./ui/toast";
 import { useCopyToClipboard } from "~/hooks/useCopyToClipboard";
 
 function stepStatusIcon(status: string): React.ReactNode {
@@ -54,20 +54,24 @@ function stepStatusIcon(status: string): React.ReactNode {
 interface PlanSidebarProps {
   activePlan: ActivePlanState | null;
   activeProposedPlan: LatestProposedPlanState | null;
+  label?: string;
   environmentId: EnvironmentId;
   markdownCwd: string | undefined;
   workspaceRoot: string | undefined;
   timestampFormat: TimestampFormat;
+  mode?: "sheet" | "sidebar";
   onClose: () => void;
 }
 
 const PlanSidebar = memo(function PlanSidebar({
   activePlan,
   activeProposedPlan,
+  label = "Plan",
   environmentId,
   markdownCwd,
   workspaceRoot,
   timestampFormat,
+  mode = "sidebar",
   onClose,
 }: PlanSidebarProps) {
   const [proposedPlanExpanded, setProposedPlanExpanded] = useState(false);
@@ -108,11 +112,13 @@ const PlanSidebar = memo(function PlanSidebar({
         });
       })
       .catch((error) => {
-        toastManager.add({
-          type: "error",
-          title: "Could not save plan",
-          description: error instanceof Error ? error.message : "An error occurred.",
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not save plan",
+            description: error instanceof Error ? error.message : "An error occurred.",
+          }),
+        );
       })
       .then(
         () => setIsSavingToWorkspace(false),
@@ -121,7 +127,14 @@ const PlanSidebar = memo(function PlanSidebar({
   }, [environmentId, planMarkdown, workspaceRoot]);
 
   return (
-    <div className="flex h-full w-[340px] shrink-0 flex-col border-l border-border/70 bg-card/50">
+    <div
+      className={cn(
+        "flex min-h-0 flex-col bg-card/50",
+        mode === "sidebar"
+          ? "h-full w-[340px] shrink-0 border-l border-border/70"
+          : "h-full w-full",
+      )}
+    >
       {/* Header */}
       <div className="flex h-12 shrink-0 items-center justify-between border-b border-border/60 px-3">
         <div className="flex items-center gap-2">
@@ -129,7 +142,7 @@ const PlanSidebar = memo(function PlanSidebar({
             variant="secondary"
             className="rounded-md bg-blue-500/10 px-1.5 py-0 text-[10px] font-semibold tracking-wide text-blue-400 uppercase"
           >
-            Plan
+            {label}
           </Badge>
           {activePlan ? (
             <span className="text-[11px] text-muted-foreground/60">
@@ -170,7 +183,7 @@ const PlanSidebar = memo(function PlanSidebar({
             size="icon-xs"
             variant="ghost"
             onClick={onClose}
-            aria-label="Close plan sidebar"
+            aria-label={`Close ${label.toLowerCase()} sidebar`}
             className="text-muted-foreground/50 hover:text-foreground/70"
           >
             <PanelRightCloseIcon className="size-3.5" />
diff --git a/apps/web/src/components/ProjectFavicon.tsx b/apps/web/src/components/ProjectFavicon.tsx
index 38e07f59ced..ad47e01bb11 100644
--- a/apps/web/src/components/ProjectFavicon.tsx
+++ b/apps/web/src/components/ProjectFavicon.tsx
@@ -10,15 +10,29 @@ export function ProjectFavicon(input: {
   cwd: string;
   className?: string;
 }) {
-  const src = resolveEnvironmentHttpUrl({
-    environmentId: input.environmentId,
-    pathname: "/api/project-favicon",
-    searchParams: { cwd: input.cwd },
-  });
+  const src = (() => {
+    try {
+      return resolveEnvironmentHttpUrl({
+        environmentId: input.environmentId,
+        pathname: "/api/project-favicon",
+        searchParams: { cwd: input.cwd },
+      });
+    } catch {
+      return null;
+    }
+  })();
   const [status, setStatus] = useState<"loading" | "loaded" | "error">(() =>
-    loadedProjectFaviconSrcs.has(src) ? "loaded" : "loading",
+    src && loadedProjectFaviconSrcs.has(src) ? "loaded" : "loading",
   );
 
+  if (!src) {
+    return (
+      <FolderIcon
+        className={`size-3.5 shrink-0 text-muted-foreground/50 ${input.className ?? ""}`}
+      />
+    );
+  }
+
   return (
     <>
       {status !== "loaded" ? (
diff --git a/apps/web/src/components/ProjectScriptsControl.tsx b/apps/web/src/components/ProjectScriptsControl.tsx
index 11b08cc2cf4..4a9cda19d65 100644
--- a/apps/web/src/components/ProjectScriptsControl.tsx
+++ b/apps/web/src/components/ProjectScriptsControl.tsx
@@ -20,13 +20,13 @@ import {
   keybindingValueForCommand,
   decodeProjectScriptKeybindingRule,
 } from "~/lib/projectScriptKeybindings";
+import { keybindingFromKeyboardEvent } from "~/components/settings/KeybindingsSettings.logic";
 import {
   commandForProjectScript,
   nextProjectScriptId,
   primaryProjectScript,
 } from "~/projectScripts";
 import { shortcutLabelForCommand } from "~/keybindings";
-import { isMacPlatform } from "~/lib/utils";
 import {
   AlertDialog,
   AlertDialogClose,
@@ -96,57 +96,6 @@ interface ProjectScriptsControlProps {
   onDeleteScript: (scriptId: string) => Promise<void> | void;
 }
 
-function normalizeShortcutKeyToken(key: string): string | null {
-  const normalized = key.toLowerCase();
-  if (
-    normalized === "meta" ||
-    normalized === "control" ||
-    normalized === "ctrl" ||
-    normalized === "shift" ||
-    normalized === "alt" ||
-    normalized === "option"
-  ) {
-    return null;
-  }
-  if (normalized === " ") return "space";
-  if (normalized === "escape") return "esc";
-  if (normalized === "arrowup") return "arrowup";
-  if (normalized === "arrowdown") return "arrowdown";
-  if (normalized === "arrowleft") return "arrowleft";
-  if (normalized === "arrowright") return "arrowright";
-  if (normalized.length === 1) return normalized;
-  if (normalized.startsWith("f") && normalized.length <= 3) return normalized;
-  if (normalized === "enter" || normalized === "tab" || normalized === "backspace") {
-    return normalized;
-  }
-  if (normalized === "delete" || normalized === "home" || normalized === "end") {
-    return normalized;
-  }
-  if (normalized === "pageup" || normalized === "pagedown") return normalized;
-  return null;
-}
-
-function keybindingFromEvent(event: KeyboardEvent<HTMLInputElement>): string | null {
-  const keyToken = normalizeShortcutKeyToken(event.key);
-  if (!keyToken) return null;
-
-  const parts: string[] = [];
-  if (isMacPlatform(navigator.platform)) {
-    if (event.metaKey) parts.push("mod");
-    if (event.ctrlKey) parts.push("ctrl");
-  } else {
-    if (event.ctrlKey) parts.push("mod");
-    if (event.metaKey) parts.push("meta");
-  }
-  if (event.altKey) parts.push("alt");
-  if (event.shiftKey) parts.push("shift");
-  if (parts.length === 0) {
-    return null;
-  }
-  parts.push(keyToken);
-  return parts.join("+");
-}
-
 export default function ProjectScriptsControl({
   scripts,
   keybindings,
@@ -186,7 +135,7 @@ export default function ProjectScriptsControl({
       setKeybinding("");
       return;
     }
-    const next = keybindingFromEvent(event);
+    const next = keybindingFromKeyboardEvent(event, navigator.platform);
     if (!next) return;
     setKeybinding(next);
   };
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
new file mode 100644
index 00000000000..defb6eb20bd
--- /dev/null
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
@@ -0,0 +1,673 @@
+import { describe, expect, it } from "vitest";
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+
+import {
+  canOneClickUpdateProviderCandidate,
+  collectProviderUpdateCandidates,
+  collectUpdatedProviderSnapshots,
+  firstRejectedProviderUpdateMessage,
+  getProviderUpdateInitialToastView,
+  getProviderUpdateProgressToastView,
+  getProviderUpdateRejectedToastView,
+  getProviderUpdateSidebarPillView,
+  getSingleProviderUpdateProgressToastView,
+  hasOneClickUpdateProviderCandidate,
+  isProviderUpdateCandidate,
+  providerUpdateNotificationKey,
+  type ProviderUpdateCandidate,
+} from "./ProviderUpdateLaunchNotification.logic";
+
+const checkedAt = "2026-04-23T10:00:00.000Z";
+const sessionStartedAt = "2026-04-23T09:59:00.000Z";
+const laterCheckedAt = "2026-04-23T10:01:00.000Z";
+
+const driver = (value: string) => ProviderDriverKind.make(value);
+const instanceId = (value: string) => ProviderInstanceId.make(value);
+
+function provider(input: {
+  readonly driver: ReturnType<typeof ProviderDriverKind.make>;
+  readonly instanceId?: ReturnType<typeof ProviderInstanceId.make>;
+  readonly enabled?: boolean;
+  readonly version?: string | null;
+  readonly latestVersion?: string | null;
+  readonly canUpdate?: boolean;
+  readonly updateCommand?: string | null;
+  readonly updateState?: ServerProvider["updateState"];
+  readonly advisoryStatus?: NonNullable<ServerProvider["versionAdvisory"]>["status"];
+}): ServerProvider {
+  const result: ServerProvider = {
+    instanceId: input.instanceId ?? instanceId(String(input.driver)),
+    driver: input.driver,
+    enabled: input.enabled ?? true,
+    installed: true,
+    version: input.version ?? "1.0.0",
+    status: "ready",
+    auth: { status: "authenticated" },
+    checkedAt,
+    models: [],
+    slashCommands: [],
+    skills: [],
+    versionAdvisory: {
+      status: input.advisoryStatus ?? "behind_latest",
+      currentVersion: input.version ?? "1.0.0",
+      latestVersion: "latestVersion" in input ? input.latestVersion : "1.1.0",
+      updateCommand: "updateCommand" in input ? input.updateCommand : "npm install -g provider",
+      canUpdate: input.canUpdate ?? true,
+      checkedAt,
+      message: "Update available.",
+    },
+  };
+
+  if (input.updateState) {
+    return { ...result, updateState: input.updateState };
+  }
+
+  return result;
+}
+
+function updateCandidate(input: Parameters<typeof provider>[0]): ProviderUpdateCandidate {
+  return provider(input) as ProviderUpdateCandidate;
+}
+
+describe("provider update launch notification logic", () => {
+  it("detects enabled providers with a latest-version advisory", () => {
+    expect(isProviderUpdateCandidate(provider({ driver: driver("codex") }))).toBe(true);
+    expect(isProviderUpdateCandidate(provider({ driver: driver("codex"), enabled: false }))).toBe(
+      false,
+    );
+    expect(
+      isProviderUpdateCandidate(
+        provider({ driver: driver("codex"), advisoryStatus: "current", latestVersion: null }),
+      ),
+    ).toBe(false);
+    expect(
+      isProviderUpdateCandidate(provider({ driver: driver("codex"), latestVersion: null })),
+    ).toBe(false);
+  });
+
+  it("deduplicates multi-instance provider candidates by driver", () => {
+    expect(
+      collectProviderUpdateCandidates([
+        provider({
+          driver: driver("codex"),
+          instanceId: instanceId("codex_personal"),
+          latestVersion: "1.1.0",
+        }),
+        provider({
+          driver: driver("codex"),
+          instanceId: instanceId("codex"),
+          latestVersion: "1.1.0",
+        }),
+        provider({ driver: driver("cursor"), latestVersion: "0.3.0" }),
+      ]),
+    ).toHaveLength(2);
+  });
+
+  it("disables one-click updates when provider instances disagree on the update command", () => {
+    const candidate = updateCandidate({
+      driver: driver("claudeAgent"),
+      instanceId: instanceId("claude_personal"),
+      latestVersion: "2.1.123",
+    });
+
+    expect(
+      canOneClickUpdateProviderCandidate(candidate, [
+        candidate,
+        provider({
+          driver: driver("claudeAgent"),
+          instanceId: instanceId("claude_work"),
+          latestVersion: "2.1.123",
+          canUpdate: true,
+          updateCommand: "bun add -g @anthropic-ai/claude-code@latest",
+        }),
+      ]),
+    ).toBe(false);
+  });
+
+  it("keeps one-click updates enabled when sibling instances are already current", () => {
+    const candidate = updateCandidate({
+      driver: driver("claudeAgent"),
+      instanceId: instanceId("claude_personal"),
+      latestVersion: "2.1.123",
+      updateCommand: "npm install -g @anthropic-ai/claude-code@latest",
+    });
+
+    expect(
+      hasOneClickUpdateProviderCandidate(candidate, [
+        candidate,
+        provider({
+          driver: driver("claudeAgent"),
+          instanceId: instanceId("claude_work"),
+          version: "2.1.123",
+          latestVersion: "2.1.123",
+          advisoryStatus: "current",
+          canUpdate: false,
+          updateCommand: null,
+        }),
+      ]),
+    ).toBe(true);
+    expect(
+      canOneClickUpdateProviderCandidate(candidate, [
+        candidate,
+        provider({
+          driver: driver("claudeAgent"),
+          instanceId: instanceId("claude_work"),
+          version: "2.1.123",
+          latestVersion: "2.1.123",
+          advisoryStatus: "current",
+          canUpdate: false,
+          updateCommand: null,
+        }),
+      ]),
+    ).toBe(true);
+  });
+
+  it("keeps the inline update action available while a provider update is already running", () => {
+    const candidate = updateCandidate({
+      driver: driver("codex"),
+      updateState: {
+        status: "running",
+        startedAt: checkedAt,
+        finishedAt: null,
+        message: "Updating provider.",
+        output: null,
+      },
+    });
+
+    expect(hasOneClickUpdateProviderCandidate(candidate, [candidate])).toBe(true);
+    expect(canOneClickUpdateProviderCandidate(candidate, [candidate])).toBe(false);
+  });
+
+  it("builds a notification key from provider latest versions", () => {
+    const codex = updateCandidate({
+      driver: driver("codex"),
+      version: "1.0.0",
+      latestVersion: "1.1.0",
+    });
+    const cursor = updateCandidate({
+      driver: driver("cursor"),
+      version: "0.2.0",
+      latestVersion: "0.3.0",
+    });
+
+    expect(providerUpdateNotificationKey([codex, cursor])).toBe("codex:1.1.0|cursor:0.3.0");
+    expect(providerUpdateNotificationKey([])).toBeNull();
+  });
+
+  it("keeps the same notification key while the published update version is unchanged", () => {
+    const first = updateCandidate({
+      driver: driver("codex"),
+      version: "1.0.0",
+      latestVersion: "1.2.0",
+    });
+    const second = updateCandidate({
+      driver: driver("codex"),
+      version: "1.1.0",
+      latestVersion: "1.2.0",
+    });
+    const nextPublishedVersion = updateCandidate({
+      driver: driver("codex"),
+      version: "1.1.0",
+      latestVersion: "1.3.0",
+    });
+
+    expect(providerUpdateNotificationKey([first])).toBe(providerUpdateNotificationKey([second]));
+    expect(providerUpdateNotificationKey([nextPublishedVersion])).not.toBe(
+      providerUpdateNotificationKey([first]),
+    );
+  });
+
+  it("tracks updated provider snapshots by instance instead of collapsing to a sibling driver", () => {
+    const targetInstanceId = instanceId("codex_personal");
+    const siblingInstanceId = instanceId("codex");
+    const updatedPersonal = provider({
+      driver: driver("codex"),
+      instanceId: targetInstanceId,
+      version: "1.1.0",
+      latestVersion: "1.1.0",
+      advisoryStatus: "current",
+      updateState: {
+        status: "succeeded",
+        startedAt: checkedAt,
+        finishedAt: checkedAt,
+        message: "Provider updated.",
+        output: null,
+      },
+    });
+    const currentDefaultSibling = provider({
+      driver: driver("codex"),
+      instanceId: siblingInstanceId,
+      version: "1.1.0",
+      latestVersion: "1.1.0",
+      advisoryStatus: "current",
+      updateState: undefined,
+    });
+
+    expect(
+      collectUpdatedProviderSnapshots({
+        results: [
+          {
+            status: "fulfilled",
+            value: {
+              providers: [updatedPersonal, currentDefaultSibling],
+            },
+          },
+        ],
+        providerInstanceIds: new Set([targetInstanceId]),
+      }),
+    ).toEqual([updatedPersonal]);
+  });
+
+  it("describes a single one-click update", () => {
+    const view = getProviderUpdateInitialToastView({
+      updateProviders: [updateCandidate({ driver: driver("codex"), latestVersion: "1.1.0" })],
+      oneClickProviders: [updateCandidate({ driver: driver("codex"), latestVersion: "1.1.0" })],
+    });
+
+    expect(view).toMatchObject({
+      phase: "initial",
+      type: "warning",
+      title: "Update Available: Codex v1.1.0",
+      description: "Install the update now or review provider settings.",
+    });
+  });
+
+  it("describes settings-only updates without one-click support", () => {
+    const view = getProviderUpdateInitialToastView({
+      updateProviders: [
+        updateCandidate({ driver: driver("codex"), canUpdate: false }),
+        updateCandidate({ driver: driver("cursor"), canUpdate: false }),
+      ],
+      oneClickProviders: [],
+    });
+
+    expect(view.description).toBe("Codex and Cursor can be updated from provider settings.");
+  });
+
+  it("uses server update state for running progress", () => {
+    const view = getProviderUpdateProgressToastView({
+      providers: [
+        provider({
+          driver: driver("codex"),
+          updateState: {
+            status: "running",
+            startedAt: checkedAt,
+            finishedAt: null,
+            message: "Updating provider.",
+            output: null,
+          },
+        }),
+      ],
+      providerCount: 1,
+    });
+
+    expect(view).toMatchObject({
+      phase: "running",
+      type: "loading",
+      title: "Updating provider",
+    });
+  });
+
+  it("uses server failure state for failed progress", () => {
+    const view = getProviderUpdateProgressToastView({
+      providers: [
+        provider({
+          driver: driver("codex"),
+          updateState: {
+            status: "failed",
+            startedAt: checkedAt,
+            finishedAt: checkedAt,
+            message: "command failed",
+            output: "stderr",
+          },
+        }),
+      ],
+      providerCount: 1,
+    });
+
+    expect(view).toMatchObject({
+      phase: "failed",
+      type: "error",
+      title: "Provider update failed",
+      description: "command failed",
+    });
+  });
+
+  it("resolves a single-provider completion view from the returned provider snapshot", () => {
+    const view = getSingleProviderUpdateProgressToastView(
+      provider({
+        driver: driver("codex"),
+        updateState: {
+          status: "failed",
+          startedAt: checkedAt,
+          finishedAt: checkedAt,
+          message: "command failed",
+          output: "stderr",
+        },
+      }),
+    );
+
+    expect(view).toMatchObject({
+      phase: "failed",
+      type: "error",
+      title: "Codex v1.1.0 update failed",
+      description: "command failed",
+    });
+  });
+
+  it("keeps unchanged providers actionable from settings", () => {
+    const view = getProviderUpdateProgressToastView({
+      providers: [
+        provider({
+          driver: driver("cursor"),
+          updateState: {
+            status: "unchanged",
+            startedAt: checkedAt,
+            finishedAt: checkedAt,
+            message: "still old",
+            output: null,
+          },
+        }),
+      ],
+      providerCount: 1,
+    });
+
+    expect(view).toMatchObject({
+      phase: "unchanged",
+      type: "warning",
+      title: "Provider still needs an update",
+      description: "Cursor still appears outdated. Check provider settings for details.",
+    });
+  });
+
+  it("marks progress succeeded once every attempted provider is no longer outdated", () => {
+    const view = getProviderUpdateProgressToastView({
+      providers: [
+        provider({
+          driver: driver("codex"),
+          version: "1.1.0",
+          latestVersion: "1.1.0",
+          advisoryStatus: "current",
+          updateState: {
+            status: "succeeded",
+            startedAt: checkedAt,
+            finishedAt: checkedAt,
+            message: "Provider updated.",
+            output: null,
+          },
+        }),
+      ],
+      providerCount: 1,
+    });
+
+    expect(view).toMatchObject({
+      phase: "succeeded",
+      type: "success",
+      title: "Provider updated",
+      description: "New sessions will use the updated provider.",
+      dismissAfterVisibleMs: 3_000,
+    });
+  });
+
+  it("uses the updated version in the single-provider success toast title", () => {
+    const view = getSingleProviderUpdateProgressToastView(
+      provider({
+        driver: driver("codex"),
+        version: "1.1.0",
+        latestVersion: "1.1.0",
+        advisoryStatus: "current",
+        updateState: {
+          status: "succeeded",
+          startedAt: checkedAt,
+          finishedAt: checkedAt,
+          message: "Provider updated.",
+          output: null,
+        },
+      }),
+    );
+
+    expect(view).toMatchObject({
+      phase: "succeeded",
+      type: "success",
+      title: "Codex updated: v1.1.0",
+      description: "New sessions will use the updated provider.",
+    });
+  });
+
+  it("falls back to a rejected RPC message for transport-level failures", () => {
+    const results: PromiseSettledResult<unknown>[] = [
+      { status: "rejected", reason: new Error("WebSocket closed") },
+    ];
+
+    expect(firstRejectedProviderUpdateMessage(results)).toBe("WebSocket closed");
+    expect(getProviderUpdateRejectedToastView(2, "WebSocket closed")).toMatchObject({
+      phase: "failed",
+      title: "Provider updates failed",
+      description: "WebSocket closed",
+    });
+  });
+
+  it("collects only attempted provider snapshots from update responses", () => {
+    const codex = provider({ driver: driver("codex") });
+    const cursor = provider({ driver: driver("cursor") });
+    const results: PromiseSettledResult<{ readonly providers: ReadonlyArray<ServerProvider> }>[] = [
+      { status: "fulfilled", value: { providers: [codex, cursor] } },
+    ];
+
+    expect(
+      collectUpdatedProviderSnapshots({
+        results,
+        providerInstanceIds: new Set([cursor.instanceId]),
+      }),
+    ).toEqual([cursor]);
+  });
+
+  it("summarizes active provider updates for the sidebar pill", () => {
+    const view = getProviderUpdateSidebarPillView([
+      provider({
+        driver: driver("codex"),
+        updateState: {
+          status: "running",
+          startedAt: checkedAt,
+          finishedAt: null,
+          message: "Updating provider.",
+          output: null,
+        },
+      }),
+      provider({
+        driver: driver("cursor"),
+        updateState: {
+          status: "queued",
+          startedAt: null,
+          finishedAt: null,
+          message: "Waiting for another provider update to finish.",
+          output: null,
+        },
+      }),
+    ]);
+
+    expect(view).toMatchObject({
+      tone: "loading",
+      title: "Updating 2 providers",
+      description: "Codex and Cursor updates are in progress.",
+    });
+  });
+
+  it("uses the provider name for single active sidebar pill updates", () => {
+    const view = getProviderUpdateSidebarPillView([
+      provider({
+        driver: driver("codex"),
+        updateState: {
+          status: "running",
+          startedAt: checkedAt,
+          finishedAt: null,
+          message: "Updating provider.",
+          output: null,
+        },
+      }),
+    ]);
+
+    expect(view).toMatchObject({
+      key: "loading:codex:running",
+      tone: "loading",
+      title: "Updating Codex",
+      description: "Codex update in progress.",
+    });
+  });
+
+  it("uses the provider name for single failed sidebar pill updates", () => {
+    const view = getProviderUpdateSidebarPillView(
+      [
+        provider({
+          driver: driver("claudeAgent"),
+          updateState: {
+            status: "failed",
+            startedAt: checkedAt,
+            finishedAt: checkedAt,
+            message: "Update command exited with code 1.",
+            output: null,
+          },
+        }),
+      ],
+      { visibleAfterIso: sessionStartedAt },
+    );
+
+    expect(view).toMatchObject({
+      key: "failed:claudeAgent:2026-04-23T10:00:00.000Z:Update command exited with code 1.",
+      tone: "error",
+      title: "Claude v1.1.0 update failed",
+      description: "Update command exited with code 1.",
+      dismissible: true,
+    });
+  });
+
+  it("shows a short-lived success sidebar pill after a single provider update succeeds", () => {
+    const view = getProviderUpdateSidebarPillView(
+      [
+        provider({
+          driver: driver("codex"),
+          version: "1.1.0",
+          latestVersion: "1.1.0",
+          advisoryStatus: "current",
+          updateState: {
+            status: "succeeded",
+            startedAt: checkedAt,
+            finishedAt: checkedAt,
+            message: "Provider updated.",
+            output: null,
+          },
+        }),
+      ],
+      { visibleAfterIso: sessionStartedAt },
+    );
+
+    expect(view).toMatchObject({
+      key: "succeeded:codex:2026-04-23T10:00:00.000Z:Provider updated.",
+      tone: "success",
+      title: "Codex updated: v1.1.0",
+      description: "New sessions will use the updated provider.",
+      dismissAfterVisibleMs: 3_000,
+    });
+  });
+
+  it("keeps unchanged sidebar pill states dismissible", () => {
+    const view = getProviderUpdateSidebarPillView(
+      [
+        provider({
+          driver: driver("cursor"),
+          updateState: {
+            status: "unchanged",
+            startedAt: checkedAt,
+            finishedAt: checkedAt,
+            message: "still old",
+            output: null,
+          },
+        }),
+      ],
+      { visibleAfterIso: sessionStartedAt },
+    );
+
+    expect(view).toMatchObject({
+      key: "unchanged:cursor:2026-04-23T10:00:00.000Z:still old",
+      tone: "warning",
+      title: "Cursor still needs an update",
+      dismissible: true,
+    });
+  });
+
+  it("does not show sidebar terminal states from before the current app session", () => {
+    expect(
+      getProviderUpdateSidebarPillView(
+        [
+          provider({
+            driver: driver("codex"),
+            updateState: {
+              status: "failed",
+              startedAt: checkedAt,
+              finishedAt: checkedAt,
+              message: "command failed",
+              output: "stderr",
+            },
+          }),
+        ],
+        { visibleAfterIso: "2026-04-23T10:00:01.000Z" },
+      ),
+    ).toBeNull();
+  });
+
+  it("shows a newer success before falling back to an older failure", () => {
+    const providers = [
+      provider({
+        driver: driver("claudeAgent"),
+        updateState: {
+          status: "failed",
+          startedAt: checkedAt,
+          finishedAt: checkedAt,
+          message: "Update command exited with code 1.",
+          output: null,
+        },
+      }),
+      provider({
+        driver: driver("codex"),
+        version: "1.2.0",
+        latestVersion: "1.2.0",
+        advisoryStatus: "current",
+        updateState: {
+          status: "succeeded",
+          startedAt: laterCheckedAt,
+          finishedAt: laterCheckedAt,
+          message: "Provider updated.",
+          output: null,
+        },
+      }),
+    ] satisfies ReadonlyArray<ServerProvider>;
+
+    const successView = getProviderUpdateSidebarPillView(providers, {
+      visibleAfterIso: sessionStartedAt,
+    });
+    expect(successView).toMatchObject({
+      key: "succeeded:codex:2026-04-23T10:01:00.000Z:Provider updated.",
+      tone: "success",
+      title: "Codex updated: v1.2.0",
+    });
+
+    const failureView = getProviderUpdateSidebarPillView(providers, {
+      visibleAfterIso: sessionStartedAt,
+      dismissedKeys: new Set(["succeeded:codex:2026-04-23T10:01:00.000Z:Provider updated."]),
+    });
+    expect(failureView).toMatchObject({
+      key: "failed:claudeAgent:2026-04-23T10:00:00.000Z:Update command exited with code 1.",
+      tone: "error",
+      title: "Claude v1.1.0 update failed",
+    });
+  });
+
+  it("does not show a sidebar pill for passive update availability", () => {
+    expect(
+      getProviderUpdateSidebarPillView([
+        provider({ driver: driver("codex"), canUpdate: true }),
+        provider({ driver: driver("cursor"), canUpdate: false }),
+      ]),
+    ).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
new file mode 100644
index 00000000000..f45b2916ce4
--- /dev/null
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
@@ -0,0 +1,537 @@
+import {
+  defaultInstanceIdForDriver,
+  PROVIDER_DISPLAY_NAMES,
+  type ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+
+export type ProviderUpdateCandidate = ServerProvider & {
+  readonly versionAdvisory: NonNullable<ServerProvider["versionAdvisory"]> & {
+    readonly status: "behind_latest";
+    readonly latestVersion: string;
+  };
+};
+
+export type ProviderUpdateToastType = "warning" | "loading" | "error" | "success";
+export type ProviderUpdateToastPhase = "initial" | "running" | "failed" | "unchanged" | "succeeded";
+
+export interface ProviderUpdateToastView {
+  readonly phase: ProviderUpdateToastPhase;
+  readonly type: ProviderUpdateToastType;
+  readonly title: string;
+  readonly description: string;
+  readonly dismissAfterVisibleMs?: number;
+}
+
+export type ProviderUpdateSidebarPillTone = "loading" | "warning" | "error" | "success";
+
+export interface ProviderUpdateSidebarPillView {
+  readonly key: string;
+  readonly tone: ProviderUpdateSidebarPillTone;
+  readonly title: string;
+  readonly description: string;
+  readonly dismissible?: boolean;
+  readonly dismissAfterVisibleMs?: number;
+}
+
+interface ProviderUpdateSidebarPillOptions {
+  readonly visibleAfterIso?: string;
+  readonly dismissedKeys?: ReadonlySet<string>;
+}
+
+const PROVIDER_UPDATE_SUCCESS_VISIBLE_MS = 3_000;
+
+function formatVersion(value: string): string {
+  return value.startsWith("v") ? value : `v${value}`;
+}
+
+function chooseRepresentativeProvider(
+  current: ServerProvider | undefined,
+  candidate: ServerProvider,
+): ServerProvider {
+  if (!current) {
+    return candidate;
+  }
+  const defaultInstanceId = defaultInstanceIdForDriver(candidate.driver);
+  if (candidate.instanceId === defaultInstanceId) {
+    return candidate;
+  }
+  if (current.instanceId === defaultInstanceId) {
+    return current;
+  }
+  return candidate.checkedAt.localeCompare(current.checkedAt) >= 0 ? candidate : current;
+}
+
+function dedupeProvidersByDriver<T extends ServerProvider>(providers: ReadonlyArray<T>): T[] {
+  const latestProviderByDriver = new Map<ProviderDriverKind, T>();
+
+  for (const provider of providers) {
+    latestProviderByDriver.set(
+      provider.driver,
+      chooseRepresentativeProvider(latestProviderByDriver.get(provider.driver), provider) as T,
+    );
+  }
+
+  return [...latestProviderByDriver.values()];
+}
+
+function dedupeProvidersByInstanceId<T extends ServerProvider>(providers: ReadonlyArray<T>): T[] {
+  const latestProviderByInstanceId = new Map<ProviderInstanceId, T>();
+
+  for (const provider of providers) {
+    const current = latestProviderByInstanceId.get(provider.instanceId);
+    if (!current || provider.checkedAt.localeCompare(current.checkedAt) >= 0) {
+      latestProviderByInstanceId.set(provider.instanceId, provider);
+    }
+  }
+
+  return [...latestProviderByInstanceId.values()];
+}
+
+function getProviderUpdatedTitle(provider: Pick<ServerProvider, "driver" | "version">): string {
+  const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+  return provider.version
+    ? `${providerName} updated: ${formatVersion(provider.version)}`
+    : `${providerName} updated`;
+}
+
+function getProviderUpdatedDescription(providerCount: number): string {
+  return providerCount === 1
+    ? "New sessions will use the updated provider."
+    : "New sessions will use the updated providers.";
+}
+
+function getProviderFailedUpdateTitle(
+  provider: Pick<ServerProvider, "driver" | "versionAdvisory">,
+): string {
+  const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+  const attemptedVersion = provider.versionAdvisory?.latestVersion;
+  return attemptedVersion
+    ? `${providerName} ${formatVersion(attemptedVersion)} update failed`
+    : `${providerName} update failed`;
+}
+
+export function isProviderUpdateCandidate(
+  provider: ServerProvider,
+): provider is ProviderUpdateCandidate {
+  return (
+    provider.enabled &&
+    provider.versionAdvisory?.status === "behind_latest" &&
+    provider.versionAdvisory.latestVersion !== null
+  );
+}
+
+export function isProviderUpdateActive(provider: Pick<ServerProvider, "updateState">): boolean {
+  return provider.updateState?.status === "queued" || provider.updateState?.status === "running";
+}
+
+export function collectProviderUpdateCandidates(
+  providers: ReadonlyArray<ServerProvider>,
+): ProviderUpdateCandidate[] {
+  return dedupeProvidersByDriver(providers.filter(isProviderUpdateCandidate));
+}
+
+export function hasOneClickUpdateProviderCandidate(
+  candidate: ProviderUpdateCandidate,
+  providers: ReadonlyArray<ServerProvider>,
+): boolean {
+  if (
+    candidate.versionAdvisory.canUpdate !== true ||
+    candidate.versionAdvisory.updateCommand === null
+  ) {
+    return false;
+  }
+
+  const driverProviders = providers.filter((provider) => provider.driver === candidate.driver);
+  if (driverProviders.length === 0) {
+    return false;
+  }
+
+  const updateCommands = new Set<string>();
+  for (const provider of driverProviders) {
+    if (!isProviderUpdateCandidate(provider)) {
+      continue;
+    }
+    const advisory = provider.versionAdvisory;
+    if (!advisory || advisory.canUpdate !== true || advisory.updateCommand === null) {
+      return false;
+    }
+    updateCommands.add(advisory.updateCommand);
+  }
+
+  return updateCommands.size === 1;
+}
+
+export function canOneClickUpdateProviderCandidate(
+  candidate: ProviderUpdateCandidate,
+  providers: ReadonlyArray<ServerProvider>,
+): boolean {
+  return (
+    !isProviderUpdateActive(candidate) && hasOneClickUpdateProviderCandidate(candidate, providers)
+  );
+}
+
+export function providerUpdateNotificationKey(
+  providers: ReadonlyArray<ProviderUpdateCandidate>,
+): string | null {
+  const parts = dedupeProvidersByDriver(providers)
+    .map((provider) => {
+      const advisory = provider.versionAdvisory;
+      return [provider.driver, advisory.latestVersion].join(":");
+    })
+    .toSorted();
+
+  return parts.length > 0 ? parts.join("|") : null;
+}
+
+export function providerUpdateCandidateKey(provider: ProviderUpdateCandidate): string {
+  return providerUpdateNotificationKey([provider])!;
+}
+
+export function formatProviderList(providers: ReadonlyArray<Pick<ServerProvider, "driver">>) {
+  const names = providers.map(
+    (provider) => PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver,
+  );
+  if (names.length <= 2) {
+    return names.join(" and ");
+  }
+  return `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;
+}
+
+export function getProviderUpdateInitialToastView(input: {
+  readonly updateProviders: ReadonlyArray<ProviderUpdateCandidate>;
+  readonly oneClickProviders: ReadonlyArray<ProviderUpdateCandidate>;
+}): ProviderUpdateToastView {
+  return {
+    phase: "initial",
+    type: "warning",
+    title: getProviderUpdateInitialToastTitle(input.updateProviders),
+    description:
+      input.oneClickProviders.length > 0
+        ? "Install the update now or review provider settings."
+        : `${formatProviderList(input.updateProviders)} can be updated from provider settings.`,
+  };
+}
+
+export function getProviderUpdateRunningToastView(providerCount: number): ProviderUpdateToastView {
+  return {
+    phase: "running",
+    type: "loading",
+    title: providerCount === 1 ? "Updating provider" : "Updating providers",
+    description: "Running provider update command.",
+  };
+}
+
+export function getProviderUpdateRejectedToastView(
+  providerCount: number,
+  message: string,
+): ProviderUpdateToastView {
+  return {
+    phase: "failed",
+    type: "error",
+    title: providerCount === 1 ? "Provider update failed" : "Provider updates failed",
+    description: message,
+  };
+}
+
+export function getProviderUpdateProgressToastView(input: {
+  readonly providers: ReadonlyArray<ServerProvider>;
+  readonly providerCount: number;
+}): ProviderUpdateToastView {
+  const providers = dedupeProvidersByDriver(input.providers);
+  const failedProviders = providers.filter((provider) => provider.updateState?.status === "failed");
+  if (failedProviders.length > 0) {
+    return {
+      phase: "failed",
+      type: "error",
+      title: failedProviders.length === 1 ? "Provider update failed" : "Provider updates failed",
+      description: getFailedProviderUpdateDescription(failedProviders),
+    };
+  }
+
+  const unchangedProviders = providers.filter(
+    (provider) => provider.updateState?.status === "unchanged",
+  );
+  if (unchangedProviders.length > 0) {
+    return {
+      phase: "unchanged",
+      type: "warning",
+      title:
+        unchangedProviders.length === 1
+          ? "Provider still needs an update"
+          : "Providers still need updates",
+      description: `${formatProviderList(unchangedProviders)} ${
+        unchangedProviders.length === 1 ? "still appears" : "still appear"
+      } outdated. Check provider settings for details.`,
+    };
+  }
+
+  if (providers.some(isProviderUpdateActive)) {
+    return getProviderUpdateRunningToastView(input.providerCount);
+  }
+
+  const hasCompleteProviderSnapshots = providers.length >= input.providerCount;
+  const allProvidersUpdated =
+    hasCompleteProviderSnapshots &&
+    providers.every(
+      (provider) =>
+        provider.updateState?.status === "succeeded" || !isProviderUpdateCandidate(provider),
+    );
+  if (allProvidersUpdated) {
+    return {
+      phase: "succeeded",
+      type: "success",
+      title: input.providerCount === 1 ? "Provider updated" : "Provider updates finished",
+      description: getProviderUpdatedDescription(input.providerCount),
+      dismissAfterVisibleMs: PROVIDER_UPDATE_SUCCESS_VISIBLE_MS,
+    };
+  }
+
+  return getProviderUpdateRunningToastView(input.providerCount);
+}
+
+export function getSingleProviderUpdateProgressToastView(
+  provider: ServerProvider,
+): ProviderUpdateToastView {
+  const view = getProviderUpdateProgressToastView({
+    providers: [provider],
+    providerCount: 1,
+  });
+  const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+
+  switch (view.phase) {
+    case "running":
+      return {
+        ...view,
+        title: `Updating ${providerName}`,
+      };
+    case "failed":
+      return {
+        ...view,
+        title: getProviderFailedUpdateTitle(provider),
+      };
+    case "unchanged":
+      return {
+        ...view,
+        title: `${providerName} still needs an update`,
+      };
+    case "succeeded":
+      return {
+        ...view,
+        title: getProviderUpdatedTitle(provider),
+      };
+    default:
+      return view;
+  }
+}
+
+export function collectUpdatedProviderSnapshots(input: {
+  readonly results: ReadonlyArray<
+    PromiseSettledResult<{ readonly providers: ReadonlyArray<ServerProvider> }>
+  >;
+  readonly providerInstanceIds: ReadonlySet<ProviderInstanceId>;
+}): ServerProvider[] {
+  const matchedProviders: ServerProvider[] = [];
+
+  for (const result of input.results) {
+    if (result.status !== "fulfilled") {
+      continue;
+    }
+    for (const provider of result.value.providers) {
+      if (input.providerInstanceIds.has(provider.instanceId)) {
+        matchedProviders.push(provider);
+      }
+    }
+  }
+
+  return dedupeProvidersByInstanceId(matchedProviders);
+}
+
+export function firstRejectedProviderUpdateMessage(
+  results: ReadonlyArray<PromiseSettledResult<unknown>>,
+): string | null {
+  const rejected = results.find((result) => result.status === "rejected");
+  if (!rejected) {
+    return null;
+  }
+  return rejected.reason instanceof Error ? rejected.reason.message : "Provider update failed.";
+}
+
+function getUpdateFinishedAt(provider: ServerProvider): string | null {
+  return provider.updateState?.finishedAt ?? null;
+}
+
+function isRecentTerminalProvider(
+  provider: ServerProvider,
+  visibleAfterIso: string | undefined,
+): boolean {
+  const status = provider.updateState?.status;
+  if (status !== "failed" && status !== "unchanged" && status !== "succeeded") {
+    return false;
+  }
+  if (visibleAfterIso === undefined) {
+    return true;
+  }
+  const finishedAt = getUpdateFinishedAt(provider);
+  return finishedAt !== null && finishedAt >= visibleAfterIso;
+}
+
+function latestFinishedAtForProviders(providers: ReadonlyArray<ServerProvider>): string | null {
+  return providers.reduce<string | null>((latest, provider) => {
+    const finishedAt = getUpdateFinishedAt(provider);
+    if (finishedAt === null) {
+      return latest;
+    }
+    return latest === null || finishedAt > latest ? finishedAt : latest;
+  }, null);
+}
+
+export function getProviderUpdateSidebarPillView(
+  providers: ReadonlyArray<ServerProvider>,
+  options?: ProviderUpdateSidebarPillOptions,
+): ProviderUpdateSidebarPillView | null {
+  const dedupedProviders = dedupeProvidersByDriver(providers);
+  const activeProviders = dedupedProviders.filter(isProviderUpdateActive);
+  if (activeProviders.length > 0) {
+    const activeProvider = activeProviders[0]!;
+    const activeProviderName =
+      PROVIDER_DISPLAY_NAMES[activeProvider.driver] ?? activeProvider.driver;
+    return {
+      key: `loading:${activeProviders
+        .map((provider) => `${provider.driver}:${provider.updateState?.status ?? "idle"}`)
+        .toSorted()
+        .join("|")}`,
+      tone: "loading",
+      title:
+        activeProviders.length === 1
+          ? `Updating ${activeProviderName}`
+          : `Updating ${activeProviders.length} providers`,
+      description:
+        activeProviders.length === 1
+          ? `${formatProviderList(activeProviders)} update in progress.`
+          : `${formatProviderList(activeProviders)} updates are in progress.`,
+    };
+  }
+
+  const recentTerminalProviders = dedupedProviders.filter((provider) =>
+    isRecentTerminalProvider(provider, options?.visibleAfterIso),
+  );
+  const terminalCandidates: ProviderUpdateSidebarPillView[] = [];
+
+  const failedProviders = recentTerminalProviders.filter(
+    (provider) => provider.updateState?.status === "failed",
+  );
+  if (failedProviders.length > 0) {
+    const failedProvider = failedProviders[0]!;
+    terminalCandidates.push({
+      key: `failed:${failedProviders
+        .map(
+          (provider) =>
+            `${provider.driver}:${provider.updateState?.finishedAt ?? "pending"}:${provider.updateState?.message ?? ""}`,
+        )
+        .toSorted()
+        .join("|")}`,
+      tone: "error",
+      title:
+        failedProviders.length === 1
+          ? getProviderFailedUpdateTitle(failedProvider)
+          : `${failedProviders.length} provider updates failed`,
+      description: getFailedProviderUpdateDescription(failedProviders),
+      dismissible: true,
+    });
+  }
+
+  const unchangedProviders = recentTerminalProviders.filter(
+    (provider) => provider.updateState?.status === "unchanged",
+  );
+  if (unchangedProviders.length > 0) {
+    const unchangedProvider = unchangedProviders[0]!;
+    const unchangedProviderName =
+      PROVIDER_DISPLAY_NAMES[unchangedProvider.driver] ?? unchangedProvider.driver;
+    terminalCandidates.push({
+      key: `unchanged:${unchangedProviders
+        .map(
+          (provider) =>
+            `${provider.driver}:${provider.updateState?.finishedAt ?? "pending"}:${provider.updateState?.message ?? ""}`,
+        )
+        .toSorted()
+        .join("|")}`,
+      tone: "warning",
+      title:
+        unchangedProviders.length === 1
+          ? `${unchangedProviderName} still needs an update`
+          : `${unchangedProviders.length} providers still need updates`,
+      description: `${formatProviderList(unchangedProviders)} ${
+        unchangedProviders.length === 1 ? "still appears" : "still appear"
+      } outdated. Review provider settings for details.`,
+      dismissible: true,
+    });
+  }
+
+  const succeededProviders = recentTerminalProviders.filter(
+    (provider) => provider.updateState?.status === "succeeded",
+  );
+  if (succeededProviders.length > 0) {
+    const succeededProvider = succeededProviders[0]!;
+    terminalCandidates.push({
+      key: `succeeded:${succeededProviders
+        .map(
+          (provider) =>
+            `${provider.driver}:${provider.updateState?.finishedAt ?? "pending"}:${provider.updateState?.message ?? ""}`,
+        )
+        .toSorted()
+        .join("|")}`,
+      tone: "success",
+      title:
+        succeededProviders.length === 1
+          ? getProviderUpdatedTitle(succeededProvider)
+          : `${succeededProviders.length} providers updated`,
+      description: getProviderUpdatedDescription(succeededProviders.length),
+      dismissAfterVisibleMs: PROVIDER_UPDATE_SUCCESS_VISIBLE_MS,
+    });
+  }
+
+  return (
+    terminalCandidates
+      .toSorted((left, right) => {
+        const leftProviders =
+          left.tone === "error"
+            ? failedProviders
+            : left.tone === "warning"
+              ? unchangedProviders
+              : succeededProviders;
+        const rightProviders =
+          right.tone === "error"
+            ? failedProviders
+            : right.tone === "warning"
+              ? unchangedProviders
+              : succeededProviders;
+        const leftFinishedAt = latestFinishedAtForProviders(leftProviders) ?? "";
+        const rightFinishedAt = latestFinishedAtForProviders(rightProviders) ?? "";
+        return rightFinishedAt.localeCompare(leftFinishedAt);
+      })
+      .find((candidate) => !options?.dismissedKeys?.has(candidate.key)) ?? null
+  );
+}
+
+function getProviderUpdateInitialToastTitle(
+  providers: ReadonlyArray<ProviderUpdateCandidate>,
+): string {
+  if (providers.length === 1) {
+    const provider = providers[0]!;
+    const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
+    return `Update Available: ${providerName} ${formatVersion(provider.versionAdvisory.latestVersion)}`;
+  }
+  return `Updates Available: ${providers.length} providers`;
+}
+
+function getFailedProviderUpdateDescription(providers: ReadonlyArray<ServerProvider>): string {
+  if (providers.length === 1) {
+    const provider = providers[0]!;
+    if (provider.updateState?.message) {
+      return provider.updateState.message;
+    }
+  }
+  return `${formatProviderList(providers)} failed to update. Check provider settings for details.`;
+}
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.tsx b/apps/web/src/components/ProviderUpdateLaunchNotification.tsx
new file mode 100644
index 00000000000..69cd83bf8dc
--- /dev/null
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.tsx
@@ -0,0 +1,300 @@
+import { useNavigate } from "@tanstack/react-router";
+import { DownloadIcon } from "lucide-react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { type ProviderDriverKind, type ProviderInstanceId } from "@t3tools/contracts";
+
+import { ensureLocalApi } from "../localApi";
+import { useDismissedProviderUpdateNotificationKeys } from "../providerUpdateDismissal";
+import { useServerProviders } from "../rpc/serverState";
+import { PROVIDER_ICON_BY_PROVIDER } from "./chat/providerIconUtils";
+import {
+  canOneClickUpdateProviderCandidate,
+  collectProviderUpdateCandidates,
+  collectUpdatedProviderSnapshots,
+  firstRejectedProviderUpdateMessage,
+  getProviderUpdateInitialToastView,
+  getProviderUpdateProgressToastView,
+  getProviderUpdateRejectedToastView,
+  getProviderUpdateRunningToastView,
+  providerUpdateNotificationKey,
+  type ProviderUpdateToastView,
+} from "./ProviderUpdateLaunchNotification.logic";
+import { stackedThreadToast, toastManager } from "./ui/toast";
+
+const seenProviderUpdateNotificationKeys = new Set<string>();
+type ProviderUpdateToastId = ReturnType<typeof toastManager.add>;
+
+type ActiveProviderUpdateToast =
+  | { readonly kind: "prompt"; readonly key: string; readonly toastId: ProviderUpdateToastId }
+  | {
+      readonly kind: "update";
+      readonly key: string;
+      readonly toastId: ProviderUpdateToastId;
+      readonly providerInstanceIds: ReadonlySet<ProviderInstanceId>;
+      readonly providerCount: number;
+    };
+
+function ProviderUpdateToastIcon({ provider }: { provider: ProviderDriverKind }) {
+  const ProviderIcon = PROVIDER_ICON_BY_PROVIDER[provider];
+
+  if (!ProviderIcon) {
+    return (
+      <span className="relative inline-flex size-4 shrink-0 items-center justify-center">
+        <DownloadIcon aria-hidden="true" className="size-4 text-success" strokeWidth={2.5} />
+      </span>
+    );
+  }
+
+  return (
+    <span className="relative inline-flex size-4 shrink-0 items-center justify-center">
+      <ProviderIcon aria-hidden="true" className="size-4" />
+      <span className="absolute -right-1 -bottom-1 inline-flex size-3 items-center justify-center rounded-full bg-popover">
+        <DownloadIcon aria-hidden="true" className="size-2.5 text-success" strokeWidth={2.5} />
+      </span>
+    </span>
+  );
+}
+
+function updateProviderUpdateToast(input: {
+  readonly toastId: ProviderUpdateToastId;
+  readonly view: ProviderUpdateToastView;
+  readonly openSettings: () => void;
+}) {
+  if (input.view.type === "loading" || input.view.type === "success") {
+    toastManager.update(input.toastId, {
+      type: input.view.type,
+      title: input.view.title,
+      description: input.view.description,
+      timeout: 0,
+      data: {
+        hideCopyButton: true,
+        ...(input.view.dismissAfterVisibleMs !== undefined
+          ? { dismissAfterVisibleMs: input.view.dismissAfterVisibleMs }
+          : {}),
+      },
+    });
+    return;
+  }
+
+  toastManager.update(
+    input.toastId,
+    stackedThreadToast({
+      type: input.view.type,
+      title: input.view.title,
+      description: input.view.description,
+      timeout: 0,
+      actionProps: {
+        children: "Settings",
+        onClick: input.openSettings,
+      },
+      actionVariant: "outline",
+      data: {
+        hideCopyButton: true,
+      },
+    }),
+  );
+}
+
+function isTerminalProviderUpdateToastView(view: ProviderUpdateToastView) {
+  return view.phase === "failed" || view.phase === "unchanged" || view.phase === "succeeded";
+}
+
+export function ProviderUpdateLaunchNotification() {
+  const navigate = useNavigate();
+  const providers = useServerProviders();
+  const activeToastRef = useRef<ActiveProviderUpdateToast | null>(null);
+  const { dismissedNotificationKeys, dismissNotificationKey } =
+    useDismissedProviderUpdateNotificationKeys();
+
+  const updateProviders = useMemo(() => collectProviderUpdateCandidates(providers), [providers]);
+  const notificationKey = useMemo(
+    () => providerUpdateNotificationKey(updateProviders),
+    [updateProviders],
+  );
+  const oneClickProviders = useMemo(
+    () =>
+      updateProviders.filter((provider) => canOneClickUpdateProviderCandidate(provider, providers)),
+    [providers, updateProviders],
+  );
+
+  const openProviderSettings = useCallback(
+    (toastId?: ProviderUpdateToastId) => {
+      const activeToast = activeToastRef.current;
+      if (toastId !== undefined) {
+        toastManager.close(toastId);
+      } else if (activeToast) {
+        toastManager.close(activeToast.toastId);
+      }
+      if (activeToast && (toastId === undefined || activeToast.toastId === toastId)) {
+        activeToastRef.current = null;
+      }
+      void navigate({ to: "/settings/providers" });
+    },
+    [navigate],
+  );
+
+  useEffect(() => {
+    const activeToast = activeToastRef.current;
+    if (activeToast?.kind !== "update") {
+      return;
+    }
+
+    const activeProviders = providers.filter((provider) =>
+      activeToast.providerInstanceIds.has(provider.instanceId),
+    );
+    const view = getProviderUpdateProgressToastView({
+      providers: activeProviders,
+      providerCount: activeToast.providerCount,
+    });
+    updateProviderUpdateToast({
+      toastId: activeToast.toastId,
+      view,
+      openSettings: () => openProviderSettings(activeToast.toastId),
+    });
+
+    if (isTerminalProviderUpdateToastView(view)) {
+      activeToastRef.current = null;
+    }
+  }, [providers, openProviderSettings]);
+
+  useEffect(() => {
+    const activeToast = activeToastRef.current;
+    if (activeToast?.kind === "prompt" && activeToast.key !== notificationKey) {
+      toastManager.close(activeToast.toastId);
+      activeToastRef.current = null;
+    }
+
+    if (
+      !notificationKey ||
+      dismissedNotificationKeys.has(notificationKey) ||
+      seenProviderUpdateNotificationKeys.has(notificationKey) ||
+      activeToastRef.current
+    ) {
+      return;
+    }
+
+    seenProviderUpdateNotificationKeys.add(notificationKey);
+
+    const initialView = getProviderUpdateInitialToastView({ updateProviders, oneClickProviders });
+
+    let toastId!: ProviderUpdateToastId;
+    let updateStarted = false;
+    const openSettings = () => openProviderSettings(toastId);
+    const dismissPrompt = () => {
+      dismissNotificationKey(notificationKey);
+    };
+
+    const runUpdates = () => {
+      if (updateStarted || oneClickProviders.length === 0) {
+        return;
+      }
+      updateStarted = true;
+
+      const providerCount = oneClickProviders.length;
+      const providerInstanceIds = new Set(oneClickProviders.map((provider) => provider.instanceId));
+      activeToastRef.current = {
+        kind: "update",
+        key: notificationKey,
+        toastId,
+        providerInstanceIds,
+        providerCount,
+      };
+
+      updateProviderUpdateToast({
+        toastId,
+        view: getProviderUpdateRunningToastView(providerCount),
+        openSettings,
+      });
+
+      void Promise.allSettled(
+        oneClickProviders.map(async (provider) =>
+          ensureLocalApi().server.updateProvider({
+            provider: provider.driver,
+            instanceId: provider.instanceId,
+          }),
+        ),
+      ).then((results) => {
+        const activeUpdateToast = activeToastRef.current;
+        if (activeUpdateToast?.kind !== "update" || activeUpdateToast.toastId !== toastId) {
+          return;
+        }
+
+        const rejectedMessage = firstRejectedProviderUpdateMessage(results);
+        if (rejectedMessage) {
+          updateProviderUpdateToast({
+            toastId,
+            view: getProviderUpdateRejectedToastView(providerCount, rejectedMessage),
+            openSettings,
+          });
+          activeToastRef.current = null;
+          return;
+        }
+
+        const updatedProviderSnapshots = collectUpdatedProviderSnapshots({
+          results,
+          providerInstanceIds,
+        });
+        const view = getProviderUpdateProgressToastView({
+          providers: updatedProviderSnapshots,
+          providerCount,
+        });
+        updateProviderUpdateToast({
+          toastId,
+          view,
+          openSettings,
+        });
+
+        if (isTerminalProviderUpdateToastView(view)) {
+          activeToastRef.current = null;
+        }
+      });
+    };
+
+    toastId = toastManager.add(
+      stackedThreadToast({
+        type: initialView.type,
+        title: initialView.title,
+        description: initialView.description,
+        timeout: 0,
+        actionProps:
+          oneClickProviders.length > 0
+            ? {
+                children: "Update",
+                onClick: runUpdates,
+              }
+            : {
+                children: "Settings",
+                onClick: openSettings,
+              },
+        actionVariant: oneClickProviders.length > 0 ? "default" : "outline",
+        data: {
+          leadingIcon:
+            updateProviders.length === 1 ? (
+              <ProviderUpdateToastIcon provider={updateProviders[0]!.driver} />
+            ) : undefined,
+          hideCopyButton: true,
+          onClose: dismissPrompt,
+          ...(oneClickProviders.length > 0
+            ? {
+                secondaryActionProps: {
+                  children: "Settings",
+                  onClick: openSettings,
+                },
+                secondaryActionVariant: "outline" as const,
+              }
+            : {}),
+        },
+      }),
+    );
+    activeToastRef.current = { kind: "prompt", key: notificationKey, toastId };
+  }, [
+    dismissNotificationKey,
+    dismissedNotificationKeys,
+    notificationKey,
+    oneClickProviders,
+    openProviderSettings,
+    updateProviders,
+  ]);
+
+  return null;
+}
diff --git a/apps/web/src/components/PullRequestThreadDialog.tsx b/apps/web/src/components/PullRequestThreadDialog.tsx
index 6c134f95a01..7c241afdedb 100644
--- a/apps/web/src/components/PullRequestThreadDialog.tsx
+++ b/apps/web/src/components/PullRequestThreadDialog.tsx
@@ -7,8 +7,10 @@ import {
   gitPreparePullRequestThreadMutationOptions,
   gitResolvePullRequestQueryOptions,
 } from "~/lib/gitReactQuery";
+import { useGitStatus } from "~/lib/gitStatusState";
 import { cn } from "~/lib/utils";
 import { parsePullRequestReference } from "~/pullRequestReference";
+import { getSourceControlPresentation } from "~/sourceControlPresentation";
 import { Button } from "./ui/button";
 import {
   Dialog,
@@ -51,6 +53,13 @@ export function PullRequestThreadDialog({
     { wait: 450 },
     (debouncerState) => ({ isPending: debouncerState.isPending }),
   );
+  const { data: gitStatus = null } = useGitStatus({ environmentId, cwd });
+  const sourceControlPresentation = useMemo(
+    () => getSourceControlPresentation(gitStatus?.sourceControlProvider),
+    [gitStatus?.sourceControlProvider],
+  );
+  const terminology = sourceControlPresentation.terminology;
+  const SourceControlIcon = sourceControlPresentation.Icon;
 
   useEffect(() => {
     if (!open) return;
@@ -161,20 +170,20 @@ export function PullRequestThreadDialog({
   const validationMessage = !referenceDirty
     ? null
     : reference.trim().length === 0
-      ? "Paste a GitHub pull request URL, `gh pr checkout 123`, or enter 123 / #123."
+      ? `Paste a ${terminology.singular} URL, checkout command, or enter 123 / #123.`
       : parsedReference === null
-        ? "Use a GitHub pull request URL, `gh pr checkout 123`, 123, or #123."
+        ? `Use a ${terminology.singular} URL, checkout command, 123, or #123.`
         : null;
   const errorMessage =
     validationMessage ??
     (resolvedPullRequest === null && resolvePullRequestQuery.isError
       ? resolvePullRequestQuery.error instanceof Error
         ? resolvePullRequestQuery.error.message
-        : "Failed to resolve pull request."
+        : `Failed to resolve ${terminology.singular}.`
       : preparePullRequestThreadMutation.error instanceof Error
         ? preparePullRequestThreadMutation.error.message
         : preparePullRequestThreadMutation.error
-          ? "Failed to prepare pull request thread."
+          ? `Failed to prepare ${terminology.singular} thread.`
           : null);
 
   return (
@@ -188,18 +197,23 @@ export function PullRequestThreadDialog({
     >
       <DialogPopup className="max-w-xl">
         <DialogHeader>
-          <DialogTitle>Checkout Pull Request</DialogTitle>
+          <DialogTitle className="flex items-center gap-2">
+            <SourceControlIcon className="size-4" />
+            Checkout {terminology.singular}
+          </DialogTitle>
           <DialogDescription>
-            Resolve a GitHub pull request, then create the draft thread in the main repo or in a
-            dedicated worktree.
+            Resolve a {sourceControlPresentation.providerName} {terminology.singular}, then create
+            the draft thread in the main repo or in a dedicated worktree.
           </DialogDescription>
         </DialogHeader>
         <DialogPanel className="space-y-4">
           <label className="grid gap-1.5">
-            <span className="text-xs font-medium text-foreground">Pull request</span>
+            <span className="text-xs font-medium text-foreground capitalize">
+              {terminology.singular}
+            </span>
             <Input
               ref={referenceInputRef}
-              placeholder="https://github.com/owner/repo/pull/42, gh pr checkout 42, or #42"
+              placeholder={`${terminology.shortLabel} URL, checkout command, or #42`}
               value={reference}
               onChange={(event) => {
                 setReferenceDirty(true);
@@ -237,7 +251,7 @@ export function PullRequestThreadDialog({
           {isResolving ? (
             <div className="flex items-center gap-2 text-muted-foreground text-xs">
               <Spinner className="size-3.5" />
-              Resolving pull request...
+              Resolving {terminology.singular}...
             </div>
           ) : null}
 
diff --git a/apps/web/src/components/RightPanelSheet.tsx b/apps/web/src/components/RightPanelSheet.tsx
new file mode 100644
index 00000000000..ebc4aa0a698
--- /dev/null
+++ b/apps/web/src/components/RightPanelSheet.tsx
@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+
+import { RIGHT_PANEL_SHEET_CLASS_NAME } from "../rightPanelLayout";
+import { Sheet, SheetPopup } from "./ui/sheet";
+
+export function RightPanelSheet(props: {
+  children: ReactNode;
+  open: boolean;
+  onClose: () => void;
+}) {
+  return (
+    <Sheet
+      open={props.open}
+      onOpenChange={(open) => {
+        if (!open) {
+          props.onClose();
+        }
+      }}
+    >
+      <SheetPopup
+        side="right"
+        showCloseButton={false}
+        keepMounted
+        className={RIGHT_PANEL_SHEET_CLASS_NAME}
+      >
+        {props.children}
+      </SheetPopup>
+    </Sheet>
+  );
+}
diff --git a/apps/web/src/components/Sidebar.logic.test.ts b/apps/web/src/components/Sidebar.logic.test.ts
index 35534af9f38..926c117c1c0 100644
--- a/apps/web/src/components/Sidebar.logic.test.ts
+++ b/apps/web/src/components/Sidebar.logic.test.ts
@@ -1,7 +1,9 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ProviderDriverKind } from "@t3tools/contracts";
 
 import {
   createThreadJumpHintVisibilityController,
+  getSidebarThreadIdsToPrewarm,
   getVisibleSidebarThreadIds,
   resolveAdjacentThreadId,
   getFallbackThreadIdAfterDelete,
@@ -19,7 +21,13 @@ import {
   sortProjectsForSidebar,
   THREAD_JUMP_HINT_SHOW_DELAY_MS,
 } from "./Sidebar.logic";
-import { EnvironmentId, OrchestrationLatestTurn, ProjectId, ThreadId } from "@t3tools/contracts";
+import {
+  EnvironmentId,
+  OrchestrationLatestTurn,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+} from "@t3tools/contracts";
 import {
   DEFAULT_INTERACTION_MODE,
   DEFAULT_RUNTIME_MODE,
@@ -121,6 +129,20 @@ describe("createThreadJumpHintVisibilityController", () => {
   });
 });
 
+describe("getSidebarThreadIdsToPrewarm", () => {
+  it("returns only the first visible thread ids up to the prewarm limit", () => {
+    expect(getSidebarThreadIdsToPrewarm(["t1", "t2", "t3"], 2)).toEqual(["t1", "t2"]);
+  });
+
+  it("returns all visible thread ids when they fit within the limit", () => {
+    expect(getSidebarThreadIdsToPrewarm(["t1", "t2"], 10)).toEqual(["t1", "t2"]);
+  });
+
+  it("returns no thread ids when the limit is zero", () => {
+    expect(getSidebarThreadIdsToPrewarm(["t1", "t2"], 0)).toEqual([]);
+  });
+});
+
 describe("shouldClearThreadSelectionOnMouseDown", () => {
   it("preserves selection for thread items", () => {
     const child = {
@@ -169,6 +191,28 @@ describe("resolveSidebarNewThreadEnvMode", () => {
 });
 
 describe("resolveSidebarNewThreadSeedContext", () => {
+  it("prefers the default worktree mode over active thread context", () => {
+    expect(
+      resolveSidebarNewThreadSeedContext({
+        projectId: "project-1",
+        defaultEnvMode: "worktree",
+        activeThread: {
+          projectId: "project-1",
+          branch: "feature/existing",
+          worktreePath: "/repo/.t3/worktrees/existing",
+        },
+        activeDraftThread: {
+          projectId: "project-1",
+          branch: "feature/draft",
+          worktreePath: "/repo/.t3/worktrees/draft",
+          envMode: "worktree",
+        },
+      }),
+    ).toEqual({
+      envMode: "worktree",
+    });
+  });
+
   it("inherits the active server thread context when creating a new thread in the same project", () => {
     expect(
       resolveSidebarNewThreadSeedContext({
@@ -272,6 +316,42 @@ describe("orderItemsByPreferredIds", () => {
       ProjectId.make("project-1"),
     ]);
   });
+
+  it("honors projectOrder physical keys via getProjectOrderKey", async () => {
+    // Regression guard for #1904 / the regression introduced by #2055:
+    // `projectOrder` is populated with physical keys (envId + cwd-derived)
+    // by the store and by drag-end handlers. Readers must identify projects
+    // with the same key format, or manual sort silently snaps back.
+    const { getProjectOrderKey } = await import("../logicalProject");
+    const projects = [
+      {
+        environmentId: EnvironmentId.make("environment-local"),
+        id: ProjectId.make("id-alpha"),
+        cwd: "/work/alpha",
+      },
+      {
+        environmentId: EnvironmentId.make("environment-local"),
+        id: ProjectId.make("id-beta"),
+        cwd: "/work/beta",
+      },
+      {
+        environmentId: EnvironmentId.make("environment-local"),
+        id: ProjectId.make("id-gamma"),
+        cwd: "/work/gamma",
+      },
+    ];
+    const ordered = orderItemsByPreferredIds({
+      items: projects,
+      preferredIds: [getProjectOrderKey(projects[2]!), getProjectOrderKey(projects[0]!)],
+      getId: getProjectOrderKey,
+    });
+
+    expect(ordered.map((project) => project.cwd)).toEqual([
+      "/work/gamma",
+      "/work/alpha",
+      "/work/beta",
+    ]);
+  });
 });
 
 describe("resolveAdjacentThreadId", () => {
@@ -401,7 +481,7 @@ describe("resolveThreadStatusPill", () => {
     latestTurn: null,
     lastVisitedAt: undefined,
     session: {
-      provider: "codex" as const,
+      provider: ProviderDriverKind.make("codex"),
       status: "running" as const,
       createdAt: "2026-03-09T10:00:00.000Z",
       updatedAt: "2026-03-09T10:00:00.000Z",
@@ -625,7 +705,7 @@ function makeProject(overrides: Partial<Project> = {}): Project {
     name: "Project",
     cwd: "/tmp/project",
     defaultModelSelection: {
-      provider: "codex",
+      instanceId: ProviderInstanceId.make("codex"),
       model: "gpt-5.4",
       ...defaultModelSelection,
     },
@@ -644,7 +724,7 @@ function makeThread(overrides: Partial<Thread> = {}): Thread {
     projectId: ProjectId.make("project-1"),
     title: "Thread",
     modelSelection: {
-      provider: "codex",
+      instanceId: ProviderInstanceId.make("codex"),
       model: "gpt-5.4",
       ...overrides?.modelSelection,
     },
diff --git a/apps/web/src/components/Sidebar.logic.ts b/apps/web/src/components/Sidebar.logic.ts
index 8c742cbe9b9..39b759ac313 100644
--- a/apps/web/src/components/Sidebar.logic.ts
+++ b/apps/web/src/components/Sidebar.logic.ts
@@ -12,6 +12,9 @@ import { isLatestTurnSettled } from "../session-logic";
 
 export const THREAD_SELECTION_SAFE_SELECTOR = "[data-thread-item], [data-thread-selection-safe]";
 export const THREAD_JUMP_HINT_SHOW_DELAY_MS = 100;
+// Visible sidebar rows are prewarmed into the thread-detail cache so opening a
+// nearby thread usually reuses an already-hot subscription.
+export const SIDEBAR_THREAD_PREWARM_LIMIT = 10;
 export type SidebarNewThreadEnvMode = "local" | "worktree";
 type SidebarProject = {
   id: string;
@@ -183,6 +186,12 @@ export function resolveSidebarNewThreadSeedContext(input: {
   worktreePath?: string | null;
   envMode: SidebarNewThreadEnvMode;
 } {
+  if (input.defaultEnvMode === "worktree") {
+    return {
+      envMode: "worktree",
+    };
+  }
+
   if (input.activeDraftThread?.projectId === input.projectId) {
     return {
       branch: input.activeDraftThread.branch,
@@ -243,6 +252,13 @@ export function getVisibleSidebarThreadIds<TThreadId>(
   );
 }
 
+export function getSidebarThreadIdsToPrewarm<TThreadId>(
+  visibleThreadIds: readonly TThreadId[],
+  limit = SIDEBAR_THREAD_PREWARM_LIMIT,
+): TThreadId[] {
+  return visibleThreadIds.slice(0, Math.max(0, limit));
+}
+
 export function resolveAdjacentThreadId<T>(input: {
   threadIds: readonly T[];
   currentThreadId: T | null;
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 03ae9790174..e8c5bbe0b11 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -3,15 +3,20 @@ import {
   ArrowUpDownIcon,
   ChevronRightIcon,
   CloudIcon,
-  FolderIcon,
-  GitPullRequestIcon,
-  PlusIcon,
+  FolderPlusIcon,
   SearchIcon,
   SettingsIcon,
   SquarePenIcon,
   TerminalIcon,
   TriangleAlertIcon,
 } from "lucide-react";
+import {
+  ChangeRequestStatusIcon,
+  prStatusIndicator,
+  resolveThreadPr,
+  terminalStatusFromRunningIds,
+  ThreadStatusLabel,
+} from "./ThreadStatusIndicators";
 import { ProjectFavicon } from "./ProjectFavicon";
 import { autoAnimate } from "@formkit/auto-animate";
 import React, { useCallback, useEffect, memo, useMemo, useRef, useState } from "react";
@@ -32,17 +37,16 @@ import { SortableContext, useSortable, verticalListSortingStrategy } from "@dnd-
 import { restrictToFirstScrollableAncestor, restrictToVerticalAxis } from "@dnd-kit/modifiers";
 import { CSS } from "@dnd-kit/utilities";
 import {
-  DEFAULT_MODEL_BY_PROVIDER,
+  type ContextMenuItem,
   type DesktopUpdateState,
-  type EnvironmentId,
   ProjectId,
-  type ScopedProjectRef,
   type ScopedThreadRef,
+  type SidebarProjectGroupingMode,
   type ThreadEnvMode,
   ThreadId,
-  type GitStatusResult,
 } from "@t3tools/contracts";
 import {
+  parseScopedThreadKey,
   scopedProjectKey,
   scopedThreadKey,
   scopeProjectRef,
@@ -50,18 +54,20 @@ import {
 } from "@t3tools/client-runtime";
 import { Link, useLocation, useNavigate, useParams, useRouter } from "@tanstack/react-router";
 import {
+  MAX_SIDEBAR_THREAD_PREVIEW_COUNT,
+  MIN_SIDEBAR_THREAD_PREVIEW_COUNT,
   type SidebarProjectSortOrder,
+  type SidebarThreadPreviewCount,
   type SidebarThreadSortOrder,
 } from "@t3tools/contracts/settings";
 import { usePrimaryEnvironmentId } from "../environments/primary";
 import { isElectron } from "../env";
 import { APP_STAGE_LABEL, APP_VERSION } from "../branding";
 import { isTerminalFocused } from "../lib/terminalFocus";
-import { isLinuxPlatform, isMacPlatform, newCommandId, newProjectId } from "../lib/utils";
+import { isMacPlatform, newCommandId } from "../lib/utils";
 import {
   selectProjectByRef,
   selectProjectsAcrossEnvironments,
-  selectSidebarThreadsForProjectRef,
   selectSidebarThreadsForProjectRefs,
   selectSidebarThreadsAcrossEnvironments,
   selectThreadByRef,
@@ -72,15 +78,18 @@ import { useUiStateStore } from "../uiStateStore";
 import {
   resolveShortcutCommand,
   shortcutLabelForCommand,
-  shouldShowThreadJumpHints,
+  shouldShowThreadJumpHintsForModifiers,
   threadJumpCommandForIndex,
   threadJumpIndexFromCommand,
   threadTraversalDirectionFromCommand,
 } from "../keybindings";
+import { useModelPickerOpen } from "../modelPickerOpenState";
+import { useShortcutModifierState } from "../shortcutModifierState";
 import { useGitStatus } from "../lib/gitStatusState";
 import { readLocalApi } from "../localApi";
 import { useComposerDraftStore } from "../composerDraftStore";
 import { useNewThreadHandler } from "../hooks/useHandleNewThread";
+import { retainThreadDetailSubscription } from "../environments/runtime/service";
 
 import { useThreadActions } from "../hooks/useThreadActions";
 import {
@@ -88,7 +97,7 @@ import {
   resolveThreadRouteRef,
   resolveThreadRouteTarget,
 } from "../threadRoutes";
-import { toastManager } from "./ui/toast";
+import { stackedThreadToast, toastManager } from "./ui/toast";
 import { formatRelativeTimeLabel } from "../timestampFormat";
 import { SettingsSidebarNav } from "./settings/SettingsSidebarNav";
 import { Kbd } from "./ui/kbd";
@@ -103,7 +112,33 @@ import {
 } from "./desktopUpdate.logic";
 import { Alert, AlertAction, AlertDescription, AlertTitle } from "./ui/alert";
 import { Button } from "./ui/button";
-import { Menu, MenuGroup, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuTrigger } from "./ui/menu";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "./ui/dialog";
+import { Input } from "./ui/input";
+import {
+  Menu,
+  MenuGroup,
+  MenuPopup,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuTrigger,
+} from "./ui/menu";
+import {
+  NumberField,
+  NumberFieldDecrement,
+  NumberFieldGroup,
+  NumberFieldIncrement,
+  NumberFieldInput,
+} from "./ui/number-field";
+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "./ui/select";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
 import {
   SidebarContent,
@@ -118,10 +153,12 @@ import {
   SidebarMenuSubItem,
   SidebarSeparator,
   SidebarTrigger,
+  useSidebar,
 } from "./ui/sidebar";
 import { useThreadSelectionStore } from "../threadSelectionStore";
-import { isNonEmpty as isNonEmptyString } from "effect/String";
+import { useCommandPaletteStore } from "../commandPaletteStore";
 import {
+  getSidebarThreadIdsToPrewarm,
   resolveAdjacentThreadId,
   isContextMenuPointerDown,
   resolveProjectStatusIndicator,
@@ -142,13 +179,24 @@ import { CommandDialogTrigger } from "./ui/command";
 import { readEnvironmentApi } from "../environmentApi";
 import { useSettings, useUpdateSettings } from "~/hooks/useSettings";
 import { useServerKeybindings } from "../rpc/serverState";
-import { deriveLogicalProjectKey } from "../logicalProject";
+import {
+  derivePhysicalProjectKey,
+  deriveProjectGroupingOverrideKey,
+  getProjectOrderKey,
+  selectProjectGroupingSettings,
+} from "../logicalProject";
 import {
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
 } from "../environments/runtime";
-import type { Project, SidebarThreadSummary } from "../types";
-const THREAD_PREVIEW_LIMIT = 6;
+import type { SidebarThreadSummary } from "../types";
+import {
+  buildPhysicalToLogicalProjectKeyMap,
+  buildSidebarProjectSnapshots,
+  type SidebarProjectGroupMember,
+  type SidebarProjectSnapshot,
+} from "../sidebarProjectGrouping";
+import { SidebarProviderUpdatePill } from "./sidebar/SidebarProviderUpdatePill";
 const SIDEBAR_SORT_LABELS: Record<SidebarProjectSortOrder, string> = {
   updated_at: "Last user message",
   created_at: "Created at",
@@ -163,23 +211,39 @@ const SIDEBAR_LIST_ANIMATION_OPTIONS = {
   easing: "ease-out",
 } as const;
 const EMPTY_THREAD_JUMP_LABELS = new Map<string, string>();
+const PROJECT_GROUPING_MODE_LABELS: Record<SidebarProjectGroupingMode, string> = {
+  repository: "Group by repository",
+  repository_path: "Group by repository path",
+  separate: "Keep separate",
+};
 
-function threadJumpLabelMapsEqual(
-  left: ReadonlyMap<string, string>,
-  right: ReadonlyMap<string, string>,
-): boolean {
-  if (left === right) {
-    return true;
-  }
-  if (left.size !== right.size) {
-    return false;
+function clampSidebarThreadPreviewCount(value: number): SidebarThreadPreviewCount {
+  return Math.min(
+    MAX_SIDEBAR_THREAD_PREVIEW_COUNT,
+    Math.max(MIN_SIDEBAR_THREAD_PREVIEW_COUNT, value),
+  ) as SidebarThreadPreviewCount;
+}
+
+function formatProjectMemberActionLabel(
+  member: SidebarProjectGroupMember,
+  groupedProjectCount: number,
+): string {
+  if (groupedProjectCount <= 1) {
+    return member.name;
   }
-  for (const [key, value] of left) {
-    if (right.get(key) !== value) {
-      return false;
-    }
+
+  return member.environmentLabel ? `${member.environmentLabel} — ${member.cwd}` : member.cwd;
+}
+
+function projectGroupingModeDescription(mode: SidebarProjectGroupingMode): string {
+  switch (mode) {
+    case "repository":
+      return "Projects from the same repository share one sidebar row.";
+    case "repository_path":
+      return "Projects group only when both the repository and repo-relative path match.";
+    case "separate":
+      return "Every project path gets its own sidebar row.";
   }
-  return true;
 }
 
 function buildThreadJumpLabelMap(input: {
@@ -212,122 +276,6 @@ function buildThreadJumpLabelMap(input: {
   return mapping.size > 0 ? mapping : EMPTY_THREAD_JUMP_LABELS;
 }
 
-type EnvironmentPresence = "local-only" | "remote-only" | "mixed";
-
-type SidebarProjectSnapshot = Project & {
-  projectKey: string;
-  environmentPresence: EnvironmentPresence;
-  memberProjectRefs: readonly ScopedProjectRef[];
-  /** Labels for remote environments this project lives in. */
-  remoteEnvironmentLabels: readonly string[];
-};
-interface TerminalStatusIndicator {
-  label: "Terminal process running";
-  colorClass: string;
-  pulse: boolean;
-}
-
-interface PrStatusIndicator {
-  label: "PR open" | "PR closed" | "PR merged";
-  colorClass: string;
-  tooltip: string;
-  url: string;
-}
-
-type ThreadPr = GitStatusResult["pr"];
-
-function ThreadStatusLabel({
-  status,
-  compact = false,
-}: {
-  status: ThreadStatusPill;
-  compact?: boolean;
-}) {
-  if (compact) {
-    return (
-      <span
-        title={status.label}
-        className={`inline-flex size-3.5 shrink-0 items-center justify-center ${status.colorClass}`}
-      >
-        <span
-          className={`size-[9px] rounded-full ${status.dotClass} ${
-            status.pulse ? "animate-pulse" : ""
-          }`}
-        />
-        <span className="sr-only">{status.label}</span>
-      </span>
-    );
-  }
-
-  return (
-    <span
-      title={status.label}
-      className={`inline-flex items-center gap-1 text-[10px] ${status.colorClass}`}
-    >
-      <span
-        className={`h-1.5 w-1.5 rounded-full ${status.dotClass} ${
-          status.pulse ? "animate-pulse" : ""
-        }`}
-      />
-      <span className="hidden md:inline">{status.label}</span>
-    </span>
-  );
-}
-
-function terminalStatusFromRunningIds(
-  runningTerminalIds: string[],
-): TerminalStatusIndicator | null {
-  if (runningTerminalIds.length === 0) {
-    return null;
-  }
-  return {
-    label: "Terminal process running",
-    colorClass: "text-teal-600 dark:text-teal-300/90",
-    pulse: true,
-  };
-}
-
-function prStatusIndicator(pr: ThreadPr): PrStatusIndicator | null {
-  if (!pr) return null;
-
-  if (pr.state === "open") {
-    return {
-      label: "PR open",
-      colorClass: "text-emerald-600 dark:text-emerald-300/90",
-      tooltip: `#${pr.number} PR open: ${pr.title}`,
-      url: pr.url,
-    };
-  }
-  if (pr.state === "closed") {
-    return {
-      label: "PR closed",
-      colorClass: "text-zinc-500 dark:text-zinc-400/80",
-      tooltip: `#${pr.number} PR closed: ${pr.title}`,
-      url: pr.url,
-    };
-  }
-  if (pr.state === "merged") {
-    return {
-      label: "PR merged",
-      colorClass: "text-violet-600 dark:text-violet-300/90",
-      tooltip: `#${pr.number} PR merged: ${pr.title}`,
-      url: pr.url,
-    };
-  }
-  return null;
-}
-
-function resolveThreadPr(
-  threadBranch: string | null,
-  gitStatus: GitStatusResult | null,
-): ThreadPr | null {
-  if (threadBranch === null || gitStatus === null || gitStatus.branch !== threadBranch) {
-    return null;
-  }
-
-  return gitStatus.pr ?? null;
-}
-
 interface SidebarThreadRowProps {
   thread: SidebarThreadSummary;
   projectCwd: string | null;
@@ -394,7 +342,6 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
   const threadKey = scopedThreadKey(threadRef);
   const lastVisitedAt = useUiStateStore((state) => state.threadLastVisitedAtById[threadKey]);
   const isSelected = useThreadSelectionStore((state) => state.selectedThreadKeys.has(threadKey));
-  const hasSelection = useThreadSelectionStore((state) => state.selectedThreadKeys.size > 0);
   const runningTerminalIds = useTerminalStateStore(
     (state) =>
       selectThreadTerminalState(state.terminalStateByThreadKey, threadRef).runningTerminalIds,
@@ -437,13 +384,13 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
     },
   });
   const pr = resolveThreadPr(thread.branch, gitStatus.data);
-  const prStatus = prStatusIndicator(pr);
+  const prStatus = prStatusIndicator(pr, gitStatus.data?.sourceControlProvider);
   const terminalStatus = terminalStatusFromRunningIds(runningTerminalIds);
   const isConfirmingArchive = confirmingArchiveThreadKey === threadKey && !isThreadRunning;
   const threadMetaClassName = isConfirmingArchive
     ? "pointer-events-none opacity-0"
     : !isThreadRunning
-      ? "pointer-events-none transition-opacity duration-150 group-hover/menu-sub-item:opacity-0 group-focus-within/menu-sub-item:opacity-0"
+      ? "pointer-events-none transition-opacity duration-150 max-sm:pr-6 group-hover/menu-sub-item:opacity-0 group-focus-within/menu-sub-item:opacity-0"
       : "pointer-events-none";
   const clearConfirmingArchive = useCallback(() => {
     setConfirmingArchiveThreadKey((current) => (current === threadKey ? null : current));
@@ -480,6 +427,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
   const handleRowContextMenu = useCallback(
     (event: React.MouseEvent) => {
       event.preventDefault();
+      const hasSelection = useThreadSelectionStore.getState().hasSelection();
       if (hasSelection && isSelected) {
         void handleMultiSelectContextMenu({
           x: event.clientX,
@@ -496,14 +444,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
         y: event.clientY,
       });
     },
-    [
-      clearSelection,
-      handleMultiSelectContextMenu,
-      handleThreadContextMenu,
-      hasSelection,
-      isSelected,
-      threadRef,
-    ],
+    [clearSelection, handleMultiSelectContextMenu, handleThreadContextMenu, isSelected, threadRef],
   );
   const handlePrClick = useCallback(
     (event: React.MouseEvent<HTMLButtonElement>) => {
@@ -628,7 +569,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
                     className={`inline-flex items-center justify-center ${prStatus.colorClass} cursor-pointer rounded-sm outline-hidden focus-visible:ring-1 focus-visible:ring-ring`}
                     onClick={handlePrClick}
                   >
-                    <GitPullRequestIcon className="size-3" />
+                    <ChangeRequestStatusIcon className="size-3" />
                   </button>
                 }
               />
@@ -639,7 +580,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
           {renamingThreadKey === threadKey ? (
             <input
               ref={handleRenameInputRef}
-              className="min-w-0 flex-1 truncate text-xs bg-transparent outline-none border border-ring rounded px-0.5"
+              className="min-w-0 flex-1 truncate text-base sm:text-xs bg-transparent outline-none border border-ring rounded px-0.5"
               value={renamingTitle}
               onChange={handleRenameInputChange}
               onKeyDown={handleRenameInputKeyDown}
@@ -647,7 +588,21 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
               onClick={handleRenameInputClick}
             />
           ) : (
-            <span className="min-w-0 flex-1 truncate text-xs">{thread.title}</span>
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <span
+                    className="min-w-0 flex-1 truncate text-xs"
+                    data-testid={`thread-title-${thread.id}`}
+                  >
+                    {thread.title}
+                  </span>
+                }
+              />
+              <TooltipPopup side="top" className="max-w-80 whitespace-normal leading-tight">
+                {thread.title}
+              </TooltipPopup>
+            </Tooltip>
           )}
         </div>
         <div className="ml-auto flex shrink-0 items-center gap-1.5">
@@ -661,7 +616,11 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
               <TerminalIcon className={`size-3 ${terminalStatus.pulse ? "animate-pulse" : ""}`} />
             </span>
           )}
-          <div className="flex min-w-12 justify-end">
+          <div
+            className={`flex min-w-12 justify-end ${
+              isRemoteThread ? "max-sm:min-w-24" : "max-sm:min-w-20"
+            }`}
+          >
             {isConfirmingArchive ? (
               <button
                 ref={handleConfirmArchiveRef}
@@ -677,13 +636,13 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
               </button>
             ) : !isThreadRunning ? (
               appSettingsConfirmThreadArchive ? (
-                <div className="pointer-events-none absolute top-1/2 right-1 -translate-y-1/2 opacity-0 transition-opacity duration-150 group-hover/menu-sub-item:pointer-events-auto group-hover/menu-sub-item:opacity-100 group-focus-within/menu-sub-item:pointer-events-auto group-focus-within/menu-sub-item:opacity-100">
+                <div className="pointer-events-none absolute top-1/2 right-1 -translate-y-1/2 opacity-0 transition-opacity duration-150 max-sm:pointer-events-auto max-sm:opacity-100 group-hover/menu-sub-item:pointer-events-auto group-hover/menu-sub-item:opacity-100 group-focus-within/menu-sub-item:pointer-events-auto group-focus-within/menu-sub-item:opacity-100">
                   <button
                     type="button"
                     data-thread-selection-safe
                     data-testid={`thread-archive-${thread.id}`}
                     aria-label={`Archive ${thread.title}`}
-                    className="inline-flex size-5 cursor-pointer items-center justify-center text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+                    className="inline-flex size-5 cursor-pointer items-center justify-center text-muted-foreground/60 transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
                     onPointerDown={stopPropagationOnPointerDown}
                     onClick={handleStartArchiveConfirmation}
                   >
@@ -694,13 +653,13 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
                 <Tooltip>
                   <TooltipTrigger
                     render={
-                      <div className="pointer-events-none absolute top-1/2 right-1 -translate-y-1/2 opacity-0 transition-opacity duration-150 group-hover/menu-sub-item:pointer-events-auto group-hover/menu-sub-item:opacity-100 group-focus-within/menu-sub-item:pointer-events-auto group-focus-within/menu-sub-item:opacity-100">
+                      <div className="pointer-events-none absolute top-1/2 right-1 -translate-y-1/2 opacity-0 transition-opacity duration-150 max-sm:pointer-events-auto max-sm:opacity-100 group-hover/menu-sub-item:pointer-events-auto group-hover/menu-sub-item:opacity-100 group-focus-within/menu-sub-item:pointer-events-auto group-focus-within/menu-sub-item:opacity-100">
                         <button
                           type="button"
                           data-thread-selection-safe
                           data-testid={`thread-archive-${thread.id}`}
                           aria-label={`Archive ${thread.title}`}
-                          className="inline-flex size-5 cursor-pointer items-center justify-center text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+                          className="inline-flex size-5 cursor-pointer items-center justify-center text-muted-foreground/60 transition-colors hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
                           onPointerDown={stopPropagationOnPointerDown}
                           onClick={handleArchiveImmediateClick}
                         >
@@ -721,11 +680,11 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
                       render={
                         <span
                           aria-label={threadEnvironmentLabel ?? "Remote"}
-                          className="inline-flex items-center justify-center"
+                          className="inline-flex h-5 items-center justify-center"
                         />
                       }
                     >
-                      <CloudIcon className="size-3 text-muted-foreground/40" />
+                      <CloudIcon className="block size-3 text-muted-foreground/60" />
                     </TooltipTrigger>
                     <TooltipPopup side="top">{threadEnvironmentLabel}</TooltipPopup>
                   </Tooltip>
@@ -745,7 +704,9 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThreadRowP
                         : "text-muted-foreground/40"
                     }`}
                   >
-                    {formatRelativeTimeLabel(thread.updatedAt ?? thread.createdAt)}
+                    {formatRelativeTimeLabel(
+                      thread.latestUserMessageAt ?? thread.updatedAt ?? thread.createdAt,
+                    )}
                   </span>
                 )}
               </span>
@@ -980,7 +941,13 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   const defaultThreadEnvMode = useSettings<ThreadEnvMode>(
     (settings) => settings.defaultThreadEnvMode,
   );
+  const projectGroupingSettings = useSettings(selectProjectGroupingSettings);
+  const { updateSettings } = useUpdateSettings();
+  const sidebarThreadPreviewCount = useSettings<SidebarThreadPreviewCount>(
+    (settings) => settings.sidebarThreadPreviewCount,
+  );
   const router = useRouter();
+  const { isMobile, setOpenMobile } = useSidebar();
   const markThreadUnread = useUiStateStore((state) => state.markThreadUnread);
   const toggleProject = useUiStateStore((state) => state.toggleProject);
   const toggleThreadSelection = useThreadSelectionStore((state) => state.toggleThread);
@@ -988,14 +955,6 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   const clearSelection = useThreadSelectionStore((state) => state.clearSelection);
   const removeFromSelection = useThreadSelectionStore((state) => state.removeFromSelection);
   const setSelectionAnchor = useThreadSelectionStore((state) => state.setAnchor);
-  const selectedThreadCount = useThreadSelectionStore((state) => state.selectedThreadKeys.size);
-  const clearComposerDraftForThread = useComposerDraftStore((state) => state.clearDraftThread);
-  const getDraftThreadByProjectRef = useComposerDraftStore(
-    (state) => state.getDraftThreadByProjectRef,
-  );
-  const clearProjectDraftThreadId = useComposerDraftStore(
-    (state) => state.clearProjectDraftThreadId,
-  );
   const { copyToClipboard: copyThreadIdToClipboard } = useCopyToClipboard<{
     threadId: ThreadId;
   }>({
@@ -1007,11 +966,13 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       });
     },
     onError: (error) => {
-      toastManager.add({
-        type: "error",
-        title: "Failed to copy thread ID",
-        description: error instanceof Error ? error.message : "An error occurred.",
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Failed to copy thread ID",
+          description: error instanceof Error ? error.message : "An error occurred.",
+        }),
+      );
     },
   });
   const { copyToClipboard: copyPathToClipboard } = useCopyToClipboard<{
@@ -1025,11 +986,13 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       });
     },
     onError: (error) => {
-      toastManager.add({
-        type: "error",
-        title: "Failed to copy path",
-        description: error instanceof Error ? error.message : "An error occurred.",
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Failed to copy path",
+          description: error instanceof Error ? error.message : "An error occurred.",
+        }),
+      );
     },
   });
   const openPrLink = useCallback((event: React.MouseEvent<HTMLElement>, prUrl: string) => {
@@ -1046,64 +1009,40 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     }
 
     void api.shell.openExternal(prUrl).catch((error) => {
-      toastManager.add({
-        type: "error",
-        title: "Unable to open PR link",
-        description: error instanceof Error ? error.message : "An error occurred.",
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Unable to open pull request link",
+          description: error instanceof Error ? error.message : "An error occurred.",
+        }),
+      );
     });
   }, []);
   const sidebarThreads = useStore(
     useShallow(
       useMemo(
         () => (state: import("../store").AppState) =>
-          selectSidebarThreadsForProjectRef(
-            state,
-            scopeProjectRef(project.environmentId, project.id),
-          ),
-        [project.environmentId, project.id],
-      ),
-    ),
-  );
-  // For grouped projects that span multiple environments, also fetch
-  // threads from the other member project refs.
-  const otherMemberRefs = useMemo(
-    () =>
-      project.memberProjectRefs.filter(
-        (ref) => ref.environmentId !== project.environmentId || ref.projectId !== project.id,
-      ),
-    [project.memberProjectRefs, project.environmentId, project.id],
-  );
-  const otherMemberThreads = useStore(
-    useShallow(
-      useMemo(
-        () =>
-          otherMemberRefs.length === 0
-            ? () => [] as SidebarThreadSummary[]
-            : (state: import("../store").AppState) =>
-                selectSidebarThreadsForProjectRefs(state, otherMemberRefs),
-        [otherMemberRefs],
+          selectSidebarThreadsForProjectRefs(state, project.memberProjectRefs),
+        [project.memberProjectRefs],
       ),
     ),
   );
-  const allSidebarThreads = useMemo(
-    () =>
-      otherMemberThreads.length === 0 ? sidebarThreads : [...sidebarThreads, ...otherMemberThreads],
-    [sidebarThreads, otherMemberThreads],
-  );
   const sidebarThreadByKey = useMemo(
     () =>
       new Map(
-        allSidebarThreads.map(
+        sidebarThreads.map(
           (thread) =>
             [scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)), thread] as const,
         ),
       ),
-    [allSidebarThreads],
+    [sidebarThreads],
   );
-  // All threads from the representative + other member environments are
-  // already fetched into allSidebarThreads, so we can use them directly.
-  const projectThreads = allSidebarThreads;
+  // Keep a ref so callbacks can read the latest map without appearing in
+  // dependency arrays (avoids invalidating every thread-row memo on each
+  // thread-list change).
+  const sidebarThreadByKeyRef = useRef(sidebarThreadByKey);
+  sidebarThreadByKeyRef.current = sidebarThreadByKey;
+  const projectThreads = sidebarThreads;
   const projectExpanded = useUiStateStore(
     (state) => state.projectExpandedById[project.projectKey] ?? true,
   );
@@ -1120,9 +1059,43 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   const [renamingThreadKey, setRenamingThreadKey] = useState<string | null>(null);
   const [renamingTitle, setRenamingTitle] = useState("");
   const [confirmingArchiveThreadKey, setConfirmingArchiveThreadKey] = useState<string | null>(null);
+  const [projectRenameTarget, setProjectRenameTarget] = useState<SidebarProjectGroupMember | null>(
+    null,
+  );
+  const [projectRenameTitle, setProjectRenameTitle] = useState("");
+  const [projectGroupingTarget, setProjectGroupingTarget] =
+    useState<SidebarProjectGroupMember | null>(null);
+  const [projectGroupingSelection, setProjectGroupingSelection] = useState<
+    SidebarProjectGroupingMode | "inherit"
+  >("inherit");
   const renamingCommittedRef = useRef(false);
   const renamingInputRef = useRef<HTMLInputElement | null>(null);
   const confirmArchiveButtonRefs = useRef(new Map<string, HTMLButtonElement>());
+  const memberProjectByScopedKey = useMemo(
+    () =>
+      new Map(
+        project.memberProjects.map((member) => [
+          scopedProjectKey(scopeProjectRef(member.environmentId, member.id)),
+          member,
+        ]),
+      ),
+    [project.memberProjects],
+  );
+  const memberThreadCountByPhysicalKey = useMemo(() => {
+    const counts = new Map<string, number>(
+      project.memberProjects.map((member) => [member.physicalProjectKey, 0] as const),
+    );
+    for (const thread of projectThreads) {
+      const member = memberProjectByScopedKey.get(
+        scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId)),
+      );
+      if (!member) {
+        continue;
+      }
+      counts.set(member.physicalProjectKey, (counts.get(member.physicalProjectKey) ?? 0) + 1);
+    }
+    return counts;
+  }, [memberProjectByScopedKey, project.memberProjects, projectThreads]);
 
   const { projectStatus, visibleProjectThreads, orderedProjectThreadKeys } = useMemo(() => {
     const lastVisitedAtByThreadKey = new Map(
@@ -1195,11 +1168,11 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         },
       });
     };
-    const hasOverflowingThreads = visibleProjectThreads.length > THREAD_PREVIEW_LIMIT;
+    const hasOverflowingThreads = visibleProjectThreads.length > sidebarThreadPreviewCount;
     const previewThreads =
       isThreadListExpanded || !hasOverflowingThreads
         ? visibleProjectThreads
-        : visibleProjectThreads.slice(0, THREAD_PREVIEW_LIMIT);
+        : visibleProjectThreads.slice(0, sidebarThreadPreviewCount);
     const visibleThreadKeys = new Set(
       [...previewThreads, ...(pinnedCollapsedThread ? [pinnedCollapsedThread] : [])].map((thread) =>
         scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
@@ -1228,6 +1201,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     pinnedCollapsedThread,
     projectExpanded,
     projectThreads,
+    sidebarThreadPreviewCount,
     threadLastVisitedAts,
     visibleProjectThreads,
   ]);
@@ -1251,7 +1225,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         event.stopPropagation();
         return;
       }
-      if (selectedThreadCount > 0) {
+      if (useThreadSelectionStore.getState().hasSelection()) {
         clearSelection();
       }
       toggleProject(project.projectKey);
@@ -1260,7 +1234,6 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       clearSelection,
       dragInProgressRef,
       project.projectKey,
-      selectedThreadCount,
       suppressProjectClickAfterDragRef,
       suppressProjectClickForContextMenuRef,
       toggleProject,
@@ -1297,6 +1270,159 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
     [suppressProjectClickAfterDragRef, suppressProjectClickForContextMenuRef],
   );
 
+  const openProjectRenameDialog = useCallback((member: SidebarProjectGroupMember) => {
+    setProjectRenameTarget(member);
+    setProjectRenameTitle(member.name);
+  }, []);
+
+  const openProjectGroupingDialog = useCallback(
+    (member: SidebarProjectGroupMember) => {
+      const overrideKey = deriveProjectGroupingOverrideKey(member);
+      setProjectGroupingTarget(member);
+      setProjectGroupingSelection(
+        projectGroupingSettings.sidebarProjectGroupingOverrides?.[overrideKey] ?? "inherit",
+      );
+    },
+    [projectGroupingSettings.sidebarProjectGroupingOverrides],
+  );
+
+  const removeProject = useCallback(
+    async (member: SidebarProjectGroupMember, options: { force?: boolean } = {}): Promise<void> => {
+      const memberProjectRef = scopeProjectRef(member.environmentId, member.id);
+      const draftStore = useComposerDraftStore.getState();
+      const projectDraftThread = draftStore.getDraftThreadByProjectRef(memberProjectRef);
+      if (projectDraftThread) {
+        draftStore.clearDraftThread(projectDraftThread.draftId);
+      }
+      draftStore.clearProjectDraftThreadId(memberProjectRef);
+
+      const projectApi = readEnvironmentApi(member.environmentId);
+      if (!projectApi) {
+        throw new Error("Project API unavailable.");
+      }
+
+      await projectApi.orchestration.dispatchCommand({
+        type: "project.delete",
+        commandId: newCommandId(),
+        projectId: member.id,
+        ...(options.force === true ? { force: true } : {}),
+      });
+    },
+    [],
+  );
+
+  const handleRemoveProject = useCallback(
+    async (member: SidebarProjectGroupMember) => {
+      const api = readLocalApi();
+      if (!api) {
+        return;
+      }
+
+      const memberProjectRef = scopeProjectRef(member.environmentId, member.id);
+      const memberThreadCount = memberThreadCountByPhysicalKey.get(member.physicalProjectKey) ?? 0;
+      if (memberThreadCount > 0) {
+        const warningToastId = toastManager.add(
+          stackedThreadToast({
+            type: "warning",
+            title: "Project is not empty",
+            description: "Delete all threads in this project before removing it.",
+            actionVariant: "destructive",
+            actionProps: {
+              children: "Delete anyway",
+              onClick: () => {
+                void (async () => {
+                  toastManager.close(warningToastId);
+                  await new Promise<void>((resolve) => {
+                    window.setTimeout(resolve, 180);
+                  });
+
+                  const latestProjectThreads = selectSidebarThreadsForProjectRefs(
+                    useStore.getState(),
+                    [memberProjectRef],
+                  );
+                  const confirmed = await api.dialogs.confirm(
+                    latestProjectThreads.length > 0
+                      ? [
+                          `Remove project "${member.name}" and delete its ${latestProjectThreads.length} thread${
+                            latestProjectThreads.length === 1 ? "" : "s"
+                          }?`,
+                          `Path: ${member.cwd}`,
+                          ...(member.environmentLabel
+                            ? [`Environment: ${member.environmentLabel}`]
+                            : []),
+                          "This permanently clears conversation history for those threads.",
+                          "This removes only this project entry.",
+                          "This action cannot be undone.",
+                        ].join("\n")
+                      : [
+                          `Remove project "${member.name}"?`,
+                          `Path: ${member.cwd}`,
+                          ...(member.environmentLabel
+                            ? [`Environment: ${member.environmentLabel}`]
+                            : []),
+                          "This removes only this project entry.",
+                        ].join("\n"),
+                  );
+                  if (!confirmed) {
+                    return;
+                  }
+
+                  await removeProject(member, { force: true });
+                })().catch((error) => {
+                  const message =
+                    error instanceof Error ? error.message : "Unknown error removing project.";
+                  console.error("Failed to remove project", {
+                    projectId: member.id,
+                    environmentId: member.environmentId,
+                    error,
+                  });
+                  toastManager.add(
+                    stackedThreadToast({
+                      type: "error",
+                      title: `Failed to remove "${member.name}"`,
+                      description: message,
+                    }),
+                  );
+                });
+              },
+            },
+          }),
+        );
+        return;
+      }
+
+      const message = [
+        `Remove project "${member.name}"?`,
+        `Path: ${member.cwd}`,
+        ...(member.environmentLabel ? [`Environment: ${member.environmentLabel}`] : []),
+        "This removes only this project entry.",
+      ].join("\n");
+      const confirmed = await api.dialogs.confirm(message);
+      if (!confirmed) {
+        return;
+      }
+
+      try {
+        await removeProject(member);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error removing project.";
+        console.error("Failed to remove project", {
+          projectId: member.id,
+          environmentId: member.environmentId,
+          error,
+        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: `Failed to remove "${member.name}"`,
+            description: message,
+          }),
+        );
+      }
+    },
+    [memberThreadCountByPhysicalKey, removeProject],
+  );
+
   const handleProjectButtonContextMenu = useCallback(
     (event: React.MouseEvent<HTMLButtonElement>) => {
       event.preventDefault();
@@ -1305,73 +1431,100 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         const api = readLocalApi();
         if (!api) return;
 
+        const actionHandlers = new Map<string, () => Promise<void> | void>();
+        const makeLeaf = (
+          action: "rename" | "grouping" | "copy-path" | "delete",
+          member: SidebarProjectGroupMember,
+          options?: {
+            destructive?: boolean;
+            disabled?: boolean;
+          },
+        ): ContextMenuItem<string> => {
+          const id = `${action}:${member.physicalProjectKey}`;
+          actionHandlers.set(id, () => {
+            switch (action) {
+              case "rename":
+                openProjectRenameDialog(member);
+                return;
+              case "grouping":
+                openProjectGroupingDialog(member);
+                return;
+              case "copy-path":
+                copyPathToClipboard(member.cwd, { path: member.cwd });
+                return;
+              case "delete":
+                return handleRemoveProject(member);
+            }
+          });
+
+          return {
+            id,
+            label: formatProjectMemberActionLabel(member, project.groupedProjectCount),
+            ...(options?.destructive ? { destructive: true } : {}),
+            ...(options?.disabled ? { disabled: true } : {}),
+          };
+        };
+
+        const buildTargetedItem = (
+          action: "rename" | "grouping" | "copy-path" | "delete",
+          label: string,
+          options?: {
+            destructive?: boolean;
+            isDisabled?: (member: SidebarProjectGroupMember) => boolean;
+          },
+        ): ContextMenuItem<string> => {
+          if (project.memberProjects.length === 1) {
+            const singleMember = project.memberProjects[0]!;
+            return {
+              ...makeLeaf(action, singleMember, {
+                ...(options?.destructive ? { destructive: true } : {}),
+                ...(options?.isDisabled?.(singleMember) ? { disabled: true } : {}),
+              }),
+              label,
+            };
+          }
+
+          return {
+            id: `${action}:submenu`,
+            label,
+            children: project.memberProjects.map((member) =>
+              makeLeaf(action, member, {
+                ...(options?.destructive ? { destructive: true } : {}),
+                ...(options?.isDisabled?.(member) ? { disabled: true } : {}),
+              }),
+            ),
+          };
+        };
+
         const clicked = await api.contextMenu.show(
           [
-            { id: "copy-path", label: "Copy Project Path" },
-            { id: "delete", label: "Remove project", destructive: true },
+            buildTargetedItem("rename", "Rename project"),
+            buildTargetedItem("grouping", "Project grouping…"),
+            buildTargetedItem("copy-path", "Copy Project Path"),
+            buildTargetedItem("delete", "Remove project", {
+              destructive: true,
+            }),
           ],
           {
             x: event.clientX,
             y: event.clientY,
           },
         );
-        if (clicked === "copy-path") {
-          copyPathToClipboard(project.cwd, { path: project.cwd });
-          return;
-        }
-        if (clicked !== "delete") return;
 
-        if (projectThreads.length > 0) {
-          toastManager.add({
-            type: "warning",
-            title: "Project is not empty",
-            description: "Delete all threads in this project before removing it.",
-          });
+        if (!clicked) {
           return;
         }
 
-        const confirmed = await api.dialogs.confirm(`Remove project "${project.name}"?`);
-        if (!confirmed) return;
-
-        try {
-          const projectDraftThread = getDraftThreadByProjectRef(
-            scopeProjectRef(project.environmentId, project.id),
-          );
-          if (projectDraftThread) {
-            clearComposerDraftForThread(projectDraftThread.draftId);
-          }
-          clearProjectDraftThreadId(scopeProjectRef(project.environmentId, project.id));
-          const projectApi = readEnvironmentApi(project.environmentId);
-          if (!projectApi) {
-            throw new Error("Project API unavailable.");
-          }
-          await projectApi.orchestration.dispatchCommand({
-            type: "project.delete",
-            commandId: newCommandId(),
-            projectId: project.id,
-          });
-        } catch (error) {
-          const message =
-            error instanceof Error ? error.message : "Unknown error removing project.";
-          console.error("Failed to remove project", { projectId: project.id, error });
-          toastManager.add({
-            type: "error",
-            title: `Failed to remove "${project.name}"`,
-            description: message,
-          });
-        }
+        await actionHandlers.get(clicked)?.();
       })();
     },
     [
-      clearComposerDraftForThread,
-      clearProjectDraftThreadId,
       copyPathToClipboard,
-      getDraftThreadByProjectRef,
-      project.cwd,
-      project.environmentId,
-      project.id,
-      project.name,
-      projectThreads.length,
+      handleRemoveProject,
+      openProjectGroupingDialog,
+      openProjectRenameDialog,
+      project.groupedProjectCount,
+      project.memberProjects,
       suppressProjectClickForContextMenuRef,
     ],
   );
@@ -1382,12 +1535,15 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         clearSelection();
       }
       setSelectionAnchor(scopedThreadKey(threadRef));
+      if (isMobile) {
+        setOpenMobile(false);
+      }
       void router.navigate({
         to: "/$environmentId/$threadId",
         params: buildThreadRouteParams(threadRef),
       });
     },
-    [clearSelection, router, setSelectionAnchor],
+    [clearSelection, isMobile, router, setOpenMobile, setSelectionAnchor],
   );
 
   const handleThreadClick = useCallback(
@@ -1418,12 +1574,23 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         clearSelection();
       }
       setSelectionAnchor(threadKey);
+      if (isMobile) {
+        setOpenMobile(false);
+      }
       void router.navigate({
         to: "/$environmentId/$threadId",
         params: buildThreadRouteParams(threadRef),
       });
     },
-    [clearSelection, rangeSelectTo, router, setSelectionAnchor, toggleThreadSelection],
+    [
+      clearSelection,
+      isMobile,
+      rangeSelectTo,
+      router,
+      setOpenMobile,
+      setSelectionAnchor,
+      toggleThreadSelection,
+    ],
   );
 
   const handleMultiSelectContextMenu = useCallback(
@@ -1444,7 +1611,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
 
       if (clicked === "mark-unread") {
         for (const threadKey of threadKeys) {
-          const thread = sidebarThreadByKey.get(threadKey);
+          const thread = sidebarThreadByKeyRef.current.get(threadKey);
           markThreadUnread(threadKey, thread?.latestTurn?.completedAt);
         }
         clearSelection();
@@ -1465,7 +1632,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
 
       const deletedThreadKeys = new Set(threadKeys);
       for (const threadKey of threadKeys) {
-        const thread = sidebarThreadByKey.get(threadKey);
+        const thread = sidebarThreadByKeyRef.current.get(threadKey);
         if (!thread) continue;
         await deleteThread(scopeThreadRef(thread.environmentId, thread.id), {
           deletedThreadKeys,
@@ -1479,14 +1646,11 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       deleteThread,
       markThreadUnread,
       removeFromSelection,
-      sidebarThreadByKey,
     ],
   );
 
-  const handleCreateThreadClick = useCallback(
-    (event: React.MouseEvent<HTMLButtonElement>) => {
-      event.preventDefault();
-      event.stopPropagation();
+  const createThreadForProjectMember = useCallback(
+    (member: SidebarProjectGroupMember) => {
       const currentRouteParams =
         router.state.matches[router.state.matches.length - 1]?.params ?? {};
       const currentRouteTarget = resolveThreadRouteTarget(currentRouteParams);
@@ -1502,12 +1666,12 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
             ? (draftStore.getDraftSession(currentRouteTarget.draftId) ?? null)
             : null;
       const seedContext = resolveSidebarNewThreadSeedContext({
-        projectId: project.id,
+        projectId: member.id,
         defaultEnvMode: resolveSidebarNewThreadEnvMode({
           defaultEnvMode: defaultThreadEnvMode,
         }),
         activeThread:
-          currentActiveThread && currentActiveThread.projectId === project.id
+          currentActiveThread && currentActiveThread.projectId === member.id
             ? {
                 projectId: currentActiveThread.projectId,
                 branch: currentActiveThread.branch,
@@ -1515,7 +1679,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
               }
             : null,
         activeDraftThread:
-          currentActiveDraftThread && currentActiveDraftThread.projectId === project.id
+          currentActiveDraftThread && currentActiveDraftThread.projectId === member.id
             ? {
                 projectId: currentActiveDraftThread.projectId,
                 branch: currentActiveDraftThread.branch,
@@ -1524,7 +1688,10 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
               }
             : null,
       });
-      void handleNewThread(scopeProjectRef(project.environmentId, project.id), {
+      if (isMobile) {
+        setOpenMobile(false);
+      }
+      void handleNewThread(scopeProjectRef(member.environmentId, member.id), {
         ...(seedContext.branch !== undefined ? { branch: seedContext.branch } : {}),
         ...(seedContext.worktreePath !== undefined
           ? { worktreePath: seedContext.worktreePath }
@@ -1532,7 +1699,47 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         envMode: seedContext.envMode,
       });
     },
-    [defaultThreadEnvMode, handleNewThread, project.environmentId, project.id, router],
+    [defaultThreadEnvMode, handleNewThread, isMobile, router, setOpenMobile],
+  );
+
+  const handleCreateThreadClick = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      event.preventDefault();
+      event.stopPropagation();
+
+      if (project.memberProjects.length === 1) {
+        createThreadForProjectMember(project.memberProjects[0]!);
+        return;
+      }
+
+      void (async () => {
+        const api = readLocalApi();
+        if (!api) {
+          return;
+        }
+        const clicked = await api.contextMenu.show(
+          project.memberProjects.map((member) => ({
+            id: member.physicalProjectKey,
+            label: formatProjectMemberActionLabel(member, project.groupedProjectCount),
+          })),
+          {
+            x: event.clientX,
+            y: event.clientY,
+          },
+        );
+        if (!clicked) {
+          return;
+        }
+        const targetMember = project.memberProjects.find(
+          (member) => member.physicalProjectKey === clicked,
+        );
+        if (!targetMember) {
+          return;
+        }
+        createThreadForProjectMember(targetMember);
+      })();
+    },
+    [createThreadForProjectMember, project.groupedProjectCount, project.memberProjects],
   );
 
   const attemptArchiveThread = useCallback(
@@ -1540,11 +1747,13 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       try {
         await archiveThread(threadRef);
       } catch (error) {
-        toastManager.add({
-          type: "error",
-          title: "Failed to archive thread",
-          description: error instanceof Error ? error.message : "An error occurred.",
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to archive thread",
+            description: error instanceof Error ? error.message : "An error occurred.",
+          }),
+        );
       }
     },
     [archiveThread],
@@ -1592,30 +1801,116 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
           title: trimmed,
         });
       } catch (error) {
-        toastManager.add({
-          type: "error",
-          title: "Failed to rename thread",
-          description: error instanceof Error ? error.message : "An error occurred.",
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to rename thread",
+            description: error instanceof Error ? error.message : "An error occurred.",
+          }),
+        );
       }
       finishRename();
     },
     [],
   );
 
+  const closeProjectRenameDialog = useCallback(() => {
+    setProjectRenameTarget(null);
+    setProjectRenameTitle("");
+  }, []);
+
+  const submitProjectRename = useCallback(async () => {
+    if (!projectRenameTarget) {
+      return;
+    }
+
+    const trimmed = projectRenameTitle.trim();
+    if (trimmed.length === 0) {
+      toastManager.add({
+        type: "warning",
+        title: "Project title cannot be empty",
+      });
+      return;
+    }
+
+    if (trimmed === projectRenameTarget.name) {
+      closeProjectRenameDialog();
+      return;
+    }
+
+    const api = readEnvironmentApi(projectRenameTarget.environmentId);
+    if (!api) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Failed to rename project",
+          description: "Project API unavailable.",
+        }),
+      );
+      return;
+    }
+
+    try {
+      await api.orchestration.dispatchCommand({
+        type: "project.meta.update",
+        commandId: newCommandId(),
+        projectId: projectRenameTarget.id,
+        title: trimmed,
+      });
+      closeProjectRenameDialog();
+    } catch (error) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Failed to rename project",
+          description: error instanceof Error ? error.message : "An error occurred.",
+        }),
+      );
+    }
+  }, [closeProjectRenameDialog, projectRenameTarget, projectRenameTitle]);
+
+  const closeProjectGroupingDialog = useCallback(() => {
+    setProjectGroupingTarget(null);
+    setProjectGroupingSelection("inherit");
+  }, []);
+
+  const saveProjectGroupingPreference = useCallback(() => {
+    if (!projectGroupingTarget) {
+      return;
+    }
+
+    const overrideKey = deriveProjectGroupingOverrideKey(projectGroupingTarget);
+    const nextOverrides = {
+      ...projectGroupingSettings.sidebarProjectGroupingOverrides,
+    };
+    if (projectGroupingSelection === "inherit") {
+      delete nextOverrides[overrideKey];
+    } else {
+      nextOverrides[overrideKey] = projectGroupingSelection;
+    }
+    updateSettings({
+      sidebarProjectGroupingOverrides: nextOverrides,
+    });
+    closeProjectGroupingDialog();
+  }, [
+    closeProjectGroupingDialog,
+    projectGroupingSelection,
+    projectGroupingSettings.sidebarProjectGroupingOverrides,
+    projectGroupingTarget,
+    updateSettings,
+  ]);
+
   const handleThreadContextMenu = useCallback(
     async (threadRef: ScopedThreadRef, position: { x: number; y: number }) => {
       const api = readLocalApi();
       if (!api) return;
       const threadKey = scopedThreadKey(threadRef);
-      const thread =
-        projectThreads.find(
-          (projectThread) =>
-            projectThread.environmentId === threadRef.environmentId &&
-            projectThread.id === threadRef.threadId,
-        ) ?? null;
+      const thread = sidebarThreadByKeyRef.current.get(threadKey) ?? null;
       if (!thread) return;
-      const threadWorkspacePath = thread.worktreePath ?? project.cwd ?? null;
+      const threadProject = memberProjectByScopedKey.get(
+        scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId)),
+      );
+      const threadWorkspacePath = thread.worktreePath ?? threadProject?.cwd ?? project.cwd ?? null;
       const clicked = await api.contextMenu.show(
         [
           { id: "rename", label: "Rename thread" },
@@ -1640,11 +1935,13 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       }
       if (clicked === "copy-path") {
         if (!threadWorkspacePath) {
-          toastManager.add({
-            type: "error",
-            title: "Path unavailable",
-            description: "This thread does not have a workspace path to copy.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Path unavailable",
+              description: "This thread does not have a workspace path to copy.",
+            }),
+          );
           return;
         }
         copyPathToClipboard(threadWorkspacePath, { path: threadWorkspacePath });
@@ -1674,8 +1971,8 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       copyThreadIdToClipboard,
       deleteThread,
       markThreadUnread,
+      memberProjectByScopedKey,
       project.cwd,
-      projectThreads,
     ],
   );
 
@@ -1685,7 +1982,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         <SidebarMenuButton
           ref={isManualProjectSorting ? dragHandleProps?.setActivatorNodeRef : undefined}
           size="sm"
-          className={`gap-2 px-2 py-1.5 text-left hover:bg-accent group-hover/project-header:bg-accent group-hover/project-header:text-sidebar-accent-foreground ${
+          className={`gap-2 px-2 py-1.5 pr-8 text-left hover:bg-accent group-hover/project-header:bg-accent group-hover/project-header:text-sidebar-accent-foreground max-sm:pr-14 ${
             isManualProjectSorting ? "cursor-grab active:cursor-grabbing" : "cursor-pointer"
           }`}
           {...(isManualProjectSorting && dragHandleProps ? dragHandleProps.attributes : {})}
@@ -1718,8 +2015,15 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
             />
           )}
           <ProjectFavicon environmentId={project.environmentId} cwd={project.cwd} />
-          <span className="flex-1 truncate text-xs font-medium text-foreground/90">
-            {project.name}
+          <span className="flex min-w-0 flex-1 items-center gap-2">
+            <span className="truncate text-xs font-medium text-foreground/90">
+              {project.displayName}
+            </span>
+            {project.groupedProjectCount > 1 ? (
+              <span className="shrink-0 text-[10px] text-muted-foreground/60">
+                {project.groupedProjectCount} projects
+              </span>
+            ) : null}
           </span>
         </SidebarMenuButton>
         {/* Environment badge – visible by default, crossfades with the
@@ -1735,7 +2039,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
                       ? "Remote project"
                       : "Available in multiple environments"
                   }
-                  className="pointer-events-none absolute top-1 right-1.5 inline-flex size-5 items-center justify-center rounded-md text-muted-foreground/50 transition-opacity duration-150 group-hover/project-header:opacity-0 group-focus-within/project-header:opacity-0"
+                  className="pointer-events-none absolute top-1 right-1.5 inline-flex size-5 items-center justify-center rounded-md text-muted-foreground/60 transition-opacity duration-150 max-sm:right-7 group-hover/project-header:opacity-0 group-focus-within/project-header:opacity-0 max-sm:group-hover/project-header:opacity-100 max-sm:group-focus-within/project-header:opacity-100"
                 />
               }
             >
@@ -1749,12 +2053,12 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         <Tooltip>
           <TooltipTrigger
             render={
-              <div className="pointer-events-none absolute top-1 right-1.5 opacity-0 transition-opacity duration-150 group-hover/project-header:pointer-events-auto group-hover/project-header:opacity-100 group-focus-within/project-header:pointer-events-auto group-focus-within/project-header:opacity-100">
+              <div className="pointer-events-none absolute top-1 right-1.5 opacity-0 transition-opacity duration-150 max-sm:pointer-events-auto max-sm:opacity-100 group-hover/project-header:pointer-events-auto group-hover/project-header:opacity-100 group-focus-within/project-header:pointer-events-auto group-focus-within/project-header:opacity-100">
                 <button
                   type="button"
-                  aria-label={`Create new thread in ${project.name}`}
+                  aria-label={`Create new thread in ${project.displayName}`}
                   data-testid="new-thread-button"
-                  className="inline-flex size-5 cursor-pointer items-center justify-center rounded-md text-muted-foreground/70 hover:bg-secondary hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+                  className="inline-flex size-5 cursor-pointer items-center justify-center rounded-md text-muted-foreground/60 hover:bg-secondary hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
                   onClick={handleCreateThreadClick}
                 >
                   <SquarePenIcon className="size-3.5" />
@@ -1803,6 +2107,124 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         expandThreadListForProject={expandThreadListForProject}
         collapseThreadListForProject={collapseThreadListForProject}
       />
+
+      <Dialog
+        open={projectRenameTarget !== null}
+        onOpenChange={(open) => {
+          if (!open) {
+            closeProjectRenameDialog();
+          }
+        }}
+      >
+        <DialogPopup className="max-w-lg">
+          <DialogHeader>
+            <DialogTitle>Rename project</DialogTitle>
+            <DialogDescription>
+              {projectRenameTarget
+                ? `Update the title for ${projectRenameTarget.cwd}.`
+                : "Update the project title."}
+            </DialogDescription>
+          </DialogHeader>
+          <DialogPanel className="space-y-4">
+            <div className="grid gap-1.5">
+              <span className="text-xs font-medium text-foreground">Project title</span>
+              <Input
+                aria-label="Project title"
+                value={projectRenameTitle}
+                onChange={(event) => setProjectRenameTitle(event.target.value)}
+                onKeyDown={(event) => {
+                  if (event.key === "Enter") {
+                    event.preventDefault();
+                    void submitProjectRename();
+                  }
+                }}
+              />
+            </div>
+            {projectRenameTarget?.environmentLabel ? (
+              <p className="text-xs text-muted-foreground">
+                Environment: {projectRenameTarget.environmentLabel}
+              </p>
+            ) : null}
+          </DialogPanel>
+          <DialogFooter>
+            <Button variant="outline" onClick={closeProjectRenameDialog}>
+              Cancel
+            </Button>
+            <Button onClick={() => void submitProjectRename()}>Save</Button>
+          </DialogFooter>
+        </DialogPopup>
+      </Dialog>
+
+      <Dialog
+        open={projectGroupingTarget !== null}
+        onOpenChange={(open) => {
+          if (!open) {
+            closeProjectGroupingDialog();
+          }
+        }}
+      >
+        <DialogPopup className="max-w-lg">
+          <DialogHeader>
+            <DialogTitle>Project grouping</DialogTitle>
+            <DialogDescription>
+              {projectGroupingTarget
+                ? `Choose how ${projectGroupingTarget.cwd} should be grouped in the sidebar.`
+                : "Choose how this project should be grouped in the sidebar."}
+            </DialogDescription>
+          </DialogHeader>
+          <DialogPanel className="space-y-4">
+            <div className="grid gap-1.5">
+              <span className="text-xs font-medium text-foreground">Grouping rule</span>
+              <Select
+                value={projectGroupingSelection}
+                onValueChange={(value) => {
+                  if (
+                    value === "inherit" ||
+                    value === "repository" ||
+                    value === "repository_path" ||
+                    value === "separate"
+                  ) {
+                    setProjectGroupingSelection(value);
+                  }
+                }}
+              >
+                <SelectTrigger className="w-full" aria-label="Project grouping rule">
+                  <SelectValue>
+                    {projectGroupingSelection === "inherit"
+                      ? `Use global default (${PROJECT_GROUPING_MODE_LABELS[projectGroupingSettings.sidebarProjectGroupingMode]})`
+                      : PROJECT_GROUPING_MODE_LABELS[projectGroupingSelection]}
+                  </SelectValue>
+                </SelectTrigger>
+                <SelectPopup align="end" alignItemWithTrigger={false}>
+                  <SelectItem hideIndicator value="inherit">
+                    Use global default
+                  </SelectItem>
+                  <SelectItem hideIndicator value="repository">
+                    {PROJECT_GROUPING_MODE_LABELS.repository}
+                  </SelectItem>
+                  <SelectItem hideIndicator value="repository_path">
+                    {PROJECT_GROUPING_MODE_LABELS.repository_path}
+                  </SelectItem>
+                  <SelectItem hideIndicator value="separate">
+                    {PROJECT_GROUPING_MODE_LABELS.separate}
+                  </SelectItem>
+                </SelectPopup>
+              </Select>
+            </div>
+            <p className="text-xs text-muted-foreground">
+              {projectGroupingSelection === "inherit"
+                ? projectGroupingModeDescription(projectGroupingSettings.sidebarProjectGroupingMode)
+                : projectGroupingModeDescription(projectGroupingSelection)}
+            </p>
+          </DialogPanel>
+          <DialogFooter>
+            <Button variant="outline" onClick={closeProjectGroupingDialog}>
+              Cancel
+            </Button>
+            <Button onClick={saveProjectGroupingPreference}>Save</Button>
+          </DialogFooter>
+        </DialogPopup>
+      </Dialog>
     </>
   );
 });
@@ -1839,14 +2261,36 @@ type SortableProjectHandleProps = Pick<
 function ProjectSortMenu({
   projectSortOrder,
   threadSortOrder,
+  projectGroupingMode,
+  threadPreviewCount,
   onProjectSortOrderChange,
   onThreadSortOrderChange,
+  onProjectGroupingModeChange,
+  onThreadPreviewCountChange,
 }: {
   projectSortOrder: SidebarProjectSortOrder;
   threadSortOrder: SidebarThreadSortOrder;
+  projectGroupingMode: SidebarProjectGroupingMode;
+  threadPreviewCount: SidebarThreadPreviewCount;
   onProjectSortOrderChange: (sortOrder: SidebarProjectSortOrder) => void;
   onThreadSortOrderChange: (sortOrder: SidebarThreadSortOrder) => void;
+  onProjectGroupingModeChange: (mode: SidebarProjectGroupingMode) => void;
+  onThreadPreviewCountChange: (count: SidebarThreadPreviewCount) => void;
 }) {
+  const handleThreadPreviewCountChange = useCallback(
+    (nextValue: number | null) => {
+      if (nextValue === null) {
+        return;
+      }
+
+      const clampedValue = clampSidebarThreadPreviewCount(nextValue);
+      if (clampedValue !== threadPreviewCount) {
+        onThreadPreviewCountChange(clampedValue);
+      }
+    },
+    [onThreadPreviewCountChange, threadPreviewCount],
+  );
+
   return (
     <Menu>
       <Tooltip>
@@ -1857,9 +2301,9 @@ function ProjectSortMenu({
         >
           <ArrowUpDownIcon className="size-3.5" />
         </TooltipTrigger>
-        <TooltipPopup side="right">Sort projects</TooltipPopup>
+        <TooltipPopup side="right">Sidebar options</TooltipPopup>
       </Tooltip>
-      <MenuPopup align="end" side="bottom" className="min-w-44">
+      <MenuPopup align="end" side="bottom" className="min-w-52">
         <MenuGroup>
           <div className="px-2 py-1 sm:text-xs font-medium text-muted-foreground">
             Sort projects
@@ -1898,6 +2342,66 @@ function ProjectSortMenu({
             ))}
           </MenuRadioGroup>
         </MenuGroup>
+        <MenuGroup>
+          <div className="px-2 pt-2 pb-1 text-muted-foreground sm:text-xs font-medium">
+            Visible threads
+          </div>
+          <div className="px-2 py-1">
+            <NumberField
+              aria-label="Visible thread count"
+              className="w-28 gap-0"
+              max={MAX_SIDEBAR_THREAD_PREVIEW_COUNT}
+              min={MIN_SIDEBAR_THREAD_PREVIEW_COUNT}
+              onValueChange={handleThreadPreviewCountChange}
+              size="sm"
+              step={1}
+              value={threadPreviewCount}
+            >
+              <NumberFieldGroup className="h-7 rounded-md sm:h-6.5">
+                <NumberFieldDecrement
+                  aria-label="Decrease visible thread count"
+                  className="px-2 sm:px-2 [&_svg]:size-3.5"
+                />
+                <NumberFieldInput
+                  aria-label="Visible thread count"
+                  className="h-7 w-9 grow-0 px-0 text-xs leading-7 sm:h-6.5 sm:leading-6.5"
+                  inputMode="numeric"
+                  onKeyDownCapture={(event) => {
+                    event.stopPropagation();
+                  }}
+                />
+                <NumberFieldIncrement
+                  aria-label="Increase visible thread count"
+                  className="px-2 sm:px-2 [&_svg]:size-3.5"
+                />
+              </NumberFieldGroup>
+            </NumberField>
+          </div>
+        </MenuGroup>
+        <MenuSeparator />
+        <MenuGroup>
+          <div className="px-2 pt-2 pb-1 font-medium text-muted-foreground sm:text-xs">
+            Group projects
+          </div>
+          <MenuRadioGroup
+            value={projectGroupingMode}
+            onValueChange={(value) => {
+              if (value === "repository" || value === "repository_path" || value === "separate") {
+                onProjectGroupingModeChange(value);
+              }
+            }}
+          >
+            {(
+              Object.entries(PROJECT_GROUPING_MODE_LABELS) as Array<
+                [SidebarProjectGroupingMode, string]
+              >
+            ).map(([value, label]) => (
+              <MenuRadioItem key={value} value={value} className="min-h-7 py-1 sm:text-xs">
+                {label}
+              </MenuRadioItem>
+            ))}
+          </MenuRadioGroup>
+        </MenuGroup>
       </MenuPopup>
     </Menu>
   );
@@ -1974,7 +2478,7 @@ const SidebarChromeHeader = memo(function SidebarChromeHeader({
   );
 
   return isElectron ? (
-    <SidebarHeader className="drag-region h-[52px] flex-row items-center gap-2 px-4 py-0 pl-[90px]">
+    <SidebarHeader className="drag-region h-[52px] flex-row items-center gap-2 px-4 py-0 pl-[90px] wco:h-[env(titlebar-area-height)] wco:pl-[calc(env(titlebar-area-x)+1em)]">
       {wordmark}
     </SidebarHeader>
   ) : (
@@ -1984,12 +2488,17 @@ const SidebarChromeHeader = memo(function SidebarChromeHeader({
 
 const SidebarChromeFooter = memo(function SidebarChromeFooter() {
   const navigate = useNavigate();
+  const { isMobile, setOpenMobile } = useSidebar();
   const handleSettingsClick = useCallback(() => {
+    if (isMobile) {
+      setOpenMobile(false);
+    }
     void navigate({ to: "/settings" });
-  }, [navigate]);
+  }, [isMobile, navigate, setOpenMobile]);
 
   return (
     <SidebarFooter className="p-2">
+      <SidebarProviderUpdatePill />
       <SidebarUpdatePill />
       <SidebarMenu>
         <SidebarMenuItem>
@@ -2015,21 +2524,10 @@ interface SidebarProjectsContentProps {
   handleDesktopUpdateButtonClick: () => void;
   projectSortOrder: SidebarProjectSortOrder;
   threadSortOrder: SidebarThreadSortOrder;
+  projectGroupingMode: SidebarProjectGroupingMode;
+  threadPreviewCount: SidebarThreadPreviewCount;
   updateSettings: ReturnType<typeof useUpdateSettings>["updateSettings"];
-  shouldShowProjectPathEntry: boolean;
-  handleStartAddProject: () => void;
-  isElectron: boolean;
-  isPickingFolder: boolean;
-  isAddingProject: boolean;
-  handlePickFolder: () => Promise<void>;
-  addProjectInputRef: React.RefObject<HTMLInputElement | null>;
-  addProjectError: string | null;
-  newCwd: string;
-  setNewCwd: React.Dispatch<React.SetStateAction<string>>;
-  setAddProjectError: React.Dispatch<React.SetStateAction<string | null>>;
-  handleAddProject: () => void;
-  setAddingProject: React.Dispatch<React.SetStateAction<boolean>>;
-  canAddProject: boolean;
+  openAddProject: () => void;
   isManualProjectSorting: boolean;
   projectDnDSensors: ReturnType<typeof useSensors>;
   projectCollisionDetection: CollisionDetection;
@@ -2067,21 +2565,10 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
     handleDesktopUpdateButtonClick,
     projectSortOrder,
     threadSortOrder,
+    projectGroupingMode,
+    threadPreviewCount,
     updateSettings,
-    shouldShowProjectPathEntry,
-    handleStartAddProject,
-    isElectron,
-    isPickingFolder,
-    isAddingProject,
-    handlePickFolder,
-    addProjectInputRef,
-    addProjectError,
-    newCwd,
-    setNewCwd,
-    setAddProjectError,
-    handleAddProject,
-    setAddingProject,
-    canAddProject,
+    openAddProject,
     isManualProjectSorting,
     projectDnDSensors,
     projectCollisionDetection,
@@ -2120,26 +2607,18 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
     },
     [updateSettings],
   );
-  const handleAddProjectInputChange = useCallback(
-    (event: React.ChangeEvent<HTMLInputElement>) => {
-      setNewCwd(event.target.value);
-      setAddProjectError(null);
+  const handleProjectGroupingModeChange = useCallback(
+    (groupingMode: SidebarProjectGroupingMode) => {
+      updateSettings({ sidebarProjectGroupingMode: groupingMode });
     },
-    [setAddProjectError, setNewCwd],
+    [updateSettings],
   );
-  const handleAddProjectInputKeyDown = useCallback(
-    (event: React.KeyboardEvent<HTMLInputElement>) => {
-      if (event.key === "Enter") handleAddProject();
-      if (event.key === "Escape") {
-        setAddingProject(false);
-        setAddProjectError(null);
-      }
+  const handleThreadPreviewCountChange = useCallback(
+    (count: SidebarThreadPreviewCount) => {
+      updateSettings({ sidebarThreadPreviewCount: count });
     },
-    [handleAddProject, setAddProjectError, setAddingProject],
+    [updateSettings],
   );
-  const handleBrowseForFolderClick = useCallback(() => {
-    void handlePickFolder();
-  }, [handlePickFolder]);
 
   return (
     <SidebarContent className="gap-0">
@@ -2198,76 +2677,31 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
             <ProjectSortMenu
               projectSortOrder={projectSortOrder}
               threadSortOrder={threadSortOrder}
+              projectGroupingMode={projectGroupingMode}
+              threadPreviewCount={threadPreviewCount}
               onProjectSortOrderChange={handleProjectSortOrderChange}
               onThreadSortOrderChange={handleThreadSortOrderChange}
+              onProjectGroupingModeChange={handleProjectGroupingModeChange}
+              onThreadPreviewCountChange={handleThreadPreviewCountChange}
             />
             <Tooltip>
               <TooltipTrigger
                 render={
                   <button
                     type="button"
-                    aria-label={shouldShowProjectPathEntry ? "Cancel add project" : "Add project"}
-                    aria-pressed={shouldShowProjectPathEntry}
+                    aria-label="Add project"
+                    data-testid="sidebar-add-project-trigger"
                     className="inline-flex size-5 cursor-pointer items-center justify-center rounded-md text-muted-foreground/60 transition-colors hover:bg-accent hover:text-foreground"
-                    onClick={handleStartAddProject}
+                    onClick={openAddProject}
                   />
                 }
               >
-                <PlusIcon
-                  className={`size-3.5 transition-transform duration-150 ${
-                    shouldShowProjectPathEntry ? "rotate-45" : "rotate-0"
-                  }`}
-                />
+                <FolderPlusIcon className="size-3.5" />
               </TooltipTrigger>
-              <TooltipPopup side="right">
-                {shouldShowProjectPathEntry ? "Cancel add project" : "Add project"}
-              </TooltipPopup>
+              <TooltipPopup side="right">Add project</TooltipPopup>
             </Tooltip>
           </div>
         </div>
-        {shouldShowProjectPathEntry && (
-          <div className="mb-2 px-1">
-            {isElectron && (
-              <button
-                type="button"
-                className="mb-1.5 flex w-full items-center justify-center gap-2 rounded-md border border-border bg-secondary py-1.5 text-xs text-foreground/80 transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-60"
-                onClick={handleBrowseForFolderClick}
-                disabled={isPickingFolder || isAddingProject}
-              >
-                <FolderIcon className="size-3.5" />
-                {isPickingFolder ? "Picking folder..." : "Browse for folder"}
-              </button>
-            )}
-            <div className="flex gap-1.5">
-              <input
-                ref={addProjectInputRef}
-                className={`min-w-0 flex-1 rounded-md border bg-secondary px-2 py-1 font-mono text-xs text-foreground placeholder:text-muted-foreground/40 focus:outline-none ${
-                  addProjectError
-                    ? "border-red-500/70 focus:border-red-500"
-                    : "border-border focus:border-ring"
-                }`}
-                placeholder="/path/to/project"
-                value={newCwd}
-                onChange={handleAddProjectInputChange}
-                onKeyDown={handleAddProjectInputKeyDown}
-                autoFocus
-              />
-              <button
-                type="button"
-                className="shrink-0 rounded-md bg-primary px-2.5 py-1 text-xs font-medium text-primary-foreground transition-colors duration-150 hover:bg-primary/90 disabled:opacity-60"
-                onClick={handleAddProject}
-                disabled={!canAddProject}
-              >
-                {isAddingProject ? "Adding..." : "Add"}
-              </button>
-            </div>
-            {addProjectError && (
-              <p className="mt-1 px-0.5 text-[11px] leading-tight text-red-400">
-                {addProjectError}
-              </p>
-            )}
-          </div>
-        )}
 
         {isManualProjectSorting ? (
           <DndContext
@@ -2342,7 +2776,7 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
           </SidebarMenu>
         )}
 
-        {projectsLength === 0 && !shouldShowProjectPathEntry && (
+        {projectsLength === 0 && (
           <div className="px-2 pt-4 text-center text-xs text-muted-foreground/60">
             No projects yet
           </div>
@@ -2355,7 +2789,6 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
 export default function Sidebar() {
   const projects = useStore(useShallow(selectProjectsAcrossEnvironments));
   const sidebarThreads = useStore(useShallow(selectSidebarThreadsAcrossEnvironments));
-  const activeEnvironmentId = useStore((store) => store.activeEnvironmentId);
   const projectExpandedById = useUiStateStore((store) => store.projectExpandedById);
   const projectOrder = useUiStateStore((store) => store.projectOrder);
   const reorderProjects = useUiStateStore((store) => store.reorderProjects);
@@ -2364,22 +2797,20 @@ export default function Sidebar() {
   const isOnSettings = pathname.startsWith("/settings");
   const sidebarThreadSortOrder = useSettings((s) => s.sidebarThreadSortOrder);
   const sidebarProjectSortOrder = useSettings((s) => s.sidebarProjectSortOrder);
-  const defaultThreadEnvMode = useSettings((s) => s.defaultThreadEnvMode);
+  const sidebarProjectGroupingMode = useSettings((s) => s.sidebarProjectGroupingMode);
+  const projectGroupingSettings = useSettings(selectProjectGroupingSettings);
+  const sidebarThreadPreviewCount = useSettings((s) => s.sidebarThreadPreviewCount);
   const { updateSettings } = useUpdateSettings();
   const { handleNewThread } = useNewThreadHandler();
   const { archiveThread, deleteThread } = useThreadActions();
+  const { isMobile, setOpenMobile } = useSidebar();
   const routeThreadRef = useParams({
     strict: false,
     select: (params) => resolveThreadRouteRef(params),
   });
   const routeThreadKey = routeThreadRef ? scopedThreadKey(routeThreadRef) : null;
   const keybindings = useServerKeybindings();
-  const [addingProject, setAddingProject] = useState(false);
-  const [newCwd, setNewCwd] = useState("");
-  const [isPickingFolder, setIsPickingFolder] = useState(false);
-  const [isAddingProject, setIsAddingProject] = useState(false);
-  const [addProjectError, setAddProjectError] = useState<string | null>(null);
-  const addProjectInputRef = useRef<HTMLInputElement | null>(null);
+  const openAddProjectCommandPalette = useCommandPaletteStore((store) => store.openAddProject);
   const [expandedThreadListsByProject, setExpandedThreadListsByProject] = useState<
     ReadonlySet<string>
   >(() => new Set());
@@ -2388,13 +2819,11 @@ export default function Sidebar() {
   const suppressProjectClickAfterDragRef = useRef(false);
   const suppressProjectClickForContextMenuRef = useRef(false);
   const [desktopUpdateState, setDesktopUpdateState] = useState<DesktopUpdateState | null>(null);
-  const selectedThreadCount = useThreadSelectionStore((s) => s.selectedThreadKeys.size);
   const clearSelection = useThreadSelectionStore((s) => s.clearSelection);
   const setSelectionAnchor = useThreadSelectionStore((s) => s.setAnchor);
-  const isLinuxDesktop = isElectron && isLinuxPlatform(navigator.platform);
   const platform = navigator.platform;
-  const shouldBrowseForProjectImmediately = isElectron && !isLinuxDesktop;
-  const shouldShowProjectPathEntry = addingProject && !shouldBrowseForProjectImmediately;
+  const shortcutModifiers = useShortcutModifierState();
+  const modelPickerOpen = useModelPickerOpen();
   const primaryEnvironmentId = usePrimaryEnvironmentId();
   const savedEnvironmentRegistry = useSavedEnvironmentRegistryStore((s) => s.byId);
   const savedEnvironmentRuntimeById = useSavedEnvironmentRuntimeStore((s) => s.byId);
@@ -2402,7 +2831,7 @@ export default function Sidebar() {
     return orderItemsByPreferredIds({
       items: projects,
       preferredIds: projectOrder,
-      getId: (project) => scopedProjectKey(scopeProjectRef(project.environmentId, project.id)),
+      getId: getProjectOrderKey,
     });
   }, [projectOrder, projects]);
 
@@ -2410,79 +2839,36 @@ export default function Sidebar() {
   // cross-environment grouping.  Projects that share a repositoryIdentity
   // canonicalKey are treated as one logical project in the sidebar.
   const physicalToLogicalKey = useMemo(() => {
-    const mapping = new Map<string, string>();
-    for (const project of orderedProjects) {
-      const physicalKey = scopedProjectKey(scopeProjectRef(project.environmentId, project.id));
-      mapping.set(physicalKey, deriveLogicalProjectKey(project));
-    }
-    return mapping;
-  }, [orderedProjects]);
+    return buildPhysicalToLogicalProjectKeyMap({
+      projects: orderedProjects,
+      settings: projectGroupingSettings,
+    });
+  }, [orderedProjects, projectGroupingSettings]);
+  const projectPhysicalKeyByScopedRef = useMemo(
+    () =>
+      new Map(
+        orderedProjects.map((project) => [
+          scopedProjectKey(scopeProjectRef(project.environmentId, project.id)),
+          derivePhysicalProjectKey(project),
+        ]),
+      ),
+    [orderedProjects],
+  );
 
   const sidebarProjects = useMemo<SidebarProjectSnapshot[]>(() => {
-    // Group projects by logical key while preserving insertion order from
-    // orderedProjects.
-    const groupedMembers = new Map<string, Project[]>();
-    for (const project of orderedProjects) {
-      const logicalKey = deriveLogicalProjectKey(project);
-      const existing = groupedMembers.get(logicalKey);
-      if (existing) {
-        existing.push(project);
-      } else {
-        groupedMembers.set(logicalKey, [project]);
-      }
-    }
-
-    const result: SidebarProjectSnapshot[] = [];
-    const seen = new Set<string>();
-    for (const project of orderedProjects) {
-      const logicalKey = deriveLogicalProjectKey(project);
-      if (seen.has(logicalKey)) continue;
-      seen.add(logicalKey);
-
-      const members = groupedMembers.get(logicalKey)!;
-      // Prefer the primary environment's project as the representative.
-      const representative: Project | undefined =
-        (primaryEnvironmentId
-          ? members.find((p) => p.environmentId === primaryEnvironmentId)
-          : undefined) ?? members[0];
-      if (!representative) continue;
-      const hasLocal =
-        primaryEnvironmentId !== null &&
-        members.some((p) => p.environmentId === primaryEnvironmentId);
-      const hasRemote =
-        primaryEnvironmentId !== null
-          ? members.some((p) => p.environmentId !== primaryEnvironmentId)
-          : false;
-
-      const refs = members.map((p) => scopeProjectRef(p.environmentId, p.id));
-      const remoteLabels = members
-        .filter((p) => primaryEnvironmentId !== null && p.environmentId !== primaryEnvironmentId)
-        .map((p) => {
-          const rt = savedEnvironmentRuntimeById[p.environmentId];
-          const saved = savedEnvironmentRegistry[p.environmentId];
-          return rt?.descriptor?.label ?? saved?.label ?? p.environmentId;
-        });
-      const snapshot: SidebarProjectSnapshot = {
-        id: representative.id,
-        environmentId: representative.environmentId,
-        name: representative.name,
-        cwd: representative.cwd,
-        repositoryIdentity: representative.repositoryIdentity ?? null,
-        defaultModelSelection: representative.defaultModelSelection,
-        createdAt: representative.createdAt,
-        updatedAt: representative.updatedAt,
-        scripts: representative.scripts,
-        projectKey: logicalKey,
-        environmentPresence:
-          hasLocal && hasRemote ? "mixed" : hasRemote ? "remote-only" : "local-only",
-        memberProjectRefs: refs,
-        remoteEnvironmentLabels: remoteLabels,
-      };
-      result.push(snapshot);
-    }
-    return result;
+    return buildSidebarProjectSnapshots({
+      projects: orderedProjects,
+      settings: projectGroupingSettings,
+      primaryEnvironmentId,
+      resolveEnvironmentLabel: (environmentId) => {
+        const rt = savedEnvironmentRuntimeById[environmentId];
+        const saved = savedEnvironmentRegistry[environmentId];
+        return rt?.descriptor?.label ?? saved?.label ?? null;
+      },
+    });
   }, [
     orderedProjects,
+    projectGroupingSettings,
     primaryEnvironmentId,
     savedEnvironmentRegistry,
     savedEnvironmentRuntimeById,
@@ -2510,18 +2896,22 @@ export default function Sidebar() {
     }
     const activeThread = sidebarThreadByKey.get(routeThreadKey);
     if (!activeThread) return null;
-    const physicalKey = scopedProjectKey(
-      scopeProjectRef(activeThread.environmentId, activeThread.projectId),
-    );
+    const physicalKey =
+      projectPhysicalKeyByScopedRef.get(
+        scopedProjectKey(scopeProjectRef(activeThread.environmentId, activeThread.projectId)),
+      ) ?? scopedProjectKey(scopeProjectRef(activeThread.environmentId, activeThread.projectId));
     return physicalToLogicalKey.get(physicalKey) ?? physicalKey;
-  }, [routeThreadKey, sidebarThreadByKey, physicalToLogicalKey]);
+  }, [routeThreadKey, sidebarThreadByKey, physicalToLogicalKey, projectPhysicalKeyByScopedRef]);
 
   // Group threads by logical project key so all threads from grouped projects
   // are displayed together.
   const threadsByProjectKey = useMemo(() => {
     const next = new Map<string, SidebarThreadSummary[]>();
     for (const thread of sidebarThreads) {
-      const physicalKey = scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId));
+      const physicalKey =
+        projectPhysicalKeyByScopedRef.get(
+          scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId)),
+        ) ?? scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId));
       const logicalKey = physicalToLogicalKey.get(physicalKey) ?? physicalKey;
       const existing = next.get(logicalKey);
       if (existing) {
@@ -2531,7 +2921,7 @@ export default function Sidebar() {
       }
     }
     return next;
-  }, [sidebarThreads, physicalToLogicalKey]);
+  }, [sidebarThreads, physicalToLogicalKey, projectPhysicalKeyByScopedRef]);
   const getCurrentSidebarShortcutContext = useCallback(
     () => ({
       terminalFocus: isTerminalFocused(),
@@ -2541,8 +2931,9 @@ export default function Sidebar() {
             routeThreadRef,
           ).terminalOpen
         : false,
+      modelPickerOpen,
     }),
-    [routeThreadRef],
+    [modelPickerOpen, routeThreadRef],
   );
   const newThreadShortcutLabelOptions = useMemo(
     () => ({
@@ -2557,131 +2948,6 @@ export default function Sidebar() {
   const newThreadShortcutLabel =
     shortcutLabelForCommand(keybindings, "chat.newLocal", newThreadShortcutLabelOptions) ??
     shortcutLabelForCommand(keybindings, "chat.new", newThreadShortcutLabelOptions);
-  const focusMostRecentThreadForProject = useCallback(
-    (projectRef: { environmentId: EnvironmentId; projectId: ProjectId }) => {
-      const physicalKey = scopedProjectKey(
-        scopeProjectRef(projectRef.environmentId, projectRef.projectId),
-      );
-      const logicalKey = physicalToLogicalKey.get(physicalKey) ?? physicalKey;
-      const latestThread = sortThreads(
-        (threadsByProjectKey.get(logicalKey) ?? []).filter((thread) => thread.archivedAt === null),
-        sidebarThreadSortOrder,
-      )[0];
-      if (!latestThread) return;
-
-      void navigate({
-        to: "/$environmentId/$threadId",
-        params: buildThreadRouteParams(scopeThreadRef(latestThread.environmentId, latestThread.id)),
-      });
-    },
-    [sidebarThreadSortOrder, navigate, threadsByProjectKey, physicalToLogicalKey],
-  );
-
-  const addProjectFromInput = useCallback(
-    async (rawCwd: string) => {
-      const cwd = rawCwd.trim();
-      if (!cwd || isAddingProject) return;
-      const api = activeEnvironmentId ? readEnvironmentApi(activeEnvironmentId) : undefined;
-      if (!api) return;
-
-      setIsAddingProject(true);
-      const finishAddingProject = () => {
-        setIsAddingProject(false);
-        setNewCwd("");
-        setAddProjectError(null);
-        setAddingProject(false);
-      };
-
-      const existing = projects.find((project) => project.cwd === cwd);
-      if (existing) {
-        focusMostRecentThreadForProject({
-          environmentId: existing.environmentId,
-          projectId: existing.id,
-        });
-        finishAddingProject();
-        return;
-      }
-
-      const projectId = newProjectId();
-      const title = cwd.split(/[/\\]/).findLast(isNonEmptyString) ?? cwd;
-      try {
-        await api.orchestration.dispatchCommand({
-          type: "project.create",
-          commandId: newCommandId(),
-          projectId,
-          title,
-          workspaceRoot: cwd,
-          defaultModelSelection: {
-            provider: "codex",
-            model: DEFAULT_MODEL_BY_PROVIDER.codex,
-          },
-          createdAt: new Date().toISOString(),
-        });
-        if (activeEnvironmentId !== null) {
-          await handleNewThread(scopeProjectRef(activeEnvironmentId, projectId), {
-            envMode: defaultThreadEnvMode,
-          }).catch(() => undefined);
-        }
-      } catch (error) {
-        const description =
-          error instanceof Error ? error.message : "An error occurred while adding the project.";
-        setIsAddingProject(false);
-        if (shouldBrowseForProjectImmediately) {
-          toastManager.add({
-            type: "error",
-            title: "Failed to add project",
-            description,
-          });
-        } else {
-          setAddProjectError(description);
-        }
-        return;
-      }
-      finishAddingProject();
-    },
-    [
-      focusMostRecentThreadForProject,
-      activeEnvironmentId,
-      handleNewThread,
-      isAddingProject,
-      projects,
-      shouldBrowseForProjectImmediately,
-      defaultThreadEnvMode,
-    ],
-  );
-
-  const handleAddProject = () => {
-    void addProjectFromInput(newCwd);
-  };
-
-  const canAddProject = newCwd.trim().length > 0 && !isAddingProject;
-
-  const handlePickFolder = async () => {
-    const api = readLocalApi();
-    if (!api || isPickingFolder) return;
-    setIsPickingFolder(true);
-    let pickedPath: string | null = null;
-    try {
-      pickedPath = await api.dialogs.pickFolder();
-    } catch {
-      // Ignore picker failures and leave the current thread selection unchanged.
-    }
-    if (pickedPath) {
-      await addProjectFromInput(pickedPath);
-    } else if (!shouldBrowseForProjectImmediately) {
-      addProjectInputRef.current?.focus();
-    }
-    setIsPickingFolder(false);
-  };
-
-  const handleStartAddProject = () => {
-    setAddProjectError(null);
-    if (shouldBrowseForProjectImmediately) {
-      void handlePickFolder();
-      return;
-    }
-    setAddingProject((prev) => !prev);
-  };
 
   const navigateToThread = useCallback(
     (threadRef: ScopedThreadRef) => {
@@ -2689,12 +2955,15 @@ export default function Sidebar() {
         clearSelection();
       }
       setSelectionAnchor(scopedThreadKey(threadRef));
+      if (isMobile) {
+        setOpenMobile(false);
+      }
       void navigate({
         to: "/$environmentId/$threadId",
         params: buildThreadRouteParams(threadRef),
       });
     },
-    [clearSelection, navigate, setSelectionAnchor],
+    [clearSelection, isMobile, navigate, setOpenMobile, setSelectionAnchor],
   );
 
   const projectDnDSensors = useSensors(
@@ -2723,8 +2992,10 @@ export default function Sidebar() {
       const activeProject = sidebarProjects.find((project) => project.projectKey === active.id);
       const overProject = sidebarProjects.find((project) => project.projectKey === over.id);
       if (!activeProject || !overProject) return;
-      const activeMemberKeys = activeProject.memberProjectRefs.map(scopedProjectKey);
-      const overMemberKeys = overProject.memberProjectRefs.map(scopedProjectKey);
+      const activeMemberKeys = activeProject.memberProjects.map(
+        (member) => member.physicalProjectKey,
+      );
+      const overMemberKeys = overProject.memberProjects.map((member) => member.physicalProjectKey);
       reorderProjects(activeMemberKeys, overMemberKeys);
     },
     [sidebarProjectSortOrder, reorderProjects, sidebarProjects],
@@ -2773,7 +3044,10 @@ export default function Sidebar() {
       id: project.projectKey,
     }));
     const sortableThreads = visibleThreads.map((thread) => {
-      const physicalKey = scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId));
+      const physicalKey =
+        projectPhysicalKeyByScopedRef.get(
+          scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId)),
+        ) ?? scopedProjectKey(scopeProjectRef(thread.environmentId, thread.projectId));
       return {
         ...thread,
         projectId: (physicalToLogicalKey.get(physicalKey) ?? physicalKey) as ProjectId,
@@ -2790,6 +3064,7 @@ export default function Sidebar() {
   }, [
     sidebarProjectSortOrder,
     physicalToLogicalKey,
+    projectPhysicalKeyByScopedRef,
     sidebarProjectByKey,
     sidebarProjects,
     visibleThreads,
@@ -2819,11 +3094,11 @@ export default function Sidebar() {
           return [];
         }
         const isThreadListExpanded = expandedThreadListsByProject.has(project.projectKey);
-        const hasOverflowingThreads = projectThreads.length > THREAD_PREVIEW_LIMIT;
+        const hasOverflowingThreads = projectThreads.length > sidebarThreadPreviewCount;
         const previewThreads =
           isThreadListExpanded || !hasOverflowingThreads
             ? projectThreads
-            : projectThreads.slice(0, THREAD_PREVIEW_LIMIT);
+            : projectThreads.slice(0, sidebarThreadPreviewCount);
         const renderedThreads = pinnedCollapsedThread ? [pinnedCollapsedThread] : previewThreads;
         return renderedThreads.map((thread) =>
           scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
@@ -2831,6 +3106,7 @@ export default function Sidebar() {
       }),
     [
       sidebarThreadSortOrder,
+      sidebarThreadPreviewCount,
       expandedThreadListsByProject,
       projectExpandedById,
       routeThreadKey,
@@ -2854,64 +3130,73 @@ export default function Sidebar() {
     () => [...threadJumpCommandByKey.keys()],
     [threadJumpCommandByKey],
   );
-  const [threadJumpLabelByKey, setThreadJumpLabelByKey] =
-    useState<ReadonlyMap<string, string>>(EMPTY_THREAD_JUMP_LABELS);
-  const threadJumpLabelsRef = useRef<ReadonlyMap<string, string>>(EMPTY_THREAD_JUMP_LABELS);
-  threadJumpLabelsRef.current = threadJumpLabelByKey;
-  const showThreadJumpHintsRef = useRef(showThreadJumpHints);
-  showThreadJumpHintsRef.current = showThreadJumpHints;
+  const sidebarShortcutContext = useMemo(
+    () => ({
+      terminalFocus: false,
+      terminalOpen: routeThreadRef
+        ? selectThreadTerminalState(
+            useTerminalStateStore.getState().terminalStateByThreadKey,
+            routeThreadRef,
+          ).terminalOpen
+        : false,
+      modelPickerOpen,
+    }),
+    [modelPickerOpen, routeThreadRef],
+  );
+  const threadJumpLabelByKey = useMemo(
+    () =>
+      buildThreadJumpLabelMap({
+        keybindings,
+        platform,
+        terminalOpen: sidebarShortcutContext.terminalOpen,
+        threadJumpCommandByKey,
+      }),
+    [keybindings, platform, sidebarShortcutContext.terminalOpen, threadJumpCommandByKey],
+  );
+  const shouldShowThreadJumpHintsNow = shouldShowThreadJumpHintsForModifiers(
+    shortcutModifiers,
+    keybindings,
+    {
+      platform,
+      context: sidebarShortcutContext,
+    },
+  );
   const visibleThreadJumpLabelByKey = showThreadJumpHints
     ? threadJumpLabelByKey
     : EMPTY_THREAD_JUMP_LABELS;
   const orderedSidebarThreadKeys = visibleSidebarThreadKeys;
+  const prewarmedSidebarThreadKeys = useMemo(
+    () => getSidebarThreadIdsToPrewarm(visibleSidebarThreadKeys),
+    [visibleSidebarThreadKeys],
+  );
+  const prewarmedSidebarThreadRefs = useMemo(
+    () =>
+      prewarmedSidebarThreadKeys.flatMap((threadKey) => {
+        const ref = parseScopedThreadKey(threadKey);
+        return ref ? [ref] : [];
+      }),
+    [prewarmedSidebarThreadKeys],
+  );
 
   useEffect(() => {
-    const clearThreadJumpHints = () => {
-      setThreadJumpLabelByKey((current) =>
-        current === EMPTY_THREAD_JUMP_LABELS ? current : EMPTY_THREAD_JUMP_LABELS,
-      );
-      updateThreadJumpHintsVisibility(false);
+    const releases = prewarmedSidebarThreadRefs.map((ref) =>
+      retainThreadDetailSubscription(ref.environmentId, ref.threadId),
+    );
+
+    return () => {
+      for (const release of releases) {
+        release();
+      }
     };
-    const shouldIgnoreThreadJumpHintUpdate = (event: globalThis.KeyboardEvent) =>
-      !event.metaKey &&
-      !event.ctrlKey &&
-      !event.altKey &&
-      !event.shiftKey &&
-      event.key !== "Meta" &&
-      event.key !== "Control" &&
-      event.key !== "Alt" &&
-      event.key !== "Shift" &&
-      !showThreadJumpHintsRef.current &&
-      threadJumpLabelsRef.current === EMPTY_THREAD_JUMP_LABELS;
+  }, [prewarmedSidebarThreadRefs]);
+
+  useEffect(() => {
+    updateThreadJumpHintsVisibility(shouldShowThreadJumpHintsNow);
+  }, [shouldShowThreadJumpHintsNow, updateThreadJumpHintsVisibility]);
 
+  useEffect(() => {
     const onWindowKeyDown = (event: globalThis.KeyboardEvent) => {
-      if (shouldIgnoreThreadJumpHintUpdate(event)) {
-        return;
-      }
       const shortcutContext = getCurrentSidebarShortcutContext();
-      const shouldShowHints = shouldShowThreadJumpHints(event, keybindings, {
-        platform,
-        context: shortcutContext,
-      });
-      if (!shouldShowHints) {
-        if (
-          showThreadJumpHintsRef.current ||
-          threadJumpLabelsRef.current !== EMPTY_THREAD_JUMP_LABELS
-        ) {
-          clearThreadJumpHints();
-        }
-      } else {
-        setThreadJumpLabelByKey((current) => {
-          const nextLabelMap = buildThreadJumpLabelMap({
-            keybindings,
-            platform,
-            terminalOpen: shortcutContext.terminalOpen,
-            threadJumpCommandByKey,
-          });
-          return threadJumpLabelMapsEqual(current, nextLabelMap) ? current : nextLabelMap;
-        });
-        updateThreadJumpHintsVisibility(true);
-      }
 
       if (event.defaultPrevented || event.repeat) {
         return;
@@ -2961,43 +3246,10 @@ export default function Sidebar() {
       navigateToThread(scopeThreadRef(targetThread.environmentId, targetThread.id));
     };
 
-    const onWindowKeyUp = (event: globalThis.KeyboardEvent) => {
-      if (shouldIgnoreThreadJumpHintUpdate(event)) {
-        return;
-      }
-      const shortcutContext = getCurrentSidebarShortcutContext();
-      const shouldShowHints = shouldShowThreadJumpHints(event, keybindings, {
-        platform,
-        context: shortcutContext,
-      });
-      if (!shouldShowHints) {
-        clearThreadJumpHints();
-        return;
-      }
-      setThreadJumpLabelByKey((current) => {
-        const nextLabelMap = buildThreadJumpLabelMap({
-          keybindings,
-          platform,
-          terminalOpen: shortcutContext.terminalOpen,
-          threadJumpCommandByKey,
-        });
-        return threadJumpLabelMapsEqual(current, nextLabelMap) ? current : nextLabelMap;
-      });
-      updateThreadJumpHintsVisibility(true);
-    };
-
-    const onWindowBlur = () => {
-      clearThreadJumpHints();
-    };
-
     window.addEventListener("keydown", onWindowKeyDown);
-    window.addEventListener("keyup", onWindowKeyUp);
-    window.addEventListener("blur", onWindowBlur);
 
     return () => {
       window.removeEventListener("keydown", onWindowKeyDown);
-      window.removeEventListener("keyup", onWindowKeyUp);
-      window.removeEventListener("blur", onWindowBlur);
     };
   }, [
     getCurrentSidebarShortcutContext,
@@ -3007,14 +3259,12 @@ export default function Sidebar() {
     platform,
     routeThreadKey,
     sidebarThreadByKey,
-    threadJumpCommandByKey,
     threadJumpThreadKeys,
-    updateThreadJumpHintsVisibility,
   ]);
 
   useEffect(() => {
     const onMouseDown = (event: globalThis.MouseEvent) => {
-      if (selectedThreadCount === 0) return;
+      if (!useThreadSelectionStore.getState().hasSelection()) return;
       const target = event.target instanceof HTMLElement ? event.target : null;
       if (!shouldClearThreadSelectionOnMouseDown(target)) return;
       clearSelection();
@@ -3024,7 +3274,7 @@ export default function Sidebar() {
     return () => {
       window.removeEventListener("mousedown", onMouseDown);
     };
-  }, [clearSelection, selectedThreadCount]);
+  }, [clearSelection]);
 
   useEffect(() => {
     if (!isElectron) return;
@@ -3093,18 +3343,22 @@ export default function Sidebar() {
           if (!shouldToastDesktopUpdateActionResult(result)) return;
           const actionError = getDesktopUpdateActionError(result);
           if (!actionError) return;
-          toastManager.add({
-            type: "error",
-            title: "Could not download update",
-            description: actionError,
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not download update",
+              description: actionError,
+            }),
+          );
         })
         .catch((error) => {
-          toastManager.add({
-            type: "error",
-            title: "Could not start update download",
-            description: error instanceof Error ? error.message : "An unexpected error occurred.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not start update download",
+              description: error instanceof Error ? error.message : "An unexpected error occurred.",
+            }),
+          );
         });
       return;
     }
@@ -3120,18 +3374,22 @@ export default function Sidebar() {
           if (!shouldToastDesktopUpdateActionResult(result)) return;
           const actionError = getDesktopUpdateActionError(result);
           if (!actionError) return;
-          toastManager.add({
-            type: "error",
-            title: "Could not install update",
-            description: actionError,
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not install update",
+              description: actionError,
+            }),
+          );
         })
         .catch((error) => {
-          toastManager.add({
-            type: "error",
-            title: "Could not install update",
-            description: error instanceof Error ? error.message : "An unexpected error occurred.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not install update",
+              description: error instanceof Error ? error.message : "An unexpected error occurred.",
+            }),
+          );
         });
     }
   }, [desktopUpdateButtonAction, desktopUpdateButtonDisabled, desktopUpdateState]);
@@ -3170,21 +3428,10 @@ export default function Sidebar() {
             handleDesktopUpdateButtonClick={handleDesktopUpdateButtonClick}
             projectSortOrder={sidebarProjectSortOrder}
             threadSortOrder={sidebarThreadSortOrder}
+            projectGroupingMode={sidebarProjectGroupingMode}
+            threadPreviewCount={sidebarThreadPreviewCount}
             updateSettings={updateSettings}
-            shouldShowProjectPathEntry={shouldShowProjectPathEntry}
-            handleStartAddProject={handleStartAddProject}
-            isElectron={isElectron}
-            isPickingFolder={isPickingFolder}
-            isAddingProject={isAddingProject}
-            handlePickFolder={handlePickFolder}
-            addProjectInputRef={addProjectInputRef}
-            addProjectError={addProjectError}
-            newCwd={newCwd}
-            setNewCwd={setNewCwd}
-            setAddProjectError={setAddProjectError}
-            handleAddProject={handleAddProject}
-            setAddingProject={setAddingProject}
-            canAddProject={canAddProject}
+            openAddProject={openAddProjectCommandPalette}
             isManualProjectSorting={isManualProjectSorting}
             projectDnDSensors={projectDnDSensors}
             projectCollisionDetection={projectCollisionDetection}
diff --git a/apps/web/src/components/ThreadStatusIndicators.tsx b/apps/web/src/components/ThreadStatusIndicators.tsx
new file mode 100644
index 00000000000..5ed0c0e4c40
--- /dev/null
+++ b/apps/web/src/components/ThreadStatusIndicators.tsx
@@ -0,0 +1,250 @@
+import { scopeProjectRef, scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
+import type { VcsStatusResult } from "@t3tools/contracts";
+import { CloudIcon, GitPullRequestIcon, TerminalIcon } from "lucide-react";
+import { useMemo } from "react";
+import { usePrimaryEnvironmentId } from "../environments/primary";
+import {
+  useSavedEnvironmentRegistryStore,
+  useSavedEnvironmentRuntimeStore,
+} from "../environments/runtime";
+import { useGitStatus } from "../lib/gitStatusState";
+import { type AppState, selectProjectByRef, useStore } from "../store";
+import { selectThreadTerminalState, useTerminalStateStore } from "../terminalStateStore";
+import { useUiStateStore } from "../uiStateStore";
+import { resolveChangeRequestPresentation } from "../sourceControlPresentation";
+import { resolveThreadStatusPill, type ThreadStatusPill } from "./Sidebar.logic";
+import type { SidebarThreadSummary } from "../types";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
+
+export interface PrStatusIndicator {
+  label: string;
+  colorClass: string;
+  tooltip: string;
+  url: string;
+}
+
+export interface TerminalStatusIndicator {
+  label: "Terminal process running";
+  colorClass: string;
+  pulse: boolean;
+}
+
+export type ThreadPr = VcsStatusResult["pr"];
+
+export function prStatusIndicator(
+  pr: ThreadPr,
+  provider: VcsStatusResult["sourceControlProvider"] | null | undefined,
+): PrStatusIndicator | null {
+  if (!pr) return null;
+  const presentation = resolveChangeRequestPresentation(provider);
+
+  if (pr.state === "open") {
+    return {
+      label: `${presentation.shortName} open`,
+      colorClass: "text-emerald-600 dark:text-emerald-300/90",
+      tooltip: `#${pr.number} ${presentation.shortName} open: ${pr.title}`,
+      url: pr.url,
+    };
+  }
+  if (pr.state === "closed") {
+    return {
+      label: `${presentation.shortName} closed`,
+      colorClass: "text-zinc-500 dark:text-zinc-400/80",
+      tooltip: `#${pr.number} ${presentation.shortName} closed: ${pr.title}`,
+      url: pr.url,
+    };
+  }
+  if (pr.state === "merged") {
+    return {
+      label: `${presentation.shortName} merged`,
+      colorClass: "text-violet-600 dark:text-violet-300/90",
+      tooltip: `#${pr.number} ${presentation.shortName} merged: ${pr.title}`,
+      url: pr.url,
+    };
+  }
+  return null;
+}
+
+export function ChangeRequestStatusIcon({ className }: { className?: string }) {
+  return <GitPullRequestIcon className={className} />;
+}
+
+export function resolveThreadPr(
+  threadBranch: string | null,
+  gitStatus: VcsStatusResult | null,
+): ThreadPr | null {
+  if (threadBranch === null || gitStatus === null || gitStatus.refName !== threadBranch) {
+    return null;
+  }
+
+  return gitStatus.pr ?? null;
+}
+
+export function terminalStatusFromRunningIds(
+  runningTerminalIds: string[],
+): TerminalStatusIndicator | null {
+  if (runningTerminalIds.length === 0) {
+    return null;
+  }
+  return {
+    label: "Terminal process running",
+    colorClass: "text-teal-600 dark:text-teal-300/90",
+    pulse: true,
+  };
+}
+
+export function ThreadStatusLabel({
+  status,
+  compact = false,
+}: {
+  status: ThreadStatusPill;
+  compact?: boolean;
+}) {
+  if (compact) {
+    return (
+      <span
+        title={status.label}
+        className={`inline-flex size-3.5 shrink-0 items-center justify-center ${status.colorClass}`}
+      >
+        <span
+          className={`size-[9px] rounded-full ${status.dotClass} ${
+            status.pulse ? "animate-pulse" : ""
+          }`}
+        />
+        <span className="sr-only">{status.label}</span>
+      </span>
+    );
+  }
+
+  return (
+    <span
+      title={status.label}
+      className={`inline-flex items-center gap-1 text-[10px] ${status.colorClass}`}
+    >
+      <span
+        className={`h-1.5 w-1.5 rounded-full ${status.dotClass} ${
+          status.pulse ? "animate-pulse" : ""
+        }`}
+      />
+      <span className="hidden md:inline">{status.label}</span>
+    </span>
+  );
+}
+
+/**
+ * Non-interactive leading status icons for a thread row in compact contexts
+ * like the command palette. Shows the change request state icon (if present) and the
+ * thread status dot, matching the sidebar's leading indicators.
+ */
+export function ThreadRowLeadingStatus({ thread }: { thread: SidebarThreadSummary }) {
+  const threadRef = scopeThreadRef(thread.environmentId, thread.id);
+  const lastVisitedAt = useUiStateStore(
+    (state) => state.threadLastVisitedAtById[scopedThreadKey(threadRef)],
+  );
+  const threadProjectCwd = useStore(
+    useMemo(
+      () => (state: AppState) =>
+        selectProjectByRef(state, scopeProjectRef(thread.environmentId, thread.projectId))?.cwd ??
+        null,
+      [thread.environmentId, thread.projectId],
+    ),
+  );
+  const gitCwd = thread.worktreePath ?? threadProjectCwd;
+  const gitStatus = useGitStatus({
+    environmentId: thread.environmentId,
+    cwd: thread.branch != null ? gitCwd : null,
+  });
+  const pr = resolveThreadPr(thread.branch, gitStatus.data);
+  const prStatus = prStatusIndicator(pr, gitStatus.data?.sourceControlProvider);
+  const threadStatus = resolveThreadStatusPill({
+    thread: {
+      ...thread,
+      lastVisitedAt,
+    },
+  });
+
+  if (!prStatus && !threadStatus) {
+    return null;
+  }
+
+  return (
+    <span className="inline-flex shrink-0 items-center gap-1.5">
+      {prStatus ? (
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <span
+                aria-label={prStatus.tooltip}
+                className={`inline-flex items-center justify-center ${prStatus.colorClass}`}
+              />
+            }
+          >
+            <ChangeRequestStatusIcon className="size-3" />
+          </TooltipTrigger>
+          <TooltipPopup side="top">{prStatus.tooltip}</TooltipPopup>
+        </Tooltip>
+      ) : null}
+      {threadStatus ? <ThreadStatusLabel status={threadStatus} /> : null}
+    </span>
+  );
+}
+
+/**
+ * Non-interactive trailing status icons for a thread row in compact contexts
+ * like the command palette. Shows a terminal-running indicator and a remote
+ * environment indicator, matching the sidebar's trailing indicators.
+ */
+export function ThreadRowTrailingStatus({ thread }: { thread: SidebarThreadSummary }) {
+  const threadRef = scopeThreadRef(thread.environmentId, thread.id);
+  const runningTerminalIds = useTerminalStateStore(
+    (state) =>
+      selectThreadTerminalState(state.terminalStateByThreadKey, threadRef).runningTerminalIds,
+  );
+  const primaryEnvironmentId = usePrimaryEnvironmentId();
+  const isRemoteThread =
+    primaryEnvironmentId !== null && thread.environmentId !== primaryEnvironmentId;
+  const remoteEnvLabel = useSavedEnvironmentRuntimeStore(
+    (state) => state.byId[thread.environmentId]?.descriptor?.label ?? null,
+  );
+  const remoteEnvSavedLabel = useSavedEnvironmentRegistryStore(
+    (state) => state.byId[thread.environmentId]?.label ?? null,
+  );
+  const threadEnvironmentLabel = isRemoteThread
+    ? (remoteEnvLabel ?? remoteEnvSavedLabel ?? "Remote")
+    : null;
+  const terminalStatus = terminalStatusFromRunningIds(runningTerminalIds);
+
+  if (!terminalStatus && !isRemoteThread) {
+    return null;
+  }
+
+  return (
+    <span className="inline-flex shrink-0 items-center gap-1.5">
+      {terminalStatus ? (
+        <span
+          role="img"
+          aria-label={terminalStatus.label}
+          title={terminalStatus.label}
+          className={`inline-flex items-center justify-center ${terminalStatus.colorClass}`}
+        >
+          <TerminalIcon className={`size-3 ${terminalStatus.pulse ? "animate-pulse" : ""}`} />
+        </span>
+      ) : null}
+      {isRemoteThread ? (
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <span
+                aria-label={threadEnvironmentLabel ?? "Remote"}
+                className="inline-flex items-center justify-center"
+              />
+            }
+          >
+            <CloudIcon className="size-3 text-muted-foreground/60" />
+          </TooltipTrigger>
+          <TooltipPopup side="top">{threadEnvironmentLabel}</TooltipPopup>
+        </Tooltip>
+      ) : null}
+    </span>
+  );
+}
diff --git a/apps/web/src/components/ThreadTerminalDrawer.browser.tsx b/apps/web/src/components/ThreadTerminalDrawer.browser.tsx
index 37e0df1cc4b..2df2e04f5c4 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.browser.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.browser.tsx
@@ -177,6 +177,7 @@ async function mountTerminalViewport(props: {
       autoFocus={false}
       resizeEpoch={0}
       drawerHeight={320}
+      keybindings={[]}
     />,
     { container: host },
   );
@@ -196,6 +197,7 @@ async function mountTerminalViewport(props: {
           autoFocus={false}
           resizeEpoch={0}
           drawerHeight={320}
+          keybindings={[]}
         />,
       );
     },
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index 91f4dbc1b36..6c71e5eb334 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -1,6 +1,7 @@
 import { FitAddon } from "@xterm/addon-fit";
 import { Plus, SquareSplitHorizontal, TerminalSquare, Trash2, XIcon } from "lucide-react";
 import {
+  type ResolvedKeybindingsConfig,
   type ScopedThreadRef,
   type TerminalEvent,
   type TerminalSessionSnapshot,
@@ -28,7 +29,16 @@ import {
   resolveWrappedTerminalLinkRange,
   wrappedTerminalLinkRangeIntersectsBufferLine,
 } from "../terminal-links";
-import { isTerminalClearShortcut, terminalNavigationShortcutData } from "../keybindings";
+import {
+  isDiffToggleShortcut,
+  isTerminalClearShortcut,
+  isTerminalCloseShortcut,
+  isTerminalNewShortcut,
+  isTerminalSplitShortcut,
+  isTerminalToggleShortcut,
+  terminalDeleteShortcutData,
+  terminalNavigationShortcutData,
+} from "../keybindings";
 import {
   DEFAULT_THREAD_TERMINAL_HEIGHT,
   DEFAULT_THREAD_TERMINAL_ID,
@@ -251,6 +261,7 @@ interface TerminalViewportProps {
   autoFocus: boolean;
   resizeEpoch: number;
   drawerHeight: number;
+  keybindings: ResolvedKeybindingsConfig;
 }
 
 export function TerminalViewport({
@@ -267,6 +278,7 @@ export function TerminalViewport({
   autoFocus,
   resizeEpoch,
   drawerHeight,
+  keybindings,
 }: TerminalViewportProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const terminalRef = useRef<Terminal | null>(null);
@@ -278,6 +290,7 @@ export function TerminalViewport({
   const selectionActionRequestIdRef = useRef(0);
   const selectionActionOpenRef = useRef(false);
   const selectionActionTimerRef = useRef<number | null>(null);
+  const keybindingsRef = useRef(keybindings);
   const lastAppliedTerminalEventIdRef = useRef(0);
   const terminalHydratedRef = useRef(false);
   const handleSessionExited = useEffectEvent(() => {
@@ -288,6 +301,10 @@ export function TerminalViewport({
   });
   const readTerminalLabel = useEffectEvent(() => terminalLabel);
 
+  useEffect(() => {
+    keybindingsRef.current = keybindings;
+  }, [keybindings]);
+
   useEffect(() => {
     const mount = containerRef.current;
     if (!mount) return;
@@ -399,6 +416,18 @@ export function TerminalViewport({
     };
 
     terminal.attachCustomKeyEventHandler((event) => {
+      const currentKeybindings = keybindingsRef.current;
+      const options = { context: { terminalFocus: true, terminalOpen: true } };
+      if (
+        isTerminalToggleShortcut(event, currentKeybindings, options) ||
+        isTerminalSplitShortcut(event, currentKeybindings, options) ||
+        isTerminalNewShortcut(event, currentKeybindings, options) ||
+        isTerminalCloseShortcut(event, currentKeybindings, options) ||
+        isDiffToggleShortcut(event, currentKeybindings, options)
+      ) {
+        return false;
+      }
+
       const navigationData = terminalNavigationShortcutData(event);
       if (navigationData !== null) {
         event.preventDefault();
@@ -407,6 +436,14 @@ export function TerminalViewport({
         return false;
       }
 
+      const deleteData = terminalDeleteShortcutData(event);
+      if (deleteData !== null) {
+        event.preventDefault();
+        event.stopPropagation();
+        void sendTerminalInput(deleteData, "Failed to delete terminal input");
+        return false;
+      }
+
       if (!isTerminalClearShortcut(event)) return true;
       event.preventDefault();
       event.stopPropagation();
@@ -783,6 +820,7 @@ interface ThreadTerminalDrawerProps {
   onCloseTerminal: (terminalId: string) => void;
   onHeightChange: (height: number) => void;
   onAddTerminalContext: (selection: TerminalContextSelection) => void;
+  keybindings: ResolvedKeybindingsConfig;
 }
 
 interface TerminalActionButtonProps {
@@ -836,6 +874,7 @@ export default function ThreadTerminalDrawer({
   onCloseTerminal,
   onHeightChange,
   onAddTerminalContext,
+  keybindings,
 }: ThreadTerminalDrawerProps) {
   const [drawerHeight, setDrawerHeight] = useState(() => clampDrawerHeight(height));
   const [resizeEpoch, setResizeEpoch] = useState(0);
@@ -1154,6 +1193,7 @@ export default function ThreadTerminalDrawer({
                         autoFocus={terminalId === resolvedActiveTerminalId}
                         resizeEpoch={resizeEpoch}
                         drawerHeight={drawerHeight}
+                        keybindings={keybindings}
                       />
                     </div>
                   </div>
@@ -1176,6 +1216,7 @@ export default function ThreadTerminalDrawer({
                   autoFocus
                   resizeEpoch={resizeEpoch}
                   drawerHeight={drawerHeight}
+                  keybindings={keybindings}
                 />
               </div>
             )}
diff --git a/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts b/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts
index aed81ab01c7..9a7e484dc20 100644
--- a/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts
+++ b/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts
@@ -8,6 +8,7 @@ function makeStatus(overrides: Partial<WsConnectionStatus> = {}): WsConnectionSt
     attemptCount: 0,
     closeCode: null,
     closeReason: null,
+    connectionLabel: null,
     connectedAt: null,
     disconnectedAt: null,
     hasConnected: false,
diff --git a/apps/web/src/components/WebSocketConnectionSurface.tsx b/apps/web/src/components/WebSocketConnectionSurface.tsx
index 7b350e98496..b54bd865c8b 100644
--- a/apps/web/src/components/WebSocketConnectionSurface.tsx
+++ b/apps/web/src/components/WebSocketConnectionSurface.tsx
@@ -10,7 +10,7 @@ import {
   useWsConnectionStatus,
   WS_RECONNECT_MAX_ATTEMPTS,
 } from "../rpc/wsConnectionState";
-import { toastManager } from "./ui/toast";
+import { stackedThreadToast, toastManager } from "./ui/toast";
 import { getPrimaryEnvironmentConnection } from "../environments/runtime";
 
 const FORCED_WS_RECONNECT_DEBOUNCE_MS = 5_000;
@@ -53,8 +53,16 @@ function describeExhaustedToast(): string {
   return "Retries exhausted trying to reconnect";
 }
 
-function buildReconnectTitle(_status: WsConnectionStatus): string {
-  return "Disconnected from T3 Server";
+function getConnectionDisplayName(status: WsConnectionStatus): string {
+  return status.connectionLabel?.trim() || "T3 Server";
+}
+
+function buildReconnectTitle(status: WsConnectionStatus): string {
+  return `Disconnected from ${getConnectionDisplayName(status)}`;
+}
+
+function buildRecoveredTitle(status: WsConnectionStatus): string {
+  return `Reconnected to ${getConnectionDisplayName(status)}`;
 }
 
 function describeRecoveredToast(
@@ -75,13 +83,34 @@ function describeRecoveredToast(
   return "Connection restored.";
 }
 
-function describeSlowRpcAckToast(requests: ReadonlyArray<SlowRpcAckRequest>): ReactNode {
+function describeSlowRpcAckToast(requests: ReadonlyArray<SlowRpcAckRequest>): string {
   const count = requests.length;
   const thresholdSeconds = Math.round((requests[0]?.thresholdMs ?? 0) / 1000);
 
   return `${count} request${count === 1 ? "" : "s"} waiting longer than ${thresholdSeconds}s.`;
 }
 
+function SlowRpcAckRequestDetails({ requests }: { requests: ReadonlyArray<SlowRpcAckRequest> }) {
+  return (
+    <ul className="space-y-2.5 text-xs text-muted-foreground">
+      {requests.map((req) => (
+        <li
+          className="min-w-0 border-border/50 border-b pb-2 last:border-b-0 last:pb-0"
+          key={req.requestId}
+        >
+          <div className="wrap-break-word font-medium text-foreground">{req.tag}</div>
+          <div className="mt-0.5 font-mono text-[10px] leading-snug opacity-90">
+            {req.requestId}
+          </div>
+          <div className="mt-0.5 text-[10px] opacity-75">
+            Started {formatConnectionMoment(req.startedAt) ?? req.startedAt}
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
 export function shouldAutoReconnect(
   status: WsConnectionStatus,
   trigger: WsAutoReconnectTrigger,
@@ -138,15 +167,18 @@ export function WebSocketConnectionCoordinator() {
           console.warn("Automatic WebSocket reconnect failed", { error });
           return;
         }
-        toastManager.add({
-          type: "error",
-          title: "Reconnect failed",
-          description: error instanceof Error ? error.message : "Unable to restart the WebSocket.",
-          data: {
-            dismissAfterVisibleMs: 8_000,
-            hideCopyButton: true,
-          },
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Reconnect failed",
+            description:
+              error instanceof Error ? error.message : "Unable to restart the WebSocket.",
+            data: {
+              dismissAfterVisibleMs: 8_000,
+              hideCopyButton: true,
+            },
+          }),
+        );
       });
   });
   const syncBrowserOnlineStatus = useEffectEvent(() => {
@@ -253,45 +285,45 @@ export function WebSocketConnectionCoordinator() {
 
     if (shouldShowReconnectToast || shouldShowOfflineToast || shouldShowExhaustedToast) {
       const toastPayload = shouldShowOfflineToast
-        ? {
-            description: describeOfflineToast(),
-            timeout: 0,
-            title: "Offline",
-            type: "warning" as const,
+        ? stackedThreadToast({
             data: {
               hideCopyButton: true,
             },
-          }
+            description: describeOfflineToast(),
+            timeout: 0,
+            title: "Offline",
+            type: "warning",
+          })
         : shouldShowExhaustedToast
-          ? {
+          ? stackedThreadToast({
               actionProps: {
                 children: "Retry",
                 onClick: triggerManualReconnect,
               },
-              description: describeExhaustedToast(),
-              timeout: 0,
-              title: "Disconnected from T3 Server",
-              type: "error" as const,
               data: {
                 hideCopyButton: true,
               },
-            }
-          : {
+              description: describeExhaustedToast(),
+              timeout: 0,
+              title: buildReconnectTitle(status),
+              type: "error",
+            })
+          : stackedThreadToast({
               actionProps: {
                 children: "Retry now",
                 onClick: triggerManualReconnect,
               },
+              data: {
+                hideCopyButton: true,
+              },
               description:
                 status.nextRetryAt === null
                   ? `Reconnecting... ${formatReconnectAttemptLabel(status)}`
                   : `Reconnecting in ${formatRetryCountdown(status.nextRetryAt, nowMs)}... ${formatReconnectAttemptLabel(status)}`,
               timeout: 0,
               title: buildReconnectTitle(status),
-              type: "loading" as const,
-              data: {
-                hideCopyButton: true,
-              },
-            };
+              type: "loading",
+            });
 
       if (toastIdRef.current) {
         toastManager.update(toastIdRef.current, toastPayload);
@@ -310,7 +342,7 @@ export function WebSocketConnectionCoordinator() {
     ) {
       const successToast = {
         description: describeRecoveredToast(previousDisconnectedAt, status.connectedAt),
-        title: "Reconnected to T3 Server",
+        title: buildRecoveredTitle(status),
         type: "success" as const,
         timeout: 0,
         data: {
@@ -369,6 +401,11 @@ export function SlowRpcAckToastCoordinator() {
     }
 
     const nextToast = {
+      data: {
+        expandableContent: <SlowRpcAckRequestDetails requests={slowRequests} />,
+        expandableDescriptionTrigger: true,
+        expandableLabels: { collapse: "Hide requests", expand: "Show requests" },
+      },
       description: describeSlowRpcAckToast(slowRequests),
       timeout: 0,
       title: "Some requests are slow",
diff --git a/apps/web/src/components/auth/PairingRouteSurface.tsx b/apps/web/src/components/auth/PairingRouteSurface.tsx
index f583af72ec4..65e9c6dd8eb 100644
--- a/apps/web/src/components/auth/PairingRouteSurface.tsx
+++ b/apps/web/src/components/auth/PairingRouteSurface.tsx
@@ -2,11 +2,13 @@ import type { AuthSessionState } from "@t3tools/contracts";
 import React, { startTransition, useEffect, useRef, useState, useCallback } from "react";
 
 import { APP_DISPLAY_NAME } from "../../branding";
+import { addSavedEnvironment } from "../../environments/runtime";
 import {
   peekPairingTokenFromUrl,
   stripPairingTokenFromUrl,
   submitServerAuthCredential,
 } from "../../environments/primary";
+import { readHostedPairingRequest } from "../../hostedPairing";
 import { Button } from "../ui/button";
 import { Input } from "../ui/input";
 
@@ -159,6 +161,127 @@ export function PairingRouteSurface({
   );
 }
 
+export function HostedPairingRouteSurface() {
+  const hostedPairingRequestRef = useRef(readHostedPairingRequest());
+  const [status, setStatus] = useState<"pairing" | "paired" | "error">(() =>
+    hostedPairingRequestRef.current ? "pairing" : "error",
+  );
+  const [message, setMessage] = useState(() =>
+    hostedPairingRequestRef.current
+      ? "Connecting to this backend."
+      : "This pairing link is missing its backend host or token.",
+  );
+  const [canRetry, setCanRetry] = useState(false);
+  const submitAttemptedRef = useRef(false);
+  const tokenSubmittedRef = useRef(false);
+
+  const submitHostedPairingRequest = useCallback(async () => {
+    const request = hostedPairingRequestRef.current;
+
+    if (!request) {
+      setStatus("error");
+      setMessage("This pairing link is missing its backend host or token.");
+      setCanRetry(false);
+      return;
+    }
+
+    if (tokenSubmittedRef.current) {
+      setStatus("error");
+      setMessage("This one-time pairing token was already submitted. Request a new pairing link.");
+      setCanRetry(false);
+      return;
+    }
+
+    setStatus("pairing");
+    setMessage("Connecting to this backend.");
+    setCanRetry(false);
+    tokenSubmittedRef.current = true;
+
+    try {
+      const record = await addSavedEnvironment({
+        label: request.label,
+        host: request.host,
+        pairingCode: request.token,
+      });
+      setStatus("paired");
+      setMessage(`${record.label} is saved in this browser.`);
+    } catch (error) {
+      tokenSubmittedRef.current = false;
+      setStatus("error");
+      setCanRetry(true);
+      setMessage(
+        `${errorMessageFromUnknown(error)} If the backend accepted this one-time token, request a new pairing link before retrying.`,
+      );
+    }
+  }, []);
+
+  useEffect(() => {
+    if (submitAttemptedRef.current) {
+      return;
+    }
+    submitAttemptedRef.current = true;
+
+    stripPairingTokenFromUrl();
+    void submitHostedPairingRequest();
+  }, [submitHostedPairingRequest]);
+
+  const request = hostedPairingRequestRef.current;
+
+  return (
+    <div className="relative flex min-h-screen items-center justify-center overflow-hidden bg-background px-4 py-10 text-foreground sm:px-6">
+      <div className="pointer-events-none absolute inset-0 opacity-80">
+        <div className="absolute inset-x-0 top-0 h-44 bg-[radial-gradient(44rem_16rem_at_top,color-mix(in_srgb,var(--color-emerald-500)_14%,transparent),transparent)]" />
+        <div className="absolute inset-y-0 left-0 w-72 bg-[radial-gradient(28rem_18rem_at_left,color-mix(in_srgb,var(--color-sky-500)_10%,transparent),transparent)]" />
+        <div className="absolute inset-0 bg-[linear-gradient(145deg,color-mix(in_srgb,var(--background)_90%,var(--color-black))_0%,var(--background)_55%)]" />
+      </div>
+
+      <section className="relative w-full max-w-xl rounded-2xl border border-border/80 bg-card/90 p-6 shadow-2xl shadow-black/20 backdrop-blur-md sm:p-8">
+        <p className="text-[11px] font-semibold tracking-[0.18em] text-muted-foreground uppercase">
+          {APP_DISPLAY_NAME}
+        </p>
+        <h1 className="mt-3 text-2xl font-semibold tracking-tight sm:text-3xl">
+          {status === "paired"
+            ? "Backend paired"
+            : status === "error"
+              ? "Pairing failed"
+              : "Pairing backend"}
+        </h1>
+        <p className="mt-2 text-sm leading-relaxed text-muted-foreground">{message}</p>
+
+        {request ? (
+          <div className="mt-5 rounded-lg border border-border/70 bg-background/55 px-3 py-3 text-xs leading-relaxed text-muted-foreground">
+            Host: <span className="font-mono text-foreground/80">{request.host}</span>
+          </div>
+        ) : null}
+
+        {status === "error" ? (
+          <div className="mt-5 rounded-lg border border-destructive/30 bg-destructive/6 px-3 py-2 text-sm text-destructive">
+            Verify the backend is reachable from this browser, supports CORS for hosted clients, and
+            is served over HTTPS when opening this page from HTTPS.
+          </div>
+        ) : null}
+
+        <div className="mt-6 flex flex-wrap gap-2">
+          {status === "pairing" ? (
+            <Button disabled size="sm">
+              Pairing...
+            </Button>
+          ) : canRetry ? (
+            <Button size="sm" onClick={() => void submitHostedPairingRequest()}>
+              Try again
+            </Button>
+          ) : null}
+          {status === "paired" ? (
+            <Button size="sm" variant="outline" onClick={() => (window.location.href = "/")}>
+              Open app
+            </Button>
+          ) : null}
+        </div>
+      </section>
+    </div>
+  );
+}
+
 function errorMessageFromUnknown(error: unknown): string {
   if (error instanceof Error && error.message.trim().length > 0) {
     return error.message;
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index cabac8272b0..96fc34c1013 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -5,7 +5,7 @@ import type {
   ProjectEntry,
   ProviderApprovalDecision,
   ProviderInteractionMode,
-  ProviderKind,
+  ResolvedKeybindingsConfig,
   RuntimeMode,
   ScopedThreadRef,
   ServerProvider,
@@ -13,12 +13,13 @@ import type {
   TurnId,
 } from "@t3tools/contracts";
 import {
+  ProviderDriverKind,
+  ProviderInstanceId,
   PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
   PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
 } from "@t3tools/contracts";
-import { normalizeModelSlug } from "@t3tools/shared/model";
+import { createModelSelection, normalizeModelSlug } from "@t3tools/shared/model";
 import {
-  forwardRef,
   memo,
   useCallback,
   useEffect,
@@ -59,7 +60,7 @@ import {
   shouldUseCompactComposerFooter,
 } from "../composerFooterLayout";
 import { type ComposerPromptEditorHandle, ComposerPromptEditor } from "../ComposerPromptEditor";
-import { AVAILABLE_PROVIDER_OPTIONS, ProviderModelPicker } from "./ProviderModelPicker";
+import { ProviderModelPicker } from "./ProviderModelPicker";
 import { type ComposerCommandItem, ComposerCommandMenu } from "./ComposerCommandMenu";
 import { ComposerPendingApprovalActions } from "./ComposerPendingApprovalActions";
 import { CompactComposerControlsMenu } from "./CompactComposerControlsMenu";
@@ -73,7 +74,7 @@ import {
   getComposerProviderState,
   renderProviderTraitsMenuContent,
   renderProviderTraitsPicker,
-} from "./composerProviderRegistry";
+} from "./composerProviderState";
 import { ContextWindowMeter } from "./ContextWindowMeter";
 import { buildExpandedImagePreview, type ExpandedImagePreview } from "./ExpandedImagePreview";
 import { basenameOfPath } from "../../vscode-icons";
@@ -94,7 +95,14 @@ import {
   XIcon,
 } from "lucide-react";
 import { proposedPlanTitle } from "../../proposedPlan";
-import { resolveSelectableProvider, getProviderModels } from "../../providerModels";
+import { getProviderInteractionModeToggle } from "../../providerModels";
+import {
+  deriveProviderInstanceEntries,
+  resolveProviderDriverKindForInstanceSelection,
+  sortProviderInstanceEntries,
+  type ProviderInstanceEntry,
+} from "../../providerInstances";
+import { type AppModelOption, getAppModelOptionsForInstance } from "../../modelSelection";
 import type { UnifiedSettings } from "@t3tools/contracts/settings";
 import type { SessionPhase, Thread } from "../../types";
 import type { PendingUserInputDraftAnswer } from "../../pendingUserInput";
@@ -102,6 +110,7 @@ import type { PendingApproval, PendingUserInput } from "../../session-logic";
 import { deriveLatestContextWindowSnapshot } from "../../lib/contextWindow";
 import { formatProviderSkillDisplayName } from "../../providerSkillPresentation";
 import { searchProviderSkills } from "../../providerSkillSearch";
+import { useMediaQuery } from "../../hooks/useMediaQuery";
 
 const IMAGE_SIZE_LIMIT_LABEL = `${Math.round(PROVIDER_SEND_TURN_MAX_IMAGE_BYTES / (1024 * 1024))}MB`;
 
@@ -129,6 +138,13 @@ const runtimeModeConfig: Record<
 const runtimeModeOptions = Object.keys(runtimeModeConfig) as RuntimeMode[];
 const COMPOSER_PATH_QUERY_DEBOUNCE_MS = 120;
 const EMPTY_PROJECT_ENTRIES: ProjectEntry[] = [];
+const COMPOSER_FLOATING_LAYER_SELECTOR = [
+  '[data-slot="popover-popup"]',
+  '[data-slot="menu-popup"]',
+  '[data-slot="select-popup"]',
+  '[data-slot="combobox-popup"]',
+  '[data-slot="autocomplete-popup"]',
+].join(",");
 
 const extendReplacementRangeForTrailingSpace = (
   text: string,
@@ -158,10 +174,16 @@ const terminalContextIdListsEqual = (
 ): boolean =>
   contexts.length === ids.length && contexts.every((context, index) => context.id === ids[index]);
 
+function isInsideComposerFloatingLayer(element: Element): boolean {
+  return element.closest(COMPOSER_FLOATING_LAYER_SELECTOR) !== null;
+}
+
 const ComposerFooterModeControls = memo(function ComposerFooterModeControls(props: {
+  showInteractionModeToggle: boolean;
   interactionMode: ProviderInteractionMode;
   runtimeMode: RuntimeMode;
   showPlanToggle: boolean;
+  planSidebarLabel: string;
   planSidebarOpen: boolean;
   onToggleInteractionMode: () => void;
   onRuntimeModeChange: (mode: RuntimeMode) => void;
@@ -174,25 +196,29 @@ const ComposerFooterModeControls = memo(function ComposerFooterModeControls(prop
     <>
       <Separator orientation="vertical" className="mx-0.5 hidden h-4 sm:block" />
 
-      <Button
-        variant="ghost"
-        className="shrink-0 whitespace-nowrap px-2 text-muted-foreground/70 hover:text-foreground/80 sm:px-3"
-        size="sm"
-        type="button"
-        onClick={props.onToggleInteractionMode}
-        title={
-          props.interactionMode === "plan"
-            ? "Plan mode — click to return to normal build mode"
-            : "Default mode — click to enter plan mode"
-        }
-      >
-        <BotIcon />
-        <span className="sr-only sm:not-sr-only">
-          {props.interactionMode === "plan" ? "Plan" : "Build"}
-        </span>
-      </Button>
+      {props.showInteractionModeToggle ? (
+        <>
+          <Button
+            variant="ghost"
+            className="shrink-0 whitespace-nowrap px-2 text-muted-foreground/70 hover:text-foreground/80 sm:px-3"
+            size="sm"
+            type="button"
+            onClick={props.onToggleInteractionMode}
+            title={
+              props.interactionMode === "plan"
+                ? "Plan mode — click to return to normal build mode"
+                : "Default mode — click to enter plan mode"
+            }
+          >
+            <BotIcon />
+            <span className="sr-only sm:not-sr-only">
+              {props.interactionMode === "plan" ? "Plan" : "Build"}
+            </span>
+          </Button>
 
-      <Separator orientation="vertical" className="mx-0.5 hidden h-4 sm:block" />
+          <Separator orientation="vertical" className="mx-0.5 hidden h-4 sm:block" />
+        </>
+      ) : null}
 
       <Select
         value={props.runtimeMode}
@@ -243,10 +269,14 @@ const ComposerFooterModeControls = memo(function ComposerFooterModeControls(prop
             size="sm"
             type="button"
             onClick={props.onTogglePlanSidebar}
-            title={props.planSidebarOpen ? "Hide plan sidebar" : "Show plan sidebar"}
+            title={
+              props.planSidebarOpen
+                ? `Hide ${props.planSidebarLabel.toLowerCase()} sidebar`
+                : `Show ${props.planSidebarLabel.toLowerCase()} sidebar`
+            }
           >
             <ListTodoIcon />
-            <span className="sr-only sm:not-sr-only">Plan</span>
+            <span className="sr-only sm:not-sr-only">{props.planSidebarLabel}</span>
           </Button>
         </>
       ) : null}
@@ -270,7 +300,9 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
   promptHasText: boolean;
   isSendBusy: boolean;
   isConnecting: boolean;
+  isEnvironmentUnavailable: boolean;
   hasSendableContent: boolean;
+  preserveComposerFocusOnPointerDown?: boolean;
   onPreviousPendingQuestion: () => void;
   onInterrupt: () => void;
   onImplementPlanInNewThread: () => void;
@@ -289,8 +321,10 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
         promptHasText={props.promptHasText}
         isSendBusy={props.isSendBusy}
         isConnecting={props.isConnecting}
+        isEnvironmentUnavailable={props.isEnvironmentUnavailable}
         isPreparingWorktree={props.isPreparingWorktree}
         hasSendableContent={props.hasSendableContent}
+        preserveComposerFocusOnPointerDown={props.preserveComposerFocusOnPointerDown ?? false}
         onPreviousPendingQuestion={props.onPreviousPendingQuestion}
         onInterrupt={props.onInterrupt}
         onImplementPlanInNewThread={props.onImplementPlanInNewThread}
@@ -306,6 +340,9 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
 export interface ChatComposerHandle {
   focusAtEnd: () => void;
   focusAt: (cursor: number) => void;
+  openModelPicker: () => void;
+  toggleModelPicker: () => void;
+  isModelPickerOpen: () => boolean;
   readSnapshot: () => {
     value: string;
     cursor: number;
@@ -328,7 +365,7 @@ export interface ChatComposerHandle {
     selectedPromptEffort: string | null;
     selectedModelOptionsForDispatch: unknown;
     selectedModelSelection: ModelSelection;
-    selectedProvider: ProviderKind;
+    selectedProvider: ProviderDriverKind;
     selectedModel: string;
     selectedProviderModels: ReadonlyArray<ServerProvider["models"][number]>;
   };
@@ -357,6 +394,10 @@ export interface ChatComposerProps {
   isConnecting: boolean;
   isSendBusy: boolean;
   isPreparingWorktree: boolean;
+  environmentUnavailable: {
+    readonly label: string;
+    readonly connectionState: "connecting" | "disconnected" | "error";
+  } | null;
 
   // Pending approvals / inputs
   activePendingApproval: PendingApproval | null;
@@ -367,7 +408,7 @@ export interface ChatComposerProps {
     isLastQuestion: boolean;
     canAdvance: boolean;
     customAnswer: string;
-    activeQuestion: { id: string } | null;
+    activeQuestion: { id: string; multiSelect?: boolean | undefined } | null;
   } | null;
   activePendingResolvedAnswers: Record<string, unknown> | null;
   activePendingIsResponding: boolean;
@@ -380,6 +421,7 @@ export interface ChatComposerProps {
   activeProposedPlan: Thread["proposedPlans"][number] | null;
   activePlan: { turnId?: TurnId } | null;
   sidebarProposedPlan: { turnId?: TurnId } | null;
+  planSidebarLabel: string;
   planSidebarOpen: boolean;
 
   // Mode
@@ -387,7 +429,7 @@ export interface ChatComposerProps {
   interactionMode: ProviderInteractionMode;
 
   // Provider / model
-  lockedProvider: ProviderKind | null;
+  lockedProvider: ProviderDriverKind | null;
   providerStatuses: ServerProvider[];
   activeProjectDefaultModelSelection: ModelSelection | null | undefined;
   activeThreadModelSelection: ModelSelection | null | undefined;
@@ -398,15 +440,18 @@ export interface ChatComposerProps {
   // Misc
   resolvedTheme: "light" | "dark";
   settings: UnifiedSettings;
+  keybindings: ResolvedKeybindingsConfig;
+  terminalOpen: boolean;
   gitCwd: string | null;
 
   // Refs the parent needs kept in sync
-  promptRef: React.MutableRefObject<string>;
-  composerImagesRef: React.MutableRefObject<ComposerImageAttachment[]>;
-  composerTerminalContextsRef: React.MutableRefObject<TerminalContextDraft[]>;
+  promptRef: React.RefObject<string>;
+  composerImagesRef: React.RefObject<ComposerImageAttachment[]>;
+  composerTerminalContextsRef: React.RefObject<TerminalContextDraft[]>;
+  composerRef: React.RefObject<ChatComposerHandle | null>;
 
   // Scroll
-  shouldAutoScrollRef: React.MutableRefObject<boolean>;
+  shouldAutoScrollRef: React.RefObject<boolean>;
   scheduleStickToBottom: () => void;
 
   // Callbacks
@@ -428,7 +473,7 @@ export interface ChatComposerProps {
     cursorAdjacentToMention: boolean,
   ) => void;
 
-  onProviderModelSelect: (provider: ProviderKind, model: string) => void;
+  onProviderModelSelect: (instanceId: ProviderInstanceId, model: string) => void;
   toggleInteractionMode: () => void;
   handleRuntimeModeChange: (mode: RuntimeMode) => void;
   handleInteractionModeChange: (mode: ProviderInteractionMode) => void;
@@ -444,317 +489,423 @@ export interface ChatComposerProps {
 // Component
 // --------------------------------------------------------------------------
 
-export const ChatComposer = memo(
-  forwardRef<ChatComposerHandle, ChatComposerProps>(function ChatComposer(props, ref) {
-    const {
-      composerDraftTarget,
-      environmentId,
-      routeKind,
-      routeThreadRef,
-      draftId,
-      activeThreadId,
-      activeThreadEnvironmentId: _activeThreadEnvironmentId,
-      activeThread,
-      isServerThread: _isServerThread,
-      isLocalDraftThread: _isLocalDraftThread,
-      phase,
-      isConnecting,
-      isSendBusy,
-      isPreparingWorktree,
-      activePendingApproval,
-      pendingApprovals,
-      pendingUserInputs,
-      activePendingProgress,
-      activePendingResolvedAnswers,
-      activePendingIsResponding,
-      activePendingDraftAnswers,
-      activePendingQuestionIndex,
-      respondingRequestIds,
-      showPlanFollowUpPrompt,
-      activeProposedPlan,
-      activePlan,
-      sidebarProposedPlan,
-      planSidebarOpen,
-      runtimeMode,
-      interactionMode,
-      lockedProvider,
+export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps) {
+  const {
+    composerDraftTarget,
+    environmentId,
+    routeKind,
+    routeThreadRef,
+    draftId,
+    activeThreadId,
+    activeThreadEnvironmentId: _activeThreadEnvironmentId,
+    activeThread,
+    isServerThread: _isServerThread,
+    isLocalDraftThread: _isLocalDraftThread,
+    phase,
+    isConnecting,
+    isSendBusy,
+    isPreparingWorktree,
+    environmentUnavailable,
+    activePendingApproval,
+    pendingApprovals,
+    pendingUserInputs,
+    activePendingProgress,
+    activePendingResolvedAnswers,
+    activePendingIsResponding,
+    activePendingDraftAnswers,
+    activePendingQuestionIndex,
+    respondingRequestIds,
+    showPlanFollowUpPrompt,
+    activeProposedPlan,
+    activePlan,
+    sidebarProposedPlan,
+    planSidebarLabel,
+    planSidebarOpen,
+    runtimeMode,
+    interactionMode,
+    lockedProvider,
+    providerStatuses,
+    activeProjectDefaultModelSelection,
+    activeThreadModelSelection,
+    activeThreadActivities,
+    resolvedTheme,
+    settings,
+    keybindings,
+    terminalOpen,
+    gitCwd,
+    promptRef,
+    composerRef,
+    composerImagesRef,
+    composerTerminalContextsRef,
+    shouldAutoScrollRef,
+    scheduleStickToBottom,
+    onSend,
+    onInterrupt,
+    onImplementPlanInNewThread,
+    onRespondToApproval,
+    onSelectActivePendingUserInputOption,
+    onAdvanceActivePendingUserInput,
+    onPreviousActivePendingUserInputQuestion,
+    onChangeActivePendingUserInputCustomAnswer,
+    onProviderModelSelect,
+    toggleInteractionMode,
+    handleRuntimeModeChange,
+    handleInteractionModeChange,
+    togglePlanSidebar,
+    focusComposer,
+    scheduleComposerFocus,
+    setThreadError,
+    onExpandImage,
+  } = props;
+
+  // ------------------------------------------------------------------
+  // Store subscriptions (prompt / images / terminal contexts)
+  // ------------------------------------------------------------------
+  const composerDraft = useComposerThreadDraft(composerDraftTarget);
+  const prompt = composerDraft.prompt;
+  const composerImages = composerDraft.images;
+  const composerTerminalContexts = composerDraft.terminalContexts;
+  const nonPersistedComposerImageIds = composerDraft.nonPersistedImageIds;
+
+  const setComposerDraftPrompt = useComposerDraftStore((store) => store.setPrompt);
+  const addComposerDraftImage = useComposerDraftStore((store) => store.addImage);
+  const addComposerDraftImages = useComposerDraftStore((store) => store.addImages);
+  const removeComposerDraftImage = useComposerDraftStore((store) => store.removeImage);
+  const insertComposerDraftTerminalContext = useComposerDraftStore(
+    (store) => store.insertTerminalContext,
+  );
+  const removeComposerDraftTerminalContext = useComposerDraftStore(
+    (store) => store.removeTerminalContext,
+  );
+  const setComposerDraftTerminalContexts = useComposerDraftStore(
+    (store) => store.setTerminalContexts,
+  );
+  const clearComposerDraftPersistedAttachments = useComposerDraftStore(
+    (store) => store.clearPersistedAttachments,
+  );
+  const syncComposerDraftPersistedAttachments = useComposerDraftStore(
+    (store) => store.syncPersistedAttachments,
+  );
+  const getComposerDraft = useComposerDraftStore((store) => store.getComposerDraft);
+
+  // ------------------------------------------------------------------
+  // Model state
+  // ------------------------------------------------------------------
+  // Instance-aware projection of the wire provider list. One entry per
+  // configured instance (default built-in + any custom `providerInstances.*`),
+  // sorted default-first per driver kind for a stable picker order.
+  const providerInstanceEntries = useMemo<ReadonlyArray<ProviderInstanceEntry>>(
+    () => sortProviderInstanceEntries(deriveProviderInstanceEntries(providerStatuses)),
+    [providerStatuses],
+  );
+  const selectedProviderByThreadId = composerDraft.activeProvider ?? null;
+  const threadProvider =
+    activeThread?.session?.providerInstanceId ??
+    activeThreadModelSelection?.instanceId ??
+    activeProjectDefaultModelSelection?.instanceId ??
+    null;
+  const explicitSelectedInstanceId = selectedProviderByThreadId ?? threadProvider;
+
+  const unlockedSelectedProvider =
+    resolveProviderDriverKindForInstanceSelection(
+      providerInstanceEntries,
       providerStatuses,
-      activeProjectDefaultModelSelection,
-      activeThreadModelSelection,
-      activeThreadActivities,
-      resolvedTheme,
-      settings,
-      gitCwd,
-      promptRef,
-      composerImagesRef,
-      composerTerminalContextsRef,
-      shouldAutoScrollRef,
-      scheduleStickToBottom,
-      onSend,
-      onInterrupt,
-      onImplementPlanInNewThread,
-      onRespondToApproval,
-      onSelectActivePendingUserInputOption,
-      onAdvanceActivePendingUserInput,
-      onPreviousActivePendingUserInputQuestion,
-      onChangeActivePendingUserInputCustomAnswer,
-      onProviderModelSelect,
-      toggleInteractionMode,
-      handleRuntimeModeChange,
-      handleInteractionModeChange,
-      togglePlanSidebar,
-      focusComposer,
-      scheduleComposerFocus,
-      setThreadError,
-      onExpandImage,
-    } = props;
-
-    // ------------------------------------------------------------------
-    // Store subscriptions (prompt / images / terminal contexts)
-    // ------------------------------------------------------------------
-    const composerDraft = useComposerThreadDraft(composerDraftTarget);
-    const prompt = composerDraft.prompt;
-    const composerImages = composerDraft.images;
-    const composerTerminalContexts = composerDraft.terminalContexts;
-    const nonPersistedComposerImageIds = composerDraft.nonPersistedImageIds;
-
-    const setComposerDraftPrompt = useComposerDraftStore((store) => store.setPrompt);
-    const addComposerDraftImage = useComposerDraftStore((store) => store.addImage);
-    const addComposerDraftImages = useComposerDraftStore((store) => store.addImages);
-    const removeComposerDraftImage = useComposerDraftStore((store) => store.removeImage);
-    const insertComposerDraftTerminalContext = useComposerDraftStore(
-      (store) => store.insertTerminalContext,
-    );
-    const removeComposerDraftTerminalContext = useComposerDraftStore(
-      (store) => store.removeTerminalContext,
-    );
-    const setComposerDraftTerminalContexts = useComposerDraftStore(
-      (store) => store.setTerminalContexts,
-    );
-    const clearComposerDraftPersistedAttachments = useComposerDraftStore(
-      (store) => store.clearPersistedAttachments,
-    );
-    const syncComposerDraftPersistedAttachments = useComposerDraftStore(
-      (store) => store.syncPersistedAttachments,
+      explicitSelectedInstanceId,
+    ) ?? ProviderDriverKind.make("codex");
+  const selectedProvider: ProviderDriverKind = lockedProvider ?? unlockedSelectedProvider;
+  const lockedContinuationGroupKey = useMemo((): string | null => {
+    if (!lockedProvider || !activeThread) return null;
+    const lockedInstanceId =
+      activeThread.session?.providerInstanceId ?? activeThreadModelSelection?.instanceId;
+    if (!lockedInstanceId) return null;
+    return (
+      providerInstanceEntries.find((entry) => entry.instanceId === lockedInstanceId)
+        ?.continuationGroupKey ?? null
     );
-    const getComposerDraft = useComposerDraftStore((store) => store.getComposerDraft);
-
-    // ------------------------------------------------------------------
-    // Model state
-    // ------------------------------------------------------------------
-    const selectedProviderByThreadId = composerDraft.activeProvider ?? null;
-    const threadProvider =
-      activeThreadModelSelection?.provider ?? activeProjectDefaultModelSelection?.provider ?? null;
-
-    const unlockedSelectedProvider = resolveSelectableProvider(
-      providerStatuses,
-      selectedProviderByThreadId ?? threadProvider ?? "codex",
+  }, [
+    activeThread,
+    activeThreadModelSelection?.instanceId,
+    lockedProvider,
+    providerInstanceEntries,
+  ]);
+
+  // Resolve which configured instance the composer is currently targeting.
+  // Priority:
+  //   1. The composer draft's `activeProvider` — the user's unsaved pick
+  //      from the model picker (must win, otherwise the UI appears to
+  //      ignore picker selections).
+  //   2. Thread's persisted instance id (server-side saved selection).
+  //   3. Project default's instance id.
+  //   4. First enabled entry matching the current driver kind.
+  //   5. First enabled entry overall / default instance for the kind.
+  //
+  const selectedInstanceId = useMemo<ProviderInstanceId>(() => {
+    const candidates: Array<string | null | undefined> = [
+      composerDraft.activeProvider,
+      activeThread?.session?.providerInstanceId,
+      activeThreadModelSelection?.instanceId,
+      activeProjectDefaultModelSelection?.instanceId,
+    ];
+    for (const candidate of candidates) {
+      if (!candidate) continue;
+      const match = providerInstanceEntries.find(
+        (entry) => entry.instanceId === candidate && entry.enabled,
+      );
+      if (match) {
+        // When locked to a specific driver kind, ignore persisted instance
+        // ids from a different kind or continuation group.
+        if (lockedProvider && match.driverKind !== lockedProvider) continue;
+        if (
+          lockedContinuationGroupKey &&
+          match.continuationGroupKey !== lockedContinuationGroupKey
+        ) {
+          continue;
+        }
+        return match.instanceId;
+      }
+    }
+    if (explicitSelectedInstanceId) {
+      return ProviderInstanceId.make(explicitSelectedInstanceId);
+    }
+    const byKind = providerInstanceEntries.find(
+      (entry) =>
+        entry.enabled &&
+        entry.driverKind === selectedProvider &&
+        (!lockedContinuationGroupKey || entry.continuationGroupKey === lockedContinuationGroupKey),
     );
-    const selectedProvider: ProviderKind = lockedProvider ?? unlockedSelectedProvider;
-
-    const { modelOptions: composerModelOptions, selectedModel } = useEffectiveComposerModelState({
-      threadRef: composerDraftTarget,
-      providers: providerStatuses,
-      selectedProvider,
-      threadModelSelection: activeThreadModelSelection,
-      projectModelSelection: activeProjectDefaultModelSelection,
-      settings,
-    });
-
-    const selectedProviderModels = getProviderModels(providerStatuses, selectedProvider);
-    const selectedProviderStatus = useMemo(
-      () => providerStatuses.find((provider) => provider.provider === selectedProvider),
-      [providerStatuses, selectedProvider],
+    if (byKind) return byKind.instanceId;
+    const anyEnabled = providerInstanceEntries.find((entry) => entry.enabled);
+    return (
+      anyEnabled?.instanceId ??
+      providerInstanceEntries[0]?.instanceId ??
+      activeThreadModelSelection?.instanceId ??
+      activeProjectDefaultModelSelection?.instanceId ??
+      ProviderInstanceId.make("codex")
     );
+  }, [
+    activeProjectDefaultModelSelection?.instanceId,
+    activeThread?.session?.providerInstanceId,
+    activeThreadModelSelection?.instanceId,
+    composerDraft.activeProvider,
+    explicitSelectedInstanceId,
+    lockedContinuationGroupKey,
+    lockedProvider,
+    providerInstanceEntries,
+    selectedProvider,
+  ]);
+
+  const { modelOptions: composerModelOptions, selectedModel } = useEffectiveComposerModelState({
+    threadRef: composerDraftTarget,
+    providers: providerStatuses,
+    selectedProvider,
+    selectedInstanceId,
+    threadModelSelection: activeThreadModelSelection,
+    projectModelSelection: activeProjectDefaultModelSelection,
+    settings,
+  });
 
-    const composerProviderState = useMemo(
-      () =>
-        getComposerProviderState({
-          provider: selectedProvider,
-          model: selectedModel,
-          models: selectedProviderModels,
-          prompt,
-          modelOptions: composerModelOptions,
-        }),
-      [composerModelOptions, prompt, selectedModel, selectedProvider, selectedProviderModels],
-    );
+  // Resolve the active instance's snapshot by `instanceId` so a custom
+  // instance gets its own slash commands, skills, and model list — not
+  // the first snapshot for the same driver kind.
+  const selectedProviderEntry = useMemo(
+    () => providerInstanceEntries.find((entry) => entry.instanceId === selectedInstanceId),
+    [providerInstanceEntries, selectedInstanceId],
+  );
+  const selectedProviderStatus = useMemo(
+    () => selectedProviderEntry?.snapshot ?? null,
+    [selectedProviderEntry],
+  );
+  const selectedProviderModels = useMemo<ReadonlyArray<ServerProvider["models"][number]>>(
+    () => selectedProviderEntry?.models ?? [],
+    [selectedProviderEntry],
+  );
 
-    const selectedPromptEffort = composerProviderState.promptEffort;
-    const selectedModelOptionsForDispatch = composerProviderState.modelOptionsForDispatch;
-    const selectedModelSelection = useMemo<ModelSelection>(
-      () => ({
+  const composerProviderState = useMemo(
+    () =>
+      getComposerProviderState({
         provider: selectedProvider,
         model: selectedModel,
-        ...(selectedModelOptionsForDispatch ? { options: selectedModelOptionsForDispatch } : {}),
+        models: selectedProviderModels,
+        prompt,
+        modelOptions: composerModelOptions?.[selectedProvider],
       }),
-      [selectedModel, selectedModelOptionsForDispatch, selectedProvider],
-    );
-    const selectedModelForPicker = selectedModel;
-    const modelOptionsByProvider = useMemo<
-      Record<ProviderKind, ReadonlyArray<ServerProvider["models"][number]>>
-    >(
-      () => ({
-        codex: providerStatuses.find((provider) => provider.provider === "codex")?.models ?? [],
-        claudeAgent:
-          providerStatuses.find((provider) => provider.provider === "claudeAgent")?.models ?? [],
-      }),
-      [providerStatuses],
-    );
-    const selectedModelForPickerWithCustomFallback = useMemo(() => {
-      const currentOptions = modelOptionsByProvider[selectedProvider];
-      return currentOptions.some((option) => option.slug === selectedModelForPicker)
-        ? selectedModelForPicker
-        : (normalizeModelSlug(selectedModelForPicker, selectedProvider) ?? selectedModelForPicker);
-    }, [modelOptionsByProvider, selectedModelForPicker, selectedProvider]);
-    const searchableModelOptions = useMemo(
-      () =>
-        AVAILABLE_PROVIDER_OPTIONS.filter(
-          (option) => lockedProvider === null || option.value === lockedProvider,
-        ).flatMap((option) =>
-          modelOptionsByProvider[option.value].map(({ slug, name }) => ({
-            provider: option.value,
-            providerLabel: option.label,
-            slug,
-            name,
-            searchSlug: slug.toLowerCase(),
-            searchName: name.toLowerCase(),
-            searchProvider: option.label.toLowerCase(),
-          })),
-        ),
-      [lockedProvider, modelOptionsByProvider],
-    );
-
-    // ------------------------------------------------------------------
-    // Context window
-    // ------------------------------------------------------------------
-    const activeContextWindow = useMemo(
-      () => deriveLatestContextWindowSnapshot(activeThreadActivities ?? []),
-      [activeThreadActivities],
-    );
+    [composerModelOptions, prompt, selectedModel, selectedProvider, selectedProviderModels],
+  );
 
-    // ------------------------------------------------------------------
-    // Composer-local state
-    // ------------------------------------------------------------------
-    const [composerCursor, setComposerCursor] = useState(() =>
-      collapseExpandedComposerCursor(prompt, prompt.length),
-    );
-    const [composerTrigger, setComposerTrigger] = useState<ComposerTrigger | null>(() =>
-      detectComposerTrigger(prompt, prompt.length),
-    );
-    const [composerHighlightedItemId, setComposerHighlightedItemId] = useState<string | null>(null);
-    const [composerHighlightedSearchKey, setComposerHighlightedSearchKey] = useState<string | null>(
-      null,
-    );
-    const [isDragOverComposer, setIsDragOverComposer] = useState(false);
-    const [isComposerFooterCompact, setIsComposerFooterCompact] = useState(false);
-    const [isComposerPrimaryActionsCompact, setIsComposerPrimaryActionsCompact] = useState(false);
-
-    // ------------------------------------------------------------------
-    // Refs
-    // ------------------------------------------------------------------
-    const composerEditorRef = useRef<ComposerPromptEditorHandle>(null);
-    const composerFormRef = useRef<HTMLFormElement>(null);
-    const composerFormHeightRef = useRef(0);
-    const composerSelectLockRef = useRef(false);
-    const composerMenuOpenRef = useRef(false);
-    const composerMenuItemsRef = useRef<ComposerCommandItem[]>([]);
-    const activeComposerMenuItemRef = useRef<ComposerCommandItem | null>(null);
-    const dragDepthRef = useRef(0);
-
-    // ------------------------------------------------------------------
-    // Derived: composer send state
-    // ------------------------------------------------------------------
-    const composerSendState = useMemo(
-      () =>
-        deriveComposerSendState({
-          prompt,
-          imageCount: composerImages.length,
-          terminalContexts: composerTerminalContexts,
-        }),
-      [composerImages.length, composerTerminalContexts, prompt],
-    );
+  const selectedPromptEffort = composerProviderState.promptEffort;
+  const selectedModelOptionsForDispatch = composerProviderState.modelOptionsForDispatch;
+  const composerProviderControls = useMemo(
+    () => ({
+      showInteractionModeToggle: getProviderInteractionModeToggle(
+        providerStatuses,
+        selectedProvider,
+      ),
+    }),
+    [providerStatuses, selectedProvider],
+  );
+  const selectedModelSelection = useMemo<ModelSelection>(
+    () => createModelSelection(selectedInstanceId, selectedModel, selectedModelOptionsForDispatch),
+    [selectedInstanceId, selectedModel, selectedModelOptionsForDispatch],
+  );
+  const selectedModelForPicker = selectedModel;
+  // Instance-keyed option list so the picker can show each configured
+  // instance (built-in + custom) as a first-class sidebar entry. The
+  // options are server-reported models plus that exact instance's
+  // configured custom models; selected slugs are not injected into lists.
+  const modelOptionsByInstance = useMemo<
+    ReadonlyMap<ProviderInstanceId, ReadonlyArray<AppModelOption>>
+  >(() => {
+    const out = new Map<ProviderInstanceId, ReadonlyArray<AppModelOption>>();
+    for (const entry of providerInstanceEntries) {
+      out.set(entry.instanceId, getAppModelOptionsForInstance(settings, entry));
+    }
+    return out;
+  }, [providerInstanceEntries, settings]);
+  const selectedModelForPickerWithCustomFallback = useMemo(() => {
+    const currentOptions = modelOptionsByInstance.get(selectedInstanceId) ?? [];
+    return currentOptions.some((option) => option.slug === selectedModelForPicker)
+      ? selectedModelForPicker
+      : (normalizeModelSlug(selectedModelForPicker, selectedProvider) ?? selectedModelForPicker);
+  }, [modelOptionsByInstance, selectedInstanceId, selectedModelForPicker, selectedProvider]);
+
+  // ------------------------------------------------------------------
+  // Context window
+  // ------------------------------------------------------------------
+  const activeContextWindow = useMemo(
+    () => deriveLatestContextWindowSnapshot(activeThreadActivities ?? []),
+    [activeThreadActivities],
+  );
 
-    // ------------------------------------------------------------------
-    // Derived: composer trigger / menu
-    // ------------------------------------------------------------------
-    const composerTriggerKind = composerTrigger?.kind ?? null;
-    const pathTriggerQuery = composerTrigger?.kind === "path" ? composerTrigger.query : "";
-    const isPathTrigger = composerTriggerKind === "path";
-    const [debouncedPathQuery, composerPathQueryDebouncer] = useDebouncedValue(
-      pathTriggerQuery,
-      { wait: COMPOSER_PATH_QUERY_DEBOUNCE_MS },
-      (debouncerState) => ({ isPending: debouncerState.isPending }),
-    );
-    const effectivePathQuery = pathTriggerQuery.length > 0 ? debouncedPathQuery : "";
-    const workspaceEntriesQuery = useQuery(
-      projectSearchEntriesQueryOptions({
-        environmentId,
-        cwd: gitCwd,
-        query: effectivePathQuery,
-        enabled: isPathTrigger,
-        limit: 80,
+  // ------------------------------------------------------------------
+  // Composer-local state
+  // ------------------------------------------------------------------
+  const [composerCursor, setComposerCursor] = useState(() =>
+    collapseExpandedComposerCursor(prompt, prompt.length),
+  );
+  const [composerTrigger, setComposerTrigger] = useState<ComposerTrigger | null>(() =>
+    detectComposerTrigger(prompt, prompt.length),
+  );
+  const [composerHighlightedItemId, setComposerHighlightedItemId] = useState<string | null>(null);
+  const [composerHighlightedSearchKey, setComposerHighlightedSearchKey] = useState<string | null>(
+    null,
+  );
+  const [isDragOverComposer, setIsDragOverComposer] = useState(false);
+  const [isComposerFooterCompact, setIsComposerFooterCompact] = useState(false);
+  const [isComposerPrimaryActionsCompact, setIsComposerPrimaryActionsCompact] = useState(false);
+  const [isComposerModelPickerOpen, setIsComposerModelPickerOpen] = useState(false);
+  const [isComposerFocused, setIsComposerFocused] = useState(false);
+  const isMobileViewport = useMediaQuery("max-sm");
+  const isComposerCollapsedMobile = isMobileViewport && !isComposerFocused;
+
+  // ------------------------------------------------------------------
+  // Refs
+  // ------------------------------------------------------------------
+  const composerEditorRef = useRef<ComposerPromptEditorHandle>(null);
+  const composerFormRef = useRef<HTMLFormElement>(null);
+  const composerSurfaceRef = useRef<HTMLDivElement>(null);
+  const composerFormHeightRef = useRef(0);
+  const composerSelectLockRef = useRef(false);
+  const composerMenuOpenRef = useRef(false);
+  const composerMenuItemsRef = useRef<ComposerCommandItem[]>([]);
+  const activeComposerMenuItemRef = useRef<ComposerCommandItem | null>(null);
+  const composerBlurFrameRef = useRef<number | null>(null);
+  const mobileComposerExpandFrameRef = useRef<number | null>(null);
+  const mobileComposerExpandReleaseFrameRef = useRef<number | null>(null);
+  const mobileComposerExpandInFlightRef = useRef(false);
+  const dragDepthRef = useRef(0);
+
+  // ------------------------------------------------------------------
+  // Derived: composer send state
+  // ------------------------------------------------------------------
+  const composerSendState = useMemo(
+    () =>
+      deriveComposerSendState({
+        prompt,
+        imageCount: composerImages.length,
+        terminalContexts: composerTerminalContexts,
       }),
-    );
-    const workspaceEntries = workspaceEntriesQuery.data?.entries ?? EMPTY_PROJECT_ENTRIES;
-
-    const composerMenuItems = useMemo<ComposerCommandItem[]>(() => {
-      if (!composerTrigger) return [];
-      if (composerTrigger.kind === "path") {
-        return workspaceEntries.map((entry) => ({
-          id: `path:${entry.kind}:${entry.path}`,
-          type: "path",
-          path: entry.path,
-          pathKind: entry.kind,
-          label: basenameOfPath(entry.path),
-          description: entry.parentPath ?? "",
-        }));
-      }
-      if (composerTrigger.kind === "slash-command") {
-        const builtInSlashCommandItems = [
-          {
-            id: "slash:model",
-            type: "slash-command",
-            command: "model",
-            label: "/model",
-            description: "Switch response model for this thread",
-          },
-          {
-            id: "slash:plan",
-            type: "slash-command",
-            command: "plan",
-            label: "/plan",
-            description: "Switch this thread into plan mode",
-          },
-          {
-            id: "slash:default",
-            type: "slash-command",
-            command: "default",
-            label: "/default",
-            description: "Switch this thread back to normal build mode",
-          },
-        ] satisfies ReadonlyArray<Extract<ComposerCommandItem, { type: "slash-command" }>>;
-        const providerSlashCommandItems = (selectedProviderStatus?.slashCommands ?? []).map(
-          (command) => ({
-            id: `provider-slash-command:${selectedProvider}:${command.name}`,
-            type: "provider-slash-command" as const,
-            provider: selectedProvider,
-            command,
-            label: `/${command.name}`,
-            description: command.description ?? command.input?.hint ?? "Run provider command",
-          }),
-        );
-        const query = composerTrigger.query.trim().toLowerCase();
-        const slashCommandItems = [...builtInSlashCommandItems, ...providerSlashCommandItems];
-        if (!query) {
-          return slashCommandItems;
-        }
-        return searchSlashCommandItems(slashCommandItems, query);
+    [composerImages.length, composerTerminalContexts, prompt],
+  );
+
+  // ------------------------------------------------------------------
+  // Derived: composer trigger / menu
+  // ------------------------------------------------------------------
+  const composerTriggerKind = composerTrigger?.kind ?? null;
+  const pathTriggerQuery = composerTrigger?.kind === "path" ? composerTrigger.query : "";
+  const isPathTrigger = composerTriggerKind === "path";
+  const [debouncedPathQuery, composerPathQueryDebouncer] = useDebouncedValue(
+    pathTriggerQuery,
+    { wait: COMPOSER_PATH_QUERY_DEBOUNCE_MS },
+    (debouncerState) => ({ isPending: debouncerState.isPending }),
+  );
+  const effectivePathQuery = pathTriggerQuery.length > 0 ? debouncedPathQuery : "";
+  const workspaceEntriesQuery = useQuery(
+    projectSearchEntriesQueryOptions({
+      environmentId,
+      cwd: gitCwd,
+      query: effectivePathQuery,
+      enabled: isPathTrigger,
+      limit: 80,
+    }),
+  );
+  const workspaceEntries = workspaceEntriesQuery.data?.entries ?? EMPTY_PROJECT_ENTRIES;
+
+  const composerMenuItems = useMemo<ComposerCommandItem[]>(() => {
+    if (!composerTrigger) return [];
+    if (composerTrigger.kind === "path") {
+      return workspaceEntries.map((entry) => ({
+        id: `path:${entry.kind}:${entry.path}`,
+        type: "path",
+        path: entry.path,
+        pathKind: entry.kind,
+        label: basenameOfPath(entry.path),
+        description: entry.parentPath ?? "",
+      }));
+    }
+    if (composerTrigger.kind === "slash-command") {
+      const builtInSlashCommandItems = [
+        {
+          id: "slash:model",
+          type: "slash-command",
+          command: "model",
+          label: "/model",
+          description: "Switch response model for this thread",
+        },
+        {
+          id: "slash:plan",
+          type: "slash-command",
+          command: "plan",
+          label: "/plan",
+          description: "Switch this thread into plan mode",
+        },
+        {
+          id: "slash:default",
+          type: "slash-command",
+          command: "default",
+          label: "/default",
+          description: "Switch this thread back to normal build mode",
+        },
+      ] satisfies ReadonlyArray<Extract<ComposerCommandItem, { type: "slash-command" }>>;
+      const providerSlashCommandItems = (selectedProviderStatus?.slashCommands ?? []).map(
+        (command) => ({
+          id: `provider-slash-command:${selectedProvider}:${command.name}`,
+          type: "provider-slash-command" as const,
+          provider: selectedProvider,
+          command,
+          label: `/${command.name}`,
+          description: command.description ?? command.input?.hint ?? "Run provider command",
+        }),
+      );
+      const query = composerTrigger.query.trim().toLowerCase();
+      const slashCommandItems = [...builtInSlashCommandItems, ...providerSlashCommandItems];
+      if (!query) {
+        return slashCommandItems;
       }
-      if (composerTrigger.kind === "skill") {
-        return searchProviderSkills(
-          selectedProviderStatus?.skills ?? [],
-          composerTrigger.query,
-        ).map((skill) => ({
+      return searchSlashCommandItems(slashCommandItems, query);
+    }
+    if (composerTrigger.kind === "skill") {
+      return searchProviderSkills(selectedProviderStatus?.skills ?? [], composerTrigger.query).map(
+        (skill) => ({
           id: `skill:${selectedProvider}:${skill.name}`,
           type: "skill" as const,
           provider: selectedProvider,
@@ -764,973 +915,1076 @@ export const ChatComposer = memo(
             skill.shortDescription ??
             skill.description ??
             (skill.scope ? `${skill.scope} skill` : "Run provider skill"),
-        }));
-      }
-      return searchableModelOptions
-        .filter(({ searchSlug, searchName, searchProvider }) => {
-          const query = composerTrigger.query.trim().toLowerCase();
-          if (!query) return true;
-          return (
-            searchSlug.includes(query) ||
-            searchName.includes(query) ||
-            searchProvider.includes(query)
-          );
-        })
-        .map(({ provider, providerLabel, slug, name }) => ({
-          id: `model:${provider}:${slug}`,
-          type: "model",
-          provider,
-          model: slug,
-          label: name,
-          description: `${providerLabel} · ${slug}`,
-        }));
-    }, [
-      composerTrigger,
-      searchableModelOptions,
-      selectedProvider,
-      selectedProviderStatus,
-      workspaceEntries,
-    ]);
-
-    const composerMenuOpen = Boolean(composerTrigger);
-    const composerMenuSearchKey = composerTrigger
-      ? `${composerTrigger.kind}:${composerTrigger.query.trim().toLowerCase()}`
-      : null;
-    const activeComposerMenuItem = useMemo(() => {
-      const activeItemId = resolveComposerMenuActiveItemId({
-        items: composerMenuItems,
-        highlightedItemId: composerHighlightedItemId,
-        currentSearchKey: composerMenuSearchKey,
-        highlightedSearchKey: composerHighlightedSearchKey,
-      });
-      return composerMenuItems.find((item) => item.id === activeItemId) ?? null;
-    }, [
-      composerHighlightedItemId,
-      composerHighlightedSearchKey,
-      composerMenuItems,
-      composerMenuSearchKey,
-    ]);
-
-    composerMenuOpenRef.current = composerMenuOpen;
-    composerMenuItemsRef.current = composerMenuItems;
-    activeComposerMenuItemRef.current = activeComposerMenuItem;
-
-    const nonPersistedComposerImageIdSet = useMemo(
-      () => new Set(nonPersistedComposerImageIds),
-      [nonPersistedComposerImageIds],
-    );
-
-    const isComposerApprovalState = activePendingApproval !== null;
-    const activePendingUserInput = pendingUserInputs[0] ?? null;
-    const hasComposerHeader =
-      isComposerApprovalState ||
-      pendingUserInputs.length > 0 ||
-      (showPlanFollowUpPrompt && activeProposedPlan !== null);
-
-    const composerFooterHasWideActions = showPlanFollowUpPrompt || activePendingProgress !== null;
-    const showPlanSidebarToggle = Boolean(activePlan || sidebarProposedPlan || planSidebarOpen);
-    const composerFooterActionLayoutKey = useMemo(() => {
-      if (activePendingProgress) {
-        return `pending:${activePendingProgress.questionIndex}:${activePendingProgress.isLastQuestion}:${activePendingIsResponding}`;
-      }
-      if (phase === "running") {
-        return "running";
-      }
-      if (showPlanFollowUpPrompt) {
-        return prompt.trim().length > 0 ? "plan:refine" : "plan:implement";
-      }
-      return `idle:${composerSendState.hasSendableContent}:${isSendBusy}:${isConnecting}:${isPreparingWorktree}`;
-    }, [
-      activePendingIsResponding,
-      activePendingProgress,
-      composerSendState.hasSendableContent,
-      isConnecting,
-      isPreparingWorktree,
-      isSendBusy,
-      phase,
-      prompt,
-      showPlanFollowUpPrompt,
-    ]);
-
-    const isComposerMenuLoading =
-      composerTriggerKind === "path" &&
-      ((pathTriggerQuery.length > 0 && composerPathQueryDebouncer.state.isPending) ||
-        workspaceEntriesQuery.isLoading ||
-        workspaceEntriesQuery.isFetching);
-    const composerMenuEmptyState = useMemo(() => {
-      if (composerTriggerKind === "skill") {
-        return "No skills found. Try / to browse provider commands.";
-      }
-      return composerTriggerKind === "path"
-        ? "No matching files or folders."
-        : "No matching command.";
-    }, [composerTriggerKind]);
-
-    // ------------------------------------------------------------------
-    // Provider traits UI
-    // ------------------------------------------------------------------
-    const setPromptFromTraits = useCallback(
-      (nextPrompt: string) => {
-        if (nextPrompt === promptRef.current) {
-          scheduleComposerFocus();
-          return;
-        }
-        promptRef.current = nextPrompt;
-        setComposerDraftPrompt(composerDraftTarget, nextPrompt);
-        const nextCursor = collapseExpandedComposerCursor(nextPrompt, nextPrompt.length);
-        setComposerCursor(nextCursor);
-        setComposerTrigger(detectComposerTrigger(nextPrompt, nextPrompt.length));
-        scheduleComposerFocus();
-      },
-      [composerDraftTarget, promptRef, scheduleComposerFocus, setComposerDraftPrompt],
-    );
-
-    const providerTraitsMenuContent = renderProviderTraitsMenuContent({
-      provider: selectedProvider,
-      ...(routeKind === "server" ? { threadRef: routeThreadRef } : {}),
-      ...(routeKind === "draft" && draftId ? { draftId } : {}),
-      model: selectedModel,
-      models: selectedProviderModels,
-      modelOptions: composerModelOptions?.[selectedProvider],
-      prompt,
-      onPromptChange: setPromptFromTraits,
-    });
-    const providerTraitsPicker = renderProviderTraitsPicker({
-      provider: selectedProvider,
-      ...(routeKind === "server" ? { threadRef: routeThreadRef } : {}),
-      ...(routeKind === "draft" && draftId ? { draftId } : {}),
-      model: selectedModel,
-      models: selectedProviderModels,
-      modelOptions: composerModelOptions?.[selectedProvider],
-      prompt,
-      onPromptChange: setPromptFromTraits,
+        }),
+      );
+    }
+    return [];
+  }, [composerTrigger, selectedProvider, selectedProviderStatus, workspaceEntries]);
+
+  const composerMenuOpen = Boolean(composerTrigger);
+  const composerMenuSearchKey = composerTrigger
+    ? `${composerTrigger.kind}:${composerTrigger.query.trim().toLowerCase()}`
+    : null;
+  const activeComposerMenuItem = useMemo(() => {
+    const activeItemId = resolveComposerMenuActiveItemId({
+      items: composerMenuItems,
+      highlightedItemId: composerHighlightedItemId,
+      currentSearchKey: composerMenuSearchKey,
+      highlightedSearchKey: composerHighlightedSearchKey,
     });
-    const pendingPrimaryAction = useMemo(
-      () =>
-        activePendingProgress
-          ? {
-              questionIndex: activePendingProgress.questionIndex,
-              isLastQuestion: activePendingProgress.isLastQuestion,
-              canAdvance: activePendingProgress.canAdvance,
-              isResponding: activePendingIsResponding,
-              isComplete: Boolean(activePendingResolvedAnswers),
-            }
-          : null,
-      [activePendingIsResponding, activePendingProgress, activePendingResolvedAnswers],
-    );
-
-    // ------------------------------------------------------------------
-    // Prompt helpers
-    // ------------------------------------------------------------------
-    const setPrompt = useCallback(
-      (nextPrompt: string) => {
-        setComposerDraftPrompt(composerDraftTarget, nextPrompt);
-      },
-      [composerDraftTarget, setComposerDraftPrompt],
-    );
-
-    const addComposerImage = useCallback(
-      (image: ComposerImageAttachment) => {
-        addComposerDraftImage(composerDraftTarget, image);
-      },
-      [composerDraftTarget, addComposerDraftImage],
-    );
-
-    const addComposerImagesToDraft = useCallback(
-      (images: ComposerImageAttachment[]) => {
-        addComposerDraftImages(composerDraftTarget, images);
-      },
-      [composerDraftTarget, addComposerDraftImages],
-    );
-
-    const removeComposerImageFromDraft = useCallback(
-      (imageId: string) => {
-        removeComposerDraftImage(composerDraftTarget, imageId);
-      },
-      [composerDraftTarget, removeComposerDraftImage],
-    );
-
-    const removeComposerTerminalContextFromDraft = useCallback(
-      (contextId: string) => {
-        const contextIndex = composerTerminalContexts.findIndex(
-          (context) => context.id === contextId,
-        );
-        if (contextIndex < 0) return;
-        const removal = removeInlineTerminalContextPlaceholder(promptRef.current, contextIndex);
-        promptRef.current = removal.prompt;
-        setPrompt(removal.prompt);
-        removeComposerDraftTerminalContext(composerDraftTarget, contextId);
-        const nextCursor = collapseExpandedComposerCursor(removal.prompt, removal.cursor);
-        setComposerCursor(nextCursor);
-        setComposerTrigger(detectComposerTrigger(removal.prompt, removal.cursor));
-      },
-      [
-        composerDraftTarget,
-        composerTerminalContexts,
-        promptRef,
-        removeComposerDraftTerminalContext,
-        setPrompt,
-      ],
-    );
+    return composerMenuItems.find((item) => item.id === activeItemId) ?? null;
+  }, [
+    composerHighlightedItemId,
+    composerHighlightedSearchKey,
+    composerMenuItems,
+    composerMenuSearchKey,
+  ]);
+
+  composerMenuOpenRef.current = composerMenuOpen;
+  composerMenuItemsRef.current = composerMenuItems;
+  activeComposerMenuItemRef.current = activeComposerMenuItem;
+
+  const nonPersistedComposerImageIdSet = useMemo(
+    () => new Set(nonPersistedComposerImageIds),
+    [nonPersistedComposerImageIds],
+  );
 
-    // ------------------------------------------------------------------
-    // Sync refs back to parent
-    // ------------------------------------------------------------------
-    useEffect(() => {
-      promptRef.current = prompt;
-      setComposerCursor((existing) => clampCollapsedComposerCursor(prompt, existing));
-    }, [prompt, promptRef]);
-
-    useEffect(() => {
-      composerImagesRef.current = composerImages;
-    }, [composerImages, composerImagesRef]);
-
-    useEffect(() => {
-      composerTerminalContextsRef.current = composerTerminalContexts;
-    }, [composerTerminalContexts, composerTerminalContextsRef]);
-
-    // ------------------------------------------------------------------
-    // Composer menu highlight sync
-    // ------------------------------------------------------------------
-    useEffect(() => {
-      if (!composerMenuOpen) {
-        setComposerHighlightedItemId(null);
-        setComposerHighlightedSearchKey(null);
-        return;
-      }
-      const nextActiveItemId = resolveComposerMenuActiveItemId({
-        items: composerMenuItems,
-        highlightedItemId: composerHighlightedItemId,
-        currentSearchKey: composerMenuSearchKey,
-        highlightedSearchKey: composerHighlightedSearchKey,
-      });
-      setComposerHighlightedItemId((existing) =>
-        existing === nextActiveItemId ? existing : nextActiveItemId,
-      );
-      setComposerHighlightedSearchKey((existing) =>
-        existing === composerMenuSearchKey ? existing : composerMenuSearchKey,
-      );
-    }, [
-      composerHighlightedItemId,
-      composerHighlightedSearchKey,
-      composerMenuItems,
-      composerMenuOpen,
-      composerMenuSearchKey,
-    ]);
-
-    const lastSyncedPendingInputRef = useRef<{
-      requestId: string | null;
-      questionId: string | null;
-    } | null>(null);
-
-    useEffect(() => {
-      const nextCustomAnswer = activePendingProgress?.customAnswer;
-      if (typeof nextCustomAnswer !== "string") {
-        lastSyncedPendingInputRef.current = null;
+  const isComposerApprovalState = activePendingApproval !== null;
+  const activePendingUserInput = pendingUserInputs[0] ?? null;
+  const hasComposerHeader =
+    isComposerApprovalState ||
+    pendingUserInputs.length > 0 ||
+    (showPlanFollowUpPrompt && activeProposedPlan !== null);
+  const showCollapsedMobilePromptRow =
+    isComposerCollapsedMobile && !isComposerApprovalState && pendingUserInputs.length === 0;
+
+  const composerFooterHasWideActions = showPlanFollowUpPrompt || activePendingProgress !== null;
+  const showPlanSidebarToggle = Boolean(activePlan || sidebarProposedPlan || planSidebarOpen);
+  const composerFooterActionLayoutKey = useMemo(() => {
+    if (activePendingProgress) {
+      return `pending:${activePendingProgress.questionIndex}:${activePendingProgress.isLastQuestion}:${activePendingIsResponding}`;
+    }
+    if (phase === "running") {
+      return "running";
+    }
+    if (showPlanFollowUpPrompt) {
+      return prompt.trim().length > 0 ? "plan:refine" : "plan:implement";
+    }
+    return `idle:${composerSendState.hasSendableContent}:${isSendBusy}:${isConnecting}:${isPreparingWorktree}`;
+  }, [
+    activePendingIsResponding,
+    activePendingProgress,
+    composerSendState.hasSendableContent,
+    isConnecting,
+    isPreparingWorktree,
+    isSendBusy,
+    phase,
+    prompt,
+    showPlanFollowUpPrompt,
+  ]);
+
+  const isComposerMenuLoading =
+    composerTriggerKind === "path" &&
+    ((pathTriggerQuery.length > 0 && composerPathQueryDebouncer.state.isPending) ||
+      workspaceEntriesQuery.isLoading ||
+      workspaceEntriesQuery.isFetching);
+  const composerMenuEmptyState = useMemo(() => {
+    if (composerTriggerKind === "skill") {
+      return "No skills found. Try / to browse provider commands.";
+    }
+    return composerTriggerKind === "path"
+      ? "No matching files or folders."
+      : "No matching command.";
+  }, [composerTriggerKind]);
+
+  // ------------------------------------------------------------------
+  // Provider traits UI
+  // ------------------------------------------------------------------
+  const setPromptFromTraits = useCallback(
+    (nextPrompt: string) => {
+      if (nextPrompt === promptRef.current) {
+        scheduleComposerFocus();
         return;
       }
+      promptRef.current = nextPrompt;
+      setComposerDraftPrompt(composerDraftTarget, nextPrompt);
+      const nextCursor = collapseExpandedComposerCursor(nextPrompt, nextPrompt.length);
+      setComposerCursor(nextCursor);
+      setComposerTrigger(detectComposerTrigger(nextPrompt, nextPrompt.length));
+      scheduleComposerFocus();
+    },
+    [composerDraftTarget, promptRef, scheduleComposerFocus, setComposerDraftPrompt],
+  );
 
-      const nextRequestId = activePendingUserInput?.requestId ?? null;
-      const nextQuestionId = activePendingProgress?.activeQuestion?.id ?? null;
-      const questionChanged =
-        lastSyncedPendingInputRef.current?.requestId !== nextRequestId ||
-        lastSyncedPendingInputRef.current?.questionId !== nextQuestionId;
-      const textChangedExternally = promptRef.current !== nextCustomAnswer;
+  const providerTraitsMenuContent = renderProviderTraitsMenuContent({
+    provider: selectedProvider,
+    ...(routeKind === "server" ? { threadRef: routeThreadRef } : {}),
+    ...(routeKind === "draft" && draftId ? { draftId } : {}),
+    model: selectedModel,
+    models: selectedProviderModels,
+    modelOptions: composerModelOptions?.[selectedProvider],
+    prompt,
+    onPromptChange: setPromptFromTraits,
+  });
+  const providerTraitsPicker = renderProviderTraitsPicker({
+    provider: selectedProvider,
+    ...(routeKind === "server" ? { threadRef: routeThreadRef } : {}),
+    ...(routeKind === "draft" && draftId ? { draftId } : {}),
+    model: selectedModel,
+    models: selectedProviderModels,
+    modelOptions: composerModelOptions?.[selectedProvider],
+    prompt,
+    onPromptChange: setPromptFromTraits,
+  });
+  const pendingPrimaryAction = useMemo(
+    () =>
+      activePendingProgress
+        ? {
+            questionIndex: activePendingProgress.questionIndex,
+            isLastQuestion: activePendingProgress.isLastQuestion,
+            canAdvance: activePendingProgress.canAdvance,
+            isResponding: activePendingIsResponding,
+            isComplete: Boolean(activePendingResolvedAnswers),
+          }
+        : null,
+    [activePendingIsResponding, activePendingProgress, activePendingResolvedAnswers],
+  );
+  const collapsedComposerPrimaryActionDisabled =
+    phase === "running" || isSendBusy || isConnecting || !composerSendState.hasSendableContent;
+  const collapsedComposerPrimaryActionLabel = "Send message";
+  const showMobilePendingAnswerActions =
+    isMobileViewport && !isComposerCollapsedMobile && pendingPrimaryAction !== null;
+
+  // ------------------------------------------------------------------
+  // Prompt helpers
+  // ------------------------------------------------------------------
+  const setPrompt = useCallback(
+    (nextPrompt: string) => {
+      setComposerDraftPrompt(composerDraftTarget, nextPrompt);
+    },
+    [composerDraftTarget, setComposerDraftPrompt],
+  );
 
-      lastSyncedPendingInputRef.current = {
-        requestId: nextRequestId,
-        questionId: nextQuestionId,
-      };
+  const addComposerImage = useCallback(
+    (image: ComposerImageAttachment) => {
+      addComposerDraftImage(composerDraftTarget, image);
+    },
+    [composerDraftTarget, addComposerDraftImage],
+  );
 
-      if (!questionChanged && !textChangedExternally) {
-        return;
-      }
+  const addComposerImagesToDraft = useCallback(
+    (images: ComposerImageAttachment[]) => {
+      addComposerDraftImages(composerDraftTarget, images);
+    },
+    [composerDraftTarget, addComposerDraftImages],
+  );
 
-      promptRef.current = nextCustomAnswer;
-      const nextCursor = collapseExpandedComposerCursor(nextCustomAnswer, nextCustomAnswer.length);
-      setComposerCursor(nextCursor);
-      setComposerTrigger(
-        detectComposerTrigger(
-          nextCustomAnswer,
-          expandCollapsedComposerCursor(nextCustomAnswer, nextCursor),
-        ),
+  const removeComposerImageFromDraft = useCallback(
+    (imageId: string) => {
+      removeComposerDraftImage(composerDraftTarget, imageId);
+    },
+    [composerDraftTarget, removeComposerDraftImage],
+  );
+
+  const removeComposerTerminalContextFromDraft = useCallback(
+    (contextId: string) => {
+      const contextIndex = composerTerminalContexts.findIndex(
+        (context) => context.id === contextId,
       );
-      setComposerHighlightedItemId(null);
-    }, [
-      activePendingProgress?.customAnswer,
-      activePendingProgress?.activeQuestion?.id,
-      activePendingUserInput?.requestId,
+      if (contextIndex < 0) return;
+      const removal = removeInlineTerminalContextPlaceholder(promptRef.current, contextIndex);
+      promptRef.current = removal.prompt;
+      setPrompt(removal.prompt);
+      removeComposerDraftTerminalContext(composerDraftTarget, contextId);
+      const nextCursor = collapseExpandedComposerCursor(removal.prompt, removal.cursor);
+      setComposerCursor(nextCursor);
+      setComposerTrigger(detectComposerTrigger(removal.prompt, removal.cursor));
+    },
+    [
+      composerDraftTarget,
+      composerTerminalContexts,
       promptRef,
-    ]);
+      removeComposerDraftTerminalContext,
+      setPrompt,
+    ],
+  );
 
-    // ------------------------------------------------------------------
-    // Reset compositor state on thread/draft change
-    // ------------------------------------------------------------------
-    useEffect(() => {
+  // ------------------------------------------------------------------
+  // Sync refs back to parent
+  // ------------------------------------------------------------------
+  useEffect(() => {
+    promptRef.current = prompt;
+    setComposerCursor((existing) => clampCollapsedComposerCursor(prompt, existing));
+  }, [prompt, promptRef]);
+
+  useEffect(() => {
+    composerImagesRef.current = composerImages;
+  }, [composerImages, composerImagesRef]);
+
+  useEffect(() => {
+    composerTerminalContextsRef.current = composerTerminalContexts;
+  }, [composerTerminalContexts, composerTerminalContextsRef]);
+
+  // ------------------------------------------------------------------
+  // Composer menu highlight sync
+  // ------------------------------------------------------------------
+  useEffect(() => {
+    if (!composerMenuOpen) {
       setComposerHighlightedItemId(null);
-      setComposerCursor(
-        collapseExpandedComposerCursor(promptRef.current, promptRef.current.length),
-      );
-      setComposerTrigger(detectComposerTrigger(promptRef.current, promptRef.current.length));
-      dragDepthRef.current = 0;
-      setIsDragOverComposer(false);
-    }, [draftId, activeThreadId, promptRef]);
-
-    // ------------------------------------------------------------------
-    // Footer compact layout observation
-    // ------------------------------------------------------------------
-    useLayoutEffect(() => {
-      const composerForm = composerFormRef.current;
-      if (!composerForm) return;
-      const measureComposerFormWidth = () => composerForm.clientWidth;
-      const measureFooterCompactness = () => {
-        const composerFormWidth = measureComposerFormWidth();
-        const footerCompact = shouldUseCompactComposerFooter(composerFormWidth, {
+      setComposerHighlightedSearchKey(null);
+      return;
+    }
+    const nextActiveItemId = resolveComposerMenuActiveItemId({
+      items: composerMenuItems,
+      highlightedItemId: composerHighlightedItemId,
+      currentSearchKey: composerMenuSearchKey,
+      highlightedSearchKey: composerHighlightedSearchKey,
+    });
+    setComposerHighlightedItemId((existing) =>
+      existing === nextActiveItemId ? existing : nextActiveItemId,
+    );
+    setComposerHighlightedSearchKey((existing) =>
+      existing === composerMenuSearchKey ? existing : composerMenuSearchKey,
+    );
+  }, [
+    composerHighlightedItemId,
+    composerHighlightedSearchKey,
+    composerMenuItems,
+    composerMenuOpen,
+    composerMenuSearchKey,
+  ]);
+
+  const lastSyncedPendingInputRef = useRef<{
+    requestId: string | null;
+    questionId: string | null;
+  } | null>(null);
+
+  useEffect(() => {
+    const nextCustomAnswer = activePendingProgress?.customAnswer;
+    if (typeof nextCustomAnswer !== "string") {
+      lastSyncedPendingInputRef.current = null;
+      return;
+    }
+
+    const nextRequestId = activePendingUserInput?.requestId ?? null;
+    const nextQuestionId = activePendingProgress?.activeQuestion?.id ?? null;
+    const questionChanged =
+      lastSyncedPendingInputRef.current?.requestId !== nextRequestId ||
+      lastSyncedPendingInputRef.current?.questionId !== nextQuestionId;
+    const textChangedExternally = promptRef.current !== nextCustomAnswer;
+
+    lastSyncedPendingInputRef.current = {
+      requestId: nextRequestId,
+      questionId: nextQuestionId,
+    };
+
+    if (!questionChanged && !textChangedExternally) {
+      return;
+    }
+
+    promptRef.current = nextCustomAnswer;
+    const nextCursor = collapseExpandedComposerCursor(nextCustomAnswer, nextCustomAnswer.length);
+    setComposerCursor(nextCursor);
+    setComposerTrigger(
+      detectComposerTrigger(
+        nextCustomAnswer,
+        expandCollapsedComposerCursor(nextCustomAnswer, nextCursor),
+      ),
+    );
+    setComposerHighlightedItemId(null);
+  }, [
+    activePendingProgress?.customAnswer,
+    activePendingProgress?.activeQuestion?.id,
+    activePendingUserInput?.requestId,
+    promptRef,
+  ]);
+
+  // ------------------------------------------------------------------
+  // Reset compositor state on thread/draft change
+  // ------------------------------------------------------------------
+  useEffect(() => {
+    setComposerHighlightedItemId(null);
+    setComposerCursor(collapseExpandedComposerCursor(promptRef.current, promptRef.current.length));
+    setComposerTrigger(detectComposerTrigger(promptRef.current, promptRef.current.length));
+    dragDepthRef.current = 0;
+    setIsDragOverComposer(false);
+  }, [draftId, activeThreadId, promptRef]);
+
+  // ------------------------------------------------------------------
+  // Footer compact layout observation
+  // ------------------------------------------------------------------
+  useLayoutEffect(() => {
+    const composerForm = composerFormRef.current;
+    if (!composerForm) return;
+    const measureComposerFormWidth = () => composerForm.clientWidth;
+    const measureFooterCompactness = () => {
+      const composerFormWidth = measureComposerFormWidth();
+      const footerCompact = shouldUseCompactComposerFooter(composerFormWidth, {
+        hasWideActions: composerFooterHasWideActions,
+      });
+      const primaryActionsCompact =
+        footerCompact &&
+        shouldUseCompactComposerPrimaryActions(composerFormWidth, {
           hasWideActions: composerFooterHasWideActions,
         });
-        const primaryActionsCompact =
-          footerCompact &&
-          shouldUseCompactComposerPrimaryActions(composerFormWidth, {
-            hasWideActions: composerFooterHasWideActions,
-          });
-        return {
-          primaryActionsCompact,
-          footerCompact,
-        };
+      return {
+        primaryActionsCompact,
+        footerCompact,
       };
+    };
 
-      composerFormHeightRef.current = composerForm.getBoundingClientRect().height;
-      const initialCompactness = measureFooterCompactness();
-      setIsComposerPrimaryActionsCompact(initialCompactness.primaryActionsCompact);
-      setIsComposerFooterCompact(initialCompactness.footerCompact);
-      if (typeof ResizeObserver === "undefined") return;
-
-      const observer = new ResizeObserver((entries) => {
-        const [entry] = entries;
-        if (!entry) return;
-        const nextCompactness = measureFooterCompactness();
-        setIsComposerPrimaryActionsCompact((previous) =>
-          previous === nextCompactness.primaryActionsCompact
-            ? previous
-            : nextCompactness.primaryActionsCompact,
-        );
-        setIsComposerFooterCompact((previous) =>
-          previous === nextCompactness.footerCompact ? previous : nextCompactness.footerCompact,
-        );
-        const nextHeight = entry.contentRect.height;
-        const previousHeight = composerFormHeightRef.current;
-        composerFormHeightRef.current = nextHeight;
-        if (previousHeight > 0 && Math.abs(nextHeight - previousHeight) < 0.5) return;
-        if (!shouldAutoScrollRef.current) return;
-        scheduleStickToBottom();
-      });
+    composerFormHeightRef.current = composerForm.getBoundingClientRect().height;
+    const initialCompactness = measureFooterCompactness();
+    setIsComposerPrimaryActionsCompact(initialCompactness.primaryActionsCompact);
+    setIsComposerFooterCompact(initialCompactness.footerCompact);
+    if (typeof ResizeObserver === "undefined") return;
+
+    const observer = new ResizeObserver((entries) => {
+      const [entry] = entries;
+      if (!entry) return;
+      const nextCompactness = measureFooterCompactness();
+      setIsComposerPrimaryActionsCompact((previous) =>
+        previous === nextCompactness.primaryActionsCompact
+          ? previous
+          : nextCompactness.primaryActionsCompact,
+      );
+      setIsComposerFooterCompact((previous) =>
+        previous === nextCompactness.footerCompact ? previous : nextCompactness.footerCompact,
+      );
+      const nextHeight = entry.contentRect.height;
+      const previousHeight = composerFormHeightRef.current;
+      composerFormHeightRef.current = nextHeight;
+      if (previousHeight > 0 && Math.abs(nextHeight - previousHeight) < 0.5) return;
+      if (!shouldAutoScrollRef.current) return;
+      scheduleStickToBottom();
+    });
 
-      observer.observe(composerForm);
-      return () => {
-        observer.disconnect();
-      };
-    }, [
-      activeThreadId,
-      composerFooterActionLayoutKey,
-      composerFooterHasWideActions,
-      scheduleStickToBottom,
-      shouldAutoScrollRef,
-    ]);
-
-    // ------------------------------------------------------------------
-    // Image persist effect
-    // ------------------------------------------------------------------
-    useEffect(() => {
-      let cancelled = false;
-      void (async () => {
-        if (composerImages.length === 0) {
-          clearComposerDraftPersistedAttachments(composerDraftTarget);
-          return;
-        }
-        const getPersistedAttachmentsForThread = () =>
-          getComposerDraft(composerDraftTarget)?.persistedAttachments ?? [];
-        try {
-          const currentPersistedAttachments = getPersistedAttachmentsForThread();
-          const existingPersistedById = new Map(
-            currentPersistedAttachments.map((attachment) => [attachment.id, attachment]),
-          );
-          const stagedAttachmentById = new Map<string, PersistedComposerImageAttachment>();
-          await Promise.all(
-            composerImages.map(async (image) => {
-              try {
-                const dataUrl = await readFileAsDataUrl(image.file);
-                stagedAttachmentById.set(image.id, {
-                  id: image.id,
-                  name: image.name,
-                  mimeType: image.mimeType,
-                  sizeBytes: image.sizeBytes,
-                  dataUrl,
-                });
-              } catch {
-                const existingPersisted = existingPersistedById.get(image.id);
-                if (existingPersisted) {
-                  stagedAttachmentById.set(image.id, existingPersisted);
-                }
+    observer.observe(composerForm);
+    return () => {
+      observer.disconnect();
+    };
+  }, [
+    activeThreadId,
+    composerFooterActionLayoutKey,
+    composerFooterHasWideActions,
+    scheduleStickToBottom,
+    shouldAutoScrollRef,
+  ]);
+
+  // ------------------------------------------------------------------
+  // Image persist effect
+  // ------------------------------------------------------------------
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      if (composerImages.length === 0) {
+        clearComposerDraftPersistedAttachments(composerDraftTarget);
+        return;
+      }
+      const getPersistedAttachmentsForThread = () =>
+        getComposerDraft(composerDraftTarget)?.persistedAttachments ?? [];
+      try {
+        const currentPersistedAttachments = getPersistedAttachmentsForThread();
+        const existingPersistedById = new Map(
+          currentPersistedAttachments.map((attachment) => [attachment.id, attachment]),
+        );
+        const stagedAttachmentById = new Map<string, PersistedComposerImageAttachment>();
+        await Promise.all(
+          composerImages.map(async (image) => {
+            try {
+              const dataUrl = await readFileAsDataUrl(image.file);
+              stagedAttachmentById.set(image.id, {
+                id: image.id,
+                name: image.name,
+                mimeType: image.mimeType,
+                sizeBytes: image.sizeBytes,
+                dataUrl,
+              });
+            } catch {
+              const existingPersisted = existingPersistedById.get(image.id);
+              if (existingPersisted) {
+                stagedAttachmentById.set(image.id, existingPersisted);
               }
-            }),
-          );
-          const serialized = Array.from(stagedAttachmentById.values());
-          if (cancelled) return;
-          syncComposerDraftPersistedAttachments(composerDraftTarget, serialized);
-        } catch {
-          const currentImageIds = new Set(composerImages.map((image) => image.id));
-          const fallbackPersistedAttachments = getPersistedAttachmentsForThread();
-          const fallbackPersistedIds = fallbackPersistedAttachments
-            .map((attachment) => attachment.id)
-            .filter((id) => currentImageIds.has(id));
-          const fallbackPersistedIdSet = new Set(fallbackPersistedIds);
-          const fallbackAttachments = fallbackPersistedAttachments.filter((attachment) =>
-            fallbackPersistedIdSet.has(attachment.id),
-          );
-          if (cancelled) return;
-          syncComposerDraftPersistedAttachments(composerDraftTarget, fallbackAttachments);
-        }
-      })();
-      return () => {
-        cancelled = true;
-      };
-    }, [
-      composerDraftTarget,
-      clearComposerDraftPersistedAttachments,
-      composerImages,
-      getComposerDraft,
-      syncComposerDraftPersistedAttachments,
-    ]);
-
-    // ------------------------------------------------------------------
-    // Callbacks: prompt change
-    // ------------------------------------------------------------------
-    const onPromptChange = useCallback(
-      (
-        nextPrompt: string,
-        nextCursor: number,
-        expandedCursor: number,
-        cursorAdjacentToMention: boolean,
-        terminalContextIds: string[],
-      ) => {
-        if (activePendingProgress?.activeQuestion && pendingUserInputs.length > 0) {
-          setComposerCursor(nextCursor);
-          setComposerTrigger(
-            cursorAdjacentToMention ? null : detectComposerTrigger(nextPrompt, expandedCursor),
-          );
-          onChangeActivePendingUserInputCustomAnswer(
-            activePendingProgress.activeQuestion.id,
-            nextPrompt,
-            nextCursor,
-            expandedCursor,
-            cursorAdjacentToMention,
-          );
-          return;
-        }
-        promptRef.current = nextPrompt;
-        setPrompt(nextPrompt);
-        if (!terminalContextIdListsEqual(composerTerminalContexts, terminalContextIds)) {
-          setComposerDraftTerminalContexts(
-            composerDraftTarget,
-            syncTerminalContextsByIds(composerTerminalContexts, terminalContextIds),
-          );
-        }
+            }
+          }),
+        );
+        const serialized = Array.from(stagedAttachmentById.values());
+        if (cancelled) return;
+        syncComposerDraftPersistedAttachments(composerDraftTarget, serialized);
+      } catch {
+        const currentImageIds = new Set(composerImages.map((image) => image.id));
+        const fallbackPersistedAttachments = getPersistedAttachmentsForThread();
+        const fallbackPersistedIds = fallbackPersistedAttachments
+          .map((attachment) => attachment.id)
+          .filter((id) => currentImageIds.has(id));
+        const fallbackPersistedIdSet = new Set(fallbackPersistedIds);
+        const fallbackAttachments = fallbackPersistedAttachments.filter((attachment) =>
+          fallbackPersistedIdSet.has(attachment.id),
+        );
+        if (cancelled) return;
+        syncComposerDraftPersistedAttachments(composerDraftTarget, fallbackAttachments);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    composerDraftTarget,
+    clearComposerDraftPersistedAttachments,
+    composerImages,
+    getComposerDraft,
+    syncComposerDraftPersistedAttachments,
+  ]);
+
+  // ------------------------------------------------------------------
+  // Callbacks: prompt change
+  // ------------------------------------------------------------------
+  const onPromptChange = useCallback(
+    (
+      nextPrompt: string,
+      nextCursor: number,
+      expandedCursor: number,
+      cursorAdjacentToMention: boolean,
+      terminalContextIds: string[],
+    ) => {
+      if (activePendingProgress?.activeQuestion && pendingUserInputs.length > 0) {
         setComposerCursor(nextCursor);
         setComposerTrigger(
           cursorAdjacentToMention ? null : detectComposerTrigger(nextPrompt, expandedCursor),
         );
-      },
-      [
-        activePendingProgress?.activeQuestion,
-        pendingUserInputs.length,
-        onChangeActivePendingUserInputCustomAnswer,
-        promptRef,
-        setPrompt,
-        composerDraftTarget,
-        composerTerminalContexts,
-        setComposerDraftTerminalContexts,
-      ],
-    );
+        onChangeActivePendingUserInputCustomAnswer(
+          activePendingProgress.activeQuestion.id,
+          nextPrompt,
+          nextCursor,
+          expandedCursor,
+          cursorAdjacentToMention,
+        );
+        return;
+      }
+      promptRef.current = nextPrompt;
+      setPrompt(nextPrompt);
+      if (!terminalContextIdListsEqual(composerTerminalContexts, terminalContextIds)) {
+        setComposerDraftTerminalContexts(
+          composerDraftTarget,
+          syncTerminalContextsByIds(composerTerminalContexts, terminalContextIds),
+        );
+      }
+      setComposerCursor(nextCursor);
+      setComposerTrigger(
+        cursorAdjacentToMention ? null : detectComposerTrigger(nextPrompt, expandedCursor),
+      );
+    },
+    [
+      activePendingProgress?.activeQuestion,
+      pendingUserInputs.length,
+      onChangeActivePendingUserInputCustomAnswer,
+      promptRef,
+      setPrompt,
+      composerDraftTarget,
+      composerTerminalContexts,
+      setComposerDraftTerminalContexts,
+    ],
+  );
 
-    // ------------------------------------------------------------------
-    // Callbacks: prompt replacement / menu
-    // ------------------------------------------------------------------
-    const applyPromptReplacement = useCallback(
-      (
-        rangeStart: number,
-        rangeEnd: number,
-        replacement: string,
-        options?: { expectedText?: string },
-      ): boolean => {
-        const currentText = promptRef.current;
-        const safeStart = Math.max(0, Math.min(currentText.length, rangeStart));
-        const safeEnd = Math.max(safeStart, Math.min(currentText.length, rangeEnd));
-        if (
-          options?.expectedText !== undefined &&
-          currentText.slice(safeStart, safeEnd) !== options.expectedText
-        ) {
-          return false;
-        }
-        const next = replaceTextRange(promptRef.current, rangeStart, rangeEnd, replacement);
-        const nextCursor = collapseExpandedComposerCursor(next.text, next.cursor);
-        const nextExpandedCursor = expandCollapsedComposerCursor(next.text, nextCursor);
-        promptRef.current = next.text;
-        const activePendingQuestion = activePendingProgress?.activeQuestion;
-        if (activePendingQuestion && activePendingUserInput) {
-          onChangeActivePendingUserInputCustomAnswer(
-            activePendingQuestion.id,
-            next.text,
-            nextCursor,
-            nextExpandedCursor,
-            false,
-          );
-        } else {
-          setPrompt(next.text);
-        }
-        setComposerCursor(nextCursor);
-        setComposerTrigger(detectComposerTrigger(next.text, nextExpandedCursor));
+  // ------------------------------------------------------------------
+  // Callbacks: prompt replacement / menu
+  // ------------------------------------------------------------------
+  const applyPromptReplacement = useCallback(
+    (
+      rangeStart: number,
+      rangeEnd: number,
+      replacement: string,
+      options?: { expectedText?: string; focusEditorAfterReplace?: boolean },
+    ): boolean => {
+      const currentText = promptRef.current;
+      const safeStart = Math.max(0, Math.min(currentText.length, rangeStart));
+      const safeEnd = Math.max(safeStart, Math.min(currentText.length, rangeEnd));
+      if (
+        options?.expectedText !== undefined &&
+        currentText.slice(safeStart, safeEnd) !== options.expectedText
+      ) {
+        return false;
+      }
+      const next = replaceTextRange(promptRef.current, rangeStart, rangeEnd, replacement);
+      const nextCursor = collapseExpandedComposerCursor(next.text, next.cursor);
+      const nextExpandedCursor = expandCollapsedComposerCursor(next.text, nextCursor);
+      promptRef.current = next.text;
+      const activePendingQuestion = activePendingProgress?.activeQuestion;
+      if (activePendingQuestion && activePendingUserInput) {
+        onChangeActivePendingUserInputCustomAnswer(
+          activePendingQuestion.id,
+          next.text,
+          nextCursor,
+          nextExpandedCursor,
+          false,
+        );
+      } else {
+        setPrompt(next.text);
+      }
+      setComposerCursor(nextCursor);
+      setComposerTrigger(detectComposerTrigger(next.text, nextExpandedCursor));
+      if (options?.focusEditorAfterReplace !== false) {
         window.requestAnimationFrame(() => {
           composerEditorRef.current?.focusAt(nextCursor);
         });
-        return true;
-      },
-      [
-        activePendingProgress?.activeQuestion,
-        activePendingUserInput,
-        onChangeActivePendingUserInputCustomAnswer,
-        promptRef,
-        setPrompt,
-      ],
-    );
-
-    const readComposerSnapshot = useCallback((): {
-      value: string;
-      cursor: number;
-      expandedCursor: number;
-      terminalContextIds: string[];
-    } => {
-      const editorSnapshot = composerEditorRef.current?.readSnapshot();
-      if (editorSnapshot) {
-        return editorSnapshot;
       }
-      return {
-        value: promptRef.current,
-        cursor: composerCursor,
-        expandedCursor: expandCollapsedComposerCursor(promptRef.current, composerCursor),
-        terminalContextIds: composerTerminalContexts.map((context) => context.id),
-      };
-    }, [composerCursor, composerTerminalContexts, promptRef]);
-
-    const resolveActiveComposerTrigger = useCallback((): {
-      snapshot: { value: string; cursor: number; expandedCursor: number };
-      trigger: ComposerTrigger | null;
-    } => {
-      const snapshot = readComposerSnapshot();
-      return {
-        snapshot,
-        trigger: detectComposerTrigger(snapshot.value, snapshot.expandedCursor),
-      };
-    }, [readComposerSnapshot]);
+      return true;
+    },
+    [
+      activePendingProgress?.activeQuestion,
+      activePendingUserInput,
+      onChangeActivePendingUserInputCustomAnswer,
+      promptRef,
+      setPrompt,
+    ],
+  );
 
-    const onSelectComposerItem = useCallback(
-      (item: ComposerCommandItem) => {
-        if (composerSelectLockRef.current) return;
-        composerSelectLockRef.current = true;
-        window.requestAnimationFrame(() => {
-          composerSelectLockRef.current = false;
-        });
-        const { snapshot, trigger } = resolveActiveComposerTrigger();
-        if (!trigger) return;
-        if (item.type === "path") {
-          const replacement = `@${item.path} `;
-          const replacementRangeEnd = extendReplacementRangeForTrailingSpace(
-            snapshot.value,
-            trigger.rangeEnd,
-            replacement,
-          );
-          const applied = applyPromptReplacement(
-            trigger.rangeStart,
-            replacementRangeEnd,
-            replacement,
-            { expectedText: snapshot.value.slice(trigger.rangeStart, replacementRangeEnd) },
-          );
-          if (applied) {
-            setComposerHighlightedItemId(null);
-          }
-          return;
+  const readComposerSnapshot = useCallback((): {
+    value: string;
+    cursor: number;
+    expandedCursor: number;
+    terminalContextIds: string[];
+  } => {
+    const editorSnapshot = composerEditorRef.current?.readSnapshot();
+    if (editorSnapshot) {
+      return editorSnapshot;
+    }
+    return {
+      value: promptRef.current,
+      cursor: composerCursor,
+      expandedCursor: expandCollapsedComposerCursor(promptRef.current, composerCursor),
+      terminalContextIds: composerTerminalContexts.map((context) => context.id),
+    };
+  }, [composerCursor, composerTerminalContexts, promptRef]);
+
+  const resolveActiveComposerTrigger = useCallback((): {
+    snapshot: { value: string; cursor: number; expandedCursor: number };
+    trigger: ComposerTrigger | null;
+  } => {
+    const snapshot = readComposerSnapshot();
+    return {
+      snapshot,
+      trigger: detectComposerTrigger(snapshot.value, snapshot.expandedCursor),
+    };
+  }, [readComposerSnapshot]);
+
+  const onSelectComposerItem = useCallback(
+    (item: ComposerCommandItem) => {
+      if (composerSelectLockRef.current) return;
+      composerSelectLockRef.current = true;
+      window.requestAnimationFrame(() => {
+        composerSelectLockRef.current = false;
+      });
+      const { snapshot, trigger } = resolveActiveComposerTrigger();
+      if (!trigger) return;
+      if (item.type === "path") {
+        const replacement = `@${item.path} `;
+        const replacementRangeEnd = extendReplacementRangeForTrailingSpace(
+          snapshot.value,
+          trigger.rangeEnd,
+          replacement,
+        );
+        const applied = applyPromptReplacement(
+          trigger.rangeStart,
+          replacementRangeEnd,
+          replacement,
+          { expectedText: snapshot.value.slice(trigger.rangeStart, replacementRangeEnd) },
+        );
+        if (applied) {
+          setComposerHighlightedItemId(null);
         }
-        if (item.type === "slash-command") {
-          if (item.command === "model") {
-            const replacement = "/model ";
-            const replacementRangeEnd = extendReplacementRangeForTrailingSpace(
-              snapshot.value,
-              trigger.rangeEnd,
-              replacement,
-            );
-            const applied = applyPromptReplacement(
-              trigger.rangeStart,
-              replacementRangeEnd,
-              replacement,
-              { expectedText: snapshot.value.slice(trigger.rangeStart, replacementRangeEnd) },
-            );
-            if (applied) {
-              setComposerHighlightedItemId(null);
-            }
-            return;
-          }
-          void handleInteractionModeChange(item.command === "plan" ? "plan" : "default");
+        return;
+      }
+      if (item.type === "slash-command") {
+        if (item.command === "model") {
           const applied = applyPromptReplacement(trigger.rangeStart, trigger.rangeEnd, "", {
             expectedText: snapshot.value.slice(trigger.rangeStart, trigger.rangeEnd),
+            focusEditorAfterReplace: false,
           });
           if (applied) {
             setComposerHighlightedItemId(null);
+            setIsComposerModelPickerOpen(true);
           }
           return;
         }
-        if (item.type === "provider-slash-command") {
-          const replacement = `/${item.command.name} `;
-          const replacementRangeEnd = extendReplacementRangeForTrailingSpace(
-            snapshot.value,
-            trigger.rangeEnd,
-            replacement,
-          );
-          const applied = applyPromptReplacement(
-            trigger.rangeStart,
-            replacementRangeEnd,
-            replacement,
-            { expectedText: snapshot.value.slice(trigger.rangeStart, replacementRangeEnd) },
-          );
-          if (applied) {
-            setComposerHighlightedItemId(null);
-          }
-          return;
-        }
-        if (item.type === "skill") {
-          const replacement = `$${item.skill.name} `;
-          const replacementRangeEnd = extendReplacementRangeForTrailingSpace(
-            snapshot.value,
-            trigger.rangeEnd,
-            replacement,
-          );
-          const applied = applyPromptReplacement(
-            trigger.rangeStart,
-            replacementRangeEnd,
-            replacement,
-            { expectedText: snapshot.value.slice(trigger.rangeStart, replacementRangeEnd) },
-          );
-          if (applied) {
-            setComposerHighlightedItemId(null);
-          }
-          return;
-        }
-        onProviderModelSelect(item.provider, item.model);
+        void handleInteractionModeChange(item.command === "plan" ? "plan" : "default");
         const applied = applyPromptReplacement(trigger.rangeStart, trigger.rangeEnd, "", {
           expectedText: snapshot.value.slice(trigger.rangeStart, trigger.rangeEnd),
         });
         if (applied) {
           setComposerHighlightedItemId(null);
         }
-      },
-      [
-        applyPromptReplacement,
-        handleInteractionModeChange,
-        onProviderModelSelect,
-        resolveActiveComposerTrigger,
-      ],
-    );
+        return;
+      }
+      if (item.type === "provider-slash-command") {
+        const replacement = `/${item.command.name} `;
+        const replacementRangeEnd = extendReplacementRangeForTrailingSpace(
+          snapshot.value,
+          trigger.rangeEnd,
+          replacement,
+        );
+        const applied = applyPromptReplacement(
+          trigger.rangeStart,
+          replacementRangeEnd,
+          replacement,
+          { expectedText: snapshot.value.slice(trigger.rangeStart, replacementRangeEnd) },
+        );
+        if (applied) {
+          setComposerHighlightedItemId(null);
+        }
+        return;
+      }
+      if (item.type === "skill") {
+        const replacement = `$${item.skill.name} `;
+        const replacementRangeEnd = extendReplacementRangeForTrailingSpace(
+          snapshot.value,
+          trigger.rangeEnd,
+          replacement,
+        );
+        const applied = applyPromptReplacement(
+          trigger.rangeStart,
+          replacementRangeEnd,
+          replacement,
+          { expectedText: snapshot.value.slice(trigger.rangeStart, replacementRangeEnd) },
+        );
+        if (applied) {
+          setComposerHighlightedItemId(null);
+        }
+        return;
+      }
+    },
+    [applyPromptReplacement, handleInteractionModeChange, resolveActiveComposerTrigger],
+  );
 
-    const onComposerMenuItemHighlighted = useCallback(
-      (itemId: string | null) => {
-        setComposerHighlightedItemId(itemId);
-        setComposerHighlightedSearchKey(composerMenuSearchKey);
-      },
-      [composerMenuSearchKey],
-    );
+  const onComposerMenuItemHighlighted = useCallback(
+    (itemId: string | null) => {
+      setComposerHighlightedItemId(itemId);
+      setComposerHighlightedSearchKey(composerMenuSearchKey);
+    },
+    [composerMenuSearchKey],
+  );
 
-    const nudgeComposerMenuHighlight = useCallback(
-      (key: "ArrowDown" | "ArrowUp") => {
-        if (composerMenuItems.length === 0) return;
-        const highlightedIndex = composerMenuItems.findIndex(
-          (item) => item.id === composerHighlightedItemId,
-        );
-        const normalizedIndex =
-          highlightedIndex >= 0 ? highlightedIndex : key === "ArrowDown" ? -1 : 0;
-        const offset = key === "ArrowDown" ? 1 : -1;
-        const nextIndex =
-          (normalizedIndex + offset + composerMenuItems.length) % composerMenuItems.length;
-        const nextItem = composerMenuItems[nextIndex];
-        setComposerHighlightedItemId(nextItem?.id ?? null);
-      },
-      [composerHighlightedItemId, composerMenuItems],
-    );
+  const nudgeComposerMenuHighlight = useCallback(
+    (key: "ArrowDown" | "ArrowUp") => {
+      if (composerMenuItems.length === 0) return;
+      const highlightedIndex = composerMenuItems.findIndex(
+        (item) => item.id === composerHighlightedItemId,
+      );
+      const normalizedIndex =
+        highlightedIndex >= 0 ? highlightedIndex : key === "ArrowDown" ? -1 : 0;
+      const offset = key === "ArrowDown" ? 1 : -1;
+      const nextIndex =
+        (normalizedIndex + offset + composerMenuItems.length) % composerMenuItems.length;
+      const nextItem = composerMenuItems[nextIndex];
+      setComposerHighlightedItemId(nextItem?.id ?? null);
+    },
+    [composerHighlightedItemId, composerMenuItems],
+  );
 
-    // ------------------------------------------------------------------
-    // Callbacks: command key
-    // ------------------------------------------------------------------
-    const onComposerCommandKey = (
-      key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
-      event: KeyboardEvent,
-    ) => {
-      if (key === "Tab" && event.shiftKey) {
-        toggleInteractionMode();
+  const blurMobileComposerAfterSend = useCallback(() => {
+    if (!isMobileViewport) return;
+    if (composerBlurFrameRef.current !== null) {
+      window.cancelAnimationFrame(composerBlurFrameRef.current);
+      composerBlurFrameRef.current = null;
+    }
+    const activeElement = document.activeElement;
+    if (activeElement instanceof HTMLElement) {
+      activeElement.blur();
+    }
+    setIsComposerFocused(false);
+  }, [isMobileViewport]);
+
+  const shouldBlurMobileComposerOnSubmit = useCallback(() => {
+    if (!isMobileViewport) return false;
+    if (isSendBusy || isConnecting || phase === "running") return false;
+    if (activePendingProgress) {
+      return activePendingProgress.isLastQuestion && Boolean(activePendingResolvedAnswers);
+    }
+    return showPlanFollowUpPrompt || composerSendState.hasSendableContent;
+  }, [
+    activePendingProgress,
+    activePendingResolvedAnswers,
+    composerSendState.hasSendableContent,
+    isConnecting,
+    isMobileViewport,
+    isSendBusy,
+    phase,
+    showPlanFollowUpPrompt,
+  ]);
+
+  const submitComposer = useCallback(
+    (event?: { preventDefault: () => void }) => {
+      onSend(event);
+      if (shouldBlurMobileComposerOnSubmit()) {
+        blurMobileComposerAfterSend();
+      }
+    },
+    [blurMobileComposerAfterSend, onSend, shouldBlurMobileComposerOnSubmit],
+  );
+  const expandMobileComposer = useCallback(() => {
+    if (composerBlurFrameRef.current !== null) {
+      window.cancelAnimationFrame(composerBlurFrameRef.current);
+      composerBlurFrameRef.current = null;
+    }
+    if (mobileComposerExpandFrameRef.current !== null) {
+      window.cancelAnimationFrame(mobileComposerExpandFrameRef.current);
+    }
+    if (mobileComposerExpandReleaseFrameRef.current !== null) {
+      window.cancelAnimationFrame(mobileComposerExpandReleaseFrameRef.current);
+    }
+    mobileComposerExpandInFlightRef.current = true;
+    setIsComposerFocused(true);
+    mobileComposerExpandFrameRef.current = window.requestAnimationFrame(() => {
+      mobileComposerExpandFrameRef.current = null;
+      composerEditorRef.current?.focusAtEnd();
+      mobileComposerExpandReleaseFrameRef.current = window.requestAnimationFrame(() => {
+        mobileComposerExpandReleaseFrameRef.current = null;
+        mobileComposerExpandInFlightRef.current = false;
+      });
+    });
+  }, []);
+
+  // ------------------------------------------------------------------
+  // Callbacks: command key
+  // ------------------------------------------------------------------
+  const onComposerCommandKey = (
+    key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
+    event: KeyboardEvent,
+  ) => {
+    if (key === "Tab" && event.shiftKey) {
+      toggleInteractionMode();
+      return true;
+    }
+    const { trigger } = resolveActiveComposerTrigger();
+    const menuIsActive = composerMenuOpenRef.current || trigger !== null;
+    if (menuIsActive) {
+      const currentItems = composerMenuItemsRef.current;
+      const selectedItem = activeComposerMenuItemRef.current ?? currentItems[0];
+      if (key === "ArrowDown" && currentItems.length > 0) {
+        nudgeComposerMenuHighlight("ArrowDown");
         return true;
       }
-      const { trigger } = resolveActiveComposerTrigger();
-      const menuIsActive = composerMenuOpenRef.current || trigger !== null;
-      if (menuIsActive) {
-        const currentItems = composerMenuItemsRef.current;
-        const selectedItem = activeComposerMenuItemRef.current ?? currentItems[0];
-        if (key === "ArrowDown" && currentItems.length > 0) {
-          nudgeComposerMenuHighlight("ArrowDown");
-          return true;
-        }
-        if (key === "ArrowUp" && currentItems.length > 0) {
-          nudgeComposerMenuHighlight("ArrowUp");
-          return true;
-        }
-        if ((key === "Enter" || key === "Tab") && selectedItem) {
-          onSelectComposerItem(selectedItem);
-          return true;
-        }
+      if (key === "ArrowUp" && currentItems.length > 0) {
+        nudgeComposerMenuHighlight("ArrowUp");
+        return true;
       }
-      if (key === "Enter" && !event.shiftKey) {
-        void onSend();
+      if ((key === "Enter" || key === "Tab") && selectedItem) {
+        onSelectComposerItem(selectedItem);
         return true;
       }
-      return false;
-    };
+    }
+    if (key === "Enter" && !event.shiftKey) {
+      submitComposer();
+      return true;
+    }
+    return false;
+  };
 
-    // ------------------------------------------------------------------
-    // Callbacks: images
-    // ------------------------------------------------------------------
-    const addComposerImages = (files: File[]) => {
-      if (!activeThreadId || files.length === 0) return;
-      if (pendingUserInputs.length > 0) {
-        toastManager.add({
-          type: "error",
-          title: "Attach images after answering plan questions.",
-        });
-        return;
+  // ------------------------------------------------------------------
+  // Callbacks: images
+  // ------------------------------------------------------------------
+  const addComposerImages = (files: File[]) => {
+    if (!activeThreadId || files.length === 0) return;
+    if (pendingUserInputs.length > 0) {
+      toastManager.add({
+        type: "error",
+        title: "Attach images after answering plan questions.",
+      });
+      return;
+    }
+    const nextImages: ComposerImageAttachment[] = [];
+    let nextImageCount = composerImagesRef.current.length;
+    let error: string | null = null;
+    for (const file of files) {
+      if (!file.type.startsWith("image/")) {
+        error = `Unsupported file type for '${file.name}'. Please attach image files only.`;
+        continue;
       }
-      const nextImages: ComposerImageAttachment[] = [];
-      let nextImageCount = composerImagesRef.current.length;
-      let error: string | null = null;
-      for (const file of files) {
-        if (!file.type.startsWith("image/")) {
-          error = `Unsupported file type for '${file.name}'. Please attach image files only.`;
-          continue;
-        }
-        if (file.size > PROVIDER_SEND_TURN_MAX_IMAGE_BYTES) {
-          error = `'${file.name}' exceeds the ${IMAGE_SIZE_LIMIT_LABEL} attachment limit.`;
-          continue;
-        }
-        if (nextImageCount >= PROVIDER_SEND_TURN_MAX_ATTACHMENTS) {
-          error = `You can attach up to ${PROVIDER_SEND_TURN_MAX_ATTACHMENTS} images per message.`;
-          break;
-        }
-        const previewUrl = URL.createObjectURL(file);
-        nextImages.push({
-          type: "image",
-          id: randomUUID(),
-          name: file.name || "image",
-          mimeType: file.type,
-          sizeBytes: file.size,
-          previewUrl,
-          file,
-        });
-        nextImageCount += 1;
+      if (file.size > PROVIDER_SEND_TURN_MAX_IMAGE_BYTES) {
+        error = `'${file.name}' exceeds the ${IMAGE_SIZE_LIMIT_LABEL} attachment limit.`;
+        continue;
       }
-      if (nextImages.length === 1 && nextImages[0]) {
-        addComposerImage(nextImages[0]);
-      } else if (nextImages.length > 1) {
-        addComposerImagesToDraft(nextImages);
+      if (nextImageCount >= PROVIDER_SEND_TURN_MAX_ATTACHMENTS) {
+        error = `You can attach up to ${PROVIDER_SEND_TURN_MAX_ATTACHMENTS} images per message.`;
+        break;
       }
-      setThreadError(activeThreadId, error);
-    };
+      const previewUrl = URL.createObjectURL(file);
+      nextImages.push({
+        type: "image",
+        id: randomUUID(),
+        name: file.name || "image",
+        mimeType: file.type,
+        sizeBytes: file.size,
+        previewUrl,
+        file,
+      });
+      nextImageCount += 1;
+    }
+    if (nextImages.length === 1 && nextImages[0]) {
+      addComposerImage(nextImages[0]);
+    } else if (nextImages.length > 1) {
+      addComposerImagesToDraft(nextImages);
+    }
+    setThreadError(activeThreadId, error);
+  };
 
-    const removeComposerImage = (imageId: string) => {
-      removeComposerImageFromDraft(imageId);
-    };
+  const removeComposerImage = (imageId: string) => {
+    removeComposerImageFromDraft(imageId);
+  };
 
-    // ------------------------------------------------------------------
-    // Callbacks: paste / drag
-    // ------------------------------------------------------------------
-    const onComposerPaste = (event: React.ClipboardEvent<HTMLElement>) => {
-      const files = Array.from(event.clipboardData.files);
-      if (files.length === 0) return;
-      const imageFiles = files.filter((file) => file.type.startsWith("image/"));
-      if (imageFiles.length === 0) return;
-      event.preventDefault();
-      addComposerImages(imageFiles);
-    };
+  // ------------------------------------------------------------------
+  // Callbacks: paste / drag
+  // ------------------------------------------------------------------
+  const onComposerPaste = (event: React.ClipboardEvent<HTMLElement>) => {
+    const files = Array.from(event.clipboardData.files);
+    if (files.length === 0) return;
+    const imageFiles = files.filter((file) => file.type.startsWith("image/"));
+    if (imageFiles.length === 0) return;
+    event.preventDefault();
+    addComposerImages(imageFiles);
+  };
 
-    const onComposerDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
-      if (!event.dataTransfer.types.includes("Files")) return;
-      event.preventDefault();
-      dragDepthRef.current += 1;
-      setIsDragOverComposer(true);
-    };
+  const onComposerDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
+    if (!event.dataTransfer.types.includes("Files")) return;
+    event.preventDefault();
+    dragDepthRef.current += 1;
+    setIsDragOverComposer(true);
+  };
 
-    const onComposerDragOver = (event: React.DragEvent<HTMLDivElement>) => {
-      if (!event.dataTransfer.types.includes("Files")) return;
-      event.preventDefault();
-      event.dataTransfer.dropEffect = "copy";
-      setIsDragOverComposer(true);
-    };
+  const onComposerDragOver = (event: React.DragEvent<HTMLDivElement>) => {
+    if (!event.dataTransfer.types.includes("Files")) return;
+    event.preventDefault();
+    event.dataTransfer.dropEffect = "copy";
+    setIsDragOverComposer(true);
+  };
+
+  const onComposerDragLeave = (event: React.DragEvent<HTMLDivElement>) => {
+    if (!event.dataTransfer.types.includes("Files")) return;
+    event.preventDefault();
+    const nextTarget = event.relatedTarget;
+    if (nextTarget instanceof Node && event.currentTarget.contains(nextTarget)) return;
+    dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+    if (dragDepthRef.current === 0) {
+      setIsDragOverComposer(false);
+    }
+  };
 
-    const onComposerDragLeave = (event: React.DragEvent<HTMLDivElement>) => {
-      if (!event.dataTransfer.types.includes("Files")) return;
-      event.preventDefault();
-      const nextTarget = event.relatedTarget;
-      if (nextTarget instanceof Node && event.currentTarget.contains(nextTarget)) return;
-      dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
-      if (dragDepthRef.current === 0) {
-        setIsDragOverComposer(false);
+  const onComposerDrop = (event: React.DragEvent<HTMLDivElement>) => {
+    if (!event.dataTransfer.types.includes("Files")) return;
+    event.preventDefault();
+    dragDepthRef.current = 0;
+    setIsDragOverComposer(false);
+    const files = Array.from(event.dataTransfer.files);
+    addComposerImages(files);
+    focusComposer();
+  };
+  const handleInterruptPrimaryAction = useCallback(() => {
+    void onInterrupt();
+  }, [onInterrupt]);
+  const handleImplementPlanInNewThreadPrimaryAction = useCallback(() => {
+    void onImplementPlanInNewThread();
+  }, [onImplementPlanInNewThread]);
+  const scheduleComposerCollapseCheck = useCallback(() => {
+    if (!isMobileViewport) {
+      return;
+    }
+    if (mobileComposerExpandInFlightRef.current) {
+      return;
+    }
+    if (composerBlurFrameRef.current !== null) {
+      window.cancelAnimationFrame(composerBlurFrameRef.current);
+    }
+    composerBlurFrameRef.current = window.requestAnimationFrame(() => {
+      composerBlurFrameRef.current = null;
+      if (mobileComposerExpandInFlightRef.current) {
+        return;
       }
-    };
+      const composerSurface = composerSurfaceRef.current;
+      const activeElement = document.activeElement;
+      if (activeElement instanceof Element && isInsideComposerFloatingLayer(activeElement)) {
+        return;
+      }
+      if (
+        composerSurface &&
+        activeElement instanceof Node &&
+        composerSurface.contains(activeElement)
+      ) {
+        return;
+      }
+      setIsComposerFocused(false);
+    });
+  }, [isMobileViewport]);
 
-    const onComposerDrop = (event: React.DragEvent<HTMLDivElement>) => {
-      if (!event.dataTransfer.types.includes("Files")) return;
-      event.preventDefault();
-      dragDepthRef.current = 0;
-      setIsDragOverComposer(false);
-      const files = Array.from(event.dataTransfer.files);
-      addComposerImages(files);
-      focusComposer();
+  useEffect(() => {
+    return () => {
+      if (composerBlurFrameRef.current !== null) {
+        window.cancelAnimationFrame(composerBlurFrameRef.current);
+      }
+      if (mobileComposerExpandFrameRef.current !== null) {
+        window.cancelAnimationFrame(mobileComposerExpandFrameRef.current);
+      }
+      if (mobileComposerExpandReleaseFrameRef.current !== null) {
+        window.cancelAnimationFrame(mobileComposerExpandReleaseFrameRef.current);
+      }
     };
-    const handleInterruptPrimaryAction = useCallback(() => {
-      void onInterrupt();
-    }, [onInterrupt]);
-    const handleImplementPlanInNewThreadPrimaryAction = useCallback(() => {
-      void onImplementPlanInNewThread();
-    }, [onImplementPlanInNewThread]);
-
-    // ------------------------------------------------------------------
-    // Imperative handle
-    // ------------------------------------------------------------------
-    useImperativeHandle(
-      ref,
-      () => ({
-        focusAtEnd: () => {
-          composerEditorRef.current?.focusAtEnd();
-        },
-        focusAt: (cursor: number) => {
-          composerEditorRef.current?.focusAt(cursor);
-        },
-        readSnapshot: () => {
-          return readComposerSnapshot();
-        },
-        resetCursorState: (options?: {
-          cursor?: number;
-          prompt?: string;
-          detectTrigger?: boolean;
-        }) => {
-          const promptForState = options?.prompt ?? promptRef.current;
-          const cursor = clampCollapsedComposerCursor(promptForState, options?.cursor ?? 0);
-          setComposerHighlightedItemId(null);
-          setComposerCursor(cursor);
-          setComposerTrigger(
-            options?.detectTrigger
-              ? detectComposerTrigger(
-                  promptForState,
-                  expandCollapsedComposerCursor(promptForState, cursor),
-                )
-              : null,
-          );
-        },
-        addTerminalContext: (selection: TerminalContextSelection) => {
-          if (!activeThread) return;
-          const snapshot = composerEditorRef.current?.readSnapshot() ?? {
-            value: promptRef.current,
-            cursor: composerCursor,
-            expandedCursor: expandCollapsedComposerCursor(promptRef.current, composerCursor),
-            terminalContextIds: composerTerminalContexts.map((context) => context.id),
-          };
-          const insertion = insertInlineTerminalContextPlaceholder(
-            snapshot.value,
-            snapshot.expandedCursor,
-          );
-          const nextCollapsedCursor = collapseExpandedComposerCursor(
-            insertion.prompt,
-            insertion.cursor,
-          );
-          const inserted = insertComposerDraftTerminalContext(
-            composerDraftTarget,
-            insertion.prompt,
-            {
-              id: randomUUID(),
-              threadId: activeThread.id,
-              createdAt: new Date().toISOString(),
-              ...selection,
-            },
-            insertion.contextIndex,
-          );
-          if (!inserted) return;
-          promptRef.current = insertion.prompt;
-          setComposerCursor(nextCollapsedCursor);
-          setComposerTrigger(detectComposerTrigger(insertion.prompt, insertion.cursor));
-          window.requestAnimationFrame(() => {
-            composerEditorRef.current?.focusAt(nextCollapsedCursor);
-          });
-        },
-        getSendContext: () => ({
-          prompt: promptRef.current,
-          images: composerImagesRef.current,
-          terminalContexts: composerTerminalContextsRef.current,
-          selectedPromptEffort,
-          selectedModelOptionsForDispatch,
-          selectedModelSelection,
-          selectedProvider,
-          selectedModel,
-          selectedProviderModels,
-        }),
-      }),
-      [
-        activeThread,
-        composerDraftTarget,
-        composerCursor,
-        composerTerminalContexts,
-        insertComposerDraftTerminalContext,
-        promptRef,
-        composerImagesRef,
-        composerTerminalContextsRef,
-        readComposerSnapshot,
-        selectedModel,
+  }, []);
+
+  // ------------------------------------------------------------------
+  // Imperative handle
+  // ------------------------------------------------------------------
+  useImperativeHandle(
+    composerRef,
+    () => ({
+      focusAtEnd: () => {
+        composerEditorRef.current?.focusAtEnd();
+      },
+      focusAt: (cursor: number) => {
+        composerEditorRef.current?.focusAt(cursor);
+      },
+      openModelPicker: () => {
+        setIsComposerModelPickerOpen(true);
+      },
+      toggleModelPicker: () => {
+        setIsComposerModelPickerOpen((open) => !open);
+      },
+      isModelPickerOpen: () => isComposerModelPickerOpen,
+      readSnapshot: () => {
+        return readComposerSnapshot();
+      },
+      resetCursorState: (options?: {
+        cursor?: number;
+        prompt?: string;
+        detectTrigger?: boolean;
+      }) => {
+        const promptForState = options?.prompt ?? promptRef.current;
+        const cursor = clampCollapsedComposerCursor(promptForState, options?.cursor ?? 0);
+        setComposerHighlightedItemId(null);
+        setComposerCursor(cursor);
+        setComposerTrigger(
+          options?.detectTrigger
+            ? detectComposerTrigger(
+                promptForState,
+                expandCollapsedComposerCursor(promptForState, cursor),
+              )
+            : null,
+        );
+      },
+      addTerminalContext: (selection: TerminalContextSelection) => {
+        if (!activeThread) return;
+        const snapshot = composerEditorRef.current?.readSnapshot() ?? {
+          value: promptRef.current,
+          cursor: composerCursor,
+          expandedCursor: expandCollapsedComposerCursor(promptRef.current, composerCursor),
+          terminalContextIds: composerTerminalContexts.map((context) => context.id),
+        };
+        const insertion = insertInlineTerminalContextPlaceholder(
+          snapshot.value,
+          snapshot.expandedCursor,
+        );
+        const nextCollapsedCursor = collapseExpandedComposerCursor(
+          insertion.prompt,
+          insertion.cursor,
+        );
+        const inserted = insertComposerDraftTerminalContext(
+          composerDraftTarget,
+          insertion.prompt,
+          {
+            id: randomUUID(),
+            threadId: activeThread.id,
+            createdAt: new Date().toISOString(),
+            ...selection,
+          },
+          insertion.contextIndex,
+        );
+        if (!inserted) return;
+        promptRef.current = insertion.prompt;
+        setComposerCursor(nextCollapsedCursor);
+        setComposerTrigger(detectComposerTrigger(insertion.prompt, insertion.cursor));
+        window.requestAnimationFrame(() => {
+          composerEditorRef.current?.focusAt(nextCollapsedCursor);
+        });
+      },
+      getSendContext: () => ({
+        prompt: promptRef.current,
+        images: composerImagesRef.current,
+        terminalContexts: composerTerminalContextsRef.current,
+        selectedPromptEffort,
         selectedModelOptionsForDispatch,
         selectedModelSelection,
-        selectedPromptEffort,
         selectedProvider,
+        selectedModel,
         selectedProviderModels,
-      ],
-    );
+      }),
+    }),
+    [
+      activeThread,
+      composerDraftTarget,
+      composerCursor,
+      composerTerminalContexts,
+      insertComposerDraftTerminalContext,
+      promptRef,
+      composerImagesRef,
+      composerTerminalContextsRef,
+      isComposerModelPickerOpen,
+      readComposerSnapshot,
+      selectedModel,
+      selectedModelOptionsForDispatch,
+      selectedModelSelection,
+      selectedPromptEffort,
+      selectedProvider,
+      selectedProviderModels,
+    ],
+  );
 
-    // Render
-    // ------------------------------------------------------------------
-    return (
-      <form
-        ref={composerFormRef}
-        onSubmit={onSend}
-        className="mx-auto w-full min-w-0 max-w-208"
-        data-chat-composer-form="true"
+  // Render
+  // ------------------------------------------------------------------
+  return (
+    <form
+      ref={composerFormRef}
+      onSubmit={submitComposer}
+      className="mx-auto w-full min-w-0 max-w-208"
+      data-chat-composer-form="true"
+    >
+      <div
+        className={cn(
+          "group rounded-[22px] p-px transition-colors duration-200",
+          composerProviderState.composerFrameClassName,
+        )}
+        onDragEnter={onComposerDragEnter}
+        onDragOver={onComposerDragOver}
+        onDragLeave={onComposerDragLeave}
+        onDrop={onComposerDrop}
       >
         <div
+          ref={composerSurfaceRef}
+          data-chat-composer-mobile-collapsed={isComposerCollapsedMobile ? "true" : "false"}
           className={cn(
-            "group rounded-[22px] p-px transition-colors duration-200",
-            composerProviderState.composerFrameClassName,
+            "rounded-[20px] border bg-card transition-colors duration-200 has-focus-visible:border-ring/45",
+            isDragOverComposer ? "border-primary/70 bg-accent/30" : "border-border",
+            environmentUnavailable ? "opacity-75" : null,
+            composerProviderState.composerSurfaceClassName,
           )}
-          onDragEnter={onComposerDragEnter}
-          onDragOver={onComposerDragOver}
-          onDragLeave={onComposerDragLeave}
-          onDrop={onComposerDrop}
+          onFocusCapture={(event) => {
+            const activeElement = event.target;
+            if (
+              isComposerCollapsedMobile &&
+              activeElement instanceof HTMLElement &&
+              activeElement.closest('[data-chat-composer-collapsed-controls="true"]')
+            ) {
+              return;
+            }
+            if (composerBlurFrameRef.current !== null) {
+              window.cancelAnimationFrame(composerBlurFrameRef.current);
+              composerBlurFrameRef.current = null;
+            }
+            setIsComposerFocused(true);
+          }}
+          onBlurCapture={() => {
+            scheduleComposerCollapseCheck();
+          }}
         >
-          <div
-            className={cn(
-              "rounded-[20px] border bg-card transition-colors duration-200 has-focus-visible:border-ring/45",
-              isDragOverComposer ? "border-primary/70 bg-accent/30" : "border-border",
-              composerProviderState.composerSurfaceClassName,
-            )}
-          >
-            {activePendingApproval ? (
+          {!isComposerCollapsedMobile &&
+            (activePendingApproval ? (
               <div className="rounded-t-[19px] border-b border-border/65 bg-muted/20">
                 <ComposerPendingApprovalPanel
                   approval={activePendingApproval}
@@ -1755,102 +2009,224 @@ export const ChatComposer = memo(
                   planTitle={proposedPlanTitle(activeProposedPlan.planMarkdown) ?? null}
                 />
               </div>
-            ) : null}
+            ) : null)}
 
+          {isComposerCollapsedMobile && activePendingApproval ? (
             <div
-              className={cn(
-                "relative px-3 pb-2 sm:px-4",
-                hasComposerHeader ? "pt-2.5 sm:pt-3" : "pt-3.5 sm:pt-4",
-              )}
+              className="rounded-t-[19px] border-b border-border/65 bg-muted/20"
+              data-chat-composer-collapsed-controls="true"
             >
-              {composerMenuOpen && !isComposerApprovalState && (
-                <div className="absolute inset-x-0 bottom-full z-20 mb-2 px-1">
-                  <ComposerCommandMenu
-                    items={composerMenuItems}
-                    resolvedTheme={resolvedTheme}
-                    isLoading={isComposerMenuLoading}
-                    triggerKind={composerTriggerKind}
-                    groupSlashCommandSections={
-                      composerTrigger?.kind === "slash-command" &&
-                      composerTrigger.query.trim().length === 0
-                    }
-                    emptyStateText={composerMenuEmptyState}
-                    activeItemId={activeComposerMenuItem?.id ?? null}
-                    onHighlightedItemChange={onComposerMenuItemHighlighted}
-                    onSelect={onSelectComposerItem}
-                  />
+              <ComposerPendingApprovalPanel
+                approval={activePendingApproval}
+                pendingCount={pendingApprovals.length}
+              />
+              <div className="flex flex-wrap items-center justify-end gap-2 px-3 pb-3 sm:px-4">
+                <ComposerPendingApprovalActions
+                  requestId={activePendingApproval.requestId}
+                  isResponding={respondingRequestIds.includes(activePendingApproval.requestId)}
+                  onRespondToApproval={onRespondToApproval}
+                />
+              </div>
+            </div>
+          ) : isComposerCollapsedMobile && pendingUserInputs.length > 0 ? (
+            <div
+              className="rounded-t-[19px] border-b border-border/65 bg-muted/20"
+              data-chat-composer-collapsed-controls="true"
+            >
+              <ComposerPendingUserInputPanel
+                pendingUserInputs={pendingUserInputs}
+                respondingRequestIds={respondingRequestIds}
+                answers={activePendingDraftAnswers}
+                questionIndex={activePendingQuestionIndex}
+                onToggleOption={onSelectActivePendingUserInputOption}
+                onAdvance={onAdvanceActivePendingUserInput}
+              />
+              <div className="px-3 pb-3 sm:px-4">
+                <div
+                  data-chat-composer-mobile-pending-compact="true"
+                  className={cn(
+                    "flex min-w-0 items-center gap-2 rounded-lg border border-border/55 bg-background/55 p-1.5 pl-3 transition-colors hover:bg-background/80",
+                    !activePendingProgress?.activeQuestion?.multiSelect && "p-0",
+                  )}
+                >
+                  <button
+                    type="button"
+                    className={cn(
+                      "min-w-0 flex-1 truncate bg-transparent py-1.5 text-left text-sm",
+                      activePendingProgress?.customAnswer
+                        ? "text-foreground"
+                        : "text-muted-foreground/60",
+                      !activePendingProgress?.activeQuestion?.multiSelect && "px-3 py-2",
+                    )}
+                    onPointerDown={(event) => event.preventDefault()}
+                    onClick={expandMobileComposer}
+                    aria-label="Write custom answer"
+                  >
+                    {activePendingProgress?.customAnswer || "Write custom answer"}
+                  </button>
+                  {activePendingProgress?.activeQuestion?.multiSelect ? (
+                    <ComposerPrimaryActions
+                      compact
+                      pendingAction={pendingPrimaryAction}
+                      isRunning={false}
+                      showPlanFollowUpPrompt={false}
+                      promptHasText={false}
+                      isSendBusy={isSendBusy}
+                      isConnecting={isConnecting}
+                      isEnvironmentUnavailable={environmentUnavailable !== null}
+                      isPreparingWorktree={false}
+                      hasSendableContent={false}
+                      preserveComposerFocusOnPointerDown
+                      onPreviousPendingQuestion={onPreviousActivePendingUserInputQuestion}
+                      onInterrupt={handleInterruptPrimaryAction}
+                      onImplementPlanInNewThread={handleImplementPlanInNewThreadPrimaryAction}
+                    />
+                  ) : null}
                 </div>
-              )}
+              </div>
+            </div>
+          ) : null}
 
-              {!isComposerApprovalState &&
-                pendingUserInputs.length === 0 &&
-                composerImages.length > 0 && (
-                  <div className="mb-3 flex flex-wrap gap-2">
-                    {composerImages.map((image) => (
-                      <div
-                        key={image.id}
-                        className="relative h-16 w-16 overflow-hidden rounded-lg border border-border/80 bg-background"
-                      >
-                        {image.previewUrl ? (
-                          <button
-                            type="button"
-                            className="h-full w-full cursor-zoom-in"
-                            aria-label={`Preview ${image.name}`}
-                            onClick={() => {
-                              const preview = buildExpandedImagePreview(composerImages, image.id);
-                              if (!preview) return;
-                              onExpandImage(preview);
-                            }}
-                          >
-                            <img
-                              src={image.previewUrl}
-                              alt={image.name}
-                              className="h-full w-full object-cover"
-                            />
-                          </button>
-                        ) : (
-                          <div className="flex h-full w-full items-center justify-center px-1 text-center text-[10px] text-muted-foreground/70">
-                            {image.name}
-                          </div>
-                        )}
-                        {nonPersistedComposerImageIdSet.has(image.id) && (
-                          <Tooltip>
-                            <TooltipTrigger
-                              render={
-                                <span
-                                  role="img"
-                                  aria-label="Draft attachment may not persist"
-                                  className="absolute left-1 top-1 inline-flex items-center justify-center rounded bg-background/85 p-0.5 text-amber-600"
-                                >
-                                  <CircleAlertIcon className="size-3" />
-                                </span>
-                              }
-                            />
-                            <TooltipPopup
-                              side="top"
-                              className="max-w-64 whitespace-normal leading-tight"
-                            >
-                              Draft attachment could not be saved locally and may be lost on
-                              navigation.
-                            </TooltipPopup>
-                          </Tooltip>
-                        )}
-                        <Button
-                          variant="ghost"
-                          size="icon-xs"
-                          className="absolute right-1 top-1 bg-background/80 hover:bg-background/90"
-                          onClick={() => removeComposerImage(image.id)}
-                          aria-label={`Remove ${image.name}`}
-                        >
-                          <XIcon />
-                        </Button>
-                      </div>
-                    ))}
-                  </div>
+          {showCollapsedMobilePromptRow ? (
+            <div className="flex items-center justify-between gap-2 px-3 py-2">
+              <button
+                type="button"
+                className={cn(
+                  "min-w-0 flex-1 truncate bg-transparent p-0 text-left text-[14px] focus:outline-none",
+                  (activePendingProgress ? activePendingProgress.customAnswer : prompt.trim())
+                    ? "text-foreground"
+                    : "text-muted-foreground/35",
                 )}
+                onPointerDown={(event) => event.preventDefault()}
+                onClick={expandMobileComposer}
+                aria-label="Expand composer"
+              >
+                {activePendingProgress
+                  ? activePendingProgress.customAnswer ||
+                    "Type your own answer, or leave this blank to use the selected option"
+                  : prompt.trim() || "Ask anything..."}
+              </button>
+              <button
+                type="button"
+                className="flex size-8 shrink-0 items-center justify-center rounded-full bg-primary/90 text-primary-foreground disabled:opacity-30"
+                disabled={collapsedComposerPrimaryActionDisabled}
+                aria-label={collapsedComposerPrimaryActionLabel}
+                onPointerDown={(event) => event.preventDefault()}
+                onClick={(event) => {
+                  event.stopPropagation();
+                  submitComposer();
+                }}
+              >
+                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+                  <path
+                    d="M8 3L8 13M8 3L4 7M8 3L12 7"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              </button>
+            </div>
+          ) : null}
 
+          <div
+            className={cn(
+              "relative px-3 pb-2 sm:px-4",
+              hasComposerHeader ? "pt-2.5 sm:pt-3" : "pt-3.5 sm:pt-4",
+              isComposerCollapsedMobile && "hidden",
+            )}
+          >
+            {composerMenuOpen && !isComposerApprovalState && (
+              <div className="absolute inset-x-0 bottom-full z-20 mb-2 px-1">
+                <ComposerCommandMenu
+                  items={composerMenuItems}
+                  resolvedTheme={resolvedTheme}
+                  isLoading={isComposerMenuLoading}
+                  triggerKind={composerTriggerKind}
+                  groupSlashCommandSections={
+                    composerTrigger?.kind === "slash-command" &&
+                    composerTrigger.query.trim().length === 0
+                  }
+                  emptyStateText={composerMenuEmptyState}
+                  activeItemId={activeComposerMenuItem?.id ?? null}
+                  onHighlightedItemChange={onComposerMenuItemHighlighted}
+                  onSelect={onSelectComposerItem}
+                />
+              </div>
+            )}
+
+            {!isComposerCollapsedMobile &&
+              !isComposerApprovalState &&
+              pendingUserInputs.length === 0 &&
+              composerImages.length > 0 && (
+                <div className="mb-3 flex flex-wrap gap-2">
+                  {composerImages.map((image) => (
+                    <div
+                      key={image.id}
+                      className="relative h-16 w-16 overflow-hidden rounded-lg border border-border/80 bg-background"
+                    >
+                      {image.previewUrl ? (
+                        <button
+                          type="button"
+                          className="h-full w-full cursor-zoom-in"
+                          aria-label={`Preview ${image.name}`}
+                          onClick={() => {
+                            const preview = buildExpandedImagePreview(composerImages, image.id);
+                            if (!preview) return;
+                            onExpandImage(preview);
+                          }}
+                        >
+                          <img
+                            src={image.previewUrl}
+                            alt={image.name}
+                            className="h-full w-full object-cover"
+                          />
+                        </button>
+                      ) : (
+                        <div className="flex h-full w-full items-center justify-center px-1 text-center text-[10px] text-muted-foreground/70">
+                          {image.name}
+                        </div>
+                      )}
+                      {nonPersistedComposerImageIdSet.has(image.id) && (
+                        <Tooltip>
+                          <TooltipTrigger
+                            render={
+                              <span
+                                role="img"
+                                aria-label="Draft attachment may not persist"
+                                className="absolute left-1 top-1 inline-flex items-center justify-center rounded bg-background/85 p-0.5 text-amber-600"
+                              >
+                                <CircleAlertIcon className="size-3" />
+                              </span>
+                            }
+                          />
+                          <TooltipPopup
+                            side="top"
+                            className="max-w-64 whitespace-normal leading-tight"
+                          >
+                            Draft attachment could not be saved locally and may be lost on
+                            navigation.
+                          </TooltipPopup>
+                        </Tooltip>
+                      )}
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        className="absolute right-1 top-1 bg-background/80 hover:bg-background/90"
+                        onClick={() => removeComposerImage(image.id)}
+                        aria-label={`Remove ${image.name}`}
+                      >
+                        <XIcon />
+                      </Button>
+                    </div>
+                  ))}
+                </div>
+              )}
+
+            <div className="relative">
               <ComposerPromptEditor
-                ref={composerEditorRef}
+                editorRef={composerEditorRef}
                 value={
                   isComposerApprovalState
                     ? ""
@@ -1865,6 +2241,7 @@ export const ChatComposer = memo(
                     : []
                 }
                 skills={selectedProviderStatus?.skills ?? []}
+                {...(showMobilePendingAnswerActions ? { className: "max-sm:pb-11" } : {})}
                 onRemoveTerminalContext={removeComposerTerminalContextFromDraft}
                 onChange={onPromptChange}
                 onCommandKeyDown={onComposerCommandKey}
@@ -1876,115 +2253,156 @@ export const ChatComposer = memo(
                       ? "Type your own answer, or leave this blank to use the selected option"
                       : showPlanFollowUpPrompt && activeProposedPlan
                         ? "Add feedback to refine the plan, or leave this blank to implement it"
-                        : phase === "disconnected"
-                          ? "Ask for follow-up changes or attach images"
-                          : "Ask anything, @tag files/folders, or use / to show available commands"
+                        : environmentUnavailable
+                          ? `${environmentUnavailable.label} is ${
+                              environmentUnavailable.connectionState === "connecting"
+                                ? "connecting"
+                                : "disconnected"
+                            }`
+                          : phase === "disconnected"
+                            ? "Ask for follow-up changes or attach images"
+                            : "Ask anything, @tag files/folders, $use skills, or / for commands"
+                }
+                disabled={
+                  isConnecting ||
+                  isComposerApprovalState ||
+                  (environmentUnavailable !== null && activePendingProgress === null)
                 }
-                disabled={isConnecting || isComposerApprovalState}
               />
-            </div>
-
-            {/* Bottom toolbar */}
-            {activePendingApproval ? (
-              <div className="flex items-center justify-end gap-2 px-2.5 pb-2.5 sm:px-3 sm:pb-3">
-                <ComposerPendingApprovalActions
-                  requestId={activePendingApproval.requestId}
-                  isResponding={respondingRequestIds.includes(activePendingApproval.requestId)}
-                  onRespondToApproval={onRespondToApproval}
-                />
-              </div>
-            ) : (
-              <div
-                data-chat-composer-footer="true"
-                data-chat-composer-footer-compact={isComposerFooterCompact ? "true" : "false"}
-                className={cn(
-                  "flex min-w-0 flex-nowrap items-center justify-between gap-2 overflow-visible px-2.5 pb-2.5 sm:px-3 sm:pb-3",
-                  isComposerFooterCompact ? "gap-1.5" : "gap-2 sm:gap-0",
-                )}
-              >
-                <div className="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
-                  <ProviderModelPicker
-                    compact={isComposerFooterCompact}
-                    provider={selectedProvider}
-                    model={selectedModelForPickerWithCustomFallback}
-                    lockedProvider={lockedProvider}
-                    providers={providerStatuses}
-                    modelOptionsByProvider={modelOptionsByProvider}
-                    {...(composerProviderState.modelPickerIconClassName
-                      ? {
-                          activeProviderIconClassName:
-                            composerProviderState.modelPickerIconClassName,
-                        }
-                      : {})}
-                    onProviderModelChange={onProviderModelSelect}
-                  />
-
-                  {isComposerFooterCompact ? (
-                    <CompactComposerControlsMenu
-                      activePlan={showPlanSidebarToggle}
-                      interactionMode={interactionMode}
-                      planSidebarOpen={planSidebarOpen}
-                      runtimeMode={runtimeMode}
-                      traitsMenuContent={providerTraitsMenuContent}
-                      onToggleInteractionMode={toggleInteractionMode}
-                      onTogglePlanSidebar={togglePlanSidebar}
-                      onRuntimeModeChange={handleRuntimeModeChange}
-                    />
-                  ) : (
-                    <>
-                      {providerTraitsPicker ? (
-                        <>
-                          <Separator
-                            orientation="vertical"
-                            className="mx-0.5 hidden h-4 sm:block"
-                          />
-                          {providerTraitsPicker}
-                        </>
-                      ) : null}
-                      <ComposerFooterModeControls
-                        interactionMode={interactionMode}
-                        runtimeMode={runtimeMode}
-                        showPlanToggle={showPlanSidebarToggle}
-                        planSidebarOpen={planSidebarOpen}
-                        onToggleInteractionMode={toggleInteractionMode}
-                        onRuntimeModeChange={handleRuntimeModeChange}
-                        onTogglePlanSidebar={togglePlanSidebar}
-                      />
-                    </>
-                  )}
-                </div>
-
-                {/* Right side: send / stop button */}
+              {showMobilePendingAnswerActions ? (
                 <div
-                  data-chat-composer-actions="right"
-                  data-chat-composer-primary-actions-compact={
-                    isComposerPrimaryActionsCompact ? "true" : "false"
-                  }
-                  className="flex shrink-0 flex-nowrap items-center justify-end gap-2"
+                  data-chat-composer-mobile-pending-actions="true"
+                  className="absolute bottom-0 right-0 flex justify-end"
                 >
-                  <ComposerFooterPrimaryActions
-                    compact={isComposerPrimaryActionsCompact}
-                    activeContextWindow={activeContextWindow}
+                  <ComposerPrimaryActions
+                    compact
                     pendingAction={pendingPrimaryAction}
-                    isRunning={phase === "running"}
-                    showPlanFollowUpPrompt={
-                      pendingUserInputs.length === 0 && showPlanFollowUpPrompt
-                    }
-                    promptHasText={prompt.trim().length > 0}
+                    isRunning={false}
+                    showPlanFollowUpPrompt={false}
+                    promptHasText={false}
                     isSendBusy={isSendBusy}
                     isConnecting={isConnecting}
-                    isPreparingWorktree={isPreparingWorktree}
-                    hasSendableContent={composerSendState.hasSendableContent}
+                    isEnvironmentUnavailable={environmentUnavailable !== null}
+                    isPreparingWorktree={false}
+                    hasSendableContent={false}
+                    preserveComposerFocusOnPointerDown
                     onPreviousPendingQuestion={onPreviousActivePendingUserInputQuestion}
                     onInterrupt={handleInterruptPrimaryAction}
                     onImplementPlanInNewThread={handleImplementPlanInNewThreadPrimaryAction}
                   />
                 </div>
-              </div>
-            )}
+              ) : null}
+            </div>
           </div>
+
+          {/* Bottom toolbar */}
+          {isComposerCollapsedMobile ? null : activePendingApproval ? (
+            <div className="flex items-center justify-end gap-2 px-2.5 pb-2.5 sm:px-3 sm:pb-3">
+              <ComposerPendingApprovalActions
+                requestId={activePendingApproval.requestId}
+                isResponding={respondingRequestIds.includes(activePendingApproval.requestId)}
+                onRespondToApproval={onRespondToApproval}
+              />
+            </div>
+          ) : (
+            <div
+              data-chat-composer-footer="true"
+              data-chat-composer-footer-compact={isComposerFooterCompact ? "true" : "false"}
+              className={cn(
+                "flex min-w-0 flex-nowrap items-center justify-between gap-2 overflow-visible px-2.5 pb-2.5 sm:px-3 sm:pb-3",
+                isComposerFooterCompact ? "gap-1.5" : "gap-2 sm:gap-0",
+                showMobilePendingAnswerActions && "hidden sm:flex",
+              )}
+            >
+              <div className="-m-1 flex min-w-0 flex-1 items-center gap-1 overflow-x-auto p-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden">
+                <ProviderModelPicker
+                  compact={isComposerFooterCompact}
+                  activeInstanceId={selectedInstanceId}
+                  model={selectedModelForPickerWithCustomFallback}
+                  lockedProvider={lockedProvider}
+                  lockedContinuationGroupKey={lockedContinuationGroupKey}
+                  instanceEntries={providerInstanceEntries}
+                  keybindings={keybindings}
+                  modelOptionsByInstance={modelOptionsByInstance}
+                  terminalOpen={terminalOpen}
+                  open={isComposerModelPickerOpen}
+                  {...(composerProviderState.modelPickerIconClassName
+                    ? {
+                        activeProviderIconClassName: composerProviderState.modelPickerIconClassName,
+                      }
+                    : {})}
+                  onOpenChange={(open) => {
+                    setIsComposerModelPickerOpen(open);
+                  }}
+                  onInstanceModelChange={onProviderModelSelect}
+                />
+
+                {isComposerFooterCompact ? (
+                  <CompactComposerControlsMenu
+                    activePlan={showPlanSidebarToggle}
+                    interactionMode={interactionMode}
+                    planSidebarLabel={planSidebarLabel}
+                    planSidebarOpen={planSidebarOpen}
+                    runtimeMode={runtimeMode}
+                    showInteractionModeToggle={composerProviderControls.showInteractionModeToggle}
+                    traitsMenuContent={providerTraitsMenuContent}
+                    onToggleInteractionMode={toggleInteractionMode}
+                    onTogglePlanSidebar={togglePlanSidebar}
+                    onRuntimeModeChange={handleRuntimeModeChange}
+                  />
+                ) : (
+                  <>
+                    {providerTraitsPicker ? (
+                      <>
+                        <Separator orientation="vertical" className="mx-0.5 hidden h-4 sm:block" />
+                        {providerTraitsPicker}
+                      </>
+                    ) : null}
+                    <ComposerFooterModeControls
+                      showInteractionModeToggle={composerProviderControls.showInteractionModeToggle}
+                      interactionMode={interactionMode}
+                      runtimeMode={runtimeMode}
+                      showPlanToggle={showPlanSidebarToggle}
+                      planSidebarLabel={planSidebarLabel}
+                      planSidebarOpen={planSidebarOpen}
+                      onToggleInteractionMode={toggleInteractionMode}
+                      onRuntimeModeChange={handleRuntimeModeChange}
+                      onTogglePlanSidebar={togglePlanSidebar}
+                    />
+                  </>
+                )}
+              </div>
+
+              {/* Right side: send / stop button */}
+              <div
+                data-chat-composer-actions="right"
+                data-chat-composer-primary-actions-compact={
+                  isComposerPrimaryActionsCompact ? "true" : "false"
+                }
+                className="flex shrink-0 flex-nowrap items-center justify-end gap-2"
+              >
+                <ComposerFooterPrimaryActions
+                  compact={isComposerPrimaryActionsCompact}
+                  activeContextWindow={activeContextWindow}
+                  pendingAction={pendingPrimaryAction}
+                  isRunning={phase === "running"}
+                  showPlanFollowUpPrompt={pendingUserInputs.length === 0 && showPlanFollowUpPrompt}
+                  promptHasText={prompt.trim().length > 0}
+                  isSendBusy={isSendBusy}
+                  isConnecting={isConnecting}
+                  isEnvironmentUnavailable={environmentUnavailable !== null}
+                  isPreparingWorktree={isPreparingWorktree}
+                  hasSendableContent={composerSendState.hasSendableContent}
+                  preserveComposerFocusOnPointerDown={isMobileViewport}
+                  onPreviousPendingQuestion={onPreviousActivePendingUserInputQuestion}
+                  onInterrupt={handleInterruptPrimaryAction}
+                  onImplementPlanInNewThread={handleImplementPlanInNewThreadPrimaryAction}
+                />
+              </div>
+            </div>
+          )}
         </div>
-      </form>
-    );
-  }),
-);
+      </div>
+    </form>
+  );
+});
diff --git a/apps/web/src/components/chat/ChatHeader.test.ts b/apps/web/src/components/chat/ChatHeader.test.ts
new file mode 100644
index 00000000000..1b7b219bdb4
--- /dev/null
+++ b/apps/web/src/components/chat/ChatHeader.test.ts
@@ -0,0 +1,48 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+
+import { shouldShowOpenInPicker } from "./ChatHeader";
+
+describe("shouldShowOpenInPicker", () => {
+  const primaryEnvironmentId = EnvironmentId.make("environment-primary");
+
+  it("shows the picker for projects in the primary environment", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: "codething-mvp",
+        activeThreadEnvironmentId: primaryEnvironmentId,
+        primaryEnvironmentId,
+      }),
+    ).toBe(true);
+  });
+
+  it("hides the picker when hosted static mode has no primary environment", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: "codething-mvp",
+        activeThreadEnvironmentId: EnvironmentId.make("environment-remote"),
+        primaryEnvironmentId: null,
+      }),
+    ).toBe(false);
+  });
+
+  it("hides the picker for remote environments", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: "codething-mvp",
+        activeThreadEnvironmentId: EnvironmentId.make("environment-remote"),
+        primaryEnvironmentId,
+      }),
+    ).toBe(false);
+  });
+
+  it("hides the picker when there is no active project", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: undefined,
+        activeThreadEnvironmentId: primaryEnvironmentId,
+        primaryEnvironmentId,
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/apps/web/src/components/chat/ChatHeader.tsx b/apps/web/src/components/chat/ChatHeader.tsx
index cda0bb1367f..3cd4576ab88 100644
--- a/apps/web/src/components/chat/ChatHeader.tsx
+++ b/apps/web/src/components/chat/ChatHeader.tsx
@@ -16,6 +16,7 @@ import ProjectScriptsControl, { type NewProjectScriptInput } from "../ProjectScr
 import { Toggle } from "../ui/toggle";
 import { SidebarTrigger } from "../ui/sidebar";
 import { OpenInPicker } from "./OpenInPicker";
+import { usePrimaryEnvironmentId } from "../../environments/primary";
 
 interface ChatHeaderProps {
   activeThreadEnvironmentId: EnvironmentId;
@@ -43,6 +44,18 @@ interface ChatHeaderProps {
   onToggleDiff: () => void;
 }
 
+export function shouldShowOpenInPicker(input: {
+  readonly activeProjectName: string | undefined;
+  readonly activeThreadEnvironmentId: EnvironmentId;
+  readonly primaryEnvironmentId: EnvironmentId | null;
+}): boolean {
+  return (
+    Boolean(input.activeProjectName) &&
+    input.primaryEnvironmentId !== null &&
+    input.activeThreadEnvironmentId === input.primaryEnvironmentId
+  );
+}
+
 export const ChatHeader = memo(function ChatHeader({
   activeThreadEnvironmentId,
   activeThreadId,
@@ -68,6 +81,13 @@ export const ChatHeader = memo(function ChatHeader({
   onToggleTerminal,
   onToggleDiff,
 }: ChatHeaderProps) {
+  const primaryEnvironmentId = usePrimaryEnvironmentId();
+  const showOpenInPicker = shouldShowOpenInPicker({
+    activeProjectName,
+    activeThreadEnvironmentId,
+    primaryEnvironmentId,
+  });
+
   return (
     <div className="@container/header-actions flex min-w-0 flex-1 items-center gap-2">
       <div className="flex min-w-0 flex-1 items-center gap-2 overflow-hidden sm:gap-3">
@@ -101,7 +121,7 @@ export const ChatHeader = memo(function ChatHeader({
             onDeleteScript={onDeleteProjectScript}
           />
         )}
-        {activeProjectName && (
+        {showOpenInPicker && (
           <OpenInPicker
             keybindings={keybindings}
             availableEditors={availableEditors}
@@ -149,14 +169,14 @@ export const ChatHeader = memo(function ChatHeader({
                 aria-label="Toggle diff panel"
                 variant="outline"
                 size="xs"
-                disabled={!isGitRepo}
+                disabled={!isGitRepo && !diffOpen}
               >
                 <DiffIcon className="size-3" />
               </Toggle>
             }
           />
           <TooltipPopup side="bottom">
-            {!isGitRepo
+            {!isGitRepo && !diffOpen
               ? "Diff panel is unavailable because this project is not a git repository."
               : diffToggleShortcutLabel
                 ? `Toggle diff panel (${diffToggleShortcutLabel})`
diff --git a/apps/web/src/components/chat/CompactComposerControlsMenu.browser.tsx b/apps/web/src/components/chat/CompactComposerControlsMenu.browser.tsx
index b596444ef34..49eb5fbb94b 100644
--- a/apps/web/src/components/chat/CompactComposerControlsMenu.browser.tsx
+++ b/apps/web/src/components/chat/CompactComposerControlsMenu.browser.tsx
@@ -1,7 +1,10 @@
 import {
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
   EnvironmentId,
   ModelSelection,
+  ProviderInstanceId,
+  ProviderDriverKind,
   ThreadId,
 } from "@t3tools/contracts";
 import { scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
@@ -10,6 +13,7 @@ import "../../index.css";
 import { page } from "vitest/browser";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { render } from "vitest-browser-react";
+import { createModelCapabilities, createModelSelection } from "@t3tools/shared/model";
 
 import { CompactComposerControlsMenu } from "./CompactComposerControlsMenu";
 import { TraitsMenuContent } from "./TraitsPicker";
@@ -17,12 +21,42 @@ import { useComposerDraftStore } from "../../composerDraftStore";
 
 const LOCAL_ENVIRONMENT_ID = EnvironmentId.make("environment-local");
 
+function selectDescriptor(
+  id: string,
+  label: string,
+  options: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>,
+  promptInjectedValues?: ReadonlyArray<string>,
+) {
+  return {
+    id,
+    label,
+    type: "select" as const,
+    options: [...options],
+    ...(options.find((option) => option.isDefault)?.id
+      ? { currentValue: options.find((option) => option.isDefault)?.id }
+      : {}),
+    ...(promptInjectedValues && promptInjectedValues.length > 0
+      ? { promptInjectedValues: [...promptInjectedValues] }
+      : {}),
+  };
+}
+
+function booleanDescriptor(id: string, label: string) {
+  return {
+    id,
+    label,
+    type: "boolean" as const,
+  };
+}
+
 async function mountMenu(props?: { modelSelection?: ModelSelection; prompt?: string }) {
   const threadId = ThreadId.make("thread-compact-menu");
   const threadRef = scopeThreadRef(LOCAL_ENVIRONMENT_ID, threadId);
   const threadKey = scopedThreadKey(threadRef);
-  const provider = props?.modelSelection?.provider ?? "claudeAgent";
-  const model = props?.modelSelection?.model ?? DEFAULT_MODEL_BY_PROVIDER[provider];
+  const provider = ProviderDriverKind.make("claudeAgent");
+  const instanceId = ProviderInstanceId.make(props?.modelSelection?.instanceId ?? provider);
+  const model =
+    props?.modelSelection?.model ?? DEFAULT_MODEL_BY_PROVIDER[provider] ?? DEFAULT_MODEL;
 
   useComposerDraftStore.setState({
     draftsByThreadKey: {
@@ -33,13 +67,9 @@ async function mountMenu(props?: { modelSelection?: ModelSelection; prompt?: str
         persistedAttachments: [],
         terminalContexts: [],
         modelSelectionByProvider: {
-          [provider]: {
-            provider,
-            model,
-            ...(props?.modelSelection?.options ? { options: props.modelSelection.options } : {}),
-          },
+          [instanceId]: createModelSelection(instanceId, model, props?.modelSelection?.options),
         },
-        activeProvider: provider,
+        activeProvider: instanceId,
         runtimeMode: null,
         interactionMode: null,
       },
@@ -51,80 +81,66 @@ async function mountMenu(props?: { modelSelection?: ModelSelection; prompt?: str
   document.body.append(host);
   const onPromptChange = vi.fn();
   const providerOptions = props?.modelSelection?.options;
-  const models =
-    provider === "claudeAgent"
-      ? [
-          {
-            slug: "claude-opus-4-6",
-            name: "Claude Opus 4.6",
-            isCustom: false,
-            capabilities: {
-              reasoningEffortLevels: [
-                { value: "low", label: "Low" },
-                { value: "medium", label: "Medium" },
-                { value: "high", label: "High", isDefault: true },
-                { value: "max", label: "Max" },
-                { value: "ultrathink", label: "Ultrathink" },
-              ],
-              supportsFastMode: true,
-              supportsThinkingToggle: false,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: ["ultrathink"],
-            },
-          },
-          {
-            slug: "claude-haiku-4-5",
-            name: "Claude Haiku 4.5",
-            isCustom: false,
-            capabilities: {
-              reasoningEffortLevels: [],
-              supportsFastMode: false,
-              supportsThinkingToggle: true,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: [],
-            },
-          },
-          {
-            slug: "claude-sonnet-4-6",
-            name: "Claude Sonnet 4.6",
-            isCustom: false,
-            capabilities: {
-              reasoningEffortLevels: [
-                { value: "low", label: "Low" },
-                { value: "medium", label: "Medium" },
-                { value: "high", label: "High", isDefault: true },
-                { value: "ultrathink", label: "Ultrathink" },
-              ],
-              supportsFastMode: false,
-              supportsThinkingToggle: false,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: ["ultrathink"],
-            },
-          },
-        ]
-      : [
-          {
-            slug: "gpt-5.4",
-            name: "GPT-5.4",
-            isCustom: false,
-            capabilities: {
-              reasoningEffortLevels: [
-                { value: "xhigh", label: "Extra High" },
-                { value: "high", label: "High", isDefault: true },
-              ],
-              supportsFastMode: true,
-              supportsThinkingToggle: false,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: [],
-            },
-          },
-        ];
+  const models = [
+    {
+      slug: "claude-opus-4-6",
+      name: "Claude Opus 4.6",
+      isCustom: false,
+      capabilities: createModelCapabilities({
+        optionDescriptors: [
+          selectDescriptor(
+            "effort",
+            "Reasoning",
+            [
+              { id: "low", label: "Low" },
+              { id: "medium", label: "Medium" },
+              { id: "high", label: "High", isDefault: true },
+              { id: "max", label: "Max" },
+              { id: "ultrathink", label: "Ultrathink" },
+            ],
+            ["ultrathink"],
+          ),
+          booleanDescriptor("fastMode", "Fast Mode"),
+        ],
+      }),
+    },
+    {
+      slug: "claude-haiku-4-5",
+      name: "Claude Haiku 4.5",
+      isCustom: false,
+      capabilities: createModelCapabilities({
+        optionDescriptors: [booleanDescriptor("thinking", "Thinking")],
+      }),
+    },
+    {
+      slug: "claude-sonnet-4-6",
+      name: "Claude Sonnet 4.6",
+      isCustom: false,
+      capabilities: createModelCapabilities({
+        optionDescriptors: [
+          selectDescriptor(
+            "effort",
+            "Reasoning",
+            [
+              { id: "low", label: "Low" },
+              { id: "medium", label: "Medium" },
+              { id: "high", label: "High", isDefault: true },
+              { id: "ultrathink", label: "Ultrathink" },
+            ],
+            ["ultrathink"],
+          ),
+        ],
+      }),
+    },
+  ];
   const screen = await render(
     <CompactComposerControlsMenu
       activePlan={false}
       interactionMode="default"
+      planSidebarLabel="Plan"
       planSidebarOpen={false}
       runtimeMode="approval-required"
+      showInteractionModeToggle
       traitsMenuContent={
         <TraitsMenuContent
           provider={provider}
@@ -167,7 +183,10 @@ describe("CompactComposerControlsMenu", () => {
 
   it("shows fast mode controls for Opus", async () => {
     await using _ = await mountMenu({
-      modelSelection: { provider: "claudeAgent", model: "claude-opus-4-6" },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-opus-4-6",
+      ),
     });
 
     await page.getByLabelText("More composer controls").click();
@@ -175,14 +194,17 @@ describe("CompactComposerControlsMenu", () => {
     await vi.waitFor(() => {
       const text = document.body.textContent ?? "";
       expect(text).toContain("Fast Mode");
-      expect(text).toContain("off");
-      expect(text).toContain("on");
+      expect(text).toContain("On");
+      expect(text).toContain("Off");
     });
   });
 
   it("hides fast mode controls for non-Opus Claude models", async () => {
     await using _ = await mountMenu({
-      modelSelection: { provider: "claudeAgent", model: "claude-sonnet-4-6" },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-sonnet-4-6",
+      ),
     });
 
     await page.getByLabelText("More composer controls").click();
@@ -194,7 +216,10 @@ describe("CompactComposerControlsMenu", () => {
 
   it("shows only the provided effort options", async () => {
     await using _ = await mountMenu({
-      modelSelection: { provider: "claudeAgent", model: "claude-sonnet-4-6" },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-sonnet-4-6",
+      ),
     });
 
     await page.getByLabelText("More composer controls").click();
@@ -211,11 +236,11 @@ describe("CompactComposerControlsMenu", () => {
 
   it("shows a Claude thinking on/off section for Haiku", async () => {
     await using _ = await mountMenu({
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-haiku-4-5",
-        options: { thinking: true },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-haiku-4-5",
+        [{ id: "thinking", value: true }],
+      ),
     });
 
     await page.getByLabelText("More composer controls").click();
@@ -223,18 +248,18 @@ describe("CompactComposerControlsMenu", () => {
     await vi.waitFor(() => {
       const text = document.body.textContent ?? "";
       expect(text).toContain("Thinking");
-      expect(text).toContain("On (default)");
+      expect(text).toContain("On");
       expect(text).toContain("Off");
     });
   });
 
   it("shows prompt-controlled Ultrathink state with selectable effort controls", async () => {
     await using _ = await mountMenu({
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-opus-4-6",
-        options: { effort: "high" },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-opus-4-6",
+        [{ id: "effort", value: "high" }],
+      ),
       prompt: "Ultrathink:\nInvestigate this",
     });
 
@@ -242,18 +267,18 @@ describe("CompactComposerControlsMenu", () => {
 
     await vi.waitFor(() => {
       const text = document.body.textContent ?? "";
-      expect(text).toContain("Effort");
+      expect(text).toContain("Reasoning");
       expect(text).not.toContain("ultrathink");
     });
   });
 
   it("warns when ultrathink appears in prompt body text", async () => {
     await using _ = await mountMenu({
-      modelSelection: {
-        provider: "claudeAgent",
-        model: "claude-opus-4-6",
-        options: { effort: "high" },
-      },
+      modelSelection: createModelSelection(
+        ProviderInstanceId.make("claudeAgent"),
+        "claude-opus-4-6",
+        [{ id: "effort", value: "high" }],
+      ),
       prompt: "Ultrathink:\nplease ultrathink about this problem",
     });
 
@@ -262,8 +287,42 @@ describe("CompactComposerControlsMenu", () => {
     await vi.waitFor(() => {
       const text = document.body.textContent ?? "";
       expect(text).toContain(
-        'Your prompt contains "ultrathink" in the text. Remove it to change effort.',
+        'Your prompt contains "ultrathink" in the text. Remove it to change this option.',
       );
     });
   });
+
+  it("can hide the interaction mode section", async () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const screen = await render(
+      <CompactComposerControlsMenu
+        activePlan={false}
+        interactionMode="default"
+        planSidebarLabel="Plan"
+        planSidebarOpen={false}
+        runtimeMode="approval-required"
+        showInteractionModeToggle={false}
+        onToggleInteractionMode={vi.fn()}
+        onTogglePlanSidebar={vi.fn()}
+        onRuntimeModeChange={vi.fn()}
+      />,
+      { container: host },
+    );
+
+    await page.getByLabelText("More composer controls").click();
+
+    await vi.waitFor(() => {
+      const text = document.body.textContent ?? "";
+      expect(text).not.toContain("Mode");
+      expect(text).not.toContain("Chat");
+      expect(text).not.toContain("Plan");
+      expect(text).toContain("Access");
+      expect(text).toContain("Supervised");
+      expect(text).toContain("Full access");
+    });
+
+    await screen.unmount();
+    host.remove();
+  });
 });
diff --git a/apps/web/src/components/chat/CompactComposerControlsMenu.tsx b/apps/web/src/components/chat/CompactComposerControlsMenu.tsx
index 84e0953440c..f1fbd193a63 100644
--- a/apps/web/src/components/chat/CompactComposerControlsMenu.tsx
+++ b/apps/web/src/components/chat/CompactComposerControlsMenu.tsx
@@ -15,8 +15,10 @@ import {
 export const CompactComposerControlsMenu = memo(function CompactComposerControlsMenu(props: {
   activePlan: boolean;
   interactionMode: ProviderInteractionMode;
+  planSidebarLabel: string;
   planSidebarOpen: boolean;
   runtimeMode: RuntimeMode;
+  showInteractionModeToggle: boolean;
   traitsMenuContent?: ReactNode;
   onToggleInteractionMode: () => void;
   onTogglePlanSidebar: () => void;
@@ -43,18 +45,22 @@ export const CompactComposerControlsMenu = memo(function CompactComposerControls
             <MenuDivider />
           </>
         ) : null}
-        <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Mode</div>
-        <MenuRadioGroup
-          value={props.interactionMode}
-          onValueChange={(value) => {
-            if (!value || value === props.interactionMode) return;
-            props.onToggleInteractionMode();
-          }}
-        >
-          <MenuRadioItem value="default">Chat</MenuRadioItem>
-          <MenuRadioItem value="plan">Plan</MenuRadioItem>
-        </MenuRadioGroup>
-        <MenuDivider />
+        {props.showInteractionModeToggle ? (
+          <>
+            <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Mode</div>
+            <MenuRadioGroup
+              value={props.interactionMode}
+              onValueChange={(value) => {
+                if (!value || value === props.interactionMode) return;
+                props.onToggleInteractionMode();
+              }}
+            >
+              <MenuRadioItem value="default">Chat</MenuRadioItem>
+              <MenuRadioItem value="plan">Plan</MenuRadioItem>
+            </MenuRadioGroup>
+            <MenuDivider />
+          </>
+        ) : null}
         <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Access</div>
         <MenuRadioGroup
           value={props.runtimeMode}
@@ -72,7 +78,9 @@ export const CompactComposerControlsMenu = memo(function CompactComposerControls
             <MenuDivider />
             <MenuItem onClick={props.onTogglePlanSidebar}>
               <ListTodoIcon className="size-4 shrink-0" />
-              {props.planSidebarOpen ? "Hide plan sidebar" : "Show plan sidebar"}
+              {props.planSidebarOpen
+                ? `Hide ${props.planSidebarLabel.toLowerCase()} sidebar`
+                : `Show ${props.planSidebarLabel.toLowerCase()} sidebar`}
             </MenuItem>
           </>
         ) : null}
diff --git a/apps/web/src/components/chat/ComposerBannerStack.tsx b/apps/web/src/components/chat/ComposerBannerStack.tsx
new file mode 100644
index 00000000000..9901237fdf0
--- /dev/null
+++ b/apps/web/src/components/chat/ComposerBannerStack.tsx
@@ -0,0 +1,195 @@
+import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { XIcon } from "lucide-react";
+
+import { cn } from "~/lib/utils";
+import { Alert, AlertAction, AlertDescription, AlertTitle } from "../ui/alert";
+import { Button } from "../ui/button";
+
+const DISMISS_TRANSITION_MS = 220;
+const frontExitStyle = {
+  opacity: 0,
+  transform: "translate3d(0, 4rem, 0)",
+} satisfies CSSProperties;
+const stackedExitStyle = {
+  opacity: 0,
+  transform: "translate3d(0, 7rem, 0)",
+} satisfies CSSProperties;
+const restingStyle = {
+  opacity: 1,
+  transform: "translate3d(0, 0, 0)",
+} satisfies CSSProperties;
+const exitTransitionStyle = {
+  transition: `transform ${DISMISS_TRANSITION_MS}ms ease-in, opacity ${DISMISS_TRANSITION_MS}ms ease-in`,
+  willChange: "transform, opacity",
+} satisfies CSSProperties;
+
+export interface ComposerBannerStackItem {
+  readonly id: string;
+  readonly variant: "error" | "info" | "success" | "warning";
+  readonly icon: ReactNode;
+  readonly title: ReactNode;
+  readonly description?: ReactNode;
+  readonly actions?: ReactNode;
+  readonly dismissLabel?: string;
+  readonly onDismiss?: () => void;
+}
+
+interface ComposerBannerStackProps {
+  readonly className?: string;
+  readonly items: ReadonlyArray<ComposerBannerStackItem>;
+}
+
+export function ComposerBannerStack({ className, items }: ComposerBannerStackProps) {
+  const [exitingItemId, setExitingItemId] = useState<string | null>(null);
+  const dismissTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (exitingItemId && !items.some((item) => item.id === exitingItemId)) {
+      setExitingItemId(null);
+    }
+  }, [exitingItemId, items]);
+
+  useEffect(() => {
+    return () => {
+      if (dismissTimeoutRef.current) {
+        clearTimeout(dismissTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  if (items.length === 0) {
+    return null;
+  }
+
+  const frontItem = items[0];
+  if (!frontItem) {
+    return null;
+  }
+  const stackedItems = items.slice(1);
+  const hasStack = stackedItems.length > 0;
+  const showCollapsedStackCap = hasStack && exitingItemId !== frontItem.id;
+
+  const requestDismiss = (item: ComposerBannerStackItem) => {
+    if (!item.onDismiss || exitingItemId) {
+      return;
+    }
+    setExitingItemId(item.id);
+    if (dismissTimeoutRef.current) {
+      clearTimeout(dismissTimeoutRef.current);
+    }
+    dismissTimeoutRef.current = setTimeout(() => {
+      dismissTimeoutRef.current = null;
+      item.onDismiss?.();
+    }, DISMISS_TRANSITION_MS);
+  };
+
+  return (
+    <div className={cn("group/banner-stack mx-auto mb-2 max-w-208", className)}>
+      <div
+        className={cn(
+          "relative",
+          hasStack ? "group-hover/banner-stack:z-50 group-focus-within/banner-stack:z-50" : null,
+        )}
+      >
+        {showCollapsedStackCap ? (
+          <div
+            className={cn(
+              "pointer-events-none absolute inset-x-0 -top-3 z-0 mx-auto h-3 rounded-t-xl",
+              "border border-b-0 border-warning/24 bg-background/96 shadow-[0_6px_18px_rgba(0,0,0,0.06)]",
+              "transition-opacity duration-150 ease-out",
+              "group-hover/banner-stack:opacity-0 group-focus-within/banner-stack:opacity-0",
+            )}
+            style={{ width: "96%" }}
+            aria-hidden="true"
+          />
+        ) : null}
+        <div
+          className={cn(
+            "relative z-10",
+            exitingItemId === frontItem.id ? "pointer-events-none" : null,
+          )}
+          style={{
+            ...exitTransitionStyle,
+            ...(exitingItemId === frontItem.id ? frontExitStyle : restingStyle),
+          }}
+        >
+          <ComposerBannerStackAlert
+            item={frontItem}
+            exiting={exitingItemId === frontItem.id}
+            onDismissRequest={() => requestDismiss(frontItem)}
+          />
+        </div>
+        {hasStack ? (
+          <div
+            className={cn(
+              "pointer-events-none absolute inset-x-0 bottom-[calc(100%+0.5rem)] z-20 space-y-2 opacity-0",
+              "transition-[opacity,transform] duration-150 ease-out",
+              "translate-y-1 transform-gpu will-change-[opacity,transform]",
+              "group-hover/banner-stack:pointer-events-auto group-hover/banner-stack:translate-y-0 group-hover/banner-stack:opacity-100",
+              "group-focus-within/banner-stack:pointer-events-auto group-focus-within/banner-stack:translate-y-0 group-focus-within/banner-stack:opacity-100",
+            )}
+          >
+            {stackedItems.map((item) => (
+              <div
+                key={item.id}
+                className={cn(exitingItemId === item.id ? "pointer-events-none" : null)}
+                style={{
+                  ...exitTransitionStyle,
+                  ...(exitingItemId === item.id ? stackedExitStyle : restingStyle),
+                }}
+              >
+                <ComposerBannerStackAlert
+                  item={item}
+                  exiting={exitingItemId === item.id}
+                  onDismissRequest={() => requestDismiss(item)}
+                />
+              </div>
+            ))}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function ComposerBannerStackAlert({
+  item,
+  exiting,
+  onDismissRequest,
+}: {
+  readonly item: ComposerBannerStackItem;
+  readonly exiting: boolean;
+  readonly onDismissRequest: () => void;
+}) {
+  const dismissOnly = item.onDismiss && !item.actions;
+
+  return (
+    <Alert variant={item.variant}>
+      {item.icon}
+      <AlertTitle>{item.title}</AlertTitle>
+      {item.description ? <AlertDescription>{item.description}</AlertDescription> : null}
+      {item.actions || item.onDismiss ? (
+        <AlertAction
+          className={
+            dismissOnly
+              ? "max-sm:col-start-3 max-sm:row-start-1 max-sm:mt-0 max-sm:self-start"
+              : undefined
+          }
+        >
+          {item.actions}
+          {item.onDismiss ? (
+            <Button
+              size="icon-xs"
+              variant="ghost"
+              aria-label={item.dismissLabel ?? "Dismiss warning"}
+              disabled={exiting}
+              onClick={onDismissRequest}
+            >
+              <XIcon className="size-3.5" />
+            </Button>
+          ) : null}
+        </AlertAction>
+      ) : null}
+    </Alert>
+  );
+}
diff --git a/apps/web/src/components/chat/ComposerCommandMenu.tsx b/apps/web/src/components/chat/ComposerCommandMenu.tsx
index de7cf2b2b80..f687ec7ba23 100644
--- a/apps/web/src/components/chat/ComposerCommandMenu.tsx
+++ b/apps/web/src/components/chat/ComposerCommandMenu.tsx
@@ -1,6 +1,6 @@
 import {
   type ProjectEntry,
-  type ProviderKind,
+  type ProviderDriverKind,
   type ServerProviderSkill,
   type ServerProviderSlashCommand,
 } from "@t3tools/contracts";
@@ -10,7 +10,6 @@ import { memo, useLayoutEffect, useMemo, useRef } from "react";
 import { type ComposerSlashCommand, type ComposerTriggerKind } from "../../composer-logic";
 import { formatProviderSkillInstallSource } from "~/providerSkillPresentation";
 import { cn } from "~/lib/utils";
-import { Badge } from "../ui/badge";
 import {
   Command,
   CommandGroup,
@@ -40,23 +39,15 @@ export type ComposerCommandItem =
   | {
       id: string;
       type: "provider-slash-command";
-      provider: ProviderKind;
+      provider: ProviderDriverKind;
       command: ServerProviderSlashCommand;
       label: string;
       description: string;
     }
-  | {
-      id: string;
-      type: "model";
-      provider: ProviderKind;
-      model: string;
-      label: string;
-      description: string;
-    }
   | {
       id: string;
       type: "skill";
-      provider: ProviderKind;
+      provider: ProviderDriverKind;
       skill: ServerProviderSkill;
       label: string;
       description: string;
@@ -255,11 +246,6 @@ const ComposerCommandMenuItem = memo(function ComposerCommandMenuItem(props: {
           <SkillGlyph className="size-3.5" />
         </span>
       ) : null}
-      {props.item.type === "model" ? (
-        <Badge variant="outline" className="px-1.5 py-0 text-[10px]">
-          model
-        </Badge>
-      ) : null}
       <span className="flex min-w-0 flex-1 items-center gap-2">
         <span className="shrink-0">{props.item.label}</span>
         <span className="min-w-0 flex-1 truncate text-muted-foreground/70 text-xs">
diff --git a/apps/web/src/components/chat/ComposerPrimaryActions.tsx b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
index 2bc40fe6ae8..fbeb9de30b8 100644
--- a/apps/web/src/components/chat/ComposerPrimaryActions.tsx
+++ b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
@@ -1,4 +1,4 @@
-import { memo } from "react";
+import { memo, type PointerEventHandler } from "react";
 import { ChevronDownIcon, ChevronLeftIcon } from "lucide-react";
 import { cn } from "~/lib/utils";
 import { Button } from "../ui/button";
@@ -20,8 +20,10 @@ interface ComposerPrimaryActionsProps {
   promptHasText: boolean;
   isSendBusy: boolean;
   isConnecting: boolean;
+  isEnvironmentUnavailable: boolean;
   isPreparingWorktree: boolean;
   hasSendableContent: boolean;
+  preserveComposerFocusOnPointerDown?: boolean;
   onPreviousPendingQuestion: () => void;
   onInterrupt: () => void;
   onImplementPlanInNewThread: () => void;
@@ -45,6 +47,10 @@ export const formatPendingPrimaryActionLabel = (input: {
   return input.questionIndex > 0 ? "Submit answers" : "Submit answer";
 };
 
+const preventPointerFocus: PointerEventHandler<HTMLElement> = (event) => {
+  event.preventDefault();
+};
+
 export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
   compact,
   pendingAction,
@@ -53,12 +59,18 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
   promptHasText,
   isSendBusy,
   isConnecting,
+  isEnvironmentUnavailable,
   isPreparingWorktree,
   hasSendableContent,
+  preserveComposerFocusOnPointerDown = false,
   onPreviousPendingQuestion,
   onInterrupt,
   onImplementPlanInNewThread,
 }: ComposerPrimaryActionsProps) {
+  const pointerFocusProps = preserveComposerFocusOnPointerDown
+    ? { onPointerDown: preventPointerFocus }
+    : undefined;
+
   if (pendingAction) {
     return (
       <div className={cn("flex items-center justify-end", compact ? "gap-1.5" : "gap-2")}>
@@ -68,6 +80,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
               size="icon-sm"
               variant="outline"
               className="rounded-full"
+              {...pointerFocusProps}
               onClick={onPreviousPendingQuestion}
               disabled={pendingAction.isResponding}
               aria-label="Previous question"
@@ -79,6 +92,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
               size="sm"
               variant="outline"
               className="rounded-full"
+              {...pointerFocusProps}
               onClick={onPreviousPendingQuestion}
               disabled={pendingAction.isResponding}
             >
@@ -90,7 +104,9 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           type="submit"
           size="sm"
           className={cn("rounded-full", compact ? "px-3" : "px-4")}
+          {...pointerFocusProps}
           disabled={
+            isEnvironmentUnavailable ||
             pendingAction.isResponding ||
             (pendingAction.isLastQuestion ? !pendingAction.isComplete : !pendingAction.canAdvance)
           }
@@ -111,6 +127,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
       <button
         type="button"
         className="flex size-8 cursor-pointer items-center justify-center rounded-full bg-rose-500/90 text-white transition-all duration-150 hover:bg-rose-500 hover:scale-105 sm:h-8 sm:w-8"
+        {...pointerFocusProps}
         onClick={onInterrupt}
         aria-label="Stop generation"
       >
@@ -128,7 +145,8 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           type="submit"
           size="sm"
           className={cn("rounded-full", compact ? "h-9 px-3 sm:h-8" : "h-9 px-4 sm:h-8")}
-          disabled={isSendBusy || isConnecting}
+          {...pointerFocusProps}
+          disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
         >
           {isConnecting || isSendBusy ? "Sending..." : "Refine"}
         </Button>
@@ -141,7 +159,8 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           type="submit"
           size="sm"
           className="h-9 rounded-l-full rounded-r-none px-4 sm:h-8"
-          disabled={isSendBusy || isConnecting}
+          {...pointerFocusProps}
+          disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
         >
           {isConnecting || isSendBusy ? "Sending..." : "Implement"}
         </Button>
@@ -153,7 +172,8 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
                 variant="default"
                 className="h-9 rounded-l-none rounded-r-full border-l-white/12 px-2 sm:h-8"
                 aria-label="Implementation actions"
-                disabled={isSendBusy || isConnecting}
+                {...pointerFocusProps}
+                disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
               />
             }
           >
@@ -161,7 +181,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           </MenuTrigger>
           <MenuPopup align="end" side="top">
             <MenuItem
-              disabled={isSendBusy || isConnecting}
+              disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
               onClick={() => void onImplementPlanInNewThread()}
             >
               Implement in a new thread
@@ -176,15 +196,18 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
     <button
       type="submit"
       className="flex h-9 w-9 enabled:cursor-pointer items-center justify-center rounded-full bg-primary/90 text-primary-foreground transition-all duration-150 hover:bg-primary hover:scale-105 disabled:pointer-events-none disabled:opacity-30 disabled:hover:scale-100 sm:h-8 sm:w-8"
-      disabled={isSendBusy || isConnecting || !hasSendableContent}
+      {...pointerFocusProps}
+      disabled={isSendBusy || isConnecting || isEnvironmentUnavailable || !hasSendableContent}
       aria-label={
-        isConnecting
-          ? "Connecting"
-          : isPreparingWorktree
-            ? "Preparing worktree"
-            : isSendBusy
-              ? "Sending"
-              : "Send message"
+        isEnvironmentUnavailable
+          ? "Environment disconnected"
+          : isConnecting
+            ? "Connecting"
+            : isPreparingWorktree
+              ? "Preparing worktree"
+              : isSendBusy
+                ? "Sending"
+                : "Send message"
       }
     >
       {isConnecting || isSendBusy ? (
diff --git a/apps/web/src/components/chat/MessagesTimeline.browser.tsx b/apps/web/src/components/chat/MessagesTimeline.browser.tsx
new file mode 100644
index 00000000000..e59938b4958
--- /dev/null
+++ b/apps/web/src/components/chat/MessagesTimeline.browser.tsx
@@ -0,0 +1,264 @@
+import "../../index.css";
+
+import { EnvironmentId } from "@t3tools/contracts";
+import { createRef } from "react";
+import type { LegendListRef } from "@legendapp/list/react";
+import { page } from "vitest/browser";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { render } from "vitest-browser-react";
+
+const scrollToEndSpy = vi.fn();
+const getStateSpy = vi.fn(() => ({ isAtEnd: true }));
+
+vi.mock("@legendapp/list/react", async () => {
+  const React = await import("react");
+
+  function LegendList(props: {
+    data: Array<{ id: string }>;
+    keyExtractor: (item: { id: string }) => string;
+    renderItem: (args: { item: { id: string } }) => React.ReactNode;
+    ListHeaderComponent?: React.ReactNode;
+    ListFooterComponent?: React.ReactNode;
+    ref?: React.Ref<LegendListRef>;
+  }) {
+    React.useImperativeHandle(
+      props.ref,
+      () =>
+        ({
+          scrollToEnd: scrollToEndSpy,
+          getState: getStateSpy,
+        }) as unknown as LegendListRef,
+    );
+
+    return (
+      <div data-testid="legend-list">
+        {props.ListHeaderComponent}
+        {props.data.map((item) => (
+          <div key={props.keyExtractor(item)}>{props.renderItem({ item })}</div>
+        ))}
+        {props.ListFooterComponent}
+      </div>
+    );
+  }
+
+  return { LegendList };
+});
+
+import { MessagesTimeline } from "./MessagesTimeline";
+
+const MESSAGE_CREATED_AT = "2026-04-13T12:00:00.000Z";
+
+function buildProps() {
+  return {
+    isWorking: false,
+    activeTurnInProgress: false,
+    activeTurnId: null,
+    activeTurnStartedAt: null,
+    listRef: createRef<LegendListRef | null>(),
+    completionDividerBeforeEntryId: null,
+    completionSummary: null,
+    turnDiffSummaryByAssistantMessageId: new Map(),
+    routeThreadKey: "environment-local:thread-1",
+    onOpenTurnDiff: vi.fn(),
+    revertTurnCountByUserMessageId: new Map(),
+    onRevertUserMessage: vi.fn(),
+    isRevertingCheckpoint: false,
+    onImageExpand: vi.fn(),
+    activeThreadEnvironmentId: EnvironmentId.make("environment-local"),
+    markdownCwd: undefined,
+    resolvedTheme: "dark" as const,
+    timestampFormat: "24-hour" as const,
+    workspaceRoot: undefined,
+    onIsAtEndChange: vi.fn(),
+  };
+}
+
+function buildLongUserMessageText(tail = "deep hidden detail only after expand") {
+  return Array.from({ length: 9 }, (_, index) =>
+    index === 8 ? tail : `Line ${index + 1}: ${"verbose prompt content ".repeat(8).trim()}`,
+  ).join("\n");
+}
+
+function buildUserTimelineEntry(text: string) {
+  return {
+    id: "entry-1",
+    kind: "message" as const,
+    createdAt: MESSAGE_CREATED_AT,
+    message: {
+      id: "message-1" as never,
+      role: "user" as const,
+      text,
+      createdAt: MESSAGE_CREATED_AT,
+      streaming: false,
+    },
+  };
+}
+
+describe("MessagesTimeline", () => {
+  afterEach(() => {
+    scrollToEndSpy.mockReset();
+    getStateSpy.mockClear();
+    vi.restoreAllMocks();
+    document.body.innerHTML = "";
+  });
+
+  it("renders activity rows instead of the empty placeholder when a thread has non-message timeline data", async () => {
+    const screen = await render(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[
+          {
+            id: "work-1",
+            kind: "work",
+            createdAt: "2026-04-13T12:00:00.000Z",
+            entry: {
+              id: "work-1",
+              createdAt: "2026-04-13T12:00:00.000Z",
+              label: "thinking",
+              detail: "Inspecting repository state",
+              tone: "thinking",
+            },
+          },
+        ]}
+      />,
+    );
+
+    try {
+      await expect
+        .element(page.getByText("Send a message to start the conversation."))
+        .not.toBeInTheDocument();
+      await expect.element(page.getByText("Thinking - Inspecting repository state")).toBeVisible();
+    } finally {
+      await screen.unmount();
+    }
+  });
+
+  it("snaps to the bottom when timeline rows appear after an initially empty render", async () => {
+    const requestAnimationFrameSpy = vi
+      .spyOn(window, "requestAnimationFrame")
+      .mockImplementation((callback: FrameRequestCallback) => {
+        callback(0);
+        return 1;
+      });
+    vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => undefined);
+
+    const props = buildProps();
+    const screen = await render(<MessagesTimeline {...props} timelineEntries={[]} />);
+
+    try {
+      await expect
+        .element(page.getByText("Send a message to start the conversation."))
+        .toBeVisible();
+
+      await screen.rerender(
+        <MessagesTimeline
+          {...props}
+          timelineEntries={[
+            {
+              id: "work-1",
+              kind: "work",
+              createdAt: "2026-04-13T12:00:00.000Z",
+              entry: {
+                id: "work-1",
+                createdAt: "2026-04-13T12:00:00.000Z",
+                label: "thinking",
+                detail: "Inspecting repository state",
+                tone: "thinking",
+              },
+            },
+          ]}
+        />,
+      );
+
+      await expect.element(page.getByText("Thinking - Inspecting repository state")).toBeVisible();
+      expect(props.onIsAtEndChange).toHaveBeenCalledWith(true);
+      expect(scrollToEndSpy).toHaveBeenCalledWith({ animated: false });
+      expect(requestAnimationFrameSpy).toHaveBeenCalled();
+    } finally {
+      await screen.unmount();
+    }
+  });
+
+  it("starts long user messages collapsed by default", async () => {
+    const screen = await render(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[buildUserTimelineEntry(buildLongUserMessageText())]}
+      />,
+    );
+
+    try {
+      const toggle = page.getByRole("button", { name: "Show full message" });
+      await expect.element(toggle).toBeVisible();
+      await expect.element(toggle).toHaveAttribute("aria-expanded", "false");
+
+      const messageBody = document.querySelector(
+        "[data-user-message-body='true']",
+      ) as HTMLDivElement | null;
+      expect(messageBody?.getAttribute("data-user-message-collapsed")).toBe("true");
+      expect(messageBody?.className).toContain("max-h-44");
+      expect(messageBody?.className).toContain("overflow-hidden");
+      expect(messageBody?.getAttribute("data-user-message-fade")).toBe("true");
+      expect(messageBody?.style.maskImage).toContain("linear-gradient");
+    } finally {
+      await screen.unmount();
+    }
+  });
+
+  it("expands and re-collapses long user messages from the toggle", async () => {
+    const screen = await render(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[buildUserTimelineEntry(buildLongUserMessageText())]}
+      />,
+    );
+
+    try {
+      const expandButton = page.getByRole("button", { name: "Show full message" });
+      await expect.element(expandButton).toBeVisible();
+
+      expect(document.body.textContent ?? "").toContain("deep hidden detail only after expand");
+
+      await expandButton.click();
+
+      const collapseButton = page.getByRole("button", { name: "Show less" });
+      await expect.element(collapseButton).toBeVisible();
+      await expect.element(collapseButton).toHaveAttribute("aria-expanded", "true");
+
+      let messageBody = document.querySelector("[data-user-message-body='true']");
+      expect(messageBody?.getAttribute("data-user-message-collapsed")).toBe("false");
+      expect(messageBody?.className).not.toContain("max-h-44");
+      expect(messageBody?.getAttribute("data-user-message-fade")).toBe("false");
+      expect((messageBody as HTMLDivElement | null)?.style.maskImage ?? "").toBe("");
+
+      await collapseButton.click();
+
+      await expect.element(page.getByRole("button", { name: "Show full message" })).toBeVisible();
+      messageBody = document.querySelector("[data-user-message-body='true']");
+      expect(messageBody?.getAttribute("data-user-message-collapsed")).toBe("true");
+      expect(messageBody?.className).toContain("max-h-44");
+      expect(messageBody?.getAttribute("data-user-message-fade")).toBe("true");
+      expect((messageBody as HTMLDivElement | null)?.style.maskImage).toContain("linear-gradient");
+    } finally {
+      await screen.unmount();
+    }
+  });
+
+  it("starts the newest long user prompt collapsed", async () => {
+    const screen = await render(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[buildUserTimelineEntry(buildLongUserMessageText("latest long prompt"))]}
+      />,
+    );
+
+    try {
+      await expect.element(page.getByRole("button", { name: "Show full message" })).toBeVisible();
+
+      const messageBody = document.querySelector("[data-user-message-body='true']");
+      expect(messageBody?.getAttribute("data-user-message-collapsed")).toBe("true");
+    } finally {
+      await screen.unmount();
+    }
+  });
+});
diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
index 29105471227..2f2b8924a84 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  computeStableMessagesTimelineRows,
   computeMessageDurationStart,
   deriveMessagesTimelineRows,
   normalizeCompactToolLabel,
@@ -252,6 +253,8 @@ describe("deriveMessagesTimelineRows", () => {
       completionDividerBeforeEntryId: "assistant-final-entry",
       isWorking: false,
       activeTurnStartedAt: null,
+      turnDiffSummaryByAssistantMessageId: new Map(),
+      revertTurnCountByUserMessageId: new Map(),
     });
 
     const assistantRows = rows.filter(
@@ -264,4 +267,276 @@ describe("deriveMessagesTimelineRows", () => {
     expect(assistantRows[1]?.showAssistantCopyButton).toBe(true);
     expect(assistantRows[1]?.showCompletionDivider).toBe(true);
   });
+
+  it("marks only the active assistant turn as streaming for copy controls", () => {
+    const rows = deriveMessagesTimelineRows({
+      timelineEntries: [
+        {
+          id: "assistant-one-entry",
+          kind: "message",
+          createdAt: "2026-01-01T00:00:10Z",
+          message: {
+            id: "assistant-one" as never,
+            role: "assistant",
+            text: "Earlier response.",
+            turnId: "turn-1" as never,
+            createdAt: "2026-01-01T00:00:10Z",
+            completedAt: "2026-01-01T00:00:11Z",
+            streaming: false,
+          },
+        },
+        {
+          id: "assistant-two-entry",
+          kind: "message",
+          createdAt: "2026-01-01T00:00:20Z",
+          message: {
+            id: "assistant-two" as never,
+            role: "assistant",
+            text: "Active response.",
+            turnId: "turn-2" as never,
+            createdAt: "2026-01-01T00:00:20Z",
+            completedAt: "2026-01-01T00:00:30Z",
+            streaming: false,
+          },
+        },
+      ],
+      completionDividerBeforeEntryId: "assistant-two-entry",
+      completionSummary: "done",
+      isWorking: false,
+      activeTurnInProgress: true,
+      activeTurnId: "turn-2" as never,
+      activeTurnStartedAt: null,
+      turnDiffSummaryByAssistantMessageId: new Map(),
+      revertTurnCountByUserMessageId: new Map(),
+    });
+
+    const assistantRows = rows.filter(
+      (row): row is Extract<(typeof rows)[number], { kind: "message" }> =>
+        row.kind === "message" && row.message.role === "assistant",
+    );
+
+    expect(assistantRows[0]?.assistantCopyStreaming).toBe(false);
+    expect(assistantRows[0]?.completionSummary).toBeNull();
+    expect(assistantRows[1]?.assistantCopyStreaming).toBe(true);
+    expect(assistantRows[1]?.completionSummary).toBe("done");
+  });
+
+  it("projects assistant diff summaries and user revert counts onto the affected rows", () => {
+    const assistantTurnDiffSummary = {
+      turnId: "turn-1" as never,
+      completedAt: "2026-01-01T00:00:30Z",
+      assistantMessageId: "assistant-1" as never,
+      checkpointTurnCount: 2,
+      files: [{ path: "src/index.ts", additions: 3, deletions: 1 }],
+    };
+
+    const rows = deriveMessagesTimelineRows({
+      timelineEntries: [
+        {
+          id: "user-entry",
+          kind: "message",
+          createdAt: "2026-01-01T00:00:00Z",
+          message: {
+            id: "user-1" as never,
+            role: "user",
+            text: "Do the thing",
+            turnId: null,
+            createdAt: "2026-01-01T00:00:00Z",
+            streaming: false,
+          },
+        },
+        {
+          id: "assistant-entry",
+          kind: "message",
+          createdAt: "2026-01-01T00:00:20Z",
+          message: {
+            id: "assistant-1" as never,
+            role: "assistant",
+            text: "Done",
+            turnId: "turn-1" as never,
+            createdAt: "2026-01-01T00:00:20Z",
+            completedAt: "2026-01-01T00:00:30Z",
+            streaming: false,
+          },
+        },
+      ],
+      completionDividerBeforeEntryId: null,
+      isWorking: false,
+      activeTurnStartedAt: null,
+      turnDiffSummaryByAssistantMessageId: new Map([
+        ["assistant-1" as never, assistantTurnDiffSummary],
+      ]),
+      revertTurnCountByUserMessageId: new Map([["user-1" as never, 1]]),
+    });
+
+    const userRow = rows.find(
+      (row): row is Extract<(typeof rows)[number], { kind: "message" }> =>
+        row.kind === "message" && row.message.role === "user",
+    );
+    const assistantRow = rows.find(
+      (row): row is Extract<(typeof rows)[number], { kind: "message" }> =>
+        row.kind === "message" && row.message.role === "assistant",
+    );
+
+    expect(userRow?.revertTurnCount).toBe(1);
+    expect(assistantRow?.assistantTurnDiffSummary).toBe(assistantTurnDiffSummary);
+  });
+});
+
+describe("computeStableMessagesTimelineRows", () => {
+  it("returns the previous result when row order and content are unchanged", () => {
+    const firstUserMessage = {
+      id: "user-1" as never,
+      role: "user" as const,
+      text: "First",
+      turnId: null,
+      createdAt: "2026-01-01T00:00:00Z",
+      streaming: false,
+    };
+    const secondUserMessage = {
+      id: "user-2" as never,
+      role: "user" as const,
+      text: "Second",
+      turnId: null,
+      createdAt: "2026-01-01T00:00:10Z",
+      streaming: false,
+    };
+
+    const rows = deriveMessagesTimelineRows({
+      timelineEntries: [
+        {
+          id: "entry-user-1",
+          kind: "message",
+          createdAt: firstUserMessage.createdAt,
+          message: firstUserMessage,
+        },
+        {
+          id: "entry-user-2",
+          kind: "message",
+          createdAt: secondUserMessage.createdAt,
+          message: secondUserMessage,
+        },
+      ],
+      completionDividerBeforeEntryId: null,
+      isWorking: false,
+      activeTurnStartedAt: null,
+      turnDiffSummaryByAssistantMessageId: new Map(),
+      revertTurnCountByUserMessageId: new Map(),
+    });
+
+    const initial = computeStableMessagesTimelineRows(rows, {
+      byId: new Map(),
+      result: [],
+    });
+
+    const repeated = computeStableMessagesTimelineRows(rows, initial);
+
+    expect(repeated).toBe(initial);
+    expect(repeated.result).toBe(initial.result);
+  });
+
+  it("reuses work rows when equivalent timeline derivations create new grouped arrays", () => {
+    const firstWorkEntry = {
+      id: "work-1",
+      createdAt: "2026-01-01T00:00:00Z",
+      label: "thinking",
+      detail: "Inspecting repository state",
+      tone: "thinking" as const,
+    };
+    const secondWorkEntry = {
+      id: "work-2",
+      createdAt: "2026-01-01T00:00:01Z",
+      label: "read",
+      detail: "Reading package.json",
+      tone: "tool" as const,
+    };
+
+    const createRows = () =>
+      deriveMessagesTimelineRows({
+        timelineEntries: [
+          {
+            id: "entry-work-1",
+            kind: "work",
+            createdAt: firstWorkEntry.createdAt,
+            entry: firstWorkEntry,
+          },
+          {
+            id: "entry-work-2",
+            kind: "work",
+            createdAt: secondWorkEntry.createdAt,
+            entry: secondWorkEntry,
+          },
+        ],
+        completionDividerBeforeEntryId: null,
+        isWorking: false,
+        activeTurnStartedAt: null,
+        turnDiffSummaryByAssistantMessageId: new Map(),
+        revertTurnCountByUserMessageId: new Map(),
+      });
+
+    const firstRows = createRows();
+    const initial = computeStableMessagesTimelineRows(firstRows, {
+      byId: new Map(),
+      result: [],
+    });
+    const secondRows = createRows();
+
+    expect(secondRows[0]).not.toBe(firstRows[0]);
+
+    const repeated = computeStableMessagesTimelineRows(secondRows, initial);
+
+    expect(repeated).toBe(initial);
+    expect(repeated.result[0]).toBe(initial.result[0]);
+  });
+
+  it("returns a new result when row order changes without content changes", () => {
+    const firstUserMessage = {
+      id: "user-1" as never,
+      role: "user" as const,
+      text: "First",
+      turnId: null,
+      createdAt: "2026-01-01T00:00:00Z",
+      streaming: false,
+    };
+    const secondUserMessage = {
+      id: "user-2" as never,
+      role: "user" as const,
+      text: "Second",
+      turnId: null,
+      createdAt: "2026-01-01T00:00:10Z",
+      streaming: false,
+    };
+
+    const firstRows = deriveMessagesTimelineRows({
+      timelineEntries: [
+        {
+          id: "entry-user-1",
+          kind: "message",
+          createdAt: firstUserMessage.createdAt,
+          message: firstUserMessage,
+        },
+        {
+          id: "entry-user-2",
+          kind: "message",
+          createdAt: secondUserMessage.createdAt,
+          message: secondUserMessage,
+        },
+      ],
+      completionDividerBeforeEntryId: null,
+      isWorking: false,
+      activeTurnStartedAt: null,
+      turnDiffSummaryByAssistantMessageId: new Map(),
+      revertTurnCountByUserMessageId: new Map(),
+    });
+
+    const initial = computeStableMessagesTimelineRows(firstRows, {
+      byId: new Map(),
+      result: [],
+    });
+
+    const reordered = computeStableMessagesTimelineRows([firstRows[1]!, firstRows[0]!], initial);
+
+    expect(reordered).not.toBe(initial);
+    expect(reordered.result).toEqual([initial.result[1], initial.result[0]]);
+  });
 });
diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.ts b/apps/web/src/components/chat/MessagesTimeline.logic.ts
index 25debf5066f..ad54dd8bdeb 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.ts
@@ -1,8 +1,7 @@
-import { type MessageId } from "@t3tools/contracts";
+import * as Equal from "effect/Equal";
 import { type TimelineEntry, type WorkLogEntry } from "../../session-logic";
-import { buildTurnDiffTree, type TurnDiffTreeNode } from "../../lib/turnDiffTree";
 import { type ChatMessage, type ProposedPlan, type TurnDiffSummary } from "../../types";
-import { estimateTimelineMessageHeight } from "../timelineHeight";
+import { type MessageId, type TurnId } from "@t3tools/contracts";
 
 export const MAX_VISIBLE_WORK_LOG_ENTRIES = 6;
 
@@ -27,7 +26,11 @@ export type MessagesTimelineRow =
       message: ChatMessage;
       durationStart: string;
       showCompletionDivider: boolean;
+      completionSummary: string | null;
       showAssistantCopyButton: boolean;
+      assistantCopyStreaming: boolean;
+      assistantTurnDiffSummary?: TurnDiffSummary | undefined;
+      revertTurnCount?: number | undefined;
     }
   | {
       kind: "proposed-plan";
@@ -37,6 +40,11 @@ export type MessagesTimelineRow =
     }
   | { kind: "working"; id: string; createdAt: string | null };
 
+export interface StableMessagesTimelineRowsState {
+  byId: Map<string, MessagesTimelineRow>;
+  result: MessagesTimelineRow[];
+}
+
 export function computeMessageDurationStart(
   messages: ReadonlyArray<TimelineDurationMessage>,
 ): Map<string, string> {
@@ -105,8 +113,13 @@ function deriveTerminalAssistantMessageIds(timelineEntries: ReadonlyArray<Timeli
 export function deriveMessagesTimelineRows(input: {
   timelineEntries: ReadonlyArray<TimelineEntry>;
   completionDividerBeforeEntryId: string | null;
+  completionSummary?: string | null;
   isWorking: boolean;
+  activeTurnInProgress?: boolean;
+  activeTurnId?: TurnId | null;
   activeTurnStartedAt: string | null;
+  turnDiffSummaryByAssistantMessageId: ReadonlyMap<MessageId, TurnDiffSummary>;
+  revertTurnCountByUserMessageId: ReadonlyMap<MessageId, number>;
 }): MessagesTimelineRow[] {
   const nextRows: MessagesTimelineRow[] = [];
   const durationStartByMessageId = computeMessageDurationStart(
@@ -149,6 +162,16 @@ export function deriveMessagesTimelineRows(input: {
       continue;
     }
 
+    const assistantTurnStillInProgress =
+      timelineEntry.message.role === "assistant" &&
+      input.activeTurnInProgress === true &&
+      input.activeTurnId != null &&
+      timelineEntry.message.turnId === input.activeTurnId;
+
+    const showCompletionDivider =
+      timelineEntry.message.role === "assistant" &&
+      input.completionDividerBeforeEntryId === timelineEntry.id;
+
     nextRows.push({
       kind: "message",
       id: timelineEntry.id,
@@ -156,12 +179,20 @@ export function deriveMessagesTimelineRows(input: {
       message: timelineEntry.message,
       durationStart:
         durationStartByMessageId.get(timelineEntry.message.id) ?? timelineEntry.message.createdAt,
-      showCompletionDivider:
-        timelineEntry.message.role === "assistant" &&
-        input.completionDividerBeforeEntryId === timelineEntry.id,
+      showCompletionDivider,
+      completionSummary: showCompletionDivider ? (input.completionSummary ?? null) : null,
       showAssistantCopyButton:
         timelineEntry.message.role === "assistant" &&
         terminalAssistantMessageIds.has(timelineEntry.message.id),
+      assistantCopyStreaming: timelineEntry.message.streaming || assistantTurnStillInProgress,
+      assistantTurnDiffSummary:
+        timelineEntry.message.role === "assistant"
+          ? input.turnDiffSummaryByAssistantMessageId.get(timelineEntry.message.id)
+          : undefined,
+      revertTurnCount:
+        timelineEntry.message.role === "user"
+          ? input.revertTurnCountByUserMessageId.get(timelineEntry.message.id)
+          : undefined,
     });
   }
 
@@ -176,71 +207,52 @@ export function deriveMessagesTimelineRows(input: {
   return nextRows;
 }
 
-export function estimateMessagesTimelineRowHeight(
-  row: MessagesTimelineRow,
-  input: {
-    timelineWidthPx: number | null;
-    expandedWorkGroups?: Readonly<Record<string, boolean>>;
-    turnDiffSummaryByAssistantMessageId?: ReadonlyMap<MessageId, TurnDiffSummary>;
-  },
-): number {
-  switch (row.kind) {
-    case "work":
-      return estimateWorkRowHeight(row, input);
-    case "proposed-plan":
-      return estimateTimelineProposedPlanHeight(row.proposedPlan);
-    case "working":
-      return 40;
-    case "message": {
-      let estimate = estimateTimelineMessageHeight(row.message, {
-        timelineWidthPx: input.timelineWidthPx,
-      });
-      const turnDiffSummary = input.turnDiffSummaryByAssistantMessageId?.get(row.message.id);
-      if (turnDiffSummary && turnDiffSummary.files.length > 0) {
-        estimate += estimateChangedFilesCardHeight(turnDiffSummary);
-      }
-      return estimate;
+export function computeStableMessagesTimelineRows(
+  rows: MessagesTimelineRow[],
+  previous: StableMessagesTimelineRowsState,
+): StableMessagesTimelineRowsState {
+  const next = new Map<string, MessagesTimelineRow>();
+  let anyChanged = rows.length !== previous.byId.size;
+
+  const result = rows.map((row, index) => {
+    const prevRow = previous.byId.get(row.id);
+    const nextRow = prevRow && isRowUnchanged(prevRow, row) ? prevRow : row;
+    next.set(row.id, nextRow);
+    if (!anyChanged && previous.result[index] !== nextRow) {
+      anyChanged = true;
     }
-  }
-}
+    return nextRow;
+  });
 
-function estimateWorkRowHeight(
-  row: Extract<MessagesTimelineRow, { kind: "work" }>,
-  input: {
-    expandedWorkGroups?: Readonly<Record<string, boolean>>;
-  },
-): number {
-  const isExpanded = input.expandedWorkGroups?.[row.id] ?? false;
-  const hasOverflow = row.groupedEntries.length > MAX_VISIBLE_WORK_LOG_ENTRIES;
-  const visibleEntries =
-    hasOverflow && !isExpanded ? MAX_VISIBLE_WORK_LOG_ENTRIES : row.groupedEntries.length;
-  const onlyToolEntries = row.groupedEntries.every((entry) => entry.tone === "tool");
-  const showHeader = hasOverflow || !onlyToolEntries;
-
-  // Card chrome, optional header, and one compact work-entry row per visible entry.
-  return 28 + (showHeader ? 26 : 0) + visibleEntries * 32;
+  return anyChanged ? { byId: next, result } : previous;
 }
 
-function estimateTimelineProposedPlanHeight(proposedPlan: ProposedPlan): number {
-  const estimatedLines = Math.max(1, Math.ceil(proposedPlan.planMarkdown.length / 72));
-  return 120 + Math.min(estimatedLines * 22, 880);
-}
+/** Shallow field comparison per row variant — avoids deep equality cost. */
+function isRowUnchanged(a: MessagesTimelineRow, b: MessagesTimelineRow): boolean {
+  if (a.kind !== b.kind || a.id !== b.id) return false;
+
+  switch (a.kind) {
+    case "working":
+      return a.createdAt === (b as typeof a).createdAt;
 
-function estimateChangedFilesCardHeight(turnDiffSummary: TurnDiffSummary): number {
-  const treeNodes = buildTurnDiffTree(turnDiffSummary.files);
-  const visibleNodeCount = countTurnDiffTreeNodes(treeNodes);
+    case "proposed-plan":
+      return a.proposedPlan === (b as typeof a).proposedPlan;
 
-  // Card chrome: top/bottom padding, header row, and tree spacing.
-  return 60 + visibleNodeCount * 25;
-}
+    case "work":
+      return Equal.equals(a.groupedEntries, (b as typeof a).groupedEntries);
 
-function countTurnDiffTreeNodes(nodes: ReadonlyArray<TurnDiffTreeNode>): number {
-  let count = 0;
-  for (const node of nodes) {
-    count += 1;
-    if (node.kind === "directory") {
-      count += countTurnDiffTreeNodes(node.children);
+    case "message": {
+      const bm = b as typeof a;
+      return (
+        a.message === bm.message &&
+        a.durationStart === bm.durationStart &&
+        a.showCompletionDivider === bm.showCompletionDivider &&
+        a.completionSummary === bm.completionSummary &&
+        a.showAssistantCopyButton === bm.showAssistantCopyButton &&
+        a.assistantCopyStreaming === bm.assistantCopyStreaming &&
+        a.assistantTurnDiffSummary === bm.assistantTurnDiffSummary &&
+        a.revertTurnCount === bm.revertTurnCount
+      );
     }
   }
-  return count;
 }
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index c4bca4b4f01..12103194870 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -1,6 +1,31 @@
-import { MessageId } from "@t3tools/contracts";
+import { EnvironmentId, MessageId } from "@t3tools/contracts";
+import { createRef, type ReactNode, type Ref } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { beforeAll, describe, expect, it, vi } from "vitest";
+import type { LegendListRef } from "@legendapp/list/react";
+
+vi.mock("@legendapp/list/react", async () => {
+  const legendListTestId = "legend-list";
+
+  const LegendList = (props: {
+    data: Array<{ id: string }>;
+    keyExtractor: (item: { id: string }) => string;
+    renderItem: (args: { item: { id: string } }) => ReactNode;
+    ListHeaderComponent?: ReactNode;
+    ListFooterComponent?: ReactNode;
+    ref?: Ref<LegendListRef>;
+  }) => (
+    <div data-testid={legendListTestId}>
+      {props.ListHeaderComponent}
+      {props.data.map((item) => (
+        <div key={props.keyExtractor(item)}>{props.renderItem({ item })}</div>
+      ))}
+      {props.ListFooterComponent}
+    </div>
+  );
+
+  return { LegendList };
+});
 
 function matchMedia() {
   return {
@@ -28,6 +53,11 @@ beforeAll(() => {
     matchMedia,
     addEventListener: () => {},
     removeEventListener: () => {},
+    requestAnimationFrame: (callback: FrameRequestCallback) => {
+      callback(0);
+      return 0;
+    },
+    cancelAnimationFrame: () => {},
     desktopBridge: undefined,
   });
   vi.stubGlobal("document", {
@@ -36,81 +66,132 @@ beforeAll(() => {
       offsetHeight: 0,
     },
   });
-  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
-    callback(0);
-    return 0;
-  });
 });
 
-const ACTIVE_THREAD_ENVIRONMENT_ID = "environment-local" as never;
+const ACTIVE_THREAD_ENVIRONMENT_ID = EnvironmentId.make("environment-local");
+const MESSAGE_CREATED_AT = "2026-03-17T19:12:28.000Z";
+
+function buildProps() {
+  return {
+    isWorking: false,
+    activeTurnInProgress: false,
+    activeTurnId: null,
+    activeTurnStartedAt: null,
+    listRef: createRef<LegendListRef | null>(),
+    completionDividerBeforeEntryId: null,
+    completionSummary: null,
+    turnDiffSummaryByAssistantMessageId: new Map(),
+    routeThreadKey: "environment-local:thread-1",
+    onOpenTurnDiff: () => {},
+    revertTurnCountByUserMessageId: new Map(),
+    onRevertUserMessage: () => {},
+    isRevertingCheckpoint: false,
+    onImageExpand: () => {},
+    activeThreadEnvironmentId: ACTIVE_THREAD_ENVIRONMENT_ID,
+    markdownCwd: undefined,
+    resolvedTheme: "light" as const,
+    timestampFormat: "locale" as const,
+    workspaceRoot: undefined,
+    onIsAtEndChange: () => {},
+  };
+}
+
+function buildLongUserMessageText(tail = "deep hidden detail only after expand") {
+  return Array.from({ length: 9 }, (_, index) =>
+    index === 8 ? tail : `Line ${index + 1}: ${"verbose prompt content ".repeat(8).trim()}`,
+  ).join("\n");
+}
+
+function buildUserTimelineEntry(text: string) {
+  return {
+    id: "entry-1",
+    kind: "message" as const,
+    createdAt: MESSAGE_CREATED_AT,
+    message: {
+      id: MessageId.make("message-1"),
+      role: "user" as const,
+      text,
+      createdAt: MESSAGE_CREATED_AT,
+      streaming: false,
+    },
+  };
+}
 
 describe("MessagesTimeline", () => {
+  it("renders collapse controls for long user messages", async () => {
+    const { MessagesTimeline } = await import("./MessagesTimeline");
+    const markup = renderToStaticMarkup(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[buildUserTimelineEntry(buildLongUserMessageText())]}
+      />,
+    );
+
+    expect(markup).toContain("Show full message");
+    expect(markup).toContain('data-user-message-collapsed="true"');
+    expect(markup).toContain('data-user-message-fade="true"');
+    expect(markup).toContain('data-user-message-footer="true"');
+  });
+
+  it("does not render collapse controls for short user messages", async () => {
+    const { MessagesTimeline } = await import("./MessagesTimeline");
+    const markup = renderToStaticMarkup(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[buildUserTimelineEntry("Short prompt.")]}
+      />,
+    );
+
+    expect(markup).not.toContain("Show full message");
+    expect(markup).toContain('data-user-message-collapsible="false"');
+  });
+
   it("renders inline terminal labels with the composer chip UI", async () => {
     const { MessagesTimeline } = await import("./MessagesTimeline");
     const markup = renderToStaticMarkup(
       <MessagesTimeline
-        hasMessages
-        isWorking={false}
-        activeTurnInProgress={false}
-        activeTurnStartedAt={null}
-        scrollContainer={null}
+        {...buildProps()}
         timelineEntries={[
-          {
-            id: "entry-1",
-            kind: "message",
-            createdAt: "2026-03-17T19:12:28.000Z",
-            message: {
-              id: MessageId.make("message-2"),
-              role: "user",
-              text: [
-                "yoo what's @terminal-1:1-5 mean",
-                "",
-                "<terminal_context>",
-                "- Terminal 1 lines 1-5:",
-                "  1 | julius@mac effect-http-ws-cli % bun i",
-                "  2 | bun install v1.3.9 (cf6cdbbb)",
-                "</terminal_context>",
-              ].join("\n"),
-              createdAt: "2026-03-17T19:12:28.000Z",
-              streaming: false,
-            },
-          },
+          buildUserTimelineEntry(
+            [
+              buildLongUserMessageText("yoo what's @terminal-1:1-5 mean"),
+              "",
+              "<terminal_context>",
+              "- Terminal 1 lines 1-5:",
+              "  1 | julius@mac effect-http-ws-cli % bun i",
+              "  2 | bun install v1.3.9 (cf6cdbbb)",
+              "</terminal_context>",
+            ].join("\n"),
+          ),
         ]}
-        completionDividerBeforeEntryId={null}
-        completionSummary={null}
-        turnDiffSummaryByAssistantMessageId={new Map()}
-        nowIso="2026-03-17T19:12:30.000Z"
-        expandedWorkGroups={{}}
-        onToggleWorkGroup={() => {}}
-        changedFilesExpandedByTurnId={{}}
-        onSetChangedFilesExpanded={() => {}}
-        onOpenTurnDiff={() => {}}
-        revertTurnCountByUserMessageId={new Map()}
-        onRevertUserMessage={() => {}}
-        isRevertingCheckpoint={false}
-        onImageExpand={() => {}}
-        activeThreadEnvironmentId={ACTIVE_THREAD_ENVIRONMENT_ID}
-        markdownCwd={undefined}
-        resolvedTheme="light"
-        timestampFormat="locale"
-        workspaceRoot={undefined}
       />,
     );
 
     expect(markup).toContain("Terminal 1 lines 1-5");
     expect(markup).toContain("lucide-terminal");
     expect(markup).toContain("yoo what&#x27;s ");
-  }, 10_000);
+    expect(markup).toContain("Show full message");
+  }, 20_000);
+
+  it("keeps the copy button for collapsed long user messages", async () => {
+    const { MessagesTimeline } = await import("./MessagesTimeline");
+    const markup = renderToStaticMarkup(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[buildUserTimelineEntry(buildLongUserMessageText())]}
+      />,
+    );
+
+    expect(markup).toContain('aria-label="Copy link"');
+    expect(markup).toContain('data-user-message-collapsed="true"');
+    expect(markup).toContain('data-user-message-footer="true"');
+  });
 
   it("renders context compaction entries in the normal work log", async () => {
     const { MessagesTimeline } = await import("./MessagesTimeline");
     const markup = renderToStaticMarkup(
       <MessagesTimeline
-        hasMessages
-        isWorking={false}
-        activeTurnInProgress={false}
-        activeTurnStartedAt={null}
-        scrollContainer={null}
+        {...buildProps()}
         timelineEntries={[
           {
             id: "entry-1",
@@ -124,28 +205,37 @@ describe("MessagesTimeline", () => {
             },
           },
         ]}
-        completionDividerBeforeEntryId={null}
-        completionSummary={null}
-        turnDiffSummaryByAssistantMessageId={new Map()}
-        nowIso="2026-03-17T19:12:30.000Z"
-        expandedWorkGroups={{}}
-        onToggleWorkGroup={() => {}}
-        changedFilesExpandedByTurnId={{}}
-        onSetChangedFilesExpanded={() => {}}
-        onOpenTurnDiff={() => {}}
-        revertTurnCountByUserMessageId={new Map()}
-        onRevertUserMessage={() => {}}
-        isRevertingCheckpoint={false}
-        onImageExpand={() => {}}
-        activeThreadEnvironmentId={ACTIVE_THREAD_ENVIRONMENT_ID}
-        markdownCwd={undefined}
-        resolvedTheme="light"
-        timestampFormat="locale"
-        workspaceRoot={undefined}
       />,
     );
 
     expect(markup).toContain("Context compacted");
     expect(markup).toContain("Work log");
   });
+
+  it("formats changed file paths from the workspace root", async () => {
+    const { MessagesTimeline } = await import("./MessagesTimeline");
+    const markup = renderToStaticMarkup(
+      <MessagesTimeline
+        {...buildProps()}
+        timelineEntries={[
+          {
+            id: "entry-1",
+            kind: "work",
+            createdAt: "2026-03-17T19:12:28.000Z",
+            entry: {
+              id: "work-1",
+              createdAt: "2026-03-17T19:12:28.000Z",
+              label: "Updated files",
+              tone: "tool",
+              changedFiles: ["C:/Users/mike/dev-stuff/t3code/apps/web/src/session-logic.ts"],
+            },
+          },
+        ]}
+        workspaceRoot="C:/Users/mike/dev-stuff/t3code"
+      />,
+    );
+
+    expect(markup).toContain("t3code/apps/web/src/session-logic.ts");
+    expect(markup).not.toContain("C:/Users/mike/dev-stuff/t3code/apps/web/src/session-logic.ts");
+  });
 });
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index f08d544cc10..1540d5f344a 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -1,21 +1,22 @@
-import { type EnvironmentId, type MessageId, type TurnId } from "@t3tools/contracts";
 import {
+  type EnvironmentId,
+  type MessageId,
+  type ServerProviderSkill,
+  type TurnId,
+} from "@t3tools/contracts";
+import {
+  createContext,
   memo,
+  use,
   useCallback,
   useEffect,
-  useLayoutEffect,
   useMemo,
   useRef,
   useState,
   type ReactNode,
 } from "react";
-import {
-  measureElement as measureVirtualElement,
-  type VirtualItem,
-  useVirtualizer,
-} from "@tanstack/react-virtual";
+import { LegendList, type LegendListRef } from "@legendapp/list/react";
 import { deriveTimelineEntries, formatElapsed } from "../../session-logic";
-import { AUTO_SCROLL_BOTTOM_THRESHOLD_PX } from "../../chat-scroll";
 import { type TurnDiffSummary } from "../../types";
 import { summarizeTurnDiffStats } from "../../lib/turnDiffTree";
 import ChatMarkdown from "../ChatMarkdown";
@@ -34,18 +35,18 @@ import {
   ZapIcon,
 } from "lucide-react";
 import { Button } from "../ui/button";
-import { clamp } from "effect/Number";
 import { buildExpandedImagePreview, ExpandedImagePreview } from "./ExpandedImagePreview";
 import { ProposedPlanCard } from "./ProposedPlanCard";
 import { ChangedFilesTree } from "./ChangedFilesTree";
 import { DiffStatLabel, hasNonZeroStat } from "./DiffStatLabel";
 import { MessageCopyButton } from "./MessageCopyButton";
 import {
+  computeStableMessagesTimelineRows,
   MAX_VISIBLE_WORK_LOG_ENTRIES,
   deriveMessagesTimelineRows,
-  estimateMessagesTimelineRowHeight,
   normalizeCompactToolLabel,
   resolveAssistantMessageCopyState,
+  type StableMessagesTimelineRowsState,
   type MessagesTimelineRow,
 } from "./MessagesTimeline.logic";
 import { TerminalContextInlineChip } from "./TerminalContextInlineChip";
@@ -55,6 +56,7 @@ import {
   type ParsedTerminalContextEntry,
 } from "~/lib/terminalContext";
 import { cn } from "~/lib/utils";
+import { useUiStateStore } from "~/uiStateStore";
 import { type TimestampFormat } from "@t3tools/contracts/settings";
 import { formatTimestamp } from "../../timestampFormat";
 
@@ -63,25 +65,55 @@ import {
   formatInlineTerminalContextLabel,
   textContainsInlineTerminalContextLabels,
 } from "./userMessageTerminalContexts";
+import { SkillInlineText } from "./SkillInlineText";
+import { formatWorkspaceRelativePath } from "../../filePathDisplay";
+
+// ---------------------------------------------------------------------------
+// Context — shared state consumed by every row component via Context.
+// Propagates through LegendList's memo boundaries for shared callbacks and
+// non-row-scoped state. `nowIso` is intentionally excluded — self-ticking
+// components (WorkingTimer, LiveElapsed) handle it.
+// ---------------------------------------------------------------------------
+
+interface TimelineRowSharedState {
+  timestampFormat: TimestampFormat;
+  routeThreadKey: string;
+  markdownCwd: string | undefined;
+  resolvedTheme: "light" | "dark";
+  workspaceRoot: string | undefined;
+  skills: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
+  activeThreadEnvironmentId: EnvironmentId;
+  onRevertUserMessage: (messageId: MessageId) => void;
+  onImageExpand: (preview: ExpandedImagePreview) => void;
+  onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
+}
+
+interface TimelineRowActivityState {
+  isWorking: boolean;
+  isRevertingCheckpoint: boolean;
+}
 
-const ALWAYS_UNVIRTUALIZED_TAIL_ROWS = 8;
+const TimelineRowCtx = createContext<TimelineRowSharedState>(null!);
+const TimelineRowActivityCtx = createContext<TimelineRowActivityState>(null!);
+const TIMELINE_LIST_HEADER = <div className="h-3 sm:h-4" />;
+const TIMELINE_LIST_FOOTER = <div className="h-3 sm:h-4" />;
+const EMPTY_TIMELINE_SKILLS: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">> = [];
+
+// ---------------------------------------------------------------------------
+// Props (public API)
+// ---------------------------------------------------------------------------
 
 interface MessagesTimelineProps {
-  hasMessages: boolean;
   isWorking: boolean;
   activeTurnInProgress: boolean;
   activeTurnId?: TurnId | null;
   activeTurnStartedAt: string | null;
-  scrollContainer: HTMLDivElement | null;
+  listRef: React.RefObject<LegendListRef | null>;
   timelineEntries: ReturnType<typeof deriveTimelineEntries>;
   completionDividerBeforeEntryId: string | null;
   completionSummary: string | null;
   turnDiffSummaryByAssistantMessageId: Map<MessageId, TurnDiffSummary>;
-  nowIso: string;
-  expandedWorkGroups: Record<string, boolean>;
-  onToggleWorkGroup: (groupId: string) => void;
-  changedFilesExpandedByTurnId: Record<string, boolean>;
-  onSetChangedFilesExpanded: (turnId: TurnId, expanded: boolean) => void;
+  routeThreadKey: string;
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
   revertTurnCountByUserMessageId: Map<MessageId, number>;
   onRevertUserMessage: (messageId: MessageId) => void;
@@ -92,35 +124,25 @@ interface MessagesTimelineProps {
   resolvedTheme: "light" | "dark";
   timestampFormat: TimestampFormat;
   workspaceRoot: string | undefined;
-  onVirtualizerSnapshot?: (snapshot: {
-    totalSize: number;
-    measurements: ReadonlyArray<{
-      id: string;
-      kind: MessagesTimelineRow["kind"];
-      index: number;
-      size: number;
-      start: number;
-      end: number;
-    }>;
-  }) => void;
+  skills?: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
+  onIsAtEndChange: (isAtEnd: boolean) => void;
 }
 
+// ---------------------------------------------------------------------------
+// MessagesTimeline — list owner
+// ---------------------------------------------------------------------------
+
 export const MessagesTimeline = memo(function MessagesTimeline({
-  hasMessages,
   isWorking,
   activeTurnInProgress,
   activeTurnId,
   activeTurnStartedAt,
-  scrollContainer,
+  listRef,
   timelineEntries,
   completionDividerBeforeEntryId,
   completionSummary,
   turnDiffSummaryByAssistantMessageId,
-  nowIso,
-  expandedWorkGroups,
-  onToggleWorkGroup,
-  changedFilesExpandedByTurnId,
-  onSetChangedFilesExpanded,
+  routeThreadKey,
   onOpenTurnDiff,
   revertTurnCountByUserMessageId,
   onRevertUserMessage,
@@ -131,181 +153,154 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   resolvedTheme,
   timestampFormat,
   workspaceRoot,
-  onVirtualizerSnapshot,
+  skills = EMPTY_TIMELINE_SKILLS,
+  onIsAtEndChange,
 }: MessagesTimelineProps) {
-  const timelineRootRef = useRef<HTMLDivElement | null>(null);
-  const [timelineWidthPx, setTimelineWidthPx] = useState<number | null>(null);
-
-  useLayoutEffect(() => {
-    const timelineRoot = timelineRootRef.current;
-    if (!timelineRoot) return;
-
-    const updateWidth = (nextWidth: number) => {
-      setTimelineWidthPx((previousWidth) => {
-        if (previousWidth !== null && Math.abs(previousWidth - nextWidth) < 0.5) {
-          return previousWidth;
-        }
-        return nextWidth;
-      });
-    };
-
-    updateWidth(timelineRoot.getBoundingClientRect().width);
-
-    if (typeof ResizeObserver === "undefined") return;
-    const observer = new ResizeObserver(() => {
-      updateWidth(timelineRoot.getBoundingClientRect().width);
-    });
-    observer.observe(timelineRoot);
-    return () => {
-      observer.disconnect();
-    };
-  }, [hasMessages, isWorking]);
-
-  const rows = useMemo(
+  const rawRows = useMemo(
     () =>
       deriveMessagesTimelineRows({
         timelineEntries,
         completionDividerBeforeEntryId,
+        completionSummary,
         isWorking,
+        activeTurnInProgress,
+        activeTurnId: activeTurnId ?? null,
         activeTurnStartedAt,
+        turnDiffSummaryByAssistantMessageId,
+        revertTurnCountByUserMessageId,
       }),
-    [timelineEntries, completionDividerBeforeEntryId, isWorking, activeTurnStartedAt],
+    [
+      timelineEntries,
+      completionDividerBeforeEntryId,
+      completionSummary,
+      isWorking,
+      activeTurnInProgress,
+      activeTurnId,
+      activeTurnStartedAt,
+      turnDiffSummaryByAssistantMessageId,
+      revertTurnCountByUserMessageId,
+    ],
   );
+  const rows = useStableRows(rawRows);
 
-  const firstUnvirtualizedRowIndex = useMemo(() => {
-    const firstTailRowIndex = Math.max(rows.length - ALWAYS_UNVIRTUALIZED_TAIL_ROWS, 0);
-    if (!activeTurnInProgress) return firstTailRowIndex;
-
-    const turnStartedAtMs =
-      typeof activeTurnStartedAt === "string" ? Date.parse(activeTurnStartedAt) : Number.NaN;
-    let firstCurrentTurnRowIndex = -1;
-    if (!Number.isNaN(turnStartedAtMs)) {
-      firstCurrentTurnRowIndex = rows.findIndex((row) => {
-        if (row.kind === "working") return true;
-        if (!row.createdAt) return false;
-        const rowCreatedAtMs = Date.parse(row.createdAt);
-        return !Number.isNaN(rowCreatedAtMs) && rowCreatedAtMs >= turnStartedAtMs;
-      });
-    }
-
-    if (firstCurrentTurnRowIndex < 0) {
-      firstCurrentTurnRowIndex = rows.findIndex(
-        (row) => row.kind === "message" && row.message.streaming,
-      );
+  const handleScroll = useCallback(() => {
+    const state = listRef.current?.getState?.();
+    if (state) {
+      onIsAtEndChange(state.isAtEnd);
     }
+  }, [listRef, onIsAtEndChange]);
 
-    if (firstCurrentTurnRowIndex < 0) return firstTailRowIndex;
+  const previousRowCountRef = useRef(rows.length);
+  useEffect(() => {
+    const previousRowCount = previousRowCountRef.current;
+    previousRowCountRef.current = rows.length;
 
-    for (let index = firstCurrentTurnRowIndex - 1; index >= 0; index -= 1) {
-      const previousRow = rows[index];
-      if (!previousRow || previousRow.kind !== "message") continue;
-      if (previousRow.message.role === "user") {
-        return Math.min(index, firstTailRowIndex);
-      }
-      if (previousRow.message.role === "assistant" && !previousRow.message.streaming) {
-        break;
-      }
+    if (previousRowCount > 0 || rows.length === 0) {
+      return;
     }
 
-    return Math.min(firstCurrentTurnRowIndex, firstTailRowIndex);
-  }, [activeTurnInProgress, activeTurnStartedAt, rows]);
-
-  const virtualizedRowCount = clamp(firstUnvirtualizedRowIndex, {
-    minimum: 0,
-    maximum: rows.length,
-  });
-  const virtualMeasurementScopeKey =
-    timelineWidthPx === null ? "width:unknown" : `width:${Math.round(timelineWidthPx)}`;
-
-  const rowVirtualizer = useVirtualizer({
-    count: virtualizedRowCount,
-    getScrollElement: () => scrollContainer,
-    // Scope cached row measurements to the current timeline width so offscreen
-    // rows do not keep stale heights after wrapping changes.
-    getItemKey: (index: number) => {
-      const rowId = rows[index]?.id ?? String(index);
-      return `${virtualMeasurementScopeKey}:${rowId}`;
-    },
-    estimateSize: (index: number) => {
-      const row = rows[index];
-      if (!row) return 96;
-      return estimateMessagesTimelineRowHeight(row, {
-        expandedWorkGroups,
-        timelineWidthPx,
-        turnDiffSummaryByAssistantMessageId,
-      });
-    },
-    measureElement: measureVirtualElement,
-    useAnimationFrameWithResizeObserver: true,
-    overscan: 8,
-  });
-  useEffect(() => {
-    if (timelineWidthPx === null) return;
-    rowVirtualizer.measure();
-  }, [rowVirtualizer, timelineWidthPx]);
-  useEffect(() => {
-    rowVirtualizer.shouldAdjustScrollPositionOnItemSizeChange = (item, _delta, instance) => {
-      const viewportHeight = instance.scrollRect?.height ?? 0;
-      const scrollOffset = instance.scrollOffset ?? 0;
-      const itemIntersectsViewport =
-        item.end > scrollOffset && item.start < scrollOffset + viewportHeight;
-      if (itemIntersectsViewport) {
-        return false;
-      }
-      const remainingDistance = instance.getTotalSize() - (scrollOffset + viewportHeight);
-      return remainingDistance > AUTO_SCROLL_BOTTOM_THRESHOLD_PX;
-    };
-    return () => {
-      rowVirtualizer.shouldAdjustScrollPositionOnItemSizeChange = undefined;
-    };
-  }, [rowVirtualizer]);
-  const pendingMeasureFrameRef = useRef<number | null>(null);
-  const onTimelineImageLoad = useCallback(() => {
-    if (pendingMeasureFrameRef.current !== null) return;
-    pendingMeasureFrameRef.current = window.requestAnimationFrame(() => {
-      pendingMeasureFrameRef.current = null;
-      rowVirtualizer.measure();
+    onIsAtEndChange(true);
+    const frameId = window.requestAnimationFrame(() => {
+      void listRef.current?.scrollToEnd?.({ animated: false });
     });
-  }, [rowVirtualizer]);
-  useEffect(() => {
     return () => {
-      const frame = pendingMeasureFrameRef.current;
-      if (frame !== null) {
-        window.cancelAnimationFrame(frame);
-      }
+      window.cancelAnimationFrame(frameId);
     };
-  }, []);
-  useLayoutEffect(() => {
-    if (!onVirtualizerSnapshot) {
-      return;
-    }
-    onVirtualizerSnapshot({
-      totalSize: rowVirtualizer.getTotalSize(),
-      measurements: rowVirtualizer.measurementsCache
-        .slice(0, virtualizedRowCount)
-        .flatMap((measurement) => {
-          const row = rows[measurement.index];
-          if (!row) {
-            return [];
-          }
-          return [
-            {
-              id: row.id,
-              kind: row.kind,
-              index: measurement.index,
-              size: measurement.size,
-              start: measurement.start,
-              end: measurement.end,
-            },
-          ];
-        }),
-    });
-  }, [onVirtualizerSnapshot, rowVirtualizer, rows, virtualizedRowCount]);
+  }, [listRef, onIsAtEndChange, rows.length]);
+
+  const sharedState = useMemo<TimelineRowSharedState>(
+    () => ({
+      timestampFormat,
+      routeThreadKey,
+      markdownCwd,
+      resolvedTheme,
+      workspaceRoot,
+      skills,
+      activeThreadEnvironmentId,
+      onRevertUserMessage,
+      onImageExpand,
+      onOpenTurnDiff,
+    }),
+    [
+      timestampFormat,
+      routeThreadKey,
+      markdownCwd,
+      resolvedTheme,
+      workspaceRoot,
+      skills,
+      activeThreadEnvironmentId,
+      onRevertUserMessage,
+      onImageExpand,
+      onOpenTurnDiff,
+    ],
+  );
+  const activityState = useMemo<TimelineRowActivityState>(
+    () => ({
+      isWorking,
+      isRevertingCheckpoint,
+    }),
+    [isRevertingCheckpoint, isWorking],
+  );
 
-  const virtualRows = rowVirtualizer.getVirtualItems();
-  const nonVirtualizedRows = rows.slice(virtualizedRowCount);
+  // Stable renderItem — no closure deps. Row components read shared state
+  // from TimelineRowCtx, which propagates through LegendList's memo.
+  const renderItem = useCallback(
+    ({ item }: { item: MessagesTimelineRow }) => (
+      <div className="mx-auto w-full min-w-0 max-w-3xl overflow-x-clip" data-timeline-root="true">
+        <TimelineRowContent row={item} />
+      </div>
+    ),
+    [],
+  );
 
-  const renderRowContent = (row: TimelineRow) => (
+  if (rows.length === 0 && !isWorking) {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <p className="text-sm text-muted-foreground/30">
+          Send a message to start the conversation.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <TimelineRowCtx value={sharedState}>
+      <TimelineRowActivityCtx value={activityState}>
+        <LegendList<MessagesTimelineRow>
+          ref={listRef}
+          data={rows}
+          keyExtractor={keyExtractor}
+          renderItem={renderItem}
+          estimatedItemSize={90}
+          initialScrollAtEnd
+          maintainScrollAtEnd
+          maintainScrollAtEndThreshold={0.1}
+          maintainVisibleContentPosition
+          onScroll={handleScroll}
+          className="h-full overflow-x-hidden overscroll-y-contain px-3 sm:px-5"
+          ListHeaderComponent={TIMELINE_LIST_HEADER}
+          ListFooterComponent={TIMELINE_LIST_FOOTER}
+        />
+      </TimelineRowActivityCtx>
+    </TimelineRowCtx>
+  );
+});
+
+function keyExtractor(item: MessagesTimelineRow) {
+  return item.id;
+}
+
+// ---------------------------------------------------------------------------
+// TimelineRowContent — the actual row component
+// ---------------------------------------------------------------------------
+
+type TimelineEntry = ReturnType<typeof deriveTimelineEntries>[number];
+type TimelineMessage = Extract<TimelineEntry, { kind: "message" }>["message"];
+type TimelineWorkEntry = Extract<MessagesTimelineRow, { kind: "work" }>["groupedEntries"][number];
+type TimelineRow = MessagesTimelineRow;
+
+const TimelineRowContent = memo(function TimelineRowContent({ row }: { row: TimelineRow }) {
+  return (
     <div
       className={cn(
         "pb-4",
@@ -316,360 +311,434 @@ export const MessagesTimeline = memo(function MessagesTimeline({
       data-message-id={row.kind === "message" ? row.message.id : undefined}
       data-message-role={row.kind === "message" ? row.message.role : undefined}
     >
-      {row.kind === "work" &&
-        (() => {
-          const groupId = row.id;
-          const groupedEntries = row.groupedEntries;
-          const isExpanded = expandedWorkGroups[groupId] ?? false;
-          const hasOverflow = groupedEntries.length > MAX_VISIBLE_WORK_LOG_ENTRIES;
-          const visibleEntries =
-            hasOverflow && !isExpanded
-              ? groupedEntries.slice(-MAX_VISIBLE_WORK_LOG_ENTRIES)
-              : groupedEntries;
-          const hiddenCount = groupedEntries.length - visibleEntries.length;
-          const onlyToolEntries = groupedEntries.every((entry) => entry.tone === "tool");
-          const showHeader = hasOverflow || !onlyToolEntries;
-          const groupLabel = onlyToolEntries ? "Tool calls" : "Work log";
-
-          return (
-            <div className="rounded-xl border border-border/45 bg-card/25 px-2 py-1.5">
-              {showHeader && (
-                <div className="mb-1.5 flex items-center justify-between gap-2 px-0.5">
-                  <p className="text-[9px] uppercase tracking-[0.16em] text-muted-foreground/55">
-                    {groupLabel} ({groupedEntries.length})
-                  </p>
-                  {hasOverflow && (
-                    <button
-                      type="button"
-                      className="text-[9px] uppercase tracking-[0.12em] text-muted-foreground/55 transition-colors duration-150 hover:text-foreground/75"
-                      onClick={() => onToggleWorkGroup(groupId)}
-                    >
-                      {isExpanded ? "Show less" : `Show ${hiddenCount} more`}
-                    </button>
-                  )}
-                </div>
-              )}
-              <div className="space-y-0.5">
-                {visibleEntries.map((workEntry) => (
-                  <SimpleWorkEntryRow key={`work-row:${workEntry.id}`} workEntry={workEntry} />
-                ))}
-              </div>
-            </div>
-          );
-        })()}
-
-      {row.kind === "message" &&
-        row.message.role === "user" &&
-        (() => {
-          const userImages = row.message.attachments ?? [];
-          const displayedUserMessage = deriveDisplayedUserMessageState(row.message.text);
-          const terminalContexts = displayedUserMessage.contexts;
-          const canRevertAgentWork = revertTurnCountByUserMessageId.has(row.message.id);
-          return (
-            <div className="flex justify-end">
-              <div className="group relative max-w-[80%] rounded-2xl rounded-br-sm border border-border bg-secondary px-4 py-3">
-                {userImages.length > 0 && (
-                  <div className="mb-2 grid max-w-[420px] grid-cols-2 gap-2">
-                    {userImages.map(
-                      (image: NonNullable<TimelineMessage["attachments"]>[number]) => (
-                        <div
-                          key={image.id}
-                          className="overflow-hidden rounded-lg border border-border/80 bg-background/70"
-                        >
-                          {image.previewUrl ? (
-                            <button
-                              type="button"
-                              className="h-full w-full cursor-zoom-in"
-                              aria-label={`Preview ${image.name}`}
-                              onClick={() => {
-                                const preview = buildExpandedImagePreview(userImages, image.id);
-                                if (!preview) return;
-                                onImageExpand(preview);
-                              }}
-                            >
-                              <img
-                                src={image.previewUrl}
-                                alt={image.name}
-                                className="block h-auto max-h-[220px] w-full object-cover"
-                                onLoad={onTimelineImageLoad}
-                                onError={onTimelineImageLoad}
-                              />
-                            </button>
-                          ) : (
-                            <div className="flex min-h-[72px] items-center justify-center px-2 py-3 text-center text-[11px] text-muted-foreground/70">
-                              {image.name}
-                            </div>
-                          )}
-                        </div>
-                      ),
-                    )}
+      {row.kind === "work" ? <WorkGroupSection groupedEntries={row.groupedEntries} /> : null}
+      {row.kind === "message" && row.message.role === "user" ? <UserTimelineRow row={row} /> : null}
+      {row.kind === "message" && row.message.role === "assistant" ? (
+        <AssistantTimelineRow row={row} />
+      ) : null}
+      {row.kind === "proposed-plan" ? <ProposedPlanTimelineRow row={row} /> : null}
+      {row.kind === "working" ? <WorkingTimelineRow row={row} /> : null}
+    </div>
+  );
+});
+
+function UserTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message" }> }) {
+  const ctx = use(TimelineRowCtx);
+  const userImages = row.message.attachments ?? [];
+  const displayedUserMessage = deriveDisplayedUserMessageState(row.message.text);
+  const terminalContexts = displayedUserMessage.contexts;
+  const canRevertAgentWork = typeof row.revertTurnCount === "number";
+
+  return (
+    <div className="flex justify-end">
+      <div className="group relative max-w-[80%] rounded-2xl rounded-br-sm border border-border bg-secondary px-4 py-3">
+        {userImages.length > 0 && (
+          <div className="mb-2 grid max-w-[420px] grid-cols-2 gap-2">
+            {userImages.map((image: NonNullable<TimelineMessage["attachments"]>[number]) => (
+              <div
+                key={image.id}
+                className="overflow-hidden rounded-lg border border-border/80 bg-background/70"
+              >
+                {image.previewUrl ? (
+                  <button
+                    type="button"
+                    className="h-full w-full cursor-zoom-in"
+                    aria-label={`Preview ${image.name}`}
+                    onClick={() => {
+                      const preview = buildExpandedImagePreview(userImages, image.id);
+                      if (!preview) return;
+                      ctx.onImageExpand(preview);
+                    }}
+                  >
+                    <img
+                      src={image.previewUrl}
+                      alt={image.name}
+                      className="block h-auto max-h-[220px] w-full object-cover"
+                    />
+                  </button>
+                ) : (
+                  <div className="flex min-h-[72px] items-center justify-center px-2 py-3 text-center text-[11px] text-muted-foreground/70">
+                    {image.name}
                   </div>
                 )}
-                {(displayedUserMessage.visibleText.trim().length > 0 ||
-                  terminalContexts.length > 0) && (
-                  <UserMessageBody
-                    text={displayedUserMessage.visibleText}
-                    terminalContexts={terminalContexts}
-                  />
-                )}
-                <div className="mt-1.5 flex items-center justify-end gap-2">
-                  <div className="flex items-center gap-1.5 opacity-0 transition-opacity duration-200 focus-within:opacity-100 group-hover:opacity-100">
-                    {displayedUserMessage.copyText && (
-                      <MessageCopyButton text={displayedUserMessage.copyText} />
-                    )}
-                    {canRevertAgentWork && (
-                      <Button
-                        type="button"
-                        size="xs"
-                        variant="outline"
-                        disabled={isRevertingCheckpoint || isWorking}
-                        onClick={() => onRevertUserMessage(row.message.id)}
-                        title="Revert to this message"
-                      >
-                        <Undo2Icon className="size-3" />
-                      </Button>
-                    )}
-                  </div>
-                  <p className="text-right text-xs text-muted-foreground/50">
-                    {formatTimestamp(row.message.createdAt, timestampFormat)}
-                  </p>
-                </div>
               </div>
-            </div>
-          );
-        })()}
-
-      {row.kind === "message" &&
-        row.message.role === "assistant" &&
-        (() => {
-          const messageText = row.message.text || (row.message.streaming ? "" : "(empty response)");
-          const assistantTurnStillInProgress =
-            activeTurnInProgress &&
-            activeTurnId !== null &&
-            activeTurnId !== undefined &&
-            row.message.turnId === activeTurnId;
-          const assistantCopyState = resolveAssistantMessageCopyState({
-            text: row.message.text ?? null,
-            showCopyButton: row.showAssistantCopyButton,
-            streaming: row.message.streaming || assistantTurnStillInProgress,
-          });
-          return (
+            ))}
+          </div>
+        )}
+        <CollapsibleUserMessageBody
+          text={displayedUserMessage.visibleText}
+          terminalContexts={terminalContexts}
+          skills={ctx.skills}
+          footer={
             <>
-              {row.showCompletionDivider && (
-                <div className="my-3 flex items-center gap-3">
-                  <span className="h-px flex-1 bg-border" />
-                  <span className="rounded-full border border-border bg-background px-2.5 py-1 text-[10px] uppercase tracking-[0.14em] text-muted-foreground/80">
-                    {completionSummary ? `Response • ${completionSummary}` : "Response"}
-                  </span>
-                  <span className="h-px flex-1 bg-border" />
-                </div>
-              )}
-              <div className="min-w-0 px-1 py-0.5">
-                <ChatMarkdown
-                  text={messageText}
-                  cwd={markdownCwd}
-                  isStreaming={Boolean(row.message.streaming)}
-                />
-                {(() => {
-                  const turnSummary = turnDiffSummaryByAssistantMessageId.get(row.message.id);
-                  if (!turnSummary) return null;
-                  const checkpointFiles = turnSummary.files;
-                  if (checkpointFiles.length === 0) return null;
-                  const summaryStat = summarizeTurnDiffStats(checkpointFiles);
-                  const changedFileCountLabel = String(checkpointFiles.length);
-                  const allDirectoriesExpanded =
-                    changedFilesExpandedByTurnId[turnSummary.turnId] ?? true;
-                  return (
-                    <div className="mt-2 rounded-lg border border-border/80 bg-card/45 p-2.5">
-                      <div className="mb-1.5 flex items-center justify-between gap-2">
-                        <p className="text-[10px] uppercase tracking-[0.12em] text-muted-foreground/65">
-                          <span>Changed files ({changedFileCountLabel})</span>
-                          {hasNonZeroStat(summaryStat) && (
-                            <>
-                              <span className="mx-1">•</span>
-                              <DiffStatLabel
-                                additions={summaryStat.additions}
-                                deletions={summaryStat.deletions}
-                              />
-                            </>
-                          )}
-                        </p>
-                        <div className="flex items-center gap-1.5">
-                          <Button
-                            type="button"
-                            size="xs"
-                            variant="outline"
-                            data-scroll-anchor-ignore
-                            onClick={() =>
-                              onSetChangedFilesExpanded(turnSummary.turnId, !allDirectoriesExpanded)
-                            }
-                          >
-                            {allDirectoriesExpanded ? "Collapse all" : "Expand all"}
-                          </Button>
-                          <Button
-                            type="button"
-                            size="xs"
-                            variant="outline"
-                            onClick={() =>
-                              onOpenTurnDiff(turnSummary.turnId, checkpointFiles[0]?.path)
-                            }
-                          >
-                            View diff
-                          </Button>
-                        </div>
-                      </div>
-                      <ChangedFilesTree
-                        key={`changed-files-tree:${turnSummary.turnId}`}
-                        turnId={turnSummary.turnId}
-                        files={checkpointFiles}
-                        allDirectoriesExpanded={allDirectoriesExpanded}
-                        resolvedTheme={resolvedTheme}
-                        onOpenTurnDiff={onOpenTurnDiff}
-                      />
-                    </div>
-                  );
-                })()}
-                <div className="mt-1.5 flex items-center gap-2">
-                  <p className="text-[10px] text-muted-foreground/30">
-                    {formatMessageMeta(
-                      row.message.createdAt,
-                      row.message.streaming
-                        ? formatElapsed(row.durationStart, nowIso)
-                        : formatElapsed(row.durationStart, row.message.completedAt),
-                      timestampFormat,
-                    )}
-                  </p>
-                  {assistantCopyState.visible ? (
-                    <div className="flex items-center opacity-0 transition-opacity duration-200  group-hover/assistant:opacity-100">
-                      <MessageCopyButton
-                        text={assistantCopyState.text ?? ""}
-                        size="icon-xs"
-                        variant="outline"
-                        className="border-border/50 bg-background/35 text-muted-foreground/45 shadow-none hover:border-border/70 hover:bg-background/55 hover:text-muted-foreground/70"
-                      />
-                    </div>
-                  ) : null}
-                </div>
+              <div className="flex items-center gap-1.5 opacity-0 transition-opacity duration-200 focus-within:opacity-100 group-hover:opacity-100">
+                {displayedUserMessage.copyText && (
+                  <MessageCopyButton text={displayedUserMessage.copyText} />
+                )}
+                {canRevertAgentWork && <RevertUserMessageButton messageId={row.message.id} />}
               </div>
+              <p className="text-right text-xs text-muted-foreground/50">
+                {formatTimestamp(row.message.createdAt, ctx.timestampFormat)}
+              </p>
             </>
-          );
-        })()}
-
-      {row.kind === "proposed-plan" && (
-        <div className="min-w-0 px-1 py-0.5">
-          <ProposedPlanCard
-            planMarkdown={row.proposedPlan.planMarkdown}
-            environmentId={activeThreadEnvironmentId}
-            cwd={markdownCwd}
-            workspaceRoot={workspaceRoot}
-          />
-        </div>
-      )}
-
-      {row.kind === "working" && (
-        <div className="py-0.5 pl-1.5">
-          <div className="flex items-center gap-2 pt-1 text-[11px] text-muted-foreground/70">
-            <span className="inline-flex items-center gap-[3px]">
-              <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse" />
-              <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse [animation-delay:200ms]" />
-              <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse [animation-delay:400ms]" />
-            </span>
-            <span>
-              {row.createdAt
-                ? `Working for ${formatWorkingTimer(row.createdAt, nowIso) ?? "0s"}`
-                : "Working..."}
-            </span>
-          </div>
-        </div>
-      )}
+          }
+        />
+      </div>
     </div>
   );
+}
 
-  if (!hasMessages && !isWorking) {
-    return (
-      <div className="flex h-full items-center justify-center">
-        <p className="text-sm text-muted-foreground/30">
-          Send a message to start the conversation.
-        </p>
-      </div>
-    );
-  }
+function RevertUserMessageButton({ messageId }: { messageId: MessageId }) {
+  const ctx = use(TimelineRowCtx);
+  const activity = use(TimelineRowActivityCtx);
 
   return (
-    <div
-      ref={timelineRootRef}
-      data-timeline-root="true"
-      className="mx-auto w-full min-w-0 max-w-3xl overflow-x-hidden"
+    <Button
+      type="button"
+      size="xs"
+      variant="outline"
+      disabled={activity.isRevertingCheckpoint || activity.isWorking}
+      onClick={() => ctx.onRevertUserMessage(messageId)}
+      title="Revert to this message"
     >
-      {virtualizedRowCount > 0 && (
-        <div className="relative" style={{ height: `${rowVirtualizer.getTotalSize()}px` }}>
-          {virtualRows.map((virtualRow: VirtualItem) => {
-            const row = rows[virtualRow.index];
-            if (!row) return null;
+      <Undo2Icon className="size-3" />
+    </Button>
+  );
+}
 
-            return (
-              <div
-                key={`virtual-row:${row.id}`}
-                data-index={virtualRow.index}
-                data-virtual-row-id={row.id}
-                data-virtual-row-kind={row.kind}
-                data-virtual-row-size={virtualRow.size}
-                data-virtual-row-start={virtualRow.start}
-                ref={rowVirtualizer.measureElement}
-                className="absolute left-0 top-0 w-full"
-                style={{ transform: `translateY(${virtualRow.start}px)` }}
-              >
-                {renderRowContent(row)}
-              </div>
-            );
-          })}
-        </div>
+function AssistantTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message" }> }) {
+  const ctx = use(TimelineRowCtx);
+  const messageText = row.message.text || (row.message.streaming ? "" : "(empty response)");
+
+  return (
+    <>
+      {row.showCompletionDivider && (
+        <AssistantCompletionDivider completionSummary={row.completionSummary} />
       )}
+      <div className="min-w-0 px-1 py-0.5">
+        <ChatMarkdown
+          text={messageText}
+          cwd={ctx.markdownCwd}
+          isStreaming={Boolean(row.message.streaming)}
+          skills={ctx.skills}
+        />
+        <AssistantChangedFilesSection
+          turnSummary={row.assistantTurnDiffSummary}
+          routeThreadKey={ctx.routeThreadKey}
+          resolvedTheme={ctx.resolvedTheme}
+          onOpenTurnDiff={ctx.onOpenTurnDiff}
+        />
+        <div className="mt-1.5 flex items-center gap-2">
+          <p className="text-[10px] text-muted-foreground/30">
+            {row.message.streaming ? (
+              <LiveMessageMeta
+                createdAt={row.message.createdAt}
+                durationStart={row.durationStart}
+                timestampFormat={ctx.timestampFormat}
+              />
+            ) : (
+              formatMessageMeta(
+                row.message.createdAt,
+                formatElapsed(row.durationStart, row.message.completedAt),
+                ctx.timestampFormat,
+              )
+            )}
+          </p>
+          <AssistantCopyButton row={row} />
+        </div>
+      </div>
+    </>
+  );
+}
 
-      {nonVirtualizedRows.map((row) => (
-        <div key={`non-virtual-row:${row.id}`}>{renderRowContent(row)}</div>
-      ))}
+function AssistantCompletionDivider({ completionSummary }: { completionSummary: string | null }) {
+  return (
+    <div className="my-3 flex items-center gap-3">
+      <span className="h-px flex-1 bg-border" />
+      <span className="rounded-full border border-border bg-background px-2.5 py-1 text-[10px] uppercase tracking-[0.14em] text-muted-foreground/80">
+        {completionSummary ? `Response • ${completionSummary}` : "Response"}
+      </span>
+      <span className="h-px flex-1 bg-border" />
     </div>
   );
-});
+}
 
-type TimelineEntry = ReturnType<typeof deriveTimelineEntries>[number];
-type TimelineMessage = Extract<TimelineEntry, { kind: "message" }>["message"];
-type TimelineWorkEntry = Extract<MessagesTimelineRow, { kind: "work" }>["groupedEntries"][number];
-type TimelineRow = MessagesTimelineRow;
+function AssistantCopyButton({ row }: { row: Extract<TimelineRow, { kind: "message" }> }) {
+  const assistantCopyState = resolveAssistantMessageCopyState({
+    text: row.message.text ?? null,
+    showCopyButton: row.showAssistantCopyButton,
+    streaming: row.assistantCopyStreaming,
+  });
 
-function formatWorkingTimer(startIso: string, endIso: string): string | null {
-  const startedAtMs = Date.parse(startIso);
-  const endedAtMs = Date.parse(endIso);
-  if (!Number.isFinite(startedAtMs) || !Number.isFinite(endedAtMs)) {
+  if (!assistantCopyState.visible) {
     return null;
   }
 
-  const elapsedSeconds = Math.max(0, Math.floor((endedAtMs - startedAtMs) / 1000));
-  if (elapsedSeconds < 60) {
-    return `${elapsedSeconds}s`;
-  }
+  return (
+    <div className="flex items-center opacity-0 transition-opacity duration-200  group-hover/assistant:opacity-100">
+      <MessageCopyButton
+        text={assistantCopyState.text ?? ""}
+        size="icon-xs"
+        variant="outline"
+        className="border-border/50 bg-background/35 text-muted-foreground/45 shadow-none hover:border-border/70 hover:bg-background/55 hover:text-muted-foreground/70"
+      />
+    </div>
+  );
+}
 
-  const hours = Math.floor(elapsedSeconds / 3600);
-  const minutes = Math.floor((elapsedSeconds % 3600) / 60);
-  const seconds = elapsedSeconds % 60;
+function ProposedPlanTimelineRow({
+  row,
+}: {
+  row: Extract<TimelineRow, { kind: "proposed-plan" }>;
+}) {
+  const ctx = use(TimelineRowCtx);
 
-  if (hours > 0) {
-    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
-  }
+  return (
+    <div className="min-w-0 px-1 py-0.5">
+      <ProposedPlanCard
+        planMarkdown={row.proposedPlan.planMarkdown}
+        environmentId={ctx.activeThreadEnvironmentId}
+        cwd={ctx.markdownCwd}
+        workspaceRoot={ctx.workspaceRoot}
+      />
+    </div>
+  );
+}
 
-  return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+function WorkingTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "working" }> }) {
+  return (
+    <div className="py-0.5 pl-1.5">
+      <div className="flex items-center gap-2 pt-1 text-[11px] text-muted-foreground/70">
+        <span className="inline-flex items-center gap-[3px]">
+          <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse" />
+          <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse [animation-delay:200ms]" />
+          <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse [animation-delay:400ms]" />
+        </span>
+        <span>
+          {row.createdAt ? (
+            <>
+              Working for <WorkingTimer createdAt={row.createdAt} />
+            </>
+          ) : (
+            "Working..."
+          )}
+        </span>
+      </div>
+    </div>
+  );
 }
 
-function formatMessageMeta(
-  createdAt: string,
-  duration: string | null,
-  timestampFormat: TimestampFormat,
-): string {
-  if (!duration) return formatTimestamp(createdAt, timestampFormat);
-  return `${formatTimestamp(createdAt, timestampFormat)} • ${duration}`;
+// ---------------------------------------------------------------------------
+// Self-ticking labels — update their own text nodes so elapsed-time display
+// does not create a React commit every second while a response is streaming.
+// ---------------------------------------------------------------------------
+
+/** Live "Working for Xs" label. */
+function WorkingTimer({ createdAt }: { createdAt: string }) {
+  const textRef = useRef<HTMLSpanElement>(null);
+  const initialText = formatWorkingTimerNow(createdAt);
+
+  useEffect(() => {
+    const updateText = () => {
+      if (textRef.current) {
+        textRef.current.textContent = formatWorkingTimerNow(createdAt);
+      }
+    };
+    updateText();
+    const id = setInterval(updateText, 1000);
+    return () => clearInterval(id);
+  }, [createdAt]);
+
+  return <span ref={textRef}>{initialText}</span>;
+}
+
+/** Live timestamp + elapsed duration for a streaming assistant message. */
+function LiveMessageMeta({
+  createdAt,
+  durationStart,
+  timestampFormat,
+}: {
+  createdAt: string;
+  durationStart: string | null | undefined;
+  timestampFormat: TimestampFormat;
+}) {
+  const textRef = useRef<HTMLSpanElement>(null);
+  const initialText = formatLiveMessageMetaNow(createdAt, durationStart, timestampFormat);
+
+  useEffect(() => {
+    const updateText = () => {
+      if (textRef.current) {
+        textRef.current.textContent = formatLiveMessageMetaNow(
+          createdAt,
+          durationStart,
+          timestampFormat,
+        );
+      }
+    };
+    updateText();
+    if (!durationStart) {
+      return;
+    }
+    const id = setInterval(updateText, 1000);
+    return () => clearInterval(id);
+  }, [createdAt, durationStart, timestampFormat]);
+
+  return <span ref={textRef}>{initialText}</span>;
+}
+
+// ---------------------------------------------------------------------------
+// Extracted row sections — own their state / store subscriptions so changes
+// re-render only the affected row, not the entire list.
+// ---------------------------------------------------------------------------
+
+/** Owns its own expand/collapse state so toggling re-renders only this row.
+ *  State resets on unmount which is fine — work groups start collapsed. */
+const WorkGroupSection = memo(function WorkGroupSection({
+  groupedEntries,
+}: {
+  groupedEntries: Extract<MessagesTimelineRow, { kind: "work" }>["groupedEntries"];
+}) {
+  const { workspaceRoot } = use(TimelineRowCtx);
+  const [isExpanded, setIsExpanded] = useState(false);
+  const hasOverflow = groupedEntries.length > MAX_VISIBLE_WORK_LOG_ENTRIES;
+  const visibleEntries =
+    hasOverflow && !isExpanded
+      ? groupedEntries.slice(-MAX_VISIBLE_WORK_LOG_ENTRIES)
+      : groupedEntries;
+  const hiddenCount = groupedEntries.length - visibleEntries.length;
+  const onlyToolEntries = groupedEntries.every((entry) => entry.tone === "tool");
+  const showHeader = hasOverflow || !onlyToolEntries;
+  const groupLabel = onlyToolEntries ? "Tool calls" : "Work log";
+
+  return (
+    <div className="rounded-xl border border-border/45 bg-card/25 px-2 py-1.5">
+      {showHeader && (
+        <div className="mb-1.5 flex items-center justify-between gap-2 px-0.5">
+          <p className="text-[9px] uppercase tracking-[0.16em] text-muted-foreground/55">
+            {groupLabel} ({groupedEntries.length})
+          </p>
+          {hasOverflow && (
+            <button
+              type="button"
+              className="text-[9px] uppercase tracking-[0.12em] text-muted-foreground/55 transition-colors duration-150 hover:text-foreground/75"
+              onClick={() => setIsExpanded((v) => !v)}
+            >
+              {isExpanded ? "Show less" : `Show ${hiddenCount} more`}
+            </button>
+          )}
+        </div>
+      )}
+      <div className="space-y-0.5">
+        {visibleEntries.map((workEntry) => (
+          <SimpleWorkEntryRow
+            key={`work-row:${workEntry.id}`}
+            workEntry={workEntry}
+            workspaceRoot={workspaceRoot}
+          />
+        ))}
+      </div>
+    </div>
+  );
+});
+
+/** Subscribes directly to the UI state store for expand/collapse state,
+ *  so toggling re-renders only this component — not the entire list. */
+const AssistantChangedFilesSection = memo(function AssistantChangedFilesSection({
+  turnSummary,
+  routeThreadKey,
+  resolvedTheme,
+  onOpenTurnDiff,
+}: {
+  turnSummary: TurnDiffSummary | undefined;
+  routeThreadKey: string;
+  resolvedTheme: "light" | "dark";
+  onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
+}) {
+  if (!turnSummary) return null;
+  const checkpointFiles = turnSummary.files;
+  if (checkpointFiles.length === 0) return null;
+
+  return (
+    <AssistantChangedFilesSectionInner
+      turnSummary={turnSummary}
+      checkpointFiles={checkpointFiles}
+      routeThreadKey={routeThreadKey}
+      resolvedTheme={resolvedTheme}
+      onOpenTurnDiff={onOpenTurnDiff}
+    />
+  );
+});
+
+/** Inner component that only mounts when there are actual changed files,
+ *  so the store subscription is unconditional (no hooks after early return). */
+function AssistantChangedFilesSectionInner({
+  turnSummary,
+  checkpointFiles,
+  routeThreadKey,
+  resolvedTheme,
+  onOpenTurnDiff,
+}: {
+  turnSummary: TurnDiffSummary;
+  checkpointFiles: TurnDiffSummary["files"];
+  routeThreadKey: string;
+  resolvedTheme: "light" | "dark";
+  onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
+}) {
+  const allDirectoriesExpanded = useUiStateStore(
+    (store) => store.threadChangedFilesExpandedById[routeThreadKey]?.[turnSummary.turnId] ?? true,
+  );
+  const setExpanded = useUiStateStore((store) => store.setThreadChangedFilesExpanded);
+  const summaryStat = summarizeTurnDiffStats(checkpointFiles);
+  const changedFileCountLabel = String(checkpointFiles.length);
+
+  return (
+    <div className="mt-2 rounded-lg border border-border/80 bg-card/45 p-2.5">
+      <div className="sticky top-2 z-10 mb-1.5 flex items-center justify-between gap-2 bg-[color-mix(in_srgb,var(--card)_45%,var(--background))] before:absolute before:inset-x-0 before:-top-2 before:h-2 before:bg-[color-mix(in_srgb,var(--card)_45%,var(--background))] before:content-['']">
+        <p className="text-[10px] uppercase tracking-[0.12em] text-muted-foreground/65">
+          <span>Changed files ({changedFileCountLabel})</span>
+          {hasNonZeroStat(summaryStat) && (
+            <>
+              <span className="mx-1">•</span>
+              <DiffStatLabel additions={summaryStat.additions} deletions={summaryStat.deletions} />
+            </>
+          )}
+        </p>
+        <div className="flex items-center gap-1.5">
+          <Button
+            type="button"
+            size="xs"
+            variant="outline"
+            data-scroll-anchor-ignore
+            onClick={() => setExpanded(routeThreadKey, turnSummary.turnId, !allDirectoriesExpanded)}
+          >
+            {allDirectoriesExpanded ? "Collapse all" : "Expand all"}
+          </Button>
+          <Button
+            type="button"
+            size="xs"
+            variant="outline"
+            onClick={() => onOpenTurnDiff(turnSummary.turnId, checkpointFiles[0]?.path)}
+          >
+            View diff
+          </Button>
+        </div>
+      </div>
+      <ChangedFilesTree
+        key={`changed-files-tree:${turnSummary.turnId}`}
+        turnId={turnSummary.turnId}
+        files={checkpointFiles}
+        allDirectoriesExpanded={allDirectoriesExpanded}
+        resolvedTheme={resolvedTheme}
+        onOpenTurnDiff={onOpenTurnDiff}
+      />
+    </div>
+  );
 }
 
+// ---------------------------------------------------------------------------
+// Leaf components
+// ---------------------------------------------------------------------------
+
 const UserMessageTerminalContextInlineLabel = memo(
   function UserMessageTerminalContextInlineLabel(props: { context: ParsedTerminalContextEntry }) {
     const tooltipText =
@@ -681,9 +750,92 @@ const UserMessageTerminalContextInlineLabel = memo(
   },
 );
 
+const MAX_COLLAPSED_USER_MESSAGE_LINES = 8;
+const MAX_COLLAPSED_USER_MESSAGE_LENGTH = 600;
+const COLLAPSED_USER_MESSAGE_FADE_HEIGHT_REM = 1.75;
+const COLLAPSED_USER_MESSAGE_FADE_MASK = `linear-gradient(to bottom, black calc(100% - ${COLLAPSED_USER_MESSAGE_FADE_HEIGHT_REM}rem), transparent)`;
+
+function shouldCollapseUserMessage(text: string): boolean {
+  if (text.trim().length === 0) {
+    return false;
+  }
+
+  return (
+    text.length > MAX_COLLAPSED_USER_MESSAGE_LENGTH ||
+    text.split("\n").length > MAX_COLLAPSED_USER_MESSAGE_LINES
+  );
+}
+
+const CollapsibleUserMessageBody = memo(function CollapsibleUserMessageBody(props: {
+  text: string;
+  terminalContexts: ParsedTerminalContextEntry[];
+  skills: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
+  footer?: ReactNode;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const hasVisibleBody = props.text.trim().length > 0 || props.terminalContexts.length > 0;
+  const canCollapse = hasVisibleBody && shouldCollapseUserMessage(props.text);
+  const isCollapsed = canCollapse && !expanded;
+
+  return (
+    <div>
+      {hasVisibleBody ? (
+        <div
+          className={cn("relative", isCollapsed && "max-h-44 overflow-hidden")}
+          data-user-message-body="true"
+          data-user-message-collapsed={isCollapsed ? "true" : "false"}
+          data-user-message-collapsible={canCollapse ? "true" : "false"}
+          data-user-message-fade={isCollapsed ? "true" : "false"}
+          style={
+            isCollapsed
+              ? {
+                  WebkitMaskImage: COLLAPSED_USER_MESSAGE_FADE_MASK,
+                  maskImage: COLLAPSED_USER_MESSAGE_FADE_MASK,
+                }
+              : undefined
+          }
+        >
+          <UserMessageBody
+            text={props.text}
+            terminalContexts={props.terminalContexts}
+            skills={props.skills}
+          />
+        </div>
+      ) : null}
+      {canCollapse || props.footer ? (
+        <div
+          className={cn(
+            "mt-1.5 flex items-center gap-2",
+            canCollapse && props.footer ? "justify-between" : "justify-end",
+          )}
+          data-user-message-footer="true"
+        >
+          {canCollapse ? (
+            <Button
+              type="button"
+              size="xs"
+              variant="ghost"
+              aria-expanded={expanded}
+              data-scroll-anchor-ignore
+              onClick={() => setExpanded((value) => !value)}
+              className="-ml-1 h-6 rounded-md px-1.5 text-xs text-muted-foreground/72 hover:bg-muted/55 hover:text-foreground/85"
+            >
+              {expanded ? "Show less" : "Show full message"}
+            </Button>
+          ) : null}
+          {props.footer ? (
+            <div className="ml-auto flex items-center gap-2">{props.footer}</div>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+});
+
 const UserMessageBody = memo(function UserMessageBody(props: {
   text: string;
   terminalContexts: ParsedTerminalContextEntry[];
+  skills: ReadonlyArray<Pick<ServerProviderSkill, "name" | "displayName">>;
 }) {
   if (props.terminalContexts.length > 0) {
     const hasEmbeddedInlineLabels = textContainsInlineTerminalContextLabels(
@@ -706,7 +858,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
         if (matchIndex > cursor) {
           inlineNodes.push(
             <span key={`user-terminal-context-inline-before:${context.header}:${cursor}`}>
-              {props.text.slice(cursor, matchIndex)}
+              <SkillInlineText text={props.text.slice(cursor, matchIndex)} skills={props.skills} />
             </span>,
           );
         }
@@ -723,7 +875,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
         if (cursor < props.text.length) {
           inlineNodes.push(
             <span key={`user-message-terminal-context-inline-rest:${cursor}`}>
-              {props.text.slice(cursor)}
+              <SkillInlineText text={props.text.slice(cursor)} skills={props.skills} />
             </span>,
           );
         }
@@ -751,7 +903,11 @@ const UserMessageBody = memo(function UserMessageBody(props: {
     }
 
     if (props.text.length > 0) {
-      inlineNodes.push(<span key="user-message-terminal-context-inline-text">{props.text}</span>);
+      inlineNodes.push(
+        <span key="user-message-terminal-context-inline-text">
+          <SkillInlineText text={props.text} skills={props.skills} />
+        </span>,
+      );
     } else if (inlinePrefix.length === 0) {
       return null;
     }
@@ -769,11 +925,80 @@ const UserMessageBody = memo(function UserMessageBody(props: {
 
   return (
     <div className="whitespace-pre-wrap wrap-break-word text-sm leading-relaxed text-foreground">
-      {props.text}
+      <SkillInlineText text={props.text} skills={props.skills} />
     </div>
   );
 });
 
+// ---------------------------------------------------------------------------
+// Structural sharing — reuse old row references when data hasn't changed
+// so LegendList (and React) can skip re-rendering unchanged items.
+// ---------------------------------------------------------------------------
+
+/** Returns a structurally-shared copy of `rows`: for each row whose content
+ *  hasn't changed since last call, the previous object reference is reused. */
+function useStableRows(rows: MessagesTimelineRow[]): MessagesTimelineRow[] {
+  const prevState = useRef<StableMessagesTimelineRowsState>({
+    byId: new Map<string, MessagesTimelineRow>(),
+    result: [],
+  });
+
+  return useMemo(() => {
+    const nextState = computeStableMessagesTimelineRows(rows, prevState.current);
+    prevState.current = nextState;
+    return nextState.result;
+  }, [rows]);
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+function formatWorkingTimer(startIso: string, endIso: string): string | null {
+  const startedAtMs = Date.parse(startIso);
+  const endedAtMs = Date.parse(endIso);
+  if (!Number.isFinite(startedAtMs) || !Number.isFinite(endedAtMs)) {
+    return null;
+  }
+
+  const elapsedSeconds = Math.max(0, Math.floor((endedAtMs - startedAtMs) / 1000));
+  if (elapsedSeconds < 60) {
+    return `${elapsedSeconds}s`;
+  }
+
+  const hours = Math.floor(elapsedSeconds / 3600);
+  const minutes = Math.floor((elapsedSeconds % 3600) / 60);
+  const seconds = elapsedSeconds % 60;
+
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+
+  return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+}
+
+function formatWorkingTimerNow(startIso: string): string {
+  return formatWorkingTimer(startIso, new Date().toISOString()) ?? "0s";
+}
+
+function formatLiveMessageMetaNow(
+  createdAt: string,
+  durationStart: string | null | undefined,
+  timestampFormat: TimestampFormat,
+): string {
+  const elapsed = durationStart ? formatElapsed(durationStart, new Date().toISOString()) : null;
+  return formatMessageMeta(createdAt, elapsed, timestampFormat);
+}
+
+function formatMessageMeta(
+  createdAt: string,
+  duration: string | null,
+  timestampFormat: TimestampFormat,
+): string {
+  if (!duration) return formatTimestamp(createdAt, timestampFormat);
+  return `${formatTimestamp(createdAt, timestampFormat)} • ${duration}`;
+}
+
 function workToneIcon(tone: TimelineWorkEntry["tone"]): {
   icon: LucideIcon;
   className: string;
@@ -811,15 +1036,17 @@ function workToneClass(tone: "thinking" | "tool" | "info" | "error"): string {
 
 function workEntryPreview(
   workEntry: Pick<TimelineWorkEntry, "detail" | "command" | "changedFiles">,
+  workspaceRoot: string | undefined,
 ) {
   if (workEntry.command) return workEntry.command;
   if (workEntry.detail) return workEntry.detail;
   if ((workEntry.changedFiles?.length ?? 0) === 0) return null;
   const [firstPath] = workEntry.changedFiles ?? [];
   if (!firstPath) return null;
+  const displayPath = formatWorkspaceRelativePath(firstPath, workspaceRoot);
   return workEntry.changedFiles!.length === 1
-    ? firstPath
-    : `${firstPath} +${workEntry.changedFiles!.length - 1} more`;
+    ? displayPath
+    : `${displayPath} +${workEntry.changedFiles!.length - 1} more`;
 }
 
 function workEntryRawCommand(
@@ -874,12 +1101,19 @@ function toolWorkEntryHeading(workEntry: TimelineWorkEntry): string {
 
 const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
   workEntry: TimelineWorkEntry;
+  workspaceRoot: string | undefined;
 }) {
-  const { workEntry } = props;
+  const { workEntry, workspaceRoot } = props;
   const iconConfig = workToneIcon(workEntry.tone);
   const EntryIcon = workEntryIcon(workEntry);
   const heading = toolWorkEntryHeading(workEntry);
-  const preview = workEntryPreview(workEntry);
+  const rawPreview = workEntryPreview(workEntry, workspaceRoot);
+  const preview =
+    rawPreview &&
+    normalizeCompactToolLabel(rawPreview).toLowerCase() ===
+      normalizeCompactToolLabel(heading).toLowerCase()
+      ? null
+      : rawPreview;
   const rawCommand = workEntryRawCommand(workEntry);
   const displayText = preview ? `${heading} - ${preview}` : heading;
   const hasChangedFiles = (workEntry.changedFiles?.length ?? 0) > 0;
@@ -894,20 +1128,20 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
           <EntryIcon className="size-3" />
         </span>
         <div className="min-w-0 flex-1 overflow-hidden">
-          <div className="max-w-full">
-            <p
-              className={cn(
-                "truncate text-xs leading-5",
-                workToneClass(workEntry.tone),
-                preview ? "text-muted-foreground/70" : "",
-              )}
-              title={rawCommand ? undefined : displayText}
-            >
-              <span className={cn("text-foreground/80", workToneClass(workEntry.tone))}>
-                {heading}
-              </span>
-              {preview &&
-                (rawCommand ? (
+          {rawCommand ? (
+            <div className="max-w-full">
+              <p
+                className={cn(
+                  "truncate text-xs leading-5",
+                  workToneClass(workEntry.tone),
+                  preview ? "text-muted-foreground/70" : "",
+                )}
+                title={displayText}
+              >
+                <span className={cn("text-foreground/80", workToneClass(workEntry.tone))}>
+                  {heading}
+                </span>
+                {preview && (
                   <Tooltip>
                     <TooltipTrigger
                       closeDelay={0}
@@ -929,24 +1163,52 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                       </div>
                     </TooltipPopup>
                   </Tooltip>
-                ) : (
-                  <span className="text-muted-foreground/55"> - {preview}</span>
-                ))}
-            </p>
-          </div>
+                )}
+              </p>
+            </div>
+          ) : (
+            <Tooltip>
+              <TooltipTrigger
+                className="block min-w-0 w-full text-left"
+                title={displayText}
+                aria-label={displayText}
+              >
+                <p
+                  className={cn(
+                    "truncate text-[11px] leading-5",
+                    workToneClass(workEntry.tone),
+                    preview ? "text-muted-foreground/70" : "",
+                  )}
+                >
+                  <span className={cn("text-foreground/80", workToneClass(workEntry.tone))}>
+                    {heading}
+                  </span>
+                  {preview && <span className="text-muted-foreground/55"> - {preview}</span>}
+                </p>
+              </TooltipTrigger>
+              <TooltipPopup className="max-w-[min(720px,calc(100vw-2rem))]">
+                <p className="whitespace-pre-wrap wrap-break-word text-xs leading-5">
+                  {displayText}
+                </p>
+              </TooltipPopup>
+            </Tooltip>
+          )}
         </div>
       </div>
       {hasChangedFiles && !previewIsChangedFiles && (
         <div className="mt-1 flex flex-wrap gap-1 pl-6">
-          {workEntry.changedFiles?.slice(0, 4).map((filePath) => (
-            <span
-              key={`${workEntry.id}:${filePath}`}
-              className="rounded-md border border-border/55 bg-background/75 px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground/75"
-              title={filePath}
-            >
-              {filePath}
-            </span>
-          ))}
+          {workEntry.changedFiles?.slice(0, 4).map((filePath) => {
+            const displayPath = formatWorkspaceRelativePath(filePath, workspaceRoot);
+            return (
+              <span
+                key={`${workEntry.id}:${filePath}`}
+                className="rounded-md border border-border/55 bg-background/75 px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground/75"
+                title={displayPath}
+              >
+                {displayPath}
+              </span>
+            );
+          })}
           {(workEntry.changedFiles?.length ?? 0) > 4 && (
             <span className="px-1 text-[10px] text-muted-foreground/55">
               +{(workEntry.changedFiles?.length ?? 0) - 4}
diff --git a/apps/web/src/components/chat/MessagesTimeline.virtualization.browser.tsx b/apps/web/src/components/chat/MessagesTimeline.virtualization.browser.tsx
deleted file mode 100644
index be3cf5c67a8..00000000000
--- a/apps/web/src/components/chat/MessagesTimeline.virtualization.browser.tsx
+++ /dev/null
@@ -1,1071 +0,0 @@
-import "../../index.css";
-
-import { MessageId, type TurnId } from "@t3tools/contracts";
-import { page } from "vitest/browser";
-import { useCallback, useState, type ComponentProps } from "react";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { render } from "vitest-browser-react";
-
-import { deriveTimelineEntries, type WorkLogEntry } from "../../session-logic";
-import { type ChatMessage, type ProposedPlan, type TurnDiffSummary } from "../../types";
-import { MessagesTimeline } from "./MessagesTimeline";
-import {
-  deriveMessagesTimelineRows,
-  estimateMessagesTimelineRowHeight,
-} from "./MessagesTimeline.logic";
-
-const DEFAULT_VIEWPORT = {
-  width: 960,
-  height: 1_100,
-};
-const MARKDOWN_CWD = "/repo/project";
-const ACTIVE_THREAD_ENVIRONMENT_ID = "environment-local" as never;
-
-interface RowMeasurement {
-  actualHeightPx: number;
-  estimatedHeightPx: number;
-  timelineWidthPx: number;
-  virtualizerSizePx: number;
-  renderedInVirtualizedRegion: boolean;
-}
-
-interface VirtualizationScenario {
-  name: string;
-  targetRowId: string;
-  props: Omit<
-    ComponentProps<typeof MessagesTimeline>,
-    "scrollContainer" | "activeThreadEnvironmentId"
-  >;
-  maxEstimateDeltaPx: number;
-}
-
-interface VirtualizerSnapshot {
-  totalSize: number;
-  measurements: ReadonlyArray<{
-    id: string;
-    kind: string;
-    index: number;
-    size: number;
-    start: number;
-    end: number;
-  }>;
-}
-
-function MessagesTimelineBrowserHarness(
-  props: Omit<
-    ComponentProps<typeof MessagesTimeline>,
-    "scrollContainer" | "activeThreadEnvironmentId"
-  >,
-) {
-  const [scrollContainer, setScrollContainer] = useState<HTMLDivElement | null>(null);
-  const [expandedWorkGroups, setExpandedWorkGroups] = useState<Record<string, boolean>>(
-    () => props.expandedWorkGroups,
-  );
-  const [changedFilesExpandedByTurnId, setChangedFilesExpandedByTurnId] = useState<
-    Record<string, boolean>
-  >(() => props.changedFilesExpandedByTurnId);
-  const handleToggleWorkGroup = useCallback(
-    (groupId: string) => {
-      setExpandedWorkGroups((current) => ({
-        ...current,
-        [groupId]: !(current[groupId] ?? false),
-      }));
-      props.onToggleWorkGroup(groupId);
-    },
-    [props],
-  );
-  const handleSetChangedFilesExpanded = useCallback(
-    (turnId: TurnId, expanded: boolean) => {
-      setChangedFilesExpandedByTurnId((current) => ({
-        ...current,
-        [turnId]: expanded,
-      }));
-      props.onSetChangedFilesExpanded(turnId, expanded);
-    },
-    [props],
-  );
-
-  return (
-    <div
-      ref={setScrollContainer}
-      data-testid="messages-timeline-scroll-container"
-      className="h-full overflow-y-auto overscroll-y-contain"
-    >
-      <MessagesTimeline
-        {...props}
-        activeThreadEnvironmentId={ACTIVE_THREAD_ENVIRONMENT_ID}
-        scrollContainer={scrollContainer}
-        expandedWorkGroups={expandedWorkGroups}
-        onToggleWorkGroup={handleToggleWorkGroup}
-        changedFilesExpandedByTurnId={changedFilesExpandedByTurnId}
-        onSetChangedFilesExpanded={handleSetChangedFilesExpanded}
-      />
-    </div>
-  );
-}
-
-function isoAt(offsetSeconds: number): string {
-  return new Date(Date.UTC(2026, 2, 17, 19, 12, 28) + offsetSeconds * 1_000).toISOString();
-}
-
-function createMessage(input: {
-  id: string;
-  role: ChatMessage["role"];
-  text: string;
-  offsetSeconds: number;
-  attachments?: ChatMessage["attachments"];
-}): ChatMessage {
-  return {
-    id: MessageId.make(input.id),
-    role: input.role,
-    text: input.text,
-    ...(input.attachments ? { attachments: input.attachments } : {}),
-    createdAt: isoAt(input.offsetSeconds),
-    ...(input.role === "assistant" ? { completedAt: isoAt(input.offsetSeconds + 1) } : {}),
-    streaming: false,
-  };
-}
-
-function createToolWorkEntry(input: {
-  id: string;
-  offsetSeconds: number;
-  label?: string;
-  detail?: string;
-}): WorkLogEntry {
-  return {
-    id: input.id,
-    createdAt: isoAt(input.offsetSeconds),
-    label: input.label ?? "exec_command completed",
-    ...(input.detail ? { detail: input.detail } : {}),
-    tone: "tool",
-    toolTitle: "exec_command",
-  };
-}
-
-function createPlan(input: {
-  id: string;
-  offsetSeconds: number;
-  planMarkdown: string;
-}): ProposedPlan {
-  return {
-    id: input.id as ProposedPlan["id"],
-    turnId: null,
-    planMarkdown: input.planMarkdown,
-    implementedAt: null,
-    implementationThreadId: null,
-    createdAt: isoAt(input.offsetSeconds),
-    updatedAt: isoAt(input.offsetSeconds + 1),
-  };
-}
-
-function createBaseTimelineProps(input: {
-  messages?: ChatMessage[];
-  proposedPlans?: ProposedPlan[];
-  workEntries?: WorkLogEntry[];
-  expandedWorkGroups?: Record<string, boolean>;
-  completionDividerBeforeEntryId?: string | null;
-  turnDiffSummaryByAssistantMessageId?: Map<MessageId, TurnDiffSummary>;
-  onVirtualizerSnapshot?: ComponentProps<typeof MessagesTimeline>["onVirtualizerSnapshot"];
-}): Omit<ComponentProps<typeof MessagesTimeline>, "scrollContainer" | "activeThreadEnvironmentId"> {
-  return {
-    hasMessages: true,
-    isWorking: false,
-    activeTurnInProgress: false,
-    activeTurnStartedAt: null,
-    timelineEntries: deriveTimelineEntries(
-      input.messages ?? [],
-      input.proposedPlans ?? [],
-      input.workEntries ?? [],
-    ),
-    completionDividerBeforeEntryId: input.completionDividerBeforeEntryId ?? null,
-    completionSummary: null,
-    turnDiffSummaryByAssistantMessageId: input.turnDiffSummaryByAssistantMessageId ?? new Map(),
-    nowIso: isoAt(10_000),
-    expandedWorkGroups: input.expandedWorkGroups ?? {},
-    onToggleWorkGroup: () => {},
-    changedFilesExpandedByTurnId: {},
-    onSetChangedFilesExpanded: () => {},
-    onOpenTurnDiff: () => {},
-    revertTurnCountByUserMessageId: new Map(),
-    onRevertUserMessage: () => {},
-    isRevertingCheckpoint: false,
-    onImageExpand: () => {},
-    markdownCwd: MARKDOWN_CWD,
-    resolvedTheme: "light",
-    timestampFormat: "locale",
-    workspaceRoot: MARKDOWN_CWD,
-    ...(input.onVirtualizerSnapshot ? { onVirtualizerSnapshot: input.onVirtualizerSnapshot } : {}),
-  };
-}
-
-function createFillerMessages(input: {
-  prefix: string;
-  startOffsetSeconds: number;
-  pairCount: number;
-}): ChatMessage[] {
-  const messages: ChatMessage[] = [];
-  for (let index = 0; index < input.pairCount; index += 1) {
-    const baseOffset = input.startOffsetSeconds + index * 4;
-    messages.push(
-      createMessage({
-        id: `${input.prefix}-user-${index}`,
-        role: "user",
-        text: `filler user message ${index}`,
-        offsetSeconds: baseOffset,
-      }),
-    );
-    messages.push(
-      createMessage({
-        id: `${input.prefix}-assistant-${index}`,
-        role: "assistant",
-        text: `filler assistant message ${index}`,
-        offsetSeconds: baseOffset + 1,
-      }),
-    );
-  }
-  return messages;
-}
-
-function createChangedFilesSummary(
-  targetMessageId: MessageId,
-  files: TurnDiffSummary["files"],
-): Map<MessageId, TurnDiffSummary> {
-  return new Map([
-    [
-      targetMessageId,
-      {
-        turnId: "turn-changed-files" as TurnId,
-        completedAt: isoAt(10),
-        assistantMessageId: targetMessageId,
-        files,
-      },
-    ],
-  ]);
-}
-
-function createChangedFilesScenario(input: {
-  name: string;
-  rowId: string;
-  files: TurnDiffSummary["files"];
-  maxEstimateDeltaPx?: number;
-}): VirtualizationScenario {
-  const beforeMessages = createFillerMessages({
-    prefix: `${input.rowId}-before`,
-    startOffsetSeconds: 0,
-    pairCount: 2,
-  });
-  const afterMessages = createFillerMessages({
-    prefix: `${input.rowId}-after`,
-    startOffsetSeconds: 40,
-    pairCount: 8,
-  });
-  const changedFilesMessage = createMessage({
-    id: input.rowId,
-    role: "assistant",
-    text: "Validation passed on the merged tree.",
-    offsetSeconds: 12,
-  });
-
-  return {
-    name: input.name,
-    targetRowId: changedFilesMessage.id,
-    props: createBaseTimelineProps({
-      messages: [...beforeMessages, changedFilesMessage, ...afterMessages],
-      turnDiffSummaryByAssistantMessageId: createChangedFilesSummary(
-        changedFilesMessage.id,
-        input.files,
-      ),
-    }),
-    maxEstimateDeltaPx: input.maxEstimateDeltaPx ?? 72,
-  };
-}
-
-function createAssistantMessageScenario(input: {
-  name: string;
-  rowId: string;
-  text: string;
-  maxEstimateDeltaPx?: number;
-}): VirtualizationScenario {
-  const beforeMessages = createFillerMessages({
-    prefix: `${input.rowId}-before`,
-    startOffsetSeconds: 0,
-    pairCount: 2,
-  });
-  const afterMessages = createFillerMessages({
-    prefix: `${input.rowId}-after`,
-    startOffsetSeconds: 40,
-    pairCount: 8,
-  });
-  const assistantMessage = createMessage({
-    id: input.rowId,
-    role: "assistant",
-    text: input.text,
-    offsetSeconds: 12,
-  });
-
-  return {
-    name: input.name,
-    targetRowId: assistantMessage.id,
-    props: createBaseTimelineProps({
-      messages: [...beforeMessages, assistantMessage, ...afterMessages],
-    }),
-    maxEstimateDeltaPx: input.maxEstimateDeltaPx ?? 16,
-  };
-}
-
-function buildStaticScenarios(): VirtualizationScenario[] {
-  const beforeMessages = createFillerMessages({
-    prefix: "before",
-    startOffsetSeconds: 0,
-    pairCount: 2,
-  });
-  const afterMessages = createFillerMessages({
-    prefix: "after",
-    startOffsetSeconds: 40,
-    pairCount: 8,
-  });
-
-  const longUserMessage = createMessage({
-    id: "target-user-long",
-    role: "user",
-    text: "x".repeat(3_200),
-    offsetSeconds: 12,
-  });
-  const workEntries = Array.from({ length: 4 }, (_, index) =>
-    createToolWorkEntry({
-      id: `target-work-${index}`,
-      offsetSeconds: 12 + index,
-      detail: `tool output line ${index + 1}`,
-    }),
-  );
-  const moderatePlan = createPlan({
-    id: "target-plan",
-    offsetSeconds: 12,
-    planMarkdown: [
-      "# Stabilize virtualization",
-      "",
-      "- Gather baseline measurements",
-      "- Add browser harness coverage",
-      "- Compare estimated and rendered heights",
-      "- Fix the broken rows without broad refactors",
-      "- Re-run lint and typecheck",
-    ].join("\n"),
-  });
-  return [
-    {
-      name: "long user message",
-      targetRowId: longUserMessage.id,
-      props: createBaseTimelineProps({
-        messages: [...beforeMessages, longUserMessage, ...afterMessages],
-      }),
-      maxEstimateDeltaPx: 56,
-    },
-    {
-      name: "grouped work log row",
-      targetRowId: workEntries[0]!.id,
-      props: createBaseTimelineProps({
-        messages: [...beforeMessages, ...afterMessages],
-        workEntries,
-      }),
-      maxEstimateDeltaPx: 56,
-    },
-    {
-      name: "expanded grouped work log row with show more enabled",
-      targetRowId: "target-work-expanded-0",
-      props: createBaseTimelineProps({
-        messages: [...beforeMessages, ...afterMessages],
-        workEntries: Array.from({ length: 10 }, (_, index) =>
-          createToolWorkEntry({
-            id: `target-work-expanded-${index}`,
-            offsetSeconds: 12 + index,
-            detail: `tool output line ${index + 1}`,
-          }),
-        ),
-        expandedWorkGroups: {
-          "target-work-expanded-0": true,
-        },
-      }),
-      maxEstimateDeltaPx: 72,
-    },
-    {
-      name: "proposed plan row",
-      targetRowId: moderatePlan.id,
-      props: createBaseTimelineProps({
-        messages: [...beforeMessages, ...afterMessages],
-        proposedPlans: [moderatePlan],
-      }),
-      maxEstimateDeltaPx: 96,
-    },
-    createAssistantMessageScenario({
-      name: "assistant single-paragraph row with plain prose",
-      rowId: "target-assistant-plain-prose",
-      text: [
-        "The host is still expanding to content somewhere in the grid layout.",
-        "I'm stripping it back further to a plain block container so the test width",
-        "is actually the timeline width.",
-      ].join(" "),
-    }),
-    createAssistantMessageScenario({
-      name: "assistant single-paragraph row with inline code",
-      rowId: "target-assistant-inline-code",
-      text: [
-        "Typecheck found one exact-optional-property issue in the browser harness:",
-        "I was always passing `onVirtualizerSnapshot`, including `undefined`.",
-        "I'm tightening that object construction and rerunning the checks.",
-      ].join(" "),
-      maxEstimateDeltaPx: 28,
-    }),
-    createChangedFilesScenario({
-      name: "assistant changed-files row with a compacted single-chain directory",
-      rowId: "target-assistant-changed-files-single-chain",
-      files: [
-        { path: "apps/web/src/components/chat/ChangedFilesTree.tsx", additions: 37, deletions: 45 },
-        {
-          path: "apps/web/src/components/chat/ChangedFilesTree.test.tsx",
-          additions: 0,
-          deletions: 26,
-        },
-      ],
-    }),
-    createChangedFilesScenario({
-      name: "assistant changed-files row with a branch after compaction",
-      rowId: "target-assistant-changed-files-branch-point",
-      files: [
-        { path: "apps/server/src/git/Layers/GitCore.ts", additions: 44, deletions: 38 },
-        { path: "apps/server/src/git/Layers/GitCore.test.ts", additions: 18, deletions: 9 },
-        {
-          path: "apps/server/src/provider/Layers/CodexAdapter.ts",
-          additions: 27,
-          deletions: 8,
-        },
-        {
-          path: "apps/server/src/provider/Layers/CodexAdapter.test.ts",
-          additions: 36,
-          deletions: 0,
-        },
-      ],
-    }),
-    createChangedFilesScenario({
-      name: "assistant changed-files row with mixed root and nested entries",
-      rowId: "target-assistant-changed-files-mixed-root",
-      files: [
-        { path: "README.md", additions: 5, deletions: 1 },
-        { path: "packages/contracts/src/orchestration.ts", additions: 13, deletions: 3 },
-        { path: "packages/shared/src/git.ts", additions: 8, deletions: 2 },
-      ],
-    }),
-  ];
-}
-
-async function nextFrame(): Promise<void> {
-  await new Promise<void>((resolve) => {
-    window.requestAnimationFrame(() => resolve());
-  });
-}
-
-async function waitForLayout(): Promise<void> {
-  await nextFrame();
-  await nextFrame();
-  await nextFrame();
-}
-
-async function setViewport(viewport: { width: number; height: number }): Promise<void> {
-  await page.viewport(viewport.width, viewport.height);
-  await waitForLayout();
-}
-
-async function waitForProductionStyles(): Promise<void> {
-  await vi.waitFor(
-    () => {
-      expect(
-        getComputedStyle(document.documentElement).getPropertyValue("--background").trim(),
-      ).not.toBe("");
-      expect(getComputedStyle(document.body).marginTop).toBe("0px");
-    },
-    { timeout: 4_000, interval: 16 },
-  );
-}
-
-async function waitForElement<T extends Element>(
-  query: () => T | null,
-  errorMessage: string,
-): Promise<T> {
-  let element: T | null = null;
-  await vi.waitFor(
-    () => {
-      element = query();
-      expect(element, errorMessage).toBeTruthy();
-    },
-    { timeout: 8_000, interval: 16 },
-  );
-  if (!element) {
-    throw new Error(errorMessage);
-  }
-  return element;
-}
-
-async function measureTimelineRow(input: {
-  host: HTMLElement;
-  props: Omit<
-    ComponentProps<typeof MessagesTimeline>,
-    "scrollContainer" | "activeThreadEnvironmentId"
-  >;
-  targetRowId: string;
-}): Promise<RowMeasurement> {
-  const scrollContainer = await waitForElement(
-    () =>
-      input.host.querySelector<HTMLDivElement>(
-        '[data-testid="messages-timeline-scroll-container"]',
-      ),
-    "Unable to find MessagesTimeline scroll container.",
-  );
-
-  const rowSelector = `[data-timeline-row-id="${input.targetRowId}"]`;
-  const virtualRowSelector = `[data-virtual-row-id="${input.targetRowId}"]`;
-
-  let timelineWidthPx = 0;
-  let actualHeightPx = 0;
-  let virtualizerSizePx = 0;
-  let renderedInVirtualizedRegion = false;
-
-  await vi.waitFor(
-    async () => {
-      scrollContainer.scrollTop = 0;
-      scrollContainer.dispatchEvent(new Event("scroll"));
-      await waitForLayout();
-
-      const rowElement = input.host.querySelector<HTMLElement>(rowSelector);
-      const virtualRowElement = input.host.querySelector<HTMLElement>(virtualRowSelector);
-      const timelineRoot = input.host.querySelector<HTMLElement>('[data-timeline-root="true"]');
-
-      expect(rowElement, "Unable to locate target timeline row.").toBeTruthy();
-      expect(virtualRowElement, "Unable to locate target virtualized wrapper.").toBeTruthy();
-      expect(timelineRoot, "Unable to locate MessagesTimeline root.").toBeTruthy();
-
-      timelineWidthPx = timelineRoot!.getBoundingClientRect().width;
-      actualHeightPx = rowElement!.getBoundingClientRect().height;
-      virtualizerSizePx = Number.parseFloat(virtualRowElement!.dataset.virtualRowSize ?? "0");
-      renderedInVirtualizedRegion = virtualRowElement!.hasAttribute("data-index");
-
-      expect(timelineWidthPx).toBeGreaterThan(0);
-      expect(actualHeightPx).toBeGreaterThan(0);
-      expect(virtualizerSizePx).toBeGreaterThan(0);
-      expect(renderedInVirtualizedRegion).toBe(true);
-    },
-    { timeout: 8_000, interval: 16 },
-  );
-
-  const rows = deriveMessagesTimelineRows({
-    timelineEntries: input.props.timelineEntries,
-    completionDividerBeforeEntryId: input.props.completionDividerBeforeEntryId,
-    isWorking: input.props.isWorking,
-    activeTurnStartedAt: input.props.activeTurnStartedAt,
-  });
-  const targetRow = rows.find((row) => row.id === input.targetRowId);
-  expect(targetRow, `Unable to derive target row ${input.targetRowId}.`).toBeTruthy();
-
-  return {
-    actualHeightPx,
-    estimatedHeightPx: estimateMessagesTimelineRowHeight(targetRow!, {
-      expandedWorkGroups: input.props.expandedWorkGroups,
-      timelineWidthPx,
-      turnDiffSummaryByAssistantMessageId: input.props.turnDiffSummaryByAssistantMessageId,
-    }),
-    timelineWidthPx,
-    virtualizerSizePx,
-    renderedInVirtualizedRegion,
-  };
-}
-
-async function mountMessagesTimeline(input: {
-  props: Omit<
-    ComponentProps<typeof MessagesTimeline>,
-    "scrollContainer" | "activeThreadEnvironmentId"
-  >;
-  viewport?: { width: number; height: number };
-}) {
-  const viewport = input.viewport ?? DEFAULT_VIEWPORT;
-  await setViewport(viewport);
-  await waitForProductionStyles();
-
-  const host = document.createElement("div");
-  host.style.width = `${viewport.width}px`;
-  host.style.minWidth = `${viewport.width}px`;
-  host.style.maxWidth = `${viewport.width}px`;
-  host.style.height = `${viewport.height}px`;
-  host.style.minHeight = `${viewport.height}px`;
-  host.style.maxHeight = `${viewport.height}px`;
-  host.style.display = "block";
-  host.style.overflow = "hidden";
-  document.body.append(host);
-
-  const screen = await render(<MessagesTimelineBrowserHarness {...input.props} />, {
-    container: host,
-  });
-  await waitForLayout();
-
-  return {
-    host,
-    rerender: async (
-      nextProps: Omit<
-        ComponentProps<typeof MessagesTimeline>,
-        "scrollContainer" | "activeThreadEnvironmentId"
-      >,
-    ) => {
-      await screen.rerender(<MessagesTimelineBrowserHarness {...nextProps} />);
-      await waitForLayout();
-    },
-    setContainerSize: async (nextViewport: { width: number; height: number }) => {
-      await setViewport(nextViewport);
-      host.style.width = `${nextViewport.width}px`;
-      host.style.minWidth = `${nextViewport.width}px`;
-      host.style.maxWidth = `${nextViewport.width}px`;
-      host.style.height = `${nextViewport.height}px`;
-      host.style.minHeight = `${nextViewport.height}px`;
-      host.style.maxHeight = `${nextViewport.height}px`;
-      await waitForLayout();
-    },
-    cleanup: async () => {
-      await screen.unmount();
-      host.remove();
-    },
-  };
-}
-
-async function measureRenderedRowActualHeight(input: {
-  host: HTMLElement;
-  targetRowId: string;
-}): Promise<number> {
-  const rowElement = await waitForElement(
-    () => input.host.querySelector<HTMLElement>(`[data-timeline-row-id="${input.targetRowId}"]`),
-    `Unable to locate rendered row ${input.targetRowId}.`,
-  );
-  return rowElement.getBoundingClientRect().height;
-}
-
-describe("MessagesTimeline virtualization harness", () => {
-  beforeEach(async () => {
-    document.body.innerHTML = "";
-    await setViewport(DEFAULT_VIEWPORT);
-  });
-
-  afterEach(() => {
-    document.body.innerHTML = "";
-  });
-
-  it.each(buildStaticScenarios())("keeps the $name estimate within tolerance", async (scenario) => {
-    const mounted = await mountMessagesTimeline({ props: scenario.props });
-
-    try {
-      const measurement = await measureTimelineRow({
-        host: mounted.host,
-        props: scenario.props,
-        targetRowId: scenario.targetRowId,
-      });
-
-      expect(
-        Math.abs(measurement.actualHeightPx - measurement.estimatedHeightPx),
-        `estimate delta for ${scenario.name}`,
-      ).toBeLessThanOrEqual(scenario.maxEstimateDeltaPx);
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-
-  it("keeps the changed-files row virtualizer size in sync after collapsing directories", async () => {
-    const beforeMessages = createFillerMessages({
-      prefix: "before-collapse",
-      startOffsetSeconds: 0,
-      pairCount: 2,
-    });
-    const afterMessages = createFillerMessages({
-      prefix: "after-collapse",
-      startOffsetSeconds: 40,
-      pairCount: 8,
-    });
-    const targetMessage = createMessage({
-      id: "target-assistant-collapse",
-      role: "assistant",
-      text: "Validation passed on the merged tree.",
-      offsetSeconds: 12,
-    });
-    const props = createBaseTimelineProps({
-      messages: [...beforeMessages, targetMessage, ...afterMessages],
-      turnDiffSummaryByAssistantMessageId: createChangedFilesSummary(targetMessage.id, [
-        { path: ".plans/effect-atom.md", additions: 89, deletions: 0 },
-        {
-          path: "apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts",
-          additions: 4,
-          deletions: 3,
-        },
-        {
-          path: "apps/server/src/checkpointing/Layers/CheckpointStore.ts",
-          additions: 131,
-          deletions: 128,
-        },
-        {
-          path: "apps/server/src/checkpointing/Layers/CheckpointStore.test.ts",
-          additions: 1,
-          deletions: 1,
-        },
-        { path: "apps/server/src/checkpointing/Errors.ts", additions: 1, deletions: 1 },
-        {
-          path: "apps/server/src/git/Layers/ClaudeTextGeneration.ts",
-          additions: 106,
-          deletions: 112,
-        },
-        { path: "apps/server/src/git/Layers/GitCore.ts", additions: 44, deletions: 38 },
-        { path: "apps/server/src/git/Layers/GitCore.test.ts", additions: 18, deletions: 9 },
-        {
-          path: "apps/web/src/components/chat/MessagesTimeline.tsx",
-          additions: 52,
-          deletions: 7,
-        },
-        {
-          path: "apps/web/src/components/chat/ChangedFilesTree.tsx",
-          additions: 32,
-          deletions: 4,
-        },
-        { path: "packages/contracts/src/orchestration.ts", additions: 13, deletions: 3 },
-        { path: "packages/shared/src/git.ts", additions: 8, deletions: 2 },
-      ]),
-    });
-    const mounted = await mountMessagesTimeline({
-      props,
-      viewport: { width: 320, height: 700 },
-    });
-
-    try {
-      const beforeCollapse = await measureTimelineRow({
-        host: mounted.host,
-        props,
-        targetRowId: targetMessage.id,
-      });
-      const targetRowElement = mounted.host.querySelector<HTMLElement>(
-        `[data-timeline-row-id="${targetMessage.id}"]`,
-      );
-      expect(targetRowElement, "Unable to locate target changed-files row.").toBeTruthy();
-
-      const collapseAllButton =
-        Array.from(targetRowElement!.querySelectorAll<HTMLButtonElement>("button")).find(
-          (button) => button.textContent?.trim() === "Collapse all",
-        ) ?? null;
-      expect(collapseAllButton, 'Unable to find "Collapse all" button.').toBeTruthy();
-
-      collapseAllButton!.click();
-
-      await vi.waitFor(
-        async () => {
-          const afterCollapse = await measureTimelineRow({
-            host: mounted.host,
-            props,
-            targetRowId: targetMessage.id,
-          });
-          expect(afterCollapse.actualHeightPx).toBeLessThan(beforeCollapse.actualHeightPx - 24);
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-
-      const afterCollapse = await measureTimelineRow({
-        host: mounted.host,
-        props,
-        targetRowId: targetMessage.id,
-      });
-      expect(
-        Math.abs(afterCollapse.actualHeightPx - afterCollapse.virtualizerSizePx),
-      ).toBeLessThanOrEqual(8);
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-
-  it("keeps the work-log row virtualizer size in sync after show more expands the group", async () => {
-    const beforeMessages = createFillerMessages({
-      prefix: "before-worklog-expand",
-      startOffsetSeconds: 0,
-      pairCount: 2,
-    });
-    const afterMessages = createFillerMessages({
-      prefix: "after-worklog-expand",
-      startOffsetSeconds: 40,
-      pairCount: 8,
-    });
-    const workEntries = Array.from({ length: 10 }, (_, index) =>
-      createToolWorkEntry({
-        id: `target-work-toggle-${index}`,
-        offsetSeconds: 12 + index,
-        detail: `tool output line ${index + 1}`,
-      }),
-    );
-    const props = createBaseTimelineProps({
-      messages: [...beforeMessages, ...afterMessages],
-      workEntries,
-    });
-    const mounted = await mountMessagesTimeline({ props });
-
-    try {
-      const beforeExpand = await measureTimelineRow({
-        host: mounted.host,
-        props,
-        targetRowId: workEntries[0]!.id,
-      });
-      const targetRowElement = mounted.host.querySelector<HTMLElement>(
-        `[data-timeline-row-id="${workEntries[0]!.id}"]`,
-      );
-      expect(targetRowElement, "Unable to locate target work-log row.").toBeTruthy();
-
-      const showMoreButton =
-        Array.from(targetRowElement!.querySelectorAll<HTMLButtonElement>("button")).find((button) =>
-          button.textContent?.includes("Show 4 more"),
-        ) ?? null;
-      expect(showMoreButton, 'Unable to find "Show more" button.').toBeTruthy();
-
-      showMoreButton!.click();
-
-      await vi.waitFor(
-        async () => {
-          const afterExpand = await measureTimelineRow({
-            host: mounted.host,
-            props,
-            targetRowId: workEntries[0]!.id,
-          });
-          expect(afterExpand.actualHeightPx).toBeGreaterThan(beforeExpand.actualHeightPx + 72);
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-
-      const afterExpand = await measureTimelineRow({
-        host: mounted.host,
-        props,
-        targetRowId: workEntries[0]!.id,
-      });
-      expect(
-        Math.abs(afterExpand.actualHeightPx - afterExpand.virtualizerSizePx),
-      ).toBeLessThanOrEqual(8);
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-
-  it("preserves measured tail row heights when rows transition into virtualization", async () => {
-    const beforeMessages = createFillerMessages({
-      prefix: "tail-transition-before",
-      startOffsetSeconds: 0,
-      pairCount: 1,
-    });
-    const afterMessages = createFillerMessages({
-      prefix: "tail-transition-after",
-      startOffsetSeconds: 40,
-      pairCount: 3,
-    });
-    const targetMessage = createMessage({
-      id: "target-tail-transition",
-      role: "assistant",
-      text: "Validation passed on the merged tree.",
-      offsetSeconds: 12,
-    });
-    let latestSnapshot: VirtualizerSnapshot | null = null;
-    const initialProps = createBaseTimelineProps({
-      messages: [...beforeMessages, targetMessage, ...afterMessages],
-      turnDiffSummaryByAssistantMessageId: createChangedFilesSummary(targetMessage.id, [
-        { path: ".plans/effect-atom.md", additions: 89, deletions: 0 },
-        {
-          path: "apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts",
-          additions: 4,
-          deletions: 3,
-        },
-        {
-          path: "apps/server/src/checkpointing/Layers/CheckpointStore.ts",
-          additions: 131,
-          deletions: 128,
-        },
-        {
-          path: "apps/server/src/checkpointing/Layers/CheckpointStore.test.ts",
-          additions: 1,
-          deletions: 1,
-        },
-        { path: "apps/server/src/checkpointing/Errors.ts", additions: 1, deletions: 1 },
-        {
-          path: "apps/server/src/git/Layers/ClaudeTextGeneration.ts",
-          additions: 106,
-          deletions: 112,
-        },
-        { path: "apps/server/src/git/Layers/GitCore.ts", additions: 44, deletions: 38 },
-        { path: "apps/server/src/git/Layers/GitCore.test.ts", additions: 18, deletions: 9 },
-        {
-          path: "apps/web/src/components/chat/MessagesTimeline.tsx",
-          additions: 52,
-          deletions: 7,
-        },
-        {
-          path: "apps/web/src/components/chat/ChangedFilesTree.tsx",
-          additions: 32,
-          deletions: 4,
-        },
-        { path: "packages/contracts/src/orchestration.ts", additions: 13, deletions: 3 },
-        { path: "packages/shared/src/git.ts", additions: 8, deletions: 2 },
-      ]),
-      onVirtualizerSnapshot: (snapshot) => {
-        latestSnapshot = {
-          totalSize: snapshot.totalSize,
-          measurements: snapshot.measurements,
-        };
-      },
-    });
-
-    const mounted = await mountMessagesTimeline({ props: initialProps });
-
-    try {
-      const initiallyRenderedHeight = await measureRenderedRowActualHeight({
-        host: mounted.host,
-        targetRowId: targetMessage.id,
-      });
-
-      const appendedProps = createBaseTimelineProps({
-        messages: [
-          ...beforeMessages,
-          targetMessage,
-          ...afterMessages,
-          ...createFillerMessages({
-            prefix: "tail-transition-extra",
-            startOffsetSeconds: 120,
-            pairCount: 8,
-          }),
-        ],
-        turnDiffSummaryByAssistantMessageId: initialProps.turnDiffSummaryByAssistantMessageId,
-        onVirtualizerSnapshot: initialProps.onVirtualizerSnapshot,
-      });
-      await mounted.rerender(appendedProps);
-
-      const scrollContainer = await waitForElement(
-        () =>
-          mounted.host.querySelector<HTMLDivElement>(
-            '[data-testid="messages-timeline-scroll-container"]',
-          ),
-        "Unable to find MessagesTimeline scroll container.",
-      );
-      scrollContainer.scrollTop = scrollContainer.scrollHeight;
-      scrollContainer.dispatchEvent(new Event("scroll"));
-      await waitForLayout();
-
-      await vi.waitFor(
-        () => {
-          const measurement = latestSnapshot?.measurements.find(
-            (entry) => entry.id === targetMessage.id,
-          );
-          expect(
-            measurement,
-            "Expected target row to transition into virtualizer cache.",
-          ).toBeTruthy();
-          expect(Math.abs((measurement?.size ?? 0) - initiallyRenderedHeight)).toBeLessThanOrEqual(
-            8,
-          );
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-
-  it("preserves measured tail image row heights when rows transition into virtualization", async () => {
-    const beforeMessages = createFillerMessages({
-      prefix: "tail-image-before",
-      startOffsetSeconds: 0,
-      pairCount: 1,
-    });
-    const afterMessages = createFillerMessages({
-      prefix: "tail-image-after",
-      startOffsetSeconds: 40,
-      pairCount: 3,
-    });
-    const targetMessage = createMessage({
-      id: "target-tail-image-transition",
-      role: "user",
-      text: "Here is a narrow screenshot.",
-      offsetSeconds: 12,
-      attachments: [
-        {
-          type: "image",
-          id: "target-tail-image",
-          name: "narrow.svg",
-          mimeType: "image/svg+xml",
-          sizeBytes: 512,
-          previewUrl:
-            "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='240' height='72'%3E%3Crect width='240' height='72' fill='%23dbeafe'/%3E%3C/svg%3E",
-        },
-      ],
-    });
-    let latestSnapshot: VirtualizerSnapshot | null = null;
-    const initialProps = createBaseTimelineProps({
-      messages: [...beforeMessages, targetMessage, ...afterMessages],
-      onVirtualizerSnapshot: (snapshot) => {
-        latestSnapshot = {
-          totalSize: snapshot.totalSize,
-          measurements: snapshot.measurements,
-        };
-      },
-    });
-    const mounted = await mountMessagesTimeline({ props: initialProps });
-
-    try {
-      await vi.waitFor(
-        () => {
-          const image = mounted.host.querySelector<HTMLImageElement>(
-            `[data-timeline-row-id="${targetMessage.id}"] img`,
-          );
-          expect(image?.naturalHeight ?? 0).toBeGreaterThan(0);
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-
-      const initiallyRenderedHeight = await measureRenderedRowActualHeight({
-        host: mounted.host,
-        targetRowId: targetMessage.id,
-      });
-      const appendedProps = createBaseTimelineProps({
-        messages: [
-          ...beforeMessages,
-          targetMessage,
-          ...afterMessages,
-          ...createFillerMessages({
-            prefix: "tail-image-extra",
-            startOffsetSeconds: 120,
-            pairCount: 8,
-          }),
-        ],
-        onVirtualizerSnapshot: initialProps.onVirtualizerSnapshot,
-      });
-      await mounted.rerender(appendedProps);
-
-      const scrollContainer = await waitForElement(
-        () =>
-          mounted.host.querySelector<HTMLDivElement>(
-            '[data-testid="messages-timeline-scroll-container"]',
-          ),
-        "Unable to find MessagesTimeline scroll container.",
-      );
-      scrollContainer.scrollTop = scrollContainer.scrollHeight;
-      scrollContainer.dispatchEvent(new Event("scroll"));
-      await waitForLayout();
-
-      await vi.waitFor(
-        () => {
-          const measurement = latestSnapshot?.measurements.find(
-            (entry) => entry.id === targetMessage.id,
-          );
-          expect(
-            measurement,
-            "Expected target image row to transition into virtualizer cache.",
-          ).toBeTruthy();
-          expect(Math.abs((measurement?.size ?? 0) - initiallyRenderedHeight)).toBeLessThanOrEqual(
-            8,
-          );
-        },
-        { timeout: 8_000, interval: 16 },
-      );
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-});
diff --git a/apps/web/src/components/chat/ModelListRow.tsx b/apps/web/src/components/chat/ModelListRow.tsx
new file mode 100644
index 00000000000..064df338e46
--- /dev/null
+++ b/apps/web/src/components/chat/ModelListRow.tsx
@@ -0,0 +1,123 @@
+import { type ProviderDriverKind, type ProviderInstanceId } from "@t3tools/contracts";
+import { memo } from "react";
+import { StarIcon } from "lucide-react";
+import {
+  getDisplayModelName,
+  getTriggerDisplayModelLabel,
+  type ModelEsque,
+  PROVIDER_ICON_BY_PROVIDER,
+} from "./providerIconUtils";
+import { ComboboxItem } from "../ui/combobox";
+import { Kbd } from "../ui/kbd";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { cn } from "~/lib/utils";
+
+export const ModelListRow = memo(function ModelListRow(props: {
+  index: number;
+  model: ModelEsque;
+  /** Instance the model belongs to — the routing key used in combobox values. */
+  instanceId: ProviderInstanceId;
+  /** Driver kind of the instance — used for the provider icon glyph. */
+  driverKind: ProviderDriverKind;
+  /**
+   * Display name to show in the secondary line (provider footer). Usually
+   * the instance's configured `displayName` so custom instances like
+   * "Codex Personal" render with their user-authored label.
+   */
+  providerDisplayName: string;
+  providerAccentColor?: string | undefined;
+  isFavorite: boolean;
+  showProvider: boolean;
+  preferShortName?: boolean;
+  useTriggerLabel?: boolean;
+  showNewBadge?: boolean;
+  jumpLabel?: string | null;
+  onToggleFavorite: () => void;
+}) {
+  const ProviderIcon = PROVIDER_ICON_BY_PROVIDER[props.driverKind] ?? null;
+  const providerLabel = props.model.subProvider
+    ? `${props.providerDisplayName} · ${props.model.subProvider}`
+    : props.providerDisplayName;
+
+  return (
+    <ComboboxItem
+      hideIndicator
+      index={props.index}
+      value={`${props.instanceId}:${props.model.slug}`}
+      contentClassName="flex w-full items-start gap-2"
+      className={cn(
+        "w-full cursor-pointer rounded px-3 py-2 transition-colors group",
+        "data-highlighted:bg-muted data-selected:bg-accent data-selected:text-foreground",
+      )}
+    >
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <button
+              className="mt-0.5 shrink-0 cursor-pointer opacity-40 transition-opacity group-hover:opacity-100"
+              onClick={(event) => {
+                event.stopPropagation();
+                props.onToggleFavorite();
+              }}
+              onKeyDown={(event) => {
+                event.stopPropagation();
+              }}
+              type="button"
+              aria-label={props.isFavorite ? "Remove from favorites" : "Add to favorites"}
+            >
+              <StarIcon
+                className={cn("size-4", props.isFavorite && "fill-current text-yellow-500")}
+              />
+            </button>
+          }
+        />
+        <TooltipPopup side="top" align="center">
+          {props.isFavorite ? "Remove from favorites" : "Add to favorites"}
+        </TooltipPopup>
+      </Tooltip>
+
+      <div className="min-w-0 flex-1 text-left">
+        <div className="flex items-center justify-between gap-2 min-w-0">
+          <div className="text-xs font-medium leading-snug flex items-center gap-2 min-w-0">
+            <span className="truncate">
+              {props.useTriggerLabel
+                ? getTriggerDisplayModelLabel(props.model)
+                : getDisplayModelName(
+                    props.model,
+                    props.preferShortName ? { preferShortName: true } : undefined,
+                  )}
+            </span>
+            {props.showNewBadge ? (
+              <span
+                className="shrink-0 rounded border border-amber-500/35 bg-amber-500/15 px-0.5 py-px text-[10px] font-bold uppercase leading-none tracking-wide text-amber-800 dark:border-amber-400/30 dark:bg-amber-400/12 dark:text-amber-200"
+                aria-label="New model"
+              >
+                New
+              </span>
+            ) : null}
+          </div>
+          {props.jumpLabel ? (
+            <Kbd className="h-4 min-w-0 shrink-0 rounded-sm px-1.5 text-[10px]">
+              {props.jumpLabel}
+            </Kbd>
+          ) : null}
+        </div>
+        {props.showProvider && (
+          <div className="flex items-center gap-1 mt-0.5">
+            {ProviderIcon ? <ProviderIcon className="size-3 shrink-0" /> : null}
+            {props.providerAccentColor ? (
+              <span
+                className="size-1.5 shrink-0 rounded-full"
+                style={{ backgroundColor: props.providerAccentColor }}
+                aria-hidden
+              />
+            ) : null}
+            <span className="text-xs font-normal leading-snug text-muted-foreground/70 truncate">
+              {providerLabel}
+            </span>
+          </div>
+        )}
+      </div>
+    </ComboboxItem>
+  );
+});
diff --git a/apps/web/src/components/chat/ModelPickerContent.tsx b/apps/web/src/components/chat/ModelPickerContent.tsx
new file mode 100644
index 00000000000..c3468ef8c65
--- /dev/null
+++ b/apps/web/src/components/chat/ModelPickerContent.tsx
@@ -0,0 +1,649 @@
+import {
+  type ProviderInstanceId,
+  type ProviderDriverKind,
+  type ResolvedKeybindingsConfig,
+} from "@t3tools/contracts";
+import { resolveSelectableModel } from "@t3tools/shared/model";
+import { memo, useMemo, useState, useCallback, useEffect, useLayoutEffect, useRef } from "react";
+import { SearchIcon } from "lucide-react";
+import { ModelListRow } from "./ModelListRow";
+import { ModelPickerSidebar } from "./ModelPickerSidebar";
+import { isModelPickerNewModel } from "./modelPickerModelHighlights";
+import { buildModelPickerSearchText, scoreModelPickerSearch } from "./modelPickerSearch";
+import { Combobox, ComboboxEmpty, ComboboxInput, ComboboxList } from "../ui/combobox";
+import { ModelEsque, PROVIDER_ICON_BY_PROVIDER } from "./providerIconUtils";
+import {
+  modelPickerJumpCommandForIndex,
+  modelPickerJumpIndexFromCommand,
+  resolveShortcutCommand,
+  shortcutLabelForCommand,
+} from "../../keybindings";
+import { useSettings, useUpdateSettings } from "~/hooks/useSettings";
+import { cn } from "~/lib/utils";
+import { TooltipProvider } from "../ui/tooltip";
+import type { ProviderInstanceEntry } from "../../providerInstances";
+import { providerModelKey, sortProviderModelItems } from "../../modelOrdering";
+
+type ModelPickerItem = {
+  slug: string;
+  name: string;
+  shortName?: string;
+  subProvider?: string;
+  instanceId: ProviderInstanceId;
+  driverKind: ProviderDriverKind;
+  instanceDisplayName: string;
+  instanceAccentColor?: string | undefined;
+  continuationGroupKey?: string | undefined;
+};
+
+const EMPTY_MODEL_JUMP_LABELS = new Map<string, string>();
+
+// Split a `${instanceId}:${slug}` combobox key back into its pieces. Slugs
+// can contain colons (e.g. some vendor model ids), so we only split on the
+// first colon — anything after that is the slug.
+function splitInstanceModelKey(key: string): { instanceId: ProviderInstanceId; slug: string } {
+  const colonIndex = key.indexOf(":");
+  if (colonIndex === -1) {
+    return { instanceId: key as ProviderInstanceId, slug: "" };
+  }
+  return {
+    instanceId: key.slice(0, colonIndex) as ProviderInstanceId,
+    slug: key.slice(colonIndex + 1),
+  };
+}
+
+export const ModelPickerContent = memo(function ModelPickerContent(props: {
+  /** The instance currently selected in the composer (combobox "value"). */
+  activeInstanceId: ProviderInstanceId;
+  model: string;
+  /**
+   * When set, the picker is locked to the given driver kind — typically
+   * because the user is editing a previously-sent message and can't change
+   * which driver served the turn. Multiple instances of the same kind
+   * remain selectable (e.g. locked to `codex` still lets the user switch
+   * between the default Codex and a custom Codex Personal).
+   */
+  lockedProvider: ProviderDriverKind | null;
+  lockedContinuationGroupKey?: string | null;
+  /**
+   * All configured provider instances in display order. Used to render
+   * the sidebar (one button per instance) and to resolve display names
+   * for the locked-mode header.
+   */
+  instanceEntries: ReadonlyArray<ProviderInstanceEntry>;
+  keybindings?: ResolvedKeybindingsConfig;
+  /**
+   * Model options per instance. Keyed by `ProviderInstanceId` so the
+   * default Codex instance and any custom Codex instances each have their
+   * own list (custom instances typically start with the same built-in
+   * model set but are free to diverge via customModels).
+   */
+  modelOptionsByInstance: ReadonlyMap<ProviderInstanceId, ReadonlyArray<ModelEsque>>;
+  terminalOpen: boolean;
+  onRequestClose?: () => void;
+  onInstanceModelChange: (instanceId: ProviderInstanceId, model: string) => void;
+}) {
+  const {
+    keybindings: providedKeybindings,
+    modelOptionsByInstance,
+    instanceEntries,
+    onInstanceModelChange,
+  } = props;
+  const [searchQuery, setSearchQuery] = useState("");
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const listRegionRef = useRef<HTMLDivElement>(null);
+  const highlightedModelKeyRef = useRef<string | null>(null);
+  const favorites = useSettings((s) => s.favorites ?? []);
+  const [selectedInstanceId, setSelectedInstanceId] = useState<ProviderInstanceId | "favorites">(
+    () => {
+      if (props.lockedProvider !== null) {
+        // When locked, prime the sidebar to the currently-active instance
+        // so jumping into the picker keeps the focused instance visible.
+        return props.activeInstanceId;
+      }
+      return favorites.length > 0 ? "favorites" : props.activeInstanceId;
+    },
+  );
+  const keybindings = useMemo<ResolvedKeybindingsConfig>(
+    () => providedKeybindings ?? [],
+    [providedKeybindings],
+  );
+  const { updateSettings } = useUpdateSettings();
+
+  const focusSearchInput = useCallback(() => {
+    searchInputRef.current?.focus({ preventScroll: true });
+  }, []);
+
+  const handleSelectInstance = useCallback(
+    (instanceId: ProviderInstanceId | "favorites") => {
+      setSelectedInstanceId(instanceId);
+      window.requestAnimationFrame(() => {
+        focusSearchInput();
+      });
+    },
+    [focusSearchInput],
+  );
+
+  useLayoutEffect(() => {
+    focusSearchInput();
+    const frame = window.requestAnimationFrame(() => {
+      focusSearchInput();
+    });
+    const timeout = window.setTimeout(() => {
+      focusSearchInput();
+    }, 0);
+    return () => {
+      window.cancelAnimationFrame(frame);
+      window.clearTimeout(timeout);
+    };
+  }, [focusSearchInput]);
+
+  // Create a Set for efficient lookup. Favorites are keyed by
+  // `${instanceId}:${slug}`; the storage schema widened from ProviderDriverKind
+  // to ProviderInstanceId so pre-migration favorites keyed by driver slugs
+  // (e.g. `"codex:gpt-5"`) still resolve — the default instance id equals
+  // the driver slug.
+  const favoritesSet = useMemo(() => {
+    return new Set(favorites.map((fav) => providerModelKey(fav.provider, fav.model)));
+  }, [favorites]);
+
+  /**
+   * Lookup table keyed by `instanceId`. Used for display name + driver
+   * kind enrichment and for `ready`/enabled filtering before flattening
+   * models into the search list.
+   */
+  const entryByInstanceId = useMemo(
+    () => new Map(instanceEntries.map((entry) => [entry.instanceId, entry])),
+    [instanceEntries],
+  );
+  const matchesLockedProvider = useCallback(
+    (entry: Pick<ProviderInstanceEntry, "driverKind" | "continuationGroupKey">): boolean => {
+      if (props.lockedProvider === null) return true;
+      if (entry.driverKind !== props.lockedProvider) return false;
+      if (!props.lockedContinuationGroupKey) return true;
+      return entry.continuationGroupKey === props.lockedContinuationGroupKey;
+    },
+    [props.lockedContinuationGroupKey, props.lockedProvider],
+  );
+
+  const readyInstanceSet = useMemo(() => {
+    const ready = new Set<ProviderInstanceId>();
+    for (const entry of instanceEntries) {
+      if (entry.status === "ready") {
+        ready.add(entry.instanceId);
+      }
+    }
+    return ready;
+  }, [instanceEntries]);
+
+  // Flatten models into a searchable array. One pass over the
+  // instance-keyed map; each model carries its instance id + driver kind
+  // so the list row can render the right icon and display name without
+  // another lookup.
+  const flatModels = useMemo(() => {
+    const out: ModelPickerItem[] = [];
+    for (const [instanceId, models] of modelOptionsByInstance) {
+      const entry = entryByInstanceId.get(instanceId);
+      if (!entry) {
+        // Instance disappeared between renders (configuration change). Skip
+        // its models — stale options shouldn't appear in the picker.
+        continue;
+      }
+      if (!readyInstanceSet.has(instanceId)) {
+        continue;
+      }
+      for (const model of models) {
+        out.push({
+          slug: model.slug,
+          name: model.name,
+          ...(model.shortName ? { shortName: model.shortName } : {}),
+          ...(model.subProvider ? { subProvider: model.subProvider } : {}),
+          instanceId,
+          driverKind: entry.driverKind,
+          instanceDisplayName: entry.displayName,
+          ...(entry.accentColor ? { instanceAccentColor: entry.accentColor } : {}),
+          ...(entry.continuationGroupKey
+            ? { continuationGroupKey: entry.continuationGroupKey }
+            : {}),
+        });
+      }
+    }
+    return out;
+  }, [modelOptionsByInstance, entryByInstanceId, readyInstanceSet]);
+
+  const isLocked = props.lockedProvider !== null;
+  const isSearching = searchQuery.trim().length > 0;
+  const lockedInstanceEntries = useMemo(
+    () =>
+      props.lockedProvider ? instanceEntries.filter((entry) => matchesLockedProvider(entry)) : [],
+    [instanceEntries, matchesLockedProvider, props.lockedProvider],
+  );
+  const showLockedInstanceSidebar = isLocked && lockedInstanceEntries.length > 1;
+  const showSidebar = !isSearching && (!isLocked || showLockedInstanceSidebar);
+  const sidebarInstanceEntries = showLockedInstanceSidebar
+    ? lockedInstanceEntries
+    : instanceEntries;
+  const instanceOrder = useMemo(
+    () => instanceEntries.map((entry) => entry.instanceId),
+    [instanceEntries],
+  );
+
+  // Filter models based on search query and selected instance
+  const filteredModels = useMemo(() => {
+    let result = flatModels;
+
+    // Apply tokenized fuzzy search across the combined provider/model search fields.
+    if (searchQuery.trim()) {
+      const rankedMatches = result
+        .map((model) => ({
+          model,
+          score: scoreModelPickerSearch(
+            {
+              name: model.name,
+              ...(model.shortName ? { shortName: model.shortName } : {}),
+              ...(model.subProvider ? { subProvider: model.subProvider } : {}),
+              driverKind: model.driverKind,
+              providerDisplayName: model.instanceDisplayName,
+              isFavorite: favoritesSet.has(providerModelKey(model.instanceId, model.slug)),
+            },
+            searchQuery,
+          ),
+          isFavorite: favoritesSet.has(providerModelKey(model.instanceId, model.slug)),
+          tieBreaker: buildModelPickerSearchText({
+            name: model.name,
+            ...(model.shortName ? { shortName: model.shortName } : {}),
+            ...(model.subProvider ? { subProvider: model.subProvider } : {}),
+            driverKind: model.driverKind,
+            providerDisplayName: model.instanceDisplayName,
+          }),
+        }))
+        .filter(
+          (
+            rankedModel,
+          ): rankedModel is {
+            model: ModelPickerItem;
+            score: number;
+            isFavorite: boolean;
+            tieBreaker: string;
+          } => rankedModel.score !== null,
+        );
+
+      // When searching, we only respect locked provider (by driver kind),
+      // ignoring sidebar selection so account-scoped searches can find a
+      // model before the user chooses a specific instance rail item.
+      if (props.lockedProvider !== null) {
+        return rankedMatches
+          .filter((rankedModel) => matchesLockedProvider(rankedModel.model))
+          .toSorted((a, b) => {
+            const scoreDelta = a.score - b.score;
+            if (scoreDelta !== 0) {
+              return scoreDelta;
+            }
+            if (a.isFavorite !== b.isFavorite) {
+              return a.isFavorite ? -1 : 1;
+            }
+            return a.tieBreaker.localeCompare(b.tieBreaker);
+          })
+          .map((rankedModel) => rankedModel.model);
+      }
+
+      return rankedMatches
+        .toSorted((a, b) => {
+          const scoreDelta = a.score - b.score;
+          if (scoreDelta !== 0) {
+            return scoreDelta;
+          }
+          if (a.isFavorite !== b.isFavorite) {
+            return a.isFavorite ? -1 : 1;
+          }
+          return a.tieBreaker.localeCompare(b.tieBreaker);
+        })
+        .map((rankedModel) => rankedModel.model);
+    }
+
+    if (props.lockedProvider !== null) {
+      result = result.filter((m) => matchesLockedProvider(m));
+      if (showLockedInstanceSidebar) {
+        result = result.filter((m) => m.instanceId === selectedInstanceId);
+      }
+    } else if (selectedInstanceId === "favorites") {
+      result = result.filter((m) => favoritesSet.has(providerModelKey(m.instanceId, m.slug)));
+    } else {
+      result = result.filter((m) => m.instanceId === selectedInstanceId);
+    }
+
+    return sortProviderModelItems(result, {
+      favoriteModelKeys: favoritesSet,
+      groupFavorites: selectedInstanceId !== "favorites",
+      instanceOrder: selectedInstanceId === "favorites" ? instanceOrder : [],
+    });
+  }, [
+    favoritesSet,
+    flatModels,
+    instanceOrder,
+    matchesLockedProvider,
+    props.lockedProvider,
+    searchQuery,
+    showLockedInstanceSidebar,
+    selectedInstanceId,
+  ]);
+
+  const handleModelSelect = useCallback(
+    (modelSlug: string, instanceId: ProviderInstanceId) => {
+      const options = modelOptionsByInstance.get(instanceId);
+      if (!options) {
+        return;
+      }
+      const entry = entryByInstanceId.get(instanceId);
+      if (!entry) {
+        return;
+      }
+      // `resolveSelectableModel` uses the driver kind for normalization
+      // (slug casing etc.). Custom instances share their driver's
+      // normalization rules, so pass the driver kind here.
+      const resolvedModel = resolveSelectableModel(entry.driverKind, modelSlug, options);
+      if (resolvedModel) {
+        onInstanceModelChange(instanceId, resolvedModel);
+      }
+    },
+    [entryByInstanceId, modelOptionsByInstance, onInstanceModelChange],
+  );
+
+  const toggleFavorite = useCallback(
+    (instanceId: ProviderInstanceId, model: string) => {
+      const newFavorites = [...favorites];
+      const index = newFavorites.findIndex((f) => f.provider === instanceId && f.model === model);
+      if (index >= 0) {
+        newFavorites.splice(index, 1);
+      } else {
+        newFavorites.push({ provider: instanceId, model });
+      }
+      updateSettings({ favorites: newFavorites });
+    },
+    [favorites, updateSettings],
+  );
+
+  const LockedProviderIcon =
+    isLocked && props.lockedProvider ? PROVIDER_ICON_BY_PROVIDER[props.lockedProvider] : null;
+  // Header label for locked mode. Use the active instance's displayName
+  // when the lock narrows to exactly one instance (so "Codex Personal"
+  // shows instead of the generic driver label); fall back to the first
+  // matching entry otherwise.
+  const lockedHeaderLabel = useMemo(() => {
+    if (!isLocked || !props.lockedProvider) return null;
+    const matches = instanceEntries.filter((entry) => matchesLockedProvider(entry));
+    if (matches.length === 0) return null;
+    const active = matches.find((entry) => entry.instanceId === props.activeInstanceId);
+    return (active ?? matches[0])?.displayName ?? null;
+  }, [
+    isLocked,
+    matchesLockedProvider,
+    props.lockedProvider,
+    props.activeInstanceId,
+    instanceEntries,
+  ]);
+  const modelJumpCommandByKey = useMemo(() => {
+    const mapping = new Map<
+      string,
+      NonNullable<ReturnType<typeof modelPickerJumpCommandForIndex>>
+    >();
+    for (const [visibleModelIndex, model] of filteredModels.entries()) {
+      const jumpCommand = modelPickerJumpCommandForIndex(visibleModelIndex);
+      if (!jumpCommand) {
+        return mapping;
+      }
+      mapping.set(`${model.instanceId}:${model.slug}`, jumpCommand);
+    }
+    return mapping;
+  }, [filteredModels]);
+  const modelJumpModelKeys = useMemo(
+    () => [...modelJumpCommandByKey.keys()],
+    [modelJumpCommandByKey],
+  );
+  const allModelKeys = useMemo(
+    (): string[] => flatModels.map((model) => `${model.instanceId}:${model.slug}`),
+    [flatModels],
+  );
+  const filteredModelKeys = useMemo(
+    (): string[] => filteredModels.map((model) => `${model.instanceId}:${model.slug}`),
+    [filteredModels],
+  );
+  const filteredModelByKey = useMemo(
+    (): ReadonlyMap<string, ModelPickerItem> =>
+      new Map(filteredModels.map((model) => [`${model.instanceId}:${model.slug}`, model] as const)),
+    [filteredModels],
+  );
+  const modelJumpShortcutContext = useMemo(
+    () =>
+      ({
+        terminalFocus: false,
+        terminalOpen: props.terminalOpen,
+        modelPickerOpen: true,
+      }) as const,
+    [props.terminalOpen],
+  );
+  const modelJumpLabelByKey = useMemo((): ReadonlyMap<string, string> => {
+    if (modelJumpCommandByKey.size === 0) {
+      return EMPTY_MODEL_JUMP_LABELS;
+    }
+    const shortcutLabelOptions = {
+      platform: navigator.platform,
+      context: modelJumpShortcutContext,
+    };
+    const mapping = new Map<string, string>();
+    for (const [modelKey, command] of modelJumpCommandByKey) {
+      const label = shortcutLabelForCommand(keybindings, command, shortcutLabelOptions);
+      if (label) {
+        mapping.set(modelKey, label);
+      }
+    }
+    return mapping.size > 0 ? mapping : EMPTY_MODEL_JUMP_LABELS;
+  }, [keybindings, modelJumpCommandByKey, modelJumpShortcutContext]);
+
+  useEffect(() => {
+    const onWindowKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.defaultPrevented || event.repeat) {
+        return;
+      }
+
+      const command = resolveShortcutCommand(event, keybindings, {
+        platform: navigator.platform,
+        context: modelJumpShortcutContext,
+      });
+      const jumpIndex = modelPickerJumpIndexFromCommand(command ?? "");
+      if (jumpIndex === null) {
+        return;
+      }
+
+      const targetModelKey = modelJumpModelKeys[jumpIndex];
+      if (!targetModelKey) {
+        return;
+      }
+      const { instanceId, slug } = splitInstanceModelKey(targetModelKey);
+      event.preventDefault();
+      event.stopPropagation();
+      handleModelSelect(slug, instanceId);
+    };
+
+    window.addEventListener("keydown", onWindowKeyDown, true);
+
+    return () => {
+      window.removeEventListener("keydown", onWindowKeyDown, true);
+    };
+  }, [handleModelSelect, keybindings, modelJumpModelKeys, modelJumpShortcutContext]);
+
+  useLayoutEffect(() => {
+    const listRegion = listRegionRef.current;
+    if (!listRegion) {
+      return;
+    }
+
+    let cancelled = false;
+    let frame = 0;
+    let nestedFrame = 0;
+    let timeout = 0;
+
+    const measureScrollArea = () => {
+      if (cancelled) {
+        return;
+      }
+      const viewport = listRegion.querySelector<HTMLElement>('[data-slot="scroll-area-viewport"]');
+      if (!viewport || viewport.scrollHeight <= viewport.clientHeight) {
+        return;
+      }
+      const originalScrollTop = viewport.scrollTop;
+      const maxScrollTop = viewport.scrollHeight - viewport.clientHeight;
+      if (maxScrollTop <= 0) {
+        return;
+      }
+      viewport.scrollTop = Math.min(originalScrollTop + 1, maxScrollTop);
+      viewport.scrollTop = originalScrollTop;
+    };
+
+    queueMicrotask(measureScrollArea);
+    frame = window.requestAnimationFrame(() => {
+      measureScrollArea();
+      nestedFrame = window.requestAnimationFrame(measureScrollArea);
+    });
+    timeout = window.setTimeout(measureScrollArea, 0);
+
+    return () => {
+      cancelled = true;
+      window.cancelAnimationFrame(frame);
+      window.cancelAnimationFrame(nestedFrame);
+      window.clearTimeout(timeout);
+    };
+  }, [filteredModelKeys]);
+
+  return (
+    <TooltipProvider delay={0}>
+      <div
+        className={cn(
+          "relative flex h-screen max-h-96 w-screen max-w-100 overflow-hidden rounded-lg border bg-popover not-dark:bg-clip-padding text-popover-foreground shadow-lg/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+          isLocked && !showLockedInstanceSidebar ? "flex-col" : "flex-row",
+        )}
+      >
+        {/* Locked provider header (only shown in locked mode) */}
+        {isLocked && !showLockedInstanceSidebar && LockedProviderIcon && lockedHeaderLabel && (
+          <div className="flex items-center gap-2 px-4 py-3 border-b">
+            <LockedProviderIcon className="size-5 shrink-0" />
+            <span className="font-medium text-sm">{lockedHeaderLabel}</span>
+          </div>
+        )}
+
+        {/* Sidebar (only in unlocked mode) */}
+        {showSidebar && (
+          <ModelPickerSidebar
+            selectedInstanceId={selectedInstanceId}
+            onSelectInstance={handleSelectInstance}
+            instanceEntries={sidebarInstanceEntries}
+            showFavorites={!isLocked}
+            showComingSoon={!isLocked}
+          />
+        )}
+
+        {/* Main content area */}
+        <Combobox
+          inline
+          items={allModelKeys}
+          filteredItems={filteredModelKeys}
+          filter={null}
+          autoHighlight
+          open
+          value={`${props.activeInstanceId}:${props.model}`}
+          onItemHighlighted={(modelKey) => {
+            highlightedModelKeyRef.current = typeof modelKey === "string" ? modelKey : null;
+          }}
+          onValueChange={(modelKey) => {
+            if (typeof modelKey !== "string") {
+              return;
+            }
+            const { instanceId, slug } = splitInstanceModelKey(modelKey);
+            handleModelSelect(slug, instanceId);
+          }}
+        >
+          <div
+            className={cn(
+              "flex min-h-0 flex-1 flex-col overflow-hidden",
+              isLocked && !showLockedInstanceSidebar ? "min-w-0" : showSidebar && "border-l",
+            )}
+          >
+            {/* Search bar */}
+            <div className="border-b px-3 py-2">
+              <ComboboxInput
+                ref={searchInputRef}
+                className="[&_input]:font-sans rounded-md"
+                inputClassName="border-0 shadow-none ring-0 focus-visible:ring-0"
+                placeholder="Search models..."
+                showTrigger={false}
+                startAddon={<SearchIcon className="size-4 shrink-0 text-muted-foreground/50" />}
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === "Escape") {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    props.onRequestClose?.();
+                    return;
+                  }
+                  if (e.key === "Enter" && highlightedModelKeyRef.current) {
+                    (
+                      e as typeof e & { preventBaseUIHandler?: () => void }
+                    ).preventBaseUIHandler?.();
+                    e.preventDefault();
+                    e.stopPropagation();
+                    const { instanceId, slug } = splitInstanceModelKey(
+                      highlightedModelKeyRef.current,
+                    );
+                    handleModelSelect(slug, instanceId);
+                    return;
+                  }
+                  e.stopPropagation();
+                }}
+                onMouseDown={(e) => e.stopPropagation()}
+                onTouchStart={(e) => e.stopPropagation()}
+                size="sm"
+              />
+            </div>
+
+            {/* Model list */}
+            <div
+              ref={listRegionRef}
+              className="relative min-h-0 flex-1 before:pointer-events-none before:absolute before:inset-0 before:bg-muted/40"
+            >
+              <ComboboxList className="model-picker-list size-full divide-y px-2 py-1">
+                {filteredModelKeys.map((modelKey, index) => {
+                  const model = filteredModelByKey.get(modelKey);
+                  if (!model) {
+                    return null;
+                  }
+                  return (
+                    <ModelListRow
+                      key={modelKey}
+                      index={index}
+                      model={model}
+                      instanceId={model.instanceId}
+                      driverKind={model.driverKind}
+                      providerDisplayName={model.instanceDisplayName}
+                      providerAccentColor={model.instanceAccentColor}
+                      isFavorite={favoritesSet.has(modelKey)}
+                      showProvider={!isLocked || showLockedInstanceSidebar}
+                      preferShortName={!isLocked}
+                      useTriggerLabel={isLocked && !showLockedInstanceSidebar}
+                      showNewBadge={isModelPickerNewModel(model.driverKind, model.slug)}
+                      jumpLabel={modelJumpLabelByKey.get(modelKey) ?? null}
+                      onToggleFavorite={() => toggleFavorite(model.instanceId, model.slug)}
+                    />
+                  );
+                })}
+              </ComboboxList>
+            </div>
+            <ComboboxEmpty className="not-empty:py-6 empty:h-0 text-xs font-normal leading-snug">
+              No models found
+            </ComboboxEmpty>
+          </div>
+        </Combobox>
+      </div>
+    </TooltipProvider>
+  );
+});
diff --git a/apps/web/src/components/chat/ModelPickerSidebar.tsx b/apps/web/src/components/chat/ModelPickerSidebar.tsx
new file mode 100644
index 00000000000..121b5267a3d
--- /dev/null
+++ b/apps/web/src/components/chat/ModelPickerSidebar.tsx
@@ -0,0 +1,263 @@
+import { type ProviderInstanceId } from "@t3tools/contracts";
+import { memo, useMemo } from "react";
+import { Clock3Icon, SparklesIcon, StarIcon } from "lucide-react";
+import { Gemini, GithubCopilotIcon } from "../Icons";
+import { ProviderInstanceIcon } from "./ProviderInstanceIcon";
+import { ScrollArea } from "../ui/scroll-area";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { cn } from "~/lib/utils";
+import type { ProviderInstanceEntry } from "../../providerInstances";
+
+/**
+ * Build the hover tooltip for an instance button. Mirrors the old
+ * kind-based copy but uses the entry's configured `displayName` so custom
+ * instances get their user-authored name (e.g. "Codex Personal — Unavailable.").
+ */
+function describeUnavailableInstance(entry: ProviderInstanceEntry): string {
+  const label = entry.displayName;
+  if (entry.status === "ready") {
+    return label;
+  }
+  const kind =
+    entry.status === "error"
+      ? "Unavailable"
+      : entry.status === "warning"
+        ? "Limited"
+        : entry.status === "disabled"
+          ? "Disabled in settings"
+          : "Not ready";
+  const msg = entry.snapshot.message?.trim();
+  return msg ? `${label} — ${kind}. ${msg}` : `${label} — ${kind}.`;
+}
+
+const SELECTED_BUTTON_CLASS = "bg-background text-foreground shadow-sm";
+const SELECTED_INDICATOR_CLASS =
+  "pointer-events-none absolute -right-1 top-1/2 z-10 h-5 w-0.5 -translate-y-1/2 rounded-l-full bg-primary";
+const BADGE_BASE_CLASS =
+  "pointer-events-none absolute -right-0.5 top-0.5 z-10 flex size-3.5 items-center justify-center rounded-full bg-transparent shadow-sm ";
+const NEW_BADGE_CLASS = `${BADGE_BASE_CLASS} text-amber-600  dark:text-amber-300 `;
+const SOON_BADGE_CLASS = `${BADGE_BASE_CLASS} text-muted-foreground `;
+
+/** Opens toward the rail so the list stays readable (not over the model names). */
+const PICKER_TOOLTIP_SIDE = "left" as const;
+const PICKER_TOOLTIP_CLASS = "max-w-64 text-balance font-normal leading-snug";
+
+export const ModelPickerSidebar = memo(function ModelPickerSidebar(props: {
+  selectedInstanceId: ProviderInstanceId | "favorites";
+  onSelectInstance: (instanceId: ProviderInstanceId | "favorites") => void;
+  /**
+   * Instance entries to render as rail buttons. Each entry becomes one icon
+   * keyed by `instanceId`, so the default built-in Codex and a user-authored
+   * `codex_personal` appear as two distinct rail items, each routing to
+   * their own model list.
+   */
+  instanceEntries: ReadonlyArray<ProviderInstanceEntry>;
+  /** Render the favorites rail entry. Hidden for locked-provider instance switching. */
+  showFavorites?: boolean;
+  /** Render non-configured coming-soon provider entries. Hidden in scoped rails. */
+  showComingSoon?: boolean;
+  /**
+   * Instance id values that should render the "new" sparkle badge. Callers
+   * pass the subset of default built-in ids they want flagged (custom
+   * instances are never flagged — the user just made them).
+   */
+  newBadgeInstanceIds?: ReadonlySet<ProviderInstanceId>;
+}) {
+  const handleSelect = (instanceId: ProviderInstanceId | "favorites") => {
+    props.onSelectInstance(instanceId);
+  };
+  const showFavorites = props.showFavorites ?? true;
+  const showComingSoon = props.showComingSoon ?? true;
+  const duplicateDriverCounts = useMemo(() => {
+    const counts = new Map<string, number>();
+    for (const entry of props.instanceEntries) {
+      counts.set(entry.driverKind, (counts.get(entry.driverKind) ?? 0) + 1);
+    }
+    return counts;
+  }, [props.instanceEntries]);
+
+  return (
+    <ScrollArea
+      hideScrollbars
+      scrollFade
+      className="w-12 shrink-0 border-r bg-muted/30"
+      data-model-picker-sidebar="true"
+    >
+      <div className="flex min-h-full flex-col gap-1 p-1">
+        {/* Favorites section */}
+        {showFavorites ? (
+          <div className="pb-1 mb-1 border-b">
+            <div className="relative w-full">
+              {props.selectedInstanceId === "favorites" && (
+                <div className={SELECTED_INDICATOR_CLASS} />
+              )}
+              <Tooltip>
+                <TooltipTrigger
+                  render={
+                    <button
+                      className={cn(
+                        "relative isolate flex w-full cursor-pointer aspect-square items-center justify-center rounded transition-colors hover:bg-muted",
+                        props.selectedInstanceId === "favorites" && SELECTED_BUTTON_CLASS,
+                      )}
+                      onClick={() => handleSelect("favorites")}
+                      type="button"
+                      data-model-picker-provider="favorites"
+                      aria-label="Favorites"
+                    >
+                      <StarIcon className="size-5 fill-current shrink-0" aria-hidden />
+                    </button>
+                  }
+                />
+                <TooltipPopup
+                  side={PICKER_TOOLTIP_SIDE}
+                  align="center"
+                  className={PICKER_TOOLTIP_CLASS}
+                >
+                  Favorites
+                </TooltipPopup>
+              </Tooltip>
+            </div>
+          </div>
+        ) : null}
+
+        {/* Instance buttons (one per configured instance — built-in + custom) */}
+        {props.instanceEntries.map((entry) => {
+          const isDisabled = !entry.isAvailable || entry.status !== "ready";
+          const isSelected = props.selectedInstanceId === entry.instanceId;
+          const showNewBadge = props.newBadgeInstanceIds?.has(entry.instanceId) ?? false;
+          const showInstanceBadge =
+            Boolean(entry.accentColor) || (duplicateDriverCounts.get(entry.driverKind) ?? 0) > 1;
+
+          const tooltip = isDisabled
+            ? describeUnavailableInstance(entry)
+            : showNewBadge
+              ? `${entry.displayName} — New`
+              : entry.displayName;
+
+          const button = (
+            <button
+              data-model-picker-provider={entry.instanceId}
+              className={cn(
+                "relative isolate flex w-full cursor-pointer aspect-square items-center justify-center rounded transition-colors hover:bg-muted",
+                isSelected && SELECTED_BUTTON_CLASS,
+                isDisabled && "opacity-50 cursor-not-allowed hover:bg-transparent",
+              )}
+              data-provider-accent-color={entry.accentColor}
+              onClick={() => !isDisabled && handleSelect(entry.instanceId)}
+              disabled={isDisabled}
+              type="button"
+              aria-label={
+                isDisabled
+                  ? tooltip
+                  : showNewBadge
+                    ? `${entry.displayName}, new`
+                    : entry.displayName
+              }
+            >
+              <ProviderInstanceIcon
+                driverKind={entry.driverKind}
+                displayName={entry.displayName}
+                accentColor={entry.accentColor}
+                showBadge={showInstanceBadge}
+                className="size-6"
+                iconClassName="size-5"
+              />
+              {showNewBadge ? (
+                <span className={NEW_BADGE_CLASS} aria-hidden>
+                  <SparklesIcon className="size-2" />
+                </span>
+              ) : null}
+            </button>
+          );
+
+          const trigger = isDisabled ? (
+            <span className="relative block w-full">{button}</span>
+          ) : (
+            button
+          );
+
+          return (
+            <div key={entry.instanceId} className="relative w-full">
+              {isSelected && <div className={SELECTED_INDICATOR_CLASS} />}
+              <Tooltip>
+                <TooltipTrigger render={trigger} />
+                <TooltipPopup
+                  side={PICKER_TOOLTIP_SIDE}
+                  align="center"
+                  className={PICKER_TOOLTIP_CLASS}
+                >
+                  {tooltip}
+                </TooltipPopup>
+              </Tooltip>
+            </div>
+          );
+        })}
+
+        {showComingSoon ? (
+          <>
+            {/* Gemini button (coming soon) */}
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <span className="relative block w-full">
+                    <button
+                      className={cn(
+                        "relative isolate flex w-full aspect-square items-center justify-center rounded opacity-50 cursor-not-allowed transition-colors hover:bg-transparent",
+                      )}
+                      disabled
+                      type="button"
+                      data-model-picker-provider="gemini-coming-soon"
+                      aria-label="Gemini — coming soon"
+                    >
+                      <Gemini className="size-5 text-muted-foreground/85" aria-hidden />
+                      <span className={SOON_BADGE_CLASS} aria-hidden>
+                        <Clock3Icon className="size-2" />
+                      </span>
+                    </button>
+                  </span>
+                }
+              />
+              <TooltipPopup
+                side={PICKER_TOOLTIP_SIDE}
+                align="center"
+                className={PICKER_TOOLTIP_CLASS}
+              >
+                Gemini — Coming soon
+              </TooltipPopup>
+            </Tooltip>
+            {/* Github Copilot button (coming soon) */}
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <span className="relative block w-full">
+                    <button
+                      className={cn(
+                        "relative isolate flex w-full aspect-square items-center justify-center rounded opacity-50 cursor-not-allowed transition-colors hover:bg-transparent",
+                      )}
+                      disabled
+                      type="button"
+                      data-model-picker-provider="github-copilot-coming-soon"
+                      aria-label="Github Copilot — coming soon"
+                    >
+                      <GithubCopilotIcon className="size-5 text-muted-foreground/85" aria-hidden />
+                      <span className={SOON_BADGE_CLASS} aria-hidden>
+                        <Clock3Icon className="size-2" />
+                      </span>
+                    </button>
+                  </span>
+                }
+              />
+              <TooltipPopup
+                side={PICKER_TOOLTIP_SIDE}
+                align="center"
+                className={PICKER_TOOLTIP_CLASS}
+              >
+                Github Copilot — Coming soon
+              </TooltipPopup>
+            </Tooltip>
+          </>
+        ) : null}
+      </div>
+    </ScrollArea>
+  );
+});
diff --git a/apps/web/src/components/chat/OpenInPicker.tsx b/apps/web/src/components/chat/OpenInPicker.tsx
index d30fa9be049..6b5f2dacc24 100644
--- a/apps/web/src/components/chat/OpenInPicker.tsx
+++ b/apps/web/src/components/chat/OpenInPicker.tsx
@@ -10,13 +10,27 @@ import {
   AntigravityIcon,
   CursorIcon,
   Icon,
+  KiroIcon,
   TraeIcon,
-  IntelliJIdeaIcon,
   VisualStudioCode,
   VisualStudioCodeInsiders,
   VSCodium,
   Zed,
 } from "../Icons";
+import {
+  AquaIcon,
+  CLionIcon,
+  DataGripIcon,
+  DataSpellIcon,
+  GoLandIcon,
+  IntelliJIdeaIcon,
+  PhpStormIcon,
+  PyCharmIcon,
+  RiderIcon,
+  RubyMineIcon,
+  RustRoverIcon,
+  WebStormIcon,
+} from "../JetBrainsIcons";
 import { isMacPlatform, isWindowsPlatform } from "~/lib/utils";
 import { readLocalApi } from "~/localApi";
 
@@ -32,6 +46,11 @@ const resolveOptions = (platform: string, availableEditors: ReadonlyArray<Editor
       Icon: TraeIcon,
       value: "trae",
     },
+    {
+      label: "Kiro",
+      Icon: KiroIcon,
+      value: "kiro",
+    },
     {
       label: "VS Code",
       Icon: VisualStudioCode,
@@ -62,6 +81,61 @@ const resolveOptions = (platform: string, availableEditors: ReadonlyArray<Editor
       Icon: IntelliJIdeaIcon,
       value: "idea",
     },
+    {
+      label: "Aqua",
+      Icon: AquaIcon,
+      value: "aqua",
+    },
+    {
+      label: "CLion",
+      Icon: CLionIcon,
+      value: "clion",
+    },
+    {
+      label: "DataGrip",
+      Icon: DataGripIcon,
+      value: "datagrip",
+    },
+    {
+      label: "DataSpell",
+      Icon: DataSpellIcon,
+      value: "dataspell",
+    },
+    {
+      label: "GoLand",
+      Icon: GoLandIcon,
+      value: "goland",
+    },
+    {
+      label: "PhpStorm",
+      Icon: PhpStormIcon,
+      value: "phpstorm",
+    },
+    {
+      label: "PyCharm",
+      Icon: PyCharmIcon,
+      value: "pycharm",
+    },
+    {
+      label: "Rider",
+      Icon: RiderIcon,
+      value: "rider",
+    },
+    {
+      label: "RubyMine",
+      Icon: RubyMineIcon,
+      value: "rubymine",
+    },
+    {
+      label: "RustRover",
+      Icon: RustRoverIcon,
+      value: "rustrover",
+    },
+    {
+      label: "WebStorm",
+      Icon: WebStormIcon,
+      value: "webstorm",
+    },
     {
       label: isMacPlatform(platform)
         ? "Finder"
diff --git a/apps/web/src/components/chat/ProposedPlanCard.tsx b/apps/web/src/components/chat/ProposedPlanCard.tsx
index a36cb097cbe..e53ee93b913 100644
--- a/apps/web/src/components/chat/ProposedPlanCard.tsx
+++ b/apps/web/src/components/chat/ProposedPlanCard.tsx
@@ -24,7 +24,7 @@ import {
   DialogPopup,
   DialogTitle,
 } from "../ui/dialog";
-import { toastManager } from "../ui/toast";
+import { stackedThreadToast, toastManager } from "../ui/toast";
 import { readEnvironmentApi } from "~/environmentApi";
 import { useCopyToClipboard } from "~/hooks/useCopyToClipboard";
 
@@ -45,11 +45,13 @@ export const ProposedPlanCard = memo(function ProposedPlanCard({
   const [isSavingToWorkspace, setIsSavingToWorkspace] = useState(false);
   const { copyToClipboard, isCopied } = useCopyToClipboard({
     onError: (error) => {
-      toastManager.add({
-        type: "error",
-        title: "Could not copy plan",
-        description: error instanceof Error ? error.message : "An error occurred while copying.",
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not copy plan",
+          description: error instanceof Error ? error.message : "An error occurred while copying.",
+        }),
+      );
     },
   });
   const savePathInputId = useId();
@@ -73,11 +75,13 @@ export const ProposedPlanCard = memo(function ProposedPlanCard({
 
   const openSaveDialog = () => {
     if (!workspaceRoot) {
-      toastManager.add({
-        type: "error",
-        title: "Workspace path is unavailable",
-        description: "This thread does not have a workspace path to save into.",
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Workspace path is unavailable",
+          description: "This thread does not have a workspace path to save into.",
+        }),
+      );
       return;
     }
     setSavePath((existing) => (existing.length > 0 ? existing : downloadFilename));
@@ -114,11 +118,13 @@ export const ProposedPlanCard = memo(function ProposedPlanCard({
         });
       })
       .catch((error) => {
-        toastManager.add({
-          type: "error",
-          title: "Could not save plan",
-          description: error instanceof Error ? error.message : "An error occurred while saving.",
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not save plan",
+            description: error instanceof Error ? error.message : "An error occurred while saving.",
+          }),
+        );
       })
       .then(
         () => {
diff --git a/apps/web/src/components/chat/ProviderInstanceIcon.tsx b/apps/web/src/components/chat/ProviderInstanceIcon.tsx
new file mode 100644
index 00000000000..154cada19aa
--- /dev/null
+++ b/apps/web/src/components/chat/ProviderInstanceIcon.tsx
@@ -0,0 +1,73 @@
+import { type CSSProperties, memo } from "react";
+import { type ProviderDriverKind } from "@t3tools/contracts";
+
+import { PROVIDER_ICON_BY_PROVIDER } from "./providerIconUtils";
+import { cn } from "~/lib/utils";
+
+export function providerInstanceInitials(label: string): string {
+  const words = label.replace(/[_-]+/g, " ").split(/\s+/u).filter(Boolean);
+  if (words.length === 0) return "";
+  if (words.length === 1) return words[0]!.slice(0, 2).toUpperCase();
+  return words
+    .slice(0, 2)
+    .map((word) => word[0]?.toUpperCase() ?? "")
+    .join("");
+}
+
+export const ProviderInstanceIcon = memo(function ProviderInstanceIcon(props: {
+  driverKind: ProviderDriverKind;
+  displayName: string;
+  accentColor?: string | undefined;
+  showBadge?: boolean;
+  className?: string;
+  iconClassName?: string;
+  badgeClassName?: string;
+  statusDotClassName?: string;
+}) {
+  const Icon = PROVIDER_ICON_BY_PROVIDER[props.driverKind] ?? null;
+  const accentStyle = props.accentColor
+    ? ({ "--provider-accent": props.accentColor } as CSSProperties)
+    : undefined;
+
+  return (
+    <span
+      className={cn(
+        "relative isolate inline-flex shrink-0 items-center justify-center",
+        props.className,
+      )}
+      style={accentStyle}
+      data-provider-accent-color={props.accentColor}
+    >
+      {Icon ? (
+        <Icon className={cn("size-5 shrink-0", props.iconClassName)} aria-hidden />
+      ) : (
+        <span className={cn("text-[10px] font-semibold leading-none", props.iconClassName)}>
+          {providerInstanceInitials(props.displayName)}
+        </span>
+      )}
+      {props.statusDotClassName ? (
+        <span
+          className={cn(
+            "pointer-events-none absolute -left-0.5 -top-0.5 size-2 rounded-full ring-2 ring-background",
+            props.statusDotClassName,
+          )}
+          aria-hidden
+        />
+      ) : null}
+      {props.showBadge ? (
+        <span
+          className={cn(
+            "pointer-events-none absolute right-0 bottom-0 flex h-3.5 min-w-3.5 items-center justify-center rounded-full border border-background px-0.5 text-[8px] font-semibold leading-none shadow-sm",
+            props.accentColor
+              ? "bg-[var(--provider-accent)] text-white"
+              : "bg-muted text-muted-foreground",
+            props.badgeClassName,
+          )}
+          aria-hidden
+        >
+          {providerInstanceInitials(props.displayName)}
+        </span>
+      ) : null}
+    </span>
+  );
+});
diff --git a/apps/web/src/components/chat/ProviderModelPicker.browser.tsx b/apps/web/src/components/chat/ProviderModelPicker.browser.tsx
index abedcd6eeb3..d3b168876a6 100644
--- a/apps/web/src/components/chat/ProviderModelPicker.browser.tsx
+++ b/apps/web/src/components/chat/ProviderModelPicker.browser.tsx
@@ -1,23 +1,110 @@
-import { type ProviderKind, type ServerProvider } from "@t3tools/contracts";
-import { page } from "vitest/browser";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import { EnvironmentId } from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
+import { page, userEvent } from "vitest/browser";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { render } from "vitest-browser-react";
 
 import { ProviderModelPicker } from "./ProviderModelPicker";
-import { getCustomModelOptionsByProvider } from "../../modelSelection";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
+import { getCustomModelOptionsByInstance } from "../../modelSelection";
+import {
+  deriveProviderInstanceEntries,
+  sortProviderInstanceEntries,
+} from "../../providerInstances";
+import type { ModelEsque } from "./providerIconUtils";
+import {
+  DEFAULT_CLIENT_SETTINGS,
+  DEFAULT_UNIFIED_SETTINGS,
+  type UnifiedSettings,
+} from "@t3tools/contracts/settings";
+import { __resetLocalApiForTests } from "../../localApi";
 
-function effort(value: string, isDefault = false) {
+// Mock the environments/runtime module to provide a mock primary environment connection
+vi.mock("../../environments/runtime", () => {
+  const primaryConnection = {
+    kind: "primary" as const,
+    knownEnvironment: {
+      id: "environment-local",
+      label: "Local environment",
+      source: "manual" as const,
+      environmentId: EnvironmentId.make("environment-local"),
+      target: {
+        httpBaseUrl: "http://localhost:3000",
+        wsBaseUrl: "ws://localhost:3000",
+      },
+    },
+    environmentId: EnvironmentId.make("environment-local"),
+    client: {
+      server: {
+        getConfig: vi.fn(),
+        updateSettings: vi.fn(),
+      },
+    },
+    ensureBootstrapped: async () => undefined,
+    reconnect: async () => undefined,
+    dispose: async () => undefined,
+  };
+
+  return {
+    getEnvironmentHttpBaseUrl: () => "http://localhost:3000",
+    getSavedEnvironmentRecord: () => null,
+    getSavedEnvironmentRuntimeState: () => null,
+    hasSavedEnvironmentRegistryHydrated: () => true,
+    listSavedEnvironmentRecords: () => [],
+    resetSavedEnvironmentRegistryStoreForTests: vi.fn(),
+    resetSavedEnvironmentRuntimeStoreForTests: vi.fn(),
+    resolveEnvironmentHttpUrl: (_environmentId: unknown, path: string) =>
+      new URL(path, "http://localhost:3000").toString(),
+    waitForSavedEnvironmentRegistryHydration: async () => undefined,
+    addSavedEnvironment: vi.fn(),
+    disconnectSavedEnvironment: vi.fn(),
+    ensureEnvironmentConnectionBootstrapped: async () => undefined,
+    getPrimaryEnvironmentConnection: () => primaryConnection,
+    readEnvironmentConnection: () => primaryConnection,
+    reconnectSavedEnvironment: vi.fn(),
+    removeSavedEnvironment: vi.fn(),
+    requireEnvironmentConnection: () => primaryConnection,
+    resetEnvironmentServiceForTests: vi.fn(),
+    startEnvironmentConnectionService: vi.fn(),
+    subscribeEnvironmentConnections: () => () => {},
+    useSavedEnvironmentRegistryStore: (
+      selector: (state: { byId: Record<string, never> }) => unknown,
+    ) => selector({ byId: {} }),
+    useSavedEnvironmentRuntimeStore: (
+      selector: (state: { byId: Record<string, never> }) => unknown,
+    ) => selector({ byId: {} }),
+  };
+});
+
+function selectDescriptor(
+  id: string,
+  label: string,
+  options: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>,
+) {
+  return {
+    id,
+    label,
+    type: "select" as const,
+    options: [...options],
+    ...(options.find((option) => option.isDefault)?.id
+      ? { currentValue: options.find((option) => option.isDefault)?.id }
+      : {}),
+  };
+}
+
+function booleanDescriptor(id: string, label: string) {
   return {
-    value,
-    label: value,
-    ...(isDefault ? { isDefault: true } : {}),
+    id,
+    label,
+    type: "boolean" as const,
   };
 }
 
 const TEST_PROVIDERS: ReadonlyArray<ServerProvider> = [
   {
-    provider: "codex",
+    driver: ProviderDriverKind.make("codex"),
+    instanceId: ProviderInstanceId.make("codex"),
+    displayName: "Codex",
     enabled: true,
     installed: true,
     version: "0.116.0",
@@ -31,30 +118,38 @@ const TEST_PROVIDERS: ReadonlyArray<ServerProvider> = [
         slug: "gpt-5-codex",
         name: "GPT-5 Codex",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-          supportsFastMode: true,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: createModelCapabilities({
+          optionDescriptors: [
+            selectDescriptor("reasoningEffort", "Reasoning", [
+              { id: "low", label: "low" },
+              { id: "medium", label: "medium", isDefault: true },
+              { id: "high", label: "high" },
+            ]),
+            booleanDescriptor("fastMode", "Fast Mode"),
+          ],
+        }),
       },
       {
         slug: "gpt-5.3-codex",
         name: "GPT-5.3 Codex",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-          supportsFastMode: true,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: createModelCapabilities({
+          optionDescriptors: [
+            selectDescriptor("reasoningEffort", "Reasoning", [
+              { id: "low", label: "low" },
+              { id: "medium", label: "medium", isDefault: true },
+              { id: "high", label: "high" },
+            ]),
+            booleanDescriptor("fastMode", "Fast Mode"),
+          ],
+        }),
       },
     ],
   },
   {
-    provider: "claudeAgent",
+    driver: ProviderDriverKind.make("claudeAgent"),
+    instanceId: ProviderInstanceId.make("claudeAgent"),
+    displayName: "Claude",
     enabled: true,
     installed: true,
     version: "1.0.0",
@@ -68,55 +163,62 @@ const TEST_PROVIDERS: ReadonlyArray<ServerProvider> = [
         slug: "claude-opus-4-6",
         name: "Claude Opus 4.6",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [
-            effort("low"),
-            effort("medium", true),
-            effort("high"),
-            effort("max"),
+        capabilities: createModelCapabilities({
+          optionDescriptors: [
+            selectDescriptor("effort", "Reasoning", [
+              { id: "low", label: "low" },
+              { id: "medium", label: "medium", isDefault: true },
+              { id: "high", label: "high" },
+              { id: "max", label: "max" },
+            ]),
+            booleanDescriptor("thinking", "Thinking"),
           ],
-          supportsFastMode: false,
-          supportsThinkingToggle: true,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        }),
       },
       {
         slug: "claude-sonnet-4-6",
         name: "Claude Sonnet 4.6",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [
-            effort("low"),
-            effort("medium", true),
-            effort("high"),
-            effort("max"),
+        capabilities: createModelCapabilities({
+          optionDescriptors: [
+            selectDescriptor("effort", "Reasoning", [
+              { id: "low", label: "low" },
+              { id: "medium", label: "medium", isDefault: true },
+              { id: "high", label: "high" },
+              { id: "max", label: "max" },
+            ]),
+            booleanDescriptor("thinking", "Thinking"),
           ],
-          supportsFastMode: false,
-          supportsThinkingToggle: true,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        }),
       },
       {
         slug: "claude-haiku-4-5",
         name: "Claude Haiku 4.5",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-          supportsFastMode: false,
-          supportsThinkingToggle: true,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: createModelCapabilities({
+          optionDescriptors: [
+            selectDescriptor("effort", "Reasoning", [
+              { id: "low", label: "low" },
+              { id: "medium", label: "medium", isDefault: true },
+              { id: "high", label: "high" },
+            ]),
+            booleanDescriptor("thinking", "Thinking"),
+          ],
+        }),
       },
     ],
   },
 ];
 
+const CODEX_INSTANCE_ID = ProviderInstanceId.make("codex");
+const CLAUDE_INSTANCE_ID = ProviderInstanceId.make("claudeAgent");
+const OPENCODE_INSTANCE_ID = ProviderInstanceId.make("opencode");
+
 function buildCodexProvider(models: ServerProvider["models"]): ServerProvider {
   return {
-    provider: "codex",
+    driver: ProviderDriverKind.make("codex"),
+    instanceId: ProviderInstanceId.make("codex"),
+    displayName: "Codex",
     enabled: true,
     installed: true,
     version: "0.116.0",
@@ -129,38 +231,64 @@ function buildCodexProvider(models: ServerProvider["models"]): ServerProvider {
   };
 }
 
+function buildOpenCodeProvider(models: ServerProvider["models"]): ServerProvider {
+  return {
+    driver: ProviderDriverKind.make("opencode"),
+    instanceId: ProviderInstanceId.make("opencode"),
+    enabled: true,
+    installed: true,
+    version: "1.0.0",
+    status: "ready",
+    auth: { status: "authenticated" },
+    checkedAt: new Date().toISOString(),
+    models,
+    slashCommands: [],
+    skills: [],
+  };
+}
+
 async function mountPicker(props: {
-  provider: ProviderKind;
+  activeInstanceId?: ProviderInstanceId;
   model: string;
-  lockedProvider: ProviderKind | null;
+  lockedProvider: ProviderDriverKind | null;
+  lockedContinuationGroupKey?: string | null;
   providers?: ReadonlyArray<ServerProvider>;
+  settings?: UnifiedSettings;
   triggerVariant?: "ghost" | "outline";
 }) {
   const host = document.createElement("div");
   document.body.append(host);
-  const onProviderModelChange = vi.fn();
+  const onInstanceModelChange = vi.fn();
   const providers = props.providers ?? TEST_PROVIDERS;
-  const modelOptionsByProvider = getCustomModelOptionsByProvider(
-    DEFAULT_UNIFIED_SETTINGS,
+  const instanceEntries = sortProviderInstanceEntries(deriveProviderInstanceEntries(providers));
+  const activeInstanceId = props.activeInstanceId ?? CODEX_INSTANCE_ID;
+  const modelOptionsByInstance = getCustomModelOptionsByInstance(
+    props.settings ?? DEFAULT_UNIFIED_SETTINGS,
     providers,
-    props.provider,
+    activeInstanceId,
     props.model,
   );
   const screen = await render(
     <ProviderModelPicker
-      provider={props.provider}
+      activeInstanceId={activeInstanceId}
       model={props.model}
       lockedProvider={props.lockedProvider}
-      providers={providers}
-      modelOptionsByProvider={modelOptionsByProvider}
+      lockedContinuationGroupKey={props.lockedContinuationGroupKey ?? null}
+      instanceEntries={instanceEntries}
+      modelOptionsByInstance={modelOptionsByInstance}
       triggerVariant={props.triggerVariant}
-      onProviderModelChange={onProviderModelChange}
+      onInstanceModelChange={onInstanceModelChange}
     />,
     { container: host },
   );
 
   return {
-    onProviderModelChange,
+    onInstanceModelChange,
+    // Back-compat alias used by callers that still assert on the old callback
+    // name. Delegates to the instance-aware mock so existing expectations work.
+    get onProviderModelChange() {
+      return onInstanceModelChange;
+    },
     cleanup: async () => {
       await screen.unmount();
       host.remove();
@@ -168,14 +296,42 @@ async function mountPicker(props: {
   };
 }
 
+function getModelPickerListElement() {
+  const modelPickerList = document.querySelector<HTMLElement>(".model-picker-list");
+  expect(modelPickerList).not.toBeNull();
+  return modelPickerList!;
+}
+
+function getModelPickerListText() {
+  return getModelPickerListElement().textContent ?? "";
+}
+
+function getVisibleModelNames() {
+  return Array.from(getModelPickerListElement().querySelectorAll<HTMLDivElement>("div.font-medium"))
+    .map((element) => element.textContent?.replace(/New$/u, "").trim() ?? "")
+    .filter((text) => text.length > 0);
+}
+
+function getSidebarProviderOrder() {
+  return Array.from(document.querySelectorAll<HTMLElement>("[data-model-picker-provider]")).map(
+    (element) => element.dataset.modelPickerProvider ?? "",
+  );
+}
+
 describe("ProviderModelPicker", () => {
-  afterEach(() => {
+  beforeEach(async () => {
+    // Reset test environment before each test
+    await __resetLocalApiForTests();
+  });
+
+  afterEach(async () => {
     document.body.innerHTML = "";
+    await __resetLocalApiForTests();
   });
 
-  it("shows provider submenus when provider switching is allowed", async () => {
+  it("shows provider sidebar in unlocked mode", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -185,65 +341,720 @@ describe("ProviderModelPicker", () => {
 
       await vi.waitFor(() => {
         const text = document.body.textContent ?? "";
-        expect(text).toContain("Codex");
+        expect(text).not.toContain("Codex");
         expect(text).toContain("Claude");
-        expect(text).not.toContain("Claude Sonnet 4.6");
+        expect(text).toContain("Claude Opus 4.6");
       });
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("opens provider submenus with a visible gap from the parent menu", async () => {
+  it("shows favorites first in the provider sidebar", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
 
     try {
       await page.getByRole("button").click();
-      const providerTrigger = page.getByRole("menuitem", { name: "Codex" });
-      await providerTrigger.hover();
 
       await vi.waitFor(() => {
-        expect(document.body.textContent ?? "").toContain("GPT-5 Codex");
+        expect(getSidebarProviderOrder().slice(0, 3)).toEqual([
+          "favorites",
+          "codex",
+          "claudeAgent",
+        ]);
       });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
 
-      const providerTriggerElement = Array.from(
-        document.querySelectorAll<HTMLElement>('[role="menuitem"]'),
-      ).find((element) => element.textContent?.includes("Codex"));
-      if (!providerTriggerElement) {
-        throw new Error("Expected the Codex provider trigger to be mounted.");
-      }
+  it("filters models by selected provider in sidebar", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+    });
 
-      const providerTriggerRect = providerTriggerElement.getBoundingClientRect();
-      const modelElement = Array.from(
-        document.querySelectorAll<HTMLElement>('[role="menuitemradio"]'),
-      ).find((element) => element.textContent?.includes("GPT-5 Codex"));
-      if (!modelElement) {
-        throw new Error("Expected the submenu model option to be mounted.");
-      }
+    try {
+      await page.getByRole("button").click();
 
-      const submenuPopup = modelElement.closest('[data-slot="menu-sub-content"]');
-      if (!(submenuPopup instanceof HTMLElement)) {
-        throw new Error("Expected submenu popup to be mounted.");
-      }
+      // Start with Claude models visible
+      await vi.waitFor(() => {
+        const text = document.body.textContent ?? "";
+        expect(text).not.toContain("GPT-5 Codex");
+        expect(text).toContain("Claude Opus 4.6");
+      });
+
+      // Click on Codex provider in sidebar
+      await vi.waitFor(() => {
+        expect(document.querySelector('[data-model-picker-provider="codex"]')).not.toBeNull();
+      });
+      await page.getByRole("button", { name: "Codex", exact: true }).click();
+
+      // Now should only show Codex models
+      await vi.waitFor(() => {
+        const listText = getModelPickerListText();
+        expect(listText).toContain("GPT-5 Codex");
+        expect(listText).not.toContain("Claude Opus 4.6");
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("uses client model visibility and ordering preferences", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+      settings: {
+        ...DEFAULT_UNIFIED_SETTINGS,
+        providerModelPreferences: {
+          [CLAUDE_INSTANCE_ID]: {
+            hiddenModels: ["claude-opus-4-6"],
+            modelOrder: ["claude-haiku-4-5", "claude-sonnet-4-6"],
+          },
+        },
+      },
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        expect(getVisibleModelNames()).toEqual(["Claude Haiku 4.5", "Claude Sonnet 4.6"]);
+        expect(getModelPickerListText()).not.toContain("Claude Opus 4.6");
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("focuses the search input after selecting a sidebar provider", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        expect(document.querySelector('[data-model-picker-provider="codex"]')).not.toBeNull();
+      });
+      await page.getByRole("button", { name: "Codex", exact: true }).click();
+
+      await vi.waitFor(() => {
+        const searchInput = document.querySelector<HTMLInputElement>(
+          'input[placeholder="Search models..."]',
+        );
+        expect(searchInput).not.toBeNull();
+        expect(document.activeElement).toBe(searchInput);
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("shows locked provider header and only its models in locked mode", async () => {
+    localStorage.setItem(
+      "t3code:client-settings:v1",
+      JSON.stringify({
+        ...DEFAULT_CLIENT_SETTINGS,
+        favorites: [
+          { provider: "codex", model: "gpt-5-codex" },
+          { provider: "claudeAgent", model: "claude-sonnet-4-6" },
+        ],
+      }),
+    );
+
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: ProviderDriverKind.make("claudeAgent"),
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        const text = document.body.textContent ?? "";
+        // Should show locked provider label
+        expect(text).toContain("Claude");
+        expect(getVisibleModelNames()).toEqual([
+          "Claude Sonnet 4.6",
+          "Claude Opus 4.6",
+          "Claude Haiku 4.5",
+        ]);
+      });
+    } finally {
+      localStorage.removeItem("t3code:client-settings:v1");
+      await mounted.cleanup();
+    }
+  });
+
+  it("keeps an instance sidebar in locked mode when that provider has multiple instances", async () => {
+    const defaultCodexModels: ServerProvider["models"] = [
+      {
+        slug: "gpt-work",
+        name: "GPT Work",
+        isCustom: false,
+        capabilities: createModelCapabilities({ optionDescriptors: [] }),
+      },
+    ];
+    const personalCodexModels: ServerProvider["models"] = [
+      {
+        slug: "gpt-personal",
+        name: "GPT Personal",
+        isCustom: false,
+        capabilities: createModelCapabilities({ optionDescriptors: [] }),
+      },
+    ];
+    const isolatedCodexModels: ServerProvider["models"] = [
+      {
+        slug: "gpt-isolated",
+        name: "GPT Isolated",
+        isCustom: false,
+        capabilities: createModelCapabilities({ optionDescriptors: [] }),
+      },
+    ];
+    const providers: ReadonlyArray<ServerProvider> = [
+      {
+        ...buildCodexProvider(defaultCodexModels),
+        instanceId: "codex" as ProviderInstanceId,
+        displayName: "Codex Work",
+        accentColor: "#2563eb",
+        continuation: { groupKey: "codex:home:/Users/julius/.codex" },
+      },
+      {
+        ...buildCodexProvider(personalCodexModels),
+        instanceId: "codex_personal" as ProviderInstanceId,
+        displayName: "Codex Personal",
+        accentColor: "#dc2626",
+        continuation: { groupKey: "codex:home:/Users/julius/.codex" },
+      },
+      {
+        ...buildCodexProvider(isolatedCodexModels),
+        instanceId: "codex_isolated" as ProviderInstanceId,
+        displayName: "Codex Isolated",
+        accentColor: "#16a34a",
+        continuation: { groupKey: "codex:home:/Users/julius/.codex_isolated" },
+      },
+      TEST_PROVIDERS[1]!,
+    ];
+    const mounted = await mountPicker({
+      activeInstanceId: "codex" as ProviderInstanceId,
+      model: "gpt-work",
+      lockedProvider: ProviderDriverKind.make("codex"),
+      lockedContinuationGroupKey: "codex:home:/Users/julius/.codex",
+      providers,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        expect(getSidebarProviderOrder()).toEqual(["codex", "codex_personal"]);
+        expect(getModelPickerListText()).not.toContain("Codex Isolated");
+        expect(
+          document.querySelector<HTMLElement>('[data-model-picker-provider="codex_personal"]')
+            ?.dataset.providerAccentColor,
+        ).toBe("#dc2626");
+        expect(getModelPickerListText()).toContain("Codex Work");
+        expect(getVisibleModelNames()).toEqual(["GPT Work"]);
+      });
+
+      await page.getByRole("button", { name: "Codex Personal" }).click();
+
+      await vi.waitFor(() => {
+        expect(getModelPickerListText()).toContain("Codex Personal");
+        expect(getVisibleModelNames()).toEqual(["GPT Personal"]);
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("falls back to the active provider's first model when props.model belongs to another provider (#1982)", async () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const onInstanceModelChange = vi.fn();
+    const modelOptionsByInstance = new Map<ProviderInstanceId, ReadonlyArray<ModelEsque>>([
+      [
+        "claudeAgent" as ProviderInstanceId,
+        [
+          { slug: "claude-opus-4-6", name: "Claude Opus 4.6" },
+          { slug: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
+        ],
+      ],
+      ["codex" as ProviderInstanceId, [{ slug: "gpt-5-codex", name: "GPT-5 Codex" }]],
+      ["cursor" as ProviderInstanceId, []],
+      ["opencode" as ProviderInstanceId, []],
+    ]);
+    const instanceEntries = sortProviderInstanceEntries(
+      deriveProviderInstanceEntries(TEST_PROVIDERS),
+    );
+    const screen = await render(
+      <ProviderModelPicker
+        activeInstanceId={"claudeAgent" as ProviderInstanceId}
+        model="gpt-5-codex"
+        lockedProvider={null}
+        instanceEntries={instanceEntries}
+        modelOptionsByInstance={modelOptionsByInstance}
+        onInstanceModelChange={onInstanceModelChange}
+      />,
+      { container: host },
+    );
+
+    try {
+      const trigger = document.querySelector<HTMLElement>(
+        '[data-chat-provider-model-picker="true"]',
+      );
+      expect(trigger).not.toBeNull();
+      const label = trigger?.textContent ?? "";
+      expect(label).not.toContain("gpt-5-codex");
+      expect(label).toContain("Claude Opus 4.6");
+    } finally {
+      await screen.unmount();
+      host.remove();
+    }
+  });
+
+  it("uses the trigger label for locked opencode rows", async () => {
+    const providers: ReadonlyArray<ServerProvider> = [
+      buildOpenCodeProvider([
+        {
+          slug: "github-copilot/claude-opus-4.5",
+          name: "Claude Opus 4.5",
+          subProvider: "GitHub Copilot",
+          shortName: "Opus 4.5",
+          isCustom: false,
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+            ],
+          }),
+        },
+      ]),
+    ];
+    const mounted = await mountPicker({
+      activeInstanceId: OPENCODE_INSTANCE_ID,
+      model: "github-copilot/claude-opus-4.5",
+      lockedProvider: ProviderDriverKind.make("opencode"),
+      providers,
+    });
+
+    try {
+      await vi.waitFor(() => {
+        const trigger = document.querySelector<HTMLElement>(
+          '[data-chat-provider-model-picker="true"]',
+        );
+        expect(trigger?.textContent).toContain("GitHub Copilot");
+        expect(trigger?.textContent).toContain("Opus 4.5");
+      });
+
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        expect(getVisibleModelNames()).toEqual(["GitHub Copilot · Opus 4.5"]);
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("searches models by name in flat list", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        const text = document.body.textContent ?? "";
+        expect(text).toContain("Claude Opus 4.6");
+        expect(text).not.toContain("GPT-5 Codex");
+      });
+
+      // Find and type in search box
+      const searchInput = page.getByPlaceholder("Search models...");
+      await searchInput.fill("claude");
+
+      await vi.waitFor(() => {
+        const text = document.body.textContent ?? "";
+        expect(text).toContain("Claude Opus 4.6");
+        expect(text).not.toContain("GPT-5 Codex");
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("supports arrow-key navigation in the model picker", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: ProviderDriverKind.make("claudeAgent"),
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      const searchInput = page.getByPlaceholder("Search models...");
+      await userEvent.click(searchInput);
+      await userEvent.keyboard("{ArrowDown}");
+      await vi.waitFor(() => {
+        const highlightedItem = document.querySelector<HTMLElement>(
+          '[data-slot="combobox-item"][data-highlighted]',
+        );
+        expect(highlightedItem).not.toBeNull();
+        expect(highlightedItem?.textContent).toContain("Claude Opus 4.6");
+      });
+      await userEvent.keyboard("{ArrowDown}");
+      await vi.waitFor(() => {
+        const highlightedItem = document.querySelector<HTMLElement>(
+          '[data-slot="combobox-item"][data-highlighted]',
+        );
+        expect(highlightedItem).not.toBeNull();
+        expect(highlightedItem?.textContent).toContain("Claude Sonnet 4.6");
+      });
+      await userEvent.keyboard("{Enter}");
+
+      expect(mounted.onProviderModelChange).toHaveBeenCalledWith(
+        "claudeAgent",
+        "claude-sonnet-4-6",
+      );
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("hides the provider sidebar while searching", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        expect(getSidebarProviderOrder().length).toBeGreaterThan(0);
+      });
 
-      const submenuRect = submenuPopup.getBoundingClientRect();
+      await page.getByPlaceholder("Search models...").fill("cla");
+
+      await vi.waitFor(() => {
+        expect(getSidebarProviderOrder()).toEqual([]);
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("closes the picker when escape is pressed in search", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      const searchInput = page.getByPlaceholder("Search models...");
+      await searchInput.click();
+      const searchInputElement = document.querySelector<HTMLInputElement>(
+        'input[placeholder="Search models..."]',
+      );
+      expect(searchInputElement).not.toBeNull();
+      searchInputElement!.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "Escape", bubbles: true }),
+      );
 
-      expect(submenuRect.left).toBeGreaterThanOrEqual(providerTriggerRect.right);
-      expect(submenuRect.left - providerTriggerRect.right).toBeGreaterThanOrEqual(2);
+      await vi.waitFor(() => {
+        expect(document.querySelector(".model-picker-list")).toBeNull();
+      });
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("shows models directly when the provider is locked mid-thread", async () => {
+  it("searches models by provider name", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
-      lockedProvider: "claudeAgent",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        const text = document.body.textContent ?? "";
+        expect(text).toContain("Claude Opus 4.6");
+        expect(text).not.toContain("GPT-5 Codex");
+      });
+
+      // Search by provider name
+      const searchInput = page.getByPlaceholder("Search models...");
+      await searchInput.fill("codex");
+
+      await vi.waitFor(() => {
+        const listText = getModelPickerListText();
+        expect(listText).toContain("GPT-5 Codex");
+        expect(listText).not.toContain("Claude Opus 4.6");
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("matches fuzzy multi-token queries across provider and model text", async () => {
+    const providers: ReadonlyArray<ServerProvider> = [
+      buildCodexProvider([
+        {
+          slug: "gpt-5-codex",
+          name: "GPT-5 Codex",
+          isCustom: false,
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+              booleanDescriptor("fastMode", "Fast Mode"),
+            ],
+          }),
+        },
+      ]),
+      buildOpenCodeProvider([
+        {
+          slug: "github-copilot/claude-opus-4.7",
+          name: "Claude Opus 4.7",
+          subProvider: "GitHub Copilot",
+          isCustom: false,
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+            ],
+          }),
+        },
+      ]),
+    ];
+    const mounted = await mountPicker({
+      activeInstanceId: OPENCODE_INSTANCE_ID,
+      model: "github-copilot/claude-opus-4.7",
+      lockedProvider: null,
+      providers,
+    });
+
+    try {
+      await page.getByRole("button").click();
+      await page.getByPlaceholder("Search models...").fill("coplt op");
+
+      await vi.waitFor(() => {
+        const listText = getModelPickerListText();
+        expect(listText).toContain("Claude Opus 4.7");
+        expect(listText).not.toContain("GPT-5 Codex");
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("renders each search result with its own provider branding", async () => {
+    const providers: ReadonlyArray<ServerProvider> = [
+      buildOpenCodeProvider([
+        {
+          slug: "github-copilot/claude-opus-4.7",
+          name: "Claude Opus 4.7",
+          subProvider: "GitHub Copilot",
+          isCustom: false,
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+            ],
+          }),
+        },
+      ]),
+      {
+        ...TEST_PROVIDERS[1]!,
+        models: [
+          {
+            slug: "claude-opus-4-6",
+            name: "Claude Opus 4.6",
+            isCustom: false,
+            capabilities: createModelCapabilities({
+              optionDescriptors: [
+                selectDescriptor("effort", "Reasoning", [
+                  { id: "low", label: "low" },
+                  { id: "medium", label: "medium", isDefault: true },
+                  { id: "high", label: "high" },
+                  { id: "max", label: "max" },
+                ]),
+                booleanDescriptor("thinking", "Thinking"),
+              ],
+            }),
+          },
+        ],
+      },
+    ];
+    const mounted = await mountPicker({
+      activeInstanceId: OPENCODE_INSTANCE_ID,
+      model: "github-copilot/claude-opus-4.7",
+      lockedProvider: null,
+      providers,
+    });
+
+    try {
+      await page.getByRole("button").click();
+      await page.getByPlaceholder("Search models...").fill("opus");
+
+      await vi.waitFor(() => {
+        const listText = getModelPickerListText();
+        expect(listText).toContain("OpenCode · GitHub Copilot");
+        expect(listText).toContain("Claude");
+        expect(listText).not.toContain("OpenCodeClaude Opus 4.6");
+      });
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("toggles favorite stars when clicked", async () => {
+    localStorage.removeItem("t3code:client-settings:v1");
+
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        const text = document.body.textContent ?? "";
+        expect(text).toContain("Claude Opus 4.6");
+      });
+
+      const getFirstStarButton = () => {
+        const starButton = document.querySelector<HTMLButtonElement>(
+          'button[aria-label*="favorites"]',
+        );
+        expect(starButton).not.toBeNull();
+        return starButton!;
+      };
+
+      const firstStar = getFirstStarButton();
+      const initialAriaLabel = firstStar.getAttribute("aria-label");
+      expect(
+        initialAriaLabel === "Add to favorites" || initialAriaLabel === "Remove from favorites",
+      ).toBe(true);
+
+      await page.getByRole("button", { name: initialAriaLabel! }).first().click();
+
+      const expectedAriaLabel =
+        initialAriaLabel === "Add to favorites" ? "Remove from favorites" : "Add to favorites";
+
+      await vi.waitFor(() => {
+        expect(getFirstStarButton().getAttribute("aria-label")).toBe(expectedAriaLabel);
+      });
+    } finally {
+      await mounted.cleanup();
+      localStorage.removeItem("t3code:client-settings:v1");
+    }
+  });
+
+  it("does not duplicate favorited models across favorites and all models sections", async () => {
+    localStorage.removeItem("t3code:client-settings:v1");
+
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+
+      await vi.waitFor(() => {
+        const text = document.body.textContent ?? "";
+        expect(text).toContain("Claude Opus 4.6");
+      });
+
+      const favoriteButton = page.getByRole("button", {
+        name: "Add to favorites",
+      });
+      await favoriteButton.first().click();
+
+      await vi.waitFor(async () => {
+        const favoritedModelRows = Array.from(
+          getModelPickerListElement().querySelectorAll<HTMLDivElement>("div.font-medium"),
+        ).filter((element) => element.textContent?.trim() === "Claude Opus 4.6");
+        expect(favoritedModelRows.length).toBe(1);
+      });
+    } finally {
+      await mounted.cleanup();
+      localStorage.removeItem("t3code:client-settings:v1");
+    }
+  });
+
+  it("shows favorited models first within the selected provider list", async () => {
+    localStorage.setItem(
+      "t3code:client-settings:v1",
+      JSON.stringify({
+        ...DEFAULT_CLIENT_SETTINGS,
+        favorites: [{ provider: "codex", model: "gpt-5.3-codex" }],
+      }),
+    );
+
+    const mounted = await mountPicker({
+      model: "gpt-5-codex",
+      lockedProvider: null,
+    });
+
+    try {
+      await page.getByRole("button").click();
+      await page.getByRole("button", { name: "Codex", exact: true }).click();
+
+      await vi.waitFor(() => {
+        expect(getVisibleModelNames().slice(0, 2)).toEqual(["GPT-5.3 Codex", "GPT-5 Codex"]);
+      });
+    } finally {
+      await mounted.cleanup();
+      localStorage.removeItem("t3code:client-settings:v1");
+    }
+  });
+
+  it("dispatches callback with correct provider and model when selected", async () => {
+    const mounted = await mountPicker({
+      activeInstanceId: CLAUDE_INSTANCE_ID,
+      model: "claude-opus-4-6",
+      lockedProvider: ProviderDriverKind.make("claudeAgent"),
     });
 
     try {
@@ -252,28 +1063,39 @@ describe("ProviderModelPicker", () => {
       await vi.waitFor(() => {
         const text = document.body.textContent ?? "";
         expect(text).toContain("Claude Sonnet 4.6");
-        expect(text).toContain("Claude Haiku 4.5");
-        expect(text).not.toContain("Codex");
       });
+
+      // Click on a model
+      const modelRow = page.getByText("Claude Sonnet 4.6").first();
+      await modelRow.click();
+
+      // Verify callback was called with correct values
+      expect(mounted.onProviderModelChange).toHaveBeenCalledWith(
+        "claudeAgent",
+        "claude-sonnet-4-6",
+      );
     } finally {
       await mounted.cleanup();
     }
   });
 
-  it("only shows codex spark when the server reports it for the account", async () => {
+  it("only shows codex spark when the server reports it", async () => {
     const providersWithoutSpark: ReadonlyArray<ServerProvider> = [
       buildCodexProvider([
         {
           slug: "gpt-5.3-codex",
           name: "GPT-5.3 Codex",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-            supportsFastMode: true,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+              booleanDescriptor("fastMode", "Fast Mode"),
+            ],
+          }),
         },
       ]),
       TEST_PROVIDERS[1]!,
@@ -284,40 +1106,44 @@ describe("ProviderModelPicker", () => {
           slug: "gpt-5.3-codex",
           name: "GPT-5.3 Codex",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-            supportsFastMode: true,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+              booleanDescriptor("fastMode", "Fast Mode"),
+            ],
+          }),
         },
         {
           slug: "gpt-5.3-codex-spark",
           name: "GPT-5.3 Codex Spark",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-            supportsFastMode: true,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+              booleanDescriptor("fastMode", "Fast Mode"),
+            ],
+          }),
         },
       ]),
       TEST_PROVIDERS[1]!,
     ];
 
     const hidden = await mountPicker({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
+      model: "gpt-5.3-codex",
       lockedProvider: null,
       providers: providersWithoutSpark,
     });
 
     try {
       await page.getByRole("button").click();
-      await page.getByRole("menuitem", { name: "Codex" }).hover();
 
       await vi.waitFor(() => {
         const text = document.body.textContent ?? "";
@@ -329,15 +1155,13 @@ describe("ProviderModelPicker", () => {
     }
 
     const visible = await mountPicker({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
+      model: "gpt-5.3-codex",
       lockedProvider: null,
       providers: providersWithSpark,
     });
 
     try {
       await page.getByRole("button").click();
-      await page.getByRole("menuitem", { name: "Codex" }).hover();
 
       await vi.waitFor(() => {
         expect(document.body.textContent ?? "").toContain("GPT-5.3 Codex Spark");
@@ -347,30 +1171,10 @@ describe("ProviderModelPicker", () => {
     }
   });
 
-  it("dispatches the canonical slug when a model is selected", async () => {
-    const mounted = await mountPicker({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
-      lockedProvider: "claudeAgent",
-    });
-
-    try {
-      await page.getByRole("button").click();
-      await page.getByRole("menuitemradio", { name: "Claude Sonnet 4.6" }).click();
-
-      expect(mounted.onProviderModelChange).toHaveBeenCalledWith(
-        "claudeAgent",
-        "claude-sonnet-4-6",
-      );
-    } finally {
-      await mounted.cleanup();
-    }
-  });
-
-  it("shows disabled providers as non-selectable entries", async () => {
+  it("shows disabled providers grayed out in sidebar", async () => {
     const disabledProviders = TEST_PROVIDERS.slice();
     const claudeIndex = disabledProviders.findIndex(
-      (provider) => provider.provider === "claudeAgent",
+      (provider) => provider.instanceId === ProviderInstanceId.make("claudeAgent"),
     );
     if (claudeIndex >= 0) {
       const claudeProvider = disabledProviders[claudeIndex]!;
@@ -380,8 +1184,8 @@ describe("ProviderModelPicker", () => {
         status: "disabled",
       };
     }
+
     const mounted = await mountPicker({
-      provider: "codex",
       model: "gpt-5-codex",
       lockedProvider: null,
       providers: disabledProviders,
@@ -392,9 +1196,9 @@ describe("ProviderModelPicker", () => {
 
       await vi.waitFor(() => {
         const text = document.body.textContent ?? "";
-        expect(text).toContain("Claude");
-        expect(text).toContain("Disabled");
-        expect(text).not.toContain("Claude Sonnet 4.6");
+        expect(text).toContain("GPT-5 Codex");
+        // Disabled provider should not have its models shown
+        expect(text).not.toContain("Claude Opus 4.6");
       });
     } finally {
       await mounted.cleanup();
@@ -403,7 +1207,6 @@ describe("ProviderModelPicker", () => {
 
   it("accepts outline trigger styling", async () => {
     const mounted = await mountPicker({
-      provider: "codex",
       model: "gpt-5-codex",
       lockedProvider: null,
       triggerVariant: "outline",
diff --git a/apps/web/src/components/chat/ProviderModelPicker.tsx b/apps/web/src/components/chat/ProviderModelPicker.tsx
index 01fa37516e5..4a2860ee469 100644
--- a/apps/web/src/components/chat/ProviderModelPicker.tsx
+++ b/apps/web/src/components/chat/ProviderModelPicker.tsx
@@ -1,89 +1,99 @@
-import { type ProviderKind, type ServerProvider } from "@t3tools/contracts";
-import { resolveSelectableModel } from "@t3tools/shared/model";
-import { memo, useState } from "react";
+import {
+  type ProviderInstanceId,
+  type ProviderDriverKind,
+  type ResolvedKeybindingsConfig,
+} from "@t3tools/contracts";
+import { memo, useEffect, useMemo, useState } from "react";
 import type { VariantProps } from "class-variance-authority";
-import { type ProviderPickerKind, PROVIDER_OPTIONS } from "../../session-logic";
 import { ChevronDownIcon } from "lucide-react";
 import { Button, buttonVariants } from "../ui/button";
-import {
-  Menu,
-  MenuGroup,
-  MenuItem,
-  MenuPopup,
-  MenuRadioGroup,
-  MenuRadioItem,
-  MenuSeparator as MenuDivider,
-  MenuSub,
-  MenuSubPopup,
-  MenuSubTrigger,
-  MenuTrigger,
-} from "../ui/menu";
-import { ClaudeAI, CursorIcon, Gemini, Icon, OpenAI, OpenCodeIcon } from "../Icons";
+import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { cn } from "~/lib/utils";
-import { getProviderSnapshot } from "../../providerModels";
-
-function isAvailableProviderOption(option: (typeof PROVIDER_OPTIONS)[number]): option is {
-  value: ProviderKind;
-  label: string;
-  available: true;
-} {
-  return option.available;
-}
-
-const PROVIDER_ICON_BY_PROVIDER: Record<ProviderPickerKind, Icon> = {
-  codex: OpenAI,
-  claudeAgent: ClaudeAI,
-  cursor: CursorIcon,
-};
-
-export const AVAILABLE_PROVIDER_OPTIONS = PROVIDER_OPTIONS.filter(isAvailableProviderOption);
-const UNAVAILABLE_PROVIDER_OPTIONS = PROVIDER_OPTIONS.filter((option) => !option.available);
-const COMING_SOON_PROVIDER_OPTIONS = [
-  { id: "opencode", label: "OpenCode", icon: OpenCodeIcon },
-  { id: "gemini", label: "Gemini", icon: Gemini },
-] as const;
-
-function providerIconClassName(
-  provider: ProviderKind | ProviderPickerKind,
-  fallbackClassName: string,
-): string {
-  return provider === "claudeAgent" ? "text-[#d97757]" : fallbackClassName;
-}
+import { ModelPickerContent } from "./ModelPickerContent";
+import { ProviderInstanceIcon } from "./ProviderInstanceIcon";
+import {
+  ModelEsque,
+  getTriggerDisplayModelLabel,
+  getTriggerDisplayModelName,
+} from "./providerIconUtils";
+import { setModelPickerOpen } from "../../modelPickerOpenState";
+import type { ProviderInstanceEntry } from "../../providerInstances";
 
 export const ProviderModelPicker = memo(function ProviderModelPicker(props: {
-  provider: ProviderKind;
+  /**
+   * The instance currently selected in the composer. Drives the trigger
+   * icon, label and the default-highlighted combobox row.
+   */
+  activeInstanceId: ProviderInstanceId;
   model: string;
-  lockedProvider: ProviderKind | null;
-  providers?: ReadonlyArray<ServerProvider>;
-  modelOptionsByProvider: Record<ProviderKind, ReadonlyArray<{ slug: string; name: string }>>;
+  lockedProvider: ProviderDriverKind | null;
+  lockedContinuationGroupKey?: string | null;
+  /** Instance entries rendered in the sidebar + used to resolve display name. */
+  instanceEntries: ReadonlyArray<ProviderInstanceEntry>;
+  keybindings?: ResolvedKeybindingsConfig;
+  modelOptionsByInstance: ReadonlyMap<ProviderInstanceId, ReadonlyArray<ModelEsque>>;
   activeProviderIconClassName?: string;
   compact?: boolean;
   disabled?: boolean;
+  terminalOpen?: boolean;
+  open?: boolean;
   triggerVariant?: VariantProps<typeof buttonVariants>["variant"];
   triggerClassName?: string;
-  onProviderModelChange: (provider: ProviderKind, model: string) => void;
+  onOpenChange?: (open: boolean) => void;
+  onInstanceModelChange: (instanceId: ProviderInstanceId, model: string) => void;
 }) {
-  const [isMenuOpen, setIsMenuOpen] = useState(false);
-  const activeProvider = props.lockedProvider ?? props.provider;
-  const selectedProviderOptions = props.modelOptionsByProvider[activeProvider];
-  const selectedModelLabel =
-    selectedProviderOptions.find((option) => option.slug === props.model)?.name ?? props.model;
-  const ProviderIcon = PROVIDER_ICON_BY_PROVIDER[activeProvider];
-  const handleModelChange = (provider: ProviderKind, value: string) => {
-    if (props.disabled) return;
-    if (!value) return;
-    const resolvedModel = resolveSelectableModel(
-      provider,
-      value,
-      props.modelOptionsByProvider[provider],
+  const [uncontrolledIsMenuOpen, setUncontrolledIsMenuOpen] = useState(false);
+  const isMenuOpen = props.open ?? uncontrolledIsMenuOpen;
+
+  // Resolve the active instance entry by exact routing key. The composer
+  // resolves fallbacks before rendering this component; if the selected
+  // instance disappears, do not infer a replacement from its driver kind.
+  const activeEntry = useMemo(() => {
+    return (
+      props.instanceEntries.find((entry) => entry.instanceId === props.activeInstanceId) ?? null
     );
-    if (!resolvedModel) return;
-    props.onProviderModelChange(provider, resolvedModel);
+  }, [props.activeInstanceId, props.instanceEntries]);
+
+  const activeInstanceId = props.activeInstanceId;
+  const selectedInstanceOptions = props.modelOptionsByInstance.get(activeInstanceId) ?? [];
+  // If the current slug belongs to a different instance (for example after
+  // a provider switch or disable), prefer the active instance's first
+  // option so the trigger icon and label stay in sync instead of showing
+  // a stale foreign slug.
+  const selectedModel =
+    selectedInstanceOptions.find((option) => option.slug === props.model) ??
+    selectedInstanceOptions[0];
+  const triggerTitle = selectedModel ? getTriggerDisplayModelName(selectedModel) : props.model;
+  const triggerSubtitle = selectedModel?.subProvider;
+  const triggerLabel = selectedModel ? getTriggerDisplayModelLabel(selectedModel) : props.model;
+  const duplicateDriverCount = props.instanceEntries.filter(
+    (entry) => activeEntry !== null && entry.driverKind === activeEntry.driverKind,
+  ).length;
+  const showInstanceBadge = Boolean(activeEntry?.accentColor) || duplicateDriverCount > 1;
+
+  const setIsMenuOpen = (open: boolean) => {
+    props.onOpenChange?.(open);
+    if (props.open === undefined) {
+      setUncontrolledIsMenuOpen(open);
+    }
+  };
+
+  useEffect(() => {
+    setModelPickerOpen(isMenuOpen);
+    return () => {
+      setModelPickerOpen(false);
+    };
+  }, [isMenuOpen]);
+
+  const handleInstanceModelChange = (instanceId: ProviderInstanceId, model: string) => {
+    if (props.disabled) return;
+    props.onInstanceModelChange(instanceId, model);
     setIsMenuOpen(false);
   };
 
   return (
-    <Menu
+    <Popover
       open={isMenuOpen}
       onOpenChange={(open) => {
         if (props.disabled) {
@@ -93,7 +103,7 @@ export const ProviderModelPicker = memo(function ProviderModelPicker(props: {
         setIsMenuOpen(open);
       }}
     >
-      <MenuTrigger
+      <PopoverTrigger
         render={
           <Button
             size="sm"
@@ -114,130 +124,64 @@ export const ProviderModelPicker = memo(function ProviderModelPicker(props: {
             props.compact ? "max-w-36 sm:pl-1" : undefined,
           )}
         >
-          <ProviderIcon
-            aria-hidden="true"
-            className={cn(
-              "size-4 shrink-0",
-              providerIconClassName(activeProvider, "text-muted-foreground/70"),
-              props.activeProviderIconClassName,
-            )}
-          />
-          <span className="min-w-0 flex-1 truncate">{selectedModelLabel}</span>
-          <ChevronDownIcon aria-hidden="true" className="size-3 shrink-0 opacity-60" />
-        </span>
-      </MenuTrigger>
-      <MenuPopup align="start">
-        {props.lockedProvider !== null ? (
-          <MenuGroup>
-            <MenuRadioGroup
-              value={props.model}
-              onValueChange={(value) => handleModelChange(props.lockedProvider!, value)}
-            >
-              {props.modelOptionsByProvider[props.lockedProvider].map((modelOption) => (
-                <MenuRadioItem
-                  key={`${props.lockedProvider}:${modelOption.slug}`}
-                  value={modelOption.slug}
-                  onClick={() => setIsMenuOpen(false)}
-                >
-                  {modelOption.name}
-                </MenuRadioItem>
-              ))}
-            </MenuRadioGroup>
-          </MenuGroup>
-        ) : (
-          <>
-            {AVAILABLE_PROVIDER_OPTIONS.map((option) => {
-              const OptionIcon = PROVIDER_ICON_BY_PROVIDER[option.value];
-              const liveProvider = props.providers
-                ? getProviderSnapshot(props.providers, option.value)
-                : undefined;
-              if (liveProvider && liveProvider.status !== "ready") {
-                const unavailableLabel = !liveProvider.enabled
-                  ? "Disabled"
-                  : !liveProvider.installed
-                    ? "Not installed"
-                    : "Unavailable";
-                return (
-                  <MenuItem key={option.value} disabled>
-                    <OptionIcon
-                      aria-hidden="true"
-                      className={cn(
-                        "size-4 shrink-0 opacity-80",
-                        providerIconClassName(option.value, "text-muted-foreground/85"),
-                      )}
-                    />
-                    <span>{option.label}</span>
-                    <span className="ms-auto text-[11px] text-muted-foreground/80 uppercase tracking-[0.08em]">
-                      {unavailableLabel}
-                    </span>
-                  </MenuItem>
-                );
+          {activeEntry ? (
+            <ProviderInstanceIcon
+              driverKind={activeEntry.driverKind}
+              displayName={activeEntry.displayName}
+              accentColor={activeEntry.accentColor}
+              showBadge={showInstanceBadge}
+              className={showInstanceBadge ? "size-5" : "size-4"}
+              iconClassName={cn("size-4", props.activeProviderIconClassName)}
+              badgeClassName="right-[-0.125rem] bottom-[-0.125rem] h-3 min-w-3 text-[7px]"
+            />
+          ) : null}
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <span
+                  className={cn(
+                    "min-w-0 flex-1 overflow-hidden",
+                    triggerSubtitle
+                      ? "grid grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-1"
+                      : "truncate",
+                  )}
+                />
               }
-              return (
-                <MenuSub key={option.value}>
-                  <MenuSubTrigger>
-                    <OptionIcon
-                      aria-hidden="true"
-                      className={cn(
-                        "size-4 shrink-0",
-                        providerIconClassName(option.value, "text-muted-foreground/85"),
-                      )}
-                    />
-                    {option.label}
-                  </MenuSubTrigger>
-                  <MenuSubPopup className="[--available-height:min(24rem,70vh)]" sideOffset={4}>
-                    <MenuGroup>
-                      <MenuRadioGroup
-                        value={props.provider === option.value ? props.model : ""}
-                        onValueChange={(value) => handleModelChange(option.value, value)}
-                      >
-                        {props.modelOptionsByProvider[option.value].map((modelOption) => (
-                          <MenuRadioItem
-                            key={`${option.value}:${modelOption.slug}`}
-                            value={modelOption.slug}
-                            onClick={() => setIsMenuOpen(false)}
-                          >
-                            {modelOption.name}
-                          </MenuRadioItem>
-                        ))}
-                      </MenuRadioGroup>
-                    </MenuGroup>
-                  </MenuSubPopup>
-                </MenuSub>
-              );
-            })}
-            {UNAVAILABLE_PROVIDER_OPTIONS.length > 0 && <MenuDivider />}
-            {UNAVAILABLE_PROVIDER_OPTIONS.map((option) => {
-              const OptionIcon = PROVIDER_ICON_BY_PROVIDER[option.value];
-              return (
-                <MenuItem key={option.value} disabled>
-                  <OptionIcon
-                    aria-hidden="true"
-                    className="size-4 shrink-0 text-muted-foreground/85 opacity-80"
-                  />
-                  <span>{option.label}</span>
-                  <span className="ms-auto text-[11px] text-muted-foreground/80 uppercase tracking-[0.08em]">
-                    Coming soon
-                  </span>
-                </MenuItem>
-              );
-            })}
-            {UNAVAILABLE_PROVIDER_OPTIONS.length === 0 && <MenuDivider />}
-            {COMING_SOON_PROVIDER_OPTIONS.map((option) => {
-              const OptionIcon = option.icon;
-              return (
-                <MenuItem key={option.id} disabled>
-                  <OptionIcon aria-hidden="true" className="size-4 shrink-0 opacity-80" />
-                  <span>{option.label}</span>
-                  <span className="ms-auto text-[11px] text-muted-foreground/80 uppercase tracking-[0.08em]">
-                    Coming soon
+            >
+              {triggerSubtitle ? (
+                <>
+                  <span className="min-w-0 truncate">{triggerSubtitle}</span>
+                  <span aria-hidden="true" className="shrink-0 opacity-60">
+                    ·
                   </span>
-                </MenuItem>
-              );
-            })}
-          </>
-        )}
-      </MenuPopup>
-    </Menu>
+                  <span className="min-w-0 truncate">{triggerTitle}</span>
+                </>
+              ) : (
+                triggerTitle
+              )}
+            </TooltipTrigger>
+            <TooltipPopup side="top">{triggerLabel}</TooltipPopup>
+          </Tooltip>
+          <ChevronDownIcon aria-hidden="true" className="size-3 shrink-0 opacity-60" />
+        </span>
+      </PopoverTrigger>
+      <PopoverPopup
+        align="start"
+        className="border-0 bg-transparent p-0 shadow-none before:hidden [--viewport-inline-padding:0] *:data-[slot=popover-viewport]:p-0"
+      >
+        <ModelPickerContent
+          activeInstanceId={activeInstanceId}
+          model={props.model}
+          lockedProvider={props.lockedProvider}
+          lockedContinuationGroupKey={props.lockedContinuationGroupKey ?? null}
+          instanceEntries={props.instanceEntries}
+          {...(props.keybindings ? { keybindings: props.keybindings } : {})}
+          modelOptionsByInstance={props.modelOptionsByInstance}
+          terminalOpen={props.terminalOpen ?? false}
+          onRequestClose={() => setIsMenuOpen(false)}
+          onInstanceModelChange={handleInstanceModelChange}
+        />
+      </PopoverPopup>
+    </Popover>
   );
 });
diff --git a/apps/web/src/components/chat/ProviderStatusBanner.tsx b/apps/web/src/components/chat/ProviderStatusBanner.tsx
index e709e75da37..a882942585f 100644
--- a/apps/web/src/components/chat/ProviderStatusBanner.tsx
+++ b/apps/web/src/components/chat/ProviderStatusBanner.tsx
@@ -1,7 +1,8 @@
-import { PROVIDER_DISPLAY_NAMES, type ServerProvider } from "@t3tools/contracts";
+import { type ServerProvider } from "@t3tools/contracts";
 import { memo } from "react";
 import { Alert, AlertDescription, AlertTitle } from "../ui/alert";
 import { CircleAlertIcon } from "lucide-react";
+import { formatProviderDriverKindLabel } from "../../providerModels";
 
 export const ProviderStatusBanner = memo(function ProviderStatusBanner({
   status,
@@ -12,7 +13,7 @@ export const ProviderStatusBanner = memo(function ProviderStatusBanner({
     return null;
   }
 
-  const providerLabel = PROVIDER_DISPLAY_NAMES[status.provider] ?? status.provider;
+  const providerLabel = status.displayName?.trim() || formatProviderDriverKindLabel(status.driver);
   const defaultMessage =
     status.status === "error"
       ? `${providerLabel} provider is unavailable.`
diff --git a/apps/web/src/components/chat/SkillInlineText.tsx b/apps/web/src/components/chat/SkillInlineText.tsx
new file mode 100644
index 00000000000..0c1abbd40dc
--- /dev/null
+++ b/apps/web/src/components/chat/SkillInlineText.tsx
@@ -0,0 +1,87 @@
+import { Children, cloneElement, isValidElement, type ReactNode } from "react";
+import type { ServerProviderSkill } from "@t3tools/contracts";
+
+import { formatProviderSkillDisplayName } from "../../providerSkillPresentation";
+import {
+  COMPOSER_INLINE_CHIP_ICON_CLASS_NAME,
+  COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME,
+  COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME,
+  SKILL_CHIP_ICON_SVG,
+} from "../composerInlineChip";
+
+const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+
+type InlineSkill = Pick<ServerProviderSkill, "name" | "displayName">;
+
+export function SkillInlineText(props: { text: string; skills: ReadonlyArray<InlineSkill> }) {
+  const nodes: ReactNode[] = [];
+  let cursor = 0;
+
+  for (const match of props.text.matchAll(SKILL_TOKEN_REGEX)) {
+    const prefix = match[1] ?? "";
+    const name = match[2] ?? "";
+    const start = (match.index ?? 0) + prefix.length;
+    const rawText = `$${name}`;
+    const skill = props.skills.find((candidate) => candidate.name === name);
+    if (!skill) {
+      continue;
+    }
+
+    if (start > cursor) {
+      nodes.push(props.text.slice(cursor, start));
+    }
+    nodes.push(<SkillChip key={`${start}:${name}`} skill={skill} rawText={rawText} />);
+    cursor = start + rawText.length;
+  }
+
+  if (cursor === 0) {
+    return <>{props.text}</>;
+  }
+  if (cursor < props.text.length) {
+    nodes.push(props.text.slice(cursor));
+  }
+  return <>{nodes}</>;
+}
+
+export function renderSkillInlineMarkdownChildren(
+  children: ReactNode,
+  skills: ReadonlyArray<InlineSkill>,
+): ReactNode {
+  return Children.map(children, (child) => {
+    if (typeof child === "string") {
+      return <SkillInlineText text={child} skills={skills} />;
+    }
+    if (!isValidElement<{ children?: ReactNode }>(child)) {
+      return child;
+    }
+    if (child.type === "code" || child.type === "a") {
+      return child;
+    }
+    if (!("children" in child.props)) {
+      return child;
+    }
+    return cloneElement(
+      child,
+      undefined,
+      renderSkillInlineMarkdownChildren(child.props.children, skills),
+    );
+  });
+}
+
+function SkillChip(props: { skill: InlineSkill; rawText: string }) {
+  return (
+    <span className="inline-flex align-middle leading-none">
+      <span className="sr-only">{props.rawText}</span>
+      <span aria-hidden="true" className={COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME}>
+        <span
+          aria-hidden="true"
+          className={COMPOSER_INLINE_CHIP_ICON_CLASS_NAME}
+          dangerouslySetInnerHTML={{ __html: SKILL_CHIP_ICON_SVG }}
+        />
+        <span className={COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME}>
+          {formatProviderSkillDisplayName(props.skill)}
+        </span>
+      </span>
+    </span>
+  );
+}
diff --git a/apps/web/src/components/chat/TraitsPicker.browser.tsx b/apps/web/src/components/chat/TraitsPicker.browser.tsx
deleted file mode 100644
index 686a36b60dd..00000000000
--- a/apps/web/src/components/chat/TraitsPicker.browser.tsx
+++ /dev/null
@@ -1,503 +0,0 @@
-import "../../index.css";
-
-import {
-  type ModelSelection,
-  ClaudeModelOptions,
-  CodexModelOptions,
-  DEFAULT_MODEL_BY_PROVIDER,
-  DEFAULT_SERVER_SETTINGS,
-  EnvironmentId,
-  type ServerProvider,
-  ThreadId,
-} from "@t3tools/contracts";
-import { scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
-import { page } from "vitest/browser";
-import { useCallback } from "react";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { render } from "vitest-browser-react";
-
-import { TraitsPicker } from "./TraitsPicker";
-import {
-  COMPOSER_DRAFT_STORAGE_KEY,
-  ComposerThreadDraftState,
-  useComposerDraftStore,
-  useComposerThreadDraft,
-  useEffectiveComposerModelState,
-} from "../../composerDraftStore";
-import { DEFAULT_CLIENT_SETTINGS } from "@t3tools/contracts/settings";
-
-// ── Claude TraitsPicker tests ─────────────────────────────────────────
-
-const LOCAL_ENVIRONMENT_ID = EnvironmentId.make("environment-local");
-const CLAUDE_THREAD_ID = ThreadId.make("thread-claude-traits");
-const CLAUDE_THREAD_REF = scopeThreadRef(LOCAL_ENVIRONMENT_ID, CLAUDE_THREAD_ID);
-const CLAUDE_THREAD_KEY = scopedThreadKey(CLAUDE_THREAD_REF);
-const CODEX_THREAD_ID = ThreadId.make("thread-codex-traits");
-const CODEX_THREAD_REF = scopeThreadRef(LOCAL_ENVIRONMENT_ID, CODEX_THREAD_ID);
-const CODEX_THREAD_KEY = scopedThreadKey(CODEX_THREAD_REF);
-const TEST_PROVIDERS: ReadonlyArray<ServerProvider> = [
-  {
-    provider: "codex",
-    enabled: true,
-    installed: true,
-    version: "0.1.0",
-    status: "ready",
-    auth: { status: "authenticated" },
-    checkedAt: "2026-01-01T00:00:00.000Z",
-    slashCommands: [],
-    skills: [],
-    models: [
-      {
-        slug: "gpt-5.4",
-        name: "GPT-5.4",
-        isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [
-            { value: "xhigh", label: "Extra High" },
-            { value: "high", label: "High", isDefault: true },
-          ],
-          supportsFastMode: true,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
-      },
-    ],
-  },
-  {
-    provider: "claudeAgent",
-    enabled: true,
-    installed: true,
-    version: "0.1.0",
-    status: "ready",
-    auth: { status: "authenticated" },
-    checkedAt: "2026-01-01T00:00:00.000Z",
-    slashCommands: [],
-    skills: [],
-    models: [
-      {
-        slug: "claude-opus-4-6",
-        name: "Claude Opus 4.6",
-        isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [
-            { value: "low", label: "Low" },
-            { value: "medium", label: "Medium" },
-            { value: "high", label: "High", isDefault: true },
-            { value: "max", label: "Max" },
-            { value: "ultrathink", label: "Ultrathink" },
-          ],
-          supportsFastMode: true,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: ["ultrathink"],
-        },
-      },
-      {
-        slug: "claude-sonnet-4-6",
-        name: "Claude Sonnet 4.6",
-        isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [
-            { value: "low", label: "Low" },
-            { value: "medium", label: "Medium" },
-            { value: "high", label: "High", isDefault: true },
-            { value: "ultrathink", label: "Ultrathink" },
-          ],
-          supportsFastMode: false,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: ["ultrathink"],
-        },
-      },
-      {
-        slug: "claude-haiku-4-5",
-        name: "Claude Haiku 4.5",
-        isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: false,
-          supportsThinkingToggle: true,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
-      },
-    ],
-  },
-];
-
-function ClaudeTraitsPickerHarness(props: {
-  model: string;
-  fallbackModelSelection: ModelSelection | null;
-  triggerVariant?: "ghost" | "outline";
-}) {
-  const prompt = useComposerThreadDraft(CLAUDE_THREAD_REF).prompt;
-  const setPrompt = useComposerDraftStore((store) => store.setPrompt);
-  const { modelOptions, selectedModel } = useEffectiveComposerModelState({
-    threadRef: CLAUDE_THREAD_REF,
-    providers: TEST_PROVIDERS,
-    selectedProvider: "claudeAgent",
-    threadModelSelection: props.fallbackModelSelection,
-    projectModelSelection: null,
-    settings: {
-      ...DEFAULT_SERVER_SETTINGS,
-      ...DEFAULT_CLIENT_SETTINGS,
-    },
-  });
-  const handlePromptChange = useCallback(
-    (nextPrompt: string) => {
-      setPrompt(CLAUDE_THREAD_REF, nextPrompt);
-    },
-    [setPrompt],
-  );
-
-  return (
-    <TraitsPicker
-      provider="claudeAgent"
-      models={TEST_PROVIDERS[1]!.models}
-      threadRef={CLAUDE_THREAD_REF}
-      model={selectedModel ?? props.model}
-      prompt={prompt}
-      modelOptions={modelOptions?.claudeAgent}
-      onPromptChange={handlePromptChange}
-      triggerVariant={props.triggerVariant}
-    />
-  );
-}
-
-async function mountClaudePicker(props?: {
-  model?: string;
-  prompt?: string;
-  options?: ClaudeModelOptions;
-  fallbackModelOptions?: {
-    effort?: "low" | "medium" | "high" | "max" | "ultrathink";
-    thinking?: boolean;
-    fastMode?: boolean;
-  } | null;
-  skipDraftModelOptions?: boolean;
-  triggerVariant?: "ghost" | "outline";
-}) {
-  const model = props?.model ?? "claude-opus-4-6";
-  const claudeOptions = !props?.skipDraftModelOptions ? props?.options : undefined;
-  const draftsByThreadKey: Record<string, ComposerThreadDraftState> = {
-    [CLAUDE_THREAD_KEY]: {
-      prompt: props?.prompt ?? "",
-      images: [],
-      nonPersistedImageIds: [],
-      persistedAttachments: [],
-      terminalContexts: [],
-      modelSelectionByProvider: props?.skipDraftModelOptions
-        ? {}
-        : {
-            claudeAgent: {
-              provider: "claudeAgent",
-              model,
-              ...(claudeOptions && Object.keys(claudeOptions).length > 0
-                ? { options: claudeOptions }
-                : {}),
-            },
-          },
-      activeProvider: "claudeAgent",
-      runtimeMode: null,
-      interactionMode: null,
-    },
-  };
-  useComposerDraftStore.setState({
-    draftsByThreadKey,
-    draftThreadsByThreadKey: {},
-    logicalProjectDraftThreadKeyByLogicalProjectKey: {},
-  });
-  const host = document.createElement("div");
-  document.body.append(host);
-  const fallbackModelSelection =
-    props?.fallbackModelOptions !== undefined
-      ? ({
-          provider: "claudeAgent",
-          model,
-          ...(props.fallbackModelOptions ? { options: props.fallbackModelOptions } : {}),
-        } satisfies ModelSelection)
-      : null;
-  const screen = await render(
-    <ClaudeTraitsPickerHarness
-      model={model}
-      fallbackModelSelection={fallbackModelSelection}
-      {...(props?.triggerVariant ? { triggerVariant: props.triggerVariant } : {})}
-    />,
-    { container: host },
-  );
-
-  const cleanup = async () => {
-    await screen.unmount();
-    host.remove();
-  };
-
-  return {
-    [Symbol.asyncDispose]: cleanup,
-    cleanup,
-  };
-}
-
-describe("TraitsPicker (Claude)", () => {
-  afterEach(() => {
-    document.body.innerHTML = "";
-    useComposerDraftStore.setState({
-      draftsByThreadKey: {},
-      draftThreadsByThreadKey: {},
-      logicalProjectDraftThreadKeyByLogicalProjectKey: {},
-      stickyModelSelectionByProvider: {},
-    });
-  });
-
-  it("shows fast mode controls for Opus", async () => {
-    await using _ = await mountClaudePicker();
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Fast Mode");
-      expect(text).toContain("off");
-      expect(text).toContain("on");
-    });
-  });
-
-  it("hides fast mode controls for non-Opus models", async () => {
-    await using _ = await mountClaudePicker({ model: "claude-sonnet-4-6" });
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      expect(document.body.textContent ?? "").not.toContain("Fast Mode");
-    });
-  });
-
-  it("shows only the provided effort options", async () => {
-    await using _ = await mountClaudePicker({
-      model: "claude-sonnet-4-6",
-    });
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Low");
-      expect(text).toContain("Medium");
-      expect(text).toContain("High");
-      expect(text).not.toContain("Max");
-      expect(text).toContain("Ultrathink");
-    });
-  });
-
-  it("shows a th  inking on/off dropdown for Haiku", async () => {
-    await using _ = await mountClaudePicker({
-      model: "claude-haiku-4-5",
-      options: { thinking: true },
-    });
-
-    await vi.waitFor(() => {
-      expect(document.body.textContent ?? "").toContain("Thinking On");
-    });
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Thinking");
-      expect(text).toContain("On (default)");
-      expect(text).toContain("Off");
-    });
-  });
-
-  it("shows prompt-controlled Ultrathink state with selectable effort controls", async () => {
-    await using _ = await mountClaudePicker({
-      model: "claude-opus-4-6",
-      options: { effort: "high" },
-      prompt: "Ultrathink:\nInvestigate this",
-    });
-
-    await vi.waitFor(() => {
-      expect(document.body.textContent ?? "").toContain("Ultrathink");
-      expect(document.body.textContent ?? "").not.toContain("Ultrathink · Prompt");
-    });
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Effort");
-      expect(text).not.toContain("ultrathink");
-    });
-  });
-
-  it("warns when ultrathink appears in prompt body text", async () => {
-    await using _ = await mountClaudePicker({
-      model: "claude-opus-4-6",
-      options: { effort: "high" },
-      prompt: "Ultrathink:\nplease ultrathink about this problem",
-    });
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain(
-        'Your prompt contains "ultrathink" in the text. Remove it to change effort.',
-      );
-    });
-  });
-
-  it("persists sticky claude model options when traits change", async () => {
-    await using _ = await mountClaudePicker({
-      model: "claude-opus-4-6",
-      options: { effort: "medium", fastMode: false },
-    });
-
-    await page.getByRole("button").click();
-    await page.getByRole("menuitemradio", { name: "Max" }).click();
-
-    expect(
-      useComposerDraftStore.getState().stickyModelSelectionByProvider.claudeAgent,
-    ).toMatchObject({
-      provider: "claudeAgent",
-      options: {
-        effort: "max",
-      },
-    });
-  });
-
-  it("accepts outline trigger styling", async () => {
-    await using _ = await mountClaudePicker({
-      triggerVariant: "outline",
-    });
-
-    const button = document.querySelector("button");
-    if (!(button instanceof HTMLButtonElement)) {
-      throw new Error("Expected traits trigger button to be rendered.");
-    }
-    expect(button.className).toContain("border-input");
-    expect(button.className).toContain("bg-popover");
-  });
-});
-
-// ── Codex TraitsPicker tests ──────────────────────────────────────────
-
-async function mountCodexPicker(props: { model?: string; options?: CodexModelOptions }) {
-  const model = props.model ?? DEFAULT_MODEL_BY_PROVIDER.codex;
-  const draftsByThreadKey: Record<string, ComposerThreadDraftState> = {
-    [CODEX_THREAD_KEY]: {
-      prompt: "",
-      images: [],
-      nonPersistedImageIds: [],
-      persistedAttachments: [],
-      terminalContexts: [],
-      modelSelectionByProvider: {
-        codex: {
-          provider: "codex",
-          model,
-          ...(props.options ? { options: props.options } : {}),
-        },
-      },
-      activeProvider: "codex",
-      runtimeMode: null,
-      interactionMode: null,
-    },
-  };
-
-  useComposerDraftStore.setState({
-    draftsByThreadKey,
-    draftThreadsByThreadKey: {},
-    logicalProjectDraftThreadKeyByLogicalProjectKey: {
-      "environment-local:project-codex-traits": CODEX_THREAD_KEY,
-    },
-  });
-  const host = document.createElement("div");
-  document.body.append(host);
-  const screen = await render(
-    <TraitsPicker
-      provider="codex"
-      models={TEST_PROVIDERS[0]!.models}
-      threadRef={CODEX_THREAD_REF}
-      model={props.model ?? DEFAULT_MODEL_BY_PROVIDER.codex}
-      prompt=""
-      modelOptions={props.options}
-      onPromptChange={() => {}}
-    />,
-    { container: host },
-  );
-
-  const cleanup = async () => {
-    await screen.unmount();
-    host.remove();
-  };
-
-  return {
-    [Symbol.asyncDispose]: cleanup,
-    cleanup,
-  };
-}
-
-describe("TraitsPicker (Codex)", () => {
-  afterEach(() => {
-    document.body.innerHTML = "";
-    localStorage.removeItem(COMPOSER_DRAFT_STORAGE_KEY);
-    useComposerDraftStore.setState({
-      draftsByThreadKey: {},
-      draftThreadsByThreadKey: {},
-      logicalProjectDraftThreadKeyByLogicalProjectKey: {},
-      stickyModelSelectionByProvider: {},
-    });
-  });
-
-  it("shows fast mode controls", async () => {
-    await using _ = await mountCodexPicker({
-      options: { fastMode: false },
-    });
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Fast Mode");
-      expect(text).toContain("off");
-      expect(text).toContain("on");
-    });
-  });
-
-  it("shows Fast in the trigger label when fast mode is active", async () => {
-    await using _ = await mountCodexPicker({
-      options: { fastMode: true },
-    });
-
-    await vi.waitFor(() => {
-      expect(document.body.textContent ?? "").toContain("High · Fast");
-    });
-  });
-
-  it("shows only the provided effort options", async () => {
-    await using _ = await mountCodexPicker({
-      options: { fastMode: false },
-    });
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Extra High");
-      expect(text).toContain("High");
-      expect(text).not.toContain("Low");
-      expect(text).not.toContain("Medium");
-    });
-  });
-
-  it("persists sticky codex model options when traits change", async () => {
-    await using _ = await mountCodexPicker({
-      options: { fastMode: false },
-    });
-
-    await page.getByRole("button").click();
-    await page.getByRole("menuitemradio", { name: "on" }).click();
-
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.codex).toMatchObject({
-      provider: "codex",
-      options: { fastMode: true },
-    });
-  });
-});
diff --git a/apps/web/src/components/chat/TraitsPicker.tsx b/apps/web/src/components/chat/TraitsPicker.tsx
index 14b5cdfb3cb..62caa323fd3 100644
--- a/apps/web/src/components/chat/TraitsPicker.tsx
+++ b/apps/web/src/components/chat/TraitsPicker.tsx
@@ -1,19 +1,17 @@
 import {
-  type ClaudeModelOptions,
-  type CodexModelOptions,
-  type ProviderKind,
-  type ProviderModelOptions,
+  type ProviderDriverKind,
+  type ProviderOptionDescriptor,
+  type ProviderOptionSelection,
   type ScopedThreadRef,
   type ServerProviderModel,
 } from "@t3tools/contracts";
 import {
   applyClaudePromptEffortPrefix,
+  buildProviderOptionSelectionsFromDescriptors,
+  getProviderOptionCurrentLabel,
+  getProviderOptionCurrentValue,
+  getProviderOptionDescriptors,
   isClaudeUltrathinkPrompt,
-  trimOrNull,
-  getDefaultEffort,
-  getDefaultContextWindow,
-  hasContextWindowOption,
-  resolveEffort,
 } from "@t3tools/shared/model";
 import { memo, useCallback, useState } from "react";
 import type { VariantProps } from "class-variance-authority";
@@ -32,7 +30,8 @@ import { useComposerDraftStore, DraftId } from "../../composerDraftStore";
 import { getProviderModelCapabilities } from "../../providerModels";
 import { cn } from "~/lib/utils";
 
-type ProviderOptions = ProviderModelOptions[ProviderKind];
+type ProviderOptions = ReadonlyArray<ProviderOptionSelection>;
+
 type TraitsPersistence =
   | {
       threadRef?: ScopedThreadRef;
@@ -46,39 +45,38 @@ type TraitsPersistence =
 
 const ULTRATHINK_PROMPT_PREFIX = "Ultrathink:\n";
 
-function getRawEffort(
-  provider: ProviderKind,
-  modelOptions: ProviderOptions | null | undefined,
-): string | null {
-  if (provider === "codex") {
-    return trimOrNull((modelOptions as CodexModelOptions | undefined)?.reasoningEffort);
-  }
-  return trimOrNull((modelOptions as ClaudeModelOptions | undefined)?.effort);
+function replaceDescriptorCurrentValue(
+  descriptors: ReadonlyArray<ProviderOptionDescriptor>,
+  descriptorId: string,
+  currentValue: string | boolean | undefined,
+): ReadonlyArray<ProviderOptionDescriptor> {
+  return descriptors.map((descriptor) =>
+    descriptor.id !== descriptorId
+      ? descriptor
+      : descriptor.type === "boolean"
+        ? {
+            ...descriptor,
+            ...(typeof currentValue === "boolean" ? { currentValue } : {}),
+          }
+        : {
+            ...descriptor,
+            ...(typeof currentValue === "string" ? { currentValue } : {}),
+          },
+  );
 }
 
-function getRawContextWindow(
-  provider: ProviderKind,
-  modelOptions: ProviderOptions | null | undefined,
+function getDescriptorStringValue(
+  descriptor: Extract<ProviderOptionDescriptor, { type: "select" }> | null,
 ): string | null {
-  if (provider === "claudeAgent") {
-    return trimOrNull((modelOptions as ClaudeModelOptions | undefined)?.contextWindow);
-  }
-  return null;
-}
-
-function buildNextOptions(
-  provider: ProviderKind,
-  modelOptions: ProviderOptions | null | undefined,
-  patch: Record<string, unknown>,
-): ProviderOptions {
-  if (provider === "codex") {
-    return { ...(modelOptions as CodexModelOptions | undefined), ...patch } as CodexModelOptions;
+  if (!descriptor) {
+    return null;
   }
-  return { ...(modelOptions as ClaudeModelOptions | undefined), ...patch } as ClaudeModelOptions;
+  const value = getProviderOptionCurrentValue(descriptor);
+  return typeof value === "string" ? value : null;
 }
 
 function getSelectedTraits(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   models: ReadonlyArray<ServerProviderModel>,
   model: string | null | undefined,
   prompt: string,
@@ -86,61 +84,118 @@ function getSelectedTraits(
   allowPromptInjectedEffort: boolean,
 ) {
   const caps = getProviderModelCapabilities(models, model, provider);
-  const effortLevels = allowPromptInjectedEffort
-    ? caps.reasoningEffortLevels
-    : caps.reasoningEffortLevels.filter(
-        (option) => !caps.promptInjectedEffortLevels.includes(option.value),
-      );
-
-  // Resolve effort from options (provider-specific key)
-  const rawEffort = getRawEffort(provider, modelOptions);
-  const effort = resolveEffort(caps, rawEffort) ?? null;
-
-  // Thinking toggle (only for models that support it)
-  const thinkingEnabled = caps.supportsThinkingToggle
-    ? ((modelOptions as ClaudeModelOptions | undefined)?.thinking ?? true)
-    : null;
-
-  // Fast mode
-  const fastModeEnabled =
-    caps.supportsFastMode &&
-    (modelOptions as { fastMode?: boolean } | undefined)?.fastMode === true;
-
-  // Context window
-  const contextWindowOptions = caps.contextWindowOptions;
-  const rawContextWindow = getRawContextWindow(provider, modelOptions);
-  const defaultContextWindow = getDefaultContextWindow(caps);
-  const contextWindow =
-    rawContextWindow && hasContextWindowOption(caps, rawContextWindow)
-      ? rawContextWindow
-      : defaultContextWindow;
+  const descriptors = getProviderOptionDescriptors({
+    caps,
+    selections: modelOptions,
+  });
+  const selectDescriptors = descriptors.filter(
+    (descriptor): descriptor is Extract<ProviderOptionDescriptor, { type: "select" }> =>
+      descriptor.type === "select",
+  );
+  const booleanDescriptors = descriptors.filter(
+    (descriptor): descriptor is Extract<ProviderOptionDescriptor, { type: "boolean" }> =>
+      descriptor.type === "boolean",
+  );
+  const primarySelectDescriptor = selectDescriptors[0] ?? null;
+  const contextWindowDescriptor =
+    selectDescriptors.find((descriptor) => descriptor.id === "contextWindow") ?? null;
+  const agentDescriptor = selectDescriptors.find((descriptor) => descriptor.id === "agent") ?? null;
+  const fastModeDescriptor =
+    booleanDescriptors.find((descriptor) => descriptor.id === "fastMode") ?? null;
+  const thinkingDescriptor =
+    booleanDescriptors.find((descriptor) => descriptor.id === "thinking") ?? null;
 
   // Prompt-controlled effort (e.g. ultrathink in prompt text)
   const ultrathinkPromptControlled =
     allowPromptInjectedEffort &&
-    caps.promptInjectedEffortLevels.length > 0 &&
+    (primarySelectDescriptor?.promptInjectedValues?.length ?? 0) > 0 &&
     isClaudeUltrathinkPrompt(prompt);
 
   // Check if "ultrathink" appears in the body text (not just our prefix)
   const ultrathinkInBodyText =
     ultrathinkPromptControlled && isClaudeUltrathinkPrompt(prompt.replace(/^Ultrathink:\s*/i, ""));
+  const effort =
+    (ultrathinkPromptControlled
+      ? "ultrathink"
+      : getDescriptorStringValue(primarySelectDescriptor)) ?? null;
+  const thinkingEnabled =
+    typeof thinkingDescriptor?.currentValue === "boolean" ? thinkingDescriptor.currentValue : null;
+  const fastModeEnabled =
+    typeof fastModeDescriptor?.currentValue === "boolean" ? fastModeDescriptor.currentValue : false;
+  const contextWindow = getDescriptorStringValue(contextWindowDescriptor);
+  const selectedAgent = getDescriptorStringValue(agentDescriptor);
+  const selectedAgentLabel = agentDescriptor
+    ? getProviderOptionCurrentLabel(agentDescriptor)
+    : null;
 
   return {
     caps,
+    descriptors,
+    selectDescriptors,
+    booleanDescriptors,
+    primarySelectDescriptor,
+    contextWindowDescriptor,
+    agentDescriptor,
+    fastModeDescriptor,
+    thinkingDescriptor,
     effort,
-    effortLevels,
     thinkingEnabled,
     fastModeEnabled,
-    contextWindowOptions,
     contextWindow,
-    defaultContextWindow,
     ultrathinkPromptControlled,
     ultrathinkInBodyText,
+    selectedAgent,
+    selectedAgentLabel,
   };
 }
 
+function getTraitsSectionVisibility(input: {
+  provider: ProviderDriverKind;
+  models: ReadonlyArray<ServerProviderModel>;
+  model: string | null | undefined;
+  prompt: string;
+  modelOptions: ProviderOptions | null | undefined;
+  allowPromptInjectedEffort?: boolean;
+}) {
+  const selected = getSelectedTraits(
+    input.provider,
+    input.models,
+    input.model,
+    input.prompt,
+    input.modelOptions,
+    input.allowPromptInjectedEffort ?? true,
+  );
+
+  const showEffort = selected.primarySelectDescriptor !== null;
+  const showThinking = selected.thinkingDescriptor !== null;
+  const showFastMode = selected.fastModeDescriptor !== null;
+  const showContextWindow = selected.contextWindowDescriptor !== null;
+  const showAgent = selected.agentDescriptor !== null;
+
+  return {
+    ...selected,
+    showEffort,
+    showThinking,
+    showFastMode,
+    showContextWindow,
+    showAgent,
+    hasAnyControls: showEffort || showThinking || showFastMode || showContextWindow || showAgent,
+  };
+}
+
+export function shouldRenderTraitsControls(input: {
+  provider: ProviderDriverKind;
+  models: ReadonlyArray<ServerProviderModel>;
+  model: string | null | undefined;
+  prompt: string;
+  modelOptions: ProviderOptions | null | undefined;
+  allowPromptInjectedEffort?: boolean;
+}): boolean {
+  return getTraitsSectionVisibility(input).hasAnyControls;
+}
+
 export interface TraitsMenuContentProps {
-  provider: ProviderKind;
+  provider: ProviderDriverKind;
   models: ReadonlyArray<ServerProviderModel>;
   model: string | null | undefined;
   prompt: string;
@@ -173,155 +228,115 @@ export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
         return;
       }
       setProviderModelOptions(threadTarget, provider, nextOptions, {
+        model,
         persistSticky: true,
       });
     },
-    [persistence, provider, setProviderModelOptions],
+    [model, persistence, provider, setProviderModelOptions],
   );
   const {
-    caps,
-    effort,
-    effortLevels,
-    thinkingEnabled,
-    fastModeEnabled,
-    contextWindowOptions,
-    contextWindow,
-    defaultContextWindow,
+    descriptors,
+    selectDescriptors,
+    booleanDescriptors,
+    primarySelectDescriptor,
     ultrathinkPromptControlled,
     ultrathinkInBodyText,
-  } = getSelectedTraits(provider, models, model, prompt, modelOptions, allowPromptInjectedEffort);
-  const defaultEffort = getDefaultEffort(caps);
+    hasAnyControls,
+  } = getTraitsSectionVisibility({
+    provider,
+    models,
+    model,
+    prompt,
+    modelOptions,
+    allowPromptInjectedEffort,
+  });
+  const updateDescriptors = (nextDescriptors: ReadonlyArray<ProviderOptionDescriptor>) => {
+    updateModelOptions(buildProviderOptionSelectionsFromDescriptors(nextDescriptors));
+  };
 
-  const handleEffortChange = useCallback(
-    (value: string) => {
-      if (!value) return;
-      const nextOption = effortLevels.find((option) => option.value === value);
-      if (!nextOption) return;
-      if (caps.promptInjectedEffortLevels.includes(nextOption.value)) {
-        const nextPrompt =
-          prompt.trim().length === 0
-            ? ULTRATHINK_PROMPT_PREFIX
-            : applyClaudePromptEffortPrefix(prompt, "ultrathink");
-        onPromptChange(nextPrompt);
-        return;
-      }
-      if (ultrathinkInBodyText) return;
-      if (ultrathinkPromptControlled) {
-        const stripped = prompt.replace(/^Ultrathink:\s*/i, "");
-        onPromptChange(stripped);
-      }
-      const effortKey = provider === "codex" ? "reasoningEffort" : "effort";
-      updateModelOptions(
-        buildNextOptions(provider, modelOptions, { [effortKey]: nextOption.value }),
-      );
-    },
-    [
-      ultrathinkPromptControlled,
-      ultrathinkInBodyText,
-      modelOptions,
-      onPromptChange,
-      updateModelOptions,
-      effortLevels,
-      prompt,
-      caps.promptInjectedEffortLevels,
-      provider,
-    ],
-  );
+  const handleSelectChange = (
+    descriptor: Extract<ProviderOptionDescriptor, { type: "select" }>,
+    value: string,
+  ) => {
+    if (!value) return;
+    if (descriptor.promptInjectedValues?.includes(value)) {
+      const nextPrompt =
+        prompt.trim().length === 0
+          ? ULTRATHINK_PROMPT_PREFIX
+          : applyClaudePromptEffortPrefix(prompt, "ultrathink");
+      onPromptChange(nextPrompt);
+      return;
+    }
+    if (ultrathinkInBodyText && descriptor.id === primarySelectDescriptor?.id) return;
+    if (ultrathinkPromptControlled && descriptor.id === primarySelectDescriptor?.id) {
+      const stripped = prompt.replace(/^Ultrathink:\s*/i, "");
+      onPromptChange(stripped);
+    }
+    updateDescriptors(replaceDescriptorCurrentValue(descriptors, descriptor.id, value));
+  };
 
-  if (effort === null && thinkingEnabled === null && contextWindowOptions.length <= 1) {
+  if (!hasAnyControls) {
     return null;
   }
 
   return (
     <>
-      {effort ? (
-        <>
+      {selectDescriptors.map((descriptor, index) => (
+        <div key={descriptor.id}>
+          {index > 0 ? <MenuDivider /> : null}
           <MenuGroup>
-            <div className="px-2 pt-1.5 pb-1 font-medium text-muted-foreground text-xs">Effort</div>
-            {ultrathinkInBodyText ? (
+            <div className="px-2 pt-1.5 pb-1 font-medium text-muted-foreground text-xs">
+              {descriptor.label}
+            </div>
+            {ultrathinkInBodyText && descriptor.id === primarySelectDescriptor?.id ? (
               <div className="px-2 pb-1.5 text-muted-foreground/80 text-xs">
-                Your prompt contains &quot;ultrathink&quot; in the text. Remove it to change effort.
+                Your prompt contains &quot;ultrathink&quot; in the text. Remove it to change this
+                option.
               </div>
             ) : null}
             <MenuRadioGroup
-              value={ultrathinkPromptControlled ? "ultrathink" : effort}
-              onValueChange={handleEffortChange}
+              value={
+                ultrathinkPromptControlled && descriptor.id === primarySelectDescriptor?.id
+                  ? "ultrathink"
+                  : (getDescriptorStringValue(descriptor) ?? "")
+              }
+              onValueChange={(value) => handleSelectChange(descriptor, value)}
             >
-              {effortLevels.map((option) => (
+              {descriptor.options.map((option) => (
                 <MenuRadioItem
-                  key={option.value}
-                  value={option.value}
-                  disabled={ultrathinkInBodyText}
+                  key={option.id}
+                  value={option.id}
+                  disabled={ultrathinkInBodyText && descriptor.id === primarySelectDescriptor?.id}
                 >
                   {option.label}
-                  {option.value === defaultEffort ? " (default)" : ""}
+                  {option.isDefault ? " (default)" : ""}
                 </MenuRadioItem>
               ))}
             </MenuRadioGroup>
           </MenuGroup>
-        </>
-      ) : thinkingEnabled !== null ? (
-        <MenuGroup>
-          <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Thinking</div>
-          <MenuRadioGroup
-            value={thinkingEnabled ? "on" : "off"}
-            onValueChange={(value) => {
-              updateModelOptions(
-                buildNextOptions(provider, modelOptions, { thinking: value === "on" }),
-              );
-            }}
-          >
-            <MenuRadioItem value="on">On (default)</MenuRadioItem>
-            <MenuRadioItem value="off">Off</MenuRadioItem>
-          </MenuRadioGroup>
-        </MenuGroup>
-      ) : null}
-      {caps.supportsFastMode ? (
-        <>
-          <MenuDivider />
-          <MenuGroup>
-            <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Fast Mode</div>
-            <MenuRadioGroup
-              value={fastModeEnabled ? "on" : "off"}
-              onValueChange={(value) => {
-                updateModelOptions(
-                  buildNextOptions(provider, modelOptions, { fastMode: value === "on" }),
-                );
-              }}
-            >
-              <MenuRadioItem value="off">off</MenuRadioItem>
-              <MenuRadioItem value="on">on</MenuRadioItem>
-            </MenuRadioGroup>
-          </MenuGroup>
-        </>
-      ) : null}
-      {contextWindowOptions.length > 1 ? (
-        <>
-          <MenuDivider />
+        </div>
+      ))}
+      {booleanDescriptors.map((descriptor, index) => (
+        <div key={descriptor.id}>
+          {index > 0 || selectDescriptors.length > 0 ? <MenuDivider /> : null}
           <MenuGroup>
             <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">
-              Context Window
+              {descriptor.label}
             </div>
             <MenuRadioGroup
-              value={contextWindow ?? defaultContextWindow ?? ""}
+              value={descriptor.currentValue === true ? "on" : "off"}
               onValueChange={(value) => {
-                updateModelOptions(
-                  buildNextOptions(provider, modelOptions, {
-                    contextWindow: value,
-                  }),
+                updateDescriptors(
+                  replaceDescriptorCurrentValue(descriptors, descriptor.id, value === "on"),
                 );
               }}
             >
-              {contextWindowOptions.map((option) => (
-                <MenuRadioItem key={option.value} value={option.value}>
-                  {option.label}
-                  {option.value === defaultContextWindow ? " (default)" : ""}
-                </MenuRadioItem>
-              ))}
+              <MenuRadioItem value="on">On</MenuRadioItem>
+              <MenuRadioItem value="off">Off</MenuRadioItem>
             </MenuRadioGroup>
           </MenuGroup>
-        </>
-      ) : null}
+        </div>
+      ))}
     </>
   );
 });
@@ -339,38 +354,44 @@ export const TraitsPicker = memo(function TraitsPicker({
   ...persistence
 }: TraitsMenuContentProps & TraitsPersistence) {
   const [isMenuOpen, setIsMenuOpen] = useState(false);
-  const {
-    caps,
-    effort,
-    effortLevels,
-    thinkingEnabled,
-    fastModeEnabled,
-    contextWindowOptions,
-    contextWindow,
-    defaultContextWindow,
-    ultrathinkPromptControlled,
-  } = getSelectedTraits(provider, models, model, prompt, modelOptions, allowPromptInjectedEffort);
+  const { descriptors, primarySelectDescriptor, ultrathinkPromptControlled } =
+    getTraitsSectionVisibility({
+      provider,
+      models,
+      model,
+      prompt,
+      modelOptions,
+      allowPromptInjectedEffort,
+    });
+  if (
+    !shouldRenderTraitsControls({
+      provider,
+      models,
+      model,
+      prompt,
+      modelOptions,
+      allowPromptInjectedEffort,
+    })
+  ) {
+    return null;
+  }
 
-  const effortLabel = effort
-    ? (effortLevels.find((l) => l.value === effort)?.label ?? effort)
-    : null;
-  const contextWindowLabel =
-    contextWindowOptions.length > 1 && contextWindow !== defaultContextWindow
-      ? (contextWindowOptions.find((o) => o.value === contextWindow)?.label ?? null)
-      : null;
-  const triggerLabel = [
-    ultrathinkPromptControlled
-      ? "Ultrathink"
-      : effortLabel
-        ? effortLabel
-        : thinkingEnabled === null
-          ? null
-          : `Thinking ${thinkingEnabled ? "On" : "Off"}`,
-    ...(caps.supportsFastMode && fastModeEnabled ? ["Fast"] : []),
-    ...(contextWindowLabel ? [contextWindowLabel] : []),
-  ]
-    .filter(Boolean)
-    .join(" · ");
+  const triggerLabel =
+    descriptors
+      .map((descriptor) => {
+        if (ultrathinkPromptControlled && descriptor.id === primarySelectDescriptor?.id) {
+          return "Ultrathink";
+        }
+        if (descriptor.type === "boolean") {
+          if (descriptor.id === "fastMode") {
+            return descriptor.currentValue === true ? "Fast" : "Normal";
+          }
+          return `${descriptor.label} ${descriptor.currentValue === true ? "On" : "Off"}`;
+        }
+        return getProviderOptionCurrentLabel(descriptor);
+      })
+      .filter((label): label is string => typeof label === "string" && label.length > 0)
+      .join(" · ") || "";
 
   const isCodexStyle = provider === "codex";
 
diff --git a/apps/web/src/components/chat/composerProviderRegistry.test.tsx b/apps/web/src/components/chat/composerProviderRegistry.test.tsx
deleted file mode 100644
index 17351178379..00000000000
--- a/apps/web/src/components/chat/composerProviderRegistry.test.tsx
+++ /dev/null
@@ -1,451 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { ServerProviderModel } from "@t3tools/contracts";
-import {
-  getComposerProviderState,
-  renderProviderTraitsMenuContent,
-  renderProviderTraitsPicker,
-} from "./composerProviderRegistry";
-
-const CODEX_MODELS: ReadonlyArray<ServerProviderModel> = [
-  {
-    slug: "gpt-5.4",
-    name: "GPT-5.4",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "xhigh", label: "Extra High" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "medium", label: "Medium" },
-        { value: "low", label: "Low" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-];
-
-const CLAUDE_MODELS: ReadonlyArray<ServerProviderModel> = [
-  {
-    slug: "claude-opus-4-6",
-    name: "Claude Opus 4.6",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "max", label: "Max" },
-        { value: "ultrathink", label: "Ultrathink" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: ["ultrathink"],
-    },
-  },
-  {
-    slug: "claude-sonnet-4-6",
-    name: "Claude Sonnet 4.6",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "ultrathink", label: "Ultrathink" },
-      ],
-      supportsFastMode: false,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: ["ultrathink"],
-    },
-  },
-  {
-    slug: "claude-haiku-4-5",
-    name: "Claude Haiku 4.5",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [],
-      supportsFastMode: false,
-      supportsThinkingToggle: true,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-];
-
-const CLAUDE_MODELS_WITH_CONTEXT_WINDOW: ReadonlyArray<ServerProviderModel> = [
-  {
-    slug: "claude-opus-4-6",
-    name: "Claude Opus 4.6",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "max", label: "Max" },
-        { value: "ultrathink", label: "Ultrathink" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [
-        { value: "200k", label: "200k", isDefault: true },
-        { value: "1m", label: "1M" },
-      ],
-      promptInjectedEffortLevels: ["ultrathink"],
-    },
-  },
-  {
-    slug: "claude-haiku-4-5",
-    name: "Claude Haiku 4.5",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [],
-      supportsFastMode: false,
-      supportsThinkingToggle: true,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    },
-  },
-];
-
-describe("getComposerProviderState", () => {
-  it("returns codex defaults when no codex draft options exist", () => {
-    const state = getComposerProviderState({
-      provider: "codex",
-      model: "gpt-5.4",
-      models: CODEX_MODELS,
-      prompt: "",
-      modelOptions: undefined,
-    });
-
-    expect(state).toEqual({
-      provider: "codex",
-      promptEffort: "high",
-      modelOptionsForDispatch: {
-        reasoningEffort: "high",
-      },
-    });
-  });
-
-  it("normalizes codex dispatch options while preserving the selected effort", () => {
-    const state = getComposerProviderState({
-      provider: "codex",
-      model: "gpt-5.4",
-      models: CODEX_MODELS,
-      prompt: "",
-      modelOptions: {
-        codex: {
-          reasoningEffort: "low",
-          fastMode: true,
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "codex",
-      promptEffort: "low",
-      modelOptionsForDispatch: {
-        reasoningEffort: "low",
-        fastMode: true,
-      },
-    });
-  });
-
-  it("preserves codex fast mode when it is the only active option", () => {
-    const state = getComposerProviderState({
-      provider: "codex",
-      model: "gpt-5.4",
-      models: CODEX_MODELS,
-      prompt: "",
-      modelOptions: {
-        codex: {
-          fastMode: true,
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "codex",
-      promptEffort: "high",
-      modelOptionsForDispatch: {
-        reasoningEffort: "high",
-        fastMode: true,
-      },
-    });
-  });
-
-  it("preserves codex default effort explicitly in dispatch options", () => {
-    const state = getComposerProviderState({
-      provider: "codex",
-      model: "gpt-5.4",
-      models: CODEX_MODELS,
-      prompt: "",
-      modelOptions: {
-        codex: {
-          reasoningEffort: "high",
-          fastMode: false,
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "codex",
-      promptEffort: "high",
-      modelOptionsForDispatch: {
-        reasoningEffort: "high",
-        fastMode: false,
-      },
-    });
-  });
-
-  it("returns Claude defaults for effort-capable models", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-sonnet-4-6",
-      models: CLAUDE_MODELS,
-      prompt: "",
-      modelOptions: undefined,
-    });
-
-    expect(state).toEqual({
-      provider: "claudeAgent",
-      promptEffort: "high",
-      modelOptionsForDispatch: {
-        effort: "high",
-      },
-    });
-  });
-
-  it("tracks Claude ultrathink from the prompt without changing dispatch effort", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-sonnet-4-6",
-      models: CLAUDE_MODELS,
-      prompt: "Ultrathink:\nInvestigate this failure",
-      modelOptions: {
-        claudeAgent: {
-          effort: "medium",
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "claudeAgent",
-      promptEffort: "medium",
-      modelOptionsForDispatch: {
-        effort: "medium",
-      },
-      composerFrameClassName: "ultrathink-frame",
-      composerSurfaceClassName: "shadow-[0_0_0_1px_rgba(255,255,255,0.04)_inset]",
-      modelPickerIconClassName: "ultrathink-chroma",
-    });
-  });
-
-  it("drops unsupported Claude effort options for models without effort controls", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-haiku-4-5",
-      models: CLAUDE_MODELS,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          effort: "max",
-          thinking: false,
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "claudeAgent",
-      promptEffort: null,
-      modelOptionsForDispatch: {
-        thinking: false,
-      },
-    });
-  });
-
-  it("preserves Claude fast mode when it is the only active option", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
-      models: CLAUDE_MODELS,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          fastMode: true,
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "claudeAgent",
-      promptEffort: "high",
-      modelOptionsForDispatch: {
-        effort: "high",
-        fastMode: true,
-      },
-    });
-  });
-
-  it("preserves Claude default effort explicitly in dispatch options", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
-      models: CLAUDE_MODELS,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          effort: "high",
-          fastMode: false,
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "claudeAgent",
-      promptEffort: "high",
-      modelOptionsForDispatch: {
-        effort: "high",
-        fastMode: false,
-      },
-    });
-  });
-
-  it("preserves explicit fastMode: false so deepMerge can overwrite a prior true", () => {
-    // Regression: normalizeClaudeModelOptionsWithCapabilities used to strip
-    // fastMode: false, which meant deepMerge could never clear a previous true.
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
-      models: CLAUDE_MODELS,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          effort: "high",
-          fastMode: false,
-        },
-      },
-    });
-
-    expect(state.modelOptionsForDispatch).toHaveProperty("fastMode", false);
-  });
-
-  it("preserves explicit thinking: true so deepMerge can overwrite a prior false", () => {
-    // Regression: thinking: true (the default) used to be stripped, which
-    // meant deepMerge could never clear a previous thinking: false.
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-haiku-4-5",
-      models: CLAUDE_MODELS,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          thinking: true,
-        },
-      },
-    });
-
-    expect(state.modelOptionsForDispatch).toHaveProperty("thinking", true);
-  });
-
-  it("preserves Claude default context window explicitly in dispatch options", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
-      models: CLAUDE_MODELS_WITH_CONTEXT_WINDOW,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          effort: "high",
-          contextWindow: "200k",
-        },
-      },
-    });
-
-    expect(state.modelOptionsForDispatch).toMatchObject({
-      effort: "high",
-      contextWindow: "200k",
-    });
-  });
-
-  it("preserves explicit contextWindow default so deepMerge can overwrite a prior 1m", () => {
-    // Regression: the default contextWindow must survive normalization so
-    // deepMerge can clear an older non-default 1m selection.
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-opus-4-6",
-      models: CLAUDE_MODELS_WITH_CONTEXT_WINDOW,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          contextWindow: "200k",
-        },
-      },
-    });
-
-    expect(state.modelOptionsForDispatch).toHaveProperty("contextWindow", "200k");
-  });
-
-  it("omits contextWindow when the model does not support it", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-haiku-4-5",
-      models: CLAUDE_MODELS_WITH_CONTEXT_WINDOW,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          contextWindow: "1m",
-        },
-      },
-    });
-
-    expect(state.modelOptionsForDispatch).toBeUndefined();
-  });
-
-  it("omits fastMode when the model does not support it", () => {
-    const state = getComposerProviderState({
-      provider: "claudeAgent",
-      model: "claude-sonnet-4-6",
-      models: CLAUDE_MODELS,
-      prompt: "",
-      modelOptions: {
-        claudeAgent: {
-          effort: "high",
-          fastMode: true,
-        },
-      },
-    });
-
-    expect(state.modelOptionsForDispatch).not.toHaveProperty("fastMode");
-  });
-});
-
-describe("provider traits render guards", () => {
-  it("returns null for codex traits picker when no thread target is provided", () => {
-    const content = renderProviderTraitsPicker({
-      provider: "codex",
-      model: "gpt-5.4",
-      models: CODEX_MODELS,
-      modelOptions: undefined,
-      prompt: "",
-      onPromptChange: () => {},
-    });
-
-    expect(content).toBeNull();
-  });
-
-  it("returns null for claude traits menu content when no thread target is provided", () => {
-    const content = renderProviderTraitsMenuContent({
-      provider: "claudeAgent",
-      model: "claude-sonnet-4-6",
-      models: CLAUDE_MODELS,
-      modelOptions: undefined,
-      prompt: "",
-      onPromptChange: () => {},
-    });
-
-    expect(content).toBeNull();
-  });
-});
diff --git a/apps/web/src/components/chat/composerProviderRegistry.tsx b/apps/web/src/components/chat/composerProviderRegistry.tsx
deleted file mode 100644
index 74d8d85cffb..00000000000
--- a/apps/web/src/components/chat/composerProviderRegistry.tsx
+++ /dev/null
@@ -1,240 +0,0 @@
-import {
-  type ProviderKind,
-  type ProviderModelOptions,
-  type ScopedThreadRef,
-  type ServerProviderModel,
-} from "@t3tools/contracts";
-import { isClaudeUltrathinkPrompt, resolveEffort } from "@t3tools/shared/model";
-import type { ReactNode } from "react";
-import type { DraftId } from "../../composerDraftStore";
-import { getProviderModelCapabilities } from "../../providerModels";
-import { TraitsMenuContent, TraitsPicker } from "./TraitsPicker";
-import {
-  normalizeClaudeModelOptionsWithCapabilities,
-  normalizeCodexModelOptionsWithCapabilities,
-} from "@t3tools/shared/model";
-
-export type ComposerProviderStateInput = {
-  provider: ProviderKind;
-  model: string;
-  models: ReadonlyArray<ServerProviderModel>;
-  prompt: string;
-  modelOptions: ProviderModelOptions | null | undefined;
-};
-
-export type ComposerProviderState = {
-  provider: ProviderKind;
-  promptEffort: string | null;
-  modelOptionsForDispatch: ProviderModelOptions[ProviderKind] | undefined;
-  composerFrameClassName?: string;
-  composerSurfaceClassName?: string;
-  modelPickerIconClassName?: string;
-};
-
-type ProviderRegistryEntry = {
-  getState: (input: ComposerProviderStateInput) => ComposerProviderState;
-  renderTraitsMenuContent: (input: {
-    threadRef?: ScopedThreadRef;
-    draftId?: DraftId;
-    model: string;
-    models: ReadonlyArray<ServerProviderModel>;
-    modelOptions: ProviderModelOptions[ProviderKind] | undefined;
-    prompt: string;
-    onPromptChange: (prompt: string) => void;
-  }) => ReactNode;
-  renderTraitsPicker: (input: {
-    threadRef?: ScopedThreadRef;
-    draftId?: DraftId;
-    model: string;
-    models: ReadonlyArray<ServerProviderModel>;
-    modelOptions: ProviderModelOptions[ProviderKind] | undefined;
-    prompt: string;
-    onPromptChange: (prompt: string) => void;
-  }) => ReactNode;
-};
-
-function hasComposerTraitsTarget(input: {
-  threadRef: ScopedThreadRef | undefined;
-  draftId: DraftId | undefined;
-}): boolean {
-  return input.threadRef !== undefined || input.draftId !== undefined;
-}
-
-function getProviderStateFromCapabilities(
-  input: ComposerProviderStateInput,
-): ComposerProviderState {
-  const { provider, model, models, prompt, modelOptions } = input;
-  const caps = getProviderModelCapabilities(models, model, provider);
-  const providerOptions = modelOptions?.[provider];
-
-  // Resolve effort
-  const rawEffort = providerOptions
-    ? "effort" in providerOptions
-      ? providerOptions.effort
-      : "reasoningEffort" in providerOptions
-        ? providerOptions.reasoningEffort
-        : null
-    : null;
-
-  const promptEffort = resolveEffort(caps, rawEffort) ?? null;
-
-  // Normalize options for dispatch
-  const normalizedOptions =
-    provider === "codex"
-      ? normalizeCodexModelOptionsWithCapabilities(caps, providerOptions)
-      : normalizeClaudeModelOptionsWithCapabilities(caps, providerOptions);
-
-  // Ultrathink styling (driven by capabilities data, not provider identity)
-  const ultrathinkActive =
-    caps.promptInjectedEffortLevels.length > 0 && isClaudeUltrathinkPrompt(prompt);
-
-  return {
-    provider,
-    promptEffort,
-    modelOptionsForDispatch: normalizedOptions,
-    ...(ultrathinkActive ? { composerFrameClassName: "ultrathink-frame" } : {}),
-    ...(ultrathinkActive
-      ? { composerSurfaceClassName: "shadow-[0_0_0_1px_rgba(255,255,255,0.04)_inset]" }
-      : {}),
-    ...(ultrathinkActive ? { modelPickerIconClassName: "ultrathink-chroma" } : {}),
-  };
-}
-
-const composerProviderRegistry: Record<ProviderKind, ProviderRegistryEntry> = {
-  codex: {
-    getState: (input) => getProviderStateFromCapabilities(input),
-    renderTraitsMenuContent: ({
-      threadRef,
-      draftId,
-      model,
-      models,
-      modelOptions,
-      prompt,
-      onPromptChange,
-    }) =>
-      !hasComposerTraitsTarget({ threadRef, draftId }) ? null : (
-        <TraitsMenuContent
-          provider="codex"
-          models={models}
-          {...(threadRef ? { threadRef } : {})}
-          {...(draftId ? { draftId } : {})}
-          model={model}
-          modelOptions={modelOptions}
-          prompt={prompt}
-          onPromptChange={onPromptChange}
-        />
-      ),
-    renderTraitsPicker: ({
-      threadRef,
-      draftId,
-      model,
-      models,
-      modelOptions,
-      prompt,
-      onPromptChange,
-    }) =>
-      !hasComposerTraitsTarget({ threadRef, draftId }) ? null : (
-        <TraitsPicker
-          provider="codex"
-          models={models}
-          {...(threadRef ? { threadRef } : {})}
-          {...(draftId ? { draftId } : {})}
-          model={model}
-          modelOptions={modelOptions}
-          prompt={prompt}
-          onPromptChange={onPromptChange}
-        />
-      ),
-  },
-  claudeAgent: {
-    getState: (input) => getProviderStateFromCapabilities(input),
-    renderTraitsMenuContent: ({
-      threadRef,
-      draftId,
-      model,
-      models,
-      modelOptions,
-      prompt,
-      onPromptChange,
-    }) =>
-      !hasComposerTraitsTarget({ threadRef, draftId }) ? null : (
-        <TraitsMenuContent
-          provider="claudeAgent"
-          models={models}
-          {...(threadRef ? { threadRef } : {})}
-          {...(draftId ? { draftId } : {})}
-          model={model}
-          modelOptions={modelOptions}
-          prompt={prompt}
-          onPromptChange={onPromptChange}
-        />
-      ),
-    renderTraitsPicker: ({
-      threadRef,
-      draftId,
-      model,
-      models,
-      modelOptions,
-      prompt,
-      onPromptChange,
-    }) =>
-      !hasComposerTraitsTarget({ threadRef, draftId }) ? null : (
-        <TraitsPicker
-          provider="claudeAgent"
-          models={models}
-          {...(threadRef ? { threadRef } : {})}
-          {...(draftId ? { draftId } : {})}
-          model={model}
-          modelOptions={modelOptions}
-          prompt={prompt}
-          onPromptChange={onPromptChange}
-        />
-      ),
-  },
-};
-
-export function getComposerProviderState(input: ComposerProviderStateInput): ComposerProviderState {
-  return composerProviderRegistry[input.provider].getState(input);
-}
-
-export function renderProviderTraitsMenuContent(input: {
-  provider: ProviderKind;
-  threadRef?: ScopedThreadRef;
-  draftId?: DraftId;
-  model: string;
-  models: ReadonlyArray<ServerProviderModel>;
-  modelOptions: ProviderModelOptions[ProviderKind] | undefined;
-  prompt: string;
-  onPromptChange: (prompt: string) => void;
-}): ReactNode {
-  return composerProviderRegistry[input.provider].renderTraitsMenuContent({
-    ...(input.threadRef ? { threadRef: input.threadRef } : {}),
-    ...(input.draftId ? { draftId: input.draftId } : {}),
-    model: input.model,
-    models: input.models,
-    modelOptions: input.modelOptions,
-    prompt: input.prompt,
-    onPromptChange: input.onPromptChange,
-  });
-}
-
-export function renderProviderTraitsPicker(input: {
-  provider: ProviderKind;
-  threadRef?: ScopedThreadRef;
-  draftId?: DraftId;
-  model: string;
-  models: ReadonlyArray<ServerProviderModel>;
-  modelOptions: ProviderModelOptions[ProviderKind] | undefined;
-  prompt: string;
-  onPromptChange: (prompt: string) => void;
-}): ReactNode {
-  return composerProviderRegistry[input.provider].renderTraitsPicker({
-    ...(input.threadRef ? { threadRef: input.threadRef } : {}),
-    ...(input.draftId ? { draftId: input.draftId } : {}),
-    model: input.model,
-    models: input.models,
-    modelOptions: input.modelOptions,
-    prompt: input.prompt,
-    onPromptChange: input.onPromptChange,
-  });
-}
diff --git a/apps/web/src/components/chat/composerProviderState.test.tsx b/apps/web/src/components/chat/composerProviderState.test.tsx
new file mode 100644
index 00000000000..d9e35c2bd53
--- /dev/null
+++ b/apps/web/src/components/chat/composerProviderState.test.tsx
@@ -0,0 +1,242 @@
+import { describe, expect, it } from "vitest";
+import {
+  ProviderDriverKind,
+  type ProviderOptionDescriptor,
+  type ProviderOptionSelection,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+import {
+  getComposerProviderState,
+  renderProviderTraitsMenuContent,
+  renderProviderTraitsPicker,
+} from "./composerProviderState";
+
+// Everything in composerProviderState is now data-driven by the model's
+// optionDescriptors, so these tests use a single synthetic provider/model and
+// vary only the descriptor shape per scenario.
+
+const PROVIDER: ProviderDriverKind = ProviderDriverKind.make("codex");
+const MODEL = "test-model";
+
+function selectDescriptor(
+  id: string,
+  options: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>,
+  promptInjectedValues?: ReadonlyArray<string>,
+): Extract<ProviderOptionDescriptor, { type: "select" }> {
+  const defaultId = options.find((option) => option.isDefault)?.id;
+  return {
+    id,
+    label: id,
+    type: "select",
+    options: [...options],
+    ...(defaultId ? { currentValue: defaultId } : {}),
+    ...(promptInjectedValues && promptInjectedValues.length > 0
+      ? { promptInjectedValues: [...promptInjectedValues] }
+      : {}),
+  };
+}
+
+function booleanDescriptor(id: string): Extract<ProviderOptionDescriptor, { type: "boolean" }> {
+  return { id, label: id, type: "boolean" };
+}
+
+function modelWith(
+  descriptors: ReadonlyArray<ProviderOptionDescriptor>,
+): ReadonlyArray<ServerProviderModel> {
+  return [
+    { slug: MODEL, name: MODEL, isCustom: false, capabilities: { optionDescriptors: descriptors } },
+  ];
+}
+
+function selections(
+  ...entries: Array<[string, string | boolean]>
+): ReadonlyArray<ProviderOptionSelection> {
+  return entries.map(([id, value]) => ({ id, value }));
+}
+
+const ULTRATHINK_FRAME_CLASSES = {
+  composerFrameClassName: "ultrathink-frame",
+  composerSurfaceClassName: "shadow-[0_0_0_1px_rgba(255,255,255,0.04)_inset]",
+  modelPickerIconClassName: "ultrathink-chroma",
+} as const;
+
+describe("getComposerProviderState", () => {
+  it("returns descriptor defaults when no selections are provided", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([
+        selectDescriptor("effort", [
+          { id: "low", label: "Low" },
+          { id: "high", label: "High", isDefault: true },
+        ]),
+      ]),
+      prompt: "",
+      modelOptions: undefined,
+    });
+
+    expect(state).toEqual({
+      provider: PROVIDER,
+      promptEffort: "high",
+      modelOptionsForDispatch: selections(["effort", "high"]),
+    });
+  });
+
+  it("lets selections override defaults and propagates them through dispatch", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([
+        selectDescriptor("effort", [
+          { id: "low", label: "Low" },
+          { id: "high", label: "High", isDefault: true },
+        ]),
+        booleanDescriptor("fastMode"),
+      ]),
+      prompt: "",
+      modelOptions: selections(["effort", "low"], ["fastMode", true]),
+    });
+
+    expect(state).toEqual({
+      provider: PROVIDER,
+      promptEffort: "low",
+      modelOptionsForDispatch: selections(["effort", "low"], ["fastMode", true]),
+    });
+  });
+
+  it("preserves selections that match defaults so deepMerge can overwrite prior state", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([
+        selectDescriptor("effort", [{ id: "high", label: "High", isDefault: true }]),
+        booleanDescriptor("fastMode"),
+      ]),
+      prompt: "",
+      modelOptions: selections(["effort", "high"], ["fastMode", false]),
+    });
+
+    expect(state.modelOptionsForDispatch).toEqual(
+      selections(["effort", "high"], ["fastMode", false]),
+    );
+  });
+
+  it("drops selections for descriptors the model does not declare", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([booleanDescriptor("thinking")]),
+      prompt: "",
+      modelOptions: selections(["effort", "max"], ["thinking", false]),
+    });
+
+    expect(state).toEqual({
+      provider: PROVIDER,
+      promptEffort: null,
+      modelOptionsForDispatch: selections(["thinking", false]),
+    });
+  });
+
+  it("derives promptEffort from the first select descriptor and preserves all others for dispatch", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([
+        selectDescriptor("effort", [{ id: "high", label: "High", isDefault: true }]),
+        selectDescriptor("contextWindow", [
+          { id: "200k", label: "200k", isDefault: true },
+          { id: "1m", label: "1M" },
+        ]),
+        selectDescriptor("agent", [
+          { id: "build", label: "Build", isDefault: true },
+          { id: "plan", label: "Plan" },
+        ]),
+      ]),
+      prompt: "",
+      modelOptions: selections(["agent", "plan"]),
+    });
+
+    expect(state.promptEffort).toBe("high");
+    expect(state.modelOptionsForDispatch).toEqual(
+      selections(["effort", "high"], ["contextWindow", "200k"], ["agent", "plan"]),
+    );
+  });
+
+  it("returns undefined dispatch options when the model declares no descriptors", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([]),
+      prompt: "",
+      modelOptions: selections(["anything", "value"]),
+    });
+
+    expect(state).toEqual({
+      provider: PROVIDER,
+      promptEffort: null,
+      modelOptionsForDispatch: undefined,
+    });
+  });
+
+  it("adds ultrathink class names when the prompt triggers a promptInjectedValues descriptor", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([
+        selectDescriptor(
+          "effort",
+          [
+            { id: "medium", label: "Medium" },
+            { id: "high", label: "High", isDefault: true },
+            { id: "ultrathink", label: "Ultrathink" },
+          ],
+          ["ultrathink"],
+        ),
+      ]),
+      prompt: "Ultrathink:\nInvestigate this failure",
+      modelOptions: selections(["effort", "medium"]),
+    });
+
+    expect(state).toEqual({
+      provider: PROVIDER,
+      promptEffort: "medium",
+      modelOptionsForDispatch: selections(["effort", "medium"]),
+      ...ULTRATHINK_FRAME_CLASSES,
+    });
+  });
+
+  it("does not add ultrathink class names when the descriptor has no promptInjectedValues", () => {
+    const state = getComposerProviderState({
+      provider: PROVIDER,
+      model: MODEL,
+      models: modelWith([
+        selectDescriptor("effort", [{ id: "high", label: "High", isDefault: true }]),
+      ]),
+      prompt: "Ultrathink:\nInvestigate this failure",
+      modelOptions: undefined,
+    });
+
+    expect(state).not.toHaveProperty("composerFrameClassName");
+    expect(state).not.toHaveProperty("composerSurfaceClassName");
+    expect(state).not.toHaveProperty("modelPickerIconClassName");
+  });
+});
+
+describe("provider traits render guards", () => {
+  it("returns null when no thread target is provided", () => {
+    const models = modelWith([
+      selectDescriptor("effort", [{ id: "high", label: "High", isDefault: true }]),
+    ]);
+    const args = {
+      provider: PROVIDER,
+      model: MODEL,
+      models,
+      modelOptions: undefined,
+      prompt: "",
+      onPromptChange: () => {},
+    };
+
+    expect(renderProviderTraitsPicker(args)).toBeNull();
+    expect(renderProviderTraitsMenuContent(args)).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/chat/composerProviderState.tsx b/apps/web/src/components/chat/composerProviderState.tsx
new file mode 100644
index 00000000000..dc61bd1e484
--- /dev/null
+++ b/apps/web/src/components/chat/composerProviderState.tsx
@@ -0,0 +1,108 @@
+import {
+  type ProviderDriverKind,
+  type ProviderOptionSelection,
+  type ScopedThreadRef,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+import {
+  buildProviderOptionSelectionsFromDescriptors,
+  getProviderOptionCurrentValue,
+  getProviderOptionDescriptors,
+  isClaudeUltrathinkPrompt,
+} from "@t3tools/shared/model";
+import type { ReactNode } from "react";
+
+import type { DraftId } from "../../composerDraftStore";
+import { getProviderModelCapabilities } from "../../providerModels";
+import { shouldRenderTraitsControls, TraitsMenuContent, TraitsPicker } from "./TraitsPicker";
+
+export type ComposerProviderStateInput = {
+  provider: ProviderDriverKind;
+  model: string;
+  models: ReadonlyArray<ServerProviderModel>;
+  prompt: string;
+  modelOptions: ReadonlyArray<ProviderOptionSelection> | null | undefined;
+};
+
+export type ComposerProviderState = {
+  provider: ProviderDriverKind;
+  promptEffort: string | null;
+  modelOptionsForDispatch: ReadonlyArray<ProviderOptionSelection> | undefined;
+  composerFrameClassName?: string;
+  composerSurfaceClassName?: string;
+  modelPickerIconClassName?: string;
+};
+
+type TraitsRenderInput = {
+  provider: ProviderDriverKind;
+  threadRef?: ScopedThreadRef;
+  draftId?: DraftId;
+  model: string;
+  models: ReadonlyArray<ServerProviderModel>;
+  modelOptions: ReadonlyArray<ProviderOptionSelection> | undefined;
+  prompt: string;
+  onPromptChange: (prompt: string) => void;
+};
+
+export function getComposerProviderState(input: ComposerProviderStateInput): ComposerProviderState {
+  const { provider, model, models, prompt, modelOptions } = input;
+  const caps = getProviderModelCapabilities(models, model, provider);
+  const descriptors = getProviderOptionDescriptors({ caps, selections: modelOptions });
+  const primarySelectDescriptor = descriptors.find(
+    (descriptor): descriptor is Extract<(typeof descriptors)[number], { type: "select" }> =>
+      descriptor.type === "select",
+  );
+  const primaryValue = getProviderOptionCurrentValue(primarySelectDescriptor ?? null);
+  const promptEffort = typeof primaryValue === "string" ? primaryValue : null;
+  const ultrathinkActive =
+    (primarySelectDescriptor?.promptInjectedValues?.length ?? 0) > 0 &&
+    isClaudeUltrathinkPrompt(prompt);
+
+  return {
+    provider,
+    promptEffort,
+    modelOptionsForDispatch: buildProviderOptionSelectionsFromDescriptors(descriptors),
+    ...(ultrathinkActive
+      ? {
+          composerFrameClassName: "ultrathink-frame",
+          composerSurfaceClassName: "shadow-[0_0_0_1px_rgba(255,255,255,0.04)_inset]",
+          modelPickerIconClassName: "ultrathink-chroma",
+        }
+      : {}),
+  };
+}
+
+function renderTraitsControl(
+  Component: typeof TraitsMenuContent | typeof TraitsPicker,
+  input: TraitsRenderInput,
+): ReactNode {
+  const { provider, threadRef, draftId, model, models, modelOptions, prompt, onPromptChange } =
+    input;
+  const hasTarget = threadRef !== undefined || draftId !== undefined;
+  if (
+    !hasTarget ||
+    !shouldRenderTraitsControls({ provider, models, model, modelOptions, prompt })
+  ) {
+    return null;
+  }
+  return (
+    <Component
+      provider={provider}
+      models={models}
+      {...(threadRef ? { threadRef } : {})}
+      {...(draftId ? { draftId } : {})}
+      model={model}
+      modelOptions={modelOptions}
+      prompt={prompt}
+      onPromptChange={onPromptChange}
+    />
+  );
+}
+
+export function renderProviderTraitsMenuContent(input: TraitsRenderInput): ReactNode {
+  return renderTraitsControl(TraitsMenuContent, input);
+}
+
+export function renderProviderTraitsPicker(input: TraitsRenderInput): ReactNode {
+  return renderTraitsControl(TraitsPicker, input);
+}
diff --git a/apps/web/src/components/chat/composerSlashCommandSearch.test.ts b/apps/web/src/components/chat/composerSlashCommandSearch.test.ts
index 3da69933d07..ab808f6640f 100644
--- a/apps/web/src/components/chat/composerSlashCommandSearch.test.ts
+++ b/apps/web/src/components/chat/composerSlashCommandSearch.test.ts
@@ -1,9 +1,12 @@
 import { describe, expect, it } from "vitest";
+import { ProviderDriverKind } from "@t3tools/contracts";
 
 import type { ComposerCommandItem } from "./ComposerCommandMenu";
 import { searchSlashCommandItems } from "./composerSlashCommandSearch";
 
 describe("searchSlashCommandItems", () => {
+  const claudeDriver = ProviderDriverKind.make("claudeAgent");
+
   it("moves exact provider command matches ahead of broader description matches", () => {
     const items = [
       {
@@ -16,7 +19,7 @@ describe("searchSlashCommandItems", () => {
       {
         id: "provider-slash-command:claudeAgent:ui",
         type: "provider-slash-command",
-        provider: "claudeAgent",
+        provider: claudeDriver,
         command: { name: "ui" },
         label: "/ui",
         description: "Explore, build, and refine UI.",
@@ -24,7 +27,7 @@ describe("searchSlashCommandItems", () => {
       {
         id: "provider-slash-command:claudeAgent:frontend-design",
         type: "provider-slash-command",
-        provider: "claudeAgent",
+        provider: claudeDriver,
         command: { name: "frontend-design" },
         label: "/frontend-design",
         description: "Create distinctive, production-grade frontend interfaces",
@@ -44,7 +47,7 @@ describe("searchSlashCommandItems", () => {
       {
         id: "provider-slash-command:claudeAgent:gh-fix-ci",
         type: "provider-slash-command",
-        provider: "claudeAgent",
+        provider: claudeDriver,
         command: { name: "gh-fix-ci" },
         label: "/gh-fix-ci",
         description: "Fix failing GitHub Actions",
@@ -52,7 +55,7 @@ describe("searchSlashCommandItems", () => {
       {
         id: "provider-slash-command:claudeAgent:github",
         type: "provider-slash-command",
-        provider: "claudeAgent",
+        provider: claudeDriver,
         command: { name: "github" },
         label: "/github",
         description: "General GitHub help",
diff --git a/apps/web/src/components/chat/modelPickerModelHighlights.ts b/apps/web/src/components/chat/modelPickerModelHighlights.ts
new file mode 100644
index 00000000000..2131480a6a2
--- /dev/null
+++ b/apps/web/src/components/chat/modelPickerModelHighlights.ts
@@ -0,0 +1,13 @@
+import type { ProviderDriverKind } from "@t3tools/contracts";
+
+/**
+ * Model slugs that show a gold "NEW" chip in the model picker list.
+ * Add entries as `provider:slug` when you want to highlight freshly shipped models.
+ */
+const NEW_MODEL_KEYS = new Set<string>([
+  // Example: "claudeAgent:claude-opus-4-7",
+]);
+
+export function isModelPickerNewModel(provider: ProviderDriverKind, slug: string): boolean {
+  return NEW_MODEL_KEYS.has(`${provider}:${slug}`);
+}
diff --git a/apps/web/src/components/chat/modelPickerSearch.test.ts b/apps/web/src/components/chat/modelPickerSearch.test.ts
new file mode 100644
index 00000000000..10282dbe3e7
--- /dev/null
+++ b/apps/web/src/components/chat/modelPickerSearch.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+
+import { buildModelPickerSearchText, scoreModelPickerSearch } from "./modelPickerSearch";
+
+describe("buildModelPickerSearchText", () => {
+  it("builds provider-agnostic search text from generic fields", () => {
+    expect(
+      buildModelPickerSearchText({
+        driverKind: "opencode",
+        providerDisplayName: "opencode",
+        name: "Claude Opus 4.7",
+        subProvider: "GitHub Copilot",
+      }),
+    ).toBe("claude opus 4.7 github copilot opencode opencode");
+  });
+});
+
+describe("scoreModelPickerSearch", () => {
+  it("matches typo-tolerant multi-token queries", () => {
+    expect(
+      scoreModelPickerSearch(
+        {
+          driverKind: "opencode",
+          providerDisplayName: "opencode",
+          name: "Claude Opus 4.7",
+          subProvider: "GitHub Copilot",
+        },
+        "coplt op",
+      ),
+    ).not.toBeNull();
+  });
+
+  it("rejects results when any query token does not match", () => {
+    expect(
+      scoreModelPickerSearch(
+        {
+          driverKind: "codex",
+          providerDisplayName: "codex",
+          name: "GPT-5 Codex",
+        },
+        "coplt op",
+      ),
+    ).toBeNull();
+  });
+
+  it("ranks exact token matches ahead of fuzzier matches", () => {
+    const exactScore = scoreModelPickerSearch(
+      {
+        driverKind: "opencode",
+        providerDisplayName: "opencode",
+        name: "Claude Opus 4.7",
+        subProvider: "GitHub Copilot",
+      },
+      "copilot opus",
+    );
+    const fuzzyScore = scoreModelPickerSearch(
+      {
+        driverKind: "opencode",
+        providerDisplayName: "opencode",
+        name: "Claude Opus 4.7",
+        subProvider: "GitHub Copilot",
+      },
+      "coplt op",
+    );
+
+    expect(exactScore).not.toBeNull();
+    expect(fuzzyScore).not.toBeNull();
+    expect(exactScore!).toBeLessThan(fuzzyScore!);
+  });
+
+  it("gives favorite models a strong enough ranking boost for partial queries", () => {
+    const favoriteScore = scoreModelPickerSearch(
+      {
+        driverKind: "claudeAgent",
+        providerDisplayName: "Claude",
+        name: "Claude Opus 4.7",
+        isFavorite: true,
+      },
+      "opu",
+    );
+    const nonFavoriteScore = scoreModelPickerSearch(
+      {
+        driverKind: "cursor",
+        providerDisplayName: "Cursor",
+        name: "Opus 4.5",
+      },
+      "opu",
+    );
+
+    expect(favoriteScore).not.toBeNull();
+    expect(nonFavoriteScore).not.toBeNull();
+    expect(favoriteScore!).toBeLessThan(nonFavoriteScore!);
+  });
+
+  it("does not let the favorite boost outrank clearly better textual matches", () => {
+    const favoriteScore = scoreModelPickerSearch(
+      {
+        driverKind: "claudeAgent",
+        providerDisplayName: "Claude",
+        name: "Claude Opus 4.7",
+        isFavorite: true,
+      },
+      "opus 4.7",
+    );
+    const nonFavoriteExactScore = scoreModelPickerSearch(
+      {
+        driverKind: "cursor",
+        providerDisplayName: "Cursor",
+        name: "Opus 4.7",
+      },
+      "opus 4.7",
+    );
+
+    expect(favoriteScore).not.toBeNull();
+    expect(nonFavoriteExactScore).not.toBeNull();
+    expect(nonFavoriteExactScore!).toBeLessThan(favoriteScore!);
+  });
+
+  it("matches a custom instance's display name against its models", () => {
+    expect(
+      scoreModelPickerSearch(
+        {
+          driverKind: "codex",
+          providerDisplayName: "Codex Personal",
+          name: "GPT-5 Codex",
+        },
+        "personal",
+      ),
+    ).not.toBeNull();
+  });
+});
diff --git a/apps/web/src/components/chat/modelPickerSearch.ts b/apps/web/src/components/chat/modelPickerSearch.ts
new file mode 100644
index 00000000000..d3a954ee4fa
--- /dev/null
+++ b/apps/web/src/components/chat/modelPickerSearch.ts
@@ -0,0 +1,83 @@
+import { normalizeSearchQuery, scoreQueryMatch } from "@t3tools/shared/searchRanking";
+
+type ModelPickerSearchableModel = {
+  /** Driver kind — indexed so "codex" still matches a Codex Personal instance. */
+  driverKind: string;
+  /**
+   * Instance display name (e.g. "Codex Personal"). Indexed as a search
+   * field so typing the custom instance's user-authored name matches its
+   * models directly instead of just the driver kind.
+   */
+  providerDisplayName: string;
+  name: string;
+  shortName?: string;
+  subProvider?: string;
+  isFavorite?: boolean;
+};
+
+const MODEL_PICKER_FAVORITE_SCORE_BOOST = 24;
+
+function getModelPickerSearchFields(model: ModelPickerSearchableModel): string[] {
+  return [
+    normalizeSearchQuery(model.name),
+    ...(model.shortName ? [normalizeSearchQuery(model.shortName)] : []),
+    ...(model.subProvider ? [normalizeSearchQuery(model.subProvider)] : []),
+    normalizeSearchQuery(model.driverKind),
+    normalizeSearchQuery(model.providerDisplayName),
+    buildModelPickerSearchText(model),
+  ];
+}
+
+function scoreModelPickerSearchToken(
+  field: string,
+  token: string,
+  fieldBase: number,
+): number | null {
+  return scoreQueryMatch({
+    value: field,
+    query: token,
+    exactBase: fieldBase,
+    prefixBase: fieldBase + 2,
+    boundaryBase: fieldBase + 4,
+    includesBase: fieldBase + 6,
+    ...(token.length >= 3 ? { fuzzyBase: fieldBase + 100 } : {}),
+  });
+}
+
+export function buildModelPickerSearchText(model: ModelPickerSearchableModel): string {
+  return normalizeSearchQuery(
+    [model.name, model.shortName, model.subProvider, model.driverKind, model.providerDisplayName]
+      .filter((value): value is string => typeof value === "string" && value.length > 0)
+      .join(" "),
+  );
+}
+
+export function scoreModelPickerSearch(
+  model: ModelPickerSearchableModel,
+  query: string,
+): number | null {
+  const tokens = normalizeSearchQuery(query)
+    .split(/\s+/u)
+    .filter((token) => token.length > 0);
+
+  if (tokens.length === 0) {
+    return 0;
+  }
+
+  const fields = getModelPickerSearchFields(model);
+  let score = 0;
+
+  for (const token of tokens) {
+    const tokenScores = fields
+      .map((field, index) => scoreModelPickerSearchToken(field, token, index * 10))
+      .filter((fieldScore): fieldScore is number => fieldScore !== null);
+
+    if (tokenScores.length === 0) {
+      return null;
+    }
+
+    score += Math.min(...tokenScores);
+  }
+
+  return model.isFavorite ? score - MODEL_PICKER_FAVORITE_SCORE_BOOST : score;
+}
diff --git a/apps/web/src/components/chat/providerIconUtils.ts b/apps/web/src/components/chat/providerIconUtils.ts
new file mode 100644
index 00000000000..88b56295f36
--- /dev/null
+++ b/apps/web/src/components/chat/providerIconUtils.ts
@@ -0,0 +1,47 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { ClaudeAI, CursorIcon, Icon, OpenAI, OpenCodeIcon } from "../Icons";
+import { PROVIDER_OPTIONS } from "../../session-logic";
+
+export const PROVIDER_ICON_BY_PROVIDER: Partial<Record<ProviderDriverKind, Icon>> = {
+  [ProviderDriverKind.make("codex")]: OpenAI,
+  [ProviderDriverKind.make("claudeAgent")]: ClaudeAI,
+  [ProviderDriverKind.make("opencode")]: OpenCodeIcon,
+  [ProviderDriverKind.make("cursor")]: CursorIcon,
+};
+
+function isAvailableProviderOption(option: (typeof PROVIDER_OPTIONS)[number]): option is {
+  value: ProviderDriverKind;
+  label: string;
+  available: true;
+  pickerSidebarBadge?: "new" | "soon";
+} {
+  return option.available;
+}
+
+export const AVAILABLE_PROVIDER_OPTIONS = PROVIDER_OPTIONS.filter(isAvailableProviderOption);
+
+export type ModelEsque = {
+  slug: string;
+  name: string;
+  shortName?: string | undefined;
+  subProvider?: string | undefined;
+};
+
+export function getDisplayModelName(
+  model: ModelEsque,
+  options?: { preferShortName?: boolean },
+): string {
+  if (options?.preferShortName && model.shortName) {
+    return model.shortName;
+  }
+  return model.name;
+}
+
+export function getTriggerDisplayModelName(model: ModelEsque): string {
+  return getDisplayModelName(model, { preferShortName: true });
+}
+
+export function getTriggerDisplayModelLabel(model: ModelEsque): string {
+  const title = getTriggerDisplayModelName(model);
+  return model.subProvider ? `${model.subProvider} · ${title}` : title;
+}
diff --git a/apps/web/src/components/composerInlineChip.ts b/apps/web/src/components/composerInlineChip.ts
index bf869ee31de..411ad42b146 100644
--- a/apps/web/src/components/composerInlineChip.ts
+++ b/apps/web/src/components/composerInlineChip.ts
@@ -8,5 +8,7 @@ export const COMPOSER_INLINE_CHIP_LABEL_CLASS_NAME = "truncate select-none leadi
 export const COMPOSER_INLINE_SKILL_CHIP_CLASS_NAME =
   "inline-flex max-w-full select-none items-center gap-1 rounded-md border border-fuchsia-500/25 bg-fuchsia-500/12 px-1.5 py-px font-medium text-[12px] leading-[1.1] text-fuchsia-700 align-middle dark:text-fuchsia-300";
 
+export const SKILL_CHIP_ICON_SVG = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round"><path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/></svg>`;
+
 export const COMPOSER_INLINE_CHIP_DISMISS_BUTTON_CLASS_NAME =
   "ml-0.5 inline-flex size-3.5 shrink-0 cursor-pointer items-center justify-center rounded-sm text-muted-foreground/72 transition-colors hover:bg-foreground/6 hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring";
diff --git a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
new file mode 100644
index 00000000000..7a20badf02b
--- /dev/null
+++ b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
@@ -0,0 +1,221 @@
+import type { DesktopSshPasswordPromptRequest } from "@t3tools/contracts";
+import { useEffect, useId, useRef, useState } from "react";
+
+import { Button } from "../ui/button";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Input } from "../ui/input";
+
+function describeSshTarget(request: DesktopSshPasswordPromptRequest): string {
+  return request.username ? `${request.username}@${request.destination}` : request.destination;
+}
+
+function formatRemainingSeconds(seconds: number): string {
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+
+function getPromptErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : "SSH password prompt failed.";
+  return message.includes("expired") || message.includes("no longer pending")
+    ? "This SSH password prompt expired. Try connecting again."
+    : message;
+}
+
+export function SshPasswordPromptDialog() {
+  const [queue, setQueue] = useState<readonly DesktopSshPasswordPromptRequest[]>([]);
+  const [password, setPassword] = useState("");
+  const [isResponding, setIsResponding] = useState(false);
+  const [now, setNow] = useState(() => Date.now());
+  const [responseError, setResponseError] = useState<string | null>(null);
+  const currentRequest = queue[0] ?? null;
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const isRespondingRef = useRef(false);
+  const formId = useId();
+
+  useEffect(() => {
+    const bridge = window.desktopBridge;
+    if (!bridge?.onSshPasswordPrompt) {
+      return;
+    }
+
+    return bridge.onSshPasswordPrompt((request) => {
+      setQueue((currentQueue) => [...currentQueue, request]);
+    });
+  }, []);
+
+  useEffect(() => {
+    setPassword("");
+    setResponseError(null);
+    if (!currentRequest) {
+      return;
+    }
+
+    setNow(Date.now());
+    const frame = window.requestAnimationFrame(() => {
+      inputRef.current?.focus();
+      inputRef.current?.select();
+    });
+    return () => {
+      window.cancelAnimationFrame(frame);
+    };
+  }, [currentRequest]);
+
+  useEffect(() => {
+    if (!currentRequest) {
+      return;
+    }
+
+    const interval = window.setInterval(() => {
+      setNow(Date.now());
+    }, 1_000);
+    return () => {
+      window.clearInterval(interval);
+    };
+  }, [currentRequest]);
+
+  const expiresAtMs = currentRequest ? Date.parse(currentRequest.expiresAt) : Number.NaN;
+  const remainingMs = Number.isFinite(expiresAtMs) ? Math.max(0, expiresAtMs - now) : null;
+  const isExpired = remainingMs !== null && remainingMs <= 0;
+  const remainingSeconds = remainingMs === null ? null : Math.ceil(remainingMs / 1_000);
+  const remainingLabel =
+    remainingSeconds === null ? null : formatRemainingSeconds(remainingSeconds);
+
+  useEffect(() => {
+    if (isExpired) {
+      setResponseError("This SSH password prompt expired. Try connecting again.");
+    }
+  }, [isExpired]);
+
+  const removeCurrentPrompt = (requestId: string) => {
+    setQueue((currentQueue) =>
+      currentQueue[0]?.requestId === requestId ? currentQueue.slice(1) : currentQueue,
+    );
+    setPassword("");
+    setResponseError(null);
+  };
+
+  const respond = async (nextPassword: string | null) => {
+    if (!currentRequest || isRespondingRef.current) {
+      return;
+    }
+
+    const requestId = currentRequest.requestId;
+    if (nextPassword !== null && isExpired) {
+      setResponseError("This SSH password prompt expired. Try connecting again.");
+      return;
+    }
+
+    isRespondingRef.current = true;
+    setIsResponding(true);
+    setResponseError(null);
+    try {
+      await window.desktopBridge?.resolveSshPasswordPrompt(requestId, nextPassword);
+      removeCurrentPrompt(requestId);
+    } catch (error) {
+      if (nextPassword === null) {
+        removeCurrentPrompt(requestId);
+      } else {
+        setResponseError(getPromptErrorMessage(error));
+      }
+    } finally {
+      isRespondingRef.current = false;
+      setIsResponding(false);
+    }
+  };
+
+  const dismissExpiredPrompt = () => {
+    if (currentRequest) {
+      removeCurrentPrompt(currentRequest.requestId);
+    }
+  };
+
+  const cancelPrompt = () => {
+    if (isExpired) {
+      dismissExpiredPrompt();
+      return;
+    }
+    void respond(null);
+  };
+
+  const target = currentRequest ? describeSshTarget(currentRequest) : null;
+
+  return (
+    <Dialog
+      open={currentRequest !== null}
+      onOpenChange={(open) => {
+        if (!open) {
+          cancelPrompt();
+        }
+      }}
+    >
+      <DialogPopup className="max-w-md" showCloseButton={false}>
+        <DialogHeader>
+          <DialogTitle>SSH Password Required</DialogTitle>
+          <DialogDescription>
+            T3 needs your SSH password to connect to{" "}
+            {target ? <code>{target}</code> : "the remote host"}. The password is passed to the
+            local SSH process for this connection attempt and is not saved by T3 Code.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel className="space-y-3" scrollFade={false}>
+          <form
+            className="space-y-3"
+            id={formId}
+            onSubmit={(event) => {
+              event.preventDefault();
+              void respond(password);
+            }}
+          >
+            <div className="space-y-2">
+              <div className="flex items-center justify-between gap-3">
+                <p className="text-sm font-medium text-foreground">{currentRequest?.prompt}</p>
+                {remainingLabel ? (
+                  <span
+                    className={
+                      isExpired
+                        ? "shrink-0 text-xs font-medium text-destructive"
+                        : "shrink-0 text-xs text-muted-foreground"
+                    }
+                  >
+                    {isExpired ? "Expired" : remainingLabel}
+                  </span>
+                ) : null}
+              </div>
+              <Input
+                ref={inputRef}
+                autoComplete="current-password"
+                disabled={isResponding || isExpired}
+                name="ssh-password"
+                type="password"
+                value={password}
+                onChange={(event) => setPassword(event.target.value)}
+              />
+            </div>
+            {responseError ? (
+              <p className="text-sm text-destructive">{responseError}</p>
+            ) : (
+              <p className="text-sm text-muted-foreground">
+                Use SSH keys to avoid repeated password prompts on new SSH sessions.
+              </p>
+            )}
+          </form>
+        </DialogPanel>
+        <DialogFooter>
+          <Button disabled={isResponding} type="button" variant="outline" onClick={cancelPrompt}>
+            {isExpired ? "Dismiss" : "Cancel"}
+          </Button>
+          <Button disabled={isResponding || isExpired} form={formId} type="submit">
+            Continue
+          </Button>
+        </DialogFooter>
+      </DialogPopup>
+    </Dialog>
+  );
+}
diff --git a/apps/web/src/components/desktopUpdate.logic.test.ts b/apps/web/src/components/desktopUpdate.logic.test.ts
index 84bde530486..454ecdfe0e9 100644
--- a/apps/web/src/components/desktopUpdate.logic.test.ts
+++ b/apps/web/src/components/desktopUpdate.logic.test.ts
@@ -17,6 +17,7 @@ import {
 const baseState: DesktopUpdateState = {
   enabled: true,
   status: "idle",
+  channel: "latest",
   currentVersion: "1.0.0",
   hostArch: "x64",
   appArch: "x64",
diff --git a/apps/web/src/components/settings/AddProviderInstanceDialog.tsx b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
new file mode 100644
index 00000000000..affa35ff260
--- /dev/null
+++ b/apps/web/src/components/settings/AddProviderInstanceDialog.tsx
@@ -0,0 +1,491 @@
+"use client";
+
+import { CheckIcon } from "lucide-react";
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  ProviderInstanceId,
+  ProviderDriverKind,
+  type ProviderInstanceConfig,
+} from "@t3tools/contracts";
+
+import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
+import { cn } from "../../lib/utils";
+import { normalizeProviderAccentColor } from "../../providerInstances";
+import { Button } from "../ui/button";
+import { ACPRegistryIcon, Gemini, GithubCopilotIcon, PiAgentIcon, type Icon } from "../Icons";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Badge } from "../ui/badge";
+import { Input } from "../ui/input";
+import { RadioGroup } from "../ui/radio-group";
+import { toastManager } from "../ui/toast";
+import { DRIVER_OPTION_BY_VALUE, DRIVER_OPTIONS } from "./providerDriverMeta";
+import { ProviderSettingsForm, deriveProviderSettingsFields } from "./ProviderSettingsForm";
+import { AnimatedHeight } from "../AnimatedHeight";
+
+const PROVIDER_ACCENT_SWATCHES = [
+  "#2563eb",
+  "#16a34a",
+  "#ea580c",
+  "#dc2626",
+  "#7c3aed",
+  "#0891b2",
+] as const;
+
+/**
+ * Normalize a user-provided label into a slug suffix for the instance id.
+ * The full id is formed by prefixing the driver slug — e.g. label "Work" on
+ * driver "codex" becomes `codex_work`. Output is trimmed to 48 chars so the
+ * final composed id stays under the 64-char slug cap enforced by
+ * `ProviderInstanceId` in `@t3tools/contracts`.
+ */
+function slugifyLabel(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 48);
+}
+
+function deriveInstanceId(driver: ProviderDriverKind, label: string): string {
+  const slug = slugifyLabel(label);
+  return slug ? `${driver}_${slug}` : "";
+}
+
+const INSTANCE_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
+const DEFAULT_DRIVER_OPTION = DRIVER_OPTIONS[0]!;
+const EMPTY_CONFIG_DRAFT: Record<string, unknown> = {};
+interface ComingSoonDriverOption {
+  readonly value: ProviderDriverKind;
+  readonly label: string;
+  readonly icon: Icon;
+}
+
+const COMING_SOON_DRIVER_OPTIONS: readonly ComingSoonDriverOption[] = [
+  {
+    value: ProviderDriverKind.make("githubCopilot"),
+    label: "Github Copilot",
+    icon: GithubCopilotIcon,
+  },
+  {
+    value: ProviderDriverKind.make("gemini"),
+    label: "Gemini",
+    icon: Gemini,
+  },
+  {
+    value: ProviderDriverKind.make("acpRegistry"),
+    label: "ACP Registry",
+    icon: ACPRegistryIcon,
+  },
+  {
+    value: ProviderDriverKind.make("piAgent"),
+    label: "Pi Agent",
+    icon: PiAgentIcon,
+  },
+];
+
+/**
+ * Validate an instance id against the same slug rules the server applies in
+ * `ProviderInstanceId` (see `packages/contracts/src/providerInstance.ts`).
+ * Returns a user-facing error string, or `null` if valid.
+ */
+function validateInstanceId(id: string, existing: ReadonlySet<string>): string | null {
+  if (id.length === 0) return "Instance ID is required.";
+  if (id.length > 64) return "Instance ID must be 64 characters or fewer.";
+  if (!INSTANCE_ID_PATTERN.test(id)) {
+    return "Instance ID must start with a letter and use only letters, digits, '-', or '_'.";
+  }
+  if (existing.has(id)) return `An instance named '${id}' already exists.`;
+  return null;
+}
+
+interface AddProviderInstanceDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function AddProviderInstanceDialog({ open, onOpenChange }: AddProviderInstanceDialogProps) {
+  const settings = useSettings();
+  const { updateSettings } = useUpdateSettings();
+
+  const [wizardStep, setWizardStep] = useState(0);
+  const [driver, setDriver] = useState<ProviderDriverKind>(DEFAULT_DRIVER_KIND);
+  const [label, setLabel] = useState("");
+  const [accentColor, setAccentColor] = useState<string>("");
+  const [instanceId, setInstanceId] = useState("");
+  const [instanceIdDirty, setInstanceIdDirty] = useState(false);
+  // Driver-specific config drafts keyed by driver so toggling between drivers
+  // during the same dialog session does not lose in-progress input.
+  const [configByDriver, setConfigByDriver] = useState<Record<string, Record<string, unknown>>>({});
+  // Errors are suppressed until the user has tried to submit once. After that
+  // they update live so fixing the problem clears the message in place.
+  const [hasAttemptedSubmit, setHasAttemptedSubmit] = useState(false);
+
+  const existingIds = useMemo(
+    () => new Set(Object.keys(settings.providerInstances ?? {})),
+    [settings.providerInstances],
+  );
+
+  // Reset the form every time the dialog opens so each creation starts
+  // from a clean slate.
+  useEffect(() => {
+    if (!open) return;
+    setDriver(DEFAULT_DRIVER_KIND);
+    setLabel("");
+    setAccentColor("");
+    setInstanceId("");
+    setWizardStep(0);
+    setInstanceIdDirty(false);
+    setConfigByDriver({});
+    setHasAttemptedSubmit(false);
+  }, [open]);
+
+  // Auto-derive the instance id from driver + label until the user types
+  // in the Instance ID field directly (after which they own its value).
+  useEffect(() => {
+    if (instanceIdDirty) return;
+    setInstanceId(deriveInstanceId(driver, label));
+  }, [driver, label, instanceIdDirty]);
+
+  const driverOption = DRIVER_OPTION_BY_VALUE[driver] ?? DEFAULT_DRIVER_OPTION;
+  const driverSettingsFields = useMemo(
+    () => deriveProviderSettingsFields(driverOption),
+    [driverOption],
+  );
+  const instanceIdError = validateInstanceId(instanceId, existingIds);
+  const showInstanceIdError = hasAttemptedSubmit && instanceIdError !== null;
+  const previewLabel = label.trim() || `${driverOption.label} Workspace`;
+  const wizardSteps = ["Driver", "Identity", "Config"] as const;
+  const wizardStepSummaries = [driverOption.label, previewLabel, null] as const;
+
+  const configDraft = configByDriver[driver] ?? EMPTY_CONFIG_DRAFT;
+  const setConfigDraft = useCallback(
+    (config: Record<string, unknown> | undefined) => {
+      setConfigByDriver((existing) => {
+        const next = { ...existing };
+        if (config === undefined || Object.keys(config).length === 0) {
+          delete next[driver];
+        } else {
+          next[driver] = config;
+        }
+        return next;
+      });
+    },
+    [driver],
+  );
+
+  const handleSave = useCallback(() => {
+    setHasAttemptedSubmit(true);
+    if (instanceIdError !== null) return;
+
+    const config = configByDriver[driver] ?? {};
+    const hasConfig = Object.keys(config).length > 0;
+    const normalizedAccentColor = normalizeProviderAccentColor(accentColor);
+
+    const nextInstance: ProviderInstanceConfig = {
+      driver,
+      enabled: true,
+      ...(label.trim().length > 0 ? { displayName: label.trim() } : {}),
+      ...(normalizedAccentColor ? { accentColor: normalizedAccentColor } : {}),
+      ...(hasConfig ? { config } : {}),
+    };
+    // `ProviderInstanceId.make` revalidates the slug; we've already checked
+    // it via `validateInstanceId`, but going through the brand constructor
+    // keeps the type boundary honest and guards against any future drift in
+    // the slug rules.
+    const brandedId = ProviderInstanceId.make(instanceId);
+    const nextMap = {
+      ...settings.providerInstances,
+      [brandedId]: nextInstance,
+    };
+    try {
+      updateSettings({ providerInstances: nextMap });
+      toastManager.add({
+        type: "success",
+        title: "Provider instance added",
+        description: `${driverOption.label} instance '${instanceId}' was added.`,
+      });
+      onOpenChange(false);
+    } catch (error) {
+      toastManager.add({
+        type: "error",
+        title: "Could not add provider instance",
+        description: error instanceof Error ? error.message : "Update failed.",
+      });
+    }
+  }, [
+    driver,
+    driverOption,
+    configByDriver,
+    instanceId,
+    instanceIdError,
+    label,
+    accentColor,
+    onOpenChange,
+    settings.providerInstances,
+    updateSettings,
+  ]);
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogPopup className="max-w-xl overflow-hidden">
+        <div className="flex min-h-0 flex-col overflow-hidden border-foreground/10 bg-background shadow-2xl">
+          <DialogHeader className="border-b border-border/70 bg-background">
+            <DialogTitle>Add provider instance</DialogTitle>
+            <DialogDescription>
+              Configure an additional provider instance — for example, a second Codex install
+              pointed at a different workspace.
+            </DialogDescription>
+            <div className="grid grid-cols-3 gap-2">
+              {wizardSteps.map((step, index) => (
+                <button
+                  key={step}
+                  type="button"
+                  className={cn(
+                    "grid min-w-0 grid-cols-[1rem_minmax(0,1fr)] gap-x-2 rounded-lg border px-3 py-2 text-left",
+                    index === wizardStep
+                      ? "border-primary bg-primary/10 ring-1 ring-primary/25"
+                      : index < wizardStep
+                        ? "border-border bg-background"
+                        : "border-border bg-muted/40",
+                  )}
+                  onClick={() => setWizardStep(index)}
+                >
+                  <span
+                    className={cn(
+                      "row-span-2 mt-0.5 grid size-4 place-items-center rounded-full border",
+                      index < wizardStep
+                        ? "border-primary bg-primary text-primary-foreground"
+                        : index === wizardStep
+                          ? "border-primary bg-background"
+                          : "border-muted-foreground/35 bg-background",
+                    )}
+                    aria-hidden
+                  >
+                    {index < wizardStep ? <CheckIcon className="size-3" /> : null}
+                  </span>
+                  <span className="text-[10px] font-medium uppercase text-muted-foreground">
+                    Step {index + 1}
+                  </span>
+                  <span className="truncate text-xs font-semibold text-foreground">
+                    {step}
+                    {index < wizardStep && wizardStepSummaries[index]
+                      ? `: ${wizardStepSummaries[index]}`
+                      : ""}
+                  </span>
+                </button>
+              ))}
+            </div>
+          </DialogHeader>
+
+          <div
+            data-slot="dialog-panel"
+            className="space-y-4 border-b border-border/70 bg-muted/20 px-6 py-5"
+          >
+            <AnimatedHeight>
+              <div className={cn("grid gap-2", wizardStep !== 0 && "hidden")}>
+                <span
+                  id="add-instance-driver-label"
+                  className="text-xs font-medium text-foreground"
+                >
+                  Driver
+                </span>
+                <RadioGroup
+                  value={driver}
+                  onValueChange={(value) => setDriver(ProviderDriverKind.make(value))}
+                  aria-labelledby="add-instance-driver-label"
+                  className="grid grid-cols-2 gap-2.5"
+                >
+                  {DRIVER_OPTIONS.map((option) => {
+                    const IconComponent = option.icon;
+                    const isSelected = option.value === driver;
+                    return (
+                      <RadioPrimitive.Root
+                        key={option.value}
+                        value={option.value}
+                        className={cn(
+                          "relative flex cursor-pointer items-center gap-3 rounded-lg border px-3 py-3 text-left outline-none transition-[background-color,border-color,box-shadow]",
+                          "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                          isSelected
+                            ? "border-primary bg-background shadow-sm ring-2 ring-primary/35"
+                            : "border-border bg-background hover:border-foreground/20 hover:bg-muted/50",
+                        )}
+                      >
+                        <IconComponent className="size-5 shrink-0" aria-hidden />
+                        <span className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">
+                          {option.label}
+                        </span>
+                        {option.badgeLabel ? (
+                          <Badge variant="warning" size="sm">
+                            {option.badgeLabel}
+                          </Badge>
+                        ) : null}
+                      </RadioPrimitive.Root>
+                    );
+                  })}
+                  {COMING_SOON_DRIVER_OPTIONS.map((option) => {
+                    const IconComponent = option.icon;
+                    return (
+                      <RadioPrimitive.Root
+                        key={option.value}
+                        value={option.value}
+                        disabled
+                        className={cn(
+                          "relative flex cursor-not-allowed items-center gap-3 rounded-lg border border-border bg-background px-3 py-3 text-left opacity-55 outline-none",
+                        )}
+                      >
+                        <IconComponent
+                          className="size-5 shrink-0 text-muted-foreground"
+                          aria-hidden
+                        />
+                        <span className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">
+                          {option.label}
+                        </span>
+                        <Badge variant="warning" size="sm">
+                          Coming Soon
+                        </Badge>
+                      </RadioPrimitive.Root>
+                    );
+                  })}
+                </RadioGroup>
+              </div>
+
+              <label className={cn("grid gap-2", wizardStep !== 1 && "hidden")}>
+                <span className="text-xs font-medium text-foreground">Label</span>
+                <Input
+                  className="bg-background"
+                  placeholder="e.g. Work"
+                  value={label}
+                  onChange={(event) => setLabel(event.target.value)}
+                />
+                <span className="text-[11px] text-muted-foreground">
+                  Shown in the provider list. Optional.
+                </span>
+              </label>
+
+              <label className={cn("grid gap-2", wizardStep !== 1 && "hidden")}>
+                <span className="text-xs font-medium text-foreground">Instance ID</span>
+                <Input
+                  className="bg-background"
+                  placeholder={`${driver}_work`}
+                  value={instanceId}
+                  onChange={(event) => {
+                    setInstanceIdDirty(true);
+                    setInstanceId(event.target.value);
+                  }}
+                  aria-invalid={showInstanceIdError}
+                />
+                {showInstanceIdError ? (
+                  <span className="text-[11px] text-destructive">{instanceIdError}</span>
+                ) : (
+                  <span className="text-[11px] text-muted-foreground">
+                    Routing key used by threads and sessions. Letters, digits, '-', or '_'.
+                  </span>
+                )}
+              </label>
+
+              <div className={cn("grid gap-2", wizardStep !== 1 && "hidden")}>
+                <span className="text-xs font-medium text-foreground">Accent color</span>
+                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                  <input
+                    type="color"
+                    value={normalizeProviderAccentColor(accentColor) ?? PROVIDER_ACCENT_SWATCHES[0]}
+                    onChange={(event) => setAccentColor(event.target.value)}
+                    aria-label="Provider instance accent color"
+                    className="h-8 w-10 cursor-pointer rounded-xl border border-input bg-background p-0.5"
+                  />
+                  <div className="flex flex-wrap gap-1.5">
+                    {PROVIDER_ACCENT_SWATCHES.map((swatch) => {
+                      const selected = accentColor.toLowerCase() === swatch;
+                      return (
+                        <button
+                          key={swatch}
+                          type="button"
+                          className={cn(
+                            "size-6 cursor-pointer rounded-full border transition",
+                            selected
+                              ? "scale-110 border-foreground ring-2 ring-ring ring-offset-1 ring-offset-background"
+                              : "border-black/10 hover:scale-105 dark:border-white/20",
+                          )}
+                          style={{ backgroundColor: swatch }}
+                          onClick={() => setAccentColor(swatch)}
+                          aria-label={`Use ${swatch} accent`}
+                        />
+                      );
+                    })}
+                  </div>
+                  {accentColor ? (
+                    <Button
+                      type="button"
+                      size="sm"
+                      variant="ghost"
+                      className="h-7 px-2 text-xs text-muted-foreground"
+                      onClick={() => setAccentColor("")}
+                    >
+                      Clear
+                    </Button>
+                  ) : null}
+                </div>
+                <span className="text-[11px] text-muted-foreground">
+                  Optional marker shown in the picker.
+                </span>
+              </div>
+
+              {driverSettingsFields.length > 0 ? (
+                <div className={cn("grid gap-4", wizardStep !== 2 && "hidden")}>
+                  <ProviderSettingsForm
+                    definition={driverOption}
+                    value={configDraft}
+                    idPrefix={`add-provider-${driver}`}
+                    variant="dialog"
+                    onChange={setConfigDraft}
+                  />
+                </div>
+              ) : wizardStep === 2 ? (
+                <div className="grid gap-2">
+                  <p className="text-sm text-muted-foreground">
+                    This driver has no required configuration. You can add the instance now.
+                  </p>
+                </div>
+              ) : null}
+            </AnimatedHeight>
+          </div>
+
+          <DialogFooter className="border-t bg-background">
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => {
+                if (wizardStep === 0) {
+                  onOpenChange(false);
+                  return;
+                }
+                setWizardStep((step) => Math.max(0, step - 1));
+              }}
+            >
+              {wizardStep === 0 ? "Cancel" : "Back"}
+            </Button>
+            {wizardStep < wizardSteps.length - 1 ? (
+              <Button size="sm" onClick={() => setWizardStep((step) => Math.min(2, step + 1))}>
+                Next
+              </Button>
+            ) : (
+              <Button size="sm" onClick={handleSave}>
+                Add instance
+              </Button>
+            )}
+          </DialogFooter>
+        </div>
+      </DialogPopup>
+    </Dialog>
+  );
+}
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index ab31fe7e173..17dc177a981 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,16 +1,28 @@
-import { PlusIcon, QrCodeIcon } from "lucide-react";
-import { memo, useCallback, useEffect, useMemo, useState } from "react";
+import {
+  ChevronDownIcon,
+  ChevronsLeftRightEllipsisIcon,
+  PlusIcon,
+  QrCodeIcon,
+  RefreshCwIcon,
+  TerminalIcon,
+  TriangleAlertIcon,
+} from "lucide-react";
+import { type ReactNode, memo, useCallback, useEffect, useMemo, useState } from "react";
 import {
   type AuthClientSession,
   type AuthPairingLink,
+  type AdvertisedEndpoint,
+  type DesktopDiscoveredSshHost,
+  type DesktopSshEnvironmentTarget,
   type DesktopServerExposureState,
   type EnvironmentId,
 } from "@t3tools/contracts";
-import { DateTime } from "effect";
+import * as DateTime from "effect/DateTime";
 
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { cn } from "../../lib/utils";
 import { formatElapsedDurationLabel, formatExpiresInLabel } from "../../timestampFormat";
+import { resolveDesktopPairingUrl, resolveHostedPairingUrl } from "./pairingUrls";
 import {
   SettingsPageContainer,
   SettingsRow,
@@ -20,6 +32,7 @@ import {
 import { Input } from "../ui/input";
 import {
   Dialog,
+  DialogClose,
   DialogFooter,
   DialogDescription,
   DialogHeader,
@@ -28,6 +41,7 @@ import {
   DialogTitle,
   DialogTrigger,
 } from "../ui/dialog";
+import { ScrollArea } from "../ui/scroll-area";
 import {
   AlertDialog,
   AlertDialogClose,
@@ -41,11 +55,23 @@ import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
 import { QRCodeSvg } from "../ui/qr-code";
 import { Spinner } from "../ui/spinner";
 import { Switch } from "../ui/switch";
-import { toastManager } from "../ui/toast";
+import { stackedThreadToast, toastManager } from "../ui/toast";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { Button } from "../ui/button";
+import { Group, GroupSeparator } from "../ui/group";
+import { AnimatedHeight } from "../AnimatedHeight";
+import {
+  Menu,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuItem,
+  MenuPopup,
+  MenuSeparator,
+  MenuTrigger,
+} from "../ui/menu";
 import { Textarea } from "../ui/textarea";
-import { setPairingTokenOnUrl } from "../../pairingUrl";
+import { getPairingTokenFromUrl, setPairingTokenOnUrl } from "../../pairingUrl";
+import { readHostedPairingRequest } from "../../hostedPairing";
 import {
   createServerPairingCredential,
   fetchSessionState,
@@ -63,10 +89,17 @@ import {
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
   addSavedEnvironment,
+  connectDesktopSshEnvironment,
+  disconnectSavedEnvironment,
   getPrimaryEnvironmentConnection,
   reconnectSavedEnvironment,
   removeSavedEnvironment,
 } from "~/environments/runtime";
+import { useUiStateStore } from "~/uiStateStore";
+import { resolveServerConfigVersionMismatch } from "~/versionSkew";
+import { useServerConfig } from "~/rpc/serverState";
+
+const DEFAULT_TAILSCALE_SERVE_PORT = 443;
 
 const accessTimestampFormatter = new Intl.DateTimeFormat(undefined, {
   dateStyle: "medium",
@@ -160,12 +193,153 @@ function getSavedBackendStatusTooltip(
     : "Not connected yet.";
 }
 
+function formatDesktopSshTarget(target: NonNullable<SavedEnvironmentRecord["desktopSsh"]>): string {
+  const authority = target.username ? `${target.username}@${target.hostname}` : target.hostname;
+  return target.port ? `${authority}:${target.port}` : authority;
+}
+
+function parseManualDesktopSshTarget(input: {
+  readonly host: string;
+  readonly username: string;
+  readonly port: string;
+}): DesktopSshEnvironmentTarget {
+  const rawHost = input.host.trim();
+  if (rawHost.length === 0) {
+    throw new Error("SSH host or alias is required.");
+  }
+
+  let hostname = rawHost;
+  let username = input.username.trim() || null;
+  let port: number | null = null;
+
+  const atIndex = hostname.lastIndexOf("@");
+  if (atIndex > 0) {
+    const inlineUsername = hostname.slice(0, atIndex).trim();
+    hostname = hostname.slice(atIndex + 1).trim();
+    if (!username && inlineUsername.length > 0) {
+      username = inlineUsername;
+    }
+  }
+
+  const bracketedHostMatch = /^\[([^\]]+)\](?::(\d+))?$/u.exec(hostname);
+  if (bracketedHostMatch) {
+    hostname = bracketedHostMatch[1]!.trim();
+    if (bracketedHostMatch[2]) {
+      port = Number.parseInt(bracketedHostMatch[2], 10);
+    }
+  } else {
+    const colonSegments = hostname.split(":");
+    if (colonSegments.length === 2 && /^\d+$/u.test(colonSegments[1] ?? "")) {
+      hostname = colonSegments[0]!.trim();
+      port = Number.parseInt(colonSegments[1]!, 10);
+    }
+  }
+
+  const rawPort = input.port.trim();
+  if (rawPort.length > 0) {
+    port = Number.parseInt(rawPort, 10);
+  }
+
+  if (hostname.length === 0) {
+    throw new Error("SSH host or alias is required.");
+  }
+
+  if (port !== null && (!Number.isInteger(port) || port <= 0 || port > 65_535)) {
+    throw new Error("SSH port must be between 1 and 65535.");
+  }
+
+  return {
+    alias: hostname,
+    hostname,
+    username,
+    port,
+  };
+}
+
+function parsePairingUrlFields(
+  input: string,
+): { readonly host: string; readonly pairingCode: string } | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  try {
+    const urlLikeInput =
+      /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//u.test(trimmed) || trimmed.startsWith("//")
+        ? trimmed
+        : `https://${trimmed}`;
+    const url = new URL(urlLikeInput, window.location.origin);
+    const hostedPairingRequest = readHostedPairingRequest(url);
+    if (hostedPairingRequest) {
+      return {
+        host: hostedPairingRequest.host,
+        pairingCode: hostedPairingRequest.token,
+      };
+    }
+
+    const pairingCode = getPairingTokenFromUrl(url);
+    if (!pairingCode) return null;
+    return {
+      host: url.origin,
+      pairingCode,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function parseRemotePairingFields(input: { readonly host: string; readonly pairingCode: string }): {
+  readonly host: string;
+  readonly pairingCode: string;
+} {
+  const parsedPairingUrl = parsePairingUrlFields(input.host);
+  if (parsedPairingUrl) return parsedPairingUrl;
+
+  const host = input.host.trim();
+  const pairingCode = input.pairingCode.trim();
+  if (!host) {
+    throw new Error("Enter a backend host.");
+  }
+  if (!pairingCode) {
+    throw new Error("Enter a pairing code.");
+  }
+  return { host, pairingCode };
+}
+
+function formatDesktopSshConnectionError(error: unknown): string {
+  const fallback = "Failed to connect SSH host.";
+  const rawMessage = error instanceof Error ? error.message : fallback;
+  const withoutIpcPrefix = rawMessage.replace(
+    /^Error invoking remote method 'desktop:ensure-ssh-environment':\s*/u,
+    "",
+  );
+  const withoutTaggedErrorPrefix = withoutIpcPrefix.replace(/^Ssh[A-Za-z]+Error:\s*/u, "");
+  return withoutTaggedErrorPrefix.trim() || fallback;
+}
+
 /** Direct row in the card – same pattern as the Provider / ACP-agent list rows. */
 const ITEM_ROW_CLASSNAME = "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
+const ENDPOINT_ROW_CLASSNAME = "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
 
 const ITEM_ROW_INNER_CLASSNAME =
   "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between";
 
+type AccessSectionPresentation = "current" | "endpoint-rail";
+
+function accessRowClassName(_presentation: AccessSectionPresentation) {
+  return ITEM_ROW_CLASSNAME;
+}
+
+function endpointRowClassName(presentation: AccessSectionPresentation, isAvailable: boolean) {
+  if (presentation === "endpoint-rail") {
+    return cn(
+      "relative border-t border-border/60 px-4 py-3 first:border-t-0 sm:px-5",
+      !isAvailable && "bg-muted/20",
+    );
+  }
+
+  return cn(ENDPOINT_ROW_CLASSNAME, !isAvailable && "bg-muted/24");
+}
+
 function sortDesktopPairingLinks(links: ReadonlyArray<ServerPairingLinkRecord>) {
   return [...links].toSorted(
     (left, right) => new Date(right.createdAt).getTime() - new Date(left.createdAt).getTime(),
@@ -243,10 +417,66 @@ function removeDesktopClientSession(
   return current.filter((clientSession) => clientSession.sessionId !== sessionId);
 }
 
-function resolveDesktopPairingUrl(endpointUrl: string, credential: string): string {
-  const url = new URL(endpointUrl);
-  url.pathname = "/pair";
-  return setPairingTokenOnUrl(url, credential).toString();
+function selectPairingEndpoint(
+  endpoints: ReadonlyArray<AdvertisedEndpoint>,
+  defaultEndpointKey?: string | null,
+): AdvertisedEndpoint | null {
+  const availableEndpoints = endpoints.filter((endpoint) => endpoint.status !== "unavailable");
+  if (defaultEndpointKey) {
+    const selectedEndpoint = availableEndpoints.find(
+      (endpoint) => endpointDefaultPreferenceKey(endpoint) === defaultEndpointKey,
+    );
+    if (selectedEndpoint) {
+      return selectedEndpoint;
+    }
+  }
+  return (
+    availableEndpoints.find((endpoint) => endpoint.isDefault) ??
+    availableEndpoints.find((endpoint) => endpoint.reachability !== "loopback") ??
+    availableEndpoints.find((endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible") ??
+    null
+  );
+}
+
+function isTailscaleHttpsEndpoint(endpoint: AdvertisedEndpoint): boolean {
+  return endpoint.id.startsWith("tailscale-magicdns:");
+}
+
+function endpointDefaultPreferenceKey(endpoint: AdvertisedEndpoint): string {
+  if (endpoint.id.startsWith("desktop-loopback:")) {
+    return "desktop-core:loopback:http";
+  }
+  if (endpoint.id.startsWith("desktop-lan:")) {
+    return "desktop-core:lan:http";
+  }
+  if (endpoint.id.startsWith("tailscale-ip:")) {
+    return "tailscale:ip:http";
+  }
+  if (isTailscaleHttpsEndpoint(endpoint)) {
+    return "tailscale:magicdns:https";
+  }
+
+  let scheme = "unknown";
+  try {
+    scheme = new URL(endpoint.httpBaseUrl).protocol.replace(/:$/u, "");
+  } catch {
+    // Keep the stored preference stable even if a custom endpoint is malformed.
+  }
+
+  return `${endpoint.provider.id}:${endpoint.reachability}:${scheme}:${endpoint.label}`;
+}
+
+function resolveAdvertisedEndpointPairingUrl(
+  endpoint: AdvertisedEndpoint,
+  credential: string,
+): string {
+  if (endpoint.compatibility.hostedHttpsApp === "compatible") {
+    return (
+      resolveHostedPairingUrl(endpoint.httpBaseUrl, credential) ??
+      resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential)
+    );
+  }
+  return resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential);
 }
 
 function resolveCurrentOriginPairingUrl(credential: string): string {
@@ -254,9 +484,21 @@ function resolveCurrentOriginPairingUrl(credential: string): string {
   return setPairingTokenOnUrl(url, credential).toString();
 }
 
+function isHostedAppPairingUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.pathname === "/pair" && url.searchParams.has("host");
+  } catch {
+    return false;
+  }
+}
+
 type PairingLinkListRowProps = {
   pairingLink: ServerPairingLinkRecord;
   endpointUrl: string | null | undefined;
+  endpoints: ReadonlyArray<AdvertisedEndpoint>;
+  defaultEndpointKey: string | null;
+  presentation?: AccessSectionPresentation;
   revokingPairingLinkId: string | null;
   onRevoke: (id: string) => void;
 };
@@ -264,6 +506,9 @@ type PairingLinkListRowProps = {
 const PairingLinkListRow = memo(function PairingLinkListRow({
   pairingLink,
   endpointUrl,
+  endpoints,
+  defaultEndpointKey,
+  presentation = "current",
   revokingPairingLinkId,
   onRevoke,
 }: PairingLinkListRowProps) {
@@ -278,53 +523,197 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
     () => resolveCurrentOriginPairingUrl(pairingLink.credential),
     [pairingLink.credential],
   );
+  const hostedPairingUrl = useMemo(
+    () =>
+      endpointUrl != null && endpointUrl !== ""
+        ? resolveHostedPairingUrl(endpointUrl, pairingLink.credential)
+        : null,
+    [endpointUrl, pairingLink.credential],
+  );
+  const endpointPairingUrl = useMemo(() => {
+    const endpoint = selectPairingEndpoint(endpoints, defaultEndpointKey);
+    return endpoint ? resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential) : null;
+  }, [defaultEndpointKey, endpoints, pairingLink.credential]);
+  const endpointCopyOptions = useMemo(
+    () =>
+      endpoints
+        .filter((endpoint) => endpoint.status !== "unavailable")
+        .map((endpoint) => {
+          const url = resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential);
+          return {
+            key: endpointDefaultPreferenceKey(endpoint),
+            label: endpoint.label,
+            url,
+            detail: isHostedAppPairingUrl(url) ? "Hosted app link" : "Backend pairing URL",
+          };
+        }),
+    [endpoints, pairingLink.credential],
+  );
   const shareablePairingUrl =
-    endpointUrl != null && endpointUrl !== ""
-      ? resolveDesktopPairingUrl(endpointUrl, pairingLink.credential)
+    endpointPairingUrl ??
+    (endpointUrl != null && endpointUrl !== ""
+      ? (hostedPairingUrl ?? resolveDesktopPairingUrl(endpointUrl, pairingLink.credential))
       : isLoopbackHostname(window.location.hostname)
         ? null
-        : currentOriginPairingUrl;
-  const copyValue = shareablePairingUrl ?? pairingLink.credential;
+        : currentOriginPairingUrl);
+  const revealValue = shareablePairingUrl ?? pairingLink.credential;
+  const isShareableHostedAppPairingUrl =
+    shareablePairingUrl !== null && isHostedAppPairingUrl(shareablePairingUrl);
   const canCopyToClipboard =
     typeof window !== "undefined" &&
     window.isSecureContext &&
     navigator.clipboard?.writeText != null;
 
-  const { copyToClipboard, isCopied } = useCopyToClipboard({
-    onCopy: () => {
+  const { copyToClipboard } = useCopyToClipboard<"code" | "hosted-link" | "link">({
+    onCopy: (kind) => {
       toastManager.add({
         type: "success",
-        title: shareablePairingUrl ? "Pairing URL copied" : "Pairing token copied",
-        description: shareablePairingUrl
-          ? "Open it in the client you want to pair to this environment."
-          : "Paste it into another client with this backend's reachable host.",
+        title:
+          kind === "hosted-link"
+            ? "Hosted app link copied"
+            : kind === "link"
+              ? "Pairing URL copied"
+              : "Pairing code copied",
+        description:
+          kind === "hosted-link"
+            ? "Open it in the browser on the device you want to connect."
+            : kind === "link"
+              ? "Open it in the client you want to pair to this environment."
+              : "Paste it into another client to finish pairing.",
       });
     },
-    onError: (error) => {
+    onError: (error, kind) => {
       setIsRevealDialogOpen(true);
-      toastManager.add({
-        type: "error",
-        title: canCopyToClipboard ? "Could not copy pairing URL" : "Clipboard copy unavailable",
-        description: canCopyToClipboard ? error.message : "Showing the full value instead.",
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: canCopyToClipboard
+            ? kind === "hosted-link"
+              ? "Could not copy hosted app link"
+              : kind === "link"
+                ? "Could not copy pairing URL"
+                : "Could not copy pairing code"
+            : "Clipboard copy unavailable",
+          description: canCopyToClipboard ? error.message : "Showing the full value instead.",
+        }),
+      );
     },
   });
 
-  const handleCopy = useCallback(() => {
-    copyToClipboard(copyValue, undefined);
-  }, [copyToClipboard, copyValue]);
+  const copyPairingValue = useCallback(
+    (value: string, kind: "code" | "hosted-link" | "link") => {
+      copyToClipboard(value, kind);
+    },
+    [copyToClipboard],
+  );
+
+  const copyKindForUrl = useCallback(
+    (url: string): "hosted-link" | "link" => (isHostedAppPairingUrl(url) ? "hosted-link" : "link"),
+    [],
+  );
+
+  const handleCopyCode = useCallback(() => {
+    copyPairingValue(pairingLink.credential, "code");
+  }, [copyPairingValue, pairingLink.credential]);
+
+  const handleCopyDefaultLink = useCallback(() => {
+    if (!shareablePairingUrl) return;
+    copyPairingValue(shareablePairingUrl, copyKindForUrl(shareablePairingUrl));
+  }, [copyKindForUrl, copyPairingValue, shareablePairingUrl]);
 
   const expiresAbsolute = formatAccessTimestamp(pairingLink.expiresAt);
 
   const roleLabel = pairingLink.role === "owner" ? "Owner" : "Client";
   const primaryLabel = pairingLink.label ?? `${roleLabel} link`;
+  const defaultEndpointCopyOption =
+    endpointCopyOptions.find((option) => option.key === defaultEndpointKey) ??
+    endpointCopyOptions[0] ??
+    null;
+  const defaultEndpointCopyLabel = defaultEndpointCopyOption?.label ?? "URL";
+  const backendEndpointCopyOptions = endpointCopyOptions.filter(
+    (option) => !isHostedAppPairingUrl(option.url),
+  );
+  const hostedEndpointCopyOptions = endpointCopyOptions.filter((option) =>
+    isHostedAppPairingUrl(option.url),
+  );
+  const renderEndpointMenuItems = (
+    options: typeof endpointCopyOptions = endpointCopyOptions,
+    renderDetail = true,
+  ) =>
+    options.map((option) => (
+      <MenuItem
+        key={option.key}
+        onClick={() => copyPairingValue(option.url, copyKindForUrl(option.url))}
+      >
+        <span className="min-w-0 flex-1">
+          <span className="block truncate">{option.label}</span>
+          {renderDetail ? (
+            <span className="block truncate text-[11px] text-muted-foreground">
+              {option.detail}
+            </span>
+          ) : null}
+        </span>
+      </MenuItem>
+    ));
+  const renderPairingCodeMenuItem = (renderDetail = true) => (
+    <MenuItem onClick={handleCopyCode}>
+      <span className="min-w-0 flex-1">
+        <span className="block truncate">Copy code</span>
+        {renderDetail ? (
+          <span className="block truncate text-[11px] text-muted-foreground">Token only</span>
+        ) : null}
+      </span>
+    </MenuItem>
+  );
+  const renderCompactEndpointGroup = (
+    label: string,
+    options: typeof endpointCopyOptions,
+    includeSeparator: boolean,
+  ) =>
+    options.length > 0 ? (
+      <>
+        {includeSeparator ? <MenuSeparator /> : null}
+        <MenuGroup>
+          <MenuGroupLabel>{label}</MenuGroupLabel>
+          {renderEndpointMenuItems(options, false)}
+        </MenuGroup>
+      </>
+    ) : null;
+  const renderGroupedCopyMenuItems = (options?: { codeFirst?: boolean }) => (
+    <>
+      {options?.codeFirst ? (
+        <>
+          <MenuGroup>
+            <MenuGroupLabel>Pairing code</MenuGroupLabel>
+            {renderPairingCodeMenuItem(false)}
+          </MenuGroup>
+          {endpointCopyOptions.length > 0 ? <MenuSeparator /> : null}
+        </>
+      ) : null}
+      {renderCompactEndpointGroup("Pairing URLs", backendEndpointCopyOptions, false)}
+      {renderCompactEndpointGroup(
+        "Hosted app link",
+        hostedEndpointCopyOptions,
+        backendEndpointCopyOptions.length > 0,
+      )}
+      {!options?.codeFirst ? (
+        <>
+          {endpointCopyOptions.length > 0 ? <MenuSeparator /> : null}
+          <MenuGroup>
+            <MenuGroupLabel>Pairing code</MenuGroupLabel>
+            {renderPairingCodeMenuItem(false)}
+          </MenuGroup>
+        </>
+      ) : null}
+    </>
+  );
 
   if (expiresAtMs <= nowMs) {
     return null;
   }
 
   return (
-    <div className={ITEM_ROW_CLASSNAME}>
+    <div className={accessRowClassName(presentation)}>
       <div className={ITEM_ROW_INNER_CLASSNAME}>
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex min-h-5 items-center gap-1.5">
@@ -375,27 +764,70 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
           <Dialog open={isRevealDialogOpen} onOpenChange={setIsRevealDialogOpen}>
             {canCopyToClipboard ? (
-              <Button size="xs" variant="outline" onClick={handleCopy}>
-                {isCopied ? "Copied" : shareablePairingUrl ? "Copy" : "Copy token"}
-              </Button>
+              <>
+                {shareablePairingUrl ? (
+                  <Group aria-label="Copy selected endpoint">
+                    <Button
+                      size="xs"
+                      variant="outline"
+                      className="max-w-56"
+                      title={`Copy pairing URL for: ${defaultEndpointCopyLabel}`}
+                      onClick={handleCopyDefaultLink}
+                    >
+                      <span className="truncate">
+                        Copy pairing URL for: {defaultEndpointCopyLabel}
+                      </span>
+                    </Button>
+                    <GroupSeparator />
+                    <Menu>
+                      <MenuTrigger
+                        render={
+                          <Button
+                            size="icon-xs"
+                            variant="outline"
+                            aria-label="Choose endpoint to copy"
+                          />
+                        }
+                      >
+                        <ChevronDownIcon className="size-3.5" />
+                      </MenuTrigger>
+                      <MenuPopup align="end" className="min-w-60">
+                        {renderGroupedCopyMenuItems()}
+                      </MenuPopup>
+                    </Menu>
+                  </Group>
+                ) : (
+                  <Button size="xs" variant="outline" onClick={handleCopyCode}>
+                    Copy code
+                  </Button>
+                )}
+              </>
             ) : (
               <DialogTrigger render={<Button size="xs" variant="outline" />}>
-                {shareablePairingUrl ? "Show link" : "Show token"}
+                {shareablePairingUrl ? "Show link" : "Show code"}
               </DialogTrigger>
             )}
             <DialogPopup className="max-w-md">
               <DialogHeader>
-                <DialogTitle>{shareablePairingUrl ? "Pairing link" : "Pairing token"}</DialogTitle>
+                <DialogTitle>
+                  {shareablePairingUrl
+                    ? isShareableHostedAppPairingUrl
+                      ? "Hosted app pairing link"
+                      : "Pairing link"
+                    : "Pairing code"}
+                </DialogTitle>
                 <DialogDescription>
                   {shareablePairingUrl
-                    ? "Clipboard copy is unavailable here. Open or manually copy this full pairing URL on the device you want to connect."
-                    : "Clipboard copy is unavailable here. Manually copy this token and pair from another client using this backend's reachable host."}
+                    ? isShareableHostedAppPairingUrl
+                      ? "Clipboard copy is unavailable here. Open or manually copy this hosted app link on the device you want to connect."
+                      : "Clipboard copy is unavailable here. Open or manually copy this full pairing URL on the device you want to connect."
+                    : "Clipboard copy is unavailable here. Manually copy this code into another client."}
                 </DialogDescription>
               </DialogHeader>
               <DialogPanel className="space-y-4">
                 <Textarea
                   readOnly
-                  value={copyValue}
+                  value={revealValue}
                   rows={shareablePairingUrl ? 4 : 3}
                   className="text-xs leading-relaxed"
                   onFocus={(event) => event.currentTarget.select()}
@@ -418,8 +850,8 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                   Done
                 </Button>
                 {canCopyToClipboard ? (
-                  <Button variant="outline" size="xs" onClick={handleCopy}>
-                    {isCopied ? "Copied" : "Copy again"}
+                  <Button variant="outline" size="xs" onClick={handleCopyCode}>
+                    Copy code
                   </Button>
                 ) : null}
               </DialogFooter>
@@ -441,12 +873,14 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
 
 type ConnectedClientListRowProps = {
   clientSession: ServerClientSessionRecord;
+  presentation?: AccessSectionPresentation;
   revokingClientSessionId: string | null;
   onRevokeSession: (sessionId: ServerClientSessionRecord["sessionId"]) => void;
 };
 
 const ConnectedClientListRow = memo(function ConnectedClientListRow({
   clientSession,
+  presentation = "current",
   revokingClientSessionId,
   onRevokeSession,
 }: ConnectedClientListRowProps) {
@@ -475,7 +909,7 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
       clientSession.subject);
 
   return (
-    <div className={ITEM_ROW_CLASSNAME}>
+    <div className={accessRowClassName(presentation)}>
       <div className={ITEM_ROW_INNER_CLASSNAME}>
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex min-h-5 items-center gap-1.5">
@@ -535,11 +969,13 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio
       setDialogOpen(false);
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to create pairing URL.";
-      toastManager.add({
-        type: "error",
-        title: "Could not create pairing URL",
-        description: message,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not create pairing URL",
+          description: message,
+        }),
+      );
     } finally {
       setIsCreatingPairingLink(false);
     }
@@ -616,6 +1052,9 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio
 
 type PairingClientsListProps = {
   endpointUrl: string | null | undefined;
+  endpoints: ReadonlyArray<AdvertisedEndpoint>;
+  defaultEndpointKey: string | null;
+  presentation?: AccessSectionPresentation;
   isLoading: boolean;
   pairingLinks: ReadonlyArray<ServerPairingLinkRecord>;
   clientSessions: ReadonlyArray<ServerClientSessionRecord>;
@@ -627,6 +1066,9 @@ type PairingClientsListProps = {
 
 const PairingClientsList = memo(function PairingClientsList({
   endpointUrl,
+  endpoints,
+  defaultEndpointKey,
+  presentation = "current",
   isLoading,
   pairingLinks,
   clientSessions,
@@ -642,6 +1084,9 @@ const PairingClientsList = memo(function PairingClientsList({
           key={pairingLink.id}
           pairingLink={pairingLink}
           endpointUrl={endpointUrl}
+          endpoints={endpoints}
+          defaultEndpointKey={defaultEndpointKey}
+          presentation={presentation}
           revokingPairingLinkId={revokingPairingLinkId}
           onRevoke={onRevokePairingLink}
         />
@@ -651,13 +1096,14 @@ const PairingClientsList = memo(function PairingClientsList({
         <ConnectedClientListRow
           key={clientSession.sessionId}
           clientSession={clientSession}
+          presentation={presentation}
           revokingClientSessionId={revokingClientSessionId}
           onRevokeSession={onRevokeClientSession}
         />
       ))}
 
       {pairingLinks.length === 0 && clientSessions.length === 0 && !isLoading ? (
-        <div className={ITEM_ROW_CLASSNAME}>
+        <div className={accessRowClassName(presentation)}>
           <p className="text-xs text-muted-foreground/60">No pairing links or client sessions.</p>
         </div>
       ) : null}
@@ -665,19 +1111,156 @@ const PairingClientsList = memo(function PairingClientsList({
   );
 });
 
+type AdvertisedEndpointListRowProps = {
+  endpoint: AdvertisedEndpoint;
+  isDefault: boolean;
+  presentation?: AccessSectionPresentation;
+  onSetDefault: (endpoint: AdvertisedEndpoint) => void;
+  onSetupTailscaleServe: (endpoint: AdvertisedEndpoint) => void;
+  onDisableTailscaleServe: (endpoint: AdvertisedEndpoint) => void;
+  isUpdatingTailscaleServe: boolean;
+};
+
+const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
+  endpoint,
+  isDefault,
+  presentation = "current",
+  onSetDefault,
+  onSetupTailscaleServe,
+  onDisableTailscaleServe,
+  isUpdatingTailscaleServe,
+}: AdvertisedEndpointListRowProps) {
+  const isAvailable = endpoint.status === "available";
+  const needsTailscaleSetup = isTailscaleHttpsEndpoint(endpoint) && endpoint.status !== "available";
+  const canDisableTailscaleServe =
+    isTailscaleHttpsEndpoint(endpoint) && endpoint.status === "available";
+  const shouldShowEndpointUrl = !needsTailscaleSetup;
+  const isEndpointRail = presentation === "endpoint-rail";
+  return (
+    <div className={endpointRowClassName(presentation, isAvailable)}>
+      {isEndpointRail && isDefault ? (
+        <span className="absolute inset-y-2 left-0 w-1 rounded-r-full bg-primary" aria-hidden />
+      ) : null}
+      <div className="flex min-h-6 min-w-0 flex-col gap-2 sm:-my-0.5 sm:flex-row sm:items-center">
+        <div className="flex min-w-0 items-baseline gap-3">
+          <h3 className="shrink-0 text-sm leading-5 font-medium text-foreground">
+            {endpoint.label}
+          </h3>
+          {shouldShowEndpointUrl ? (
+            <p
+              className="min-w-0 truncate text-xs leading-5 text-muted-foreground"
+              title={endpoint.httpBaseUrl}
+            >
+              {endpoint.httpBaseUrl}
+            </p>
+          ) : null}
+          {!isAvailable ? (
+            <span className="shrink-0 rounded-md border border-border/70 px-1 py-0.5 text-[10px] text-muted-foreground">
+              Setup required
+            </span>
+          ) : null}
+        </div>
+        <div className="ml-auto flex min-h-6 shrink-0 items-center justify-end gap-2">
+          {isDefault ? (
+            <span className="rounded-md border border-primary/30 bg-primary/10 px-1 py-0.5 text-[10px] text-primary">
+              Default
+            </span>
+          ) : null}
+          {needsTailscaleSetup ? (
+            <Button
+              size="xs"
+              variant="outline"
+              onClick={() => onSetupTailscaleServe(endpoint)}
+              disabled={isUpdatingTailscaleServe}
+            >
+              {isUpdatingTailscaleServe ? "Restarting…" : "Setup"}
+            </Button>
+          ) : null}
+          {canDisableTailscaleServe ? (
+            <Button
+              size="xs"
+              variant="destructive-outline"
+              onClick={() => onDisableTailscaleServe(endpoint)}
+              disabled={isUpdatingTailscaleServe}
+            >
+              {isUpdatingTailscaleServe ? "Restarting…" : "Disable"}
+            </Button>
+          ) : null}
+          {!needsTailscaleSetup && !isDefault ? (
+            <Button size="xs" variant="outline" onClick={() => onSetDefault(endpoint)}>
+              Set as default
+            </Button>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+});
+
+function NetworkAccessDescription({
+  endpoint,
+  hiddenEndpointCount,
+  expanded,
+  onToggleExpanded,
+  fallback,
+}: {
+  endpoint: AdvertisedEndpoint | null;
+  hiddenEndpointCount: number;
+  expanded: boolean;
+  onToggleExpanded: () => void;
+  fallback: ReactNode;
+}) {
+  if (!endpoint) {
+    return fallback;
+  }
+
+  const summary = (
+    <>
+      <span className="min-w-0 truncate">{endpoint.httpBaseUrl}</span>
+      {hiddenEndpointCount > 0 ? (
+        <span className="shrink-0 text-xs font-medium">
+          {expanded ? "Hide" : `+${hiddenEndpointCount}`}
+        </span>
+      ) : null}
+    </>
+  );
+
+  return (
+    <span className="inline-flex min-w-0 max-w-full items-baseline gap-1">
+      <span className="shrink-0">Reachable at</span>
+      {hiddenEndpointCount > 0 ? (
+        <button
+          type="button"
+          className="inline-flex min-w-0 max-w-full items-baseline gap-2 border-b border-dotted border-muted-foreground/60 text-left text-muted-foreground underline-offset-4 hover:border-foreground hover:text-foreground"
+          onClick={onToggleExpanded}
+          aria-expanded={expanded}
+        >
+          {summary}
+        </button>
+      ) : (
+        <span className="inline-flex min-w-0 max-w-full items-baseline gap-2">{summary}</span>
+      )}
+    </span>
+  );
+}
+
 type SavedBackendListRowProps = {
   environmentId: EnvironmentId;
   reconnectingEnvironmentId: EnvironmentId | null;
+  disconnectingEnvironmentId: EnvironmentId | null;
   removingEnvironmentId: EnvironmentId | null;
-  onReconnect: (environmentId: EnvironmentId) => void;
+  onConnect: (environmentId: EnvironmentId) => void;
+  onDisconnect: (environmentId: EnvironmentId) => void;
   onRemove: (environmentId: EnvironmentId) => void;
 };
 
 function SavedBackendListRow({
   environmentId,
   reconnectingEnvironmentId,
+  disconnectingEnvironmentId,
   removingEnvironmentId,
-  onReconnect,
+  onConnect,
+  onDisconnect,
   onRemove,
 }: SavedBackendListRowProps) {
   const nowMs = useRelativeTimeTick(1_000);
@@ -689,6 +1272,10 @@ function SavedBackendListRow({
   }
 
   const connectionState = runtime?.connectionState ?? "disconnected";
+  const isConnected = connectionState === "connected";
+  const isConnecting =
+    connectionState === "connecting" || reconnectingEnvironmentId === environmentId;
+  const isDisconnecting = disconnectingEnvironmentId === environmentId;
   const stateDotClassName =
     connectionState === "connected"
       ? "bg-success"
@@ -699,8 +1286,11 @@ function SavedBackendListRow({
           : "bg-muted-foreground/40";
   const roleLabel = runtime?.role ? (runtime.role === "owner" ? "Owner" : "Client") : null;
   const descriptorLabel = runtime?.descriptor?.label ?? null;
+  const displayLabel = descriptorLabel ?? record.label;
   const statusTooltip = getSavedBackendStatusTooltip(runtime, record, nowMs);
+  const versionMismatch = resolveServerConfigVersionMismatch(runtime?.serverConfig);
   const metadataBits = [
+    record.desktopSsh ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}` : null,
     roleLabel,
     record.lastConnectedAt
       ? `Last connected ${formatAccessTimestamp(record.lastConnectedAt)}`
@@ -719,23 +1309,35 @@ function SavedBackendListRow({
                 connectionState === "connecting" ? "bg-warning/60 duration-2000" : null
               }
             />
-            <h3 className="text-sm font-medium text-foreground">{record.label}</h3>
+            <h3 className="text-sm font-medium text-foreground">{displayLabel}</h3>
           </div>
           {metadataBits.length > 0 ? (
             <p className="text-xs text-muted-foreground">{metadataBits.join(" · ")}</p>
           ) : null}
-          {descriptorLabel && descriptorLabel !== record.label ? (
-            <p className="text-xs text-muted-foreground">Server label: {descriptorLabel}</p>
+          {versionMismatch ? (
+            <p className="flex items-center gap-1 text-warning text-xs">
+              <TriangleAlertIcon className="size-3.5 shrink-0" />
+              Version drift: client {versionMismatch.clientVersion}, server{" "}
+              {versionMismatch.serverVersion}.
+            </p>
           ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
           <Button
             size="xs"
             variant="outline"
-            disabled={reconnectingEnvironmentId === environmentId}
-            onClick={() => void onReconnect(environmentId)}
+            disabled={isConnected ? isDisconnecting : isConnecting}
+            onClick={() =>
+              void (isConnected ? onDisconnect(environmentId) : onConnect(environmentId))
+            }
           >
-            {reconnectingEnvironmentId === environmentId ? "Reconnecting…" : "Reconnect"}
+            {isConnected
+              ? isDisconnecting
+                ? "Disconnecting…"
+                : "Disconnect"
+              : isConnecting
+                ? "Connecting…"
+                : "Connect"}
           </Button>
           <Button
             size="xs"
@@ -751,6 +1353,46 @@ function SavedBackendListRow({
   );
 }
 
+interface DesktopSshHostRowProps {
+  target: DesktopDiscoveredSshHost;
+  connectingHostAlias: string | null;
+  onConnect: (target: DesktopDiscoveredSshHost) => void;
+}
+
+const DesktopSshHostRow = memo(function DesktopSshHostRow({
+  target,
+  connectingHostAlias,
+  onConnect,
+}: DesktopSshHostRowProps) {
+  const address = formatDesktopSshTarget(target);
+  const showAddress = address !== target.alias;
+  const buttonLabel = connectingHostAlias === target.alias ? "Adding…" : "Add environment";
+
+  return (
+    <div className="border-t border-border/60 px-4 py-3 first:border-t-0 sm:px-5">
+      <div className={ITEM_ROW_INNER_CLASSNAME}>
+        <div className="min-w-0 flex-1">
+          <h3 className="truncate text-sm font-medium text-foreground">{target.alias}</h3>
+          {showAddress ? <p className="truncate text-xs text-muted-foreground">{address}</p> : null}
+        </div>
+        <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
+          <Button
+            size="xs"
+            variant="outline"
+            disabled={connectingHostAlias === target.alias}
+            onClick={() => onConnect(target)}
+          >
+            {connectingHostAlias === target.alias ? (
+              <RefreshCwIcon className="size-3 animate-spin" />
+            ) : null}
+            {buttonLabel}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+});
+
 export function ConnectionsSettings() {
   const desktopBridge = window.desktopBridge;
   const [currentSessionRole, setCurrentSessionRole] = useState<"owner" | "client" | null>(
@@ -767,9 +1409,42 @@ export function ConnectionsSettings() {
         .map((record) => record.environmentId),
     [savedEnvironmentsById],
   );
+  const savedDesktopSshEnvironmentsByAlias = useMemo(
+    () =>
+      Object.values(savedEnvironmentsById).reduce<Record<string, SavedEnvironmentRecord>>(
+        (accumulator, record) => {
+          if (record.desktopSsh?.alias) {
+            accumulator[record.desktopSsh.alias] = record;
+          }
+          return accumulator;
+        },
+        {},
+      ),
+    [savedEnvironmentsById],
+  );
+  const savedDesktopSshEnvironmentKeys = useMemo(() => {
+    const keys = new Set<string>();
+    for (const record of Object.values(savedEnvironmentsById)) {
+      const target = record.desktopSsh;
+      if (!target) continue;
+      keys.add(target.alias);
+      keys.add(formatDesktopSshTarget(target));
+    }
+    return keys;
+  }, [savedEnvironmentsById]);
+  const [discoveredSshHosts, setDiscoveredSshHosts] = useState<
+    ReadonlyArray<DesktopDiscoveredSshHost>
+  >([]);
+  const [hasLoadedDiscoveredSshHosts, setHasLoadedDiscoveredSshHosts] = useState(false);
+  const [isLoadingDiscoveredSshHosts, setIsLoadingDiscoveredSshHosts] = useState(false);
+  const [discoveredSshHostsError, setDiscoveredSshHostsError] = useState<string | null>(null);
+  const [connectingSshHostAlias, setConnectingSshHostAlias] = useState<string | null>(null);
 
   const [desktopServerExposureState, setDesktopServerExposureState] =
     useState<DesktopServerExposureState | null>(null);
+  const [desktopAdvertisedEndpoints, setDesktopAdvertisedEndpoints] = useState<
+    ReadonlyArray<AdvertisedEndpoint>
+  >([]);
   const [desktopServerExposureError, setDesktopServerExposureError] = useState<string | null>(null);
   const [desktopPairingLinks, setDesktopPairingLinks] = useState<
     ReadonlyArray<ServerPairingLinkRecord>
@@ -789,27 +1464,78 @@ export function ConnectionsSettings() {
   >(null);
   const [isRevokingOtherDesktopClients, setIsRevokingOtherDesktopClients] = useState(false);
   const [addBackendDialogOpen, setAddBackendDialogOpen] = useState(false);
-  const [savedBackendMode, setSavedBackendMode] = useState<"pairing-url" | "host-code">(
-    "pairing-url",
-  );
-  const [savedBackendLabel, setSavedBackendLabel] = useState("");
-  const [savedBackendPairingUrl, setSavedBackendPairingUrl] = useState("");
+  const [savedBackendMode, setSavedBackendMode] = useState<"remote" | "ssh">("remote");
   const [savedBackendHost, setSavedBackendHost] = useState("");
   const [savedBackendPairingCode, setSavedBackendPairingCode] = useState("");
+  const [savedBackendSshHost, setSavedBackendSshHost] = useState("");
+  const [savedBackendSshUsername, setSavedBackendSshUsername] = useState("");
+  const [savedBackendSshPort, setSavedBackendSshPort] = useState("");
   const [savedBackendError, setSavedBackendError] = useState<string | null>(null);
   const [isAddingSavedBackend, setIsAddingSavedBackend] = useState(false);
+  const unsavedDiscoveredSshHosts = useMemo(
+    () =>
+      discoveredSshHosts.filter((target) => {
+        const address = formatDesktopSshTarget(target);
+        return (
+          !savedDesktopSshEnvironmentKeys.has(target.alias) &&
+          !savedDesktopSshEnvironmentKeys.has(address)
+        );
+      }),
+    [discoveredSshHosts, savedDesktopSshEnvironmentKeys],
+  );
   const [reconnectingSavedEnvironmentId, setReconnectingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
+  const [disconnectingSavedEnvironmentId, setDisconnectingSavedEnvironmentId] =
+    useState<EnvironmentId | null>(null);
   const [removingSavedEnvironmentId, setRemovingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
   const [isUpdatingDesktopServerExposure, setIsUpdatingDesktopServerExposure] = useState(false);
+  const [isDesktopServerExposureDialogOpen, setIsDesktopServerExposureDialogOpen] = useState(false);
+  const [isUpdatingTailscaleServe, setIsUpdatingTailscaleServe] = useState(false);
+  const [pendingTailscaleServeEndpoint, setPendingTailscaleServeEndpoint] =
+    useState<AdvertisedEndpoint | null>(null);
+  const [disableTailscaleServeDialogOpen, setDisableTailscaleServeDialogOpen] = useState(false);
+  const [tailscaleServePortInput, setTailscaleServePortInput] = useState(
+    String(DEFAULT_TAILSCALE_SERVE_PORT),
+  );
   const [pendingDesktopServerExposureMode, setPendingDesktopServerExposureMode] = useState<
     DesktopServerExposureState["mode"] | null
   >(null);
+  const primaryServerConfig = useServerConfig();
+  const primaryVersionMismatch = resolveServerConfigVersionMismatch(primaryServerConfig);
+  const [isAdvertisedEndpointListExpanded, setIsAdvertisedEndpointListExpanded] = useState(false);
+  const defaultAdvertisedEndpointKey = useUiStateStore(
+    (state) => state.defaultAdvertisedEndpointKey,
+  );
+  const setDefaultAdvertisedEndpointKey = useUiStateStore(
+    (state) => state.setDefaultAdvertisedEndpointKey,
+  );
   const canManageLocalBackend = currentSessionRole === "owner";
   const isLocalBackendNetworkAccessible = desktopBridge
     ? desktopServerExposureState?.mode === "network-accessible"
     : currentAuthPolicy === "remote-reachable";
+  const trimmedTailscaleServePortInput = tailscaleServePortInput.trim();
+  const parsedTailscaleServePort = Number(trimmedTailscaleServePortInput);
+  const isTailscaleServePortValid =
+    /^\d+$/u.test(trimmedTailscaleServePortInput) &&
+    Number.isInteger(parsedTailscaleServePort) &&
+    parsedTailscaleServePort >= 1 &&
+    parsedTailscaleServePort <= 65_535;
+
+  const pendingTailscaleServeBaseUrl = useMemo(() => {
+    if (!pendingTailscaleServeEndpoint) return null;
+    if (!isTailscaleServePortValid) return pendingTailscaleServeEndpoint.httpBaseUrl;
+    if (parsedTailscaleServePort === DEFAULT_TAILSCALE_SERVE_PORT) {
+      return pendingTailscaleServeEndpoint.httpBaseUrl;
+    }
+    try {
+      const url = new URL(pendingTailscaleServeEndpoint.httpBaseUrl);
+      url.port = String(parsedTailscaleServePort);
+      return url.toString().replace(/\/$/u, "");
+    } catch {
+      return pendingTailscaleServeEndpoint.httpBaseUrl;
+    }
+  }, [isTailscaleServePortValid, parsedTailscaleServePort, pendingTailscaleServeEndpoint]);
 
   const handleDesktopServerExposureChange = useCallback(
     async (checked: boolean) => {
@@ -821,18 +1547,20 @@ export function ConnectionsSettings() {
           checked ? "network-accessible" : "local-only",
         );
         setDesktopServerExposureState(nextState);
-        setPendingDesktopServerExposureMode(null);
+        setIsDesktopServerExposureDialogOpen(false);
         setIsUpdatingDesktopServerExposure(false);
       } catch (error) {
         const message =
           error instanceof Error ? error.message : "Failed to update network exposure.";
-        setPendingDesktopServerExposureMode(null);
+        setIsDesktopServerExposureDialogOpen(false);
         setDesktopServerExposureError(message);
-        toastManager.add({
-          type: "error",
-          title: "Could not update network access",
-          description: message,
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not update network access",
+            description: message,
+          }),
+        );
         setIsUpdatingDesktopServerExposure(false);
       }
     },
@@ -845,6 +1573,74 @@ export function ConnectionsSettings() {
     void handleDesktopServerExposureChange(checked);
   }, [handleDesktopServerExposureChange, pendingDesktopServerExposureMode]);
 
+  const handleConfirmTailscaleServeSetup = useCallback(async () => {
+    if (!desktopBridge) return;
+    if (!isTailscaleServePortValid) return;
+    setIsUpdatingTailscaleServe(true);
+    setDesktopServerExposureError(null);
+    try {
+      const nextState = await desktopBridge.setTailscaleServeEnabled({
+        enabled: true,
+        port: parsedTailscaleServePort,
+      });
+      setDesktopServerExposureState(nextState);
+      setPendingTailscaleServeEndpoint(null);
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Failed to configure Tailscale HTTPS.";
+      setDesktopServerExposureError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not set up Tailscale HTTPS",
+          description: message,
+        }),
+      );
+    } finally {
+      setIsUpdatingTailscaleServe(false);
+    }
+  }, [desktopBridge, isTailscaleServePortValid, parsedTailscaleServePort]);
+
+  const handleStartTailscaleServeSetup = useCallback(
+    (endpoint: AdvertisedEndpoint) => {
+      setTailscaleServePortInput(
+        String(desktopServerExposureState?.tailscaleServePort ?? DEFAULT_TAILSCALE_SERVE_PORT),
+      );
+      setPendingTailscaleServeEndpoint(endpoint);
+    },
+    [desktopServerExposureState?.tailscaleServePort],
+  );
+
+  const handleConfirmTailscaleServeDisable = useCallback(async () => {
+    if (!desktopBridge) return;
+    setIsUpdatingTailscaleServe(true);
+    setDesktopServerExposureError(null);
+    try {
+      const nextState = await desktopBridge.setTailscaleServeEnabled({
+        enabled: false,
+        port: desktopServerExposureState?.tailscaleServePort ?? DEFAULT_TAILSCALE_SERVE_PORT,
+      });
+      setDesktopServerExposureState(nextState);
+      setDisableTailscaleServeDialogOpen(false);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to disable Tailscale HTTPS.";
+      setDesktopServerExposureError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not disable Tailscale HTTPS",
+          description: message,
+        }),
+      );
+    } finally {
+      setIsUpdatingTailscaleServe(false);
+    }
+  }, [desktopBridge, desktopServerExposureState?.tailscaleServePort]);
+
+  const handleStartTailscaleServeDisable = useCallback((_endpoint: AdvertisedEndpoint) => {
+    setDisableTailscaleServeDialogOpen(true);
+  }, []);
+
   const handleRevokeDesktopPairingLink = useCallback(async (id: string) => {
     setRevokingDesktopPairingLinkId(id);
     setDesktopAccessManagementError(null);
@@ -853,11 +1649,13 @@ export function ConnectionsSettings() {
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to revoke pairing link.";
       setDesktopAccessManagementError(message);
-      toastManager.add({
-        type: "error",
-        title: "Could not revoke pairing link",
-        description: message,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not revoke pairing link",
+          description: message,
+        }),
+      );
     } finally {
       setRevokingDesktopPairingLinkId(null);
     }
@@ -872,11 +1670,13 @@ export function ConnectionsSettings() {
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to revoke client access.";
         setDesktopAccessManagementError(message);
-        toastManager.add({
-          type: "error",
-          title: "Could not revoke client access",
-          description: message,
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not revoke client access",
+            description: message,
+          }),
+        );
       } finally {
         setRevokingDesktopClientSessionId(null);
       }
@@ -897,33 +1697,66 @@ export function ConnectionsSettings() {
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to revoke other clients.";
       setDesktopAccessManagementError(message);
-      toastManager.add({
-        type: "error",
-        title: "Could not revoke other clients",
-        description: message,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not revoke other clients",
+          description: message,
+        }),
+      );
     } finally {
       setIsRevokingOtherDesktopClients(false);
     }
   }, []);
 
   const handleAddSavedBackend = useCallback(async () => {
+    if (savedBackendMode === "ssh") {
+      setIsAddingSavedBackend(true);
+      setSavedBackendError(null);
+      try {
+        const target = parseManualDesktopSshTarget({
+          host: savedBackendSshHost,
+          username: savedBackendSshUsername,
+          port: savedBackendSshPort,
+        });
+        const record = await connectDesktopSshEnvironment(target, { label: "" });
+        setSavedBackendHost("");
+        setSavedBackendPairingCode("");
+        setSavedBackendSshHost("");
+        setSavedBackendSshUsername("");
+        setSavedBackendSshPort("");
+
+        setAddBackendDialogOpen(false);
+        toastManager.add({
+          type: "success",
+          title: "Environment connected",
+          description: `${record.label} is ready over an SSH-managed tunnel.`,
+        });
+      } catch (error) {
+        const message = formatDesktopSshConnectionError(error);
+        setSavedBackendError(message);
+      } finally {
+        setIsAddingSavedBackend(false);
+      }
+      return;
+    }
+
     setIsAddingSavedBackend(true);
     setSavedBackendError(null);
     try {
+      const remotePairingInput = parseRemotePairingFields({
+        host: savedBackendHost,
+        pairingCode: savedBackendPairingCode,
+      });
       const record = await addSavedEnvironment({
-        label: savedBackendLabel,
-        ...(savedBackendMode === "pairing-url"
-          ? { pairingUrl: savedBackendPairingUrl }
-          : {
-              host: savedBackendHost,
-              pairingCode: savedBackendPairingCode,
-            }),
+        label: "",
+        ...remotePairingInput,
       });
-      setSavedBackendLabel("");
-      setSavedBackendPairingUrl("");
       setSavedBackendHost("");
       setSavedBackendPairingCode("");
+      setSavedBackendSshHost("");
+      setSavedBackendSshUsername("");
+      setSavedBackendSshPort("");
       setAddBackendDialogOpen(false);
       toastManager.add({
         type: "success",
@@ -933,40 +1766,65 @@ export function ConnectionsSettings() {
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to add backend.";
       setSavedBackendError(message);
-      toastManager.add({
-        type: "error",
-        title: "Could not add backend",
-        description: message,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not add backend",
+          description: message,
+        }),
+      );
     } finally {
       setIsAddingSavedBackend(false);
     }
   }, [
     savedBackendHost,
-    savedBackendLabel,
     savedBackendMode,
     savedBackendPairingCode,
-    savedBackendPairingUrl,
+    savedBackendSshHost,
+    savedBackendSshPort,
+    savedBackendSshUsername,
   ]);
 
-  const handleReconnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
+  const handleConnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
     setReconnectingSavedEnvironmentId(environmentId);
     setSavedBackendError(null);
     try {
       await reconnectSavedEnvironment(environmentId);
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to reconnect backend.";
+      const message = error instanceof Error ? error.message : "Failed to connect backend.";
       setSavedBackendError(message);
-      toastManager.add({
-        type: "error",
-        title: "Could not reconnect backend",
-        description: message,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not connect backend",
+          description: message,
+        }),
+      );
     } finally {
       setReconnectingSavedEnvironmentId(null);
     }
   }, []);
 
+  const handleDisconnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
+    setDisconnectingSavedEnvironmentId(environmentId);
+    setSavedBackendError(null);
+    try {
+      await disconnectSavedEnvironment(environmentId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to disconnect backend.";
+      setSavedBackendError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not disconnect backend",
+          description: message,
+        }),
+      );
+    } finally {
+      setDisconnectingSavedEnvironmentId(null);
+    }
+  }, []);
+
   const handleRemoveSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
     setRemovingSavedEnvironmentId(environmentId);
     setSavedBackendError(null);
@@ -975,16 +1833,96 @@ export function ConnectionsSettings() {
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to remove backend.";
       setSavedBackendError(message);
-      toastManager.add({
-        type: "error",
-        title: "Could not remove backend",
-        description: message,
-      });
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not remove backend",
+          description: message,
+        }),
+      );
     } finally {
       setRemovingSavedEnvironmentId(null);
     }
   }, []);
 
+  const loadDiscoveredSshHosts = useCallback(async () => {
+    if (!desktopBridge) {
+      setDiscoveredSshHosts([]);
+      setHasLoadedDiscoveredSshHosts(false);
+      setDiscoveredSshHostsError(null);
+      return;
+    }
+
+    setIsLoadingDiscoveredSshHosts(true);
+    setDiscoveredSshHostsError(null);
+    try {
+      const hosts = await desktopBridge.discoverSshHosts();
+      setDiscoveredSshHosts(hosts);
+      setHasLoadedDiscoveredSshHosts(true);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to discover SSH hosts.";
+      setDiscoveredSshHostsError(message);
+      setHasLoadedDiscoveredSshHosts(true);
+    } finally {
+      setIsLoadingDiscoveredSshHosts(false);
+    }
+  }, [desktopBridge]);
+
+  const handleConnectSshHost = useCallback(
+    async (target: DesktopSshEnvironmentTarget, label?: string) => {
+      setConnectingSshHostAlias(target.alias);
+      if (savedBackendMode === "ssh") {
+        setSavedBackendError(null);
+      } else {
+        setDiscoveredSshHostsError(null);
+      }
+      try {
+        const record = await connectDesktopSshEnvironment(
+          target,
+          label === undefined ? undefined : { label },
+        );
+        setSavedBackendSshHost("");
+        setSavedBackendSshUsername("");
+        setSavedBackendSshPort("");
+        setAddBackendDialogOpen(false);
+        toastManager.add({
+          type: "success",
+          title: savedDesktopSshEnvironmentsByAlias[target.alias]
+            ? "Environment reconnected"
+            : "Environment connected",
+          description: `${record.label} is ready over an SSH-managed tunnel.`,
+        });
+      } catch (error) {
+        const message = formatDesktopSshConnectionError(error);
+        if (savedBackendMode === "ssh") {
+          setSavedBackendError(message);
+        } else {
+          setDiscoveredSshHostsError(message);
+        }
+      } finally {
+        setConnectingSshHostAlias(null);
+      }
+    },
+    [savedBackendMode, savedDesktopSshEnvironmentsByAlias],
+  );
+
+  useEffect(() => {
+    if (!desktopBridge || !addBackendDialogOpen || savedBackendMode !== "ssh") {
+      return;
+    }
+    if (hasLoadedDiscoveredSshHosts || isLoadingDiscoveredSshHosts) {
+      return;
+    }
+    void loadDiscoveredSshHosts();
+  }, [
+    addBackendDialogOpen,
+    desktopBridge,
+    hasLoadedDiscoveredSshHosts,
+    isLoadingDiscoveredSshHosts,
+    loadDiscoveredSshHosts,
+    savedBackendMode,
+  ]);
+
   useEffect(() => {
     if (desktopBridge) {
       setCurrentSessionRole("owner");
@@ -1087,8 +2025,21 @@ export function ConnectionsSettings() {
             error instanceof Error ? error.message : "Failed to load network exposure state.";
           setDesktopServerExposureError(message);
         });
+      void desktopBridge
+        .getAdvertisedEndpoints()
+        .then((endpoints) => {
+          if (cancelled) return;
+          setDesktopAdvertisedEndpoints(endpoints);
+        })
+        .catch((error: unknown) => {
+          if (cancelled) return;
+          const message =
+            error instanceof Error ? error.message : "Failed to load reachable endpoints.";
+          setDesktopServerExposureError(message);
+        });
     } else {
       setDesktopServerExposureState(null);
+      setDesktopAdvertisedEndpoints([]);
       setDesktopServerExposureError(null);
     }
 
@@ -1105,131 +2056,420 @@ export function ConnectionsSettings() {
     setDesktopClientSessions([]);
     setDesktopAccessManagementError(null);
     setDesktopServerExposureState(null);
+    setDesktopAdvertisedEndpoints([]);
     setDesktopServerExposureError(null);
   }, [canManageLocalBackend]);
   const visibleDesktopPairingLinks = useMemo(
     () => desktopPairingLinks.filter((pairingLink) => pairingLink.role === "client"),
     [desktopPairingLinks],
   );
+  const tailscaleHttpsEndpoint = useMemo(
+    () => desktopAdvertisedEndpoints.find(isTailscaleHttpsEndpoint) ?? null,
+    [desktopAdvertisedEndpoints],
+  );
+  const visibleDesktopNetworkAdvertisedEndpoints = useMemo(
+    () =>
+      isLocalBackendNetworkAccessible
+        ? desktopAdvertisedEndpoints.filter((endpoint) => !isTailscaleHttpsEndpoint(endpoint))
+        : [],
+    [desktopAdvertisedEndpoints, isLocalBackendNetworkAccessible],
+  );
+  const visibleDesktopAdvertisedEndpoints = useMemo(
+    () =>
+      tailscaleHttpsEndpoint
+        ? [...visibleDesktopNetworkAdvertisedEndpoints, tailscaleHttpsEndpoint]
+        : visibleDesktopNetworkAdvertisedEndpoints,
+    [tailscaleHttpsEndpoint, visibleDesktopNetworkAdvertisedEndpoints],
+  );
+  const isLocalBackendRemotelyReachable =
+    isLocalBackendNetworkAccessible || tailscaleHttpsEndpoint?.status === "available";
+  const defaultDesktopNetworkAdvertisedEndpoint = useMemo(
+    () =>
+      selectPairingEndpoint(visibleDesktopNetworkAdvertisedEndpoints, defaultAdvertisedEndpointKey),
+    [defaultAdvertisedEndpointKey, visibleDesktopNetworkAdvertisedEndpoints],
+  );
+  const defaultDesktopAdvertisedEndpoint = useMemo(
+    () =>
+      defaultDesktopNetworkAdvertisedEndpoint ??
+      selectPairingEndpoint(
+        tailscaleHttpsEndpoint ? [tailscaleHttpsEndpoint] : [],
+        defaultAdvertisedEndpointKey,
+      ),
+    [defaultAdvertisedEndpointKey, defaultDesktopNetworkAdvertisedEndpoint, tailscaleHttpsEndpoint],
+  );
+  const defaultDesktopAdvertisedEndpointKey = defaultDesktopAdvertisedEndpoint
+    ? endpointDefaultPreferenceKey(defaultDesktopAdvertisedEndpoint)
+    : null;
+  const handleSetDefaultAdvertisedEndpoint = useCallback(
+    (endpoint: AdvertisedEndpoint) => {
+      setDefaultAdvertisedEndpointKey(endpointDefaultPreferenceKey(endpoint));
+    },
+    [setDefaultAdvertisedEndpointKey],
+  );
+  const handleSavedBackendHostChange = useCallback((value: string) => {
+    const parsedPairingUrl = parsePairingUrlFields(value);
+    if (parsedPairingUrl) {
+      setSavedBackendHost(parsedPairingUrl.host);
+      setSavedBackendPairingCode(parsedPairingUrl.pairingCode);
+      return;
+    }
+    setSavedBackendHost(value);
+  }, []);
+
+  const renderConnectionModeCard = (input: {
+    readonly mode: "remote" | "ssh";
+    readonly title: string;
+    readonly description: string;
+    readonly icon?: ReactNode;
+  }) => {
+    const selected = savedBackendMode === input.mode;
+    return (
+      <button
+        type="button"
+        aria-pressed={selected}
+        className={cn(
+          "group flex min-h-24 items-start gap-3 rounded-lg border p-4 text-left",
+          selected ? "border-primary/50 bg-primary/5" : "border-border/60 hover:bg-muted/40",
+        )}
+        disabled={isAddingSavedBackend}
+        onClick={() => {
+          setSavedBackendMode(input.mode);
+        }}
+      >
+        {input.icon ? (
+          <span
+            className={cn(
+              "mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-md border",
+              selected
+                ? "border-primary/30 bg-primary/10 text-primary"
+                : "border-border/70 bg-background text-muted-foreground group-hover:text-foreground",
+            )}
+          >
+            {input.icon}
+          </span>
+        ) : null}
+        <span className="min-w-0">
+          <span className="block text-sm font-medium text-foreground">{input.title}</span>
+          <span className="mt-1 block text-xs leading-relaxed text-muted-foreground">
+            {input.description}
+          </span>
+        </span>
+      </button>
+    );
+  };
+
+  const renderRemoteFields = () => (
+    <div className="space-y-3">
+      <div className="grid gap-3 sm:grid-cols-[minmax(0,1fr)_10rem]">
+        <label className="block">
+          <span className="mb-1.5 block text-xs font-medium text-foreground">Host</span>
+          <Input
+            value={savedBackendHost}
+            onChange={(event) => handleSavedBackendHostChange(event.target.value)}
+            placeholder="backend.example.com"
+            disabled={isAddingSavedBackend}
+            spellCheck={false}
+          />
+        </label>
+        <label className="block">
+          <span className="mb-1.5 block text-xs font-medium text-foreground">Pairing code</span>
+          <Input
+            value={savedBackendPairingCode}
+            onChange={(event) => setSavedBackendPairingCode(event.target.value)}
+            placeholder="PAIRCODE"
+            disabled={isAddingSavedBackend}
+            spellCheck={false}
+          />
+        </label>
+      </div>
+      <div>
+        <span className="mt-1 block text-[11px] text-muted-foreground">
+          Paste a full pairing URL here to fill both fields automatically.
+        </span>
+      </div>
+    </div>
+  );
+  const renderRemoteModeBody = () => (
+    <div className="space-y-4">
+      {renderRemoteFields()}
+      {savedBackendError ? <p className="text-xs text-destructive">{savedBackendError}</p> : null}
+      <Button
+        variant="outline"
+        className="w-full"
+        disabled={isAddingSavedBackend}
+        onClick={() => void handleAddSavedBackend()}
+      >
+        <PlusIcon className="size-3.5" />
+        {isAddingSavedBackend ? "Adding…" : "Add environment"}
+      </Button>
+    </div>
+  );
+  const renderSshFields = () => (
+    <div className="space-y-4">
+      <div className="space-y-3">
+        <label className="block">
+          <span className="mb-1.5 block text-xs font-medium text-foreground">
+            SSH host or alias
+          </span>
+          <Input
+            value={savedBackendSshHost}
+            onChange={(event) => setSavedBackendSshHost(event.target.value)}
+            placeholder="Search hosts or type devbox"
+            disabled={isAddingSavedBackend}
+            spellCheck={false}
+          />
+        </label>
+        <div className="grid gap-3 sm:grid-cols-[minmax(0,1fr)_7rem]">
+          <label className="block">
+            <span className="mb-1.5 block text-xs font-medium text-foreground">Username</span>
+            <Input
+              value={savedBackendSshUsername}
+              onChange={(event) => setSavedBackendSshUsername(event.target.value)}
+              placeholder="root"
+              disabled={isAddingSavedBackend}
+              spellCheck={false}
+            />
+          </label>
+          <label className="block">
+            <span className="mb-1.5 block text-xs font-medium text-foreground">Port</span>
+            <Input
+              value={savedBackendSshPort}
+              onChange={(event) => setSavedBackendSshPort(event.target.value)}
+              placeholder="22"
+              inputMode="numeric"
+              disabled={isAddingSavedBackend}
+              spellCheck={false}
+            />
+          </label>
+        </div>
+        {savedBackendError || discoveredSshHostsError ? (
+          <div className="rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2 text-xs text-destructive">
+            {savedBackendError ?? discoveredSshHostsError}
+          </div>
+        ) : null}
+        <Button
+          variant="outline"
+          className="w-full"
+          disabled={isAddingSavedBackend}
+          onClick={() => void handleAddSavedBackend()}
+        >
+          <PlusIcon className="size-3.5" />
+          {isAddingSavedBackend ? "Adding…" : "Add environment"}
+        </Button>
+      </div>
+      <div className="overflow-hidden rounded-lg border border-border/60">
+        <div className="flex items-center justify-between gap-3 border-b border-border/60 bg-muted/30 px-3 py-2">
+          <div className="min-w-0">
+            <p className="text-xs font-medium text-foreground">Suggested hosts</p>
+            <p className="text-[11px] text-muted-foreground">From SSH config and known hosts</p>
+          </div>
+          <Button
+            size="xs"
+            variant="ghost"
+            disabled={isLoadingDiscoveredSshHosts}
+            onClick={() => void loadDiscoveredSshHosts()}
+          >
+            {isLoadingDiscoveredSshHosts ? (
+              <RefreshCwIcon className="size-3 animate-spin" />
+            ) : (
+              <RefreshCwIcon className="size-3" />
+            )}
+            Refresh
+          </Button>
+        </div>
+        <ScrollArea scrollFade className="max-h-56">
+          <div>
+            {unsavedDiscoveredSshHosts.map((target) => (
+              <DesktopSshHostRow
+                key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
+                target={target}
+                connectingHostAlias={connectingSshHostAlias}
+                onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
+              />
+            ))}
+            {hasLoadedDiscoveredSshHosts &&
+            !isLoadingDiscoveredSshHosts &&
+            unsavedDiscoveredSshHosts.length === 0 ? (
+              <div className={ITEM_ROW_CLASSNAME}>
+                <p className="text-xs text-muted-foreground">No new SSH hosts were discovered.</p>
+              </div>
+            ) : null}
+          </div>
+        </ScrollArea>
+      </div>
+    </div>
+  );
+  const renderNetworkAccessToggle = () => (
+    <Switch
+      checked={desktopServerExposureState?.mode === "network-accessible"}
+      disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
+      onCheckedChange={(checked) => {
+        setPendingDesktopServerExposureMode(checked ? "network-accessible" : "local-only");
+        setIsDesktopServerExposureDialogOpen(true);
+      }}
+      aria-label="Enable network access"
+    />
+  );
+  const renderEndpointRows = (presentation: AccessSectionPresentation) =>
+    isAdvertisedEndpointListExpanded
+      ? visibleDesktopNetworkAdvertisedEndpoints.map((endpoint) => {
+          const endpointKey = endpointDefaultPreferenceKey(endpoint);
+          return (
+            <AdvertisedEndpointListRow
+              key={endpoint.id}
+              endpoint={endpoint}
+              isDefault={endpointKey === defaultDesktopAdvertisedEndpointKey}
+              presentation={presentation}
+              onSetDefault={handleSetDefaultAdvertisedEndpoint}
+              onSetupTailscaleServe={handleStartTailscaleServeSetup}
+              onDisableTailscaleServe={handleStartTailscaleServeDisable}
+              isUpdatingTailscaleServe={isUpdatingTailscaleServe}
+            />
+          );
+        })
+      : null;
+  const renderTailscaleRow = () => (
+    <SettingsRow
+      title="Tailscale HTTPS"
+      description={
+        tailscaleHttpsEndpoint
+          ? tailscaleHttpsEndpoint.status === "available"
+            ? tailscaleHttpsEndpoint.httpBaseUrl
+            : "Use Tailscale Serve to expose this backend through a MagicDNS HTTPS URL."
+          : "Start Tailscale to set up HTTPS access through MagicDNS."
+      }
+      control={
+        tailscaleHttpsEndpoint ? (
+          <Switch
+            checked={tailscaleHttpsEndpoint.status === "available"}
+            disabled={isUpdatingTailscaleServe}
+            onCheckedChange={(checked) => {
+              if (checked) {
+                handleStartTailscaleServeSetup(tailscaleHttpsEndpoint);
+                return;
+              }
+              handleStartTailscaleServeDisable(tailscaleHttpsEndpoint);
+            }}
+            aria-label="Enable Tailscale HTTPS"
+          />
+        ) : null
+      }
+    />
+  );
+  const renderAuthorizedClients = (presentation: AccessSectionPresentation) => (
+    <>
+      {desktopAccessManagementError ? (
+        <div className={accessRowClassName(presentation)}>
+          <p className="text-xs text-destructive">{desktopAccessManagementError}</p>
+        </div>
+      ) : null}
+      <PairingClientsList
+        endpointUrl={desktopServerExposureState?.endpointUrl}
+        endpoints={visibleDesktopAdvertisedEndpoints}
+        defaultEndpointKey={defaultDesktopAdvertisedEndpointKey}
+        presentation={presentation}
+        isLoading={isLoadingDesktopAccessManagement}
+        pairingLinks={visibleDesktopPairingLinks}
+        clientSessions={desktopClientSessions}
+        revokingPairingLinkId={revokingDesktopPairingLinkId}
+        revokingClientSessionId={revokingDesktopClientSessionId}
+        onRevokePairingLink={handleRevokeDesktopPairingLink}
+        onRevokeClientSession={handleRevokeDesktopClientSession}
+      />
+    </>
+  );
+  const renderNetworkAccessRow = () => (
+    <SettingsRow
+      title="Network access"
+      description={
+        isLocalBackendNetworkAccessible ? (
+          <NetworkAccessDescription
+            endpoint={defaultDesktopNetworkAdvertisedEndpoint}
+            hiddenEndpointCount={Math.max(visibleDesktopNetworkAdvertisedEndpoints.length - 1, 0)}
+            expanded={isAdvertisedEndpointListExpanded}
+            onToggleExpanded={() => setIsAdvertisedEndpointListExpanded((expanded) => !expanded)}
+            fallback={
+              desktopServerExposureState?.endpointUrl
+                ? `Reachable at ${desktopServerExposureState.endpointUrl}`
+                : desktopServerExposureState?.advertisedHost
+                  ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
+                  : "Exposed on all interfaces."
+            }
+          />
+        ) : desktopServerExposureState ? (
+          "Limited to this machine."
+        ) : (
+          "Loading…"
+        )
+      }
+      status={
+        desktopServerExposureError ? (
+          <span className="block text-destructive">{desktopServerExposureError}</span>
+        ) : null
+      }
+      control={renderNetworkAccessToggle()}
+    />
+  );
+  const renderDisabledNetworkAccessRow = () => (
+    <SettingsRow
+      title="Network access"
+      description={
+        currentAuthPolicy === "remote-reachable"
+          ? "This backend is already configured for remote access. Network exposure changes must be made where the server is launched."
+          : "This backend is only reachable on this machine. Restart it with a non-loopback host to enable remote pairing."
+      }
+      control={
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <span className="inline-flex">
+                <Switch
+                  checked={isLocalBackendNetworkAccessible}
+                  disabled
+                  aria-label="Enable network access"
+                />
+              </span>
+            }
+          />
+          <TooltipPopup side="top">
+            Network exposure changes restart the backend and must be controlled where the server
+            process is launched.
+          </TooltipPopup>
+        </Tooltip>
+      }
+    />
+  );
+
   return (
     <SettingsPageContainer>
       {canManageLocalBackend ? (
         <>
           <SettingsSection title="Manage local backend">
-            {desktopBridge ? (
+            {primaryVersionMismatch ? (
               <SettingsRow
-                title="Network access"
+                title="Version drift"
                 description={
-                  desktopServerExposureState?.endpointUrl
-                    ? `Reachable at ${desktopServerExposureState.endpointUrl}`
-                    : desktopServerExposureState?.mode === "network-accessible"
-                      ? desktopServerExposureState.advertisedHost
-                        ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
-                        : "Exposed on all interfaces."
-                      : desktopServerExposureState
-                        ? "Limited to this machine."
-                        : "Loading…"
-                }
-                status={
-                  desktopServerExposureError ? (
-                    <span className="block text-destructive">{desktopServerExposureError}</span>
-                  ) : null
-                }
-                control={
-                  <AlertDialog
-                    open={pendingDesktopServerExposureMode !== null}
-                    onOpenChange={(open) => {
-                      if (isUpdatingDesktopServerExposure) return;
-                      if (!open) setPendingDesktopServerExposureMode(null);
-                    }}
-                  >
-                    <Switch
-                      checked={desktopServerExposureState?.mode === "network-accessible"}
-                      disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
-                      onCheckedChange={(checked) => {
-                        setPendingDesktopServerExposureMode(
-                          checked ? "network-accessible" : "local-only",
-                        );
-                      }}
-                      aria-label="Enable network access"
-                    />
-                    <AlertDialogPopup>
-                      <AlertDialogHeader>
-                        <AlertDialogTitle>
-                          {pendingDesktopServerExposureMode === "network-accessible"
-                            ? "Enable network access?"
-                            : "Disable network access?"}
-                        </AlertDialogTitle>
-                        <AlertDialogDescription>
-                          {pendingDesktopServerExposureMode === "network-accessible"
-                            ? "T3 Code will restart to expose this environment over the network."
-                            : "T3 Code will restart and limit this environment back to this machine."}
-                        </AlertDialogDescription>
-                      </AlertDialogHeader>
-                      <AlertDialogFooter>
-                        <AlertDialogClose
-                          disabled={isUpdatingDesktopServerExposure}
-                          render={
-                            <Button variant="outline" disabled={isUpdatingDesktopServerExposure} />
-                          }
-                        >
-                          Cancel
-                        </AlertDialogClose>
-                        <Button
-                          onClick={handleConfirmDesktopServerExposureChange}
-                          disabled={
-                            pendingDesktopServerExposureMode === null ||
-                            isUpdatingDesktopServerExposure
-                          }
-                        >
-                          {isUpdatingDesktopServerExposure ? (
-                            <>
-                              <Spinner className="size-3.5" />
-                              Restarting…
-                            </>
-                          ) : pendingDesktopServerExposureMode === "network-accessible" ? (
-                            "Restart and enable"
-                          ) : (
-                            "Restart and disable"
-                          )}
-                        </Button>
-                      </AlertDialogFooter>
-                    </AlertDialogPopup>
-                  </AlertDialog>
+                  <span className="flex items-center gap-1 text-warning">
+                    <TriangleAlertIcon className="size-3.5 shrink-0" />
+                    Client {primaryVersionMismatch.clientVersion}, server{" "}
+                    {primaryVersionMismatch.serverVersion}. Sync them if RPC calls or reconnects
+                    fail.
+                  </span>
                 }
               />
+            ) : null}
+            {desktopBridge ? (
+              <>
+                {renderNetworkAccessRow()}
+                {renderEndpointRows("endpoint-rail")}
+                {renderTailscaleRow()}
+              </>
             ) : (
-              <SettingsRow
-                title="Network access"
-                description={
-                  currentAuthPolicy === "remote-reachable"
-                    ? "This backend is already configured for remote access. Network exposure changes must be made where the server is launched."
-                    : "This backend is only reachable on this machine. Restart it with a non-loopback host to enable remote pairing."
-                }
-                control={
-                  <Tooltip>
-                    <TooltipTrigger
-                      render={
-                        <span className="inline-flex">
-                          <Switch
-                            checked={isLocalBackendNetworkAccessible}
-                            disabled
-                            aria-label="Enable network access"
-                          />
-                        </span>
-                      }
-                    />
-                    <TooltipPopup side="top">
-                      Network exposure changes restart the backend and must be controlled where the
-                      server process is launched.
-                    </TooltipPopup>
-                  </Tooltip>
-                }
-              />
+              renderDisabledNetworkAccessRow()
             )}
           </SettingsSection>
 
-          {isLocalBackendNetworkAccessible ? (
+          {isLocalBackendRemotelyReachable ? (
             <SettingsSection
               title="Authorized clients"
               headerAction={
@@ -1240,23 +2480,166 @@ export function ConnectionsSettings() {
                 />
               }
             >
-              {desktopAccessManagementError ? (
-                <div className={ITEM_ROW_CLASSNAME}>
-                  <p className="text-xs text-destructive">{desktopAccessManagementError}</p>
-                </div>
-              ) : null}
-              <PairingClientsList
-                endpointUrl={desktopServerExposureState?.endpointUrl}
-                isLoading={isLoadingDesktopAccessManagement}
-                pairingLinks={visibleDesktopPairingLinks}
-                clientSessions={desktopClientSessions}
-                revokingPairingLinkId={revokingDesktopPairingLinkId}
-                revokingClientSessionId={revokingDesktopClientSessionId}
-                onRevokePairingLink={handleRevokeDesktopPairingLink}
-                onRevokeClientSession={handleRevokeDesktopClientSession}
-              />
+              {renderAuthorizedClients("current")}
             </SettingsSection>
           ) : null}
+          <AlertDialog
+            open={isDesktopServerExposureDialogOpen}
+            onOpenChange={(open) => {
+              if (isUpdatingDesktopServerExposure) return;
+              setIsDesktopServerExposureDialogOpen(open);
+            }}
+            onOpenChangeComplete={(open) => {
+              if (!open) setPendingDesktopServerExposureMode(null);
+            }}
+          >
+            <AlertDialogPopup>
+              <AlertDialogHeader>
+                <AlertDialogTitle>
+                  {pendingDesktopServerExposureMode === "network-accessible"
+                    ? "Enable network access?"
+                    : "Disable network access?"}
+                </AlertDialogTitle>
+                <AlertDialogDescription>
+                  {pendingDesktopServerExposureMode === "network-accessible"
+                    ? "T3 Code will restart to expose this environment over the network."
+                    : "T3 Code will restart and limit this environment back to this machine."}
+                </AlertDialogDescription>
+              </AlertDialogHeader>
+              <AlertDialogFooter>
+                <AlertDialogClose
+                  disabled={isUpdatingDesktopServerExposure}
+                  render={<Button variant="outline" disabled={isUpdatingDesktopServerExposure} />}
+                >
+                  Cancel
+                </AlertDialogClose>
+                <Button
+                  variant={
+                    pendingDesktopServerExposureMode === "local-only" ? "destructive" : "default"
+                  }
+                  onClick={handleConfirmDesktopServerExposureChange}
+                  disabled={
+                    pendingDesktopServerExposureMode === null || isUpdatingDesktopServerExposure
+                  }
+                >
+                  {isUpdatingDesktopServerExposure ? (
+                    <>
+                      <Spinner className="size-3.5" />
+                      Restarting…
+                    </>
+                  ) : pendingDesktopServerExposureMode === "network-accessible" ? (
+                    "Restart and enable"
+                  ) : (
+                    "Restart and disable"
+                  )}
+                </Button>
+              </AlertDialogFooter>
+            </AlertDialogPopup>
+          </AlertDialog>
+          <AlertDialog
+            open={disableTailscaleServeDialogOpen}
+            onOpenChange={(open) => {
+              if (isUpdatingTailscaleServe) return;
+              setDisableTailscaleServeDialogOpen(open);
+            }}
+          >
+            <AlertDialogPopup>
+              <AlertDialogHeader>
+                <AlertDialogTitle>Disable Tailscale HTTPS?</AlertDialogTitle>
+                <AlertDialogDescription>
+                  T3 Code will restart the local backend without Tailscale Serve.
+                </AlertDialogDescription>
+              </AlertDialogHeader>
+              <AlertDialogFooter>
+                <AlertDialogClose
+                  disabled={isUpdatingTailscaleServe}
+                  render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
+                >
+                  Cancel
+                </AlertDialogClose>
+                <Button
+                  variant="destructive"
+                  onClick={() => void handleConfirmTailscaleServeDisable()}
+                  disabled={isUpdatingTailscaleServe}
+                >
+                  {isUpdatingTailscaleServe ? (
+                    <>
+                      <Spinner className="size-3.5" />
+                      Restarting…
+                    </>
+                  ) : (
+                    "Restart and disable"
+                  )}
+                </Button>
+              </AlertDialogFooter>
+            </AlertDialogPopup>
+          </AlertDialog>
+          <Dialog
+            open={pendingTailscaleServeEndpoint !== null}
+            onOpenChange={(open) => {
+              if (isUpdatingTailscaleServe) return;
+              if (!open) setPendingTailscaleServeEndpoint(null);
+            }}
+          >
+            <DialogPopup className="max-w-md">
+              <DialogHeader>
+                <DialogTitle>Set up Tailscale HTTPS?</DialogTitle>
+                <DialogDescription>
+                  T3 Code will restart the local backend with Tailscale Serve enabled and ask
+                  Tailscale to proxy HTTPS traffic to this backend.
+                </DialogDescription>
+              </DialogHeader>
+              <DialogPanel className="space-y-4">
+                <label className="block">
+                  <span className="text-sm font-medium text-foreground">HTTPS port</span>
+                  <Input
+                    className="mt-2"
+                    type="number"
+                    inputMode="numeric"
+                    min={1}
+                    max={65_535}
+                    step={1}
+                    value={tailscaleServePortInput}
+                    onChange={(event) => setTailscaleServePortInput(event.target.value)}
+                    disabled={isUpdatingTailscaleServe}
+                  />
+                </label>
+                {!isTailscaleServePortValid ? (
+                  <p className="mt-2 text-xs text-destructive">Enter a port from 1 to 65535.</p>
+                ) : null}
+                <div className="rounded-md border border-border/70 bg-muted/20 px-3 py-2">
+                  <p className="text-xs font-medium text-muted-foreground">HTTPS endpoint</p>
+                  <p
+                    className="mt-1 truncate text-sm text-foreground"
+                    title={pendingTailscaleServeBaseUrl ?? undefined}
+                  >
+                    {pendingTailscaleServeBaseUrl ?? "Pending MagicDNS endpoint"}
+                  </p>
+                </div>
+              </DialogPanel>
+              <DialogFooter>
+                <DialogClose
+                  disabled={isUpdatingTailscaleServe}
+                  render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
+                >
+                  Cancel
+                </DialogClose>
+                <Button
+                  onClick={() => void handleConfirmTailscaleServeSetup()}
+                  disabled={isUpdatingTailscaleServe || !isTailscaleServePortValid}
+                >
+                  {isUpdatingTailscaleServe ? (
+                    <>
+                      <Spinner className="size-3.5" />
+                      Restarting…
+                    </>
+                  ) : (
+                    "Enable"
+                  )}
+                </Button>
+              </DialogFooter>
+            </DialogPopup>
+          </Dialog>
         </>
       ) : (
         <SettingsSection title="Local backend access">
@@ -1279,128 +2662,52 @@ export function ConnectionsSettings() {
               }
             }}
           >
-            <DialogTrigger
-              render={
-                <Button size="xs" variant="outline">
-                  <PlusIcon className="size-3" />
-                  Add environment
-                </Button>
-              }
-            />
-            <DialogPopup>
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <DialogTrigger
+                    render={
+                      <Button
+                        size="xs"
+                        variant="ghost"
+                        className="h-5 gap-1 rounded-sm px-1 text-[11px] font-normal text-muted-foreground/60 hover:text-muted-foreground"
+                        aria-label="Add environment"
+                      >
+                        <PlusIcon className="size-3" />
+                        <span>Add environment</span>
+                      </Button>
+                    }
+                  />
+                }
+              />
+              <TooltipPopup side="top">Add environment</TooltipPopup>
+            </Tooltip>
+            <DialogPopup className="max-h-[80dvh] sm:max-w-3xl">
               <DialogHeader>
                 <DialogTitle>Add Environment</DialogTitle>
                 <DialogDescription>Pair another environment to this client.</DialogDescription>
-                <div className="flex gap-1 rounded-lg border border-border/60 bg-muted/50 p-1">
-                  <button
-                    type="button"
-                    className={cn(
-                      "flex-1 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
-                      savedBackendMode === "pairing-url"
-                        ? "bg-background text-foreground shadow-xs"
-                        : "text-muted-foreground hover:text-foreground",
-                    )}
-                    disabled={isAddingSavedBackend}
-                    onClick={() => setSavedBackendMode("pairing-url")}
-                  >
-                    Pairing URL
-                  </button>
-                  <button
-                    type="button"
-                    className={cn(
-                      "flex-1 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
-                      savedBackendMode === "host-code"
-                        ? "bg-background text-foreground shadow-xs"
-                        : "text-muted-foreground hover:text-foreground",
-                    )}
-                    disabled={isAddingSavedBackend}
-                    onClick={() => setSavedBackendMode("host-code")}
-                  >
-                    Host + code
-                  </button>
-                </div>
               </DialogHeader>
               <DialogPanel>
                 <div className="space-y-4">
-                  {savedBackendMode === "pairing-url" ? (
-                    <p className="text-xs text-muted-foreground">
-                      Enter the full pairing URL from the environment you want to connect to.
-                    </p>
-                  ) : (
-                    <p className="text-xs text-muted-foreground">
-                      Enter the backend host and pairing code separately.
-                    </p>
-                  )}
-                  <div className="space-y-3">
-                    <label className="block">
-                      <span className="mb-1.5 block text-xs font-medium text-foreground">
-                        Label
-                      </span>
-                      <Input
-                        value={savedBackendLabel}
-                        onChange={(event) => setSavedBackendLabel(event.target.value)}
-                        placeholder="My backend (optional)"
-                        disabled={isAddingSavedBackend}
-                        spellCheck={false}
-                      />
-                    </label>
-                    {savedBackendMode === "pairing-url" ? (
-                      <label className="block">
-                        <span className="mb-1.5 block text-xs font-medium text-foreground">
-                          Pairing URL
-                        </span>
-                        <Input
-                          value={savedBackendPairingUrl}
-                          onChange={(event) => setSavedBackendPairingUrl(event.target.value)}
-                          placeholder="https://backend.example.com/pair#token=..."
-                          disabled={isAddingSavedBackend}
-                          spellCheck={false}
-                        />
-                        <span className="mt-1 block text-[11px] text-muted-foreground">
-                          The full URL including the pairing token.
-                        </span>
-                      </label>
-                    ) : (
-                      <>
-                        <label className="block">
-                          <span className="mb-1.5 block text-xs font-medium text-foreground">
-                            Host
-                          </span>
-                          <Input
-                            value={savedBackendHost}
-                            onChange={(event) => setSavedBackendHost(event.target.value)}
-                            placeholder="https://backend.example.com"
-                            disabled={isAddingSavedBackend}
-                            spellCheck={false}
-                          />
-                        </label>
-                        <label className="block">
-                          <span className="mb-1.5 block text-xs font-medium text-foreground">
-                            Pairing code
-                          </span>
-                          <Input
-                            value={savedBackendPairingCode}
-                            onChange={(event) => setSavedBackendPairingCode(event.target.value)}
-                            placeholder="Pairing code"
-                            disabled={isAddingSavedBackend}
-                            spellCheck={false}
-                          />
-                        </label>
-                      </>
-                    )}
+                  <div className="grid gap-3 sm:grid-cols-2">
+                    {renderConnectionModeCard({
+                      mode: "remote",
+                      title: "Remote link",
+                      description: "Enter a backend host and pairing code.",
+                      icon: <ChevronsLeftRightEllipsisIcon aria-hidden className="size-4" />,
+                    })}
+                    {desktopBridge
+                      ? renderConnectionModeCard({
+                          mode: "ssh",
+                          title: "SSH",
+                          description: "Use local SSH config, agent, and tunnels for the backend.",
+                          icon: <TerminalIcon aria-hidden className="size-4" />,
+                        })
+                      : null}
                   </div>
-                  {savedBackendError ? (
-                    <p className="text-xs text-destructive">{savedBackendError}</p>
-                  ) : null}
-                  <Button
-                    variant="outline"
-                    className="w-full"
-                    disabled={isAddingSavedBackend}
-                    onClick={() => void handleAddSavedBackend()}
-                  >
-                    <PlusIcon className="size-3.5" />
-                    {isAddingSavedBackend ? "Adding…" : "Add Backend"}
-                  </Button>
+                  <AnimatedHeight>
+                    {savedBackendMode === "ssh" ? renderSshFields() : renderRemoteModeBody()}
+                  </AnimatedHeight>
                 </div>
               </DialogPanel>
             </DialogPopup>
@@ -1412,8 +2719,10 @@ export function ConnectionsSettings() {
             key={environmentId}
             environmentId={environmentId}
             reconnectingEnvironmentId={reconnectingSavedEnvironmentId}
+            disconnectingEnvironmentId={disconnectingSavedEnvironmentId}
             removingEnvironmentId={removingSavedEnvironmentId}
-            onReconnect={handleReconnectSavedBackend}
+            onConnect={handleConnectSavedBackend}
+            onDisconnect={handleDisconnectSavedBackend}
             onRemove={handleRemoveSavedBackend}
           />
         ))}
diff --git a/apps/web/src/components/settings/DiagnosticsSettings.tsx b/apps/web/src/components/settings/DiagnosticsSettings.tsx
new file mode 100644
index 00000000000..3a36e2a51e5
--- /dev/null
+++ b/apps/web/src/components/settings/DiagnosticsSettings.tsx
@@ -0,0 +1,1310 @@
+import {
+  AlertTriangleIcon,
+  ChevronDownIcon,
+  ChevronRightIcon,
+  CopyIcon,
+  FolderOpenIcon,
+  InfoIcon,
+  RefreshCwIcon,
+} from "lucide-react";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import type {
+  ServerProcessDiagnosticsEntry,
+  ServerProcessResourceHistorySummary,
+  ServerProcessSignal,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+
+import { ensureLocalApi } from "../../localApi";
+import { cn } from "../../lib/utils";
+import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
+import { formatRelativeTime } from "../../timestampFormat";
+import { useServerAvailableEditors, useServerObservability } from "../../rpc/serverState";
+import {
+  useProcessDiagnostics,
+  useProcessResourceHistory,
+} from "../../lib/processDiagnosticsState";
+import { useTraceDiagnostics } from "../../lib/traceDiagnosticsState";
+import { Button } from "../ui/button";
+import { ScrollArea } from "../ui/scroll-area";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { toastManager } from "../ui/toast";
+import { SettingsPageContainer, SettingsSection, useRelativeTimeTick } from "./settingsLayout";
+
+const NUMBER_FORMAT = new Intl.NumberFormat();
+
+function formatCount(value: number): string {
+  return NUMBER_FORMAT.format(value);
+}
+
+function formatDuration(value: number): string {
+  if (value < 1_000) return `${Math.round(value)} ms`;
+  return `${(value / 1_000).toFixed(value >= 10_000 ? 1 : 2)} s`;
+}
+
+function formatBytes(value: number): string {
+  if (value < 1024) return `${value} B`;
+  const units = ["KB", "MB", "GB"] as const;
+  let unitIndex = -1;
+  let next = value;
+  do {
+    next /= 1024;
+    unitIndex += 1;
+  } while (next >= 1024 && unitIndex < units.length - 1);
+  return `${next.toFixed(next >= 10 ? 1 : 2)} ${units[unitIndex]}`;
+}
+
+function formatRelative(value: DateTime.Utc | null): string {
+  if (!value) return "No trace records";
+  const relative = formatRelativeTime(DateTime.formatIso(value));
+  return relative.suffix ? `${relative.value} ${relative.suffix}` : relative.value;
+}
+
+function formatRelativeNoWrap(value: DateTime.Utc | null): string {
+  return formatRelative(value).replaceAll(" ", "\u00a0");
+}
+
+function shortenTraceId(traceId: string): string {
+  if (traceId.length <= 32) return traceId;
+  return `${traceId.slice(0, 18)}...${traceId.slice(-10)}`;
+}
+
+function isStaleProcessSignalMessage(message: string | undefined): boolean {
+  return message?.includes("not a live descendant") ?? false;
+}
+
+function StatBlock({
+  label,
+  value,
+  tooltip,
+  tone = "default",
+}: {
+  label: string;
+  value: string;
+  tooltip?: ReactNode;
+  tone?: "default" | "warning" | "danger";
+}) {
+  return (
+    <div className="min-w-0 border-border/60 px-4 py-3 sm:px-5">
+      <div className="flex min-w-0 items-center gap-1.5 text-[11px] font-medium uppercase tracking-[0.08em] text-muted-foreground/70">
+        <span className="min-w-0 truncate">{label}</span>
+        {tooltip ? (
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <button
+                  type="button"
+                  className="inline-flex size-3.5 shrink-0 items-center justify-center rounded-sm text-muted-foreground/60 hover:text-foreground"
+                  aria-label={`${label} details`}
+                >
+                  <InfoIcon className="size-3" />
+                </button>
+              }
+            />
+            <TooltipPopup
+              side="top"
+              className="max-w-[min(300px,calc(100vw-2rem))] whitespace-normal text-left text-[11px] leading-relaxed text-wrap"
+            >
+              {tooltip}
+            </TooltipPopup>
+          </Tooltip>
+        ) : null}
+      </div>
+      <div
+        className={cn(
+          "mt-1 truncate font-mono text-lg font-semibold tabular-nums text-foreground",
+          tone === "warning" && "text-amber-600 dark:text-amber-400",
+          tone === "danger" && "text-destructive",
+        )}
+      >
+        {value}
+      </div>
+    </div>
+  );
+}
+
+function StatsGrid({ children }: { children: ReactNode }) {
+  return (
+    <div className="relative grid grid-cols-2 sm:grid-cols-4">
+      <span
+        className="pointer-events-none absolute inset-y-0 left-1/2 w-px bg-border/60"
+        aria-hidden
+      />
+      <span
+        className="pointer-events-none absolute inset-x-0 top-1/2 h-px bg-border/60 sm:hidden"
+        aria-hidden
+      />
+      <span
+        className="pointer-events-none absolute inset-y-0 left-1/4 hidden w-px bg-border/60 sm:block"
+        aria-hidden
+      />
+      <span
+        className="pointer-events-none absolute inset-y-0 left-3/4 hidden w-px bg-border/60 sm:block"
+        aria-hidden
+      />
+      {children}
+    </div>
+  );
+}
+
+function EmptyRows({ label }: { label: string }) {
+  return <div className="px-4 py-4 text-xs text-muted-foreground sm:px-5">{label}</div>;
+}
+
+function ExpandableText({
+  text,
+  className,
+  collapsedClassName = "line-clamp-3",
+  expandLabel = "Show full error",
+}: {
+  text: string;
+  className?: string;
+  collapsedClassName?: string;
+  expandLabel?: string;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const canExpand = text.length > 180 || text.includes("\n");
+
+  return (
+    <div className={cn("min-w-0", className)}>
+      <div
+        className={cn(
+          "whitespace-pre-wrap break-words",
+          !expanded && canExpand ? collapsedClassName : null,
+        )}
+      >
+        {text}
+      </div>
+      {canExpand ? (
+        <button
+          type="button"
+          className="mt-1 text-[11px] font-medium text-foreground/70 underline-offset-2 hover:text-foreground hover:underline"
+          onClick={() => setExpanded((value) => !value)}
+        >
+          {expanded ? "Show less" : expandLabel}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+function DiagnosticsTable({
+  headers,
+  children,
+  minTableWidth = "min-w-[640px]",
+  columnWidths,
+}: {
+  headers: ReadonlyArray<string>;
+  children: ReactNode;
+  minTableWidth?: string;
+  columnWidths?: ReadonlyArray<string>;
+}) {
+  return (
+    <ScrollArea
+      chainVerticalScroll
+      scrollFade
+      hideScrollbars
+      className="w-full max-w-full rounded-none"
+    >
+      <table
+        className={cn("w-full text-left text-xs", minTableWidth, columnWidths && "table-fixed")}
+      >
+        {columnWidths ? (
+          <colgroup>
+            {headers.map((header, index) => (
+              <col key={header} className={columnWidths[index]} />
+            ))}
+          </colgroup>
+        ) : null}
+        <thead className="border-b border-border/60 text-[11px] uppercase tracking-[0.08em] text-muted-foreground/70">
+          <tr>
+            {headers.map((header, index) => (
+              <th
+                key={header}
+                className={cn(
+                  "whitespace-nowrap px-4 py-2.5 font-semibold first:sm:pl-5 last:sm:pr-5",
+                  !columnWidths && index === headers.length - 1 && "w-px",
+                )}
+              >
+                {header.replaceAll(" ", "\u00a0")}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border/60">{children}</tbody>
+      </table>
+    </ScrollArea>
+  );
+}
+
+function TraceIdCell({ traceId }: { traceId: string }) {
+  const [copied, setCopied] = useState(false);
+  const copyTraceId = useCallback(() => {
+    void navigator.clipboard
+      ?.writeText(traceId)
+      .then(() => {
+        setCopied(true);
+        window.setTimeout(() => setCopied(false), 1_200);
+      })
+      .catch(() => undefined);
+  }, [traceId]);
+
+  return (
+    <div className="flex w-full min-w-0 max-w-full items-center gap-2">
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <span className="min-w-0 flex-1 truncate font-mono text-[11px]">
+              {shortenTraceId(traceId)}
+            </span>
+          }
+        />
+        <TooltipPopup
+          side="top"
+          className="max-w-[min(520px,calc(100vw-2rem))] break-all font-mono text-[11px]"
+        >
+          {traceId}
+        </TooltipPopup>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <button
+              type="button"
+              className="inline-flex size-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+              aria-label={copied ? "Copied trace ID" : "Copy trace ID"}
+              onClick={copyTraceId}
+            >
+              <CopyIcon className="size-3" />
+            </button>
+          }
+        />
+        <TooltipPopup side="top">{copied ? "Copied" : "Copy full trace ID"}</TooltipPopup>
+      </Tooltip>
+    </div>
+  );
+}
+
+function formatProcessName(command: string): string {
+  const firstToken = command.trim().split(/\s+/)[0];
+  if (!firstToken) return command;
+  const normalized = firstToken.replace(/^['"]|['"]$/g, "");
+  const segments = normalized.split(/[\\/]/).filter(Boolean);
+  return segments.at(-1) ?? normalized;
+}
+
+function formatProcessType(process: ServerProcessDiagnosticsEntry): string {
+  if (process.depth > 0) return "Subprocess";
+  if (/\b(codex|claude|opencode|cursor)\b/i.test(process.command)) return "Agent";
+  return "Process";
+}
+
+function ProcessNameCell({
+  process,
+  isExpanded,
+  onToggle,
+}: {
+  process: ServerProcessDiagnosticsEntry;
+  isExpanded: boolean;
+  onToggle: (pid: number) => void;
+}) {
+  const name = formatProcessName(process.command);
+  const hasChildren = process.childPids.length > 0;
+  const ChevronIcon = isExpanded ? ChevronDownIcon : ChevronRightIcon;
+
+  return (
+    <div
+      className="grid min-w-0 grid-cols-[1.25rem_0.375rem_minmax(0,1fr)] items-center gap-2"
+      style={{ paddingLeft: `${Math.min(process.depth, 6) * 10}px` }}
+    >
+      {hasChildren ? (
+        <button
+          type="button"
+          className="inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+          aria-label={isExpanded ? `Collapse ${name}` : `Expand ${name}`}
+          onClick={() => onToggle(process.pid)}
+        >
+          <ChevronIcon className="size-3.5" />
+        </button>
+      ) : (
+        <span className="size-5 shrink-0" aria-hidden="true" />
+      )}
+      <span className="size-1.5 shrink-0 rounded-full bg-emerald-500/80" />
+      <Tooltip>
+        <TooltipTrigger
+          render={<span className="min-w-0 truncate font-medium text-foreground">{name}</span>}
+        />
+        <TooltipPopup
+          side="top"
+          className="max-w-[min(440px,calc(100vw-2rem))] whitespace-normal break-words text-left font-mono text-[11px] leading-relaxed text-wrap"
+        >
+          {process.command}
+        </TooltipPopup>
+      </Tooltip>
+    </div>
+  );
+}
+
+function ProcessSignalActions({
+  process,
+  isSignaling,
+  onSignal,
+}: {
+  process: ServerProcessDiagnosticsEntry;
+  isSignaling: boolean;
+  onSignal: (pid: number, signal: ServerProcessSignal) => void;
+}) {
+  return (
+    <div className="flex items-center justify-end gap-1.5">
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <button
+              type="button"
+              disabled={isSignaling}
+              className="text-[11px] font-medium text-muted-foreground underline-offset-2 hover:text-foreground hover:underline disabled:pointer-events-none disabled:opacity-50"
+              onClick={() => onSignal(process.pid, "SIGINT")}
+            >
+              INT
+            </button>
+          }
+        />
+        <TooltipPopup side="top">Send SIGINT</TooltipPopup>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <button
+              type="button"
+              disabled={isSignaling}
+              className="text-[11px] font-medium text-destructive underline-offset-2 hover:underline disabled:pointer-events-none disabled:opacity-50"
+              onClick={() => onSignal(process.pid, "SIGKILL")}
+            >
+              KILL
+            </button>
+          }
+        />
+        <TooltipPopup side="top">Send SIGKILL</TooltipPopup>
+      </Tooltip>
+    </div>
+  );
+}
+
+function ProcessDiagnosticsTable({
+  processes,
+  signalingPid,
+  onSignal,
+  emptyLabel,
+}: {
+  processes: ReadonlyArray<ServerProcessDiagnosticsEntry>;
+  signalingPid: number | null;
+  onSignal: (pid: number, signal: ServerProcessSignal) => void;
+  emptyLabel?: string;
+}) {
+  const [collapsedPids, setCollapsedPids] = useState<ReadonlySet<number>>(() => new Set());
+  const visibleProcesses = useMemo(() => {
+    const visible: ServerProcessDiagnosticsEntry[] = [];
+    let hiddenChildDepth: number | null = null;
+
+    for (const process of processes) {
+      if (hiddenChildDepth !== null) {
+        if (process.depth > hiddenChildDepth) continue;
+        hiddenChildDepth = null;
+      }
+
+      visible.push(process);
+      if (collapsedPids.has(process.pid)) {
+        hiddenChildDepth = process.depth;
+      }
+    }
+
+    return visible;
+  }, [collapsedPids, processes]);
+
+  const toggleProcess = useCallback((pid: number) => {
+    setCollapsedPids((previous) => {
+      const next = new Set(previous);
+      if (next.has(pid)) {
+        next.delete(pid);
+      } else {
+        next.add(pid);
+      }
+      return next;
+    });
+  }, []);
+
+  return (
+    <ScrollArea
+      chainVerticalScroll
+      scrollFade
+      hideScrollbars
+      className="max-h-[min(64vh,44rem)] w-full max-w-full rounded-none border-t border-border/60"
+    >
+      <table className="w-full min-w-[1040px] table-fixed text-left text-xs">
+        <colgroup>
+          <col className="w-[24%]" />
+          <col className="w-[8%]" />
+          <col className="w-[10%]" />
+          <col className="w-[33%]" />
+          <col className="w-[8%]" />
+          <col className="w-[11%]" />
+          <col className="w-[6%]" />
+        </colgroup>
+        <thead className="sticky top-0 z-10 border-b border-border/60 bg-card text-[11px] uppercase tracking-[0.08em] text-muted-foreground/70">
+          <tr>
+            <th className="px-4 py-2 font-semibold sm:pl-5">Name</th>
+            <th className="px-3 py-2 text-right font-semibold">CPU</th>
+            <th className="px-3 py-2 text-right font-semibold">Memory</th>
+            <th className="px-3 py-2 font-semibold">Command</th>
+            <th className="px-3 py-2 text-right font-semibold">PID</th>
+            <th className="px-3 py-2 font-semibold">Type</th>
+            <th className="p-2 text-right font-semibold sm:pr-4">Kill</th>
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border/50">
+          {visibleProcesses.length === 0 ? (
+            <tr>
+              <td colSpan={7} className="px-4 py-4 text-xs text-muted-foreground sm:px-5">
+                {emptyLabel ?? "No live descendant processes found."}
+              </td>
+            </tr>
+          ) : null}
+          {visibleProcesses.map((process) => (
+            <tr key={process.pid} className="hover:bg-muted/20">
+              <td className="px-4 py-2 align-middle sm:pl-5">
+                <ProcessNameCell
+                  process={process}
+                  isExpanded={!collapsedPids.has(process.pid)}
+                  onToggle={toggleProcess}
+                />
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums">
+                {process.cpuPercent.toFixed(1)}%
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums">
+                {formatBytes(process.rssBytes)}
+              </td>
+              <td className="px-3 py-2 align-middle text-muted-foreground">
+                <Tooltip>
+                  <TooltipTrigger
+                    render={<span className="block truncate">{process.command}</span>}
+                  />
+                  <TooltipPopup
+                    side="top"
+                    className="max-w-[min(440px,calc(100vw-2rem))] whitespace-normal break-words text-left font-mono text-[11px] leading-relaxed text-wrap"
+                  >
+                    {process.command}
+                  </TooltipPopup>
+                </Tooltip>
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums text-muted-foreground">
+                {process.pid}
+              </td>
+              <td className="truncate px-3 py-2 align-middle text-muted-foreground">
+                {formatProcessType(process)}
+              </td>
+              <td className="p-2 align-middle sm:pr-4">
+                <ProcessSignalActions
+                  process={process}
+                  isSignaling={signalingPid === process.pid}
+                  onSignal={onSignal}
+                />
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </ScrollArea>
+  );
+}
+
+const RESOURCE_HISTORY_WINDOWS = [
+  { label: "5m", windowMs: 5 * 60_000, bucketMs: 30_000 },
+  { label: "15m", windowMs: 15 * 60_000, bucketMs: 60_000 },
+  { label: "30m", windowMs: 30 * 60_000, bucketMs: 2 * 60_000 },
+  { label: "1h", windowMs: 60 * 60_000, bucketMs: 5 * 60_000 },
+] as const;
+
+function formatCpuTime(seconds: number): string {
+  if (seconds < 60) return `${seconds.toFixed(seconds >= 10 ? 1 : 2)}s`;
+  const minutes = seconds / 60;
+  if (minutes < 60) return `${minutes.toFixed(minutes >= 10 ? 1 : 2)}m`;
+  return `${(minutes / 60).toFixed(2)}h`;
+}
+
+function formatShortProcessName(command: string): string {
+  const name = formatProcessName(command);
+  return name.length > 42 ? `${name.slice(0, 39)}...` : name;
+}
+
+function ResourceHistoryProcessNameCell({
+  process,
+  visualDepth,
+}: {
+  process: ServerProcessResourceHistorySummary;
+  visualDepth: number;
+}) {
+  const name = formatShortProcessName(process.command);
+
+  return (
+    <div
+      className="grid min-w-0 grid-cols-[1.25rem_0.375rem_minmax(0,1fr)] items-center gap-2"
+      style={{ paddingLeft: `${Math.min(visualDepth, 6) * 10}px` }}
+      aria-label={`${process.isServerRoot ? "Root" : "Child"} process ${name}`}
+    >
+      <span className="size-5 shrink-0" aria-hidden="true" />
+      <span
+        className={cn(
+          "size-1.5 shrink-0 rounded-full",
+          process.isServerRoot ? "bg-amber-500/90" : "bg-emerald-500/80",
+        )}
+      />
+      <Tooltip>
+        <TooltipTrigger
+          render={<span className="min-w-0 truncate font-medium text-foreground">{name}</span>}
+        />
+        <TooltipPopup
+          side="top"
+          className="max-w-[min(440px,calc(100vw-2rem))] whitespace-normal break-words text-left font-mono text-[11px] leading-relaxed text-wrap"
+        >
+          {process.command}
+        </TooltipPopup>
+      </Tooltip>
+    </div>
+  );
+}
+
+function ProcessResourceHistoryChart({
+  buckets,
+}: {
+  buckets: ReadonlyArray<{
+    readonly startedAt: DateTime.Utc;
+    readonly avgCpuPercent: number;
+    readonly maxCpuPercent: number;
+  }>;
+}) {
+  const maxCpuPercent = Math.max(1, ...buckets.map((bucket) => bucket.maxCpuPercent));
+
+  return (
+    <div className="border-t border-border/60 px-4 py-3 sm:px-5">
+      <div className="flex h-28 items-end gap-1 overflow-hidden rounded-sm bg-muted/10 p-2">
+        {buckets.map((bucket) => {
+          const peakHeight = Math.max(2, (bucket.maxCpuPercent / maxCpuPercent) * 100);
+          const averageHeight = Math.max(2, (bucket.avgCpuPercent / maxCpuPercent) * 100);
+          return (
+            <Tooltip key={DateTime.formatIso(bucket.startedAt)}>
+              <TooltipTrigger
+                render={
+                  <div className="flex h-full min-w-1 flex-1 items-end">
+                    <div
+                      className="relative h-full w-full"
+                      aria-label={`Average CPU ${bucket.avgCpuPercent.toFixed(1)}%, peak CPU ${bucket.maxCpuPercent.toFixed(1)}%`}
+                    >
+                      <div
+                        className="absolute inset-x-0 bottom-0 rounded-t-sm bg-foreground/15 transition-colors"
+                        style={{ height: `${peakHeight}%` }}
+                      />
+                      <div
+                        className="absolute inset-x-0 bottom-0 rounded-t-sm bg-foreground/60 transition-colors"
+                        style={{ height: `${averageHeight}%` }}
+                      />
+                    </div>
+                  </div>
+                }
+              />
+              <TooltipPopup side="top">
+                Avg {bucket.avgCpuPercent.toFixed(1)}%, peak {bucket.maxCpuPercent.toFixed(1)}%
+              </TooltipPopup>
+            </Tooltip>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function ResourceHistoryWindowSelector({
+  selectedWindowMs,
+  onSelect,
+}: {
+  selectedWindowMs: number;
+  onSelect: (windowMs: number) => void;
+}) {
+  return (
+    <div className="flex items-center rounded-md border border-border/60 p-0.5">
+      {RESOURCE_HISTORY_WINDOWS.map((option) => (
+        <button
+          key={option.windowMs}
+          type="button"
+          className={cn(
+            "h-6 rounded-sm px-2 text-[11px] font-medium text-muted-foreground hover:text-foreground",
+            selectedWindowMs === option.windowMs && "bg-muted text-foreground",
+          )}
+          onClick={() => onSelect(option.windowMs)}
+        >
+          {option.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+function ProcessResourceHistoryTable({
+  processes,
+  emptyLabel,
+}: {
+  processes: ReadonlyArray<ServerProcessResourceHistorySummary>;
+  emptyLabel: string;
+}) {
+  const shallowestChildDepth = processes.reduce<number | null>((minDepth, process) => {
+    if (process.isServerRoot) return minDepth;
+    return minDepth === null ? process.depth : Math.min(minDepth, process.depth);
+  }, null);
+
+  return (
+    <ScrollArea
+      chainVerticalScroll
+      scrollFade
+      hideScrollbars
+      className="max-h-[min(64vh,44rem)] w-full max-w-full border-t border-border/60"
+    >
+      <table className="w-full min-w-[980px] table-fixed text-left text-xs">
+        <colgroup>
+          <col className="w-[24%]" />
+          <col className="w-[10%]" />
+          <col className="w-[10%]" />
+          <col className="w-[10%]" />
+          <col className="w-[10%]" />
+          <col className="w-[10%]" />
+          <col className="w-[16%]" />
+          <col className="w-[10%]" />
+        </colgroup>
+        <thead className="sticky top-0 z-10 border-b border-border/60 bg-card text-[11px] uppercase tracking-[0.08em] text-muted-foreground/70">
+          <tr>
+            <th className="px-4 py-2 font-semibold sm:pl-5">Process</th>
+            <th className="px-3 py-2 text-right font-semibold">CPU Time</th>
+            <th className="px-3 py-2 text-right font-semibold">Current</th>
+            <th className="px-3 py-2 text-right font-semibold">Average</th>
+            <th className="px-3 py-2 text-right font-semibold">Peak</th>
+            <th className="px-3 py-2 text-right font-semibold">Max Mem</th>
+            <th className="px-3 py-2 font-semibold">Command</th>
+            <th className="px-3 py-2 text-right font-semibold sm:pr-5">PID</th>
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border/50">
+          {processes.length === 0 ? (
+            <tr>
+              <td colSpan={8} className="px-4 py-4 text-xs text-muted-foreground sm:px-5">
+                {emptyLabel}
+              </td>
+            </tr>
+          ) : null}
+          {processes.map((process) => (
+            <tr key={process.processKey} className="hover:bg-muted/20">
+              <td className="px-4 py-2 align-middle sm:pl-5">
+                <ResourceHistoryProcessNameCell
+                  process={process}
+                  visualDepth={
+                    process.isServerRoot || shallowestChildDepth === null
+                      ? 0
+                      : Math.max(1, process.depth - shallowestChildDepth + 1)
+                  }
+                />
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums">
+                {formatCpuTime(process.cpuSecondsApprox)}
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums">
+                {process.currentCpuPercent.toFixed(1)}%
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums">
+                {process.avgCpuPercent.toFixed(1)}%
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums">
+                {process.maxCpuPercent.toFixed(1)}%
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums">
+                {formatBytes(process.maxRssBytes)}
+              </td>
+              <td className="px-3 py-2 align-middle text-muted-foreground">
+                <Tooltip>
+                  <TooltipTrigger
+                    render={<span className="block truncate">{process.command}</span>}
+                  />
+                  <TooltipPopup
+                    side="top"
+                    className="max-w-[min(440px,calc(100vw-2rem))] whitespace-normal break-words text-left font-mono text-[11px] leading-relaxed text-wrap"
+                  >
+                    {process.command}
+                  </TooltipPopup>
+                </Tooltip>
+              </td>
+              <td className="px-3 py-2 text-right align-middle font-mono tabular-nums text-muted-foreground sm:pr-5">
+                {process.pid}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </ScrollArea>
+  );
+}
+
+function DiagnosticsLastChecked({ checkedAt }: { checkedAt: DateTime.Utc | null }) {
+  useRelativeTimeTick();
+  const relative = checkedAt ? formatRelativeTime(DateTime.formatIso(checkedAt)) : null;
+
+  if (!relative) {
+    return <span className="text-[11px] text-muted-foreground/50">Checking</span>;
+  }
+
+  return (
+    <span className="text-[11px] text-muted-foreground/60">
+      {relative.suffix ? (
+        <>
+          Checked <span className="font-mono tabular-nums">{relative.value}</span> {relative.suffix}
+        </>
+      ) : (
+        <>Checked {relative.value}</>
+      )}
+    </span>
+  );
+}
+
+function DiagnosticsRefreshButton({
+  isPending,
+  label,
+  onClick,
+}: {
+  isPending: boolean;
+  label: string;
+  onClick: () => void;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <Button
+            size="icon-xs"
+            variant="ghost"
+            className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+            disabled={isPending}
+            onClick={onClick}
+            aria-label={label}
+          >
+            <RefreshCwIcon className={cn("size-3", isPending && "animate-spin")} />
+          </Button>
+        }
+      />
+      <TooltipPopup side="top">{label}</TooltipPopup>
+    </Tooltip>
+  );
+}
+
+export function DiagnosticsSettingsPanel() {
+  const observability = useServerObservability();
+  const availableEditors = useServerAvailableEditors();
+  const [resourceWindowMs, setResourceWindowMs] = useState(15 * 60_000);
+  const selectedResourceWindow =
+    RESOURCE_HISTORY_WINDOWS.find((option) => option.windowMs === resourceWindowMs) ??
+    RESOURCE_HISTORY_WINDOWS[1];
+  const { data, error, isPending, refresh } = useTraceDiagnostics();
+  const {
+    data: processData,
+    error: processError,
+    isPending: isProcessPending,
+    refresh: refreshProcesses,
+  } = useProcessDiagnostics();
+  const {
+    data: resourceData,
+    error: resourceError,
+    isPending: isResourcePending,
+    refresh: refreshResources,
+  } = useProcessResourceHistory({
+    windowMs: selectedResourceWindow.windowMs,
+    bucketMs: selectedResourceWindow.bucketMs,
+  });
+  const [isOpeningLogsDirectory, setIsOpeningLogsDirectory] = useState(false);
+  const [openLogsDirectoryError, setOpenLogsDirectoryError] = useState<string | null>(null);
+  const [signalingPid, setSignalingPid] = useState<number | null>(null);
+
+  const openLogsDirectory = useCallback(() => {
+    const logsDirectoryPath = observability?.logsDirectoryPath ?? null;
+    if (!logsDirectoryPath) return;
+
+    const editor = resolveAndPersistPreferredEditor(availableEditors ?? []);
+    if (!editor) {
+      setOpenLogsDirectoryError("No available editors found.");
+      return;
+    }
+
+    setIsOpeningLogsDirectory(true);
+    setOpenLogsDirectoryError(null);
+    void ensureLocalApi()
+      .shell.openInEditor(logsDirectoryPath, editor)
+      .catch((error: unknown) => {
+        setOpenLogsDirectoryError(
+          error instanceof Error ? error.message : "Unable to open logs folder.",
+        );
+      })
+      .finally(() => {
+        setIsOpeningLogsDirectory(false);
+      });
+  }, [availableEditors, observability?.logsDirectoryPath]);
+
+  const isInitialLoading = isPending && data === null;
+  const isProcessInitialLoading = isProcessPending && processData === null;
+  const signalProcess = useCallback(
+    (pid: number, signal: ServerProcessSignal) => {
+      if (
+        signal === "SIGKILL" &&
+        !window.confirm(`Send SIGKILL to process ${pid}? This cannot be handled by the process.`)
+      ) {
+        return;
+      }
+
+      setSignalingPid(pid);
+      void ensureLocalApi()
+        .server.signalProcess({ pid, signal })
+        .then((result) => {
+          if (!result.signaled) {
+            const message = Option.getOrUndefined(result.message);
+            refreshProcesses();
+            if (isStaleProcessSignalMessage(message)) {
+              toastManager.add({
+                type: "info",
+                title: "Process already exited",
+                description:
+                  "The process is not a child of the T3 Server. It might already have exited.",
+              });
+              return;
+            }
+
+            toastManager.add({
+              type: "error",
+              title: `Could not send ${signal}`,
+              description: message ?? `Failed to send ${signal}.`,
+            });
+            return;
+          }
+          refreshProcesses();
+        })
+        .catch((error: unknown) => {
+          toastManager.add({
+            type: "error",
+            title: `Could not send ${signal}`,
+            description: error instanceof Error ? error.message : `Failed to send ${signal}.`,
+          });
+        })
+        .finally(() => {
+          setSignalingPid(null);
+        });
+    },
+    [refreshProcesses],
+  );
+
+  const processDiagnosticsError = processData ? Option.getOrNull(processData.error) : null;
+  const processResourceError = resourceData ? Option.getOrNull(resourceData.error) : null;
+  const traceDiagnosticsError = data ? Option.getOrNull(data.error) : null;
+  const traceDiagnosticsPartialFailure = data
+    ? Option.getOrElse(data.partialFailure, () => false)
+    : false;
+
+  return (
+    <SettingsPageContainer>
+      <SettingsSection
+        title="Live Processes"
+        headerAction={
+          <div className="flex items-center gap-1.5">
+            <DiagnosticsLastChecked checkedAt={processData?.readAt ?? null} />
+            <DiagnosticsRefreshButton
+              isPending={isProcessPending}
+              label="Refresh process diagnostics"
+              onClick={refreshProcesses}
+            />
+          </div>
+        }
+      >
+        <StatsGrid>
+          <StatBlock
+            label="Child Processes"
+            value={processData ? formatCount(processData.processCount) : "..."}
+          />
+          <StatBlock
+            label="CPU"
+            value={processData ? `${processData.totalCpuPercent.toFixed(1)}%` : "..."}
+            tooltip="Total CPU across live child processes of the current server process. The desktop shell and other parent processes are not included."
+          />
+          <StatBlock
+            label="Memory"
+            value={processData ? formatBytes(processData.totalRssBytes) : "..."}
+            tooltip="Total resident memory across live child processes of the current server process. The desktop shell and other parent processes are not included."
+          />
+          <StatBlock
+            label="Server PID"
+            value={processData ? String(processData.serverPid) : "..."}
+          />
+        </StatsGrid>
+        {processDiagnosticsError || processError ? (
+          <div className="space-y-2 border-t border-border/60 px-4 py-3 text-xs text-muted-foreground sm:px-5">
+            {processDiagnosticsError ? (
+              <div className="flex items-start gap-2 text-destructive">
+                <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+                <span>{processDiagnosticsError.message}</span>
+              </div>
+            ) : null}
+            {processError ? (
+              <div className="flex items-start gap-2 text-destructive">
+                <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+                <span>{processError}</span>
+              </div>
+            ) : null}
+          </div>
+        ) : null}
+        <ProcessDiagnosticsTable
+          processes={processData?.processes ?? []}
+          signalingPid={signalingPid}
+          onSignal={signalProcess}
+          emptyLabel={
+            isProcessInitialLoading
+              ? "Loading live processes..."
+              : "No live descendant processes found."
+          }
+        />
+      </SettingsSection>
+
+      <SettingsSection
+        title="Resource History"
+        headerAction={
+          <div className="flex items-center gap-1.5">
+            <ResourceHistoryWindowSelector
+              selectedWindowMs={resourceWindowMs}
+              onSelect={setResourceWindowMs}
+            />
+            <DiagnosticsLastChecked checkedAt={resourceData?.readAt ?? null} />
+            <DiagnosticsRefreshButton
+              isPending={isResourcePending}
+              label="Refresh resource history"
+              onClick={refreshResources}
+            />
+          </div>
+        }
+      >
+        <StatsGrid>
+          <StatBlock
+            label="CPU Time"
+            value={resourceData ? formatCpuTime(resourceData.totalCpuSecondsApprox) : "..."}
+            tooltip="Approximate active CPU time for the T3 server root process and its descendants during the selected window. It grows only while sampled processes use CPU and older samples leave as the window moves."
+          />
+          <StatBlock
+            label="Samples"
+            value={resourceData ? formatCount(resourceData.retainedSampleCount) : "..."}
+            tooltip="In-memory process samples retained by the server. This resets when the server restarts."
+          />
+          <StatBlock
+            label="Interval"
+            value={resourceData ? formatDuration(resourceData.sampleIntervalMs) : "..."}
+          />
+          <StatBlock
+            label="Processes"
+            value={resourceData ? formatCount(resourceData.topProcesses.length) : "..."}
+          />
+        </StatsGrid>
+        {processResourceError || resourceError ? (
+          <div className="space-y-2 border-t border-border/60 px-4 py-3 text-xs text-muted-foreground sm:px-5">
+            {processResourceError ? (
+              <div className="flex items-start gap-2 text-destructive">
+                <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+                <span>{processResourceError.message}</span>
+              </div>
+            ) : null}
+            {resourceError ? (
+              <div className="flex items-start gap-2 text-destructive">
+                <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+                <span>{resourceError}</span>
+              </div>
+            ) : null}
+          </div>
+        ) : null}
+        <ProcessResourceHistoryChart buckets={resourceData?.buckets ?? []} />
+        <ProcessResourceHistoryTable
+          processes={resourceData?.topProcesses ?? []}
+          emptyLabel={
+            isResourcePending && resourceData === null
+              ? "Collecting process resource samples..."
+              : "No process resource samples found for this window."
+          }
+        />
+      </SettingsSection>
+
+      <SettingsSection
+        title="Trace Diagnostics"
+        headerAction={
+          <div className="flex items-center gap-1.5">
+            <DiagnosticsLastChecked checkedAt={data?.readAt ?? null} />
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <Button
+                    size="icon-xs"
+                    variant="ghost"
+                    className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                    disabled={!observability?.logsDirectoryPath || isOpeningLogsDirectory}
+                    onClick={openLogsDirectory}
+                    aria-label="Open logs folder"
+                  >
+                    <FolderOpenIcon className="size-3" />
+                  </Button>
+                }
+              />
+              <TooltipPopup side="top">Open logs folder</TooltipPopup>
+            </Tooltip>
+            <DiagnosticsRefreshButton
+              isPending={isPending}
+              label="Refresh trace diagnostics"
+              onClick={refresh}
+            />
+          </div>
+        }
+      >
+        <StatsGrid>
+          <StatBlock label="Spans" value={data ? formatCount(data.recordCount) : "..."} />
+          <StatBlock
+            label="Failures"
+            value={data ? formatCount(data.failureCount) : "..."}
+            tone={data && data.failureCount > 0 ? "danger" : "default"}
+          />
+          <StatBlock
+            label="Slow Spans"
+            value={data ? formatCount(data.slowSpanCount) : "..."}
+            tooltip={
+              data
+                ? `Spans with a duration of ${formatDuration(data.slowSpanThresholdMs)} or longer.`
+                : "Spans at or above the configured slow-span threshold."
+            }
+            tone={data && data.slowSpanCount > 0 ? "warning" : "default"}
+          />
+          <StatBlock
+            label="Parse Errors"
+            value={data ? formatCount(data.parseErrorCount) : "..."}
+            tone={data && data.parseErrorCount > 0 ? "warning" : "default"}
+          />
+        </StatsGrid>
+        {openLogsDirectoryError || traceDiagnosticsError || error ? (
+          <div className="space-y-2 border-t border-border/60 px-4 py-3 text-xs text-muted-foreground sm:px-5">
+            {openLogsDirectoryError ? (
+              <div className="flex items-start gap-2 text-destructive">
+                <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+                <span>{openLogsDirectoryError}</span>
+              </div>
+            ) : null}
+            {traceDiagnosticsError ? (
+              <div
+                className={cn(
+                  "flex items-start gap-2",
+                  traceDiagnosticsPartialFailure
+                    ? "text-amber-600 dark:text-amber-400"
+                    : "text-destructive",
+                )}
+              >
+                <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+                <span>
+                  {traceDiagnosticsPartialFailure
+                    ? `Some trace files could not be read, so diagnostics may be incomplete. ${traceDiagnosticsError.message}`
+                    : traceDiagnosticsError.message}
+                </span>
+              </div>
+            ) : null}
+            {error ? (
+              <div className="flex items-start gap-2 text-destructive">
+                <AlertTriangleIcon className="mt-0.5 size-3.5 shrink-0" />
+                <span>{error}</span>
+              </div>
+            ) : null}
+          </div>
+        ) : null}
+      </SettingsSection>
+
+      <SettingsSection title="Latest Failures">
+        {data && data.latestFailures.length > 0 ? (
+          <DiagnosticsTable headers={["Span", "Cause", "Duration", "Ended"]}>
+            {data.latestFailures.map((failure) => (
+              <tr key={`${failure.traceId}:${failure.spanId}`}>
+                <td className="px-4 py-3 align-top text-xs font-medium text-foreground first:sm:pl-5">
+                  {failure.name}
+                </td>
+                <td className="max-w-[360px] px-4 py-3 align-top text-muted-foreground">
+                  <ExpandableText text={failure.cause} />
+                </td>
+                <td className="px-4 py-3 align-top font-mono tabular-nums">
+                  {formatDuration(failure.durationMs)}
+                </td>
+                <td className="whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums text-muted-foreground last:sm:pr-5">
+                  {formatRelativeNoWrap(failure.endedAt)}
+                </td>
+              </tr>
+            ))}
+          </DiagnosticsTable>
+        ) : (
+          <EmptyRows label={isInitialLoading ? "Loading failures..." : "No failed spans found."} />
+        )}
+      </SettingsSection>
+
+      <SettingsSection title="Most Common Failures">
+        {data && data.commonFailures.length > 0 ? (
+          <DiagnosticsTable
+            headers={["Span", "Count", "Cause", "Last Seen"]}
+            minTableWidth="min-w-[760px]"
+          >
+            {data.commonFailures.map((failure) => (
+              <tr key={`${failure.name}:${failure.cause}`}>
+                <td className="px-4 py-3 align-top text-xs font-medium text-foreground first:sm:pl-5">
+                  {failure.name}
+                </td>
+                <td className="px-4 py-3 align-top font-mono tabular-nums">
+                  {formatCount(failure.count)}
+                </td>
+                <td className="max-w-[360px] px-4 py-3 align-top text-muted-foreground">
+                  <ExpandableText text={failure.cause} />
+                </td>
+                <td className="w-px whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums text-muted-foreground last:sm:pr-5">
+                  {formatRelativeNoWrap(failure.lastSeenAt)}
+                </td>
+              </tr>
+            ))}
+          </DiagnosticsTable>
+        ) : (
+          <EmptyRows
+            label={isInitialLoading ? "Loading failure groups..." : "No repeated failures found."}
+          />
+        )}
+      </SettingsSection>
+
+      <SettingsSection title="Slowest Spans">
+        {data && data.slowestSpans.length > 0 ? (
+          <DiagnosticsTable
+            headers={["Span", "Duration", "Ended", "Trace"]}
+            minTableWidth="min-w-[900px]"
+            columnWidths={["w-[44%]", "w-[14%]", "w-[12%]", "w-[30%]"]}
+          >
+            {data.slowestSpans.map((span) => (
+              <tr key={`${span.traceId}:${span.spanId}`}>
+                <td className="px-4 py-3 align-top text-xs font-medium text-foreground first:sm:pl-5">
+                  {span.name}
+                </td>
+                <td className="px-4 py-3 align-top font-mono tabular-nums">
+                  {formatDuration(span.durationMs)}
+                </td>
+                <td className="w-px whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums text-muted-foreground">
+                  {formatRelativeNoWrap(span.endedAt)}
+                </td>
+                <td className="min-w-0 whitespace-nowrap px-4 py-3 align-top text-muted-foreground last:sm:pr-5">
+                  <TraceIdCell traceId={span.traceId} />
+                </td>
+              </tr>
+            ))}
+          </DiagnosticsTable>
+        ) : (
+          <EmptyRows label={isInitialLoading ? "Loading slow spans..." : "No spans found."} />
+        )}
+      </SettingsSection>
+
+      <SettingsSection title="Span Logs">
+        {data && data.latestWarningAndErrorLogs.length > 0 ? (
+          <ScrollArea
+            chainVerticalScroll
+            scrollFade
+            hideScrollbars
+            className="w-full max-w-full rounded-none"
+          >
+            <table className="w-full min-w-[920px] table-fixed text-left text-xs">
+              <colgroup>
+                <col className="w-[11%]" />
+                <col className="w-[9%]" />
+                <col className="w-[24%]" />
+                <col className="w-[26%]" />
+                <col className="w-[30%]" />
+              </colgroup>
+              <thead className="border-b border-border/60 text-[11px] uppercase tracking-[0.08em] text-muted-foreground/70">
+                <tr>
+                  <th className="whitespace-nowrap px-4 py-2.5 font-semibold sm:pl-5">Time</th>
+                  <th className="whitespace-nowrap px-4 py-2.5 font-semibold">Level</th>
+                  <th className="whitespace-nowrap px-4 py-2.5 font-semibold">Span</th>
+                  <th className="whitespace-nowrap px-4 py-2.5 font-semibold">Message</th>
+                  <th className="whitespace-nowrap px-4 py-2.5 font-semibold sm:pr-5">Trace</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-border/60">
+                {data.latestWarningAndErrorLogs.map((event) => (
+                  <tr
+                    key={`${event.traceId}:${event.spanId}:${DateTime.formatIso(event.seenAt)}:${event.message}`}
+                    className="hover:bg-muted/15"
+                  >
+                    <td className="whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums text-muted-foreground sm:pl-5">
+                      {formatRelativeNoWrap(event.seenAt)}
+                    </td>
+                    <td className="px-4 py-3 align-top">
+                      <span className="inline-flex rounded bg-muted px-1.5 py-0.5 font-mono text-[11px] font-medium uppercase text-foreground/80">
+                        {event.level}
+                      </span>
+                    </td>
+                    <td className="px-4 py-3 align-top">
+                      <div className="truncate font-medium text-foreground">{event.spanName}</div>
+                    </td>
+                    <td className="px-4 py-3 align-top text-muted-foreground">
+                      <ExpandableText
+                        collapsedClassName="line-clamp-2"
+                        expandLabel="Show full message"
+                        text={event.message}
+                      />
+                    </td>
+                    <td className="min-w-0 whitespace-nowrap px-4 py-3 align-top text-muted-foreground sm:pr-5">
+                      <TraceIdCell traceId={event.traceId} />
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </ScrollArea>
+        ) : (
+          <EmptyRows
+            label={isInitialLoading ? "Loading recent logs..." : "No warnings or errors found."}
+          />
+        )}
+      </SettingsSection>
+
+      <SettingsSection title="Top Span Names">
+        {data && data.topSpansByCount.length > 0 ? (
+          <DiagnosticsTable
+            headers={["Span", "Count", "Failures", "Average", "Max"]}
+            minTableWidth="min-w-[760px]"
+            columnWidths={["w-[48%]", "w-[13%]", "w-[13%]", "w-[13%]", "w-[13%]"]}
+          >
+            {data.topSpansByCount.map((span) => (
+              <tr key={span.name}>
+                <td className="px-4 py-3 align-top text-xs font-medium text-foreground first:sm:pl-5">
+                  {span.name}
+                </td>
+                <td className="whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums">
+                  {formatCount(span.count)}
+                </td>
+                <td className="whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums">
+                  {formatCount(span.failureCount)}
+                </td>
+                <td className="whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums">
+                  {formatDuration(span.averageDurationMs)}
+                </td>
+                <td className="whitespace-nowrap px-4 py-3 align-top font-mono tabular-nums last:sm:pr-5">
+                  {formatDuration(span.maxDurationMs)}
+                </td>
+              </tr>
+            ))}
+          </DiagnosticsTable>
+        ) : (
+          <EmptyRows label={isInitialLoading ? "Loading span names..." : "No spans found."} />
+        )}
+      </SettingsSection>
+    </SettingsPageContainer>
+  );
+}
diff --git a/apps/web/src/components/settings/KeybindingsSettings.logic.test.ts b/apps/web/src/components/settings/KeybindingsSettings.logic.test.ts
new file mode 100644
index 00000000000..6c52b9579c6
--- /dev/null
+++ b/apps/web/src/components/settings/KeybindingsSettings.logic.test.ts
@@ -0,0 +1,248 @@
+import { describe, expect, it } from "vitest";
+import type { ResolvedKeybindingsConfig } from "@t3tools/contracts";
+
+import {
+  buildKeybindingRows,
+  buildKeybindingCommandOptions,
+  buildWhenVariableOptions,
+  commandLabel,
+  keybindingConflictLabels,
+  keybindingFromKeyboardEvent,
+  parseWhenExpressionDraft,
+  shortcutToKeybindingInput,
+  unknownWhenVariables,
+  whenAstToExpression,
+} from "./KeybindingsSettings.logic";
+
+describe("KeybindingsSettings.logic", () => {
+  it("builds searchable rows with readable key and when values", () => {
+    const rows = buildKeybindingRows(
+      [
+        {
+          command: "terminal.toggle",
+          shortcut: {
+            key: "j",
+            modKey: true,
+            metaKey: false,
+            ctrlKey: false,
+            altKey: false,
+            shiftKey: false,
+          },
+          whenAst: {
+            type: "not",
+            node: { type: "identifier", name: "terminalFocus" },
+          },
+        },
+      ] satisfies ResolvedKeybindingsConfig,
+      "terminal",
+    );
+
+    expect(rows).toEqual([
+      expect.objectContaining({
+        command: "terminal.toggle",
+        key: "mod+j",
+        when: "!terminalFocus",
+        defaultKey: "mod+j",
+        defaultWhen: "",
+        source: "Custom",
+      }),
+    ]);
+  });
+
+  it("captures platform-specific mod shortcuts", () => {
+    expect(
+      keybindingFromKeyboardEvent(
+        { key: "K", metaKey: true, ctrlKey: false, altKey: false, shiftKey: true },
+        "MacIntel",
+      ),
+    ).toBe("mod+shift+k");
+    expect(
+      keybindingFromKeyboardEvent(
+        { key: "K", metaKey: false, ctrlKey: true, altKey: false, shiftKey: true },
+        "Win32",
+      ),
+    ).toBe("mod+shift+k");
+  });
+
+  it("serializes shortcuts and when expressions for upserts", () => {
+    expect(
+      shortcutToKeybindingInput({
+        key: " ",
+        modKey: true,
+        metaKey: false,
+        ctrlKey: false,
+        altKey: true,
+        shiftKey: false,
+      }),
+    ).toBe("mod+alt+space");
+
+    expect(
+      whenAstToExpression({
+        type: "and",
+        left: { type: "identifier", name: "editorFocus" },
+        right: {
+          type: "not",
+          node: { type: "identifier", name: "terminalFocus" },
+        },
+      }),
+    ).toBe("editorFocus && !terminalFocus");
+
+    expect(parseWhenExpressionDraft("editorFocus && (!terminalFocus || modelPickerOpen)")).toEqual({
+      ok: true,
+      value: {
+        type: "and",
+        left: { type: "identifier", name: "editorFocus" },
+        right: {
+          type: "or",
+          left: {
+            type: "not",
+            node: { type: "identifier", name: "terminalFocus" },
+          },
+          right: { type: "identifier", name: "modelPickerOpen" },
+        },
+      },
+    });
+    expect(parseWhenExpressionDraft("editorFocus &&")).toEqual({
+      ok: false,
+      message: "Use variables with !, &&, ||, and parentheses.",
+    });
+
+    expect(parseWhenExpressionDraft("!(terminalFocus || modelPickerOpen)")).toEqual({
+      ok: true,
+      value: {
+        type: "not",
+        node: {
+          type: "or",
+          left: { type: "identifier", name: "terminalFocus" },
+          right: { type: "identifier", name: "modelPickerOpen" },
+        },
+      },
+    });
+  });
+
+  it("formats static and project script command labels", () => {
+    expect(commandLabel("commandPalette.toggle")).toBe("Command Palette: Toggle");
+    expect(commandLabel("script.setup-db.run")).toBe("Run Script: Setup Db");
+  });
+
+  it("builds known when variable options from defaults without frontend labels", () => {
+    const options = buildWhenVariableOptions();
+
+    expect(options).toEqual(
+      expect.arrayContaining(["terminalFocus", "terminalOpen", "modelPickerOpen", "true", "false"]),
+    );
+    expect(options).not.toContain("customModeActive");
+  });
+
+  it("builds command options from defaults and resolved project bindings", () => {
+    const options = buildKeybindingCommandOptions([
+      {
+        command: "script.setup-db.run",
+        shortcut: {
+          key: "r",
+          modKey: true,
+          metaKey: false,
+          ctrlKey: false,
+          altKey: false,
+          shiftKey: false,
+        },
+      },
+    ] satisfies ResolvedKeybindingsConfig);
+
+    expect(options).toEqual(expect.arrayContaining(["chat.new", "script.setup-db.run"]));
+  });
+
+  it("reports unknown when variables without rejecting parseable expressions", () => {
+    const parsed = parseWhenExpressionDraft("!terminalFocus && terminalFoc");
+
+    expect(parsed.ok).toBe(true);
+    expect(unknownWhenVariables(parsed.ok ? parsed.value : undefined)).toEqual(["terminalFoc"]);
+  });
+
+  it("marks each default shortcut for multi-binding commands as default", () => {
+    const rows = buildKeybindingRows(
+      [
+        {
+          command: "chat.new",
+          shortcut: {
+            key: "n",
+            modKey: true,
+            metaKey: false,
+            ctrlKey: false,
+            altKey: false,
+            shiftKey: false,
+          },
+          whenAst: {
+            type: "not",
+            node: { type: "identifier", name: "terminalFocus" },
+          },
+        },
+        {
+          command: "chat.new",
+          shortcut: {
+            key: "o",
+            modKey: true,
+            metaKey: false,
+            ctrlKey: false,
+            altKey: false,
+            shiftKey: true,
+          },
+          whenAst: {
+            type: "not",
+            node: { type: "identifier", name: "terminalFocus" },
+          },
+        },
+      ] satisfies ResolvedKeybindingsConfig,
+      "",
+    );
+
+    expect(rows.map((row) => row.source)).toEqual(["Default", "Default"]);
+  });
+
+  it("reports conflicting shortcuts that share an active when context", () => {
+    const rows = buildKeybindingRows(
+      [
+        {
+          command: "chat.new",
+          shortcut: {
+            key: "n",
+            modKey: true,
+            metaKey: false,
+            ctrlKey: false,
+            altKey: false,
+            shiftKey: false,
+          },
+          whenAst: {
+            type: "not",
+            node: { type: "identifier", name: "terminalFocus" },
+          },
+        },
+        {
+          command: "chat.newLocal",
+          shortcut: {
+            key: "n",
+            modKey: true,
+            metaKey: false,
+            ctrlKey: false,
+            altKey: false,
+            shiftKey: false,
+          },
+          whenAst: {
+            type: "not",
+            node: { type: "identifier", name: "terminalFocus" },
+          },
+        },
+      ] satisfies ResolvedKeybindingsConfig,
+      "",
+    );
+
+    expect(rows[0]?.conflicts).toEqual(["Chat: New Local"]);
+    expect(
+      keybindingConflictLabels(rows, {
+        rowId: rows[0]?.id ?? "",
+        key: "mod+n",
+        when: "",
+      }),
+    ).toEqual(["Chat: New Local"]);
+  });
+});
diff --git a/apps/web/src/components/settings/KeybindingsSettings.logic.ts b/apps/web/src/components/settings/KeybindingsSettings.logic.ts
new file mode 100644
index 00000000000..bb6b92048ac
--- /dev/null
+++ b/apps/web/src/components/settings/KeybindingsSettings.logic.ts
@@ -0,0 +1,337 @@
+import {
+  type KeybindingCommand,
+  type KeybindingShortcut,
+  type KeybindingWhenNode,
+  type ResolvedKeybindingRule,
+  type ResolvedKeybindingsConfig,
+} from "@t3tools/contracts";
+import {
+  DEFAULT_RESOLVED_KEYBINDINGS,
+  parseKeybindingWhenExpression,
+} from "@t3tools/shared/keybindings";
+
+import { isMacPlatform } from "../../lib/utils";
+
+export type KeybindingSource = "Default" | "Custom" | "Project";
+
+export interface KeybindingRow {
+  readonly id: string;
+  readonly command: KeybindingCommand;
+  readonly key: string;
+  readonly when: string;
+  readonly source: KeybindingSource;
+  readonly defaultKey: string | null;
+  readonly defaultWhen: string;
+  readonly binding: ResolvedKeybindingRule;
+  readonly conflicts: ReadonlyArray<string>;
+}
+
+export type WhenVariableOption = string;
+export type KeybindingCommandOption = KeybindingCommand;
+
+const CORE_WHEN_VARIABLES = ["terminalFocus", "terminalOpen", "true", "false"] as const;
+
+const DEFAULT_WHEN_VARIABLES = new Set<string>(CORE_WHEN_VARIABLES);
+for (const binding of DEFAULT_RESOLVED_KEYBINDINGS) {
+  collectWhenIdentifiersFromNode(binding.whenAst, DEFAULT_WHEN_VARIABLES);
+}
+
+export const DEFAULT_WHEN_VARIABLE =
+  [...DEFAULT_WHEN_VARIABLES].find(
+    (identifier) => identifier !== "true" && identifier !== "false",
+  ) ?? "terminalFocus";
+const KNOWN_WHEN_VARIABLES = new Set(DEFAULT_WHEN_VARIABLES);
+
+export function shortcutToKeybindingInput(shortcut: KeybindingShortcut): string {
+  const parts: string[] = [];
+  if (shortcut.modKey) parts.push("mod");
+  if (shortcut.metaKey) parts.push("meta");
+  if (shortcut.ctrlKey) parts.push("ctrl");
+  if (shortcut.altKey) parts.push("alt");
+  if (shortcut.shiftKey) parts.push("shift");
+  parts.push(shortcut.key === " " ? "space" : shortcut.key === "escape" ? "esc" : shortcut.key);
+  return parts.join("+");
+}
+
+export function whenAstToExpression(node: KeybindingWhenNode | undefined): string {
+  if (!node) return "";
+  switch (node.type) {
+    case "identifier":
+      return node.name;
+    case "not":
+      return `!${wrapWhenExpression(node.node)}`;
+    case "and":
+      return `${wrapWhenExpression(node.left)} && ${wrapWhenExpression(node.right)}`;
+    case "or":
+      return `${wrapWhenExpression(node.left)} || ${wrapWhenExpression(node.right)}`;
+  }
+}
+
+function wrapWhenExpression(node: KeybindingWhenNode): string {
+  if (node.type === "identifier" || node.type === "not") return whenAstToExpression(node);
+  return `(${whenAstToExpression(node)})`;
+}
+
+export function parseWhenExpressionDraft(
+  expression: string,
+): { ok: true; value: KeybindingWhenNode | undefined } | { ok: false; message: string } {
+  const trimmed = expression.trim();
+  if (trimmed.length === 0) return { ok: true, value: undefined };
+
+  const ast = parseKeybindingWhenExpression(trimmed);
+  if (!ast) {
+    return {
+      ok: false,
+      message: "Use variables with !, &&, ||, and parentheses.",
+    };
+  }
+
+  return { ok: true, value: ast };
+}
+
+function sourceForBinding(binding: ResolvedKeybindingRule): KeybindingSource {
+  if (String(binding.command).startsWith("script.")) {
+    return "Project";
+  }
+
+  const bindingKey = shortcutToKeybindingInput(binding.shortcut);
+  const bindingWhen = whenAstToExpression(binding.whenAst);
+  const isDefault = DEFAULT_RESOLVED_KEYBINDINGS.some(
+    (entry) =>
+      entry.command === binding.command &&
+      shortcutToKeybindingInput(entry.shortcut) === bindingKey &&
+      whenAstToExpression(entry.whenAst) === bindingWhen,
+  );
+
+  return isDefault ? "Default" : "Custom";
+}
+
+function defaultBindingForBinding(
+  binding: ResolvedKeybindingRule,
+): ResolvedKeybindingRule | undefined {
+  const bindingKey = shortcutToKeybindingInput(binding.shortcut);
+  const bindingWhen = whenAstToExpression(binding.whenAst);
+
+  return (
+    DEFAULT_RESOLVED_KEYBINDINGS.find(
+      (entry) =>
+        entry.command === binding.command &&
+        shortcutToKeybindingInput(entry.shortcut) === bindingKey &&
+        whenAstToExpression(entry.whenAst) === bindingWhen,
+    ) ??
+    DEFAULT_RESOLVED_KEYBINDINGS.find(
+      (entry) =>
+        entry.command === binding.command && whenAstToExpression(entry.whenAst) === bindingWhen,
+    ) ??
+    DEFAULT_RESOLVED_KEYBINDINGS.find((entry) => entry.command === binding.command)
+  );
+}
+
+function keybindingRowId(command: KeybindingCommand, key: string, when: string): string {
+  return `${command}\u0000${key}\u0000${when}`;
+}
+
+function conflictsWithWhen(leftWhen: string, rightWhen: string): boolean {
+  return leftWhen.length === 0 || rightWhen.length === 0 || leftWhen === rightWhen;
+}
+
+export function keybindingConflictLabels(
+  rows: ReadonlyArray<KeybindingRow>,
+  input: { readonly rowId: string; readonly key: string; readonly when: string },
+): ReadonlyArray<string> {
+  if (input.key.trim().length === 0) return [];
+  const conflicts = rows
+    .filter(
+      (candidate) =>
+        candidate.id !== input.rowId &&
+        candidate.key === input.key &&
+        conflictsWithWhen(candidate.when, input.when),
+    )
+    .map((candidate) => commandLabel(candidate.command));
+  return [...new Set(conflicts)].toSorted();
+}
+
+export function buildKeybindingRows(
+  keybindings: ResolvedKeybindingsConfig,
+  query: string,
+): ReadonlyArray<KeybindingRow> {
+  const normalizedQuery = query.trim().toLowerCase();
+  const rows = keybindings.map((binding, index) => {
+    const defaultBinding = defaultBindingForBinding(binding);
+    const key = shortcutToKeybindingInput(binding.shortcut);
+    const when = whenAstToExpression(binding.whenAst);
+    return {
+      id: `${keybindingRowId(binding.command, key, when)}\u0000${index}`,
+      command: binding.command,
+      key,
+      when,
+      source: sourceForBinding(binding),
+      defaultKey: defaultBinding ? shortcutToKeybindingInput(defaultBinding.shortcut) : null,
+      defaultWhen: whenAstToExpression(defaultBinding?.whenAst),
+      binding,
+      conflicts: [],
+    } satisfies KeybindingRow;
+  });
+
+  const rowsWithConflicts = rows.map((row) => {
+    const conflicts = keybindingConflictLabels(rows, {
+      rowId: row.id,
+      key: row.key,
+      when: row.when,
+    });
+    return conflicts.length > 0
+      ? Object.assign({}, row, { conflicts: [...new Set(conflicts)].toSorted() })
+      : row;
+  });
+
+  rowsWithConflicts.sort((left, right) => {
+    const commandCompare = left.command.localeCompare(right.command);
+    if (commandCompare !== 0) return commandCompare;
+    return left.key.localeCompare(right.key);
+  });
+
+  if (normalizedQuery.length === 0) {
+    return rowsWithConflicts;
+  }
+
+  return rowsWithConflicts.filter((row) => {
+    return (
+      row.command.toLowerCase().includes(normalizedQuery) ||
+      row.key.toLowerCase().includes(normalizedQuery) ||
+      row.when.toLowerCase().includes(normalizedQuery) ||
+      row.source.toLowerCase().includes(normalizedQuery)
+    );
+  });
+}
+
+function collectWhenIdentifiersFromNode(
+  node: KeybindingWhenNode | undefined,
+  identifiers: Set<string>,
+): void {
+  if (!node) return;
+  switch (node.type) {
+    case "identifier":
+      identifiers.add(node.name);
+      return;
+    case "not":
+      collectWhenIdentifiersFromNode(node.node, identifiers);
+      return;
+    case "and":
+    case "or":
+      collectWhenIdentifiersFromNode(node.left, identifiers);
+      collectWhenIdentifiersFromNode(node.right, identifiers);
+      return;
+  }
+}
+
+export function isKnownWhenVariable(identifier: string): boolean {
+  return KNOWN_WHEN_VARIABLES.has(identifier);
+}
+
+export function unknownWhenVariables(node: KeybindingWhenNode | undefined): ReadonlyArray<string> {
+  const identifiers = new Set<string>();
+  collectWhenIdentifiersFromNode(node, identifiers);
+  return [...identifiers].filter((identifier) => !isKnownWhenVariable(identifier)).toSorted();
+}
+
+export function buildWhenVariableOptions(): ReadonlyArray<WhenVariableOption> {
+  return [...KNOWN_WHEN_VARIABLES].toSorted((left, right) => {
+    const leftCoreIndex = CORE_WHEN_VARIABLES.indexOf(left as (typeof CORE_WHEN_VARIABLES)[number]);
+    const rightCoreIndex = CORE_WHEN_VARIABLES.indexOf(
+      right as (typeof CORE_WHEN_VARIABLES)[number],
+    );
+    if (leftCoreIndex !== -1 || rightCoreIndex !== -1) {
+      return (
+        (leftCoreIndex === -1 ? Number.MAX_SAFE_INTEGER : leftCoreIndex) -
+        (rightCoreIndex === -1 ? Number.MAX_SAFE_INTEGER : rightCoreIndex)
+      );
+    }
+    return left.localeCompare(right);
+  });
+}
+
+export function buildKeybindingCommandOptions(
+  keybindings: ResolvedKeybindingsConfig,
+): ReadonlyArray<KeybindingCommandOption> {
+  const commands = new Set<KeybindingCommand>();
+  for (const binding of DEFAULT_RESOLVED_KEYBINDINGS) {
+    commands.add(binding.command);
+  }
+  for (const binding of keybindings) {
+    commands.add(binding.command);
+  }
+  return [...commands].toSorted((left, right) =>
+    commandLabel(left).localeCompare(commandLabel(right)),
+  );
+}
+
+export function commandLabel(command: KeybindingCommand): string {
+  const raw = String(command);
+  if (raw.startsWith("script.") && raw.endsWith(".run")) {
+    return `Run Script: ${titleCaseCommandSegment(raw.slice("script.".length, -".run".length))}`;
+  }
+  return raw.split(".").map(titleCaseCommandSegment).join(": ");
+}
+
+function titleCaseCommandSegment(segment: string): string {
+  return segment
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+export function normalizeShortcutKeyToken(key: string): string | null {
+  const normalized = key.toLowerCase();
+  if (
+    normalized === "meta" ||
+    normalized === "control" ||
+    normalized === "ctrl" ||
+    normalized === "shift" ||
+    normalized === "alt" ||
+    normalized === "option"
+  ) {
+    return null;
+  }
+  if (normalized === " ") return "space";
+  if (normalized === "escape") return "esc";
+  if (normalized === "arrowup") return "arrowup";
+  if (normalized === "arrowdown") return "arrowdown";
+  if (normalized === "arrowleft") return "arrowleft";
+  if (normalized === "arrowright") return "arrowright";
+  if (normalized.length === 1) return normalized;
+  if (/^f\d{1,2}$/.test(normalized)) return normalized;
+  if (normalized === "enter" || normalized === "tab" || normalized === "backspace") {
+    return normalized;
+  }
+  if (normalized === "delete" || normalized === "home" || normalized === "end") {
+    return normalized;
+  }
+  if (normalized === "pageup" || normalized === "pagedown") return normalized;
+  return null;
+}
+
+export function keybindingFromKeyboardEvent(
+  event: Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "altKey" | "shiftKey">,
+  platform: string,
+): string | null {
+  const keyToken = normalizeShortcutKeyToken(event.key);
+  if (!keyToken) return null;
+
+  const parts: string[] = [];
+  if (isMacPlatform(platform)) {
+    if (event.metaKey) parts.push("mod");
+    if (event.ctrlKey) parts.push("ctrl");
+  } else {
+    if (event.ctrlKey) parts.push("mod");
+    if (event.metaKey) parts.push("meta");
+  }
+  if (event.altKey) parts.push("alt");
+  if (event.shiftKey) parts.push("shift");
+  if (parts.length === 0) {
+    return null;
+  }
+  parts.push(keyToken);
+  return parts.join("+");
+}
diff --git a/apps/web/src/components/settings/KeybindingsSettings.tsx b/apps/web/src/components/settings/KeybindingsSettings.tsx
new file mode 100644
index 00000000000..89b070c931c
--- /dev/null
+++ b/apps/web/src/components/settings/KeybindingsSettings.tsx
@@ -0,0 +1,1282 @@
+import {
+  ChevronDownIcon,
+  CircleXIcon,
+  EllipsisIcon,
+  FileJsonIcon,
+  InfoIcon,
+  MinusIcon,
+  PlusIcon,
+  SearchIcon,
+  TriangleAlertIcon,
+  XIcon,
+} from "lucide-react";
+import {
+  type KeyboardEvent,
+  type ReactNode,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from "react";
+import {
+  type KeybindingCommand,
+  type KeybindingWhenNode,
+  type ServerRemoveKeybindingInput,
+  type ServerUpsertKeybindingInput,
+} from "@t3tools/contracts";
+
+import { isElectron } from "../../env";
+import { openInPreferredEditor } from "../../editorPreferences";
+import { formatShortcutLabel } from "../../keybindings";
+import { cn } from "../../lib/utils";
+import { ensureLocalApi } from "../../localApi";
+import { useServerKeybindings, useServerKeybindingsConfigPath } from "../../rpc/serverState";
+import { Button } from "../ui/button";
+import { Input } from "../ui/input";
+import { Kbd, KbdGroup } from "../ui/kbd";
+import { Menu, MenuItem, MenuPopup, MenuTrigger } from "../ui/menu";
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover";
+import { ScrollArea } from "../ui/scroll-area";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../ui/select";
+import { Toggle } from "../ui/toggle";
+import { toastManager } from "../ui/toast";
+import {
+  buildKeybindingRows,
+  buildKeybindingCommandOptions,
+  buildWhenVariableOptions,
+  commandLabel,
+  DEFAULT_WHEN_VARIABLE,
+  isKnownWhenVariable,
+  keybindingConflictLabels,
+  keybindingFromKeyboardEvent,
+  parseWhenExpressionDraft,
+  type KeybindingCommandOption,
+  type KeybindingRow,
+  type WhenVariableOption,
+  unknownWhenVariables,
+  whenAstToExpression,
+} from "./KeybindingsSettings.logic";
+import { SettingsPageContainer, SettingsSection } from "./settingsLayout";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+
+function KeybindingPill({ value }: { value: string }) {
+  const parts = value.split("+");
+  return (
+    <KbdGroup className="bg-transparent p-0 shadow-none">
+      {parts.map((part) => (
+        <Kbd key={part} className="min-w-6 justify-center px-1.5">
+          {part === "mod"
+            ? navigator.platform.toLowerCase().includes("mac")
+              ? "⌘"
+              : "Ctrl"
+            : part === "shift"
+              ? "⇧"
+              : part === "alt"
+                ? navigator.platform.toLowerCase().includes("mac")
+                  ? "⌥"
+                  : "Alt"
+                : part === "ctrl"
+                  ? "⌃"
+                  : part.length === 1
+                    ? part.toUpperCase()
+                    : part}
+        </Kbd>
+      ))}
+    </KbdGroup>
+  );
+}
+
+function ExpandableHeaderSearch({
+  query,
+  onChange,
+  isOpen,
+  onOpenChange,
+  inputRef,
+  collapsedAccessory,
+}: {
+  query: string;
+  onChange: (next: string) => void;
+  isOpen: boolean;
+  onOpenChange: (next: boolean) => void;
+  inputRef?: RefObject<HTMLInputElement | null>;
+  collapsedAccessory?: ReactNode;
+}) {
+  if (!isOpen) {
+    return (
+      <>
+        {collapsedAccessory}
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <Button
+                type="button"
+                size="icon-xs"
+                variant="ghost"
+                className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                onClick={() => onOpenChange(true)}
+                aria-label="Search keybindings"
+              >
+                <SearchIcon className="size-3" />
+              </Button>
+            }
+          />
+          <TooltipPopup side="top">Search keybindings</TooltipPopup>
+        </Tooltip>
+      </>
+    );
+  }
+
+  return (
+    <div className="relative">
+      <SearchIcon className="pointer-events-none absolute top-1/2 left-2 size-3 -translate-y-1/2 text-muted-foreground" />
+      <input
+        ref={inputRef}
+        autoFocus
+        type="text"
+        value={query}
+        onChange={(event) => onChange(event.currentTarget.value)}
+        onBlur={() => {
+          if (query.length === 0) onOpenChange(false);
+        }}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            onChange("");
+            onOpenChange(false);
+          }
+        }}
+        placeholder="Search keybindings"
+        aria-label="Search keybindings"
+        className="h-6 w-44 rounded-md border border-input bg-background pl-7 pr-2 text-[11px] text-foreground outline-none placeholder:text-muted-foreground/72 focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/24"
+      />
+    </div>
+  );
+}
+
+type BooleanOperator = "and" | "or";
+
+function flattenWhenChildren(
+  node: KeybindingWhenNode,
+  operator: BooleanOperator,
+): KeybindingWhenNode[] {
+  if (node.type !== operator) return [node];
+  return [
+    ...flattenWhenChildren(node.left, operator),
+    ...flattenWhenChildren(node.right, operator),
+  ];
+}
+
+function buildWhenExpressionGroup(
+  children: readonly KeybindingWhenNode[],
+  operator: BooleanOperator,
+): KeybindingWhenNode | undefined {
+  const first = children[0];
+  if (!first) return undefined;
+  return children.slice(1).reduce<KeybindingWhenNode>(
+    (left, right) => ({
+      type: operator,
+      left,
+      right,
+    }),
+    first,
+  );
+}
+
+function conditionParts(node: KeybindingWhenNode): { identifier: string; negated: boolean } | null {
+  if (node.type === "identifier") return { identifier: node.name, negated: false };
+  if (node.type === "not" && node.node.type === "identifier") {
+    return { identifier: node.node.name, negated: true };
+  }
+  return null;
+}
+
+function setConditionIdentifier(node: KeybindingWhenNode, identifier: string): KeybindingWhenNode {
+  const parts = conditionParts(node);
+  if (!parts) return node;
+  const next: KeybindingWhenNode = { type: "identifier", name: identifier };
+  return parts.negated ? { type: "not", node: next } : next;
+}
+
+function setConditionNegated(node: KeybindingWhenNode, negated: boolean): KeybindingWhenNode {
+  const parts = conditionParts(node);
+  if (!parts) return negated ? { type: "not", node } : node;
+  const identifier: KeybindingWhenNode = { type: "identifier", name: parts.identifier };
+  return negated ? { type: "not", node: identifier } : identifier;
+}
+
+function defaultWhenCondition(): KeybindingWhenNode {
+  return { type: "identifier", name: DEFAULT_WHEN_VARIABLE };
+}
+
+function defaultWhenGroup(operator: BooleanOperator = "and"): KeybindingWhenNode {
+  return {
+    type: operator,
+    left: defaultWhenCondition(),
+    right: { type: "not", node: defaultWhenCondition() },
+  };
+}
+
+function UnknownWhenVariableWarning({
+  identifiers,
+  focusable = true,
+}: {
+  identifiers: ReadonlyArray<string>;
+  focusable?: boolean;
+}) {
+  if (identifiers.length === 0) return null;
+  const label =
+    identifiers.length === 1
+      ? `Unknown condition: ${identifiers[0]}`
+      : `Unknown conditions: ${identifiers.join(", ")}`;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <span
+            tabIndex={focusable ? 0 : undefined}
+            aria-label={label}
+            className="inline-flex size-4.5 shrink-0 items-center justify-center rounded-sm text-warning outline-none transition-colors hover:bg-warning/10 focus-visible:ring-[3px] focus-visible:ring-warning/25"
+          >
+            <TriangleAlertIcon className="size-3.5" />
+          </span>
+        }
+      />
+      <TooltipPopup side="top" className="max-w-72 whitespace-normal leading-relaxed">
+        T3 Code does not recognize this condition yet. It can still be saved, but it may not match
+        unless the runtime provides it.
+      </TooltipPopup>
+    </Tooltip>
+  );
+}
+
+function KeybindingConflictWarning({ labels }: { labels: ReadonlyArray<string> }) {
+  if (labels.length === 0) return null;
+  const description =
+    labels.length === 1
+      ? `Conflicts with ${labels[0]}.`
+      : `Conflicts with ${labels.slice(0, 3).join(", ")}${labels.length > 3 ? ", and more" : ""}.`;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <span
+            tabIndex={0}
+            aria-label={description}
+            className="inline-flex size-5 shrink-0 items-center justify-center rounded-sm text-warning outline-none transition-colors hover:bg-warning/10 focus-visible:ring-[3px] focus-visible:ring-warning/25"
+          >
+            <TriangleAlertIcon className="size-3.5" />
+          </span>
+        }
+      />
+      <TooltipPopup side="top" className="max-w-72 whitespace-normal leading-relaxed">
+        {description} The most recent matching binding wins when both conditions can apply.
+      </TooltipPopup>
+    </Tooltip>
+  );
+}
+
+function WhenVariableSelect({
+  value,
+  variables,
+  unknownIdentifiers,
+  onChange,
+}: {
+  value: string;
+  variables: ReadonlyArray<WhenVariableOption>;
+  unknownIdentifiers?: ReadonlyArray<string>;
+  onChange: (value: string) => void;
+}) {
+  const selected = variables.find((option) => option === value);
+  const options =
+    selected || variables.some((option) => option === value) ? variables : [value, ...variables];
+
+  return (
+    <Select value={value} onValueChange={(nextValue) => nextValue && onChange(nextValue)}>
+      <SelectTrigger
+        size="xs"
+        className="h-7 min-h-7 min-w-0 flex-1 rounded-md font-mono text-xs sm:h-7"
+      >
+        <SelectValue placeholder="Condition" className="leading-7" />
+        {unknownIdentifiers && unknownIdentifiers.length > 0 ? (
+          <UnknownWhenVariableWarning identifiers={unknownIdentifiers} focusable={false} />
+        ) : null}
+      </SelectTrigger>
+      <SelectContent
+        alignItemWithTrigger={false}
+        matchTriggerWidth={false}
+        popupClassName="w-fit"
+        className="max-h-72 w-fit min-w-44"
+      >
+        {options.map((option) => (
+          <SelectItem
+            key={option}
+            value={option}
+            className="min-h-7 w-full py-1 font-mono text-[12px]"
+          >
+            <span className="truncate">{option}</span>
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
+function WhenExpressionNodeEditor({
+  node,
+  variables,
+  depth = 0,
+  onChange,
+  onRemove,
+}: {
+  node: KeybindingWhenNode;
+  variables: ReadonlyArray<WhenVariableOption>;
+  depth?: number;
+  onChange: (node: KeybindingWhenNode) => void;
+  onRemove?: () => void;
+}) {
+  const condition = conditionParts(node);
+
+  if (condition) {
+    const unknownIdentifiers = isKnownWhenVariable(condition.identifier)
+      ? []
+      : [condition.identifier];
+
+    return (
+      <div className="flex items-center gap-2 rounded-md border border-border/70 bg-background/60 px-2 py-2">
+        <Toggle
+          pressed={condition.negated}
+          onPressedChange={(pressed) => onChange(setConditionNegated(node, pressed))}
+          aria-label={`Negate ${condition.identifier}`}
+          variant="outline"
+          size="xs"
+          className="h-7 min-w-10 px-2 text-[11px] sm:h-7"
+        >
+          Not
+        </Toggle>
+        <WhenVariableSelect
+          value={condition.identifier}
+          variables={variables}
+          unknownIdentifiers={unknownIdentifiers}
+          onChange={(value) => onChange(setConditionIdentifier(node, value))}
+        />
+        {onRemove ? (
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon-sm"
+            className="size-7 sm:size-7"
+            aria-label="Remove condition"
+            onClick={onRemove}
+          >
+            <MinusIcon className="size-3.5" />
+          </Button>
+        ) : null}
+      </div>
+    );
+  }
+
+  if (node.type === "not") {
+    return (
+      <div
+        className={cn(
+          "space-y-2 rounded-lg border border-border/70 bg-muted/20 p-2",
+          depth > 0 && "border-border/50 bg-background/50",
+        )}
+      >
+        <div className="flex items-center gap-2">
+          <Toggle
+            pressed
+            onPressedChange={(pressed) => onChange(pressed ? node : node.node)}
+            aria-label="Negate group"
+            variant="outline"
+            size="xs"
+            className="h-7 min-w-10 px-2 text-[11px] sm:h-7"
+          >
+            Not
+          </Toggle>
+          {onRemove ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-sm"
+              className="ml-auto size-7 sm:size-7"
+              aria-label="Remove negated group"
+              onClick={onRemove}
+            >
+              <MinusIcon className="size-3.5" />
+            </Button>
+          ) : null}
+        </div>
+        <div className="relative pl-4">
+          <span className="absolute top-0 bottom-0 left-1.5 w-px bg-border/70" aria-hidden />
+          <span className="absolute top-4 left-1.5 h-px w-2.5 bg-border/70" aria-hidden />
+          <WhenExpressionNodeEditor
+            node={node.node}
+            variables={variables}
+            depth={depth + 1}
+            onChange={(next) => onChange({ type: "not", node: next })}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  const operator: BooleanOperator = node.type === "or" ? "or" : "and";
+  const children = flattenWhenChildren(node, operator);
+  const childKeyCounts = new Map<string, number>();
+  const childEntries = children.map((child) => {
+    const baseKey = `${child.type}-${whenAstToExpression(child)}`;
+    const count = childKeyCounts.get(baseKey) ?? 0;
+    childKeyCounts.set(baseKey, count + 1);
+    return { child, key: count === 0 ? baseKey : `${baseKey}-${count}` };
+  });
+
+  const updateChild = (target: KeybindingWhenNode, next: KeybindingWhenNode) => {
+    let didUpdate = false;
+    const nextChildren = children.map((child) => {
+      if (!didUpdate && child === target) {
+        didUpdate = true;
+        return next;
+      }
+      return child;
+    });
+    const nextNode = buildWhenExpressionGroup(nextChildren, operator);
+    if (nextNode) onChange(nextNode);
+  };
+
+  const removeChild = (target: KeybindingWhenNode) => {
+    let didRemove = false;
+    const nextChildren = children.filter((child) => {
+      if (!didRemove && child === target) {
+        didRemove = true;
+        return false;
+      }
+      return true;
+    });
+    const nextNode = buildWhenExpressionGroup(nextChildren, operator);
+    if (nextNode) {
+      onChange(nextNode);
+    } else {
+      onChange(defaultWhenCondition());
+    }
+  };
+
+  const setOperator = (nextOperator: BooleanOperator) => {
+    if (nextOperator === operator) return;
+    const nextNode = buildWhenExpressionGroup(children, nextOperator);
+    if (nextNode) onChange(nextNode);
+  };
+
+  const addCondition = () => {
+    const nextNode = buildWhenExpressionGroup([...children, defaultWhenCondition()], operator);
+    if (nextNode) onChange(nextNode);
+  };
+
+  const addGroup = () => {
+    const nestedOperator: BooleanOperator = operator === "and" ? "or" : "and";
+    const group: KeybindingWhenNode = {
+      type: nestedOperator,
+      left: defaultWhenCondition(),
+      right: { type: "not", node: defaultWhenCondition() },
+    };
+    const nextNode = buildWhenExpressionGroup([...children, group], operator);
+    if (nextNode) onChange(nextNode);
+  };
+
+  return (
+    <div
+      className={cn(
+        "space-y-2 rounded-lg border border-border/60 bg-muted/10 p-2",
+        depth > 0 && "border-border/70 bg-background/55",
+      )}
+    >
+      <div className="flex flex-wrap items-center gap-2">
+        <Select value={operator} onValueChange={(value) => setOperator(value as BooleanOperator)}>
+          <SelectTrigger size="xs" className="h-7 min-h-7 w-24 rounded-md text-xs sm:h-7">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent
+            alignItemWithTrigger={false}
+            matchTriggerWidth={false}
+            popupClassName="w-fit"
+            className="w-fit min-w-24"
+          >
+            <SelectItem value="and" className="min-h-7 py-1 font-mono text-[12px]">
+              and
+            </SelectItem>
+            <SelectItem value="or" className="min-h-7 py-1 font-mono text-[12px]">
+              or
+            </SelectItem>
+          </SelectContent>
+        </Select>
+        <Button
+          type="button"
+          variant="outline"
+          size="xs"
+          className="h-7 sm:h-7"
+          onClick={addCondition}
+        >
+          <PlusIcon className="size-3.5" />
+          Condition
+        </Button>
+        <Button type="button" variant="outline" size="xs" className="h-7 sm:h-7" onClick={addGroup}>
+          <PlusIcon className="size-3.5" />
+          Group
+        </Button>
+        {onRemove ? (
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon-sm"
+            className="ml-auto size-7 sm:size-7"
+            aria-label="Remove group"
+            onClick={onRemove}
+          >
+            <MinusIcon className="size-3.5" />
+          </Button>
+        ) : null}
+      </div>
+      <div className="space-y-2">
+        {childEntries.map(({ child, key }) => (
+          <div key={key} className="relative pl-4">
+            <span
+              className={cn(
+                "absolute top-0 bottom-0 left-1.5 w-px",
+                depth === 0 ? "bg-border" : "bg-border/70",
+              )}
+              aria-hidden
+            />
+            <span
+              className={cn(
+                "absolute top-4 left-1.5 h-px w-2.5",
+                depth === 0 ? "bg-border" : "bg-border/70",
+              )}
+              aria-hidden
+            />
+            <WhenExpressionNodeEditor
+              node={child}
+              variables={variables}
+              depth={depth + 1}
+              onChange={(next) => updateChild(child, next)}
+              onRemove={() => removeChild(child)}
+            />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function WhenExpressionBuilder({
+  value,
+  variables,
+  onChange,
+  onValidityChange,
+}: {
+  value: KeybindingWhenNode | undefined;
+  variables: ReadonlyArray<WhenVariableOption>;
+  onChange: (value: KeybindingWhenNode | undefined) => void;
+  onValidityChange?: (valid: boolean) => void;
+}) {
+  const expression = whenAstToExpression(value);
+  const [expressionDraft, setExpressionDraft] = useState(expression);
+  const parseResult = useMemo(() => parseWhenExpressionDraft(expressionDraft), [expressionDraft]);
+  const parseError = parseResult.ok ? null : parseResult.message;
+  const unknownIdentifiers = parseResult.ok ? unknownWhenVariables(parseResult.value) : [];
+
+  const updateExpressionDraft = (nextExpression: string) => {
+    setExpressionDraft(nextExpression);
+    const nextResult = parseWhenExpressionDraft(nextExpression);
+    onValidityChange?.(nextResult.ok);
+    if (nextResult.ok) {
+      onChange(nextResult.value);
+    }
+  };
+
+  const updateExpressionValue = (nextValue: KeybindingWhenNode | undefined) => {
+    setExpressionDraft(whenAstToExpression(nextValue));
+    onValidityChange?.(true);
+    onChange(nextValue);
+  };
+
+  const addRootCondition = () => {
+    if (!value) {
+      updateExpressionValue(defaultWhenCondition());
+      return;
+    }
+    updateExpressionValue({ type: "and", left: value, right: defaultWhenCondition() });
+  };
+
+  const addRootGroup = () => {
+    const group = defaultWhenGroup("or");
+    if (!value) {
+      updateExpressionValue(group);
+      return;
+    }
+    updateExpressionValue({ type: "and", left: value, right: group });
+  };
+
+  return (
+    <div className="w-[min(34rem,calc(100vw-2rem))] space-y-3">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <div className="text-sm font-medium text-foreground">When</div>
+        </div>
+        <div className="flex shrink-0 items-center gap-2">
+          <Button
+            type="button"
+            variant="outline"
+            size="xs"
+            className="h-7 sm:h-7"
+            onClick={addRootCondition}
+          >
+            <PlusIcon className="size-3.5" />
+            Condition
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            size="xs"
+            className="h-7 sm:h-7"
+            onClick={addRootGroup}
+          >
+            <PlusIcon className="size-3.5" />
+            Group
+          </Button>
+        </div>
+      </div>
+
+      <div className="space-y-1.5">
+        <div className="relative">
+          <Input
+            value={expressionDraft}
+            onChange={(event) => updateExpressionDraft(event.currentTarget.value)}
+            placeholder="Always"
+            aria-invalid={Boolean(parseError)}
+            aria-label="When expression"
+            className={cn(
+              "h-7 rounded-md font-mono text-[12px] leading-7 sm:h-7 sm:leading-7",
+              unknownIdentifiers.length > 0 && "pr-9",
+              parseError && "border-destructive/70 focus-visible:border-destructive",
+            )}
+          />
+          {unknownIdentifiers.length > 0 ? (
+            <span className="absolute inset-y-0 right-2 flex items-center">
+              <UnknownWhenVariableWarning identifiers={unknownIdentifiers} />
+            </span>
+          ) : null}
+        </div>
+        {parseError ? (
+          <div className="flex items-center gap-1.5 text-[11px] text-destructive">
+            <CircleXIcon className="size-3.5" />
+            {parseError}
+          </div>
+        ) : null}
+      </div>
+
+      <div className="relative">
+        {value ? (
+          <WhenExpressionNodeEditor
+            node={value}
+            variables={variables}
+            onChange={updateExpressionValue}
+            onRemove={() => updateExpressionValue(undefined)}
+          />
+        ) : (
+          <div className="rounded-md border border-dashed border-border/80 bg-muted/15 p-3">
+            <div className="flex flex-wrap gap-2">
+              <Button type="button" size="xs" className="h-7 sm:h-7" onClick={addRootCondition}>
+                <PlusIcon className="size-3.5" />
+                Condition
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                size="xs"
+                className="h-7 sm:h-7"
+                onClick={addRootGroup}
+              >
+                <PlusIcon className="size-3.5" />
+                Group
+              </Button>
+            </div>
+          </div>
+        )}
+        {parseError ? (
+          <div className="pointer-events-none absolute inset-0 flex items-center justify-center rounded-lg border border-destructive/30 bg-background/75 p-4 text-center text-xs text-destructive backdrop-blur-[1px]">
+            Fix the expression above to continue editing visually.
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+type KeybindingRowDraftState = {
+  keyDraft: string;
+  whenDraft: KeybindingWhenNode | undefined;
+  isRecording: boolean;
+  isWhenDraftValid: boolean;
+};
+
+function createKeybindingRowDraft(row: KeybindingRow): KeybindingRowDraftState {
+  return {
+    keyDraft: row.key,
+    whenDraft: row.binding.whenAst,
+    isRecording: false,
+    isWhenDraftValid: true,
+  };
+}
+
+function keybindingRowDraftReducer(
+  state: KeybindingRowDraftState,
+  patch: Partial<KeybindingRowDraftState>,
+): KeybindingRowDraftState {
+  return { ...state, ...patch };
+}
+
+function rowKeybindingTarget(row: KeybindingRow): ServerRemoveKeybindingInput {
+  return {
+    command: row.command,
+    key: row.key,
+    ...(row.when.trim().length > 0 ? { when: row.when } : {}),
+  };
+}
+
+function KeybindingTableRow({
+  row,
+  allRows,
+  variables,
+  isSaving,
+  onSave,
+  onReset,
+  onRemove,
+}: {
+  row: KeybindingRow;
+  allRows: ReadonlyArray<KeybindingRow>;
+  variables: ReadonlyArray<WhenVariableOption>;
+  isSaving: boolean;
+  onSave: (input: ServerUpsertKeybindingInput) => void;
+  onReset: (row: KeybindingRow) => void;
+  onRemove: (row: KeybindingRow) => void;
+}) {
+  const [draft, setDraft] = useReducer(keybindingRowDraftReducer, row, createKeybindingRowDraft);
+  const { keyDraft, whenDraft, isRecording, isWhenDraftValid } = draft;
+  const whenDraftExpression = whenAstToExpression(whenDraft);
+  const isDirty = keyDraft !== row.key || whenDraftExpression !== row.when;
+  const displayShortcut = formatShortcutLabel(row.binding.shortcut);
+  const canReset = row.source === "Custom" && row.defaultKey !== null;
+  const canRemove = row.source !== "Default";
+  const hasRowActions = canReset || canRemove;
+  const showPill = !isRecording && keyDraft === row.key && row.key.length > 0 && !isDirty;
+  const conflictLabels = keybindingConflictLabels(allRows, {
+    rowId: row.id,
+    key: keyDraft,
+    when: whenDraftExpression,
+  });
+
+  const save = () => {
+    onSave({
+      command: row.command,
+      key: keyDraft,
+      when: whenDraftExpression.trim().length > 0 ? whenDraftExpression : undefined,
+      replace: rowKeybindingTarget(row),
+    });
+  };
+
+  const captureKeybinding = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === "Tab") return;
+    event.preventDefault();
+    if (event.key === "Escape") {
+      setDraft({ keyDraft: row.key, isRecording: false });
+      return;
+    }
+    const next = keybindingFromKeyboardEvent(event.nativeEvent, navigator.platform);
+    if (!next) return;
+    setDraft({ keyDraft: next, isRecording: false });
+  };
+
+  return (
+    <div className="grid grid-cols-[minmax(190px,1.1fr)_minmax(220px,0.85fr)_minmax(210px,1fr)_60px] items-center px-4 py-1.5 text-sm even:bg-muted/15 hover:bg-accent/40">
+      <div className="min-w-0 pr-4">
+        <div className="flex min-w-0 items-center gap-1.5">
+          <div className="truncate text-[13px] font-medium text-foreground" title={row.command}>
+            {commandLabel(row.command)}
+          </div>
+        </div>
+      </div>
+      <div className="flex min-w-0 items-center gap-2 pr-4">
+        {showPill ? (
+          <button
+            type="button"
+            onClick={() => setDraft({ isRecording: true })}
+            aria-label={`Edit shortcut for ${commandLabel(row.command)}`}
+            className="group inline-flex h-7 items-center gap-1.5 rounded-md border border-transparent px-1.5 outline-none transition-colors hover:border-border/70 hover:bg-background focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/24"
+          >
+            <KeybindingPill value={row.key} />
+            <span className="text-[10px] uppercase tracking-[0.08em] text-muted-foreground/0 transition-opacity group-hover:text-muted-foreground/70 group-focus-visible:text-muted-foreground/70">
+              Edit
+            </span>
+          </button>
+        ) : (
+          <Input
+            autoFocus={isRecording}
+            aria-label={`Keybinding for ${commandLabel(row.command)}`}
+            value={isRecording ? "" : keyDraft}
+            placeholder={isRecording ? "Press shortcut" : "Unassigned"}
+            className={cn(
+              "h-7 w-44 rounded-md font-mono text-[12px] sm:h-7",
+              isRecording && "border-primary/70 bg-primary/5",
+            )}
+            onFocus={() => setDraft({ isRecording: true })}
+            onBlur={() => setDraft({ isRecording: false })}
+            onChange={(event) => setDraft({ keyDraft: event.currentTarget.value })}
+            onKeyDown={captureKeybinding}
+          />
+        )}
+        {isDirty ? (
+          <Button
+            size="xs"
+            className="h-7 sm:h-7"
+            disabled={isSaving || keyDraft.trim().length === 0 || !isWhenDraftValid}
+            onClick={save}
+          >
+            {isSaving ? "Saving" : "Save"}
+          </Button>
+        ) : null}
+      </div>
+      <div className="pr-4">
+        <Popover>
+          <PopoverTrigger
+            className={cn(
+              "inline-flex h-7 w-full items-center justify-between gap-2 rounded-md border border-input bg-background px-2.5 text-left font-mono text-[12px] text-foreground shadow-xs/5 outline-none transition-colors hover:bg-accent focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/24",
+              !whenDraftExpression && "text-muted-foreground",
+            )}
+            aria-label={`Edit when clause for ${commandLabel(row.command)}`}
+          >
+            <span className="truncate">{whenDraftExpression || "Always"}</span>
+            <ChevronDownIcon className="size-3.5 shrink-0 opacity-60" />
+          </PopoverTrigger>
+          <PopoverContent align="start" sideOffset={6}>
+            <WhenExpressionBuilder
+              value={whenDraft}
+              variables={variables}
+              onChange={(nextWhenDraft) => setDraft({ whenDraft: nextWhenDraft })}
+              onValidityChange={(nextIsValid) => setDraft({ isWhenDraftValid: nextIsValid })}
+            />
+          </PopoverContent>
+        </Popover>
+      </div>
+      <div className="flex items-center justify-end gap-1">
+        <KeybindingConflictWarning labels={conflictLabels} />
+        {hasRowActions ? (
+          <Menu>
+            <MenuTrigger
+              render={
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon-sm"
+                  className="size-7 text-muted-foreground hover:text-foreground sm:size-7"
+                  disabled={isSaving}
+                  aria-label={`Actions for ${commandLabel(row.command)}`}
+                />
+              }
+            >
+              <EllipsisIcon className="size-3.5" />
+            </MenuTrigger>
+            <MenuPopup align="end" className="min-w-36">
+              {canReset ? (
+                <MenuItem disabled={isSaving} onClick={() => onReset(row)}>
+                  Reset to default
+                </MenuItem>
+              ) : null}
+              {canRemove ? (
+                <MenuItem variant="destructive" disabled={isSaving} onClick={() => onRemove(row)}>
+                  Remove
+                </MenuItem>
+              ) : null}
+            </MenuPopup>
+          </Menu>
+        ) : null}
+        <span className="sr-only">{displayShortcut}</span>
+      </div>
+    </div>
+  );
+}
+
+function NewKeybindingTableRow({
+  commandOptions,
+  allRows,
+  variables,
+  isSaving,
+  onSave,
+  onCancel,
+}: {
+  commandOptions: ReadonlyArray<KeybindingCommandOption>;
+  allRows: ReadonlyArray<KeybindingRow>;
+  variables: ReadonlyArray<WhenVariableOption>;
+  isSaving: boolean;
+  onSave: (input: ServerUpsertKeybindingInput) => void;
+  onCancel: () => void;
+}) {
+  const [commandDraft, setCommandDraft] = useState<KeybindingCommand | "">("");
+  const [draft, setDraft] = useReducer(keybindingRowDraftReducer, {
+    keyDraft: "",
+    whenDraft: undefined,
+    isRecording: false,
+    isWhenDraftValid: true,
+  });
+  const { keyDraft, whenDraft, isRecording, isWhenDraftValid } = draft;
+  const whenDraftExpression = whenAstToExpression(whenDraft);
+  const conflictLabels = keybindingConflictLabels(allRows, {
+    rowId: "new",
+    key: keyDraft,
+    when: whenDraftExpression,
+  });
+  const commandLabelText = commandDraft ? commandLabel(commandDraft) : "new keybinding";
+
+  const save = () => {
+    if (!commandDraft) return;
+    onSave({
+      command: commandDraft,
+      key: keyDraft,
+      ...(whenDraftExpression.trim().length > 0 ? { when: whenDraftExpression } : {}),
+    });
+  };
+
+  const captureKeybinding = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === "Tab") return;
+    event.preventDefault();
+    if (event.key === "Escape") {
+      setDraft({ keyDraft: "", isRecording: false });
+      return;
+    }
+    const next = keybindingFromKeyboardEvent(event.nativeEvent, navigator.platform);
+    if (!next) return;
+    setDraft({ keyDraft: next, isRecording: false });
+  };
+
+  return (
+    <div className="grid grid-cols-[minmax(190px,1.1fr)_minmax(220px,0.85fr)_minmax(210px,1fr)_60px] items-center px-4 py-1.5 text-sm even:bg-muted/15 hover:bg-accent/40">
+      <div className="min-w-0 pr-4">
+        <Select
+          value={commandDraft}
+          onValueChange={(value) => setCommandDraft(value as KeybindingCommand)}
+        >
+          <SelectTrigger
+            size="xs"
+            className="h-7 min-h-7 w-full max-w-60 rounded-md text-xs sm:h-7"
+          >
+            <SelectValue placeholder="Command" />
+          </SelectTrigger>
+          <SelectContent
+            alignItemWithTrigger={false}
+            matchTriggerWidth={false}
+            className="max-h-72 w-fit min-w-56"
+          >
+            {commandOptions.map((command) => (
+              <SelectItem key={command} value={command} className="min-h-7 w-full py-1 text-[12px]">
+                <span className="truncate">{commandLabel(command)}</span>
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+      <div className="flex min-w-0 items-center gap-2 pr-4">
+        <Input
+          aria-label={`Keybinding for ${commandLabelText}`}
+          value={isRecording ? "" : keyDraft}
+          placeholder={isRecording ? "Press shortcut" : "Unassigned"}
+          className={cn(
+            "h-7 w-44 rounded-md font-mono text-[12px] sm:h-7",
+            isRecording && "border-primary/70 bg-primary/5",
+          )}
+          onFocus={() => setDraft({ isRecording: true })}
+          onBlur={() => setDraft({ isRecording: false })}
+          onChange={(event) => setDraft({ keyDraft: event.currentTarget.value })}
+          onKeyDown={captureKeybinding}
+        />
+        <Button
+          size="xs"
+          className="h-7 sm:h-7"
+          disabled={isSaving || !commandDraft || keyDraft.trim().length === 0 || !isWhenDraftValid}
+          onClick={save}
+        >
+          {isSaving ? "Saving" : "Save"}
+        </Button>
+      </div>
+      <div className="pr-4">
+        <Popover>
+          <PopoverTrigger
+            className={cn(
+              "inline-flex h-7 w-full items-center justify-between gap-2 rounded-md border border-input bg-background px-2.5 text-left font-mono text-[12px] text-foreground shadow-xs/5 outline-none transition-colors hover:bg-accent focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/24",
+              !whenDraftExpression && "text-muted-foreground",
+            )}
+            aria-label={`Edit when clause for ${commandLabelText}`}
+          >
+            <span className="truncate">{whenDraftExpression || "Always"}</span>
+            <ChevronDownIcon className="size-3.5 shrink-0 opacity-60" />
+          </PopoverTrigger>
+          <PopoverContent align="start" sideOffset={6}>
+            <WhenExpressionBuilder
+              value={whenDraft}
+              variables={variables}
+              onChange={(nextWhenDraft) => setDraft({ whenDraft: nextWhenDraft })}
+              onValidityChange={(nextIsValid) => setDraft({ isWhenDraftValid: nextIsValid })}
+            />
+          </PopoverContent>
+        </Popover>
+      </div>
+      <div className="flex items-center justify-end gap-1">
+        <KeybindingConflictWarning labels={conflictLabels} />
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-sm"
+                className="size-7 text-muted-foreground hover:text-foreground sm:size-7"
+                disabled={isSaving}
+                aria-label="Cancel new keybinding"
+                onClick={onCancel}
+              />
+            }
+          >
+            <XIcon className="size-3.5" />
+          </TooltipTrigger>
+          <TooltipPopup side="top">Cancel</TooltipPopup>
+        </Tooltip>
+      </div>
+    </div>
+  );
+}
+
+export function KeybindingsSettingsPanel() {
+  const keybindings = useServerKeybindings();
+  const keybindingsConfigPath = useServerKeybindingsConfigPath();
+  const [query, setQuery] = useState("");
+  const [isSearchOpen, setIsSearchOpen] = useState(false);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const [savingCommand, setSavingCommand] = useState<KeybindingCommand | null>(null);
+  const [isAddingBinding, setIsAddingBinding] = useState(false);
+  const rows = useMemo(() => buildKeybindingRows(keybindings, query), [keybindings, query]);
+  const commandOptions = useMemo(() => buildKeybindingCommandOptions(keybindings), [keybindings]);
+  const whenVariables = useMemo(() => buildWhenVariableOptions(), []);
+
+  useEffect(() => {
+    const handleKeyDown = (event: globalThis.KeyboardEvent) => {
+      const isMod = event.metaKey || event.ctrlKey;
+      if (!isMod || event.altKey || event.key.toLowerCase() !== "f") return;
+
+      const target = event.target;
+      if (
+        target !== searchInputRef.current &&
+        target instanceof HTMLElement &&
+        (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable)
+      ) {
+        return;
+      }
+
+      event.preventDefault();
+      setIsSearchOpen(true);
+      requestAnimationFrame(() => {
+        searchInputRef.current?.focus();
+        searchInputRef.current?.select();
+      });
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, []);
+
+  const openKeybindingsFile = useCallback(() => {
+    if (!keybindingsConfigPath) return;
+    void openInPreferredEditor(ensureLocalApi(), keybindingsConfigPath).catch((error: unknown) => {
+      toastManager.add({
+        title: "Unable to open keybindings file",
+        description:
+          error instanceof Error ? error.message : "The keybindings file was not opened.",
+        type: "error",
+      });
+    });
+  }, [keybindingsConfigPath]);
+
+  const saveKeybinding = useCallback((input: ServerUpsertKeybindingInput) => {
+    setSavingCommand(input.command);
+    const payload: ServerUpsertKeybindingInput = {
+      command: input.command,
+      key: input.key.trim(),
+      ...(input.when?.trim() ? { when: input.when.trim() } : {}),
+      ...(input.replace ? { replace: input.replace } : {}),
+    };
+    void ensureLocalApi()
+      .server.upsertKeybinding(payload)
+      .then(() => {
+        setIsAddingBinding(false);
+      })
+      .catch((error: unknown) => {
+        toastManager.add({
+          title: "Unable to save keybinding",
+          description: error instanceof Error ? error.message : "The keybinding was not saved.",
+          type: "error",
+        });
+      })
+      .finally(() => {
+        setSavingCommand(null);
+      });
+  }, []);
+
+  const removeKeybinding = useCallback((row: KeybindingRow) => {
+    setSavingCommand(row.command);
+    void ensureLocalApi()
+      .server.removeKeybinding(rowKeybindingTarget(row))
+      .catch((error: unknown) => {
+        toastManager.add({
+          title: "Unable to remove keybinding",
+          description: error instanceof Error ? error.message : "The keybinding was not removed.",
+          type: "error",
+        });
+      })
+      .finally(() => {
+        setSavingCommand(null);
+      });
+  }, []);
+
+  const resetKeybinding = useCallback(
+    (row: KeybindingRow) => {
+      if (!row.defaultKey) return;
+      saveKeybinding({
+        command: row.command,
+        key: row.defaultKey,
+        when: row.defaultWhen.trim().length > 0 ? row.defaultWhen : undefined,
+        replace: {
+          command: row.command,
+          key: row.key,
+          ...(row.when.trim().length > 0 ? { when: row.when } : {}),
+        },
+      });
+    },
+    [saveKeybinding],
+  );
+
+  const bindingsCount = (
+    <span className="text-[11px] text-muted-foreground">
+      {rows.length + (isAddingBinding ? 1 : 0)}{" "}
+      {rows.length + (isAddingBinding ? 1 : 0) === 1 ? "binding" : "bindings"}
+    </span>
+  );
+
+  return (
+    <SettingsPageContainer className="max-w-5xl">
+      <SettingsSection
+        title="Keybindings"
+        headerAction={
+          <div className="flex items-center gap-1.5">
+            <ExpandableHeaderSearch
+              query={query}
+              onChange={setQuery}
+              isOpen={isSearchOpen}
+              onOpenChange={setIsSearchOpen}
+              inputRef={searchInputRef}
+              collapsedAccessory={bindingsCount}
+            />
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <Button
+                    type="button"
+                    size="icon-xs"
+                    variant="ghost"
+                    className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                    onClick={() => setIsAddingBinding(true)}
+                    aria-label="Add keybinding"
+                  >
+                    <PlusIcon className="size-3" />
+                  </Button>
+                }
+              />
+              <TooltipPopup side="top">Add keybinding</TooltipPopup>
+            </Tooltip>
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <Button
+                    type="button"
+                    size="icon-xs"
+                    variant="ghost"
+                    className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                    disabled={!keybindingsConfigPath}
+                    onClick={openKeybindingsFile}
+                    aria-label="Open keybindings.json"
+                  >
+                    <FileJsonIcon className="size-3" />
+                  </Button>
+                }
+              />
+              <TooltipPopup side="top">Open keybindings.json</TooltipPopup>
+            </Tooltip>
+          </div>
+        }
+      >
+        {!isElectron ? (
+          <div className="flex items-start gap-2 border-b border-warning/20 bg-warning/5 px-3 py-2.5 text-[12px] leading-relaxed text-muted-foreground sm:px-4">
+            <InfoIcon className="mt-0.5 size-3.5 shrink-0 text-warning" />
+            <p>
+              Some shortcuts may be claimed by the browser before T3 Code sees them. Use the desktop
+              app for better keybinding support.
+            </p>
+          </div>
+        ) : null}
+
+        <ScrollArea
+          chainVerticalScroll
+          scrollFade
+          hideScrollbars
+          className="w-full max-w-full rounded-none"
+        >
+          <div className="grid min-w-[680px] grid-cols-[minmax(190px,1.1fr)_minmax(220px,0.85fr)_minmax(210px,1fr)_60px] border-b border-border/70 bg-muted/25 px-4 py-2 text-[11px] font-semibold uppercase tracking-[0.07em] text-muted-foreground">
+            <div>Command</div>
+            <div>Keybinding</div>
+            <div>When</div>
+            <div>Status</div>
+          </div>
+          <div className="min-w-[680px] divide-y divide-border/60">
+            {isAddingBinding ? (
+              <NewKeybindingTableRow
+                commandOptions={commandOptions}
+                allRows={rows}
+                variables={whenVariables}
+                isSaving={savingCommand !== null}
+                onSave={saveKeybinding}
+                onCancel={() => setIsAddingBinding(false)}
+              />
+            ) : null}
+            {rows.map((row) => (
+              <KeybindingTableRow
+                key={row.id}
+                row={row}
+                allRows={rows}
+                variables={whenVariables}
+                isSaving={savingCommand === row.command}
+                onSave={saveKeybinding}
+                onReset={resetKeybinding}
+                onRemove={removeKeybinding}
+              />
+            ))}
+            {rows.length === 0 && !isAddingBinding ? (
+              <div className="px-4 py-12 text-center text-sm text-muted-foreground">
+                No keybindings match your search.
+              </div>
+            ) : null}
+          </div>
+        </ScrollArea>
+      </SettingsSection>
+    </SettingsPageContainer>
+  );
+}
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.test.ts b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
new file mode 100644
index 00000000000..1aa062c9d68
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import type { ServerProviderModel } from "@t3tools/contracts";
+
+import { deriveProviderModelsForDisplay } from "./ProviderInstanceCard";
+
+describe("deriveProviderModelsForDisplay", () => {
+  it("uses current config custom models instead of stale live custom rows", () => {
+    const liveModels: ReadonlyArray<ServerProviderModel> = [
+      {
+        slug: "server-model",
+        name: "Server Model",
+        isCustom: false,
+        capabilities: null,
+      },
+      {
+        slug: "removed-custom",
+        name: "Removed Custom",
+        isCustom: true,
+        capabilities: null,
+      },
+      {
+        slug: "kept-custom",
+        name: "Kept Custom",
+        isCustom: true,
+        capabilities: null,
+      },
+    ];
+
+    expect(
+      deriveProviderModelsForDisplay({
+        liveModels,
+        customModels: ["kept-custom"],
+      }).map((model) => model.slug),
+    ).toEqual(["server-model", "kept-custom"]);
+  });
+});
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
new file mode 100644
index 00000000000..430ec3637e0
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -0,0 +1,875 @@
+"use client";
+
+import {
+  ArrowUpCircleIcon,
+  ChevronDownIcon,
+  CopyIcon,
+  DownloadIcon,
+  LoaderIcon,
+  PlusIcon,
+  Trash2Icon,
+  XIcon,
+} from "lucide-react";
+import { useEffect, useState, type ReactNode } from "react";
+import {
+  isProviderDriverKind,
+  type ProviderInstanceConfig,
+  type ProviderInstanceEnvironmentVariable,
+  type ProviderInstanceId,
+  type ProviderDriverKind,
+  type ServerProvider,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+
+import { cn } from "../../lib/utils";
+import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
+import { normalizeProviderAccentColor } from "../../providerInstances";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import { Collapsible, CollapsibleContent } from "../ui/collapsible";
+import { DraftInput } from "../ui/draft-input";
+import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
+import { ScrollArea } from "../ui/scroll-area";
+import { Switch } from "../ui/switch";
+import { stackedThreadToast, toastManager } from "../ui/toast";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import type { DriverOption } from "./providerDriverMeta";
+import { ProviderSettingsForm } from "./ProviderSettingsForm";
+import { ProviderModelsSection } from "./ProviderModelsSection";
+import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
+import { RedactedSensitiveText } from "./RedactedSensitiveText";
+import {
+  getProviderVersionAdvisoryPresentation,
+  PROVIDER_STATUS_STYLES,
+  getProviderSummary,
+  getProviderVersionLabel,
+  type ProviderStatusKey,
+} from "./providerStatus";
+
+const PROVIDER_ACCENT_SWATCHES = [
+  "#2563eb",
+  "#16a34a",
+  "#ea580c",
+  "#dc2626",
+  "#7c3aed",
+  "#0891b2",
+] as const;
+
+const ENVIRONMENT_VARIABLE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+let environmentVariableDraftId = 0;
+const nextEnvironmentVariableDraftId = () => `provider-env-${environmentVariableDraftId++}`;
+
+type EnvironmentDraftRow = {
+  readonly id: string;
+  readonly name: string;
+  readonly value: string;
+  readonly sensitive: boolean;
+  readonly valueRedacted?: boolean;
+};
+
+function makeEnvironmentDraftRow(
+  variable: ProviderInstanceEnvironmentVariable,
+  index: number,
+): EnvironmentDraftRow {
+  return {
+    id: `${index}:${variable.name}`,
+    name: variable.name,
+    value: variable.value,
+    sensitive: variable.sensitive,
+    ...(variable.valueRedacted !== undefined ? { valueRedacted: variable.valueRedacted } : {}),
+  };
+}
+
+/**
+ * Read a string[] at `key` from the opaque config blob, filtering out
+ * non-string entries. Used for `customModels`, which is always typed as
+ * `string[]` by the concrete driver schemas but arrives here as
+ * `Schema.Unknown`.
+ */
+function readConfigStringArray(config: unknown, key: string): ReadonlyArray<string> {
+  if (config === null || typeof config !== "object") return [];
+  const value = (config as Record<string, unknown>)[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+/**
+ * Set `key` to an arbitrary value on the opaque config blob. Unlike
+ * provider settings field updates, does not drop empty-looking values — the
+ * caller is responsible for deciding whether an empty array / empty
+ * object should be stored explicitly (e.g. `customModels: []` is a
+ * meaningful "user cleared their custom list" state distinct from
+ * "driver default").
+ */
+function nextConfigBlobWithValue(
+  config: unknown,
+  key: string,
+  value: unknown,
+): Record<string, unknown> {
+  const base: Record<string, unknown> =
+    config !== null && typeof config === "object" ? { ...(config as Record<string, unknown>) } : {};
+  base[key] = value;
+  return base;
+}
+
+export function deriveProviderModelsForDisplay(input: {
+  readonly liveModels: ReadonlyArray<ServerProviderModel> | undefined;
+  readonly customModels: ReadonlyArray<string>;
+}): ReadonlyArray<ServerProviderModel> {
+  const liveCustomModelsBySlug = new Map(
+    (input.liveModels ?? [])
+      .filter((model) => model.isCustom)
+      .map((model) => [model.slug, model] as const),
+  );
+  const serverModels = input.liveModels?.filter((model) => !model.isCustom) ?? [];
+  const customModels = input.customModels.map(
+    (slug) =>
+      liveCustomModelsBySlug.get(slug) ?? {
+        slug,
+        name: slug,
+        isCustom: true,
+        capabilities: null,
+      },
+  );
+  return [...serverModels, ...customModels];
+}
+
+function ProviderAuthEmail(props: {
+  readonly email: string | undefined;
+  readonly prefix?: string;
+  readonly separator?: boolean;
+}) {
+  const trimmed = props.email?.trim();
+  if (!trimmed) return null;
+
+  return (
+    <span className="inline-flex min-w-0 items-center gap-1.5">
+      {props.separator ? <span aria-hidden>·</span> : null}
+      {props.prefix ? <span className="text-muted-foreground/80">{props.prefix}</span> : null}
+      <RedactedSensitiveText
+        value={trimmed}
+        ariaLabel="Toggle account email visibility"
+        revealTooltip="Click to reveal email"
+        hideTooltip="Click to hide email"
+      />
+    </span>
+  );
+}
+
+function ProviderAccentColorPicker(props: {
+  readonly displayName: string;
+  readonly value: string | undefined;
+  readonly onCommit: (value: string) => void;
+}) {
+  const [draft, setDraft] = useState(props.value ?? "");
+  const [isEditing, setIsEditing] = useState(false);
+  const draftColor = normalizeProviderAccentColor(draft);
+
+  useEffect(() => {
+    if (isEditing) return;
+    setDraft(props.value ?? "");
+  }, [isEditing, props.value]);
+
+  const commitDraft = () => {
+    setIsEditing(false);
+    props.onCommit(draftColor ?? "");
+  };
+
+  const commitSwatch = (swatch: string) => {
+    setIsEditing(false);
+    setDraft(swatch);
+    props.onCommit(swatch);
+  };
+
+  return (
+    <div className="grid gap-2">
+      <span className="text-xs font-medium text-foreground">Accent color</span>
+      <div className="flex min-w-0 flex-wrap items-center gap-2">
+        <input
+          type="color"
+          value={draftColor ?? PROVIDER_ACCENT_SWATCHES[0]}
+          onFocus={() => setIsEditing(true)}
+          onInput={(event) => {
+            setIsEditing(true);
+            setDraft(event.currentTarget.value);
+          }}
+          onChange={(event) => {
+            setIsEditing(true);
+            setDraft(event.currentTarget.value);
+          }}
+          onBlur={commitDraft}
+          aria-label={`Accent color for ${props.displayName}`}
+          className="h-8 w-10 cursor-pointer rounded border border-input bg-background p-0.5"
+        />
+        <div className="flex flex-wrap gap-1.5">
+          {PROVIDER_ACCENT_SWATCHES.map((swatch) => {
+            const selected = draftColor?.toLowerCase() === swatch;
+            return (
+              <button
+                key={swatch}
+                type="button"
+                className={cn(
+                  "size-6 cursor-pointer rounded-full border transition",
+                  selected
+                    ? "border-foreground ring-2 ring-ring ring-offset-1 ring-offset-background"
+                    : "border-black/10 hover:scale-105 dark:border-white/20",
+                )}
+                style={{ backgroundColor: swatch }}
+                onClick={() => commitSwatch(swatch)}
+                aria-label={`Use ${swatch} accent`}
+              />
+            );
+          })}
+        </div>
+        {draftColor ? (
+          <Button
+            type="button"
+            size="sm"
+            variant="ghost"
+            className="h-7 px-2 text-xs text-muted-foreground"
+            onClick={() => {
+              setIsEditing(false);
+              setDraft("");
+              props.onCommit("");
+            }}
+          >
+            Clear
+          </Button>
+        ) : null}
+      </div>
+      <span className="text-xs text-muted-foreground">
+        Used to distinguish this instance in picker rails and model lists.
+      </span>
+    </div>
+  );
+}
+
+function ProviderEnvironmentSection(props: {
+  readonly environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>;
+  readonly onChange: (environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>) => void;
+}) {
+  const [rows, setRows] = useState<ReadonlyArray<EnvironmentDraftRow>>(() =>
+    props.environment.map(makeEnvironmentDraftRow),
+  );
+
+  useEffect(() => {
+    setRows(props.environment.map(makeEnvironmentDraftRow));
+  }, [props.environment]);
+
+  const publishRows = (nextRows: ReadonlyArray<EnvironmentDraftRow>) => {
+    const published: ProviderInstanceEnvironmentVariable[] = [];
+    for (const row of nextRows) {
+      const name = row.name.trim();
+      if (!ENVIRONMENT_VARIABLE_NAME_PATTERN.test(name)) {
+        if (
+          name.length > 0 ||
+          row.value.length > 0 ||
+          row.sensitive !== true ||
+          row.valueRedacted !== undefined
+        ) {
+          return;
+        }
+        continue;
+      }
+      const { id: _id, ...rest } = row;
+      published.push({ ...rest, name });
+    }
+    props.onChange(published);
+  };
+
+  const updateVariable = (id: string, patch: Partial<Omit<EnvironmentDraftRow, "id">>) => {
+    const nextRows = rows.map((row) =>
+      row.id === id
+        ? {
+            ...row,
+            ...patch,
+            ...(patch.value !== undefined ? { valueRedacted: false } : {}),
+          }
+        : row,
+    );
+    setRows(nextRows);
+    publishRows(nextRows);
+  };
+
+  const removeVariable = (id: string) => {
+    const nextRows = rows.filter((row) => row.id !== id);
+    setRows(nextRows);
+    publishRows(nextRows);
+  };
+
+  return (
+    <div className="grid gap-2">
+      <div className="flex items-center justify-between gap-3">
+        <span className="text-xs font-medium text-foreground">Environment variables</span>
+        <Button
+          type="button"
+          size="sm"
+          variant="outline"
+          className="h-7 gap-1.5 px-2 text-xs"
+          onClick={() =>
+            setRows([
+              ...rows,
+              {
+                id: nextEnvironmentVariableDraftId(),
+                name: "",
+                value: "",
+                sensitive: true,
+              },
+            ])
+          }
+        >
+          <PlusIcon className="size-3" />
+          Add
+        </Button>
+      </div>
+      {rows.length === 0 ? (
+        <p className="text-xs text-muted-foreground">
+          Add variables to pass API keys, base URLs, or other per-instance CLI settings.
+        </p>
+      ) : (
+        <div className="grid gap-2">
+          {rows.map((variable, index) => (
+            <div
+              key={variable.id}
+              className="grid gap-2 rounded-md border border-border/70 bg-muted/20 p-2 sm:grid-cols-[minmax(0,1fr)_minmax(0,1.4fr)_auto_auto] sm:items-center"
+            >
+              <DraftInput
+                value={variable.name}
+                onCommit={(name) => updateVariable(variable.id, { name: name.trim() })}
+                placeholder="VARIABLE_NAME"
+                spellCheck={false}
+                aria-label={`Environment variable name ${index + 1}`}
+              />
+              <DraftInput
+                value={variable.valueRedacted ? "" : variable.value}
+                onCommit={(value) => updateVariable(variable.id, { value })}
+                type={variable.sensitive ? "password" : undefined}
+                autoComplete="off"
+                placeholder={
+                  variable.valueRedacted ? "Stored secret - enter a new value to replace" : "Value"
+                }
+                spellCheck={false}
+                aria-label={`Environment variable value ${index + 1}`}
+              />
+              <label className="inline-flex h-8 items-center gap-2 text-xs text-muted-foreground">
+                <input
+                  type="checkbox"
+                  className="size-3.5"
+                  checked={variable.sensitive}
+                  onChange={(event) => {
+                    const sensitive = event.currentTarget.checked;
+                    updateVariable(variable.id, {
+                      sensitive,
+                      ...(sensitive && variable.valueRedacted === undefined
+                        ? {}
+                        : { valueRedacted: sensitive ? variable.valueRedacted : false }),
+                    });
+                  }}
+                />
+                Sensitive
+              </label>
+              <Button
+                type="button"
+                size="icon-sm"
+                variant="ghost"
+                className="size-8 justify-self-start text-muted-foreground hover:text-destructive sm:justify-self-end"
+                onClick={() => removeVariable(variable.id)}
+                aria-label={`Remove environment variable ${variable.name || index + 1}`}
+              >
+                <XIcon className="size-3.5" />
+              </Button>
+            </div>
+          ))}
+        </div>
+      )}
+      <span className="text-xs text-muted-foreground">
+        Sensitive values are stored separately and are not returned to the app after saving.
+      </span>
+    </div>
+  );
+}
+
+interface ProviderInstanceCardProps {
+  readonly instanceId: ProviderInstanceId;
+  readonly instance: ProviderInstanceConfig;
+  readonly driverOption: DriverOption | undefined;
+  readonly liveProvider: ServerProvider | undefined;
+  readonly isExpanded: boolean;
+  readonly onExpandedChange: (open: boolean) => void;
+  readonly onUpdate: (nextInstance: ProviderInstanceConfig) => void;
+  /**
+   * Pass `undefined` to hide the delete button entirely. Built-in default
+   * instance slots use `undefined` — they can't be deleted without losing
+   * the slot, and their "reset to defaults" affordance lives on an outer
+   * reset button instead. Explicit `| undefined` in the type accommodates
+   * `exactOptionalPropertyTypes: true`, where an absent key and
+   * `{ onDelete: undefined }` are treated as distinct shapes.
+   */
+  readonly onDelete?: (() => void) | undefined;
+  /**
+   * Optional outer reset button rendered next to the driver icon. Built-in
+   * default slots supply a reset-to-factory control here; custom instances
+   * omit it.
+   */
+  readonly headerAction?: ReactNode | undefined;
+  readonly hiddenModels: ReadonlyArray<string>;
+  readonly favoriteModels: ReadonlyArray<string>;
+  readonly modelOrder: ReadonlyArray<string>;
+  readonly onHiddenModelsChange: (next: ReadonlyArray<string>) => void;
+  readonly onFavoriteModelsChange: (next: ReadonlyArray<string>) => void;
+  readonly onModelOrderChange: (next: ReadonlyArray<string>) => void;
+  readonly onRunUpdate?: (() => void) | undefined;
+  readonly isUpdating?: boolean | undefined;
+}
+
+/**
+ * A single configured provider-instance row in the Providers settings
+ * section. Used for every row — both the built-in default instance for a
+ * driver (rendered with `onDelete` omitted) and user-authored custom
+ * instances (`onDelete` supplied). The only UI difference between the two
+ * is whether the trash button is visible; every other field (display
+ * name, config fields, models) behaves identically.
+ *
+ * Behavior notes:
+ *   - `liveProvider` is matched by the caller via `instanceId`; when no
+ *     match is available (e.g. the server hasn't probed yet, or the
+ *     driver is not shipped by the current build) the card still renders
+ *     with a neutral "checking" summary.
+ *   - Unknown drivers (`driverOption === undefined`) get a read-only
+ *     notice instead of editable fields, so fork instances round-trip
+ *     without accidentally destroying their config.
+ *   - The enabled Switch writes to the envelope's `instance.enabled`
+ *     field; the server's registry consults this at `entry.enabled ?? true`
+ *     before materializing the instance, and the probe also checks its
+ *     driver-specific `config.enabled`. We treat the envelope flag as the
+ *     single source of truth from the UI — built-in cards used to write
+ *     the inner flag, but on the promotion-to-instance path every edit
+ *     flows through the envelope.
+ */
+export function ProviderInstanceCard({
+  instanceId,
+  instance,
+  driverOption,
+  liveProvider,
+  isExpanded,
+  onExpandedChange,
+  onUpdate,
+  onDelete,
+  headerAction,
+  hiddenModels,
+  favoriteModels,
+  modelOrder,
+  onHiddenModelsChange,
+  onFavoriteModelsChange,
+  onModelOrderChange,
+  onRunUpdate,
+  isUpdating = false,
+}: ProviderInstanceCardProps) {
+  const enabled = instance.enabled ?? true;
+  // The server-reported status wins when present; otherwise fall back to
+  // "disabled"/"warning" based on the local `enabled` flag so the dot
+  // reflects the persisted intent even before the first probe completes.
+  const statusKey: ProviderStatusKey =
+    (liveProvider?.status as ProviderStatusKey | undefined) ?? (enabled ? "warning" : "disabled");
+  const statusStyle = PROVIDER_STATUS_STYLES[statusKey];
+  const rawSummary = getProviderSummary(liveProvider);
+  const authEmail = liveProvider?.auth.email;
+  const hasAuthenticatedEmail =
+    liveProvider?.auth.status === "authenticated" && Boolean(authEmail?.trim());
+  const authenticatedDetail = hasAuthenticatedEmail
+    ? (liveProvider?.auth.label ?? liveProvider?.auth.type ?? null)
+    : null;
+  const summary = rawSummary;
+  const versionLabel = getProviderVersionLabel(liveProvider?.version);
+  const versionAdvisory = getProviderVersionAdvisoryPresentation(liveProvider?.versionAdvisory);
+  const updateCommand = versionAdvisory?.updateCommand ?? null;
+  const FallbackIconComponent = driverOption?.icon;
+  const displayName =
+    instance.displayName?.trim() || driverOption?.label || String(instance.driver);
+  const accentColor = normalizeProviderAccentColor(instance.accentColor);
+  const { copyToClipboard } = useCopyToClipboard<{ providerName: string }>({
+    onCopy: ({ providerName }) => {
+      toastManager.add({
+        type: "success",
+        title: `${providerName} update command copied`,
+        description: "Run it in a terminal when you are ready to update.",
+      });
+    },
+    onError: (error, { providerName }) => {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: `Could not copy ${providerName} update command`,
+          description: error.message,
+        }),
+      );
+    },
+  });
+
+  // Narrow `instance.driver` for callers that key on the closed
+  // `ProviderDriverKind` union (e.g. `normalizeModelSlug`'s alias table). Custom
+  // fork drivers pass through as `null` and those callers fall back to
+  // verbatim behaviour.
+  const driverKind: ProviderDriverKind | null = isProviderDriverKind(instance.driver)
+    ? instance.driver
+    : null;
+
+  const customModels = readConfigStringArray(instance.config, "customModels");
+  // Server-returned models may lag behind settings writes. Treat probe
+  // models as the source for built-ins only; custom rows come directly
+  // from the current instance config so add/remove reflects immediately.
+  const modelsForDisplay = deriveProviderModelsForDisplay({
+    liveModels: liveProvider?.models,
+    customModels,
+  });
+
+  const updateDisplayName = (value: string) => {
+    const trimmed = value.trim();
+    const { displayName: _omit, ...rest } = instance;
+    onUpdate(
+      trimmed.length > 0
+        ? ({ ...rest, displayName: trimmed } as ProviderInstanceConfig)
+        : (rest as ProviderInstanceConfig),
+    );
+  };
+
+  const updateEnabled = (value: boolean) => {
+    onUpdate({ ...instance, enabled: value });
+  };
+
+  const updateAccentColor = (value: string) => {
+    const normalized = normalizeProviderAccentColor(value);
+    const { accentColor: _omit, ...rest } = instance;
+    onUpdate(
+      normalized
+        ? ({ ...rest, accentColor: normalized } as ProviderInstanceConfig)
+        : (rest as ProviderInstanceConfig),
+    );
+  };
+
+  const updateConfig = (nextConfig: Record<string, unknown> | undefined) => {
+    const { config: _omit, ...rest } = instance;
+    onUpdate(
+      nextConfig !== undefined
+        ? ({ ...rest, config: nextConfig } as ProviderInstanceConfig)
+        : (rest as ProviderInstanceConfig),
+    );
+  };
+
+  const updateCustomModels = (next: ReadonlyArray<string>) => {
+    const nextConfig = nextConfigBlobWithValue(instance.config, "customModels", [...next]);
+    const { config: _omit, ...rest } = instance;
+    onUpdate({ ...rest, config: nextConfig } as ProviderInstanceConfig);
+  };
+
+  const updateEnvironment = (environment: ReadonlyArray<ProviderInstanceEnvironmentVariable>) => {
+    const cleaned = environment.filter((variable) => variable.name.trim().length > 0);
+    const { environment: _omit, ...rest } = instance;
+    onUpdate(
+      cleaned.length > 0
+        ? ({ ...rest, environment: cleaned } as ProviderInstanceConfig)
+        : (rest as ProviderInstanceConfig),
+    );
+  };
+
+  const titleIconNode = driverKind ? (
+    <ProviderInstanceIcon
+      driverKind={driverKind}
+      displayName={displayName}
+      accentColor={accentColor}
+      showBadge={Boolean(accentColor)}
+      statusDotClassName={statusStyle.dot}
+      className="size-5"
+      iconClassName="size-4 text-foreground/80"
+      badgeClassName="right-[-0.125rem] bottom-[-0.125rem] h-3 min-w-3 text-[7px]"
+    />
+  ) : FallbackIconComponent ? (
+    <span className="relative inline-flex size-5 shrink-0 items-center justify-center">
+      <FallbackIconComponent className="size-4 text-foreground/80" aria-hidden />
+      <span
+        className={cn(
+          "pointer-events-none absolute -left-0.5 -top-0.5 size-2 rounded-full ring-2 ring-background",
+          statusStyle.dot,
+        )}
+        aria-hidden
+      />
+    </span>
+  ) : (
+    <span className={cn("size-2 shrink-0 rounded-full", statusStyle.dot)} />
+  );
+
+  const titleHeadNode = (
+    <>
+      {titleIconNode}
+      <h3 className="truncate text-[13px] font-semibold tracking-[-0.01em] text-foreground">
+        {displayName}
+      </h3>
+      {String(instanceId) !== String(instance.driver) ? (
+        <code className="truncate rounded bg-muted/60 px-1 py-0.5 text-[10px] text-muted-foreground">
+          {instanceId}
+        </code>
+      ) : null}
+      {driverOption?.badgeLabel ? (
+        <Badge variant="warning" size="sm" className="shrink-0">
+          {driverOption.badgeLabel}
+        </Badge>
+      ) : null}
+    </>
+  );
+
+  const titleTailNode = (
+    <>
+      {headerAction ? (
+        <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center">
+          {headerAction}
+        </span>
+      ) : null}
+      {onDelete ? (
+        <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center">
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <Button
+                  size="icon-xs"
+                  variant="ghost"
+                  className="size-5 rounded-sm p-0 text-muted-foreground hover:text-destructive"
+                  onClick={onDelete}
+                  aria-label={`Delete provider instance ${instanceId}`}
+                >
+                  <Trash2Icon className="size-3" />
+                </Button>
+              }
+            />
+            <TooltipPopup side="top">Delete instance</TooltipPopup>
+          </Tooltip>
+        </span>
+      ) : null}
+    </>
+  );
+
+  const authRowNode = (
+    <p className="flex min-w-0 flex-wrap items-center gap-x-1 text-xs text-muted-foreground/80">
+      {hasAuthenticatedEmail ? (
+        <>
+          <span>Authenticated as</span>
+          <ProviderAuthEmail email={authEmail} />
+          {authenticatedDetail ? <span>· {authenticatedDetail}</span> : null}
+        </>
+      ) : (
+        <>
+          <span>{summary.headline}</span>
+          <ProviderAuthEmail email={authEmail} separator prefix="Email" />
+        </>
+      )}
+      {summary.detail ? <span>- {summary.detail}</span> : null}
+    </p>
+  );
+
+  const versionCodeNode = versionLabel ? (
+    <code className="text-xs text-muted-foreground">{versionLabel}</code>
+  ) : null;
+
+  return (
+    <div className="border-t border-border/60 first:border-t-0">
+      <div className="px-4 py-3.5 sm:px-5">
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <div className="min-w-0 flex-1 space-y-1">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              {titleHeadNode}
+              {versionCodeNode}
+              {versionAdvisory ? (
+                <Popover>
+                  <PopoverTrigger
+                    render={
+                      <Button
+                        type="button"
+                        size="icon-xs"
+                        variant="ghost"
+                        className={cn(
+                          "size-5 rounded-sm p-0",
+                          versionAdvisory.emphasis === "strong"
+                            ? "text-warning hover:text-warning"
+                            : "text-primary hover:text-primary",
+                        )}
+                        aria-label="Update available — view details"
+                      >
+                        <ArrowUpCircleIcon className="size-3.5 [animation:bounce_2.4s_ease-in-out_infinite] motion-reduce:animate-none" />
+                      </Button>
+                    }
+                  />
+                  <PopoverPopup
+                    side="bottom"
+                    align="start"
+                    className="w-[min(21rem,calc(100vw-1.5rem))] [--popup-width:min(21rem,calc(100vw-1.5rem))]"
+                  >
+                    <div className="grid min-w-0 gap-3">
+                      <div className="grid gap-0.5">
+                        <p className="text-[13px] font-semibold leading-tight text-foreground">
+                          Update available
+                        </p>
+                        <p
+                          className={cn(
+                            "text-xs leading-snug",
+                            versionAdvisory.emphasis === "strong"
+                              ? "text-warning"
+                              : "text-muted-foreground",
+                          )}
+                        >
+                          {versionAdvisory.detail}
+                        </p>
+                      </div>
+                      {onRunUpdate ? (
+                        <Button
+                          type="button"
+                          size="xs"
+                          variant="default"
+                          className="w-full"
+                          disabled={isUpdating}
+                          onClick={onRunUpdate}
+                        >
+                          {isUpdating ? <LoaderIcon className="animate-spin" /> : <DownloadIcon />}
+                          {isUpdating ? "Updating" : "Update now"}
+                        </Button>
+                      ) : null}
+                      {onRunUpdate && updateCommand ? (
+                        <div className="flex items-center gap-2 text-[10px] font-medium uppercase tracking-wider text-muted-foreground">
+                          <span aria-hidden className="h-px flex-1 bg-border" />
+                          or, update manually using
+                          <span aria-hidden className="h-px flex-1 bg-border" />
+                        </div>
+                      ) : null}
+                      {updateCommand ? (
+                        <div className="flex min-w-0 items-center gap-1 rounded-md border border-border/70 bg-muted/40 py-0.5 pr-0.5 pl-2">
+                          <ScrollArea scrollFade className="h-8 min-w-0 flex-1 rounded-none">
+                            <code className="flex h-full w-max items-center whitespace-nowrap pr-3 font-mono text-[11px] text-foreground">
+                              {updateCommand}
+                            </code>
+                          </ScrollArea>
+                          <Tooltip>
+                            <TooltipTrigger
+                              render={
+                                <Button
+                                  type="button"
+                                  size="icon-xs"
+                                  variant="ghost"
+                                  className="size-6 shrink-0 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                                  onClick={() =>
+                                    copyToClipboard(updateCommand, {
+                                      providerName: displayName,
+                                    })
+                                  }
+                                  aria-label="Copy update command"
+                                >
+                                  <CopyIcon className="size-3" />
+                                </Button>
+                              }
+                            />
+                            <TooltipPopup side="top">Copy command</TooltipPopup>
+                          </Tooltip>
+                        </div>
+                      ) : null}
+                    </div>
+                  </PopoverPopup>
+                </Popover>
+              ) : null}
+              {titleTailNode}
+            </div>
+            {authRowNode}
+          </div>
+          <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
+            <Button
+              size="sm"
+              variant="ghost"
+              className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground"
+              onClick={() => onExpandedChange(!isExpanded)}
+              aria-label={`Toggle ${displayName} details`}
+            >
+              <ChevronDownIcon
+                className={cn("size-3.5 transition-transform", isExpanded && "rotate-180")}
+              />
+            </Button>
+            <Switch
+              checked={enabled}
+              onCheckedChange={(checked) => updateEnabled(Boolean(checked))}
+              aria-label={`Enable ${displayName}`}
+            />
+          </div>
+        </div>
+      </div>
+
+      <Collapsible open={isExpanded} onOpenChange={onExpandedChange}>
+        <CollapsibleContent>
+          <div className="space-y-0">
+            <div className="border-t border-border/60 px-4 py-3 sm:px-5">
+              <label htmlFor={`provider-instance-${instanceId}-display-name`} className="block">
+                <span className="text-xs font-medium text-foreground">Display name</span>
+                <DraftInput
+                  id={`provider-instance-${instanceId}-display-name`}
+                  className="mt-1.5"
+                  value={instance.displayName ?? ""}
+                  onCommit={updateDisplayName}
+                  placeholder={driverOption?.label ?? "Instance label"}
+                  spellCheck={false}
+                />
+                <span className="mt-1 block text-xs text-muted-foreground">
+                  Optional label shown in the provider list.
+                </span>
+              </label>
+            </div>
+
+            <div className="border-t border-border/60 px-4 py-3 sm:px-5">
+              <ProviderAccentColorPicker
+                displayName={displayName}
+                value={accentColor}
+                onCommit={updateAccentColor}
+              />
+            </div>
+
+            <div className="border-t border-border/60 px-4 py-3 sm:px-5">
+              <ProviderEnvironmentSection
+                environment={instance.environment ?? []}
+                onChange={updateEnvironment}
+              />
+            </div>
+
+            {driverOption ? (
+              <ProviderSettingsForm
+                definition={driverOption}
+                value={instance.config}
+                idPrefix={`provider-instance-${instanceId}`}
+                variant="card"
+                onChange={updateConfig}
+              />
+            ) : null}
+
+            {driverOption !== undefined ? (
+              <ProviderModelsSection
+                instanceId={instanceId}
+                driverKind={driverKind}
+                models={modelsForDisplay}
+                customModels={customModels}
+                hiddenModels={hiddenModels}
+                favoriteModels={favoriteModels}
+                modelOrder={modelOrder}
+                onChange={updateCustomModels}
+                onHiddenModelsChange={onHiddenModelsChange}
+                onFavoriteModelsChange={onFavoriteModelsChange}
+                onModelOrderChange={onModelOrderChange}
+              />
+            ) : (
+              <div className="border-t border-border/60 px-4 py-3 sm:px-5">
+                <p className="text-xs text-muted-foreground">
+                  This instance uses a driver (
+                  <code className="text-foreground">{String(instance.driver)}</code>) that is not
+                  shipped with the current build. Configuration values are preserved but cannot be
+                  edited from this surface.
+                </p>
+              </div>
+            )}
+          </div>
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/settings/ProviderModelsSection.tsx b/apps/web/src/components/settings/ProviderModelsSection.tsx
new file mode 100644
index 00000000000..5db713495b9
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderModelsSection.tsx
@@ -0,0 +1,411 @@
+"use client";
+
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  EyeIcon,
+  EyeOffIcon,
+  InfoIcon,
+  PlusIcon,
+  StarIcon,
+  XIcon,
+} from "lucide-react";
+import { useMemo, useRef, useState } from "react";
+import {
+  ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+import { normalizeModelSlug } from "@t3tools/shared/model";
+
+import { cn } from "../../lib/utils";
+import { sortModelsForProviderInstance } from "../../modelOrdering";
+import { MAX_CUSTOM_MODEL_LENGTH } from "../../modelSelection";
+import { Button } from "../ui/button";
+import { Input } from "../ui/input";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+
+/**
+ * Placeholder text for the "add a custom model" input, keyed by driver
+ * kind. Mirrors the prior hardcoded switch in `SettingsPanels.tsx` so the
+ * UX is unchanged — only the owning component has moved.
+ */
+const CUSTOM_MODEL_PLACEHOLDER_BY_KIND: Partial<Record<ProviderDriverKind, string>> = {
+  [ProviderDriverKind.make("codex")]: "gpt-6.7-codex-ultra-preview",
+  [ProviderDriverKind.make("claudeAgent")]: "claude-sonnet-5-0",
+  [ProviderDriverKind.make("cursor")]: "claude-sonnet-4-6",
+  [ProviderDriverKind.make("opencode")]: "openai/gpt-5",
+};
+
+interface ProviderModelsSectionProps {
+  /** Identifier used to namespace input ids within the DOM. */
+  readonly instanceId: ProviderInstanceId;
+  /**
+   * Driver kind for slug normalization + input placeholder. `null` when
+   * the section is rendered without enough provider metadata.
+   */
+  readonly driverKind: ProviderDriverKind | null;
+  /**
+   * The live model list to display. Includes both built-in (probe-reported)
+   * and custom entries, distinguished by `isCustom`.
+   */
+  readonly models: ReadonlyArray<ServerProviderModel>;
+  /**
+   * The persisted custom-model slug list for this instance. Drives dedup,
+   * and is the array we hand back verbatim (with the new slug appended /
+   * removed) via `onChange`.
+   */
+  readonly customModels: ReadonlyArray<string>;
+  /** Server-returned model slugs hidden from the model picker. */
+  readonly hiddenModels: ReadonlyArray<string>;
+  /** Model slugs favorited for this provider instance. */
+  readonly favoriteModels: ReadonlyArray<string>;
+  /** Explicit user-authored model ordering for this provider instance. */
+  readonly modelOrder: ReadonlyArray<string>;
+  /**
+   * Commit the new custom-model list. Caller is responsible for routing the
+   * write to the correct storage (legacy `settings.providers[kind]` vs.
+   * `providerInstances[id].config`).
+   */
+  readonly onChange: (next: ReadonlyArray<string>) => void;
+  readonly onHiddenModelsChange: (next: ReadonlyArray<string>) => void;
+  readonly onFavoriteModelsChange: (next: ReadonlyArray<string>) => void;
+  readonly onModelOrderChange: (next: ReadonlyArray<string>) => void;
+}
+
+/**
+ * Shared "Models" section rendered on both the built-in default and custom
+ * provider-instance cards. Owns its own input + error local state so two
+ * cards on screen don't fight over the input value.
+ *
+ * Validation mirrors the pre-consolidation logic in `SettingsPanels`:
+ *   - empty / whitespace → "Enter a model slug."
+ *   - duplicate of a non-custom (probe-reported) slug → "already built in"
+ *   - exceeds `MAX_CUSTOM_MODEL_LENGTH` → length error
+ *   - duplicate of an already-saved custom slug → already-saved error
+ */
+export function ProviderModelsSection({
+  instanceId,
+  driverKind,
+  models,
+  customModels,
+  hiddenModels,
+  favoriteModels,
+  modelOrder,
+  onChange,
+  onHiddenModelsChange,
+  onFavoriteModelsChange,
+  onModelOrderChange,
+}: ProviderModelsSectionProps) {
+  const [input, setInput] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const listRef = useRef<HTMLDivElement | null>(null);
+  const hiddenModelSet = useMemo(() => new Set(hiddenModels), [hiddenModels]);
+  const favoriteModelSet = useMemo(() => new Set(favoriteModels), [favoriteModels]);
+  const orderedModels = useMemo(() => {
+    return sortModelsForProviderInstance(models, {
+      favoriteModels: favoriteModelSet,
+      groupFavorites: true,
+      modelOrder,
+    });
+  }, [favoriteModelSet, modelOrder, models]);
+
+  const handleAdd = () => {
+    const normalized = driverKind ? normalizeModelSlug(input, driverKind) : input.trim() || null;
+    if (!normalized) {
+      setError("Enter a model slug.");
+      return;
+    }
+    if (models.some((model) => !model.isCustom && model.slug === normalized)) {
+      setError("That model is already built in.");
+      return;
+    }
+    if (normalized.length > MAX_CUSTOM_MODEL_LENGTH) {
+      setError(`Model slugs must be ${MAX_CUSTOM_MODEL_LENGTH} characters or less.`);
+      return;
+    }
+    if (customModels.includes(normalized)) {
+      setError("That custom model is already saved.");
+      return;
+    }
+
+    onChange([...customModels, normalized]);
+    setInput("");
+    setError(null);
+
+    // Scroll the new row into view once the DOM reflects the commit.
+    // `MutationObserver` handles the one-frame gap between `onChange` and
+    // the `models` prop update; the `requestAnimationFrame` covers the
+    // common case where the parent updates synchronously.
+    const el = listRef.current;
+    if (!el) return;
+    const scrollToEnd = () => el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+    requestAnimationFrame(scrollToEnd);
+    const observer = new MutationObserver(() => {
+      scrollToEnd();
+      observer.disconnect();
+    });
+    observer.observe(el, { childList: true, subtree: true });
+    setTimeout(() => observer.disconnect(), 2_000);
+  };
+
+  const handleRemove = (slug: string) => {
+    onChange(customModels.filter((model) => model !== slug));
+    onModelOrderChange(modelOrder.filter((model) => model !== slug));
+    onFavoriteModelsChange(favoriteModels.filter((model) => model !== slug));
+    setError(null);
+  };
+
+  const handleToggleHidden = (slug: string) => {
+    if (hiddenModelSet.has(slug)) {
+      onHiddenModelsChange(hiddenModels.filter((model) => model !== slug));
+      return;
+    }
+    onHiddenModelsChange([...hiddenModels, slug]);
+  };
+
+  const handleToggleFavorite = (slug: string) => {
+    if (favoriteModelSet.has(slug)) {
+      onFavoriteModelsChange(favoriteModels.filter((model) => model !== slug));
+      return;
+    }
+    onFavoriteModelsChange([...favoriteModels, slug]);
+  };
+
+  const handleMove = (slug: string, direction: -1 | 1) => {
+    const slugs = orderedModels.map((model) => model.slug);
+    const index = slugs.indexOf(slug);
+    const nextIndex = index + direction;
+    if (index < 0 || nextIndex < 0 || nextIndex >= slugs.length) {
+      return;
+    }
+    const next = [...slugs];
+    [next[index], next[nextIndex]] = [next[nextIndex]!, next[index]!];
+    onModelOrderChange(next);
+  };
+
+  return (
+    <div className="border-t border-border/60 px-4 py-3 sm:px-5">
+      <div className="text-xs font-medium text-foreground">Models</div>
+      <div className="mt-1 text-xs text-muted-foreground">
+        {models.length} model{models.length === 1 ? "" : "s"} available.
+      </div>
+      <div ref={listRef} className="mt-2 max-h-40 overflow-y-auto pb-1">
+        {orderedModels.map((model, index) => {
+          const caps = model.capabilities;
+          const capLabels: string[] = [];
+          const isHidden = !model.isCustom && hiddenModelSet.has(model.slug);
+          const isFavorite = favoriteModelSet.has(model.slug);
+          const previousModel = orderedModels[index - 1];
+          const nextModel = orderedModels[index + 1];
+          const canMoveUp =
+            previousModel !== undefined && favoriteModelSet.has(previousModel.slug) === isFavorite;
+          const canMoveDown =
+            nextModel !== undefined && favoriteModelSet.has(nextModel.slug) === isFavorite;
+          const descriptors = caps?.optionDescriptors ?? [];
+          if (descriptors.some((descriptor) => descriptor.id === "fastMode")) {
+            capLabels.push("Fast mode");
+          }
+          if (descriptors.some((descriptor) => descriptor.id === "thinking")) {
+            capLabels.push("Thinking");
+          }
+          if (
+            descriptors.some(
+              (descriptor) =>
+                descriptor.type === "select" &&
+                (descriptor.id === "reasoningEffort" ||
+                  descriptor.id === "effort" ||
+                  descriptor.id === "reasoning" ||
+                  descriptor.id === "variant"),
+            )
+          ) {
+            capLabels.push("Reasoning");
+          }
+          const hasDetails = capLabels.length > 0 || model.name !== model.slug;
+
+          return (
+            <div
+              key={`${instanceId}:${model.slug}`}
+              className={cn(
+                "grid min-h-7 grid-cols-[minmax(0,1fr)_auto] items-center gap-2 py-1",
+                isHidden && "text-muted-foreground",
+              )}
+            >
+              <div className="flex min-w-0 items-center gap-1">
+                <span
+                  className={cn(
+                    "min-w-0 truncate text-xs",
+                    isHidden ? "text-muted-foreground line-through" : "text-foreground/90",
+                  )}
+                >
+                  {model.name}
+                </span>
+                {hasDetails ? (
+                  <Tooltip>
+                    <TooltipTrigger
+                      render={
+                        <Button
+                          size="icon-xs"
+                          variant="ghost"
+                          className="size-5 rounded-sm p-0 text-muted-foreground/60 hover:text-muted-foreground"
+                          aria-label={`Details for ${model.name}`}
+                        />
+                      }
+                    >
+                      <InfoIcon className="size-3" />
+                    </TooltipTrigger>
+                    <TooltipPopup side="top" className="max-w-56">
+                      <div className="space-y-1">
+                        <code className="block text-[11px] text-foreground">{model.slug}</code>
+                        {capLabels.length > 0 ? (
+                          <div className="flex flex-wrap gap-x-2 gap-y-0.5">
+                            {capLabels.map((label) => (
+                              <span key={label} className="text-[10px] text-muted-foreground">
+                                {label}
+                              </span>
+                            ))}
+                          </div>
+                        ) : null}
+                      </div>
+                    </TooltipPopup>
+                  </Tooltip>
+                ) : null}
+                {isHidden ? (
+                  <span className="text-[10px] text-muted-foreground">hidden</span>
+                ) : null}
+                {model.isCustom ? (
+                  <span className="text-[10px] text-muted-foreground">custom</span>
+                ) : null}
+              </div>
+              <div className="flex shrink-0 items-center gap-0.5">
+                <Tooltip>
+                  <TooltipTrigger
+                    render={
+                      <Button
+                        size="icon-xs"
+                        variant="ghost"
+                        className={cn(
+                          "size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground",
+                          isFavorite && "text-yellow-500 hover:text-yellow-600",
+                        )}
+                        onClick={() => handleToggleFavorite(model.slug)}
+                        aria-label={`${isFavorite ? "Remove" : "Add"} ${model.name} ${
+                          isFavorite ? "from" : "to"
+                        } favorites`}
+                      />
+                    }
+                  >
+                    <StarIcon className={cn("size-3", isFavorite && "fill-current")} />
+                  </TooltipTrigger>
+                  <TooltipPopup side="top">
+                    {isFavorite ? "Remove from favorites" : "Add to favorites"}
+                  </TooltipPopup>
+                </Tooltip>
+                <Tooltip>
+                  <TooltipTrigger
+                    render={
+                      <Button
+                        size="icon-xs"
+                        variant="ghost"
+                        className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                        disabled={!canMoveUp}
+                        onClick={() => handleMove(model.slug, -1)}
+                        aria-label={`Move ${model.name} up`}
+                      />
+                    }
+                  >
+                    <ArrowUpIcon className="size-3" />
+                  </TooltipTrigger>
+                  <TooltipPopup side="top">Move up</TooltipPopup>
+                </Tooltip>
+                <Tooltip>
+                  <TooltipTrigger
+                    render={
+                      <Button
+                        size="icon-xs"
+                        variant="ghost"
+                        className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                        disabled={!canMoveDown}
+                        onClick={() => handleMove(model.slug, 1)}
+                        aria-label={`Move ${model.name} down`}
+                      />
+                    }
+                  >
+                    <ArrowDownIcon className="size-3" />
+                  </TooltipTrigger>
+                  <TooltipPopup side="top">Move down</TooltipPopup>
+                </Tooltip>
+                {!model.isCustom ? (
+                  <Tooltip>
+                    <TooltipTrigger
+                      render={
+                        <Button
+                          size="icon-xs"
+                          variant="ghost"
+                          className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                          onClick={() => handleToggleHidden(model.slug)}
+                          aria-label={`${isHidden ? "Show" : "Hide"} ${model.name}`}
+                        />
+                      }
+                    >
+                      {isHidden ? (
+                        <EyeIcon className="size-3" />
+                      ) : (
+                        <EyeOffIcon className="size-3" />
+                      )}
+                    </TooltipTrigger>
+                    <TooltipPopup side="top">
+                      {isHidden ? "Show in picker" : "Hide from picker"}
+                    </TooltipPopup>
+                  </Tooltip>
+                ) : null}
+                {model.isCustom ? (
+                  <Tooltip>
+                    <TooltipTrigger
+                      render={
+                        <Button
+                          size="icon-xs"
+                          variant="ghost"
+                          className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                          aria-label={`Remove ${model.slug}`}
+                          onClick={() => handleRemove(model.slug)}
+                        />
+                      }
+                    >
+                      <XIcon className="size-3" />
+                    </TooltipTrigger>
+                    <TooltipPopup side="top">Remove custom model</TooltipPopup>
+                  </Tooltip>
+                ) : null}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+
+      <div className="mt-3 flex flex-col gap-2 sm:flex-row">
+        <Input
+          id={`provider-instance-${instanceId}-custom-model`}
+          value={input}
+          onChange={(event) => {
+            setInput(event.target.value);
+            if (error) setError(null);
+          }}
+          onKeyDown={(event) => {
+            if (event.key !== "Enter") return;
+            event.preventDefault();
+            handleAdd();
+          }}
+          placeholder={driverKind ? CUSTOM_MODEL_PLACEHOLDER_BY_KIND[driverKind] : "model-slug"}
+          spellCheck={false}
+        />
+        <Button className="shrink-0" variant="outline" onClick={handleAdd}>
+          <PlusIcon className="size-3.5" />
+          Add
+        </Button>
+      </div>
+
+      {error ? <p className="mt-2 text-xs text-destructive">{error}</p> : null}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/settings/ProviderSettingsForm.test.ts b/apps/web/src/components/settings/ProviderSettingsForm.test.ts
new file mode 100644
index 00000000000..0d3bc5ae98a
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderSettingsForm.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import { ProviderDriverKind } from "@t3tools/contracts";
+
+import { DRIVER_OPTION_BY_VALUE } from "./providerDriverMeta";
+import {
+  deriveProviderSettingsFields,
+  nextProviderConfigWithFieldValue,
+  readProviderConfigBoolean,
+  readProviderConfigString,
+} from "./ProviderSettingsForm";
+
+describe("ProviderSettingsForm helpers", () => {
+  it("derives visible provider config fields from the client definition schema", () => {
+    const codex = DRIVER_OPTION_BY_VALUE[ProviderDriverKind.make("codex")];
+
+    expect(codex).toBeDefined();
+    expect(deriveProviderSettingsFields(codex!).map((field) => field.key)).toEqual([
+      "binaryPath",
+      "homePath",
+      "shadowHomePath",
+    ]);
+  });
+
+  it("sources labels and descriptions from schema annotations", () => {
+    const opencode = DRIVER_OPTION_BY_VALUE[ProviderDriverKind.make("opencode")];
+    expect(opencode).toBeDefined();
+
+    const serverPassword = deriveProviderSettingsFields(opencode!).find(
+      (field) => field.key === "serverPassword",
+    );
+
+    expect(serverPassword).toMatchObject({
+      label: "Server password",
+      description: "Stored in plain text on disk.",
+      control: "password",
+    });
+  });
+
+  it("preserves unknown config keys while omitting empty configurable fields", () => {
+    const opencode = DRIVER_OPTION_BY_VALUE[ProviderDriverKind.make("opencode")];
+    expect(opencode).toBeDefined();
+
+    const serverUrl = deriveProviderSettingsFields(opencode!).find(
+      (field) => field.key === "serverUrl",
+    );
+    expect(serverUrl).toBeDefined();
+
+    const next = nextProviderConfigWithFieldValue(
+      { forkOwned: 1, serverUrl: "http://127.0.0.1:4096" },
+      serverUrl!,
+      "",
+    );
+
+    expect(next).toEqual({ forkOwned: 1 });
+  });
+
+  it("reads non-string config values as blank strings", () => {
+    expect(readProviderConfigString({ binaryPath: 123 }, "binaryPath")).toBe("");
+  });
+
+  it("omits false boolean fields when clearWhenEmpty is omit", () => {
+    const next = nextProviderConfigWithFieldValue(
+      { forkOwned: 1, experimental: true },
+      {
+        key: "experimental",
+        control: "switch",
+        label: "Experimental",
+        clearWhenEmpty: "omit",
+        defaultBooleanValue: false,
+      },
+      false,
+    );
+
+    expect(next).toEqual({ forkOwned: 1 });
+  });
+
+  it("omits true boolean fields when true is the default", () => {
+    const next = nextProviderConfigWithFieldValue(
+      { forkOwned: 1, experimental: false },
+      {
+        key: "experimental",
+        control: "switch",
+        label: "Experimental",
+        clearWhenEmpty: "omit",
+        defaultBooleanValue: true,
+      },
+      true,
+    );
+
+    expect(next).toEqual({ forkOwned: 1 });
+  });
+
+  it("stores false boolean fields when true is the default", () => {
+    const next = nextProviderConfigWithFieldValue(
+      undefined,
+      {
+        key: "experimental",
+        control: "switch",
+        label: "Experimental",
+        clearWhenEmpty: "omit",
+        defaultBooleanValue: true,
+      },
+      false,
+    );
+
+    expect(next).toEqual({ experimental: false });
+  });
+
+  it("preserves false boolean fields when clearWhenEmpty is persist", () => {
+    const next = nextProviderConfigWithFieldValue(
+      undefined,
+      {
+        key: "experimental",
+        control: "switch",
+        label: "Experimental",
+        clearWhenEmpty: "persist",
+      },
+      false,
+    );
+
+    expect(next).toEqual({ experimental: false });
+  });
+
+  it("reads non-boolean config values as false booleans", () => {
+    expect(readProviderConfigBoolean({ experimental: "true" }, "experimental")).toBe(false);
+  });
+
+  it("reads missing boolean config values from the supplied default", () => {
+    expect(readProviderConfigBoolean({}, "experimental", true)).toBe(true);
+  });
+});
diff --git a/apps/web/src/components/settings/ProviderSettingsForm.tsx b/apps/web/src/components/settings/ProviderSettingsForm.tsx
new file mode 100644
index 00000000000..83dc7d0688a
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderSettingsForm.tsx
@@ -0,0 +1,304 @@
+"use client";
+
+import { useMemo, type ReactNode } from "react";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import type {
+  ProviderSettingsFormAnnotation,
+  ProviderSettingsFormControl,
+  ProviderSettingsFormSchemaAnnotation,
+} from "@t3tools/contracts";
+
+import { cn } from "../../lib/utils";
+import { DraftInput } from "../ui/draft-input";
+import { Input } from "../ui/input";
+import { Switch } from "../ui/switch";
+import { Textarea } from "../ui/textarea";
+import type { ProviderClientDefinition } from "./providerDriverMeta";
+
+export interface ProviderSettingsFieldModel {
+  readonly key: string;
+  readonly control: ProviderSettingsFormControl;
+  readonly label: string;
+  readonly description?: string | undefined;
+  readonly placeholder?: string | undefined;
+  readonly clearWhenEmpty: "omit" | "persist";
+  readonly defaultBooleanValue?: boolean | undefined;
+}
+
+function titleizeFieldKey(key: string): string {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .replace(/^./, (char) => char.toUpperCase());
+}
+
+function readFieldAnnotations(
+  fieldSchema: ProviderClientDefinition["settingsSchema"]["fields"][string],
+) {
+  return Schema.resolveAnnotationsKey(fieldSchema) ?? Schema.resolveAnnotations(fieldSchema);
+}
+
+function readFieldAnnotationString(
+  fieldSchema: ProviderClientDefinition["settingsSchema"]["fields"][string],
+  key: "title" | "description",
+): string | undefined {
+  const annotations = readFieldAnnotations(fieldSchema);
+  const value = annotations?.[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readProviderSettingsFormAnnotation(
+  fieldSchema: ProviderClientDefinition["settingsSchema"]["fields"][string],
+): ProviderSettingsFormAnnotation {
+  const annotation = readFieldAnnotations(fieldSchema)?.providerSettingsForm;
+  return annotation ?? {};
+}
+
+function readProviderSettingsFormSchemaAnnotation(
+  definition: ProviderClientDefinition,
+): ProviderSettingsFormSchemaAnnotation {
+  return Schema.resolveAnnotations(definition.settingsSchema)?.providerSettingsFormSchema ?? {};
+}
+
+function readFieldBooleanDefault(
+  fieldSchema: ProviderClientDefinition["settingsSchema"]["fields"][string],
+): boolean | undefined {
+  const decodeDefault = Schema.decodeUnknownOption(fieldSchema as Schema.Decoder<unknown>);
+  const decoded = decodeDefault(undefined);
+  return Option.isSome(decoded) && typeof decoded.value === "boolean" ? decoded.value : undefined;
+}
+
+export function deriveProviderSettingsFields(
+  definition: ProviderClientDefinition,
+): ReadonlyArray<ProviderSettingsFieldModel> {
+  const schemaAnnotation = readProviderSettingsFormSchemaAnnotation(definition);
+  const orderedKeys = new Map(
+    (schemaAnnotation.order ?? []).map((key, index) => [key, index] as const),
+  );
+  const orderFallbackOffset = orderedKeys.size;
+
+  return Object.keys(definition.settingsSchema.fields)
+    .map((key, index) => ({ key, index }))
+    .toSorted((left, right) => {
+      return (
+        (orderedKeys.get(left.key) ?? orderFallbackOffset + left.index) -
+        (orderedKeys.get(right.key) ?? orderFallbackOffset + right.index)
+      );
+    })
+    .flatMap(({ key }) => {
+      const fieldSchema = definition.settingsSchema.fields[key]!;
+      const formAnnotation = readProviderSettingsFormAnnotation(fieldSchema);
+      if (formAnnotation.hidden) return [];
+
+      const annotatedTitle = readFieldAnnotationString(fieldSchema, "title");
+      const annotatedDescription = readFieldAnnotationString(fieldSchema, "description");
+      return [
+        {
+          key,
+          control: formAnnotation.control ?? "text",
+          label: annotatedTitle ?? titleizeFieldKey(key),
+          ...(annotatedDescription !== undefined ? { description: annotatedDescription } : {}),
+          ...(formAnnotation.placeholder !== undefined
+            ? { placeholder: formAnnotation.placeholder }
+            : {}),
+          clearWhenEmpty: formAnnotation.clearWhenEmpty ?? "omit",
+          ...(formAnnotation.control === "switch"
+            ? { defaultBooleanValue: readFieldBooleanDefault(fieldSchema) }
+            : {}),
+        } satisfies ProviderSettingsFieldModel,
+      ];
+    });
+}
+
+export function readProviderConfigString(config: unknown, key: string): string {
+  if (config === null || typeof config !== "object") return "";
+  const value = (config as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : "";
+}
+
+export function readProviderConfigBoolean(
+  config: unknown,
+  key: string,
+  defaultValue = false,
+): boolean {
+  if (config === null || typeof config !== "object") return defaultValue;
+  const value = (config as Record<string, unknown>)[key];
+  return typeof value === "boolean" ? value : defaultValue;
+}
+
+export function nextProviderConfigWithFieldValue(
+  config: unknown,
+  field: ProviderSettingsFieldModel,
+  value: string | boolean,
+): Record<string, unknown> | undefined {
+  const base: Record<string, unknown> =
+    config !== null && typeof config === "object" ? { ...(config as Record<string, unknown>) } : {};
+
+  if (typeof value === "boolean") {
+    const emptyBooleanValue = field.defaultBooleanValue ?? false;
+    if (field.clearWhenEmpty === "omit" && value === emptyBooleanValue) {
+      delete base[field.key];
+    } else {
+      base[field.key] = value;
+    }
+    return Object.keys(base).length > 0 ? base : undefined;
+  }
+
+  const trimmed = value.trim();
+  if (field.clearWhenEmpty === "omit" && trimmed.length === 0) {
+    delete base[field.key];
+  } else {
+    base[field.key] = value;
+  }
+  return Object.keys(base).length > 0 ? base : undefined;
+}
+
+interface ProviderSettingsFormProps {
+  readonly definition: ProviderClientDefinition;
+  readonly value: unknown;
+  readonly idPrefix: string;
+  readonly variant: "card" | "dialog";
+  readonly onChange: (nextConfig: Record<string, unknown> | undefined) => void;
+}
+
+function FieldFrame(props: {
+  readonly variant: ProviderSettingsFormProps["variant"];
+  readonly children: ReactNode;
+}) {
+  if (props.variant === "card") {
+    return <div className="border-t border-border/60 px-4 py-3 sm:px-5">{props.children}</div>;
+  }
+  return <div className="grid gap-1.5">{props.children}</div>;
+}
+
+interface ProviderSettingsFieldRowProps {
+  readonly field: ProviderSettingsFieldModel;
+  readonly value: unknown;
+  readonly idPrefix: string;
+  readonly variant: ProviderSettingsFormProps["variant"];
+  readonly onChange: ProviderSettingsFormProps["onChange"];
+}
+
+function ProviderSettingsFieldRow({
+  field,
+  value,
+  idPrefix,
+  variant,
+  onChange,
+}: ProviderSettingsFieldRowProps) {
+  const inputId = `${idPrefix}-${field.key}`;
+  const descriptionClassName =
+    variant === "card"
+      ? "mt-1 block text-xs text-muted-foreground"
+      : "text-[11px] text-muted-foreground";
+  const label = <span className="text-xs font-medium text-foreground">{field.label}</span>;
+  const description = field.description ? (
+    <span className={descriptionClassName}>{field.description}</span>
+  ) : null;
+
+  if (field.control === "switch") {
+    return (
+      <FieldFrame variant={variant}>
+        <div className="flex items-center justify-between gap-3">
+          <div className="min-w-0">
+            {label}
+            {description}
+          </div>
+          <Switch
+            checked={readProviderConfigBoolean(value, field.key, field.defaultBooleanValue)}
+            onCheckedChange={(checked) =>
+              onChange(nextProviderConfigWithFieldValue(value, field, Boolean(checked)))
+            }
+            aria-label={field.label}
+          />
+        </div>
+      </FieldFrame>
+    );
+  }
+
+  if (field.control === "textarea") {
+    return (
+      <FieldFrame variant={variant}>
+        <label htmlFor={inputId} className={cn(variant === "card" && "block")}>
+          {label}
+          <Textarea
+            id={inputId}
+            className={cn(variant === "card" && "mt-1.5")}
+            value={readProviderConfigString(value, field.key)}
+            onChange={(event) =>
+              onChange(nextProviderConfigWithFieldValue(value, field, event.target.value))
+            }
+            placeholder={field.placeholder}
+            spellCheck={false}
+          />
+          {description}
+        </label>
+      </FieldFrame>
+    );
+  }
+
+  const type = field.control === "password" ? "password" : undefined;
+  return (
+    <FieldFrame variant={variant}>
+      <label htmlFor={inputId} className={cn(variant === "card" && "block")}>
+        {label}
+        {variant === "card" ? (
+          <DraftInput
+            id={inputId}
+            className="mt-1.5"
+            type={type}
+            autoComplete={field.control === "password" ? "off" : undefined}
+            value={readProviderConfigString(value, field.key)}
+            onCommit={(next) => onChange(nextProviderConfigWithFieldValue(value, field, next))}
+            placeholder={field.placeholder}
+            spellCheck={false}
+          />
+        ) : (
+          <Input
+            id={inputId}
+            className="bg-background"
+            type={type}
+            autoComplete={field.control === "password" ? "off" : undefined}
+            value={readProviderConfigString(value, field.key)}
+            onChange={(event) =>
+              onChange(nextProviderConfigWithFieldValue(value, field, event.target.value))
+            }
+            placeholder={field.placeholder}
+            spellCheck={false}
+          />
+        )}
+        {description}
+      </label>
+    </FieldFrame>
+  );
+}
+
+export function ProviderSettingsForm({
+  definition,
+  value,
+  idPrefix,
+  variant,
+  onChange,
+}: ProviderSettingsFormProps) {
+  const fields = useMemo(() => deriveProviderSettingsFields(definition), [definition]);
+
+  if (fields.length === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {fields.map((field) => (
+        <ProviderSettingsFieldRow
+          key={field.key}
+          field={field}
+          value={value}
+          idPrefix={idPrefix}
+          variant={variant}
+          onChange={onChange}
+        />
+      ))}
+    </>
+  );
+}
diff --git a/apps/web/src/components/settings/RedactedSensitiveText.tsx b/apps/web/src/components/settings/RedactedSensitiveText.tsx
new file mode 100644
index 00000000000..95b31b40369
--- /dev/null
+++ b/apps/web/src/components/settings/RedactedSensitiveText.tsx
@@ -0,0 +1,61 @@
+import { useMemo, useState } from "react";
+
+import { cn } from "../../lib/utils";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+
+const REDACTED_TEXT_ALPHABET = "abcdefghjkmnpqrstuvwxyz23456789";
+
+function redactedPlaceholder(value: string): string {
+  let state = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    state ^= value.charCodeAt(index);
+    state = Math.imul(state, 0x01000193);
+  }
+
+  const nextChar = () => {
+    state = Math.imul(state ^ (state >>> 13), 0x85ebca6b);
+    state = Math.imul(state ^ (state >>> 16), 0xc2b2ae35);
+    return REDACTED_TEXT_ALPHABET[Math.abs(state) % REDACTED_TEXT_ALPHABET.length] ?? "x";
+  };
+
+  return Array.from(value, (char) => {
+    if (char === "@" || char === "." || char === "-" || char === "_") return char;
+    return nextChar();
+  }).join("");
+}
+
+export function RedactedSensitiveText(props: {
+  readonly value: string | null | undefined;
+  readonly ariaLabel: string;
+  readonly revealTooltip: string;
+  readonly hideTooltip: string;
+  readonly className?: string;
+}) {
+  const [revealed, setRevealed] = useState(false);
+  const value = props.value?.trim();
+  const redacted = useMemo(() => (value ? redactedPlaceholder(value) : ""), [value]);
+
+  if (!value) return null;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <button
+            type="button"
+            className={cn(
+              "min-w-0 cursor-pointer rounded-sm font-mono text-[11px] leading-none transition hover:text-foreground",
+              revealed ? "text-muted-foreground" : "select-none text-muted-foreground blur-[2px]",
+              props.className,
+            )}
+            onClick={() => setRevealed((current) => !current)}
+            aria-label={props.ariaLabel}
+          >
+            {revealed ? value : redacted}
+          </button>
+        }
+      />
+      <TooltipPopup side="top">{revealed ? props.hideTooltip : props.revealTooltip}</TooltipPopup>
+    </Tooltip>
+  );
+}
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 0337da23a4e..34f24006edc 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -7,20 +7,54 @@ import {
   DEFAULT_SERVER_SETTINGS,
   EnvironmentId,
   type DesktopBridge,
+  type DesktopUpdateChannel,
   type DesktopUpdateState,
   type LocalApi,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerConfig,
+  type ServerProcessResourceHistoryResult,
+  type ServerProvider,
+  type SourceControlDiscoveryResult,
 } from "@t3tools/contracts";
-import { DateTime } from "effect";
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
 import { page } from "vitest/browser";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { render } from "vitest-browser-react";
+import type { ReactNode } from "react";
+import {
+  RouterProvider,
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from "@tanstack/react-router";
 
 import { __resetLocalApiForTests } from "../../localApi";
-import { AppAtomRegistryProvider } from "../../rpc/atomRegistry";
+import { AppAtomRegistryProvider, resetAppAtomRegistryForTests } from "../../rpc/atomRegistry";
 import { resetServerStateForTests, setServerConfigSnapshot } from "../../rpc/serverState";
+import { useUiStateStore } from "../../uiStateStore";
 import { ConnectionsSettings } from "./ConnectionsSettings";
-import { GeneralSettingsPanel } from "./SettingsPanels";
+import { DiagnosticsSettingsPanel } from "./DiagnosticsSettings";
+import { GeneralSettingsPanel, ProviderSettingsPanel } from "./SettingsPanels";
+import { SourceControlSettingsPanel } from "./SourceControlSettings";
+
+function renderWithTestRouter(children: ReactNode) {
+  const rootRoute = createRootRoute({
+    component: () => children,
+  });
+  const indexRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: "/",
+  });
+  const router = createRouter({
+    routeTree: rootRoute.addChildren([indexRoute]),
+    history: createMemoryHistory({ initialEntries: ["/"] }),
+  });
+
+  return render(<RouterProvider router={router} />);
+}
 
 const authAccessHarness = vi.hoisted(() => {
   type Snapshot = AuthAccessSnapshot;
@@ -112,6 +146,8 @@ const authAccessHarness = vi.hoisted(() => {
   };
 });
 
+const mockConnectDesktopSshEnvironment = vi.hoisted(() => vi.fn());
+
 vi.mock("../../environments/runtime", () => {
   const primaryConnection = {
     kind: "primary" as const,
@@ -149,6 +185,7 @@ vi.mock("../../environments/runtime", () => {
       new URL(path, "http://localhost:3000").toString(),
     waitForSavedEnvironmentRegistryHydration: async () => undefined,
     addSavedEnvironment: vi.fn(),
+    connectDesktopSshEnvironment: mockConnectDesktopSshEnvironment,
     disconnectSavedEnvironment: vi.fn(),
     ensureEnvironmentConnectionBootstrapped: async () => undefined,
     getPrimaryEnvironmentConnection: () => primaryConnection,
@@ -200,8 +237,50 @@ function createBaseServerConfig(): ServerConfig {
   };
 }
 
+function createOutdatedProvider(
+  driver: string,
+  updateCommand = "npm install -g openai/codex@latest",
+): ServerProvider {
+  return {
+    instanceId: ProviderInstanceId.make(driver),
+    driver: ProviderDriverKind.make(driver),
+    enabled: true,
+    installed: true,
+    version: "1.0.0",
+    status: "ready",
+    auth: { status: "authenticated" },
+    checkedAt: "2026-05-04T10:00:00.000Z",
+    models: [],
+    slashCommands: [],
+    skills: [],
+    versionAdvisory: {
+      status: "behind_latest",
+      currentVersion: "1.0.0",
+      latestVersion: "1.1.0",
+      message: "Update available.",
+      checkedAt: "2026-05-04T10:00:00.000Z",
+      updateCommand,
+      canUpdate: true,
+    },
+  };
+}
+
 function makeUtc(value: string) {
-  return DateTime.makeUnsafe(Date.parse(value));
+  return DateTime.makeUnsafe(value);
+}
+
+function createEmptyProcessResourceHistoryResult(): ServerProcessResourceHistoryResult {
+  return {
+    readAt: makeUtc("2036-04-07T00:00:00.000Z"),
+    windowMs: 15 * 60_000,
+    bucketMs: 60_000,
+    sampleIntervalMs: 5_000,
+    retainedSampleCount: 0,
+    totalCpuSecondsApprox: 0,
+    buckets: [],
+    topProcesses: [],
+    error: Option.none(),
+  };
 }
 
 function makePairingLink(input: {
@@ -256,12 +335,16 @@ function makeClientSession(input: {
 }
 
 const createDesktopBridgeStub = (overrides?: {
+  readonly discoverSshHosts?: DesktopBridge["discoverSshHosts"];
   readonly serverExposureState?: Awaited<ReturnType<DesktopBridge["getServerExposureState"]>>;
+  readonly advertisedEndpoints?: Awaited<ReturnType<DesktopBridge["getAdvertisedEndpoints"]>>;
   readonly setServerExposureMode?: DesktopBridge["setServerExposureMode"];
+  readonly setUpdateChannel?: DesktopBridge["setUpdateChannel"];
 }): DesktopBridge => {
   const idleUpdateState: DesktopUpdateState = {
     enabled: false,
     status: "idle",
+    channel: "latest",
     currentVersion: "0.0.0-test",
     hostArch: "arm64",
     appArch: "arm64",
@@ -276,6 +359,7 @@ const createDesktopBridgeStub = (overrides?: {
   };
 
   return {
+    getAppBranding: vi.fn().mockReturnValue(null),
     getLocalEnvironmentBootstrap: () => ({
       label: "Local environment",
       httpBaseUrl: "http://127.0.0.1:3773",
@@ -289,11 +373,58 @@ const createDesktopBridgeStub = (overrides?: {
     getSavedEnvironmentSecret: vi.fn().mockResolvedValue(null),
     setSavedEnvironmentSecret: vi.fn().mockResolvedValue(true),
     removeSavedEnvironmentSecret: vi.fn().mockResolvedValue(undefined),
+    discoverSshHosts: overrides?.discoverSshHosts ?? vi.fn().mockResolvedValue([]),
+    ensureSshEnvironment: vi.fn().mockImplementation(async (target) => ({
+      target,
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      pairingToken: "ssh-pairing-token",
+    })),
+    disconnectSshEnvironment: vi.fn().mockResolvedValue(undefined),
+    fetchSshEnvironmentDescriptor: vi.fn().mockResolvedValue({
+      environmentId: "environment-ssh",
+      label: "SSH environment",
+      platform: {
+        os: "linux",
+        arch: "x64",
+      },
+      serverVersion: "0.0.0-test",
+      capabilities: {
+        repositoryIdentity: true,
+      },
+    }),
+    bootstrapSshBearerSession: vi.fn().mockResolvedValue({
+      authenticated: true,
+      role: "owner",
+      sessionMethod: "bearer-session-token",
+      expiresAt: "2026-05-01T12:00:00.000Z",
+      sessionToken: "ssh-bearer-token",
+    }),
+    fetchSshSessionState: vi.fn().mockResolvedValue({
+      authenticated: true,
+      auth: {
+        policy: "remote-reachable",
+        bootstrapMethods: ["one-time-token"],
+        sessionMethods: ["browser-session-cookie", "bearer-session-token"],
+        sessionCookieName: "t3_session",
+      },
+      role: "owner",
+      sessionMethod: "bearer-session-token",
+      expiresAt: "2026-05-01T12:00:00.000Z",
+    }),
+    issueSshWebSocketToken: vi.fn().mockResolvedValue({
+      token: "ssh-ws-token",
+      expiresAt: "2026-05-01T12:05:00.000Z",
+    }),
+    onSshPasswordPrompt: vi.fn(() => () => {}),
+    resolveSshPasswordPrompt: vi.fn().mockResolvedValue(undefined),
     getServerExposureState: vi.fn().mockResolvedValue(
       overrides?.serverExposureState ?? {
         mode: "local-only",
         endpointUrl: null,
         advertisedHost: null,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
     ),
     setServerExposureMode:
@@ -302,7 +433,17 @@ const createDesktopBridgeStub = (overrides?: {
         mode,
         endpointUrl: mode === "network-accessible" ? "http://192.168.1.44:3773" : null,
         advertisedHost: mode === "network-accessible" ? "192.168.1.44" : null,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       })),
+    setTailscaleServeEnabled: vi.fn().mockImplementation(async (input) => ({
+      mode: overrides?.serverExposureState?.mode ?? "network-accessible",
+      endpointUrl: overrides?.serverExposureState?.endpointUrl ?? "http://192.168.1.44:3773",
+      advertisedHost: overrides?.serverExposureState?.advertisedHost ?? "192.168.1.44",
+      tailscaleServeEnabled: input.enabled,
+      tailscaleServePort: input.port ?? 443,
+    })),
+    getAdvertisedEndpoints: vi.fn().mockResolvedValue(overrides?.advertisedEndpoints ?? []),
     pickFolder: vi.fn().mockResolvedValue(null),
     confirm: vi.fn().mockResolvedValue(false),
     setTheme: vi.fn().mockResolvedValue(undefined),
@@ -310,6 +451,12 @@ const createDesktopBridgeStub = (overrides?: {
     openExternal: vi.fn().mockResolvedValue(true),
     onMenuAction: () => () => {},
     getUpdateState: vi.fn().mockResolvedValue(idleUpdateState),
+    setUpdateChannel:
+      overrides?.setUpdateChannel ??
+      vi.fn().mockImplementation(async (channel: DesktopUpdateChannel) => ({
+        ...idleUpdateState,
+        channel,
+      })),
     checkForUpdate: vi.fn().mockResolvedValue({ checked: false, state: idleUpdateState }),
     downloadUpdate: vi
       .fn()
@@ -333,7 +480,9 @@ describe("GeneralSettingsPanel observability", () => {
     resetServerStateForTests();
     await __resetLocalApiForTests();
     localStorage.clear();
+    useUiStateStore.setState({ defaultAdvertisedEndpointKey: null });
     authAccessHarness.reset();
+    mockConnectDesktopSshEnvironment.mockReset();
   });
 
   afterEach(async () => {
@@ -419,25 +568,194 @@ describe("GeneralSettingsPanel observability", () => {
       .toBeInTheDocument();
   });
 
-  it("shows diagnostics inside About with a single logs-folder action", async () => {
+  it("hides advertised endpoint rows when desktop network access is disabled", async () => {
+    window.desktopBridge = createDesktopBridgeStub({
+      serverExposureState: {
+        mode: "local-only",
+        endpointUrl: null,
+        advertisedHost: null,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
+      },
+      advertisedEndpoints: [
+        {
+          id: "loopback",
+          label: "This machine",
+          provider: {
+            id: "desktop-core",
+            label: "Desktop",
+            kind: "manual",
+            isAddon: false,
+          },
+          httpBaseUrl: "http://127.0.0.1:3773/",
+          wsBaseUrl: "ws://127.0.0.1:3773/",
+          reachability: "loopback",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-core",
+          status: "available",
+          isDefault: true,
+        },
+        {
+          id: "tailscale-ip",
+          label: "Tailscale IP",
+          provider: {
+            id: "tailscale",
+            label: "Tailscale",
+            kind: "private-network",
+            isAddon: true,
+          },
+          httpBaseUrl: "http://100.105.39.17:3773/",
+          wsBaseUrl: "ws://100.105.39.17:3773/",
+          reachability: "private-network",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-addon",
+          status: "available",
+        },
+      ],
+    });
+    authAccessHarness.setSnapshot({
+      pairingLinks: [],
+      clientSessions: [],
+    });
     setServerConfigSnapshot(createBaseServerConfig());
 
     mounted = await render(
+      <AppAtomRegistryProvider>
+        <ConnectionsSettings />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByText("Limited to this machine.")).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "This machine", exact: true }))
+      .not.toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "Tailscale IP", exact: true }))
+      .not.toBeInTheDocument();
+  });
+
+  it("collapses advertised endpoints behind the network access summary", async () => {
+    window.desktopBridge = createDesktopBridgeStub({
+      serverExposureState: {
+        mode: "network-accessible",
+        endpointUrl: "http://192.168.86.39:3773",
+        advertisedHost: "192.168.86.39",
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
+      },
+      advertisedEndpoints: [
+        {
+          id: "desktop-loopback:3773",
+          label: "This machine",
+          provider: {
+            id: "desktop-core",
+            label: "Desktop",
+            kind: "manual",
+            isAddon: false,
+          },
+          httpBaseUrl: "http://127.0.0.1:3773/",
+          wsBaseUrl: "ws://127.0.0.1:3773/",
+          reachability: "loopback",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-core",
+          status: "available",
+        },
+        {
+          id: "desktop-lan:http://192.168.86.39:3773",
+          label: "Local network",
+          provider: {
+            id: "desktop-core",
+            label: "Desktop",
+            kind: "manual",
+            isAddon: false,
+          },
+          httpBaseUrl: "http://192.168.86.39:3773/",
+          wsBaseUrl: "ws://192.168.86.39:3773/",
+          reachability: "lan",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-core",
+          status: "available",
+          isDefault: true,
+        },
+        {
+          id: "tailscale-ip:http://100.105.39.17:3773",
+          label: "Tailscale IP",
+          provider: {
+            id: "tailscale",
+            label: "Tailscale",
+            kind: "private-network",
+            isAddon: true,
+          },
+          httpBaseUrl: "http://100.105.39.17:3773/",
+          wsBaseUrl: "ws://100.105.39.17:3773/",
+          reachability: "private-network",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-addon",
+          status: "available",
+        },
+      ],
+    });
+    authAccessHarness.setSnapshot({
+      pairingLinks: [],
+      clientSessions: [],
+    });
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ConnectionsSettings />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByText("http://192.168.86.39:3773/")).toBeInTheDocument();
+    await expect.element(page.getByRole("button", { name: "+2" })).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "Local network", exact: true }))
+      .not.toBeInTheDocument();
+
+    await page.getByRole("button", { name: "+2" }).click();
+
+    await expect
+      .element(page.getByRole("heading", { name: "Local network", exact: true }))
+      .toBeInTheDocument();
+    await expect.element(page.getByText("Default", { exact: true })).toBeInTheDocument();
+    await page.getByRole("button", { name: "Set as default" }).first().click();
+    await expect.element(page.getByText("http://127.0.0.1:3773/").first()).toBeInTheDocument();
+  });
+
+  it("shows diagnostics inside About with a diagnostics link", async () => {
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await renderWithTestRouter(
       <AppAtomRegistryProvider>
         <GeneralSettingsPanel />
       </AppAtomRegistryProvider>,
     );
 
     await expect.element(page.getByText("About")).toBeInTheDocument();
-    await expect.element(page.getByText("Diagnostics")).toBeInTheDocument();
-    await expect.element(page.getByText("Open logs folder")).toBeInTheDocument();
     await expect
-      .element(page.getByText("/repo/project/.t3/logs", { exact: true }))
+      .element(page.getByRole("heading", { name: "Diagnostics", exact: true }))
       .toBeInTheDocument();
+    await expect.element(page.getByRole("link", { name: "View diagnostics" })).toBeInTheDocument();
     await expect
       .element(
         page.getByText(
-          "Local trace file. OTLP exporting traces to http://localhost:4318/v1/traces.",
+          "Local trace file. Exporting OTEL traces to http://localhost:4318/v1/traces.",
         ),
       )
       .toBeInTheDocument();
@@ -449,6 +767,8 @@ describe("GeneralSettingsPanel observability", () => {
         mode: "network-accessible",
         endpointUrl: "http://192.168.1.44:3773",
         advertisedHost: "192.168.1.44",
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
     });
     let pairingLinks: Array<AuthAccessSnapshot["pairingLinks"][number]> = [];
@@ -554,7 +874,7 @@ describe("GeneralSettingsPanel observability", () => {
       .element(page.getByText("Client · Mobile · iOS · Safari · 192.168.1.88"))
       .toBeInTheDocument();
     await expect
-      .element(page.getByRole("button", { name: /^(Copy|Show link)$/ }))
+      .element(page.getByRole("button", { name: /^Copy pairing URL for:/ }))
       .toBeInTheDocument();
     await expect.element(page.getByText("Revoke others")).toBeInTheDocument();
   });
@@ -565,6 +885,8 @@ describe("GeneralSettingsPanel observability", () => {
         mode: "network-accessible",
         endpointUrl: "http://192.168.1.44:3773",
         advertisedHost: "192.168.1.44",
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
     });
     let clientSessions: Array<AuthAccessSnapshot["clientSessions"][number]> = [
@@ -665,30 +987,420 @@ describe("GeneralSettingsPanel observability", () => {
     await vi.waitFor(() => {
       expect(desktopBridge.setServerExposureMode).toHaveBeenCalledWith("network-accessible");
     });
+    await expect.element(page.getByText("http://192.168.1.44:3773")).toBeInTheDocument();
+  });
+
+  it("adds desktop ssh environments from the add-environment dialog", async () => {
+    const discoverSshHosts = vi.fn().mockResolvedValue([
+      {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+        source: "ssh-config" as const,
+      },
+    ]);
+    window.desktopBridge = createDesktopBridgeStub({
+      discoverSshHosts,
+    });
+    mockConnectDesktopSshEnvironment.mockResolvedValue({
+      environmentId: EnvironmentId.make("environment-devbox"),
+      label: "Build box",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      createdAt: "2036-04-07T00:00:00.000Z",
+      lastConnectedAt: "2036-04-07T00:00:00.000Z",
+      desktopSsh: {
+        alias: "devbox.example.com",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 2222,
+      },
+    });
+
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ConnectionsSettings />
+      </AppAtomRegistryProvider>,
+    );
+
+    await page.getByRole("button", { name: "Add environment", exact: true }).click();
+    const addEnvironmentDialog = page.getByRole("dialog", { name: "Add Environment" });
+    await expect
+      .element(addEnvironmentDialog.getByRole("heading", { name: "Add Environment", exact: true }))
+      .toBeInTheDocument();
+    await addEnvironmentDialog.getByRole("button", { name: /^SSH\b/ }).click();
+    await vi.waitFor(() => {
+      expect(discoverSshHosts).toHaveBeenCalledTimes(1);
+    });
     await expect
-      .element(page.getByText("Reachable at http://192.168.1.44:3773"))
+      .element(page.getByRole("heading", { name: "devbox", exact: true }))
       .toBeInTheDocument();
+
+    await addEnvironmentDialog.getByLabelText("SSH host or alias").fill("devbox.example.com");
+    await addEnvironmentDialog.getByLabelText("Username").fill("julius");
+    await addEnvironmentDialog.getByLabelText("Port").fill("2222");
+    await addEnvironmentDialog
+      .getByRole("button", { name: "Add environment", exact: true })
+      .first()
+      .click();
+
+    await vi.waitFor(() => {
+      expect(mockConnectDesktopSshEnvironment).toHaveBeenCalledWith(
+        {
+          alias: "devbox.example.com",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 2222,
+        },
+        { label: "" },
+      );
+    });
   });
 
   it("opens the logs folder in the preferred editor", async () => {
     const openInEditor = vi.fn<LocalApi["shell"]["openInEditor"]>().mockResolvedValue(undefined);
     window.nativeApi = {
+      persistence: {
+        getClientSettings: vi.fn().mockResolvedValue(null),
+        setClientSettings: vi.fn().mockResolvedValue(undefined),
+      },
       shell: {
         openInEditor,
       },
+      server: {
+        getProcessDiagnostics: vi.fn().mockResolvedValue({
+          serverPid: 1234,
+          readAt: makeUtc("2036-04-07T00:00:00.000Z"),
+          processCount: 0,
+          totalRssBytes: 0,
+          totalCpuPercent: 0,
+          processes: [],
+          error: Option.none(),
+        }),
+        getProcessResourceHistory: vi
+          .fn()
+          .mockResolvedValue(createEmptyProcessResourceHistoryResult()),
+        getTraceDiagnostics: vi.fn().mockResolvedValue({
+          traceFilePath: "/repo/project/.t3/traces.jsonl",
+          scannedFilePaths: ["/repo/project/.t3/traces.jsonl"],
+          readAt: makeUtc("2036-04-07T00:00:00.000Z"),
+          recordCount: 0,
+          parseErrorCount: 0,
+          firstSpanAt: Option.none(),
+          lastSpanAt: Option.none(),
+          failureCount: 0,
+          interruptionCount: 0,
+          slowSpanThresholdMs: 5_000,
+          slowSpanCount: 0,
+          logLevelCounts: {},
+          topSpansByCount: [],
+          slowestSpans: [],
+          commonFailures: [],
+          latestFailures: [],
+          latestWarningAndErrorLogs: [],
+          partialFailure: Option.none(),
+          error: Option.none(),
+        }),
+      },
     } as unknown as LocalApi;
 
     setServerConfigSnapshot(createBaseServerConfig());
 
     mounted = await render(
       <AppAtomRegistryProvider>
-        <GeneralSettingsPanel />
+        <DiagnosticsSettingsPanel />
       </AppAtomRegistryProvider>,
     );
 
-    const openLogsButton = page.getByText("Open logs folder");
+    const openLogsButton = page.getByLabelText("Open logs folder");
     await openLogsButton.click();
 
     expect(openInEditor).toHaveBeenCalledWith("/repo/project/.t3/logs", "cursor");
   });
+
+  it("shows an OpenCode server URL field in provider settings", async () => {
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ProviderSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await page.getByLabelText("Toggle OpenCode details").click();
+
+    // The unified provider-instance card renders field labels without a
+    // driver-name prefix (the driver name is already shown in the card
+    // header), so the labels read "Server URL" / "Server password"
+    // rather than the old "OpenCode server URL" / "OpenCode server password".
+    await expect.element(page.getByText("Server URL")).toBeInTheDocument();
+    await expect.element(page.getByPlaceholder("http://127.0.0.1:4096")).toBeInTheDocument();
+    await expect.element(page.getByText("Server password")).toBeInTheDocument();
+    await expect.element(page.getByPlaceholder("Optional")).toBeInTheDocument();
+  });
+
+  it("runs one-click provider updates from the provider card", async () => {
+    const updateProvider = vi.fn<LocalApi["server"]["updateProvider"]>().mockResolvedValue({
+      providers: [createOutdatedProvider("codex")],
+    });
+    window.nativeApi = {
+      persistence: {
+        getClientSettings: vi.fn().mockResolvedValue(null),
+        setClientSettings: vi.fn().mockResolvedValue(undefined),
+      },
+      server: {
+        updateProvider,
+      },
+    } as unknown as LocalApi;
+
+    setServerConfigSnapshot({
+      ...createBaseServerConfig(),
+      providers: [createOutdatedProvider("codex")],
+    });
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ProviderSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await page.getByRole("button", { name: "Update available — view details" }).click();
+    await expect.element(page.getByRole("button", { name: "Update now" })).toBeInTheDocument();
+    await page.getByRole("button", { name: "Update now" }).click();
+
+    expect(updateProvider).toHaveBeenCalledWith({
+      provider: ProviderDriverKind.make("codex"),
+      instanceId: ProviderInstanceId.make("codex"),
+    });
+  });
+
+  it("keeps long provider update commands inside the fixed-width popover", async () => {
+    const longUpdateCommand =
+      "npm install -g @anthropic-ai/claude-code@latest --registry=https://registry.npmjs.org --cache=/tmp/t3code-provider-update-cache";
+
+    setServerConfigSnapshot({
+      ...createBaseServerConfig(),
+      providers: [createOutdatedProvider("codex", longUpdateCommand)],
+    });
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ProviderSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await page.getByRole("button", { name: "Update available — view details" }).click();
+    await expect.element(page.getByText(longUpdateCommand)).toBeInTheDocument();
+
+    await vi.waitFor(() => {
+      const popup = document.querySelector<HTMLElement>('[data-slot="popover-popup"]');
+      const commandCode = Array.from(document.querySelectorAll<HTMLElement>("code")).find(
+        (element) => element.textContent === longUpdateCommand,
+      );
+      const scrollViewport = commandCode?.closest<HTMLElement>(
+        '[data-slot="scroll-area-viewport"]',
+      );
+
+      expect(popup).toBeTruthy();
+      expect(commandCode).toBeTruthy();
+      expect(scrollViewport).toBeTruthy();
+
+      const popupRect = popup!.getBoundingClientRect();
+      const viewportRect = scrollViewport!.getBoundingClientRect();
+
+      expect(popupRect.width).toBeGreaterThan(300);
+      expect(popupRect.width).toBeLessThanOrEqual(337);
+      expect(viewportRect.right).toBeLessThanOrEqual(popupRect.right + 0.5);
+      expect(scrollViewport!.scrollWidth).toBeGreaterThan(scrollViewport!.clientWidth);
+    });
+  });
+});
+
+describe("SourceControlSettingsPanel discovery states", () => {
+  let mounted:
+    | (Awaited<ReturnType<typeof render>> & {
+        cleanup?: () => Promise<void>;
+        unmount?: () => Promise<void>;
+      })
+    | null = null;
+
+  beforeEach(async () => {
+    resetAppAtomRegistryForTests();
+    await __resetLocalApiForTests();
+    document.body.innerHTML = "";
+  });
+
+  afterEach(async () => {
+    if (mounted) {
+      const teardown = mounted.cleanup ?? mounted.unmount;
+      await teardown?.call(mounted).catch(() => {});
+    }
+    mounted = null;
+    Reflect.deleteProperty(window, "nativeApi");
+    document.body.innerHTML = "";
+    await __resetLocalApiForTests();
+    resetAppAtomRegistryForTests();
+  });
+
+  function setSourceControlDiscoveryStub(
+    discoverSourceControl: () => Promise<SourceControlDiscoveryResult>,
+  ) {
+    window.nativeApi = {
+      server: {
+        discoverSourceControl,
+      },
+    } as LocalApi;
+  }
+
+  it("shows skeleton sections while the first source control scan is pending", async () => {
+    setSourceControlDiscoveryStub(() => new Promise(() => {}));
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <SourceControlSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByText("Version Control")).toBeInTheDocument();
+    await expect.element(page.getByText("Source Control Providers")).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("button", { name: "Rescan server environment" }))
+      .toBeDisabled();
+    await expect.element(page.getByText("Nothing detected yet")).not.toBeInTheDocument();
+  });
+
+  it("uses the shared empty state when discovery completes without tools", async () => {
+    setSourceControlDiscoveryStub(async () => ({
+      versionControlSystems: [],
+      sourceControlProviders: [],
+    }));
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <SourceControlSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByText("Nothing detected yet")).toBeInTheDocument();
+    await expect
+      .element(
+        page.getByText(
+          "Install Git on the server, add optional hosting integrations or credentials your workspace needs, then rescan.",
+        ),
+      )
+      .toBeInTheDocument();
+    await expect.element(page.getByRole("button", { name: "Scan" })).toBeInTheDocument();
+  });
+
+  it("keeps discovered rows instead of showing the empty state", async () => {
+    setSourceControlDiscoveryStub(async () => ({
+      versionControlSystems: [
+        {
+          kind: "git",
+          label: "Git",
+          executable: "git",
+          implemented: true,
+          status: "available",
+          version: Option.some("git version 2.50.0"),
+          installHint: "Install Git.",
+          detail: Option.none(),
+        },
+      ],
+      sourceControlProviders: [],
+    }));
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <SourceControlSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByRole("switch", { name: "Git availability" })).toBeDisabled();
+    await expect.element(page.getByText("Nothing detected yet")).not.toBeInTheDocument();
+  });
+
+  it("shows Git fetch interval settings inside the Git details dropdown", async () => {
+    setSourceControlDiscoveryStub(async () => ({
+      versionControlSystems: [
+        {
+          kind: "git",
+          label: "Git",
+          executable: "git",
+          implemented: true,
+          status: "available",
+          version: Option.some("git version 2.50.0"),
+          installHint: "Install Git.",
+          detail: Option.none(),
+        },
+      ],
+      sourceControlProviders: [],
+    }));
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <SourceControlSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    const toggle = page.getByRole("button", { name: "Toggle Git details" });
+    await expect.element(toggle).toHaveAttribute("aria-expanded", "false");
+
+    await toggle.click();
+
+    await expect.element(toggle).toHaveAttribute("aria-expanded", "true");
+    await expect
+      .element(page.getByLabelText("Automatic Git fetch interval in seconds"))
+      .toBeVisible();
+    await expect
+      .element(page.getByText("Automatic Git fetches run every 30 seconds"))
+      .not.toBeInTheDocument();
+  });
+
+  it("does not rescan on remount while the discovery atom is fresh", async () => {
+    let calls = 0;
+    setSourceControlDiscoveryStub(async () => {
+      calls += 1;
+      return {
+        versionControlSystems: [
+          {
+            kind: "git",
+            label: "Git",
+            executable: "git",
+            implemented: true,
+            status: "available",
+            version: Option.some("git version 2.50.0"),
+            installHint: "Install Git.",
+            detail: Option.none(),
+          },
+        ],
+        sourceControlProviders: [],
+      };
+    });
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <SourceControlSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByRole("switch", { name: "Git availability" })).toBeDisabled();
+    expect(calls).toBe(1);
+
+    const teardown = mounted.cleanup ?? mounted.unmount;
+    await teardown?.call(mounted).catch(() => {});
+    mounted = null;
+    document.body.innerHTML = "";
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <SourceControlSettingsPanel />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByRole("switch", { name: "Git availability" })).toBeDisabled();
+    expect(calls).toBe(1);
+  });
 });
diff --git a/apps/web/src/components/settings/SettingsPanels.logic.test.ts b/apps/web/src/components/settings/SettingsPanels.logic.test.ts
new file mode 100644
index 00000000000..7a7c68a6b9c
--- /dev/null
+++ b/apps/web/src/components/settings/SettingsPanels.logic.test.ts
@@ -0,0 +1,104 @@
+import {
+  DEFAULT_SERVER_SETTINGS,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ProviderInstanceConfig,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+import {
+  buildProviderInstanceUpdatePatch,
+  formatDiagnosticsDescription,
+} from "./SettingsPanels.logic";
+
+describe("formatDiagnosticsDescription", () => {
+  it("collapses trace and metric URLs that share the same OTEL base path", () => {
+    expect(
+      formatDiagnosticsDescription({
+        localTracingEnabled: true,
+        otlpTracesEnabled: true,
+        otlpTracesUrl: "http://localhost:4318/v1/traces",
+        otlpMetricsEnabled: true,
+        otlpMetricsUrl: "http://localhost:4318/v1/metrics",
+      }),
+    ).toBe("Local trace file. Exporting OTEL to http://localhost:4318/v1/{traces,metrics}.");
+  });
+
+  it("keeps separate trace and metric URLs when their base paths differ", () => {
+    expect(
+      formatDiagnosticsDescription({
+        localTracingEnabled: true,
+        otlpTracesEnabled: true,
+        otlpTracesUrl: "http://localhost:4318/v1/traces",
+        otlpMetricsEnabled: true,
+        otlpMetricsUrl: "http://localhost:9000/v1/metrics",
+      }),
+    ).toBe(
+      "Local trace file. Exporting OTEL traces to http://localhost:4318/v1/traces and metrics to http://localhost:9000/v1/metrics.",
+    );
+  });
+
+  it("omits OTEL text when no exporter is enabled", () => {
+    expect(
+      formatDiagnosticsDescription({
+        localTracingEnabled: true,
+        otlpTracesEnabled: false,
+        otlpMetricsEnabled: false,
+      }),
+    ).toBe("Local trace file.");
+  });
+});
+
+describe("buildProviderInstanceUpdatePatch", () => {
+  it("promotes an edited default provider into providerInstances and resets the legacy provider", () => {
+    const instanceId = ProviderInstanceId.make("codex");
+    const nextInstance = {
+      driver: ProviderDriverKind.make("codex"),
+      enabled: true,
+      config: {
+        binaryPath: "/opt/t3/codex",
+      },
+    } satisfies ProviderInstanceConfig;
+
+    const patch = buildProviderInstanceUpdatePatch({
+      settings: {
+        ...DEFAULT_SERVER_SETTINGS,
+        providers: {
+          ...DEFAULT_SERVER_SETTINGS.providers,
+          codex: {
+            ...DEFAULT_SERVER_SETTINGS.providers.codex,
+            binaryPath: "/legacy/codex",
+          },
+        },
+      },
+      instanceId,
+      instance: nextInstance,
+      driver: ProviderDriverKind.make("codex"),
+      isDefault: true,
+    });
+
+    expect(patch.providerInstances?.[instanceId]).toEqual(nextInstance);
+    expect(patch.providers?.codex).toEqual(DEFAULT_SERVER_SETTINGS.providers.codex);
+  });
+
+  it("updates custom instances without touching legacy provider settings", () => {
+    const instanceId = ProviderInstanceId.make("codex_personal");
+    const nextInstance = {
+      driver: ProviderDriverKind.make("codex"),
+      enabled: true,
+      config: {
+        homePath: "/Users/example/.codex-personal",
+      },
+    } satisfies ProviderInstanceConfig;
+
+    const patch = buildProviderInstanceUpdatePatch({
+      settings: DEFAULT_SERVER_SETTINGS,
+      instanceId,
+      instance: nextInstance,
+      driver: ProviderDriverKind.make("codex"),
+      isDefault: false,
+    });
+
+    expect(patch.providerInstances?.[instanceId]).toEqual(nextInstance);
+    expect(patch.providers).toBeUndefined();
+  });
+});
diff --git a/apps/web/src/components/settings/SettingsPanels.logic.ts b/apps/web/src/components/settings/SettingsPanels.logic.ts
new file mode 100644
index 00000000000..99d7052965a
--- /dev/null
+++ b/apps/web/src/components/settings/SettingsPanels.logic.ts
@@ -0,0 +1,91 @@
+import type {
+  ProviderDriverKind,
+  ProviderInstanceConfig,
+  ProviderInstanceId,
+  ServerSettings,
+  UnifiedSettings,
+} from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
+
+function collapseOtelSignalsUrl(input: {
+  readonly tracesUrl: string;
+  readonly metricsUrl: string;
+}): string | null {
+  const tracesSuffix = "/traces";
+  const metricsSuffix = "/metrics";
+  if (!input.tracesUrl.endsWith(tracesSuffix) || !input.metricsUrl.endsWith(metricsSuffix)) {
+    return null;
+  }
+
+  const tracesBase = input.tracesUrl.slice(0, -tracesSuffix.length);
+  const metricsBase = input.metricsUrl.slice(0, -metricsSuffix.length);
+  if (tracesBase !== metricsBase) {
+    return null;
+  }
+
+  return `${tracesBase}/{traces,metrics}`;
+}
+
+export function formatDiagnosticsDescription(input: {
+  readonly localTracingEnabled: boolean;
+  readonly otlpTracesEnabled: boolean;
+  readonly otlpTracesUrl?: string | undefined;
+  readonly otlpMetricsEnabled: boolean;
+  readonly otlpMetricsUrl?: string | undefined;
+}): string {
+  const mode = input.localTracingEnabled ? "Local trace file" : "Terminal logs only";
+  const tracesUrl = input.otlpTracesEnabled ? input.otlpTracesUrl : undefined;
+  const metricsUrl = input.otlpMetricsEnabled ? input.otlpMetricsUrl : undefined;
+
+  if (tracesUrl && metricsUrl) {
+    const collapsedUrl = collapseOtelSignalsUrl({ tracesUrl, metricsUrl });
+    return collapsedUrl
+      ? `${mode}. Exporting OTEL to ${collapsedUrl}.`
+      : `${mode}. Exporting OTEL traces to ${tracesUrl} and metrics to ${metricsUrl}.`;
+  }
+
+  if (tracesUrl) {
+    return `${mode}. Exporting OTEL traces to ${tracesUrl}.`;
+  }
+
+  if (metricsUrl) {
+    return `${mode}. Exporting OTEL metrics to ${metricsUrl}.`;
+  }
+
+  return `${mode}.`;
+}
+
+export function buildProviderInstanceUpdatePatch(input: {
+  readonly settings: Pick<ServerSettings, "providers" | "providerInstances">;
+  readonly instanceId: ProviderInstanceId;
+  readonly instance: ProviderInstanceConfig;
+  readonly driver: ProviderDriverKind;
+  readonly isDefault: boolean;
+  readonly textGenerationModelSelection?:
+    | ServerSettings["textGenerationModelSelection"]
+    | undefined;
+}): Partial<UnifiedSettings> {
+  type LegacyProviderSettings = ServerSettings["providers"][keyof ServerSettings["providers"]];
+  const legacyProviderDefaults = DEFAULT_UNIFIED_SETTINGS.providers as Record<
+    string,
+    LegacyProviderSettings | undefined
+  >;
+  const legacyProviderDefault = input.isDefault ? legacyProviderDefaults[input.driver] : undefined;
+  return {
+    ...(legacyProviderDefault !== undefined
+      ? {
+          providers: {
+            ...input.settings.providers,
+            [input.driver]: legacyProviderDefault,
+          } as ServerSettings["providers"],
+        }
+      : {}),
+    providerInstances: {
+      ...input.settings.providerInstances,
+      [input.instanceId]: input.instance,
+    },
+    ...(input.textGenerationModelSelection !== undefined
+      ? { textGenerationModelSelection: input.textGenerationModelSelection }
+      : {}),
+  };
+}
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index c8766f26436..e7f21da4809 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1,27 +1,22 @@
-import {
-  ArchiveIcon,
-  ArchiveX,
-  ChevronDownIcon,
-  InfoIcon,
-  LoaderIcon,
-  PlusIcon,
-  RefreshCwIcon,
-  XIcon,
-} from "lucide-react";
+import { ArchiveIcon, ArchiveX, LoaderIcon, PlusIcon, RefreshCwIcon } from "lucide-react";
 import { useQueryClient } from "@tanstack/react-query";
-import { type ReactNode, useCallback, useMemo, useRef, useState } from "react";
+import { Link } from "@tanstack/react-router";
+import { useCallback, useMemo, useRef, useState } from "react";
 import {
+  defaultInstanceIdForDriver,
+  type DesktopUpdateChannel,
   PROVIDER_DISPLAY_NAMES,
+  ProviderDriverKind,
+  type ProviderInstanceConfig,
+  type ProviderInstanceId,
   type ScopedThreadRef,
-  type ProviderKind,
-  type ServerProvider,
-  type ServerProviderModel,
 } from "@t3tools/contracts";
 import { scopeThreadRef } from "@t3tools/client-runtime";
 import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
-import { normalizeModelSlug } from "@t3tools/shared/model";
-import { Equal } from "effect";
-import { APP_VERSION } from "../../branding";
+import { createModelSelection } from "@t3tools/shared/model";
+import * as Duration from "effect/Duration";
+import * as Equal from "effect/Equal";
+import { APP_VERSION, HOSTED_APP_CHANNEL, HOSTED_APP_CHANNEL_LABEL } from "../../branding";
 import {
   canCheckForUpdate,
   getDesktopUpdateButtonTooltip,
@@ -31,8 +26,8 @@ import {
 } from "../../components/desktopUpdate.logic";
 import { ProviderModelPicker } from "../chat/ProviderModelPicker";
 import { TraitsPicker } from "../chat/TraitsPicker";
-import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
+import { buildHostedChannelSelectionUrl, type HostedAppChannel } from "../../hostedPairing";
 import { useTheme } from "../../hooks/useTheme";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
@@ -41,27 +36,38 @@ import {
   useDesktopUpdateState,
 } from "../../lib/desktopUpdateReactQuery";
 import {
-  MAX_CUSTOM_MODEL_LENGTH,
-  getCustomModelOptionsByProvider,
+  getCustomModelOptionsByInstance,
   resolveAppModelSelectionState,
 } from "../../modelSelection";
+import {
+  deriveProviderInstanceEntries,
+  sortProviderInstanceEntries,
+} from "../../providerInstances";
 import { ensureLocalApi, readLocalApi } from "../../localApi";
 import { useShallow } from "zustand/react/shallow";
-import {
-  selectProjectsAcrossEnvironments,
-  selectThreadShellsAcrossEnvironments,
-  useStore,
-} from "../../store";
+import { selectProjectsAcrossEnvironments, useStore } from "../../store";
+import { useArchivedThreadSnapshots } from "../../lib/archivedThreadsState";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
-import { cn } from "../../lib/utils";
 import { Button } from "../ui/button";
-import { Collapsible, CollapsibleContent } from "../ui/collapsible";
-import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
-import { Input } from "../ui/input";
+import { DraftInput } from "../ui/draft-input";
 import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
 import { Switch } from "../ui/switch";
-import { toastManager } from "../ui/toast";
+import { stackedThreadToast, toastManager } from "../ui/toast";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { AddProviderInstanceDialog } from "./AddProviderInstanceDialog";
+import {
+  canOneClickUpdateProviderCandidate,
+  collectProviderUpdateCandidates,
+  hasOneClickUpdateProviderCandidate,
+  isProviderUpdateActive,
+  type ProviderUpdateCandidate,
+} from "../ProviderUpdateLaunchNotification.logic";
+import { ProviderInstanceCard } from "./ProviderInstanceCard";
+import { DRIVER_OPTIONS, getDriverOption } from "./providerDriverMeta";
+import {
+  buildProviderInstanceUpdatePatch,
+  formatDiagnosticsDescription,
+} from "./SettingsPanels.logic";
 import {
   SettingResetButton,
   SettingsPageContainer,
@@ -70,12 +76,7 @@ import {
   useRelativeTimeTick,
 } from "./settingsLayout";
 import { ProjectFavicon } from "../ProjectFavicon";
-import {
-  useServerAvailableEditors,
-  useServerKeybindingsConfigPath,
-  useServerObservability,
-  useServerProviders,
-} from "../../rpc/serverState";
+import { useServerObservability, useServerProviders } from "../../rpc/serverState";
 
 const THEME_OPTIONS = [
   {
@@ -98,106 +99,28 @@ const TIMESTAMP_FORMAT_LABELS = {
   "24-hour": "24-hour",
 } as const;
 
-type InstallProviderSettings = {
-  provider: ProviderKind;
-  title: string;
-  binaryPlaceholder: string;
-  binaryDescription: ReactNode;
-  homePathKey?: "codexHomePath";
-  homePlaceholder?: string;
-  homeDescription?: ReactNode;
-};
-
-const PROVIDER_SETTINGS: readonly InstallProviderSettings[] = [
-  {
-    provider: "codex",
-    title: "Codex",
-    binaryPlaceholder: "Codex binary path",
-    binaryDescription: "Path to the Codex binary",
-    homePathKey: "codexHomePath",
-    homePlaceholder: "CODEX_HOME",
-    homeDescription: "Optional custom Codex home and config directory.",
-  },
-  {
-    provider: "claudeAgent",
-    title: "Claude",
-    binaryPlaceholder: "Claude binary path",
-    binaryDescription: "Path to the Claude binary",
-  },
-] as const;
-
-const PROVIDER_STATUS_STYLES = {
-  disabled: {
-    dot: "bg-amber-400",
-  },
-  error: {
-    dot: "bg-destructive",
-  },
-  ready: {
-    dot: "bg-success",
-  },
-  warning: {
-    dot: "bg-warning",
-  },
-} as const;
+const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
-function getProviderSummary(provider: ServerProvider | undefined) {
-  if (!provider) {
-    return {
-      headline: "Checking provider status",
-      detail: "Waiting for the server to report installation and authentication details.",
-    };
-  }
-  if (!provider.enabled) {
-    return {
-      headline: "Disabled",
-      detail:
-        provider.message ?? "This provider is installed but disabled for new sessions in T3 Code.",
-    };
-  }
-  if (!provider.installed) {
-    return {
-      headline: "Not found",
-      detail: provider.message ?? "CLI not detected on PATH.",
-    };
-  }
-  if (provider.auth.status === "authenticated") {
-    const authLabel = provider.auth.label ?? provider.auth.type;
-    return {
-      headline: authLabel ? `Authenticated · ${authLabel}` : "Authenticated",
-      detail: provider.message ?? null,
-    };
-  }
-  if (provider.auth.status === "unauthenticated") {
-    return {
-      headline: "Not authenticated",
-      detail: provider.message ?? null,
-    };
-  }
-  if (provider.status === "warning") {
-    return {
-      headline: "Needs attention",
-      detail:
-        provider.message ?? "The provider is installed, but the server could not fully verify it.",
-    };
-  }
-  if (provider.status === "error") {
-    return {
-      headline: "Unavailable",
-      detail: provider.message ?? "The provider failed its startup checks.",
-    };
-  }
-  return {
-    headline: "Available",
-    detail: provider.message ?? "Installed and ready, but authentication could not be verified.",
-  };
+function withoutProviderInstanceKey<V>(
+  record: Readonly<Record<ProviderInstanceId, V>> | undefined,
+  key: ProviderInstanceId,
+): Record<ProviderInstanceId, V> {
+  const next = { ...record } as Record<ProviderInstanceId, V>;
+  delete next[key];
+  return next;
 }
 
-function getProviderVersionLabel(version: string | null | undefined) {
-  if (!version) return null;
-  return version.startsWith("v") ? version : `v${version}`;
+function withoutProviderInstanceFavorites(
+  favorites: ReadonlyArray<{ readonly provider: ProviderInstanceId; readonly model: string }>,
+  instanceId: ProviderInstanceId,
+) {
+  return favorites.filter((favorite) => favorite.provider !== instanceId);
 }
 
+const PROVIDER_SETTINGS = DRIVER_OPTIONS.map((definition) => ({
+  provider: definition.value,
+}));
+
 function ProviderLastChecked({ lastCheckedAt }: { lastCheckedAt: string | null }) {
   useRelativeTimeTick();
   const lastCheckedRelative = lastCheckedAt ? formatRelativeTime(lastCheckedAt) : null;
@@ -232,8 +155,45 @@ function AboutVersionTitle() {
 function AboutVersionSection() {
   const queryClient = useQueryClient();
   const updateStateQuery = useDesktopUpdateState();
+  const [isChangingUpdateChannel, setIsChangingUpdateChannel] = useState(false);
 
   const updateState = updateStateQuery.data ?? null;
+  const hasDesktopBridge = typeof window !== "undefined" && Boolean(window.desktopBridge);
+  const selectedUpdateChannel = updateState?.channel ?? "latest";
+  const selectedHostedAppChannel = hasDesktopBridge ? null : HOSTED_APP_CHANNEL;
+
+  const handleUpdateChannelChange = useCallback(
+    (channel: DesktopUpdateChannel) => {
+      const bridge = window.desktopBridge;
+      if (
+        !bridge ||
+        typeof bridge.setUpdateChannel !== "function" ||
+        channel === selectedUpdateChannel
+      ) {
+        return;
+      }
+
+      setIsChangingUpdateChannel(true);
+      void bridge
+        .setUpdateChannel(channel)
+        .then((state) => {
+          setDesktopUpdateStateQueryData(queryClient, state);
+        })
+        .catch((error: unknown) => {
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not change update track",
+              description: error instanceof Error ? error.message : "Update track change failed.",
+            }),
+          );
+        })
+        .finally(() => {
+          setIsChangingUpdateChannel(false);
+        });
+    },
+    [queryClient, selectedUpdateChannel],
+  );
 
   const handleButtonClick = useCallback(() => {
     const bridge = window.desktopBridge;
@@ -248,11 +208,13 @@ function AboutVersionSection() {
           setDesktopUpdateStateQueryData(queryClient, result.state);
         })
         .catch((error: unknown) => {
-          toastManager.add({
-            type: "error",
-            title: "Could not download update",
-            description: error instanceof Error ? error.message : "Download failed.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not download update",
+              description: error instanceof Error ? error.message : "Download failed.",
+            }),
+          );
         });
       return;
     }
@@ -270,11 +232,13 @@ function AboutVersionSection() {
           setDesktopUpdateStateQueryData(queryClient, result.state);
         })
         .catch((error: unknown) => {
-          toastManager.add({
-            type: "error",
-            title: "Could not install update",
-            description: error instanceof Error ? error.message : "Install failed.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not install update",
+              description: error instanceof Error ? error.message : "Install failed.",
+            }),
+          );
         });
       return;
     }
@@ -285,20 +249,24 @@ function AboutVersionSection() {
       .then((result) => {
         setDesktopUpdateStateQueryData(queryClient, result.state);
         if (!result.checked) {
-          toastManager.add({
-            type: "error",
-            title: "Could not check for updates",
-            description:
-              result.state.message ?? "Automatic updates are not available in this build.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not check for updates",
+              description:
+                result.state.message ?? "Automatic updates are not available in this build.",
+            }),
+          );
         }
       })
       .catch((error: unknown) => {
-        toastManager.add({
-          type: "error",
-          title: "Could not check for updates",
-          description: error instanceof Error ? error.message : "Update check failed.",
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not check for updates",
+            description: error instanceof Error ? error.message : "Update check failed.",
+          }),
+        );
       });
   }, [queryClient, updateState]);
 
@@ -323,44 +291,101 @@ function AboutVersionSection() {
       : "Current version of the application.";
 
   return (
-    <SettingsRow
-      title={<AboutVersionTitle />}
-      description={description}
-      control={
-        <Tooltip>
-          <TooltipTrigger
-            render={
-              <Button
-                size="xs"
-                variant={action === "install" ? "default" : "outline"}
-                disabled={buttonDisabled}
-                onClick={handleButtonClick}
+    <>
+      <SettingsRow
+        title={<AboutVersionTitle />}
+        description={description}
+        control={
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <Button
+                  size="xs"
+                  variant={action === "install" ? "default" : "outline"}
+                  disabled={buttonDisabled}
+                  onClick={handleButtonClick}
+                >
+                  {buttonLabel}
+                </Button>
+              }
+            />
+            {buttonTooltip ? <TooltipPopup>{buttonTooltip}</TooltipPopup> : null}
+          </Tooltip>
+        }
+      />
+      {hasDesktopBridge ? (
+        <SettingsRow
+          title="Update track"
+          description="Stable follows full releases. Nightly follows the nightly desktop channel and can switch back to stable immediately."
+          control={
+            <Select
+              value={selectedUpdateChannel}
+              onValueChange={(value) => {
+                handleUpdateChannelChange(value as DesktopUpdateChannel);
+              }}
+            >
+              <SelectTrigger
+                className="w-full sm:w-40"
+                aria-label="Update track"
+                disabled={isChangingUpdateChannel}
               >
-                {buttonLabel}
-              </Button>
-            }
-          />
-          {buttonTooltip ? <TooltipPopup>{buttonTooltip}</TooltipPopup> : null}
-        </Tooltip>
-      }
-    />
+                <SelectValue>
+                  {selectedUpdateChannel === "nightly" ? "Nightly" : "Stable"}
+                </SelectValue>
+              </SelectTrigger>
+              <SelectPopup align="end" alignItemWithTrigger={false}>
+                <SelectItem hideIndicator value="latest">
+                  Stable
+                </SelectItem>
+                <SelectItem hideIndicator value="nightly">
+                  Nightly
+                </SelectItem>
+              </SelectPopup>
+            </Select>
+          }
+        />
+      ) : selectedHostedAppChannel ? (
+        <SettingsRow
+          title="Update track"
+          description="Switches the hosted app release channel."
+          control={
+            <Select
+              value={selectedHostedAppChannel}
+              onValueChange={(value) => {
+                if (value === selectedHostedAppChannel) return;
+                window.location.assign(
+                  buildHostedChannelSelectionUrl({ channel: value as HostedAppChannel }),
+                );
+              }}
+            >
+              <SelectTrigger className="w-full sm:w-40" aria-label="Update track">
+                <SelectValue>{HOSTED_APP_CHANNEL_LABEL}</SelectValue>
+              </SelectTrigger>
+              <SelectPopup align="end" alignItemWithTrigger={false}>
+                <SelectItem hideIndicator value="latest">
+                  Latest
+                </SelectItem>
+                <SelectItem hideIndicator value="nightly">
+                  Nightly
+                </SelectItem>
+              </SelectPopup>
+            </Select>
+          }
+        />
+      ) : null}
+    </>
   );
 }
 
 export function useSettingsRestore(onRestored?: () => void) {
   const { theme, setTheme } = useTheme();
   const settings = useSettings();
-  const { resetSettings } = useUpdateSettings();
+  const { updateSettings } = useUpdateSettings();
 
   const isGitWritingModelDirty = !Equal.equals(
     settings.textGenerationModelSelection ?? null,
     DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection ?? null,
   );
-  const areProviderSettingsDirty = PROVIDER_SETTINGS.some((providerSettings) => {
-    const currentSettings = settings.providers[providerSettings.provider];
-    const defaultSettings = DEFAULT_UNIFIED_SETTINGS.providers[providerSettings.provider];
-    return !Equal.equals(currentSettings, defaultSettings);
-  });
 
   const changedSettingLabels = useMemo(
     () => [
@@ -368,15 +393,31 @@ export function useSettingsRestore(onRestored?: () => void) {
       ...(settings.timestampFormat !== DEFAULT_UNIFIED_SETTINGS.timestampFormat
         ? ["Time format"]
         : []),
+      ...(settings.sidebarThreadPreviewCount !== DEFAULT_UNIFIED_SETTINGS.sidebarThreadPreviewCount
+        ? ["Visible threads"]
+        : []),
       ...(settings.diffWordWrap !== DEFAULT_UNIFIED_SETTINGS.diffWordWrap
         ? ["Diff line wrapping"]
         : []),
+      ...(settings.diffIgnoreWhitespace !== DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace
+        ? ["Diff whitespace changes"]
+        : []),
+      ...(settings.autoOpenPlanSidebar !== DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar
+        ? ["Auto-open task panel"]
+        : []),
       ...(settings.enableAssistantStreaming !== DEFAULT_UNIFIED_SETTINGS.enableAssistantStreaming
         ? ["Assistant output"]
         : []),
+      ...(Duration.toMillis(settings.automaticGitFetchInterval) !==
+      Duration.toMillis(DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval)
+        ? ["Automatic Git fetch interval"]
+        : []),
       ...(settings.defaultThreadEnvMode !== DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode
         ? ["New thread mode"]
         : []),
+      ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
+        ? ["Add project base directory"]
+        : []),
       ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
         ? ["Archive confirmation"]
         : []),
@@ -384,16 +425,19 @@ export function useSettingsRestore(onRestored?: () => void) {
         ? ["Delete confirmation"]
         : []),
       ...(isGitWritingModelDirty ? ["Git writing model"] : []),
-      ...(areProviderSettingsDirty ? ["Providers"] : []),
     ],
     [
-      areProviderSettingsDirty,
       isGitWritingModelDirty,
+      settings.autoOpenPlanSidebar,
       settings.confirmThreadArchive,
       settings.confirmThreadDelete,
+      settings.addProjectBaseDirectory,
       settings.defaultThreadEnvMode,
+      settings.diffIgnoreWhitespace,
       settings.diffWordWrap,
+      settings.automaticGitFetchInterval,
       settings.enableAssistantStreaming,
+      settings.sidebarThreadPreviewCount,
       settings.timestampFormat,
       theme,
     ],
@@ -410,9 +454,22 @@ export function useSettingsRestore(onRestored?: () => void) {
     if (!confirmed) return;
 
     setTheme("system");
-    resetSettings();
+    updateSettings({
+      timestampFormat: DEFAULT_UNIFIED_SETTINGS.timestampFormat,
+      diffWordWrap: DEFAULT_UNIFIED_SETTINGS.diffWordWrap,
+      diffIgnoreWhitespace: DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace,
+      sidebarThreadPreviewCount: DEFAULT_UNIFIED_SETTINGS.sidebarThreadPreviewCount,
+      autoOpenPlanSidebar: DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar,
+      enableAssistantStreaming: DEFAULT_UNIFIED_SETTINGS.enableAssistantStreaming,
+      automaticGitFetchInterval: DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
+      defaultThreadEnvMode: DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode,
+      addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
+      confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
+      confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+      textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
+    });
     onRestored?.();
-  }, [changedSettingLabels, onRestored, resetSettings, setTheme]);
+  }, [changedSettingLabels, onRestored, setTheme, updateSettings]);
 
   return {
     changedSettingLabels,
@@ -424,78 +481,32 @@ export function GeneralSettingsPanel() {
   const { theme, setTheme } = useTheme();
   const settings = useSettings();
   const { updateSettings } = useUpdateSettings();
-  const [openingPathByTarget, setOpeningPathByTarget] = useState({
-    keybindings: false,
-    logsDirectory: false,
-  });
-  const [openPathErrorByTarget, setOpenPathErrorByTarget] = useState<
-    Partial<Record<"keybindings" | "logsDirectory", string | null>>
-  >({});
-  const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
-    codex: Boolean(
-      settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
-      settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
-      settings.providers.codex.customModels.length > 0,
-    ),
-    claudeAgent: Boolean(
-      settings.providers.claudeAgent.binaryPath !==
-        DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
-      settings.providers.claudeAgent.customModels.length > 0,
-    ),
-  });
-  const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
-    Record<ProviderKind, string>
-  >({
-    codex: "",
-    claudeAgent: "",
-  });
-  const [customModelErrorByProvider, setCustomModelErrorByProvider] = useState<
-    Partial<Record<ProviderKind, string | null>>
-  >({});
-  const [isRefreshingProviders, setIsRefreshingProviders] = useState(false);
-  const refreshingRef = useRef(false);
-  const modelListRefs = useRef<Partial<Record<ProviderKind, HTMLDivElement | null>>>({});
-  const refreshProviders = useCallback(() => {
-    if (refreshingRef.current) return;
-    refreshingRef.current = true;
-    setIsRefreshingProviders(true);
-    void ensureLocalApi()
-      .server.refreshProviders()
-      .catch((error: unknown) => {
-        console.warn("Failed to refresh providers", error);
-      })
-      .finally(() => {
-        refreshingRef.current = false;
-        setIsRefreshingProviders(false);
-      });
-  }, []);
-
-  const keybindingsConfigPath = useServerKeybindingsConfigPath();
-  const availableEditors = useServerAvailableEditors();
   const observability = useServerObservability();
   const serverProviders = useServerProviders();
-  const codexHomePath = settings.providers.codex.homePath;
-  const logsDirectoryPath = observability?.logsDirectoryPath ?? null;
-  const diagnosticsDescription = (() => {
-    const exports: string[] = [];
-    if (observability?.otlpTracesEnabled && observability.otlpTracesUrl) {
-      exports.push(`traces to ${observability.otlpTracesUrl}`);
-    }
-    if (observability?.otlpMetricsEnabled && observability.otlpMetricsUrl) {
-      exports.push(`metrics to ${observability.otlpMetricsUrl}`);
-    }
-    const mode = observability?.localTracingEnabled ? "Local trace file" : "Terminal logs only";
-    return exports.length > 0 ? `${mode}. OTLP exporting ${exports.join(" and ")}.` : `${mode}.`;
-  })();
+  const diagnosticsDescription = formatDiagnosticsDescription({
+    localTracingEnabled: observability?.localTracingEnabled ?? false,
+    otlpTracesEnabled: observability?.otlpTracesEnabled ?? false,
+    otlpTracesUrl: observability?.otlpTracesUrl,
+    otlpMetricsEnabled: observability?.otlpMetricsEnabled ?? false,
+    otlpMetricsUrl: observability?.otlpMetricsUrl,
+  });
 
   const textGenerationModelSelection = resolveAppModelSelectionState(settings, serverProviders);
-  const textGenProvider = textGenerationModelSelection.provider;
+  const textGenInstanceId = textGenerationModelSelection.instanceId;
   const textGenModel = textGenerationModelSelection.model;
   const textGenModelOptions = textGenerationModelSelection.options;
-  const gitModelOptionsByProvider = getCustomModelOptionsByProvider(
+  const gitModelInstanceEntries = sortProviderInstanceEntries(
+    deriveProviderInstanceEntries(serverProviders),
+  );
+  const textGenInstanceEntry = gitModelInstanceEntries.find(
+    (entry) => entry.instanceId === textGenInstanceId,
+  );
+  const textGenProvider: ProviderDriverKind =
+    textGenInstanceEntry?.driverKind ?? DEFAULT_DRIVER_KIND;
+  const gitModelOptionsByInstance = getCustomModelOptionsByInstance(
     settings,
     serverProviders,
-    textGenProvider,
+    textGenInstanceId,
     textGenModel,
   );
   const isGitWritingModelDirty = !Equal.equals(
@@ -503,185 +514,6 @@ export function GeneralSettingsPanel() {
     DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection ?? null,
   );
 
-  const openInPreferredEditor = useCallback(
-    (target: "keybindings" | "logsDirectory", path: string | null, failureMessage: string) => {
-      if (!path) return;
-      setOpenPathErrorByTarget((existing) => ({ ...existing, [target]: null }));
-      setOpeningPathByTarget((existing) => ({ ...existing, [target]: true }));
-
-      const editor = resolveAndPersistPreferredEditor(availableEditors ?? []);
-      if (!editor) {
-        setOpenPathErrorByTarget((existing) => ({
-          ...existing,
-          [target]: "No available editors found.",
-        }));
-        setOpeningPathByTarget((existing) => ({ ...existing, [target]: false }));
-        return;
-      }
-
-      void ensureLocalApi()
-        .shell.openInEditor(path, editor)
-        .catch((error) => {
-          setOpenPathErrorByTarget((existing) => ({
-            ...existing,
-            [target]: error instanceof Error ? error.message : failureMessage,
-          }));
-        })
-        .finally(() => {
-          setOpeningPathByTarget((existing) => ({ ...existing, [target]: false }));
-        });
-    },
-    [availableEditors],
-  );
-
-  const openKeybindingsFile = useCallback(() => {
-    openInPreferredEditor("keybindings", keybindingsConfigPath, "Unable to open keybindings file.");
-  }, [keybindingsConfigPath, openInPreferredEditor]);
-
-  const openLogsDirectory = useCallback(() => {
-    openInPreferredEditor("logsDirectory", logsDirectoryPath, "Unable to open logs folder.");
-  }, [logsDirectoryPath, openInPreferredEditor]);
-
-  const openKeybindingsError = openPathErrorByTarget.keybindings ?? null;
-  const openDiagnosticsError = openPathErrorByTarget.logsDirectory ?? null;
-  const isOpeningKeybindings = openingPathByTarget.keybindings;
-  const isOpeningLogsDirectory = openingPathByTarget.logsDirectory;
-
-  const addCustomModel = useCallback(
-    (provider: ProviderKind) => {
-      const customModelInput = customModelInputByProvider[provider];
-      const customModels = settings.providers[provider].customModels;
-      const normalized = normalizeModelSlug(customModelInput, provider);
-      if (!normalized) {
-        setCustomModelErrorByProvider((existing) => ({
-          ...existing,
-          [provider]: "Enter a model slug.",
-        }));
-        return;
-      }
-      if (
-        serverProviders
-          .find((candidate) => candidate.provider === provider)
-          ?.models.some((option) => !option.isCustom && option.slug === normalized)
-      ) {
-        setCustomModelErrorByProvider((existing) => ({
-          ...existing,
-          [provider]: "That model is already built in.",
-        }));
-        return;
-      }
-      if (normalized.length > MAX_CUSTOM_MODEL_LENGTH) {
-        setCustomModelErrorByProvider((existing) => ({
-          ...existing,
-          [provider]: `Model slugs must be ${MAX_CUSTOM_MODEL_LENGTH} characters or less.`,
-        }));
-        return;
-      }
-      if (customModels.includes(normalized)) {
-        setCustomModelErrorByProvider((existing) => ({
-          ...existing,
-          [provider]: "That custom model is already saved.",
-        }));
-        return;
-      }
-
-      updateSettings({
-        providers: {
-          ...settings.providers,
-          [provider]: {
-            ...settings.providers[provider],
-            customModels: [...customModels, normalized],
-          },
-        },
-      });
-      setCustomModelInputByProvider((existing) => ({
-        ...existing,
-        [provider]: "",
-      }));
-      setCustomModelErrorByProvider((existing) => ({
-        ...existing,
-        [provider]: null,
-      }));
-
-      const el = modelListRefs.current[provider];
-      if (!el) return;
-      const scrollToEnd = () => el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
-      requestAnimationFrame(scrollToEnd);
-      const observer = new MutationObserver(() => {
-        scrollToEnd();
-        observer.disconnect();
-      });
-      observer.observe(el, { childList: true, subtree: true });
-      setTimeout(() => observer.disconnect(), 2_000);
-    },
-    [customModelInputByProvider, serverProviders, settings, updateSettings],
-  );
-
-  const removeCustomModel = useCallback(
-    (provider: ProviderKind, slug: string) => {
-      updateSettings({
-        providers: {
-          ...settings.providers,
-          [provider]: {
-            ...settings.providers[provider],
-            customModels: settings.providers[provider].customModels.filter(
-              (model) => model !== slug,
-            ),
-          },
-        },
-      });
-      setCustomModelErrorByProvider((existing) => ({
-        ...existing,
-        [provider]: null,
-      }));
-    },
-    [settings, updateSettings],
-  );
-
-  const providerCards = PROVIDER_SETTINGS.map((providerSettings) => {
-    const liveProvider = serverProviders.find(
-      (candidate) => candidate.provider === providerSettings.provider,
-    );
-    const providerConfig = settings.providers[providerSettings.provider];
-    const defaultProviderConfig = DEFAULT_UNIFIED_SETTINGS.providers[providerSettings.provider];
-    const statusKey = liveProvider?.status ?? (providerConfig.enabled ? "warning" : "disabled");
-    const summary = getProviderSummary(liveProvider);
-    const models: ReadonlyArray<ServerProviderModel> =
-      liveProvider?.models ??
-      providerConfig.customModels.map((slug) => ({
-        slug,
-        name: slug,
-        isCustom: true,
-        capabilities: null,
-      }));
-
-    return {
-      provider: providerSettings.provider,
-      title: providerSettings.title,
-      binaryPlaceholder: providerSettings.binaryPlaceholder,
-      binaryDescription: providerSettings.binaryDescription,
-      homePathKey: providerSettings.homePathKey,
-      homePlaceholder: providerSettings.homePlaceholder,
-      homeDescription: providerSettings.homeDescription,
-      binaryPathValue: providerConfig.binaryPath,
-      isDirty: !Equal.equals(providerConfig, defaultProviderConfig),
-      liveProvider,
-      models,
-      providerConfig,
-      statusStyle: PROVIDER_STATUS_STYLES[statusKey],
-      summary,
-      versionLabel: getProviderVersionLabel(liveProvider?.version),
-    };
-  });
-
-  const lastCheckedAt =
-    serverProviders.length > 0
-      ? serverProviders.reduce(
-          (latest, provider) => (provider.checkedAt > latest ? provider.checkedAt : latest),
-          serverProviders[0]!.checkedAt,
-        )
-      : null;
-
   return (
     <SettingsPageContainer>
       <SettingsSection title="General">
@@ -784,6 +616,32 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        <SettingsRow
+          title="Hide whitespace changes"
+          description="Set whether the diff panel ignores whitespace-only edits by default."
+          resetAction={
+            settings.diffIgnoreWhitespace !== DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace ? (
+              <SettingResetButton
+                label="diff whitespace changes"
+                onClick={() =>
+                  updateSettings({
+                    diffIgnoreWhitespace: DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <Switch
+              checked={settings.diffIgnoreWhitespace}
+              onCheckedChange={(checked) =>
+                updateSettings({ diffIgnoreWhitespace: Boolean(checked) })
+              }
+              aria-label="Hide whitespace changes by default"
+            />
+          }
+        />
+
         <SettingsRow
           title="Assistant output"
           description="Show token-by-token output while a response is in progress."
@@ -811,6 +669,32 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        <SettingsRow
+          title="Auto-open task panel"
+          description="Open the right-side plan and task panel automatically when steps appear."
+          resetAction={
+            settings.autoOpenPlanSidebar !== DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar ? (
+              <SettingResetButton
+                label="auto-open task panel"
+                onClick={() =>
+                  updateSettings({
+                    autoOpenPlanSidebar: DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <Switch
+              checked={settings.autoOpenPlanSidebar}
+              onCheckedChange={(checked) =>
+                updateSettings({ autoOpenPlanSidebar: Boolean(checked) })
+              }
+              aria-label="Open the task panel automatically"
+            />
+          }
+        />
+
         <SettingsRow
           title="New threads"
           description="Pick the default workspace mode for newly created draft threads."
@@ -852,6 +736,34 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        <SettingsRow
+          title="Add project starts in"
+          description='Leave empty to use "~/" when the Add Project browser opens.'
+          resetAction={
+            settings.addProjectBaseDirectory !==
+            DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory ? (
+              <SettingResetButton
+                label="add project base directory"
+                onClick={() =>
+                  updateSettings({
+                    addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <DraftInput
+              className="w-full sm:w-72"
+              value={settings.addProjectBaseDirectory}
+              onCommit={(next) => updateSettings({ addProjectBaseDirectory: next })}
+              placeholder="~/"
+              spellCheck={false}
+              aria-label="Add project base directory"
+            />
+          }
+        />
+
         <SettingsRow
           title="Archive confirmation"
           description="Require a second click on the inline archive action before a thread is archived."
@@ -923,19 +835,19 @@ export function GeneralSettingsPanel() {
           control={
             <div className="flex flex-wrap items-center justify-end gap-1.5">
               <ProviderModelPicker
-                provider={textGenProvider}
+                activeInstanceId={textGenInstanceId}
                 model={textGenModel}
                 lockedProvider={null}
-                providers={serverProviders}
-                modelOptionsByProvider={gitModelOptionsByProvider}
+                instanceEntries={gitModelInstanceEntries}
+                modelOptionsByInstance={gitModelOptionsByInstance}
                 triggerVariant="outline"
                 triggerClassName="min-w-0 max-w-none shrink-0 text-foreground/90 hover:text-foreground"
-                onProviderModelChange={(provider, model) => {
+                onInstanceModelChange={(instanceId, model) => {
                   updateSettings({
                     textGenerationModelSelection: resolveAppModelSelectionState(
                       {
                         ...settings,
-                        textGenerationModelSelection: { provider, model },
+                        textGenerationModelSelection: createModelSelection(instanceId, model),
                       },
                       serverProviders,
                     ),
@@ -945,8 +857,11 @@ export function GeneralSettingsPanel() {
               <TraitsPicker
                 provider={textGenProvider}
                 models={
-                  serverProviders.find((provider) => provider.provider === textGenProvider)
-                    ?.models ?? []
+                  // Use the exact instance's models (rather than the
+                  // first-kind-match) so a custom text-gen instance like
+                  // `codex_personal` gets its own model list, not the
+                  // default Codex one.
+                  textGenInstanceEntry?.models ?? []
                 }
                 model={textGenModel}
                 prompt=""
@@ -960,11 +875,11 @@ export function GeneralSettingsPanel() {
                     textGenerationModelSelection: resolveAppModelSelectionState(
                       {
                         ...settings,
-                        textGenerationModelSelection: {
-                          provider: textGenProvider,
-                          model: textGenModel,
-                          ...(nextOptions ? { options: nextOptions } : {}),
-                        },
+                        textGenerationModelSelection: createModelSelection(
+                          textGenInstanceId,
+                          textGenModel,
+                          nextOptions,
+                        ),
                       },
                       serverProviders,
                     ),
@@ -976,11 +891,314 @@ export function GeneralSettingsPanel() {
         />
       </SettingsSection>
 
+      <SettingsSection title="About">
+        {isElectron || HOSTED_APP_CHANNEL ? (
+          <AboutVersionSection />
+        ) : (
+          <SettingsRow
+            title={<AboutVersionTitle />}
+            description="Current version of the application."
+          />
+        )}
+        <SettingsRow
+          title="Diagnostics"
+          description={diagnosticsDescription}
+          control={
+            <Button render={<Link to="/settings/diagnostics" />} size="xs" variant="outline">
+              View diagnostics
+            </Button>
+          }
+        />
+      </SettingsSection>
+    </SettingsPageContainer>
+  );
+}
+
+export function ProviderSettingsPanel() {
+  const settings = useSettings();
+  const { updateSettings } = useUpdateSettings();
+  const serverProviders = useServerProviders();
+  const [isRefreshingProviders, setIsRefreshingProviders] = useState(false);
+  const [isAddInstanceDialogOpen, setIsAddInstanceDialogOpen] = useState(false);
+  const [updatingProviderDrivers, setUpdatingProviderDrivers] = useState<
+    ReadonlySet<ProviderDriverKind>
+  >(() => new Set());
+  const [openInstanceDetails, setOpenInstanceDetails] = useState<Record<string, boolean>>({});
+  const refreshingRef = useRef(false);
+
+  const providerUpdateCandidates = useMemo(
+    () => collectProviderUpdateCandidates(serverProviders),
+    [serverProviders],
+  );
+  const providerUpdateCandidateByInstanceId = useMemo(
+    () => new Map(providerUpdateCandidates.map((candidate) => [candidate.instanceId, candidate])),
+    [providerUpdateCandidates],
+  );
+  const visibleProviderSettings = PROVIDER_SETTINGS.filter(
+    (providerSettings) =>
+      providerSettings.provider !== "cursor" ||
+      serverProviders.some(
+        (provider) =>
+          provider.instanceId === defaultInstanceIdForDriver(ProviderDriverKind.make("cursor")),
+      ),
+  );
+  const textGenerationModelSelection = resolveAppModelSelectionState(settings, serverProviders);
+  const textGenInstanceId = textGenerationModelSelection.instanceId;
+  const lastCheckedAt =
+    serverProviders.length > 0
+      ? serverProviders.reduce(
+          (latest, provider) => (provider.checkedAt > latest ? provider.checkedAt : latest),
+          serverProviders[0]!.checkedAt,
+        )
+      : null;
+
+  const refreshProviders = useCallback(() => {
+    if (refreshingRef.current) return;
+    refreshingRef.current = true;
+    setIsRefreshingProviders(true);
+    void ensureLocalApi()
+      .server.refreshProviders()
+      .catch((error: unknown) => {
+        console.warn("Failed to refresh providers", error);
+      })
+      .finally(() => {
+        refreshingRef.current = false;
+        setIsRefreshingProviders(false);
+      });
+  }, []);
+
+  const runProviderUpdate = useCallback(async (candidate: ProviderUpdateCandidate) => {
+    let started = false;
+    setUpdatingProviderDrivers((previous) => {
+      if (previous.has(candidate.driver)) {
+        return previous;
+      }
+      started = true;
+      const next = new Set(previous);
+      next.add(candidate.driver);
+      return next;
+    });
+    if (!started) {
+      return;
+    }
+
+    try {
+      await ensureLocalApi().server.updateProvider({
+        provider: candidate.driver,
+        instanceId: candidate.instanceId,
+      });
+    } catch (error) {
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: `Could not update ${PROVIDER_DISPLAY_NAMES[candidate.driver] ?? candidate.driver}`,
+          description:
+            error instanceof Error
+              ? error.message
+              : "The provider update command could not be started.",
+        }),
+      );
+    } finally {
+      setUpdatingProviderDrivers((previous) => {
+        if (!previous.has(candidate.driver)) {
+          return previous;
+        }
+        const next = new Set(previous);
+        next.delete(candidate.driver);
+        return next;
+      });
+    }
+  }, []);
+
+  interface InstanceRow {
+    readonly instanceId: ProviderInstanceId;
+    readonly instance: ProviderInstanceConfig;
+    readonly driver: ProviderDriverKind;
+    readonly isDefault: boolean;
+    readonly isDirty?: boolean;
+  }
+
+  const instancesByDriver = new Map<
+    ProviderDriverKind,
+    Array<[ProviderInstanceId, ProviderInstanceConfig]>
+  >();
+  for (const [rawId, instance] of Object.entries(settings.providerInstances ?? {})) {
+    const driver = instance.driver;
+    const list = instancesByDriver.get(driver) ?? [];
+    list.push([rawId as ProviderInstanceId, instance]);
+    instancesByDriver.set(driver, list);
+  }
+
+  const defaultSlotIdsBySource = new Set<string>(
+    visibleProviderSettings.map((providerSettings) =>
+      String(defaultInstanceIdForDriver(providerSettings.provider)),
+    ),
+  );
+
+  const rows: InstanceRow[] = [];
+  const visibleDriverKinds = new Set<ProviderDriverKind>(
+    visibleProviderSettings.map((providerSettings) => providerSettings.provider),
+  );
+
+  for (const providerSettings of visibleProviderSettings) {
+    type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
+    const legacyProviders = settings.providers as Record<string, LegacyProviderSettings>;
+    const defaultLegacyProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
+      string,
+      LegacyProviderSettings
+    >;
+    const driver = providerSettings.provider;
+    const defaultInstanceId = defaultInstanceIdForDriver(driver);
+    const explicitInstance = settings.providerInstances?.[defaultInstanceId];
+    const legacyConfig = legacyProviders[providerSettings.provider]!;
+    const defaultLegacyConfig = defaultLegacyProviders[providerSettings.provider]!;
+    const effectiveInstance: ProviderInstanceConfig =
+      explicitInstance ??
+      ({
+        driver,
+        enabled: legacyConfig.enabled,
+        config: legacyConfig,
+      } satisfies ProviderInstanceConfig);
+    const isDirty =
+      explicitInstance !== undefined || !Equal.equals(legacyConfig, defaultLegacyConfig);
+    rows.push({
+      instanceId: defaultInstanceId,
+      instance: effectiveInstance,
+      driver,
+      isDefault: true,
+      isDirty,
+    });
+    for (const [id, instance] of instancesByDriver.get(providerSettings.provider) ?? []) {
+      if (id === defaultInstanceId) continue;
+      rows.push({ instanceId: id, instance, driver: instance.driver, isDefault: false });
+    }
+  }
+  for (const [driver, list] of instancesByDriver) {
+    if (visibleDriverKinds.has(driver)) continue;
+    for (const [id, instance] of list) {
+      rows.push({
+        instanceId: id,
+        instance,
+        driver: instance.driver,
+        isDefault: defaultSlotIdsBySource.has(String(id)),
+      });
+    }
+  }
+
+  const updateProviderInstance = (
+    row: InstanceRow,
+    next: ProviderInstanceConfig,
+    options?: {
+      readonly textGenerationModelSelection?: Parameters<
+        typeof buildProviderInstanceUpdatePatch
+      >[0]["textGenerationModelSelection"];
+    },
+  ) => {
+    updateSettings(
+      buildProviderInstanceUpdatePatch({
+        settings,
+        instanceId: row.instanceId,
+        instance: next,
+        driver: row.driver,
+        isDefault: row.isDefault,
+        textGenerationModelSelection: options?.textGenerationModelSelection,
+      }),
+    );
+  };
+
+  const deleteProviderInstance = (id: ProviderInstanceId) => {
+    updateSettings({
+      providerInstances: withoutProviderInstanceKey(settings.providerInstances, id),
+      providerModelPreferences: withoutProviderInstanceKey(settings.providerModelPreferences, id),
+      favorites: withoutProviderInstanceFavorites(settings.favorites ?? [], id),
+    });
+  };
+
+  const updateProviderModelPreferences = (
+    instanceId: ProviderInstanceId,
+    next: {
+      readonly hiddenModels: ReadonlyArray<string>;
+      readonly modelOrder: ReadonlyArray<string>;
+    },
+  ) => {
+    const hiddenModels = [...new Set(next.hiddenModels.filter((slug) => slug.trim().length > 0))];
+    const modelOrder = [...new Set(next.modelOrder.filter((slug) => slug.trim().length > 0))];
+    const rest = withoutProviderInstanceKey(settings.providerModelPreferences, instanceId);
+    updateSettings({
+      providerModelPreferences:
+        hiddenModels.length === 0 && modelOrder.length === 0
+          ? rest
+          : {
+              ...rest,
+              [instanceId]: {
+                hiddenModels,
+                modelOrder,
+              },
+            },
+    });
+  };
+
+  const updateProviderFavoriteModels = (
+    instanceId: ProviderInstanceId,
+    nextFavoriteModels: ReadonlyArray<string>,
+  ) => {
+    const favoriteModels = [
+      ...new Set(nextFavoriteModels.map((slug) => slug.trim()).filter((slug) => slug.length > 0)),
+    ];
+    updateSettings({
+      favorites: [
+        ...withoutProviderInstanceFavorites(settings.favorites ?? [], instanceId),
+        ...favoriteModels.map((model) => ({ provider: instanceId, model })),
+      ],
+    });
+  };
+
+  const resetDefaultInstance = (driverKind: ProviderDriverKind) => {
+    type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
+    const defaultLegacyProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
+      string,
+      LegacyProviderSettings | undefined
+    >;
+    const defaultInstanceId = defaultInstanceIdForDriver(driverKind);
+    const defaultLegacyProvider = defaultLegacyProviders[driverKind];
+    if (defaultLegacyProvider === undefined) return;
+    updateSettings({
+      providers: {
+        ...settings.providers,
+        [driverKind]: defaultLegacyProvider,
+      } as typeof settings.providers,
+      providerInstances: withoutProviderInstanceKey(settings.providerInstances, defaultInstanceId),
+      providerModelPreferences: withoutProviderInstanceKey(
+        settings.providerModelPreferences,
+        defaultInstanceId,
+      ),
+      favorites: withoutProviderInstanceFavorites(settings.favorites ?? [], defaultInstanceId),
+    });
+  };
+
+  return (
+    <SettingsPageContainer>
       <SettingsSection
         title="Providers"
         headerAction={
           <div className="flex items-center gap-1.5">
             <ProviderLastChecked lastCheckedAt={lastCheckedAt} />
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <Button
+                    size="icon-xs"
+                    variant="ghost"
+                    className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+                    onClick={() => setIsAddInstanceDialogOpen(true)}
+                    aria-label="Add provider instance"
+                  >
+                    <PlusIcon className="size-3" />
+                  </Button>
+                }
+              />
+              <TooltipPopup side="top">Add provider instance</TooltipPopup>
+            </Tooltip>
             <Tooltip>
               <TooltipTrigger
                 render={
@@ -1005,395 +1223,160 @@ export function GeneralSettingsPanel() {
           </div>
         }
       >
-        {providerCards.map((providerCard) => {
-          const customModelInput = customModelInputByProvider[providerCard.provider];
-          const customModelError = customModelErrorByProvider[providerCard.provider] ?? null;
-          const providerDisplayName =
-            PROVIDER_DISPLAY_NAMES[providerCard.provider] ?? providerCard.title;
-
+        {rows.map((row) => {
+          const driverOption = getDriverOption(row.driver);
+          const liveProvider = serverProviders.find(
+            (candidate) => candidate.instanceId === row.instanceId,
+          );
+          const updateCandidate = liveProvider
+            ? providerUpdateCandidateByInstanceId.get(liveProvider.instanceId)
+            : undefined;
+          const isDriverUpdateRunning =
+            updateCandidate !== undefined &&
+            (updatingProviderDrivers.has(updateCandidate.driver) ||
+              serverProviders.some(
+                (provider) =>
+                  provider.driver === updateCandidate.driver && isProviderUpdateActive(provider),
+              ));
+          const showInlineUpdateButton =
+            updateCandidate !== undefined &&
+            hasOneClickUpdateProviderCandidate(updateCandidate, serverProviders);
+          const canRunInlineUpdate =
+            updateCandidate !== undefined &&
+            canOneClickUpdateProviderCandidate(updateCandidate, serverProviders) &&
+            !updatingProviderDrivers.has(updateCandidate.driver);
+          const modelPreferences = settings.providerModelPreferences?.[row.instanceId] ?? {
+            hiddenModels: [],
+            modelOrder: [],
+          };
+          const favoriteModels = (settings.favorites ?? [])
+            .filter((favorite) => favorite.provider === row.instanceId)
+            .map((favorite) => favorite.model);
+          const resetLabel = driverOption?.label ?? String(row.driver);
+          const headerAction =
+            row.isDefault && row.isDirty ? (
+              <SettingResetButton
+                label={`${resetLabel} provider settings`}
+                onClick={() => resetDefaultInstance(row.driver)}
+              />
+            ) : null;
           return (
-            <div key={providerCard.provider} className="border-t border-border first:border-t-0">
-              <div className="px-4 py-4 sm:px-5">
-                <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
-                  <div className="min-w-0 flex-1 space-y-1">
-                    <div className="flex min-h-5 items-center gap-1.5">
-                      <span
-                        className={cn("size-2 shrink-0 rounded-full", providerCard.statusStyle.dot)}
-                      />
-                      <h3 className="text-sm font-medium text-foreground">{providerDisplayName}</h3>
-                      {providerCard.versionLabel ? (
-                        <code className="text-xs text-muted-foreground">
-                          {providerCard.versionLabel}
-                        </code>
-                      ) : null}
-                      <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center">
-                        {providerCard.isDirty ? (
-                          <SettingResetButton
-                            label={`${providerDisplayName} provider settings`}
-                            onClick={() => {
-                              updateSettings({
-                                providers: {
-                                  ...settings.providers,
-                                  [providerCard.provider]:
-                                    DEFAULT_UNIFIED_SETTINGS.providers[providerCard.provider],
-                                },
-                              });
-                              setCustomModelErrorByProvider((existing) => ({
-                                ...existing,
-                                [providerCard.provider]: null,
-                              }));
-                            }}
-                          />
-                        ) : null}
-                      </span>
-                    </div>
-                    <p className="text-xs text-muted-foreground">
-                      {providerCard.summary.headline}
-                      {providerCard.summary.detail ? ` - ${providerCard.summary.detail}` : null}
-                    </p>
-                  </div>
-                  <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
-                    <Button
-                      size="sm"
-                      variant="ghost"
-                      className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground"
-                      onClick={() =>
-                        setOpenProviderDetails((existing) => ({
-                          ...existing,
-                          [providerCard.provider]: !existing[providerCard.provider],
-                        }))
-                      }
-                      aria-label={`Toggle ${providerDisplayName} details`}
-                    >
-                      <ChevronDownIcon
-                        className={cn(
-                          "size-3.5 transition-transform",
-                          openProviderDetails[providerCard.provider] && "rotate-180",
-                        )}
-                      />
-                    </Button>
-                    <Switch
-                      checked={providerCard.providerConfig.enabled}
-                      onCheckedChange={(checked) => {
-                        const isDisabling = !checked;
-                        const shouldClearModelSelection =
-                          isDisabling && textGenProvider === providerCard.provider;
-                        updateSettings({
-                          providers: {
-                            ...settings.providers,
-                            [providerCard.provider]: {
-                              ...settings.providers[providerCard.provider],
-                              enabled: Boolean(checked),
-                            },
-                          },
-                          ...(shouldClearModelSelection
-                            ? {
-                                textGenerationModelSelection:
-                                  DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
-                              }
-                            : {}),
-                        });
-                      }}
-                      aria-label={`Enable ${providerDisplayName}`}
-                    />
-                  </div>
-                </div>
-              </div>
-
-              <Collapsible
-                open={openProviderDetails[providerCard.provider]}
-                onOpenChange={(open) =>
-                  setOpenProviderDetails((existing) => ({
-                    ...existing,
-                    [providerCard.provider]: open,
-                  }))
+            <ProviderInstanceCard
+              key={row.instanceId}
+              instanceId={row.instanceId}
+              instance={row.instance}
+              driverOption={driverOption}
+              liveProvider={liveProvider}
+              isExpanded={openInstanceDetails[row.instanceId] ?? false}
+              onExpandedChange={(open) =>
+                setOpenInstanceDetails((existing) => ({
+                  ...existing,
+                  [row.instanceId]: open,
+                }))
+              }
+              onUpdate={(next) => {
+                const wasEnabled = row.instance.enabled ?? true;
+                const isDisabling = next.enabled === false && wasEnabled;
+                const shouldClearTextGen = isDisabling && textGenInstanceId === row.instanceId;
+                if (shouldClearTextGen) {
+                  updateProviderInstance(row, next, {
+                    textGenerationModelSelection:
+                      DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
+                  });
+                } else {
+                  updateProviderInstance(row, next);
                 }
-              >
-                <CollapsibleContent>
-                  <div className="space-y-0">
-                    <div className="border-t border-border/60 px-4 py-3 sm:px-5">
-                      <label
-                        htmlFor={`provider-install-${providerCard.provider}-binary-path`}
-                        className="block"
-                      >
-                        <span className="text-xs font-medium text-foreground">
-                          {providerDisplayName} binary path
-                        </span>
-                        <Input
-                          id={`provider-install-${providerCard.provider}-binary-path`}
-                          className="mt-1.5"
-                          value={providerCard.binaryPathValue}
-                          onChange={(event) =>
-                            updateSettings({
-                              providers: {
-                                ...settings.providers,
-                                [providerCard.provider]: {
-                                  ...settings.providers[providerCard.provider],
-                                  binaryPath: event.target.value,
-                                },
-                              },
-                            })
-                          }
-                          placeholder={providerCard.binaryPlaceholder}
-                          spellCheck={false}
-                        />
-                        <span className="mt-1 block text-xs text-muted-foreground">
-                          {providerCard.binaryDescription}
-                        </span>
-                      </label>
-                    </div>
-
-                    {providerCard.homePathKey ? (
-                      <div className="border-t border-border/60 px-4 py-3 sm:px-5">
-                        <label
-                          htmlFor={`provider-install-${providerCard.homePathKey}`}
-                          className="block"
-                        >
-                          <span className="text-xs font-medium text-foreground">
-                            CODEX_HOME path
-                          </span>
-                          <Input
-                            id={`provider-install-${providerCard.homePathKey}`}
-                            className="mt-1.5"
-                            value={codexHomePath}
-                            onChange={(event) =>
-                              updateSettings({
-                                providers: {
-                                  ...settings.providers,
-                                  codex: {
-                                    ...settings.providers.codex,
-                                    homePath: event.target.value,
-                                  },
-                                },
-                              })
-                            }
-                            placeholder={providerCard.homePlaceholder}
-                            spellCheck={false}
-                          />
-                          {providerCard.homeDescription ? (
-                            <span className="mt-1 block text-xs text-muted-foreground">
-                              {providerCard.homeDescription}
-                            </span>
-                          ) : null}
-                        </label>
-                      </div>
-                    ) : null}
-
-                    <div className="border-t border-border/60 px-4 py-3 sm:px-5">
-                      <div className="text-xs font-medium text-foreground">Models</div>
-                      <div className="mt-1 text-xs text-muted-foreground">
-                        {providerCard.models.length} model
-                        {providerCard.models.length === 1 ? "" : "s"} available.
-                      </div>
-                      <div
-                        ref={(el) => {
-                          modelListRefs.current[providerCard.provider] = el;
-                        }}
-                        className="mt-2 max-h-40 overflow-y-auto pb-1"
-                      >
-                        {providerCard.models.map((model) => {
-                          const caps = model.capabilities;
-                          const capLabels: string[] = [];
-                          if (caps?.supportsFastMode) capLabels.push("Fast mode");
-                          if (caps?.supportsThinkingToggle) capLabels.push("Thinking");
-                          if (
-                            caps?.reasoningEffortLevels &&
-                            caps.reasoningEffortLevels.length > 0
-                          ) {
-                            capLabels.push("Reasoning");
-                          }
-                          const hasDetails = capLabels.length > 0 || model.name !== model.slug;
-
-                          return (
-                            <div
-                              key={`${providerCard.provider}:${model.slug}`}
-                              className="flex items-center gap-2 py-1"
-                            >
-                              <span className="min-w-0 truncate text-xs text-foreground/90">
-                                {model.name}
-                              </span>
-                              {hasDetails ? (
-                                <Tooltip>
-                                  <TooltipTrigger
-                                    render={
-                                      <button
-                                        type="button"
-                                        className="shrink-0 text-muted-foreground/40 transition-colors hover:text-muted-foreground"
-                                        aria-label={`Details for ${model.name}`}
-                                      />
-                                    }
-                                  >
-                                    <InfoIcon className="size-3" />
-                                  </TooltipTrigger>
-                                  <TooltipPopup side="top" className="max-w-56">
-                                    <div className="space-y-1">
-                                      <code className="block text-[11px] text-foreground">
-                                        {model.slug}
-                                      </code>
-                                      {capLabels.length > 0 ? (
-                                        <div className="flex flex-wrap gap-x-2 gap-y-0.5">
-                                          {capLabels.map((label) => (
-                                            <span
-                                              key={label}
-                                              className="text-[10px] text-muted-foreground"
-                                            >
-                                              {label}
-                                            </span>
-                                          ))}
-                                        </div>
-                                      ) : null}
-                                    </div>
-                                  </TooltipPopup>
-                                </Tooltip>
-                              ) : null}
-                              {model.isCustom ? (
-                                <div className="ml-auto flex shrink-0 items-center gap-1.5">
-                                  <span className="text-[10px] text-muted-foreground">custom</span>
-                                  <button
-                                    type="button"
-                                    className="text-muted-foreground transition-colors hover:text-foreground"
-                                    aria-label={`Remove ${model.slug}`}
-                                    onClick={() =>
-                                      removeCustomModel(providerCard.provider, model.slug)
-                                    }
-                                  >
-                                    <XIcon className="size-3" />
-                                  </button>
-                                </div>
-                              ) : null}
-                            </div>
-                          );
-                        })}
-                      </div>
-
-                      <div className="mt-3 flex flex-col gap-2 sm:flex-row">
-                        <Input
-                          id={`custom-model-${providerCard.provider}`}
-                          value={customModelInput}
-                          onChange={(event) => {
-                            const value = event.target.value;
-                            setCustomModelInputByProvider((existing) => ({
-                              ...existing,
-                              [providerCard.provider]: value,
-                            }));
-                            if (customModelError) {
-                              setCustomModelErrorByProvider((existing) => ({
-                                ...existing,
-                                [providerCard.provider]: null,
-                              }));
-                            }
-                          }}
-                          onKeyDown={(event) => {
-                            if (event.key !== "Enter") return;
-                            event.preventDefault();
-                            addCustomModel(providerCard.provider);
-                          }}
-                          placeholder={
-                            providerCard.provider === "codex"
-                              ? "gpt-6.7-codex-ultra-preview"
-                              : "claude-sonnet-5-0"
-                          }
-                          spellCheck={false}
-                        />
-                        <Button
-                          className="shrink-0"
-                          variant="outline"
-                          onClick={() => addCustomModel(providerCard.provider)}
-                        >
-                          <PlusIcon className="size-3.5" />
-                          Add
-                        </Button>
-                      </div>
-
-                      {customModelError ? (
-                        <p className="mt-2 text-xs text-destructive">{customModelError}</p>
-                      ) : null}
-                    </div>
-                  </div>
-                </CollapsibleContent>
-              </Collapsible>
-            </div>
+              }}
+              onDelete={row.isDefault ? undefined : () => deleteProviderInstance(row.instanceId)}
+              headerAction={headerAction}
+              hiddenModels={modelPreferences.hiddenModels}
+              favoriteModels={favoriteModels}
+              modelOrder={modelPreferences.modelOrder}
+              onHiddenModelsChange={(hiddenModels) =>
+                updateProviderModelPreferences(row.instanceId, {
+                  ...modelPreferences,
+                  hiddenModels,
+                })
+              }
+              onFavoriteModelsChange={(favoriteModels) =>
+                updateProviderFavoriteModels(row.instanceId, favoriteModels)
+              }
+              onModelOrderChange={(modelOrder) =>
+                updateProviderModelPreferences(row.instanceId, {
+                  ...modelPreferences,
+                  modelOrder,
+                })
+              }
+              onRunUpdate={
+                showInlineUpdateButton && updateCandidate
+                  ? () => {
+                      if (!canRunInlineUpdate) {
+                        return;
+                      }
+                      void runProviderUpdate(updateCandidate);
+                    }
+                  : undefined
+              }
+              isUpdating={showInlineUpdateButton ? isDriverUpdateRunning : undefined}
+            />
           );
         })}
       </SettingsSection>
 
-      <SettingsSection title="Advanced">
-        <SettingsRow
-          title="Keybindings"
-          description="Open the persisted `keybindings.json` file to edit advanced bindings directly."
-          status={
-            <>
-              <span className="block break-all font-mono text-[11px] text-foreground">
-                {keybindingsConfigPath ?? "Resolving keybindings path..."}
-              </span>
-              {openKeybindingsError ? (
-                <span className="mt-1 block text-destructive">{openKeybindingsError}</span>
-              ) : (
-                <span className="mt-1 block">Opens in your preferred editor.</span>
-              )}
-            </>
-          }
-          control={
-            <Button
-              size="xs"
-              variant="outline"
-              disabled={!keybindingsConfigPath || isOpeningKeybindings}
-              onClick={openKeybindingsFile}
-            >
-              {isOpeningKeybindings ? "Opening..." : "Open file"}
-            </Button>
-          }
-        />
-      </SettingsSection>
-
-      <SettingsSection title="About">
-        {isElectron ? (
-          <AboutVersionSection />
-        ) : (
-          <SettingsRow
-            title={<AboutVersionTitle />}
-            description="Current version of the application."
-          />
-        )}
-        <SettingsRow
-          title="Diagnostics"
-          description={diagnosticsDescription}
-          status={
-            <>
-              <span className="block break-all font-mono text-[11px] text-foreground">
-                {logsDirectoryPath ?? "Resolving logs directory..."}
-              </span>
-              {openDiagnosticsError ? (
-                <span className="mt-1 block text-destructive">{openDiagnosticsError}</span>
-              ) : null}
-            </>
-          }
-          control={
-            <Button
-              size="xs"
-              variant="outline"
-              disabled={!logsDirectoryPath || isOpeningLogsDirectory}
-              onClick={openLogsDirectory}
-            >
-              {isOpeningLogsDirectory ? "Opening..." : "Open logs folder"}
-            </Button>
-          }
-        />
-      </SettingsSection>
+      <AddProviderInstanceDialog
+        open={isAddInstanceDialogOpen}
+        onOpenChange={setIsAddInstanceDialogOpen}
+      />
     </SettingsPageContainer>
   );
 }
 
 export function ArchivedThreadsPanel() {
   const projects = useStore(useShallow(selectProjectsAcrossEnvironments));
-  const threads = useStore(useShallow(selectThreadShellsAcrossEnvironments));
   const { unarchiveThread, confirmAndDeleteThread } = useThreadActions();
+  const environmentIds = useMemo(
+    () => [...new Set(projects.map((project) => project.environmentId))],
+    [projects],
+  );
+  const {
+    snapshots: archivedSnapshots,
+    error: archiveError,
+    isLoading: isLoadingArchive,
+    refresh: refreshArchivedThreads,
+  } = useArchivedThreadSnapshots(environmentIds);
+
   const archivedGroups = useMemo(() => {
-    return projects
+    const projectsByEnvironmentAndId = new Map(
+      archivedSnapshots.flatMap(({ environmentId, snapshot }) =>
+        snapshot.projects.map(
+          (project) =>
+            [
+              `${environmentId}:${project.id}`,
+              {
+                id: project.id,
+                environmentId,
+                name: project.title,
+                cwd: project.workspaceRoot,
+              },
+            ] as const,
+        ),
+      ),
+    );
+    const threads = archivedSnapshots.flatMap(({ environmentId, snapshot }) =>
+      snapshot.threads.map((thread) => ({
+        ...thread,
+        environmentId,
+      })),
+    );
+
+    return [...projectsByEnvironmentAndId.values()]
       .map((project) => ({
         project,
         threads: threads
-          .filter((thread) => thread.projectId === project.id && thread.archivedAt !== null)
+          .filter(
+            (thread) =>
+              thread.projectId === project.id && thread.environmentId === project.environmentId,
+          )
           .toSorted((left, right) => {
             const leftKey = left.archivedAt ?? left.createdAt;
             const rightKey = right.archivedAt ?? right.createdAt;
@@ -1401,7 +1384,7 @@ export function ArchivedThreadsPanel() {
           }),
       }))
       .filter((group) => group.threads.length > 0);
-  }, [projects, threads]);
+  }, [archivedSnapshots]);
 
   const handleArchivedThreadContextMenu = useCallback(
     async (threadRef: ScopedThreadRef, position: { x: number; y: number }) => {
@@ -1418,36 +1401,52 @@ export function ArchivedThreadsPanel() {
       if (clicked === "unarchive") {
         try {
           await unarchiveThread(threadRef);
+          refreshArchivedThreads();
         } catch (error) {
-          toastManager.add({
-            type: "error",
-            title: "Failed to unarchive thread",
-            description: error instanceof Error ? error.message : "An error occurred.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Failed to unarchive thread",
+              description: error instanceof Error ? error.message : "An error occurred.",
+            }),
+          );
         }
         return;
       }
 
       if (clicked === "delete") {
         await confirmAndDeleteThread(threadRef);
+        refreshArchivedThreads();
       }
     },
-    [confirmAndDeleteThread, unarchiveThread],
+    [confirmAndDeleteThread, refreshArchivedThreads, unarchiveThread],
   );
 
   return (
     <SettingsPageContainer>
       {archivedGroups.length === 0 ? (
         <SettingsSection title="Archived threads">
-          <Empty className="min-h-88">
-            <EmptyMedia variant="icon">
-              <ArchiveIcon />
-            </EmptyMedia>
-            <EmptyHeader>
-              <EmptyTitle>No archived threads</EmptyTitle>
-              <EmptyDescription>Archived threads will appear here.</EmptyDescription>
-            </EmptyHeader>
-          </Empty>
+          <SettingsRow
+            title={
+              <span className="inline-flex items-center gap-2">
+                {isLoadingArchive ? (
+                  <LoaderIcon className="size-3.5 animate-spin text-muted-foreground" />
+                ) : (
+                  <ArchiveIcon className="size-3.5 text-muted-foreground" />
+                )}
+                {isLoadingArchive
+                  ? "Loading archived threads"
+                  : archiveError
+                    ? "Could not load archived threads"
+                    : "No archived threads"}
+              </span>
+            }
+            description={
+              isLoadingArchive
+                ? "Checking connected environments."
+                : (archiveError ?? "Archived threads will appear here.")
+            }
+          />
         </SettingsSection>
       ) : (
         archivedGroups.map(({ project, threads: projectThreads }) => (
@@ -1457,9 +1456,8 @@ export function ArchivedThreadsPanel() {
             icon={<ProjectFavicon environmentId={project.environmentId} cwd={project.cwd} />}
           >
             {projectThreads.map((thread) => (
-              <div
+              <SettingsRow
                 key={thread.id}
-                className="flex items-center justify-between gap-3 border-t border-border px-4 py-3 first:border-t-0 sm:px-5"
                 onContextMenu={(event) => {
                   event.preventDefault();
                   void handleArchivedThreadContextMenu(
@@ -1470,37 +1468,40 @@ export function ArchivedThreadsPanel() {
                     },
                   );
                 }}
-              >
-                <div className="min-w-0 flex-1">
-                  <h3 className="truncate text-sm font-medium text-foreground">{thread.title}</h3>
-                  <p className="text-xs text-muted-foreground">
+                title={thread.title}
+                description={
+                  <>
                     Archived {formatRelativeTimeLabel(thread.archivedAt ?? thread.createdAt)}
                     {" \u00b7 Created "}
                     {formatRelativeTimeLabel(thread.createdAt)}
-                  </p>
-                </div>
-                <Button
-                  type="button"
-                  variant="outline"
-                  size="sm"
-                  className="h-7 shrink-0 cursor-pointer gap-1.5 px-2.5"
-                  onClick={() =>
-                    void unarchiveThread(scopeThreadRef(thread.environmentId, thread.id)).catch(
-                      (error) => {
-                        toastManager.add({
-                          type: "error",
-                          title: "Failed to unarchive thread",
-                          description:
-                            error instanceof Error ? error.message : "An error occurred.",
-                        });
-                      },
-                    )
-                  }
-                >
-                  <ArchiveX className="size-3.5" />
-                  <span>Unarchive</span>
-                </Button>
-              </div>
+                  </>
+                }
+                control={
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    className="h-7 shrink-0 cursor-pointer gap-1.5 px-2.5"
+                    onClick={() =>
+                      void unarchiveThread(scopeThreadRef(thread.environmentId, thread.id))
+                        .then(() => refreshArchivedThreads())
+                        .catch((error) => {
+                          toastManager.add(
+                            stackedThreadToast({
+                              type: "error",
+                              title: "Failed to unarchive thread",
+                              description:
+                                error instanceof Error ? error.message : "An error occurred.",
+                            }),
+                          );
+                        })
+                    }
+                  >
+                    <ArchiveX className="size-3.5" />
+                    <span>Unarchive</span>
+                  </Button>
+                }
+              />
             ))}
           </SettingsSection>
         ))
diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index a150a7c75fd..bec96063868 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -1,6 +1,14 @@
-import type { ComponentType } from "react";
-import { ArchiveIcon, ArrowLeftIcon, Link2Icon, Settings2Icon } from "lucide-react";
-import { useNavigate } from "@tanstack/react-router";
+import { useCallback, type ComponentType } from "react";
+import {
+  ArchiveIcon,
+  ArrowLeftIcon,
+  BotIcon,
+  GitBranchIcon,
+  KeyboardIcon,
+  Link2Icon,
+  Settings2Icon,
+} from "lucide-react";
+import { useCanGoBack, useNavigate } from "@tanstack/react-router";
 
 import {
   SidebarContent,
@@ -10,10 +18,14 @@ import {
   SidebarMenuButton,
   SidebarMenuItem,
   SidebarSeparator,
+  useSidebar,
 } from "../ui/sidebar";
 
 export type SettingsSectionPath =
   | "/settings/general"
+  | "/settings/keybindings"
+  | "/settings/providers"
+  | "/settings/source-control"
   | "/settings/connections"
   | "/settings/archived";
 
@@ -23,12 +35,36 @@ export const SETTINGS_NAV_ITEMS: ReadonlyArray<{
   icon: ComponentType<{ className?: string }>;
 }> = [
   { label: "General", to: "/settings/general", icon: Settings2Icon },
+  { label: "Keybindings", to: "/settings/keybindings", icon: KeyboardIcon },
+  { label: "Providers", to: "/settings/providers", icon: BotIcon },
+  { label: "Source Control", to: "/settings/source-control", icon: GitBranchIcon },
   { label: "Connections", to: "/settings/connections", icon: Link2Icon },
   { label: "Archive", to: "/settings/archived", icon: ArchiveIcon },
 ];
 
 export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   const navigate = useNavigate();
+  const canGoBack = useCanGoBack();
+  const { isMobile, setOpenMobile } = useSidebar();
+  const handleSectionClick = useCallback(
+    (to: SettingsSectionPath) => {
+      if (isMobile) {
+        setOpenMobile(false);
+      }
+      void navigate({ to, replace: true });
+    },
+    [isMobile, navigate, setOpenMobile],
+  );
+  const handleBackClick = useCallback(() => {
+    if (isMobile) {
+      setOpenMobile(false);
+    }
+    if (canGoBack) {
+      window.history.back();
+      return;
+    }
+    void navigate({ to: "/" });
+  }, [canGoBack, isMobile, navigate, setOpenMobile]);
 
   return (
     <>
@@ -48,7 +84,7 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
                         ? "gap-2.5 px-2.5 py-2 text-left text-[13px] font-medium text-foreground"
                         : "gap-2.5 px-2.5 py-2 text-left text-[13px] text-muted-foreground/70 hover:text-foreground/80"
                     }
-                    onClick={() => void navigate({ to: item.to, replace: true })}
+                    onClick={() => handleSectionClick(item.to)}
                   >
                     <Icon
                       className={
@@ -73,7 +109,7 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
             <SidebarMenuButton
               size="sm"
               className="gap-2 px-2 py-2 text-xs text-muted-foreground hover:bg-accent hover:text-foreground"
-              onClick={() => window.history.back()}
+              onClick={handleBackClick}
             >
               <ArrowLeftIcon className="size-4" />
               <span>Back</span>
diff --git a/apps/web/src/components/settings/SourceControlSettings.tsx b/apps/web/src/components/settings/SourceControlSettings.tsx
new file mode 100644
index 00000000000..0cda0c1b869
--- /dev/null
+++ b/apps/web/src/components/settings/SourceControlSettings.tsx
@@ -0,0 +1,508 @@
+import { ChevronDownIcon, GitPullRequestIcon, RefreshCwIcon } from "lucide-react";
+import * as Duration from "effect/Duration";
+import * as Option from "effect/Option";
+import { useState, type ReactNode } from "react";
+import type {
+  SourceControlProviderKind,
+  SourceControlDiscoveryResult,
+  SourceControlProviderAuth,
+  SourceControlProviderDiscoveryItem,
+  VcsDriverKind,
+  VcsDiscoveryItem,
+} from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
+
+import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
+import { cn } from "../../lib/utils";
+import {
+  refreshSourceControlDiscovery,
+  useSourceControlDiscovery,
+} from "../../lib/sourceControlDiscoveryState";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import { Collapsible, CollapsibleContent } from "../ui/collapsible";
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "../ui/empty";
+import { Skeleton } from "../ui/skeleton";
+import {
+  NumberField,
+  NumberFieldDecrement,
+  NumberFieldGroup,
+  NumberFieldIncrement,
+  NumberFieldInput,
+} from "../ui/number-field";
+import { Switch } from "../ui/switch";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import {
+  AzureDevOpsIcon,
+  BitbucketIcon,
+  GitHubIcon,
+  GitIcon,
+  GitLabIcon,
+  JujutsuIcon,
+  type Icon,
+} from "../Icons";
+import { RedactedSensitiveText } from "./RedactedSensitiveText";
+import { SettingResetButton, SettingsPageContainer, SettingsSection } from "./settingsLayout";
+
+const EMPTY_DISCOVERY_RESULT: SourceControlDiscoveryResult = {
+  versionControlSystems: [],
+  sourceControlProviders: [],
+};
+
+const SOURCE_CONTROL_PROVIDER_ICONS: Partial<Record<SourceControlProviderKind, Icon>> = {
+  github: GitHubIcon,
+  gitlab: GitLabIcon,
+  "azure-devops": AzureDevOpsIcon,
+  bitbucket: BitbucketIcon,
+};
+
+const VCS_ICONS: Partial<Record<VcsDriverKind, Icon>> = {
+  git: GitIcon,
+  jj: JujutsuIcon,
+};
+
+const SOURCE_CONTROL_SKELETON_ROWS = ["primary", "secondary"] as const;
+const GIT_FETCH_INTERVAL_STEP_SECONDS = 5;
+
+function durationToSeconds(duration: Duration.Duration): number {
+  return Math.round(Duration.toMillis(duration) / 1_000);
+}
+
+function normalizeFetchIntervalSeconds(value: number | null): number {
+  if (value === null || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.round(value));
+}
+
+function optionLabel(value: Option.Option<string>): string | null {
+  return Option.getOrNull(value);
+}
+
+function isProviderDiscoveryItem(
+  item: VcsDiscoveryItem | SourceControlProviderDiscoveryItem,
+): item is SourceControlProviderDiscoveryItem {
+  return "auth" in item;
+}
+
+function isVcsNotReady(item: VcsDiscoveryItem | SourceControlProviderDiscoveryItem): boolean {
+  return !isProviderDiscoveryItem(item) && !item.implemented;
+}
+
+function authPresentation(auth: SourceControlProviderAuth): {
+  readonly label: string;
+  readonly badge: "warning" | null;
+} {
+  if (auth.status === "authenticated") {
+    return { label: "Authenticated", badge: null };
+  }
+  if (auth.status === "unauthenticated") {
+    return { label: "Not authenticated", badge: "warning" };
+  }
+  return { label: "Status unknown", badge: null };
+}
+
+function RedactedAccount(props: { readonly account: string | null }) {
+  return (
+    <RedactedSensitiveText
+      value={props.account}
+      ariaLabel="Toggle source control account visibility"
+      revealTooltip="Click to reveal account"
+      hideTooltip="Click to hide account"
+    />
+  );
+}
+
+function itemStatusDot(item: VcsDiscoveryItem | SourceControlProviderDiscoveryItem): string {
+  if (isVcsNotReady(item)) return "bg-muted-foreground/35";
+  if (item.status !== "available") return "bg-warning";
+  if (isProviderDiscoveryItem(item) && item.auth.status !== "authenticated") return "bg-warning";
+  return "bg-success";
+}
+
+function SourceControlItemMark({
+  item,
+}: {
+  readonly item: VcsDiscoveryItem | SourceControlProviderDiscoveryItem;
+}) {
+  const dotClassName = itemStatusDot(item);
+  const Icon = isProviderDiscoveryItem(item)
+    ? SOURCE_CONTROL_PROVIDER_ICONS[item.kind]
+    : VCS_ICONS[item.kind];
+
+  if (!Icon) {
+    return <span className={cn("size-2 shrink-0 rounded-full", dotClassName)} aria-hidden />;
+  }
+
+  return (
+    <span className="relative inline-flex size-5 shrink-0 items-center justify-center">
+      <Icon className="size-4.5 text-foreground/80" aria-hidden />
+      <span
+        className={cn(
+          "pointer-events-none absolute -left-0.5 -top-0.5 size-2 rounded-full ring-2 ring-background",
+          dotClassName,
+        )}
+        aria-hidden
+      />
+    </span>
+  );
+}
+
+function itemSummary({
+  item,
+  auth,
+  authAccount,
+}: {
+  readonly item: VcsDiscoveryItem | SourceControlProviderDiscoveryItem;
+  readonly auth: SourceControlProviderAuth | null;
+  readonly authAccount: string | null;
+}) {
+  if (isVcsNotReady(item)) {
+    return <span>Support for {item.label} is coming soon.</span>;
+  }
+
+  if (item.status !== "available") {
+    return <span>Not available on this server: {item.installHint}</span>;
+  }
+
+  if (auth) {
+    if (auth.status === "authenticated") {
+      return (
+        <>
+          <span>Authenticated</span>
+          {authAccount ? (
+            <>
+              <span aria-hidden>as</span>
+              <RedactedAccount account={authAccount} />
+            </>
+          ) : null}
+        </>
+      );
+    }
+
+    if (!item.executable) {
+      return <span>{item.installHint}</span>;
+    }
+
+    if (auth.status === "unauthenticated") {
+      return (
+        <span>
+          {item.label} is not authenticated on this server. Sign in or configure credentials using
+          the <code className="rounded bg-muted px-1 py-px text-[11px]">{item.executable}</code>{" "}
+          tool on the server host to enable pull request features.
+        </span>
+      );
+    }
+    return (
+      <span>
+        Could not verify {item.label}. {item.installHint}
+      </span>
+    );
+  }
+
+  return <span>Available</span>;
+}
+
+function DiscoveryItemRow({
+  item,
+  children,
+}: {
+  readonly item: VcsDiscoveryItem | SourceControlProviderDiscoveryItem;
+  readonly children?: ReactNode;
+}) {
+  const version = optionLabel(item.version);
+  const enabled =
+    item.status === "available" && (isProviderDiscoveryItem(item) || item.implemented);
+  const auth = isProviderDiscoveryItem(item) ? item.auth : null;
+  const authStatus = auth ? authPresentation(auth) : null;
+  const authAccount = auth ? optionLabel(auth.account) : null;
+  const [isExpanded, setIsExpanded] = useState(false);
+  const hasDetails = children !== undefined;
+
+  return (
+    <div
+      className={cn(
+        "border-t border-border/60 first:border-t-0",
+        isVcsNotReady(item) && "opacity-80",
+      )}
+    >
+      <div className="px-4 py-3.5 sm:px-5">
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+          <div className="min-w-0 flex-1 space-y-1">
+            <div className="flex min-w-0 flex-wrap items-center gap-2">
+              <SourceControlItemMark item={item} />
+              <span className="truncate text-[13px] font-semibold tracking-[-0.01em] text-foreground">
+                {item.label}
+              </span>
+              {version ? <code className="text-xs text-muted-foreground">{version}</code> : null}
+              {isVcsNotReady(item) ? (
+                <Badge variant="warning" size="sm">
+                  Coming Soon
+                </Badge>
+              ) : null}
+              {authStatus?.badge ? (
+                <Badge variant={authStatus.badge} size="sm">
+                  {authStatus.label}
+                </Badge>
+              ) : null}
+            </div>
+            <p className="flex min-w-0 flex-wrap items-center gap-x-1 text-xs text-muted-foreground/80">
+              {itemSummary({ item, auth, authAccount })}
+            </p>
+          </div>
+          <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
+            {hasDetails ? (
+              <Button
+                size="sm"
+                variant="ghost"
+                className="h-7 px-2 text-xs text-muted-foreground hover:text-foreground"
+                onClick={() => setIsExpanded((open) => !open)}
+                aria-expanded={isExpanded}
+                aria-label={`Toggle ${item.label} details`}
+              >
+                <ChevronDownIcon
+                  className={cn("size-3.5 transition-transform", isExpanded && "rotate-180")}
+                />
+              </Button>
+            ) : null}
+            {!isVcsNotReady(item) ? (
+              <Switch checked={enabled} disabled aria-label={`${item.label} availability`} />
+            ) : null}
+          </div>
+        </div>
+      </div>
+
+      {hasDetails ? (
+        <Collapsible open={isExpanded} onOpenChange={setIsExpanded}>
+          <CollapsibleContent>
+            <div className="border-t border-border/60 px-4 py-3 sm:px-5">{children}</div>
+          </CollapsibleContent>
+        </Collapsible>
+      ) : null}
+    </div>
+  );
+}
+
+function GitFetchIntervalSettings() {
+  const automaticGitFetchInterval = useSettings((settings) => settings.automaticGitFetchInterval);
+  const { updateSettings } = useUpdateSettings();
+  const automaticGitFetchIntervalSeconds = durationToSeconds(automaticGitFetchInterval);
+  const defaultAutomaticGitFetchIntervalSeconds = durationToSeconds(
+    DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
+  );
+  const canResetFetchInterval =
+    automaticGitFetchIntervalSeconds !== defaultAutomaticGitFetchIntervalSeconds;
+
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+        <div className="min-w-0 space-y-1">
+          <div className="flex min-w-0 items-center gap-1">
+            <span className="text-xs font-medium text-foreground">Fetch interval</span>
+            <span
+              className={cn(
+                "inline-flex size-5 shrink-0 items-center justify-center transition-opacity",
+                canResetFetchInterval ? "opacity-100" : "pointer-events-none opacity-0",
+              )}
+              aria-hidden={!canResetFetchInterval}
+            >
+              {canResetFetchInterval ? (
+                <SettingResetButton
+                  label="fetch interval"
+                  onClick={() =>
+                    updateSettings({
+                      automaticGitFetchInterval: DEFAULT_UNIFIED_SETTINGS.automaticGitFetchInterval,
+                    })
+                  }
+                />
+              ) : null}
+            </span>
+          </div>
+          <p className="max-w-2xl text-xs leading-relaxed text-muted-foreground">
+            Refresh remote branch status in the background. Set this to 0 seconds if Git credentials
+            or security keys should only be prompted by explicit Git actions.
+          </p>
+        </div>
+        <div className="flex shrink-0 items-center gap-2">
+          <NumberField
+            value={automaticGitFetchIntervalSeconds}
+            min={0}
+            step={GIT_FETCH_INTERVAL_STEP_SECONDS}
+            size="sm"
+            className="w-32"
+            onValueChange={(value) =>
+              updateSettings({
+                automaticGitFetchInterval: Duration.seconds(normalizeFetchIntervalSeconds(value)),
+              })
+            }
+          >
+            <NumberFieldGroup>
+              <NumberFieldDecrement aria-label="Decrease fetch interval" />
+              <NumberFieldInput aria-label="Automatic Git fetch interval in seconds" />
+              <NumberFieldIncrement aria-label="Increase fetch interval" />
+            </NumberFieldGroup>
+          </NumberField>
+          <span className="text-xs text-muted-foreground">seconds</span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function SourceControlSectionSkeleton({
+  title,
+  headerAction,
+}: {
+  readonly title: string;
+  readonly headerAction?: ReactNode;
+}) {
+  return (
+    <SettingsSection title={title} headerAction={headerAction}>
+      {SOURCE_CONTROL_SKELETON_ROWS.map((row) => (
+        <div key={row} className="border-t border-border/60 px-4 py-3.5 first:border-t-0 sm:px-5">
+          <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+            <div className="min-w-0 flex-1 space-y-2">
+              <div className="flex items-center gap-2">
+                <span className="relative inline-flex size-5 shrink-0 items-center justify-center">
+                  <Skeleton className="size-4.5 rounded-md" />
+                  <Skeleton
+                    className="pointer-events-none absolute -left-0.5 -top-0.5 size-2 rounded-full ring-2 ring-background"
+                    aria-hidden
+                  />
+                </span>
+                <Skeleton className="h-4 w-28 rounded-full" />
+                <Skeleton className="h-5 w-14 rounded-full" />
+              </div>
+              <Skeleton className="h-3 w-full max-w-xs rounded-full" />
+            </div>
+            <div className="flex shrink-0 items-center gap-2">
+              <Skeleton className="size-7 rounded-md" />
+              <Skeleton className="h-5 w-9 rounded-full" />
+            </div>
+          </div>
+        </div>
+      ))}
+    </SettingsSection>
+  );
+}
+
+function EmptySourceControlDiscovery({
+  error,
+  isPending,
+  onScan,
+}: {
+  readonly error: string | null;
+  readonly isPending: boolean;
+  readonly onScan: () => void;
+}) {
+  const hasError = error !== null;
+
+  return (
+    <SettingsSection title="Server environment">
+      <Empty className="min-h-88">
+        <EmptyMedia variant="icon">
+          <GitPullRequestIcon />
+        </EmptyMedia>
+        <EmptyHeader>
+          <EmptyTitle>
+            {hasError ? "Could not scan the server environment" : "Nothing detected yet"}
+          </EmptyTitle>
+          <EmptyDescription>
+            {hasError
+              ? error
+              : "Install Git on the server, add optional hosting integrations or credentials your workspace needs, then rescan."}
+          </EmptyDescription>
+        </EmptyHeader>
+        <EmptyContent>
+          <Button
+            size="sm"
+            variant="outline"
+            className="h-8 gap-1.5 px-3 text-xs"
+            onClick={onScan}
+            disabled={isPending}
+          >
+            <RefreshCwIcon className={cn("size-3.5", isPending && "animate-spin")} />
+            Scan
+          </Button>
+        </EmptyContent>
+      </Empty>
+    </SettingsSection>
+  );
+}
+
+export function SourceControlSettingsPanel() {
+  const discovery = useSourceControlDiscovery();
+  const result = discovery.data ?? EMPTY_DISCOVERY_RESULT;
+  const hasDiscoveryItems =
+    result.versionControlSystems.length > 0 || result.sourceControlProviders.length > 0;
+  const isInitialScanPending = discovery.isPending && discovery.data === null;
+  const handleScan = () => {
+    void refreshSourceControlDiscovery();
+  };
+  const scanButton = (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <Button
+            size="icon-xs"
+            variant="ghost"
+            className="size-5 rounded-sm p-0 text-muted-foreground hover:text-foreground"
+            onClick={handleScan}
+            disabled={discovery.isPending}
+            aria-label="Rescan server environment"
+          >
+            <RefreshCwIcon className={cn("size-3", discovery.isPending && "animate-spin")} />
+          </Button>
+        }
+      />
+      <TooltipPopup side="top">Rescan Git and hosting integrations</TooltipPopup>
+    </Tooltip>
+  );
+
+  return (
+    <SettingsPageContainer>
+      {isInitialScanPending ? (
+        <>
+          <SourceControlSectionSkeleton title="Version Control" headerAction={scanButton} />
+          <SourceControlSectionSkeleton title="Source Control Providers" />
+        </>
+      ) : hasDiscoveryItems ? (
+        <>
+          {result.versionControlSystems.length > 0 ? (
+            <SettingsSection title="Version Control" headerAction={scanButton}>
+              {result.versionControlSystems.map((item) => (
+                <DiscoveryItemRow key={`vcs:${item.kind}`} item={item}>
+                  {item.kind === "git" ? <GitFetchIntervalSettings /> : undefined}
+                </DiscoveryItemRow>
+              ))}
+            </SettingsSection>
+          ) : null}
+
+          {result.sourceControlProviders.length > 0 ? (
+            <SettingsSection
+              title="Source Control Providers"
+              headerAction={result.versionControlSystems.length === 0 ? scanButton : null}
+            >
+              {result.sourceControlProviders.map((item) => (
+                <DiscoveryItemRow key={`provider:${item.kind}`} item={item} />
+              ))}
+            </SettingsSection>
+          ) : null}
+        </>
+      ) : (
+        <EmptySourceControlDiscovery
+          error={discovery.error}
+          isPending={discovery.isPending}
+          onScan={handleScan}
+        />
+      )}
+    </SettingsPageContainer>
+  );
+}
diff --git a/apps/web/src/components/settings/pairingUrls.test.ts b/apps/web/src/components/settings/pairingUrls.test.ts
new file mode 100644
index 00000000000..b32f5c51b32
--- /dev/null
+++ b/apps/web/src/components/settings/pairingUrls.test.ts
@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveDesktopPairingUrl, resolveHostedPairingUrl } from "./pairingUrls";
+
+describe("settings pairing URL helpers", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("uses direct backend pairing URLs for HTTP endpoints", () => {
+    expect(resolveHostedPairingUrl("http://192.168.1.44:3773", "PAIRCODE")).toBeNull();
+    expect(resolveDesktopPairingUrl("http://192.168.1.44:3773", "PAIRCODE")).toBe(
+      "http://192.168.1.44:3773/pair#token=PAIRCODE",
+    );
+  });
+
+  it("uses hosted pairing URLs for HTTPS endpoints", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://preview.t3.codes");
+
+    expect(resolveHostedPairingUrl("https://host.tailnet.example.ts.net:3773", "PAIRCODE")).toBe(
+      "https://preview.t3.codes/pair?host=https%3A%2F%2Fhost.tailnet.example.ts.net%3A3773#token=PAIRCODE",
+    );
+  });
+});
diff --git a/apps/web/src/components/settings/pairingUrls.ts b/apps/web/src/components/settings/pairingUrls.ts
new file mode 100644
index 00000000000..891fe04ad6b
--- /dev/null
+++ b/apps/web/src/components/settings/pairingUrls.ts
@@ -0,0 +1,20 @@
+import { buildHostedPairingUrl } from "../../hostedPairing";
+import { setPairingTokenOnUrl } from "../../pairingUrl";
+
+export function resolveDesktopPairingUrl(endpointUrl: string, credential: string): string {
+  const url = new URL(endpointUrl);
+  url.pathname = "/pair";
+  return setPairingTokenOnUrl(url, credential).toString();
+}
+
+export function resolveHostedPairingUrl(endpointUrl: string, credential: string): string | null {
+  const url = new URL(endpointUrl);
+  if (url.protocol !== "https:") {
+    return null;
+  }
+
+  return buildHostedPairingUrl({
+    host: endpointUrl,
+    token: credential,
+  });
+}
diff --git a/apps/web/src/components/settings/providerDriverMeta.ts b/apps/web/src/components/settings/providerDriverMeta.ts
new file mode 100644
index 00000000000..8d3d7482f62
--- /dev/null
+++ b/apps/web/src/components/settings/providerDriverMeta.ts
@@ -0,0 +1,82 @@
+import {
+  ClaudeSettings,
+  CodexSettings,
+  CursorSettings,
+  OpenCodeSettings,
+  ProviderDriverKind,
+} from "@t3tools/contracts";
+import type * as Schema from "effect/Schema";
+import { ClaudeAI, CursorIcon, type Icon, OpenAI, OpenCodeIcon } from "../Icons";
+
+type ProviderSettingsSchema = {
+  readonly fields: Readonly<Record<string, Schema.Top>>;
+} & Schema.Top;
+
+/**
+ * Browser-safe provider definition. This is deliberately shaped like the
+ * future provider package client export: the core web app gets a schema with
+ * field annotations plus provider-level presentation metadata, then renders
+ * settings generically.
+ */
+export interface ProviderClientDefinition {
+  readonly value: ProviderDriverKind;
+  readonly label: string;
+  readonly icon: Icon;
+  readonly settingsSchema: ProviderSettingsSchema;
+  /**
+   * Optional short label rendered as a `variant="warning"` badge next to
+   * the instance title. Used to flag drivers that still ship under an
+   * early-access or preview gate — the flag is a property of the driver
+   * kind (not a specific instance), so every instance of that driver —
+   * built-in default or custom — advertises the same marker.
+   */
+  readonly badgeLabel?: string;
+}
+
+export const PROVIDER_CLIENT_DEFINITIONS: readonly ProviderClientDefinition[] = [
+  {
+    value: ProviderDriverKind.make("codex"),
+    label: "Codex",
+    icon: OpenAI,
+    settingsSchema: CodexSettings,
+  },
+  {
+    value: ProviderDriverKind.make("claudeAgent"),
+    label: "Claude",
+    icon: ClaudeAI,
+    settingsSchema: ClaudeSettings,
+  },
+  {
+    value: ProviderDriverKind.make("cursor"),
+    label: "Cursor",
+    icon: CursorIcon,
+    badgeLabel: "Early Access",
+    settingsSchema: CursorSettings,
+  },
+  {
+    value: ProviderDriverKind.make("opencode"),
+    label: "OpenCode",
+    icon: OpenCodeIcon,
+    settingsSchema: OpenCodeSettings,
+  },
+];
+
+export const PROVIDER_CLIENT_DEFINITION_BY_VALUE: Partial<
+  Record<ProviderDriverKind, ProviderClientDefinition>
+> = Object.fromEntries(
+  PROVIDER_CLIENT_DEFINITIONS.map((definition) => [definition.value, definition]),
+);
+
+export const DRIVER_OPTIONS = PROVIDER_CLIENT_DEFINITIONS;
+export const DRIVER_OPTION_BY_VALUE = PROVIDER_CLIENT_DEFINITION_BY_VALUE;
+export type DriverOption = ProviderClientDefinition;
+
+/**
+ * Look up the driver metadata for an instance's `driver` field. Accepts
+ * Returns `undefined` for fork / unknown drivers so callers can decide how
+ * to render them — typically by falling back to a generic card.
+ */
+export function getDriverOption(driver: ProviderDriverKind | undefined): DriverOption | undefined {
+  if (driver === undefined) return undefined;
+  return PROVIDER_CLIENT_DEFINITION_BY_VALUE[driver];
+}
diff --git a/apps/web/src/components/settings/providerStatus.ts b/apps/web/src/components/settings/providerStatus.ts
new file mode 100644
index 00000000000..06622a761b7
--- /dev/null
+++ b/apps/web/src/components/settings/providerStatus.ts
@@ -0,0 +1,117 @@
+import type { ServerProvider, ServerProviderVersionAdvisory } from "@t3tools/contracts";
+
+/**
+ * Visual treatment for each server-reported provider status. Centralized so
+ * the default-driver card and per-instance cards share the same language.
+ */
+export const PROVIDER_STATUS_STYLES = {
+  disabled: {
+    dot: "bg-amber-400",
+  },
+  error: {
+    dot: "bg-destructive",
+  },
+  ready: {
+    dot: "bg-success",
+  },
+  warning: {
+    dot: "bg-warning",
+  },
+} as const;
+
+export type ProviderStatusKey = keyof typeof PROVIDER_STATUS_STYLES;
+
+/**
+ * Derive the headline + detail copy shown under a provider's name in the
+ * settings page. Prefers `provider.message` for server-supplied detail and
+ * falls back to generic phrasing when the server has not yet reported any
+ * state — which happens before the first probe or when an instance names a
+ * driver this build does not ship.
+ */
+export function getProviderSummary(provider: ServerProvider | undefined) {
+  if (!provider) {
+    return {
+      headline: "Checking provider status",
+      detail: "Waiting for the server to report installation and authentication details.",
+    };
+  }
+  if (!provider.enabled) {
+    return {
+      headline: "Disabled",
+      detail:
+        provider.message ?? "This provider is installed but disabled for new sessions in T3 Code.",
+    };
+  }
+  if (!provider.installed) {
+    return {
+      headline: "Not found",
+      detail: provider.message ?? "CLI not detected on PATH.",
+    };
+  }
+  if (provider.auth.status === "authenticated") {
+    const authLabel = provider.auth.label ?? provider.auth.type;
+    return {
+      headline: authLabel ? `Authenticated · ${authLabel}` : "Authenticated",
+      detail: provider.message ?? null,
+    };
+  }
+  if (provider.auth.status === "unauthenticated") {
+    return {
+      headline: "Not authenticated",
+      detail: provider.message ?? null,
+    };
+  }
+  if (provider.status === "warning") {
+    return {
+      headline: "Needs attention",
+      detail:
+        provider.message ?? "The provider is installed, but the server could not fully verify it.",
+    };
+  }
+  if (provider.status === "error") {
+    return {
+      headline: "Unavailable",
+      detail: provider.message ?? "The provider failed its startup checks.",
+    };
+  }
+  return {
+    headline: "Available",
+    detail: provider.message ?? "Installed and ready, but authentication could not be verified.",
+  };
+}
+
+/**
+ * Normalize a version string for display. Adds the `v` prefix when the
+ * driver reported a bare version (e.g. `1.2.3`) so cards render
+ * consistently regardless of driver.
+ */
+export function getProviderVersionLabel(version: string | null | undefined) {
+  if (!version) return null;
+  return version.startsWith("v") ? version : `v${version}`;
+}
+
+export function getProviderVersionAdvisoryPresentation(
+  advisory: ServerProviderVersionAdvisory | undefined,
+): {
+  readonly detail: string;
+  readonly updateCommand: string | null;
+  readonly emphasis: "normal" | "strong";
+} | null {
+  if (!advisory || advisory.status === "current" || advisory.status === "unknown") {
+    return null;
+  }
+
+  const label = "Update available";
+  const version = advisory.latestVersion;
+  const versionLabel = getProviderVersionLabel(version);
+
+  return {
+    detail:
+      advisory.message ??
+      (versionLabel
+        ? `${label}: install ${versionLabel}.`
+        : `${label}: install the latest provider version.`),
+    updateCommand: advisory.updateCommand,
+    emphasis: "normal" as const,
+  };
+}
diff --git a/apps/web/src/components/settings/settingsLayout.tsx b/apps/web/src/components/settings/settingsLayout.tsx
index f41e32f9e5c..391898b1110 100644
--- a/apps/web/src/components/settings/settingsLayout.tsx
+++ b/apps/web/src/components/settings/settingsLayout.tsx
@@ -1,5 +1,5 @@
 import { Undo2Icon } from "lucide-react";
-import { type ReactNode, useEffect, useState } from "react";
+import { type ComponentPropsWithoutRef, type ReactNode, useEffect, useState } from "react";
 
 import { cn } from "../../lib/utils";
 import { Button } from "../ui/button";
@@ -20,21 +20,23 @@ export function SettingsSection({
   icon,
   headerAction,
   children,
-}: {
+  className,
+  ...sectionProps
+}: ComponentPropsWithoutRef<"section"> & {
   title: string;
   icon?: ReactNode;
   headerAction?: ReactNode;
   children: ReactNode;
 }) {
   return (
-    <section className="space-y-2.5">
+    <section {...sectionProps} className={cn("space-y-2.5", className)}>
       <div className="flex items-center justify-between px-1">
         <h2 className="flex items-center gap-2 text-[11px] font-semibold uppercase tracking-[0.08em] text-foreground/50">
           <span className="inline-block h-px w-3 bg-border" aria-hidden />
           {icon}
           {title}
         </h2>
-        {headerAction}
+        <div className="flex h-5 min-w-5 items-center justify-end">{headerAction}</div>
       </div>
       <div className="relative overflow-hidden rounded-2xl border bg-card text-card-foreground shadow-sm/4 not-dark:bg-clip-padding before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:shadow-none dark:before:shadow-[0_-1px_--theme(--color-white/6%)]">
         {children}
@@ -50,9 +52,11 @@ export function SettingsRow({
   resetAction,
   control,
   children,
-}: {
+  className,
+  ...rowProps
+}: Omit<ComponentPropsWithoutRef<"div">, "title"> & {
   title: ReactNode;
-  description: string;
+  description: ReactNode;
   status?: ReactNode;
   resetAction?: ReactNode;
   control?: ReactNode;
@@ -60,9 +64,11 @@ export function SettingsRow({
 }) {
   return (
     <div
+      {...rowProps}
       className={cn(
         "border-t border-border/60 px-4 first:border-t-0 sm:px-5",
-        children ? "pt-4 pb-0" : "py-4",
+        children ? "pt-3.5 pb-0" : "py-3.5",
+        className,
       )}
     >
       <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
@@ -75,7 +81,7 @@ export function SettingsRow({
               {resetAction}
             </span>
           </div>
-          <p className="text-xs leading-relaxed text-muted-foreground/80">{description}</p>
+          <p className="text-xs text-muted-foreground/80">{description}</p>
           {status ? <div className="pt-0.5 text-[11px] text-muted-foreground">{status}</div> : null}
         </div>
         {control ? (
@@ -113,10 +119,18 @@ export function SettingResetButton({ label, onClick }: { label: string; onClick:
   );
 }
 
-export function SettingsPageContainer({ children }: { children: ReactNode }) {
+export function SettingsPageContainer({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) {
   return (
     <div className="flex-1 overflow-y-auto p-6 sm:p-8">
-      <div className="mx-auto flex w-full max-w-3xl flex-col gap-8">{children}</div>
+      <div className={cn("mx-auto flex w-full max-w-3xl flex-col gap-8", className)}>
+        {children}
+      </div>
     </div>
   );
 }
diff --git a/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx b/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
new file mode 100644
index 00000000000..d5b1b9bddd4
--- /dev/null
+++ b/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
@@ -0,0 +1,207 @@
+import { useNavigate } from "@tanstack/react-router";
+import type { ServerProvider } from "@t3tools/contracts";
+import { CircleCheckIcon, DownloadIcon, LoaderIcon, TriangleAlertIcon, XIcon } from "lucide-react";
+import { useCallback, useEffect, useState, type CSSProperties } from "react";
+
+import { useServerProviders } from "../../rpc/serverState";
+import {
+  getProviderUpdateSidebarPillView,
+  type ProviderUpdateSidebarPillView,
+} from "../ProviderUpdateLaunchNotification.logic";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+
+const PROVIDER_UPDATE_PILL_STYLES = {
+  loading:
+    "bg-primary/15 text-primary group-has-[button.provider-update-main:hover]/provider-update:bg-primary/22",
+  success:
+    "bg-success/12 text-success group-has-[button.provider-update-main:hover]/provider-update:bg-success/18",
+  warning:
+    "bg-warning/12 text-warning group-has-[button.provider-update-main:hover]/provider-update:bg-warning/18",
+  error:
+    "bg-destructive/12 text-destructive group-has-[button.provider-update-main:hover]/provider-update:bg-destructive/18",
+} as const;
+
+const PROVIDER_UPDATE_PILL_PROGRESS_STYLES = {
+  success: "bg-success/18",
+  warning: "bg-warning/14",
+  error: "bg-destructive/14",
+} as const;
+
+function latestProviderCheckedAt(
+  providers: ReadonlyArray<Pick<ServerProvider, "checkedAt">>,
+): string | undefined {
+  return providers.reduce<string | undefined>(
+    (latest, provider) =>
+      latest === undefined || provider.checkedAt > latest ? provider.checkedAt : latest,
+    undefined,
+  );
+}
+
+export function SidebarProviderUpdatePill() {
+  const navigate = useNavigate();
+  const providers = useServerProviders();
+  const [dismissedKeys, setDismissedKeys] = useState<ReadonlySet<string>>(() => new Set());
+  const [renderedView, setRenderedView] = useState<ProviderUpdateSidebarPillView | null>(null);
+  const [pendingView, setPendingView] = useState<ProviderUpdateSidebarPillView | null>(null);
+  const [exitingKey, setExitingKey] = useState<string | null>(null);
+  const [dismissAfterExitKey, setDismissAfterExitKey] = useState<string | null>(null);
+  const [visibleAfterIso, setVisibleAfterIso] = useState<string | undefined>();
+  const effectiveVisibleAfterIso = visibleAfterIso ?? latestProviderCheckedAt(providers);
+  const view = getProviderUpdateSidebarPillView(providers, {
+    ...(effectiveVisibleAfterIso !== undefined
+      ? { visibleAfterIso: effectiveVisibleAfterIso }
+      : {}),
+    dismissedKeys,
+  });
+
+  useEffect(() => {
+    if (visibleAfterIso === undefined && effectiveVisibleAfterIso !== undefined) {
+      setVisibleAfterIso(effectiveVisibleAfterIso);
+    }
+  }, [effectiveVisibleAfterIso, visibleAfterIso]);
+
+  const openProviderSettings = useCallback(() => {
+    void navigate({ to: "/settings/providers" });
+  }, [navigate]);
+  const displayedView = renderedView ?? view;
+  const dismissAfterVisibleMs = displayedView?.dismissAfterVisibleMs;
+  const viewKey = displayedView?.key ?? null;
+  const showDismissProgress =
+    dismissAfterVisibleMs !== undefined &&
+    displayedView?.tone !== "loading" &&
+    exitingKey !== viewKey;
+
+  const startExit = useCallback(
+    (key: string, nextView: ProviderUpdateSidebarPillView | null, dismissKey?: string) => {
+      if (exitingKey === key) {
+        return;
+      }
+      setPendingView(nextView);
+      setExitingKey(key);
+      setDismissAfterExitKey(dismissKey ?? null);
+    },
+    [exitingKey],
+  );
+
+  useEffect(() => {
+    if (exitingKey !== null) {
+      return;
+    }
+    if (!renderedView) {
+      if (view) {
+        setRenderedView(view);
+      }
+      return;
+    }
+    if (!view) {
+      startExit(renderedView.key, null);
+      return;
+    }
+    if (view.key !== renderedView.key) {
+      startExit(renderedView.key, view);
+      return;
+    }
+  }, [exitingKey, renderedView, startExit, view]);
+
+  useEffect(() => {
+    if (!dismissAfterVisibleMs || !viewKey) {
+      return;
+    }
+    if (exitingKey === viewKey) {
+      return;
+    }
+    const timeoutId = window.setTimeout(() => {
+      startExit(viewKey, null, viewKey);
+    }, dismissAfterVisibleMs);
+
+    return () => window.clearTimeout(timeoutId);
+  }, [dismissAfterVisibleMs, exitingKey, startExit, viewKey]);
+
+  if (!displayedView) {
+    return null;
+  }
+
+  return (
+    <div
+      className={`group/provider-update relative flex h-7 w-full items-center overflow-hidden rounded-lg text-xs font-medium transform-gpu transition-all duration-180 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform ${
+        PROVIDER_UPDATE_PILL_STYLES[displayedView.tone]
+      } ${
+        exitingKey === displayedView.key
+          ? "pointer-events-none translate-y-1.5 opacity-0"
+          : "translate-y-0 opacity-100"
+      }`}
+      onTransitionEnd={(event) => {
+        if (event.target !== event.currentTarget) {
+          return;
+        }
+        if (!displayedView || exitingKey !== displayedView.key) {
+          return;
+        }
+        if (dismissAfterExitKey === displayedView.key) {
+          setDismissedKeys((previous) => new Set(previous).add(displayedView.key));
+        }
+        setRenderedView(pendingView);
+        setPendingView(null);
+        setExitingKey(null);
+        setDismissAfterExitKey(null);
+      }}
+    >
+      {showDismissProgress ? (
+        <div
+          key={displayedView.key}
+          aria-hidden="true"
+          className={`provider-update-pill-progress pointer-events-none absolute inset-y-0 left-0 w-full origin-left border-r border-current/15 shadow-[inset_0_1px_0_rgb(255_255_255_/_0.08)] ${
+            PROVIDER_UPDATE_PILL_PROGRESS_STYLES[displayedView.tone]
+          }`}
+          style={
+            {
+              "--provider-update-pill-dismiss-ms": `${dismissAfterVisibleMs}ms`,
+            } as CSSProperties
+          }
+        />
+      ) : null}
+      <div className="pointer-events-none absolute inset-0 rounded-lg transition-colors" />
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <button
+              type="button"
+              aria-label={displayedView.description}
+              className="provider-update-main relative z-[1] flex h-full flex-1 items-center gap-2 px-2 text-left"
+              onClick={openProviderSettings}
+            >
+              {displayedView.tone === "loading" ? (
+                <LoaderIcon className="size-3.5 animate-spin" />
+              ) : displayedView.tone === "success" ? (
+                <CircleCheckIcon className="size-3.5" />
+              ) : displayedView.tone === "error" ? (
+                <TriangleAlertIcon className="size-3.5" />
+              ) : (
+                <DownloadIcon className="size-3.5" />
+              )}
+              <span>{displayedView.title}</span>
+            </button>
+          }
+        />
+        <TooltipPopup side="top">{displayedView.description}</TooltipPopup>
+      </Tooltip>
+      {displayedView.dismissible && (
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <button
+                type="button"
+                aria-label="Dismiss provider update notice"
+                className="relative z-[1] mr-1 inline-flex size-5 items-center justify-center rounded-md opacity-70 transition-opacity hover:opacity-100"
+                onClick={() => startExit(displayedView.key, null, displayedView.key)}
+              >
+                <XIcon className="size-3.5" />
+              </button>
+            }
+          />
+          <TooltipPopup side="top">Dismiss until provider status changes</TooltipPopup>
+        </Tooltip>
+      )}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/sidebar/SidebarUpdatePill.tsx b/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
index 2f9aec112a9..d7e5b74d42d 100644
--- a/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
+++ b/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
@@ -6,7 +6,7 @@ import {
   setDesktopUpdateStateQueryData,
   useDesktopUpdateState,
 } from "../../lib/desktopUpdateReactQuery";
-import { toastManager } from "../ui/toast";
+import { stackedThreadToast, toastManager } from "../ui/toast";
 import {
   getArm64IntelBuildWarningDescription,
   getDesktopUpdateActionError,
@@ -55,18 +55,22 @@ export function SidebarUpdatePill() {
           if (!shouldToastDesktopUpdateActionResult(result)) return;
           const actionError = getDesktopUpdateActionError(result);
           if (!actionError) return;
-          toastManager.add({
-            type: "error",
-            title: "Could not download update",
-            description: actionError,
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not download update",
+              description: actionError,
+            }),
+          );
         })
         .catch((error) => {
-          toastManager.add({
-            type: "error",
-            title: "Could not start update download",
-            description: error instanceof Error ? error.message : "An unexpected error occurred.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not start update download",
+              description: error instanceof Error ? error.message : "An unexpected error occurred.",
+            }),
+          );
         });
       return;
     }
@@ -81,18 +85,22 @@ export function SidebarUpdatePill() {
           if (!shouldToastDesktopUpdateActionResult(result)) return;
           const actionError = getDesktopUpdateActionError(result);
           if (!actionError) return;
-          toastManager.add({
-            type: "error",
-            title: "Could not install update",
-            description: actionError,
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not install update",
+              description: actionError,
+            }),
+          );
         })
         .catch((error) => {
-          toastManager.add({
-            type: "error",
-            title: "Could not install update",
-            description: error instanceof Error ? error.message : "An unexpected error occurred.",
-          });
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Could not install update",
+              description: error instanceof Error ? error.message : "An unexpected error occurred.",
+            }),
+          );
         });
     }
   }, [action, disabled, queryClient, state]);
diff --git a/apps/web/src/components/timelineHeight.test.ts b/apps/web/src/components/timelineHeight.test.ts
deleted file mode 100644
index 5317a5fc683..00000000000
--- a/apps/web/src/components/timelineHeight.test.ts
+++ /dev/null
@@ -1,151 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { appendTerminalContextsToPrompt } from "../lib/terminalContext";
-import { buildInlineTerminalContextText } from "./chat/userMessageTerminalContexts";
-import { estimateTimelineMessageHeight } from "./timelineHeight";
-
-describe("estimateTimelineMessageHeight", () => {
-  it("uses assistant sizing rules for assistant messages", () => {
-    expect(
-      estimateTimelineMessageHeight({
-        role: "assistant",
-        text: "a".repeat(144),
-      }),
-    ).toBe(86.5);
-  });
-
-  it("uses assistant sizing rules for system messages", () => {
-    expect(
-      estimateTimelineMessageHeight({
-        role: "system",
-        text: "a".repeat(144),
-      }),
-    ).toBe(86.5);
-  });
-
-  it("adds one attachment row for one or two user attachments", () => {
-    expect(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: "hello",
-        attachments: [{ id: "1" }],
-      }),
-    ).toBe(234);
-
-    expect(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: "hello",
-        attachments: [{ id: "1" }, { id: "2" }],
-      }),
-    ).toBe(234);
-  });
-
-  it("adds a second attachment row for three or four user attachments", () => {
-    expect(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: "hello",
-        attachments: [{ id: "1" }, { id: "2" }, { id: "3" }],
-      }),
-    ).toBe(350);
-
-    expect(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: "hello",
-        attachments: [{ id: "1" }, { id: "2" }, { id: "3" }, { id: "4" }],
-      }),
-    ).toBe(350);
-  });
-
-  it("does not cap long user message estimates", () => {
-    expect(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: "a".repeat(56 * 120),
-      }),
-    ).toBe(2736);
-  });
-
-  it("counts explicit newlines for user message estimates", () => {
-    expect(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: "first\nsecond\nthird",
-      }),
-    ).toBe(162);
-  });
-
-  it("adds terminal context chrome without counting the hidden block as message text", () => {
-    const prompt = appendTerminalContextsToPrompt("Investigate this", [
-      {
-        terminalId: "default",
-        terminalLabel: "Terminal 1",
-        lineStart: 40,
-        lineEnd: 43,
-        text: [
-          "git status",
-          "M apps/web/src/components/chat/MessagesTimeline.tsx",
-          "?? tmp",
-          "",
-        ].join("\n"),
-      },
-    ]);
-
-    expect(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: prompt,
-      }),
-    ).toBe(
-      estimateTimelineMessageHeight({
-        role: "user",
-        text: `${buildInlineTerminalContextText([{ header: "Terminal 1 lines 40-43" }])} Investigate this`,
-      }),
-    );
-  });
-
-  it("uses narrower width to increase user line wrapping", () => {
-    const message = {
-      role: "user" as const,
-      text: "a".repeat(52),
-    };
-
-    expect(estimateTimelineMessageHeight(message, { timelineWidthPx: 320 })).toBe(140);
-    expect(estimateTimelineMessageHeight(message, { timelineWidthPx: 768 })).toBe(118);
-  });
-
-  it("does not clamp user wrapping too aggressively on very narrow layouts", () => {
-    const message = {
-      role: "user" as const,
-      text: "a".repeat(20),
-    };
-
-    expect(estimateTimelineMessageHeight(message, { timelineWidthPx: 100 })).toBe(184);
-    expect(estimateTimelineMessageHeight(message, { timelineWidthPx: 320 })).toBe(118);
-  });
-
-  it("uses narrower width to increase assistant line wrapping", () => {
-    const message = {
-      role: "assistant" as const,
-      text: "a".repeat(200),
-    };
-
-    expect(estimateTimelineMessageHeight(message, { timelineWidthPx: 320 })).toBe(154.75);
-    expect(estimateTimelineMessageHeight(message, { timelineWidthPx: 768 })).toBe(86.5);
-  });
-
-  it("treats inline code as wider when estimating assistant markdown wrapping", () => {
-    const message = {
-      role: "assistant" as const,
-      text: [
-        "Typecheck found one exact-optional-property issue in the browser harness:",
-        "I was always passing `onVirtualizerSnapshot`, including `undefined`.",
-        "I'm tightening that object construction and rerunning the checks.",
-      ].join(" "),
-    };
-
-    expect(estimateTimelineMessageHeight(message, { timelineWidthPx: 768 })).toBe(109.25);
-  });
-});
diff --git a/apps/web/src/components/timelineHeight.ts b/apps/web/src/components/timelineHeight.ts
deleted file mode 100644
index 3cb2aebb889..00000000000
--- a/apps/web/src/components/timelineHeight.ts
+++ /dev/null
@@ -1,131 +0,0 @@
-import { deriveDisplayedUserMessageState } from "../lib/terminalContext";
-import { buildInlineTerminalContextText } from "./chat/userMessageTerminalContexts";
-
-const ASSISTANT_CHARS_PER_LINE_FALLBACK = 72;
-const USER_CHARS_PER_LINE_FALLBACK = 56;
-const USER_LINE_HEIGHT_PX = 22;
-const ASSISTANT_LINE_HEIGHT_PX = 22.75;
-// Assistant rows render as markdown content plus a compact timestamp meta line.
-// The DOM baseline is much smaller than the user bubble chrome, so model it
-// separately instead of reusing the old shared constant.
-const ASSISTANT_BASE_HEIGHT_PX = 41;
-const USER_BASE_HEIGHT_PX = 96;
-const ATTACHMENTS_PER_ROW = 2;
-// Full-app browser measurements land closer to a ~116px attachment row once
-// the bubble shrinks to content width, so calibrate the estimate to that DOM.
-const USER_ATTACHMENT_ROW_HEIGHT_PX = 116;
-const USER_BUBBLE_WIDTH_RATIO = 0.8;
-const USER_BUBBLE_HORIZONTAL_PADDING_PX = 32;
-const ASSISTANT_MESSAGE_HORIZONTAL_PADDING_PX = 8;
-const USER_MONO_AVG_CHAR_WIDTH_PX = 8.4;
-const ASSISTANT_AVG_CHAR_WIDTH_PX = 7.2;
-const MIN_USER_CHARS_PER_LINE = 4;
-const MIN_ASSISTANT_CHARS_PER_LINE = 20;
-const ASSISTANT_INLINE_CODE_WIDTH_MULTIPLIER = 1.2;
-const ASSISTANT_INLINE_CODE_WRAP_OVERHEAD_CHARS = 2;
-const INLINE_CODE_SPAN_REGEX = /`([^`\n]+)`/g;
-
-interface TimelineMessageHeightInput {
-  role: "user" | "assistant" | "system";
-  text: string;
-  attachments?: ReadonlyArray<{ id: string }>;
-}
-
-interface TimelineHeightEstimateLayout {
-  timelineWidthPx: number | null;
-}
-
-function estimateWrappedLineCount(text: string, charsPerLine: number): number {
-  if (text.length === 0) return 1;
-
-  // Avoid allocating via split for long logs; iterate once and count wrapped lines.
-  let lines = 0;
-  let currentLineLength = 0;
-  for (let index = 0; index < text.length; index += 1) {
-    if (text.charCodeAt(index) === 10) {
-      lines += Math.max(1, Math.ceil(currentLineLength / charsPerLine));
-      currentLineLength = 0;
-      continue;
-    }
-    currentLineLength += 1;
-  }
-
-  lines += Math.max(1, Math.ceil(currentLineLength / charsPerLine));
-  return lines;
-}
-
-function isFinitePositiveNumber(value: number | null | undefined): value is number {
-  return typeof value === "number" && Number.isFinite(value) && value > 0;
-}
-
-function estimateCharsPerLineForUser(timelineWidthPx: number | null): number {
-  if (!isFinitePositiveNumber(timelineWidthPx)) return USER_CHARS_PER_LINE_FALLBACK;
-  const bubbleWidthPx = timelineWidthPx * USER_BUBBLE_WIDTH_RATIO;
-  const textWidthPx = Math.max(bubbleWidthPx - USER_BUBBLE_HORIZONTAL_PADDING_PX, 0);
-  return Math.max(MIN_USER_CHARS_PER_LINE, Math.floor(textWidthPx / USER_MONO_AVG_CHAR_WIDTH_PX));
-}
-
-function estimateCharsPerLineForAssistant(timelineWidthPx: number | null): number {
-  if (!isFinitePositiveNumber(timelineWidthPx)) return ASSISTANT_CHARS_PER_LINE_FALLBACK;
-  const textWidthPx = Math.max(timelineWidthPx - ASSISTANT_MESSAGE_HORIZONTAL_PADDING_PX, 0);
-  return Math.max(
-    MIN_ASSISTANT_CHARS_PER_LINE,
-    Math.floor(textWidthPx / ASSISTANT_AVG_CHAR_WIDTH_PX),
-  );
-}
-
-function expandAssistantInlineCodeForEstimate(text: string) {
-  return text.replace(INLINE_CODE_SPAN_REGEX, (_match, code: string) =>
-    "x".repeat(
-      Math.max(
-        code.length + 2,
-        Math.ceil(
-          code.length * ASSISTANT_INLINE_CODE_WIDTH_MULTIPLIER +
-            ASSISTANT_INLINE_CODE_WRAP_OVERHEAD_CHARS,
-        ),
-      ),
-    ),
-  );
-}
-
-export function estimateTimelineMessageHeight(
-  message: TimelineMessageHeightInput,
-  layout: TimelineHeightEstimateLayout = { timelineWidthPx: null },
-): number {
-  if (message.role === "assistant") {
-    const charsPerLine = estimateCharsPerLineForAssistant(layout.timelineWidthPx);
-    const estimatedLines = estimateWrappedLineCount(
-      expandAssistantInlineCodeForEstimate(message.text),
-      charsPerLine,
-    );
-    return ASSISTANT_BASE_HEIGHT_PX + estimatedLines * ASSISTANT_LINE_HEIGHT_PX;
-  }
-
-  if (message.role === "user") {
-    const charsPerLine = estimateCharsPerLineForUser(layout.timelineWidthPx);
-    const displayedUserMessage = deriveDisplayedUserMessageState(message.text);
-    const renderedText =
-      displayedUserMessage.contexts.length > 0
-        ? [
-            buildInlineTerminalContextText(displayedUserMessage.contexts),
-            displayedUserMessage.visibleText,
-          ]
-            .filter((part) => part.length > 0)
-            .join(" ")
-        : displayedUserMessage.visibleText;
-    const estimatedLines = estimateWrappedLineCount(renderedText, charsPerLine);
-    const attachmentCount = message.attachments?.length ?? 0;
-    const attachmentRows = Math.ceil(attachmentCount / ATTACHMENTS_PER_ROW);
-    const attachmentHeight = attachmentRows * USER_ATTACHMENT_ROW_HEIGHT_PX;
-    return USER_BASE_HEIGHT_PX + estimatedLines * USER_LINE_HEIGHT_PX + attachmentHeight;
-  }
-
-  // `system` messages are not rendered in the chat timeline, but keep a stable
-  // explicit branch in case they are present in timeline data.
-  const charsPerLine = estimateCharsPerLineForAssistant(layout.timelineWidthPx);
-  const estimatedLines = estimateWrappedLineCount(
-    expandAssistantInlineCodeForEstimate(message.text),
-    charsPerLine,
-  );
-  return ASSISTANT_BASE_HEIGHT_PX + estimatedLines * ASSISTANT_LINE_HEIGHT_PX;
-}
diff --git a/apps/web/src/components/ui/alert-dialog.tsx b/apps/web/src/components/ui/alert-dialog.tsx
index 5c65f261f59..84bcff96316 100644
--- a/apps/web/src/components/ui/alert-dialog.tsx
+++ b/apps/web/src/components/ui/alert-dialog.tsx
@@ -18,7 +18,7 @@ function AlertDialogBackdrop({ className, ...props }: AlertDialogPrimitive.Backd
   return (
     <AlertDialogPrimitive.Backdrop
       className={cn(
-        "fixed inset-0 z-50 bg-black/32 backdrop-blur-sm transition-all duration-200 ease-out data-ending-style:opacity-0 data-starting-style:opacity-0",
+        "fixed inset-0 z-50 transition-all duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0",
         className,
       )}
       data-slot="alert-dialog-backdrop"
@@ -31,7 +31,7 @@ function AlertDialogViewport({ className, ...props }: AlertDialogPrimitive.Viewp
   return (
     <AlertDialogPrimitive.Viewport
       className={cn(
-        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center p-4",
+        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center bg-white/48 p-4 backdrop-blur-[2px] dark:bg-black/28",
         className,
       )}
       data-slot="alert-dialog-viewport"
diff --git a/apps/web/src/components/ui/autocomplete.tsx b/apps/web/src/components/ui/autocomplete.tsx
index 676db613ae1..d6db87d48c2 100644
--- a/apps/web/src/components/ui/autocomplete.tsx
+++ b/apps/web/src/components/ui/autocomplete.tsx
@@ -193,7 +193,7 @@ function AutocompleteList({ className, ...props }: AutocompletePrimitive.List.Pr
   return (
     <ScrollArea scrollbarGutter scrollFade>
       <AutocompletePrimitive.List
-        className={cn("not-empty:scroll-py-1 not-empty:p-1 in-data-has-overflow-y:pe-3", className)}
+        className={cn("not-empty:scroll-py-1 not-empty:p-1", className)}
         data-slot="autocomplete-list"
         {...props}
       />
diff --git a/apps/web/src/components/ui/combobox.tsx b/apps/web/src/components/ui/combobox.tsx
index 8348d4c2fcf..b83eead95f1 100644
--- a/apps/web/src/components/ui/combobox.tsx
+++ b/apps/web/src/components/ui/combobox.tsx
@@ -22,9 +22,9 @@ function Combobox<Value, Multiple extends boolean | undefined = false>(
   const chipsRef = React.useRef<Element | null>(null);
   const value = React.useMemo(() => ({ chipsRef, multiple: !!props.multiple }), [props.multiple]);
   return (
-    <ComboboxContext.Provider value={value}>
+    <ComboboxContext value={value}>
       <ComboboxPrimitive.Root {...props} />
-    </ComboboxContext.Provider>
+    </ComboboxContext>
   );
 }
 
@@ -151,7 +151,7 @@ function ComboboxPopup({
   side?: ComboboxPrimitive.Positioner.Props["side"];
   anchor?: ComboboxPrimitive.Positioner.Props["anchor"];
 }) {
-  const { chipsRef } = React.useContext(ComboboxContext);
+  const { chipsRef } = React.use(ComboboxContext);
   const anchor = anchorProp ?? chipsRef;
 
   return (
@@ -186,10 +186,12 @@ function ComboboxPopup({
 
 function ComboboxItem({
   className,
+  contentClassName,
   children,
   hideIndicator = false,
   ...props
 }: ComboboxPrimitive.Item.Props & {
+  contentClassName?: string;
   hideIndicator?: boolean;
 }) {
   return (
@@ -204,7 +206,14 @@ function ComboboxItem({
       <ComboboxPrimitive.ItemIndicator className={cn("col-start-1", hideIndicator && "hidden")}>
         <CheckIcon />
       </ComboboxPrimitive.ItemIndicator>
-      <div className={hideIndicator ? "col-start-1 col-span-full" : "col-start-2"}>{children}</div>
+      <div
+        className={cn(
+          hideIndicator ? "col-start-1 col-span-full" : "col-start-2",
+          contentClassName,
+        )}
+      >
+        {children}
+      </div>
     </ComboboxPrimitive.Item>
   );
 }
@@ -264,10 +273,7 @@ function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
   return (
     <ScrollArea scrollbarGutter scrollFade>
       <ComboboxPrimitive.List
-        className={cn(
-          "not-empty:scroll-py-1 not-empty:px-1 not-empty:py-1 in-data-has-overflow-y:pe-3",
-          className,
-        )}
+        className={cn("not-empty:scroll-py-1 not-empty:px-1 not-empty:py-1", className)}
         data-slot="combobox-list"
         {...props}
       />
@@ -275,6 +281,20 @@ function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
   );
 }
 
+/**
+ * A variant of `ComboboxList` without `ScrollArea`, for use when
+ * an external virtualizer (e.g. LegendList) owns the scroll container.
+ */
+function ComboboxListVirtualized({ className, ...props }: ComboboxPrimitive.List.Props) {
+  return (
+    <ComboboxPrimitive.List
+      className={cn("not-empty:px-1 not-empty:py-1", className)}
+      data-slot="combobox-list"
+      {...props}
+    />
+  );
+}
+
 function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
   return <ComboboxPrimitive.Clear className={className} data-slot="combobox-clear" {...props} />;
 }
@@ -304,7 +324,7 @@ function ComboboxChips({
 }: ComboboxPrimitive.Chips.Props & {
   startAddon?: React.ReactNode;
 }) {
-  const { chipsRef } = React.useContext(ComboboxContext);
+  const { chipsRef } = React.use(ComboboxContext);
 
   return (
     <ComboboxPrimitive.Chips
@@ -371,6 +391,7 @@ export {
   ComboboxEmpty,
   ComboboxValue,
   ComboboxList,
+  ComboboxListVirtualized,
   ComboboxClear,
   ComboboxStatus,
   ComboboxRow,
diff --git a/apps/web/src/components/ui/command.tsx b/apps/web/src/components/ui/command.tsx
index 0bd1c7a5737..10edb9ce3b2 100644
--- a/apps/web/src/components/ui/command.tsx
+++ b/apps/web/src/components/ui/command.tsx
@@ -43,7 +43,7 @@ function CommandDialogViewport({ className, ...props }: CommandDialogPrimitive.V
   return (
     <CommandDialogPrimitive.Viewport
       className={cn(
-        "fixed inset-0 z-50 flex flex-col items-center px-4 py-[max(--spacing(4),4vh)] sm:py-[10vh]",
+        "pointer-events-none fixed inset-0 z-50 flex flex-col items-center px-4 py-[max(--spacing(4),4vh)] sm:py-[10vh]",
         className,
       )}
       data-slot="command-dialog-viewport"
@@ -52,14 +52,21 @@ function CommandDialogViewport({ className, ...props }: CommandDialogPrimitive.V
   );
 }
 
-function CommandDialogPopup({ className, children, ...props }: CommandDialogPrimitive.Popup.Props) {
+function CommandDialogPopup({
+  className,
+  children,
+  onBackdropPointerDown,
+  ...props
+}: CommandDialogPrimitive.Popup.Props & {
+  onBackdropPointerDown?: React.PointerEventHandler<HTMLDivElement>;
+}) {
   return (
     <CommandDialogPortal>
-      <CommandDialogBackdrop />
+      <CommandDialogBackdrop onPointerDown={onBackdropPointerDown} />
       <CommandDialogViewport>
         <CommandDialogPrimitive.Popup
           className={cn(
-            "-translate-y-[calc(1.25rem*var(--nested-dialogs))] relative row-start-2 flex max-h-105 min-h-0 w-full min-w-0 max-w-xl scale-[calc(1-0.1*var(--nested-dialogs))] flex-col rounded-2xl border bg-popover not-dark:bg-clip-padding text-popover-foreground opacity-[calc(1-0.1*var(--nested-dialogs))] shadow-lg/5 outline-none transition-[scale,opacity,translate] duration-200 ease-in-out will-change-transform before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:bg-muted/72 before:shadow-[0_1px_--theme(--color-black/4%)] data-nested:data-ending-style:translate-y-8 data-nested:data-starting-style:translate-y-8 data-nested-dialog-open:origin-top data-ending-style:scale-98 data-starting-style:scale-98 data-ending-style:opacity-0 data-starting-style:opacity-0 **:data-[slot=scroll-area-viewport]:data-has-overflow-y:pe-1 dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+            "pointer-events-auto -translate-y-[calc(1.25rem*var(--nested-dialogs))] relative row-start-2 flex max-h-105 min-h-0 w-full min-w-0 max-w-xl scale-[calc(1-0.1*var(--nested-dialogs))] flex-col rounded-2xl border bg-popover not-dark:bg-clip-padding text-popover-foreground opacity-[calc(1-0.1*var(--nested-dialogs))] shadow-lg/5 outline-none transition-[scale,opacity,translate] duration-200 ease-in-out will-change-transform before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-2xl)-1px)] before:bg-muted/72 before:shadow-[0_1px_--theme(--color-black/4%)] data-nested:data-ending-style:translate-y-8 data-nested:data-starting-style:translate-y-8 data-nested-dialog-open:origin-top data-ending-style:scale-98 data-starting-style:scale-98 data-ending-style:opacity-0 data-starting-style:opacity-0 **:data-[slot=scroll-area-viewport]:data-has-overflow-y:pe-1 dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
             className,
           )}
           data-slot="command-dialog-popup"
@@ -137,7 +144,7 @@ function CommandPanel({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       className={cn(
-        "-mx-px not-has-[+[data-slot=command-footer]]:-mb-px relative min-h-0 rounded-t-xl not-has-[+[data-slot=command-footer]]:rounded-b-2xl border border-b-0 bg-popover bg-clip-padding shadow-xs/5 [clip-path:inset(0_1px)] not-has-[+[data-slot=command-footer]]:[clip-path:inset(0_1px_1px_1px_round_0_0_calc(var(--radius-2xl)-1px)_calc(var(--radius-2xl)-1px))] before:pointer-events-none before:absolute before:inset-0 before:rounded-t-[calc(var(--radius-xl)-1px)] **:data-[slot=scroll-area-scrollbar]:mt-2",
+        "-mx-px not-has-[+[data-slot=command-footer]]:-mb-px relative min-h-0 overflow-hidden rounded-t-xl not-has-[+[data-slot=command-footer]]:rounded-b-2xl border border-b-0 bg-popover bg-clip-padding shadow-xs/5 [clip-path:inset(0_1px)] not-has-[+[data-slot=command-footer]]:[clip-path:inset(0_1px_1px_1px_round_0_0_calc(var(--radius-2xl)-1px)_calc(var(--radius-2xl)-1px))] before:pointer-events-none before:absolute before:inset-0 before:rounded-t-[calc(var(--radius-xl)-1px)] **:data-[slot=scroll-area-scrollbar]:mt-2 [touch-action:pan-y]",
         className,
       )}
       {...props}
diff --git a/apps/web/src/components/ui/dialog.tsx b/apps/web/src/components/ui/dialog.tsx
index 080ac809975..bebe1b0ee03 100644
--- a/apps/web/src/components/ui/dialog.tsx
+++ b/apps/web/src/components/ui/dialog.tsx
@@ -24,7 +24,7 @@ function DialogBackdrop({ className, ...props }: DialogPrimitive.Backdrop.Props)
   return (
     <DialogPrimitive.Backdrop
       className={cn(
-        "fixed inset-0 z-50 bg-black/32 backdrop-blur-sm transition-all duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0",
+        "fixed inset-0 z-50 transition-all duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0",
         className,
       )}
       data-slot="dialog-backdrop"
@@ -37,7 +37,7 @@ function DialogViewport({ className, ...props }: DialogPrimitive.Viewport.Props)
   return (
     <DialogPrimitive.Viewport
       className={cn(
-        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center p-4",
+        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center bg-white/48 p-4 backdrop-blur-[2px] dark:bg-black/28",
         className,
       )}
       data-slot="dialog-viewport"
diff --git a/apps/web/src/components/ui/draft-input.tsx b/apps/web/src/components/ui/draft-input.tsx
new file mode 100644
index 00000000000..a81d5d9baf6
--- /dev/null
+++ b/apps/web/src/components/ui/draft-input.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import { useCommitOnBlur } from "~/hooks/useCommitOnBlur";
+import { Input, type InputProps } from "./input";
+
+export type DraftInputProps = Omit<InputProps, "value" | "onChange" | "defaultValue"> & {
+  readonly value: string;
+  readonly onCommit: (next: string) => void;
+};
+
+/**
+ * Text `<Input>` that buffers keystrokes locally and invokes `onCommit`
+ * only when the user finishes editing (blur or Enter). Prevents each
+ * keystroke from triggering a settings-wide re-render or a server RPC
+ * round-trip, which otherwise makes fields backed by a server-hydrated
+ * value feel laggy.
+ */
+export function DraftInput({ value, onCommit, ...rest }: DraftInputProps) {
+  const bag = useCommitOnBlur(value, onCommit);
+  return <Input {...rest} {...bag} />;
+}
diff --git a/apps/web/src/components/ui/input.tsx b/apps/web/src/components/ui/input.tsx
index 001a240ddfd..7ab7eb6cea0 100644
--- a/apps/web/src/components/ui/input.tsx
+++ b/apps/web/src/components/ui/input.tsx
@@ -27,6 +27,31 @@ function Input({
     props.type === "file" &&
       "text-muted-foreground file:me-3 file:bg-transparent file:font-medium file:text-foreground file:text-sm",
   );
+  let inputElement: React.ReactElement;
+
+  if (nativeInput) {
+    const { style, onValueChange: _onValueChange, ...nativeInputProps } = props;
+    const nativeStyle = typeof style === "function" ? undefined : style;
+
+    inputElement = (
+      <input
+        className={inputClassName}
+        data-slot="input"
+        size={typeof size === "number" ? size : undefined}
+        style={nativeStyle}
+        {...(nativeInputProps as React.ComponentProps<"input">)}
+      />
+    );
+  } else {
+    inputElement = (
+      <InputPrimitive
+        className={inputClassName}
+        data-slot="input"
+        size={typeof size === "number" ? size : undefined}
+        {...props}
+      />
+    );
+  }
 
   return (
     <span
@@ -40,21 +65,7 @@ function Input({
       data-size={size}
       data-slot="input-control"
     >
-      {nativeInput ? (
-        <input
-          className={inputClassName}
-          data-slot="input"
-          size={typeof size === "number" ? size : undefined}
-          {...props}
-        />
-      ) : (
-        <InputPrimitive
-          className={inputClassName}
-          data-slot="input"
-          size={typeof size === "number" ? size : undefined}
-          {...props}
-        />
-      )}
+      {inputElement}
     </span>
   );
 }
diff --git a/apps/web/src/components/ui/number-field.tsx b/apps/web/src/components/ui/number-field.tsx
new file mode 100644
index 00000000000..4b348f2ffed
--- /dev/null
+++ b/apps/web/src/components/ui/number-field.tsx
@@ -0,0 +1,156 @@
+"use client";
+
+import { NumberField as NumberFieldPrimitive } from "@base-ui/react/number-field";
+import { MinusIcon, PlusIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "~/lib/utils";
+import { Label } from "~/components/ui/label";
+
+export const NumberFieldContext: React.Context<{
+  fieldId: string;
+} | null> = React.createContext<{
+  fieldId: string;
+} | null>(null);
+
+export function NumberField({
+  id,
+  className,
+  size = "default",
+  ...props
+}: NumberFieldPrimitive.Root.Props & {
+  size?: "sm" | "default" | "lg";
+}): React.ReactElement {
+  const generatedId = React.useId();
+  const fieldId = id ?? generatedId;
+  const contextValue = React.useMemo(() => ({ fieldId }), [fieldId]);
+
+  return (
+    <NumberFieldContext value={contextValue}>
+      <NumberFieldPrimitive.Root
+        className={cn("flex w-full flex-col items-start gap-2", className)}
+        data-size={size}
+        data-slot="number-field"
+        id={fieldId}
+        {...props}
+      />
+    </NumberFieldContext>
+  );
+}
+
+export function NumberFieldGroup({
+  className,
+  ...props
+}: NumberFieldPrimitive.Group.Props): React.ReactElement {
+  return (
+    <NumberFieldPrimitive.Group
+      className={cn(
+        "relative flex w-full justify-between rounded-lg border border-input bg-background not-dark:bg-clip-padding text-base text-foreground shadow-xs/5 ring-ring/24 transition-shadow before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] not-data-disabled:not-focus-within:not-aria-invalid:before:shadow-[0_1px_--theme(--color-black/4%)] focus-within:border-ring focus-within:ring-[3px] has-aria-invalid:border-destructive/36 has-autofill:bg-foreground/4 focus-within:has-aria-invalid:border-destructive/64 focus-within:has-aria-invalid:ring-destructive/48 data-disabled:pointer-events-none data-disabled:opacity-64 sm:text-sm dark:bg-input/32 dark:has-autofill:bg-foreground/8 dark:has-aria-invalid:ring-destructive/24 dark:not-data-disabled:not-focus-within:not-aria-invalid:before:shadow-[0_-1px_--theme(--color-white/6%)] [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0 [[data-disabled],:focus-within,[aria-invalid]]:shadow-none",
+        className,
+      )}
+      data-slot="number-field-group"
+      {...props}
+    />
+  );
+}
+
+export function NumberFieldDecrement({
+  className,
+  ...props
+}: NumberFieldPrimitive.Decrement.Props): React.ReactElement {
+  return (
+    <NumberFieldPrimitive.Decrement
+      className={cn(
+        "relative flex shrink-0 cursor-pointer items-center justify-center rounded-s-[calc(var(--radius-lg)-1px)] in-data-[size=sm]:px-[calc(--spacing(2.5)-1px)] px-[calc(--spacing(3)-1px)] transition-colors pointer-coarse:after:absolute pointer-coarse:after:size-full pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:bg-accent",
+        className,
+      )}
+      data-slot="number-field-decrement"
+      {...props}
+    >
+      <MinusIcon />
+    </NumberFieldPrimitive.Decrement>
+  );
+}
+
+export function NumberFieldIncrement({
+  className,
+  ...props
+}: NumberFieldPrimitive.Increment.Props): React.ReactElement {
+  return (
+    <NumberFieldPrimitive.Increment
+      className={cn(
+        "relative flex shrink-0 cursor-pointer items-center justify-center rounded-e-[calc(var(--radius-lg)-1px)] in-data-[size=sm]:px-[calc(--spacing(2.5)-1px)] px-[calc(--spacing(3)-1px)] transition-colors pointer-coarse:after:absolute pointer-coarse:after:size-full pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:bg-accent",
+        className,
+      )}
+      data-slot="number-field-increment"
+      {...props}
+    >
+      <PlusIcon />
+    </NumberFieldPrimitive.Increment>
+  );
+}
+
+export function NumberFieldInput({
+  className,
+  ...props
+}: NumberFieldPrimitive.Input.Props): React.ReactElement {
+  return (
+    <NumberFieldPrimitive.Input
+      className={cn(
+        "h-8.5 in-data-[size=lg]:h-9.5 in-data-[size=sm]:h-7.5 w-full min-w-0 grow bg-transparent in-data-[size=sm]:px-[calc(--spacing(2.5)-1px)] px-[calc(--spacing(3)-1px)] text-center tabular-nums in-data-[size=lg]:leading-9.5 in-data-[size=sm]:leading-7.5 leading-8.5 outline-none [transition:background-color_5000000s_ease-in-out_0s] sm:h-7.5 sm:in-data-[size=lg]:h-8.5 sm:in-data-[size=sm]:h-6.5 sm:in-data-[size=lg]:leading-8.5 sm:in-data-[size=sm]:leading-8.5 sm:leading-7.5",
+        className,
+      )}
+      data-slot="number-field-input"
+      {...props}
+    />
+  );
+}
+
+export function NumberFieldScrubArea({
+  className,
+  label,
+  ...props
+}: NumberFieldPrimitive.ScrubArea.Props & {
+  label: string;
+}): React.ReactElement {
+  const context = React.use(NumberFieldContext);
+
+  if (!context) {
+    throw new Error(
+      "NumberFieldScrubArea must be used within a NumberField component for accessibility.",
+    );
+  }
+
+  return (
+    <NumberFieldPrimitive.ScrubArea
+      className={cn("flex cursor-ew-resize", className)}
+      data-slot="number-field-scrub-area"
+      {...props}
+    >
+      <Label className="cursor-ew-resize" htmlFor={context.fieldId}>
+        {label}
+      </Label>
+      <NumberFieldPrimitive.ScrubAreaCursor className="drop-shadow-[0_1px_1px_#0008] filter">
+        <CursorGrowIcon />
+      </NumberFieldPrimitive.ScrubAreaCursor>
+    </NumberFieldPrimitive.ScrubArea>
+  );
+}
+
+export function CursorGrowIcon(props: React.ComponentProps<"svg">): React.ReactElement {
+  return (
+    <svg
+      aria-hidden="true"
+      fill="black"
+      height="14"
+      stroke="white"
+      viewBox="0 0 24 14"
+      width="26"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path d="M19.5 5.5L6.49737 5.51844V2L1 6.9999L6.5 12L6.49737 8.5L19.5 8.5V12L25 6.9999L19.5 2V5.5Z" />
+    </svg>
+  );
+}
+
+export { NumberFieldPrimitive };
diff --git a/apps/web/src/components/ui/scroll-area.tsx b/apps/web/src/components/ui/scroll-area.tsx
index 50deb1ba871..f9a36386751 100644
--- a/apps/web/src/components/ui/scroll-area.tsx
+++ b/apps/web/src/components/ui/scroll-area.tsx
@@ -10,20 +10,26 @@ function ScrollArea({
   scrollFade = false,
   scrollbarGutter = false,
   hideScrollbars = false,
+  chainVerticalScroll = false,
   ...props
 }: ScrollAreaPrimitive.Root.Props & {
   scrollFade?: boolean;
   scrollbarGutter?: boolean;
   hideScrollbars?: boolean;
+  chainVerticalScroll?: boolean;
 }) {
   return (
-    <ScrollAreaPrimitive.Root className={cn("size-full min-h-0", className)} {...props}>
+    <ScrollAreaPrimitive.Root
+      className={cn("relative size-full min-h-0 overflow-hidden rounded-[inherit]", className)}
+      {...props}
+    >
       <ScrollAreaPrimitive.Viewport
         className={cn(
-          "h-full overscroll-contain rounded-[inherit] outline-none transition-shadows focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-has-overflow-x:overscroll-x-contain",
+          "h-full max-h-[inherit] overflow-auto overscroll-contain rounded-[inherit] outline-none transition-shadows focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-has-overflow-x:overscroll-x-contain",
+          chainVerticalScroll && "overscroll-y-auto",
           scrollFade &&
             "mask-t-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-start)))] mask-b-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-end)))] mask-l-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-start)))] mask-r-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-end)))] [--fade-size:1.5rem]",
-          scrollbarGutter && "data-has-overflow-y:pe-2.5 data-has-overflow-x:pb-2.5",
+          scrollbarGutter && "[scrollbar-gutter:stable]",
           hideScrollbars &&
             "[-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden",
         )}
diff --git a/apps/web/src/components/ui/select.tsx b/apps/web/src/components/ui/select.tsx
index 5c423ef05ba..3649a567f73 100644
--- a/apps/web/src/components/ui/select.tsx
+++ b/apps/web/src/components/ui/select.tsx
@@ -12,7 +12,7 @@ import { cn } from "~/lib/utils";
 const Select = SelectPrimitive.Root;
 
 const selectTriggerVariants = cva(
-  "relative inline-flex select-none items-center justify-between gap-2 border rounded-lg text-left text-base outline-none transition-[color,box-shadow,background-color] data-disabled:pointer-events-none data-disabled:opacity-64 sm:text-sm [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4",
+  "relative inline-flex cursor-pointer select-none items-center justify-between gap-2 border rounded-lg text-left text-base outline-none transition-[color,box-shadow,background-color] data-disabled:pointer-events-none data-disabled:opacity-64 sm:text-sm [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4",
   {
     defaultVariants: {
       size: "default",
@@ -105,20 +105,24 @@ function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
 
 function SelectPopup({
   className,
+  popupClassName,
   children,
   side = "bottom",
   sideOffset = 4,
   align = "start",
   alignOffset = 0,
   alignItemWithTrigger = true,
+  matchTriggerWidth = true,
   anchor,
   ...props
 }: SelectPrimitive.Popup.Props & {
+  popupClassName?: string;
   side?: SelectPrimitive.Positioner.Props["side"];
   sideOffset?: SelectPrimitive.Positioner.Props["sideOffset"];
   align?: SelectPrimitive.Positioner.Props["align"];
   alignOffset?: SelectPrimitive.Positioner.Props["alignOffset"];
   alignItemWithTrigger?: SelectPrimitive.Positioner.Props["alignItemWithTrigger"];
+  matchTriggerWidth?: boolean;
   anchor?: SelectPrimitive.Positioner.Props["anchor"];
 }) {
   return (
@@ -144,7 +148,13 @@ function SelectPopup({
           >
             <ChevronUpIcon className="relative size-4.5 sm:size-4" />
           </SelectPrimitive.ScrollUpArrow>
-          <div className="relative h-full min-w-(--anchor-width) rounded-lg border bg-popover not-dark:bg-clip-padding shadow-lg/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]">
+          <div
+            className={cn(
+              "relative h-full rounded-lg border bg-popover not-dark:bg-clip-padding shadow-lg/5 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+              matchTriggerWidth && "min-w-(--anchor-width)",
+              popupClassName,
+            )}
+          >
             <SelectPrimitive.List
               className={cn("max-h-(--available-height) overflow-y-auto p-1", className)}
               data-slot="select-list"
diff --git a/apps/web/src/components/ui/sidebar.tsx b/apps/web/src/components/ui/sidebar.tsx
index cfa29e950b9..d27412c9599 100644
--- a/apps/web/src/components/ui/sidebar.tsx
+++ b/apps/web/src/components/ui/sidebar.tsx
@@ -19,7 +19,7 @@ import { Skeleton } from "~/components/ui/skeleton";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "~/components/ui/tooltip";
 import { useIsMobile } from "~/hooks/useMediaQuery";
 import { getLocalStorageItem, setLocalStorageItem } from "~/hooks/useLocalStorage";
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 
 const SIDEBAR_COOKIE_NAME = "sidebar_state";
 const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
@@ -77,7 +77,7 @@ const SidebarContext = React.createContext<SidebarContextProps | null>(null);
 const SidebarInstanceContext = React.createContext<SidebarInstanceContextProps | null>(null);
 
 function useSidebar() {
-  const context = React.useContext(SidebarContext);
+  const context = React.use(SidebarContext);
   if (!context) {
     throw new Error("useSidebar must be used within a SidebarProvider.");
   }
@@ -148,7 +148,7 @@ function SidebarProvider({
   );
 
   return (
-    <SidebarContext.Provider value={contextValue}>
+    <SidebarContext value={contextValue}>
       <div
         className={cn(
           "group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar",
@@ -166,7 +166,7 @@ function SidebarProvider({
       >
         {children}
       </div>
-    </SidebarContext.Provider>
+    </SidebarContext>
   );
 }
 
@@ -206,7 +206,7 @@ function Sidebar({
 
   if (collapsible === "none") {
     return (
-      <SidebarInstanceContext.Provider value={instanceContextValue}>
+      <SidebarInstanceContext value={instanceContextValue}>
         <div
           className={cn(
             "flex h-full w-(--sidebar-width) flex-col bg-sidebar text-sidebar-foreground",
@@ -217,13 +217,13 @@ function Sidebar({
         >
           {children}
         </div>
-      </SidebarInstanceContext.Provider>
+      </SidebarInstanceContext>
     );
   }
 
   if (isMobile) {
     return (
-      <SidebarInstanceContext.Provider value={instanceContextValue}>
+      <SidebarInstanceContext value={instanceContextValue}>
         <Sheet onOpenChange={setOpenMobile} open={openMobile} {...props}>
           <SheetPopup
             className={cn(
@@ -245,15 +245,22 @@ function Sidebar({
               <SheetTitle>Sidebar</SheetTitle>
               <SheetDescription>Displays the mobile sidebar.</SheetDescription>
             </SheetHeader>
-            <div className="flex h-full w-full flex-col">{children}</div>
+            <div
+              className={cn(
+                "flex h-full w-full flex-col pb-safe pt-safe",
+                side === "left" ? "pl-safe" : "pr-safe",
+              )}
+            >
+              {children}
+            </div>
           </SheetPopup>
         </Sheet>
-      </SidebarInstanceContext.Provider>
+      </SidebarInstanceContext>
     );
   }
 
   return (
-    <SidebarInstanceContext.Provider value={instanceContextValue}>
+    <SidebarInstanceContext value={instanceContextValue}>
       <div
         className="group peer hidden text-sidebar-foreground md:block"
         data-collapsible={state === "collapsed" ? collapsible : ""}
@@ -298,7 +305,7 @@ function Sidebar({
           </div>
         </div>
       </div>
-    </SidebarInstanceContext.Provider>
+    </SidebarInstanceContext>
   );
 }
 
@@ -338,7 +345,7 @@ function SidebarRail({
   ...props
 }: React.ComponentProps<"button">) {
   const { open, toggleSidebar } = useSidebar();
-  const sidebarInstance = React.useContext(SidebarInstanceContext);
+  const sidebarInstance = React.use(SidebarInstanceContext);
   const railRef = React.useRef<HTMLButtonElement | null>(null);
   const suppressClickRef = React.useRef(false);
   const resizeStateRef = React.useRef<{
@@ -882,7 +889,7 @@ function SidebarMenuSkeleton({
 }: React.ComponentProps<"div"> & {
   showIcon?: boolean;
 }) {
-  // Random width between 50 to 90%.
+  // Random width between 50 to 90%. Intentionally wrapped in useMemo to avoid changing width on every render.
   const width = React.useMemo(() => {
     return `${Math.floor(Math.random() * 40) + 50}%`;
   }, []);
diff --git a/apps/web/src/components/ui/toast.logic.test.ts b/apps/web/src/components/ui/toast.logic.test.ts
index e634d7d9463..fefb61196bb 100644
--- a/apps/web/src/components/ui/toast.logic.test.ts
+++ b/apps/web/src/components/ui/toast.logic.test.ts
@@ -45,6 +45,62 @@ describe("buildVisibleToastLayout", () => {
     );
   });
 
+  it("reflows live toasts forward when the front toast is dismissed", () => {
+    const visibleToasts = [
+      { id: "a", height: 48, transitionStatus: "ending" as const },
+      { id: "b", height: 72 },
+      { id: "c", height: 24 },
+    ];
+
+    const layout = buildVisibleToastLayout(visibleToasts);
+
+    // frontmost height should be the first live toast, not the ending one
+    assert.equal(layout.frontmostHeight, 72);
+    assert.deepEqual(
+      layout.items.map(({ toast, visibleIndex, offsetY }) => ({
+        id: toast.id,
+        visibleIndex,
+        offsetY,
+      })),
+      [
+        // Ending toast stays at its front slot; data-ending-style drives its exit
+        { id: "a", visibleIndex: 0, offsetY: 0 },
+        // Live toasts get fresh indices starting at 0 so they move up in sync
+        { id: "b", visibleIndex: 0, offsetY: 0 },
+        { id: "c", visibleIndex: 1, offsetY: 72 },
+      ],
+    );
+  });
+
+  it("keeps a non-front ending toast at its current slot so it exits straight", () => {
+    const visibleToasts = [
+      { id: "a", height: 48 },
+      { id: "b", height: 72, transitionStatus: "ending" as const },
+      { id: "c", height: 24 },
+    ];
+
+    const layout = buildVisibleToastLayout(visibleToasts);
+
+    // front toast stays, so frontmost height is unchanged
+    assert.equal(layout.frontmostHeight, 48);
+    assert.deepEqual(
+      layout.items.map(({ toast, visibleIndex, offsetY }) => ({
+        id: toast.id,
+        visibleIndex,
+        offsetY,
+      })),
+      [
+        // Front live toast — unaffected
+        { id: "a", visibleIndex: 0, offsetY: 0 },
+        // Ending toast keeps its pre-dismissal slot so its horizontal exit
+        // originates from where the user saw it (not from Y=0).
+        { id: "b", visibleIndex: 1, offsetY: 48 },
+        // Live toast behind "b" slides forward into the vacated slot.
+        { id: "c", visibleIndex: 1, offsetY: 48 },
+      ],
+    );
+  });
+
   it("treats missing heights as zero", () => {
     const layout = buildVisibleToastLayout([
       { id: "a" },
diff --git a/apps/web/src/components/ui/toast.logic.ts b/apps/web/src/components/ui/toast.logic.ts
index 09905a7a670..80f23970cee 100644
--- a/apps/web/src/components/ui/toast.logic.ts
+++ b/apps/web/src/components/ui/toast.logic.ts
@@ -14,6 +14,12 @@ type ToastWithHeight = {
   height?: number | null | undefined;
 };
 
+type ToastWithTransitionStatus = {
+  transitionStatus?: "starting" | "ending" | undefined;
+};
+
+type ToastWithLayoutProps = ToastWithHeight & ToastWithTransitionStatus;
+
 type VisibleToastLayoutItem<TToast extends object> = {
   toast: TToast;
   visibleIndex: number;
@@ -21,25 +27,61 @@ type VisibleToastLayoutItem<TToast extends object> = {
 };
 
 export function buildVisibleToastLayout<TToast extends object>(
-  visibleToasts: readonly (TToast & ToastWithHeight)[],
+  visibleToasts: readonly (TToast & ToastWithLayoutProps)[],
 ): {
   frontmostHeight: number;
-  items: VisibleToastLayoutItem<TToast & ToastWithHeight>[];
+  items: VisibleToastLayoutItem<TToast & ToastWithLayoutProps>[];
 } {
-  let offsetY = 0;
+  // Two parallel cursors:
+  //   - `full*`  advances on every toast, so an ending toast keeps the slot it
+  //     occupied before dismissal and its data-ending-style exit transform
+  //     originates from the correct position (critical for dismissing a
+  //     non-front toast in the expanded stack — otherwise it would snap to
+  //     Y=0 and slide off diagonally).
+  //   - `live*`  advances only on non-ending toasts, so live toasts reflow
+  //     past the vacated slot in parallel with the exit animation instead of
+  //     waiting for it to finish (which caused a visible "stop and bump").
+  let fullIndex = 0;
+  let fullOffsetY = 0;
+  let liveIndex = 0;
+  let liveOffsetY = 0;
+
+  const items: VisibleToastLayoutItem<TToast & ToastWithLayoutProps>[] = visibleToasts.map(
+    (toast) => {
+      const height = normalizeToastHeight(toast.height);
+
+      if (toast.transitionStatus === "ending") {
+        const item = {
+          toast,
+          visibleIndex: fullIndex,
+          offsetY: fullOffsetY,
+        };
+        fullOffsetY += height;
+        fullIndex += 1;
+        return item;
+      }
 
-  return {
-    frontmostHeight: normalizeToastHeight(visibleToasts[0]?.height),
-    items: visibleToasts.map((toast, visibleIndex) => {
       const item = {
         toast,
-        visibleIndex,
-        offsetY,
+        visibleIndex: liveIndex,
+        offsetY: liveOffsetY,
       };
 
-      offsetY += normalizeToastHeight(toast.height);
+      fullOffsetY += height;
+      fullIndex += 1;
+      liveOffsetY += height;
+      liveIndex += 1;
       return item;
-    }),
+    },
+  );
+
+  // Frontmost height should reflect the first non-ending (live) toast so the
+  // stack sizes to what's actually staying on screen.
+  const frontmostLiveToast = visibleToasts.find((toast) => toast.transitionStatus !== "ending");
+
+  return {
+    frontmostHeight: normalizeToastHeight(frontmostLiveToast?.height),
+    items,
   };
 }
 
diff --git a/apps/web/src/components/ui/toast.tsx b/apps/web/src/components/ui/toast.tsx
index 916f1c5e970..0ebf0c8a7f2 100644
--- a/apps/web/src/components/ui/toast.tsx
+++ b/apps/web/src/components/ui/toast.tsx
@@ -1,17 +1,28 @@
 "use client";
 
 import { Toast } from "@base-ui/react/toast";
-import { useEffect, useMemo, type CSSProperties } from "react";
+import {
+  useEffect,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ComponentPropsWithoutRef,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
 import { useParams } from "@tanstack/react-router";
 import { type ScopedThreadRef, type ThreadId } from "@t3tools/contracts";
 import {
   CheckIcon,
+  ChevronDownIcon,
+  ChevronUpIcon,
   CircleAlertIcon,
   CircleCheckIcon,
   CopyIcon,
   InfoIcon,
   LoaderCircleIcon,
   TriangleAlertIcon,
+  XIcon,
 } from "lucide-react";
 
 import { cn } from "~/lib/utils";
@@ -28,9 +39,34 @@ import {
 export type ThreadToastData = {
   threadRef?: ScopedThreadRef | null;
   threadId?: ThreadId | null;
+  leadingIcon?: ReactNode;
   tooltipStyle?: boolean;
+  onClose?: (() => void) | undefined;
   dismissAfterVisibleMs?: number;
   hideCopyButton?: boolean;
+  secondaryActionProps?: ComponentPropsWithoutRef<"button">;
+  secondaryActionVariant?:
+    | "default"
+    | "destructive"
+    | "destructive-outline"
+    | "ghost"
+    | "link"
+    | "outline"
+    | "secondary";
+  /** Optional extra body shown after toggling “Show details” (e.g. a list of pending RPCs). */
+  expandableContent?: ReactNode;
+  expandableLabels?: { expand?: string; collapse?: string };
+  /** When set with `expandableContent`, the summary + label act as one text disclosure (no separate chevron row). */
+  expandableDescriptionTrigger?: boolean;
+  actionLayout?: "inline" | "stacked-end";
+  actionVariant?:
+    | "default"
+    | "destructive"
+    | "destructive-outline"
+    | "ghost"
+    | "link"
+    | "outline"
+    | "secondary";
 };
 
 const toastManager = Toast.createToastManager<ThreadToastData>();
@@ -46,25 +82,303 @@ const TOAST_ICONS = {
   warning: TriangleAlertIcon,
 } as const;
 
+/** Visually shorten long error bodies; clipboard copy still uses the full `description` string. */
+const ERROR_DESCRIPTION_CLAMP_MIN_CHARS = 180;
+function errorDescriptionClampClass(type: unknown, description: unknown): string | undefined {
+  if (type !== "error" || typeof description !== "string") {
+    return undefined;
+  }
+  if (description.length < ERROR_DESCRIPTION_CLAMP_MIN_CHARS) {
+    return undefined;
+  }
+  return "line-clamp-4";
+}
+
+/** Dismiss-only: circular control overlapping the card corner (iOS notification–style). */
+const toastCornerDismissClass = "absolute z-20 -top-1.5 -right-1.5";
+const toastCornerOrbClass = cn(
+  "inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-full border border-border/60 bg-popover/92 text-muted-foreground shadow-sm outline-none backdrop-blur-sm",
+  "transition-[color,background-color,box-shadow] hover:bg-popover hover:text-foreground",
+  "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+);
+
+function handleToastDismissClick(
+  manager: typeof toastManager | typeof anchoredToastManager,
+  toastId: ToastId,
+  onClose: (() => void) | undefined,
+) {
+  onClose?.();
+  manager.close(toastId);
+}
+
 function CopyErrorButton({ text }: { text: string }) {
   const { copyToClipboard, isCopied } = useCopyToClipboard();
 
   return (
     <button
-      className="shrink-0 cursor-pointer rounded-md p-1 text-muted-foreground opacity-60 transition-opacity hover:opacity-100"
+      className="inline-flex size-5 shrink-0 cursor-pointer items-center justify-center rounded-md p-0 text-muted-foreground/80 transition-colors hover:text-muted-foreground"
       onClick={() => copyToClipboard(text)}
       title="Copy error"
       type="button"
     >
-      {isCopied ? (
-        <CheckIcon className="size-3.5 text-success" />
-      ) : (
-        <CopyIcon className="size-3.5" />
-      )}
+      {isCopied ? <CheckIcon className="size-3 text-success" /> : <CopyIcon className="size-3" />}
     </button>
   );
 }
 
+/** Scrollable cap for long expandable lists (~10rem); keeps the toast from growing without bound. */
+const toastExpandablePanelClassName =
+  "mt-2 max-h-40 min-h-0 overflow-y-auto overscroll-contain pr-0.5 select-text";
+
+function ToastExpandableSection({
+  children,
+  labels,
+}: {
+  children: ReactNode;
+  labels: { expand?: string; collapse?: string };
+}) {
+  const [open, setOpen] = useState(false);
+  const expandLabel = labels.expand ?? "Show details";
+  const collapseLabel = labels.collapse ?? "Hide details";
+
+  return (
+    <div className="min-w-0">
+      <button
+        aria-expanded={open}
+        className="inline-flex cursor-pointer items-center gap-1 rounded-md py-0.5 text-left text-xs font-medium text-muted-foreground transition-colors hover:text-foreground"
+        onClick={() => setOpen((prev) => !prev)}
+        type="button"
+      >
+        {open ? (
+          <ChevronUpIcon className="size-3.5 shrink-0 opacity-80" strokeWidth={2.25} />
+        ) : (
+          <ChevronDownIcon className="size-3.5 shrink-0 opacity-80" strokeWidth={2.25} />
+        )}
+        {open ? collapseLabel : expandLabel}
+      </button>
+      {open ? <div className={toastExpandablePanelClassName}>{children}</div> : null}
+    </div>
+  );
+}
+
+function ToastDescriptionAndExpandable({
+  toastData,
+  toastDescription,
+  toastType,
+}: {
+  toastData: ThreadToastData | undefined;
+  toastDescription: unknown;
+  toastType: unknown;
+}) {
+  const expandableContent = toastData?.expandableContent;
+  const labels = toastData?.expandableLabels ?? {};
+  const descriptionTrigger = toastData?.expandableDescriptionTrigger ?? false;
+  const descriptionClassName = cn(
+    "min-w-0 select-text wrap-break-word text-muted-foreground",
+    errorDescriptionClampClass(toastType, toastDescription),
+  );
+  const [open, setOpen] = useState(false);
+
+  if (!expandableContent) {
+    return <Toast.Description className={descriptionClassName} data-slot="toast-description" />;
+  }
+
+  if (!descriptionTrigger) {
+    return (
+      <>
+        <Toast.Description className={descriptionClassName} data-slot="toast-description" />
+        <ToastExpandableSection labels={labels}>{expandableContent}</ToastExpandableSection>
+      </>
+    );
+  }
+
+  const expandLabel = labels.expand ?? "Show details";
+  const collapseLabel = labels.collapse ?? "Hide details";
+
+  const toggle = () => setOpen((v) => !v);
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      toggle();
+    }
+  };
+
+  return (
+    <>
+      <div
+        aria-expanded={open}
+        className={cn(
+          "group flex min-w-0 w-full cursor-pointer select-none items-start gap-1.5 rounded-sm text-left outline-none ring-offset-background",
+          "transition-colors hover:bg-muted/40",
+          "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+        )}
+        onClick={toggle}
+        onKeyDown={onKeyDown}
+        role="button"
+        tabIndex={0}
+        title={open ? collapseLabel : expandLabel}
+      >
+        <div className="min-w-0 flex-1">
+          <Toast.Description
+            className={cn(
+              "min-w-0 select-none wrap-break-word text-muted-foreground",
+              errorDescriptionClampClass(toastType, toastDescription),
+              "underline-offset-2 decoration-muted-foreground/60 group-hover:underline",
+            )}
+            data-slot="toast-description"
+          />
+        </div>
+        {open ? (
+          <ChevronUpIcon
+            aria-hidden
+            className="mt-0.5 size-3.5 shrink-0 text-muted-foreground opacity-80"
+            strokeWidth={2.25}
+          />
+        ) : (
+          <ChevronDownIcon
+            aria-hidden
+            className="mt-0.5 size-3.5 shrink-0 text-muted-foreground opacity-80"
+            strokeWidth={2.25}
+          />
+        )}
+      </div>
+      {open ? <div className={toastExpandablePanelClassName}>{expandableContent}</div> : null}
+    </>
+  );
+}
+
+type ToastIconComponent = (typeof TOAST_ICONS)[keyof typeof TOAST_ICONS];
+
+interface ToastBodyDescriptor {
+  readonly Icon: ToastIconComponent | null | undefined;
+  readonly stackedActionLayout: boolean;
+  readonly actionVariant: NonNullable<ThreadToastData["actionVariant"]>;
+  readonly secondaryActionVariant: NonNullable<ThreadToastData["secondaryActionVariant"]>;
+  readonly copyErrorText: string | null;
+  readonly hasTrailingControls: boolean;
+  readonly inlineContentEndPad: string;
+}
+
+function deriveToastBodyDescriptor(toast: {
+  readonly type?: string | undefined;
+  readonly description?: unknown;
+  readonly actionProps?: unknown;
+  readonly data?: ThreadToastData | undefined;
+}): ToastBodyDescriptor {
+  const Icon = toast.type ? TOAST_ICONS[toast.type as keyof typeof TOAST_ICONS] : null;
+  const stackedActionLayout =
+    toast.actionProps !== undefined && toast.data?.actionLayout === "stacked-end";
+  const actionVariant: NonNullable<ThreadToastData["actionVariant"]> =
+    toast.data?.actionVariant ?? "default";
+  const secondaryActionVariant: NonNullable<ThreadToastData["secondaryActionVariant"]> =
+    toast.data?.secondaryActionVariant ?? "outline";
+  const copyErrorText =
+    toast.type === "error" && typeof toast.description === "string" && !toast.data?.hideCopyButton
+      ? toast.description
+      : null;
+  const hasSecondaryAction = toast.data?.secondaryActionProps !== undefined;
+  const hasTrailingControls =
+    copyErrorText !== null || toast.actionProps !== undefined || hasSecondaryAction;
+  const inlineContentEndPad = hasTrailingControls ? "pr-6" : "pr-10";
+  return {
+    Icon,
+    stackedActionLayout,
+    actionVariant,
+    secondaryActionVariant,
+    copyErrorText,
+    hasTrailingControls,
+    inlineContentEndPad,
+  };
+}
+
+interface ToastBodyContentProps extends ToastBodyDescriptor {
+  readonly actionProps: { readonly children?: ReactNode } | undefined;
+  readonly toastData: ThreadToastData | undefined;
+  readonly toastDescription: unknown;
+  readonly toastType: unknown;
+}
+
+function ToastBodyContent({
+  stackedActionLayout,
+  Icon,
+  copyErrorText,
+  actionProps,
+  actionVariant,
+  secondaryActionVariant,
+  hasTrailingControls,
+  toastData,
+  toastDescription,
+  toastType,
+}: ToastBodyContentProps) {
+  const secondaryActionProps = toastData?.secondaryActionProps;
+  const leadingIcon = toastData?.leadingIcon;
+  const { className: secondaryActionClassName, ...secondaryActionRest } =
+    secondaryActionProps ?? {};
+
+  return (
+    <>
+      <div className={cn("flex min-w-0 gap-2", !stackedActionLayout && "flex-1")}>
+        {leadingIcon ? (
+          <div
+            className="flex h-lh w-4 shrink-0 items-center justify-center"
+            data-slot="toast-icon"
+          >
+            {leadingIcon}
+          </div>
+        ) : Icon ? (
+          <div
+            className="[&>svg]:h-lh [&>svg]:w-4 [&_svg]:pointer-events-none [&_svg]:shrink-0"
+            data-slot="toast-icon"
+          >
+            <Icon className="in-data-[type=loading]:animate-spin in-data-[type=error]:text-destructive in-data-[type=info]:text-info in-data-[type=success]:text-success in-data-[type=warning]:text-warning in-data-[type=loading]:opacity-80" />
+          </div>
+        ) : null}
+        <div
+          className={cn(
+            "flex min-h-0 min-w-0 flex-1 flex-col gap-0.5",
+            stackedActionLayout && "pr-5",
+          )}
+        >
+          <Toast.Title className="min-w-0 wrap-break-word font-medium" data-slot="toast-title" />
+          <ToastDescriptionAndExpandable
+            toastData={toastData}
+            toastDescription={toastDescription}
+            toastType={toastType}
+          />
+        </div>
+      </div>
+      {hasTrailingControls ? (
+        <div
+          className={cn(
+            "flex items-center gap-1.5",
+            stackedActionLayout ? "w-full justify-end" : "shrink-0",
+          )}
+        >
+          {copyErrorText !== null ? <CopyErrorButton text={copyErrorText} /> : null}
+          {secondaryActionProps ? (
+            <button
+              {...secondaryActionRest}
+              className={cn(
+                buttonVariants({ size: "xs", variant: secondaryActionVariant }),
+                secondaryActionClassName,
+              )}
+              type="button"
+            />
+          ) : null}
+          {actionProps ? (
+            <Toast.Action
+              className={cn(buttonVariants({ size: "xs", variant: actionVariant }), "shrink-0")}
+              data-slot="toast-action"
+            >
+              {actionProps.children}
+            </Toast.Action>
+          ) : null}
+        </div>
+      ) : null}
+    </>
+  );
+}
+
 type ToastPosition =
   | "top-left"
   | "top-center"
@@ -227,16 +541,17 @@ function Toasts({ position = "top-right" }: { position: ToastPosition }) {
         }
       >
         {visibleToastLayout.items.map(({ toast, visibleIndex, offsetY }) => {
-          const Icon = toast.type ? TOAST_ICONS[toast.type as keyof typeof TOAST_ICONS] : null;
           const hideCollapsedContent = shouldHideCollapsedToastContent(
             visibleIndex,
             visibleToastLayout.items.length,
           );
+          const bodyDescriptor = deriveToastBodyDescriptor(toast);
+          const { stackedActionLayout, inlineContentEndPad } = bodyDescriptor;
 
           return (
             <Toast.Root
               className={cn(
-                "absolute z-[calc(9999-var(--toast-index))] h-(--toast-calc-height) w-full select-none rounded-lg border bg-popover not-dark:bg-clip-padding text-popover-foreground shadow-lg/5 [transition:transform_.5s_cubic-bezier(.22,1,.36,1),opacity_.5s,height_.15s] before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+                "absolute z-[calc(9999-var(--toast-index))] w-full overflow-visible select-none rounded-lg border bg-popover not-dark:bg-clip-padding text-popover-foreground shadow-lg/5 [transition:transform_.5s_cubic-bezier(.22,1,.36,1),opacity_.5s,height_.15s] before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
                 // Base positioning using data-position
                 "data-[position*=right]:right-0 data-[position*=right]:left-auto",
                 "data-[position*=left]:right-auto data-[position*=left]:left-0",
@@ -247,11 +562,19 @@ function Toasts({ position = "top-right" }: { position: ToastPosition }) {
                 "after:absolute after:left-0 after:h-[calc(var(--toast-gap)+1px)] after:w-full",
                 "data-[position*=top]:after:top-full",
                 "data-[position*=bottom]:after:bottom-full",
-                // Define some variables
-                // Base UI exposes a shared front-most height for the collapsed stack.
-                // If that shared measurement is briefly stale, long content can render
-                // outside the card until hover expands the toast and swaps to its own height.
-                "[--toast-calc-height:max(var(--toast-frontmost-height,var(--toast-height)),var(--toast-height))] [--toast-gap:--spacing(3)] [--toast-peek:--spacing(3)] [--toast-scale:calc(max(0,1-(var(--toast-index)*.1)))] [--toast-shrink:calc(1-var(--toast-scale))]",
+                // `--toast-calc-height`: behind + collapsed = peek height only (content `opacity-0`);
+                // max(front, own) there produced a tall empty shell for long bodies.
+                visibleIndex > 0
+                  ? "not-data-expanded:[--toast-calc-height:var(--toast-frontmost-height)] data-expanded:[--toast-calc-height:max(var(--toast-frontmost-height,var(--toast-height)),var(--toast-height))]"
+                  : "[--toast-calc-height:max(var(--toast-frontmost-height,var(--toast-height)),var(--toast-height))]",
+                "[--toast-gap:--spacing(3)] [--toast-peek:--spacing(3)] [--toast-scale:calc(max(0,1-(var(--toast-index)*.1)))] [--toast-shrink:calc(1-var(--toast-scale))]",
+                // Root height: never `min-h-(--toast-height)` — Base UI measures height by briefly forcing
+                // `height: auto` on this node; an old `min-height` from `--toast-height` blocks shrinking,
+                // so `recalculateHeight` keeps the inflated value after an expandable closes.
+                // Behind + collapsed: fixed peek. Otherwise natural height (expand/collapse, hover stack).
+                visibleIndex > 0
+                  ? "not-data-expanded:h-(--toast-calc-height) data-expanded:h-auto"
+                  : "h-auto",
                 // Define offset-y variable
                 "data-[position*=top]:[--toast-calc-offset-y:calc(var(--toast-offset-y)+var(--toast-index)*var(--toast-gap)+var(--toast-swipe-movement-y))]",
                 "data-[position*=bottom]:[--toast-calc-offset-y:calc(var(--toast-offset-y)*-1+var(--toast-index)*var(--toast-gap)*-1+var(--toast-swipe-movement-y))]",
@@ -260,8 +583,7 @@ function Toasts({ position = "top-right" }: { position: ToastPosition }) {
                 "data-[position*=bottom]:transform-[translateX(var(--toast-swipe-movement-x))_translateY(calc(var(--toast-swipe-movement-y)-(var(--toast-index)*var(--toast-peek))-(var(--toast-shrink)*var(--toast-calc-height))))_scale(var(--toast-scale))]",
                 // Limited state
                 "data-limited:opacity-0",
-                // Expanded state
-                "data-expanded:h-(--toast-height)",
+                // Expanded stack
                 "data-position:data-expanded:transform-[translateX(var(--toast-swipe-movement-x))_translateY(var(--toast-calc-offset-y))]",
                 // Starting and ending animations
                 "data-[position*=top]:data-starting-style:transform-[translateY(calc(-100%-var(--toast-inset)))]",
@@ -302,47 +624,38 @@ function Toasts({ position = "top-right" }: { position: ToastPosition }) {
                 dismissAfterVisibleMs={toast.data?.dismissAfterVisibleMs}
                 toastId={toast.id}
               />
+              <div className={toastCornerDismissClass}>
+                <button
+                  aria-label="Dismiss notification"
+                  className={toastCornerOrbClass}
+                  data-slot="toast-close"
+                  onClick={() =>
+                    handleToastDismissClick(toastManager, toast.id, toast.data?.onClose)
+                  }
+                  type="button"
+                >
+                  <XIcon className="size-3" strokeWidth={2.25} />
+                </button>
+              </div>
               <Toast.Content
                 className={cn(
-                  "pointer-events-auto flex items-center justify-between gap-1.5 overflow-hidden px-3.5 py-3 text-sm transition-opacity duration-250 data-expanded:opacity-100",
+                  // `overflow-x: clip` avoids the CSS quirk where pairing `hidden` + `y: visible`
+                  // forces `y` to `auto`. Expandable detail panels can extend below without being cut off.
+                  "pointer-events-auto min-h-0 overflow-y-visible pl-3.5 text-sm transition-opacity duration-250 [overflow-x:clip] data-expanded:opacity-100",
+                  stackedActionLayout
+                    ? "flex flex-col gap-2 py-2.5 pr-3.5"
+                    : cn("py-3", "flex items-center justify-between gap-1.5", inlineContentEndPad),
                   hideCollapsedContent &&
                     "not-data-expanded:pointer-events-none not-data-expanded:opacity-0",
                 )}
               >
-                <div className="flex min-w-0 flex-1 gap-2">
-                  {Icon && (
-                    <div
-                      className="[&>svg]:h-lh [&>svg]:w-4 [&_svg]:pointer-events-none [&_svg]:shrink-0"
-                      data-slot="toast-icon"
-                    >
-                      <Icon className="in-data-[type=loading]:animate-spin in-data-[type=error]:text-destructive in-data-[type=info]:text-info in-data-[type=success]:text-success in-data-[type=warning]:text-warning in-data-[type=loading]:opacity-80" />
-                    </div>
-                  )}
-
-                  <div className="flex min-w-0 flex-1 flex-col gap-0.5">
-                    <div className="flex items-center justify-between gap-1">
-                      <Toast.Title
-                        className="min-w-0 wrap-break-word font-medium"
-                        data-slot="toast-title"
-                      />
-                      {toast.type === "error" &&
-                        typeof toast.description === "string" &&
-                        !toast.data?.hideCopyButton && <CopyErrorButton text={toast.description} />}
-                    </div>
-                    <Toast.Description
-                      className="min-w-0 select-text wrap-break-word text-muted-foreground"
-                      data-slot="toast-description"
-                    />
-                  </div>
-                </div>
-                {toast.actionProps && (
-                  <Toast.Action
-                    className={cn(buttonVariants({ size: "xs" }), "shrink-0")}
-                    data-slot="toast-action"
-                  >
-                    {toast.actionProps.children}
-                  </Toast.Action>
-                )}
+                <ToastBodyContent
+                  {...bodyDescriptor}
+                  actionProps={toast.actionProps}
+                  toastData={toast.data}
+                  toastDescription={toast.description}
+                  toastType={toast.type}
+                />
               </Toast.Content>
             </Toast.Root>
           );
@@ -371,9 +684,10 @@ function AnchoredToasts() {
         {toasts
           .filter((toast) => shouldRenderThreadScopedToast(toast.data, activeThreadRef))
           .map((toast) => {
-            const Icon = toast.type ? TOAST_ICONS[toast.type as keyof typeof TOAST_ICONS] : null;
             const tooltipStyle = toast.data?.tooltipStyle ?? false;
             const positionerProps = toast.positionerProps;
+            const bodyDescriptor = deriveToastBodyDescriptor(toast);
+            const { stackedActionLayout, inlineContentEndPad } = bodyDescriptor;
 
             if (!positionerProps?.anchor) {
               return null;
@@ -389,7 +703,7 @@ function AnchoredToasts() {
               >
                 <Toast.Root
                   className={cn(
-                    "relative text-balance border bg-popover not-dark:bg-clip-padding text-popover-foreground text-xs transition-[scale,opacity] before:pointer-events-none before:absolute before:inset-0 before:shadow-[0_1px_--theme(--color-black/4%)] data-ending-style:scale-98 data-starting-style:scale-98 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+                    "relative overflow-visible text-balance border bg-popover not-dark:bg-clip-padding text-popover-foreground text-xs transition-[scale,opacity] before:pointer-events-none before:absolute before:inset-0 before:shadow-[0_1px_--theme(--color-black/4%)] data-ending-style:scale-98 data-starting-style:scale-98 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
                     tooltipStyle
                       ? "rounded-md shadow-md/5 before:rounded-[calc(var(--radius-md)-1px)]"
                       : "rounded-lg shadow-lg/5 before:rounded-[calc(var(--radius-lg)-1px)]",
@@ -402,44 +716,45 @@ function AnchoredToasts() {
                       <Toast.Title data-slot="toast-title" />
                     </Toast.Content>
                   ) : (
-                    <Toast.Content className="pointer-events-auto flex items-center justify-between gap-1.5 overflow-hidden px-3.5 py-3 text-sm">
-                      <div className="flex min-w-0 flex-1 gap-2">
-                        {Icon && (
-                          <div
-                            className="[&>svg]:h-lh [&>svg]:w-4 [&_svg]:pointer-events-none [&_svg]:shrink-0"
-                            data-slot="toast-icon"
-                          >
-                            <Icon className="in-data-[type=loading]:animate-spin in-data-[type=error]:text-destructive in-data-[type=info]:text-info in-data-[type=success]:text-success in-data-[type=warning]:text-warning in-data-[type=loading]:opacity-80" />
-                          </div>
-                        )}
-
-                        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
-                          <div className="flex items-center gap-1">
-                            <Toast.Title
-                              className="min-w-0 wrap-break-word font-medium"
-                              data-slot="toast-title"
-                            />
-                            {toast.type === "error" &&
-                              typeof toast.description === "string" &&
-                              !toast.data?.hideCopyButton && (
-                                <CopyErrorButton text={toast.description} />
-                              )}
-                          </div>
-                          <Toast.Description
-                            className="min-w-0 select-text wrap-break-word text-muted-foreground"
-                            data-slot="toast-description"
-                          />
-                        </div>
-                      </div>
-                      {toast.actionProps && (
-                        <Toast.Action
-                          className={cn(buttonVariants({ size: "xs" }), "shrink-0")}
-                          data-slot="toast-action"
+                    <>
+                      <div className={toastCornerDismissClass}>
+                        <button
+                          aria-label="Dismiss notification"
+                          className={toastCornerOrbClass}
+                          data-slot="toast-close"
+                          onClick={() =>
+                            handleToastDismissClick(
+                              anchoredToastManager,
+                              toast.id,
+                              toast.data?.onClose,
+                            )
+                          }
+                          type="button"
                         >
-                          {toast.actionProps.children}
-                        </Toast.Action>
-                      )}
-                    </Toast.Content>
+                          <XIcon className="size-3" strokeWidth={2.25} />
+                        </button>
+                      </div>
+                      <Toast.Content
+                        className={cn(
+                          "pointer-events-auto min-h-0 overflow-y-visible pl-3.5 text-sm [overflow-x:clip]",
+                          stackedActionLayout
+                            ? "flex flex-col gap-2 py-2.5 pr-3.5"
+                            : cn(
+                                "py-3",
+                                "flex items-center justify-between gap-1.5",
+                                inlineContentEndPad,
+                              ),
+                        )}
+                      >
+                        <ToastBodyContent
+                          {...bodyDescriptor}
+                          actionProps={toast.actionProps}
+                          toastData={toast.data}
+                          toastDescription={toast.description}
+                          toastType={toast.type}
+                        />
+                      </Toast.Content>
+                    </>
                   )}
                 </Toast.Root>
               </Toast.Positioner>
@@ -450,6 +765,9 @@ function AnchoredToasts() {
   );
 }
 
+export { stackedThreadToast } from "./toastHelpers";
+export type { StackedThreadToastOptions } from "./toastHelpers";
+
 export {
   ToastProvider,
   type ToastPosition,
diff --git a/apps/web/src/components/ui/toastHelpers.ts b/apps/web/src/components/ui/toastHelpers.ts
new file mode 100644
index 00000000000..4ec5d14106c
--- /dev/null
+++ b/apps/web/src/components/ui/toastHelpers.ts
@@ -0,0 +1,58 @@
+"use client";
+
+import type { ToastManagerAddOptions } from "@base-ui/react/toast";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+
+import type { ThreadToastData } from "./toast";
+
+export type StackedThreadToastOptions = {
+  type: "error" | "warning" | "success" | "info" | "loading";
+  title: ReactNode;
+  description?: ReactNode;
+  timeout?: number;
+  priority?: "low" | "high";
+  actionProps?: ComponentPropsWithoutRef<"button">;
+  /** Merged into `data`; `actionLayout` is always forced to `"stacked-end"` by the helper. */
+  actionVariant?: ThreadToastData["actionVariant"];
+  data?: Omit<ThreadToastData, "actionLayout">;
+};
+
+/**
+ * Thread toast using the stacked body + bottom action row (copy for errors, CTA on its own row).
+ */
+export function stackedThreadToast(
+  options: StackedThreadToastOptions,
+): ToastManagerAddOptions<ThreadToastData> {
+  const { type, title, description, timeout, priority, actionProps, actionVariant, data } = options;
+
+  // Helper-owned `actionLayout` must win over any caller-provided `data`, so spread
+  // the caller's data first and apply `actionLayout: "stacked-end"` last.
+  const mergedData: ThreadToastData = {
+    ...(data !== undefined ? data : {}),
+    actionLayout: "stacked-end",
+  };
+  if (actionVariant !== undefined) {
+    mergedData.actionVariant = actionVariant;
+  }
+
+  const payload: ToastManagerAddOptions<ThreadToastData> = {
+    type,
+    title,
+    data: mergedData,
+  };
+
+  if (description !== undefined) {
+    payload.description = description;
+  }
+  if (timeout !== undefined) {
+    payload.timeout = timeout;
+  }
+  if (priority !== undefined) {
+    payload.priority = priority;
+  }
+  if (actionProps !== undefined) {
+    payload.actionProps = actionProps;
+  }
+
+  return payload;
+}
diff --git a/apps/web/src/components/ui/toggle-group.tsx b/apps/web/src/components/ui/toggle-group.tsx
index 437c5ef987c..68cf007d762 100644
--- a/apps/web/src/components/ui/toggle-group.tsx
+++ b/apps/web/src/components/ui/toggle-group.tsx
@@ -43,7 +43,7 @@ function ToggleGroup({
       orientation={orientation}
       {...props}
     >
-      <ToggleGroupContext.Provider value={value}>{children}</ToggleGroupContext.Provider>
+      <ToggleGroupContext value={value}>{children}</ToggleGroupContext>
     </ToggleGroupPrimitive>
   );
 }
@@ -55,7 +55,7 @@ function Toggle({
   size,
   ...props
 }: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
-  const context = React.useContext(ToggleGroupContext);
+  const context = React.use(ToggleGroupContext);
 
   const resolvedVariant = variant ?? context.variant;
   const resolvedSize = size ?? context.size;
diff --git a/apps/web/src/composer-logic.test.ts b/apps/web/src/composer-logic.test.ts
index 1c18af54e62..eaec8b44fa2 100644
--- a/apps/web/src/composer-logic.test.ts
+++ b/apps/web/src/composer-logic.test.ts
@@ -36,18 +36,25 @@ describe("detectComposerTrigger", () => {
     });
   });
 
-  it("detects slash model query after /model", () => {
-    const text = "/model spark";
+  it("keeps /model as a slash command item", () => {
+    const text = "/model";
     const trigger = detectComposerTrigger(text, text.length);
 
     expect(trigger).toEqual({
-      kind: "slash-model",
-      query: "spark",
+      kind: "slash-command",
+      query: "model",
       rangeStart: 0,
       rangeEnd: text.length,
     });
   });
 
+  it("does not keep a subcommand trigger active after /model arguments", () => {
+    const text = "/model spark";
+    const trigger = detectComposerTrigger(text, text.length);
+
+    expect(trigger).toBeNull();
+  });
+
   it("detects non-model slash commands while typing", () => {
     const text = "/pl";
     const trigger = detectComposerTrigger(text, text.length);
diff --git a/apps/web/src/composer-logic.ts b/apps/web/src/composer-logic.ts
index a5b26b0e2de..fb63d2581c7 100644
--- a/apps/web/src/composer-logic.ts
+++ b/apps/web/src/composer-logic.ts
@@ -1,7 +1,7 @@
 import { splitPromptIntoComposerSegments } from "./composer-editor-mentions";
 import { INLINE_TERMINAL_CONTEXT_PLACEHOLDER } from "./lib/terminalContext";
 
-export type ComposerTriggerKind = "path" | "slash-command" | "slash-model" | "skill";
+export type ComposerTriggerKind = "path" | "slash-command" | "skill";
 export type ComposerSlashCommand = "model" | "plan" | "default";
 
 export interface ComposerTrigger {
@@ -224,14 +224,6 @@ export function detectComposerTrigger(text: string, cursorInput: number): Compos
     const commandMatch = /^\/(\S*)$/.exec(linePrefix);
     if (commandMatch) {
       const commandQuery = commandMatch[1] ?? "";
-      if (commandQuery.toLowerCase() === "model") {
-        return {
-          kind: "slash-model",
-          query: "",
-          rangeStart: lineStart,
-          rangeEnd: cursor,
-        };
-      }
       return {
         kind: "slash-command",
         query: commandQuery,
@@ -239,16 +231,6 @@ export function detectComposerTrigger(text: string, cursorInput: number): Compos
         rangeEnd: cursor,
       };
     }
-
-    const modelMatch = /^\/model(?:\s+(.*))?$/.exec(linePrefix);
-    if (modelMatch) {
-      return {
-        kind: "slash-model",
-        query: (modelMatch[1] ?? "").trim(),
-        rangeStart: lineStart,
-        rangeEnd: cursor,
-      };
-    }
   }
 
   const tokenStart = tokenStartForCursor(text, cursor);
diff --git a/apps/web/src/composerDraftStore.test.ts b/apps/web/src/composerDraftStore.test.ts
index 2169bbf8584..67f754bd715 100644
--- a/apps/web/src/composerDraftStore.test.ts
+++ b/apps/web/src/composerDraftStore.test.ts
@@ -6,12 +6,54 @@ import {
 } from "@t3tools/client-runtime";
 import * as Schema from "effect/Schema";
 import {
+  defaultInstanceIdForDriver,
   EnvironmentId,
   ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ThreadId,
   type ModelSelection,
-  type ProviderModelOptions,
+  type ProviderOptionSelection,
 } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
+
+// The composer draft's `modelSelectionByProvider` and
+// `stickyModelSelectionByProvider` maps are keyed by `ProviderInstanceId`
+// in production; these aliases keep the legacy-key migration tests concise.
+const CODEX_INSTANCE = ProviderInstanceId.make("codex");
+const CLAUDE_AGENT_INSTANCE = ProviderInstanceId.make("claudeAgent");
+const CURSOR_INSTANCE = ProviderInstanceId.make("cursor");
+const CODEX_DRIVER = ProviderDriverKind.make("codex");
+const CLAUDE_AGENT_DRIVER = ProviderDriverKind.make("claudeAgent");
+const CURSOR_DRIVER = ProviderDriverKind.make("cursor");
+
+type ProviderOptionSelectionBag = ReadonlyArray<ProviderOptionSelection>;
+type ProviderOptionSelectionsByProvider = Partial<Record<string, ProviderOptionSelectionBag>>;
+
+function toSelections(
+  options: Record<string, string | boolean | undefined> | undefined,
+): ReadonlyArray<ProviderOptionSelection> {
+  const result: Array<ProviderOptionSelection> = [];
+  if (!options) return result;
+  for (const [id, value] of Object.entries(options)) {
+    if (typeof value === "string" || typeof value === "boolean") {
+      result.push({ id, value });
+    }
+  }
+  return result;
+}
+
+function selectionsByProvider(
+  options: Partial<Record<ProviderDriverKind, Record<string, string | boolean | undefined>>>,
+): ProviderOptionSelectionsByProvider {
+  const result: ProviderOptionSelectionsByProvider = {};
+  for (const [provider, bag] of Object.entries(options) as Array<
+    [ProviderDriverKind, Record<string, string | boolean | undefined>]
+  >) {
+    result[provider] = toSelections(bag);
+  }
+  return result;
+}
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
@@ -91,19 +133,17 @@ function resetComposerDraftStore() {
 }
 
 function modelSelection(
-  provider: "codex" | "claudeAgent",
+  provider: ProviderDriverKind,
   model: string,
-  options?: ModelSelection["options"],
+  options?: Record<string, string | boolean | undefined>,
 ): ModelSelection {
-  return {
-    provider,
-    model,
-    ...(options ? { options } : {}),
-  } as ModelSelection;
+  return createModelSelection(defaultInstanceIdForDriver(provider), model, toSelections(options));
 }
 
-function providerModelOptions(options: ProviderModelOptions): ProviderModelOptions {
-  return options;
+function providerModelOptions(
+  options: Partial<Record<string, Record<string, string | boolean | undefined>>>,
+): ProviderOptionSelectionsByProvider {
+  return selectionsByProvider(options);
 }
 
 const TEST_ENVIRONMENT_ID = EnvironmentId.make("environment-local");
@@ -561,6 +601,49 @@ describe("composerDraftStore project draft thread mapping", () => {
     expect(draftByKey(draftId)).toBeUndefined();
   });
 
+  it("revokes draft image blob URLs when clearing a project's draft thread", () => {
+    const store = useComposerDraftStore.getState();
+    const originalRevokeObjectUrl = URL.revokeObjectURL;
+    const revokeSpy = vi.fn<(url: string) => void>();
+    URL.revokeObjectURL = revokeSpy;
+
+    try {
+      store.setProjectDraftThreadId(projectRef, draftId, { threadId });
+      store.addImage(draftId, makeImage({ id: "img-project-clear", previewUrl: "blob:clear" }));
+
+      store.clearProjectDraftThreadId(projectRef);
+
+      expect(useComposerDraftStore.getState().getDraftThreadByProjectRef(projectRef)).toBeNull();
+      expect(useComposerDraftStore.getState().getDraftThread(draftId)).toBeNull();
+      expect(revokeSpy).toHaveBeenCalledWith("blob:clear");
+    } finally {
+      URL.revokeObjectURL = originalRevokeObjectUrl;
+    }
+  });
+
+  it("revokes draft image blob URLs when clearing a matching project draft thread by id", () => {
+    const store = useComposerDraftStore.getState();
+    const originalRevokeObjectUrl = URL.revokeObjectURL;
+    const revokeSpy = vi.fn<(url: string) => void>();
+    URL.revokeObjectURL = revokeSpy;
+
+    try {
+      store.setProjectDraftThreadId(projectRef, draftId, { threadId });
+      store.addImage(
+        draftId,
+        makeImage({ id: "img-project-clear-by-id", previewUrl: "blob:clear-by-id" }),
+      );
+
+      store.clearProjectDraftThreadById(projectRef, draftId);
+
+      expect(useComposerDraftStore.getState().getDraftThreadByProjectRef(projectRef)).toBeNull();
+      expect(useComposerDraftStore.getState().getDraftThread(draftId)).toBeNull();
+      expect(revokeSpy).toHaveBeenCalledWith("blob:clear-by-id");
+    } finally {
+      URL.revokeObjectURL = originalRevokeObjectUrl;
+    }
+  });
+
   it("clears orphaned composer drafts when remapping a project to a new draft thread", () => {
     const store = useComposerDraftStore.getState();
     store.setProjectDraftThreadId(projectRef, draftId, { threadId });
@@ -858,14 +941,16 @@ describe("composerDraftStore modelSelection", () => {
     const store = useComposerDraftStore.getState();
     store.setModelSelection(
       threadRef,
-      modelSelection("codex", "gpt-5.3-codex", {
+      modelSelection(CODEX_DRIVER, "gpt-5.3-codex", {
         reasoningEffort: "xhigh",
         fastMode: true,
       }),
     );
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.3-codex", {
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CODEX_INSTANCE],
+    ).toEqual(
+      modelSelection(CODEX_DRIVER, "gpt-5.3-codex", {
         reasoningEffort: "xhigh",
         fastMode: true,
       }),
@@ -874,11 +959,11 @@ describe("composerDraftStore modelSelection", () => {
 
   it("keeps default-only model selections on the draft", () => {
     const store = useComposerDraftStore.getState();
-    store.setModelSelection(threadRef, modelSelection("codex", "gpt-5.4"));
+    store.setModelSelection(threadRef, modelSelection(CODEX_DRIVER, "gpt-5.4"));
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.4"),
-    );
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CODEX_INSTANCE],
+    ).toEqual(modelSelection(CODEX_DRIVER, "gpt-5.4"));
   });
 
   it("replaces only the targeted provider options on the current model selection", () => {
@@ -886,13 +971,13 @@ describe("composerDraftStore modelSelection", () => {
 
     store.setModelSelection(
       threadRef,
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         effort: "max",
         fastMode: true,
       }),
     );
     store.setStickyModelSelection(
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         effort: "max",
         fastMode: true,
       }),
@@ -900,20 +985,24 @@ describe("composerDraftStore modelSelection", () => {
 
     store.setProviderModelOptions(
       threadRef,
-      "claudeAgent",
+      CLAUDE_AGENT_DRIVER,
+      toSelections({ thinking: false }),
       {
-        thinking: false,
+        persistSticky: true,
       },
-      { persistSticky: true },
     );
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CLAUDE_AGENT_INSTANCE],
+    ).toEqual(
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         thinking: false,
       }),
     );
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CLAUDE_AGENT_INSTANCE],
+    ).toEqual(
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         thinking: false,
       }),
     );
@@ -924,17 +1013,17 @@ describe("composerDraftStore modelSelection", () => {
 
     store.setModelSelection(
       threadRef,
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         effort: "max",
       }),
     );
 
-    store.setProviderModelOptions(threadRef, "claudeAgent", {
-      thinking: true,
-    });
+    store.setProviderModelOptions(threadRef, CLAUDE_AGENT_DRIVER, toSelections({ thinking: true }));
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CLAUDE_AGENT_INSTANCE],
+    ).toEqual(
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         thinking: true,
       }),
     );
@@ -944,44 +1033,104 @@ describe("composerDraftStore modelSelection", () => {
   it("keeps explicit off/default codex overrides on the selection", () => {
     const store = useComposerDraftStore.getState();
 
-    store.setModelSelection(threadRef, modelSelection("codex", "gpt-5.4", { fastMode: true }));
+    store.setModelSelection(threadRef, modelSelection(CODEX_DRIVER, "gpt-5.4", { fastMode: true }));
 
-    store.setProviderModelOptions(threadRef, "codex", {
-      reasoningEffort: "high",
-      fastMode: false,
-    });
+    store.setProviderModelOptions(
+      threadRef,
+      CODEX_DRIVER,
+      toSelections({ reasoningEffort: "high", fastMode: false }),
+    );
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.4", {
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CODEX_INSTANCE],
+    ).toEqual(
+      modelSelection(CODEX_DRIVER, "gpt-5.4", {
         reasoningEffort: "high",
         fastMode: false,
       }),
     );
   });
 
+  it("keeps explicit Cursor reset overrides on the selection", () => {
+    const store = useComposerDraftStore.getState();
+
+    store.setModelSelection(
+      threadRef,
+      modelSelection(CURSOR_DRIVER, "claude-opus-4-6", {
+        reasoning: "xhigh",
+        fastMode: true,
+        thinking: false,
+      }),
+    );
+
+    store.setProviderModelOptions(
+      threadRef,
+      CURSOR_DRIVER,
+      toSelections({ reasoning: "medium", fastMode: false, thinking: true }),
+    );
+
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(
+      modelSelection(CURSOR_DRIVER, "claude-opus-4-6", {
+        reasoning: "medium",
+        fastMode: false,
+        thinking: true,
+      }),
+    );
+  });
+
+  it("preserves the selected Cursor model when only traits change", () => {
+    const store = useComposerDraftStore.getState();
+
+    store.setProviderModelOptions(threadRef, CURSOR_DRIVER, toSelections({ reasoning: "high" }), {
+      model: "gpt-5.4",
+      persistSticky: true,
+    });
+
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(
+      modelSelection(CURSOR_DRIVER, "gpt-5.4", {
+        reasoning: "high",
+      }),
+    );
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(
+      modelSelection(CURSOR_DRIVER, "gpt-5.4", {
+        reasoning: "high",
+      }),
+    );
+  });
+
   it("updates only the draft when sticky persistence is omitted", () => {
     const store = useComposerDraftStore.getState();
 
     store.setStickyModelSelection(
-      modelSelection("claudeAgent", "claude-opus-4-6", { effort: "max" }),
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", { effort: "max" }),
     );
     store.setModelSelection(
       threadRef,
-      modelSelection("claudeAgent", "claude-opus-4-6", { effort: "max" }),
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", { effort: "max" }),
     );
 
-    store.setProviderModelOptions(threadRef, "claudeAgent", {
-      thinking: false,
-    });
+    store.setProviderModelOptions(
+      threadRef,
+      CLAUDE_AGENT_DRIVER,
+      toSelections({ thinking: false }),
+    );
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CLAUDE_AGENT_INSTANCE],
+    ).toEqual(
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         thinking: false,
       }),
     );
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", { effort: "max" }),
-    );
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CLAUDE_AGENT_INSTANCE],
+    ).toEqual(modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", { effort: "max" }));
   });
 
   it("does not clear other provider options when setting options for a single provider", () => {
@@ -1000,8 +1149,17 @@ describe("composerDraftStore modelSelection", () => {
     store.setModelOptions(threadRef, providerModelOptions({ codex: { reasoningEffort: "xhigh" } }));
 
     const draft = draftFor(threadId, TEST_ENVIRONMENT_ID);
-    expect(draft?.modelSelectionByProvider.codex?.options).toEqual({ reasoningEffort: "xhigh" });
-    expect(draft?.modelSelectionByProvider.claudeAgent?.options).toEqual({ effort: "max" });
+    expect(draft?.modelSelectionByProvider[CODEX_INSTANCE]?.options).toEqual(
+      createModelSelection(CODEX_INSTANCE, "gpt-5.4", toSelections({ reasoningEffort: "xhigh" }))
+        .options,
+    );
+    expect(draft?.modelSelectionByProvider[CLAUDE_AGENT_INSTANCE]?.options).toEqual(
+      createModelSelection(
+        CLAUDE_AGENT_INSTANCE,
+        "claude-opus-4-6",
+        toSelections({ effort: "max" }),
+      ).options,
+    );
   });
 
   it("preserves other provider options when switching the active model selection", () => {
@@ -1015,32 +1173,29 @@ describe("composerDraftStore modelSelection", () => {
       }),
     );
 
-    store.setModelSelection(threadRef, modelSelection("claudeAgent", "claude-opus-4-6"));
+    store.setModelSelection(threadRef, modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6"));
 
     const draft = draftFor(threadId, TEST_ENVIRONMENT_ID);
-    expect(draft?.modelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", { effort: "max" }),
+    expect(draft?.modelSelectionByProvider[CLAUDE_AGENT_INSTANCE]).toEqual(
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", { effort: "max" }),
+    );
+    expect(draft?.modelSelectionByProvider[CODEX_INSTANCE]?.options).toEqual(
+      createModelSelection(CODEX_INSTANCE, "gpt-5.4", toSelections({ fastMode: true })).options,
     );
-    expect(draft?.modelSelectionByProvider.codex?.options).toEqual({ fastMode: true });
     expect(draft?.activeProvider).toBe("claudeAgent");
   });
 
   it("creates the first sticky snapshot from provider option changes", () => {
     const store = useComposerDraftStore.getState();
 
-    store.setModelSelection(threadRef, modelSelection("codex", "gpt-5.4"));
+    store.setModelSelection(threadRef, modelSelection(CODEX_DRIVER, "gpt-5.4"));
 
-    store.setProviderModelOptions(
-      threadRef,
-      "codex",
-      {
-        fastMode: true,
-      },
-      { persistSticky: true },
-    );
+    store.setProviderModelOptions(threadRef, CODEX_DRIVER, toSelections({ fastMode: true }), {
+      persistSticky: true,
+    });
 
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.4", {
+    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider[CODEX_INSTANCE]).toEqual(
+      modelSelection(CODEX_DRIVER, "gpt-5.4", {
         fastMode: true,
       }),
     );
@@ -1050,30 +1205,32 @@ describe("composerDraftStore modelSelection", () => {
     const store = useComposerDraftStore.getState();
 
     store.setStickyModelSelection(
-      modelSelection("claudeAgent", "claude-opus-4-6", { effort: "max" }),
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", { effort: "max" }),
     );
     store.setModelSelection(
       threadRef,
-      modelSelection("claudeAgent", "claude-opus-4-6", { effort: "max" }),
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", { effort: "max" }),
     );
 
     store.setProviderModelOptions(
       threadRef,
-      "claudeAgent",
+      CLAUDE_AGENT_DRIVER,
+      toSelections({ thinking: false }),
       {
-        thinking: false,
+        persistSticky: false,
       },
-      { persistSticky: false },
     );
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", {
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CLAUDE_AGENT_INSTANCE],
+    ).toEqual(
+      modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", {
         thinking: false,
       }),
     );
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.claudeAgent).toEqual(
-      modelSelection("claudeAgent", "claude-opus-4-6", { effort: "max" }),
-    );
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CLAUDE_AGENT_INSTANCE],
+    ).toEqual(modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6", { effort: "max" }));
   });
 });
 
@@ -1088,11 +1245,11 @@ describe("composerDraftStore setModelSelection", () => {
   it("keeps explicit model overrides instead of coercing to null", () => {
     const store = useComposerDraftStore.getState();
 
-    store.setModelSelection(threadRef, modelSelection("codex", "gpt-5.3-codex"));
+    store.setModelSelection(threadRef, modelSelection(CODEX_DRIVER, "gpt-5.3-codex"));
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.3-codex"),
-    );
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CODEX_INSTANCE],
+    ).toEqual(modelSelection(CODEX_DRIVER, "gpt-5.3-codex"));
   });
 });
 
@@ -1105,14 +1262,14 @@ describe("composerDraftStore sticky composer settings", () => {
     const store = useComposerDraftStore.getState();
 
     store.setStickyModelSelection(
-      modelSelection("codex", "gpt-5.3-codex", {
+      modelSelection(CODEX_DRIVER, "gpt-5.3-codex", {
         reasoningEffort: "medium",
         fastMode: true,
       }),
     );
 
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.3-codex", {
+    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider[CODEX_INSTANCE]).toEqual(
+      modelSelection(CODEX_DRIVER, "gpt-5.3-codex", {
         reasoningEffort: "medium",
         fastMode: true,
       }),
@@ -1123,25 +1280,43 @@ describe("composerDraftStore sticky composer settings", () => {
   it("normalizes empty sticky model options by dropping selection options", () => {
     const store = useComposerDraftStore.getState();
 
-    store.setStickyModelSelection(modelSelection("codex", "gpt-5.4"));
+    store.setStickyModelSelection(modelSelection(CODEX_DRIVER, "gpt-5.4"));
 
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.4"),
+    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider[CODEX_INSTANCE]).toEqual(
+      modelSelection(CODEX_DRIVER, "gpt-5.4"),
     );
     expect(useComposerDraftStore.getState().stickyActiveProvider).toBe("codex");
   });
 
+  it("drops empty cursor model options when normalizing sticky state", () => {
+    const store = useComposerDraftStore.getState();
+
+    store.setStickyModelSelection(
+      modelSelection(CURSOR_DRIVER, "gpt-5.4", {
+        reasoning: undefined,
+        fastMode: undefined,
+        thinking: undefined,
+        contextWindow: undefined,
+      }),
+    );
+
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(modelSelection(CURSOR_DRIVER, "gpt-5.4"));
+    expect(useComposerDraftStore.getState().stickyActiveProvider).toBe("cursor");
+  });
+
   it("applies sticky activeProvider to new drafts", () => {
     const store = useComposerDraftStore.getState();
     const threadId = ThreadId.make("thread-sticky-active-provider");
     const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
 
-    store.setStickyModelSelection(modelSelection("claudeAgent", "claude-opus-4-6"));
+    store.setStickyModelSelection(modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6"));
     store.applyStickyState(threadRef);
 
     expect(draftFor(threadId, TEST_ENVIRONMENT_ID)).toMatchObject({
       modelSelectionByProvider: {
-        claudeAgent: modelSelection("claudeAgent", "claude-opus-4-6"),
+        claudeAgent: modelSelection(CLAUDE_AGENT_DRIVER, "claude-opus-4-6"),
       },
       activeProvider: "claudeAgent",
     });
@@ -1160,16 +1335,22 @@ describe("composerDraftStore provider-scoped option updates", () => {
     const store = useComposerDraftStore.getState();
     store.setModelSelection(
       threadRef,
-      modelSelection("codex", "gpt-5.3-codex", {
+      modelSelection(CODEX_DRIVER, "gpt-5.3-codex", {
         reasoningEffort: "medium",
       }),
     );
-    store.setProviderModelOptions(threadRef, "claudeAgent", { effort: "max" });
+    store.setProviderModelOptions(threadRef, CLAUDE_AGENT_DRIVER, toSelections({ effort: "max" }));
     const draft = draftFor(threadId, TEST_ENVIRONMENT_ID);
-    expect(draft?.modelSelectionByProvider.codex).toEqual(
-      modelSelection("codex", "gpt-5.3-codex", { reasoningEffort: "medium" }),
+    expect(draft?.modelSelectionByProvider[CODEX_INSTANCE]).toEqual(
+      modelSelection(CODEX_DRIVER, "gpt-5.3-codex", { reasoningEffort: "medium" }),
+    );
+    expect(draft?.modelSelectionByProvider[CLAUDE_AGENT_INSTANCE]?.options).toEqual(
+      createModelSelection(
+        CLAUDE_AGENT_INSTANCE,
+        "claude-opus-4-6",
+        toSelections({ effort: "max" }),
+      ).options,
     );
-    expect(draft?.modelSelectionByProvider.claudeAgent?.options).toEqual({ effort: "max" });
     expect(draft?.activeProvider).toBe("codex");
   });
 });
diff --git a/apps/web/src/composerDraftStore.ts b/apps/web/src/composerDraftStore.ts
index 231cf06566e..d554ad7b0d3 100644
--- a/apps/web/src/composerDraftStore.ts
+++ b/apps/web/src/composerDraftStore.ts
@@ -1,14 +1,14 @@
 import {
-  CODEX_REASONING_EFFORT_OPTIONS,
-  type ClaudeCodeEffort,
-  type CodexReasoningEffort,
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
+  defaultInstanceIdForDriver,
   type EnvironmentId,
   ModelSelection,
   ProjectId,
+  ProviderInstanceId,
   ProviderInteractionMode,
-  ProviderKind,
-  ProviderModelOptions,
+  ProviderDriverKind,
+  ProviderOptionSelection,
   RuntimeMode,
   type ServerProvider,
   type ScopedProjectRef,
@@ -26,10 +26,10 @@ import {
 import * as Schema from "effect/Schema";
 import * as Equal from "effect/Equal";
 import { DeepMutable } from "effect/Types";
-import { normalizeModelSlug } from "@t3tools/shared/model";
+import { createModelSelection, normalizeModelSlug } from "@t3tools/shared/model";
 import { useMemo } from "react";
 import { getLocalStorageItem } from "./hooks/useLocalStorage";
-import { resolveAppModelSelection } from "./modelSelection";
+import { resolveAppModelSelection, resolveAppModelSelectionForInstance } from "./modelSelection";
 import { DEFAULT_INTERACTION_MODE, DEFAULT_RUNTIME_MODE, type ChatImageAttachment } from "./types";
 import {
   type TerminalContextDraft,
@@ -42,11 +42,12 @@ import { useShallow } from "zustand/react/shallow";
 import { createDebouncedStorage, createMemoryStorage } from "./lib/storage";
 import { getDefaultServerModel } from "./providerModels";
 import { UnifiedSettings } from "@t3tools/contracts/settings";
+const isRuntimeMode = Schema.is(RuntimeMode);
+const isProviderDriverKind = Schema.is(ProviderDriverKind);
 
 export const COMPOSER_DRAFT_STORAGE_KEY = "t3code:composer-drafts:v1";
-const COMPOSER_DRAFT_STORAGE_VERSION = 5;
+const COMPOSER_DRAFT_STORAGE_VERSION = 6;
 const DraftThreadEnvModeSchema = Schema.Literals(["local", "worktree"]);
-const isRuntimeMode = Schema.is(RuntimeMode);
 export type DraftThreadEnvMode = typeof DraftThreadEnvModeSchema.Type;
 
 export const DraftId = Schema.String.pipe(Schema.brand("DraftId"));
@@ -95,32 +96,48 @@ const PersistedComposerThreadDraftState = Schema.Struct({
   prompt: Schema.String,
   attachments: Schema.Array(PersistedComposerImageAttachment),
   terminalContexts: Schema.optionalKey(Schema.Array(PersistedTerminalContextDraft)),
-  modelSelectionByProvider: Schema.optionalKey(
-    Schema.Record(ProviderKind, Schema.optionalKey(ModelSelection)),
-  ),
-  activeProvider: Schema.optionalKey(Schema.NullOr(ProviderKind)),
+  // Keyed by `ProviderInstanceId` (open branded slug) so custom provider
+  // instances (e.g. `codex_personal`) round-trip alongside the built-in
+  // `codex` / `claudeAgent` / ... entries. Every prior `ProviderDriverKind`
+  // literal satisfies the `ProviderInstanceId` slug pattern, so existing
+  // persisted drafts decode unchanged.
+  //
+  // The record's value schema is NOT wrapped in `Schema.optionalKey`:
+  // that helper is only meaningful on property signatures with a known
+  // key set, and `Schema.Record(<branded string>, …)` produces an index
+  // signature at runtime (Schema rejects the combination). Absence of
+  // an entry already encodes "no selection for this instance".
+  modelSelectionByProvider: Schema.optionalKey(Schema.Record(ProviderInstanceId, ModelSelection)),
+  activeProvider: Schema.optionalKey(Schema.NullOr(ProviderInstanceId)),
   runtimeMode: Schema.optionalKey(RuntimeMode),
   interactionMode: Schema.optionalKey(ProviderInteractionMode),
 });
 type PersistedComposerThreadDraftState = typeof PersistedComposerThreadDraftState.Type;
 
-const LegacyCodexFields = Schema.Struct({
-  effort: Schema.optionalKey(Schema.Literals(CODEX_REASONING_EFFORT_OPTIONS)),
-  codexFastMode: Schema.optionalKey(Schema.Boolean),
-  serviceTier: Schema.optionalKey(Schema.String),
-});
-type LegacyCodexFields = typeof LegacyCodexFields.Type;
+/**
+ * Per-provider record of generic option selections. Used as a transient
+ * representation when migrating legacy v2 storage payloads and when
+ * deriving per-provider option bundles for downstream consumers.
+ */
+type ProviderOptionSelectionsByProvider = Partial<
+  Record<string, ReadonlyArray<ProviderOptionSelection>>
+>;
 
-const LegacyThreadModelFields = Schema.Struct({
-  provider: Schema.optionalKey(ProviderKind),
-  model: Schema.optionalKey(Schema.String),
-  modelOptions: Schema.optionalKey(Schema.NullOr(ProviderModelOptions)),
-});
-type LegacyThreadModelFields = typeof LegacyThreadModelFields.Type;
+type LegacyCodexFields = {
+  effort?: unknown;
+  codexFastMode?: unknown;
+  serviceTier?: unknown;
+};
+
+type LegacyThreadModelFields = {
+  provider?: unknown;
+  model?: unknown;
+  modelOptions?: unknown;
+};
 
 type LegacyV2ThreadDraftFields = {
   modelSelection?: ModelSelection | null;
-  modelOptions?: ProviderModelOptions | null;
+  modelOptions?: unknown;
 };
 
 type LegacyPersistedComposerThreadDraftState = PersistedComposerThreadDraftState &
@@ -128,16 +145,15 @@ type LegacyPersistedComposerThreadDraftState = PersistedComposerThreadDraftState
   LegacyThreadModelFields &
   LegacyV2ThreadDraftFields;
 
-const LegacyStickyModelFields = Schema.Struct({
-  stickyProvider: Schema.optionalKey(ProviderKind),
-  stickyModel: Schema.optionalKey(Schema.String),
-  stickyModelOptions: Schema.optionalKey(Schema.NullOr(ProviderModelOptions)),
-});
-type LegacyStickyModelFields = typeof LegacyStickyModelFields.Type;
+type LegacyStickyModelFields = {
+  stickyProvider?: unknown;
+  stickyModel?: unknown;
+  stickyModelOptions?: unknown;
+};
 
 type LegacyV2StoreFields = {
   stickyModelSelection?: ModelSelection | null;
-  stickyModelOptions?: ProviderModelOptions | null;
+  stickyModelOptions?: unknown;
   projectDraftThreadIdByProjectId?: Record<string, string> | null;
   draftsByThreadId?: Record<string, PersistedComposerThreadDraftState> | null;
   draftThreadsByThreadId?: Record<string, PersistedDraftThreadState> | null;
@@ -179,9 +195,9 @@ const PersistedComposerDraftStoreState = Schema.Struct({
   draftThreadsByThreadKey: Schema.Record(Schema.String, PersistedDraftThreadState),
   logicalProjectDraftThreadKeyByLogicalProjectKey: Schema.Record(Schema.String, Schema.String),
   stickyModelSelectionByProvider: Schema.optionalKey(
-    Schema.Record(ProviderKind, Schema.optionalKey(ModelSelection)),
+    Schema.Record(ProviderInstanceId, ModelSelection),
   ),
-  stickyActiveProvider: Schema.optionalKey(Schema.NullOr(ProviderKind)),
+  stickyActiveProvider: Schema.optionalKey(Schema.NullOr(ProviderInstanceId)),
 });
 type PersistedComposerDraftStoreState = typeof PersistedComposerDraftStoreState.Type;
 
@@ -200,8 +216,17 @@ export interface ComposerThreadDraftState {
   nonPersistedImageIds: string[];
   persistedAttachments: PersistedComposerImageAttachment[];
   terminalContexts: TerminalContextDraft[];
-  modelSelectionByProvider: Partial<Record<ProviderKind, ModelSelection>>;
-  activeProvider: ProviderKind | null;
+  /**
+   * Per-instance model selection. Keyed by `ProviderInstanceId` (open
+   * branded slug) so a default `codex` instance and a user-authored
+   * `codex_personal` instance each persist their own selected model. Every
+   * historical `ProviderDriverKind` literal (`codex` / `claudeAgent` / `cursor` /
+   * `opencode`) also satisfies the `ProviderInstanceId` slug pattern, so
+   * legacy kind-keyed drafts round-trip unchanged.
+   */
+  modelSelectionByProvider: Partial<Record<ProviderInstanceId, ModelSelection>>;
+  /** Routing key of the last picked instance (see `modelSelectionByProvider`). */
+  activeProvider: ProviderInstanceId | null;
   runtimeMode: RuntimeMode | null;
   interactionMode: ProviderInteractionMode | null;
 }
@@ -256,8 +281,8 @@ interface ComposerDraftStoreState {
   draftsByThreadKey: Record<string, ComposerThreadDraftState>;
   draftThreadsByThreadKey: Record<string, DraftThreadState>;
   logicalProjectDraftThreadKeyByLogicalProjectKey: Record<string, string>;
-  stickyModelSelectionByProvider: Partial<Record<ProviderKind, ModelSelection>>;
-  stickyActiveProvider: ProviderKind | null;
+  stickyModelSelectionByProvider: Partial<Record<ProviderInstanceId, ModelSelection>>;
+  stickyActiveProvider: ProviderInstanceId | null;
   /** Returns the editable composer content for a draft session or server thread. */
   getComposerDraft: (target: ComposerThreadTarget) => ComposerThreadDraftState | null;
   /** Looks up the active draft session for a logical project identity. */
@@ -332,16 +357,21 @@ interface ComposerDraftStoreState {
     threadRef: ComposerThreadTarget,
     modelSelection: ModelSelection | null | undefined,
   ) => void;
+  /** Replace the model options for one or more providers in the draft. */
   setModelOptions: (
     threadRef: ComposerThreadTarget,
-    modelOptions: ProviderModelOptions | null | undefined,
+    modelOptions:
+      | Partial<Record<string, ReadonlyArray<ProviderOptionSelection>>>
+      | null
+      | undefined,
   ) => void;
   applyStickyState: (threadRef: ComposerThreadTarget) => void;
   setProviderModelOptions: (
     threadRef: ComposerThreadTarget,
-    provider: ProviderKind,
-    nextProviderOptions: ProviderModelOptions[ProviderKind] | null | undefined,
+    provider: ProviderDriverKind,
+    nextProviderOptions: ReadonlyArray<ProviderOptionSelection> | null | undefined,
     options?: {
+      model?: string | null | undefined;
       persistSticky?: boolean;
     },
   ) => void;
@@ -376,37 +406,55 @@ interface ComposerDraftStoreState {
 
 export interface EffectiveComposerModelState {
   selectedModel: string;
-  modelOptions: ProviderModelOptions | null;
+  modelOptions: ProviderOptionSelectionsByProvider | null;
 }
 
 interface ComposerDraftModelState {
-  activeProvider: ProviderKind | null;
-  modelSelectionByProvider: Partial<Record<ProviderKind, ModelSelection>>;
+  activeProvider: ProviderInstanceId | null;
+  modelSelectionByProvider: Partial<Record<ProviderInstanceId, ModelSelection>>;
 }
 
-function providerModelOptionsFromSelection(
+function providerSelectionsFromModelSelection(
   modelSelection: ModelSelection | null | undefined,
-): ProviderModelOptions | null {
-  if (!modelSelection?.options) {
+): ProviderOptionSelectionsByProvider | null {
+  if (!modelSelection) {
     return null;
   }
-
-  return {
-    [modelSelection.provider]: modelSelection.options,
-  };
+  const options = modelSelection.options;
+  if (!options || options.length === 0) {
+    return null;
+  }
+  return { [modelSelection.instanceId]: options };
 }
 
 function modelSelectionByProviderToOptions(
-  map: Partial<Record<ProviderKind, ModelSelection>> | null | undefined,
-): ProviderModelOptions | null {
+  map: Partial<Record<string, ModelSelection>> | null | undefined,
+): ProviderOptionSelectionsByProvider | null {
   if (!map) return null;
-  const result: Record<string, unknown> = {};
+  const result: ProviderOptionSelectionsByProvider = {};
   for (const [provider, selection] of Object.entries(map)) {
-    if (selection?.options) {
+    if (selection?.options && selection.options.length > 0) {
       result[provider] = selection.options;
     }
   }
-  return Object.keys(result).length > 0 ? (result as ProviderModelOptions) : null;
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+function cloneModelSelection(selection: ModelSelection): DeepMutable<ModelSelection> {
+  return {
+    ...selection,
+    ...(selection.options ? { options: selection.options.map((option) => ({ ...option })) } : {}),
+  } as DeepMutable<ModelSelection>;
+}
+
+function compactModelSelectionByProvider(
+  selections: Partial<Record<ProviderInstanceId, ModelSelection>>,
+): DeepMutable<Record<ProviderInstanceId, ModelSelection>> {
+  return Object.fromEntries(
+    Object.entries(selections)
+      .filter((entry): entry is [string, ModelSelection] => entry[1] !== undefined)
+      .map(([provider, selection]) => [provider, cloneModelSelection(selection)]),
+  ) as DeepMutable<Record<ProviderInstanceId, ModelSelection>>;
 }
 
 const EMPTY_PERSISTED_DRAFT_STORE_STATE = Object.freeze<PersistedComposerDraftStoreState>({
@@ -424,7 +472,7 @@ const EMPTY_TERMINAL_CONTEXTS: TerminalContextDraft[] = [];
 Object.freeze(EMPTY_IMAGES);
 Object.freeze(EMPTY_IDS);
 Object.freeze(EMPTY_PERSISTED_ATTACHMENTS);
-const EMPTY_MODEL_SELECTION_BY_PROVIDER: Partial<Record<ProviderKind, ModelSelection>> =
+const EMPTY_MODEL_SELECTION_BY_PROVIDER: Partial<Record<ProviderDriverKind, ModelSelection>> =
   Object.freeze({});
 const EMPTY_COMPOSER_DRAFT_MODEL_STATE = Object.freeze<ComposerDraftModelState>({
   activeProvider: null,
@@ -527,101 +575,125 @@ function shouldRemoveDraft(draft: ComposerThreadDraftState): boolean {
   );
 }
 
-function normalizeProviderKind(value: unknown): ProviderKind | null {
-  return value === "codex" || value === "claudeAgent" ? value : null;
+function normalizeProviderDriverKind(value: unknown): ProviderDriverKind | null {
+  return isProviderDriverKind(value) ? value : null;
+}
+
+/**
+ * Match the `ProviderInstanceId` slug pattern (letter followed by
+ * letters/digits/`-`/`_`, 1..64 chars). Permissive validator — the schema
+ * layer owns authoritative validation; this is used inline to gate typed
+ * writes to the draft's instance-keyed maps without pulling the full
+ * Effect Schema runtime into the hot path.
+ */
+const PROVIDER_INSTANCE_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+
+/**
+ * Coerce an arbitrary persisted value into a valid `ProviderInstanceId`. Used
+ * wherever we need to accept both legacy driver-kind keys and custom instance
+ * slugs (e.g. `codex_personal`) as routing keys.
+ */
+function normalizeProviderInstanceId(value: unknown): ProviderInstanceId | null {
+  if (typeof value !== "string") return null;
+  if (!PROVIDER_INSTANCE_ID_PATTERN.test(value)) return null;
+  return value as ProviderInstanceId;
+}
+
+/**
+ * Coerce an unknown value into a `ReadonlyArray<ProviderOptionSelection>`.
+ * Accepts either:
+ *   - the v3 representation: an array of `{ id, value }` entries
+ *   - the legacy v2 representation: a record of `{ id: string | boolean }`
+ *
+ * Validation is intentionally permissive: descriptors are the source of truth
+ * for which option ids are meaningful for a given provider/model. Anything
+ * outside the descriptor list is harmless trailing data and will simply be
+ * ignored downstream.
+ */
+function coerceProviderOptionSelections(
+  value: unknown,
+): ReadonlyArray<ProviderOptionSelection> | undefined {
+  if (Array.isArray(value)) {
+    const out: ProviderOptionSelection[] = [];
+    for (const entry of value) {
+      if (!entry || typeof entry !== "object") continue;
+      const record = entry as Record<string, unknown>;
+      const id = record.id;
+      const optionValue = record.value;
+      if (typeof id !== "string" || id.length === 0) continue;
+      if (typeof optionValue === "string" || typeof optionValue === "boolean") {
+        out.push({ id, value: optionValue });
+      }
+    }
+    return out.length > 0 ? out : undefined;
+  }
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const out: ProviderOptionSelection[] = [];
+    for (const [id, raw] of Object.entries(record)) {
+      if (typeof raw === "string" || typeof raw === "boolean") {
+        out.push({ id, value: raw });
+      }
+    }
+    return out.length > 0 ? out : undefined;
+  }
+  return undefined;
 }
 
+/**
+ * Normalize a per-provider options bag from either the v3 or legacy v2 shape.
+ *
+ * `provider` and `legacy` parameters are migration-only inputs used to
+ * recover legacy codex fields (effort/codexFastMode/serviceTier) that lived
+ * directly on the draft instead of inside `modelOptions.codex`.
+ */
 function normalizeProviderModelOptions(
   value: unknown,
-  provider?: ProviderKind | null,
+  provider?: ProviderDriverKind | null,
   legacy?: LegacyCodexFields,
-): ProviderModelOptions | null {
+): ProviderOptionSelectionsByProvider | null {
   const candidate = value && typeof value === "object" ? (value as Record<string, unknown>) : null;
-  const codexCandidate =
-    candidate?.codex && typeof candidate.codex === "object"
-      ? (candidate.codex as Record<string, unknown>)
-      : null;
-  const claudeCandidate =
-    candidate?.claudeAgent && typeof candidate.claudeAgent === "object"
-      ? (candidate.claudeAgent as Record<string, unknown>)
-      : null;
-
-  const codexReasoningEffort: CodexReasoningEffort | undefined =
-    codexCandidate?.reasoningEffort === "low" ||
-    codexCandidate?.reasoningEffort === "medium" ||
-    codexCandidate?.reasoningEffort === "high" ||
-    codexCandidate?.reasoningEffort === "xhigh"
-      ? codexCandidate.reasoningEffort
-      : provider === "codex" &&
-          (legacy?.effort === "low" ||
-            legacy?.effort === "medium" ||
-            legacy?.effort === "high" ||
-            legacy?.effort === "xhigh")
-        ? legacy.effort
-        : undefined;
-  const codexFastMode =
-    codexCandidate?.fastMode === true
-      ? true
-      : codexCandidate?.fastMode === false
-        ? false
-        : (provider === "codex" && legacy?.codexFastMode === true) ||
-            (typeof legacy?.serviceTier === "string" && legacy.serviceTier === "fast")
-          ? true
-          : undefined;
-  const codex =
-    codexReasoningEffort !== undefined || codexFastMode !== undefined
-      ? {
-          ...(codexReasoningEffort !== undefined ? { reasoningEffort: codexReasoningEffort } : {}),
-          ...(codexFastMode !== undefined ? { fastMode: codexFastMode } : {}),
-        }
-      : undefined;
-
-  const claudeThinking =
-    claudeCandidate?.thinking === true
-      ? true
-      : claudeCandidate?.thinking === false
-        ? false
-        : undefined;
-  const claudeEffort: ClaudeCodeEffort | undefined =
-    claudeCandidate?.effort === "low" ||
-    claudeCandidate?.effort === "medium" ||
-    claudeCandidate?.effort === "high" ||
-    claudeCandidate?.effort === "max" ||
-    claudeCandidate?.effort === "ultrathink"
-      ? claudeCandidate.effort
-      : undefined;
-  const claudeFastMode =
-    claudeCandidate?.fastMode === true
-      ? true
-      : claudeCandidate?.fastMode === false
-        ? false
-        : undefined;
-  const claudeContextWindow =
-    typeof claudeCandidate?.contextWindow === "string" && claudeCandidate.contextWindow.length > 0
-      ? claudeCandidate.contextWindow
-      : undefined;
-  const claude =
-    claudeThinking !== undefined ||
-    claudeEffort !== undefined ||
-    claudeFastMode !== undefined ||
-    claudeContextWindow !== undefined
-      ? {
-          ...(claudeThinking !== undefined ? { thinking: claudeThinking } : {}),
-          ...(claudeEffort !== undefined ? { effort: claudeEffort } : {}),
-          ...(claudeFastMode !== undefined ? { fastMode: claudeFastMode } : {}),
-          ...(claudeContextWindow !== undefined ? { contextWindow: claudeContextWindow } : {}),
-        }
-      : undefined;
+  const result: ProviderOptionSelectionsByProvider = {};
+  for (const providerKey of ["codex", "claudeAgent", "cursor", "opencode"] as const) {
+    const selections = coerceProviderOptionSelections(candidate?.[providerKey]);
+    if (selections) {
+      result[providerKey] = selections;
+    }
+  }
 
-  if (!codex && !claude) {
-    return null;
+  // Recover legacy codex fields that lived outside modelOptions.
+  if (provider === "codex" && legacy) {
+    const codexExtras: ProviderOptionSelection[] = [];
+    if (typeof legacy.effort === "string" && legacy.effort.length > 0) {
+      codexExtras.push({ id: "reasoningEffort", value: legacy.effort });
+    }
+    const fastMode =
+      legacy.codexFastMode === true ||
+      (typeof legacy.serviceTier === "string" && legacy.serviceTier === "fast");
+    if (fastMode) {
+      codexExtras.push({ id: "fastMode", value: true });
+    }
+    if (codexExtras.length > 0) {
+      const existing = result.codex ?? [];
+      const existingIds = new Set(existing.map((entry) => entry.id));
+      const merged = [...existing];
+      for (const extra of codexExtras) {
+        if (!existingIds.has(extra.id)) merged.push(extra);
+      }
+      result.codex = merged;
+    }
   }
-  return {
-    ...(codex ? { codex } : {}),
-    ...(claude ? { claudeAgent: claude } : {}),
-  };
+
+  return Object.keys(result).length > 0 ? result : null;
 }
 
+// Returns a model selection whose `instanceId` is a valid
+// `ProviderInstanceId` slug. Legacy `provider` fields are promoted verbatim
+// because default instance ids used the same slug as the driver kind.
+//
+// Selections whose instance id doesn't match the slug pattern collapse to
+// `null` — caller is responsible for deciding whether that's a dropped
+// write or a routed error.
 function normalizeModelSelection(
   value: unknown,
   legacy?: {
@@ -630,108 +702,134 @@ function normalizeModelSelection(
     modelOptions?: unknown;
     legacyCodex?: LegacyCodexFields;
   },
-): ModelSelection | null {
+): NormalizedModelSelection | null {
   const candidate = value && typeof value === "object" ? (value as Record<string, unknown>) : null;
-  const provider = normalizeProviderKind(candidate?.provider ?? legacy?.provider);
-  if (provider === null) {
+  // Post-migration ModelSelection carries `instanceId`; pre-migration (v2
+  // storage, legacy wire shapes) carries `provider`. Accept either so both
+  // normalized stores and legacy drafts round-trip through this helper.
+  const instanceId = normalizeProviderInstanceId(
+    candidate?.instanceId ?? candidate?.provider ?? legacy?.provider,
+  );
+  if (instanceId === null) {
     return null;
   }
   const rawModel = candidate?.model ?? legacy?.model;
   if (typeof rawModel !== "string") {
     return null;
   }
-  const model = normalizeModelSlug(rawModel, provider);
+  // Slug normalization can use provider-kind-specific rules when a legacy
+  // driver key is present. Instance-only selections are not reverse-inferred
+  // into a driver kind here; they get generic default normalization.
+  const driverKindHint =
+    normalizeProviderDriverKind(candidate?.provider ?? legacy?.provider) ??
+    ProviderDriverKind.make("codex");
+  const model = normalizeModelSlug(rawModel, driverKindHint);
   if (!model) {
     return null;
   }
-  const modelOptions = normalizeProviderModelOptions(
-    candidate?.options ? { [provider]: candidate.options } : legacy?.modelOptions,
-    provider,
-    provider === "codex" ? legacy?.legacyCodex : undefined,
-  );
-  const options = provider === "codex" ? modelOptions?.codex : modelOptions?.claudeAgent;
-  return {
-    provider,
-    model,
-    ...(options ? { options } : {}),
-  };
+  if (Array.isArray(candidate?.options)) {
+    const selections = coerceProviderOptionSelections(candidate.options);
+    return createModelSelection(instanceId, model, selections) as NormalizedModelSelection;
+  }
+  // Per-kind options were a pre-migration concern; only recover them for a
+  // built-in-kind instance. Custom instances don't have a legacy options
+  // store to thread through here.
+  const kindForLegacyOptions = normalizeProviderDriverKind(instanceId);
+  const modelOptions = kindForLegacyOptions
+    ? normalizeProviderModelOptions(
+        candidate?.options ? { [kindForLegacyOptions]: candidate.options } : legacy?.modelOptions,
+        kindForLegacyOptions,
+        kindForLegacyOptions === "codex" ? legacy?.legacyCodex : undefined,
+      )
+    : null;
+  const options = kindForLegacyOptions ? modelOptions?.[kindForLegacyOptions] : undefined;
+  return createModelSelection(instanceId, model, options) as NormalizedModelSelection;
 }
 
+type NormalizedModelSelection = Omit<ModelSelection, "instanceId"> & {
+  readonly instanceId: ProviderInstanceId;
+};
+
 // ── Legacy sync helpers (used only during migration from v2 storage) ──
+//
+// These operate against the legacy kind-keyed `modelOptions` map. The
+// normalized selection now carries an open `ProviderInstanceId`; legacy
+// migration only recovers options for keys that existed before custom
+// provider instances.
 
 function legacySyncModelSelectionOptions(
-  modelSelection: ModelSelection | null,
-  modelOptions: ProviderModelOptions | null | undefined,
-): ModelSelection | null {
+  modelSelection: NormalizedModelSelection | null,
+  modelOptions: ProviderOptionSelectionsByProvider | null | undefined,
+): NormalizedModelSelection | null {
   if (modelSelection === null) {
     return null;
   }
-  const options = modelOptions?.[modelSelection.provider];
-  return {
-    provider: modelSelection.provider,
-    model: modelSelection.model,
-    ...(options ? { options } : {}),
-  };
+  const kind = normalizeProviderDriverKind(modelSelection.instanceId);
+  const options = kind ? modelOptions?.[kind] : undefined;
+  return createModelSelection(
+    modelSelection.instanceId,
+    modelSelection.model,
+    options,
+  ) as NormalizedModelSelection;
 }
 
 function legacyMergeModelSelectionIntoProviderModelOptions(
-  modelSelection: ModelSelection | null,
-  currentModelOptions: ProviderModelOptions | null | undefined,
-): ProviderModelOptions | null {
-  if (modelSelection?.options === undefined) {
+  modelSelection: NormalizedModelSelection | null,
+  currentModelOptions: ProviderOptionSelectionsByProvider | null | undefined,
+): ProviderOptionSelectionsByProvider | null {
+  if (!modelSelection?.options || modelSelection.options.length === 0) {
+    return normalizeProviderModelOptions(currentModelOptions);
+  }
+  const kind = normalizeProviderDriverKind(modelSelection.instanceId);
+  if (!kind) {
     return normalizeProviderModelOptions(currentModelOptions);
   }
   return legacyReplaceProviderModelOptions(
     normalizeProviderModelOptions(currentModelOptions),
-    modelSelection.provider,
+    kind,
     modelSelection.options,
   );
 }
 
 function legacyReplaceProviderModelOptions(
-  currentModelOptions: ProviderModelOptions | null | undefined,
-  provider: ProviderKind,
-  nextProviderOptions: ProviderModelOptions[ProviderKind] | null | undefined,
-): ProviderModelOptions | null {
+  currentModelOptions: ProviderOptionSelectionsByProvider | null | undefined,
+  provider: ProviderDriverKind,
+  nextProviderOptions: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+): ProviderOptionSelectionsByProvider | null {
   const { [provider]: _discardedProviderModelOptions, ...otherProviderModelOptions } =
     currentModelOptions ?? {};
-  const normalizedNextProviderOptions = normalizeProviderModelOptions(
-    { [provider]: nextProviderOptions },
-    provider,
-  );
-
-  return normalizeProviderModelOptions({
-    ...otherProviderModelOptions,
-    ...(normalizedNextProviderOptions ? normalizedNextProviderOptions : {}),
-  });
+  const merged: ProviderOptionSelectionsByProvider = { ...otherProviderModelOptions };
+  if (nextProviderOptions && nextProviderOptions.length > 0) {
+    merged[provider] = nextProviderOptions;
+  }
+  return Object.keys(merged).length > 0 ? merged : null;
 }
 
 // ── New helpers for the consolidated representation ────────────────────
 
 function legacyToModelSelectionByProvider(
-  modelSelection: ModelSelection | null,
-  modelOptions: ProviderModelOptions | null | undefined,
-): Partial<Record<ProviderKind, ModelSelection>> {
-  const result: Partial<Record<ProviderKind, ModelSelection>> = {};
-  // Add entries from the options bag (for non-active providers)
+  modelSelection: NormalizedModelSelection | null,
+  modelOptions: ProviderOptionSelectionsByProvider | null | undefined,
+): Partial<Record<ProviderInstanceId, ModelSelection>> {
+  const result: Partial<Record<ProviderInstanceId, ModelSelection>> = {};
   if (modelOptions) {
-    for (const provider of ["codex", "claudeAgent"] as const) {
+    for (const provider of ["codex", "claudeAgent", "cursor", "opencode"] as const) {
       const options = modelOptions[provider];
-      if (options && Object.keys(options).length > 0) {
-        result[provider] = {
-          provider,
-          model:
-            modelSelection?.provider === provider
-              ? modelSelection.model
-              : DEFAULT_MODEL_BY_PROVIDER[provider],
+      if (options && options.length > 0) {
+        const driverKind = ProviderDriverKind.make(provider);
+        const instanceKey = defaultInstanceIdForDriver(driverKind);
+        result[instanceKey] = createModelSelection(
+          instanceKey,
+          modelSelection?.instanceId === instanceKey
+            ? modelSelection.model
+            : (DEFAULT_MODEL_BY_PROVIDER[driverKind] ?? DEFAULT_MODEL),
           options,
-        };
+        );
       }
     }
   }
-  // Add/overwrite the active selection (it's authoritative for its provider)
   if (modelSelection) {
-    result[modelSelection.provider] = modelSelection;
+    result[modelSelection.instanceId] = modelSelection as ModelSelection;
   }
   return result;
 }
@@ -742,29 +840,69 @@ export function deriveEffectiveComposerModelState(input: {
     | null
     | undefined;
   providers: ReadonlyArray<ServerProvider>;
-  selectedProvider: ProviderKind;
+  selectedProvider: ProviderDriverKind;
+  /**
+   * Optional routing key of the instance whose selection should override
+   * the driver-level lookup. When present, the draft is queried by
+   * `modelSelectionByProvider[selectedInstanceId]` so a custom Codex
+   * instance (e.g. `codex_personal`) reads its own saved model instead of
+   * collapsing to the default Codex bucket.
+   */
+  selectedInstanceId?: ProviderInstanceId | null | undefined;
   threadModelSelection: ModelSelection | null | undefined;
   projectModelSelection: ModelSelection | null | undefined;
   settings: UnifiedSettings;
 }): EffectiveComposerModelState {
+  const baseModelCandidate =
+    input.threadModelSelection?.model ?? input.projectModelSelection?.model ?? null;
   const baseModel =
-    normalizeModelSlug(
-      input.threadModelSelection?.model ?? input.projectModelSelection?.model,
+    (input.selectedInstanceId
+      ? resolveAppModelSelectionForInstance(
+          input.selectedInstanceId,
+          input.settings,
+          input.providers,
+          baseModelCandidate,
+        )
+      : null) ??
+    resolveAppModelSelection(
       input.selectedProvider,
-    ) ?? getDefaultServerModel(input.providers, input.selectedProvider);
-  const activeSelection = input.draft?.modelSelectionByProvider?.[input.selectedProvider];
+      input.settings,
+      input.providers,
+      baseModelCandidate,
+    ) ??
+    normalizeModelSlug(baseModelCandidate, input.selectedProvider) ??
+    getDefaultServerModel(input.providers, input.selectedProvider);
+  // Look up the instance's saved selection first; fall back to the
+  // driver-kind bucket so legacy kind-keyed drafts still resolve. Every
+  // `ProviderDriverKind` literal is a valid `ProviderInstanceId` slug, so the
+  // cast to the branded type is safe.
+  const instanceSelection = input.selectedInstanceId
+    ? input.draft?.modelSelectionByProvider?.[input.selectedInstanceId]
+    : undefined;
+  const legacySelection =
+    input.draft?.modelSelectionByProvider?.[ProviderInstanceId.make(input.selectedProvider)];
+  const activeSelection = instanceSelection ?? legacySelection;
+  const activeSelectionInstanceId = instanceSelection
+    ? (input.selectedInstanceId ?? ProviderInstanceId.make(input.selectedProvider))
+    : ProviderInstanceId.make(input.selectedProvider);
   const selectedModel = activeSelection?.model
-    ? resolveAppModelSelection(
+    ? (resolveAppModelSelectionForInstance(
+        activeSelectionInstanceId,
+        input.settings,
+        input.providers,
+        activeSelection.model,
+      ) ??
+      resolveAppModelSelection(
         input.selectedProvider,
         input.settings,
         input.providers,
         activeSelection.model,
-      )
+      ))
     : baseModel;
   const modelOptions =
     modelSelectionByProviderToOptions(input.draft?.modelSelectionByProvider) ??
-    providerModelOptionsFromSelection(input.threadModelSelection) ??
-    providerModelOptionsFromSelection(input.projectModelSelection) ??
+    providerSelectionsFromModelSelection(input.threadModelSelection) ??
+    providerSelectionsFromModelSelection(input.projectModelSelection) ??
     null;
 
   return {
@@ -783,6 +921,15 @@ function revokeObjectPreviewUrl(previewUrl: string): void {
   URL.revokeObjectURL(previewUrl);
 }
 
+function revokeDraftThreadPreviewUrls(draft: ComposerThreadDraftState | undefined): void {
+  if (!draft) {
+    return;
+  }
+  for (const image of draft.images) {
+    revokeObjectPreviewUrl(image.previewUrl);
+  }
+}
+
 function normalizePersistedAttachment(value: unknown): PersistedComposerImageAttachment | null {
   if (!value || typeof value !== "object") {
     return null;
@@ -1102,7 +1249,8 @@ function removeDraftThreadReferences(
   ) as Record<string, string>;
   const { [threadKey]: _removedDraftThread, ...restDraftThreadsByThreadKey } =
     state.draftThreadsByThreadKey;
-  const { [threadKey]: _removedComposerDraft, ...restDraftsByThreadKey } = state.draftsByThreadKey;
+  const { [threadKey]: removedComposerDraft, ...restDraftsByThreadKey } = state.draftsByThreadKey;
+  revokeDraftThreadPreviewUrls(removedComposerDraft);
   return {
     draftsByThreadKey: restDraftsByThreadKey,
     draftThreadsByThreadKey: restDraftThreadsByThreadKey,
@@ -1340,8 +1488,8 @@ function normalizePersistedDraftsByThreadId(
     );
     // If the draft already has the v3 shape, use it directly
     const legacyDraftCandidate = draftValue as LegacyPersistedComposerThreadDraftState;
-    let modelSelectionByProvider: Partial<Record<ProviderKind, ModelSelection>> = {};
-    let activeProvider: ProviderKind | null = null;
+    let modelSelectionByProvider: Partial<Record<ProviderInstanceId, ModelSelection>> = {};
+    let activeProvider: ProviderInstanceId | null = null;
 
     if (
       draftCandidate.modelSelectionByProvider &&
@@ -1349,9 +1497,9 @@ function normalizePersistedDraftsByThreadId(
     ) {
       // v3 format
       modelSelectionByProvider = draftCandidate.modelSelectionByProvider as Partial<
-        Record<ProviderKind, ModelSelection>
+        Record<ProviderInstanceId, ModelSelection>
       >;
-      activeProvider = normalizeProviderKind(draftCandidate.activeProvider);
+      activeProvider = normalizeProviderInstanceId(draftCandidate.activeProvider);
     } else {
       // v2 or legacy format: migrate
       const normalizedModelOptions =
@@ -1365,7 +1513,7 @@ function normalizePersistedDraftsByThreadId(
         {
           provider: legacyDraftCandidate.provider,
           model: legacyDraftCandidate.model,
-          modelOptions: normalizedModelOptions ?? legacyDraftCandidate.modelOptions,
+          modelOptions: normalizedModelOptions ?? (legacyDraftCandidate.modelOptions as unknown),
           legacyCodex: legacyDraftCandidate,
         },
       );
@@ -1381,7 +1529,7 @@ function normalizePersistedDraftsByThreadId(
         modelSelection,
         mergedModelOptions,
       );
-      activeProvider = modelSelection?.provider ?? null;
+      activeProvider = modelSelection?.instanceId ?? null;
     }
 
     const hasModelData =
@@ -1412,7 +1560,12 @@ function normalizePersistedDraftsByThreadId(
       prompt,
       attachments,
       ...(terminalContexts.length > 0 ? { terminalContexts } : {}),
-      ...(hasModelData ? { modelSelectionByProvider, activeProvider } : {}),
+      ...(hasModelData
+        ? {
+            modelSelectionByProvider: compactModelSelectionByProvider(modelSelectionByProvider),
+            activeProvider,
+          }
+        : {}),
       ...(runtimeMode ? { runtimeMode } : {}),
       ...(interactionMode ? { interactionMode } : {}),
     };
@@ -1456,7 +1609,7 @@ function migratePersistedComposerDraftStoreState(
     stickyModelSelection,
     nextStickyModelOptions,
   );
-  const stickyActiveProvider = normalizeProviderKind(candidate.stickyProvider) ?? null;
+  const stickyActiveProvider = normalizeProviderInstanceId(candidate.stickyProvider) ?? null;
 
   const { draftThreadsByThreadKey, logicalProjectDraftThreadKeyByLogicalProjectKey } =
     normalizePersistedDraftThreads(rawDraftThreadsByThreadId, rawProjectDraftThreadIdByProjectKey);
@@ -1468,7 +1621,7 @@ function migratePersistedComposerDraftStoreState(
     draftsByThreadKey,
     draftThreadsByThreadKey,
     logicalProjectDraftThreadKeyByLogicalProjectKey,
-    stickyModelSelectionByProvider,
+    stickyModelSelectionByProvider: compactModelSelectionByProvider(stickyModelSelectionByProvider),
     stickyActiveProvider,
   };
 }
@@ -1513,7 +1666,9 @@ function partializeComposerDraftStoreState(
         : {}),
       ...(hasModelData
         ? {
-            modelSelectionByProvider: draft.modelSelectionByProvider,
+            modelSelectionByProvider: compactModelSelectionByProvider(
+              draft.modelSelectionByProvider,
+            ),
             activeProvider: draft.activeProvider,
           }
         : {}),
@@ -1527,7 +1682,9 @@ function partializeComposerDraftStoreState(
     draftThreadsByThreadKey: state.draftThreadsByThreadKey,
     logicalProjectDraftThreadKeyByLogicalProjectKey:
       state.logicalProjectDraftThreadKeyByLogicalProjectKey,
-    stickyModelSelectionByProvider: state.stickyModelSelectionByProvider,
+    stickyModelSelectionByProvider: compactModelSelectionByProvider(
+      state.stickyModelSelectionByProvider,
+    ),
     stickyActiveProvider: state.stickyActiveProvider,
   };
 }
@@ -1550,17 +1707,19 @@ function normalizeCurrentPersistedComposerDraftStoreState(
     );
 
   // Handle both v3 (modelSelectionByProvider) and v2/legacy formats
-  let stickyModelSelectionByProvider: Partial<Record<ProviderKind, ModelSelection>> = {};
-  let stickyActiveProvider: ProviderKind | null = null;
+  let stickyModelSelectionByProvider: Partial<Record<ProviderInstanceId, ModelSelection>> = {};
+  let stickyActiveProvider: ProviderInstanceId | null = null;
   if (
     normalizedPersistedState.stickyModelSelectionByProvider &&
     typeof normalizedPersistedState.stickyModelSelectionByProvider === "object"
   ) {
     stickyModelSelectionByProvider =
       normalizedPersistedState.stickyModelSelectionByProvider as Partial<
-        Record<ProviderKind, ModelSelection>
+        Record<ProviderInstanceId, ModelSelection>
       >;
-    stickyActiveProvider = normalizeProviderKind(normalizedPersistedState.stickyActiveProvider);
+    stickyActiveProvider = normalizeProviderInstanceId(
+      normalizedPersistedState.stickyActiveProvider,
+    );
   } else {
     // Legacy migration path
     const stickyModelOptions =
@@ -1585,7 +1744,7 @@ function normalizeCurrentPersistedComposerDraftStoreState(
       stickyModelSelection,
       nextStickyModelOptions,
     );
-    stickyActiveProvider = normalizeProviderKind(normalizedPersistedState.stickyProvider);
+    stickyActiveProvider = normalizeProviderInstanceId(normalizedPersistedState.stickyProvider);
   }
 
   return {
@@ -1595,7 +1754,7 @@ function normalizeCurrentPersistedComposerDraftStoreState(
     ),
     draftThreadsByThreadKey,
     logicalProjectDraftThreadKeyByLogicalProjectKey,
-    stickyModelSelectionByProvider,
+    stickyModelSelectionByProvider: compactModelSelectionByProvider(stickyModelSelectionByProvider),
     stickyActiveProvider,
   };
 }
@@ -1724,9 +1883,9 @@ function toHydratedThreadDraft(
   persistedDraft: PersistedComposerThreadDraftState,
 ): ComposerThreadDraftState {
   // The persisted draft is already in v3 shape (migration handles older formats)
-  const modelSelectionByProvider: Partial<Record<ProviderKind, ModelSelection>> =
+  const modelSelectionByProvider: Partial<Record<ProviderInstanceId, ModelSelection>> =
     persistedDraft.modelSelectionByProvider ?? {};
-  const activeProvider = normalizeProviderKind(persistedDraft.activeProvider) ?? null;
+  const activeProvider = normalizeProviderInstanceId(persistedDraft.activeProvider) ?? null;
 
   return {
     prompt: persistedDraft.prompt,
@@ -1881,13 +2040,18 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
               [draftId]: nextDraftThread,
             };
             let nextDraftsByThreadKey = state.draftsByThreadKey;
+            const previousDraftThread =
+              previousThreadKeyForLogicalProject === undefined
+                ? undefined
+                : nextDraftThreadsByThreadKey[previousThreadKeyForLogicalProject];
             if (
               previousThreadKeyForLogicalProject &&
               previousThreadKeyForLogicalProject !== draftId &&
               !isComposerThreadKeyInUse(
                 nextLogicalProjectDraftThreadKeyByLogicalProjectKey,
                 previousThreadKeyForLogicalProject,
-              )
+              ) &&
+              !isDraftThreadPromoting(previousDraftThread)
             ) {
               delete nextDraftThreadsByThreadKey[previousThreadKeyForLogicalProject];
               if (state.draftsByThreadKey[previousThreadKeyForLogicalProject] !== undefined) {
@@ -2064,12 +2228,6 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
           if (threadKey.length === 0) {
             return;
           }
-          const existing = get().draftsByThreadKey[threadKey];
-          if (existing) {
-            for (const image of existing.images) {
-              revokeObjectPreviewUrl(image.previewUrl);
-            }
-          }
           set((state) => {
             const hasDraftThread = state.draftThreadsByThreadKey[threadKey] !== undefined;
             const hasLogicalProjectMapping = Object.values(
@@ -2088,18 +2246,18 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
             if (!normalized) {
               return state;
             }
-            const nextMap: Partial<Record<ProviderKind, ModelSelection>> = {
+            const nextMap: Partial<Record<ProviderInstanceId, ModelSelection>> = {
               ...state.stickyModelSelectionByProvider,
-              [normalized.provider]: normalized,
+              [normalized.instanceId]: normalized,
             };
             if (Equal.equals(state.stickyModelSelectionByProvider, nextMap)) {
-              return state.stickyActiveProvider === normalized.provider
+              return state.stickyActiveProvider === normalized.instanceId
                 ? state
-                : { stickyActiveProvider: normalized.provider };
+                : { stickyActiveProvider: normalized.instanceId };
             }
             return {
               stickyModelSelectionByProvider: nextMap,
-              stickyActiveProvider: normalized.provider,
+              stickyActiveProvider: normalized.instanceId,
             };
           });
         },
@@ -2119,8 +2277,12 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
             const nextMap = { ...base.modelSelectionByProvider };
             for (const [provider, selection] of Object.entries(stickyMap)) {
               if (selection) {
-                const current = nextMap[provider as ProviderKind];
-                nextMap[provider as ProviderKind] = {
+                // Iteration key comes from the instance-keyed sticky map,
+                // so coerce the string back to `ProviderInstanceId` for
+                // the typed lookup.
+                const instanceKey = provider as ProviderInstanceId;
+                const current = nextMap[instanceKey];
+                nextMap[instanceKey] = {
                   ...selection,
                   model: current?.model ?? selection.model,
                 };
@@ -2206,20 +2368,20 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
             const base = existing ?? createEmptyThreadDraft();
             const nextMap = { ...base.modelSelectionByProvider };
             if (normalized) {
-              const current = nextMap[normalized.provider];
+              const current = nextMap[normalized.instanceId];
               if (normalized.options !== undefined) {
                 // Explicit options provided → use them
-                nextMap[normalized.provider] = normalized;
+                nextMap[normalized.instanceId] = normalized as ModelSelection;
               } else {
                 // No options in selection → preserve existing options, update provider+model
-                nextMap[normalized.provider] = {
-                  provider: normalized.provider,
-                  model: normalized.model,
-                  ...(current?.options ? { options: current.options } : {}),
-                };
+                nextMap[normalized.instanceId] = createModelSelection(
+                  normalized.instanceId,
+                  normalized.model,
+                  current?.options,
+                );
               }
             }
-            const nextActiveProvider = normalized?.provider ?? base.activeProvider;
+            const nextActiveProvider = normalized?.instanceId ?? base.activeProvider;
             if (
               Equal.equals(base.modelSelectionByProvider, nextMap) &&
               base.activeProvider === nextActiveProvider
@@ -2245,29 +2407,28 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
           if (threadKey.length === 0) {
             return;
           }
-          const normalizedOpts = normalizeProviderModelOptions(modelOptions);
           set((state) => {
             const existing = state.draftsByThreadKey[threadKey];
-            if (!existing && normalizedOpts === null) {
+            if (!existing && (!modelOptions || Object.keys(modelOptions).length === 0)) {
               return state;
             }
             const base = existing ?? createEmptyThreadDraft();
             const nextMap = { ...base.modelSelectionByProvider };
-            for (const provider of ["codex", "claudeAgent"] as const) {
-              // Only touch providers explicitly present in the input
-              if (!normalizedOpts || !(provider in normalizedOpts)) continue;
-              const opts = normalizedOpts[provider];
-              const current = nextMap[provider];
-              if (opts) {
-                nextMap[provider] = {
-                  provider,
-                  model: current?.model ?? DEFAULT_MODEL_BY_PROVIDER[provider],
-                  options: opts,
-                };
+            for (const provider of ["codex", "claudeAgent", "cursor", "opencode"] as const) {
+              if (!modelOptions || !(provider in modelOptions)) continue;
+              const opts = modelOptions[provider];
+              const driverKind = ProviderDriverKind.make(provider);
+              const instanceKey = defaultInstanceIdForDriver(driverKind);
+              const current = nextMap[instanceKey];
+              if (opts && opts.length > 0) {
+                nextMap[instanceKey] = createModelSelection(
+                  instanceKey,
+                  current?.model ?? DEFAULT_MODEL_BY_PROVIDER[driverKind] ?? DEFAULT_MODEL,
+                  opts,
+                );
               } else if (current?.options) {
-                // Remove options but keep the selection
                 const { options: _, ...rest } = current;
-                nextMap[provider] = rest as ModelSelection;
+                nextMap[instanceKey] = rest as ModelSelection;
               }
             }
             if (Equal.equals(base.modelSelectionByProvider, nextMap)) {
@@ -2291,16 +2452,17 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
           if (threadKey.length === 0) {
             return;
           }
-          const normalizedProvider = normalizeProviderKind(provider);
+          const normalizedProvider = normalizeProviderDriverKind(provider);
           if (normalizedProvider === null) {
             return;
           }
-          // Normalize just this provider's options
-          const normalizedOpts = normalizeProviderModelOptions(
-            { [normalizedProvider]: nextProviderOptions },
-            normalizedProvider,
-          );
-          const providerOpts = normalizedOpts?.[normalizedProvider];
+          const instanceKey = defaultInstanceIdForDriver(normalizedProvider);
+          const fallbackModel =
+            normalizeModelSlug(options?.model, normalizedProvider) ??
+            DEFAULT_MODEL_BY_PROVIDER[normalizedProvider] ??
+            DEFAULT_MODEL;
+          const providerOpts =
+            nextProviderOptions && nextProviderOptions.length > 0 ? nextProviderOptions : undefined;
 
           set((state) => {
             const existing = state.draftsByThreadKey[threadKey];
@@ -2308,16 +2470,16 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
 
             // Update the map entry for this provider
             const nextMap = { ...base.modelSelectionByProvider };
-            const currentForProvider = nextMap[normalizedProvider];
+            const currentForProvider = nextMap[instanceKey];
             if (providerOpts) {
-              nextMap[normalizedProvider] = {
-                provider: normalizedProvider,
-                model: currentForProvider?.model ?? DEFAULT_MODEL_BY_PROVIDER[normalizedProvider],
-                options: providerOpts,
-              };
-            } else if (currentForProvider?.options) {
+              nextMap[instanceKey] = createModelSelection(
+                instanceKey,
+                currentForProvider?.model ?? fallbackModel,
+                providerOpts,
+              );
+            } else if (currentForProvider && (currentForProvider.options?.length ?? 0) > 0) {
               const { options: _, ...rest } = currentForProvider;
-              nextMap[normalizedProvider] = rest as ModelSelection;
+              nextMap[instanceKey] = rest as ModelSelection;
             }
 
             // Handle sticky persistence
@@ -2326,23 +2488,20 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
             if (options?.persistSticky === true) {
               nextStickyMap = { ...state.stickyModelSelectionByProvider };
               const stickyBase =
-                nextStickyMap[normalizedProvider] ??
-                base.modelSelectionByProvider[normalizedProvider] ??
-                ({
-                  provider: normalizedProvider,
-                  model: DEFAULT_MODEL_BY_PROVIDER[normalizedProvider],
-                } as ModelSelection);
+                nextStickyMap[instanceKey] ??
+                base.modelSelectionByProvider[instanceKey] ??
+                createModelSelection(instanceKey, fallbackModel);
               if (providerOpts) {
-                nextStickyMap[normalizedProvider] = {
-                  ...stickyBase,
-                  provider: normalizedProvider,
-                  options: providerOpts,
-                };
-              } else if (stickyBase.options) {
+                nextStickyMap[instanceKey] = createModelSelection(
+                  instanceKey,
+                  stickyBase.model,
+                  providerOpts,
+                );
+              } else if ((stickyBase.options?.length ?? 0) > 0) {
                 const { options: _, ...rest } = stickyBase;
-                nextStickyMap[normalizedProvider] = rest as ModelSelection;
+                nextStickyMap[instanceKey] = rest as ModelSelection;
               }
-              nextStickyActiveProvider = base.activeProvider ?? normalizedProvider;
+              nextStickyActiveProvider = base.activeProvider ?? instanceKey;
             }
 
             if (
@@ -2793,7 +2952,13 @@ export function useEffectiveComposerModelState(input: {
   threadRef?: ComposerThreadTarget;
   draftId?: DraftId;
   providers: ReadonlyArray<ServerProvider>;
-  selectedProvider: ProviderKind;
+  selectedProvider: ProviderDriverKind;
+  /**
+   * When supplied, the draft's saved selection for this instance takes
+   * precedence over the driver-kind bucket — so a custom `codex_personal`
+   * instance reads its own model, not the default Codex's.
+   */
+  selectedInstanceId?: ProviderInstanceId | null | undefined;
   threadModelSelection: ModelSelection | null | undefined;
   projectModelSelection: ModelSelection | null | undefined;
   settings: UnifiedSettings;
@@ -2806,6 +2971,7 @@ export function useEffectiveComposerModelState(input: {
         draft,
         providers: input.providers,
         selectedProvider: input.selectedProvider,
+        selectedInstanceId: input.selectedInstanceId,
         threadModelSelection: input.threadModelSelection,
         projectModelSelection: input.projectModelSelection,
         settings: input.settings,
@@ -2815,6 +2981,7 @@ export function useEffectiveComposerModelState(input: {
       input.providers,
       input.settings,
       input.projectModelSelection,
+      input.selectedInstanceId,
       input.selectedProvider,
       input.threadModelSelection,
     ],
diff --git a/apps/web/src/composerHandleContext.ts b/apps/web/src/composerHandleContext.ts
index 820720ba7e4..4b825d3dde0 100644
--- a/apps/web/src/composerHandleContext.ts
+++ b/apps/web/src/composerHandleContext.ts
@@ -1,10 +1,10 @@
-import { createContext, useContext, type MutableRefObject } from "react";
+import { createContext, use } from "react";
 import type { ChatComposerHandle } from "./components/chat/ChatComposer";
 
-export type ComposerHandleRef = MutableRefObject<ChatComposerHandle | null>;
+export type ComposerHandleRef = React.RefObject<ChatComposerHandle | null>;
 
 export const ComposerHandleContext = createContext<ComposerHandleRef | null>(null);
 
 export function useComposerHandleContext(): ComposerHandleRef | null {
-  return useContext(ComposerHandleContext);
+  return use(ComposerHandleContext);
 }
diff --git a/apps/web/src/contextMenuFallback.test.ts b/apps/web/src/contextMenuFallback.test.ts
new file mode 100644
index 00000000000..598d0d8bbed
--- /dev/null
+++ b/apps/web/src/contextMenuFallback.test.ts
@@ -0,0 +1,221 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { showContextMenuFallback } from "./contextMenuFallback";
+
+type FakeListener = (event: FakeDomEvent) => void;
+
+class FakeDomEvent {
+  defaultPrevented = false;
+
+  constructor(
+    readonly type: string,
+    init: Record<string, unknown> = {},
+  ) {
+    Object.assign(this, init);
+  }
+
+  preventDefault() {
+    this.defaultPrevented = true;
+  }
+}
+
+class FakeElement {
+  children: FakeElement[] = [];
+  parent: FakeElement | null = null;
+  style: Record<string, string> & { cssText?: string } = {};
+  dataset: Record<string, string> = {};
+  className = "";
+  disabled = false;
+  type = "";
+  private textValue = "";
+  private readonly listeners = new Map<string, FakeListener[]>();
+
+  constructor(readonly tagName: string) {}
+
+  appendChild(child: FakeElement) {
+    child.parent = this;
+    this.children.push(child);
+    return child;
+  }
+
+  remove() {
+    if (!this.parent) {
+      return;
+    }
+    const index = this.parent.children.indexOf(this);
+    if (index >= 0) {
+      this.parent.children.splice(index, 1);
+    }
+    this.parent = null;
+  }
+
+  addEventListener(type: string, listener: FakeListener) {
+    const existing = this.listeners.get(type) ?? [];
+    existing.push(listener);
+    this.listeners.set(type, existing);
+  }
+
+  dispatchEvent(event: FakeDomEvent) {
+    for (const listener of this.listeners.get(event.type) ?? []) {
+      listener(event);
+    }
+    return true;
+  }
+
+  set textContent(value: string) {
+    this.textValue = value;
+  }
+
+  get textContent() {
+    return `${this.textValue}${this.children.map((child) => child.textContent).join("")}`;
+  }
+
+  querySelectorAll(tagName: string): FakeElement[] {
+    const matches: FakeElement[] = [];
+    if (this.tagName === tagName) {
+      matches.push(this);
+    }
+    for (const child of this.children) {
+      matches.push(...child.querySelectorAll(tagName));
+    }
+    return matches;
+  }
+
+  getBoundingClientRect() {
+    const left = Number.parseInt(this.style.left ?? "0", 10) || 0;
+    const top = Number.parseInt(this.style.top ?? "0", 10) || 0;
+    const width = this.tagName === "div" ? 180 : 140;
+    const height = this.tagName === "div" ? 120 : 28;
+    return {
+      left,
+      top,
+      width,
+      height,
+      right: left + width,
+      bottom: top + height,
+    };
+  }
+}
+
+class FakeBody extends FakeElement {
+  private html = "";
+
+  constructor() {
+    super("body");
+  }
+
+  set innerHTML(value: string) {
+    this.html = value;
+    this.children = [];
+  }
+
+  get innerHTML() {
+    return this.html;
+  }
+}
+
+class FakeDocument {
+  body = new FakeBody();
+  private readonly listeners = new Map<string, FakeListener[]>();
+
+  createElement(tagName: string) {
+    return new FakeElement(tagName);
+  }
+
+  addEventListener(type: string, listener: FakeListener) {
+    const existing = this.listeners.get(type) ?? [];
+    existing.push(listener);
+    this.listeners.set(type, existing);
+  }
+
+  removeEventListener(type: string, listener: FakeListener) {
+    const existing = this.listeners.get(type);
+    if (!existing) {
+      return;
+    }
+    const index = existing.indexOf(listener);
+    if (index >= 0) {
+      existing.splice(index, 1);
+    }
+  }
+
+  querySelectorAll(tagName: string) {
+    return this.body.querySelectorAll(tagName);
+  }
+}
+
+function findButton(label: string): FakeElement | undefined {
+  return (document as unknown as FakeDocument)
+    .querySelectorAll("button")
+    .find((button) => button.textContent.includes(label));
+}
+
+beforeEach(() => {
+  vi.stubGlobal("document", new FakeDocument());
+  vi.stubGlobal("window", {
+    innerWidth: 1280,
+    innerHeight: 800,
+  });
+  vi.stubGlobal("requestAnimationFrame", (callback: (time: number) => void) => {
+    callback(0);
+    return 0;
+  });
+  vi.stubGlobal(
+    "MouseEvent",
+    class extends FakeDomEvent {
+      constructor(type: string, init: Record<string, unknown> = {}) {
+        super(type, init);
+      }
+    },
+  );
+  vi.stubGlobal(
+    "KeyboardEvent",
+    class extends FakeDomEvent {
+      constructor(type: string, init: Record<string, unknown> = {}) {
+        super(type, init);
+      }
+    },
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("showContextMenuFallback", () => {
+  it("resolves a clicked flat menu item", async () => {
+    const selectionPromise = showContextMenuFallback([
+      { id: "rename", label: "Rename" },
+      { id: "delete", label: "Delete", destructive: true },
+    ]);
+
+    const renameButton = findButton("Rename");
+    expect(renameButton).toBeTruthy();
+    renameButton?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+
+    await expect(selectionPromise).resolves.toBe("rename");
+  });
+
+  it("opens nested submenus and resolves the clicked leaf id", async () => {
+    const selectionPromise = showContextMenuFallback([
+      {
+        id: "rename:submenu",
+        label: "Rename project",
+        children: [
+          { id: "rename:project-a", label: "/tmp/project-a" },
+          { id: "rename:project-b", label: "/tmp/project-b" },
+        ],
+      },
+    ]);
+
+    const parentButton = findButton("Rename project");
+    expect(parentButton).toBeTruthy();
+    parentButton?.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
+
+    const childButton = findButton("/tmp/project-b");
+    expect(childButton).toBeTruthy();
+    childButton?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+
+    await expect(selectionPromise).resolves.toBe("rename:project-b");
+  });
+});
diff --git a/apps/web/src/contextMenuFallback.ts b/apps/web/src/contextMenuFallback.ts
index 9fd1a12956e..cda90df5d11 100644
--- a/apps/web/src/contextMenuFallback.ts
+++ b/apps/web/src/contextMenuFallback.ts
@@ -1,9 +1,22 @@
 import type { ContextMenuItem } from "@t3tools/contracts";
 
+function clampMenuPosition(menu: HTMLDivElement, preferredLeft: number, preferredTop: number) {
+  const rect = menu.getBoundingClientRect();
+  const left = Math.min(
+    Math.max(4, preferredLeft),
+    Math.max(4, window.innerWidth - rect.width - 4),
+  );
+  const top = Math.min(
+    Math.max(4, preferredTop),
+    Math.max(4, window.innerHeight - rect.height - 4),
+  );
+  menu.style.left = `${left}px`;
+  menu.style.top = `${top}px`;
+}
+
 /**
  * Imperative DOM-based context menu for non-Electron environments.
- * Shows a positioned dropdown and returns a promise that resolves
- * with the clicked item id, or null if dismissed.
+ * Supports nested submenus and resolves with the clicked leaf item id.
  */
 export function showContextMenuFallback<T extends string>(
   items: readonly ContextMenuItem<T>[],
@@ -13,62 +26,117 @@ export function showContextMenuFallback<T extends string>(
     const overlay = document.createElement("div");
     overlay.style.cssText = "position:fixed;inset:0;z-index:9999";
 
-    const menu = document.createElement("div");
-    menu.className =
-      "fixed z-[10000] min-w-[140px] rounded-md border border-border bg-popover py-1 shadow-xl animate-in fade-in zoom-in-95";
-
-    const x = position?.x ?? 0;
-    const y = position?.y ?? 0;
-    menu.style.top = `${y}px`;
-    menu.style.left = `${x}px`;
+    const menuStack: HTMLDivElement[] = [];
 
-    function cleanup(result: T | null) {
+    const cleanup = (result: T | null) => {
       document.removeEventListener("keydown", onKeyDown);
       overlay.remove();
-      menu.remove();
+      for (const menu of menuStack) {
+        menu.remove();
+      }
       resolve(result);
-    }
+    };
 
-    function onKeyDown(e: KeyboardEvent) {
-      if (e.key === "Escape") {
-        e.preventDefault();
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
         cleanup(null);
       }
-    }
+    };
 
-    overlay.addEventListener("mousedown", () => cleanup(null));
-    document.addEventListener("keydown", onKeyDown);
-
-    for (const item of items) {
-      const btn = document.createElement("button");
-      btn.type = "button";
-      btn.textContent = item.label;
-      const isDestructiveAction = item.destructive === true || item.id === "delete";
-      const isDisabled = item.disabled === true;
-      btn.disabled = isDisabled;
-      btn.className = isDisabled
-        ? "flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-muted-foreground/60 cursor-not-allowed"
-        : isDestructiveAction
-          ? "flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-destructive hover:bg-accent cursor-default"
-          : "flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-popover-foreground hover:bg-accent cursor-default";
-      if (!isDisabled) {
-        btn.addEventListener("click", () => cleanup(item.id));
+    const closeMenusFromLevel = (level: number) => {
+      while (menuStack.length > level) {
+        menuStack.pop()?.remove();
       }
-      menu.appendChild(btn);
-    }
+    };
 
-    document.body.appendChild(overlay);
-    document.body.appendChild(menu);
+    const openMenu = (
+      entries: readonly ContextMenuItem<T>[],
+      preferredLeft: number,
+      preferredTop: number,
+      level: number,
+    ) => {
+      closeMenusFromLevel(level);
 
-    // Adjust if menu overflows viewport
-    requestAnimationFrame(() => {
-      const rect = menu.getBoundingClientRect();
-      if (rect.right > window.innerWidth) {
-        menu.style.left = `${window.innerWidth - rect.width - 4}px`;
-      }
-      if (rect.bottom > window.innerHeight) {
-        menu.style.top = `${window.innerHeight - rect.height - 4}px`;
+      const menu = document.createElement("div");
+      menu.className =
+        "fixed z-[10000] min-w-[160px] rounded-md border border-border bg-popover py-1 shadow-xl animate-in fade-in zoom-in-95";
+      menu.style.left = `${preferredLeft}px`;
+      menu.style.top = `${preferredTop}px`;
+      menu.dataset.level = String(level);
+
+      for (const item of entries) {
+        const button = document.createElement("button");
+        button.type = "button";
+        const hasChildren = Array.isArray(item.children) && item.children.length > 0;
+        const isLeafDestructive =
+          !hasChildren && (item.destructive === true || item.id === ("delete" as T));
+        const isDisabled = item.disabled === true;
+        button.disabled = isDisabled;
+        button.className = isDisabled
+          ? "flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-muted-foreground/60 cursor-not-allowed"
+          : isLeafDestructive
+            ? "flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-destructive hover:bg-accent cursor-default"
+            : "flex w-full items-center gap-2 px-3 py-1.5 text-left text-[11px] text-popover-foreground hover:bg-accent cursor-default";
+
+        const label = document.createElement("span");
+        label.className = "min-w-0 flex-1 truncate";
+        label.textContent = item.label;
+        button.appendChild(label);
+
+        if (hasChildren) {
+          const chevron = document.createElement("span");
+          chevron.className = "shrink-0 text-muted-foreground/70";
+          chevron.textContent = "›";
+          button.appendChild(chevron);
+        }
+
+        if (!isDisabled) {
+          if (hasChildren) {
+            button.addEventListener("mouseenter", () => {
+              const rect = button.getBoundingClientRect();
+              const nextLeft = rect.right + 4;
+              const nextTop = rect.top;
+              openMenu(item.children!, nextLeft, nextTop, level + 1);
+
+              const childMenu = menuStack[level + 1];
+              if (!childMenu) {
+                return;
+              }
+              const childRect = childMenu.getBoundingClientRect();
+              if (childRect.right > window.innerWidth) {
+                clampMenuPosition(childMenu, rect.left - childRect.width - 4, rect.top);
+              }
+            });
+            button.addEventListener("click", (event) => {
+              event.preventDefault();
+            });
+          } else {
+            button.addEventListener("mouseenter", () => {
+              closeMenusFromLevel(level + 1);
+            });
+            button.addEventListener("click", () => cleanup(item.id));
+          }
+        }
+
+        menu.appendChild(button);
       }
-    });
+
+      menu.addEventListener("mouseenter", () => {
+        closeMenusFromLevel(level + 1);
+      });
+
+      document.body.appendChild(menu);
+      menuStack[level] = menu;
+
+      requestAnimationFrame(() => {
+        clampMenuPosition(menu, preferredLeft, preferredTop);
+      });
+    };
+
+    overlay.addEventListener("mousedown", () => cleanup(null));
+    document.addEventListener("keydown", onKeyDown);
+    document.body.appendChild(overlay);
+    openMenu(items, position?.x ?? 0, position?.y ?? 0, 0);
   });
 }
diff --git a/apps/web/src/environmentApi.ts b/apps/web/src/environmentApi.ts
index 5f23a53a756..9e7b0c939a9 100644
--- a/apps/web/src/environmentApi.ts
+++ b/apps/web/src/environmentApi.ts
@@ -3,6 +3,8 @@ import type { EnvironmentId, EnvironmentApi } from "@t3tools/contracts";
 import type { WsRpcClient } from "./rpc/wsRpcClient";
 import { readEnvironmentConnection } from "./environments/runtime";
 
+const environmentApiOverridesForTests = new Map<EnvironmentId, EnvironmentApi>();
+
 export function createEnvironmentApi(rpcClient: WsRpcClient): EnvironmentApi {
   return {
     terminal: {
@@ -18,30 +20,38 @@ export function createEnvironmentApi(rpcClient: WsRpcClient): EnvironmentApi {
       searchEntries: rpcClient.projects.searchEntries,
       writeFile: rpcClient.projects.writeFile,
     },
+    filesystem: {
+      browse: rpcClient.filesystem.browse,
+    },
+    sourceControl: {
+      lookupRepository: rpcClient.sourceControl.lookupRepository,
+      cloneRepository: rpcClient.sourceControl.cloneRepository,
+      publishRepository: rpcClient.sourceControl.publishRepository,
+    },
+    vcs: {
+      pull: rpcClient.vcs.pull,
+      refreshStatus: rpcClient.vcs.refreshStatus,
+      onStatus: (input, callback, options) => rpcClient.vcs.onStatus(input, callback, options),
+      listRefs: rpcClient.vcs.listRefs,
+      createWorktree: rpcClient.vcs.createWorktree,
+      removeWorktree: rpcClient.vcs.removeWorktree,
+      createRef: rpcClient.vcs.createRef,
+      switchRef: rpcClient.vcs.switchRef,
+      init: rpcClient.vcs.init,
+    },
     git: {
-      pull: rpcClient.git.pull,
-      refreshStatus: rpcClient.git.refreshStatus,
-      onStatus: (input, callback, options) => rpcClient.git.onStatus(input, callback, options),
-      listBranches: rpcClient.git.listBranches,
-      createWorktree: rpcClient.git.createWorktree,
-      removeWorktree: rpcClient.git.removeWorktree,
-      createBranch: rpcClient.git.createBranch,
-      checkout: rpcClient.git.checkout,
-      init: rpcClient.git.init,
       resolvePullRequest: rpcClient.git.resolvePullRequest,
       preparePullRequestThread: rpcClient.git.preparePullRequestThread,
     },
     orchestration: {
-      getSnapshot: rpcClient.orchestration.getSnapshot,
       dispatchCommand: rpcClient.orchestration.dispatchCommand,
       getTurnDiff: rpcClient.orchestration.getTurnDiff,
       getFullThreadDiff: rpcClient.orchestration.getFullThreadDiff,
-      replayEvents: (fromSequenceExclusive) =>
-        rpcClient.orchestration
-          .replayEvents({ fromSequenceExclusive })
-          .then((events) => [...events]),
-      onDomainEvent: (callback, options) =>
-        rpcClient.orchestration.onDomainEvent(callback, options),
+      getArchivedShellSnapshot: rpcClient.orchestration.getArchivedShellSnapshot,
+      subscribeShell: (callback, options) =>
+        rpcClient.orchestration.subscribeShell(callback, options),
+      subscribeThread: (input, callback, options) =>
+        rpcClient.orchestration.subscribeThread(input, callback, options),
     },
   };
 }
@@ -55,6 +65,11 @@ export function readEnvironmentApi(environmentId: EnvironmentId): EnvironmentApi
     return undefined;
   }
 
+  const overriddenApi = environmentApiOverridesForTests.get(environmentId);
+  if (overriddenApi) {
+    return overriddenApi;
+  }
+
   const connection = readEnvironmentConnection(environmentId);
   return connection ? createEnvironmentApi(connection.client) : undefined;
 }
@@ -66,3 +81,14 @@ export function ensureEnvironmentApi(environmentId: EnvironmentId): EnvironmentA
   }
   return api;
 }
+
+export function __setEnvironmentApiOverrideForTests(
+  environmentId: EnvironmentId,
+  api: EnvironmentApi,
+): void {
+  environmentApiOverridesForTests.set(environmentId, api);
+}
+
+export function __resetEnvironmentApiOverridesForTests(): void {
+  environmentApiOverridesForTests.clear();
+}
diff --git a/apps/web/src/environmentGrouping.test.ts b/apps/web/src/environmentGrouping.test.ts
index 4e8473188a1..8dd5eb89a08 100644
--- a/apps/web/src/environmentGrouping.test.ts
+++ b/apps/web/src/environmentGrouping.test.ts
@@ -1,4 +1,4 @@
-import { EnvironmentId, ProjectId, ThreadId } from "@t3tools/contracts";
+import { EnvironmentId, ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 import { scopeProjectRef } from "@t3tools/client-runtime";
 import { describe, expect, it } from "vitest";
 
@@ -10,7 +10,12 @@ import {
   type AppState,
   type EnvironmentState,
 } from "./store";
-import { deriveLogicalProjectKey } from "./logicalProject";
+import {
+  deriveLogicalProjectKey,
+  deriveLogicalProjectKeyFromSettings,
+  derivePhysicalProjectKey,
+  resolveProjectGroupingMode,
+} from "./logicalProject";
 import type { Project, SidebarThreadSummary } from "./types";
 import { DEFAULT_INTERACTION_MODE } from "./types";
 
@@ -31,6 +36,10 @@ const threadL1 = ThreadId.make("thread-local-only-1");
 const threadRO1 = ThreadId.make("thread-remote-only-1");
 
 const SHARED_REPO_CANONICAL_KEY = "github.com/example/shared-repo";
+const DEFAULT_GROUPING_SETTINGS = {
+  sidebarProjectGroupingMode: "repository" as const,
+  sidebarProjectGroupingOverrides: {},
+};
 
 // ── Factory Helpers ──────────────────────────────────────────────────
 
@@ -39,7 +48,7 @@ function makeProject(
 ): Project {
   return {
     cwd: `/tmp/${overrides.name}`,
-    defaultModelSelection: { provider: "codex" as const, model: "gpt-5-codex" },
+    defaultModelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5-codex" },
     createdAt: "2026-01-01T00:00:00.000Z",
     updatedAt: "2026-01-01T00:00:00.000Z",
     scripts: [],
@@ -238,9 +247,7 @@ describe("environment grouping", () => {
         environmentId: primaryEnvId,
         name: "local-only",
       });
-      const key = deriveLogicalProjectKey(project);
-      expect(key).toContain(primaryEnvId);
-      expect(key).toContain(localOnlyProjectId);
+      expect(deriveLogicalProjectKey(project)).toBe(derivePhysicalProjectKey(project));
     });
 
     it("groups projects from different environments that share the same canonical key", () => {
@@ -273,6 +280,134 @@ describe("environment grouping", () => {
       expect(deriveLogicalProjectKey(primary)).toBe(deriveLogicalProjectKey(remote));
     });
 
+    it("groups repo root and nested projects from the same repository by default", () => {
+      const rootProject = makeProject({
+        id: sharedProjectPrimaryId,
+        environmentId: primaryEnvId,
+        name: "shared-repo",
+        cwd: "/workspace/repo",
+        repositoryIdentity: {
+          canonicalKey: SHARED_REPO_CANONICAL_KEY,
+          rootPath: "/workspace/repo",
+          locator: {
+            source: "git-remote",
+            remoteName: "origin",
+            remoteUrl: "https://github.com/example/shared-repo.git",
+          },
+        },
+      });
+      const nestedProject = makeProject({
+        id: localOnlyProjectId,
+        environmentId: primaryEnvId,
+        name: "web",
+        cwd: "/workspace/repo/apps/web",
+        repositoryIdentity: {
+          canonicalKey: SHARED_REPO_CANONICAL_KEY,
+          rootPath: "/workspace/repo",
+          locator: {
+            source: "git-remote",
+            remoteName: "origin",
+            remoteUrl: "https://github.com/example/shared-repo.git",
+          },
+        },
+      });
+
+      expect(deriveLogicalProjectKey(rootProject)).toBe(SHARED_REPO_CANONICAL_KEY);
+      expect(deriveLogicalProjectKey(nestedProject)).toBe(SHARED_REPO_CANONICAL_KEY);
+    });
+
+    it("uses repository path grouping when requested", () => {
+      const rootProject = makeProject({
+        id: sharedProjectPrimaryId,
+        environmentId: primaryEnvId,
+        name: "shared-repo",
+        cwd: "/workspace/repo",
+        repositoryIdentity: {
+          canonicalKey: SHARED_REPO_CANONICAL_KEY,
+          rootPath: "/workspace/repo",
+          locator: {
+            source: "git-remote",
+            remoteName: "origin",
+            remoteUrl: "https://github.com/example/shared-repo.git",
+          },
+        },
+      });
+      const nestedProject = makeProject({
+        id: localOnlyProjectId,
+        environmentId: primaryEnvId,
+        name: "web",
+        cwd: "/workspace/repo/apps/web",
+        repositoryIdentity: {
+          canonicalKey: SHARED_REPO_CANONICAL_KEY,
+          rootPath: "/workspace/repo",
+          locator: {
+            source: "git-remote",
+            remoteName: "origin",
+            remoteUrl: "https://github.com/example/shared-repo.git",
+          },
+        },
+      });
+
+      expect(
+        deriveLogicalProjectKey(rootProject, {
+          groupingMode: "repository_path",
+        }),
+      ).toBe(SHARED_REPO_CANONICAL_KEY);
+      expect(
+        deriveLogicalProjectKey(nestedProject, {
+          groupingMode: "repository_path",
+        }),
+      ).toBe(`${SHARED_REPO_CANONICAL_KEY}::apps/web`);
+    });
+
+    it("groups matching nested project paths across environments when repo roots differ", () => {
+      const primary = makeProject({
+        id: sharedProjectPrimaryId,
+        environmentId: primaryEnvId,
+        name: "web",
+        cwd: "/workspace/repo/apps/web",
+        repositoryIdentity: {
+          canonicalKey: SHARED_REPO_CANONICAL_KEY,
+          rootPath: "/workspace/repo",
+          locator: {
+            source: "git-remote",
+            remoteName: "origin",
+            remoteUrl: "https://github.com/example/shared-repo.git",
+          },
+        },
+      });
+      const remote = makeProject({
+        id: sharedProjectRemoteId,
+        environmentId: remoteEnvId,
+        name: "web",
+        cwd: "/srv/checkout/apps/web",
+        repositoryIdentity: {
+          canonicalKey: SHARED_REPO_CANONICAL_KEY,
+          rootPath: "/srv/checkout",
+          locator: {
+            source: "git-remote",
+            remoteName: "origin",
+            remoteUrl: "https://github.com/example/shared-repo.git",
+          },
+        },
+      });
+
+      expect(
+        deriveLogicalProjectKey(primary, {
+          groupingMode: "repository_path",
+        }),
+      ).toBe(`${SHARED_REPO_CANONICAL_KEY}::apps/web`);
+      expect(
+        deriveLogicalProjectKey(primary, {
+          groupingMode: "repository_path",
+        }),
+      ).toBe(
+        deriveLogicalProjectKey(remote, {
+          groupingMode: "repository_path",
+        }),
+      );
+    });
+
     it("does NOT group projects without shared canonical key", () => {
       const local = makeProject({
         id: localOnlyProjectId,
@@ -286,6 +421,32 @@ describe("environment grouping", () => {
       });
       expect(deriveLogicalProjectKey(local)).not.toBe(deriveLogicalProjectKey(remote));
     });
+
+    it("uses per-project overrides from settings", () => {
+      const project = makeProject({
+        id: sharedProjectPrimaryId,
+        environmentId: primaryEnvId,
+        name: "shared-repo",
+        repositoryIdentity: {
+          canonicalKey: SHARED_REPO_CANONICAL_KEY,
+          locator: {
+            source: "git-remote",
+            remoteName: "origin",
+            remoteUrl: "https://github.com/example/shared-repo.git",
+          },
+        },
+      });
+
+      expect(resolveProjectGroupingMode(project, DEFAULT_GROUPING_SETTINGS)).toBe("repository");
+      expect(
+        deriveLogicalProjectKeyFromSettings(project, {
+          ...DEFAULT_GROUPING_SETTINGS,
+          sidebarProjectGroupingOverrides: {
+            [derivePhysicalProjectKey(project)]: "separate",
+          },
+        }),
+      ).toBe(derivePhysicalProjectKey(project));
+    });
   });
 
   describe("selectProjectsAcrossEnvironments", () => {
diff --git a/apps/web/src/environments/primary/auth.ts b/apps/web/src/environments/primary/auth.ts
index ae2d6bd64dc..9a7e39a0207 100644
--- a/apps/web/src/environments/primary/auth.ts
+++ b/apps/web/src/environments/primary/auth.ts
@@ -16,7 +16,8 @@ import {
 } from "../../pairingUrl";
 
 import { resolvePrimaryEnvironmentHttpUrl } from "./target";
-import { Data, Predicate } from "effect";
+import * as Data from "effect/Data";
+import * as Predicate from "effect/Predicate";
 
 export class BootstrapHttpError extends Data.TaggedError("BootstrapHttpError")<{
   readonly message: string;
@@ -57,6 +58,7 @@ type ServerAuthGateState =
     };
 
 let bootstrapPromise: Promise<ServerAuthGateState> | null = null;
+let resolvedAuthenticatedGateState: ServerAuthGateState | null = null;
 const AUTH_SESSION_ESTABLISH_TIMEOUT_MS = 2_000;
 const AUTH_SESSION_ESTABLISH_STEP_MS = 100;
 
@@ -109,6 +111,40 @@ async function readErrorMessage(response: Response, fallbackMessage: string): Pr
   return text || fallbackMessage;
 }
 
+const INVALID_BOOTSTRAP_CREDENTIAL_MESSAGES = new Set([
+  "Invalid bootstrap credential.",
+  "Unknown bootstrap credential.",
+]);
+
+function parseBootstrapErrorMessage(message: string): string {
+  const trimmed = message.trim();
+  if (trimmed.length === 0) {
+    return "";
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as {
+      error?: unknown;
+    };
+    if (typeof parsed.error === "string" && parsed.error.trim().length > 0) {
+      return parsed.error.trim();
+    }
+  } catch {
+    // Not JSON; fall back to plain text.
+  }
+
+  return trimmed;
+}
+
+function toFriendlyBootstrapErrorMessage(status: number, message: string): string {
+  const parsedMessage = parseBootstrapErrorMessage(message);
+  if (status === 401 && INVALID_BOOTSTRAP_CREDENTIAL_MESSAGES.has(parsedMessage)) {
+    return "Invalid pairing token. Check the token and try again.";
+  }
+
+  return parsedMessage;
+}
+
 async function exchangeBootstrapCredential(credential: string): Promise<AuthBootstrapResult> {
   return retryTransientBootstrap(async () => {
     const payload: AuthBootstrapInput = { credential };
@@ -122,7 +158,7 @@ async function exchangeBootstrapCredential(credential: string): Promise<AuthBoot
     });
 
     if (!response.ok) {
-      const message = await response.text();
+      const message = toFriendlyBootstrapErrorMessage(response.status, await response.text());
       throw new BootstrapHttpError({
         message: message || `Failed to bootstrap auth session (${response.status}).`,
         status: response.status,
@@ -224,6 +260,7 @@ export async function submitServerAuthCredential(credential: string): Promise<vo
     throw new Error("Enter a pairing token to continue.");
   }
 
+  resolvedAuthenticatedGateState = null;
   await exchangeBootstrapCredential(trimmedCredential);
   bootstrapPromise = null;
   stripPairingTokenFromUrl();
@@ -341,19 +378,31 @@ export async function revokeOtherServerClientSessions(): Promise<number> {
 }
 
 export async function resolveInitialServerAuthGateState(): Promise<ServerAuthGateState> {
+  if (resolvedAuthenticatedGateState?.status === "authenticated") {
+    return resolvedAuthenticatedGateState;
+  }
+
   if (bootstrapPromise) {
     return bootstrapPromise;
   }
 
   const nextPromise = bootstrapServerAuth();
   bootstrapPromise = nextPromise;
-  return nextPromise.finally(() => {
-    if (bootstrapPromise === nextPromise) {
-      bootstrapPromise = null;
-    }
-  });
+  return nextPromise
+    .then((result) => {
+      if (result.status === "authenticated") {
+        resolvedAuthenticatedGateState = result;
+      }
+      return result;
+    })
+    .finally(() => {
+      if (bootstrapPromise === nextPromise) {
+        bootstrapPromise = null;
+      }
+    });
 }
 
 export function __resetServerAuthBootstrapForTests() {
   bootstrapPromise = null;
+  resolvedAuthenticatedGateState = null;
 }
diff --git a/apps/web/src/environments/remote/api.test.ts b/apps/web/src/environments/remote/api.test.ts
index bbff762412f..d760714d8ec 100644
--- a/apps/web/src/environments/remote/api.test.ts
+++ b/apps/web/src/environments/remote/api.test.ts
@@ -48,6 +48,19 @@ describe("remote environment api", () => {
     });
   });
 
+  it("derives backend urls and token from a hosted app pairing link", () => {
+    expect(
+      resolveRemotePairingTarget({
+        pairingUrl:
+          "https://app.t3.codes/pair?host=https%3A%2F%2Fdesktop.tailnet.ts.net%3A44342%2F#token=pairing-token",
+      }),
+    ).toEqual({
+      credential: "pairing-token",
+      httpBaseUrl: "https://desktop.tailnet.ts.net:44342/",
+      wsBaseUrl: "wss://desktop.tailnet.ts.net:44342/",
+    });
+  });
+
   it("derives backend urls from a host and pairing code", () => {
     expect(
       resolveRemotePairingTarget({
diff --git a/apps/web/src/environments/remote/api.ts b/apps/web/src/environments/remote/api.ts
index 50b593975d3..5d56a0b4204 100644
--- a/apps/web/src/environments/remote/api.ts
+++ b/apps/web/src/environments/remote/api.ts
@@ -15,6 +15,12 @@ class RemoteEnvironmentAuthHttpError extends Error {
   }
 }
 
+export function isRemoteEnvironmentAuthHttpError(
+  error: unknown,
+): error is RemoteEnvironmentAuthHttpError {
+  return error instanceof RemoteEnvironmentAuthHttpError;
+}
+
 function remoteEndpointUrl(httpBaseUrl: string, pathname: string): string {
   const url = new URL(httpBaseUrl);
   url.pathname = pathname;
diff --git a/apps/web/src/environments/remote/target.ts b/apps/web/src/environments/remote/target.ts
index 311450d5faf..ad925f014c6 100644
--- a/apps/web/src/environments/remote/target.ts
+++ b/apps/web/src/environments/remote/target.ts
@@ -1,4 +1,5 @@
 import { getPairingTokenFromUrl } from "../../pairingUrl";
+import { readHostedPairingRequest } from "../../hostedPairing";
 
 export interface ResolvedRemotePairingTarget {
   readonly credential: string;
@@ -57,6 +58,16 @@ export function resolveRemotePairingTarget(input: {
   const pairingUrl = input.pairingUrl?.trim() ?? "";
   if (pairingUrl.length > 0) {
     const url = new URL(pairingUrl, window.location.origin);
+    const hostedPairingRequest = readHostedPairingRequest(url);
+    if (hostedPairingRequest) {
+      const hostedBackendUrl = normalizeRemoteBaseUrl(hostedPairingRequest.host);
+      return {
+        credential: hostedPairingRequest.token,
+        httpBaseUrl: toHttpBaseUrl(hostedBackendUrl),
+        wsBaseUrl: toWsBaseUrl(hostedBackendUrl),
+      };
+    }
+
     const credential = getPairingTokenFromUrl(url) ?? "";
     if (!credential) {
       throw new Error("Pairing URL is missing its token.");
diff --git a/apps/web/src/environments/runtime/catalog.ts b/apps/web/src/environments/runtime/catalog.ts
index 6aecf80f804..7ece1ccb0ca 100644
--- a/apps/web/src/environments/runtime/catalog.ts
+++ b/apps/web/src/environments/runtime/catalog.ts
@@ -18,6 +18,7 @@ export interface SavedEnvironmentRecord {
   readonly httpBaseUrl: string;
   readonly createdAt: string;
   readonly lastConnectedAt: string | null;
+  readonly desktopSsh?: PersistedSavedEnvironmentRecord["desktopSsh"];
 }
 
 interface SavedEnvironmentRegistryState {
@@ -28,13 +29,14 @@ interface SavedEnvironmentRegistryStore extends SavedEnvironmentRegistryState {
   readonly upsert: (record: SavedEnvironmentRecord) => void;
   readonly remove: (environmentId: EnvironmentId) => void;
   readonly markConnected: (environmentId: EnvironmentId, connectedAt: string) => void;
+  readonly rename: (environmentId: EnvironmentId, label: string) => void;
   readonly reset: () => void;
 }
 
 let savedEnvironmentRegistryHydrated = false;
 let savedEnvironmentRegistryHydrationPromise: Promise<void> | null = null;
 
-function toPersistedSavedEnvironmentRecord(
+export function toPersistedSavedEnvironmentRecord(
   record: SavedEnvironmentRecord,
 ): PersistedSavedEnvironmentRecord {
   return {
@@ -44,6 +46,7 @@ function toPersistedSavedEnvironmentRecord(
     wsBaseUrl: record.wsBaseUrl,
     createdAt: record.createdAt,
     lastConnectedAt: record.lastConnectedAt,
+    ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
   };
 }
 
@@ -148,6 +151,23 @@ export const useSavedEnvironmentRegistryStore = create<SavedEnvironmentRegistryS
       persistSavedEnvironmentRegistryState(byId);
       return { byId };
     }),
+  rename: (environmentId, label) =>
+    set((state) => {
+      const existing = state.byId[environmentId];
+      const nextLabel = label.trim();
+      if (!existing || nextLabel.length === 0 || existing.label === nextLabel) {
+        return state;
+      }
+      const byId = {
+        ...state.byId,
+        [environmentId]: {
+          ...existing,
+          label: nextLabel,
+        },
+      };
+      persistSavedEnvironmentRegistryState(byId);
+      return { byId };
+    }),
   reset: () => {
     persistSavedEnvironmentRegistryState({});
     set({
diff --git a/apps/web/src/environments/runtime/connection.test.ts b/apps/web/src/environments/runtime/connection.test.ts
index 4dc65015497..c490795d233 100644
--- a/apps/web/src/environments/runtime/connection.test.ts
+++ b/apps/web/src/environments/runtime/connection.test.ts
@@ -4,43 +4,32 @@ import { describe, expect, it, vi } from "vitest";
 import { createEnvironmentConnection } from "./connection";
 import type { WsRpcClient } from "~/rpc/wsRpcClient";
 
-function createTestClient(options?: {
-  readonly getSnapshot?: () => Promise<{ readonly snapshotSequence: number }>;
-  readonly replayEvents?: () => Promise<ReadonlyArray<any>>;
-}) {
+function createTestClient() {
   const lifecycleListeners = new Set<(event: any) => void>();
   const configListeners = new Set<(event: any) => void>();
   const terminalListeners = new Set<(event: any) => void>();
-  let domainResubscribe: (() => void) | undefined;
-
-  const getSnapshot = vi.fn(
-    options?.getSnapshot ??
-      (async () =>
-        ({
-          snapshotSequence: 1,
-          projects: [],
-          threads: [],
-        }) as any),
-  );
-  const replayEvents = vi.fn(options?.replayEvents ?? (async () => []));
+  const shellListeners = new Set<(event: any) => void>();
+  let shellResubscribe: (() => void) | undefined;
 
   const client = {
     dispose: vi.fn(async () => undefined),
-    reconnect: vi.fn(async () => undefined),
+    reconnect: vi.fn(async () => {
+      shellResubscribe?.();
+    }),
     server: {
       getConfig: vi.fn(async () => ({
         environment: {
           environmentId: EnvironmentId.make("env-1"),
         },
       })),
-      subscribeConfig: (listener: (event: any) => void) => {
+      subscribeConfig: vi.fn((listener: (event: any) => void) => {
         configListeners.add(listener);
         return () => configListeners.delete(listener);
-      },
-      subscribeLifecycle: (listener: (event: any) => void) => {
+      }),
+      subscribeLifecycle: vi.fn((listener: (event: any) => void) => {
         lifecycleListeners.add(listener);
         return () => lifecycleListeners.delete(listener);
-      },
+      }),
       subscribeAuthAccess: () => () => undefined,
       refreshProviders: vi.fn(async () => undefined),
       upsertKeybinding: vi.fn(async () => undefined),
@@ -48,19 +37,33 @@ function createTestClient(options?: {
       updateSettings: vi.fn(async () => undefined),
     },
     orchestration: {
-      getSnapshot,
       dispatchCommand: vi.fn(async () => undefined),
       getTurnDiff: vi.fn(async () => undefined),
       getFullThreadDiff: vi.fn(async () => undefined),
-      replayEvents,
-      onDomainEvent: vi.fn((_: (event: any) => void, options?: { onResubscribe?: () => void }) => {
-        domainResubscribe = options?.onResubscribe;
-        return () => {
-          if (domainResubscribe === options?.onResubscribe) {
-            domainResubscribe = undefined;
-          }
-        };
-      }),
+      subscribeShell: vi.fn(
+        (listener: (event: any) => void, options?: { onResubscribe?: () => void }) => {
+          shellListeners.add(listener);
+          shellResubscribe = options?.onResubscribe;
+          queueMicrotask(() => {
+            listener({
+              kind: "snapshot",
+              snapshot: {
+                snapshotSequence: 1,
+                projects: [],
+                threads: [],
+                updatedAt: "2026-04-12T00:00:00.000Z",
+              },
+            });
+          });
+          return () => {
+            shellListeners.delete(listener);
+            if (shellResubscribe === options?.onResubscribe) {
+              shellResubscribe = undefined;
+            }
+          };
+        },
+      ),
+      subscribeThread: vi.fn(() => () => undefined),
     },
     terminal: {
       open: vi.fn(async () => undefined),
@@ -82,16 +85,7 @@ function createTestClient(options?: {
       openInEditor: vi.fn(async () => undefined),
     },
     git: {
-      pull: vi.fn(async () => undefined),
-      refreshStatus: vi.fn(async () => undefined),
-      onStatus: vi.fn(() => () => undefined),
       runStackedAction: vi.fn(async () => ({}) as any),
-      listBranches: vi.fn(async () => []),
-      createWorktree: vi.fn(async () => undefined),
-      removeWorktree: vi.fn(async () => undefined),
-      createBranch: vi.fn(async () => undefined),
-      checkout: vi.fn(async () => undefined),
-      init: vi.fn(async () => undefined),
       resolvePullRequest: vi.fn(async () => undefined),
       preparePullRequestThread: vi.fn(async () => undefined),
     },
@@ -99,8 +93,6 @@ function createTestClient(options?: {
 
   return {
     client,
-    getSnapshot,
-    replayEvents,
     emitWelcome: (environmentId: EnvironmentId) => {
       for (const listener of lifecycleListeners) {
         listener({
@@ -125,17 +117,27 @@ function createTestClient(options?: {
         });
       }
     },
-    triggerDomainResubscribe: () => {
-      domainResubscribe?.();
+    emitShellSnapshot: (snapshotSequence: number) => {
+      for (const listener of shellListeners) {
+        listener({
+          kind: "snapshot",
+          snapshot: {
+            snapshotSequence,
+            projects: [],
+            threads: [],
+            updatedAt: "2026-04-12T00:00:00.000Z",
+          },
+        });
+      }
     },
   };
 }
 
 describe("createEnvironmentConnection", () => {
-  it("bootstraps a snapshot immediately for a new connection", async () => {
+  it("bootstraps from the shell subscription snapshot", async () => {
     const environmentId = EnvironmentId.make("env-1");
-    const { client, getSnapshot } = createTestClient();
-    const syncSnapshot = vi.fn();
+    const { client } = createTestClient();
+    const syncShellSnapshot = vi.fn();
 
     const connection = createEnvironmentConnection({
       kind: "saved",
@@ -150,16 +152,14 @@ describe("createEnvironmentConnection", () => {
         environmentId,
       },
       client,
-      applyEventBatch: vi.fn(),
-      syncSnapshot,
+      applyShellEvent: vi.fn(),
+      syncShellSnapshot,
       applyTerminalEvent: vi.fn(),
     });
 
-    await Promise.resolve();
-    await Promise.resolve();
+    await connection.ensureBootstrapped();
 
-    expect(getSnapshot).toHaveBeenCalledTimes(1);
-    expect(syncSnapshot).toHaveBeenCalledWith(
+    expect(syncShellSnapshot).toHaveBeenCalledWith(
       expect.objectContaining({ snapshotSequence: 1 }),
       environmentId,
     );
@@ -184,8 +184,8 @@ describe("createEnvironmentConnection", () => {
         environmentId,
       },
       client,
-      applyEventBatch: vi.fn(),
-      syncSnapshot: vi.fn(),
+      applyShellEvent: vi.fn(),
+      syncShellSnapshot: vi.fn(),
       applyTerminalEvent: vi.fn(),
     });
 
@@ -196,14 +196,10 @@ describe("createEnvironmentConnection", () => {
     await connection.dispose();
   });
 
-  it("rejects ensureBootstrapped when snapshot recovery fails", async () => {
+  it("waits for a fresh shell snapshot after reconnect", async () => {
     const environmentId = EnvironmentId.make("env-1");
-    const snapshotError = new Error("snapshot failed");
-    const { client } = createTestClient({
-      getSnapshot: async () => {
-        throw snapshotError;
-      },
-    });
+    const { client, emitShellSnapshot } = createTestClient();
+    const syncShellSnapshot = vi.fn();
 
     const connection = createEnvironmentConnection({
       kind: "saved",
@@ -218,101 +214,39 @@ describe("createEnvironmentConnection", () => {
         environmentId,
       },
       client,
-      applyEventBatch: vi.fn(),
-      syncSnapshot: vi.fn(),
+      applyShellEvent: vi.fn(),
+      syncShellSnapshot,
       applyTerminalEvent: vi.fn(),
     });
 
-    await expect(connection.ensureBootstrapped()).rejects.toThrow("snapshot failed");
-
-    await connection.dispose();
-  });
-
-  it("retries replay recovery after transport disconnects during resubscribe", async () => {
-    const environmentId = EnvironmentId.make("env-1");
-    let replayAttempts = 0;
-    const applyEventBatch = vi.fn();
-    const { client, replayEvents, triggerDomainResubscribe } = createTestClient({
-      replayEvents: async () => {
-        replayAttempts += 1;
-        if (replayAttempts === 1) {
-          throw new Error("SocketCloseError: 1006");
-        }
+    await connection.ensureBootstrapped();
 
-        return [
-          {
-            sequence: 2,
-            type: "thread.created",
-            payload: {},
-          },
-        ];
-      },
-    });
-
-    const connection = createEnvironmentConnection({
-      kind: "saved",
-      knownEnvironment: {
-        id: "env-1",
-        label: "Remote env",
-        source: "manual",
-        target: {
-          httpBaseUrl: "http://example.test",
-          wsBaseUrl: "ws://example.test",
-        },
-        environmentId,
-      },
-      client,
-      applyEventBatch,
-      syncSnapshot: vi.fn(),
-      applyTerminalEvent: vi.fn(),
-    });
-
-    await Promise.resolve();
+    const reconnectPromise = connection.reconnect();
     await Promise.resolve();
+    expect(syncShellSnapshot).toHaveBeenCalledTimes(1);
 
-    triggerDomainResubscribe();
+    emitShellSnapshot(2);
+    await reconnectPromise;
 
-    await vi.waitFor(() => {
-      expect(replayEvents).toHaveBeenCalledTimes(2);
-      expect(applyEventBatch).toHaveBeenCalledWith(
-        [
-          expect.objectContaining({
-            sequence: 2,
-          }),
-        ],
-        environmentId,
-      );
-    });
+    expect(client.reconnect).toHaveBeenCalledTimes(1);
+    expect(syncShellSnapshot).toHaveBeenCalledTimes(2);
+    expect(syncShellSnapshot).toHaveBeenLastCalledWith(
+      expect.objectContaining({ snapshotSequence: 2 }),
+      environmentId,
+    );
 
     await connection.dispose();
   });
-  it("swallows replay recovery failures triggered by resubscribe", async () => {
-    const environmentId = EnvironmentId.make("env-1");
-    const snapshotError = new Error("snapshot failed");
-    let snapshotCalls = 0;
-    const { client, triggerDomainResubscribe } = createTestClient({
-      getSnapshot: async () => {
-        snapshotCalls += 1;
-        if (snapshotCalls === 1) {
-          return {
-            snapshotSequence: 1,
-            projects: [],
-            threads: [],
-          } as any;
-        }
 
-        throw snapshotError;
-      },
-      replayEvents: async () => {
-        throw new Error("SocketCloseError: 1006");
-      },
-    });
+  it("skips primary lifecycle/config subscriptions when no handlers are registered", async () => {
+    const environmentId = EnvironmentId.make("env-1");
+    const { client } = createTestClient();
 
     const connection = createEnvironmentConnection({
-      kind: "saved",
+      kind: "primary",
       knownEnvironment: {
         id: "env-1",
-        label: "Remote env",
+        label: "Local env",
         source: "manual",
         target: {
           httpBaseUrl: "http://example.test",
@@ -321,26 +255,14 @@ describe("createEnvironmentConnection", () => {
         environmentId,
       },
       client,
-      applyEventBatch: vi.fn(),
-      syncSnapshot: vi.fn(),
+      applyShellEvent: vi.fn(),
+      syncShellSnapshot: vi.fn(),
       applyTerminalEvent: vi.fn(),
     });
 
-    await Promise.resolve();
-    await Promise.resolve();
-
-    const onUnhandledRejection = vi.fn();
-    process.on("unhandledRejection", onUnhandledRejection);
-
-    try {
-      triggerDomainResubscribe();
-      await new Promise((resolve) => setTimeout(resolve, 0));
-      await new Promise((resolve) => setTimeout(resolve, 0));
-    } finally {
-      process.off("unhandledRejection", onUnhandledRejection);
-    }
-
-    expect(onUnhandledRejection).not.toHaveBeenCalled();
+    expect(client.server.subscribeLifecycle).not.toHaveBeenCalled();
+    expect(client.server.subscribeConfig).not.toHaveBeenCalled();
+    expect(client.orchestration.subscribeShell).toHaveBeenCalledOnce();
 
     await connection.dispose();
   });
diff --git a/apps/web/src/environments/runtime/connection.ts b/apps/web/src/environments/runtime/connection.ts
index ef79d3fce6c..beacf6144da 100644
--- a/apps/web/src/environments/runtime/connection.ts
+++ b/apps/web/src/environments/runtime/connection.ts
@@ -1,29 +1,15 @@
 import type {
   EnvironmentId,
-  OrchestrationEvent,
-  OrchestrationReadModel,
+  OrchestrationShellSnapshot,
+  OrchestrationShellStreamEvent,
   ServerConfig,
   ServerLifecycleWelcomePayload,
   TerminalEvent,
 } from "@t3tools/contracts";
 import type { KnownEnvironment } from "@t3tools/client-runtime";
 
-import {
-  deriveReplayRetryDecision,
-  type OrchestrationRecoveryReason,
-} from "../../orchestrationRecovery";
-import {
-  createOrchestrationRecoveryCoordinator,
-  type ReplayRetryTracker,
-} from "../../orchestrationRecovery";
-import { isTransportConnectionErrorMessage } from "~/rpc/transportError";
 import type { WsRpcClient } from "~/rpc/wsRpcClient";
 
-const REPLAY_RECOVERY_RETRY_DELAY_MS = 100;
-const MAX_NO_PROGRESS_REPLAY_RETRIES = 3;
-const RECOVERY_TRANSPORT_RETRY_DELAY_MS = 250;
-const MAX_RECOVERY_TRANSPORT_RETRIES = 20;
-
 export interface EnvironmentConnection {
   readonly kind: "primary" | "saved";
   readonly environmentId: EnvironmentId;
@@ -35,11 +21,14 @@ export interface EnvironmentConnection {
 }
 
 interface OrchestrationHandlers {
-  readonly applyEventBatch: (
-    events: ReadonlyArray<OrchestrationEvent>,
+  readonly applyShellEvent: (
+    event: OrchestrationShellStreamEvent,
+    environmentId: EnvironmentId,
+  ) => void;
+  readonly syncShellSnapshot: (
+    snapshot: OrchestrationShellSnapshot,
     environmentId: EnvironmentId,
   ) => void;
-  readonly syncSnapshot: (snapshot: OrchestrationReadModel, environmentId: EnvironmentId) => void;
   readonly applyTerminalEvent: (event: TerminalEvent, environmentId: EnvironmentId) => void;
 }
 
@@ -52,33 +41,31 @@ interface EnvironmentConnectionInput extends OrchestrationHandlers {
   readonly onWelcome?: (payload: ServerLifecycleWelcomePayload) => void;
 }
 
-function createSnapshotBootstrapController(input: {
-  readonly isBootstrapped: () => boolean;
-  readonly runSnapshotRecovery: (
-    reason: Extract<OrchestrationRecoveryReason, "bootstrap" | "replay-failed">,
-  ) => Promise<void>;
-}) {
-  let inFlight: Promise<void> | null = null;
+function createBootstrapGate() {
+  let resolve: (() => void) | null = null;
+  let reject: ((error: unknown) => void) | null = null;
+  let promise = new Promise<void>((nextResolve, nextReject) => {
+    resolve = nextResolve;
+    reject = nextReject;
+  });
 
   return {
-    ensureSnapshotRecovery(
-      reason: Extract<OrchestrationRecoveryReason, "bootstrap" | "replay-failed">,
-    ): Promise<void> {
-      if (input.isBootstrapped()) {
-        return Promise.resolve();
-      }
-
-      if (inFlight !== null) {
-        return inFlight;
-      }
-
-      const nextInFlight = input.runSnapshotRecovery(reason).finally(() => {
-        if (inFlight === nextInFlight) {
-          inFlight = null;
-        }
+    wait: () => promise,
+    resolve: () => {
+      resolve?.();
+      resolve = null;
+      reject = null;
+    },
+    reject: (error: unknown) => {
+      reject?.(error);
+      resolve = null;
+      reject = null;
+    },
+    reset: () => {
+      promise = new Promise<void>((nextResolve, nextReject) => {
+        resolve = nextResolve;
+        reject = nextReject;
       });
-      inFlight = nextInFlight;
-      return inFlight;
     },
   };
 }
@@ -86,10 +73,6 @@ function createSnapshotBootstrapController(input: {
 export function createEnvironmentConnection(
   input: EnvironmentConnectionInput,
 ): EnvironmentConnection {
-  const recovery = createOrchestrationRecoveryCoordinator();
-  let replayRetryTracker: ReplayRetryTracker | null = null;
-  const pendingDomainEvents: OrchestrationEvent[] = [];
-  let flushPendingDomainEventsScheduled = false;
   const environmentId = input.knownEnvironment.environmentId;
 
   if (!environmentId) {
@@ -99,6 +82,9 @@ export function createEnvironmentConnection(
   }
 
   let disposed = false;
+  const bootstrapGate = createBootstrapGate();
+  const shouldObserveLifecycle = input.kind === "saved" || input.onWelcome !== undefined;
+  const shouldObserveConfig = input.kind === "saved" || input.onConfigSnapshot !== undefined;
 
   const observeEnvironmentIdentity = (nextEnvironmentId: EnvironmentId, source: string) => {
     if (environmentId !== nextEnvironmentId) {
@@ -108,191 +94,51 @@ export function createEnvironmentConnection(
     }
   };
 
-  const flushPendingDomainEvents = () => {
-    flushPendingDomainEventsScheduled = false;
-    if (disposed || pendingDomainEvents.length === 0) {
-      return;
-    }
-
-    const events = pendingDomainEvents.splice(0, pendingDomainEvents.length);
-    const nextEvents = recovery.markEventBatchApplied(events);
-    if (nextEvents.length === 0) {
-      return;
-    }
-    input.applyEventBatch(nextEvents, environmentId);
-  };
-
-  const schedulePendingDomainEventFlush = () => {
-    if (flushPendingDomainEventsScheduled) {
-      return;
-    }
-
-    flushPendingDomainEventsScheduled = true;
-    queueMicrotask(flushPendingDomainEvents);
-  };
-
-  const retryTransportRecoveryOperation = async <T>(operation: () => Promise<T>): Promise<T> => {
-    for (let attempt = 0; ; attempt += 1) {
-      try {
-        return await operation();
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (
-          disposed ||
-          !isTransportConnectionErrorMessage(message) ||
-          attempt >= MAX_RECOVERY_TRANSPORT_RETRIES - 1
-        ) {
-          throw error;
-        }
-
-        await new Promise<void>((resolve) => {
-          setTimeout(resolve, RECOVERY_TRANSPORT_RETRY_DELAY_MS);
-        });
-
-        if (disposed) {
-          throw error;
-        }
-      }
-    }
-  };
-  const scheduleReplayRecovery = (reason: "sequence-gap" | "resubscribe") => {
-    void runReplayRecovery(reason).catch(() => undefined);
-  };
-
-  const runReplayRecovery = async (reason: "sequence-gap" | "resubscribe"): Promise<void> => {
-    if (!recovery.beginReplayRecovery(reason)) {
-      return;
-    }
-
-    const fromSequenceExclusive = recovery.getState().latestSequence;
-    try {
-      const events = await retryTransportRecoveryOperation(() =>
-        input.client.orchestration.replayEvents({ fromSequenceExclusive }),
-      );
-      if (!disposed) {
-        const nextEvents = recovery.markEventBatchApplied(events);
-        if (nextEvents.length > 0) {
-          input.applyEventBatch(nextEvents, environmentId);
-        }
-      }
-    } catch {
-      replayRetryTracker = null;
-      recovery.failReplayRecovery();
-      if (disposed) {
-        return;
-      }
-      await snapshotBootstrap.ensureSnapshotRecovery("replay-failed");
-      return;
-    }
-
-    if (disposed) {
-      return;
-    }
-
-    const replayCompletion = recovery.completeReplayRecovery();
-    const retryDecision = deriveReplayRetryDecision({
-      previousTracker: replayRetryTracker,
-      completion: replayCompletion,
-      recoveryState: recovery.getState(),
-      baseDelayMs: REPLAY_RECOVERY_RETRY_DELAY_MS,
-      maxNoProgressRetries: MAX_NO_PROGRESS_REPLAY_RETRIES,
-    });
-    replayRetryTracker = retryDecision.tracker;
-
-    if (retryDecision.shouldRetry) {
-      if (retryDecision.delayMs > 0) {
-        await new Promise<void>((resolve) => {
-          setTimeout(resolve, retryDecision.delayMs);
-        });
-        if (disposed) {
-          return;
-        }
-      }
-      scheduleReplayRecovery(reason);
-    } else if (replayCompletion.shouldReplay && import.meta.env.MODE !== "test") {
-      console.warn(
-        "[orchestration-recovery]",
-        "Stopping replay recovery after no-progress retries.",
-        {
-          environmentId,
-          state: recovery.getState(),
+  const unsubLifecycle = shouldObserveLifecycle
+    ? input.client.server.subscribeLifecycle(
+        (event: Parameters<Parameters<WsRpcClient["server"]["subscribeLifecycle"]>[0]>[0]) => {
+          if (event.type !== "welcome") {
+            return;
+          }
+          observeEnvironmentIdentity(
+            event.payload.environment.environmentId,
+            "server lifecycle welcome",
+          );
+          input.onWelcome?.(event.payload);
         },
-      );
-    }
-  };
-
-  const runSnapshotRecovery = async (
-    reason: Extract<OrchestrationRecoveryReason, "bootstrap" | "replay-failed">,
-  ): Promise<void> => {
-    const started = recovery.beginSnapshotRecovery(reason);
-    if (!started) {
-      return;
-    }
-
-    try {
-      const snapshot = await retryTransportRecoveryOperation(() =>
-        input.client.orchestration.getSnapshot(),
-      );
-      if (!disposed) {
-        input.syncSnapshot(snapshot, environmentId);
-        if (recovery.completeSnapshotRecovery(snapshot.snapshotSequence)) {
-          scheduleReplayRecovery("sequence-gap");
-        }
-      }
-    } catch (error) {
-      recovery.failSnapshotRecovery();
-      throw error;
-    }
-  };
-
-  const snapshotBootstrap = createSnapshotBootstrapController({
-    isBootstrapped: () => recovery.getState().bootstrapped,
-    runSnapshotRecovery,
-  });
-
-  const unsubLifecycle = input.client.server.subscribeLifecycle(
-    (event: Parameters<Parameters<WsRpcClient["server"]["subscribeLifecycle"]>[0]>[0]) => {
-      if (event.type !== "welcome") {
-        return;
-      }
-      observeEnvironmentIdentity(
-        event.payload.environment.environmentId,
-        "server lifecycle welcome",
-      );
-      input.onWelcome?.(event.payload);
-    },
-  );
-
-  const unsubConfig = input.client.server.subscribeConfig(
-    (event: Parameters<Parameters<WsRpcClient["server"]["subscribeConfig"]>[0]>[0]) => {
-      if (event.type !== "snapshot") {
-        return;
-      }
-      observeEnvironmentIdentity(event.config.environment.environmentId, "server config snapshot");
-      input.onConfigSnapshot?.(event.config);
-    },
-  );
-
-  const unsubDomainEvent = input.client.orchestration.onDomainEvent(
-    (event: Parameters<Parameters<WsRpcClient["orchestration"]["onDomainEvent"]>[0]>[0]) => {
-      const action = recovery.classifyDomainEvent(event.sequence);
-      if (action === "apply") {
-        pendingDomainEvents.push(event);
-        schedulePendingDomainEventFlush();
+      )
+    : () => undefined;
+
+  const unsubConfig = shouldObserveConfig
+    ? input.client.server.subscribeConfig(
+        (event: Parameters<Parameters<WsRpcClient["server"]["subscribeConfig"]>[0]>[0]) => {
+          if (event.type !== "snapshot") {
+            return;
+          }
+          observeEnvironmentIdentity(
+            event.config.environment.environmentId,
+            "server config snapshot",
+          );
+          input.onConfigSnapshot?.(event.config);
+        },
+      )
+    : () => undefined;
+
+  const unsubShell = input.client.orchestration.subscribeShell(
+    (item: Parameters<Parameters<WsRpcClient["orchestration"]["subscribeShell"]>[0]>[0]) => {
+      if (item.kind === "snapshot") {
+        input.syncShellSnapshot(item.snapshot, environmentId);
+        bootstrapGate.resolve();
         return;
       }
-      if (action === "recover") {
-        flushPendingDomainEvents();
-        scheduleReplayRecovery("sequence-gap");
-      }
+      input.applyShellEvent(item, environmentId);
     },
     {
       onResubscribe: () => {
         if (disposed) {
           return;
         }
-        flushPendingDomainEvents();
-        scheduleReplayRecovery("resubscribe");
+        bootstrapGate.reset();
       },
     },
   );
@@ -303,13 +149,9 @@ export function createEnvironmentConnection(
     },
   );
 
-  void snapshotBootstrap.ensureSnapshotRecovery("bootstrap").catch(() => undefined);
-
   const cleanup = () => {
     disposed = true;
-    flushPendingDomainEventsScheduled = false;
-    pendingDomainEvents.length = 0;
-    unsubDomainEvent();
+    unsubShell();
     unsubTerminalEvent();
     unsubLifecycle();
     unsubConfig();
@@ -320,11 +162,17 @@ export function createEnvironmentConnection(
     environmentId,
     knownEnvironment: input.knownEnvironment,
     client: input.client,
-    ensureBootstrapped: () => snapshotBootstrap.ensureSnapshotRecovery("bootstrap"),
+    ensureBootstrapped: () => bootstrapGate.wait(),
     reconnect: async () => {
-      await input.client.reconnect();
-      await input.refreshMetadata?.();
-      await snapshotBootstrap.ensureSnapshotRecovery("bootstrap");
+      bootstrapGate.reset();
+      try {
+        await input.client.reconnect();
+        await input.refreshMetadata?.();
+        await bootstrapGate.wait();
+      } catch (error) {
+        bootstrapGate.reject(error);
+        throw error;
+      }
     },
     dispose: async () => {
       cleanup();
diff --git a/apps/web/src/environments/runtime/index.ts b/apps/web/src/environments/runtime/index.ts
index 8c813f10826..0192fb6026d 100644
--- a/apps/web/src/environments/runtime/index.ts
+++ b/apps/web/src/environments/runtime/index.ts
@@ -16,6 +16,7 @@ export {
 
 export {
   addSavedEnvironment,
+  connectDesktopSshEnvironment,
   disconnectSavedEnvironment,
   ensureEnvironmentConnectionBootstrapped,
   getPrimaryEnvironmentConnection,
diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index 9bcbc4f7133..04aa11e86d1 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -1,14 +1,60 @@
 import { EnvironmentId } from "@t3tools/contracts";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+let mockSavedRecords: Array<Record<string, unknown>> = [];
 
 const mockResolveRemotePairingTarget = vi.fn();
 const mockFetchRemoteEnvironmentDescriptor = vi.fn();
 const mockBootstrapRemoteBearerSession = vi.fn();
+const mockFetchRemoteSessionState = vi.fn();
+const mockIsRemoteEnvironmentAuthHttpError = vi.fn((_: unknown) => false);
+const mockResolveRemoteWebSocketConnectionUrl = vi.fn();
+const mockBootstrapSshBearerSession = vi.fn();
+const mockFetchSshSessionState = vi.fn();
 const mockPersistSavedEnvironmentRecord = vi.fn();
 const mockWriteSavedEnvironmentBearerToken = vi.fn();
 const mockSetSavedEnvironmentRegistry = vi.fn();
-const mockUpsert = vi.fn();
-const mockListSavedEnvironmentRecords = vi.fn();
+const mockGetSavedEnvironmentRecord = vi.fn((environmentId: EnvironmentId) => {
+  return mockSavedRecords.find((record) => record.environmentId === environmentId) ?? null;
+});
+const mockReadSavedEnvironmentBearerToken = vi.fn();
+const mockRemoveSavedEnvironmentBearerToken = vi.fn();
+const mockPatchRuntime = vi.fn();
+const mockClearRuntime = vi.fn();
+const mockRegistrySetState = vi.fn((next: { byId: Record<string, Record<string, unknown>> }) => {
+  mockSavedRecords = Object.values(next.byId);
+});
+const mockRemove = vi.fn((environmentId: EnvironmentId) => {
+  mockSavedRecords = mockSavedRecords.filter((record) => record.environmentId !== environmentId);
+});
+const mockMarkConnected = vi.fn((environmentId: EnvironmentId, connectedAt: string) => {
+  mockSavedRecords = mockSavedRecords.map((record) =>
+    record.environmentId === environmentId ? { ...record, lastConnectedAt: connectedAt } : record,
+  );
+});
+const mockRename = vi.fn((environmentId: EnvironmentId, label: string) => {
+  mockSavedRecords = mockSavedRecords.map((record) =>
+    record.environmentId === environmentId ? { ...record, label } : record,
+  );
+});
+const mockUpsert = vi.fn((record: Record<string, unknown>) => {
+  mockSavedRecords = [
+    ...mockSavedRecords.filter((entry) => entry.environmentId !== record.environmentId),
+    record,
+  ];
+});
+const mockListSavedEnvironmentRecords = vi.fn(() => mockSavedRecords);
+const mockEnsureSshEnvironment = vi.fn();
+const mockDisconnectSshEnvironment = vi.fn();
+const mockFetchSshEnvironmentDescriptor = vi.fn();
+const mockToPersistedSavedEnvironmentRecord = vi.fn((record) => record);
+const mockCreateEnvironmentConnection = vi.fn();
+const mockClientGetConfig = vi.fn(async () => ({
+  environment: {
+    environmentId: EnvironmentId.make("environment-1"),
+    label: "Remote environment",
+  },
+}));
 
 vi.mock("../remote/target", () => ({
   resolveRemotePairingTarget: mockResolveRemotePairingTarget,
@@ -17,8 +63,9 @@ vi.mock("../remote/target", () => ({
 vi.mock("../remote/api", () => ({
   bootstrapRemoteBearerSession: mockBootstrapRemoteBearerSession,
   fetchRemoteEnvironmentDescriptor: mockFetchRemoteEnvironmentDescriptor,
-  fetchRemoteSessionState: vi.fn(),
-  resolveRemoteWebSocketConnectionUrl: vi.fn(),
+  fetchRemoteSessionState: mockFetchRemoteSessionState,
+  isRemoteEnvironmentAuthHttpError: mockIsRemoteEnvironmentAuthHttpError,
+  resolveRemoteWebSocketConnectionUrl: mockResolveRemoteWebSocketConnectionUrl,
 }));
 
 vi.mock("~/localApi", () => ({
@@ -30,24 +77,28 @@ vi.mock("~/localApi", () => ({
 }));
 
 vi.mock("./catalog", () => ({
-  getSavedEnvironmentRecord: vi.fn(),
+  getSavedEnvironmentRecord: mockGetSavedEnvironmentRecord,
   hasSavedEnvironmentRegistryHydrated: vi.fn(),
   listSavedEnvironmentRecords: mockListSavedEnvironmentRecords,
   persistSavedEnvironmentRecord: mockPersistSavedEnvironmentRecord,
-  readSavedEnvironmentBearerToken: vi.fn(),
-  removeSavedEnvironmentBearerToken: vi.fn(),
+  readSavedEnvironmentBearerToken: mockReadSavedEnvironmentBearerToken,
+  removeSavedEnvironmentBearerToken: mockRemoveSavedEnvironmentBearerToken,
+  toPersistedSavedEnvironmentRecord: mockToPersistedSavedEnvironmentRecord,
   useSavedEnvironmentRegistryStore: {
     getState: () => ({
       upsert: mockUpsert,
-      remove: vi.fn(),
-      markConnected: vi.fn(),
+      remove: mockRemove,
+      markConnected: mockMarkConnected,
+      rename: mockRename,
     }),
+    setState: mockRegistrySetState,
+    subscribe: vi.fn(() => () => {}),
   },
   useSavedEnvironmentRuntimeStore: {
     getState: () => ({
       ensure: vi.fn(),
-      patch: vi.fn(),
-      clear: vi.fn(),
+      patch: mockPatchRuntime,
+      clear: mockClearRuntime,
     }),
   },
   waitForSavedEnvironmentRegistryHydration: vi.fn(),
@@ -55,18 +106,58 @@ vi.mock("./catalog", () => ({
 }));
 
 vi.mock("./connection", () => ({
-  createEnvironmentConnection: vi.fn(),
+  createEnvironmentConnection: mockCreateEnvironmentConnection,
+}));
+
+vi.mock("../../rpc/wsRpcClient", () => ({
+  createWsRpcClient: vi.fn(() => ({
+    server: {
+      getConfig: mockClientGetConfig,
+    },
+    orchestration: {
+      subscribeThread: vi.fn(() => () => {}),
+    },
+  })),
+}));
+
+vi.mock("../../rpc/wsTransport", () => ({
+  WsTransport: vi.fn(),
 }));
 
 describe("addSavedEnvironment", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   beforeEach(() => {
     vi.resetModules();
     vi.clearAllMocks();
-    mockResolveRemotePairingTarget.mockReturnValue({
-      httpBaseUrl: "https://remote.example.com/",
-      wsBaseUrl: "wss://remote.example.com/",
-      credential: "pairing-code",
+    mockSavedRecords = [];
+    vi.stubGlobal("window", {
+      desktopBridge: {
+        ensureSshEnvironment: mockEnsureSshEnvironment,
+        disconnectSshEnvironment: mockDisconnectSshEnvironment,
+        fetchSshEnvironmentDescriptor: mockFetchSshEnvironmentDescriptor,
+        bootstrapSshBearerSession: mockBootstrapSshBearerSession,
+        fetchSshSessionState: mockFetchSshSessionState,
+        issueSshWebSocketToken: vi.fn(),
+      },
     });
+    mockResolveRemotePairingTarget.mockImplementation(
+      (input: { host?: string; pairingCode?: string }) => ({
+        httpBaseUrl: input.host
+          ? input.host.endsWith("/")
+            ? input.host
+            : `${input.host}/`
+          : "https://remote.example.com/",
+        wsBaseUrl: input.host
+          ? input.host.replace(/^http/u, "ws").endsWith("/")
+            ? input.host.replace(/^http/u, "ws")
+            : `${input.host.replace(/^http/u, "ws")}/`
+          : "wss://remote.example.com/",
+        credential: input.pairingCode ?? "pairing-code",
+      }),
+    );
     mockFetchRemoteEnvironmentDescriptor.mockResolvedValue({
       environmentId: EnvironmentId.make("environment-1"),
       label: "Remote environment",
@@ -75,10 +166,60 @@ describe("addSavedEnvironment", () => {
       sessionToken: "bearer-token",
       role: "owner",
     });
+    mockFetchRemoteSessionState.mockResolvedValue({
+      authenticated: true,
+      role: "owner",
+    });
+    mockIsRemoteEnvironmentAuthHttpError.mockReturnValue(false);
+    mockResolveRemoteWebSocketConnectionUrl.mockResolvedValue(
+      "wss://remote.example.com/?wsToken=remote-token",
+    );
+    mockFetchSshEnvironmentDescriptor.mockResolvedValue({
+      environmentId: EnvironmentId.make("environment-1"),
+      label: "Remote environment",
+    });
+    mockBootstrapSshBearerSession.mockResolvedValue({
+      sessionToken: "ssh-bearer-token",
+      role: "owner",
+    });
     mockPersistSavedEnvironmentRecord.mockResolvedValue(undefined);
     mockWriteSavedEnvironmentBearerToken.mockResolvedValue(false);
     mockSetSavedEnvironmentRegistry.mockResolvedValue(undefined);
-    mockListSavedEnvironmentRecords.mockReturnValue([]);
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockRemoveSavedEnvironmentBearerToken.mockResolvedValue(undefined);
+    mockFetchSshSessionState.mockResolvedValue({
+      authenticated: true,
+      role: "owner",
+    });
+    mockCreateEnvironmentConnection.mockImplementation(
+      (input: { knownEnvironment: { environmentId: EnvironmentId }; client: unknown }) => ({
+        kind: "saved",
+        environmentId: input.knownEnvironment.environmentId,
+        knownEnvironment: input.knownEnvironment,
+        client: input.client,
+        ensureBootstrapped: async () => undefined,
+        reconnect: async () => undefined,
+        dispose: async () => undefined,
+      }),
+    );
+    mockClientGetConfig.mockResolvedValue({
+      environment: {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+      },
+    });
+    mockEnsureSshEnvironment.mockResolvedValue({
+      target: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      pairingToken: "ssh-pairing-code",
+    });
+    mockDisconnectSshEnvironment.mockResolvedValue(undefined);
   });
 
   it("rolls back persisted metadata when bearer token persistence fails", async () => {
@@ -102,4 +243,664 @@ describe("addSavedEnvironment", () => {
 
     await resetEnvironmentServiceForTests();
   });
+
+  it("restores unrelated saved environments when credential persistence rollback runs", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-existing"),
+        label: "Existing environment",
+        httpBaseUrl: "https://existing.example.com/",
+        wsBaseUrl: "wss://existing.example.com/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+      },
+    ];
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "Remote environment",
+        host: "remote.example.com",
+        pairingCode: "123456",
+      }),
+    ).rejects.toThrow("Unable to persist saved environment credentials.");
+
+    expect(mockSetSavedEnvironmentRegistry).toHaveBeenCalledWith([
+      expect.objectContaining({
+        environmentId: EnvironmentId.make("environment-existing"),
+      }),
+    ]);
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("persists the server label after saved environment metadata refresh", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockClientGetConfig.mockResolvedValue({
+      environment: {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Julius's Mac mini",
+      },
+    });
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "100.65.180.100",
+        host: "remote.example.com",
+        pairingCode: "123456",
+      }),
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-1"),
+    });
+
+    expect(mockRename).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      "Julius's Mac mini",
+    );
+    expect(mockSavedRecords).toEqual([
+      expect.objectContaining({
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Julius's Mac mini",
+      }),
+    ]);
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("removes an older ssh record when the same target returns a new environment id", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockFetchSshEnvironmentDescriptor.mockResolvedValue({
+      environmentId: EnvironmentId.make("environment-2"),
+      label: "Remote environment",
+    });
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Old ssh environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "Remote environment",
+        host: "http://127.0.0.1:3774/",
+        pairingCode: "ssh-pairing-code",
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      }),
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-2"),
+    });
+
+    expect(mockUpsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        environmentId: EnvironmentId.make("environment-2"),
+      }),
+    );
+    expect(mockRemove).toHaveBeenCalledWith(EnvironmentId.make("environment-1"));
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("retries desktop ssh session refresh when the forwarded endpoint returns ssh_http 401", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockBootstrapSshBearerSession
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token",
+        role: "owner",
+      })
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token-2",
+        role: "owner",
+      });
+    mockFetchSshSessionState
+      .mockRejectedValueOnce(new Error("[ssh_http:401] Unauthorized"))
+      .mockResolvedValueOnce({
+        authenticated: true,
+        role: "owner",
+      });
+
+    const { connectDesktopSshEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await expect(
+      connectDesktopSshEnvironment({
+        alias: "devbox",
+        hostname: "devbox",
+        username: null,
+        port: null,
+      }),
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-1"),
+    });
+
+    expect(mockEnsureSshEnvironment).toHaveBeenCalled();
+    expect(mockBootstrapSshBearerSession).toHaveBeenCalledTimes(2);
+    expect(mockFetchSshSessionState).toHaveBeenCalledTimes(2);
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("does not attempt desktop ssh bearer recovery for non-ssh saved environments", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    const authError = {
+      status: 401,
+      message: "Unauthorized",
+    };
+    mockFetchRemoteSessionState.mockRejectedValueOnce(authError);
+    mockIsRemoteEnvironmentAuthHttpError.mockImplementation(
+      (error: unknown) => error === authError,
+    );
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "Remote environment",
+        host: "remote.example.com",
+        pairingCode: "123456",
+      }),
+    ).rejects.toThrow("Saved environment credential expired. Pair it again.");
+
+    expect(mockEnsureSshEnvironment).not.toHaveBeenCalled();
+    expect(mockBootstrapSshBearerSession).not.toHaveBeenCalled();
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("only registers the retried ssh connection after bearer re-issuance succeeds", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockBootstrapSshBearerSession
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token",
+        role: "owner",
+      })
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token-2",
+        role: "owner",
+      });
+    mockFetchSshSessionState
+      .mockRejectedValueOnce(new Error("[ssh_http:401] Unauthorized"))
+      .mockResolvedValueOnce({
+        authenticated: true,
+        role: "owner",
+      });
+
+    const createdConnections: Array<{
+      readonly environmentId: EnvironmentId;
+      readonly dispose: ReturnType<typeof vi.fn>;
+    }> = [];
+    mockCreateEnvironmentConnection.mockImplementation(
+      (input: { knownEnvironment: { environmentId: EnvironmentId }; client: unknown }) => {
+        const connection = {
+          kind: "saved" as const,
+          environmentId: input.knownEnvironment.environmentId,
+          knownEnvironment: input.knownEnvironment,
+          client: input.client,
+          ensureBootstrapped: async () => undefined,
+          reconnect: async () => undefined,
+          dispose: vi.fn(async () => undefined),
+        };
+        createdConnections.push(connection);
+        return connection;
+      },
+    );
+
+    const {
+      connectDesktopSshEnvironment,
+      listEnvironmentConnections,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    await connectDesktopSshEnvironment({
+      alias: "devbox",
+      hostname: "devbox",
+      username: null,
+      port: null,
+    });
+
+    expect(createdConnections).toHaveLength(2);
+    expect(createdConnections[0]?.dispose).toHaveBeenCalledTimes(1);
+    expect(listEnvironmentConnections()).toHaveLength(1);
+    expect(listEnvironmentConnections()[0]).toBe(createdConnections[1]);
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("marks desktop ssh reconnect failures as runtime errors when bearer recovery fails", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+
+    const connection = {
+      kind: "saved" as const,
+      environmentId: EnvironmentId.make("environment-1"),
+      knownEnvironment: {
+        environmentId: EnvironmentId.make("environment-1"),
+      },
+      client: {},
+      ensureBootstrapped: async () => undefined,
+      reconnect: vi.fn(async () => {
+        throw new Error("socket closed");
+      }),
+      dispose: async () => undefined,
+    };
+    mockCreateEnvironmentConnection.mockReturnValue(connection);
+
+    const { addSavedEnvironment, reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await addSavedEnvironment({
+      label: "Remote environment",
+      host: "http://127.0.0.1:3774/",
+      pairingCode: "ssh-pairing-code",
+      desktopSsh: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+    });
+
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(false);
+
+    await expect(reconnectSavedEnvironment(EnvironmentId.make("environment-1"))).rejects.toThrow(
+      "Unable to persist saved environment credentials.",
+    );
+
+    expect(mockPatchRuntime).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "error",
+        lastError: "Unable to persist saved environment credentials.",
+      }),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("bootstraps a desktop ssh environment through the desktop bridge", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+
+    const { connectDesktopSshEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await expect(
+      connectDesktopSshEnvironment({
+        alias: "devbox",
+        hostname: "devbox",
+        username: null,
+        port: null,
+      }),
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-1"),
+    });
+
+    expect(mockEnsureSshEnvironment).toHaveBeenCalledWith(
+      {
+        alias: "devbox",
+        hostname: "devbox",
+        username: null,
+        port: null,
+      },
+      { issuePairingToken: true },
+    );
+    expect(mockResolveRemotePairingTarget).toHaveBeenCalledWith({
+      host: "http://127.0.0.1:3774/",
+      pairingCode: "ssh-pairing-code",
+    });
+    expect(mockFetchSshEnvironmentDescriptor).toHaveBeenCalledWith("http://127.0.0.1:3774/");
+    expect(mockBootstrapSshBearerSession).toHaveBeenCalledWith(
+      "http://127.0.0.1:3774/",
+      "ssh-pairing-code",
+    );
+    expect(mockFetchRemoteEnvironmentDescriptor).not.toHaveBeenCalled();
+    expect(mockBootstrapRemoteBearerSession).not.toHaveBeenCalled();
+    expect(mockUpsert.mock.invocationCallOrder[0]).toBeLessThan(
+      mockCreateEnvironmentConnection.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("disconnects the desktop ssh process before removing a saved ssh environment", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+
+    const { removeSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await removeSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockDisconnectSshEnvironment).toHaveBeenCalledWith({
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 22,
+    });
+    expect(mockRemove).toHaveBeenCalledWith(EnvironmentId.make("environment-1"));
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+    expect(mockDisconnectSshEnvironment.mock.invocationCallOrder[0]).toBeLessThan(
+      mockRemove.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("disconnects a saved ssh environment without removing its saved record", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+
+    const { disconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await disconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockDisconnectSshEnvironment).toHaveBeenCalledWith({
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 22,
+    });
+    expect(mockRemove).not.toHaveBeenCalled();
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("keeps remote environment credentials when disconnecting a non-ssh saved environment", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "https://remote.example.com/",
+        wsBaseUrl: "wss://remote.example.com/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+      },
+    ];
+
+    const { disconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await disconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockDisconnectSshEnvironment).not.toHaveBeenCalled();
+    expect(mockRemove).not.toHaveBeenCalled();
+    expect(mockRemoveSavedEnvironmentBearerToken).not.toHaveBeenCalled();
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("cancels a pending saved environment connection when disconnected", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "https://remote.example.com/",
+        wsBaseUrl: "wss://remote.example.com/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+      },
+    ];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue("bearer-token");
+    const dispose = vi.fn(async () => undefined);
+    mockCreateEnvironmentConnection.mockImplementation(
+      (input: { knownEnvironment: { environmentId: EnvironmentId }; client: unknown }) => ({
+        kind: "saved" as const,
+        environmentId: input.knownEnvironment.environmentId,
+        knownEnvironment: input.knownEnvironment,
+        client: input.client,
+        ensureBootstrapped: async () => undefined,
+        reconnect: async () => undefined,
+        dispose,
+      }),
+    );
+    let resolveSessionState!: (value: {
+      readonly authenticated: true;
+      readonly role: "owner";
+    }) => void;
+    mockFetchRemoteSessionState.mockReturnValue(
+      new Promise((resolve) => {
+        resolveSessionState = resolve;
+      }),
+    );
+
+    const {
+      disconnectSavedEnvironment,
+      listEnvironmentConnections,
+      reconnectSavedEnvironment,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const reconnectPromise = reconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+    await vi.waitFor(() => {
+      expect(mockFetchRemoteSessionState).toHaveBeenCalledOnce();
+    });
+
+    await disconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+    resolveSessionState({
+      authenticated: true,
+      role: "owner",
+    });
+    await expect(reconnectPromise).resolves.toBeUndefined();
+
+    expect(listEnvironmentConnections()).toHaveLength(0);
+    expect(dispose).toHaveBeenCalledOnce();
+    expect(mockPatchRuntime).not.toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "error",
+      }),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("reissues ssh pairing credentials when connecting after a manual ssh disconnect", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+
+    const { reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await reconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockEnsureSshEnvironment).toHaveBeenCalledWith(
+      {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+      { issuePairingToken: true },
+    );
+    expect(mockBootstrapSshBearerSession).toHaveBeenCalledWith(
+      "http://127.0.0.1:3774/",
+      "ssh-pairing-code",
+    );
+    expect(mockWriteSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      "ssh-bearer-token",
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("rolls back ssh registry metadata when pairing token issuance fails", async () => {
+    const originalRecord = {
+      environmentId: EnvironmentId.make("environment-1"),
+      label: "Remote environment",
+      httpBaseUrl: "http://127.0.0.1:3773/",
+      wsBaseUrl: "ws://127.0.0.1:3773/",
+      createdAt: "2026-04-14T00:00:00.000Z",
+      lastConnectedAt: null,
+      desktopSsh: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+    };
+    mockSavedRecords = [originalRecord];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockEnsureSshEnvironment.mockResolvedValue({
+      target: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      pairingToken: null,
+    });
+
+    const { reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await expect(reconnectSavedEnvironment(EnvironmentId.make("environment-1"))).rejects.toThrow(
+      "Desktop SSH launch did not return a pairing token.",
+    );
+
+    expect(mockPersistSavedEnvironmentRecord).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpBaseUrl: "http://127.0.0.1:3774/",
+      }),
+    );
+    expect(mockSetSavedEnvironmentRegistry).toHaveBeenCalledWith([originalRecord]);
+    expect(mockSavedRecords).toEqual([originalRecord]);
+    expect(mockBootstrapSshBearerSession).not.toHaveBeenCalled();
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("surfaces desktop ssh bootstrap failures during saved ssh reconnect", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockEnsureSshEnvironment.mockRejectedValue(new Error("SSH command timed out after 60000ms."));
+
+    const { reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await expect(reconnectSavedEnvironment(EnvironmentId.make("environment-1"))).rejects.toThrow(
+      "SSH command timed out after 60000ms.",
+    );
+    expect(mockPatchRuntime).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "connecting",
+      }),
+    );
+    expect(mockPatchRuntime).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "error",
+        lastError: "SSH command timed out after 60000ms.",
+      }),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
 });
diff --git a/apps/web/src/environments/runtime/service.savedEnvironments.test.ts b/apps/web/src/environments/runtime/service.savedEnvironments.test.ts
new file mode 100644
index 00000000000..b1d59bb49e1
--- /dev/null
+++ b/apps/web/src/environments/runtime/service.savedEnvironments.test.ts
@@ -0,0 +1,326 @@
+import { QueryClient } from "@tanstack/react-query";
+import { EnvironmentId } from "@t3tools/contracts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockCreateEnvironmentConnection = vi.fn();
+const mockCreateWsRpcClient = vi.fn();
+const mockFetchRemoteSessionState = vi.fn();
+const mockWaitForSavedEnvironmentRegistryHydration = vi.fn();
+const mockListSavedEnvironmentRecords = vi.fn();
+const mockSavedEnvironmentRegistrySubscribe = vi.fn();
+const mockReadSavedEnvironmentBearerToken = vi.fn();
+const mockGetSavedEnvironmentRecord = vi.fn();
+
+function MockWsTransport() {
+  return undefined;
+}
+
+vi.mock("../primary", () => ({
+  getPrimaryKnownEnvironment: vi.fn(() => ({
+    id: "env-1",
+    label: "Primary environment",
+    source: "window-origin",
+    target: {
+      httpBaseUrl: "http://127.0.0.1:3000/",
+      wsBaseUrl: "ws://127.0.0.1:3000/",
+    },
+    environmentId: EnvironmentId.make("env-1"),
+  })),
+}));
+
+vi.mock("../remote/api", () => ({
+  bootstrapRemoteBearerSession: vi.fn(),
+  fetchRemoteEnvironmentDescriptor: vi.fn(),
+  fetchRemoteSessionState: mockFetchRemoteSessionState,
+  resolveRemoteWebSocketConnectionUrl: vi.fn(() => "ws://remote.example.test"),
+}));
+
+vi.mock("./catalog", () => ({
+  getSavedEnvironmentRecord: mockGetSavedEnvironmentRecord,
+  hasSavedEnvironmentRegistryHydrated: vi.fn(() => true),
+  listSavedEnvironmentRecords: mockListSavedEnvironmentRecords,
+  persistSavedEnvironmentRecord: vi.fn(),
+  readSavedEnvironmentBearerToken: mockReadSavedEnvironmentBearerToken,
+  removeSavedEnvironmentBearerToken: vi.fn(),
+  useSavedEnvironmentRegistryStore: {
+    subscribe: mockSavedEnvironmentRegistrySubscribe,
+    getState: () => ({
+      upsert: vi.fn(),
+      remove: vi.fn(),
+      markConnected: vi.fn(),
+      rename: vi.fn(),
+    }),
+  },
+  useSavedEnvironmentRuntimeStore: {
+    getState: () => ({
+      ensure: vi.fn(),
+      patch: vi.fn(),
+      clear: vi.fn(),
+    }),
+  },
+  waitForSavedEnvironmentRegistryHydration: mockWaitForSavedEnvironmentRegistryHydration,
+  writeSavedEnvironmentBearerToken: vi.fn(),
+}));
+
+vi.mock("./connection", () => ({
+  createEnvironmentConnection: mockCreateEnvironmentConnection,
+}));
+
+vi.mock("../../rpc/wsRpcClient", () => ({
+  createWsRpcClient: mockCreateWsRpcClient,
+}));
+
+vi.mock("../../rpc/wsTransport", () => ({
+  WsTransport: MockWsTransport,
+}));
+
+vi.mock("~/composerDraftStore", () => ({
+  markPromotedDraftThreadByRef: vi.fn(),
+  markPromotedDraftThreadsByRef: vi.fn(),
+  useComposerDraftStore: {
+    getState: () => ({
+      getDraftThreadByRef: vi.fn(() => null),
+      clearDraftThread: vi.fn(),
+    }),
+  },
+}));
+
+vi.mock("~/localApi", () => ({
+  ensureLocalApi: vi.fn(() => ({
+    persistence: {
+      setSavedEnvironmentRegistry: vi.fn(async () => undefined),
+    },
+  })),
+}));
+
+vi.mock("~/lib/terminalStateCleanup", () => ({
+  collectActiveTerminalThreadIds: vi.fn(() => []),
+}));
+
+vi.mock("~/orchestrationEventEffects", () => ({
+  deriveOrchestrationBatchEffects: vi.fn(() => ({
+    promotedThreadRefs: [],
+    invalidatedProviderState: false,
+  })),
+}));
+
+vi.mock("~/lib/projectReactQuery", () => ({
+  projectQueryKeys: {
+    all: ["projects"],
+  },
+}));
+
+vi.mock("~/lib/providerReactQuery", () => ({
+  providerQueryKeys: {
+    all: ["providers"],
+  },
+}));
+
+vi.mock("~/store", () => ({
+  useStore: {
+    getState: () => ({
+      syncServerShellSnapshot: vi.fn(),
+      syncServerThreadDetail: vi.fn(),
+      removeServerThreadDetail: vi.fn(),
+      applyServerShellEvent: vi.fn(),
+    }),
+  },
+  selectProjectsAcrossEnvironments: vi.fn(() => []),
+  selectSidebarThreadSummaryByRef: vi.fn(() => null),
+  selectThreadByRef: vi.fn(() => null),
+  selectThreadsAcrossEnvironments: vi.fn(() => []),
+}));
+
+vi.mock("~/terminalStateStore", () => ({
+  useTerminalStateStore: {
+    getState: () => ({
+      applyTerminalEvent: vi.fn(),
+      removeTerminalState: vi.fn(),
+      clearTerminalSelection: vi.fn(),
+    }),
+  },
+}));
+
+vi.mock("~/uiStateStore", () => ({
+  useUiStateStore: {
+    getState: () => ({
+      clearThreadUi: vi.fn(),
+      syncPromotedDraftThreadRefs: vi.fn(),
+    }),
+  },
+}));
+
+const savedRecord = {
+  environmentId: EnvironmentId.make("env-saved"),
+  label: "Remote environment",
+  httpBaseUrl: "https://remote.example.test/",
+  wsBaseUrl: "wss://remote.example.test/",
+};
+
+const configSnapshot = {
+  environment: {
+    environmentId: savedRecord.environmentId,
+    label: "Remote environment",
+  },
+};
+
+function createClient() {
+  return {
+    dispose: vi.fn(async () => undefined),
+    reconnect: vi.fn(async () => undefined),
+    server: {
+      getConfig: vi.fn(async () => configSnapshot),
+      subscribeConfig: vi.fn(() => () => undefined),
+      subscribeLifecycle: vi.fn(() => () => undefined),
+      subscribeAuthAccess: vi.fn(() => () => undefined),
+      refreshProviders: vi.fn(async () => undefined),
+      upsertKeybinding: vi.fn(async () => undefined),
+      getSettings: vi.fn(async () => undefined),
+      updateSettings: vi.fn(async () => undefined),
+    },
+    orchestration: {
+      subscribeShell: vi.fn(() => () => undefined),
+      subscribeThread: vi.fn(() => () => undefined),
+      dispatchCommand: vi.fn(async () => undefined),
+      getTurnDiff: vi.fn(async () => undefined),
+      getFullThreadDiff: vi.fn(async () => undefined),
+    },
+    terminal: {
+      open: vi.fn(async () => undefined),
+      write: vi.fn(async () => undefined),
+      resize: vi.fn(async () => undefined),
+      clear: vi.fn(async () => undefined),
+      restart: vi.fn(async () => undefined),
+      close: vi.fn(async () => undefined),
+      onEvent: vi.fn(() => () => undefined),
+    },
+    projects: {
+      searchEntries: vi.fn(async () => []),
+      writeFile: vi.fn(async () => undefined),
+    },
+    shell: {
+      openInEditor: vi.fn(async () => undefined),
+    },
+    git: {
+      pull: vi.fn(async () => undefined),
+      refreshStatus: vi.fn(async () => undefined),
+      onStatus: vi.fn(() => () => undefined),
+      runStackedAction: vi.fn(async () => ({})),
+      listBranches: vi.fn(async () => []),
+      createWorktree: vi.fn(async () => undefined),
+      removeWorktree: vi.fn(async () => undefined),
+      createBranch: vi.fn(async () => undefined),
+      checkout: vi.fn(async () => undefined),
+      init: vi.fn(async () => undefined),
+      resolvePullRequest: vi.fn(async () => undefined),
+      preparePullRequestThread: vi.fn(async () => undefined),
+    },
+  };
+}
+
+describe("saved environment startup", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.resetModules();
+    vi.clearAllMocks();
+
+    mockFetchRemoteSessionState.mockResolvedValue({
+      authenticated: true,
+      role: "owner",
+    });
+    mockGetSavedEnvironmentRecord.mockImplementation((environmentId: EnvironmentId) =>
+      environmentId === savedRecord.environmentId ? savedRecord : null,
+    );
+    mockListSavedEnvironmentRecords.mockReturnValue([savedRecord]);
+    mockSavedEnvironmentRegistrySubscribe.mockReturnValue(() => undefined);
+    mockWaitForSavedEnvironmentRegistryHydration.mockResolvedValue(undefined);
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue("saved-bearer-token");
+    mockCreateWsRpcClient.mockImplementation(() => createClient());
+    mockCreateEnvironmentConnection.mockImplementation((input) => {
+      if (input.kind === "saved") {
+        queueMicrotask(() => {
+          input.onConfigSnapshot?.(configSnapshot);
+        });
+      }
+
+      return {
+        kind: input.kind,
+        environmentId: input.knownEnvironment.environmentId,
+        knownEnvironment: input.knownEnvironment,
+        client: input.client,
+        ensureBootstrapped: vi.fn(async () => undefined),
+        reconnect: vi.fn(async () => undefined),
+        dispose: vi.fn(async () => undefined),
+      };
+    });
+  });
+
+  afterEach(async () => {
+    const { resetEnvironmentServiceForTests } = await import("./service");
+    await resetEnvironmentServiceForTests();
+    vi.useRealTimers();
+  });
+
+  it("uses the initial config snapshot instead of issuing an extra getConfig call", async () => {
+    const { startEnvironmentConnectionService, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    await vi.runAllTimersAsync();
+
+    const savedConnectionCall = mockCreateEnvironmentConnection.mock.calls.find(
+      ([input]) => input.kind === "saved",
+    );
+    expect(savedConnectionCall).toBeDefined();
+
+    const savedClient = savedConnectionCall?.[0]?.client;
+    expect(savedClient.server.getConfig).not.toHaveBeenCalled();
+    expect(mockFetchRemoteSessionState).toHaveBeenCalledTimes(1);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("coalesces hydration and registry sync so the initial saved connection only starts once", async () => {
+    let finishHydration!: () => void;
+    let finishTokenRead!: (token: string) => void;
+
+    mockWaitForSavedEnvironmentRegistryHydration.mockImplementation(
+      () =>
+        new Promise<void>((resolve) => {
+          finishHydration = () => resolve();
+        }),
+    );
+    mockReadSavedEnvironmentBearerToken.mockImplementation(
+      () =>
+        new Promise<string>((resolve) => {
+          finishTokenRead = resolve;
+        }),
+    );
+
+    const { startEnvironmentConnectionService, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    const registryListener = mockSavedEnvironmentRegistrySubscribe.mock.calls[0]?.[0];
+    expect(registryListener).toBeTypeOf("function");
+
+    registryListener?.();
+    finishHydration();
+    await vi.waitFor(() => {
+      expect(mockReadSavedEnvironmentBearerToken).toHaveBeenCalledTimes(1);
+    });
+
+    finishTokenRead("saved-bearer-token");
+    await vi.runAllTimersAsync();
+
+    const savedConnectionCalls = mockCreateEnvironmentConnection.mock.calls.filter(
+      ([input]) => input.kind === "saved",
+    );
+    expect(savedConnectionCalls).toHaveLength(1);
+    expect(mockFetchRemoteSessionState).toHaveBeenCalledTimes(1);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+});
diff --git a/apps/web/src/environments/runtime/service.test.ts b/apps/web/src/environments/runtime/service.test.ts
index 7a4af404980..40ec455adc1 100644
--- a/apps/web/src/environments/runtime/service.test.ts
+++ b/apps/web/src/environments/runtime/service.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { shouldApplyTerminalEvent } from "./service";
+import {
+  shouldApplyProjectionEvent,
+  shouldApplyProjectionSnapshot,
+  shouldApplyTerminalEvent,
+} from "./service";
 
 describe("shouldApplyTerminalEvent", () => {
   it("applies terminal events for draft-only threads", () => {
@@ -39,3 +43,106 @@ describe("shouldApplyTerminalEvent", () => {
     ).toBe(true);
   });
 });
+
+describe("shouldApplyProjectionSnapshot", () => {
+  it("accepts the first snapshot for an environment", () => {
+    expect(
+      shouldApplyProjectionSnapshot({
+        current: null,
+        next: {
+          snapshotSequence: 1,
+          updatedAt: "2026-04-22T10:00:00.000Z",
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("drops snapshots with an older sequence", () => {
+    expect(
+      shouldApplyProjectionSnapshot({
+        current: {
+          sequence: 5,
+          updatedAt: "2026-04-22T10:05:00.000Z",
+        },
+        next: {
+          snapshotSequence: 4,
+          updatedAt: "2026-04-22T10:06:00.000Z",
+        },
+      }),
+    ).toBe(false);
+  });
+
+  it("drops snapshots with the same sequence and older timestamp", () => {
+    expect(
+      shouldApplyProjectionSnapshot({
+        current: {
+          sequence: 5,
+          updatedAt: "2026-04-22T10:05:00.000Z",
+        },
+        next: {
+          snapshotSequence: 5,
+          updatedAt: "2026-04-22T10:04:59.000Z",
+        },
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts snapshots with the same sequence and a newer timestamp", () => {
+    expect(
+      shouldApplyProjectionSnapshot({
+        current: {
+          sequence: 5,
+          updatedAt: "2026-04-22T10:05:00.000Z",
+        },
+        next: {
+          snapshotSequence: 5,
+          updatedAt: "2026-04-22T10:05:01.000Z",
+        },
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("shouldApplyProjectionEvent", () => {
+  it("accepts the first event for an environment", () => {
+    expect(
+      shouldApplyProjectionEvent({
+        current: null,
+        sequence: 1,
+      }),
+    ).toBe(true);
+  });
+
+  it("drops stale or duplicate events", () => {
+    expect(
+      shouldApplyProjectionEvent({
+        current: {
+          sequence: 5,
+          updatedAt: "2026-04-22T10:05:00.000Z",
+        },
+        sequence: 5,
+      }),
+    ).toBe(false);
+    expect(
+      shouldApplyProjectionEvent({
+        current: {
+          sequence: 5,
+          updatedAt: "2026-04-22T10:05:00.000Z",
+        },
+        sequence: 4,
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts newer events", () => {
+    expect(
+      shouldApplyProjectionEvent({
+        current: {
+          sequence: 5,
+          updatedAt: "2026-04-22T10:05:00.000Z",
+        },
+        sequence: 6,
+      }),
+    ).toBe(true);
+  });
+});
diff --git a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
new file mode 100644
index 00000000000..087200451f3
--- /dev/null
+++ b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
@@ -0,0 +1,514 @@
+import { QueryClient } from "@tanstack/react-query";
+import {
+  EnvironmentId,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+  TurnId,
+  type OrchestrationShellSnapshot,
+} from "@t3tools/contracts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockSubscribeThread = vi.fn();
+const mockThreadUnsubscribe = vi.fn();
+const mockCreateEnvironmentConnection = vi.fn();
+const mockCreateWsRpcClient = vi.fn();
+const mockWaitForSavedEnvironmentRegistryHydration = vi.fn();
+const mockListSavedEnvironmentRecords = vi.fn();
+const mockGetSavedEnvironmentRecord = vi.fn();
+const mockReadSavedEnvironmentBearerToken = vi.fn();
+const mockSavedEnvironmentRegistrySubscribe = vi.fn();
+const mockGetPrimaryKnownEnvironment = vi.hoisted(() => vi.fn());
+const mockFetchRemoteSessionState = vi.fn();
+const mockConnectionReconnects: Array<ReturnType<typeof vi.fn>> = [];
+let savedEnvironmentRegistryListener: (() => void) | null = null;
+
+function MockWsTransport() {
+  return undefined;
+}
+
+vi.mock("../primary", () => ({
+  getPrimaryKnownEnvironment: mockGetPrimaryKnownEnvironment,
+}));
+
+vi.mock("../remote/api", () => ({
+  bootstrapRemoteBearerSession: vi.fn(),
+  fetchRemoteEnvironmentDescriptor: vi.fn(),
+  fetchRemoteSessionState: mockFetchRemoteSessionState,
+  isRemoteEnvironmentAuthHttpError: vi.fn(() => false),
+  resolveRemoteWebSocketConnectionUrl: vi.fn(async () => "ws://remote.example.test/ws"),
+}));
+
+vi.mock("./catalog", () => ({
+  getSavedEnvironmentRecord: mockGetSavedEnvironmentRecord,
+  hasSavedEnvironmentRegistryHydrated: vi.fn(() => true),
+  listSavedEnvironmentRecords: mockListSavedEnvironmentRecords,
+  persistSavedEnvironmentRecord: vi.fn(),
+  readSavedEnvironmentBearerToken: mockReadSavedEnvironmentBearerToken,
+  removeSavedEnvironmentBearerToken: vi.fn(),
+  useSavedEnvironmentRegistryStore: {
+    subscribe: mockSavedEnvironmentRegistrySubscribe,
+    getState: () => ({
+      upsert: vi.fn(),
+      remove: vi.fn(),
+      markConnected: vi.fn(),
+      rename: vi.fn(),
+    }),
+  },
+  useSavedEnvironmentRuntimeStore: {
+    getState: () => ({
+      ensure: vi.fn(),
+      patch: vi.fn(),
+      clear: vi.fn(),
+    }),
+  },
+  waitForSavedEnvironmentRegistryHydration: mockWaitForSavedEnvironmentRegistryHydration,
+  writeSavedEnvironmentBearerToken: vi.fn(),
+}));
+
+vi.mock("./connection", () => ({
+  createEnvironmentConnection: mockCreateEnvironmentConnection,
+}));
+
+vi.mock("../../rpc/wsRpcClient", () => ({
+  createWsRpcClient: mockCreateWsRpcClient,
+}));
+
+vi.mock("../../rpc/wsTransport", () => ({
+  WsTransport: MockWsTransport,
+}));
+
+function makeThreadShellSnapshot(params: {
+  readonly threadId: ThreadId;
+  readonly sessionStatus?:
+    | "idle"
+    | "starting"
+    | "running"
+    | "ready"
+    | "interrupted"
+    | "stopped"
+    | "error";
+  readonly hasPendingApprovals?: boolean;
+  readonly hasPendingUserInput?: boolean;
+  readonly hasActionableProposedPlan?: boolean;
+}): OrchestrationShellSnapshot {
+  const projectId = ProjectId.make("project-1");
+  const turnId = TurnId.make("turn-1");
+
+  return {
+    snapshotSequence: 1,
+    projects: [],
+    updatedAt: "2026-04-13T00:00:00.000Z",
+    threads: [
+      {
+        id: params.threadId,
+        projectId,
+        title: "Thread",
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5-codex",
+        },
+        runtimeMode: "full-access",
+        interactionMode: "default",
+        branch: null,
+        worktreePath: null,
+        latestTurn:
+          params.sessionStatus === "running"
+            ? {
+                turnId,
+                state: "running",
+                requestedAt: "2026-04-13T00:00:00.000Z",
+                startedAt: "2026-04-13T00:00:01.000Z",
+                completedAt: null,
+                assistantMessageId: null,
+              }
+            : null,
+        createdAt: "2026-04-13T00:00:00.000Z",
+        updatedAt: "2026-04-13T00:00:00.000Z",
+        archivedAt: null,
+        session: params.sessionStatus
+          ? {
+              threadId: params.threadId,
+              status: params.sessionStatus,
+              providerName: "codex",
+              runtimeMode: "full-access",
+              activeTurnId: params.sessionStatus === "running" ? turnId : null,
+              lastError: null,
+              updatedAt: "2026-04-13T00:00:00.000Z",
+            }
+          : null,
+        latestUserMessageAt: null,
+        hasPendingApprovals: params.hasPendingApprovals ?? false,
+        hasPendingUserInput: params.hasPendingUserInput ?? false,
+        hasActionableProposedPlan: params.hasActionableProposedPlan ?? false,
+      },
+    ],
+  };
+}
+
+describe("retainThreadDetailSubscription", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.resetModules();
+    vi.clearAllMocks();
+    mockGetPrimaryKnownEnvironment.mockReturnValue({
+      id: "env-1",
+      label: "Primary environment",
+      source: "window-origin",
+      target: {
+        httpBaseUrl: "http://127.0.0.1:3000/",
+        wsBaseUrl: "ws://127.0.0.1:3000/",
+      },
+      environmentId: EnvironmentId.make("env-1"),
+    });
+
+    mockThreadUnsubscribe.mockImplementation(() => undefined);
+    mockSubscribeThread.mockImplementation(() => mockThreadUnsubscribe);
+    mockCreateWsRpcClient.mockReturnValue({
+      server: {
+        getConfig: vi.fn(async () => ({
+          environment: {
+            environmentId: EnvironmentId.make("env-remote"),
+            label: "Remote env",
+            platform: { os: "darwin", arch: "arm64" },
+            serverVersion: "0.0.0-test",
+            capabilities: { repositoryIdentity: true },
+          },
+        })),
+      },
+      isHeartbeatFresh: vi.fn(() => true),
+      orchestration: {
+        subscribeThread: mockSubscribeThread,
+      },
+    });
+    mockCreateEnvironmentConnection.mockImplementation((input) => {
+      const reconnect = vi.fn(async () => undefined);
+      mockConnectionReconnects.push(reconnect);
+      return {
+        kind: input.kind,
+        environmentId: input.knownEnvironment.environmentId,
+        knownEnvironment: input.knownEnvironment,
+        client: input.client,
+        ensureBootstrapped: vi.fn(async () => undefined),
+        reconnect,
+        dispose: vi.fn(async () => undefined),
+      };
+    });
+    savedEnvironmentRegistryListener = null;
+    mockSavedEnvironmentRegistrySubscribe.mockImplementation((listener: () => void) => {
+      savedEnvironmentRegistryListener = listener;
+      return () => {
+        if (savedEnvironmentRegistryListener === listener) {
+          savedEnvironmentRegistryListener = null;
+        }
+      };
+    });
+    mockWaitForSavedEnvironmentRegistryHydration.mockResolvedValue(undefined);
+    mockListSavedEnvironmentRecords.mockReturnValue([]);
+    mockGetSavedEnvironmentRecord.mockReturnValue(null);
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockFetchRemoteSessionState.mockResolvedValue({
+      authenticated: true,
+      role: "client",
+    });
+    mockConnectionReconnects.length = 0;
+  });
+
+  afterEach(async () => {
+    const { resetEnvironmentServiceForTests } = await import("./service");
+    await resetEnvironmentServiceForTests();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("keeps thread detail subscriptions warm across releases until idle eviction", async () => {
+    const {
+      retainThreadDetailSubscription,
+      startEnvironmentConnectionService,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    const environmentId = EnvironmentId.make("env-1");
+    const threadId = ThreadId.make("thread-1");
+
+    const releaseFirst = retainThreadDetailSubscription(environmentId, threadId);
+    expect(mockSubscribeThread).toHaveBeenCalledTimes(1);
+
+    releaseFirst();
+    expect(mockThreadUnsubscribe).not.toHaveBeenCalled();
+
+    const releaseSecond = retainThreadDetailSubscription(environmentId, threadId);
+    expect(mockSubscribeThread).toHaveBeenCalledTimes(1);
+
+    releaseSecond();
+    await vi.advanceTimersByTimeAsync(2 * 60 * 1000);
+    expect(mockThreadUnsubscribe).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(28 * 60 * 1000);
+    expect(mockThreadUnsubscribe).toHaveBeenCalledTimes(1);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("does not start the primary connection until the known environment has an id", async () => {
+    mockGetPrimaryKnownEnvironment.mockReturnValue({
+      id: "env-1",
+      label: "Primary environment",
+      source: "window-origin",
+      target: {
+        httpBaseUrl: "http://127.0.0.1:3000/",
+        wsBaseUrl: "ws://127.0.0.1:3000/",
+      },
+    });
+    const {
+      listEnvironmentConnections,
+      resetEnvironmentServiceForTests,
+      startEnvironmentConnectionService,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+
+    expect(mockCreateEnvironmentConnection).not.toHaveBeenCalled();
+    expect(listEnvironmentConnections()).toEqual([]);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("keeps non-idle thread detail subscriptions attached until the thread becomes idle", async () => {
+    const {
+      retainThreadDetailSubscription,
+      startEnvironmentConnectionService,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    const environmentId = EnvironmentId.make("env-1");
+    const threadId = ThreadId.make("thread-active");
+
+    const connectionInput = mockCreateEnvironmentConnection.mock.calls[0]?.[0];
+    expect(connectionInput).toBeDefined();
+
+    connectionInput.syncShellSnapshot(
+      makeThreadShellSnapshot({
+        threadId,
+        sessionStatus: "ready",
+        hasPendingApprovals: true,
+      }),
+      environmentId,
+    );
+
+    const release = retainThreadDetailSubscription(environmentId, threadId);
+    expect(mockSubscribeThread).toHaveBeenCalledTimes(1);
+
+    release();
+    await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
+    expect(mockThreadUnsubscribe).not.toHaveBeenCalled();
+
+    connectionInput.applyShellEvent(
+      {
+        kind: "thread-upserted",
+        sequence: 2,
+        thread: makeThreadShellSnapshot({
+          threadId,
+          sessionStatus: "idle",
+        }).threads[0]!,
+      },
+      environmentId,
+    );
+
+    await vi.advanceTimersByTimeAsync(30 * 60 * 1000);
+    expect(mockThreadUnsubscribe).toHaveBeenCalledTimes(1);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("reattaches retained thread detail subscriptions after a saved environment reconnect replaces the client", async () => {
+    const environmentId = EnvironmentId.make("env-remote");
+    const threadId = ThreadId.make("thread-reconnect");
+    const record = {
+      environmentId,
+      label: "Remote env",
+      httpBaseUrl: "http://remote.example.test",
+      wsBaseUrl: "ws://remote.example.test",
+      createdAt: "2026-05-01T00:00:00.000Z",
+      lastConnectedAt: "2026-05-01T00:00:00.000Z",
+    };
+    mockListSavedEnvironmentRecords.mockReturnValue([record]);
+    mockGetSavedEnvironmentRecord.mockReturnValue(record);
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue("bearer-token");
+
+    const {
+      disconnectSavedEnvironment,
+      listEnvironmentConnections,
+      reconnectSavedEnvironment,
+      retainThreadDetailSubscription,
+      startEnvironmentConnectionService,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    savedEnvironmentRegistryListener?.();
+    await vi.waitFor(() => {
+      expect(mockCreateEnvironmentConnection).toHaveBeenCalledTimes(2);
+      expect(
+        listEnvironmentConnections().some(
+          (connection) => connection.environmentId === environmentId,
+        ),
+      ).toBe(true);
+    });
+
+    const release = retainThreadDetailSubscription(environmentId, threadId);
+    expect(mockSubscribeThread).toHaveBeenCalledTimes(1);
+
+    await disconnectSavedEnvironment(environmentId);
+    expect(mockThreadUnsubscribe).toHaveBeenCalledTimes(1);
+    expect(
+      listEnvironmentConnections().some((connection) => connection.environmentId === environmentId),
+    ).toBe(false);
+
+    const reconnectPromise = reconnectSavedEnvironment(environmentId);
+    await vi.advanceTimersByTimeAsync(200);
+    await reconnectPromise;
+    await vi.waitFor(() => {
+      expect(mockCreateEnvironmentConnection).toHaveBeenCalledTimes(3);
+      expect(mockSubscribeThread).toHaveBeenCalledTimes(2);
+    });
+
+    release();
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("keeps healthy environment streams connected when the browser resumes from the background", async () => {
+    let visibilityState: DocumentVisibilityState = "visible";
+    const documentTarget = new EventTarget();
+    const windowTarget = new EventTarget();
+    vi.stubGlobal("document", {
+      addEventListener: documentTarget.addEventListener.bind(documentTarget),
+      removeEventListener: documentTarget.removeEventListener.bind(documentTarget),
+      get visibilityState() {
+        return visibilityState;
+      },
+    });
+    vi.stubGlobal("window", {
+      addEventListener: windowTarget.addEventListener.bind(windowTarget),
+      removeEventListener: windowTarget.removeEventListener.bind(windowTarget),
+    });
+
+    const { resetEnvironmentServiceForTests, startEnvironmentConnectionService } =
+      await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    expect(mockConnectionReconnects).toHaveLength(1);
+
+    visibilityState = "hidden";
+    documentTarget.dispatchEvent(new Event("visibilitychange"));
+    expect(mockConnectionReconnects[0]).not.toHaveBeenCalled();
+
+    visibilityState = "visible";
+    documentTarget.dispatchEvent(new Event("visibilitychange"));
+    expect(mockConnectionReconnects[0]).not.toHaveBeenCalled();
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("reconnects stale environment streams when the browser resumes from the background", async () => {
+    let visibilityState: DocumentVisibilityState = "visible";
+    const documentTarget = new EventTarget();
+    const windowTarget = new EventTarget();
+    vi.stubGlobal("document", {
+      addEventListener: documentTarget.addEventListener.bind(documentTarget),
+      removeEventListener: documentTarget.removeEventListener.bind(documentTarget),
+      get visibilityState() {
+        return visibilityState;
+      },
+    });
+    vi.stubGlobal("window", {
+      addEventListener: windowTarget.addEventListener.bind(windowTarget),
+      removeEventListener: windowTarget.removeEventListener.bind(windowTarget),
+    });
+    mockCreateWsRpcClient.mockReturnValue({
+      server: {
+        getConfig: vi.fn(async () => ({
+          environment: {
+            environmentId: EnvironmentId.make("env-remote"),
+            label: "Remote env",
+            platform: { os: "darwin", arch: "arm64" },
+            serverVersion: "0.0.0-test",
+            capabilities: { repositoryIdentity: true },
+          },
+        })),
+      },
+      isHeartbeatFresh: vi.fn(() => false),
+      orchestration: {
+        subscribeThread: mockSubscribeThread,
+      },
+    });
+
+    const { resetEnvironmentServiceForTests, startEnvironmentConnectionService } =
+      await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    expect(mockConnectionReconnects).toHaveLength(1);
+
+    visibilityState = "hidden";
+    documentTarget.dispatchEvent(new Event("visibilitychange"));
+    expect(mockConnectionReconnects[0]).not.toHaveBeenCalled();
+
+    visibilityState = "visible";
+    documentTarget.dispatchEvent(new Event("visibilitychange"));
+    expect(mockConnectionReconnects[0]).toHaveBeenCalledTimes(1);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("allows a larger idle cache before capacity eviction starts", async () => {
+    const {
+      retainThreadDetailSubscription,
+      startEnvironmentConnectionService,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    const environmentId = EnvironmentId.make("env-1");
+
+    for (let index = 0; index < 12; index += 1) {
+      const release = retainThreadDetailSubscription(
+        environmentId,
+        ThreadId.make(`thread-${index + 1}`),
+      );
+      release();
+    }
+
+    expect(mockThreadUnsubscribe).not.toHaveBeenCalled();
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("disposes cached thread detail subscriptions when the environment service resets", async () => {
+    const {
+      retainThreadDetailSubscription,
+      startEnvironmentConnectionService,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    const environmentId = EnvironmentId.make("env-1");
+    const threadId = ThreadId.make("thread-2");
+
+    const release = retainThreadDetailSubscription(environmentId, threadId);
+    release();
+
+    await resetEnvironmentServiceForTests();
+    expect(mockThreadUnsubscribe).toHaveBeenCalledTimes(1);
+
+    stop();
+  });
+});
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 5c8d2dacabc..21a4561beb4 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -1,8 +1,11 @@
 import {
   type AuthSessionRole,
+  type DesktopSshEnvironmentBootstrap,
+  type DesktopSshEnvironmentTarget,
   type EnvironmentId,
   type OrchestrationEvent,
-  type OrchestrationReadModel,
+  type OrchestrationShellSnapshot,
+  type OrchestrationShellStreamEvent,
   type ServerConfig,
   type TerminalEvent,
   ThreadId,
@@ -12,7 +15,6 @@ import { Throttler } from "@tanstack/react-pacer";
 import {
   createKnownEnvironment,
   getKnownEnvironmentWsBaseUrl,
-  scopedProjectKey,
   scopedThreadKey,
   scopeProjectRef,
   scopeThreadRef,
@@ -33,6 +35,7 @@ import {
   bootstrapRemoteBearerSession,
   fetchRemoteEnvironmentDescriptor,
   fetchRemoteSessionState,
+  isRemoteEnvironmentAuthHttpError,
   resolveRemoteWebSocketConnectionUrl,
 } from "../remote/api";
 import { resolveRemotePairingTarget } from "../remote/target";
@@ -44,6 +47,7 @@ import {
   readSavedEnvironmentBearerToken,
   removeSavedEnvironmentBearerToken,
   type SavedEnvironmentRecord,
+  toPersistedSavedEnvironmentRecord,
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
   waitForSavedEnvironmentRegistryHydration,
@@ -53,13 +57,22 @@ import { createEnvironmentConnection, type EnvironmentConnection } from "./conne
 import {
   useStore,
   selectProjectsAcrossEnvironments,
+  selectSidebarThreadSummaryByRef,
   selectThreadByRef,
   selectThreadsAcrossEnvironments,
 } from "~/store";
 import { useTerminalStateStore } from "~/terminalStateStore";
 import { useUiStateStore } from "~/uiStateStore";
+import type { WsProtocolCloseContext } from "../../rpc/protocol";
+import { getServerConfig } from "../../rpc/serverState";
 import { WsTransport } from "../../rpc/wsTransport";
 import { createWsRpcClient, type WsRpcClient } from "../../rpc/wsRpcClient";
+import { appendVersionMismatchHint, resolveServerConfigVersionMismatch } from "../../versionSkew";
+import {
+  deriveLogicalProjectKeyFromSettings,
+  derivePhysicalProjectKey,
+} from "../../logicalProject";
+import { getClientSettings } from "~/hooks/useSettings";
 
 type EnvironmentServiceState = {
   readonly queryClient: QueryClient;
@@ -68,11 +81,510 @@ type EnvironmentServiceState = {
   stop: () => void;
 };
 
+type ThreadDetailSubscriptionEntry = {
+  readonly environmentId: EnvironmentId;
+  readonly threadId: ThreadId;
+  unsubscribe: () => void;
+  unsubscribeConnectionListener: (() => void) | null;
+  refCount: number;
+  lastAccessedAt: number;
+  evictionTimeoutId: ReturnType<typeof setTimeout> | null;
+};
+
 const environmentConnections = new Map<EnvironmentId, EnvironmentConnection>();
+class SavedEnvironmentConnectionCancelledError extends Error {
+  constructor(environmentId: EnvironmentId) {
+    super(`Saved environment ${environmentId} connection was cancelled.`);
+    this.name = "SavedEnvironmentConnectionCancelledError";
+  }
+}
+
+function isSavedEnvironmentConnectionCancelledError(
+  error: unknown,
+): error is SavedEnvironmentConnectionCancelledError {
+  return error instanceof SavedEnvironmentConnectionCancelledError;
+}
+
+interface PendingSavedEnvironmentConnection {
+  cancelled: boolean;
+  readonly promise: Promise<EnvironmentConnection>;
+}
+
+const pendingSavedEnvironmentConnections = new Map<
+  EnvironmentId,
+  PendingSavedEnvironmentConnection
+>();
 const environmentConnectionListeners = new Set<() => void>();
+const threadDetailSubscriptions = new Map<string, ThreadDetailSubscriptionEntry>();
+const lastAppliedProjectionVersionByEnvironment = new Map<
+  EnvironmentId,
+  {
+    readonly sequence: number;
+    readonly updatedAt: string | null;
+  }
+>();
 
 let activeService: EnvironmentServiceState | null = null;
 let needsProviderInvalidation = false;
+let lastBrowserHiddenAt: number | null = null;
+let lastBrowserResumeReconnectAt = Number.NEGATIVE_INFINITY;
+
+// Thread detail subscription cache policy:
+// - Active consumers keep a subscription retained via refCount.
+// - Released subscriptions stay warm for a longer idle TTL to avoid churn
+//   while moving around the UI.
+// - Threads with active work or pending user action are sticky and are never
+//   evicted while they remain non-idle.
+// - Capacity eviction only targets idle cached subscriptions.
+const THREAD_DETAIL_SUBSCRIPTION_IDLE_EVICTION_MS = 15 * 60 * 1000;
+const MAX_CACHED_THREAD_DETAIL_SUBSCRIPTIONS = 32;
+const BROWSER_RESUME_RECONNECT_COOLDOWN_MS = 2_000;
+const INITIAL_SERVER_CONFIG_SNAPSHOT_WAIT_MS = 150;
+const NOOP = () => undefined;
+const SSH_HTTP_STATUS_RE = /^\[ssh_http:(\d+)\]\s/u;
+
+function createDeferredPromise<T>() {
+  let resolve: ((value: T) => void) | null = null;
+  const promise = new Promise<T>((nextResolve) => {
+    resolve = nextResolve;
+  });
+
+  return {
+    promise,
+    resolve: (value: T) => {
+      resolve?.(value);
+      resolve = null;
+    },
+  };
+}
+
+async function waitForConfigSnapshot(
+  promise: Promise<ServerConfig>,
+  timeoutMs: number,
+): Promise<ServerConfig | null> {
+  return await new Promise<ServerConfig | null>((resolve) => {
+    const timeoutId = globalThis.setTimeout(() => resolve(null), timeoutMs);
+    promise.then(
+      (config) => {
+        clearTimeout(timeoutId);
+        resolve(config);
+      },
+      () => {
+        clearTimeout(timeoutId);
+        resolve(null);
+      },
+    );
+  });
+}
+
+function createSavedEnvironmentSyncScheduler() {
+  let activeSync: Promise<void> | null = null;
+  let queued = false;
+
+  const run = async (): Promise<void> => {
+    do {
+      queued = false;
+      await syncSavedEnvironmentConnections(listSavedEnvironmentRecords());
+    } while (queued);
+  };
+
+  return () => {
+    if (activeSync) {
+      queued = true;
+      return activeSync;
+    }
+
+    activeSync = run()
+      .catch(() => undefined)
+      .finally(() => {
+        activeSync = null;
+      });
+
+    return activeSync;
+  };
+}
+function compareAppliedProjectionVersion(
+  left: { readonly sequence: number; readonly updatedAt: string | null },
+  right: { readonly sequence: number; readonly updatedAt: string | null },
+): number {
+  if (left.sequence !== right.sequence) {
+    return left.sequence - right.sequence;
+  }
+
+  const leftUpdatedAt = left.updatedAt ?? "";
+  const rightUpdatedAt = right.updatedAt ?? "";
+  if (leftUpdatedAt === rightUpdatedAt) {
+    return 0;
+  }
+
+  return leftUpdatedAt < rightUpdatedAt ? -1 : 1;
+}
+
+function toAppliedProjectionVersion(
+  snapshot: Pick<OrchestrationShellSnapshot, "snapshotSequence" | "updatedAt">,
+): {
+  readonly sequence: number;
+  readonly updatedAt: string;
+} {
+  return {
+    sequence: snapshot.snapshotSequence,
+    updatedAt: snapshot.updatedAt,
+  };
+}
+
+export function shouldApplyProjectionSnapshot(input: {
+  readonly current: {
+    readonly sequence: number;
+    readonly updatedAt: string | null;
+  } | null;
+  readonly next: Pick<OrchestrationShellSnapshot, "snapshotSequence" | "updatedAt">;
+}): boolean {
+  if (input.current === null) {
+    return true;
+  }
+
+  return compareAppliedProjectionVersion(input.current, toAppliedProjectionVersion(input.next)) < 0;
+}
+
+export function shouldApplyProjectionEvent(input: {
+  readonly current: {
+    readonly sequence: number;
+    readonly updatedAt: string | null;
+  } | null;
+  readonly sequence: number;
+}): boolean {
+  if (input.current === null) {
+    return true;
+  }
+
+  return input.sequence > input.current.sequence;
+}
+
+function readLastAppliedProjectionVersion(environmentId: EnvironmentId): {
+  readonly sequence: number;
+  readonly updatedAt: string | null;
+} | null {
+  return lastAppliedProjectionVersionByEnvironment.get(environmentId) ?? null;
+}
+
+function markAppliedProjectionSnapshot(
+  environmentId: EnvironmentId,
+  snapshot: Pick<OrchestrationShellSnapshot, "snapshotSequence" | "updatedAt">,
+): void {
+  const nextVersion = toAppliedProjectionVersion(snapshot);
+  const currentVersion = readLastAppliedProjectionVersion(environmentId);
+  if (
+    currentVersion !== null &&
+    compareAppliedProjectionVersion(currentVersion, nextVersion) >= 0
+  ) {
+    return;
+  }
+
+  lastAppliedProjectionVersionByEnvironment.set(environmentId, nextVersion);
+}
+
+function markAppliedProjectionEvent(environmentId: EnvironmentId, sequence: number): void {
+  const currentVersion = readLastAppliedProjectionVersion(environmentId);
+  if (currentVersion !== null && sequence <= currentVersion.sequence) {
+    return;
+  }
+
+  lastAppliedProjectionVersionByEnvironment.set(environmentId, {
+    sequence,
+    updatedAt: currentVersion?.updatedAt ?? null,
+  });
+}
+function getThreadDetailSubscriptionKey(environmentId: EnvironmentId, threadId: ThreadId): string {
+  return scopedThreadKey(scopeThreadRef(environmentId, threadId));
+}
+
+function clearThreadDetailSubscriptionEviction(
+  entry: ThreadDetailSubscriptionEntry,
+): ThreadDetailSubscriptionEntry {
+  if (entry.evictionTimeoutId !== null) {
+    clearTimeout(entry.evictionTimeoutId);
+    entry.evictionTimeoutId = null;
+  }
+  return entry;
+}
+
+function isNonIdleThreadDetailSubscription(entry: ThreadDetailSubscriptionEntry): boolean {
+  const threadRef = scopeThreadRef(entry.environmentId, entry.threadId);
+  const state = useStore.getState();
+  const sidebarThread = selectSidebarThreadSummaryByRef(state, threadRef);
+
+  // Prefer shell/sidebar state first because it carries the coarse thread
+  // readiness flags used throughout the UI (pending approvals/input/plan).
+  if (sidebarThread) {
+    if (
+      sidebarThread.hasPendingApprovals ||
+      sidebarThread.hasPendingUserInput ||
+      sidebarThread.hasActionableProposedPlan
+    ) {
+      return true;
+    }
+
+    const orchestrationStatus = sidebarThread.session?.orchestrationStatus;
+    if (
+      orchestrationStatus &&
+      orchestrationStatus !== "idle" &&
+      orchestrationStatus !== "stopped"
+    ) {
+      return true;
+    }
+
+    if (sidebarThread.latestTurn?.state === "running") {
+      return true;
+    }
+  }
+
+  const thread = selectThreadByRef(state, threadRef);
+  if (!thread) {
+    return false;
+  }
+
+  const orchestrationStatus = thread.session?.orchestrationStatus;
+  return (
+    Boolean(
+      orchestrationStatus && orchestrationStatus !== "idle" && orchestrationStatus !== "stopped",
+    ) ||
+    thread.latestTurn?.state === "running" ||
+    thread.pendingSourceProposedPlan !== undefined
+  );
+}
+
+function shouldEvictThreadDetailSubscription(entry: ThreadDetailSubscriptionEntry): boolean {
+  return entry.refCount === 0 && !isNonIdleThreadDetailSubscription(entry);
+}
+
+function attachThreadDetailSubscription(entry: ThreadDetailSubscriptionEntry): boolean {
+  if (entry.unsubscribeConnectionListener !== null) {
+    entry.unsubscribeConnectionListener();
+    entry.unsubscribeConnectionListener = null;
+  }
+  if (entry.unsubscribe !== NOOP) {
+    return true;
+  }
+
+  const connection = readEnvironmentConnection(entry.environmentId);
+  if (!connection) {
+    return false;
+  }
+
+  entry.unsubscribe = connection.client.orchestration.subscribeThread(
+    { threadId: entry.threadId },
+    (item) => {
+      if (item.kind === "snapshot") {
+        useStore.getState().syncServerThreadDetail(item.snapshot.thread, entry.environmentId);
+        return;
+      }
+      applyEnvironmentThreadDetailEvent(item.event, entry.environmentId);
+    },
+  );
+  return true;
+}
+
+function watchThreadDetailSubscriptionConnection(entry: ThreadDetailSubscriptionEntry): void {
+  if (entry.unsubscribeConnectionListener !== null) {
+    return;
+  }
+
+  entry.unsubscribeConnectionListener = subscribeEnvironmentConnections(() => {
+    if (attachThreadDetailSubscription(entry)) {
+      entry.lastAccessedAt = Date.now();
+    }
+  });
+  attachThreadDetailSubscription(entry);
+}
+
+function disposeThreadDetailSubscriptionByKey(key: string): boolean {
+  const entry = threadDetailSubscriptions.get(key);
+  if (!entry) {
+    return false;
+  }
+
+  clearThreadDetailSubscriptionEviction(entry);
+  entry.unsubscribeConnectionListener?.();
+  entry.unsubscribeConnectionListener = null;
+  threadDetailSubscriptions.delete(key);
+  entry.unsubscribe();
+  entry.unsubscribe = NOOP;
+  return true;
+}
+
+function disposeThreadDetailSubscriptionsForEnvironment(environmentId: EnvironmentId): void {
+  for (const [key, entry] of threadDetailSubscriptions) {
+    if (entry.environmentId === environmentId) {
+      disposeThreadDetailSubscriptionByKey(key);
+    }
+  }
+}
+
+function detachThreadDetailSubscriptionsForEnvironment(environmentId: EnvironmentId): void {
+  for (const entry of threadDetailSubscriptions.values()) {
+    if (entry.environmentId !== environmentId) {
+      continue;
+    }
+    entry.unsubscribe();
+    entry.unsubscribe = NOOP;
+    watchThreadDetailSubscriptionConnection(entry);
+  }
+}
+
+function attachThreadDetailSubscriptionsForEnvironment(environmentId: EnvironmentId): void {
+  for (const entry of threadDetailSubscriptions.values()) {
+    if (entry.environmentId === environmentId) {
+      attachThreadDetailSubscription(entry);
+    }
+  }
+}
+
+function reconcileThreadDetailSubscriptionsForEnvironment(
+  environmentId: EnvironmentId,
+  threadIds: ReadonlyArray<ThreadId>,
+): void {
+  const activeThreadIds = new Set(threadIds);
+  for (const [key, entry] of threadDetailSubscriptions) {
+    if (entry.environmentId === environmentId && !activeThreadIds.has(entry.threadId)) {
+      disposeThreadDetailSubscriptionByKey(key);
+    }
+  }
+}
+
+function scheduleThreadDetailSubscriptionEviction(entry: ThreadDetailSubscriptionEntry): void {
+  clearThreadDetailSubscriptionEviction(entry);
+  if (!shouldEvictThreadDetailSubscription(entry)) {
+    return;
+  }
+
+  entry.evictionTimeoutId = setTimeout(() => {
+    const currentEntry = threadDetailSubscriptions.get(
+      getThreadDetailSubscriptionKey(entry.environmentId, entry.threadId),
+    );
+    if (!currentEntry) {
+      return;
+    }
+
+    currentEntry.evictionTimeoutId = null;
+    if (!shouldEvictThreadDetailSubscription(currentEntry)) {
+      return;
+    }
+    disposeThreadDetailSubscriptionByKey(
+      getThreadDetailSubscriptionKey(entry.environmentId, entry.threadId),
+    );
+  }, THREAD_DETAIL_SUBSCRIPTION_IDLE_EVICTION_MS);
+}
+
+function evictIdleThreadDetailSubscriptionsToCapacity(): void {
+  if (threadDetailSubscriptions.size <= MAX_CACHED_THREAD_DETAIL_SUBSCRIPTIONS) {
+    return;
+  }
+
+  const idleEntries = [...threadDetailSubscriptions.entries()]
+    .filter(([, entry]) => shouldEvictThreadDetailSubscription(entry))
+    .toSorted(([, left], [, right]) => left.lastAccessedAt - right.lastAccessedAt);
+
+  for (const [key] of idleEntries) {
+    if (threadDetailSubscriptions.size <= MAX_CACHED_THREAD_DETAIL_SUBSCRIPTIONS) {
+      return;
+    }
+    disposeThreadDetailSubscriptionByKey(key);
+  }
+}
+
+function reconcileThreadDetailSubscriptionEvictionState(
+  entry: ThreadDetailSubscriptionEntry,
+): void {
+  clearThreadDetailSubscriptionEviction(entry);
+  if (!shouldEvictThreadDetailSubscription(entry)) {
+    return;
+  }
+
+  scheduleThreadDetailSubscriptionEviction(entry);
+}
+
+function reconcileThreadDetailSubscriptionEvictionForThread(
+  environmentId: EnvironmentId,
+  threadId: ThreadId,
+): void {
+  const entry = threadDetailSubscriptions.get(
+    getThreadDetailSubscriptionKey(environmentId, threadId),
+  );
+  if (!entry) {
+    return;
+  }
+
+  reconcileThreadDetailSubscriptionEvictionState(entry);
+}
+
+function reconcileThreadDetailSubscriptionEvictionForEnvironment(
+  environmentId: EnvironmentId,
+): void {
+  for (const entry of threadDetailSubscriptions.values()) {
+    if (entry.environmentId === environmentId) {
+      reconcileThreadDetailSubscriptionEvictionState(entry);
+    }
+  }
+  evictIdleThreadDetailSubscriptionsToCapacity();
+}
+
+export function retainThreadDetailSubscription(
+  environmentId: EnvironmentId,
+  threadId: ThreadId,
+): () => void {
+  const key = getThreadDetailSubscriptionKey(environmentId, threadId);
+  const existing = threadDetailSubscriptions.get(key);
+  if (existing) {
+    clearThreadDetailSubscriptionEviction(existing);
+    existing.refCount += 1;
+    existing.lastAccessedAt = Date.now();
+    if (!attachThreadDetailSubscription(existing)) {
+      watchThreadDetailSubscriptionConnection(existing);
+    }
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      existing.refCount = Math.max(0, existing.refCount - 1);
+      existing.lastAccessedAt = Date.now();
+      if (existing.refCount === 0) {
+        reconcileThreadDetailSubscriptionEvictionState(existing);
+        evictIdleThreadDetailSubscriptionsToCapacity();
+      }
+    };
+  }
+
+  const entry: ThreadDetailSubscriptionEntry = {
+    environmentId,
+    threadId,
+    unsubscribe: NOOP,
+    unsubscribeConnectionListener: null,
+    refCount: 1,
+    lastAccessedAt: Date.now(),
+    evictionTimeoutId: null,
+  };
+  threadDetailSubscriptions.set(key, entry);
+  if (!attachThreadDetailSubscription(entry)) {
+    watchThreadDetailSubscriptionConnection(entry);
+  }
+  evictIdleThreadDetailSubscriptionsToCapacity();
+
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    entry.refCount = Math.max(0, entry.refCount - 1);
+    entry.lastAccessedAt = Date.now();
+    if (entry.refCount === 0) {
+      reconcileThreadDetailSubscriptionEvictionState(entry);
+      evictIdleThreadDetailSubscriptionsToCapacity();
+    }
+  };
+}
 
 function emitEnvironmentConnectionRegistryChange() {
   for (const listener of environmentConnectionListeners) {
@@ -91,6 +603,227 @@ function isoNow(): string {
   return new Date().toISOString();
 }
 
+function readSshHttpErrorStatus(error: unknown): number | null {
+  if (!(error instanceof Error)) {
+    return null;
+  }
+
+  const match = SSH_HTTP_STATUS_RE.exec(error.message);
+  if (!match) {
+    return null;
+  }
+
+  const parsed = Number.parseInt(match[1] ?? "", 10);
+  return Number.isInteger(parsed) ? parsed : null;
+}
+
+function isSshHttpAuthError(error: unknown, status: number): boolean {
+  return readSshHttpErrorStatus(error) === status;
+}
+
+function isDesktopSshTargetEqual(
+  left: DesktopSshEnvironmentTarget | undefined,
+  right: DesktopSshEnvironmentTarget | undefined,
+): boolean {
+  if (!left || !right) {
+    return false;
+  }
+
+  return (
+    left.alias === right.alias &&
+    left.hostname === right.hostname &&
+    left.username === right.username &&
+    left.port === right.port
+  );
+}
+
+function findSavedEnvironmentRecordByDesktopSshTarget(
+  target: DesktopSshEnvironmentTarget | undefined,
+): SavedEnvironmentRecord | null {
+  if (!target) {
+    return null;
+  }
+
+  return (
+    listSavedEnvironmentRecords().find((record) =>
+      isDesktopSshTargetEqual(record.desktopSsh, target),
+    ) ?? null
+  );
+}
+
+function buildSavedEnvironmentRegistryById(
+  records: ReadonlyArray<SavedEnvironmentRecord>,
+): Record<EnvironmentId, SavedEnvironmentRecord> {
+  return Object.fromEntries(records.map((record) => [record.environmentId, record])) as Record<
+    EnvironmentId,
+    SavedEnvironmentRecord
+  >;
+}
+
+type SavedEnvironmentRegistrySnapshot = ReadonlyMap<EnvironmentId, SavedEnvironmentRecord | null>;
+
+function snapshotSavedEnvironmentRegistry(
+  environmentIds: ReadonlyArray<EnvironmentId>,
+): SavedEnvironmentRegistrySnapshot {
+  return new Map(
+    environmentIds.map((environmentId) => [
+      environmentId,
+      getSavedEnvironmentRecord(environmentId) ?? null,
+    ]),
+  );
+}
+
+async function persistSavedEnvironmentRegistryRollback(
+  snapshot: SavedEnvironmentRegistrySnapshot,
+): Promise<void> {
+  const byId = buildSavedEnvironmentRegistryById(listSavedEnvironmentRecords());
+  for (const [environmentId, record] of snapshot) {
+    if (record) {
+      byId[environmentId] = record;
+      continue;
+    }
+    delete byId[environmentId];
+  }
+  const records = Object.values(byId);
+  await ensureLocalApi().persistence.setSavedEnvironmentRegistry(
+    records.map((entry) => toPersistedSavedEnvironmentRecord(entry)),
+  );
+  useSavedEnvironmentRegistryStore.setState({
+    byId,
+  });
+}
+
+async function resolveDesktopSshEnvironmentBootstrap(
+  target: DesktopSshEnvironmentTarget,
+  options?: { readonly issuePairingToken?: boolean },
+): Promise<DesktopSshEnvironmentBootstrap> {
+  const desktopBridge = window.desktopBridge;
+  if (!desktopBridge) {
+    throw new Error("SSH launch is only available in the desktop app.");
+  }
+
+  return await desktopBridge.ensureSshEnvironment(target, options);
+}
+
+function getDesktopSshBridge() {
+  const desktopBridge = window.desktopBridge;
+  if (!desktopBridge) {
+    throw new Error("SSH launch is only available in the desktop app.");
+  }
+  return desktopBridge;
+}
+
+async function fetchDesktopSshEnvironmentDescriptor(httpBaseUrl: string) {
+  return await getDesktopSshBridge().fetchSshEnvironmentDescriptor(httpBaseUrl);
+}
+
+async function bootstrapDesktopSshBearerSession(httpBaseUrl: string, credential: string) {
+  return await getDesktopSshBridge().bootstrapSshBearerSession(httpBaseUrl, credential);
+}
+
+async function fetchDesktopSshSessionState(httpBaseUrl: string, bearerToken: string) {
+  return await getDesktopSshBridge().fetchSshSessionState(httpBaseUrl, bearerToken);
+}
+
+async function resolveDesktopSshWebSocketConnectionUrl(
+  wsBaseUrl: string,
+  httpBaseUrl: string,
+  bearerToken: string,
+) {
+  const issued = await getDesktopSshBridge().issueSshWebSocketToken(httpBaseUrl, bearerToken);
+  const url = new URL(wsBaseUrl, window.location.origin);
+  url.searchParams.set("wsToken", issued.token);
+  return url.toString();
+}
+
+async function prepareSavedEnvironmentRecordForConnection(
+  record: SavedEnvironmentRecord,
+  options?: { readonly issuePairingToken?: boolean },
+): Promise<{
+  readonly record: SavedEnvironmentRecord;
+  readonly pairingToken: string | null;
+  readonly remotePort: number | null;
+  readonly remoteServerKind: "external" | "managed" | null;
+}> {
+  if (!record.desktopSsh) {
+    return {
+      record,
+      pairingToken: null,
+      remotePort: null,
+      remoteServerKind: null,
+    };
+  }
+
+  const bootstrap = await resolveDesktopSshEnvironmentBootstrap(record.desktopSsh, options);
+  const nextRecord: SavedEnvironmentRecord = {
+    ...record,
+    httpBaseUrl: bootstrap.httpBaseUrl,
+    wsBaseUrl: bootstrap.wsBaseUrl,
+    desktopSsh: bootstrap.target,
+  };
+
+  if (
+    nextRecord.httpBaseUrl !== record.httpBaseUrl ||
+    nextRecord.wsBaseUrl !== record.wsBaseUrl ||
+    !isDesktopSshTargetEqual(nextRecord.desktopSsh, record.desktopSsh)
+  ) {
+    await persistSavedEnvironmentRecord(nextRecord);
+    useSavedEnvironmentRegistryStore.getState().upsert(nextRecord);
+  }
+
+  return {
+    record: nextRecord,
+    pairingToken: bootstrap.pairingToken,
+    remotePort: bootstrap.remotePort ?? null,
+    remoteServerKind: bootstrap.remoteServerKind ?? null,
+  };
+}
+
+async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Promise<{
+  readonly record: SavedEnvironmentRecord;
+  readonly bearerToken: string;
+  readonly role: AuthSessionRole | null;
+}> {
+  const registrySnapshot = snapshotSavedEnvironmentRegistry([record.environmentId]);
+  const prepared = await prepareSavedEnvironmentRecordForConnection(record, {
+    issuePairingToken: true,
+  });
+  if (!prepared.pairingToken) {
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
+    throw new Error("Desktop SSH launch did not return a pairing token.");
+  }
+
+  const bearerSession = await bootstrapDesktopSshBearerSession(
+    prepared.record.httpBaseUrl,
+    prepared.pairingToken,
+  ).catch(async (error) => {
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
+    const detail = [
+      `local ${prepared.record.httpBaseUrl}`,
+      `remote port ${prepared.remotePort ?? "unknown"}`,
+      prepared.remoteServerKind ? `remote server ${prepared.remoteServerKind}` : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message} (${detail})`);
+  });
+  const didPersistBearerToken = await writeSavedEnvironmentBearerToken(
+    prepared.record.environmentId,
+    bearerSession.sessionToken,
+  );
+  if (!didPersistBearerToken) {
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
+    throw new Error("Unable to persist saved environment credentials.");
+  }
+
+  return {
+    record: prepared.record,
+    bearerToken: bearerSession.sessionToken,
+    role: bearerSession.role ?? null,
+  };
+}
+
 function setRuntimeConnecting(environmentId: EnvironmentId) {
   useSavedEnvironmentRuntimeStore.getState().patch(environmentId, {
     connectionState: "connecting",
@@ -169,17 +902,20 @@ function coalesceOrchestrationUiEvents(
   return coalesced;
 }
 
-function reconcileSnapshotDerivedState() {
-  const storeState = useStore.getState();
-  const threads = selectThreadsAcrossEnvironments(storeState);
-  const projects = selectProjectsAcrossEnvironments(storeState);
-
+function syncProjectUiFromStore() {
+  const projects = selectProjectsAcrossEnvironments(useStore.getState());
+  const clientSettings = getClientSettings();
   useUiStateStore.getState().syncProjects(
     projects.map((project) => ({
-      key: scopedProjectKey(scopeProjectRef(project.environmentId, project.id)),
+      key: derivePhysicalProjectKey(project),
+      logicalKey: deriveLogicalProjectKeyFromSettings(project, clientSettings),
       cwd: project.cwd,
     })),
   );
+}
+
+function syncThreadUiFromStore() {
+  const threads = selectThreadsAcrossEnvironments(useStore.getState());
   useUiStateStore.getState().syncThreads(
     threads.map((thread) => ({
       key: scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
@@ -189,7 +925,13 @@ function reconcileSnapshotDerivedState() {
   markPromotedDraftThreadsByRef(
     threads.map((thread) => scopeThreadRef(thread.environmentId, thread.id)),
   );
+}
+
+function reconcileSnapshotDerivedState() {
+  syncProjectUiFromStore();
+  syncThreadUiFromStore();
 
+  const threads = selectThreadsAcrossEnvironments(useStore.getState());
   const activeThreadKeys = collectActiveTerminalThreadIds({
     snapshotThreads: threads.map((thread) => ({
       key: scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
@@ -237,9 +979,11 @@ function applyRecoveredEventBatch(
   useStore.getState().applyOrchestrationEvents(uiEvents, environmentId);
   if (needsProjectUiSync) {
     const projects = selectProjectsAcrossEnvironments(useStore.getState());
+    const clientSettings = getClientSettings();
     useUiStateStore.getState().syncProjects(
       projects.map((project) => ({
-        key: scopedProjectKey(scopeProjectRef(project.environmentId, project.id)),
+        key: derivePhysicalProjectKey(project),
+        logicalKey: deriveLogicalProjectKeyFromSettings(project, clientSettings),
         cwd: project.cwd,
       })),
     );
@@ -268,16 +1012,95 @@ function applyRecoveredEventBatch(
       .getState()
       .clearThreadUi(scopedThreadKey(scopeThreadRef(environmentId, threadId)));
   }
+  for (const event of events) {
+    if (event.type === "project.deleted") {
+      draftStore.clearProjectDraftThreadId(scopeProjectRef(environmentId, event.payload.projectId));
+    }
+  }
   for (const threadId of batchEffects.removeTerminalStateThreadIds) {
     useTerminalStateStore.getState().removeTerminalState(scopeThreadRef(environmentId, threadId));
   }
+
+  reconcileThreadDetailSubscriptionEvictionForEnvironment(environmentId);
+}
+
+export function applyEnvironmentThreadDetailEvent(
+  event: OrchestrationEvent,
+  environmentId: EnvironmentId,
+) {
+  applyRecoveredEventBatch([event], environmentId);
+}
+
+function applyShellEvent(event: OrchestrationShellStreamEvent, environmentId: EnvironmentId) {
+  if (
+    !shouldApplyProjectionEvent({
+      current: readLastAppliedProjectionVersion(environmentId),
+      sequence: event.sequence,
+    })
+  ) {
+    return;
+  }
+
+  const threadId =
+    event.kind === "thread-upserted"
+      ? event.thread.id
+      : event.kind === "thread-removed"
+        ? event.threadId
+        : null;
+  const threadRef = threadId ? scopeThreadRef(environmentId, threadId) : null;
+  const previousThread = threadRef ? selectThreadByRef(useStore.getState(), threadRef) : undefined;
+
+  useStore.getState().applyShellEvent(event, environmentId);
+  markAppliedProjectionEvent(environmentId, event.sequence);
+
+  switch (event.kind) {
+    case "project-upserted":
+    case "project-removed":
+      syncProjectUiFromStore();
+      return;
+    case "thread-upserted":
+      syncThreadUiFromStore();
+      if (!previousThread && threadRef) {
+        markPromotedDraftThreadByRef(threadRef);
+      }
+      if (previousThread?.archivedAt === null && event.thread.archivedAt !== null && threadRef) {
+        useTerminalStateStore.getState().removeTerminalState(threadRef);
+      }
+      reconcileThreadDetailSubscriptionEvictionForThread(environmentId, event.thread.id);
+      evictIdleThreadDetailSubscriptionsToCapacity();
+      return;
+    case "thread-removed":
+      if (threadRef) {
+        disposeThreadDetailSubscriptionByKey(scopedThreadKey(threadRef));
+        useComposerDraftStore.getState().clearDraftThread(threadRef);
+        useUiStateStore.getState().clearThreadUi(scopedThreadKey(threadRef));
+        useTerminalStateStore.getState().removeTerminalState(threadRef);
+      }
+      syncThreadUiFromStore();
+      return;
+  }
 }
 
 function createEnvironmentConnectionHandlers() {
   return {
-    applyEventBatch: applyRecoveredEventBatch,
-    syncSnapshot: (snapshot: OrchestrationReadModel, environmentId: EnvironmentId) => {
-      useStore.getState().syncServerReadModel(snapshot, environmentId);
+    applyShellEvent,
+    syncShellSnapshot: (snapshot: OrchestrationShellSnapshot, environmentId: EnvironmentId) => {
+      if (
+        !shouldApplyProjectionSnapshot({
+          current: readLastAppliedProjectionVersion(environmentId),
+          next: snapshot,
+        })
+      ) {
+        return;
+      }
+
+      useStore.getState().syncServerShellSnapshot(snapshot, environmentId);
+      markAppliedProjectionSnapshot(environmentId, snapshot);
+      reconcileThreadDetailSubscriptionsForEnvironment(
+        environmentId,
+        snapshot.threads.map((thread) => thread.id),
+      );
+      reconcileThreadDetailSubscriptionEvictionForEnvironment(environmentId);
       reconcileSnapshotDerivedState();
     },
     applyTerminalEvent: (event: TerminalEvent, environmentId: EnvironmentId) => {
@@ -307,40 +1130,80 @@ function createPrimaryEnvironmentClient(
       `Unable to resolve websocket URL for ${knownEnvironment?.label ?? "primary environment"}.`,
     );
   }
+  const connectionLabel = knownEnvironment?.label ?? null;
 
-  return createWsRpcClient(new WsTransport(wsBaseUrl));
+  return createWsRpcClient(
+    new WsTransport(wsBaseUrl, {
+      getConnectionLabel: () => connectionLabel,
+      getVersionMismatchHint: () =>
+        resolveServerConfigVersionMismatch(getServerConfig())?.hint ?? null,
+    }),
+  );
 }
 
 function createSavedEnvironmentClient(
-  record: SavedEnvironmentRecord,
+  environmentId: EnvironmentId,
   bearerToken: string,
 ): WsRpcClient {
-  useSavedEnvironmentRuntimeStore.getState().ensure(record.environmentId);
+  useSavedEnvironmentRuntimeStore.getState().ensure(environmentId);
 
   return createWsRpcClient(
     new WsTransport(
-      () =>
-        resolveRemoteWebSocketConnectionUrl({
-          wsBaseUrl: record.wsBaseUrl,
-          httpBaseUrl: record.httpBaseUrl,
-          bearerToken,
-        }),
+      async () => {
+        const record = getSavedEnvironmentRecord(environmentId);
+        if (!record) {
+          throw new Error(`Saved environment ${environmentId} not found.`);
+        }
+        return record.desktopSsh
+          ? await resolveDesktopSshWebSocketConnectionUrl(
+              record.wsBaseUrl,
+              record.httpBaseUrl,
+              bearerToken,
+            )
+          : await resolveRemoteWebSocketConnectionUrl({
+              wsBaseUrl: record.wsBaseUrl,
+              httpBaseUrl: record.httpBaseUrl,
+              bearerToken,
+            });
+      },
       {
+        getConnectionLabel: () => getSavedEnvironmentRecord(environmentId)?.label ?? null,
+        getVersionMismatchHint: () =>
+          resolveServerConfigVersionMismatch(
+            useSavedEnvironmentRuntimeStore.getState().byId[environmentId]?.serverConfig,
+          )?.hint ?? null,
         onAttempt: () => {
-          setRuntimeConnecting(record.environmentId);
+          setRuntimeConnecting(environmentId);
         },
         onOpen: () => {
-          setRuntimeConnected(record.environmentId);
+          setRuntimeConnected(environmentId);
         },
         onError: (message: string) => {
-          useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
+          const mismatch = resolveServerConfigVersionMismatch(
+            useSavedEnvironmentRuntimeStore.getState().byId[environmentId]?.serverConfig,
+          );
+          useSavedEnvironmentRuntimeStore.getState().patch(environmentId, {
             connectionState: "error",
-            lastError: message,
+            lastError: appendVersionMismatchHint(message, mismatch),
             lastErrorAt: isoNow(),
           });
         },
-        onClose: (details: { readonly code: number; readonly reason: string }) => {
-          setRuntimeDisconnected(record.environmentId, details.reason);
+        onClose: (
+          details: { readonly code: number; readonly reason: string },
+          context: WsProtocolCloseContext,
+        ) => {
+          if (context.intentional) {
+            return;
+          }
+          setRuntimeDisconnected(
+            environmentId,
+            appendVersionMismatchHint(
+              details.reason,
+              resolveServerConfigVersionMismatch(
+                useSavedEnvironmentRuntimeStore.getState().byId[environmentId]?.serverConfig,
+              ),
+            ),
+          );
         },
       },
     ),
@@ -348,18 +1211,25 @@ function createSavedEnvironmentClient(
 }
 
 async function refreshSavedEnvironmentMetadata(
-  record: SavedEnvironmentRecord,
+  environmentId: EnvironmentId,
   bearerToken: string,
   client: WsRpcClient,
   roleHint?: AuthSessionRole | null,
   configHint?: ServerConfig | null,
 ): Promise<void> {
+  const record = getSavedEnvironmentRecord(environmentId);
+  if (!record) {
+    throw new Error(`Saved environment ${environmentId} not found.`);
+  }
+
   const [serverConfig, sessionState] = await Promise.all([
     configHint ? Promise.resolve(configHint) : client.server.getConfig(),
-    fetchRemoteSessionState({
-      httpBaseUrl: record.httpBaseUrl,
-      bearerToken,
-    }),
+    record.desktopSsh
+      ? fetchDesktopSshSessionState(record.httpBaseUrl, bearerToken)
+      : fetchRemoteSessionState({
+          httpBaseUrl: record.httpBaseUrl,
+          bearerToken,
+        }),
   ]);
 
   useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
@@ -368,6 +1238,9 @@ async function refreshSavedEnvironmentMetadata(
     serverConfig,
     role: sessionState.authenticated ? (sessionState.role ?? roleHint ?? null) : null,
   });
+  useSavedEnvironmentRegistryStore
+    .getState()
+    .rename(record.environmentId, serverConfig.environment.label);
 }
 
 function registerConnection(connection: EnvironmentConnection): EnvironmentConnection {
@@ -376,6 +1249,7 @@ function registerConnection(connection: EnvironmentConnection): EnvironmentConne
     throw new Error(`Environment ${connection.environmentId} already has an active connection.`);
   }
   environmentConnections.set(connection.environmentId, connection);
+  attachThreadDetailSubscriptionsForEnvironment(connection.environmentId);
   emitEnvironmentConnectionRegistryChange();
   return connection;
 }
@@ -386,8 +1260,10 @@ async function removeConnection(environmentId: EnvironmentId): Promise<boolean>
     return false;
   }
 
+  lastAppliedProjectionVersionByEnvironment.delete(environmentId);
   environmentConnections.delete(environmentId);
   emitEnvironmentConnectionRegistryChange();
+  detachThreadDetailSubscriptionsForEnvironment(environmentId);
   await connection.dispose();
   return true;
 }
@@ -413,6 +1289,10 @@ function createPrimaryEnvironmentConnection(): EnvironmentConnection {
   );
 }
 
+function maybeCreatePrimaryEnvironmentConnection(): EnvironmentConnection | null {
+  return getPrimaryKnownEnvironment()?.environmentId ? createPrimaryEnvironmentConnection() : null;
+}
+
 async function ensureSavedEnvironmentConnection(
   record: SavedEnvironmentRecord,
   options?: {
@@ -427,69 +1307,152 @@ async function ensureSavedEnvironmentConnection(
     return existing;
   }
 
-  const bearerToken =
-    options?.bearerToken ?? (await readSavedEnvironmentBearerToken(record.environmentId));
-  if (!bearerToken) {
-    useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
-      authState: "requires-auth",
-      role: null,
-      connectionState: "disconnected",
-      lastError: "Saved environment is missing its saved credential. Pair it again.",
-      lastErrorAt: isoNow(),
-    });
-    throw new Error("Saved environment is missing its saved credential.");
+  const pending = pendingSavedEnvironmentConnections.get(record.environmentId);
+  if (pending) {
+    return pending.promise;
   }
 
-  const client = options?.client ?? createSavedEnvironmentClient(record, bearerToken);
-  const knownEnvironment = createKnownEnvironment({
-    id: record.environmentId,
-    label: record.label,
-    source: "manual",
-    target: {
-      httpBaseUrl: record.httpBaseUrl,
-      wsBaseUrl: record.wsBaseUrl,
-    },
-  });
-  const connection = createEnvironmentConnection({
-    kind: "saved",
-    knownEnvironment: {
-      ...knownEnvironment,
-      environmentId: record.environmentId,
-    },
-    client,
-    refreshMetadata: async () => {
-      await refreshSavedEnvironmentMetadata(record, bearerToken, client);
-    },
-    onConfigSnapshot: (config) => {
-      useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
-        descriptor: config.environment,
-        serverConfig: config,
+  const pendingEntry: PendingSavedEnvironmentConnection = {
+    cancelled: false,
+    promise: Promise.resolve().then(async () => {
+      let activeRecord = record;
+      let roleHint = options?.role ?? null;
+      let bearerToken =
+        options?.bearerToken ?? (await readSavedEnvironmentBearerToken(record.environmentId));
+      if (!bearerToken) {
+        if (record.desktopSsh) {
+          const issued = await issueDesktopSshBearerSession(record);
+          activeRecord = issued.record;
+          bearerToken = issued.bearerToken;
+          roleHint = issued.role;
+        } else {
+          useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
+            authState: "requires-auth",
+            role: null,
+            connectionState: "disconnected",
+            lastError: "Saved environment is missing its saved credential. Pair it again.",
+            lastErrorAt: isoNow(),
+          });
+          throw new Error("Saved environment is missing its saved credential.");
+        }
+      } else {
+        const prepared = await prepareSavedEnvironmentRecordForConnection(record);
+        activeRecord = prepared.record;
+      }
+
+      const activeBearerToken = bearerToken;
+      const client =
+        options?.client ??
+        createSavedEnvironmentClient(activeRecord.environmentId, activeBearerToken);
+      const initialConfigSnapshot = createDeferredPromise<ServerConfig>();
+      const knownEnvironment = createKnownEnvironment({
+        id: activeRecord.environmentId,
+        label: activeRecord.label,
+        source: "manual",
+        target: {
+          httpBaseUrl: activeRecord.httpBaseUrl,
+          wsBaseUrl: activeRecord.wsBaseUrl,
+        },
       });
-    },
-    onWelcome: (payload) => {
-      useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
-        descriptor: payload.environment,
+      const connection = createEnvironmentConnection({
+        kind: "saved",
+        knownEnvironment: {
+          ...knownEnvironment,
+          environmentId: activeRecord.environmentId,
+        },
+        client,
+        refreshMetadata: async () => {
+          await refreshSavedEnvironmentMetadata(
+            activeRecord.environmentId,
+            activeBearerToken,
+            client,
+          );
+        },
+        onConfigSnapshot: (config) => {
+          initialConfigSnapshot.resolve(config);
+          useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
+            descriptor: config.environment,
+            serverConfig: config,
+          });
+        },
+        onWelcome: (payload) => {
+          useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
+            descriptor: payload.environment,
+          });
+        },
+        ...createEnvironmentConnectionHandlers(),
       });
-    },
-    ...createEnvironmentConnectionHandlers(),
-  });
 
-  registerConnection(connection);
+      try {
+        try {
+          const initialServerConfig =
+            options?.serverConfig ??
+            (await waitForConfigSnapshot(
+              initialConfigSnapshot.promise,
+              INITIAL_SERVER_CONFIG_SNAPSHOT_WAIT_MS,
+            ));
+          await refreshSavedEnvironmentMetadata(
+            activeRecord.environmentId,
+            activeBearerToken,
+            client,
+            roleHint,
+            initialServerConfig,
+          );
+        } catch (error) {
+          const isAuthError = activeRecord.desktopSsh
+            ? isSshHttpAuthError(error, 401)
+            : isRemoteEnvironmentAuthHttpError(error) && error.status === 401;
+          if (!isAuthError) {
+            throw error;
+          }
+          if (!activeRecord.desktopSsh) {
+            await removeSavedEnvironmentBearerToken(activeRecord.environmentId);
+            throw new Error("Saved environment credential expired. Pair it again.", {
+              cause: error,
+            });
+          }
+
+          const issued = await issueDesktopSshBearerSession(activeRecord);
+          activeRecord = issued.record;
+          bearerToken = issued.bearerToken;
+          roleHint = issued.role;
+          await connection.dispose().catch(() => undefined);
+          pendingSavedEnvironmentConnections.delete(activeRecord.environmentId);
+          return await ensureSavedEnvironmentConnection(activeRecord, {
+            bearerToken,
+            role: roleHint,
+            serverConfig: options?.serverConfig ?? null,
+          });
+        }
+        if (
+          pendingEntry.cancelled ||
+          pendingSavedEnvironmentConnections.get(activeRecord.environmentId) !== pendingEntry
+        ) {
+          await connection.dispose().catch(() => undefined);
+          throw new SavedEnvironmentConnectionCancelledError(activeRecord.environmentId);
+        }
+        registerConnection(connection);
+        return connection;
+      } catch (error) {
+        if (error instanceof SavedEnvironmentConnectionCancelledError) {
+          throw error;
+        }
+        setRuntimeError(activeRecord.environmentId, error);
+        const removed = await removeConnection(activeRecord.environmentId).catch(() => false);
+        if (!removed) {
+          await connection.dispose().catch(() => undefined);
+        }
+        throw error;
+      }
+    }),
+  };
 
-  try {
-    await refreshSavedEnvironmentMetadata(
-      record,
-      bearerToken,
-      client,
-      options?.role ?? null,
-      options?.serverConfig ?? null,
-    );
-    return connection;
-  } catch (error) {
-    setRuntimeError(record.environmentId, error);
-    await removeConnection(record.environmentId).catch(() => false);
-    throw error;
-  }
+  pendingSavedEnvironmentConnections.set(record.environmentId, pendingEntry);
+  return await pendingEntry.promise.finally(() => {
+    if (pendingSavedEnvironmentConnections.get(record.environmentId) === pendingEntry) {
+      pendingSavedEnvironmentConnections.delete(record.environmentId);
+    }
+  });
 }
 
 async function syncSavedEnvironmentConnections(
@@ -514,6 +1477,58 @@ function stopActiveService() {
   activeService = null;
 }
 
+function reconnectEnvironmentConnectionsAfterBrowserResume(reason: string): void {
+  const now = Date.now();
+  if (now - lastBrowserResumeReconnectAt < BROWSER_RESUME_RECONNECT_COOLDOWN_MS) {
+    return;
+  }
+
+  for (const connection of environmentConnections.values()) {
+    if (connection.client.isHeartbeatFresh()) {
+      continue;
+    }
+    lastBrowserResumeReconnectAt = now;
+    void connection.reconnect().catch((error) => {
+      console.warn("Environment reconnect after browser resume failed", {
+        environmentId: connection.environmentId,
+        reason,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  }
+}
+
+function subscribeBrowserResumeReconnects(): () => void {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return NOOP;
+  }
+
+  const handleVisibilityChange = () => {
+    if (document.visibilityState === "hidden") {
+      lastBrowserHiddenAt = Date.now();
+      return;
+    }
+    if (document.visibilityState === "visible" && lastBrowserHiddenAt !== null) {
+      lastBrowserHiddenAt = null;
+      reconnectEnvironmentConnectionsAfterBrowserResume("visibilitychange");
+    }
+  };
+
+  const handlePageShow = (event: PageTransitionEvent) => {
+    if (event.persisted || lastBrowserHiddenAt !== null) {
+      lastBrowserHiddenAt = null;
+      reconnectEnvironmentConnectionsAfterBrowserResume("pageshow");
+    }
+  };
+
+  document.addEventListener("visibilitychange", handleVisibilityChange);
+  window.addEventListener("pageshow", handlePageShow);
+  return () => {
+    document.removeEventListener("visibilitychange", handleVisibilityChange);
+    window.removeEventListener("pageshow", handlePageShow);
+  };
+}
+
 export function subscribeEnvironmentConnections(listener: () => void): () => void {
   environmentConnectionListeners.add(listener);
   return () => {
@@ -544,13 +1559,23 @@ export function getPrimaryEnvironmentConnection(): EnvironmentConnection {
 }
 
 export async function disconnectSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
+  const record = getSavedEnvironmentRecord(environmentId);
+  const pendingConnection = pendingSavedEnvironmentConnections.get(environmentId);
+  if (pendingConnection) {
+    pendingConnection.cancelled = true;
+    pendingSavedEnvironmentConnections.delete(environmentId);
+  }
   const connection = environmentConnections.get(environmentId);
-  if (connection?.kind !== "saved") {
-    return;
+
+  if (connection?.kind === "saved") {
+    await removeConnection(environmentId).catch(() => false);
   }
+  setRuntimeDisconnected(environmentId);
 
-  useSavedEnvironmentRuntimeStore.getState().clear(environmentId);
-  await removeConnection(environmentId).catch(() => false);
+  if (record?.desktopSsh && typeof window !== "undefined") {
+    await window.desktopBridge?.disconnectSshEnvironment(record.desktopSsh);
+    await removeSavedEnvironmentBearerToken(environmentId);
+  }
 }
 
 export async function reconnectSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
@@ -561,23 +1586,57 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
 
   const connection = environmentConnections.get(environmentId);
   if (!connection) {
-    await ensureSavedEnvironmentConnection(record);
-    return;
+    setRuntimeConnecting(environmentId);
+    try {
+      await ensureSavedEnvironmentConnection(record);
+      return;
+    } catch (error) {
+      if (isSavedEnvironmentConnectionCancelledError(error)) {
+        return;
+      }
+      setRuntimeError(environmentId, error);
+      throw error;
+    }
   }
 
   setRuntimeConnecting(environmentId);
   try {
+    if (record.desktopSsh) {
+      await prepareSavedEnvironmentRecordForConnection(record);
+    }
     await connection.reconnect();
   } catch (error) {
+    if (record.desktopSsh) {
+      try {
+        const issued = await issueDesktopSshBearerSession(
+          getSavedEnvironmentRecord(environmentId) ?? record,
+        );
+        await removeConnection(environmentId).catch(() => false);
+        await ensureSavedEnvironmentConnection(issued.record, {
+          bearerToken: issued.bearerToken,
+          role: issued.role,
+        });
+        return;
+      } catch (recoveryError) {
+        if (isSavedEnvironmentConnectionCancelledError(recoveryError)) {
+          return;
+        }
+        setRuntimeError(environmentId, recoveryError);
+        throw recoveryError;
+      }
+    }
     setRuntimeError(environmentId, error);
     throw error;
   }
 }
 
 export async function removeSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
+  await disconnectSavedEnvironment(environmentId);
+  disposeThreadDetailSubscriptionsForEnvironment(environmentId);
   useSavedEnvironmentRegistryStore.getState().remove(environmentId);
+  useSavedEnvironmentRuntimeStore.getState().clear(environmentId);
+  useStore.getState().removeEnvironmentState(environmentId);
   await removeSavedEnvironmentBearerToken(environmentId);
-  await disconnectSavedEnvironment(environmentId);
 }
 
 export async function addSavedEnvironment(input: {
@@ -585,33 +1644,43 @@ export async function addSavedEnvironment(input: {
   readonly pairingUrl?: string;
   readonly host?: string;
   readonly pairingCode?: string;
+  readonly desktopSsh?: DesktopSshEnvironmentTarget;
 }): Promise<SavedEnvironmentRecord> {
   const resolvedTarget = resolveRemotePairingTarget({
     ...(input.pairingUrl !== undefined ? { pairingUrl: input.pairingUrl } : {}),
     ...(input.host !== undefined ? { host: input.host } : {}),
     ...(input.pairingCode !== undefined ? { pairingCode: input.pairingCode } : {}),
   });
-  const descriptor = await fetchRemoteEnvironmentDescriptor({
-    httpBaseUrl: resolvedTarget.httpBaseUrl,
-  });
+  const descriptor = input.desktopSsh
+    ? await fetchDesktopSshEnvironmentDescriptor(resolvedTarget.httpBaseUrl)
+    : await fetchRemoteEnvironmentDescriptor({
+        httpBaseUrl: resolvedTarget.httpBaseUrl,
+      });
   const environmentId = descriptor.environmentId;
-
-  if (environmentConnections.has(environmentId)) {
-    throw new Error("This environment is already connected.");
-  }
-
-  const bearerSession = await bootstrapRemoteBearerSession({
-    httpBaseUrl: resolvedTarget.httpBaseUrl,
-    credential: resolvedTarget.credential,
-  });
+  const registrySnapshot = snapshotSavedEnvironmentRegistry([environmentId]);
+  const existingRecord =
+    getSavedEnvironmentRecord(environmentId) ??
+    findSavedEnvironmentRecordByDesktopSshTarget(input.desktopSsh);
+  const staleDesktopSshRecord =
+    existingRecord && existingRecord.environmentId !== environmentId ? existingRecord : null;
+
+  const bearerSession = input.desktopSsh
+    ? await bootstrapDesktopSshBearerSession(resolvedTarget.httpBaseUrl, resolvedTarget.credential)
+    : await bootstrapRemoteBearerSession({
+        httpBaseUrl: resolvedTarget.httpBaseUrl,
+        credential: resolvedTarget.credential,
+      });
 
   const record: SavedEnvironmentRecord = {
     environmentId,
-    label: input.label.trim() || descriptor.label,
+    label: input.label.trim() || existingRecord?.label || descriptor.label,
     wsBaseUrl: resolvedTarget.wsBaseUrl,
     httpBaseUrl: resolvedTarget.httpBaseUrl,
-    createdAt: isoNow(),
+    createdAt: existingRecord?.createdAt ?? isoNow(),
     lastConnectedAt: isoNow(),
+    ...((input.desktopSsh ?? existingRecord?.desktopSsh)
+      ? { desktopSsh: input.desktopSsh ?? existingRecord?.desktopSsh }
+      : {}),
   };
 
   await persistSavedEnvironmentRecord(record);
@@ -620,26 +1689,50 @@ export async function addSavedEnvironment(input: {
     bearerSession.sessionToken,
   );
   if (!didPersistBearerToken) {
-    await ensureLocalApi().persistence.setSavedEnvironmentRegistry(
-      listSavedEnvironmentRecords().map((entry) => ({
-        environmentId: entry.environmentId,
-        label: entry.label,
-        httpBaseUrl: entry.httpBaseUrl,
-        wsBaseUrl: entry.wsBaseUrl,
-        createdAt: entry.createdAt,
-        lastConnectedAt: entry.lastConnectedAt,
-      })),
-    );
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
     throw new Error("Unable to persist saved environment credentials.");
   }
+  useSavedEnvironmentRegistryStore.getState().upsert(record);
+  if (staleDesktopSshRecord) {
+    await removeSavedEnvironment(staleDesktopSshRecord.environmentId);
+  }
+  await removeConnection(environmentId).catch(() => false);
   await ensureSavedEnvironmentConnection(record, {
     bearerToken: bearerSession.sessionToken,
     role: bearerSession.role,
   });
-  useSavedEnvironmentRegistryStore.getState().upsert(record);
   return record;
 }
 
+export async function connectDesktopSshEnvironment(
+  target: DesktopSshEnvironmentTarget,
+  options?: { label?: string },
+): Promise<SavedEnvironmentRecord> {
+  const bootstrap = await resolveDesktopSshEnvironmentBootstrap(target, {
+    issuePairingToken: true,
+  });
+  if (!bootstrap.pairingToken) {
+    throw new Error("Desktop SSH launch did not return a pairing token.");
+  }
+
+  return await addSavedEnvironment({
+    label: options?.label?.trim() || bootstrap.target.alias,
+    host: bootstrap.httpBaseUrl,
+    pairingCode: bootstrap.pairingToken,
+    desktopSsh: bootstrap.target,
+  }).catch((error) => {
+    const detail = [
+      `local ${bootstrap.httpBaseUrl}`,
+      `remote port ${bootstrap.remotePort ?? "unknown"}`,
+      bootstrap.remoteServerKind ? `remote server ${bootstrap.remoteServerKind}` : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message} (${detail})`);
+  });
+}
+
 export async function ensureEnvironmentConnectionBootstrapped(
   environmentId: EnvironmentId,
 ): Promise<void> {
@@ -677,26 +1770,30 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
       trailing: true,
     },
   );
+  const requestSavedEnvironmentSync = createSavedEnvironmentSyncScheduler();
 
-  createPrimaryEnvironmentConnection();
+  maybeCreatePrimaryEnvironmentConnection();
 
   const unsubscribeSavedEnvironments = useSavedEnvironmentRegistryStore.subscribe(() => {
     if (!hasSavedEnvironmentRegistryHydrated()) {
       return;
     }
-    void syncSavedEnvironmentConnections(listSavedEnvironmentRecords());
+    void requestSavedEnvironmentSync();
   });
 
   void waitForSavedEnvironmentRegistryHydration()
-    .then(() => syncSavedEnvironmentConnections(listSavedEnvironmentRecords()))
+    .then(() => requestSavedEnvironmentSync())
     .catch(() => undefined);
 
+  const unsubscribeBrowserResumeReconnects = subscribeBrowserResumeReconnects();
+
   activeService = {
     queryClient,
     queryInvalidationThrottler,
     refCount: 1,
     stop: () => {
       unsubscribeSavedEnvironments();
+      unsubscribeBrowserResumeReconnects();
       queryInvalidationThrottler.cancel();
     },
   };
@@ -714,6 +1811,13 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
 
 export async function resetEnvironmentServiceForTests(): Promise<void> {
   stopActiveService();
+  lastBrowserHiddenAt = null;
+  lastBrowserResumeReconnectAt = Number.NEGATIVE_INFINITY;
+  lastAppliedProjectionVersionByEnvironment.clear();
+  pendingSavedEnvironmentConnections.clear();
+  for (const key of Array.from(threadDetailSubscriptions.keys())) {
+    disposeThreadDetailSubscriptionByKey(key);
+  }
   await Promise.all(
     [...environmentConnections.keys()].map((environmentId) => removeConnection(environmentId)),
   );
diff --git a/apps/web/src/filePathDisplay.test.ts b/apps/web/src/filePathDisplay.test.ts
new file mode 100644
index 00000000000..c196b5677b5
--- /dev/null
+++ b/apps/web/src/filePathDisplay.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+
+import { formatWorkspaceRelativePath } from "./filePathDisplay";
+
+describe("formatWorkspaceRelativePath", () => {
+  it("formats absolute workspace paths from the workspace root", () => {
+    expect(
+      formatWorkspaceRelativePath(
+        "C:/Users/mike/dev-stuff/t3code/apps/web/src/session-logic.ts:501",
+        "C:/Users/mike/dev-stuff/t3code",
+      ),
+    ).toBe("t3code/apps/web/src/session-logic.ts:501");
+  });
+
+  it("prefixes relative paths with the workspace root label", () => {
+    expect(
+      formatWorkspaceRelativePath(
+        "apps/web/src/session-logic.ts:501",
+        "C:/Users/mike/dev-stuff/t3code",
+      ),
+    ).toBe("t3code/apps/web/src/session-logic.ts:501");
+  });
+
+  it("keeps paths already rooted at the workspace label stable", () => {
+    expect(
+      formatWorkspaceRelativePath(
+        "t3code/apps/web/src/session-logic.ts:501",
+        "C:/Users/mike/dev-stuff/t3code",
+      ),
+    ).toBe("t3code/apps/web/src/session-logic.ts:501");
+  });
+
+  it("preserves columns when present", () => {
+    expect(
+      formatWorkspaceRelativePath(
+        "/C:/Users/mike/dev-stuff/t3code/apps/web/src/session-logic.ts:501:9",
+        "C:/Users/mike/dev-stuff/t3code",
+      ),
+    ).toBe("t3code/apps/web/src/session-logic.ts:501:9");
+  });
+});
diff --git a/apps/web/src/filePathDisplay.ts b/apps/web/src/filePathDisplay.ts
new file mode 100644
index 00000000000..5a6e2a02e10
--- /dev/null
+++ b/apps/web/src/filePathDisplay.ts
@@ -0,0 +1,57 @@
+import { splitPathAndPosition } from "./terminal-links";
+
+function normalizePathSeparators(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+function canonicalizeWindowsDrivePath(path: string): string {
+  return /^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path;
+}
+
+function trimTrailingPathSeparators(path: string): string {
+  return path.replace(/[\\/]+$/, "");
+}
+
+function basenameOfPath(path: string): string {
+  const separatorIndex = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return separatorIndex >= 0 ? path.slice(separatorIndex + 1) : path;
+}
+
+function stripRelativePrefixes(path: string): string {
+  return path.replace(/^\.\/+/, "").replace(/^\/+/, "");
+}
+
+export function formatWorkspaceRelativePath(
+  pathWithPosition: string,
+  workspaceRoot: string | undefined,
+): string {
+  const { path, line, column } = splitPathAndPosition(pathWithPosition);
+  const normalizedPath = canonicalizeWindowsDrivePath(normalizePathSeparators(path));
+
+  let displayPath = normalizedPath;
+  if (workspaceRoot) {
+    const normalizedWorkspaceRoot = canonicalizeWindowsDrivePath(
+      normalizePathSeparators(trimTrailingPathSeparators(workspaceRoot)),
+    );
+    const workspaceLabel = basenameOfPath(normalizedWorkspaceRoot);
+    const pathForCompare = normalizedPath.toLowerCase();
+    const workspaceForCompare = normalizedWorkspaceRoot.toLowerCase();
+    const workspaceWithSeparator = `${workspaceForCompare}/`;
+    const workspaceLabelWithSeparator = `${workspaceLabel.toLowerCase()}/`;
+
+    if (pathForCompare === workspaceForCompare) {
+      displayPath = workspaceLabel;
+    } else if (pathForCompare.startsWith(workspaceWithSeparator)) {
+      const relativeSuffix = normalizedPath.slice(normalizedWorkspaceRoot.length + 1);
+      displayPath = `${workspaceLabel}/${relativeSuffix}`;
+    } else if (!normalizedPath.startsWith("/")) {
+      const relativePath = stripRelativePrefixes(normalizedPath);
+      displayPath = pathForCompare.startsWith(workspaceLabelWithSeparator)
+        ? normalizedPath
+        : `${workspaceLabel}/${relativePath}`;
+    }
+  }
+
+  if (!line) return displayPath;
+  return `${displayPath}:${line}${column ? `:${column}` : ""}`;
+}
diff --git a/apps/web/src/hooks/useCommitOnBlur.ts b/apps/web/src/hooks/useCommitOnBlur.ts
new file mode 100644
index 00000000000..43244762aa1
--- /dev/null
+++ b/apps/web/src/hooks/useCommitOnBlur.ts
@@ -0,0 +1,49 @@
+import { type ChangeEvent, type KeyboardEvent, useEffect, useRef, useState } from "react";
+
+/**
+ * Buffer text input locally so keystrokes don't cause a settings-wide
+ * re-render (and optionally a server RPC round-trip) on every character.
+ * `onCommit` fires on blur and on Enter.
+ *
+ * The draft resynchronizes from the upstream `value` only when the input
+ * is not focused, so an external push (e.g. an optimistic settings
+ * update from the user's own commit, or a reset to defaults) doesn't
+ * clobber an in-progress edit.
+ *
+ * Returns a bag of props that should be spread onto an `<Input>`:
+ *
+ *   const bag = useCommitOnBlur(instance.displayName ?? "", (next) => {...});
+ *   <Input {...bag} placeholder="e.g. Work" />
+ */
+export function useCommitOnBlur(value: string, onCommit: (next: string) => void) {
+  const [draft, setDraft] = useState(value);
+  const focusedRef = useRef(false);
+
+  useEffect(() => {
+    if (!focusedRef.current) {
+      setDraft(value);
+    }
+  }, [value]);
+
+  return {
+    value: draft,
+    onChange: (event: ChangeEvent<HTMLInputElement>) => {
+      setDraft(event.target.value);
+    },
+    onFocus: () => {
+      focusedRef.current = true;
+    },
+    onBlur: () => {
+      focusedRef.current = false;
+      if (draft !== value) {
+        onCommit(draft);
+      }
+    },
+    onKeyDown: (event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === "Enter") {
+        event.preventDefault();
+        (event.target as HTMLInputElement).blur();
+      }
+    },
+  };
+}
diff --git a/apps/web/src/hooks/useHandleNewThread.ts b/apps/web/src/hooks/useHandleNewThread.ts
index 6856140daaa..e440497ba42 100644
--- a/apps/web/src/hooks/useHandleNewThread.ts
+++ b/apps/web/src/hooks/useHandleNewThread.ts
@@ -10,14 +10,20 @@ import {
 } from "../composerDraftStore";
 import { newDraftId, newThreadId } from "../lib/utils";
 import { orderItemsByPreferredIds } from "../components/Sidebar.logic";
-import { deriveLogicalProjectKey } from "../logicalProject";
+import {
+  deriveLogicalProjectKeyFromSettings,
+  getProjectOrderKey,
+  selectProjectGroupingSettings,
+} from "../logicalProject";
 import { selectProjectsAcrossEnvironments, useStore } from "../store";
 import { createThreadSelectorByRef } from "../storeSelectors";
 import { resolveThreadRouteTarget } from "../threadRoutes";
 import { useUiStateStore } from "../uiStateStore";
+import { useSettings } from "./useSettings";
 
 function useNewThreadState() {
   const projects = useStore(useShallow((store) => selectProjectsAcrossEnvironments(store)));
+  const projectGroupingSettings = useSettings(selectProjectGroupingSettings);
   const router = useRouter();
   const getCurrentRouteTarget = useCallback(() => {
     const currentRouteParams = router.state.matches[router.state.matches.length - 1]?.params ?? {};
@@ -48,7 +54,7 @@ function useNewThreadState() {
           candidate.environmentId === projectRef.environmentId,
       );
       const logicalProjectKey = project
-        ? deriveLogicalProjectKey(project)
+        ? deriveLogicalProjectKeyFromSettings(project, projectGroupingSettings)
         : scopedProjectKey(projectRef);
       const hasBranchOption = options?.branch !== undefined;
       const hasWorktreePathOption = options?.worktreePath !== undefined;
@@ -87,7 +93,8 @@ function useNewThreadState() {
       if (
         latestActiveDraftThread &&
         currentRouteTarget?.kind === "draft" &&
-        latestActiveDraftThread.logicalProjectKey === logicalProjectKey
+        latestActiveDraftThread.logicalProjectKey === logicalProjectKey &&
+        latestActiveDraftThread.promotedTo == null
       ) {
         if (hasBranchOption || hasWorktreePathOption || hasEnvModeOption) {
           setDraftThreadContext(currentRouteTarget.draftId, {
@@ -128,7 +135,7 @@ function useNewThreadState() {
         });
       })();
     },
-    [getCurrentRouteTarget, router, projects],
+    [getCurrentRouteTarget, projectGroupingSettings, router, projects],
   );
 }
 
@@ -163,7 +170,7 @@ export function useHandleNewThread() {
     return orderItemsByPreferredIds({
       items: projects,
       preferredIds: projectOrder,
-      getId: (project) => scopedProjectKey(scopeProjectRef(project.environmentId, project.id)),
+      getId: getProjectOrderKey,
     });
   }, [projectOrder, projects]);
   const handleNewThread = useNewThreadState();
diff --git a/apps/web/src/hooks/useLocalStorage.ts b/apps/web/src/hooks/useLocalStorage.ts
index da9aa4b889d..93d26f66329 100644
--- a/apps/web/src/hooks/useLocalStorage.ts
+++ b/apps/web/src/hooks/useLocalStorage.ts
@@ -19,11 +19,15 @@ const isomorphicLocalStorage: Storage =
         };
       })();
 
-const decode = <T, E>(schema: Schema.Codec<T, E>, value: string) =>
-  Schema.decodeSync(Schema.fromJsonString(schema))(value);
+const decode = <T, E>(schema: Schema.Codec<T, E>, value: string) => {
+  const decodeJson = Schema.decodeSync(Schema.fromJsonString(schema));
+  return decodeJson(value);
+};
 
-const encode = <T, E>(schema: Schema.Codec<T, E>, value: T) =>
-  Schema.encodeSync(Schema.fromJsonString(schema))(value);
+const encode = <T, E>(schema: Schema.Codec<T, E>, value: T) => {
+  const encodeJson = Schema.encodeSync(Schema.fromJsonString(schema));
+  return encodeJson(value);
+};
 
 export const getLocalStorageItem = <T, E>(key: string, schema: Schema.Codec<T, E>): T | null => {
   const item = isomorphicLocalStorage.getItem(key);
diff --git a/apps/web/src/hooks/useSettings.ts b/apps/web/src/hooks/useSettings.ts
index 3dc2cf9b201..005c8ad82fc 100644
--- a/apps/web/src/hooks/useSettings.ts
+++ b/apps/web/src/hooks/useSettings.ts
@@ -10,21 +10,23 @@
  * store.
  */
 import { useCallback, useMemo, useSyncExternalStore } from "react";
-import { ServerSettings, ServerSettingsPatch } from "@t3tools/contracts";
+import { ServerSettings, type ServerSettingsPatch } from "@t3tools/contracts";
 import {
+  type ClientSettingsPatch,
   type ClientSettings,
   DEFAULT_CLIENT_SETTINGS,
   DEFAULT_UNIFIED_SETTINGS,
   UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
-import { Struct } from "effect";
-import { deepMerge } from "@t3tools/shared/Struct";
+import * as Struct from "effect/Struct";
+import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
 import { applySettingsUpdated, getServerConfig, useServerSettings } from "~/rpc/serverState";
 
 const CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE = "[CLIENT_SETTINGS]";
 
 const clientSettingsListeners = new Set<() => void>();
+const clientSettingsHydrationListeners = new Set<() => void>();
 let clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
 let clientSettingsHydrated = false;
 let clientSettingsHydrationPromise: Promise<void> | null = null;
@@ -35,6 +37,12 @@ function emitClientSettingsChange() {
   }
 }
 
+function emitClientSettingsHydrationChange() {
+  for (const listener of clientSettingsHydrationListeners) {
+    listener();
+  }
+}
+
 function getClientSettingsSnapshot(): ClientSettings {
   return clientSettingsSnapshot;
 }
@@ -44,6 +52,14 @@ function replaceClientSettingsSnapshot(settings: ClientSettings): void {
   emitClientSettingsChange();
 }
 
+function setClientSettingsHydrated(nextHydrated: boolean): void {
+  if (clientSettingsHydrated === nextHydrated) {
+    return;
+  }
+  clientSettingsHydrated = nextHydrated;
+  emitClientSettingsHydrationChange();
+}
+
 function subscribeClientSettings(listener: () => void): () => void {
   clientSettingsListeners.add(listener);
   void hydrateClientSettings();
@@ -52,6 +68,18 @@ function subscribeClientSettings(listener: () => void): () => void {
   };
 }
 
+function getClientSettingsHydratedSnapshot(): boolean {
+  return clientSettingsHydrated;
+}
+
+function subscribeClientSettingsHydration(listener: () => void): () => void {
+  clientSettingsHydrationListeners.add(listener);
+  void hydrateClientSettings();
+  return () => {
+    clientSettingsHydrationListeners.delete(listener);
+  };
+}
+
 async function hydrateClientSettings(): Promise<void> {
   if (clientSettingsHydrated) {
     return;
@@ -64,12 +92,12 @@ async function hydrateClientSettings(): Promise<void> {
     try {
       const persistedSettings = await ensureLocalApi().persistence.getClientSettings();
       if (persistedSettings) {
-        replaceClientSettingsSnapshot(persistedSettings);
+        replaceClientSettingsSnapshot({ ...DEFAULT_CLIENT_SETTINGS, ...persistedSettings });
       }
     } catch (error) {
       console.error(`${CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE} hydrate failed`, error);
     } finally {
-      clientSettingsHydrated = true;
+      setClientSettingsHydrated(true);
     }
   })();
 
@@ -98,7 +126,7 @@ const SERVER_SETTINGS_KEYS = new Set<string>(Struct.keys(ServerSettings.fields))
 
 function splitPatch(patch: Partial<UnifiedSettings>): {
   serverPatch: ServerSettingsPatch;
-  clientPatch: Partial<ClientSettings>;
+  clientPatch: ClientSettingsPatch;
 } {
   const serverPatch: Record<string, unknown> = {};
   const clientPatch: Record<string, unknown> = {};
@@ -111,7 +139,7 @@ function splitPatch(patch: Partial<UnifiedSettings>): {
   }
   return {
     serverPatch: serverPatch as ServerSettingsPatch,
-    clientPatch: clientPatch as Partial<ClientSettings>,
+    clientPatch: clientPatch as ClientSettingsPatch,
   };
 }
 
@@ -122,6 +150,23 @@ function splitPatch(patch: Partial<UnifiedSettings>): {
  * only re-render when the slice they care about changes.
  */
 
+/**
+ * Non-hook accessor for the current merged client settings snapshot.
+ * Used by non-React code paths (e.g. runtime services) that need the latest
+ * settings without subscribing.
+ */
+export function getClientSettings(): ClientSettings {
+  return getClientSettingsSnapshot();
+}
+
+export function useClientSettingsHydrated(): boolean {
+  return useSyncExternalStore(
+    subscribeClientSettingsHydration,
+    getClientSettingsHydratedSnapshot,
+    () => false,
+  );
+}
+
 export function useSettings<T = UnifiedSettings>(selector?: (s: UnifiedSettings) => T): T {
   const serverSettings = useServerSettings();
   const clientSettings = useSyncExternalStore(
@@ -154,7 +199,7 @@ export function useUpdateSettings() {
     if (Object.keys(serverPatch).length > 0) {
       const currentServerConfig = getServerConfig();
       if (currentServerConfig) {
-        applySettingsUpdated(deepMerge(currentServerConfig.settings, serverPatch));
+        applySettingsUpdated(applyServerSettingsPatch(currentServerConfig.settings, serverPatch));
       }
       // Fire-and-forget RPC — push will reconcile on success
       void ensureLocalApi().server.updateSettings(serverPatch);
@@ -183,4 +228,5 @@ export function __resetClientSettingsPersistenceForTests(): void {
   clientSettingsHydrated = false;
   clientSettingsHydrationPromise = null;
   clientSettingsListeners.clear();
+  clientSettingsHydrationListeners.clear();
 }
diff --git a/apps/web/src/hooks/useThreadActions.ts b/apps/web/src/hooks/useThreadActions.ts
index 4835edd4d19..7fc4bb2efd1 100644
--- a/apps/web/src/hooks/useThreadActions.ts
+++ b/apps/web/src/hooks/useThreadActions.ts
@@ -2,13 +2,14 @@ import { parseScopedThreadKey, scopeProjectRef, scopeThreadRef } from "@t3tools/
 import { type ScopedThreadRef, ThreadId } from "@t3tools/contracts";
 import { useQueryClient } from "@tanstack/react-query";
 import { useRouter } from "@tanstack/react-router";
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 
 import { getFallbackThreadIdAfterDelete } from "../components/Sidebar.logic";
 import { useComposerDraftStore } from "../composerDraftStore";
 import { useNewThreadHandler } from "./useHandleNewThread";
 import { ensureEnvironmentApi, readEnvironmentApi } from "../environmentApi";
 import { invalidateGitQueries } from "../lib/gitReactQuery";
+import { refreshArchivedThreadsForEnvironment } from "../lib/archivedThreadsState";
 import { newCommandId } from "../lib/utils";
 import { readLocalApi } from "../localApi";
 import {
@@ -20,7 +21,7 @@ import {
 import { useTerminalStateStore } from "../terminalStateStore";
 import { buildThreadRouteParams, resolveThreadRouteRef } from "../threadRoutes";
 import { formatWorktreePathForDisplay, getOrphanedWorktreePathForThread } from "../worktreeCleanup";
-import { toastManager } from "../components/ui/toast";
+import { stackedThreadToast, toastManager } from "../components/ui/toast";
 import { useSettings } from "./useSettings";
 
 export function useThreadActions() {
@@ -33,6 +34,12 @@ export function useThreadActions() {
   const clearTerminalState = useTerminalStateStore((state) => state.clearTerminalState);
   const router = useRouter();
   const { handleNewThread } = useNewThreadHandler();
+  // Keep a ref so archiveThread can call handleNewThread without appearing in
+  // its dependency array — handleNewThread is inherently unstable (depends on
+  // the projects list) and would otherwise cascade new references into every
+  // sidebar row via archiveThread → attemptArchiveThread.
+  const handleNewThreadRef = useRef(handleNewThread);
+  handleNewThreadRef.current = handleNewThread;
   const queryClient = useQueryClient();
 
   const resolveThreadTarget = useCallback((target: ScopedThreadRef) => {
@@ -62,21 +69,24 @@ export function useThreadActions() {
         throw new Error("Cannot archive a running thread.");
       }
 
-      await api.orchestration.dispatchCommand({
+      const currentRouteThreadRef = getCurrentRouteThreadRef();
+      const shouldNavigateToDraft =
+        currentRouteThreadRef?.threadId === threadRef.threadId &&
+        currentRouteThreadRef.environmentId === threadRef.environmentId;
+      const archiveCommand = api.orchestration.dispatchCommand({
         type: "thread.archive",
         commandId: newCommandId(),
         threadId: threadRef.threadId,
       });
-      const currentRouteThreadRef = getCurrentRouteThreadRef();
 
-      if (
-        currentRouteThreadRef?.threadId === threadRef.threadId &&
-        currentRouteThreadRef.environmentId === threadRef.environmentId
-      ) {
-        await handleNewThread(scopeProjectRef(thread.environmentId, thread.projectId));
+      if (shouldNavigateToDraft) {
+        await handleNewThreadRef.current(scopeProjectRef(thread.environmentId, thread.projectId));
       }
+
+      await archiveCommand;
+      refreshArchivedThreadsForEnvironment(threadRef.environmentId);
     },
-    [getCurrentRouteThreadRef, handleNewThread, resolveThreadTarget],
+    [getCurrentRouteThreadRef, resolveThreadTarget],
   );
 
   const unarchiveThread = useCallback(async (target: ScopedThreadRef) => {
@@ -87,6 +97,7 @@ export function useThreadActions() {
       commandId: newCommandId(),
       threadId: target.threadId,
     });
+    refreshArchivedThreadsForEnvironment(target.environmentId);
   }, []);
 
   const deleteThread = useCallback(
@@ -94,7 +105,16 @@ export function useThreadActions() {
       const api = readEnvironmentApi(target.environmentId);
       if (!api) return;
       const resolved = resolveThreadTarget(target);
-      if (!resolved) return;
+      if (!resolved) {
+        // Thread not in main store (e.g. archived thread) — dispatch delete directly.
+        await api.orchestration.dispatchCommand({
+          type: "thread.delete",
+          commandId: newCommandId(),
+          threadId: target.threadId,
+        });
+        refreshArchivedThreadsForEnvironment(target.environmentId);
+        return;
+      }
       const { thread, threadRef } = resolved;
       const state = useStore.getState();
       const threads = selectThreadsForEnvironment(state, threadRef.environmentId);
@@ -169,6 +189,7 @@ export function useThreadActions() {
         commandId: newCommandId(),
         threadId: threadRef.threadId,
       });
+      refreshArchivedThreadsForEnvironment(threadRef.environmentId);
       clearComposerDraftForThread(threadRef);
       clearProjectDraftThreadById(
         scopeProjectRef(threadRef.environmentId, thread.projectId),
@@ -203,7 +224,7 @@ export function useThreadActions() {
       }
 
       try {
-        await ensureEnvironmentApi(threadRef.environmentId).git.removeWorktree({
+        await ensureEnvironmentApi(threadRef.environmentId).vcs.removeWorktree({
           cwd: threadProject.cwd,
           path: orphanedWorktreePath,
           force: true,
@@ -219,11 +240,13 @@ export function useThreadActions() {
           worktreePath: orphanedWorktreePath,
           error,
         });
-        toastManager.add({
-          type: "error",
-          title: "Thread deleted, but worktree removal failed",
-          description: `Could not remove ${displayWorktreePath ?? orphanedWorktreePath}. ${message}`,
-        });
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Thread deleted, but worktree removal failed",
+            description: `Could not remove ${displayWorktreePath ?? orphanedWorktreePath}. ${message}`,
+          }),
+        );
       }
     },
     [
@@ -244,13 +267,12 @@ export function useThreadActions() {
       if (!api) return;
       const localApi = readLocalApi();
       const resolved = resolveThreadTarget(target);
-      if (!resolved) return;
-      const { thread } = resolved;
 
       if (confirmThreadDelete && localApi) {
+        const title = resolved?.thread.title ?? "this thread";
         const confirmed = await localApi.dialogs.confirm(
           [
-            `Delete thread "${thread.title}"?`,
+            `Delete thread "${title}"?`,
             "This permanently clears conversation history for this thread.",
           ].join("\n"),
         );
diff --git a/apps/web/src/hostedPairing.test.ts b/apps/web/src/hostedPairing.test.ts
new file mode 100644
index 00000000000..983094c1e5b
--- /dev/null
+++ b/apps/web/src/hostedPairing.test.ts
@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  buildHostedChannelSelectionUrl,
+  buildHostedPairingUrl,
+  hasHostedPairingRequest,
+  isHostedStaticApp,
+  readHostedPairingRequest,
+} from "./hostedPairing";
+
+describe("hostedPairing", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("reads hosted pairing host and query token parameters", () => {
+    const url = new URL("https://app.t3.codes/pair?host=100.64.1.2:3773&token=ABCD1234");
+
+    expect(readHostedPairingRequest(url)).toEqual({
+      host: "100.64.1.2:3773",
+      token: "ABCD1234",
+      label: "",
+    });
+    expect(hasHostedPairingRequest(url)).toBe(true);
+  });
+
+  it("prefers hash tokens so generated hosted links do not put credentials in search params", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://preview.t3.codes");
+
+    const url = new URL(
+      buildHostedPairingUrl({
+        host: "https://backend.example.com:3773",
+        token: "pairing-token",
+        label: "Workstation",
+      }),
+    );
+
+    expect(url.origin).toBe("https://preview.t3.codes");
+    expect(url.pathname).toBe("/pair");
+    expect(url.searchParams.get("host")).toBe("https://backend.example.com:3773");
+    expect(url.searchParams.get("label")).toBe("Workstation");
+    expect(url.searchParams.has("token")).toBe(false);
+    expect(url.hash).toBe("#token=pairing-token");
+  });
+
+  it("builds hosted channel selection URLs through the configured router origin", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://app.t3.codes");
+
+    const url = new URL(
+      buildHostedChannelSelectionUrl({
+        channel: "nightly",
+      }),
+    );
+
+    expect(url.origin).toBe("https://app.t3.codes");
+    expect(url.pathname).toBe("/__t3code/channel");
+    expect(url.searchParams.get("channel")).toBe("nightly");
+    expect(url.searchParams.has("next")).toBe(false);
+  });
+
+  it("ignores incomplete hosted pairing requests", () => {
+    expect(
+      hasHostedPairingRequest(new URL("https://app.t3.codes/pair?host=backend.example.com")),
+    ).toBe(false);
+    expect(hasHostedPairingRequest(new URL("https://app.t3.codes/pair?token=ABCD1234"))).toBe(
+      false,
+    );
+  });
+
+  it("detects the hosted static app only when no backend URL is configured", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://preview.t3.codes");
+    vi.stubEnv("VITE_HTTP_URL", "");
+    vi.stubEnv("VITE_WS_URL", "");
+
+    expect(isHostedStaticApp(new URL("https://preview.t3.codes/"))).toBe(true);
+    expect(isHostedStaticApp(new URL("https://preview.t3.codes/pair"))).toBe(true);
+    expect(isHostedStaticApp(new URL("https://backend.example.com/"))).toBe(false);
+
+    vi.stubEnv("VITE_HTTP_URL", "https://backend.example.com");
+    expect(isHostedStaticApp(new URL("https://preview.t3.codes/"))).toBe(false);
+  });
+
+  it("detects hosted channel aliases as static apps", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://app.t3.codes");
+    vi.stubEnv("VITE_HOSTED_APP_CHANNEL", "nightly");
+    vi.stubEnv("VITE_HTTP_URL", "");
+    vi.stubEnv("VITE_WS_URL", "");
+
+    expect(isHostedStaticApp(new URL("https://nightly.app.t3.codes/"))).toBe(true);
+
+    vi.stubEnv("VITE_HTTP_URL", "https://backend.example.com");
+    expect(isHostedStaticApp(new URL("https://nightly.app.t3.codes/"))).toBe(false);
+  });
+});
diff --git a/apps/web/src/hostedPairing.ts b/apps/web/src/hostedPairing.ts
new file mode 100644
index 00000000000..cc547323f8d
--- /dev/null
+++ b/apps/web/src/hostedPairing.ts
@@ -0,0 +1,89 @@
+import { getPairingTokenFromUrl, setPairingTokenOnUrl } from "./pairingUrl";
+
+const DEFAULT_HOSTED_APP_URL = "https://app.t3.codes";
+
+export interface HostedPairingRequest {
+  readonly host: string;
+  readonly token: string;
+  readonly label: string;
+}
+
+export type HostedAppChannel = "latest" | "nightly";
+
+function configuredHostedAppUrl(): string {
+  return import.meta.env.VITE_HOSTED_APP_URL?.trim() || DEFAULT_HOSTED_APP_URL;
+}
+
+function configuredBackendUrl(): string {
+  return import.meta.env.VITE_HTTP_URL?.trim() || import.meta.env.VITE_WS_URL?.trim() || "";
+}
+
+function configuredHostedAppChannel(): HostedAppChannel | null {
+  const channel = import.meta.env.VITE_HOSTED_APP_CHANNEL?.trim().toLowerCase();
+  return channel === "latest" || channel === "nightly" ? channel : null;
+}
+
+function originFromUrl(value: string): string | null {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+export function isHostedStaticApp(url: URL = new URL(window.location.href)): boolean {
+  if (configuredBackendUrl()) {
+    return false;
+  }
+
+  if (configuredHostedAppChannel()) {
+    return true;
+  }
+
+  const hostedOrigin = originFromUrl(configuredHostedAppUrl());
+  return hostedOrigin !== null && url.origin === hostedOrigin;
+}
+
+export function readHostedPairingRequest(url: URL = new URL(window.location.href)) {
+  const host = url.searchParams.get("host")?.trim() ?? "";
+  const token = getPairingTokenFromUrl(url)?.trim() ?? "";
+  const label = url.searchParams.get("label")?.trim() ?? "";
+
+  if (!host || !token) {
+    return null;
+  }
+
+  return {
+    host,
+    token,
+    label,
+  } satisfies HostedPairingRequest;
+}
+
+export function hasHostedPairingRequest(url: URL = new URL(window.location.href)): boolean {
+  return readHostedPairingRequest(url) !== null;
+}
+
+export function buildHostedPairingUrl(input: {
+  readonly host: string;
+  readonly token: string;
+  readonly label?: string | null;
+}): string {
+  const url = new URL("/pair", configuredHostedAppUrl());
+  url.searchParams.set("host", input.host);
+
+  const label = input.label?.trim();
+  if (label) {
+    url.searchParams.set("label", label);
+  }
+
+  return setPairingTokenOnUrl(url, input.token).toString();
+}
+
+export function buildHostedChannelSelectionUrl(input: {
+  readonly channel: HostedAppChannel;
+}): string {
+  const url = new URL("/__t3code/channel", configuredHostedAppUrl());
+  url.searchParams.set("channel", input.channel);
+  return url.toString();
+}
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 71602ee05e5..0f0417d438f 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -1,6 +1,8 @@
 @import "tailwindcss";
 
 @custom-variant dark (&:is(.dark, .dark *));
+/* Window Controls Overlay: active when Electron exposes native titlebar control geometry. */
+@custom-variant wco (&:is(.wco, .wco *));
 
 @theme inline {
   --animate-skeleton: skeleton 2s -1s infinite linear;
@@ -56,6 +58,22 @@
   }
 }
 
+/* Safe-area inset utilities for surfaces that opt into edge-to-edge rendering.
+   Insets resolve to 0 when the browser already constrains the layout viewport
+   to the safe area. */
+@utility pt-safe {
+  padding-top: max(env(safe-area-inset-top), 0px);
+}
+@utility pb-safe {
+  padding-bottom: max(env(safe-area-inset-bottom), 0px);
+}
+@utility pl-safe {
+  padding-left: max(env(safe-area-inset-left), 0px);
+}
+@utility pr-safe {
+  padding-right: max(env(safe-area-inset-right), 0px);
+}
+
 /* Suppress all transitions during theme changes */
 .no-transitions,
 .no-transitions *,
@@ -136,19 +154,28 @@ body {
     sans-serif;
   margin: 0;
   padding: 0;
-  min-height: 100vh;
 }
 
 html,
-body,
+body {
+  min-height: calc(100svh + env(safe-area-inset-top));
+  overscroll-behavior: none;
+}
+
+body {
+  height: 100%;
+  overflow: hidden;
+}
+
 #root {
   height: 100%;
   width: 100%;
   max-width: 100%;
-  overflow-y: hidden;
   overflow-x: hidden;
   overflow-x: clip;
+  overflow-y: hidden;
   overscroll-behavior-y: none;
+  padding-top: max(env(safe-area-inset-top), 0px);
 }
 
 body::after {
@@ -322,6 +349,47 @@ label:has(> select#reasoning-effort) select {
   font-size: 0.75rem;
 }
 
+.chat-markdown-file-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.28rem;
+  border: 1px solid color-mix(in srgb, var(--border) 92%, transparent);
+  border-radius: 0.375rem;
+  background: color-mix(in srgb, var(--muted) 88%, var(--background));
+  padding: 0.08rem 0.34rem;
+  color: var(--foreground);
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: 0.75rem;
+  line-height: 1.15;
+  vertical-align: text-bottom;
+  transition:
+    background-color 120ms ease,
+    border-color 120ms ease,
+    color 120ms ease,
+    opacity 120ms ease;
+}
+
+.chat-markdown-file-link:hover {
+  opacity: 1;
+  color: var(--foreground);
+  border-color: color-mix(in srgb, var(--border) 65%, var(--foreground));
+  background: color-mix(in srgb, var(--muted) 72%, var(--background));
+}
+
+.chat-markdown-file-link:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--ring) 70%, transparent);
+}
+
+.chat-markdown-file-link-icon {
+  opacity: 0.72;
+}
+
+.chat-markdown-file-link-label {
+  color: color-mix(in srgb, var(--foreground) 88%, transparent);
+  line-height: 1.1;
+}
+
 .chat-markdown pre {
   max-width: 100%;
   overflow-x: auto;
@@ -338,13 +406,33 @@ label:has(> select#reasoning-effort) select {
   font-size: 0.75rem;
 }
 
+.markdown-file-link-tooltip-scroll {
+  scrollbar-width: thin;
+  scrollbar-color: color-mix(in srgb, var(--border) 78%, transparent) transparent;
+}
+
+.markdown-file-link-tooltip-scroll::-webkit-scrollbar {
+  height: 6px;
+}
+
+.markdown-file-link-tooltip-scroll::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.markdown-file-link-tooltip-scroll::-webkit-scrollbar-thumb {
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--border) 78%, transparent);
+}
+
 .chat-markdown .chat-markdown-codeblock {
+  --chat-markdown-codeblock-copy-button-space: 1.5rem;
   position: relative;
   margin: 0.65rem 0;
 }
 
 .chat-markdown .chat-markdown-codeblock pre {
   margin: 0;
+  padding-right: calc(0.9rem + var(--chat-markdown-codeblock-copy-button-space));
 }
 
 .chat-markdown .chat-markdown-copy-button {
@@ -361,6 +449,7 @@ label:has(> select#reasoning-effort) select {
   border: 1px solid var(--border);
   background: color-mix(in srgb, var(--background) 82%, transparent);
   color: var(--muted-foreground);
+  cursor: pointer;
   opacity: 0;
   pointer-events: none;
   transition:
@@ -396,6 +485,19 @@ label:has(> select#reasoning-effort) select {
   text-align: left;
 }
 
+@keyframes provider-update-pill-countdown {
+  from {
+    transform: scaleX(1);
+  }
+  to {
+    transform: scaleX(0);
+  }
+}
+
+.provider-update-pill-progress {
+  animation: provider-update-pill-countdown var(--provider-update-pill-dismiss-ms) linear forwards;
+}
+
 /* Diffs theme bridge (match diff surfaces to app palette) */
 .diff-panel-viewport {
   background: color-mix(in srgb, var(--background) 94%, var(--card));
@@ -470,3 +572,25 @@ label:has(> select#reasoning-effort) select {
   -webkit-background-clip: text;
   animation: ultrathink-rainbow 10s linear infinite;
 }
+
+/* Thin scrollbar for model picker */
+.model-picker-list::-webkit-scrollbar {
+  width: 4px;
+}
+
+.model-picker-list::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.1);
+  border-radius: 2px;
+}
+
+.model-picker-list::-webkit-scrollbar-thumb:hover {
+  background: rgba(0, 0, 0, 0.2);
+}
+
+.dark .model-picker-list::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.dark .model-picker-list::-webkit-scrollbar-thumb:hover {
+  background: rgba(255, 255, 255, 0.15);
+}
diff --git a/apps/web/src/keybindings.test.ts b/apps/web/src/keybindings.test.ts
index 613f67d5487..85c14fa0ab7 100644
--- a/apps/web/src/keybindings.test.ts
+++ b/apps/web/src/keybindings.test.ts
@@ -11,6 +11,8 @@ import {
   isChatNewShortcut,
   isChatNewLocalShortcut,
   isDiffToggleShortcut,
+  modelPickerJumpCommandForIndex,
+  modelPickerJumpIndexFromCommand,
   isOpenFavoriteEditorShortcut,
   isTerminalClearShortcut,
   isTerminalCloseShortcut,
@@ -18,8 +20,10 @@ import {
   isTerminalSplitShortcut,
   isTerminalToggleShortcut,
   resolveShortcutCommand,
+  shouldShowModelPickerJumpHints,
   shouldShowThreadJumpHints,
   shortcutLabelForCommand,
+  terminalDeleteShortcutData,
   terminalNavigationShortcutData,
   threadJumpCommandForIndex,
   threadJumpIndexFromCommand,
@@ -106,6 +110,11 @@ const DEFAULT_BINDINGS = compile([
     command: "commandPalette.toggle",
     whenAst: whenNot(whenIdentifier("terminalFocus")),
   },
+  {
+    shortcut: modShortcut("m", { shiftKey: true }),
+    command: "modelPicker.toggle",
+    whenAst: whenNot(whenIdentifier("terminalFocus")),
+  },
   { shortcut: modShortcut("o", { shiftKey: true }), command: "chat.new" },
   { shortcut: modShortcut("n", { shiftKey: true }), command: "chat.newLocal" },
   { shortcut: modShortcut("o"), command: "editor.openFavorite" },
@@ -114,6 +123,21 @@ const DEFAULT_BINDINGS = compile([
   { shortcut: modShortcut("1"), command: "thread.jump.1" },
   { shortcut: modShortcut("2"), command: "thread.jump.2" },
   { shortcut: modShortcut("3"), command: "thread.jump.3" },
+  {
+    shortcut: modShortcut("1"),
+    command: "modelPicker.jump.1",
+    whenAst: whenIdentifier("modelPickerOpen"),
+  },
+  {
+    shortcut: modShortcut("2"),
+    command: "modelPicker.jump.2",
+    whenAst: whenIdentifier("modelPickerOpen"),
+  },
+  {
+    shortcut: modShortcut("3"),
+    command: "modelPicker.jump.3",
+    whenAst: whenIdentifier("modelPickerOpen"),
+  },
 ]);
 
 describe("isTerminalToggleShortcut", () => {
@@ -130,6 +154,15 @@ describe("isTerminalToggleShortcut", () => {
       isTerminalToggleShortcut(event({ ctrlKey: true }), DEFAULT_BINDINGS, { platform: "Win32" }),
     );
   });
+
+  it("matches Ctrl+J on non-macOS while terminalFocus is true", () => {
+    assert.isTrue(
+      isTerminalToggleShortcut(event({ ctrlKey: true }), DEFAULT_BINDINGS, {
+        platform: "Win32",
+        context: { terminalFocus: true },
+      }),
+    );
+  });
 });
 
 describe("split/new/close terminal shortcuts", () => {
@@ -258,6 +291,10 @@ describe("shortcutLabelForCommand", () => {
       shortcutLabelForCommand(DEFAULT_BINDINGS, "commandPalette.toggle", "MacIntel"),
       "⌘K",
     );
+    assert.strictEqual(
+      shortcutLabelForCommand(DEFAULT_BINDINGS, "modelPicker.toggle", "Linux"),
+      "Ctrl+Shift+M",
+    );
     assert.strictEqual(
       shortcutLabelForCommand(DEFAULT_BINDINGS, "editor.openFavorite", "Linux"),
       "Ctrl+O",
@@ -270,6 +307,13 @@ describe("shortcutLabelForCommand", () => {
       shortcutLabelForCommand(DEFAULT_BINDINGS, "thread.previous", "Linux"),
       "Ctrl+Shift+[",
     );
+    assert.strictEqual(
+      shortcutLabelForCommand(DEFAULT_BINDINGS, "modelPicker.jump.3", {
+        platform: "MacIntel",
+        context: { modelPickerOpen: true },
+      }),
+      "⌘3",
+    );
   });
 
   it("returns null for commands shadowed by a later conflicting shortcut", () => {
@@ -351,6 +395,32 @@ describe("thread navigation helpers", () => {
   });
 });
 
+describe("model picker navigation helpers", () => {
+  it("maps jump commands to visible model indices", () => {
+    assert.strictEqual(modelPickerJumpCommandForIndex(0), "modelPicker.jump.1");
+    assert.strictEqual(modelPickerJumpCommandForIndex(2), "modelPicker.jump.3");
+    assert.isNull(modelPickerJumpCommandForIndex(9));
+    assert.strictEqual(modelPickerJumpIndexFromCommand("modelPicker.jump.1"), 0);
+    assert.strictEqual(modelPickerJumpIndexFromCommand("modelPicker.jump.3"), 2);
+    assert.isNull(modelPickerJumpIndexFromCommand("thread.jump.1"));
+  });
+
+  it("shows jump hints only while the model picker context is active", () => {
+    assert.isFalse(
+      shouldShowModelPickerJumpHints(event({ metaKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { modelPickerOpen: false },
+      }),
+    );
+    assert.isTrue(
+      shouldShowModelPickerJumpHints(event({ metaKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { modelPickerOpen: true },
+      }),
+    );
+  });
+});
+
 describe("chat/editor shortcuts", () => {
   it("matches chat.new shortcut", () => {
     assert.isTrue(
@@ -560,6 +630,34 @@ describe("isTerminalClearShortcut", () => {
   });
 });
 
+describe("terminalDeleteShortcutData", () => {
+  it("maps Cmd+Backspace on macOS to delete-to-line-start", () => {
+    assert.strictEqual(
+      terminalDeleteShortcutData(event({ key: "Backspace", metaKey: true }), "MacIntel"),
+      "\u0015",
+    );
+  });
+
+  it("ignores non-macOS platforms and modified variants", () => {
+    assert.isNull(terminalDeleteShortcutData(event({ key: "Backspace", metaKey: true }), "Linux"));
+    assert.isNull(
+      terminalDeleteShortcutData(
+        event({ key: "Backspace", metaKey: true, altKey: true }),
+        "MacIntel",
+      ),
+    );
+  });
+
+  it("ignores non-keydown events", () => {
+    assert.isNull(
+      terminalDeleteShortcutData(
+        event({ type: "keyup", key: "Backspace", metaKey: true }),
+        "MacIntel",
+      ),
+    );
+  });
+});
+
 describe("terminalNavigationShortcutData", () => {
   it("maps Option+Arrow on macOS to word movement", () => {
     assert.strictEqual(
diff --git a/apps/web/src/keybindings.ts b/apps/web/src/keybindings.ts
index 286454dc05e..dbf2450f794 100644
--- a/apps/web/src/keybindings.ts
+++ b/apps/web/src/keybindings.ts
@@ -2,8 +2,10 @@ import {
   type KeybindingCommand,
   type KeybindingShortcut,
   type KeybindingWhenNode,
+  MODEL_PICKER_JUMP_KEYBINDING_COMMANDS,
   type ResolvedKeybindingsConfig,
   THREAD_JUMP_KEYBINDING_COMMANDS,
+  type ModelPickerJumpKeybindingCommand,
   type ThreadJumpKeybindingCommand,
 } from "@t3tools/contracts";
 import { isMacPlatform } from "./lib/utils";
@@ -18,6 +20,13 @@ export interface ShortcutEventLike {
   altKey: boolean;
 }
 
+export interface ShortcutModifierStateLike {
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+}
+
 export interface ShortcutMatchContext {
   terminalFocus: boolean;
   terminalOpen: boolean;
@@ -37,6 +46,7 @@ const TERMINAL_WORD_BACKWARD = "\u001bb";
 const TERMINAL_WORD_FORWARD = "\u001bf";
 const TERMINAL_LINE_START = "\u0001";
 const TERMINAL_LINE_END = "\u0005";
+const TERMINAL_DELETE_TO_LINE_START = "\u0015";
 const EVENT_CODE_KEY_ALIASES: Readonly<Record<string, readonly string[]>> = {
   BracketLeft: ["["],
   BracketRight: ["]"],
@@ -70,7 +80,7 @@ function resolveEventKeys(event: ShortcutEventLike): Set<string> {
 }
 
 function matchesShortcutModifiers(
-  event: ShortcutEventLike,
+  event: ShortcutModifierStateLike,
   shortcut: KeybindingShortcut,
   platform = navigator.platform,
 ): boolean {
@@ -268,13 +278,60 @@ export function shouldShowThreadJumpHints(
   event: ShortcutEventLike,
   keybindings: ResolvedKeybindingsConfig,
   options?: ShortcutMatchOptions,
+): boolean {
+  return shouldShowThreadJumpHintsForModifiers(event, keybindings, options);
+}
+
+export function shouldShowThreadJumpHintsForModifiers(
+  modifiers: ShortcutModifierStateLike,
+  keybindings: ResolvedKeybindingsConfig,
+  options?: ShortcutMatchOptions,
 ): boolean {
   const platform = resolvePlatform(options);
 
   for (const command of THREAD_JUMP_KEYBINDING_COMMANDS) {
     const shortcut = findEffectiveShortcutForCommand(keybindings, command, options);
     if (!shortcut) continue;
-    if (matchesShortcutModifiers(event, shortcut, platform)) {
+    if (matchesShortcutModifiers(modifiers, shortcut, platform)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function modelPickerJumpCommandForIndex(
+  index: number,
+): ModelPickerJumpKeybindingCommand | null {
+  return MODEL_PICKER_JUMP_KEYBINDING_COMMANDS[index] ?? null;
+}
+
+export function modelPickerJumpIndexFromCommand(command: string): number | null {
+  const index = MODEL_PICKER_JUMP_KEYBINDING_COMMANDS.indexOf(
+    command as ModelPickerJumpKeybindingCommand,
+  );
+  return index === -1 ? null : index;
+}
+
+export function shouldShowModelPickerJumpHints(
+  event: ShortcutEventLike,
+  keybindings: ResolvedKeybindingsConfig,
+  options?: ShortcutMatchOptions,
+): boolean {
+  return shouldShowModelPickerJumpHintsForModifiers(event, keybindings, options);
+}
+
+export function shouldShowModelPickerJumpHintsForModifiers(
+  modifiers: ShortcutModifierStateLike,
+  keybindings: ResolvedKeybindingsConfig,
+  options?: ShortcutMatchOptions,
+): boolean {
+  const platform = resolvePlatform(options);
+
+  for (const command of MODEL_PICKER_JUMP_KEYBINDING_COMMANDS) {
+    const shortcut = findEffectiveShortcutForCommand(keybindings, command, options);
+    if (!shortcut) continue;
+    if (matchesShortcutModifiers(modifiers, shortcut, platform)) {
       return true;
     }
   }
@@ -370,6 +427,28 @@ export function isTerminalClearShortcut(
   );
 }
 
+export function terminalDeleteShortcutData(
+  event: ShortcutEventLike,
+  platform = navigator.platform,
+): string | null {
+  if (event.type !== undefined && event.type !== "keydown") {
+    return null;
+  }
+
+  if (!isMacPlatform(platform)) {
+    return null;
+  }
+
+  const key = normalizeEventKey(event.key);
+  if (key !== "backspace") {
+    return null;
+  }
+
+  return event.metaKey && !event.ctrlKey && !event.altKey && !event.shiftKey
+    ? TERMINAL_DELETE_TO_LINE_START
+    : null;
+}
+
 export function terminalNavigationShortcutData(
   event: ShortcutEventLike,
   platform = navigator.platform,
diff --git a/apps/web/src/lib/archivedThreadsState.ts b/apps/web/src/lib/archivedThreadsState.ts
new file mode 100644
index 00000000000..1fe91455fc8
--- /dev/null
+++ b/apps/web/src/lib/archivedThreadsState.ts
@@ -0,0 +1,106 @@
+import { useAtomValue } from "@effect/atom-react";
+import { EnvironmentId, type OrchestrationShellSnapshot } from "@t3tools/contracts";
+import { AsyncResult, Atom } from "effect/unstable/reactivity";
+import { useCallback, useMemo } from "react";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { readEnvironmentApi } from "../environmentApi";
+import { appAtomRegistry } from "../rpc/atomRegistry";
+
+const ARCHIVED_THREADS_STALE_TIME_MS = 5_000;
+const ARCHIVED_THREADS_IDLE_TTL_MS = 5 * 60_000;
+const ARCHIVED_THREADS_ENVIRONMENT_KEY_SEPARATOR = "\u001f";
+
+export type ArchivedSnapshotEntry = {
+  readonly environmentId: EnvironmentId;
+  readonly snapshot: OrchestrationShellSnapshot;
+};
+
+const knownArchivedThreadEnvironmentKeys = new Set<string>();
+
+function makeArchivedThreadsEnvironmentKey(environmentIds: ReadonlyArray<EnvironmentId>): string {
+  return environmentIds.toSorted().join(ARCHIVED_THREADS_ENVIRONMENT_KEY_SEPARATOR);
+}
+
+function parseArchivedThreadsEnvironmentKey(key: string): ReadonlyArray<EnvironmentId> {
+  if (key.length === 0) {
+    return [];
+  }
+  return key
+    .split(ARCHIVED_THREADS_ENVIRONMENT_KEY_SEPARATOR)
+    .map((environmentId) => EnvironmentId.make(environmentId));
+}
+
+const archivedThreadSnapshotsAtom = Atom.family((environmentKey: string) => {
+  knownArchivedThreadEnvironmentKeys.add(environmentKey);
+  return Atom.make(
+    Effect.promise(async (): Promise<ReadonlyArray<ArchivedSnapshotEntry>> => {
+      const environmentIds = parseArchivedThreadsEnvironmentKey(environmentKey);
+      const snapshots = await Promise.all(
+        environmentIds.map(async (environmentId) => {
+          const api = readEnvironmentApi(environmentId);
+          if (!api) {
+            return null;
+          }
+          return {
+            environmentId,
+            snapshot: await api.orchestration.getArchivedShellSnapshot(),
+          };
+        }),
+      );
+      return snapshots.filter((snapshot) => snapshot !== null);
+    }),
+  ).pipe(
+    Atom.swr({
+      staleTime: ARCHIVED_THREADS_STALE_TIME_MS,
+      revalidateOnMount: true,
+    }),
+    Atom.setIdleTTL(ARCHIVED_THREADS_IDLE_TTL_MS),
+    Atom.withLabel(`archived-thread-snapshots:${environmentKey}`),
+  );
+});
+
+function readArchivedThreadsError(
+  result: AsyncResult.AsyncResult<ReadonlyArray<ArchivedSnapshotEntry>, unknown>,
+): string | null {
+  if (result._tag !== "Failure") {
+    return null;
+  }
+
+  const error = Cause.squash(result.cause);
+  return error instanceof Error ? error.message : "Failed to load archived threads.";
+}
+
+export function refreshArchivedThreadsForEnvironment(environmentId: EnvironmentId): void {
+  for (const key of knownArchivedThreadEnvironmentKeys) {
+    if (parseArchivedThreadsEnvironmentKey(key).includes(environmentId)) {
+      appAtomRegistry.refresh(archivedThreadSnapshotsAtom(key));
+    }
+  }
+}
+
+export function useArchivedThreadSnapshots(environmentIds: ReadonlyArray<EnvironmentId>): {
+  readonly snapshots: ReadonlyArray<ArchivedSnapshotEntry>;
+  readonly error: string | null;
+  readonly isLoading: boolean;
+  readonly refresh: () => void;
+} {
+  const environmentKey = useMemo(
+    () => makeArchivedThreadsEnvironmentKey(environmentIds),
+    [environmentIds],
+  );
+  const atom = archivedThreadSnapshotsAtom(environmentKey);
+  const result = useAtomValue(atom);
+  const snapshots = Option.getOrElse(AsyncResult.value(result), () => []);
+  const refresh = useCallback(() => {
+    appAtomRegistry.refresh(atom);
+  }, [atom]);
+
+  return {
+    snapshots,
+    error: readArchivedThreadsError(result),
+    isLoading: result.waiting,
+    refresh,
+  };
+}
diff --git a/apps/web/src/lib/desktopUpdateReactQuery.test.ts b/apps/web/src/lib/desktopUpdateReactQuery.test.ts
index a0f47559184..4c954ef692e 100644
--- a/apps/web/src/lib/desktopUpdateReactQuery.test.ts
+++ b/apps/web/src/lib/desktopUpdateReactQuery.test.ts
@@ -10,6 +10,7 @@ import {
 const baseState: DesktopUpdateState = {
   enabled: true,
   status: "idle",
+  channel: "latest",
   currentVersion: "1.0.0",
   hostArch: "x64",
   appArch: "x64",
diff --git a/apps/web/src/lib/gitReactQuery.test.ts b/apps/web/src/lib/gitReactQuery.test.ts
index 93ba66e4a24..2995207b938 100644
--- a/apps/web/src/lib/gitReactQuery.test.ts
+++ b/apps/web/src/lib/gitReactQuery.test.ts
@@ -11,7 +11,7 @@ vi.mock("../wsRpcClient", () => ({
 }));
 
 import type { InfiniteData } from "@tanstack/react-query";
-import { EnvironmentId, type GitListBranchesResult } from "@t3tools/contracts";
+import { EnvironmentId, type VcsListRefsResult } from "@t3tools/contracts";
 
 import {
   gitBranchSearchInfiniteQueryOptions,
@@ -22,15 +22,15 @@ import {
   invalidateGitQueries,
 } from "./gitReactQuery";
 
-const BRANCH_QUERY_RESULT: GitListBranchesResult = {
-  branches: [],
+const BRANCH_QUERY_RESULT: VcsListRefsResult = {
+  refs: [],
   isRepo: true,
-  hasOriginRemote: true,
+  hasPrimaryRemote: true,
   nextCursor: null,
   totalCount: 0,
 };
 
-const BRANCH_SEARCH_RESULT: InfiniteData<GitListBranchesResult, number> = {
+const BRANCH_SEARCH_RESULT: InfiniteData<VcsListRefsResult, number> = {
   pages: [BRANCH_QUERY_RESULT],
   pageParams: [0],
 };
diff --git a/apps/web/src/lib/gitReactQuery.ts b/apps/web/src/lib/gitReactQuery.ts
index 68d2b5bf53c..9db96420aa6 100644
--- a/apps/web/src/lib/gitReactQuery.ts
+++ b/apps/web/src/lib/gitReactQuery.ts
@@ -2,6 +2,7 @@ import {
   type EnvironmentId,
   type GitActionProgressEvent,
   type GitStackedAction,
+  type SourceControlPublishRepositoryInput,
   type ThreadId,
 } from "@t3tools/contracts";
 import {
@@ -19,23 +20,25 @@ const GIT_BRANCHES_PAGE_SIZE = 100;
 
 export const gitQueryKeys = {
   all: ["git"] as const,
-  branches: (environmentId: EnvironmentId | null, cwd: string | null) =>
-    ["git", "branches", environmentId ?? null, cwd] as const,
+  refs: (environmentId: EnvironmentId | null, cwd: string | null) =>
+    ["git", "refs", environmentId ?? null, cwd] as const,
   branchSearch: (environmentId: EnvironmentId | null, cwd: string | null, query: string) =>
-    ["git", "branches", environmentId ?? null, cwd, "search", query] as const,
+    ["git", "refs", environmentId ?? null, cwd, "search", query] as const,
 };
 
 export const gitMutationKeys = {
   init: (environmentId: EnvironmentId | null, cwd: string | null) =>
     ["git", "mutation", "init", environmentId ?? null, cwd] as const,
-  checkout: (environmentId: EnvironmentId | null, cwd: string | null) =>
-    ["git", "mutation", "checkout", environmentId ?? null, cwd] as const,
+  switchRef: (environmentId: EnvironmentId | null, cwd: string | null) =>
+    ["git", "mutation", "switchRef", environmentId ?? null, cwd] as const,
   runStackedAction: (environmentId: EnvironmentId | null, cwd: string | null) =>
     ["git", "mutation", "run-stacked-action", environmentId ?? null, cwd] as const,
   pull: (environmentId: EnvironmentId | null, cwd: string | null) =>
     ["git", "mutation", "pull", environmentId ?? null, cwd] as const,
   preparePullRequestThread: (environmentId: EnvironmentId | null, cwd: string | null) =>
     ["git", "mutation", "prepare-pull-request-thread", environmentId ?? null, cwd] as const,
+  publishRepository: (environmentId: EnvironmentId | null, cwd: string | null) =>
+    ["git", "mutation", "publish-repository", environmentId ?? null, cwd] as const,
 };
 
 export function invalidateGitQueries(
@@ -45,7 +48,7 @@ export function invalidateGitQueries(
   const environmentId = input?.environmentId ?? null;
   const cwd = input?.cwd ?? null;
   if (cwd !== null) {
-    return queryClient.invalidateQueries({ queryKey: gitQueryKeys.branches(environmentId, cwd) });
+    return queryClient.invalidateQueries({ queryKey: gitQueryKeys.refs(environmentId, cwd) });
   }
 
   return queryClient.invalidateQueries({ queryKey: gitQueryKeys.all });
@@ -60,9 +63,12 @@ function invalidateGitBranchQueries(
     return Promise.resolve();
   }
 
-  return queryClient.invalidateQueries({ queryKey: gitQueryKeys.branches(environmentId, cwd) });
+  return queryClient.invalidateQueries({ queryKey: gitQueryKeys.refs(environmentId, cwd) });
 }
 
+/**
+ * @deprecated Use a VCS-named query helper once the UI naming migration lands.
+ */
 export function gitBranchSearchInfiniteQueryOptions(input: {
   environmentId: EnvironmentId | null;
   cwd: string | null;
@@ -75,10 +81,10 @@ export function gitBranchSearchInfiniteQueryOptions(input: {
     queryKey: gitQueryKeys.branchSearch(input.environmentId, input.cwd, normalizedQuery),
     initialPageParam: 0,
     queryFn: async ({ pageParam }) => {
-      if (!input.cwd) throw new Error("Git branches are unavailable.");
-      if (!input.environmentId) throw new Error("Git branches are unavailable.");
+      if (!input.cwd) throw new Error("Git refs are unavailable.");
+      if (!input.environmentId) throw new Error("Git refs are unavailable.");
       const api = ensureEnvironmentApi(input.environmentId);
-      return api.git.listBranches({
+      return api.vcs.listRefs({
         cwd: input.cwd,
         ...(normalizedQuery.length > 0 ? { query: normalizedQuery } : {}),
         cursor: pageParam,
@@ -121,6 +127,9 @@ export function gitResolvePullRequestQueryOptions(input: {
   });
 }
 
+/**
+ * @deprecated Use a VCS-named mutation helper once the UI naming migration lands.
+ */
 export function gitInitMutationOptions(input: {
   environmentId: EnvironmentId | null;
   cwd: string | null;
@@ -131,7 +140,7 @@ export function gitInitMutationOptions(input: {
     mutationFn: async () => {
       if (!input.cwd || !input.environmentId) throw new Error("Git init is unavailable.");
       const api = ensureEnvironmentApi(input.environmentId);
-      return api.git.init({ cwd: input.cwd });
+      return api.vcs.init({ cwd: input.cwd });
     },
     onSettled: async () => {
       await invalidateGitBranchQueries(input.queryClient, input.environmentId, input.cwd);
@@ -139,17 +148,20 @@ export function gitInitMutationOptions(input: {
   });
 }
 
+/**
+ * @deprecated Use a VCS-named mutation helper once the UI naming migration lands.
+ */
 export function gitCheckoutMutationOptions(input: {
   environmentId: EnvironmentId | null;
   cwd: string | null;
   queryClient: QueryClient;
 }) {
   return mutationOptions({
-    mutationKey: gitMutationKeys.checkout(input.environmentId, input.cwd),
-    mutationFn: async (branch: string) => {
-      if (!input.cwd || !input.environmentId) throw new Error("Git checkout is unavailable.");
+    mutationKey: gitMutationKeys.switchRef(input.environmentId, input.cwd),
+    mutationFn: async (refName: string) => {
+      if (!input.cwd || !input.environmentId) throw new Error("Git switchRef is unavailable.");
       const api = ensureEnvironmentApi(input.environmentId);
-      return api.git.checkout({ cwd: input.cwd, branch });
+      return api.vcs.switchRef({ cwd: input.cwd, refName });
     },
     onSettled: async () => {
       await invalidateGitBranchQueries(input.queryClient, input.environmentId, input.cwd);
@@ -198,6 +210,9 @@ export function gitRunStackedActionMutationOptions(input: {
   });
 }
 
+/**
+ * @deprecated Use a VCS-named mutation helper once the UI naming migration lands.
+ */
 export function gitPullMutationOptions(input: {
   environmentId: EnvironmentId | null;
   cwd: string | null;
@@ -208,7 +223,7 @@ export function gitPullMutationOptions(input: {
     mutationFn: async () => {
       if (!input.cwd || !input.environmentId) throw new Error("Git pull is unavailable.");
       const api = ensureEnvironmentApi(input.environmentId);
-      return api.git.pull({ cwd: input.cwd });
+      return api.vcs.pull({ cwd: input.cwd });
     },
     onSuccess: async () => {
       await invalidateGitBranchQueries(input.queryClient, input.environmentId, input.cwd);
@@ -216,6 +231,29 @@ export function gitPullMutationOptions(input: {
   });
 }
 
+export function sourceControlPublishRepositoryMutationOptions(input: {
+  environmentId: EnvironmentId | null;
+  cwd: string | null;
+  queryClient: QueryClient;
+}) {
+  return mutationOptions({
+    mutationKey: gitMutationKeys.publishRepository(input.environmentId, input.cwd),
+    mutationFn: async (args: Omit<SourceControlPublishRepositoryInput, "cwd">) => {
+      if (!input.cwd || !input.environmentId) {
+        throw new Error("Repository publishing is unavailable.");
+      }
+      const api = ensureEnvironmentApi(input.environmentId);
+      return api.sourceControl.publishRepository({ cwd: input.cwd, ...args });
+    },
+    onSuccess: async () => {
+      await invalidateGitBranchQueries(input.queryClient, input.environmentId, input.cwd);
+    },
+  });
+}
+
+/**
+ * @deprecated Use a VCS-named mutation helper once the UI naming migration lands.
+ */
 export function gitCreateWorktreeMutationOptions(input: {
   environmentId: EnvironmentId | null;
   queryClient: QueryClient;
@@ -223,12 +261,12 @@ export function gitCreateWorktreeMutationOptions(input: {
   return mutationOptions({
     mutationKey: ["git", "mutation", "create-worktree", input.environmentId ?? null] as const,
     mutationFn: (
-      args: Parameters<ReturnType<typeof ensureEnvironmentApi>["git"]["createWorktree"]>[0],
+      args: Parameters<ReturnType<typeof ensureEnvironmentApi>["vcs"]["createWorktree"]>[0],
     ) => {
       if (!input.environmentId) {
         throw new Error("Worktree creation is unavailable.");
       }
-      return ensureEnvironmentApi(input.environmentId).git.createWorktree(args);
+      return ensureEnvironmentApi(input.environmentId).vcs.createWorktree(args);
     },
     onSuccess: async () => {
       await invalidateGitQueries(input.queryClient, { environmentId: input.environmentId });
@@ -236,6 +274,9 @@ export function gitCreateWorktreeMutationOptions(input: {
   });
 }
 
+/**
+ * @deprecated Use a VCS-named mutation helper once the UI naming migration lands.
+ */
 export function gitRemoveWorktreeMutationOptions(input: {
   environmentId: EnvironmentId | null;
   queryClient: QueryClient;
@@ -243,12 +284,12 @@ export function gitRemoveWorktreeMutationOptions(input: {
   return mutationOptions({
     mutationKey: ["git", "mutation", "remove-worktree", input.environmentId ?? null] as const,
     mutationFn: (
-      args: Parameters<ReturnType<typeof ensureEnvironmentApi>["git"]["removeWorktree"]>[0],
+      args: Parameters<ReturnType<typeof ensureEnvironmentApi>["vcs"]["removeWorktree"]>[0],
     ) => {
       if (!input.environmentId) {
         throw new Error("Worktree removal is unavailable.");
       }
-      return ensureEnvironmentApi(input.environmentId).git.removeWorktree(args);
+      return ensureEnvironmentApi(input.environmentId).vcs.removeWorktree(args);
     },
     onSuccess: async () => {
       await invalidateGitQueries(input.queryClient, { environmentId: input.environmentId });
diff --git a/apps/web/src/lib/gitStatusState.test.ts b/apps/web/src/lib/gitStatusState.test.ts
index b5317d9ec11..40766563fb7 100644
--- a/apps/web/src/lib/gitStatusState.test.ts
+++ b/apps/web/src/lib/gitStatusState.test.ts
@@ -1,4 +1,4 @@
-import { EnvironmentId, type GitStatusResult } from "@t3tools/contracts";
+import { EnvironmentId, type VcsStatusResult } from "@t3tools/contracts";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import type { WsRpcClient } from "../rpc/wsRpcClient";
@@ -33,17 +33,17 @@ function registerListener<T>(listeners: Set<(event: T) => void>, listener: (even
   };
 }
 
-const gitStatusListeners = new Set<(event: GitStatusResult) => void>();
+const gitStatusListeners = new Set<(event: VcsStatusResult) => void>();
 const ENVIRONMENT_ID = EnvironmentId.make("environment-local");
 const OTHER_ENVIRONMENT_ID = EnvironmentId.make("environment-remote");
 const TARGET = { environmentId: ENVIRONMENT_ID, cwd: "/repo" } as const;
 const FRESH_TARGET = { environmentId: ENVIRONMENT_ID, cwd: "/fresh" } as const;
 
-const BASE_STATUS: GitStatusResult = {
+const BASE_STATUS: VcsStatusResult = {
   isRepo: true,
-  hasOriginRemote: true,
-  isDefaultBranch: false,
-  branch: "feature/push-status",
+  hasPrimaryRemote: true,
+  isDefaultRef: false,
+  refName: "feature/push-status",
   hasWorkingTreeChanges: false,
   workingTree: { files: [], insertions: 0, deletions: 0 },
   hasUpstream: true,
@@ -55,21 +55,21 @@ const BASE_STATUS: GitStatusResult = {
 const gitClient = {
   refreshStatus: vi.fn(async (input: { cwd: string }) => ({
     ...BASE_STATUS,
-    branch: `${input.cwd}-refreshed`,
+    refName: `${input.cwd}-refreshed`,
   })),
-  onStatus: vi.fn((input: { cwd: string }, listener: (event: GitStatusResult) => void) =>
+  onStatus: vi.fn((input: { cwd: string }, listener: (event: VcsStatusResult) => void) =>
     registerListener(gitStatusListeners, listener),
   ),
 };
 
-function emitGitStatus(event: GitStatusResult) {
+function emitGitStatus(event: VcsStatusResult) {
   for (const listener of gitStatusListeners) {
     listener(event);
   }
 }
 
 function createRegisteredGitStatusClient(environmentId: EnvironmentId) {
-  const listeners = new Set<(event: GitStatusResult) => void>();
+  const listeners = new Set<(event: VcsStatusResult) => void>();
   const client = {
     dispose: vi.fn(async () => undefined),
     reconnect: vi.fn(async () => undefined),
@@ -89,22 +89,24 @@ function createRegisteredGitStatusClient(environmentId: EnvironmentId) {
     shell: {
       openInEditor: vi.fn(async () => undefined),
     },
-    git: {
+    vcs: {
       pull: vi.fn(async () => undefined),
       refreshStatus: vi.fn(async (input: { cwd: string }) => ({
         ...BASE_STATUS,
-        branch: `${input.cwd}-refreshed`,
+        refName: `${input.cwd}-refreshed`,
       })),
-      onStatus: vi.fn((_: { cwd: string }, listener: (event: GitStatusResult) => void) =>
+      onStatus: vi.fn((_: { cwd: string }, listener: (event: VcsStatusResult) => void) =>
         registerListener(listeners, listener),
       ),
-      runStackedAction: vi.fn(async () => ({}) as any),
-      listBranches: vi.fn(async () => []),
+      listRefs: vi.fn(async () => []),
       createWorktree: vi.fn(async () => undefined),
       removeWorktree: vi.fn(async () => undefined),
-      createBranch: vi.fn(async () => undefined),
-      checkout: vi.fn(async () => undefined),
+      createRef: vi.fn(async () => undefined),
+      switchRef: vi.fn(async () => undefined),
       init: vi.fn(async () => undefined),
+    },
+    git: {
+      runStackedAction: vi.fn(async () => ({}) as any),
       resolvePullRequest: vi.fn(async () => undefined),
       preparePullRequestThread: vi.fn(async () => undefined),
     },
@@ -123,12 +125,11 @@ function createRegisteredGitStatusClient(environmentId: EnvironmentId) {
       subscribeAuthAccess: vi.fn(() => () => undefined),
     },
     orchestration: {
-      getSnapshot: vi.fn(async () => ({ snapshotSequence: 1, projects: [], threads: [] }) as any),
       dispatchCommand: vi.fn(async () => undefined),
       getTurnDiff: vi.fn(async () => undefined),
       getFullThreadDiff: vi.fn(async () => undefined),
-      replayEvents: vi.fn(async () => []),
-      onDomainEvent: vi.fn(() => () => undefined),
+      subscribeShell: vi.fn(() => () => undefined),
+      subscribeThread: vi.fn(() => () => undefined),
     },
   } as unknown as WsRpcClient;
 
@@ -156,7 +157,7 @@ function createRegisteredGitStatusClient(environmentId: EnvironmentId) {
 
   return {
     client,
-    emit: (event: GitStatusResult) => {
+    emit: (event: VcsStatusResult) => {
       for (const listener of listeners) {
         listener(event);
       }
@@ -220,7 +221,7 @@ describe("gitStatusState", () => {
 
     expect(gitClient.onStatus).toHaveBeenCalledOnce();
     expect(gitClient.refreshStatus).toHaveBeenCalledWith({ cwd: "/repo" });
-    expect(refreshed).toEqual({ ...BASE_STATUS, branch: "/repo-refreshed" });
+    expect(refreshed).toEqual({ ...BASE_STATUS, refName: "/repo-refreshed" });
     expect(getGitStatusSnapshot(TARGET)).toEqual({
       data: BASE_STATUS,
       error: null,
@@ -232,17 +233,17 @@ describe("gitStatusState", () => {
   });
 
   it("keeps git status subscriptions isolated by environment when cwds match", () => {
-    const localListeners = new Set<(event: GitStatusResult) => void>();
-    const remoteListeners = new Set<(event: GitStatusResult) => void>();
+    const localListeners = new Set<(event: VcsStatusResult) => void>();
+    const remoteListeners = new Set<(event: VcsStatusResult) => void>();
     const localClient = {
       refreshStatus: vi.fn(),
-      onStatus: vi.fn((_: { cwd: string }, listener: (event: GitStatusResult) => void) =>
+      onStatus: vi.fn((_: { cwd: string }, listener: (event: VcsStatusResult) => void) =>
         registerListener(localListeners, listener),
       ),
     };
     const remoteClient = {
       refreshStatus: vi.fn(),
-      onStatus: vi.fn((_: { cwd: string }, listener: (event: GitStatusResult) => void) =>
+      onStatus: vi.fn((_: { cwd: string }, listener: (event: VcsStatusResult) => void) =>
         registerListener(remoteListeners, listener),
       ),
     };
@@ -255,11 +256,11 @@ describe("gitStatusState", () => {
       listener(BASE_STATUS);
     }
     for (const listener of remoteListeners) {
-      listener({ ...BASE_STATUS, branch: "remote-branch" });
+      listener({ ...BASE_STATUS, refName: "remote-refName" });
     }
 
-    expect(getGitStatusSnapshot(TARGET).data?.branch).toBe("feature/push-status");
-    expect(getGitStatusSnapshot(remoteTarget).data?.branch).toBe("remote-branch");
+    expect(getGitStatusSnapshot(TARGET).data?.refName).toBe("feature/push-status");
+    expect(getGitStatusSnapshot(remoteTarget).data?.refName).toBe("remote-refName");
 
     releaseLocal();
     releaseRemote();
@@ -293,7 +294,7 @@ describe("gitStatusState", () => {
     const release = watchGitStatus(TARGET);
 
     firstClient.emit(BASE_STATUS);
-    expect(getGitStatusSnapshot(TARGET).data?.branch).toBe("feature/push-status");
+    expect(getGitStatusSnapshot(TARGET).data?.refName).toBe("feature/push-status");
 
     serviceHarness.connections.delete(ENVIRONMENT_ID);
     for (const listener of serviceHarness.listeners) {
@@ -308,10 +309,10 @@ describe("gitStatusState", () => {
     });
 
     const secondClient = createRegisteredGitStatusClient(ENVIRONMENT_ID);
-    secondClient.emit({ ...BASE_STATUS, branch: "reconnected-branch" });
+    secondClient.emit({ ...BASE_STATUS, refName: "reconnected-refName" });
 
     expect(getGitStatusSnapshot(TARGET)).toEqual({
-      data: { ...BASE_STATUS, branch: "reconnected-branch" },
+      data: { ...BASE_STATUS, refName: "reconnected-refName" },
       error: null,
       cause: null,
       isPending: false,
diff --git a/apps/web/src/lib/gitStatusState.ts b/apps/web/src/lib/gitStatusState.ts
index 2c23ae5b826..4174c97c797 100644
--- a/apps/web/src/lib/gitStatusState.ts
+++ b/apps/web/src/lib/gitStatusState.ts
@@ -2,9 +2,9 @@ import { useAtomValue } from "@effect/atom-react";
 import {
   type EnvironmentId,
   type GitManagerServiceError,
-  type GitStatusResult,
+  type VcsStatusResult,
 } from "@t3tools/contracts";
-import { Cause } from "effect";
+import * as Cause from "effect/Cause";
 import { Atom } from "effect/unstable/reactivity";
 import { useEffect } from "react";
 
@@ -16,13 +16,13 @@ import {
 import type { WsRpcClient } from "~/rpc/wsRpcClient";
 
 interface GitStatusState {
-  readonly data: GitStatusResult | null;
+  readonly data: VcsStatusResult | null;
   readonly error: GitManagerServiceError | null;
   readonly cause: Cause.Cause<GitManagerServiceError> | null;
   readonly isPending: boolean;
 }
 
-type GitStatusClient = Pick<WsRpcClient["git"], "onStatus" | "refreshStatus">;
+type GitStatusClient = Pick<WsRpcClient["vcs"], "onStatus" | "refreshStatus">;
 interface ResolvedGitStatusClient {
   readonly clientIdentity: string;
   readonly client: GitStatusClient;
@@ -56,7 +56,7 @@ const EMPTY_GIT_STATUS_ATOM = Atom.make(EMPTY_GIT_STATUS_STATE).pipe(
 const NOOP: () => void = () => undefined;
 const watchedGitStatuses = new Map<string, WatchedGitStatus>();
 const knownGitStatusKeys = new Set<string>();
-const gitStatusRefreshInFlight = new Map<string, Promise<GitStatusResult>>();
+const gitStatusRefreshInFlight = new Map<string, Promise<VcsStatusResult>>();
 const gitStatusLastRefreshAtByKey = new Map<string, number>();
 
 const GIT_STATUS_REFRESH_DEBOUNCE_MS = 1_000;
@@ -83,7 +83,7 @@ function readResolvedGitStatusClient(target: GitStatusTarget): ResolvedGitStatus
   }
   const connection = readEnvironmentConnection(target.environmentId);
   return connection
-    ? { clientIdentity: connection.environmentId, client: connection.client.git }
+    ? { clientIdentity: connection.environmentId, client: connection.client.vcs }
     : null;
 }
 
@@ -119,7 +119,7 @@ export function watchGitStatus(target: GitStatusTarget, client?: GitStatusClient
 export function refreshGitStatus(
   target: GitStatusTarget,
   client?: GitStatusClient,
-): Promise<GitStatusResult | null> {
+): Promise<VcsStatusResult | null> {
   const targetKey = getGitStatusTargetKey(target);
   if (targetKey === null || target.cwd === null) {
     return Promise.resolve(null);
@@ -245,7 +245,7 @@ function subscribeToGitStatus(targetKey: string, cwd: string, client: GitStatusC
   markGitStatusPending(targetKey);
   return client.onStatus(
     { cwd },
-    (status: GitStatusResult) => {
+    (status: VcsStatusResult) => {
       appAtomRegistry.set(gitStatusStateAtom(targetKey), {
         data: status,
         error: null,
diff --git a/apps/web/src/lib/processDiagnosticsState.ts b/apps/web/src/lib/processDiagnosticsState.ts
new file mode 100644
index 00000000000..7e1b3d698a6
--- /dev/null
+++ b/apps/web/src/lib/processDiagnosticsState.ts
@@ -0,0 +1,140 @@
+import { useAtomValue } from "@effect/atom-react";
+import type {
+  ServerProcessDiagnosticsResult,
+  ServerProcessResourceHistoryResult,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { AsyncResult, Atom } from "effect/unstable/reactivity";
+import { useCallback } from "react";
+
+import { ensureLocalApi } from "../localApi";
+import { appAtomRegistry } from "../rpc/atomRegistry";
+
+const PROCESS_DIAGNOSTICS_STALE_TIME_MS = 2_000;
+const PROCESS_DIAGNOSTICS_IDLE_TTL_MS = 5 * 60_000;
+const PROCESS_RESOURCE_HISTORY_STALE_TIME_MS = 5_000;
+const PROCESS_RESOURCE_HISTORY_INPUT_SEPARATOR = ":";
+
+const processDiagnosticsAtom = Atom.make(
+  Effect.promise(() => ensureLocalApi().server.getProcessDiagnostics()),
+).pipe(
+  Atom.swr({
+    staleTime: PROCESS_DIAGNOSTICS_STALE_TIME_MS,
+    revalidateOnMount: true,
+  }),
+  Atom.setIdleTTL(PROCESS_DIAGNOSTICS_IDLE_TTL_MS),
+  Atom.withLabel("process-diagnostics"),
+);
+
+function formatProcessResourceHistoryKey(input: {
+  readonly windowMs: number;
+  readonly bucketMs: number;
+}): string {
+  return `${input.windowMs}${PROCESS_RESOURCE_HISTORY_INPUT_SEPARATOR}${input.bucketMs}`;
+}
+
+function parseProcessResourceHistoryKey(key: string): {
+  readonly windowMs: number;
+  readonly bucketMs: number;
+} {
+  const [windowMs = "0", bucketMs = "0"] = key.split(PROCESS_RESOURCE_HISTORY_INPUT_SEPARATOR);
+  return {
+    windowMs: Number(windowMs),
+    bucketMs: Number(bucketMs),
+  };
+}
+
+const processResourceHistoryAtom = Atom.family((key: string) => {
+  const input = parseProcessResourceHistoryKey(key);
+  return Atom.make(
+    Effect.promise(() => ensureLocalApi().server.getProcessResourceHistory(input)),
+  ).pipe(
+    Atom.swr({
+      staleTime: PROCESS_RESOURCE_HISTORY_STALE_TIME_MS,
+      revalidateOnMount: true,
+    }),
+    Atom.setIdleTTL(PROCESS_DIAGNOSTICS_IDLE_TTL_MS),
+    Atom.withLabel(`process-resource-history:${key}`),
+  );
+});
+
+export interface ProcessDiagnosticsState {
+  readonly data: ServerProcessDiagnosticsResult | null;
+  readonly error: string | null;
+  readonly isPending: boolean;
+  readonly refresh: () => void;
+}
+
+export interface ProcessResourceHistoryState {
+  readonly data: ServerProcessResourceHistoryResult | null;
+  readonly error: string | null;
+  readonly isPending: boolean;
+  readonly refresh: () => void;
+}
+
+function formatProcessDiagnosticsError(error: unknown): string {
+  return error instanceof Error ? error.message : "Failed to load process diagnostics.";
+}
+
+function readProcessDiagnosticsError(
+  result: AsyncResult.AsyncResult<ServerProcessDiagnosticsResult, unknown>,
+): string | null {
+  if (result._tag !== "Failure") {
+    return null;
+  }
+
+  const squashed = Cause.squash(result.cause);
+  return formatProcessDiagnosticsError(squashed);
+}
+
+function readProcessResourceHistoryError(
+  result: AsyncResult.AsyncResult<ServerProcessResourceHistoryResult, unknown>,
+): string | null {
+  if (result._tag !== "Failure") {
+    return null;
+  }
+
+  const squashed = Cause.squash(result.cause);
+  return formatProcessDiagnosticsError(squashed);
+}
+
+export function refreshProcessDiagnostics(): void {
+  appAtomRegistry.refresh(processDiagnosticsAtom);
+}
+
+export function useProcessDiagnostics(): ProcessDiagnosticsState {
+  const result = useAtomValue(processDiagnosticsAtom);
+  const data = Option.getOrNull(AsyncResult.value(result));
+  const refresh = useCallback(() => {
+    refreshProcessDiagnostics();
+  }, []);
+
+  return {
+    data,
+    error: readProcessDiagnosticsError(result),
+    isPending: result.waiting,
+    refresh,
+  };
+}
+
+export function useProcessResourceHistory(input: {
+  readonly windowMs: number;
+  readonly bucketMs: number;
+}): ProcessResourceHistoryState {
+  const atom = processResourceHistoryAtom(formatProcessResourceHistoryKey(input));
+  const result = useAtomValue(atom);
+  const data = Option.getOrNull(AsyncResult.value(result));
+
+  const refresh = useCallback(() => {
+    appAtomRegistry.refresh(atom);
+  }, [atom]);
+
+  return {
+    data,
+    error: readProcessResourceHistoryError(result),
+    isPending: result.waiting,
+    refresh,
+  };
+}
diff --git a/apps/web/src/lib/projectPaths.test.ts b/apps/web/src/lib/projectPaths.test.ts
new file mode 100644
index 00000000000..7989622e1d5
--- /dev/null
+++ b/apps/web/src/lib/projectPaths.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  appendBrowsePathSegment,
+  canNavigateUp,
+  getBrowseDirectoryPath,
+  findProjectByPath,
+  getBrowseLeafPathSegment,
+  getBrowseParentPath,
+  hasTrailingPathSeparator,
+  inferProjectTitleFromPath,
+  isExplicitRelativeProjectPath,
+  isFilesystemBrowseQuery,
+  normalizeProjectPathForComparison,
+  normalizeProjectPathForDispatch,
+  isUnsupportedWindowsProjectPath,
+  resolveProjectPathForDispatch,
+} from "./projectPaths";
+
+describe("projectPaths", () => {
+  it("normalizes trailing separators for dispatch and comparison", () => {
+    expect(normalizeProjectPathForDispatch(" /repo/app/ ")).toBe("/repo/app");
+    expect(normalizeProjectPathForComparison("/repo/app/")).toBe("/repo/app");
+  });
+
+  it("normalizes windows-style paths for comparison", () => {
+    expect(normalizeProjectPathForComparison("C:/Work/Repo/")).toBe("c:\\work\\repo");
+    expect(normalizeProjectPathForComparison("C:\\Work\\Repo\\")).toBe("c:\\work\\repo");
+  });
+
+  it("finds existing projects even when the input formatting differs", () => {
+    const existing = findProjectByPath(
+      [
+        { id: "project-1", cwd: "/repo/app" },
+        { id: "project-2", cwd: "C:\\Work\\Repo" },
+      ],
+      "C:/Work/Repo/",
+    );
+
+    expect(existing?.id).toBe("project-2");
+  });
+
+  it("infers project titles from normalized paths", () => {
+    expect(inferProjectTitleFromPath("/repo/app/")).toBe("app");
+    expect(inferProjectTitleFromPath("C:\\Work\\Repo\\")).toBe("Repo");
+    expect(inferProjectTitleFromPath("/home/user\\project/")).toBe("user\\project");
+  });
+
+  it("detects browse queries across supported path styles", () => {
+    expect(isFilesystemBrowseQuery(".")).toBe(false);
+    expect(isFilesystemBrowseQuery("..")).toBe(false);
+    expect(isFilesystemBrowseQuery("./")).toBe(true);
+    expect(isFilesystemBrowseQuery("../")).toBe(true);
+    expect(isFilesystemBrowseQuery("~/projects")).toBe(true);
+    expect(isFilesystemBrowseQuery("..\\docs")).toBe(true);
+    expect(isFilesystemBrowseQuery("notes")).toBe(false);
+  });
+
+  it("only treats windows-style paths as browse queries on windows", () => {
+    expect(isFilesystemBrowseQuery("C:\\Work\\Repo\\", "MacIntel")).toBe(false);
+    expect(isFilesystemBrowseQuery("C:\\Work\\Repo\\", "Win32")).toBe(true);
+    expect(isUnsupportedWindowsProjectPath("C:\\Work\\Repo\\", "MacIntel")).toBe(true);
+    expect(isUnsupportedWindowsProjectPath("C:\\Work\\Repo\\", "Win32")).toBe(false);
+  });
+
+  it("detects explicit relative project paths", () => {
+    expect(isExplicitRelativeProjectPath(".")).toBe(true);
+    expect(isExplicitRelativeProjectPath("..")).toBe(true);
+    expect(isExplicitRelativeProjectPath("./docs")).toBe(true);
+    expect(isExplicitRelativeProjectPath("..\\docs")).toBe(true);
+    expect(isExplicitRelativeProjectPath("/repo/docs")).toBe(false);
+  });
+
+  it("resolves explicit relative paths against the current project", () => {
+    expect(resolveProjectPathForDispatch(".", "/repo/app")).toBe("/repo/app");
+    expect(resolveProjectPathForDispatch("..", "/repo/app")).toBe("/repo");
+    expect(resolveProjectPathForDispatch("./docs", "/repo/app")).toBe("/repo/app/docs");
+    expect(resolveProjectPathForDispatch("../docs", "/repo/app")).toBe("/repo/docs");
+    expect(resolveProjectPathForDispatch("./Repo", "C:\\Work")).toBe("C:\\Work\\Repo");
+    expect(resolveProjectPathForDispatch("./docs", "/home/user\\project")).toBe(
+      "/home/user\\project/docs",
+    );
+  });
+
+  it("navigates browse paths with matching separators", () => {
+    expect(appendBrowsePathSegment("/repo/", "src")).toBe("/repo/src/");
+    expect(appendBrowsePathSegment("C:\\Work\\", "Repo")).toBe("C:\\Work\\Repo\\");
+    expect(appendBrowsePathSegment("/home/user\\project/", "docs")).toBe(
+      "/home/user\\project/docs/",
+    );
+    expect(getBrowseParentPath("/repo/src/")).toBe("/repo/");
+    expect(getBrowseParentPath("C:\\Work\\Repo\\")).toBe("C:\\Work\\");
+    expect(getBrowseParentPath("\\\\server\\share\\")).toBeNull();
+    expect(getBrowseParentPath("\\\\server\\share\\repo\\")).toBe("\\\\server\\share\\");
+    expect(getBrowseParentPath("C:\\")).toBeNull();
+    expect(getBrowseParentPath("/home/user\\project/docs/")).toBe("/home/user\\project/");
+  });
+
+  it("detects browse path boundaries", () => {
+    expect(hasTrailingPathSeparator("/repo/src/")).toBe(true);
+    expect(hasTrailingPathSeparator("/repo/src")).toBe(false);
+    expect(getBrowseDirectoryPath("/repo/src")).toBe("/repo/");
+    expect(getBrowseDirectoryPath("/repo/src/")).toBe("/repo/src/");
+    expect(getBrowseLeafPathSegment("/repo/src")).toBe("src");
+    expect(getBrowseLeafPathSegment("C:\\Work\\Repo\\Docs")).toBe("Docs");
+    expect(getBrowseDirectoryPath("/home/user\\project/docs")).toBe("/home/user\\project/");
+    expect(getBrowseLeafPathSegment("/home/user\\project/docs")).toBe("docs");
+  });
+
+  it("only allows browse-up after entering a directory", () => {
+    expect(canNavigateUp("~/repo")).toBe(false);
+    expect(canNavigateUp("~/a")).toBe(false);
+    expect(canNavigateUp("~/repo/")).toBe(true);
+    expect(canNavigateUp("\\\\server\\share\\")).toBe(false);
+    expect(canNavigateUp("\\\\server\\share\\repo\\")).toBe(true);
+  });
+});
diff --git a/apps/web/src/lib/projectPaths.ts b/apps/web/src/lib/projectPaths.ts
new file mode 100644
index 00000000000..4b823dff933
--- /dev/null
+++ b/apps/web/src/lib/projectPaths.ts
@@ -0,0 +1,259 @@
+import {
+  isExplicitRelativePath,
+  isUncPath,
+  isWindowsAbsolutePath,
+  isWindowsDrivePath,
+} from "@t3tools/shared/path";
+import { isWindowsPlatform } from "./utils";
+
+function isRootPath(value: string): boolean {
+  return value === "/" || value === "\\" || /^[a-zA-Z]:[/\\]?$/.test(value);
+}
+
+function getAbsolutePathKind(value: string): "unix" | "windows" | null {
+  if (isWindowsDrivePath(value) || isUncPath(value)) {
+    return "windows";
+  }
+
+  if (value.startsWith("/")) {
+    return "unix";
+  }
+
+  return null;
+}
+
+function trimTrailingPathSeparators(value: string): string {
+  if (value.length === 0 || isRootPath(value)) {
+    return value;
+  }
+
+  const trimmed =
+    getAbsolutePathKind(value) === "unix"
+      ? value.replace(/\/+$/g, "")
+      : value.replace(/[\\/]+$/g, "");
+  if (trimmed.length === 0) {
+    return value;
+  }
+
+  return /^[a-zA-Z]:$/.test(trimmed) ? `${trimmed}\\` : trimmed;
+}
+
+function preferredPathSeparator(value: string): "/" | "\\" {
+  const absolutePathKind = getAbsolutePathKind(value);
+  if (absolutePathKind === "windows") {
+    return "\\";
+  }
+  if (absolutePathKind === "unix") {
+    return "/";
+  }
+
+  return value.includes("\\") ? "\\" : "/";
+}
+
+export function hasTrailingPathSeparator(value: string): boolean {
+  return (getAbsolutePathKind(value) === "unix" ? /\/$/ : /[\\/]$/).test(value);
+}
+
+export { isExplicitRelativePath as isExplicitRelativeProjectPath };
+
+function splitPathSegments(value: string, separator: "/" | "\\"): string[] {
+  return value.split(separator === "/" ? /\/+/ : /[\\/]+/).filter(Boolean);
+}
+
+function getLastPathSeparatorIndex(value: string): number {
+  if (getAbsolutePathKind(value) === "unix") {
+    return value.lastIndexOf("/");
+  }
+
+  return Math.max(value.lastIndexOf("/"), value.lastIndexOf("\\"));
+}
+
+function splitAbsolutePath(value: string): {
+  root: string;
+  separator: "/" | "\\";
+  segments: string[];
+} | null {
+  if (isWindowsDrivePath(value)) {
+    const root = `${value.slice(0, 2)}\\`;
+    const segments = splitPathSegments(value.slice(root.length), "\\");
+    return { root, separator: "\\", segments };
+  }
+  if (isUncPath(value)) {
+    const segments = splitPathSegments(value, "\\");
+    const [server, share, ...rest] = segments;
+    if (!server || !share) {
+      return null;
+    }
+    return {
+      root: `\\\\${server}\\${share}\\`,
+      separator: "\\",
+      segments: rest,
+    };
+  }
+  if (value.startsWith("/")) {
+    return {
+      root: "/",
+      separator: "/",
+      segments: splitPathSegments(value.slice(1), "/"),
+    };
+  }
+  return null;
+}
+
+export function isFilesystemBrowseQuery(
+  value: string,
+  platform = typeof navigator === "undefined" ? "" : navigator.platform,
+): boolean {
+  const allowWindowsPaths = isWindowsPlatform(platform);
+  return (
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    value.startsWith(".\\") ||
+    value.startsWith("..\\") ||
+    value.startsWith("/") ||
+    value.startsWith("~/") ||
+    (allowWindowsPaths && isWindowsAbsolutePath(value))
+  );
+}
+
+export function isUnsupportedWindowsProjectPath(value: string, platform: string): boolean {
+  return isWindowsAbsolutePath(value) && !isWindowsPlatform(platform);
+}
+
+export function normalizeProjectPathForDispatch(value: string): string {
+  return trimTrailingPathSeparators(value.trim());
+}
+
+export function resolveProjectPathForDispatch(value: string, cwd?: string | null): string {
+  const trimmedValue = value.trim();
+  if (!isExplicitRelativePath(trimmedValue) || !cwd) {
+    return normalizeProjectPathForDispatch(trimmedValue);
+  }
+
+  const absoluteBase = splitAbsolutePath(normalizeProjectPathForDispatch(cwd));
+  if (!absoluteBase) {
+    return normalizeProjectPathForDispatch(trimmedValue);
+  }
+
+  const nextSegments = [...absoluteBase.segments];
+  for (const segment of trimmedValue.split(/[\\/]+/)) {
+    if (segment.length === 0 || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      nextSegments.pop();
+      continue;
+    }
+    nextSegments.push(segment);
+  }
+
+  const joinedPath = nextSegments.join(absoluteBase.separator);
+  if (joinedPath.length === 0) {
+    return normalizeProjectPathForDispatch(absoluteBase.root);
+  }
+
+  return normalizeProjectPathForDispatch(`${absoluteBase.root}${joinedPath}`);
+}
+
+export function normalizeProjectPathForComparison(value: string): string {
+  const normalized = normalizeProjectPathForDispatch(value);
+  if (isWindowsDrivePath(normalized) || normalized.startsWith("\\\\")) {
+    return normalized.replaceAll("/", "\\").toLowerCase();
+  }
+  return normalized;
+}
+
+export function findProjectByPath<T extends { cwd: string }>(
+  projects: ReadonlyArray<T>,
+  candidatePath: string,
+): T | undefined {
+  const normalizedCandidate = normalizeProjectPathForComparison(candidatePath);
+  if (normalizedCandidate.length === 0) {
+    return undefined;
+  }
+
+  return projects.find(
+    (project) => normalizeProjectPathForComparison(project.cwd) === normalizedCandidate,
+  );
+}
+
+export function inferProjectTitleFromPath(value: string): string {
+  const normalized = normalizeProjectPathForDispatch(value);
+  const absolutePath = splitAbsolutePath(normalized);
+  if (absolutePath) {
+    return absolutePath.segments.findLast(Boolean) ?? normalized;
+  }
+
+  const segments = normalized.split(/[/\\]/);
+  return segments.findLast(Boolean) ?? normalized;
+}
+
+export function appendBrowsePathSegment(currentPath: string, segment: string): string {
+  const separator = preferredPathSeparator(currentPath);
+  return `${getBrowseDirectoryPath(currentPath)}${segment}${separator}`;
+}
+
+export function getBrowseLeafPathSegment(currentPath: string): string {
+  const lastSeparatorIndex = getLastPathSeparatorIndex(currentPath);
+  return currentPath.slice(lastSeparatorIndex + 1);
+}
+
+export function getBrowseDirectoryPath(currentPath: string): string {
+  if (hasTrailingPathSeparator(currentPath)) {
+    return currentPath;
+  }
+
+  const lastSeparatorIndex = getLastPathSeparatorIndex(currentPath);
+  if (lastSeparatorIndex < 0) {
+    return currentPath;
+  }
+
+  return currentPath.slice(0, lastSeparatorIndex + 1);
+}
+
+export function ensureBrowseDirectoryPath(currentPath: string): string {
+  const trimmed = currentPath.trim();
+  if (trimmed.length === 0) {
+    return trimmed;
+  }
+
+  if (hasTrailingPathSeparator(trimmed)) {
+    return trimmed;
+  }
+
+  return `${trimmed}${preferredPathSeparator(trimmed)}`;
+}
+
+export function getBrowseParentPath(currentPath: string): string | null {
+  const trimmed = trimTrailingPathSeparators(currentPath);
+  const absolutePath = splitAbsolutePath(trimmed);
+  if (absolutePath) {
+    if (absolutePath.segments.length === 0) {
+      return null;
+    }
+
+    if (absolutePath.segments.length === 1) {
+      return absolutePath.root;
+    }
+
+    const parentSegments = absolutePath.segments.slice(0, -1).join(absolutePath.separator);
+    return `${absolutePath.root}${parentSegments}${absolutePath.separator}`;
+  }
+
+  const separator = preferredPathSeparator(currentPath);
+  const lastSeparatorIndex = getLastPathSeparatorIndex(trimmed);
+
+  if (lastSeparatorIndex < 0) {
+    return null;
+  }
+
+  if (lastSeparatorIndex === 2 && /^[a-zA-Z]:/.test(trimmed)) {
+    return `${trimmed.slice(0, 2)}${separator}`;
+  }
+
+  return trimmed.slice(0, lastSeparatorIndex + 1);
+}
+
+export function canNavigateUp(currentPath: string): boolean {
+  return hasTrailingPathSeparator(currentPath) && getBrowseParentPath(currentPath) !== null;
+}
diff --git a/apps/web/src/lib/projectScriptKeybindings.ts b/apps/web/src/lib/projectScriptKeybindings.ts
index 4ea80cf824f..6f2048f9cd3 100644
--- a/apps/web/src/lib/projectScriptKeybindings.ts
+++ b/apps/web/src/lib/projectScriptKeybindings.ts
@@ -4,10 +4,12 @@ import {
   type KeybindingRule,
   type ResolvedKeybindingsConfig,
 } from "@t3tools/contracts";
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 
 export const PROJECT_SCRIPT_KEYBINDING_INVALID_MESSAGE = "Invalid keybinding.";
 
+const decodeKeybindingRule = Schema.decodeUnknownOption(KeybindingRuleSchema);
+
 function normalizeProjectScriptKeybindingInput(
   keybinding: string | null | undefined,
 ): string | null {
@@ -22,7 +24,7 @@ export function decodeProjectScriptKeybindingRule(input: {
   const normalizedKey = normalizeProjectScriptKeybindingInput(input.keybinding);
   if (!normalizedKey) return null;
 
-  const decoded = Schema.decodeUnknownOption(KeybindingRuleSchema)({
+  const decoded = decodeKeybindingRule({
     key: normalizedKey,
     command: input.command,
   });
diff --git a/apps/web/src/lib/providerReactQuery.test.ts b/apps/web/src/lib/providerReactQuery.test.ts
index 85466326e4d..bd1c1858681 100644
--- a/apps/web/src/lib/providerReactQuery.test.ts
+++ b/apps/web/src/lib/providerReactQuery.test.ts
@@ -30,6 +30,7 @@ describe("providerQueryKeys.checkpointDiff", () => {
       threadId,
       fromTurnCount: 1,
       toTurnCount: 2,
+      ignoreWhitespace: false,
     } as const;
 
     expect(
@@ -44,10 +45,58 @@ describe("providerQueryKeys.checkpointDiff", () => {
       }),
     );
   });
+
+  it("includes ignoreWhitespace so normal and whitespace-hidden diffs do not collide", () => {
+    const baseInput = {
+      environmentId,
+      threadId,
+      fromTurnCount: 1,
+      toTurnCount: 2,
+      cacheScope: "turn:abc",
+    } as const;
+
+    expect(
+      providerQueryKeys.checkpointDiff({
+        ...baseInput,
+        ignoreWhitespace: false,
+      }),
+    ).not.toEqual(
+      providerQueryKeys.checkpointDiff({
+        ...baseInput,
+        ignoreWhitespace: true,
+      }),
+    );
+  });
 });
 
 describe("checkpointDiffQueryOptions", () => {
-  it("forwards checkpoint range to the provider API", async () => {
+  it("forwards checkpoint range to the provider API by default", async () => {
+    const getTurnDiff = vi.fn().mockResolvedValue({ diff: "patch" });
+    const getFullThreadDiff = vi.fn().mockResolvedValue({ diff: "patch" });
+    mockNativeApi({ getTurnDiff, getFullThreadDiff });
+
+    const options = checkpointDiffQueryOptions({
+      environmentId,
+      threadId,
+      fromTurnCount: 3,
+      toTurnCount: 4,
+      ignoreWhitespace: false,
+      cacheScope: "turn:abc",
+    });
+
+    const queryClient = new QueryClient();
+    await queryClient.fetchQuery(options);
+
+    expect(getTurnDiff).toHaveBeenCalledWith({
+      threadId,
+      fromTurnCount: 3,
+      toTurnCount: 4,
+      ignoreWhitespace: false,
+    });
+    expect(getFullThreadDiff).not.toHaveBeenCalled();
+  });
+
+  it("forwards whitespace-hidden checkpoint range to the provider API", async () => {
     const getTurnDiff = vi.fn().mockResolvedValue({ diff: "patch" });
     const getFullThreadDiff = vi.fn().mockResolvedValue({ diff: "patch" });
     mockNativeApi({ getTurnDiff, getFullThreadDiff });
@@ -57,6 +106,7 @@ describe("checkpointDiffQueryOptions", () => {
       threadId,
       fromTurnCount: 3,
       toTurnCount: 4,
+      ignoreWhitespace: true,
       cacheScope: "turn:abc",
     });
 
@@ -67,6 +117,7 @@ describe("checkpointDiffQueryOptions", () => {
       threadId,
       fromTurnCount: 3,
       toTurnCount: 4,
+      ignoreWhitespace: true,
     });
     expect(getFullThreadDiff).not.toHaveBeenCalled();
   });
@@ -81,6 +132,7 @@ describe("checkpointDiffQueryOptions", () => {
       threadId,
       fromTurnCount: 0,
       toTurnCount: 2,
+      ignoreWhitespace: true,
       cacheScope: "thread:all",
     });
 
@@ -90,6 +142,7 @@ describe("checkpointDiffQueryOptions", () => {
     expect(getFullThreadDiff).toHaveBeenCalledWith({
       threadId,
       toTurnCount: 2,
+      ignoreWhitespace: true,
     });
     expect(getTurnDiff).not.toHaveBeenCalled();
   });
@@ -104,6 +157,7 @@ describe("checkpointDiffQueryOptions", () => {
       threadId,
       fromTurnCount: 4,
       toTurnCount: 3,
+      ignoreWhitespace: false,
       cacheScope: "turn:invalid",
     });
 
@@ -122,6 +176,7 @@ describe("checkpointDiffQueryOptions", () => {
       threadId,
       fromTurnCount: 1,
       toTurnCount: 2,
+      ignoreWhitespace: false,
       cacheScope: "turn:abc",
     });
     const retry = options.retry;
@@ -147,6 +202,7 @@ describe("checkpointDiffQueryOptions", () => {
       threadId,
       fromTurnCount: 1,
       toTurnCount: 2,
+      ignoreWhitespace: false,
       cacheScope: "turn:abc",
     });
     const retryDelay = options.retryDelay;
diff --git a/apps/web/src/lib/providerReactQuery.ts b/apps/web/src/lib/providerReactQuery.ts
index 20007fc8fb6..69ba1faef45 100644
--- a/apps/web/src/lib/providerReactQuery.ts
+++ b/apps/web/src/lib/providerReactQuery.ts
@@ -5,14 +5,19 @@ import {
   ThreadId,
 } from "@t3tools/contracts";
 import { queryOptions } from "@tanstack/react-query";
-import { Option, Schema } from "effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 import { ensureEnvironmentApi } from "../environmentApi";
 
+const decodeFullThreadDiffInput = Schema.decodeUnknownOption(OrchestrationGetFullThreadDiffInput);
+const decodeTurnDiffInput = Schema.decodeUnknownOption(OrchestrationGetTurnDiffInput);
+
 interface CheckpointDiffQueryInput {
   environmentId: EnvironmentId | null;
   threadId: ThreadId | null;
   fromTurnCount: number | null;
   toTurnCount: number | null;
+  ignoreWhitespace: boolean;
   cacheScope?: string | null;
   enabled?: boolean;
 }
@@ -27,22 +32,25 @@ export const providerQueryKeys = {
       input.threadId,
       input.fromTurnCount,
       input.toTurnCount,
+      input.ignoreWhitespace,
       input.cacheScope ?? null,
     ] as const,
 };
 
 function decodeCheckpointDiffRequest(input: CheckpointDiffQueryInput) {
   if (input.fromTurnCount === 0) {
-    return Schema.decodeUnknownOption(OrchestrationGetFullThreadDiffInput)({
+    return decodeFullThreadDiffInput({
       threadId: input.threadId,
       toTurnCount: input.toTurnCount,
+      ignoreWhitespace: input.ignoreWhitespace,
     }).pipe(Option.map((fields) => ({ kind: "fullThreadDiff" as const, input: fields })));
   }
 
-  return Schema.decodeUnknownOption(OrchestrationGetTurnDiffInput)({
+  return decodeTurnDiffInput({
     threadId: input.threadId,
     fromTurnCount: input.fromTurnCount,
     toTurnCount: input.toTurnCount,
+    ignoreWhitespace: input.ignoreWhitespace,
   }).pipe(Option.map((fields) => ({ kind: "turnDiff" as const, input: fields })));
 }
 
diff --git a/apps/web/src/lib/sourceControlDiscoveryState.ts b/apps/web/src/lib/sourceControlDiscoveryState.ts
new file mode 100644
index 00000000000..daff900a0d5
--- /dev/null
+++ b/apps/web/src/lib/sourceControlDiscoveryState.ts
@@ -0,0 +1,103 @@
+import { useAtomValue } from "@effect/atom-react";
+import {
+  type SourceControlDiscoveryTarget,
+  type SourceControlDiscoveryState,
+  createSourceControlDiscoveryManager,
+  getSourceControlDiscoveryTargetKey,
+  sourceControlDiscoveryStateAtom,
+} from "@t3tools/client-runtime";
+import { EnvironmentId, type SourceControlDiscoveryResult } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import { Atom } from "effect/unstable/reactivity";
+
+import { readPrimaryEnvironmentDescriptor } from "../environments/primary";
+import { readEnvironmentConnection } from "../environments/runtime";
+import { readLocalApi } from "../localApi";
+import { appAtomRegistry } from "../rpc/atomRegistry";
+
+const SOURCE_CONTROL_DISCOVERY_TARGET = { key: "primary" } as const;
+const SOURCE_CONTROL_DISCOVERY_STALE_TIME_MS = 30_000;
+const SOURCE_CONTROL_DISCOVERY_IDLE_TTL_MS = 5 * 60_000;
+
+interface SourceControlDiscoveryTargetInput {
+  readonly environmentId?: EnvironmentId | null;
+}
+
+function sourceControlDiscoveryTarget(
+  input?: SourceControlDiscoveryTargetInput,
+): SourceControlDiscoveryTarget {
+  const environmentId = input?.environmentId ?? null;
+  if (!environmentId) {
+    return SOURCE_CONTROL_DISCOVERY_TARGET;
+  }
+  return readPrimaryEnvironmentDescriptor()?.environmentId === environmentId
+    ? SOURCE_CONTROL_DISCOVERY_TARGET
+    : { key: environmentId };
+}
+
+export const sourceControlDiscoveryManager = createSourceControlDiscoveryManager({
+  getRegistry: () => appAtomRegistry,
+  getClient: (key) => {
+    if (key === SOURCE_CONTROL_DISCOVERY_TARGET.key) {
+      const primaryEnvironmentId = readPrimaryEnvironmentDescriptor()?.environmentId ?? null;
+      const primaryConnection = primaryEnvironmentId
+        ? readEnvironmentConnection(primaryEnvironmentId)
+        : null;
+      if (primaryConnection) {
+        return primaryConnection.client.server;
+      }
+      try {
+        return readLocalApi()?.server ?? null;
+      } catch {
+        return null;
+      }
+    }
+    const environmentId = EnvironmentId.make(key);
+    const connection = readEnvironmentConnection(environmentId);
+    if (connection) {
+      return connection.client.server;
+    }
+    return null;
+  },
+});
+
+const sourceControlDiscoveryAutoRefreshAtom = Atom.family((targetKey: string) =>
+  Atom.make(() =>
+    Effect.promise(() => sourceControlDiscoveryManager.refresh({ key: targetKey })),
+  ).pipe(
+    Atom.swr({
+      staleTime: SOURCE_CONTROL_DISCOVERY_STALE_TIME_MS,
+      revalidateOnMount: true,
+    }),
+    Atom.setIdleTTL(SOURCE_CONTROL_DISCOVERY_IDLE_TTL_MS),
+    Atom.withLabel(`source-control-discovery:auto-refresh:${targetKey}`),
+  ),
+);
+
+export function refreshSourceControlDiscovery(
+  input?: SourceControlDiscoveryTargetInput,
+): Promise<SourceControlDiscoveryResult | null> {
+  return sourceControlDiscoveryManager.refresh(sourceControlDiscoveryTarget(input));
+}
+
+export function getSourceControlDiscoverySnapshot(
+  input?: SourceControlDiscoveryTargetInput,
+): SourceControlDiscoveryState {
+  return sourceControlDiscoveryManager.getSnapshot(sourceControlDiscoveryTarget(input));
+}
+
+export function resetSourceControlDiscoveryStateForTests(): void {
+  sourceControlDiscoveryManager.reset();
+}
+
+export function useSourceControlDiscovery(
+  input?: SourceControlDiscoveryTargetInput,
+): SourceControlDiscoveryState {
+  const targetKey =
+    getSourceControlDiscoveryTargetKey(sourceControlDiscoveryTarget(input)) ??
+    SOURCE_CONTROL_DISCOVERY_TARGET.key;
+
+  useAtomValue(sourceControlDiscoveryAutoRefreshAtom(targetKey));
+
+  return useAtomValue(sourceControlDiscoveryStateAtom(targetKey));
+}
diff --git a/apps/web/src/lib/threadSort.test.ts b/apps/web/src/lib/threadSort.test.ts
index f80260a69da..2a69357c49e 100644
--- a/apps/web/src/lib/threadSort.test.ts
+++ b/apps/web/src/lib/threadSort.test.ts
@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { DEFAULT_RUNTIME_MODE, EnvironmentId, ProjectId, ThreadId } from "@t3tools/contracts";
+import {
+  DEFAULT_RUNTIME_MODE,
+  EnvironmentId,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+} from "@t3tools/contracts";
 import type { Thread } from "../types";
 import { getLatestThreadForProject, sortThreads } from "./threadSort";
 
@@ -13,7 +19,7 @@ function makeThread(overrides: Partial<Thread> = {}): Thread {
     codexThreadId: null,
     projectId: PROJECT_ID,
     title: "Thread",
-    modelSelection: { provider: "codex", model: "gpt-5.4" },
+    modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
     runtimeMode: DEFAULT_RUNTIME_MODE,
     interactionMode: "default",
     session: null,
diff --git a/apps/web/src/lib/traceDiagnosticsState.ts b/apps/web/src/lib/traceDiagnosticsState.ts
new file mode 100644
index 00000000000..73d9a6c3949
--- /dev/null
+++ b/apps/web/src/lib/traceDiagnosticsState.ts
@@ -0,0 +1,65 @@
+import { useAtomValue } from "@effect/atom-react";
+import type { ServerTraceDiagnosticsResult } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { AsyncResult, Atom } from "effect/unstable/reactivity";
+import { useCallback } from "react";
+
+import { ensureLocalApi } from "../localApi";
+import { appAtomRegistry } from "../rpc/atomRegistry";
+
+const TRACE_DIAGNOSTICS_STALE_TIME_MS = 5_000;
+const TRACE_DIAGNOSTICS_IDLE_TTL_MS = 5 * 60_000;
+
+const traceDiagnosticsAtom = Atom.make(
+  Effect.promise(() => ensureLocalApi().server.getTraceDiagnostics()),
+).pipe(
+  Atom.swr({
+    staleTime: TRACE_DIAGNOSTICS_STALE_TIME_MS,
+    revalidateOnMount: true,
+  }),
+  Atom.setIdleTTL(TRACE_DIAGNOSTICS_IDLE_TTL_MS),
+  Atom.withLabel("trace-diagnostics"),
+);
+
+export interface TraceDiagnosticsState {
+  readonly data: ServerTraceDiagnosticsResult | null;
+  readonly error: string | null;
+  readonly isPending: boolean;
+  readonly refresh: () => void;
+}
+
+function formatTraceDiagnosticsError(error: unknown): string {
+  return error instanceof Error ? error.message : "Failed to load trace diagnostics.";
+}
+
+function readTraceDiagnosticsError(
+  result: AsyncResult.AsyncResult<ServerTraceDiagnosticsResult, unknown>,
+): string | null {
+  if (result._tag !== "Failure") {
+    return null;
+  }
+
+  const squashed = Cause.squash(result.cause);
+  return formatTraceDiagnosticsError(squashed);
+}
+
+export function refreshTraceDiagnostics(): void {
+  appAtomRegistry.refresh(traceDiagnosticsAtom);
+}
+
+export function useTraceDiagnostics(): TraceDiagnosticsState {
+  const result = useAtomValue(traceDiagnosticsAtom);
+  const data = Option.getOrNull(AsyncResult.value(result));
+  const refresh = useCallback(() => {
+    refreshTraceDiagnostics();
+  }, []);
+
+  return {
+    data,
+    error: readTraceDiagnosticsError(result),
+    isPending: result.waiting,
+    refresh,
+  };
+}
diff --git a/apps/web/src/lib/windowControlsOverlay.ts b/apps/web/src/lib/windowControlsOverlay.ts
new file mode 100644
index 00000000000..8f9ae786b0e
--- /dev/null
+++ b/apps/web/src/lib/windowControlsOverlay.ts
@@ -0,0 +1,40 @@
+const WCO_CLASS_NAME = "wco";
+
+interface WindowControlsOverlayLike {
+  readonly visible: boolean;
+  addEventListener(type: "geometrychange", listener: EventListener): void;
+  removeEventListener(type: "geometrychange", listener: EventListener): void;
+}
+
+interface NavigatorWithWindowControlsOverlay extends Navigator {
+  readonly windowControlsOverlay?: WindowControlsOverlayLike;
+}
+
+function getWindowControlsOverlay(): WindowControlsOverlayLike | null {
+  if (typeof navigator === "undefined") {
+    return null;
+  }
+
+  return (navigator as NavigatorWithWindowControlsOverlay).windowControlsOverlay ?? null;
+}
+
+export function syncDocumentWindowControlsOverlayClass(): () => void {
+  if (typeof document === "undefined") {
+    return () => {};
+  }
+
+  const overlay = getWindowControlsOverlay();
+  const update = () => {
+    document.documentElement.classList.toggle(WCO_CLASS_NAME, overlay !== null && overlay.visible);
+  };
+
+  update();
+  if (!overlay) {
+    return () => {};
+  }
+
+  overlay.addEventListener("geometrychange", update);
+  return () => {
+    overlay.removeEventListener("geometrychange", update);
+  };
+}
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 3883d77c8dc..8bfb0e599ad 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -3,10 +3,11 @@ import {
   DEFAULT_SERVER_SETTINGS,
   type DesktopBridge,
   EnvironmentId,
-  EventId,
-  type GitStatusResult,
+  type VcsStatusResult,
   ProjectId,
-  type OrchestrationEvent,
+  type OrchestrationShellStreamItem,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerConfig,
   type ServerProvider,
   type TerminalEvent,
@@ -32,8 +33,8 @@ function registerListener<T>(listeners: Set<(event: T) => void>, listener: (even
 }
 
 const terminalEventListeners = new Set<(event: TerminalEvent) => void>();
-const orchestrationEventListeners = new Set<(event: OrchestrationEvent) => void>();
-const gitStatusListeners = new Set<(event: GitStatusResult) => void>();
+const shellStreamListeners = new Set<(event: OrchestrationShellStreamItem) => void>();
+const gitStatusListeners = new Set<(event: VcsStatusResult) => void>();
 
 const rpcClientMock = {
   dispose: vi.fn(),
@@ -52,28 +53,39 @@ const rpcClientMock = {
     searchEntries: vi.fn(),
     writeFile: vi.fn(),
   },
+  filesystem: {
+    browse: vi.fn(),
+  },
+  sourceControl: {
+    lookupRepository: vi.fn(),
+    cloneRepository: vi.fn(),
+    publishRepository: vi.fn(),
+  },
   shell: {
     openInEditor: vi.fn(),
   },
-  git: {
+  vcs: {
     pull: vi.fn(),
     refreshStatus: vi.fn(),
-    onStatus: vi.fn((input: { cwd: string }, listener: (event: GitStatusResult) => void) =>
+    onStatus: vi.fn((input: { cwd: string }, listener: (event: VcsStatusResult) => void) =>
       registerListener(gitStatusListeners, listener),
     ),
-    runStackedAction: vi.fn(),
-    listBranches: vi.fn(),
+    listRefs: vi.fn(),
     createWorktree: vi.fn(),
     removeWorktree: vi.fn(),
-    createBranch: vi.fn(),
-    checkout: vi.fn(),
+    createRef: vi.fn(),
+    switchRef: vi.fn(),
     init: vi.fn(),
+  },
+  git: {
+    runStackedAction: vi.fn(),
     resolvePullRequest: vi.fn(),
     preparePullRequestThread: vi.fn(),
   },
   server: {
     getConfig: vi.fn(),
     refreshProviders: vi.fn(),
+    updateProvider: vi.fn(),
     upsertKeybinding: vi.fn(),
     getSettings: vi.fn(),
     updateSettings: vi.fn(),
@@ -82,14 +94,13 @@ const rpcClientMock = {
     subscribeAuthAccess: vi.fn(),
   },
   orchestration: {
-    getSnapshot: vi.fn(),
     dispatchCommand: vi.fn(),
     getTurnDiff: vi.fn(),
     getFullThreadDiff: vi.fn(),
-    replayEvents: vi.fn(),
-    onDomainEvent: vi.fn((listener: (event: OrchestrationEvent) => void) =>
-      registerListener(orchestrationEventListeners, listener),
+    subscribeShell: vi.fn((listener: (event: OrchestrationShellStreamItem) => void) =>
+      registerListener(shellStreamListeners, listener),
     ),
+    subscribeThread: vi.fn(() => () => undefined),
   },
 };
 
@@ -159,6 +170,7 @@ function createLocalStorageStub(): Storage {
 
 function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridge {
   return {
+    getAppBranding: () => null,
     getLocalEnvironmentBootstrap: () => null,
     getClientSettings: async () => null,
     setClientSettings: async () => undefined,
@@ -167,16 +179,47 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
     getSavedEnvironmentSecret: async () => null,
     setSavedEnvironmentSecret: async () => true,
     removeSavedEnvironmentSecret: async () => undefined,
+    discoverSshHosts: async () => [],
+    ensureSshEnvironment: async () => {
+      throw new Error("ensureSshEnvironment not implemented in test");
+    },
+    disconnectSshEnvironment: async () => undefined,
+    fetchSshEnvironmentDescriptor: async () => {
+      throw new Error("fetchSshEnvironmentDescriptor not implemented in test");
+    },
+    bootstrapSshBearerSession: async () => {
+      throw new Error("bootstrapSshBearerSession not implemented in test");
+    },
+    fetchSshSessionState: async () => {
+      throw new Error("fetchSshSessionState not implemented in test");
+    },
+    issueSshWebSocketToken: async () => {
+      throw new Error("issueSshWebSocketToken not implemented in test");
+    },
+    onSshPasswordPrompt: () => () => undefined,
+    resolveSshPasswordPrompt: async () => undefined,
     getServerExposureState: async () => ({
       mode: "local-only",
       endpointUrl: null,
       advertisedHost: null,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
     }),
     setServerExposureMode: async () => ({
       mode: "local-only",
       endpointUrl: null,
       advertisedHost: null,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
     }),
+    setTailscaleServeEnabled: async (input) => ({
+      mode: "local-only",
+      endpointUrl: null,
+      advertisedHost: null,
+      tailscaleServeEnabled: input.enabled,
+      tailscaleServePort: input.port ?? 443,
+    }),
+    getAdvertisedEndpoints: async () => [],
     pickFolder: async () => null,
     confirm: async () => true,
     setTheme: async () => undefined,
@@ -186,6 +229,9 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
     getUpdateState: async () => {
       throw new Error("getUpdateState not implemented in test");
     },
+    setUpdateChannel: async () => {
+      throw new Error("setUpdateChannel not implemented in test");
+    },
     checkForUpdate: async () => {
       throw new Error("checkForUpdate not implemented in test");
     },
@@ -202,7 +248,8 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
 
 const defaultProviders: ReadonlyArray<ServerProvider> = [
   {
-    provider: "codex",
+    instanceId: ProviderInstanceId.make("codex"),
+    driver: ProviderDriverKind.make("codex"),
     enabled: true,
     installed: true,
     version: "0.116.0",
@@ -251,11 +298,11 @@ const baseServerConfig: ServerConfig = {
   settings: DEFAULT_SERVER_SETTINGS,
 };
 
-const baseGitStatus: GitStatusResult = {
+const baseGitStatus: VcsStatusResult = {
   isRepo: true,
-  hasOriginRemote: true,
-  isDefaultBranch: false,
-  branch: "feature/streamed",
+  hasPrimaryRemote: true,
+  isDefaultRef: false,
+  refName: "feature/streamed",
   hasWorkingTreeChanges: false,
   workingTree: { files: [], insertions: 0, deletions: 0 },
   hasUpstream: true,
@@ -269,7 +316,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   showContextMenuFallbackMock.mockReset();
   terminalEventListeners.clear();
-  orchestrationEventListeners.clear();
+  shellStreamListeners.clear();
   gitStatusListeners.clear();
   const testWindow = getWindowForTest();
   Reflect.deleteProperty(testWindow, "desktopBridge");
@@ -296,15 +343,15 @@ describe("wsApi", () => {
     expect(rpcClientMock.server.subscribeLifecycle).not.toHaveBeenCalled();
   });
 
-  it("forwards terminal and orchestration stream events", async () => {
+  it("forwards terminal and shell stream events", async () => {
     const { createEnvironmentApi } = await import("./environmentApi");
 
     const api = createEnvironmentApi(rpcClientMock as never);
     const onTerminalEvent = vi.fn();
-    const onDomainEvent = vi.fn();
+    const onShellEvent = vi.fn();
 
     api.terminal.onEvent(onTerminalEvent);
-    api.orchestration.onDomainEvent(onDomainEvent);
+    api.orchestration.subscribeShell(onShellEvent);
 
     const terminalEvent = {
       threadId: "thread-1",
@@ -315,34 +362,26 @@ describe("wsApi", () => {
     } as const;
     emitEvent(terminalEventListeners, terminalEvent);
 
-    const orchestrationEvent = {
+    const shellEvent = {
+      kind: "project-upserted" as const,
       sequence: 1,
-      eventId: EventId.make("event-1"),
-      aggregateKind: "project",
-      aggregateId: ProjectId.make("project-1"),
-      occurredAt: "2026-02-24T00:00:00.000Z",
-      commandId: null,
-      causationEventId: null,
-      correlationId: null,
-      metadata: {},
-      type: "project.created",
-      payload: {
-        projectId: ProjectId.make("project-1"),
+      project: {
+        id: ProjectId.make("project-1"),
         title: "Project",
         workspaceRoot: "/tmp/workspace",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         scripts: [],
         createdAt: "2026-02-24T00:00:00.000Z",
         updatedAt: "2026-02-24T00:00:00.000Z",
       },
-    } satisfies Extract<OrchestrationEvent, { type: "project.created" }>;
-    emitEvent(orchestrationEventListeners, orchestrationEvent);
+    } satisfies OrchestrationShellStreamItem;
+    emitEvent(shellStreamListeners, shellEvent);
 
     expect(onTerminalEvent).toHaveBeenCalledWith(terminalEvent);
-    expect(onDomainEvent).toHaveBeenCalledWith(orchestrationEvent);
+    expect(onShellEvent).toHaveBeenCalledWith(shellEvent);
   });
 
   it("forwards git status stream events", async () => {
@@ -351,36 +390,36 @@ describe("wsApi", () => {
     const api = createEnvironmentApi(rpcClientMock as never);
     const onStatus = vi.fn();
 
-    api.git.onStatus({ cwd: "/repo" }, onStatus);
+    api.vcs.onStatus({ cwd: "/repo" }, onStatus);
 
     const gitStatus = baseGitStatus;
     emitEvent(gitStatusListeners, gitStatus);
 
-    expect(rpcClientMock.git.onStatus).toHaveBeenCalledWith({ cwd: "/repo" }, onStatus, undefined);
+    expect(rpcClientMock.vcs.onStatus).toHaveBeenCalledWith({ cwd: "/repo" }, onStatus, undefined);
     expect(onStatus).toHaveBeenCalledWith(gitStatus);
   });
 
   it("forwards git status refreshes directly to the RPC client", async () => {
-    rpcClientMock.git.refreshStatus.mockResolvedValue(baseGitStatus);
+    rpcClientMock.vcs.refreshStatus.mockResolvedValue(baseGitStatus);
     const { createEnvironmentApi } = await import("./environmentApi");
 
     const api = createEnvironmentApi(rpcClientMock as never);
 
-    await api.git.refreshStatus({ cwd: "/repo" });
+    await api.vcs.refreshStatus({ cwd: "/repo" });
 
-    expect(rpcClientMock.git.refreshStatus).toHaveBeenCalledWith({ cwd: "/repo" });
+    expect(rpcClientMock.vcs.refreshStatus).toHaveBeenCalledWith({ cwd: "/repo" });
   });
 
-  it("forwards orchestration stream subscription options to the RPC client", async () => {
+  it("forwards shell stream subscription options to the RPC client", async () => {
     const { createEnvironmentApi } = await import("./environmentApi");
 
     const api = createEnvironmentApi(rpcClientMock as never);
-    const onDomainEvent = vi.fn();
+    const onShellEvent = vi.fn();
     const onResubscribe = vi.fn();
 
-    api.orchestration.onDomainEvent(onDomainEvent, { onResubscribe });
+    api.orchestration.subscribeShell(onShellEvent, { onResubscribe });
 
-    expect(rpcClientMock.orchestration.onDomainEvent).toHaveBeenCalledWith(onDomainEvent, {
+    expect(rpcClientMock.orchestration.subscribeShell).toHaveBeenCalledWith(onShellEvent, {
       onResubscribe,
     });
   });
@@ -397,7 +436,7 @@ describe("wsApi", () => {
       title: "Project",
       workspaceRoot: "/tmp/project",
       defaultModelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
       createdAt: "2026-02-24T00:00:00.000Z",
@@ -425,6 +464,25 @@ describe("wsApi", () => {
     });
   });
 
+  it("forwards filesystem browse requests to the RPC client", async () => {
+    rpcClientMock.filesystem.browse.mockResolvedValue({
+      parentPath: "/tmp/project/",
+      entries: [],
+    });
+    const { createEnvironmentApi } = await import("./environmentApi");
+
+    const api = createEnvironmentApi(rpcClientMock as never);
+    await api.filesystem.browse({
+      partialPath: "/tmp/project/",
+      cwd: "/tmp/project",
+    });
+
+    expect(rpcClientMock.filesystem.browse).toHaveBeenCalledWith({
+      partialPath: "/tmp/project/",
+      cwd: "/tmp/project",
+    });
+  });
+
   it("forwards full-thread diff requests to the orchestration RPC", async () => {
     rpcClientMock.orchestration.getFullThreadDiff.mockResolvedValue({ diff: "patch" });
     const { createEnvironmentApi } = await import("./environmentApi");
@@ -457,6 +515,34 @@ describe("wsApi", () => {
     expect(rpcClientMock.server.refreshProviders).toHaveBeenCalledWith();
   });
 
+  it("forwards provider updates directly to the RPC client", async () => {
+    const nextProviders: ReadonlyArray<ServerProvider> = [
+      {
+        ...defaultProviders[0]!,
+        updateState: {
+          status: "succeeded",
+          startedAt: "2026-01-03T00:00:00.000Z",
+          finishedAt: "2026-01-03T00:00:01.000Z",
+          message: "Provider updated.",
+          output: null,
+        },
+      },
+    ];
+    rpcClientMock.server.updateProvider.mockResolvedValue({ providers: nextProviders });
+    const { createLocalApi } = await import("./localApi");
+
+    const api = createLocalApi(rpcClientMock as never);
+
+    await expect(
+      api.server.updateProvider({ provider: ProviderDriverKind.make("codex") }),
+    ).resolves.toEqual({
+      providers: nextProviders,
+    });
+    expect(rpcClientMock.server.updateProvider).toHaveBeenCalledWith({
+      provider: ProviderDriverKind.make("codex"),
+    });
+  });
+
   it("forwards server settings updates directly to the RPC client", async () => {
     const nextSettings = {
       ...DEFAULT_SERVER_SETTINGS,
@@ -487,6 +573,19 @@ describe("wsApi", () => {
     expect(showContextMenu).toHaveBeenCalledWith(items, undefined);
   });
 
+  it("forwards folder picker options to the desktop bridge", async () => {
+    const pickFolder = vi.fn().mockResolvedValue("/tmp/project");
+    getWindowForTest().desktopBridge = makeDesktopBridge({ pickFolder });
+
+    const { createLocalApi } = await import("./localApi");
+    const api = createLocalApi(rpcClientMock as never);
+
+    await expect(api.dialogs.pickFolder({ initialPath: "/tmp/workspace" })).resolves.toBe(
+      "/tmp/project",
+    );
+    expect(pickFolder).toHaveBeenCalledWith({ initialPath: "/tmp/workspace" });
+  });
+
   it("falls back to the browser context menu helper when the desktop bridge is missing", async () => {
     showContextMenuFallbackMock.mockResolvedValue("rename");
     const { createLocalApi } = await import("./localApi");
@@ -499,13 +598,26 @@ describe("wsApi", () => {
   });
 
   it("reads and writes persistence through the desktop bridge when available", async () => {
-    const getClientSettings = vi.fn().mockResolvedValue({
+    const clientSettings = {
+      autoOpenPlanSidebar: false,
       confirmThreadArchive: true,
       confirmThreadDelete: false,
+      dismissedProviderUpdateNotificationKeys: [],
+      diffIgnoreWhitespace: true,
       diffWordWrap: true,
-      sidebarProjectSortOrder: "manual",
-      sidebarThreadSortOrder: "created_at",
-      timestampFormat: "24-hour",
+      favorites: [],
+      providerModelPreferences: {},
+      sidebarProjectGroupingMode: "repository_path" as const,
+      sidebarProjectGroupingOverrides: {
+        "environment-local:/tmp/project": "separate" as const,
+      },
+      sidebarProjectSortOrder: "manual" as const,
+      sidebarThreadSortOrder: "created_at" as const,
+      sidebarThreadPreviewCount: 6,
+      timestampFormat: "24-hour" as const,
+    };
+    const getClientSettings = vi.fn().mockResolvedValue({
+      ...clientSettings,
     });
     const setClientSettings = vi.fn().mockResolvedValue(undefined);
     const getSavedEnvironmentRegistry = vi.fn().mockResolvedValue([]);
@@ -527,14 +639,7 @@ describe("wsApi", () => {
     const api = createLocalApi(rpcClientMock as never);
 
     await api.persistence.getClientSettings();
-    await api.persistence.setClientSettings({
-      confirmThreadArchive: true,
-      confirmThreadDelete: false,
-      diffWordWrap: true,
-      sidebarProjectSortOrder: "manual",
-      sidebarThreadSortOrder: "created_at",
-      timestampFormat: "24-hour",
-    });
+    await api.persistence.setClientSettings(clientSettings);
     await api.persistence.getSavedEnvironmentRegistry();
     await api.persistence.setSavedEnvironmentRegistry([]);
     await api.persistence.getSavedEnvironmentSecret(EnvironmentId.make("environment-local"));
@@ -545,14 +650,7 @@ describe("wsApi", () => {
     await api.persistence.removeSavedEnvironmentSecret(EnvironmentId.make("environment-local"));
 
     expect(getClientSettings).toHaveBeenCalledWith();
-    expect(setClientSettings).toHaveBeenCalledWith({
-      confirmThreadArchive: true,
-      confirmThreadDelete: false,
-      diffWordWrap: true,
-      sidebarProjectSortOrder: "manual",
-      sidebarThreadSortOrder: "created_at",
-      timestampFormat: "24-hour",
-    });
+    expect(setClientSettings).toHaveBeenCalledWith(clientSettings);
     expect(getSavedEnvironmentRegistry).toHaveBeenCalledWith();
     expect(setSavedEnvironmentRegistry).toHaveBeenCalledWith([]);
     expect(getSavedEnvironmentSecret).toHaveBeenCalledWith("environment-local");
@@ -563,15 +661,26 @@ describe("wsApi", () => {
   it("falls back to browser storage for persistence when the desktop bridge is missing", async () => {
     const { createLocalApi } = await import("./localApi");
     const api = createLocalApi(rpcClientMock as never);
-
-    await api.persistence.setClientSettings({
+    const clientSettings = {
+      autoOpenPlanSidebar: false,
       confirmThreadArchive: true,
       confirmThreadDelete: false,
+      dismissedProviderUpdateNotificationKeys: [],
+      diffIgnoreWhitespace: true,
       diffWordWrap: true,
-      sidebarProjectSortOrder: "manual",
-      sidebarThreadSortOrder: "created_at",
-      timestampFormat: "24-hour",
-    });
+      favorites: [],
+      providerModelPreferences: {},
+      sidebarProjectGroupingMode: "repository_path" as const,
+      sidebarProjectGroupingOverrides: {
+        "environment-local:/tmp/project": "separate" as const,
+      },
+      sidebarProjectSortOrder: "manual" as const,
+      sidebarThreadSortOrder: "created_at" as const,
+      sidebarThreadPreviewCount: 6,
+      timestampFormat: "24-hour" as const,
+    };
+
+    await api.persistence.setClientSettings(clientSettings);
     await api.persistence.setSavedEnvironmentRegistry([
       {
         environmentId: EnvironmentId.make("environment-local"),
@@ -587,14 +696,7 @@ describe("wsApi", () => {
       "bearer-token",
     );
 
-    await expect(api.persistence.getClientSettings()).resolves.toEqual({
-      confirmThreadArchive: true,
-      confirmThreadDelete: false,
-      diffWordWrap: true,
-      sidebarProjectSortOrder: "manual",
-      sidebarThreadSortOrder: "created_at",
-      timestampFormat: "24-hour",
-    });
+    await expect(api.persistence.getClientSettings()).resolves.toEqual(clientSettings);
     await expect(api.persistence.getSavedEnvironmentRegistry()).resolves.toEqual([
       {
         environmentId: EnvironmentId.make("environment-local"),
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index 40ed014580a..ba097d2ff6b 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -1,6 +1,7 @@
 import type { ContextMenuItem, LocalApi } from "@t3tools/contracts";
 
 import { resetGitStatusStateForTests } from "./lib/gitStatusState";
+import { resetSourceControlDiscoveryStateForTests } from "./lib/sourceControlDiscoveryState";
 import { resetRequestLatencyStateForTests } from "./rpc/requestLatencyState";
 import { resetServerStateForTests } from "./rpc/serverState";
 import { resetWsConnectionStateForTests } from "./rpc/wsConnectionState";
@@ -12,6 +13,7 @@ import {
   getPrimaryEnvironmentConnection,
   resetEnvironmentServiceForTests,
 } from "./environments/runtime";
+import { getPrimaryKnownEnvironment } from "./environments/primary";
 import { type WsRpcClient } from "./rpc/wsRpcClient";
 import { showContextMenuFallback } from "./contextMenuFallback";
 import {
@@ -26,12 +28,16 @@ import {
 
 let cachedApi: LocalApi | undefined;
 
-export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
+function unavailableLocalBackendError(): Error {
+  return new Error("Local backend API is unavailable before a backend is paired.");
+}
+
+function createBrowserLocalApi(rpcClient?: WsRpcClient): LocalApi {
   return {
     dialogs: {
-      pickFolder: async () => {
+      pickFolder: async (options) => {
         if (!window.desktopBridge) return null;
-        return window.desktopBridge.pickFolder();
+        return window.desktopBridge.pickFolder(options);
       },
       confirm: async (message) => {
         if (window.desktopBridge) {
@@ -41,7 +47,10 @@ export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
       },
     },
     shell: {
-      openInEditor: (cwd, editor) => rpcClient.shell.openInEditor({ cwd, editor }),
+      openInEditor: (cwd, editor) =>
+        rpcClient
+          ? rpcClient.shell.openInEditor({ cwd, editor })
+          : Promise.reject(unavailableLocalBackendError()),
       openExternal: async (url) => {
         if (window.desktopBridge) {
           const opened = await window.desktopBridge.openExternal(url);
@@ -110,15 +119,58 @@ export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
       },
     },
     server: {
-      getConfig: rpcClient.server.getConfig,
-      refreshProviders: rpcClient.server.refreshProviders,
-      upsertKeybinding: rpcClient.server.upsertKeybinding,
-      getSettings: rpcClient.server.getSettings,
-      updateSettings: rpcClient.server.updateSettings,
+      getConfig: () =>
+        rpcClient ? rpcClient.server.getConfig() : Promise.reject(unavailableLocalBackendError()),
+      refreshProviders: () =>
+        rpcClient
+          ? rpcClient.server.refreshProviders()
+          : Promise.reject(unavailableLocalBackendError()),
+      updateProvider: (input) =>
+        rpcClient
+          ? rpcClient.server.updateProvider(input)
+          : Promise.reject(unavailableLocalBackendError()),
+      upsertKeybinding: (input) =>
+        rpcClient
+          ? rpcClient.server.upsertKeybinding(input)
+          : Promise.reject(unavailableLocalBackendError()),
+      removeKeybinding: (input) =>
+        rpcClient
+          ? rpcClient.server.removeKeybinding(input)
+          : Promise.reject(unavailableLocalBackendError()),
+      getSettings: () =>
+        rpcClient ? rpcClient.server.getSettings() : Promise.reject(unavailableLocalBackendError()),
+      updateSettings: (patch) =>
+        rpcClient
+          ? rpcClient.server.updateSettings(patch)
+          : Promise.reject(unavailableLocalBackendError()),
+      discoverSourceControl: () =>
+        rpcClient
+          ? rpcClient.server.discoverSourceControl()
+          : Promise.reject(unavailableLocalBackendError()),
+      getTraceDiagnostics: () =>
+        rpcClient
+          ? rpcClient.server.getTraceDiagnostics()
+          : Promise.reject(unavailableLocalBackendError()),
+      getProcessDiagnostics: () =>
+        rpcClient
+          ? rpcClient.server.getProcessDiagnostics()
+          : Promise.reject(unavailableLocalBackendError()),
+      getProcessResourceHistory: (input) =>
+        rpcClient
+          ? rpcClient.server.getProcessResourceHistory(input)
+          : Promise.reject(unavailableLocalBackendError()),
+      signalProcess: (input) =>
+        rpcClient
+          ? rpcClient.server.signalProcess(input)
+          : Promise.reject(unavailableLocalBackendError()),
     },
   };
 }
 
+export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
+  return createBrowserLocalApi(rpcClient);
+}
+
 export function readLocalApi(): LocalApi | undefined {
   if (typeof window === "undefined") return undefined;
   if (cachedApi) return cachedApi;
@@ -128,7 +180,10 @@ export function readLocalApi(): LocalApi | undefined {
     return cachedApi;
   }
 
-  cachedApi = createLocalApi(getPrimaryEnvironmentConnection().client);
+  const primaryEnvironment = getPrimaryKnownEnvironment();
+  cachedApi = primaryEnvironment
+    ? createLocalApi(getPrimaryEnvironmentConnection().client)
+    : createBrowserLocalApi();
   return cachedApi;
 }
 
@@ -146,6 +201,7 @@ export async function __resetLocalApiForTests() {
   __resetClientSettingsPersistenceForTests();
   await resetEnvironmentServiceForTests();
   resetGitStatusStateForTests();
+  resetSourceControlDiscoveryStateForTests();
   resetRequestLatencyStateForTests();
   resetSavedEnvironmentRegistryStoreForTests();
   resetSavedEnvironmentRuntimeStoreForTests();
diff --git a/apps/web/src/logicalProject.ts b/apps/web/src/logicalProject.ts
index 789441877bc..72415d57de0 100644
--- a/apps/web/src/logicalProject.ts
+++ b/apps/web/src/logicalProject.ts
@@ -1,19 +1,172 @@
 import { scopedProjectKey, scopeProjectRef } from "@t3tools/client-runtime";
-import type { ScopedProjectRef } from "@t3tools/contracts";
+import type { ScopedProjectRef, SidebarProjectGroupingMode } from "@t3tools/contracts";
+import type { UnifiedSettings } from "@t3tools/contracts/settings";
+import { normalizeProjectPathForComparison } from "./lib/projectPaths";
 import type { Project } from "./types";
 
+export interface ProjectGroupingSettings {
+  sidebarProjectGroupingMode: SidebarProjectGroupingMode;
+  sidebarProjectGroupingOverrides: Record<string, SidebarProjectGroupingMode>;
+}
+
+export type ProjectGroupingMode = SidebarProjectGroupingMode;
+
+export function selectProjectGroupingSettings(settings: UnifiedSettings): ProjectGroupingSettings {
+  return {
+    sidebarProjectGroupingMode: settings.sidebarProjectGroupingMode,
+    sidebarProjectGroupingOverrides: settings.sidebarProjectGroupingOverrides,
+  };
+}
+
+function uniqueNonEmptyValues(values: ReadonlyArray<string | null | undefined>): string[] {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const value of values) {
+    const trimmed = value?.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    unique.push(trimmed);
+  }
+  return unique;
+}
+
+function deriveRepositoryRelativeProjectPath(
+  project: Pick<Project, "cwd" | "repositoryIdentity">,
+): string | null {
+  const rootPath = project.repositoryIdentity?.rootPath?.trim();
+  if (!rootPath) {
+    return null;
+  }
+
+  const normalizedProjectPath = normalizeProjectPathForComparison(project.cwd);
+  const normalizedRootPath = normalizeProjectPathForComparison(rootPath);
+  if (normalizedProjectPath.length === 0 || normalizedRootPath.length === 0) {
+    return null;
+  }
+
+  if (normalizedProjectPath === normalizedRootPath) {
+    return "";
+  }
+
+  const separator = normalizedRootPath.includes("\\") ? "\\" : "/";
+  const rootPrefix = `${normalizedRootPath}${separator}`;
+  if (!normalizedProjectPath.startsWith(rootPrefix)) {
+    return null;
+  }
+
+  return normalizedProjectPath.slice(rootPrefix.length).replaceAll("\\", "/");
+}
+
+export function derivePhysicalProjectKeyFromPath(environmentId: string, cwd: string): string {
+  return `${environmentId}:${normalizeProjectPathForComparison(cwd)}`;
+}
+
+export function derivePhysicalProjectKey(project: Pick<Project, "environmentId" | "cwd">): string {
+  return derivePhysicalProjectKeyFromPath(project.environmentId, project.cwd);
+}
+
+export function deriveProjectGroupingOverrideKey(
+  project: Pick<Project, "environmentId" | "cwd">,
+): string {
+  return derivePhysicalProjectKey(project);
+}
+
+// Key under which a project's manual sort order (projectOrder) is stored.
+// Must stay aligned with the writer side in `uiStateStore.syncProjects` and
+// the drag handlers in `Sidebar` so readers and writers agree.
+export function getProjectOrderKey(project: Pick<Project, "environmentId" | "cwd">): string {
+  return derivePhysicalProjectKey(project);
+}
+
+export function resolveProjectGroupingMode(
+  project: Pick<Project, "environmentId" | "cwd">,
+  settings: ProjectGroupingSettings,
+): SidebarProjectGroupingMode {
+  return (
+    settings.sidebarProjectGroupingOverrides?.[deriveProjectGroupingOverrideKey(project)] ??
+    settings.sidebarProjectGroupingMode
+  );
+}
+
+function deriveRepositoryScopedKey(
+  project: Pick<Project, "cwd" | "repositoryIdentity">,
+  groupingMode: SidebarProjectGroupingMode,
+): string | null {
+  const canonicalKey = project.repositoryIdentity?.canonicalKey;
+  if (!canonicalKey) {
+    return null;
+  }
+
+  if (groupingMode === "repository") {
+    return canonicalKey;
+  }
+
+  const relativeProjectPath = deriveRepositoryRelativeProjectPath(project);
+  if (relativeProjectPath === null) {
+    return canonicalKey;
+  }
+
+  return relativeProjectPath.length === 0
+    ? canonicalKey
+    : `${canonicalKey}::${relativeProjectPath}`;
+}
+
 export function deriveLogicalProjectKey(
-  project: Pick<Project, "environmentId" | "id" | "repositoryIdentity">,
+  project: Pick<Project, "environmentId" | "id" | "cwd" | "repositoryIdentity">,
+  options?: {
+    groupingMode?: SidebarProjectGroupingMode;
+  },
 ): string {
+  const groupingMode = options?.groupingMode ?? "repository";
+  if (groupingMode === "separate") {
+    return derivePhysicalProjectKey(project);
+  }
+
   return (
-    project.repositoryIdentity?.canonicalKey ??
+    deriveRepositoryScopedKey(project, groupingMode) ??
+    derivePhysicalProjectKey(project) ??
     scopedProjectKey(scopeProjectRef(project.environmentId, project.id))
   );
 }
 
+export function deriveLogicalProjectKeyFromSettings(
+  project: Pick<Project, "environmentId" | "id" | "cwd" | "repositoryIdentity">,
+  settings: ProjectGroupingSettings,
+): string {
+  return deriveLogicalProjectKey(project, {
+    groupingMode: resolveProjectGroupingMode(project, settings),
+  });
+}
+
 export function deriveLogicalProjectKeyFromRef(
   projectRef: ScopedProjectRef,
-  project: Pick<Project, "repositoryIdentity"> | null | undefined,
+  project: Pick<Project, "environmentId" | "id" | "cwd" | "repositoryIdentity"> | null | undefined,
+  options?: {
+    groupingMode?: SidebarProjectGroupingMode;
+  },
 ): string {
-  return project?.repositoryIdentity?.canonicalKey ?? scopedProjectKey(projectRef);
+  return project ? deriveLogicalProjectKey(project, options) : scopedProjectKey(projectRef);
+}
+
+export function deriveProjectGroupLabel(input: {
+  representative: Pick<Project, "name" | "repositoryIdentity">;
+  members: ReadonlyArray<Pick<Project, "name" | "repositoryIdentity">>;
+}): string {
+  const sharedDisplayNames = uniqueNonEmptyValues(
+    input.members.map((member) => member.repositoryIdentity?.displayName),
+  );
+  if (sharedDisplayNames.length === 1) {
+    return sharedDisplayNames[0]!;
+  }
+
+  const sharedRepositoryNames = uniqueNonEmptyValues(
+    input.members.map((member) => member.repositoryIdentity?.name),
+  );
+  if (sharedRepositoryNames.length === 1) {
+    return sharedRepositoryNames[0]!;
+  }
+
+  return input.representative.name;
 }
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index fda5913c977..68a7dfaa931 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -9,12 +9,17 @@ import "./index.css";
 import { isElectron } from "./env";
 import { getRouter } from "./router";
 import { APP_DISPLAY_NAME } from "./branding";
+import { syncDocumentWindowControlsOverlayClass } from "./lib/windowControlsOverlay";
 
 // Electron loads the app from a file-backed shell, so hash history avoids path resolution issues.
 const history = isElectron ? createHashHistory() : createBrowserHistory();
 
 const router = getRouter(history);
 
+if (isElectron) {
+  syncDocumentWindowControlsOverlayClass();
+}
+
 document.title = APP_DISPLAY_NAME;
 
 ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
diff --git a/apps/web/src/markdown-links.test.ts b/apps/web/src/markdown-links.test.ts
index d3ca8bc99a1..ae46c29a33a 100644
--- a/apps/web/src/markdown-links.test.ts
+++ b/apps/web/src/markdown-links.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { resolveMarkdownFileLinkTarget, rewriteMarkdownFileUriHref } from "./markdown-links";
+import {
+  resolveMarkdownFileLinkMeta,
+  resolveMarkdownFileLinkTarget,
+  rewriteMarkdownFileUriHref,
+} from "./markdown-links";
 
 describe("rewriteMarkdownFileUriHref", () => {
   it("rewrites file uri hrefs into direct path hrefs", () => {
@@ -14,6 +18,20 @@ describe("rewriteMarkdownFileUriHref", () => {
       "/Users/julius/project/file%2520name.md",
     );
   });
+
+  it("normalizes file uri hrefs for windows drive paths", () => {
+    expect(
+      rewriteMarkdownFileUriHref(
+        "file:///D:/Programme/t3code/apps/web/src/components/chat/OpenInPicker.tsx#L69",
+      ),
+    ).toBe("D:/Programme/t3code/apps/web/src/components/chat/OpenInPicker.tsx#L69");
+  });
+
+  it("unwraps angle-bracketed file uri hrefs", () => {
+    expect(
+      rewriteMarkdownFileUriHref(" <file:///D:/Programme/t3code/apps/web/src/markdown-links.ts> "),
+    ).toBe("D:/Programme/t3code/apps/web/src/markdown-links.ts");
+  });
 });
 
 describe("resolveMarkdownFileLinkTarget", () => {
@@ -57,6 +75,45 @@ describe("resolveMarkdownFileLinkTarget", () => {
     );
   });
 
+  it("formats tooltip display paths relative to the cwd when possible", () => {
+    expect(
+      resolveMarkdownFileLinkMeta(
+        "file:///C:/Users/mike/dev-stuff/t3code/apps/web/src/session-logic.ts#L501",
+        "C:/Users/mike/dev-stuff/t3code",
+      ),
+    ).toMatchObject({
+      displayPath: "t3code/apps/web/src/session-logic.ts:501",
+    });
+  });
+
+  it("formats tooltip display paths relative to the cwd for slash-prefixed windows paths", () => {
+    expect(
+      resolveMarkdownFileLinkMeta(
+        "/C:/Users/mike/dev-stuff/t3code/apps/web/src/components/chat/MessagesTimeline.virtualization.browser.tsx",
+        "C:/Users/mike/dev-stuff/t3code",
+      ),
+    ).toMatchObject({
+      displayPath:
+        "t3code/apps/web/src/components/chat/MessagesTimeline.virtualization.browser.tsx",
+    });
+  });
+
+  it("normalizes slash-prefixed windows drive paths before resolving", () => {
+    expect(
+      resolveMarkdownFileLinkTarget(
+        "/D:/Programme/t3code/apps/web/src/components/chat/OpenInPicker.tsx#L69",
+      ),
+    ).toBe("D:/Programme/t3code/apps/web/src/components/chat/OpenInPicker.tsx:69");
+  });
+
+  it("resolves angle-bracketed windows drive paths", () => {
+    expect(
+      resolveMarkdownFileLinkTarget(
+        "</D:/Programme/t3code/apps/web/src/components/ChatMarkdown.tsx:1>",
+      ),
+    ).toBe("D:/Programme/t3code/apps/web/src/components/ChatMarkdown.tsx:1");
+  });
+
   it("does not treat app routes as file links", () => {
     expect(resolveMarkdownFileLinkTarget("/chat/settings")).toBeNull();
   });
diff --git a/apps/web/src/markdown-links.ts b/apps/web/src/markdown-links.ts
index b5dcab01006..9ec4ee4564c 100644
--- a/apps/web/src/markdown-links.ts
+++ b/apps/web/src/markdown-links.ts
@@ -1,4 +1,5 @@
-import { resolvePathLinkTarget } from "./terminal-links";
+import { formatWorkspaceRelativePath } from "./filePathDisplay";
+import { resolvePathLinkTarget, splitPathAndPosition } from "./terminal-links";
 
 const WINDOWS_DRIVE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
 const WINDOWS_UNC_PATH_PATTERN = /^\\\\/;
@@ -21,6 +22,15 @@ const POSIX_FILE_ROOT_PREFIXES = [
   "/root/",
 ] as const;
 
+export interface MarkdownFileLinkMeta {
+  filePath: string;
+  targetPath: string;
+  displayPath: string;
+  basename: string;
+  line?: number;
+  column?: number;
+}
+
 function safeDecode(value: string): string {
   try {
     return decodeURIComponent(value);
@@ -29,6 +39,14 @@ function safeDecode(value: string): string {
   }
 }
 
+function unwrapMarkdownLinkDestination(value: string): string {
+  return value.startsWith("<") && value.endsWith(">") ? value.slice(1, -1) : value;
+}
+
+export function normalizeMarkdownLinkDestination(value: string): string {
+  return unwrapMarkdownLinkDestination(value.trim());
+}
+
 function stripSearchAndHash(value: string): { path: string; hash: string } {
   const hashIndex = value.indexOf("#");
   const pathWithSearch = hashIndex >= 0 ? value.slice(0, hashIndex) : value;
@@ -38,6 +56,10 @@ function stripSearchAndHash(value: string): { path: string; hash: string } {
   return { path, hash: rawHash };
 }
 
+function normalizeWindowsDrivePath(path: string): string {
+  return /^\/[A-Za-z]:[\\/]/.test(path) ? path.slice(1) : path;
+}
+
 function parseFileUrlHref(
   href: string,
   options?: { readonly decodePath?: boolean },
@@ -50,7 +72,7 @@ function parseFileUrlHref(
     if (rawPath.length === 0) return null;
 
     // Browser URL parser encodes "C:/foo" as "/C:/foo" for file URLs.
-    const normalizedPath = /^\/[A-Za-z]:[\\/]/.test(rawPath) ? rawPath.slice(1) : rawPath;
+    const normalizedPath = normalizeWindowsDrivePath(rawPath);
 
     return {
       path: options?.decodePath === false ? normalizedPath : safeDecode(normalizedPath),
@@ -63,7 +85,8 @@ function parseFileUrlHref(
 
 export function rewriteMarkdownFileUriHref(href: string | undefined): string | null {
   if (!href) return null;
-  const target = parseFileUrlHref(href.trim(), { decodePath: false });
+  const normalizedHref = normalizeMarkdownLinkDestination(href);
+  const target = parseFileUrlHref(normalizedHref, { decodePath: false });
   if (!target) return null;
   return `${target.path}${target.hash}`;
 }
@@ -114,14 +137,16 @@ export function resolveMarkdownFileLinkTarget(
   cwd?: string,
 ): string | null {
   if (!href) return null;
-  const rawHref = href.trim();
+  const rawHref = normalizeMarkdownLinkDestination(href);
   if (rawHref.length === 0 || rawHref.startsWith("#")) return null;
 
   const fileUrlTarget = rawHref.toLowerCase().startsWith("file:")
     ? parseFileUrlHref(rawHref)
     : null;
   const source = fileUrlTarget ?? stripSearchAndHash(rawHref);
-  const decodedPath = fileUrlTarget ? source.path.trim() : safeDecode(source.path.trim());
+  const decodedPath = normalizeWindowsDrivePath(
+    fileUrlTarget ? source.path.trim() : safeDecode(source.path.trim()),
+  );
   const decodedHash = safeDecode(source.hash.trim());
 
   if (decodedPath.length === 0) return null;
@@ -143,3 +168,31 @@ export function resolveMarkdownFileLinkTarget(
   if (!cwd) return null;
   return resolvePathLinkTarget(pathWithPosition, cwd);
 }
+
+function basenameOfPath(path: string): string {
+  const separatorIndex = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return separatorIndex >= 0 ? path.slice(separatorIndex + 1) : path;
+}
+
+export function resolveMarkdownFileLinkMeta(
+  href: string | undefined,
+  cwd?: string,
+): MarkdownFileLinkMeta | null {
+  const targetPath = resolveMarkdownFileLinkTarget(href, cwd);
+  if (!targetPath) return null;
+
+  const { path, line, column } = splitPathAndPosition(targetPath);
+  const parsedLine = line ? Number.parseInt(line, 10) : Number.NaN;
+  const parsedColumn = column ? Number.parseInt(column, 10) : Number.NaN;
+  const lineNumber = Number.isFinite(parsedLine) ? parsedLine : undefined;
+  const columnNumber = Number.isFinite(parsedColumn) ? parsedColumn : undefined;
+
+  return {
+    filePath: path,
+    targetPath,
+    displayPath: formatWorkspaceRelativePath(targetPath, cwd),
+    basename: basenameOfPath(path),
+    ...(lineNumber !== undefined ? { line: lineNumber } : {}),
+    ...(columnNumber !== undefined ? { column: columnNumber } : {}),
+  };
+}
diff --git a/apps/web/src/modelOrdering.test.ts b/apps/web/src/modelOrdering.test.ts
new file mode 100644
index 00000000000..82a9d8f9afd
--- /dev/null
+++ b/apps/web/src/modelOrdering.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { ProviderInstanceId } from "@t3tools/contracts";
+
+import {
+  providerModelKey,
+  sortModelsForProviderInstance,
+  sortProviderModelItems,
+} from "./modelOrdering";
+
+const CODEX_WORK_ID = ProviderInstanceId.make("codex_work");
+const CLAUDE_ID = ProviderInstanceId.make("claudeAgent");
+
+describe("model ordering", () => {
+  it("groups favorites first while preserving provider model order inside each group", () => {
+    const models = [
+      { slug: "gpt-5.5" },
+      { slug: "gpt-5.4-mini" },
+      { slug: "crest-alpha" },
+      { slug: "gpt-5.3-codex" },
+    ];
+
+    expect(
+      sortModelsForProviderInstance(models, {
+        favoriteModels: ["gpt-5.5", "gpt-5.4-mini", "crest-alpha"],
+        groupFavorites: true,
+        modelOrder: ["gpt-5.4-mini", "gpt-5.5", "crest-alpha", "gpt-5.3-codex"],
+      }).map((model) => model.slug),
+    ).toEqual(["gpt-5.4-mini", "gpt-5.5", "crest-alpha", "gpt-5.3-codex"]);
+  });
+
+  it("sorts the favorites view by provider order, then provider model order", () => {
+    const items = [
+      { instanceId: CODEX_WORK_ID, slug: "gpt-5.4-mini" },
+      { instanceId: CODEX_WORK_ID, slug: "gpt-5.5" },
+      { instanceId: CODEX_WORK_ID, slug: "crest-alpha" },
+      { instanceId: CLAUDE_ID, slug: "claude-opus-4-6" },
+    ];
+    const favoriteKeys = [
+      providerModelKey(CODEX_WORK_ID, "gpt-5.5"),
+      providerModelKey(CLAUDE_ID, "claude-opus-4-6"),
+      providerModelKey(CODEX_WORK_ID, "gpt-5.4-mini"),
+      providerModelKey(CODEX_WORK_ID, "crest-alpha"),
+    ];
+
+    expect(
+      sortProviderModelItems(items, {
+        favoriteModelKeys: favoriteKeys,
+        instanceOrder: [CODEX_WORK_ID, CLAUDE_ID],
+      }).map((item) => item.slug),
+    ).toEqual(["gpt-5.4-mini", "gpt-5.5", "crest-alpha", "claude-opus-4-6"]);
+  });
+});
diff --git a/apps/web/src/modelOrdering.ts b/apps/web/src/modelOrdering.ts
new file mode 100644
index 00000000000..c8b5d9cec64
--- /dev/null
+++ b/apps/web/src/modelOrdering.ts
@@ -0,0 +1,86 @@
+import type { ProviderInstanceId } from "@t3tools/contracts";
+import * as Arr from "effect/Array";
+import * as Order from "effect/Order";
+
+export interface ModelSlugItem {
+  readonly slug: string;
+}
+
+export interface ProviderModelItem extends ModelSlugItem {
+  readonly instanceId: ProviderInstanceId;
+}
+
+export function providerModelKey(instanceId: ProviderInstanceId, slug: string): string {
+  return `${instanceId}:${slug}`;
+}
+
+function rankByValue(values: ReadonlyArray<string>): ReadonlyMap<string, number> {
+  return new Map(Arr.map(values, (value, index) => [value, index] as const));
+}
+
+function toSet(
+  values: ReadonlySet<string> | ReadonlyArray<string> | undefined,
+): ReadonlySet<string> {
+  return values instanceof Set ? values : new Set(values ?? []);
+}
+
+function byOptionalRank<T>(rank: (item: T) => number | undefined): Order.Order<T> {
+  return Order.mapInput(Order.Number, (item: T) => rank(item) ?? Number.POSITIVE_INFINITY);
+}
+
+function byTrueFirst<T>(predicate: (item: T) => boolean): Order.Order<T> {
+  return Order.mapInput(Order.flip(Order.Boolean), predicate);
+}
+
+export function sortModelsForProviderInstance<T extends ModelSlugItem>(
+  models: ReadonlyArray<T>,
+  options?: {
+    readonly modelOrder?: ReadonlyArray<string>;
+    readonly favoriteModels?: ReadonlySet<string> | ReadonlyArray<string>;
+    readonly groupFavorites?: boolean;
+  },
+): T[] {
+  const modelOrder = options?.modelOrder ?? [];
+  const favoriteModels = toSet(options?.favoriteModels);
+  const orderBySlug = rankByValue(modelOrder);
+  const originalOrder = rankByValue(Arr.map(models, (model) => model.slug));
+  const orders: Array<Order.Order<T>> = [
+    ...(options?.groupFavorites === true
+      ? [byTrueFirst<T>((model) => favoriteModels.has(model.slug))]
+      : []),
+    byOptionalRank((model) => orderBySlug.get(model.slug)),
+    byOptionalRank((model) => originalOrder.get(model.slug)),
+  ];
+
+  return Arr.sort(models, Order.combineAll(orders));
+}
+
+export function sortProviderModelItems<T extends ProviderModelItem>(
+  items: ReadonlyArray<T>,
+  options?: {
+    readonly favoriteModelKeys?: ReadonlySet<string> | ReadonlyArray<string>;
+    readonly groupFavorites?: boolean;
+    readonly instanceOrder?: ReadonlyArray<ProviderInstanceId>;
+  },
+): T[] {
+  const favoriteModelKeys = toSet(options?.favoriteModelKeys);
+  const instanceOrder = new Map(
+    Arr.map(options?.instanceOrder ?? [], (instanceId, index) => [instanceId, index] as const),
+  );
+  const originalOrder = rankByValue(
+    Arr.map(items, (item) => providerModelKey(item.instanceId, item.slug)),
+  );
+  const orders: Array<Order.Order<T>> = [
+    ...(options?.groupFavorites === true
+      ? [
+          byTrueFirst<T>((item) =>
+            favoriteModelKeys.has(providerModelKey(item.instanceId, item.slug)),
+          ),
+        ]
+      : []),
+    byOptionalRank((item) => instanceOrder.get(item.instanceId)),
+    byOptionalRank((item) => originalOrder.get(providerModelKey(item.instanceId, item.slug))),
+  ];
+
+  return Arr.sort(items, Order.combineAll(orders));
+}
diff --git a/apps/web/src/modelPickerOpenState.ts b/apps/web/src/modelPickerOpenState.ts
new file mode 100644
index 00000000000..5a4993c16e7
--- /dev/null
+++ b/apps/web/src/modelPickerOpenState.ts
@@ -0,0 +1,17 @@
+import { create } from "zustand";
+
+const useModelPickerOpenStore = create<{
+  open: boolean;
+  setOpen: (open: boolean) => void;
+}>((set) => ({
+  open: false,
+  setOpen: (open) => set((current) => (current.open === open ? current : { open })),
+}));
+
+export function useModelPickerOpen(): boolean {
+  return useModelPickerOpenStore((store) => store.open);
+}
+
+export function setModelPickerOpen(open: boolean): void {
+  useModelPickerOpenStore.getState().setOpen(open);
+}
diff --git a/apps/web/src/modelSelection.test.ts b/apps/web/src/modelSelection.test.ts
new file mode 100644
index 00000000000..67758cac5d1
--- /dev/null
+++ b/apps/web/src/modelSelection.test.ts
@@ -0,0 +1,251 @@
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, type UnifiedSettings } from "@t3tools/contracts/settings";
+import { describe, expect, it } from "vitest";
+import { deriveProviderInstanceEntries } from "./providerInstances";
+import {
+  getAppModelOptionsForInstance,
+  resolveAppModelSelectionForInstance,
+  resolveAppModelSelectionState,
+} from "./modelSelection";
+
+function provider(input: {
+  provider?: ProviderDriverKind;
+  instanceId: string;
+  models?: ReadonlyArray<string>;
+}): ServerProvider {
+  const driver =
+    input.provider ??
+    (input.instanceId.startsWith("claude_")
+      ? ProviderDriverKind.make("claudeAgent")
+      : ProviderDriverKind.make("codex"));
+  return {
+    instanceId: ProviderInstanceId.make(input.instanceId),
+    driver,
+    enabled: true,
+    installed: true,
+    version: null,
+    status: "ready",
+    auth: { status: "authenticated" },
+    checkedAt: "2026-01-01T00:00:00.000Z",
+    models: (input.models ?? []).map((slug) => ({
+      slug,
+      name: slug,
+      isCustom: false,
+      capabilities: {},
+    })),
+    slashCommands: [],
+    skills: [],
+  };
+}
+
+function settingsWithProviderInstances(): UnifiedSettings {
+  return {
+    ...DEFAULT_UNIFIED_SETTINGS,
+    providerInstances: {
+      [ProviderInstanceId.make("claudeAgent")]: {
+        driver: ProviderDriverKind.make("claudeAgent"),
+        config: { customModels: [] },
+      },
+      [ProviderInstanceId.make("claude_openrouter")]: {
+        driver: ProviderDriverKind.make("claudeAgent"),
+        config: { customModels: ["openai/gpt-5.5"] },
+      },
+    },
+  };
+}
+
+describe("instance-scoped model selection", () => {
+  it("keeps custom models on the provider instance that declared them", () => {
+    const providers = [
+      provider({
+        instanceId: "claudeAgent",
+        models: ["claude-sonnet-4-6"],
+      }),
+      provider({
+        instanceId: "claude_openrouter",
+        models: ["claude-sonnet-4-6"],
+      }),
+    ];
+    const entries = deriveProviderInstanceEntries(providers);
+    const stock = entries.find((entry) => entry.instanceId === "claudeAgent")!;
+    const openrouter = entries.find((entry) => entry.instanceId === "claude_openrouter")!;
+
+    expect(
+      getAppModelOptionsForInstance(settingsWithProviderInstances(), stock).map(
+        (option) => option.slug,
+      ),
+    ).not.toContain("openai/gpt-5.5");
+    expect(
+      getAppModelOptionsForInstance(settingsWithProviderInstances(), openrouter).map(
+        (option) => option.slug,
+      ),
+    ).toContain("openai/gpt-5.5");
+  });
+
+  it("resolves a custom slug against the selected custom instance", () => {
+    const providers = [
+      provider({ provider: ProviderDriverKind.make("claudeAgent"), instanceId: "claudeAgent" }),
+      provider({
+        provider: ProviderDriverKind.make("claudeAgent"),
+        instanceId: "claude_openrouter",
+      }),
+    ];
+
+    expect(
+      resolveAppModelSelectionForInstance(
+        ProviderInstanceId.make("claude_openrouter"),
+        settingsWithProviderInstances(),
+        providers,
+        "openai/gpt-5.5",
+      ),
+    ).toBe("openai/gpt-5.5");
+  });
+
+  it("does not inject an unknown selected slug into the stock instance list", () => {
+    const providers = [
+      provider({
+        instanceId: "claudeAgent",
+        models: ["claude-sonnet-4-6"],
+      }),
+      provider({
+        instanceId: "claude_openrouter",
+        models: ["claude-sonnet-4-6"],
+      }),
+    ];
+    const stock = deriveProviderInstanceEntries(providers).find(
+      (entry) => entry.instanceId === "claudeAgent",
+    )!;
+
+    expect(
+      getAppModelOptionsForInstance(settingsWithProviderInstances(), stock).map(
+        (option) => option.slug,
+      ),
+    ).not.toContain("openai/gpt-5.5");
+  });
+
+  it("hides server models from the instance option list", () => {
+    const providers = [
+      provider({
+        instanceId: "claudeAgent",
+        models: ["claude-opus-4-6", "claude-sonnet-4-6"],
+      }),
+    ];
+    const settings: UnifiedSettings = {
+      ...settingsWithProviderInstances(),
+      providerModelPreferences: {
+        [ProviderInstanceId.make("claudeAgent")]: {
+          hiddenModels: ["claude-opus-4-6"],
+          modelOrder: [],
+        },
+      },
+    };
+    const stock = deriveProviderInstanceEntries(providers).find(
+      (entry) => entry.instanceId === "claudeAgent",
+    )!;
+
+    expect(getAppModelOptionsForInstance(settings, stock).map((option) => option.slug)).toEqual([
+      "claude-sonnet-4-6",
+    ]);
+  });
+
+  it("applies persisted per-instance model ordering", () => {
+    const providers = [
+      provider({
+        instanceId: "claudeAgent",
+        models: ["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"],
+      }),
+    ];
+    const settings: UnifiedSettings = {
+      ...settingsWithProviderInstances(),
+      providerModelPreferences: {
+        [ProviderInstanceId.make("claudeAgent")]: {
+          hiddenModels: [],
+          modelOrder: ["claude-haiku-4-5", "claude-opus-4-6"],
+        },
+      },
+    };
+    const stock = deriveProviderInstanceEntries(providers).find(
+      (entry) => entry.instanceId === "claudeAgent",
+    )!;
+
+    expect(getAppModelOptionsForInstance(settings, stock).map((option) => option.slug)).toEqual([
+      "claude-haiku-4-5",
+      "claude-opus-4-6",
+      "claude-sonnet-4-6",
+    ]);
+  });
+
+  it("falls back when the selected model is hidden", () => {
+    const providers = [
+      provider({
+        instanceId: "claudeAgent",
+        models: ["claude-opus-4-6", "claude-sonnet-4-6"],
+      }),
+    ];
+    const settings: UnifiedSettings = {
+      ...settingsWithProviderInstances(),
+      providerModelPreferences: {
+        [ProviderInstanceId.make("claudeAgent")]: {
+          hiddenModels: ["claude-opus-4-6"],
+          modelOrder: [],
+        },
+      },
+    };
+
+    expect(
+      resolveAppModelSelectionForInstance(
+        ProviderInstanceId.make("claudeAgent"),
+        settings,
+        providers,
+        "claude-opus-4-6",
+      ),
+    ).toBe("claude-sonnet-4-6");
+  });
+
+  it("falls back instead of resolving a custom slug against the wrong instance", () => {
+    const providers = [
+      provider({
+        instanceId: "claudeAgent",
+        models: ["claude-sonnet-4-6"],
+      }),
+      provider({
+        instanceId: "claude_openrouter",
+        models: ["claude-sonnet-4-6"],
+      }),
+    ];
+
+    expect(
+      resolveAppModelSelectionForInstance(
+        ProviderInstanceId.make("claudeAgent"),
+        settingsWithProviderInstances(),
+        providers,
+        "openai/gpt-5.5",
+      ),
+    ).toBe("claude-sonnet-4-6");
+  });
+
+  it("preserves custom provider instances in settings model selection", () => {
+    const providers = [
+      provider({
+        instanceId: "claudeAgent",
+        models: ["claude-sonnet-4-6"],
+      }),
+      provider({
+        instanceId: "claude_openrouter",
+        models: ["claude-sonnet-4-6"],
+      }),
+    ];
+    const settings: UnifiedSettings = {
+      ...settingsWithProviderInstances(),
+      textGenerationModelSelection: {
+        instanceId: ProviderInstanceId.make("claude_openrouter"),
+        model: "openai/gpt-5.5",
+      },
+    };
+
+    expect(resolveAppModelSelectionState(settings, providers)).toEqual({
+      instanceId: ProviderInstanceId.make("claude_openrouter"),
+      model: "openai/gpt-5.5",
+    });
+  });
+});
diff --git a/apps/web/src/modelSelection.ts b/apps/web/src/modelSelection.ts
index 98e2884adfe..8ba0c8fa5d9 100644
--- a/apps/web/src/modelSelection.ts
+++ b/apps/web/src/modelSelection.ts
@@ -1,58 +1,121 @@
 import {
+  DEFAULT_GIT_TEXT_GENERATION_MODEL,
   DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER,
+  defaultInstanceIdForDriver,
   type ModelSelection,
-  type ProviderKind,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerProvider,
 } from "@t3tools/contracts";
-import { normalizeModelSlug, resolveSelectableModel } from "@t3tools/shared/model";
-import { getComposerProviderState } from "./components/chat/composerProviderRegistry";
+import {
+  createModelSelection,
+  normalizeModelSlug,
+  resolveSelectableModel,
+} from "@t3tools/shared/model";
+import { getComposerProviderState } from "./components/chat/composerProviderState";
 import { UnifiedSettings } from "@t3tools/contracts/settings";
 import {
   getDefaultServerModel,
   getProviderModels,
   resolveSelectableProvider,
 } from "./providerModels";
+import { ModelEsque } from "./components/chat/providerIconUtils";
+import { type ProviderInstanceEntry, deriveProviderInstanceEntries } from "./providerInstances";
+import { sortModelsForProviderInstance } from "./modelOrdering";
 
 const MAX_CUSTOM_MODEL_COUNT = 32;
 export const MAX_CUSTOM_MODEL_LENGTH = 256;
+const DEFAULT_TEXT_GENERATION_INSTANCE_ID = ProviderInstanceId.make("codex");
 
-export type ProviderCustomModelConfig = {
-  provider: ProviderKind;
-  title: string;
-  description: string;
-  placeholder: string;
-  example: string;
-};
+/**
+ * Resolve the custom-model list for a given instance, preferring the
+ * instance's own `providerInstances[id].config.customModels` blob when
+ * present and falling back to the legacy per-kind
+ * `settings.providers[kind].customModels` bucket for default instances only.
+ *
+ * The Settings UI promotes the legacy bucket into an explicit
+ * `providerInstances[defaultId]` entry on every edit (the "migrate on
+ * first write" scheme documented in
+ * `ProviderInstanceRegistryHydration`), so this helper exists primarily
+ * so readers pick up that promotion immediately — and so first-time
+ * viewers on pre-migration settings still see their legacy list on
+ * default slots. Custom instances intentionally do not read the legacy
+ * per-driver bucket; otherwise one custom model added to `claude_openrouter`
+ * can appear on the stock `claudeAgent` instance.
+ */
+function readInstanceCustomModels(
+  settings: UnifiedSettings,
+  instanceId: ProviderInstanceId,
+  driverKind: ProviderDriverKind,
+): ReadonlyArray<string> {
+  const instance = settings.providerInstances?.[instanceId];
+  const config = instance?.config;
+  if (config !== null && typeof config === "object") {
+    const value = (config as Record<string, unknown>).customModels;
+    if (Array.isArray(value)) {
+      return value.filter((entry): entry is string => typeof entry === "string");
+    }
+  }
+  const defaultInstanceId = defaultInstanceIdForDriver(driverKind);
+  if (instanceId !== defaultInstanceId) {
+    return [];
+  }
+  const legacyProviders = settings.providers as Record<
+    string,
+    { readonly customModels: ReadonlyArray<string> } | undefined
+  >;
+  return legacyProviders[driverKind]?.customModels ?? [];
+}
 
 export interface AppModelOption {
   slug: string;
   name: string;
+  shortName?: string;
+  subProvider?: string;
   isCustom: boolean;
 }
 
-const PROVIDER_CUSTOM_MODEL_CONFIG: Record<ProviderKind, ProviderCustomModelConfig> = {
-  codex: {
-    provider: "codex",
-    title: "Codex",
-    description: "Save additional Codex model slugs for the picker and `/model` command.",
-    placeholder: "your-codex-model-slug",
-    example: "gpt-6.7-codex-ultra-preview",
-  },
-  claudeAgent: {
-    provider: "claudeAgent",
-    title: "Claude",
-    description: "Save additional Claude model slugs for the picker and `/model` command.",
-    placeholder: "your-claude-model-slug",
-    example: "claude-sonnet-5-0",
-  },
-};
+function toAppModelOption(model: ServerProvider["models"][number]): AppModelOption {
+  const option: AppModelOption = {
+    slug: model.slug,
+    name: model.name,
+    isCustom: model.isCustom,
+  };
+  if (model.shortName) option.shortName = model.shortName;
+  if (model.subProvider) option.subProvider = model.subProvider;
+  return option;
+}
+
+function readInstanceModelPreferences(
+  settings: UnifiedSettings,
+  instanceId: ProviderInstanceId,
+): { readonly hiddenModels: ReadonlyArray<string>; readonly modelOrder: ReadonlyArray<string> } {
+  return (
+    settings.providerModelPreferences?.[instanceId] ?? {
+      hiddenModels: [],
+      modelOrder: [],
+    }
+  );
+}
 
-export const MODEL_PROVIDER_SETTINGS = Object.values(PROVIDER_CUSTOM_MODEL_CONFIG);
+function applyInstanceModelPreferences(
+  options: ReadonlyArray<AppModelOption>,
+  preferences: {
+    readonly hiddenModels: ReadonlyArray<string>;
+    readonly modelOrder: ReadonlyArray<string>;
+  },
+): AppModelOption[] {
+  const hiddenModels = new Set(preferences.hiddenModels);
+  return sortModelsForProviderInstance(
+    options.filter((option) => option.isCustom || !hiddenModels.has(option.slug)),
+    { modelOrder: preferences.modelOrder },
+  );
+}
 
 export function normalizeCustomModelSlugs(
   models: Iterable<string | null | undefined>,
   builtInModelSlugs: ReadonlySet<string>,
-  provider: ProviderKind = "codex",
+  provider: ProviderDriverKind = ProviderDriverKind.make("codex"),
 ): string[] {
   const normalizedModels: string[] = [];
   const seen = new Set<string>();
@@ -81,25 +144,23 @@ export function normalizeCustomModelSlugs(
 export function getAppModelOptions(
   settings: UnifiedSettings,
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind,
-  selectedModel?: string | null,
+  provider: ProviderDriverKind,
+  _selectedModel?: string | null,
 ): AppModelOption[] {
-  const options: AppModelOption[] = getProviderModels(providers, provider).map(
-    ({ slug, name, isCustom }) => ({
-      slug,
-      name,
-      isCustom,
-    }),
-  );
+  const options: AppModelOption[] = getProviderModels(providers, provider).map(toAppModelOption);
   const seen = new Set(options.map((option) => option.slug));
-  const trimmedSelectedModel = selectedModel?.trim().toLowerCase();
   const builtInModelSlugs = new Set(
     getProviderModels(providers, provider)
       .filter((model) => !model.isCustom)
       .map((model) => model.slug),
   );
 
-  const customModels = settings.providers[provider].customModels;
+  // Read from the default instance's config first (that's where edits
+  // now land), falling back to the legacy per-kind bucket so unmigrated
+  // settings and the initial render before the first write both still
+  // see the user's authored custom models.
+  const defaultInstanceId = defaultInstanceIdForDriver(provider);
+  const customModels = readInstanceCustomModels(settings, defaultInstanceId, provider);
   for (const slug of normalizeCustomModelSlugs(customModels, builtInModelSlugs, provider)) {
     if (seen.has(slug)) {
       continue;
@@ -113,27 +174,52 @@ export function getAppModelOptions(
     });
   }
 
-  const normalizedSelectedModel = normalizeModelSlug(selectedModel, provider);
-  const selectedModelMatchesExistingName =
-    typeof trimmedSelectedModel === "string" &&
-    options.some((option) => option.name.toLowerCase() === trimmedSelectedModel);
-  if (
-    normalizedSelectedModel &&
-    !seen.has(normalizedSelectedModel) &&
-    !selectedModelMatchesExistingName
-  ) {
-    options.push({
-      slug: normalizedSelectedModel,
-      name: normalizedSelectedModel,
-      isCustom: true,
-    });
+  return applyInstanceModelPreferences(
+    options,
+    readInstanceModelPreferences(settings, defaultInstanceId),
+  );
+}
+
+/**
+ * Instance-scoped variant of {@link getAppModelOptions}. Built-in models
+ * come from the instance's own `entry.models` snapshot (rather than the
+ * first-matching-kind fallback in `getProviderModels`), so each custom
+ * instance gets the precise model list its driver reported. Custom model
+ * slugs come from the instance's own `providerInstances[id].config.customModels`
+ * when present, falling back to the legacy per-kind
+ * `settings.providers[driverKind].customModels` bucket for default
+ * instances only. This keeps two instances of the same kind from leaking
+ * custom slugs into each other.
+ */
+export function getAppModelOptionsForInstance(
+  settings: UnifiedSettings,
+  entry: ProviderInstanceEntry,
+): AppModelOption[] {
+  const options: AppModelOption[] = entry.models.map(toAppModelOption);
+  const seen = new Set(options.map((option) => option.slug));
+  const builtInModelSlugs = new Set(
+    entry.models.filter((model) => !model.isCustom).map((model) => model.slug),
+  );
+
+  const customModels = readInstanceCustomModels(settings, entry.instanceId, entry.driverKind);
+  const normalizer = entry.driverKind;
+  for (const slug of normalizeCustomModelSlugs(customModels, builtInModelSlugs, normalizer)) {
+    if (seen.has(slug)) {
+      continue;
+    }
+
+    seen.add(slug);
+    options.push({ slug, name: slug, isCustom: true });
   }
 
-  return options;
+  return applyInstanceModelPreferences(
+    options,
+    readInstanceModelPreferences(settings, entry.instanceId),
+  );
 }
 
 export function resolveAppModelSelection(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   settings: UnifiedSettings,
   providers: ReadonlyArray<ServerProvider>,
   selectedModel: string | null | undefined,
@@ -146,26 +232,41 @@ export function resolveAppModelSelection(
   );
 }
 
-export function getCustomModelOptionsByProvider(
+export function resolveAppModelSelectionForInstance(
+  instanceId: ProviderInstanceId,
   settings: UnifiedSettings,
   providers: ReadonlyArray<ServerProvider>,
-  selectedProvider?: ProviderKind | null,
-  selectedModel?: string | null,
-): Record<ProviderKind, ReadonlyArray<{ slug: string; name: string }>> {
-  return {
-    codex: getAppModelOptions(
-      settings,
-      providers,
-      "codex",
-      selectedProvider === "codex" ? selectedModel : undefined,
-    ),
-    claudeAgent: getAppModelOptions(
-      settings,
-      providers,
-      "claudeAgent",
-      selectedProvider === "claudeAgent" ? selectedModel : undefined,
-    ),
-  };
+  selectedModel: string | null | undefined,
+): string | null {
+  const entry = deriveProviderInstanceEntries(providers).find(
+    (candidate) => candidate.instanceId === instanceId,
+  );
+  if (!entry) return null;
+  const options = getAppModelOptionsForInstance(settings, entry);
+  return (
+    resolveSelectableModel(entry.driverKind, selectedModel, options) ??
+    options[0]?.slug ??
+    entry.models[0]?.slug ??
+    null
+  );
+}
+
+/**
+ * Instance-keyed model options map. Each configured instance gets its own
+ * option list so the model picker can show the same driver's built-in and
+ * custom instances side by side without collapsing them.
+ */
+export function getCustomModelOptionsByInstance(
+  settings: UnifiedSettings,
+  providers: ReadonlyArray<ServerProvider>,
+  _selectedInstanceId?: ProviderInstanceId | null,
+  _selectedModel?: string | null,
+): ReadonlyMap<ProviderInstanceId, ReadonlyArray<ModelEsque>> {
+  const out = new Map<ProviderInstanceId, ReadonlyArray<ModelEsque>>();
+  for (const entry of deriveProviderInstanceEntries(providers)) {
+    out.set(entry.instanceId, getAppModelOptionsForInstance(settings, entry));
+  }
+  return out;
 }
 
 export function resolveAppModelSelectionState(
@@ -173,28 +274,52 @@ export function resolveAppModelSelectionState(
   providers: ReadonlyArray<ServerProvider>,
 ): ModelSelection {
   const selection = settings.textGenerationModelSelection ?? {
-    provider: "codex" as const,
-    model: DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER.codex,
+    instanceId: DEFAULT_TEXT_GENERATION_INSTANCE_ID,
+    model: DEFAULT_GIT_TEXT_GENERATION_MODEL,
   };
-  const provider = resolveSelectableProvider(providers, selection.provider);
+  const entries = deriveProviderInstanceEntries(providers);
+  const selectedEntry = entries.find(
+    (entry) => entry.instanceId === selection.instanceId && entry.enabled && entry.isAvailable,
+  );
+  const entry =
+    selectedEntry ?? entries.find((candidate) => candidate.enabled && candidate.isAvailable);
+  if (entry) {
+    // When the instance changed due to fallback (e.g. selected instance was disabled),
+    // don't carry over the old instance's model — use the fallback instance's default.
+    const selectedModel = selectedEntry ? selection.model : null;
+    const model =
+      resolveAppModelSelectionForInstance(entry.instanceId, settings, providers, selectedModel) ??
+      entry.models[0]?.slug ??
+      DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER[entry.driverKind];
+    if (!model) {
+      return createModelSelection(entry.instanceId, "", []);
+    }
+    const provider = entry.driverKind;
+    const { modelOptionsForDispatch } = getComposerProviderState({
+      provider,
+      model,
+      models: entry.models,
+      prompt: "",
+      modelOptions: selectedEntry ? selection.options : undefined,
+    });
+
+    return createModelSelection(entry.instanceId, model, modelOptionsForDispatch);
+  }
+
+  const provider = resolveSelectableProvider(providers, null);
+  const keptSelectedProvider = false;
 
   // When the provider changed due to fallback (e.g. selected provider was disabled),
   // don't carry over the old provider's model — use the fallback provider's default.
-  const selectedModel = provider === selection.provider ? selection.model : null;
+  const selectedModel = keptSelectedProvider ? selection.model : null;
   const model = resolveAppModelSelection(provider, settings, providers, selectedModel);
   const { modelOptionsForDispatch } = getComposerProviderState({
     provider,
     model,
     models: getProviderModels(providers, provider),
     prompt: "",
-    modelOptions: {
-      [provider]: provider === selection.provider ? selection.options : undefined,
-    },
+    modelOptions: keptSelectedProvider ? selection.options : undefined,
   });
 
-  return {
-    provider,
-    model,
-    ...(modelOptionsForDispatch ? { options: modelOptionsForDispatch } : {}),
-  };
+  return createModelSelection(defaultInstanceIdForDriver(provider), model, modelOptionsForDispatch);
 }
diff --git a/apps/web/src/observability/clientTracing.ts b/apps/web/src/observability/clientTracing.ts
index f9eae4b5a19..c0d104ac517 100644
--- a/apps/web/src/observability/clientTracing.ts
+++ b/apps/web/src/observability/clientTracing.ts
@@ -1,4 +1,8 @@
-import { Exit, Layer, ManagedRuntime, Scope, Tracer } from "effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Scope from "effect/Scope";
+import * as Tracer from "effect/Tracer";
 import { FetchHttpClient, HttpClient } from "effect/unstable/http";
 import { OtlpSerialization, OtlpTracer } from "effect/unstable/observability";
 
diff --git a/apps/web/src/orchestrationEventEffects.test.ts b/apps/web/src/orchestrationEventEffects.test.ts
index d35dc9e2602..a20e64e2539 100644
--- a/apps/web/src/orchestrationEventEffects.test.ts
+++ b/apps/web/src/orchestrationEventEffects.test.ts
@@ -3,6 +3,7 @@ import {
   EventId,
   MessageId,
   ProjectId,
+  ProviderInstanceId,
   ThreadId,
   TurnId,
   type OrchestrationEvent,
@@ -49,7 +50,7 @@ describe("deriveOrchestrationBatchEffects", () => {
         threadId: createdThreadId,
         projectId: ProjectId.make("project-1"),
         title: "Created thread",
-        modelSelection: { provider: "codex", model: "gpt-5-codex" },
+        modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5-codex" },
         runtimeMode: "full-access",
         interactionMode: "default",
         branch: null,
@@ -86,7 +87,7 @@ describe("deriveOrchestrationBatchEffects", () => {
         threadId,
         projectId: ProjectId.make("project-1"),
         title: "Recreated thread",
-        modelSelection: { provider: "codex", model: "gpt-5-codex" },
+        modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5-codex" },
         runtimeMode: "full-access",
         interactionMode: "default",
         branch: null,
diff --git a/apps/web/src/projectScripts.ts b/apps/web/src/projectScripts.ts
index 1cb3a6c7582..1c02b4e8104 100644
--- a/apps/web/src/projectScripts.ts
+++ b/apps/web/src/projectScripts.ts
@@ -4,7 +4,8 @@ import {
   type KeybindingCommand,
   type ProjectScript,
 } from "@t3tools/contracts";
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
+const isScriptRunCommand = Schema.is(SCRIPT_RUN_COMMAND_PATTERN);
 
 function normalizeScriptId(value: string): string {
   const cleaned = value
@@ -26,7 +27,7 @@ export const commandForProjectScript = (scriptId: string): KeybindingCommand =>
 
 export function projectScriptIdFromCommand(command: string): string | null {
   const trimmed = command.trim();
-  if (!Schema.is(SCRIPT_RUN_COMMAND_PATTERN)(trimmed)) {
+  if (!isScriptRunCommand(trimmed)) {
     return null;
   }
   const [prefix, , suffix] = SCRIPT_RUN_COMMAND_PATTERN.parts;
diff --git a/apps/web/src/providerInstances.test.ts b/apps/web/src/providerInstances.test.ts
new file mode 100644
index 00000000000..7104f365ebf
--- /dev/null
+++ b/apps/web/src/providerInstances.test.ts
@@ -0,0 +1,132 @@
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+import {
+  deriveProviderInstanceEntries,
+  resolveSelectableProviderInstance,
+  resolveProviderDriverKindForInstanceSelection,
+} from "./providerInstances";
+
+function provider(input: {
+  provider: ProviderDriverKind;
+  instanceId: string;
+  enabled?: boolean;
+  availability?: ServerProvider["availability"];
+  displayName?: string;
+}): ServerProvider {
+  return {
+    instanceId: ProviderInstanceId.make(input.instanceId),
+    driver: input.provider,
+    ...(input.displayName ? { displayName: input.displayName } : {}),
+    enabled: input.enabled ?? true,
+    installed: true,
+    version: null,
+    status: "ready",
+    ...(input.availability ? { availability: input.availability } : {}),
+    auth: { status: "authenticated" },
+    checkedAt: "2026-01-01T00:00:00.000Z",
+    models: [],
+    slashCommands: [],
+    skills: [],
+  };
+}
+
+describe("deriveProviderInstanceEntries", () => {
+  it("uses explicit instance id and driver kind from the snapshot", () => {
+    const snapshot = provider({
+      provider: ProviderDriverKind.make("codex"),
+      instanceId: "codex_personal",
+    });
+    const [entry] = deriveProviderInstanceEntries([snapshot]);
+
+    expect(entry?.instanceId).toBe("codex_personal");
+    expect(entry?.driverKind).toBe("codex");
+    expect(entry?.isDefault).toBe(false);
+  });
+});
+
+describe("resolveSelectableProviderInstance", () => {
+  it("returns the requested instance when it is enabled and available", () => {
+    const requested = ProviderInstanceId.make("claude_work");
+    const providers = [
+      provider({ provider: ProviderDriverKind.make("codex"), instanceId: "codex" }),
+      provider({ provider: ProviderDriverKind.make("claudeAgent"), instanceId: requested }),
+    ];
+
+    expect(resolveSelectableProviderInstance(providers, requested)).toBe(requested);
+  });
+
+  it("falls back to the first enabled and available instance", () => {
+    const disabled = ProviderInstanceId.make("codex");
+    const fallback = ProviderInstanceId.make("claudeAgent");
+    const providers = [
+      provider({
+        provider: ProviderDriverKind.make("codex"),
+        instanceId: disabled,
+        enabled: false,
+      }),
+      provider({ provider: ProviderDriverKind.make("claudeAgent"), instanceId: fallback }),
+    ];
+
+    expect(resolveSelectableProviderInstance(providers, disabled)).toBe(fallback);
+  });
+
+  it("does not return disabled, unavailable, or unknown instances when none are sendable", () => {
+    const disabled = ProviderInstanceId.make("codex");
+    const unavailable = ProviderInstanceId.make("claudeAgent");
+    const unknown = ProviderInstanceId.make("removed_instance");
+    const providers = [
+      provider({
+        provider: ProviderDriverKind.make("codex"),
+        instanceId: disabled,
+        enabled: false,
+      }),
+      provider({
+        provider: ProviderDriverKind.make("claudeAgent"),
+        instanceId: unavailable,
+        availability: "unavailable",
+      }),
+    ];
+
+    expect(resolveSelectableProviderInstance(providers, disabled)).toBeUndefined();
+    expect(resolveSelectableProviderInstance(providers, unavailable)).toBeUndefined();
+    expect(resolveSelectableProviderInstance(providers, unknown)).toBeUndefined();
+  });
+});
+
+describe("resolveProviderDriverKindForInstanceSelection", () => {
+  it("maps custom provider instance ids back to their driver kind", () => {
+    const providers = [
+      provider({ provider: ProviderDriverKind.make("codex"), instanceId: "codex" }),
+      provider({
+        provider: ProviderDriverKind.make("claudeAgent"),
+        instanceId: "claude_openrouter",
+        displayName: "Claude OpenRouter",
+      }),
+    ];
+    const entries = deriveProviderInstanceEntries(providers);
+
+    expect(
+      resolveProviderDriverKindForInstanceSelection(
+        entries,
+        providers,
+        ProviderInstanceId.make("claude_openrouter"),
+      ),
+    ).toBe("claudeAgent");
+  });
+
+  it("does not guess a provider kind when the instance selection is unknown", () => {
+    const providers = [
+      provider({ provider: ProviderDriverKind.make("codex"), instanceId: "codex", enabled: false }),
+      provider({ provider: ProviderDriverKind.make("claudeAgent"), instanceId: "claudeAgent" }),
+    ];
+    const entries = deriveProviderInstanceEntries(providers);
+
+    expect(
+      resolveProviderDriverKindForInstanceSelection(
+        entries,
+        providers,
+        ProviderInstanceId.make("removed_instance"),
+      ),
+    ).toBeUndefined();
+  });
+});
diff --git a/apps/web/src/providerInstances.ts b/apps/web/src/providerInstances.ts
new file mode 100644
index 00000000000..6ff0bd1ab98
--- /dev/null
+++ b/apps/web/src/providerInstances.ts
@@ -0,0 +1,248 @@
+/**
+ * Instance-aware view over the wire `ServerProvider[]`.
+ *
+ * The wire carries one `ServerProvider` per *configured instance* — the
+ * default built-in codex instance, a user-authored `codex_personal`, an
+ * unavailable shadow for a fork driver, etc. Legacy UI code collapsed these
+ * into a single bucket per built-in driver via `.find((p) => p.driver === kind)`,
+ * which silently dropped every custom instance after the first. This module
+ * replaces that pattern with `ProviderInstanceEntry[]`, keyed on
+ * `ProviderInstanceId`, so the model picker, settings list, and composer
+ * can treat built-in and custom instances uniformly.
+ *
+ * @module providerInstances
+ */
+import {
+  defaultInstanceIdForDriver,
+  PROVIDER_DISPLAY_NAMES,
+  type ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProvider,
+  type ServerProviderModel,
+  type ServerProviderState,
+} from "@t3tools/contracts";
+
+import { formatProviderDriverKindLabel } from "./providerModels";
+
+/**
+ * UI-facing projection of one configured provider instance. Carries the
+ * snapshot verbatim for callers that need server-side fields we don't
+ * hoist here, plus the precomputed `instanceId` / `driverKind` /
+ * `displayName` used by every picker and settings view.
+ */
+export interface ProviderInstanceEntry {
+  readonly instanceId: ProviderInstanceId;
+  readonly driverKind: ProviderDriverKind;
+  readonly displayName: string;
+  readonly accentColor?: string | undefined;
+  readonly continuationGroupKey?: string | undefined;
+  readonly enabled: boolean;
+  readonly installed: boolean;
+  readonly status: ServerProviderState;
+  /**
+   * True when this entry is the default instance for its driver kind —
+   * i.e. its instance id equals `defaultInstanceIdForDriver(driverKind)`.
+   * The settings panel and picker sort defaults before customs.
+   */
+  readonly isDefault: boolean;
+  /** True when `availability === "unavailable"` is absent or "available". */
+  readonly isAvailable: boolean;
+  readonly snapshot: ServerProvider;
+  readonly models: ReadonlyArray<ServerProviderModel>;
+}
+
+/**
+ * Turn an instance id slug into a human-readable label. Splits on `_` / `-`
+ * and camelCase boundaries and title-cases each token, so `codex_personal`
+ * becomes "Codex Personal" and `myCustomInstance` becomes "My Custom
+ * Instance".
+ *
+ * This is a fallback used only when the wire snapshot's `displayName`
+ * doesn't disambiguate a non-default instance from the default one of the
+ * same driver (today every built-in driver hard-codes a single presentation
+ * label per kind, so two instances of the same kind arrive with identical
+ * display names). When a server/driver later plumbs the user's configured
+ * `ProviderInstanceConfig.displayName` through to the snapshot, that value
+ * will take precedence over this fallback.
+ */
+function humanizeInstanceId(instanceId: ProviderInstanceId): string {
+  return instanceId
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .split(" ")
+    .filter((token) => token.length > 0)
+    .map((token) => token.charAt(0).toUpperCase() + token.slice(1))
+    .join(" ");
+}
+
+function driverKindLabel(driverKind: ProviderDriverKind): string {
+  return PROVIDER_DISPLAY_NAMES[driverKind] ?? formatProviderDriverKindLabel(driverKind);
+}
+
+export function normalizeProviderAccentColor(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  return /^#[0-9a-fA-F]{6}$/u.test(trimmed) ? trimmed : undefined;
+}
+
+/**
+ * Resolve an entry's displayName with a tiered priority:
+ *
+ *   1. A snapshot `displayName` that differs from the driver-kind label —
+ *      the server has explicitly named this instance, trust it.
+ *   2. For non-default instances, a humanized `instanceId` — the server
+ *      fell back to the driver-level presentation constant (which is the
+ *      same for every instance of that kind), so we differentiate at the
+ *      UI layer by slug. This is what keeps "Codex" + "Codex Personal"
+ *      distinguishable in tooltips and list labels today.
+ *   3. The snapshot's `displayName` (if any) — default instance, trust
+ *      whatever label the driver stamped.
+ *   4. `driverKindLabel(driverKind)` — nothing else on hand, so use the
+ *      canonical brand label from contracts (falling back to a generic
+ *      title-case of the kind slug).
+ */
+function resolveInstanceDisplayName(
+  snapshot: ServerProvider,
+  instanceId: ProviderInstanceId,
+  driverKind: ProviderDriverKind,
+  isDefault: boolean,
+): string {
+  const trimmedSnapshotName = snapshot.displayName?.trim();
+  const kindLabel = driverKindLabel(driverKind);
+  if (trimmedSnapshotName && trimmedSnapshotName !== kindLabel) {
+    return trimmedSnapshotName;
+  }
+  if (!isDefault) {
+    const humanized = humanizeInstanceId(instanceId);
+    if (humanized.length > 0) return humanized;
+  }
+  return trimmedSnapshotName || kindLabel;
+}
+
+/**
+ * Project the wire `ServerProvider[]` into instance entries, one per
+ * configured instance. Preserves the server's ordering (which sources
+ * from `deriveProviderInstanceConfigMap` — explicit `providerInstances.*`
+ * first, synthesized defaults after) so callers that want "default first"
+ * should sort with `sortProviderInstanceEntries` below.
+ */
+export function deriveProviderInstanceEntries(
+  providers: ReadonlyArray<ServerProvider>,
+): ReadonlyArray<ProviderInstanceEntry> {
+  return providers.map((snapshot) => {
+    const instanceId = snapshot.instanceId;
+    const driverKind = snapshot.driver;
+    const defaultId = defaultInstanceIdForDriver(driverKind);
+    const isDefault = instanceId === defaultId;
+    const displayName = resolveInstanceDisplayName(snapshot, instanceId, driverKind, isDefault);
+    return {
+      instanceId,
+      driverKind,
+      displayName,
+      accentColor: normalizeProviderAccentColor(snapshot.accentColor),
+      continuationGroupKey: snapshot.continuation?.groupKey,
+      enabled: snapshot.enabled,
+      installed: snapshot.installed,
+      status: snapshot.status,
+      isDefault,
+      isAvailable: snapshot.availability !== "unavailable",
+      snapshot,
+      models: snapshot.models,
+    } satisfies ProviderInstanceEntry;
+  });
+}
+
+/**
+ * Sort instance entries so the default instance of each driver kind appears
+ * before any custom instances of the same kind. Within a kind, custom
+ * instances keep their settings-author order (which is how the server
+ * emits them). Stable across kinds: entries retain the server's
+ * cross-driver ordering.
+ */
+export function sortProviderInstanceEntries(
+  entries: ReadonlyArray<ProviderInstanceEntry>,
+): ReadonlyArray<ProviderInstanceEntry> {
+  // Group by driver kind preserving first-appearance order, then emit
+  // default-first within each kind. Using a Map keeps the "first-seen"
+  // semantics for kinds whose default instance is absent (unusual but
+  // possible during the migration).
+  const byKind = new Map<ProviderDriverKind, ProviderInstanceEntry[]>();
+  for (const entry of entries) {
+    const bucket = byKind.get(entry.driverKind);
+    if (bucket) {
+      bucket.push(entry);
+    } else {
+      byKind.set(entry.driverKind, [entry]);
+    }
+  }
+  const sorted: ProviderInstanceEntry[] = [];
+  for (const bucket of byKind.values()) {
+    const defaults = bucket.filter((entry) => entry.isDefault);
+    const customs = bucket.filter((entry) => !entry.isDefault);
+    sorted.push(...defaults, ...customs);
+  }
+  return sorted;
+}
+
+/**
+ * Look up a single instance entry by exact `instanceId`. Missing snapshots
+ * are not inferred from driver kind in UI routing code.
+ */
+export function getProviderInstanceEntry(
+  providers: ReadonlyArray<ServerProvider>,
+  instanceId: ProviderInstanceId,
+): ProviderInstanceEntry | undefined {
+  return deriveProviderInstanceEntries(providers).find((entry) => entry.instanceId === instanceId);
+}
+
+/**
+ * Model list for a specific instance. Returns `[]` when the instance isn't
+ * present so callers don't have to thread optionality through render code.
+ */
+export function getProviderInstanceModels(
+  providers: ReadonlyArray<ServerProvider>,
+  instanceId: ProviderInstanceId,
+): ReadonlyArray<ServerProviderModel> {
+  return getProviderInstanceEntry(providers, instanceId)?.models ?? [];
+}
+
+/**
+ * Resolve the routing key for a selection that may reference an instance
+ * id that no longer exists (e.g. a persisted thread selection after the
+ * user deleted the custom instance). Returns the first enabled instance
+ * as a fallback so downstream code can still send a turn.
+ */
+export function resolveSelectableProviderInstance(
+  providers: ReadonlyArray<ServerProvider>,
+  instanceId: ProviderInstanceId | undefined,
+): ProviderInstanceId | undefined {
+  if (instanceId === undefined) {
+    return deriveProviderInstanceEntries(providers).find(
+      (entry) => entry.enabled && entry.isAvailable,
+    )?.instanceId;
+  }
+  const entries = deriveProviderInstanceEntries(providers);
+  const requested = entries.find((entry) => entry.instanceId === instanceId);
+  if (requested && requested.enabled && requested.isAvailable) {
+    return instanceId;
+  }
+  return entries.find((entry) => entry.enabled && entry.isAvailable)?.instanceId;
+}
+
+/**
+ * Resolve an open model-selection routing key back to a driver kind.
+ * Custom instance ids such as `claude_openrouter` are not themselves
+ * driver-kind slugs, but the composer still needs the owning driver kind
+ * for capabilities, options, icons, and turn dispatch metadata.
+ */
+export function resolveProviderDriverKindForInstanceSelection(
+  entries: ReadonlyArray<ProviderInstanceEntry>,
+  providers: ReadonlyArray<ServerProvider>,
+  selection: ProviderInstanceId | ProviderDriverKind | null | undefined,
+): ProviderDriverKind | undefined {
+  const matchedEntry = entries.find((entry) => entry.instanceId === selection);
+  if (matchedEntry) {
+    return matchedEntry.driverKind;
+  }
+  return undefined;
+}
diff --git a/apps/web/src/providerModels.ts b/apps/web/src/providerModels.ts
index 298c794de33..aa9afcf31e1 100644
--- a/apps/web/src/providerModels.ts
+++ b/apps/web/src/providerModels.ts
@@ -1,56 +1,86 @@
 import {
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
   type ModelCapabilities,
-  type ProviderKind,
+  type ProviderInstanceId,
   type ServerProvider,
   type ServerProviderModel,
 } from "@t3tools/contracts";
-import { normalizeModelSlug } from "@t3tools/shared/model";
+import { createModelCapabilities, normalizeModelSlug } from "@t3tools/shared/model";
 
-const EMPTY_CAPABILITIES: ModelCapabilities = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-};
+const EMPTY_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
+
+export function formatProviderDriverKindLabel(provider: ProviderDriverKind): string {
+  return provider
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
 
 export function getProviderModels(
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 ): ReadonlyArray<ServerProviderModel> {
-  return providers.find((candidate) => candidate.provider === provider)?.models ?? [];
+  return getProviderSnapshot(providers, provider)?.models ?? [];
 }
 
 export function getProviderSnapshot(
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 ): ServerProvider | undefined {
-  return providers.find((candidate) => candidate.provider === provider);
+  const defaultInstanceId = defaultInstanceIdForDriver(provider);
+  return providers.find((candidate) => candidate.instanceId === defaultInstanceId);
+}
+
+export function getProviderDisplayName(
+  providers: ReadonlyArray<ServerProvider>,
+  provider: ProviderDriverKind,
+): string {
+  const snapshot = getProviderSnapshot(providers, provider);
+  return snapshot?.displayName?.trim() || formatProviderDriverKindLabel(provider);
+}
+
+export function getProviderInteractionModeToggle(
+  providers: ReadonlyArray<ServerProvider>,
+  provider: ProviderDriverKind,
+): boolean {
+  return getProviderSnapshot(providers, provider)?.showInteractionModeToggle ?? true;
 }
 
 export function isProviderEnabled(
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 ): boolean {
-  return getProviderSnapshot(providers, provider)?.enabled ?? true;
+  if (providers.length === 0) {
+    return true;
+  }
+  return getProviderSnapshot(providers, provider)?.enabled ?? false;
 }
 
+// Resolve an instance selection to the correlated live driver. If the
+// instance is absent, fall back to a live enabled provider instead of
+// inferring a driver from the missing instance id.
 export function resolveSelectableProvider(
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind | null | undefined,
-): ProviderKind {
-  const requested = provider ?? "codex";
-  if (isProviderEnabled(providers, requested)) {
-    return requested;
+  provider: ProviderDriverKind | ProviderInstanceId | null | undefined,
+): ProviderDriverKind {
+  const requestedEntry = providers.find((candidate) => candidate.instanceId === provider);
+  if (requestedEntry?.enabled) {
+    return requestedEntry.driver;
   }
-  return providers.find((candidate) => candidate.enabled)?.provider ?? requested;
+  return providers.find((candidate) => candidate.enabled)?.driver ?? DEFAULT_DRIVER_KIND;
 }
 
 export function getProviderModelCapabilities(
   models: ReadonlyArray<ServerProviderModel>,
   model: string | null | undefined,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 ): ModelCapabilities {
   const slug = normalizeModelSlug(model, provider);
   return models.find((candidate) => candidate.slug === slug)?.capabilities ?? EMPTY_CAPABILITIES;
@@ -58,12 +88,13 @@ export function getProviderModelCapabilities(
 
 export function getDefaultServerModel(
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 ): string {
   const models = getProviderModels(providers, provider);
   return (
     models.find((model) => !model.isCustom)?.slug ??
     models[0]?.slug ??
-    DEFAULT_MODEL_BY_PROVIDER[provider]
+    DEFAULT_MODEL_BY_PROVIDER[provider] ??
+    DEFAULT_MODEL
   );
 }
diff --git a/apps/web/src/providerUpdateDismissal.test.ts b/apps/web/src/providerUpdateDismissal.test.ts
new file mode 100644
index 00000000000..bb528b45142
--- /dev/null
+++ b/apps/web/src/providerUpdateDismissal.test.ts
@@ -0,0 +1,23 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { removeLocalStorageItem } from "./hooks/useLocalStorage";
+import {
+  dismissProviderUpdateNotification,
+  isProviderUpdateNotificationDismissed,
+  PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+} from "./providerUpdateDismissal";
+
+describe("providerUpdateDismissal", () => {
+  beforeEach(() => {
+    removeLocalStorageItem(PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY);
+  });
+
+  it("persists provider update dismissals by notification key", () => {
+    expect(isProviderUpdateNotificationDismissed("opencode:1.14.33")).toBe(false);
+
+    dismissProviderUpdateNotification("opencode:1.14.33");
+
+    expect(isProviderUpdateNotificationDismissed("opencode:1.14.33")).toBe(true);
+    expect(isProviderUpdateNotificationDismissed("opencode:1.14.34")).toBe(false);
+  });
+});
diff --git a/apps/web/src/providerUpdateDismissal.ts b/apps/web/src/providerUpdateDismissal.ts
new file mode 100644
index 00000000000..7cce819ccf9
--- /dev/null
+++ b/apps/web/src/providerUpdateDismissal.ts
@@ -0,0 +1,92 @@
+import { useCallback, useMemo } from "react";
+import * as Schema from "effect/Schema";
+
+import { getLocalStorageItem, setLocalStorageItem, useLocalStorage } from "./hooks/useLocalStorage";
+
+export const PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY = "t3code:provider-update-dismissals:v1";
+
+const ProviderUpdateDismissalsSchema = Schema.Struct({
+  keys: Schema.Array(Schema.String),
+});
+
+type ProviderUpdateDismissals = typeof ProviderUpdateDismissalsSchema.Type;
+
+function readProviderUpdateDismissals(): ProviderUpdateDismissals {
+  try {
+    return (
+      getLocalStorageItem(
+        PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+        ProviderUpdateDismissalsSchema,
+      ) ?? {
+        keys: [],
+      }
+    );
+  } catch {
+    return { keys: [] };
+  }
+}
+
+function writeProviderUpdateDismissals(document: ProviderUpdateDismissals): void {
+  try {
+    setLocalStorageItem(
+      PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+      document,
+      ProviderUpdateDismissalsSchema,
+    );
+  } catch {
+    // Dismissal state is best-effort UI state; a storage failure should not block the toast.
+  }
+}
+
+export function isProviderUpdateNotificationDismissed(
+  dismissalKey: string | null | undefined,
+): boolean {
+  if (!dismissalKey) {
+    return false;
+  }
+  return readProviderUpdateDismissals().keys.includes(dismissalKey);
+}
+
+export function dismissProviderUpdateNotification(dismissalKey: string | null | undefined): void {
+  const trimmedKey = dismissalKey?.trim();
+  if (!trimmedKey) {
+    return;
+  }
+  const document = readProviderUpdateDismissals();
+  if (document.keys.includes(trimmedKey)) {
+    return;
+  }
+  writeProviderUpdateDismissals({
+    keys: [...document.keys, trimmedKey],
+  });
+}
+
+export function useDismissedProviderUpdateNotificationKeys() {
+  const [dismissals, setDismissals] = useLocalStorage(
+    PROVIDER_UPDATE_DISMISSALS_STORAGE_KEY,
+    { keys: [] },
+    ProviderUpdateDismissalsSchema,
+  );
+  const dismissedKeys = dismissals.keys;
+
+  const dismissedKeySet = useMemo(() => new Set(dismissedKeys), [dismissedKeys]);
+
+  const dismissNotificationKey = useCallback(
+    (key: string) => {
+      const trimmedKey = key.trim();
+      if (trimmedKey.length === 0 || dismissedKeySet.has(trimmedKey)) {
+        return;
+      }
+
+      setDismissals({
+        keys: [...dismissedKeys, trimmedKey],
+      });
+    },
+    [dismissedKeySet, dismissedKeys, setDismissals],
+  );
+
+  return {
+    dismissedNotificationKeys: dismissedKeySet,
+    dismissNotificationKey,
+  };
+}
diff --git a/apps/web/src/pullRequestReference.test.ts b/apps/web/src/pullRequestReference.test.ts
index 2a1ed520799..9157061a304 100644
--- a/apps/web/src/pullRequestReference.test.ts
+++ b/apps/web/src/pullRequestReference.test.ts
@@ -9,6 +9,24 @@ describe("parsePullRequestReference", () => {
     );
   });
 
+  it("accepts Azure DevOps pull request URLs", () => {
+    expect(
+      parsePullRequestReference("https://dev.azure.com/acme/project/_git/t3code/pullrequest/42"),
+    ).toBe("https://dev.azure.com/acme/project/_git/t3code/pullrequest/42");
+  });
+
+  it("accepts GitLab merge request URLs", () => {
+    expect(parsePullRequestReference("https://gitlab.com/group/project/-/merge_requests/42")).toBe(
+      "https://gitlab.com/group/project/-/merge_requests/42",
+    );
+  });
+
+  it("accepts legacy Azure DevOps pull request URLs", () => {
+    expect(
+      parsePullRequestReference("https://acme.visualstudio.com/project/_git/t3code/pullrequest/42"),
+    ).toBe("https://acme.visualstudio.com/project/_git/t3code/pullrequest/42");
+  });
+
   it("accepts raw numbers", () => {
     expect(parsePullRequestReference("42")).toBe("42");
   });
@@ -31,6 +49,24 @@ describe("parsePullRequestReference", () => {
     ).toBe("https://github.com/pingdotgg/t3code/pull/42");
   });
 
+  it("accepts glab mr checkout commands with raw numbers", () => {
+    expect(parsePullRequestReference("glab mr checkout 42")).toBe("42");
+  });
+
+  it("accepts az repos pr checkout commands with raw numbers", () => {
+    expect(parsePullRequestReference("az repos pr checkout --id 42")).toBe("42");
+  });
+
+  it("accepts az repos pr checkout commands with equals-style ids", () => {
+    expect(parsePullRequestReference("az repos pr checkout --id=42")).toBe("42");
+  });
+
+  it("accepts az repos pr checkout commands with extra flags", () => {
+    expect(parsePullRequestReference("az repos pr checkout --id 42 --remote-name origin")).toBe(
+      "42",
+    );
+  });
+
   it("rejects non-pull-request input", () => {
     expect(parsePullRequestReference("feature/my-branch")).toBeNull();
   });
diff --git a/apps/web/src/pullRequestReference.ts b/apps/web/src/pullRequestReference.ts
index b033db7d214..b919e736cc0 100644
--- a/apps/web/src/pullRequestReference.ts
+++ b/apps/web/src/pullRequestReference.ts
@@ -1,7 +1,26 @@
 const GITHUB_PULL_REQUEST_URL_PATTERN =
   /^https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/(\d+)(?:[/?#].*)?$/i;
+const GITLAB_MERGE_REQUEST_URL_PATTERN =
+  /^https:\/\/[^/\s]*gitlab[^/\s]*\/.+\/-\/merge_requests\/(\d+)(?:[/?#].*)?$/i;
+const AZURE_DEVOPS_PULL_REQUEST_URL_PATTERN =
+  /^https:\/\/(?:dev\.azure\.com\/[^/\s]+\/[^/\s]+|[^/\s]+\.visualstudio\.com\/[^/\s]+)\/_git\/[^/\s]+\/pullrequest\/(\d+)(?:[/?#].*)?$/i;
 const PULL_REQUEST_NUMBER_PATTERN = /^#?(\d+)$/;
 const GITHUB_CLI_PR_CHECKOUT_PATTERN = /^gh\s+pr\s+checkout\s+(.+)$/i;
+const GITLAB_CLI_MR_CHECKOUT_PATTERN = /^glab\s+mr\s+checkout\s+(.+)$/i;
+const AZURE_DEVOPS_CLI_PR_CHECKOUT_PATTERN = /^az\s+repos\s+pr\s+checkout\s+(.+)$/i;
+
+function parseAzureDevOpsCheckoutReference(args: string): string | null {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  for (const [index, part] of parts.entries()) {
+    if (part === "--id" || part === "-i") {
+      return parts[index + 1] ?? null;
+    }
+    if (part.startsWith("--id=")) {
+      return part.slice("--id=".length) || null;
+    }
+  }
+  return parts.find((part) => !part.startsWith("-")) ?? null;
+}
 
 export function parsePullRequestReference(input: string): string | null {
   const trimmed = input.trim();
@@ -10,12 +29,23 @@ export function parsePullRequestReference(input: string): string | null {
   }
 
   const ghCliCheckoutMatch = GITHUB_CLI_PR_CHECKOUT_PATTERN.exec(trimmed);
-  const normalizedInput = ghCliCheckoutMatch?.[1]?.trim() ?? trimmed;
+  const glabCliCheckoutMatch = GITLAB_CLI_MR_CHECKOUT_PATTERN.exec(trimmed);
+  const azureDevOpsCliCheckoutMatch = AZURE_DEVOPS_CLI_PR_CHECKOUT_PATTERN.exec(trimmed);
+  const normalizedInput =
+    ghCliCheckoutMatch?.[1]?.trim() ??
+    glabCliCheckoutMatch?.[1]?.trim() ??
+    (azureDevOpsCliCheckoutMatch?.[1]
+      ? parseAzureDevOpsCheckoutReference(azureDevOpsCliCheckoutMatch[1])
+      : null) ??
+    trimmed;
   if (normalizedInput.length === 0) {
     return null;
   }
 
-  const urlMatch = GITHUB_PULL_REQUEST_URL_PATTERN.exec(normalizedInput);
+  const urlMatch =
+    GITHUB_PULL_REQUEST_URL_PATTERN.exec(normalizedInput) ??
+    GITLAB_MERGE_REQUEST_URL_PATTERN.exec(normalizedInput) ??
+    AZURE_DEVOPS_PULL_REQUEST_URL_PATTERN.exec(normalizedInput);
   if (urlMatch?.[1]) {
     return normalizedInput;
   }
diff --git a/apps/web/src/rightPanelLayout.ts b/apps/web/src/rightPanelLayout.ts
new file mode 100644
index 00000000000..5528072e57b
--- /dev/null
+++ b/apps/web/src/rightPanelLayout.ts
@@ -0,0 +1,3 @@
+export const RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY = "(max-width: 980px)";
+export const RIGHT_PANEL_SHEET_CLASS_NAME =
+  "w-[min(42vw,28rem)] min-w-80 max-w-[28rem] p-0 max-[760px]:w-[min(88vw,24rem)] max-[760px]:min-w-0 wco:mt-[env(titlebar-area-height)] wco:h-[calc(100%-env(titlebar-area-height))] wco:max-h-[calc(100%-env(titlebar-area-height))]";
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index 6494ecdb25f..3a9140e278c 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -13,7 +13,11 @@ import { Route as SettingsRouteImport } from './routes/settings'
 import { Route as PairRouteImport } from './routes/pair'
 import { Route as ChatRouteImport } from './routes/_chat'
 import { Route as ChatIndexRouteImport } from './routes/_chat.index'
+import { Route as SettingsSourceControlRouteImport } from './routes/settings.source-control'
+import { Route as SettingsProvidersRouteImport } from './routes/settings.providers'
+import { Route as SettingsKeybindingsRouteImport } from './routes/settings.keybindings'
 import { Route as SettingsGeneralRouteImport } from './routes/settings.general'
+import { Route as SettingsDiagnosticsRouteImport } from './routes/settings.diagnostics'
 import { Route as SettingsConnectionsRouteImport } from './routes/settings.connections'
 import { Route as SettingsArchivedRouteImport } from './routes/settings.archived'
 import { Route as ChatDraftDraftIdRouteImport } from './routes/_chat.draft.$draftId'
@@ -38,11 +42,31 @@ const ChatIndexRoute = ChatIndexRouteImport.update({
   path: '/',
   getParentRoute: () => ChatRoute,
 } as any)
+const SettingsSourceControlRoute = SettingsSourceControlRouteImport.update({
+  id: '/source-control',
+  path: '/source-control',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsProvidersRoute = SettingsProvidersRouteImport.update({
+  id: '/providers',
+  path: '/providers',
+  getParentRoute: () => SettingsRoute,
+} as any)
+const SettingsKeybindingsRoute = SettingsKeybindingsRouteImport.update({
+  id: '/keybindings',
+  path: '/keybindings',
+  getParentRoute: () => SettingsRoute,
+} as any)
 const SettingsGeneralRoute = SettingsGeneralRouteImport.update({
   id: '/general',
   path: '/general',
   getParentRoute: () => SettingsRoute,
 } as any)
+const SettingsDiagnosticsRoute = SettingsDiagnosticsRouteImport.update({
+  id: '/diagnostics',
+  path: '/diagnostics',
+  getParentRoute: () => SettingsRoute,
+} as any)
 const SettingsConnectionsRoute = SettingsConnectionsRouteImport.update({
   id: '/connections',
   path: '/connections',
@@ -71,7 +95,11 @@ export interface FileRoutesByFullPath {
   '/settings': typeof SettingsRouteWithChildren
   '/settings/archived': typeof SettingsArchivedRoute
   '/settings/connections': typeof SettingsConnectionsRoute
+  '/settings/diagnostics': typeof SettingsDiagnosticsRoute
   '/settings/general': typeof SettingsGeneralRoute
+  '/settings/keybindings': typeof SettingsKeybindingsRoute
+  '/settings/providers': typeof SettingsProvidersRoute
+  '/settings/source-control': typeof SettingsSourceControlRoute
   '/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
   '/draft/$draftId': typeof ChatDraftDraftIdRoute
 }
@@ -80,7 +108,11 @@ export interface FileRoutesByTo {
   '/settings': typeof SettingsRouteWithChildren
   '/settings/archived': typeof SettingsArchivedRoute
   '/settings/connections': typeof SettingsConnectionsRoute
+  '/settings/diagnostics': typeof SettingsDiagnosticsRoute
   '/settings/general': typeof SettingsGeneralRoute
+  '/settings/keybindings': typeof SettingsKeybindingsRoute
+  '/settings/providers': typeof SettingsProvidersRoute
+  '/settings/source-control': typeof SettingsSourceControlRoute
   '/': typeof ChatIndexRoute
   '/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
   '/draft/$draftId': typeof ChatDraftDraftIdRoute
@@ -92,7 +124,11 @@ export interface FileRoutesById {
   '/settings': typeof SettingsRouteWithChildren
   '/settings/archived': typeof SettingsArchivedRoute
   '/settings/connections': typeof SettingsConnectionsRoute
+  '/settings/diagnostics': typeof SettingsDiagnosticsRoute
   '/settings/general': typeof SettingsGeneralRoute
+  '/settings/keybindings': typeof SettingsKeybindingsRoute
+  '/settings/providers': typeof SettingsProvidersRoute
+  '/settings/source-control': typeof SettingsSourceControlRoute
   '/_chat/': typeof ChatIndexRoute
   '/_chat/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
   '/_chat/draft/$draftId': typeof ChatDraftDraftIdRoute
@@ -105,7 +141,11 @@ export interface FileRouteTypes {
     | '/settings'
     | '/settings/archived'
     | '/settings/connections'
+    | '/settings/diagnostics'
     | '/settings/general'
+    | '/settings/keybindings'
+    | '/settings/providers'
+    | '/settings/source-control'
     | '/$environmentId/$threadId'
     | '/draft/$draftId'
   fileRoutesByTo: FileRoutesByTo
@@ -114,7 +154,11 @@ export interface FileRouteTypes {
     | '/settings'
     | '/settings/archived'
     | '/settings/connections'
+    | '/settings/diagnostics'
     | '/settings/general'
+    | '/settings/keybindings'
+    | '/settings/providers'
+    | '/settings/source-control'
     | '/'
     | '/$environmentId/$threadId'
     | '/draft/$draftId'
@@ -125,7 +169,11 @@ export interface FileRouteTypes {
     | '/settings'
     | '/settings/archived'
     | '/settings/connections'
+    | '/settings/diagnostics'
     | '/settings/general'
+    | '/settings/keybindings'
+    | '/settings/providers'
+    | '/settings/source-control'
     | '/_chat/'
     | '/_chat/$environmentId/$threadId'
     | '/_chat/draft/$draftId'
@@ -167,6 +215,27 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ChatIndexRouteImport
       parentRoute: typeof ChatRoute
     }
+    '/settings/source-control': {
+      id: '/settings/source-control'
+      path: '/source-control'
+      fullPath: '/settings/source-control'
+      preLoaderRoute: typeof SettingsSourceControlRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/providers': {
+      id: '/settings/providers'
+      path: '/providers'
+      fullPath: '/settings/providers'
+      preLoaderRoute: typeof SettingsProvidersRouteImport
+      parentRoute: typeof SettingsRoute
+    }
+    '/settings/keybindings': {
+      id: '/settings/keybindings'
+      path: '/keybindings'
+      fullPath: '/settings/keybindings'
+      preLoaderRoute: typeof SettingsKeybindingsRouteImport
+      parentRoute: typeof SettingsRoute
+    }
     '/settings/general': {
       id: '/settings/general'
       path: '/general'
@@ -174,6 +243,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof SettingsGeneralRouteImport
       parentRoute: typeof SettingsRoute
     }
+    '/settings/diagnostics': {
+      id: '/settings/diagnostics'
+      path: '/diagnostics'
+      fullPath: '/settings/diagnostics'
+      preLoaderRoute: typeof SettingsDiagnosticsRouteImport
+      parentRoute: typeof SettingsRoute
+    }
     '/settings/connections': {
       id: '/settings/connections'
       path: '/connections'
@@ -222,13 +298,21 @@ const ChatRouteWithChildren = ChatRoute._addFileChildren(ChatRouteChildren)
 interface SettingsRouteChildren {
   SettingsArchivedRoute: typeof SettingsArchivedRoute
   SettingsConnectionsRoute: typeof SettingsConnectionsRoute
+  SettingsDiagnosticsRoute: typeof SettingsDiagnosticsRoute
   SettingsGeneralRoute: typeof SettingsGeneralRoute
+  SettingsKeybindingsRoute: typeof SettingsKeybindingsRoute
+  SettingsProvidersRoute: typeof SettingsProvidersRoute
+  SettingsSourceControlRoute: typeof SettingsSourceControlRoute
 }
 
 const SettingsRouteChildren: SettingsRouteChildren = {
   SettingsArchivedRoute: SettingsArchivedRoute,
   SettingsConnectionsRoute: SettingsConnectionsRoute,
+  SettingsDiagnosticsRoute: SettingsDiagnosticsRoute,
   SettingsGeneralRoute: SettingsGeneralRoute,
+  SettingsKeybindingsRoute: SettingsKeybindingsRoute,
+  SettingsProvidersRoute: SettingsProvidersRoute,
+  SettingsSourceControlRoute: SettingsSourceControlRoute,
 }
 
 const SettingsRouteWithChildren = SettingsRoute._addFileChildren(
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 8c5046af362..ec525fa2316 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -13,15 +13,28 @@ import { QueryClient, useQueryClient } from "@tanstack/react-query";
 import { APP_DISPLAY_NAME } from "../branding";
 import { AppSidebarLayout } from "../components/AppSidebarLayout";
 import { CommandPalette } from "../components/CommandPalette";
+import { SshPasswordPromptDialog } from "../components/desktop/SshPasswordPromptDialog";
+import { ProviderUpdateLaunchNotification } from "../components/ProviderUpdateLaunchNotification";
 import {
   SlowRpcAckToastCoordinator,
   WebSocketConnectionCoordinator,
   WebSocketConnectionSurface,
 } from "../components/WebSocketConnectionSurface";
 import { Button } from "../components/ui/button";
-import { AnchoredToastProvider, ToastProvider, toastManager } from "../components/ui/toast";
+import {
+  AnchoredToastProvider,
+  stackedThreadToast,
+  ToastProvider,
+  toastManager,
+} from "../components/ui/toast";
 import { resolveAndPersistPreferredEditor } from "../editorPreferences";
 import { readLocalApi } from "../localApi";
+import { useSettings } from "../hooks/useSettings";
+import {
+  deriveLogicalProjectKeyFromSettings,
+  derivePhysicalProjectKeyFromPath,
+  selectProjectGroupingSettings,
+} from "../logicalProject";
 import {
   getServerConfigUpdatedNotification,
   ServerConfigUpdatedNotification,
@@ -36,19 +49,41 @@ import { syncBrowserChromeTheme } from "../hooks/useTheme";
 import {
   ensureEnvironmentConnectionBootstrapped,
   getPrimaryEnvironmentConnection,
+  listSavedEnvironmentRecords,
+  waitForSavedEnvironmentRegistryHydration,
   startEnvironmentConnectionService,
+  useSavedEnvironmentRegistryStore,
 } from "../environments/runtime";
 import { configureClientTracing } from "../observability/clientTracing";
 import {
   ensurePrimaryEnvironmentReady,
+  getPrimaryKnownEnvironment,
   resolveInitialServerAuthGateState,
   updatePrimaryEnvironmentDescriptor,
 } from "../environments/primary";
+import { hasHostedPairingRequest, isHostedStaticApp } from "../hostedPairing";
 
 export const Route = createRootRouteWithContext<{
   queryClient: QueryClient;
 }>()({
-  beforeLoad: async () => {
+  beforeLoad: async ({ location }) => {
+    if (location.pathname === "/pair" && hasHostedPairingRequest(new URL(window.location.href))) {
+      return {
+        authGateState: {
+          status: "hosted-pairing",
+        } as const,
+      };
+    }
+
+    if (isHostedStaticApp(new URL(window.location.href))) {
+      await waitForSavedEnvironmentRegistryHydration();
+      return {
+        authGateState: {
+          status: "hosted-static",
+        } as const,
+      };
+    }
+
     const [, authGateState] = await Promise.all([
       ensurePrimaryEnvironmentReady(),
       resolveInitialServerAuthGateState(),
@@ -67,6 +102,7 @@ export const Route = createRootRouteWithContext<{
 function RootRouteView() {
   const pathname = useLocation({ select: (location) => location.pathname });
   const { authGateState } = Route.useRouteContext();
+  const primaryEnvironmentAuthenticated = authGateState.status === "authenticated";
 
   useEffect(() => {
     const frame = window.requestAnimationFrame(() => {
@@ -81,30 +117,66 @@ function RootRouteView() {
     return <Outlet />;
   }
 
-  if (authGateState.status !== "authenticated") {
+  if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
     return <Outlet />;
   }
+
+  const appShell = (
+    <CommandPalette>
+      <AppSidebarLayout>
+        <Outlet />
+      </AppSidebarLayout>
+    </CommandPalette>
+  );
+
   return (
     <ToastProvider>
       <AnchoredToastProvider>
-        <AuthenticatedTracingBootstrap />
-        <ServerStateBootstrap />
+        {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
+        {primaryEnvironmentAuthenticated ? <ServerStateBootstrap /> : null}
         <EnvironmentConnectionManagerBootstrap />
-        <EventRouter />
-        <WebSocketConnectionCoordinator />
-        <SlowRpcAckToastCoordinator />
-        <WebSocketConnectionSurface>
-          <CommandPalette>
-            <AppSidebarLayout>
-              <Outlet />
-            </AppSidebarLayout>
-          </CommandPalette>
-        </WebSocketConnectionSurface>
+        <SshPasswordPromptDialog />
+        <HostedStaticEnvironmentBootstrap />
+        {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
+        {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
+        {primaryEnvironmentAuthenticated ? <WebSocketConnectionCoordinator /> : null}
+        {primaryEnvironmentAuthenticated ? <SlowRpcAckToastCoordinator /> : null}
+        {primaryEnvironmentAuthenticated ? (
+          <WebSocketConnectionSurface>{appShell}</WebSocketConnectionSurface>
+        ) : (
+          appShell
+        )}
       </AnchoredToastProvider>
     </ToastProvider>
   );
 }
 
+function HostedStaticEnvironmentBootstrap() {
+  const savedEnvironmentCount = useSavedEnvironmentRegistryStore(
+    (state) => Object.keys(state.byId).length,
+  );
+
+  useEffect(() => {
+    if (getPrimaryKnownEnvironment()) {
+      return;
+    }
+
+    const currentActiveEnvironmentId = useStore.getState().activeEnvironmentId;
+    if (currentActiveEnvironmentId) {
+      return;
+    }
+
+    const firstSavedEnvironment = listSavedEnvironmentRecords()[0];
+    if (!firstSavedEnvironment) {
+      return;
+    }
+
+    useStore.getState().setActiveEnvironmentId(firstSavedEnvironment.environmentId);
+  }, [savedEnvironmentCount]);
+
+  return null;
+}
+
 function RootRouteErrorView({ error, reset }: ErrorComponentProps) {
   const message = errorMessage(error);
   const details = errorDetails(error);
@@ -177,7 +249,13 @@ function errorDetails(error: unknown): string {
 }
 
 function ServerStateBootstrap() {
-  useEffect(() => startServerStateSync(getPrimaryEnvironmentConnection().client.server), []);
+  useEffect(() => {
+    if (!getPrimaryKnownEnvironment()) {
+      return;
+    }
+
+    return startServerStateSync(getPrimaryEnvironmentConnection().client.server);
+  }, []);
 
   return null;
 }
@@ -204,9 +282,11 @@ function EventRouter() {
   const setActiveEnvironmentId = useStore((store) => store.setActiveEnvironmentId);
   const navigate = useNavigate();
   const pathname = useLocation({ select: (loc) => loc.pathname });
+  const projectGroupingSettings = useSettings(selectProjectGroupingSettings);
   const readPathname = useEffectEvent(() => pathname);
   const handledBootstrapThreadIdRef = useRef<string | null>(null);
   const seenServerConfigUpdateIdRef = useRef(getServerConfigUpdatedNotification()?.id ?? 0);
+  const lastKeybindingsSuccessToastAtRef = useRef(0);
   const disposedRef = useRef(false);
   const serverConfig = useServerConfig();
 
@@ -224,14 +304,21 @@ function EventRouter() {
       if (!payload.bootstrapProjectId || !payload.bootstrapThreadId) {
         return;
       }
-      useUiStateStore
-        .getState()
-        .setProjectExpanded(
-          scopedProjectKey(
-            scopeProjectRef(payload.environment.environmentId, payload.bootstrapProjectId),
-          ),
-          true,
+      const bootstrapEnvironmentState =
+        useStore.getState().environmentStateById[payload.environment.environmentId];
+      const bootstrapProject =
+        bootstrapEnvironmentState?.projectById[payload.bootstrapProjectId] ?? null;
+      const bootstrapProjectKey =
+        (bootstrapProject
+          ? deriveLogicalProjectKeyFromSettings(bootstrapProject, projectGroupingSettings)
+          : null) ??
+        (serverConfig?.cwd
+          ? derivePhysicalProjectKeyFromPath(payload.environment.environmentId, serverConfig.cwd)
+          : null) ??
+        scopedProjectKey(
+          scopeProjectRef(payload.environment.environmentId, payload.bootstrapProjectId),
         );
+      useUiStateStore.getState().setProjectExpanded(bootstrapProjectKey, true);
 
       if (readPathname() !== "/") {
         return;
@@ -266,6 +353,11 @@ function EventRouter() {
 
       const issue = payload.issues.find((entry) => entry.kind.startsWith("keybindings."));
       if (!issue) {
+        const now = Date.now();
+        if (now - lastKeybindingsSuccessToastAtRef.current < 2_000) {
+          return;
+        }
+        lastKeybindingsSuccessToastAtRef.current = now;
         toastManager.add({
           type: "success",
           title: "Keybindings updated",
@@ -274,37 +366,42 @@ function EventRouter() {
         return;
       }
 
-      toastManager.add({
-        type: "warning",
-        title: "Invalid keybindings configuration",
-        description: issue.message,
-        actionProps: {
-          children: "Open keybindings.json",
-          onClick: () => {
-            const api = readLocalApi();
-            if (!api) {
-              return;
-            }
-
-            void Promise.resolve(serverConfig ?? api.server.getConfig())
-              .then((config) => {
-                const editor = resolveAndPersistPreferredEditor(config.availableEditors);
-                if (!editor) {
-                  throw new Error("No available editors found.");
-                }
-                return api.shell.openInEditor(config.keybindingsConfigPath, editor);
-              })
-              .catch((error) => {
-                toastManager.add({
-                  type: "error",
-                  title: "Unable to open keybindings file",
-                  description:
-                    error instanceof Error ? error.message : "Unknown error opening file.",
+      toastManager.add(
+        stackedThreadToast({
+          type: "warning",
+          title: "Invalid keybindings configuration",
+          description: issue.message,
+          actionVariant: "outline",
+          actionProps: {
+            children: "Open keybindings.json",
+            onClick: () => {
+              const api = readLocalApi();
+              if (!api) {
+                return;
+              }
+
+              void Promise.resolve(serverConfig ?? api.server.getConfig())
+                .then((config) => {
+                  const editor = resolveAndPersistPreferredEditor(config.availableEditors);
+                  if (!editor) {
+                    throw new Error("No available editors found.");
+                  }
+                  return api.shell.openInEditor(config.keybindingsConfigPath, editor);
+                })
+                .catch((error) => {
+                  toastManager.add(
+                    stackedThreadToast({
+                      type: "error",
+                      title: "Unable to open keybindings file",
+                      description:
+                        error instanceof Error ? error.message : "Unknown error opening file.",
+                    }),
+                  );
                 });
-              });
+            },
           },
-        },
-      });
+        }),
+      );
     },
   );
 
diff --git a/apps/web/src/routes/_chat.$environmentId.$threadId.tsx b/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
index b62fd6b9c65..1877fee6f7d 100644
--- a/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
+++ b/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
@@ -1,5 +1,5 @@
 import { createFileRoute, retainSearchParams, useNavigate } from "@tanstack/react-router";
-import { Suspense, lazy, type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
+import { Suspense, lazy, useCallback, useEffect, useMemo, useState } from "react";
 
 import ChatView from "../components/ChatView";
 import { threadHasStarted } from "../components/ChatView.logic";
@@ -17,45 +17,20 @@ import {
   stripDiffSearchParams,
 } from "../diffRouteSearch";
 import { useMediaQuery } from "../hooks/useMediaQuery";
+import { RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY } from "../rightPanelLayout";
 import { selectEnvironmentState, selectThreadExistsByRef, useStore } from "../store";
 import { createThreadSelectorByRef } from "../storeSelectors";
 import { resolveThreadRouteRef, buildThreadRouteParams } from "../threadRoutes";
-import { Sheet, SheetPopup } from "../components/ui/sheet";
+import { RightPanelSheet } from "../components/RightPanelSheet";
 import { Sidebar, SidebarInset, SidebarProvider, SidebarRail } from "~/components/ui/sidebar";
 
 const DiffPanel = lazy(() => import("../components/DiffPanel"));
-const DIFF_INLINE_LAYOUT_MEDIA_QUERY = "(max-width: 1180px)";
 const DIFF_INLINE_SIDEBAR_WIDTH_STORAGE_KEY = "chat_diff_sidebar_width";
-const DIFF_INLINE_DEFAULT_WIDTH = "clamp(28rem,48vw,44rem)";
-const DIFF_INLINE_SIDEBAR_MIN_WIDTH = 26 * 16;
+const DIFF_INLINE_DEFAULT_WIDTH = "clamp(24rem,34vw,36rem)";
+const DIFF_INLINE_SIDEBAR_MIN_WIDTH = 22 * 16;
+const DIFF_INLINE_SIDEBAR_MAX_WIDTH = 256 * 16;
 const COMPOSER_COMPACT_MIN_LEFT_CONTROLS_WIDTH_PX = 208;
 
-const DiffPanelSheet = (props: {
-  children: ReactNode;
-  diffOpen: boolean;
-  onCloseDiff: () => void;
-}) => {
-  return (
-    <Sheet
-      open={props.diffOpen}
-      onOpenChange={(open) => {
-        if (!open) {
-          props.onCloseDiff();
-        }
-      }}
-    >
-      <SheetPopup
-        side="right"
-        showCloseButton={false}
-        keepMounted
-        className="w-[min(88vw,820px)] max-w-[820px] p-0"
-      >
-        {props.children}
-      </SheetPopup>
-    </Sheet>
-  );
-};
-
 const DiffLoadingFallback = (props: { mode: DiffPanelMode }) => {
   return (
     <DiffPanelShell mode={props.mode} header={<DiffPanelHeaderSkeleton />}>
@@ -150,6 +125,7 @@ const DiffPanelInlineSidebar = (props: {
         collapsible="offcanvas"
         className="border-l border-border bg-card text-foreground"
         resizable={{
+          maxWidth: DIFF_INLINE_SIDEBAR_MAX_WIDTH,
           minWidth: DIFF_INLINE_SIDEBAR_MIN_WIDTH,
           shouldAcceptWidth: shouldAcceptInlineSidebarWidth,
           storageKey: DIFF_INLINE_SIDEBAR_WIDTH_STORAGE_KEY,
@@ -192,7 +168,7 @@ function ChatThreadRouteView() {
   const serverThreadStarted = threadHasStarted(serverThread);
   const environmentHasAnyThreads = environmentHasServerThreads || environmentHasDraftThreads;
   const diffOpen = search.diff === "1";
-  const shouldUseDiffSheet = useMediaQuery(DIFF_INLINE_LAYOUT_MEDIA_QUERY);
+  const shouldUseDiffSheet = useMediaQuery(RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY);
   const currentThreadKey = threadRef ? `${threadRef.environmentId}:${threadRef.threadId}` : null;
   const [diffPanelMountState, setDiffPanelMountState] = useState(() => ({
     threadKey: currentThreadKey,
@@ -264,11 +240,12 @@ function ChatThreadRouteView() {
   if (!shouldUseDiffSheet) {
     return (
       <>
-        <SidebarInset className="h-dvh  min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
+        <SidebarInset className="h-svh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground md:h-dvh">
           <ChatView
             environmentId={threadRef.environmentId}
             threadId={threadRef.threadId}
             onDiffPanelOpen={markDiffOpened}
+            reserveTitleBarControlInset={!diffOpen}
             routeKind="server"
           />
         </SidebarInset>
@@ -284,7 +261,7 @@ function ChatThreadRouteView() {
 
   return (
     <>
-      <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
+      <SidebarInset className="h-svh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground md:h-dvh">
         <ChatView
           environmentId={threadRef.environmentId}
           threadId={threadRef.threadId}
@@ -292,9 +269,9 @@ function ChatThreadRouteView() {
           routeKind="server"
         />
       </SidebarInset>
-      <DiffPanelSheet diffOpen={diffOpen} onCloseDiff={closeDiff}>
+      <RightPanelSheet open={diffOpen} onClose={closeDiff}>
         {shouldRenderDiffContent ? <LazyDiffPanel mode="sheet" /> : null}
-      </DiffPanelSheet>
+      </RightPanelSheet>
     </>
   );
 }
diff --git a/apps/web/src/routes/_chat.draft.$draftId.tsx b/apps/web/src/routes/_chat.draft.$draftId.tsx
index e7bb1d0912f..77b9f18f0d7 100644
--- a/apps/web/src/routes/_chat.draft.$draftId.tsx
+++ b/apps/web/src/routes/_chat.draft.$draftId.tsx
@@ -55,7 +55,7 @@ function DraftChatThreadRouteView() {
 
   if (canonicalThreadRef) {
     return (
-      <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
+      <SidebarInset className="h-svh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground md:h-dvh">
         <ChatView
           environmentId={canonicalThreadRef.environmentId}
           threadId={canonicalThreadRef.threadId}
@@ -70,7 +70,7 @@ function DraftChatThreadRouteView() {
   }
 
   return (
-    <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
+    <SidebarInset className="h-svh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground md:h-dvh">
       <ChatView
         draftId={draftId}
         environmentId={draftSession.environmentId}
diff --git a/apps/web/src/routes/_chat.index.tsx b/apps/web/src/routes/_chat.index.tsx
index 43f06177a74..98a125bdfe4 100644
--- a/apps/web/src/routes/_chat.index.tsx
+++ b/apps/web/src/routes/_chat.index.tsx
@@ -1,11 +1,66 @@
 import { createFileRoute } from "@tanstack/react-router";
+import { LinkIcon, PlusIcon } from "lucide-react";
 
 import { NoActiveThreadState } from "../components/NoActiveThreadState";
+import { Button } from "../components/ui/button";
+import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from "../components/ui/empty";
+import { SidebarInset, SidebarTrigger } from "../components/ui/sidebar";
+import { useSavedEnvironmentRegistryStore } from "../environments/runtime";
+import { APP_DISPLAY_NAME } from "~/branding";
 
 function ChatIndexRouteView() {
+  const { authGateState } = Route.useRouteContext();
+  const savedEnvironmentCount = useSavedEnvironmentRegistryStore(
+    (state) => Object.keys(state.byId).length,
+  );
+
+  if (authGateState.status === "hosted-static" && savedEnvironmentCount === 0) {
+    return <HostedStaticOnboardingState />;
+  }
+
   return <NoActiveThreadState />;
 }
 
 export const Route = createFileRoute("/_chat/")({
   component: ChatIndexRouteView,
 });
+
+function HostedStaticOnboardingState() {
+  return (
+    <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
+      <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden bg-background">
+        <header className="border-b border-border px-3 py-2 sm:px-5 sm:py-3">
+          <div className="flex items-center gap-2">
+            <SidebarTrigger className="size-7 shrink-0 md:hidden" />
+            <span className="text-sm font-medium text-foreground md:text-muted-foreground/60">
+              {APP_DISPLAY_NAME}
+            </span>
+          </div>
+        </header>
+
+        <Empty className="flex-1">
+          <div className="w-full max-w-xl rounded-3xl border border-border/55 bg-card/20 px-8 py-12 shadow-sm/5">
+            <EmptyHeader className="max-w-none">
+              <div className="mx-auto mb-5 flex size-11 items-center justify-center rounded-xl border border-border/70 bg-background/70 text-muted-foreground">
+                <LinkIcon className="size-5" />
+              </div>
+              <EmptyTitle className="text-foreground text-xl">
+                Connect an environment to get started
+              </EmptyTitle>
+              <EmptyDescription className="mt-2 text-sm leading-relaxed text-muted-foreground/78">
+                Open a pairing link from your T3 Code desktop app or add a reachable backend
+                manually. Your saved environments stay in this browser.
+              </EmptyDescription>
+              <div className="mt-6 flex justify-center">
+                <Button render={<a href="/settings/connections" />} size="sm">
+                  <PlusIcon className="size-4" />
+                  Add environment
+                </Button>
+              </div>
+            </EmptyHeader>
+          </div>
+        </Empty>
+      </div>
+    </SidebarInset>
+  );
+}
diff --git a/apps/web/src/routes/_chat.tsx b/apps/web/src/routes/_chat.tsx
index b72e504fae9..da22d7e6028 100644
--- a/apps/web/src/routes/_chat.tsx
+++ b/apps/web/src/routes/_chat.tsx
@@ -2,10 +2,6 @@ import { Outlet, createFileRoute, redirect } from "@tanstack/react-router";
 import { useEffect } from "react";
 
 import { useCommandPaletteStore } from "../commandPaletteStore";
-import {
-  ensurePrimaryEnvironmentReady,
-  resolveInitialServerAuthGateState,
-} from "../environments/primary";
 import { useHandleNewThread } from "../hooks/useHandleNewThread";
 import {
   startNewLocalThreadFromContext,
@@ -111,12 +107,11 @@ function ChatRouteLayout() {
 }
 
 export const Route = createFileRoute("/_chat")({
-  beforeLoad: async () => {
-    const [, authGateState] = await Promise.all([
-      ensurePrimaryEnvironmentReady(),
-      resolveInitialServerAuthGateState(),
-    ]);
-    if (authGateState.status !== "authenticated") {
+  beforeLoad: async ({ context }) => {
+    if (
+      context.authGateState.status !== "authenticated" &&
+      context.authGateState.status !== "hosted-static"
+    ) {
       throw redirect({ to: "/pair", replace: true });
     }
   },
diff --git a/apps/web/src/routes/pair.tsx b/apps/web/src/routes/pair.tsx
index 053816bd773..6575cd1bafa 100644
--- a/apps/web/src/routes/pair.tsx
+++ b/apps/web/src/routes/pair.tsx
@@ -1,18 +1,21 @@
 import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
 
-import { PairingPendingSurface, PairingRouteSurface } from "../components/auth/PairingRouteSurface";
 import {
-  ensurePrimaryEnvironmentReady,
-  resolveInitialServerAuthGateState,
-} from "../environments/primary";
+  HostedPairingRouteSurface,
+  PairingPendingSurface,
+  PairingRouteSurface,
+} from "../components/auth/PairingRouteSurface";
 
 export const Route = createFileRoute("/pair")({
-  beforeLoad: async () => {
-    const [, authGateState] = await Promise.all([
-      ensurePrimaryEnvironmentReady(),
-      resolveInitialServerAuthGateState(),
-    ]);
-    if (authGateState.status === "authenticated") {
+  beforeLoad: async ({ context }) => {
+    const { authGateState } = context;
+    if (authGateState.status === "hosted-pairing") {
+      return {
+        authGateState,
+      };
+    }
+
+    if (authGateState.status === "authenticated" || authGateState.status === "hosted-static") {
       throw redirect({ to: "/", replace: true });
     }
     return {
@@ -31,6 +34,10 @@ function PairRouteView() {
     return null;
   }
 
+  if (authGateState.status === "hosted-pairing") {
+    return <HostedPairingRouteSurface />;
+  }
+
   return (
     <PairingRouteSurface
       auth={authGateState.auth}
diff --git a/apps/web/src/routes/settings.diagnostics.tsx b/apps/web/src/routes/settings.diagnostics.tsx
new file mode 100644
index 00000000000..e86e5c5cb14
--- /dev/null
+++ b/apps/web/src/routes/settings.diagnostics.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { DiagnosticsSettingsPanel } from "../components/settings/DiagnosticsSettings";
+
+export const Route = createFileRoute("/settings/diagnostics")({
+  component: DiagnosticsSettingsPanel,
+});
diff --git a/apps/web/src/routes/settings.general.tsx b/apps/web/src/routes/settings.general.tsx
index 7fb503e0a25..c907a4915b1 100644
--- a/apps/web/src/routes/settings.general.tsx
+++ b/apps/web/src/routes/settings.general.tsx
@@ -2,6 +2,10 @@ import { createFileRoute } from "@tanstack/react-router";
 
 import { GeneralSettingsPanel } from "../components/settings/SettingsPanels";
 
+function SettingsGeneralRoute() {
+  return <GeneralSettingsPanel />;
+}
+
 export const Route = createFileRoute("/settings/general")({
-  component: GeneralSettingsPanel,
+  component: SettingsGeneralRoute,
 });
diff --git a/apps/web/src/routes/settings.keybindings.tsx b/apps/web/src/routes/settings.keybindings.tsx
new file mode 100644
index 00000000000..f4478407868
--- /dev/null
+++ b/apps/web/src/routes/settings.keybindings.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { KeybindingsSettingsPanel } from "../components/settings/KeybindingsSettings";
+
+export const Route = createFileRoute("/settings/keybindings")({
+  component: KeybindingsSettingsPanel,
+});
diff --git a/apps/web/src/routes/settings.providers.tsx b/apps/web/src/routes/settings.providers.tsx
new file mode 100644
index 00000000000..a7a86c2b50b
--- /dev/null
+++ b/apps/web/src/routes/settings.providers.tsx
@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { ProviderSettingsPanel } from "../components/settings/SettingsPanels";
+
+function SettingsProvidersRoute() {
+  return <ProviderSettingsPanel />;
+}
+
+export const Route = createFileRoute("/settings/providers")({
+  component: SettingsProvidersRoute,
+});
diff --git a/apps/web/src/routes/settings.source-control.tsx b/apps/web/src/routes/settings.source-control.tsx
new file mode 100644
index 00000000000..bb09b3fd33c
--- /dev/null
+++ b/apps/web/src/routes/settings.source-control.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { SourceControlSettingsPanel } from "../components/settings/SourceControlSettings";
+
+export const Route = createFileRoute("/settings/source-control")({
+  component: SourceControlSettingsPanel,
+});
diff --git a/apps/web/src/routes/settings.tsx b/apps/web/src/routes/settings.tsx
index 543b182c374..ec98e7ee363 100644
--- a/apps/web/src/routes/settings.tsx
+++ b/apps/web/src/routes/settings.tsx
@@ -1,28 +1,56 @@
 import { RotateCcwIcon } from "lucide-react";
-import { Outlet, createFileRoute, redirect } from "@tanstack/react-router";
-import { useEffect, useState } from "react";
-
 import {
-  ensurePrimaryEnvironmentReady,
-  resolveInitialServerAuthGateState,
-} from "../environments/primary";
+  Outlet,
+  createFileRoute,
+  redirect,
+  useCanGoBack,
+  useLocation,
+  useNavigate,
+} from "@tanstack/react-router";
+import { useCallback, useEffect, useState } from "react";
+
 import { useSettingsRestore } from "../components/settings/SettingsPanels";
 import { Button } from "../components/ui/button";
 import { SidebarInset, SidebarTrigger } from "../components/ui/sidebar";
 import { isElectron } from "../env";
 
+function RestoreDefaultsButton({ onRestored }: { onRestored: () => void }) {
+  const { changedSettingLabels, restoreDefaults } = useSettingsRestore(onRestored);
+
+  return (
+    <Button
+      size="xs"
+      variant="outline"
+      disabled={changedSettingLabels.length === 0}
+      onClick={() => void restoreDefaults()}
+    >
+      <RotateCcwIcon className="size-3.5" />
+      Restore defaults
+    </Button>
+  );
+}
+
 function SettingsContentLayout() {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const canGoBack = useCanGoBack();
   const [restoreSignal, setRestoreSignal] = useState(0);
-  const { changedSettingLabels, restoreDefaults } = useSettingsRestore(() =>
-    setRestoreSignal((value) => value + 1),
-  );
+  const showRestoreDefaults = location.pathname === "/settings/general";
+  const handleRestored = () => setRestoreSignal((value) => value + 1);
+  const navigateBackWithinApp = useCallback(() => {
+    if (canGoBack) {
+      window.history.back();
+      return;
+    }
+    void navigate({ to: "/" });
+  }, [canGoBack, navigate]);
 
   useEffect(() => {
     const onKeyDown = (event: KeyboardEvent) => {
       if (event.defaultPrevented) return;
       if (event.key === "Escape") {
         event.preventDefault();
-        window.history.back();
+        navigateBackWithinApp();
       }
     };
 
@@ -30,47 +58,35 @@ function SettingsContentLayout() {
     return () => {
       window.removeEventListener("keydown", onKeyDown);
     };
-  }, []);
+  }, [navigateBackWithinApp]);
 
   return (
     <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground isolate">
       <div className="flex min-h-0 min-w-0 flex-1 flex-col bg-background text-foreground">
         {!isElectron && (
           <header className="border-b border-border px-3 py-2 sm:px-5">
-            <div className="flex items-center gap-2">
+            <div className="flex min-h-7 items-center gap-2 sm:min-h-6">
               <SidebarTrigger className="size-7 shrink-0 md:hidden" />
               <span className="text-sm font-medium text-foreground">Settings</span>
-              <div className="ms-auto flex items-center gap-2">
-                <Button
-                  size="xs"
-                  variant="outline"
-                  disabled={changedSettingLabels.length === 0}
-                  onClick={() => void restoreDefaults()}
-                >
-                  <RotateCcwIcon className="size-3.5" />
-                  Restore defaults
-                </Button>
-              </div>
+              {showRestoreDefaults ? (
+                <div className="ms-auto flex items-center gap-2">
+                  <RestoreDefaultsButton onRestored={handleRestored} />
+                </div>
+              ) : null}
             </div>
           </header>
         )}
 
         {isElectron && (
-          <div className="drag-region flex h-[52px] shrink-0 items-center border-b border-border px-5">
+          <div className="drag-region flex h-[52px] shrink-0 items-center border-b border-border px-5 wco:h-[env(titlebar-area-height)] wco:pr-[calc(100vw-env(titlebar-area-width)-env(titlebar-area-x)+1em)]">
             <span className="text-xs font-medium tracking-wide text-muted-foreground/70">
               Settings
             </span>
-            <div className="ms-auto flex items-center gap-2">
-              <Button
-                size="xs"
-                variant="outline"
-                disabled={changedSettingLabels.length === 0}
-                onClick={() => void restoreDefaults()}
-              >
-                <RotateCcwIcon className="size-3.5" />
-                Restore defaults
-              </Button>
-            </div>
+            {showRestoreDefaults ? (
+              <div className="ms-auto flex items-center gap-2">
+                <RestoreDefaultsButton onRestored={handleRestored} />
+              </div>
+            ) : null}
           </div>
         )}
 
@@ -87,12 +103,11 @@ function SettingsRouteLayout() {
 }
 
 export const Route = createFileRoute("/settings")({
-  beforeLoad: async ({ location }) => {
-    const [, authGateState] = await Promise.all([
-      ensurePrimaryEnvironmentReady(),
-      resolveInitialServerAuthGateState(),
-    ]);
-    if (authGateState.status !== "authenticated") {
+  beforeLoad: async ({ context, location }) => {
+    if (
+      context.authGateState.status !== "authenticated" &&
+      context.authGateState.status !== "hosted-static"
+    ) {
       throw redirect({ to: "/pair", replace: true });
     }
 
diff --git a/apps/web/src/rpc/atomRegistry.tsx b/apps/web/src/rpc/atomRegistry.ts
similarity index 55%
rename from apps/web/src/rpc/atomRegistry.tsx
rename to apps/web/src/rpc/atomRegistry.ts
index 89385c9a75e..3fb12914a2f 100644
--- a/apps/web/src/rpc/atomRegistry.tsx
+++ b/apps/web/src/rpc/atomRegistry.ts
@@ -1,11 +1,11 @@
 import { RegistryContext } from "@effect/atom-react";
 import { AtomRegistry } from "effect/unstable/reactivity";
-import type { ReactNode } from "react";
+import { createElement } from "react";
 
 export let appAtomRegistry = AtomRegistry.make();
 
-export function AppAtomRegistryProvider({ children }: { readonly children: ReactNode }) {
-  return <RegistryContext.Provider value={appAtomRegistry}>{children}</RegistryContext.Provider>;
+export function AppAtomRegistryProvider({ children }: React.PropsWithChildren) {
+  return createElement(RegistryContext.Provider, { value: appAtomRegistry }, children);
 }
 
 export function resetAppAtomRegistryForTests() {
diff --git a/apps/web/src/rpc/protocol.ts b/apps/web/src/rpc/protocol.ts
index 5c5c51d8990..eb5caf2f7ab 100644
--- a/apps/web/src/rpc/protocol.ts
+++ b/apps/web/src/rpc/protocol.ts
@@ -1,5 +1,8 @@
 import { WsRpcGroup } from "@t3tools/contracts";
-import { Duration, Effect, Layer, Schedule } from "effect";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
 import { RpcClient, RpcSerialization } from "effect/unstable/rpc";
 import * as Socket from "effect/unstable/socket/Socket";
 
@@ -14,14 +17,45 @@ import {
   recordWsConnectionClosed,
   recordWsConnectionErrored,
   recordWsConnectionOpened,
+  type WsConnectionMetadata,
   WS_RECONNECT_MAX_RETRIES,
 } from "./wsConnectionState";
 
+export interface WsProtocolCloseContext {
+  readonly intentional: boolean;
+}
+
 export interface WsProtocolLifecycleHandlers {
+  readonly getConnectionLabel?: () => string | null;
+  readonly getVersionMismatchHint?: () => string | null;
+  readonly isCloseIntentional?: () => boolean;
+  readonly isActive?: () => boolean;
   readonly onAttempt?: (socketUrl: string) => void;
   readonly onOpen?: () => void;
+  readonly onHeartbeatPing?: () => void;
+  readonly onHeartbeatPong?: () => void;
+  readonly onHeartbeatTimeout?: () => void;
+  readonly onRequestStart?: (info: {
+    readonly id: string;
+    readonly tag: string;
+    readonly stream: boolean;
+  }) => void;
+  readonly onRequestChunk?: (info: {
+    readonly id: string;
+    readonly tag: string;
+    readonly chunkCount: number;
+  }) => void;
+  readonly onRequestExit?: (info: {
+    readonly id: string;
+    readonly tag: string;
+    readonly stream: boolean;
+  }) => void;
+  readonly onRequestInterrupt?: (info: { readonly id: string; readonly tag?: string }) => void;
   readonly onError?: (message: string) => void;
-  readonly onClose?: (details: { readonly code: number; readonly reason: string }) => void;
+  readonly onClose?: (
+    details: { readonly code: number; readonly reason: string },
+    context: WsProtocolCloseContext,
+  ) => void;
 }
 
 export const makeWsRpcProtocolClient = RpcClient.make(WsRpcGroup);
@@ -47,42 +81,77 @@ function resolveWsRpcSocketUrl(rawUrl: string): string {
   return resolved.toString();
 }
 
-function defaultLifecycleHandlers(): Required<WsProtocolLifecycleHandlers> {
+function resolveConnectionMetadata(handlers?: WsProtocolLifecycleHandlers): WsConnectionMetadata {
+  return {
+    connectionLabel: handlers?.getConnectionLabel?.() ?? null,
+    versionMismatchHint: handlers?.getVersionMismatchHint?.() ?? null,
+  };
+}
+
+type ComposedWsProtocolLifecycleHandlers = Required<
+  Pick<WsProtocolLifecycleHandlers, "isActive" | "onAttempt" | "onOpen" | "onError" | "onClose">
+>;
+
+function defaultLifecycleHandlers(
+  handlers?: WsProtocolLifecycleHandlers,
+): ComposedWsProtocolLifecycleHandlers {
   return {
-    onAttempt: recordWsConnectionAttempt,
-    onOpen: recordWsConnectionOpened,
+    isActive: () => true,
+    onAttempt: (socketUrl) => {
+      recordWsConnectionAttempt(socketUrl, resolveConnectionMetadata(handlers));
+    },
+    onOpen: () => {
+      recordWsConnectionOpened(resolveConnectionMetadata(handlers));
+    },
     onError: (message) => {
       clearAllTrackedRpcRequests();
-      recordWsConnectionErrored(message);
+      recordWsConnectionErrored(message, resolveConnectionMetadata(handlers));
     },
-    onClose: (details) => {
+    onClose: (details, context) => {
       clearAllTrackedRpcRequests();
-      recordWsConnectionClosed(details);
+      if (context.intentional) {
+        return;
+      }
+      recordWsConnectionClosed(details, resolveConnectionMetadata(handlers));
     },
   };
 }
 
 function composeLifecycleHandlers(
   handlers?: WsProtocolLifecycleHandlers,
-): Required<WsProtocolLifecycleHandlers> {
-  const defaults = defaultLifecycleHandlers();
+): ComposedWsProtocolLifecycleHandlers {
+  const defaults = defaultLifecycleHandlers(handlers);
+  const isActive = handlers?.isActive ?? defaults.isActive;
 
   return {
+    isActive,
     onAttempt: (socketUrl) => {
+      if (!isActive()) {
+        return;
+      }
       defaults.onAttempt(socketUrl);
       handlers?.onAttempt?.(socketUrl);
     },
     onOpen: () => {
+      if (!isActive()) {
+        return;
+      }
       defaults.onOpen();
       handlers?.onOpen?.();
     },
     onError: (message) => {
+      if (!isActive()) {
+        return;
+      }
       defaults.onError(message);
       handlers?.onError?.(message);
     },
-    onClose: (details) => {
-      defaults.onClose(details);
-      handlers?.onClose?.(details);
+    onClose: (details, context) => {
+      if (!isActive()) {
+        return;
+      }
+      defaults.onClose(details, context);
+      handlers?.onClose?.(details, context);
     },
   };
 }
@@ -128,10 +197,15 @@ export function createWsRpcProtocolLayer(
       socket.addEventListener(
         "close",
         (event) => {
-          lifecycle.onClose({
-            code: event.code,
-            reason: event.reason,
-          });
+          lifecycle.onClose(
+            {
+              code: event.code,
+              reason: event.reason,
+            },
+            {
+              intentional: handlers?.isCloseIntentional?.() ?? false,
+            },
+          );
         },
         { once: true },
       );
@@ -156,22 +230,99 @@ export function createWsRpcProtocolLayer(
         ...protocol,
         run: (clientId, writeResponse) =>
           protocol.run(clientId, (response) => {
-            if (response._tag === "Chunk" || response._tag === "Exit") {
-              acknowledgeRpcRequest(response.requestId);
-            } else if (response._tag === "ClientProtocolError" || response._tag === "Defect") {
+            if (response._tag === "ClientProtocolError" || response._tag === "Defect") {
               clearAllTrackedRpcRequests();
             }
             return writeResponse(response);
           }),
-        send: (clientId, request, transferables) => {
-          if (request._tag === "Request") {
-            trackRpcRequestSent(request.id, request.tag);
-          }
-          return protocol.send(clientId, request, transferables);
-        },
       }),
     ),
   );
+  const requestHooksLayer = Layer.succeed(
+    RpcClient.RequestHooks,
+    RpcClient.RequestHooks.of({
+      onRequestStart: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestStart?.({
+            id: String(info.id),
+            tag: info.tag,
+            stream: info.stream,
+          });
+          trackRpcRequestSent(String(info.id), info.tag);
+        }),
+      onRequestChunk: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestChunk?.({
+            id: String(info.id),
+            tag: info.tag,
+            chunkCount: info.chunkCount,
+          });
+          acknowledgeRpcRequest(String(info.id));
+        }),
+      onRequestExit: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestExit?.({
+            id: String(info.id),
+            tag: info.tag,
+            stream: info.stream,
+          });
+          acknowledgeRpcRequest(String(info.id));
+        }),
+      onRequestInterrupt: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestInterrupt?.({
+            id: String(info.id),
+            ...(info.tag === undefined ? {} : { tag: info.tag }),
+          });
+          acknowledgeRpcRequest(String(info.id));
+        }),
+    }),
+  );
+  const connectionHooksLayer = Layer.succeed(
+    RpcClient.ConnectionHooks,
+    RpcClient.ConnectionHooks.of({
+      onConnect: Effect.void,
+      onDisconnect: Effect.void,
+      onPing: Effect.sync(() => {
+        if (lifecycle.isActive()) {
+          handlers?.onHeartbeatPing?.();
+        }
+      }),
+      onPong: Effect.sync(() => {
+        if (lifecycle.isActive()) {
+          handlers?.onHeartbeatPong?.();
+        }
+      }),
+      onPingTimeout: Effect.sync(() => {
+        if (lifecycle.isActive()) {
+          clearAllTrackedRpcRequests();
+          recordWsConnectionErrored(
+            "WebSocket heartbeat timed out.",
+            resolveConnectionMetadata(handlers),
+          );
+          handlers?.onHeartbeatTimeout?.();
+        }
+      }),
+    }),
+  );
 
-  return protocolLayer.pipe(Layer.provide(Layer.mergeAll(socketLayer, RpcSerialization.layerJson)));
+  return Layer.mergeAll(
+    protocolLayer.pipe(
+      Layer.provide(Layer.mergeAll(socketLayer, RpcSerialization.layerJson, connectionHooksLayer)),
+    ),
+    requestHooksLayer,
+    connectionHooksLayer,
+  );
 }
diff --git a/apps/web/src/rpc/requestLatencyState.ts b/apps/web/src/rpc/requestLatencyState.ts
index d21e37b5298..ecc3b88275c 100644
--- a/apps/web/src/rpc/requestLatencyState.ts
+++ b/apps/web/src/rpc/requestLatencyState.ts
@@ -36,7 +36,7 @@ function getSlowRpcAckRequestsValue(): ReadonlyArray<SlowRpcAckRequest> {
 }
 
 function shouldTrackRpcAck(tag: string): boolean {
-  return !tag.startsWith("subscribe");
+  return !tag.includes("subscribe");
 }
 
 export function getSlowRpcAckRequests(): ReadonlyArray<SlowRpcAckRequest> {
diff --git a/apps/web/src/rpc/serverState.test.ts b/apps/web/src/rpc/serverState.test.ts
index a587fcd9f1e..506ef84eeaa 100644
--- a/apps/web/src/rpc/serverState.test.ts
+++ b/apps/web/src/rpc/serverState.test.ts
@@ -1,6 +1,8 @@
 import {
   DEFAULT_SERVER_SETTINGS,
   EnvironmentId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ProjectId,
   ThreadId,
   type ServerConfig,
@@ -8,10 +10,12 @@ import {
   type ServerLifecycleStreamEvent,
   type ServerProvider,
 } from "@t3tools/contracts";
+import { DEFAULT_RESOLVED_KEYBINDINGS } from "@t3tools/shared/keybindings";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
   getServerConfig,
+  getServerKeybindings,
   onProvidersUpdated,
   onServerConfigUpdated,
   onWelcome,
@@ -40,7 +44,8 @@ const configListeners = new Set<(event: ServerConfigStreamEvent) => void>();
 
 const defaultProviders: ReadonlyArray<ServerProvider> = [
   {
-    provider: "codex",
+    instanceId: ProviderInstanceId.make("codex"),
+    driver: ProviderDriverKind.make("codex"),
     enabled: true,
     installed: true,
     version: "0.116.0",
@@ -138,6 +143,11 @@ afterEach(() => {
 });
 
 describe("serverState", () => {
+  it("uses default keybindings before a server config snapshot is available", () => {
+    expect(getServerConfig()).toBeNull();
+    expect(getServerKeybindings()).toEqual(DEFAULT_RESOLVED_KEYBINDINGS);
+  });
+
   it("bootstraps the server config snapshot and replays it to late subscribers", async () => {
     serverApi.getConfig.mockResolvedValueOnce(baseServerConfig);
 
@@ -268,10 +278,25 @@ describe("serverState", () => {
       },
     ];
 
+    const nextKeybindings = [
+      {
+        command: "commandPalette.toggle",
+        shortcut: {
+          key: "p",
+          metaKey: false,
+          ctrlKey: false,
+          shiftKey: false,
+          altKey: false,
+          modKey: true,
+        },
+      },
+    ] as const;
+
     emitServerConfigEvent({
       version: 1,
       type: "keybindingsUpdated",
       payload: {
+        keybindings: nextKeybindings,
         issues: [{ kind: "keybindings.malformed-config", message: "bad json" }],
       },
     });
@@ -296,6 +321,7 @@ describe("serverState", () => {
     await waitFor(() => {
       expect(getServerConfig()).toEqual({
         ...baseServerConfig,
+        keybindings: nextKeybindings,
         issues: [{ kind: "keybindings.malformed-config", message: "bad json" }],
         providers: nextProviders,
         settings: {
diff --git a/apps/web/src/rpc/serverState.ts b/apps/web/src/rpc/serverState.ts
index 35472a96ed5..0a49ee1e225 100644
--- a/apps/web/src/rpc/serverState.ts
+++ b/apps/web/src/rpc/serverState.ts
@@ -10,6 +10,7 @@ import {
   type ServerProviderUpdatedPayload,
   type ServerSettings,
 } from "@t3tools/contracts";
+import { DEFAULT_RESOLVED_KEYBINDINGS } from "@t3tools/shared/keybindings";
 import { Atom } from "effect/unstable/reactivity";
 import { useCallback, useRef } from "react";
 
@@ -42,12 +43,12 @@ function toServerConfigUpdatedPayload(config: ServerConfig): ServerConfigUpdated
 }
 
 const EMPTY_AVAILABLE_EDITORS: ReadonlyArray<EditorId> = [];
-const EMPTY_KEYBINDINGS: ServerConfig["keybindings"] = [];
 const EMPTY_SERVER_PROVIDERS: ReadonlyArray<ServerProvider> = [];
 
 const selectAvailableEditors = (config: ServerConfig | null): ReadonlyArray<EditorId> =>
   config?.availableEditors ?? EMPTY_AVAILABLE_EDITORS;
-const selectKeybindings = (config: ServerConfig | null) => config?.keybindings ?? EMPTY_KEYBINDINGS;
+const selectKeybindings = (config: ServerConfig | null) =>
+  config?.keybindings ?? DEFAULT_RESOLVED_KEYBINDINGS;
 const selectKeybindingsConfigPath = (config: ServerConfig | null) =>
   config?.keybindingsConfigPath ?? null;
 const selectObservability = (config: ServerConfig | null) => config?.observability ?? null;
@@ -74,6 +75,10 @@ export function getServerConfig(): ServerConfig | null {
   return appAtomRegistry.get(serverConfigAtom);
 }
 
+export function getServerKeybindings(): ServerConfig["keybindings"] {
+  return selectKeybindings(getServerConfig());
+}
+
 export function getServerConfigUpdatedNotification(): ServerConfigUpdatedNotification | null {
   return appAtomRegistry.get(serverConfigUpdatedAtom);
 }
@@ -97,6 +102,7 @@ export function applyServerConfigEvent(event: ServerConfigStreamEvent): void {
       }
       const nextConfig = {
         ...latestServerConfig,
+        keybindings: event.payload.keybindings,
         issues: event.payload.issues,
       } satisfies ServerConfig;
       resolveServerConfig(nextConfig);
diff --git a/apps/web/src/rpc/wsConnectionState.test.ts b/apps/web/src/rpc/wsConnectionState.test.ts
index fb0b9d85aef..b836789609e 100644
--- a/apps/web/src/rpc/wsConnectionState.test.ts
+++ b/apps/web/src/rpc/wsConnectionState.test.ts
@@ -45,7 +45,9 @@ describe("wsConnectionState", () => {
   });
 
   it("schedules the next retry after a failed websocket attempt", () => {
-    recordWsConnectionAttempt("ws://localhost:3020/ws");
+    recordWsConnectionAttempt("ws://localhost:3020/ws", {
+      connectionLabel: "Remote Mac",
+    });
     recordWsConnectionErrored("Unable to connect to the T3 server WebSocket.");
 
     const firstRetryDelayMs = getWsReconnectDelayMsForRetry(0);
@@ -54,12 +56,42 @@ describe("wsConnectionState", () => {
     }
 
     expect(getWsConnectionStatus()).toMatchObject({
+      connectionLabel: "Remote Mac",
       nextRetryAt: new Date(Date.now() + firstRetryDelayMs).toISOString(),
       reconnectAttemptCount: 1,
       reconnectPhase: "waiting",
     });
   });
 
+  it("adds a version mismatch hint to websocket errors when metadata includes one", () => {
+    recordWsConnectionAttempt("ws://localhost:3020/ws", {
+      connectionLabel: "Remote Mac",
+    });
+    recordWsConnectionErrored("Unable to connect to the T3 server WebSocket.", {
+      versionMismatchHint: "Version mismatch. Try syncing the client and server.",
+    });
+
+    expect(getWsConnectionStatus()).toMatchObject({
+      lastError:
+        "Unable to connect to the T3 server WebSocket. Hint: Version mismatch. Try syncing the client and server.",
+    });
+  });
+
+  it("adds a version mismatch hint to websocket close reasons when metadata includes one", () => {
+    recordWsConnectionAttempt("ws://localhost:3020/ws");
+    recordWsConnectionOpened();
+    recordWsConnectionClosed(
+      { code: 1006, reason: "socket closed" },
+      {
+        versionMismatchHint: "Version mismatch. Try syncing the client and server.",
+      },
+    );
+
+    expect(getWsConnectionStatus()).toMatchObject({
+      closeReason: "socket closed Hint: Version mismatch. Try syncing the client and server.",
+    });
+  });
+
   it("marks the reconnect cycle as exhausted after the final attempt fails", () => {
     for (let attempt = 0; attempt < WS_RECONNECT_MAX_ATTEMPTS; attempt += 1) {
       recordWsConnectionAttempt("ws://localhost:3020/ws");
diff --git a/apps/web/src/rpc/wsConnectionState.ts b/apps/web/src/rpc/wsConnectionState.ts
index d3050a2b4c9..bc8a5a78607 100644
--- a/apps/web/src/rpc/wsConnectionState.ts
+++ b/apps/web/src/rpc/wsConnectionState.ts
@@ -16,6 +16,7 @@ export interface WsConnectionStatus {
   readonly attemptCount: number;
   readonly closeCode: number | null;
   readonly closeReason: string | null;
+  readonly connectionLabel: string | null;
   readonly connectedAt: string | null;
   readonly disconnectedAt: string | null;
   readonly hasConnected: boolean;
@@ -34,6 +35,7 @@ const INITIAL_WS_CONNECTION_STATUS = Object.freeze<WsConnectionStatus>({
   attemptCount: 0,
   closeCode: null,
   closeReason: null,
+  connectionLabel: null,
   connectedAt: null,
   disconnectedAt: null,
   hasConnected: false,
@@ -65,6 +67,16 @@ function updateWsConnectionStatus(
   return nextStatus;
 }
 
+export interface WsConnectionMetadata {
+  readonly connectionLabel?: string | null;
+  readonly versionMismatchHint?: string | null;
+}
+
+function normalizeConnectionLabel(label: string | null | undefined): string | null {
+  const normalized = label?.trim();
+  return normalized ? normalized : null;
+}
+
 export function getWsConnectionStatus(): WsConnectionStatus {
   return appAtomRegistry.get(wsConnectionStatusAtom);
 }
@@ -85,10 +97,15 @@ export function getWsConnectionUiState(status: WsConnectionStatus): WsConnection
   return "reconnecting";
 }
 
-export function recordWsConnectionAttempt(socketUrl: string): WsConnectionStatus {
+export function recordWsConnectionAttempt(
+  socketUrl: string,
+  metadata?: WsConnectionMetadata,
+): WsConnectionStatus {
+  const connectionLabel = normalizeConnectionLabel(metadata?.connectionLabel);
   return updateWsConnectionStatus((current) => ({
     ...current,
     attemptCount: current.attemptCount + 1,
+    connectionLabel: connectionLabel ?? current.connectionLabel,
     nextRetryAt: null,
     phase: "connecting",
     reconnectAttemptCount: current.phase === "connected" ? 1 : current.reconnectAttemptCount + 1,
@@ -97,11 +114,13 @@ export function recordWsConnectionAttempt(socketUrl: string): WsConnectionStatus
   }));
 }
 
-export function recordWsConnectionOpened(): WsConnectionStatus {
+export function recordWsConnectionOpened(metadata?: WsConnectionMetadata): WsConnectionStatus {
+  const connectionLabel = normalizeConnectionLabel(metadata?.connectionLabel);
   return updateWsConnectionStatus((current) => ({
     ...current,
     closeCode: null,
     closeReason: null,
+    connectionLabel: connectionLabel ?? current.connectionLabel,
     connectedAt: isoNow(),
     disconnectedAt: null,
     hasConnected: true,
@@ -112,24 +131,48 @@ export function recordWsConnectionOpened(): WsConnectionStatus {
   }));
 }
 
-export function recordWsConnectionErrored(message?: string | null): WsConnectionStatus {
+function appendHint(message: string | null | undefined, hint: string | null | undefined) {
+  const normalizedMessage = message?.trim();
+  const normalizedHint = hint?.trim();
+  if (!normalizedMessage) {
+    return normalizedHint ? `Hint: ${normalizedHint}` : null;
+  }
+  return normalizedHint ? `${normalizedMessage} Hint: ${normalizedHint}` : normalizedMessage;
+}
+
+export function recordWsConnectionErrored(
+  message?: string | null,
+  metadata?: WsConnectionMetadata,
+): WsConnectionStatus {
   return updateWsConnectionStatus((current) =>
     applyDisconnectState(current, {
-      lastError: message?.trim() ? message : current.lastError,
+      lastError:
+        appendHint(message, metadata?.versionMismatchHint) ??
+        appendHint(current.lastError, metadata?.versionMismatchHint),
       lastErrorAt: isoNow(),
     }),
   );
 }
 
-export function recordWsConnectionClosed(details?: {
-  readonly code?: number;
-  readonly reason?: string;
-}): WsConnectionStatus {
+export function recordWsConnectionClosed(
+  details?: {
+    readonly code?: number;
+    readonly reason?: string;
+  },
+  metadata?: WsConnectionMetadata,
+): WsConnectionStatus {
+  const connectionLabel = normalizeConnectionLabel(metadata?.connectionLabel);
   return updateWsConnectionStatus((current) =>
-    applyDisconnectState(current, {
-      closeCode: details?.code ?? current.closeCode,
-      closeReason: details?.reason?.trim() ? details.reason : current.closeReason,
-    }),
+    applyDisconnectState(
+      current,
+      {
+        closeCode: details?.code ?? current.closeCode,
+        closeReason:
+          appendHint(details?.reason, metadata?.versionMismatchHint) ??
+          appendHint(current.closeReason, metadata?.versionMismatchHint),
+      },
+      connectionLabel === null ? undefined : { connectionLabel },
+    ),
   );
 }
 
@@ -173,6 +216,7 @@ function applyDisconnectState(
   updates: Partial<
     Pick<WsConnectionStatus, "closeCode" | "closeReason" | "lastError" | "lastErrorAt">
   >,
+  metadata?: WsConnectionMetadata,
 ): WsConnectionStatus {
   const disconnectedAt = current.disconnectedAt ?? isoNow();
   const nextRetryDelayMs =
@@ -183,6 +227,7 @@ function applyDisconnectState(
   return {
     ...current,
     ...updates,
+    connectionLabel: normalizeConnectionLabel(metadata?.connectionLabel) ?? current.connectionLabel,
     disconnectedAt,
     nextRetryAt:
       nextRetryDelayMs === null
diff --git a/apps/web/src/rpc/wsRpcClient.test.ts b/apps/web/src/rpc/wsRpcClient.test.ts
index 56f39b1bd32..f1c0d06bc0b 100644
--- a/apps/web/src/rpc/wsRpcClient.test.ts
+++ b/apps/web/src/rpc/wsRpcClient.test.ts
@@ -1,7 +1,7 @@
 import type {
-  GitStatusLocalResult,
-  GitStatusRemoteResult,
-  GitStatusStreamEvent,
+  VcsStatusLocalResult,
+  VcsStatusRemoteResult,
+  VcsStatusStreamEvent,
 } from "@t3tools/contracts";
 import { describe, expect, it, vi } from "vitest";
 
@@ -18,16 +18,16 @@ vi.mock("./wsTransport", () => ({
 import { createWsRpcClient } from "./wsRpcClient";
 import { type WsTransport } from "./wsTransport";
 
-const baseLocalStatus: GitStatusLocalResult = {
+const baseLocalStatus: VcsStatusLocalResult = {
   isRepo: true,
-  hasOriginRemote: true,
-  isDefaultBranch: false,
-  branch: "feature/demo",
+  hasPrimaryRemote: true,
+  isDefaultRef: false,
+  refName: "feature/demo",
   hasWorkingTreeChanges: false,
   workingTree: { files: [], insertions: 0, deletions: 0 },
 };
 
-const baseRemoteStatus: GitStatusRemoteResult = {
+const baseRemoteStatus: VcsStatusRemoteResult = {
   hasUpstream: true,
   aheadCount: 0,
   behindCount: 0,
@@ -35,7 +35,7 @@ const baseRemoteStatus: GitStatusRemoteResult = {
 };
 
 describe("wsRpcClient", () => {
-  it("reduces git status stream events into flat status snapshots", () => {
+  it("reduces vcs status stream events into flat status snapshots", () => {
     const subscribe = vi.fn(<TValue>(_connect: unknown, listener: (value: TValue) => void) => {
       for (const event of [
         {
@@ -54,7 +54,7 @@ describe("wsRpcClient", () => {
             hasWorkingTreeChanges: true,
           },
         },
-      ] satisfies GitStatusStreamEvent[]) {
+      ] satisfies VcsStatusStreamEvent[]) {
         listener(event as TValue);
       }
       return () => undefined;
@@ -74,7 +74,7 @@ describe("wsRpcClient", () => {
     const client = createWsRpcClient(transport as unknown as WsTransport);
     const listener = vi.fn();
 
-    client.git.onStatus({ cwd: "/repo" }, listener);
+    client.vcs.onStatus({ cwd: "/repo" }, listener);
 
     expect(listener.mock.calls).toEqual([
       [
@@ -83,6 +83,7 @@ describe("wsRpcClient", () => {
           hasUpstream: false,
           aheadCount: 0,
           behindCount: 0,
+          aheadOfDefaultCount: 0,
           pr: null,
         },
       ],
diff --git a/apps/web/src/rpc/wsRpcClient.ts b/apps/web/src/rpc/wsRpcClient.ts
index b714889b7aa..c730ddc4bb2 100644
--- a/apps/web/src/rpc/wsRpcClient.ts
+++ b/apps/web/src/rpc/wsRpcClient.ts
@@ -2,15 +2,16 @@ import {
   type GitActionProgressEvent,
   type GitRunStackedActionInput,
   type GitRunStackedActionResult,
-  type GitStatusResult,
-  type GitStatusStreamEvent,
+  type VcsStatusResult,
+  type VcsStatusStreamEvent,
   type LocalApi,
   ORCHESTRATION_WS_METHODS,
   type ServerSettingsPatch,
   WS_METHODS,
 } from "@t3tools/contracts";
 import { applyGitStatusStreamEvent } from "@t3tools/shared/git";
-import { Effect, Stream } from "effect";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
 
 import { type WsRpcProtocolClient } from "./protocol";
 import { resetWsReconnectBackoff } from "./wsConnectionState";
@@ -39,6 +40,15 @@ type RpcStreamMethod<TTag extends RpcTag> =
     ? (listener: (event: TEvent) => void, options?: StreamSubscriptionOptions) => () => void
     : never;
 
+type RpcInputStreamMethod<TTag extends RpcTag> =
+  RpcMethod<TTag> extends (input: any, options?: any) => Stream.Stream<infer TEvent, any, any>
+    ? (
+        input: RpcInput<TTag>,
+        listener: (event: TEvent) => void,
+        options?: StreamSubscriptionOptions,
+      ) => () => void
+    : never;
+
 interface GitRunStackedActionOptions {
   readonly onProgress?: (event: GitActionProgressEvent) => void;
 }
@@ -46,6 +56,7 @@ interface GitRunStackedActionOptions {
 export interface WsRpcClient {
   readonly dispose: () => Promise<void>;
   readonly reconnect: () => Promise<void>;
+  readonly isHeartbeatFresh: () => boolean;
   readonly terminal: {
     readonly open: RpcUnaryMethod<typeof WS_METHODS.terminalOpen>;
     readonly write: RpcUnaryMethod<typeof WS_METHODS.terminalWrite>;
@@ -59,30 +70,43 @@ export interface WsRpcClient {
     readonly searchEntries: RpcUnaryMethod<typeof WS_METHODS.projectsSearchEntries>;
     readonly writeFile: RpcUnaryMethod<typeof WS_METHODS.projectsWriteFile>;
   };
+  readonly filesystem: {
+    readonly browse: RpcUnaryMethod<typeof WS_METHODS.filesystemBrowse>;
+  };
+  readonly sourceControl: {
+    readonly lookupRepository: RpcUnaryMethod<typeof WS_METHODS.sourceControlLookupRepository>;
+    readonly cloneRepository: RpcUnaryMethod<typeof WS_METHODS.sourceControlCloneRepository>;
+    readonly publishRepository: RpcUnaryMethod<typeof WS_METHODS.sourceControlPublishRepository>;
+  };
   readonly shell: {
     readonly openInEditor: (input: {
       readonly cwd: Parameters<LocalApi["shell"]["openInEditor"]>[0];
       readonly editor: Parameters<LocalApi["shell"]["openInEditor"]>[1];
     }) => ReturnType<LocalApi["shell"]["openInEditor"]>;
   };
-  readonly git: {
-    readonly pull: RpcUnaryMethod<typeof WS_METHODS.gitPull>;
-    readonly refreshStatus: RpcUnaryMethod<typeof WS_METHODS.gitRefreshStatus>;
+  readonly vcs: {
+    readonly pull: RpcUnaryMethod<typeof WS_METHODS.vcsPull>;
+    readonly refreshStatus: RpcUnaryMethod<typeof WS_METHODS.vcsRefreshStatus>;
     readonly onStatus: (
-      input: RpcInput<typeof WS_METHODS.subscribeGitStatus>,
-      listener: (status: GitStatusResult) => void,
+      input: RpcInput<typeof WS_METHODS.subscribeVcsStatus>,
+      listener: (status: VcsStatusResult) => void,
       options?: StreamSubscriptionOptions,
     ) => () => void;
+    readonly listRefs: RpcUnaryMethod<typeof WS_METHODS.vcsListRefs>;
+    readonly createWorktree: RpcUnaryMethod<typeof WS_METHODS.vcsCreateWorktree>;
+    readonly removeWorktree: RpcUnaryMethod<typeof WS_METHODS.vcsRemoveWorktree>;
+    readonly createRef: RpcUnaryMethod<typeof WS_METHODS.vcsCreateRef>;
+    readonly switchRef: RpcUnaryMethod<typeof WS_METHODS.vcsSwitchRef>;
+    readonly init: RpcUnaryMethod<typeof WS_METHODS.vcsInit>;
+  };
+  /**
+   * Git-specific workflows. Local repository mechanics live under `vcs`.
+   */
+  readonly git: {
     readonly runStackedAction: (
       input: GitRunStackedActionInput,
       options?: GitRunStackedActionOptions,
     ) => Promise<GitRunStackedActionResult>;
-    readonly listBranches: RpcUnaryMethod<typeof WS_METHODS.gitListBranches>;
-    readonly createWorktree: RpcUnaryMethod<typeof WS_METHODS.gitCreateWorktree>;
-    readonly removeWorktree: RpcUnaryMethod<typeof WS_METHODS.gitRemoveWorktree>;
-    readonly createBranch: RpcUnaryMethod<typeof WS_METHODS.gitCreateBranch>;
-    readonly checkout: RpcUnaryMethod<typeof WS_METHODS.gitCheckout>;
-    readonly init: RpcUnaryMethod<typeof WS_METHODS.gitInit>;
     readonly resolvePullRequest: RpcUnaryMethod<typeof WS_METHODS.gitResolvePullRequest>;
     readonly preparePullRequestThread: RpcUnaryMethod<
       typeof WS_METHODS.gitPreparePullRequestThread
@@ -90,23 +114,44 @@ export interface WsRpcClient {
   };
   readonly server: {
     readonly getConfig: RpcUnaryNoArgMethod<typeof WS_METHODS.serverGetConfig>;
-    readonly refreshProviders: RpcUnaryNoArgMethod<typeof WS_METHODS.serverRefreshProviders>;
+    /**
+     * Refresh provider snapshots. Pass `{ instanceId }` to refresh a single
+     * configured instance; pass no argument (or `{}`) to refresh all.
+     */
+    readonly refreshProviders: (
+      input?: RpcInput<typeof WS_METHODS.serverRefreshProviders>,
+    ) => ReturnType<RpcUnaryMethod<typeof WS_METHODS.serverRefreshProviders>>;
+    readonly updateProvider: RpcUnaryMethod<typeof WS_METHODS.serverUpdateProvider>;
     readonly upsertKeybinding: RpcUnaryMethod<typeof WS_METHODS.serverUpsertKeybinding>;
+    readonly removeKeybinding: RpcUnaryMethod<typeof WS_METHODS.serverRemoveKeybinding>;
     readonly getSettings: RpcUnaryNoArgMethod<typeof WS_METHODS.serverGetSettings>;
     readonly updateSettings: (
       patch: ServerSettingsPatch,
     ) => ReturnType<RpcUnaryMethod<typeof WS_METHODS.serverUpdateSettings>>;
+    readonly discoverSourceControl: RpcUnaryNoArgMethod<
+      typeof WS_METHODS.serverDiscoverSourceControl
+    >;
+    readonly getTraceDiagnostics: RpcUnaryNoArgMethod<typeof WS_METHODS.serverGetTraceDiagnostics>;
+    readonly getProcessDiagnostics: RpcUnaryNoArgMethod<
+      typeof WS_METHODS.serverGetProcessDiagnostics
+    >;
+    readonly getProcessResourceHistory: RpcUnaryMethod<
+      typeof WS_METHODS.serverGetProcessResourceHistory
+    >;
+    readonly signalProcess: RpcUnaryMethod<typeof WS_METHODS.serverSignalProcess>;
     readonly subscribeConfig: RpcStreamMethod<typeof WS_METHODS.subscribeServerConfig>;
     readonly subscribeLifecycle: RpcStreamMethod<typeof WS_METHODS.subscribeServerLifecycle>;
     readonly subscribeAuthAccess: RpcStreamMethod<typeof WS_METHODS.subscribeAuthAccess>;
   };
   readonly orchestration: {
-    readonly getSnapshot: RpcUnaryNoArgMethod<typeof ORCHESTRATION_WS_METHODS.getSnapshot>;
     readonly dispatchCommand: RpcUnaryMethod<typeof ORCHESTRATION_WS_METHODS.dispatchCommand>;
     readonly getTurnDiff: RpcUnaryMethod<typeof ORCHESTRATION_WS_METHODS.getTurnDiff>;
     readonly getFullThreadDiff: RpcUnaryMethod<typeof ORCHESTRATION_WS_METHODS.getFullThreadDiff>;
-    readonly replayEvents: RpcUnaryMethod<typeof ORCHESTRATION_WS_METHODS.replayEvents>;
-    readonly onDomainEvent: RpcStreamMethod<typeof WS_METHODS.subscribeOrchestrationDomainEvents>;
+    readonly getArchivedShellSnapshot: RpcUnaryNoArgMethod<
+      typeof ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot
+    >;
+    readonly subscribeShell: RpcStreamMethod<typeof ORCHESTRATION_WS_METHODS.subscribeShell>;
+    readonly subscribeThread: RpcInputStreamMethod<typeof ORCHESTRATION_WS_METHODS.subscribeThread>;
   };
 }
 
@@ -117,6 +162,7 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
       resetWsReconnectBackoff();
       await transport.reconnect();
     },
+    isHeartbeatFresh: () => transport.isHeartbeatFresh(),
     terminal: {
       open: (input) => transport.request((client) => client[WS_METHODS.terminalOpen](input)),
       write: (input) => transport.request((client) => client[WS_METHODS.terminalWrite](input)),
@@ -125,11 +171,10 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
       restart: (input) => transport.request((client) => client[WS_METHODS.terminalRestart](input)),
       close: (input) => transport.request((client) => client[WS_METHODS.terminalClose](input)),
       onEvent: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeTerminalEvents]({}),
-          listener,
-          options,
-        ),
+        transport.subscribe((client) => client[WS_METHODS.subscribeTerminalEvents]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeTerminalEvents,
+        }),
     },
     projects: {
       searchEntries: (input) =>
@@ -137,25 +182,46 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
       writeFile: (input) =>
         transport.request((client) => client[WS_METHODS.projectsWriteFile](input)),
     },
+    filesystem: {
+      browse: (input) => transport.request((client) => client[WS_METHODS.filesystemBrowse](input)),
+    },
+    sourceControl: {
+      lookupRepository: (input) =>
+        transport.request((client) => client[WS_METHODS.sourceControlLookupRepository](input)),
+      cloneRepository: (input) =>
+        transport.request((client) => client[WS_METHODS.sourceControlCloneRepository](input)),
+      publishRepository: (input) =>
+        transport.request((client) => client[WS_METHODS.sourceControlPublishRepository](input)),
+    },
     shell: {
       openInEditor: (input) =>
         transport.request((client) => client[WS_METHODS.shellOpenInEditor](input)),
     },
-    git: {
-      pull: (input) => transport.request((client) => client[WS_METHODS.gitPull](input)),
+    vcs: {
+      pull: (input) => transport.request((client) => client[WS_METHODS.vcsPull](input)),
       refreshStatus: (input) =>
-        transport.request((client) => client[WS_METHODS.gitRefreshStatus](input)),
+        transport.request((client) => client[WS_METHODS.vcsRefreshStatus](input)),
       onStatus: (input, listener, options) => {
-        let current: GitStatusResult | null = null;
+        let current: VcsStatusResult | null = null;
         return transport.subscribe(
-          (client) => client[WS_METHODS.subscribeGitStatus](input),
-          (event: GitStatusStreamEvent) => {
+          (client) => client[WS_METHODS.subscribeVcsStatus](input),
+          (event: VcsStatusStreamEvent) => {
             current = applyGitStatusStreamEvent(current, event);
             listener(current);
           },
-          options,
+          { ...options, tag: WS_METHODS.subscribeVcsStatus },
         );
       },
+      listRefs: (input) => transport.request((client) => client[WS_METHODS.vcsListRefs](input)),
+      createWorktree: (input) =>
+        transport.request((client) => client[WS_METHODS.vcsCreateWorktree](input)),
+      removeWorktree: (input) =>
+        transport.request((client) => client[WS_METHODS.vcsRemoveWorktree](input)),
+      createRef: (input) => transport.request((client) => client[WS_METHODS.vcsCreateRef](input)),
+      switchRef: (input) => transport.request((client) => client[WS_METHODS.vcsSwitchRef](input)),
+      init: (input) => transport.request((client) => client[WS_METHODS.vcsInit](input)),
+    },
+    git: {
       runStackedAction: async (input, options) => {
         let result: GitRunStackedActionResult | null = null;
 
@@ -175,16 +241,6 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
 
         throw new Error("Git action stream completed without a final result.");
       },
-      listBranches: (input) =>
-        transport.request((client) => client[WS_METHODS.gitListBranches](input)),
-      createWorktree: (input) =>
-        transport.request((client) => client[WS_METHODS.gitCreateWorktree](input)),
-      removeWorktree: (input) =>
-        transport.request((client) => client[WS_METHODS.gitRemoveWorktree](input)),
-      createBranch: (input) =>
-        transport.request((client) => client[WS_METHODS.gitCreateBranch](input)),
-      checkout: (input) => transport.request((client) => client[WS_METHODS.gitCheckout](input)),
-      init: (input) => transport.request((client) => client[WS_METHODS.gitInit](input)),
       resolvePullRequest: (input) =>
         transport.request((client) => client[WS_METHODS.gitResolvePullRequest](input)),
       preparePullRequestThread: (input) =>
@@ -192,50 +248,75 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
     },
     server: {
       getConfig: () => transport.request((client) => client[WS_METHODS.serverGetConfig]({})),
-      refreshProviders: () =>
-        transport.request((client) => client[WS_METHODS.serverRefreshProviders]({})),
+      refreshProviders: (input) =>
+        transport.request((client) => client[WS_METHODS.serverRefreshProviders](input ?? {})),
+      updateProvider: (input) =>
+        transport.request((client) => client[WS_METHODS.serverUpdateProvider](input)),
       upsertKeybinding: (input) =>
         transport.request((client) => client[WS_METHODS.serverUpsertKeybinding](input)),
+      removeKeybinding: (input) =>
+        transport.request((client) => client[WS_METHODS.serverRemoveKeybinding](input)),
       getSettings: () => transport.request((client) => client[WS_METHODS.serverGetSettings]({})),
       updateSettings: (patch) =>
         transport.request((client) => client[WS_METHODS.serverUpdateSettings]({ patch })),
-      subscribeConfig: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeServerConfig]({}),
-          listener,
-          options,
+      discoverSourceControl: () =>
+        transport.request((client) => client[WS_METHODS.serverDiscoverSourceControl]({})),
+      getTraceDiagnostics: () =>
+        transport.request((client) =>
+          client[WS_METHODS.serverGetTraceDiagnostics]({}).pipe(Effect.withTracerEnabled(false)),
         ),
-      subscribeLifecycle: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeServerLifecycle]({}),
-          listener,
-          options,
+      getProcessDiagnostics: () =>
+        transport.request((client) =>
+          client[WS_METHODS.serverGetProcessDiagnostics]({}).pipe(Effect.withTracerEnabled(false)),
         ),
-      subscribeAuthAccess: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeAuthAccess]({}),
-          listener,
-          options,
+      getProcessResourceHistory: (input) =>
+        transport.request((client) =>
+          client[WS_METHODS.serverGetProcessResourceHistory](input).pipe(
+            Effect.withTracerEnabled(false),
+          ),
+        ),
+      signalProcess: (input) =>
+        transport.request((client) =>
+          client[WS_METHODS.serverSignalProcess](input).pipe(Effect.withTracerEnabled(false)),
         ),
+      subscribeConfig: (listener, options) =>
+        transport.subscribe((client) => client[WS_METHODS.subscribeServerConfig]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeServerConfig,
+        }),
+      subscribeLifecycle: (listener, options) =>
+        transport.subscribe((client) => client[WS_METHODS.subscribeServerLifecycle]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeServerLifecycle,
+        }),
+      subscribeAuthAccess: (listener, options) =>
+        transport.subscribe((client) => client[WS_METHODS.subscribeAuthAccess]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeAuthAccess,
+        }),
     },
     orchestration: {
-      getSnapshot: () =>
-        transport.request((client) => client[ORCHESTRATION_WS_METHODS.getSnapshot]({})),
       dispatchCommand: (input) =>
         transport.request((client) => client[ORCHESTRATION_WS_METHODS.dispatchCommand](input)),
       getTurnDiff: (input) =>
         transport.request((client) => client[ORCHESTRATION_WS_METHODS.getTurnDiff](input)),
       getFullThreadDiff: (input) =>
         transport.request((client) => client[ORCHESTRATION_WS_METHODS.getFullThreadDiff](input)),
-      replayEvents: (input) =>
-        transport
-          .request((client) => client[ORCHESTRATION_WS_METHODS.replayEvents](input))
-          .then((events) => [...events]),
-      onDomainEvent: (listener, options) =>
+      getArchivedShellSnapshot: () =>
+        transport.request((client) =>
+          client[ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot]({}),
+        ),
+      subscribeShell: (listener, options) =>
+        transport.subscribe(
+          (client) => client[ORCHESTRATION_WS_METHODS.subscribeShell]({}),
+          listener,
+          { ...options, tag: ORCHESTRATION_WS_METHODS.subscribeShell },
+        ),
+      subscribeThread: (input, listener, options) =>
         transport.subscribe(
-          (client) => client[WS_METHODS.subscribeOrchestrationDomainEvents]({}),
+          (client) => client[ORCHESTRATION_WS_METHODS.subscribeThread](input),
           listener,
-          options,
+          { ...options, tag: ORCHESTRATION_WS_METHODS.subscribeThread },
         ),
     },
   };
diff --git a/apps/web/src/rpc/wsTransport.test.ts b/apps/web/src/rpc/wsTransport.test.ts
index 2863bb0225a..aeb5496f516 100644
--- a/apps/web/src/rpc/wsTransport.test.ts
+++ b/apps/web/src/rpc/wsTransport.test.ts
@@ -1,5 +1,6 @@
-import { DEFAULT_SERVER_SETTINGS, WS_METHODS } from "@t3tools/contracts";
-import { Stream } from "effect";
+import { DEFAULT_SERVER_SETTINGS, ServerSettings, WS_METHODS } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
@@ -18,6 +19,8 @@ import {
 } from "../rpc/wsConnectionState";
 import { WsTransport } from "./wsTransport";
 
+const encodeServerSettings = Schema.encodeSync(ServerSettings);
+
 type WsEventType = "open" | "message" | "close" | "error";
 type WsEvent = { code?: number; data?: unknown; reason?: string; type?: string };
 type WsListener = (event?: WsEvent) => void;
@@ -284,10 +287,15 @@ describe("WsTransport", () => {
     socket.close(1012, "service restart");
 
     await waitFor(() => {
-      expect(onClose).toHaveBeenCalledWith({
-        code: 1012,
-        reason: "service restart",
-      });
+      expect(onClose).toHaveBeenCalledWith(
+        {
+          code: 1012,
+          reason: "service restart",
+        },
+        {
+          intentional: false,
+        },
+      );
       expect(getWsConnectionStatus()).toMatchObject({
         attemptCount: 2,
         closeReason: "service restart",
@@ -298,6 +306,38 @@ describe("WsTransport", () => {
     await transport.dispose();
   });
 
+  it("does not report an intentional dispose as a reconnectable disconnect", async () => {
+    const onClose = vi.fn();
+    const transport = createTransport("ws://localhost:3020", {
+      getConnectionLabel: () => "Remote Mac mini",
+      onClose,
+    });
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(1);
+    });
+
+    const socket = getSocket();
+    socket.open();
+
+    await waitFor(() => {
+      expect(getWsConnectionStatus()).toMatchObject({
+        connectionLabel: "Remote Mac mini",
+        hasConnected: true,
+        phase: "connected",
+      });
+    });
+
+    await transport.dispose();
+
+    expect(onClose).not.toHaveBeenCalled();
+    expect(getWsConnectionStatus()).toMatchObject({
+      connectionLabel: "Remote Mac mini",
+      phase: "connected",
+      reconnectPhase: "idle",
+    });
+  });
+
   it("reconnects the websocket session without disposing the transport", async () => {
     const transport = createTransport("ws://localhost:3020");
 
@@ -324,6 +364,11 @@ describe("WsTransport", () => {
     const secondSocket = getSocket();
     expect(secondSocket).not.toBe(firstSocket);
     expect(firstSocket.readyState).toBe(MockWebSocket.CLOSED);
+    expect(getWsConnectionStatus()).toMatchObject({
+      closeCode: null,
+      closeReason: null,
+      phase: "connecting",
+    });
 
     const requestPromise = transport.request((client) =>
       client[WS_METHODS.serverUpsertKeybinding]({
@@ -361,6 +406,92 @@ describe("WsTransport", () => {
     await transport.dispose();
   });
 
+  it("ignores stale socket lifecycle events after a reconnect starts a new session", async () => {
+    const onClose = vi.fn();
+    const transport = createTransport("ws://localhost:3020", { onClose });
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(1);
+    });
+
+    const firstSocket = getSocket();
+    firstSocket.open();
+
+    await waitFor(() => {
+      expect(getWsConnectionStatus()).toMatchObject({
+        hasConnected: true,
+        phase: "connected",
+      });
+    });
+
+    await transport.reconnect();
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(2);
+    });
+
+    expect(onClose).not.toHaveBeenCalled();
+    expect(getWsConnectionStatus()).toMatchObject({
+      closeCode: null,
+      closeReason: null,
+      phase: "connecting",
+    });
+
+    const secondSocket = getSocket();
+    secondSocket.open();
+
+    await waitFor(() => {
+      expect(getWsConnectionStatus()).toMatchObject({
+        phase: "connected",
+      });
+    });
+
+    firstSocket.close(1006, "stale close");
+
+    expect(onClose).not.toHaveBeenCalled();
+    expect(getWsConnectionStatus()).toMatchObject({
+      closeCode: null,
+      closeReason: null,
+      phase: "connected",
+    });
+
+    await transport.dispose();
+  });
+
+  it("ignores stale socket close events after the transport is disposed", async () => {
+    const onClose = vi.fn();
+    const transport = createTransport("ws://localhost:3020", { onClose });
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(1);
+    });
+
+    const firstSocket = getSocket();
+    firstSocket.open();
+
+    await waitFor(() => {
+      expect(getWsConnectionStatus()).toMatchObject({
+        hasConnected: true,
+        phase: "connected",
+      });
+    });
+
+    await transport.reconnect();
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(2);
+    });
+
+    const secondSocket = getSocket();
+    secondSocket.open();
+    await transport.dispose();
+
+    onClose.mockClear();
+    firstSocket.close(1006, "stale close after dispose");
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
   it("marks unary requests as slow until the first server ack arrives", async () => {
     const slowAckThresholdMs = 25;
     setSlowRpcAckThresholdMsForTests(slowAckThresholdMs);
@@ -417,6 +548,56 @@ describe("WsTransport", () => {
     await transport.dispose();
   }, 5_000);
 
+  it("clears slow unary request tracking when the transport reconnects", async () => {
+    const slowAckThresholdMs = 25;
+    setSlowRpcAckThresholdMsForTests(slowAckThresholdMs);
+    const transport = createTransport("ws://localhost:3020");
+
+    const requestPromise = transport.request((client) =>
+      client[WS_METHODS.serverUpsertKeybinding]({
+        command: "terminal.toggle",
+        key: "ctrl+k",
+      }),
+    );
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(1);
+    });
+
+    const firstSocket = getSocket();
+    firstSocket.open();
+
+    await waitFor(() => {
+      expect(firstSocket.sent).toHaveLength(1);
+    });
+
+    const firstRequest = JSON.parse(firstSocket.sent[0] ?? "{}") as { id: string };
+
+    await waitFor(() => {
+      expect(getSlowRpcAckRequests()).toMatchObject([
+        {
+          requestId: firstRequest.id,
+          tag: WS_METHODS.serverUpsertKeybinding,
+        },
+      ]);
+    }, 1_000);
+
+    void requestPromise.catch(() => undefined);
+
+    await transport.reconnect();
+
+    expect(getSlowRpcAckRequests()).toEqual([]);
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(2);
+    });
+
+    const secondSocket = getSocket();
+    secondSocket.open();
+
+    await transport.dispose();
+  }, 5_000);
+
   it("sends unary RPC requests and resolves successful exits", async () => {
     const transport = createTransport("ws://localhost:3020");
 
@@ -639,6 +820,115 @@ describe("WsTransport", () => {
     await transport.dispose();
   });
 
+  it("re-subscribes live stream listeners after an explicit transport reconnect", async () => {
+    const transport = createTransport("ws://localhost:3020");
+    const listener = vi.fn();
+    const onResubscribe = vi.fn();
+
+    const unsubscribe = transport.subscribe(
+      (client) => client[WS_METHODS.subscribeServerLifecycle]({}),
+      listener,
+      { onResubscribe },
+    );
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(1);
+    });
+
+    const firstSocket = getSocket();
+    firstSocket.open();
+
+    await waitFor(() => {
+      expect(firstSocket.sent).toHaveLength(1);
+    });
+
+    const firstRequest = JSON.parse(firstSocket.sent[0] ?? "{}") as { id: string };
+    const firstEvent = {
+      version: 1,
+      sequence: 1,
+      type: "welcome",
+      payload: {
+        environment: {
+          environmentId: "environment-local",
+          label: "Local environment",
+          platform: { os: "darwin", arch: "arm64" },
+          serverVersion: "0.0.0-test",
+          capabilities: { repositoryIdentity: true },
+        },
+        cwd: "/tmp/one",
+        projectName: "one",
+      },
+    };
+
+    firstSocket.serverMessage(
+      JSON.stringify({
+        _tag: "Chunk",
+        requestId: firstRequest.id,
+        values: [firstEvent],
+      }),
+    );
+
+    await waitFor(() => {
+      expect(listener).toHaveBeenLastCalledWith(firstEvent);
+    });
+
+    await transport.reconnect();
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(2);
+    });
+
+    const secondSocket = getSocket();
+    expect(secondSocket).not.toBe(firstSocket);
+    expect(firstSocket.readyState).toBe(MockWebSocket.CLOSED);
+
+    secondSocket.open();
+
+    await waitFor(() => {
+      expect(secondSocket.sent).toHaveLength(1);
+    });
+
+    const secondRequest = JSON.parse(secondSocket.sent[0] ?? "{}") as {
+      id: string;
+      tag: string;
+    };
+    expect(secondRequest.tag).toBe(WS_METHODS.subscribeServerLifecycle);
+    expect(secondRequest.id).not.toBe(firstRequest.id);
+    expect(onResubscribe).toHaveBeenCalledOnce();
+
+    const secondEvent = {
+      version: 1,
+      sequence: 2,
+      type: "welcome",
+      payload: {
+        environment: {
+          environmentId: "environment-local",
+          label: "Local environment",
+          platform: { os: "darwin", arch: "arm64" },
+          serverVersion: "0.0.0-test",
+          capabilities: { repositoryIdentity: true },
+        },
+        cwd: "/tmp/two",
+        projectName: "two",
+      },
+    };
+
+    secondSocket.serverMessage(
+      JSON.stringify({
+        _tag: "Chunk",
+        requestId: secondRequest.id,
+        values: [secondEvent],
+      }),
+    );
+
+    await waitFor(() => {
+      expect(listener).toHaveBeenLastCalledWith(secondEvent);
+    });
+
+    unsubscribe();
+    await transport.dispose();
+  });
+
   it("does not fire onResubscribe when the first stream attempt exits before any value", async () => {
     const transport = createTransport("ws://localhost:3020");
     const listener = vi.fn();
@@ -935,7 +1225,7 @@ describe("WsTransport", () => {
         requestId: requestMessage.id,
         exit: {
           _tag: "Success",
-          value: DEFAULT_SERVER_SETTINGS,
+          value: encodeServerSettings(DEFAULT_SERVER_SETTINGS),
         },
       }),
     );
diff --git a/apps/web/src/rpc/wsTransport.ts b/apps/web/src/rpc/wsTransport.ts
index 851cc5046cb..9e8cc821364 100644
--- a/apps/web/src/rpc/wsTransport.ts
+++ b/apps/web/src/rpc/wsTransport.ts
@@ -1,17 +1,16 @@
-import {
-  Cause,
-  Duration,
-  Effect,
-  Exit,
-  Layer,
-  ManagedRuntime,
-  Option,
-  Scope,
-  Stream,
-} from "effect";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Option from "effect/Option";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import { RpcClient } from "effect/unstable/rpc";
 
 import { ClientTracingLive } from "../observability/clientTracing";
+import { clearAllTrackedRpcRequests } from "./requestLatencyState";
 import {
   createWsRpcProtocolLayer,
   makeWsRpcProtocolClient,
@@ -24,6 +23,7 @@ import { isTransportConnectionErrorMessage } from "./transportError";
 interface SubscribeOptions {
   readonly retryDelay?: Duration.Input;
   readonly onResubscribe?: () => void;
+  readonly tag?: string;
 }
 
 interface RequestOptions {
@@ -39,6 +39,12 @@ interface TransportSession {
   readonly runtime: ManagedRuntime.ManagedRuntime<RpcClient.Protocol, never>;
 }
 
+interface StreamRequestStartInfo {
+  readonly id: string;
+  readonly tag: string;
+  readonly stream: boolean;
+}
+
 function formatErrorMessage(error: unknown): string {
   if (error instanceof Error && error.message.trim().length > 0) {
     return error.message;
@@ -51,8 +57,13 @@ export class WsTransport {
   private readonly lifecycleHandlers: WsProtocolLifecycleHandlers | undefined;
   private disposed = false;
   private hasReportedTransportDisconnect = false;
+  private intentionalCloseDepth = 0;
   private reconnectChain: Promise<void> = Promise.resolve();
+  private nextSessionId = 0;
+  private activeSessionId = 0;
   private session: TransportSession;
+  private lastHeartbeatPongAt = 0;
+  private readonly streamRequestStartListeners = new Set<(info: StreamRequestStartInfo) => void>();
 
   constructor(
     url: WsRpcProtocolSocketUrlProvider,
@@ -121,20 +132,26 @@ export class WsTransport {
           return;
         }
 
+        const session = this.session;
         try {
-          if (hasReceivedValue) {
-            try {
-              options?.onResubscribe?.();
-            } catch {
-              // Swallow reconnect hook errors so the stream can recover.
-            }
-          }
-
-          const session = this.session;
           const runningStream = this.runStreamOnSession(
             session,
             connect,
             listener,
+            {
+              ...(options?.tag === undefined ? {} : { tag: options.tag }),
+              ...(hasReceivedValue
+                ? {
+                    onStarted: () => {
+                      try {
+                        options?.onResubscribe?.();
+                      } catch {
+                        // Swallow reconnect hook errors so the stream can recover.
+                      }
+                    },
+                  }
+                : {}),
+            },
             () => active,
             () => {
               this.hasReportedTransportDisconnect = false;
@@ -150,6 +167,10 @@ export class WsTransport {
             return;
           }
 
+          if (session !== this.session) {
+            continue;
+          }
+
           const formattedError = formatErrorMessage(error);
           if (!isTransportConnectionErrorMessage(formattedError)) {
             console.warn("WebSocket RPC subscription failed", {
@@ -185,6 +206,8 @@ export class WsTransport {
         throw new Error("Transport disposed");
       }
 
+      clearAllTrackedRpcRequests();
+      this.lastHeartbeatPongAt = 0;
       const previousSession = this.session;
       this.session = this.createSession();
       await this.closeSession(previousSession);
@@ -194,6 +217,10 @@ export class WsTransport {
     await reconnectOperation;
   }
 
+  isHeartbeatFresh(maxAgeMs = 15_000): boolean {
+    return this.lastHeartbeatPongAt > 0 && Date.now() - this.lastHeartbeatPongAt <= maxAgeMs;
+  }
+
   async dispose() {
     if (this.disposed) {
       return;
@@ -203,14 +230,42 @@ export class WsTransport {
   }
 
   private closeSession(session: TransportSession) {
+    this.intentionalCloseDepth += 1;
     return session.runtime.runPromise(Scope.close(session.clientScope, Exit.void)).finally(() => {
+      this.intentionalCloseDepth -= 1;
       session.runtime.dispose();
     });
   }
 
   private createSession(): TransportSession {
+    const sessionId = this.nextSessionId + 1;
+    this.nextSessionId = sessionId;
+    this.activeSessionId = sessionId;
     const runtime = ManagedRuntime.make(
-      Layer.mergeAll(createWsRpcProtocolLayer(this.url, this.lifecycleHandlers), ClientTracingLive),
+      Layer.mergeAll(
+        createWsRpcProtocolLayer(this.url, {
+          ...this.lifecycleHandlers,
+          isActive: () => !this.disposed && this.activeSessionId === sessionId,
+          isCloseIntentional: () =>
+            this.disposed ||
+            this.intentionalCloseDepth > 0 ||
+            this.lifecycleHandlers?.isCloseIntentional?.() === true,
+          onHeartbeatPong: () => {
+            this.lastHeartbeatPongAt = Date.now();
+            this.lifecycleHandlers?.onHeartbeatPong?.();
+          },
+          onRequestStart: (info) => {
+            this.lifecycleHandlers?.onRequestStart?.(info);
+            if (!info.stream) {
+              return;
+            }
+            for (const listener of this.streamRequestStartListeners) {
+              listener(info);
+            }
+          },
+        }),
+        ClientTracingLive,
+      ),
     );
     const clientScope = runtime.runSync(Scope.make());
     return {
@@ -224,6 +279,10 @@ export class WsTransport {
     session: TransportSession,
     connect: (client: WsRpcProtocolClient) => Stream.Stream<TValue, Error, never>,
     listener: (value: TValue) => void,
+    requestStart: {
+      readonly tag?: string;
+      readonly onStarted?: () => void;
+    },
     isActive: () => boolean,
     markValueReceived: () => void,
   ): {
@@ -236,6 +295,23 @@ export class WsTransport {
       resolveCompleted = resolve;
       rejectCompleted = reject;
     });
+    let requestStartListener: ((info: StreamRequestStartInfo) => void) | null = null;
+    if (requestStart.onStarted) {
+      requestStartListener = (info) => {
+        if (!isActive() || !info.stream) {
+          return;
+        }
+        if (requestStart.tag !== undefined && info.tag !== requestStart.tag) {
+          return;
+        }
+        requestStart.onStarted?.();
+        if (requestStartListener) {
+          this.streamRequestStartListeners.delete(requestStartListener);
+          requestStartListener = null;
+        }
+      };
+      this.streamRequestStartListeners.add(requestStartListener);
+    }
     const cancel = session.runtime.runCallback(
       Effect.promise(() => session.clientPromise).pipe(
         Effect.flatMap((client) =>
@@ -257,6 +333,10 @@ export class WsTransport {
       ),
       {
         onExit: (exit) => {
+          if (requestStartListener) {
+            this.streamRequestStartListeners.delete(requestStartListener);
+            requestStartListener = null;
+          }
           if (Exit.isSuccess(exit)) {
             resolveCompleted();
             return;
diff --git a/apps/web/src/session-logic.test.ts b/apps/web/src/session-logic.test.ts
index d3fd3043499..baf384d6af2 100644
--- a/apps/web/src/session-logic.test.ts
+++ b/apps/web/src/session-logic.test.ts
@@ -11,7 +11,6 @@ import {
   deriveCompletionDividerBeforeEntryId,
   deriveActiveWorkStartedAt,
   deriveActivePlanState,
-  PROVIDER_OPTIONS,
   derivePendingApprovals,
   derivePendingUserInputs,
   deriveTimelineEntries,
@@ -343,6 +342,30 @@ describe("deriveActivePlanState", () => {
       steps: [{ step: "Implement Codex user input", status: "inProgress" }],
     });
   });
+
+  it("falls back to the most recent plan from a previous turn", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "plan-from-turn-1",
+        createdAt: "2026-02-23T00:00:01.000Z",
+        kind: "turn.plan.updated",
+        summary: "Plan updated",
+        tone: "info",
+        turnId: "turn-1",
+        payload: {
+          plan: [{ step: "Write tests", status: "completed" }],
+        },
+      }),
+    ];
+
+    // Current turn is turn-2, which has no plan activity — should fall back to turn-1's plan
+    const result = deriveActivePlanState(activities, TurnId.make("turn-2"));
+    expect(result).toEqual({
+      createdAt: "2026-02-23T00:00:01.000Z",
+      turnId: "turn-1",
+      steps: [{ step: "Write tests", status: "completed" }],
+    });
+  });
 });
 
 describe("findLatestProposedPlan", () => {
@@ -568,7 +591,7 @@ describe("deriveWorkLogEntries", () => {
     expect(entries.map((entry) => entry.id)).toEqual(["tool-complete"]);
   });
 
-  it("omits task start and completion lifecycle entries", () => {
+  it("omits task.started but shows task.progress and task.completed", () => {
     const activities: OrchestrationThreadActivity[] = [
       makeActivity({
         id: "task-start",
@@ -594,7 +617,40 @@ describe("deriveWorkLogEntries", () => {
     ];
 
     const entries = deriveWorkLogEntries(activities, undefined);
-    expect(entries.map((entry) => entry.id)).toEqual(["task-progress"]);
+    expect(entries.map((entry) => entry.id)).toEqual(["task-progress", "task-complete"]);
+  });
+
+  it("uses payload summary as label for task entries when available", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "task-progress-with-summary",
+        createdAt: "2026-02-23T00:00:02.000Z",
+        kind: "task.progress",
+        summary: "Reasoning update",
+        tone: "info",
+        payload: { summary: "Searching for API endpoints" },
+      }),
+    ];
+
+    const entries = deriveWorkLogEntries(activities, undefined);
+    expect(entries[0]?.label).toBe("Searching for API endpoints");
+  });
+
+  it("uses payload detail as label for task.completed and preserves error tone", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "task-completed-failed",
+        createdAt: "2026-02-23T00:00:03.000Z",
+        kind: "task.completed",
+        summary: "Task failed",
+        tone: "error",
+        payload: { detail: "Failed to deploy changes" },
+      }),
+    ];
+
+    const entries = deriveWorkLogEntries(activities, undefined);
+    expect(entries[0]?.label).toBe("Failed to deploy changes");
+    expect(entries[0]?.tone).toBe("error");
   });
 
   it("filters by turn id when provided", () => {
@@ -864,6 +920,199 @@ describe("deriveWorkLogEntries", () => {
     ]);
   });
 
+  it("drops duplicated tool detail when it only repeats the title", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "read-file-generic",
+        kind: "tool.completed",
+        summary: "Read File",
+        payload: {
+          itemType: "dynamic_tool_call",
+          title: "Read File",
+          detail: "Read File",
+        },
+      }),
+    ];
+
+    const [entry] = deriveWorkLogEntries(activities, undefined);
+    expect(entry?.toolTitle).toBe("Read File");
+    expect(entry?.detail).toBeUndefined();
+  });
+
+  it("uses grep raw output summaries instead of repeating the generic tool label", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "grep-update",
+        createdAt: "2026-02-23T00:00:01.000Z",
+        kind: "tool.updated",
+        summary: "grep",
+        payload: {
+          itemType: "web_search",
+          title: "grep",
+          detail: "grep",
+          data: {
+            toolCallId: "tool-grep-1",
+            kind: "search",
+            rawInput: {},
+          },
+        },
+      }),
+      makeActivity({
+        id: "grep-complete",
+        createdAt: "2026-02-23T00:00:02.000Z",
+        kind: "tool.completed",
+        summary: "grep",
+        payload: {
+          itemType: "web_search",
+          title: "grep",
+          detail: "grep",
+          data: {
+            toolCallId: "tool-grep-1",
+            kind: "search",
+            rawOutput: {
+              totalFiles: 19,
+              truncated: false,
+            },
+          },
+        },
+      }),
+    ];
+
+    const entries = deriveWorkLogEntries(activities, undefined);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      id: "grep-complete",
+      toolTitle: "grep",
+      detail: "19 files",
+      itemType: "web_search",
+    });
+  });
+
+  it("uses completed read-file output previews and still collapses the same tool call", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "read-update",
+        createdAt: "2026-02-23T00:00:01.000Z",
+        kind: "tool.updated",
+        summary: "Read File",
+        payload: {
+          itemType: "dynamic_tool_call",
+          title: "Read File",
+          detail: "Read File",
+          data: {
+            toolCallId: "tool-read-1",
+            kind: "read",
+            rawInput: {},
+          },
+        },
+      }),
+      makeActivity({
+        id: "read-complete",
+        createdAt: "2026-02-23T00:00:02.000Z",
+        kind: "tool.completed",
+        summary: "Read File",
+        payload: {
+          itemType: "dynamic_tool_call",
+          title: "Read File",
+          detail: "Read File",
+          data: {
+            toolCallId: "tool-read-1",
+            kind: "read",
+            rawOutput: {
+              content:
+                'import * as Effect from "effect/Effect"\nimport * as Layer from "effect/Layer"\n',
+            },
+          },
+        },
+      }),
+    ];
+
+    const entries = deriveWorkLogEntries(activities, undefined);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      id: "read-complete",
+      toolTitle: "Read File",
+      detail: 'import * as Effect from "effect/Effect"',
+      itemType: "dynamic_tool_call",
+    });
+  });
+
+  it("does not use command stdout as the detail when Cursor omits the command input", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "cursor-command-complete",
+        createdAt: "2026-04-16T22:40:42.221Z",
+        kind: "tool.completed",
+        summary: "Ran command",
+        payload: {
+          itemType: "command_execution",
+          title: "Ran command",
+          data: {
+            toolCallId: "toolu_vrtx_01WypXgRM8PPygBtrVAZwzy5",
+            kind: "execute",
+            rawInput: {},
+            rawOutput: {
+              exitCode: 0,
+              stdout: "total 960\napps\npackages\n",
+              stderr: "",
+            },
+          },
+        },
+      }),
+    ];
+
+    const [entry] = deriveWorkLogEntries(activities, undefined);
+    expect(entry).toMatchObject({
+      id: "cursor-command-complete",
+      label: "Ran command",
+      itemType: "command_execution",
+      toolTitle: "Ran command",
+    });
+    expect(entry?.detail).toBeUndefined();
+    expect(entry?.command).toBeUndefined();
+  });
+
+  it("collapses legacy completed tool rows that are missing tool metadata", () => {
+    const activities: OrchestrationThreadActivity[] = [
+      makeActivity({
+        id: "legacy-read-update",
+        createdAt: "2026-02-23T00:00:01.000Z",
+        kind: "tool.updated",
+        summary: "Read File",
+        payload: {
+          itemType: "dynamic_tool_call",
+          title: "Read File",
+          detail: "Read File",
+          data: {
+            toolCallId: "tool-read-legacy",
+            kind: "read",
+            rawInput: {},
+          },
+        },
+      }),
+      makeActivity({
+        id: "legacy-read-complete",
+        createdAt: "2026-02-23T00:00:02.000Z",
+        kind: "tool.completed",
+        summary: "Read File",
+        payload: {
+          itemType: "dynamic_tool_call",
+          title: "Read File",
+          detail: "Read File",
+        },
+      }),
+    ];
+
+    const entries = deriveWorkLogEntries(activities, undefined);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      id: "legacy-read-complete",
+      toolTitle: "Read File",
+      itemType: "dynamic_tool_call",
+    });
+    expect(entries[0]?.detail).toBeUndefined();
+  });
+
   it("collapses repeated lifecycle updates for the same tool call into one entry", () => {
     const activities: OrchestrationThreadActivity[] = [
       makeActivity({
@@ -1227,6 +1476,19 @@ describe("deriveActiveWorkStartedAt", () => {
     ).toBe("2026-02-27T21:10:00.000Z");
   });
 
+  it("uses the new send start while the session is running a different turn", () => {
+    expect(
+      deriveActiveWorkStartedAt(
+        latestTurn,
+        {
+          orchestrationStatus: "running",
+          activeTurnId: TurnId.make("turn-2"),
+        },
+        "2026-02-27T21:11:00.000Z",
+      ),
+    ).toBe("2026-02-27T21:11:00.000Z");
+  });
+
   it("falls back to sendStartedAt once the latest turn is settled", () => {
     expect(
       deriveActiveWorkStartedAt(
@@ -1254,25 +1516,3 @@ describe("deriveActiveWorkStartedAt", () => {
     ).toBe("2026-02-27T21:11:00.000Z");
   });
 });
-
-describe("PROVIDER_OPTIONS", () => {
-  it("advertises Claude as available while keeping Cursor as a placeholder", () => {
-    const claude = PROVIDER_OPTIONS.find((option) => option.value === "claudeAgent");
-    const cursor = PROVIDER_OPTIONS.find((option) => option.value === "cursor");
-    expect(PROVIDER_OPTIONS).toEqual([
-      { value: "codex", label: "Codex", available: true },
-      { value: "claudeAgent", label: "Claude", available: true },
-      { value: "cursor", label: "Cursor", available: false },
-    ]);
-    expect(claude).toEqual({
-      value: "claudeAgent",
-      label: "Claude",
-      available: true,
-    });
-    expect(cursor).toEqual({
-      value: "cursor",
-      label: "Cursor",
-      available: false,
-    });
-  });
-});
diff --git a/apps/web/src/session-logic.ts b/apps/web/src/session-logic.ts
index 54e84c883a4..a7767672fa1 100644
--- a/apps/web/src/session-logic.ts
+++ b/apps/web/src/session-logic.ts
@@ -1,10 +1,12 @@
+import * as Option from "effect/Option";
+import * as Arr from "effect/Array";
 import {
   ApprovalRequestId,
   isToolLifecycleItemType,
   type OrchestrationLatestTurn,
   type OrchestrationThreadActivity,
   type OrchestrationProposedPlanId,
-  type ProviderKind,
+  ProviderDriverKind,
   type ToolLifecycleItemType,
   type UserInputQuestion,
   type ThreadId,
@@ -20,16 +22,29 @@ import type {
   TurnDiffSummary,
 } from "./types";
 
-export type ProviderPickerKind = ProviderKind | "cursor";
+export type ProviderPickerKind = ProviderDriverKind;
 
 export const PROVIDER_OPTIONS: Array<{
   value: ProviderPickerKind;
   label: string;
   available: boolean;
+  /** Shown on the model picker sidebar when relevant */
+  pickerSidebarBadge?: "new" | "soon";
 }> = [
-  { value: "codex", label: "Codex", available: true },
-  { value: "claudeAgent", label: "Claude", available: true },
-  { value: "cursor", label: "Cursor", available: false },
+  { value: ProviderDriverKind.make("codex"), label: "Codex", available: true },
+  { value: ProviderDriverKind.make("claudeAgent"), label: "Claude", available: true },
+  {
+    value: ProviderDriverKind.make("opencode"),
+    label: "OpenCode",
+    available: true,
+    pickerSidebarBadge: "new",
+  },
+  {
+    value: ProviderDriverKind.make("cursor"),
+    label: "Cursor",
+    available: true,
+    pickerSidebarBadge: "new",
+  },
 ];
 
 export interface WorkLogEntry {
@@ -49,6 +64,7 @@ export interface WorkLogEntry {
 interface DerivedWorkLogEntry extends WorkLogEntry {
   activityKind: OrchestrationThreadActivity["kind"];
   collapseKey?: string;
+  toolCallId?: string;
 }
 
 export interface PendingApproval {
@@ -145,6 +161,14 @@ export function deriveActiveWorkStartedAt(
   session: SessionActivityState | null,
   sendStartedAt: string | null,
 ): string | null {
+  const runningTurnId =
+    session?.orchestrationStatus === "running" ? (session.activeTurnId ?? null) : null;
+  if (runningTurnId !== null) {
+    if (latestTurn?.turnId === runningTurnId) {
+      return latestTurn.startedAt ?? sendStartedAt;
+    }
+    return sendStartedAt;
+  }
   if (!isLatestTurnSettled(latestTurn, session)) {
     return latestTurn?.startedAt ?? sendStartedAt;
   }
@@ -155,6 +179,7 @@ function requestKindFromRequestType(requestType: unknown): PendingApproval["requ
   switch (requestType) {
     case "command_execution_approval":
     case "exec_command_approval":
+    case "dynamic_tool_call":
       return "command";
     case "file_read_approval":
       return "file-read";
@@ -340,16 +365,15 @@ export function deriveActivePlanState(
   latestTurnId: TurnId | undefined,
 ): ActivePlanState | null {
   const ordered = [...activities].toSorted(compareActivitiesByOrder);
-  const candidates = ordered.filter((activity) => {
-    if (activity.kind !== "turn.plan.updated") {
-      return false;
-    }
-    if (!latestTurnId) {
-      return true;
-    }
-    return activity.turnId === latestTurnId;
-  });
-  const latest = candidates.at(-1);
+  const allPlanActivities = ordered.filter((activity) => activity.kind === "turn.plan.updated");
+  // Prefer plan from the current turn; fall back to the most recent plan from any turn
+  // so that TodoWrite tasks persist across follow-up messages.
+  const latest = Option.firstSomeOf([
+    ...(latestTurnId
+      ? Arr.findLast(allPlanActivities, (activity) => activity.turnId === latestTurnId)
+      : Option.none()),
+    Arr.last(allPlanActivities),
+  ]).pipe(Option.getOrNull);
   if (!latest) {
     return null;
   }
@@ -464,7 +488,7 @@ export function deriveWorkLogEntries(
   const entries = ordered
     .filter((activity) => (latestTurnId ? activity.turnId === latestTurnId : true))
     .filter((activity) => activity.kind !== "tool.started")
-    .filter((activity) => activity.kind !== "task.started" && activity.kind !== "task.completed")
+    .filter((activity) => activity.kind !== "task.started")
     .filter((activity) => activity.kind !== "context-window.updated")
     .filter((activity) => activity.summary !== "Checkpoint captured")
     .filter((activity) => !isPlanBoundaryToolActivity(activity))
@@ -494,20 +518,44 @@ function toDerivedWorkLogEntry(activity: OrchestrationThreadActivity): DerivedWo
   const commandPreview = extractToolCommand(payload);
   const changedFiles = extractChangedFiles(payload);
   const title = extractToolTitle(payload);
+  const isTaskActivity = activity.kind === "task.progress" || activity.kind === "task.completed";
+  const taskSummary =
+    isTaskActivity && typeof payload?.summary === "string" && payload.summary.length > 0
+      ? payload.summary
+      : null;
+  const taskDetailAsLabel =
+    isTaskActivity &&
+    !taskSummary &&
+    typeof payload?.detail === "string" &&
+    payload.detail.length > 0
+      ? payload.detail
+      : null;
+  const taskLabel = taskSummary || taskDetailAsLabel;
+  const detail = isTaskActivity
+    ? !taskDetailAsLabel &&
+      payload &&
+      typeof payload.detail === "string" &&
+      payload.detail.length > 0
+      ? stripTrailingExitCode(payload.detail).output
+      : null
+    : extractToolDetail(payload, title ?? activity.summary);
+  const toolCallId = isTaskActivity ? null : extractToolCallId(payload);
   const entry: DerivedWorkLogEntry = {
     id: activity.id,
     createdAt: activity.createdAt,
-    label: activity.summary,
-    tone: activity.tone === "approval" ? "info" : activity.tone,
+    label: taskLabel || activity.summary,
+    tone:
+      activity.kind === "task.progress"
+        ? "thinking"
+        : activity.tone === "approval"
+          ? "info"
+          : activity.tone,
     activityKind: activity.kind,
   };
   const itemType = extractWorkLogItemType(payload);
   const requestKind = extractWorkLogRequestKind(payload);
-  if (payload && typeof payload.detail === "string" && payload.detail.length > 0) {
-    const detail = stripTrailingExitCode(payload.detail).output;
-    if (detail) {
-      entry.detail = detail;
-    }
+  if (detail) {
+    entry.detail = detail;
   }
   if (commandPreview.command) {
     entry.command = commandPreview.command;
@@ -527,6 +575,9 @@ function toDerivedWorkLogEntry(activity: OrchestrationThreadActivity): DerivedWo
   if (requestKind) {
     entry.requestKind = requestKind;
   }
+  if (toolCallId) {
+    entry.toolCallId = toolCallId;
+  }
   const collapseKey = deriveToolLifecycleCollapseKey(entry);
   if (collapseKey) {
     entry.collapseKey = collapseKey;
@@ -562,7 +613,16 @@ function shouldCollapseToolLifecycleEntries(
   if (previous.activityKind === "tool.completed") {
     return false;
   }
-  return previous.collapseKey !== undefined && previous.collapseKey === next.collapseKey;
+  if (previous.collapseKey !== undefined && previous.collapseKey === next.collapseKey) {
+    return true;
+  }
+  return (
+    previous.toolCallId !== undefined &&
+    next.toolCallId === undefined &&
+    previous.itemType === next.itemType &&
+    normalizeCompactToolLabel(previous.toolTitle ?? previous.label) ===
+      normalizeCompactToolLabel(next.toolTitle ?? next.label)
+  );
 }
 
 function mergeDerivedWorkLogEntries(
@@ -577,6 +637,7 @@ function mergeDerivedWorkLogEntries(
   const itemType = next.itemType ?? previous.itemType;
   const requestKind = next.requestKind ?? previous.requestKind;
   const collapseKey = next.collapseKey ?? previous.collapseKey;
+  const toolCallId = next.toolCallId ?? previous.toolCallId;
   return {
     ...previous,
     ...next,
@@ -588,6 +649,7 @@ function mergeDerivedWorkLogEntries(
     ...(itemType ? { itemType } : {}),
     ...(requestKind ? { requestKind } : {}),
     ...(collapseKey ? { collapseKey } : {}),
+    ...(toolCallId ? { toolCallId } : {}),
   };
 }
 
@@ -606,6 +668,9 @@ function deriveToolLifecycleCollapseKey(entry: DerivedWorkLogEntry): string | un
   if (entry.activityKind !== "tool.updated" && entry.activityKind !== "tool.completed") {
     return undefined;
   }
+  if (entry.toolCallId) {
+    return `tool:${entry.toolCallId}`;
+  }
   const normalizedLabel = normalizeCompactToolLabel(entry.toolTitle ?? entry.label);
   const detail = entry.detail?.trim() ?? "";
   const itemType = entry.itemType ?? "";
@@ -643,6 +708,10 @@ function asTrimmedString(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function asNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
 function trimMatchingOuterQuotes(value: string): string {
   const trimmed = value.trim();
   if (
@@ -826,6 +895,111 @@ function extractToolTitle(payload: Record<string, unknown> | null): string | nul
   return asTrimmedString(payload?.title);
 }
 
+function extractToolCallId(payload: Record<string, unknown> | null): string | null {
+  const data = asRecord(payload?.data);
+  return asTrimmedString(data?.toolCallId);
+}
+
+function normalizeInlinePreview(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function truncateInlinePreview(value: string, maxLength = 84): string {
+  if (value.length <= maxLength) {
+    return value;
+  }
+  return `${value.slice(0, maxLength - 1).trimEnd()}…`;
+}
+
+function normalizePreviewForComparison(value: string | null | undefined): string | null {
+  const normalized = asTrimmedString(value);
+  if (!normalized) {
+    return null;
+  }
+  return normalizeCompactToolLabel(normalizeInlinePreview(normalized)).toLowerCase();
+}
+
+function summarizeToolTextOutput(value: string): string | null {
+  const lines = value
+    .split(/\r?\n/u)
+    .map((line) => normalizeInlinePreview(line))
+    .filter((line) => line.length > 0);
+  const firstLine = lines.find((line) => line !== "```");
+  if (firstLine) {
+    return truncateInlinePreview(firstLine);
+  }
+  if (lines.length > 1) {
+    return `${lines.length.toLocaleString()} lines`;
+  }
+  return null;
+}
+
+function summarizeToolRawOutput(payload: Record<string, unknown> | null): string | null {
+  const data = asRecord(payload?.data);
+  const rawOutput = asRecord(data?.rawOutput);
+  if (!rawOutput) {
+    return null;
+  }
+
+  const totalFiles = asNumber(rawOutput.totalFiles);
+  if (totalFiles !== null) {
+    const suffix = rawOutput.truncated === true ? "+" : "";
+    return `${totalFiles.toLocaleString()} file${totalFiles === 1 ? "" : "s"}${suffix}`;
+  }
+
+  const content = asTrimmedString(rawOutput.content);
+  if (content) {
+    return summarizeToolTextOutput(content);
+  }
+
+  const stdout = asTrimmedString(rawOutput.stdout);
+  if (stdout) {
+    return summarizeToolTextOutput(stdout);
+  }
+
+  return null;
+}
+
+function isCommandToolDetail(payload: Record<string, unknown> | null, heading: string): boolean {
+  const data = asRecord(payload?.data);
+  const kind = asTrimmedString(data?.kind)?.toLowerCase();
+  const title = asTrimmedString(payload?.title ?? heading)?.toLowerCase();
+  return (
+    extractWorkLogItemType(payload) === "command_execution" ||
+    kind === "execute" ||
+    title === "terminal" ||
+    title === "ran command"
+  );
+}
+
+function extractToolDetail(
+  payload: Record<string, unknown> | null,
+  heading: string,
+): string | null {
+  const rawDetail = asTrimmedString(payload?.detail);
+  const detail = rawDetail ? stripTrailingExitCode(rawDetail).output : null;
+  const normalizedHeading = normalizePreviewForComparison(heading);
+  const normalizedDetail = normalizePreviewForComparison(detail);
+
+  if (detail && normalizedHeading !== normalizedDetail) {
+    return detail;
+  }
+
+  if (isCommandToolDetail(payload, heading)) {
+    return null;
+  }
+
+  const rawOutputSummary = summarizeToolRawOutput(payload);
+  if (rawOutputSummary) {
+    const normalizedRawOutputSummary = normalizePreviewForComparison(rawOutputSummary);
+    if (normalizedRawOutputSummary !== normalizedHeading) {
+      return rawOutputSummary;
+    }
+  }
+
+  return null;
+}
+
 function stripTrailingExitCode(value: string): {
   output: string | null;
   exitCode?: number | undefined;
diff --git a/apps/web/src/shortcutModifierState.test.ts b/apps/web/src/shortcutModifierState.test.ts
new file mode 100644
index 00000000000..46a7fc4aac3
--- /dev/null
+++ b/apps/web/src/shortcutModifierState.test.ts
@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  areShortcutModifierStatesEqual,
+  clearShortcutModifierState,
+  readShortcutModifierState,
+  setShortcutModifierState,
+  syncShortcutModifierStateFromKeyboardEvent,
+} from "./shortcutModifierState";
+
+function keyboardEventLike(type: "keydown" | "keyup", init: Partial<KeyboardEvent>): KeyboardEvent {
+  return {
+    type,
+    key: "",
+    metaKey: false,
+    ctrlKey: false,
+    altKey: false,
+    shiftKey: false,
+    ...init,
+  } as KeyboardEvent;
+}
+
+describe("shortcutModifierState", () => {
+  it("compares modifier states by value", () => {
+    expect(
+      areShortcutModifierStatesEqual(
+        { metaKey: false, ctrlKey: true, altKey: false, shiftKey: true },
+        { metaKey: false, ctrlKey: true, altKey: false, shiftKey: true },
+      ),
+    ).toBe(true);
+    expect(
+      areShortcutModifierStatesEqual(
+        { metaKey: false, ctrlKey: true, altKey: false, shiftKey: true },
+        { metaKey: false, ctrlKey: false, altKey: false, shiftKey: true },
+      ),
+    ).toBe(false);
+  });
+
+  it("preserves the current store object when modifier values do not change", () => {
+    clearShortcutModifierState();
+
+    const initialState = readShortcutModifierState();
+    setShortcutModifierState({
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: false,
+    });
+
+    expect(readShortcutModifierState()).toBe(initialState);
+
+    setShortcutModifierState({
+      metaKey: false,
+      ctrlKey: true,
+      altKey: false,
+      shiftKey: false,
+    });
+    const updatedState = readShortcutModifierState();
+    expect(updatedState).not.toBe(initialState);
+    expect(updatedState).toEqual({
+      metaKey: false,
+      ctrlKey: true,
+      altKey: false,
+      shiftKey: false,
+    });
+
+    setShortcutModifierState({
+      metaKey: false,
+      ctrlKey: true,
+      altKey: false,
+      shiftKey: false,
+    });
+    expect(readShortcutModifierState()).toBe(updatedState);
+
+    clearShortcutModifierState();
+    const clearedState = readShortcutModifierState();
+    expect(clearedState).toEqual({
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: false,
+    });
+    expect(clearedState).not.toBe(updatedState);
+
+    clearShortcutModifierState();
+    expect(readShortcutModifierState()).toBe(clearedState);
+  });
+
+  it("tracks bare modifier keydown and keyup events explicitly", () => {
+    clearShortcutModifierState();
+
+    syncShortcutModifierStateFromKeyboardEvent(
+      keyboardEventLike("keydown", {
+        key: "Meta",
+        metaKey: false,
+      }),
+    );
+    expect(readShortcutModifierState()).toEqual({
+      metaKey: true,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: false,
+    });
+
+    syncShortcutModifierStateFromKeyboardEvent(
+      keyboardEventLike("keydown", {
+        key: "Shift",
+        metaKey: true,
+        shiftKey: false,
+      }),
+    );
+    expect(readShortcutModifierState()).toEqual({
+      metaKey: true,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: true,
+    });
+
+    syncShortcutModifierStateFromKeyboardEvent(
+      keyboardEventLike("keyup", {
+        key: "Meta",
+        metaKey: true,
+        shiftKey: true,
+      }),
+    );
+    expect(readShortcutModifierState()).toEqual({
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: true,
+    });
+
+    syncShortcutModifierStateFromKeyboardEvent(
+      keyboardEventLike("keyup", {
+        key: "Shift",
+        shiftKey: true,
+      }),
+    );
+    expect(readShortcutModifierState()).toEqual({
+      metaKey: false,
+      ctrlKey: false,
+      altKey: false,
+      shiftKey: false,
+    });
+  });
+});
diff --git a/apps/web/src/shortcutModifierState.ts b/apps/web/src/shortcutModifierState.ts
new file mode 100644
index 00000000000..370f3b0a70c
--- /dev/null
+++ b/apps/web/src/shortcutModifierState.ts
@@ -0,0 +1,96 @@
+import { create } from "zustand";
+
+export interface ShortcutModifierState {
+  metaKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+  shiftKey: boolean;
+}
+
+const EMPTY_SHORTCUT_MODIFIER_STATE: ShortcutModifierState = {
+  metaKey: false,
+  ctrlKey: false,
+  altKey: false,
+  shiftKey: false,
+};
+
+export function areShortcutModifierStatesEqual(
+  left: ShortcutModifierState,
+  right: ShortcutModifierState,
+): boolean {
+  return (
+    left.metaKey === right.metaKey &&
+    left.ctrlKey === right.ctrlKey &&
+    left.altKey === right.altKey &&
+    left.shiftKey === right.shiftKey
+  );
+}
+
+const useShortcutModifierStateStore = create<{
+  state: ShortcutModifierState;
+  setState: (state: ShortcutModifierState) => void;
+  clear: () => void;
+}>((set) => ({
+  state: EMPTY_SHORTCUT_MODIFIER_STATE,
+  setState: (state) =>
+    set((current) => (areShortcutModifierStatesEqual(current.state, state) ? current : { state })),
+  clear: () =>
+    set((current) =>
+      areShortcutModifierStatesEqual(current.state, EMPTY_SHORTCUT_MODIFIER_STATE)
+        ? current
+        : { state: EMPTY_SHORTCUT_MODIFIER_STATE },
+    ),
+}));
+
+export function useShortcutModifierState(): ShortcutModifierState {
+  return useShortcutModifierStateStore((store) => store.state);
+}
+
+function normalizeModifierKey(key: string): keyof ShortcutModifierState | null {
+  switch (key) {
+    case "Meta":
+    case "OS":
+    case "Command":
+      return "metaKey";
+    case "Control":
+      return "ctrlKey";
+    case "Alt":
+    case "Option":
+      return "altKey";
+    case "Shift":
+      return "shiftKey";
+    default:
+      return null;
+  }
+}
+
+export function syncShortcutModifierStateFromKeyboardEvent(event: KeyboardEvent): void {
+  const normalizedModifierKey = normalizeModifierKey(event.key);
+  if (normalizedModifierKey) {
+    const currentState = useShortcutModifierStateStore.getState().state;
+    useShortcutModifierStateStore.getState().setState({
+      ...currentState,
+      [normalizedModifierKey]: event.type === "keydown",
+    });
+    return;
+  }
+
+  useShortcutModifierStateStore.getState().setState({
+    metaKey: event.metaKey,
+    ctrlKey: event.ctrlKey,
+    altKey: event.altKey,
+    shiftKey: event.shiftKey,
+  });
+}
+
+export function setShortcutModifierState(state: ShortcutModifierState): void {
+  useShortcutModifierStateStore.getState().setState(state);
+}
+
+export function clearShortcutModifierState(): void {
+  useShortcutModifierStateStore.getState().clear();
+}
+
+export function readShortcutModifierState(): ShortcutModifierState {
+  return useShortcutModifierStateStore.getState().state;
+}
diff --git a/apps/web/src/sidebarProjectGrouping.ts b/apps/web/src/sidebarProjectGrouping.ts
new file mode 100644
index 00000000000..8909c1bf755
--- /dev/null
+++ b/apps/web/src/sidebarProjectGrouping.ts
@@ -0,0 +1,118 @@
+import { scopeProjectRef } from "@t3tools/client-runtime";
+import type { EnvironmentId, ScopedProjectRef } from "@t3tools/contracts";
+import {
+  deriveLogicalProjectKeyFromSettings,
+  derivePhysicalProjectKey,
+  deriveProjectGroupLabel,
+  type ProjectGroupingSettings,
+} from "./logicalProject";
+import type { Project } from "./types";
+
+export type EnvironmentPresence = "local-only" | "remote-only" | "mixed";
+
+export interface SidebarProjectGroupMember extends Project {
+  physicalProjectKey: string;
+  environmentLabel: string | null;
+}
+
+export interface SidebarProjectSnapshot extends Project {
+  projectKey: string;
+  displayName: string;
+  groupedProjectCount: number;
+  environmentPresence: EnvironmentPresence;
+  memberProjects: readonly SidebarProjectGroupMember[];
+  memberProjectRefs: readonly ScopedProjectRef[];
+  remoteEnvironmentLabels: readonly string[];
+}
+
+export function buildPhysicalToLogicalProjectKeyMap(input: {
+  projects: ReadonlyArray<Project>;
+  settings: ProjectGroupingSettings;
+}): Map<string, string> {
+  const mapping = new Map<string, string>();
+  for (const project of input.projects) {
+    mapping.set(
+      derivePhysicalProjectKey(project),
+      deriveLogicalProjectKeyFromSettings(project, input.settings),
+    );
+  }
+  return mapping;
+}
+
+export function buildSidebarProjectSnapshots(input: {
+  projects: ReadonlyArray<Project>;
+  settings: ProjectGroupingSettings;
+  primaryEnvironmentId: EnvironmentId | null;
+  resolveEnvironmentLabel: (environmentId: EnvironmentId) => string | null;
+}): SidebarProjectSnapshot[] {
+  const groupedMembers = new Map<string, SidebarProjectGroupMember[]>();
+  for (const project of input.projects) {
+    const logicalKey = deriveLogicalProjectKeyFromSettings(project, input.settings);
+    const member: SidebarProjectGroupMember = {
+      ...project,
+      physicalProjectKey: derivePhysicalProjectKey(project),
+      environmentLabel: input.resolveEnvironmentLabel(project.environmentId),
+    };
+    const existing = groupedMembers.get(logicalKey);
+    if (existing) {
+      existing.push(member);
+    } else {
+      groupedMembers.set(logicalKey, [member]);
+    }
+  }
+
+  const result: SidebarProjectSnapshot[] = [];
+  const seen = new Set<string>();
+  for (const project of input.projects) {
+    const logicalKey = deriveLogicalProjectKeyFromSettings(project, input.settings);
+    if (seen.has(logicalKey)) {
+      continue;
+    }
+    seen.add(logicalKey);
+
+    const members = groupedMembers.get(logicalKey) ?? [];
+    const representative =
+      (input.primaryEnvironmentId
+        ? members.find((member) => member.environmentId === input.primaryEnvironmentId)
+        : null) ?? members[0];
+    if (!representative) {
+      continue;
+    }
+
+    const hasLocal =
+      input.primaryEnvironmentId !== null &&
+      members.some((member) => member.environmentId === input.primaryEnvironmentId);
+    const hasRemote =
+      input.primaryEnvironmentId !== null
+        ? members.some((member) => member.environmentId !== input.primaryEnvironmentId)
+        : false;
+    const remoteEnvironmentLabels = members
+      .filter(
+        (member) =>
+          input.primaryEnvironmentId !== null &&
+          member.environmentId !== input.primaryEnvironmentId,
+      )
+      .flatMap((member) => (member.environmentLabel ? [member.environmentLabel] : []))
+      .filter((label, index, labels) => labels.indexOf(label) === index);
+
+    result.push({
+      ...representative,
+      projectKey: logicalKey,
+      displayName:
+        members.length > 1
+          ? deriveProjectGroupLabel({
+              representative,
+              members,
+            })
+          : representative.name,
+      groupedProjectCount: members.length,
+      environmentPresence:
+        hasLocal && hasRemote ? "mixed" : hasRemote ? "remote-only" : "local-only",
+      memberProjects: members,
+      memberProjectRefs: members.map((member) => scopeProjectRef(member.environmentId, member.id)),
+      remoteEnvironmentLabels,
+    });
+  }
+
+  return result;
+}
diff --git a/apps/web/src/sourceControlPresentation.ts b/apps/web/src/sourceControlPresentation.ts
new file mode 100644
index 00000000000..68271228ed6
--- /dev/null
+++ b/apps/web/src/sourceControlPresentation.ts
@@ -0,0 +1,62 @@
+import { GitPullRequestIcon } from "lucide-react";
+import type { ElementType } from "react";
+import type { SourceControlProviderInfo } from "@t3tools/contracts";
+export {
+  DEFAULT_CHANGE_REQUEST_TERMINOLOGY,
+  formatChangeRequestAction,
+  formatCreateChangeRequestPhrase,
+  getChangeRequestTerminology,
+  resolveChangeRequestPresentation,
+  type ChangeRequestPresentation,
+  type ChangeRequestTerminology,
+} from "@t3tools/shared/sourceControl";
+import {
+  getChangeRequestTerminology,
+  resolveChangeRequestPresentation,
+  type ChangeRequestTerminology,
+} from "@t3tools/shared/sourceControl";
+import { AzureDevOpsIcon, BitbucketIcon, GitHubIcon, GitLabIcon } from "./components/Icons";
+
+export interface SourceControlPresentation {
+  readonly providerName: string;
+  readonly terminology: ChangeRequestTerminology;
+  readonly Icon: ElementType<{ className?: string }>;
+}
+
+export function getSourceControlPresentation(
+  provider: SourceControlProviderInfo | null | undefined,
+): SourceControlPresentation {
+  const presentation = resolveChangeRequestPresentation(provider);
+  switch (presentation.icon) {
+    case "github":
+      return {
+        providerName: provider?.name || presentation.providerName,
+        terminology: getChangeRequestTerminology(provider),
+        Icon: GitHubIcon,
+      };
+    case "gitlab":
+      return {
+        providerName: provider?.name || presentation.providerName,
+        terminology: getChangeRequestTerminology(provider),
+        Icon: GitLabIcon,
+      };
+    case "azure-devops":
+      return {
+        providerName: provider?.name || presentation.providerName,
+        terminology: getChangeRequestTerminology(provider),
+        Icon: AzureDevOpsIcon,
+      };
+    case "bitbucket":
+      return {
+        providerName: provider?.name || presentation.providerName,
+        terminology: getChangeRequestTerminology(provider),
+        Icon: BitbucketIcon,
+      };
+    case "change-request":
+      return {
+        providerName: provider?.name || presentation.providerName,
+        terminology: getChangeRequestTerminology(provider),
+        Icon: GitPullRequestIcon,
+      };
+  }
+}
diff --git a/apps/web/src/store.test.ts b/apps/web/src/store.test.ts
index 951830dbbc2..59ebd0cea0c 100644
--- a/apps/web/src/store.test.ts
+++ b/apps/web/src/store.test.ts
@@ -1,28 +1,28 @@
 import { scopeThreadRef } from "@t3tools/client-runtime";
 import {
   CheckpointRef,
-  DEFAULT_MODEL_BY_PROVIDER,
+  DEFAULT_MODEL,
   EnvironmentId,
   EventId,
   MessageId,
   ProjectId,
+  ProviderInstanceId,
   ThreadId,
   TurnId,
   type OrchestrationEvent,
-  type OrchestrationReadModel,
 } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 
 import {
   applyOrchestrationEvent,
   applyOrchestrationEvents,
+  removeEnvironmentState,
   selectEnvironmentState,
   selectProjectsAcrossEnvironments,
   selectThreadByRef,
   selectThreadExistsByRef,
   setThreadBranch,
   selectThreadsAcrossEnvironments,
-  syncServerReadModel,
   type AppState,
   type EnvironmentState,
 } from "./store";
@@ -67,7 +67,7 @@ function makeThread(overrides: Partial<Thread> = {}): Thread {
     projectId: ProjectId.make("project-1"),
     title: "Thread",
     modelSelection: {
-      provider: "codex",
+      instanceId: ProviderInstanceId.make("codex"),
       model: "gpt-5-codex",
     },
     runtimeMode: DEFAULT_RUNTIME_MODE,
@@ -95,7 +95,7 @@ function makeState(thread: Thread): AppState {
     name: "Project",
     cwd: "/tmp/project",
     defaultModelSelection: {
-      provider: "codex" as const,
+      instanceId: ProviderInstanceId.make("codex"),
       model: "gpt-5-codex",
     },
     createdAt: "2026-02-13T00:00:00.000Z",
@@ -247,6 +247,39 @@ function makeEvent<T extends OrchestrationEvent["type"]>(
   } as Extract<OrchestrationEvent, { type: T }>;
 }
 
+describe("environment state removal", () => {
+  it("drops local state for removed environments", () => {
+    const removedThread = makeThread({
+      environmentId: remoteEnvironmentId,
+      id: ThreadId.make("thread-removed"),
+    });
+    const keptThread = makeThread({ id: ThreadId.make("thread-kept") });
+    const removedState = makeState(removedThread).environmentStateById[remoteEnvironmentId]!;
+    const keptState = makeState(keptThread).environmentStateById[localEnvironmentId]!;
+    const state: AppState = {
+      activeEnvironmentId: remoteEnvironmentId,
+      environmentStateById: {
+        [remoteEnvironmentId]: removedState,
+        [localEnvironmentId]: keptState,
+      },
+    };
+
+    const next = removeEnvironmentState(state, remoteEnvironmentId);
+
+    expect(next.activeEnvironmentId).toBeNull();
+    expect(next.environmentStateById[remoteEnvironmentId]).toBeUndefined();
+    expect(next.environmentStateById[localEnvironmentId]).toBe(keptState);
+  });
+
+  it("preserves active environment when removing a different environment", () => {
+    const state = makeState(makeThread());
+
+    const next = removeEnvironmentState(state, remoteEnvironmentId);
+
+    expect(next).toBe(state);
+  });
+});
+
 describe("thread selection memoization", () => {
   it("returns stable thread references for repeated reads of the same state", () => {
     const thread = makeThread({
@@ -369,75 +402,6 @@ describe("thread selection memoization", () => {
   });
 });
 
-function makeReadModelThread(overrides: Partial<OrchestrationReadModel["threads"][number]>) {
-  return {
-    id: ThreadId.make("thread-1"),
-    projectId: ProjectId.make("project-1"),
-    title: "Thread",
-    modelSelection: {
-      provider: "codex",
-      model: "gpt-5.3-codex",
-    },
-    runtimeMode: DEFAULT_RUNTIME_MODE,
-    interactionMode: DEFAULT_INTERACTION_MODE,
-    branch: null,
-    worktreePath: null,
-    latestTurn: null,
-    createdAt: "2026-02-27T00:00:00.000Z",
-    updatedAt: "2026-02-27T00:00:00.000Z",
-    archivedAt: null,
-    deletedAt: null,
-    messages: [],
-    activities: [],
-    proposedPlans: [],
-    checkpoints: [],
-    session: null,
-    ...overrides,
-  } satisfies OrchestrationReadModel["threads"][number];
-}
-
-function makeReadModel(thread: OrchestrationReadModel["threads"][number]): OrchestrationReadModel {
-  return {
-    snapshotSequence: 1,
-    updatedAt: "2026-02-27T00:00:00.000Z",
-    projects: [
-      {
-        id: ProjectId.make("project-1"),
-        title: "Project",
-        workspaceRoot: "/tmp/project",
-        defaultModelSelection: {
-          provider: "codex",
-          model: "gpt-5.3-codex",
-        },
-        createdAt: "2026-02-27T00:00:00.000Z",
-        updatedAt: "2026-02-27T00:00:00.000Z",
-        deletedAt: null,
-        scripts: [],
-      },
-    ],
-    threads: [thread],
-  };
-}
-
-function makeReadModelProject(
-  overrides: Partial<OrchestrationReadModel["projects"][number]>,
-): OrchestrationReadModel["projects"][number] {
-  return {
-    id: ProjectId.make("project-1"),
-    title: "Project",
-    workspaceRoot: "/tmp/project",
-    defaultModelSelection: {
-      provider: "codex",
-      model: "gpt-5.3-codex",
-    },
-    createdAt: "2026-02-27T00:00:00.000Z",
-    updatedAt: "2026-02-27T00:00:00.000Z",
-    deletedAt: null,
-    scripts: [],
-    ...overrides,
-  };
-}
-
 describe("setThreadBranch", () => {
   it("updates only the scoped thread environment", () => {
     const sharedThreadId = ThreadId.make("thread-shared");
@@ -478,159 +442,6 @@ describe("setThreadBranch", () => {
   });
 });
 
-describe("store read model sync", () => {
-  it("marks bootstrap complete after snapshot sync", () => {
-    const initialState = withActiveEnvironmentState(
-      localEnvironmentStateOf(makeState(makeThread())),
-      {
-        bootstrapComplete: false,
-      },
-    );
-
-    const next = syncServerReadModel(
-      initialState,
-      makeReadModel(makeReadModelThread({})),
-      localEnvironmentId,
-    );
-
-    expect(localEnvironmentStateOf(next).bootstrapComplete).toBe(true);
-  });
-
-  it("preserves claude model slugs without an active session", () => {
-    const initialState = makeState(makeThread());
-    const readModel = makeReadModel(
-      makeReadModelThread({
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-        },
-      }),
-    );
-
-    const next = syncServerReadModel(initialState, readModel, localEnvironmentId);
-
-    expect(threadsOf(next)[0]?.modelSelection.model).toBe("claude-opus-4-6");
-  });
-
-  it("resolves claude aliases when session provider is claudeAgent", () => {
-    const initialState = makeState(makeThread());
-    const readModel = makeReadModel(
-      makeReadModelThread({
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "sonnet",
-        },
-        session: {
-          threadId: ThreadId.make("thread-1"),
-          status: "ready",
-          providerName: "claudeAgent",
-          runtimeMode: "approval-required",
-          activeTurnId: null,
-          lastError: null,
-          updatedAt: "2026-02-27T00:00:00.000Z",
-        },
-      }),
-    );
-
-    const next = syncServerReadModel(initialState, readModel, localEnvironmentId);
-
-    expect(threadsOf(next)[0]?.modelSelection.model).toBe("claude-sonnet-4-6");
-  });
-
-  it("preserves project and thread updatedAt timestamps from the read model", () => {
-    const initialState = makeState(makeThread());
-    const readModel = makeReadModel(
-      makeReadModelThread({
-        updatedAt: "2026-02-27T00:05:00.000Z",
-      }),
-    );
-
-    const next = syncServerReadModel(initialState, readModel, localEnvironmentId);
-
-    expect(projectsOf(next)[0]?.updatedAt).toBe("2026-02-27T00:00:00.000Z");
-    expect(threadsOf(next)[0]?.updatedAt).toBe("2026-02-27T00:05:00.000Z");
-  });
-
-  it("maps archivedAt from the read model", () => {
-    const initialState = makeState(makeThread());
-    const archivedAt = "2026-02-28T00:00:00.000Z";
-    const next = syncServerReadModel(
-      initialState,
-      makeReadModel(
-        makeReadModelThread({
-          archivedAt,
-        }),
-      ),
-      localEnvironmentId,
-    );
-
-    expect(threadsOf(next)[0]?.archivedAt).toBe(archivedAt);
-  });
-
-  it("replaces projects using snapshot order during recovery", () => {
-    const project1 = ProjectId.make("project-1");
-    const project2 = ProjectId.make("project-2");
-    const project3 = ProjectId.make("project-3");
-    const initialState: AppState = makeEmptyState({
-      projectIds: [project2, project1],
-      projectById: {
-        [project2]: {
-          id: project2,
-          environmentId: localEnvironmentId,
-          name: "Project 2",
-          cwd: "/tmp/project-2",
-          defaultModelSelection: {
-            provider: "codex",
-            model: DEFAULT_MODEL_BY_PROVIDER.codex,
-          },
-          createdAt: "2026-02-27T00:00:00.000Z",
-          updatedAt: "2026-02-27T00:00:00.000Z",
-          scripts: [],
-        },
-        [project1]: {
-          id: project1,
-          environmentId: localEnvironmentId,
-          name: "Project 1",
-          cwd: "/tmp/project-1",
-          defaultModelSelection: {
-            provider: "codex",
-            model: DEFAULT_MODEL_BY_PROVIDER.codex,
-          },
-          createdAt: "2026-02-27T00:00:00.000Z",
-          updatedAt: "2026-02-27T00:00:00.000Z",
-          scripts: [],
-        },
-      },
-    });
-    const readModel: OrchestrationReadModel = {
-      snapshotSequence: 2,
-      updatedAt: "2026-02-27T00:00:00.000Z",
-      projects: [
-        makeReadModelProject({
-          id: project1,
-          title: "Project 1",
-          workspaceRoot: "/tmp/project-1",
-        }),
-        makeReadModelProject({
-          id: project2,
-          title: "Project 2",
-          workspaceRoot: "/tmp/project-2",
-        }),
-        makeReadModelProject({
-          id: project3,
-          title: "Project 3",
-          workspaceRoot: "/tmp/project-3",
-        }),
-      ],
-      threads: [],
-    };
-
-    const next = syncServerReadModel(initialState, readModel, localEnvironmentId);
-
-    expect(projectsOf(next).map((project) => project.id)).toEqual([project1, project2, project3]);
-  });
-});
-
 describe("incremental orchestration updates", () => {
   it("does not mark bootstrap complete for incremental events", () => {
     const state = withActiveEnvironmentState(localEnvironmentStateOf(makeState(makeThread())), {
@@ -687,8 +498,8 @@ describe("incremental orchestration updates", () => {
           name: "Project",
           cwd: "/tmp/project",
           defaultModelSelection: {
-            provider: "codex",
-            model: DEFAULT_MODEL_BY_PROVIDER.codex,
+            instanceId: ProviderInstanceId.make("codex"),
+            model: DEFAULT_MODEL,
           },
           createdAt: "2026-02-27T00:00:00.000Z",
           updatedAt: "2026-02-27T00:00:00.000Z",
@@ -704,8 +515,8 @@ describe("incremental orchestration updates", () => {
         title: "Project Recreated",
         workspaceRoot: "/tmp/project",
         defaultModelSelection: {
-          provider: "codex",
-          model: DEFAULT_MODEL_BY_PROVIDER.codex,
+          instanceId: ProviderInstanceId.make("codex"),
+          model: DEFAULT_MODEL,
         },
         scripts: [],
         createdAt: "2026-02-27T00:00:01.000Z",
@@ -742,8 +553,8 @@ describe("incremental orchestration updates", () => {
           name: "Project 1",
           cwd: "/tmp/project-1",
           defaultModelSelection: {
-            provider: "codex",
-            model: DEFAULT_MODEL_BY_PROVIDER.codex,
+            instanceId: ProviderInstanceId.make("codex"),
+            model: DEFAULT_MODEL,
           },
           createdAt: "2026-02-27T00:00:00.000Z",
           updatedAt: "2026-02-27T00:00:00.000Z",
@@ -755,8 +566,8 @@ describe("incremental orchestration updates", () => {
           name: "Project 2",
           cwd: "/tmp/project-2",
           defaultModelSelection: {
-            provider: "codex",
-            model: DEFAULT_MODEL_BY_PROVIDER.codex,
+            instanceId: ProviderInstanceId.make("codex"),
+            model: DEFAULT_MODEL,
           },
           createdAt: "2026-02-27T00:00:00.000Z",
           updatedAt: "2026-02-27T00:00:00.000Z",
@@ -772,8 +583,8 @@ describe("incremental orchestration updates", () => {
         projectId: recreatedProjectId,
         title: "Recovered thread",
         modelSelection: {
-          provider: "codex",
-          model: DEFAULT_MODEL_BY_PROVIDER.codex,
+          instanceId: ProviderInstanceId.make("codex"),
+          model: DEFAULT_MODEL,
         },
         runtimeMode: DEFAULT_RUNTIME_MODE,
         interactionMode: DEFAULT_INTERACTION_MODE,
diff --git a/apps/web/src/store.ts b/apps/web/src/store.ts
index 58a0697c7d0..e9972f7c9a8 100644
--- a/apps/web/src/store.ts
+++ b/apps/web/src/store.ts
@@ -3,28 +3,26 @@ import type {
   MessageId,
   OrchestrationCheckpointSummary,
   OrchestrationEvent,
+  OrchestrationLatestTurn,
   OrchestrationMessage,
   OrchestrationProposedPlan,
   OrchestrationReadModel,
+  OrchestrationShellSnapshot,
+  OrchestrationShellStreamEvent,
   OrchestrationSession,
   OrchestrationSessionStatus,
   OrchestrationThread,
+  OrchestrationThreadShell,
   OrchestrationThreadActivity,
   ProjectId,
-  ProviderKind,
   ScopedProjectRef,
   ScopedThreadRef,
-  ThreadId,
-  TurnId,
 } from "@t3tools/contracts";
+import { isProviderDriverKind, ProviderDriverKind } from "@t3tools/contracts";
+import type { ThreadId, TurnId } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
 import { resolveModelSlugForProvider } from "@t3tools/shared/model";
 import { create } from "zustand";
-import {
-  derivePendingApprovals,
-  derivePendingUserInputs,
-  findLatestProposedPlan,
-  hasActionableProposedPlan,
-} from "./session-logic";
 import {
   type ChatMessage,
   type Project,
@@ -39,15 +37,38 @@ import {
 import { resolveEnvironmentHttpUrl } from "./environments/runtime";
 import { sanitizeThreadErrorMessage } from "./rpc/transportError";
 import { getThreadFromEnvironmentState } from "./threadDerivation";
+const isProviderDriverKindValue = Schema.is(ProviderDriverKind);
 
 export interface EnvironmentState {
   projectIds: ProjectId[];
   projectById: Record<ProjectId, Project>;
+
+  // ---------------------------------------------------------------------------
+  // Thread bookkeeping — written by BOTH shell stream and detail stream.
+  // Both streams ensure the thread is registered here; the bookkeeping is
+  // additive (append-only IDs) so concurrent writes are safe.
+  // ---------------------------------------------------------------------------
   threadIds: ThreadId[];
   threadIdsByProjectId: Record<ProjectId, ThreadId[]>;
+
+  // ---------------------------------------------------------------------------
+  // Thread shell / session / turn — written by BOTH shell stream and detail
+  // stream.  The shell stream is the *authoritative* source (server pre-
+  // computes these from the projection pipeline), but the detail stream also
+  // writes them so the active thread has up-to-date state even if the shell
+  // event hasn't arrived yet.  Structural equality checks in both write
+  // functions prevent unnecessary React re-renders when both streams deliver
+  // equivalent data.
+  // ---------------------------------------------------------------------------
   threadShellById: Record<ThreadId, ThreadShell>;
   threadSessionById: Record<ThreadId, ThreadSession | null>;
   threadTurnStateById: Record<ThreadId, ThreadTurnState>;
+
+  // ---------------------------------------------------------------------------
+  // Thread detail content — written ONLY by the detail stream
+  // (writeThreadState / syncServerThreadDetail).  The shell stream never
+  // touches these.
+  // ---------------------------------------------------------------------------
   messageIdsByThreadId: Record<ThreadId, MessageId[]>;
   messageByThreadId: Record<ThreadId, Record<MessageId, ChatMessage>>;
   activityIdsByThreadId: Record<ThreadId, string[]>;
@@ -56,7 +77,16 @@ export interface EnvironmentState {
   proposedPlanByThreadId: Record<ThreadId, Record<string, ProposedPlan>>;
   turnDiffIdsByThreadId: Record<ThreadId, TurnId[]>;
   turnDiffSummaryByThreadId: Record<ThreadId, Record<TurnId, TurnDiffSummary>>;
+
+  // ---------------------------------------------------------------------------
+  // Sidebar summary — written ONLY by the shell stream
+  // (writeThreadShellState / mapThreadShell).  Pre-computed server-side with
+  // fields like latestUserMessageAt, hasPendingApprovals, etc.  The detail
+  // stream must NOT write here; the shell stream is the single source of
+  // truth for sidebar data.
+  // ---------------------------------------------------------------------------
   sidebarThreadSummaryById: Record<ThreadId, SidebarThreadSummary>;
+
   bootstrapComplete: boolean;
 }
 
@@ -100,12 +130,16 @@ function arraysEqual<T>(left: readonly T[], right: readonly T[]): boolean {
   return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 
-function normalizeModelSelection<T extends { provider: "codex" | "claudeAgent"; model: string }>(
-  selection: T,
-): T {
+// Accepts the open `instanceId` string carried on `ModelSelection`; malformed
+// values pass through unchanged, while valid slugs use any registered alias
+// table for model normalization.
+function normalizeModelSelection<T extends { instanceId: string; model: string }>(selection: T): T {
+  if (!isProviderDriverKind(selection.instanceId)) {
+    return selection;
+  }
   return {
     ...selection,
-    model: resolveModelSlugForProvider(selection.provider, selection.model),
+    model: resolveModelSlugForProvider(selection.instanceId, selection.model),
   };
 }
 
@@ -116,6 +150,7 @@ function mapProjectScripts(scripts: ReadonlyArray<Project["scripts"][number]>):
 function mapSession(session: OrchestrationSession): ThreadSession {
   return {
     provider: toLegacyProvider(session.providerName),
+    providerInstanceId: session.providerInstanceId ?? undefined,
     status: toLegacySessionStatus(session.status),
     orchestrationStatus: session.status,
     activeTurnId: session.activeTurnId ?? undefined,
@@ -175,7 +210,9 @@ function mapTurnDiffSummary(checkpoint: OrchestrationCheckpointSummary): TurnDif
 }
 
 function mapProject(
-  project: OrchestrationReadModel["projects"][number],
+  project:
+    | OrchestrationReadModel["projects"][number]
+    | OrchestrationShellSnapshot["projects"][number],
   environmentId: EnvironmentId,
 ): Project {
   return {
@@ -219,6 +256,62 @@ function mapThread(thread: OrchestrationThread, environmentId: EnvironmentId): T
   };
 }
 
+function mapThreadShell(
+  thread: OrchestrationThreadShell,
+  environmentId: EnvironmentId,
+): {
+  shell: ThreadShell;
+  session: ThreadSession | null;
+  turnState: ThreadTurnState;
+  summary: SidebarThreadSummary;
+} {
+  const shell: ThreadShell = {
+    id: thread.id,
+    environmentId,
+    codexThreadId: null,
+    projectId: thread.projectId,
+    title: thread.title,
+    modelSelection: normalizeModelSelection(thread.modelSelection),
+    runtimeMode: thread.runtimeMode,
+    interactionMode: thread.interactionMode,
+    error: sanitizeThreadErrorMessage(thread.session?.lastError),
+    createdAt: thread.createdAt,
+    archivedAt: thread.archivedAt,
+    updatedAt: thread.updatedAt,
+    branch: thread.branch,
+    worktreePath: thread.worktreePath,
+  };
+  const session = thread.session ? mapSession(thread.session) : null;
+  const turnState: ThreadTurnState = {
+    latestTurn: thread.latestTurn,
+    pendingSourceProposedPlan: thread.latestTurn?.sourceProposedPlan,
+  };
+  const summary: SidebarThreadSummary = {
+    id: thread.id,
+    environmentId,
+    projectId: thread.projectId,
+    title: thread.title,
+    interactionMode: thread.interactionMode,
+    session,
+    createdAt: thread.createdAt,
+    archivedAt: thread.archivedAt,
+    updatedAt: thread.updatedAt,
+    latestTurn: thread.latestTurn,
+    branch: thread.branch,
+    worktreePath: thread.worktreePath,
+    latestUserMessageAt: thread.latestUserMessageAt,
+    hasPendingApprovals: thread.hasPendingApprovals,
+    hasPendingUserInput: thread.hasPendingUserInput,
+    hasActionableProposedPlan: thread.hasActionableProposedPlan,
+  };
+  return {
+    shell,
+    session,
+    turnState,
+    summary,
+  };
+}
+
 function toThreadShell(thread: Thread): ThreadShell {
   return {
     id: thread.id,
@@ -247,40 +340,47 @@ function toThreadTurnState(thread: Thread): ThreadTurnState {
   };
 }
 
-function getLatestUserMessageAt(messages: ReadonlyArray<ChatMessage>): string | null {
-  let latestUserMessageAt: string | null = null;
-  for (const message of messages) {
-    if (message.role !== "user") {
-      continue;
-    }
-    if (latestUserMessageAt === null || message.createdAt > latestUserMessageAt) {
-      latestUserMessageAt = message.createdAt;
-    }
-  }
-  return latestUserMessageAt;
+function sourceProposedPlansEqual(
+  left: OrchestrationLatestTurn["sourceProposedPlan"] | undefined,
+  right: OrchestrationLatestTurn["sourceProposedPlan"] | undefined,
+): boolean {
+  if (left === right) return true;
+  if (left === undefined || right === undefined) return false;
+  return left.threadId === right.threadId && left.planId === right.planId;
 }
 
-function buildSidebarThreadSummary(thread: Thread): SidebarThreadSummary {
-  return {
-    id: thread.id,
-    environmentId: thread.environmentId,
-    projectId: thread.projectId,
-    title: thread.title,
-    interactionMode: thread.interactionMode,
-    session: thread.session,
-    createdAt: thread.createdAt,
-    archivedAt: thread.archivedAt,
-    updatedAt: thread.updatedAt,
-    latestTurn: thread.latestTurn,
-    branch: thread.branch,
-    worktreePath: thread.worktreePath,
-    latestUserMessageAt: getLatestUserMessageAt(thread.messages),
-    hasPendingApprovals: derivePendingApprovals(thread.activities).length > 0,
-    hasPendingUserInput: derivePendingUserInputs(thread.activities).length > 0,
-    hasActionableProposedPlan: hasActionableProposedPlan(
-      findLatestProposedPlan(thread.proposedPlans, thread.latestTurn?.turnId ?? null),
-    ),
-  };
+function latestTurnsEqual(
+  left: OrchestrationLatestTurn | null | undefined,
+  right: OrchestrationLatestTurn | null | undefined,
+): boolean {
+  if (left === right) return true;
+  if (left == null || right == null) return false;
+  return (
+    left.turnId === right.turnId &&
+    left.state === right.state &&
+    left.requestedAt === right.requestedAt &&
+    left.startedAt === right.startedAt &&
+    left.completedAt === right.completedAt &&
+    left.assistantMessageId === right.assistantMessageId &&
+    sourceProposedPlansEqual(left.sourceProposedPlan, right.sourceProposedPlan)
+  );
+}
+
+function threadSessionsEqual(
+  left: ThreadSession | null | undefined,
+  right: ThreadSession | null | undefined,
+): boolean {
+  if (left === right) return true;
+  if (left == null || right == null) return false;
+  return (
+    left.provider === right.provider &&
+    left.status === right.status &&
+    left.orchestrationStatus === right.orchestrationStatus &&
+    left.activeTurnId === right.activeTurnId &&
+    left.createdAt === right.createdAt &&
+    left.updatedAt === right.updatedAt &&
+    left.lastError === right.lastError
+  );
 }
 
 function sidebarThreadSummariesEqual(
@@ -293,11 +393,11 @@ function sidebarThreadSummariesEqual(
     left.projectId === right.projectId &&
     left.title === right.title &&
     left.interactionMode === right.interactionMode &&
-    left.session === right.session &&
+    threadSessionsEqual(left.session, right.session) &&
     left.createdAt === right.createdAt &&
     left.archivedAt === right.archivedAt &&
     left.updatedAt === right.updatedAt &&
-    left.latestTurn === right.latestTurn &&
+    latestTurnsEqual(left.latestTurn, right.latestTurn) &&
     left.branch === right.branch &&
     left.worktreePath === right.worktreePath &&
     left.latestUserMessageAt === right.latestUserMessageAt &&
@@ -330,8 +430,8 @@ function threadShellsEqual(left: ThreadShell | undefined, right: ThreadShell): b
 function threadTurnStatesEqual(left: ThreadTurnState | undefined, right: ThreadTurnState): boolean {
   return (
     left !== undefined &&
-    left.latestTurn === right.latestTurn &&
-    left.pendingSourceProposedPlan === right.pendingSourceProposedPlan
+    latestTurnsEqual(left.latestTurn, right.latestTurn) &&
+    sourceProposedPlansEqual(left.pendingSourceProposedPlan, right.pendingSourceProposedPlan)
   );
 }
 
@@ -405,34 +505,32 @@ function getThreads(state: EnvironmentState): Thread[] {
   });
 }
 
-function writeThreadState(
+/**
+ * Ensure a thread is registered in the bookkeeping indices (threadIds,
+ * threadIdsByProjectId).  Shared by both the shell stream and detail stream
+ * write paths — the bookkeeping is additive (append-only IDs) so concurrent
+ * writes from both streams are safe.
+ */
+function ensureThreadRegistered(
   state: EnvironmentState,
-  nextThread: Thread,
-  previousThread?: Thread,
+  threadId: ThreadId,
+  nextProjectId: ProjectId,
+  previousProjectId: ProjectId | undefined,
 ): EnvironmentState {
-  const nextShell = toThreadShell(nextThread);
-  const nextTurnState = toThreadTurnState(nextThread);
-  const previousShell = state.threadShellById[nextThread.id];
-  const previousTurnState = state.threadTurnStateById[nextThread.id];
-  const previousSummary = state.sidebarThreadSummaryById[nextThread.id];
-  const nextSummary = buildSidebarThreadSummary(nextThread);
-
   let nextState = state;
 
-  if (!state.threadIds.includes(nextThread.id)) {
+  if (!state.threadIds.includes(threadId)) {
     nextState = {
       ...nextState,
-      threadIds: [...nextState.threadIds, nextThread.id],
+      threadIds: [...nextState.threadIds, threadId],
     };
   }
 
-  const previousProjectId = previousThread?.projectId;
-  const nextProjectId = nextThread.projectId;
   if (previousProjectId !== nextProjectId) {
     let threadIdsByProjectId = nextState.threadIdsByProjectId;
     if (previousProjectId) {
       const previousIds = threadIdsByProjectId[previousProjectId] ?? EMPTY_THREAD_IDS;
-      const nextIds = removeId(previousIds, nextThread.id);
+      const nextIds = removeId(previousIds, threadId);
       if (nextIds.length === 0) {
         const { [previousProjectId]: _removed, ...rest } = threadIdsByProjectId;
         threadIdsByProjectId = rest as Record<ProjectId, ThreadId[]>;
@@ -444,7 +542,7 @@ function writeThreadState(
       }
     }
     const projectThreadIds = threadIdsByProjectId[nextProjectId] ?? EMPTY_THREAD_IDS;
-    const nextProjectThreadIds = appendId(projectThreadIds, nextThread.id);
+    const nextProjectThreadIds = appendId(projectThreadIds, threadId);
     if (!arraysEqual(projectThreadIds, nextProjectThreadIds)) {
       threadIdsByProjectId = {
         ...threadIdsByProjectId,
@@ -459,6 +557,36 @@ function writeThreadState(
     }
   }
 
+  return nextState;
+}
+
+/**
+ * Write thread state from the **detail stream** (per-thread subscription).
+ *
+ * Owns: messages, activities, proposed plans, turn diff summaries.
+ * Also writes threadShellById / threadSessionById / threadTurnStateById so
+ * the active thread has up-to-date state even if the shell stream event
+ * hasn't arrived yet (both streams use structural equality checks to avoid
+ * unnecessary re-renders when delivering equivalent data).
+ * Does NOT write sidebarThreadSummaryById — that is shell-stream-only.
+ */
+function writeThreadState(
+  state: EnvironmentState,
+  nextThread: Thread,
+  previousThread?: Thread,
+): EnvironmentState {
+  const nextShell = toThreadShell(nextThread);
+  const nextTurnState = toThreadTurnState(nextThread);
+  const previousShell = state.threadShellById[nextThread.id];
+  const previousTurnState = state.threadTurnStateById[nextThread.id];
+
+  let nextState = ensureThreadRegistered(
+    state,
+    nextThread.id,
+    nextThread.projectId,
+    previousThread?.projectId,
+  );
+
   if (!threadShellsEqual(previousShell, nextShell)) {
     nextState = {
       ...nextState,
@@ -469,7 +597,7 @@ function writeThreadState(
     };
   }
 
-  if ((previousThread?.session ?? null) !== nextThread.session) {
+  if (!threadSessionsEqual(previousThread?.session ?? null, nextThread.session)) {
     nextState = {
       ...nextState,
       threadSessionById: {
@@ -549,12 +677,83 @@ function writeThreadState(
     };
   }
 
-  if (!sidebarThreadSummariesEqual(previousSummary, nextSummary)) {
+  return nextState;
+}
+
+/**
+ * Write thread state from the **shell stream** (all-threads subscription).
+ *
+ * Owns: sidebarThreadSummaryById (pre-computed server-side sidebar data).
+ * Also writes threadShellById / threadSessionById / threadTurnStateById as
+ * the authoritative source for these fields.  The detail stream may also
+ * write them for the focused thread (see writeThreadState); structural
+ * equality checks prevent unnecessary re-renders.
+ * Does NOT write message/activity/proposedPlan/turnDiff content — that is
+ * detail-stream-only.
+ */
+function writeThreadShellState(
+  state: EnvironmentState,
+  nextThread: {
+    shell: ThreadShell;
+    session: ThreadSession | null;
+    turnState: ThreadTurnState;
+    summary: SidebarThreadSummary;
+  },
+): EnvironmentState {
+  const previousShell = state.threadShellById[nextThread.shell.id];
+
+  let nextState = ensureThreadRegistered(
+    state,
+    nextThread.shell.id,
+    nextThread.shell.projectId,
+    previousShell?.projectId,
+  );
+
+  if (!threadShellsEqual(previousShell, nextThread.shell)) {
+    nextState = {
+      ...nextState,
+      threadShellById: {
+        ...nextState.threadShellById,
+        [nextThread.shell.id]: nextThread.shell,
+      },
+    };
+  }
+
+  if (
+    !threadSessionsEqual(state.threadSessionById[nextThread.shell.id] ?? null, nextThread.session)
+  ) {
+    nextState = {
+      ...nextState,
+      threadSessionById: {
+        ...nextState.threadSessionById,
+        [nextThread.shell.id]: nextThread.session,
+      },
+    };
+  }
+
+  if (
+    !threadTurnStatesEqual(state.threadTurnStateById[nextThread.shell.id], nextThread.turnState)
+  ) {
+    nextState = {
+      ...nextState,
+      threadTurnStateById: {
+        ...nextState.threadTurnStateById,
+        [nextThread.shell.id]: nextThread.turnState,
+      },
+    };
+  }
+
+  if (
+    !sidebarThreadSummariesEqual(
+      state.sidebarThreadSummaryById[nextThread.shell.id],
+      nextThread.summary,
+    )
+  ) {
     nextState = {
       ...nextState,
       sidebarThreadSummaryById: {
         ...nextState.sidebarThreadSummaryById,
-        [nextThread.id]: nextSummary,
+        [nextThread.shell.id]: nextThread.summary,
       },
     };
   }
@@ -562,6 +761,17 @@ function writeThreadState(
   return nextState;
 }
 
+function retainThreadScopedRecord<T>(
+  record: Record<ThreadId, T>,
+  nextThreadIds: ReadonlySet<ThreadId>,
+): Record<ThreadId, T> {
+  return Object.fromEntries(
+    Object.entries(record).flatMap(([threadId, value]) =>
+      nextThreadIds.has(threadId as ThreadId) ? [[threadId, value] as const] : [],
+    ),
+  ) as Record<ThreadId, T>;
+}
+
 function removeThreadState(state: EnvironmentState, threadId: ThreadId): EnvironmentState {
   const shell = state.threadShellById[threadId];
   if (!shell) {
@@ -796,11 +1006,11 @@ function toLegacySessionStatus(
   }
 }
 
-function toLegacyProvider(providerName: string | null): ProviderKind {
-  if (providerName === "codex" || providerName === "claudeAgent") {
+function toLegacyProvider(providerName: string | null): ProviderDriverKind {
+  if (isProviderDriverKindValue(providerName)) {
     return providerName;
   }
-  return "codex";
+  return ProviderDriverKind.make("codex");
 }
 
 function attachmentPreviewRoutePath(attachmentId: string): string {
@@ -834,82 +1044,6 @@ function buildProjectState(
   };
 }
 
-function buildThreadState(
-  threads: ReadonlyArray<Thread>,
-): Pick<
-  EnvironmentState,
-  | "threadIds"
-  | "threadIdsByProjectId"
-  | "threadShellById"
-  | "threadSessionById"
-  | "threadTurnStateById"
-  | "messageIdsByThreadId"
-  | "messageByThreadId"
-  | "activityIdsByThreadId"
-  | "activityByThreadId"
-  | "proposedPlanIdsByThreadId"
-  | "proposedPlanByThreadId"
-  | "turnDiffIdsByThreadId"
-  | "turnDiffSummaryByThreadId"
-  | "sidebarThreadSummaryById"
-> {
-  const threadIds: ThreadId[] = [];
-  const threadIdsByProjectId: Record<ProjectId, ThreadId[]> = {};
-  const threadShellById: Record<ThreadId, ThreadShell> = {};
-  const threadSessionById: Record<ThreadId, ThreadSession | null> = {};
-  const threadTurnStateById: Record<ThreadId, ThreadTurnState> = {};
-  const messageIdsByThreadId: Record<ThreadId, MessageId[]> = {};
-  const messageByThreadId: Record<ThreadId, Record<MessageId, ChatMessage>> = {};
-  const activityIdsByThreadId: Record<ThreadId, string[]> = {};
-  const activityByThreadId: Record<ThreadId, Record<string, OrchestrationThreadActivity>> = {};
-  const proposedPlanIdsByThreadId: Record<ThreadId, string[]> = {};
-  const proposedPlanByThreadId: Record<ThreadId, Record<string, ProposedPlan>> = {};
-  const turnDiffIdsByThreadId: Record<ThreadId, TurnId[]> = {};
-  const turnDiffSummaryByThreadId: Record<ThreadId, Record<TurnId, TurnDiffSummary>> = {};
-  const sidebarThreadSummaryById: Record<ThreadId, SidebarThreadSummary> = {};
-
-  for (const thread of threads) {
-    threadIds.push(thread.id);
-    threadIdsByProjectId[thread.projectId] = [
-      ...(threadIdsByProjectId[thread.projectId] ?? EMPTY_THREAD_IDS),
-      thread.id,
-    ];
-    threadShellById[thread.id] = toThreadShell(thread);
-    threadSessionById[thread.id] = thread.session;
-    threadTurnStateById[thread.id] = toThreadTurnState(thread);
-    const messageSlice = buildMessageSlice(thread);
-    messageIdsByThreadId[thread.id] = messageSlice.ids;
-    messageByThreadId[thread.id] = messageSlice.byId;
-    const activitySlice = buildActivitySlice(thread);
-    activityIdsByThreadId[thread.id] = activitySlice.ids;
-    activityByThreadId[thread.id] = activitySlice.byId;
-    const proposedPlanSlice = buildProposedPlanSlice(thread);
-    proposedPlanIdsByThreadId[thread.id] = proposedPlanSlice.ids;
-    proposedPlanByThreadId[thread.id] = proposedPlanSlice.byId;
-    const turnDiffSlice = buildTurnDiffSlice(thread);
-    turnDiffIdsByThreadId[thread.id] = turnDiffSlice.ids;
-    turnDiffSummaryByThreadId[thread.id] = turnDiffSlice.byId;
-    sidebarThreadSummaryById[thread.id] = buildSidebarThreadSummary(thread);
-  }
-
-  return {
-    threadIds,
-    threadIdsByProjectId,
-    threadShellById,
-    threadSessionById,
-    threadTurnStateById,
-    messageIdsByThreadId,
-    messageByThreadId,
-    activityIdsByThreadId,
-    activityByThreadId,
-    proposedPlanIdsByThreadId,
-    proposedPlanByThreadId,
-    turnDiffIdsByThreadId,
-    turnDiffSummaryByThreadId,
-    sidebarThreadSummaryById,
-  };
-}
-
 function getStoredEnvironmentState(
   state: AppState,
   environmentId: EnvironmentId,
@@ -941,41 +1075,76 @@ function commitEnvironmentState(
   };
 }
 
-function syncEnvironmentReadModel(
+function syncEnvironmentShellSnapshot(
   state: EnvironmentState,
-  readModel: OrchestrationReadModel,
+  snapshot: OrchestrationShellSnapshot,
   environmentId: EnvironmentId,
 ): EnvironmentState {
-  const projects = readModel.projects
-    .filter((project) => project.deletedAt === null)
-    .map((project) => mapProject(project, environmentId));
-  const threads = readModel.threads
-    .filter((thread) => thread.deletedAt === null)
-    .map((thread) => mapThread(thread, environmentId));
-  return {
+  const nextProjects = snapshot.projects.map((project) => mapProject(project, environmentId));
+  const nextThreadIds = new Set(snapshot.threads.map((thread) => thread.id));
+  let nextState: EnvironmentState = {
     ...state,
-    ...buildProjectState(projects),
-    ...buildThreadState(threads),
+    ...buildProjectState(nextProjects),
+    threadIds: [],
+    threadIdsByProjectId: {},
+    threadShellById: {},
+    threadSessionById: {},
+    threadTurnStateById: {},
+    sidebarThreadSummaryById: {},
+    messageIdsByThreadId: retainThreadScopedRecord(state.messageIdsByThreadId, nextThreadIds),
+    messageByThreadId: retainThreadScopedRecord(state.messageByThreadId, nextThreadIds),
+    activityIdsByThreadId: retainThreadScopedRecord(state.activityIdsByThreadId, nextThreadIds),
+    activityByThreadId: retainThreadScopedRecord(state.activityByThreadId, nextThreadIds),
+    proposedPlanIdsByThreadId: retainThreadScopedRecord(
+      state.proposedPlanIdsByThreadId,
+      nextThreadIds,
+    ),
+    proposedPlanByThreadId: retainThreadScopedRecord(state.proposedPlanByThreadId, nextThreadIds),
+    turnDiffIdsByThreadId: retainThreadScopedRecord(state.turnDiffIdsByThreadId, nextThreadIds),
+    turnDiffSummaryByThreadId: retainThreadScopedRecord(
+      state.turnDiffSummaryByThreadId,
+      nextThreadIds,
+    ),
     bootstrapComplete: true,
   };
+
+  for (const thread of snapshot.threads) {
+    nextState = writeThreadShellState(nextState, mapThreadShell(thread, environmentId));
+  }
+
+  return nextState;
 }
 
-export function syncServerReadModel(
+export function syncServerShellSnapshot(
   state: AppState,
-  readModel: OrchestrationReadModel,
+  snapshot: OrchestrationShellSnapshot,
   environmentId: EnvironmentId,
 ): AppState {
   return commitEnvironmentState(
     state,
     environmentId,
-    syncEnvironmentReadModel(
+    syncEnvironmentShellSnapshot(
       getStoredEnvironmentState(state, environmentId),
-      readModel,
+      snapshot,
       environmentId,
     ),
   );
 }
 
+export function syncServerThreadDetail(
+  state: AppState,
+  thread: OrchestrationThread,
+  environmentId: EnvironmentId,
+): AppState {
+  const environmentState = getStoredEnvironmentState(state, environmentId);
+  const previousThread = getThreadFromEnvironmentState(environmentState, thread.id);
+  return commitEnvironmentState(
+    state,
+    environmentId,
+    writeThreadState(environmentState, mapThread(thread, environmentId), previousThread),
+  );
+}
+
 function applyEnvironmentOrchestrationEvent(
   state: EnvironmentState,
   event: OrchestrationEvent,
@@ -1466,6 +1635,67 @@ function applyEnvironmentOrchestrationEvent(
   return state;
 }
 
+function applyEnvironmentShellEvent(
+  state: EnvironmentState,
+  event: OrchestrationShellStreamEvent,
+  environmentId: EnvironmentId,
+): EnvironmentState {
+  switch (event.kind) {
+    case "project-upserted": {
+      const nextProject = mapProject(event.project, environmentId);
+      const existingProjectId =
+        state.projectIds.find(
+          (projectId) =>
+            projectId === event.project.id ||
+            state.projectById[projectId]?.cwd === event.project.workspaceRoot,
+        ) ?? null;
+      let projectById = state.projectById;
+      let projectIds = state.projectIds;
+
+      if (existingProjectId !== null && existingProjectId !== nextProject.id) {
+        const { [existingProjectId]: _removedProject, ...restProjectById } = state.projectById;
+        projectById = {
+          ...restProjectById,
+          [nextProject.id]: nextProject,
+        };
+        projectIds = state.projectIds.map((projectId) =>
+          projectId === existingProjectId ? nextProject.id : projectId,
+        );
+      } else {
+        projectById = {
+          ...state.projectById,
+          [nextProject.id]: nextProject,
+        };
+        projectIds =
+          existingProjectId === null && !state.projectIds.includes(nextProject.id)
+            ? [...state.projectIds, nextProject.id]
+            : state.projectIds;
+      }
+
+      return {
+        ...state,
+        projectById,
+        projectIds,
+      };
+    }
+    case "project-removed": {
+      if (!state.projectById[event.projectId]) {
+        return state;
+      }
+      const { [event.projectId]: _removedProject, ...projectById } = state.projectById;
+      return {
+        ...state,
+        projectById,
+        projectIds: removeId(state.projectIds, event.projectId),
+      };
+    }
+    case "thread-upserted":
+      return writeThreadShellState(state, mapThreadShell(event.thread, environmentId));
+    case "thread-removed":
+      return removeThreadState(state, event.threadId);
+  }
+}
+
 export function applyOrchestrationEvents(
   state: AppState,
   events: ReadonlyArray<OrchestrationEvent>,
@@ -1649,6 +1879,22 @@ export function applyOrchestrationEvent(
   );
 }
 
+export function applyShellEvent(
+  state: AppState,
+  event: OrchestrationShellStreamEvent,
+  environmentId: EnvironmentId,
+): AppState {
+  return commitEnvironmentState(
+    state,
+    environmentId,
+    applyEnvironmentShellEvent(
+      getStoredEnvironmentState(state, environmentId),
+      event,
+      environmentId,
+    ),
+  );
+}
+
 export function setActiveEnvironmentId(state: AppState, environmentId: EnvironmentId): AppState {
   if (state.activeEnvironmentId === environmentId) {
     return state;
@@ -1660,6 +1906,20 @@ export function setActiveEnvironmentId(state: AppState, environmentId: Environme
   };
 }
 
+export function removeEnvironmentState(state: AppState, environmentId: EnvironmentId): AppState {
+  if (!state.environmentStateById[environmentId] && state.activeEnvironmentId !== environmentId) {
+    return state;
+  }
+
+  const { [environmentId]: _removed, ...environmentStateById } = state.environmentStateById;
+  return {
+    ...state,
+    activeEnvironmentId:
+      state.activeEnvironmentId === environmentId ? null : state.activeEnvironmentId,
+    environmentStateById,
+  };
+}
+
 export function setThreadBranch(
   state: AppState,
   threadRef: ScopedThreadRef,
@@ -1685,12 +1945,18 @@ export function setThreadBranch(
 
 interface AppStore extends AppState {
   setActiveEnvironmentId: (environmentId: EnvironmentId) => void;
-  syncServerReadModel: (readModel: OrchestrationReadModel, environmentId: EnvironmentId) => void;
+  removeEnvironmentState: (environmentId: EnvironmentId) => void;
+  syncServerShellSnapshot: (
+    snapshot: OrchestrationShellSnapshot,
+    environmentId: EnvironmentId,
+  ) => void;
+  syncServerThreadDetail: (thread: OrchestrationThread, environmentId: EnvironmentId) => void;
   applyOrchestrationEvent: (event: OrchestrationEvent, environmentId: EnvironmentId) => void;
   applyOrchestrationEvents: (
     events: ReadonlyArray<OrchestrationEvent>,
     environmentId: EnvironmentId,
   ) => void;
+  applyShellEvent: (event: OrchestrationShellStreamEvent, environmentId: EnvironmentId) => void;
   setError: (threadId: ThreadId, error: string | null) => void;
   setThreadBranch: (
     threadRef: ScopedThreadRef,
@@ -1703,12 +1969,18 @@ export const useStore = create<AppStore>((set) => ({
   ...initialState,
   setActiveEnvironmentId: (environmentId) =>
     set((state) => setActiveEnvironmentId(state, environmentId)),
-  syncServerReadModel: (readModel, environmentId) =>
-    set((state) => syncServerReadModel(state, readModel, environmentId)),
+  removeEnvironmentState: (environmentId) =>
+    set((state) => removeEnvironmentState(state, environmentId)),
+  syncServerShellSnapshot: (snapshot, environmentId) =>
+    set((state) => syncServerShellSnapshot(state, snapshot, environmentId)),
+  syncServerThreadDetail: (thread, environmentId) =>
+    set((state) => syncServerThreadDetail(state, thread, environmentId)),
   applyOrchestrationEvent: (event, environmentId) =>
     set((state) => applyOrchestrationEvent(state, event, environmentId)),
   applyOrchestrationEvents: (events, environmentId) =>
     set((state) => applyOrchestrationEvents(state, events, environmentId)),
+  applyShellEvent: (event, environmentId) =>
+    set((state) => applyShellEvent(state, event, environmentId)),
   setError: (threadId, error) => set((state) => setError(state, threadId, error)),
   setThreadBranch: (threadRef, branch, worktreePath) =>
     set((state) => setThreadBranch(state, threadRef, branch, worktreePath)),
diff --git a/apps/web/src/storeSelectors.ts b/apps/web/src/storeSelectors.ts
index 02b88f31b18..95ed6ff1f41 100644
--- a/apps/web/src/storeSelectors.ts
+++ b/apps/web/src/storeSelectors.ts
@@ -1,6 +1,6 @@
 import { type ScopedProjectRef, type ScopedThreadRef, type ThreadId } from "@t3tools/contracts";
 import { selectEnvironmentState, type AppState, type EnvironmentState } from "./store";
-import { type Project, type SidebarThreadSummary, type Thread } from "./types";
+import { type Project, type Thread } from "./types";
 import { getThreadFromEnvironmentState } from "./threadDerivation";
 
 export function createProjectSelectorByRef(
@@ -10,15 +10,6 @@ export function createProjectSelectorByRef(
     ref ? selectEnvironmentState(state, ref.environmentId).projectById[ref.projectId] : undefined;
 }
 
-export function createSidebarThreadSummarySelectorByRef(
-  ref: ScopedThreadRef | null | undefined,
-): (state: AppState) => SidebarThreadSummary | undefined {
-  return (state) =>
-    ref
-      ? selectEnvironmentState(state, ref.environmentId).sidebarThreadSummaryById[ref.threadId]
-      : undefined;
-}
-
 function createScopedThreadSelector(
   resolveRef: (state: AppState) => ScopedThreadRef | null | undefined,
 ): (state: AppState) => Thread | undefined {
diff --git a/apps/web/src/terminal-links.ts b/apps/web/src/terminal-links.ts
index 0d40a90e415..a4eeda4279c 100644
--- a/apps/web/src/terminal-links.ts
+++ b/apps/web/src/terminal-links.ts
@@ -137,7 +137,7 @@ function inferHomeFromCwd(cwd: string): string | undefined {
   return undefined;
 }
 
-function splitPathAndPosition(value: string): {
+export function splitPathAndPosition(value: string): {
   path: string;
   line: string | undefined;
   column: string | undefined;
diff --git a/apps/web/src/timestampFormat.ts b/apps/web/src/timestampFormat.ts
index c39e4a6c7d3..4cf47a2c398 100644
--- a/apps/web/src/timestampFormat.ts
+++ b/apps/web/src/timestampFormat.ts
@@ -57,8 +57,7 @@ export function formatRelativeTime(isoDate: string): { value: string; suffix: st
   const diffMs = Date.now() - new Date(isoDate).getTime();
   if (diffMs < 0) return { value: "just now", suffix: null };
   const seconds = Math.floor(diffMs / 1000);
-  if (seconds < 5) return { value: "just now", suffix: null };
-  if (seconds < 60) return { value: `${seconds}s`, suffix: "ago" };
+  if (seconds < 60) return { value: "just now", suffix: null };
   const minutes = Math.floor(seconds / 60);
   if (minutes < 60) return { value: `${minutes}m`, suffix: "ago" };
   const hours = Math.floor(minutes / 60);
diff --git a/apps/web/src/types.ts b/apps/web/src/types.ts
index a5449757311..7c9fd41bba1 100644
--- a/apps/web/src/types.ts
+++ b/apps/web/src/types.ts
@@ -11,7 +11,8 @@ import type {
   ProjectId,
   TurnId,
   MessageId,
-  ProviderKind,
+  ProviderDriverKind,
+  ProviderInstanceId,
   CheckpointRef,
   ProviderInteractionMode,
   RuntimeMode,
@@ -158,7 +159,8 @@ export interface SidebarThreadSummary {
 }
 
 export interface ThreadSession {
-  provider: ProviderKind;
+  provider: ProviderDriverKind;
+  providerInstanceId?: ProviderInstanceId | undefined;
   status: SessionPhase | "error" | "closed";
   activeTurnId?: TurnId | undefined;
   createdAt: string;
diff --git a/apps/web/src/uiStateStore.test.ts b/apps/web/src/uiStateStore.test.ts
index c906bbc1d78..5d860fbb7fd 100644
--- a/apps/web/src/uiStateStore.test.ts
+++ b/apps/web/src/uiStateStore.test.ts
@@ -1,10 +1,16 @@
 import { ProjectId, ThreadId } from "@t3tools/contracts";
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
   clearThreadUi,
+  hydratePersistedProjectState,
+  markThreadVisited,
   markThreadUnread,
+  PERSISTED_STATE_KEY,
+  type PersistedUiState,
+  persistState,
   reorderProjects,
+  setDefaultAdvertisedEndpointKey,
   setProjectExpanded,
   setThreadChangedFilesExpanded,
   syncProjects,
@@ -18,11 +24,34 @@ function makeUiState(overrides: Partial<UiState> = {}): UiState {
     projectOrder: [],
     threadLastVisitedAtById: {},
     threadChangedFilesExpandedById: {},
+    defaultAdvertisedEndpointKey: null,
     ...overrides,
   };
 }
 
 describe("uiStateStore pure functions", () => {
+  it("markThreadVisited stores the provided server timestamp", () => {
+    const threadId = ThreadId.make("thread-1");
+    const initialState = makeUiState();
+
+    const next = markThreadVisited(initialState, threadId, "2026-02-25T12:30:00.700Z");
+
+    expect(next.threadLastVisitedAtById[threadId]).toBe("2026-02-25T12:30:00.700Z");
+  });
+
+  it("markThreadVisited does not move visit state backwards under clock skew", () => {
+    const threadId = ThreadId.make("thread-1");
+    const initialState = makeUiState({
+      threadLastVisitedAtById: {
+        [threadId]: "2026-02-25T12:30:00.700Z",
+      },
+    });
+
+    const next = markThreadVisited(initialState, threadId, "2026-02-25T12:30:00.000Z");
+
+    expect(next).toBe(initialState);
+  });
+
   it("markThreadUnread moves lastVisitedAt before completion for a completed thread", () => {
     const threadId = ThreadId.make("thread-1");
     const latestTurnCompletedAt = "2026-02-25T12:30:00.000Z";
@@ -75,6 +104,18 @@ describe("uiStateStore pure functions", () => {
     expect(next).toBe(initialState);
   });
 
+  it("setDefaultAdvertisedEndpointKey stores endpoint preference by stable key", () => {
+    const initialState = makeUiState();
+
+    const next = setDefaultAdvertisedEndpointKey(initialState, "desktop-core:lan:http");
+
+    expect(next.defaultAdvertisedEndpointKey).toBe("desktop-core:lan:http");
+    expect(setDefaultAdvertisedEndpointKey(next, "desktop-core:lan:http")).toBe(next);
+    expect(setDefaultAdvertisedEndpointKey(next, "")).toMatchObject({
+      defaultAdvertisedEndpointKey: null,
+    });
+  });
+
   it("reorderProjects moves all member keys of a multi-member group together", () => {
     const keyALocal = "env-local:proj-a";
     const keyARemote = "env-remote:proj-a";
@@ -183,40 +224,43 @@ describe("uiStateStore pure functions", () => {
     });
 
     const next = syncProjects(initialState, [
-      { key: project1, cwd: "/tmp/project-1" },
-      { key: project2, cwd: "/tmp/project-2" },
-      { key: project3, cwd: "/tmp/project-3" },
+      { key: project1, logicalKey: project1, cwd: "/tmp/project-1" },
+      { key: project2, logicalKey: project2, cwd: "/tmp/project-2" },
+      { key: project3, logicalKey: project3, cwd: "/tmp/project-3" },
     ]);
 
     expect(next.projectOrder).toEqual([project2, project1, project3]);
     expect(next.projectExpandedById[project2]).toBe(false);
   });
 
-  it("syncProjects preserves manual order when a project is recreated with the same cwd", () => {
-    const oldProject1 = ProjectId.make("project-1");
-    const oldProject2 = ProjectId.make("project-2");
-    const recreatedProject2 = ProjectId.make("project-2b");
+  it("syncProjects preserves manual order across project id churn at the same cwd", () => {
+    // Under the current design, physical key and logical key are both
+    // cwd-derived, so an internal project-id change doesn't alter the store
+    // keys. This test locks in that stability: re-syncing the same cwds keeps
+    // manual order and collapse state.
+    const keyProject1 = "env-local:/tmp/project-1";
+    const keyProject2 = "env-local:/tmp/project-2";
     const initialState = syncProjects(
       makeUiState({
         projectExpandedById: {
-          [oldProject1]: true,
-          [oldProject2]: false,
+          [keyProject1]: true,
+          [keyProject2]: false,
         },
-        projectOrder: [oldProject2, oldProject1],
+        projectOrder: [keyProject2, keyProject1],
       }),
       [
-        { key: oldProject1, cwd: "/tmp/project-1" },
-        { key: oldProject2, cwd: "/tmp/project-2" },
+        { key: keyProject1, logicalKey: keyProject1, cwd: "/tmp/project-1" },
+        { key: keyProject2, logicalKey: keyProject2, cwd: "/tmp/project-2" },
       ],
     );
 
     const next = syncProjects(initialState, [
-      { key: oldProject1, cwd: "/tmp/project-1" },
-      { key: recreatedProject2, cwd: "/tmp/project-2" },
+      { key: keyProject1, logicalKey: keyProject1, cwd: "/tmp/project-1" },
+      { key: keyProject2, logicalKey: keyProject2, cwd: "/tmp/project-2" },
     ]);
 
-    expect(next.projectOrder).toEqual([recreatedProject2, oldProject1]);
-    expect(next.projectExpandedById[recreatedProject2]).toBe(false);
+    expect(next.projectOrder).toEqual([keyProject2, keyProject1]);
+    expect(next.projectExpandedById[keyProject2]).toBe(false);
   });
 
   it("syncProjects returns a new state when only project cwd changes", () => {
@@ -228,16 +272,70 @@ describe("uiStateStore pure functions", () => {
         },
         projectOrder: [project1],
       }),
-      [{ key: project1, cwd: "/tmp/project-1" }],
+      [{ key: project1, logicalKey: project1, cwd: "/tmp/project-1" }],
     );
 
-    const next = syncProjects(initialState, [{ key: project1, cwd: "/tmp/project-1-renamed" }]);
+    const next = syncProjects(initialState, [
+      { key: project1, logicalKey: project1, cwd: "/tmp/project-1-renamed" },
+    ]);
 
     expect(next).not.toBe(initialState);
     expect(next.projectOrder).toEqual([project1]);
     expect(next.projectExpandedById[project1]).toBe(false);
   });
 
+  it("syncProjects keys projectExpandedById by the logical key, not the physical key", () => {
+    // In repository grouping mode, multiple physical projects (different
+    // environments or different repo-relative paths) collapse into one
+    // logical group. The group's expand state must be keyed by the logical
+    // key so clicks on the grouped row toggle the shared state, and so the
+    // state survives subsequent syncProjects calls (which rebuild the map
+    // from incoming inputs).
+    const physicalLocal = "env-local:/repo/project";
+    const physicalRemote = "env-remote:/repo/project";
+    const logicalKey = "repo-canonical-key";
+
+    const initial = syncProjects(makeUiState(), [
+      { key: physicalLocal, logicalKey, cwd: "/repo/project" },
+      { key: physicalRemote, logicalKey, cwd: "/repo/project" },
+    ]);
+
+    expect(initial.projectExpandedById).toEqual({ [logicalKey]: true });
+
+    const afterCollapse = { ...initial, projectExpandedById: { [logicalKey]: false } };
+    const next = syncProjects(afterCollapse, [
+      { key: physicalLocal, logicalKey, cwd: "/repo/project" },
+      { key: physicalRemote, logicalKey, cwd: "/repo/project" },
+    ]);
+
+    expect(next.projectExpandedById[logicalKey]).toBe(false);
+  });
+
+  it("syncProjects preserves expand state when a project's logical key changes", () => {
+    // Example: late-arriving repo metadata flips grouping identity from the
+    // physical key to a canonical repository key. The row did not actually
+    // change, so the user's collapse choice must carry over.
+    const physicalKey = "env-local:/repo/project";
+    const previousLogicalKey = physicalKey;
+    const nextLogicalKey = "repo-canonical-key";
+
+    const initial = syncProjects(makeUiState(), [
+      { key: physicalKey, logicalKey: previousLogicalKey, cwd: "/repo/project" },
+    ]);
+
+    expect(initial.projectExpandedById[previousLogicalKey]).toBe(true);
+
+    const afterCollapse = {
+      ...initial,
+      projectExpandedById: { [previousLogicalKey]: false },
+    };
+    const next = syncProjects(afterCollapse, [
+      { key: physicalKey, logicalKey: nextLogicalKey, cwd: "/repo/project" },
+    ]);
+
+    expect(next.projectExpandedById[nextLogicalKey]).toBe(false);
+  });
+
   it("syncThreads prunes missing thread UI state", () => {
     const thread1 = ThreadId.make("thread-1");
     const thread2 = ThreadId.make("thread-2");
@@ -346,3 +444,167 @@ describe("uiStateStore pure functions", () => {
     expect(next.threadChangedFilesExpandedById).toEqual({});
   });
 });
+
+function createLocalStorageStub(): Storage {
+  const store = new Map<string, string>();
+  return {
+    clear: () => {
+      store.clear();
+    },
+    getItem: (key) => store.get(key) ?? null,
+    key: (index) => [...store.keys()][index] ?? null,
+    get length() {
+      return store.size;
+    },
+    removeItem: (key) => {
+      store.delete(key);
+    },
+    setItem: (key, value) => {
+      store.set(key, value);
+    },
+  };
+}
+
+describe("uiStateStore persistence round-trip", () => {
+  let localStorageStub: Storage;
+
+  beforeEach(() => {
+    localStorageStub = createLocalStorageStub();
+    vi.stubGlobal("window", { localStorage: localStorageStub });
+    vi.stubGlobal("localStorage", localStorageStub);
+    // Reset module-level persistence state so tests don't bleed into each other.
+    hydratePersistedProjectState({ collapsedProjectCwds: [], expandedProjectCwds: [] });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("preserves all-collapsed project state across restart", () => {
+    // Regression: pre-fix, persistState only wrote `expandedProjectCwds`, so
+    // an empty array on rehydrate was indistinguishable from a fresh install
+    // and the syncProjects fallback re-expanded every row.
+    const projectA = { key: "kA", logicalKey: "kA", cwd: "/projA" };
+    const projectB = { key: "kB", logicalKey: "kB", cwd: "/projB" };
+
+    let state = syncProjects(makeUiState(), [projectA, projectB]);
+    state = setProjectExpanded(state, projectA.key, false);
+    state = setProjectExpanded(state, projectB.key, false);
+    persistState(state);
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+    hydratePersistedProjectState(persisted);
+    const rehydrated = syncProjects(makeUiState(), [projectA, projectB]);
+
+    expect(rehydrated.projectExpandedById).toEqual({
+      [projectA.key]: false,
+      [projectB.key]: false,
+    });
+  });
+
+  it("respects mixed expand state on rehydrate and defaults new projects to expanded", () => {
+    const projectA = { key: "kA", logicalKey: "kA", cwd: "/projA" };
+    const projectB = { key: "kB", logicalKey: "kB", cwd: "/projB" };
+    const projectC = { key: "kC", logicalKey: "kC", cwd: "/projC" };
+
+    let state = syncProjects(makeUiState(), [projectA, projectB]);
+    state = setProjectExpanded(state, projectB.key, false);
+    persistState(state);
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+    hydratePersistedProjectState(persisted);
+    const rehydrated = syncProjects(makeUiState(), [projectA, projectB, projectC]);
+
+    expect(rehydrated.projectExpandedById).toEqual({
+      [projectA.key]: true,
+      [projectB.key]: false,
+      [projectC.key]: true,
+    });
+  });
+
+  it("preserves legacy not-in-expanded-list = collapsed for one upgrade session", () => {
+    // Pre-fix shape only stored expandedProjectCwds. Absence of
+    // collapsedProjectCwds opts the session into the legacy fallback so
+    // upgrade users do not see previously collapsed rows pop open.
+    hydratePersistedProjectState({
+      expandedProjectCwds: ["/projA"],
+    });
+
+    const rehydrated = syncProjects(makeUiState(), [
+      { key: "kA", logicalKey: "kA", cwd: "/projA" },
+      { key: "kB", logicalKey: "kB", cwd: "/projB" },
+    ]);
+
+    expect(rehydrated.projectExpandedById).toEqual({
+      kA: true,
+      kB: false,
+    });
+  });
+
+  it("preserves manual project order across restart", () => {
+    const projectA = { key: "kOrderA", logicalKey: "kOrderA", cwd: "/order-projA" };
+    const projectB = { key: "kOrderB", logicalKey: "kOrderB", cwd: "/order-projB" };
+    const projectC = { key: "kOrderC", logicalKey: "kOrderC", cwd: "/order-projC" };
+
+    let state = syncProjects(makeUiState(), [projectA, projectB, projectC]);
+    state = reorderProjects(state, [projectC.key], [projectA.key]);
+    expect(state.projectOrder).toEqual([projectC.key, projectA.key, projectB.key]);
+    persistState(state);
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+    expect(persisted.projectOrderCwds).toEqual([projectC.cwd, projectA.cwd, projectB.cwd]);
+
+    hydratePersistedProjectState(persisted);
+    // Fresh state (empty projectOrder) so syncProjects derives order from
+    // persistedProjectOrderCwds rather than the in-memory projectOrder branch.
+    const rehydrated = syncProjects(makeUiState(), [projectA, projectB, projectC]);
+
+    expect(rehydrated.projectOrder).toEqual([projectC.key, projectA.key, projectB.key]);
+  });
+
+  it("persists the default advertised endpoint preference", () => {
+    const state = setDefaultAdvertisedEndpointKey(makeUiState(), "desktop-core:lan:http");
+
+    persistState(state);
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+    expect(persisted.defaultAdvertisedEndpointKey).toBe("desktop-core:lan:http");
+  });
+
+  it("preserves expand state across restart when project's logical key changes", () => {
+    // After restart, in-memory previousExpandedById is empty, so the
+    // previousLogicalKey-to-state bridge in syncProjects cannot help. The
+    // persisted-cwd fallback is the only mechanism that can carry collapse
+    // state across a restart that also flips a project into a new logical
+    // group (e.g. late-arriving repo metadata). This locks in that path.
+    const physicalKey = "env-local:/lk-restart-proj";
+    const previousLogicalKey = physicalKey;
+    const cwd = "/lk-restart-proj";
+
+    let state = syncProjects(makeUiState(), [
+      { key: physicalKey, logicalKey: previousLogicalKey, cwd },
+    ]);
+    state = setProjectExpanded(state, previousLogicalKey, false);
+    persistState(state);
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+    hydratePersistedProjectState(persisted);
+
+    const nextLogicalKey = "lk-restart-canonical";
+    const rehydrated = syncProjects(makeUiState(), [
+      { key: physicalKey, logicalKey: nextLogicalKey, cwd },
+    ]);
+
+    expect(rehydrated.projectExpandedById[nextLogicalKey]).toBe(false);
+  });
+});
diff --git a/apps/web/src/uiStateStore.ts b/apps/web/src/uiStateStore.ts
index 7ae72320630..b76f5f6859a 100644
--- a/apps/web/src/uiStateStore.ts
+++ b/apps/web/src/uiStateStore.ts
@@ -1,7 +1,7 @@
 import { Debouncer } from "@tanstack/react-pacer";
 import { create } from "zustand";
 
-const PERSISTED_STATE_KEY = "t3code:ui-state:v1";
+export const PERSISTED_STATE_KEY = "t3code:ui-state:v1";
 const LEGACY_PERSISTED_STATE_KEYS = [
   "t3code:renderer-state:v8",
   "t3code:renderer-state:v7",
@@ -15,9 +15,11 @@ const LEGACY_PERSISTED_STATE_KEYS = [
   "codething:renderer-state:v1",
 ] as const;
 
-interface PersistedUiState {
+export interface PersistedUiState {
+  collapsedProjectCwds?: string[];
   expandedProjectCwds?: string[];
   projectOrderCwds?: string[];
+  defaultAdvertisedEndpointKey?: string | null;
   threadChangedFilesExpandedById?: Record<string, Record<string, boolean>>;
 }
 
@@ -31,10 +33,17 @@ export interface UiThreadState {
   threadChangedFilesExpandedById: Record<string, Record<string, boolean>>;
 }
 
-export interface UiState extends UiProjectState, UiThreadState {}
+export interface UiEndpointState {
+  defaultAdvertisedEndpointKey: string | null;
+}
+
+export interface UiState extends UiProjectState, UiThreadState, UiEndpointState {}
 
 export interface SyncProjectInput {
+  /** Physical project key (env + cwd). Used for manual sort order. */
   key: string;
+  /** Logical group key. Used for expand/collapse state. */
+  logicalKey: string;
   cwd: string;
 }
 
@@ -48,11 +57,20 @@ const initialState: UiState = {
   projectOrder: [],
   threadLastVisitedAtById: {},
   threadChangedFilesExpandedById: {},
+  defaultAdvertisedEndpointKey: null,
 };
 
+const persistedCollapsedProjectCwds = new Set<string>();
 const persistedExpandedProjectCwds = new Set<string>();
 const persistedProjectOrderCwds: string[] = [];
+// Pre-fix persisted shape only listed expanded cwds, so anything not listed
+// was treated as collapsed. Track whether the loaded blob carried the new
+// `collapsedProjectCwds` field so we can preserve that legacy semantic for
+// one session after upgrade, until persistState rewrites in the new shape.
+let persistedProjectStateUsesLegacyShape = false;
 const currentProjectCwdById = new Map<string, string>();
+const currentProjectCwdsByLogicalKey = new Map<string, string[]>();
+const currentLogicalKeyByPhysicalKey = new Map<string, string>();
 let legacyKeysCleanedUp = false;
 
 function readPersistedState(): UiState {
@@ -76,6 +94,11 @@ function readPersistedState(): UiState {
     hydratePersistedProjectState(parsed);
     return {
       ...initialState,
+      defaultAdvertisedEndpointKey:
+        typeof parsed.defaultAdvertisedEndpointKey === "string" &&
+        parsed.defaultAdvertisedEndpointKey.length > 0
+          ? parsed.defaultAdvertisedEndpointKey
+          : null,
       threadChangedFilesExpandedById: sanitizePersistedThreadChangedFilesExpanded(
         parsed.threadChangedFilesExpandedById,
       ),
@@ -113,9 +136,16 @@ function sanitizePersistedThreadChangedFilesExpanded(
   return nextState;
 }
 
-function hydratePersistedProjectState(parsed: PersistedUiState): void {
+export function hydratePersistedProjectState(parsed: PersistedUiState): void {
+  persistedCollapsedProjectCwds.clear();
   persistedExpandedProjectCwds.clear();
   persistedProjectOrderCwds.length = 0;
+  persistedProjectStateUsesLegacyShape = !Array.isArray(parsed.collapsedProjectCwds);
+  for (const cwd of parsed.collapsedProjectCwds ?? []) {
+    if (typeof cwd === "string" && cwd.length > 0) {
+      persistedCollapsedProjectCwds.add(cwd);
+    }
+  }
   for (const cwd of parsed.expandedProjectCwds ?? []) {
     if (typeof cwd === "string" && cwd.length > 0) {
       persistedExpandedProjectCwds.add(cwd);
@@ -128,17 +158,20 @@ function hydratePersistedProjectState(parsed: PersistedUiState): void {
   }
 }
 
-function persistState(state: UiState): void {
+export function persistState(state: UiState): void {
   if (typeof window === "undefined") {
     return;
   }
   try {
+    // Persist collapsed cwds explicitly so an empty/missing field unambiguously
+    // means "first install" rather than "user collapsed everything"; without
+    // this, the syncProjects fallback would re-expand all rows on next launch.
+    const collapsedProjectCwds = Object.entries(state.projectExpandedById)
+      .filter(([, expanded]) => !expanded)
+      .flatMap(([logicalKey]) => currentProjectCwdsByLogicalKey.get(logicalKey) ?? []);
     const expandedProjectCwds = Object.entries(state.projectExpandedById)
       .filter(([, expanded]) => expanded)
-      .flatMap(([projectId]) => {
-        const cwd = currentProjectCwdById.get(projectId);
-        return cwd ? [cwd] : [];
-      });
+      .flatMap(([logicalKey]) => currentProjectCwdsByLogicalKey.get(logicalKey) ?? []);
     const projectOrderCwds = state.projectOrder.flatMap((projectId) => {
       const cwd = currentProjectCwdById.get(projectId);
       return cwd ? [cwd] : [];
@@ -154,8 +187,10 @@ function persistState(state: UiState): void {
     window.localStorage.setItem(
       PERSISTED_STATE_KEY,
       JSON.stringify({
+        collapsedProjectCwds,
         expandedProjectCwds,
         projectOrderCwds,
+        defaultAdvertisedEndpointKey: state.defaultAdvertisedEndpointKey,
         threadChangedFilesExpandedById,
       } satisfies PersistedUiState),
     );
@@ -211,12 +246,40 @@ function nestedBooleanRecordsEqual(
 
 export function syncProjects(state: UiState, projects: readonly SyncProjectInput[]): UiState {
   const previousProjectCwdById = new Map(currentProjectCwdById);
-  const previousProjectIdByCwd = new Map(
-    [...previousProjectCwdById.entries()].map(([projectId, cwd]) => [cwd, projectId] as const),
-  );
+  const previousLogicalKeyByPhysicalKey = new Map(currentLogicalKeyByPhysicalKey);
   currentProjectCwdById.clear();
+  currentLogicalKeyByPhysicalKey.clear();
   for (const project of projects) {
     currentProjectCwdById.set(project.key, project.cwd);
+    currentLogicalKeyByPhysicalKey.set(project.key, project.logicalKey);
+  }
+  currentProjectCwdsByLogicalKey.clear();
+  for (const project of projects) {
+    const cwds = currentProjectCwdsByLogicalKey.get(project.logicalKey);
+    if (cwds) {
+      if (!cwds.includes(project.cwd)) {
+        cwds.push(project.cwd);
+      }
+    } else {
+      currentProjectCwdsByLogicalKey.set(project.logicalKey, [project.cwd]);
+    }
+  }
+  // Build reverse map: for each new logical key, which previous logical keys
+  // did its member projects live under? Lets us preserve expand state when a
+  // project's logical key changes (e.g. late-arriving repo metadata flips the
+  // group identity).
+  const previousLogicalKeysByNewLogicalKey = new Map<string, Set<string>>();
+  for (const project of projects) {
+    const previousLogicalKey = previousLogicalKeyByPhysicalKey.get(project.key);
+    if (!previousLogicalKey || previousLogicalKey === project.logicalKey) {
+      continue;
+    }
+    const set = previousLogicalKeysByNewLogicalKey.get(project.logicalKey);
+    if (set) {
+      set.add(previousLogicalKey);
+    } else {
+      previousLogicalKeysByNewLogicalKey.set(project.logicalKey, new Set([previousLogicalKey]));
+    }
   }
   const cwdMappingChanged =
     previousProjectCwdById.size !== currentProjectCwdById.size ||
@@ -228,14 +291,38 @@ export function syncProjects(state: UiState, projects: readonly SyncProjectInput
     persistedProjectOrderCwds.map((cwd, index) => [cwd, index] as const),
   );
   const mappedProjects = projects.map((project, index) => {
-    const previousProjectIdForCwd = previousProjectIdByCwd.get(project.cwd);
-    const expanded =
-      previousExpandedById[project.key] ??
-      (previousProjectIdForCwd ? previousExpandedById[previousProjectIdForCwd] : undefined) ??
-      (persistedExpandedProjectCwds.size > 0
-        ? persistedExpandedProjectCwds.has(project.cwd)
-        : true);
-    nextExpandedById[project.key] = expanded;
+    if (!(project.logicalKey in nextExpandedById)) {
+      const groupCwds = currentProjectCwdsByLogicalKey.get(project.logicalKey) ?? [project.cwd];
+      const fallbackFromPreviousLogicalKey = (() => {
+        const previousKeys = previousLogicalKeysByNewLogicalKey.get(project.logicalKey);
+        if (!previousKeys) {
+          return undefined;
+        }
+        for (const previousKey of previousKeys) {
+          if (previousKey in previousExpandedById) {
+            return previousExpandedById[previousKey];
+          }
+        }
+        return undefined;
+      })();
+      const fallbackFromPersistedShape = (() => {
+        if (groupCwds.some((cwd) => persistedExpandedProjectCwds.has(cwd))) {
+          return true;
+        }
+        if (groupCwds.some((cwd) => persistedCollapsedProjectCwds.has(cwd))) {
+          return false;
+        }
+        if (persistedProjectStateUsesLegacyShape && persistedExpandedProjectCwds.size > 0) {
+          return false;
+        }
+        return true;
+      })();
+      const expanded =
+        previousExpandedById[project.logicalKey] ??
+        fallbackFromPreviousLogicalKey ??
+        fallbackFromPersistedShape;
+      nextExpandedById[project.logicalKey] = expanded;
+    }
     return {
       id: project.key,
       cwd: project.cwd,
@@ -246,6 +333,7 @@ export function syncProjects(state: UiState, projects: readonly SyncProjectInput
   const nextProjectOrder =
     state.projectOrder.length > 0
       ? (() => {
+          const currentProjectIds = new Set(mappedProjects.map((project) => project.id));
           const nextProjectIdByCwd = new Map(
             mappedProjects.map((project) => [project.cwd, project.id] as const),
           );
@@ -254,7 +342,7 @@ export function syncProjects(state: UiState, projects: readonly SyncProjectInput
 
           for (const projectId of state.projectOrder) {
             const matchedProjectId =
-              (projectId in nextExpandedById ? projectId : undefined) ??
+              (currentProjectIds.has(projectId) ? projectId : undefined) ??
               (() => {
                 const previousCwd = previousProjectCwdById.get(projectId);
                 return previousCwd ? nextProjectIdByCwd.get(previousCwd) : undefined;
@@ -456,6 +544,17 @@ export function setThreadChangedFilesExpanded(
   };
 }
 
+export function setDefaultAdvertisedEndpointKey(state: UiState, key: string | null): UiState {
+  const nextKey = key && key.length > 0 ? key : null;
+  if (state.defaultAdvertisedEndpointKey === nextKey) {
+    return state;
+  }
+  return {
+    ...state,
+    defaultAdvertisedEndpointKey: nextKey,
+  };
+}
+
 export function toggleProject(state: UiState, projectId: string): UiState {
   const expanded = state.projectExpandedById[projectId] ?? true;
   return {
@@ -530,6 +629,7 @@ interface UiStateStore extends UiState {
   markThreadUnread: (threadId: string, latestTurnCompletedAt: string | null | undefined) => void;
   clearThreadUi: (threadId: string) => void;
   setThreadChangedFilesExpanded: (threadId: string, turnId: string, expanded: boolean) => void;
+  setDefaultAdvertisedEndpointKey: (key: string | null) => void;
   toggleProject: (projectId: string) => void;
   setProjectExpanded: (projectId: string, expanded: boolean) => void;
   reorderProjects: (
@@ -549,6 +649,8 @@ export const useUiStateStore = create<UiStateStore>((set) => ({
   clearThreadUi: (threadId) => set((state) => clearThreadUi(state, threadId)),
   setThreadChangedFilesExpanded: (threadId, turnId, expanded) =>
     set((state) => setThreadChangedFilesExpanded(state, threadId, turnId, expanded)),
+  setDefaultAdvertisedEndpointKey: (key) =>
+    set((state) => setDefaultAdvertisedEndpointKey(state, key)),
   toggleProject: (projectId) => set((state) => toggleProject(state, projectId)),
   setProjectExpanded: (projectId, expanded) =>
     set((state) => setProjectExpanded(state, projectId, expanded)),
diff --git a/apps/web/src/versionSkew.test.ts b/apps/web/src/versionSkew.test.ts
new file mode 100644
index 00000000000..01c4985565a
--- /dev/null
+++ b/apps/web/src/versionSkew.test.ts
@@ -0,0 +1,78 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+
+import { APP_VERSION } from "./branding";
+import {
+  appendVersionMismatchHint,
+  buildVersionMismatchDismissalKey,
+  dismissVersionMismatch,
+  isVersionMismatchDismissed,
+  resolveServerConfigVersionMismatch,
+  resolveVersionMismatch,
+} from "./versionSkew";
+
+describe("versionSkew", () => {
+  it("does not warn when versions match", () => {
+    expect(resolveVersionMismatch(APP_VERSION)).toBeNull();
+  });
+
+  it("returns a mismatch when the server version differs from the client", () => {
+    expect(resolveVersionMismatch("9.9.9")).toEqual({
+      clientVersion: APP_VERSION,
+      serverVersion: "9.9.9",
+      hint: "Version mismatch. Try syncing the client and server to the same T3 Code version.",
+    });
+  });
+
+  it("reads the server version from config descriptors", () => {
+    expect(
+      resolveServerConfigVersionMismatch({
+        environment: {
+          environmentId: EnvironmentId.make("environment-1"),
+          label: "Remote",
+          platform: {
+            os: "darwin",
+            arch: "arm64",
+          },
+          serverVersion: "9.9.9",
+          capabilities: {
+            repositoryIdentity: true,
+          },
+        },
+      }),
+    ).toMatchObject({
+      serverVersion: "9.9.9",
+    });
+  });
+
+  it("keys dismissals by environment, client version, and server version", () => {
+    const environmentId = EnvironmentId.make("environment-dismissal");
+    const key = buildVersionMismatchDismissalKey(environmentId, {
+      clientVersion: APP_VERSION,
+      serverVersion: "9.9.9",
+    });
+
+    expect(key).toBe(`${environmentId}:${APP_VERSION}:9.9.9`);
+    expect(isVersionMismatchDismissed(key)).toBe(false);
+
+    dismissVersionMismatch(key);
+
+    expect(isVersionMismatchDismissed(key)).toBe(true);
+    expect(
+      isVersionMismatchDismissed(
+        buildVersionMismatchDismissalKey(environmentId, {
+          clientVersion: APP_VERSION,
+          serverVersion: "9.9.10",
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it("appends a hint to connection errors when versions differ", () => {
+    const mismatch = resolveVersionMismatch("9.9.9");
+
+    expect(appendVersionMismatchHint("Socket closed.", mismatch)).toBe(
+      "Socket closed. Hint: Version mismatch. Try syncing the client and server to the same T3 Code version.",
+    );
+  });
+});
diff --git a/apps/web/src/versionSkew.ts b/apps/web/src/versionSkew.ts
new file mode 100644
index 00000000000..cb0116c8550
--- /dev/null
+++ b/apps/web/src/versionSkew.ts
@@ -0,0 +1,116 @@
+import type { EnvironmentId, ServerConfig } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+
+import { APP_VERSION } from "./branding";
+import { getLocalStorageItem, setLocalStorageItem } from "./hooks/useLocalStorage";
+
+export interface VersionMismatch {
+  readonly clientVersion: string;
+  readonly serverVersion: string;
+  readonly hint: string;
+}
+
+export const VERSION_MISMATCH_DISMISSALS_STORAGE_KEY = "t3code:version-mismatch-dismissals:v1";
+
+const VersionMismatchDismissalsSchema = Schema.Struct({
+  keys: Schema.Array(Schema.String),
+});
+
+type VersionMismatchDismissals = typeof VersionMismatchDismissalsSchema.Type;
+
+function normalizeVersion(version: string | null | undefined): string | null {
+  const trimmed = version?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : null;
+}
+
+export function resolveVersionMismatch(
+  serverVersion: string | null | undefined,
+): VersionMismatch | null {
+  const normalizedClientVersion = normalizeVersion(APP_VERSION);
+  const normalizedServerVersion = normalizeVersion(serverVersion);
+  if (
+    !normalizedClientVersion ||
+    !normalizedServerVersion ||
+    normalizedClientVersion === normalizedServerVersion
+  ) {
+    return null;
+  }
+
+  return {
+    clientVersion: normalizedClientVersion,
+    serverVersion: normalizedServerVersion,
+    hint: "Version mismatch. Try syncing the client and server to the same T3 Code version.",
+  };
+}
+
+export function resolveServerConfigVersionMismatch(
+  serverConfig: Pick<ServerConfig, "environment"> | null | undefined,
+): VersionMismatch | null {
+  return resolveVersionMismatch(serverConfig?.environment.serverVersion);
+}
+
+export function buildVersionMismatchDismissalKey(
+  environmentId: EnvironmentId,
+  mismatch: Pick<VersionMismatch, "clientVersion" | "serverVersion">,
+): string {
+  return `${environmentId}:${mismatch.clientVersion}:${mismatch.serverVersion}`;
+}
+
+function readVersionMismatchDismissals(): VersionMismatchDismissals {
+  try {
+    return (
+      getLocalStorageItem(
+        VERSION_MISMATCH_DISMISSALS_STORAGE_KEY,
+        VersionMismatchDismissalsSchema,
+      ) ?? { keys: [] }
+    );
+  } catch {
+    return { keys: [] };
+  }
+}
+
+function writeVersionMismatchDismissals(document: VersionMismatchDismissals): void {
+  try {
+    setLocalStorageItem(
+      VERSION_MISMATCH_DISMISSALS_STORAGE_KEY,
+      document,
+      VersionMismatchDismissalsSchema,
+    );
+  } catch {
+    // Dismissal state is best-effort UI state; a storage failure should not block the banner.
+  }
+}
+
+export function isVersionMismatchDismissed(dismissalKey: string | null | undefined): boolean {
+  if (!dismissalKey) {
+    return false;
+  }
+  return readVersionMismatchDismissals().keys.includes(dismissalKey);
+}
+
+export function dismissVersionMismatch(dismissalKey: string | null | undefined): void {
+  if (!dismissalKey) {
+    return;
+  }
+  const document = readVersionMismatchDismissals();
+  if (document.keys.includes(dismissalKey)) {
+    return;
+  }
+  writeVersionMismatchDismissals({
+    keys: [...document.keys, dismissalKey],
+  });
+}
+
+export function appendVersionMismatchHint(
+  message: string | null | undefined,
+  mismatch: VersionMismatch | null | undefined,
+): string | null {
+  const normalizedMessage = normalizeVersion(message);
+  if (!normalizedMessage) {
+    return mismatch?.hint ?? null;
+  }
+  if (!mismatch) {
+    return normalizedMessage;
+  }
+  return `${normalizedMessage} Hint: ${mismatch.hint}`;
+}
diff --git a/apps/web/src/vite-env.d.ts b/apps/web/src/vite-env.d.ts
index 1d7d41db1bc..75ee936603c 100644
--- a/apps/web/src/vite-env.d.ts
+++ b/apps/web/src/vite-env.d.ts
@@ -3,6 +3,10 @@
 import type { DesktopBridge, LocalApi } from "@t3tools/contracts";
 
 interface ImportMetaEnv {
+  readonly VITE_HTTP_URL: string;
+  readonly VITE_WS_URL: string;
+  readonly VITE_HOSTED_APP_URL: string;
+  readonly VITE_HOSTED_APP_CHANNEL: string;
   readonly APP_VERSION: string;
 }
 
diff --git a/apps/web/src/worktreeCleanup.test.ts b/apps/web/src/worktreeCleanup.test.ts
index bdd5bb12a06..9c833c03c74 100644
--- a/apps/web/src/worktreeCleanup.test.ts
+++ b/apps/web/src/worktreeCleanup.test.ts
@@ -1,4 +1,4 @@
-import { EnvironmentId, ProjectId, ThreadId } from "@t3tools/contracts";
+import { EnvironmentId, ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 
 import { DEFAULT_INTERACTION_MODE, DEFAULT_RUNTIME_MODE, type Thread } from "./types";
@@ -14,7 +14,7 @@ function makeThread(overrides: Partial<Thread> = {}): Thread {
     projectId: ProjectId.make("project-1"),
     title: "Thread",
     modelSelection: {
-      provider: "codex",
+      instanceId: ProviderInstanceId.make("codex"),
       model: "gpt-5.3-codex",
     },
     runtimeMode: DEFAULT_RUNTIME_MODE,
diff --git a/apps/web/test/wsRpcHarness.ts b/apps/web/test/wsRpcHarness.ts
index f5d86a50194..2609464c1d7 100644
--- a/apps/web/test/wsRpcHarness.ts
+++ b/apps/web/test/wsRpcHarness.ts
@@ -1,5 +1,9 @@
-import { Effect, Exit, PubSub, Scope, Stream } from "effect";
-import { WS_METHODS, WsRpcGroup } from "@t3tools/contracts";
+import { ORCHESTRATION_WS_METHODS, WS_METHODS, WsRpcGroup } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as PubSub from "effect/PubSub";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import { RpcMessage, RpcSerialization, RpcServer } from "effect/unstable/rpc";
 
 type RpcServerInstance = RpcServer.RpcServer<any>;
@@ -23,9 +27,10 @@ interface BrowserWsRpcHarnessOptions {
 }
 
 const STREAM_METHODS = new Set<string>([
+  ORCHESTRATION_WS_METHODS.subscribeShell,
+  ORCHESTRATION_WS_METHODS.subscribeThread,
   WS_METHODS.gitRunStackedAction,
-  WS_METHODS.subscribeGitStatus,
-  WS_METHODS.subscribeOrchestrationDomainEvents,
+  WS_METHODS.subscribeVcsStatus,
   WS_METHODS.subscribeTerminalEvents,
   WS_METHODS.subscribeServerConfig,
   WS_METHODS.subscribeServerLifecycle,
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 178f4bcbabf..0a23203c7b0 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -2,6 +2,10 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "composite": true,
+    "module": "Preserve",
+    "moduleResolution": "Bundler",
+    "erasableSyntaxOnly": false,
+    "verbatimModuleSyntax": false,
     "jsx": "react-jsx",
     "lib": ["ES2023", "DOM", "DOM.Iterable"],
     "types": ["vite/client"],
@@ -11,15 +15,25 @@
     "plugins": [
       {
         "name": "@effect/language-service",
-        "namespaceImportPackages": ["@effect/platform-node"],
+        "namespaceImportPackages": ["@effect/platform-node", "effect"],
         "diagnosticSeverity": {
           "importFromBarrel": "error",
-          "anyUnknownInErrorContext": "warning",
-          "instanceOfSchema": "warning",
-          "deterministicKeys": "warning"
+          "anyUnknownInErrorContext": "error",
+          "unsafeEffectTypeAssertion": "error",
+          "instanceOfSchema": "error",
+          "deterministicKeys": "error",
+          "strictEffectProvide": "off",
+          "missingEffectServiceDependency": "error",
+          "leakingRequirements": "error",
+          "globalErrorInEffectCatch": "error",
+          "globalErrorInEffectFailure": "error",
+          "unknownInEffectCatch": "error",
+          "strictBooleanExpressions": "off",
+          "preferSchemaOverJson": "error",
+          "schemaSyncInEffect": "error"
         }
       }
     ]
   },
-  "include": ["src", "vite.config.ts", "test"]
+  "include": ["src", "vite.config.ts", "vercel.ts", "test"]
 }
diff --git a/apps/web/vercel.ts b/apps/web/vercel.ts
new file mode 100644
index 00000000000..a0aeb57fb1f
--- /dev/null
+++ b/apps/web/vercel.ts
@@ -0,0 +1,66 @@
+import { matchers, routes, type Transform, type VercelConfig } from "@vercel/config/v1";
+
+const ROUTER_HOST = "app.t3.codes";
+const HOSTED_WEB_CHANNEL_COOKIE = "t3code_web_channel";
+const LATEST_ORIGIN = "https://latest.app.t3.codes";
+const NIGHTLY_ORIGIN = "https://nightly.app.t3.codes";
+const CLEAN_CHANNEL_QUERY_TRANSFORMS = [
+  {
+    type: "request.query",
+    op: "delete",
+    target: { key: "channel" },
+  },
+] satisfies Transform[];
+
+function channelCookie(channel: "latest" | "nightly"): string {
+  return [
+    `${HOSTED_WEB_CHANNEL_COOKIE}=${channel}`,
+    "Path=/",
+    "Max-Age=31536000",
+    "HttpOnly",
+    "Secure",
+    "SameSite=Lax",
+  ].join("; ");
+}
+
+export const config: VercelConfig = {
+  buildCommand:
+    'turbo build --filter @t3tools/web && bun ../../scripts/apply-web-brand-assets.ts --channel "${VITE_HOSTED_APP_CHANNEL:-latest}"',
+  git: {
+    deploymentEnabled: false,
+  },
+  installCommand:
+    "bun add -g turbo && bun install --filter '@t3tools/contracts' --filter '@t3tools/client-runtime' --filter '@t3tools/scripts' --filter '@t3tools/web'",
+  routes: [
+    {
+      src: "/__t3code/channel",
+      has: [matchers.query("channel", "nightly")],
+      transforms: CLEAN_CHANNEL_QUERY_TRANSFORMS,
+      headers: {
+        Location: "/",
+        "Set-Cookie": channelCookie("nightly"),
+      },
+      status: 302,
+    },
+    {
+      src: "/__t3code/channel",
+      transforms: CLEAN_CHANNEL_QUERY_TRANSFORMS,
+      headers: {
+        Location: "/",
+        "Set-Cookie": channelCookie("latest"),
+      },
+      status: 302,
+    },
+    {
+      src: "/(.*)",
+      has: [matchers.host(ROUTER_HOST), matchers.cookie(HOSTED_WEB_CHANNEL_COOKIE, "nightly")],
+      dest: `${NIGHTLY_ORIGIN}/$1`,
+    },
+    {
+      src: "/(.*)",
+      has: [matchers.host(ROUTER_HOST)],
+      dest: `${LATEST_ORIGIN}/$1`,
+    },
+  ],
+  rewrites: [routes.rewrite("/(.*)", "/index.html")],
+};
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 01b50766952..38819e28d73 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -7,8 +7,22 @@ import pkg from "./package.json" with { type: "json" };
 
 const port = Number(process.env.PORT ?? 5733);
 const host = process.env.HOST?.trim() || "localhost";
-const configuredHttpUrl = process.env.VITE_HTTP_URL?.trim();
 const configuredWsUrl = process.env.VITE_WS_URL?.trim();
+const configuredHostedAppChannel = process.env.VITE_HOSTED_APP_CHANNEL?.trim() || "";
+const configuredAppVersion = process.env.APP_VERSION?.trim() || pkg.version;
+const configuredHostedAppUrl = (() => {
+  const explicitHostedAppUrl = process.env.VITE_HOSTED_APP_URL?.trim();
+  if (explicitHostedAppUrl) {
+    return explicitHostedAppUrl;
+  }
+  if (process.env.VERCEL_ENV === "production" && process.env.VERCEL_PROJECT_PRODUCTION_URL) {
+    return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`;
+  }
+  if (process.env.VERCEL_URL) {
+    return `https://${process.env.VERCEL_URL}`;
+  }
+  return undefined;
+})();
 const sourcemapEnv = process.env.T3CODE_WEB_SOURCEMAP?.trim().toLowerCase();
 
 const buildSourcemap =
@@ -56,13 +70,20 @@ export default defineConfig({
     tailwindcss(),
   ],
   optimizeDeps: {
-    include: ["@pierre/diffs", "@pierre/diffs/react", "@pierre/diffs/worker/worker.js"],
+    include: [
+      "@pierre/diffs",
+      "@pierre/diffs/react",
+      "@pierre/diffs/worker/worker.js",
+      "effect/Array",
+      "effect/Order",
+    ],
   },
   define: {
-    "import.meta.env.VITE_HTTP_URL": JSON.stringify(configuredHttpUrl ?? ""),
     // In dev mode, tell the web app where the WebSocket server lives
     "import.meta.env.VITE_WS_URL": JSON.stringify(configuredWsUrl ?? ""),
-    "import.meta.env.APP_VERSION": JSON.stringify(pkg.version),
+    "import.meta.env.VITE_HOSTED_APP_URL": JSON.stringify(configuredHostedAppUrl ?? ""),
+    "import.meta.env.VITE_HOSTED_APP_CHANNEL": JSON.stringify(configuredHostedAppChannel),
+    "import.meta.env.APP_VERSION": JSON.stringify(configuredAppVersion),
   },
   resolve: {
     tsconfigPaths: true,
diff --git a/assets/dev/blueprint-icon-composer.icon/Assets/T3.svg b/assets/dev/blueprint-icon-composer.icon/Assets/T3.svg
new file mode 100644
index 00000000000..b12706fdfc2
--- /dev/null
+++ b/assets/dev/blueprint-icon-composer.icon/Assets/T3.svg
@@ -0,0 +1,3 @@
+<svg width="77" height="47" viewBox="0 0 77 47" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M14.56 45.5V8.58H1.69082e-06V-3.09944e-06H39.65V8.58H25.09V45.5H14.56ZM57.8454 46.28C54.6821 46.28 51.5404 45.8683 48.4204 45.045C45.3004 44.1783 42.6571 42.965 40.4904 41.405L44.5854 33.345C46.3188 34.6017 48.3338 35.5983 50.6304 36.335C52.9271 37.0717 55.2454 37.44 57.5854 37.44C60.2288 37.44 62.3088 36.92 63.8254 35.88C65.3421 34.84 66.1004 33.41 66.1004 31.59C66.1004 29.8567 65.4288 28.4917 64.0854 27.495C62.7421 26.4983 60.5754 26 57.5854 26H52.7754V19.045L65.4504 4.68L66.6204 8.45H42.7654V-3.09944e-06H74.6154V6.825L62.0054 21.19L56.6754 18.135H59.7304C65.3204 18.135 69.5454 19.3917 72.4054 21.905C75.2654 24.4183 76.6954 27.6467 76.6954 31.59C76.6954 34.1467 76.0238 36.5517 74.6804 38.805C73.3371 41.015 71.2788 42.8133 68.5054 44.2C65.7321 45.5867 62.1788 46.28 57.8454 46.28Z" fill="white"/>
+</svg>
diff --git a/assets/dev/blueprint-icon-composer.icon/Assets/Texturelabs_Paper_381XL.jpg b/assets/dev/blueprint-icon-composer.icon/Assets/Texturelabs_Paper_381XL.jpg
new file mode 100644
index 00000000000..d98c41a4e3e
Binary files /dev/null and b/assets/dev/blueprint-icon-composer.icon/Assets/Texturelabs_Paper_381XL.jpg differ
diff --git a/assets/dev/blueprint-icon-composer.icon/Assets/gpt-image-1.5-kn76n9hynne5q3qxy3g91chp2d84t871.png b/assets/dev/blueprint-icon-composer.icon/Assets/gpt-image-1.5-kn76n9hynne5q3qxy3g91chp2d84t871.png
new file mode 100644
index 00000000000..fa7700d01c7
Binary files /dev/null and b/assets/dev/blueprint-icon-composer.icon/Assets/gpt-image-1.5-kn76n9hynne5q3qxy3g91chp2d84t871.png differ
diff --git a/assets/dev/blueprint-icon-composer.icon/icon.json b/assets/dev/blueprint-icon-composer.icon/icon.json
new file mode 100644
index 00000000000..1c15123dab4
--- /dev/null
+++ b/assets/dev/blueprint-icon-composer.icon/icon.json
@@ -0,0 +1,47 @@
+{
+  "fill": {
+    "solid": "display-p3:0.00000,0.00000,0.00000,1.00000"
+  },
+  "groups": [
+    {
+      "layers": [
+        {
+          "blend-mode": "normal",
+          "fill": "automatic",
+          "glass": true,
+          "hidden": false,
+          "image-name": "gpt-image-1.5-kn76n9hynne5q3qxy3g91chp2d84t871.png",
+          "name": "gpt-image-1.5-kn76n9hynne5q3qxy3g91chp2d84t871",
+          "position": {
+            "scale": 1.05,
+            "translation-in-points": [0, 0]
+          }
+        },
+        {
+          "image-name": "T3.svg",
+          "name": "T3",
+          "position": {
+            "scale": 10,
+            "translation-in-points": [0, 0]
+          }
+        },
+        {
+          "hidden": false,
+          "image-name": "Texturelabs_Paper_381XL.jpg",
+          "name": "Texturelabs_Paper_381XL"
+        }
+      ],
+      "shadow": {
+        "kind": "neutral",
+        "opacity": 0.5
+      },
+      "translucency": {
+        "enabled": true,
+        "value": 0.5
+      }
+    }
+  ],
+  "supported-platforms": {
+    "squares": ["iOS", "macOS"]
+  }
+}
diff --git a/assets/dev/blueprint-ios-1024.png b/assets/dev/blueprint-ios-1024.png
index b33d6f337b0..51b764ac72a 100644
Binary files a/assets/dev/blueprint-ios-1024.png and b/assets/dev/blueprint-ios-1024.png differ
diff --git a/assets/dev/blueprint-macos-1024.png b/assets/dev/blueprint-macos-1024.png
index 8dba03e01fe..7c165fdb851 100644
Binary files a/assets/dev/blueprint-macos-1024.png and b/assets/dev/blueprint-macos-1024.png differ
diff --git a/assets/dev/blueprint-universal-1024.png b/assets/dev/blueprint-universal-1024.png
index b33d6f337b0..51b764ac72a 100644
Binary files a/assets/dev/blueprint-universal-1024.png and b/assets/dev/blueprint-universal-1024.png differ
diff --git a/assets/dev/blueprint-web-apple-touch-180.png b/assets/dev/blueprint-web-apple-touch-180.png
index e0e1b9659b8..4a135d22fdb 100644
Binary files a/assets/dev/blueprint-web-apple-touch-180.png and b/assets/dev/blueprint-web-apple-touch-180.png differ
diff --git a/assets/dev/blueprint-web-favicon-16x16.png b/assets/dev/blueprint-web-favicon-16x16.png
index 673d8459998..56e0e837131 100644
Binary files a/assets/dev/blueprint-web-favicon-16x16.png and b/assets/dev/blueprint-web-favicon-16x16.png differ
diff --git a/assets/dev/blueprint-web-favicon-32x32.png b/assets/dev/blueprint-web-favicon-32x32.png
index 25bcc95d4aa..9e9f31ea989 100644
Binary files a/assets/dev/blueprint-web-favicon-32x32.png and b/assets/dev/blueprint-web-favicon-32x32.png differ
diff --git a/assets/dev/blueprint-web-favicon.ico b/assets/dev/blueprint-web-favicon.ico
index 36975b99782..e0ee3e1408f 100644
Binary files a/assets/dev/blueprint-web-favicon.ico and b/assets/dev/blueprint-web-favicon.ico differ
diff --git a/assets/dev/blueprint-windows.ico b/assets/dev/blueprint-windows.ico
index 36975b99782..e0ee3e1408f 100644
Binary files a/assets/dev/blueprint-windows.ico and b/assets/dev/blueprint-windows.ico differ
diff --git a/assets/nightly/blueprint-ios-1024.png b/assets/nightly/blueprint-ios-1024.png
new file mode 100644
index 00000000000..b33d6f337b0
Binary files /dev/null and b/assets/nightly/blueprint-ios-1024.png differ
diff --git a/assets/nightly/blueprint-macos-1024.png b/assets/nightly/blueprint-macos-1024.png
new file mode 100644
index 00000000000..8dba03e01fe
Binary files /dev/null and b/assets/nightly/blueprint-macos-1024.png differ
diff --git a/assets/nightly/blueprint-universal-1024.png b/assets/nightly/blueprint-universal-1024.png
new file mode 100644
index 00000000000..b33d6f337b0
Binary files /dev/null and b/assets/nightly/blueprint-universal-1024.png differ
diff --git a/assets/nightly/blueprint-web-apple-touch-180.png b/assets/nightly/blueprint-web-apple-touch-180.png
new file mode 100644
index 00000000000..e0e1b9659b8
Binary files /dev/null and b/assets/nightly/blueprint-web-apple-touch-180.png differ
diff --git a/assets/nightly/blueprint-web-favicon-16x16.png b/assets/nightly/blueprint-web-favicon-16x16.png
new file mode 100644
index 00000000000..673d8459998
Binary files /dev/null and b/assets/nightly/blueprint-web-favicon-16x16.png differ
diff --git a/assets/nightly/blueprint-web-favicon-32x32.png b/assets/nightly/blueprint-web-favicon-32x32.png
new file mode 100644
index 00000000000..25bcc95d4aa
Binary files /dev/null and b/assets/nightly/blueprint-web-favicon-32x32.png differ
diff --git a/assets/nightly/blueprint-web-favicon.ico b/assets/nightly/blueprint-web-favicon.ico
new file mode 100644
index 00000000000..36975b99782
Binary files /dev/null and b/assets/nightly/blueprint-web-favicon.ico differ
diff --git a/assets/nightly/blueprint-windows.ico b/assets/nightly/blueprint-windows.ico
new file mode 100644
index 00000000000..36975b99782
Binary files /dev/null and b/assets/nightly/blueprint-windows.ico differ
diff --git a/bun.lock b/bun.lock
index 0c95792b694..769bb8c42b8 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,24 +5,32 @@
     "": {
       "name": "@t3tools/monorepo",
       "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@oxlint/plugins": "^1.63.0",
         "@types/node": "catalog:",
         "oxfmt": "^0.40.0",
-        "oxlint": "^1.55.0",
+        "oxlint": "^1.63.0",
         "turbo": "^2.3.3",
+        "typescript": "catalog:",
         "vitest": "catalog:",
       },
     },
     "apps/desktop": {
       "name": "@t3tools/desktop",
-      "version": "0.0.17",
+      "version": "0.0.24",
       "dependencies": {
+        "@effect/platform-node": "catalog:",
+        "@t3tools/contracts": "workspace:*",
+        "@t3tools/shared": "workspace:*",
+        "@t3tools/ssh": "workspace:*",
+        "@t3tools/tailscale": "workspace:*",
         "effect": "catalog:",
-        "electron": "40.6.0",
+        "electron": "41.5.0",
         "electron-updater": "^6.6.2",
       },
       "devDependencies": {
-        "@t3tools/contracts": "workspace:*",
-        "@t3tools/shared": "workspace:*",
+        "@effect/language-service": "catalog:",
+        "@effect/vitest": "catalog:",
         "@types/node": "catalog:",
         "tsdown": "catalog:",
         "typescript": "catalog:",
@@ -42,28 +50,32 @@
     },
     "apps/server": {
       "name": "t3",
-      "version": "0.0.17",
+      "version": "0.0.24",
       "bin": {
         "t3": "./dist/bin.mjs",
       },
       "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.2.77",
         "@effect/platform-bun": "catalog:",
         "@effect/platform-node": "catalog:",
+        "@effect/platform-node-shared": "catalog:",
         "@effect/sql-sqlite-bun": "catalog:",
-        "@pierre/diffs": "^1.1.0-beta.16",
+        "@opencode-ai/sdk": "^1.3.15",
+        "@pierre/diffs": "catalog:",
         "effect": "catalog:",
         "node-pty": "^1.1.0",
-        "open": "^10.1.0",
       },
       "devDependencies": {
+        "@anthropic-ai/claude-agent-sdk": "^0.2.111",
         "@effect/language-service": "catalog:",
         "@effect/vitest": "catalog:",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
+        "@t3tools/tailscale": "workspace:*",
         "@t3tools/web": "workspace:*",
         "@types/bun": "catalog:",
         "@types/node": "catalog:",
+        "effect-acp": "workspace:*",
+        "effect-codex-app-server": "workspace:*",
         "tsdown": "catalog:",
         "typescript": "catalog:",
         "vitest": "catalog:",
@@ -71,32 +83,32 @@
     },
     "apps/web": {
       "name": "@t3tools/web",
-      "version": "0.0.17",
+      "version": "0.0.24",
       "dependencies": {
-        "@base-ui/react": "^1.2.0",
+        "@base-ui/react": "^1.4.1",
         "@dnd-kit/core": "^6.3.1",
         "@dnd-kit/modifiers": "^9.0.0",
         "@dnd-kit/sortable": "^10.0.0",
         "@dnd-kit/utilities": "^3.2.2",
         "@effect/atom-react": "catalog:",
         "@formkit/auto-animate": "^0.9.0",
+        "@legendapp/list": "3.0.0-beta.44",
         "@lexical/react": "^0.41.0",
-        "@pierre/diffs": "^1.1.0-beta.16",
+        "@pierre/diffs": "catalog:",
         "@t3tools/client-runtime": "workspace:*",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
         "@tanstack/react-pacer": "^0.19.4",
         "@tanstack/react-query": "^5.90.0",
         "@tanstack/react-router": "^1.160.2",
-        "@tanstack/react-virtual": "^3.13.18",
         "@xterm/addon-fit": "^0.11.0",
         "@xterm/xterm": "^6.0.0",
         "class-variance-authority": "^0.7.1",
         "effect": "catalog:",
         "lexical": "^0.41.0",
         "lucide-react": "^0.564.0",
-        "react": "^19.0.0",
-        "react-dom": "^19.0.0",
+        "react": "19.2.6",
+        "react-dom": "19.2.6",
         "react-markdown": "^10.1.0",
         "remark-gfm": "^4.0.1",
         "tailwind-merge": "^3.4.0",
@@ -108,11 +120,12 @@
         "@tailwindcss/vite": "^4.0.0",
         "@tanstack/router-plugin": "^1.161.0",
         "@types/babel__core": "^7.20.5",
-        "@types/react": "^19.0.0",
-        "@types/react-dom": "^19.0.0",
+        "@types/react": "~19.2.14",
+        "@types/react-dom": "~19.2.3",
+        "@vercel/config": "^0.3.0",
         "@vitejs/plugin-react": "^6.0.0",
         "@vitest/browser-playwright": "^4.0.18",
-        "babel-plugin-react-compiler": "^19.0.0-beta-e552027-20250112",
+        "babel-plugin-react-compiler": "1.0.0",
         "msw": "2.12.11",
         "playwright": "^1.58.2",
         "tailwindcss": "^4.0.0",
@@ -122,11 +135,27 @@
         "vitest-browser-react": "^2.0.5",
       },
     },
+    "oxlint-plugin-t3code": {
+      "name": "@t3tools/oxlint-plugin-t3code",
+      "dependencies": {
+        "@effect/platform-node": "catalog:",
+        "@oxlint/plugins": "^1.63.0",
+        "effect": "catalog:",
+      },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/vitest": "catalog:",
+        "@types/bun": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
     "packages/client-runtime": {
       "name": "@t3tools/client-runtime",
-      "version": "0.0.0-alpha.1",
       "dependencies": {
         "@t3tools/contracts": "workspace:*",
+        "@t3tools/shared": "workspace:*",
+        "effect": "catalog:",
       },
       "devDependencies": {
         "@effect/language-service": "catalog:",
@@ -136,25 +165,82 @@
     },
     "packages/contracts": {
       "name": "@t3tools/contracts",
-      "version": "0.0.17",
+      "version": "0.0.24",
       "dependencies": {
         "effect": "catalog:",
       },
       "devDependencies": {
         "@effect/language-service": "catalog:",
         "@effect/vitest": "catalog:",
-        "tsdown": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
+    "packages/effect-acp": {
+      "name": "effect-acp",
+      "dependencies": {
+        "effect": "catalog:",
+      },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/openapi-generator": "catalog:",
+        "@effect/platform-node": "catalog:",
+        "@effect/vitest": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
+    "packages/effect-codex-app-server": {
+      "name": "effect-codex-app-server",
+      "dependencies": {
+        "effect": "catalog:",
+      },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/openapi-generator": "catalog:",
+        "@effect/platform-node": "catalog:",
+        "@effect/vitest": "catalog:",
         "typescript": "catalog:",
         "vitest": "catalog:",
       },
     },
     "packages/shared": {
       "name": "@t3tools/shared",
-      "version": "0.0.0-alpha.1",
       "dependencies": {
         "@t3tools/contracts": "workspace:*",
         "effect": "catalog:",
       },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/platform-node": "catalog:",
+        "@effect/vitest": "catalog:",
+        "@types/node": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
+    "packages/ssh": {
+      "name": "@t3tools/ssh",
+      "dependencies": {
+        "@t3tools/contracts": "workspace:*",
+        "@t3tools/shared": "workspace:*",
+        "effect": "catalog:",
+      },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/platform-node": "catalog:",
+        "@effect/vitest": "catalog:",
+        "@types/node": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
+    "packages/tailscale": {
+      "name": "@t3tools/tailscale",
+      "dependencies": {
+        "@effect/platform-node": "catalog:",
+        "effect": "catalog:",
+      },
       "devDependencies": {
         "@effect/language-service": "catalog:",
         "@effect/vitest": "catalog:",
@@ -182,8 +268,12 @@
     },
   },
   "trustedDependencies": [
+    "electron",
     "node-pty",
   ],
+  "patchedDependencies": {
+    "effect@4.0.0-beta.59": "patches/effect@4.0.0-beta.59.patch",
+  },
   "overrides": {
     "@effect/atom-react": "catalog:",
     "@effect/platform-bun": "catalog:",
@@ -195,22 +285,26 @@
     "vite": "^8.0.0",
   },
   "catalog": {
-    "@effect/atom-react": "4.0.0-beta.45",
+    "@effect/atom-react": "4.0.0-beta.59",
     "@effect/language-service": "0.84.2",
-    "@effect/platform-bun": "4.0.0-beta.45",
-    "@effect/platform-node": "4.0.0-beta.45",
-    "@effect/platform-node-shared": "4.0.0-beta.45",
-    "@effect/sql-sqlite-bun": "4.0.0-beta.45",
-    "@effect/vitest": "4.0.0-beta.45",
-    "@types/bun": "^1.3.9",
+    "@effect/openapi-generator": "4.0.0-beta.59",
+    "@effect/platform-bun": "4.0.0-beta.59",
+    "@effect/platform-node": "4.0.0-beta.59",
+    "@effect/platform-node-shared": "4.0.0-beta.59",
+    "@effect/sql-sqlite-bun": "4.0.0-beta.59",
+    "@effect/vitest": "4.0.0-beta.59",
+    "@pierre/diffs": "1.1.20",
+    "@types/bun": "^1.3.11",
     "@types/node": "^24.10.13",
-    "effect": "4.0.0-beta.45",
+    "effect": "4.0.0-beta.59",
     "tsdown": "^0.20.3",
     "typescript": "^5.7.3",
     "vitest": "^4.0.0",
   },
   "packages": {
-    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.77", "", { "optionalDependencies": { "@img/sharp-darwin-arm64": "^0.34.2", "@img/sharp-darwin-x64": "^0.34.2", "@img/sharp-linux-arm": "^0.34.2", "@img/sharp-linux-arm64": "^0.34.2", "@img/sharp-linux-x64": "^0.34.2", "@img/sharp-linuxmusl-arm64": "^0.34.2", "@img/sharp-linuxmusl-x64": "^0.34.2", "@img/sharp-win32-arm64": "^0.34.2", "@img/sharp-win32-x64": "^0.34.2" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-t+R1BW3ahCFMNM7/8WJq7+Gw9KPA9Cl7UUK8fWPokJZ75cf/xwEd9MqB+MVNoQT45dJiom/wxybT7tqYPkCqyg=="],
+    "@anthropic-ai/claude-agent-sdk": ["@anthropic-ai/claude-agent-sdk@0.2.111", "", { "dependencies": { "@anthropic-ai/sdk": "^0.81.0", "@modelcontextprotocol/sdk": "^1.29.0" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "^0.34.2", "@img/sharp-darwin-x64": "^0.34.2", "@img/sharp-linux-arm": "^0.34.2", "@img/sharp-linux-arm64": "^0.34.2", "@img/sharp-linux-x64": "^0.34.2", "@img/sharp-linuxmusl-arm64": "^0.34.2", "@img/sharp-linuxmusl-x64": "^0.34.2", "@img/sharp-win32-arm64": "^0.34.2", "@img/sharp-win32-x64": "^0.34.2" }, "peerDependencies": { "zod": "^4.0.0" } }, "sha512-DwXyJpVL8JXB8L2toSw1by7uIt1p8hPGi0P+hqr5tL+Ae7DcK9O3tUd6XcGown3LZ49zNCUAIpqX3wDmOhqp0Q=="],
+
+    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.81.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-D4K5PvEV6wPiRtVlVsJHIUhHAmOZ6IT/I9rKlTf84gR7GyyAurPJK7z9BOf/AZqC5d1DhYQGJNKRmV+q8dGhgw=="],
 
     "@astrojs/check": ["@astrojs/check@0.9.8", "", { "dependencies": { "@astrojs/language-server": "^2.16.5", "chokidar": "^4.0.3", "kleur": "^4.1.5", "yargs": "^17.7.2" }, "peerDependencies": { "typescript": "^5.0.0" }, "bin": { "astro-check": "bin/astro-check.js" } }, "sha512-LDng8446QLS5ToKjRHd3bgUdirvemVVExV7nRyJfW2wV36xuv7vDxwy5NWN9zqeSEDgg0Tv84sP+T3yEq+Zlkw=="],
 
@@ -268,9 +362,9 @@
 
     "@babel/types": ["@babel/types@7.29.0", "", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.28.5" } }, "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A=="],
 
-    "@base-ui/react": ["@base-ui/react@1.3.0", "", { "dependencies": { "@babel/runtime": "^7.28.6", "@base-ui/utils": "0.2.6", "@floating-ui/react-dom": "^2.1.8", "@floating-ui/utils": "^0.2.11", "tabbable": "^6.4.0", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@types/react": "^17 || ^18 || ^19", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@types/react"] }, "sha512-FwpKqZbPz14AITp1CVgf4AjhKPe1OeeVKSBMdgD10zbFlj3QSWelmtCMLi2+/PFZZcIm3l87G7rwtCZJwHyXWA=="],
+    "@base-ui/react": ["@base-ui/react@1.4.1", "", { "dependencies": { "@babel/runtime": "^7.29.2", "@base-ui/utils": "0.2.8", "@floating-ui/react-dom": "^2.1.8", "@floating-ui/utils": "^0.2.11", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@date-fns/tz": "^1.2.0", "@types/react": "^17 || ^18 || ^19", "date-fns": "^4.0.0", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@date-fns/tz", "@types/react", "date-fns"] }, "sha512-Ab5/LIhcmL8BQcsBUYiOfkSDRdLpvgUBzMK30cu684JPcLclYlztharvCZyNNgzJtbAiREzI9q0pI5erHCMgCw=="],
 
-    "@base-ui/utils": ["@base-ui/utils@0.2.6", "", { "dependencies": { "@babel/runtime": "^7.28.6", "@floating-ui/utils": "^0.2.11", "reselect": "^5.1.1", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@types/react": "^17 || ^18 || ^19", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@types/react"] }, "sha512-yQ+qeuqohwhsNpoYDqqXaLllYAkPCP4vYdDrVo8FQXaAPfHWm1pG/Vm+jmGTA5JFS0BAIjookyapuJFY8F9PIw=="],
+    "@base-ui/utils": ["@base-ui/utils@0.2.8", "", { "dependencies": { "@babel/runtime": "^7.29.2", "@floating-ui/utils": "^0.2.11", "reselect": "^5.1.1", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@types/react": "^17 || ^18 || ^19", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@types/react"] }, "sha512-jvOi+c+ftGlGotNcKnzPVg2IhCaDTB6/6R3JeqdjdXktuAJi3wKH9T7+svuaKh1mmfVU11UWzUZVH74JDfi/wQ=="],
 
     "@blazediff/core": ["@blazediff/core@1.9.1", "", {}, "sha512-ehg3jIkYKulZh+8om/O25vkvSsXXwC+skXmyA87FFx6A/45eqOkZsBltMw/TVteb0mloiGT8oGRTcjRAz66zaA=="],
 
@@ -290,19 +384,21 @@
 
     "@dnd-kit/utilities": ["@dnd-kit/utilities@3.2.2", "", { "dependencies": { "tslib": "^2.0.0" }, "peerDependencies": { "react": ">=16.8.0" } }, "sha512-+MKAJEOfaBe5SmV6t34p80MMKhjvUz0vRrvVJbPT0WElzaOJ/1xs+D+KDv+tD/NE5ujfrChEcshd4fLn0wpiqg=="],
 
-    "@effect/atom-react": ["@effect/atom-react@4.0.0-beta.45", "", { "peerDependencies": { "effect": "^4.0.0-beta.45", "react": "^19.2.4", "scheduler": "*" } }, "sha512-jCoiae9UNeis9Yoal1p5V/P4eJK9nX89wORom7X5LpR2Ok920SZJc8dIeYkRXRAp9BCYJ/yWcO8gGLf7do71vg=="],
+    "@effect/atom-react": ["@effect/atom-react@4.0.0-beta.59", "", { "peerDependencies": { "effect": "^4.0.0-beta.59", "react": "^19.2.4", "scheduler": "*" } }, "sha512-VkznQz5c+Z/BLxX+hQNPzPOyUnLQjnbppFSNP7tbPru7HKR4ihzCDC6Xjbx87156MOrZ+JOa6shTMbmvGT5W0w=="],
 
     "@effect/language-service": ["@effect/language-service@0.84.2", "", { "bin": { "effect-language-service": "cli.js" } }, "sha512-l04qNxpiA8rY5yXWckRPJ7Mk5MNerXuNymSFf+IdflfI5i8jgL1bpBNLuP6ijg7wgjdHc/KmTnCj2kT0SCntuA=="],
 
-    "@effect/platform-bun": ["@effect/platform-bun@4.0.0-beta.45", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.45" }, "peerDependencies": { "effect": "^4.0.0-beta.45" } }, "sha512-dZsbkJ+o4JfKE1OIAlMq8YWhmEfXxtTYennYADK/M/XlOtkFLsc2jkZppDvMznVni6JpFxWc7wd5rUf8jBVP5g=="],
+    "@effect/openapi-generator": ["@effect/openapi-generator@4.0.0-beta.59", "", { "peerDependencies": { "@effect/platform-node": "^4.0.0-beta.59", "effect": "^4.0.0-beta.59" }, "bin": { "openapigen": "dist/bin.js" } }, "sha512-y1KF6mEb3pA5AdQsNGeWxV42Xi1uBt9Wzo5xMsp06j/WkOM2vWFmvSXw6xvwINAUi1HVjdOLo3xnTXtSv9YdRg=="],
+
+    "@effect/platform-bun": ["@effect/platform-bun@4.0.0-beta.59", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.59" }, "peerDependencies": { "effect": "^4.0.0-beta.59" } }, "sha512-1jXCIx34X80ojiK9ACO9Q7RST9CXudRmlAbsP4kPqjUo6aqOuGSWXq9ueBO4LbaIZiioRxtTciom35U9ldfTkQ=="],
 
-    "@effect/platform-node": ["@effect/platform-node@4.0.0-beta.45", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.45", "mime": "^4.1.0", "undici": "^7.24.0" }, "peerDependencies": { "effect": "^4.0.0-beta.45", "ioredis": "^5.7.0" } }, "sha512-P07NMG4eoy62iLX9szak0hkr7hrwgq5+XMkm7URVug/3zqfZVxEG2kxn9JzVK1lF5WbaVrEKwjt3IkEJxzSPtg=="],
+    "@effect/platform-node": ["@effect/platform-node@4.0.0-beta.59", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.59", "mime": "^4.1.0", "undici": "^8.0.2" }, "peerDependencies": { "effect": "^4.0.0-beta.59", "ioredis": "^5.7.0" } }, "sha512-jHRW0l953FjYNhQHexr48jFiBu5iGEZH5nmKD6Ha+lPtm1MrKG2V4njfWA3Fv0nUmd3VN87eBJ557wU0twN1Hg=="],
 
-    "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.45", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.19.0" }, "peerDependencies": { "effect": "^4.0.0-beta.45" } }, "sha512-0T4RG18o+aCVUSlmPxA7uAjHJkyE3MS/uRrR5kCNSZQNG3X71wdIbu82wE/MnV6+6YSSPDx/6TVdZWYkJF0JWw=="],
+    "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.59", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.20.0" }, "peerDependencies": { "effect": "^4.0.0-beta.59" } }, "sha512-fGwFJuG0Te9U/ZeqeDZ2HcSKZBhX5wLjX2/Rxb5+yaOkvvFAN9MvIh05R0QQK5DCcERvnbhHSl1CjSIAN4aEwQ=="],
 
-    "@effect/sql-sqlite-bun": ["@effect/sql-sqlite-bun@4.0.0-beta.45", "", { "peerDependencies": { "effect": "^4.0.0-beta.45" } }, "sha512-sJBBztwI4YxjdjhdyjWelh3KKoZucmmZS2ONeNDIzYgqFlsrwEEUrhVkWf5ch9Io+kUUzeb6q7/SedFoLUWO7g=="],
+    "@effect/sql-sqlite-bun": ["@effect/sql-sqlite-bun@4.0.0-beta.59", "", { "peerDependencies": { "effect": "^4.0.0-beta.59" } }, "sha512-qZWt2HeLgSY8ygEfwbldK9lJ5xg/WP4lgCp1VLlyE8BImSB5g1h+UbhitXr+pOIf+ry4Xmc4ycp7YwTBOFH5/A=="],
 
-    "@effect/vitest": ["@effect/vitest@4.0.0-beta.45", "", { "peerDependencies": { "effect": "^4.0.0-beta.45", "vitest": "^3.0.0 || ^4.0.0" } }, "sha512-38JA5Z6c2FoEhpVKbl7rjTrMU8Al5T30Kwtb6N3B9kOkyr2SsmvNsP9T65bh03IBh3ak9U//acrkmjS3hLQwKA=="],
+    "@effect/vitest": ["@effect/vitest@4.0.0-beta.59", "", { "peerDependencies": { "effect": "^4.0.0-beta.59", "vitest": "^3.0.0 || ^4.0.0" } }, "sha512-jhpJbpDs1ED58SmFzcfmqLXxle84fiexaMEhV8SBl8WC2GM3FT5DW0WJYFjbZIH5/735brp3iGdjY5/uAxS7Bg=="],
 
     "@electron/get": ["@electron/get@2.0.3", "", { "dependencies": { "debug": "^4.1.1", "env-paths": "^2.2.0", "fs-extra": "^8.1.0", "got": "^11.8.5", "progress": "^2.0.3", "semver": "^6.2.0", "sumchecker": "^3.0.1" }, "optionalDependencies": { "global-agent": "^3.0.0" } }, "sha512-Qkzpg2s9GnVV2I2BjRksUi43U5e6+zaQMcjoJy0C+C5oxaKl+fmckGDQFtRpZpZV0NQekuZZ+tGz7EA9TVnQtQ=="],
 
@@ -390,6 +486,8 @@
 
     "@formkit/auto-animate": ["@formkit/auto-animate@0.9.0", "", {}, "sha512-VhP4zEAacXS3dfTpJpJ88QdLqMTcabMg0jwpOSxZ/VzfQVfl3GkZSCZThhGC5uhq/TxPHPzW0dzr4H9Bb1OgKA=="],
 
+    "@hono/node-server": ["@hono/node-server@1.19.14", "", { "peerDependencies": { "hono": "^4" } }, "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw=="],
+
     "@img/colour": ["@img/colour@1.1.0", "", {}, "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ=="],
 
     "@img/sharp-darwin-arm64": ["@img/sharp-darwin-arm64@0.34.5", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.2.4" }, "os": "darwin", "cpu": "arm64" }, "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w=="],
@@ -462,6 +560,8 @@
 
     "@jridgewell/trace-mapping": ["@jridgewell/trace-mapping@0.3.31", "", { "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", "@jridgewell/sourcemap-codec": "^1.4.14" } }, "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw=="],
 
+    "@legendapp/list": ["@legendapp/list@3.0.0-beta.44", "", { "dependencies": { "use-sync-external-store": "^1.5.0" }, "peerDependencies": { "react": "*" } }, "sha512-loGRve78NuZ5k8Z54ZSDNOtv3dVBM1SeBCRtm1EYtZiDIZ8SyMVcYpUGgFpGuNKk71+9/NuM9hvScrgf7+4E+A=="],
+
     "@lexical/clipboard": ["@lexical/clipboard@0.41.0", "", { "dependencies": { "@lexical/html": "0.41.0", "@lexical/list": "0.41.0", "@lexical/selection": "0.41.0", "@lexical/utils": "0.41.0", "lexical": "0.41.0" } }, "sha512-Ex5lPkb4NBBX1DCPzOAIeHBJFH1bJcmATjREaqpnTfxCbuOeQkt44wchezUA0oDl+iAxNZ3+pLLWiUju9icoSA=="],
 
     "@lexical/code": ["@lexical/code@0.41.0", "", { "dependencies": { "@lexical/utils": "0.41.0", "lexical": "0.41.0", "prismjs": "^1.30.0" } }, "sha512-0hoNi1KC9/N3SBOGcOcFqnT0OpwmcRRAhfxTKMGqfCtCvAMzULVwZ8RWc9/NV9bKYESgBTW5D9xkDANP2mspHg=="],
@@ -506,6 +606,8 @@
 
     "@lexical/yjs": ["@lexical/yjs@0.41.0", "", { "dependencies": { "@lexical/offset": "0.41.0", "@lexical/selection": "0.41.0", "lexical": "0.41.0" }, "peerDependencies": { "yjs": ">=13.5.22" } }, "sha512-PaKTxSbVC4fpqUjQ7vUL9RkNF1PjL8TFl5jRe03PqoPYpE33buf3VXX6+cOUEfv9+uknSqLCPHoBS/4jN3a97w=="],
 
+    "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.29.0", "", { "dependencies": { "@hono/node-server": "^1.19.9", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.2.1", "express-rate-limit": "^8.2.1", "hono": "^4.11.4", "jose": "^6.1.3", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ=="],
+
     "@msgpackr-extract/msgpackr-extract-darwin-arm64": ["@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-QZHtlVgbAdy2zAqNA9Gu1UpIuI8Xvsd1v8ic6B2pZmeFnFcMWiPLfWXh7TVw4eGEZ/C9TH281KwhVoeQUKbyjw=="],
 
     "@msgpackr-extract/msgpackr-extract-darwin-x64": ["@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-mdzd3AVzYKuUmiWOQ8GNhl64/IoFGol569zNRdkLReh6LRLHOXxU4U8eq0JwaD8iFHdVGqSy4IjFL4reoWCDFw=="],
@@ -528,6 +630,8 @@
 
     "@open-draft/until": ["@open-draft/until@2.1.0", "", {}, "sha512-U69T3ItWHvLwGg5eJ0n3I62nWuE6ilHlmz7zM0npLBRvPRd7e6NYmg54vvRtP5mZG7kZqZCFVdsTWo7BPtBujg=="],
 
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.3.15", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-Uk59C7wsK20wpdr277yx7Xz7TqG5jGqlZUpSW3wDH/7a2K2iBg0lXc2wskHuCXLRXMhXpPZtb4a3SOpPENkkbg=="],
+
     "@oslojs/encoding": ["@oslojs/encoding@1.1.0", "", {}, "sha512-70wQhgYmndg4GCPxPPxPGevRKqTIJ2Nh4OkiMWmDAVYsTQ+Ta7Sq+rPevXyXGdzr30/qZBnyOalCszoMxlyldQ=="],
 
     "@oxc-project/runtime": ["@oxc-project/runtime@0.115.0", "", {}, "sha512-Rg8Wlt5dCbXhQnsXPrkOjL1DTSvXLgb2R/KYfnf1/K+R0k6UMLEmbQXPM+kwrWqSmWA2t0B1EtHy2/3zikQpvQ=="],
@@ -572,47 +676,49 @@
 
     "@oxfmt/binding-win32-x64-msvc": ["@oxfmt/binding-win32-x64-msvc@0.40.0", "", { "os": "win32", "cpu": "x64" }, "sha512-/Zmj0yTYSvmha6TG1QnoLqVT7ZMRDqXvFXXBQpIjteEwx9qvUYMBH2xbiOFhDeMUJkGwC3D6fdKsFtaqUvkwNA=="],
 
-    "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.56.0", "", { "os": "android", "cpu": "arm" }, "sha512-IyfYPthZyiSKwAv/dLjeO18SaK8MxLI9Yss2JrRDyweQAkuL3LhEy7pwIwI7uA3KQc1Vdn20kdmj3q0oUIQL6A=="],
+    "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.63.0", "", { "os": "android", "cpu": "arm" }, "sha512-A9xLtQt7i0OA1PoB/meog6kikXI9CdwEp7ZwQqmgnpKn3G3b1orvTDy8CQ6T7w1HvDrgWGB78PkFKcWgibcTCg=="],
+
+    "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.63.0", "", { "os": "android", "cpu": "arm64" }, "sha512-SQo+ZMvdR9l3CxZp5W5gFNxSiDxclY6lOzzNpKYLF8asESpm3Pwumx0gER5T7aHLF1/2BAAtLD3DiDkdgy4V1A=="],
 
-    "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.56.0", "", { "os": "android", "cpu": "arm64" }, "sha512-Ga5zYrzH6vc/VFxhn6MmyUnYEfy9vRpwTIks99mY3j6Nz30yYpIkWryI0QKPCgvGUtDSXVLEaMum5nA+WrNOSg=="],
+    "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.63.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-6W82XjJDTmMnjg30427l0dufpnyLoq7wEukKdM6/g2VIybRVuQiBVh43EA4b+UxZ3+tLcKm+Or/pXGNgLCEU8g=="],
 
-    "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.56.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-ogmbdJysnw/D4bDcpf1sPLpFThZ48lYp4aKYm10Z/6Nh1SON6NtnNhTNOlhEY296tDFItsZUz+2tgcSYqh8Eyw=="],
+    "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.63.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-CnWd/YCuVG5W1BYkjJEVbJG11o526O9qAwBEQM+nh8K19CRFUkFdROXCyYkGmroHEYQe4vgQ6+lh3550Lp35Xw=="],
 
-    "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.56.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-x8QE1h+RAtQ2g+3KPsP6Fk/tdz6zJQUv5c7fTrJxXV3GHOo+Ry5p/PsogU4U+iUZg0rj6hS+E4xi+mnwwlDCWQ=="],
+    "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.63.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-a4eZAqrmtajqcxfdAzC+l7g3PaE3V8hpAYqqeD3fTxLXOMFdK3eNTZrU80n4dDEVm0JXy1aL5PqvqWldBl6zYA=="],
 
-    "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.56.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-6G+WMZvwJpMvY7my+/SHEjb7BTk/PFbePqLpmVmUJRIsJMy/UlyYqjpuh0RCgYYkPLcnXm1rUM04kbTk8yS1Yg=="],
+    "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.63.0", "", { "os": "linux", "cpu": "arm" }, "sha512-tYUtU9TdbU3uXF5D62g5zXJ13iniFGhXQx5vp9cyEjGdbSAY3VdFBSaldYvyoDmgMZ0ZYuwQP1Y4t2Fhejwa0w=="],
 
-    "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.56.0", "", { "os": "linux", "cpu": "arm" }, "sha512-YYHBsk/sl7fYwQOok+6W5lBPeUEvisznV/HZD2IfZmF3Bns6cPC3Z0vCtSEOaAWTjYWN3jVsdu55jMxKlsdlhg=="],
+    "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.63.0", "", { "os": "linux", "cpu": "arm" }, "sha512-I5r3twFf776UZg9dmRo2xbrKt00tTkORXEVe0ctg4vdTkQvJAjiCHxnbAU2HL1AiJ9cqADA76MAliuilsAWnvg=="],
 
-    "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.56.0", "", { "os": "linux", "cpu": "arm" }, "sha512-+AZK8rOUr78y8WT6XkDb04IbMRqauNV+vgT6f8ZLOH8wnpQ9i7Nol0XLxAu+Cq7Sb+J9wC0j6Km5hG8rj47/yQ=="],
+    "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.63.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-t7ltUkg6FFh4b564QyGir8xIj/QZbXu8FlcRkcyW9+ztr/mfRHlvUOFd95pJCXi9s/L5DrUeWWgpXRS+V+6igQ=="],
 
-    "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.56.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-urse2SnugwJRojUkGSSeH2LPMaje5Q50yQtvtL9HFckiyeqXzoFwOAZqD5TR29R2lq7UHidfFDM9EGcchcbb8A=="],
+    "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.63.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-Q5mmZy/XWjuYFUuQyYjOvZ5U/JkKEwnpir6hGxhh6HcdP0V/BKxLo8dqkfF/t7r7AguB17dfS/8+go5AQDRR6g=="],
 
-    "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.56.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-rkTZkBfJ4TYLjansjSzL6mgZOdN5IvUnSq3oNJSLwBcNvy3dlgQtpHPrRxrCEbbcp7oQ6If0tkNaqfOsphYZ9g=="],
+    "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.63.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-uBGtuZ0TzLB4x5wVa82HGNvYqY8buwDhyCnCP0R0gkk9szqVsP0MeTtD5HX7EsEuFIt+aYmYxuxeVxs3nTSwtQ=="],
 
-    "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.56.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-uqL1kMH3u69/e1CH2EJhP3CP28jw2ExLsku4o8RVAZ7fySo9zOyI2fy9pVlTAp4voBLVgzndXi3SgtdyCTa2aA=="],
+    "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.63.0", "", { "os": "linux", "cpu": "none" }, "sha512-h4s6FwxE+9MeA181o0dnDwHP32Y/bG8EiB/vrD6Ib+AMt6haigDc/0bUtI/sLmQDBMJnUfaCmtSSrEAqjtEVrA=="],
 
-    "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.56.0", "", { "os": "linux", "cpu": "none" }, "sha512-j0CcMBOgV6KsRaBdsebIeiy7hCjEvq2KdEsiULf2LZqAq0v1M1lWjelhCV57LxsqaIGChXFuFJ0RiFrSRHPhSg=="],
+    "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.63.0", "", { "os": "linux", "cpu": "none" }, "sha512-2EaNcCBR8Mcjl5ARtuN3BdEpVkX7KpjSjMGZ/mJMIeaXgTtdz5ytg2VwygMSStA/k0ixfvZFoZOfjDEcouV5vQ=="],
 
-    "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.56.0", "", { "os": "linux", "cpu": "none" }, "sha512-7VDOiL8cDG3DQ/CY3yKjbV1c4YPvc4vH8qW09Vv+5ukq3l/Kcyr6XGCd5NvxUmxqDb2vjMpM+eW/4JrEEsUetA=="],
+    "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.63.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-p4hlf/fd7TrYYl3QrWWD0GocqJefwMu3cHQhmi2FvEB/YOvFb5DZN3SMBaPi7B1TM5DeypkEtrVib674q1KKPg=="],
 
-    "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.56.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-JGRpX0M+ikD3WpwJ7vKcHKV6Kg0dT52BW2Eu2BupXotYeqGXBrbY+QPkAyKO6MNgKozyTNaRh3r7g+VWgyAQYQ=="],
+    "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.63.0", "", { "os": "linux", "cpu": "x64" }, "sha512-Vgq9rkRVcPcjbcH+ihYTfpeR7vCXfqpd+z5ItTGc0yYUV59L5ceHYN1iV4H9bKGV7Rn5hkVc7x3mSvHegduENA=="],
 
-    "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.56.0", "", { "os": "linux", "cpu": "x64" }, "sha512-dNaICPvtmuxFP/VbqdofrLqdS3bM/AKJN3LMJD52si44ea7Be1cBk6NpfIahaysG9Uo+L98QKddU9CD5L8UHnQ=="],
+    "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.63.0", "", { "os": "linux", "cpu": "x64" }, "sha512-3/Lkq/ncooA61rorrC+ZQed1Bc4VpGj+WnGsp58zmxKgvZ2vhreu+dcVyr3mX8NUpq7mfZ4gDDTou/yrF1Pd7A=="],
 
-    "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.56.0", "", { "os": "linux", "cpu": "x64" }, "sha512-pF1vOtM+GuXmbklM1hV8WMsn6tCNPvkUzklj/Ej98JhlanbmA2RB1BILgOpwSuCTRTIYx2MXssmEyQQ90QF5aA=="],
+    "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.63.0", "", { "os": "none", "cpu": "arm64" }, "sha512-0/EdD/6hDkx5Mfd769PTjvEM8mZ/6Dfukp1dBCL/2PjlIVGEtYdNZyok6ChqYPsT9JcFnlQnUeQzO0/1L/oC9w=="],
 
-    "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.56.0", "", { "os": "none", "cpu": "arm64" }, "sha512-bp8NQ4RE6fDIFLa4bdBiOA+TAvkNkg+rslR+AvvjlLTYXLy9/uKAYLQudaQouWihLD/hgkrXIKKzXi5IXOewwg=="],
+    "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.63.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-wb0CUkN8ngwPiRQBjD1Cj0LsHeNvm+Xt6YBHDMtj2DVQVD6Oj8Ri7g6BD+KICf6LaBqZlmzOvy6nF9E/8yyGOg=="],
 
-    "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.56.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-PxT4OJDfMOQBzo3OlzFb9gkoSD+n8qSBxyVq2wQSZIHFQYGEqIRTo9M0ZStvZm5fdhMqaVYpOnJvH2hUMEDk/g=="],
+    "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.63.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-BX5iq+ovdNlVYhSn5qPMUIT0uwAwt2lmEnCnzK+Gkhw4DovIvhGb96OFhV8yzQNUnQxn/xGkOR+X+BLrLDNm8w=="],
 
-    "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.56.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-PTRy6sIEPqy2x8PTP1baBNReN/BNEFmde0L+mYeHmjXE1Vlcc9+I5nsqENsB2yAm5wLkzPoTNCMY/7AnabT4/A=="],
+    "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.63.0", "", { "os": "win32", "cpu": "x64" }, "sha512-QeN/WELOfsXMeYwxvfgQrl6CbVftYUCZsGXHjXQd5Trccm8+i4gmtxaOui4xbJQaiDlviF8F3yLSBloQUeFsfA=="],
 
-    "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.56.0", "", { "os": "win32", "cpu": "x64" }, "sha512-ZHa0clocjLmIDr+1LwoWtxRcoYniAvERotvwKUYKhH41NVfl0Y4LNbyQkwMZzwDvKklKGvGZ5+DAG58/Ik47tQ=="],
+    "@oxlint/plugins": ["@oxlint/plugins@1.63.0", "", {}, "sha512-vZAzaUQkwgdN62RHgPFzfCsiBI6SDJMUdUlBGpJK0V++UHCMUk7UeJseygOhE/wOUSgV3ccE4ORkgab3C3MC6g=="],
 
-    "@pierre/diffs": ["@pierre/diffs@1.1.0", "", { "dependencies": { "@pierre/theme": "0.0.22", "@shikijs/transformers": "^3.0.0", "diff": "8.0.3", "hast-util-to-html": "9.0.5", "lru_map": "0.4.1", "shiki": "^3.0.0" }, "peerDependencies": { "react": "^18.3.1 || ^19.0.0", "react-dom": "^18.3.1 || ^19.0.0" } }, "sha512-wbxrzcmanJuHZb81iir09j42uU9AnKxXDtAuEQJbAnti5f2UfYdCQYejawuHZStFrlsMacCZLh/dDHmqvAaQCw=="],
+    "@pierre/diffs": ["@pierre/diffs@1.1.20", "", { "dependencies": { "@pierre/theme": "0.0.28", "@shikijs/transformers": "^3.0.0", "diff": "8.0.3", "hast-util-to-html": "9.0.5", "lru_map": "0.4.1", "shiki": "^3.0.0" }, "peerDependencies": { "react": "^18.3.1 || ^19.0.0", "react-dom": "^18.3.1 || ^19.0.0" } }, "sha512-lLi+3sLCm3QDd5/aLO9pw+WbF6UzhrkWm2oTZ5WZJTGemOyUNRJ4DDhcEKmVusu4C4bXx9Nssh6fF+wQcapb5w=="],
 
-    "@pierre/theme": ["@pierre/theme@0.0.22", "", {}, "sha512-ePUIdQRNGjrveELTU7fY89Xa7YGHHEy5Po5jQy/18lm32eRn96+tnYJEtFooGdffrx55KBUtOXfvVy/7LDFFhA=="],
+    "@pierre/theme": ["@pierre/theme@0.0.28", "", {}, "sha512-1j/H/fECBuc9dEvntdWI+l435HZapw+RCJTlqCA6BboQ5TjlnE005j/ROWutXIs8aq5OAc82JI2Kwk4A1WWBgw=="],
 
     "@polka/url": ["@polka/url@1.0.0-next.29", "", {}, "sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww=="],
 
@@ -688,10 +794,16 @@
 
     "@t3tools/marketing": ["@t3tools/marketing@workspace:apps/marketing"],
 
+    "@t3tools/oxlint-plugin-t3code": ["@t3tools/oxlint-plugin-t3code@workspace:oxlint-plugin-t3code"],
+
     "@t3tools/scripts": ["@t3tools/scripts@workspace:scripts"],
 
     "@t3tools/shared": ["@t3tools/shared@workspace:packages/shared"],
 
+    "@t3tools/ssh": ["@t3tools/ssh@workspace:packages/ssh"],
+
+    "@t3tools/tailscale": ["@t3tools/tailscale@workspace:packages/tailscale"],
+
     "@t3tools/web": ["@t3tools/web@workspace:apps/web"],
 
     "@tailwindcss/node": ["@tailwindcss/node@4.2.1", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.19.0", "jiti": "^2.6.1", "lightningcss": "1.31.1", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.2.1" } }, "sha512-jlx6sLk4EOwO6hHe1oCGm1Q4AN/s0rSrTTPBGPM0/RQ6Uylwq17FuU8IeJJKEjtc6K6O07zsvP+gDO6MMWo7pg=="],
@@ -740,8 +852,6 @@
 
     "@tanstack/react-store": ["@tanstack/react-store@0.8.1", "", { "dependencies": { "@tanstack/store": "0.8.1", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-XItJt+rG8c5Wn/2L/bnxys85rBpm0BfMbhb4zmPVLXAKY9POrp1xd6IbU4PKoOI+jSEGc3vntPRfLGSgXfE2Ig=="],
 
-    "@tanstack/react-virtual": ["@tanstack/react-virtual@3.13.23", "", { "dependencies": { "@tanstack/virtual-core": "3.13.23" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-XnMRnHQ23piOVj2bzJqHrRrLg4r+F86fuBcwteKfbIjJrtGxb4z7tIvPVAe4B+4UVwo9G4Giuz5fmapcrnZ0OQ=="],
-
     "@tanstack/router-core": ["@tanstack/router-core@1.167.3", "", { "dependencies": { "@tanstack/history": "1.161.6", "@tanstack/store": "^0.9.1", "cookie-es": "^2.0.0", "seroval": "^1.4.2", "seroval-plugins": "^1.4.2", "tiny-invariant": "^1.3.3", "tiny-warning": "^1.0.3" } }, "sha512-M/CxrTGKk1fsySJjd+Pzpbi3YLDz+cJSutDjSTMy12owWlOgHV/I6kzR0UxyaBlHraM6XgMHNA0XdgsS1fa4Nw=="],
 
     "@tanstack/router-generator": ["@tanstack/router-generator@1.166.11", "", { "dependencies": { "@tanstack/router-core": "1.167.3", "@tanstack/router-utils": "1.161.6", "@tanstack/virtual-file-routes": "1.161.6", "prettier": "^3.5.0", "recast": "^0.23.11", "source-map": "^0.7.4", "tsx": "^4.19.2", "zod": "^3.24.2" } }, "sha512-Q/49wxURbft1oNOvo/eVAWZq/lNLK3nBGlavqhLToAYXY6LCzfMtRlE/y3XPHzYC9pZc09u5jvBR1k1E4hyGDQ=="],
@@ -752,8 +862,6 @@
 
     "@tanstack/store": ["@tanstack/store@0.9.2", "", {}, "sha512-K013lUJEFJK2ofFQ/hZKJUmCnpcV00ebLyOyFOWQvyQHUOZp/iYO84BM6aOGiV81JzwbX0APTVmW8YI7yiG5oA=="],
 
-    "@tanstack/virtual-core": ["@tanstack/virtual-core@3.13.23", "", {}, "sha512-zSz2Z2HNyLjCplANTDyl3BcdQJc2k1+yyFoKhNRmCr7V7dY8o8q5m8uFTI1/Pg1kL+Hgrz6u3Xo6eFUB7l66cg=="],
-
     "@tanstack/virtual-file-routes": ["@tanstack/virtual-file-routes@1.161.6", "", {}, "sha512-EGWs9yvJA821pUkwkiZLQW89CzUumHyJy8NKq229BubyoWXfDw1oWnTJYSS/hhbLiwP9+KpopjeF5wWwnCCyeQ=="],
 
     "@tybys/wasm-util": ["@tybys/wasm-util@0.10.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg=="],
@@ -766,7 +874,7 @@
 
     "@types/babel__traverse": ["@types/babel__traverse@7.28.0", "", { "dependencies": { "@babel/types": "^7.28.2" } }, "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q=="],
 
-    "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
 
     "@types/cacheable-request": ["@types/cacheable-request@6.0.3", "", { "dependencies": { "@types/http-cache-semantics": "*", "@types/keyv": "^3.1.4", "@types/node": "*", "@types/responselike": "^1.0.0" } }, "sha512-IQ3EbTzGxIigb1I3qPZc1rWJnH0BmSKv5QYTalEwweFvyBDLSAe24zP0le/hyi7ecGfZVlIVAg4BZqb8WBwKqw=="],
 
@@ -812,6 +920,14 @@
 
     "@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g=="],
 
+    "@vercel/config": ["@vercel/config@0.3.0", "", { "dependencies": { "@vercel/routing-utils": "6.2.0", "pretty-cache-header": "^1.0.0", "zod": "^3.22.0" }, "bin": { "config": "dist/cli.js" } }, "sha512-Tf5k5y2F478oTiQcU5R8Ntix1UejE6NdduZnI7aa1XXxjCtifX1XdRS/D2uTjiQAwIL3pLa1LSAN80ABbba+TQ=="],
+
+    "@vercel/functions": ["@vercel/functions@3.5.0", "", { "dependencies": { "@vercel/oidc": "3.4.0" }, "peerDependencies": { "@aws-sdk/credential-provider-web-identity": "*" }, "optionalPeers": ["@aws-sdk/credential-provider-web-identity"] }, "sha512-+RokZ+4gkYyOsKBuJ29cQ8iSZG123LLJbZfPry20kkTgrN9U0277La4feP4DnWVo3sGoYa4plCEKY9XKUYoX9g=="],
+
+    "@vercel/oidc": ["@vercel/oidc@3.4.0", "", {}, "sha512-p0sKfHkfRmMaqqDwNL4tjnX9TgRrLMlEtUjIxfrEns8pOxz1R9ztqOVI+ehqiq93/2/HnfPe/UBZkfAZwnx0UA=="],
+
+    "@vercel/routing-utils": ["@vercel/routing-utils@6.2.0", "", { "dependencies": { "path-to-regexp": "6.1.0", "path-to-regexp-updated": "npm:path-to-regexp@6.3.0" }, "optionalDependencies": { "ajv": "^6.12.3" } }, "sha512-YI2cGYZmJKEyGSEgf5Fw5rVuW7X1bTOQ7/pnLRNTFMH3YB3qqP5erCLCJGv2kIvNo1iQAPINHQRJj6ykEdGoPg=="],
+
     "@vitejs/plugin-react": ["@vitejs/plugin-react@6.0.1", "", { "dependencies": { "@rolldown/pluginutils": "1.0.0-rc.7" }, "peerDependencies": { "@rolldown/plugin-babel": "^0.1.7 || ^0.2.0", "babel-plugin-react-compiler": "^1.0.0", "vite": "^8.0.0" }, "optionalPeers": ["@rolldown/plugin-babel", "babel-plugin-react-compiler"] }, "sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ=="],
 
     "@vitest/browser": ["@vitest/browser@4.1.0", "", { "dependencies": { "@blazediff/core": "1.9.1", "@vitest/mocker": "4.1.0", "@vitest/utils": "4.1.0", "magic-string": "^0.30.21", "pngjs": "^7.0.0", "sirv": "^3.0.2", "tinyrainbow": "^3.0.3", "ws": "^8.19.0" }, "peerDependencies": { "vitest": "4.1.0" } }, "sha512-tG/iOrgbiHQks0ew7CdelUyNEHkv8NLrt+CqdTivIuoSnXvO7scWMn4Kqo78/UGY1NJ6Hv+vp8BvRnED/bjFdQ=="],
@@ -852,12 +968,16 @@
 
     "@xterm/xterm": ["@xterm/xterm@6.0.0", "", {}, "sha512-TQwDdQGtwwDt+2cgKDLn0IRaSxYu1tSUjgKarSDkUM0ZNiSRXFpjxEsvc/Zgc5kq5omJ+V0a8/kIM2WD3sMOYg=="],
 
+    "accepts": ["accepts@2.0.0", "", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
+
     "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
 
     "ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
 
     "ajv-draft-04": ["ajv-draft-04@1.0.0", "", { "peerDependencies": { "ajv": "^8.5.0" }, "optionalPeers": ["ajv"] }, "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw=="],
 
+    "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
+
     "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
     "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
@@ -884,7 +1004,7 @@
 
     "babel-dead-code-elimination": ["babel-dead-code-elimination@1.0.12", "", { "dependencies": { "@babel/core": "^7.23.7", "@babel/parser": "^7.23.6", "@babel/traverse": "^7.23.7", "@babel/types": "^7.23.6" } }, "sha512-GERT7L2TiYcYDtYk1IpD+ASAYXjKbLTDPhBtYj7X1NuRMDTMtAx9kyBenub1Ev41lo91OHCKdmP+egTDmfQ7Ig=="],
 
-    "babel-plugin-react-compiler": ["babel-plugin-react-compiler@19.0.0-beta-ebf51a3-20250411", "", { "dependencies": { "@babel/types": "^7.26.0" } }, "sha512-q84bNR9JG1crykAlJUt5Ud0/5BUyMFuQww/mrwIQDFBaxsikqBDj3f/FNDsVd2iR26A1HvXKWPEIfgJDv8/V2g=="],
+    "babel-plugin-react-compiler": ["babel-plugin-react-compiler@1.0.0", "", { "dependencies": { "@babel/types": "^7.26.0" } }, "sha512-Ixm8tFfoKKIPYdCCKYTsqv+Fd4IJ0DQqMyEimo+pxUOMUR9cVPlwTrFt9Avu+3cb6Zp3mAzl+t1MrG2fxxKsxw=="],
 
     "bail": ["bail@2.0.2", "", {}, "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw=="],
 
@@ -894,6 +1014,8 @@
 
     "birpc": ["birpc@4.0.0", "", {}, "sha512-LShSxJP0KTmd101b6DRyGBj57LZxSDYWKitQNW/mi8GRMvZb078Uf9+pveax1DrVL89vm7mWe+TovdI/UDOuPw=="],
 
+    "body-parser": ["body-parser@2.2.2", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.1", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA=="],
+
     "boolbase": ["boolbase@1.0.0", "", {}, "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww=="],
 
     "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],
@@ -906,9 +1028,9 @@
 
     "builder-util-runtime": ["builder-util-runtime@9.5.1", "", { "dependencies": { "debug": "^4.3.4", "sax": "^1.2.4" } }, "sha512-qt41tMfgHTllhResqM5DcnHyDIWNgzHvuY2jDcYP9iaGpkWxTUzV6GQjDeLnlR1/DtdlcsWQbA7sByMpmJFTLQ=="],
 
-    "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
 
-    "bundle-name": ["bundle-name@4.1.0", "", { "dependencies": { "run-applescript": "^7.0.0" } }, "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q=="],
+    "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
 
     "cac": ["cac@6.7.14", "", {}, "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ=="],
 
@@ -916,6 +1038,10 @@
 
     "cacheable-request": ["cacheable-request@7.0.4", "", { "dependencies": { "clone-response": "^1.0.2", "get-stream": "^5.1.0", "http-cache-semantics": "^4.0.0", "keyv": "^4.0.0", "lowercase-keys": "^2.0.0", "normalize-url": "^6.0.1", "responselike": "^2.0.0" } }, "sha512-v+p6ongsrp0yTGbJXjgxPow2+DL93DASP4kXCDKb8/bwRtt9OEF3whggkkDkGNzgcWy2XaF4a8nZglC7uElscg=="],
 
+    "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],
+
+    "call-bound": ["call-bound@1.0.4", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "get-intrinsic": "^1.3.0" } }, "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg=="],
+
     "caniuse-lite": ["caniuse-lite@1.0.30001779", "", {}, "sha512-U5og2PN7V4DMgF50YPNtnZJGWVLFjjsN3zb6uMT5VGYIewieDj1upwfuVNXf4Kor+89c3iCRJnSzMD5LmTvsfA=="],
 
     "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
@@ -956,12 +1082,22 @@
 
     "common-ancestor-path": ["common-ancestor-path@2.0.0", "", {}, "sha512-dnN3ibLeoRf2HNC+OlCiNc5d2zxbLJXOtiZUudNFSXZrNSydxcCsSpRzXwfu7BBWCIfHPw+xTayeBvJCP/D8Ng=="],
 
+    "content-disposition": ["content-disposition@1.1.0", "", {}, "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g=="],
+
+    "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
+
     "convert-source-map": ["convert-source-map@2.0.0", "", {}, "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="],
 
     "cookie": ["cookie@1.1.1", "", {}, "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ=="],
 
     "cookie-es": ["cookie-es@2.0.0", "", {}, "sha512-RAj4E421UYRgqokKUmotqAwuplYw15qtdXfY+hGzgCJ/MBjCVZcSoHK/kH9kocfjRjcDME7IiDWR/1WX1TM2Pg=="],
 
+    "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="],
+
+    "cors": ["cors@2.8.6", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
     "crossws": ["crossws@0.3.5", "", { "dependencies": { "uncrypto": "^0.1.3" } }, "sha512-ojKiDvcmByhwa8YYqbQI/hg7MEU0NC03+pSdEq4ZUnZR9xXpwk7E43SMNGkn+JxJGPFtNvQ48+vV2p+P1ml5PA=="],
 
     "css-select": ["css-select@5.2.2", "", { "dependencies": { "boolbase": "^1.0.0", "css-what": "^6.1.0", "domhandler": "^5.0.2", "domutils": "^3.0.1", "nth-check": "^2.0.1" } }, "sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw=="],
@@ -980,22 +1116,18 @@
 
     "decompress-response": ["decompress-response@6.0.0", "", { "dependencies": { "mimic-response": "^3.1.0" } }, "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ=="],
 
-    "default-browser": ["default-browser@5.5.0", "", { "dependencies": { "bundle-name": "^4.1.0", "default-browser-id": "^5.0.0" } }, "sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw=="],
-
-    "default-browser-id": ["default-browser-id@5.0.1", "", {}, "sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q=="],
-
     "defer-to-connect": ["defer-to-connect@2.0.1", "", {}, "sha512-4tvttepXG1VaYGrRibk5EwJd1t4udunSOVMdLSAL6mId1ix438oPwPZMALY41FCijukO1L0twNcGsdzS7dHgDg=="],
 
     "define-data-property": ["define-data-property@1.1.4", "", { "dependencies": { "es-define-property": "^1.0.0", "es-errors": "^1.3.0", "gopd": "^1.0.1" } }, "sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A=="],
 
-    "define-lazy-prop": ["define-lazy-prop@3.0.0", "", {}, "sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg=="],
-
     "define-properties": ["define-properties@1.2.1", "", { "dependencies": { "define-data-property": "^1.0.1", "has-property-descriptors": "^1.0.0", "object-keys": "^1.1.1" } }, "sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg=="],
 
     "defu": ["defu@6.1.4", "", {}, "sha512-mEQCMmwJu317oSz8CwdIOdwf3xMif1ttiM8LTufzc3g6kR+9Pe236twL8j3IYT1F7GfRgGcW6MWxzZjLIkuHIg=="],
 
     "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
 
+    "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
+
     "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
 
     "destr": ["destr@2.0.5", "", {}, "sha512-ugFTXCtDZunbzasqBxrK93Ik/DRYsO6S/fedkWEMKqt04xZ4csmnmwGDBAb07QWNaGMAmnTIemsYZCksjATwsA=="],
@@ -1024,9 +1156,17 @@
 
     "dts-resolver": ["dts-resolver@2.1.3", "", { "peerDependencies": { "oxc-resolver": ">=11.0.0" }, "optionalPeers": ["oxc-resolver"] }, "sha512-bihc7jPC90VrosXNzK0LTE2cuLP6jr0Ro8jk+kMugHReJVLIpHz/xadeq3MhuwyO4TD4OA3L1Q8pBBFRc08Tsw=="],
 
-    "effect": ["effect@4.0.0-beta.45", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.5.3", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.8", "multipasta": "^0.2.7", "toml": "^3.0.0", "uuid": "^13.0.0", "yaml": "^2.8.2" } }, "sha512-vvNrUWqnzBIW1hRMa+zw0CLRW6HLgdu7hQ6K7PT/rS+UY/73Ma11O+Oi9oc9zwL8KcN37M47UDseAdlF0bGNWw=="],
+    "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
+
+    "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
 
-    "electron": ["electron@40.6.0", "", { "dependencies": { "@electron/get": "^2.0.0", "@types/node": "^24.9.0", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js" } }, "sha512-ett8W+yOFGDuM0vhJMamYSkrbV3LoaffzJd9GfjI96zRAxyrNqUSKqBpf/WGbQCweDxX2pkUCUfrv4wwKpsFZA=="],
+    "effect": ["effect@4.0.0-beta.59", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.6.0", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.9", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^13.0.0", "yaml": "^2.8.3" } }, "sha512-xyUDLeHSe8d6lWGOvR6Fgn2HL6gYeTZ/S4Jzk9uc4ZUxMPPsNZlNXrvk0C7/utQFzeX7uAWcVnG2BjbA0SRoAA=="],
+
+    "effect-acp": ["effect-acp@workspace:packages/effect-acp"],
+
+    "effect-codex-app-server": ["effect-codex-app-server@workspace:packages/effect-codex-app-server"],
+
+    "electron": ["electron@41.5.0", "", { "dependencies": { "@electron/get": "^2.0.0", "@types/node": "^24.9.0", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js" } }, "sha512-x9j9//PubUA4EjDtQbZhtk3prolandqCKgit0uCIqc1jb8FTskPbnJtxcDFB1aejczJcuERgjPixBUaMwoWyJg=="],
 
     "electron-to-chromium": ["electron-to-chromium@1.5.313", "", {}, "sha512-QBMrTWEf00GXZmJyx2lbYD45jpI3TUFnNIzJ5BBc8piGUDwMPa1GV6HJWTZVvY/eiN3fSopl7NRbgGp9sZ9LTA=="],
 
@@ -1038,6 +1178,8 @@
 
     "empathic": ["empathic@2.0.0", "", {}, "sha512-i6UzDscO/XfAcNYD75CfICkmfLedpyPDdozrLMmQc5ORaQcdMoc21OnlEylMIqI7U8eniKrPMxxtj8k0vhmJhA=="],
 
+    "encodeurl": ["encodeurl@2.0.0", "", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
+
     "end-of-stream": ["end-of-stream@1.4.5", "", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
 
     "enhanced-resolve": ["enhanced-resolve@5.20.0", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.0" } }, "sha512-/ce7+jQ1PQ6rVXwe+jKEg5hW5ciicHwIQUagZkp6IufBoY3YDgdTTY1azVs0qoRgVmvsNB+rbjLJxDAeHHtwsQ=="],
@@ -1052,12 +1194,16 @@
 
     "es-module-lexer": ["es-module-lexer@2.0.0", "", {}, "sha512-5POEcUuZybH7IdmGsD8wlf0AI55wMecM9rVBTI/qEAy2c1kTOm3DjFYjrBdI2K3BaJjJYfYFeRtM0t9ssnRuxw=="],
 
+    "es-object-atoms": ["es-object-atoms@1.1.1", "", { "dependencies": { "es-errors": "^1.3.0" } }, "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA=="],
+
     "es6-error": ["es6-error@4.1.1", "", {}, "sha512-Um/+FxMr9CISWh0bi5Zv0iOD+4cFh5qLeks1qhAopKVAJw3drgKbKySikp7wGhDL0HPeaja0P5ULZrxLkniUVg=="],
 
     "esbuild": ["esbuild@0.27.4", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.27.4", "@esbuild/android-arm": "0.27.4", "@esbuild/android-arm64": "0.27.4", "@esbuild/android-x64": "0.27.4", "@esbuild/darwin-arm64": "0.27.4", "@esbuild/darwin-x64": "0.27.4", "@esbuild/freebsd-arm64": "0.27.4", "@esbuild/freebsd-x64": "0.27.4", "@esbuild/linux-arm": "0.27.4", "@esbuild/linux-arm64": "0.27.4", "@esbuild/linux-ia32": "0.27.4", "@esbuild/linux-loong64": "0.27.4", "@esbuild/linux-mips64el": "0.27.4", "@esbuild/linux-ppc64": "0.27.4", "@esbuild/linux-riscv64": "0.27.4", "@esbuild/linux-s390x": "0.27.4", "@esbuild/linux-x64": "0.27.4", "@esbuild/netbsd-arm64": "0.27.4", "@esbuild/netbsd-x64": "0.27.4", "@esbuild/openbsd-arm64": "0.27.4", "@esbuild/openbsd-x64": "0.27.4", "@esbuild/openharmony-arm64": "0.27.4", "@esbuild/sunos-x64": "0.27.4", "@esbuild/win32-arm64": "0.27.4", "@esbuild/win32-ia32": "0.27.4", "@esbuild/win32-x64": "0.27.4" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ=="],
 
     "escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
 
+    "escape-html": ["escape-html@1.0.3", "", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
+
     "escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
 
     "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
@@ -1066,10 +1212,20 @@
 
     "estree-walker": ["estree-walker@3.0.3", "", { "dependencies": { "@types/estree": "^1.0.0" } }, "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g=="],
 
+    "etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
+
     "eventemitter3": ["eventemitter3@5.0.4", "", {}, "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="],
 
+    "eventsource": ["eventsource@3.0.7", "", { "dependencies": { "eventsource-parser": "^3.0.1" } }, "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA=="],
+
+    "eventsource-parser": ["eventsource-parser@3.0.6", "", {}, "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg=="],
+
     "expect-type": ["expect-type@1.3.0", "", {}, "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA=="],
 
+    "express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
+
+    "express-rate-limit": ["express-rate-limit@8.3.2", "", { "dependencies": { "ip-address": "10.1.0" }, "peerDependencies": { "express": ">= 4.11" } }, "sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg=="],
+
     "extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="],
 
     "extract-zip": ["extract-zip@2.0.1", "", { "dependencies": { "debug": "^4.1.1", "get-stream": "^5.1.0", "yauzl": "^2.10.0" }, "optionalDependencies": { "@types/yauzl": "^2.9.1" }, "bin": { "extract-zip": "cli.js" } }, "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg=="],
@@ -1078,6 +1234,8 @@
 
     "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
 
+    "fast-json-stable-stringify": ["fast-json-stable-stringify@2.1.0", "", {}, "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw=="],
+
     "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="],
 
     "fd-slicer": ["fd-slicer@1.1.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g=="],
@@ -1086,6 +1244,8 @@
 
     "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
 
+    "finalhandler": ["finalhandler@2.1.1", "", { "dependencies": { "debug": "^4.4.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "on-finished": "^2.4.1", "parseurl": "^1.3.3", "statuses": "^2.0.1" } }, "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA=="],
+
     "find-my-way-ts": ["find-my-way-ts@0.1.6", "", {}, "sha512-a85L9ZoXtNAey3Y6Z+eBWW658kO/MwR7zIafkIUPUMf3isZG0NCs2pjW2wtjxAKuJPxMAsHUIP4ZPGv0o5gyTA=="],
 
     "flattie": ["flattie@1.1.1", "", {}, "sha512-9UbaD6XdAL97+k/n+N7JwX46K/M6Zc6KcFYskrYL8wbBV/Uyk0CTAMY0VT+qiK5PM7AIc9aTWYtq65U7T+aCNQ=="],
@@ -1094,14 +1254,24 @@
 
     "fontkitten": ["fontkitten@1.0.3", "", { "dependencies": { "tiny-inflate": "^1.0.3" } }, "sha512-Wp1zXWPVUPBmfoa3Cqc9ctaKuzKAV6uLstRqlR56kSjplf5uAce+qeyYym7F+PHbGTk+tCEdkCW6RD7DX/gBZw=="],
 
+    "forwarded": ["forwarded@0.2.0", "", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
+
+    "fresh": ["fresh@2.0.0", "", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
+
     "fs-extra": ["fs-extra@10.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ=="],
 
     "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
 
+    "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
+
     "gensync": ["gensync@1.0.0-beta.2", "", {}, "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg=="],
 
     "get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
 
+    "get-intrinsic": ["get-intrinsic@1.3.0", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.2", "es-define-property": "^1.0.1", "es-errors": "^1.3.0", "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", "get-proto": "^1.0.1", "gopd": "^1.2.0", "has-symbols": "^1.1.0", "hasown": "^2.0.2", "math-intrinsics": "^1.1.0" } }, "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ=="],
+
+    "get-proto": ["get-proto@1.0.1", "", { "dependencies": { "dunder-proto": "^1.0.1", "es-object-atoms": "^1.0.0" } }, "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g=="],
+
     "get-stream": ["get-stream@5.2.0", "", { "dependencies": { "pump": "^3.0.0" } }, "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA=="],
 
     "get-tsconfig": ["get-tsconfig@4.13.6", "", { "dependencies": { "resolve-pkg-maps": "^1.0.0" } }, "sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw=="],
@@ -1126,6 +1296,10 @@
 
     "has-property-descriptors": ["has-property-descriptors@1.0.2", "", { "dependencies": { "es-define-property": "^1.0.0" } }, "sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg=="],
 
+    "has-symbols": ["has-symbols@1.1.0", "", {}, "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ=="],
+
+    "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
     "hast-util-from-html": ["hast-util-from-html@2.0.3", "", { "dependencies": { "@types/hast": "^3.0.0", "devlop": "^1.1.0", "hast-util-from-parse5": "^8.0.0", "parse5": "^7.0.0", "vfile": "^6.0.0", "vfile-message": "^4.0.0" } }, "sha512-CUSRHXyKjzHov8yKsQjGOElXy/3EKpyX56ELnkHH34vDVw1N1XSQ1ZcAvTyAPtGqLTuKP/uxM+aLkSPqF/EtMw=="],
 
     "hast-util-from-parse5": ["hast-util-from-parse5@8.0.3", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "devlop": "^1.0.0", "hastscript": "^9.0.0", "property-information": "^7.0.0", "vfile": "^6.0.0", "vfile-location": "^5.0.0", "web-namespaces": "^2.0.0" } }, "sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg=="],
@@ -1150,6 +1324,8 @@
 
     "headers-polyfill": ["headers-polyfill@4.0.3", "", {}, "sha512-IScLbePpkvO846sIwOtOTDjutRMWdXdJmXdMvk6gCBHxFO8d+QKOQedyZSxFTTFYRSmlgSTDtXqqq4pcenBXLQ=="],
 
+    "hono": ["hono@4.12.14", "", {}, "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w=="],
+
     "hookable": ["hookable@6.1.0", "", {}, "sha512-ZoKZSJgu8voGK2geJS+6YtYjvIzu9AOM/KZXsBxr83uhLL++e9pEv/dlgwgy3dvHg06kTz6JOh1hk3C8Ceiymw=="],
 
     "html-escaper": ["html-escaper@3.0.3", "", {}, "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ=="],
@@ -1160,16 +1336,26 @@
 
     "http-cache-semantics": ["http-cache-semantics@4.2.0", "", {}, "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ=="],
 
+    "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
+
     "http2-wrapper": ["http2-wrapper@1.0.3", "", { "dependencies": { "quick-lru": "^5.1.1", "resolve-alpn": "^1.0.0" } }, "sha512-V+23sDMr12Wnz7iTcDeJr3O6AIxlnvT/bmaAAAP/Xda35C90p9599p0F1eHR/N1KILWSoWVAiOMFjBBXaXSMxg=="],
 
+    "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
+
     "import-without-cache": ["import-without-cache@0.2.5", "", {}, "sha512-B6Lc2s6yApwnD2/pMzFh/d5AVjdsDXjgkeJ766FmFuJELIGHNycKRj+l3A39yZPM4CchqNCB4RITEAYB1KUM6A=="],
 
+    "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
+
     "ini": ["ini@6.0.0", "", {}, "sha512-IBTdIkzZNOpqm7q3dRqJvMaldXjDHWkEDfrwGEQTs5eaQMWV+djAhR+wahyNNMAa+qpbDUhBMVt4ZKNwpPm7xQ=="],
 
     "inline-style-parser": ["inline-style-parser@0.2.7", "", {}, "sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA=="],
 
     "ioredis": ["ioredis@5.10.0", "", { "dependencies": { "@ioredis/commands": "1.5.1", "cluster-key-slot": "^1.1.0", "debug": "^4.3.4", "denque": "^2.1.0", "lodash.defaults": "^4.2.0", "lodash.isarguments": "^3.1.0", "redis-errors": "^1.2.0", "redis-parser": "^3.0.0", "standard-as-callback": "^2.1.0" } }, "sha512-HVBe9OFuqs+Z6n64q09PQvP1/R4Bm+30PAyyD4wIEqssh3v9L21QjCVk4kRLucMBcDokJTcLjsGeVRlq/nH6DA=="],
 
+    "ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="],
+
+    "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="],
+
     "iron-webcrypto": ["iron-webcrypto@1.2.1", "", {}, "sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg=="],
 
     "is-alphabetical": ["is-alphabetical@2.0.1", "", {}, "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ=="],
@@ -1198,14 +1384,20 @@
 
     "is-plain-obj": ["is-plain-obj@4.1.0", "", {}, "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg=="],
 
+    "is-promise": ["is-promise@4.0.0", "", {}, "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ=="],
+
     "is-wsl": ["is-wsl@3.1.1", "", { "dependencies": { "is-inside-container": "^1.0.0" } }, "sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw=="],
 
     "isbot": ["isbot@5.1.36", "", {}, "sha512-C/ZtXyJqDPZ7G7JPr06ApWyYoHjYexQbS6hPYD4WYCzpv2Qes6Z+CCEfTX4Owzf+1EJ933PoI2p+B9v7wpGZBQ=="],
 
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
     "isomorphic.js": ["isomorphic.js@0.2.5", "", {}, "sha512-PIeMbHqMt4DnUP3MA/Flc0HElYjMXArsw1qwJZcm9sqR8mq3l8NYizFMty0pWwE/tzIGH3EKK5+jes5mAr85yw=="],
 
     "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
 
+    "jose": ["jose@6.2.2", "", {}, "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ=="],
+
     "js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
 
     "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
@@ -1214,8 +1406,12 @@
 
     "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
 
+    "json-schema-to-ts": ["json-schema-to-ts@3.1.1", "", { "dependencies": { "@babel/runtime": "^7.18.3", "ts-algebra": "^2.0.0" } }, "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g=="],
+
     "json-schema-traverse": ["json-schema-traverse@1.0.0", "", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
 
+    "json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
+
     "json-stringify-safe": ["json-stringify-safe@5.0.1", "", {}, "sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA=="],
 
     "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
@@ -1286,6 +1482,8 @@
 
     "matcher": ["matcher@3.0.0", "", { "dependencies": { "escape-string-regexp": "^4.0.0" } }, "sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng=="],
 
+    "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
+
     "mdast-util-definitions": ["mdast-util-definitions@6.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "unist-util-visit": "^5.0.0" } }, "sha512-scTllyX6pnYNZH/AIp/0ePz6s4cZtARxImwoPJ7kS42n+MnVsI4XbnG6d4ibehRIldYMWM2LD7ImQblVhUejVQ=="],
 
     "mdast-util-find-and-replace": ["mdast-util-find-and-replace@3.0.2", "", { "dependencies": { "@types/mdast": "^4.0.0", "escape-string-regexp": "^5.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg=="],
@@ -1320,6 +1518,10 @@
 
     "mdn-data": ["mdn-data@2.27.1", "", {}, "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ=="],
 
+    "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
+
+    "merge-descriptors": ["merge-descriptors@2.0.0", "", {}, "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g=="],
+
     "micromark": ["micromark@4.0.2", "", { "dependencies": { "@types/debug": "^4.0.0", "debug": "^4.0.0", "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-core-commonmark": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-combine-extensions": "^2.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA=="],
 
     "micromark-core-commonmark": ["micromark-core-commonmark@2.0.3", "", { "dependencies": { "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-factory-destination": "^2.0.0", "micromark-factory-label": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-factory-title": "^2.0.0", "micromark-factory-whitespace": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-html-tag-name": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg=="],
@@ -1378,6 +1580,10 @@
 
     "mime": ["mime@4.1.0", "", { "bin": { "mime": "bin/cli.js" } }, "sha512-X5ju04+cAzsojXKes0B/S4tcYtFAJ6tTMuSPBEn9CPGlrWr8Fiw7qYeLT0XyH80HSoAoqWCaz+MWKh22P7G1cw=="],
 
+    "mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
+
+    "mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
+
     "mimic-response": ["mimic-response@3.1.0", "", {}, "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ=="],
 
     "mrmime": ["mrmime@2.0.1", "", {}, "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ=="],
@@ -1398,6 +1604,8 @@
 
     "nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
 
+    "negotiator": ["negotiator@1.0.0", "", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
+
     "neotraverse": ["neotraverse@0.6.18", "", {}, "sha512-Z4SmBUweYa09+o6pG+eASabEpP6QkQ70yHj351pQoEXIs8uHbaU2DWVmzBANKgflPa47A50PtB2+NgRpQvr7vA=="],
 
     "nlcst-to-string": ["nlcst-to-string@4.0.0", "", { "dependencies": { "@types/nlcst": "^2.0.0" } }, "sha512-YKLBCcUYKAg0FNlOBT6aI91qFmSiFKiluk655WzPF+DDMA02qIyy8uiRqI8QXtcFpEvll12LpL5MXqEmAZ+dcA=="],
@@ -1420,6 +1628,10 @@
 
     "nth-check": ["nth-check@2.1.1", "", { "dependencies": { "boolbase": "^1.0.0" } }, "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w=="],
 
+    "object-assign": ["object-assign@4.1.1", "", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
+
+    "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
+
     "object-keys": ["object-keys@1.1.1", "", {}, "sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA=="],
 
     "obug": ["obug@2.1.1", "", {}, "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ=="],
@@ -1428,19 +1640,19 @@
 
     "ohash": ["ohash@2.0.11", "", {}, "sha512-RdR9FQrFwNBNXAr4GixM8YaRZRJ5PUWbKYbE5eOsrwAjJW0q2REGcf79oYPsLyskQCZG1PLN+S/K1V00joZAoQ=="],
 
+    "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
+
     "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
 
     "oniguruma-parser": ["oniguruma-parser@0.12.1", "", {}, "sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w=="],
 
     "oniguruma-to-es": ["oniguruma-to-es@4.3.5", "", { "dependencies": { "oniguruma-parser": "^0.12.1", "regex": "^6.1.0", "regex-recursion": "^6.0.2" } }, "sha512-Zjygswjpsewa0NLTsiizVuMQZbp0MDyM6lIt66OxsF21npUDlzpHi1Mgb/qhQdkb+dWFTzJmFbEWdvZgRho8eQ=="],
 
-    "open": ["open@10.2.0", "", { "dependencies": { "default-browser": "^5.2.1", "define-lazy-prop": "^3.0.0", "is-inside-container": "^1.0.0", "wsl-utils": "^0.1.0" } }, "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA=="],
-
     "outvariant": ["outvariant@1.4.3", "", {}, "sha512-+Sl2UErvtsoajRDKCE5/dBz4DIvHXQQnAxtQTF04OJxY0+DyZXSo5P5Bb7XYWOh81syohlYL24hbDwxedPUJCA=="],
 
     "oxfmt": ["oxfmt@0.40.0", "", { "dependencies": { "tinypool": "2.1.0" }, "optionalDependencies": { "@oxfmt/binding-android-arm-eabi": "0.40.0", "@oxfmt/binding-android-arm64": "0.40.0", "@oxfmt/binding-darwin-arm64": "0.40.0", "@oxfmt/binding-darwin-x64": "0.40.0", "@oxfmt/binding-freebsd-x64": "0.40.0", "@oxfmt/binding-linux-arm-gnueabihf": "0.40.0", "@oxfmt/binding-linux-arm-musleabihf": "0.40.0", "@oxfmt/binding-linux-arm64-gnu": "0.40.0", "@oxfmt/binding-linux-arm64-musl": "0.40.0", "@oxfmt/binding-linux-ppc64-gnu": "0.40.0", "@oxfmt/binding-linux-riscv64-gnu": "0.40.0", "@oxfmt/binding-linux-riscv64-musl": "0.40.0", "@oxfmt/binding-linux-s390x-gnu": "0.40.0", "@oxfmt/binding-linux-x64-gnu": "0.40.0", "@oxfmt/binding-linux-x64-musl": "0.40.0", "@oxfmt/binding-openharmony-arm64": "0.40.0", "@oxfmt/binding-win32-arm64-msvc": "0.40.0", "@oxfmt/binding-win32-ia32-msvc": "0.40.0", "@oxfmt/binding-win32-x64-msvc": "0.40.0" }, "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-g0C3I7xUj4b4DcagevM9kgH6+pUHytikxUcn3/VUkvzTNaaXBeyZqb7IBsHwojeXm4mTBEC/aBjBTMVUkZwWUQ=="],
 
-    "oxlint": ["oxlint@1.56.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.56.0", "@oxlint/binding-android-arm64": "1.56.0", "@oxlint/binding-darwin-arm64": "1.56.0", "@oxlint/binding-darwin-x64": "1.56.0", "@oxlint/binding-freebsd-x64": "1.56.0", "@oxlint/binding-linux-arm-gnueabihf": "1.56.0", "@oxlint/binding-linux-arm-musleabihf": "1.56.0", "@oxlint/binding-linux-arm64-gnu": "1.56.0", "@oxlint/binding-linux-arm64-musl": "1.56.0", "@oxlint/binding-linux-ppc64-gnu": "1.56.0", "@oxlint/binding-linux-riscv64-gnu": "1.56.0", "@oxlint/binding-linux-riscv64-musl": "1.56.0", "@oxlint/binding-linux-s390x-gnu": "1.56.0", "@oxlint/binding-linux-x64-gnu": "1.56.0", "@oxlint/binding-linux-x64-musl": "1.56.0", "@oxlint/binding-openharmony-arm64": "1.56.0", "@oxlint/binding-win32-arm64-msvc": "1.56.0", "@oxlint/binding-win32-ia32-msvc": "1.56.0", "@oxlint/binding-win32-x64-msvc": "1.56.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.15.0" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-Q+5Mj5PVaH/R6/fhMMFzw4dT+KPB+kQW4kaL8FOIq7tfhlnEVp6+3lcWqFruuTNlUo9srZUW3qH7Id4pskeR6g=="],
+    "oxlint": ["oxlint@1.63.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.63.0", "@oxlint/binding-android-arm64": "1.63.0", "@oxlint/binding-darwin-arm64": "1.63.0", "@oxlint/binding-darwin-x64": "1.63.0", "@oxlint/binding-freebsd-x64": "1.63.0", "@oxlint/binding-linux-arm-gnueabihf": "1.63.0", "@oxlint/binding-linux-arm-musleabihf": "1.63.0", "@oxlint/binding-linux-arm64-gnu": "1.63.0", "@oxlint/binding-linux-arm64-musl": "1.63.0", "@oxlint/binding-linux-ppc64-gnu": "1.63.0", "@oxlint/binding-linux-riscv64-gnu": "1.63.0", "@oxlint/binding-linux-riscv64-musl": "1.63.0", "@oxlint/binding-linux-s390x-gnu": "1.63.0", "@oxlint/binding-linux-x64-gnu": "1.63.0", "@oxlint/binding-linux-x64-musl": "1.63.0", "@oxlint/binding-openharmony-arm64": "1.63.0", "@oxlint/binding-win32-arm64-msvc": "1.63.0", "@oxlint/binding-win32-ia32-msvc": "1.63.0", "@oxlint/binding-win32-x64-msvc": "1.63.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.22.1" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-9TGXetdjgIHOJ9OiReomP7nnrMkV9HxC1xM2ramJSLQpzxjsAJtQwa4wqkJN2f/uCrqZuJseFuSlWDdvcruveg=="],
 
     "p-cancelable": ["p-cancelable@2.1.1", "", {}, "sha512-BZOr3nRQHOntUjTrH8+Lh54smKHoHyur8We1V8DSMVrl5A2malOOwuJRnKRDjSnkoeBh4at6BwEnb5I7Jl31wg=="],
 
@@ -1458,10 +1670,16 @@
 
     "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
 
+    "parseurl": ["parseurl@1.3.3", "", {}, "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ=="],
+
     "path-browserify": ["path-browserify@1.0.1", "", {}, "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g=="],
 
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
     "path-to-regexp": ["path-to-regexp@6.3.0", "", {}, "sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ=="],
 
+    "path-to-regexp-updated": ["path-to-regexp@6.3.0", "", {}, "sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ=="],
+
     "pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="],
 
     "pend": ["pend@1.2.0", "", {}, "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg=="],
@@ -1472,6 +1690,8 @@
 
     "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
+    "pkce-challenge": ["pkce-challenge@5.0.1", "", {}, "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ=="],
+
     "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
 
     "playwright-core": ["playwright-core@1.58.2", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
@@ -1482,25 +1702,37 @@
 
     "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
 
+    "pretty-cache-header": ["pretty-cache-header@1.0.0", "", { "dependencies": { "timestring": "^6.0.0" } }, "sha512-xtXazslu25CdnGnUkByU1RoOjK55TqwatJkjjJLg5ZAdz2Lngko/mmaUgeET36P2GMlNwh3fdM7FWBO717pNcw=="],
+
     "prismjs": ["prismjs@1.30.0", "", {}, "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw=="],
 
     "progress": ["progress@2.0.3", "", {}, "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA=="],
 
     "property-information": ["property-information@7.1.0", "", {}, "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ=="],
 
+    "proxy-addr": ["proxy-addr@2.0.7", "", { "dependencies": { "forwarded": "0.2.0", "ipaddr.js": "1.9.1" } }, "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg=="],
+
     "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
 
+    "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
+
     "pure-rand": ["pure-rand@8.1.0", "", {}, "sha512-53B3MB8wetRdD6JZ4W/0gDKaOvKwuXrEmV1auQc0hASWge8rieKV4PCCVNVbJ+i24miiubb4c/B+dg8Ho0ikYw=="],
 
+    "qs": ["qs@6.15.1", "", { "dependencies": { "side-channel": "^1.1.0" } }, "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg=="],
+
     "quansync": ["quansync@1.0.0", "", {}, "sha512-5xZacEEufv3HSTPQuchrvV6soaiACMFnq1H8wkVioctoH3TRha9Sz66lOxRwPK/qZj7HPiSveih9yAyh98gvqA=="],
 
     "quick-lru": ["quick-lru@5.1.1", "", {}, "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA=="],
 
     "radix3": ["radix3@1.1.2", "", {}, "sha512-b484I/7b8rDEdSDKckSSBA8knMpcdsXudlE/LNL639wFoHKwLbEkQFZHWEYwDC0wa0FKUcCY+GAF73Z7wxNVFA=="],
 
-    "react": ["react@19.2.4", "", {}, "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ=="],
+    "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="],
+
+    "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
 
-    "react-dom": ["react-dom@19.2.4", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.4" } }, "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ=="],
+    "react": ["react@19.2.6", "", {}, "sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q=="],
+
+    "react-dom": ["react-dom@19.2.6", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.6" } }, "sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g=="],
 
     "react-error-boundary": ["react-error-boundary@6.1.1", "", { "peerDependencies": { "react": "^18.0.0 || ^19.0.0" } }, "sha512-BrYwPOdXi5mqkk5lw+Uvt0ThHx32rCt3BkukS4X23A2AIWDPSGX6iaWTc0y9TU/mHDA/6qOSGel+B2ERkOvD1w=="],
 
@@ -1568,7 +1800,9 @@
 
     "rolldown-plugin-dts": ["rolldown-plugin-dts@0.22.5", "", { "dependencies": { "@babel/generator": "8.0.0-rc.2", "@babel/helper-validator-identifier": "8.0.0-rc.2", "@babel/parser": "8.0.0-rc.2", "@babel/types": "8.0.0-rc.2", "ast-kit": "^3.0.0-beta.1", "birpc": "^4.0.0", "dts-resolver": "^2.1.3", "get-tsconfig": "^4.13.6", "obug": "^2.1.1" }, "peerDependencies": { "@ts-macro/tsc": "^0.3.6", "@typescript/native-preview": ">=7.0.0-dev.20250601.1", "rolldown": "^1.0.0-rc.3", "typescript": "^5.0.0 || ^6.0.0-beta", "vue-tsc": "~3.2.0" }, "optionalPeers": ["@ts-macro/tsc", "@typescript/native-preview", "typescript", "vue-tsc"] }, "sha512-M/HXfM4cboo+jONx9Z0X+CUf3B5tCi7ni+kR5fUW50Fp9AlZk0oVLesibGWgCXDKFp5lpgQ9yhKoImUFjl3VZw=="],
 
-    "run-applescript": ["run-applescript@7.1.0", "", {}, "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q=="],
+    "router": ["router@2.2.0", "", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
 
     "sax": ["sax@1.5.0", "", {}, "sha512-21IYA3Q5cQf089Z6tgaUTr7lDAyzoTPx5HRtbhsME8Udispad8dC/+sziTNugOEx54ilvatQ9YCzl4KQLPcRHA=="],
 
@@ -1578,16 +1812,34 @@
 
     "semver-compare": ["semver-compare@1.0.0", "", {}, "sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow=="],
 
+    "send": ["send@1.2.1", "", { "dependencies": { "debug": "^4.4.3", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "fresh": "^2.0.0", "http-errors": "^2.0.1", "mime-types": "^3.0.2", "ms": "^2.1.3", "on-finished": "^2.4.1", "range-parser": "^1.2.1", "statuses": "^2.0.2" } }, "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ=="],
+
     "serialize-error": ["serialize-error@7.0.1", "", { "dependencies": { "type-fest": "^0.13.1" } }, "sha512-8I8TjW5KMOKsZQTvoxjuSIa7foAwPWGOts+6o7sgjz41/qMD9VQHEDxi6PBvK2l0MXUmqZyNpUK+T2tQaaElvw=="],
 
     "seroval": ["seroval@1.5.1", "", {}, "sha512-OwrZRZAfhHww0WEnKHDY8OM0U/Qs8OTfIDWhUD4BLpNJUfXK4cGmjiagGze086m+mhI+V2nD0gfbHEnJjb9STA=="],
 
     "seroval-plugins": ["seroval-plugins@1.5.1", "", { "peerDependencies": { "seroval": "^1.0" } }, "sha512-4FbuZ/TMl02sqv0RTFexu0SP6V+ywaIe5bAWCCEik0fk17BhALgwvUDVF7e3Uvf9pxmwCEJsRPmlkUE6HdzLAw=="],
 
+    "serve-static": ["serve-static@2.2.1", "", { "dependencies": { "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "parseurl": "^1.3.3", "send": "^1.2.0" } }, "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw=="],
+
+    "setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
+
     "sharp": ["sharp@0.34.5", "", { "dependencies": { "@img/colour": "^1.0.0", "detect-libc": "^2.1.2", "semver": "^7.7.3" }, "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" } }, "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg=="],
 
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
     "shiki": ["shiki@4.0.2", "", { "dependencies": { "@shikijs/core": "4.0.2", "@shikijs/engine-javascript": "4.0.2", "@shikijs/engine-oniguruma": "4.0.2", "@shikijs/langs": "4.0.2", "@shikijs/themes": "4.0.2", "@shikijs/types": "4.0.2", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-eAVKTMedR5ckPo4xne/PjYQYrU3qx78gtJZ+sHlXEg5IHhhoQhMfZVzetTYuaJS0L2Ef3AcCRzCHV8T0WI6nIQ=="],
 
+    "side-channel": ["side-channel@1.1.0", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.3", "side-channel-list": "^1.0.0", "side-channel-map": "^1.0.1", "side-channel-weakmap": "^1.0.2" } }, "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw=="],
+
+    "side-channel-list": ["side-channel-list@1.0.1", "", { "dependencies": { "es-errors": "^1.3.0", "object-inspect": "^1.13.4" } }, "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w=="],
+
+    "side-channel-map": ["side-channel-map@1.0.1", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3" } }, "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA=="],
+
+    "side-channel-weakmap": ["side-channel-weakmap@1.0.2", "", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "get-intrinsic": "^1.2.5", "object-inspect": "^1.13.3", "side-channel-map": "^1.0.1" } }, "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A=="],
+
     "siginfo": ["siginfo@2.0.0", "", {}, "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g=="],
 
     "signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
@@ -1642,6 +1894,8 @@
 
     "tapable": ["tapable@2.3.0", "", {}, "sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg=="],
 
+    "timestring": ["timestring@6.0.0", "", {}, "sha512-wMctrWD2HZZLuIlchlkE2dfXJh7J2KDI9Dwl+2abPYg0mswQHfOAyQW3jJg1pY5VfttSINZuKcXoB3FGypVklA=="],
+
     "tiny-inflate": ["tiny-inflate@1.0.3", "", {}, "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw=="],
 
     "tiny-invariant": ["tiny-invariant@1.3.3", "", {}, "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg=="],
@@ -1668,7 +1922,9 @@
 
     "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
 
-    "toml": ["toml@3.0.0", "", {}, "sha512-y/mWCZinnvxjTKYhJ+pYxwD0mRLVvOtdS2Awbgxln6iEnt4rk0yBxeSBHkGJcPucRiG0e55mwWp+g/05rsrd6w=="],
+    "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
+
+    "toml": ["toml@4.1.1", "", {}, "sha512-EBJnVBr3dTXdA89WVFoAIPUqkBjxPMwRqsfuo1r240tKFHXv3zgca4+NJib/h6TyvGF7vOawz0jGuryJCdNHrw=="],
 
     "totalist": ["totalist@3.0.1", "", {}, "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ=="],
 
@@ -1680,6 +1936,8 @@
 
     "trough": ["trough@2.2.0", "", {}, "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw=="],
 
+    "ts-algebra": ["ts-algebra@2.0.0", "", {}, "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw=="],
+
     "tsconfck": ["tsconfck@3.1.6", "", { "peerDependencies": { "typescript": "^5.0.0" }, "optionalPeers": ["typescript"], "bin": { "tsconfck": "bin/tsconfck.js" } }, "sha512-ks6Vjr/jEw0P1gmOVwutM3B7fWxoWBL2KRDb1JfqGVawBmO5UsvmWOQFGHBPl5yxYz4eERr19E6L7NMv+Fej4w=="],
 
     "tsdown": ["tsdown@0.20.3", "", { "dependencies": { "ansis": "^4.2.0", "cac": "^6.7.14", "defu": "^6.1.4", "empathic": "^2.0.0", "hookable": "^6.0.1", "import-without-cache": "^0.2.5", "obug": "^2.1.1", "picomatch": "^4.0.3", "rolldown": "1.0.0-rc.3", "rolldown-plugin-dts": "^0.22.1", "semver": "^7.7.3", "tinyexec": "^1.0.2", "tinyglobby": "^0.2.15", "tree-kill": "^1.2.2", "unconfig-core": "^7.4.2", "unrun": "^0.2.27" }, "peerDependencies": { "@arethetypeswrong/core": "^0.18.1", "@vitejs/devtools": "*", "publint": "^0.3.0", "typescript": "^5.0.0", "unplugin-lightningcss": "^0.4.0", "unplugin-unused": "^0.5.0" }, "optionalPeers": ["@arethetypeswrong/core", "@vitejs/devtools", "publint", "typescript", "unplugin-lightningcss", "unplugin-unused"], "bin": { "tsdown": "dist/run.mjs" } }, "sha512-qWOUXSbe4jN8JZEgrkc/uhJpC8VN2QpNu3eZkBWwNuTEjc/Ik1kcc54ycfcQ5QPRHeu9OQXaLfCI3o7pEJgB2w=="],
@@ -1704,6 +1962,8 @@
 
     "type-fest": ["type-fest@5.4.4", "", { "dependencies": { "tagged-tag": "^1.0.0" } }, "sha512-JnTrzGu+zPV3aXIUhnyWJj4z/wigMsdYajGLIYakqyOW1nPllzXEJee0QQbHj+CTIQtXGlAjuK0UY+2xTyjVAw=="],
 
+    "type-is": ["type-is@2.0.1", "", { "dependencies": { "content-type": "^1.0.5", "media-typer": "^1.1.0", "mime-types": "^3.0.0" } }, "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw=="],
+
     "typesafe-path": ["typesafe-path@0.2.2", "", {}, "sha512-OJabfkAg1WLZSqJAJ0Z6Sdt3utnbzr/jh+NAHoyWHJe8CMSy79Gm085094M9nvTPy22KzTVn5Zq5mbapCI/hPA=="],
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
@@ -1718,7 +1978,7 @@
 
     "uncrypto": ["uncrypto@0.1.3", "", {}, "sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q=="],
 
-    "undici": ["undici@7.24.4", "", {}, "sha512-BM/JzwwaRXxrLdElV2Uo6cTLEjhSb3WXboncJamZ15NgUURmvlXvxa6xkwIOILIjPNo9i8ku136ZvWV0Uly8+w=="],
+    "undici": ["undici@8.2.0", "", {}, "sha512-Z+4Hx9GE26Lh9Upwfnc8C7SsrpBPGaM/Gm6kMFtiG7c+5IvQKlXi/t+9x9DrrCh29cww5TSP9YdVaBcnLDs5fQ=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
@@ -1746,6 +2006,8 @@
 
     "universalify": ["universalify@2.0.1", "", {}, "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw=="],
 
+    "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
+
     "unplugin": ["unplugin@2.3.11", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "acorn": "^8.15.0", "picomatch": "^4.0.3", "webpack-virtual-modules": "^0.6.2" } }, "sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww=="],
 
     "unrun": ["unrun@0.2.32", "", { "dependencies": { "rolldown": "1.0.0-rc.9" }, "peerDependencies": { "synckit": "^0.11.11" }, "optionalPeers": ["synckit"], "bin": { "unrun": "dist/cli.mjs" } }, "sha512-opd3z6791rf281JdByf0RdRQrpcc7WyzqittqIXodM/5meNWdTwrVxeyzbaCp4/Rgls/um14oUaif1gomO8YGg=="],
@@ -1756,10 +2018,14 @@
 
     "update-browserslist-db": ["update-browserslist-db@1.2.3", "", { "dependencies": { "escalade": "^3.2.0", "picocolors": "^1.1.1" }, "peerDependencies": { "browserslist": ">= 4.21.0" }, "bin": { "update-browserslist-db": "cli.js" } }, "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w=="],
 
+    "uri-js": ["uri-js@4.4.1", "", { "dependencies": { "punycode": "^2.1.0" } }, "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg=="],
+
     "use-sync-external-store": ["use-sync-external-store@1.6.0", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w=="],
 
     "uuid": ["uuid@13.0.0", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w=="],
 
+    "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
+
     "vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q=="],
 
     "vfile-location": ["vfile-location@5.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile": "^6.0.0" } }, "sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg=="],
@@ -1812,6 +2078,8 @@
 
     "webpack-virtual-modules": ["webpack-virtual-modules@0.6.2", "", {}, "sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ=="],
 
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
     "which-pm-runs": ["which-pm-runs@1.1.0", "", {}, "sha512-n1brCuqClxfFfq/Rb0ICg9giSZqCS+pLtccdag6C2HyufBrh3fBOiy9nb6ggRMvWOVH5GrdJskj5iGTZNxd7SA=="],
 
     "why-is-node-running": ["why-is-node-running@2.3.0", "", { "dependencies": { "siginfo": "^2.0.0", "stackback": "0.0.2" }, "bin": { "why-is-node-running": "cli.js" } }, "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w=="],
@@ -1820,9 +2088,7 @@
 
     "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
 
-    "ws": ["ws@8.19.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg=="],
-
-    "wsl-utils": ["wsl-utils@0.1.0", "", { "dependencies": { "is-wsl": "^3.1.0" } }, "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw=="],
+    "ws": ["ws@8.20.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA=="],
 
     "xxhash-wasm": ["xxhash-wasm@1.1.0", "", {}, "sha512-147y/6YNh+tlp6nd/2pWq38i9h6mz/EuQ6njIrmW8D1BS5nCqs0P6DG+m6zTGnNz5I+uhZ0SHxBs9BsPrwcKDA=="],
 
@@ -1830,7 +2096,7 @@
 
     "yallist": ["yallist@3.1.1", "", {}, "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g=="],
 
-    "yaml": ["yaml@2.8.2", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A=="],
+    "yaml": ["yaml@2.8.3", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg=="],
 
     "yaml-language-server": ["yaml-language-server@1.20.0", "", { "dependencies": { "@vscode/l10n": "^0.0.18", "ajv": "^8.17.1", "ajv-draft-04": "^1.0.0", "prettier": "^3.5.0", "request-light": "^0.5.7", "vscode-json-languageservice": "4.1.8", "vscode-languageserver": "^9.0.0", "vscode-languageserver-textdocument": "^1.0.1", "vscode-languageserver-types": "^3.16.0", "vscode-uri": "^3.0.2", "yaml": "2.7.1" }, "bin": { "yaml-language-server": "bin/yaml-language-server" } }, "sha512-qhjK/bzSRZ6HtTvgeFvjNPJGWdZ0+x5NREV/9XZWFjIGezew2b4r5JPy66IfOhd5OA7KeFwk1JfmEbnTvev0cA=="],
 
@@ -1848,12 +2114,16 @@
 
     "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
 
+    "zod-to-json-schema": ["zod-to-json-schema@3.25.2", "", { "peerDependencies": { "zod": "^3.25.28 || ^4" } }, "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA=="],
+
     "zustand": ["zustand@5.0.12", "", { "peerDependencies": { "@types/react": ">=18.0.0", "immer": ">=9.0.6", "react": ">=18.0.0", "use-sync-external-store": ">=1.2.0" }, "optionalPeers": ["@types/react", "immer", "react", "use-sync-external-store"] }, "sha512-i77ae3aZq4dhMlRhJVCYgMLKuSiZAaUPAct2AksxQ+gOtimhGMdXljRT21P5BNpeT4kXlLIckvkPM029OljD7g=="],
 
     "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
 
     "@astrojs/language-server/@astrojs/compiler": ["@astrojs/compiler@2.13.1", "", {}, "sha512-f3FN83d2G/v32ipNClRKgYv30onQlMZX1vCeZMjPsMMPl1mDpmbl0+N5BYo4S/ofzqJyS5hvwacEo0CCVDn/Qg=="],
 
+    "@astrojs/yaml2ts/yaml": ["yaml@2.8.2", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A=="],
+
     "@babel/code-frame/@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.28.5", "", {}, "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q=="],
 
     "@babel/core/@babel/generator": ["@babel/generator@7.29.1", "", { "dependencies": { "@babel/parser": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" } }, "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw=="],
@@ -1874,6 +2144,10 @@
 
     "@babel/types/@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.28.5", "", {}, "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q=="],
 
+    "@base-ui/react/@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
+
+    "@base-ui/utils/@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
+
     "@electron/get/fs-extra": ["fs-extra@8.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g=="],
 
     "@electron/get/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
@@ -1918,6 +2192,14 @@
 
     "@tanstack/router-utils/@babel/generator": ["@babel/generator@7.29.1", "", { "dependencies": { "@babel/parser": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" } }, "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw=="],
 
+    "@vercel/config/zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+
+    "@vercel/routing-utils/ajv": ["ajv@6.15.0", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw=="],
+
+    "@vercel/routing-utils/path-to-regexp": ["path-to-regexp@6.1.0", "", {}, "sha512-h9DqehX3zZZDCEm+xbfU0ZmwCGFCAAraPJWMXJ4+v32NjZJilVg3k1TcKsRgIb8IQ/izZSaydDc1OhJCZvs2Dw=="],
+
+    "@vitest/browser/ws": ["ws@8.19.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg=="],
+
     "anymatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
 
     "ast-kit/@babel/parser": ["@babel/parser@8.0.0-rc.2", "", { "dependencies": { "@babel/types": "^8.0.0-rc.2" }, "bin": "./bin/babel-parser.js" }, "sha512-29AhEtcq4x8Dp3T72qvUMZHx0OMXCj4Jy/TEReQa+KWLln524Cj1fWb3QFi0l/xSpptQBR6y9RNEXuxpFvwiUQ=="],
@@ -1928,6 +2210,8 @@
 
     "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
 
+    "express/cookie": ["cookie@0.7.2", "", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
+
     "h3/cookie-es": ["cookie-es@1.2.2", "", {}, "sha512-+W7VmiVINB+ywl1HGXJXmrqkOhpKrIiVZV6tQuV54ZyQC7MMuBt81Vc336GMLoHBq5hV/F9eXgt5Mnx0Rha5Fg=="],
 
     "mdast-util-find-and-replace/escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
@@ -1942,6 +2226,8 @@
 
     "rolldown-plugin-dts/@babel/types": ["@babel/types@8.0.0-rc.2", "", { "dependencies": { "@babel/helper-string-parser": "^8.0.0-rc.2", "@babel/helper-validator-identifier": "^8.0.0-rc.2" } }, "sha512-91gAaWRznDwSX4E2tZ1YjBuIfnQVOFDCQ2r0Toby0gu4XEbyF623kXLMA8d4ZbCu+fINcrudkmEcwSUHgDDkNw=="],
 
+    "router/path-to-regexp": ["path-to-regexp@8.4.2", "", {}, "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA=="],
+
     "serialize-error/type-fest": ["type-fest@0.13.1", "", {}, "sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg=="],
 
     "tsx/fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
@@ -2036,6 +2322,8 @@
 
     "@tanstack/router-plugin/chokidar/readdirp": ["readdirp@3.6.0", "", { "dependencies": { "picomatch": "^2.2.1" } }, "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA=="],
 
+    "@vercel/routing-utils/ajv/json-schema-traverse": ["json-schema-traverse@0.4.1", "", {}, "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg=="],
+
     "ast-kit/@babel/parser/@babel/types": ["@babel/types@8.0.0-rc.2", "", { "dependencies": { "@babel/helper-string-parser": "^8.0.0-rc.2", "@babel/helper-validator-identifier": "^8.0.0-rc.2" } }, "sha512-91gAaWRznDwSX4E2tZ1YjBuIfnQVOFDCQ2r0Toby0gu4XEbyF623kXLMA8d4ZbCu+fINcrudkmEcwSUHgDDkNw=="],
 
     "csso/css-tree/mdn-data": ["mdn-data@2.0.28", "", {}, "sha512-aylIc7Z9y4yzHYAJNuESG3hfhC+0Ibp/MAMiaOZgNv4pmEdFyfZhhhny4MNiAfWdBQ1RQ2mfDWmM1x8SvGyp8g=="],
diff --git a/docs/observability.md b/docs/observability.md
index dde10935709..5b98d1163ea 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -69,11 +69,11 @@ npx t3
 ```
 
 ```bash
-bun dev
+node --run dev
 ```
 
 ```bash
-bun dev:desktop
+node --run dev:desktop
 ```
 
 ### Option 2: Run With A Local LGTM Stack
@@ -122,13 +122,13 @@ npx t3
 Monorepo web/server dev:
 
 ```bash
-bun dev
+node --run dev
 ```
 
 Monorepo desktop dev:
 
 ```bash
-bun dev:desktop
+node --run dev:desktop
 ```
 
 Packaged desktop app:
diff --git a/docs/providers/claude.md b/docs/providers/claude.md
new file mode 100644
index 00000000000..bbf72722cf1
--- /dev/null
+++ b/docs/providers/claude.md
@@ -0,0 +1,224 @@
+# Claude
+
+This guide is for people who want to use more than one Claude setup in T3 Code.
+
+Common reasons:
+
+- use separate work and personal Claude accounts
+- try a different Claude Code configuration without disturbing your main setup
+- run Claude through a router such as Claude Code Router
+- use external providers exposed through a Claude-compatible workflow
+
+## I Only Use One Claude Account
+
+Use the default provider.
+
+Log in with Claude Code normally:
+
+```bash
+claude auth login
+```
+
+In T3 Code Settings, your Claude provider can stay like this:
+
+```text
+Display name: Claude
+Binary path: claude
+Claude HOME path: empty
+```
+
+An empty `Claude HOME path` means T3 Code uses your normal home directory.
+
+## I Want Work And Personal Claude Accounts
+
+Use a different Claude home for each account.
+
+Example:
+
+```text
+default home                 work account
+~/.claude_personal_home       personal account
+```
+
+### Set Up The First Account
+
+Log in normally:
+
+```bash
+claude auth login
+```
+
+In T3 Code Settings:
+
+```text
+Display name: Claude Work
+Binary path: claude
+Claude HOME path: empty
+```
+
+### Set Up The Second Account
+
+Log in with a separate home:
+
+```bash
+mkdir -p ~/.claude_personal_home
+HOME=~/.claude_personal_home claude auth login
+```
+
+Then add another Claude provider in T3 Code:
+
+```text
+Display name: Claude Personal
+Binary path: claude
+Claude HOME path: ~/.claude_personal_home
+```
+
+Use the email shown in Settings to confirm each provider is using the intended account. Emails are
+blurred by default; click the blurred email to reveal it.
+
+## Can I Switch Claude Accounts In An Existing Thread?
+
+Usually, no.
+
+T3 Code only offers Claude providers that use the same Claude home for an existing thread. A
+different Claude home is treated as a different Claude environment.
+
+This is different from the recommended Codex setup. Claude Code keeps account and local state across
+multiple files under its home directory, so T3 Code keeps separate Claude homes isolated instead of
+trying to share part of the state.
+
+## I Want To Use OpenRouter
+
+Use this when you want Claude Code to talk to OpenRouter directly, without running a local router.
+This is the simplest external-provider setup.
+
+OpenRouter provides a Claude Code integration through Claude's Anthropic-compatible environment
+variables.
+
+### Configure A Claude OpenRouter Provider
+
+Add or edit a Claude provider in T3 Code Settings:
+
+```text
+Display name: Claude OpenRouter
+Binary path: claude
+Claude HOME path: ~/.claude_openrouter_home
+```
+
+In that provider's Environment variables section, add:
+
+```text
+ANTHROPIC_BASE_URL   https://openrouter.ai/api
+ANTHROPIC_AUTH_TOKEN sk-or-...                Sensitive
+ANTHROPIC_API_KEY                              Empty value
+```
+
+Mark `ANTHROPIC_AUTH_TOKEN` as sensitive. T3 Code stores the value as a server secret and does not
+send it back to the app after saving.
+
+If you want this setup isolated from your normal Claude account, create that home first:
+
+```bash
+mkdir -p ~/.claude_openrouter_home
+```
+
+If you previously used the same Claude home with a normal Anthropic login, run `/logout` in a Claude
+Code session for that home before using OpenRouter. Otherwise Claude Code may keep using cached
+Anthropic credentials instead of the OpenRouter token.
+
+### Pick OpenRouter Models
+
+OpenRouter can route Claude Code's default model roles to OpenRouter model IDs.
+
+Example:
+
+```text
+ANTHROPIC_DEFAULT_OPUS_MODEL    anthropic/claude-opus-4.6
+ANTHROPIC_DEFAULT_SONNET_MODEL  anthropic/claude-sonnet-4.6
+ANTHROPIC_DEFAULT_HAIKU_MODEL   anthropic/claude-haiku-4.5
+CLAUDE_CODE_SUBAGENT_MODEL      anthropic/claude-sonnet-4.6
+```
+
+Add those to the same provider's Environment variables section if you want stable model choices.
+
+### Verify OpenRouter Is Being Used
+
+Open a Claude session and run:
+
+```text
+/status
+```
+
+You should see the Anthropic base URL set to:
+
+```text
+https://openrouter.ai/api
+```
+
+You can also check the OpenRouter activity dashboard for requests from your API key.
+
+### Common OpenRouter Mistakes
+
+- Use `https://openrouter.ai/api`, not `https://openrouter.ai/api/v1`, for Claude Code.
+- Set `ANTHROPIC_AUTH_TOKEN` to your OpenRouter API key.
+- Set `ANTHROPIC_API_KEY` to an empty string so Claude Code does not try to use an Anthropic login.
+- Put these variables on the Claude provider instance, not in global shell startup files.
+
+OpenRouter's setup can change over time. Use its upstream Claude Code guide for the current details:
+<https://openrouter.ai/docs/guides/guides/claude-code-integration>.
+
+## I Want To Use Claude Code Router
+
+Claude Code Router is useful when you want a local routing layer with more control than a direct
+OpenRouter setup.
+
+T3 Code does not need a special Claude Code Router provider. Treat the router as a Claude
+environment.
+
+Use this when you want Claude Code Router to decide which upstream model or provider handles Claude
+requests.
+
+High-level flow:
+
+1. Start Claude Code Router.
+2. Add or configure a Claude provider in T3 Code.
+3. Put the router's required variables on that provider instance.
+
+Configure a Claude provider:
+
+```text
+Display name: Claude Router
+Binary path: claude
+Claude HOME path: ~/.claude_router_home
+```
+
+Then copy the variables that `ccr activate` would export into the provider's Environment variables
+section. Mark tokens and API keys as sensitive.
+
+If you want the router-backed setup to stay separate from your normal Claude account, create and log
+in with a dedicated home first:
+
+```bash
+mkdir -p ~/.claude_router_home
+ccr start
+ccr activate
+HOME=~/.claude_router_home claude auth login
+```
+
+Claude Code Router's setup can change over time. Use its upstream README for the current install and
+configuration steps: <https://github.com/musistudio/claude-code-router>.
+
+## I Want Different Claude Settings, Not A Different Account
+
+Create another Claude provider with the same account if you want a named preset.
+
+Examples:
+
+- "Claude Default"
+- "Claude Router"
+- "Claude Experimental"
+
+If the preset needs different Claude files, give it a different `Claude HOME path`. If it needs
+different API keys, base URLs, or router settings, use Environment variables.
+
+Do not put environment variable assignments in `Launch arguments`.
diff --git a/docs/providers/codex.md b/docs/providers/codex.md
new file mode 100644
index 00000000000..cc9e84e484a
--- /dev/null
+++ b/docs/providers/codex.md
@@ -0,0 +1,140 @@
+# Codex
+
+This guide is for people who want to use more than one Codex account in T3 Code.
+
+Common reasons:
+
+- use a work account for work projects
+- use a personal account for personal projects
+- switch to another account when one account hits limits
+- keep one shared Codex history instead of maintaining two separate Codex setups
+
+## I Only Use One Codex Account
+
+Use the default provider.
+
+In Settings, your Codex provider can stay like this:
+
+```text
+Display name: Codex
+CODEX_HOME path: ~/.codex
+Shadow home path: empty
+```
+
+Log in with Codex normally:
+
+```bash
+codex login
+```
+
+## I Want Work And Personal Codex Accounts
+
+Use one real Codex home and one shadow home.
+
+Recommended setup:
+
+```text
+~/.codex      shared Codex home
+~/.codex_p    second account auth
+```
+
+The idea is:
+
+- both accounts can see the same T3/Codex sessions
+- each account keeps its own login
+- existing threads can continue with either account
+
+### Set Up The First Account
+
+Log in normally:
+
+```bash
+codex login
+```
+
+This is the account used by `~/.codex`.
+
+In T3 Code Settings, name it something obvious:
+
+```text
+Display name: Codex Work
+CODEX_HOME path: ~/.codex
+Shadow home path: empty
+```
+
+### Set Up The Second Account
+
+Log in with a separate Codex home:
+
+```bash
+mkdir -p ~/.codex_p
+CODEX_HOME=~/.codex_p codex login
+```
+
+In T3 Code Settings, add another Codex provider:
+
+```text
+Display name: Codex Personal
+CODEX_HOME path: ~/.codex
+Shadow home path: ~/.codex_p
+```
+
+The important part is that both providers use the same `CODEX_HOME path`, but only the second one
+has a `Shadow home path`.
+
+## Which Account Am I Using?
+
+Open Settings and look at the provider row.
+
+T3 Code shows the authenticated email for providers that report one. Emails are blurred by default;
+click the blurred email to reveal it.
+
+Use display names and accent colors to make accounts easy to tell apart in the model picker.
+
+## I Need A Different API Key Or Endpoint
+
+Use the provider's Environment variables section in Settings.
+
+This is useful when a Codex-compatible setup needs account-specific variables. Add the variables to
+the provider instance that should receive them, and mark API keys or tokens as sensitive. Sensitive
+values are stored as server secrets and are not sent back to the app after saving.
+
+## Can I Switch Accounts In An Existing Thread?
+
+Yes, when both Codex providers share the same `CODEX_HOME path`.
+
+For example:
+
+```text
+Codex Work      CODEX_HOME path: ~/.codex
+Codex Personal  CODEX_HOME path: ~/.codex, Shadow home path: ~/.codex_p
+```
+
+Those two providers are considered compatible for continuation, so the locked model picker can show
+both.
+
+If you add a third Codex provider with a completely different `CODEX_HOME path`, T3 Code treats it
+as a different workspace. It will not be offered for existing threads created under `~/.codex`.
+
+## If Both Accounts Look The Same
+
+If two Codex providers show the same account or the same unexpected model list:
+
+1. Check the email in Settings.
+2. Refresh provider status.
+3. Confirm the second provider has `Shadow home path` set.
+4. Confirm the shadow directory has its own `auth.json`.
+5. If you copied `~/.codex` into the shadow directory, remove everything except `auth.json`.
+
+Example cleanup:
+
+```bash
+find ~/.codex_p -mindepth 1 ! -name auth.json -exec rm -rf {} +
+```
+
+## When To Use A Separate CODEX_HOME
+
+Use a totally separate `CODEX_HOME path` only when you want a separate Codex workspace.
+
+That means separate sessions and less account switching inside old threads. Most dual-account users
+should use the shared-home plus shadow-home setup instead.
diff --git a/docs/release.md b/docs/release.md
index 4aec150f335..df9033218b9 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -1,23 +1,102 @@
 # Release Checklist
 
-This document covers how to run desktop releases from one tag, first without signing, then with signing.
+This document covers the unified release workflow for stable and nightly desktop releases.
 
 ## What the workflow does
 
-- Trigger: push tag matching `v*.*.*`.
+- Workflow: `.github/workflows/release.yml`
+- Triggers:
+  - push tag matching `v*.*.*` for stable releases
+  - scheduled nightly at `09:00 UTC`
+  - manual `workflow_dispatch` for either channel
 - Runs quality gates first: lint, typecheck, test.
-- Builds four artifacts in parallel:
+- Builds four artifacts in parallel for both channels:
   - macOS `arm64` DMG
   - macOS `x64` DMG
   - Linux `x64` AppImage
   - Windows `x64` NSIS installer
 - Publishes one GitHub Release with all produced files.
-  - Versions with a suffix after `X.Y.Z` (for example `1.2.3-alpha.1`) are published as GitHub prereleases.
-  - Only plain `X.Y.Z` releases are marked as the repository's latest release.
-- Includes Electron auto-update metadata (for example `latest*.yml` and `*.blockmap`) in release assets.
-- Publishes the CLI package (`apps/server`, npm package `t3`) with OIDC trusted publishing.
+  - Stable tags with a suffix after `X.Y.Z` (for example `1.2.3-alpha.1`) are published as GitHub prereleases.
+  - Only plain stable `X.Y.Z` releases are marked as the repository's latest release.
+  - Nightly runs are always GitHub prereleases and never marked latest.
+  - Automatically generated release notes are pinned to the previous tag in the same channel, so stable compares to the previous stable tag and nightly compares to the previous nightly tag.
+- Includes Electron auto-update metadata (for example `latest*.yml`, `nightly*.yml`, and `*.blockmap`) in release assets.
+- Publishes the CLI package (`apps/server`, npm package `t3`) with OIDC trusted publishing from the same workflow file:
+  - stable releases publish npm dist-tag `latest`
+  - nightly releases publish npm dist-tag `nightly`
+- Deploys the hosted web app to Vercel only after a release is published:
+  - stable releases are aliased to the `latest` hosted app channel
+  - nightly releases are aliased to the `nightly` hosted app channel
 - Signing is optional and auto-detected per platform from secrets.
 
+## Hosted web app release deployment
+
+The hosted app is intentionally not deployed by Vercel's Git integration. The
+web project disables automatic Git deployments in `apps/web/vercel.ts` via
+`git.deploymentEnabled: false`, and `.github/workflows/release.yml` deploys the
+web app with Vercel CLI after the GitHub Release succeeds.
+
+Required GitHub Actions secrets:
+
+- `VERCEL_TOKEN`
+- `VERCEL_ORG_ID`
+- `VERCEL_PROJECT_ID`
+
+Optional GitHub Actions variables:
+
+- `VERCEL_TEAM_SLUG`: overrides the Vercel CLI scope when the team slug is preferred over the `VERCEL_ORG_ID` secret.
+- `T3CODE_WEB_ROUTER_URL`: defaults to `https://app.t3.codes`.
+- `T3CODE_WEB_LATEST_DOMAIN`: defaults to `latest.app.t3.codes`.
+- `T3CODE_WEB_NIGHTLY_DOMAIN`: defaults to `nightly.app.t3.codes`.
+
+Required Vercel domains:
+
+- `app.t3.codes`: the router domain users open, updated by stable releases.
+- `latest.app.t3.codes`: channel alias updated by stable releases.
+- `nightly.app.t3.codes`: channel alias updated by nightly releases.
+
+The router domain uses `apps/web/vercel.ts` routes. Users opt into a channel by
+visiting `/__t3code/channel?channel=latest` or
+`/__t3code/channel?channel=nightly`; the router stores the
+`t3code_web_channel` cookie and rewrites future requests on `app.t3.codes` to
+the matching channel alias.
+
+The release deploy job rewrites release package versions before upload so the
+hosted app's About panel renders the release version. Stable deploys alias the
+same deployment to both the `latest` channel and the router domain so the router
+rules stay current. Nightly deploys only alias the `nightly` channel. The job
+also passes `VITE_HOSTED_APP_CHANNEL=latest|nightly`, which renders the hosted
+update track selector in the About panel. Changing the selector navigates
+through `/__t3code/channel` on the router domain so the user's channel cookie is
+updated before redirecting to the hosted app root.
+
+One-time Vercel dashboard setup:
+
+1. Confirm the web project root directory remains `apps/web`.
+2. Add the three domains above to the web project.
+3. Disable automatic Git deployments in the dashboard if desired; the committed
+   `vercel.ts` setting is the source-of-truth, but disconnecting Git in the
+   dashboard is also safe.
+4. Run one stable release deployment, or manually alias the current stable
+   deployment, so `app.t3.codes` points at a deployment containing the router
+   rules in `apps/web/vercel.ts`. Future stable releases keep this alias current.
+
+## Nightly builds
+
+- Workflow: `.github/workflows/release.yml`
+- Triggers:
+  - scheduled every day at `09:00 UTC`
+  - manual `workflow_dispatch` with `channel=nightly`
+- Runs the same desktop quality gates and artifact matrix as the tagged release flow.
+- Publishes a GitHub prerelease only:
+  - tag format: `nightly-vX.Y.Z-nightly.YYYYMMDD.<run_number>`
+  - release name includes the short commit SHA
+  - `make_latest` is always `false`
+- Uses the next stable patch version as the nightly base. For example, `0.0.17` produces nightlies on `0.0.18-nightly.*`.
+- Publishes Electron auto-update metadata to the dedicated `nightly` updater channel, so desktop users can opt into that track independently from stable.
+- Publishes the CLI package (`apps/server`, npm package `t3`) to the `nightly` npm dist-tag using the same nightly version.
+- Does not commit version bumps back to `main`.
+
 ## Desktop auto-update notes
 
 - Runtime updater: `electron-updater` in `apps/desktop/src/main.ts`.
@@ -34,15 +113,15 @@ This document covers how to run desktop releases from one tag, first without sig
   - the app forwards it as an `Authorization: Bearer <token>` request header for updater HTTP calls.
 - Required release assets for updater:
   - platform installers (`.exe`, `.dmg`, `.AppImage`, plus macOS `.zip` for Squirrel.Mac update payloads)
-  - `latest*.yml` metadata
+  - channel metadata: `latest*.yml` for stable releases, `nightly*.yml` for nightly releases
   - `*.blockmap` files (used for differential downloads)
 - macOS metadata note:
-  - `electron-updater` reads `latest-mac.yml` for both Intel and Apple Silicon.
-  - The workflow merges the per-arch mac manifests into one `latest-mac.yml` before publishing the GitHub Release.
+  - `electron-updater` reads `latest-mac.yml` on stable and `nightly-mac.yml` on nightly, for both Intel and Apple Silicon.
+  - The workflow merges the per-arch mac manifests into one channel-specific mac manifest before publishing the GitHub Release.
 
 ## 0) npm OIDC trusted publishing setup (CLI)
 
-The workflow publishes the CLI with `bun publish` from `apps/server` after bumping
+The workflow publishes the CLI with `npm publish` from `apps/server` after bumping
 the package version to the release tag version.
 
 Checklist:
@@ -57,7 +136,8 @@ Checklist:
 4. Create release tag `vX.Y.Z` and push; workflow will:
    - set `apps/server/package.json` version to `X.Y.Z`
    - build web + server
-   - run `bun publish --access public`
+   - run `npm publish --access public --tag latest`
+5. Nightly runs from the same workflow file publish with `npm publish --access public --tag nightly`.
 
 ## 1) Dry-run release without signing
 
diff --git a/docs/source-control-providers.md b/docs/source-control-providers.md
new file mode 100644
index 00000000000..c496d5516a6
--- /dev/null
+++ b/docs/source-control-providers.md
@@ -0,0 +1,127 @@
+# Source Control Integrations
+
+T3 Code connects directly to your Git hosting provider so you can create pull requests, review code, and manage repositories without leaving your editor. Work stays in flow—no more jumping between browser tabs and terminal windows.
+
+## Supported Providers
+
+T3 Code works with the platforms your team already uses:
+
+- **GitHub** – Pull requests, repository creation, and clone integration
+- **GitLab** – Merge requests, repository publishing, and hosted clones
+- **Bitbucket** – Pull request workflows (via API token authentication)
+- **Azure DevOps** – Pull request support for Microsoft-hosted repositories
+
+## What You Can Do
+
+### Start Projects from Anywhere
+
+**Clone repositories directly**
+
+- Open the Command Palette (`Cmd/Ctrl + K`) → **Add Project**
+- Choose **GitHub repository**, **GitLab repository**, **Bitbucket repository**, **Azure DevOps repository**, or paste any **Git URL**
+- Enter the repository path (`owner/repo`, `group/project`, `workspace/repository`, or `project/repository`) or a full Git URL, pick a destination, and start coding
+
+**Publish local projects to the cloud**
+
+- Have a local Git repository without a remote?
+- Use the **Publish Repository** action to create a new hosted repository (GitHub, GitLab, Bitbucket, or Azure DevOps), add it as your origin remote, and push—all in one flow
+- Perfect for turning a weekend prototype into a real project
+
+### Manage Code Reviews Without Context Switching
+
+**Create pull requests while you work**
+
+- Push a branch and create a pull request from the Git panel
+- T3 Code can suggest titles and descriptions based on your commits
+- Supports GitHub Pull Requests, GitLab Merge Requests, and Bitbucket Pull Requests
+
+**Stay on top of open reviews**
+
+- See if your current branch already has an open PR/MR
+- Open the review directly in your browser with one click
+- Check out a teammate's branch to review code locally
+
+### Know Your Setup at a Glance
+
+The **Source Control settings** page shows you exactly what's connected:
+
+- ✅ Which providers are authenticated and ready
+- ⚠️ What's missing and how to fix it
+- 👤 Which account is signed in (when available)
+
+Run a quick **Rescan** after setting up a new machine or changing credentials.
+
+## Getting Started
+
+### For GitHub (Recommended for most users)
+
+1. Install the GitHub CLI on the machine running T3 Code:
+   ```bash
+   brew install gh
+   ```
+2. Sign in:
+   ```bash
+   gh auth login
+   ```
+3. Open **Settings → Source Control** in T3 Code and verify GitHub shows as authenticated
+
+That's it—you can now clone, publish, and create pull requests.
+
+### For GitLab
+
+1. Install the GitLab CLI:
+   ```bash
+   brew install glab
+   ```
+2. Authenticate:
+   ```bash
+   glab auth login
+   ```
+3. Check **Settings → Source Control** to confirm the connection
+
+### For Bitbucket
+
+Bitbucket uses API tokens instead of a CLI tool:
+
+1. Create an API token in your Atlassian account with read/write access to pull requests and repositories
+2. Add these environment variables to the environment running T3 Code:
+   ```bash
+   export T3CODE_BITBUCKET_EMAIL="you@example.com"
+   export T3CODE_BITBUCKET_API_TOKEN="your-token"
+   ```
+3. Restart T3 Code and verify the connection in **Source Control settings**
+
+### For Azure DevOps
+
+1. Install Azure CLI:
+   ```bash
+   brew install azure-cli
+   ```
+2. Add the DevOps extension:
+   ```bash
+   az extension add --name azure-devops
+   ```
+3. Sign in:
+   ```bash
+   az login
+   ```
+
+---
+
+## Requirements & Troubleshooting
+
+**Git is required** – T3 Code uses Git for all local operations. Ensure `git` is installed on your server.
+
+**Server-side setup** – Authentication happens on the machine running T3 Code (the server), not your local browser. If you're using a hosted or team instance, your administrator may have already configured providers.
+
+**Common issues:**
+
+- **Provider shows "Not authenticated"** – Run the login command for that provider (e.g., `gh auth login`) in a terminal on the server, then rescan in Settings
+- **Bitbucket not connecting** – Double-check your environment variables are set in the correct shell profile and the server was restarted
+- **Can't push to a remote** – Verify your Git remote URL matches the provider you've authenticated with (SSH vs HTTPS remotes may need different credentials)
+
+**Need more help?** Check your provider's CLI documentation:
+
+- [GitHub CLI](https://cli.github.com/)
+- [GitLab CLI](https://gitlab.com/gitlab-org/cli)
+- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/)
diff --git a/oxlint-plugin-t3code/index.ts b/oxlint-plugin-t3code/index.ts
new file mode 100644
index 00000000000..5189bb4dc80
--- /dev/null
+++ b/oxlint-plugin-t3code/index.ts
@@ -0,0 +1,12 @@
+import { definePlugin } from "@oxlint/plugins";
+
+import noInlineSchemaCompile from "./rules/no-inline-schema-compile.ts";
+
+export default definePlugin({
+  meta: {
+    name: "t3code",
+  },
+  rules: {
+    "no-inline-schema-compile": noInlineSchemaCompile,
+  },
+});
diff --git a/oxlint-plugin-t3code/package.json b/oxlint-plugin-t3code/package.json
new file mode 100644
index 00000000000..2601e70248f
--- /dev/null
+++ b/oxlint-plugin-t3code/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@t3tools/oxlint-plugin-t3code",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@effect/platform-node": "catalog:",
+    "@oxlint/plugins": "^1.63.0",
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@effect/vitest": "catalog:",
+    "@types/bun": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/oxlint-plugin-t3code/rules/no-inline-schema-compile.test.ts b/oxlint-plugin-t3code/rules/no-inline-schema-compile.test.ts
new file mode 100644
index 00000000000..1e95b2608a0
--- /dev/null
+++ b/oxlint-plugin-t3code/rules/no-inline-schema-compile.test.ts
@@ -0,0 +1,83 @@
+import { assert, describe } from "@effect/vitest";
+
+import { createOxlintRuleHarness } from "../test/utils.ts";
+
+const rule = createOxlintRuleHarness("t3code/no-inline-schema-compile");
+
+describe("t3code/no-inline-schema-compile", () => {
+  rule.valid(
+    "allows schema compilers hoisted to module scope",
+    `
+      import { Schema } from "effect";
+
+      const User = Schema.Struct({ name: Schema.String });
+      const decodeUser = Schema.decodeUnknownEffect(User);
+
+      export const parseUser = (input: unknown) => decodeUser(input);
+    `,
+  );
+
+  rule.valid(
+    "allows factory helpers that return a precompiled decoder",
+    `
+      import { Schema } from "effect";
+
+      export const makeParser = <A, I>(schema: Schema.Codec<A, I>) => {
+        const decode = Schema.decodeUnknownEffect(schema);
+        return (input: unknown) => decode(input);
+      };
+    `,
+  );
+
+  rule.valid(
+    "allows schema construction helpers that use encode transformations",
+    `
+      import { Schema } from "effect";
+
+      export const makePrettyJson = <S extends Schema.Top>(schema: S) =>
+        Schema.fromJsonString(schema).pipe(
+          Schema.encode({
+            decode: Schema.String,
+            encode: Schema.String,
+          }),
+        );
+    `,
+  );
+
+  rule.valid(
+    "allows dynamic schema parameters that cannot be hoisted to module scope",
+    `
+      import { Schema } from "effect";
+
+      export const parseWith = <A, I>(schema: Schema.Codec<A, I>, input: unknown) =>
+        Schema.decodeUnknownEffect(schema)(input);
+    `,
+  );
+
+  rule.invalid(
+    "reports schema compilers inside function bodies",
+    `
+      import { Schema } from "effect";
+
+      const User = Schema.Struct({ name: Schema.String });
+
+      export const parseUser = (input: unknown) => Schema.decodeUnknownEffect(User)(input);
+    `,
+    (output) => {
+      assert.match(output, /Hoist Schema\.decodeUnknownEffect/);
+    },
+  );
+
+  rule.invalid(
+    "reports inline schema literals as high confidence findings",
+    `
+      import { Schema } from "effect";
+
+      export const parseUser = (input: unknown) =>
+        Schema.decodeUnknownEffect(Schema.Struct({ name: Schema.String }))(input);
+    `,
+    (output) => {
+      assert.match(output, /inline schema literal and the compiled function/);
+    },
+  );
+});
diff --git a/oxlint-plugin-t3code/rules/no-inline-schema-compile.ts b/oxlint-plugin-t3code/rules/no-inline-schema-compile.ts
new file mode 100644
index 00000000000..f34ded78a56
--- /dev/null
+++ b/oxlint-plugin-t3code/rules/no-inline-schema-compile.ts
@@ -0,0 +1,150 @@
+import { defineRule } from "@oxlint/plugins";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+import { getPropertyName, isIdentifier, unwrapExpression } from "../utils.ts";
+
+// Effect Schema decoder/encoder APIs allocate compiled functions. Keep them
+// outside function bodies so hot paths do not rebuild compilers per call.
+const COMPILER_METHODS = new Set<keyof typeof Schema>([
+  "is",
+  "asserts",
+  "decodeEffect",
+  "decodeExit",
+  "decodeOption",
+  "decodePromise",
+  "decodeSync",
+  "decodeUnknownExit",
+  "decodeUnknownEffect",
+  "decodeUnknownOption",
+  "decodeUnknownPromise",
+  "decodeUnknownSync",
+
+  "encodeExit",
+  "encodeEffect",
+  "encodeOption",
+  "encodePromise",
+  "encodeSync",
+  "encodeUnknownExit",
+  "encodeUnknownEffect",
+  "encodeUnknownOption",
+  "encodeUnknownPromise",
+  "encodeUnknownSync",
+]);
+
+const getSchemaCompilerMethod = (callee: unknown): Option.Option<string> => {
+  const expression = unwrapExpression(callee);
+  if (Option.isNone(expression) || expression.value.type !== "MemberExpression") {
+    return Option.none();
+  }
+
+  const object = unwrapExpression(expression.value.object);
+  if (!isIdentifier(object, "Schema")) return Option.none();
+
+  return Option.filter(getPropertyName(expression.value.property), (method) =>
+    COMPILER_METHODS.has(method as keyof typeof Schema),
+  );
+};
+
+const isStaticSchemaReference = (node: unknown): boolean => {
+  const expression = unwrapExpression(node);
+  if (Option.isNone(expression)) return false;
+
+  if (expression.value.type === "Identifier") {
+    const [firstChar] = expression.value.name;
+    return firstChar !== undefined && firstChar.toUpperCase() === firstChar;
+  }
+
+  return expression.value.type === "MemberExpression";
+};
+
+const isNestedStaticSchemaCall = (node: unknown): boolean => {
+  const expression = unwrapExpression(node);
+  if (Option.isNone(expression) || expression.value.type !== "CallExpression") return false;
+
+  const callee = unwrapExpression(expression.value.callee);
+  if (Option.isNone(callee) || callee.value.type !== "MemberExpression") return false;
+
+  const object = unwrapExpression(callee.value.object);
+  if (!isIdentifier(object, "Schema")) return false;
+
+  const method = getPropertyName(callee.value.property);
+  if (Option.isSome(method) && method.value === "fromJsonString") {
+    const firstArg = expression.value.arguments[0];
+    return isStaticSchemaReference(firstArg) || isNestedStaticSchemaCall(firstArg);
+  }
+
+  return true;
+};
+
+const isImmediatelyInvoked = (node: unknown): boolean => {
+  const expression = unwrapExpression(node);
+  if (Option.isNone(expression)) return false;
+
+  const parent =
+    "parent" in expression.value ? unwrapExpression(expression.value.parent) : Option.none();
+  return (
+    Option.isSome(parent) &&
+    parent.value.type === "CallExpression" &&
+    unwrapExpression(parent.value.callee).pipe(
+      Option.exists((callee) => callee === expression.value),
+    )
+  );
+};
+
+const messageHigh = (method: string) =>
+  `Hoist Schema.${method}(...) to module scope: both the inline schema literal and the compiled function are rebuilt on every call. Move the compiled function to a module-level const.`;
+
+const messageMedium = (method: string) =>
+  `Hoist Schema.${method}(...) to module scope: the compiled function is rebuilt on every call. Move it to a module-level const.`;
+
+export default defineRule({
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow Schema decoder/encoder compiler calls inside function bodies; hoist them to module scope.",
+    },
+  },
+  createOnce(context) {
+    let functionDepth = 0;
+
+    const resetFunctionDepth = () => {
+      functionDepth = 0;
+    };
+
+    const enterFunction = () => {
+      functionDepth++;
+    };
+
+    const exitFunction = () => {
+      functionDepth--;
+    };
+
+    return {
+      before: resetFunctionDepth,
+      FunctionDeclaration: enterFunction,
+      "FunctionDeclaration:exit": exitFunction,
+      FunctionExpression: enterFunction,
+      "FunctionExpression:exit": exitFunction,
+      ArrowFunctionExpression: enterFunction,
+      "ArrowFunctionExpression:exit": exitFunction,
+      CallExpression(node) {
+        if (functionDepth === 0) return;
+
+        const method = getSchemaCompilerMethod(node.callee);
+        if (Option.isNone(method)) return;
+        if (!isImmediatelyInvoked(node)) return;
+
+        const firstArg = node.arguments[0];
+        const high = firstArg && isNestedStaticSchemaCall(firstArg);
+        if (!high && !isStaticSchemaReference(firstArg)) return;
+
+        context.report({
+          node: node.callee,
+          message: high ? messageHigh(method.value) : messageMedium(method.value),
+        });
+      },
+    };
+  },
+});
diff --git a/oxlint-plugin-t3code/test/utils.ts b/oxlint-plugin-t3code/test/utils.ts
new file mode 100644
index 00000000000..f44dd3a5d16
--- /dev/null
+++ b/oxlint-plugin-t3code/test/utils.ts
@@ -0,0 +1,152 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+class OxlintFixtureFailure extends Data.TaggedError("OxlintFixtureFailure")<{
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}> {
+  static readonly is = (u: unknown): u is OxlintFixtureFailure =>
+    Predicate.isTagged(u, "OxlintFixtureFailure");
+}
+
+class OxlintFixtureExpectedFailure extends Data.TaggedError("OxlintFixtureExpectedFailure")<{
+  readonly ruleName: string;
+}> {
+  override get message() {
+    return `Expected oxlint to report a failure for rule ${this.ruleName}, but it passed.`;
+  }
+}
+
+const encodeOxlintConfig = Schema.encodeEffect(Schema.UnknownFromJsonString);
+
+interface RuleHarness {
+  readonly run: (
+    source: string,
+  ) => Effect.Effect<
+    string,
+    OxlintFixtureFailure | PlatformError.PlatformError | Schema.SchemaError,
+    NodeServices.NodeServices
+  >;
+  readonly runAndExpectFailure: (
+    source: string,
+  ) => Effect.Effect<
+    string,
+    OxlintFixtureExpectedFailure | PlatformError.PlatformError | Schema.SchemaError,
+    NodeServices.NodeServices
+  >;
+  readonly valid: (name: string, source: string) => void;
+  readonly invalid: (name: string, source: string, assertion?: (output: string) => void) => void;
+}
+
+const collectStreamAsString = <E>(stream: Stream.Stream<Uint8Array, E>): Effect.Effect<string, E> =>
+  stream.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => "",
+      (acc, chunk) => acc + chunk,
+    ),
+  );
+
+const spawnAndCollectOutput = Effect.fnUntraced(function* (command: ChildProcess.Command) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner.spawn(command);
+
+  const [stdout, stderr, exitCode] = yield* Effect.all(
+    [
+      collectStreamAsString(child.stdout),
+      collectStreamAsString(child.stderr),
+      child.exitCode.pipe(Effect.map(Number)),
+    ],
+    { concurrency: "unbounded" },
+  );
+
+  return { exitCode, stdout, stderr };
+}, Effect.scoped);
+
+export const createOxlintRuleHarness = (ruleName: string): RuleHarness => {
+  const [pluginName, shortRuleName] = ruleName.split("/");
+  const diagnosticRuleName =
+    pluginName && shortRuleName ? `${pluginName}\\(${shortRuleName}\\)` : ruleName;
+  const test = it.layer(NodeServices.layer);
+
+  const run: RuleHarness["run"] = Effect.fnUntraced(function* (source: string) {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const fixtureDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-oxlint-" });
+    const configPath = path.join(fixtureDir, ".oxlintrc.json");
+    const sourcePath = path.join(fixtureDir, "fixture.ts");
+    const repoRoot = path.join(import.meta.dirname, "..", "..");
+    const oxlintBin = path.join(repoRoot, "node_modules", ".bin", "oxlint");
+    const pluginPath = path.join(repoRoot, "oxlint-plugin-t3code", "index.ts");
+
+    yield* fs.writeFileString(
+      configPath,
+      yield* encodeOxlintConfig({
+        jsPlugins: [{ name: "t3code", specifier: pluginPath }],
+        rules: { [ruleName]: "error" },
+      }),
+    );
+    yield* fs.writeFileString(sourcePath, source);
+
+    const output = yield* spawnAndCollectOutput(
+      ChildProcess.make(oxlintBin, ["--config", configPath, sourcePath], { cwd: repoRoot }),
+    );
+
+    if (output.exitCode !== 0) {
+      return yield* new OxlintFixtureFailure({
+        exitCode: output.exitCode,
+        stdout: output.stdout,
+        stderr: output.stderr,
+      });
+    }
+
+    return `${output.stdout}${output.stderr}`;
+  }, Effect.scoped);
+
+  const runAndExpectFailure: RuleHarness["runAndExpectFailure"] = (source) =>
+    run(source).pipe(
+      Effect.matchEffect({
+        onFailure: (error) =>
+          OxlintFixtureFailure.is(error)
+            ? Effect.succeed(
+                `oxlint fixture failed with exit code ${error.exitCode}\n${error.stdout}\n${error.stderr}`,
+              )
+            : Effect.fail(error),
+        onSuccess: () => Effect.fail(new OxlintFixtureExpectedFailure({ ruleName })),
+      }),
+    );
+
+  return {
+    run,
+    runAndExpectFailure,
+    valid(name, source) {
+      test(name, (it) => {
+        it.effect("passes", () => run(source));
+      });
+    },
+    invalid(name, source, assertion) {
+      test(name, (it) => {
+        it.effect("reports the rule diagnostic", () =>
+          runAndExpectFailure(source).pipe(
+            Effect.tap((output) =>
+              Effect.sync(() => {
+                assert.match(output, new RegExp(diagnosticRuleName));
+                assertion?.(output);
+              }),
+            ),
+          ),
+        );
+      });
+    },
+  };
+};
diff --git a/oxlint-plugin-t3code/tsconfig.json b/oxlint-plugin-t3code/tsconfig.json
new file mode 100644
index 00000000000..266b534fef0
--- /dev/null
+++ b/oxlint-plugin-t3code/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "types": ["bun", "node"],
+    "lib": ["ESNext", "esnext.disposable"]
+  },
+  "include": ["**/*.ts"]
+}
diff --git a/oxlint-plugin-t3code/utils.ts b/oxlint-plugin-t3code/utils.ts
new file mode 100644
index 00000000000..3943cd74dec
--- /dev/null
+++ b/oxlint-plugin-t3code/utils.ts
@@ -0,0 +1,58 @@
+import type { ESTree } from "@oxlint/plugins";
+import * as Option from "effect/Option";
+
+type ExpressionWrapper =
+  | ESTree.ChainExpression
+  | ESTree.ParenthesizedExpression
+  | ESTree.TSNonNullExpression
+  | ESTree.TSAsExpression
+  | ESTree.TSTypeAssertion;
+
+type AstNode = ESTree.Node;
+
+const asAstNode = (node: unknown): Option.Option<AstNode> =>
+  typeof node === "object" && node !== null && "type" in node && typeof node.type === "string"
+    ? Option.some(node as AstNode)
+    : Option.none();
+
+const isExpressionWrapper = (node: AstNode): node is ExpressionWrapper =>
+  node.type === "ChainExpression" ||
+  node.type === "ParenthesizedExpression" ||
+  node.type === "TSNonNullExpression" ||
+  node.type === "TSAsExpression" ||
+  node.type === "TSTypeAssertion";
+
+export function unwrapExpression(node: unknown): Option.Option<AstNode> {
+  let current = asAstNode(node);
+
+  while (Option.isSome(current) && isExpressionWrapper(current.value)) {
+    current = asAstNode(current.value.expression);
+  }
+
+  return current;
+}
+
+export function getPropertyName(node: unknown): Option.Option<string> {
+  return Option.flatMap(asAstNode(node), (expression) => {
+    if (expression.type === "Identifier" && typeof expression.name === "string") {
+      return Option.some(expression.name);
+    }
+    if (expression.type === "PrivateIdentifier" && typeof expression.name === "string") {
+      return Option.some(expression.name);
+    }
+    if (expression.type === "Literal" && typeof expression.value === "string") {
+      return Option.some(expression.value);
+    }
+    return Option.none();
+  });
+}
+
+export function isIdentifier(node: Option.Option<AstNode>, name?: string): boolean {
+  if (Option.isNone(node)) return false;
+  const expression = node.value;
+  return (
+    expression.type === "Identifier" &&
+    typeof expression.name === "string" &&
+    (name === undefined || expression.name === name)
+  );
+}
diff --git a/package.json b/package.json
index 97b30e6d4dc..a1aa5d0b1cd 100644
--- a/package.json
+++ b/package.json
@@ -4,19 +4,22 @@
   "workspaces": {
     "packages": [
       "apps/*",
+      "oxlint-plugin-t3code",
       "packages/*",
       "scripts"
     ],
     "catalog": {
-      "effect": "4.0.0-beta.45",
-      "@effect/atom-react": "4.0.0-beta.45",
-      "@effect/platform-bun": "4.0.0-beta.45",
-      "@effect/platform-node": "4.0.0-beta.45",
-      "@effect/platform-node-shared": "4.0.0-beta.45",
-      "@effect/sql-sqlite-bun": "4.0.0-beta.45",
-      "@effect/vitest": "4.0.0-beta.45",
+      "effect": "4.0.0-beta.59",
+      "@effect/atom-react": "4.0.0-beta.59",
+      "@effect/openapi-generator": "4.0.0-beta.59",
+      "@effect/platform-bun": "4.0.0-beta.59",
+      "@effect/platform-node": "4.0.0-beta.59",
+      "@effect/platform-node-shared": "4.0.0-beta.59",
+      "@effect/sql-sqlite-bun": "4.0.0-beta.59",
+      "@effect/vitest": "4.0.0-beta.59",
       "@effect/language-service": "0.84.2",
-      "@types/bun": "^1.3.9",
+      "@pierre/diffs": "1.1.20",
+      "@types/bun": "^1.3.11",
       "@types/node": "^24.10.13",
       "tsdown": "^0.20.3",
       "typescript": "^5.7.3",
@@ -25,6 +28,7 @@
   },
   "type": "module",
   "scripts": {
+    "prepare": "effect-language-service patch",
     "dev": "node scripts/dev-runner.ts dev",
     "dev:server": "node scripts/dev-runner.ts dev:server",
     "dev:web": "node scripts/dev-runner.ts dev:web",
@@ -33,7 +37,7 @@
     "start": "turbo run start --filter=t3",
     "start:desktop": "turbo run start --filter=@t3tools/desktop",
     "start:marketing": "turbo run preview --filter=@t3tools/marketing",
-    "start:mock-update-server": "bun run scripts/mock-update-server.ts",
+    "start:mock-update-server": "node scripts/mock-update-server.ts",
     "build": "turbo run build",
     "build:marketing": "turbo run build --filter=@t3tools/marketing",
     "build:desktop": "turbo run build --filter=@t3tools/desktop --filter=t3",
@@ -49,16 +53,21 @@
     "dist:desktop:dmg:arm64": "node scripts/build-desktop-artifact.ts --platform mac --target dmg --arch arm64",
     "dist:desktop:dmg:x64": "node scripts/build-desktop-artifact.ts --platform mac --target dmg --arch x64",
     "dist:desktop:linux": "node scripts/build-desktop-artifact.ts --platform linux --target AppImage --arch x64",
-    "dist:desktop:win": "node scripts/build-desktop-artifact.ts --platform win --target nsis --arch x64",
+    "dist:desktop:win": "node scripts/build-desktop-artifact.ts --platform win --target nsis",
+    "dist:desktop:win:arm64": "node scripts/build-desktop-artifact.ts --platform win --target nsis --arch arm64",
+    "dist:desktop:win:x64": "node scripts/build-desktop-artifact.ts --platform win --target nsis --arch x64",
     "release:smoke": "node scripts/release-smoke.ts",
     "clean": "rm -rf node_modules apps/*/node_modules packages/*/node_modules apps/*/dist apps/*/dist-electron packages/*/dist .turbo apps/*/.turbo packages/*/.turbo",
     "sync:vscode-icons": "node scripts/sync-vscode-icons.mjs"
   },
   "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@oxlint/plugins": "^1.63.0",
     "@types/node": "catalog:",
     "oxfmt": "^0.40.0",
-    "oxlint": "^1.55.0",
+    "oxlint": "^1.63.0",
     "turbo": "^2.3.3",
+    "typescript": "catalog:",
     "vitest": "catalog:"
   },
   "overrides": {
@@ -72,16 +81,20 @@
     "vite": "^8.0.0"
   },
   "engines": {
-    "bun": "^1.3.9",
+    "bun": "^1.3.11",
     "node": "^24.13.1"
   },
-  "packageManager": "bun@1.3.9",
+  "packageManager": "bun@1.3.11",
   "msw": {
     "workerDirectory": [
       "apps/web/public"
     ]
   },
+  "patchedDependencies": {
+    "effect@4.0.0-beta.59": "patches/effect@4.0.0-beta.59.patch"
+  },
   "trustedDependencies": [
-    "node-pty"
+    "node-pty",
+    "electron"
   ]
 }
diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json
index bfe2d7828eb..58bc576a24f 100644
--- a/packages/client-runtime/package.json
+++ b/packages/client-runtime/package.json
@@ -1,6 +1,5 @@
 {
   "name": "@t3tools/client-runtime",
-  "version": "0.0.0-alpha.1",
   "private": true,
   "type": "module",
   "exports": {
@@ -10,12 +9,13 @@
     }
   },
   "scripts": {
-    "prepare": "effect-language-service patch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
-    "@t3tools/contracts": "workspace:*"
+    "@t3tools/contracts": "workspace:*",
+    "@t3tools/shared": "workspace:*",
+    "effect": "catalog:"
   },
   "devDependencies": {
     "@effect/language-service": "catalog:",
diff --git a/packages/client-runtime/src/advertisedEndpoint.test.ts b/packages/client-runtime/src/advertisedEndpoint.test.ts
new file mode 100644
index 00000000000..1cbfde87bd3
--- /dev/null
+++ b/packages/client-runtime/src/advertisedEndpoint.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  classifyHostedHttpsCompatibility,
+  createAdvertisedEndpoint,
+  deriveWsBaseUrl,
+  normalizeHttpBaseUrl,
+} from "./advertisedEndpoint.ts";
+
+const coreProvider = {
+  id: "desktop-core",
+  label: "Desktop",
+  kind: "core",
+  isAddon: false,
+} as const;
+
+describe("advertised endpoint helpers", () => {
+  it("normalizes HTTP and WebSocket base URLs", () => {
+    expect(normalizeHttpBaseUrl("https://example.com/path?x=1#hash")).toBe("https://example.com/");
+    expect(normalizeHttpBaseUrl("wss://example.com/socket")).toBe("https://example.com/");
+    expect(deriveWsBaseUrl("https://example.com/api")).toBe("wss://example.com/");
+    expect(deriveWsBaseUrl("http://127.0.0.1:3773")).toBe("ws://127.0.0.1:3773/");
+  });
+
+  it("marks HTTP endpoints as blocked from hosted HTTPS apps", () => {
+    expect(classifyHostedHttpsCompatibility("http://192.168.1.44:3773")).toBe(
+      "mixed-content-blocked",
+    );
+    expect(classifyHostedHttpsCompatibility("https://desktop.example.com", "compatible")).toBe(
+      "compatible",
+    );
+  });
+
+  it("creates provider-neutral endpoint records", () => {
+    expect(
+      createAdvertisedEndpoint({
+        id: "lan:http://192.168.1.44:3773",
+        label: "LAN",
+        provider: coreProvider,
+        httpBaseUrl: "http://192.168.1.44:3773",
+        reachability: "lan",
+        source: "desktop-core",
+        isDefault: true,
+      }),
+    ).toEqual({
+      id: "lan:http://192.168.1.44:3773",
+      label: "LAN",
+      provider: coreProvider,
+      httpBaseUrl: "http://192.168.1.44:3773/",
+      wsBaseUrl: "ws://192.168.1.44:3773/",
+      reachability: "lan",
+      compatibility: {
+        hostedHttpsApp: "mixed-content-blocked",
+        desktopApp: "compatible",
+      },
+      source: "desktop-core",
+      status: "available",
+      isDefault: true,
+    });
+  });
+});
diff --git a/packages/client-runtime/src/advertisedEndpoint.ts b/packages/client-runtime/src/advertisedEndpoint.ts
new file mode 100644
index 00000000000..da7d766fa80
--- /dev/null
+++ b/packages/client-runtime/src/advertisedEndpoint.ts
@@ -0,0 +1 @@
+export * from "@t3tools/shared/advertisedEndpoint";
diff --git a/packages/client-runtime/src/index.ts b/packages/client-runtime/src/index.ts
index 5dd6b9afa57..cb7472dff51 100644
--- a/packages/client-runtime/src/index.ts
+++ b/packages/client-runtime/src/index.ts
@@ -1,2 +1,4 @@
-export * from "./knownEnvironment";
-export * from "./scoped";
+export * from "./advertisedEndpoint.ts";
+export * from "./knownEnvironment.ts";
+export * from "./scoped.ts";
+export * from "./sourceControlDiscoveryState.ts";
diff --git a/packages/client-runtime/src/knownEnvironment.test.ts b/packages/client-runtime/src/knownEnvironment.test.ts
index dca56c1e6da..a40161e9b04 100644
--- a/packages/client-runtime/src/knownEnvironment.test.ts
+++ b/packages/client-runtime/src/knownEnvironment.test.ts
@@ -1,7 +1,7 @@
 import { EnvironmentId, ProjectId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 
-import { createKnownEnvironment, getKnownEnvironmentHttpBaseUrl } from "./knownEnvironment";
+import { createKnownEnvironment, getKnownEnvironmentHttpBaseUrl } from "./knownEnvironment.ts";
 import {
   parseScopedProjectKey,
   parseScopedThreadKey,
@@ -10,7 +10,7 @@ import {
   scopedThreadKey,
   scopeProjectRef,
   scopeThreadRef,
-} from "./scoped";
+} from "./scoped.ts";
 
 describe("known environment bootstrap helpers", () => {
   it("creates known environments from explicit server base urls", () => {
diff --git a/packages/client-runtime/src/sourceControlDiscoveryState.test.ts b/packages/client-runtime/src/sourceControlDiscoveryState.test.ts
new file mode 100644
index 00000000000..9a988be00a5
--- /dev/null
+++ b/packages/client-runtime/src/sourceControlDiscoveryState.test.ts
@@ -0,0 +1,107 @@
+import { assert, beforeEach, it } from "vitest";
+import type { SourceControlDiscoveryResult } from "@t3tools/contracts";
+import { AtomRegistry } from "effect/unstable/reactivity";
+
+import {
+  EMPTY_SOURCE_CONTROL_DISCOVERY_STATE,
+  createSourceControlDiscoveryManager,
+} from "./sourceControlDiscoveryState.ts";
+
+const EMPTY_RESULT: SourceControlDiscoveryResult = {
+  versionControlSystems: [],
+  sourceControlProviders: [],
+};
+
+function unresolvedDiscovery() {
+  throw new Error("Discovery resolver was not initialized.");
+}
+
+let registry = AtomRegistry.make();
+
+beforeEach(() => {
+  registry.dispose();
+  registry = AtomRegistry.make();
+});
+
+it("stores refreshed discovery data in an atom snapshot", async () => {
+  const manager = createSourceControlDiscoveryManager({
+    getRegistry: () => registry,
+    getClient: () => ({
+      discoverSourceControl: async () => EMPTY_RESULT,
+    }),
+  });
+
+  assert.deepStrictEqual(manager.getSnapshot({ key: null }), EMPTY_SOURCE_CONTROL_DISCOVERY_STATE);
+
+  const result = await manager.refresh({ key: "primary" });
+
+  assert.strictEqual(result, EMPTY_RESULT);
+  assert.deepStrictEqual(manager.getSnapshot({ key: "primary" }), {
+    data: EMPTY_RESULT,
+    error: null,
+    isPending: false,
+  });
+});
+
+it("deduplicates in-flight discovery refreshes by target key", async () => {
+  let resolveDiscovery: (result: SourceControlDiscoveryResult) => void = unresolvedDiscovery;
+  let calls = 0;
+  const manager = createSourceControlDiscoveryManager({
+    getRegistry: () => registry,
+    getClient: () => ({
+      discoverSourceControl: () => {
+        calls += 1;
+        return new Promise<SourceControlDiscoveryResult>((resolve) => {
+          resolveDiscovery = resolve;
+        });
+      },
+    }),
+  });
+
+  const first = manager.refresh({ key: "primary" });
+  const second = manager.refresh({ key: "primary" });
+
+  assert.strictEqual(first, second);
+  assert.strictEqual(calls, 1);
+  assert.deepStrictEqual(manager.getSnapshot({ key: "primary" }), {
+    data: null,
+    error: null,
+    isPending: true,
+  });
+
+  resolveDiscovery(EMPTY_RESULT);
+  await first;
+
+  assert.deepStrictEqual(manager.getSnapshot({ key: "primary" }), {
+    data: EMPTY_RESULT,
+    error: null,
+    isPending: false,
+  });
+});
+
+it("keeps the previous snapshot when refresh fails", async () => {
+  let shouldFail = false;
+  const manager = createSourceControlDiscoveryManager({
+    getRegistry: () => registry,
+    getClient: () => ({
+      discoverSourceControl: async () => {
+        if (shouldFail) {
+          throw new Error("probe failed");
+        }
+        return EMPTY_RESULT;
+      },
+    }),
+  });
+
+  await manager.refresh({ key: "primary" });
+  shouldFail = true;
+
+  const result = await manager.refresh({ key: "primary" });
+
+  assert.strictEqual(result, EMPTY_RESULT);
+  assert.deepStrictEqual(manager.getSnapshot({ key: "primary" }), {
+    data: EMPTY_RESULT,
+    error: "probe failed",
+    isPending: false,
+  });
+});
diff --git a/packages/client-runtime/src/sourceControlDiscoveryState.ts b/packages/client-runtime/src/sourceControlDiscoveryState.ts
new file mode 100644
index 00000000000..b18d6103b80
--- /dev/null
+++ b/packages/client-runtime/src/sourceControlDiscoveryState.ts
@@ -0,0 +1,206 @@
+import type { SourceControlDiscoveryResult } from "@t3tools/contracts";
+import { Atom, type AtomRegistry } from "effect/unstable/reactivity";
+
+/* --- Types ---------------------------------------------------------- */
+
+export interface SourceControlDiscoveryState {
+  readonly data: SourceControlDiscoveryResult | null;
+  readonly error: string | null;
+  readonly isPending: boolean;
+}
+
+export interface SourceControlDiscoveryTarget {
+  readonly key: string | null;
+}
+
+export interface SourceControlDiscoveryClient {
+  readonly discoverSourceControl: () => Promise<SourceControlDiscoveryResult>;
+}
+
+/* --- Constants ------------------------------------------------------ */
+
+export const EMPTY_SOURCE_CONTROL_DISCOVERY_STATE = Object.freeze<SourceControlDiscoveryState>({
+  data: null,
+  error: null,
+  isPending: false,
+});
+
+const INITIAL_SOURCE_CONTROL_DISCOVERY_STATE = Object.freeze<SourceControlDiscoveryState>({
+  data: null,
+  error: null,
+  isPending: true,
+});
+
+/* --- Atoms ---------------------------------------------------------- */
+
+const knownSourceControlDiscoveryKeys = new Set<string>();
+
+export const sourceControlDiscoveryStateAtom = Atom.family((key: string) => {
+  knownSourceControlDiscoveryKeys.add(key);
+  return Atom.make(INITIAL_SOURCE_CONTROL_DISCOVERY_STATE).pipe(
+    Atom.keepAlive,
+    Atom.withLabel(`source-control-discovery:${key}`),
+  );
+});
+
+export const EMPTY_SOURCE_CONTROL_DISCOVERY_ATOM = Atom.make(
+  EMPTY_SOURCE_CONTROL_DISCOVERY_STATE,
+).pipe(Atom.keepAlive, Atom.withLabel("source-control-discovery:null"));
+
+/* --- Helpers -------------------------------------------------------- */
+
+export function getSourceControlDiscoveryTargetKey(
+  target: SourceControlDiscoveryTarget,
+): string | null {
+  const key = target.key?.trim();
+  return key && key.length > 0 ? key : null;
+}
+
+/* --- Refresh manager ------------------------------------------------ */
+
+export interface SourceControlDiscoveryManagerConfig {
+  /**
+   * Get the atom registry used to read/write source-control discovery snapshots.
+   */
+  readonly getRegistry: () => AtomRegistry.AtomRegistry;
+  /**
+   * Resolve the runtime client for a discovery target key.
+   *
+   * Web currently uses a single `"primary"` target, but keeping this keyed
+   * lets mobile or future multi-environment clients provide separate discovery
+   * clients without changing the state primitive.
+   */
+  readonly getClient: (key: string) => SourceControlDiscoveryClient | null;
+}
+
+export function createSourceControlDiscoveryManager(config: SourceControlDiscoveryManagerConfig) {
+  const refreshInFlight = new Map<string, Promise<SourceControlDiscoveryResult | null>>();
+
+  /* -- Atom helpers -------------------------------------------------- */
+
+  function setState(targetKey: string, nextState: SourceControlDiscoveryState): void {
+    config.getRegistry().set(sourceControlDiscoveryStateAtom(targetKey), nextState);
+  }
+
+  function markPending(targetKey: string): void {
+    const current = config.getRegistry().get(sourceControlDiscoveryStateAtom(targetKey));
+    const next: SourceControlDiscoveryState =
+      current.data === null
+        ? INITIAL_SOURCE_CONTROL_DISCOVERY_STATE
+        : {
+            data: current.data,
+            error: null,
+            isPending: true,
+          };
+
+    if (
+      current.data === next.data &&
+      current.error === next.error &&
+      current.isPending === next.isPending
+    ) {
+      return;
+    }
+
+    setState(targetKey, next);
+  }
+
+  function setData(targetKey: string, data: SourceControlDiscoveryResult): void {
+    setState(targetKey, {
+      data,
+      error: null,
+      isPending: false,
+    });
+  }
+
+  function setError(targetKey: string, error: unknown): void {
+    const current = config.getRegistry().get(sourceControlDiscoveryStateAtom(targetKey));
+    setState(targetKey, {
+      data: current.data,
+      error: error instanceof Error ? error.message : "Failed to discover source control tools.",
+      isPending: false,
+    });
+  }
+
+  /* -- Public API ---------------------------------------------------- */
+
+  /**
+   * Trigger a one-shot source-control discovery RPC for a target.
+   *
+   * Calls are deduplicated while a refresh for the same target key is in
+   * flight. On failure, the previous successful snapshot is kept in `data`
+   * and the error message is stored separately so UI can keep rendering stale
+   * discovery results while showing the failure.
+   *
+   * @param target The logical runtime target to refresh.
+   * @param client Optional pre-resolved client, useful in tests.
+   */
+  function refresh(
+    target: SourceControlDiscoveryTarget,
+    client?: SourceControlDiscoveryClient,
+  ): Promise<SourceControlDiscoveryResult | null> {
+    const targetKey = getSourceControlDiscoveryTargetKey(target);
+    if (targetKey === null) {
+      return Promise.resolve(null);
+    }
+
+    const existing = refreshInFlight.get(targetKey);
+    if (existing) {
+      return existing;
+    }
+
+    const resolvedClient = client ?? config.getClient(targetKey);
+    if (!resolvedClient) {
+      const error = new Error("Source control discovery client is unavailable.");
+      setError(targetKey, error);
+      return Promise.resolve(getSnapshot(target).data);
+    }
+
+    markPending(targetKey);
+    const promise = resolvedClient.discoverSourceControl().then(
+      (result) => {
+        setData(targetKey, result);
+        return result;
+      },
+      (error: unknown) => {
+        setError(targetKey, error);
+        return getSnapshot(target).data;
+      },
+    );
+    const tracked = promise.finally(() => refreshInFlight.delete(targetKey));
+    refreshInFlight.set(targetKey, tracked);
+    return tracked;
+  }
+
+  /**
+   * Read the current atom snapshot for `target`.
+   *
+   * Invalid targets return the inert empty state rather than creating a new
+   * family atom entry.
+   */
+  function getSnapshot(target: SourceControlDiscoveryTarget): SourceControlDiscoveryState {
+    const targetKey = getSourceControlDiscoveryTargetKey(target);
+    if (targetKey === null) {
+      return EMPTY_SOURCE_CONTROL_DISCOVERY_STATE;
+    }
+
+    return config.getRegistry().get(sourceControlDiscoveryStateAtom(targetKey));
+  }
+
+  /**
+   * Clear in-flight refresh tracking and reset every known discovery atom.
+   * Primarily used by tests and runtime teardown.
+   */
+  function reset(): void {
+    refreshInFlight.clear();
+    for (const key of knownSourceControlDiscoveryKeys) {
+      setState(key, INITIAL_SOURCE_CONTROL_DISCOVERY_STATE);
+    }
+    knownSourceControlDiscoveryKeys.clear();
+  }
+
+  return {
+    refresh,
+    getSnapshot,
+    reset,
+  };
+}
diff --git a/packages/client-runtime/tsconfig.json b/packages/client-runtime/tsconfig.json
index 564a5990051..73a306f847a 100644
--- a/packages/client-runtime/tsconfig.json
+++ b/packages/client-runtime/tsconfig.json
@@ -1,4 +1,5 @@
 {
   "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
   "include": ["src"]
 }
diff --git a/packages/contracts/package.json b/packages/contracts/package.json
index 63ce74a1ab0..5b2ad2cc412 100644
--- a/packages/contracts/package.json
+++ b/packages/contracts/package.json
@@ -1,30 +1,22 @@
 {
   "name": "@t3tools/contracts",
-  "version": "0.0.17",
+  "version": "0.0.24",
   "private": true,
   "files": [
     "dist"
   ],
   "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./src/index.ts",
   "exports": {
-    "./settings": {
-      "types": "./src/settings.ts",
-      "import": "./src/settings.ts",
-      "require": "./src/settings.ts"
-    },
     ".": {
       "types": "./src/index.ts",
-      "import": "./src/index.ts",
-      "require": "./dist/index.cjs"
+      "import": "./src/index.ts"
+    },
+    "./settings": {
+      "types": "./src/settings.ts",
+      "import": "./src/settings.ts"
     }
   },
   "scripts": {
-    "dev": "tsdown src/index.ts --format esm,cjs --dts --watch --clean",
-    "build": "tsdown src/index.ts --format esm,cjs --dts --clean",
-    "prepare": "effect-language-service patch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
@@ -34,7 +26,6 @@
   "devDependencies": {
     "@effect/language-service": "catalog:",
     "@effect/vitest": "catalog:",
-    "tsdown": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"
   }
diff --git a/packages/contracts/src/auth.ts b/packages/contracts/src/auth.ts
index 73327a45af1..8439d12b069 100644
--- a/packages/contracts/src/auth.ts
+++ b/packages/contracts/src/auth.ts
@@ -1,6 +1,6 @@
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 
-import { AuthSessionId, TrimmedNonEmptyString } from "./baseSchemas";
+import { AuthSessionId, TrimmedNonEmptyString } from "./baseSchemas.ts";
 
 /**
  * Declares the server's overall authentication posture.
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts
index 10ee6851be2..614ea5131fb 100644
--- a/packages/contracts/src/baseSchemas.ts
+++ b/packages/contracts/src/baseSchemas.ts
@@ -1,10 +1,21 @@
-import { Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
 
-export const TrimmedString = Schema.Trim;
+export const TrimmedString = Schema.String.pipe(
+  Schema.decodeTo(
+    Schema.String,
+    SchemaTransformation.transformOrFail({
+      decode: (value) => Effect.succeed(value.trim()),
+      encode: (value) => Effect.succeed(value.trim()),
+    }),
+  ),
+);
 export const TrimmedNonEmptyString = TrimmedString.check(Schema.isNonEmpty());
 
 export const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
 export const PositiveInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }));
 
 export const IsoDateTime = Schema.String;
 export type IsoDateTime = typeof IsoDateTime.Type;
diff --git a/packages/contracts/src/desktopBootstrap.ts b/packages/contracts/src/desktopBootstrap.ts
new file mode 100644
index 00000000000..c23dbbb3960
--- /dev/null
+++ b/packages/contracts/src/desktopBootstrap.ts
@@ -0,0 +1,18 @@
+import * as Schema from "effect/Schema";
+
+import { PortSchema } from "./baseSchemas.ts";
+
+export const DesktopBackendBootstrap = Schema.Struct({
+  mode: Schema.Literal("desktop"),
+  noBrowser: Schema.Boolean,
+  port: PortSchema,
+  t3Home: Schema.String,
+  host: Schema.String,
+  desktopBootstrapToken: Schema.String,
+  tailscaleServeEnabled: Schema.Boolean,
+  tailscaleServePort: PortSchema,
+  otlpTracesUrl: Schema.optional(Schema.String),
+  otlpMetricsUrl: Schema.optional(Schema.String),
+});
+
+export type DesktopBackendBootstrap = typeof DesktopBackendBootstrap.Type;
diff --git a/packages/contracts/src/editor.ts b/packages/contracts/src/editor.ts
index 2ffdf4c6dbe..c80ef481613 100644
--- a/packages/contracts/src/editor.ts
+++ b/packages/contracts/src/editor.ts
@@ -1,5 +1,5 @@
-import { Schema } from "effect";
-import { TrimmedNonEmptyString } from "./baseSchemas";
+import * as Schema from "effect/Schema";
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
 
 export const EditorLaunchStyle = Schema.Literals(["direct-path", "goto", "line-column"]);
 export type EditorLaunchStyle = typeof EditorLaunchStyle.Type;
@@ -8,12 +8,14 @@ type EditorDefinition = {
   readonly id: string;
   readonly label: string;
   readonly commands: readonly [string, ...string[]] | null;
+  readonly baseArgs?: readonly string[];
   readonly launchStyle: EditorLaunchStyle;
 };
 
 export const EDITORS = [
   { id: "cursor", label: "Cursor", commands: ["cursor"], launchStyle: "goto" },
   { id: "trae", label: "Trae", commands: ["trae"], launchStyle: "goto" },
+  { id: "kiro", label: "Kiro", commands: ["kiro"], baseArgs: ["ide"], launchStyle: "goto" },
   { id: "vscode", label: "VS Code", commands: ["code"], launchStyle: "goto" },
   {
     id: "vscode-insiders",
@@ -25,19 +27,33 @@ export const EDITORS = [
   { id: "zed", label: "Zed", commands: ["zed", "zeditor"], launchStyle: "direct-path" },
   { id: "antigravity", label: "Antigravity", commands: ["agy"], launchStyle: "goto" },
   { id: "idea", label: "IntelliJ IDEA", commands: ["idea"], launchStyle: "line-column" },
+  { id: "aqua", label: "Aqua", commands: ["aqua"], launchStyle: "line-column" },
+  { id: "clion", label: "CLion", commands: ["clion"], launchStyle: "line-column" },
+  { id: "datagrip", label: "DataGrip", commands: ["datagrip"], launchStyle: "line-column" },
+  { id: "dataspell", label: "DataSpell", commands: ["dataspell"], launchStyle: "line-column" },
+  { id: "goland", label: "GoLand", commands: ["goland"], launchStyle: "line-column" },
+  { id: "phpstorm", label: "PhpStorm", commands: ["phpstorm"], launchStyle: "line-column" },
+  { id: "pycharm", label: "PyCharm", commands: ["pycharm"], launchStyle: "line-column" },
+  { id: "rider", label: "Rider", commands: ["rider"], launchStyle: "line-column" },
+  { id: "rubymine", label: "RubyMine", commands: ["rubymine"], launchStyle: "line-column" },
+  { id: "rustrover", label: "RustRover", commands: ["rustrover"], launchStyle: "line-column" },
+  { id: "webstorm", label: "WebStorm", commands: ["webstorm"], launchStyle: "line-column" },
   { id: "file-manager", label: "File Manager", commands: null, launchStyle: "direct-path" },
 ] as const satisfies ReadonlyArray<EditorDefinition>;
 
 export const EditorId = Schema.Literals(EDITORS.map((e) => e.id));
 export type EditorId = typeof EditorId.Type;
 
-export const OpenInEditorInput = Schema.Struct({
+export const LaunchEditorInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
   editor: EditorId,
 });
-export type OpenInEditorInput = typeof OpenInEditorInput.Type;
+export type LaunchEditorInput = typeof LaunchEditorInput.Type;
 
-export class OpenError extends Schema.TaggedErrorClass<OpenError>()("OpenError", {
-  message: Schema.String,
-  cause: Schema.optional(Schema.Defect),
-}) {}
+export class ExternalLauncherError extends Schema.TaggedErrorClass<ExternalLauncherError>()(
+  "ExternalLauncherError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {}
diff --git a/packages/contracts/src/environment.ts b/packages/contracts/src/environment.ts
index bc3b5459cd9..fb52972d5aa 100644
--- a/packages/contracts/src/environment.ts
+++ b/packages/contracts/src/environment.ts
@@ -1,6 +1,7 @@
-import { Effect, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
 
-import { EnvironmentId, ProjectId, ThreadId, TrimmedNonEmptyString } from "./baseSchemas";
+import { EnvironmentId, ProjectId, ThreadId, TrimmedNonEmptyString } from "./baseSchemas.ts";
 
 export const ExecutionEnvironmentPlatformOs = Schema.Literals([
   "darwin",
@@ -51,6 +52,7 @@ export type RepositoryIdentityLocator = typeof RepositoryIdentityLocator.Type;
 export const RepositoryIdentity = Schema.Struct({
   canonicalKey: TrimmedNonEmptyString,
   locator: RepositoryIdentityLocator,
+  rootPath: Schema.optionalKey(TrimmedNonEmptyString),
   displayName: Schema.optionalKey(TrimmedNonEmptyString),
   provider: Schema.optionalKey(TrimmedNonEmptyString),
   owner: Schema.optionalKey(TrimmedNonEmptyString),
diff --git a/packages/contracts/src/filesystem.ts b/packages/contracts/src/filesystem.ts
new file mode 100644
index 00000000000..37da5863429
--- /dev/null
+++ b/packages/contracts/src/filesystem.ts
@@ -0,0 +1,30 @@
+import * as Schema from "effect/Schema";
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
+
+const FILESYSTEM_PATH_MAX_LENGTH = 512;
+
+export const FilesystemBrowseInput = Schema.Struct({
+  partialPath: TrimmedNonEmptyString.check(Schema.isMaxLength(FILESYSTEM_PATH_MAX_LENGTH)),
+  cwd: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(FILESYSTEM_PATH_MAX_LENGTH))),
+});
+export type FilesystemBrowseInput = typeof FilesystemBrowseInput.Type;
+
+export const FilesystemBrowseEntry = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  fullPath: TrimmedNonEmptyString,
+});
+export type FilesystemBrowseEntry = typeof FilesystemBrowseEntry.Type;
+
+export const FilesystemBrowseResult = Schema.Struct({
+  parentPath: TrimmedNonEmptyString,
+  entries: Schema.Array(FilesystemBrowseEntry),
+});
+export type FilesystemBrowseResult = typeof FilesystemBrowseResult.Type;
+
+export class FilesystemBrowseError extends Schema.TaggedErrorClass<FilesystemBrowseError>()(
+  "FilesystemBrowseError",
+  {
+    message: TrimmedNonEmptyString,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {}
diff --git a/packages/contracts/src/git.test.ts b/packages/contracts/src/git.test.ts
index d5b2d7dfd89..33eb0a8339f 100644
--- a/packages/contracts/src/git.test.ts
+++ b/packages/contracts/src/git.test.ts
@@ -1,15 +1,15 @@
 import { describe, expect, it } from "vitest";
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 
 import {
-  GitCreateWorktreeInput,
+  VcsCreateWorktreeInput,
   GitPreparePullRequestThreadInput,
   GitRunStackedActionResult,
   GitRunStackedActionInput,
   GitResolvePullRequestResult,
-} from "./git";
+} from "./git.ts";
 
-const decodeCreateWorktreeInput = Schema.decodeUnknownSync(GitCreateWorktreeInput);
+const decodeCreateWorktreeInput = Schema.decodeUnknownSync(VcsCreateWorktreeInput);
 const decodePreparePullRequestThreadInput = Schema.decodeUnknownSync(
   GitPreparePullRequestThreadInput,
 );
@@ -17,16 +17,16 @@ const decodeRunStackedActionInput = Schema.decodeUnknownSync(GitRunStackedAction
 const decodeRunStackedActionResult = Schema.decodeUnknownSync(GitRunStackedActionResult);
 const decodeResolvePullRequestResult = Schema.decodeUnknownSync(GitResolvePullRequestResult);
 
-describe("GitCreateWorktreeInput", () => {
-  it("accepts omitted newBranch for existing-branch worktrees", () => {
+describe("VcsCreateWorktreeInput", () => {
+  it("accepts omitted newRefName for existing-refName worktrees", () => {
     const parsed = decodeCreateWorktreeInput({
       cwd: "/repo",
-      branch: "feature/existing",
+      refName: "feature/existing",
       path: "/tmp/worktree",
     });
 
-    expect(parsed.newBranch).toBeUndefined();
-    expect(parsed.branch).toBe("feature/existing");
+    expect(parsed.newRefName).toBeUndefined();
+    expect(parsed.refName).toBe("feature/existing");
   });
 });
 
diff --git a/packages/contracts/src/git.ts b/packages/contracts/src/git.ts
index 345208acf9e..0b155bf49b7 100644
--- a/packages/contracts/src/git.ts
+++ b/packages/contracts/src/git.ts
@@ -1,5 +1,7 @@
-import { Schema } from "effect";
-import { NonNegativeInt, PositiveInt, ThreadId, TrimmedNonEmptyString } from "./baseSchemas";
+import * as Schema from "effect/Schema";
+import { NonNegativeInt, PositiveInt, ThreadId, TrimmedNonEmptyString } from "./baseSchemas.ts";
+import { SourceControlProviderError, SourceControlProviderInfo } from "./sourceControl.ts";
+import { VcsDriverKind } from "./vcs.ts";
 
 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
 const GIT_LIST_BRANCHES_MAX_LIMIT = 200;
@@ -40,18 +42,10 @@ const GitPushStepStatus = Schema.Literals([
 ]);
 const GitBranchStepStatus = Schema.Literals(["created", "skipped_not_requested"]);
 const GitPrStepStatus = Schema.Literals(["created", "opened_existing", "skipped_not_requested"]);
-const GitStatusPrState = Schema.Literals(["open", "closed", "merged"]);
+const VcsStatusChangeRequestState = Schema.Literals(["open", "closed", "merged"]);
 const GitPullRequestReference = TrimmedNonEmptyStringSchema;
 const GitPullRequestState = Schema.Literals(["open", "closed", "merged"]);
 const GitPreparePullRequestThreadMode = Schema.Literals(["local", "worktree"]);
-export const GitHostingProviderKind = Schema.Literals(["github", "gitlab", "unknown"]);
-export type GitHostingProviderKind = typeof GitHostingProviderKind.Type;
-export const GitHostingProvider = Schema.Struct({
-  kind: GitHostingProviderKind,
-  name: TrimmedNonEmptyStringSchema,
-  baseUrl: Schema.String,
-});
-export type GitHostingProvider = typeof GitHostingProvider.Type;
 export const GitRunStackedActionToastRunAction = Schema.Struct({
   kind: GitStackedAction,
 });
@@ -79,7 +73,7 @@ const GitRunStackedActionToast = Schema.Struct({
 });
 export type GitRunStackedActionToast = typeof GitRunStackedActionToast.Type;
 
-export const GitBranch = Schema.Struct({
+export const VcsRef = Schema.Struct({
   name: TrimmedNonEmptyStringSchema,
   isRemote: Schema.optional(Schema.Boolean),
   remoteName: Schema.optional(TrimmedNonEmptyStringSchema),
@@ -87,11 +81,11 @@ export const GitBranch = Schema.Struct({
   isDefault: Schema.Boolean,
   worktreePath: TrimmedNonEmptyStringSchema.pipe(Schema.NullOr),
 });
-export type GitBranch = typeof GitBranch.Type;
+export type VcsRef = typeof VcsRef.Type;
 
-const GitWorktree = Schema.Struct({
+const VcsWorktree = Schema.Struct({
   path: TrimmedNonEmptyStringSchema,
-  branch: TrimmedNonEmptyStringSchema,
+  refName: TrimmedNonEmptyStringSchema,
 });
 const GitResolvedPullRequest = Schema.Struct({
   number: PositiveInt,
@@ -105,15 +99,15 @@ export type GitResolvedPullRequest = typeof GitResolvedPullRequest.Type;
 
 // RPC Inputs
 
-export const GitStatusInput = Schema.Struct({
+export const VcsStatusInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
 });
-export type GitStatusInput = typeof GitStatusInput.Type;
+export type VcsStatusInput = typeof VcsStatusInput.Type;
 
-export const GitPullInput = Schema.Struct({
+export const VcsPullInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
 });
-export type GitPullInput = typeof GitPullInput.Type;
+export type VcsPullInput = typeof VcsPullInput.Type;
 
 export const GitRunStackedActionInput = Schema.Struct({
   actionId: TrimmedNonEmptyStringSchema,
@@ -127,7 +121,7 @@ export const GitRunStackedActionInput = Schema.Struct({
 });
 export type GitRunStackedActionInput = typeof GitRunStackedActionInput.Type;
 
-export const GitListBranchesInput = Schema.Struct({
+export const VcsListRefsInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
   query: Schema.optional(TrimmedNonEmptyStringSchema.check(Schema.isMaxLength(256))),
   cursor: Schema.optional(NonNegativeInt),
@@ -135,15 +129,15 @@ export const GitListBranchesInput = Schema.Struct({
     PositiveInt.check(Schema.isLessThanOrEqualTo(GIT_LIST_BRANCHES_MAX_LIMIT)),
   ),
 });
-export type GitListBranchesInput = typeof GitListBranchesInput.Type;
+export type VcsListRefsInput = typeof VcsListRefsInput.Type;
 
-export const GitCreateWorktreeInput = Schema.Struct({
+export const VcsCreateWorktreeInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
-  branch: TrimmedNonEmptyStringSchema,
-  newBranch: Schema.optional(TrimmedNonEmptyStringSchema),
+  refName: TrimmedNonEmptyStringSchema,
+  newRefName: Schema.optional(TrimmedNonEmptyStringSchema),
   path: Schema.NullOr(TrimmedNonEmptyStringSchema),
 });
-export type GitCreateWorktreeInput = typeof GitCreateWorktreeInput.Type;
+export type VcsCreateWorktreeInput = typeof VcsCreateWorktreeInput.Type;
 
 export const GitPullRequestRefInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
@@ -159,53 +153,54 @@ export const GitPreparePullRequestThreadInput = Schema.Struct({
 });
 export type GitPreparePullRequestThreadInput = typeof GitPreparePullRequestThreadInput.Type;
 
-export const GitRemoveWorktreeInput = Schema.Struct({
+export const VcsRemoveWorktreeInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
   path: TrimmedNonEmptyStringSchema,
   force: Schema.optional(Schema.Boolean),
 });
-export type GitRemoveWorktreeInput = typeof GitRemoveWorktreeInput.Type;
+export type VcsRemoveWorktreeInput = typeof VcsRemoveWorktreeInput.Type;
 
-export const GitCreateBranchInput = Schema.Struct({
+export const VcsCreateRefInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
-  branch: TrimmedNonEmptyStringSchema,
-  checkout: Schema.optional(Schema.Boolean),
+  refName: TrimmedNonEmptyStringSchema,
+  switchRef: Schema.optional(Schema.Boolean),
 });
-export type GitCreateBranchInput = typeof GitCreateBranchInput.Type;
+export type VcsCreateRefInput = typeof VcsCreateRefInput.Type;
 
-export const GitCreateBranchResult = Schema.Struct({
-  branch: TrimmedNonEmptyStringSchema,
+export const VcsCreateRefResult = Schema.Struct({
+  refName: TrimmedNonEmptyStringSchema,
 });
-export type GitCreateBranchResult = typeof GitCreateBranchResult.Type;
+export type VcsCreateRefResult = typeof VcsCreateRefResult.Type;
 
-export const GitCheckoutInput = Schema.Struct({
+export const VcsSwitchRefInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
-  branch: TrimmedNonEmptyStringSchema,
+  refName: TrimmedNonEmptyStringSchema,
 });
-export type GitCheckoutInput = typeof GitCheckoutInput.Type;
+export type VcsSwitchRefInput = typeof VcsSwitchRefInput.Type;
 
-export const GitInitInput = Schema.Struct({
+export const VcsInitInput = Schema.Struct({
   cwd: TrimmedNonEmptyStringSchema,
+  kind: Schema.optional(VcsDriverKind),
 });
-export type GitInitInput = typeof GitInitInput.Type;
+export type VcsInitInput = typeof VcsInitInput.Type;
 
 // RPC Results
 
-const GitStatusPr = Schema.Struct({
+const VcsStatusChangeRequest = Schema.Struct({
   number: PositiveInt,
   title: TrimmedNonEmptyStringSchema,
   url: Schema.String,
-  baseBranch: TrimmedNonEmptyStringSchema,
-  headBranch: TrimmedNonEmptyStringSchema,
-  state: GitStatusPrState,
+  baseRef: TrimmedNonEmptyStringSchema,
+  headRef: TrimmedNonEmptyStringSchema,
+  state: VcsStatusChangeRequestState,
 });
 
-const GitStatusLocalShape = {
+const VcsStatusLocalShape = {
   isRepo: Schema.Boolean,
-  hostingProvider: Schema.optional(GitHostingProvider),
-  hasOriginRemote: Schema.Boolean,
-  isDefaultBranch: Schema.Boolean,
-  branch: Schema.NullOr(TrimmedNonEmptyStringSchema),
+  sourceControlProvider: Schema.optional(SourceControlProviderInfo),
+  hasPrimaryRemote: Schema.Boolean,
+  isDefaultRef: Schema.Boolean,
+  refName: Schema.NullOr(TrimmedNonEmptyStringSchema),
   hasWorkingTreeChanges: Schema.Boolean,
   workingTree: Schema.Struct({
     files: Schema.Array(
@@ -220,52 +215,53 @@ const GitStatusLocalShape = {
   }),
 };
 
-const GitStatusRemoteShape = {
+const VcsStatusRemoteShape = {
   hasUpstream: Schema.Boolean,
   aheadCount: NonNegativeInt,
   behindCount: NonNegativeInt,
-  pr: Schema.NullOr(GitStatusPr),
+  aheadOfDefaultCount: Schema.optional(NonNegativeInt),
+  pr: Schema.NullOr(VcsStatusChangeRequest),
 };
 
-export const GitStatusLocalResult = Schema.Struct(GitStatusLocalShape);
-export type GitStatusLocalResult = typeof GitStatusLocalResult.Type;
+export const VcsStatusLocalResult = Schema.Struct(VcsStatusLocalShape);
+export type VcsStatusLocalResult = typeof VcsStatusLocalResult.Type;
 
-export const GitStatusRemoteResult = Schema.Struct(GitStatusRemoteShape);
-export type GitStatusRemoteResult = typeof GitStatusRemoteResult.Type;
+export const VcsStatusRemoteResult = Schema.Struct(VcsStatusRemoteShape);
+export type VcsStatusRemoteResult = typeof VcsStatusRemoteResult.Type;
 
-export const GitStatusResult = Schema.Struct({
-  ...GitStatusLocalShape,
-  ...GitStatusRemoteShape,
+export const VcsStatusResult = Schema.Struct({
+  ...VcsStatusLocalShape,
+  ...VcsStatusRemoteShape,
 });
-export type GitStatusResult = typeof GitStatusResult.Type;
+export type VcsStatusResult = typeof VcsStatusResult.Type;
 
-export const GitStatusStreamEvent = Schema.Union([
+export const VcsStatusStreamEvent = Schema.Union([
   Schema.TaggedStruct("snapshot", {
-    local: GitStatusLocalResult,
-    remote: Schema.NullOr(GitStatusRemoteResult),
+    local: VcsStatusLocalResult,
+    remote: Schema.NullOr(VcsStatusRemoteResult),
   }),
   Schema.TaggedStruct("localUpdated", {
-    local: GitStatusLocalResult,
+    local: VcsStatusLocalResult,
   }),
   Schema.TaggedStruct("remoteUpdated", {
-    remote: Schema.NullOr(GitStatusRemoteResult),
+    remote: Schema.NullOr(VcsStatusRemoteResult),
   }),
 ]);
-export type GitStatusStreamEvent = typeof GitStatusStreamEvent.Type;
+export type VcsStatusStreamEvent = typeof VcsStatusStreamEvent.Type;
 
-export const GitListBranchesResult = Schema.Struct({
-  branches: Schema.Array(GitBranch),
+export const VcsListRefsResult = Schema.Struct({
+  refs: Schema.Array(VcsRef),
   isRepo: Schema.Boolean,
-  hasOriginRemote: Schema.Boolean,
+  hasPrimaryRemote: Schema.Boolean,
   nextCursor: NonNegativeInt.pipe(Schema.NullOr),
   totalCount: NonNegativeInt,
 });
-export type GitListBranchesResult = typeof GitListBranchesResult.Type;
+export type VcsListRefsResult = typeof VcsListRefsResult.Type;
 
-export const GitCreateWorktreeResult = Schema.Struct({
-  worktree: GitWorktree,
+export const VcsCreateWorktreeResult = Schema.Struct({
+  worktree: VcsWorktree,
 });
-export type GitCreateWorktreeResult = typeof GitCreateWorktreeResult.Type;
+export type VcsCreateWorktreeResult = typeof VcsCreateWorktreeResult.Type;
 
 export const GitResolvePullRequestResult = Schema.Struct({
   pullRequest: GitResolvedPullRequest,
@@ -279,10 +275,10 @@ export const GitPreparePullRequestThreadResult = Schema.Struct({
 });
 export type GitPreparePullRequestThreadResult = typeof GitPreparePullRequestThreadResult.Type;
 
-export const GitCheckoutResult = Schema.Struct({
-  branch: Schema.NullOr(TrimmedNonEmptyStringSchema),
+export const VcsSwitchRefResult = Schema.Struct({
+  refName: Schema.NullOr(TrimmedNonEmptyStringSchema),
 });
-export type GitCheckoutResult = typeof GitCheckoutResult.Type;
+export type VcsSwitchRefResult = typeof VcsSwitchRefResult.Type;
 
 export const GitRunStackedActionResult = Schema.Struct({
   action: GitStackedAction,
@@ -313,12 +309,12 @@ export const GitRunStackedActionResult = Schema.Struct({
 });
 export type GitRunStackedActionResult = typeof GitRunStackedActionResult.Type;
 
-export const GitPullResult = Schema.Struct({
+export const VcsPullResult = Schema.Struct({
   status: Schema.Literals(["pulled", "skipped_up_to_date"]),
-  branch: TrimmedNonEmptyStringSchema,
-  upstreamBranch: TrimmedNonEmptyStringSchema.pipe(Schema.NullOr),
+  refName: TrimmedNonEmptyStringSchema,
+  upstreamRef: TrimmedNonEmptyStringSchema.pipe(Schema.NullOr),
 });
-export type GitPullResult = typeof GitPullResult.Type;
+export type VcsPullResult = typeof VcsPullResult.Type;
 
 // RPC / domain errors
 export class GitCommandError extends Schema.TaggedErrorClass<GitCommandError>()("GitCommandError", {
@@ -333,16 +329,6 @@ export class GitCommandError extends Schema.TaggedErrorClass<GitCommandError>()(
   }
 }
 
-export class GitHubCliError extends Schema.TaggedErrorClass<GitHubCliError>()("GitHubCliError", {
-  operation: Schema.String,
-  detail: Schema.String,
-  cause: Schema.optional(Schema.Defect),
-}) {
-  override get message(): string {
-    return `GitHub CLI failed in ${this.operation}: ${this.detail}`;
-  }
-}
-
 export class TextGenerationError extends Schema.TaggedErrorClass<TextGenerationError>()(
   "TextGenerationError",
   {
@@ -369,7 +355,7 @@ export class GitManagerError extends Schema.TaggedErrorClass<GitManagerError>()(
 export const GitManagerServiceError = Schema.Union([
   GitManagerError,
   GitCommandError,
-  GitHubCliError,
+  SourceControlProviderError,
   TextGenerationError,
 ]);
 export type GitManagerServiceError = typeof GitManagerServiceError.Type;
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index f12cf80d57a..8402c82647d 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,16 +1,22 @@
-export * from "./baseSchemas";
-export * from "./auth";
-export * from "./environment";
-export * from "./ipc";
-export * from "./terminal";
-export * from "./provider";
-export * from "./providerRuntime";
-export * from "./model";
-export * from "./keybindings";
-export * from "./server";
-export * from "./settings";
-export * from "./git";
-export * from "./orchestration";
-export * from "./editor";
-export * from "./project";
-export * from "./rpc";
+export * from "./baseSchemas.ts";
+export * from "./auth.ts";
+export * from "./environment.ts";
+export * from "./desktopBootstrap.ts";
+export * from "./remoteAccess.ts";
+export * from "./ipc.ts";
+export * from "./terminal.ts";
+export * from "./provider.ts";
+export * from "./providerInstance.ts";
+export * from "./providerRuntime.ts";
+export * from "./model.ts";
+export * from "./keybindings.ts";
+export * from "./server.ts";
+export * from "./settings.ts";
+export * from "./git.ts";
+export * from "./vcs.ts";
+export * from "./sourceControl.ts";
+export * from "./orchestration.ts";
+export * from "./editor.ts";
+export * from "./project.ts";
+export * from "./filesystem.ts";
+export * from "./rpc.ts";
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 31e86938053..c0515aa9b26 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -1,34 +1,44 @@
 import type {
-  GitCheckoutInput,
-  GitCheckoutResult,
-  GitCreateBranchInput,
+  VcsSwitchRefInput,
+  VcsSwitchRefResult,
+  VcsCreateRefInput,
   GitPreparePullRequestThreadInput,
   GitPreparePullRequestThreadResult,
   GitPullRequestRefInput,
-  GitCreateWorktreeInput,
-  GitCreateWorktreeResult,
-  GitInitInput,
-  GitListBranchesInput,
-  GitListBranchesResult,
-  GitPullInput,
-  GitPullResult,
-  GitRemoveWorktreeInput,
+  VcsCreateWorktreeInput,
+  VcsCreateWorktreeResult,
+  VcsInitInput,
+  VcsListRefsInput,
+  VcsListRefsResult,
+  VcsPullInput,
+  VcsPullResult,
+  VcsRemoveWorktreeInput,
   GitResolvePullRequestResult,
-  GitStatusInput,
-  GitStatusResult,
-  GitCreateBranchResult,
-} from "./git";
+  VcsStatusInput,
+  VcsStatusResult,
+  VcsCreateRefResult,
+} from "./git.ts";
+import type { FilesystemBrowseInput, FilesystemBrowseResult } from "./filesystem.ts";
 import type {
   ProjectSearchEntriesInput,
   ProjectSearchEntriesResult,
   ProjectWriteFileInput,
   ProjectWriteFileResult,
-} from "./project";
+} from "./project.ts";
+import type { ProviderInstanceId } from "./providerInstance.ts";
 import type {
   ServerConfig,
+  ServerProcessDiagnosticsResult,
+  ServerProcessResourceHistoryInput,
+  ServerProcessResourceHistoryResult,
+  ServerProviderUpdateInput,
   ServerProviderUpdatedPayload,
+  ServerRemoveKeybindingResult,
+  ServerSignalProcessInput,
+  ServerSignalProcessResult,
+  ServerTraceDiagnosticsResult,
   ServerUpsertKeybindingResult,
-} from "./server";
+} from "./server.ts";
 import type {
   TerminalClearInput,
   TerminalCloseInput,
@@ -38,28 +48,64 @@ import type {
   TerminalRestartInput,
   TerminalSessionSnapshot,
   TerminalWriteInput,
-} from "./terminal";
-import type { ServerUpsertKeybindingInput } from "./server";
+} from "./terminal.ts";
+import type { ServerRemoveKeybindingInput, ServerUpsertKeybindingInput } from "./server.ts";
+import * as Schema from "effect/Schema";
 import type {
   ClientOrchestrationCommand,
   OrchestrationGetFullThreadDiffInput,
   OrchestrationGetFullThreadDiffResult,
   OrchestrationGetTurnDiffInput,
   OrchestrationGetTurnDiffResult,
-  OrchestrationEvent,
-  OrchestrationReadModel,
-} from "./orchestration";
-import type { EnvironmentId } from "./baseSchemas";
-import { EditorId } from "./editor";
-import { ClientSettings, ServerSettings, ServerSettingsPatch } from "./settings";
+  OrchestrationShellSnapshot,
+  OrchestrationShellStreamItem,
+  OrchestrationSubscribeThreadInput,
+  OrchestrationThreadStreamItem,
+} from "./orchestration.ts";
+import { EnvironmentId } from "./baseSchemas.ts";
+import { AuthBearerBootstrapResult, AuthSessionState, AuthWebSocketTokenResult } from "./auth.ts";
+import { AdvertisedEndpoint } from "./remoteAccess.ts";
+import { EditorId } from "./editor.ts";
+import { ExecutionEnvironmentDescriptor } from "./environment.ts";
+import type { ClientSettings, ServerSettings, ServerSettingsPatch } from "./settings.ts";
+import type {
+  SourceControlCloneRepositoryInput,
+  SourceControlCloneRepositoryResult,
+  SourceControlDiscoveryResult,
+  SourceControlPublishRepositoryInput,
+  SourceControlPublishRepositoryResult,
+  SourceControlRepositoryInfo,
+  SourceControlRepositoryLookupInput,
+} from "./sourceControl.ts";
 
 export interface ContextMenuItem<T extends string = string> {
   id: T;
   label: string;
   destructive?: boolean;
   disabled?: boolean;
+  children?: readonly ContextMenuItem<T>[];
+}
+
+export interface ContextMenuItemSchemaType {
+  readonly id: string;
+  readonly label: string;
+  readonly destructive?: boolean;
+  readonly disabled?: boolean;
+  readonly children?: readonly ContextMenuItemSchemaType[];
 }
 
+export const ContextMenuItemSchema: Schema.Codec<ContextMenuItemSchemaType> = Schema.Struct({
+  id: Schema.String,
+  label: Schema.String,
+  destructive: Schema.optionalKey(Schema.Boolean),
+  disabled: Schema.optionalKey(Schema.Boolean),
+  children: Schema.optionalKey(
+    Schema.Array(
+      Schema.suspend((): Schema.Codec<ContextMenuItemSchemaType> => ContextMenuItemSchema),
+    ),
+  ),
+});
+
 export type DesktopUpdateStatus =
   | "disabled"
   | "idle"
@@ -72,6 +118,35 @@ export type DesktopUpdateStatus =
 
 export type DesktopRuntimeArch = "arm64" | "x64" | "other";
 export type DesktopTheme = "light" | "dark" | "system";
+export type DesktopUpdateChannel = "latest" | "nightly";
+export type DesktopAppStageLabel = "Alpha" | "Dev" | "Nightly";
+
+export const DesktopUpdateStatusSchema = Schema.Literals([
+  "disabled",
+  "idle",
+  "checking",
+  "up-to-date",
+  "available",
+  "downloading",
+  "downloaded",
+  "error",
+]);
+export const DesktopRuntimeArchSchema = Schema.Literals(["arm64", "x64", "other"]);
+export const DesktopThemeSchema = Schema.Literals(["light", "dark", "system"]);
+export const DesktopUpdateChannelSchema = Schema.Literals(["latest", "nightly"]);
+export const DesktopAppStageLabelSchema = Schema.Literals(["Alpha", "Dev", "Nightly"]);
+
+export interface DesktopAppBranding {
+  baseName: string;
+  stageLabel: DesktopAppStageLabel;
+  displayName: string;
+}
+
+export const DesktopAppBrandingSchema = Schema.Struct({
+  baseName: Schema.String,
+  stageLabel: DesktopAppStageLabelSchema,
+  displayName: Schema.String,
+});
 
 export interface DesktopRuntimeInfo {
   hostArch: DesktopRuntimeArch;
@@ -79,9 +154,16 @@ export interface DesktopRuntimeInfo {
   runningUnderArm64Translation: boolean;
 }
 
+export const DesktopRuntimeInfoSchema = Schema.Struct({
+  hostArch: DesktopRuntimeArchSchema,
+  appArch: DesktopRuntimeArchSchema,
+  runningUnderArm64Translation: Schema.Boolean,
+});
+
 export interface DesktopUpdateState {
   enabled: boolean;
   status: DesktopUpdateStatus;
+  channel: DesktopUpdateChannel;
   currentVersion: string;
   hostArch: DesktopRuntimeArch;
   appArch: DesktopRuntimeArch;
@@ -95,17 +177,45 @@ export interface DesktopUpdateState {
   canRetry: boolean;
 }
 
+export const DesktopUpdateStateSchema = Schema.Struct({
+  enabled: Schema.Boolean,
+  status: DesktopUpdateStatusSchema,
+  channel: DesktopUpdateChannelSchema,
+  currentVersion: Schema.String,
+  hostArch: DesktopRuntimeArchSchema,
+  appArch: DesktopRuntimeArchSchema,
+  runningUnderArm64Translation: Schema.Boolean,
+  availableVersion: Schema.NullOr(Schema.String),
+  downloadedVersion: Schema.NullOr(Schema.String),
+  downloadPercent: Schema.NullOr(Schema.Number),
+  checkedAt: Schema.NullOr(Schema.String),
+  message: Schema.NullOr(Schema.String),
+  errorContext: Schema.NullOr(Schema.Literals(["check", "download", "install"])),
+  canRetry: Schema.Boolean,
+});
+
 export interface DesktopUpdateActionResult {
   accepted: boolean;
   completed: boolean;
   state: DesktopUpdateState;
 }
 
+export const DesktopUpdateActionResultSchema = Schema.Struct({
+  accepted: Schema.Boolean,
+  completed: Schema.Boolean,
+  state: DesktopUpdateStateSchema,
+});
+
 export interface DesktopUpdateCheckResult {
   checked: boolean;
   state: DesktopUpdateState;
 }
 
+export const DesktopUpdateCheckResultSchema = Schema.Struct({
+  checked: Schema.Boolean,
+  state: DesktopUpdateStateSchema,
+});
+
 export interface DesktopEnvironmentBootstrap {
   label: string;
   httpBaseUrl: string | null;
@@ -113,24 +223,154 @@ export interface DesktopEnvironmentBootstrap {
   bootstrapToken?: string;
 }
 
-export interface PersistedSavedEnvironmentRecord {
-  environmentId: EnvironmentId;
-  label: string;
-  wsBaseUrl: string;
+export const DesktopEnvironmentBootstrapSchema = Schema.Struct({
+  label: Schema.String,
+  httpBaseUrl: Schema.NullOr(Schema.String),
+  wsBaseUrl: Schema.NullOr(Schema.String),
+  bootstrapToken: Schema.optionalKey(Schema.String),
+});
+
+export const DesktopSshEnvironmentTargetSchema = Schema.Struct({
+  alias: Schema.String,
+  hostname: Schema.String,
+  username: Schema.NullOr(Schema.String),
+  port: Schema.NullOr(Schema.Number),
+});
+export type DesktopSshEnvironmentTarget = typeof DesktopSshEnvironmentTargetSchema.Type;
+
+export type DesktopSshHostSource = "ssh-config" | "known-hosts";
+export const DesktopSshHostSourceSchema = Schema.Literals(["ssh-config", "known-hosts"]);
+
+export interface DesktopDiscoveredSshHost extends DesktopSshEnvironmentTarget {
+  source: DesktopSshHostSource;
+}
+
+export const DesktopDiscoveredSshHostSchema = Schema.Struct({
+  alias: Schema.String,
+  hostname: Schema.String,
+  username: Schema.NullOr(Schema.String),
+  port: Schema.NullOr(Schema.Number),
+  source: DesktopSshHostSourceSchema,
+});
+
+export interface DesktopSshEnvironmentBootstrap {
+  target: DesktopSshEnvironmentTarget;
   httpBaseUrl: string;
-  createdAt: string;
-  lastConnectedAt: string | null;
+  wsBaseUrl: string;
+  pairingToken: string | null;
+  remotePort?: number;
+  remoteServerKind?: "external" | "managed";
+}
+
+export const DesktopSshEnvironmentBootstrapSchema = Schema.Struct({
+  target: DesktopSshEnvironmentTargetSchema,
+  httpBaseUrl: Schema.String,
+  wsBaseUrl: Schema.String,
+  pairingToken: Schema.NullOr(Schema.String),
+  remotePort: Schema.optionalKey(Schema.Number),
+  remoteServerKind: Schema.optionalKey(Schema.Literals(["external", "managed"])),
+});
+
+export interface DesktopSshPasswordPromptRequest {
+  requestId: string;
+  destination: string;
+  username: string | null;
+  prompt: string;
+  expiresAt: string;
 }
 
+export const DesktopSshPasswordPromptRequestSchema = Schema.Struct({
+  requestId: Schema.String,
+  destination: Schema.String,
+  username: Schema.NullOr(Schema.String),
+  prompt: Schema.String,
+  expiresAt: Schema.String,
+});
+
+export const DesktopSshPasswordPromptCancelledType = "ssh-password-prompt-cancelled" as const;
+
+export const DesktopSshPasswordPromptCancelledResultSchema = Schema.Struct({
+  type: Schema.Literal(DesktopSshPasswordPromptCancelledType),
+  message: Schema.String,
+});
+
+export const DesktopSshEnvironmentEnsureOptionsSchema = Schema.Struct({
+  issuePairingToken: Schema.optionalKey(Schema.Boolean),
+});
+
+export const DesktopSshEnvironmentEnsureInputSchema = Schema.Struct({
+  target: DesktopSshEnvironmentTargetSchema,
+  options: Schema.optionalKey(DesktopSshEnvironmentEnsureOptionsSchema),
+});
+
+export const DesktopSshEnvironmentEnsureResultSchema = Schema.Union([
+  DesktopSshEnvironmentBootstrapSchema,
+  DesktopSshPasswordPromptCancelledResultSchema,
+]);
+
+export const DesktopSshHttpBaseUrlInputSchema = Schema.Struct({
+  httpBaseUrl: Schema.String,
+});
+
+export const DesktopSshBearerRequestInputSchema = Schema.Struct({
+  httpBaseUrl: Schema.String,
+  bearerToken: Schema.String,
+});
+
+export const DesktopSshBearerBootstrapInputSchema = Schema.Struct({
+  httpBaseUrl: Schema.String,
+  credential: Schema.String,
+});
+
+export const DesktopSshPasswordPromptResolutionInputSchema = Schema.Struct({
+  requestId: Schema.String,
+  password: Schema.NullOr(Schema.String),
+});
+
+export const PersistedSavedEnvironmentRecordSchema = Schema.Struct({
+  environmentId: EnvironmentId,
+  label: Schema.String,
+  wsBaseUrl: Schema.String,
+  httpBaseUrl: Schema.String,
+  createdAt: Schema.String,
+  lastConnectedAt: Schema.NullOr(Schema.String),
+  desktopSsh: Schema.optionalKey(DesktopSshEnvironmentTargetSchema),
+});
+export type PersistedSavedEnvironmentRecord = typeof PersistedSavedEnvironmentRecordSchema.Type;
+
 export type DesktopServerExposureMode = "local-only" | "network-accessible";
 
+export const DesktopServerExposureModeSchema = Schema.Literals([
+  "local-only",
+  "network-accessible",
+]);
+
 export interface DesktopServerExposureState {
   mode: DesktopServerExposureMode;
   endpointUrl: string | null;
   advertisedHost: string | null;
+  tailscaleServeEnabled: boolean;
+  tailscaleServePort: number;
 }
 
+export const DesktopServerExposureStateSchema = Schema.Struct({
+  mode: DesktopServerExposureModeSchema,
+  endpointUrl: Schema.NullOr(Schema.String),
+  advertisedHost: Schema.NullOr(Schema.String),
+  tailscaleServeEnabled: Schema.Boolean,
+  tailscaleServePort: Schema.Number,
+});
+
+export interface PickFolderOptions {
+  initialPath?: string | null;
+}
+
+export const PickFolderOptionsSchema = Schema.Struct({
+  initialPath: Schema.optionalKey(Schema.NullOr(Schema.String)),
+});
+
 export interface DesktopBridge {
+  getAppBranding: () => DesktopAppBranding | null;
   getLocalEnvironmentBootstrap: () => DesktopEnvironmentBootstrap | null;
   getClientSettings: () => Promise<ClientSettings | null>;
   setClientSettings: (settings: ClientSettings) => Promise<void>;
@@ -141,9 +381,32 @@ export interface DesktopBridge {
   getSavedEnvironmentSecret: (environmentId: EnvironmentId) => Promise<string | null>;
   setSavedEnvironmentSecret: (environmentId: EnvironmentId, secret: string) => Promise<boolean>;
   removeSavedEnvironmentSecret: (environmentId: EnvironmentId) => Promise<void>;
+  discoverSshHosts: () => Promise<readonly DesktopDiscoveredSshHost[]>;
+  ensureSshEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+    options?: { issuePairingToken?: boolean },
+  ) => Promise<DesktopSshEnvironmentBootstrap>;
+  disconnectSshEnvironment: (target: DesktopSshEnvironmentTarget) => Promise<void>;
+  fetchSshEnvironmentDescriptor: (httpBaseUrl: string) => Promise<ExecutionEnvironmentDescriptor>;
+  bootstrapSshBearerSession: (
+    httpBaseUrl: string,
+    credential: string,
+  ) => Promise<AuthBearerBootstrapResult>;
+  fetchSshSessionState: (httpBaseUrl: string, bearerToken: string) => Promise<AuthSessionState>;
+  issueSshWebSocketToken: (
+    httpBaseUrl: string,
+    bearerToken: string,
+  ) => Promise<AuthWebSocketTokenResult>;
+  onSshPasswordPrompt: (listener: (request: DesktopSshPasswordPromptRequest) => void) => () => void;
+  resolveSshPasswordPrompt: (requestId: string, password: string | null) => Promise<void>;
   getServerExposureState: () => Promise<DesktopServerExposureState>;
   setServerExposureMode: (mode: DesktopServerExposureMode) => Promise<DesktopServerExposureState>;
-  pickFolder: () => Promise<string | null>;
+  setTailscaleServeEnabled: (input: {
+    readonly enabled: boolean;
+    readonly port?: number;
+  }) => Promise<DesktopServerExposureState>;
+  getAdvertisedEndpoints: () => Promise<readonly AdvertisedEndpoint[]>;
+  pickFolder: (options?: PickFolderOptions) => Promise<string | null>;
   confirm: (message: string) => Promise<boolean>;
   setTheme: (theme: DesktopTheme) => Promise<void>;
   showContextMenu: <T extends string>(
@@ -153,6 +416,7 @@ export interface DesktopBridge {
   openExternal: (url: string) => Promise<boolean>;
   onMenuAction: (listener: (action: string) => void) => () => void;
   getUpdateState: () => Promise<DesktopUpdateState>;
+  setUpdateChannel: (channel: DesktopUpdateChannel) => Promise<DesktopUpdateState>;
   checkForUpdate: () => Promise<DesktopUpdateCheckResult>;
   downloadUpdate: () => Promise<DesktopUpdateActionResult>;
   installUpdate: () => Promise<DesktopUpdateActionResult>;
@@ -171,7 +435,7 @@ export interface DesktopBridge {
  */
 export interface LocalApi {
   dialogs: {
-    pickFolder: () => Promise<string | null>;
+    pickFolder: (options?: PickFolderOptions) => Promise<string | null>;
     confirm: (message: string) => Promise<boolean>;
   };
   shell: {
@@ -197,10 +461,26 @@ export interface LocalApi {
   };
   server: {
     getConfig: () => Promise<ServerConfig>;
-    refreshProviders: () => Promise<ServerProviderUpdatedPayload>;
+    /**
+     * Refresh provider snapshots. When `input.instanceId` is supplied only that
+     * configured instance is probed; otherwise every configured instance is
+     * refreshed (legacy untargeted refresh).
+     */
+    refreshProviders: (input?: {
+      readonly instanceId?: ProviderInstanceId;
+    }) => Promise<ServerProviderUpdatedPayload>;
+    updateProvider: (input: ServerProviderUpdateInput) => Promise<ServerProviderUpdatedPayload>;
     upsertKeybinding: (input: ServerUpsertKeybindingInput) => Promise<ServerUpsertKeybindingResult>;
+    removeKeybinding: (input: ServerRemoveKeybindingInput) => Promise<ServerRemoveKeybindingResult>;
     getSettings: () => Promise<ServerSettings>;
     updateSettings: (patch: ServerSettingsPatch) => Promise<ServerSettings>;
+    discoverSourceControl: () => Promise<SourceControlDiscoveryResult>;
+    getTraceDiagnostics: () => Promise<ServerTraceDiagnosticsResult>;
+    getProcessDiagnostics: () => Promise<ServerProcessDiagnosticsResult>;
+    getProcessResourceHistory: (
+      input: ServerProcessResourceHistoryInput,
+    ) => Promise<ServerProcessResourceHistoryResult>;
+    signalProcess: (input: ServerSignalProcessInput) => Promise<ServerSignalProcessResult>;
   };
 }
 
@@ -209,7 +489,7 @@ export interface LocalApi {
  *
  * These operations must always be routed with explicit environment context.
  * They represent remote stateful capabilities such as orchestration, terminal,
- * project, and git operations. In multi-environment mode, each environment gets
+ * project, VCS, and provider operations. In multi-environment mode, each environment gets
  * its own instance of this surface, and callers should resolve it by
  * `environmentId` rather than reaching through the local desktop bridge.
  */
@@ -227,37 +507,59 @@ export interface EnvironmentApi {
     searchEntries: (input: ProjectSearchEntriesInput) => Promise<ProjectSearchEntriesResult>;
     writeFile: (input: ProjectWriteFileInput) => Promise<ProjectWriteFileResult>;
   };
-  git: {
-    listBranches: (input: GitListBranchesInput) => Promise<GitListBranchesResult>;
-    createWorktree: (input: GitCreateWorktreeInput) => Promise<GitCreateWorktreeResult>;
-    removeWorktree: (input: GitRemoveWorktreeInput) => Promise<void>;
-    createBranch: (input: GitCreateBranchInput) => Promise<GitCreateBranchResult>;
-    checkout: (input: GitCheckoutInput) => Promise<GitCheckoutResult>;
-    init: (input: GitInitInput) => Promise<void>;
-    resolvePullRequest: (input: GitPullRequestRefInput) => Promise<GitResolvePullRequestResult>;
-    preparePullRequestThread: (
-      input: GitPreparePullRequestThreadInput,
-    ) => Promise<GitPreparePullRequestThreadResult>;
-    pull: (input: GitPullInput) => Promise<GitPullResult>;
-    refreshStatus: (input: GitStatusInput) => Promise<GitStatusResult>;
+  filesystem: {
+    browse: (input: FilesystemBrowseInput) => Promise<FilesystemBrowseResult>;
+  };
+  sourceControl: {
+    lookupRepository: (
+      input: SourceControlRepositoryLookupInput,
+    ) => Promise<SourceControlRepositoryInfo>;
+    cloneRepository: (
+      input: SourceControlCloneRepositoryInput,
+    ) => Promise<SourceControlCloneRepositoryResult>;
+    publishRepository: (
+      input: SourceControlPublishRepositoryInput,
+    ) => Promise<SourceControlPublishRepositoryResult>;
+  };
+  vcs: {
+    listRefs: (input: VcsListRefsInput) => Promise<VcsListRefsResult>;
+    createWorktree: (input: VcsCreateWorktreeInput) => Promise<VcsCreateWorktreeResult>;
+    removeWorktree: (input: VcsRemoveWorktreeInput) => Promise<void>;
+    createRef: (input: VcsCreateRefInput) => Promise<VcsCreateRefResult>;
+    switchRef: (input: VcsSwitchRefInput) => Promise<VcsSwitchRefResult>;
+    init: (input: VcsInitInput) => Promise<void>;
+    pull: (input: VcsPullInput) => Promise<VcsPullResult>;
+    refreshStatus: (input: VcsStatusInput) => Promise<VcsStatusResult>;
     onStatus: (
-      input: GitStatusInput,
-      callback: (status: GitStatusResult) => void,
+      input: VcsStatusInput,
+      callback: (status: VcsStatusResult) => void,
       options?: {
         onResubscribe?: () => void;
       },
     ) => () => void;
   };
+  git: {
+    resolvePullRequest: (input: GitPullRequestRefInput) => Promise<GitResolvePullRequestResult>;
+    preparePullRequestThread: (
+      input: GitPreparePullRequestThreadInput,
+    ) => Promise<GitPreparePullRequestThreadResult>;
+  };
   orchestration: {
-    getSnapshot: () => Promise<OrchestrationReadModel>;
     dispatchCommand: (command: ClientOrchestrationCommand) => Promise<{ sequence: number }>;
     getTurnDiff: (input: OrchestrationGetTurnDiffInput) => Promise<OrchestrationGetTurnDiffResult>;
     getFullThreadDiff: (
       input: OrchestrationGetFullThreadDiffInput,
     ) => Promise<OrchestrationGetFullThreadDiffResult>;
-    replayEvents: (fromSequenceExclusive: number) => Promise<OrchestrationEvent[]>;
-    onDomainEvent: (
-      callback: (event: OrchestrationEvent) => void,
+    getArchivedShellSnapshot: () => Promise<OrchestrationShellSnapshot>;
+    subscribeShell: (
+      callback: (event: OrchestrationShellStreamItem) => void,
+      options?: {
+        onResubscribe?: () => void;
+      },
+    ) => () => void;
+    subscribeThread: (
+      input: OrchestrationSubscribeThreadInput,
+      callback: (event: OrchestrationThreadStreamItem) => void,
       options?: {
         onResubscribe?: () => void;
       },
diff --git a/packages/contracts/src/keybindings.test.ts b/packages/contracts/src/keybindings.test.ts
index 092d5344f2b..2165597ac30 100644
--- a/packages/contracts/src/keybindings.test.ts
+++ b/packages/contracts/src/keybindings.test.ts
@@ -1,13 +1,13 @@
-import { Schema } from "effect";
 import { assert, it } from "@effect/vitest";
-import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Effect from "effect/Effect";
 
 import {
   KeybindingsConfig,
   KeybindingRule,
   ResolvedKeybindingRule,
   ResolvedKeybindingsConfig,
-} from "./keybindings";
+} from "./keybindings.ts";
 
 const decode = <S extends Schema.Top>(
   schema: S,
@@ -53,6 +53,18 @@ it.effect("parses keybinding rules", () =>
     });
     assert.strictEqual(parsedLocal.command, "chat.newLocal");
 
+    const parsedModelPickerToggle = yield* decode(KeybindingRule, {
+      key: "mod+shift+m",
+      command: "modelPicker.toggle",
+    });
+    assert.strictEqual(parsedModelPickerToggle.command, "modelPicker.toggle");
+
+    const parsedModelPickerJump = yield* decode(KeybindingRule, {
+      key: "mod+1",
+      command: "modelPicker.jump.1",
+    });
+    assert.strictEqual(parsedModelPickerJump.command, "modelPicker.jump.1");
+
     const parsedThreadPrevious = yield* decode(KeybindingRule, {
       key: "mod+shift+[",
       command: "thread.previous",
diff --git a/packages/contracts/src/keybindings.ts b/packages/contracts/src/keybindings.ts
index 72067eac8a8..502e564fb82 100644
--- a/packages/contracts/src/keybindings.ts
+++ b/packages/contracts/src/keybindings.ts
@@ -1,8 +1,8 @@
-import { Schema } from "effect";
-import { TrimmedString } from "./baseSchemas";
+import * as Schema from "effect/Schema";
+import { TrimmedString } from "./baseSchemas.ts";
 
 export const MAX_KEYBINDING_VALUE_LENGTH = 64;
-const MAX_KEYBINDING_WHEN_LENGTH = 256;
+export const MAX_KEYBINDING_WHEN_LENGTH = 256;
 export const MAX_WHEN_EXPRESSION_DEPTH = 64;
 export const MAX_SCRIPT_ID_LENGTH = 24;
 export const MAX_KEYBINDINGS_COUNT = 256;
@@ -20,6 +20,20 @@ export const THREAD_JUMP_KEYBINDING_COMMANDS = [
 ] as const;
 export type ThreadJumpKeybindingCommand = (typeof THREAD_JUMP_KEYBINDING_COMMANDS)[number];
 
+export const MODEL_PICKER_JUMP_KEYBINDING_COMMANDS = [
+  "modelPicker.jump.1",
+  "modelPicker.jump.2",
+  "modelPicker.jump.3",
+  "modelPicker.jump.4",
+  "modelPicker.jump.5",
+  "modelPicker.jump.6",
+  "modelPicker.jump.7",
+  "modelPicker.jump.8",
+  "modelPicker.jump.9",
+] as const;
+export type ModelPickerJumpKeybindingCommand =
+  (typeof MODEL_PICKER_JUMP_KEYBINDING_COMMANDS)[number];
+
 export const THREAD_KEYBINDING_COMMANDS = [
   "thread.previous",
   "thread.next",
@@ -27,6 +41,12 @@ export const THREAD_KEYBINDING_COMMANDS = [
 ] as const;
 export type ThreadKeybindingCommand = (typeof THREAD_KEYBINDING_COMMANDS)[number];
 
+export const MODEL_PICKER_KEYBINDING_COMMANDS = [
+  "modelPicker.toggle",
+  ...MODEL_PICKER_JUMP_KEYBINDING_COMMANDS,
+] as const;
+export type ModelPickerKeybindingCommand = (typeof MODEL_PICKER_KEYBINDING_COMMANDS)[number];
+
 const STATIC_KEYBINDING_COMMANDS = [
   "terminal.toggle",
   "terminal.split",
@@ -37,6 +57,7 @@ const STATIC_KEYBINDING_COMMANDS = [
   "chat.new",
   "chat.newLocal",
   "editor.openFavorite",
+  ...MODEL_PICKER_KEYBINDING_COMMANDS,
   ...THREAD_KEYBINDING_COMMANDS,
 ] as const;
 
@@ -55,12 +76,12 @@ export const KeybindingCommand = Schema.Union([
 ]);
 export type KeybindingCommand = typeof KeybindingCommand.Type;
 
-const KeybindingValue = TrimmedString.check(
+export const KeybindingValue = TrimmedString.check(
   Schema.isMinLength(1),
   Schema.isMaxLength(MAX_KEYBINDING_VALUE_LENGTH),
 );
 
-const KeybindingWhen = TrimmedString.check(
+export const KeybindingWhen = TrimmedString.check(
   Schema.isMinLength(1),
   Schema.isMaxLength(MAX_KEYBINDING_WHEN_LENGTH),
 );
diff --git a/packages/contracts/src/model.ts b/packages/contracts/src/model.ts
index 7d87d882d92..8e7daaa0c79 100644
--- a/packages/contracts/src/model.ts
+++ b/packages/contracts/src/model.ts
@@ -1,71 +1,161 @@
-import { Schema } from "effect";
-import { TrimmedNonEmptyString } from "./baseSchemas";
-import type { ProviderKind } from "./orchestration";
-
-export const CODEX_REASONING_EFFORT_OPTIONS = ["xhigh", "high", "medium", "low"] as const;
-export type CodexReasoningEffort = (typeof CODEX_REASONING_EFFORT_OPTIONS)[number];
-export const CLAUDE_CODE_EFFORT_OPTIONS = ["low", "medium", "high", "max", "ultrathink"] as const;
-export type ClaudeCodeEffort = (typeof CLAUDE_CODE_EFFORT_OPTIONS)[number];
-export type ProviderReasoningEffort = CodexReasoningEffort | ClaudeCodeEffort;
-
-export const CodexModelOptions = Schema.Struct({
-  reasoningEffort: Schema.optional(Schema.Literals(CODEX_REASONING_EFFORT_OPTIONS)),
-  fastMode: Schema.optional(Schema.Boolean),
-});
-export type CodexModelOptions = typeof CodexModelOptions.Type;
-
-export const ClaudeModelOptions = Schema.Struct({
-  thinking: Schema.optional(Schema.Boolean),
-  effort: Schema.optional(Schema.Literals(CLAUDE_CODE_EFFORT_OPTIONS)),
-  fastMode: Schema.optional(Schema.Boolean),
-  contextWindow: Schema.optional(Schema.String),
-});
-export type ClaudeModelOptions = typeof ClaudeModelOptions.Type;
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
+import { ProviderDriverKind } from "./providerInstance.ts";
 
-export const ProviderModelOptions = Schema.Struct({
-  codex: Schema.optional(CodexModelOptions),
-  claudeAgent: Schema.optional(ClaudeModelOptions),
-});
-export type ProviderModelOptions = typeof ProviderModelOptions.Type;
+export const ProviderOptionDescriptorType = Schema.Literals(["select", "boolean"]);
+export type ProviderOptionDescriptorType = typeof ProviderOptionDescriptorType.Type;
 
-export const EffortOption = Schema.Struct({
-  value: TrimmedNonEmptyString,
+export const ProviderOptionChoice = Schema.Struct({
+  id: TrimmedNonEmptyString,
   label: TrimmedNonEmptyString,
+  description: Schema.optional(TrimmedNonEmptyString),
   isDefault: Schema.optional(Schema.Boolean),
 });
-export type EffortOption = typeof EffortOption.Type;
+export type ProviderOptionChoice = typeof ProviderOptionChoice.Type;
 
-export const ContextWindowOption = Schema.Struct({
-  value: TrimmedNonEmptyString,
+const ProviderOptionDescriptorBase = {
+  id: TrimmedNonEmptyString,
   label: TrimmedNonEmptyString,
-  isDefault: Schema.optional(Schema.Boolean),
+  description: Schema.optional(TrimmedNonEmptyString),
+} as const;
+
+export const SelectProviderOptionDescriptor = Schema.Struct({
+  ...ProviderOptionDescriptorBase,
+  type: Schema.Literal("select"),
+  options: Schema.Array(ProviderOptionChoice),
+  currentValue: Schema.optional(TrimmedNonEmptyString),
+  promptInjectedValues: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
+});
+export type SelectProviderOptionDescriptor = typeof SelectProviderOptionDescriptor.Type;
+
+export const BooleanProviderOptionDescriptor = Schema.Struct({
+  ...ProviderOptionDescriptorBase,
+  type: Schema.Literal("boolean"),
+  currentValue: Schema.optional(Schema.Boolean),
+});
+export type BooleanProviderOptionDescriptor = typeof BooleanProviderOptionDescriptor.Type;
+
+export const ProviderOptionDescriptor = Schema.Union([
+  SelectProviderOptionDescriptor,
+  BooleanProviderOptionDescriptor,
+]);
+export type ProviderOptionDescriptor = typeof ProviderOptionDescriptor.Type;
+
+export const ProviderOptionSelectionValue = Schema.Union([TrimmedNonEmptyString, Schema.Boolean]);
+export type ProviderOptionSelectionValue = typeof ProviderOptionSelectionValue.Type;
+
+export const ProviderOptionSelection = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  value: ProviderOptionSelectionValue,
 });
-export type ContextWindowOption = typeof ContextWindowOption.Type;
+export type ProviderOptionSelection = typeof ProviderOptionSelection.Type;
+
+/**
+ * Legacy on-disk shape for provider option selections, kept readable by the
+ * decoder so we can tolerate stored data written before the v3 array shape.
+ *
+ * Persisted historically as `{ effort: "max", fastMode: true, ... }` inside
+ * `modelSelection.options`. Migration 026 rewrites stored rows to the
+ * canonical array shape, but we still see the legacy form in:
+ *   - `settings.json` files from older client builds,
+ *   - SQLite databases that have not yet run migration 026,
+ *   - any future regression that re-introduces the legacy shape.
+ */
+const LegacyProviderOptionSelectionsObject = Schema.Record(Schema.String, Schema.Unknown);
+
+const ProviderOptionSelectionsFromLegacyObject = LegacyProviderOptionSelectionsObject.pipe(
+  Schema.decodeTo(
+    Schema.Array(ProviderOptionSelection),
+    SchemaTransformation.transformOrFail({
+      decode: (record) => Effect.succeed(coerceLegacyOptionsObjectToArray(record)),
+      encode: (selections) => Effect.succeed(canonicalSelectionsToLegacyObject(selections)),
+    }),
+  ),
+);
+
+/**
+ * Schema for the `options` field of every `ModelSelection` variant.
+ *
+ * Accepts both:
+ *   - the canonical array shape `Array<{ id, value }>` (preferred), and
+ *   - the legacy object shape `Record<string, string | boolean | …>` from
+ *     pre-migration data.
+ *
+ * Always normalizes to the canonical array on decode and re-encodes as the
+ * canonical array, so any legacy storage gets cleaned up the next time the
+ * containing record is written back.
+ */
+export const ProviderOptionSelections = Schema.Union([
+  Schema.Array(ProviderOptionSelection),
+  ProviderOptionSelectionsFromLegacyObject,
+]);
+export type ProviderOptionSelections = typeof ProviderOptionSelections.Type;
+
+function coerceLegacyOptionsObjectToArray(
+  record: Record<string, unknown>,
+): ReadonlyArray<ProviderOptionSelection> {
+  const entries: Array<ProviderOptionSelection> = [];
+  for (const [rawKey, rawValue] of Object.entries(record)) {
+    const id = typeof rawKey === "string" ? rawKey.trim() : "";
+    if (id.length === 0) continue;
+    if (typeof rawValue === "string") {
+      const trimmed = rawValue.trim();
+      if (trimmed.length > 0) entries.push({ id, value: trimmed });
+    } else if (typeof rawValue === "boolean") {
+      entries.push({ id, value: rawValue });
+    }
+    // Drop anything else (numbers, null, nested objects/arrays) to match the
+    // permissive normalization performed by migration 026.
+  }
+  return entries;
+}
+
+function canonicalSelectionsToLegacyObject(
+  selections: ReadonlyArray<ProviderOptionSelection>,
+): Record<string, string | boolean> {
+  const out: Record<string, string | boolean> = {};
+  for (const { id, value } of selections) {
+    out[id] = value;
+  }
+  return out;
+}
 
 export const ModelCapabilities = Schema.Struct({
-  reasoningEffortLevels: Schema.Array(EffortOption),
-  supportsFastMode: Schema.Boolean,
-  supportsThinkingToggle: Schema.Boolean,
-  contextWindowOptions: Schema.Array(ContextWindowOption),
-  promptInjectedEffortLevels: Schema.Array(TrimmedNonEmptyString),
+  optionDescriptors: Schema.optional(Schema.Array(ProviderOptionDescriptor)),
 });
 export type ModelCapabilities = typeof ModelCapabilities.Type;
 
-export const DEFAULT_MODEL_BY_PROVIDER: Record<ProviderKind, string> = {
-  codex: "gpt-5.4",
-  claudeAgent: "claude-sonnet-4-6",
-};
+const CODEX_DRIVER_KIND = ProviderDriverKind.make("codex");
+const CLAUDE_DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
+const CURSOR_DRIVER_KIND = ProviderDriverKind.make("cursor");
+const OPENCODE_DRIVER_KIND = ProviderDriverKind.make("opencode");
 
-export const DEFAULT_MODEL = DEFAULT_MODEL_BY_PROVIDER.codex;
+export const DEFAULT_MODEL = "gpt-5.4";
+export const DEFAULT_GIT_TEXT_GENERATION_MODEL = "gpt-5.4-mini";
+
+export const DEFAULT_MODEL_BY_PROVIDER: Partial<Record<ProviderDriverKind, string>> = {
+  [CODEX_DRIVER_KIND]: DEFAULT_MODEL,
+  [CLAUDE_DRIVER_KIND]: "claude-sonnet-4-6",
+  [CURSOR_DRIVER_KIND]: "auto",
+  [OPENCODE_DRIVER_KIND]: "openai/gpt-5",
+};
 
 /** Per-provider text generation model defaults. */
-export const DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER: Record<ProviderKind, string> = {
-  codex: "gpt-5.4-mini",
-  claudeAgent: "claude-haiku-4-5",
+export const DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER: Partial<
+  Record<ProviderDriverKind, string>
+> = {
+  [CODEX_DRIVER_KIND]: DEFAULT_GIT_TEXT_GENERATION_MODEL,
+  [CLAUDE_DRIVER_KIND]: "claude-haiku-4-5",
+  [CURSOR_DRIVER_KIND]: "composer-2",
+  [OPENCODE_DRIVER_KIND]: "openai/gpt-5",
 };
 
-export const MODEL_SLUG_ALIASES_BY_PROVIDER: Record<ProviderKind, Record<string, string>> = {
-  codex: {
+export const MODEL_SLUG_ALIASES_BY_PROVIDER: Partial<
+  Record<ProviderDriverKind, Record<string, string>>
+> = {
+  [CODEX_DRIVER_KIND]: {
     "gpt-5-codex": "gpt-5.4",
     "5.4": "gpt-5.4",
     "5.3": "gpt-5.3-codex",
@@ -73,8 +163,10 @@ export const MODEL_SLUG_ALIASES_BY_PROVIDER: Record<ProviderKind, Record<string,
     "5.3-spark": "gpt-5.3-codex-spark",
     "gpt-5.3-spark": "gpt-5.3-codex-spark",
   },
-  claudeAgent: {
-    opus: "claude-opus-4-6",
+  [CLAUDE_DRIVER_KIND]: {
+    opus: "claude-opus-4-7",
+    "opus-4.7": "claude-opus-4-7",
+    "claude-opus-4.7": "claude-opus-4-7",
     "opus-4.6": "claude-opus-4-6",
     "claude-opus-4.6": "claude-opus-4-6",
     "claude-opus-4-6-20251117": "claude-opus-4-6",
@@ -87,11 +179,25 @@ export const MODEL_SLUG_ALIASES_BY_PROVIDER: Record<ProviderKind, Record<string,
     "claude-haiku-4.5": "claude-haiku-4-5",
     "claude-haiku-4-5-20251001": "claude-haiku-4-5",
   },
+  [CURSOR_DRIVER_KIND]: {
+    composer: "composer-2",
+    "composer-1.5": "composer-1.5",
+    "composer-1": "composer-1.5",
+    "opus-4.6-thinking": "claude-opus-4-6",
+    "opus-4.6": "claude-opus-4-6",
+    "sonnet-4.6-thinking": "claude-sonnet-4-6",
+    "sonnet-4.6": "claude-sonnet-4-6",
+    "opus-4.5-thinking": "claude-opus-4-5",
+    "opus-4.5": "claude-opus-4-5",
+  },
+  [OPENCODE_DRIVER_KIND]: {},
 };
 
 // ── Provider display names ────────────────────────────────────────────
 
-export const PROVIDER_DISPLAY_NAMES: Record<ProviderKind, string> = {
-  codex: "Codex",
-  claudeAgent: "Claude",
+export const PROVIDER_DISPLAY_NAMES: Partial<Record<ProviderDriverKind, string>> = {
+  [CODEX_DRIVER_KIND]: "Codex",
+  [CLAUDE_DRIVER_KIND]: "Claude",
+  [CURSOR_DRIVER_KIND]: "Cursor",
+  [OPENCODE_DRIVER_KIND]: "OpenCode",
 };
diff --git a/packages/contracts/src/orchestration.test.ts b/packages/contracts/src/orchestration.test.ts
index 53e84f1b98b..a9cdfd22532 100644
--- a/packages/contracts/src/orchestration.test.ts
+++ b/packages/contracts/src/orchestration.test.ts
@@ -1,12 +1,15 @@
 import assert from "node:assert/strict";
 import { it } from "@effect/vitest";
-import { Effect, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
 
 import {
   DEFAULT_PROVIDER_INTERACTION_MODE,
   DEFAULT_RUNTIME_MODE,
+  ModelSelection,
   OrchestrationCommand,
   OrchestrationEvent,
+  OrchestrationGetFullThreadDiffInput,
   OrchestrationGetTurnDiffInput,
   OrchestrationLatestTurn,
   ProjectCreatedPayload,
@@ -19,9 +22,11 @@ import {
   ThreadCreatedPayload,
   ThreadTurnDiff,
   ThreadTurnStartRequestedPayload,
-} from "./orchestration";
+} from "./orchestration.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
 
 const decodeTurnDiffInput = Schema.decodeUnknownEffect(OrchestrationGetTurnDiffInput);
+const decodeFullThreadDiffInput = Schema.decodeUnknownEffect(OrchestrationGetFullThreadDiffInput);
 const decodeThreadTurnDiff = Schema.decodeUnknownEffect(ThreadTurnDiff);
 const decodeProjectCreateCommand = Schema.decodeUnknownEffect(ProjectCreateCommand);
 const decodeProjectCreatedPayload = Schema.decodeUnknownEffect(ProjectCreatedPayload);
@@ -33,6 +38,14 @@ const decodeThreadTurnStartRequestedPayload = Schema.decodeUnknownEffect(
 const decodeOrchestrationLatestTurn = Schema.decodeUnknownEffect(OrchestrationLatestTurn);
 const decodeOrchestrationProposedPlan = Schema.decodeUnknownEffect(OrchestrationProposedPlan);
 const decodeOrchestrationSession = Schema.decodeUnknownEffect(OrchestrationSession);
+const encodeThreadCreatedPayload = Schema.encodeEffect(ThreadCreatedPayload);
+
+function getOptionValue(
+  options: ReadonlyArray<{ id: string; value: unknown }> | undefined,
+  id: string,
+): unknown {
+  return options?.find((option) => option.id === id)?.value;
+}
 const decodeThreadCreatedPayload = Schema.decodeUnknownEffect(ThreadCreatedPayload);
 const decodeOrchestrationCommand = Schema.decodeUnknownEffect(OrchestrationCommand);
 const decodeOrchestrationEvent = Schema.decodeUnknownEffect(OrchestrationEvent);
@@ -50,6 +63,29 @@ it.effect("parses turn diff input when fromTurnCount <= toTurnCount", () =>
   }),
 );
 
+it.effect("parses turn diff input with whitespace ignoring enabled", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeTurnDiffInput({
+      threadId: "thread-1",
+      fromTurnCount: 1,
+      toTurnCount: 2,
+      ignoreWhitespace: true,
+    });
+    assert.strictEqual(parsed.ignoreWhitespace, true);
+  }),
+);
+
+it.effect("parses full thread diff input with whitespace ignoring enabled", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeFullThreadDiffInput({
+      threadId: "thread-1",
+      toTurnCount: 2,
+      ignoreWhitespace: true,
+    });
+    assert.strictEqual(parsed.ignoreWhitespace, true);
+  }),
+);
+
 it.effect("rejects turn diff input when fromTurnCount > toTurnCount", () =>
   Effect.gen(function* () {
     const result = yield* Effect.exit(
@@ -95,13 +131,30 @@ it.effect("trims branded ids and command string fields at decode boundaries", ()
     assert.strictEqual(parsed.projectId, "project-1");
     assert.strictEqual(parsed.title, "Project Title");
     assert.strictEqual(parsed.workspaceRoot, "/tmp/workspace");
+    assert.strictEqual(parsed.createWorkspaceRootIfMissing, undefined);
     assert.deepStrictEqual(parsed.defaultModelSelection, {
-      provider: "codex",
+      instanceId: ProviderInstanceId.make("codex"),
       model: "gpt-5.2",
     });
   }),
 );
 
+it.effect("decodes project.create with createWorkspaceRootIfMissing enabled", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeProjectCreateCommand({
+      type: "project.create",
+      commandId: "cmd-1",
+      projectId: "project-1",
+      title: "Project Title",
+      workspaceRoot: "/tmp/workspace",
+      createWorkspaceRootIfMissing: true,
+      createdAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    assert.strictEqual(parsed.createWorkspaceRootIfMissing, true);
+  }),
+);
+
 it.effect("decodes historical project.created payloads with a default provider", () =>
   Effect.gen(function* () {
     const parsed = yield* decodeProjectCreatedPayload({
@@ -116,7 +169,7 @@ it.effect("decodes historical project.created payloads with a default provider",
       createdAt: "2026-01-01T00:00:00.000Z",
       updatedAt: "2026-01-01T00:00:00.000Z",
     });
-    assert.strictEqual(parsed.defaultModelSelection?.provider, "codex");
+    assert.strictEqual(parsed.defaultModelSelection?.instanceId, "codex");
   }),
 );
 
@@ -130,7 +183,7 @@ it.effect("decodes project.meta-updated payloads with explicit default provider"
       },
       updatedAt: "2026-01-01T00:00:00.000Z",
     });
-    assert.strictEqual(parsed.defaultModelSelection?.provider, "claudeAgent");
+    assert.strictEqual(parsed.defaultModelSelection?.instanceId, "claudeAgent");
   }),
 );
 
@@ -189,7 +242,7 @@ it.effect("preserves explicit provider and runtime mode in thread.turn.start", (
       runtimeMode: "full-access",
       createdAt: "2026-01-01T00:00:00.000Z",
     });
-    assert.strictEqual(parsed.modelSelection?.provider, "codex");
+    assert.strictEqual(parsed.modelSelection?.instanceId, "codex");
     assert.strictEqual(parsed.runtimeMode, "full-access");
     assert.strictEqual(parsed.interactionMode, DEFAULT_PROVIDER_INTERACTION_MODE);
   }),
@@ -254,7 +307,7 @@ it.effect("decodes thread.created runtime mode for historical events", () =>
     });
 
     assert.strictEqual(parsed.runtimeMode, DEFAULT_RUNTIME_MODE);
-    assert.strictEqual(parsed.modelSelection.provider, "codex");
+    assert.strictEqual(parsed.modelSelection.instanceId, "codex");
   }),
 );
 
@@ -268,7 +321,7 @@ it.effect("decodes thread.meta-updated payloads with explicit provider", () =>
       },
       updatedAt: "2026-01-01T00:00:00.000Z",
     });
-    assert.strictEqual(parsed.modelSelection?.provider, "claudeAgent");
+    assert.strictEqual(parsed.modelSelection?.instanceId, "claudeAgent");
   }),
 );
 
@@ -347,19 +400,97 @@ it.effect("accepts provider-scoped model options in thread.turn.start", () =>
       modelSelection: {
         provider: "codex",
         model: "gpt-5.3-codex",
+        options: [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
+      },
+      createdAt: "2026-01-01T00:00:00.000Z",
+    });
+    assert.strictEqual(parsed.modelSelection?.instanceId, "codex");
+    assert.strictEqual(getOptionValue(parsed.modelSelection?.options, "reasoningEffort"), "high");
+    assert.strictEqual(getOptionValue(parsed.modelSelection?.options, "fastMode"), true);
+  }),
+);
+
+it.effect("normalizes legacy object-shaped modelSelection.options on decode", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeThreadCreatedPayload({
+      threadId: "thread-1",
+      projectId: "project-1",
+      title: "Legacy options thread",
+      modelSelection: {
+        provider: "claudeAgent",
+        model: "claude-opus-4-6",
         options: {
-          reasoningEffort: "high",
+          effort: "max",
           fastMode: true,
+          // Falsy/garbage entries are dropped, matching migration 026.
+          emptyStr: "   ",
+          nullish: null,
+          nested: { foo: 1 },
         },
       },
+      branch: null,
+      worktreePath: null,
       createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
     });
-    assert.strictEqual(parsed.modelSelection?.provider, "codex");
-    assert.strictEqual(parsed.modelSelection?.options?.reasoningEffort, "high");
-    assert.strictEqual(parsed.modelSelection?.options?.fastMode, true);
+
+    assert.strictEqual(parsed.modelSelection.instanceId, ProviderInstanceId.make("claudeAgent"));
+    assert.deepStrictEqual(parsed.modelSelection.options, [
+      { id: "effort", value: "max" },
+      { id: "fastMode", value: true },
+    ]);
   }),
 );
 
+it.effect("normalizes legacy object-shaped defaultModelSelection.options on decode", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeProjectCreatedPayload({
+      projectId: "project-1",
+      title: "Legacy default project",
+      workspaceRoot: "/tmp/legacy",
+      defaultModelSelection: {
+        provider: "codex",
+        model: "gpt-5.4",
+        options: { reasoningEffort: "low" },
+      },
+      scripts: [],
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    });
+
+    assert.deepStrictEqual(parsed.defaultModelSelection?.options, [
+      { id: "reasoningEffort", value: "low" },
+    ]);
+  }),
+);
+
+it.effect(
+  "normalizes legacy object-shaped options on decode and re-encodes as canonical array",
+  () =>
+    Effect.gen(function* () {
+      const decoded = yield* decodeThreadCreatedPayload({
+        threadId: "thread-1",
+        projectId: "project-1",
+        title: "Round trip thread",
+        modelSelection: {
+          provider: "codex",
+          model: "gpt-5.4",
+          options: { fastMode: true },
+        },
+        branch: null,
+        worktreePath: null,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+      });
+
+      const encoded = yield* encodeThreadCreatedPayload(decoded);
+      assert.deepStrictEqual(encoded.modelSelection.options, [{ id: "fastMode", value: true }]);
+    }),
+);
+
 it.effect("accepts a title seed in thread.turn.start", () =>
   Effect.gen(function* () {
     const parsed = yield* decodeThreadTurnStartCommand({
@@ -516,3 +647,96 @@ it.effect("preserves proposed plan implementation metadata when present", () =>
     assert.strictEqual(parsed.implementationThreadId, "thread-2");
   }),
 );
+
+// ── ModelSelection: instance-keyed wire shape + legacy decoder ────────
+//
+// `ModelSelection` is routing-keyed on `instanceId` — never a driver kind.
+// Persisted and in-flight payloads from pre-instance builds carry a
+// `provider` field whose value was a driver kind; those payloads are migrated
+// at the wire boundary by
+// promoting `provider` to the default instance id for that driver
+// (built-in drivers use the driver kind slug as their default instance id, so
+// the migration is a 1:1 rename).
+//
+// These tests pin the rollback/fork tolerance invariant: legacy payloads
+// decode cleanly for fork-provided drivers, and the decoded form uses
+// `instanceId` uniformly regardless of origin.
+
+const decodeModelSelection = Schema.decodeUnknownEffect(ModelSelection);
+const encodeModelSelection = Schema.encodeUnknownEffect(ModelSelection);
+
+it.effect("ModelSelection migrates legacy `provider` field to `instanceId`", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeModelSelection({
+      provider: "codex",
+      model: "gpt-5-codex",
+      options: [{ id: "reasoningEffort", value: "high" }],
+    });
+    assert.strictEqual(parsed.instanceId, ProviderInstanceId.make("codex"));
+    assert.strictEqual(parsed.model, "gpt-5-codex");
+    assert.deepStrictEqual(parsed.options, [{ id: "reasoningEffort", value: "high" }]);
+  }),
+);
+
+it.effect("ModelSelection accepts an explicit instanceId routing key", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeModelSelection({
+      instanceId: "codex_personal",
+      model: "gpt-5-codex",
+    });
+    assert.strictEqual(parsed.instanceId, ProviderInstanceId.make("codex_personal"));
+  }),
+);
+
+it.effect("ModelSelection prefers explicit instanceId over legacy provider", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeModelSelection({
+      provider: "codex",
+      instanceId: "codex_personal",
+      model: "gpt-5-codex",
+    });
+    assert.strictEqual(parsed.instanceId, ProviderInstanceId.make("codex_personal"));
+  }),
+);
+
+it.effect(
+  "ModelSelection decodes unknown driver kinds via legacy provider (rollback / fork invariant)",
+  () =>
+    Effect.gen(function* () {
+      const parsed = yield* decodeModelSelection({
+        provider: "ollama",
+        model: "llama3:70b",
+        options: [{ id: "temperature", value: "0.4" }],
+      });
+      assert.strictEqual(parsed.instanceId, ProviderInstanceId.make("ollama"));
+      assert.strictEqual(parsed.model, "llama3:70b");
+    }),
+);
+
+it.effect("ModelSelection encodes to the canonical instanceId wire form", () =>
+  Effect.gen(function* () {
+    const decoded = yield* decodeModelSelection({
+      provider: "ollama",
+      model: "llama3:70b",
+      options: [{ id: "temperature", value: "0.4" }],
+    });
+    const encoded = yield* encodeModelSelection(decoded);
+    assert.deepStrictEqual(encoded, {
+      instanceId: "ollama",
+      model: "llama3:70b",
+      options: [{ id: "temperature", value: "0.4" }],
+    });
+  }),
+);
+
+it.effect("ModelSelection rejects malformed instance ids", () =>
+  Effect.gen(function* () {
+    const result = yield* Effect.exit(
+      decodeModelSelection({
+        instanceId: "1invalid", // must start with a letter
+        model: "x",
+      }),
+    );
+    assert.strictEqual(result._tag, "Failure");
+  }),
+);
diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.ts
index c80367d1587..401928171c8 100644
--- a/packages/contracts/src/orchestration.ts
+++ b/packages/contracts/src/orchestration.ts
@@ -1,6 +1,11 @@
-import { Effect, Option, Schema, SchemaIssue, Struct } from "effect";
-import { ClaudeModelOptions, CodexModelOptions } from "./model";
-import { RepositoryIdentity } from "./environment";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import * as Struct from "effect/Struct";
+import { ProviderOptionSelections } from "./model.ts";
+import { RepositoryIdentity } from "./environment.ts";
 import {
   ApprovalRequestId,
   CheckpointRef,
@@ -14,18 +19,19 @@ import {
   ThreadId,
   TrimmedNonEmptyString,
   TurnId,
-} from "./baseSchemas";
+} from "./baseSchemas.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
 
 export const ORCHESTRATION_WS_METHODS = {
-  getSnapshot: "orchestration.getSnapshot",
   dispatchCommand: "orchestration.dispatchCommand",
   getTurnDiff: "orchestration.getTurnDiff",
   getFullThreadDiff: "orchestration.getFullThreadDiff",
   replayEvents: "orchestration.replayEvents",
+  getArchivedShellSnapshot: "orchestration.getArchivedShellSnapshot",
+  subscribeShell: "orchestration.subscribeShell",
+  subscribeThread: "orchestration.subscribeThread",
 } as const;
 
-export const ProviderKind = Schema.Literals(["codex", "claudeAgent"]);
-export type ProviderKind = typeof ProviderKind.Type;
 export const ProviderApprovalPolicy = Schema.Literals([
   "untrusted",
   "on-failure",
@@ -40,23 +46,72 @@ export const ProviderSandboxMode = Schema.Literals([
 ]);
 export type ProviderSandboxMode = typeof ProviderSandboxMode.Type;
 
-export const DEFAULT_PROVIDER_KIND: ProviderKind = "codex";
-
-export const CodexModelSelection = Schema.Struct({
-  provider: Schema.Literal("codex"),
+/**
+ * `ModelSelection` — selection of a model on a configured provider instance.
+ *
+ * The routing key is `instanceId` (a user-defined slug identifying one
+ * configured provider instance). Drivers, credentials, working-directory
+ * bindings, and any other per-instance state are recovered from the
+ * runtime registry via the instance id.
+ *
+ * Wire legacy: persisted selections produced before the driver/instance
+ * split carried a `provider: <driver-id>` field instead. The schema absorbs
+ * that shape via a pre-decoding transform — `{provider, model}` is promoted
+ * to `{instanceId: defaultInstanceIdForDriver(provider), model}`. No
+ * post-decode compatibility code lives in the runtime; the transform is the
+ * only compat surface.
+ */
+const ModelSelectionWire = Schema.Struct({
+  instanceId: ProviderInstanceId,
   model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(CodexModelOptions),
-});
-export type CodexModelSelection = typeof CodexModelSelection.Type;
-
-export const ClaudeModelSelection = Schema.Struct({
-  provider: Schema.Literal("claudeAgent"),
-  model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(ClaudeModelOptions),
-});
-export type ClaudeModelSelection = typeof ClaudeModelSelection.Type;
-
-export const ModelSelection = Schema.Union([CodexModelSelection, ClaudeModelSelection]);
+  options: Schema.optionalKey(ProviderOptionSelections),
+});
+
+// Source shape for persisted legacy payloads. Fields are typed as
+// `Schema.Unknown` so malformed drafts still make it into the transform and
+// fail validation through the target schema (with proper error messages)
+// rather than at the source-struct layer where the error is less actionable.
+const ModelSelectionSource = Schema.Struct({
+  provider: Schema.optional(Schema.Unknown),
+  instanceId: Schema.optional(Schema.Unknown),
+  model: Schema.Unknown,
+  options: Schema.optional(Schema.Unknown),
+});
+
+export const ModelSelection = ModelSelectionSource.pipe(
+  Schema.decodeTo(
+    ModelSelectionWire,
+    SchemaTransformation.transformOrFail({
+      decode: (raw) => {
+        // Resolve the routing key: prefer an explicit `instanceId`; fall
+        // back to promoting the legacy `provider` slug (the canonical
+        // `defaultInstanceIdForDriver` mapping) so persisted rollout-era
+        // payloads decode without data loss. The target schema brands the
+        // string as `ProviderInstanceId`.
+        const instanceIdSource =
+          raw.instanceId !== undefined
+            ? raw.instanceId
+            : typeof raw.provider === "string"
+              ? raw.provider
+              : undefined;
+        const base: Record<string, unknown> = {
+          instanceId: instanceIdSource,
+          model: raw.model,
+        };
+        if (raw.options !== undefined) base.options = raw.options;
+        return Effect.succeed(base as typeof ModelSelectionWire.Encoded);
+      },
+      encode: (value) => {
+        const base: Record<string, unknown> = {
+          model: value.model,
+          instanceId: value.instanceId,
+        };
+        if (value.options !== undefined) base.options = value.options;
+        return Effect.succeed(base as typeof ModelSelectionSource.Encoded);
+      },
+    }),
+  ),
+);
 export type ModelSelection = typeof ModelSelection.Type;
 
 export const RuntimeMode = Schema.Literals([
@@ -206,6 +261,7 @@ export const OrchestrationSession = Schema.Struct({
   threadId: ThreadId,
   status: OrchestrationSessionStatus,
   providerName: Schema.NullOr(TrimmedNonEmptyString),
+  providerInstanceId: Schema.optional(ProviderInstanceId),
   runtimeMode: RuntimeMode.pipe(Schema.withDecodingDefault(Effect.succeed(DEFAULT_RUNTIME_MODE))),
   activeTurnId: Schema.NullOr(TurnId),
   lastError: Schema.NullOr(TrimmedNonEmptyString),
@@ -308,12 +364,100 @@ export const OrchestrationReadModel = Schema.Struct({
 });
 export type OrchestrationReadModel = typeof OrchestrationReadModel.Type;
 
+export const OrchestrationProjectShell = Schema.Struct({
+  id: ProjectId,
+  title: TrimmedNonEmptyString,
+  workspaceRoot: TrimmedNonEmptyString,
+  repositoryIdentity: Schema.optional(Schema.NullOr(RepositoryIdentity)),
+  defaultModelSelection: Schema.NullOr(ModelSelection),
+  scripts: Schema.Array(ProjectScript),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
+});
+export type OrchestrationProjectShell = typeof OrchestrationProjectShell.Type;
+
+export const OrchestrationThreadShell = Schema.Struct({
+  id: ThreadId,
+  projectId: ProjectId,
+  title: TrimmedNonEmptyString,
+  modelSelection: ModelSelection,
+  runtimeMode: RuntimeMode,
+  interactionMode: ProviderInteractionMode.pipe(
+    Schema.withDecodingDefault(Effect.succeed(DEFAULT_PROVIDER_INTERACTION_MODE)),
+  ),
+  branch: Schema.NullOr(TrimmedNonEmptyString),
+  worktreePath: Schema.NullOr(TrimmedNonEmptyString),
+  latestTurn: Schema.NullOr(OrchestrationLatestTurn),
+  createdAt: IsoDateTime,
+  updatedAt: IsoDateTime,
+  archivedAt: Schema.NullOr(IsoDateTime).pipe(Schema.withDecodingDefault(Effect.succeed(null))),
+  session: Schema.NullOr(OrchestrationSession),
+  latestUserMessageAt: Schema.NullOr(IsoDateTime),
+  hasPendingApprovals: Schema.Boolean,
+  hasPendingUserInput: Schema.Boolean,
+  hasActionableProposedPlan: Schema.Boolean,
+});
+export type OrchestrationThreadShell = typeof OrchestrationThreadShell.Type;
+
+export const OrchestrationShellSnapshot = Schema.Struct({
+  snapshotSequence: NonNegativeInt,
+  projects: Schema.Array(OrchestrationProjectShell),
+  threads: Schema.Array(OrchestrationThreadShell),
+  updatedAt: IsoDateTime,
+});
+export type OrchestrationShellSnapshot = typeof OrchestrationShellSnapshot.Type;
+
+export const OrchestrationShellStreamEvent = Schema.Union([
+  Schema.Struct({
+    kind: Schema.Literal("project-upserted"),
+    sequence: NonNegativeInt,
+    project: OrchestrationProjectShell,
+  }),
+  Schema.Struct({
+    kind: Schema.Literal("project-removed"),
+    sequence: NonNegativeInt,
+    projectId: ProjectId,
+  }),
+  Schema.Struct({
+    kind: Schema.Literal("thread-upserted"),
+    sequence: NonNegativeInt,
+    thread: OrchestrationThreadShell,
+  }),
+  Schema.Struct({
+    kind: Schema.Literal("thread-removed"),
+    sequence: NonNegativeInt,
+    threadId: ThreadId,
+  }),
+]);
+export type OrchestrationShellStreamEvent = typeof OrchestrationShellStreamEvent.Type;
+
+export const OrchestrationShellStreamItem = Schema.Union([
+  Schema.Struct({
+    kind: Schema.Literal("snapshot"),
+    snapshot: OrchestrationShellSnapshot,
+  }),
+  OrchestrationShellStreamEvent,
+]);
+export type OrchestrationShellStreamItem = typeof OrchestrationShellStreamItem.Type;
+
+export const OrchestrationSubscribeThreadInput = Schema.Struct({
+  threadId: ThreadId,
+});
+export type OrchestrationSubscribeThreadInput = typeof OrchestrationSubscribeThreadInput.Type;
+
+export const OrchestrationThreadDetailSnapshot = Schema.Struct({
+  snapshotSequence: NonNegativeInt,
+  thread: OrchestrationThread,
+});
+export type OrchestrationThreadDetailSnapshot = typeof OrchestrationThreadDetailSnapshot.Type;
+
 export const ProjectCreateCommand = Schema.Struct({
   type: Schema.Literal("project.create"),
   commandId: CommandId,
   projectId: ProjectId,
   title: TrimmedNonEmptyString,
   workspaceRoot: TrimmedNonEmptyString,
+  createWorkspaceRootIfMissing: Schema.optional(Schema.Boolean),
   defaultModelSelection: Schema.optional(Schema.NullOr(ModelSelection)),
   createdAt: IsoDateTime,
 });
@@ -332,6 +476,7 @@ const ProjectDeleteCommand = Schema.Struct({
   type: Schema.Literal("project.delete"),
   commandId: CommandId,
   projectId: ProjectId,
+  force: Schema.optional(Schema.Boolean),
 });
 
 const ThreadCreateCommand = Schema.Struct({
@@ -955,6 +1100,18 @@ export const OrchestrationEvent = Schema.Union([
 ]);
 export type OrchestrationEvent = typeof OrchestrationEvent.Type;
 
+export const OrchestrationThreadStreamItem = Schema.Union([
+  Schema.Struct({
+    kind: Schema.Literal("snapshot"),
+    snapshot: OrchestrationThreadDetailSnapshot,
+  }),
+  Schema.Struct({
+    kind: Schema.Literal("event"),
+    event: OrchestrationEvent,
+  }),
+]);
+export type OrchestrationThreadStreamItem = typeof OrchestrationThreadStreamItem.Type;
+
 export const OrchestrationCommandReceiptStatus = Schema.Literals(["accepted", "rejected"]);
 export type OrchestrationCommandReceiptStatus = typeof OrchestrationCommandReceiptStatus.Type;
 
@@ -1019,13 +1176,11 @@ export const DispatchResult = Schema.Struct({
 });
 export type DispatchResult = typeof DispatchResult.Type;
 
-export const OrchestrationGetSnapshotInput = Schema.Struct({});
-export type OrchestrationGetSnapshotInput = typeof OrchestrationGetSnapshotInput.Type;
-const OrchestrationGetSnapshotResult = OrchestrationReadModel;
-export type OrchestrationGetSnapshotResult = typeof OrchestrationGetSnapshotResult.Type;
-
 export const OrchestrationGetTurnDiffInput = TurnCountRange.mapFields(
-  Struct.assign({ threadId: ThreadId }),
+  Struct.assign({
+    threadId: ThreadId,
+    ignoreWhitespace: Schema.optionalKey(Schema.Boolean),
+  }),
   { unsafePreserveChecks: true },
 );
 export type OrchestrationGetTurnDiffInput = typeof OrchestrationGetTurnDiffInput.Type;
@@ -1036,6 +1191,7 @@ export type OrchestrationGetTurnDiffResult = typeof OrchestrationGetTurnDiffResu
 export const OrchestrationGetFullThreadDiffInput = Schema.Struct({
   threadId: ThreadId,
   toTurnCount: NonNegativeInt,
+  ignoreWhitespace: Schema.optionalKey(Schema.Boolean),
 });
 export type OrchestrationGetFullThreadDiffInput = typeof OrchestrationGetFullThreadDiffInput.Type;
 
@@ -1051,10 +1207,6 @@ const OrchestrationReplayEventsResult = Schema.Array(OrchestrationEvent);
 export type OrchestrationReplayEventsResult = typeof OrchestrationReplayEventsResult.Type;
 
 export const OrchestrationRpcSchemas = {
-  getSnapshot: {
-    input: OrchestrationGetSnapshotInput,
-    output: OrchestrationGetSnapshotResult,
-  },
   dispatchCommand: {
     input: ClientOrchestrationCommand,
     output: DispatchResult,
@@ -1071,6 +1223,18 @@ export const OrchestrationRpcSchemas = {
     input: OrchestrationReplayEventsInput,
     output: OrchestrationReplayEventsResult,
   },
+  getArchivedShellSnapshot: {
+    input: Schema.Struct({}),
+    output: OrchestrationShellSnapshot,
+  },
+  subscribeThread: {
+    input: OrchestrationSubscribeThreadInput,
+    output: OrchestrationThreadStreamItem,
+  },
+  subscribeShell: {
+    input: Schema.Struct({}),
+    output: OrchestrationShellStreamItem,
+  },
 } as const;
 
 export class OrchestrationGetSnapshotError extends Schema.TaggedErrorClass<OrchestrationGetSnapshotError>()(
diff --git a/packages/contracts/src/project.ts b/packages/contracts/src/project.ts
index 2851120d1d4..c99cff3133e 100644
--- a/packages/contracts/src/project.ts
+++ b/packages/contracts/src/project.ts
@@ -1,5 +1,5 @@
-import { Schema } from "effect";
-import { PositiveInt, TrimmedNonEmptyString } from "./baseSchemas";
+import * as Schema from "effect/Schema";
+import { PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
 
 const PROJECT_SEARCH_ENTRIES_MAX_LIMIT = 200;
 const PROJECT_WRITE_FILE_PATH_MAX_LENGTH = 512;
diff --git a/packages/contracts/src/provider.test.ts b/packages/contracts/src/provider.test.ts
index 37469984de4..d3df41ba9f4 100644
--- a/packages/contracts/src/provider.test.ts
+++ b/packages/contracts/src/provider.test.ts
@@ -1,10 +1,24 @@
 import { describe, expect, it } from "vitest";
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 
-import { ProviderSendTurnInput, ProviderSessionStartInput } from "./provider";
+import {
+  ProviderEvent,
+  ProviderSendTurnInput,
+  ProviderSession,
+  ProviderSessionStartInput,
+} from "./provider.ts";
 
 const decodeProviderSessionStartInput = Schema.decodeUnknownSync(ProviderSessionStartInput);
 const decodeProviderSendTurnInput = Schema.decodeUnknownSync(ProviderSendTurnInput);
+const decodeProviderSession = Schema.decodeUnknownSync(ProviderSession);
+const decodeProviderEvent = Schema.decodeUnknownSync(ProviderEvent);
+
+function getOptionValue(
+  options: ReadonlyArray<{ id: string; value: unknown }> | undefined,
+  id: string,
+): unknown {
+  return options?.find((option) => option.id === id)?.value;
+}
 
 describe("ProviderSessionStartInput", () => {
   it("accepts codex-compatible payloads", () => {
@@ -15,21 +29,18 @@ describe("ProviderSessionStartInput", () => {
       modelSelection: {
         provider: "codex",
         model: "gpt-5.3-codex",
-        options: {
-          reasoningEffort: "high",
-          fastMode: true,
-        },
+        options: [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
       },
       runtimeMode: "full-access",
     });
     expect(parsed.runtimeMode).toBe("full-access");
-    expect(parsed.modelSelection?.provider).toBe("codex");
+    expect(parsed.modelSelection?.instanceId).toBe("codex");
     expect(parsed.modelSelection?.model).toBe("gpt-5.3-codex");
-    if (parsed.modelSelection?.provider !== "codex") {
-      throw new Error("Expected codex modelSelection");
-    }
-    expect(parsed.modelSelection.options?.reasoningEffort).toBe("high");
-    expect(parsed.modelSelection.options?.fastMode).toBe(true);
+    expect(getOptionValue(parsed.modelSelection?.options, "reasoningEffort")).toBe("high");
+    expect(getOptionValue(parsed.modelSelection?.options, "fastMode")).toBe(true);
   });
 
   it("rejects payloads without runtime mode", () => {
@@ -49,25 +60,58 @@ describe("ProviderSessionStartInput", () => {
       modelSelection: {
         provider: "claudeAgent",
         model: "claude-sonnet-4-6",
-        options: {
-          thinking: true,
-          effort: "max",
-          fastMode: true,
-        },
+        options: [
+          { id: "thinking", value: true },
+          { id: "effort", value: "max" },
+          { id: "fastMode", value: true },
+        ],
       },
       runtimeMode: "full-access",
     });
     expect(parsed.provider).toBe("claudeAgent");
-    expect(parsed.modelSelection?.provider).toBe("claudeAgent");
+    expect(parsed.modelSelection?.instanceId).toBe("claudeAgent");
     expect(parsed.modelSelection?.model).toBe("claude-sonnet-4-6");
-    if (parsed.modelSelection?.provider !== "claudeAgent") {
-      throw new Error("Expected claude modelSelection");
-    }
-    expect(parsed.modelSelection.options?.thinking).toBe(true);
-    expect(parsed.modelSelection.options?.effort).toBe("max");
-    expect(parsed.modelSelection.options?.fastMode).toBe(true);
+    expect(getOptionValue(parsed.modelSelection?.options, "thinking")).toBe(true);
+    expect(getOptionValue(parsed.modelSelection?.options, "effort")).toBe("max");
+    expect(getOptionValue(parsed.modelSelection?.options, "fastMode")).toBe(true);
     expect(parsed.runtimeMode).toBe("full-access");
   });
+
+  it("accepts cursor provider", () => {
+    const parsed = decodeProviderSessionStartInput({
+      threadId: "thread-1",
+      provider: "cursor",
+      cwd: "/tmp/workspace",
+      runtimeMode: "full-access",
+      modelSelection: {
+        provider: "cursor",
+        model: "composer-2",
+        options: [{ id: "fastMode", value: true }],
+      },
+    });
+    expect(parsed.provider).toBe("cursor");
+    expect(parsed.modelSelection?.instanceId).toBe("cursor");
+    expect(parsed.modelSelection?.model).toBe("composer-2");
+    expect(getOptionValue(parsed.modelSelection?.options, "fastMode")).toBe(true);
+  });
+
+  it("accepts fork-provided driver kinds as branded slugs", () => {
+    const parsed = decodeProviderSessionStartInput({
+      threadId: "thread-1",
+      provider: "ollama",
+      providerInstanceId: "ollama_local",
+      cwd: "/tmp/workspace",
+      runtimeMode: "full-access",
+      modelSelection: {
+        instanceId: "ollama_local",
+        model: "llama3.3",
+      },
+    });
+
+    expect(parsed.provider).toBe("ollama");
+    expect(parsed.providerInstanceId).toBe("ollama_local");
+    expect(parsed.modelSelection?.instanceId).toBe("ollama_local");
+  });
 });
 
 describe("ProviderSendTurnInput", () => {
@@ -77,20 +121,17 @@ describe("ProviderSendTurnInput", () => {
       modelSelection: {
         provider: "codex",
         model: "gpt-5.3-codex",
-        options: {
-          reasoningEffort: "xhigh",
-          fastMode: true,
-        },
+        options: [
+          { id: "reasoningEffort", value: "xhigh" },
+          { id: "fastMode", value: true },
+        ],
       },
     });
 
-    expect(parsed.modelSelection?.provider).toBe("codex");
+    expect(parsed.modelSelection?.instanceId).toBe("codex");
     expect(parsed.modelSelection?.model).toBe("gpt-5.3-codex");
-    if (parsed.modelSelection?.provider !== "codex") {
-      throw new Error("Expected codex modelSelection");
-    }
-    expect(parsed.modelSelection.options?.reasoningEffort).toBe("xhigh");
-    expect(parsed.modelSelection.options?.fastMode).toBe(true);
+    expect(getOptionValue(parsed.modelSelection?.options, "reasoningEffort")).toBe("xhigh");
+    expect(getOptionValue(parsed.modelSelection?.options, "fastMode")).toBe(true);
   });
 
   it("accepts claude modelSelection including ultrathink", () => {
@@ -99,18 +140,89 @@ describe("ProviderSendTurnInput", () => {
       modelSelection: {
         provider: "claudeAgent",
         model: "claude-sonnet-4-6",
-        options: {
-          effort: "ultrathink",
-          fastMode: true,
-        },
+        options: [
+          { id: "effort", value: "ultrathink" },
+          { id: "fastMode", value: true },
+        ],
       },
     });
 
-    expect(parsed.modelSelection?.provider).toBe("claudeAgent");
-    if (parsed.modelSelection?.provider !== "claudeAgent") {
-      throw new Error("Expected claude modelSelection");
-    }
-    expect(parsed.modelSelection.options?.effort).toBe("ultrathink");
-    expect(parsed.modelSelection.options?.fastMode).toBe(true);
+    expect(parsed.modelSelection?.instanceId).toBe("claudeAgent");
+    expect(getOptionValue(parsed.modelSelection?.options, "effort")).toBe("ultrathink");
+    expect(getOptionValue(parsed.modelSelection?.options, "fastMode")).toBe(true);
+  });
+});
+
+describe("providerInstanceId routing key (slice-2 invariant)", () => {
+  it("decodes a ProviderSessionStartInput without providerInstanceId (legacy producer)", () => {
+    const parsed = decodeProviderSessionStartInput({
+      threadId: "thread-1",
+      provider: "codex",
+      runtimeMode: "full-access",
+    });
+    expect(parsed.providerInstanceId).toBeUndefined();
+  });
+
+  it("decodes a ProviderSessionStartInput with providerInstanceId (post-migration producer)", () => {
+    const parsed = decodeProviderSessionStartInput({
+      threadId: "thread-1",
+      provider: "codex",
+      providerInstanceId: "codex_personal",
+      runtimeMode: "full-access",
+    });
+    expect(parsed.providerInstanceId).toBe("codex_personal");
+  });
+
+  it("propagates providerInstanceId through ProviderSession decode", () => {
+    const session = decodeProviderSession({
+      provider: "codex",
+      providerInstanceId: "codex_work",
+      status: "ready",
+      runtimeMode: "full-access",
+      threadId: "thread-1",
+      createdAt: "2024-01-01T00:00:00Z",
+      updatedAt: "2024-01-01T00:00:00Z",
+    });
+    expect(session.providerInstanceId).toBe("codex_work");
+  });
+
+  it("decodes ProviderSession for fork-provided driver kinds", () => {
+    const session = decodeProviderSession({
+      provider: "ollama",
+      providerInstanceId: "ollama_local",
+      status: "ready",
+      runtimeMode: "full-access",
+      threadId: "thread-1",
+      createdAt: "2024-01-01T00:00:00Z",
+      updatedAt: "2024-01-01T00:00:00Z",
+    });
+
+    expect(session.provider).toBe("ollama");
+    expect(session.providerInstanceId).toBe("ollama_local");
+  });
+
+  it("decodes a ProviderEvent carrying both legacy provider and new instance routing", () => {
+    const event = decodeProviderEvent({
+      id: "event-1",
+      kind: "notification",
+      provider: "codex",
+      providerInstanceId: "codex_personal",
+      threadId: "thread-1",
+      createdAt: "2024-01-01T00:00:00Z",
+      method: "session.created",
+    });
+    expect(event.provider).toBe("codex");
+    expect(event.providerInstanceId).toBe("codex_personal");
+  });
+
+  it("rejects providerInstanceId values that fail the slug pattern (defense in depth)", () => {
+    expect(() =>
+      decodeProviderSessionStartInput({
+        threadId: "thread-1",
+        provider: "codex",
+        providerInstanceId: "1bad",
+        runtimeMode: "full-access",
+      }),
+    ).toThrow();
   });
 });
diff --git a/packages/contracts/src/provider.ts b/packages/contracts/src/provider.ts
index 16102920d71..94fb007a7bc 100644
--- a/packages/contracts/src/provider.ts
+++ b/packages/contracts/src/provider.ts
@@ -1,5 +1,5 @@
-import { Schema } from "effect";
-import { TrimmedNonEmptyString } from "./baseSchemas";
+import * as Schema from "effect/Schema";
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
 import {
   ApprovalRequestId,
   EventId,
@@ -7,7 +7,7 @@ import {
   ProviderItemId,
   ThreadId,
   TurnId,
-} from "./baseSchemas";
+} from "./baseSchemas.ts";
 import {
   ChatAttachment,
   ModelSelection,
@@ -16,12 +16,12 @@ import {
   ProviderApprovalDecision,
   ProviderApprovalPolicy,
   ProviderInteractionMode,
-  ProviderKind,
   ProviderRequestKind,
   ProviderSandboxMode,
   ProviderUserInputAnswers,
   RuntimeMode,
-} from "./orchestration";
+} from "./orchestration.ts";
+import { ProviderInstanceId, ProviderDriverKind } from "./providerInstance.ts";
 
 const ProviderSessionStatus = Schema.Literals([
   "connecting",
@@ -32,7 +32,11 @@ const ProviderSessionStatus = Schema.Literals([
 ]);
 
 export const ProviderSession = Schema.Struct({
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
+  // Optional during the driver/instance migration. Once every producer
+  // populates it (post-slice-4), routing flips to instance-id-only and the
+  // legacy `provider` field is removed.
+  providerInstanceId: Schema.optional(ProviderInstanceId),
   status: ProviderSessionStatus,
   runtimeMode: RuntimeMode,
   cwd: Schema.optional(TrimmedNonEmptyString),
@@ -48,7 +52,9 @@ export type ProviderSession = typeof ProviderSession.Type;
 
 export const ProviderSessionStartInput = Schema.Struct({
   threadId: ThreadId,
-  provider: Schema.optional(ProviderKind),
+  provider: Schema.optional(ProviderDriverKind),
+  // See ProviderSession for the migration story.
+  providerInstanceId: Schema.optional(ProviderInstanceId),
   cwd: Schema.optional(TrimmedNonEmptyString),
   modelSelection: Schema.optional(ModelSelection),
   resumeCursor: Schema.optional(Schema.Unknown),
@@ -108,7 +114,9 @@ const ProviderEventKind = Schema.Literals(["session", "notification", "request",
 export const ProviderEvent = Schema.Struct({
   id: EventId,
   kind: ProviderEventKind,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
+  // See ProviderSession for the migration story.
+  providerInstanceId: Schema.optional(ProviderInstanceId),
   threadId: ThreadId,
   createdAt: IsoDateTime,
   method: TrimmedNonEmptyString,
diff --git a/packages/contracts/src/providerInstance.test.ts b/packages/contracts/src/providerInstance.test.ts
new file mode 100644
index 00000000000..272e4a70ef2
--- /dev/null
+++ b/packages/contracts/src/providerInstance.test.ts
@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+import * as Schema from "effect/Schema";
+
+import {
+  ProviderDriverKind,
+  ProviderInstanceConfig,
+  ProviderInstanceConfigMap,
+  ProviderInstanceId,
+  ProviderInstanceRef,
+} from "./providerInstance.ts";
+
+const decodeProviderDriverKind = Schema.decodeUnknownSync(ProviderDriverKind);
+const decodeProviderInstanceId = Schema.decodeUnknownSync(ProviderInstanceId);
+const decodeProviderInstanceRef = Schema.decodeUnknownSync(ProviderInstanceRef);
+const decodeProviderInstanceConfig = Schema.decodeUnknownSync(ProviderInstanceConfig);
+const decodeProviderInstanceConfigMap = Schema.decodeUnknownSync(ProviderInstanceConfigMap);
+
+describe("provider slug validation (shared by driver + instance ids)", () => {
+  const cases = [
+    { schemaName: "ProviderInstanceId", decode: decodeProviderInstanceId },
+    { schemaName: "ProviderDriverKind", decode: decodeProviderDriverKind },
+  ] as const;
+
+  for (const { schemaName, decode } of cases) {
+    describe(schemaName, () => {
+      it.each(["codex", "codex_personal", "codex-work", "claudeAgent", "x", "abc123", "ollama"])(
+        "accepts %s",
+        (id) => {
+          expect(decode(id)).toBe(id);
+        },
+      );
+
+      it.each([
+        ["empty string", ""],
+        ["leading digit", "1codex"],
+        ["leading dash", "-codex"],
+        ["leading underscore", "_codex"],
+        ["whitespace inside", "codex personal"],
+        ["dot inside", "codex.personal"],
+        ["slash inside", "codex/personal"],
+      ])("rejects %s", (_label, value) => {
+        expect(() => decode(value)).toThrow();
+      });
+
+      it("trims surrounding whitespace before validating", () => {
+        expect(decode("  codex_work  ")).toBe("codex_work");
+      });
+
+      it("rejects ids longer than 64 characters", () => {
+        const tooLong = "a".repeat(65);
+        expect(() => decode(tooLong)).toThrow();
+        const justRight = "a".repeat(64);
+        expect(decode(justRight)).toBe(justRight);
+      });
+    });
+  }
+});
+
+describe("ProviderInstanceRef", () => {
+  it("decodes a driver ref", () => {
+    const ref = decodeProviderInstanceRef({
+      instanceId: "codex_work",
+      driver: "codex",
+    });
+    expect(ref.instanceId).toBe("codex_work");
+    expect(ref.driver).toBe("codex");
+  });
+
+  it("decodes a fork-defined driver ref without complaint", () => {
+    const ref = decodeProviderInstanceRef({
+      instanceId: "ollama_local",
+      driver: "ollama",
+    });
+    expect(ref.instanceId).toBe("ollama_local");
+    expect(ref.driver).toBe("ollama");
+  });
+
+  it("rejects refs whose driver field is not a valid slug", () => {
+    expect(() =>
+      decodeProviderInstanceRef({
+        instanceId: "codex",
+        driver: "1nope",
+      }),
+    ).toThrow();
+  });
+});
+
+describe("ProviderInstanceConfig", () => {
+  it("accepts a minimal config envelope for a driver", () => {
+    const decoded = decodeProviderInstanceConfig({ driver: "codex" });
+    expect(decoded.driver).toBe("codex");
+    expect(decoded.displayName).toBeUndefined();
+    expect(decoded.enabled).toBeUndefined();
+    expect(decoded.config).toBeUndefined();
+  });
+
+  it("preserves driver-opaque config payloads verbatim", () => {
+    const opaqueConfig = { homePath: "~/.codex_personal", binaryPath: "codex" };
+    const decoded = decodeProviderInstanceConfig({
+      driver: "codex",
+      displayName: "Codex (personal)",
+      accentColor: "#dc2626",
+      enabled: true,
+      config: opaqueConfig,
+    });
+    expect(decoded.displayName).toBe("Codex (personal)");
+    expect(decoded.accentColor).toBe("#dc2626");
+    expect(decoded.enabled).toBe(true);
+    expect(decoded.config).toEqual(opaqueConfig);
+  });
+
+  it("trims provider instance envelope fields", () => {
+    const decoded = decodeProviderInstanceConfig({
+      driver: "  codex  ",
+      displayName: "  Codex Personal  ",
+      accentColor: "  #dc2626  ",
+      environment: [{ name: "  OPENROUTER_API_KEY  ", value: "  sk-or-test  " }],
+    });
+
+    expect(decoded).toMatchObject({
+      driver: "codex",
+      displayName: "Codex Personal",
+      accentColor: "#dc2626",
+      environment: [{ name: "OPENROUTER_API_KEY", value: "  sk-or-test  " }],
+    });
+  });
+
+  it("decodes generic environment variables on the instance envelope", () => {
+    const decoded = decodeProviderInstanceConfig({
+      driver: "claudeAgent",
+      environment: [
+        { name: "ANTHROPIC_BASE_URL", value: "https://openrouter.ai/api", sensitive: false },
+        { name: "OPENROUTER_API_KEY", value: "sk-or-test", sensitive: true },
+        { name: "ANTHROPIC_API_KEY", value: "", sensitive: false },
+      ],
+    });
+
+    expect(decoded.environment).toEqual([
+      { name: "ANTHROPIC_BASE_URL", value: "https://openrouter.ai/api", sensitive: false },
+      { name: "OPENROUTER_API_KEY", value: "sk-or-test", sensitive: true },
+      { name: "ANTHROPIC_API_KEY", value: "", sensitive: false },
+    ]);
+  });
+
+  it("rejects invalid environment variable names", () => {
+    expect(() =>
+      decodeProviderInstanceConfig({
+        driver: "codex",
+        environment: [{ name: "HAS-DASH", value: "x", sensitive: false }],
+      }),
+    ).toThrow();
+  });
+
+  it("decodes envelopes that name an unknown driver and preserves their config opaquely", () => {
+    const opaqueConfig = { someUnknownKnob: 42, model: "llama3" };
+    const decoded = decodeProviderInstanceConfig({
+      driver: "ollama",
+      displayName: "Ollama",
+      enabled: true,
+      config: opaqueConfig,
+    });
+    expect(decoded.driver).toBe("ollama");
+    expect(decoded.config).toEqual(opaqueConfig);
+  });
+
+  it("rejects a blank displayName (must be trimmed non-empty)", () => {
+    expect(() => decodeProviderInstanceConfig({ driver: "codex", displayName: "   " })).toThrow();
+  });
+
+  it("rejects driver values that do not satisfy the slug pattern", () => {
+    expect(() => decodeProviderInstanceConfig({ driver: "" })).toThrow();
+    expect(() => decodeProviderInstanceConfig({ driver: "has spaces" })).toThrow();
+  });
+});
+
+describe("ProviderInstanceConfigMap", () => {
+  it("decodes a multi-instance map mixing first-party and fork drivers", () => {
+    const decoded = decodeProviderInstanceConfigMap({
+      codex_personal: {
+        driver: "codex",
+        displayName: "Codex (personal)",
+        config: { homePath: "~/.codex_personal" },
+      },
+      codex_work: {
+        driver: "codex",
+        config: { homePath: "~/.codex_work" },
+      },
+      claudeAgent: { driver: "claudeAgent" },
+      ollama_local: { driver: "ollama", config: { endpoint: "http://localhost:11434" } },
+    });
+    expect(new Set(Object.keys(decoded))).toEqual(
+      new Set(["claudeAgent", "codex_personal", "codex_work", "ollama_local"]),
+    );
+    expect(decoded[ProviderInstanceId.make("codex_personal")]?.driver).toBe("codex");
+    expect(decoded[ProviderInstanceId.make("codex_work")]?.config).toEqual({
+      homePath: "~/.codex_work",
+    });
+    expect(decoded[ProviderInstanceId.make("ollama_local")]?.driver).toBe("ollama");
+  });
+
+  it("rejects keys that fail the instance-id pattern", () => {
+    expect(() =>
+      decodeProviderInstanceConfigMap({
+        "1codex": { driver: "codex" },
+      }),
+    ).toThrow();
+  });
+});
diff --git a/packages/contracts/src/providerInstance.ts b/packages/contracts/src/providerInstance.ts
new file mode 100644
index 00000000000..2a9fc9ed0d1
--- /dev/null
+++ b/packages/contracts/src/providerInstance.ts
@@ -0,0 +1,149 @@
+/**
+ * Provider-instance contracts.
+ *
+ * Splits the historical "provider kind" concept into two:
+ *
+ *   - `ProviderDriverKind` is the implementation kind selector (e.g. codex,
+ *     claudeAgent, a fork's `ollama`, …). It picks which driver package
+ *     handles the protocol, the probe, the adapter, and text generation.
+ *
+ *   - `ProviderInstanceId` is the routing key (a user-defined slug).
+ *     Threads, sessions, runtime events, and persisted bindings reference
+ *     instance ids — never driver kinds — so a user can configure multiple
+ *     instances of the same driver (e.g. `codex_personal` + `codex_work`),
+ *     each with independent driver-specific configuration.
+ *
+ * Forward/backward compatibility invariant
+ * ----------------------------------------
+ * `ProviderDriverKind` is intentionally an **open** branded slug, not a closed
+ * literal union. The server hosts forks, ships in PRs that add drivers, and
+ * users frequently roll between branches and forks. Any of those paths can
+ * leave `ServerSettings`, persisted thread state, or session bindings
+ * referencing a driver that the currently-running build does not know about.
+ *
+ * The rule: parsing any of those payloads must always succeed, and the
+ * runtime is responsible for marking the unknown driver/instance as
+ * "unavailable" rather than crashing. Built-in drivers shipped by the core
+ * product happens to register in a given build is not part of the contract
+ * layer. Driver availability is discovered through the runtime registry.
+ *
+ * Driver-specific configuration is similarly opaque at the contracts layer:
+ * drivers live in (or will be extracted to) their own packages and own their
+ * config schemas. The contracts package only knows the envelope.
+ *
+ * @module providerInstance
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
+
+const PROVIDER_SLUG_MAX_CHARS = 64;
+/**
+ * Slug pattern shared by driver kinds and instance ids — letters, digits,
+ * dashes, underscores. The first character must be a letter so slugs remain
+ * JS-identifier friendly when used as object keys, log fields, or telemetry
+ * attributes. Mixed case is permitted so historical driver kinds (e.g.
+ * `claudeAgent`) can be used verbatim during the migration and so external
+ * fork authors retain reasonable freedom.
+ */
+const PROVIDER_SLUG_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+const ENVIRONMENT_VARIABLE_NAME_MAX_CHARS = 128;
+const ENVIRONMENT_VARIABLE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+const slugSchema = TrimmedNonEmptyString.check(
+  Schema.isMaxLength(PROVIDER_SLUG_MAX_CHARS),
+  Schema.isPattern(PROVIDER_SLUG_PATTERN),
+);
+
+/**
+ * `ProviderDriverKind` — open branded slug naming a driver implementation.
+ *
+ * Constraints (validated at the schema layer):
+ *   - starts with a letter
+ *   - only letters, digits, `-`, `_` after the first char
+ *   - 1..64 characters
+ *
+ * Notably **not** validated: that the driver is one we know how to load.
+ * That check belongs to the runtime registry, which downgrades unknown
+ * drivers gracefully (see module docs).
+ */
+export const ProviderDriverKind = slugSchema.pipe(Schema.brand("ProviderDriverKind"));
+export type ProviderDriverKind = typeof ProviderDriverKind.Type;
+
+const isProviderDriverKindValue = Schema.is(ProviderDriverKind);
+export const isProviderDriverKind = (value: unknown): value is ProviderDriverKind =>
+  isProviderDriverKindValue(value);
+
+/**
+ * `ProviderInstanceId` — user-defined routing key for a configured provider
+ * instance. Same slug rules as `ProviderDriverKind`; branded separately so the
+ * type system cannot confuse the two.
+ */
+export const ProviderInstanceId = slugSchema.pipe(Schema.brand("ProviderInstanceId"));
+export type ProviderInstanceId = typeof ProviderInstanceId.Type;
+
+/**
+ * Lightweight reference identifying which driver implements an instance.
+ * Carried alongside `ProviderInstanceId` on wire shapes so consumers can
+ * branch on driver behavior (icons, capabilities, presentation) without
+ * having to look up the instance in the registry.
+ */
+export const ProviderInstanceRef = Schema.Struct({
+  instanceId: ProviderInstanceId,
+  driver: ProviderDriverKind,
+});
+export type ProviderInstanceRef = typeof ProviderInstanceRef.Type;
+
+export const ProviderInstanceEnvironmentVariableName = TrimmedNonEmptyString.check(
+  Schema.isMaxLength(ENVIRONMENT_VARIABLE_NAME_MAX_CHARS),
+  Schema.isPattern(ENVIRONMENT_VARIABLE_NAME_PATTERN),
+);
+export type ProviderInstanceEnvironmentVariableName =
+  typeof ProviderInstanceEnvironmentVariableName.Type;
+
+export const ProviderInstanceEnvironmentVariable = Schema.Struct({
+  name: ProviderInstanceEnvironmentVariableName,
+  value: Schema.String.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
+  sensitive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
+  valueRedacted: Schema.optionalKey(Schema.Boolean),
+});
+export type ProviderInstanceEnvironmentVariable = typeof ProviderInstanceEnvironmentVariable.Type;
+
+export const ProviderInstanceEnvironment = Schema.Array(ProviderInstanceEnvironmentVariable);
+export type ProviderInstanceEnvironment = typeof ProviderInstanceEnvironment.Type;
+
+/**
+ * Envelope shape for a provider instance configuration in `ServerSettings`.
+ *
+ * `driver` is intentionally accepted as any well-formed slug (see module
+ * docs). The driver-specific config payload is left as `Schema.Unknown`;
+ * each driver registers its own decoder with the runtime registry, and
+ * envelopes for unknown drivers are preserved verbatim so they round-trip
+ * across version changes without data loss.
+ */
+export const ProviderInstanceConfig = Schema.Struct({
+  driver: ProviderDriverKind,
+  displayName: Schema.optional(TrimmedNonEmptyString),
+  accentColor: Schema.optional(TrimmedNonEmptyString),
+  environment: Schema.optionalKey(ProviderInstanceEnvironment),
+  enabled: Schema.optionalKey(Schema.Boolean),
+  config: Schema.optionalKey(Schema.Unknown),
+});
+export type ProviderInstanceConfig = typeof ProviderInstanceConfig.Type;
+
+/**
+ * Map shape for `ServerSettings.providerInstances`. Keyed by
+ * `ProviderInstanceId`, values are envelopes the registry feeds to drivers.
+ */
+export const ProviderInstanceConfigMap = Schema.Record(ProviderInstanceId, ProviderInstanceConfig);
+export type ProviderInstanceConfigMap = typeof ProviderInstanceConfigMap.Type;
+
+/**
+ * Construct the canonical `ProviderInstanceId` used as a back-compat default
+ * for a built-in driver. The legacy single-instance-per-driver world used
+ * the driver kind itself as the instance id; preserving that mapping keeps
+ * existing persisted threads, bindings, and cache files routable across the
+ * migration without rewriting their stored selection payloads.
+ */
+export const defaultInstanceIdForDriver = (driver: ProviderDriverKind): ProviderInstanceId =>
+  ProviderInstanceId.make(driver);
diff --git a/packages/contracts/src/providerRuntime.test.ts b/packages/contracts/src/providerRuntime.test.ts
index 9d9c395c3d5..587c1879454 100644
--- a/packages/contracts/src/providerRuntime.test.ts
+++ b/packages/contracts/src/providerRuntime.test.ts
@@ -1,11 +1,28 @@
 import { describe, expect, it } from "vitest";
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 
-import { ProviderRuntimeEvent } from "./providerRuntime";
+import { ProviderRuntimeEvent } from "./providerRuntime.ts";
 
 const decodeRuntimeEvent = Schema.decodeUnknownSync(ProviderRuntimeEvent);
 
 describe("ProviderRuntimeEvent", () => {
+  it("accepts fork-provided driver kinds as branded slugs", () => {
+    const parsed = decodeRuntimeEvent({
+      type: "session.started",
+      eventId: "event-ollama-session",
+      provider: "ollama",
+      providerInstanceId: "ollama_local",
+      createdAt: "2026-02-28T00:00:00.000Z",
+      threadId: "thread-1",
+      payload: {
+        message: "started",
+      },
+    });
+
+    expect(parsed.provider).toBe("ollama");
+    expect(parsed.providerInstanceId).toBe("ollama_local");
+  });
+
   it("decodes turn.plan.updated for plan rendering", () => {
     const parsed = decodeRuntimeEvent({
       type: "turn.plan.updated",
diff --git a/packages/contracts/src/providerRuntime.ts b/packages/contracts/src/providerRuntime.ts
index 6b03d70d56c..5032dc4eb41 100644
--- a/packages/contracts/src/providerRuntime.ts
+++ b/packages/contracts/src/providerRuntime.ts
@@ -1,4 +1,5 @@
-import { Effect, Schema } from "effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
 import {
   EventId,
   IsoDateTime,
@@ -11,19 +12,22 @@ import {
   ThreadId,
   TrimmedNonEmptyString,
   TurnId,
-} from "./baseSchemas";
-import { ProviderKind } from "./orchestration";
+} from "./baseSchemas.ts";
+import { ProviderInstanceId, ProviderDriverKind } from "./providerInstance.ts";
 
 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
 const UnknownRecordSchema = Schema.Record(Schema.String, Schema.Unknown);
 
-const RuntimeEventRawSource = Schema.Literals([
-  "codex.app-server.notification",
-  "codex.app-server.request",
-  "codex.eventmsg",
-  "claude.sdk.message",
-  "claude.sdk.permission",
-  "codex.sdk.thread-event",
+const RuntimeEventRawSource = Schema.Union([
+  Schema.Literal("codex.app-server.notification"),
+  Schema.Literal("codex.app-server.request"),
+  Schema.Literal("codex.eventmsg"),
+  Schema.Literal("claude.sdk.message"),
+  Schema.Literal("claude.sdk.permission"),
+  Schema.Literal("codex.sdk.thread-event"),
+  Schema.Literal("opencode.sdk.event"),
+  Schema.Literal("acp.jsonrpc"),
+  Schema.TemplateLiteral(["acp.", Schema.String, ".extension"]),
 ]);
 export type RuntimeEventRawSource = typeof RuntimeEventRawSource.Type;
 
@@ -242,7 +246,11 @@ const RuntimeErrorType = Schema.Literal("runtime.error");
 
 const ProviderRuntimeEventBase = Schema.Struct({
   eventId: EventId,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
+  // Optional during the driver/instance migration. See providerInstance.ts
+  // for the routing-key-vs-driver-id distinction. Once every emitter
+  // populates it (post-slice-4), routing flips to instance-id-only.
+  providerInstanceId: Schema.optional(ProviderInstanceId),
   threadId: ThreadId,
   createdAt: IsoDateTime,
   turnId: Schema.optional(TurnId),
diff --git a/packages/contracts/src/remoteAccess.ts b/packages/contracts/src/remoteAccess.ts
new file mode 100644
index 00000000000..e3de3c29e12
--- /dev/null
+++ b/packages/contracts/src/remoteAccess.ts
@@ -0,0 +1,68 @@
+import * as Schema from "effect/Schema";
+
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
+
+export const AdvertisedEndpointProviderKind = Schema.Literals([
+  "core",
+  "private-network",
+  "tunnel",
+  "manual",
+]);
+export type AdvertisedEndpointProviderKind = typeof AdvertisedEndpointProviderKind.Type;
+
+export const AdvertisedEndpointReachability = Schema.Literals([
+  "loopback",
+  "lan",
+  "private-network",
+  "public",
+]);
+export type AdvertisedEndpointReachability = typeof AdvertisedEndpointReachability.Type;
+
+export const AdvertisedEndpointHostedHttpsCompatibility = Schema.Literals([
+  "compatible",
+  "mixed-content-blocked",
+  "requires-configuration",
+  "unknown",
+]);
+export type AdvertisedEndpointHostedHttpsCompatibility =
+  typeof AdvertisedEndpointHostedHttpsCompatibility.Type;
+
+export const AdvertisedEndpointStatus = Schema.Literals(["available", "unavailable", "unknown"]);
+export type AdvertisedEndpointStatus = typeof AdvertisedEndpointStatus.Type;
+
+export const AdvertisedEndpointSource = Schema.Literals([
+  "desktop-core",
+  "desktop-addon",
+  "server",
+  "user",
+]);
+export type AdvertisedEndpointSource = typeof AdvertisedEndpointSource.Type;
+
+export const AdvertisedEndpointProvider = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  label: TrimmedNonEmptyString,
+  kind: AdvertisedEndpointProviderKind,
+  isAddon: Schema.Boolean,
+});
+export type AdvertisedEndpointProvider = typeof AdvertisedEndpointProvider.Type;
+
+export const AdvertisedEndpointCompatibility = Schema.Struct({
+  hostedHttpsApp: AdvertisedEndpointHostedHttpsCompatibility,
+  desktopApp: Schema.Literals(["compatible", "unknown"]),
+});
+export type AdvertisedEndpointCompatibility = typeof AdvertisedEndpointCompatibility.Type;
+
+export const AdvertisedEndpoint = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  label: TrimmedNonEmptyString,
+  provider: AdvertisedEndpointProvider,
+  httpBaseUrl: TrimmedNonEmptyString,
+  wsBaseUrl: TrimmedNonEmptyString,
+  reachability: AdvertisedEndpointReachability,
+  compatibility: AdvertisedEndpointCompatibility,
+  source: AdvertisedEndpointSource,
+  status: AdvertisedEndpointStatus,
+  isDefault: Schema.optional(Schema.Boolean),
+  description: Schema.optional(TrimmedNonEmptyString),
+});
+export type AdvertisedEndpoint = typeof AdvertisedEndpoint.Type;
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index f47b427bcd6..d4c0f85665d 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -1,50 +1,54 @@
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 import * as Rpc from "effect/unstable/rpc/Rpc";
 import * as RpcGroup from "effect/unstable/rpc/RpcGroup";
 
-import { OpenError, OpenInEditorInput } from "./editor";
-import { AuthAccessStreamEvent } from "./auth";
+import { ExternalLauncherError, LaunchEditorInput } from "./editor.ts";
+import { AuthAccessStreamEvent } from "./auth.ts";
+import {
+  FilesystemBrowseInput,
+  FilesystemBrowseResult,
+  FilesystemBrowseError,
+} from "./filesystem.ts";
 import {
   GitActionProgressEvent,
-  GitCheckoutInput,
-  GitCheckoutResult,
+  VcsSwitchRefInput,
+  VcsSwitchRefResult,
   GitCommandError,
-  GitCreateBranchInput,
-  GitCreateBranchResult,
-  GitCreateWorktreeInput,
-  GitCreateWorktreeResult,
-  GitInitInput,
-  GitListBranchesInput,
-  GitListBranchesResult,
+  VcsCreateRefInput,
+  VcsCreateRefResult,
+  VcsCreateWorktreeInput,
+  VcsCreateWorktreeResult,
+  VcsInitInput,
+  VcsListRefsInput,
+  VcsListRefsResult,
   GitManagerServiceError,
   GitPreparePullRequestThreadInput,
   GitPreparePullRequestThreadResult,
-  GitPullInput,
+  VcsPullInput,
   GitPullRequestRefInput,
-  GitPullResult,
-  GitRemoveWorktreeInput,
+  VcsPullResult,
+  VcsRemoveWorktreeInput,
   GitResolvePullRequestResult,
   GitRunStackedActionInput,
-  GitStatusInput,
-  GitStatusResult,
-  GitStatusStreamEvent,
-} from "./git";
-import { KeybindingsConfigError } from "./keybindings";
+  VcsStatusInput,
+  VcsStatusResult,
+  VcsStatusStreamEvent,
+} from "./git.ts";
+import { KeybindingsConfigError } from "./keybindings.ts";
 import {
   ClientOrchestrationCommand,
-  OrchestrationEvent,
   ORCHESTRATION_WS_METHODS,
   OrchestrationDispatchCommandError,
   OrchestrationGetFullThreadDiffError,
   OrchestrationGetFullThreadDiffInput,
   OrchestrationGetSnapshotError,
-  OrchestrationGetSnapshotInput,
   OrchestrationGetTurnDiffError,
   OrchestrationGetTurnDiffInput,
   OrchestrationReplayEventsError,
   OrchestrationReplayEventsInput,
   OrchestrationRpcSchemas,
-} from "./orchestration";
+} from "./orchestration.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
 import {
   ProjectSearchEntriesError,
   ProjectSearchEntriesInput,
@@ -52,7 +56,7 @@ import {
   ProjectWriteFileError,
   ProjectWriteFileInput,
   ProjectWriteFileResult,
-} from "./project";
+} from "./project.ts";
 import {
   TerminalClearInput,
   TerminalCloseInput,
@@ -63,16 +67,37 @@ import {
   TerminalRestartInput,
   TerminalSessionSnapshot,
   TerminalWriteInput,
-} from "./terminal";
+} from "./terminal.ts";
 import {
   ServerConfigStreamEvent,
   ServerConfig,
+  ServerProviderUpdateError,
+  ServerProviderUpdateInput,
   ServerLifecycleStreamEvent,
+  ServerRemoveKeybindingInput,
+  ServerRemoveKeybindingResult,
   ServerProviderUpdatedPayload,
+  ServerTraceDiagnosticsResult,
+  ServerProcessDiagnosticsResult,
+  ServerProcessResourceHistoryInput,
+  ServerProcessResourceHistoryResult,
+  ServerSignalProcessInput,
+  ServerSignalProcessResult,
   ServerUpsertKeybindingInput,
   ServerUpsertKeybindingResult,
-} from "./server";
-import { ServerSettings, ServerSettingsError, ServerSettingsPatch } from "./settings";
+} from "./server.ts";
+import { ServerSettings, ServerSettingsError, ServerSettingsPatch } from "./settings.ts";
+import {
+  SourceControlCloneRepositoryInput,
+  SourceControlCloneRepositoryResult,
+  SourceControlDiscoveryResult,
+  SourceControlPublishRepositoryInput,
+  SourceControlPublishRepositoryResult,
+  SourceControlRepositoryError,
+  SourceControlRepositoryInfo,
+  SourceControlRepositoryLookupInput,
+} from "./sourceControl.ts";
+import { VcsError } from "./vcs.ts";
 
 export const WS_METHODS = {
   // Project registry methods
@@ -85,16 +110,21 @@ export const WS_METHODS = {
   // Shell methods
   shellOpenInEditor: "shell.openInEditor",
 
-  // Git methods
-  gitPull: "git.pull",
-  gitRefreshStatus: "git.refreshStatus",
+  // Filesystem methods
+  filesystemBrowse: "filesystem.browse",
+
+  // VCS methods
+  vcsPull: "vcs.pull",
+  vcsRefreshStatus: "vcs.refreshStatus",
+  vcsListRefs: "vcs.listRefs",
+  vcsCreateWorktree: "vcs.createWorktree",
+  vcsRemoveWorktree: "vcs.removeWorktree",
+  vcsCreateRef: "vcs.createRef",
+  vcsSwitchRef: "vcs.switchRef",
+  vcsInit: "vcs.init",
+
+  // Git workflow methods
   gitRunStackedAction: "git.runStackedAction",
-  gitListBranches: "git.listBranches",
-  gitCreateWorktree: "git.createWorktree",
-  gitRemoveWorktree: "git.removeWorktree",
-  gitCreateBranch: "git.createBranch",
-  gitCheckout: "git.checkout",
-  gitInit: "git.init",
   gitResolvePullRequest: "git.resolvePullRequest",
   gitPreparePullRequestThread: "git.preparePullRequestThread",
 
@@ -109,13 +139,24 @@ export const WS_METHODS = {
   // Server meta
   serverGetConfig: "server.getConfig",
   serverRefreshProviders: "server.refreshProviders",
+  serverUpdateProvider: "server.updateProvider",
   serverUpsertKeybinding: "server.upsertKeybinding",
+  serverRemoveKeybinding: "server.removeKeybinding",
   serverGetSettings: "server.getSettings",
   serverUpdateSettings: "server.updateSettings",
+  serverDiscoverSourceControl: "server.discoverSourceControl",
+  serverGetTraceDiagnostics: "server.getTraceDiagnostics",
+  serverGetProcessDiagnostics: "server.getProcessDiagnostics",
+  serverGetProcessResourceHistory: "server.getProcessResourceHistory",
+  serverSignalProcess: "server.signalProcess",
+
+  // Source control methods
+  sourceControlLookupRepository: "sourceControl.lookupRepository",
+  sourceControlCloneRepository: "sourceControl.cloneRepository",
+  sourceControlPublishRepository: "sourceControl.publishRepository",
 
   // Streaming subscriptions
-  subscribeGitStatus: "subscribeGitStatus",
-  subscribeOrchestrationDomainEvents: "subscribeOrchestrationDomainEvents",
+  subscribeVcsStatus: "subscribeVcsStatus",
   subscribeTerminalEvents: "subscribeTerminalEvents",
   subscribeServerConfig: "subscribeServerConfig",
   subscribeServerLifecycle: "subscribeServerLifecycle",
@@ -128,6 +169,12 @@ export const WsServerUpsertKeybindingRpc = Rpc.make(WS_METHODS.serverUpsertKeybi
   error: KeybindingsConfigError,
 });
 
+export const WsServerRemoveKeybindingRpc = Rpc.make(WS_METHODS.serverRemoveKeybinding, {
+  payload: ServerRemoveKeybindingInput,
+  success: ServerRemoveKeybindingResult,
+  error: KeybindingsConfigError,
+});
+
 export const WsServerGetConfigRpc = Rpc.make(WS_METHODS.serverGetConfig, {
   payload: Schema.Struct({}),
   success: ServerConfig,
@@ -135,8 +182,22 @@ export const WsServerGetConfigRpc = Rpc.make(WS_METHODS.serverGetConfig, {
 });
 
 export const WsServerRefreshProvidersRpc = Rpc.make(WS_METHODS.serverRefreshProviders, {
-  payload: Schema.Struct({}),
+  payload: Schema.Struct({
+    /**
+     * When supplied, only refresh this specific provider instance. When
+     * omitted, refresh all configured instances — the legacy `refresh()`
+     * behaviour retained for transports that still dispatch untargeted
+     * refreshes.
+     */
+    instanceId: Schema.optional(ProviderInstanceId),
+  }),
+  success: ServerProviderUpdatedPayload,
+});
+
+export const WsServerUpdateProviderRpc = Rpc.make(WS_METHODS.serverUpdateProvider, {
+  payload: ServerProviderUpdateInput,
   success: ServerProviderUpdatedPayload,
+  error: ServerProviderUpdateError,
 });
 
 export const WsServerGetSettingsRpc = Rpc.make(WS_METHODS.serverGetSettings, {
@@ -151,6 +212,58 @@ export const WsServerUpdateSettingsRpc = Rpc.make(WS_METHODS.serverUpdateSetting
   error: ServerSettingsError,
 });
 
+export const WsServerDiscoverSourceControlRpc = Rpc.make(WS_METHODS.serverDiscoverSourceControl, {
+  payload: Schema.Struct({}),
+  success: SourceControlDiscoveryResult,
+});
+
+export const WsServerGetTraceDiagnosticsRpc = Rpc.make(WS_METHODS.serverGetTraceDiagnostics, {
+  payload: Schema.Struct({}),
+  success: ServerTraceDiagnosticsResult,
+});
+
+export const WsServerGetProcessDiagnosticsRpc = Rpc.make(WS_METHODS.serverGetProcessDiagnostics, {
+  payload: Schema.Struct({}),
+  success: ServerProcessDiagnosticsResult,
+});
+
+export const WsServerGetProcessResourceHistoryRpc = Rpc.make(
+  WS_METHODS.serverGetProcessResourceHistory,
+  {
+    payload: ServerProcessResourceHistoryInput,
+    success: ServerProcessResourceHistoryResult,
+  },
+);
+
+export const WsServerSignalProcessRpc = Rpc.make(WS_METHODS.serverSignalProcess, {
+  payload: ServerSignalProcessInput,
+  success: ServerSignalProcessResult,
+});
+
+export const WsSourceControlLookupRepositoryRpc = Rpc.make(
+  WS_METHODS.sourceControlLookupRepository,
+  {
+    payload: SourceControlRepositoryLookupInput,
+    success: SourceControlRepositoryInfo,
+    error: SourceControlRepositoryError,
+  },
+);
+
+export const WsSourceControlCloneRepositoryRpc = Rpc.make(WS_METHODS.sourceControlCloneRepository, {
+  payload: SourceControlCloneRepositoryInput,
+  success: SourceControlCloneRepositoryResult,
+  error: SourceControlRepositoryError,
+});
+
+export const WsSourceControlPublishRepositoryRpc = Rpc.make(
+  WS_METHODS.sourceControlPublishRepository,
+  {
+    payload: SourceControlPublishRepositoryInput,
+    success: SourceControlPublishRepositoryResult,
+    error: SourceControlRepositoryError,
+  },
+);
+
 export const WsProjectsSearchEntriesRpc = Rpc.make(WS_METHODS.projectsSearchEntries, {
   payload: ProjectSearchEntriesInput,
   success: ProjectSearchEntriesResult,
@@ -164,26 +277,32 @@ export const WsProjectsWriteFileRpc = Rpc.make(WS_METHODS.projectsWriteFile, {
 });
 
 export const WsShellOpenInEditorRpc = Rpc.make(WS_METHODS.shellOpenInEditor, {
-  payload: OpenInEditorInput,
-  error: OpenError,
+  payload: LaunchEditorInput,
+  error: ExternalLauncherError,
+});
+
+export const WsFilesystemBrowseRpc = Rpc.make(WS_METHODS.filesystemBrowse, {
+  payload: FilesystemBrowseInput,
+  success: FilesystemBrowseResult,
+  error: FilesystemBrowseError,
 });
 
-export const WsSubscribeGitStatusRpc = Rpc.make(WS_METHODS.subscribeGitStatus, {
-  payload: GitStatusInput,
-  success: GitStatusStreamEvent,
+export const WsSubscribeVcsStatusRpc = Rpc.make(WS_METHODS.subscribeVcsStatus, {
+  payload: VcsStatusInput,
+  success: VcsStatusStreamEvent,
   error: GitManagerServiceError,
   stream: true,
 });
 
-export const WsGitPullRpc = Rpc.make(WS_METHODS.gitPull, {
-  payload: GitPullInput,
-  success: GitPullResult,
+export const WsVcsPullRpc = Rpc.make(WS_METHODS.vcsPull, {
+  payload: VcsPullInput,
+  success: VcsPullResult,
   error: GitCommandError,
 });
 
-export const WsGitRefreshStatusRpc = Rpc.make(WS_METHODS.gitRefreshStatus, {
-  payload: GitStatusInput,
-  success: GitStatusResult,
+export const WsVcsRefreshStatusRpc = Rpc.make(WS_METHODS.vcsRefreshStatus, {
+  payload: VcsStatusInput,
+  success: VcsStatusResult,
   error: GitManagerServiceError,
 });
 
@@ -206,38 +325,38 @@ export const WsGitPreparePullRequestThreadRpc = Rpc.make(WS_METHODS.gitPreparePu
   error: GitManagerServiceError,
 });
 
-export const WsGitListBranchesRpc = Rpc.make(WS_METHODS.gitListBranches, {
-  payload: GitListBranchesInput,
-  success: GitListBranchesResult,
+export const WsVcsListRefsRpc = Rpc.make(WS_METHODS.vcsListRefs, {
+  payload: VcsListRefsInput,
+  success: VcsListRefsResult,
   error: GitCommandError,
 });
 
-export const WsGitCreateWorktreeRpc = Rpc.make(WS_METHODS.gitCreateWorktree, {
-  payload: GitCreateWorktreeInput,
-  success: GitCreateWorktreeResult,
+export const WsVcsCreateWorktreeRpc = Rpc.make(WS_METHODS.vcsCreateWorktree, {
+  payload: VcsCreateWorktreeInput,
+  success: VcsCreateWorktreeResult,
   error: GitCommandError,
 });
 
-export const WsGitRemoveWorktreeRpc = Rpc.make(WS_METHODS.gitRemoveWorktree, {
-  payload: GitRemoveWorktreeInput,
+export const WsVcsRemoveWorktreeRpc = Rpc.make(WS_METHODS.vcsRemoveWorktree, {
+  payload: VcsRemoveWorktreeInput,
   error: GitCommandError,
 });
 
-export const WsGitCreateBranchRpc = Rpc.make(WS_METHODS.gitCreateBranch, {
-  payload: GitCreateBranchInput,
-  success: GitCreateBranchResult,
+export const WsVcsCreateRefRpc = Rpc.make(WS_METHODS.vcsCreateRef, {
+  payload: VcsCreateRefInput,
+  success: VcsCreateRefResult,
   error: GitCommandError,
 });
 
-export const WsGitCheckoutRpc = Rpc.make(WS_METHODS.gitCheckout, {
-  payload: GitCheckoutInput,
-  success: GitCheckoutResult,
+export const WsVcsSwitchRefRpc = Rpc.make(WS_METHODS.vcsSwitchRef, {
+  payload: VcsSwitchRefInput,
+  success: VcsSwitchRefResult,
   error: GitCommandError,
 });
 
-export const WsGitInitRpc = Rpc.make(WS_METHODS.gitInit, {
-  payload: GitInitInput,
-  error: GitCommandError,
+export const WsVcsInitRpc = Rpc.make(WS_METHODS.vcsInit, {
+  payload: VcsInitInput,
+  error: VcsError,
 });
 
 export const WsTerminalOpenRpc = Rpc.make(WS_METHODS.terminalOpen, {
@@ -272,12 +391,6 @@ export const WsTerminalCloseRpc = Rpc.make(WS_METHODS.terminalClose, {
   error: TerminalError,
 });
 
-export const WsOrchestrationGetSnapshotRpc = Rpc.make(ORCHESTRATION_WS_METHODS.getSnapshot, {
-  payload: OrchestrationGetSnapshotInput,
-  success: OrchestrationRpcSchemas.getSnapshot.output,
-  error: OrchestrationGetSnapshotError,
-});
-
 export const WsOrchestrationDispatchCommandRpc = Rpc.make(
   ORCHESTRATION_WS_METHODS.dispatchCommand,
   {
@@ -308,11 +421,28 @@ export const WsOrchestrationReplayEventsRpc = Rpc.make(ORCHESTRATION_WS_METHODS.
   error: OrchestrationReplayEventsError,
 });
 
-export const WsSubscribeOrchestrationDomainEventsRpc = Rpc.make(
-  WS_METHODS.subscribeOrchestrationDomainEvents,
+export const WsOrchestrationGetArchivedShellSnapshotRpc = Rpc.make(
+  ORCHESTRATION_WS_METHODS.getArchivedShellSnapshot,
+  {
+    payload: OrchestrationRpcSchemas.getArchivedShellSnapshot.input,
+    success: OrchestrationRpcSchemas.getArchivedShellSnapshot.output,
+    error: OrchestrationGetSnapshotError,
+  },
+);
+
+export const WsOrchestrationSubscribeShellRpc = Rpc.make(ORCHESTRATION_WS_METHODS.subscribeShell, {
+  payload: OrchestrationRpcSchemas.subscribeShell.input,
+  success: OrchestrationRpcSchemas.subscribeShell.output,
+  error: OrchestrationGetSnapshotError,
+  stream: true,
+});
+
+export const WsOrchestrationSubscribeThreadRpc = Rpc.make(
+  ORCHESTRATION_WS_METHODS.subscribeThread,
   {
-    payload: Schema.Struct({}),
-    success: OrchestrationEvent,
+    payload: OrchestrationRpcSchemas.subscribeThread.input,
+    success: OrchestrationRpcSchemas.subscribeThread.output,
+    error: OrchestrationGetSnapshotError,
     stream: true,
   },
 );
@@ -345,38 +475,50 @@ export const WsSubscribeAuthAccessRpc = Rpc.make(WS_METHODS.subscribeAuthAccess,
 export const WsRpcGroup = RpcGroup.make(
   WsServerGetConfigRpc,
   WsServerRefreshProvidersRpc,
+  WsServerUpdateProviderRpc,
   WsServerUpsertKeybindingRpc,
+  WsServerRemoveKeybindingRpc,
   WsServerGetSettingsRpc,
   WsServerUpdateSettingsRpc,
+  WsServerDiscoverSourceControlRpc,
+  WsServerGetTraceDiagnosticsRpc,
+  WsServerGetProcessDiagnosticsRpc,
+  WsServerGetProcessResourceHistoryRpc,
+  WsServerSignalProcessRpc,
+  WsSourceControlLookupRepositoryRpc,
+  WsSourceControlCloneRepositoryRpc,
+  WsSourceControlPublishRepositoryRpc,
   WsProjectsSearchEntriesRpc,
   WsProjectsWriteFileRpc,
   WsShellOpenInEditorRpc,
-  WsSubscribeGitStatusRpc,
-  WsGitPullRpc,
-  WsGitRefreshStatusRpc,
+  WsFilesystemBrowseRpc,
+  WsSubscribeVcsStatusRpc,
+  WsVcsPullRpc,
+  WsVcsRefreshStatusRpc,
   WsGitRunStackedActionRpc,
   WsGitResolvePullRequestRpc,
   WsGitPreparePullRequestThreadRpc,
-  WsGitListBranchesRpc,
-  WsGitCreateWorktreeRpc,
-  WsGitRemoveWorktreeRpc,
-  WsGitCreateBranchRpc,
-  WsGitCheckoutRpc,
-  WsGitInitRpc,
+  WsVcsListRefsRpc,
+  WsVcsCreateWorktreeRpc,
+  WsVcsRemoveWorktreeRpc,
+  WsVcsCreateRefRpc,
+  WsVcsSwitchRefRpc,
+  WsVcsInitRpc,
   WsTerminalOpenRpc,
   WsTerminalWriteRpc,
   WsTerminalResizeRpc,
   WsTerminalClearRpc,
   WsTerminalRestartRpc,
   WsTerminalCloseRpc,
-  WsSubscribeOrchestrationDomainEventsRpc,
   WsSubscribeTerminalEventsRpc,
   WsSubscribeServerConfigRpc,
   WsSubscribeServerLifecycleRpc,
   WsSubscribeAuthAccessRpc,
-  WsOrchestrationGetSnapshotRpc,
   WsOrchestrationDispatchCommandRpc,
   WsOrchestrationGetTurnDiffRpc,
   WsOrchestrationGetFullThreadDiffRpc,
   WsOrchestrationReplayEventsRpc,
+  WsOrchestrationGetArchivedShellSnapshotRpc,
+  WsOrchestrationSubscribeShellRpc,
+  WsOrchestrationSubscribeThreadRpc,
 );
diff --git a/packages/contracts/src/server.test.ts b/packages/contracts/src/server.test.ts
index 6e5f70c2e4d..a2ad0cbb383 100644
--- a/packages/contracts/src/server.test.ts
+++ b/packages/contracts/src/server.test.ts
@@ -1,14 +1,15 @@
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 import { describe, expect, it } from "vitest";
 
-import { ServerProvider } from "./server";
+import { ServerProvider } from "./server.ts";
 
 const decodeServerProvider = Schema.decodeUnknownSync(ServerProvider);
 
 describe("ServerProvider", () => {
-  it("defaults capability arrays when decoding legacy snapshots", () => {
+  it("defaults capability arrays when decoding provider snapshots", () => {
     const parsed = decodeServerProvider({
-      provider: "codex",
+      instanceId: "codex",
+      driver: "codex",
       enabled: true,
       installed: true,
       version: "1.0.0",
@@ -22,5 +23,52 @@ describe("ServerProvider", () => {
 
     expect(parsed.slashCommands).toEqual([]);
     expect(parsed.skills).toEqual([]);
+    expect(parsed.versionAdvisory).toBeUndefined();
+    expect(parsed.updateState).toBeUndefined();
+  });
+
+  it("defaults one-click update support when decoding older advisory snapshots", () => {
+    const parsed = decodeServerProvider({
+      instanceId: "codex",
+      driver: "codex",
+      enabled: true,
+      installed: true,
+      version: "1.0.0",
+      status: "ready",
+      auth: {
+        status: "authenticated",
+      },
+      checkedAt: "2026-04-10T00:00:00.000Z",
+      models: [],
+      versionAdvisory: {
+        status: "behind_latest",
+        currentVersion: "1.0.0",
+        latestVersion: "1.0.1",
+        updateCommand: "npm install -g @openai/codex@latest",
+        checkedAt: "2026-04-10T00:00:00.000Z",
+        message: "Update available.",
+      },
+    });
+
+    expect(parsed.versionAdvisory?.canUpdate).toBe(false);
+  });
+
+  it("decodes continuation group metadata", () => {
+    const parsed = decodeServerProvider({
+      instanceId: "codex_personal",
+      driver: "codex",
+      continuation: { groupKey: "codex:home:/Users/julius/.codex" },
+      enabled: true,
+      installed: true,
+      version: "1.0.0",
+      status: "ready",
+      auth: {
+        status: "authenticated",
+      },
+      checkedAt: "2026-04-10T00:00:00.000Z",
+      models: [],
+    });
+
+    expect(parsed.continuation?.groupKey).toBe("codex:home:/Users/julius/.codex");
   });
 });
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index 50db737c6ae..85ff4a4b2cb 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -1,18 +1,25 @@
-import { Effect, Schema } from "effect";
-import { ExecutionEnvironmentDescriptor } from "./environment";
-import { ServerAuthDescriptor } from "./auth";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { ExecutionEnvironmentDescriptor } from "./environment.ts";
+import { ServerAuthDescriptor } from "./auth.ts";
 import {
   IsoDateTime,
   NonNegativeInt,
+  PositiveInt,
   ProjectId,
   ThreadId,
   TrimmedNonEmptyString,
-} from "./baseSchemas";
-import { KeybindingRule, ResolvedKeybindingsConfig } from "./keybindings";
-import { EditorId } from "./editor";
-import { ModelCapabilities } from "./model";
-import { ProviderKind } from "./orchestration";
-import { ServerSettings } from "./settings";
+} from "./baseSchemas.ts";
+import {
+  KeybindingCommand,
+  KeybindingValue,
+  KeybindingWhen,
+  ResolvedKeybindingsConfig,
+} from "./keybindings.ts";
+import { EditorId } from "./editor.ts";
+import { ModelCapabilities } from "./model.ts";
+import { ProviderDriverKind, ProviderInstanceId } from "./providerInstance.ts";
+import { ServerSettings } from "./settings.ts";
 
 const KeybindingsMalformedConfigIssue = Schema.Struct({
   kind: Schema.Literal("keybindings.malformed-config"),
@@ -47,12 +54,15 @@ export const ServerProviderAuth = Schema.Struct({
   status: ServerProviderAuthStatus,
   type: Schema.optional(TrimmedNonEmptyString),
   label: Schema.optional(TrimmedNonEmptyString),
+  email: Schema.optional(TrimmedNonEmptyString),
 });
 export type ServerProviderAuth = typeof ServerProviderAuth.Type;
 
 export const ServerProviderModel = Schema.Struct({
   slug: TrimmedNonEmptyString,
   name: TrimmedNonEmptyString,
+  shortName: Schema.optional(TrimmedNonEmptyString),
+  subProvider: Schema.optional(TrimmedNonEmptyString),
   isCustom: Schema.Boolean,
   capabilities: Schema.NullOr(ModelCapabilities),
 });
@@ -81,8 +91,80 @@ export const ServerProviderSkill = Schema.Struct({
 });
 export type ServerProviderSkill = typeof ServerProviderSkill.Type;
 
+/**
+ * Availability of a configured provider instance from the runtime's POV.
+ *
+ *  - `available` — the build ships this driver and an instance is wired
+ *    up. Default for legacy snapshots produced from the closed
+ *    `ServerSettings.providers` map.
+ *  - `unavailable` — the user's `ServerSettings.providerInstances` (or a
+ *    persisted thread / session binding) references a driver this build
+ *    doesn't ship. Common after rolling back from a fork or PR branch
+ *    that introduced a new driver. The snapshot is preserved so the UI
+ *    can render "missing driver" affordances and so the data round-trips
+ *    when the user moves back to the fork.
+ *
+ * Snapshots with `availability: "unavailable"` MUST set
+ * `installed: false` and `enabled: false`; the runtime refuses turn
+ * starts against them with a structured error.
+ */
+export const ServerProviderAvailability = Schema.Literals(["available", "unavailable"]);
+export type ServerProviderAvailability = typeof ServerProviderAvailability.Type;
+
+export const ServerProviderContinuation = Schema.Struct({
+  groupKey: TrimmedNonEmptyString,
+});
+export type ServerProviderContinuation = typeof ServerProviderContinuation.Type;
+
+export const ServerProviderVersionAdvisoryStatus = Schema.Literals([
+  "unknown",
+  "current",
+  "behind_latest",
+]);
+export type ServerProviderVersionAdvisoryStatus = typeof ServerProviderVersionAdvisoryStatus.Type;
+
+export const ServerProviderVersionAdvisory = Schema.Struct({
+  status: ServerProviderVersionAdvisoryStatus,
+  currentVersion: Schema.NullOr(TrimmedNonEmptyString),
+  latestVersion: Schema.NullOr(TrimmedNonEmptyString),
+  updateCommand: Schema.NullOr(TrimmedNonEmptyString),
+  canUpdate: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
+  checkedAt: Schema.NullOr(IsoDateTime),
+  message: Schema.NullOr(TrimmedNonEmptyString),
+});
+export type ServerProviderVersionAdvisory = typeof ServerProviderVersionAdvisory.Type;
+
+export const ServerProviderUpdateStatus = Schema.Literals([
+  "idle",
+  "queued",
+  "running",
+  "succeeded",
+  "failed",
+  "unchanged",
+]);
+export type ServerProviderUpdateStatus = typeof ServerProviderUpdateStatus.Type;
+
+export const ServerProviderUpdateState = Schema.Struct({
+  status: ServerProviderUpdateStatus,
+  startedAt: Schema.NullOr(IsoDateTime),
+  finishedAt: Schema.NullOr(IsoDateTime),
+  message: Schema.NullOr(TrimmedNonEmptyString),
+  output: Schema.NullOr(Schema.String.check(Schema.isMaxLength(10_000))),
+});
+export type ServerProviderUpdateState = typeof ServerProviderUpdateState.Type;
+
 export const ServerProvider = Schema.Struct({
-  provider: ProviderKind,
+  // Routing key for the configured instance this snapshot represents. This
+  // is the only stable identity consumers may use for provider routing.
+  instanceId: ProviderInstanceId,
+  // Open driver kind slug that selects the implementation handling this
+  // instance. It is metadata/capability context, not a routing key.
+  driver: ProviderDriverKind,
+  displayName: Schema.optional(TrimmedNonEmptyString),
+  accentColor: Schema.optional(TrimmedNonEmptyString),
+  badgeLabel: Schema.optional(TrimmedNonEmptyString),
+  continuation: Schema.optional(ServerProviderContinuation),
+  showInteractionModeToggle: Schema.optional(Schema.Boolean),
   enabled: Schema.Boolean,
   installed: Schema.Boolean,
   version: Schema.NullOr(TrimmedNonEmptyString),
@@ -90,17 +172,37 @@ export const ServerProvider = Schema.Struct({
   auth: ServerProviderAuth,
   checkedAt: IsoDateTime,
   message: Schema.optional(TrimmedNonEmptyString),
+  // Optional for back-compat: every legacy producer omits this field and
+  // an absent value is interpreted as `"available"` by consumers (see
+  // `isProviderAvailable`). New `ProviderInstanceRegistry` outputs set it
+  // explicitly so the UI can render unavailable shadows from
+  // `ServerSettings.providerInstances`.
+  availability: Schema.optional(ServerProviderAvailability),
+  // Human-readable reason populated when `availability === "unavailable"`.
+  // Surfaces in the UI alongside the missing-driver affordance.
+  unavailableReason: Schema.optional(TrimmedNonEmptyString),
   models: Schema.Array(ServerProviderModel),
   slashCommands: Schema.Array(ServerProviderSlashCommand).pipe(
     Schema.withDecodingDefault(Effect.succeed([])),
   ),
   skills: Schema.Array(ServerProviderSkill).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
+  versionAdvisory: Schema.optionalKey(ServerProviderVersionAdvisory),
+  updateState: Schema.optionalKey(ServerProviderUpdateState),
 });
 export type ServerProvider = typeof ServerProvider.Type;
 
 export const ServerProviders = Schema.Array(ServerProvider);
 export type ServerProviders = typeof ServerProviders.Type;
 
+/**
+ * Treat the optional `availability` as "available" when absent. This is
+ * the rule legacy producers (which omit the field) and new producers
+ * (which set it explicitly) agree on so consumers never have to thread
+ * `?? "available"` defaults through their code paths.
+ */
+export const isProviderAvailable = (snapshot: ServerProvider): boolean =>
+  snapshot.availability !== "unavailable";
+
 export const ServerObservability = Schema.Struct({
   logsDirectoryPath: TrimmedNonEmptyString,
   localTracingEnabled: Schema.Boolean,
@@ -111,6 +213,187 @@ export const ServerObservability = Schema.Struct({
 });
 export type ServerObservability = typeof ServerObservability.Type;
 
+export const ServerTraceDiagnosticsErrorKind = Schema.Literals([
+  "trace-file-not-found",
+  "trace-file-read-failed",
+]);
+export type ServerTraceDiagnosticsErrorKind = typeof ServerTraceDiagnosticsErrorKind.Type;
+
+export const ServerTraceDiagnosticsSpanSummary = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  count: NonNegativeInt,
+  failureCount: NonNegativeInt,
+  totalDurationMs: Schema.Number,
+  averageDurationMs: Schema.Number,
+  maxDurationMs: Schema.Number,
+});
+export type ServerTraceDiagnosticsSpanSummary = typeof ServerTraceDiagnosticsSpanSummary.Type;
+
+export const ServerTraceDiagnosticsFailureSummary = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  cause: TrimmedNonEmptyString,
+  count: NonNegativeInt,
+  lastSeenAt: Schema.DateTimeUtc,
+  traceId: TrimmedNonEmptyString,
+  spanId: TrimmedNonEmptyString,
+});
+export type ServerTraceDiagnosticsFailureSummary = typeof ServerTraceDiagnosticsFailureSummary.Type;
+
+export const ServerTraceDiagnosticsRecentFailure = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  cause: TrimmedNonEmptyString,
+  durationMs: Schema.Number,
+  endedAt: Schema.DateTimeUtc,
+  traceId: TrimmedNonEmptyString,
+  spanId: TrimmedNonEmptyString,
+});
+export type ServerTraceDiagnosticsRecentFailure = typeof ServerTraceDiagnosticsRecentFailure.Type;
+
+export const ServerTraceDiagnosticsSpanOccurrence = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  durationMs: Schema.Number,
+  endedAt: Schema.DateTimeUtc,
+  traceId: TrimmedNonEmptyString,
+  spanId: TrimmedNonEmptyString,
+});
+export type ServerTraceDiagnosticsSpanOccurrence = typeof ServerTraceDiagnosticsSpanOccurrence.Type;
+
+export const ServerTraceDiagnosticsLogEvent = Schema.Struct({
+  spanName: TrimmedNonEmptyString,
+  level: TrimmedNonEmptyString,
+  message: TrimmedNonEmptyString,
+  seenAt: Schema.DateTimeUtc,
+  traceId: TrimmedNonEmptyString,
+  spanId: TrimmedNonEmptyString,
+});
+export type ServerTraceDiagnosticsLogEvent = typeof ServerTraceDiagnosticsLogEvent.Type;
+
+export const ServerTraceDiagnosticsResult = Schema.Struct({
+  traceFilePath: TrimmedNonEmptyString,
+  scannedFilePaths: Schema.Array(TrimmedNonEmptyString),
+  readAt: Schema.DateTimeUtc,
+  recordCount: NonNegativeInt,
+  parseErrorCount: NonNegativeInt,
+  firstSpanAt: Schema.Option(Schema.DateTimeUtc),
+  lastSpanAt: Schema.Option(Schema.DateTimeUtc),
+  failureCount: NonNegativeInt,
+  interruptionCount: NonNegativeInt,
+  slowSpanThresholdMs: NonNegativeInt,
+  slowSpanCount: NonNegativeInt,
+  logLevelCounts: Schema.Record(TrimmedNonEmptyString, NonNegativeInt),
+  topSpansByCount: Schema.Array(ServerTraceDiagnosticsSpanSummary),
+  slowestSpans: Schema.Array(ServerTraceDiagnosticsSpanOccurrence),
+  commonFailures: Schema.Array(ServerTraceDiagnosticsFailureSummary),
+  latestFailures: Schema.Array(ServerTraceDiagnosticsRecentFailure),
+  latestWarningAndErrorLogs: Schema.Array(ServerTraceDiagnosticsLogEvent),
+  partialFailure: Schema.Option(Schema.Boolean),
+  error: Schema.Option(
+    Schema.Struct({
+      kind: ServerTraceDiagnosticsErrorKind,
+      message: TrimmedNonEmptyString,
+    }),
+  ),
+});
+export type ServerTraceDiagnosticsResult = typeof ServerTraceDiagnosticsResult.Type;
+
+export const ServerProcessSignal = Schema.Literals(["SIGINT", "SIGKILL"]);
+export type ServerProcessSignal = typeof ServerProcessSignal.Type;
+
+export const ServerProcessDiagnosticsEntry = Schema.Struct({
+  pid: PositiveInt,
+  ppid: NonNegativeInt,
+  pgid: Schema.Option(Schema.Int),
+  status: TrimmedNonEmptyString,
+  cpuPercent: Schema.Number,
+  rssBytes: NonNegativeInt,
+  elapsed: TrimmedNonEmptyString,
+  command: TrimmedNonEmptyString,
+  depth: NonNegativeInt,
+  childPids: Schema.Array(PositiveInt),
+});
+export type ServerProcessDiagnosticsEntry = typeof ServerProcessDiagnosticsEntry.Type;
+
+export const ServerProcessDiagnosticsResult = Schema.Struct({
+  serverPid: PositiveInt,
+  readAt: Schema.DateTimeUtc,
+  processCount: NonNegativeInt,
+  totalRssBytes: NonNegativeInt,
+  totalCpuPercent: Schema.Number,
+  processes: Schema.Array(ServerProcessDiagnosticsEntry),
+  error: Schema.Option(
+    Schema.Struct({
+      message: TrimmedNonEmptyString,
+    }),
+  ),
+});
+export type ServerProcessDiagnosticsResult = typeof ServerProcessDiagnosticsResult.Type;
+
+export const ServerProcessResourceHistoryInput = Schema.Struct({
+  windowMs: NonNegativeInt,
+  bucketMs: NonNegativeInt,
+});
+export type ServerProcessResourceHistoryInput = typeof ServerProcessResourceHistoryInput.Type;
+
+export const ServerProcessResourceHistoryBucket = Schema.Struct({
+  startedAt: Schema.DateTimeUtc,
+  endedAt: Schema.DateTimeUtc,
+  avgCpuPercent: Schema.Number,
+  maxCpuPercent: Schema.Number,
+  maxRssBytes: NonNegativeInt,
+  maxProcessCount: NonNegativeInt,
+});
+export type ServerProcessResourceHistoryBucket = typeof ServerProcessResourceHistoryBucket.Type;
+
+export const ServerProcessResourceHistorySummary = Schema.Struct({
+  processKey: TrimmedNonEmptyString,
+  pid: PositiveInt,
+  ppid: NonNegativeInt,
+  command: TrimmedNonEmptyString,
+  depth: NonNegativeInt,
+  isServerRoot: Schema.Boolean,
+  firstSeenAt: Schema.DateTimeUtc,
+  lastSeenAt: Schema.DateTimeUtc,
+  currentCpuPercent: Schema.Number,
+  avgCpuPercent: Schema.Number,
+  maxCpuPercent: Schema.Number,
+  cpuSecondsApprox: Schema.Number,
+  currentRssBytes: NonNegativeInt,
+  maxRssBytes: NonNegativeInt,
+  sampleCount: NonNegativeInt,
+});
+export type ServerProcessResourceHistorySummary = typeof ServerProcessResourceHistorySummary.Type;
+
+export const ServerProcessResourceHistoryResult = Schema.Struct({
+  readAt: Schema.DateTimeUtc,
+  windowMs: NonNegativeInt,
+  bucketMs: NonNegativeInt,
+  sampleIntervalMs: NonNegativeInt,
+  retainedSampleCount: NonNegativeInt,
+  totalCpuSecondsApprox: Schema.Number,
+  buckets: Schema.Array(ServerProcessResourceHistoryBucket),
+  topProcesses: Schema.Array(ServerProcessResourceHistorySummary),
+  error: Schema.Option(
+    Schema.Struct({
+      message: TrimmedNonEmptyString,
+    }),
+  ),
+});
+export type ServerProcessResourceHistoryResult = typeof ServerProcessResourceHistoryResult.Type;
+
+export const ServerSignalProcessInput = Schema.Struct({
+  pid: PositiveInt,
+  signal: ServerProcessSignal,
+});
+export type ServerSignalProcessInput = typeof ServerSignalProcessInput.Type;
+
+export const ServerSignalProcessResult = Schema.Struct({
+  pid: PositiveInt,
+  signal: ServerProcessSignal,
+  signaled: Schema.Boolean,
+  message: Schema.Option(TrimmedNonEmptyString),
+});
+export type ServerSignalProcessResult = typeof ServerSignalProcessResult.Type;
+
 export const ServerConfig = Schema.Struct({
   environment: ExecutionEnvironmentDescriptor,
   auth: ServerAuthDescriptor,
@@ -125,15 +408,32 @@ export const ServerConfig = Schema.Struct({
 });
 export type ServerConfig = typeof ServerConfig.Type;
 
-export const ServerUpsertKeybindingInput = KeybindingRule;
+const ServerUpsertKeybindingReplaceTarget = Schema.Struct({
+  key: KeybindingValue,
+  command: KeybindingCommand,
+  when: Schema.optional(KeybindingWhen),
+});
+
+export const ServerUpsertKeybindingInput = Schema.Struct({
+  key: KeybindingValue,
+  command: KeybindingCommand,
+  when: Schema.optional(KeybindingWhen),
+  replace: Schema.optional(ServerUpsertKeybindingReplaceTarget),
+});
 export type ServerUpsertKeybindingInput = typeof ServerUpsertKeybindingInput.Type;
 
+export const ServerRemoveKeybindingInput = ServerUpsertKeybindingReplaceTarget;
+export type ServerRemoveKeybindingInput = typeof ServerRemoveKeybindingInput.Type;
+
 export const ServerUpsertKeybindingResult = Schema.Struct({
   keybindings: ResolvedKeybindingsConfig,
   issues: ServerConfigIssues,
 });
 export type ServerUpsertKeybindingResult = typeof ServerUpsertKeybindingResult.Type;
 
+export const ServerRemoveKeybindingResult = ServerUpsertKeybindingResult;
+export type ServerRemoveKeybindingResult = typeof ServerRemoveKeybindingResult.Type;
+
 export const ServerConfigUpdatedPayload = Schema.Struct({
   issues: ServerConfigIssues,
   providers: ServerProviders,
@@ -142,6 +442,7 @@ export const ServerConfigUpdatedPayload = Schema.Struct({
 export type ServerConfigUpdatedPayload = typeof ServerConfigUpdatedPayload.Type;
 
 export const ServerConfigKeybindingsUpdatedPayload = Schema.Struct({
+  keybindings: ResolvedKeybindingsConfig,
   issues: ServerConfigIssues,
 });
 export type ServerConfigKeybindingsUpdatedPayload =
@@ -237,3 +538,22 @@ export const ServerProviderUpdatedPayload = Schema.Struct({
   providers: ServerProviders,
 });
 export type ServerProviderUpdatedPayload = typeof ServerProviderUpdatedPayload.Type;
+
+export const ServerProviderUpdateInput = Schema.Struct({
+  provider: ProviderDriverKind,
+  instanceId: Schema.optionalKey(ProviderInstanceId),
+});
+export type ServerProviderUpdateInput = typeof ServerProviderUpdateInput.Type;
+
+export class ServerProviderUpdateError extends Schema.TaggedErrorClass<ServerProviderUpdateError>()(
+  "ServerProviderUpdateError",
+  {
+    provider: ProviderDriverKind,
+    reason: TrimmedNonEmptyString,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `Provider update failed for ${this.provider}: ${this.reason}`;
+  }
+}
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
new file mode 100644
index 00000000000..39695fe3b01
--- /dev/null
+++ b/packages/contracts/src/settings.test.ts
@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import * as Schema from "effect/Schema";
+
+import { ProviderInstanceId } from "./providerInstance.ts";
+import { DEFAULT_SERVER_SETTINGS, ServerSettings, ServerSettingsPatch } from "./settings.ts";
+
+const decodeServerSettings = Schema.decodeUnknownSync(ServerSettings);
+const decodeServerSettingsPatch = Schema.decodeUnknownSync(ServerSettingsPatch);
+const encodeServerSettings = Schema.encodeSync(ServerSettings);
+
+describe("ServerSettings.providerInstances (slice-2 invariant)", () => {
+  it("defaults to an empty record so legacy configs without the key still decode", () => {
+    expect(DEFAULT_SERVER_SETTINGS.providerInstances).toEqual({});
+  });
+
+  it("decodes a fully empty config (legacy on-disk shape) without complaint", () => {
+    const decoded = decodeServerSettings({});
+    expect(decoded.providerInstances).toEqual({});
+    // Legacy `providers` struct is still hydrated with its per-driver defaults
+    // so existing call sites keep working through the migration.
+    expect(decoded.providers.codex.enabled).toBe(true);
+  });
+
+  it("decodes a multi-instance map mixing first-party and fork drivers", () => {
+    const decoded = decodeServerSettings({
+      providerInstances: {
+        codex_personal: {
+          driver: "codex",
+          displayName: "Codex (personal)",
+          config: { homePath: "~/.codex_personal" },
+        },
+        codex_work: {
+          driver: "codex",
+          config: { homePath: "~/.codex_work" },
+        },
+        ollama_local: {
+          driver: "ollama",
+          displayName: "Ollama (local)",
+          config: { endpoint: "http://localhost:11434" },
+        },
+      },
+    });
+    const personalId = ProviderInstanceId.make("codex_personal");
+    const workId = ProviderInstanceId.make("codex_work");
+    const ollamaId = ProviderInstanceId.make("ollama_local");
+
+    expect(decoded.providerInstances[personalId]?.driver).toBe("codex");
+    expect(decoded.providerInstances[workId]?.config).toEqual({ homePath: "~/.codex_work" });
+    // Critical: a config naming a driver this build does not know about
+    // (`ollama` is not in `ProviderDriverKind`) must round-trip without loss.
+    // The runtime handles "driver not installed" — the schema must not.
+    expect(decoded.providerInstances[ollamaId]?.driver).toBe("ollama");
+    expect(decoded.providerInstances[ollamaId]?.config).toEqual({
+      endpoint: "http://localhost:11434",
+    });
+  });
+
+  it("rejects instance keys that violate the slug pattern", () => {
+    expect(() =>
+      decodeServerSettings({
+        providerInstances: { "1bad": { driver: "codex" } },
+      }),
+    ).toThrow();
+  });
+});
+
+describe("ServerSettingsPatch.providerInstances", () => {
+  it("treats providerInstances as an optional whole-map replacement", () => {
+    const patch = decodeServerSettingsPatch({});
+    expect(patch.providerInstances).toBeUndefined();
+
+    const replacement = decodeServerSettingsPatch({
+      providerInstances: {
+        codex_personal: { driver: "codex", config: { homePath: "~/.codex" } },
+      },
+    });
+    expect(replacement.providerInstances).toBeDefined();
+    expect(replacement.providerInstances?.[ProviderInstanceId.make("codex_personal")]?.driver).toBe(
+      "codex",
+    );
+  });
+
+  it("preserves a fork-defined driver entry through patch decoding", () => {
+    const patch = decodeServerSettingsPatch({
+      providerInstances: {
+        ollama_local: {
+          driver: "ollama",
+          config: { endpoint: "http://localhost:11434" },
+        },
+      },
+    });
+    const ollamaId = ProviderInstanceId.make("ollama_local");
+    expect(patch.providerInstances?.[ollamaId]?.driver).toBe("ollama");
+  });
+});
+
+describe("ServerSettingsPatch string normalization", () => {
+  it("trims string settings while decoding patches", () => {
+    const patch = decodeServerSettingsPatch({
+      addProjectBaseDirectory: "  ~/Development  ",
+      textGenerationModelSelection: { model: "  gpt-5.4-mini  " },
+      observability: {
+        otlpTracesUrl: "  http://localhost:4318/v1/traces  ",
+      },
+      providers: {
+        codex: {
+          binaryPath: "  /opt/homebrew/bin/codex  ",
+          homePath: "  ~/.codex  ",
+        },
+      },
+      providerInstances: {
+        codex_personal: {
+          driver: "  codex  ",
+          displayName: "  Codex Personal  ",
+          config: { homePath: "  ~/.codex-personal  " },
+        },
+      },
+    });
+
+    expect(patch.addProjectBaseDirectory).toBe("~/Development");
+    expect(patch.textGenerationModelSelection?.model).toBe("gpt-5.4-mini");
+    expect(patch.observability?.otlpTracesUrl).toBe("http://localhost:4318/v1/traces");
+    expect(patch.providers?.codex?.binaryPath).toBe("/opt/homebrew/bin/codex");
+    expect(patch.providers?.codex?.homePath).toBe("~/.codex");
+    expect(patch.providerInstances?.[ProviderInstanceId.make("codex_personal")]?.driver).toBe(
+      "codex",
+    );
+    expect(patch.providerInstances?.[ProviderInstanceId.make("codex_personal")]?.displayName).toBe(
+      "Codex Personal",
+    );
+    expect(patch.providerInstances?.[ProviderInstanceId.make("codex_personal")]?.config).toEqual({
+      homePath: "  ~/.codex-personal  ",
+    });
+  });
+
+  it("trims encoded server settings values before validation", () => {
+    const defaultSettings = decodeServerSettings({});
+    const encoded = encodeServerSettings({
+      ...defaultSettings,
+      addProjectBaseDirectory: "  ~/Development  ",
+      providers: {
+        ...defaultSettings.providers,
+        codex: {
+          ...defaultSettings.providers.codex,
+          binaryPath: "  /opt/homebrew/bin/codex  ",
+        },
+      },
+    });
+
+    expect(encoded.addProjectBaseDirectory).toBe("~/Development");
+    expect(encoded.providers?.codex?.binaryPath).toBe("/opt/homebrew/bin/codex");
+  });
+});
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 426f8bee568..2d115eed98e 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -1,13 +1,11 @@
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
+import * as Duration from "effect/Duration";
 import * as Schema from "effect/Schema";
 import * as SchemaTransformation from "effect/SchemaTransformation";
-import { TrimmedNonEmptyString, TrimmedString } from "./baseSchemas";
-import {
-  ClaudeModelOptions,
-  CodexModelOptions,
-  DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER,
-} from "./model";
-import { ModelSelection } from "./orchestration";
+import { TrimmedNonEmptyString, TrimmedString } from "./baseSchemas.ts";
+import { DEFAULT_GIT_TEXT_GENERATION_MODEL, ProviderOptionSelections } from "./model.ts";
+import { ModelSelection } from "./orchestration.ts";
+import { ProviderInstanceConfig, ProviderInstanceId } from "./providerInstance.ts";
 
 // ── Client Settings (local-only) ───────────────────────────────
 
@@ -23,16 +21,74 @@ export const SidebarThreadSortOrder = Schema.Literals(["updated_at", "created_at
 export type SidebarThreadSortOrder = typeof SidebarThreadSortOrder.Type;
 export const DEFAULT_SIDEBAR_THREAD_SORT_ORDER: SidebarThreadSortOrder = "updated_at";
 
+export const SidebarProjectGroupingMode = Schema.Literals([
+  "repository",
+  "repository_path",
+  "separate",
+]);
+export type SidebarProjectGroupingMode = typeof SidebarProjectGroupingMode.Type;
+export const DEFAULT_SIDEBAR_PROJECT_GROUPING_MODE: SidebarProjectGroupingMode = "repository";
+export const MIN_SIDEBAR_THREAD_PREVIEW_COUNT = 1;
+export const MAX_SIDEBAR_THREAD_PREVIEW_COUNT = 15;
+export const SidebarThreadPreviewCount = Schema.Int.check(
+  Schema.isBetween({
+    minimum: MIN_SIDEBAR_THREAD_PREVIEW_COUNT,
+    maximum: MAX_SIDEBAR_THREAD_PREVIEW_COUNT,
+  }),
+);
+export type SidebarThreadPreviewCount = typeof SidebarThreadPreviewCount.Type;
+export const DEFAULT_SIDEBAR_THREAD_PREVIEW_COUNT: SidebarThreadPreviewCount = 6;
+
 export const ClientSettingsSchema = Schema.Struct({
+  autoOpenPlanSidebar: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
   confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
   confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
+    Schema.withDecodingDefault(Effect.succeed([])),
+  ),
+  diffIgnoreWhitespace: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
   diffWordWrap: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
+  // Model favorites. Historically keyed by provider kind, now
+  // widened to `ProviderInstanceId` so users can favorite a specific model
+  // on a custom provider instance (e.g. "Codex Personal · gpt-5") without
+  // the UI collapsing it into the same bucket as the default Codex. The
+  // widening is backward-compatible by construction: prior provider-kind
+  // strings satisfy the `ProviderInstanceId` slug schema, so previously
+  // persisted favorites decode unchanged and continue to point at the
+  // default instance for their kind (because `defaultInstanceIdForDriver(kind)`
+  // uses the same slug). The field name is kept as `provider` for storage
+  // stability; new call sites should treat the value as an instance id.
+  favorites: Schema.Array(
+    Schema.Struct({
+      provider: ProviderInstanceId,
+      model: TrimmedNonEmptyString,
+    }),
+  ).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
+  providerModelPreferences: Schema.Record(
+    ProviderInstanceId,
+    Schema.Struct({
+      hiddenModels: Schema.Array(Schema.String).pipe(
+        Schema.withDecodingDefault(Effect.succeed([])),
+      ),
+      modelOrder: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
+    }),
+  ).pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+  sidebarProjectGroupingMode: SidebarProjectGroupingMode.pipe(
+    Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_PROJECT_GROUPING_MODE)),
+  ),
+  sidebarProjectGroupingOverrides: Schema.Record(
+    TrimmedNonEmptyString,
+    SidebarProjectGroupingMode,
+  ).pipe(Schema.withDecodingDefault(Effect.succeed({}))),
   sidebarProjectSortOrder: SidebarProjectSortOrder.pipe(
     Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_PROJECT_SORT_ORDER)),
   ),
   sidebarThreadSortOrder: SidebarThreadSortOrder.pipe(
     Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_THREAD_SORT_ORDER)),
   ),
+  sidebarThreadPreviewCount: SidebarThreadPreviewCount.pipe(
+    Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_THREAD_PREVIEW_COUNT)),
+  ),
   timestampFormat: TimestampFormat.pipe(
     Schema.withDecodingDefault(Effect.succeed(DEFAULT_TIMESTAMP_FORMAT)),
   ),
@@ -58,46 +114,271 @@ const makeBinaryPathSetting = (fallback: string) =>
     Schema.withDecodingDefault(Effect.succeed(fallback)),
   );
 
-export const CodexSettings = Schema.Struct({
-  enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
-  binaryPath: makeBinaryPathSetting("codex"),
-  homePath: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
-  customModels: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
-});
+export type ProviderSettingsFormControl = "text" | "password" | "textarea" | "switch";
+
+export interface ProviderSettingsFormAnnotation {
+  readonly control?: ProviderSettingsFormControl | undefined;
+  readonly placeholder?: string | undefined;
+  readonly hidden?: boolean | undefined;
+  readonly clearWhenEmpty?: "omit" | "persist" | undefined;
+}
+
+export interface ProviderSettingsFormSchemaAnnotation {
+  readonly order?: readonly string[] | undefined;
+}
+
+declare module "effect/Schema" {
+  namespace Annotations {
+    interface Annotations {
+      readonly providerSettingsForm?: ProviderSettingsFormAnnotation | undefined;
+      readonly providerSettingsFormSchema?: ProviderSettingsFormSchemaAnnotation | undefined;
+    }
+  }
+}
+
+export type ProviderSettingsOrder<Fields extends Schema.Struct.Fields> = readonly Extract<
+  keyof Fields,
+  string
+>[];
+
+export function makeProviderSettingsSchema<const Fields extends Schema.Struct.Fields>(
+  fields: Fields,
+  options?: {
+    readonly order?: ProviderSettingsOrder<Fields> | undefined;
+  },
+): Schema.Struct<Fields> {
+  return Schema.Struct(fields).pipe(
+    Schema.annotate({
+      providerSettingsFormSchema:
+        options?.order === undefined ? undefined : { order: options.order },
+    }),
+  );
+}
+
+export const CodexSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(true)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("codex").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description: "Path to the Codex binary used by this instance.",
+        providerSettingsForm: { placeholder: "codex", clearWhenEmpty: "omit" },
+      }),
+    ),
+    homePath: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "CODEX_HOME path",
+        description: "Custom Codex home and config directory.",
+        providerSettingsForm: {
+          placeholder: "~/.codex",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    shadowHomePath: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Shadow home path",
+        description:
+          "Account-specific Codex home. Keeps auth.json separate while sharing state from CODEX_HOME.",
+        providerSettingsForm: {
+          placeholder: "~/.codex-t3/personal",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+  },
+  {
+    order: ["binaryPath", "homePath", "shadowHomePath"],
+  },
+);
 export type CodexSettings = typeof CodexSettings.Type;
 
-export const ClaudeSettings = Schema.Struct({
-  enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
-  binaryPath: makeBinaryPathSetting("claude"),
-  customModels: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
-});
+export const ClaudeSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(true)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("claude").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description: "Path to the Claude binary used by this instance.",
+        providerSettingsForm: { placeholder: "claude", clearWhenEmpty: "omit" },
+      }),
+    ),
+    homePath: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Claude HOME path",
+        description:
+          "Custom HOME used when running this Claude instance. Keeps .claude.json and .claude separate.",
+        providerSettingsForm: { placeholder: "~", clearWhenEmpty: "omit" },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    launchArgs: Schema.String.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Launch arguments",
+        description: "Additional CLI arguments passed on session start.",
+        providerSettingsForm: {
+          placeholder: "e.g. --chrome",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+  },
+  {
+    order: ["binaryPath", "homePath", "launchArgs"],
+  },
+);
 export type ClaudeSettings = typeof ClaudeSettings.Type;
 
+export const CursorSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(false)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("agent").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description: "Path to the Cursor agent binary.",
+        providerSettingsForm: { placeholder: "agent", clearWhenEmpty: "omit" },
+      }),
+    ),
+    apiEndpoint: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "API endpoint",
+        description: "Override the Cursor API endpoint for this instance.",
+        providerSettingsForm: {
+          placeholder: "https://...",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+  },
+  {
+    order: ["binaryPath", "apiEndpoint"],
+  },
+);
+export type CursorSettings = typeof CursorSettings.Type;
+
+export const OpenCodeSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(true)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("opencode").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description: "Path to the OpenCode binary.",
+        providerSettingsForm: {
+          placeholder: "opencode",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    serverUrl: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Server URL",
+        description: "Leave blank to let T3 Code spawn the server when needed.",
+        providerSettingsForm: {
+          placeholder: "http://127.0.0.1:4096",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    serverPassword: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Server password",
+        description: "Stored in plain text on disk.",
+        providerSettingsForm: {
+          control: "password",
+          placeholder: "Optional",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+  },
+  {
+    order: ["binaryPath", "serverUrl", "serverPassword"],
+  },
+);
+export type OpenCodeSettings = typeof OpenCodeSettings.Type;
+
 export const ObservabilitySettings = Schema.Struct({
   otlpTracesUrl: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
   otlpMetricsUrl: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
 });
 export type ObservabilitySettings = typeof ObservabilitySettings.Type;
 
+export const DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL = Duration.seconds(30);
+
 export const ServerSettings = Schema.Struct({
   enableAssistantStreaming: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
+  automaticGitFetchInterval: Schema.DurationFromMillis.pipe(
+    Schema.withDecodingDefault(
+      Effect.succeed(Duration.toMillis(DEFAULT_AUTOMATIC_GIT_FETCH_INTERVAL)),
+    ),
+  ),
   defaultThreadEnvMode: ThreadEnvMode.pipe(
     Schema.withDecodingDefault(Effect.succeed("local" as const satisfies ThreadEnvMode)),
   ),
+  addProjectBaseDirectory: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
   textGenerationModelSelection: ModelSelection.pipe(
     Schema.withDecodingDefault(
       Effect.succeed({
-        provider: "codex" as const,
-        model: DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER.codex,
+        instanceId: ProviderInstanceId.make("codex"),
+        model: DEFAULT_GIT_TEXT_GENERATION_MODEL,
       }),
     ),
   ),
 
-  // Provider specific settings
+  // Legacy single-instance-per-driver settings. Continues to be the source
+  // of truth until `providerInstances` (below) lands per-driver migration
+  // shims and the server starts hydrating instances from it. Driver-specific
+  // schemas live here for the duration of the migration; once each driver
+  // owns its config in its own package, this struct shrinks to nothing and
+  // is removed entirely.
   providers: Schema.Struct({
     codex: CodexSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
     claudeAgent: ClaudeSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+    cursor: CursorSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+    opencode: OpenCodeSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
   }).pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+  // New driver-agnostic instance map. Keyed by `ProviderInstanceId`; values
+  // are `ProviderInstanceConfig` envelopes. The driver-specific config blob
+  // is `Schema.Unknown` at this layer so envelopes with unknown drivers
+  // (forks, downgrades, in-flight PR branches) round-trip without loss.
+  // See providerInstance.ts for the forward/backward compatibility invariant.
+  providerInstances: Schema.Record(ProviderInstanceId, ProviderInstanceConfig).pipe(
+    Schema.withDecodingDefault(Effect.succeed({})),
+  ),
   observability: ObservabilitySettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
 });
 export type ServerSettings = typeof ServerSettings.Type;
@@ -127,59 +408,106 @@ export const DEFAULT_UNIFIED_SETTINGS: UnifiedSettings = {
 
 // ── Server Settings Patch (replace with a Schema.deepPartial if available) ──────────────────────────────────────────
 
-const CodexModelOptionsPatch = Schema.Struct({
-  reasoningEffort: Schema.optionalKey(CodexModelOptions.fields.reasoningEffort),
-  fastMode: Schema.optionalKey(CodexModelOptions.fields.fastMode),
+const ModelSelectionPatch = Schema.Struct({
+  instanceId: Schema.optionalKey(ProviderInstanceId),
+  model: Schema.optionalKey(TrimmedNonEmptyString),
+  options: Schema.optionalKey(ProviderOptionSelections),
 });
 
-const ClaudeModelOptionsPatch = Schema.Struct({
-  thinking: Schema.optionalKey(ClaudeModelOptions.fields.thinking),
-  effort: Schema.optionalKey(ClaudeModelOptions.fields.effort),
-  fastMode: Schema.optionalKey(ClaudeModelOptions.fields.fastMode),
-  contextWindow: Schema.optionalKey(ClaudeModelOptions.fields.contextWindow),
+const CodexSettingsPatch = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Boolean),
+  binaryPath: Schema.optionalKey(TrimmedString),
+  homePath: Schema.optionalKey(TrimmedString),
+  shadowHomePath: Schema.optionalKey(TrimmedString),
+  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
-const ModelSelectionPatch = Schema.Union([
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("codex")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(CodexModelOptionsPatch),
-  }),
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("claudeAgent")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(ClaudeModelOptionsPatch),
-  }),
-]);
+const ClaudeSettingsPatch = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Boolean),
+  binaryPath: Schema.optionalKey(TrimmedString),
+  homePath: Schema.optionalKey(TrimmedString),
+  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  launchArgs: Schema.optionalKey(TrimmedString),
+});
 
-const CodexSettingsPatch = Schema.Struct({
+const CursorSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
-  binaryPath: Schema.optionalKey(Schema.String),
-  homePath: Schema.optionalKey(Schema.String),
+  binaryPath: Schema.optionalKey(TrimmedString),
+  apiEndpoint: Schema.optionalKey(TrimmedString),
   customModels: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
-const ClaudeSettingsPatch = Schema.Struct({
+const OpenCodeSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
-  binaryPath: Schema.optionalKey(Schema.String),
+  binaryPath: Schema.optionalKey(TrimmedString),
+  serverUrl: Schema.optionalKey(TrimmedString),
+  serverPassword: Schema.optionalKey(TrimmedString),
   customModels: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
 export const ServerSettingsPatch = Schema.Struct({
+  // Server settings
   enableAssistantStreaming: Schema.optionalKey(Schema.Boolean),
+  automaticGitFetchInterval: Schema.optionalKey(Schema.DurationFromMillis),
   defaultThreadEnvMode: Schema.optionalKey(ThreadEnvMode),
+  addProjectBaseDirectory: Schema.optionalKey(TrimmedString),
   textGenerationModelSelection: Schema.optionalKey(ModelSelectionPatch),
   observability: Schema.optionalKey(
     Schema.Struct({
-      otlpTracesUrl: Schema.optionalKey(Schema.String),
-      otlpMetricsUrl: Schema.optionalKey(Schema.String),
+      otlpTracesUrl: Schema.optionalKey(TrimmedString),
+      otlpMetricsUrl: Schema.optionalKey(TrimmedString),
     }),
   ),
   providers: Schema.optionalKey(
     Schema.Struct({
       codex: Schema.optionalKey(CodexSettingsPatch),
       claudeAgent: Schema.optionalKey(ClaudeSettingsPatch),
+      cursor: Schema.optionalKey(CursorSettingsPatch),
+      opencode: Schema.optionalKey(OpenCodeSettingsPatch),
     }),
   ),
+  // Whole-map replacement for the new instance config. Patching individual
+  // entries is intentionally out of scope: the map is small, and partial
+  // patches risk leaving driver-specific config in a half-merged state.
+  // The web UI sends a fully-formed map every time it edits this field.
+  providerInstances: Schema.optionalKey(Schema.Record(ProviderInstanceId, ProviderInstanceConfig)),
 });
 export type ServerSettingsPatch = typeof ServerSettingsPatch.Type;
+
+export const ClientSettingsPatch = Schema.Struct({
+  autoOpenPlanSidebar: Schema.optionalKey(Schema.Boolean),
+  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
+  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
+  diffWordWrap: Schema.optionalKey(Schema.Boolean),
+  favorites: Schema.optionalKey(
+    Schema.Array(
+      Schema.Struct({
+        provider: ProviderInstanceId,
+        model: TrimmedNonEmptyString,
+      }),
+    ),
+  ),
+  providerModelPreferences: Schema.optionalKey(
+    Schema.Record(
+      ProviderInstanceId,
+      Schema.Struct({
+        hiddenModels: Schema.Array(Schema.String).pipe(
+          Schema.withDecodingDefault(Effect.succeed([])),
+        ),
+        modelOrder: Schema.Array(Schema.String).pipe(
+          Schema.withDecodingDefault(Effect.succeed([])),
+        ),
+      }),
+    ),
+  ),
+  sidebarProjectGroupingMode: Schema.optionalKey(SidebarProjectGroupingMode),
+  sidebarProjectGroupingOverrides: Schema.optionalKey(
+    Schema.Record(TrimmedNonEmptyString, SidebarProjectGroupingMode),
+  ),
+  sidebarProjectSortOrder: Schema.optionalKey(SidebarProjectSortOrder),
+  sidebarThreadSortOrder: Schema.optionalKey(SidebarThreadSortOrder),
+  sidebarThreadPreviewCount: Schema.optionalKey(SidebarThreadPreviewCount),
+  timestampFormat: Schema.optionalKey(TimestampFormat),
+});
+export type ClientSettingsPatch = typeof ClientSettingsPatch.Type;
diff --git a/packages/contracts/src/sourceControl.ts b/packages/contracts/src/sourceControl.ts
new file mode 100644
index 00000000000..a8764a68763
--- /dev/null
+++ b/packages/contracts/src/sourceControl.ts
@@ -0,0 +1,179 @@
+import * as Schema from "effect/Schema";
+import { PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
+import { VcsDriverKind } from "./vcs.ts";
+
+export const SourceControlProviderKind = Schema.Literals([
+  "github",
+  "gitlab",
+  "azure-devops",
+  "bitbucket",
+  "unknown",
+]);
+export type SourceControlProviderKind = typeof SourceControlProviderKind.Type;
+
+export const SourceControlProviderInfo = Schema.Struct({
+  kind: SourceControlProviderKind,
+  name: TrimmedNonEmptyString,
+  baseUrl: Schema.String,
+});
+export type SourceControlProviderInfo = typeof SourceControlProviderInfo.Type;
+
+export const ChangeRequestState = Schema.Literals(["open", "closed", "merged"]);
+export type ChangeRequestState = typeof ChangeRequestState.Type;
+
+export const ChangeRequest = Schema.Struct({
+  provider: SourceControlProviderKind,
+  number: PositiveInt,
+  title: TrimmedNonEmptyString,
+  url: Schema.String,
+  baseRefName: TrimmedNonEmptyString,
+  headRefName: TrimmedNonEmptyString,
+  state: ChangeRequestState,
+  updatedAt: Schema.Option(Schema.DateTimeUtc),
+  isCrossRepository: Schema.optional(Schema.Boolean),
+  headRepositoryNameWithOwner: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
+  headRepositoryOwnerLogin: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
+});
+export type ChangeRequest = typeof ChangeRequest.Type;
+
+export const SourceControlRepositoryCloneUrls = Schema.Struct({
+  nameWithOwner: TrimmedNonEmptyString,
+  url: TrimmedNonEmptyString,
+  sshUrl: TrimmedNonEmptyString,
+});
+export type SourceControlRepositoryCloneUrls = typeof SourceControlRepositoryCloneUrls.Type;
+
+export const SourceControlRepositoryVisibility = Schema.Literals(["private", "public"]);
+export type SourceControlRepositoryVisibility = typeof SourceControlRepositoryVisibility.Type;
+
+export const SourceControlCloneProtocol = Schema.Literals(["auto", "ssh", "https"]);
+export type SourceControlCloneProtocol = typeof SourceControlCloneProtocol.Type;
+
+export const SourceControlRepositoryInfo = Schema.Struct({
+  provider: SourceControlProviderKind,
+  nameWithOwner: TrimmedNonEmptyString,
+  url: TrimmedNonEmptyString,
+  sshUrl: TrimmedNonEmptyString,
+});
+export type SourceControlRepositoryInfo = typeof SourceControlRepositoryInfo.Type;
+
+export const SourceControlRepositoryLookupInput = Schema.Struct({
+  provider: SourceControlProviderKind,
+  repository: TrimmedNonEmptyString,
+  cwd: Schema.optional(TrimmedNonEmptyString),
+});
+export type SourceControlRepositoryLookupInput = typeof SourceControlRepositoryLookupInput.Type;
+
+export const SourceControlCloneRepositoryInput = Schema.Struct({
+  provider: Schema.optional(SourceControlProviderKind),
+  repository: Schema.optional(TrimmedNonEmptyString),
+  remoteUrl: Schema.optional(TrimmedNonEmptyString),
+  destinationPath: TrimmedNonEmptyString,
+  protocol: Schema.optional(SourceControlCloneProtocol),
+});
+export type SourceControlCloneRepositoryInput = typeof SourceControlCloneRepositoryInput.Type;
+
+export const SourceControlCloneRepositoryResult = Schema.Struct({
+  cwd: TrimmedNonEmptyString,
+  remoteUrl: TrimmedNonEmptyString,
+  repository: Schema.NullOr(SourceControlRepositoryInfo),
+});
+export type SourceControlCloneRepositoryResult = typeof SourceControlCloneRepositoryResult.Type;
+
+export const SourceControlPublishRepositoryInput = Schema.Struct({
+  cwd: TrimmedNonEmptyString,
+  provider: SourceControlProviderKind,
+  repository: TrimmedNonEmptyString,
+  visibility: SourceControlRepositoryVisibility,
+  remoteName: Schema.optional(TrimmedNonEmptyString),
+  protocol: Schema.optional(SourceControlCloneProtocol),
+});
+export type SourceControlPublishRepositoryInput = typeof SourceControlPublishRepositoryInput.Type;
+
+export const SourceControlPublishStatus = Schema.Literals(["pushed", "remote_added"]);
+export type SourceControlPublishStatus = typeof SourceControlPublishStatus.Type;
+
+export const SourceControlPublishRepositoryResult = Schema.Struct({
+  repository: SourceControlRepositoryInfo,
+  remoteName: TrimmedNonEmptyString,
+  remoteUrl: TrimmedNonEmptyString,
+  branch: TrimmedNonEmptyString,
+  upstreamBranch: Schema.optional(TrimmedNonEmptyString),
+  status: SourceControlPublishStatus,
+});
+export type SourceControlPublishRepositoryResult = typeof SourceControlPublishRepositoryResult.Type;
+
+export const SourceControlDiscoveryStatus = Schema.Literals(["available", "missing"]);
+export type SourceControlDiscoveryStatus = typeof SourceControlDiscoveryStatus.Type;
+
+export const SourceControlProviderAuthStatus = Schema.Literals([
+  "authenticated",
+  "unauthenticated",
+  "unknown",
+]);
+export type SourceControlProviderAuthStatus = typeof SourceControlProviderAuthStatus.Type;
+
+export const SourceControlProviderAuth = Schema.Struct({
+  status: SourceControlProviderAuthStatus,
+  account: Schema.Option(TrimmedNonEmptyString),
+  host: Schema.Option(TrimmedNonEmptyString),
+  detail: Schema.Option(TrimmedNonEmptyString),
+});
+export type SourceControlProviderAuth = typeof SourceControlProviderAuth.Type;
+
+const SourceControlDiscoverySharedFields = {
+  label: TrimmedNonEmptyString,
+  executable: Schema.optional(TrimmedNonEmptyString),
+  status: SourceControlDiscoveryStatus,
+  version: Schema.Option(TrimmedNonEmptyString),
+  installHint: TrimmedNonEmptyString,
+  detail: Schema.Option(TrimmedNonEmptyString),
+} as const;
+
+export const VcsDiscoveryItem = Schema.Struct({
+  kind: VcsDriverKind,
+  implemented: Schema.Boolean,
+  ...SourceControlDiscoverySharedFields,
+});
+export type VcsDiscoveryItem = typeof VcsDiscoveryItem.Type;
+
+export const SourceControlProviderDiscoveryItem = Schema.Struct({
+  kind: SourceControlProviderKind,
+  ...SourceControlDiscoverySharedFields,
+  auth: SourceControlProviderAuth,
+});
+export type SourceControlProviderDiscoveryItem = typeof SourceControlProviderDiscoveryItem.Type;
+
+export const SourceControlDiscoveryResult = Schema.Struct({
+  versionControlSystems: Schema.Array(VcsDiscoveryItem),
+  sourceControlProviders: Schema.Array(SourceControlProviderDiscoveryItem),
+});
+export type SourceControlDiscoveryResult = typeof SourceControlDiscoveryResult.Type;
+
+export class SourceControlProviderError extends Schema.TaggedErrorClass<SourceControlProviderError>()(
+  "SourceControlProviderError",
+  {
+    provider: SourceControlProviderKind,
+    operation: Schema.String,
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `Source control provider ${this.provider} failed in ${this.operation}: ${this.detail}`;
+  }
+}
+
+export class SourceControlRepositoryError extends Schema.TaggedErrorClass<SourceControlRepositoryError>()(
+  "SourceControlRepositoryError",
+  {
+    provider: SourceControlProviderKind,
+    operation: Schema.String,
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `Source control repository operation ${this.operation} failed for ${this.provider}: ${this.detail}`;
+  }
+}
diff --git a/packages/contracts/src/terminal.test.ts b/packages/contracts/src/terminal.test.ts
index 1bef8db3a0b..1f96570acf8 100644
--- a/packages/contracts/src/terminal.test.ts
+++ b/packages/contracts/src/terminal.test.ts
@@ -1,4 +1,4 @@
-import { Schema } from "effect";
+import * as Schema from "effect/Schema";
 import { describe, expect, it } from "vitest";
 
 import {
@@ -11,7 +11,7 @@ import {
   TerminalSessionSnapshot,
   TerminalThreadInput,
   TerminalWriteInput,
-} from "./terminal";
+} from "./terminal.ts";
 
 function decodeSync<S extends Schema.Top>(schema: S, input: unknown): Schema.Schema.Type<S> {
   return Schema.decodeUnknownSync(schema as never)(input) as Schema.Schema.Type<S>;
@@ -38,13 +38,24 @@ describe("TerminalOpenInput", () => {
     ).toBe(true);
   });
 
+  it("accepts ultrawide terminal dimensions from xterm fit", () => {
+    expect(
+      decodes(TerminalOpenInput, {
+        threadId: "thread-1",
+        cwd: "/tmp/project",
+        cols: 423,
+        rows: 40,
+      }),
+    ).toBe(true);
+  });
+
   it("rejects invalid bounds", () => {
     expect(
       decodes(TerminalOpenInput, {
         threadId: "thread-1",
         cwd: "/tmp/project",
         cols: 10,
-        rows: 2,
+        rows: 0,
       }),
     ).toBe(false);
   });
@@ -153,6 +164,8 @@ describe("TerminalCloseInput", () => {
 });
 
 describe("TerminalSessionSnapshot", () => {
+  const isoTimestamp = "2026-01-01T00:00:00.000Z";
+
   it("accepts running snapshots", () => {
     expect(
       decodes(TerminalSessionSnapshot, {
@@ -165,20 +178,22 @@ describe("TerminalSessionSnapshot", () => {
         history: "hello\n",
         exitCode: null,
         exitSignal: null,
-        updatedAt: new Date().toISOString(),
+        updatedAt: isoTimestamp,
       }),
     ).toBe(true);
   });
 });
 
 describe("TerminalEvent", () => {
+  const isoTimestamp = "2026-01-01T00:00:00.000Z";
+
   it("accepts output events", () => {
     expect(
       decodes(TerminalEvent, {
         type: "output",
         threadId: "thread-1",
         terminalId: DEFAULT_TERMINAL_ID,
-        createdAt: new Date().toISOString(),
+        createdAt: isoTimestamp,
         data: "line\n",
       }),
     ).toBe(true);
@@ -190,7 +205,7 @@ describe("TerminalEvent", () => {
         type: "exited",
         threadId: "thread-1",
         terminalId: DEFAULT_TERMINAL_ID,
-        createdAt: new Date().toISOString(),
+        createdAt: isoTimestamp,
         exitCode: 0,
         exitSignal: null,
       }),
@@ -203,7 +218,7 @@ describe("TerminalEvent", () => {
         type: "activity",
         threadId: "thread-1",
         terminalId: DEFAULT_TERMINAL_ID,
-        createdAt: new Date().toISOString(),
+        createdAt: isoTimestamp,
         hasRunningSubprocess: true,
       }),
     ).toBe(true);
@@ -215,7 +230,7 @@ describe("TerminalEvent", () => {
         type: "started",
         threadId: "thread-1",
         terminalId: DEFAULT_TERMINAL_ID,
-        createdAt: new Date().toISOString(),
+        createdAt: isoTimestamp,
         snapshot: {
           threadId: "thread-1",
           terminalId: DEFAULT_TERMINAL_ID,
@@ -226,7 +241,7 @@ describe("TerminalEvent", () => {
           history: "",
           exitCode: null,
           exitSignal: null,
-          updatedAt: new Date().toISOString(),
+          updatedAt: isoTimestamp,
         },
       }),
     ).toBe(true);
diff --git a/packages/contracts/src/terminal.ts b/packages/contracts/src/terminal.ts
index 3fe883b4420..a26de01099c 100644
--- a/packages/contracts/src/terminal.ts
+++ b/packages/contracts/src/terminal.ts
@@ -1,14 +1,15 @@
-import { Effect, Schema } from "effect";
-import { TrimmedNonEmptyString } from "./baseSchemas";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
 
 export const DEFAULT_TERMINAL_ID = "default";
 
 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
-const TerminalColsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(20)).check(
-  Schema.isLessThanOrEqualTo(400),
+const TerminalColsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).check(
+  Schema.isLessThanOrEqualTo(1000),
 );
-const TerminalRowsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(5)).check(
-  Schema.isLessThanOrEqualTo(200),
+const TerminalRowsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).check(
+  Schema.isLessThanOrEqualTo(500),
 );
 const TerminalIdSchema = TrimmedNonEmptyStringSchema.check(Schema.isMaxLength(128));
 const TerminalEnvKeySchema = Schema.String.check(
@@ -169,10 +170,13 @@ export class TerminalCwdError extends Schema.TaggedErrorClass<TerminalCwdError>(
       return `Terminal cwd does not exist: ${this.cwd}`;
     }
     const causeMessage =
-      this.cause && typeof this.cause === "object" && "message" in this.cause
+      this.cause !== undefined &&
+      this.cause !== null &&
+      typeof this.cause === "object" &&
+      "message" in this.cause
         ? this.cause.message
         : undefined;
-    return causeMessage
+    return typeof causeMessage === "string" && causeMessage.length > 0
       ? `Failed to access terminal cwd: ${this.cwd} (${causeMessage})`
       : `Failed to access terminal cwd: ${this.cwd}`;
   }
diff --git a/packages/contracts/src/vcs.ts b/packages/contracts/src/vcs.ts
new file mode 100644
index 00000000000..f52f825ec3f
--- /dev/null
+++ b/packages/contracts/src/vcs.ts
@@ -0,0 +1,232 @@
+import * as Schema from "effect/Schema";
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
+
+export const VcsDriverKind = Schema.Literals(["git", "jj", "unknown"]);
+export type VcsDriverKind = typeof VcsDriverKind.Type;
+
+export const VcsFreshnessSource = Schema.Literals([
+  "live-local",
+  "cached-local",
+  "cached-remote",
+  "explicit-remote",
+]);
+export type VcsFreshnessSource = typeof VcsFreshnessSource.Type;
+
+export const VcsFreshness = Schema.Struct({
+  source: VcsFreshnessSource,
+  observedAt: Schema.DateTimeUtc,
+  expiresAt: Schema.Option(Schema.DateTimeUtc),
+});
+export type VcsFreshness = typeof VcsFreshness.Type;
+
+export const VcsDriverCapabilities = Schema.Struct({
+  kind: VcsDriverKind,
+  supportsWorktrees: Schema.Boolean,
+  supportsBookmarks: Schema.Boolean,
+  supportsAtomicSnapshot: Schema.Boolean,
+  supportsPushDefaultRemote: Schema.Boolean,
+  ignoreClassifier: Schema.Literals(["native", "git-compatible-fallback"]),
+});
+export type VcsDriverCapabilities = typeof VcsDriverCapabilities.Type;
+
+export const VcsRepositoryIdentity = Schema.Struct({
+  kind: VcsDriverKind,
+  rootPath: TrimmedNonEmptyString,
+  metadataPath: Schema.NullOr(TrimmedNonEmptyString),
+  freshness: VcsFreshness,
+});
+export type VcsRepositoryIdentity = typeof VcsRepositoryIdentity.Type;
+
+export const VcsListWorkspaceFilesResult = Schema.Struct({
+  paths: Schema.Array(TrimmedNonEmptyString),
+  truncated: Schema.Boolean,
+  freshness: VcsFreshness,
+});
+export type VcsListWorkspaceFilesResult = typeof VcsListWorkspaceFilesResult.Type;
+
+export const VcsRemote = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  url: TrimmedNonEmptyString,
+  pushUrl: Schema.Option(TrimmedNonEmptyString),
+  isPrimary: Schema.Boolean,
+});
+export type VcsRemote = typeof VcsRemote.Type;
+
+export const VcsListRemotesResult = Schema.Struct({
+  remotes: Schema.Array(VcsRemote),
+  freshness: VcsFreshness,
+});
+export type VcsListRemotesResult = typeof VcsListRemotesResult.Type;
+
+export interface VcsProcessErrorContext {
+  readonly operation: string;
+  readonly command: string;
+  readonly cwd: string;
+}
+
+export interface VcsProcessSpawnFailure {
+  readonly cause: unknown;
+}
+
+export interface VcsProcessStdinFailure {
+  readonly cause: unknown;
+}
+
+export interface VcsProcessReadFailure {
+  readonly stream: "stdout" | "stderr" | "exitCode";
+  readonly cause: unknown;
+}
+
+export interface VcsProcessOutputLimitFailure {
+  readonly stream: "stdout" | "stderr";
+  readonly maxBytes: number;
+}
+
+export interface VcsProcessTimeoutFailure {
+  readonly timeoutMs: number;
+}
+
+export class VcsProcessSpawnError extends Schema.TaggedErrorClass<VcsProcessSpawnError>()(
+  "VcsProcessSpawnError",
+  {
+    operation: Schema.String,
+    command: Schema.String,
+    cwd: Schema.String,
+    cause: Schema.Defect,
+  },
+) {
+  override get message(): string {
+    return `VCS process failed to spawn in ${this.operation}: ${this.command} (${this.cwd})`;
+  }
+
+  static fromProcessSpawnError(context: VcsProcessErrorContext, error: VcsProcessSpawnFailure) {
+    return new VcsProcessSpawnError({
+      ...context,
+      cause: error.cause,
+    });
+  }
+}
+
+export class VcsProcessExitError extends Schema.TaggedErrorClass<VcsProcessExitError>()(
+  "VcsProcessExitError",
+  {
+    operation: Schema.String,
+    command: Schema.String,
+    cwd: Schema.String,
+    exitCode: Schema.Number,
+    detail: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `VCS process failed in ${this.operation}: ${this.command} (${this.cwd}) exited with ${this.exitCode} - ${this.detail}`;
+  }
+}
+
+export class VcsProcessTimeoutError extends Schema.TaggedErrorClass<VcsProcessTimeoutError>()(
+  "VcsProcessTimeoutError",
+  {
+    operation: Schema.String,
+    command: Schema.String,
+    cwd: Schema.String,
+    timeoutMs: Schema.Number,
+  },
+) {
+  override get message(): string {
+    return `VCS process timed out in ${this.operation}: ${this.command} (${this.cwd}) after ${this.timeoutMs}ms`;
+  }
+
+  static fromProcessTimeoutError(context: VcsProcessErrorContext, error: VcsProcessTimeoutFailure) {
+    return new VcsProcessTimeoutError({
+      ...context,
+      timeoutMs: error.timeoutMs,
+    });
+  }
+}
+
+export class VcsOutputDecodeError extends Schema.TaggedErrorClass<VcsOutputDecodeError>()(
+  "VcsOutputDecodeError",
+  {
+    operation: Schema.String,
+    command: Schema.String,
+    cwd: Schema.String,
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `VCS output decode failed in ${this.operation}: ${this.command} (${this.cwd}) - ${this.detail}`;
+  }
+
+  static fromProcessStdinError(context: VcsProcessErrorContext, error: VcsProcessStdinFailure) {
+    return new VcsOutputDecodeError({
+      ...context,
+      detail: "failed to write process stdin",
+      cause: error.cause,
+    });
+  }
+
+  static fromProcessReadError(context: VcsProcessErrorContext, error: VcsProcessReadFailure) {
+    return new VcsOutputDecodeError({
+      ...context,
+      detail:
+        error.stream === "exitCode"
+          ? "failed to read process exit code"
+          : `failed to read process ${error.stream}`,
+      cause: error.cause,
+    });
+  }
+
+  static fromProcessOutputLimitError(
+    context: VcsProcessErrorContext,
+    error: VcsProcessOutputLimitFailure,
+  ) {
+    return new VcsOutputDecodeError({
+      ...context,
+      detail: `process ${error.stream} exceeded ${error.maxBytes} bytes`,
+    });
+  }
+
+  static missingExitCode(context: VcsProcessErrorContext) {
+    return new VcsOutputDecodeError({
+      ...context,
+      detail: "process completed without an exit code",
+    });
+  }
+}
+
+export class VcsRepositoryDetectionError extends Schema.TaggedErrorClass<VcsRepositoryDetectionError>()(
+  "VcsRepositoryDetectionError",
+  {
+    operation: Schema.String,
+    cwd: Schema.String,
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message(): string {
+    return `VCS repository detection failed in ${this.operation}: ${this.cwd} - ${this.detail}`;
+  }
+}
+
+export class VcsUnsupportedOperationError extends Schema.TaggedErrorClass<VcsUnsupportedOperationError>()(
+  "VcsUnsupportedOperationError",
+  {
+    operation: Schema.String,
+    kind: VcsDriverKind,
+    detail: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `VCS operation is unsupported for ${this.kind} in ${this.operation}: ${this.detail}`;
+  }
+}
+
+export const VcsError = Schema.Union([
+  VcsProcessSpawnError,
+  VcsProcessExitError,
+  VcsProcessTimeoutError,
+  VcsOutputDecodeError,
+  VcsRepositoryDetectionError,
+  VcsUnsupportedOperationError,
+]);
+export type VcsError = typeof VcsError.Type;
diff --git a/packages/contracts/tsconfig.json b/packages/contracts/tsconfig.json
index 92d639f99bd..73a306f847a 100644
--- a/packages/contracts/tsconfig.json
+++ b/packages/contracts/tsconfig.json
@@ -1,18 +1,5 @@
 {
   "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "plugins": [
-      {
-        "name": "@effect/language-service",
-        "namespaceImportPackages": ["@effect/platform-node"],
-        "diagnosticSeverity": {
-          "importFromBarrel": "error",
-          "anyUnknownInErrorContext": "warning",
-          "instanceOfSchema": "warning",
-          "deterministicKeys": "warning"
-        }
-      }
-    ]
-  },
+  "compilerOptions": {},
   "include": ["src"]
 }
diff --git a/packages/effect-acp/package.json b/packages/effect-acp/package.json
new file mode 100644
index 00000000000..c6233cb421d
--- /dev/null
+++ b/packages/effect-acp/package.json
@@ -0,0 +1,51 @@
+{
+  "name": "effect-acp",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./client": {
+      "types": "./src/client.ts",
+      "import": "./src/client.ts"
+    },
+    "./agent": {
+      "types": "./src/agent.ts",
+      "import": "./src/agent.ts"
+    },
+    "./schema": {
+      "types": "./src/schema.ts",
+      "import": "./src/schema.ts"
+    },
+    "./rpc": {
+      "types": "./src/rpc.ts",
+      "import": "./src/rpc.ts"
+    },
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "import": "./src/protocol.ts"
+    },
+    "./terminal": {
+      "types": "./src/terminal.ts",
+      "import": "./src/terminal.ts"
+    },
+    "./errors": {
+      "types": "./src/errors.ts",
+      "import": "./src/errors.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "generate": "bun run scripts/generate.ts"
+  },
+  "dependencies": {
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@effect/openapi-generator": "catalog:",
+    "@effect/platform-node": "catalog:",
+    "@effect/vitest": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/packages/effect-acp/scripts/generate.ts b/packages/effect-acp/scripts/generate.ts
new file mode 100644
index 00000000000..374f636df1e
--- /dev/null
+++ b/packages/effect-acp/scripts/generate.ts
@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { make as makeJsonSchemaGenerator } from "@effect/openapi-generator/JsonSchemaGenerator";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { Command, Flag } from "effect/unstable/cli";
+import { FetchHttpClient, HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+const CURRENT_SCHEMA_RELEASE = "v0.11.3";
+
+interface GenerateCommandError {
+  readonly _tag: "GenerateCommandError";
+  readonly message: string;
+}
+
+interface GeneratedPaths {
+  readonly generatedDir: string;
+  readonly upstreamSchemaPath: string;
+  readonly upstreamMetaPath: string;
+  readonly schemaOutputPath: string;
+  readonly metaOutputPath: string;
+}
+
+const UpstreamJsonSchemaSchema = Schema.Struct({
+  $defs: Schema.Record(Schema.String, Schema.Json),
+});
+const MetaJsonSchema = Schema.Struct({
+  agentMethods: Schema.Record(Schema.String, Schema.String),
+  clientMethods: Schema.Record(Schema.String, Schema.String),
+  version: Schema.Union([Schema.Number, Schema.String]),
+});
+const encodeAgentMethods = Schema.encodeEffect(
+  Schema.fromJsonString(MetaJsonSchema.fields.agentMethods),
+);
+const encodeClientMethods = Schema.encodeEffect(
+  Schema.fromJsonString(MetaJsonSchema.fields.clientMethods),
+);
+const encodeVersion = Schema.encodeEffect(Schema.fromJsonString(MetaJsonSchema.fields.version));
+
+const decodeUpstreamSchema = Schema.decodeEffect(Schema.fromJsonString(UpstreamJsonSchemaSchema));
+const decodeMetaJson = Schema.decodeEffect(Schema.fromJsonString(MetaJsonSchema));
+
+const getGeneratedPaths = Effect.fn("getGeneratedPaths")(function* () {
+  const path = yield* Path.Path;
+  const generatedDir = path.join(import.meta.dirname, "..", "src", "_generated");
+  return {
+    generatedDir,
+    upstreamSchemaPath: path.join(generatedDir, "upstream-schema.json"),
+    upstreamMetaPath: path.join(generatedDir, "upstream-meta.json"),
+    schemaOutputPath: path.join(generatedDir, "schema.gen.ts"),
+    metaOutputPath: path.join(generatedDir, "meta.gen.ts"),
+  } satisfies GeneratedPaths;
+});
+
+const ensureGeneratedDir = Effect.fn("ensureGeneratedDir")(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const { generatedDir } = yield* getGeneratedPaths();
+
+  yield* fs.makeDirectory(generatedDir, { recursive: true });
+});
+
+const downloadFile = Effect.fn("downloadFile")(function* (url: string, outputPath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  yield* fs.makeDirectory(path.dirname(outputPath), { recursive: true });
+
+  const text = yield* HttpClient.get(url).pipe(
+    Effect.flatMap(HttpClientResponse.filterStatusOk),
+    Effect.flatMap((response) => response.text),
+  );
+
+  yield* fs.writeFileString(outputPath, text);
+});
+
+const downloadSchemas = Effect.fn("downloadSchemas")(function* (tag: string) {
+  const { upstreamMetaPath, upstreamSchemaPath } = yield* getGeneratedPaths();
+  const fs = yield* FileSystem.FileSystem;
+  const baseUrl = `https://github.com/agentclientprotocol/agent-client-protocol/releases/download/${tag}`;
+
+  yield* downloadFile(`${baseUrl}/schema.unstable.json`, upstreamSchemaPath);
+  yield* downloadFile(`${baseUrl}/meta.unstable.json`, upstreamMetaPath);
+
+  yield* Effect.addFinalizer(() =>
+    Effect.all([fs.remove(upstreamSchemaPath), fs.remove(upstreamMetaPath)]).pipe(
+      Effect.ignoreCause({ log: true }),
+    ),
+  );
+});
+
+const readFileString = Effect.fn("readJsonFile")(function* (filePath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  return yield* fs.readFileString(filePath);
+});
+
+const writeGeneratedFiles = Effect.fn("writeGeneratedFiles")(function* (
+  schemaOutput: string,
+  metaOutput: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const { metaOutputPath, schemaOutputPath } = yield* getGeneratedPaths();
+
+  yield* fs.writeFileString(schemaOutputPath, schemaOutput);
+  yield* fs.writeFileString(metaOutputPath, metaOutput);
+});
+
+function collectSchemaEntries(
+  chunk: string,
+): ReadonlyArray<{ readonly name: string; readonly code: string }> {
+  const lines = chunk
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("//"));
+  const entries: Array<{ name: string; code: string }> = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const typeLine = lines[index];
+    if (!typeLine?.startsWith("export type ")) {
+      continue;
+    }
+
+    const constLine = lines[index + 1];
+    if (!constLine?.startsWith("export const ")) {
+      throw new Error(`Malformed generator output near: ${typeLine}`);
+    }
+
+    const match = /^export type ([A-Za-z0-9_]+)/.exec(typeLine);
+    if (!match?.[1]) {
+      throw new Error(`Could not extract schema name from: ${typeLine}`);
+    }
+
+    entries.push({
+      name: match[1],
+      code: `${typeLine}\n${constLine}`,
+    });
+    index += 1;
+  }
+
+  return entries;
+}
+
+function normalizeNullableTypes(value: typeof Schema.Json.Type): typeof Schema.Json.Type {
+  if (Array.isArray(value)) {
+    return value.map(normalizeNullableTypes);
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  const normalizedEntries = Object.entries(value).map(([key, child]) => [
+    key,
+    normalizeNullableTypes(child),
+  ]);
+  const normalizedObject = Object.fromEntries(normalizedEntries) as Record<
+    string,
+    typeof Schema.Json.Type
+  >;
+  const typeValue = normalizedObject.type;
+
+  if (!Array.isArray(typeValue)) {
+    return normalizedObject;
+  }
+
+  const normalizedTypes = typeValue.filter((entry): entry is string => typeof entry === "string");
+  if (normalizedTypes.length !== typeValue.length || !normalizedTypes.includes("null")) {
+    return normalizedObject;
+  }
+
+  const nonNullTypes = normalizedTypes.filter((entry) => entry !== "null");
+  if (nonNullTypes.length !== 1) {
+    return normalizedObject;
+  }
+  const nonNullType = nonNullTypes[0]!;
+
+  const nextObject: Record<string, typeof Schema.Json.Type> = {};
+  for (const [key, child] of Object.entries(normalizedObject)) {
+    if (key !== "type") {
+      nextObject[key] = child;
+    }
+  }
+
+  return {
+    anyOf: [
+      {
+        ...nextObject,
+        type: nonNullType,
+      },
+      { type: "null" },
+    ],
+  };
+}
+
+const generateSchemas = Effect.fn("generateSchemas")(function* (skipDownload: boolean) {
+  const { upstreamMetaPath, upstreamSchemaPath } = yield* getGeneratedPaths();
+
+  yield* ensureGeneratedDir();
+
+  if (!skipDownload) {
+    yield* Effect.log(`Downloading ACP schema assets for ${CURRENT_SCHEMA_RELEASE}`);
+    yield* downloadSchemas(CURRENT_SCHEMA_RELEASE);
+  }
+
+  const upstreamSchema = yield* readFileString(upstreamSchemaPath).pipe(
+    Effect.flatMap(decodeUpstreamSchema),
+  );
+  const upstreamMeta = yield* readFileString(upstreamMetaPath).pipe(Effect.flatMap(decodeMetaJson));
+  const normalizedDefinitions = Object.fromEntries(
+    Object.entries(upstreamSchema.$defs).map(([name, schema]) => [
+      name,
+      normalizeNullableTypes(schema),
+    ]),
+  );
+
+  const sortedEntries = Object.entries(normalizedDefinitions).toSorted(([left], [right]) =>
+    left.localeCompare(right),
+  );
+  const generatedEntries = new Map<string, string>();
+  const generator = makeJsonSchemaGenerator();
+
+  for (const [name, schema] of sortedEntries) {
+    generator.addSchema(name, schema as never);
+  }
+
+  const output = generator.generate("openapi-3.1", normalizedDefinitions as never, false).trim();
+  if (output.length > 0) {
+    for (const entry of collectSchemaEntries(output)) {
+      if (!generatedEntries.has(entry.name)) {
+        generatedEntries.set(entry.name, entry.code);
+      }
+    }
+  }
+
+  const prelude = [
+    `// This file is generated by the effect-acp package. Do not edit manually.`,
+    `// Current ACP schema release: ${CURRENT_SCHEMA_RELEASE}`,
+    "",
+  ];
+
+  const schemaOutput = [
+    ...prelude,
+    'import * as Schema from "effect/Schema";',
+    "",
+    [...generatedEntries.values()].join("\n\n"),
+    "",
+  ].join("\n");
+
+  const metaOutput = [
+    ...prelude,
+    `export const AGENT_METHODS = ${yield* encodeAgentMethods(upstreamMeta.agentMethods)} as const;`,
+    "",
+    `export const CLIENT_METHODS = ${yield* encodeClientMethods(upstreamMeta.clientMethods)} as const;`,
+    "",
+    `export const PROTOCOL_VERSION = ${yield* encodeVersion(upstreamMeta.version)} as const;`,
+    "",
+  ].join("\n");
+
+  yield* writeGeneratedFiles(schemaOutput, metaOutput);
+  yield* Effect.log(
+    `Generated ${generatedEntries.size} ACP schemas from ${CURRENT_SCHEMA_RELEASE}`,
+  );
+
+  const { generatedDir } = yield* getGeneratedPaths();
+  yield* Effect.service(ChildProcessSpawner.ChildProcessSpawner).pipe(
+    Effect.flatMap((spawner) => spawner.spawn(ChildProcess.make("bun", ["oxfmt", generatedDir]))),
+    Effect.flatMap((child) => child.exitCode),
+    Effect.tap((code) =>
+      code === 0
+        ? Effect.void
+        : Effect.fail<GenerateCommandError>({
+            _tag: "GenerateCommandError",
+            message: `oxfmt failed with exit code ${code}`,
+          }),
+    ),
+  );
+});
+
+const generateCommand = Command.make(
+  "generate",
+  {
+    skipDownload: Flag.boolean("skip-download").pipe(Flag.withDefault(false)),
+  },
+  ({ skipDownload }) => generateSchemas(skipDownload),
+).pipe(Command.withDescription("Generate Effect ACP schemas from the pinned ACP release assets."));
+
+const runtimeLayer = Layer.mergeAll(
+  Logger.layer([Logger.consolePretty()]),
+  NodeServices.layer,
+  FetchHttpClient.layer,
+);
+
+Command.run(generateCommand, { version: "0.0.0" }).pipe(
+  Effect.scoped,
+  Effect.provide(runtimeLayer),
+  NodeRuntime.runMain,
+);
diff --git a/packages/effect-acp/src/_generated/meta.gen.ts b/packages/effect-acp/src/_generated/meta.gen.ts
new file mode 100644
index 00000000000..5d2dd3dd3dd
--- /dev/null
+++ b/packages/effect-acp/src/_generated/meta.gen.ts
@@ -0,0 +1,35 @@
+// This file is generated by the effect-acp package. Do not edit manually.
+// Current ACP schema release: v0.11.3
+
+export const AGENT_METHODS = {
+  authenticate: "authenticate",
+  initialize: "initialize",
+  logout: "logout",
+  session_cancel: "session/cancel",
+  session_close: "session/close",
+  session_fork: "session/fork",
+  session_list: "session/list",
+  session_load: "session/load",
+  session_new: "session/new",
+  session_prompt: "session/prompt",
+  session_resume: "session/resume",
+  session_set_config_option: "session/set_config_option",
+  session_set_mode: "session/set_mode",
+  session_set_model: "session/set_model",
+} as const;
+
+export const CLIENT_METHODS = {
+  fs_read_text_file: "fs/read_text_file",
+  fs_write_text_file: "fs/write_text_file",
+  session_elicitation: "session/elicitation",
+  session_elicitation_complete: "session/elicitation/complete",
+  session_request_permission: "session/request_permission",
+  session_update: "session/update",
+  terminal_create: "terminal/create",
+  terminal_kill: "terminal/kill",
+  terminal_output: "terminal/output",
+  terminal_release: "terminal/release",
+  terminal_wait_for_exit: "terminal/wait_for_exit",
+} as const;
+
+export const PROTOCOL_VERSION = 1 as const;
diff --git a/packages/effect-acp/src/_generated/schema.gen.ts b/packages/effect-acp/src/_generated/schema.gen.ts
new file mode 100644
index 00000000000..73fdc752364
--- /dev/null
+++ b/packages/effect-acp/src/_generated/schema.gen.ts
@@ -0,0 +1,10375 @@
+// This file is generated by the effect-acp package. Do not edit manually.
+// Current ACP schema release: v0.11.3
+
+import * as Schema from "effect/Schema";
+
+export type AuthEnvVar = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly label?: string | null;
+  readonly name: string;
+  readonly optional?: boolean;
+  readonly secret?: boolean;
+};
+export const AuthEnvVar = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  label: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Human-readable label for this variable, displayed in client UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  name: Schema.String.annotate({
+    description: 'The environment variable name (e.g. `"OPENAI_API_KEY"`).',
+  }),
+  optional: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Whether this variable is optional.\n\nDefaults to `false`.",
+      default: false,
+    }),
+  ),
+  secret: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Whether this value is a secret (e.g. API key, token).\nClients should use a password-style input for secret vars.\n\nDefaults to `true`.",
+      default: true,
+    }),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nDescribes a single environment variable for an [`AuthMethodEnvVar`] authentication method.",
+});
+
+export type AvailableCommandInput = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly hint: string;
+};
+export const AvailableCommandInput = Schema.Union([
+  Schema.Struct({
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    hint: Schema.String.annotate({
+      description: "A hint to display when the input hasn't been provided yet",
+    }),
+  }).annotate({
+    title: "unstructured",
+    description: "All text that was typed after the command name is provided as input.",
+  }),
+]).annotate({ description: "The input specification for a command." });
+
+export type Cost = { readonly amount: number; readonly currency: string };
+export const Cost = Schema.Struct({
+  amount: Schema.Number.annotate({
+    description: "Total cumulative cost for session.",
+    format: "double",
+  }).check(Schema.isFinite()),
+  currency: Schema.String.annotate({ description: 'ISO 4217 currency code (e.g., "USD", "EUR").' }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCost information for a session.",
+});
+
+export type ElicitationContentValue = string | number | number | boolean | ReadonlyArray<string>;
+export const ElicitationContentValue = Schema.Union([
+  Schema.String.annotate({ title: "String" }),
+  Schema.Number.annotate({ title: "Integer", format: "int64" }).check(Schema.isInt()),
+  Schema.Number.annotate({ title: "Number", format: "double" }).check(Schema.isFinite()),
+  Schema.Boolean.annotate({ title: "Boolean" }),
+  Schema.Array(Schema.String).annotate({ title: "StringArray" }),
+]);
+
+export type ElicitationFormCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+};
+export const ElicitationFormCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForm-based elicitation capabilities.",
+});
+
+export type ElicitationUrlCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+};
+export const ElicitationUrlCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nURL-based elicitation capabilities.",
+});
+
+export type EmbeddedResourceResource =
+  | {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly mimeType?: string | null;
+      readonly text: string;
+      readonly uri: string;
+    }
+  | {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly blob: string;
+      readonly mimeType?: string | null;
+      readonly uri: string;
+    };
+export const EmbeddedResourceResource = Schema.Union([
+  Schema.Struct({
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    text: Schema.String,
+    uri: Schema.String,
+  }).annotate({ title: "TextResourceContents", description: "Text-based resource contents." }),
+  Schema.Struct({
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    blob: Schema.String,
+    mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    uri: Schema.String,
+  }).annotate({ title: "BlobResourceContents", description: "Binary resource contents." }),
+]).annotate({ description: "Resource content that can be embedded in a message." });
+
+export type EnumOption = { readonly const: string; readonly title: string };
+export const EnumOption = Schema.Struct({
+  const: Schema.String.annotate({ description: "The constant value for this option." }),
+  title: Schema.String.annotate({ description: "Human-readable title for this option." }),
+}).annotate({ description: "A titled enum option with a const value and human-readable title." });
+
+export type EnvVariable = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly name: string;
+  readonly value: string;
+};
+export const EnvVariable = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  name: Schema.String.annotate({ description: "The name of the environment variable." }),
+  value: Schema.String.annotate({ description: "The value to set for the environment variable." }),
+}).annotate({ description: "An environment variable to set when launching an MCP server." });
+
+export type Error = {
+  readonly code:
+    | -32700
+    | -32600
+    | -32601
+    | -32602
+    | -32603
+    | -32800
+    | -32000
+    | -32002
+    | -32042
+    | number;
+  readonly data?: unknown;
+  readonly message: string;
+};
+export const Error = Schema.Struct({
+  code: Schema.Union([
+    Schema.Literal(-32700).annotate({
+      title: "Parse error",
+      description:
+        "**Parse error**: Invalid JSON was received by the server.\nAn error occurred on the server while parsing the JSON text.",
+      format: "int32",
+    }),
+    Schema.Literal(-32600).annotate({
+      title: "Invalid request",
+      description: "**Invalid request**: The JSON sent is not a valid Request object.",
+      format: "int32",
+    }),
+    Schema.Literal(-32601).annotate({
+      title: "Method not found",
+      description: "**Method not found**: The method does not exist or is not available.",
+      format: "int32",
+    }),
+    Schema.Literal(-32602).annotate({
+      title: "Invalid params",
+      description: "**Invalid params**: Invalid method parameter(s).",
+      format: "int32",
+    }),
+    Schema.Literal(-32603).annotate({
+      title: "Internal error",
+      description:
+        "**Internal error**: Internal JSON-RPC error.\nReserved for implementation-defined server errors.",
+      format: "int32",
+    }),
+    Schema.Literal(-32800).annotate({
+      title: "Request cancelled",
+      description:
+        "**Request cancelled**: **UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nExecution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.",
+      format: "int32",
+    }),
+    Schema.Literal(-32000).annotate({
+      title: "Authentication required",
+      description:
+        "**Authentication required**: Authentication is required before this operation can be performed.",
+      format: "int32",
+    }),
+    Schema.Literal(-32002).annotate({
+      title: "Resource not found",
+      description: "**Resource not found**: A given resource, such as a file, was not found.",
+      format: "int32",
+    }),
+    Schema.Literal(-32042).annotate({
+      title: "URL elicitation required",
+      description:
+        "**URL elicitation required**: **UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe agent requires user input via a URL-based elicitation before it can proceed.",
+      format: "int32",
+    }),
+    Schema.Number.annotate({
+      title: "Other",
+      description: "Other undefined error code.",
+      format: "int32",
+    }).check(Schema.isInt()),
+  ]).annotate({
+    description:
+      "Predefined error codes for common JSON-RPC and ACP-specific errors.\n\nThese codes follow the JSON-RPC 2.0 specification for standard errors\nand use the reserved range (-32000 to -32099) for protocol-specific errors.",
+  }),
+  data: Schema.optionalKey(
+    Schema.Unknown.annotate({
+      description:
+        "Optional primitive or structured value that contains additional information about the error.\nThis may include debugging information or context-specific details.",
+    }),
+  ),
+  message: Schema.String.annotate({
+    description:
+      "A string providing a short description of the error.\nThe message should be limited to a concise single sentence.",
+  }),
+}).annotate({
+  description:
+    "JSON-RPC error object.\n\nRepresents an error that occurred during method execution, following the\nJSON-RPC 2.0 error object specification with optional additional data.\n\nSee protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object)",
+});
+
+export type HttpHeader = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly name: string;
+  readonly value: string;
+};
+export const HttpHeader = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  name: Schema.String.annotate({ description: "The name of the HTTP header." }),
+  value: Schema.String.annotate({ description: "The value to set for the HTTP header." }),
+}).annotate({ description: "An HTTP header to set when making requests to the MCP server." });
+
+export type Implementation = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly name: string;
+  readonly title?: string | null;
+  readonly version: string;
+};
+export const Implementation = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  name: Schema.String.annotate({
+    description:
+      "Intended for programmatic or logical use, but can be used as a display\nname fallback if title isn’t present.",
+  }),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Intended for UI and end-user contexts — optimized to be human-readable\nand easily understood.\n\nIf not provided, the name should be used for display.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  version: Schema.String.annotate({
+    description:
+      'Version of the implementation. Can be displayed to the user or used\nfor debugging or metrics purposes. (e.g. "1.0.0").',
+  }),
+}).annotate({
+  description:
+    "Metadata about the implementation of the client or agent.\nDescribes the name and version of an MCP implementation, with an optional\ntitle for UI representation.",
+});
+
+export type LogoutCapabilities = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const LogoutCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nLogout capabilities supported by the agent.\n\nBy supplying `{}` it means that the agent supports the logout method.",
+});
+
+export type ModelInfo = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly description?: string | null;
+  readonly modelId: string;
+  readonly name: string;
+};
+export const ModelInfo = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional description of the model." }),
+      Schema.Null,
+    ]),
+  ),
+  modelId: Schema.String.annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for a model.",
+  }),
+  name: Schema.String.annotate({ description: "Human-readable name of the model." }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInformation about a selectable model.",
+});
+
+export type PermissionOption = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+  readonly name: string;
+  readonly optionId: string;
+};
+export const PermissionOption = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  kind: Schema.Literals(["allow_once", "allow_always", "reject_once", "reject_always"]).annotate({
+    description:
+      "The type of permission option being presented to the user.\n\nHelps clients choose appropriate icons and UI treatment.",
+  }),
+  name: Schema.String.annotate({ description: "Human-readable label to display to the user." }),
+  optionId: Schema.String.annotate({ description: "Unique identifier for a permission option." }),
+}).annotate({ description: "An option presented to the user when requesting permission." });
+
+export type PlanEntry = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly content: string;
+  readonly priority: "high" | "medium" | "low";
+  readonly status: "pending" | "in_progress" | "completed";
+};
+export const PlanEntry = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  content: Schema.String.annotate({
+    description: "Human-readable description of what this task aims to accomplish.",
+  }),
+  priority: Schema.Literals(["high", "medium", "low"]).annotate({
+    description:
+      "Priority levels for plan entries.\n\nUsed to indicate the relative importance or urgency of different\ntasks in the execution plan.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)",
+  }),
+  status: Schema.Literals(["pending", "in_progress", "completed"]).annotate({
+    description:
+      "Status of a plan entry in the execution flow.\n\nTracks the lifecycle of each task from planning through completion.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)",
+  }),
+}).annotate({
+  description:
+    "A single entry in the execution plan.\n\nRepresents a task or goal that the assistant intends to accomplish\nas part of fulfilling the user's request.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)",
+});
+
+export type RequestId = null | number | string;
+export const RequestId = Schema.Union([
+  Schema.Null.annotate({ title: "Null" }),
+  Schema.Number.annotate({ title: "Number", format: "int64" }).check(Schema.isInt()),
+  Schema.String.annotate({ title: "Str" }),
+]).annotate({
+  description:
+    "JSON RPC Request Id\n\nAn identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]\n\nThe Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.\n\n[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.\n\n[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.",
+});
+
+export type Role = "assistant" | "user";
+export const Role = Schema.Literals(["assistant", "user"]).annotate({
+  description: "The sender or recipient of messages and data in a conversation.",
+});
+
+export type SessionCloseCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+};
+export const SessionCloseCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for the `session/close` method.\n\nBy supplying `{}` it means that the agent supports closing of sessions.",
+});
+
+export type SessionConfigOptionCategory = "mode" | "model" | "thought_level" | string;
+export const SessionConfigOptionCategory = Schema.Union([
+  Schema.Literal("mode").annotate({ description: "Session mode selector." }),
+  Schema.Literal("model").annotate({ description: "Model selector." }),
+  Schema.Literal("thought_level").annotate({ description: "Thought/reasoning level selector." }),
+  Schema.String.annotate({ title: "other", description: "Unknown / uncategorized selector." }),
+]).annotate({
+  description:
+    "Semantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec.",
+});
+
+export type SessionConfigSelectOption = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly description?: string | null;
+  readonly name: string;
+  readonly value: string;
+};
+export const SessionConfigSelectOption = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional description for this option value." }),
+      Schema.Null,
+    ]),
+  ),
+  name: Schema.String.annotate({ description: "Human-readable label for this option value." }),
+  value: Schema.String.annotate({
+    description: "Unique identifier for a session configuration option value.",
+  }),
+}).annotate({ description: "A possible value for a session configuration option." });
+
+export type SessionForkCapabilities = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const SessionForkCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for the `session/fork` method.\n\nBy supplying `{}` it means that the agent supports forking of sessions.",
+});
+
+export type SessionInfo = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly cwd: string;
+  readonly sessionId: string;
+  readonly title?: string | null;
+  readonly updatedAt?: string | null;
+};
+export const SessionInfo = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.String.annotate({
+    description: "The working directory for this session. Must be an absolute path.",
+  }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Human-readable title for the session" }),
+      Schema.Null,
+    ]),
+  ),
+  updatedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "ISO 8601 timestamp of last activity" }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Information about a session returned by session/list" });
+
+export type SessionListCapabilities = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const SessionListCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "Capabilities for the `session/list` method.\n\nBy supplying `{}` it means that the agent supports listing of sessions.",
+});
+
+export type SessionModeId = string;
+export const SessionModeId = Schema.String.annotate({
+  description: "Unique identifier for a Session Mode.",
+});
+
+export type SessionResumeCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+};
+export const SessionResumeCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for the `session/resume` method.\n\nBy supplying `{}` it means that the agent supports resuming of sessions.",
+});
+
+export type StringFormat = "email" | "uri" | "date" | "date-time";
+export const StringFormat = Schema.Literals(["email", "uri", "date", "date-time"]).annotate({
+  description: "String format types for string properties in elicitation schemas.",
+});
+
+export type TerminalExitStatus = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly exitCode?: number | null;
+  readonly signal?: string | null;
+};
+export const TerminalExitStatus = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  exitCode: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "The process exit code (may be null if terminated by signal).",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  signal: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "The signal that terminated the process (may be null if exited normally).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Exit status of a terminal command." });
+
+export type ToolCallLocation = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly line?: number | null;
+  readonly path: string;
+};
+export const ToolCallLocation = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  line: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional line number within the file.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.String.annotate({ description: "The file path being accessed or modified." }),
+}).annotate({
+  description:
+    'A file location being accessed or modified by a tool.\n\nEnables clients to implement "follow-along" features that track\nwhich files the agent is working with in real-time.\n\nSee protocol docs: [Following the Agent](https://agentclientprotocol.com/protocol/tool-calls#following-the-agent)',
+});
+
+export type ToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+export const ToolCallStatus = Schema.Literals([
+  "pending",
+  "in_progress",
+  "completed",
+  "failed",
+]).annotate({
+  description:
+    "Execution status of a tool call.\n\nTool calls progress through different statuses during their lifecycle.\n\nSee protocol docs: [Status](https://agentclientprotocol.com/protocol/tool-calls#status)",
+});
+
+export type ToolKind =
+  | "read"
+  | "edit"
+  | "delete"
+  | "move"
+  | "search"
+  | "execute"
+  | "think"
+  | "fetch"
+  | "switch_mode"
+  | "other";
+export const ToolKind = Schema.Literals([
+  "read",
+  "edit",
+  "delete",
+  "move",
+  "search",
+  "execute",
+  "think",
+  "fetch",
+  "switch_mode",
+  "other",
+]).annotate({
+  description:
+    "Categories of tools that can be invoked.\n\nTool kinds help clients choose appropriate icons and optimize how they\ndisplay tool execution progress.\n\nSee protocol docs: [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating)",
+});
+
+export type Usage = {
+  readonly cachedReadTokens?: number | null;
+  readonly cachedWriteTokens?: number | null;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly thoughtTokens?: number | null;
+  readonly totalTokens: number;
+};
+export const Usage = Schema.Struct({
+  cachedReadTokens: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Total cache read tokens.", format: "uint64" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  cachedWriteTokens: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Total cache write tokens.", format: "uint64" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  inputTokens: Schema.Number.annotate({
+    description: "Total input tokens across all turns.",
+    format: "uint64",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  outputTokens: Schema.Number.annotate({
+    description: "Total output tokens across all turns.",
+    format: "uint64",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  thoughtTokens: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Total thought/reasoning tokens", format: "uint64" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  totalTokens: Schema.Number.annotate({
+    description: "Sum of all token types across session.",
+    format: "uint64",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage information for a prompt turn.",
+});
+
+export type AuthMethod =
+  | {
+      readonly type: "env_var";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly description?: string | null;
+      readonly id: string;
+      readonly link?: string | null;
+      readonly name: string;
+      readonly vars: ReadonlyArray<AuthEnvVar>;
+    }
+  | {
+      readonly type: "terminal";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly args?: ReadonlyArray<string>;
+      readonly description?: string | null;
+      readonly env?: { readonly [x: string]: string };
+      readonly id: string;
+      readonly name: string;
+    }
+  | {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly description?: string | null;
+      readonly id: string;
+      readonly name: string;
+    };
+export const AuthMethod = Schema.Union([
+  Schema.Struct({
+    type: Schema.Literal("env_var"),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    description: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description:
+            "Optional description providing more details about this authentication method.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    id: Schema.String.annotate({
+      description: "Unique identifier for this authentication method.",
+    }),
+    link: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description: "Optional link to a page where the user can obtain their credentials.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    name: Schema.String.annotate({
+      description: "Human-readable name of the authentication method.",
+    }),
+    vars: Schema.Array(AuthEnvVar).annotate({
+      description: "The environment variables the client should set.",
+    }),
+  }).annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nEnvironment variable authentication method.\n\nThe user provides credentials that the client passes to the agent as environment variables.",
+  }),
+  Schema.Struct({
+    type: Schema.Literal("terminal"),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    args: Schema.optionalKey(
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Additional arguments to pass when running the agent binary for terminal auth.",
+      }),
+    ),
+    description: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description:
+            "Optional description providing more details about this authentication method.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    env: Schema.optionalKey(
+      Schema.Record(Schema.String, Schema.String).annotate({
+        description:
+          "Additional environment variables to set when running the agent binary for terminal auth.",
+      }),
+    ),
+    id: Schema.String.annotate({
+      description: "Unique identifier for this authentication method.",
+    }),
+    name: Schema.String.annotate({
+      description: "Human-readable name of the authentication method.",
+    }),
+  }).annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nTerminal-based authentication method.\n\nThe client runs an interactive terminal for the user to authenticate via a TUI.",
+  }),
+  Schema.Struct({
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    description: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description:
+            "Optional description providing more details about this authentication method.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    id: Schema.String.annotate({
+      description: "Unique identifier for this authentication method.",
+    }),
+    name: Schema.String.annotate({
+      description: "Human-readable name of the authentication method.",
+    }),
+  }).annotate({
+    title: "agent",
+    description:
+      "Agent handles authentication itself.\n\nThis is the default authentication method type.",
+  }),
+]).annotate({
+  description:
+    "Describes an available authentication method.\n\nThe `type` field acts as the discriminator in the serialized JSON form.\nWhen no `type` is present, the method is treated as `agent`.",
+});
+
+export type AvailableCommand = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly description: string;
+  readonly input?: AvailableCommandInput | null;
+  readonly name: string;
+};
+export const AvailableCommand = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.String.annotate({
+    description: "Human-readable description of what the command does.",
+  }),
+  input: Schema.optionalKey(
+    Schema.Union([AvailableCommandInput, Schema.Null]).annotate({
+      description: "Input for the command if required",
+    }),
+  ),
+  name: Schema.String.annotate({
+    description: "Command name (e.g., `create_plan`, `research_codebase`).",
+  }),
+}).annotate({ description: "Information about a command." });
+
+export type ElicitationCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly form?: ElicitationFormCapabilities | null;
+  readonly url?: ElicitationUrlCapabilities | null;
+};
+export const ElicitationCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  form: Schema.optionalKey(
+    Schema.Union([ElicitationFormCapabilities, Schema.Null]).annotate({
+      description: "Whether the client supports form-based elicitation.",
+    }),
+  ),
+  url: Schema.optionalKey(
+    Schema.Union([ElicitationUrlCapabilities, Schema.Null]).annotate({
+      description: "Whether the client supports URL-based elicitation.",
+    }),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation capabilities supported by the client.",
+});
+
+export type McpServer =
+  | {
+      readonly type: "http";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly headers: ReadonlyArray<HttpHeader>;
+      readonly name: string;
+      readonly url: string;
+    }
+  | {
+      readonly type: "sse";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly headers: ReadonlyArray<HttpHeader>;
+      readonly name: string;
+      readonly url: string;
+    }
+  | {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly args: ReadonlyArray<string>;
+      readonly command: string;
+      readonly env: ReadonlyArray<EnvVariable>;
+      readonly name: string;
+    };
+export const McpServer = Schema.Union([
+  Schema.Struct({
+    type: Schema.Literal("http"),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    headers: Schema.Array(HttpHeader).annotate({
+      description: "HTTP headers to set when making requests to the MCP server.",
+    }),
+    name: Schema.String.annotate({
+      description: "Human-readable name identifying this MCP server.",
+    }),
+    url: Schema.String.annotate({ description: "URL to the MCP server." }),
+  }).annotate({ description: "HTTP transport configuration for MCP." }),
+  Schema.Struct({
+    type: Schema.Literal("sse"),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    headers: Schema.Array(HttpHeader).annotate({
+      description: "HTTP headers to set when making requests to the MCP server.",
+    }),
+    name: Schema.String.annotate({
+      description: "Human-readable name identifying this MCP server.",
+    }),
+    url: Schema.String.annotate({ description: "URL to the MCP server." }),
+  }).annotate({ description: "SSE transport configuration for MCP." }),
+  Schema.Struct({
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    args: Schema.Array(Schema.String).annotate({
+      description: "Command-line arguments to pass to the MCP server.",
+    }),
+    command: Schema.String.annotate({ description: "Path to the MCP server executable." }),
+    env: Schema.Array(EnvVariable).annotate({
+      description: "Environment variables to set when launching the MCP server.",
+    }),
+    name: Schema.String.annotate({
+      description: "Human-readable name identifying this MCP server.",
+    }),
+  }).annotate({ title: "stdio", description: "Stdio transport configuration for MCP." }),
+]).annotate({
+  description:
+    "Configuration for connecting to an MCP (Model Context Protocol) server.\n\nMCP servers provide tools and context that the agent can use when\nprocessing prompts.\n\nSee protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers)",
+});
+
+export type SessionModelState = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly availableModels: ReadonlyArray<ModelInfo>;
+  readonly currentModelId: string;
+};
+export const SessionModelState = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  availableModels: Schema.Array(ModelInfo).annotate({
+    description: "The set of models that the Agent can use",
+  }),
+  currentModelId: Schema.String.annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for a model.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe set of models and the one currently active.",
+});
+
+export type Annotations = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly audience?: ReadonlyArray<Role> | null;
+  readonly lastModified?: string | null;
+  readonly priority?: number | null;
+};
+export const Annotations = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  audience: Schema.optionalKey(Schema.Union([Schema.Array(Role), Schema.Null])),
+  lastModified: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  priority: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "double" }).check(Schema.isFinite()),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "Optional annotations for the client. The client can use annotations to inform how objects are used or displayed",
+});
+
+export type SessionConfigSelectGroup = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly group: string;
+  readonly name: string;
+  readonly options: ReadonlyArray<SessionConfigSelectOption>;
+};
+export const SessionConfigSelectGroup = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  group: Schema.String.annotate({
+    description: "Unique identifier for a session configuration option value group.",
+  }),
+  name: Schema.String.annotate({ description: "Human-readable label for this group." }),
+  options: Schema.Array(SessionConfigSelectOption).annotate({
+    description: "The set of option values in this group.",
+  }),
+}).annotate({ description: "A group of possible values for a session configuration option." });
+
+export type SessionMode = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly description?: string | null;
+  readonly id: SessionModeId;
+  readonly name: string;
+};
+export const SessionMode = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  id: SessionModeId,
+  name: Schema.String,
+}).annotate({
+  description:
+    "A mode the agent can operate in.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+});
+
+export type ElicitationPropertySchema =
+  | {
+      readonly type: "string";
+      readonly default?: string | null;
+      readonly description?: string | null;
+      readonly enum?: ReadonlyArray<string> | null;
+      readonly format?: StringFormat | null;
+      readonly maxLength?: number | null;
+      readonly minLength?: number | null;
+      readonly oneOf?: ReadonlyArray<EnumOption> | null;
+      readonly pattern?: string | null;
+      readonly title?: string | null;
+    }
+  | {
+      readonly type: "number";
+      readonly default?: number | null;
+      readonly description?: string | null;
+      readonly maximum?: number | null;
+      readonly minimum?: number | null;
+      readonly title?: string | null;
+    }
+  | {
+      readonly type: "integer";
+      readonly default?: number | null;
+      readonly description?: string | null;
+      readonly maximum?: number | null;
+      readonly minimum?: number | null;
+      readonly title?: string | null;
+    }
+  | {
+      readonly type: "boolean";
+      readonly default?: boolean | null;
+      readonly description?: string | null;
+      readonly title?: string | null;
+    }
+  | {
+      readonly type: "array";
+      readonly default?: ReadonlyArray<string> | null;
+      readonly description?: string | null;
+      readonly items:
+        | { readonly enum: ReadonlyArray<string>; readonly type: "string" }
+        | { readonly anyOf: ReadonlyArray<EnumOption> };
+      readonly maxItems?: number | null;
+      readonly minItems?: number | null;
+      readonly title?: string | null;
+    };
+export const ElicitationPropertySchema = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("string"),
+      default: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ description: "Default value." }), Schema.Null]),
+      ),
+      description: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Human-readable description." }),
+          Schema.Null,
+        ]),
+      ),
+      enum: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(Schema.String).annotate({
+            description: "Enum values for untitled single-select enums.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      format: Schema.optionalKey(
+        Schema.Union([StringFormat, Schema.Null]).annotate({ description: "String format." }),
+      ),
+      maxLength: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ description: "Maximum string length.", format: "uint32" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      minLength: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ description: "Minimum string length.", format: "uint32" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      oneOf: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(EnumOption).annotate({
+            description: "Titled enum options for titled single-select enums.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      pattern: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Pattern the string must match." }),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Optional title for the property." }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({
+      description:
+        'Schema for string properties in an elicitation form.\n\nWhen `enum` or `oneOf` is set, this represents a single-select enum\nwith `"type": "string"`.',
+    }),
+    Schema.Struct({
+      type: Schema.Literal("number"),
+      default: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ description: "Default value.", format: "double" }).check(
+            Schema.isFinite(),
+          ),
+          Schema.Null,
+        ]),
+      ),
+      description: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Human-readable description." }),
+          Schema.Null,
+        ]),
+      ),
+      maximum: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "Maximum value (inclusive).",
+            format: "double",
+          }).check(Schema.isFinite()),
+          Schema.Null,
+        ]),
+      ),
+      minimum: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "Minimum value (inclusive).",
+            format: "double",
+          }).check(Schema.isFinite()),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Optional title for the property." }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({
+      description: "Schema for number (floating-point) properties in an elicitation form.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("integer"),
+      default: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ description: "Default value.", format: "int64" }).check(
+            Schema.isInt(),
+          ),
+          Schema.Null,
+        ]),
+      ),
+      description: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Human-readable description." }),
+          Schema.Null,
+        ]),
+      ),
+      maximum: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "Maximum value (inclusive).",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      minimum: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "Minimum value (inclusive).",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Optional title for the property." }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({ description: "Schema for integer properties in an elicitation form." }),
+    Schema.Struct({
+      type: Schema.Literal("boolean"),
+      default: Schema.optionalKey(
+        Schema.Union([Schema.Boolean.annotate({ description: "Default value." }), Schema.Null]),
+      ),
+      description: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Human-readable description." }),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Optional title for the property." }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({ description: "Schema for boolean properties in an elicitation form." }),
+    Schema.Struct({
+      type: Schema.Literal("array"),
+      default: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(Schema.String).annotate({ description: "Default selected values." }),
+          Schema.Null,
+        ]),
+      ),
+      description: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Human-readable description." }),
+          Schema.Null,
+        ]),
+      ),
+      items: Schema.Union([
+        Schema.Struct({
+          enum: Schema.Array(Schema.String).annotate({ description: "Allowed enum values." }),
+          type: Schema.Literal("string").annotate({
+            description: "Items definition for untitled multi-select enum properties.",
+          }),
+        }).annotate({
+          title: "Untitled",
+          description: "Items definition for untitled multi-select enum properties.",
+        }),
+        Schema.Struct({
+          anyOf: Schema.Array(EnumOption).annotate({ description: "Titled enum options." }),
+        }).annotate({
+          title: "Titled",
+          description: "Items definition for titled multi-select enum properties.",
+        }),
+      ]).annotate({ description: "Items for a multi-select (array) property schema." }),
+      maxItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "Maximum number of items to select.",
+            format: "uint64",
+          })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      minItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "Minimum number of items to select.",
+            format: "uint64",
+          })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Optional title for the property." }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({
+      description: "Schema for multi-select (array) properties in an elicitation form.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    'Property schema for elicitation form fields.\n\nEach variant corresponds to a JSON Schema `"type"` value.\nSingle-select enums use the `String` variant with `enum` or `oneOf` set.\nMulti-select enums use the `Array` variant.',
+});
+
+export type ContentBlock =
+  | {
+      readonly type: "text";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly annotations?: Annotations | null;
+      readonly text: string;
+    }
+  | {
+      readonly type: "image";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly annotations?: Annotations | null;
+      readonly data: string;
+      readonly mimeType: string;
+      readonly uri?: string | null;
+    }
+  | {
+      readonly type: "audio";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly annotations?: Annotations | null;
+      readonly data: string;
+      readonly mimeType: string;
+    }
+  | {
+      readonly type: "resource_link";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly annotations?: Annotations | null;
+      readonly description?: string | null;
+      readonly mimeType?: string | null;
+      readonly name: string;
+      readonly size?: number | null;
+      readonly title?: string | null;
+      readonly uri: string;
+    }
+  | {
+      readonly type: "resource";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly annotations?: Annotations | null;
+      readonly resource: EmbeddedResourceResource;
+    };
+export const ContentBlock = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("text"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+      text: Schema.String,
+    }).annotate({ description: "Text provided to or from an LLM." }),
+    Schema.Struct({
+      type: Schema.Literal("image"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+      data: Schema.String,
+      mimeType: Schema.String,
+      uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ description: "An image provided to or from an LLM." }),
+    Schema.Struct({
+      type: Schema.Literal("audio"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+      data: Schema.String,
+      mimeType: Schema.String,
+    }).annotate({ description: "Audio provided to or from an LLM." }),
+    Schema.Struct({
+      type: Schema.Literal("resource_link"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+      description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      name: Schema.String,
+      size: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      uri: Schema.String,
+    }).annotate({
+      description:
+        "A resource that the server is capable of reading, included in a prompt or tool call result.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("resource"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+      resource: EmbeddedResourceResource,
+    }).annotate({
+      description: "The contents of a resource, embedded into a prompt or tool call result.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+});
+
+export type ToolCallContent =
+  | {
+      readonly type: "content";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly content:
+        | {
+            readonly type: "text";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly text: string;
+          }
+        | {
+            readonly type: "image";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+            readonly uri?: string | null;
+          }
+        | {
+            readonly type: "audio";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+          }
+        | {
+            readonly type: "resource_link";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly description?: string | null;
+            readonly mimeType?: string | null;
+            readonly name: string;
+            readonly size?: number | null;
+            readonly title?: string | null;
+            readonly uri: string;
+          }
+        | {
+            readonly type: "resource";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly resource: EmbeddedResourceResource;
+          };
+    }
+  | {
+      readonly type: "diff";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly newText: string;
+      readonly oldText?: string | null;
+      readonly path: string;
+    }
+  | {
+      readonly type: "terminal";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly terminalId: string;
+    };
+export const ToolCallContent = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("content"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      content: Schema.Union(
+        [
+          Schema.Struct({
+            type: Schema.Literal("text"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            text: Schema.String,
+          }).annotate({ description: "Text provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("image"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+            uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+          }).annotate({ description: "An image provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("audio"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+          }).annotate({ description: "Audio provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("resource_link"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            name: Schema.String,
+            size: Schema.optionalKey(
+              Schema.Union([
+                Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                Schema.Null,
+              ]),
+            ),
+            title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            uri: Schema.String,
+          }).annotate({
+            description:
+              "A resource that the server is capable of reading, included in a prompt or tool call result.",
+          }),
+          Schema.Struct({
+            type: Schema.Literal("resource"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            resource: EmbeddedResourceResource,
+          }).annotate({
+            description: "The contents of a resource, embedded into a prompt or tool call result.",
+          }),
+        ],
+        { mode: "oneOf" },
+      ).annotate({
+        description:
+          "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+      }),
+    }).annotate({ description: "Standard content block (text, images, resources)." }),
+    Schema.Struct({
+      type: Schema.Literal("diff"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      newText: Schema.String.annotate({ description: "The new content after modification." }),
+      oldText: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "The original content (None for new files)." }),
+          Schema.Null,
+        ]),
+      ),
+      path: Schema.String.annotate({ description: "The file path being modified." }),
+    }).annotate({
+      description:
+        "A diff representing file modifications.\n\nShows changes to files in a format suitable for display in the client UI.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("terminal"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      terminalId: Schema.String,
+    }).annotate({
+      description:
+        "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "Content produced by a tool call.\n\nTool calls can produce different types of content including\nstandard content blocks (text, images) or file diffs.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)",
+});
+
+export type SessionConfigOption =
+  | {
+      readonly type: "select";
+      readonly currentValue: string;
+      readonly options:
+        | ReadonlyArray<SessionConfigSelectOption>
+        | ReadonlyArray<SessionConfigSelectGroup>;
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly category?: SessionConfigOptionCategory | null;
+      readonly description?: string | null;
+      readonly id: string;
+      readonly name: string;
+    }
+  | {
+      readonly type: "boolean";
+      readonly currentValue: boolean;
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly category?: SessionConfigOptionCategory | null;
+      readonly description?: string | null;
+      readonly id: string;
+      readonly name: string;
+    };
+export const SessionConfigOption = Schema.Union([
+  Schema.Struct({
+    type: Schema.Literal("select"),
+    currentValue: Schema.String.annotate({
+      description: "Unique identifier for a session configuration option value.",
+    }),
+    options: Schema.Union([
+      Schema.Array(SessionConfigSelectOption).annotate({
+        title: "Ungrouped",
+        description: "A flat list of options with no grouping.",
+      }),
+      Schema.Array(SessionConfigSelectGroup).annotate({
+        title: "Grouped",
+        description: "A list of options grouped under headers.",
+      }),
+    ]).annotate({ description: "Possible values for a session configuration option." }),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    category: Schema.optionalKey(
+      Schema.Union([SessionConfigOptionCategory, Schema.Null]).annotate({
+        description: "Optional semantic category for this option (UX only).",
+      }),
+    ),
+    description: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description: "Optional description for the Client to display to the user.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    id: Schema.String.annotate({
+      description: "Unique identifier for a session configuration option.",
+    }),
+    name: Schema.String.annotate({ description: "Human-readable label for the option." }),
+  }).annotate({ description: "A session configuration option selector and its current state." }),
+  Schema.Struct({
+    type: Schema.Literal("boolean"),
+    currentValue: Schema.Boolean.annotate({
+      description: "The current value of the boolean option.",
+    }),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    category: Schema.optionalKey(
+      Schema.Union([SessionConfigOptionCategory, Schema.Null]).annotate({
+        description: "Optional semantic category for this option (UX only).",
+      }),
+    ),
+    description: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description: "Optional description for the Client to display to the user.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    id: Schema.String.annotate({
+      description: "Unique identifier for a session configuration option.",
+    }),
+    name: Schema.String.annotate({ description: "Human-readable label for the option." }),
+  }).annotate({ description: "A session configuration option selector and its current state." }),
+]);
+
+export type SessionModeState = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly availableModes: ReadonlyArray<SessionMode>;
+  readonly currentModeId: string;
+};
+export const SessionModeState = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  availableModes: Schema.Array(SessionMode).annotate({
+    description: "The set of modes that the Agent can operate in",
+  }),
+  currentModeId: Schema.String.annotate({ description: "Unique identifier for a Session Mode." }),
+}).annotate({ description: "The set of modes and the one currently active." });
+
+export type AgentAuthCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly logout?: LogoutCapabilities | null;
+};
+export const AgentAuthCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  logout: Schema.optionalKey(
+    Schema.Union([LogoutCapabilities, Schema.Null]).annotate({
+      description:
+        "Whether the agent supports the logout method.\n\nBy supplying `{}` it means that the agent supports the logout method.",
+    }),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication-related capabilities supported by the agent.",
+});
+
+export type AgentCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly auth?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly logout?: LogoutCapabilities | null;
+  };
+  readonly loadSession?: boolean;
+  readonly mcpCapabilities?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly http?: boolean;
+    readonly sse?: boolean;
+  };
+  readonly promptCapabilities?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly audio?: boolean;
+    readonly embeddedContext?: boolean;
+    readonly image?: boolean;
+  };
+  readonly sessionCapabilities?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly close?: SessionCloseCapabilities | null;
+    readonly fork?: SessionForkCapabilities | null;
+    readonly list?: SessionListCapabilities | null;
+    readonly resume?: SessionResumeCapabilities | null;
+  };
+};
+export const AgentCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  auth: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      logout: Schema.optionalKey(
+        Schema.Union([LogoutCapabilities, Schema.Null]).annotate({
+          description:
+            "Whether the agent supports the logout method.\n\nBy supplying `{}` it means that the agent supports the logout method.",
+        }),
+      ),
+    }).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication-related capabilities supported by the agent.",
+      default: {},
+    }),
+  ),
+  loadSession: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Whether the agent supports `session/load`.",
+      default: false,
+    }),
+  ),
+  mcpCapabilities: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      http: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Agent supports [`McpServer::Http`].",
+          default: false,
+        }),
+      ),
+      sse: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Agent supports [`McpServer::Sse`].",
+          default: false,
+        }),
+      ),
+    }).annotate({
+      description: "MCP capabilities supported by the agent",
+      default: { http: false, sse: false },
+    }),
+  ),
+  promptCapabilities: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      audio: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Agent supports [`ContentBlock::Audio`].",
+          default: false,
+        }),
+      ),
+      embeddedContext: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description:
+            "Agent supports embedded context in `session/prompt` requests.\n\nWhen enabled, the Client is allowed to include [`ContentBlock::Resource`]\nin prompt requests for pieces of context that are referenced in the message.",
+          default: false,
+        }),
+      ),
+      image: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Agent supports [`ContentBlock::Image`].",
+          default: false,
+        }),
+      ),
+    }).annotate({
+      description:
+        "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for [`ContentBlock::Text`]\nand [`ContentBlock::ResourceLink`] in prompt requests.\n\nOther variants must be explicitly opted in to.\nCapabilities for different types of content in prompt requests.\n\nIndicates which content types beyond the baseline (text and resource links)\nthe agent can process.\n\nSee protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)",
+      default: { audio: false, embeddedContext: false, image: false },
+    }),
+  ),
+  sessionCapabilities: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      close: Schema.optionalKey(
+        Schema.Union([SessionCloseCapabilities, Schema.Null]).annotate({
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/close`.",
+        }),
+      ),
+      fork: Schema.optionalKey(
+        Schema.Union([SessionForkCapabilities, Schema.Null]).annotate({
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/fork`.",
+        }),
+      ),
+      list: Schema.optionalKey(
+        Schema.Union([SessionListCapabilities, Schema.Null]).annotate({
+          description: "Whether the agent supports `session/list`.",
+        }),
+      ),
+      resume: Schema.optionalKey(
+        Schema.Union([SessionResumeCapabilities, Schema.Null]).annotate({
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/resume`.",
+        }),
+      ),
+    }).annotate({
+      default: {},
+      description:
+        "Session capabilities supported by the agent.\n\nAs a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nOptionally, they **MAY** support other session methods and notifications by specifying additional capabilities.\n\nNote: `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities)",
+    }),
+  ),
+}).annotate({
+  description:
+    "Capabilities supported by the agent.\n\nAdvertised during initialization to inform the client about\navailable features and content types.\n\nSee protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities)",
+});
+
+export type AgentNotification = {
+  readonly method: string;
+  readonly params?:
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly sessionId: string;
+        readonly update:
+          | {
+              readonly sessionUpdate: "user_message_chunk";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly content:
+                | {
+                    readonly type: "text";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly text: string;
+                  }
+                | {
+                    readonly type: "image";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly data: string;
+                    readonly mimeType: string;
+                    readonly uri?: string | null;
+                  }
+                | {
+                    readonly type: "audio";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly data: string;
+                    readonly mimeType: string;
+                  }
+                | {
+                    readonly type: "resource_link";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly description?: string | null;
+                    readonly mimeType?: string | null;
+                    readonly name: string;
+                    readonly size?: number | null;
+                    readonly title?: string | null;
+                    readonly uri: string;
+                  }
+                | {
+                    readonly type: "resource";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly resource: EmbeddedResourceResource;
+                  };
+              readonly messageId?: string | null;
+            }
+          | {
+              readonly sessionUpdate: "agent_message_chunk";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly content:
+                | {
+                    readonly type: "text";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly text: string;
+                  }
+                | {
+                    readonly type: "image";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly data: string;
+                    readonly mimeType: string;
+                    readonly uri?: string | null;
+                  }
+                | {
+                    readonly type: "audio";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly data: string;
+                    readonly mimeType: string;
+                  }
+                | {
+                    readonly type: "resource_link";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly description?: string | null;
+                    readonly mimeType?: string | null;
+                    readonly name: string;
+                    readonly size?: number | null;
+                    readonly title?: string | null;
+                    readonly uri: string;
+                  }
+                | {
+                    readonly type: "resource";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly resource: EmbeddedResourceResource;
+                  };
+              readonly messageId?: string | null;
+            }
+          | {
+              readonly sessionUpdate: "agent_thought_chunk";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly content:
+                | {
+                    readonly type: "text";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly text: string;
+                  }
+                | {
+                    readonly type: "image";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly data: string;
+                    readonly mimeType: string;
+                    readonly uri?: string | null;
+                  }
+                | {
+                    readonly type: "audio";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly data: string;
+                    readonly mimeType: string;
+                  }
+                | {
+                    readonly type: "resource_link";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly description?: string | null;
+                    readonly mimeType?: string | null;
+                    readonly name: string;
+                    readonly size?: number | null;
+                    readonly title?: string | null;
+                    readonly uri: string;
+                  }
+                | {
+                    readonly type: "resource";
+                    readonly _meta?: { readonly [x: string]: unknown } | null;
+                    readonly annotations?: Annotations | null;
+                    readonly resource: EmbeddedResourceResource;
+                  };
+              readonly messageId?: string | null;
+            }
+          | {
+              readonly sessionUpdate: "tool_call";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly content?: ReadonlyArray<ToolCallContent>;
+              readonly kind?:
+                | "read"
+                | "edit"
+                | "delete"
+                | "move"
+                | "search"
+                | "execute"
+                | "think"
+                | "fetch"
+                | "switch_mode"
+                | "other";
+              readonly locations?: ReadonlyArray<ToolCallLocation>;
+              readonly rawInput?: unknown;
+              readonly rawOutput?: unknown;
+              readonly status?: "pending" | "in_progress" | "completed" | "failed";
+              readonly title: string;
+              readonly toolCallId: string;
+            }
+          | {
+              readonly sessionUpdate: "tool_call_update";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly content?: ReadonlyArray<ToolCallContent> | null;
+              readonly kind?: ToolKind | null;
+              readonly locations?: ReadonlyArray<ToolCallLocation> | null;
+              readonly rawInput?: unknown;
+              readonly rawOutput?: unknown;
+              readonly status?: ToolCallStatus | null;
+              readonly title?: string | null;
+              readonly toolCallId: string;
+            }
+          | {
+              readonly sessionUpdate: "plan";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly entries: ReadonlyArray<PlanEntry>;
+            }
+          | {
+              readonly sessionUpdate: "available_commands_update";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly availableCommands: ReadonlyArray<AvailableCommand>;
+            }
+          | {
+              readonly sessionUpdate: "current_mode_update";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly currentModeId: string;
+            }
+          | {
+              readonly sessionUpdate: "config_option_update";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly configOptions: ReadonlyArray<SessionConfigOption>;
+            }
+          | {
+              readonly sessionUpdate: "session_info_update";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly title?: string | null;
+              readonly updatedAt?: string | null;
+            }
+          | {
+              readonly sessionUpdate: "usage_update";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly cost?: Cost | null;
+              readonly size: number;
+              readonly used: number;
+            };
+      }
+    | { readonly _meta?: { readonly [x: string]: unknown } | null; readonly elicitationId: string }
+    | unknown
+    | null;
+};
+export const AgentNotification = Schema.Struct({
+  method: Schema.String,
+  params: Schema.optionalKey(
+    Schema.Union([
+      Schema.Union([
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+          update: Schema.Union(
+            [
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("user_message_chunk"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                content: Schema.Union(
+                  [
+                    Schema.Struct({
+                      type: Schema.Literal("text"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      text: Schema.String,
+                    }).annotate({ description: "Text provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("image"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      data: Schema.String,
+                      mimeType: Schema.String,
+                      uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                    }).annotate({ description: "An image provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("audio"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      data: Schema.String,
+                      mimeType: Schema.String,
+                    }).annotate({ description: "Audio provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("resource_link"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      name: Schema.String,
+                      size: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                          Schema.Null,
+                        ]),
+                      ),
+                      title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      uri: Schema.String,
+                    }).annotate({
+                      description:
+                        "A resource that the server is capable of reading, included in a prompt or tool call result.",
+                    }),
+                    Schema.Struct({
+                      type: Schema.Literal("resource"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      resource: EmbeddedResourceResource,
+                    }).annotate({
+                      description:
+                        "The contents of a resource, embedded into a prompt or tool call result.",
+                    }),
+                  ],
+                  { mode: "oneOf" },
+                ).annotate({
+                  description:
+                    "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+                }),
+                messageId: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.String.annotate({
+                      description:
+                        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+              }).annotate({ description: "A streamed item of content" }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("agent_message_chunk"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                content: Schema.Union(
+                  [
+                    Schema.Struct({
+                      type: Schema.Literal("text"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      text: Schema.String,
+                    }).annotate({ description: "Text provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("image"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      data: Schema.String,
+                      mimeType: Schema.String,
+                      uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                    }).annotate({ description: "An image provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("audio"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      data: Schema.String,
+                      mimeType: Schema.String,
+                    }).annotate({ description: "Audio provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("resource_link"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      name: Schema.String,
+                      size: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                          Schema.Null,
+                        ]),
+                      ),
+                      title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      uri: Schema.String,
+                    }).annotate({
+                      description:
+                        "A resource that the server is capable of reading, included in a prompt or tool call result.",
+                    }),
+                    Schema.Struct({
+                      type: Schema.Literal("resource"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      resource: EmbeddedResourceResource,
+                    }).annotate({
+                      description:
+                        "The contents of a resource, embedded into a prompt or tool call result.",
+                    }),
+                  ],
+                  { mode: "oneOf" },
+                ).annotate({
+                  description:
+                    "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+                }),
+                messageId: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.String.annotate({
+                      description:
+                        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+              }).annotate({ description: "A streamed item of content" }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("agent_thought_chunk"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                content: Schema.Union(
+                  [
+                    Schema.Struct({
+                      type: Schema.Literal("text"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      text: Schema.String,
+                    }).annotate({ description: "Text provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("image"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      data: Schema.String,
+                      mimeType: Schema.String,
+                      uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                    }).annotate({ description: "An image provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("audio"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      data: Schema.String,
+                      mimeType: Schema.String,
+                    }).annotate({ description: "Audio provided to or from an LLM." }),
+                    Schema.Struct({
+                      type: Schema.Literal("resource_link"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      name: Schema.String,
+                      size: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                          Schema.Null,
+                        ]),
+                      ),
+                      title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+                      uri: Schema.String,
+                    }).annotate({
+                      description:
+                        "A resource that the server is capable of reading, included in a prompt or tool call result.",
+                    }),
+                    Schema.Struct({
+                      type: Schema.Literal("resource"),
+                      _meta: Schema.optionalKey(
+                        Schema.Union([
+                          Schema.Record(Schema.String, Schema.Unknown).annotate({
+                            description:
+                              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                          }),
+                          Schema.Null,
+                        ]),
+                      ),
+                      annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+                      resource: EmbeddedResourceResource,
+                    }).annotate({
+                      description:
+                        "The contents of a resource, embedded into a prompt or tool call result.",
+                    }),
+                  ],
+                  { mode: "oneOf" },
+                ).annotate({
+                  description:
+                    "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+                }),
+                messageId: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.String.annotate({
+                      description:
+                        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+              }).annotate({ description: "A streamed item of content" }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("tool_call"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                content: Schema.optionalKey(
+                  Schema.Array(ToolCallContent).annotate({
+                    description: "Content produced by the tool call.",
+                  }),
+                ),
+                kind: Schema.optionalKey(
+                  Schema.Literals([
+                    "read",
+                    "edit",
+                    "delete",
+                    "move",
+                    "search",
+                    "execute",
+                    "think",
+                    "fetch",
+                    "switch_mode",
+                    "other",
+                  ]).annotate({
+                    description:
+                      "Categories of tools that can be invoked.\n\nTool kinds help clients choose appropriate icons and optimize how they\ndisplay tool execution progress.\n\nSee protocol docs: [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating)",
+                  }),
+                ),
+                locations: Schema.optionalKey(
+                  Schema.Array(ToolCallLocation).annotate({
+                    description:
+                      'File locations affected by this tool call.\nEnables "follow-along" features in clients.',
+                  }),
+                ),
+                rawInput: Schema.optionalKey(
+                  Schema.Unknown.annotate({
+                    description: "Raw input parameters sent to the tool.",
+                  }),
+                ),
+                rawOutput: Schema.optionalKey(
+                  Schema.Unknown.annotate({ description: "Raw output returned by the tool." }),
+                ),
+                status: Schema.optionalKey(
+                  Schema.Literals(["pending", "in_progress", "completed", "failed"]).annotate({
+                    description:
+                      "Execution status of a tool call.\n\nTool calls progress through different statuses during their lifecycle.\n\nSee protocol docs: [Status](https://agentclientprotocol.com/protocol/tool-calls#status)",
+                  }),
+                ),
+                title: Schema.String.annotate({
+                  description: "Human-readable title describing what the tool is doing.",
+                }),
+                toolCallId: Schema.String.annotate({
+                  description: "Unique identifier for a tool call within a session.",
+                }),
+              }).annotate({
+                description:
+                  "Represents a tool call that the language model has requested.\n\nTool calls are actions that the agent executes on behalf of the language model,\nsuch as reading files, executing code, or fetching data from external sources.\n\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/tool-calls)",
+              }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("tool_call_update"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                content: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Array(ToolCallContent).annotate({
+                      description: "Replace the content collection.",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                kind: Schema.optionalKey(
+                  Schema.Union([ToolKind, Schema.Null]).annotate({
+                    description: "Update the tool kind.",
+                  }),
+                ),
+                locations: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Array(ToolCallLocation).annotate({
+                      description: "Replace the locations collection.",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                rawInput: Schema.optionalKey(
+                  Schema.Unknown.annotate({ description: "Update the raw input." }),
+                ),
+                rawOutput: Schema.optionalKey(
+                  Schema.Unknown.annotate({ description: "Update the raw output." }),
+                ),
+                status: Schema.optionalKey(
+                  Schema.Union([ToolCallStatus, Schema.Null]).annotate({
+                    description: "Update the execution status.",
+                  }),
+                ),
+                title: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.String.annotate({ description: "Update the human-readable title." }),
+                    Schema.Null,
+                  ]),
+                ),
+                toolCallId: Schema.String.annotate({
+                  description: "Unique identifier for a tool call within a session.",
+                }),
+              }).annotate({
+                description:
+                  "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)",
+              }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("plan"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                entries: Schema.Array(PlanEntry).annotate({
+                  description:
+                    "The list of tasks to be accomplished.\n\nWhen updating a plan, the agent must send a complete list of all entries\nwith their current status. The client replaces the entire plan with each update.",
+                }),
+              }).annotate({
+                description:
+                  "An execution plan for accomplishing complex tasks.\n\nPlans consist of multiple entries representing individual tasks or goals.\nAgents report plans to clients to provide visibility into their execution strategy.\nPlans can evolve during execution as the agent discovers new requirements or completes tasks.\n\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)",
+              }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("available_commands_update"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                availableCommands: Schema.Array(AvailableCommand).annotate({
+                  description: "Commands the agent can execute",
+                }),
+              }).annotate({ description: "Available commands are ready or have changed" }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("current_mode_update"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                currentModeId: Schema.String.annotate({
+                  description: "Unique identifier for a Session Mode.",
+                }),
+              }).annotate({
+                description:
+                  "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+              }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("config_option_update"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                configOptions: Schema.Array(SessionConfigOption).annotate({
+                  description: "The full set of configuration options and their current values.",
+                }),
+              }).annotate({ description: "Session configuration options have been updated." }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("session_info_update"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                title: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.String.annotate({
+                      description: "Human-readable title for the session. Set to null to clear.",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                updatedAt: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.String.annotate({
+                      description: "ISO 8601 timestamp of last activity. Set to null to clear.",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+              }).annotate({
+                description:
+                  "Update to session metadata. All fields are optional to support partial updates.\n\nAgents send this notification to update session information like title or custom metadata.\nThis allows clients to display dynamic session names and track session state changes.",
+              }),
+              Schema.Struct({
+                sessionUpdate: Schema.Literal("usage_update"),
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                cost: Schema.optionalKey(
+                  Schema.Union([Cost, Schema.Null]).annotate({
+                    description: "Cumulative session cost (optional).",
+                  }),
+                ),
+                size: Schema.Number.annotate({
+                  description: "Total context window size in tokens.",
+                  format: "uint64",
+                })
+                  .check(Schema.isInt())
+                  .check(Schema.isGreaterThanOrEqualTo(0)),
+                used: Schema.Number.annotate({
+                  description: "Tokens currently in context.",
+                  format: "uint64",
+                })
+                  .check(Schema.isInt())
+                  .check(Schema.isGreaterThanOrEqualTo(0)),
+              }).annotate({
+                description:
+                  "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for a session.",
+              }),
+            ],
+            { mode: "oneOf" },
+          ).annotate({
+            description:
+              "Different types of updates that can be sent during session processing.\n\nThese updates provide real-time feedback about the agent's progress.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)",
+          }),
+        }).annotate({
+          title: "SessionNotification",
+          description:
+            "Notification containing a session update from the agent.\n\nUsed to stream real-time progress and results during prompt processing.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          elicitationId: Schema.String.annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.",
+          }),
+        }).annotate({
+          title: "ElicitationCompleteNotification",
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification sent by the agent when a URL-based elicitation is complete.",
+        }),
+        Schema.Unknown.annotate({
+          title: "ExtNotification",
+          description:
+            "Allows the Agent to send an arbitrary notification that is not part of the ACP spec.\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+      ]).annotate({
+        description:
+          "All possible notifications that an agent can send to a client.\n\nThis enum is used internally for routing RPC notifications. You typically won't need\nto use this directly - use the notification methods on the [`Client`] trait instead.\n\nNotifications do not expect a response.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type AgentRequest = {
+  readonly id: RequestId;
+  readonly method: string;
+  readonly params?:
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly content: string;
+        readonly path: string;
+        readonly sessionId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly limit?: number | null;
+        readonly line?: number | null;
+        readonly path: string;
+        readonly sessionId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly options: ReadonlyArray<PermissionOption>;
+        readonly sessionId: string;
+        readonly toolCall: {
+          readonly _meta?: { readonly [x: string]: unknown } | null;
+          readonly content?: ReadonlyArray<ToolCallContent> | null;
+          readonly kind?: ToolKind | null;
+          readonly locations?: ReadonlyArray<ToolCallLocation> | null;
+          readonly rawInput?: unknown;
+          readonly rawOutput?: unknown;
+          readonly status?: ToolCallStatus | null;
+          readonly title?: string | null;
+          readonly toolCallId: string;
+        };
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly args?: ReadonlyArray<string>;
+        readonly command: string;
+        readonly cwd?: string | null;
+        readonly env?: ReadonlyArray<EnvVariable>;
+        readonly outputByteLimit?: number | null;
+        readonly sessionId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly sessionId: string;
+        readonly terminalId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly sessionId: string;
+        readonly terminalId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly sessionId: string;
+        readonly terminalId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly sessionId: string;
+        readonly terminalId: string;
+      }
+    | {
+        readonly mode: "form";
+        readonly requestedSchema: {
+          readonly description?: string | null;
+          readonly properties?: { readonly [x: string]: ElicitationPropertySchema };
+          readonly required?: ReadonlyArray<string> | null;
+          readonly title?: string | null;
+          readonly type?: "object";
+        };
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly message: string;
+        readonly sessionId: string;
+      }
+    | {
+        readonly mode: "url";
+        readonly elicitationId: string;
+        readonly url: string;
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly message: string;
+        readonly sessionId: string;
+      }
+    | unknown
+    | null;
+};
+export const AgentRequest = Schema.Struct({
+  id: RequestId,
+  method: Schema.String,
+  params: Schema.optionalKey(
+    Schema.Union([
+      Schema.Union([
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          content: Schema.String.annotate({
+            description: "The text content to write to the file.",
+          }),
+          path: Schema.String.annotate({ description: "Absolute path to the file to write." }),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "WriteTextFileRequest",
+          description:
+            "Request to write content to a text file.\n\nOnly available if the client supports the `fs.writeTextFile` capability.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          limit: Schema.optionalKey(
+            Schema.Union([
+              Schema.Number.annotate({
+                description: "Maximum number of lines to read.",
+                format: "uint32",
+              })
+                .check(Schema.isInt())
+                .check(Schema.isGreaterThanOrEqualTo(0)),
+              Schema.Null,
+            ]),
+          ),
+          line: Schema.optionalKey(
+            Schema.Union([
+              Schema.Number.annotate({
+                description: "Line number to start reading from (1-based).",
+                format: "uint32",
+              })
+                .check(Schema.isInt())
+                .check(Schema.isGreaterThanOrEqualTo(0)),
+              Schema.Null,
+            ]),
+          ),
+          path: Schema.String.annotate({ description: "Absolute path to the file to read." }),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "ReadTextFileRequest",
+          description:
+            "Request to read content from a text file.\n\nOnly available if the client supports the `fs.readTextFile` capability.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          options: Schema.Array(PermissionOption).annotate({
+            description: "Available permission options for the user to choose from.",
+          }),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+          toolCall: Schema.Struct({
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            content: Schema.optionalKey(
+              Schema.Union([
+                Schema.Array(ToolCallContent).annotate({
+                  description: "Replace the content collection.",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            kind: Schema.optionalKey(
+              Schema.Union([ToolKind, Schema.Null]).annotate({
+                description: "Update the tool kind.",
+              }),
+            ),
+            locations: Schema.optionalKey(
+              Schema.Union([
+                Schema.Array(ToolCallLocation).annotate({
+                  description: "Replace the locations collection.",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            rawInput: Schema.optionalKey(
+              Schema.Unknown.annotate({ description: "Update the raw input." }),
+            ),
+            rawOutput: Schema.optionalKey(
+              Schema.Unknown.annotate({ description: "Update the raw output." }),
+            ),
+            status: Schema.optionalKey(
+              Schema.Union([ToolCallStatus, Schema.Null]).annotate({
+                description: "Update the execution status.",
+              }),
+            ),
+            title: Schema.optionalKey(
+              Schema.Union([
+                Schema.String.annotate({ description: "Update the human-readable title." }),
+                Schema.Null,
+              ]),
+            ),
+            toolCallId: Schema.String.annotate({
+              description: "Unique identifier for a tool call within a session.",
+            }),
+          }).annotate({
+            description:
+              "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)",
+          }),
+        }).annotate({
+          title: "RequestPermissionRequest",
+          description:
+            "Request for user permission to execute a tool call.\n\nSent when the agent needs authorization before performing a sensitive operation.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          args: Schema.optionalKey(
+            Schema.Array(Schema.String).annotate({ description: "Array of command arguments." }),
+          ),
+          command: Schema.String.annotate({ description: "The command to execute." }),
+          cwd: Schema.optionalKey(
+            Schema.Union([
+              Schema.String.annotate({
+                description: "Working directory for the command (absolute path).",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          env: Schema.optionalKey(
+            Schema.Array(EnvVariable).annotate({
+              description: "Environment variables for the command.",
+            }),
+          ),
+          outputByteLimit: Schema.optionalKey(
+            Schema.Union([
+              Schema.Number.annotate({
+                description:
+                  "Maximum number of output bytes to retain.\n\nWhen the limit is exceeded, the Client truncates from the beginning of the output\nto stay within the limit.\n\nThe Client MUST ensure truncation happens at a character boundary to maintain valid\nstring output, even if this means the retained output is slightly less than the\nspecified limit.",
+                format: "uint64",
+              })
+                .check(Schema.isInt())
+                .check(Schema.isGreaterThanOrEqualTo(0)),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "CreateTerminalRequest",
+          description: "Request to create a new terminal and execute a command.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+          terminalId: Schema.String.annotate({
+            description: "The ID of the terminal to get output from.",
+          }),
+        }).annotate({
+          title: "TerminalOutputRequest",
+          description: "Request to get the current output and status of a terminal.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+          terminalId: Schema.String.annotate({ description: "The ID of the terminal to release." }),
+        }).annotate({
+          title: "ReleaseTerminalRequest",
+          description: "Request to release a terminal and free its resources.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+          terminalId: Schema.String.annotate({
+            description: "The ID of the terminal to wait for.",
+          }),
+        }).annotate({
+          title: "WaitForTerminalExitRequest",
+          description: "Request to wait for a terminal command to exit.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+          terminalId: Schema.String.annotate({ description: "The ID of the terminal to kill." }),
+        }).annotate({
+          title: "KillTerminalRequest",
+          description: "Request to kill a terminal without releasing it.",
+        }),
+        Schema.Union([
+          Schema.Struct({
+            mode: Schema.Literal("form"),
+            requestedSchema: Schema.Struct({
+              description: Schema.optionalKey(
+                Schema.Union([
+                  Schema.String.annotate({
+                    description: "Optional description of what this schema represents.",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              properties: Schema.optionalKey(
+                Schema.Record(Schema.String, ElicitationPropertySchema).annotate({
+                  description: "Property definitions (must be primitive types).",
+                  default: {},
+                }),
+              ),
+              required: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Array(Schema.String).annotate({
+                    description: "List of required property names.",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              title: Schema.optionalKey(
+                Schema.Union([
+                  Schema.String.annotate({ description: "Optional title for the schema." }),
+                  Schema.Null,
+                ]),
+              ),
+              type: Schema.optionalKey(
+                Schema.Literal("object").annotate({
+                  description: "Type discriminator for elicitation schemas.",
+                  default: "object",
+                }),
+              ),
+            }).annotate({
+              description:
+                "Type-safe elicitation schema for requesting structured user input.\n\nThis represents a JSON Schema object with primitive-typed properties,\nas required by the elicitation specification.",
+            }),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            message: Schema.String.annotate({
+              description: "A human-readable message describing what input is needed.",
+            }),
+            sessionId: Schema.String.annotate({
+              description:
+                "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+            }),
+          }).annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.",
+          }),
+          Schema.Struct({
+            mode: Schema.Literal("url"),
+            elicitationId: Schema.String.annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.",
+            }),
+            url: Schema.String.annotate({
+              description: "The URL to direct the user to.",
+              format: "uri",
+            }),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            message: Schema.String.annotate({
+              description: "A human-readable message describing what input is needed.",
+            }),
+            sessionId: Schema.String.annotate({
+              description:
+                "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+            }),
+          }).annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.",
+          }),
+        ]).annotate({
+          title: "ElicitationRequest",
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequests structured user input via a form or URL.",
+        }),
+        Schema.Unknown.annotate({
+          title: "ExtMethodRequest",
+          description:
+            "Allows for sending an arbitrary request that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+      ]).annotate({
+        description:
+          "All possible requests that an agent can send to a client.\n\nThis enum is used internally for routing RPC requests. You typically won't need\nto use this directly - instead, use the methods on the [`Client`] trait.\n\nThis enum encompasses all method calls from agent to client.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type AgentResponse =
+  | {
+      readonly id: RequestId;
+      readonly result:
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly agentCapabilities?: {
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly auth?: {
+                readonly _meta?: { readonly [x: string]: unknown } | null;
+                readonly logout?: LogoutCapabilities | null;
+              };
+              readonly loadSession?: boolean;
+              readonly mcpCapabilities?: {
+                readonly _meta?: { readonly [x: string]: unknown } | null;
+                readonly http?: boolean;
+                readonly sse?: boolean;
+              };
+              readonly promptCapabilities?: {
+                readonly _meta?: { readonly [x: string]: unknown } | null;
+                readonly audio?: boolean;
+                readonly embeddedContext?: boolean;
+                readonly image?: boolean;
+              };
+              readonly sessionCapabilities?: {
+                readonly _meta?: { readonly [x: string]: unknown } | null;
+                readonly close?: SessionCloseCapabilities | null;
+                readonly fork?: SessionForkCapabilities | null;
+                readonly list?: SessionListCapabilities | null;
+                readonly resume?: SessionResumeCapabilities | null;
+              };
+            };
+            readonly agentInfo?: Implementation | null;
+            readonly authMethods?: ReadonlyArray<AuthMethod>;
+            readonly protocolVersion: number;
+          }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+            readonly models?: SessionModelState | null;
+            readonly modes?: SessionModeState | null;
+            readonly sessionId: string;
+          }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+            readonly models?: SessionModelState | null;
+            readonly modes?: SessionModeState | null;
+          }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly nextCursor?: string | null;
+            readonly sessions: ReadonlyArray<SessionInfo>;
+          }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+            readonly models?: SessionModelState | null;
+            readonly modes?: SessionModeState | null;
+            readonly sessionId: string;
+          }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+            readonly models?: SessionModelState | null;
+            readonly modes?: SessionModeState | null;
+          }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly configOptions: ReadonlyArray<SessionConfigOption>;
+          }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly stopReason:
+              | "end_turn"
+              | "max_tokens"
+              | "max_turn_requests"
+              | "refusal"
+              | "cancelled";
+            readonly usage?: Usage | null;
+            readonly userMessageId?: string | null;
+          }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | unknown;
+    }
+  | { readonly error: Error; readonly id: RequestId };
+export const AgentResponse = Schema.Union([
+  Schema.Struct({
+    id: RequestId,
+    result: Schema.Union([
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        agentCapabilities: Schema.optionalKey(
+          Schema.Struct({
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            auth: Schema.optionalKey(
+              Schema.Struct({
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                logout: Schema.optionalKey(
+                  Schema.Union([LogoutCapabilities, Schema.Null]).annotate({
+                    description:
+                      "Whether the agent supports the logout method.\n\nBy supplying `{}` it means that the agent supports the logout method.",
+                  }),
+                ),
+              }).annotate({
+                description:
+                  "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication-related capabilities supported by the agent.",
+                default: {},
+              }),
+            ),
+            loadSession: Schema.optionalKey(
+              Schema.Boolean.annotate({
+                description: "Whether the agent supports `session/load`.",
+                default: false,
+              }),
+            ),
+            mcpCapabilities: Schema.optionalKey(
+              Schema.Struct({
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                http: Schema.optionalKey(
+                  Schema.Boolean.annotate({
+                    description: "Agent supports [`McpServer::Http`].",
+                    default: false,
+                  }),
+                ),
+                sse: Schema.optionalKey(
+                  Schema.Boolean.annotate({
+                    description: "Agent supports [`McpServer::Sse`].",
+                    default: false,
+                  }),
+                ),
+              }).annotate({
+                description: "MCP capabilities supported by the agent",
+                default: { http: false, sse: false },
+              }),
+            ),
+            promptCapabilities: Schema.optionalKey(
+              Schema.Struct({
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                audio: Schema.optionalKey(
+                  Schema.Boolean.annotate({
+                    description: "Agent supports [`ContentBlock::Audio`].",
+                    default: false,
+                  }),
+                ),
+                embeddedContext: Schema.optionalKey(
+                  Schema.Boolean.annotate({
+                    description:
+                      "Agent supports embedded context in `session/prompt` requests.\n\nWhen enabled, the Client is allowed to include [`ContentBlock::Resource`]\nin prompt requests for pieces of context that are referenced in the message.",
+                    default: false,
+                  }),
+                ),
+                image: Schema.optionalKey(
+                  Schema.Boolean.annotate({
+                    description: "Agent supports [`ContentBlock::Image`].",
+                    default: false,
+                  }),
+                ),
+              }).annotate({
+                description:
+                  "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for [`ContentBlock::Text`]\nand [`ContentBlock::ResourceLink`] in prompt requests.\n\nOther variants must be explicitly opted in to.\nCapabilities for different types of content in prompt requests.\n\nIndicates which content types beyond the baseline (text and resource links)\nthe agent can process.\n\nSee protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)",
+                default: { audio: false, embeddedContext: false, image: false },
+              }),
+            ),
+            sessionCapabilities: Schema.optionalKey(
+              Schema.Struct({
+                _meta: Schema.optionalKey(
+                  Schema.Union([
+                    Schema.Record(Schema.String, Schema.Unknown).annotate({
+                      description:
+                        "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                    }),
+                    Schema.Null,
+                  ]),
+                ),
+                close: Schema.optionalKey(
+                  Schema.Union([SessionCloseCapabilities, Schema.Null]).annotate({
+                    description:
+                      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/close`.",
+                  }),
+                ),
+                fork: Schema.optionalKey(
+                  Schema.Union([SessionForkCapabilities, Schema.Null]).annotate({
+                    description:
+                      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/fork`.",
+                  }),
+                ),
+                list: Schema.optionalKey(
+                  Schema.Union([SessionListCapabilities, Schema.Null]).annotate({
+                    description: "Whether the agent supports `session/list`.",
+                  }),
+                ),
+                resume: Schema.optionalKey(
+                  Schema.Union([SessionResumeCapabilities, Schema.Null]).annotate({
+                    description:
+                      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/resume`.",
+                  }),
+                ),
+              }).annotate({
+                default: {},
+                description:
+                  "Session capabilities supported by the agent.\n\nAs a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nOptionally, they **MAY** support other session methods and notifications by specifying additional capabilities.\n\nNote: `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities)",
+              }),
+            ),
+          }).annotate({
+            description:
+              "Capabilities supported by the agent.\n\nAdvertised during initialization to inform the client about\navailable features and content types.\n\nSee protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities)",
+            default: {
+              auth: {},
+              loadSession: false,
+              mcpCapabilities: { http: false, sse: false },
+              promptCapabilities: { audio: false, embeddedContext: false, image: false },
+              sessionCapabilities: {},
+            },
+          }),
+        ),
+        agentInfo: Schema.optionalKey(
+          Schema.Union([Implementation, Schema.Null]).annotate({
+            description:
+              "Information about the Agent name and version sent to the Client.\n\nNote: in future versions of the protocol, this will be required.",
+          }),
+        ),
+        authMethods: Schema.optionalKey(
+          Schema.Array(AuthMethod).annotate({
+            description: "Authentication methods supported by the agent.",
+            default: [],
+          }),
+        ),
+        protocolVersion: Schema.Number.annotate({
+          description:
+            "Protocol version identifier.\n\nThis version is only bumped for breaking changes.\nNon-breaking changes should be introduced via capabilities.",
+          format: "uint16",
+        })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0))
+          .check(Schema.isLessThanOrEqualTo(65535)),
+      }).annotate({
+        title: "InitializeResponse",
+        description:
+          "Response to the `initialize` method.\n\nContains the negotiated protocol version and agent capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "AuthenticateResponse",
+        description: "Response to the `authenticate` method.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "LogoutResponse",
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to the `logout` method.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        configOptions: Schema.optionalKey(
+          Schema.Union([
+            Schema.Array(SessionConfigOption).annotate({
+              description: "Initial session configuration options if supported by the Agent.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        models: Schema.optionalKey(
+          Schema.Union([SessionModelState, Schema.Null]).annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+          }),
+        ),
+        modes: Schema.optionalKey(
+          Schema.Union([SessionModeState, Schema.Null]).annotate({
+            description:
+              "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+          }),
+        ),
+        sessionId: Schema.String.annotate({
+          description:
+            "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+        }),
+      }).annotate({
+        title: "NewSessionResponse",
+        description:
+          "Response from creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        configOptions: Schema.optionalKey(
+          Schema.Union([
+            Schema.Array(SessionConfigOption).annotate({
+              description: "Initial session configuration options if supported by the Agent.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        models: Schema.optionalKey(
+          Schema.Union([SessionModelState, Schema.Null]).annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+          }),
+        ),
+        modes: Schema.optionalKey(
+          Schema.Union([SessionModeState, Schema.Null]).annotate({
+            description:
+              "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+          }),
+        ),
+      }).annotate({
+        title: "LoadSessionResponse",
+        description: "Response from loading an existing session.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        nextCursor: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description:
+                "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. If absent, there are no more results.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        sessions: Schema.Array(SessionInfo).annotate({
+          description: "Array of session information objects",
+        }),
+      }).annotate({
+        title: "ListSessionsResponse",
+        description: "Response from listing sessions.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        configOptions: Schema.optionalKey(
+          Schema.Union([
+            Schema.Array(SessionConfigOption).annotate({
+              description: "Initial session configuration options if supported by the Agent.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        models: Schema.optionalKey(
+          Schema.Union([SessionModelState, Schema.Null]).annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+          }),
+        ),
+        modes: Schema.optionalKey(
+          Schema.Union([SessionModeState, Schema.Null]).annotate({
+            description:
+              "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+          }),
+        ),
+        sessionId: Schema.String.annotate({
+          description:
+            "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+        }),
+      }).annotate({
+        title: "ForkSessionResponse",
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from forking an existing session.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        configOptions: Schema.optionalKey(
+          Schema.Union([
+            Schema.Array(SessionConfigOption).annotate({
+              description: "Initial session configuration options if supported by the Agent.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        models: Schema.optionalKey(
+          Schema.Union([SessionModelState, Schema.Null]).annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+          }),
+        ),
+        modes: Schema.optionalKey(
+          Schema.Union([SessionModeState, Schema.Null]).annotate({
+            description:
+              "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+          }),
+        ),
+      }).annotate({
+        title: "ResumeSessionResponse",
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from resuming an existing session.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "CloseSessionResponse",
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from closing a session.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "SetSessionModeResponse",
+        description: "Response to `session/set_mode` method.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        configOptions: Schema.Array(SessionConfigOption).annotate({
+          description: "The full set of configuration options and their current values.",
+        }),
+      }).annotate({
+        title: "SetSessionConfigOptionResponse",
+        description: "Response to `session/set_config_option` method.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        stopReason: Schema.Literals([
+          "end_turn",
+          "max_tokens",
+          "max_turn_requests",
+          "refusal",
+          "cancelled",
+        ]).annotate({
+          description:
+            "Reasons why an agent stops processing a prompt turn.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons)",
+        }),
+        usage: Schema.optionalKey(
+          Schema.Union([Usage, Schema.Null]).annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for this turn (optional).",
+          }),
+        ),
+        userMessageId: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe acknowledged user message ID.\n\nIf the client provided a `messageId` in the [`PromptRequest`], the agent echoes it here\nto confirm it was recorded. If the client did not provide one, the agent MAY assign one\nand return it here. Absence of this field indicates the agent did not record a message ID.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "PromptResponse",
+        description:
+          "Response from processing a user prompt.\n\nSee protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion)",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "SetSessionModelResponse",
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `session/set_model` method.",
+      }),
+      Schema.Unknown.annotate({
+        title: "ExtMethodResponse",
+        description:
+          "Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+    ]).annotate({
+      description:
+        "All possible responses that an agent can send to a client.\n\nThis enum is used internally for routing RPC responses. You typically won't need\nto use this directly - the responses are handled automatically by the connection.\n\nThese are responses to the corresponding `ClientRequest` variants.",
+    }),
+  }).annotate({ title: "Result" }),
+  Schema.Struct({ error: Error, id: RequestId }).annotate({ title: "Error" }),
+]);
+
+export type AudioContent = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly annotations?: Annotations | null;
+  readonly data: string;
+  readonly mimeType: string;
+};
+export const AudioContent = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+  data: Schema.String,
+  mimeType: Schema.String,
+}).annotate({ description: "Audio provided to or from an LLM." });
+
+export type AuthCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly terminal?: boolean;
+};
+export const AuthCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  terminal: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Whether the client supports `terminal` authentication methods.\n\nWhen `true`, the agent may include `terminal` entries in its authentication methods.",
+      default: false,
+    }),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.",
+});
+
+export type AuthenticateRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly methodId: string;
+};
+export const AuthenticateRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  methodId: Schema.String.annotate({
+    description:
+      "The ID of the authentication method to use.\nMust be one of the methods advertised in the initialize response.",
+  }),
+}).annotate({
+  description:
+    "Request parameters for the authenticate method.\n\nSpecifies which authentication method to use.",
+});
+
+export type AuthenticateResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const AuthenticateResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Response to the `authenticate` method." });
+
+export type AuthMethodAgent = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly description?: string | null;
+  readonly id: string;
+  readonly name: string;
+};
+export const AuthMethodAgent = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional description providing more details about this authentication method.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  id: Schema.String.annotate({ description: "Unique identifier for this authentication method." }),
+  name: Schema.String.annotate({
+    description: "Human-readable name of the authentication method.",
+  }),
+}).annotate({
+  description:
+    "Agent handles authentication itself.\n\nThis is the default authentication method type.",
+});
+
+export type AuthMethodEnvVar = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly description?: string | null;
+  readonly id: string;
+  readonly link?: string | null;
+  readonly name: string;
+  readonly vars: ReadonlyArray<AuthEnvVar>;
+};
+export const AuthMethodEnvVar = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional description providing more details about this authentication method.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  id: Schema.String.annotate({ description: "Unique identifier for this authentication method." }),
+  link: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional link to a page where the user can obtain their credentials.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  name: Schema.String.annotate({
+    description: "Human-readable name of the authentication method.",
+  }),
+  vars: Schema.Array(AuthEnvVar).annotate({
+    description: "The environment variables the client should set.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nEnvironment variable authentication method.\n\nThe user provides credentials that the client passes to the agent as environment variables.",
+});
+
+export type AuthMethodTerminal = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly args?: ReadonlyArray<string>;
+  readonly description?: string | null;
+  readonly env?: { readonly [x: string]: string };
+  readonly id: string;
+  readonly name: string;
+};
+export const AuthMethodTerminal = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  args: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      description: "Additional arguments to pass when running the agent binary for terminal auth.",
+    }),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional description providing more details about this authentication method.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  env: Schema.optionalKey(
+    Schema.Record(Schema.String, Schema.String).annotate({
+      description:
+        "Additional environment variables to set when running the agent binary for terminal auth.",
+    }),
+  ),
+  id: Schema.String.annotate({ description: "Unique identifier for this authentication method." }),
+  name: Schema.String.annotate({
+    description: "Human-readable name of the authentication method.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nTerminal-based authentication method.\n\nThe client runs an interactive terminal for the user to authenticate via a TUI.",
+});
+
+export type AvailableCommandsUpdate = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly availableCommands: ReadonlyArray<AvailableCommand>;
+};
+export const AvailableCommandsUpdate = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  availableCommands: Schema.Array(AvailableCommand).annotate({
+    description: "Commands the agent can execute",
+  }),
+}).annotate({ description: "Available commands are ready or have changed" });
+
+export type BlobResourceContents = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly blob: string;
+  readonly mimeType?: string | null;
+  readonly uri: string;
+};
+export const BlobResourceContents = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  blob: Schema.String,
+  mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  uri: Schema.String,
+}).annotate({ description: "Binary resource contents." });
+
+export type BooleanPropertySchema = {
+  readonly default?: boolean | null;
+  readonly description?: string | null;
+  readonly title?: string | null;
+};
+export const BooleanPropertySchema = Schema.Struct({
+  default: Schema.optionalKey(
+    Schema.Union([Schema.Boolean.annotate({ description: "Default value." }), Schema.Null]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Human-readable description." }),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional title for the property." }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Schema for boolean properties in an elicitation form." });
+
+export type CancelNotification = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly sessionId: string;
+};
+export const CancelNotification = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "Notification to cancel ongoing operations for a session.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)",
+});
+
+export type CancelRequestNotification = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly requestId: null | number | string;
+};
+export const CancelRequestNotification = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  requestId: Schema.Union([
+    Schema.Null.annotate({ title: "Null" }),
+    Schema.Number.annotate({ title: "Number", format: "int64" }).check(Schema.isInt()),
+    Schema.String.annotate({ title: "Str" }),
+  ]).annotate({
+    description:
+      "JSON RPC Request Id\n\nAn identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]\n\nThe Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.\n\n[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.\n\n[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)",
+});
+
+export type ClientCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly auth?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly terminal?: boolean;
+  };
+  readonly elicitation?: ElicitationCapabilities | null;
+  readonly fs?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly readTextFile?: boolean;
+    readonly writeTextFile?: boolean;
+  };
+  readonly terminal?: boolean;
+};
+export const ClientCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  auth: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      terminal: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description:
+            "Whether the client supports `terminal` authentication methods.\n\nWhen `true`, the agent may include `terminal` entries in its authentication methods.",
+          default: false,
+        }),
+      ),
+    }).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.",
+      default: { terminal: false },
+    }),
+  ),
+  elicitation: Schema.optionalKey(
+    Schema.Union([ElicitationCapabilities, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.",
+    }),
+  ),
+  fs: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      readTextFile: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Whether the Client supports `fs/read_text_file` requests.",
+          default: false,
+        }),
+      ),
+      writeTextFile: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Whether the Client supports `fs/write_text_file` requests.",
+          default: false,
+        }),
+      ),
+    }).annotate({
+      description:
+        "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)",
+      default: { readTextFile: false, writeTextFile: false },
+    }),
+  ),
+  terminal: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Whether the Client support all `terminal/*` methods.",
+      default: false,
+    }),
+  ),
+}).annotate({
+  description:
+    "Capabilities supported by the client.\n\nAdvertised during initialization to inform the agent about\navailable features and methods.\n\nSee protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities)",
+});
+
+export type ClientNotification = {
+  readonly method: string;
+  readonly params?:
+    | { readonly _meta?: { readonly [x: string]: unknown } | null; readonly sessionId: string }
+    | unknown
+    | null;
+};
+export const ClientNotification = Schema.Struct({
+  method: Schema.String,
+  params: Schema.optionalKey(
+    Schema.Union([
+      Schema.Union([
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "CancelNotification",
+          description:
+            "Notification to cancel ongoing operations for a session.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)",
+        }),
+        Schema.Unknown.annotate({
+          title: "ExtNotification",
+          description:
+            "Allows the Agent to send an arbitrary notification that is not part of the ACP spec.\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+      ]).annotate({
+        description:
+          "All possible notifications that a client can send to an agent.\n\nThis enum is used internally for routing RPC notifications. You typically won't need\nto use this directly - use the notification methods on the [`Agent`] trait instead.\n\nNotifications do not expect a response.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest = {
+  readonly id: RequestId;
+  readonly method: string;
+  readonly params?:
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly clientCapabilities?: {
+          readonly _meta?: { readonly [x: string]: unknown } | null;
+          readonly auth?: {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly terminal?: boolean;
+          };
+          readonly elicitation?: ElicitationCapabilities | null;
+          readonly fs?: {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly readTextFile?: boolean;
+            readonly writeTextFile?: boolean;
+          };
+          readonly terminal?: boolean;
+        };
+        readonly clientInfo?: Implementation | null;
+        readonly protocolVersion: number;
+      }
+    | { readonly _meta?: { readonly [x: string]: unknown } | null; readonly methodId: string }
+    | { readonly _meta?: { readonly [x: string]: unknown } | null }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly cwd: string;
+        readonly mcpServers: ReadonlyArray<McpServer>;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly cwd: string;
+        readonly mcpServers: ReadonlyArray<McpServer>;
+        readonly sessionId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly cursor?: string | null;
+        readonly cwd?: string | null;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly cwd: string;
+        readonly mcpServers?: ReadonlyArray<McpServer>;
+        readonly sessionId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly cwd: string;
+        readonly mcpServers?: ReadonlyArray<McpServer>;
+        readonly sessionId: string;
+      }
+    | { readonly _meta?: { readonly [x: string]: unknown } | null; readonly sessionId: string }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly modeId: string;
+        readonly sessionId: string;
+      }
+    | {
+        readonly type: "boolean";
+        readonly value: boolean;
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly configId: string;
+        readonly sessionId: string;
+      }
+    | {
+        readonly value: string;
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly configId: string;
+        readonly sessionId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly messageId?: string | null;
+        readonly prompt: ReadonlyArray<ContentBlock>;
+        readonly sessionId: string;
+      }
+    | {
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly modelId: string;
+        readonly sessionId: string;
+      }
+    | unknown
+    | null;
+};
+export const ClientRequest = Schema.Struct({
+  id: RequestId,
+  method: Schema.String,
+  params: Schema.optionalKey(
+    Schema.Union([
+      Schema.Union([
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          clientCapabilities: Schema.optionalKey(
+            Schema.Struct({
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              auth: Schema.optionalKey(
+                Schema.Struct({
+                  _meta: Schema.optionalKey(
+                    Schema.Union([
+                      Schema.Record(Schema.String, Schema.Unknown).annotate({
+                        description:
+                          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                      }),
+                      Schema.Null,
+                    ]),
+                  ),
+                  terminal: Schema.optionalKey(
+                    Schema.Boolean.annotate({
+                      description:
+                        "Whether the client supports `terminal` authentication methods.\n\nWhen `true`, the agent may include `terminal` entries in its authentication methods.",
+                      default: false,
+                    }),
+                  ),
+                }).annotate({
+                  description:
+                    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.",
+                  default: { terminal: false },
+                }),
+              ),
+              elicitation: Schema.optionalKey(
+                Schema.Union([ElicitationCapabilities, Schema.Null]).annotate({
+                  description:
+                    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.",
+                }),
+              ),
+              fs: Schema.optionalKey(
+                Schema.Struct({
+                  _meta: Schema.optionalKey(
+                    Schema.Union([
+                      Schema.Record(Schema.String, Schema.Unknown).annotate({
+                        description:
+                          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                      }),
+                      Schema.Null,
+                    ]),
+                  ),
+                  readTextFile: Schema.optionalKey(
+                    Schema.Boolean.annotate({
+                      description: "Whether the Client supports `fs/read_text_file` requests.",
+                      default: false,
+                    }),
+                  ),
+                  writeTextFile: Schema.optionalKey(
+                    Schema.Boolean.annotate({
+                      description: "Whether the Client supports `fs/write_text_file` requests.",
+                      default: false,
+                    }),
+                  ),
+                }).annotate({
+                  description:
+                    "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)",
+                  default: { readTextFile: false, writeTextFile: false },
+                }),
+              ),
+              terminal: Schema.optionalKey(
+                Schema.Boolean.annotate({
+                  description: "Whether the Client support all `terminal/*` methods.",
+                  default: false,
+                }),
+              ),
+            }).annotate({
+              description:
+                "Capabilities supported by the client.\n\nAdvertised during initialization to inform the agent about\navailable features and methods.\n\nSee protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities)",
+              default: {
+                auth: { terminal: false },
+                fs: { readTextFile: false, writeTextFile: false },
+                terminal: false,
+              },
+            }),
+          ),
+          clientInfo: Schema.optionalKey(
+            Schema.Union([Implementation, Schema.Null]).annotate({
+              description:
+                "Information about the Client name and version sent to the Agent.\n\nNote: in future versions of the protocol, this will be required.",
+            }),
+          ),
+          protocolVersion: Schema.Number.annotate({
+            description:
+              "Protocol version identifier.\n\nThis version is only bumped for breaking changes.\nNon-breaking changes should be introduced via capabilities.",
+            format: "uint16",
+          })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0))
+            .check(Schema.isLessThanOrEqualTo(65535)),
+        }).annotate({
+          title: "InitializeRequest",
+          description:
+            "Request parameters for the initialize method.\n\nSent by the client to establish connection and negotiate capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          methodId: Schema.String.annotate({
+            description:
+              "The ID of the authentication method to use.\nMust be one of the methods advertised in the initialize response.",
+          }),
+        }).annotate({
+          title: "AuthenticateRequest",
+          description:
+            "Request parameters for the authenticate method.\n\nSpecifies which authentication method to use.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+        }).annotate({
+          title: "LogoutRequest",
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for the logout method.\n\nTerminates the current authenticated session.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          cwd: Schema.String.annotate({
+            description: "The working directory for this session. Must be an absolute path.",
+          }),
+          mcpServers: Schema.Array(McpServer).annotate({
+            description:
+              "List of MCP (Model Context Protocol) servers the agent should connect to.",
+          }),
+        }).annotate({
+          title: "NewSessionRequest",
+          description:
+            "Request parameters for creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          cwd: Schema.String.annotate({ description: "The working directory for this session." }),
+          mcpServers: Schema.Array(McpServer).annotate({
+            description: "List of MCP servers to connect to for this session.",
+          }),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "LoadSessionRequest",
+          description:
+            "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `loadSession` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          cursor: Schema.optionalKey(
+            Schema.Union([
+              Schema.String.annotate({
+                description:
+                  "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          cwd: Schema.optionalKey(
+            Schema.Union([
+              Schema.String.annotate({
+                description: "Filter sessions by working directory. Must be an absolute path.",
+              }),
+              Schema.Null,
+            ]),
+          ),
+        }).annotate({
+          title: "ListSessionsRequest",
+          description:
+            "Request parameters for listing existing sessions.\n\nOnly available if the Agent supports the `sessionCapabilities.list` capability.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          cwd: Schema.String.annotate({ description: "The working directory for this session." }),
+          mcpServers: Schema.optionalKey(
+            Schema.Array(McpServer).annotate({
+              description: "List of MCP servers to connect to for this session.",
+            }),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "ForkSessionRequest",
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for forking an existing session.\n\nCreates a new session based on the context of an existing one, allowing\noperations like generating summaries without affecting the original session's history.\n\nOnly available if the Agent supports the `session.fork` capability.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          cwd: Schema.String.annotate({ description: "The working directory for this session." }),
+          mcpServers: Schema.optionalKey(
+            Schema.Array(McpServer).annotate({
+              description: "List of MCP servers to connect to for this session.",
+            }),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "ResumeSessionRequest",
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `session.resume` capability.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "CloseSessionRequest",
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.close` capability.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          modeId: Schema.String.annotate({ description: "Unique identifier for a Session Mode." }),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "SetSessionModeRequest",
+          description: "Request parameters for setting a session mode.",
+        }),
+        Schema.Union([
+          Schema.Struct({
+            type: Schema.Literal("boolean"),
+            value: Schema.Boolean.annotate({ description: "The boolean value." }),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            configId: Schema.String.annotate({
+              description: "Unique identifier for a session configuration option.",
+            }),
+            sessionId: Schema.String.annotate({
+              description:
+                "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+            }),
+          }).annotate({
+            description: "Request parameters for setting a session configuration option.",
+          }),
+          Schema.Struct({
+            value: Schema.String.annotate({
+              description: "Unique identifier for a session configuration option value.",
+            }),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            configId: Schema.String.annotate({
+              description: "Unique identifier for a session configuration option.",
+            }),
+            sessionId: Schema.String.annotate({
+              description:
+                "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+            }),
+          }).annotate({
+            title: "value_id",
+            description: "Request parameters for setting a session configuration option.",
+          }),
+        ]).annotate({
+          title: "SetSessionConfigOptionRequest",
+          description: "Sets the current value for a session configuration option.",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          messageId: Schema.optionalKey(
+            Schema.Union([
+              Schema.String.annotate({
+                description:
+                  "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA client-generated unique identifier for this user message.\n\nIf provided, the Agent SHOULD echo this value as `userMessageId` in the\n[`PromptResponse`] to confirm it was recorded.\nBoth clients and agents MUST use UUID format for message IDs.",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          prompt: Schema.Array(ContentBlock).annotate({
+            description:
+              "The blocks of content that compose the user's message.\n\nAs a baseline, the Agent MUST support [`ContentBlock::Text`] and [`ContentBlock::ResourceLink`],\nwhile other variants are optionally enabled via [`PromptCapabilities`].\n\nThe Client MUST adapt its interface according to [`PromptCapabilities`].\n\nThe client MAY include referenced pieces of context as either\n[`ContentBlock::Resource`] or [`ContentBlock::ResourceLink`].\n\nWhen available, [`ContentBlock::Resource`] is preferred\nas it avoids extra round-trips and allows the message to include\npieces of context from sources the agent may not have access to.",
+          }),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "PromptRequest",
+          description:
+            "Request parameters for sending a user prompt to the agent.\n\nContains the user's message and any additional context.\n\nSee protocol docs: [User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message)",
+        }),
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          modelId: Schema.String.annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for a model.",
+          }),
+          sessionId: Schema.String.annotate({
+            description:
+              "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+          }),
+        }).annotate({
+          title: "SetSessionModelRequest",
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for setting a session model.",
+        }),
+        Schema.Unknown.annotate({
+          title: "ExtMethodRequest",
+          description:
+            "Allows for sending an arbitrary request that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+      ]).annotate({
+        description:
+          "All possible requests that a client can send to an agent.\n\nThis enum is used internally for routing RPC requests. You typically won't need\nto use this directly - instead, use the methods on the [`Agent`] trait.\n\nThis enum encompasses all method calls from client to agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientResponse =
+  | {
+      readonly id: RequestId;
+      readonly result:
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null; readonly content: string }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly outcome:
+              | { readonly outcome: "cancelled" }
+              | {
+                  readonly outcome: "selected";
+                  readonly _meta?: { readonly [x: string]: unknown } | null;
+                  readonly optionId: string;
+                };
+          }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null; readonly terminalId: string }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly exitStatus?: TerminalExitStatus | null;
+            readonly output: string;
+            readonly truncated: boolean;
+          }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly exitCode?: number | null;
+            readonly signal?: string | null;
+          }
+        | { readonly _meta?: { readonly [x: string]: unknown } | null }
+        | {
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly action:
+              | {
+                  readonly action: "accept";
+                  readonly content?: { readonly [x: string]: ElicitationContentValue } | null;
+                }
+              | { readonly action: "decline" }
+              | { readonly action: "cancel" };
+          }
+        | unknown;
+    }
+  | { readonly error: Error; readonly id: RequestId };
+export const ClientResponse = Schema.Union([
+  Schema.Struct({
+    id: RequestId,
+    result: Schema.Union([
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "WriteTextFileResponse",
+        description: "Response to `fs/write_text_file`",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        content: Schema.String,
+      }).annotate({
+        title: "ReadTextFileResponse",
+        description: "Response containing the contents of a text file.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        outcome: Schema.Union(
+          [
+            Schema.Struct({ outcome: Schema.Literal("cancelled") }).annotate({
+              description:
+                "The prompt turn was cancelled before the user responded.\n\nWhen a client sends a `session/cancel` notification to cancel an ongoing\nprompt turn, it MUST respond to all pending `session/request_permission`\nrequests with this `Cancelled` outcome.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)",
+            }),
+            Schema.Struct({
+              outcome: Schema.Literal("selected"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              optionId: Schema.String.annotate({
+                description: "Unique identifier for a permission option.",
+              }),
+            }).annotate({ description: "The user selected one of the provided options." }),
+          ],
+          { mode: "oneOf" },
+        ).annotate({ description: "The outcome of a permission request." }),
+      }).annotate({
+        title: "RequestPermissionResponse",
+        description: "Response to a permission request.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        terminalId: Schema.String.annotate({
+          description: "The unique identifier for the created terminal.",
+        }),
+      }).annotate({
+        title: "CreateTerminalResponse",
+        description: "Response containing the ID of the created terminal.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        exitStatus: Schema.optionalKey(
+          Schema.Union([TerminalExitStatus, Schema.Null]).annotate({
+            description: "Exit status if the command has completed.",
+          }),
+        ),
+        output: Schema.String.annotate({ description: "The terminal output captured so far." }),
+        truncated: Schema.Boolean.annotate({
+          description: "Whether the output was truncated due to byte limits.",
+        }),
+      }).annotate({
+        title: "TerminalOutputResponse",
+        description: "Response containing the terminal output and exit status.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "ReleaseTerminalResponse",
+        description: "Response to terminal/release method",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        exitCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({
+              description: "The process exit code (may be null if terminated by signal).",
+              format: "uint32",
+            })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+        signal: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description:
+                "The signal that terminated the process (may be null if exited normally).",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "WaitForTerminalExitResponse",
+        description: "Response containing the exit status of a terminal command.",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        title: "KillTerminalResponse",
+        description: "Response to `terminal/kill` method",
+      }),
+      Schema.Struct({
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        action: Schema.Union(
+          [
+            Schema.Struct({
+              action: Schema.Literal("accept"),
+              content: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, ElicitationContentValue).annotate({
+                    description:
+                      "The user-provided content, if any, as an object matching the requested schema.",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+            }).annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.",
+            }),
+            Schema.Struct({ action: Schema.Literal("decline") }).annotate({
+              description: "The user declined the elicitation.",
+            }),
+            Schema.Struct({ action: Schema.Literal("cancel") }).annotate({
+              description: "The elicitation was cancelled.",
+            }),
+          ],
+          { mode: "oneOf" },
+        ).annotate({
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user's action in response to an elicitation.",
+        }),
+      }).annotate({
+        title: "ElicitationResponse",
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from the client to an elicitation request.",
+      }),
+      Schema.Unknown.annotate({
+        title: "ExtMethodResponse",
+        description:
+          "Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+    ]).annotate({
+      description:
+        "All possible responses that a client can send to an agent.\n\nThis enum is used internally for routing RPC responses. You typically won't need\nto use this directly - the responses are handled automatically by the connection.\n\nThese are responses to the corresponding `AgentRequest` variants.",
+    }),
+  }).annotate({ title: "Result" }),
+  Schema.Struct({ error: Error, id: RequestId }).annotate({ title: "Error" }),
+]);
+
+export type CloseSessionRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly sessionId: string;
+};
+export const CloseSessionRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.close` capability.",
+});
+
+export type CloseSessionResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const CloseSessionResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from closing a session.",
+});
+
+export type ConfigOptionUpdate = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly configOptions: ReadonlyArray<SessionConfigOption>;
+};
+export const ConfigOptionUpdate = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  configOptions: Schema.Array(SessionConfigOption).annotate({
+    description: "The full set of configuration options and their current values.",
+  }),
+}).annotate({ description: "Session configuration options have been updated." });
+
+export type Content = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly content:
+    | {
+        readonly type: "text";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly text: string;
+      }
+    | {
+        readonly type: "image";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly data: string;
+        readonly mimeType: string;
+        readonly uri?: string | null;
+      }
+    | {
+        readonly type: "audio";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly data: string;
+        readonly mimeType: string;
+      }
+    | {
+        readonly type: "resource_link";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly description?: string | null;
+        readonly mimeType?: string | null;
+        readonly name: string;
+        readonly size?: number | null;
+        readonly title?: string | null;
+        readonly uri: string;
+      }
+    | {
+        readonly type: "resource";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly resource: EmbeddedResourceResource;
+      };
+};
+export const Content = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  content: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("text"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        text: Schema.String,
+      }).annotate({ description: "Text provided to or from an LLM." }),
+      Schema.Struct({
+        type: Schema.Literal("image"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        data: Schema.String,
+        mimeType: Schema.String,
+        uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      }).annotate({ description: "An image provided to or from an LLM." }),
+      Schema.Struct({
+        type: Schema.Literal("audio"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        data: Schema.String,
+        mimeType: Schema.String,
+      }).annotate({ description: "Audio provided to or from an LLM." }),
+      Schema.Struct({
+        type: Schema.Literal("resource_link"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        name: Schema.String,
+        size: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+            Schema.Null,
+          ]),
+        ),
+        title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        uri: Schema.String,
+      }).annotate({
+        description:
+          "A resource that the server is capable of reading, included in a prompt or tool call result.",
+      }),
+      Schema.Struct({
+        type: Schema.Literal("resource"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        resource: EmbeddedResourceResource,
+      }).annotate({
+        description: "The contents of a resource, embedded into a prompt or tool call result.",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description:
+      "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+  }),
+}).annotate({ description: "Standard content block (text, images, resources)." });
+
+export type ContentChunk = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly content:
+    | {
+        readonly type: "text";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly text: string;
+      }
+    | {
+        readonly type: "image";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly data: string;
+        readonly mimeType: string;
+        readonly uri?: string | null;
+      }
+    | {
+        readonly type: "audio";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly data: string;
+        readonly mimeType: string;
+      }
+    | {
+        readonly type: "resource_link";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly description?: string | null;
+        readonly mimeType?: string | null;
+        readonly name: string;
+        readonly size?: number | null;
+        readonly title?: string | null;
+        readonly uri: string;
+      }
+    | {
+        readonly type: "resource";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly annotations?: Annotations | null;
+        readonly resource: EmbeddedResourceResource;
+      };
+  readonly messageId?: string | null;
+};
+export const ContentChunk = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  content: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("text"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        text: Schema.String,
+      }).annotate({ description: "Text provided to or from an LLM." }),
+      Schema.Struct({
+        type: Schema.Literal("image"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        data: Schema.String,
+        mimeType: Schema.String,
+        uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      }).annotate({ description: "An image provided to or from an LLM." }),
+      Schema.Struct({
+        type: Schema.Literal("audio"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        data: Schema.String,
+        mimeType: Schema.String,
+      }).annotate({ description: "Audio provided to or from an LLM." }),
+      Schema.Struct({
+        type: Schema.Literal("resource_link"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        name: Schema.String,
+        size: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+            Schema.Null,
+          ]),
+        ),
+        title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        uri: Schema.String,
+      }).annotate({
+        description:
+          "A resource that the server is capable of reading, included in a prompt or tool call result.",
+      }),
+      Schema.Struct({
+        type: Schema.Literal("resource"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+        resource: EmbeddedResourceResource,
+      }).annotate({
+        description: "The contents of a resource, embedded into a prompt or tool call result.",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description:
+      "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+  }),
+  messageId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "A streamed item of content" });
+
+export type CreateTerminalRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly args?: ReadonlyArray<string>;
+  readonly command: string;
+  readonly cwd?: string | null;
+  readonly env?: ReadonlyArray<EnvVariable>;
+  readonly outputByteLimit?: number | null;
+  readonly sessionId: string;
+};
+export const CreateTerminalRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  args: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({ description: "Array of command arguments." }),
+  ),
+  command: Schema.String.annotate({ description: "The command to execute." }),
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Working directory for the command (absolute path)." }),
+      Schema.Null,
+    ]),
+  ),
+  env: Schema.optionalKey(
+    Schema.Array(EnvVariable).annotate({ description: "Environment variables for the command." }),
+  ),
+  outputByteLimit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description:
+          "Maximum number of output bytes to retain.\n\nWhen the limit is exceeded, the Client truncates from the beginning of the output\nto stay within the limit.\n\nThe Client MUST ensure truncation happens at a character boundary to maintain valid\nstring output, even if this means the retained output is slightly less than the\nspecified limit.",
+        format: "uint64",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({ description: "Request to create a new terminal and execute a command." });
+
+export type CreateTerminalResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly terminalId: string;
+};
+export const CreateTerminalResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  terminalId: Schema.String.annotate({
+    description: "The unique identifier for the created terminal.",
+  }),
+}).annotate({ description: "Response containing the ID of the created terminal." });
+
+export type CurrentModeUpdate = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly currentModeId: string;
+};
+export const CurrentModeUpdate = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  currentModeId: Schema.String.annotate({ description: "Unique identifier for a Session Mode." }),
+}).annotate({
+  description:
+    "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+});
+
+export type Diff = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly newText: string;
+  readonly oldText?: string | null;
+  readonly path: string;
+};
+export const Diff = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  newText: Schema.String.annotate({ description: "The new content after modification." }),
+  oldText: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "The original content (None for new files)." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.String.annotate({ description: "The file path being modified." }),
+}).annotate({
+  description:
+    "A diff representing file modifications.\n\nShows changes to files in a format suitable for display in the client UI.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)",
+});
+
+export type ElicitationAcceptAction = {
+  readonly content?: { readonly [x: string]: ElicitationContentValue } | null;
+};
+export const ElicitationAcceptAction = Schema.Struct({
+  content: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, ElicitationContentValue).annotate({
+        description:
+          "The user-provided content, if any, as an object matching the requested schema.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.",
+});
+
+export type ElicitationAction =
+  | {
+      readonly action: "accept";
+      readonly content?: { readonly [x: string]: ElicitationContentValue } | null;
+    }
+  | { readonly action: "decline" }
+  | { readonly action: "cancel" };
+export const ElicitationAction = Schema.Union(
+  [
+    Schema.Struct({
+      action: Schema.Literal("accept"),
+      content: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, ElicitationContentValue).annotate({
+            description:
+              "The user-provided content, if any, as an object matching the requested schema.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.",
+    }),
+    Schema.Struct({ action: Schema.Literal("decline") }).annotate({
+      description: "The user declined the elicitation.",
+    }),
+    Schema.Struct({ action: Schema.Literal("cancel") }).annotate({
+      description: "The elicitation was cancelled.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user's action in response to an elicitation.",
+});
+
+export type ElicitationCompleteNotification = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly elicitationId: string;
+};
+export const ElicitationCompleteNotification = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  elicitationId: Schema.String.annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification sent by the agent when a URL-based elicitation is complete.",
+});
+
+export type ElicitationFormMode = {
+  readonly requestedSchema: {
+    readonly description?: string | null;
+    readonly properties?: { readonly [x: string]: ElicitationPropertySchema };
+    readonly required?: ReadonlyArray<string> | null;
+    readonly title?: string | null;
+    readonly type?: "object";
+  };
+};
+export const ElicitationFormMode = Schema.Struct({
+  requestedSchema: Schema.Struct({
+    description: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description: "Optional description of what this schema represents.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    properties: Schema.optionalKey(
+      Schema.Record(Schema.String, ElicitationPropertySchema).annotate({
+        description: "Property definitions (must be primitive types).",
+        default: {},
+      }),
+    ),
+    required: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(Schema.String).annotate({ description: "List of required property names." }),
+        Schema.Null,
+      ]),
+    ),
+    title: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({ description: "Optional title for the schema." }),
+        Schema.Null,
+      ]),
+    ),
+    type: Schema.optionalKey(
+      Schema.Literal("object").annotate({
+        description: "Type discriminator for elicitation schemas.",
+        default: "object",
+      }),
+    ),
+  }).annotate({
+    description:
+      "Type-safe elicitation schema for requesting structured user input.\n\nThis represents a JSON Schema object with primitive-typed properties,\nas required by the elicitation specification.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForm-based elicitation mode where the client renders a form from the provided schema.",
+});
+
+export type ElicitationId = string;
+export const ElicitationId = Schema.String.annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.",
+});
+
+export type ElicitationRequest =
+  | {
+      readonly mode: "form";
+      readonly requestedSchema: {
+        readonly description?: string | null;
+        readonly properties?: { readonly [x: string]: ElicitationPropertySchema };
+        readonly required?: ReadonlyArray<string> | null;
+        readonly title?: string | null;
+        readonly type?: "object";
+      };
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly message: string;
+      readonly sessionId: string;
+    }
+  | {
+      readonly mode: "url";
+      readonly elicitationId: string;
+      readonly url: string;
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly message: string;
+      readonly sessionId: string;
+    };
+export const ElicitationRequest = Schema.Union([
+  Schema.Struct({
+    mode: Schema.Literal("form"),
+    requestedSchema: Schema.Struct({
+      description: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Optional description of what this schema represents.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      properties: Schema.optionalKey(
+        Schema.Record(Schema.String, ElicitationPropertySchema).annotate({
+          description: "Property definitions (must be primitive types).",
+          default: {},
+        }),
+      ),
+      required: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(Schema.String).annotate({ description: "List of required property names." }),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Optional title for the schema." }),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.optionalKey(
+        Schema.Literal("object").annotate({
+          description: "Type discriminator for elicitation schemas.",
+          default: "object",
+        }),
+      ),
+    }).annotate({
+      description:
+        "Type-safe elicitation schema for requesting structured user input.\n\nThis represents a JSON Schema object with primitive-typed properties,\nas required by the elicitation specification.",
+    }),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    message: Schema.String.annotate({
+      description: "A human-readable message describing what input is needed.",
+    }),
+    sessionId: Schema.String.annotate({
+      description:
+        "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+    }),
+  }).annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.",
+  }),
+  Schema.Struct({
+    mode: Schema.Literal("url"),
+    elicitationId: Schema.String.annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.",
+    }),
+    url: Schema.String.annotate({ description: "The URL to direct the user to.", format: "uri" }),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    message: Schema.String.annotate({
+      description: "A human-readable message describing what input is needed.",
+    }),
+    sessionId: Schema.String.annotate({
+      description:
+        "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+    }),
+  }).annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.",
+  }),
+]);
+
+export type ElicitationResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly action:
+    | {
+        readonly action: "accept";
+        readonly content?: { readonly [x: string]: ElicitationContentValue } | null;
+      }
+    | { readonly action: "decline" }
+    | { readonly action: "cancel" };
+};
+export const ElicitationResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  action: Schema.Union(
+    [
+      Schema.Struct({
+        action: Schema.Literal("accept"),
+        content: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, ElicitationContentValue).annotate({
+              description:
+                "The user-provided content, if any, as an object matching the requested schema.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.",
+      }),
+      Schema.Struct({ action: Schema.Literal("decline") }).annotate({
+        description: "The user declined the elicitation.",
+      }),
+      Schema.Struct({ action: Schema.Literal("cancel") }).annotate({
+        description: "The elicitation was cancelled.",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user's action in response to an elicitation.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from the client to an elicitation request.",
+});
+
+export type ElicitationSchema = {
+  readonly description?: string | null;
+  readonly properties?: { readonly [x: string]: ElicitationPropertySchema };
+  readonly required?: ReadonlyArray<string> | null;
+  readonly title?: string | null;
+  readonly type?: "object";
+};
+export const ElicitationSchema = Schema.Struct({
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional description of what this schema represents.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  properties: Schema.optionalKey(
+    Schema.Record(Schema.String, ElicitationPropertySchema).annotate({
+      description: "Property definitions (must be primitive types).",
+      default: {},
+    }),
+  ),
+  required: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({ description: "List of required property names." }),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional title for the schema." }),
+      Schema.Null,
+    ]),
+  ),
+  type: Schema.optionalKey(
+    Schema.Literal("object").annotate({
+      description: "Type discriminator for elicitation schemas.",
+      default: "object",
+    }),
+  ),
+}).annotate({
+  description:
+    "Type-safe elicitation schema for requesting structured user input.\n\nThis represents a JSON Schema object with primitive-typed properties,\nas required by the elicitation specification.",
+});
+
+export type ElicitationSchemaType = "object";
+export const ElicitationSchemaType = Schema.Literal("object").annotate({
+  description: "Type discriminator for elicitation schemas.",
+});
+
+export type ElicitationStringType = "string";
+export const ElicitationStringType = Schema.Literal("string").annotate({
+  description: "Items definition for untitled multi-select enum properties.",
+});
+
+export type ElicitationUrlMode = { readonly elicitationId: string; readonly url: string };
+export const ElicitationUrlMode = Schema.Struct({
+  elicitationId: Schema.String.annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.",
+  }),
+  url: Schema.String.annotate({ description: "The URL to direct the user to.", format: "uri" }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nURL-based elicitation mode where the client directs the user to a URL.",
+});
+
+export type EmbeddedResource = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly annotations?: Annotations | null;
+  readonly resource: EmbeddedResourceResource;
+};
+export const EmbeddedResource = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+  resource: EmbeddedResourceResource,
+}).annotate({
+  description: "The contents of a resource, embedded into a prompt or tool call result.",
+});
+
+export type ErrorCode =
+  | -32700
+  | -32600
+  | -32601
+  | -32602
+  | -32603
+  | -32800
+  | -32000
+  | -32002
+  | -32042
+  | number;
+export const ErrorCode = Schema.Union([
+  Schema.Literal(-32700).annotate({
+    title: "Parse error",
+    description:
+      "**Parse error**: Invalid JSON was received by the server.\nAn error occurred on the server while parsing the JSON text.",
+    format: "int32",
+  }),
+  Schema.Literal(-32600).annotate({
+    title: "Invalid request",
+    description: "**Invalid request**: The JSON sent is not a valid Request object.",
+    format: "int32",
+  }),
+  Schema.Literal(-32601).annotate({
+    title: "Method not found",
+    description: "**Method not found**: The method does not exist or is not available.",
+    format: "int32",
+  }),
+  Schema.Literal(-32602).annotate({
+    title: "Invalid params",
+    description: "**Invalid params**: Invalid method parameter(s).",
+    format: "int32",
+  }),
+  Schema.Literal(-32603).annotate({
+    title: "Internal error",
+    description:
+      "**Internal error**: Internal JSON-RPC error.\nReserved for implementation-defined server errors.",
+    format: "int32",
+  }),
+  Schema.Literal(-32800).annotate({
+    title: "Request cancelled",
+    description:
+      "**Request cancelled**: **UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nExecution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.",
+    format: "int32",
+  }),
+  Schema.Literal(-32000).annotate({
+    title: "Authentication required",
+    description:
+      "**Authentication required**: Authentication is required before this operation can be performed.",
+    format: "int32",
+  }),
+  Schema.Literal(-32002).annotate({
+    title: "Resource not found",
+    description: "**Resource not found**: A given resource, such as a file, was not found.",
+    format: "int32",
+  }),
+  Schema.Literal(-32042).annotate({
+    title: "URL elicitation required",
+    description:
+      "**URL elicitation required**: **UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe agent requires user input via a URL-based elicitation before it can proceed.",
+    format: "int32",
+  }),
+  Schema.Number.annotate({
+    title: "Other",
+    description: "Other undefined error code.",
+    format: "int32",
+  }).check(Schema.isInt()),
+]).annotate({
+  description:
+    "Predefined error codes for common JSON-RPC and ACP-specific errors.\n\nThese codes follow the JSON-RPC 2.0 specification for standard errors\nand use the reserved range (-32000 to -32099) for protocol-specific errors.",
+});
+
+export type ExtNotification = unknown;
+export const ExtNotification = Schema.Unknown.annotate({
+  description:
+    "Allows the Agent to send an arbitrary notification that is not part of the ACP spec.\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+});
+
+export type ExtRequest = unknown;
+export const ExtRequest = Schema.Unknown.annotate({
+  description:
+    "Allows for sending an arbitrary request that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+});
+
+export type ExtResponse = unknown;
+export const ExtResponse = Schema.Unknown.annotate({
+  description:
+    "Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+});
+
+export type FileSystemCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly readTextFile?: boolean;
+  readonly writeTextFile?: boolean;
+};
+export const FileSystemCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  readTextFile: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Whether the Client supports `fs/read_text_file` requests.",
+      default: false,
+    }),
+  ),
+  writeTextFile: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Whether the Client supports `fs/write_text_file` requests.",
+      default: false,
+    }),
+  ),
+}).annotate({
+  description:
+    "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)",
+});
+
+export type ForkSessionRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly cwd: string;
+  readonly mcpServers?: ReadonlyArray<McpServer>;
+  readonly sessionId: string;
+};
+export const ForkSessionRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.String.annotate({ description: "The working directory for this session." }),
+  mcpServers: Schema.optionalKey(
+    Schema.Array(McpServer).annotate({
+      description: "List of MCP servers to connect to for this session.",
+    }),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for forking an existing session.\n\nCreates a new session based on the context of an existing one, allowing\noperations like generating summaries without affecting the original session's history.\n\nOnly available if the Agent supports the `session.fork` capability.",
+});
+
+export type ForkSessionResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+  readonly models?: SessionModelState | null;
+  readonly modes?: SessionModeState | null;
+  readonly sessionId: string;
+};
+export const ForkSessionResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  configOptions: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(SessionConfigOption).annotate({
+        description: "Initial session configuration options if supported by the Agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  models: Schema.optionalKey(
+    Schema.Union([SessionModelState, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+    }),
+  ),
+  modes: Schema.optionalKey(
+    Schema.Union([SessionModeState, Schema.Null]).annotate({
+      description:
+        "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+    }),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from forking an existing session.",
+});
+
+export type ImageContent = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly annotations?: Annotations | null;
+  readonly data: string;
+  readonly mimeType: string;
+  readonly uri?: string | null;
+};
+export const ImageContent = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+  data: Schema.String,
+  mimeType: Schema.String,
+  uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ description: "An image provided to or from an LLM." });
+
+export type InitializeRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly clientCapabilities?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly auth?: {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly terminal?: boolean;
+    };
+    readonly elicitation?: ElicitationCapabilities | null;
+    readonly fs?: {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly readTextFile?: boolean;
+      readonly writeTextFile?: boolean;
+    };
+    readonly terminal?: boolean;
+  };
+  readonly clientInfo?: Implementation | null;
+  readonly protocolVersion: number;
+};
+export const InitializeRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  clientCapabilities: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      auth: Schema.optionalKey(
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          terminal: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description:
+                "Whether the client supports `terminal` authentication methods.\n\nWhen `true`, the agent may include `terminal` entries in its authentication methods.",
+              default: false,
+            }),
+          ),
+        }).annotate({
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.",
+          default: { terminal: false },
+        }),
+      ),
+      elicitation: Schema.optionalKey(
+        Schema.Union([ElicitationCapabilities, Schema.Null]).annotate({
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.",
+        }),
+      ),
+      fs: Schema.optionalKey(
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          readTextFile: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description: "Whether the Client supports `fs/read_text_file` requests.",
+              default: false,
+            }),
+          ),
+          writeTextFile: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description: "Whether the Client supports `fs/write_text_file` requests.",
+              default: false,
+            }),
+          ),
+        }).annotate({
+          description:
+            "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)",
+          default: { readTextFile: false, writeTextFile: false },
+        }),
+      ),
+      terminal: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Whether the Client support all `terminal/*` methods.",
+          default: false,
+        }),
+      ),
+    }).annotate({
+      description:
+        "Capabilities supported by the client.\n\nAdvertised during initialization to inform the agent about\navailable features and methods.\n\nSee protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities)",
+      default: {
+        auth: { terminal: false },
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+      },
+    }),
+  ),
+  clientInfo: Schema.optionalKey(
+    Schema.Union([Implementation, Schema.Null]).annotate({
+      description:
+        "Information about the Client name and version sent to the Agent.\n\nNote: in future versions of the protocol, this will be required.",
+    }),
+  ),
+  protocolVersion: Schema.Number.annotate({
+    description:
+      "Protocol version identifier.\n\nThis version is only bumped for breaking changes.\nNon-breaking changes should be introduced via capabilities.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0))
+    .check(Schema.isLessThanOrEqualTo(65535)),
+}).annotate({
+  description:
+    "Request parameters for the initialize method.\n\nSent by the client to establish connection and negotiate capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)",
+});
+
+export type InitializeResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly agentCapabilities?: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly auth?: {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly logout?: LogoutCapabilities | null;
+    };
+    readonly loadSession?: boolean;
+    readonly mcpCapabilities?: {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly http?: boolean;
+      readonly sse?: boolean;
+    };
+    readonly promptCapabilities?: {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly audio?: boolean;
+      readonly embeddedContext?: boolean;
+      readonly image?: boolean;
+    };
+    readonly sessionCapabilities?: {
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly close?: SessionCloseCapabilities | null;
+      readonly fork?: SessionForkCapabilities | null;
+      readonly list?: SessionListCapabilities | null;
+      readonly resume?: SessionResumeCapabilities | null;
+    };
+  };
+  readonly agentInfo?: Implementation | null;
+  readonly authMethods?: ReadonlyArray<AuthMethod>;
+  readonly protocolVersion: number;
+};
+export const InitializeResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentCapabilities: Schema.optionalKey(
+    Schema.Struct({
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      auth: Schema.optionalKey(
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          logout: Schema.optionalKey(
+            Schema.Union([LogoutCapabilities, Schema.Null]).annotate({
+              description:
+                "Whether the agent supports the logout method.\n\nBy supplying `{}` it means that the agent supports the logout method.",
+            }),
+          ),
+        }).annotate({
+          description:
+            "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication-related capabilities supported by the agent.",
+          default: {},
+        }),
+      ),
+      loadSession: Schema.optionalKey(
+        Schema.Boolean.annotate({
+          description: "Whether the agent supports `session/load`.",
+          default: false,
+        }),
+      ),
+      mcpCapabilities: Schema.optionalKey(
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          http: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description: "Agent supports [`McpServer::Http`].",
+              default: false,
+            }),
+          ),
+          sse: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description: "Agent supports [`McpServer::Sse`].",
+              default: false,
+            }),
+          ),
+        }).annotate({
+          description: "MCP capabilities supported by the agent",
+          default: { http: false, sse: false },
+        }),
+      ),
+      promptCapabilities: Schema.optionalKey(
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          audio: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description: "Agent supports [`ContentBlock::Audio`].",
+              default: false,
+            }),
+          ),
+          embeddedContext: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description:
+                "Agent supports embedded context in `session/prompt` requests.\n\nWhen enabled, the Client is allowed to include [`ContentBlock::Resource`]\nin prompt requests for pieces of context that are referenced in the message.",
+              default: false,
+            }),
+          ),
+          image: Schema.optionalKey(
+            Schema.Boolean.annotate({
+              description: "Agent supports [`ContentBlock::Image`].",
+              default: false,
+            }),
+          ),
+        }).annotate({
+          description:
+            "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for [`ContentBlock::Text`]\nand [`ContentBlock::ResourceLink`] in prompt requests.\n\nOther variants must be explicitly opted in to.\nCapabilities for different types of content in prompt requests.\n\nIndicates which content types beyond the baseline (text and resource links)\nthe agent can process.\n\nSee protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)",
+          default: { audio: false, embeddedContext: false, image: false },
+        }),
+      ),
+      sessionCapabilities: Schema.optionalKey(
+        Schema.Struct({
+          _meta: Schema.optionalKey(
+            Schema.Union([
+              Schema.Record(Schema.String, Schema.Unknown).annotate({
+                description:
+                  "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+              }),
+              Schema.Null,
+            ]),
+          ),
+          close: Schema.optionalKey(
+            Schema.Union([SessionCloseCapabilities, Schema.Null]).annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/close`.",
+            }),
+          ),
+          fork: Schema.optionalKey(
+            Schema.Union([SessionForkCapabilities, Schema.Null]).annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/fork`.",
+            }),
+          ),
+          list: Schema.optionalKey(
+            Schema.Union([SessionListCapabilities, Schema.Null]).annotate({
+              description: "Whether the agent supports `session/list`.",
+            }),
+          ),
+          resume: Schema.optionalKey(
+            Schema.Union([SessionResumeCapabilities, Schema.Null]).annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/resume`.",
+            }),
+          ),
+        }).annotate({
+          default: {},
+          description:
+            "Session capabilities supported by the agent.\n\nAs a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nOptionally, they **MAY** support other session methods and notifications by specifying additional capabilities.\n\nNote: `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities)",
+        }),
+      ),
+    }).annotate({
+      description:
+        "Capabilities supported by the agent.\n\nAdvertised during initialization to inform the client about\navailable features and content types.\n\nSee protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities)",
+      default: {
+        auth: {},
+        loadSession: false,
+        mcpCapabilities: { http: false, sse: false },
+        promptCapabilities: { audio: false, embeddedContext: false, image: false },
+        sessionCapabilities: {},
+      },
+    }),
+  ),
+  agentInfo: Schema.optionalKey(
+    Schema.Union([Implementation, Schema.Null]).annotate({
+      description:
+        "Information about the Agent name and version sent to the Client.\n\nNote: in future versions of the protocol, this will be required.",
+    }),
+  ),
+  authMethods: Schema.optionalKey(
+    Schema.Array(AuthMethod).annotate({
+      description: "Authentication methods supported by the agent.",
+      default: [],
+    }),
+  ),
+  protocolVersion: Schema.Number.annotate({
+    description:
+      "Protocol version identifier.\n\nThis version is only bumped for breaking changes.\nNon-breaking changes should be introduced via capabilities.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0))
+    .check(Schema.isLessThanOrEqualTo(65535)),
+}).annotate({
+  description:
+    "Response to the `initialize` method.\n\nContains the negotiated protocol version and agent capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)",
+});
+
+export type IntegerPropertySchema = {
+  readonly default?: number | null;
+  readonly description?: string | null;
+  readonly maximum?: number | null;
+  readonly minimum?: number | null;
+  readonly title?: string | null;
+};
+export const IntegerPropertySchema = Schema.Struct({
+  default: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Default value.", format: "int64" }).check(
+        Schema.isInt(),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Human-readable description." }),
+      Schema.Null,
+    ]),
+  ),
+  maximum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Maximum value (inclusive).", format: "int64" }).check(
+        Schema.isInt(),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  minimum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Minimum value (inclusive).", format: "int64" }).check(
+        Schema.isInt(),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional title for the property." }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Schema for integer properties in an elicitation form." });
+
+export type KillTerminalRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly sessionId: string;
+  readonly terminalId: string;
+};
+export const KillTerminalRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+  terminalId: Schema.String.annotate({ description: "The ID of the terminal to kill." }),
+}).annotate({ description: "Request to kill a terminal without releasing it." });
+
+export type KillTerminalResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const KillTerminalResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Response to `terminal/kill` method" });
+
+export type ListSessionsRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly cursor?: string | null;
+  readonly cwd?: string | null;
+};
+export const ListSessionsRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Filter sessions by working directory. Must be an absolute path.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "Request parameters for listing existing sessions.\n\nOnly available if the Agent supports the `sessionCapabilities.list` capability.",
+});
+
+export type ListSessionsResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly nextCursor?: string | null;
+  readonly sessions: ReadonlyArray<SessionInfo>;
+};
+export const ListSessionsResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  nextCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. If absent, there are no more results.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessions: Schema.Array(SessionInfo).annotate({
+    description: "Array of session information objects",
+  }),
+}).annotate({ description: "Response from listing sessions." });
+
+export type LoadSessionRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly cwd: string;
+  readonly mcpServers: ReadonlyArray<McpServer>;
+  readonly sessionId: string;
+};
+export const LoadSessionRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.String.annotate({ description: "The working directory for this session." }),
+  mcpServers: Schema.Array(McpServer).annotate({
+    description: "List of MCP servers to connect to for this session.",
+  }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `loadSession` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)",
+});
+
+export type LoadSessionResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+  readonly models?: SessionModelState | null;
+  readonly modes?: SessionModeState | null;
+};
+export const LoadSessionResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  configOptions: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(SessionConfigOption).annotate({
+        description: "Initial session configuration options if supported by the Agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  models: Schema.optionalKey(
+    Schema.Union([SessionModelState, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+    }),
+  ),
+  modes: Schema.optionalKey(
+    Schema.Union([SessionModeState, Schema.Null]).annotate({
+      description:
+        "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+    }),
+  ),
+}).annotate({ description: "Response from loading an existing session." });
+
+export type LogoutRequest = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const LogoutRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for the logout method.\n\nTerminates the current authenticated session.",
+});
+
+export type LogoutResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const LogoutResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to the `logout` method.",
+});
+
+export type McpCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly http?: boolean;
+  readonly sse?: boolean;
+};
+export const McpCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  http: Schema.optionalKey(
+    Schema.Boolean.annotate({ description: "Agent supports [`McpServer::Http`].", default: false }),
+  ),
+  sse: Schema.optionalKey(
+    Schema.Boolean.annotate({ description: "Agent supports [`McpServer::Sse`].", default: false }),
+  ),
+}).annotate({ description: "MCP capabilities supported by the agent" });
+
+export type McpServerHttp = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly headers: ReadonlyArray<HttpHeader>;
+  readonly name: string;
+  readonly url: string;
+};
+export const McpServerHttp = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  headers: Schema.Array(HttpHeader).annotate({
+    description: "HTTP headers to set when making requests to the MCP server.",
+  }),
+  name: Schema.String.annotate({ description: "Human-readable name identifying this MCP server." }),
+  url: Schema.String.annotate({ description: "URL to the MCP server." }),
+}).annotate({ description: "HTTP transport configuration for MCP." });
+
+export type McpServerSse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly headers: ReadonlyArray<HttpHeader>;
+  readonly name: string;
+  readonly url: string;
+};
+export const McpServerSse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  headers: Schema.Array(HttpHeader).annotate({
+    description: "HTTP headers to set when making requests to the MCP server.",
+  }),
+  name: Schema.String.annotate({ description: "Human-readable name identifying this MCP server." }),
+  url: Schema.String.annotate({ description: "URL to the MCP server." }),
+}).annotate({ description: "SSE transport configuration for MCP." });
+
+export type McpServerStdio = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly args: ReadonlyArray<string>;
+  readonly command: string;
+  readonly env: ReadonlyArray<EnvVariable>;
+  readonly name: string;
+};
+export const McpServerStdio = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  args: Schema.Array(Schema.String).annotate({
+    description: "Command-line arguments to pass to the MCP server.",
+  }),
+  command: Schema.String.annotate({ description: "Path to the MCP server executable." }),
+  env: Schema.Array(EnvVariable).annotate({
+    description: "Environment variables to set when launching the MCP server.",
+  }),
+  name: Schema.String.annotate({ description: "Human-readable name identifying this MCP server." }),
+}).annotate({ description: "Stdio transport configuration for MCP." });
+
+export type ModelId = string;
+export const ModelId = Schema.String.annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for a model.",
+});
+
+export type MultiSelectItems =
+  | { readonly enum: ReadonlyArray<string>; readonly type: "string" }
+  | { readonly anyOf: ReadonlyArray<EnumOption> };
+export const MultiSelectItems = Schema.Union([
+  Schema.Struct({
+    enum: Schema.Array(Schema.String).annotate({ description: "Allowed enum values." }),
+    type: Schema.Literal("string").annotate({
+      description: "Items definition for untitled multi-select enum properties.",
+    }),
+  }).annotate({
+    title: "Untitled",
+    description: "Items definition for untitled multi-select enum properties.",
+  }),
+  Schema.Struct({
+    anyOf: Schema.Array(EnumOption).annotate({ description: "Titled enum options." }),
+  }).annotate({
+    title: "Titled",
+    description: "Items definition for titled multi-select enum properties.",
+  }),
+]).annotate({ description: "Items for a multi-select (array) property schema." });
+
+export type MultiSelectPropertySchema = {
+  readonly default?: ReadonlyArray<string> | null;
+  readonly description?: string | null;
+  readonly items:
+    | { readonly enum: ReadonlyArray<string>; readonly type: "string" }
+    | { readonly anyOf: ReadonlyArray<EnumOption> };
+  readonly maxItems?: number | null;
+  readonly minItems?: number | null;
+  readonly title?: string | null;
+};
+export const MultiSelectPropertySchema = Schema.Struct({
+  default: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({ description: "Default selected values." }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Human-readable description." }),
+      Schema.Null,
+    ]),
+  ),
+  items: Schema.Union([
+    Schema.Struct({
+      enum: Schema.Array(Schema.String).annotate({ description: "Allowed enum values." }),
+      type: Schema.Literal("string").annotate({
+        description: "Items definition for untitled multi-select enum properties.",
+      }),
+    }).annotate({
+      title: "Untitled",
+      description: "Items definition for untitled multi-select enum properties.",
+    }),
+    Schema.Struct({
+      anyOf: Schema.Array(EnumOption).annotate({ description: "Titled enum options." }),
+    }).annotate({
+      title: "Titled",
+      description: "Items definition for titled multi-select enum properties.",
+    }),
+  ]).annotate({ description: "Items for a multi-select (array) property schema." }),
+  maxItems: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Maximum number of items to select.",
+        format: "uint64",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  minItems: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Minimum number of items to select.",
+        format: "uint64",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional title for the property." }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Schema for multi-select (array) properties in an elicitation form." });
+
+export type NewSessionRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly cwd: string;
+  readonly mcpServers: ReadonlyArray<McpServer>;
+};
+export const NewSessionRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.String.annotate({
+    description: "The working directory for this session. Must be an absolute path.",
+  }),
+  mcpServers: Schema.Array(McpServer).annotate({
+    description: "List of MCP (Model Context Protocol) servers the agent should connect to.",
+  }),
+}).annotate({
+  description:
+    "Request parameters for creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)",
+});
+
+export type NewSessionResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+  readonly models?: SessionModelState | null;
+  readonly modes?: SessionModeState | null;
+  readonly sessionId: string;
+};
+export const NewSessionResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  configOptions: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(SessionConfigOption).annotate({
+        description: "Initial session configuration options if supported by the Agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  models: Schema.optionalKey(
+    Schema.Union([SessionModelState, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+    }),
+  ),
+  modes: Schema.optionalKey(
+    Schema.Union([SessionModeState, Schema.Null]).annotate({
+      description:
+        "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+    }),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "Response from creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)",
+});
+
+export type NumberPropertySchema = {
+  readonly default?: number | null;
+  readonly description?: string | null;
+  readonly maximum?: number | null;
+  readonly minimum?: number | null;
+  readonly title?: string | null;
+};
+export const NumberPropertySchema = Schema.Struct({
+  default: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Default value.", format: "double" }).check(
+        Schema.isFinite(),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Human-readable description." }),
+      Schema.Null,
+    ]),
+  ),
+  maximum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Maximum value (inclusive).", format: "double" }).check(
+        Schema.isFinite(),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  minimum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Minimum value (inclusive).", format: "double" }).check(
+        Schema.isFinite(),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional title for the property." }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description: "Schema for number (floating-point) properties in an elicitation form.",
+});
+
+export type PermissionOptionId = string;
+export const PermissionOptionId = Schema.String.annotate({
+  description: "Unique identifier for a permission option.",
+});
+
+export type PermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+export const PermissionOptionKind = Schema.Literals([
+  "allow_once",
+  "allow_always",
+  "reject_once",
+  "reject_always",
+]).annotate({
+  description:
+    "The type of permission option being presented to the user.\n\nHelps clients choose appropriate icons and UI treatment.",
+});
+
+export type Plan = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly entries: ReadonlyArray<PlanEntry>;
+};
+export const Plan = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  entries: Schema.Array(PlanEntry).annotate({
+    description:
+      "The list of tasks to be accomplished.\n\nWhen updating a plan, the agent must send a complete list of all entries\nwith their current status. The client replaces the entire plan with each update.",
+  }),
+}).annotate({
+  description:
+    "An execution plan for accomplishing complex tasks.\n\nPlans consist of multiple entries representing individual tasks or goals.\nAgents report plans to clients to provide visibility into their execution strategy.\nPlans can evolve during execution as the agent discovers new requirements or completes tasks.\n\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)",
+});
+
+export type PlanEntryPriority = "high" | "medium" | "low";
+export const PlanEntryPriority = Schema.Literals(["high", "medium", "low"]).annotate({
+  description:
+    "Priority levels for plan entries.\n\nUsed to indicate the relative importance or urgency of different\ntasks in the execution plan.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)",
+});
+
+export type PlanEntryStatus = "pending" | "in_progress" | "completed";
+export const PlanEntryStatus = Schema.Literals(["pending", "in_progress", "completed"]).annotate({
+  description:
+    "Status of a plan entry in the execution flow.\n\nTracks the lifecycle of each task from planning through completion.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent-plan#plan-entries)",
+});
+
+export type PromptCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly audio?: boolean;
+  readonly embeddedContext?: boolean;
+  readonly image?: boolean;
+};
+export const PromptCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  audio: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Agent supports [`ContentBlock::Audio`].",
+      default: false,
+    }),
+  ),
+  embeddedContext: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Agent supports embedded context in `session/prompt` requests.\n\nWhen enabled, the Client is allowed to include [`ContentBlock::Resource`]\nin prompt requests for pieces of context that are referenced in the message.",
+      default: false,
+    }),
+  ),
+  image: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Agent supports [`ContentBlock::Image`].",
+      default: false,
+    }),
+  ),
+}).annotate({
+  description:
+    "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for [`ContentBlock::Text`]\nand [`ContentBlock::ResourceLink`] in prompt requests.\n\nOther variants must be explicitly opted in to.\nCapabilities for different types of content in prompt requests.\n\nIndicates which content types beyond the baseline (text and resource links)\nthe agent can process.\n\nSee protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)",
+});
+
+export type PromptRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly messageId?: string | null;
+  readonly prompt: ReadonlyArray<ContentBlock>;
+  readonly sessionId: string;
+};
+export const PromptRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  messageId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA client-generated unique identifier for this user message.\n\nIf provided, the Agent SHOULD echo this value as `userMessageId` in the\n[`PromptResponse`] to confirm it was recorded.\nBoth clients and agents MUST use UUID format for message IDs.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  prompt: Schema.Array(ContentBlock).annotate({
+    description:
+      "The blocks of content that compose the user's message.\n\nAs a baseline, the Agent MUST support [`ContentBlock::Text`] and [`ContentBlock::ResourceLink`],\nwhile other variants are optionally enabled via [`PromptCapabilities`].\n\nThe Client MUST adapt its interface according to [`PromptCapabilities`].\n\nThe client MAY include referenced pieces of context as either\n[`ContentBlock::Resource`] or [`ContentBlock::ResourceLink`].\n\nWhen available, [`ContentBlock::Resource`] is preferred\nas it avoids extra round-trips and allows the message to include\npieces of context from sources the agent may not have access to.",
+  }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "Request parameters for sending a user prompt to the agent.\n\nContains the user's message and any additional context.\n\nSee protocol docs: [User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message)",
+});
+
+export type PromptResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly stopReason: "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+  readonly usage?: Usage | null;
+  readonly userMessageId?: string | null;
+};
+export const PromptResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  stopReason: Schema.Literals([
+    "end_turn",
+    "max_tokens",
+    "max_turn_requests",
+    "refusal",
+    "cancelled",
+  ]).annotate({
+    description:
+      "Reasons why an agent stops processing a prompt turn.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons)",
+  }),
+  usage: Schema.optionalKey(
+    Schema.Union([Usage, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for this turn (optional).",
+    }),
+  ),
+  userMessageId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe acknowledged user message ID.\n\nIf the client provided a `messageId` in the [`PromptRequest`], the agent echoes it here\nto confirm it was recorded. If the client did not provide one, the agent MAY assign one\nand return it here. Absence of this field indicates the agent did not record a message ID.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "Response from processing a user prompt.\n\nSee protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion)",
+});
+
+export type ProtocolVersion = number;
+export const ProtocolVersion = Schema.Number.annotate({
+  description:
+    "Protocol version identifier.\n\nThis version is only bumped for breaking changes.\nNon-breaking changes should be introduced via capabilities.",
+  format: "uint16",
+})
+  .check(Schema.isInt())
+  .check(Schema.isGreaterThanOrEqualTo(0))
+  .check(Schema.isLessThanOrEqualTo(65535));
+
+export type ReadTextFileRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly limit?: number | null;
+  readonly line?: number | null;
+  readonly path: string;
+  readonly sessionId: string;
+};
+export const ReadTextFileRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Maximum number of lines to read.", format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  line: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Line number to start reading from (1-based).",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.String.annotate({ description: "Absolute path to the file to read." }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "Request to read content from a text file.\n\nOnly available if the client supports the `fs.readTextFile` capability.",
+});
+
+export type ReadTextFileResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly content: string;
+};
+export const ReadTextFileResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  content: Schema.String,
+}).annotate({ description: "Response containing the contents of a text file." });
+
+export type ReleaseTerminalRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly sessionId: string;
+  readonly terminalId: string;
+};
+export const ReleaseTerminalRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+  terminalId: Schema.String.annotate({ description: "The ID of the terminal to release." }),
+}).annotate({ description: "Request to release a terminal and free its resources." });
+
+export type ReleaseTerminalResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const ReleaseTerminalResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Response to terminal/release method" });
+
+export type RequestPermissionOutcome =
+  | { readonly outcome: "cancelled" }
+  | {
+      readonly outcome: "selected";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly optionId: string;
+    };
+export const RequestPermissionOutcome = Schema.Union(
+  [
+    Schema.Struct({ outcome: Schema.Literal("cancelled") }).annotate({
+      description:
+        "The prompt turn was cancelled before the user responded.\n\nWhen a client sends a `session/cancel` notification to cancel an ongoing\nprompt turn, it MUST respond to all pending `session/request_permission`\nrequests with this `Cancelled` outcome.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)",
+    }),
+    Schema.Struct({
+      outcome: Schema.Literal("selected"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      optionId: Schema.String.annotate({
+        description: "Unique identifier for a permission option.",
+      }),
+    }).annotate({ description: "The user selected one of the provided options." }),
+  ],
+  { mode: "oneOf" },
+).annotate({ description: "The outcome of a permission request." });
+
+export type RequestPermissionRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly options: ReadonlyArray<PermissionOption>;
+  readonly sessionId: string;
+  readonly toolCall: {
+    readonly _meta?: { readonly [x: string]: unknown } | null;
+    readonly content?: ReadonlyArray<ToolCallContent> | null;
+    readonly kind?: ToolKind | null;
+    readonly locations?: ReadonlyArray<ToolCallLocation> | null;
+    readonly rawInput?: unknown;
+    readonly rawOutput?: unknown;
+    readonly status?: ToolCallStatus | null;
+    readonly title?: string | null;
+    readonly toolCallId: string;
+  };
+};
+export const RequestPermissionRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  options: Schema.Array(PermissionOption).annotate({
+    description: "Available permission options for the user to choose from.",
+  }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+  toolCall: Schema.Struct({
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    content: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(ToolCallContent).annotate({ description: "Replace the content collection." }),
+        Schema.Null,
+      ]),
+    ),
+    kind: Schema.optionalKey(
+      Schema.Union([ToolKind, Schema.Null]).annotate({ description: "Update the tool kind." }),
+    ),
+    locations: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(ToolCallLocation).annotate({
+          description: "Replace the locations collection.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    rawInput: Schema.optionalKey(Schema.Unknown.annotate({ description: "Update the raw input." })),
+    rawOutput: Schema.optionalKey(
+      Schema.Unknown.annotate({ description: "Update the raw output." }),
+    ),
+    status: Schema.optionalKey(
+      Schema.Union([ToolCallStatus, Schema.Null]).annotate({
+        description: "Update the execution status.",
+      }),
+    ),
+    title: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({ description: "Update the human-readable title." }),
+        Schema.Null,
+      ]),
+    ),
+    toolCallId: Schema.String.annotate({
+      description: "Unique identifier for a tool call within a session.",
+    }),
+  }).annotate({
+    description:
+      "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)",
+  }),
+}).annotate({
+  description:
+    "Request for user permission to execute a tool call.\n\nSent when the agent needs authorization before performing a sensitive operation.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)",
+});
+
+export type RequestPermissionResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly outcome:
+    | { readonly outcome: "cancelled" }
+    | {
+        readonly outcome: "selected";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly optionId: string;
+      };
+};
+export const RequestPermissionResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  outcome: Schema.Union(
+    [
+      Schema.Struct({ outcome: Schema.Literal("cancelled") }).annotate({
+        description:
+          "The prompt turn was cancelled before the user responded.\n\nWhen a client sends a `session/cancel` notification to cancel an ongoing\nprompt turn, it MUST respond to all pending `session/request_permission`\nrequests with this `Cancelled` outcome.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)",
+      }),
+      Schema.Struct({
+        outcome: Schema.Literal("selected"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        optionId: Schema.String.annotate({
+          description: "Unique identifier for a permission option.",
+        }),
+      }).annotate({ description: "The user selected one of the provided options." }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "The outcome of a permission request." }),
+}).annotate({ description: "Response to a permission request." });
+
+export type ResourceLink = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly annotations?: Annotations | null;
+  readonly description?: string | null;
+  readonly mimeType?: string | null;
+  readonly name: string;
+  readonly size?: number | null;
+  readonly title?: string | null;
+  readonly uri: string;
+};
+export const ResourceLink = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  size: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  uri: Schema.String,
+}).annotate({
+  description:
+    "A resource that the server is capable of reading, included in a prompt or tool call result.",
+});
+
+export type ResumeSessionRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly cwd: string;
+  readonly mcpServers?: ReadonlyArray<McpServer>;
+  readonly sessionId: string;
+};
+export const ResumeSessionRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.String.annotate({ description: "The working directory for this session." }),
+  mcpServers: Schema.optionalKey(
+    Schema.Array(McpServer).annotate({
+      description: "List of MCP servers to connect to for this session.",
+    }),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `session.resume` capability.",
+});
+
+export type ResumeSessionResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly configOptions?: ReadonlyArray<SessionConfigOption> | null;
+  readonly models?: SessionModelState | null;
+  readonly modes?: SessionModeState | null;
+};
+export const ResumeSessionResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  configOptions: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(SessionConfigOption).annotate({
+        description: "Initial session configuration options if supported by the Agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  models: Schema.optionalKey(
+    Schema.Union([SessionModelState, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial model state if supported by the Agent",
+    }),
+  ),
+  modes: Schema.optionalKey(
+    Schema.Union([SessionModeState, Schema.Null]).annotate({
+      description:
+        "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+    }),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from resuming an existing session.",
+});
+
+export type SelectedPermissionOutcome = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly optionId: string;
+};
+export const SelectedPermissionOutcome = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  optionId: Schema.String.annotate({ description: "Unique identifier for a permission option." }),
+}).annotate({ description: "The user selected one of the provided options." });
+
+export type SessionCapabilities = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly close?: SessionCloseCapabilities | null;
+  readonly fork?: SessionForkCapabilities | null;
+  readonly list?: SessionListCapabilities | null;
+  readonly resume?: SessionResumeCapabilities | null;
+};
+export const SessionCapabilities = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  close: Schema.optionalKey(
+    Schema.Union([SessionCloseCapabilities, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/close`.",
+    }),
+  ),
+  fork: Schema.optionalKey(
+    Schema.Union([SessionForkCapabilities, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/fork`.",
+    }),
+  ),
+  list: Schema.optionalKey(
+    Schema.Union([SessionListCapabilities, Schema.Null]).annotate({
+      description: "Whether the agent supports `session/list`.",
+    }),
+  ),
+  resume: Schema.optionalKey(
+    Schema.Union([SessionResumeCapabilities, Schema.Null]).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/resume`.",
+    }),
+  ),
+}).annotate({
+  description:
+    "Session capabilities supported by the agent.\n\nAs a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nOptionally, they **MAY** support other session methods and notifications by specifying additional capabilities.\n\nNote: `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities)",
+});
+
+export type SessionConfigBoolean = { readonly currentValue: boolean };
+export const SessionConfigBoolean = Schema.Struct({
+  currentValue: Schema.Boolean.annotate({
+    description: "The current value of the boolean option.",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA boolean on/off toggle session configuration option payload.",
+});
+
+export type SessionConfigGroupId = string;
+export const SessionConfigGroupId = Schema.String.annotate({
+  description: "Unique identifier for a session configuration option value group.",
+});
+
+export type SessionConfigId = string;
+export const SessionConfigId = Schema.String.annotate({
+  description: "Unique identifier for a session configuration option.",
+});
+
+export type SessionConfigSelect = {
+  readonly currentValue: string;
+  readonly options:
+    | ReadonlyArray<SessionConfigSelectOption>
+    | ReadonlyArray<SessionConfigSelectGroup>;
+};
+export const SessionConfigSelect = Schema.Struct({
+  currentValue: Schema.String.annotate({
+    description: "Unique identifier for a session configuration option value.",
+  }),
+  options: Schema.Union([
+    Schema.Array(SessionConfigSelectOption).annotate({
+      title: "Ungrouped",
+      description: "A flat list of options with no grouping.",
+    }),
+    Schema.Array(SessionConfigSelectGroup).annotate({
+      title: "Grouped",
+      description: "A list of options grouped under headers.",
+    }),
+  ]).annotate({ description: "Possible values for a session configuration option." }),
+}).annotate({
+  description: "A single-value selector (dropdown) session configuration option payload.",
+});
+
+export type SessionConfigSelectOptions =
+  | ReadonlyArray<SessionConfigSelectOption>
+  | ReadonlyArray<SessionConfigSelectGroup>;
+export const SessionConfigSelectOptions = Schema.Union([
+  Schema.Array(SessionConfigSelectOption).annotate({
+    title: "Ungrouped",
+    description: "A flat list of options with no grouping.",
+  }),
+  Schema.Array(SessionConfigSelectGroup).annotate({
+    title: "Grouped",
+    description: "A list of options grouped under headers.",
+  }),
+]).annotate({ description: "Possible values for a session configuration option." });
+
+export type SessionConfigValueId = string;
+export const SessionConfigValueId = Schema.String.annotate({
+  description: "Unique identifier for a session configuration option value.",
+});
+
+export type SessionId = string;
+export const SessionId = Schema.String.annotate({
+  description:
+    "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+});
+
+export type SessionInfoUpdate = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly title?: string | null;
+  readonly updatedAt?: string | null;
+};
+export const SessionInfoUpdate = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Human-readable title for the session. Set to null to clear.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  updatedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "ISO 8601 timestamp of last activity. Set to null to clear.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "Update to session metadata. All fields are optional to support partial updates.\n\nAgents send this notification to update session information like title or custom metadata.\nThis allows clients to display dynamic session names and track session state changes.",
+});
+
+export type SessionNotification = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly sessionId: string;
+  readonly update:
+    | {
+        readonly sessionUpdate: "user_message_chunk";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly content:
+          | {
+              readonly type: "text";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly text: string;
+            }
+          | {
+              readonly type: "image";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly data: string;
+              readonly mimeType: string;
+              readonly uri?: string | null;
+            }
+          | {
+              readonly type: "audio";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly data: string;
+              readonly mimeType: string;
+            }
+          | {
+              readonly type: "resource_link";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly description?: string | null;
+              readonly mimeType?: string | null;
+              readonly name: string;
+              readonly size?: number | null;
+              readonly title?: string | null;
+              readonly uri: string;
+            }
+          | {
+              readonly type: "resource";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly resource: EmbeddedResourceResource;
+            };
+        readonly messageId?: string | null;
+      }
+    | {
+        readonly sessionUpdate: "agent_message_chunk";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly content:
+          | {
+              readonly type: "text";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly text: string;
+            }
+          | {
+              readonly type: "image";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly data: string;
+              readonly mimeType: string;
+              readonly uri?: string | null;
+            }
+          | {
+              readonly type: "audio";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly data: string;
+              readonly mimeType: string;
+            }
+          | {
+              readonly type: "resource_link";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly description?: string | null;
+              readonly mimeType?: string | null;
+              readonly name: string;
+              readonly size?: number | null;
+              readonly title?: string | null;
+              readonly uri: string;
+            }
+          | {
+              readonly type: "resource";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly resource: EmbeddedResourceResource;
+            };
+        readonly messageId?: string | null;
+      }
+    | {
+        readonly sessionUpdate: "agent_thought_chunk";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly content:
+          | {
+              readonly type: "text";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly text: string;
+            }
+          | {
+              readonly type: "image";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly data: string;
+              readonly mimeType: string;
+              readonly uri?: string | null;
+            }
+          | {
+              readonly type: "audio";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly data: string;
+              readonly mimeType: string;
+            }
+          | {
+              readonly type: "resource_link";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly description?: string | null;
+              readonly mimeType?: string | null;
+              readonly name: string;
+              readonly size?: number | null;
+              readonly title?: string | null;
+              readonly uri: string;
+            }
+          | {
+              readonly type: "resource";
+              readonly _meta?: { readonly [x: string]: unknown } | null;
+              readonly annotations?: Annotations | null;
+              readonly resource: EmbeddedResourceResource;
+            };
+        readonly messageId?: string | null;
+      }
+    | {
+        readonly sessionUpdate: "tool_call";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly content?: ReadonlyArray<ToolCallContent>;
+        readonly kind?:
+          | "read"
+          | "edit"
+          | "delete"
+          | "move"
+          | "search"
+          | "execute"
+          | "think"
+          | "fetch"
+          | "switch_mode"
+          | "other";
+        readonly locations?: ReadonlyArray<ToolCallLocation>;
+        readonly rawInput?: unknown;
+        readonly rawOutput?: unknown;
+        readonly status?: "pending" | "in_progress" | "completed" | "failed";
+        readonly title: string;
+        readonly toolCallId: string;
+      }
+    | {
+        readonly sessionUpdate: "tool_call_update";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly content?: ReadonlyArray<ToolCallContent> | null;
+        readonly kind?: ToolKind | null;
+        readonly locations?: ReadonlyArray<ToolCallLocation> | null;
+        readonly rawInput?: unknown;
+        readonly rawOutput?: unknown;
+        readonly status?: ToolCallStatus | null;
+        readonly title?: string | null;
+        readonly toolCallId: string;
+      }
+    | {
+        readonly sessionUpdate: "plan";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly entries: ReadonlyArray<PlanEntry>;
+      }
+    | {
+        readonly sessionUpdate: "available_commands_update";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly availableCommands: ReadonlyArray<AvailableCommand>;
+      }
+    | {
+        readonly sessionUpdate: "current_mode_update";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly currentModeId: string;
+      }
+    | {
+        readonly sessionUpdate: "config_option_update";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly configOptions: ReadonlyArray<SessionConfigOption>;
+      }
+    | {
+        readonly sessionUpdate: "session_info_update";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly title?: string | null;
+        readonly updatedAt?: string | null;
+      }
+    | {
+        readonly sessionUpdate: "usage_update";
+        readonly _meta?: { readonly [x: string]: unknown } | null;
+        readonly cost?: Cost | null;
+        readonly size: number;
+        readonly used: number;
+      };
+};
+export const SessionNotification = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+  update: Schema.Union(
+    [
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("user_message_chunk"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        content: Schema.Union(
+          [
+            Schema.Struct({
+              type: Schema.Literal("text"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              text: Schema.String,
+            }).annotate({ description: "Text provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("image"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              data: Schema.String,
+              mimeType: Schema.String,
+              uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            }).annotate({ description: "An image provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("audio"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              data: Schema.String,
+              mimeType: Schema.String,
+            }).annotate({ description: "Audio provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("resource_link"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              name: Schema.String,
+              size: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                  Schema.Null,
+                ]),
+              ),
+              title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              uri: Schema.String,
+            }).annotate({
+              description:
+                "A resource that the server is capable of reading, included in a prompt or tool call result.",
+            }),
+            Schema.Struct({
+              type: Schema.Literal("resource"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              resource: EmbeddedResourceResource,
+            }).annotate({
+              description:
+                "The contents of a resource, embedded into a prompt or tool call result.",
+            }),
+          ],
+          { mode: "oneOf" },
+        ).annotate({
+          description:
+            "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+        }),
+        messageId: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({ description: "A streamed item of content" }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("agent_message_chunk"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        content: Schema.Union(
+          [
+            Schema.Struct({
+              type: Schema.Literal("text"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              text: Schema.String,
+            }).annotate({ description: "Text provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("image"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              data: Schema.String,
+              mimeType: Schema.String,
+              uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            }).annotate({ description: "An image provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("audio"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              data: Schema.String,
+              mimeType: Schema.String,
+            }).annotate({ description: "Audio provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("resource_link"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              name: Schema.String,
+              size: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                  Schema.Null,
+                ]),
+              ),
+              title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              uri: Schema.String,
+            }).annotate({
+              description:
+                "A resource that the server is capable of reading, included in a prompt or tool call result.",
+            }),
+            Schema.Struct({
+              type: Schema.Literal("resource"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              resource: EmbeddedResourceResource,
+            }).annotate({
+              description:
+                "The contents of a resource, embedded into a prompt or tool call result.",
+            }),
+          ],
+          { mode: "oneOf" },
+        ).annotate({
+          description:
+            "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+        }),
+        messageId: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({ description: "A streamed item of content" }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("agent_thought_chunk"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        content: Schema.Union(
+          [
+            Schema.Struct({
+              type: Schema.Literal("text"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              text: Schema.String,
+            }).annotate({ description: "Text provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("image"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              data: Schema.String,
+              mimeType: Schema.String,
+              uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            }).annotate({ description: "An image provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("audio"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              data: Schema.String,
+              mimeType: Schema.String,
+            }).annotate({ description: "Audio provided to or from an LLM." }),
+            Schema.Struct({
+              type: Schema.Literal("resource_link"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              name: Schema.String,
+              size: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                  Schema.Null,
+                ]),
+              ),
+              title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+              uri: Schema.String,
+            }).annotate({
+              description:
+                "A resource that the server is capable of reading, included in a prompt or tool call result.",
+            }),
+            Schema.Struct({
+              type: Schema.Literal("resource"),
+              _meta: Schema.optionalKey(
+                Schema.Union([
+                  Schema.Record(Schema.String, Schema.Unknown).annotate({
+                    description:
+                      "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                  }),
+                  Schema.Null,
+                ]),
+              ),
+              annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+              resource: EmbeddedResourceResource,
+            }).annotate({
+              description:
+                "The contents of a resource, embedded into a prompt or tool call result.",
+            }),
+          ],
+          { mode: "oneOf" },
+        ).annotate({
+          description:
+            "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+        }),
+        messageId: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description:
+                "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({ description: "A streamed item of content" }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("tool_call"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        content: Schema.optionalKey(
+          Schema.Array(ToolCallContent).annotate({
+            description: "Content produced by the tool call.",
+          }),
+        ),
+        kind: Schema.optionalKey(
+          Schema.Literals([
+            "read",
+            "edit",
+            "delete",
+            "move",
+            "search",
+            "execute",
+            "think",
+            "fetch",
+            "switch_mode",
+            "other",
+          ]).annotate({
+            description:
+              "Categories of tools that can be invoked.\n\nTool kinds help clients choose appropriate icons and optimize how they\ndisplay tool execution progress.\n\nSee protocol docs: [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating)",
+          }),
+        ),
+        locations: Schema.optionalKey(
+          Schema.Array(ToolCallLocation).annotate({
+            description:
+              'File locations affected by this tool call.\nEnables "follow-along" features in clients.',
+          }),
+        ),
+        rawInput: Schema.optionalKey(
+          Schema.Unknown.annotate({ description: "Raw input parameters sent to the tool." }),
+        ),
+        rawOutput: Schema.optionalKey(
+          Schema.Unknown.annotate({ description: "Raw output returned by the tool." }),
+        ),
+        status: Schema.optionalKey(
+          Schema.Literals(["pending", "in_progress", "completed", "failed"]).annotate({
+            description:
+              "Execution status of a tool call.\n\nTool calls progress through different statuses during their lifecycle.\n\nSee protocol docs: [Status](https://agentclientprotocol.com/protocol/tool-calls#status)",
+          }),
+        ),
+        title: Schema.String.annotate({
+          description: "Human-readable title describing what the tool is doing.",
+        }),
+        toolCallId: Schema.String.annotate({
+          description: "Unique identifier for a tool call within a session.",
+        }),
+      }).annotate({
+        description:
+          "Represents a tool call that the language model has requested.\n\nTool calls are actions that the agent executes on behalf of the language model,\nsuch as reading files, executing code, or fetching data from external sources.\n\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/tool-calls)",
+      }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("tool_call_update"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        content: Schema.optionalKey(
+          Schema.Union([
+            Schema.Array(ToolCallContent).annotate({
+              description: "Replace the content collection.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        kind: Schema.optionalKey(
+          Schema.Union([ToolKind, Schema.Null]).annotate({ description: "Update the tool kind." }),
+        ),
+        locations: Schema.optionalKey(
+          Schema.Union([
+            Schema.Array(ToolCallLocation).annotate({
+              description: "Replace the locations collection.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        rawInput: Schema.optionalKey(
+          Schema.Unknown.annotate({ description: "Update the raw input." }),
+        ),
+        rawOutput: Schema.optionalKey(
+          Schema.Unknown.annotate({ description: "Update the raw output." }),
+        ),
+        status: Schema.optionalKey(
+          Schema.Union([ToolCallStatus, Schema.Null]).annotate({
+            description: "Update the execution status.",
+          }),
+        ),
+        title: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({ description: "Update the human-readable title." }),
+            Schema.Null,
+          ]),
+        ),
+        toolCallId: Schema.String.annotate({
+          description: "Unique identifier for a tool call within a session.",
+        }),
+      }).annotate({
+        description:
+          "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)",
+      }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("plan"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        entries: Schema.Array(PlanEntry).annotate({
+          description:
+            "The list of tasks to be accomplished.\n\nWhen updating a plan, the agent must send a complete list of all entries\nwith their current status. The client replaces the entire plan with each update.",
+        }),
+      }).annotate({
+        description:
+          "An execution plan for accomplishing complex tasks.\n\nPlans consist of multiple entries representing individual tasks or goals.\nAgents report plans to clients to provide visibility into their execution strategy.\nPlans can evolve during execution as the agent discovers new requirements or completes tasks.\n\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)",
+      }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("available_commands_update"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        availableCommands: Schema.Array(AvailableCommand).annotate({
+          description: "Commands the agent can execute",
+        }),
+      }).annotate({ description: "Available commands are ready or have changed" }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("current_mode_update"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        currentModeId: Schema.String.annotate({
+          description: "Unique identifier for a Session Mode.",
+        }),
+      }).annotate({
+        description:
+          "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+      }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("config_option_update"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        configOptions: Schema.Array(SessionConfigOption).annotate({
+          description: "The full set of configuration options and their current values.",
+        }),
+      }).annotate({ description: "Session configuration options have been updated." }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("session_info_update"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        title: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description: "Human-readable title for the session. Set to null to clear.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        updatedAt: Schema.optionalKey(
+          Schema.Union([
+            Schema.String.annotate({
+              description: "ISO 8601 timestamp of last activity. Set to null to clear.",
+            }),
+            Schema.Null,
+          ]),
+        ),
+      }).annotate({
+        description:
+          "Update to session metadata. All fields are optional to support partial updates.\n\nAgents send this notification to update session information like title or custom metadata.\nThis allows clients to display dynamic session names and track session state changes.",
+      }),
+      Schema.Struct({
+        sessionUpdate: Schema.Literal("usage_update"),
+        _meta: Schema.optionalKey(
+          Schema.Union([
+            Schema.Record(Schema.String, Schema.Unknown).annotate({
+              description:
+                "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+            }),
+            Schema.Null,
+          ]),
+        ),
+        cost: Schema.optionalKey(
+          Schema.Union([Cost, Schema.Null]).annotate({
+            description: "Cumulative session cost (optional).",
+          }),
+        ),
+        size: Schema.Number.annotate({
+          description: "Total context window size in tokens.",
+          format: "uint64",
+        })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        used: Schema.Number.annotate({
+          description: "Tokens currently in context.",
+          format: "uint64",
+        })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+      }).annotate({
+        description:
+          "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for a session.",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description:
+      "Different types of updates that can be sent during session processing.\n\nThese updates provide real-time feedback about the agent's progress.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)",
+  }),
+}).annotate({
+  description:
+    "Notification containing a session update from the agent.\n\nUsed to stream real-time progress and results during prompt processing.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)",
+});
+
+export type SessionUpdate =
+  | {
+      readonly sessionUpdate: "user_message_chunk";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly content:
+        | {
+            readonly type: "text";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly text: string;
+          }
+        | {
+            readonly type: "image";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+            readonly uri?: string | null;
+          }
+        | {
+            readonly type: "audio";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+          }
+        | {
+            readonly type: "resource_link";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly description?: string | null;
+            readonly mimeType?: string | null;
+            readonly name: string;
+            readonly size?: number | null;
+            readonly title?: string | null;
+            readonly uri: string;
+          }
+        | {
+            readonly type: "resource";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly resource: EmbeddedResourceResource;
+          };
+      readonly messageId?: string | null;
+    }
+  | {
+      readonly sessionUpdate: "agent_message_chunk";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly content:
+        | {
+            readonly type: "text";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly text: string;
+          }
+        | {
+            readonly type: "image";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+            readonly uri?: string | null;
+          }
+        | {
+            readonly type: "audio";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+          }
+        | {
+            readonly type: "resource_link";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly description?: string | null;
+            readonly mimeType?: string | null;
+            readonly name: string;
+            readonly size?: number | null;
+            readonly title?: string | null;
+            readonly uri: string;
+          }
+        | {
+            readonly type: "resource";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly resource: EmbeddedResourceResource;
+          };
+      readonly messageId?: string | null;
+    }
+  | {
+      readonly sessionUpdate: "agent_thought_chunk";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly content:
+        | {
+            readonly type: "text";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly text: string;
+          }
+        | {
+            readonly type: "image";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+            readonly uri?: string | null;
+          }
+        | {
+            readonly type: "audio";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly data: string;
+            readonly mimeType: string;
+          }
+        | {
+            readonly type: "resource_link";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly description?: string | null;
+            readonly mimeType?: string | null;
+            readonly name: string;
+            readonly size?: number | null;
+            readonly title?: string | null;
+            readonly uri: string;
+          }
+        | {
+            readonly type: "resource";
+            readonly _meta?: { readonly [x: string]: unknown } | null;
+            readonly annotations?: Annotations | null;
+            readonly resource: EmbeddedResourceResource;
+          };
+      readonly messageId?: string | null;
+    }
+  | {
+      readonly sessionUpdate: "tool_call";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly content?: ReadonlyArray<ToolCallContent>;
+      readonly kind?:
+        | "read"
+        | "edit"
+        | "delete"
+        | "move"
+        | "search"
+        | "execute"
+        | "think"
+        | "fetch"
+        | "switch_mode"
+        | "other";
+      readonly locations?: ReadonlyArray<ToolCallLocation>;
+      readonly rawInput?: unknown;
+      readonly rawOutput?: unknown;
+      readonly status?: "pending" | "in_progress" | "completed" | "failed";
+      readonly title: string;
+      readonly toolCallId: string;
+    }
+  | {
+      readonly sessionUpdate: "tool_call_update";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly content?: ReadonlyArray<ToolCallContent> | null;
+      readonly kind?: ToolKind | null;
+      readonly locations?: ReadonlyArray<ToolCallLocation> | null;
+      readonly rawInput?: unknown;
+      readonly rawOutput?: unknown;
+      readonly status?: ToolCallStatus | null;
+      readonly title?: string | null;
+      readonly toolCallId: string;
+    }
+  | {
+      readonly sessionUpdate: "plan";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly entries: ReadonlyArray<PlanEntry>;
+    }
+  | {
+      readonly sessionUpdate: "available_commands_update";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly availableCommands: ReadonlyArray<AvailableCommand>;
+    }
+  | {
+      readonly sessionUpdate: "current_mode_update";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly currentModeId: string;
+    }
+  | {
+      readonly sessionUpdate: "config_option_update";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly configOptions: ReadonlyArray<SessionConfigOption>;
+    }
+  | {
+      readonly sessionUpdate: "session_info_update";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly title?: string | null;
+      readonly updatedAt?: string | null;
+    }
+  | {
+      readonly sessionUpdate: "usage_update";
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly cost?: Cost | null;
+      readonly size: number;
+      readonly used: number;
+    };
+export const SessionUpdate = Schema.Union(
+  [
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("user_message_chunk"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      content: Schema.Union(
+        [
+          Schema.Struct({
+            type: Schema.Literal("text"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            text: Schema.String,
+          }).annotate({ description: "Text provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("image"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+            uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+          }).annotate({ description: "An image provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("audio"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+          }).annotate({ description: "Audio provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("resource_link"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            name: Schema.String,
+            size: Schema.optionalKey(
+              Schema.Union([
+                Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                Schema.Null,
+              ]),
+            ),
+            title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            uri: Schema.String,
+          }).annotate({
+            description:
+              "A resource that the server is capable of reading, included in a prompt or tool call result.",
+          }),
+          Schema.Struct({
+            type: Schema.Literal("resource"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            resource: EmbeddedResourceResource,
+          }).annotate({
+            description: "The contents of a resource, embedded into a prompt or tool call result.",
+          }),
+        ],
+        { mode: "oneOf" },
+      ).annotate({
+        description:
+          "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+      }),
+      messageId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({ description: "A streamed item of content" }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("agent_message_chunk"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      content: Schema.Union(
+        [
+          Schema.Struct({
+            type: Schema.Literal("text"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            text: Schema.String,
+          }).annotate({ description: "Text provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("image"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+            uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+          }).annotate({ description: "An image provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("audio"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+          }).annotate({ description: "Audio provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("resource_link"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            name: Schema.String,
+            size: Schema.optionalKey(
+              Schema.Union([
+                Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                Schema.Null,
+              ]),
+            ),
+            title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            uri: Schema.String,
+          }).annotate({
+            description:
+              "A resource that the server is capable of reading, included in a prompt or tool call result.",
+          }),
+          Schema.Struct({
+            type: Schema.Literal("resource"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            resource: EmbeddedResourceResource,
+          }).annotate({
+            description: "The contents of a resource, embedded into a prompt or tool call result.",
+          }),
+        ],
+        { mode: "oneOf" },
+      ).annotate({
+        description:
+          "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+      }),
+      messageId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({ description: "A streamed item of content" }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("agent_thought_chunk"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      content: Schema.Union(
+        [
+          Schema.Struct({
+            type: Schema.Literal("text"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            text: Schema.String,
+          }).annotate({ description: "Text provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("image"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+            uri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+          }).annotate({ description: "An image provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("audio"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            data: Schema.String,
+            mimeType: Schema.String,
+          }).annotate({ description: "Audio provided to or from an LLM." }),
+          Schema.Struct({
+            type: Schema.Literal("resource_link"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            name: Schema.String,
+            size: Schema.optionalKey(
+              Schema.Union([
+                Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+                Schema.Null,
+              ]),
+            ),
+            title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+            uri: Schema.String,
+          }).annotate({
+            description:
+              "A resource that the server is capable of reading, included in a prompt or tool call result.",
+          }),
+          Schema.Struct({
+            type: Schema.Literal("resource"),
+            _meta: Schema.optionalKey(
+              Schema.Union([
+                Schema.Record(Schema.String, Schema.Unknown).annotate({
+                  description:
+                    "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+                }),
+                Schema.Null,
+              ]),
+            ),
+            annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+            resource: EmbeddedResourceResource,
+          }).annotate({
+            description: "The contents of a resource, embedded into a prompt or tool call result.",
+          }),
+        ],
+        { mode: "oneOf" },
+      ).annotate({
+        description:
+          "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content—whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/content)",
+      }),
+      messageId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({ description: "A streamed item of content" }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("tool_call"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      content: Schema.optionalKey(
+        Schema.Array(ToolCallContent).annotate({
+          description: "Content produced by the tool call.",
+        }),
+      ),
+      kind: Schema.optionalKey(
+        Schema.Literals([
+          "read",
+          "edit",
+          "delete",
+          "move",
+          "search",
+          "execute",
+          "think",
+          "fetch",
+          "switch_mode",
+          "other",
+        ]).annotate({
+          description:
+            "Categories of tools that can be invoked.\n\nTool kinds help clients choose appropriate icons and optimize how they\ndisplay tool execution progress.\n\nSee protocol docs: [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating)",
+        }),
+      ),
+      locations: Schema.optionalKey(
+        Schema.Array(ToolCallLocation).annotate({
+          description:
+            'File locations affected by this tool call.\nEnables "follow-along" features in clients.',
+        }),
+      ),
+      rawInput: Schema.optionalKey(
+        Schema.Unknown.annotate({ description: "Raw input parameters sent to the tool." }),
+      ),
+      rawOutput: Schema.optionalKey(
+        Schema.Unknown.annotate({ description: "Raw output returned by the tool." }),
+      ),
+      status: Schema.optionalKey(
+        Schema.Literals(["pending", "in_progress", "completed", "failed"]).annotate({
+          description:
+            "Execution status of a tool call.\n\nTool calls progress through different statuses during their lifecycle.\n\nSee protocol docs: [Status](https://agentclientprotocol.com/protocol/tool-calls#status)",
+        }),
+      ),
+      title: Schema.String.annotate({
+        description: "Human-readable title describing what the tool is doing.",
+      }),
+      toolCallId: Schema.String.annotate({
+        description: "Unique identifier for a tool call within a session.",
+      }),
+    }).annotate({
+      description:
+        "Represents a tool call that the language model has requested.\n\nTool calls are actions that the agent executes on behalf of the language model,\nsuch as reading files, executing code, or fetching data from external sources.\n\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/tool-calls)",
+    }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("tool_call_update"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      content: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(ToolCallContent).annotate({
+            description: "Replace the content collection.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      kind: Schema.optionalKey(
+        Schema.Union([ToolKind, Schema.Null]).annotate({ description: "Update the tool kind." }),
+      ),
+      locations: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(ToolCallLocation).annotate({
+            description: "Replace the locations collection.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      rawInput: Schema.optionalKey(
+        Schema.Unknown.annotate({ description: "Update the raw input." }),
+      ),
+      rawOutput: Schema.optionalKey(
+        Schema.Unknown.annotate({ description: "Update the raw output." }),
+      ),
+      status: Schema.optionalKey(
+        Schema.Union([ToolCallStatus, Schema.Null]).annotate({
+          description: "Update the execution status.",
+        }),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Update the human-readable title." }),
+          Schema.Null,
+        ]),
+      ),
+      toolCallId: Schema.String.annotate({
+        description: "Unique identifier for a tool call within a session.",
+      }),
+    }).annotate({
+      description:
+        "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)",
+    }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("plan"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      entries: Schema.Array(PlanEntry).annotate({
+        description:
+          "The list of tasks to be accomplished.\n\nWhen updating a plan, the agent must send a complete list of all entries\nwith their current status. The client replaces the entire plan with each update.",
+      }),
+    }).annotate({
+      description:
+        "An execution plan for accomplishing complex tasks.\n\nPlans consist of multiple entries representing individual tasks or goals.\nAgents report plans to clients to provide visibility into their execution strategy.\nPlans can evolve during execution as the agent discovers new requirements or completes tasks.\n\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)",
+    }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("available_commands_update"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      availableCommands: Schema.Array(AvailableCommand).annotate({
+        description: "Commands the agent can execute",
+      }),
+    }).annotate({ description: "Available commands are ready or have changed" }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("current_mode_update"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      currentModeId: Schema.String.annotate({
+        description: "Unique identifier for a Session Mode.",
+      }),
+    }).annotate({
+      description:
+        "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)",
+    }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("config_option_update"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      configOptions: Schema.Array(SessionConfigOption).annotate({
+        description: "The full set of configuration options and their current values.",
+      }),
+    }).annotate({ description: "Session configuration options have been updated." }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("session_info_update"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Human-readable title for the session. Set to null to clear.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      updatedAt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "ISO 8601 timestamp of last activity. Set to null to clear.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({
+      description:
+        "Update to session metadata. All fields are optional to support partial updates.\n\nAgents send this notification to update session information like title or custom metadata.\nThis allows clients to display dynamic session names and track session state changes.",
+    }),
+    Schema.Struct({
+      sessionUpdate: Schema.Literal("usage_update"),
+      _meta: Schema.optionalKey(
+        Schema.Union([
+          Schema.Record(Schema.String, Schema.Unknown).annotate({
+            description:
+              "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      cost: Schema.optionalKey(
+        Schema.Union([Cost, Schema.Null]).annotate({
+          description: "Cumulative session cost (optional).",
+        }),
+      ),
+      size: Schema.Number.annotate({
+        description: "Total context window size in tokens.",
+        format: "uint64",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      used: Schema.Number.annotate({
+        description: "Tokens currently in context.",
+        format: "uint64",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+    }).annotate({
+      description:
+        "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for a session.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "Different types of updates that can be sent during session processing.\n\nThese updates provide real-time feedback about the agent's progress.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)",
+});
+
+export type SetSessionConfigOptionRequest =
+  | {
+      readonly type: "boolean";
+      readonly value: boolean;
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly configId: string;
+      readonly sessionId: string;
+    }
+  | {
+      readonly value: string;
+      readonly _meta?: { readonly [x: string]: unknown } | null;
+      readonly configId: string;
+      readonly sessionId: string;
+    };
+export const SetSessionConfigOptionRequest = Schema.Union([
+  Schema.Struct({
+    type: Schema.Literal("boolean"),
+    value: Schema.Boolean.annotate({ description: "The boolean value." }),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    configId: Schema.String.annotate({
+      description: "Unique identifier for a session configuration option.",
+    }),
+    sessionId: Schema.String.annotate({
+      description:
+        "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+    }),
+  }).annotate({ description: "Request parameters for setting a session configuration option." }),
+  Schema.Struct({
+    value: Schema.String.annotate({
+      description: "Unique identifier for a session configuration option value.",
+    }),
+    _meta: Schema.optionalKey(
+      Schema.Union([
+        Schema.Record(Schema.String, Schema.Unknown).annotate({
+          description:
+            "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    configId: Schema.String.annotate({
+      description: "Unique identifier for a session configuration option.",
+    }),
+    sessionId: Schema.String.annotate({
+      description:
+        "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+    }),
+  }).annotate({
+    title: "value_id",
+    description: "Request parameters for setting a session configuration option.",
+  }),
+]);
+
+export type SetSessionConfigOptionResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly configOptions: ReadonlyArray<SessionConfigOption>;
+};
+export const SetSessionConfigOptionResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  configOptions: Schema.Array(SessionConfigOption).annotate({
+    description: "The full set of configuration options and their current values.",
+  }),
+}).annotate({ description: "Response to `session/set_config_option` method." });
+
+export type SetSessionModelRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly modelId: string;
+  readonly sessionId: string;
+};
+export const SetSessionModelRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  modelId: Schema.String.annotate({
+    description:
+      "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for a model.",
+  }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for setting a session model.",
+});
+
+export type SetSessionModelResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const SetSessionModelResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `session/set_model` method.",
+});
+
+export type SetSessionModeRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly modeId: string;
+  readonly sessionId: string;
+};
+export const SetSessionModeRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  modeId: Schema.String.annotate({ description: "Unique identifier for a Session Mode." }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({ description: "Request parameters for setting a session mode." });
+
+export type SetSessionModeResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const SetSessionModeResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Response to `session/set_mode` method." });
+
+export type StopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+export const StopReason = Schema.Literals([
+  "end_turn",
+  "max_tokens",
+  "max_turn_requests",
+  "refusal",
+  "cancelled",
+]).annotate({
+  description:
+    "Reasons why an agent stops processing a prompt turn.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons)",
+});
+
+export type StringPropertySchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly enum?: ReadonlyArray<string> | null;
+  readonly format?: StringFormat | null;
+  readonly maxLength?: number | null;
+  readonly minLength?: number | null;
+  readonly oneOf?: ReadonlyArray<EnumOption> | null;
+  readonly pattern?: string | null;
+  readonly title?: string | null;
+};
+export const StringPropertySchema = Schema.Struct({
+  default: Schema.optionalKey(
+    Schema.Union([Schema.String.annotate({ description: "Default value." }), Schema.Null]),
+  ),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Human-readable description." }),
+      Schema.Null,
+    ]),
+  ),
+  enum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description: "Enum values for untitled single-select enums.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  format: Schema.optionalKey(
+    Schema.Union([StringFormat, Schema.Null]).annotate({ description: "String format." }),
+  ),
+  maxLength: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Maximum string length.", format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  minLength: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ description: "Minimum string length.", format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  oneOf: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(EnumOption).annotate({
+        description: "Titled enum options for titled single-select enums.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  pattern: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Pattern the string must match." }),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional title for the property." }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  description:
+    'Schema for string properties in an elicitation form.\n\nWhen `enum` or `oneOf` is set, this represents a single-select enum\nwith `"type": "string"`.',
+});
+
+export type Terminal = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly terminalId: string;
+};
+export const Terminal = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  terminalId: Schema.String,
+}).annotate({
+  description:
+    "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)",
+});
+
+export type TerminalOutputRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly sessionId: string;
+  readonly terminalId: string;
+};
+export const TerminalOutputRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+  terminalId: Schema.String.annotate({ description: "The ID of the terminal to get output from." }),
+}).annotate({ description: "Request to get the current output and status of a terminal." });
+
+export type TerminalOutputResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly exitStatus?: TerminalExitStatus | null;
+  readonly output: string;
+  readonly truncated: boolean;
+};
+export const TerminalOutputResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  exitStatus: Schema.optionalKey(
+    Schema.Union([TerminalExitStatus, Schema.Null]).annotate({
+      description: "Exit status if the command has completed.",
+    }),
+  ),
+  output: Schema.String.annotate({ description: "The terminal output captured so far." }),
+  truncated: Schema.Boolean.annotate({
+    description: "Whether the output was truncated due to byte limits.",
+  }),
+}).annotate({ description: "Response containing the terminal output and exit status." });
+
+export type TextContent = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly annotations?: Annotations | null;
+  readonly text: string;
+};
+export const TextContent = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  annotations: Schema.optionalKey(Schema.Union([Annotations, Schema.Null])),
+  text: Schema.String,
+}).annotate({ description: "Text provided to or from an LLM." });
+
+export type TextResourceContents = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly mimeType?: string | null;
+  readonly text: string;
+  readonly uri: string;
+};
+export const TextResourceContents = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  text: Schema.String,
+  uri: Schema.String,
+}).annotate({ description: "Text-based resource contents." });
+
+export type TitledMultiSelectItems = { readonly anyOf: ReadonlyArray<EnumOption> };
+export const TitledMultiSelectItems = Schema.Struct({
+  anyOf: Schema.Array(EnumOption).annotate({ description: "Titled enum options." }),
+}).annotate({ description: "Items definition for titled multi-select enum properties." });
+
+export type ToolCall = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly content?: ReadonlyArray<ToolCallContent>;
+  readonly kind?:
+    | "read"
+    | "edit"
+    | "delete"
+    | "move"
+    | "search"
+    | "execute"
+    | "think"
+    | "fetch"
+    | "switch_mode"
+    | "other";
+  readonly locations?: ReadonlyArray<ToolCallLocation>;
+  readonly rawInput?: unknown;
+  readonly rawOutput?: unknown;
+  readonly status?: "pending" | "in_progress" | "completed" | "failed";
+  readonly title: string;
+  readonly toolCallId: string;
+};
+export const ToolCall = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  content: Schema.optionalKey(
+    Schema.Array(ToolCallContent).annotate({ description: "Content produced by the tool call." }),
+  ),
+  kind: Schema.optionalKey(
+    Schema.Literals([
+      "read",
+      "edit",
+      "delete",
+      "move",
+      "search",
+      "execute",
+      "think",
+      "fetch",
+      "switch_mode",
+      "other",
+    ]).annotate({
+      description:
+        "Categories of tools that can be invoked.\n\nTool kinds help clients choose appropriate icons and optimize how they\ndisplay tool execution progress.\n\nSee protocol docs: [Creating](https://agentclientprotocol.com/protocol/tool-calls#creating)",
+    }),
+  ),
+  locations: Schema.optionalKey(
+    Schema.Array(ToolCallLocation).annotate({
+      description:
+        'File locations affected by this tool call.\nEnables "follow-along" features in clients.',
+    }),
+  ),
+  rawInput: Schema.optionalKey(
+    Schema.Unknown.annotate({ description: "Raw input parameters sent to the tool." }),
+  ),
+  rawOutput: Schema.optionalKey(
+    Schema.Unknown.annotate({ description: "Raw output returned by the tool." }),
+  ),
+  status: Schema.optionalKey(
+    Schema.Literals(["pending", "in_progress", "completed", "failed"]).annotate({
+      description:
+        "Execution status of a tool call.\n\nTool calls progress through different statuses during their lifecycle.\n\nSee protocol docs: [Status](https://agentclientprotocol.com/protocol/tool-calls#status)",
+    }),
+  ),
+  title: Schema.String.annotate({
+    description: "Human-readable title describing what the tool is doing.",
+  }),
+  toolCallId: Schema.String.annotate({
+    description: "Unique identifier for a tool call within a session.",
+  }),
+}).annotate({
+  description:
+    "Represents a tool call that the language model has requested.\n\nTool calls are actions that the agent executes on behalf of the language model,\nsuch as reading files, executing code, or fetching data from external sources.\n\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/tool-calls)",
+});
+
+export type ToolCallId = string;
+export const ToolCallId = Schema.String.annotate({
+  description: "Unique identifier for a tool call within a session.",
+});
+
+export type ToolCallUpdate = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly content?: ReadonlyArray<ToolCallContent> | null;
+  readonly kind?: ToolKind | null;
+  readonly locations?: ReadonlyArray<ToolCallLocation> | null;
+  readonly rawInput?: unknown;
+  readonly rawOutput?: unknown;
+  readonly status?: ToolCallStatus | null;
+  readonly title?: string | null;
+  readonly toolCallId: string;
+};
+export const ToolCallUpdate = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  content: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ToolCallContent).annotate({ description: "Replace the content collection." }),
+      Schema.Null,
+    ]),
+  ),
+  kind: Schema.optionalKey(
+    Schema.Union([ToolKind, Schema.Null]).annotate({ description: "Update the tool kind." }),
+  ),
+  locations: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ToolCallLocation).annotate({ description: "Replace the locations collection." }),
+      Schema.Null,
+    ]),
+  ),
+  rawInput: Schema.optionalKey(Schema.Unknown.annotate({ description: "Update the raw input." })),
+  rawOutput: Schema.optionalKey(Schema.Unknown.annotate({ description: "Update the raw output." })),
+  status: Schema.optionalKey(
+    Schema.Union([ToolCallStatus, Schema.Null]).annotate({
+      description: "Update the execution status.",
+    }),
+  ),
+  title: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Update the human-readable title." }),
+      Schema.Null,
+    ]),
+  ),
+  toolCallId: Schema.String.annotate({
+    description: "Unique identifier for a tool call within a session.",
+  }),
+}).annotate({
+  description:
+    "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)",
+});
+
+export type UnstructuredCommandInput = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly hint: string;
+};
+export const UnstructuredCommandInput = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  hint: Schema.String.annotate({
+    description: "A hint to display when the input hasn't been provided yet",
+  }),
+}).annotate({
+  description: "All text that was typed after the command name is provided as input.",
+});
+
+export type UntitledMultiSelectItems = {
+  readonly enum: ReadonlyArray<string>;
+  readonly type: "string";
+};
+export const UntitledMultiSelectItems = Schema.Struct({
+  enum: Schema.Array(Schema.String).annotate({ description: "Allowed enum values." }),
+  type: Schema.Literal("string").annotate({
+    description: "Items definition for untitled multi-select enum properties.",
+  }),
+}).annotate({ description: "Items definition for untitled multi-select enum properties." });
+
+export type UsageUpdate = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly cost?: Cost | null;
+  readonly size: number;
+  readonly used: number;
+};
+export const UsageUpdate = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cost: Schema.optionalKey(
+    Schema.Union([Cost, Schema.Null]).annotate({
+      description: "Cumulative session cost (optional).",
+    }),
+  ),
+  size: Schema.Number.annotate({
+    description: "Total context window size in tokens.",
+    format: "uint64",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  used: Schema.Number.annotate({ description: "Tokens currently in context.", format: "uint64" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({
+  description:
+    "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for a session.",
+});
+
+export type WaitForTerminalExitRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly sessionId: string;
+  readonly terminalId: string;
+};
+export const WaitForTerminalExitRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+  terminalId: Schema.String.annotate({ description: "The ID of the terminal to wait for." }),
+}).annotate({ description: "Request to wait for a terminal command to exit." });
+
+export type WaitForTerminalExitResponse = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly exitCode?: number | null;
+  readonly signal?: string | null;
+};
+export const WaitForTerminalExitResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  exitCode: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "The process exit code (may be null if terminated by signal).",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  signal: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "The signal that terminated the process (may be null if exited normally).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Response containing the exit status of a terminal command." });
+
+export type WriteTextFileRequest = {
+  readonly _meta?: { readonly [x: string]: unknown } | null;
+  readonly content: string;
+  readonly path: string;
+  readonly sessionId: string;
+};
+export const WriteTextFileRequest = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  content: Schema.String.annotate({ description: "The text content to write to the file." }),
+  path: Schema.String.annotate({ description: "Absolute path to the file to write." }),
+  sessionId: Schema.String.annotate({
+    description:
+      "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session-setup#session-id)",
+  }),
+}).annotate({
+  description:
+    "Request to write content to a text file.\n\nOnly available if the client supports the `fs.writeTextFile` capability.",
+});
+
+export type WriteTextFileResponse = { readonly _meta?: { readonly [x: string]: unknown } | null };
+export const WriteTextFileResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Unknown).annotate({
+        description:
+          "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Response to `fs/write_text_file`" });
diff --git a/packages/effect-acp/src/_internal/shared.ts b/packages/effect-acp/src/_internal/shared.ts
new file mode 100644
index 00000000000..937d931c404
--- /dev/null
+++ b/packages/effect-acp/src/_internal/shared.ts
@@ -0,0 +1,113 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import { RpcClientError } from "effect/unstable/rpc";
+
+import * as AcpSchema from "../_generated/schema.gen.ts";
+import * as AcpError from "../errors.ts";
+const isError = Schema.is(AcpSchema.Error);
+const isAcpRequestError = Schema.is(AcpError.AcpRequestError);
+
+const formatSchemaIssue = SchemaIssue.makeFormatterDefault();
+
+export const callRpc = <A>(
+  effect: Effect.Effect<A, RpcClientError.RpcClientError | AcpSchema.Error>,
+): Effect.Effect<A, AcpError.AcpError> =>
+  effect.pipe(
+    Effect.catchTag("RpcClientError", (error) =>
+      Effect.fail(
+        new AcpError.AcpTransportError({
+          detail: error.message,
+          cause: error,
+        }),
+      ),
+    ),
+    Effect.catchIf(isError, (error) =>
+      Effect.fail(AcpError.AcpRequestError.fromProtocolError(error)),
+    ),
+  );
+
+export const runHandler = Effect.fnUntraced(function* <A, B>(
+  handler: ((payload: A) => Effect.Effect<B, AcpError.AcpError>) | undefined,
+  payload: A,
+  method: string,
+) {
+  if (!handler) {
+    return yield* Effect.fail(AcpError.AcpRequestError.methodNotFound(method).toProtocolError());
+  }
+  return yield* handler(payload).pipe(
+    Effect.mapError((error) =>
+      isAcpRequestError(error)
+        ? error.toProtocolError()
+        : AcpError.AcpRequestError.internalError(error.message).toProtocolError(),
+    ),
+  );
+});
+
+export function decodeExtRequestRegistration<A, I>(
+  method: string,
+  payload: Schema.Codec<A, I>,
+  handler: (payload: A) => Effect.Effect<unknown, AcpError.AcpError>,
+) {
+  return (params: unknown): Effect.Effect<unknown, AcpError.AcpError> =>
+    Schema.decodeUnknownEffect(payload)(params).pipe(
+      Effect.mapError((error) =>
+        AcpError.AcpRequestError.invalidParams(
+          `Invalid ${method} payload: ${formatSchemaIssue(error.issue)}`,
+          { issue: error.issue },
+        ),
+      ),
+      Effect.flatMap((decoded) => handler(decoded)),
+    );
+}
+
+export function decodeExtNotificationRegistration<A, I>(
+  method: string,
+  payload: Schema.Codec<A, I>,
+  handler: (payload: A) => Effect.Effect<void, AcpError.AcpError>,
+) {
+  return (params: unknown): Effect.Effect<void, AcpError.AcpError> =>
+    Schema.decodeUnknownEffect(payload)(params).pipe(
+      Effect.mapError(
+        (error) =>
+          new AcpError.AcpProtocolParseError({
+            detail: `Invalid ${method} notification payload: ${formatSchemaIssue(error.issue)}`,
+            cause: error,
+          }),
+      ),
+      Effect.flatMap((decoded) => handler(decoded)),
+    );
+}
+
+const encoder = new TextEncoder();
+
+const JsonRpcId = Schema.Union([Schema.Number, Schema.String]);
+const JsonRpcHeaders = Schema.Array(Schema.Unknown);
+
+export const jsonRpcRequest = <A, I>(method: string, params: Schema.Codec<A, I>) =>
+  Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: JsonRpcId,
+    method: Schema.Literal(method),
+    params,
+    headers: JsonRpcHeaders,
+  });
+
+export const jsonRpcNotification = <A, I>(method: string, params: Schema.Codec<A, I>) =>
+  Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    method: Schema.Literal(method),
+    params,
+  });
+
+export const jsonRpcResponse = <A, I>(result: Schema.Codec<A, I>) =>
+  Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: JsonRpcId,
+    result,
+  });
+
+export const encodeJsonl = <A, I>(schema: Schema.Codec<A, I>, value: A) =>
+  Effect.map(Schema.encodeEffect(Schema.fromJsonString(schema))(value), (encoded) =>
+    encoder.encode(`${encoded}\n`),
+  );
diff --git a/packages/effect-acp/src/_internal/stdio.ts b/packages/effect-acp/src/_internal/stdio.ts
new file mode 100644
index 00000000000..8ddb4d37d0f
--- /dev/null
+++ b/packages/effect-acp/src/_internal/stdio.ts
@@ -0,0 +1,57 @@
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Sink from "effect/Sink";
+import * as Stdio from "effect/Stdio";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as AcpError from "../errors.ts";
+
+const encoder = new TextEncoder();
+
+export const makeChildStdio = (handle: ChildProcessSpawner.ChildProcessHandle) =>
+  Stdio.make({
+    args: Effect.succeed([]),
+    stdin: handle.stdout,
+    stdout: () =>
+      Sink.mapInput(handle.stdin, (chunk: string | Uint8Array) =>
+        typeof chunk === "string" ? encoder.encode(chunk) : chunk,
+      ),
+    stderr: () => Sink.drain,
+  });
+
+export const makeInMemoryStdio = Effect.fn("makeInMemoryStdio")(function* () {
+  const input = yield* Queue.unbounded<Uint8Array, Cause.Done<void>>();
+  const output = yield* Queue.unbounded<string>();
+  const decoder = new TextDecoder();
+
+  return {
+    stdio: Stdio.make({
+      args: Effect.succeed([]),
+      stdin: Stream.fromQueue(input),
+      stdout: () =>
+        Sink.forEach((chunk: string | Uint8Array) =>
+          Queue.offer(
+            output,
+            typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }),
+          ),
+        ),
+      stderr: () => Sink.drain,
+    }),
+    input,
+    output,
+  };
+});
+
+export const makeTerminationError = (
+  handle: ChildProcessSpawner.ChildProcessHandle,
+): Effect.Effect<AcpError.AcpError> =>
+  Effect.match(handle.exitCode, {
+    onFailure: (cause) =>
+      new AcpError.AcpTransportError({
+        detail: "Failed to determine ACP process exit status",
+        cause,
+      }),
+    onSuccess: (code) => new AcpError.AcpProcessExitedError({ code }),
+  });
diff --git a/packages/effect-acp/src/agent.test.ts b/packages/effect-acp/src/agent.test.ts
new file mode 100644
index 00000000000..fac52398cf2
--- /dev/null
+++ b/packages/effect-acp/src/agent.test.ts
@@ -0,0 +1,255 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+
+import { assert, it } from "@effect/vitest";
+
+import * as AcpAgent from "./agent.ts";
+import * as AcpSchema from "./_generated/schema.gen.ts";
+import {
+  encodeJsonl,
+  jsonRpcNotification,
+  jsonRpcRequest,
+  jsonRpcResponse,
+} from "./_internal/shared.ts";
+import { makeInMemoryStdio } from "./_internal/stdio.ts";
+
+const RequestPermissionRequest = jsonRpcRequest(
+  "session/request_permission",
+  AcpSchema.RequestPermissionRequest,
+);
+const InitializeRequest = jsonRpcRequest("initialize", AcpSchema.InitializeRequest);
+const InitializeResponse = jsonRpcResponse(AcpSchema.InitializeResponse);
+const RequestPermissionResponse = jsonRpcResponse(AcpSchema.RequestPermissionResponse);
+const SessionCancelNotification = jsonRpcNotification(
+  "session/cancel",
+  AcpSchema.CancelNotification,
+);
+const ExtPingNotification = jsonRpcNotification("x/ping", Schema.Struct({ count: Schema.Number }));
+const ExtRequest = jsonRpcRequest("x/test", Schema.Struct({ hello: Schema.String }));
+const ExtResponse = jsonRpcResponse(Schema.Struct({ ok: Schema.Boolean }));
+const decodeRequestPermissionRequest = Schema.decodeEffect(
+  Schema.fromJsonString(RequestPermissionRequest),
+);
+const decodeInitializeResponse = Schema.decodeEffect(Schema.fromJsonString(InitializeResponse));
+
+it.effect("effect-acp agent handles core agent requests and outbound client requests", () =>
+  Effect.gen(function* () {
+    const { stdio, input, output } = yield* makeInMemoryStdio();
+    const cancelNotifications = yield* Ref.make<Array<string>>([]);
+    const extNotifications = yield* Ref.make<Array<number>>([]);
+    const cancelReceived = yield* Deferred.make<void>();
+    const extReceived = yield* Deferred.make<void>();
+    const scope = yield* Scope.make();
+    const context = yield* Layer.buildWithScope(AcpAgent.layer(stdio), scope);
+
+    yield* Effect.gen(function* () {
+      const agent = yield* AcpAgent.AcpAgent;
+
+      yield* agent.handleInitialize(() =>
+        Effect.succeed({
+          protocolVersion: 1,
+          agentCapabilities: {},
+          agentInfo: {
+            name: "mock-agent",
+            version: "0.0.0",
+          },
+        }),
+      );
+      yield* agent.handleCancel((notification) =>
+        Ref.update(cancelNotifications, (current) => [...current, notification.sessionId]).pipe(
+          Effect.andThen(Deferred.succeed(cancelReceived, undefined)),
+        ),
+      );
+      yield* agent.handleExtNotification(
+        "x/ping",
+        Schema.Struct({ count: Schema.Number }),
+        (payload) =>
+          Ref.update(extNotifications, (current) => [...current, payload.count]).pipe(
+            Effect.andThen(Deferred.succeed(extReceived, undefined)),
+          ),
+      );
+
+      const permissionFiber = yield* agent.client
+        .requestPermission({
+          sessionId: "session-1",
+          toolCall: {
+            toolCallId: "tool-1",
+            title: "Allow mock action",
+          },
+          options: [{ optionId: "allow", name: "Allow", kind: "allow_once" }],
+        })
+        .pipe(Effect.forkScoped);
+
+      const permissionRequest = yield* decodeRequestPermissionRequest(yield* Queue.take(output));
+      assert.equal(permissionRequest.jsonrpc, "2.0");
+      assert.equal(permissionRequest.method, "session/request_permission");
+      assert.deepEqual(permissionRequest.params, {
+        sessionId: "session-1",
+        toolCall: {
+          toolCallId: "tool-1",
+          title: "Allow mock action",
+        },
+        options: [{ optionId: "allow", name: "Allow", kind: "allow_once" }],
+      });
+      assert.deepEqual(permissionRequest.headers, []);
+
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(RequestPermissionResponse, {
+          jsonrpc: "2.0",
+          id: permissionRequest.id,
+          result: {
+            outcome: {
+              outcome: "selected",
+              optionId: "allow",
+            },
+          },
+        }),
+      );
+
+      const permission = yield* Fiber.join(permissionFiber);
+      assert.equal(permission.outcome.outcome, "selected");
+
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(InitializeRequest, {
+          jsonrpc: "2.0",
+          id: 2,
+          method: "initialize",
+          params: {
+            protocolVersion: 1,
+            clientCapabilities: {
+              fs: { readTextFile: false, writeTextFile: false },
+              terminal: false,
+            },
+            clientInfo: {
+              name: "effect-acp-test",
+              version: "0.0.0",
+            },
+          },
+          headers: [],
+        }),
+      );
+
+      const initResponse = yield* decodeInitializeResponse(yield* Queue.take(output));
+      assert.deepEqual(initResponse, {
+        jsonrpc: "2.0",
+        id: 2,
+        result: {
+          protocolVersion: 1,
+          agentCapabilities: {},
+          agentInfo: {
+            name: "mock-agent",
+            version: "0.0.0",
+          },
+        },
+      });
+
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(SessionCancelNotification, {
+          jsonrpc: "2.0",
+          method: "session/cancel",
+          params: {
+            sessionId: "session-1",
+          },
+        }),
+      );
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(ExtPingNotification, {
+          jsonrpc: "2.0",
+          method: "x/ping",
+          params: { count: 2 },
+        }),
+      );
+
+      yield* Deferred.await(cancelReceived);
+      yield* Deferred.await(extReceived);
+      assert.deepEqual(yield* Ref.get(cancelNotifications), ["session-1"]);
+      assert.deepEqual(yield* Ref.get(extNotifications), [2]);
+    }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+  }),
+);
+
+it.effect("effect-acp agent uses distinct ids for RPC calls and extension requests", () =>
+  Effect.gen(function* () {
+    const { stdio, input, output } = yield* makeInMemoryStdio();
+    const scope = yield* Scope.make();
+    const context = yield* Layer.buildWithScope(AcpAgent.layer(stdio), scope);
+
+    yield* Effect.gen(function* () {
+      const agent = yield* AcpAgent.AcpAgent;
+
+      const permissionFiber = yield* agent.client
+        .requestPermission({
+          sessionId: "session-1",
+          toolCall: {
+            toolCallId: "tool-1",
+            title: "Allow mock action",
+          },
+          options: [{ optionId: "allow", name: "Allow", kind: "allow_once" }],
+        })
+        .pipe(Effect.forkScoped);
+      const extFiber = yield* agent.client
+        .extRequest("x/test", { hello: "world" })
+        .pipe(Effect.forkScoped);
+
+      const firstOutbound = yield* Queue.take(output);
+      const secondOutbound = yield* Queue.take(output);
+
+      const decodedPermission = Schema.decodeEffect(
+        Schema.fromJsonString(RequestPermissionRequest),
+      );
+      const decodedExt = Schema.decodeEffect(Schema.fromJsonString(ExtRequest));
+      const firstIsPermission = yield* decodedPermission(firstOutbound).pipe(
+        Effect.match({
+          onFailure: () => false,
+          onSuccess: () => true,
+        }),
+      );
+
+      const permissionRequest = firstIsPermission
+        ? yield* decodedPermission(firstOutbound)
+        : yield* decodedPermission(secondOutbound);
+      const extRequest = firstIsPermission
+        ? yield* decodedExt(secondOutbound)
+        : yield* decodedExt(firstOutbound);
+
+      assert.notEqual(permissionRequest.id, extRequest.id);
+
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(RequestPermissionResponse, {
+          jsonrpc: "2.0",
+          id: permissionRequest.id,
+          result: {
+            outcome: {
+              outcome: "selected",
+              optionId: "allow",
+            },
+          },
+        }),
+      );
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(ExtResponse, {
+          jsonrpc: "2.0",
+          id: extRequest.id,
+          result: { ok: true },
+        }),
+      );
+
+      const permission = yield* Fiber.join(permissionFiber);
+      assert.equal(permission.outcome.outcome, "selected");
+      assert.deepEqual(yield* Fiber.join(extFiber), { ok: true });
+    }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+  }),
+);
diff --git a/packages/effect-acp/src/agent.ts b/packages/effect-acp/src/agent.ts
new file mode 100644
index 00000000000..0de2b49b843
--- /dev/null
+++ b/packages/effect-acp/src/agent.ts
@@ -0,0 +1,519 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as Stdio from "effect/Stdio";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as RpcServer from "effect/unstable/rpc/RpcServer";
+
+import * as AcpSchema from "./_generated/schema.gen.ts";
+import { AGENT_METHODS, CLIENT_METHODS } from "./_generated/meta.gen.ts";
+import * as AcpError from "./errors.ts";
+import * as AcpProtocol from "./protocol.ts";
+import * as AcpRpcs from "./rpc.ts";
+import {
+  callRpc,
+  decodeExtNotificationRegistration,
+  decodeExtRequestRegistration,
+  runHandler,
+} from "./_internal/shared.ts";
+import * as AcpTerminal from "./terminal.ts";
+
+export interface AcpAgentOptions {
+  readonly logIncoming?: boolean;
+  readonly logOutgoing?: boolean;
+  readonly logger?: (event: AcpProtocol.AcpProtocolLogEvent) => Effect.Effect<void, never>;
+}
+
+export interface AcpAgentShape {
+  readonly raw: {
+    /**
+     * Stream of inbound ACP notifications observed on the connection.
+     */
+    readonly notifications: Stream.Stream<AcpProtocol.AcpIncomingNotification>;
+    /**
+     * Sends a generic ACP extension request.
+     * @see https://agentclientprotocol.com/protocol/extensibility
+     */
+    readonly request: (
+      method: string,
+      payload: unknown,
+    ) => Effect.Effect<unknown, AcpError.AcpError>;
+    /**
+     * Sends a generic ACP extension notification.
+     * @see https://agentclientprotocol.com/protocol/extensibility
+     */
+    readonly notify: (method: string, payload: unknown) => Effect.Effect<void, AcpError.AcpError>;
+  };
+  readonly client: {
+    /**
+     * Requests client permission for an operation.
+     * @see https://agentclientprotocol.com/protocol/schema#session/request_permission
+     */
+    readonly requestPermission: (
+      payload: AcpSchema.RequestPermissionRequest,
+    ) => Effect.Effect<AcpSchema.RequestPermissionResponse, AcpError.AcpError>;
+    /**
+     * Requests structured user input from the client.
+     * @see https://agentclientprotocol.com/protocol/schema#session/elicitation
+     */
+    readonly elicit: (
+      payload: AcpSchema.ElicitationRequest,
+    ) => Effect.Effect<AcpSchema.ElicitationResponse, AcpError.AcpError>;
+    /**
+     * Requests file contents from the client.
+     * @see https://agentclientprotocol.com/protocol/schema#fs/read_text_file
+     */
+    readonly readTextFile: (
+      payload: AcpSchema.ReadTextFileRequest,
+    ) => Effect.Effect<AcpSchema.ReadTextFileResponse, AcpError.AcpError>;
+    /**
+     * Writes a text file through the client.
+     * @see https://agentclientprotocol.com/protocol/schema#fs/write_text_file
+     */
+    readonly writeTextFile: (
+      payload: AcpSchema.WriteTextFileRequest,
+    ) => Effect.Effect<AcpSchema.WriteTextFileResponse, AcpError.AcpError>;
+    /**
+     * Creates a terminal on the client side.
+     * @see https://agentclientprotocol.com/protocol/schema#terminal/create
+     */
+    readonly createTerminal: (
+      payload: AcpSchema.CreateTerminalRequest,
+    ) => Effect.Effect<AcpTerminal.AcpTerminal, AcpError.AcpError>;
+    /**
+     * Sends a `session/update` notification to the client.
+     * @see https://agentclientprotocol.com/protocol/schema#session/update
+     */
+    readonly sessionUpdate: (
+      payload: AcpSchema.SessionNotification,
+    ) => Effect.Effect<void, AcpError.AcpError>;
+    /**
+     * Sends a `session/elicitation/complete` notification to the client.
+     * @see https://agentclientprotocol.com/protocol/schema#session/elicitation/complete
+     */
+    readonly elicitationComplete: (
+      payload: AcpSchema.ElicitationCompleteNotification,
+    ) => Effect.Effect<void, AcpError.AcpError>;
+    /**
+     * Sends an ACP extension request to the client.
+     * @see https://agentclientprotocol.com/protocol/extensibility
+     */
+    readonly extRequest: (
+      method: string,
+      payload: unknown,
+    ) => Effect.Effect<unknown, AcpError.AcpError>;
+    /**
+     * Sends an ACP extension notification to the client.
+     * @see https://agentclientprotocol.com/protocol/extensibility
+     */
+    readonly extNotification: (
+      method: string,
+      payload: unknown,
+    ) => Effect.Effect<void, AcpError.AcpError>;
+  };
+  /**
+   * Registers a handler for `initialize`.
+   * @see https://agentclientprotocol.com/protocol/schema#initialize
+   */
+  readonly handleInitialize: (
+    handler: (
+      request: AcpSchema.InitializeRequest,
+    ) => Effect.Effect<AcpSchema.InitializeResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `authenticate`.
+   * @see https://agentclientprotocol.com/protocol/schema#authenticate
+   */
+  readonly handleAuthenticate: (
+    handler: (
+      request: AcpSchema.AuthenticateRequest,
+    ) => Effect.Effect<AcpSchema.AuthenticateResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleLogout: (
+    handler: (
+      request: AcpSchema.LogoutRequest,
+    ) => Effect.Effect<AcpSchema.LogoutResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleCreateSession: (
+    handler: (
+      request: AcpSchema.NewSessionRequest,
+    ) => Effect.Effect<AcpSchema.NewSessionResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleLoadSession: (
+    handler: (
+      request: AcpSchema.LoadSessionRequest,
+    ) => Effect.Effect<AcpSchema.LoadSessionResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleListSessions: (
+    handler: (
+      request: AcpSchema.ListSessionsRequest,
+    ) => Effect.Effect<AcpSchema.ListSessionsResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleForkSession: (
+    handler: (
+      request: AcpSchema.ForkSessionRequest,
+    ) => Effect.Effect<AcpSchema.ForkSessionResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleResumeSession: (
+    handler: (
+      request: AcpSchema.ResumeSessionRequest,
+    ) => Effect.Effect<AcpSchema.ResumeSessionResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleCloseSession: (
+    handler: (
+      request: AcpSchema.CloseSessionRequest,
+    ) => Effect.Effect<AcpSchema.CloseSessionResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleSetSessionModel: (
+    handler: (
+      request: AcpSchema.SetSessionModelRequest,
+    ) => Effect.Effect<AcpSchema.SetSessionModelResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleSetSessionConfigOption: (
+    handler: (
+      request: AcpSchema.SetSessionConfigOptionRequest,
+    ) => Effect.Effect<AcpSchema.SetSessionConfigOptionResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handlePrompt: (
+    handler: (
+      request: AcpSchema.PromptRequest,
+    ) => Effect.Effect<AcpSchema.PromptResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `session/cancel`.
+   * @see https://agentclientprotocol.com/protocol/schema#session/cancel
+   */
+  readonly handleCancel: (
+    handler: (notification: AcpSchema.CancelNotification) => Effect.Effect<void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleUnknownExtRequest: (
+    handler: (method: string, params: unknown) => Effect.Effect<unknown, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleUnknownExtNotification: (
+    handler: (method: string, params: unknown) => Effect.Effect<void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleExtRequest: <A, I>(
+    method: string,
+    payload: Schema.Codec<A, I>,
+    handler: (payload: A) => Effect.Effect<unknown, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  readonly handleExtNotification: <A, I>(
+    method: string,
+    payload: Schema.Codec<A, I>,
+    handler: (payload: A) => Effect.Effect<void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+}
+
+export class AcpAgent extends Context.Service<AcpAgent, AcpAgentShape>()("effect-acp/AcpAgent") {}
+
+interface AcpCoreAgentRequestHandlers {
+  initialize?: (
+    request: AcpSchema.InitializeRequest,
+  ) => Effect.Effect<AcpSchema.InitializeResponse, AcpError.AcpError>;
+  authenticate?: (
+    request: AcpSchema.AuthenticateRequest,
+  ) => Effect.Effect<AcpSchema.AuthenticateResponse, AcpError.AcpError>;
+  logout?: (
+    request: AcpSchema.LogoutRequest,
+  ) => Effect.Effect<AcpSchema.LogoutResponse, AcpError.AcpError>;
+  createSession?: (
+    request: AcpSchema.NewSessionRequest,
+  ) => Effect.Effect<AcpSchema.NewSessionResponse, AcpError.AcpError>;
+  loadSession?: (
+    request: AcpSchema.LoadSessionRequest,
+  ) => Effect.Effect<AcpSchema.LoadSessionResponse, AcpError.AcpError>;
+  listSessions?: (
+    request: AcpSchema.ListSessionsRequest,
+  ) => Effect.Effect<AcpSchema.ListSessionsResponse, AcpError.AcpError>;
+  forkSession?: (
+    request: AcpSchema.ForkSessionRequest,
+  ) => Effect.Effect<AcpSchema.ForkSessionResponse, AcpError.AcpError>;
+  resumeSession?: (
+    request: AcpSchema.ResumeSessionRequest,
+  ) => Effect.Effect<AcpSchema.ResumeSessionResponse, AcpError.AcpError>;
+  closeSession?: (
+    request: AcpSchema.CloseSessionRequest,
+  ) => Effect.Effect<AcpSchema.CloseSessionResponse, AcpError.AcpError>;
+  setSessionModel?: (
+    request: AcpSchema.SetSessionModelRequest,
+  ) => Effect.Effect<AcpSchema.SetSessionModelResponse, AcpError.AcpError>;
+  setSessionConfigOption?: (
+    request: AcpSchema.SetSessionConfigOptionRequest,
+  ) => Effect.Effect<AcpSchema.SetSessionConfigOptionResponse, AcpError.AcpError>;
+  prompt?: (
+    request: AcpSchema.PromptRequest,
+  ) => Effect.Effect<AcpSchema.PromptResponse, AcpError.AcpError>;
+}
+
+const decodeCancelNotification = Schema.decodeUnknownEffect(AcpSchema.CancelNotification);
+
+export const make = Effect.fn("effect-acp/AcpAgent.make")(function* (
+  stdio: Stdio.Stdio,
+  options: AcpAgentOptions = {},
+): Effect.fn.Return<AcpAgentShape, never, Scope.Scope> {
+  const coreHandlers: AcpCoreAgentRequestHandlers = {};
+  const cancelHandlers: Array<
+    (notification: AcpSchema.CancelNotification) => Effect.Effect<void, AcpError.AcpError>
+  > = [];
+  const extRequestHandlers = new Map<
+    string,
+    (params: unknown) => Effect.Effect<unknown, AcpError.AcpError>
+  >();
+  const extNotificationHandlers = new Map<
+    string,
+    (params: unknown) => Effect.Effect<void, AcpError.AcpError>
+  >();
+  let unknownExtRequestHandler:
+    | ((method: string, params: unknown) => Effect.Effect<unknown, AcpError.AcpError>)
+    | undefined;
+  let unknownExtNotificationHandler:
+    | ((method: string, params: unknown) => Effect.Effect<void, AcpError.AcpError>)
+    | undefined;
+
+  const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+    stdio,
+    serverRequestMethods: new Set(AcpRpcs.AgentRpcs.requests.keys()),
+    ...(options.logIncoming !== undefined ? { logIncoming: options.logIncoming } : {}),
+    ...(options.logOutgoing !== undefined ? { logOutgoing: options.logOutgoing } : {}),
+    ...(options.logger ? { logger: options.logger } : {}),
+    onNotification: (notification) => {
+      if (
+        notification._tag === "ExtNotification" &&
+        notification.method === AGENT_METHODS.session_cancel
+      ) {
+        return decodeCancelNotification(notification.params).pipe(
+          Effect.mapError(
+            (error) =>
+              new AcpError.AcpProtocolParseError({
+                detail: `Invalid ${AGENT_METHODS.session_cancel} notification payload`,
+                cause: error,
+              }),
+          ),
+          Effect.flatMap((decoded) =>
+            Effect.forEach(cancelHandlers, (handler) => handler(decoded), { discard: true }),
+          ),
+        );
+      }
+
+      if (notification._tag !== "ExtNotification") {
+        return Effect.void;
+      }
+
+      const handler = extNotificationHandlers.get(notification.method);
+      if (handler) {
+        return handler(notification.params);
+      }
+      return unknownExtNotificationHandler
+        ? unknownExtNotificationHandler(notification.method, notification.params)
+        : Effect.void;
+    },
+    onExtRequest: (method, params) => {
+      const handler = extRequestHandlers.get(method);
+      if (handler) {
+        return handler(params);
+      }
+      return unknownExtRequestHandler
+        ? unknownExtRequestHandler(method, params)
+        : Effect.fail(AcpError.AcpRequestError.methodNotFound(method));
+    },
+  });
+
+  const agentHandlerLayer = AcpRpcs.AgentRpcs.toLayer(
+    AcpRpcs.AgentRpcs.of({
+      [AGENT_METHODS.initialize]: (payload) =>
+        runHandler(coreHandlers.initialize, payload, AGENT_METHODS.initialize),
+      [AGENT_METHODS.authenticate]: (payload) =>
+        runHandler(coreHandlers.authenticate, payload, AGENT_METHODS.authenticate),
+      [AGENT_METHODS.logout]: (payload) =>
+        runHandler(coreHandlers.logout, payload, AGENT_METHODS.logout),
+      [AGENT_METHODS.session_new]: (payload) =>
+        runHandler(coreHandlers.createSession, payload, AGENT_METHODS.session_new),
+      [AGENT_METHODS.session_load]: (payload) =>
+        runHandler(coreHandlers.loadSession, payload, AGENT_METHODS.session_load),
+      [AGENT_METHODS.session_list]: (payload) =>
+        runHandler(coreHandlers.listSessions, payload, AGENT_METHODS.session_list),
+      [AGENT_METHODS.session_fork]: (payload) =>
+        runHandler(coreHandlers.forkSession, payload, AGENT_METHODS.session_fork),
+      [AGENT_METHODS.session_resume]: (payload) =>
+        runHandler(coreHandlers.resumeSession, payload, AGENT_METHODS.session_resume),
+      [AGENT_METHODS.session_close]: (payload) =>
+        runHandler(coreHandlers.closeSession, payload, AGENT_METHODS.session_close),
+      [AGENT_METHODS.session_set_model]: (payload) =>
+        runHandler(coreHandlers.setSessionModel, payload, AGENT_METHODS.session_set_model),
+      [AGENT_METHODS.session_set_config_option]: (payload) =>
+        runHandler(
+          coreHandlers.setSessionConfigOption,
+          payload,
+          AGENT_METHODS.session_set_config_option,
+        ),
+      [AGENT_METHODS.session_prompt]: (payload) =>
+        runHandler(coreHandlers.prompt, payload, AGENT_METHODS.session_prompt),
+    }),
+  );
+
+  yield* RpcServer.make(AcpRpcs.AgentRpcs).pipe(
+    Effect.provideService(RpcServer.Protocol, transport.serverProtocol),
+    Effect.provide(agentHandlerLayer),
+    Effect.forkScoped,
+  );
+
+  let nextRpcRequestId = 1n << 32n;
+  const rpc = yield* RpcClient.make(AcpRpcs.ClientRpcs, {
+    generateRequestId: () => nextRpcRequestId++ as never,
+  }).pipe(Effect.provideService(RpcClient.Protocol, transport.clientProtocol));
+
+  return AcpAgent.of({
+    raw: {
+      notifications: transport.incoming,
+      request: transport.request,
+      notify: transport.notify,
+    },
+    client: {
+      requestPermission: (payload) =>
+        callRpc(rpc[CLIENT_METHODS.session_request_permission](payload)),
+      elicit: (payload) => callRpc(rpc[CLIENT_METHODS.session_elicitation](payload)),
+      readTextFile: (payload) => callRpc(rpc[CLIENT_METHODS.fs_read_text_file](payload)),
+      writeTextFile: (payload) => callRpc(rpc[CLIENT_METHODS.fs_write_text_file](payload)),
+      createTerminal: (payload) =>
+        callRpc(rpc[CLIENT_METHODS.terminal_create](payload)).pipe(
+          Effect.map((response) =>
+            AcpTerminal.makeTerminal({
+              sessionId: payload.sessionId,
+              terminalId: response.terminalId,
+              output: callRpc(
+                rpc[CLIENT_METHODS.terminal_output]({
+                  sessionId: payload.sessionId,
+                  terminalId: response.terminalId,
+                }),
+              ),
+              waitForExit: callRpc(
+                rpc[CLIENT_METHODS.terminal_wait_for_exit]({
+                  sessionId: payload.sessionId,
+                  terminalId: response.terminalId,
+                }),
+              ),
+              kill: callRpc(
+                rpc[CLIENT_METHODS.terminal_kill]({
+                  sessionId: payload.sessionId,
+                  terminalId: response.terminalId,
+                }),
+              ),
+              release: callRpc(
+                rpc[CLIENT_METHODS.terminal_release]({
+                  sessionId: payload.sessionId,
+                  terminalId: response.terminalId,
+                }),
+              ),
+            }),
+          ),
+        ),
+      sessionUpdate: (payload) => transport.notify(CLIENT_METHODS.session_update, payload),
+      elicitationComplete: (payload) =>
+        transport.notify(CLIENT_METHODS.session_elicitation_complete, payload),
+      extRequest: transport.request,
+      extNotification: transport.notify,
+    },
+    handleInitialize: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.initialize = handler;
+        return Effect.void;
+      }),
+    handleAuthenticate: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.authenticate = handler;
+        return Effect.void;
+      }),
+    handleLogout: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.logout = handler;
+        return Effect.void;
+      }),
+    handleCreateSession: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.createSession = handler;
+        return Effect.void;
+      }),
+    handleLoadSession: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.loadSession = handler;
+        return Effect.void;
+      }),
+    handleListSessions: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.listSessions = handler;
+        return Effect.void;
+      }),
+    handleForkSession: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.forkSession = handler;
+        return Effect.void;
+      }),
+    handleResumeSession: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.resumeSession = handler;
+        return Effect.void;
+      }),
+    handleCloseSession: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.closeSession = handler;
+        return Effect.void;
+      }),
+    handleSetSessionModel: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.setSessionModel = handler;
+        return Effect.void;
+      }),
+    handleSetSessionConfigOption: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.setSessionConfigOption = handler;
+        return Effect.void;
+      }),
+    handlePrompt: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.prompt = handler;
+        return Effect.void;
+      }),
+    handleCancel: (handler) =>
+      Effect.suspend(() => {
+        cancelHandlers.push(handler);
+        return Effect.void;
+      }),
+    handleUnknownExtRequest: (handler) =>
+      Effect.suspend(() => {
+        unknownExtRequestHandler = handler;
+        return Effect.void;
+      }),
+    handleUnknownExtNotification: (handler) =>
+      Effect.suspend(() => {
+        unknownExtNotificationHandler = handler;
+        return Effect.void;
+      }),
+    handleExtRequest: (method, payload, handler) =>
+      Effect.suspend(() => {
+        extRequestHandlers.set(method, decodeExtRequestRegistration(method, payload, handler));
+        return Effect.void;
+      }),
+    handleExtNotification: (method, payload, handler) =>
+      Effect.suspend(() => {
+        extNotificationHandlers.set(
+          method,
+          decodeExtNotificationRegistration(method, payload, handler),
+        );
+        return Effect.void;
+      }),
+  });
+});
+
+export const layer = (stdio: Stdio.Stdio, options: AcpAgentOptions = {}): Layer.Layer<AcpAgent> =>
+  Layer.effect(AcpAgent, make(stdio, options));
+
+export const layerStdio = (
+  options: AcpAgentOptions = {},
+): Layer.Layer<AcpAgent, never, Stdio.Stdio> =>
+  Layer.effect(
+    AcpAgent,
+    Effect.flatMap(Effect.service(Stdio.Stdio), (stdio) => make(stdio, options)),
+  );
diff --git a/packages/effect-acp/src/client.test.ts b/packages/effect-acp/src/client.test.ts
new file mode 100644
index 00000000000..5c9a6f8336f
--- /dev/null
+++ b/packages/effect-acp/src/client.test.ts
@@ -0,0 +1,449 @@
+import * as Path from "effect/Path";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it, assert } from "@effect/vitest";
+
+import * as AcpClient from "./client.ts";
+import * as AcpSchema from "./_generated/schema.gen.ts";
+import * as AcpError from "./errors.ts";
+import { encodeJsonl, jsonRpcRequest, jsonRpcResponse } from "./_internal/shared.ts";
+import { makeInMemoryStdio } from "./_internal/stdio.ts";
+
+const InitializeRequest = jsonRpcRequest("initialize", AcpSchema.InitializeRequest);
+const InitializeResponse = jsonRpcResponse(AcpSchema.InitializeResponse);
+const ExtRequest = jsonRpcRequest("x/test", Schema.Struct({ hello: Schema.String }));
+const ExtResponse = jsonRpcResponse(Schema.Struct({ ok: Schema.Boolean }));
+const mockPeerPath = Effect.map(Effect.service(Path.Path), (path) =>
+  path.join(import.meta.dirname, "../test/fixtures/acp-mock-peer.ts"),
+);
+
+it.layer(NodeServices.layer)("effect-acp client", (it) => {
+  const makeHandle = (env?: Record<string, string>) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const path = yield* Path.Path;
+      const command = ChildProcess.make("bun", ["run", yield* mockPeerPath], {
+        cwd: path.join(import.meta.dirname, ".."),
+        shell: process.platform === "win32",
+        ...(env ? { env: { ...process.env, ...env } } : {}),
+      });
+      return yield* spawner.spawn(command);
+    });
+
+  it.effect("initializes, prompts, receives updates, and handles permission requests", () =>
+    Effect.gen(function* () {
+      const updates = yield* Ref.make<Array<unknown>>([]);
+      const elicitationCompletions = yield* Ref.make<Array<unknown>>([]);
+      const typedRequests = yield* Ref.make<Array<unknown>>([]);
+      const typedNotifications = yield* Ref.make<Array<unknown>>([]);
+      const handle = yield* makeHandle();
+      const scope = yield* Scope.make();
+      const acpLayer = AcpClient.layerChildProcess(handle);
+      const context = yield* Layer.buildWithScope(acpLayer, scope);
+
+      const ext = yield* Effect.gen(function* () {
+        const acp = yield* AcpClient.AcpClient;
+
+        yield* acp.handleRequestPermission(() =>
+          Effect.succeed({
+            outcome: {
+              outcome: "selected",
+              optionId: "allow",
+            },
+          }),
+        );
+        yield* acp.handleElicitation(() =>
+          Effect.succeed({
+            action: {
+              action: "accept",
+              content: {
+                approved: true,
+              },
+            },
+          }),
+        );
+        yield* acp.handleSessionUpdate((notification) =>
+          Ref.update(updates, (current) => [...current, notification]),
+        );
+        yield* acp.handleElicitationComplete((notification) =>
+          Ref.update(elicitationCompletions, (current) => [...current, notification]),
+        );
+        yield* acp.handleExtRequest(
+          "x/typed_request",
+          Schema.Struct({ message: Schema.String }),
+          (payload) =>
+            Ref.update(typedRequests, (current) => [...current, payload]).pipe(
+              Effect.as({
+                ok: true,
+                echoedMessage: payload.message,
+              }),
+            ),
+        );
+        yield* acp.handleExtNotification(
+          "x/typed_notification",
+          Schema.Struct({ count: Schema.Number }),
+          (payload) => Ref.update(typedNotifications, (current) => [...current, payload]),
+        );
+
+        const init = yield* acp.agent.initialize({
+          protocolVersion: 1,
+          clientCapabilities: {
+            fs: { readTextFile: false, writeTextFile: false },
+            terminal: false,
+          },
+          clientInfo: {
+            name: "effect-acp-test",
+            version: "0.0.0",
+          },
+        });
+        assert.equal(init.protocolVersion, 1);
+
+        yield* acp.agent.authenticate({ methodId: "cursor_login" });
+
+        const session = yield* acp.agent.createSession({
+          cwd: process.cwd(),
+          mcpServers: [],
+        });
+        assert.equal(session.sessionId, "mock-session-1");
+
+        const prompt = yield* acp.agent.prompt({
+          sessionId: session.sessionId,
+          prompt: [{ type: "text", text: "hello" }],
+        });
+        assert.equal(prompt.stopReason, "end_turn");
+
+        const streamed = yield* Stream.runCollect(Stream.take(acp.raw.notifications, 2));
+        assert.equal(streamed.length, 2);
+        assert.equal(streamed[0]?._tag, "SessionUpdate");
+        assert.equal(streamed[1]?._tag, "ElicitationComplete");
+        assert.equal((yield* Ref.get(updates)).length, 1);
+        assert.equal((yield* Ref.get(elicitationCompletions)).length, 1);
+        assert.deepEqual(yield* Ref.get(typedRequests), [{ message: "hello from typed request" }]);
+        assert.deepEqual(yield* Ref.get(typedNotifications), [{ count: 2 }]);
+
+        return yield* acp.raw.request("x/echo", {
+          hello: "world",
+        });
+      }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+
+      assert.deepEqual(ext, {
+        echoedMethod: "x/echo",
+        echoedParams: {
+          hello: "world",
+        },
+      });
+    }),
+  );
+
+  it.effect(
+    "returns formatted invalid params when a typed extension request payload is wrong",
+    () =>
+      Effect.gen(function* () {
+        const handle = yield* makeHandle({ ACP_MOCK_BAD_TYPED_REQUEST: "1" });
+        const scope = yield* Scope.make();
+        const acpLayer = AcpClient.layerChildProcess(handle);
+        const context = yield* Layer.buildWithScope(acpLayer, scope);
+
+        const result = yield* Effect.gen(function* () {
+          const acp = yield* AcpClient.AcpClient;
+
+          yield* acp.handleRequestPermission(() =>
+            Effect.succeed({
+              outcome: {
+                outcome: "selected",
+                optionId: "allow",
+              },
+            }),
+          );
+          yield* acp.handleElicitation(() =>
+            Effect.succeed({
+              action: {
+                action: "accept",
+                content: {
+                  approved: true,
+                },
+              },
+            }),
+          );
+          yield* acp.handleExtRequest(
+            "x/typed_request",
+            Schema.Struct({ message: Schema.String }),
+            () => Effect.succeed({ ok: true }),
+          );
+
+          yield* acp.agent.initialize({
+            protocolVersion: 1,
+            clientCapabilities: {
+              fs: { readTextFile: false, writeTextFile: false },
+              terminal: false,
+            },
+            clientInfo: {
+              name: "effect-acp-test",
+              version: "0.0.0",
+            },
+          });
+
+          yield* acp.agent.authenticate({ methodId: "cursor_login" });
+
+          const session = yield* acp.agent.createSession({
+            cwd: process.cwd(),
+            mcpServers: [],
+          });
+
+          return yield* Effect.exit(
+            acp.agent.prompt({
+              sessionId: session.sessionId,
+              prompt: [{ type: "text", text: "hello" }],
+            }),
+          );
+        }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+
+        if (result._tag !== "Failure") {
+          assert.fail("Expected prompt to fail for invalid typed extension payload");
+        }
+        const rendered = Cause.pretty(result.cause);
+        assert.include(rendered, "Invalid x/typed_request payload:");
+        assert.include(rendered, "Expected string, got 123");
+      }),
+  );
+
+  it.effect("replays buffered notifications to handlers registered after they arrive", () =>
+    Effect.gen(function* () {
+      const updates = yield* Ref.make<Array<unknown>>([]);
+      const elicitationCompletions = yield* Ref.make<Array<unknown>>([]);
+      const typedRequests = yield* Ref.make<Array<unknown>>([]);
+      const typedNotifications = yield* Ref.make<Array<unknown>>([]);
+      const handle = yield* makeHandle();
+      const scope = yield* Scope.make();
+      const acpLayer = AcpClient.layerChildProcess(handle);
+      const context = yield* Layer.buildWithScope(acpLayer, scope);
+
+      yield* Effect.gen(function* () {
+        const acp = yield* AcpClient.AcpClient;
+
+        yield* acp.handleRequestPermission(() =>
+          Effect.succeed({
+            outcome: {
+              outcome: "selected",
+              optionId: "allow",
+            },
+          }),
+        );
+        yield* acp.handleElicitation(() =>
+          Effect.succeed({
+            action: {
+              action: "accept",
+              content: {
+                approved: true,
+              },
+            },
+          }),
+        );
+        yield* acp.handleExtRequest(
+          "x/typed_request",
+          Schema.Struct({ message: Schema.String }),
+          (payload) =>
+            Ref.update(typedRequests, (current) => [...current, payload]).pipe(
+              Effect.as({
+                ok: true,
+                echoedMessage: payload.message,
+              }),
+            ),
+        );
+        yield* acp.handleExtNotification(
+          "x/typed_notification",
+          Schema.Struct({ count: Schema.Number }),
+          (payload) => Ref.update(typedNotifications, (current) => [...current, payload]),
+        );
+
+        yield* acp.agent.initialize({
+          protocolVersion: 1,
+          clientCapabilities: {
+            fs: { readTextFile: false, writeTextFile: false },
+            terminal: false,
+          },
+          clientInfo: {
+            name: "effect-acp-test",
+            version: "0.0.0",
+          },
+        });
+        yield* acp.agent.authenticate({ methodId: "cursor_login" });
+
+        const session = yield* acp.agent.createSession({
+          cwd: process.cwd(),
+          mcpServers: [],
+        });
+        yield* acp.agent.prompt({
+          sessionId: session.sessionId,
+          prompt: [{ type: "text", text: "hello" }],
+        });
+
+        yield* acp.handleSessionUpdate((notification) =>
+          Ref.update(updates, (current) => [...current, notification]),
+        );
+        yield* acp.handleElicitationComplete((notification) =>
+          Ref.update(elicitationCompletions, (current) => [...current, notification]),
+        );
+
+        assert.equal((yield* Ref.get(updates)).length, 1);
+        assert.equal((yield* Ref.get(elicitationCompletions)).length, 1);
+        assert.deepEqual(yield* Ref.get(typedRequests), [{ message: "hello from typed request" }]);
+        assert.deepEqual(yield* Ref.get(typedNotifications), [{ count: 2 }]);
+      }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+    }),
+  );
+
+  it.effect("continues dispatching session updates after one handler fails", () =>
+    Effect.gen(function* () {
+      const successfulHandlers = yield* Ref.make(0);
+      const handle = yield* makeHandle();
+      const scope = yield* Scope.make();
+      const acpLayer = AcpClient.layerChildProcess(handle);
+      const context = yield* Layer.buildWithScope(acpLayer, scope);
+
+      yield* Effect.gen(function* () {
+        const acp = yield* AcpClient.AcpClient;
+
+        yield* acp.handleRequestPermission(() =>
+          Effect.succeed({
+            outcome: {
+              outcome: "selected",
+              optionId: "allow",
+            },
+          }),
+        );
+        yield* acp.handleElicitation(() =>
+          Effect.succeed({
+            action: {
+              action: "accept",
+              content: {
+                approved: true,
+              },
+            },
+          }),
+        );
+        yield* acp.handleExtRequest(
+          "x/typed_request",
+          Schema.Struct({ message: Schema.String }),
+          () => Effect.succeed({ ok: true }),
+        );
+        yield* acp.handleExtNotification(
+          "x/typed_notification",
+          Schema.Struct({ count: Schema.Number }),
+          () => Effect.void,
+        );
+        yield* acp.handleSessionUpdate(() =>
+          Effect.fail(AcpError.AcpRequestError.internalError("session update handler failed")),
+        );
+        yield* acp.handleSessionUpdate(() => Ref.update(successfulHandlers, (count) => count + 1));
+
+        yield* acp.agent.initialize({
+          protocolVersion: 1,
+          clientCapabilities: {
+            fs: { readTextFile: false, writeTextFile: false },
+            terminal: false,
+          },
+          clientInfo: {
+            name: "effect-acp-test",
+            version: "0.0.0",
+          },
+        });
+        yield* acp.agent.authenticate({ methodId: "cursor_login" });
+
+        const session = yield* acp.agent.createSession({
+          cwd: process.cwd(),
+          mcpServers: [],
+        });
+        yield* acp.agent.prompt({
+          sessionId: session.sessionId,
+          prompt: [{ type: "text", text: "hello" }],
+        });
+
+        assert.equal(yield* Ref.get(successfulHandlers), 1);
+      }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+    }),
+  );
+
+  it.effect("uses distinct ids for RPC calls and extension requests", () =>
+    Effect.gen(function* () {
+      const { stdio, input, output } = yield* makeInMemoryStdio();
+      const scope = yield* Scope.make();
+      const acp = yield* AcpClient.make(stdio).pipe(Effect.provideService(Scope.Scope, scope));
+
+      const initializeFiber = yield* acp.agent
+        .initialize({
+          protocolVersion: 1,
+          clientCapabilities: {
+            fs: { readTextFile: false, writeTextFile: false },
+            terminal: false,
+          },
+          clientInfo: {
+            name: "effect-acp-test",
+            version: "0.0.0",
+          },
+        })
+        .pipe(Effect.forkScoped);
+      const extFiber = yield* acp.raw.request("x/test", { hello: "world" }).pipe(Effect.forkScoped);
+
+      const firstOutbound = yield* Queue.take(output);
+      const secondOutbound = yield* Queue.take(output);
+
+      const decodedInitialize = Schema.decodeEffect(Schema.fromJsonString(InitializeRequest));
+      const decodedExt = Schema.decodeEffect(Schema.fromJsonString(ExtRequest));
+      const firstIsInitialize = yield* decodedInitialize(firstOutbound).pipe(
+        Effect.match({
+          onFailure: () => false,
+          onSuccess: () => true,
+        }),
+      );
+
+      const initializeRequest = firstIsInitialize
+        ? yield* decodedInitialize(firstOutbound)
+        : yield* decodedInitialize(secondOutbound);
+      const extRequest = firstIsInitialize
+        ? yield* decodedExt(secondOutbound)
+        : yield* decodedExt(firstOutbound);
+
+      assert.notEqual(initializeRequest.id, extRequest.id);
+
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(InitializeResponse, {
+          jsonrpc: "2.0",
+          id: initializeRequest.id,
+          result: {
+            protocolVersion: 1,
+            agentCapabilities: {},
+            agentInfo: {
+              name: "mock-agent",
+              version: "0.0.0",
+            },
+          },
+        }),
+      );
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(ExtResponse, {
+          jsonrpc: "2.0",
+          id: extRequest.id,
+          result: { ok: true },
+        }),
+      );
+
+      yield* Fiber.join(initializeFiber);
+      assert.deepEqual(yield* Fiber.join(extFiber), { ok: true });
+      yield* Scope.close(scope, Exit.void);
+    }),
+  );
+});
diff --git a/packages/effect-acp/src/client.ts b/packages/effect-acp/src/client.ts
new file mode 100644
index 00000000000..3052726edef
--- /dev/null
+++ b/packages/effect-acp/src/client.ts
@@ -0,0 +1,569 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Stdio from "effect/Stdio";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as RpcServer from "effect/unstable/rpc/RpcServer";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as AcpError from "./errors.ts";
+import * as AcpProtocol from "./protocol.ts";
+import * as AcpRpcs from "./rpc.ts";
+import * as AcpSchema from "./_generated/schema.gen.ts";
+import { AGENT_METHODS, CLIENT_METHODS } from "./_generated/meta.gen.ts";
+import {
+  callRpc,
+  decodeExtNotificationRegistration,
+  decodeExtRequestRegistration,
+  runHandler,
+} from "./_internal/shared.ts";
+import { makeChildStdio, makeTerminationError } from "./_internal/stdio.ts";
+
+export interface AcpClientOptions {
+  readonly logIncoming?: boolean;
+  readonly logOutgoing?: boolean;
+  readonly logger?: (event: AcpProtocol.AcpProtocolLogEvent) => Effect.Effect<void, never>;
+}
+
+type AcpClientRaw = {
+  readonly notifications: Stream.Stream<AcpProtocol.AcpIncomingNotification>;
+  readonly request: (method: string, payload: unknown) => Effect.Effect<unknown, AcpError.AcpError>;
+  readonly notify: (method: string, payload: unknown) => Effect.Effect<void, AcpError.AcpError>;
+};
+
+export interface AcpClientShape {
+  readonly raw: AcpClientRaw;
+  readonly agent: {
+    /**
+     * Initializes the ACP session and negotiates capabilities.
+     * @see https://agentclientprotocol.com/protocol/schema#initialize
+     */
+    readonly initialize: (
+      payload: AcpSchema.InitializeRequest,
+    ) => Effect.Effect<AcpSchema.InitializeResponse, AcpError.AcpError>;
+    /**
+     * Performs ACP authentication when the agent requires it.
+     * @see https://agentclientprotocol.com/protocol/schema#authenticate
+     */
+    readonly authenticate: (
+      payload: AcpSchema.AuthenticateRequest,
+    ) => Effect.Effect<AcpSchema.AuthenticateResponse, AcpError.AcpError>;
+    /**
+     * Logs out the current ACP identity.
+     * @see https://agentclientprotocol.com/protocol/schema#logout
+     */
+    readonly logout: (
+      payload: AcpSchema.LogoutRequest,
+    ) => Effect.Effect<AcpSchema.LogoutResponse, AcpError.AcpError>;
+    /**
+     * Starts a new ACP session.
+     * @see https://agentclientprotocol.com/protocol/schema#session/new
+     */
+    readonly createSession: (
+      payload: AcpSchema.NewSessionRequest,
+    ) => Effect.Effect<AcpSchema.NewSessionResponse, AcpError.AcpError>;
+    /**
+     * Loads a previously saved ACP session.
+     * @see https://agentclientprotocol.com/protocol/schema#session/load
+     */
+    readonly loadSession: (
+      payload: AcpSchema.LoadSessionRequest,
+    ) => Effect.Effect<AcpSchema.LoadSessionResponse, AcpError.AcpError>;
+    /**
+     * Lists available ACP sessions.
+     * @see https://agentclientprotocol.com/protocol/schema#session/list
+     */
+    readonly listSessions: (
+      payload: AcpSchema.ListSessionsRequest,
+    ) => Effect.Effect<AcpSchema.ListSessionsResponse, AcpError.AcpError>;
+    /**
+     * Forks an ACP session.
+     * @see https://agentclientprotocol.com/protocol/schema#session/fork
+     */
+    readonly forkSession: (
+      payload: AcpSchema.ForkSessionRequest,
+    ) => Effect.Effect<AcpSchema.ForkSessionResponse, AcpError.AcpError>;
+    /**
+     * Resumes an ACP session.
+     * @see https://agentclientprotocol.com/protocol/schema#session/resume
+     */
+    readonly resumeSession: (
+      payload: AcpSchema.ResumeSessionRequest,
+    ) => Effect.Effect<AcpSchema.ResumeSessionResponse, AcpError.AcpError>;
+    /**
+     * Closes an ACP session.
+     * @see https://agentclientprotocol.com/protocol/schema#session/close
+     */
+    readonly closeSession: (
+      payload: AcpSchema.CloseSessionRequest,
+    ) => Effect.Effect<AcpSchema.CloseSessionResponse, AcpError.AcpError>;
+    /**
+     * Selects the active model for a session.
+     * @see https://agentclientprotocol.com/protocol/schema#session/set_model
+     */
+    readonly setSessionModel: (
+      payload: AcpSchema.SetSessionModelRequest,
+    ) => Effect.Effect<AcpSchema.SetSessionModelResponse, AcpError.AcpError>;
+    /**
+     * Updates a session configuration option.
+     * @see https://agentclientprotocol.com/protocol/schema#session/set_config_option
+     */
+    readonly setSessionConfigOption: (
+      payload: AcpSchema.SetSessionConfigOptionRequest,
+    ) => Effect.Effect<AcpSchema.SetSessionConfigOptionResponse, AcpError.AcpError>;
+    /**
+     * Sends a prompt turn to the agent.
+     * @see https://agentclientprotocol.com/protocol/schema#session/prompt
+     */
+    readonly prompt: (
+      payload: AcpSchema.PromptRequest,
+    ) => Effect.Effect<AcpSchema.PromptResponse, AcpError.AcpError>;
+    /**
+     * Sends a real ACP `session/cancel` notification.
+     * @see https://agentclientprotocol.com/protocol/schema#session/cancel
+     */
+    readonly cancel: (
+      payload: AcpSchema.CancelNotification,
+    ) => Effect.Effect<void, AcpError.AcpError>;
+  };
+  /**
+   * Registers a handler for `session/request_permission`.
+   * @see https://agentclientprotocol.com/protocol/schema#session/request_permission
+   */
+  readonly handleRequestPermission: (
+    handler: (
+      request: AcpSchema.RequestPermissionRequest,
+    ) => Effect.Effect<AcpSchema.RequestPermissionResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `session/elicitation`.
+   * @see https://agentclientprotocol.com/protocol/schema#session/elicitation
+   */
+  readonly handleElicitation: (
+    handler: (
+      request: AcpSchema.ElicitationRequest,
+    ) => Effect.Effect<AcpSchema.ElicitationResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `fs/read_text_file`.
+   * @see https://agentclientprotocol.com/protocol/schema#fs/read_text_file
+   */
+  readonly handleReadTextFile: (
+    handler: (
+      request: AcpSchema.ReadTextFileRequest,
+    ) => Effect.Effect<AcpSchema.ReadTextFileResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `fs/write_text_file`.
+   * @see https://agentclientprotocol.com/protocol/schema#fs/write_text_file
+   */
+  readonly handleWriteTextFile: (
+    handler: (
+      request: AcpSchema.WriteTextFileRequest,
+    ) => Effect.Effect<AcpSchema.WriteTextFileResponse | void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `terminal/create`.
+   * @see https://agentclientprotocol.com/protocol/schema#terminal/create
+   */
+  readonly handleCreateTerminal: (
+    handler: (
+      request: AcpSchema.CreateTerminalRequest,
+    ) => Effect.Effect<AcpSchema.CreateTerminalResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `terminal/output`.
+   * @see https://agentclientprotocol.com/protocol/schema#terminal/output
+   */
+  readonly handleTerminalOutput: (
+    handler: (
+      request: AcpSchema.TerminalOutputRequest,
+    ) => Effect.Effect<AcpSchema.TerminalOutputResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `terminal/wait_for_exit`.
+   * @see https://agentclientprotocol.com/protocol/schema#terminal/wait_for_exit
+   */
+  readonly handleTerminalWaitForExit: (
+    handler: (
+      request: AcpSchema.WaitForTerminalExitRequest,
+    ) => Effect.Effect<AcpSchema.WaitForTerminalExitResponse, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `terminal/kill`.
+   * @see https://agentclientprotocol.com/protocol/schema#terminal/kill
+   */
+  readonly handleTerminalKill: (
+    handler: (
+      request: AcpSchema.KillTerminalRequest,
+    ) => Effect.Effect<AcpSchema.KillTerminalResponse | void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `terminal/release`.
+   * @see https://agentclientprotocol.com/protocol/schema#terminal/release
+   */
+  readonly handleTerminalRelease: (
+    handler: (
+      request: AcpSchema.ReleaseTerminalRequest,
+    ) => Effect.Effect<AcpSchema.ReleaseTerminalResponse | void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `session/update`.
+   * @see https://agentclientprotocol.com/protocol/schema#session/update
+   */
+  readonly handleSessionUpdate: (
+    handler: (
+      notification: AcpSchema.SessionNotification,
+    ) => Effect.Effect<void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a handler for `session/elicitation/complete`.
+   * @see https://agentclientprotocol.com/protocol/schema#session/elicitation/complete
+   */
+  readonly handleElicitationComplete: (
+    handler: (
+      notification: AcpSchema.ElicitationCompleteNotification,
+    ) => Effect.Effect<void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a fallback extension request handler.
+   * @see https://agentclientprotocol.com/protocol/extensibility
+   */
+  readonly handleUnknownExtRequest: (
+    handler: (method: string, params: unknown) => Effect.Effect<unknown, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a fallback extension notification handler.
+   * @see https://agentclientprotocol.com/protocol/extensibility
+   */
+  readonly handleUnknownExtNotification: (
+    handler: (method: string, params: unknown) => Effect.Effect<void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a typed extension request handler.
+   * @see https://agentclientprotocol.com/protocol/extensibility
+   */
+  readonly handleExtRequest: <A, I>(
+    method: string,
+    payload: Schema.Codec<A, I>,
+    handler: (payload: A) => Effect.Effect<unknown, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+  /**
+   * Registers a typed extension notification handler.
+   * @see https://agentclientprotocol.com/protocol/extensibility
+   */
+  readonly handleExtNotification: <A, I>(
+    method: string,
+    payload: Schema.Codec<A, I>,
+    handler: (payload: A) => Effect.Effect<void, AcpError.AcpError>,
+  ) => Effect.Effect<void>;
+}
+
+export class AcpClient extends Context.Service<AcpClient, AcpClientShape>()(
+  "effect-acp/AcpClient",
+) {}
+
+interface AcpCoreRequestHandlers {
+  requestPermission?: (
+    request: AcpSchema.RequestPermissionRequest,
+  ) => Effect.Effect<AcpSchema.RequestPermissionResponse, AcpError.AcpError>;
+  elicitation?: (
+    request: AcpSchema.ElicitationRequest,
+  ) => Effect.Effect<AcpSchema.ElicitationResponse, AcpError.AcpError>;
+  readTextFile?: (
+    request: AcpSchema.ReadTextFileRequest,
+  ) => Effect.Effect<AcpSchema.ReadTextFileResponse, AcpError.AcpError>;
+  writeTextFile?: (
+    request: AcpSchema.WriteTextFileRequest,
+  ) => Effect.Effect<AcpSchema.WriteTextFileResponse | void, AcpError.AcpError>;
+  createTerminal?: (
+    request: AcpSchema.CreateTerminalRequest,
+  ) => Effect.Effect<AcpSchema.CreateTerminalResponse, AcpError.AcpError>;
+  terminalOutput?: (
+    request: AcpSchema.TerminalOutputRequest,
+  ) => Effect.Effect<AcpSchema.TerminalOutputResponse, AcpError.AcpError>;
+  terminalWaitForExit?: (
+    request: AcpSchema.WaitForTerminalExitRequest,
+  ) => Effect.Effect<AcpSchema.WaitForTerminalExitResponse, AcpError.AcpError>;
+  terminalKill?: (
+    request: AcpSchema.KillTerminalRequest,
+  ) => Effect.Effect<AcpSchema.KillTerminalResponse | void, AcpError.AcpError>;
+  terminalRelease?: (
+    request: AcpSchema.ReleaseTerminalRequest,
+  ) => Effect.Effect<AcpSchema.ReleaseTerminalResponse | void, AcpError.AcpError>;
+}
+
+interface AcpNotificationHandlers {
+  readonly sessionUpdate: BufferedNotificationHandler<AcpSchema.SessionNotification>;
+  readonly elicitationComplete: BufferedNotificationHandler<AcpSchema.ElicitationCompleteNotification>;
+}
+
+interface BufferedNotificationHandler<A> {
+  readonly handlers: Array<(notification: A) => Effect.Effect<void, AcpError.AcpError>>;
+  readonly pending: Array<A>;
+}
+
+export const make = Effect.fn("effect-acp/AcpClient.make")(function* (
+  stdio: Stdio.Stdio,
+  options: AcpClientOptions = {},
+  terminationError?: Effect.Effect<AcpError.AcpError>,
+): Effect.fn.Return<AcpClientShape, never, Scope.Scope> {
+  const coreHandlers: AcpCoreRequestHandlers = {};
+  const notificationHandlers: AcpNotificationHandlers = {
+    sessionUpdate: { handlers: [], pending: [] },
+    elicitationComplete: { handlers: [], pending: [] },
+  };
+  const extRequestHandlers = new Map<
+    string,
+    (params: unknown) => Effect.Effect<unknown, AcpError.AcpError>
+  >();
+  const extNotificationHandlers = new Map<
+    string,
+    (params: unknown) => Effect.Effect<void, AcpError.AcpError>
+  >();
+  let unknownExtRequestHandler:
+    | ((method: string, params: unknown) => Effect.Effect<unknown, AcpError.AcpError>)
+    | undefined;
+  let unknownExtNotificationHandler:
+    | ((method: string, params: unknown) => Effect.Effect<void, AcpError.AcpError>)
+    | undefined;
+
+  const runNotificationHandlers = <A>(
+    registration: BufferedNotificationHandler<A>,
+    notification: A,
+  ) =>
+    Effect.forEach(
+      registration.handlers,
+      (handler) => handler(notification).pipe(Effect.catch(() => Effect.void)),
+      { discard: true },
+    );
+
+  const flushBufferedNotifications = <A>(registration: BufferedNotificationHandler<A>) =>
+    Effect.suspend(() => {
+      if (registration.handlers.length === 0 || registration.pending.length === 0) {
+        return Effect.void;
+      }
+      const pending = registration.pending.splice(0, registration.pending.length);
+      return Effect.forEach(
+        pending,
+        (notification) => runNotificationHandlers(registration, notification),
+        {
+          discard: true,
+        },
+      );
+    });
+
+  const dispatchNotification = (notification: AcpProtocol.AcpIncomingNotification) => {
+    switch (notification._tag) {
+      case "SessionUpdate": {
+        if (notificationHandlers.sessionUpdate.handlers.length === 0) {
+          notificationHandlers.sessionUpdate.pending.push(notification.params);
+          return Effect.void;
+        }
+        return runNotificationHandlers(notificationHandlers.sessionUpdate, notification.params);
+      }
+      case "ElicitationComplete": {
+        if (notificationHandlers.elicitationComplete.handlers.length === 0) {
+          notificationHandlers.elicitationComplete.pending.push(notification.params);
+          return Effect.void;
+        }
+        return runNotificationHandlers(
+          notificationHandlers.elicitationComplete,
+          notification.params,
+        );
+      }
+      case "ExtNotification": {
+        const handler = extNotificationHandlers.get(notification.method);
+        if (handler) {
+          return handler(notification.params);
+        }
+        return unknownExtNotificationHandler
+          ? unknownExtNotificationHandler(notification.method, notification.params)
+          : Effect.void;
+      }
+    }
+  };
+
+  const dispatchExtRequest = (method: string, params: unknown) => {
+    const handler = extRequestHandlers.get(method);
+    if (handler) {
+      return handler(params);
+    }
+    return unknownExtRequestHandler
+      ? unknownExtRequestHandler(method, params)
+      : Effect.fail(AcpError.AcpRequestError.methodNotFound(method));
+  };
+
+  const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+    stdio: stdio,
+    ...(terminationError ? { terminationError } : {}),
+    serverRequestMethods: new Set(AcpRpcs.ClientRpcs.requests.keys()),
+    ...(options.logIncoming !== undefined ? { logIncoming: options.logIncoming } : {}),
+    ...(options.logOutgoing !== undefined ? { logOutgoing: options.logOutgoing } : {}),
+    ...(options.logger ? { logger: options.logger } : {}),
+    onNotification: dispatchNotification,
+    onExtRequest: dispatchExtRequest,
+  });
+
+  const clientHandlerLayer = AcpRpcs.ClientRpcs.toLayer(
+    AcpRpcs.ClientRpcs.of({
+      [CLIENT_METHODS.session_request_permission]: (payload) =>
+        runHandler(
+          coreHandlers.requestPermission,
+          payload,
+          CLIENT_METHODS.session_request_permission,
+        ),
+      [CLIENT_METHODS.session_elicitation]: (payload) =>
+        runHandler(coreHandlers.elicitation, payload, CLIENT_METHODS.session_elicitation),
+      [CLIENT_METHODS.fs_read_text_file]: (payload) =>
+        runHandler(coreHandlers.readTextFile, payload, CLIENT_METHODS.fs_read_text_file),
+      [CLIENT_METHODS.fs_write_text_file]: (payload) =>
+        runHandler(coreHandlers.writeTextFile, payload, CLIENT_METHODS.fs_write_text_file).pipe(
+          Effect.map((result) => result ?? {}),
+        ),
+      [CLIENT_METHODS.terminal_create]: (payload) =>
+        runHandler(coreHandlers.createTerminal, payload, CLIENT_METHODS.terminal_create),
+      [CLIENT_METHODS.terminal_output]: (payload) =>
+        runHandler(coreHandlers.terminalOutput, payload, CLIENT_METHODS.terminal_output),
+      [CLIENT_METHODS.terminal_wait_for_exit]: (payload) =>
+        runHandler(
+          coreHandlers.terminalWaitForExit,
+          payload,
+          CLIENT_METHODS.terminal_wait_for_exit,
+        ),
+      [CLIENT_METHODS.terminal_kill]: (payload) =>
+        runHandler(coreHandlers.terminalKill, payload, CLIENT_METHODS.terminal_kill).pipe(
+          Effect.map((result) => result ?? {}),
+        ),
+      [CLIENT_METHODS.terminal_release]: (payload) =>
+        runHandler(coreHandlers.terminalRelease, payload, CLIENT_METHODS.terminal_release).pipe(
+          Effect.map((result) => result ?? {}),
+        ),
+    }),
+  );
+
+  yield* RpcServer.make(AcpRpcs.ClientRpcs).pipe(
+    Effect.provideService(RpcServer.Protocol, transport.serverProtocol),
+    Effect.provide(clientHandlerLayer),
+    Effect.forkScoped,
+  );
+
+  let nextRpcRequestId = 1n << 32n;
+  const rpc = yield* RpcClient.make(AcpRpcs.AgentRpcs, {
+    generateRequestId: () => nextRpcRequestId++ as never,
+  }).pipe(Effect.provideService(RpcClient.Protocol, transport.clientProtocol));
+
+  return AcpClient.of({
+    raw: {
+      notifications: transport.incoming,
+      request: transport.request,
+      notify: transport.notify,
+    },
+    agent: {
+      initialize: (payload) => callRpc(rpc[AGENT_METHODS.initialize](payload)),
+      authenticate: (payload) => callRpc(rpc[AGENT_METHODS.authenticate](payload)),
+      logout: (payload) => callRpc(rpc[AGENT_METHODS.logout](payload)),
+      createSession: (payload) => callRpc(rpc[AGENT_METHODS.session_new](payload)),
+      loadSession: (payload) => callRpc(rpc[AGENT_METHODS.session_load](payload)),
+      listSessions: (payload) => callRpc(rpc[AGENT_METHODS.session_list](payload)),
+      forkSession: (payload) => callRpc(rpc[AGENT_METHODS.session_fork](payload)),
+      resumeSession: (payload) => callRpc(rpc[AGENT_METHODS.session_resume](payload)),
+      closeSession: (payload) => callRpc(rpc[AGENT_METHODS.session_close](payload)),
+      setSessionModel: (payload) => callRpc(rpc[AGENT_METHODS.session_set_model](payload)),
+      setSessionConfigOption: (payload) =>
+        callRpc(rpc[AGENT_METHODS.session_set_config_option](payload)),
+      prompt: (payload) => callRpc(rpc[AGENT_METHODS.session_prompt](payload)),
+      cancel: (payload) => transport.notify(AGENT_METHODS.session_cancel, payload),
+    },
+    handleRequestPermission: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.requestPermission = handler;
+        return Effect.void;
+      }),
+    handleElicitation: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.elicitation = handler;
+        return Effect.void;
+      }),
+    handleReadTextFile: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.readTextFile = handler;
+        return Effect.void;
+      }),
+    handleWriteTextFile: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.writeTextFile = handler;
+        return Effect.void;
+      }),
+    handleCreateTerminal: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.createTerminal = handler;
+        return Effect.void;
+      }),
+    handleTerminalOutput: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.terminalOutput = handler;
+        return Effect.void;
+      }),
+    handleTerminalWaitForExit: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.terminalWaitForExit = handler;
+        return Effect.void;
+      }),
+    handleTerminalKill: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.terminalKill = handler;
+        return Effect.void;
+      }),
+    handleTerminalRelease: (handler) =>
+      Effect.suspend(() => {
+        coreHandlers.terminalRelease = handler;
+        return Effect.void;
+      }),
+    handleSessionUpdate: (handler) =>
+      Effect.suspend(() => {
+        notificationHandlers.sessionUpdate.handlers.push(handler);
+        return flushBufferedNotifications(notificationHandlers.sessionUpdate);
+      }),
+    handleElicitationComplete: (handler) =>
+      Effect.suspend(() => {
+        notificationHandlers.elicitationComplete.handlers.push(handler);
+        return flushBufferedNotifications(notificationHandlers.elicitationComplete);
+      }),
+    handleUnknownExtRequest: (handler) =>
+      Effect.suspend(() => {
+        unknownExtRequestHandler = handler;
+        return Effect.void;
+      }),
+    handleUnknownExtNotification: (handler) =>
+      Effect.suspend(() => {
+        unknownExtNotificationHandler = handler;
+        return Effect.void;
+      }),
+    handleExtRequest: (method, payload, handler) =>
+      Effect.suspend(() => {
+        extRequestHandlers.set(method, decodeExtRequestRegistration(method, payload, handler));
+        return Effect.void;
+      }),
+    handleExtNotification: (method, payload, handler) =>
+      Effect.suspend(() => {
+        extNotificationHandlers.set(
+          method,
+          decodeExtNotificationRegistration(method, payload, handler),
+        );
+        return Effect.void;
+      }),
+  });
+});
+
+export const layerChildProcess = (
+  handle: ChildProcessSpawner.ChildProcessHandle,
+  options: AcpClientOptions = {},
+): Layer.Layer<AcpClient> => {
+  const stdio = makeChildStdio(handle);
+  const terminationError = makeTerminationError(handle);
+  return Layer.effect(AcpClient, make(stdio, options, terminationError));
+};
diff --git a/packages/effect-acp/src/errors.ts b/packages/effect-acp/src/errors.ts
new file mode 100644
index 00000000000..b2fa39120d4
--- /dev/null
+++ b/packages/effect-acp/src/errors.ts
@@ -0,0 +1,139 @@
+import * as Schema from "effect/Schema";
+
+import * as AcpSchema from "./_generated/schema.gen.ts";
+
+export class AcpSpawnError extends Schema.TaggedErrorClass<AcpSpawnError>()("AcpSpawnError", {
+  command: Schema.optional(Schema.String),
+  cause: Schema.Defect,
+}) {
+  override get message() {
+    return this.command
+      ? `Failed to spawn ACP process for command: ${this.command}`
+      : "Failed to spawn ACP process";
+  }
+}
+
+export class AcpProcessExitedError extends Schema.TaggedErrorClass<AcpProcessExitedError>()(
+  "AcpProcessExitedError",
+  {
+    code: Schema.optional(Schema.Number),
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message() {
+    return this.code === undefined
+      ? "ACP process exited"
+      : `ACP process exited with code ${this.code}`;
+  }
+}
+
+export class AcpProtocolParseError extends Schema.TaggedErrorClass<AcpProtocolParseError>()(
+  "AcpProtocolParseError",
+  {
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message() {
+    return `Failed to parse ACP protocol message: ${this.detail}`;
+  }
+}
+
+export class AcpTransportError extends Schema.TaggedErrorClass<AcpTransportError>()(
+  "AcpTransportError",
+  {
+    detail: Schema.String,
+    cause: Schema.Defect,
+  },
+) {}
+
+export class AcpRequestError extends Schema.TaggedErrorClass<AcpRequestError>()("AcpRequestError", {
+  code: AcpSchema.ErrorCode,
+  errorMessage: Schema.String,
+  data: Schema.optional(Schema.Unknown),
+}) {
+  override get message() {
+    return this.errorMessage;
+  }
+
+  static fromProtocolError(error: AcpSchema.Error) {
+    return new AcpRequestError({
+      code: error.code,
+      errorMessage: error.message,
+      ...(error.data !== undefined ? { data: error.data } : {}),
+    });
+  }
+
+  static parseError(message = "Parse error", data?: unknown) {
+    return new AcpRequestError({
+      code: -32700,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static invalidRequest(message = "Invalid request", data?: unknown) {
+    return new AcpRequestError({
+      code: -32600,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static methodNotFound(method: string) {
+    return new AcpRequestError({
+      code: -32601,
+      errorMessage: `Method not found: ${method}`,
+    });
+  }
+
+  static invalidParams(message = "Invalid params", data?: unknown) {
+    return new AcpRequestError({
+      code: -32602,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static internalError(message = "Internal error", data?: unknown) {
+    return new AcpRequestError({
+      code: -32603,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static authRequired(message = "Authentication required", data?: unknown) {
+    return new AcpRequestError({
+      code: -32000,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static resourceNotFound(message = "Resource not found", data?: unknown) {
+    return new AcpRequestError({
+      code: -32002,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  toProtocolError() {
+    return AcpSchema.Error.make({
+      code: this.code,
+      message: this.errorMessage,
+      ...(this.data !== undefined ? { data: this.data } : {}),
+    });
+  }
+}
+
+export const AcpError = Schema.Union([
+  AcpRequestError,
+  AcpSpawnError,
+  AcpProcessExitedError,
+  AcpProtocolParseError,
+  AcpTransportError,
+]);
+
+export type AcpError = typeof AcpError.Type;
diff --git a/packages/effect-acp/src/protocol.test.ts b/packages/effect-acp/src/protocol.test.ts
new file mode 100644
index 00000000000..8a4a193e3c7
--- /dev/null
+++ b/packages/effect-acp/src/protocol.test.ts
@@ -0,0 +1,448 @@
+import * as Path from "effect/Path";
+import * as AcpError from "./errors.ts";
+import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as Fiber from "effect/Fiber";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as Ref from "effect/Ref";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { it, assert } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+
+import * as AcpSchema from "./_generated/schema.gen.ts";
+import * as AcpProtocol from "./protocol.ts";
+import {
+  encodeJsonl,
+  jsonRpcNotification,
+  jsonRpcRequest,
+  jsonRpcResponse,
+} from "./_internal/shared.ts";
+import { makeInMemoryStdio, makeTerminationError, makeChildStdio } from "./_internal/stdio.ts";
+
+const SessionCancelNotification = jsonRpcNotification(
+  "session/cancel",
+  AcpSchema.CancelNotification,
+);
+const SessionUpdateNotification = jsonRpcNotification(
+  "session/update",
+  AcpSchema.SessionNotification,
+);
+const ElicitationCompleteNotification = jsonRpcNotification(
+  "session/elicitation/complete",
+  AcpSchema.ElicitationCompleteNotification,
+);
+const RequestPermissionRequest = jsonRpcRequest(
+  "session/request_permission",
+  AcpSchema.RequestPermissionRequest,
+);
+const RequestPermissionResponse = jsonRpcResponse(AcpSchema.RequestPermissionResponse);
+const ExtRequest = jsonRpcRequest("x/test", Schema.Struct({ hello: Schema.String }));
+const ExtResponse = jsonRpcResponse(Schema.Struct({ ok: Schema.Boolean }));
+const decodeSessionCancelNotification = Schema.decodeEffect(
+  Schema.fromJsonString(SessionCancelNotification),
+);
+const decodeExtRequest = Schema.decodeEffect(Schema.fromJsonString(ExtRequest));
+const decodeRequestPermissionResponse = Schema.decodeEffect(
+  Schema.fromJsonString(RequestPermissionResponse),
+);
+const mockPeerPath = Effect.map(Effect.service(Path.Path), (path) =>
+  path.join(import.meta.dirname, "../test/fixtures/acp-mock-peer.ts"),
+);
+
+const makeHandle = (env?: Record<string, string>) =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const path = yield* Path.Path;
+    const command = ChildProcess.make("bun", ["run", yield* mockPeerPath], {
+      cwd: path.join(import.meta.dirname, ".."),
+      shell: process.platform === "win32",
+      ...(env ? { env: { ...process.env, ...env } } : {}),
+    });
+    return yield* spawner.spawn(command);
+  });
+
+it.layer(NodeServices.layer)("effect-acp protocol", (it) => {
+  it.effect(
+    "emits exact JSON-RPC notifications and decodes inbound session/update and elicitation completion",
+    () =>
+      Effect.gen(function* () {
+        const { stdio, input, output } = yield* makeInMemoryStdio();
+        const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+          stdio,
+          serverRequestMethods: new Set(),
+        });
+
+        const notifications =
+          yield* Deferred.make<ReadonlyArray<AcpProtocol.AcpIncomingNotification>>();
+        yield* transport.incoming.pipe(
+          Stream.take(2),
+          Stream.runCollect,
+          Effect.flatMap((notificationChunk) => Deferred.succeed(notifications, notificationChunk)),
+          Effect.forkScoped,
+        );
+
+        yield* transport.notify("session/cancel", { sessionId: "session-1" });
+        const outbound = yield* Queue.take(output);
+        assert.deepEqual(yield* decodeSessionCancelNotification(outbound), {
+          jsonrpc: "2.0",
+          method: "session/cancel",
+          params: {
+            sessionId: "session-1",
+          },
+        });
+
+        yield* Queue.offer(
+          input,
+          yield* encodeJsonl(SessionUpdateNotification, {
+            jsonrpc: "2.0",
+            method: "session/update",
+            params: {
+              sessionId: "session-1",
+              update: {
+                sessionUpdate: "plan",
+                entries: [
+                  {
+                    content: "Inspect repository",
+                    priority: "high",
+                    status: "in_progress",
+                  },
+                ],
+              },
+            },
+          }),
+        );
+
+        yield* Queue.offer(
+          input,
+          yield* encodeJsonl(ElicitationCompleteNotification, {
+            jsonrpc: "2.0",
+            method: "session/elicitation/complete",
+            params: {
+              elicitationId: "elicitation-1",
+            },
+          }),
+        );
+
+        const [update, completion] = yield* Deferred.await(notifications);
+        assert.equal(update?._tag, "SessionUpdate");
+        assert.equal(completion?._tag, "ElicitationComplete");
+      }),
+  );
+
+  it.effect("logs outgoing notifications when logOutgoing is enabled", () =>
+    Effect.gen(function* () {
+      const { stdio } = yield* makeInMemoryStdio();
+      const events: Array<AcpProtocol.AcpProtocolLogEvent> = [];
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio,
+        serverRequestMethods: new Set(),
+        logOutgoing: true,
+        logger: (event) =>
+          Effect.sync(() => {
+            events.push(event);
+          }),
+      });
+
+      yield* transport.notify("session/cancel", { sessionId: "session-1" });
+
+      assert.deepEqual(events, [
+        {
+          direction: "outgoing",
+          stage: "decoded",
+          payload: {
+            _tag: "Request",
+            id: "",
+            tag: "session/cancel",
+            payload: {
+              sessionId: "session-1",
+            },
+            headers: [],
+          },
+        },
+        {
+          direction: "outgoing",
+          stage: "raw",
+          payload:
+            '{"jsonrpc":"2.0","method":"session/cancel","params":{"sessionId":"session-1"},"id":"","headers":[]}\n',
+        },
+      ]);
+    }),
+  );
+
+  it.effect("fails notification encoding through the declared ACP error channel", () =>
+    Effect.gen(function* () {
+      const { stdio } = yield* makeInMemoryStdio();
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio,
+        serverRequestMethods: new Set(),
+      });
+
+      const bigintError = yield* transport.notify("x/test", 1n).pipe(Effect.flip);
+      assert.instanceOf(bigintError, AcpError.AcpProtocolParseError);
+      assert.equal(bigintError.detail, "Failed to encode ACP message");
+
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+      const circularError = yield* transport.notify("x/test", circular).pipe(Effect.flip);
+      assert.instanceOf(circularError, AcpError.AcpProtocolParseError);
+      assert.equal(circularError.detail, "Failed to encode ACP message");
+    }),
+  );
+
+  it.effect("supports generic extension requests over the patched transport", () =>
+    Effect.gen(function* () {
+      const { stdio, input, output } = yield* makeInMemoryStdio();
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio,
+        serverRequestMethods: new Set(),
+      });
+
+      const response = yield* transport
+        .request("x/test", { hello: "world" })
+        .pipe(Effect.forkScoped);
+      const outbound = yield* Queue.take(output);
+      assert.deepEqual(yield* decodeExtRequest(outbound), {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "x/test",
+        params: {
+          hello: "world",
+        },
+        headers: [],
+      });
+
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(ExtResponse, {
+          jsonrpc: "2.0",
+          id: 1,
+          result: {
+            ok: true,
+          },
+        }),
+      );
+
+      const resolved = yield* Fiber.join(response);
+      assert.deepEqual(resolved, { ok: true });
+    }),
+  );
+
+  it.effect("preserves zero-valued ids for inbound core client requests", () =>
+    Effect.gen(function* () {
+      const { stdio, input, output } = yield* makeInMemoryStdio();
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio,
+        serverRequestMethods: new Set(["session/request_permission"]),
+      });
+      const inboundRequest = yield* Deferred.make<unknown>();
+
+      yield* transport.serverProtocol
+        .run((_clientId, message) => Deferred.succeed(inboundRequest, message).pipe(Effect.asVoid))
+        .pipe(Effect.forkScoped);
+
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(RequestPermissionRequest, {
+          jsonrpc: "2.0",
+          id: 0,
+          method: "session/request_permission",
+          params: {
+            sessionId: "session-1",
+            toolCall: {
+              toolCallId: "tool-1",
+              title: "Allow mock action",
+            },
+            options: [{ optionId: "allow", name: "Allow", kind: "allow_once" }],
+          },
+          headers: [],
+        }),
+      );
+
+      const message = yield* Deferred.await(inboundRequest);
+      assert.deepEqual(message, {
+        _tag: "Request",
+        id: "0",
+        tag: "session/request_permission",
+        payload: {
+          sessionId: "session-1",
+          toolCall: {
+            toolCallId: "tool-1",
+            title: "Allow mock action",
+          },
+          options: [{ optionId: "allow", name: "Allow", kind: "allow_once" }],
+        },
+        headers: [],
+      });
+
+      yield* transport.serverProtocol.send(0, {
+        _tag: "Exit",
+        requestId: "0",
+        exit: {
+          _tag: "Success",
+          value: {
+            outcome: {
+              outcome: "selected",
+              optionId: "allow",
+            },
+          },
+        },
+      });
+
+      const outbound = yield* Queue.take(output);
+      assert.deepEqual(yield* decodeRequestPermissionResponse(outbound), {
+        jsonrpc: "2.0",
+        id: 0,
+        result: {
+          outcome: {
+            outcome: "selected",
+            optionId: "allow",
+          },
+        },
+      });
+    }),
+  );
+
+  it.effect("cleans up interrupted extension requests before a late response arrives", () =>
+    Effect.gen(function* () {
+      const { stdio, input, output } = yield* makeInMemoryStdio();
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio,
+        serverRequestMethods: new Set(),
+      });
+      const lateResponse = yield* Deferred.make<unknown>();
+
+      yield* transport.clientProtocol
+        .run(0, (message) => Deferred.succeed(lateResponse, message).pipe(Effect.asVoid))
+        .pipe(Effect.forkScoped);
+
+      const response = yield* transport
+        .request("x/test", { hello: "world" })
+        .pipe(Effect.forkScoped);
+      const outbound = yield* Queue.take(output);
+      assert.deepEqual(yield* decodeExtRequest(outbound), {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "x/test",
+        params: {
+          hello: "world",
+        },
+        headers: [],
+      });
+
+      yield* Fiber.interrupt(response);
+      yield* Queue.offer(
+        input,
+        yield* encodeJsonl(ExtResponse, {
+          jsonrpc: "2.0",
+          id: 1,
+          result: {
+            ok: true,
+          },
+        }),
+      );
+
+      const message = yield* Deferred.await(lateResponse);
+      assert.deepEqual(message, {
+        _tag: "Exit",
+        requestId: "1",
+        exit: {
+          _tag: "Success",
+          value: {
+            ok: true,
+          },
+        },
+      });
+    }),
+  );
+
+  it.effect("propagates the real child exit code when the input stream ends", () =>
+    Effect.gen(function* () {
+      const handle = yield* makeHandle({ ACP_MOCK_EXIT_IMMEDIATELY_CODE: "7" });
+      const firstMessage = yield* Deferred.make<unknown>();
+      const termination = yield* Deferred.make<AcpError.AcpError>();
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio: makeChildStdio(handle),
+        terminationError: makeTerminationError(handle),
+        serverRequestMethods: new Set(),
+        onTermination: (error) => Deferred.succeed(termination, error).pipe(Effect.asVoid),
+      });
+
+      yield* transport.clientProtocol
+        .run(0, (message) => Deferred.succeed(firstMessage, message).pipe(Effect.asVoid))
+        .pipe(Effect.forkScoped);
+
+      const message = yield* Deferred.await(firstMessage);
+      const exitError = yield* Deferred.await(termination);
+      assert.instanceOf(exitError, AcpError.AcpProcessExitedError);
+      assert.equal((exitError as AcpError.AcpProcessExitedError).code, 7);
+      assert.equal((message as { readonly _tag?: string })._tag, "ClientProtocolError");
+      const defect = (message as { readonly error: { readonly reason: unknown } }).error.reason as {
+        readonly _tag: string;
+        readonly cause: unknown;
+      };
+      assert.equal(defect._tag, "RpcClientDefect");
+      assert.instanceOf(defect.cause, AcpError.AcpProcessExitedError);
+      assert.equal((defect.cause as AcpError.AcpProcessExitedError).code, 7);
+    }),
+  );
+
+  it.effect("does not emit a second process-exit error after a decode failure", () =>
+    Effect.gen(function* () {
+      const handle = yield* makeHandle({
+        ACP_MOCK_MALFORMED_OUTPUT: "1",
+        ACP_MOCK_MALFORMED_OUTPUT_EXIT_CODE: "23",
+      });
+      const terminationCalls = yield* Ref.make(0);
+      const firstMessage = yield* Deferred.make<unknown>();
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio: makeChildStdio(handle),
+        terminationError: makeTerminationError(handle),
+        serverRequestMethods: new Set(),
+        onTermination: () => Ref.update(terminationCalls, (count) => count + 1),
+      });
+
+      yield* transport.clientProtocol
+        .run(0, (message) => Deferred.succeed(firstMessage, message).pipe(Effect.asVoid))
+        .pipe(Effect.forkScoped);
+
+      const message = yield* Deferred.await(firstMessage);
+      assert.equal(yield* Ref.get(terminationCalls), 1);
+      assert.equal((message as { readonly _tag?: string })._tag, "ClientProtocolError");
+      const defect = (message as { readonly error: { readonly reason: unknown } }).error.reason as {
+        readonly _tag: string;
+        readonly cause: unknown;
+      };
+      assert.equal(defect._tag, "RpcClientDefect");
+      assert.instanceOf(defect.cause, AcpError.AcpProtocolParseError);
+    }),
+  );
+
+  it.effect("fails pending extension requests with the propagated exit code", () =>
+    Effect.gen(function* () {
+      const { stdio, input, output } = yield* makeInMemoryStdio();
+      const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
+        stdio,
+        terminationError: Effect.succeed(new AcpError.AcpProcessExitedError({ code: 0 })),
+        serverRequestMethods: new Set(),
+      });
+
+      const response = yield* transport
+        .request("x/test", { hello: "world" })
+        .pipe(Effect.forkScoped);
+      yield* Queue.take(output);
+      yield* Queue.end(input);
+
+      const error = yield* Fiber.join(response).pipe(
+        Effect.match({
+          onFailure: (error) => error,
+          onSuccess: () => assert.fail("Expected request to fail after process exit"),
+        }),
+      );
+      assert.instanceOf(error, AcpError.AcpProcessExitedError);
+      assert.equal(error.code, 0);
+    }),
+  );
+});
diff --git a/packages/effect-acp/src/protocol.ts b/packages/effect-acp/src/protocol.ts
new file mode 100644
index 00000000000..52d6eafd6d5
--- /dev/null
+++ b/packages/effect-acp/src/protocol.ts
@@ -0,0 +1,536 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as Stdio from "effect/Stdio";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as RpcClientError from "effect/unstable/rpc/RpcClientError";
+import * as RpcMessage from "effect/unstable/rpc/RpcMessage";
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
+import * as RpcServer from "effect/unstable/rpc/RpcServer";
+
+import * as AcpSchema from "./_generated/schema.gen.ts";
+import { CLIENT_METHODS } from "./_generated/meta.gen.ts";
+import * as AcpError from "./errors.ts";
+const isAcpError = Schema.is(AcpError.AcpError);
+const isAcpRequestError = Schema.is(AcpError.AcpRequestError);
+
+export interface AcpProtocolLogEvent {
+  readonly direction: "incoming" | "outgoing";
+  readonly stage: "raw" | "decoded" | "decode_failed";
+  readonly payload: unknown;
+}
+
+export type AcpIncomingNotification =
+  | {
+      readonly _tag: "SessionUpdate";
+      readonly method: typeof CLIENT_METHODS.session_update;
+      readonly params: typeof AcpSchema.SessionNotification.Type;
+    }
+  | {
+      readonly _tag: "ElicitationComplete";
+      readonly method: typeof CLIENT_METHODS.session_elicitation_complete;
+      readonly params: typeof AcpSchema.ElicitationCompleteNotification.Type;
+    }
+  | {
+      readonly _tag: "ExtNotification";
+      readonly method: string;
+      readonly params: unknown;
+    };
+
+export interface AcpPatchedProtocolOptions {
+  readonly stdio: Stdio.Stdio;
+  readonly terminationError?: Effect.Effect<AcpError.AcpError>;
+  readonly serverRequestMethods: ReadonlySet<string>;
+  readonly logIncoming?: boolean;
+  readonly logOutgoing?: boolean;
+  readonly logger?: (event: AcpProtocolLogEvent) => Effect.Effect<void, never>;
+  readonly onNotification?: (
+    notification: AcpIncomingNotification,
+  ) => Effect.Effect<void, AcpError.AcpError, never>;
+  readonly onExtRequest?: (
+    method: string,
+    params: unknown,
+  ) => Effect.Effect<unknown, AcpError.AcpError, never>;
+  readonly onTermination?: (error: AcpError.AcpError) => Effect.Effect<void, never, never>;
+}
+
+export interface AcpPatchedProtocol {
+  readonly clientProtocol: RpcClient.Protocol["Service"];
+  readonly serverProtocol: RpcServer.Protocol["Service"];
+  readonly incoming: Stream.Stream<AcpIncomingNotification>;
+  readonly request: (method: string, payload: unknown) => Effect.Effect<unknown, AcpError.AcpError>;
+  readonly notify: (method: string, payload: unknown) => Effect.Effect<void, AcpError.AcpError>;
+}
+
+const decodeSessionUpdate = Schema.decodeUnknownEffect(AcpSchema.SessionNotification);
+const decodeElicitationComplete = Schema.decodeUnknownEffect(
+  AcpSchema.ElicitationCompleteNotification,
+);
+const parserFactory = RpcSerialization.ndJsonRpc();
+
+export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(function* (
+  options: AcpPatchedProtocolOptions,
+): Effect.fn.Return<AcpPatchedProtocol, never, Scope.Scope> {
+  const parser = parserFactory.makeUnsafe();
+  const serverQueue = yield* Queue.unbounded<RpcMessage.FromClientEncoded>();
+  const clientQueue = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
+  const notificationQueue = yield* Queue.unbounded<AcpIncomingNotification>();
+  const disconnects = yield* Queue.unbounded<number>();
+  const outgoing = yield* Queue.unbounded<string | Uint8Array, Cause.Done<void>>();
+  const nextRequestId = yield* Ref.make(1n);
+  const terminationHandled = yield* Ref.make(false);
+  const extPending = yield* Ref.make(
+    new Map<string, Deferred.Deferred<unknown, AcpError.AcpError>>(),
+  );
+
+  const logProtocol = (event: AcpProtocolLogEvent) => {
+    if (event.direction === "incoming" && !options.logIncoming) {
+      return Effect.void;
+    }
+    if (event.direction === "outgoing" && !options.logOutgoing) {
+      return Effect.void;
+    }
+    return (
+      options.logger?.(event) ??
+      Effect.logDebug("ACP protocol event").pipe(Effect.annotateLogs({ event }))
+    );
+  };
+
+  const offerOutgoing = Effect.fn("offerOutgoing")(function* (
+    message: RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded,
+  ) {
+    yield* logProtocol({
+      direction: "outgoing",
+      stage: "decoded",
+      payload: message,
+    });
+
+    const encoded = yield* Effect.try({
+      try: () => parser.encode(message),
+      catch: (cause) =>
+        new AcpError.AcpProtocolParseError({
+          detail: "Failed to encode ACP message",
+          cause,
+        }),
+    });
+
+    if (encoded) {
+      yield* logProtocol({
+        direction: "outgoing",
+        stage: "raw",
+        payload: typeof encoded === "string" ? encoded : new TextDecoder().decode(encoded),
+      });
+
+      yield* Queue.offer(outgoing, encoded).pipe(Effect.asVoid);
+    }
+  });
+
+  const resolveExtPending = (
+    requestId: string,
+    onFound: (deferred: Deferred.Deferred<unknown, AcpError.AcpError>) => Effect.Effect<void>,
+  ) =>
+    Ref.modify(extPending, (pending) => {
+      const deferred = pending.get(requestId);
+      if (!deferred) {
+        return [Effect.void, pending] as const;
+      }
+      const next = new Map(pending);
+      next.delete(requestId);
+      return [onFound(deferred), next] as const;
+    }).pipe(Effect.flatten);
+
+  const removeExtPending = (requestId: string) =>
+    Ref.update(extPending, (pending) => {
+      if (!pending.has(requestId)) {
+        return pending;
+      }
+      const next = new Map(pending);
+      next.delete(requestId);
+      return next;
+    });
+
+  const completeExtPendingFailure = (requestId: string, error: AcpError.AcpError) =>
+    resolveExtPending(requestId, (deferred) => Deferred.fail(deferred, error));
+
+  const completeExtPendingSuccess = (requestId: string, value: unknown) =>
+    resolveExtPending(requestId, (deferred) => Deferred.succeed(deferred, value));
+
+  const failAllExtPending = (error: AcpError.AcpError) =>
+    Ref.getAndSet(extPending, new Map()).pipe(
+      Effect.flatMap((pending) =>
+        Effect.forEach([...pending.values()], (deferred) => Deferred.fail(deferred, error), {
+          discard: true,
+        }),
+      ),
+    );
+
+  const dispatchNotification = (notification: AcpIncomingNotification) =>
+    Queue.offer(notificationQueue, notification).pipe(
+      Effect.andThen(
+        options.onNotification
+          ? options.onNotification(notification).pipe(Effect.catch(() => Effect.void))
+          : Effect.void,
+      ),
+      Effect.asVoid,
+    );
+
+  const emitClientProtocolError = (error: AcpError.AcpError) =>
+    Queue.offer(clientQueue, {
+      _tag: "ClientProtocolError",
+      error: new RpcClientError.RpcClientError({
+        reason: new RpcClientError.RpcClientDefect({
+          message: error.message,
+          cause: error,
+        }),
+      }),
+    }).pipe(Effect.asVoid);
+
+  const handleTermination = (classify: () => Effect.Effect<AcpError.AcpError | undefined>) =>
+    Ref.modify(terminationHandled, (handled) => {
+      if (handled) {
+        return [Effect.void, true] as const;
+      }
+      return [
+        Effect.gen(function* () {
+          yield* Queue.offer(disconnects, 0);
+          const error = yield* classify();
+          if (!error) {
+            return;
+          }
+          yield* failAllExtPending(error);
+          yield* emitClientProtocolError(error);
+          if (options.onTermination) {
+            yield* options.onTermination(error);
+          }
+        }),
+        true,
+      ] as const;
+    }).pipe(Effect.flatten);
+
+  const respondWithSuccess = (requestId: string, value: unknown) =>
+    offerOutgoing({
+      _tag: "Exit",
+      requestId,
+      exit: {
+        _tag: "Success",
+        value,
+      },
+    });
+
+  const respondWithError = (requestId: string, error: AcpError.AcpRequestError) =>
+    offerOutgoing({
+      _tag: "Exit",
+      requestId,
+      exit: {
+        _tag: "Failure",
+        cause: [
+          {
+            _tag: "Fail",
+            error: error.toProtocolError(),
+          },
+        ],
+      },
+    });
+
+  const handleExtRequest = (message: RpcMessage.RequestEncoded) => {
+    if (!options.onExtRequest) {
+      return respondWithError(message.id, AcpError.AcpRequestError.methodNotFound(message.tag));
+    }
+    return options.onExtRequest(message.tag, message.payload).pipe(
+      Effect.matchEffect({
+        onFailure: (error) => respondWithError(message.id, normalizeToRequestError(error)),
+        onSuccess: (value) => respondWithSuccess(message.id, value),
+      }),
+    );
+  };
+
+  const handleRequestEncoded = (message: RpcMessage.RequestEncoded) => {
+    if (message.id === "") {
+      if (message.tag === CLIENT_METHODS.session_update) {
+        return decodeSessionUpdate(message.payload).pipe(
+          Effect.map(
+            (params) =>
+              ({
+                _tag: "SessionUpdate",
+                method: CLIENT_METHODS.session_update,
+                params,
+              }) satisfies AcpIncomingNotification,
+          ),
+          Effect.mapError(
+            (cause) =>
+              new AcpError.AcpProtocolParseError({
+                detail: `Invalid ${CLIENT_METHODS.session_update} notification payload`,
+                cause,
+              }),
+          ),
+          Effect.flatMap(dispatchNotification),
+        );
+      }
+      if (message.tag === CLIENT_METHODS.session_elicitation_complete) {
+        return decodeElicitationComplete(message.payload).pipe(
+          Effect.map(
+            (params) =>
+              ({
+                _tag: "ElicitationComplete",
+                method: CLIENT_METHODS.session_elicitation_complete,
+                params,
+              }) satisfies AcpIncomingNotification,
+          ),
+          Effect.mapError(
+            (cause) =>
+              new AcpError.AcpProtocolParseError({
+                detail: `Invalid ${CLIENT_METHODS.session_elicitation_complete} notification payload`,
+                cause,
+              }),
+          ),
+          Effect.flatMap(dispatchNotification),
+        );
+      }
+      return dispatchNotification({
+        _tag: "ExtNotification",
+        method: message.tag,
+        params: message.payload,
+      });
+    }
+
+    if (!options.serverRequestMethods.has(message.tag)) {
+      return handleExtRequest(message).pipe(
+        Effect.catch(() => respondWithError(message.id, AcpError.AcpRequestError.internalError())),
+        Effect.asVoid,
+      );
+    }
+
+    return Queue.offer(serverQueue, message).pipe(Effect.asVoid);
+  };
+
+  const handleExitEncoded = (message: RpcMessage.ResponseExitEncoded) =>
+    Ref.get(extPending).pipe(
+      Effect.flatMap((pending) => {
+        if (!pending.has(message.requestId)) {
+          return Queue.offer(clientQueue, message).pipe(Effect.asVoid);
+        }
+        if (message.exit._tag === "Success") {
+          return completeExtPendingSuccess(message.requestId, message.exit.value);
+        }
+        const failure = message.exit.cause.find((entry) => entry._tag === "Fail");
+        if (failure && isProtocolError(failure.error)) {
+          return completeExtPendingFailure(
+            message.requestId,
+            AcpError.AcpRequestError.fromProtocolError(failure.error),
+          );
+        }
+        return completeExtPendingFailure(
+          message.requestId,
+          AcpError.AcpRequestError.internalError("Extension request failed"),
+        );
+      }),
+    );
+
+  const routeDecodedMessage = (
+    message: RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded,
+  ): Effect.Effect<void, AcpError.AcpError> => {
+    switch (message._tag) {
+      case "Request":
+        return handleRequestEncoded(message);
+      case "Exit":
+        return handleExitEncoded(message);
+      case "Chunk":
+        return Ref.get(extPending).pipe(
+          Effect.flatMap((pending) =>
+            pending.has(message.requestId)
+              ? completeExtPendingFailure(
+                  message.requestId,
+                  AcpError.AcpRequestError.internalError(
+                    "Streaming extension responses are not supported",
+                  ),
+                )
+              : Queue.offer(clientQueue, message).pipe(Effect.asVoid),
+          ),
+        );
+      case "Defect":
+      case "ClientProtocolError":
+      case "Pong":
+        return Queue.offer(clientQueue, message).pipe(Effect.asVoid);
+      case "Ack":
+      case "Interrupt":
+      case "Ping":
+      case "Eof":
+        return Queue.offer(serverQueue, message).pipe(Effect.asVoid);
+    }
+  };
+
+  yield* options.stdio.stdin.pipe(
+    Stream.runForEach((data) =>
+      logProtocol({
+        direction: "incoming",
+        stage: "raw",
+        payload: typeof data === "string" ? data : new TextDecoder().decode(data),
+      }).pipe(
+        Effect.flatMap(() =>
+          Effect.try({
+            try: () =>
+              parser.decode(data) as ReadonlyArray<
+                RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded
+              >,
+            catch: (cause) =>
+              new AcpError.AcpProtocolParseError({
+                detail: "Failed to decode ACP wire message",
+                cause,
+              }),
+          }),
+        ),
+        Effect.tap((messages) =>
+          logProtocol({
+            direction: "incoming",
+            stage: "decoded",
+            payload: messages,
+          }),
+        ),
+        Effect.tapErrorTag("AcpProtocolParseError", (error) =>
+          logProtocol({
+            direction: "incoming",
+            stage: "decode_failed",
+            payload: {
+              detail: error.detail,
+              cause: error.cause,
+            },
+          }),
+        ),
+        Effect.flatMap((messages) =>
+          Effect.forEach(messages, routeDecodedMessage, {
+            discard: true,
+          }),
+        ),
+      ),
+    ),
+    Effect.matchEffect({
+      onFailure: (error) => {
+        const normalized: AcpError.AcpError = isAcpError(error)
+          ? error
+          : new AcpError.AcpTransportError({
+              detail: error instanceof Error ? error.message : String(error),
+              cause: error,
+            });
+        return handleTermination(() => Effect.succeed(normalized));
+      },
+      onSuccess: () =>
+        handleTermination(
+          () =>
+            options.terminationError ??
+            Effect.succeed(
+              new AcpError.AcpTransportError({
+                detail: "ACP input stream ended",
+                cause: new Error("ACP input stream ended"),
+              }),
+            ),
+        ),
+    }),
+    Effect.forkScoped,
+  );
+
+  yield* Stream.fromQueue(outgoing).pipe(Stream.run(options.stdio.stdout()), Effect.forkScoped);
+
+  const clientProtocol = RpcClient.Protocol.of({
+    run: (_clientId, f) =>
+      Stream.fromQueue(clientQueue).pipe(
+        Stream.runForEach((message) => f(message)),
+        Effect.forever,
+      ),
+    send: (_clientId, request) => offerOutgoing(request).pipe(Effect.mapError(toRpcClientError)),
+    supportsAck: true,
+    supportsTransferables: false,
+  });
+
+  const serverProtocol = RpcServer.Protocol.of({
+    run: (f) =>
+      Stream.fromQueue(serverQueue).pipe(
+        Stream.runForEach((message) => f(0, message)),
+        Effect.forever,
+      ),
+    disconnects,
+    send: (_clientId, response) => offerOutgoing(response).pipe(Effect.orDie),
+    end: (_clientId) => Queue.end(outgoing),
+    clientIds: Effect.succeed(new Set([0])),
+    initialMessage: Effect.succeedNone,
+    supportsAck: true,
+    supportsTransferables: false,
+    supportsSpanPropagation: true,
+  });
+
+  const sendNotification = Effect.fn("sendNotification")(function* (
+    method: string,
+    payload: unknown,
+  ) {
+    yield* offerOutgoing({
+      _tag: "Request",
+      id: "",
+      tag: method,
+      payload,
+      headers: [],
+    });
+  });
+
+  const sendRequest = Effect.fn("sendRequest")(function* (method: string, payload: unknown) {
+    const requestId = yield* Ref.modify(
+      nextRequestId,
+      (current) => [current, current + 1n] as const,
+    );
+    const deferred = yield* Deferred.make<unknown, AcpError.AcpError>();
+    yield* Ref.update(extPending, (pending) => new Map(pending).set(String(requestId), deferred));
+    yield* offerOutgoing({
+      _tag: "Request",
+      id: String(requestId),
+      tag: method,
+      payload,
+      headers: [],
+    }).pipe(
+      Effect.catch((error) =>
+        removeExtPending(String(requestId)).pipe(Effect.andThen(Effect.fail(error))),
+      ),
+    );
+    return yield* Deferred.await(deferred).pipe(
+      Effect.onInterrupt(() => removeExtPending(String(requestId))),
+    );
+  });
+
+  return {
+    clientProtocol,
+    serverProtocol,
+    get incoming() {
+      return Stream.fromQueue(notificationQueue);
+    },
+    request: sendRequest,
+    notify: sendNotification,
+  } satisfies AcpPatchedProtocol;
+});
+
+function isProtocolError(
+  value: unknown,
+): value is { code: number; message: string; data?: unknown } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "code" in value &&
+    typeof value.code === "number" &&
+    "message" in value &&
+    typeof value.message === "string"
+  );
+}
+
+function normalizeToRequestError(error: AcpError.AcpError): AcpError.AcpRequestError {
+  return isAcpRequestError(error) ? error : AcpError.AcpRequestError.internalError(error.message);
+}
+
+function toRpcClientError(error: AcpError.AcpError): RpcClientError.RpcClientError {
+  return new RpcClientError.RpcClientError({
+    reason: new RpcClientError.RpcClientDefect({
+      message: error.message,
+      cause: error,
+    }),
+  });
+}
diff --git a/packages/effect-acp/src/rpc.ts b/packages/effect-acp/src/rpc.ts
new file mode 100644
index 00000000000..93d903e7872
--- /dev/null
+++ b/packages/effect-acp/src/rpc.ts
@@ -0,0 +1,158 @@
+import * as Rpc from "effect/unstable/rpc/Rpc";
+import * as RpcGroup from "effect/unstable/rpc/RpcGroup";
+
+import * as AcpSchema from "./_generated/schema.gen.ts";
+import { AGENT_METHODS, CLIENT_METHODS } from "./_generated/meta.gen.ts";
+
+export const InitializeRpc = Rpc.make(AGENT_METHODS.initialize, {
+  payload: AcpSchema.InitializeRequest,
+  success: AcpSchema.InitializeResponse,
+  error: AcpSchema.Error,
+});
+
+export const AuthenticateRpc = Rpc.make(AGENT_METHODS.authenticate, {
+  payload: AcpSchema.AuthenticateRequest,
+  success: AcpSchema.AuthenticateResponse,
+  error: AcpSchema.Error,
+});
+
+export const LogoutRpc = Rpc.make(AGENT_METHODS.logout, {
+  payload: AcpSchema.LogoutRequest,
+  success: AcpSchema.LogoutResponse,
+  error: AcpSchema.Error,
+});
+
+export const NewSessionRpc = Rpc.make(AGENT_METHODS.session_new, {
+  payload: AcpSchema.NewSessionRequest,
+  success: AcpSchema.NewSessionResponse,
+  error: AcpSchema.Error,
+});
+
+export const LoadSessionRpc = Rpc.make(AGENT_METHODS.session_load, {
+  payload: AcpSchema.LoadSessionRequest,
+  success: AcpSchema.LoadSessionResponse,
+  error: AcpSchema.Error,
+});
+
+export const ListSessionsRpc = Rpc.make(AGENT_METHODS.session_list, {
+  payload: AcpSchema.ListSessionsRequest,
+  success: AcpSchema.ListSessionsResponse,
+  error: AcpSchema.Error,
+});
+
+export const ForkSessionRpc = Rpc.make(AGENT_METHODS.session_fork, {
+  payload: AcpSchema.ForkSessionRequest,
+  success: AcpSchema.ForkSessionResponse,
+  error: AcpSchema.Error,
+});
+
+export const ResumeSessionRpc = Rpc.make(AGENT_METHODS.session_resume, {
+  payload: AcpSchema.ResumeSessionRequest,
+  success: AcpSchema.ResumeSessionResponse,
+  error: AcpSchema.Error,
+});
+
+export const CloseSessionRpc = Rpc.make(AGENT_METHODS.session_close, {
+  payload: AcpSchema.CloseSessionRequest,
+  success: AcpSchema.CloseSessionResponse,
+  error: AcpSchema.Error,
+});
+
+export const PromptRpc = Rpc.make(AGENT_METHODS.session_prompt, {
+  payload: AcpSchema.PromptRequest,
+  success: AcpSchema.PromptResponse,
+  error: AcpSchema.Error,
+});
+
+export const SetSessionModelRpc = Rpc.make(AGENT_METHODS.session_set_model, {
+  payload: AcpSchema.SetSessionModelRequest,
+  success: AcpSchema.SetSessionModelResponse,
+  error: AcpSchema.Error,
+});
+
+export const SetSessionConfigOptionRpc = Rpc.make(AGENT_METHODS.session_set_config_option, {
+  payload: AcpSchema.SetSessionConfigOptionRequest,
+  success: AcpSchema.SetSessionConfigOptionResponse,
+  error: AcpSchema.Error,
+});
+
+export const ReadTextFileRpc = Rpc.make(CLIENT_METHODS.fs_read_text_file, {
+  payload: AcpSchema.ReadTextFileRequest,
+  success: AcpSchema.ReadTextFileResponse,
+  error: AcpSchema.Error,
+});
+
+export const WriteTextFileRpc = Rpc.make(CLIENT_METHODS.fs_write_text_file, {
+  payload: AcpSchema.WriteTextFileRequest,
+  success: AcpSchema.WriteTextFileResponse,
+  error: AcpSchema.Error,
+});
+
+export const RequestPermissionRpc = Rpc.make(CLIENT_METHODS.session_request_permission, {
+  payload: AcpSchema.RequestPermissionRequest,
+  success: AcpSchema.RequestPermissionResponse,
+  error: AcpSchema.Error,
+});
+
+export const ElicitationRpc = Rpc.make(CLIENT_METHODS.session_elicitation, {
+  payload: AcpSchema.ElicitationRequest,
+  success: AcpSchema.ElicitationResponse,
+  error: AcpSchema.Error,
+});
+
+export const CreateTerminalRpc = Rpc.make(CLIENT_METHODS.terminal_create, {
+  payload: AcpSchema.CreateTerminalRequest,
+  success: AcpSchema.CreateTerminalResponse,
+  error: AcpSchema.Error,
+});
+
+export const TerminalOutputRpc = Rpc.make(CLIENT_METHODS.terminal_output, {
+  payload: AcpSchema.TerminalOutputRequest,
+  success: AcpSchema.TerminalOutputResponse,
+  error: AcpSchema.Error,
+});
+
+export const ReleaseTerminalRpc = Rpc.make(CLIENT_METHODS.terminal_release, {
+  payload: AcpSchema.ReleaseTerminalRequest,
+  success: AcpSchema.ReleaseTerminalResponse,
+  error: AcpSchema.Error,
+});
+
+export const WaitForTerminalExitRpc = Rpc.make(CLIENT_METHODS.terminal_wait_for_exit, {
+  payload: AcpSchema.WaitForTerminalExitRequest,
+  success: AcpSchema.WaitForTerminalExitResponse,
+  error: AcpSchema.Error,
+});
+
+export const KillTerminalRpc = Rpc.make(CLIENT_METHODS.terminal_kill, {
+  payload: AcpSchema.KillTerminalRequest,
+  success: AcpSchema.KillTerminalResponse,
+  error: AcpSchema.Error,
+});
+
+export const AgentRpcs = RpcGroup.make(
+  InitializeRpc,
+  AuthenticateRpc,
+  LogoutRpc,
+  NewSessionRpc,
+  LoadSessionRpc,
+  ListSessionsRpc,
+  ForkSessionRpc,
+  ResumeSessionRpc,
+  CloseSessionRpc,
+  PromptRpc,
+  SetSessionModelRpc,
+  SetSessionConfigOptionRpc,
+);
+
+export const ClientRpcs = RpcGroup.make(
+  ReadTextFileRpc,
+  WriteTextFileRpc,
+  RequestPermissionRpc,
+  ElicitationRpc,
+  CreateTerminalRpc,
+  TerminalOutputRpc,
+  ReleaseTerminalRpc,
+  WaitForTerminalExitRpc,
+  KillTerminalRpc,
+);
diff --git a/packages/effect-acp/src/schema.ts b/packages/effect-acp/src/schema.ts
new file mode 100644
index 00000000000..8e354aca370
--- /dev/null
+++ b/packages/effect-acp/src/schema.ts
@@ -0,0 +1,2 @@
+export * from "./_generated/schema.gen.ts";
+export * from "./_generated/meta.gen.ts";
diff --git a/packages/effect-acp/src/terminal.ts b/packages/effect-acp/src/terminal.ts
new file mode 100644
index 00000000000..088ff863738
--- /dev/null
+++ b/packages/effect-acp/src/terminal.ts
@@ -0,0 +1,45 @@
+import * as Effect from "effect/Effect";
+
+import type * as AcpSchema from "./_generated/schema.gen.ts";
+import type * as AcpError from "./errors.ts";
+
+export interface AcpTerminal {
+  readonly sessionId: string;
+  readonly terminalId: string;
+  /** Reads buffered output from the terminal.
+   * Spec: https://agentclientprotocol.com/protocol/schema#terminal/output
+   */
+  readonly output: Effect.Effect<AcpSchema.TerminalOutputResponse, AcpError.AcpError>;
+  /** Waits for terminal exit and returns the exit result.
+   * Spec: https://agentclientprotocol.com/protocol/schema#terminal/wait_for_exit
+   */
+  readonly waitForExit: Effect.Effect<AcpSchema.WaitForTerminalExitResponse, AcpError.AcpError>;
+  /** Terminates the terminal process.
+   * Spec: https://agentclientprotocol.com/protocol/schema#terminal/kill
+   */
+  readonly kill: Effect.Effect<AcpSchema.KillTerminalResponse, AcpError.AcpError>;
+  /** Releases the terminal handle from the ACP session.
+   * Spec: https://agentclientprotocol.com/protocol/schema#terminal/release
+   */
+  readonly release: Effect.Effect<AcpSchema.ReleaseTerminalResponse, AcpError.AcpError>;
+}
+
+export interface MakeTerminalOptions {
+  readonly sessionId: string;
+  readonly terminalId: string;
+  readonly output: Effect.Effect<AcpSchema.TerminalOutputResponse, AcpError.AcpError>;
+  readonly waitForExit: Effect.Effect<AcpSchema.WaitForTerminalExitResponse, AcpError.AcpError>;
+  readonly kill: Effect.Effect<AcpSchema.KillTerminalResponse, AcpError.AcpError>;
+  readonly release: Effect.Effect<AcpSchema.ReleaseTerminalResponse, AcpError.AcpError>;
+}
+
+export function makeTerminal(options: MakeTerminalOptions): AcpTerminal {
+  return {
+    sessionId: options.sessionId,
+    terminalId: options.terminalId,
+    output: options.output,
+    waitForExit: options.waitForExit,
+    kill: options.kill,
+    release: options.release,
+  };
+}
diff --git a/packages/effect-acp/test/examples/cursor-acp-client.example.ts b/packages/effect-acp/test/examples/cursor-acp-client.example.ts
new file mode 100644
index 00000000000..f730c3dbde0
--- /dev/null
+++ b/packages/effect-acp/test/examples/cursor-acp-client.example.ts
@@ -0,0 +1,81 @@
+import * as Effect from "effect/Effect";
+import * as Console from "effect/Console";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+
+import * as AcpClient from "../../src/client.ts";
+
+const program = Effect.gen(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const command = ChildProcess.make("cursor-agent", ["acp"], {
+    cwd: process.cwd(),
+    shell: process.platform === "win32",
+  });
+  const handle = yield* spawner.spawn(command);
+  const acpLayer = AcpClient.layerChildProcess(handle, {
+    logIncoming: true,
+    logOutgoing: true,
+  });
+
+  yield* Effect.gen(function* () {
+    const acp = yield* AcpClient.AcpClient;
+
+    yield* acp.handleRequestPermission(() =>
+      Effect.succeed({
+        outcome: {
+          outcome: "selected",
+          optionId: "allow",
+        },
+      }),
+    );
+    // yield* acp.handleSessionUpdate((notification) =>
+    //   Console.log("session/update", JSON.stringify(notification)),
+    // );
+
+    const initialized = yield* acp.agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+        _meta: {
+          parameterizedModelPicker: true,
+        },
+      },
+      clientInfo: {
+        name: "effect-acp-example",
+        version: "0.0.0",
+      },
+    });
+    yield* Console.log("initialized", initialized);
+
+    const session = yield* acp.agent.createSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+    });
+
+    const config = yield* acp.agent.setSessionConfigOption({
+      sessionId: session.sessionId,
+      configId: "model",
+      value: "claude-opus-4-6",
+    });
+
+    yield* Console.log("config", config);
+
+    const result = yield* acp.agent.prompt({
+      sessionId: session.sessionId,
+      prompt: [
+        {
+          type: "text",
+          text: "Illustrate your ability to create todo lists and then execute all of them. Do not write the list to disk, illustrate your built in ability!",
+        },
+      ],
+    });
+
+    yield* Console.log("prompt result", result);
+    yield* acp.agent.cancel({ sessionId: session.sessionId });
+  }).pipe(Effect.provide(acpLayer));
+});
+
+program.pipe(Effect.scoped, Effect.provide(NodeServices.layer), NodeRuntime.runMain);
diff --git a/packages/effect-acp/test/fixtures/acp-mock-peer.ts b/packages/effect-acp/test/fixtures/acp-mock-peer.ts
new file mode 100644
index 00000000000..7ff88a2c7e0
--- /dev/null
+++ b/packages/effect-acp/test/fixtures/acp-mock-peer.ts
@@ -0,0 +1,136 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+
+import * as AcpAgent from "../../src/agent.ts";
+
+if (process.env.ACP_MOCK_MALFORMED_OUTPUT === "1") {
+  process.stdout.write("{not-json}\n");
+  process.exit(Number(process.env.ACP_MOCK_MALFORMED_OUTPUT_EXIT_CODE ?? "0"));
+}
+
+if (process.env.ACP_MOCK_EXIT_IMMEDIATELY_CODE !== undefined) {
+  process.exit(Number(process.env.ACP_MOCK_EXIT_IMMEDIATELY_CODE));
+}
+
+const sessionId = "mock-session-1";
+
+const program = Effect.gen(function* () {
+  const agent = yield* AcpAgent.AcpAgent;
+
+  yield* agent.handleInitialize(() =>
+    Effect.succeed({
+      protocolVersion: 1,
+      agentCapabilities: {
+        sessionCapabilities: {
+          list: {},
+        },
+      },
+      agentInfo: {
+        name: "mock-agent",
+        version: "0.0.0",
+      },
+    }),
+  );
+
+  yield* agent.handleAuthenticate(() => Effect.succeed({}));
+  yield* agent.handleLogout(() => Effect.succeed({}));
+  yield* agent.handleCreateSession(() =>
+    Effect.succeed({
+      sessionId,
+    }),
+  );
+  yield* agent.handleLoadSession(() => Effect.succeed({}));
+  yield* agent.handleListSessions(() =>
+    Effect.succeed({
+      sessions: [
+        {
+          sessionId,
+          cwd: process.cwd(),
+        },
+      ],
+    }),
+  );
+
+  yield* agent.handlePrompt(() =>
+    Effect.gen(function* () {
+      yield* agent.client.requestPermission({
+        sessionId,
+        options: [
+          {
+            optionId: "allow",
+            name: "Allow",
+            kind: "allow_once",
+          },
+        ],
+        toolCall: {
+          toolCallId: "tool-1",
+          title: "Read project files",
+        },
+      });
+
+      yield* agent.client.elicit({
+        sessionId,
+        message: "Need confirmation before continuing.",
+        mode: "form",
+        requestedSchema: {
+          type: "object",
+          title: "Need confirmation",
+          properties: {
+            approved: {
+              type: "boolean",
+              title: "Approved",
+            },
+          },
+          required: ["approved"],
+        },
+      });
+
+      yield* agent.client.sessionUpdate({
+        sessionId,
+        update: {
+          sessionUpdate: "plan",
+          entries: [
+            {
+              content: "Inspect the repository",
+              priority: "high",
+              status: "in_progress",
+            },
+          ],
+        },
+      });
+
+      yield* agent.client.elicitationComplete({
+        elicitationId: "elicitation-1",
+      });
+
+      yield* agent.client.extRequest("x/typed_request", {
+        message: process.env.ACP_MOCK_BAD_TYPED_REQUEST === "1" ? 123 : "hello from typed request",
+      });
+
+      yield* agent.client.extNotification("x/typed_notification", {
+        count: 2,
+      });
+
+      return {
+        stopReason: "end_turn" as const,
+      };
+    }),
+  );
+
+  yield* agent.handleUnknownExtRequest((method, params) =>
+    Effect.succeed({
+      echoedMethod: method,
+      echoedParams: params ?? null,
+    }),
+  );
+
+  return yield* Effect.never;
+});
+
+program.pipe(
+  Effect.provide(Layer.provide(AcpAgent.layerStdio(), NodeServices.layer)),
+  NodeRuntime.runMain,
+);
diff --git a/packages/effect-acp/tsconfig.json b/packages/effect-acp/tsconfig.json
new file mode 100644
index 00000000000..04f1d37800f
--- /dev/null
+++ b/packages/effect-acp/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": ["src", "scripts", "test"]
+}
diff --git a/packages/effect-codex-app-server/package.json b/packages/effect-codex-app-server/package.json
new file mode 100644
index 00000000000..fb2df244401
--- /dev/null
+++ b/packages/effect-codex-app-server/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "effect-codex-app-server",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./client": {
+      "types": "./src/client.ts",
+      "import": "./src/client.ts"
+    },
+    "./schema": {
+      "types": "./src/schema.ts",
+      "import": "./src/schema.ts"
+    },
+    "./rpc": {
+      "types": "./src/rpc.ts",
+      "import": "./src/rpc.ts"
+    },
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "import": "./src/protocol.ts"
+    },
+    "./errors": {
+      "types": "./src/errors.ts",
+      "import": "./src/errors.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "generate": "bun run scripts/generate.ts",
+    "probe": "bun run test/examples/codex-app-server-probe.ts"
+  },
+  "dependencies": {
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@effect/openapi-generator": "catalog:",
+    "@effect/platform-node": "catalog:",
+    "@effect/vitest": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/packages/effect-codex-app-server/scripts/generate.ts b/packages/effect-codex-app-server/scripts/generate.ts
new file mode 100644
index 00000000000..d12caa3464b
--- /dev/null
+++ b/packages/effect-codex-app-server/scripts/generate.ts
@@ -0,0 +1,775 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { make as makeJsonSchemaGenerator } from "@effect/openapi-generator/JsonSchemaGenerator";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+const UPSTREAM_REF = "07b695190f30a450e4921f71f77473e564395c59";
+const USER_AGENT = "effect-codex-app-server-generator";
+const GITHUB_API_BASE =
+  "https://api.github.com/repos/openai/codex/contents/codex-rs/app-server-protocol";
+
+const GithubContentEntries = Schema.Array(
+  Schema.Struct({
+    name: Schema.String,
+    path: Schema.String,
+    download_url: Schema.NullOr(Schema.String),
+    type: Schema.String,
+  }),
+);
+type GithubContentEntry = (typeof GithubContentEntries.Type)[number];
+
+const JsonSchemaDocument = Schema.StructWithRest(
+  Schema.Struct({
+    definitions: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+  }),
+  [Schema.Record(Schema.String, Schema.Json)],
+);
+const decodeGithubContentEntries = Schema.decodeEffect(Schema.fromJsonString(GithubContentEntries));
+const decodeJsonSchemaDocument = Schema.decodeEffect(Schema.fromJsonString(JsonSchemaDocument));
+
+interface GeneratedPaths {
+  readonly generatedDir: string;
+  readonly schemaOutputPath: string;
+  readonly metaOutputPath: string;
+  readonly namespacesOutputPath: string;
+}
+
+interface MethodEntry {
+  readonly method: string;
+  readonly paramsType?: string;
+}
+
+interface JsonSchemaFile {
+  readonly namespace?: string;
+  readonly exportName: string;
+  readonly fileName: string;
+  readonly downloadUrl: string;
+  readonly qualifiedName: string;
+}
+
+class GeneratorError extends Schema.TaggedErrorClass<GeneratorError>()("GeneratorError", {
+  detail: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+const ManualSchemas: Record<string, typeof Schema.Json.Type> = {
+  GetAuthStatusParams: {
+    type: "object",
+    title: "GetAuthStatusParams",
+    properties: {
+      includeToken: {
+        anyOf: [{ type: "boolean" }, { type: "null" }],
+      },
+      refreshToken: {
+        anyOf: [{ type: "boolean" }, { type: "null" }],
+      },
+    },
+  },
+  GetConversationSummaryParams: {
+    title: "GetConversationSummaryParams",
+    oneOf: [
+      {
+        type: "object",
+        properties: {
+          rolloutPath: { type: "string" },
+        },
+        required: ["rolloutPath"],
+      },
+      {
+        type: "object",
+        properties: {
+          conversationId: { type: "string" },
+        },
+        required: ["conversationId"],
+      },
+    ],
+  },
+  GetConversationSummaryResponse: {
+    type: "object",
+    title: "GetConversationSummaryResponse",
+    properties: {
+      summary: {},
+    },
+    required: ["summary"],
+  },
+  GitDiffToRemoteParams: {
+    type: "object",
+    title: "GitDiffToRemoteParams",
+    properties: {
+      cwd: { type: "string" },
+    },
+    required: ["cwd"],
+  },
+  GitDiffToRemoteResponse: {
+    type: "object",
+    title: "GitDiffToRemoteResponse",
+    properties: {
+      sha: { type: "string" },
+      diff: { type: "string" },
+    },
+    required: ["sha", "diff"],
+  },
+  GetAuthStatusResponse: {
+    type: "object",
+    title: "GetAuthStatusResponse",
+    properties: {
+      authMethod: {
+        anyOf: [{}, { type: "null" }],
+      },
+      authToken: {
+        anyOf: [{ type: "string" }, { type: "null" }],
+      },
+      requiresOpenaiAuth: {
+        anyOf: [{ type: "boolean" }, { type: "null" }],
+      },
+    },
+    required: ["authMethod", "authToken", "requiresOpenaiAuth"],
+  },
+};
+
+const getGeneratedPaths = Effect.fn("getGeneratedPaths")(function* () {
+  const path = yield* Path.Path;
+  const generatedDir = path.join(import.meta.dirname, "..", "src", "_generated");
+  return {
+    generatedDir,
+    schemaOutputPath: path.join(generatedDir, "schema.gen.ts"),
+    metaOutputPath: path.join(generatedDir, "meta.gen.ts"),
+    namespacesOutputPath: path.join(generatedDir, "namespaces.gen.ts"),
+  } satisfies GeneratedPaths;
+});
+
+const ensureGeneratedDir = Effect.fn("ensureGeneratedDir")(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const { generatedDir } = yield* getGeneratedPaths();
+  yield* fs.makeDirectory(generatedDir, { recursive: true });
+});
+
+const fetchText = Effect.fn("fetchText")(function* (url: string) {
+  return yield* HttpClientRequest.get(url).pipe(
+    HttpClientRequest.setHeader("user-agent", USER_AGENT),
+    HttpClient.execute,
+    Effect.flatMap(HttpClientResponse.filterStatusOk),
+    Effect.flatMap((okResponse) => okResponse.text),
+    Effect.mapError(
+      (cause) =>
+        new GeneratorError({
+          detail: `Failed to fetch ${url}`,
+          cause,
+        }),
+    ),
+  );
+});
+
+const fetchDirectoryEntries = Effect.fn("fetchDirectoryEntries")(function* (path: string) {
+  const raw = yield* fetchText(`${GITHUB_API_BASE}/${path}?ref=${UPSTREAM_REF}`);
+  return yield* decodeGithubContentEntries(raw);
+});
+
+function collectSchemaEntries(
+  chunk: string,
+): ReadonlyArray<{ readonly name: string; readonly code: string }> {
+  const lines = chunk
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("//"));
+  const entries: Array<{ name: string; code: string }> = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const typeLine = lines[index];
+    if (!typeLine?.startsWith("export type ")) {
+      continue;
+    }
+
+    const constLine = lines[index + 1];
+    if (!constLine?.startsWith("export const ")) {
+      throw new Error(`Malformed generator output near: ${typeLine}`);
+    }
+
+    const match = /^export type ([A-Za-z0-9_]+)/.exec(typeLine);
+    if (!match?.[1]) {
+      throw new Error(`Could not extract schema name from: ${typeLine}`);
+    }
+
+    entries.push({
+      name: match[1],
+      code: `${typeLine}\n${constLine}`,
+    });
+    index += 1;
+  }
+
+  return entries;
+}
+
+function normalizeNullableTypes(value: typeof Schema.Json.Type): typeof Schema.Json.Type {
+  if (Array.isArray(value)) {
+    return value.map(normalizeNullableTypes);
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  const normalizedEntries = Object.entries(value).map(([key, child]) => [
+    key,
+    normalizeNullableTypes(child),
+  ]);
+  const normalizedObject = Object.fromEntries(normalizedEntries) as Record<
+    string,
+    typeof Schema.Json.Type
+  >;
+  const typeValue = normalizedObject.type;
+
+  if (!Array.isArray(typeValue)) {
+    return normalizedObject;
+  }
+
+  const normalizedTypes = typeValue.filter((entry): entry is string => typeof entry === "string");
+  if (normalizedTypes.length !== typeValue.length || !normalizedTypes.includes("null")) {
+    return normalizedObject;
+  }
+
+  const nonNullTypes = normalizedTypes.filter((entry) => entry !== "null");
+  if (nonNullTypes.length !== 1) {
+    return normalizedObject;
+  }
+  const nonNullType = nonNullTypes[0]!;
+
+  const nextObject: Record<string, typeof Schema.Json.Type> = {};
+  for (const [key, child] of Object.entries(normalizedObject)) {
+    if (key !== "type") {
+      nextObject[key] = child;
+    }
+  }
+
+  return {
+    anyOf: [
+      {
+        ...nextObject,
+        type: nonNullType,
+      },
+      { type: "null" },
+    ],
+  };
+}
+
+function stripNullDefaults(value: typeof Schema.Json.Type): typeof Schema.Json.Type {
+  if (Array.isArray(value)) {
+    return value.map(stripNullDefaults);
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key, child]) => !(key === "default" && child === null))
+      .map(([key, child]) => [key, stripNullDefaults(child)]),
+  ) as typeof Schema.Json.Type;
+}
+
+function toPascalCaseMethod(method: string) {
+  return method
+    .split("/")
+    .flatMap((segment) => segment.split(/(?=[A-Z])/))
+    .flatMap((segment) => segment.split(/[-_]/))
+    .filter(Boolean)
+    .map((segment) => segment[0]!.toUpperCase() + segment.slice(1))
+    .join("");
+}
+
+function parseRequestEntries(fileContents: string): ReadonlyArray<MethodEntry> {
+  const entryPattern = /\{\s*"method":\s*"([^"]+)",\s*id:\s*RequestId,\s*params:\s*([^,}]+)/g;
+  const entries: Array<MethodEntry> = [];
+  let match: RegExpExecArray | null;
+  while ((match = entryPattern.exec(fileContents)) !== null) {
+    entries.push({
+      method: match[1]!,
+      paramsType: match[2]!.trim(),
+    });
+  }
+  return entries;
+}
+
+function parseNotificationEntries(fileContents: string): ReadonlyArray<MethodEntry> {
+  const entryPattern = /\{\s*"method":\s*"([^"]+)"(?:,\s*"params":\s*([^ }]+))?\s*\}/g;
+  const entries: Array<MethodEntry> = [];
+  let match: RegExpExecArray | null;
+  while ((match = entryPattern.exec(fileContents)) !== null) {
+    entries.push({
+      method: match[1]!,
+      ...(match[2] ? { paramsType: match[2].trim() } : {}),
+    });
+  }
+  return entries;
+}
+
+function resolveSchemaTypeName(
+  rawTypeName: string,
+  generatedSchemaNames: ReadonlySet<string>,
+): string {
+  if (rawTypeName === "undefined") {
+    return "undefined";
+  }
+
+  const candidates = [
+    rawTypeName,
+    `V2${rawTypeName}`,
+    `V1${rawTypeName}`,
+    `SerdeJson${rawTypeName}`,
+  ];
+  for (const candidate of candidates) {
+    if (generatedSchemaNames.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`Unable to resolve schema type name: ${rawTypeName}`);
+}
+
+function resolveResponseTypeName(
+  method: string,
+  paramsType: string | undefined,
+  generatedSchemaNames: ReadonlySet<string>,
+): string {
+  const overrides: Record<string, string> = {
+    "account/logout": "LogoutAccountResponse",
+    "account/rateLimits/read": "GetAccountRateLimitsResponse",
+    "config/batchWrite": "ConfigWriteResponse",
+    "config/mcpServer/reload": "McpServerRefreshResponse",
+    "config/value/write": "ConfigWriteResponse",
+    "configRequirements/read": "ConfigRequirementsReadResponse",
+  };
+
+  const override = overrides[method];
+  if (override) {
+    return resolveSchemaTypeName(override, generatedSchemaNames);
+  }
+
+  if (paramsType && paramsType !== "undefined") {
+    const fromParams = paramsType.replace(/Params$/, "Response");
+    try {
+      return resolveSchemaTypeName(fromParams, generatedSchemaNames);
+    } catch {
+      // Fall through to method-based lookup.
+    }
+  }
+
+  return resolveSchemaTypeName(`${toPascalCaseMethod(method)}Response`, generatedSchemaNames);
+}
+
+function renderMethodConstants(constantName: string, entries: ReadonlyArray<MethodEntry>) {
+  return [
+    `export const ${constantName} = {`,
+    ...entries.map(
+      (entry) => `  ${JSON.stringify(entry.method)}: ${JSON.stringify(entry.method)},`,
+    ),
+    "} as const;",
+    "",
+  ].join("\n");
+}
+
+function renderTypeInterface(
+  interfaceName: string,
+  entries: ReadonlyArray<MethodEntry>,
+  typeName: (entry: MethodEntry) => string,
+) {
+  return [
+    `export interface ${interfaceName} {`,
+    ...entries.map((entry) => `  readonly ${JSON.stringify(entry.method)}: ${typeName(entry)};`),
+    "}",
+    "",
+  ].join("\n");
+}
+
+function renderSchemaMap(
+  constantName: string,
+  entries: ReadonlyArray<MethodEntry>,
+  typeName: (entry: MethodEntry) => string,
+) {
+  return [
+    `export const ${constantName} = {`,
+    ...entries.map((entry) => {
+      const schemaName = typeName(entry);
+      return `  ${JSON.stringify(entry.method)}: ${
+        schemaName === "undefined" ? "undefined" : `CodexSchema.${schemaName}`
+      },`;
+    }),
+    "} as const;",
+    "",
+  ].join("\n");
+}
+
+function renderSchemaTypeReference(schemaName: string) {
+  return schemaName === "undefined" ? "undefined" : `typeof CodexSchema.${schemaName}.Type`;
+}
+
+function exportNameForPath(filePath: string): string {
+  const relative = filePath.replace(/^schema\/json\//, "").replace(/\.json$/, "");
+  if (!relative.includes("/")) {
+    return relative;
+  }
+
+  const [namespace, name] = relative.split("/", 2) as [string, string];
+  const namespacePrefix = namespace
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((segment) => segment[0]!.toUpperCase() + segment.slice(1))
+    .join("");
+  return `${namespacePrefix}${name}`;
+}
+
+function buildJsonSchemaFiles(
+  entries: ReadonlyArray<GithubContentEntry>,
+): ReadonlyArray<JsonSchemaFile> {
+  return entries
+    .filter(
+      (entry) =>
+        entry.type === "file" &&
+        entry.name.endsWith(".json") &&
+        entry.download_url !== null &&
+        !entry.name.startsWith("codex_app_server_protocol."),
+    )
+    .map((entry) => {
+      const relative = entry.path.replace(/^codex-rs\/app-server-protocol\/schema\/json\//, "");
+      const parts = relative.split("/");
+      if (parts.length > 1) {
+        return {
+          namespace: parts[0]!,
+          exportName: exportNameForPath(relative),
+          fileName: entry.name,
+          downloadUrl: entry.download_url!,
+          qualifiedName: relative.replace(/\.json$/, ""),
+        } satisfies JsonSchemaFile;
+      }
+      return {
+        exportName: exportNameForPath(relative),
+        fileName: entry.name,
+        downloadUrl: entry.download_url!,
+        qualifiedName: relative.replace(/\.json$/, ""),
+      } satisfies JsonSchemaFile;
+    });
+}
+
+function rewriteExternalRefs(
+  value: typeof Schema.Json.Type,
+  localDefinitionNames: ReadonlyMap<string, string>,
+  currentNamespace: string | undefined,
+  exportNameByQualifiedName: ReadonlyMap<string, string>,
+): typeof Schema.Json.Type {
+  if (Array.isArray(value)) {
+    return value.map((entry) =>
+      rewriteExternalRefs(entry, localDefinitionNames, currentNamespace, exportNameByQualifiedName),
+    );
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => {
+      if (key === "$ref" && typeof child === "string" && child.startsWith("#/definitions/")) {
+        const definitionName = child.slice("#/definitions/".length);
+        const localRewrite = localDefinitionNames.get(definitionName);
+        if (localRewrite) {
+          return [key, `#/definitions/${localRewrite}`];
+        }
+
+        const candidates = [
+          ...(currentNamespace ? [`${currentNamespace}/${definitionName}`] : []),
+          definitionName,
+          definitionName.replace(/^v[12]\//, ""),
+          definitionName.replace(/^serde_json\//, ""),
+          `v2/${definitionName}`,
+          `v1/${definitionName}`,
+          `serde_json/${definitionName}`,
+        ];
+
+        const rewritten = candidates
+          .map((candidate) => exportNameByQualifiedName.get(candidate))
+          .find((candidate) => candidate !== undefined);
+
+        if (!rewritten) {
+          throw new Error(`Missing rewritten definition for ref: ${child}`);
+        }
+
+        return [key, `#/definitions/${rewritten}`];
+      }
+
+      return [
+        key,
+        rewriteExternalRefs(
+          child,
+          localDefinitionNames,
+          currentNamespace,
+          exportNameByQualifiedName,
+        ),
+      ];
+    }),
+  ) as typeof Schema.Json.Type;
+}
+
+const generateFiles = Effect.fn("generateFiles")(function* () {
+  yield* ensureGeneratedDir();
+
+  const [rootJsonEntries, v1JsonEntries, v2JsonEntries] = yield* Effect.all([
+    fetchDirectoryEntries("schema/json"),
+    fetchDirectoryEntries("schema/json/v1"),
+    fetchDirectoryEntries("schema/json/v2"),
+  ]);
+
+  const jsonSchemaFiles = [
+    ...buildJsonSchemaFiles(rootJsonEntries),
+    ...buildJsonSchemaFiles(v1JsonEntries),
+    ...buildJsonSchemaFiles(v2JsonEntries),
+  ].toSorted((left, right) => left.exportName.localeCompare(right.exportName));
+
+  const exportNameByQualifiedName = new Map(
+    jsonSchemaFiles.map((file) => [file.qualifiedName, file.exportName]),
+  );
+  const aggregateSchemas: Record<string, typeof Schema.Json.Type> = {};
+
+  for (const file of jsonSchemaFiles) {
+    const raw = yield* fetchText(file.downloadUrl);
+    const parsed = yield* decodeJsonSchemaDocument(raw);
+    const localDefinitionNames = new Map(
+      Object.keys(parsed.definitions ?? {}).map((definitionName) => [
+        definitionName,
+        `${file.exportName}__${definitionName.replace(/[^A-Za-z0-9]/g, "")}`,
+      ]),
+    );
+
+    for (const [definitionName, definitionSchema] of Object.entries(parsed.definitions ?? {})) {
+      aggregateSchemas[localDefinitionNames.get(definitionName)!] = stripNullDefaults(
+        normalizeNullableTypes(
+          rewriteExternalRefs(
+            definitionSchema,
+            localDefinitionNames,
+            file.namespace,
+            exportNameByQualifiedName,
+          ),
+        ),
+      );
+    }
+
+    const topLevelSchema: Record<string, typeof Schema.Json.Type> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (key !== "definitions") {
+        topLevelSchema[key] = value;
+      }
+    }
+
+    aggregateSchemas[file.exportName] = stripNullDefaults(
+      normalizeNullableTypes(
+        rewriteExternalRefs(
+          topLevelSchema,
+          localDefinitionNames,
+          file.namespace,
+          exportNameByQualifiedName,
+        ),
+      ),
+    );
+  }
+
+  for (const [name, schema] of Object.entries(ManualSchemas)) {
+    if (!(name in aggregateSchemas)) {
+      aggregateSchemas[name] = stripNullDefaults(normalizeNullableTypes(schema));
+    }
+  }
+
+  const generator = makeJsonSchemaGenerator();
+  for (const [name, schema] of Object.entries(aggregateSchemas).toSorted(([left], [right]) =>
+    left.localeCompare(right),
+  )) {
+    generator.addSchema(name, schema as never);
+  }
+
+  const generatedEntries = new Map<string, string>();
+  const output = generator.generate("openapi-3.1", aggregateSchemas as never, false).trim();
+  if (output.length > 0) {
+    for (const entry of collectSchemaEntries(output)) {
+      if (!generatedEntries.has(entry.name)) {
+        generatedEntries.set(entry.name, entry.code);
+      }
+    }
+  }
+
+  const generatedSchemaNames = new Set(generatedEntries.keys());
+  const clientRequestRaw = yield* fetchText(
+    `https://raw.githubusercontent.com/openai/codex/${UPSTREAM_REF}/codex-rs/app-server-protocol/schema/typescript/ClientRequest.ts`,
+  );
+  const clientNotificationRaw = yield* fetchText(
+    `https://raw.githubusercontent.com/openai/codex/${UPSTREAM_REF}/codex-rs/app-server-protocol/schema/typescript/ClientNotification.ts`,
+  );
+  const serverRequestRaw = yield* fetchText(
+    `https://raw.githubusercontent.com/openai/codex/${UPSTREAM_REF}/codex-rs/app-server-protocol/schema/typescript/ServerRequest.ts`,
+  );
+  const serverNotificationRaw = yield* fetchText(
+    `https://raw.githubusercontent.com/openai/codex/${UPSTREAM_REF}/codex-rs/app-server-protocol/schema/typescript/ServerNotification.ts`,
+  );
+
+  const clientRequestEntries = parseRequestEntries(clientRequestRaw);
+  const clientNotificationEntries = parseNotificationEntries(clientNotificationRaw);
+  const serverRequestEntries = parseRequestEntries(serverRequestRaw);
+  const serverNotificationEntries = parseNotificationEntries(serverNotificationRaw);
+
+  const prelude = [
+    "// This file is generated by the effect-codex-app-server package. Do not edit manually.",
+    `// Upstream protocol ref: ${UPSTREAM_REF}`,
+    "",
+  ];
+
+  const schemaOutput = [
+    ...prelude,
+    'import * as Schema from "effect/Schema";',
+    "",
+    [...generatedEntries.values()].join("\n\n"),
+    "",
+  ].join("\n");
+
+  const metaOutput = [
+    ...prelude,
+    'import * as CodexSchema from "./schema.gen.ts";',
+    "",
+    renderMethodConstants("CLIENT_REQUEST_METHODS", clientRequestEntries),
+    renderMethodConstants("CLIENT_NOTIFICATION_METHODS", clientNotificationEntries),
+    renderMethodConstants("SERVER_REQUEST_METHODS", serverRequestEntries),
+    renderMethodConstants("SERVER_NOTIFICATION_METHODS", serverNotificationEntries),
+    "export type ClientRequestMethod = keyof typeof CLIENT_REQUEST_METHODS;",
+    "export type ClientNotificationMethod = keyof typeof CLIENT_NOTIFICATION_METHODS;",
+    "export type ServerRequestMethod = keyof typeof SERVER_REQUEST_METHODS;",
+    "export type ServerNotificationMethod = keyof typeof SERVER_NOTIFICATION_METHODS;",
+    "",
+    renderTypeInterface("ClientRequestParamsByMethod", clientRequestEntries, (entry) =>
+      renderSchemaTypeReference(
+        resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+      ),
+    ),
+    renderTypeInterface("ClientRequestResponsesByMethod", clientRequestEntries, (entry) =>
+      renderSchemaTypeReference(
+        resolveResponseTypeName(entry.method, entry.paramsType, generatedSchemaNames),
+      ),
+    ),
+    renderTypeInterface("ClientNotificationParamsByMethod", clientNotificationEntries, (entry) =>
+      renderSchemaTypeReference(
+        resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+      ),
+    ),
+    renderTypeInterface("ServerRequestParamsByMethod", serverRequestEntries, (entry) =>
+      renderSchemaTypeReference(
+        resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+      ),
+    ),
+    renderTypeInterface("ServerRequestResponsesByMethod", serverRequestEntries, (entry) =>
+      renderSchemaTypeReference(
+        resolveResponseTypeName(entry.method, entry.paramsType, generatedSchemaNames),
+      ),
+    ),
+    renderTypeInterface("ServerNotificationParamsByMethod", serverNotificationEntries, (entry) =>
+      renderSchemaTypeReference(
+        resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+      ),
+    ),
+    renderSchemaMap("CLIENT_REQUEST_PARAMS", clientRequestEntries, (entry) =>
+      resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+    ),
+    renderSchemaMap("CLIENT_REQUEST_RESPONSES", clientRequestEntries, (entry) =>
+      resolveResponseTypeName(entry.method, entry.paramsType, generatedSchemaNames),
+    ),
+    renderSchemaMap("CLIENT_NOTIFICATION_PARAMS", clientNotificationEntries, (entry) =>
+      resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+    ),
+    renderSchemaMap("SERVER_REQUEST_PARAMS", serverRequestEntries, (entry) =>
+      resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+    ),
+    renderSchemaMap("SERVER_REQUEST_RESPONSES", serverRequestEntries, (entry) =>
+      resolveResponseTypeName(entry.method, entry.paramsType, generatedSchemaNames),
+    ),
+    renderSchemaMap("SERVER_NOTIFICATION_PARAMS", serverNotificationEntries, (entry) =>
+      resolveSchemaTypeName(entry.paramsType ?? "undefined", generatedSchemaNames),
+    ),
+  ].join("\n");
+
+  const namespaceGroups = new Map<string, Array<JsonSchemaFile>>();
+  for (const file of jsonSchemaFiles) {
+    if (!file.namespace) {
+      continue;
+    }
+    const current = namespaceGroups.get(file.namespace) ?? [];
+    current.push(file);
+    namespaceGroups.set(file.namespace, current);
+  }
+
+  const namespacesOutput = [
+    ...prelude,
+    'import * as CodexSchema from "./schema.gen.ts";',
+    "",
+    ...[...namespaceGroups.entries()]
+      .toSorted(([left], [right]) => left.localeCompare(right))
+      .map(([namespace, files]) => {
+        const constantName = namespace.replace(/[^A-Za-z0-9]/g, "");
+        return [
+          `export const ${constantName} = {`,
+          ...files
+            .toSorted((left, right) => left.fileName.localeCompare(right.fileName))
+            .map(
+              (file) =>
+                `  ${JSON.stringify(file.fileName.replace(/\.json$/, ""))}: CodexSchema.${file.exportName},`,
+            ),
+          "} as const;",
+          "",
+        ].join("\n");
+      }),
+  ].join("\n");
+
+  const fs = yield* FileSystem.FileSystem;
+  const { generatedDir, metaOutputPath, namespacesOutputPath, schemaOutputPath } =
+    yield* getGeneratedPaths();
+  yield* fs.writeFileString(schemaOutputPath, schemaOutput);
+  yield* fs.writeFileString(metaOutputPath, metaOutput);
+  yield* fs.writeFileString(namespacesOutputPath, namespacesOutput);
+
+  yield* Effect.log(`Generated Codex App Server schemas from ${UPSTREAM_REF}`);
+
+  yield* Effect.service(ChildProcessSpawner.ChildProcessSpawner).pipe(
+    Effect.flatMap((spawner) => spawner.spawn(ChildProcess.make("bun", ["oxfmt", generatedDir]))),
+    Effect.flatMap((child) => child.exitCode),
+    Effect.tap((code) =>
+      code === 0
+        ? Effect.void
+        : Effect.fail(
+            new GeneratorError({
+              detail: `oxfmt failed with exit code ${code}`,
+            }),
+          ),
+    ),
+  );
+});
+
+generateFiles().pipe(
+  Effect.scoped,
+  Effect.provide(
+    Layer.mergeAll(
+      Logger.layer([Logger.consolePretty()]),
+      NodeServices.layer,
+      FetchHttpClient.layer,
+    ),
+  ),
+  NodeRuntime.runMain,
+);
diff --git a/packages/effect-codex-app-server/src/_generated/meta.gen.ts b/packages/effect-codex-app-server/src/_generated/meta.gen.ts
new file mode 100644
index 00000000000..b6c0b00d1c2
--- /dev/null
+++ b/packages/effect-codex-app-server/src/_generated/meta.gen.ts
@@ -0,0 +1,689 @@
+// This file is generated by the effect-codex-app-server package. Do not edit manually.
+// Upstream protocol ref: 07b695190f30a450e4921f71f77473e564395c59
+
+import * as CodexSchema from "./schema.gen.ts";
+
+export const CLIENT_REQUEST_METHODS = {
+  initialize: "initialize",
+  "thread/start": "thread/start",
+  "thread/resume": "thread/resume",
+  "thread/fork": "thread/fork",
+  "thread/archive": "thread/archive",
+  "thread/unsubscribe": "thread/unsubscribe",
+  "thread/name/set": "thread/name/set",
+  "thread/metadata/update": "thread/metadata/update",
+  "thread/unarchive": "thread/unarchive",
+  "thread/compact/start": "thread/compact/start",
+  "thread/shellCommand": "thread/shellCommand",
+  "thread/approveGuardianDeniedAction": "thread/approveGuardianDeniedAction",
+  "thread/rollback": "thread/rollback",
+  "thread/list": "thread/list",
+  "thread/loaded/list": "thread/loaded/list",
+  "thread/read": "thread/read",
+  "thread/inject_items": "thread/inject_items",
+  "skills/list": "skills/list",
+  "hooks/list": "hooks/list",
+  "marketplace/add": "marketplace/add",
+  "marketplace/remove": "marketplace/remove",
+  "marketplace/upgrade": "marketplace/upgrade",
+  "plugin/list": "plugin/list",
+  "plugin/read": "plugin/read",
+  "plugin/skill/read": "plugin/skill/read",
+  "plugin/share/save": "plugin/share/save",
+  "plugin/share/updateTargets": "plugin/share/updateTargets",
+  "plugin/share/list": "plugin/share/list",
+  "plugin/share/delete": "plugin/share/delete",
+  "app/list": "app/list",
+  "fs/readFile": "fs/readFile",
+  "fs/writeFile": "fs/writeFile",
+  "fs/createDirectory": "fs/createDirectory",
+  "fs/getMetadata": "fs/getMetadata",
+  "fs/readDirectory": "fs/readDirectory",
+  "fs/remove": "fs/remove",
+  "fs/copy": "fs/copy",
+  "fs/watch": "fs/watch",
+  "fs/unwatch": "fs/unwatch",
+  "skills/config/write": "skills/config/write",
+  "plugin/install": "plugin/install",
+  "plugin/uninstall": "plugin/uninstall",
+  "turn/start": "turn/start",
+  "turn/steer": "turn/steer",
+  "turn/interrupt": "turn/interrupt",
+  "review/start": "review/start",
+  "model/list": "model/list",
+  "modelProvider/capabilities/read": "modelProvider/capabilities/read",
+  "experimentalFeature/list": "experimentalFeature/list",
+  "experimentalFeature/enablement/set": "experimentalFeature/enablement/set",
+  "mcpServer/oauth/login": "mcpServer/oauth/login",
+  "config/mcpServer/reload": "config/mcpServer/reload",
+  "mcpServerStatus/list": "mcpServerStatus/list",
+  "mcpServer/resource/read": "mcpServer/resource/read",
+  "mcpServer/tool/call": "mcpServer/tool/call",
+  "windowsSandbox/setupStart": "windowsSandbox/setupStart",
+  "windowsSandbox/readiness": "windowsSandbox/readiness",
+  "account/login/start": "account/login/start",
+  "account/login/cancel": "account/login/cancel",
+  "account/logout": "account/logout",
+  "account/rateLimits/read": "account/rateLimits/read",
+  "account/sendAddCreditsNudgeEmail": "account/sendAddCreditsNudgeEmail",
+  "feedback/upload": "feedback/upload",
+  "command/exec": "command/exec",
+  "command/exec/write": "command/exec/write",
+  "command/exec/terminate": "command/exec/terminate",
+  "command/exec/resize": "command/exec/resize",
+  "config/read": "config/read",
+  "externalAgentConfig/detect": "externalAgentConfig/detect",
+  "externalAgentConfig/import": "externalAgentConfig/import",
+  "config/value/write": "config/value/write",
+  "config/batchWrite": "config/batchWrite",
+  "configRequirements/read": "configRequirements/read",
+  "account/read": "account/read",
+  getConversationSummary: "getConversationSummary",
+  gitDiffToRemote: "gitDiffToRemote",
+  getAuthStatus: "getAuthStatus",
+  fuzzyFileSearch: "fuzzyFileSearch",
+} as const;
+
+export const CLIENT_NOTIFICATION_METHODS = {
+  initialized: "initialized",
+} as const;
+
+export const SERVER_REQUEST_METHODS = {
+  "item/commandExecution/requestApproval": "item/commandExecution/requestApproval",
+  "item/fileChange/requestApproval": "item/fileChange/requestApproval",
+  "item/tool/requestUserInput": "item/tool/requestUserInput",
+  "mcpServer/elicitation/request": "mcpServer/elicitation/request",
+  "item/permissions/requestApproval": "item/permissions/requestApproval",
+  "item/tool/call": "item/tool/call",
+  "account/chatgptAuthTokens/refresh": "account/chatgptAuthTokens/refresh",
+  applyPatchApproval: "applyPatchApproval",
+  execCommandApproval: "execCommandApproval",
+} as const;
+
+export const SERVER_NOTIFICATION_METHODS = {
+  error: "error",
+  "thread/started": "thread/started",
+  "thread/status/changed": "thread/status/changed",
+  "thread/archived": "thread/archived",
+  "thread/unarchived": "thread/unarchived",
+  "thread/closed": "thread/closed",
+  "skills/changed": "skills/changed",
+  "thread/name/updated": "thread/name/updated",
+  "thread/goal/updated": "thread/goal/updated",
+  "thread/goal/cleared": "thread/goal/cleared",
+  "thread/tokenUsage/updated": "thread/tokenUsage/updated",
+  "turn/started": "turn/started",
+  "hook/started": "hook/started",
+  "turn/completed": "turn/completed",
+  "hook/completed": "hook/completed",
+  "turn/diff/updated": "turn/diff/updated",
+  "turn/plan/updated": "turn/plan/updated",
+  "item/started": "item/started",
+  "item/autoApprovalReview/started": "item/autoApprovalReview/started",
+  "item/autoApprovalReview/completed": "item/autoApprovalReview/completed",
+  "item/completed": "item/completed",
+  "rawResponseItem/completed": "rawResponseItem/completed",
+  "item/agentMessage/delta": "item/agentMessage/delta",
+  "item/plan/delta": "item/plan/delta",
+  "command/exec/outputDelta": "command/exec/outputDelta",
+  "process/outputDelta": "process/outputDelta",
+  "process/exited": "process/exited",
+  "item/commandExecution/outputDelta": "item/commandExecution/outputDelta",
+  "item/commandExecution/terminalInteraction": "item/commandExecution/terminalInteraction",
+  "item/fileChange/outputDelta": "item/fileChange/outputDelta",
+  "item/fileChange/patchUpdated": "item/fileChange/patchUpdated",
+  "serverRequest/resolved": "serverRequest/resolved",
+  "item/mcpToolCall/progress": "item/mcpToolCall/progress",
+  "mcpServer/oauthLogin/completed": "mcpServer/oauthLogin/completed",
+  "mcpServer/startupStatus/updated": "mcpServer/startupStatus/updated",
+  "account/updated": "account/updated",
+  "account/rateLimits/updated": "account/rateLimits/updated",
+  "app/list/updated": "app/list/updated",
+  "remoteControl/status/changed": "remoteControl/status/changed",
+  "externalAgentConfig/import/completed": "externalAgentConfig/import/completed",
+  "fs/changed": "fs/changed",
+  "item/reasoning/summaryTextDelta": "item/reasoning/summaryTextDelta",
+  "item/reasoning/summaryPartAdded": "item/reasoning/summaryPartAdded",
+  "item/reasoning/textDelta": "item/reasoning/textDelta",
+  "thread/compacted": "thread/compacted",
+  "model/rerouted": "model/rerouted",
+  "model/verification": "model/verification",
+  warning: "warning",
+  guardianWarning: "guardianWarning",
+  deprecationNotice: "deprecationNotice",
+  configWarning: "configWarning",
+  "fuzzyFileSearch/sessionUpdated": "fuzzyFileSearch/sessionUpdated",
+  "fuzzyFileSearch/sessionCompleted": "fuzzyFileSearch/sessionCompleted",
+  "thread/realtime/started": "thread/realtime/started",
+  "thread/realtime/itemAdded": "thread/realtime/itemAdded",
+  "thread/realtime/transcript/delta": "thread/realtime/transcript/delta",
+  "thread/realtime/transcript/done": "thread/realtime/transcript/done",
+  "thread/realtime/outputAudio/delta": "thread/realtime/outputAudio/delta",
+  "thread/realtime/sdp": "thread/realtime/sdp",
+  "thread/realtime/error": "thread/realtime/error",
+  "thread/realtime/closed": "thread/realtime/closed",
+  "windows/worldWritableWarning": "windows/worldWritableWarning",
+  "windowsSandbox/setupCompleted": "windowsSandbox/setupCompleted",
+  "account/login/completed": "account/login/completed",
+} as const;
+
+export type ClientRequestMethod = keyof typeof CLIENT_REQUEST_METHODS;
+export type ClientNotificationMethod = keyof typeof CLIENT_NOTIFICATION_METHODS;
+export type ServerRequestMethod = keyof typeof SERVER_REQUEST_METHODS;
+export type ServerNotificationMethod = keyof typeof SERVER_NOTIFICATION_METHODS;
+
+export interface ClientRequestParamsByMethod {
+  readonly initialize: typeof CodexSchema.V1InitializeParams.Type;
+  readonly "thread/start": typeof CodexSchema.V2ThreadStartParams.Type;
+  readonly "thread/resume": typeof CodexSchema.V2ThreadResumeParams.Type;
+  readonly "thread/fork": typeof CodexSchema.V2ThreadForkParams.Type;
+  readonly "thread/archive": typeof CodexSchema.V2ThreadArchiveParams.Type;
+  readonly "thread/unsubscribe": typeof CodexSchema.V2ThreadUnsubscribeParams.Type;
+  readonly "thread/name/set": typeof CodexSchema.V2ThreadSetNameParams.Type;
+  readonly "thread/metadata/update": typeof CodexSchema.V2ThreadMetadataUpdateParams.Type;
+  readonly "thread/unarchive": typeof CodexSchema.V2ThreadUnarchiveParams.Type;
+  readonly "thread/compact/start": typeof CodexSchema.V2ThreadCompactStartParams.Type;
+  readonly "thread/shellCommand": typeof CodexSchema.V2ThreadShellCommandParams.Type;
+  readonly "thread/approveGuardianDeniedAction": typeof CodexSchema.V2ThreadApproveGuardianDeniedActionParams.Type;
+  readonly "thread/rollback": typeof CodexSchema.V2ThreadRollbackParams.Type;
+  readonly "thread/list": typeof CodexSchema.V2ThreadListParams.Type;
+  readonly "thread/loaded/list": typeof CodexSchema.V2ThreadLoadedListParams.Type;
+  readonly "thread/read": typeof CodexSchema.V2ThreadReadParams.Type;
+  readonly "thread/inject_items": typeof CodexSchema.V2ThreadInjectItemsParams.Type;
+  readonly "skills/list": typeof CodexSchema.V2SkillsListParams.Type;
+  readonly "hooks/list": typeof CodexSchema.V2HooksListParams.Type;
+  readonly "marketplace/add": typeof CodexSchema.V2MarketplaceAddParams.Type;
+  readonly "marketplace/remove": typeof CodexSchema.V2MarketplaceRemoveParams.Type;
+  readonly "marketplace/upgrade": typeof CodexSchema.V2MarketplaceUpgradeParams.Type;
+  readonly "plugin/list": typeof CodexSchema.V2PluginListParams.Type;
+  readonly "plugin/read": typeof CodexSchema.V2PluginReadParams.Type;
+  readonly "plugin/skill/read": typeof CodexSchema.V2PluginSkillReadParams.Type;
+  readonly "plugin/share/save": typeof CodexSchema.V2PluginShareSaveParams.Type;
+  readonly "plugin/share/updateTargets": typeof CodexSchema.V2PluginShareUpdateTargetsParams.Type;
+  readonly "plugin/share/list": typeof CodexSchema.V2PluginShareListParams.Type;
+  readonly "plugin/share/delete": typeof CodexSchema.V2PluginShareDeleteParams.Type;
+  readonly "app/list": typeof CodexSchema.V2AppsListParams.Type;
+  readonly "fs/readFile": typeof CodexSchema.V2FsReadFileParams.Type;
+  readonly "fs/writeFile": typeof CodexSchema.V2FsWriteFileParams.Type;
+  readonly "fs/createDirectory": typeof CodexSchema.V2FsCreateDirectoryParams.Type;
+  readonly "fs/getMetadata": typeof CodexSchema.V2FsGetMetadataParams.Type;
+  readonly "fs/readDirectory": typeof CodexSchema.V2FsReadDirectoryParams.Type;
+  readonly "fs/remove": typeof CodexSchema.V2FsRemoveParams.Type;
+  readonly "fs/copy": typeof CodexSchema.V2FsCopyParams.Type;
+  readonly "fs/watch": typeof CodexSchema.V2FsWatchParams.Type;
+  readonly "fs/unwatch": typeof CodexSchema.V2FsUnwatchParams.Type;
+  readonly "skills/config/write": typeof CodexSchema.V2SkillsConfigWriteParams.Type;
+  readonly "plugin/install": typeof CodexSchema.V2PluginInstallParams.Type;
+  readonly "plugin/uninstall": typeof CodexSchema.V2PluginUninstallParams.Type;
+  readonly "turn/start": typeof CodexSchema.V2TurnStartParams.Type;
+  readonly "turn/steer": typeof CodexSchema.V2TurnSteerParams.Type;
+  readonly "turn/interrupt": typeof CodexSchema.V2TurnInterruptParams.Type;
+  readonly "review/start": typeof CodexSchema.V2ReviewStartParams.Type;
+  readonly "model/list": typeof CodexSchema.V2ModelListParams.Type;
+  readonly "modelProvider/capabilities/read": typeof CodexSchema.V2ModelProviderCapabilitiesReadParams.Type;
+  readonly "experimentalFeature/list": typeof CodexSchema.V2ExperimentalFeatureListParams.Type;
+  readonly "experimentalFeature/enablement/set": typeof CodexSchema.V2ExperimentalFeatureEnablementSetParams.Type;
+  readonly "mcpServer/oauth/login": typeof CodexSchema.V2McpServerOauthLoginParams.Type;
+  readonly "config/mcpServer/reload": undefined;
+  readonly "mcpServerStatus/list": typeof CodexSchema.V2ListMcpServerStatusParams.Type;
+  readonly "mcpServer/resource/read": typeof CodexSchema.V2McpResourceReadParams.Type;
+  readonly "mcpServer/tool/call": typeof CodexSchema.V2McpServerToolCallParams.Type;
+  readonly "windowsSandbox/setupStart": typeof CodexSchema.V2WindowsSandboxSetupStartParams.Type;
+  readonly "windowsSandbox/readiness": undefined;
+  readonly "account/login/start": typeof CodexSchema.V2LoginAccountParams.Type;
+  readonly "account/login/cancel": typeof CodexSchema.V2CancelLoginAccountParams.Type;
+  readonly "account/logout": undefined;
+  readonly "account/rateLimits/read": undefined;
+  readonly "account/sendAddCreditsNudgeEmail": typeof CodexSchema.V2SendAddCreditsNudgeEmailParams.Type;
+  readonly "feedback/upload": typeof CodexSchema.V2FeedbackUploadParams.Type;
+  readonly "command/exec": typeof CodexSchema.V2CommandExecParams.Type;
+  readonly "command/exec/write": typeof CodexSchema.V2CommandExecWriteParams.Type;
+  readonly "command/exec/terminate": typeof CodexSchema.V2CommandExecTerminateParams.Type;
+  readonly "command/exec/resize": typeof CodexSchema.V2CommandExecResizeParams.Type;
+  readonly "config/read": typeof CodexSchema.V2ConfigReadParams.Type;
+  readonly "externalAgentConfig/detect": typeof CodexSchema.V2ExternalAgentConfigDetectParams.Type;
+  readonly "externalAgentConfig/import": typeof CodexSchema.V2ExternalAgentConfigImportParams.Type;
+  readonly "config/value/write": typeof CodexSchema.V2ConfigValueWriteParams.Type;
+  readonly "config/batchWrite": typeof CodexSchema.V2ConfigBatchWriteParams.Type;
+  readonly "configRequirements/read": undefined;
+  readonly "account/read": typeof CodexSchema.V2GetAccountParams.Type;
+  readonly getConversationSummary: typeof CodexSchema.GetConversationSummaryParams.Type;
+  readonly gitDiffToRemote: typeof CodexSchema.GitDiffToRemoteParams.Type;
+  readonly getAuthStatus: typeof CodexSchema.GetAuthStatusParams.Type;
+  readonly fuzzyFileSearch: typeof CodexSchema.FuzzyFileSearchParams.Type;
+}
+
+export interface ClientRequestResponsesByMethod {
+  readonly initialize: typeof CodexSchema.V1InitializeResponse.Type;
+  readonly "thread/start": typeof CodexSchema.V2ThreadStartResponse.Type;
+  readonly "thread/resume": typeof CodexSchema.V2ThreadResumeResponse.Type;
+  readonly "thread/fork": typeof CodexSchema.V2ThreadForkResponse.Type;
+  readonly "thread/archive": typeof CodexSchema.V2ThreadArchiveResponse.Type;
+  readonly "thread/unsubscribe": typeof CodexSchema.V2ThreadUnsubscribeResponse.Type;
+  readonly "thread/name/set": typeof CodexSchema.V2ThreadSetNameResponse.Type;
+  readonly "thread/metadata/update": typeof CodexSchema.V2ThreadMetadataUpdateResponse.Type;
+  readonly "thread/unarchive": typeof CodexSchema.V2ThreadUnarchiveResponse.Type;
+  readonly "thread/compact/start": typeof CodexSchema.V2ThreadCompactStartResponse.Type;
+  readonly "thread/shellCommand": typeof CodexSchema.V2ThreadShellCommandResponse.Type;
+  readonly "thread/approveGuardianDeniedAction": typeof CodexSchema.V2ThreadApproveGuardianDeniedActionResponse.Type;
+  readonly "thread/rollback": typeof CodexSchema.V2ThreadRollbackResponse.Type;
+  readonly "thread/list": typeof CodexSchema.V2ThreadListResponse.Type;
+  readonly "thread/loaded/list": typeof CodexSchema.V2ThreadLoadedListResponse.Type;
+  readonly "thread/read": typeof CodexSchema.V2ThreadReadResponse.Type;
+  readonly "thread/inject_items": typeof CodexSchema.V2ThreadInjectItemsResponse.Type;
+  readonly "skills/list": typeof CodexSchema.V2SkillsListResponse.Type;
+  readonly "hooks/list": typeof CodexSchema.V2HooksListResponse.Type;
+  readonly "marketplace/add": typeof CodexSchema.V2MarketplaceAddResponse.Type;
+  readonly "marketplace/remove": typeof CodexSchema.V2MarketplaceRemoveResponse.Type;
+  readonly "marketplace/upgrade": typeof CodexSchema.V2MarketplaceUpgradeResponse.Type;
+  readonly "plugin/list": typeof CodexSchema.V2PluginListResponse.Type;
+  readonly "plugin/read": typeof CodexSchema.V2PluginReadResponse.Type;
+  readonly "plugin/skill/read": typeof CodexSchema.V2PluginSkillReadResponse.Type;
+  readonly "plugin/share/save": typeof CodexSchema.V2PluginShareSaveResponse.Type;
+  readonly "plugin/share/updateTargets": typeof CodexSchema.V2PluginShareUpdateTargetsResponse.Type;
+  readonly "plugin/share/list": typeof CodexSchema.V2PluginShareListResponse.Type;
+  readonly "plugin/share/delete": typeof CodexSchema.V2PluginShareDeleteResponse.Type;
+  readonly "app/list": typeof CodexSchema.V2AppsListResponse.Type;
+  readonly "fs/readFile": typeof CodexSchema.V2FsReadFileResponse.Type;
+  readonly "fs/writeFile": typeof CodexSchema.V2FsWriteFileResponse.Type;
+  readonly "fs/createDirectory": typeof CodexSchema.V2FsCreateDirectoryResponse.Type;
+  readonly "fs/getMetadata": typeof CodexSchema.V2FsGetMetadataResponse.Type;
+  readonly "fs/readDirectory": typeof CodexSchema.V2FsReadDirectoryResponse.Type;
+  readonly "fs/remove": typeof CodexSchema.V2FsRemoveResponse.Type;
+  readonly "fs/copy": typeof CodexSchema.V2FsCopyResponse.Type;
+  readonly "fs/watch": typeof CodexSchema.V2FsWatchResponse.Type;
+  readonly "fs/unwatch": typeof CodexSchema.V2FsUnwatchResponse.Type;
+  readonly "skills/config/write": typeof CodexSchema.V2SkillsConfigWriteResponse.Type;
+  readonly "plugin/install": typeof CodexSchema.V2PluginInstallResponse.Type;
+  readonly "plugin/uninstall": typeof CodexSchema.V2PluginUninstallResponse.Type;
+  readonly "turn/start": typeof CodexSchema.V2TurnStartResponse.Type;
+  readonly "turn/steer": typeof CodexSchema.V2TurnSteerResponse.Type;
+  readonly "turn/interrupt": typeof CodexSchema.V2TurnInterruptResponse.Type;
+  readonly "review/start": typeof CodexSchema.V2ReviewStartResponse.Type;
+  readonly "model/list": typeof CodexSchema.V2ModelListResponse.Type;
+  readonly "modelProvider/capabilities/read": typeof CodexSchema.V2ModelProviderCapabilitiesReadResponse.Type;
+  readonly "experimentalFeature/list": typeof CodexSchema.V2ExperimentalFeatureListResponse.Type;
+  readonly "experimentalFeature/enablement/set": typeof CodexSchema.V2ExperimentalFeatureEnablementSetResponse.Type;
+  readonly "mcpServer/oauth/login": typeof CodexSchema.V2McpServerOauthLoginResponse.Type;
+  readonly "config/mcpServer/reload": typeof CodexSchema.V2McpServerRefreshResponse.Type;
+  readonly "mcpServerStatus/list": typeof CodexSchema.V2ListMcpServerStatusResponse.Type;
+  readonly "mcpServer/resource/read": typeof CodexSchema.V2McpResourceReadResponse.Type;
+  readonly "mcpServer/tool/call": typeof CodexSchema.V2McpServerToolCallResponse.Type;
+  readonly "windowsSandbox/setupStart": typeof CodexSchema.V2WindowsSandboxSetupStartResponse.Type;
+  readonly "windowsSandbox/readiness": typeof CodexSchema.V2WindowsSandboxReadinessResponse.Type;
+  readonly "account/login/start": typeof CodexSchema.V2LoginAccountResponse.Type;
+  readonly "account/login/cancel": typeof CodexSchema.V2CancelLoginAccountResponse.Type;
+  readonly "account/logout": typeof CodexSchema.V2LogoutAccountResponse.Type;
+  readonly "account/rateLimits/read": typeof CodexSchema.V2GetAccountRateLimitsResponse.Type;
+  readonly "account/sendAddCreditsNudgeEmail": typeof CodexSchema.V2SendAddCreditsNudgeEmailResponse.Type;
+  readonly "feedback/upload": typeof CodexSchema.V2FeedbackUploadResponse.Type;
+  readonly "command/exec": typeof CodexSchema.V2CommandExecResponse.Type;
+  readonly "command/exec/write": typeof CodexSchema.V2CommandExecWriteResponse.Type;
+  readonly "command/exec/terminate": typeof CodexSchema.V2CommandExecTerminateResponse.Type;
+  readonly "command/exec/resize": typeof CodexSchema.V2CommandExecResizeResponse.Type;
+  readonly "config/read": typeof CodexSchema.V2ConfigReadResponse.Type;
+  readonly "externalAgentConfig/detect": typeof CodexSchema.V2ExternalAgentConfigDetectResponse.Type;
+  readonly "externalAgentConfig/import": typeof CodexSchema.V2ExternalAgentConfigImportResponse.Type;
+  readonly "config/value/write": typeof CodexSchema.V2ConfigWriteResponse.Type;
+  readonly "config/batchWrite": typeof CodexSchema.V2ConfigWriteResponse.Type;
+  readonly "configRequirements/read": typeof CodexSchema.V2ConfigRequirementsReadResponse.Type;
+  readonly "account/read": typeof CodexSchema.V2GetAccountResponse.Type;
+  readonly getConversationSummary: typeof CodexSchema.GetConversationSummaryResponse.Type;
+  readonly gitDiffToRemote: typeof CodexSchema.GitDiffToRemoteResponse.Type;
+  readonly getAuthStatus: typeof CodexSchema.GetAuthStatusResponse.Type;
+  readonly fuzzyFileSearch: typeof CodexSchema.FuzzyFileSearchResponse.Type;
+}
+
+export interface ClientNotificationParamsByMethod {
+  readonly initialized: undefined;
+}
+
+export interface ServerRequestParamsByMethod {
+  readonly "item/commandExecution/requestApproval": typeof CodexSchema.CommandExecutionRequestApprovalParams.Type;
+  readonly "item/fileChange/requestApproval": typeof CodexSchema.FileChangeRequestApprovalParams.Type;
+  readonly "item/tool/requestUserInput": typeof CodexSchema.ToolRequestUserInputParams.Type;
+  readonly "mcpServer/elicitation/request": typeof CodexSchema.McpServerElicitationRequestParams.Type;
+  readonly "item/permissions/requestApproval": typeof CodexSchema.PermissionsRequestApprovalParams.Type;
+  readonly "item/tool/call": typeof CodexSchema.DynamicToolCallParams.Type;
+  readonly "account/chatgptAuthTokens/refresh": typeof CodexSchema.ChatgptAuthTokensRefreshParams.Type;
+  readonly applyPatchApproval: typeof CodexSchema.ApplyPatchApprovalParams.Type;
+  readonly execCommandApproval: typeof CodexSchema.ExecCommandApprovalParams.Type;
+}
+
+export interface ServerRequestResponsesByMethod {
+  readonly "item/commandExecution/requestApproval": typeof CodexSchema.CommandExecutionRequestApprovalResponse.Type;
+  readonly "item/fileChange/requestApproval": typeof CodexSchema.FileChangeRequestApprovalResponse.Type;
+  readonly "item/tool/requestUserInput": typeof CodexSchema.ToolRequestUserInputResponse.Type;
+  readonly "mcpServer/elicitation/request": typeof CodexSchema.McpServerElicitationRequestResponse.Type;
+  readonly "item/permissions/requestApproval": typeof CodexSchema.PermissionsRequestApprovalResponse.Type;
+  readonly "item/tool/call": typeof CodexSchema.DynamicToolCallResponse.Type;
+  readonly "account/chatgptAuthTokens/refresh": typeof CodexSchema.ChatgptAuthTokensRefreshResponse.Type;
+  readonly applyPatchApproval: typeof CodexSchema.ApplyPatchApprovalResponse.Type;
+  readonly execCommandApproval: typeof CodexSchema.ExecCommandApprovalResponse.Type;
+}
+
+export interface ServerNotificationParamsByMethod {
+  readonly error: typeof CodexSchema.V2ErrorNotification.Type;
+  readonly "thread/started": typeof CodexSchema.V2ThreadStartedNotification.Type;
+  readonly "thread/status/changed": typeof CodexSchema.V2ThreadStatusChangedNotification.Type;
+  readonly "thread/archived": typeof CodexSchema.V2ThreadArchivedNotification.Type;
+  readonly "thread/unarchived": typeof CodexSchema.V2ThreadUnarchivedNotification.Type;
+  readonly "thread/closed": typeof CodexSchema.V2ThreadClosedNotification.Type;
+  readonly "skills/changed": typeof CodexSchema.V2SkillsChangedNotification.Type;
+  readonly "thread/name/updated": typeof CodexSchema.V2ThreadNameUpdatedNotification.Type;
+  readonly "thread/goal/updated": typeof CodexSchema.V2ThreadGoalUpdatedNotification.Type;
+  readonly "thread/goal/cleared": typeof CodexSchema.V2ThreadGoalClearedNotification.Type;
+  readonly "thread/tokenUsage/updated": typeof CodexSchema.V2ThreadTokenUsageUpdatedNotification.Type;
+  readonly "turn/started": typeof CodexSchema.V2TurnStartedNotification.Type;
+  readonly "hook/started": typeof CodexSchema.V2HookStartedNotification.Type;
+  readonly "turn/completed": typeof CodexSchema.V2TurnCompletedNotification.Type;
+  readonly "hook/completed": typeof CodexSchema.V2HookCompletedNotification.Type;
+  readonly "turn/diff/updated": typeof CodexSchema.V2TurnDiffUpdatedNotification.Type;
+  readonly "turn/plan/updated": typeof CodexSchema.V2TurnPlanUpdatedNotification.Type;
+  readonly "item/started": typeof CodexSchema.V2ItemStartedNotification.Type;
+  readonly "item/autoApprovalReview/started": typeof CodexSchema.V2ItemGuardianApprovalReviewStartedNotification.Type;
+  readonly "item/autoApprovalReview/completed": typeof CodexSchema.V2ItemGuardianApprovalReviewCompletedNotification.Type;
+  readonly "item/completed": typeof CodexSchema.V2ItemCompletedNotification.Type;
+  readonly "rawResponseItem/completed": typeof CodexSchema.V2RawResponseItemCompletedNotification.Type;
+  readonly "item/agentMessage/delta": typeof CodexSchema.V2AgentMessageDeltaNotification.Type;
+  readonly "item/plan/delta": typeof CodexSchema.V2PlanDeltaNotification.Type;
+  readonly "command/exec/outputDelta": typeof CodexSchema.V2CommandExecOutputDeltaNotification.Type;
+  readonly "process/outputDelta": typeof CodexSchema.V2ProcessOutputDeltaNotification.Type;
+  readonly "process/exited": typeof CodexSchema.V2ProcessExitedNotification.Type;
+  readonly "item/commandExecution/outputDelta": typeof CodexSchema.V2CommandExecutionOutputDeltaNotification.Type;
+  readonly "item/commandExecution/terminalInteraction": typeof CodexSchema.V2TerminalInteractionNotification.Type;
+  readonly "item/fileChange/outputDelta": typeof CodexSchema.V2FileChangeOutputDeltaNotification.Type;
+  readonly "item/fileChange/patchUpdated": typeof CodexSchema.V2FileChangePatchUpdatedNotification.Type;
+  readonly "serverRequest/resolved": typeof CodexSchema.V2ServerRequestResolvedNotification.Type;
+  readonly "item/mcpToolCall/progress": typeof CodexSchema.V2McpToolCallProgressNotification.Type;
+  readonly "mcpServer/oauthLogin/completed": typeof CodexSchema.V2McpServerOauthLoginCompletedNotification.Type;
+  readonly "mcpServer/startupStatus/updated": typeof CodexSchema.V2McpServerStatusUpdatedNotification.Type;
+  readonly "account/updated": typeof CodexSchema.V2AccountUpdatedNotification.Type;
+  readonly "account/rateLimits/updated": typeof CodexSchema.V2AccountRateLimitsUpdatedNotification.Type;
+  readonly "app/list/updated": typeof CodexSchema.V2AppListUpdatedNotification.Type;
+  readonly "remoteControl/status/changed": typeof CodexSchema.V2RemoteControlStatusChangedNotification.Type;
+  readonly "externalAgentConfig/import/completed": typeof CodexSchema.V2ExternalAgentConfigImportCompletedNotification.Type;
+  readonly "fs/changed": typeof CodexSchema.V2FsChangedNotification.Type;
+  readonly "item/reasoning/summaryTextDelta": typeof CodexSchema.V2ReasoningSummaryTextDeltaNotification.Type;
+  readonly "item/reasoning/summaryPartAdded": typeof CodexSchema.V2ReasoningSummaryPartAddedNotification.Type;
+  readonly "item/reasoning/textDelta": typeof CodexSchema.V2ReasoningTextDeltaNotification.Type;
+  readonly "thread/compacted": typeof CodexSchema.V2ContextCompactedNotification.Type;
+  readonly "model/rerouted": typeof CodexSchema.V2ModelReroutedNotification.Type;
+  readonly "model/verification": typeof CodexSchema.V2ModelVerificationNotification.Type;
+  readonly warning: typeof CodexSchema.V2WarningNotification.Type;
+  readonly guardianWarning: typeof CodexSchema.V2GuardianWarningNotification.Type;
+  readonly deprecationNotice: typeof CodexSchema.V2DeprecationNoticeNotification.Type;
+  readonly configWarning: typeof CodexSchema.V2ConfigWarningNotification.Type;
+  readonly "fuzzyFileSearch/sessionUpdated": typeof CodexSchema.FuzzyFileSearchSessionUpdatedNotification.Type;
+  readonly "fuzzyFileSearch/sessionCompleted": typeof CodexSchema.FuzzyFileSearchSessionCompletedNotification.Type;
+  readonly "thread/realtime/started": typeof CodexSchema.V2ThreadRealtimeStartedNotification.Type;
+  readonly "thread/realtime/itemAdded": typeof CodexSchema.V2ThreadRealtimeItemAddedNotification.Type;
+  readonly "thread/realtime/transcript/delta": typeof CodexSchema.V2ThreadRealtimeTranscriptDeltaNotification.Type;
+  readonly "thread/realtime/transcript/done": typeof CodexSchema.V2ThreadRealtimeTranscriptDoneNotification.Type;
+  readonly "thread/realtime/outputAudio/delta": typeof CodexSchema.V2ThreadRealtimeOutputAudioDeltaNotification.Type;
+  readonly "thread/realtime/sdp": typeof CodexSchema.V2ThreadRealtimeSdpNotification.Type;
+  readonly "thread/realtime/error": typeof CodexSchema.V2ThreadRealtimeErrorNotification.Type;
+  readonly "thread/realtime/closed": typeof CodexSchema.V2ThreadRealtimeClosedNotification.Type;
+  readonly "windows/worldWritableWarning": typeof CodexSchema.V2WindowsWorldWritableWarningNotification.Type;
+  readonly "windowsSandbox/setupCompleted": typeof CodexSchema.V2WindowsSandboxSetupCompletedNotification.Type;
+  readonly "account/login/completed": typeof CodexSchema.V2AccountLoginCompletedNotification.Type;
+}
+
+export const CLIENT_REQUEST_PARAMS = {
+  initialize: CodexSchema.V1InitializeParams,
+  "thread/start": CodexSchema.V2ThreadStartParams,
+  "thread/resume": CodexSchema.V2ThreadResumeParams,
+  "thread/fork": CodexSchema.V2ThreadForkParams,
+  "thread/archive": CodexSchema.V2ThreadArchiveParams,
+  "thread/unsubscribe": CodexSchema.V2ThreadUnsubscribeParams,
+  "thread/name/set": CodexSchema.V2ThreadSetNameParams,
+  "thread/metadata/update": CodexSchema.V2ThreadMetadataUpdateParams,
+  "thread/unarchive": CodexSchema.V2ThreadUnarchiveParams,
+  "thread/compact/start": CodexSchema.V2ThreadCompactStartParams,
+  "thread/shellCommand": CodexSchema.V2ThreadShellCommandParams,
+  "thread/approveGuardianDeniedAction": CodexSchema.V2ThreadApproveGuardianDeniedActionParams,
+  "thread/rollback": CodexSchema.V2ThreadRollbackParams,
+  "thread/list": CodexSchema.V2ThreadListParams,
+  "thread/loaded/list": CodexSchema.V2ThreadLoadedListParams,
+  "thread/read": CodexSchema.V2ThreadReadParams,
+  "thread/inject_items": CodexSchema.V2ThreadInjectItemsParams,
+  "skills/list": CodexSchema.V2SkillsListParams,
+  "hooks/list": CodexSchema.V2HooksListParams,
+  "marketplace/add": CodexSchema.V2MarketplaceAddParams,
+  "marketplace/remove": CodexSchema.V2MarketplaceRemoveParams,
+  "marketplace/upgrade": CodexSchema.V2MarketplaceUpgradeParams,
+  "plugin/list": CodexSchema.V2PluginListParams,
+  "plugin/read": CodexSchema.V2PluginReadParams,
+  "plugin/skill/read": CodexSchema.V2PluginSkillReadParams,
+  "plugin/share/save": CodexSchema.V2PluginShareSaveParams,
+  "plugin/share/updateTargets": CodexSchema.V2PluginShareUpdateTargetsParams,
+  "plugin/share/list": CodexSchema.V2PluginShareListParams,
+  "plugin/share/delete": CodexSchema.V2PluginShareDeleteParams,
+  "app/list": CodexSchema.V2AppsListParams,
+  "fs/readFile": CodexSchema.V2FsReadFileParams,
+  "fs/writeFile": CodexSchema.V2FsWriteFileParams,
+  "fs/createDirectory": CodexSchema.V2FsCreateDirectoryParams,
+  "fs/getMetadata": CodexSchema.V2FsGetMetadataParams,
+  "fs/readDirectory": CodexSchema.V2FsReadDirectoryParams,
+  "fs/remove": CodexSchema.V2FsRemoveParams,
+  "fs/copy": CodexSchema.V2FsCopyParams,
+  "fs/watch": CodexSchema.V2FsWatchParams,
+  "fs/unwatch": CodexSchema.V2FsUnwatchParams,
+  "skills/config/write": CodexSchema.V2SkillsConfigWriteParams,
+  "plugin/install": CodexSchema.V2PluginInstallParams,
+  "plugin/uninstall": CodexSchema.V2PluginUninstallParams,
+  "turn/start": CodexSchema.V2TurnStartParams,
+  "turn/steer": CodexSchema.V2TurnSteerParams,
+  "turn/interrupt": CodexSchema.V2TurnInterruptParams,
+  "review/start": CodexSchema.V2ReviewStartParams,
+  "model/list": CodexSchema.V2ModelListParams,
+  "modelProvider/capabilities/read": CodexSchema.V2ModelProviderCapabilitiesReadParams,
+  "experimentalFeature/list": CodexSchema.V2ExperimentalFeatureListParams,
+  "experimentalFeature/enablement/set": CodexSchema.V2ExperimentalFeatureEnablementSetParams,
+  "mcpServer/oauth/login": CodexSchema.V2McpServerOauthLoginParams,
+  "config/mcpServer/reload": undefined,
+  "mcpServerStatus/list": CodexSchema.V2ListMcpServerStatusParams,
+  "mcpServer/resource/read": CodexSchema.V2McpResourceReadParams,
+  "mcpServer/tool/call": CodexSchema.V2McpServerToolCallParams,
+  "windowsSandbox/setupStart": CodexSchema.V2WindowsSandboxSetupStartParams,
+  "windowsSandbox/readiness": undefined,
+  "account/login/start": CodexSchema.V2LoginAccountParams,
+  "account/login/cancel": CodexSchema.V2CancelLoginAccountParams,
+  "account/logout": undefined,
+  "account/rateLimits/read": undefined,
+  "account/sendAddCreditsNudgeEmail": CodexSchema.V2SendAddCreditsNudgeEmailParams,
+  "feedback/upload": CodexSchema.V2FeedbackUploadParams,
+  "command/exec": CodexSchema.V2CommandExecParams,
+  "command/exec/write": CodexSchema.V2CommandExecWriteParams,
+  "command/exec/terminate": CodexSchema.V2CommandExecTerminateParams,
+  "command/exec/resize": CodexSchema.V2CommandExecResizeParams,
+  "config/read": CodexSchema.V2ConfigReadParams,
+  "externalAgentConfig/detect": CodexSchema.V2ExternalAgentConfigDetectParams,
+  "externalAgentConfig/import": CodexSchema.V2ExternalAgentConfigImportParams,
+  "config/value/write": CodexSchema.V2ConfigValueWriteParams,
+  "config/batchWrite": CodexSchema.V2ConfigBatchWriteParams,
+  "configRequirements/read": undefined,
+  "account/read": CodexSchema.V2GetAccountParams,
+  getConversationSummary: CodexSchema.GetConversationSummaryParams,
+  gitDiffToRemote: CodexSchema.GitDiffToRemoteParams,
+  getAuthStatus: CodexSchema.GetAuthStatusParams,
+  fuzzyFileSearch: CodexSchema.FuzzyFileSearchParams,
+} as const;
+
+export const CLIENT_REQUEST_RESPONSES = {
+  initialize: CodexSchema.V1InitializeResponse,
+  "thread/start": CodexSchema.V2ThreadStartResponse,
+  "thread/resume": CodexSchema.V2ThreadResumeResponse,
+  "thread/fork": CodexSchema.V2ThreadForkResponse,
+  "thread/archive": CodexSchema.V2ThreadArchiveResponse,
+  "thread/unsubscribe": CodexSchema.V2ThreadUnsubscribeResponse,
+  "thread/name/set": CodexSchema.V2ThreadSetNameResponse,
+  "thread/metadata/update": CodexSchema.V2ThreadMetadataUpdateResponse,
+  "thread/unarchive": CodexSchema.V2ThreadUnarchiveResponse,
+  "thread/compact/start": CodexSchema.V2ThreadCompactStartResponse,
+  "thread/shellCommand": CodexSchema.V2ThreadShellCommandResponse,
+  "thread/approveGuardianDeniedAction": CodexSchema.V2ThreadApproveGuardianDeniedActionResponse,
+  "thread/rollback": CodexSchema.V2ThreadRollbackResponse,
+  "thread/list": CodexSchema.V2ThreadListResponse,
+  "thread/loaded/list": CodexSchema.V2ThreadLoadedListResponse,
+  "thread/read": CodexSchema.V2ThreadReadResponse,
+  "thread/inject_items": CodexSchema.V2ThreadInjectItemsResponse,
+  "skills/list": CodexSchema.V2SkillsListResponse,
+  "hooks/list": CodexSchema.V2HooksListResponse,
+  "marketplace/add": CodexSchema.V2MarketplaceAddResponse,
+  "marketplace/remove": CodexSchema.V2MarketplaceRemoveResponse,
+  "marketplace/upgrade": CodexSchema.V2MarketplaceUpgradeResponse,
+  "plugin/list": CodexSchema.V2PluginListResponse,
+  "plugin/read": CodexSchema.V2PluginReadResponse,
+  "plugin/skill/read": CodexSchema.V2PluginSkillReadResponse,
+  "plugin/share/save": CodexSchema.V2PluginShareSaveResponse,
+  "plugin/share/updateTargets": CodexSchema.V2PluginShareUpdateTargetsResponse,
+  "plugin/share/list": CodexSchema.V2PluginShareListResponse,
+  "plugin/share/delete": CodexSchema.V2PluginShareDeleteResponse,
+  "app/list": CodexSchema.V2AppsListResponse,
+  "fs/readFile": CodexSchema.V2FsReadFileResponse,
+  "fs/writeFile": CodexSchema.V2FsWriteFileResponse,
+  "fs/createDirectory": CodexSchema.V2FsCreateDirectoryResponse,
+  "fs/getMetadata": CodexSchema.V2FsGetMetadataResponse,
+  "fs/readDirectory": CodexSchema.V2FsReadDirectoryResponse,
+  "fs/remove": CodexSchema.V2FsRemoveResponse,
+  "fs/copy": CodexSchema.V2FsCopyResponse,
+  "fs/watch": CodexSchema.V2FsWatchResponse,
+  "fs/unwatch": CodexSchema.V2FsUnwatchResponse,
+  "skills/config/write": CodexSchema.V2SkillsConfigWriteResponse,
+  "plugin/install": CodexSchema.V2PluginInstallResponse,
+  "plugin/uninstall": CodexSchema.V2PluginUninstallResponse,
+  "turn/start": CodexSchema.V2TurnStartResponse,
+  "turn/steer": CodexSchema.V2TurnSteerResponse,
+  "turn/interrupt": CodexSchema.V2TurnInterruptResponse,
+  "review/start": CodexSchema.V2ReviewStartResponse,
+  "model/list": CodexSchema.V2ModelListResponse,
+  "modelProvider/capabilities/read": CodexSchema.V2ModelProviderCapabilitiesReadResponse,
+  "experimentalFeature/list": CodexSchema.V2ExperimentalFeatureListResponse,
+  "experimentalFeature/enablement/set": CodexSchema.V2ExperimentalFeatureEnablementSetResponse,
+  "mcpServer/oauth/login": CodexSchema.V2McpServerOauthLoginResponse,
+  "config/mcpServer/reload": CodexSchema.V2McpServerRefreshResponse,
+  "mcpServerStatus/list": CodexSchema.V2ListMcpServerStatusResponse,
+  "mcpServer/resource/read": CodexSchema.V2McpResourceReadResponse,
+  "mcpServer/tool/call": CodexSchema.V2McpServerToolCallResponse,
+  "windowsSandbox/setupStart": CodexSchema.V2WindowsSandboxSetupStartResponse,
+  "windowsSandbox/readiness": CodexSchema.V2WindowsSandboxReadinessResponse,
+  "account/login/start": CodexSchema.V2LoginAccountResponse,
+  "account/login/cancel": CodexSchema.V2CancelLoginAccountResponse,
+  "account/logout": CodexSchema.V2LogoutAccountResponse,
+  "account/rateLimits/read": CodexSchema.V2GetAccountRateLimitsResponse,
+  "account/sendAddCreditsNudgeEmail": CodexSchema.V2SendAddCreditsNudgeEmailResponse,
+  "feedback/upload": CodexSchema.V2FeedbackUploadResponse,
+  "command/exec": CodexSchema.V2CommandExecResponse,
+  "command/exec/write": CodexSchema.V2CommandExecWriteResponse,
+  "command/exec/terminate": CodexSchema.V2CommandExecTerminateResponse,
+  "command/exec/resize": CodexSchema.V2CommandExecResizeResponse,
+  "config/read": CodexSchema.V2ConfigReadResponse,
+  "externalAgentConfig/detect": CodexSchema.V2ExternalAgentConfigDetectResponse,
+  "externalAgentConfig/import": CodexSchema.V2ExternalAgentConfigImportResponse,
+  "config/value/write": CodexSchema.V2ConfigWriteResponse,
+  "config/batchWrite": CodexSchema.V2ConfigWriteResponse,
+  "configRequirements/read": CodexSchema.V2ConfigRequirementsReadResponse,
+  "account/read": CodexSchema.V2GetAccountResponse,
+  getConversationSummary: CodexSchema.GetConversationSummaryResponse,
+  gitDiffToRemote: CodexSchema.GitDiffToRemoteResponse,
+  getAuthStatus: CodexSchema.GetAuthStatusResponse,
+  fuzzyFileSearch: CodexSchema.FuzzyFileSearchResponse,
+} as const;
+
+export const CLIENT_NOTIFICATION_PARAMS = {
+  initialized: undefined,
+} as const;
+
+export const SERVER_REQUEST_PARAMS = {
+  "item/commandExecution/requestApproval": CodexSchema.CommandExecutionRequestApprovalParams,
+  "item/fileChange/requestApproval": CodexSchema.FileChangeRequestApprovalParams,
+  "item/tool/requestUserInput": CodexSchema.ToolRequestUserInputParams,
+  "mcpServer/elicitation/request": CodexSchema.McpServerElicitationRequestParams,
+  "item/permissions/requestApproval": CodexSchema.PermissionsRequestApprovalParams,
+  "item/tool/call": CodexSchema.DynamicToolCallParams,
+  "account/chatgptAuthTokens/refresh": CodexSchema.ChatgptAuthTokensRefreshParams,
+  applyPatchApproval: CodexSchema.ApplyPatchApprovalParams,
+  execCommandApproval: CodexSchema.ExecCommandApprovalParams,
+} as const;
+
+export const SERVER_REQUEST_RESPONSES = {
+  "item/commandExecution/requestApproval": CodexSchema.CommandExecutionRequestApprovalResponse,
+  "item/fileChange/requestApproval": CodexSchema.FileChangeRequestApprovalResponse,
+  "item/tool/requestUserInput": CodexSchema.ToolRequestUserInputResponse,
+  "mcpServer/elicitation/request": CodexSchema.McpServerElicitationRequestResponse,
+  "item/permissions/requestApproval": CodexSchema.PermissionsRequestApprovalResponse,
+  "item/tool/call": CodexSchema.DynamicToolCallResponse,
+  "account/chatgptAuthTokens/refresh": CodexSchema.ChatgptAuthTokensRefreshResponse,
+  applyPatchApproval: CodexSchema.ApplyPatchApprovalResponse,
+  execCommandApproval: CodexSchema.ExecCommandApprovalResponse,
+} as const;
+
+export const SERVER_NOTIFICATION_PARAMS = {
+  error: CodexSchema.V2ErrorNotification,
+  "thread/started": CodexSchema.V2ThreadStartedNotification,
+  "thread/status/changed": CodexSchema.V2ThreadStatusChangedNotification,
+  "thread/archived": CodexSchema.V2ThreadArchivedNotification,
+  "thread/unarchived": CodexSchema.V2ThreadUnarchivedNotification,
+  "thread/closed": CodexSchema.V2ThreadClosedNotification,
+  "skills/changed": CodexSchema.V2SkillsChangedNotification,
+  "thread/name/updated": CodexSchema.V2ThreadNameUpdatedNotification,
+  "thread/goal/updated": CodexSchema.V2ThreadGoalUpdatedNotification,
+  "thread/goal/cleared": CodexSchema.V2ThreadGoalClearedNotification,
+  "thread/tokenUsage/updated": CodexSchema.V2ThreadTokenUsageUpdatedNotification,
+  "turn/started": CodexSchema.V2TurnStartedNotification,
+  "hook/started": CodexSchema.V2HookStartedNotification,
+  "turn/completed": CodexSchema.V2TurnCompletedNotification,
+  "hook/completed": CodexSchema.V2HookCompletedNotification,
+  "turn/diff/updated": CodexSchema.V2TurnDiffUpdatedNotification,
+  "turn/plan/updated": CodexSchema.V2TurnPlanUpdatedNotification,
+  "item/started": CodexSchema.V2ItemStartedNotification,
+  "item/autoApprovalReview/started": CodexSchema.V2ItemGuardianApprovalReviewStartedNotification,
+  "item/autoApprovalReview/completed":
+    CodexSchema.V2ItemGuardianApprovalReviewCompletedNotification,
+  "item/completed": CodexSchema.V2ItemCompletedNotification,
+  "rawResponseItem/completed": CodexSchema.V2RawResponseItemCompletedNotification,
+  "item/agentMessage/delta": CodexSchema.V2AgentMessageDeltaNotification,
+  "item/plan/delta": CodexSchema.V2PlanDeltaNotification,
+  "command/exec/outputDelta": CodexSchema.V2CommandExecOutputDeltaNotification,
+  "process/outputDelta": CodexSchema.V2ProcessOutputDeltaNotification,
+  "process/exited": CodexSchema.V2ProcessExitedNotification,
+  "item/commandExecution/outputDelta": CodexSchema.V2CommandExecutionOutputDeltaNotification,
+  "item/commandExecution/terminalInteraction": CodexSchema.V2TerminalInteractionNotification,
+  "item/fileChange/outputDelta": CodexSchema.V2FileChangeOutputDeltaNotification,
+  "item/fileChange/patchUpdated": CodexSchema.V2FileChangePatchUpdatedNotification,
+  "serverRequest/resolved": CodexSchema.V2ServerRequestResolvedNotification,
+  "item/mcpToolCall/progress": CodexSchema.V2McpToolCallProgressNotification,
+  "mcpServer/oauthLogin/completed": CodexSchema.V2McpServerOauthLoginCompletedNotification,
+  "mcpServer/startupStatus/updated": CodexSchema.V2McpServerStatusUpdatedNotification,
+  "account/updated": CodexSchema.V2AccountUpdatedNotification,
+  "account/rateLimits/updated": CodexSchema.V2AccountRateLimitsUpdatedNotification,
+  "app/list/updated": CodexSchema.V2AppListUpdatedNotification,
+  "remoteControl/status/changed": CodexSchema.V2RemoteControlStatusChangedNotification,
+  "externalAgentConfig/import/completed":
+    CodexSchema.V2ExternalAgentConfigImportCompletedNotification,
+  "fs/changed": CodexSchema.V2FsChangedNotification,
+  "item/reasoning/summaryTextDelta": CodexSchema.V2ReasoningSummaryTextDeltaNotification,
+  "item/reasoning/summaryPartAdded": CodexSchema.V2ReasoningSummaryPartAddedNotification,
+  "item/reasoning/textDelta": CodexSchema.V2ReasoningTextDeltaNotification,
+  "thread/compacted": CodexSchema.V2ContextCompactedNotification,
+  "model/rerouted": CodexSchema.V2ModelReroutedNotification,
+  "model/verification": CodexSchema.V2ModelVerificationNotification,
+  warning: CodexSchema.V2WarningNotification,
+  guardianWarning: CodexSchema.V2GuardianWarningNotification,
+  deprecationNotice: CodexSchema.V2DeprecationNoticeNotification,
+  configWarning: CodexSchema.V2ConfigWarningNotification,
+  "fuzzyFileSearch/sessionUpdated": CodexSchema.FuzzyFileSearchSessionUpdatedNotification,
+  "fuzzyFileSearch/sessionCompleted": CodexSchema.FuzzyFileSearchSessionCompletedNotification,
+  "thread/realtime/started": CodexSchema.V2ThreadRealtimeStartedNotification,
+  "thread/realtime/itemAdded": CodexSchema.V2ThreadRealtimeItemAddedNotification,
+  "thread/realtime/transcript/delta": CodexSchema.V2ThreadRealtimeTranscriptDeltaNotification,
+  "thread/realtime/transcript/done": CodexSchema.V2ThreadRealtimeTranscriptDoneNotification,
+  "thread/realtime/outputAudio/delta": CodexSchema.V2ThreadRealtimeOutputAudioDeltaNotification,
+  "thread/realtime/sdp": CodexSchema.V2ThreadRealtimeSdpNotification,
+  "thread/realtime/error": CodexSchema.V2ThreadRealtimeErrorNotification,
+  "thread/realtime/closed": CodexSchema.V2ThreadRealtimeClosedNotification,
+  "windows/worldWritableWarning": CodexSchema.V2WindowsWorldWritableWarningNotification,
+  "windowsSandbox/setupCompleted": CodexSchema.V2WindowsSandboxSetupCompletedNotification,
+  "account/login/completed": CodexSchema.V2AccountLoginCompletedNotification,
+} as const;
diff --git a/packages/effect-codex-app-server/src/_generated/namespaces.gen.ts b/packages/effect-codex-app-server/src/_generated/namespaces.gen.ts
new file mode 100644
index 00000000000..a676187dfc7
--- /dev/null
+++ b/packages/effect-codex-app-server/src/_generated/namespaces.gen.ts
@@ -0,0 +1,220 @@
+// This file is generated by the effect-codex-app-server package. Do not edit manually.
+// Upstream protocol ref: 07b695190f30a450e4921f71f77473e564395c59
+
+import * as CodexSchema from "./schema.gen.ts";
+
+export const v1 = {
+  InitializeParams: CodexSchema.V1InitializeParams,
+  InitializeResponse: CodexSchema.V1InitializeResponse,
+} as const;
+
+export const v2 = {
+  AccountLoginCompletedNotification: CodexSchema.V2AccountLoginCompletedNotification,
+  AccountRateLimitsUpdatedNotification: CodexSchema.V2AccountRateLimitsUpdatedNotification,
+  AccountUpdatedNotification: CodexSchema.V2AccountUpdatedNotification,
+  AgentMessageDeltaNotification: CodexSchema.V2AgentMessageDeltaNotification,
+  AppListUpdatedNotification: CodexSchema.V2AppListUpdatedNotification,
+  AppsListParams: CodexSchema.V2AppsListParams,
+  AppsListResponse: CodexSchema.V2AppsListResponse,
+  CancelLoginAccountParams: CodexSchema.V2CancelLoginAccountParams,
+  CancelLoginAccountResponse: CodexSchema.V2CancelLoginAccountResponse,
+  CommandExecOutputDeltaNotification: CodexSchema.V2CommandExecOutputDeltaNotification,
+  CommandExecParams: CodexSchema.V2CommandExecParams,
+  CommandExecResizeParams: CodexSchema.V2CommandExecResizeParams,
+  CommandExecResizeResponse: CodexSchema.V2CommandExecResizeResponse,
+  CommandExecResponse: CodexSchema.V2CommandExecResponse,
+  CommandExecTerminateParams: CodexSchema.V2CommandExecTerminateParams,
+  CommandExecTerminateResponse: CodexSchema.V2CommandExecTerminateResponse,
+  CommandExecutionOutputDeltaNotification: CodexSchema.V2CommandExecutionOutputDeltaNotification,
+  CommandExecWriteParams: CodexSchema.V2CommandExecWriteParams,
+  CommandExecWriteResponse: CodexSchema.V2CommandExecWriteResponse,
+  ConfigBatchWriteParams: CodexSchema.V2ConfigBatchWriteParams,
+  ConfigReadParams: CodexSchema.V2ConfigReadParams,
+  ConfigReadResponse: CodexSchema.V2ConfigReadResponse,
+  ConfigRequirementsReadResponse: CodexSchema.V2ConfigRequirementsReadResponse,
+  ConfigValueWriteParams: CodexSchema.V2ConfigValueWriteParams,
+  ConfigWarningNotification: CodexSchema.V2ConfigWarningNotification,
+  ConfigWriteResponse: CodexSchema.V2ConfigWriteResponse,
+  ContextCompactedNotification: CodexSchema.V2ContextCompactedNotification,
+  DeprecationNoticeNotification: CodexSchema.V2DeprecationNoticeNotification,
+  ErrorNotification: CodexSchema.V2ErrorNotification,
+  ExperimentalFeatureEnablementSetParams: CodexSchema.V2ExperimentalFeatureEnablementSetParams,
+  ExperimentalFeatureEnablementSetResponse: CodexSchema.V2ExperimentalFeatureEnablementSetResponse,
+  ExperimentalFeatureListParams: CodexSchema.V2ExperimentalFeatureListParams,
+  ExperimentalFeatureListResponse: CodexSchema.V2ExperimentalFeatureListResponse,
+  ExternalAgentConfigDetectParams: CodexSchema.V2ExternalAgentConfigDetectParams,
+  ExternalAgentConfigDetectResponse: CodexSchema.V2ExternalAgentConfigDetectResponse,
+  ExternalAgentConfigImportCompletedNotification:
+    CodexSchema.V2ExternalAgentConfigImportCompletedNotification,
+  ExternalAgentConfigImportParams: CodexSchema.V2ExternalAgentConfigImportParams,
+  ExternalAgentConfigImportResponse: CodexSchema.V2ExternalAgentConfigImportResponse,
+  FeedbackUploadParams: CodexSchema.V2FeedbackUploadParams,
+  FeedbackUploadResponse: CodexSchema.V2FeedbackUploadResponse,
+  FileChangeOutputDeltaNotification: CodexSchema.V2FileChangeOutputDeltaNotification,
+  FileChangePatchUpdatedNotification: CodexSchema.V2FileChangePatchUpdatedNotification,
+  FsChangedNotification: CodexSchema.V2FsChangedNotification,
+  FsCopyParams: CodexSchema.V2FsCopyParams,
+  FsCopyResponse: CodexSchema.V2FsCopyResponse,
+  FsCreateDirectoryParams: CodexSchema.V2FsCreateDirectoryParams,
+  FsCreateDirectoryResponse: CodexSchema.V2FsCreateDirectoryResponse,
+  FsGetMetadataParams: CodexSchema.V2FsGetMetadataParams,
+  FsGetMetadataResponse: CodexSchema.V2FsGetMetadataResponse,
+  FsReadDirectoryParams: CodexSchema.V2FsReadDirectoryParams,
+  FsReadDirectoryResponse: CodexSchema.V2FsReadDirectoryResponse,
+  FsReadFileParams: CodexSchema.V2FsReadFileParams,
+  FsReadFileResponse: CodexSchema.V2FsReadFileResponse,
+  FsRemoveParams: CodexSchema.V2FsRemoveParams,
+  FsRemoveResponse: CodexSchema.V2FsRemoveResponse,
+  FsUnwatchParams: CodexSchema.V2FsUnwatchParams,
+  FsUnwatchResponse: CodexSchema.V2FsUnwatchResponse,
+  FsWatchParams: CodexSchema.V2FsWatchParams,
+  FsWatchResponse: CodexSchema.V2FsWatchResponse,
+  FsWriteFileParams: CodexSchema.V2FsWriteFileParams,
+  FsWriteFileResponse: CodexSchema.V2FsWriteFileResponse,
+  GetAccountParams: CodexSchema.V2GetAccountParams,
+  GetAccountRateLimitsResponse: CodexSchema.V2GetAccountRateLimitsResponse,
+  GetAccountResponse: CodexSchema.V2GetAccountResponse,
+  GuardianWarningNotification: CodexSchema.V2GuardianWarningNotification,
+  HookCompletedNotification: CodexSchema.V2HookCompletedNotification,
+  HooksListParams: CodexSchema.V2HooksListParams,
+  HooksListResponse: CodexSchema.V2HooksListResponse,
+  HookStartedNotification: CodexSchema.V2HookStartedNotification,
+  ItemCompletedNotification: CodexSchema.V2ItemCompletedNotification,
+  ItemGuardianApprovalReviewCompletedNotification:
+    CodexSchema.V2ItemGuardianApprovalReviewCompletedNotification,
+  ItemGuardianApprovalReviewStartedNotification:
+    CodexSchema.V2ItemGuardianApprovalReviewStartedNotification,
+  ItemStartedNotification: CodexSchema.V2ItemStartedNotification,
+  ListMcpServerStatusParams: CodexSchema.V2ListMcpServerStatusParams,
+  ListMcpServerStatusResponse: CodexSchema.V2ListMcpServerStatusResponse,
+  LoginAccountParams: CodexSchema.V2LoginAccountParams,
+  LoginAccountResponse: CodexSchema.V2LoginAccountResponse,
+  LogoutAccountResponse: CodexSchema.V2LogoutAccountResponse,
+  MarketplaceAddParams: CodexSchema.V2MarketplaceAddParams,
+  MarketplaceAddResponse: CodexSchema.V2MarketplaceAddResponse,
+  MarketplaceRemoveParams: CodexSchema.V2MarketplaceRemoveParams,
+  MarketplaceRemoveResponse: CodexSchema.V2MarketplaceRemoveResponse,
+  MarketplaceUpgradeParams: CodexSchema.V2MarketplaceUpgradeParams,
+  MarketplaceUpgradeResponse: CodexSchema.V2MarketplaceUpgradeResponse,
+  McpResourceReadParams: CodexSchema.V2McpResourceReadParams,
+  McpResourceReadResponse: CodexSchema.V2McpResourceReadResponse,
+  McpServerOauthLoginCompletedNotification: CodexSchema.V2McpServerOauthLoginCompletedNotification,
+  McpServerOauthLoginParams: CodexSchema.V2McpServerOauthLoginParams,
+  McpServerOauthLoginResponse: CodexSchema.V2McpServerOauthLoginResponse,
+  McpServerRefreshResponse: CodexSchema.V2McpServerRefreshResponse,
+  McpServerStatusUpdatedNotification: CodexSchema.V2McpServerStatusUpdatedNotification,
+  McpServerToolCallParams: CodexSchema.V2McpServerToolCallParams,
+  McpServerToolCallResponse: CodexSchema.V2McpServerToolCallResponse,
+  McpToolCallProgressNotification: CodexSchema.V2McpToolCallProgressNotification,
+  ModelListParams: CodexSchema.V2ModelListParams,
+  ModelListResponse: CodexSchema.V2ModelListResponse,
+  ModelProviderCapabilitiesReadParams: CodexSchema.V2ModelProviderCapabilitiesReadParams,
+  ModelProviderCapabilitiesReadResponse: CodexSchema.V2ModelProviderCapabilitiesReadResponse,
+  ModelReroutedNotification: CodexSchema.V2ModelReroutedNotification,
+  ModelVerificationNotification: CodexSchema.V2ModelVerificationNotification,
+  PlanDeltaNotification: CodexSchema.V2PlanDeltaNotification,
+  PluginInstallParams: CodexSchema.V2PluginInstallParams,
+  PluginInstallResponse: CodexSchema.V2PluginInstallResponse,
+  PluginListParams: CodexSchema.V2PluginListParams,
+  PluginListResponse: CodexSchema.V2PluginListResponse,
+  PluginReadParams: CodexSchema.V2PluginReadParams,
+  PluginReadResponse: CodexSchema.V2PluginReadResponse,
+  PluginShareDeleteParams: CodexSchema.V2PluginShareDeleteParams,
+  PluginShareDeleteResponse: CodexSchema.V2PluginShareDeleteResponse,
+  PluginShareListParams: CodexSchema.V2PluginShareListParams,
+  PluginShareListResponse: CodexSchema.V2PluginShareListResponse,
+  PluginShareSaveParams: CodexSchema.V2PluginShareSaveParams,
+  PluginShareSaveResponse: CodexSchema.V2PluginShareSaveResponse,
+  PluginShareUpdateTargetsParams: CodexSchema.V2PluginShareUpdateTargetsParams,
+  PluginShareUpdateTargetsResponse: CodexSchema.V2PluginShareUpdateTargetsResponse,
+  PluginSkillReadParams: CodexSchema.V2PluginSkillReadParams,
+  PluginSkillReadResponse: CodexSchema.V2PluginSkillReadResponse,
+  PluginUninstallParams: CodexSchema.V2PluginUninstallParams,
+  PluginUninstallResponse: CodexSchema.V2PluginUninstallResponse,
+  ProcessExitedNotification: CodexSchema.V2ProcessExitedNotification,
+  ProcessOutputDeltaNotification: CodexSchema.V2ProcessOutputDeltaNotification,
+  RawResponseItemCompletedNotification: CodexSchema.V2RawResponseItemCompletedNotification,
+  ReasoningSummaryPartAddedNotification: CodexSchema.V2ReasoningSummaryPartAddedNotification,
+  ReasoningSummaryTextDeltaNotification: CodexSchema.V2ReasoningSummaryTextDeltaNotification,
+  ReasoningTextDeltaNotification: CodexSchema.V2ReasoningTextDeltaNotification,
+  RemoteControlStatusChangedNotification: CodexSchema.V2RemoteControlStatusChangedNotification,
+  ReviewStartParams: CodexSchema.V2ReviewStartParams,
+  ReviewStartResponse: CodexSchema.V2ReviewStartResponse,
+  SendAddCreditsNudgeEmailParams: CodexSchema.V2SendAddCreditsNudgeEmailParams,
+  SendAddCreditsNudgeEmailResponse: CodexSchema.V2SendAddCreditsNudgeEmailResponse,
+  ServerRequestResolvedNotification: CodexSchema.V2ServerRequestResolvedNotification,
+  SkillsChangedNotification: CodexSchema.V2SkillsChangedNotification,
+  SkillsConfigWriteParams: CodexSchema.V2SkillsConfigWriteParams,
+  SkillsConfigWriteResponse: CodexSchema.V2SkillsConfigWriteResponse,
+  SkillsListParams: CodexSchema.V2SkillsListParams,
+  SkillsListResponse: CodexSchema.V2SkillsListResponse,
+  TerminalInteractionNotification: CodexSchema.V2TerminalInteractionNotification,
+  ThreadApproveGuardianDeniedActionParams: CodexSchema.V2ThreadApproveGuardianDeniedActionParams,
+  ThreadApproveGuardianDeniedActionResponse:
+    CodexSchema.V2ThreadApproveGuardianDeniedActionResponse,
+  ThreadArchivedNotification: CodexSchema.V2ThreadArchivedNotification,
+  ThreadArchiveParams: CodexSchema.V2ThreadArchiveParams,
+  ThreadArchiveResponse: CodexSchema.V2ThreadArchiveResponse,
+  ThreadClosedNotification: CodexSchema.V2ThreadClosedNotification,
+  ThreadCompactStartParams: CodexSchema.V2ThreadCompactStartParams,
+  ThreadCompactStartResponse: CodexSchema.V2ThreadCompactStartResponse,
+  ThreadForkParams: CodexSchema.V2ThreadForkParams,
+  ThreadForkResponse: CodexSchema.V2ThreadForkResponse,
+  ThreadGoalClearedNotification: CodexSchema.V2ThreadGoalClearedNotification,
+  ThreadGoalUpdatedNotification: CodexSchema.V2ThreadGoalUpdatedNotification,
+  ThreadInjectItemsParams: CodexSchema.V2ThreadInjectItemsParams,
+  ThreadInjectItemsResponse: CodexSchema.V2ThreadInjectItemsResponse,
+  ThreadListParams: CodexSchema.V2ThreadListParams,
+  ThreadListResponse: CodexSchema.V2ThreadListResponse,
+  ThreadLoadedListParams: CodexSchema.V2ThreadLoadedListParams,
+  ThreadLoadedListResponse: CodexSchema.V2ThreadLoadedListResponse,
+  ThreadMetadataUpdateParams: CodexSchema.V2ThreadMetadataUpdateParams,
+  ThreadMetadataUpdateResponse: CodexSchema.V2ThreadMetadataUpdateResponse,
+  ThreadNameUpdatedNotification: CodexSchema.V2ThreadNameUpdatedNotification,
+  ThreadReadParams: CodexSchema.V2ThreadReadParams,
+  ThreadReadResponse: CodexSchema.V2ThreadReadResponse,
+  ThreadRealtimeClosedNotification: CodexSchema.V2ThreadRealtimeClosedNotification,
+  ThreadRealtimeErrorNotification: CodexSchema.V2ThreadRealtimeErrorNotification,
+  ThreadRealtimeItemAddedNotification: CodexSchema.V2ThreadRealtimeItemAddedNotification,
+  ThreadRealtimeOutputAudioDeltaNotification:
+    CodexSchema.V2ThreadRealtimeOutputAudioDeltaNotification,
+  ThreadRealtimeSdpNotification: CodexSchema.V2ThreadRealtimeSdpNotification,
+  ThreadRealtimeStartedNotification: CodexSchema.V2ThreadRealtimeStartedNotification,
+  ThreadRealtimeTranscriptDeltaNotification:
+    CodexSchema.V2ThreadRealtimeTranscriptDeltaNotification,
+  ThreadRealtimeTranscriptDoneNotification: CodexSchema.V2ThreadRealtimeTranscriptDoneNotification,
+  ThreadResumeParams: CodexSchema.V2ThreadResumeParams,
+  ThreadResumeResponse: CodexSchema.V2ThreadResumeResponse,
+  ThreadRollbackParams: CodexSchema.V2ThreadRollbackParams,
+  ThreadRollbackResponse: CodexSchema.V2ThreadRollbackResponse,
+  ThreadSetNameParams: CodexSchema.V2ThreadSetNameParams,
+  ThreadSetNameResponse: CodexSchema.V2ThreadSetNameResponse,
+  ThreadShellCommandParams: CodexSchema.V2ThreadShellCommandParams,
+  ThreadShellCommandResponse: CodexSchema.V2ThreadShellCommandResponse,
+  ThreadStartedNotification: CodexSchema.V2ThreadStartedNotification,
+  ThreadStartParams: CodexSchema.V2ThreadStartParams,
+  ThreadStartResponse: CodexSchema.V2ThreadStartResponse,
+  ThreadStatusChangedNotification: CodexSchema.V2ThreadStatusChangedNotification,
+  ThreadTokenUsageUpdatedNotification: CodexSchema.V2ThreadTokenUsageUpdatedNotification,
+  ThreadUnarchivedNotification: CodexSchema.V2ThreadUnarchivedNotification,
+  ThreadUnarchiveParams: CodexSchema.V2ThreadUnarchiveParams,
+  ThreadUnarchiveResponse: CodexSchema.V2ThreadUnarchiveResponse,
+  ThreadUnsubscribeParams: CodexSchema.V2ThreadUnsubscribeParams,
+  ThreadUnsubscribeResponse: CodexSchema.V2ThreadUnsubscribeResponse,
+  TurnCompletedNotification: CodexSchema.V2TurnCompletedNotification,
+  TurnDiffUpdatedNotification: CodexSchema.V2TurnDiffUpdatedNotification,
+  TurnInterruptParams: CodexSchema.V2TurnInterruptParams,
+  TurnInterruptResponse: CodexSchema.V2TurnInterruptResponse,
+  TurnPlanUpdatedNotification: CodexSchema.V2TurnPlanUpdatedNotification,
+  TurnStartedNotification: CodexSchema.V2TurnStartedNotification,
+  TurnStartParams: CodexSchema.V2TurnStartParams,
+  TurnStartResponse: CodexSchema.V2TurnStartResponse,
+  TurnSteerParams: CodexSchema.V2TurnSteerParams,
+  TurnSteerResponse: CodexSchema.V2TurnSteerResponse,
+  WarningNotification: CodexSchema.V2WarningNotification,
+  WindowsSandboxReadinessResponse: CodexSchema.V2WindowsSandboxReadinessResponse,
+  WindowsSandboxSetupCompletedNotification: CodexSchema.V2WindowsSandboxSetupCompletedNotification,
+  WindowsSandboxSetupStartParams: CodexSchema.V2WindowsSandboxSetupStartParams,
+  WindowsSandboxSetupStartResponse: CodexSchema.V2WindowsSandboxSetupStartResponse,
+  WindowsWorldWritableWarningNotification: CodexSchema.V2WindowsWorldWritableWarningNotification,
+} as const;
diff --git a/packages/effect-codex-app-server/src/_generated/schema.gen.ts b/packages/effect-codex-app-server/src/_generated/schema.gen.ts
new file mode 100644
index 00000000000..8cb1f622fc6
--- /dev/null
+++ b/packages/effect-codex-app-server/src/_generated/schema.gen.ts
@@ -0,0 +1,36615 @@
+// This file is generated by the effect-codex-app-server package. Do not edit manually.
+// Upstream protocol ref: 07b695190f30a450e4921f71f77473e564395c59
+
+import * as Schema from "effect/Schema";
+
+export type ApplyPatchApprovalParams__FileChange =
+  | { readonly content: string; readonly type: "add" }
+  | { readonly content: string; readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update"; readonly unified_diff: string };
+export const ApplyPatchApprovalParams__FileChange = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.String,
+      type: Schema.Literal("add").annotate({ title: "AddFileChangeType" }),
+    }).annotate({ title: "AddFileChange" }),
+    Schema.Struct({
+      content: Schema.String,
+      type: Schema.Literal("delete").annotate({ title: "DeleteFileChangeType" }),
+    }).annotate({ title: "DeleteFileChange" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdateFileChangeType" }),
+      unified_diff: Schema.String,
+    }).annotate({ title: "UpdateFileChange" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ApplyPatchApprovalParams__ThreadId = string;
+export const ApplyPatchApprovalParams__ThreadId = Schema.String;
+
+export type ApplyPatchApprovalResponse__NetworkPolicyRuleAction = "allow" | "deny";
+export const ApplyPatchApprovalResponse__NetworkPolicyRuleAction = Schema.Literals([
+  "allow",
+  "deny",
+]);
+
+export type ChatgptAuthTokensRefreshParams__ChatgptAuthTokensRefreshReason = "unauthorized";
+export const ChatgptAuthTokensRefreshParams__ChatgptAuthTokensRefreshReason =
+  Schema.Literal("unauthorized");
+
+export type ClientRequest__AbsolutePathBuf = string;
+export const ClientRequest__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type ClientRequest__AddCreditsNudgeCreditType = "credits" | "usage_limit";
+export const ClientRequest__AddCreditsNudgeCreditType = Schema.Literals(["credits", "usage_limit"]);
+
+export type ClientRequest__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const ClientRequest__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type ClientRequest__AppsListParams = {
+  readonly cursor?: string | null;
+  readonly forceRefetch?: boolean;
+  readonly limit?: number | null;
+  readonly threadId?: string | null;
+};
+export const ClientRequest__AppsListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  forceRefetch: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "When true, bypass app caches and fetch the latest data from sources.",
+    }),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional thread id used to evaluate app feature gating from that thread's config.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "EXPERIMENTAL - list available apps/connectors." });
+
+export type ClientRequest__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const ClientRequest__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__CancelLoginAccountParams = { readonly loginId: string };
+export const ClientRequest__CancelLoginAccountParams = Schema.Struct({ loginId: Schema.String });
+
+export type ClientRequest__ClientInfo = {
+  readonly name: string;
+  readonly title?: string | null;
+  readonly version: string;
+};
+export const ClientRequest__ClientInfo = Schema.Struct({
+  name: Schema.String,
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  version: Schema.String,
+});
+
+export type ClientRequest__CommandExecResizeParams = {
+  readonly processId: string;
+  readonly size: { readonly cols: number; readonly rows: number };
+};
+export const ClientRequest__CommandExecResizeParams = Schema.Struct({
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+  size: Schema.Struct({
+    cols: Schema.Number.annotate({
+      description: "Terminal width in character cells.",
+      format: "uint16",
+    })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    rows: Schema.Number.annotate({
+      description: "Terminal height in character cells.",
+      format: "uint16",
+    })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({ description: "PTY size in character cells for `command/exec` PTY sessions." }),
+}).annotate({ description: "Resize a running PTY-backed `command/exec` session." });
+
+export type ClientRequest__CommandExecTerminalSize = {
+  readonly cols: number;
+  readonly rows: number;
+};
+export const ClientRequest__CommandExecTerminalSize = Schema.Struct({
+  cols: Schema.Number.annotate({
+    description: "Terminal width in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  rows: Schema.Number.annotate({
+    description: "Terminal height in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({ description: "PTY size in character cells for `command/exec` PTY sessions." });
+
+export type ClientRequest__CommandExecTerminateParams = { readonly processId: string };
+export const ClientRequest__CommandExecTerminateParams = Schema.Struct({
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+}).annotate({ description: "Terminate a running `command/exec` session." });
+
+export type ClientRequest__CommandExecWriteParams = {
+  readonly closeStdin?: boolean;
+  readonly deltaBase64?: string | null;
+  readonly processId: string;
+};
+export const ClientRequest__CommandExecWriteParams = Schema.Struct({
+  closeStdin: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Close stdin after writing `deltaBase64`, if present.",
+    }),
+  ),
+  deltaBase64: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional base64-encoded stdin bytes to write." }),
+      Schema.Null,
+    ]),
+  ),
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+}).annotate({
+  description: "Write stdin bytes to a running `command/exec` session, close stdin, or both.",
+});
+
+export type ClientRequest__CommandMigration = { readonly name: string };
+export const ClientRequest__CommandMigration = Schema.Struct({ name: Schema.String });
+
+export type ClientRequest__ConfigReadParams = {
+  readonly cwd?: string | null;
+  readonly includeLayers?: boolean;
+};
+export const ClientRequest__ConfigReadParams = Schema.Struct({
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional working directory to resolve project config layers. If specified, return the effective config as seen from that directory (i.e., including any project layers between `cwd` and the project/repo root).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  includeLayers: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+});
+
+export type ClientRequest__ExperimentalFeatureEnablementSetParams = {
+  readonly enablement: { readonly [x: string]: boolean };
+};
+export const ClientRequest__ExperimentalFeatureEnablementSetParams = Schema.Struct({
+  enablement: Schema.Record(Schema.String, Schema.Boolean).annotate({
+    description:
+      "Process-wide runtime feature enablement keyed by canonical feature name.\n\nOnly named features are updated. Omitted features are left unchanged. Send an empty map for a no-op.",
+  }),
+});
+
+export type ClientRequest__ExperimentalFeatureListParams = {
+  readonly cursor?: string | null;
+  readonly limit?: number | null;
+};
+export const ClientRequest__ExperimentalFeatureListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__ExternalAgentConfigDetectParams = {
+  readonly cwds?: ReadonlyArray<string> | null;
+  readonly includeHome?: boolean;
+};
+export const ClientRequest__ExternalAgentConfigDetectParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description: "Zero or more working directories to include for repo-scoped detection.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  includeHome: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "If true, include detection under the user's home (~/.claude, ~/.codex, etc.).",
+    }),
+  ),
+});
+
+export type ClientRequest__ExternalAgentConfigMigrationItemType =
+  | "AGENTS_MD"
+  | "CONFIG"
+  | "SKILLS"
+  | "PLUGINS"
+  | "MCP_SERVER_CONFIG"
+  | "SUBAGENTS"
+  | "HOOKS"
+  | "COMMANDS"
+  | "SESSIONS";
+export const ClientRequest__ExternalAgentConfigMigrationItemType = Schema.Literals([
+  "AGENTS_MD",
+  "CONFIG",
+  "SKILLS",
+  "PLUGINS",
+  "MCP_SERVER_CONFIG",
+  "SUBAGENTS",
+  "HOOKS",
+  "COMMANDS",
+  "SESSIONS",
+]);
+
+export type ClientRequest__FeedbackUploadParams = {
+  readonly classification: string;
+  readonly extraLogFiles?: ReadonlyArray<string> | null;
+  readonly includeLogs: boolean;
+  readonly reason?: string | null;
+  readonly tags?: { readonly [x: string]: string } | null;
+  readonly threadId?: string | null;
+};
+export const ClientRequest__FeedbackUploadParams = Schema.Struct({
+  classification: Schema.String,
+  extraLogFiles: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  includeLogs: Schema.Boolean,
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  tags: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+  ),
+  threadId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ClientRequest__FileSystemAccessMode = "read" | "write" | "none";
+export const ClientRequest__FileSystemAccessMode = Schema.Literals(["read", "write", "none"]);
+
+export type ClientRequest__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const ClientRequest__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__FsCopyParams = {
+  readonly destinationPath: string;
+  readonly recursive?: boolean;
+  readonly sourcePath: string;
+};
+export const ClientRequest__FsCopyParams = Schema.Struct({
+  destinationPath: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  recursive: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Required for directory copies; ignored for file copies.",
+    }),
+  ),
+  sourcePath: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ description: "Copy a file or directory tree on the host filesystem." });
+
+export type ClientRequest__FsCreateDirectoryParams = {
+  readonly path: string;
+  readonly recursive?: boolean | null;
+};
+export const ClientRequest__FsCreateDirectoryParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  recursive: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "Whether parent directories should also be created. Defaults to `true`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Create a directory on the host filesystem." });
+
+export type ClientRequest__FsGetMetadataParams = { readonly path: string };
+export const ClientRequest__FsGetMetadataParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ description: "Request metadata for an absolute path." });
+
+export type ClientRequest__FsReadDirectoryParams = { readonly path: string };
+export const ClientRequest__FsReadDirectoryParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ description: "List direct child names for a directory." });
+
+export type ClientRequest__FsReadFileParams = { readonly path: string };
+export const ClientRequest__FsReadFileParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ description: "Read a file from the host filesystem." });
+
+export type ClientRequest__FsRemoveParams = {
+  readonly force?: boolean | null;
+  readonly path: string;
+  readonly recursive?: boolean | null;
+};
+export const ClientRequest__FsRemoveParams = Schema.Struct({
+  force: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "Whether missing paths should be ignored. Defaults to `true`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  recursive: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "Whether directory removal should recurse. Defaults to `true`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Remove a file or directory tree from the host filesystem." });
+
+export type ClientRequest__FsUnwatchParams = { readonly watchId: string };
+export const ClientRequest__FsUnwatchParams = Schema.Struct({
+  watchId: Schema.String.annotate({
+    description: "Watch identifier previously provided to `fs/watch`.",
+  }),
+}).annotate({ description: "Stop filesystem watch notifications for a prior `fs/watch`." });
+
+export type ClientRequest__FsWatchParams = { readonly path: string; readonly watchId: string };
+export const ClientRequest__FsWatchParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  watchId: Schema.String.annotate({
+    description: "Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.",
+  }),
+}).annotate({ description: "Start filesystem watch notifications for an absolute path." });
+
+export type ClientRequest__FsWriteFileParams = {
+  readonly dataBase64: string;
+  readonly path: string;
+};
+export const ClientRequest__FsWriteFileParams = Schema.Struct({
+  dataBase64: Schema.String.annotate({ description: "File contents encoded as base64." }),
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ description: "Write a file on the host filesystem." });
+
+export type ClientRequest__FuzzyFileSearchParams = {
+  readonly cancellationToken?: string | null;
+  readonly query: string;
+  readonly roots: ReadonlyArray<string>;
+};
+export const ClientRequest__FuzzyFileSearchParams = Schema.Struct({
+  cancellationToken: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  query: Schema.String,
+  roots: Schema.Array(Schema.String),
+});
+
+export type ClientRequest__GetAccountParams = { readonly refreshToken?: boolean };
+export const ClientRequest__GetAccountParams = Schema.Struct({
+  refreshToken: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "When `true`, requests a proactive token refresh before returning.\n\nIn managed auth mode this triggers the normal refresh-token flow. In external auth mode this flag is ignored. Clients should refresh tokens themselves and call `account/login/start` with `chatgptAuthTokens`.",
+      default: false,
+    }),
+  ),
+});
+
+export type ClientRequest__HookMigration = { readonly name: string };
+export const ClientRequest__HookMigration = Schema.Struct({ name: Schema.String });
+
+export type ClientRequest__HooksListParams = { readonly cwds?: ReadonlyArray<string> };
+export const ClientRequest__HooksListParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      description: "When empty, defaults to the current session working directory.",
+    }),
+  ),
+});
+
+export type ClientRequest__ImageDetail = "auto" | "low" | "high" | "original";
+export const ClientRequest__ImageDetail = Schema.Literals(["auto", "low", "high", "original"]);
+
+export type ClientRequest__InitializeCapabilities = {
+  readonly experimentalApi?: boolean;
+  readonly optOutNotificationMethods?: ReadonlyArray<string> | null;
+};
+export const ClientRequest__InitializeCapabilities = Schema.Struct({
+  experimentalApi: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Opt into receiving experimental API methods and fields.",
+      default: false,
+    }),
+  ),
+  optOutNotificationMethods: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Exact notification method names that should be suppressed for this connection (for example `thread/started`).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Client-declared capabilities negotiated during initialize." });
+
+export type ClientRequest__LocalShellAction = {
+  readonly command: ReadonlyArray<string>;
+  readonly env?: { readonly [x: string]: string } | null;
+  readonly timeout_ms?: number | null;
+  readonly type: "exec";
+  readonly user?: string | null;
+  readonly working_directory?: string | null;
+};
+export const ClientRequest__LocalShellAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.Array(Schema.String),
+      env: Schema.optionalKey(
+        Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+      ),
+      timeout_ms: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint64" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("exec").annotate({ title: "ExecLocalShellActionType" }),
+      user: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      working_directory: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "ExecLocalShellAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__LocalShellStatus = "completed" | "in_progress" | "incomplete";
+export const ClientRequest__LocalShellStatus = Schema.Literals([
+  "completed",
+  "in_progress",
+  "incomplete",
+]);
+
+export type ClientRequest__LoginAccountParams =
+  | { readonly apiKey: string; readonly type: "apiKey" }
+  | { readonly codexStreamlinedLogin?: boolean; readonly type: "chatgpt" }
+  | { readonly type: "chatgptDeviceCode" }
+  | {
+      readonly accessToken: string;
+      readonly chatgptAccountId: string;
+      readonly chatgptPlanType?: string | null;
+      readonly type: "chatgptAuthTokens";
+    };
+export const ClientRequest__LoginAccountParams = Schema.Union(
+  [
+    Schema.Struct({
+      apiKey: Schema.String,
+      type: Schema.Literal("apiKey").annotate({ title: "ApiKeyLoginAccountParamsType" }),
+    }).annotate({ title: "ApiKeyLoginAccountParams" }),
+    Schema.Struct({
+      codexStreamlinedLogin: Schema.optionalKey(Schema.Boolean),
+      type: Schema.Literal("chatgpt").annotate({ title: "ChatgptLoginAccountParamsType" }),
+    }).annotate({ title: "ChatgptLoginAccountParams" }),
+    Schema.Struct({
+      type: Schema.Literal("chatgptDeviceCode").annotate({
+        title: "ChatgptDeviceCodeLoginAccountParamsType",
+      }),
+    }).annotate({ title: "ChatgptDeviceCodeLoginAccountParams" }),
+    Schema.Struct({
+      accessToken: Schema.String.annotate({
+        description:
+          "Access token (JWT) supplied by the client. This token is used for backend API requests and email extraction.",
+      }),
+      chatgptAccountId: Schema.String.annotate({
+        description: "Workspace/account identifier supplied by the client.",
+      }),
+      chatgptPlanType: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "Optional plan type supplied by the client.\n\nWhen `null`, Codex attempts to derive the plan type from access-token claims. If unavailable, the plan defaults to `unknown`.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("chatgptAuthTokens").annotate({
+        title: "ChatgptAuthTokensLoginAccountParamsType",
+      }),
+    }).annotate({
+      title: "ChatgptAuthTokensLoginAccountParams",
+      description:
+        "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE. The access token must contain the same scopes that Codex-managed ChatGPT auth tokens have.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__MarketplaceAddParams = {
+  readonly refName?: string | null;
+  readonly source: string;
+  readonly sparsePaths?: ReadonlyArray<string> | null;
+};
+export const ClientRequest__MarketplaceAddParams = Schema.Struct({
+  refName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  source: Schema.String,
+  sparsePaths: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+});
+
+export type ClientRequest__MarketplaceRemoveParams = { readonly marketplaceName: string };
+export const ClientRequest__MarketplaceRemoveParams = Schema.Struct({
+  marketplaceName: Schema.String,
+});
+
+export type ClientRequest__MarketplaceUpgradeParams = { readonly marketplaceName?: string | null };
+export const ClientRequest__MarketplaceUpgradeParams = Schema.Struct({
+  marketplaceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ClientRequest__McpResourceReadParams = {
+  readonly server: string;
+  readonly threadId?: string | null;
+  readonly uri: string;
+};
+export const ClientRequest__McpResourceReadParams = Schema.Struct({
+  server: Schema.String,
+  threadId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  uri: Schema.String,
+});
+
+export type ClientRequest__McpServerMigration = { readonly name: string };
+export const ClientRequest__McpServerMigration = Schema.Struct({ name: Schema.String });
+
+export type ClientRequest__McpServerOauthLoginParams = {
+  readonly name: string;
+  readonly scopes?: ReadonlyArray<string> | null;
+  readonly timeoutSecs?: number | null;
+};
+export const ClientRequest__McpServerOauthLoginParams = Schema.Struct({
+  name: Schema.String,
+  scopes: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  timeoutSecs: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+});
+
+export type ClientRequest__McpServerStatusDetail = "full" | "toolsAndAuthOnly";
+export const ClientRequest__McpServerStatusDetail = Schema.Literals(["full", "toolsAndAuthOnly"]);
+
+export type ClientRequest__McpServerToolCallParams = {
+  readonly _meta?: unknown;
+  readonly arguments?: unknown;
+  readonly server: string;
+  readonly threadId: string;
+  readonly tool: string;
+};
+export const ClientRequest__McpServerToolCallParams = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  arguments: Schema.optionalKey(Schema.Unknown),
+  server: Schema.String,
+  threadId: Schema.String,
+  tool: Schema.String,
+});
+
+export type ClientRequest__MergeStrategy = "replace" | "upsert";
+export const ClientRequest__MergeStrategy = Schema.Literals(["replace", "upsert"]);
+
+export type ClientRequest__MessagePhase = "commentary" | "final_answer";
+export const ClientRequest__MessagePhase = Schema.Literals(["commentary", "final_answer"]).annotate(
+  {
+    description:
+      'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+  },
+);
+
+export type ClientRequest__ModeKind = "plan" | "default";
+export const ClientRequest__ModeKind = Schema.Literals(["plan", "default"]).annotate({
+  description: "Initial collaboration mode to use when the TUI starts.",
+});
+
+export type ClientRequest__ModelListParams = {
+  readonly cursor?: string | null;
+  readonly includeHidden?: boolean | null;
+  readonly limit?: number | null;
+};
+export const ClientRequest__ModelListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  includeHidden: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "When true, include models that are hidden from the default picker list.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__ModelProviderCapabilitiesReadParams = {};
+export const ClientRequest__ModelProviderCapabilitiesReadParams = Schema.Struct({});
+
+export type ClientRequest__PermissionProfileNetworkPermissions = { readonly enabled: boolean };
+export const ClientRequest__PermissionProfileNetworkPermissions = Schema.Struct({
+  enabled: Schema.Boolean,
+});
+
+export type ClientRequest__Personality = "none" | "friendly" | "pragmatic";
+export const ClientRequest__Personality = Schema.Literals(["none", "friendly", "pragmatic"]);
+
+export type ClientRequest__PluginListMarketplaceKind =
+  | "local"
+  | "workspace-directory"
+  | "shared-with-me";
+export const ClientRequest__PluginListMarketplaceKind = Schema.Literals([
+  "local",
+  "workspace-directory",
+  "shared-with-me",
+]);
+
+export type ClientRequest__PluginShareDeleteParams = { readonly remotePluginId: string };
+export const ClientRequest__PluginShareDeleteParams = Schema.Struct({
+  remotePluginId: Schema.String,
+});
+
+export type ClientRequest__PluginShareDiscoverability = "LISTED" | "UNLISTED" | "PRIVATE";
+export const ClientRequest__PluginShareDiscoverability = Schema.Literals([
+  "LISTED",
+  "UNLISTED",
+  "PRIVATE",
+]);
+
+export type ClientRequest__PluginShareListParams = {};
+export const ClientRequest__PluginShareListParams = Schema.Struct({});
+
+export type ClientRequest__PluginSharePrincipalType = "user" | "group" | "workspace";
+export const ClientRequest__PluginSharePrincipalType = Schema.Literals([
+  "user",
+  "group",
+  "workspace",
+]);
+
+export type ClientRequest__PluginSkillReadParams = {
+  readonly remoteMarketplaceName: string;
+  readonly remotePluginId: string;
+  readonly skillName: string;
+};
+export const ClientRequest__PluginSkillReadParams = Schema.Struct({
+  remoteMarketplaceName: Schema.String,
+  remotePluginId: Schema.String,
+  skillName: Schema.String,
+});
+
+export type ClientRequest__PluginUninstallParams = { readonly pluginId: string };
+export const ClientRequest__PluginUninstallParams = Schema.Struct({ pluginId: Schema.String });
+
+export type ClientRequest__PluginsMigration = {
+  readonly marketplaceName: string;
+  readonly pluginNames: ReadonlyArray<string>;
+};
+export const ClientRequest__PluginsMigration = Schema.Struct({
+  marketplaceName: Schema.String,
+  pluginNames: Schema.Array(Schema.String),
+});
+
+export type ClientRequest__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const ClientRequest__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type ClientRequest__ReasoningItemContent =
+  | { readonly text: string; readonly type: "reasoning_text" }
+  | { readonly text: string; readonly type: "text" };
+export const ClientRequest__ReasoningItemContent = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("reasoning_text").annotate({
+        title: "ReasoningTextReasoningItemContentType",
+      }),
+    }).annotate({ title: "ReasoningTextReasoningItemContent" }),
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("text").annotate({ title: "TextReasoningItemContentType" }),
+    }).annotate({ title: "TextReasoningItemContent" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ReasoningItemReasoningSummary = {
+  readonly text: string;
+  readonly type: "summary_text";
+};
+export const ClientRequest__ReasoningItemReasoningSummary = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("summary_text").annotate({
+        title: "SummaryTextReasoningItemReasoningSummaryType",
+      }),
+    }).annotate({ title: "SummaryTextReasoningItemReasoningSummary" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ReasoningSummary = "auto" | "concise" | "detailed" | "none";
+export const ClientRequest__ReasoningSummary = Schema.Union(
+  [
+    Schema.Literals(["auto", "concise", "detailed"]),
+    Schema.Literal("none").annotate({ description: "Option to disable reasoning summaries." }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries",
+});
+
+export type ClientRequest__RequestId = string | number;
+export const ClientRequest__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type ClientRequest__ResponsesApiWebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "open_page"; readonly url?: string | null }
+  | {
+      readonly pattern?: string | null;
+      readonly type: "find_in_page";
+      readonly url?: string | null;
+    }
+  | { readonly type: "other" };
+export const ClientRequest__ResponsesApiWebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchResponsesApiWebSearchActionType" }),
+    }).annotate({ title: "SearchResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("open_page").annotate({
+        title: "OpenPageResponsesApiWebSearchActionType",
+      }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("find_in_page").annotate({
+        title: "FindInPageResponsesApiWebSearchActionType",
+      }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherResponsesApiWebSearchActionType" }),
+    }).annotate({ title: "OtherResponsesApiWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ReviewDelivery = "inline" | "detached";
+export const ClientRequest__ReviewDelivery = Schema.Literals(["inline", "detached"]);
+
+export type ClientRequest__ReviewTarget =
+  | { readonly type: "uncommittedChanges" }
+  | { readonly branch: string; readonly type: "baseBranch" }
+  | { readonly sha: string; readonly title?: string | null; readonly type: "commit" }
+  | { readonly instructions: string; readonly type: "custom" };
+export const ClientRequest__ReviewTarget = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("uncommittedChanges").annotate({
+        title: "UncommittedChangesReviewTargetType",
+      }),
+    }).annotate({
+      title: "UncommittedChangesReviewTarget",
+      description: "Review the working tree: staged, unstaged, and untracked files.",
+    }),
+    Schema.Struct({
+      branch: Schema.String,
+      type: Schema.Literal("baseBranch").annotate({ title: "BaseBranchReviewTargetType" }),
+    }).annotate({
+      title: "BaseBranchReviewTarget",
+      description: "Review changes between the current branch and the given base branch.",
+    }),
+    Schema.Struct({
+      sha: Schema.String,
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Optional human-readable label (e.g., commit subject) for UIs.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("commit").annotate({ title: "CommitReviewTargetType" }),
+    }).annotate({
+      title: "CommitReviewTarget",
+      description: "Review the changes introduced by a specific commit.",
+    }),
+    Schema.Struct({
+      instructions: Schema.String,
+      type: Schema.Literal("custom").annotate({ title: "CustomReviewTargetType" }),
+    }).annotate({
+      title: "CustomReviewTarget",
+      description: "Arbitrary instructions, equivalent to the old free-form prompt.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export const ClientRequest__SandboxMode = Schema.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access",
+]);
+
+export type ClientRequest__SessionMigration = {
+  readonly cwd: string;
+  readonly path: string;
+  readonly title?: string | null;
+};
+export const ClientRequest__SessionMigration = Schema.Struct({
+  cwd: Schema.String,
+  path: Schema.String,
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ClientRequest__SkillsListExtraRootsForCwd = {
+  readonly cwd: string;
+  readonly extraUserRoots: ReadonlyArray<string>;
+};
+export const ClientRequest__SkillsListExtraRootsForCwd = Schema.Struct({
+  cwd: Schema.String,
+  extraUserRoots: Schema.Array(Schema.String),
+});
+
+export type ClientRequest__SortDirection = "asc" | "desc";
+export const ClientRequest__SortDirection = Schema.Literals(["asc", "desc"]);
+
+export type ClientRequest__SubagentMigration = { readonly name: string };
+export const ClientRequest__SubagentMigration = Schema.Struct({ name: Schema.String });
+
+export type ClientRequest__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const ClientRequest__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__ThreadApproveGuardianDeniedActionParams = {
+  readonly event: unknown;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadApproveGuardianDeniedActionParams = Schema.Struct({
+  event: Schema.Unknown.annotate({
+    description: "Serialized `codex_protocol::protocol::GuardianAssessmentEvent`.",
+  }),
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadArchiveParams = { readonly threadId: string };
+export const ClientRequest__ThreadArchiveParams = Schema.Struct({ threadId: Schema.String });
+
+export type ClientRequest__ThreadCompactStartParams = { readonly threadId: string };
+export const ClientRequest__ThreadCompactStartParams = Schema.Struct({ threadId: Schema.String });
+
+export type ClientRequest__ThreadInjectItemsParams = {
+  readonly items: ReadonlyArray<unknown>;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadInjectItemsParams = Schema.Struct({
+  items: Schema.Array(Schema.Unknown).annotate({
+    description: "Raw Responses API items to append to the thread's model-visible history.",
+  }),
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadListCwdFilter = string | ReadonlyArray<string>;
+export const ClientRequest__ThreadListCwdFilter = Schema.Union([
+  Schema.String,
+  Schema.Array(Schema.String),
+]);
+
+export type ClientRequest__ThreadLoadedListParams = {
+  readonly cursor?: string | null;
+  readonly limit?: number | null;
+};
+export const ClientRequest__ThreadLoadedListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to no limit.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__ThreadMetadataGitInfoUpdateParams = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const ClientRequest__ThreadMetadataGitInfoUpdateParams = Schema.Struct({
+  branch: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Omit to leave the stored branch unchanged, set to `null` to clear it, or provide a non-empty string to replace it.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  originUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Omit to leave the stored origin URL unchanged, set to `null` to clear it, or provide a non-empty string to replace it.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sha: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Omit to leave the stored commit unchanged, set to `null` to clear it, or provide a non-empty string to replace it.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__ThreadReadParams = {
+  readonly includeTurns?: boolean;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadReadParams = Schema.Struct({
+  includeTurns: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "When true, include turns and their items from rollout history.",
+      default: false,
+    }),
+  ),
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadRollbackParams = {
+  readonly numTurns: number;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadRollbackParams = Schema.Struct({
+  numTurns: Schema.Number.annotate({
+    description:
+      "The number of turns to drop from the end of the thread. Must be >= 1.\n\nThis only modifies the thread's history and does not revert local file changes that have been made by the agent. Clients are responsible for reverting these changes.",
+    format: "uint32",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadSetNameParams = {
+  readonly name: string;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadSetNameParams = Schema.Struct({
+  name: Schema.String,
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadShellCommandParams = {
+  readonly command: string;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadShellCommandParams = Schema.Struct({
+  command: Schema.String.annotate({
+    description:
+      "Shell command string evaluated by the thread's configured shell. Unlike `command/exec`, this intentionally preserves shell syntax such as pipes, redirects, and quoting. This runs unsandboxed with full access rather than inheriting the thread sandbox policy.",
+  }),
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadSortKey = "created_at" | "updated_at";
+export const ClientRequest__ThreadSortKey = Schema.Literals(["created_at", "updated_at"]);
+
+export type ClientRequest__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const ClientRequest__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type ClientRequest__ThreadSourceKind =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "subAgent"
+  | "subAgentReview"
+  | "subAgentCompact"
+  | "subAgentThreadSpawn"
+  | "subAgentOther"
+  | "unknown";
+export const ClientRequest__ThreadSourceKind = Schema.Literals([
+  "cli",
+  "vscode",
+  "exec",
+  "appServer",
+  "subAgent",
+  "subAgentReview",
+  "subAgentCompact",
+  "subAgentThreadSpawn",
+  "subAgentOther",
+  "unknown",
+]);
+
+export type ClientRequest__ThreadStartSource = "startup" | "clear";
+export const ClientRequest__ThreadStartSource = Schema.Literals(["startup", "clear"]);
+
+export type ClientRequest__ThreadUnarchiveParams = { readonly threadId: string };
+export const ClientRequest__ThreadUnarchiveParams = Schema.Struct({ threadId: Schema.String });
+
+export type ClientRequest__ThreadUnsubscribeParams = { readonly threadId: string };
+export const ClientRequest__ThreadUnsubscribeParams = Schema.Struct({ threadId: Schema.String });
+
+export type ClientRequest__TurnInterruptParams = {
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ClientRequest__TurnInterruptParams = Schema.Struct({
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ClientRequest__WindowsSandboxSetupMode = "elevated" | "unelevated";
+export const ClientRequest__WindowsSandboxSetupMode = Schema.Literals(["elevated", "unelevated"]);
+
+export type CommandExecutionRequestApprovalParams__AbsolutePathBuf = string;
+export const CommandExecutionRequestApprovalParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type CommandExecutionRequestApprovalParams__AdditionalNetworkPermissions = {
+  readonly enabled?: boolean | null;
+};
+export const CommandExecutionRequestApprovalParams__AdditionalNetworkPermissions = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+});
+
+export type CommandExecutionRequestApprovalParams__FileSystemAccessMode = "read" | "write" | "none";
+export const CommandExecutionRequestApprovalParams__FileSystemAccessMode = Schema.Literals([
+  "read",
+  "write",
+  "none",
+]);
+
+export type CommandExecutionRequestApprovalParams__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const CommandExecutionRequestApprovalParams__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type CommandExecutionRequestApprovalParams__NetworkApprovalProtocol =
+  | "http"
+  | "https"
+  | "socks5Tcp"
+  | "socks5Udp";
+export const CommandExecutionRequestApprovalParams__NetworkApprovalProtocol = Schema.Literals([
+  "http",
+  "https",
+  "socks5Tcp",
+  "socks5Udp",
+]);
+
+export type CommandExecutionRequestApprovalParams__NetworkPolicyRuleAction = "allow" | "deny";
+export const CommandExecutionRequestApprovalParams__NetworkPolicyRuleAction = Schema.Literals([
+  "allow",
+  "deny",
+]);
+
+export type CommandExecutionRequestApprovalResponse__NetworkPolicyRuleAction = "allow" | "deny";
+export const CommandExecutionRequestApprovalResponse__NetworkPolicyRuleAction = Schema.Literals([
+  "allow",
+  "deny",
+]);
+
+export type DynamicToolCallResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const DynamicToolCallResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ExecCommandApprovalParams__ParsedCommand =
+  | { readonly cmd: string; readonly name: string; readonly path: string; readonly type: "read" }
+  | { readonly cmd: string; readonly path?: string | null; readonly type: "list_files" }
+  | {
+      readonly cmd: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly cmd: string; readonly type: "unknown" };
+export const ExecCommandApprovalParams__ParsedCommand = Schema.Union(
+  [
+    Schema.Struct({
+      cmd: Schema.String,
+      name: Schema.String,
+      path: Schema.String.annotate({
+        description:
+          "(Best effort) Path to the file being read by the command. When possible, this is an absolute path, though when relative, it should be resolved against the `cwd`` that will be used to run the command to derive the absolute path.",
+      }),
+      type: Schema.Literal("read").annotate({ title: "ReadParsedCommandType" }),
+    }).annotate({ title: "ReadParsedCommand" }),
+    Schema.Struct({
+      cmd: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("list_files").annotate({ title: "ListFilesParsedCommandType" }),
+    }).annotate({ title: "ListFilesParsedCommand" }),
+    Schema.Struct({
+      cmd: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchParsedCommandType" }),
+    }).annotate({ title: "SearchParsedCommand" }),
+    Schema.Struct({
+      cmd: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownParsedCommandType" }),
+    }).annotate({ title: "UnknownParsedCommand" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ExecCommandApprovalParams__ThreadId = string;
+export const ExecCommandApprovalParams__ThreadId = Schema.String;
+
+export type ExecCommandApprovalResponse__NetworkPolicyRuleAction = "allow" | "deny";
+export const ExecCommandApprovalResponse__NetworkPolicyRuleAction = Schema.Literals([
+  "allow",
+  "deny",
+]);
+
+export type FileChangeRequestApprovalResponse__FileChangeApprovalDecision =
+  | "accept"
+  | "acceptForSession"
+  | "decline"
+  | "cancel";
+export const FileChangeRequestApprovalResponse__FileChangeApprovalDecision = Schema.Literals([
+  "accept",
+  "acceptForSession",
+  "decline",
+  "cancel",
+]);
+
+export type FuzzyFileSearchResponse__FuzzyFileSearchMatchType = "file" | "directory";
+export const FuzzyFileSearchResponse__FuzzyFileSearchMatchType = Schema.Literals([
+  "file",
+  "directory",
+]);
+
+export type FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchMatchType =
+  | "file"
+  | "directory";
+export const FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchMatchType = Schema.Literals([
+  "file",
+  "directory",
+]);
+
+export type JSONRPCError__JSONRPCErrorError = {
+  readonly code: number;
+  readonly data?: unknown;
+  readonly message: string;
+};
+export const JSONRPCError__JSONRPCErrorError = Schema.Struct({
+  code: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  data: Schema.optionalKey(Schema.Unknown),
+  message: Schema.String,
+});
+
+export type JSONRPCError__RequestId = string | number;
+export const JSONRPCError__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type JSONRPCMessage__JSONRPCErrorError = {
+  readonly code: number;
+  readonly data?: unknown;
+  readonly message: string;
+};
+export const JSONRPCMessage__JSONRPCErrorError = Schema.Struct({
+  code: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  data: Schema.optionalKey(Schema.Unknown),
+  message: Schema.String,
+});
+
+export type JSONRPCMessage__JSONRPCNotification = {
+  readonly method: string;
+  readonly params?: unknown;
+};
+export const JSONRPCMessage__JSONRPCNotification = Schema.Struct({
+  method: Schema.String,
+  params: Schema.optionalKey(Schema.Unknown),
+}).annotate({ description: "A notification which does not expect a response." });
+
+export type JSONRPCMessage__RequestId = string | number;
+export const JSONRPCMessage__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type JSONRPCMessage__W3cTraceContext = {
+  readonly traceparent?: string | null;
+  readonly tracestate?: string | null;
+};
+export const JSONRPCMessage__W3cTraceContext = Schema.Struct({
+  traceparent: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  tracestate: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type JSONRPCRequest__RequestId = string | number;
+export const JSONRPCRequest__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type JSONRPCRequest__W3cTraceContext = {
+  readonly traceparent?: string | null;
+  readonly tracestate?: string | null;
+};
+export const JSONRPCRequest__W3cTraceContext = Schema.Struct({
+  traceparent: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  tracestate: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type JSONRPCResponse__RequestId = string | number;
+export const JSONRPCResponse__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type McpServerElicitationRequestParams__McpElicitationArrayType = "array";
+export const McpServerElicitationRequestParams__McpElicitationArrayType = Schema.Literal("array");
+
+export type McpServerElicitationRequestParams__McpElicitationBooleanType = "boolean";
+export const McpServerElicitationRequestParams__McpElicitationBooleanType =
+  Schema.Literal("boolean");
+
+export type McpServerElicitationRequestParams__McpElicitationConstOption = {
+  readonly const: string;
+  readonly title: string;
+};
+export const McpServerElicitationRequestParams__McpElicitationConstOption = Schema.Struct({
+  const: Schema.String,
+  title: Schema.String,
+});
+
+export type McpServerElicitationRequestParams__McpElicitationNumberType = "number" | "integer";
+export const McpServerElicitationRequestParams__McpElicitationNumberType = Schema.Literals([
+  "number",
+  "integer",
+]);
+
+export type McpServerElicitationRequestParams__McpElicitationObjectType = "object";
+export const McpServerElicitationRequestParams__McpElicitationObjectType = Schema.Literal("object");
+
+export type McpServerElicitationRequestParams__McpElicitationStringFormat =
+  | "email"
+  | "uri"
+  | "date"
+  | "date-time";
+export const McpServerElicitationRequestParams__McpElicitationStringFormat = Schema.Literals([
+  "email",
+  "uri",
+  "date",
+  "date-time",
+]);
+
+export type McpServerElicitationRequestParams__McpElicitationStringType = "string";
+export const McpServerElicitationRequestParams__McpElicitationStringType = Schema.Literal("string");
+
+export type McpServerElicitationRequestResponse__McpServerElicitationAction =
+  | "accept"
+  | "decline"
+  | "cancel";
+export const McpServerElicitationRequestResponse__McpServerElicitationAction = Schema.Literals([
+  "accept",
+  "decline",
+  "cancel",
+]);
+
+export type PermissionsRequestApprovalParams__AbsolutePathBuf = string;
+export const PermissionsRequestApprovalParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type PermissionsRequestApprovalParams__AdditionalNetworkPermissions = {
+  readonly enabled?: boolean | null;
+};
+export const PermissionsRequestApprovalParams__AdditionalNetworkPermissions = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+});
+
+export type PermissionsRequestApprovalParams__FileSystemAccessMode = "read" | "write" | "none";
+export const PermissionsRequestApprovalParams__FileSystemAccessMode = Schema.Literals([
+  "read",
+  "write",
+  "none",
+]);
+
+export type PermissionsRequestApprovalParams__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const PermissionsRequestApprovalParams__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type PermissionsRequestApprovalResponse__AbsolutePathBuf = string;
+export const PermissionsRequestApprovalResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type PermissionsRequestApprovalResponse__AdditionalNetworkPermissions = {
+  readonly enabled?: boolean | null;
+};
+export const PermissionsRequestApprovalResponse__AdditionalNetworkPermissions = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+});
+
+export type PermissionsRequestApprovalResponse__FileSystemAccessMode = "read" | "write" | "none";
+export const PermissionsRequestApprovalResponse__FileSystemAccessMode = Schema.Literals([
+  "read",
+  "write",
+  "none",
+]);
+
+export type PermissionsRequestApprovalResponse__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const PermissionsRequestApprovalResponse__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__AbsolutePathBuf = string;
+export const ServerNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type ServerNotification__AccountLoginCompletedNotification = {
+  readonly error?: string | null;
+  readonly loginId?: string | null;
+  readonly success: boolean;
+};
+export const ServerNotification__AccountLoginCompletedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  loginId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  success: Schema.Boolean,
+});
+
+export type ServerNotification__AdditionalNetworkPermissions = {
+  readonly enabled?: boolean | null;
+};
+export const ServerNotification__AdditionalNetworkPermissions = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+});
+
+export type ServerNotification__AgentMessageDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__AgentMessageDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__AgentPath = string;
+export const ServerNotification__AgentPath = Schema.String;
+
+export type ServerNotification__AppBranding = {
+  readonly category?: string | null;
+  readonly developer?: string | null;
+  readonly isDiscoverableApp: boolean;
+  readonly privacyPolicy?: string | null;
+  readonly termsOfService?: string | null;
+  readonly website?: string | null;
+};
+export const ServerNotification__AppBranding = Schema.Struct({
+  category: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developer: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  isDiscoverableApp: Schema.Boolean,
+  privacyPolicy: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  termsOfService: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  website: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ description: "EXPERIMENTAL - app metadata returned by app-list APIs." });
+
+export type ServerNotification__AppReview = { readonly status: string };
+export const ServerNotification__AppReview = Schema.Struct({ status: Schema.String });
+
+export type ServerNotification__AppScreenshot = {
+  readonly fileId?: string | null;
+  readonly url?: string | null;
+  readonly userPrompt: string;
+};
+export const ServerNotification__AppScreenshot = Schema.Struct({
+  fileId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  userPrompt: Schema.String,
+});
+
+export type ServerNotification__AuthMode =
+  | "apikey"
+  | "chatgpt"
+  | "chatgptAuthTokens"
+  | "agentIdentity";
+export const ServerNotification__AuthMode = Schema.Literals([
+  "apikey",
+  "chatgpt",
+  "chatgptAuthTokens",
+  "agentIdentity",
+]).annotate({ description: "Authentication mode for OpenAI-backed providers." });
+
+export type ServerNotification__AutoReviewDecisionSource = "agent";
+export const ServerNotification__AutoReviewDecisionSource = Schema.Literal("agent").annotate({
+  description: "[UNSTABLE] Source that produced a terminal approval auto-review decision.",
+});
+
+export type ServerNotification__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const ServerNotification__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type ServerNotification__CommandExecOutputDeltaNotification = {
+  readonly capReached: boolean;
+  readonly deltaBase64: string;
+  readonly processId: string;
+  readonly stream: "stdout" | "stderr";
+};
+export const ServerNotification__CommandExecOutputDeltaNotification = Schema.Struct({
+  capReached: Schema.Boolean.annotate({
+    description:
+      "`true` on the final streamed chunk for a stream when `outputBytesCap` truncated later output on that stream.",
+  }),
+  deltaBase64: Schema.String.annotate({ description: "Base64-encoded output bytes." }),
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+  stream: Schema.Literals(["stdout", "stderr"]).annotate({
+    description: "Stream label for `command/exec/outputDelta` notifications.",
+  }),
+}).annotate({
+  description:
+    "Base64-encoded output chunk emitted for a streaming `command/exec` request.\n\nThese notifications are connection-scoped. If the originating connection closes, the server terminates the process.",
+});
+
+export type ServerNotification__CommandExecutionOutputDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__CommandExecutionOutputDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const ServerNotification__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type ServerNotification__ContextCompactedNotification = {
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ContextCompactedNotification = Schema.Struct({
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ description: "Deprecated: Use `ContextCompaction` item type instead." });
+
+export type ServerNotification__CreditsSnapshot = {
+  readonly balance?: string | null;
+  readonly hasCredits: boolean;
+  readonly unlimited: boolean;
+};
+export const ServerNotification__CreditsSnapshot = Schema.Struct({
+  balance: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  hasCredits: Schema.Boolean,
+  unlimited: Schema.Boolean,
+});
+
+export type ServerNotification__DeprecationNoticeNotification = {
+  readonly details?: string | null;
+  readonly summary: string;
+};
+export const ServerNotification__DeprecationNoticeNotification = Schema.Struct({
+  details: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional extra guidance, such as migration steps or rationale.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  summary: Schema.String.annotate({ description: "Concise summary of what is deprecated." }),
+});
+
+export type ServerNotification__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const ServerNotification__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const ServerNotification__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type ServerNotification__ExternalAgentConfigImportCompletedNotification = {};
+export const ServerNotification__ExternalAgentConfigImportCompletedNotification = Schema.Struct({});
+
+export type ServerNotification__FileChangeOutputDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__FileChangeOutputDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  description:
+    "Deprecated legacy notification for `apply_patch` textual output.\n\nThe server no longer emits this notification.",
+});
+
+export type ServerNotification__FileSystemAccessMode = "read" | "write" | "none";
+export const ServerNotification__FileSystemAccessMode = Schema.Literals(["read", "write", "none"]);
+
+export type ServerNotification__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const ServerNotification__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__FuzzyFileSearchMatchType = "file" | "directory";
+export const ServerNotification__FuzzyFileSearchMatchType = Schema.Literals(["file", "directory"]);
+
+export type ServerNotification__FuzzyFileSearchSessionCompletedNotification = {
+  readonly sessionId: string;
+};
+export const ServerNotification__FuzzyFileSearchSessionCompletedNotification = Schema.Struct({
+  sessionId: Schema.String,
+});
+
+export type ServerNotification__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const ServerNotification__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerNotification__GuardianApprovalReviewStatus =
+  | "inProgress"
+  | "approved"
+  | "denied"
+  | "timedOut"
+  | "aborted";
+export const ServerNotification__GuardianApprovalReviewStatus = Schema.Literals([
+  "inProgress",
+  "approved",
+  "denied",
+  "timedOut",
+  "aborted",
+]).annotate({ description: "[UNSTABLE] Lifecycle state for an approval auto-review." });
+
+export type ServerNotification__GuardianCommandSource = "shell" | "unifiedExec";
+export const ServerNotification__GuardianCommandSource = Schema.Literals(["shell", "unifiedExec"]);
+
+export type ServerNotification__GuardianRiskLevel = "low" | "medium" | "high" | "critical";
+export const ServerNotification__GuardianRiskLevel = Schema.Literals([
+  "low",
+  "medium",
+  "high",
+  "critical",
+]).annotate({ description: "[UNSTABLE] Risk level assigned by approval auto-review." });
+
+export type ServerNotification__GuardianUserAuthorization = "unknown" | "low" | "medium" | "high";
+export const ServerNotification__GuardianUserAuthorization = Schema.Literals([
+  "unknown",
+  "low",
+  "medium",
+  "high",
+]).annotate({ description: "[UNSTABLE] Authorization level assigned by approval auto-review." });
+
+export type ServerNotification__GuardianWarningNotification = {
+  readonly message: string;
+  readonly threadId: string;
+};
+export const ServerNotification__GuardianWarningNotification = Schema.Struct({
+  message: Schema.String.annotate({
+    description: "Concise guardian warning message for the user.",
+  }),
+  threadId: Schema.String.annotate({ description: "Thread target for the guardian warning." }),
+});
+
+export type ServerNotification__HookEventName =
+  | "preToolUse"
+  | "permissionRequest"
+  | "postToolUse"
+  | "preCompact"
+  | "postCompact"
+  | "sessionStart"
+  | "userPromptSubmit"
+  | "stop";
+export const ServerNotification__HookEventName = Schema.Literals([
+  "preToolUse",
+  "permissionRequest",
+  "postToolUse",
+  "preCompact",
+  "postCompact",
+  "sessionStart",
+  "userPromptSubmit",
+  "stop",
+]);
+
+export type ServerNotification__HookExecutionMode = "sync" | "async";
+export const ServerNotification__HookExecutionMode = Schema.Literals(["sync", "async"]);
+
+export type ServerNotification__HookHandlerType = "command" | "prompt" | "agent";
+export const ServerNotification__HookHandlerType = Schema.Literals(["command", "prompt", "agent"]);
+
+export type ServerNotification__HookOutputEntryKind =
+  | "warning"
+  | "stop"
+  | "feedback"
+  | "context"
+  | "error";
+export const ServerNotification__HookOutputEntryKind = Schema.Literals([
+  "warning",
+  "stop",
+  "feedback",
+  "context",
+  "error",
+]);
+
+export type ServerNotification__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const ServerNotification__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type ServerNotification__HookRunStatus =
+  | "running"
+  | "completed"
+  | "failed"
+  | "blocked"
+  | "stopped";
+export const ServerNotification__HookRunStatus = Schema.Literals([
+  "running",
+  "completed",
+  "failed",
+  "blocked",
+  "stopped",
+]);
+
+export type ServerNotification__HookScope = "thread" | "turn";
+export const ServerNotification__HookScope = Schema.Literals(["thread", "turn"]);
+
+export type ServerNotification__McpServerOauthLoginCompletedNotification = {
+  readonly error?: string | null;
+  readonly name: string;
+  readonly success: boolean;
+};
+export const ServerNotification__McpServerOauthLoginCompletedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  success: Schema.Boolean,
+});
+
+export type ServerNotification__McpServerStartupState =
+  | "starting"
+  | "ready"
+  | "failed"
+  | "cancelled";
+export const ServerNotification__McpServerStartupState = Schema.Literals([
+  "starting",
+  "ready",
+  "failed",
+  "cancelled",
+]);
+
+export type ServerNotification__McpToolCallError = { readonly message: string };
+export const ServerNotification__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type ServerNotification__McpToolCallProgressNotification = {
+  readonly itemId: string;
+  readonly message: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__McpToolCallProgressNotification = Schema.Struct({
+  itemId: Schema.String,
+  message: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const ServerNotification__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type ServerNotification__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const ServerNotification__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type ServerNotification__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const ServerNotification__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type ServerNotification__MessagePhase = "commentary" | "final_answer";
+export const ServerNotification__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type ServerNotification__ModelRerouteReason = "highRiskCyberActivity";
+export const ServerNotification__ModelRerouteReason = Schema.Literal("highRiskCyberActivity");
+
+export type ServerNotification__ModelVerification = "trustedAccessForCyber";
+export const ServerNotification__ModelVerification = Schema.Literal("trustedAccessForCyber");
+
+export type ServerNotification__NetworkApprovalProtocol =
+  | "http"
+  | "https"
+  | "socks5Tcp"
+  | "socks5Udp";
+export const ServerNotification__NetworkApprovalProtocol = Schema.Literals([
+  "http",
+  "https",
+  "socks5Tcp",
+  "socks5Udp",
+]);
+
+export type ServerNotification__NonSteerableTurnKind = "review" | "compact";
+export const ServerNotification__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type ServerNotification__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const ServerNotification__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type ServerNotification__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const ServerNotification__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__PlanDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__PlanDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  description:
+    "EXPERIMENTAL - proposed plan streaming deltas for plan items. Clients should not assume concatenated deltas match the completed plan item content.",
+});
+
+export type ServerNotification__PlanType =
+  | "free"
+  | "go"
+  | "plus"
+  | "pro"
+  | "prolite"
+  | "team"
+  | "self_serve_business_usage_based"
+  | "business"
+  | "enterprise_cbp_usage_based"
+  | "enterprise"
+  | "edu"
+  | "unknown";
+export const ServerNotification__PlanType = Schema.Literals([
+  "free",
+  "go",
+  "plus",
+  "pro",
+  "prolite",
+  "team",
+  "self_serve_business_usage_based",
+  "business",
+  "enterprise_cbp_usage_based",
+  "enterprise",
+  "edu",
+  "unknown",
+]);
+
+export type ServerNotification__ProcessExitedNotification = {
+  readonly exitCode: number;
+  readonly processHandle: string;
+  readonly stderr: string;
+  readonly stderrCapReached: boolean;
+  readonly stdout: string;
+  readonly stdoutCapReached: boolean;
+};
+export const ServerNotification__ProcessExitedNotification = Schema.Struct({
+  exitCode: Schema.Number.annotate({ description: "Process exit code.", format: "int32" }).check(
+    Schema.isInt(),
+  ),
+  processHandle: Schema.String.annotate({
+    description: "Client-supplied, connection-scoped `processHandle` from `process/spawn`.",
+  }),
+  stderr: Schema.String.annotate({
+    description:
+      "Buffered stderr capture.\n\nEmpty when stderr was streamed via `process/outputDelta`.",
+  }),
+  stderrCapReached: Schema.Boolean.annotate({
+    description:
+      "Whether stderr reached `outputBytesCap`.\n\nIn streaming mode, stderr is empty and cap state is also reported on the final stderr `process/outputDelta` notification.",
+  }),
+  stdout: Schema.String.annotate({
+    description:
+      "Buffered stdout capture.\n\nEmpty when stdout was streamed via `process/outputDelta`.",
+  }),
+  stdoutCapReached: Schema.Boolean.annotate({
+    description:
+      "Whether stdout reached `outputBytesCap`.\n\nIn streaming mode, stdout is empty and cap state is also reported on the final stdout `process/outputDelta` notification.",
+  }),
+}).annotate({ description: "Final process exit notification for `process/spawn`." });
+
+export type ServerNotification__ProcessOutputDeltaNotification = {
+  readonly capReached: boolean;
+  readonly deltaBase64: string;
+  readonly processHandle: string;
+  readonly stream: "stdout" | "stderr";
+};
+export const ServerNotification__ProcessOutputDeltaNotification = Schema.Struct({
+  capReached: Schema.Boolean.annotate({
+    description:
+      "True on the final streamed chunk for this stream when output was truncated by `outputBytesCap`.",
+  }),
+  deltaBase64: Schema.String.annotate({ description: "Base64-encoded output bytes." }),
+  processHandle: Schema.String.annotate({
+    description: "Client-supplied, connection-scoped `processHandle` from `process/spawn`.",
+  }),
+  stream: Schema.Literals(["stdout", "stderr"]).annotate({
+    description: "Stream label for `process/outputDelta` notifications.",
+  }),
+}).annotate({
+  description: "Base64-encoded output chunk emitted for a streaming `process/spawn` request.",
+});
+
+export type ServerNotification__RateLimitReachedType =
+  | "rate_limit_reached"
+  | "workspace_owner_credits_depleted"
+  | "workspace_member_credits_depleted"
+  | "workspace_owner_usage_limit_reached"
+  | "workspace_member_usage_limit_reached";
+export const ServerNotification__RateLimitReachedType = Schema.Literals([
+  "rate_limit_reached",
+  "workspace_owner_credits_depleted",
+  "workspace_member_credits_depleted",
+  "workspace_owner_usage_limit_reached",
+  "workspace_member_usage_limit_reached",
+]);
+
+export type ServerNotification__RateLimitWindow = {
+  readonly resetsAt?: number | null;
+  readonly usedPercent: number;
+  readonly windowDurationMins?: number | null;
+};
+export const ServerNotification__RateLimitWindow = Schema.Struct({
+  resetsAt: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  usedPercent: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+  windowDurationMins: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+});
+
+export type ServerNotification__RealtimeConversationVersion = "v1" | "v2";
+export const ServerNotification__RealtimeConversationVersion = Schema.Literals(["v1", "v2"]);
+
+export type ServerNotification__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const ServerNotification__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type ServerNotification__ReasoningSummaryPartAddedNotification = {
+  readonly itemId: string;
+  readonly summaryIndex: number;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ReasoningSummaryPartAddedNotification = Schema.Struct({
+  itemId: Schema.String,
+  summaryIndex: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__ReasoningSummaryTextDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly summaryIndex: number;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ReasoningSummaryTextDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  summaryIndex: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__ReasoningTextDeltaNotification = {
+  readonly contentIndex: number;
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ReasoningTextDeltaNotification = Schema.Struct({
+  contentIndex: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__RemoteControlConnectionStatus =
+  | "disabled"
+  | "connecting"
+  | "connected"
+  | "errored";
+export const ServerNotification__RemoteControlConnectionStatus = Schema.Literals([
+  "disabled",
+  "connecting",
+  "connected",
+  "errored",
+]);
+
+export type ServerNotification__RequestId = string | number;
+export const ServerNotification__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type ServerNotification__SkillsChangedNotification = {};
+export const ServerNotification__SkillsChangedNotification = Schema.Struct({}).annotate({
+  description:
+    "Notification emitted when watched local skill files change.\n\nTreat this as an invalidation signal and re-run `skills/list` with the client's current parameters when refreshed skill metadata is needed.",
+});
+
+export type ServerNotification__TerminalInteractionNotification = {
+  readonly itemId: string;
+  readonly processId: string;
+  readonly stdin: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__TerminalInteractionNotification = Schema.Struct({
+  itemId: Schema.String,
+  processId: Schema.String,
+  stdin: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const ServerNotification__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ServerNotification__TextPosition = { readonly column: number; readonly line: number };
+export const ServerNotification__TextPosition = Schema.Struct({
+  column: Schema.Number.annotate({
+    description: "1-based column number (in Unicode scalar values).",
+    format: "uint",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  line: Schema.Number.annotate({ description: "1-based line number.", format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type ServerNotification__ThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
+export const ServerNotification__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type ServerNotification__ThreadArchivedNotification = { readonly threadId: string };
+export const ServerNotification__ThreadArchivedNotification = Schema.Struct({
+  threadId: Schema.String,
+});
+
+export type ServerNotification__ThreadClosedNotification = { readonly threadId: string };
+export const ServerNotification__ThreadClosedNotification = Schema.Struct({
+  threadId: Schema.String,
+});
+
+export type ServerNotification__ThreadGoalClearedNotification = { readonly threadId: string };
+export const ServerNotification__ThreadGoalClearedNotification = Schema.Struct({
+  threadId: Schema.String,
+});
+
+export type ServerNotification__ThreadGoalStatus =
+  | "active"
+  | "paused"
+  | "budgetLimited"
+  | "complete";
+export const ServerNotification__ThreadGoalStatus = Schema.Literals([
+  "active",
+  "paused",
+  "budgetLimited",
+  "complete",
+]);
+
+export type ServerNotification__ThreadId = string;
+export const ServerNotification__ThreadId = Schema.String;
+
+export type ServerNotification__ThreadNameUpdatedNotification = {
+  readonly threadId: string;
+  readonly threadName?: string | null;
+};
+export const ServerNotification__ThreadNameUpdatedNotification = Schema.Struct({
+  threadId: Schema.String,
+  threadName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerNotification__ThreadRealtimeAudioChunk = {
+  readonly data: string;
+  readonly itemId?: string | null;
+  readonly numChannels: number;
+  readonly sampleRate: number;
+  readonly samplesPerChannel?: number | null;
+};
+export const ServerNotification__ThreadRealtimeAudioChunk = Schema.Struct({
+  data: Schema.String,
+  itemId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  numChannels: Schema.Number.annotate({ format: "uint16" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  sampleRate: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  samplesPerChannel: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "EXPERIMENTAL - thread realtime audio chunk." });
+
+export type ServerNotification__ThreadRealtimeClosedNotification = {
+  readonly reason?: string | null;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadRealtimeClosedNotification = Schema.Struct({
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+}).annotate({ description: "EXPERIMENTAL - emitted when thread realtime transport closes." });
+
+export type ServerNotification__ThreadRealtimeErrorNotification = {
+  readonly message: string;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadRealtimeErrorNotification = Schema.Struct({
+  message: Schema.String,
+  threadId: Schema.String,
+}).annotate({ description: "EXPERIMENTAL - emitted when thread realtime encounters an error." });
+
+export type ServerNotification__ThreadRealtimeItemAddedNotification = {
+  readonly item: unknown;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadRealtimeItemAddedNotification = Schema.Struct({
+  item: Schema.Unknown,
+  threadId: Schema.String,
+}).annotate({
+  description: "EXPERIMENTAL - raw non-audio thread realtime item emitted by the backend.",
+});
+
+export type ServerNotification__ThreadRealtimeSdpNotification = {
+  readonly sdp: string;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadRealtimeSdpNotification = Schema.Struct({
+  sdp: Schema.String,
+  threadId: Schema.String,
+}).annotate({
+  description: "EXPERIMENTAL - emitted with the remote SDP for a WebRTC realtime session.",
+});
+
+export type ServerNotification__ThreadRealtimeTranscriptDeltaNotification = {
+  readonly delta: string;
+  readonly role: string;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadRealtimeTranscriptDeltaNotification = Schema.Struct({
+  delta: Schema.String.annotate({ description: "Live transcript delta from the realtime event." }),
+  role: Schema.String,
+  threadId: Schema.String,
+}).annotate({
+  description:
+    "EXPERIMENTAL - flat transcript delta emitted whenever realtime transcript text changes.",
+});
+
+export type ServerNotification__ThreadRealtimeTranscriptDoneNotification = {
+  readonly role: string;
+  readonly text: string;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadRealtimeTranscriptDoneNotification = Schema.Struct({
+  role: Schema.String,
+  text: Schema.String.annotate({ description: "Final complete text for the transcript part." }),
+  threadId: Schema.String,
+}).annotate({
+  description:
+    "EXPERIMENTAL - final transcript text emitted when realtime completes a transcript part.",
+});
+
+export type ServerNotification__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const ServerNotification__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type ServerNotification__ThreadUnarchivedNotification = { readonly threadId: string };
+export const ServerNotification__ThreadUnarchivedNotification = Schema.Struct({
+  threadId: Schema.String,
+});
+
+export type ServerNotification__TokenUsageBreakdown = {
+  readonly cachedInputTokens: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly reasoningOutputTokens: number;
+  readonly totalTokens: number;
+};
+export const ServerNotification__TokenUsageBreakdown = Schema.Struct({
+  cachedInputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  inputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  outputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  reasoningOutputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  totalTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+});
+
+export type ServerNotification__TurnDiffUpdatedNotification = {
+  readonly diff: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__TurnDiffUpdatedNotification = Schema.Struct({
+  diff: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  description:
+    "Notification that the turn-level unified diff has changed. Contains the latest aggregated diff across all file changes in the turn.",
+});
+
+export type ServerNotification__TurnPlanStepStatus = "pending" | "inProgress" | "completed";
+export const ServerNotification__TurnPlanStepStatus = Schema.Literals([
+  "pending",
+  "inProgress",
+  "completed",
+]);
+
+export type ServerNotification__TurnStatus = "completed" | "interrupted" | "failed" | "inProgress";
+export const ServerNotification__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type ServerNotification__WarningNotification = {
+  readonly message: string;
+  readonly threadId?: string | null;
+};
+export const ServerNotification__WarningNotification = Schema.Struct({
+  message: Schema.String.annotate({ description: "Concise warning message for the user." }),
+  threadId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional thread target when the warning applies to a specific thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ServerNotification__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const ServerNotification__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__WindowsSandboxSetupMode = "elevated" | "unelevated";
+export const ServerNotification__WindowsSandboxSetupMode = Schema.Literals([
+  "elevated",
+  "unelevated",
+]);
+
+export type ServerNotification__WindowsWorldWritableWarningNotification = {
+  readonly extraCount: number;
+  readonly failedScan: boolean;
+  readonly samplePaths: ReadonlyArray<string>;
+};
+export const ServerNotification__WindowsWorldWritableWarningNotification = Schema.Struct({
+  extraCount: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  failedScan: Schema.Boolean,
+  samplePaths: Schema.Array(Schema.String),
+});
+
+export type ServerRequest__AbsolutePathBuf = string;
+export const ServerRequest__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type ServerRequest__AdditionalNetworkPermissions = { readonly enabled?: boolean | null };
+export const ServerRequest__AdditionalNetworkPermissions = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+});
+
+export type ServerRequest__ChatgptAuthTokensRefreshReason = "unauthorized";
+export const ServerRequest__ChatgptAuthTokensRefreshReason = Schema.Literal("unauthorized");
+
+export type ServerRequest__DynamicToolCallParams = {
+  readonly arguments: unknown;
+  readonly callId: string;
+  readonly namespace?: string | null;
+  readonly threadId: string;
+  readonly tool: string;
+  readonly turnId: string;
+};
+export const ServerRequest__DynamicToolCallParams = Schema.Struct({
+  arguments: Schema.Unknown,
+  callId: Schema.String,
+  namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  tool: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerRequest__FileChange =
+  | { readonly content: string; readonly type: "add" }
+  | { readonly content: string; readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update"; readonly unified_diff: string };
+export const ServerRequest__FileChange = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.String,
+      type: Schema.Literal("add").annotate({ title: "AddFileChangeType" }),
+    }).annotate({ title: "AddFileChange" }),
+    Schema.Struct({
+      content: Schema.String,
+      type: Schema.Literal("delete").annotate({ title: "DeleteFileChangeType" }),
+    }).annotate({ title: "DeleteFileChange" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdateFileChangeType" }),
+      unified_diff: Schema.String,
+    }).annotate({ title: "UpdateFileChange" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerRequest__FileChangeRequestApprovalParams = {
+  readonly grantRoot?: string | null;
+  readonly itemId: string;
+  readonly reason?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerRequest__FileChangeRequestApprovalParams = Schema.Struct({
+  grantRoot: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "[UNSTABLE] When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  itemId: Schema.String,
+  reason: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional explanatory reason (e.g. request for extra write access).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerRequest__FileSystemAccessMode = "read" | "write" | "none";
+export const ServerRequest__FileSystemAccessMode = Schema.Literals(["read", "write", "none"]);
+
+export type ServerRequest__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const ServerRequest__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerRequest__McpElicitationArrayType = "array";
+export const ServerRequest__McpElicitationArrayType = Schema.Literal("array");
+
+export type ServerRequest__McpElicitationBooleanType = "boolean";
+export const ServerRequest__McpElicitationBooleanType = Schema.Literal("boolean");
+
+export type ServerRequest__McpElicitationConstOption = {
+  readonly const: string;
+  readonly title: string;
+};
+export const ServerRequest__McpElicitationConstOption = Schema.Struct({
+  const: Schema.String,
+  title: Schema.String,
+});
+
+export type ServerRequest__McpElicitationNumberType = "number" | "integer";
+export const ServerRequest__McpElicitationNumberType = Schema.Literals(["number", "integer"]);
+
+export type ServerRequest__McpElicitationObjectType = "object";
+export const ServerRequest__McpElicitationObjectType = Schema.Literal("object");
+
+export type ServerRequest__McpElicitationStringFormat = "email" | "uri" | "date" | "date-time";
+export const ServerRequest__McpElicitationStringFormat = Schema.Literals([
+  "email",
+  "uri",
+  "date",
+  "date-time",
+]);
+
+export type ServerRequest__McpElicitationStringType = "string";
+export const ServerRequest__McpElicitationStringType = Schema.Literal("string");
+
+export type ServerRequest__NetworkApprovalProtocol = "http" | "https" | "socks5Tcp" | "socks5Udp";
+export const ServerRequest__NetworkApprovalProtocol = Schema.Literals([
+  "http",
+  "https",
+  "socks5Tcp",
+  "socks5Udp",
+]);
+
+export type ServerRequest__NetworkPolicyRuleAction = "allow" | "deny";
+export const ServerRequest__NetworkPolicyRuleAction = Schema.Literals(["allow", "deny"]);
+
+export type ServerRequest__ParsedCommand =
+  | { readonly cmd: string; readonly name: string; readonly path: string; readonly type: "read" }
+  | { readonly cmd: string; readonly path?: string | null; readonly type: "list_files" }
+  | {
+      readonly cmd: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly cmd: string; readonly type: "unknown" };
+export const ServerRequest__ParsedCommand = Schema.Union(
+  [
+    Schema.Struct({
+      cmd: Schema.String,
+      name: Schema.String,
+      path: Schema.String.annotate({
+        description:
+          "(Best effort) Path to the file being read by the command. When possible, this is an absolute path, though when relative, it should be resolved against the `cwd`` that will be used to run the command to derive the absolute path.",
+      }),
+      type: Schema.Literal("read").annotate({ title: "ReadParsedCommandType" }),
+    }).annotate({ title: "ReadParsedCommand" }),
+    Schema.Struct({
+      cmd: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("list_files").annotate({ title: "ListFilesParsedCommandType" }),
+    }).annotate({ title: "ListFilesParsedCommand" }),
+    Schema.Struct({
+      cmd: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchParsedCommandType" }),
+    }).annotate({ title: "SearchParsedCommand" }),
+    Schema.Struct({
+      cmd: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownParsedCommandType" }),
+    }).annotate({ title: "UnknownParsedCommand" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerRequest__RequestId = string | number;
+export const ServerRequest__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type ServerRequest__ThreadId = string;
+export const ServerRequest__ThreadId = Schema.String;
+
+export type ServerRequest__ToolRequestUserInputOption = {
+  readonly description: string;
+  readonly label: string;
+};
+export const ServerRequest__ToolRequestUserInputOption = Schema.Struct({
+  description: Schema.String,
+  label: Schema.String,
+}).annotate({
+  description: "EXPERIMENTAL. Defines a single selectable option for request_user_input.",
+});
+
+export type ToolRequestUserInputParams__ToolRequestUserInputOption = {
+  readonly description: string;
+  readonly label: string;
+};
+export const ToolRequestUserInputParams__ToolRequestUserInputOption = Schema.Struct({
+  description: Schema.String,
+  label: Schema.String,
+}).annotate({
+  description: "EXPERIMENTAL. Defines a single selectable option for request_user_input.",
+});
+
+export type ToolRequestUserInputResponse__ToolRequestUserInputAnswer = {
+  readonly answers: ReadonlyArray<string>;
+};
+export const ToolRequestUserInputResponse__ToolRequestUserInputAnswer = Schema.Struct({
+  answers: Schema.Array(Schema.String),
+}).annotate({
+  description: "EXPERIMENTAL. Captures a user's answer to a request_user_input question.",
+});
+
+export type V1InitializeParams__ClientInfo = {
+  readonly name: string;
+  readonly title?: string | null;
+  readonly version: string;
+};
+export const V1InitializeParams__ClientInfo = Schema.Struct({
+  name: Schema.String,
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  version: Schema.String,
+});
+
+export type V1InitializeParams__InitializeCapabilities = {
+  readonly experimentalApi?: boolean;
+  readonly optOutNotificationMethods?: ReadonlyArray<string> | null;
+};
+export const V1InitializeParams__InitializeCapabilities = Schema.Struct({
+  experimentalApi: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Opt into receiving experimental API methods and fields.",
+      default: false,
+    }),
+  ),
+  optOutNotificationMethods: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Exact notification method names that should be suppressed for this connection (for example `thread/started`).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "Client-declared capabilities negotiated during initialize." });
+
+export type V2AccountRateLimitsUpdatedNotification__CreditsSnapshot = {
+  readonly balance?: string | null;
+  readonly hasCredits: boolean;
+  readonly unlimited: boolean;
+};
+export const V2AccountRateLimitsUpdatedNotification__CreditsSnapshot = Schema.Struct({
+  balance: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  hasCredits: Schema.Boolean,
+  unlimited: Schema.Boolean,
+});
+
+export type V2AccountRateLimitsUpdatedNotification__PlanType =
+  | "free"
+  | "go"
+  | "plus"
+  | "pro"
+  | "prolite"
+  | "team"
+  | "self_serve_business_usage_based"
+  | "business"
+  | "enterprise_cbp_usage_based"
+  | "enterprise"
+  | "edu"
+  | "unknown";
+export const V2AccountRateLimitsUpdatedNotification__PlanType = Schema.Literals([
+  "free",
+  "go",
+  "plus",
+  "pro",
+  "prolite",
+  "team",
+  "self_serve_business_usage_based",
+  "business",
+  "enterprise_cbp_usage_based",
+  "enterprise",
+  "edu",
+  "unknown",
+]);
+
+export type V2AccountRateLimitsUpdatedNotification__RateLimitReachedType =
+  | "rate_limit_reached"
+  | "workspace_owner_credits_depleted"
+  | "workspace_member_credits_depleted"
+  | "workspace_owner_usage_limit_reached"
+  | "workspace_member_usage_limit_reached";
+export const V2AccountRateLimitsUpdatedNotification__RateLimitReachedType = Schema.Literals([
+  "rate_limit_reached",
+  "workspace_owner_credits_depleted",
+  "workspace_member_credits_depleted",
+  "workspace_owner_usage_limit_reached",
+  "workspace_member_usage_limit_reached",
+]);
+
+export type V2AccountRateLimitsUpdatedNotification__RateLimitWindow = {
+  readonly resetsAt?: number | null;
+  readonly usedPercent: number;
+  readonly windowDurationMins?: number | null;
+};
+export const V2AccountRateLimitsUpdatedNotification__RateLimitWindow = Schema.Struct({
+  resetsAt: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  usedPercent: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+  windowDurationMins: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+});
+
+export type V2AccountUpdatedNotification__AuthMode =
+  | "apikey"
+  | "chatgpt"
+  | "chatgptAuthTokens"
+  | "agentIdentity";
+export const V2AccountUpdatedNotification__AuthMode = Schema.Literals([
+  "apikey",
+  "chatgpt",
+  "chatgptAuthTokens",
+  "agentIdentity",
+]).annotate({ description: "Authentication mode for OpenAI-backed providers." });
+
+export type V2AccountUpdatedNotification__PlanType =
+  | "free"
+  | "go"
+  | "plus"
+  | "pro"
+  | "prolite"
+  | "team"
+  | "self_serve_business_usage_based"
+  | "business"
+  | "enterprise_cbp_usage_based"
+  | "enterprise"
+  | "edu"
+  | "unknown";
+export const V2AccountUpdatedNotification__PlanType = Schema.Literals([
+  "free",
+  "go",
+  "plus",
+  "pro",
+  "prolite",
+  "team",
+  "self_serve_business_usage_based",
+  "business",
+  "enterprise_cbp_usage_based",
+  "enterprise",
+  "edu",
+  "unknown",
+]);
+
+export type V2AppListUpdatedNotification__AppBranding = {
+  readonly category?: string | null;
+  readonly developer?: string | null;
+  readonly isDiscoverableApp: boolean;
+  readonly privacyPolicy?: string | null;
+  readonly termsOfService?: string | null;
+  readonly website?: string | null;
+};
+export const V2AppListUpdatedNotification__AppBranding = Schema.Struct({
+  category: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developer: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  isDiscoverableApp: Schema.Boolean,
+  privacyPolicy: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  termsOfService: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  website: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ description: "EXPERIMENTAL - app metadata returned by app-list APIs." });
+
+export type V2AppListUpdatedNotification__AppReview = { readonly status: string };
+export const V2AppListUpdatedNotification__AppReview = Schema.Struct({ status: Schema.String });
+
+export type V2AppListUpdatedNotification__AppScreenshot = {
+  readonly fileId?: string | null;
+  readonly url?: string | null;
+  readonly userPrompt: string;
+};
+export const V2AppListUpdatedNotification__AppScreenshot = Schema.Struct({
+  fileId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  userPrompt: Schema.String,
+});
+
+export type V2AppsListResponse__AppBranding = {
+  readonly category?: string | null;
+  readonly developer?: string | null;
+  readonly isDiscoverableApp: boolean;
+  readonly privacyPolicy?: string | null;
+  readonly termsOfService?: string | null;
+  readonly website?: string | null;
+};
+export const V2AppsListResponse__AppBranding = Schema.Struct({
+  category: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developer: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  isDiscoverableApp: Schema.Boolean,
+  privacyPolicy: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  termsOfService: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  website: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ description: "EXPERIMENTAL - app metadata returned by app-list APIs." });
+
+export type V2AppsListResponse__AppReview = { readonly status: string };
+export const V2AppsListResponse__AppReview = Schema.Struct({ status: Schema.String });
+
+export type V2AppsListResponse__AppScreenshot = {
+  readonly fileId?: string | null;
+  readonly url?: string | null;
+  readonly userPrompt: string;
+};
+export const V2AppsListResponse__AppScreenshot = Schema.Struct({
+  fileId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  userPrompt: Schema.String,
+});
+
+export type V2CancelLoginAccountResponse__CancelLoginAccountStatus = "canceled" | "notFound";
+export const V2CancelLoginAccountResponse__CancelLoginAccountStatus = Schema.Literals([
+  "canceled",
+  "notFound",
+]);
+
+export type V2CommandExecParams__AbsolutePathBuf = string;
+export const V2CommandExecParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2CommandExecParams__CommandExecTerminalSize = {
+  readonly cols: number;
+  readonly rows: number;
+};
+export const V2CommandExecParams__CommandExecTerminalSize = Schema.Struct({
+  cols: Schema.Number.annotate({
+    description: "Terminal width in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  rows: Schema.Number.annotate({
+    description: "Terminal height in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({ description: "PTY size in character cells for `command/exec` PTY sessions." });
+
+export type V2CommandExecParams__FileSystemAccessMode = "read" | "write" | "none";
+export const V2CommandExecParams__FileSystemAccessMode = Schema.Literals(["read", "write", "none"]);
+
+export type V2CommandExecParams__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const V2CommandExecParams__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2CommandExecParams__PermissionProfileNetworkPermissions = {
+  readonly enabled: boolean;
+};
+export const V2CommandExecParams__PermissionProfileNetworkPermissions = Schema.Struct({
+  enabled: Schema.Boolean,
+});
+
+export type V2ConfigBatchWriteParams__MergeStrategy = "replace" | "upsert";
+export const V2ConfigBatchWriteParams__MergeStrategy = Schema.Literals(["replace", "upsert"]);
+
+export type V2ConfigReadResponse__AbsolutePathBuf = string;
+export const V2ConfigReadResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ConfigReadResponse__AnalyticsConfig = {
+  readonly enabled?: boolean | null;
+  readonly [x: string]: unknown;
+};
+export const V2ConfigReadResponse__AnalyticsConfig = Schema.StructWithRest(
+  Schema.Struct({ enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])) }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+);
+
+export type V2ConfigReadResponse__AppToolApproval = "auto" | "prompt" | "approve";
+export const V2ConfigReadResponse__AppToolApproval = Schema.Literals(["auto", "prompt", "approve"]);
+
+export type V2ConfigReadResponse__AppToolsConfig = {};
+export const V2ConfigReadResponse__AppToolsConfig = Schema.Struct({});
+
+export type V2ConfigReadResponse__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const V2ConfigReadResponse__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ConfigReadResponse__AppsDefaultConfig = {
+  readonly destructive_enabled?: boolean;
+  readonly enabled?: boolean;
+  readonly open_world_enabled?: boolean;
+};
+export const V2ConfigReadResponse__AppsDefaultConfig = Schema.Struct({
+  destructive_enabled: Schema.optionalKey(Schema.Boolean.annotate({ default: true })),
+  enabled: Schema.optionalKey(Schema.Boolean.annotate({ default: true })),
+  open_world_enabled: Schema.optionalKey(Schema.Boolean.annotate({ default: true })),
+});
+
+export type V2ConfigReadResponse__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ConfigReadResponse__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ConfigReadResponse__ForcedLoginMethod = "chatgpt" | "api";
+export const V2ConfigReadResponse__ForcedLoginMethod = Schema.Literals(["chatgpt", "api"]);
+
+export type V2ConfigReadResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ConfigReadResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ConfigReadResponse__ReasoningSummary = "auto" | "concise" | "detailed" | "none";
+export const V2ConfigReadResponse__ReasoningSummary = Schema.Union(
+  [
+    Schema.Literals(["auto", "concise", "detailed"]),
+    Schema.Literal("none").annotate({ description: "Option to disable reasoning summaries." }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries",
+});
+
+export type V2ConfigReadResponse__SandboxMode =
+  | "read-only"
+  | "workspace-write"
+  | "danger-full-access";
+export const V2ConfigReadResponse__SandboxMode = Schema.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access",
+]);
+
+export type V2ConfigReadResponse__SandboxWorkspaceWrite = {
+  readonly exclude_slash_tmp?: boolean;
+  readonly exclude_tmpdir_env_var?: boolean;
+  readonly network_access?: boolean;
+  readonly writable_roots?: ReadonlyArray<string>;
+};
+export const V2ConfigReadResponse__SandboxWorkspaceWrite = Schema.Struct({
+  exclude_slash_tmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  exclude_tmpdir_env_var: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  network_access: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  writable_roots: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+});
+
+export type V2ConfigReadResponse__Verbosity = "low" | "medium" | "high";
+export const V2ConfigReadResponse__Verbosity = Schema.Literals(["low", "medium", "high"]).annotate({
+  description:
+    "Controls output length/detail on GPT-5 models via the Responses API. Serialized with lowercase values to match the OpenAI API.",
+});
+
+export type V2ConfigReadResponse__WebSearchContextSize = "low" | "medium" | "high";
+export const V2ConfigReadResponse__WebSearchContextSize = Schema.Literals([
+  "low",
+  "medium",
+  "high",
+]);
+
+export type V2ConfigReadResponse__WebSearchLocation = {
+  readonly city?: string | null;
+  readonly country?: string | null;
+  readonly region?: string | null;
+  readonly timezone?: string | null;
+};
+export const V2ConfigReadResponse__WebSearchLocation = Schema.Struct({
+  city: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  country: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  region: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  timezone: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ConfigReadResponse__WebSearchMode = "disabled" | "cached" | "live";
+export const V2ConfigReadResponse__WebSearchMode = Schema.Literals(["disabled", "cached", "live"]);
+
+export type V2ConfigRequirementsReadResponse__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ConfigRequirementsReadResponse__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ConfigRequirementsReadResponse__ConfiguredHookHandler =
+  | {
+      readonly async: boolean;
+      readonly command: string;
+      readonly statusMessage?: string | null;
+      readonly timeoutSec?: number | null;
+      readonly type: "command";
+    }
+  | { readonly type: "prompt" }
+  | { readonly type: "agent" };
+export const V2ConfigRequirementsReadResponse__ConfiguredHookHandler = Schema.Union(
+  [
+    Schema.Struct({
+      async: Schema.Boolean,
+      command: Schema.String,
+      statusMessage: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      timeoutSec: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint64" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("command").annotate({ title: "CommandConfiguredHookHandlerType" }),
+    }).annotate({ title: "CommandConfiguredHookHandler" }),
+    Schema.Struct({
+      type: Schema.Literal("prompt").annotate({ title: "PromptConfiguredHookHandlerType" }),
+    }).annotate({ title: "PromptConfiguredHookHandler" }),
+    Schema.Struct({
+      type: Schema.Literal("agent").annotate({ title: "AgentConfiguredHookHandlerType" }),
+    }).annotate({ title: "AgentConfiguredHookHandler" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ConfigRequirementsReadResponse__NetworkDomainPermission = "allow" | "deny";
+export const V2ConfigRequirementsReadResponse__NetworkDomainPermission = Schema.Literals([
+  "allow",
+  "deny",
+]);
+
+export type V2ConfigRequirementsReadResponse__NetworkUnixSocketPermission = "allow" | "none";
+export const V2ConfigRequirementsReadResponse__NetworkUnixSocketPermission = Schema.Literals([
+  "allow",
+  "none",
+]);
+
+export type V2ConfigRequirementsReadResponse__ResidencyRequirement = "us";
+export const V2ConfigRequirementsReadResponse__ResidencyRequirement = Schema.Literal("us");
+
+export type V2ConfigRequirementsReadResponse__SandboxMode =
+  | "read-only"
+  | "workspace-write"
+  | "danger-full-access";
+export const V2ConfigRequirementsReadResponse__SandboxMode = Schema.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access",
+]);
+
+export type V2ConfigRequirementsReadResponse__WebSearchMode = "disabled" | "cached" | "live";
+export const V2ConfigRequirementsReadResponse__WebSearchMode = Schema.Literals([
+  "disabled",
+  "cached",
+  "live",
+]);
+
+export type V2ConfigValueWriteParams__MergeStrategy = "replace" | "upsert";
+export const V2ConfigValueWriteParams__MergeStrategy = Schema.Literals(["replace", "upsert"]);
+
+export type V2ConfigWarningNotification__TextPosition = {
+  readonly column: number;
+  readonly line: number;
+};
+export const V2ConfigWarningNotification__TextPosition = Schema.Struct({
+  column: Schema.Number.annotate({
+    description: "1-based column number (in Unicode scalar values).",
+    format: "uint",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  line: Schema.Number.annotate({ description: "1-based line number.", format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ConfigWriteResponse__AbsolutePathBuf = string;
+export const V2ConfigWriteResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ConfigWriteResponse__WriteStatus = "ok" | "okOverridden";
+export const V2ConfigWriteResponse__WriteStatus = Schema.Literals(["ok", "okOverridden"]);
+
+export type V2ErrorNotification__NonSteerableTurnKind = "review" | "compact";
+export const V2ErrorNotification__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2ExperimentalFeatureListResponse__ExperimentalFeature = {
+  readonly announcement?: string | null;
+  readonly defaultEnabled: boolean;
+  readonly description?: string | null;
+  readonly displayName?: string | null;
+  readonly enabled: boolean;
+  readonly name: string;
+  readonly stage: "beta" | "underDevelopment" | "stable" | "deprecated" | "removed";
+};
+export const V2ExperimentalFeatureListResponse__ExperimentalFeature = Schema.Struct({
+  announcement: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Announcement copy shown to users when the feature is introduced. Null when this feature is not in beta.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  defaultEnabled: Schema.Boolean.annotate({
+    description: "Whether this feature is enabled by default.",
+  }),
+  description: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Short summary describing what the feature does. Null when this feature is not in beta.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  displayName: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "User-facing display name shown in the experimental features UI. Null when this feature is not in beta.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  enabled: Schema.Boolean.annotate({
+    description: "Whether this feature is currently enabled in the loaded config.",
+  }),
+  name: Schema.String.annotate({
+    description: "Stable key used in config.toml and CLI flag toggles.",
+  }),
+  stage: Schema.Literals(["beta", "underDevelopment", "stable", "deprecated", "removed"]).annotate({
+    description: "Lifecycle stage of this feature flag.",
+  }),
+});
+
+export type V2ExternalAgentConfigDetectResponse__CommandMigration = { readonly name: string };
+export const V2ExternalAgentConfigDetectResponse__CommandMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItemType =
+  | "AGENTS_MD"
+  | "CONFIG"
+  | "SKILLS"
+  | "PLUGINS"
+  | "MCP_SERVER_CONFIG"
+  | "SUBAGENTS"
+  | "HOOKS"
+  | "COMMANDS"
+  | "SESSIONS";
+export const V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItemType =
+  Schema.Literals([
+    "AGENTS_MD",
+    "CONFIG",
+    "SKILLS",
+    "PLUGINS",
+    "MCP_SERVER_CONFIG",
+    "SUBAGENTS",
+    "HOOKS",
+    "COMMANDS",
+    "SESSIONS",
+  ]);
+
+export type V2ExternalAgentConfigDetectResponse__HookMigration = { readonly name: string };
+export const V2ExternalAgentConfigDetectResponse__HookMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2ExternalAgentConfigDetectResponse__McpServerMigration = { readonly name: string };
+export const V2ExternalAgentConfigDetectResponse__McpServerMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2ExternalAgentConfigDetectResponse__PluginsMigration = {
+  readonly marketplaceName: string;
+  readonly pluginNames: ReadonlyArray<string>;
+};
+export const V2ExternalAgentConfigDetectResponse__PluginsMigration = Schema.Struct({
+  marketplaceName: Schema.String,
+  pluginNames: Schema.Array(Schema.String),
+});
+
+export type V2ExternalAgentConfigDetectResponse__SessionMigration = {
+  readonly cwd: string;
+  readonly path: string;
+  readonly title?: string | null;
+};
+export const V2ExternalAgentConfigDetectResponse__SessionMigration = Schema.Struct({
+  cwd: Schema.String,
+  path: Schema.String,
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ExternalAgentConfigDetectResponse__SubagentMigration = { readonly name: string };
+export const V2ExternalAgentConfigDetectResponse__SubagentMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2ExternalAgentConfigImportParams__CommandMigration = { readonly name: string };
+export const V2ExternalAgentConfigImportParams__CommandMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItemType =
+  | "AGENTS_MD"
+  | "CONFIG"
+  | "SKILLS"
+  | "PLUGINS"
+  | "MCP_SERVER_CONFIG"
+  | "SUBAGENTS"
+  | "HOOKS"
+  | "COMMANDS"
+  | "SESSIONS";
+export const V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItemType =
+  Schema.Literals([
+    "AGENTS_MD",
+    "CONFIG",
+    "SKILLS",
+    "PLUGINS",
+    "MCP_SERVER_CONFIG",
+    "SUBAGENTS",
+    "HOOKS",
+    "COMMANDS",
+    "SESSIONS",
+  ]);
+
+export type V2ExternalAgentConfigImportParams__HookMigration = { readonly name: string };
+export const V2ExternalAgentConfigImportParams__HookMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2ExternalAgentConfigImportParams__McpServerMigration = { readonly name: string };
+export const V2ExternalAgentConfigImportParams__McpServerMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2ExternalAgentConfigImportParams__PluginsMigration = {
+  readonly marketplaceName: string;
+  readonly pluginNames: ReadonlyArray<string>;
+};
+export const V2ExternalAgentConfigImportParams__PluginsMigration = Schema.Struct({
+  marketplaceName: Schema.String,
+  pluginNames: Schema.Array(Schema.String),
+});
+
+export type V2ExternalAgentConfigImportParams__SessionMigration = {
+  readonly cwd: string;
+  readonly path: string;
+  readonly title?: string | null;
+};
+export const V2ExternalAgentConfigImportParams__SessionMigration = Schema.Struct({
+  cwd: Schema.String,
+  path: Schema.String,
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ExternalAgentConfigImportParams__SubagentMigration = { readonly name: string };
+export const V2ExternalAgentConfigImportParams__SubagentMigration = Schema.Struct({
+  name: Schema.String,
+});
+
+export type V2FileChangePatchUpdatedNotification__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2FileChangePatchUpdatedNotification__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2FsChangedNotification__AbsolutePathBuf = string;
+export const V2FsChangedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsReadDirectoryResponse__FsReadDirectoryEntry = {
+  readonly fileName: string;
+  readonly isDirectory: boolean;
+  readonly isFile: boolean;
+};
+export const V2FsReadDirectoryResponse__FsReadDirectoryEntry = Schema.Struct({
+  fileName: Schema.String.annotate({
+    description: "Direct child entry name only, not an absolute or relative path.",
+  }),
+  isDirectory: Schema.Boolean.annotate({
+    description: "Whether this entry resolves to a directory.",
+  }),
+  isFile: Schema.Boolean.annotate({
+    description: "Whether this entry resolves to a regular file.",
+  }),
+}).annotate({ description: "A directory entry returned by `fs/readDirectory`." });
+
+export type V2GetAccountRateLimitsResponse__CreditsSnapshot = {
+  readonly balance?: string | null;
+  readonly hasCredits: boolean;
+  readonly unlimited: boolean;
+};
+export const V2GetAccountRateLimitsResponse__CreditsSnapshot = Schema.Struct({
+  balance: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  hasCredits: Schema.Boolean,
+  unlimited: Schema.Boolean,
+});
+
+export type V2GetAccountRateLimitsResponse__PlanType =
+  | "free"
+  | "go"
+  | "plus"
+  | "pro"
+  | "prolite"
+  | "team"
+  | "self_serve_business_usage_based"
+  | "business"
+  | "enterprise_cbp_usage_based"
+  | "enterprise"
+  | "edu"
+  | "unknown";
+export const V2GetAccountRateLimitsResponse__PlanType = Schema.Literals([
+  "free",
+  "go",
+  "plus",
+  "pro",
+  "prolite",
+  "team",
+  "self_serve_business_usage_based",
+  "business",
+  "enterprise_cbp_usage_based",
+  "enterprise",
+  "edu",
+  "unknown",
+]);
+
+export type V2GetAccountRateLimitsResponse__RateLimitReachedType =
+  | "rate_limit_reached"
+  | "workspace_owner_credits_depleted"
+  | "workspace_member_credits_depleted"
+  | "workspace_owner_usage_limit_reached"
+  | "workspace_member_usage_limit_reached";
+export const V2GetAccountRateLimitsResponse__RateLimitReachedType = Schema.Literals([
+  "rate_limit_reached",
+  "workspace_owner_credits_depleted",
+  "workspace_member_credits_depleted",
+  "workspace_owner_usage_limit_reached",
+  "workspace_member_usage_limit_reached",
+]);
+
+export type V2GetAccountRateLimitsResponse__RateLimitWindow = {
+  readonly resetsAt?: number | null;
+  readonly usedPercent: number;
+  readonly windowDurationMins?: number | null;
+};
+export const V2GetAccountRateLimitsResponse__RateLimitWindow = Schema.Struct({
+  resetsAt: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  usedPercent: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+  windowDurationMins: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+});
+
+export type V2GetAccountResponse__PlanType =
+  | "free"
+  | "go"
+  | "plus"
+  | "pro"
+  | "prolite"
+  | "team"
+  | "self_serve_business_usage_based"
+  | "business"
+  | "enterprise_cbp_usage_based"
+  | "enterprise"
+  | "edu"
+  | "unknown";
+export const V2GetAccountResponse__PlanType = Schema.Literals([
+  "free",
+  "go",
+  "plus",
+  "pro",
+  "prolite",
+  "team",
+  "self_serve_business_usage_based",
+  "business",
+  "enterprise_cbp_usage_based",
+  "enterprise",
+  "edu",
+  "unknown",
+]);
+
+export type V2HookCompletedNotification__AbsolutePathBuf = string;
+export const V2HookCompletedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2HookCompletedNotification__HookEventName =
+  | "preToolUse"
+  | "permissionRequest"
+  | "postToolUse"
+  | "preCompact"
+  | "postCompact"
+  | "sessionStart"
+  | "userPromptSubmit"
+  | "stop";
+export const V2HookCompletedNotification__HookEventName = Schema.Literals([
+  "preToolUse",
+  "permissionRequest",
+  "postToolUse",
+  "preCompact",
+  "postCompact",
+  "sessionStart",
+  "userPromptSubmit",
+  "stop",
+]);
+
+export type V2HookCompletedNotification__HookExecutionMode = "sync" | "async";
+export const V2HookCompletedNotification__HookExecutionMode = Schema.Literals(["sync", "async"]);
+
+export type V2HookCompletedNotification__HookHandlerType = "command" | "prompt" | "agent";
+export const V2HookCompletedNotification__HookHandlerType = Schema.Literals([
+  "command",
+  "prompt",
+  "agent",
+]);
+
+export type V2HookCompletedNotification__HookOutputEntryKind =
+  | "warning"
+  | "stop"
+  | "feedback"
+  | "context"
+  | "error";
+export const V2HookCompletedNotification__HookOutputEntryKind = Schema.Literals([
+  "warning",
+  "stop",
+  "feedback",
+  "context",
+  "error",
+]);
+
+export type V2HookCompletedNotification__HookRunStatus =
+  | "running"
+  | "completed"
+  | "failed"
+  | "blocked"
+  | "stopped";
+export const V2HookCompletedNotification__HookRunStatus = Schema.Literals([
+  "running",
+  "completed",
+  "failed",
+  "blocked",
+  "stopped",
+]);
+
+export type V2HookCompletedNotification__HookScope = "thread" | "turn";
+export const V2HookCompletedNotification__HookScope = Schema.Literals(["thread", "turn"]);
+
+export type V2HooksListResponse__AbsolutePathBuf = string;
+export const V2HooksListResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2HooksListResponse__HookErrorInfo = {
+  readonly message: string;
+  readonly path: string;
+};
+export const V2HooksListResponse__HookErrorInfo = Schema.Struct({
+  message: Schema.String,
+  path: Schema.String,
+});
+
+export type V2HooksListResponse__HookEventName =
+  | "preToolUse"
+  | "permissionRequest"
+  | "postToolUse"
+  | "preCompact"
+  | "postCompact"
+  | "sessionStart"
+  | "userPromptSubmit"
+  | "stop";
+export const V2HooksListResponse__HookEventName = Schema.Literals([
+  "preToolUse",
+  "permissionRequest",
+  "postToolUse",
+  "preCompact",
+  "postCompact",
+  "sessionStart",
+  "userPromptSubmit",
+  "stop",
+]);
+
+export type V2HooksListResponse__HookHandlerType = "command" | "prompt" | "agent";
+export const V2HooksListResponse__HookHandlerType = Schema.Literals(["command", "prompt", "agent"]);
+
+export type V2HooksListResponse__HookSource =
+  | "system"
+  | "user"
+  | "project"
+  | "mdm"
+  | "sessionFlags"
+  | "plugin"
+  | "cloudRequirements"
+  | "legacyManagedConfigFile"
+  | "legacyManagedConfigMdm"
+  | "unknown";
+export const V2HooksListResponse__HookSource = Schema.Literals([
+  "system",
+  "user",
+  "project",
+  "mdm",
+  "sessionFlags",
+  "plugin",
+  "cloudRequirements",
+  "legacyManagedConfigFile",
+  "legacyManagedConfigMdm",
+  "unknown",
+]);
+
+export type V2HooksListResponse__HookTrustStatus = "managed" | "untrusted" | "trusted" | "modified";
+export const V2HooksListResponse__HookTrustStatus = Schema.Literals([
+  "managed",
+  "untrusted",
+  "trusted",
+  "modified",
+]);
+
+export type V2HookStartedNotification__AbsolutePathBuf = string;
+export const V2HookStartedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2HookStartedNotification__HookEventName =
+  | "preToolUse"
+  | "permissionRequest"
+  | "postToolUse"
+  | "preCompact"
+  | "postCompact"
+  | "sessionStart"
+  | "userPromptSubmit"
+  | "stop";
+export const V2HookStartedNotification__HookEventName = Schema.Literals([
+  "preToolUse",
+  "permissionRequest",
+  "postToolUse",
+  "preCompact",
+  "postCompact",
+  "sessionStart",
+  "userPromptSubmit",
+  "stop",
+]);
+
+export type V2HookStartedNotification__HookExecutionMode = "sync" | "async";
+export const V2HookStartedNotification__HookExecutionMode = Schema.Literals(["sync", "async"]);
+
+export type V2HookStartedNotification__HookHandlerType = "command" | "prompt" | "agent";
+export const V2HookStartedNotification__HookHandlerType = Schema.Literals([
+  "command",
+  "prompt",
+  "agent",
+]);
+
+export type V2HookStartedNotification__HookOutputEntryKind =
+  | "warning"
+  | "stop"
+  | "feedback"
+  | "context"
+  | "error";
+export const V2HookStartedNotification__HookOutputEntryKind = Schema.Literals([
+  "warning",
+  "stop",
+  "feedback",
+  "context",
+  "error",
+]);
+
+export type V2HookStartedNotification__HookRunStatus =
+  | "running"
+  | "completed"
+  | "failed"
+  | "blocked"
+  | "stopped";
+export const V2HookStartedNotification__HookRunStatus = Schema.Literals([
+  "running",
+  "completed",
+  "failed",
+  "blocked",
+  "stopped",
+]);
+
+export type V2HookStartedNotification__HookScope = "thread" | "turn";
+export const V2HookStartedNotification__HookScope = Schema.Literals(["thread", "turn"]);
+
+export type V2ItemCompletedNotification__AbsolutePathBuf = string;
+export const V2ItemCompletedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ItemCompletedNotification__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ItemCompletedNotification__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ItemCompletedNotification__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ItemCompletedNotification__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ItemCompletedNotification__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ItemCompletedNotification__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemCompletedNotification__DynamicToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ItemCompletedNotification__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ItemCompletedNotification__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ItemCompletedNotification__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ItemCompletedNotification__McpToolCallError = { readonly message: string };
+export const V2ItemCompletedNotification__McpToolCallError = Schema.Struct({
+  message: Schema.String,
+});
+
+export type V2ItemCompletedNotification__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ItemCompletedNotification__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ItemCompletedNotification__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ItemCompletedNotification__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ItemCompletedNotification__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ItemCompletedNotification__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ItemCompletedNotification__MessagePhase = "commentary" | "final_answer";
+export const V2ItemCompletedNotification__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ItemCompletedNotification__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ItemCompletedNotification__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ItemCompletedNotification__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ItemCompletedNotification__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemCompletedNotification__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ItemCompletedNotification__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ItemCompletedNotification__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ItemCompletedNotification__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ItemCompletedNotification__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ItemCompletedNotification__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf = string;
+export const V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf =
+  Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  });
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__AdditionalNetworkPermissions = {
+  readonly enabled?: boolean | null;
+};
+export const V2ItemGuardianApprovalReviewCompletedNotification__AdditionalNetworkPermissions =
+  Schema.Struct({ enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])) });
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__AutoReviewDecisionSource = "agent";
+export const V2ItemGuardianApprovalReviewCompletedNotification__AutoReviewDecisionSource =
+  Schema.Literal("agent").annotate({
+    description: "[UNSTABLE] Source that produced a terminal approval auto-review decision.",
+  });
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__FileSystemAccessMode =
+  | "read"
+  | "write"
+  | "none";
+export const V2ItemGuardianApprovalReviewCompletedNotification__FileSystemAccessMode =
+  Schema.Literals(["read", "write", "none"]);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSpecialPath =
+  Schema.Union(
+    [
+      Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+        title: "RootFileSystemSpecialPath",
+      }),
+      Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+        title: "MinimalFileSystemSpecialPath",
+      }),
+      Schema.Struct({
+        kind: Schema.Literal("project_roots"),
+        subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      }).annotate({ title: "KindFileSystemSpecialPath" }),
+      Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+        title: "TmpdirFileSystemSpecialPath",
+      }),
+      Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+        title: "SlashTmpFileSystemSpecialPath",
+      }),
+      Schema.Struct({
+        kind: Schema.Literal("unknown"),
+        path: Schema.String,
+        subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      }),
+    ],
+    { mode: "oneOf" },
+  );
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewStatus =
+  | "inProgress"
+  | "approved"
+  | "denied"
+  | "timedOut"
+  | "aborted";
+export const V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewStatus =
+  Schema.Literals(["inProgress", "approved", "denied", "timedOut", "aborted"]).annotate({
+    description: "[UNSTABLE] Lifecycle state for an approval auto-review.",
+  });
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__GuardianCommandSource =
+  | "shell"
+  | "unifiedExec";
+export const V2ItemGuardianApprovalReviewCompletedNotification__GuardianCommandSource =
+  Schema.Literals(["shell", "unifiedExec"]);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__GuardianRiskLevel =
+  | "low"
+  | "medium"
+  | "high"
+  | "critical";
+export const V2ItemGuardianApprovalReviewCompletedNotification__GuardianRiskLevel = Schema.Literals(
+  ["low", "medium", "high", "critical"],
+).annotate({ description: "[UNSTABLE] Risk level assigned by approval auto-review." });
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__GuardianUserAuthorization =
+  | "unknown"
+  | "low"
+  | "medium"
+  | "high";
+export const V2ItemGuardianApprovalReviewCompletedNotification__GuardianUserAuthorization =
+  Schema.Literals(["unknown", "low", "medium", "high"]).annotate({
+    description: "[UNSTABLE] Authorization level assigned by approval auto-review.",
+  });
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__NetworkApprovalProtocol =
+  | "http"
+  | "https"
+  | "socks5Tcp"
+  | "socks5Udp";
+export const V2ItemGuardianApprovalReviewCompletedNotification__NetworkApprovalProtocol =
+  Schema.Literals(["http", "https", "socks5Tcp", "socks5Udp"]);
+
+export type V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf = string;
+export const V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf =
+  Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__AdditionalNetworkPermissions = {
+  readonly enabled?: boolean | null;
+};
+export const V2ItemGuardianApprovalReviewStartedNotification__AdditionalNetworkPermissions =
+  Schema.Struct({ enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])) });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__FileSystemAccessMode =
+  | "read"
+  | "write"
+  | "none";
+export const V2ItemGuardianApprovalReviewStartedNotification__FileSystemAccessMode =
+  Schema.Literals(["read", "write", "none"]);
+
+export type V2ItemGuardianApprovalReviewStartedNotification__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const V2ItemGuardianApprovalReviewStartedNotification__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewStatus =
+  | "inProgress"
+  | "approved"
+  | "denied"
+  | "timedOut"
+  | "aborted";
+export const V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewStatus =
+  Schema.Literals(["inProgress", "approved", "denied", "timedOut", "aborted"]).annotate({
+    description: "[UNSTABLE] Lifecycle state for an approval auto-review.",
+  });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__GuardianCommandSource =
+  | "shell"
+  | "unifiedExec";
+export const V2ItemGuardianApprovalReviewStartedNotification__GuardianCommandSource =
+  Schema.Literals(["shell", "unifiedExec"]);
+
+export type V2ItemGuardianApprovalReviewStartedNotification__GuardianRiskLevel =
+  | "low"
+  | "medium"
+  | "high"
+  | "critical";
+export const V2ItemGuardianApprovalReviewStartedNotification__GuardianRiskLevel = Schema.Literals([
+  "low",
+  "medium",
+  "high",
+  "critical",
+]).annotate({ description: "[UNSTABLE] Risk level assigned by approval auto-review." });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__GuardianUserAuthorization =
+  | "unknown"
+  | "low"
+  | "medium"
+  | "high";
+export const V2ItemGuardianApprovalReviewStartedNotification__GuardianUserAuthorization =
+  Schema.Literals(["unknown", "low", "medium", "high"]).annotate({
+    description: "[UNSTABLE] Authorization level assigned by approval auto-review.",
+  });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__NetworkApprovalProtocol =
+  | "http"
+  | "https"
+  | "socks5Tcp"
+  | "socks5Udp";
+export const V2ItemGuardianApprovalReviewStartedNotification__NetworkApprovalProtocol =
+  Schema.Literals(["http", "https", "socks5Tcp", "socks5Udp"]);
+
+export type V2ItemStartedNotification__AbsolutePathBuf = string;
+export const V2ItemStartedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ItemStartedNotification__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ItemStartedNotification__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ItemStartedNotification__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ItemStartedNotification__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ItemStartedNotification__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ItemStartedNotification__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemStartedNotification__DynamicToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ItemStartedNotification__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ItemStartedNotification__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ItemStartedNotification__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ItemStartedNotification__McpToolCallError = { readonly message: string };
+export const V2ItemStartedNotification__McpToolCallError = Schema.Struct({
+  message: Schema.String,
+});
+
+export type V2ItemStartedNotification__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ItemStartedNotification__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ItemStartedNotification__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ItemStartedNotification__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ItemStartedNotification__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ItemStartedNotification__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ItemStartedNotification__MessagePhase = "commentary" | "final_answer";
+export const V2ItemStartedNotification__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ItemStartedNotification__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ItemStartedNotification__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ItemStartedNotification__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ItemStartedNotification__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemStartedNotification__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ItemStartedNotification__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ItemStartedNotification__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ItemStartedNotification__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ItemStartedNotification__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ItemStartedNotification__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ListMcpServerStatusParams__McpServerStatusDetail = "full" | "toolsAndAuthOnly";
+export const V2ListMcpServerStatusParams__McpServerStatusDetail = Schema.Literals([
+  "full",
+  "toolsAndAuthOnly",
+]);
+
+export type V2ListMcpServerStatusResponse__McpAuthStatus =
+  | "unsupported"
+  | "notLoggedIn"
+  | "bearerToken"
+  | "oAuth";
+export const V2ListMcpServerStatusResponse__McpAuthStatus = Schema.Literals([
+  "unsupported",
+  "notLoggedIn",
+  "bearerToken",
+  "oAuth",
+]);
+
+export type V2ListMcpServerStatusResponse__Resource = {
+  readonly _meta?: unknown;
+  readonly annotations?: unknown;
+  readonly description?: string | null;
+  readonly icons?: ReadonlyArray<unknown> | null;
+  readonly mimeType?: string | null;
+  readonly name: string;
+  readonly size?: number | null;
+  readonly title?: string | null;
+  readonly uri: string;
+};
+export const V2ListMcpServerStatusResponse__Resource = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  annotations: Schema.optionalKey(Schema.Unknown),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  icons: Schema.optionalKey(Schema.Union([Schema.Array(Schema.Unknown), Schema.Null])),
+  mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  size: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  uri: Schema.String,
+}).annotate({ description: "A known resource that the server is capable of reading." });
+
+export type V2ListMcpServerStatusResponse__ResourceTemplate = {
+  readonly annotations?: unknown;
+  readonly description?: string | null;
+  readonly mimeType?: string | null;
+  readonly name: string;
+  readonly title?: string | null;
+  readonly uriTemplate: string;
+};
+export const V2ListMcpServerStatusResponse__ResourceTemplate = Schema.Struct({
+  annotations: Schema.optionalKey(Schema.Unknown),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  uriTemplate: Schema.String,
+}).annotate({ description: "A template description for resources available on the server." });
+
+export type V2ListMcpServerStatusResponse__Tool = {
+  readonly _meta?: unknown;
+  readonly annotations?: unknown;
+  readonly description?: string | null;
+  readonly icons?: ReadonlyArray<unknown> | null;
+  readonly inputSchema: unknown;
+  readonly name: string;
+  readonly outputSchema?: unknown;
+  readonly title?: string | null;
+};
+export const V2ListMcpServerStatusResponse__Tool = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  annotations: Schema.optionalKey(Schema.Unknown),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  icons: Schema.optionalKey(Schema.Union([Schema.Array(Schema.Unknown), Schema.Null])),
+  inputSchema: Schema.Unknown,
+  name: Schema.String,
+  outputSchema: Schema.optionalKey(Schema.Unknown),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ description: "Definition for a tool the client can call." });
+
+export type V2MarketplaceAddResponse__AbsolutePathBuf = string;
+export const V2MarketplaceAddResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2MarketplaceRemoveResponse__AbsolutePathBuf = string;
+export const V2MarketplaceRemoveResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2MarketplaceUpgradeResponse__AbsolutePathBuf = string;
+export const V2MarketplaceUpgradeResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2MarketplaceUpgradeResponse__MarketplaceUpgradeErrorInfo = {
+  readonly marketplaceName: string;
+  readonly message: string;
+};
+export const V2MarketplaceUpgradeResponse__MarketplaceUpgradeErrorInfo = Schema.Struct({
+  marketplaceName: Schema.String,
+  message: Schema.String,
+});
+
+export type V2McpResourceReadResponse__ResourceContent =
+  | {
+      readonly _meta?: unknown;
+      readonly mimeType?: string | null;
+      readonly text: string;
+      readonly uri: string;
+    }
+  | {
+      readonly _meta?: unknown;
+      readonly blob: string;
+      readonly mimeType?: string | null;
+      readonly uri: string;
+    };
+export const V2McpResourceReadResponse__ResourceContent = Schema.Union([
+  Schema.Struct({
+    _meta: Schema.optionalKey(Schema.Unknown),
+    mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    text: Schema.String,
+    uri: Schema.String.annotate({ description: "The URI of this resource." }),
+  }),
+  Schema.Struct({
+    _meta: Schema.optionalKey(Schema.Unknown),
+    blob: Schema.String,
+    mimeType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    uri: Schema.String.annotate({ description: "The URI of this resource." }),
+  }),
+]).annotate({ description: "Contents returned when reading a resource from an MCP server." });
+
+export type V2McpServerStatusUpdatedNotification__McpServerStartupState =
+  | "starting"
+  | "ready"
+  | "failed"
+  | "cancelled";
+export const V2McpServerStatusUpdatedNotification__McpServerStartupState = Schema.Literals([
+  "starting",
+  "ready",
+  "failed",
+  "cancelled",
+]);
+
+export type V2ModelListResponse__InputModality = "text" | "image";
+export const V2ModelListResponse__InputModality = Schema.Literals(["text", "image"]).annotate({
+  description: "Canonical user-input modality tags advertised by a model.",
+});
+
+export type V2ModelListResponse__ModelAvailabilityNux = { readonly message: string };
+export const V2ModelListResponse__ModelAvailabilityNux = Schema.Struct({ message: Schema.String });
+
+export type V2ModelListResponse__ModelServiceTier = {
+  readonly description: string;
+  readonly id: string;
+  readonly name: string;
+};
+export const V2ModelListResponse__ModelServiceTier = Schema.Struct({
+  description: Schema.String,
+  id: Schema.String,
+  name: Schema.String,
+});
+
+export type V2ModelListResponse__ModelUpgradeInfo = {
+  readonly migrationMarkdown?: string | null;
+  readonly model: string;
+  readonly modelLink?: string | null;
+  readonly upgradeCopy?: string | null;
+};
+export const V2ModelListResponse__ModelUpgradeInfo = Schema.Struct({
+  migrationMarkdown: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  model: Schema.String,
+  modelLink: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  upgradeCopy: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ModelListResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ModelListResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ModelReroutedNotification__ModelRerouteReason = "highRiskCyberActivity";
+export const V2ModelReroutedNotification__ModelRerouteReason =
+  Schema.Literal("highRiskCyberActivity");
+
+export type V2ModelVerificationNotification__ModelVerification = "trustedAccessForCyber";
+export const V2ModelVerificationNotification__ModelVerification =
+  Schema.Literal("trustedAccessForCyber");
+
+export type V2PluginInstallParams__AbsolutePathBuf = string;
+export const V2PluginInstallParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2PluginInstallResponse__AppSummary = {
+  readonly description?: string | null;
+  readonly id: string;
+  readonly installUrl?: string | null;
+  readonly name: string;
+  readonly needsAuth: boolean;
+};
+export const V2PluginInstallResponse__AppSummary = Schema.Struct({
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  id: Schema.String,
+  installUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  needsAuth: Schema.Boolean,
+}).annotate({ description: "EXPERIMENTAL - app metadata summary for plugin responses." });
+
+export type V2PluginInstallResponse__PluginAuthPolicy = "ON_INSTALL" | "ON_USE";
+export const V2PluginInstallResponse__PluginAuthPolicy = Schema.Literals(["ON_INSTALL", "ON_USE"]);
+
+export type V2PluginListParams__AbsolutePathBuf = string;
+export const V2PluginListParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2PluginListParams__PluginListMarketplaceKind =
+  | "local"
+  | "workspace-directory"
+  | "shared-with-me";
+export const V2PluginListParams__PluginListMarketplaceKind = Schema.Literals([
+  "local",
+  "workspace-directory",
+  "shared-with-me",
+]);
+
+export type V2PluginListResponse__AbsolutePathBuf = string;
+export const V2PluginListResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2PluginListResponse__MarketplaceInterface = { readonly displayName?: string | null };
+export const V2PluginListResponse__MarketplaceInterface = Schema.Struct({
+  displayName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginListResponse__PluginAuthPolicy = "ON_INSTALL" | "ON_USE";
+export const V2PluginListResponse__PluginAuthPolicy = Schema.Literals(["ON_INSTALL", "ON_USE"]);
+
+export type V2PluginListResponse__PluginInstallPolicy =
+  | "NOT_AVAILABLE"
+  | "AVAILABLE"
+  | "INSTALLED_BY_DEFAULT";
+export const V2PluginListResponse__PluginInstallPolicy = Schema.Literals([
+  "NOT_AVAILABLE",
+  "AVAILABLE",
+  "INSTALLED_BY_DEFAULT",
+]);
+
+export type V2PluginListResponse__PluginSharePrincipalType = "user" | "group" | "workspace";
+export const V2PluginListResponse__PluginSharePrincipalType = Schema.Literals([
+  "user",
+  "group",
+  "workspace",
+]);
+
+export type V2PluginReadParams__AbsolutePathBuf = string;
+export const V2PluginReadParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2PluginReadResponse__AbsolutePathBuf = string;
+export const V2PluginReadResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2PluginReadResponse__AppSummary = {
+  readonly description?: string | null;
+  readonly id: string;
+  readonly installUrl?: string | null;
+  readonly name: string;
+  readonly needsAuth: boolean;
+};
+export const V2PluginReadResponse__AppSummary = Schema.Struct({
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  id: Schema.String,
+  installUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  needsAuth: Schema.Boolean,
+}).annotate({ description: "EXPERIMENTAL - app metadata summary for plugin responses." });
+
+export type V2PluginReadResponse__HookEventName =
+  | "preToolUse"
+  | "permissionRequest"
+  | "postToolUse"
+  | "preCompact"
+  | "postCompact"
+  | "sessionStart"
+  | "userPromptSubmit"
+  | "stop";
+export const V2PluginReadResponse__HookEventName = Schema.Literals([
+  "preToolUse",
+  "permissionRequest",
+  "postToolUse",
+  "preCompact",
+  "postCompact",
+  "sessionStart",
+  "userPromptSubmit",
+  "stop",
+]);
+
+export type V2PluginReadResponse__PluginAuthPolicy = "ON_INSTALL" | "ON_USE";
+export const V2PluginReadResponse__PluginAuthPolicy = Schema.Literals(["ON_INSTALL", "ON_USE"]);
+
+export type V2PluginReadResponse__PluginInstallPolicy =
+  | "NOT_AVAILABLE"
+  | "AVAILABLE"
+  | "INSTALLED_BY_DEFAULT";
+export const V2PluginReadResponse__PluginInstallPolicy = Schema.Literals([
+  "NOT_AVAILABLE",
+  "AVAILABLE",
+  "INSTALLED_BY_DEFAULT",
+]);
+
+export type V2PluginReadResponse__PluginSharePrincipalType = "user" | "group" | "workspace";
+export const V2PluginReadResponse__PluginSharePrincipalType = Schema.Literals([
+  "user",
+  "group",
+  "workspace",
+]);
+
+export type V2PluginShareListResponse__AbsolutePathBuf = string;
+export const V2PluginShareListResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2PluginShareListResponse__PluginAuthPolicy = "ON_INSTALL" | "ON_USE";
+export const V2PluginShareListResponse__PluginAuthPolicy = Schema.Literals([
+  "ON_INSTALL",
+  "ON_USE",
+]);
+
+export type V2PluginShareListResponse__PluginInstallPolicy =
+  | "NOT_AVAILABLE"
+  | "AVAILABLE"
+  | "INSTALLED_BY_DEFAULT";
+export const V2PluginShareListResponse__PluginInstallPolicy = Schema.Literals([
+  "NOT_AVAILABLE",
+  "AVAILABLE",
+  "INSTALLED_BY_DEFAULT",
+]);
+
+export type V2PluginShareListResponse__PluginSharePrincipalType = "user" | "group" | "workspace";
+export const V2PluginShareListResponse__PluginSharePrincipalType = Schema.Literals([
+  "user",
+  "group",
+  "workspace",
+]);
+
+export type V2PluginShareSaveParams__AbsolutePathBuf = string;
+export const V2PluginShareSaveParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2PluginShareSaveParams__PluginShareDiscoverability = "LISTED" | "UNLISTED" | "PRIVATE";
+export const V2PluginShareSaveParams__PluginShareDiscoverability = Schema.Literals([
+  "LISTED",
+  "UNLISTED",
+  "PRIVATE",
+]);
+
+export type V2PluginShareSaveParams__PluginSharePrincipalType = "user" | "group" | "workspace";
+export const V2PluginShareSaveParams__PluginSharePrincipalType = Schema.Literals([
+  "user",
+  "group",
+  "workspace",
+]);
+
+export type V2PluginShareUpdateTargetsParams__PluginSharePrincipalType =
+  | "user"
+  | "group"
+  | "workspace";
+export const V2PluginShareUpdateTargetsParams__PluginSharePrincipalType = Schema.Literals([
+  "user",
+  "group",
+  "workspace",
+]);
+
+export type V2PluginShareUpdateTargetsResponse__PluginSharePrincipalType =
+  | "user"
+  | "group"
+  | "workspace";
+export const V2PluginShareUpdateTargetsResponse__PluginSharePrincipalType = Schema.Literals([
+  "user",
+  "group",
+  "workspace",
+]);
+
+export type V2RawResponseItemCompletedNotification__ImageDetail =
+  | "auto"
+  | "low"
+  | "high"
+  | "original";
+export const V2RawResponseItemCompletedNotification__ImageDetail = Schema.Literals([
+  "auto",
+  "low",
+  "high",
+  "original",
+]);
+
+export type V2RawResponseItemCompletedNotification__LocalShellAction = {
+  readonly command: ReadonlyArray<string>;
+  readonly env?: { readonly [x: string]: string } | null;
+  readonly timeout_ms?: number | null;
+  readonly type: "exec";
+  readonly user?: string | null;
+  readonly working_directory?: string | null;
+};
+export const V2RawResponseItemCompletedNotification__LocalShellAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.Array(Schema.String),
+      env: Schema.optionalKey(
+        Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+      ),
+      timeout_ms: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint64" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("exec").annotate({ title: "ExecLocalShellActionType" }),
+      user: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      working_directory: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "ExecLocalShellAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2RawResponseItemCompletedNotification__LocalShellStatus =
+  | "completed"
+  | "in_progress"
+  | "incomplete";
+export const V2RawResponseItemCompletedNotification__LocalShellStatus = Schema.Literals([
+  "completed",
+  "in_progress",
+  "incomplete",
+]);
+
+export type V2RawResponseItemCompletedNotification__MessagePhase = "commentary" | "final_answer";
+export const V2RawResponseItemCompletedNotification__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2RawResponseItemCompletedNotification__ReasoningItemContent =
+  | { readonly text: string; readonly type: "reasoning_text" }
+  | { readonly text: string; readonly type: "text" };
+export const V2RawResponseItemCompletedNotification__ReasoningItemContent = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("reasoning_text").annotate({
+        title: "ReasoningTextReasoningItemContentType",
+      }),
+    }).annotate({ title: "ReasoningTextReasoningItemContent" }),
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("text").annotate({ title: "TextReasoningItemContentType" }),
+    }).annotate({ title: "TextReasoningItemContent" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2RawResponseItemCompletedNotification__ReasoningItemReasoningSummary = {
+  readonly text: string;
+  readonly type: "summary_text";
+};
+export const V2RawResponseItemCompletedNotification__ReasoningItemReasoningSummary = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("summary_text").annotate({
+        title: "SummaryTextReasoningItemReasoningSummaryType",
+      }),
+    }).annotate({ title: "SummaryTextReasoningItemReasoningSummary" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2RawResponseItemCompletedNotification__ResponsesApiWebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "open_page"; readonly url?: string | null }
+  | {
+      readonly pattern?: string | null;
+      readonly type: "find_in_page";
+      readonly url?: string | null;
+    }
+  | { readonly type: "other" };
+export const V2RawResponseItemCompletedNotification__ResponsesApiWebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchResponsesApiWebSearchActionType" }),
+    }).annotate({ title: "SearchResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("open_page").annotate({
+        title: "OpenPageResponsesApiWebSearchActionType",
+      }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("find_in_page").annotate({
+        title: "FindInPageResponsesApiWebSearchActionType",
+      }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherResponsesApiWebSearchActionType" }),
+    }).annotate({ title: "OtherResponsesApiWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2RemoteControlStatusChangedNotification__RemoteControlConnectionStatus =
+  | "disabled"
+  | "connecting"
+  | "connected"
+  | "errored";
+export const V2RemoteControlStatusChangedNotification__RemoteControlConnectionStatus =
+  Schema.Literals(["disabled", "connecting", "connected", "errored"]);
+
+export type V2ReviewStartParams__ReviewDelivery = "inline" | "detached";
+export const V2ReviewStartParams__ReviewDelivery = Schema.Literals(["inline", "detached"]);
+
+export type V2ReviewStartParams__ReviewTarget =
+  | { readonly type: "uncommittedChanges" }
+  | { readonly branch: string; readonly type: "baseBranch" }
+  | { readonly sha: string; readonly title?: string | null; readonly type: "commit" }
+  | { readonly instructions: string; readonly type: "custom" };
+export const V2ReviewStartParams__ReviewTarget = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("uncommittedChanges").annotate({
+        title: "UncommittedChangesReviewTargetType",
+      }),
+    }).annotate({
+      title: "UncommittedChangesReviewTarget",
+      description: "Review the working tree: staged, unstaged, and untracked files.",
+    }),
+    Schema.Struct({
+      branch: Schema.String,
+      type: Schema.Literal("baseBranch").annotate({ title: "BaseBranchReviewTargetType" }),
+    }).annotate({
+      title: "BaseBranchReviewTarget",
+      description: "Review changes between the current branch and the given base branch.",
+    }),
+    Schema.Struct({
+      sha: Schema.String,
+      title: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Optional human-readable label (e.g., commit subject) for UIs.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("commit").annotate({ title: "CommitReviewTargetType" }),
+    }).annotate({
+      title: "CommitReviewTarget",
+      description: "Review the changes introduced by a specific commit.",
+    }),
+    Schema.Struct({
+      instructions: Schema.String,
+      type: Schema.Literal("custom").annotate({ title: "CustomReviewTargetType" }),
+    }).annotate({
+      title: "CustomReviewTarget",
+      description: "Arbitrary instructions, equivalent to the old free-form prompt.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ReviewStartResponse__AbsolutePathBuf = string;
+export const V2ReviewStartResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ReviewStartResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ReviewStartResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ReviewStartResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ReviewStartResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ReviewStartResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ReviewStartResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ReviewStartResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ReviewStartResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ReviewStartResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ReviewStartResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ReviewStartResponse__McpToolCallError = { readonly message: string };
+export const V2ReviewStartResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2ReviewStartResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ReviewStartResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ReviewStartResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ReviewStartResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ReviewStartResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ReviewStartResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ReviewStartResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ReviewStartResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ReviewStartResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ReviewStartResponse__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2ReviewStartResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ReviewStartResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ReviewStartResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ReviewStartResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ReviewStartResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ReviewStartResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ReviewStartResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ReviewStartResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ReviewStartResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ReviewStartResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ReviewStartResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ReviewStartResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2SendAddCreditsNudgeEmailParams__AddCreditsNudgeCreditType = "credits" | "usage_limit";
+export const V2SendAddCreditsNudgeEmailParams__AddCreditsNudgeCreditType = Schema.Literals([
+  "credits",
+  "usage_limit",
+]);
+
+export type V2SendAddCreditsNudgeEmailResponse__AddCreditsNudgeEmailStatus =
+  | "sent"
+  | "cooldown_active";
+export const V2SendAddCreditsNudgeEmailResponse__AddCreditsNudgeEmailStatus = Schema.Literals([
+  "sent",
+  "cooldown_active",
+]);
+
+export type V2ServerRequestResolvedNotification__RequestId = string | number;
+export const V2ServerRequestResolvedNotification__RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]);
+
+export type V2SkillsConfigWriteParams__AbsolutePathBuf = string;
+export const V2SkillsConfigWriteParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2SkillsListParams__SkillsListExtraRootsForCwd = {
+  readonly cwd: string;
+  readonly extraUserRoots: ReadonlyArray<string>;
+};
+export const V2SkillsListParams__SkillsListExtraRootsForCwd = Schema.Struct({
+  cwd: Schema.String,
+  extraUserRoots: Schema.Array(Schema.String),
+});
+
+export type V2SkillsListResponse__AbsolutePathBuf = string;
+export const V2SkillsListResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2SkillsListResponse__SkillErrorInfo = {
+  readonly message: string;
+  readonly path: string;
+};
+export const V2SkillsListResponse__SkillErrorInfo = Schema.Struct({
+  message: Schema.String,
+  path: Schema.String,
+});
+
+export type V2SkillsListResponse__SkillScope = "user" | "repo" | "system" | "admin";
+export const V2SkillsListResponse__SkillScope = Schema.Literals([
+  "user",
+  "repo",
+  "system",
+  "admin",
+]);
+
+export type V2SkillsListResponse__SkillToolDependency = {
+  readonly command?: string | null;
+  readonly description?: string | null;
+  readonly transport?: string | null;
+  readonly type: string;
+  readonly url?: string | null;
+  readonly value: string;
+};
+export const V2SkillsListResponse__SkillToolDependency = Schema.Struct({
+  command: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  transport: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: Schema.String,
+  url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  value: Schema.String,
+});
+
+export type V2ThreadForkParams__AbsolutePathBuf = string;
+export const V2ThreadForkParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadForkParams__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const V2ThreadForkParams__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ThreadForkParams__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ThreadForkParams__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkParams__SandboxMode =
+  | "read-only"
+  | "workspace-write"
+  | "danger-full-access";
+export const V2ThreadForkParams__SandboxMode = Schema.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access",
+]);
+
+export type V2ThreadForkParams__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadForkParams__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadForkResponse__AbsolutePathBuf = string;
+export const V2ThreadForkResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadForkResponse__AgentPath = string;
+export const V2ThreadForkResponse__AgentPath = Schema.String;
+
+export type V2ThreadForkResponse__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ThreadForkResponse__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadForkResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadForkResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadForkResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadForkResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadForkResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadForkResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadForkResponse__FileSystemAccessMode = "read" | "write" | "none";
+export const V2ThreadForkResponse__FileSystemAccessMode = Schema.Literals([
+  "read",
+  "write",
+  "none",
+]);
+
+export type V2ThreadForkResponse__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const V2ThreadForkResponse__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadForkResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadForkResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadForkResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadForkResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadForkResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2ThreadForkResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadForkResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadForkResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadForkResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadForkResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadForkResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadForkResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadForkResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadForkResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadForkResponse__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2ThreadForkResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadForkResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadForkResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadForkResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__PermissionProfileNetworkPermissions = {
+  readonly enabled: boolean;
+};
+export const V2ThreadForkResponse__PermissionProfileNetworkPermissions = Schema.Struct({
+  enabled: Schema.Boolean,
+});
+
+export type V2ThreadForkResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadForkResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadForkResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadForkResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadForkResponse__ThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
+export const V2ThreadForkResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadForkResponse__ThreadId = string;
+export const V2ThreadForkResponse__ThreadId = Schema.String;
+
+export type V2ThreadForkResponse__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadForkResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadForkResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadForkResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadForkResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadForkResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadGoalUpdatedNotification__ThreadGoalStatus =
+  | "active"
+  | "paused"
+  | "budgetLimited"
+  | "complete";
+export const V2ThreadGoalUpdatedNotification__ThreadGoalStatus = Schema.Literals([
+  "active",
+  "paused",
+  "budgetLimited",
+  "complete",
+]);
+
+export type V2ThreadListParams__SortDirection = "asc" | "desc";
+export const V2ThreadListParams__SortDirection = Schema.Literals(["asc", "desc"]);
+
+export type V2ThreadListParams__ThreadListCwdFilter = string | ReadonlyArray<string>;
+export const V2ThreadListParams__ThreadListCwdFilter = Schema.Union([
+  Schema.String,
+  Schema.Array(Schema.String),
+]);
+
+export type V2ThreadListParams__ThreadSortKey = "created_at" | "updated_at";
+export const V2ThreadListParams__ThreadSortKey = Schema.Literals(["created_at", "updated_at"]);
+
+export type V2ThreadListParams__ThreadSourceKind =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "subAgent"
+  | "subAgentReview"
+  | "subAgentCompact"
+  | "subAgentThreadSpawn"
+  | "subAgentOther"
+  | "unknown";
+export const V2ThreadListParams__ThreadSourceKind = Schema.Literals([
+  "cli",
+  "vscode",
+  "exec",
+  "appServer",
+  "subAgent",
+  "subAgentReview",
+  "subAgentCompact",
+  "subAgentThreadSpawn",
+  "subAgentOther",
+  "unknown",
+]);
+
+export type V2ThreadListResponse__AbsolutePathBuf = string;
+export const V2ThreadListResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadListResponse__AgentPath = string;
+export const V2ThreadListResponse__AgentPath = Schema.String;
+
+export type V2ThreadListResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadListResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadListResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadListResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadListResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadListResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadListResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadListResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadListResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadListResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadListResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadListResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadListResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadListResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2ThreadListResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadListResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadListResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadListResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadListResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadListResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadListResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadListResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadListResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadListResponse__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2ThreadListResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadListResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadListResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadListResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadListResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadListResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadListResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadListResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadListResponse__ThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
+export const V2ThreadListResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadListResponse__ThreadId = string;
+export const V2ThreadListResponse__ThreadId = Schema.String;
+
+export type V2ThreadListResponse__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadListResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadListResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadListResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadListResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadListResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateParams__ThreadMetadataGitInfoUpdateParams = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadMetadataUpdateParams__ThreadMetadataGitInfoUpdateParams = Schema.Struct({
+  branch: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Omit to leave the stored branch unchanged, set to `null` to clear it, or provide a non-empty string to replace it.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  originUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Omit to leave the stored origin URL unchanged, set to `null` to clear it, or provide a non-empty string to replace it.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sha: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Omit to leave the stored commit unchanged, set to `null` to clear it, or provide a non-empty string to replace it.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadMetadataUpdateResponse__AbsolutePathBuf = string;
+export const V2ThreadMetadataUpdateResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadMetadataUpdateResponse__AgentPath = string;
+export const V2ThreadMetadataUpdateResponse__AgentPath = Schema.String;
+
+export type V2ThreadMetadataUpdateResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadMetadataUpdateResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadMetadataUpdateResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadMetadataUpdateResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadMetadataUpdateResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadMetadataUpdateResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__DynamicToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadMetadataUpdateResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadMetadataUpdateResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadMetadataUpdateResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadMetadataUpdateResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadMetadataUpdateResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadMetadataUpdateResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadMetadataUpdateResponse__McpToolCallError = Schema.Struct({
+  message: Schema.String,
+});
+
+export type V2ThreadMetadataUpdateResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadMetadataUpdateResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadMetadataUpdateResponse__McpToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadMetadataUpdateResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadMetadataUpdateResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadMetadataUpdateResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadMetadataUpdateResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadMetadataUpdateResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadMetadataUpdateResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadMetadataUpdateResponse__NonSteerableTurnKind = Schema.Literals([
+  "review",
+  "compact",
+]);
+
+export type V2ThreadMetadataUpdateResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadMetadataUpdateResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadMetadataUpdateResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadMetadataUpdateResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadMetadataUpdateResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadMetadataUpdateResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadMetadataUpdateResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadMetadataUpdateResponse__ThreadActiveFlag =
+  | "waitingOnApproval"
+  | "waitingOnUserInput";
+export const V2ThreadMetadataUpdateResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadMetadataUpdateResponse__ThreadId = string;
+export const V2ThreadMetadataUpdateResponse__ThreadId = Schema.String;
+
+export type V2ThreadMetadataUpdateResponse__ThreadSource =
+  | "user"
+  | "subagent"
+  | "memory_consolidation";
+export const V2ThreadMetadataUpdateResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadMetadataUpdateResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadMetadataUpdateResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadMetadataUpdateResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadMetadataUpdateResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__AbsolutePathBuf = string;
+export const V2ThreadReadResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadReadResponse__AgentPath = string;
+export const V2ThreadReadResponse__AgentPath = Schema.String;
+
+export type V2ThreadReadResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadReadResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadReadResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadReadResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadReadResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadReadResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadReadResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadReadResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadReadResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadReadResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadReadResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadReadResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadReadResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2ThreadReadResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadReadResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadReadResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadReadResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadReadResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadReadResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadReadResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadReadResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadReadResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadReadResponse__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2ThreadReadResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadReadResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadReadResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadReadResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadReadResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadReadResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadReadResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadReadResponse__ThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
+export const V2ThreadReadResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadReadResponse__ThreadId = string;
+export const V2ThreadReadResponse__ThreadId = Schema.String;
+
+export type V2ThreadReadResponse__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadReadResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadReadResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadReadResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadReadResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadReadResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRealtimeOutputAudioDeltaNotification__ThreadRealtimeAudioChunk = {
+  readonly data: string;
+  readonly itemId?: string | null;
+  readonly numChannels: number;
+  readonly sampleRate: number;
+  readonly samplesPerChannel?: number | null;
+};
+export const V2ThreadRealtimeOutputAudioDeltaNotification__ThreadRealtimeAudioChunk = Schema.Struct(
+  {
+    data: Schema.String,
+    itemId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    numChannels: Schema.Number.annotate({ format: "uint16" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    sampleRate: Schema.Number.annotate({ format: "uint32" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    samplesPerChannel: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint32" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        Schema.Null,
+      ]),
+    ),
+  },
+).annotate({ description: "EXPERIMENTAL - thread realtime audio chunk." });
+
+export type V2ThreadRealtimeStartedNotification__RealtimeConversationVersion = "v1" | "v2";
+export const V2ThreadRealtimeStartedNotification__RealtimeConversationVersion = Schema.Literals([
+  "v1",
+  "v2",
+]);
+
+export type V2ThreadResumeParams__AbsolutePathBuf = string;
+export const V2ThreadResumeParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadResumeParams__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const V2ThreadResumeParams__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ThreadResumeParams__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ThreadResumeParams__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__ImageDetail = "auto" | "low" | "high" | "original";
+export const V2ThreadResumeParams__ImageDetail = Schema.Literals([
+  "auto",
+  "low",
+  "high",
+  "original",
+]);
+
+export type V2ThreadResumeParams__LocalShellAction = {
+  readonly command: ReadonlyArray<string>;
+  readonly env?: { readonly [x: string]: string } | null;
+  readonly timeout_ms?: number | null;
+  readonly type: "exec";
+  readonly user?: string | null;
+  readonly working_directory?: string | null;
+};
+export const V2ThreadResumeParams__LocalShellAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.Array(Schema.String),
+      env: Schema.optionalKey(
+        Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+      ),
+      timeout_ms: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint64" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(0)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("exec").annotate({ title: "ExecLocalShellActionType" }),
+      user: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      working_directory: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "ExecLocalShellAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__LocalShellStatus = "completed" | "in_progress" | "incomplete";
+export const V2ThreadResumeParams__LocalShellStatus = Schema.Literals([
+  "completed",
+  "in_progress",
+  "incomplete",
+]);
+
+export type V2ThreadResumeParams__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadResumeParams__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadResumeParams__Personality = "none" | "friendly" | "pragmatic";
+export const V2ThreadResumeParams__Personality = Schema.Literals(["none", "friendly", "pragmatic"]);
+
+export type V2ThreadResumeParams__ReasoningItemContent =
+  | { readonly text: string; readonly type: "reasoning_text" }
+  | { readonly text: string; readonly type: "text" };
+export const V2ThreadResumeParams__ReasoningItemContent = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("reasoning_text").annotate({
+        title: "ReasoningTextReasoningItemContentType",
+      }),
+    }).annotate({ title: "ReasoningTextReasoningItemContent" }),
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("text").annotate({ title: "TextReasoningItemContentType" }),
+    }).annotate({ title: "TextReasoningItemContent" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__ReasoningItemReasoningSummary = {
+  readonly text: string;
+  readonly type: "summary_text";
+};
+export const V2ThreadResumeParams__ReasoningItemReasoningSummary = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("summary_text").annotate({
+        title: "SummaryTextReasoningItemReasoningSummaryType",
+      }),
+    }).annotate({ title: "SummaryTextReasoningItemReasoningSummary" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__ResponsesApiWebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "open_page"; readonly url?: string | null }
+  | {
+      readonly pattern?: string | null;
+      readonly type: "find_in_page";
+      readonly url?: string | null;
+    }
+  | { readonly type: "other" };
+export const V2ThreadResumeParams__ResponsesApiWebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchResponsesApiWebSearchActionType" }),
+    }).annotate({ title: "SearchResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("open_page").annotate({
+        title: "OpenPageResponsesApiWebSearchActionType",
+      }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("find_in_page").annotate({
+        title: "FindInPageResponsesApiWebSearchActionType",
+      }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageResponsesApiWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherResponsesApiWebSearchActionType" }),
+    }).annotate({ title: "OtherResponsesApiWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__SandboxMode =
+  | "read-only"
+  | "workspace-write"
+  | "danger-full-access";
+export const V2ThreadResumeParams__SandboxMode = Schema.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access",
+]);
+
+export type V2ThreadResumeResponse__AbsolutePathBuf = string;
+export const V2ThreadResumeResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadResumeResponse__AgentPath = string;
+export const V2ThreadResumeResponse__AgentPath = Schema.String;
+
+export type V2ThreadResumeResponse__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ThreadResumeResponse__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadResumeResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadResumeResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadResumeResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadResumeResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadResumeResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadResumeResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadResumeResponse__FileSystemAccessMode = "read" | "write" | "none";
+export const V2ThreadResumeResponse__FileSystemAccessMode = Schema.Literals([
+  "read",
+  "write",
+  "none",
+]);
+
+export type V2ThreadResumeResponse__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const V2ThreadResumeResponse__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadResumeResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadResumeResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadResumeResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadResumeResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadResumeResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2ThreadResumeResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadResumeResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadResumeResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadResumeResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadResumeResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadResumeResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadResumeResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadResumeResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadResumeResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadResumeResponse__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2ThreadResumeResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadResumeResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadResumeResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadResumeResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__PermissionProfileNetworkPermissions = {
+  readonly enabled: boolean;
+};
+export const V2ThreadResumeResponse__PermissionProfileNetworkPermissions = Schema.Struct({
+  enabled: Schema.Boolean,
+});
+
+export type V2ThreadResumeResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadResumeResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadResumeResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadResumeResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadResumeResponse__ThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
+export const V2ThreadResumeResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadResumeResponse__ThreadId = string;
+export const V2ThreadResumeResponse__ThreadId = Schema.String;
+
+export type V2ThreadResumeResponse__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadResumeResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadResumeResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadResumeResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadResumeResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadResumeResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__AbsolutePathBuf = string;
+export const V2ThreadRollbackResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadRollbackResponse__AgentPath = string;
+export const V2ThreadRollbackResponse__AgentPath = Schema.String;
+
+export type V2ThreadRollbackResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadRollbackResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadRollbackResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadRollbackResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadRollbackResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadRollbackResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadRollbackResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadRollbackResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadRollbackResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadRollbackResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadRollbackResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadRollbackResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadRollbackResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2ThreadRollbackResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadRollbackResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadRollbackResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadRollbackResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadRollbackResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadRollbackResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadRollbackResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadRollbackResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadRollbackResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadRollbackResponse__NonSteerableTurnKind = Schema.Literals([
+  "review",
+  "compact",
+]);
+
+export type V2ThreadRollbackResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadRollbackResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadRollbackResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadRollbackResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadRollbackResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadRollbackResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadRollbackResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadRollbackResponse__ThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
+export const V2ThreadRollbackResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadRollbackResponse__ThreadId = string;
+export const V2ThreadRollbackResponse__ThreadId = Schema.String;
+
+export type V2ThreadRollbackResponse__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadRollbackResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadRollbackResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadRollbackResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadRollbackResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadRollbackResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__AbsolutePathBuf = string;
+export const V2ThreadStartedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadStartedNotification__AgentPath = string;
+export const V2ThreadStartedNotification__AgentPath = Schema.String;
+
+export type V2ThreadStartedNotification__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadStartedNotification__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadStartedNotification__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadStartedNotification__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadStartedNotification__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadStartedNotification__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__DynamicToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadStartedNotification__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadStartedNotification__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadStartedNotification__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadStartedNotification__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadStartedNotification__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadStartedNotification__McpToolCallError = { readonly message: string };
+export const V2ThreadStartedNotification__McpToolCallError = Schema.Struct({
+  message: Schema.String,
+});
+
+export type V2ThreadStartedNotification__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadStartedNotification__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadStartedNotification__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadStartedNotification__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadStartedNotification__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadStartedNotification__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadStartedNotification__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadStartedNotification__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadStartedNotification__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadStartedNotification__NonSteerableTurnKind = Schema.Literals([
+  "review",
+  "compact",
+]);
+
+export type V2ThreadStartedNotification__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadStartedNotification__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadStartedNotification__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadStartedNotification__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadStartedNotification__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadStartedNotification__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadStartedNotification__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadStartedNotification__ThreadActiveFlag =
+  | "waitingOnApproval"
+  | "waitingOnUserInput";
+export const V2ThreadStartedNotification__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadStartedNotification__ThreadId = string;
+export const V2ThreadStartedNotification__ThreadId = Schema.String;
+
+export type V2ThreadStartedNotification__ThreadSource =
+  | "user"
+  | "subagent"
+  | "memory_consolidation";
+export const V2ThreadStartedNotification__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadStartedNotification__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadStartedNotification__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadStartedNotification__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadStartedNotification__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartParams__AbsolutePathBuf = string;
+export const V2ThreadStartParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadStartParams__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const V2ThreadStartParams__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ThreadStartParams__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ThreadStartParams__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartParams__Personality = "none" | "friendly" | "pragmatic";
+export const V2ThreadStartParams__Personality = Schema.Literals(["none", "friendly", "pragmatic"]);
+
+export type V2ThreadStartParams__SandboxMode =
+  | "read-only"
+  | "workspace-write"
+  | "danger-full-access";
+export const V2ThreadStartParams__SandboxMode = Schema.Literals([
+  "read-only",
+  "workspace-write",
+  "danger-full-access",
+]);
+
+export type V2ThreadStartParams__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadStartParams__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadStartParams__ThreadStartSource = "startup" | "clear";
+export const V2ThreadStartParams__ThreadStartSource = Schema.Literals(["startup", "clear"]);
+
+export type V2ThreadStartResponse__AbsolutePathBuf = string;
+export const V2ThreadStartResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadStartResponse__AgentPath = string;
+export const V2ThreadStartResponse__AgentPath = Schema.String;
+
+export type V2ThreadStartResponse__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2ThreadStartResponse__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadStartResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadStartResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadStartResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadStartResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadStartResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadStartResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadStartResponse__FileSystemAccessMode = "read" | "write" | "none";
+export const V2ThreadStartResponse__FileSystemAccessMode = Schema.Literals([
+  "read",
+  "write",
+  "none",
+]);
+
+export type V2ThreadStartResponse__FileSystemSpecialPath =
+  | { readonly kind: "root" }
+  | { readonly kind: "minimal" }
+  | { readonly kind: "project_roots"; readonly subpath?: string | null }
+  | { readonly kind: "tmpdir" }
+  | { readonly kind: "slash_tmp" }
+  | { readonly kind: "unknown"; readonly path: string; readonly subpath?: string | null };
+export const V2ThreadStartResponse__FileSystemSpecialPath = Schema.Union(
+  [
+    Schema.Struct({ kind: Schema.Literal("root") }).annotate({
+      title: "RootFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("minimal") }).annotate({
+      title: "MinimalFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("project_roots"),
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "KindFileSystemSpecialPath" }),
+    Schema.Struct({ kind: Schema.Literal("tmpdir") }).annotate({
+      title: "TmpdirFileSystemSpecialPath",
+    }),
+    Schema.Struct({ kind: Schema.Literal("slash_tmp") }).annotate({
+      title: "SlashTmpFileSystemSpecialPath",
+    }),
+    Schema.Struct({
+      kind: Schema.Literal("unknown"),
+      path: Schema.String,
+      subpath: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadStartResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadStartResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadStartResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadStartResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadStartResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2ThreadStartResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadStartResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadStartResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadStartResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadStartResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadStartResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadStartResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadStartResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadStartResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadStartResponse__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2ThreadStartResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadStartResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadStartResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadStartResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__PermissionProfileNetworkPermissions = {
+  readonly enabled: boolean;
+};
+export const V2ThreadStartResponse__PermissionProfileNetworkPermissions = Schema.Struct({
+  enabled: Schema.Boolean,
+});
+
+export type V2ThreadStartResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadStartResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadStartResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadStartResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadStartResponse__ThreadActiveFlag = "waitingOnApproval" | "waitingOnUserInput";
+export const V2ThreadStartResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadStartResponse__ThreadId = string;
+export const V2ThreadStartResponse__ThreadId = Schema.String;
+
+export type V2ThreadStartResponse__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadStartResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadStartResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadStartResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadStartResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadStartResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStatusChangedNotification__ThreadActiveFlag =
+  | "waitingOnApproval"
+  | "waitingOnUserInput";
+export const V2ThreadStatusChangedNotification__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadTokenUsageUpdatedNotification__TokenUsageBreakdown = {
+  readonly cachedInputTokens: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly reasoningOutputTokens: number;
+  readonly totalTokens: number;
+};
+export const V2ThreadTokenUsageUpdatedNotification__TokenUsageBreakdown = Schema.Struct({
+  cachedInputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  inputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  outputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  reasoningOutputTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  totalTokens: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+});
+
+export type V2ThreadUnarchiveResponse__AbsolutePathBuf = string;
+export const V2ThreadUnarchiveResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2ThreadUnarchiveResponse__AgentPath = string;
+export const V2ThreadUnarchiveResponse__AgentPath = Schema.String;
+
+export type V2ThreadUnarchiveResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2ThreadUnarchiveResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2ThreadUnarchiveResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadUnarchiveResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadUnarchiveResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2ThreadUnarchiveResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnarchiveResponse__DynamicToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadUnarchiveResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadUnarchiveResponse__GitInfo = {
+  readonly branch?: string | null;
+  readonly originUrl?: string | null;
+  readonly sha?: string | null;
+};
+export const V2ThreadUnarchiveResponse__GitInfo = Schema.Struct({
+  branch: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  originUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadUnarchiveResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2ThreadUnarchiveResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2ThreadUnarchiveResponse__McpToolCallError = { readonly message: string };
+export const V2ThreadUnarchiveResponse__McpToolCallError = Schema.Struct({
+  message: Schema.String,
+});
+
+export type V2ThreadUnarchiveResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2ThreadUnarchiveResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2ThreadUnarchiveResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadUnarchiveResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadUnarchiveResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2ThreadUnarchiveResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2ThreadUnarchiveResponse__MessagePhase = "commentary" | "final_answer";
+export const V2ThreadUnarchiveResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2ThreadUnarchiveResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2ThreadUnarchiveResponse__NonSteerableTurnKind = Schema.Literals([
+  "review",
+  "compact",
+]);
+
+export type V2ThreadUnarchiveResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2ThreadUnarchiveResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2ThreadUnarchiveResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2ThreadUnarchiveResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnarchiveResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2ThreadUnarchiveResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2ThreadUnarchiveResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2ThreadUnarchiveResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadUnarchiveResponse__ThreadActiveFlag =
+  | "waitingOnApproval"
+  | "waitingOnUserInput";
+export const V2ThreadUnarchiveResponse__ThreadActiveFlag = Schema.Literals([
+  "waitingOnApproval",
+  "waitingOnUserInput",
+]);
+
+export type V2ThreadUnarchiveResponse__ThreadId = string;
+export const V2ThreadUnarchiveResponse__ThreadId = Schema.String;
+
+export type V2ThreadUnarchiveResponse__ThreadSource = "user" | "subagent" | "memory_consolidation";
+export const V2ThreadUnarchiveResponse__ThreadSource = Schema.Literals([
+  "user",
+  "subagent",
+  "memory_consolidation",
+]);
+
+export type V2ThreadUnarchiveResponse__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2ThreadUnarchiveResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2ThreadUnarchiveResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2ThreadUnarchiveResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnsubscribeResponse__ThreadUnsubscribeStatus =
+  | "notLoaded"
+  | "notSubscribed"
+  | "unsubscribed";
+export const V2ThreadUnsubscribeResponse__ThreadUnsubscribeStatus = Schema.Literals([
+  "notLoaded",
+  "notSubscribed",
+  "unsubscribed",
+]);
+
+export type V2TurnCompletedNotification__AbsolutePathBuf = string;
+export const V2TurnCompletedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2TurnCompletedNotification__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2TurnCompletedNotification__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2TurnCompletedNotification__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2TurnCompletedNotification__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2TurnCompletedNotification__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2TurnCompletedNotification__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnCompletedNotification__DynamicToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2TurnCompletedNotification__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnCompletedNotification__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2TurnCompletedNotification__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2TurnCompletedNotification__McpToolCallError = { readonly message: string };
+export const V2TurnCompletedNotification__McpToolCallError = Schema.Struct({
+  message: Schema.String,
+});
+
+export type V2TurnCompletedNotification__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2TurnCompletedNotification__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2TurnCompletedNotification__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2TurnCompletedNotification__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnCompletedNotification__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2TurnCompletedNotification__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2TurnCompletedNotification__MessagePhase = "commentary" | "final_answer";
+export const V2TurnCompletedNotification__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2TurnCompletedNotification__NonSteerableTurnKind = "review" | "compact";
+export const V2TurnCompletedNotification__NonSteerableTurnKind = Schema.Literals([
+  "review",
+  "compact",
+]);
+
+export type V2TurnCompletedNotification__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2TurnCompletedNotification__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2TurnCompletedNotification__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2TurnCompletedNotification__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnCompletedNotification__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2TurnCompletedNotification__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2TurnCompletedNotification__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2TurnCompletedNotification__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2TurnCompletedNotification__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2TurnCompletedNotification__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2TurnCompletedNotification__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2TurnCompletedNotification__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnPlanUpdatedNotification__TurnPlanStepStatus =
+  | "pending"
+  | "inProgress"
+  | "completed";
+export const V2TurnPlanUpdatedNotification__TurnPlanStepStatus = Schema.Literals([
+  "pending",
+  "inProgress",
+  "completed",
+]);
+
+export type V2TurnStartedNotification__AbsolutePathBuf = string;
+export const V2TurnStartedNotification__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2TurnStartedNotification__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2TurnStartedNotification__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2TurnStartedNotification__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2TurnStartedNotification__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2TurnStartedNotification__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2TurnStartedNotification__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartedNotification__DynamicToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2TurnStartedNotification__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnStartedNotification__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2TurnStartedNotification__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2TurnStartedNotification__McpToolCallError = { readonly message: string };
+export const V2TurnStartedNotification__McpToolCallError = Schema.Struct({
+  message: Schema.String,
+});
+
+export type V2TurnStartedNotification__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2TurnStartedNotification__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2TurnStartedNotification__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2TurnStartedNotification__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnStartedNotification__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2TurnStartedNotification__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2TurnStartedNotification__MessagePhase = "commentary" | "final_answer";
+export const V2TurnStartedNotification__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2TurnStartedNotification__NonSteerableTurnKind = "review" | "compact";
+export const V2TurnStartedNotification__NonSteerableTurnKind = Schema.Literals([
+  "review",
+  "compact",
+]);
+
+export type V2TurnStartedNotification__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2TurnStartedNotification__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2TurnStartedNotification__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2TurnStartedNotification__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartedNotification__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2TurnStartedNotification__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2TurnStartedNotification__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2TurnStartedNotification__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2TurnStartedNotification__TurnStatus =
+  | "completed"
+  | "interrupted"
+  | "failed"
+  | "inProgress";
+export const V2TurnStartedNotification__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2TurnStartedNotification__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2TurnStartedNotification__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartParams__AbsolutePathBuf = string;
+export const V2TurnStartParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2TurnStartParams__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const V2TurnStartParams__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2TurnStartParams__AskForApproval =
+  | "untrusted"
+  | "on-failure"
+  | "on-request"
+  | "never"
+  | {
+      readonly granular: {
+        readonly mcp_elicitations: boolean;
+        readonly request_permissions?: boolean;
+        readonly rules: boolean;
+        readonly sandbox_approval: boolean;
+        readonly skill_approval?: boolean;
+      };
+    };
+export const V2TurnStartParams__AskForApproval = Schema.Union(
+  [
+    Schema.Literals(["untrusted", "on-failure", "on-request", "never"]),
+    Schema.Struct({
+      granular: Schema.Struct({
+        mcp_elicitations: Schema.Boolean,
+        request_permissions: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        rules: Schema.Boolean,
+        sandbox_approval: Schema.Boolean,
+        skill_approval: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      }),
+    }).annotate({ title: "GranularAskForApproval" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartParams__ModeKind = "plan" | "default";
+export const V2TurnStartParams__ModeKind = Schema.Literals(["plan", "default"]).annotate({
+  description: "Initial collaboration mode to use when the TUI starts.",
+});
+
+export type V2TurnStartParams__Personality = "none" | "friendly" | "pragmatic";
+export const V2TurnStartParams__Personality = Schema.Literals(["none", "friendly", "pragmatic"]);
+
+export type V2TurnStartParams__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2TurnStartParams__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2TurnStartParams__ReasoningSummary = "auto" | "concise" | "detailed" | "none";
+export const V2TurnStartParams__ReasoningSummary = Schema.Union(
+  [
+    Schema.Literals(["auto", "concise", "detailed"]),
+    Schema.Literal("none").annotate({ description: "Option to disable reasoning summaries." }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries",
+});
+
+export type V2TurnStartParams__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2TurnStartParams__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2TurnStartResponse__AbsolutePathBuf = string;
+export const V2TurnStartResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2TurnStartResponse__CollabAgentStatus =
+  | "pendingInit"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "errored"
+  | "shutdown"
+  | "notFound";
+export const V2TurnStartResponse__CollabAgentStatus = Schema.Literals([
+  "pendingInit",
+  "running",
+  "interrupted",
+  "completed",
+  "errored",
+  "shutdown",
+  "notFound",
+]);
+
+export type V2TurnStartResponse__CommandExecutionStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2TurnStartResponse__CommandExecutionStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2TurnStartResponse__DynamicToolCallOutputContentItem =
+  | { readonly text: string; readonly type: "inputText" }
+  | { readonly imageUrl: string; readonly type: "inputImage" };
+export const V2TurnStartResponse__DynamicToolCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("inputText").annotate({
+        title: "InputTextDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextDynamicToolCallOutputContentItem" }),
+    Schema.Struct({
+      imageUrl: Schema.String,
+      type: Schema.Literal("inputImage").annotate({
+        title: "InputImageDynamicToolCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageDynamicToolCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartResponse__DynamicToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2TurnStartResponse__DynamicToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnStartResponse__HookPromptFragment = {
+  readonly hookRunId: string;
+  readonly text: string;
+};
+export const V2TurnStartResponse__HookPromptFragment = Schema.Struct({
+  hookRunId: Schema.String,
+  text: Schema.String,
+});
+
+export type V2TurnStartResponse__McpToolCallError = { readonly message: string };
+export const V2TurnStartResponse__McpToolCallError = Schema.Struct({ message: Schema.String });
+
+export type V2TurnStartResponse__McpToolCallResult = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly structuredContent?: unknown;
+};
+export const V2TurnStartResponse__McpToolCallResult = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+});
+
+export type V2TurnStartResponse__McpToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2TurnStartResponse__McpToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnStartResponse__MemoryCitationEntry = {
+  readonly lineEnd: number;
+  readonly lineStart: number;
+  readonly note: string;
+  readonly path: string;
+};
+export const V2TurnStartResponse__MemoryCitationEntry = Schema.Struct({
+  lineEnd: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  lineStart: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  note: Schema.String,
+  path: Schema.String,
+});
+
+export type V2TurnStartResponse__MessagePhase = "commentary" | "final_answer";
+export const V2TurnStartResponse__MessagePhase = Schema.Literals([
+  "commentary",
+  "final_answer",
+]).annotate({
+  description:
+    'Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as "phase unknown" and keep compatibility behavior for legacy models.',
+});
+
+export type V2TurnStartResponse__NonSteerableTurnKind = "review" | "compact";
+export const V2TurnStartResponse__NonSteerableTurnKind = Schema.Literals(["review", "compact"]);
+
+export type V2TurnStartResponse__PatchApplyStatus =
+  | "inProgress"
+  | "completed"
+  | "failed"
+  | "declined";
+export const V2TurnStartResponse__PatchApplyStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+  "declined",
+]);
+
+export type V2TurnStartResponse__PatchChangeKind =
+  | { readonly type: "add" }
+  | { readonly type: "delete" }
+  | { readonly move_path?: string | null; readonly type: "update" };
+export const V2TurnStartResponse__PatchChangeKind = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("add").annotate({ title: "AddPatchChangeKindType" }),
+    }).annotate({ title: "AddPatchChangeKind" }),
+    Schema.Struct({
+      type: Schema.Literal("delete").annotate({ title: "DeletePatchChangeKindType" }),
+    }).annotate({ title: "DeletePatchChangeKind" }),
+    Schema.Struct({
+      move_path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("update").annotate({ title: "UpdatePatchChangeKindType" }),
+    }).annotate({ title: "UpdatePatchChangeKind" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartResponse__ReasoningEffort =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+export const V2TurnStartResponse__ReasoningEffort = Schema.Literals([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]).annotate({
+  description:
+    "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
+});
+
+export type V2TurnStartResponse__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2TurnStartResponse__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2TurnStartResponse__TurnStatus = "completed" | "interrupted" | "failed" | "inProgress";
+export const V2TurnStartResponse__TurnStatus = Schema.Literals([
+  "completed",
+  "interrupted",
+  "failed",
+  "inProgress",
+]);
+
+export type V2TurnStartResponse__WebSearchAction =
+  | {
+      readonly queries?: ReadonlyArray<string> | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly type: "openPage"; readonly url?: string | null }
+  | { readonly pattern?: string | null; readonly type: "findInPage"; readonly url?: string | null }
+  | { readonly type: "other" };
+export const V2TurnStartResponse__WebSearchAction = Schema.Union(
+  [
+    Schema.Struct({
+      queries: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchWebSearchActionType" }),
+    }).annotate({ title: "SearchWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("openPage").annotate({ title: "OpenPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "OpenPageWebSearchAction" }),
+    Schema.Struct({
+      pattern: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("findInPage").annotate({ title: "FindInPageWebSearchActionType" }),
+      url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    }).annotate({ title: "FindInPageWebSearchAction" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherWebSearchActionType" }),
+    }).annotate({ title: "OtherWebSearchAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnSteerParams__TextElement = {
+  readonly byteRange: { readonly end: number; readonly start: number };
+  readonly placeholder?: string | null;
+};
+export const V2TurnSteerParams__TextElement = Schema.Struct({
+  byteRange: Schema.Struct({
+    end: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    start: Schema.Number.annotate({ format: "uint" })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({
+    description: "Byte range in the parent `text` buffer that this element occupies.",
+  }),
+  placeholder: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional human-readable placeholder for the element, displayed in the UI.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2WindowsSandboxReadinessResponse__WindowsSandboxReadiness =
+  | "ready"
+  | "notConfigured"
+  | "updateRequired";
+export const V2WindowsSandboxReadinessResponse__WindowsSandboxReadiness = Schema.Literals([
+  "ready",
+  "notConfigured",
+  "updateRequired",
+]);
+
+export type V2WindowsSandboxSetupCompletedNotification__WindowsSandboxSetupMode =
+  | "elevated"
+  | "unelevated";
+export const V2WindowsSandboxSetupCompletedNotification__WindowsSandboxSetupMode = Schema.Literals([
+  "elevated",
+  "unelevated",
+]);
+
+export type V2WindowsSandboxSetupStartParams__AbsolutePathBuf = string;
+export const V2WindowsSandboxSetupStartParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2WindowsSandboxSetupStartParams__WindowsSandboxSetupMode = "elevated" | "unelevated";
+export const V2WindowsSandboxSetupStartParams__WindowsSandboxSetupMode = Schema.Literals([
+  "elevated",
+  "unelevated",
+]);
+
+export type ApplyPatchApprovalResponse__NetworkPolicyAmendment = {
+  readonly action: ApplyPatchApprovalResponse__NetworkPolicyRuleAction;
+  readonly host: string;
+};
+export const ApplyPatchApprovalResponse__NetworkPolicyAmendment = Schema.Struct({
+  action: ApplyPatchApprovalResponse__NetworkPolicyRuleAction,
+  host: Schema.String,
+});
+
+export type ClientRequest__PermissionProfileModificationParams = {
+  readonly path: ClientRequest__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const ClientRequest__PermissionProfileModificationParams = Schema.Union(
+  [
+    Schema.Struct({
+      path: ClientRequest__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootPermissionProfileModificationParamsType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootPermissionProfileModificationParams",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__PluginInstallParams = {
+  readonly marketplacePath?: ClientRequest__AbsolutePathBuf | null;
+  readonly pluginName: string;
+  readonly remoteMarketplaceName?: string | null;
+};
+export const ClientRequest__PluginInstallParams = Schema.Struct({
+  marketplacePath: Schema.optionalKey(Schema.Union([ClientRequest__AbsolutePathBuf, Schema.Null])),
+  pluginName: Schema.String,
+  remoteMarketplaceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ClientRequest__PluginReadParams = {
+  readonly marketplacePath?: ClientRequest__AbsolutePathBuf | null;
+  readonly pluginName: string;
+  readonly remoteMarketplaceName?: string | null;
+};
+export const ClientRequest__PluginReadParams = Schema.Struct({
+  marketplacePath: Schema.optionalKey(Schema.Union([ClientRequest__AbsolutePathBuf, Schema.Null])),
+  pluginName: Schema.String,
+  remoteMarketplaceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ClientRequest__SandboxPolicy =
+  | { readonly type: "dangerFullAccess" }
+  | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+  | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+  | {
+      readonly excludeSlashTmp?: boolean;
+      readonly excludeTmpdirEnvVar?: boolean;
+      readonly networkAccess?: boolean;
+      readonly type: "workspaceWrite";
+      readonly writableRoots?: ReadonlyArray<ClientRequest__AbsolutePathBuf>;
+    };
+export const ClientRequest__SandboxPolicy = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("dangerFullAccess").annotate({
+        title: "DangerFullAccessSandboxPolicyType",
+      }),
+    }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+    }).annotate({ title: "ReadOnlySandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(
+        Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+      ),
+      type: Schema.Literal("externalSandbox").annotate({
+        title: "ExternalSandboxSandboxPolicyType",
+      }),
+    }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+    Schema.Struct({
+      excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("workspaceWrite").annotate({ title: "WorkspaceWriteSandboxPolicyType" }),
+      writableRoots: Schema.optionalKey(
+        Schema.Array(ClientRequest__AbsolutePathBuf).annotate({ default: [] }),
+      ),
+    }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__SkillsConfigWriteParams = {
+  readonly enabled: boolean;
+  readonly name?: string | null;
+  readonly path?: ClientRequest__AbsolutePathBuf | null;
+};
+export const ClientRequest__SkillsConfigWriteParams = Schema.Struct({
+  enabled: Schema.Boolean,
+  name: Schema.optionalKey(
+    Schema.Union([Schema.String.annotate({ description: "Name-based selector." }), Schema.Null]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([ClientRequest__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Path-based selector.",
+    }),
+  ),
+});
+
+export type ClientRequest__SendAddCreditsNudgeEmailParams = {
+  readonly creditType: ClientRequest__AddCreditsNudgeCreditType;
+};
+export const ClientRequest__SendAddCreditsNudgeEmailParams = Schema.Struct({
+  creditType: ClientRequest__AddCreditsNudgeCreditType,
+});
+
+export type ClientRequest__FileSystemPath =
+  | { readonly path: ClientRequest__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | { readonly type: "special"; readonly value: ClientRequest__FileSystemSpecialPath };
+export const ClientRequest__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: ClientRequest__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: ClientRequest__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ContentItem =
+  | { readonly text: string; readonly type: "input_text" }
+  | {
+      readonly detail?: ClientRequest__ImageDetail | null;
+      readonly image_url: string;
+      readonly type: "input_image";
+    }
+  | { readonly text: string; readonly type: "output_text" };
+export const ClientRequest__ContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("input_text").annotate({ title: "InputTextContentItemType" }),
+    }).annotate({ title: "InputTextContentItem" }),
+    Schema.Struct({
+      detail: Schema.optionalKey(Schema.Union([ClientRequest__ImageDetail, Schema.Null])),
+      image_url: Schema.String,
+      type: Schema.Literal("input_image").annotate({ title: "InputImageContentItemType" }),
+    }).annotate({ title: "InputImageContentItem" }),
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("output_text").annotate({ title: "OutputTextContentItemType" }),
+    }).annotate({ title: "OutputTextContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__FunctionCallOutputContentItem =
+  | { readonly text: string; readonly type: "input_text" }
+  | {
+      readonly detail?: ClientRequest__ImageDetail | null;
+      readonly image_url: string;
+      readonly type: "input_image";
+    };
+export const ClientRequest__FunctionCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("input_text").annotate({
+        title: "InputTextFunctionCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextFunctionCallOutputContentItem" }),
+    Schema.Struct({
+      detail: Schema.optionalKey(Schema.Union([ClientRequest__ImageDetail, Schema.Null])),
+      image_url: Schema.String,
+      type: Schema.Literal("input_image").annotate({
+        title: "InputImageFunctionCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageFunctionCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "Responses API compatible content items that can be returned by a tool call. This is a subset of ContentItem with the types we support as function call outputs.",
+});
+
+export type ClientRequest__InitializeParams = {
+  readonly capabilities?: ClientRequest__InitializeCapabilities | null;
+  readonly clientInfo: ClientRequest__ClientInfo;
+};
+export const ClientRequest__InitializeParams = Schema.Struct({
+  capabilities: Schema.optionalKey(
+    Schema.Union([ClientRequest__InitializeCapabilities, Schema.Null]),
+  ),
+  clientInfo: ClientRequest__ClientInfo,
+});
+
+export type ClientRequest__ListMcpServerStatusParams = {
+  readonly cursor?: string | null;
+  readonly detail?: ClientRequest__McpServerStatusDetail | null;
+  readonly limit?: number | null;
+};
+export const ClientRequest__ListMcpServerStatusParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  detail: Schema.optionalKey(
+    Schema.Union([ClientRequest__McpServerStatusDetail, Schema.Null]).annotate({
+      description:
+        "Controls how much MCP inventory data to fetch for each server. Defaults to `Full` when omitted.",
+    }),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a server-defined value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__ConfigEdit = {
+  readonly keyPath: string;
+  readonly mergeStrategy: ClientRequest__MergeStrategy;
+  readonly value: unknown;
+};
+export const ClientRequest__ConfigEdit = Schema.Struct({
+  keyPath: Schema.String,
+  mergeStrategy: ClientRequest__MergeStrategy,
+  value: Schema.Unknown,
+});
+
+export type ClientRequest__ConfigValueWriteParams = {
+  readonly expectedVersion?: string | null;
+  readonly filePath?: string | null;
+  readonly keyPath: string;
+  readonly mergeStrategy: ClientRequest__MergeStrategy;
+  readonly value: unknown;
+};
+export const ClientRequest__ConfigValueWriteParams = Schema.Struct({
+  expectedVersion: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  filePath: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Path to the config file to write; defaults to the user's `config.toml` when omitted.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  keyPath: Schema.String,
+  mergeStrategy: ClientRequest__MergeStrategy,
+  value: Schema.Unknown,
+});
+
+export type ClientRequest__PluginListParams = {
+  readonly cwds?: ReadonlyArray<ClientRequest__AbsolutePathBuf> | null;
+  readonly marketplaceKinds?: ReadonlyArray<ClientRequest__PluginListMarketplaceKind> | null;
+};
+export const ClientRequest__PluginListParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ClientRequest__AbsolutePathBuf).annotate({
+        description:
+          "Optional working directories used to discover repo marketplaces. When omitted, only home-scoped marketplaces and the official curated marketplace are considered.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  marketplaceKinds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ClientRequest__PluginListMarketplaceKind).annotate({
+        description:
+          "Optional marketplace kind filter. When omitted, only local marketplaces are queried, plus the default remote catalog when enabled by feature flag.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__PluginShareTarget = {
+  readonly principalId: string;
+  readonly principalType: ClientRequest__PluginSharePrincipalType;
+};
+export const ClientRequest__PluginShareTarget = Schema.Struct({
+  principalId: Schema.String,
+  principalType: ClientRequest__PluginSharePrincipalType,
+});
+
+export type ClientRequest__Settings = {
+  readonly developer_instructions?: string | null;
+  readonly model: string;
+  readonly reasoning_effort?: ClientRequest__ReasoningEffort | null;
+};
+export const ClientRequest__Settings = Schema.Struct({
+  developer_instructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  model: Schema.String,
+  reasoning_effort: Schema.optionalKey(Schema.Union([ClientRequest__ReasoningEffort, Schema.Null])),
+}).annotate({ description: "Settings for a collaboration mode." });
+
+export type ClientRequest__ReviewStartParams = {
+  readonly delivery?: ClientRequest__ReviewDelivery | null;
+  readonly target: ClientRequest__ReviewTarget;
+  readonly threadId: string;
+};
+export const ClientRequest__ReviewStartParams = Schema.Struct({
+  delivery: Schema.optionalKey(
+    Schema.Union([ClientRequest__ReviewDelivery, Schema.Null]).annotate({
+      description:
+        "Where to run the review: inline (default) on the current thread or detached on a new thread (returned in `reviewThreadId`).",
+    }),
+  ),
+  target: ClientRequest__ReviewTarget,
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadResumeParams = {
+  readonly approvalPolicy?: ClientRequest__AskForApproval | null;
+  readonly approvalsReviewer?: ClientRequest__ApprovalsReviewer | null;
+  readonly baseInstructions?: string | null;
+  readonly config?: { readonly [x: string]: unknown } | null;
+  readonly cwd?: string | null;
+  readonly developerInstructions?: string | null;
+  readonly model?: string | null;
+  readonly modelProvider?: string | null;
+  readonly personality?: ClientRequest__Personality | null;
+  readonly sandbox?: ClientRequest__SandboxMode | null;
+  readonly serviceTier?: string | null;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadResumeParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(Schema.Union([ClientRequest__AskForApproval, Schema.Null])),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([ClientRequest__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this thread and subsequent turns.",
+    }),
+  ),
+  baseInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  config: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.Unknown), Schema.Null]),
+  ),
+  cwd: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developerInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  model: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Configuration overrides for the resumed thread, if any.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  modelProvider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  personality: Schema.optionalKey(Schema.Union([ClientRequest__Personality, Schema.Null])),
+  sandbox: Schema.optionalKey(Schema.Union([ClientRequest__SandboxMode, Schema.Null])),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+}).annotate({
+  description:
+    "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+});
+
+export type ClientRequest__SkillsListParams = {
+  readonly cwds?: ReadonlyArray<string>;
+  readonly forceReload?: boolean;
+  readonly perCwdExtraUserRoots?: ReadonlyArray<ClientRequest__SkillsListExtraRootsForCwd> | null;
+};
+export const ClientRequest__SkillsListParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      description: "When empty, defaults to the current session working directory.",
+    }),
+  ),
+  forceReload: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "When true, bypass the skills cache and re-scan skills from disk.",
+    }),
+  ),
+  perCwdExtraUserRoots: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ClientRequest__SkillsListExtraRootsForCwd).annotate({
+        description: "Optional per-cwd extra roots to scan as user-scoped skills.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ClientRequest__MigrationDetails = {
+  readonly commands?: ReadonlyArray<ClientRequest__CommandMigration>;
+  readonly hooks?: ReadonlyArray<ClientRequest__HookMigration>;
+  readonly mcpServers?: ReadonlyArray<ClientRequest__McpServerMigration>;
+  readonly plugins?: ReadonlyArray<ClientRequest__PluginsMigration>;
+  readonly sessions?: ReadonlyArray<ClientRequest__SessionMigration>;
+  readonly subagents?: ReadonlyArray<ClientRequest__SubagentMigration>;
+};
+export const ClientRequest__MigrationDetails = Schema.Struct({
+  commands: Schema.optionalKey(
+    Schema.Array(ClientRequest__CommandMigration).annotate({ default: [] }),
+  ),
+  hooks: Schema.optionalKey(Schema.Array(ClientRequest__HookMigration).annotate({ default: [] })),
+  mcpServers: Schema.optionalKey(
+    Schema.Array(ClientRequest__McpServerMigration).annotate({ default: [] }),
+  ),
+  plugins: Schema.optionalKey(
+    Schema.Array(ClientRequest__PluginsMigration).annotate({ default: [] }),
+  ),
+  sessions: Schema.optionalKey(
+    Schema.Array(ClientRequest__SessionMigration).annotate({ default: [] }),
+  ),
+  subagents: Schema.optionalKey(
+    Schema.Array(ClientRequest__SubagentMigration).annotate({ default: [] }),
+  ),
+});
+
+export type ClientRequest__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<ClientRequest__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const ClientRequest__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(ClientRequest__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ThreadMetadataUpdateParams = {
+  readonly gitInfo?: ClientRequest__ThreadMetadataGitInfoUpdateParams | null;
+  readonly threadId: string;
+};
+export const ClientRequest__ThreadMetadataUpdateParams = Schema.Struct({
+  gitInfo: Schema.optionalKey(
+    Schema.Union([ClientRequest__ThreadMetadataGitInfoUpdateParams, Schema.Null]).annotate({
+      description:
+        "Patch the stored Git metadata for this thread. Omit a field to leave it unchanged, set it to `null` to clear it, or provide a string to replace the stored value.",
+    }),
+  ),
+  threadId: Schema.String,
+});
+
+export type ClientRequest__ThreadForkParams = {
+  readonly approvalPolicy?: ClientRequest__AskForApproval | null;
+  readonly approvalsReviewer?: ClientRequest__ApprovalsReviewer | null;
+  readonly baseInstructions?: string | null;
+  readonly config?: { readonly [x: string]: unknown } | null;
+  readonly cwd?: string | null;
+  readonly developerInstructions?: string | null;
+  readonly ephemeral?: boolean;
+  readonly model?: string | null;
+  readonly modelProvider?: string | null;
+  readonly sandbox?: ClientRequest__SandboxMode | null;
+  readonly serviceTier?: string | null;
+  readonly threadId: string;
+  readonly threadSource?: ClientRequest__ThreadSource | null;
+};
+export const ClientRequest__ThreadForkParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(Schema.Union([ClientRequest__AskForApproval, Schema.Null])),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([ClientRequest__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this thread and subsequent turns.",
+    }),
+  ),
+  baseInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  config: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.Unknown), Schema.Null]),
+  ),
+  cwd: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developerInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  ephemeral: Schema.optionalKey(Schema.Boolean),
+  model: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Configuration overrides for the forked thread, if any.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  modelProvider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sandbox: Schema.optionalKey(Schema.Union([ClientRequest__SandboxMode, Schema.Null])),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  threadSource: Schema.optionalKey(
+    Schema.Union([ClientRequest__ThreadSource, Schema.Null]).annotate({
+      description:
+        "Optional client-supplied analytics source classification for this forked thread.",
+    }),
+  ),
+}).annotate({
+  description:
+    "There are two ways to fork a thread: 1. By thread_id: load the thread from disk by thread_id and fork it into a new thread. 2. By path: load the thread from disk by path and fork it into a new thread.\n\nIf using path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+});
+
+export type ClientRequest__ThreadListParams = {
+  readonly archived?: boolean | null;
+  readonly cursor?: string | null;
+  readonly cwd?: ClientRequest__ThreadListCwdFilter | null;
+  readonly limit?: number | null;
+  readonly modelProviders?: ReadonlyArray<string> | null;
+  readonly searchTerm?: string | null;
+  readonly sortDirection?: ClientRequest__SortDirection | null;
+  readonly sortKey?: ClientRequest__ThreadSortKey | null;
+  readonly sourceKinds?: ReadonlyArray<ClientRequest__ThreadSourceKind> | null;
+  readonly useStateDbOnly?: boolean;
+};
+export const ClientRequest__ThreadListParams = Schema.Struct({
+  archived: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description:
+          "Optional archived filter; when set to true, only archived threads are returned. If false or null, only non-archived threads are returned.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.optionalKey(
+    Schema.Union([ClientRequest__ThreadListCwdFilter, Schema.Null]).annotate({
+      description:
+        "Optional cwd filter or filters; when set, only threads whose session cwd exactly matches one of these paths are returned.",
+    }),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  modelProviders: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Optional provider filter; when set, only sessions recorded under these providers are returned. When present but empty, includes all providers.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  searchTerm: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional substring filter for the extracted thread title.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sortDirection: Schema.optionalKey(
+    Schema.Union([ClientRequest__SortDirection, Schema.Null]).annotate({
+      description: "Optional sort direction; defaults to descending (newest first).",
+    }),
+  ),
+  sortKey: Schema.optionalKey(
+    Schema.Union([ClientRequest__ThreadSortKey, Schema.Null]).annotate({
+      description: "Optional sort key; defaults to created_at.",
+    }),
+  ),
+  sourceKinds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ClientRequest__ThreadSourceKind).annotate({
+        description:
+          "Optional source filter; when set, only sessions from these source kinds are returned. When omitted or empty, defaults to interactive sources.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  useStateDbOnly: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "If true, return from the state DB without scanning JSONL rollouts to repair thread metadata. Omitted or false preserves scan-and-repair behavior.",
+    }),
+  ),
+});
+
+export type ClientRequest__ThreadStartParams = {
+  readonly approvalPolicy?: ClientRequest__AskForApproval | null;
+  readonly approvalsReviewer?: ClientRequest__ApprovalsReviewer | null;
+  readonly baseInstructions?: string | null;
+  readonly config?: { readonly [x: string]: unknown } | null;
+  readonly cwd?: string | null;
+  readonly developerInstructions?: string | null;
+  readonly ephemeral?: boolean | null;
+  readonly model?: string | null;
+  readonly modelProvider?: string | null;
+  readonly personality?: ClientRequest__Personality | null;
+  readonly sandbox?: ClientRequest__SandboxMode | null;
+  readonly serviceName?: string | null;
+  readonly serviceTier?: string | null;
+  readonly sessionStartSource?: ClientRequest__ThreadStartSource | null;
+  readonly threadSource?: ClientRequest__ThreadSource | null;
+};
+export const ClientRequest__ThreadStartParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(Schema.Union([ClientRequest__AskForApproval, Schema.Null])),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([ClientRequest__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this thread and subsequent turns.",
+    }),
+  ),
+  baseInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  config: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.Unknown), Schema.Null]),
+  ),
+  cwd: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developerInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  ephemeral: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  model: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  modelProvider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  personality: Schema.optionalKey(Schema.Union([ClientRequest__Personality, Schema.Null])),
+  sandbox: Schema.optionalKey(Schema.Union([ClientRequest__SandboxMode, Schema.Null])),
+  serviceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sessionStartSource: Schema.optionalKey(
+    Schema.Union([ClientRequest__ThreadStartSource, Schema.Null]),
+  ),
+  threadSource: Schema.optionalKey(
+    Schema.Union([ClientRequest__ThreadSource, Schema.Null]).annotate({
+      description: "Optional client-supplied analytics source classification for this thread.",
+    }),
+  ),
+});
+
+export type ClientRequest__WindowsSandboxSetupStartParams = {
+  readonly cwd?: ClientRequest__AbsolutePathBuf | null;
+  readonly mode: ClientRequest__WindowsSandboxSetupMode;
+};
+export const ClientRequest__WindowsSandboxSetupStartParams = Schema.Struct({
+  cwd: Schema.optionalKey(Schema.Union([ClientRequest__AbsolutePathBuf, Schema.Null])),
+  mode: ClientRequest__WindowsSandboxSetupMode,
+});
+
+export type CommandExecutionRequestApprovalParams__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: CommandExecutionRequestApprovalParams__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const CommandExecutionRequestApprovalParams__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: CommandExecutionRequestApprovalParams__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type CommandExecutionRequestApprovalParams__FileSystemPath =
+  | { readonly path: CommandExecutionRequestApprovalParams__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | {
+      readonly type: "special";
+      readonly value: CommandExecutionRequestApprovalParams__FileSystemSpecialPath;
+    };
+export const CommandExecutionRequestApprovalParams__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: CommandExecutionRequestApprovalParams__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: CommandExecutionRequestApprovalParams__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type CommandExecutionRequestApprovalParams__NetworkApprovalContext = {
+  readonly host: string;
+  readonly protocol: CommandExecutionRequestApprovalParams__NetworkApprovalProtocol;
+};
+export const CommandExecutionRequestApprovalParams__NetworkApprovalContext = Schema.Struct({
+  host: Schema.String,
+  protocol: CommandExecutionRequestApprovalParams__NetworkApprovalProtocol,
+});
+
+export type CommandExecutionRequestApprovalParams__NetworkPolicyAmendment = {
+  readonly action: CommandExecutionRequestApprovalParams__NetworkPolicyRuleAction;
+  readonly host: string;
+};
+export const CommandExecutionRequestApprovalParams__NetworkPolicyAmendment = Schema.Struct({
+  action: CommandExecutionRequestApprovalParams__NetworkPolicyRuleAction,
+  host: Schema.String,
+});
+
+export type CommandExecutionRequestApprovalResponse__NetworkPolicyAmendment = {
+  readonly action: CommandExecutionRequestApprovalResponse__NetworkPolicyRuleAction;
+  readonly host: string;
+};
+export const CommandExecutionRequestApprovalResponse__NetworkPolicyAmendment = Schema.Struct({
+  action: CommandExecutionRequestApprovalResponse__NetworkPolicyRuleAction,
+  host: Schema.String,
+});
+
+export type ExecCommandApprovalResponse__NetworkPolicyAmendment = {
+  readonly action: ExecCommandApprovalResponse__NetworkPolicyRuleAction;
+  readonly host: string;
+};
+export const ExecCommandApprovalResponse__NetworkPolicyAmendment = Schema.Struct({
+  action: ExecCommandApprovalResponse__NetworkPolicyRuleAction,
+  host: Schema.String,
+});
+
+export type FuzzyFileSearchResponse__FuzzyFileSearchResult = {
+  readonly file_name: string;
+  readonly indices?: ReadonlyArray<number> | null;
+  readonly match_type: FuzzyFileSearchResponse__FuzzyFileSearchMatchType;
+  readonly path: string;
+  readonly root: string;
+  readonly score: number;
+};
+export const FuzzyFileSearchResponse__FuzzyFileSearchResult = Schema.Struct({
+  file_name: Schema.String,
+  indices: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(
+        Schema.Number.annotate({ format: "uint32" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  match_type: FuzzyFileSearchResponse__FuzzyFileSearchMatchType,
+  path: Schema.String,
+  root: Schema.String,
+  score: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({ description: "Superset of [`codex_file_search::FileMatch`]" });
+
+export type FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchResult = {
+  readonly file_name: string;
+  readonly indices?: ReadonlyArray<number> | null;
+  readonly match_type: FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchMatchType;
+  readonly path: string;
+  readonly root: string;
+  readonly score: number;
+};
+export const FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchResult = Schema.Struct({
+  file_name: Schema.String,
+  indices: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(
+        Schema.Number.annotate({ format: "uint32" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  match_type: FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchMatchType,
+  path: Schema.String,
+  root: Schema.String,
+  score: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({ description: "Superset of [`codex_file_search::FileMatch`]" });
+
+export type JSONRPCMessage__JSONRPCError = {
+  readonly error: JSONRPCMessage__JSONRPCErrorError;
+  readonly id: JSONRPCMessage__RequestId;
+};
+export const JSONRPCMessage__JSONRPCError = Schema.Struct({
+  error: JSONRPCMessage__JSONRPCErrorError,
+  id: JSONRPCMessage__RequestId,
+}).annotate({ description: "A response to a request that indicates an error occurred." });
+
+export type JSONRPCMessage__JSONRPCResponse = {
+  readonly id: JSONRPCMessage__RequestId;
+  readonly result: unknown;
+};
+export const JSONRPCMessage__JSONRPCResponse = Schema.Struct({
+  id: JSONRPCMessage__RequestId,
+  result: Schema.Unknown,
+}).annotate({ description: "A successful (non-error) response to a request." });
+
+export type JSONRPCMessage__JSONRPCRequest = {
+  readonly id: JSONRPCMessage__RequestId;
+  readonly method: string;
+  readonly params?: unknown;
+  readonly trace?: JSONRPCMessage__W3cTraceContext | null;
+};
+export const JSONRPCMessage__JSONRPCRequest = Schema.Struct({
+  id: JSONRPCMessage__RequestId,
+  method: Schema.String,
+  params: Schema.optionalKey(Schema.Unknown),
+  trace: Schema.optionalKey(
+    Schema.Union([JSONRPCMessage__W3cTraceContext, Schema.Null]).annotate({
+      description: "Optional W3C Trace Context for distributed tracing.",
+    }),
+  ),
+}).annotate({ description: "A request that expects a response." });
+
+export type McpServerElicitationRequestParams__McpElicitationBooleanSchema = {
+  readonly default?: boolean | null;
+  readonly description?: string | null;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationBooleanType;
+};
+export const McpServerElicitationRequestParams__McpElicitationBooleanSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: McpServerElicitationRequestParams__McpElicitationBooleanType,
+});
+
+export type McpServerElicitationRequestParams__McpElicitationTitledEnumItems = {
+  readonly anyOf: ReadonlyArray<McpServerElicitationRequestParams__McpElicitationConstOption>;
+};
+export const McpServerElicitationRequestParams__McpElicitationTitledEnumItems = Schema.Struct({
+  anyOf: Schema.Array(McpServerElicitationRequestParams__McpElicitationConstOption),
+});
+
+export type McpServerElicitationRequestParams__McpElicitationNumberSchema = {
+  readonly default?: number | null;
+  readonly description?: string | null;
+  readonly maximum?: number | null;
+  readonly minimum?: number | null;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationNumberType;
+};
+export const McpServerElicitationRequestParams__McpElicitationNumberSchema = Schema.Struct({
+  default: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "double" }).check(Schema.isFinite()),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  maximum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "double" }).check(Schema.isFinite()),
+      Schema.Null,
+    ]),
+  ),
+  minimum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "double" }).check(Schema.isFinite()),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: McpServerElicitationRequestParams__McpElicitationNumberType,
+});
+
+export type McpServerElicitationRequestParams__McpElicitationLegacyTitledEnumSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly enum: ReadonlyArray<string>;
+  readonly enumNames?: ReadonlyArray<string> | null;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationStringType;
+};
+export const McpServerElicitationRequestParams__McpElicitationLegacyTitledEnumSchema =
+  Schema.Struct({
+    default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    enum: Schema.Array(Schema.String),
+    enumNames: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+    title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    type: McpServerElicitationRequestParams__McpElicitationStringType,
+  });
+
+export type McpServerElicitationRequestParams__McpElicitationStringSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly format?: McpServerElicitationRequestParams__McpElicitationStringFormat | null;
+  readonly maxLength?: number | null;
+  readonly minLength?: number | null;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationStringType;
+};
+export const McpServerElicitationRequestParams__McpElicitationStringSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  format: Schema.optionalKey(
+    Schema.Union([McpServerElicitationRequestParams__McpElicitationStringFormat, Schema.Null]),
+  ),
+  maxLength: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  minLength: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: McpServerElicitationRequestParams__McpElicitationStringType,
+});
+
+export type McpServerElicitationRequestParams__McpElicitationTitledSingleSelectEnumSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly oneOf: ReadonlyArray<McpServerElicitationRequestParams__McpElicitationConstOption>;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationStringType;
+};
+export const McpServerElicitationRequestParams__McpElicitationTitledSingleSelectEnumSchema =
+  Schema.Struct({
+    default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    oneOf: Schema.Array(McpServerElicitationRequestParams__McpElicitationConstOption),
+    title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    type: McpServerElicitationRequestParams__McpElicitationStringType,
+  });
+
+export type McpServerElicitationRequestParams__McpElicitationUntitledEnumItems = {
+  readonly enum: ReadonlyArray<string>;
+  readonly type: McpServerElicitationRequestParams__McpElicitationStringType;
+};
+export const McpServerElicitationRequestParams__McpElicitationUntitledEnumItems = Schema.Struct({
+  enum: Schema.Array(Schema.String),
+  type: McpServerElicitationRequestParams__McpElicitationStringType,
+});
+
+export type McpServerElicitationRequestParams__McpElicitationUntitledSingleSelectEnumSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly enum: ReadonlyArray<string>;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationStringType;
+};
+export const McpServerElicitationRequestParams__McpElicitationUntitledSingleSelectEnumSchema =
+  Schema.Struct({
+    default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    enum: Schema.Array(Schema.String),
+    title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    type: McpServerElicitationRequestParams__McpElicitationStringType,
+  });
+
+export type PermissionsRequestApprovalParams__FileSystemPath =
+  | { readonly path: PermissionsRequestApprovalParams__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | {
+      readonly type: "special";
+      readonly value: PermissionsRequestApprovalParams__FileSystemSpecialPath;
+    };
+export const PermissionsRequestApprovalParams__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: PermissionsRequestApprovalParams__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: PermissionsRequestApprovalParams__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type PermissionsRequestApprovalResponse__FileSystemPath =
+  | { readonly path: PermissionsRequestApprovalResponse__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | {
+      readonly type: "special";
+      readonly value: PermissionsRequestApprovalResponse__FileSystemSpecialPath;
+    };
+export const PermissionsRequestApprovalResponse__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: PermissionsRequestApprovalResponse__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: PermissionsRequestApprovalResponse__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: ServerNotification__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const ServerNotification__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: ServerNotification__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__FsChangedNotification = {
+  readonly changedPaths: ReadonlyArray<ServerNotification__AbsolutePathBuf>;
+  readonly watchId: string;
+};
+export const ServerNotification__FsChangedNotification = Schema.Struct({
+  changedPaths: Schema.Array(ServerNotification__AbsolutePathBuf).annotate({
+    description: "File or directory paths associated with this event.",
+  }),
+  watchId: Schema.String.annotate({
+    description: "Watch identifier previously provided to `fs/watch`.",
+  }),
+}).annotate({ description: "Filesystem watch notification emitted for `fs/watch` subscribers." });
+
+export type ServerNotification__AppMetadata = {
+  readonly categories?: ReadonlyArray<string> | null;
+  readonly developer?: string | null;
+  readonly firstPartyRequiresInstall?: boolean | null;
+  readonly firstPartyType?: string | null;
+  readonly review?: ServerNotification__AppReview | null;
+  readonly screenshots?: ReadonlyArray<ServerNotification__AppScreenshot> | null;
+  readonly seoDescription?: string | null;
+  readonly showInComposerWhenUnlinked?: boolean | null;
+  readonly subCategories?: ReadonlyArray<string> | null;
+  readonly version?: string | null;
+  readonly versionId?: string | null;
+  readonly versionNotes?: string | null;
+};
+export const ServerNotification__AppMetadata = Schema.Struct({
+  categories: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  developer: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  firstPartyRequiresInstall: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  firstPartyType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  review: Schema.optionalKey(Schema.Union([ServerNotification__AppReview, Schema.Null])),
+  screenshots: Schema.optionalKey(
+    Schema.Union([Schema.Array(ServerNotification__AppScreenshot), Schema.Null]),
+  ),
+  seoDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  showInComposerWhenUnlinked: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  subCategories: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  version: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  versionId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  versionNotes: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerNotification__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: ServerNotification__CollabAgentStatus;
+};
+export const ServerNotification__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: ServerNotification__CollabAgentStatus,
+});
+
+export type ServerNotification__FileSystemPath =
+  | { readonly path: ServerNotification__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | { readonly type: "special"; readonly value: ServerNotification__FileSystemSpecialPath };
+export const ServerNotification__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: ServerNotification__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: ServerNotification__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__FuzzyFileSearchResult = {
+  readonly file_name: string;
+  readonly indices?: ReadonlyArray<number> | null;
+  readonly match_type: ServerNotification__FuzzyFileSearchMatchType;
+  readonly path: string;
+  readonly root: string;
+  readonly score: number;
+};
+export const ServerNotification__FuzzyFileSearchResult = Schema.Struct({
+  file_name: Schema.String,
+  indices: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(
+        Schema.Number.annotate({ format: "uint32" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+      ),
+      Schema.Null,
+    ]),
+  ),
+  match_type: ServerNotification__FuzzyFileSearchMatchType,
+  path: Schema.String,
+  root: Schema.String,
+  score: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({ description: "Superset of [`codex_file_search::FileMatch`]" });
+
+export type ServerNotification__GuardianApprovalReview = {
+  readonly rationale?: string | null;
+  readonly riskLevel?: ServerNotification__GuardianRiskLevel | null;
+  readonly status: ServerNotification__GuardianApprovalReviewStatus;
+  readonly userAuthorization?: ServerNotification__GuardianUserAuthorization | null;
+};
+export const ServerNotification__GuardianApprovalReview = Schema.Struct({
+  rationale: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  riskLevel: Schema.optionalKey(Schema.Union([ServerNotification__GuardianRiskLevel, Schema.Null])),
+  status: ServerNotification__GuardianApprovalReviewStatus,
+  userAuthorization: Schema.optionalKey(
+    Schema.Union([ServerNotification__GuardianUserAuthorization, Schema.Null]),
+  ),
+}).annotate({
+  description:
+    "[UNSTABLE] Temporary approval auto-review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+});
+
+export type ServerNotification__HookOutputEntry = {
+  readonly kind: ServerNotification__HookOutputEntryKind;
+  readonly text: string;
+};
+export const ServerNotification__HookOutputEntry = Schema.Struct({
+  kind: ServerNotification__HookOutputEntryKind,
+  text: Schema.String,
+});
+
+export type ServerNotification__McpServerStatusUpdatedNotification = {
+  readonly error?: string | null;
+  readonly name: string;
+  readonly status: ServerNotification__McpServerStartupState;
+};
+export const ServerNotification__McpServerStatusUpdatedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  status: ServerNotification__McpServerStartupState,
+});
+
+export type ServerNotification__MemoryCitation = {
+  readonly entries: ReadonlyArray<ServerNotification__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const ServerNotification__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(ServerNotification__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type ServerNotification__ModelReroutedNotification = {
+  readonly fromModel: string;
+  readonly reason: ServerNotification__ModelRerouteReason;
+  readonly threadId: string;
+  readonly toModel: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ModelReroutedNotification = Schema.Struct({
+  fromModel: Schema.String,
+  reason: ServerNotification__ModelRerouteReason,
+  threadId: Schema.String,
+  toModel: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__ModelVerificationNotification = {
+  readonly threadId: string;
+  readonly turnId: string;
+  readonly verifications: ReadonlyArray<ServerNotification__ModelVerification>;
+};
+export const ServerNotification__ModelVerificationNotification = Schema.Struct({
+  threadId: Schema.String,
+  turnId: Schema.String,
+  verifications: Schema.Array(ServerNotification__ModelVerification),
+});
+
+export type ServerNotification__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: ServerNotification__NonSteerableTurnKind;
+      };
+    };
+export const ServerNotification__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({ turnKind: ServerNotification__NonSteerableTurnKind }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type ServerNotification__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: ServerNotification__PatchChangeKind;
+  readonly path: string;
+};
+export const ServerNotification__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: ServerNotification__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type ServerNotification__AccountUpdatedNotification = {
+  readonly authMode?: ServerNotification__AuthMode | null;
+  readonly planType?: ServerNotification__PlanType | null;
+};
+export const ServerNotification__AccountUpdatedNotification = Schema.Struct({
+  authMode: Schema.optionalKey(Schema.Union([ServerNotification__AuthMode, Schema.Null])),
+  planType: Schema.optionalKey(Schema.Union([ServerNotification__PlanType, Schema.Null])),
+});
+
+export type ServerNotification__RateLimitSnapshot = {
+  readonly credits?: ServerNotification__CreditsSnapshot | null;
+  readonly limitId?: string | null;
+  readonly limitName?: string | null;
+  readonly planType?: ServerNotification__PlanType | null;
+  readonly primary?: ServerNotification__RateLimitWindow | null;
+  readonly rateLimitReachedType?: ServerNotification__RateLimitReachedType | null;
+  readonly secondary?: ServerNotification__RateLimitWindow | null;
+};
+export const ServerNotification__RateLimitSnapshot = Schema.Struct({
+  credits: Schema.optionalKey(Schema.Union([ServerNotification__CreditsSnapshot, Schema.Null])),
+  limitId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  limitName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  planType: Schema.optionalKey(Schema.Union([ServerNotification__PlanType, Schema.Null])),
+  primary: Schema.optionalKey(Schema.Union([ServerNotification__RateLimitWindow, Schema.Null])),
+  rateLimitReachedType: Schema.optionalKey(
+    Schema.Union([ServerNotification__RateLimitReachedType, Schema.Null]),
+  ),
+  secondary: Schema.optionalKey(Schema.Union([ServerNotification__RateLimitWindow, Schema.Null])),
+});
+
+export type ServerNotification__ThreadRealtimeStartedNotification = {
+  readonly realtimeSessionId?: string | null;
+  readonly threadId: string;
+  readonly version: ServerNotification__RealtimeConversationVersion;
+};
+export const ServerNotification__ThreadRealtimeStartedNotification = Schema.Struct({
+  realtimeSessionId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  version: ServerNotification__RealtimeConversationVersion,
+}).annotate({ description: "EXPERIMENTAL - emitted when thread realtime startup is accepted." });
+
+export type ServerNotification__RemoteControlStatusChangedNotification = {
+  readonly environmentId?: string | null;
+  readonly status: ServerNotification__RemoteControlConnectionStatus;
+};
+export const ServerNotification__RemoteControlStatusChangedNotification = Schema.Struct({
+  environmentId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: ServerNotification__RemoteControlConnectionStatus,
+}).annotate({
+  description: "Current remote-control connection status and environment id exposed to clients.",
+});
+
+export type ServerNotification__ServerRequestResolvedNotification = {
+  readonly requestId: ServerNotification__RequestId;
+  readonly threadId: string;
+};
+export const ServerNotification__ServerRequestResolvedNotification = Schema.Struct({
+  requestId: ServerNotification__RequestId,
+  threadId: Schema.String,
+});
+
+export type ServerNotification__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<ServerNotification__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const ServerNotification__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(ServerNotification__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__TextRange = {
+  readonly end: ServerNotification__TextPosition;
+  readonly start: ServerNotification__TextPosition;
+};
+export const ServerNotification__TextRange = Schema.Struct({
+  end: ServerNotification__TextPosition,
+  start: ServerNotification__TextPosition,
+});
+
+export type ServerNotification__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<ServerNotification__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const ServerNotification__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(ServerNotification__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__ThreadGoal = {
+  readonly createdAt: number;
+  readonly objective: string;
+  readonly status: ServerNotification__ThreadGoalStatus;
+  readonly threadId: string;
+  readonly timeUsedSeconds: number;
+  readonly tokenBudget?: number | null;
+  readonly tokensUsed: number;
+  readonly updatedAt: number;
+};
+export const ServerNotification__ThreadGoal = Schema.Struct({
+  createdAt: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  objective: Schema.String,
+  status: ServerNotification__ThreadGoalStatus,
+  threadId: Schema.String,
+  timeUsedSeconds: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  tokenBudget: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  tokensUsed: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  updatedAt: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+});
+
+export type ServerNotification__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: ServerNotification__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: ServerNotification__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const ServerNotification__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(Schema.Union([ServerNotification__AgentPath, Schema.Null])),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: ServerNotification__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__ThreadRealtimeOutputAudioDeltaNotification = {
+  readonly audio: ServerNotification__ThreadRealtimeAudioChunk;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadRealtimeOutputAudioDeltaNotification = Schema.Struct({
+  audio: ServerNotification__ThreadRealtimeAudioChunk,
+  threadId: Schema.String,
+}).annotate({ description: "EXPERIMENTAL - streamed output audio emitted by thread realtime." });
+
+export type ServerNotification__ThreadTokenUsage = {
+  readonly last: ServerNotification__TokenUsageBreakdown;
+  readonly modelContextWindow?: number | null;
+  readonly total: ServerNotification__TokenUsageBreakdown;
+};
+export const ServerNotification__ThreadTokenUsage = Schema.Struct({
+  last: ServerNotification__TokenUsageBreakdown,
+  modelContextWindow: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  total: ServerNotification__TokenUsageBreakdown,
+});
+
+export type ServerNotification__TurnPlanStep = {
+  readonly status: ServerNotification__TurnPlanStepStatus;
+  readonly step: string;
+};
+export const ServerNotification__TurnPlanStep = Schema.Struct({
+  status: ServerNotification__TurnPlanStepStatus,
+  step: Schema.String,
+});
+
+export type ServerNotification__WindowsSandboxSetupCompletedNotification = {
+  readonly error?: string | null;
+  readonly mode: ServerNotification__WindowsSandboxSetupMode;
+  readonly success: boolean;
+};
+export const ServerNotification__WindowsSandboxSetupCompletedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  mode: ServerNotification__WindowsSandboxSetupMode,
+  success: Schema.Boolean,
+});
+
+export type ServerRequest__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: ServerRequest__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const ServerRequest__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: ServerRequest__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerRequest__ChatgptAuthTokensRefreshParams = {
+  readonly previousAccountId?: string | null;
+  readonly reason: ServerRequest__ChatgptAuthTokensRefreshReason;
+};
+export const ServerRequest__ChatgptAuthTokensRefreshParams = Schema.Struct({
+  previousAccountId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Workspace/account identifier that Codex was previously using.\n\nClients that manage multiple accounts/workspaces can use this as a hint to refresh the token for the correct workspace.\n\nThis may be `null` when the prior auth state did not include a workspace identifier (`chatgpt_account_id`).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reason: ServerRequest__ChatgptAuthTokensRefreshReason,
+});
+
+export type ServerRequest__FileSystemPath =
+  | { readonly path: ServerRequest__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | { readonly type: "special"; readonly value: ServerRequest__FileSystemSpecialPath };
+export const ServerRequest__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: ServerRequest__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: ServerRequest__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerRequest__McpElicitationBooleanSchema = {
+  readonly default?: boolean | null;
+  readonly description?: string | null;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationBooleanType;
+};
+export const ServerRequest__McpElicitationBooleanSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationBooleanType,
+});
+
+export type ServerRequest__McpElicitationTitledEnumItems = {
+  readonly anyOf: ReadonlyArray<ServerRequest__McpElicitationConstOption>;
+};
+export const ServerRequest__McpElicitationTitledEnumItems = Schema.Struct({
+  anyOf: Schema.Array(ServerRequest__McpElicitationConstOption),
+});
+
+export type ServerRequest__McpElicitationNumberSchema = {
+  readonly default?: number | null;
+  readonly description?: string | null;
+  readonly maximum?: number | null;
+  readonly minimum?: number | null;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationNumberType;
+};
+export const ServerRequest__McpElicitationNumberSchema = Schema.Struct({
+  default: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "double" }).check(Schema.isFinite()),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  maximum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "double" }).check(Schema.isFinite()),
+      Schema.Null,
+    ]),
+  ),
+  minimum: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "double" }).check(Schema.isFinite()),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationNumberType,
+});
+
+export type ServerRequest__McpElicitationLegacyTitledEnumSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly enum: ReadonlyArray<string>;
+  readonly enumNames?: ReadonlyArray<string> | null;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationStringType;
+};
+export const ServerRequest__McpElicitationLegacyTitledEnumSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  enum: Schema.Array(Schema.String),
+  enumNames: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationStringType,
+});
+
+export type ServerRequest__McpElicitationStringSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly format?: ServerRequest__McpElicitationStringFormat | null;
+  readonly maxLength?: number | null;
+  readonly minLength?: number | null;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationStringType;
+};
+export const ServerRequest__McpElicitationStringSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  format: Schema.optionalKey(
+    Schema.Union([ServerRequest__McpElicitationStringFormat, Schema.Null]),
+  ),
+  maxLength: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  minLength: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationStringType,
+});
+
+export type ServerRequest__McpElicitationTitledSingleSelectEnumSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly oneOf: ReadonlyArray<ServerRequest__McpElicitationConstOption>;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationStringType;
+};
+export const ServerRequest__McpElicitationTitledSingleSelectEnumSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  oneOf: Schema.Array(ServerRequest__McpElicitationConstOption),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationStringType,
+});
+
+export type ServerRequest__McpElicitationUntitledEnumItems = {
+  readonly enum: ReadonlyArray<string>;
+  readonly type: ServerRequest__McpElicitationStringType;
+};
+export const ServerRequest__McpElicitationUntitledEnumItems = Schema.Struct({
+  enum: Schema.Array(Schema.String),
+  type: ServerRequest__McpElicitationStringType,
+});
+
+export type ServerRequest__McpElicitationUntitledSingleSelectEnumSchema = {
+  readonly default?: string | null;
+  readonly description?: string | null;
+  readonly enum: ReadonlyArray<string>;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationStringType;
+};
+export const ServerRequest__McpElicitationUntitledSingleSelectEnumSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  enum: Schema.Array(Schema.String),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationStringType,
+});
+
+export type ServerRequest__NetworkApprovalContext = {
+  readonly host: string;
+  readonly protocol: ServerRequest__NetworkApprovalProtocol;
+};
+export const ServerRequest__NetworkApprovalContext = Schema.Struct({
+  host: Schema.String,
+  protocol: ServerRequest__NetworkApprovalProtocol,
+});
+
+export type ServerRequest__NetworkPolicyAmendment = {
+  readonly action: ServerRequest__NetworkPolicyRuleAction;
+  readonly host: string;
+};
+export const ServerRequest__NetworkPolicyAmendment = Schema.Struct({
+  action: ServerRequest__NetworkPolicyRuleAction,
+  host: Schema.String,
+});
+
+export type ServerRequest__ApplyPatchApprovalParams = {
+  readonly callId: string;
+  readonly conversationId: ServerRequest__ThreadId;
+  readonly fileChanges: { readonly [x: string]: ServerRequest__FileChange };
+  readonly grantRoot?: string | null;
+  readonly reason?: string | null;
+};
+export const ServerRequest__ApplyPatchApprovalParams = Schema.Struct({
+  callId: Schema.String.annotate({
+    description:
+      "Use to correlate this with [codex_protocol::protocol::PatchApplyBeginEvent] and [codex_protocol::protocol::PatchApplyEndEvent].",
+  }),
+  conversationId: ServerRequest__ThreadId,
+  fileChanges: Schema.Record(Schema.String, ServerRequest__FileChange),
+  grantRoot: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reason: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional explanatory reason (e.g. request for extra write access).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ServerRequest__ExecCommandApprovalParams = {
+  readonly approvalId?: string | null;
+  readonly callId: string;
+  readonly command: ReadonlyArray<string>;
+  readonly conversationId: ServerRequest__ThreadId;
+  readonly cwd: string;
+  readonly parsedCmd: ReadonlyArray<ServerRequest__ParsedCommand>;
+  readonly reason?: string | null;
+};
+export const ServerRequest__ExecCommandApprovalParams = Schema.Struct({
+  approvalId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Identifier for this specific approval callback." }),
+      Schema.Null,
+    ]),
+  ),
+  callId: Schema.String.annotate({
+    description:
+      "Use to correlate this with [codex_protocol::protocol::ExecCommandBeginEvent] and [codex_protocol::protocol::ExecCommandEndEvent].",
+  }),
+  command: Schema.Array(Schema.String),
+  conversationId: ServerRequest__ThreadId,
+  cwd: Schema.String,
+  parsedCmd: Schema.Array(ServerRequest__ParsedCommand),
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerRequest__ToolRequestUserInputQuestion = {
+  readonly header: string;
+  readonly id: string;
+  readonly isOther?: boolean;
+  readonly isSecret?: boolean;
+  readonly options?: ReadonlyArray<ServerRequest__ToolRequestUserInputOption> | null;
+  readonly question: string;
+};
+export const ServerRequest__ToolRequestUserInputQuestion = Schema.Struct({
+  header: Schema.String,
+  id: Schema.String,
+  isOther: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  isSecret: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  options: Schema.optionalKey(
+    Schema.Union([Schema.Array(ServerRequest__ToolRequestUserInputOption), Schema.Null]),
+  ),
+  question: Schema.String,
+}).annotate({
+  description: "EXPERIMENTAL. Represents one request_user_input question and its required options.",
+});
+
+export type ToolRequestUserInputParams__ToolRequestUserInputQuestion = {
+  readonly header: string;
+  readonly id: string;
+  readonly isOther?: boolean;
+  readonly isSecret?: boolean;
+  readonly options?: ReadonlyArray<ToolRequestUserInputParams__ToolRequestUserInputOption> | null;
+  readonly question: string;
+};
+export const ToolRequestUserInputParams__ToolRequestUserInputQuestion = Schema.Struct({
+  header: Schema.String,
+  id: Schema.String,
+  isOther: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  isSecret: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  options: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ToolRequestUserInputParams__ToolRequestUserInputOption),
+      Schema.Null,
+    ]),
+  ),
+  question: Schema.String,
+}).annotate({
+  description: "EXPERIMENTAL. Represents one request_user_input question and its required options.",
+});
+
+export type V2AccountRateLimitsUpdatedNotification__RateLimitSnapshot = {
+  readonly credits?: V2AccountRateLimitsUpdatedNotification__CreditsSnapshot | null;
+  readonly limitId?: string | null;
+  readonly limitName?: string | null;
+  readonly planType?: V2AccountRateLimitsUpdatedNotification__PlanType | null;
+  readonly primary?: V2AccountRateLimitsUpdatedNotification__RateLimitWindow | null;
+  readonly rateLimitReachedType?: V2AccountRateLimitsUpdatedNotification__RateLimitReachedType | null;
+  readonly secondary?: V2AccountRateLimitsUpdatedNotification__RateLimitWindow | null;
+};
+export const V2AccountRateLimitsUpdatedNotification__RateLimitSnapshot = Schema.Struct({
+  credits: Schema.optionalKey(
+    Schema.Union([V2AccountRateLimitsUpdatedNotification__CreditsSnapshot, Schema.Null]),
+  ),
+  limitId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  limitName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  planType: Schema.optionalKey(
+    Schema.Union([V2AccountRateLimitsUpdatedNotification__PlanType, Schema.Null]),
+  ),
+  primary: Schema.optionalKey(
+    Schema.Union([V2AccountRateLimitsUpdatedNotification__RateLimitWindow, Schema.Null]),
+  ),
+  rateLimitReachedType: Schema.optionalKey(
+    Schema.Union([V2AccountRateLimitsUpdatedNotification__RateLimitReachedType, Schema.Null]),
+  ),
+  secondary: Schema.optionalKey(
+    Schema.Union([V2AccountRateLimitsUpdatedNotification__RateLimitWindow, Schema.Null]),
+  ),
+});
+
+export type V2AppListUpdatedNotification__AppMetadata = {
+  readonly categories?: ReadonlyArray<string> | null;
+  readonly developer?: string | null;
+  readonly firstPartyRequiresInstall?: boolean | null;
+  readonly firstPartyType?: string | null;
+  readonly review?: V2AppListUpdatedNotification__AppReview | null;
+  readonly screenshots?: ReadonlyArray<V2AppListUpdatedNotification__AppScreenshot> | null;
+  readonly seoDescription?: string | null;
+  readonly showInComposerWhenUnlinked?: boolean | null;
+  readonly subCategories?: ReadonlyArray<string> | null;
+  readonly version?: string | null;
+  readonly versionId?: string | null;
+  readonly versionNotes?: string | null;
+};
+export const V2AppListUpdatedNotification__AppMetadata = Schema.Struct({
+  categories: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  developer: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  firstPartyRequiresInstall: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  firstPartyType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  review: Schema.optionalKey(Schema.Union([V2AppListUpdatedNotification__AppReview, Schema.Null])),
+  screenshots: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2AppListUpdatedNotification__AppScreenshot), Schema.Null]),
+  ),
+  seoDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  showInComposerWhenUnlinked: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  subCategories: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  version: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  versionId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  versionNotes: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2AppsListResponse__AppMetadata = {
+  readonly categories?: ReadonlyArray<string> | null;
+  readonly developer?: string | null;
+  readonly firstPartyRequiresInstall?: boolean | null;
+  readonly firstPartyType?: string | null;
+  readonly review?: V2AppsListResponse__AppReview | null;
+  readonly screenshots?: ReadonlyArray<V2AppsListResponse__AppScreenshot> | null;
+  readonly seoDescription?: string | null;
+  readonly showInComposerWhenUnlinked?: boolean | null;
+  readonly subCategories?: ReadonlyArray<string> | null;
+  readonly version?: string | null;
+  readonly versionId?: string | null;
+  readonly versionNotes?: string | null;
+};
+export const V2AppsListResponse__AppMetadata = Schema.Struct({
+  categories: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  developer: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  firstPartyRequiresInstall: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  firstPartyType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  review: Schema.optionalKey(Schema.Union([V2AppsListResponse__AppReview, Schema.Null])),
+  screenshots: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2AppsListResponse__AppScreenshot), Schema.Null]),
+  ),
+  seoDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  showInComposerWhenUnlinked: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  subCategories: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  version: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  versionId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  versionNotes: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2CommandExecParams__SandboxPolicy =
+  | { readonly type: "dangerFullAccess" }
+  | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+  | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+  | {
+      readonly excludeSlashTmp?: boolean;
+      readonly excludeTmpdirEnvVar?: boolean;
+      readonly networkAccess?: boolean;
+      readonly type: "workspaceWrite";
+      readonly writableRoots?: ReadonlyArray<V2CommandExecParams__AbsolutePathBuf>;
+    };
+export const V2CommandExecParams__SandboxPolicy = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("dangerFullAccess").annotate({
+        title: "DangerFullAccessSandboxPolicyType",
+      }),
+    }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+    }).annotate({ title: "ReadOnlySandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(
+        Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+      ),
+      type: Schema.Literal("externalSandbox").annotate({
+        title: "ExternalSandboxSandboxPolicyType",
+      }),
+    }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+    Schema.Struct({
+      excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("workspaceWrite").annotate({ title: "WorkspaceWriteSandboxPolicyType" }),
+      writableRoots: Schema.optionalKey(
+        Schema.Array(V2CommandExecParams__AbsolutePathBuf).annotate({ default: [] }),
+      ),
+    }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2CommandExecParams__FileSystemPath =
+  | { readonly path: V2CommandExecParams__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | { readonly type: "special"; readonly value: V2CommandExecParams__FileSystemSpecialPath };
+export const V2CommandExecParams__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2CommandExecParams__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: V2CommandExecParams__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ConfigBatchWriteParams__ConfigEdit = {
+  readonly keyPath: string;
+  readonly mergeStrategy: V2ConfigBatchWriteParams__MergeStrategy;
+  readonly value: unknown;
+};
+export const V2ConfigBatchWriteParams__ConfigEdit = Schema.Struct({
+  keyPath: Schema.String,
+  mergeStrategy: V2ConfigBatchWriteParams__MergeStrategy,
+  value: Schema.Unknown,
+});
+
+export type V2ConfigReadResponse__ConfigLayerSource =
+  | { readonly domain: string; readonly key: string; readonly type: "mdm" }
+  | { readonly file: string; readonly type: "system" }
+  | { readonly file: string; readonly type: "user" }
+  | { readonly dotCodexFolder: V2ConfigReadResponse__AbsolutePathBuf; readonly type: "project" }
+  | { readonly type: "sessionFlags" }
+  | {
+      readonly file: V2ConfigReadResponse__AbsolutePathBuf;
+      readonly type: "legacyManagedConfigTomlFromFile";
+    }
+  | { readonly type: "legacyManagedConfigTomlFromMdm" };
+export const V2ConfigReadResponse__ConfigLayerSource = Schema.Union(
+  [
+    Schema.Struct({
+      domain: Schema.String,
+      key: Schema.String,
+      type: Schema.Literal("mdm").annotate({ title: "MdmConfigLayerSourceType" }),
+    }).annotate({
+      title: "MdmConfigLayerSource",
+      description: "Managed preferences layer delivered by MDM (macOS only).",
+    }),
+    Schema.Struct({
+      file: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      type: Schema.Literal("system").annotate({ title: "SystemConfigLayerSourceType" }),
+    }).annotate({
+      title: "SystemConfigLayerSource",
+      description: "Managed config layer from a file (usually `managed_config.toml`).",
+    }),
+    Schema.Struct({
+      file: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      type: Schema.Literal("user").annotate({ title: "UserConfigLayerSourceType" }),
+    }).annotate({
+      title: "UserConfigLayerSource",
+      description:
+        "User config layer from $CODEX_HOME/config.toml. This layer is special in that it is expected to be: - writable by the user - generally outside the workspace directory",
+    }),
+    Schema.Struct({
+      dotCodexFolder: V2ConfigReadResponse__AbsolutePathBuf,
+      type: Schema.Literal("project").annotate({ title: "ProjectConfigLayerSourceType" }),
+    }).annotate({
+      title: "ProjectConfigLayerSource",
+      description:
+        "Path to a .codex/ folder within a project. There could be multiple of these between `cwd` and the project/repo root.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("sessionFlags").annotate({ title: "SessionFlagsConfigLayerSourceType" }),
+    }).annotate({
+      title: "SessionFlagsConfigLayerSource",
+      description: "Session-layer overrides supplied via `-c`/`--config`.",
+    }),
+    Schema.Struct({
+      file: V2ConfigReadResponse__AbsolutePathBuf,
+      type: Schema.Literal("legacyManagedConfigTomlFromFile").annotate({
+        title: "LegacyManagedConfigTomlFromFileConfigLayerSourceType",
+      }),
+    }).annotate({
+      title: "LegacyManagedConfigTomlFromFileConfigLayerSource",
+      description:
+        '`managed_config.toml` was designed to be a config that was loaded as the last layer on top of everything else. This scheme did not quite work out as intended, but we keep this variant as a "best effort" while we phase out `managed_config.toml` in favor of `requirements.toml`.',
+    }),
+    Schema.Struct({
+      type: Schema.Literal("legacyManagedConfigTomlFromMdm").annotate({
+        title: "LegacyManagedConfigTomlFromMdmConfigLayerSourceType",
+      }),
+    }).annotate({ title: "LegacyManagedConfigTomlFromMdmConfigLayerSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ConfigReadResponse__WebSearchToolConfig = {
+  readonly allowed_domains?: ReadonlyArray<string> | null;
+  readonly context_size?: V2ConfigReadResponse__WebSearchContextSize | null;
+  readonly location?: V2ConfigReadResponse__WebSearchLocation | null;
+};
+export const V2ConfigReadResponse__WebSearchToolConfig = Schema.Struct({
+  allowed_domains: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  context_size: Schema.optionalKey(
+    Schema.Union([V2ConfigReadResponse__WebSearchContextSize, Schema.Null]),
+  ),
+  location: Schema.optionalKey(
+    Schema.Union([V2ConfigReadResponse__WebSearchLocation, Schema.Null]),
+  ),
+});
+
+export type V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup = {
+  readonly hooks: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookHandler>;
+  readonly matcher?: string | null;
+};
+export const V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup = Schema.Struct({
+  hooks: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookHandler),
+  matcher: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ConfigRequirementsReadResponse__ConfigRequirements = {
+  readonly allowedApprovalPolicies?: ReadonlyArray<V2ConfigRequirementsReadResponse__AskForApproval> | null;
+  readonly allowedSandboxModes?: ReadonlyArray<V2ConfigRequirementsReadResponse__SandboxMode> | null;
+  readonly allowedWebSearchModes?: ReadonlyArray<V2ConfigRequirementsReadResponse__WebSearchMode> | null;
+  readonly enforceResidency?: V2ConfigRequirementsReadResponse__ResidencyRequirement | null;
+  readonly featureRequirements?: { readonly [x: string]: boolean } | null;
+};
+export const V2ConfigRequirementsReadResponse__ConfigRequirements = Schema.Struct({
+  allowedApprovalPolicies: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2ConfigRequirementsReadResponse__AskForApproval), Schema.Null]),
+  ),
+  allowedSandboxModes: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2ConfigRequirementsReadResponse__SandboxMode), Schema.Null]),
+  ),
+  allowedWebSearchModes: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2ConfigRequirementsReadResponse__WebSearchMode), Schema.Null]),
+  ),
+  enforceResidency: Schema.optionalKey(
+    Schema.Union([V2ConfigRequirementsReadResponse__ResidencyRequirement, Schema.Null]),
+  ),
+  featureRequirements: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.Boolean), Schema.Null]),
+  ),
+});
+
+export type V2ConfigWarningNotification__TextRange = {
+  readonly end: V2ConfigWarningNotification__TextPosition;
+  readonly start: V2ConfigWarningNotification__TextPosition;
+};
+export const V2ConfigWarningNotification__TextRange = Schema.Struct({
+  end: V2ConfigWarningNotification__TextPosition,
+  start: V2ConfigWarningNotification__TextPosition,
+});
+
+export type V2ConfigWriteResponse__ConfigLayerSource =
+  | { readonly domain: string; readonly key: string; readonly type: "mdm" }
+  | { readonly file: string; readonly type: "system" }
+  | { readonly file: string; readonly type: "user" }
+  | { readonly dotCodexFolder: V2ConfigWriteResponse__AbsolutePathBuf; readonly type: "project" }
+  | { readonly type: "sessionFlags" }
+  | {
+      readonly file: V2ConfigWriteResponse__AbsolutePathBuf;
+      readonly type: "legacyManagedConfigTomlFromFile";
+    }
+  | { readonly type: "legacyManagedConfigTomlFromMdm" };
+export const V2ConfigWriteResponse__ConfigLayerSource = Schema.Union(
+  [
+    Schema.Struct({
+      domain: Schema.String,
+      key: Schema.String,
+      type: Schema.Literal("mdm").annotate({ title: "MdmConfigLayerSourceType" }),
+    }).annotate({
+      title: "MdmConfigLayerSource",
+      description: "Managed preferences layer delivered by MDM (macOS only).",
+    }),
+    Schema.Struct({
+      file: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      type: Schema.Literal("system").annotate({ title: "SystemConfigLayerSourceType" }),
+    }).annotate({
+      title: "SystemConfigLayerSource",
+      description: "Managed config layer from a file (usually `managed_config.toml`).",
+    }),
+    Schema.Struct({
+      file: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      type: Schema.Literal("user").annotate({ title: "UserConfigLayerSourceType" }),
+    }).annotate({
+      title: "UserConfigLayerSource",
+      description:
+        "User config layer from $CODEX_HOME/config.toml. This layer is special in that it is expected to be: - writable by the user - generally outside the workspace directory",
+    }),
+    Schema.Struct({
+      dotCodexFolder: V2ConfigWriteResponse__AbsolutePathBuf,
+      type: Schema.Literal("project").annotate({ title: "ProjectConfigLayerSourceType" }),
+    }).annotate({
+      title: "ProjectConfigLayerSource",
+      description:
+        "Path to a .codex/ folder within a project. There could be multiple of these between `cwd` and the project/repo root.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("sessionFlags").annotate({ title: "SessionFlagsConfigLayerSourceType" }),
+    }).annotate({
+      title: "SessionFlagsConfigLayerSource",
+      description: "Session-layer overrides supplied via `-c`/`--config`.",
+    }),
+    Schema.Struct({
+      file: V2ConfigWriteResponse__AbsolutePathBuf,
+      type: Schema.Literal("legacyManagedConfigTomlFromFile").annotate({
+        title: "LegacyManagedConfigTomlFromFileConfigLayerSourceType",
+      }),
+    }).annotate({
+      title: "LegacyManagedConfigTomlFromFileConfigLayerSource",
+      description:
+        '`managed_config.toml` was designed to be a config that was loaded as the last layer on top of everything else. This scheme did not quite work out as intended, but we keep this variant as a "best effort" while we phase out `managed_config.toml` in favor of `requirements.toml`.',
+    }),
+    Schema.Struct({
+      type: Schema.Literal("legacyManagedConfigTomlFromMdm").annotate({
+        title: "LegacyManagedConfigTomlFromMdmConfigLayerSourceType",
+      }),
+    }).annotate({ title: "LegacyManagedConfigTomlFromMdmConfigLayerSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ErrorNotification__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ErrorNotification__NonSteerableTurnKind;
+      };
+    };
+export const V2ErrorNotification__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ErrorNotification__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ExternalAgentConfigDetectResponse__MigrationDetails = {
+  readonly commands?: ReadonlyArray<V2ExternalAgentConfigDetectResponse__CommandMigration>;
+  readonly hooks?: ReadonlyArray<V2ExternalAgentConfigDetectResponse__HookMigration>;
+  readonly mcpServers?: ReadonlyArray<V2ExternalAgentConfigDetectResponse__McpServerMigration>;
+  readonly plugins?: ReadonlyArray<V2ExternalAgentConfigDetectResponse__PluginsMigration>;
+  readonly sessions?: ReadonlyArray<V2ExternalAgentConfigDetectResponse__SessionMigration>;
+  readonly subagents?: ReadonlyArray<V2ExternalAgentConfigDetectResponse__SubagentMigration>;
+};
+export const V2ExternalAgentConfigDetectResponse__MigrationDetails = Schema.Struct({
+  commands: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigDetectResponse__CommandMigration).annotate({ default: [] }),
+  ),
+  hooks: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigDetectResponse__HookMigration).annotate({ default: [] }),
+  ),
+  mcpServers: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigDetectResponse__McpServerMigration).annotate({ default: [] }),
+  ),
+  plugins: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigDetectResponse__PluginsMigration).annotate({ default: [] }),
+  ),
+  sessions: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigDetectResponse__SessionMigration).annotate({ default: [] }),
+  ),
+  subagents: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigDetectResponse__SubagentMigration).annotate({ default: [] }),
+  ),
+});
+
+export type V2ExternalAgentConfigImportParams__MigrationDetails = {
+  readonly commands?: ReadonlyArray<V2ExternalAgentConfigImportParams__CommandMigration>;
+  readonly hooks?: ReadonlyArray<V2ExternalAgentConfigImportParams__HookMigration>;
+  readonly mcpServers?: ReadonlyArray<V2ExternalAgentConfigImportParams__McpServerMigration>;
+  readonly plugins?: ReadonlyArray<V2ExternalAgentConfigImportParams__PluginsMigration>;
+  readonly sessions?: ReadonlyArray<V2ExternalAgentConfigImportParams__SessionMigration>;
+  readonly subagents?: ReadonlyArray<V2ExternalAgentConfigImportParams__SubagentMigration>;
+};
+export const V2ExternalAgentConfigImportParams__MigrationDetails = Schema.Struct({
+  commands: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigImportParams__CommandMigration).annotate({ default: [] }),
+  ),
+  hooks: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigImportParams__HookMigration).annotate({ default: [] }),
+  ),
+  mcpServers: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigImportParams__McpServerMigration).annotate({ default: [] }),
+  ),
+  plugins: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigImportParams__PluginsMigration).annotate({ default: [] }),
+  ),
+  sessions: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigImportParams__SessionMigration).annotate({ default: [] }),
+  ),
+  subagents: Schema.optionalKey(
+    Schema.Array(V2ExternalAgentConfigImportParams__SubagentMigration).annotate({ default: [] }),
+  ),
+});
+
+export type V2FileChangePatchUpdatedNotification__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2FileChangePatchUpdatedNotification__PatchChangeKind;
+  readonly path: string;
+};
+export const V2FileChangePatchUpdatedNotification__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2FileChangePatchUpdatedNotification__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2GetAccountRateLimitsResponse__RateLimitSnapshot = {
+  readonly credits?: V2GetAccountRateLimitsResponse__CreditsSnapshot | null;
+  readonly limitId?: string | null;
+  readonly limitName?: string | null;
+  readonly planType?: V2GetAccountRateLimitsResponse__PlanType | null;
+  readonly primary?: V2GetAccountRateLimitsResponse__RateLimitWindow | null;
+  readonly rateLimitReachedType?: V2GetAccountRateLimitsResponse__RateLimitReachedType | null;
+  readonly secondary?: V2GetAccountRateLimitsResponse__RateLimitWindow | null;
+};
+export const V2GetAccountRateLimitsResponse__RateLimitSnapshot = Schema.Struct({
+  credits: Schema.optionalKey(
+    Schema.Union([V2GetAccountRateLimitsResponse__CreditsSnapshot, Schema.Null]),
+  ),
+  limitId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  limitName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  planType: Schema.optionalKey(
+    Schema.Union([V2GetAccountRateLimitsResponse__PlanType, Schema.Null]),
+  ),
+  primary: Schema.optionalKey(
+    Schema.Union([V2GetAccountRateLimitsResponse__RateLimitWindow, Schema.Null]),
+  ),
+  rateLimitReachedType: Schema.optionalKey(
+    Schema.Union([V2GetAccountRateLimitsResponse__RateLimitReachedType, Schema.Null]),
+  ),
+  secondary: Schema.optionalKey(
+    Schema.Union([V2GetAccountRateLimitsResponse__RateLimitWindow, Schema.Null]),
+  ),
+});
+
+export type V2GetAccountResponse__Account =
+  | { readonly type: "apiKey" }
+  | {
+      readonly email: string;
+      readonly planType: V2GetAccountResponse__PlanType;
+      readonly type: "chatgpt";
+    }
+  | { readonly type: "amazonBedrock" };
+export const V2GetAccountResponse__Account = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("apiKey").annotate({ title: "ApiKeyAccountType" }),
+    }).annotate({ title: "ApiKeyAccount" }),
+    Schema.Struct({
+      email: Schema.String,
+      planType: V2GetAccountResponse__PlanType,
+      type: Schema.Literal("chatgpt").annotate({ title: "ChatgptAccountType" }),
+    }).annotate({ title: "ChatgptAccount" }),
+    Schema.Struct({
+      type: Schema.Literal("amazonBedrock").annotate({ title: "AmazonBedrockAccountType" }),
+    }).annotate({ title: "AmazonBedrockAccount" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2HookCompletedNotification__HookOutputEntry = {
+  readonly kind: V2HookCompletedNotification__HookOutputEntryKind;
+  readonly text: string;
+};
+export const V2HookCompletedNotification__HookOutputEntry = Schema.Struct({
+  kind: V2HookCompletedNotification__HookOutputEntryKind,
+  text: Schema.String,
+});
+
+export type V2HooksListResponse__HookMetadata = {
+  readonly command?: string | null;
+  readonly currentHash: string;
+  readonly displayOrder: number;
+  readonly enabled: boolean;
+  readonly eventName: V2HooksListResponse__HookEventName;
+  readonly handlerType: V2HooksListResponse__HookHandlerType;
+  readonly isManaged: boolean;
+  readonly key: string;
+  readonly matcher?: string | null;
+  readonly pluginId?: string | null;
+  readonly source: V2HooksListResponse__HookSource;
+  readonly sourcePath: V2HooksListResponse__AbsolutePathBuf;
+  readonly statusMessage?: string | null;
+  readonly timeoutSec: number;
+  readonly trustStatus: V2HooksListResponse__HookTrustStatus;
+};
+export const V2HooksListResponse__HookMetadata = Schema.Struct({
+  command: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  currentHash: Schema.String,
+  displayOrder: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  enabled: Schema.Boolean,
+  eventName: V2HooksListResponse__HookEventName,
+  handlerType: V2HooksListResponse__HookHandlerType,
+  isManaged: Schema.Boolean,
+  key: Schema.String,
+  matcher: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  pluginId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  source: V2HooksListResponse__HookSource,
+  sourcePath: V2HooksListResponse__AbsolutePathBuf,
+  statusMessage: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  timeoutSec: Schema.Number.annotate({ format: "uint64" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  trustStatus: V2HooksListResponse__HookTrustStatus,
+});
+
+export type V2HookStartedNotification__HookOutputEntry = {
+  readonly kind: V2HookStartedNotification__HookOutputEntryKind;
+  readonly text: string;
+};
+export const V2HookStartedNotification__HookOutputEntry = Schema.Struct({
+  kind: V2HookStartedNotification__HookOutputEntryKind,
+  text: Schema.String,
+});
+
+export type V2ItemCompletedNotification__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ItemCompletedNotification__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ItemCompletedNotification__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ItemCompletedNotification__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemCompletedNotification__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ItemCompletedNotification__CollabAgentStatus;
+};
+export const V2ItemCompletedNotification__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ItemCompletedNotification__CollabAgentStatus,
+});
+
+export type V2ItemCompletedNotification__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ItemCompletedNotification__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ItemCompletedNotification__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ItemCompletedNotification__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ItemCompletedNotification__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ItemCompletedNotification__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ItemCompletedNotification__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ItemCompletedNotification__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ItemCompletedNotification__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ItemCompletedNotification__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ItemCompletedNotification__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ItemCompletedNotification__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__FileSystemPath =
+  | {
+      readonly path: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf;
+      readonly type: "path";
+    }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | {
+      readonly type: "special";
+      readonly value: V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSpecialPath;
+    };
+export const V2ItemGuardianApprovalReviewCompletedNotification__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReview = {
+  readonly rationale?: string | null;
+  readonly riskLevel?: V2ItemGuardianApprovalReviewCompletedNotification__GuardianRiskLevel | null;
+  readonly status: V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewStatus;
+  readonly userAuthorization?: V2ItemGuardianApprovalReviewCompletedNotification__GuardianUserAuthorization | null;
+};
+export const V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReview =
+  Schema.Struct({
+    rationale: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    riskLevel: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewCompletedNotification__GuardianRiskLevel,
+        Schema.Null,
+      ]),
+    ),
+    status: V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewStatus,
+    userAuthorization: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewCompletedNotification__GuardianUserAuthorization,
+        Schema.Null,
+      ]),
+    ),
+  }).annotate({
+    description:
+      "[UNSTABLE] Temporary approval auto-review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+  });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__FileSystemPath =
+  | {
+      readonly path: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf;
+      readonly type: "path";
+    }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | {
+      readonly type: "special";
+      readonly value: V2ItemGuardianApprovalReviewStartedNotification__FileSystemSpecialPath;
+    };
+export const V2ItemGuardianApprovalReviewStartedNotification__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: V2ItemGuardianApprovalReviewStartedNotification__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReview = {
+  readonly rationale?: string | null;
+  readonly riskLevel?: V2ItemGuardianApprovalReviewStartedNotification__GuardianRiskLevel | null;
+  readonly status: V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewStatus;
+  readonly userAuthorization?: V2ItemGuardianApprovalReviewStartedNotification__GuardianUserAuthorization | null;
+};
+export const V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReview =
+  Schema.Struct({
+    rationale: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    riskLevel: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewStartedNotification__GuardianRiskLevel,
+        Schema.Null,
+      ]),
+    ),
+    status: V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewStatus,
+    userAuthorization: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewStartedNotification__GuardianUserAuthorization,
+        Schema.Null,
+      ]),
+    ),
+  }).annotate({
+    description:
+      "[UNSTABLE] Temporary approval auto-review payload used by `item/autoApprovalReview/*` notifications. This shape is expected to change soon.",
+  });
+
+export type V2ItemStartedNotification__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ItemStartedNotification__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ItemStartedNotification__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ItemStartedNotification__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemStartedNotification__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ItemStartedNotification__CollabAgentStatus;
+};
+export const V2ItemStartedNotification__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ItemStartedNotification__CollabAgentStatus,
+});
+
+export type V2ItemStartedNotification__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ItemStartedNotification__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ItemStartedNotification__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ItemStartedNotification__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ItemStartedNotification__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ItemStartedNotification__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ItemStartedNotification__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ItemStartedNotification__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ItemStartedNotification__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ItemStartedNotification__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ItemStartedNotification__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ItemStartedNotification__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ListMcpServerStatusResponse__McpServerStatus = {
+  readonly authStatus: V2ListMcpServerStatusResponse__McpAuthStatus;
+  readonly name: string;
+  readonly resourceTemplates: ReadonlyArray<V2ListMcpServerStatusResponse__ResourceTemplate>;
+  readonly resources: ReadonlyArray<V2ListMcpServerStatusResponse__Resource>;
+  readonly tools: { readonly [x: string]: V2ListMcpServerStatusResponse__Tool };
+};
+export const V2ListMcpServerStatusResponse__McpServerStatus = Schema.Struct({
+  authStatus: V2ListMcpServerStatusResponse__McpAuthStatus,
+  name: Schema.String,
+  resourceTemplates: Schema.Array(V2ListMcpServerStatusResponse__ResourceTemplate),
+  resources: Schema.Array(V2ListMcpServerStatusResponse__Resource),
+  tools: Schema.Record(Schema.String, V2ListMcpServerStatusResponse__Tool),
+});
+
+export type V2ModelListResponse__ReasoningEffortOption = {
+  readonly description: string;
+  readonly reasoningEffort: V2ModelListResponse__ReasoningEffort;
+};
+export const V2ModelListResponse__ReasoningEffortOption = Schema.Struct({
+  description: Schema.String,
+  reasoningEffort: V2ModelListResponse__ReasoningEffort,
+});
+
+export type V2PluginListResponse__MarketplaceLoadErrorInfo = {
+  readonly marketplacePath: V2PluginListResponse__AbsolutePathBuf;
+  readonly message: string;
+};
+export const V2PluginListResponse__MarketplaceLoadErrorInfo = Schema.Struct({
+  marketplacePath: V2PluginListResponse__AbsolutePathBuf,
+  message: Schema.String,
+});
+
+export type V2PluginListResponse__PluginInterface = {
+  readonly brandColor?: string | null;
+  readonly capabilities: ReadonlyArray<string>;
+  readonly category?: string | null;
+  readonly composerIcon?: V2PluginListResponse__AbsolutePathBuf | null;
+  readonly composerIconUrl?: string | null;
+  readonly defaultPrompt?: ReadonlyArray<string> | null;
+  readonly developerName?: string | null;
+  readonly displayName?: string | null;
+  readonly logo?: V2PluginListResponse__AbsolutePathBuf | null;
+  readonly logoUrl?: string | null;
+  readonly longDescription?: string | null;
+  readonly privacyPolicyUrl?: string | null;
+  readonly screenshotUrls: ReadonlyArray<string>;
+  readonly screenshots: ReadonlyArray<V2PluginListResponse__AbsolutePathBuf>;
+  readonly shortDescription?: string | null;
+  readonly termsOfServiceUrl?: string | null;
+  readonly websiteUrl?: string | null;
+};
+export const V2PluginListResponse__PluginInterface = Schema.Struct({
+  brandColor: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  capabilities: Schema.Array(Schema.String),
+  category: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  composerIcon: Schema.optionalKey(
+    Schema.Union([V2PluginListResponse__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Local composer icon path, resolved from the installed plugin package.",
+    }),
+  ),
+  composerIconUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Remote composer icon URL from the plugin catalog." }),
+      Schema.Null,
+    ]),
+  ),
+  defaultPrompt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Starter prompts for the plugin. Capped at 3 entries with a maximum of 128 characters per entry.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  developerName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  displayName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  logo: Schema.optionalKey(
+    Schema.Union([V2PluginListResponse__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Local logo path, resolved from the installed plugin package.",
+    }),
+  ),
+  logoUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Remote logo URL from the plugin catalog." }),
+      Schema.Null,
+    ]),
+  ),
+  longDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  privacyPolicyUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  screenshotUrls: Schema.Array(Schema.String).annotate({
+    description: "Remote screenshot URLs from the plugin catalog.",
+  }),
+  screenshots: Schema.Array(V2PluginListResponse__AbsolutePathBuf).annotate({
+    description: "Local screenshot paths, resolved from the installed plugin package.",
+  }),
+  shortDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  termsOfServiceUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  websiteUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginListResponse__PluginSource =
+  | { readonly path: V2PluginListResponse__AbsolutePathBuf; readonly type: "local" }
+  | {
+      readonly path?: string | null;
+      readonly refName?: string | null;
+      readonly sha?: string | null;
+      readonly type: "git";
+      readonly url: string;
+    }
+  | { readonly type: "remote" };
+export const V2PluginListResponse__PluginSource = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2PluginListResponse__AbsolutePathBuf,
+      type: Schema.Literal("local").annotate({ title: "LocalPluginSourceType" }),
+    }).annotate({ title: "LocalPluginSource" }),
+    Schema.Struct({
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      refName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("git").annotate({ title: "GitPluginSourceType" }),
+      url: Schema.String,
+    }).annotate({ title: "GitPluginSource" }),
+    Schema.Struct({
+      type: Schema.Literal("remote").annotate({ title: "RemotePluginSourceType" }),
+    }).annotate({
+      title: "RemotePluginSource",
+      description:
+        "The plugin is available in the remote catalog. Download metadata is kept server-side and is not exposed through the app-server API.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2PluginListResponse__PluginSharePrincipal = {
+  readonly name: string;
+  readonly principalId: string;
+  readonly principalType: V2PluginListResponse__PluginSharePrincipalType;
+};
+export const V2PluginListResponse__PluginSharePrincipal = Schema.Struct({
+  name: Schema.String,
+  principalId: Schema.String,
+  principalType: V2PluginListResponse__PluginSharePrincipalType,
+});
+
+export type V2PluginReadResponse__PluginInterface = {
+  readonly brandColor?: string | null;
+  readonly capabilities: ReadonlyArray<string>;
+  readonly category?: string | null;
+  readonly composerIcon?: V2PluginReadResponse__AbsolutePathBuf | null;
+  readonly composerIconUrl?: string | null;
+  readonly defaultPrompt?: ReadonlyArray<string> | null;
+  readonly developerName?: string | null;
+  readonly displayName?: string | null;
+  readonly logo?: V2PluginReadResponse__AbsolutePathBuf | null;
+  readonly logoUrl?: string | null;
+  readonly longDescription?: string | null;
+  readonly privacyPolicyUrl?: string | null;
+  readonly screenshotUrls: ReadonlyArray<string>;
+  readonly screenshots: ReadonlyArray<V2PluginReadResponse__AbsolutePathBuf>;
+  readonly shortDescription?: string | null;
+  readonly termsOfServiceUrl?: string | null;
+  readonly websiteUrl?: string | null;
+};
+export const V2PluginReadResponse__PluginInterface = Schema.Struct({
+  brandColor: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  capabilities: Schema.Array(Schema.String),
+  category: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  composerIcon: Schema.optionalKey(
+    Schema.Union([V2PluginReadResponse__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Local composer icon path, resolved from the installed plugin package.",
+    }),
+  ),
+  composerIconUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Remote composer icon URL from the plugin catalog." }),
+      Schema.Null,
+    ]),
+  ),
+  defaultPrompt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Starter prompts for the plugin. Capped at 3 entries with a maximum of 128 characters per entry.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  developerName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  displayName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  logo: Schema.optionalKey(
+    Schema.Union([V2PluginReadResponse__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Local logo path, resolved from the installed plugin package.",
+    }),
+  ),
+  logoUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Remote logo URL from the plugin catalog." }),
+      Schema.Null,
+    ]),
+  ),
+  longDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  privacyPolicyUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  screenshotUrls: Schema.Array(Schema.String).annotate({
+    description: "Remote screenshot URLs from the plugin catalog.",
+  }),
+  screenshots: Schema.Array(V2PluginReadResponse__AbsolutePathBuf).annotate({
+    description: "Local screenshot paths, resolved from the installed plugin package.",
+  }),
+  shortDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  termsOfServiceUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  websiteUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginReadResponse__PluginSource =
+  | { readonly path: V2PluginReadResponse__AbsolutePathBuf; readonly type: "local" }
+  | {
+      readonly path?: string | null;
+      readonly refName?: string | null;
+      readonly sha?: string | null;
+      readonly type: "git";
+      readonly url: string;
+    }
+  | { readonly type: "remote" };
+export const V2PluginReadResponse__PluginSource = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2PluginReadResponse__AbsolutePathBuf,
+      type: Schema.Literal("local").annotate({ title: "LocalPluginSourceType" }),
+    }).annotate({ title: "LocalPluginSource" }),
+    Schema.Struct({
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      refName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("git").annotate({ title: "GitPluginSourceType" }),
+      url: Schema.String,
+    }).annotate({ title: "GitPluginSource" }),
+    Schema.Struct({
+      type: Schema.Literal("remote").annotate({ title: "RemotePluginSourceType" }),
+    }).annotate({
+      title: "RemotePluginSource",
+      description:
+        "The plugin is available in the remote catalog. Download metadata is kept server-side and is not exposed through the app-server API.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2PluginReadResponse__SkillInterface = {
+  readonly brandColor?: string | null;
+  readonly defaultPrompt?: string | null;
+  readonly displayName?: string | null;
+  readonly iconLarge?: V2PluginReadResponse__AbsolutePathBuf | null;
+  readonly iconSmall?: V2PluginReadResponse__AbsolutePathBuf | null;
+  readonly shortDescription?: string | null;
+};
+export const V2PluginReadResponse__SkillInterface = Schema.Struct({
+  brandColor: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  defaultPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  displayName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  iconLarge: Schema.optionalKey(Schema.Union([V2PluginReadResponse__AbsolutePathBuf, Schema.Null])),
+  iconSmall: Schema.optionalKey(Schema.Union([V2PluginReadResponse__AbsolutePathBuf, Schema.Null])),
+  shortDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginReadResponse__PluginHookSummary = {
+  readonly eventName: V2PluginReadResponse__HookEventName;
+  readonly key: string;
+};
+export const V2PluginReadResponse__PluginHookSummary = Schema.Struct({
+  eventName: V2PluginReadResponse__HookEventName,
+  key: Schema.String,
+});
+
+export type V2PluginReadResponse__PluginSharePrincipal = {
+  readonly name: string;
+  readonly principalId: string;
+  readonly principalType: V2PluginReadResponse__PluginSharePrincipalType;
+};
+export const V2PluginReadResponse__PluginSharePrincipal = Schema.Struct({
+  name: Schema.String,
+  principalId: Schema.String,
+  principalType: V2PluginReadResponse__PluginSharePrincipalType,
+});
+
+export type V2PluginShareListResponse__PluginInterface = {
+  readonly brandColor?: string | null;
+  readonly capabilities: ReadonlyArray<string>;
+  readonly category?: string | null;
+  readonly composerIcon?: V2PluginShareListResponse__AbsolutePathBuf | null;
+  readonly composerIconUrl?: string | null;
+  readonly defaultPrompt?: ReadonlyArray<string> | null;
+  readonly developerName?: string | null;
+  readonly displayName?: string | null;
+  readonly logo?: V2PluginShareListResponse__AbsolutePathBuf | null;
+  readonly logoUrl?: string | null;
+  readonly longDescription?: string | null;
+  readonly privacyPolicyUrl?: string | null;
+  readonly screenshotUrls: ReadonlyArray<string>;
+  readonly screenshots: ReadonlyArray<V2PluginShareListResponse__AbsolutePathBuf>;
+  readonly shortDescription?: string | null;
+  readonly termsOfServiceUrl?: string | null;
+  readonly websiteUrl?: string | null;
+};
+export const V2PluginShareListResponse__PluginInterface = Schema.Struct({
+  brandColor: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  capabilities: Schema.Array(Schema.String),
+  category: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  composerIcon: Schema.optionalKey(
+    Schema.Union([V2PluginShareListResponse__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Local composer icon path, resolved from the installed plugin package.",
+    }),
+  ),
+  composerIconUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Remote composer icon URL from the plugin catalog." }),
+      Schema.Null,
+    ]),
+  ),
+  defaultPrompt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Starter prompts for the plugin. Capped at 3 entries with a maximum of 128 characters per entry.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  developerName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  displayName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  logo: Schema.optionalKey(
+    Schema.Union([V2PluginShareListResponse__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Local logo path, resolved from the installed plugin package.",
+    }),
+  ),
+  logoUrl: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Remote logo URL from the plugin catalog." }),
+      Schema.Null,
+    ]),
+  ),
+  longDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  privacyPolicyUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  screenshotUrls: Schema.Array(Schema.String).annotate({
+    description: "Remote screenshot URLs from the plugin catalog.",
+  }),
+  screenshots: Schema.Array(V2PluginShareListResponse__AbsolutePathBuf).annotate({
+    description: "Local screenshot paths, resolved from the installed plugin package.",
+  }),
+  shortDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  termsOfServiceUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  websiteUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginShareListResponse__PluginSource =
+  | { readonly path: V2PluginShareListResponse__AbsolutePathBuf; readonly type: "local" }
+  | {
+      readonly path?: string | null;
+      readonly refName?: string | null;
+      readonly sha?: string | null;
+      readonly type: "git";
+      readonly url: string;
+    }
+  | { readonly type: "remote" };
+export const V2PluginShareListResponse__PluginSource = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2PluginShareListResponse__AbsolutePathBuf,
+      type: Schema.Literal("local").annotate({ title: "LocalPluginSourceType" }),
+    }).annotate({ title: "LocalPluginSource" }),
+    Schema.Struct({
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      refName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      sha: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("git").annotate({ title: "GitPluginSourceType" }),
+      url: Schema.String,
+    }).annotate({ title: "GitPluginSource" }),
+    Schema.Struct({
+      type: Schema.Literal("remote").annotate({ title: "RemotePluginSourceType" }),
+    }).annotate({
+      title: "RemotePluginSource",
+      description:
+        "The plugin is available in the remote catalog. Download metadata is kept server-side and is not exposed through the app-server API.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2PluginShareListResponse__PluginSharePrincipal = {
+  readonly name: string;
+  readonly principalId: string;
+  readonly principalType: V2PluginShareListResponse__PluginSharePrincipalType;
+};
+export const V2PluginShareListResponse__PluginSharePrincipal = Schema.Struct({
+  name: Schema.String,
+  principalId: Schema.String,
+  principalType: V2PluginShareListResponse__PluginSharePrincipalType,
+});
+
+export type V2PluginShareSaveParams__PluginShareTarget = {
+  readonly principalId: string;
+  readonly principalType: V2PluginShareSaveParams__PluginSharePrincipalType;
+};
+export const V2PluginShareSaveParams__PluginShareTarget = Schema.Struct({
+  principalId: Schema.String,
+  principalType: V2PluginShareSaveParams__PluginSharePrincipalType,
+});
+
+export type V2PluginShareUpdateTargetsParams__PluginShareTarget = {
+  readonly principalId: string;
+  readonly principalType: V2PluginShareUpdateTargetsParams__PluginSharePrincipalType;
+};
+export const V2PluginShareUpdateTargetsParams__PluginShareTarget = Schema.Struct({
+  principalId: Schema.String,
+  principalType: V2PluginShareUpdateTargetsParams__PluginSharePrincipalType,
+});
+
+export type V2PluginShareUpdateTargetsResponse__PluginSharePrincipal = {
+  readonly name: string;
+  readonly principalId: string;
+  readonly principalType: V2PluginShareUpdateTargetsResponse__PluginSharePrincipalType;
+};
+export const V2PluginShareUpdateTargetsResponse__PluginSharePrincipal = Schema.Struct({
+  name: Schema.String,
+  principalId: Schema.String,
+  principalType: V2PluginShareUpdateTargetsResponse__PluginSharePrincipalType,
+});
+
+export type V2RawResponseItemCompletedNotification__ContentItem =
+  | { readonly text: string; readonly type: "input_text" }
+  | {
+      readonly detail?: V2RawResponseItemCompletedNotification__ImageDetail | null;
+      readonly image_url: string;
+      readonly type: "input_image";
+    }
+  | { readonly text: string; readonly type: "output_text" };
+export const V2RawResponseItemCompletedNotification__ContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("input_text").annotate({ title: "InputTextContentItemType" }),
+    }).annotate({ title: "InputTextContentItem" }),
+    Schema.Struct({
+      detail: Schema.optionalKey(
+        Schema.Union([V2RawResponseItemCompletedNotification__ImageDetail, Schema.Null]),
+      ),
+      image_url: Schema.String,
+      type: Schema.Literal("input_image").annotate({ title: "InputImageContentItemType" }),
+    }).annotate({ title: "InputImageContentItem" }),
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("output_text").annotate({ title: "OutputTextContentItemType" }),
+    }).annotate({ title: "OutputTextContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2RawResponseItemCompletedNotification__FunctionCallOutputContentItem =
+  | { readonly text: string; readonly type: "input_text" }
+  | {
+      readonly detail?: V2RawResponseItemCompletedNotification__ImageDetail | null;
+      readonly image_url: string;
+      readonly type: "input_image";
+    };
+export const V2RawResponseItemCompletedNotification__FunctionCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("input_text").annotate({
+        title: "InputTextFunctionCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextFunctionCallOutputContentItem" }),
+    Schema.Struct({
+      detail: Schema.optionalKey(
+        Schema.Union([V2RawResponseItemCompletedNotification__ImageDetail, Schema.Null]),
+      ),
+      image_url: Schema.String,
+      type: Schema.Literal("input_image").annotate({
+        title: "InputImageFunctionCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageFunctionCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "Responses API compatible content items that can be returned by a tool call. This is a subset of ContentItem with the types we support as function call outputs.",
+});
+
+export type V2ReviewStartResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ReviewStartResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ReviewStartResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ReviewStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ReviewStartResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ReviewStartResponse__CollabAgentStatus;
+};
+export const V2ReviewStartResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ReviewStartResponse__CollabAgentStatus,
+});
+
+export type V2ReviewStartResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ReviewStartResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ReviewStartResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ReviewStartResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ReviewStartResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ReviewStartResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ReviewStartResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ReviewStartResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ReviewStartResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ReviewStartResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ReviewStartResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ReviewStartResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ReviewStartResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ReviewStartResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ReviewStartResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ReviewStartResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2SkillsListResponse__SkillInterface = {
+  readonly brandColor?: string | null;
+  readonly defaultPrompt?: string | null;
+  readonly displayName?: string | null;
+  readonly iconLarge?: V2SkillsListResponse__AbsolutePathBuf | null;
+  readonly iconSmall?: V2SkillsListResponse__AbsolutePathBuf | null;
+  readonly shortDescription?: string | null;
+};
+export const V2SkillsListResponse__SkillInterface = Schema.Struct({
+  brandColor: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  defaultPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  displayName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  iconLarge: Schema.optionalKey(Schema.Union([V2SkillsListResponse__AbsolutePathBuf, Schema.Null])),
+  iconSmall: Schema.optionalKey(Schema.Union([V2SkillsListResponse__AbsolutePathBuf, Schema.Null])),
+  shortDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2SkillsListResponse__SkillDependencies = {
+  readonly tools: ReadonlyArray<V2SkillsListResponse__SkillToolDependency>;
+};
+export const V2SkillsListResponse__SkillDependencies = Schema.Struct({
+  tools: Schema.Array(V2SkillsListResponse__SkillToolDependency),
+});
+
+export type V2ThreadForkParams__PermissionProfileModificationParams = {
+  readonly path: V2ThreadForkParams__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const V2ThreadForkParams__PermissionProfileModificationParams = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadForkParams__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootPermissionProfileModificationParamsType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootPermissionProfileModificationParams",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__ActivePermissionProfileModification = {
+  readonly path: V2ThreadForkResponse__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const V2ThreadForkResponse__ActivePermissionProfileModification = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadForkResponse__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootActivePermissionProfileModificationType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootActivePermissionProfileModification",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadForkResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadForkResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadForkResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadForkResponse__CollabAgentStatus;
+};
+export const V2ThreadForkResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadForkResponse__CollabAgentStatus,
+});
+
+export type V2ThreadForkResponse__FileSystemPath =
+  | { readonly path: V2ThreadForkResponse__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | { readonly type: "special"; readonly value: V2ThreadForkResponse__FileSystemSpecialPath };
+export const V2ThreadForkResponse__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadForkResponse__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: V2ThreadForkResponse__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadForkResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadForkResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadForkResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadForkResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadForkResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadForkResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadForkResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadForkResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadForkResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadForkResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadForkResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadForkResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadForkResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadForkResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadForkResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadForkResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadForkResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadForkResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadForkResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadForkResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadGoalUpdatedNotification__ThreadGoal = {
+  readonly createdAt: number;
+  readonly objective: string;
+  readonly status: V2ThreadGoalUpdatedNotification__ThreadGoalStatus;
+  readonly threadId: string;
+  readonly timeUsedSeconds: number;
+  readonly tokenBudget?: number | null;
+  readonly tokensUsed: number;
+  readonly updatedAt: number;
+};
+export const V2ThreadGoalUpdatedNotification__ThreadGoal = Schema.Struct({
+  createdAt: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  objective: Schema.String,
+  status: V2ThreadGoalUpdatedNotification__ThreadGoalStatus,
+  threadId: Schema.String,
+  timeUsedSeconds: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  tokenBudget: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  tokensUsed: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  updatedAt: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+});
+
+export type V2ThreadListResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadListResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadListResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadListResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadListResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadListResponse__CollabAgentStatus;
+};
+export const V2ThreadListResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadListResponse__CollabAgentStatus,
+});
+
+export type V2ThreadListResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadListResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadListResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadListResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadListResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadListResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadListResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadListResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadListResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadListResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadListResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadListResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadListResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadListResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadListResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadListResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadListResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadListResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadListResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadListResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadListResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadListResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadMetadataUpdateResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadMetadataUpdateResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadMetadataUpdateResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadMetadataUpdateResponse__CollabAgentStatus;
+};
+export const V2ThreadMetadataUpdateResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadMetadataUpdateResponse__CollabAgentStatus,
+});
+
+export type V2ThreadMetadataUpdateResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadMetadataUpdateResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadMetadataUpdateResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadMetadataUpdateResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadMetadataUpdateResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadMetadataUpdateResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadMetadataUpdateResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadMetadataUpdateResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadMetadataUpdateResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadMetadataUpdateResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadMetadataUpdateResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadMetadataUpdateResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadMetadataUpdateResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadMetadataUpdateResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadMetadataUpdateResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadMetadataUpdateResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadMetadataUpdateResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadMetadataUpdateResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadMetadataUpdateResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadMetadataUpdateResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadMetadataUpdateResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadReadResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadReadResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadReadResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadReadResponse__CollabAgentStatus;
+};
+export const V2ThreadReadResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadReadResponse__CollabAgentStatus,
+});
+
+export type V2ThreadReadResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadReadResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadReadResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadReadResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadReadResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadReadResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadReadResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadReadResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadReadResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadReadResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadReadResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadReadResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadReadResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadReadResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadReadResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadReadResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadReadResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadReadResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadReadResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadReadResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadReadResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__PermissionProfileModificationParams = {
+  readonly path: V2ThreadResumeParams__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const V2ThreadResumeParams__PermissionProfileModificationParams = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadResumeParams__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootPermissionProfileModificationParamsType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootPermissionProfileModificationParams",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__ContentItem =
+  | { readonly text: string; readonly type: "input_text" }
+  | {
+      readonly detail?: V2ThreadResumeParams__ImageDetail | null;
+      readonly image_url: string;
+      readonly type: "input_image";
+    }
+  | { readonly text: string; readonly type: "output_text" };
+export const V2ThreadResumeParams__ContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("input_text").annotate({ title: "InputTextContentItemType" }),
+    }).annotate({ title: "InputTextContentItem" }),
+    Schema.Struct({
+      detail: Schema.optionalKey(Schema.Union([V2ThreadResumeParams__ImageDetail, Schema.Null])),
+      image_url: Schema.String,
+      type: Schema.Literal("input_image").annotate({ title: "InputImageContentItemType" }),
+    }).annotate({ title: "InputImageContentItem" }),
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("output_text").annotate({ title: "OutputTextContentItemType" }),
+    }).annotate({ title: "OutputTextContentItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__FunctionCallOutputContentItem =
+  | { readonly text: string; readonly type: "input_text" }
+  | {
+      readonly detail?: V2ThreadResumeParams__ImageDetail | null;
+      readonly image_url: string;
+      readonly type: "input_image";
+    };
+export const V2ThreadResumeParams__FunctionCallOutputContentItem = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      type: Schema.Literal("input_text").annotate({
+        title: "InputTextFunctionCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputTextFunctionCallOutputContentItem" }),
+    Schema.Struct({
+      detail: Schema.optionalKey(Schema.Union([V2ThreadResumeParams__ImageDetail, Schema.Null])),
+      image_url: Schema.String,
+      type: Schema.Literal("input_image").annotate({
+        title: "InputImageFunctionCallOutputContentItemType",
+      }),
+    }).annotate({ title: "InputImageFunctionCallOutputContentItem" }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "Responses API compatible content items that can be returned by a tool call. This is a subset of ContentItem with the types we support as function call outputs.",
+});
+
+export type V2ThreadResumeResponse__ActivePermissionProfileModification = {
+  readonly path: V2ThreadResumeResponse__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const V2ThreadResumeResponse__ActivePermissionProfileModification = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadResumeResponse__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootActivePermissionProfileModificationType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootActivePermissionProfileModification",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadResumeResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadResumeResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadResumeResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadResumeResponse__CollabAgentStatus;
+};
+export const V2ThreadResumeResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadResumeResponse__CollabAgentStatus,
+});
+
+export type V2ThreadResumeResponse__FileSystemPath =
+  | { readonly path: V2ThreadResumeResponse__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | { readonly type: "special"; readonly value: V2ThreadResumeResponse__FileSystemSpecialPath };
+export const V2ThreadResumeResponse__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadResumeResponse__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: V2ThreadResumeResponse__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadResumeResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadResumeResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadResumeResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadResumeResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadResumeResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadResumeResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadResumeResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadResumeResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadResumeResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadResumeResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadResumeResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadResumeResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadResumeResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadResumeResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadResumeResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadResumeResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadResumeResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadResumeResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadResumeResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadResumeResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadRollbackResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadRollbackResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadRollbackResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadRollbackResponse__CollabAgentStatus;
+};
+export const V2ThreadRollbackResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadRollbackResponse__CollabAgentStatus,
+});
+
+export type V2ThreadRollbackResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadRollbackResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadRollbackResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadRollbackResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadRollbackResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadRollbackResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadRollbackResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadRollbackResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadRollbackResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadRollbackResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadRollbackResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadRollbackResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadRollbackResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadRollbackResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadRollbackResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadRollbackResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadRollbackResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadRollbackResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadRollbackResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadRollbackResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadRollbackResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadStartedNotification__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadStartedNotification__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadStartedNotification__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadStartedNotification__CollabAgentStatus;
+};
+export const V2ThreadStartedNotification__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadStartedNotification__CollabAgentStatus,
+});
+
+export type V2ThreadStartedNotification__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadStartedNotification__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadStartedNotification__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadStartedNotification__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadStartedNotification__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadStartedNotification__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadStartedNotification__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadStartedNotification__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadStartedNotification__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadStartedNotification__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadStartedNotification__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadStartedNotification__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadStartedNotification__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadStartedNotification__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadStartedNotification__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadStartedNotification__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadStartedNotification__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadStartedNotification__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadStartedNotification__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadStartedNotification__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadStartedNotification__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartParams__PermissionProfileModificationParams = {
+  readonly path: V2ThreadStartParams__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const V2ThreadStartParams__PermissionProfileModificationParams = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadStartParams__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootPermissionProfileModificationParamsType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootPermissionProfileModificationParams",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__ActivePermissionProfileModification = {
+  readonly path: V2ThreadStartResponse__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const V2ThreadStartResponse__ActivePermissionProfileModification = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootActivePermissionProfileModificationType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootActivePermissionProfileModification",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadStartResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadStartResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadStartResponse__CollabAgentStatus;
+};
+export const V2ThreadStartResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadStartResponse__CollabAgentStatus,
+});
+
+export type V2ThreadStartResponse__FileSystemPath =
+  | { readonly path: V2ThreadStartResponse__AbsolutePathBuf; readonly type: "path" }
+  | { readonly pattern: string; readonly type: "glob_pattern" }
+  | { readonly type: "special"; readonly value: V2ThreadStartResponse__FileSystemSpecialPath };
+export const V2ThreadStartResponse__FileSystemPath = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2ThreadStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("path").annotate({ title: "PathFileSystemPathType" }),
+    }).annotate({ title: "PathFileSystemPath" }),
+    Schema.Struct({
+      pattern: Schema.String,
+      type: Schema.Literal("glob_pattern").annotate({ title: "GlobPatternFileSystemPathType" }),
+    }).annotate({ title: "GlobPatternFileSystemPath" }),
+    Schema.Struct({
+      type: Schema.Literal("special").annotate({ title: "SpecialFileSystemPathType" }),
+      value: V2ThreadStartResponse__FileSystemSpecialPath,
+    }).annotate({ title: "SpecialFileSystemPath" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadStartResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadStartResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadStartResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadStartResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadStartResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadStartResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadStartResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadStartResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadStartResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadStartResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadStartResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadStartResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadStartResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadStartResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadStartResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadStartResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadStartResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadStartResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadStartResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadStartResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStatusChangedNotification__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadStatusChangedNotification__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadStatusChangedNotification__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadStatusChangedNotification__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadTokenUsageUpdatedNotification__ThreadTokenUsage = {
+  readonly last: V2ThreadTokenUsageUpdatedNotification__TokenUsageBreakdown;
+  readonly modelContextWindow?: number | null;
+  readonly total: V2ThreadTokenUsageUpdatedNotification__TokenUsageBreakdown;
+};
+export const V2ThreadTokenUsageUpdatedNotification__ThreadTokenUsage = Schema.Struct({
+  last: V2ThreadTokenUsageUpdatedNotification__TokenUsageBreakdown,
+  modelContextWindow: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  total: V2ThreadTokenUsageUpdatedNotification__TokenUsageBreakdown,
+});
+
+export type V2ThreadUnarchiveResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2ThreadUnarchiveResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2ThreadUnarchiveResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2ThreadUnarchiveResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnarchiveResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2ThreadUnarchiveResponse__CollabAgentStatus;
+};
+export const V2ThreadUnarchiveResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2ThreadUnarchiveResponse__CollabAgentStatus,
+});
+
+export type V2ThreadUnarchiveResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2ThreadUnarchiveResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2ThreadUnarchiveResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2ThreadUnarchiveResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2ThreadUnarchiveResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2ThreadUnarchiveResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2ThreadUnarchiveResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2ThreadUnarchiveResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2ThreadUnarchiveResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2ThreadUnarchiveResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2ThreadUnarchiveResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2ThreadUnarchiveResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2ThreadUnarchiveResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2ThreadUnarchiveResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2ThreadUnarchiveResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2ThreadUnarchiveResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnarchiveResponse__SubAgentSource =
+  | "review"
+  | "compact"
+  | "memory_consolidation"
+  | {
+      readonly thread_spawn: {
+        readonly agent_nickname?: string | null;
+        readonly agent_path?: V2ThreadUnarchiveResponse__AgentPath | null;
+        readonly agent_role?: string | null;
+        readonly depth: number;
+        readonly parent_thread_id: V2ThreadUnarchiveResponse__ThreadId;
+      };
+    }
+  | { readonly other: string };
+export const V2ThreadUnarchiveResponse__SubAgentSource = Schema.Union(
+  [
+    Schema.Literals(["review", "compact", "memory_consolidation"]),
+    Schema.Struct({
+      thread_spawn: Schema.Struct({
+        agent_nickname: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        agent_path: Schema.optionalKey(
+          Schema.Union([V2ThreadUnarchiveResponse__AgentPath, Schema.Null]),
+        ),
+        agent_role: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        depth: Schema.Number.annotate({ format: "int32" }).check(Schema.isInt()),
+        parent_thread_id: V2ThreadUnarchiveResponse__ThreadId,
+      }),
+    }).annotate({ title: "ThreadSpawnSubAgentSource" }),
+    Schema.Struct({ other: Schema.String }).annotate({ title: "OtherSubAgentSource" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnCompletedNotification__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2TurnCompletedNotification__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2TurnCompletedNotification__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2TurnCompletedNotification__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnCompletedNotification__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2TurnCompletedNotification__CollabAgentStatus;
+};
+export const V2TurnCompletedNotification__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2TurnCompletedNotification__CollabAgentStatus,
+});
+
+export type V2TurnCompletedNotification__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2TurnCompletedNotification__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2TurnCompletedNotification__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2TurnCompletedNotification__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2TurnCompletedNotification__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2TurnCompletedNotification__NonSteerableTurnKind;
+      };
+    };
+export const V2TurnCompletedNotification__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2TurnCompletedNotification__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2TurnCompletedNotification__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2TurnCompletedNotification__PatchChangeKind;
+  readonly path: string;
+};
+export const V2TurnCompletedNotification__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2TurnCompletedNotification__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2TurnCompletedNotification__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2TurnCompletedNotification__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2TurnCompletedNotification__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2TurnCompletedNotification__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnPlanUpdatedNotification__TurnPlanStep = {
+  readonly status: V2TurnPlanUpdatedNotification__TurnPlanStepStatus;
+  readonly step: string;
+};
+export const V2TurnPlanUpdatedNotification__TurnPlanStep = Schema.Struct({
+  status: V2TurnPlanUpdatedNotification__TurnPlanStepStatus,
+  step: Schema.String,
+});
+
+export type V2TurnStartedNotification__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2TurnStartedNotification__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2TurnStartedNotification__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2TurnStartedNotification__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartedNotification__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2TurnStartedNotification__CollabAgentStatus;
+};
+export const V2TurnStartedNotification__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2TurnStartedNotification__CollabAgentStatus,
+});
+
+export type V2TurnStartedNotification__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2TurnStartedNotification__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2TurnStartedNotification__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2TurnStartedNotification__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2TurnStartedNotification__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2TurnStartedNotification__NonSteerableTurnKind;
+      };
+    };
+export const V2TurnStartedNotification__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2TurnStartedNotification__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2TurnStartedNotification__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2TurnStartedNotification__PatchChangeKind;
+  readonly path: string;
+};
+export const V2TurnStartedNotification__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2TurnStartedNotification__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2TurnStartedNotification__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2TurnStartedNotification__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2TurnStartedNotification__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2TurnStartedNotification__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartParams__PermissionProfileModificationParams = {
+  readonly path: V2TurnStartParams__AbsolutePathBuf;
+  readonly type: "additionalWritableRoot";
+};
+export const V2TurnStartParams__PermissionProfileModificationParams = Schema.Union(
+  [
+    Schema.Struct({
+      path: V2TurnStartParams__AbsolutePathBuf,
+      type: Schema.Literal("additionalWritableRoot").annotate({
+        title: "AdditionalWritableRootPermissionProfileModificationParamsType",
+      }),
+    }).annotate({
+      title: "AdditionalWritableRootPermissionProfileModificationParams",
+      description: "Additional concrete directory that should be writable.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartParams__SandboxPolicy =
+  | { readonly type: "dangerFullAccess" }
+  | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+  | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+  | {
+      readonly excludeSlashTmp?: boolean;
+      readonly excludeTmpdirEnvVar?: boolean;
+      readonly networkAccess?: boolean;
+      readonly type: "workspaceWrite";
+      readonly writableRoots?: ReadonlyArray<V2TurnStartParams__AbsolutePathBuf>;
+    };
+export const V2TurnStartParams__SandboxPolicy = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("dangerFullAccess").annotate({
+        title: "DangerFullAccessSandboxPolicyType",
+      }),
+    }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+    }).annotate({ title: "ReadOnlySandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(
+        Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+      ),
+      type: Schema.Literal("externalSandbox").annotate({
+        title: "ExternalSandboxSandboxPolicyType",
+      }),
+    }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+    Schema.Struct({
+      excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("workspaceWrite").annotate({ title: "WorkspaceWriteSandboxPolicyType" }),
+      writableRoots: Schema.optionalKey(
+        Schema.Array(V2TurnStartParams__AbsolutePathBuf).annotate({ default: [] }),
+      ),
+    }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartParams__Settings = {
+  readonly developer_instructions?: string | null;
+  readonly model: string;
+  readonly reasoning_effort?: V2TurnStartParams__ReasoningEffort | null;
+};
+export const V2TurnStartParams__Settings = Schema.Struct({
+  developer_instructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  model: Schema.String,
+  reasoning_effort: Schema.optionalKey(
+    Schema.Union([V2TurnStartParams__ReasoningEffort, Schema.Null]),
+  ),
+}).annotate({ description: "Settings for a collaboration mode." });
+
+export type V2TurnStartParams__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2TurnStartParams__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2TurnStartParams__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2TurnStartParams__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartResponse__CommandAction =
+  | {
+      readonly command: string;
+      readonly name: string;
+      readonly path: V2TurnStartResponse__AbsolutePathBuf;
+      readonly type: "read";
+    }
+  | { readonly command: string; readonly path?: string | null; readonly type: "listFiles" }
+  | {
+      readonly command: string;
+      readonly path?: string | null;
+      readonly query?: string | null;
+      readonly type: "search";
+    }
+  | { readonly command: string; readonly type: "unknown" };
+export const V2TurnStartResponse__CommandAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      name: Schema.String,
+      path: V2TurnStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("read").annotate({ title: "ReadCommandActionType" }),
+    }).annotate({ title: "ReadCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("listFiles").annotate({ title: "ListFilesCommandActionType" }),
+    }).annotate({ title: "ListFilesCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      path: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      query: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("search").annotate({ title: "SearchCommandActionType" }),
+    }).annotate({ title: "SearchCommandAction" }),
+    Schema.Struct({
+      command: Schema.String,
+      type: Schema.Literal("unknown").annotate({ title: "UnknownCommandActionType" }),
+    }).annotate({ title: "UnknownCommandAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartResponse__CollabAgentState = {
+  readonly message?: string | null;
+  readonly status: V2TurnStartResponse__CollabAgentStatus;
+};
+export const V2TurnStartResponse__CollabAgentState = Schema.Struct({
+  message: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2TurnStartResponse__CollabAgentStatus,
+});
+
+export type V2TurnStartResponse__MemoryCitation = {
+  readonly entries: ReadonlyArray<V2TurnStartResponse__MemoryCitationEntry>;
+  readonly threadIds: ReadonlyArray<string>;
+};
+export const V2TurnStartResponse__MemoryCitation = Schema.Struct({
+  entries: Schema.Array(V2TurnStartResponse__MemoryCitationEntry),
+  threadIds: Schema.Array(Schema.String),
+});
+
+export type V2TurnStartResponse__CodexErrorInfo =
+  | "contextWindowExceeded"
+  | "usageLimitExceeded"
+  | "serverOverloaded"
+  | "cyberPolicy"
+  | "internalServerError"
+  | "unauthorized"
+  | "badRequest"
+  | "threadRollbackFailed"
+  | "sandboxError"
+  | "other"
+  | { readonly httpConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamConnectionFailed: { readonly httpStatusCode?: number | null } }
+  | { readonly responseStreamDisconnected: { readonly httpStatusCode?: number | null } }
+  | { readonly responseTooManyFailedAttempts: { readonly httpStatusCode?: number | null } }
+  | {
+      readonly activeTurnNotSteerable: {
+        readonly turnKind: V2TurnStartResponse__NonSteerableTurnKind;
+      };
+    };
+export const V2TurnStartResponse__CodexErrorInfo = Schema.Union(
+  [
+    Schema.Literals([
+      "contextWindowExceeded",
+      "usageLimitExceeded",
+      "serverOverloaded",
+      "cyberPolicy",
+      "internalServerError",
+      "unauthorized",
+      "badRequest",
+      "threadRollbackFailed",
+      "sandboxError",
+      "other",
+    ]),
+    Schema.Struct({
+      httpConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({ title: "HttpConnectionFailedCodexErrorInfo" }),
+    Schema.Struct({
+      responseStreamConnectionFailed: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamConnectionFailedCodexErrorInfo",
+      description: "Failed to connect to the response SSE stream.",
+    }),
+    Schema.Struct({
+      responseStreamDisconnected: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseStreamDisconnectedCodexErrorInfo",
+      description:
+        "The response SSE stream disconnected in the middle of a turn before completion.",
+    }),
+    Schema.Struct({
+      responseTooManyFailedAttempts: Schema.Struct({
+        httpStatusCode: Schema.optionalKey(
+          Schema.Union([
+            Schema.Number.annotate({ format: "uint16" })
+              .check(Schema.isInt())
+              .check(Schema.isGreaterThanOrEqualTo(0)),
+            Schema.Null,
+          ]),
+        ),
+      }),
+    }).annotate({
+      title: "ResponseTooManyFailedAttemptsCodexErrorInfo",
+      description: "Reached the retry limit for responses.",
+    }),
+    Schema.Struct({
+      activeTurnNotSteerable: Schema.Struct({
+        turnKind: V2TurnStartResponse__NonSteerableTurnKind,
+      }),
+    }).annotate({
+      title: "ActiveTurnNotSteerableCodexErrorInfo",
+      description:
+        "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  description:
+    "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+});
+
+export type V2TurnStartResponse__FileUpdateChange = {
+  readonly diff: string;
+  readonly kind: V2TurnStartResponse__PatchChangeKind;
+  readonly path: string;
+};
+export const V2TurnStartResponse__FileUpdateChange = Schema.Struct({
+  diff: Schema.String,
+  kind: V2TurnStartResponse__PatchChangeKind,
+  path: Schema.String,
+});
+
+export type V2TurnStartResponse__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2TurnStartResponse__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2TurnStartResponse__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2TurnStartResponse__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnSteerParams__UserInput =
+  | {
+      readonly text: string;
+      readonly text_elements?: ReadonlyArray<V2TurnSteerParams__TextElement>;
+      readonly type: "text";
+    }
+  | { readonly type: "image"; readonly url: string }
+  | { readonly path: string; readonly type: "localImage" }
+  | { readonly name: string; readonly path: string; readonly type: "skill" }
+  | { readonly name: string; readonly path: string; readonly type: "mention" };
+export const V2TurnSteerParams__UserInput = Schema.Union(
+  [
+    Schema.Struct({
+      text: Schema.String,
+      text_elements: Schema.optionalKey(
+        Schema.Array(V2TurnSteerParams__TextElement).annotate({
+          description: "UI-defined spans within `text` used to render or persist special elements.",
+          default: [],
+        }),
+      ),
+      type: Schema.Literal("text").annotate({ title: "TextUserInputType" }),
+    }).annotate({ title: "TextUserInput" }),
+    Schema.Struct({
+      type: Schema.Literal("image").annotate({ title: "ImageUserInputType" }),
+      url: Schema.String,
+    }).annotate({ title: "ImageUserInput" }),
+    Schema.Struct({
+      path: Schema.String,
+      type: Schema.Literal("localImage").annotate({ title: "LocalImageUserInputType" }),
+    }).annotate({ title: "LocalImageUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("skill").annotate({ title: "SkillUserInputType" }),
+    }).annotate({ title: "SkillUserInput" }),
+    Schema.Struct({
+      name: Schema.String,
+      path: Schema.String,
+      type: Schema.Literal("mention").annotate({ title: "MentionUserInputType" }),
+    }).annotate({ title: "MentionUserInput" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ApplyPatchApprovalResponse__ReviewDecision =
+  | "approved"
+  | {
+      readonly approved_execpolicy_amendment: {
+        readonly proposed_execpolicy_amendment: ReadonlyArray<string>;
+      };
+    }
+  | "approved_for_session"
+  | {
+      readonly network_policy_amendment: {
+        readonly network_policy_amendment: ApplyPatchApprovalResponse__NetworkPolicyAmendment;
+      };
+    }
+  | "denied"
+  | "timed_out"
+  | "abort";
+export const ApplyPatchApprovalResponse__ReviewDecision = Schema.Union(
+  [
+    Schema.Literal("approved").annotate({
+      description: "User has approved this command and the agent should execute it.",
+    }),
+    Schema.Struct({
+      approved_execpolicy_amendment: Schema.Struct({
+        proposed_execpolicy_amendment: Schema.Array(Schema.String),
+      }),
+    }).annotate({
+      title: "ApprovedExecpolicyAmendmentReviewDecision",
+      description:
+        "User has approved this command and wants to apply the proposed execpolicy amendment so future matching commands are permitted.",
+    }),
+    Schema.Literal("approved_for_session").annotate({
+      description:
+        "User has approved this request and wants future prompts in the same session-scoped approval cache to be automatically approved for the remainder of the session.",
+    }),
+    Schema.Struct({
+      network_policy_amendment: Schema.Struct({
+        network_policy_amendment: ApplyPatchApprovalResponse__NetworkPolicyAmendment,
+      }),
+    }).annotate({
+      title: "NetworkPolicyAmendmentReviewDecision",
+      description:
+        "User chose to persist a network policy rule (allow/deny) for future requests to the same host.",
+    }),
+    Schema.Literal("denied").annotate({
+      description:
+        "User has denied this command and the agent should not execute it, but it should continue the session and try something else.",
+    }),
+    Schema.Literal("timed_out").annotate({
+      description: "Automatic approval review timed out before reaching a decision.",
+    }),
+    Schema.Literal("abort").annotate({
+      description:
+        "User has denied this command and the agent should not do anything until the user's next command.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({ description: "User's decision in response to an ExecApprovalRequest." });
+
+export type ClientRequest__CommandExecParams = {
+  readonly command: ReadonlyArray<string>;
+  readonly cwd?: string | null;
+  readonly disableOutputCap?: boolean;
+  readonly disableTimeout?: boolean;
+  readonly env?: { readonly [x: string]: string | null } | null;
+  readonly outputBytesCap?: number | null;
+  readonly processId?: string | null;
+  readonly sandboxPolicy?: ClientRequest__SandboxPolicy | null;
+  readonly size?: ClientRequest__CommandExecTerminalSize | null;
+  readonly streamStdin?: boolean;
+  readonly streamStdoutStderr?: boolean;
+  readonly timeoutMs?: number | null;
+  readonly tty?: boolean;
+};
+export const ClientRequest__CommandExecParams = Schema.Struct({
+  command: Schema.Array(Schema.String).annotate({
+    description: "Command argv vector. Empty arrays are rejected.",
+  }),
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional working directory. Defaults to the server cwd.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  disableOutputCap: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Disable stdout/stderr capture truncation for this request.\n\nCannot be combined with `outputBytesCap`.",
+    }),
+  ),
+  disableTimeout: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Disable the timeout entirely for this request.\n\nCannot be combined with `timeoutMs`.",
+    }),
+  ),
+  env: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Null])).annotate({
+        description:
+          "Optional environment overrides merged into the server-computed environment.\n\nMatching names override inherited values. Set a key to `null` to unset an inherited variable.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  outputBytesCap: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description:
+          "Optional per-stream stdout/stderr capture cap in bytes.\n\nWhen omitted, the server default applies. Cannot be combined with `disableOutputCap`.",
+        format: "uint",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  processId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional client-supplied, connection-scoped process id.\n\nRequired for `tty`, `streamStdin`, `streamStdoutStderr`, and follow-up `command/exec/write`, `command/exec/resize`, and `command/exec/terminate` calls. When omitted, buffered execution gets an internal id that is not exposed to the client.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sandboxPolicy: Schema.optionalKey(
+    Schema.Union([ClientRequest__SandboxPolicy, Schema.Null]).annotate({
+      description:
+        "Optional sandbox policy for this command.\n\nUses the same shape as thread/turn execution sandbox configuration and defaults to the user's configured policy when omitted. Cannot be combined with `permissionProfile`.",
+    }),
+  ),
+  size: Schema.optionalKey(
+    Schema.Union([ClientRequest__CommandExecTerminalSize, Schema.Null]).annotate({
+      description: "Optional initial PTY size in character cells. Only valid when `tty` is true.",
+    }),
+  ),
+  streamStdin: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Allow follow-up `command/exec/write` requests to write stdin bytes.\n\nRequires a client-supplied `processId`.",
+    }),
+  ),
+  streamStdoutStderr: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Stream stdout/stderr via `command/exec/outputDelta` notifications.\n\nStreamed bytes are not duplicated into the final response and require a client-supplied `processId`.",
+    }),
+  ),
+  timeoutMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description:
+          "Optional timeout in milliseconds.\n\nWhen omitted, the server default applies. Cannot be combined with `disableTimeout`.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  tty: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Enable PTY mode.\n\nThis implies `streamStdin` and `streamStdoutStderr`.",
+    }),
+  ),
+}).annotate({
+  description:
+    "Run a standalone command (argv vector) in the server sandbox without creating a thread or turn.\n\nThe final `command/exec` response is deferred until the process exits and is sent only after all `command/exec/outputDelta` notifications for that connection have been emitted.",
+});
+
+export type ClientRequest__FileSystemSandboxEntry = {
+  readonly access: ClientRequest__FileSystemAccessMode;
+  readonly path: ClientRequest__FileSystemPath;
+};
+export const ClientRequest__FileSystemSandboxEntry = Schema.Struct({
+  access: ClientRequest__FileSystemAccessMode,
+  path: ClientRequest__FileSystemPath,
+});
+
+export type ClientRequest__FunctionCallOutputBody =
+  | string
+  | ReadonlyArray<ClientRequest__FunctionCallOutputContentItem>;
+export const ClientRequest__FunctionCallOutputBody = Schema.Union([
+  Schema.String,
+  Schema.Array(ClientRequest__FunctionCallOutputContentItem),
+]);
+
+export type ClientRequest__ConfigBatchWriteParams = {
+  readonly edits: ReadonlyArray<ClientRequest__ConfigEdit>;
+  readonly expectedVersion?: string | null;
+  readonly filePath?: string | null;
+  readonly reloadUserConfig?: boolean;
+};
+export const ClientRequest__ConfigBatchWriteParams = Schema.Struct({
+  edits: Schema.Array(ClientRequest__ConfigEdit),
+  expectedVersion: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  filePath: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Path to the config file to write; defaults to the user's `config.toml` when omitted.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reloadUserConfig: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "When true, hot-reload the updated user config into all loaded threads after writing.",
+    }),
+  ),
+});
+
+export type ClientRequest__PluginShareSaveParams = {
+  readonly discoverability?: ClientRequest__PluginShareDiscoverability | null;
+  readonly pluginPath: ClientRequest__AbsolutePathBuf;
+  readonly remotePluginId?: string | null;
+  readonly shareTargets?: ReadonlyArray<ClientRequest__PluginShareTarget> | null;
+};
+export const ClientRequest__PluginShareSaveParams = Schema.Struct({
+  discoverability: Schema.optionalKey(
+    Schema.Union([ClientRequest__PluginShareDiscoverability, Schema.Null]),
+  ),
+  pluginPath: ClientRequest__AbsolutePathBuf,
+  remotePluginId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  shareTargets: Schema.optionalKey(
+    Schema.Union([Schema.Array(ClientRequest__PluginShareTarget), Schema.Null]),
+  ),
+});
+
+export type ClientRequest__PluginShareUpdateTargetsParams = {
+  readonly remotePluginId: string;
+  readonly shareTargets: ReadonlyArray<ClientRequest__PluginShareTarget>;
+};
+export const ClientRequest__PluginShareUpdateTargetsParams = Schema.Struct({
+  remotePluginId: Schema.String,
+  shareTargets: Schema.Array(ClientRequest__PluginShareTarget),
+});
+
+export type ClientRequest__ExternalAgentConfigMigrationItem = {
+  readonly cwd?: string | null;
+  readonly description: string;
+  readonly details?: ClientRequest__MigrationDetails | null;
+  readonly itemType: ClientRequest__ExternalAgentConfigMigrationItemType;
+};
+export const ClientRequest__ExternalAgentConfigMigrationItem = Schema.Struct({
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Null or empty means home-scoped migration; non-empty means repo-scoped migration.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.String,
+  details: Schema.optionalKey(Schema.Union([ClientRequest__MigrationDetails, Schema.Null])),
+  itemType: ClientRequest__ExternalAgentConfigMigrationItemType,
+});
+
+export type ClientRequest__TurnStartParams = {
+  readonly approvalPolicy?: ClientRequest__AskForApproval | null;
+  readonly approvalsReviewer?: ClientRequest__ApprovalsReviewer | null;
+  readonly cwd?: string | null;
+  readonly effort?: ClientRequest__ReasoningEffort | null;
+  readonly input: ReadonlyArray<ClientRequest__UserInput>;
+  readonly model?: string | null;
+  readonly outputSchema?: unknown;
+  readonly personality?: ClientRequest__Personality | null;
+  readonly sandboxPolicy?: ClientRequest__SandboxPolicy | null;
+  readonly serviceTier?: string | null;
+  readonly summary?: ClientRequest__ReasoningSummary | null;
+  readonly threadId: string;
+};
+export const ClientRequest__TurnStartParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(
+    Schema.Union([ClientRequest__AskForApproval, Schema.Null]).annotate({
+      description: "Override the approval policy for this turn and subsequent turns.",
+    }),
+  ),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([ClientRequest__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this turn and subsequent turns.",
+    }),
+  ),
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Override the working directory for this turn and subsequent turns.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  effort: Schema.optionalKey(
+    Schema.Union([ClientRequest__ReasoningEffort, Schema.Null]).annotate({
+      description: "Override the reasoning effort for this turn and subsequent turns.",
+    }),
+  ),
+  input: Schema.Array(ClientRequest__UserInput),
+  model: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Override the model for this turn and subsequent turns.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  outputSchema: Schema.optionalKey(
+    Schema.Unknown.annotate({
+      description:
+        "Optional JSON Schema used to constrain the final assistant message for this turn.",
+    }),
+  ),
+  personality: Schema.optionalKey(
+    Schema.Union([ClientRequest__Personality, Schema.Null]).annotate({
+      description: "Override the personality for this turn and subsequent turns.",
+    }),
+  ),
+  sandboxPolicy: Schema.optionalKey(
+    Schema.Union([ClientRequest__SandboxPolicy, Schema.Null]).annotate({
+      description: "Override the sandbox policy for this turn and subsequent turns.",
+    }),
+  ),
+  serviceTier: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Override the service tier for this turn and subsequent turns.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  summary: Schema.optionalKey(
+    Schema.Union([ClientRequest__ReasoningSummary, Schema.Null]).annotate({
+      description: "Override the reasoning summary for this turn and subsequent turns.",
+    }),
+  ),
+  threadId: Schema.String,
+});
+
+export type ClientRequest__TurnSteerParams = {
+  readonly expectedTurnId: string;
+  readonly input: ReadonlyArray<ClientRequest__UserInput>;
+  readonly threadId: string;
+};
+export const ClientRequest__TurnSteerParams = Schema.Struct({
+  expectedTurnId: Schema.String.annotate({
+    description:
+      "Required active turn id precondition. The request fails when it does not match the currently active turn.",
+  }),
+  input: Schema.Array(ClientRequest__UserInput),
+  threadId: Schema.String,
+});
+
+export type CommandExecutionRequestApprovalParams__FileSystemSandboxEntry = {
+  readonly access: CommandExecutionRequestApprovalParams__FileSystemAccessMode;
+  readonly path: CommandExecutionRequestApprovalParams__FileSystemPath;
+};
+export const CommandExecutionRequestApprovalParams__FileSystemSandboxEntry = Schema.Struct({
+  access: CommandExecutionRequestApprovalParams__FileSystemAccessMode,
+  path: CommandExecutionRequestApprovalParams__FileSystemPath,
+});
+
+export type CommandExecutionRequestApprovalResponse__CommandExecutionApprovalDecision =
+  | "accept"
+  | "acceptForSession"
+  | {
+      readonly acceptWithExecpolicyAmendment: {
+        readonly execpolicy_amendment: ReadonlyArray<string>;
+      };
+    }
+  | {
+      readonly applyNetworkPolicyAmendment: {
+        readonly network_policy_amendment: CommandExecutionRequestApprovalResponse__NetworkPolicyAmendment;
+      };
+    }
+  | "decline"
+  | "cancel";
+export const CommandExecutionRequestApprovalResponse__CommandExecutionApprovalDecision =
+  Schema.Union(
+    [
+      Schema.Literal("accept").annotate({ description: "User approved the command." }),
+      Schema.Literal("acceptForSession").annotate({
+        description:
+          "User approved the command and future prompts in the same session-scoped approval cache should run without prompting.",
+      }),
+      Schema.Struct({
+        acceptWithExecpolicyAmendment: Schema.Struct({
+          execpolicy_amendment: Schema.Array(Schema.String),
+        }),
+      }).annotate({
+        title: "AcceptWithExecpolicyAmendmentCommandExecutionApprovalDecision",
+        description:
+          "User approved the command, and wants to apply the proposed execpolicy amendment so future matching commands can run without prompting.",
+      }),
+      Schema.Struct({
+        applyNetworkPolicyAmendment: Schema.Struct({
+          network_policy_amendment: CommandExecutionRequestApprovalResponse__NetworkPolicyAmendment,
+        }),
+      }).annotate({
+        title: "ApplyNetworkPolicyAmendmentCommandExecutionApprovalDecision",
+        description: "User chose a persistent network policy rule (allow/deny) for this host.",
+      }),
+      Schema.Literal("decline").annotate({
+        description: "User denied the command. The agent will continue the turn.",
+      }),
+      Schema.Literal("cancel").annotate({
+        description: "User denied the command. The turn will also be immediately interrupted.",
+      }),
+    ],
+    { mode: "oneOf" },
+  );
+
+export type ExecCommandApprovalResponse__ReviewDecision =
+  | "approved"
+  | {
+      readonly approved_execpolicy_amendment: {
+        readonly proposed_execpolicy_amendment: ReadonlyArray<string>;
+      };
+    }
+  | "approved_for_session"
+  | {
+      readonly network_policy_amendment: {
+        readonly network_policy_amendment: ExecCommandApprovalResponse__NetworkPolicyAmendment;
+      };
+    }
+  | "denied"
+  | "timed_out"
+  | "abort";
+export const ExecCommandApprovalResponse__ReviewDecision = Schema.Union(
+  [
+    Schema.Literal("approved").annotate({
+      description: "User has approved this command and the agent should execute it.",
+    }),
+    Schema.Struct({
+      approved_execpolicy_amendment: Schema.Struct({
+        proposed_execpolicy_amendment: Schema.Array(Schema.String),
+      }),
+    }).annotate({
+      title: "ApprovedExecpolicyAmendmentReviewDecision",
+      description:
+        "User has approved this command and wants to apply the proposed execpolicy amendment so future matching commands are permitted.",
+    }),
+    Schema.Literal("approved_for_session").annotate({
+      description:
+        "User has approved this request and wants future prompts in the same session-scoped approval cache to be automatically approved for the remainder of the session.",
+    }),
+    Schema.Struct({
+      network_policy_amendment: Schema.Struct({
+        network_policy_amendment: ExecCommandApprovalResponse__NetworkPolicyAmendment,
+      }),
+    }).annotate({
+      title: "NetworkPolicyAmendmentReviewDecision",
+      description:
+        "User chose to persist a network policy rule (allow/deny) for future requests to the same host.",
+    }),
+    Schema.Literal("denied").annotate({
+      description:
+        "User has denied this command and the agent should not execute it, but it should continue the session and try something else.",
+    }),
+    Schema.Literal("timed_out").annotate({
+      description: "Automatic approval review timed out before reaching a decision.",
+    }),
+    Schema.Literal("abort").annotate({
+      description:
+        "User has denied this command and the agent should not do anything until the user's next command.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({ description: "User's decision in response to an ExecApprovalRequest." });
+
+export type McpServerElicitationRequestParams__McpElicitationTitledMultiSelectEnumSchema = {
+  readonly default?: ReadonlyArray<string> | null;
+  readonly description?: string | null;
+  readonly items: McpServerElicitationRequestParams__McpElicitationTitledEnumItems;
+  readonly maxItems?: number | null;
+  readonly minItems?: number | null;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationArrayType;
+};
+export const McpServerElicitationRequestParams__McpElicitationTitledMultiSelectEnumSchema =
+  Schema.Struct({
+    default: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+    description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    items: McpServerElicitationRequestParams__McpElicitationTitledEnumItems,
+    maxItems: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint64" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        Schema.Null,
+      ]),
+    ),
+    minItems: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint64" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        Schema.Null,
+      ]),
+    ),
+    title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    type: McpServerElicitationRequestParams__McpElicitationArrayType,
+  });
+
+export type McpServerElicitationRequestParams__McpElicitationUntitledMultiSelectEnumSchema = {
+  readonly default?: ReadonlyArray<string> | null;
+  readonly description?: string | null;
+  readonly items: McpServerElicitationRequestParams__McpElicitationUntitledEnumItems;
+  readonly maxItems?: number | null;
+  readonly minItems?: number | null;
+  readonly title?: string | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationArrayType;
+};
+export const McpServerElicitationRequestParams__McpElicitationUntitledMultiSelectEnumSchema =
+  Schema.Struct({
+    default: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+    description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    items: McpServerElicitationRequestParams__McpElicitationUntitledEnumItems,
+    maxItems: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint64" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        Schema.Null,
+      ]),
+    ),
+    minItems: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint64" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        Schema.Null,
+      ]),
+    ),
+    title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    type: McpServerElicitationRequestParams__McpElicitationArrayType,
+  });
+
+export type McpServerElicitationRequestParams__McpElicitationSingleSelectEnumSchema =
+  | McpServerElicitationRequestParams__McpElicitationUntitledSingleSelectEnumSchema
+  | McpServerElicitationRequestParams__McpElicitationTitledSingleSelectEnumSchema;
+export const McpServerElicitationRequestParams__McpElicitationSingleSelectEnumSchema = Schema.Union(
+  [
+    McpServerElicitationRequestParams__McpElicitationUntitledSingleSelectEnumSchema,
+    McpServerElicitationRequestParams__McpElicitationTitledSingleSelectEnumSchema,
+  ],
+);
+
+export type PermissionsRequestApprovalParams__FileSystemSandboxEntry = {
+  readonly access: PermissionsRequestApprovalParams__FileSystemAccessMode;
+  readonly path: PermissionsRequestApprovalParams__FileSystemPath;
+};
+export const PermissionsRequestApprovalParams__FileSystemSandboxEntry = Schema.Struct({
+  access: PermissionsRequestApprovalParams__FileSystemAccessMode,
+  path: PermissionsRequestApprovalParams__FileSystemPath,
+});
+
+export type PermissionsRequestApprovalResponse__FileSystemSandboxEntry = {
+  readonly access: PermissionsRequestApprovalResponse__FileSystemAccessMode;
+  readonly path: PermissionsRequestApprovalResponse__FileSystemPath;
+};
+export const PermissionsRequestApprovalResponse__FileSystemSandboxEntry = Schema.Struct({
+  access: PermissionsRequestApprovalResponse__FileSystemAccessMode,
+  path: PermissionsRequestApprovalResponse__FileSystemPath,
+});
+
+export type ServerNotification__AppInfo = {
+  readonly appMetadata?: ServerNotification__AppMetadata | null;
+  readonly branding?: ServerNotification__AppBranding | null;
+  readonly description?: string | null;
+  readonly distributionChannel?: string | null;
+  readonly id: string;
+  readonly installUrl?: string | null;
+  readonly isAccessible?: boolean;
+  readonly isEnabled?: boolean;
+  readonly labels?: { readonly [x: string]: string } | null;
+  readonly logoUrl?: string | null;
+  readonly logoUrlDark?: string | null;
+  readonly name: string;
+  readonly pluginDisplayNames?: ReadonlyArray<string>;
+};
+export const ServerNotification__AppInfo = Schema.Struct({
+  appMetadata: Schema.optionalKey(Schema.Union([ServerNotification__AppMetadata, Schema.Null])),
+  branding: Schema.optionalKey(Schema.Union([ServerNotification__AppBranding, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  distributionChannel: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  id: Schema.String,
+  installUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  isAccessible: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  isEnabled: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Whether this app is enabled in config.toml. Example: ```toml [apps.bad_app] enabled = false ```",
+      default: true,
+    }),
+  ),
+  labels: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+  ),
+  logoUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  logoUrlDark: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  pluginDisplayNames: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+}).annotate({ description: "EXPERIMENTAL - app metadata returned by app-list APIs." });
+
+export type ServerNotification__FileSystemSandboxEntry = {
+  readonly access: ServerNotification__FileSystemAccessMode;
+  readonly path: ServerNotification__FileSystemPath;
+};
+export const ServerNotification__FileSystemSandboxEntry = Schema.Struct({
+  access: ServerNotification__FileSystemAccessMode,
+  path: ServerNotification__FileSystemPath,
+});
+
+export type ServerNotification__FuzzyFileSearchSessionUpdatedNotification = {
+  readonly files: ReadonlyArray<ServerNotification__FuzzyFileSearchResult>;
+  readonly query: string;
+  readonly sessionId: string;
+};
+export const ServerNotification__FuzzyFileSearchSessionUpdatedNotification = Schema.Struct({
+  files: Schema.Array(ServerNotification__FuzzyFileSearchResult),
+  query: Schema.String,
+  sessionId: Schema.String,
+});
+
+export type ServerNotification__HookRunSummary = {
+  readonly completedAt?: number | null;
+  readonly displayOrder: number;
+  readonly durationMs?: number | null;
+  readonly entries: ReadonlyArray<ServerNotification__HookOutputEntry>;
+  readonly eventName: ServerNotification__HookEventName;
+  readonly executionMode: ServerNotification__HookExecutionMode;
+  readonly handlerType: ServerNotification__HookHandlerType;
+  readonly id: string;
+  readonly scope: ServerNotification__HookScope;
+  readonly source?:
+    | "system"
+    | "user"
+    | "project"
+    | "mdm"
+    | "sessionFlags"
+    | "plugin"
+    | "cloudRequirements"
+    | "legacyManagedConfigFile"
+    | "legacyManagedConfigMdm"
+    | "unknown";
+  readonly sourcePath: ServerNotification__AbsolutePathBuf;
+  readonly startedAt: number;
+  readonly status: ServerNotification__HookRunStatus;
+  readonly statusMessage?: string | null;
+};
+export const ServerNotification__HookRunSummary = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  displayOrder: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  durationMs: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  entries: Schema.Array(ServerNotification__HookOutputEntry),
+  eventName: ServerNotification__HookEventName,
+  executionMode: ServerNotification__HookExecutionMode,
+  handlerType: ServerNotification__HookHandlerType,
+  id: Schema.String,
+  scope: ServerNotification__HookScope,
+  source: Schema.optionalKey(
+    Schema.Literals([
+      "system",
+      "user",
+      "project",
+      "mdm",
+      "sessionFlags",
+      "plugin",
+      "cloudRequirements",
+      "legacyManagedConfigFile",
+      "legacyManagedConfigMdm",
+      "unknown",
+    ]).annotate({ default: "unknown" }),
+  ),
+  sourcePath: ServerNotification__AbsolutePathBuf,
+  startedAt: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  status: ServerNotification__HookRunStatus,
+  statusMessage: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerNotification__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: ServerNotification__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const ServerNotification__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([ServerNotification__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type ServerNotification__FileChangePatchUpdatedNotification = {
+  readonly changes: ReadonlyArray<ServerNotification__FileUpdateChange>;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__FileChangePatchUpdatedNotification = Schema.Struct({
+  changes: Schema.Array(ServerNotification__FileUpdateChange),
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__AccountRateLimitsUpdatedNotification = {
+  readonly rateLimits: ServerNotification__RateLimitSnapshot;
+};
+export const ServerNotification__AccountRateLimitsUpdatedNotification = Schema.Struct({
+  rateLimits: ServerNotification__RateLimitSnapshot,
+});
+
+export type ServerNotification__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<ServerNotification__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<ServerNotification__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: ServerNotification__MemoryCitation | null;
+      readonly phase?: ServerNotification__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<ServerNotification__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: ServerNotification__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<ServerNotification__FileUpdateChange>;
+      readonly id: string;
+      readonly status: ServerNotification__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: ServerNotification__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: ServerNotification__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: ServerNotification__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<ServerNotification__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: ServerNotification__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: ServerNotification__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: ServerNotification__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: ServerNotification__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: ServerNotification__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: ServerNotification__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const ServerNotification__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(ServerNotification__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(ServerNotification__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([ServerNotification__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([ServerNotification__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(ServerNotification__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: ServerNotification__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(ServerNotification__FileUpdateChange),
+      id: Schema.String,
+      status: ServerNotification__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(Schema.Union([ServerNotification__McpToolCallError, Schema.Null])),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([ServerNotification__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: ServerNotification__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(ServerNotification__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: ServerNotification__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, ServerNotification__CollabAgentState).annotate({
+        description: "Last known status of the target agents, when available.",
+      }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([ServerNotification__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(Schema.Union([ServerNotification__WebSearchAction, Schema.Null])),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: ServerNotification__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([ServerNotification__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__ConfigWarningNotification = {
+  readonly details?: string | null;
+  readonly path?: string | null;
+  readonly range?: ServerNotification__TextRange | null;
+  readonly summary: string;
+};
+export const ServerNotification__ConfigWarningNotification = Schema.Struct({
+  details: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional extra guidance or error details." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional path to the config file that triggered the warning.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  range: Schema.optionalKey(
+    Schema.Union([ServerNotification__TextRange, Schema.Null]).annotate({
+      description: "Optional range for the error location inside the config file.",
+    }),
+  ),
+  summary: Schema.String.annotate({ description: "Concise summary of the warning." }),
+});
+
+export type ServerNotification__ThreadStatusChangedNotification = {
+  readonly status: ServerNotification__ThreadStatus;
+  readonly threadId: string;
+};
+export const ServerNotification__ThreadStatusChangedNotification = Schema.Struct({
+  status: ServerNotification__ThreadStatus,
+  threadId: Schema.String,
+});
+
+export type ServerNotification__ThreadGoalUpdatedNotification = {
+  readonly goal: ServerNotification__ThreadGoal;
+  readonly threadId: string;
+  readonly turnId?: string | null;
+};
+export const ServerNotification__ThreadGoalUpdatedNotification = Schema.Struct({
+  goal: ServerNotification__ThreadGoal,
+  threadId: Schema.String,
+  turnId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerNotification__ThreadTokenUsageUpdatedNotification = {
+  readonly threadId: string;
+  readonly tokenUsage: ServerNotification__ThreadTokenUsage;
+  readonly turnId: string;
+};
+export const ServerNotification__ThreadTokenUsageUpdatedNotification = Schema.Struct({
+  threadId: Schema.String,
+  tokenUsage: ServerNotification__ThreadTokenUsage,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__TurnPlanUpdatedNotification = {
+  readonly explanation?: string | null;
+  readonly plan: ReadonlyArray<ServerNotification__TurnPlanStep>;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__TurnPlanUpdatedNotification = Schema.Struct({
+  explanation: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  plan: Schema.Array(ServerNotification__TurnPlanStep),
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerRequest__FileSystemSandboxEntry = {
+  readonly access: ServerRequest__FileSystemAccessMode;
+  readonly path: ServerRequest__FileSystemPath;
+};
+export const ServerRequest__FileSystemSandboxEntry = Schema.Struct({
+  access: ServerRequest__FileSystemAccessMode,
+  path: ServerRequest__FileSystemPath,
+});
+
+export type ServerRequest__McpElicitationTitledMultiSelectEnumSchema = {
+  readonly default?: ReadonlyArray<string> | null;
+  readonly description?: string | null;
+  readonly items: ServerRequest__McpElicitationTitledEnumItems;
+  readonly maxItems?: number | null;
+  readonly minItems?: number | null;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationArrayType;
+};
+export const ServerRequest__McpElicitationTitledMultiSelectEnumSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  items: ServerRequest__McpElicitationTitledEnumItems,
+  maxItems: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint64" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  minItems: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint64" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationArrayType,
+});
+
+export type ServerRequest__McpElicitationUntitledMultiSelectEnumSchema = {
+  readonly default?: ReadonlyArray<string> | null;
+  readonly description?: string | null;
+  readonly items: ServerRequest__McpElicitationUntitledEnumItems;
+  readonly maxItems?: number | null;
+  readonly minItems?: number | null;
+  readonly title?: string | null;
+  readonly type: ServerRequest__McpElicitationArrayType;
+};
+export const ServerRequest__McpElicitationUntitledMultiSelectEnumSchema = Schema.Struct({
+  default: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  items: ServerRequest__McpElicitationUntitledEnumItems,
+  maxItems: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint64" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  minItems: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint64" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  title: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  type: ServerRequest__McpElicitationArrayType,
+});
+
+export type ServerRequest__McpElicitationSingleSelectEnumSchema =
+  | ServerRequest__McpElicitationUntitledSingleSelectEnumSchema
+  | ServerRequest__McpElicitationTitledSingleSelectEnumSchema;
+export const ServerRequest__McpElicitationSingleSelectEnumSchema = Schema.Union([
+  ServerRequest__McpElicitationUntitledSingleSelectEnumSchema,
+  ServerRequest__McpElicitationTitledSingleSelectEnumSchema,
+]);
+
+export type ServerRequest__CommandExecutionRequestApprovalParams = {
+  readonly approvalId?: string | null;
+  readonly command?: string | null;
+  readonly commandActions?: ReadonlyArray<ServerRequest__CommandAction> | null;
+  readonly cwd?: ServerRequest__AbsolutePathBuf | null;
+  readonly itemId: string;
+  readonly networkApprovalContext?: ServerRequest__NetworkApprovalContext | null;
+  readonly proposedExecpolicyAmendment?: ReadonlyArray<string> | null;
+  readonly proposedNetworkPolicyAmendments?: ReadonlyArray<ServerRequest__NetworkPolicyAmendment> | null;
+  readonly reason?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerRequest__CommandExecutionRequestApprovalParams = Schema.Struct({
+  approvalId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Unique identifier for this specific approval callback.\n\nFor regular shell/unified_exec approvals, this is null.\n\nFor zsh-exec-bridge subcommand approvals, multiple callbacks can belong to one parent `itemId`, so `approvalId` is a distinct opaque callback id (a UUID) used to disambiguate routing.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  command: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "The command to be executed." }),
+      Schema.Null,
+    ]),
+  ),
+  commandActions: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ServerRequest__CommandAction).annotate({
+        description: "Best-effort parsed command actions for friendly display.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.optionalKey(
+    Schema.Union([ServerRequest__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "The command's working directory.",
+    }),
+  ),
+  itemId: Schema.String,
+  networkApprovalContext: Schema.optionalKey(
+    Schema.Union([ServerRequest__NetworkApprovalContext, Schema.Null]).annotate({
+      description: "Optional context for a managed-network approval prompt.",
+    }),
+  ),
+  proposedExecpolicyAmendment: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Optional proposed execpolicy amendment to allow similar commands without prompting.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  proposedNetworkPolicyAmendments: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ServerRequest__NetworkPolicyAmendment).annotate({
+        description:
+          "Optional proposed network policy amendments (allow/deny host) for future requests.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reason: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional explanatory reason (e.g. request for network access).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerRequest__ToolRequestUserInputParams = {
+  readonly itemId: string;
+  readonly questions: ReadonlyArray<ServerRequest__ToolRequestUserInputQuestion>;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerRequest__ToolRequestUserInputParams = Schema.Struct({
+  itemId: Schema.String,
+  questions: Schema.Array(ServerRequest__ToolRequestUserInputQuestion),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ description: "EXPERIMENTAL. Params sent with a request_user_input event." });
+
+export type V2AppListUpdatedNotification__AppInfo = {
+  readonly appMetadata?: V2AppListUpdatedNotification__AppMetadata | null;
+  readonly branding?: V2AppListUpdatedNotification__AppBranding | null;
+  readonly description?: string | null;
+  readonly distributionChannel?: string | null;
+  readonly id: string;
+  readonly installUrl?: string | null;
+  readonly isAccessible?: boolean;
+  readonly isEnabled?: boolean;
+  readonly labels?: { readonly [x: string]: string } | null;
+  readonly logoUrl?: string | null;
+  readonly logoUrlDark?: string | null;
+  readonly name: string;
+  readonly pluginDisplayNames?: ReadonlyArray<string>;
+};
+export const V2AppListUpdatedNotification__AppInfo = Schema.Struct({
+  appMetadata: Schema.optionalKey(
+    Schema.Union([V2AppListUpdatedNotification__AppMetadata, Schema.Null]),
+  ),
+  branding: Schema.optionalKey(
+    Schema.Union([V2AppListUpdatedNotification__AppBranding, Schema.Null]),
+  ),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  distributionChannel: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  id: Schema.String,
+  installUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  isAccessible: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  isEnabled: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Whether this app is enabled in config.toml. Example: ```toml [apps.bad_app] enabled = false ```",
+      default: true,
+    }),
+  ),
+  labels: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+  ),
+  logoUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  logoUrlDark: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  pluginDisplayNames: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+}).annotate({ description: "EXPERIMENTAL - app metadata returned by app-list APIs." });
+
+export type V2AppsListResponse__AppInfo = {
+  readonly appMetadata?: V2AppsListResponse__AppMetadata | null;
+  readonly branding?: V2AppsListResponse__AppBranding | null;
+  readonly description?: string | null;
+  readonly distributionChannel?: string | null;
+  readonly id: string;
+  readonly installUrl?: string | null;
+  readonly isAccessible?: boolean;
+  readonly isEnabled?: boolean;
+  readonly labels?: { readonly [x: string]: string } | null;
+  readonly logoUrl?: string | null;
+  readonly logoUrlDark?: string | null;
+  readonly name: string;
+  readonly pluginDisplayNames?: ReadonlyArray<string>;
+};
+export const V2AppsListResponse__AppInfo = Schema.Struct({
+  appMetadata: Schema.optionalKey(Schema.Union([V2AppsListResponse__AppMetadata, Schema.Null])),
+  branding: Schema.optionalKey(Schema.Union([V2AppsListResponse__AppBranding, Schema.Null])),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  distributionChannel: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  id: Schema.String,
+  installUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  isAccessible: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  isEnabled: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Whether this app is enabled in config.toml. Example: ```toml [apps.bad_app] enabled = false ```",
+      default: true,
+    }),
+  ),
+  labels: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+  ),
+  logoUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  logoUrlDark: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  pluginDisplayNames: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+}).annotate({ description: "EXPERIMENTAL - app metadata returned by app-list APIs." });
+
+export type V2CommandExecParams__FileSystemSandboxEntry = {
+  readonly access: V2CommandExecParams__FileSystemAccessMode;
+  readonly path: V2CommandExecParams__FileSystemPath;
+};
+export const V2CommandExecParams__FileSystemSandboxEntry = Schema.Struct({
+  access: V2CommandExecParams__FileSystemAccessMode,
+  path: V2CommandExecParams__FileSystemPath,
+});
+
+export type V2ConfigReadResponse__ConfigLayer = {
+  readonly config: unknown;
+  readonly disabledReason?: string | null;
+  readonly name: V2ConfigReadResponse__ConfigLayerSource;
+  readonly version: string;
+};
+export const V2ConfigReadResponse__ConfigLayer = Schema.Struct({
+  config: Schema.Unknown,
+  disabledReason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: V2ConfigReadResponse__ConfigLayerSource,
+  version: Schema.String,
+});
+
+export type V2ConfigReadResponse__ConfigLayerMetadata = {
+  readonly name: V2ConfigReadResponse__ConfigLayerSource;
+  readonly version: string;
+};
+export const V2ConfigReadResponse__ConfigLayerMetadata = Schema.Struct({
+  name: V2ConfigReadResponse__ConfigLayerSource,
+  version: Schema.String,
+});
+
+export type V2ConfigReadResponse__ToolsV2 = {
+  readonly view_image?: boolean | null;
+  readonly web_search?: V2ConfigReadResponse__WebSearchToolConfig | null;
+};
+export const V2ConfigReadResponse__ToolsV2 = Schema.Struct({
+  view_image: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  web_search: Schema.optionalKey(
+    Schema.Union([V2ConfigReadResponse__WebSearchToolConfig, Schema.Null]),
+  ),
+});
+
+export type V2ConfigWriteResponse__ConfigLayerMetadata = {
+  readonly name: V2ConfigWriteResponse__ConfigLayerSource;
+  readonly version: string;
+};
+export const V2ConfigWriteResponse__ConfigLayerMetadata = Schema.Struct({
+  name: V2ConfigWriteResponse__ConfigLayerSource,
+  version: Schema.String,
+});
+
+export type V2ErrorNotification__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ErrorNotification__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ErrorNotification__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ErrorNotification__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItem = {
+  readonly cwd?: string | null;
+  readonly description: string;
+  readonly details?: V2ExternalAgentConfigDetectResponse__MigrationDetails | null;
+  readonly itemType: V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItemType;
+};
+export const V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItem = Schema.Struct({
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Null or empty means home-scoped migration; non-empty means repo-scoped migration.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.String,
+  details: Schema.optionalKey(
+    Schema.Union([V2ExternalAgentConfigDetectResponse__MigrationDetails, Schema.Null]),
+  ),
+  itemType: V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItemType,
+});
+
+export type V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItem = {
+  readonly cwd?: string | null;
+  readonly description: string;
+  readonly details?: V2ExternalAgentConfigImportParams__MigrationDetails | null;
+  readonly itemType: V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItemType;
+};
+export const V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItem = Schema.Struct({
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Null or empty means home-scoped migration; non-empty means repo-scoped migration.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  description: Schema.String,
+  details: Schema.optionalKey(
+    Schema.Union([V2ExternalAgentConfigImportParams__MigrationDetails, Schema.Null]),
+  ),
+  itemType: V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItemType,
+});
+
+export type V2HookCompletedNotification__HookRunSummary = {
+  readonly completedAt?: number | null;
+  readonly displayOrder: number;
+  readonly durationMs?: number | null;
+  readonly entries: ReadonlyArray<V2HookCompletedNotification__HookOutputEntry>;
+  readonly eventName: V2HookCompletedNotification__HookEventName;
+  readonly executionMode: V2HookCompletedNotification__HookExecutionMode;
+  readonly handlerType: V2HookCompletedNotification__HookHandlerType;
+  readonly id: string;
+  readonly scope: V2HookCompletedNotification__HookScope;
+  readonly source?:
+    | "system"
+    | "user"
+    | "project"
+    | "mdm"
+    | "sessionFlags"
+    | "plugin"
+    | "cloudRequirements"
+    | "legacyManagedConfigFile"
+    | "legacyManagedConfigMdm"
+    | "unknown";
+  readonly sourcePath: V2HookCompletedNotification__AbsolutePathBuf;
+  readonly startedAt: number;
+  readonly status: V2HookCompletedNotification__HookRunStatus;
+  readonly statusMessage?: string | null;
+};
+export const V2HookCompletedNotification__HookRunSummary = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  displayOrder: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  durationMs: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  entries: Schema.Array(V2HookCompletedNotification__HookOutputEntry),
+  eventName: V2HookCompletedNotification__HookEventName,
+  executionMode: V2HookCompletedNotification__HookExecutionMode,
+  handlerType: V2HookCompletedNotification__HookHandlerType,
+  id: Schema.String,
+  scope: V2HookCompletedNotification__HookScope,
+  source: Schema.optionalKey(
+    Schema.Literals([
+      "system",
+      "user",
+      "project",
+      "mdm",
+      "sessionFlags",
+      "plugin",
+      "cloudRequirements",
+      "legacyManagedConfigFile",
+      "legacyManagedConfigMdm",
+      "unknown",
+    ]).annotate({ default: "unknown" }),
+  ),
+  sourcePath: V2HookCompletedNotification__AbsolutePathBuf,
+  startedAt: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  status: V2HookCompletedNotification__HookRunStatus,
+  statusMessage: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2HooksListResponse__HooksListEntry = {
+  readonly cwd: string;
+  readonly errors: ReadonlyArray<V2HooksListResponse__HookErrorInfo>;
+  readonly hooks: ReadonlyArray<V2HooksListResponse__HookMetadata>;
+  readonly warnings: ReadonlyArray<string>;
+};
+export const V2HooksListResponse__HooksListEntry = Schema.Struct({
+  cwd: Schema.String,
+  errors: Schema.Array(V2HooksListResponse__HookErrorInfo),
+  hooks: Schema.Array(V2HooksListResponse__HookMetadata),
+  warnings: Schema.Array(Schema.String),
+});
+
+export type V2HookStartedNotification__HookRunSummary = {
+  readonly completedAt?: number | null;
+  readonly displayOrder: number;
+  readonly durationMs?: number | null;
+  readonly entries: ReadonlyArray<V2HookStartedNotification__HookOutputEntry>;
+  readonly eventName: V2HookStartedNotification__HookEventName;
+  readonly executionMode: V2HookStartedNotification__HookExecutionMode;
+  readonly handlerType: V2HookStartedNotification__HookHandlerType;
+  readonly id: string;
+  readonly scope: V2HookStartedNotification__HookScope;
+  readonly source?:
+    | "system"
+    | "user"
+    | "project"
+    | "mdm"
+    | "sessionFlags"
+    | "plugin"
+    | "cloudRequirements"
+    | "legacyManagedConfigFile"
+    | "legacyManagedConfigMdm"
+    | "unknown";
+  readonly sourcePath: V2HookStartedNotification__AbsolutePathBuf;
+  readonly startedAt: number;
+  readonly status: V2HookStartedNotification__HookRunStatus;
+  readonly statusMessage?: string | null;
+};
+export const V2HookStartedNotification__HookRunSummary = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  displayOrder: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  durationMs: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+  entries: Schema.Array(V2HookStartedNotification__HookOutputEntry),
+  eventName: V2HookStartedNotification__HookEventName,
+  executionMode: V2HookStartedNotification__HookExecutionMode,
+  handlerType: V2HookStartedNotification__HookHandlerType,
+  id: Schema.String,
+  scope: V2HookStartedNotification__HookScope,
+  source: Schema.optionalKey(
+    Schema.Literals([
+      "system",
+      "user",
+      "project",
+      "mdm",
+      "sessionFlags",
+      "plugin",
+      "cloudRequirements",
+      "legacyManagedConfigFile",
+      "legacyManagedConfigMdm",
+      "unknown",
+    ]).annotate({ default: "unknown" }),
+  ),
+  sourcePath: V2HookStartedNotification__AbsolutePathBuf,
+  startedAt: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  status: V2HookStartedNotification__HookRunStatus,
+  statusMessage: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ItemCompletedNotification__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ItemCompletedNotification__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ItemCompletedNotification__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ItemCompletedNotification__MemoryCitation | null;
+      readonly phase?: V2ItemCompletedNotification__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ItemCompletedNotification__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ItemCompletedNotification__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ItemCompletedNotification__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ItemCompletedNotification__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ItemCompletedNotification__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ItemCompletedNotification__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ItemCompletedNotification__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ItemCompletedNotification__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ItemCompletedNotification__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: {
+        readonly [x: string]: V2ItemCompletedNotification__CollabAgentState;
+      };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ItemCompletedNotification__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ItemCompletedNotification__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ItemCompletedNotification__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ItemCompletedNotification__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ItemCompletedNotification__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ItemCompletedNotification__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ItemCompletedNotification__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ItemCompletedNotification__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2ItemCompletedNotification__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ItemCompletedNotification__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ItemCompletedNotification__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ItemCompletedNotification__FileUpdateChange),
+      id: Schema.String,
+      status: V2ItemCompletedNotification__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ItemCompletedNotification__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ItemCompletedNotification__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ItemCompletedNotification__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ItemCompletedNotification__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ItemCompletedNotification__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2ItemCompletedNotification__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ItemCompletedNotification__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ItemCompletedNotification__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ItemCompletedNotification__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ItemCompletedNotification__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSandboxEntry = {
+  readonly access: V2ItemGuardianApprovalReviewCompletedNotification__FileSystemAccessMode;
+  readonly path: V2ItemGuardianApprovalReviewCompletedNotification__FileSystemPath;
+};
+export const V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSandboxEntry =
+  Schema.Struct({
+    access: V2ItemGuardianApprovalReviewCompletedNotification__FileSystemAccessMode,
+    path: V2ItemGuardianApprovalReviewCompletedNotification__FileSystemPath,
+  });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__FileSystemSandboxEntry = {
+  readonly access: V2ItemGuardianApprovalReviewStartedNotification__FileSystemAccessMode;
+  readonly path: V2ItemGuardianApprovalReviewStartedNotification__FileSystemPath;
+};
+export const V2ItemGuardianApprovalReviewStartedNotification__FileSystemSandboxEntry =
+  Schema.Struct({
+    access: V2ItemGuardianApprovalReviewStartedNotification__FileSystemAccessMode,
+    path: V2ItemGuardianApprovalReviewStartedNotification__FileSystemPath,
+  });
+
+export type V2ItemStartedNotification__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ItemStartedNotification__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ItemStartedNotification__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ItemStartedNotification__MemoryCitation | null;
+      readonly phase?: V2ItemStartedNotification__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ItemStartedNotification__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ItemStartedNotification__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ItemStartedNotification__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ItemStartedNotification__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ItemStartedNotification__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ItemStartedNotification__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ItemStartedNotification__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ItemStartedNotification__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ItemStartedNotification__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ItemStartedNotification__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ItemStartedNotification__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ItemStartedNotification__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ItemStartedNotification__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ItemStartedNotification__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ItemStartedNotification__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ItemStartedNotification__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ItemStartedNotification__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ItemStartedNotification__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2ItemStartedNotification__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ItemStartedNotification__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ItemStartedNotification__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ItemStartedNotification__FileUpdateChange),
+      id: Schema.String,
+      status: V2ItemStartedNotification__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ItemStartedNotification__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ItemStartedNotification__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ItemStartedNotification__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ItemStartedNotification__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ItemStartedNotification__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2ItemStartedNotification__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ItemStartedNotification__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ItemStartedNotification__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ItemStartedNotification__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ItemStartedNotification__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ModelListResponse__Model = {
+  readonly additionalSpeedTiers?: ReadonlyArray<string>;
+  readonly availabilityNux?: V2ModelListResponse__ModelAvailabilityNux | null;
+  readonly defaultReasoningEffort: V2ModelListResponse__ReasoningEffort;
+  readonly description: string;
+  readonly displayName: string;
+  readonly hidden: boolean;
+  readonly id: string;
+  readonly inputModalities?: ReadonlyArray<V2ModelListResponse__InputModality>;
+  readonly isDefault: boolean;
+  readonly model: string;
+  readonly serviceTiers?: ReadonlyArray<V2ModelListResponse__ModelServiceTier>;
+  readonly supportedReasoningEfforts: ReadonlyArray<V2ModelListResponse__ReasoningEffortOption>;
+  readonly supportsPersonality?: boolean;
+  readonly upgrade?: string | null;
+  readonly upgradeInfo?: V2ModelListResponse__ModelUpgradeInfo | null;
+};
+export const V2ModelListResponse__Model = Schema.Struct({
+  additionalSpeedTiers: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      description: "Deprecated: use `serviceTiers` instead.",
+      default: [],
+    }),
+  ),
+  availabilityNux: Schema.optionalKey(
+    Schema.Union([V2ModelListResponse__ModelAvailabilityNux, Schema.Null]),
+  ),
+  defaultReasoningEffort: V2ModelListResponse__ReasoningEffort,
+  description: Schema.String,
+  displayName: Schema.String,
+  hidden: Schema.Boolean,
+  id: Schema.String,
+  inputModalities: Schema.optionalKey(
+    Schema.Array(V2ModelListResponse__InputModality).annotate({ default: ["text", "image"] }),
+  ),
+  isDefault: Schema.Boolean,
+  model: Schema.String,
+  serviceTiers: Schema.optionalKey(
+    Schema.Array(V2ModelListResponse__ModelServiceTier).annotate({ default: [] }),
+  ),
+  supportedReasoningEfforts: Schema.Array(V2ModelListResponse__ReasoningEffortOption),
+  supportsPersonality: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+  upgrade: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  upgradeInfo: Schema.optionalKey(
+    Schema.Union([V2ModelListResponse__ModelUpgradeInfo, Schema.Null]),
+  ),
+});
+
+export type V2PluginListResponse__PluginShareContext = {
+  readonly creatorAccountUserId?: string | null;
+  readonly creatorName?: string | null;
+  readonly remotePluginId: string;
+  readonly shareTargets?: ReadonlyArray<V2PluginListResponse__PluginSharePrincipal> | null;
+  readonly shareUrl?: string | null;
+};
+export const V2PluginListResponse__PluginShareContext = Schema.Struct({
+  creatorAccountUserId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  creatorName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  remotePluginId: Schema.String,
+  shareTargets: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2PluginListResponse__PluginSharePrincipal), Schema.Null]),
+  ),
+  shareUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginReadResponse__SkillSummary = {
+  readonly description: string;
+  readonly enabled: boolean;
+  readonly interface?: V2PluginReadResponse__SkillInterface | null;
+  readonly name: string;
+  readonly path?: V2PluginReadResponse__AbsolutePathBuf | null;
+  readonly shortDescription?: string | null;
+};
+export const V2PluginReadResponse__SkillSummary = Schema.Struct({
+  description: Schema.String,
+  enabled: Schema.Boolean,
+  interface: Schema.optionalKey(Schema.Union([V2PluginReadResponse__SkillInterface, Schema.Null])),
+  name: Schema.String,
+  path: Schema.optionalKey(Schema.Union([V2PluginReadResponse__AbsolutePathBuf, Schema.Null])),
+  shortDescription: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginReadResponse__PluginShareContext = {
+  readonly creatorAccountUserId?: string | null;
+  readonly creatorName?: string | null;
+  readonly remotePluginId: string;
+  readonly shareTargets?: ReadonlyArray<V2PluginReadResponse__PluginSharePrincipal> | null;
+  readonly shareUrl?: string | null;
+};
+export const V2PluginReadResponse__PluginShareContext = Schema.Struct({
+  creatorAccountUserId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  creatorName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  remotePluginId: Schema.String,
+  shareTargets: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2PluginReadResponse__PluginSharePrincipal), Schema.Null]),
+  ),
+  shareUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2PluginShareListResponse__PluginShareContext = {
+  readonly creatorAccountUserId?: string | null;
+  readonly creatorName?: string | null;
+  readonly remotePluginId: string;
+  readonly shareTargets?: ReadonlyArray<V2PluginShareListResponse__PluginSharePrincipal> | null;
+  readonly shareUrl?: string | null;
+};
+export const V2PluginShareListResponse__PluginShareContext = Schema.Struct({
+  creatorAccountUserId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  creatorName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  remotePluginId: Schema.String,
+  shareTargets: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2PluginShareListResponse__PluginSharePrincipal), Schema.Null]),
+  ),
+  shareUrl: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2RawResponseItemCompletedNotification__FunctionCallOutputBody =
+  | string
+  | ReadonlyArray<V2RawResponseItemCompletedNotification__FunctionCallOutputContentItem>;
+export const V2RawResponseItemCompletedNotification__FunctionCallOutputBody = Schema.Union([
+  Schema.String,
+  Schema.Array(V2RawResponseItemCompletedNotification__FunctionCallOutputContentItem),
+]);
+
+export type V2ReviewStartResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ReviewStartResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ReviewStartResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ReviewStartResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ReviewStartResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ReviewStartResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ReviewStartResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ReviewStartResponse__MemoryCitation | null;
+      readonly phase?: V2ReviewStartResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ReviewStartResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ReviewStartResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ReviewStartResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ReviewStartResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ReviewStartResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ReviewStartResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ReviewStartResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ReviewStartResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ReviewStartResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ReviewStartResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ReviewStartResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ReviewStartResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ReviewStartResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ReviewStartResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ReviewStartResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ReviewStartResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ReviewStartResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ReviewStartResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2ReviewStartResponse__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ReviewStartResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ReviewStartResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ReviewStartResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ReviewStartResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ReviewStartResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ReviewStartResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ReviewStartResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ReviewStartResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ReviewStartResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, V2ReviewStartResponse__CollabAgentState).annotate({
+        description: "Last known status of the target agents, when available.",
+      }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ReviewStartResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ReviewStartResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ReviewStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ReviewStartResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2SkillsListResponse__SkillMetadata = {
+  readonly dependencies?: V2SkillsListResponse__SkillDependencies | null;
+  readonly description: string;
+  readonly enabled: boolean;
+  readonly interface?: V2SkillsListResponse__SkillInterface | null;
+  readonly name: string;
+  readonly path: V2SkillsListResponse__AbsolutePathBuf;
+  readonly scope: V2SkillsListResponse__SkillScope;
+  readonly shortDescription?: string | null;
+};
+export const V2SkillsListResponse__SkillMetadata = Schema.Struct({
+  dependencies: Schema.optionalKey(
+    Schema.Union([V2SkillsListResponse__SkillDependencies, Schema.Null]),
+  ),
+  description: Schema.String,
+  enabled: Schema.Boolean,
+  interface: Schema.optionalKey(Schema.Union([V2SkillsListResponse__SkillInterface, Schema.Null])),
+  name: Schema.String,
+  path: V2SkillsListResponse__AbsolutePathBuf,
+  scope: V2SkillsListResponse__SkillScope,
+  shortDescription: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Legacy short_description from SKILL.md. Prefer SKILL.json interface.short_description.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ThreadForkResponse__FileSystemSandboxEntry = {
+  readonly access: V2ThreadForkResponse__FileSystemAccessMode;
+  readonly path: V2ThreadForkResponse__FileSystemPath;
+};
+export const V2ThreadForkResponse__FileSystemSandboxEntry = Schema.Struct({
+  access: V2ThreadForkResponse__FileSystemAccessMode,
+  path: V2ThreadForkResponse__FileSystemPath,
+});
+
+export type V2ThreadForkResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadForkResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadForkResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadForkResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadForkResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadForkResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadForkResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadForkResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadForkResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadForkResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadForkResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadForkResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadForkResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadForkResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadForkResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadForkResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadForkResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadForkResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ThreadForkResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadForkResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadForkResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadForkResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadForkResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadForkResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadForkResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadForkResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadForkResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2ThreadForkResponse__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadForkResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadForkResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadForkResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadForkResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadForkResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadForkResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadForkResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadForkResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadForkResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, V2ThreadForkResponse__CollabAgentState).annotate({
+        description: "Last known status of the target agents, when available.",
+      }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadForkResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadForkResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadForkResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadForkResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadListResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadListResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadListResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadListResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadListResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadListResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadListResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadListResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadListResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadListResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadListResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadListResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadListResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadListResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadListResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadListResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadListResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadListResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ThreadListResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadListResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadListResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadListResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadListResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadListResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadListResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadListResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadListResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2ThreadListResponse__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadListResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadListResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadListResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadListResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadListResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadListResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadListResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadListResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadListResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, V2ThreadListResponse__CollabAgentState).annotate({
+        description: "Last known status of the target agents, when available.",
+      }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadListResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadListResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadListResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadListResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadMetadataUpdateResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadMetadataUpdateResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadMetadataUpdateResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadMetadataUpdateResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadMetadataUpdateResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadMetadataUpdateResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadMetadataUpdateResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadMetadataUpdateResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadMetadataUpdateResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadMetadataUpdateResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadMetadataUpdateResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadMetadataUpdateResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadMetadataUpdateResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadMetadataUpdateResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadMetadataUpdateResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadMetadataUpdateResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadMetadataUpdateResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: {
+        readonly [x: string]: V2ThreadMetadataUpdateResponse__CollabAgentState;
+      };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadMetadataUpdateResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadMetadataUpdateResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadMetadataUpdateResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadMetadataUpdateResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadMetadataUpdateResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadMetadataUpdateResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadMetadataUpdateResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadMetadataUpdateResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2ThreadMetadataUpdateResponse__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadMetadataUpdateResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadMetadataUpdateResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadMetadataUpdateResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadMetadataUpdateResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadMetadataUpdateResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadMetadataUpdateResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadMetadataUpdateResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadMetadataUpdateResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadMetadataUpdateResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2ThreadMetadataUpdateResponse__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadMetadataUpdateResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadMetadataUpdateResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadMetadataUpdateResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadMetadataUpdateResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadReadResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadReadResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadReadResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadReadResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadReadResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadReadResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadReadResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadReadResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadReadResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadReadResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadReadResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadReadResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadReadResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadReadResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadReadResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadReadResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadReadResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ThreadReadResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadReadResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadReadResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadReadResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadReadResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadReadResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadReadResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadReadResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadReadResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2ThreadReadResponse__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadReadResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadReadResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadReadResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadReadResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadReadResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadReadResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadReadResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadReadResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadReadResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, V2ThreadReadResponse__CollabAgentState).annotate({
+        description: "Last known status of the target agents, when available.",
+      }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadReadResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadReadResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadReadResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadReadResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__FunctionCallOutputBody =
+  | string
+  | ReadonlyArray<V2ThreadResumeParams__FunctionCallOutputContentItem>;
+export const V2ThreadResumeParams__FunctionCallOutputBody = Schema.Union([
+  Schema.String,
+  Schema.Array(V2ThreadResumeParams__FunctionCallOutputContentItem),
+]);
+
+export type V2ThreadResumeResponse__FileSystemSandboxEntry = {
+  readonly access: V2ThreadResumeResponse__FileSystemAccessMode;
+  readonly path: V2ThreadResumeResponse__FileSystemPath;
+};
+export const V2ThreadResumeResponse__FileSystemSandboxEntry = Schema.Struct({
+  access: V2ThreadResumeResponse__FileSystemAccessMode,
+  path: V2ThreadResumeResponse__FileSystemPath,
+});
+
+export type V2ThreadResumeResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadResumeResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadResumeResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadResumeResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadResumeResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadResumeResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadResumeResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadResumeResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadResumeResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadResumeResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadResumeResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadResumeResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadResumeResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadResumeResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadResumeResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadResumeResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadResumeResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadResumeResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ThreadResumeResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadResumeResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadResumeResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadResumeResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadResumeResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadResumeResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadResumeResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadResumeResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadResumeResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2ThreadResumeResponse__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadResumeResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadResumeResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadResumeResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadResumeResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadResumeResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadResumeResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadResumeResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadResumeResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadResumeResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, V2ThreadResumeResponse__CollabAgentState).annotate(
+        { description: "Last known status of the target agents, when available." },
+      ),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadResumeResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadResumeResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadResumeResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadResumeResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadRollbackResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadRollbackResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadRollbackResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadRollbackResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadRollbackResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadRollbackResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadRollbackResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadRollbackResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadRollbackResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadRollbackResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadRollbackResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadRollbackResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadRollbackResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadRollbackResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadRollbackResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadRollbackResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadRollbackResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ThreadRollbackResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadRollbackResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadRollbackResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadRollbackResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadRollbackResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadRollbackResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadRollbackResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadRollbackResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadRollbackResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2ThreadRollbackResponse__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadRollbackResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadRollbackResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadRollbackResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadRollbackResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadRollbackResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadRollbackResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadRollbackResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadRollbackResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadRollbackResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2ThreadRollbackResponse__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadRollbackResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadRollbackResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadRollbackResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadRollbackResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadStartedNotification__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadStartedNotification__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadStartedNotification__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadStartedNotification__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadStartedNotification__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadStartedNotification__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadStartedNotification__MemoryCitation | null;
+      readonly phase?: V2ThreadStartedNotification__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadStartedNotification__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadStartedNotification__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadStartedNotification__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadStartedNotification__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadStartedNotification__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadStartedNotification__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadStartedNotification__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadStartedNotification__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadStartedNotification__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: {
+        readonly [x: string]: V2ThreadStartedNotification__CollabAgentState;
+      };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadStartedNotification__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadStartedNotification__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadStartedNotification__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadStartedNotification__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadStartedNotification__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadStartedNotification__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadStartedNotification__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadStartedNotification__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2ThreadStartedNotification__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadStartedNotification__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadStartedNotification__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadStartedNotification__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadStartedNotification__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadStartedNotification__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadStartedNotification__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadStartedNotification__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadStartedNotification__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadStartedNotification__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2ThreadStartedNotification__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadStartedNotification__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadStartedNotification__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadStartedNotification__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadStartedNotification__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__FileSystemSandboxEntry = {
+  readonly access: V2ThreadStartResponse__FileSystemAccessMode;
+  readonly path: V2ThreadStartResponse__FileSystemPath;
+};
+export const V2ThreadStartResponse__FileSystemSandboxEntry = Schema.Struct({
+  access: V2ThreadStartResponse__FileSystemAccessMode,
+  path: V2ThreadStartResponse__FileSystemPath,
+});
+
+export type V2ThreadStartResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadStartResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadStartResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadStartResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadStartResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadStartResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadStartResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadStartResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadStartResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadStartResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadStartResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadStartResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadStartResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadStartResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadStartResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadStartResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadStartResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadStartResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ThreadStartResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadStartResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadStartResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadStartResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadStartResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadStartResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadStartResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadStartResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadStartResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2ThreadStartResponse__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadStartResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadStartResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadStartResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadStartResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadStartResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadStartResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadStartResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadStartResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadStartResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, V2ThreadStartResponse__CollabAgentState).annotate({
+        description: "Last known status of the target agents, when available.",
+      }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadStartResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadStartResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadStartResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnarchiveResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2ThreadUnarchiveResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2ThreadUnarchiveResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadUnarchiveResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2ThreadUnarchiveResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadUnarchiveResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2ThreadUnarchiveResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2ThreadUnarchiveResponse__MemoryCitation | null;
+      readonly phase?: V2ThreadUnarchiveResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2ThreadUnarchiveResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2ThreadUnarchiveResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2ThreadUnarchiveResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2ThreadUnarchiveResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2ThreadUnarchiveResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2ThreadUnarchiveResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2ThreadUnarchiveResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2ThreadUnarchiveResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2ThreadUnarchiveResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2ThreadUnarchiveResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2ThreadUnarchiveResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2ThreadUnarchiveResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2ThreadUnarchiveResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2ThreadUnarchiveResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2ThreadUnarchiveResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadUnarchiveResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2ThreadUnarchiveResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2ThreadUnarchiveResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2ThreadUnarchiveResponse__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2ThreadUnarchiveResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2ThreadUnarchiveResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2ThreadUnarchiveResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2ThreadUnarchiveResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2ThreadUnarchiveResponse__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2ThreadUnarchiveResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2ThreadUnarchiveResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadUnarchiveResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2ThreadUnarchiveResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2ThreadUnarchiveResponse__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2ThreadUnarchiveResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadUnarchiveResponse__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2ThreadUnarchiveResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2ThreadUnarchiveResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnCompletedNotification__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2TurnCompletedNotification__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2TurnCompletedNotification__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2TurnCompletedNotification__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2TurnCompletedNotification__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2TurnCompletedNotification__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2TurnCompletedNotification__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2TurnCompletedNotification__MemoryCitation | null;
+      readonly phase?: V2TurnCompletedNotification__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2TurnCompletedNotification__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2TurnCompletedNotification__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2TurnCompletedNotification__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2TurnCompletedNotification__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2TurnCompletedNotification__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2TurnCompletedNotification__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2TurnCompletedNotification__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2TurnCompletedNotification__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2TurnCompletedNotification__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: {
+        readonly [x: string]: V2TurnCompletedNotification__CollabAgentState;
+      };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2TurnCompletedNotification__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2TurnCompletedNotification__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2TurnCompletedNotification__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2TurnCompletedNotification__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2TurnCompletedNotification__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2TurnCompletedNotification__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2TurnCompletedNotification__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2TurnCompletedNotification__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2TurnCompletedNotification__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2TurnCompletedNotification__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2TurnCompletedNotification__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2TurnCompletedNotification__FileUpdateChange),
+      id: Schema.String,
+      status: V2TurnCompletedNotification__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2TurnCompletedNotification__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2TurnCompletedNotification__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2TurnCompletedNotification__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2TurnCompletedNotification__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2TurnCompletedNotification__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2TurnCompletedNotification__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2TurnCompletedNotification__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2TurnCompletedNotification__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2TurnCompletedNotification__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2TurnCompletedNotification__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartedNotification__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2TurnStartedNotification__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2TurnStartedNotification__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2TurnStartedNotification__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2TurnStartedNotification__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2TurnStartedNotification__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2TurnStartedNotification__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2TurnStartedNotification__MemoryCitation | null;
+      readonly phase?: V2TurnStartedNotification__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2TurnStartedNotification__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2TurnStartedNotification__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2TurnStartedNotification__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2TurnStartedNotification__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2TurnStartedNotification__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2TurnStartedNotification__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2TurnStartedNotification__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2TurnStartedNotification__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2TurnStartedNotification__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2TurnStartedNotification__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2TurnStartedNotification__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2TurnStartedNotification__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2TurnStartedNotification__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2TurnStartedNotification__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2TurnStartedNotification__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2TurnStartedNotification__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2TurnStartedNotification__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2TurnStartedNotification__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2TurnStartedNotification__MessagePhase, Schema.Null]),
+      ),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2TurnStartedNotification__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2TurnStartedNotification__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2TurnStartedNotification__FileUpdateChange),
+      id: Schema.String,
+      status: V2TurnStartedNotification__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(
+        Schema.Union([V2TurnStartedNotification__McpToolCallError, Schema.Null]),
+      ),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2TurnStartedNotification__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2TurnStartedNotification__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2TurnStartedNotification__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2TurnStartedNotification__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(
+        Schema.String,
+        V2TurnStartedNotification__CollabAgentState,
+      ).annotate({ description: "Last known status of the target agents, when available." }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2TurnStartedNotification__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2TurnStartedNotification__WebSearchAction, Schema.Null]),
+      ),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2TurnStartedNotification__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2TurnStartedNotification__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartResponse__TurnError = {
+  readonly additionalDetails?: string | null;
+  readonly codexErrorInfo?: V2TurnStartResponse__CodexErrorInfo | null;
+  readonly message: string;
+};
+export const V2TurnStartResponse__TurnError = Schema.Struct({
+  additionalDetails: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  codexErrorInfo: Schema.optionalKey(
+    Schema.Union([V2TurnStartResponse__CodexErrorInfo, Schema.Null]),
+  ),
+  message: Schema.String,
+});
+
+export type V2TurnStartResponse__ThreadItem =
+  | {
+      readonly content: ReadonlyArray<V2TurnStartResponse__UserInput>;
+      readonly id: string;
+      readonly type: "userMessage";
+    }
+  | {
+      readonly fragments: ReadonlyArray<V2TurnStartResponse__HookPromptFragment>;
+      readonly id: string;
+      readonly type: "hookPrompt";
+    }
+  | {
+      readonly id: string;
+      readonly memoryCitation?: V2TurnStartResponse__MemoryCitation | null;
+      readonly phase?: V2TurnStartResponse__MessagePhase | null;
+      readonly text: string;
+      readonly type: "agentMessage";
+    }
+  | { readonly id: string; readonly text: string; readonly type: "plan" }
+  | {
+      readonly content?: ReadonlyArray<string>;
+      readonly id: string;
+      readonly summary?: ReadonlyArray<string>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly aggregatedOutput?: string | null;
+      readonly command: string;
+      readonly commandActions: ReadonlyArray<V2TurnStartResponse__CommandAction>;
+      readonly cwd: string;
+      readonly durationMs?: number | null;
+      readonly exitCode?: number | null;
+      readonly id: string;
+      readonly processId?: string | null;
+      readonly source?: "agent" | "userShell" | "unifiedExecStartup" | "unifiedExecInteraction";
+      readonly status: V2TurnStartResponse__CommandExecutionStatus;
+      readonly type: "commandExecution";
+    }
+  | {
+      readonly changes: ReadonlyArray<V2TurnStartResponse__FileUpdateChange>;
+      readonly id: string;
+      readonly status: V2TurnStartResponse__PatchApplyStatus;
+      readonly type: "fileChange";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly durationMs?: number | null;
+      readonly error?: V2TurnStartResponse__McpToolCallError | null;
+      readonly id: string;
+      readonly mcpAppResourceUri?: string | null;
+      readonly result?: V2TurnStartResponse__McpToolCallResult | null;
+      readonly server: string;
+      readonly status: V2TurnStartResponse__McpToolCallStatus;
+      readonly tool: string;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly contentItems?: ReadonlyArray<V2TurnStartResponse__DynamicToolCallOutputContentItem> | null;
+      readonly durationMs?: number | null;
+      readonly id: string;
+      readonly namespace?: string | null;
+      readonly status: V2TurnStartResponse__DynamicToolCallStatus;
+      readonly success?: boolean | null;
+      readonly tool: string;
+      readonly type: "dynamicToolCall";
+    }
+  | {
+      readonly agentsStates: { readonly [x: string]: V2TurnStartResponse__CollabAgentState };
+      readonly id: string;
+      readonly model?: string | null;
+      readonly prompt?: string | null;
+      readonly reasoningEffort?: V2TurnStartResponse__ReasoningEffort | null;
+      readonly receiverThreadIds: ReadonlyArray<string>;
+      readonly senderThreadId: string;
+      readonly status: "inProgress" | "completed" | "failed";
+      readonly tool: "spawnAgent" | "sendInput" | "resumeAgent" | "wait" | "closeAgent";
+      readonly type: "collabAgentToolCall";
+    }
+  | {
+      readonly action?: V2TurnStartResponse__WebSearchAction | null;
+      readonly id: string;
+      readonly query: string;
+      readonly type: "webSearch";
+    }
+  | {
+      readonly id: string;
+      readonly path: V2TurnStartResponse__AbsolutePathBuf;
+      readonly type: "imageView";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revisedPrompt?: string | null;
+      readonly savedPath?: V2TurnStartResponse__AbsolutePathBuf | null;
+      readonly status: string;
+      readonly type: "imageGeneration";
+    }
+  | { readonly id: string; readonly review: string; readonly type: "enteredReviewMode" }
+  | { readonly id: string; readonly review: string; readonly type: "exitedReviewMode" }
+  | { readonly id: string; readonly type: "contextCompaction" };
+export const V2TurnStartResponse__ThreadItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2TurnStartResponse__UserInput),
+      id: Schema.String,
+      type: Schema.Literal("userMessage").annotate({ title: "UserMessageThreadItemType" }),
+    }).annotate({ title: "UserMessageThreadItem" }),
+    Schema.Struct({
+      fragments: Schema.Array(V2TurnStartResponse__HookPromptFragment),
+      id: Schema.String,
+      type: Schema.Literal("hookPrompt").annotate({ title: "HookPromptThreadItemType" }),
+    }).annotate({ title: "HookPromptThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      memoryCitation: Schema.optionalKey(
+        Schema.Union([V2TurnStartResponse__MemoryCitation, Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2TurnStartResponse__MessagePhase, Schema.Null])),
+      text: Schema.String,
+      type: Schema.Literal("agentMessage").annotate({ title: "AgentMessageThreadItemType" }),
+    }).annotate({ title: "AgentMessageThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      text: Schema.String,
+      type: Schema.Literal("plan").annotate({ title: "PlanThreadItemType" }),
+    }).annotate({
+      title: "PlanThreadItem",
+      description:
+        "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
+    }),
+    Schema.Struct({
+      content: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      id: Schema.String,
+      summary: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningThreadItemType" }),
+    }).annotate({ title: "ReasoningThreadItem" }),
+    Schema.Struct({
+      aggregatedOutput: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "The command's output, aggregated from stdout and stderr.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      command: Schema.String.annotate({ description: "The command to be executed." }),
+      commandActions: Schema.Array(V2TurnStartResponse__CommandAction).annotate({
+        description:
+          "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
+      }),
+      cwd: Schema.String.annotate({
+        description:
+          "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+      }),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the command execution in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      exitCode: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The command's exit code.",
+            format: "int32",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      processId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Identifier for the underlying PTY process (when available).",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      source: Schema.optionalKey(
+        Schema.Literals([
+          "agent",
+          "userShell",
+          "unifiedExecStartup",
+          "unifiedExecInteraction",
+        ]).annotate({ default: "agent" }),
+      ),
+      status: V2TurnStartResponse__CommandExecutionStatus,
+      type: Schema.Literal("commandExecution").annotate({
+        title: "CommandExecutionThreadItemType",
+      }),
+    }).annotate({ title: "CommandExecutionThreadItem" }),
+    Schema.Struct({
+      changes: Schema.Array(V2TurnStartResponse__FileUpdateChange),
+      id: Schema.String,
+      status: V2TurnStartResponse__PatchApplyStatus,
+      type: Schema.Literal("fileChange").annotate({ title: "FileChangeThreadItemType" }),
+    }).annotate({ title: "FileChangeThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the MCP tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      error: Schema.optionalKey(Schema.Union([V2TurnStartResponse__McpToolCallError, Schema.Null])),
+      id: Schema.String,
+      mcpAppResourceUri: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      result: Schema.optionalKey(
+        Schema.Union([V2TurnStartResponse__McpToolCallResult, Schema.Null]),
+      ),
+      server: Schema.String,
+      status: V2TurnStartResponse__McpToolCallStatus,
+      tool: Schema.String,
+      type: Schema.Literal("mcpToolCall").annotate({ title: "McpToolCallThreadItemType" }),
+    }).annotate({ title: "McpToolCallThreadItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      contentItems: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2TurnStartResponse__DynamicToolCallOutputContentItem),
+          Schema.Null,
+        ]),
+      ),
+      durationMs: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({
+            description: "The duration of the dynamic tool call in milliseconds.",
+            format: "int64",
+          }).check(Schema.isInt()),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: V2TurnStartResponse__DynamicToolCallStatus,
+      success: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+      tool: Schema.String,
+      type: Schema.Literal("dynamicToolCall").annotate({ title: "DynamicToolCallThreadItemType" }),
+    }).annotate({ title: "DynamicToolCallThreadItem" }),
+    Schema.Struct({
+      agentsStates: Schema.Record(Schema.String, V2TurnStartResponse__CollabAgentState).annotate({
+        description: "Last known status of the target agents, when available.",
+      }),
+      id: Schema.String.annotate({ description: "Unique identifier for this collab tool call." }),
+      model: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Model requested for the spawned agent, when applicable.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      prompt: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Prompt text sent as part of the collab tool call, when available.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      reasoningEffort: Schema.optionalKey(
+        Schema.Union([V2TurnStartResponse__ReasoningEffort, Schema.Null]).annotate({
+          description: "Reasoning effort requested for the spawned agent, when applicable.",
+        }),
+      ),
+      receiverThreadIds: Schema.Array(Schema.String).annotate({
+        description:
+          "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
+      }),
+      senderThreadId: Schema.String.annotate({
+        description: "Thread ID of the agent issuing the collab request.",
+      }),
+      status: Schema.Literals(["inProgress", "completed", "failed"]).annotate({
+        description: "Current status of the collab tool call.",
+      }),
+      tool: Schema.Literals([
+        "spawnAgent",
+        "sendInput",
+        "resumeAgent",
+        "wait",
+        "closeAgent",
+      ]).annotate({ description: "Name of the collab tool that was invoked." }),
+      type: Schema.Literal("collabAgentToolCall").annotate({
+        title: "CollabAgentToolCallThreadItemType",
+      }),
+    }).annotate({ title: "CollabAgentToolCallThreadItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(Schema.Union([V2TurnStartResponse__WebSearchAction, Schema.Null])),
+      id: Schema.String,
+      query: Schema.String,
+      type: Schema.Literal("webSearch").annotate({ title: "WebSearchThreadItemType" }),
+    }).annotate({ title: "WebSearchThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      path: V2TurnStartResponse__AbsolutePathBuf,
+      type: Schema.Literal("imageView").annotate({ title: "ImageViewThreadItemType" }),
+    }).annotate({ title: "ImageViewThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revisedPrompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      savedPath: Schema.optionalKey(
+        Schema.Union([V2TurnStartResponse__AbsolutePathBuf, Schema.Null]),
+      ),
+      status: Schema.String,
+      type: Schema.Literal("imageGeneration").annotate({ title: "ImageGenerationThreadItemType" }),
+    }).annotate({ title: "ImageGenerationThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("enteredReviewMode").annotate({
+        title: "EnteredReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "EnteredReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      review: Schema.String,
+      type: Schema.Literal("exitedReviewMode").annotate({
+        title: "ExitedReviewModeThreadItemType",
+      }),
+    }).annotate({ title: "ExitedReviewModeThreadItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      type: Schema.Literal("contextCompaction").annotate({
+        title: "ContextCompactionThreadItemType",
+      }),
+    }).annotate({ title: "ContextCompactionThreadItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__PermissionProfileFileSystemPermissions =
+  | {
+      readonly entries: ReadonlyArray<ClientRequest__FileSystemSandboxEntry>;
+      readonly globScanMaxDepth?: number | null;
+      readonly type: "restricted";
+    }
+  | { readonly type: "unrestricted" };
+export const ClientRequest__PermissionProfileFileSystemPermissions = Schema.Union(
+  [
+    Schema.Struct({
+      entries: Schema.Array(ClientRequest__FileSystemSandboxEntry),
+      globScanMaxDepth: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(1)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("restricted").annotate({
+        title: "RestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "RestrictedPermissionProfileFileSystemPermissions" }),
+    Schema.Struct({
+      type: Schema.Literal("unrestricted").annotate({
+        title: "UnrestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "UnrestrictedPermissionProfileFileSystemPermissions" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ExternalAgentConfigImportParams = {
+  readonly migrationItems: ReadonlyArray<ClientRequest__ExternalAgentConfigMigrationItem>;
+};
+export const ClientRequest__ExternalAgentConfigImportParams = Schema.Struct({
+  migrationItems: Schema.Array(ClientRequest__ExternalAgentConfigMigrationItem),
+});
+
+export type CommandExecutionRequestApprovalParams__AdditionalFileSystemPermissions = {
+  readonly entries?: ReadonlyArray<CommandExecutionRequestApprovalParams__FileSystemSandboxEntry> | null;
+  readonly globScanMaxDepth?: number | null;
+  readonly read?: ReadonlyArray<CommandExecutionRequestApprovalParams__AbsolutePathBuf> | null;
+  readonly write?: ReadonlyArray<CommandExecutionRequestApprovalParams__AbsolutePathBuf> | null;
+};
+export const CommandExecutionRequestApprovalParams__AdditionalFileSystemPermissions = Schema.Struct(
+  {
+    entries: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(CommandExecutionRequestApprovalParams__FileSystemSandboxEntry),
+        Schema.Null,
+      ]),
+    ),
+    globScanMaxDepth: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(1)),
+        Schema.Null,
+      ]),
+    ),
+    read: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(CommandExecutionRequestApprovalParams__AbsolutePathBuf).annotate({
+          description: "This will be removed in favor of `entries`.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    write: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(CommandExecutionRequestApprovalParams__AbsolutePathBuf).annotate({
+          description: "This will be removed in favor of `entries`.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+  },
+);
+
+export type McpServerElicitationRequestParams__McpElicitationMultiSelectEnumSchema =
+  | McpServerElicitationRequestParams__McpElicitationUntitledMultiSelectEnumSchema
+  | McpServerElicitationRequestParams__McpElicitationTitledMultiSelectEnumSchema;
+export const McpServerElicitationRequestParams__McpElicitationMultiSelectEnumSchema = Schema.Union([
+  McpServerElicitationRequestParams__McpElicitationUntitledMultiSelectEnumSchema,
+  McpServerElicitationRequestParams__McpElicitationTitledMultiSelectEnumSchema,
+]);
+
+export type PermissionsRequestApprovalParams__AdditionalFileSystemPermissions = {
+  readonly entries?: ReadonlyArray<PermissionsRequestApprovalParams__FileSystemSandboxEntry> | null;
+  readonly globScanMaxDepth?: number | null;
+  readonly read?: ReadonlyArray<PermissionsRequestApprovalParams__AbsolutePathBuf> | null;
+  readonly write?: ReadonlyArray<PermissionsRequestApprovalParams__AbsolutePathBuf> | null;
+};
+export const PermissionsRequestApprovalParams__AdditionalFileSystemPermissions = Schema.Struct({
+  entries: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(PermissionsRequestApprovalParams__FileSystemSandboxEntry),
+      Schema.Null,
+    ]),
+  ),
+  globScanMaxDepth: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(1)),
+      Schema.Null,
+    ]),
+  ),
+  read: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(PermissionsRequestApprovalParams__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  write: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(PermissionsRequestApprovalParams__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type PermissionsRequestApprovalResponse__AdditionalFileSystemPermissions = {
+  readonly entries?: ReadonlyArray<PermissionsRequestApprovalResponse__FileSystemSandboxEntry> | null;
+  readonly globScanMaxDepth?: number | null;
+  readonly read?: ReadonlyArray<PermissionsRequestApprovalResponse__AbsolutePathBuf> | null;
+  readonly write?: ReadonlyArray<PermissionsRequestApprovalResponse__AbsolutePathBuf> | null;
+};
+export const PermissionsRequestApprovalResponse__AdditionalFileSystemPermissions = Schema.Struct({
+  entries: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(PermissionsRequestApprovalResponse__FileSystemSandboxEntry),
+      Schema.Null,
+    ]),
+  ),
+  globScanMaxDepth: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(1)),
+      Schema.Null,
+    ]),
+  ),
+  read: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(PermissionsRequestApprovalResponse__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  write: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(PermissionsRequestApprovalResponse__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ServerNotification__AppListUpdatedNotification = {
+  readonly data: ReadonlyArray<ServerNotification__AppInfo>;
+};
+export const ServerNotification__AppListUpdatedNotification = Schema.Struct({
+  data: Schema.Array(ServerNotification__AppInfo),
+}).annotate({ description: "EXPERIMENTAL - notification emitted when the app list changes." });
+
+export type ServerNotification__AdditionalFileSystemPermissions = {
+  readonly entries?: ReadonlyArray<ServerNotification__FileSystemSandboxEntry> | null;
+  readonly globScanMaxDepth?: number | null;
+  readonly read?: ReadonlyArray<ServerNotification__AbsolutePathBuf> | null;
+  readonly write?: ReadonlyArray<ServerNotification__AbsolutePathBuf> | null;
+};
+export const ServerNotification__AdditionalFileSystemPermissions = Schema.Struct({
+  entries: Schema.optionalKey(
+    Schema.Union([Schema.Array(ServerNotification__FileSystemSandboxEntry), Schema.Null]),
+  ),
+  globScanMaxDepth: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(1)),
+      Schema.Null,
+    ]),
+  ),
+  read: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ServerNotification__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  write: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ServerNotification__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ServerNotification__HookCompletedNotification = {
+  readonly run: ServerNotification__HookRunSummary;
+  readonly threadId: string;
+  readonly turnId?: string | null;
+};
+export const ServerNotification__HookCompletedNotification = Schema.Struct({
+  run: ServerNotification__HookRunSummary,
+  threadId: Schema.String,
+  turnId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerNotification__HookStartedNotification = {
+  readonly run: ServerNotification__HookRunSummary;
+  readonly threadId: string;
+  readonly turnId?: string | null;
+};
+export const ServerNotification__HookStartedNotification = Schema.Struct({
+  run: ServerNotification__HookRunSummary,
+  threadId: Schema.String,
+  turnId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ServerNotification__ErrorNotification = {
+  readonly error: ServerNotification__TurnError;
+  readonly threadId: string;
+  readonly turnId: string;
+  readonly willRetry: boolean;
+};
+export const ServerNotification__ErrorNotification = Schema.Struct({
+  error: ServerNotification__TurnError,
+  threadId: Schema.String,
+  turnId: Schema.String,
+  willRetry: Schema.Boolean,
+});
+
+export type ServerNotification__ItemCompletedNotification = {
+  readonly completedAtMs: number;
+  readonly item: ServerNotification__ThreadItem;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ItemCompletedNotification = Schema.Struct({
+  completedAtMs: Schema.Number.annotate({
+    description: "Unix timestamp (in milliseconds) when this item lifecycle completed.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  item: ServerNotification__ThreadItem,
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__ItemStartedNotification = {
+  readonly item: ServerNotification__ThreadItem;
+  readonly startedAtMs: number;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ItemStartedNotification = Schema.Struct({
+  item: ServerNotification__ThreadItem,
+  startedAtMs: Schema.Number.annotate({
+    description: "Unix timestamp (in milliseconds) when this item lifecycle started.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerNotification__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: ServerNotification__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<ServerNotification__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: ServerNotification__TurnStatus;
+};
+export const ServerNotification__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([ServerNotification__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(ServerNotification__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: ServerNotification__TurnStatus,
+});
+
+export type ServerRequest__AdditionalFileSystemPermissions = {
+  readonly entries?: ReadonlyArray<ServerRequest__FileSystemSandboxEntry> | null;
+  readonly globScanMaxDepth?: number | null;
+  readonly read?: ReadonlyArray<ServerRequest__AbsolutePathBuf> | null;
+  readonly write?: ReadonlyArray<ServerRequest__AbsolutePathBuf> | null;
+};
+export const ServerRequest__AdditionalFileSystemPermissions = Schema.Struct({
+  entries: Schema.optionalKey(
+    Schema.Union([Schema.Array(ServerRequest__FileSystemSandboxEntry), Schema.Null]),
+  ),
+  globScanMaxDepth: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(1)),
+      Schema.Null,
+    ]),
+  ),
+  read: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ServerRequest__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  write: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(ServerRequest__AbsolutePathBuf).annotate({
+        description: "This will be removed in favor of `entries`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type ServerRequest__McpElicitationMultiSelectEnumSchema =
+  | ServerRequest__McpElicitationUntitledMultiSelectEnumSchema
+  | ServerRequest__McpElicitationTitledMultiSelectEnumSchema;
+export const ServerRequest__McpElicitationMultiSelectEnumSchema = Schema.Union([
+  ServerRequest__McpElicitationUntitledMultiSelectEnumSchema,
+  ServerRequest__McpElicitationTitledMultiSelectEnumSchema,
+]);
+
+export type V2CommandExecParams__PermissionProfileFileSystemPermissions =
+  | {
+      readonly entries: ReadonlyArray<V2CommandExecParams__FileSystemSandboxEntry>;
+      readonly globScanMaxDepth?: number | null;
+      readonly type: "restricted";
+    }
+  | { readonly type: "unrestricted" };
+export const V2CommandExecParams__PermissionProfileFileSystemPermissions = Schema.Union(
+  [
+    Schema.Struct({
+      entries: Schema.Array(V2CommandExecParams__FileSystemSandboxEntry),
+      globScanMaxDepth: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(1)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("restricted").annotate({
+        title: "RestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "RestrictedPermissionProfileFileSystemPermissions" }),
+    Schema.Struct({
+      type: Schema.Literal("unrestricted").annotate({
+        title: "UnrestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "UnrestrictedPermissionProfileFileSystemPermissions" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ConfigReadResponse__ProfileV2 = {
+  readonly approval_policy?: V2ConfigReadResponse__AskForApproval | null;
+  readonly approvals_reviewer?: V2ConfigReadResponse__ApprovalsReviewer | null;
+  readonly chatgpt_base_url?: string | null;
+  readonly model?: string | null;
+  readonly model_provider?: string | null;
+  readonly model_reasoning_effort?: V2ConfigReadResponse__ReasoningEffort | null;
+  readonly model_reasoning_summary?: V2ConfigReadResponse__ReasoningSummary | null;
+  readonly model_verbosity?: V2ConfigReadResponse__Verbosity | null;
+  readonly service_tier?: string | null;
+  readonly tools?: V2ConfigReadResponse__ToolsV2 | null;
+  readonly web_search?: V2ConfigReadResponse__WebSearchMode | null;
+  readonly [x: string]: unknown;
+};
+export const V2ConfigReadResponse__ProfileV2 = Schema.StructWithRest(
+  Schema.Struct({
+    approval_policy: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__AskForApproval, Schema.Null]),
+    ),
+    approvals_reviewer: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__ApprovalsReviewer, Schema.Null]).annotate({
+        description:
+          "[UNSTABLE] Optional profile-level override for where approval requests are routed for review. If omitted, the enclosing config default is used.",
+      }),
+    ),
+    chatgpt_base_url: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    model: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    model_provider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    model_reasoning_effort: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__ReasoningEffort, Schema.Null]),
+    ),
+    model_reasoning_summary: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__ReasoningSummary, Schema.Null]),
+    ),
+    model_verbosity: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__Verbosity, Schema.Null]),
+    ),
+    service_tier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    tools: Schema.optionalKey(Schema.Union([V2ConfigReadResponse__ToolsV2, Schema.Null])),
+    web_search: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__WebSearchMode, Schema.Null]),
+    ),
+  }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+);
+
+export type V2ConfigWriteResponse__OverriddenMetadata = {
+  readonly effectiveValue: unknown;
+  readonly message: string;
+  readonly overridingLayer: V2ConfigWriteResponse__ConfigLayerMetadata;
+};
+export const V2ConfigWriteResponse__OverriddenMetadata = Schema.Struct({
+  effectiveValue: Schema.Unknown,
+  message: Schema.String,
+  overridingLayer: V2ConfigWriteResponse__ConfigLayerMetadata,
+});
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__AdditionalFileSystemPermissions = {
+  readonly entries?: ReadonlyArray<V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSandboxEntry> | null;
+  readonly globScanMaxDepth?: number | null;
+  readonly read?: ReadonlyArray<V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf> | null;
+  readonly write?: ReadonlyArray<V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf> | null;
+};
+export const V2ItemGuardianApprovalReviewCompletedNotification__AdditionalFileSystemPermissions =
+  Schema.Struct({
+    entries: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(V2ItemGuardianApprovalReviewCompletedNotification__FileSystemSandboxEntry),
+        Schema.Null,
+      ]),
+    ),
+    globScanMaxDepth: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(1)),
+        Schema.Null,
+      ]),
+    ),
+    read: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf).annotate({
+          description: "This will be removed in favor of `entries`.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    write: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf).annotate({
+          description: "This will be removed in favor of `entries`.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+  });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__AdditionalFileSystemPermissions = {
+  readonly entries?: ReadonlyArray<V2ItemGuardianApprovalReviewStartedNotification__FileSystemSandboxEntry> | null;
+  readonly globScanMaxDepth?: number | null;
+  readonly read?: ReadonlyArray<V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf> | null;
+  readonly write?: ReadonlyArray<V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf> | null;
+};
+export const V2ItemGuardianApprovalReviewStartedNotification__AdditionalFileSystemPermissions =
+  Schema.Struct({
+    entries: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(V2ItemGuardianApprovalReviewStartedNotification__FileSystemSandboxEntry),
+        Schema.Null,
+      ]),
+    ),
+    globScanMaxDepth: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "uint" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(1)),
+        Schema.Null,
+      ]),
+    ),
+    read: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf).annotate({
+          description: "This will be removed in favor of `entries`.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    write: Schema.optionalKey(
+      Schema.Union([
+        Schema.Array(V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf).annotate({
+          description: "This will be removed in favor of `entries`.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+  });
+
+export type V2PluginListResponse__PluginSummary = {
+  readonly authPolicy: V2PluginListResponse__PluginAuthPolicy;
+  readonly availability?: "DISABLED_BY_ADMIN" | "AVAILABLE";
+  readonly enabled: boolean;
+  readonly id: string;
+  readonly installPolicy: V2PluginListResponse__PluginInstallPolicy;
+  readonly installed: boolean;
+  readonly interface?: V2PluginListResponse__PluginInterface | null;
+  readonly keywords?: ReadonlyArray<string>;
+  readonly name: string;
+  readonly shareContext?: V2PluginListResponse__PluginShareContext | null;
+  readonly source: V2PluginListResponse__PluginSource;
+};
+export const V2PluginListResponse__PluginSummary = Schema.Struct({
+  authPolicy: V2PluginListResponse__PluginAuthPolicy,
+  availability: Schema.optionalKey(
+    Schema.Literals(["DISABLED_BY_ADMIN", "AVAILABLE"]).annotate({
+      description: "Availability state for installing and using the plugin.",
+      default: "AVAILABLE",
+    }),
+  ),
+  enabled: Schema.Boolean,
+  id: Schema.String,
+  installPolicy: V2PluginListResponse__PluginInstallPolicy,
+  installed: Schema.Boolean,
+  interface: Schema.optionalKey(Schema.Union([V2PluginListResponse__PluginInterface, Schema.Null])),
+  keywords: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+  name: Schema.String,
+  shareContext: Schema.optionalKey(
+    Schema.Union([V2PluginListResponse__PluginShareContext, Schema.Null]).annotate({
+      description: "Remote sharing context associated with this plugin when available.",
+    }),
+  ),
+  source: V2PluginListResponse__PluginSource,
+});
+
+export type V2PluginReadResponse__PluginSummary = {
+  readonly authPolicy: V2PluginReadResponse__PluginAuthPolicy;
+  readonly availability?: "DISABLED_BY_ADMIN" | "AVAILABLE";
+  readonly enabled: boolean;
+  readonly id: string;
+  readonly installPolicy: V2PluginReadResponse__PluginInstallPolicy;
+  readonly installed: boolean;
+  readonly interface?: V2PluginReadResponse__PluginInterface | null;
+  readonly keywords?: ReadonlyArray<string>;
+  readonly name: string;
+  readonly shareContext?: V2PluginReadResponse__PluginShareContext | null;
+  readonly source: V2PluginReadResponse__PluginSource;
+};
+export const V2PluginReadResponse__PluginSummary = Schema.Struct({
+  authPolicy: V2PluginReadResponse__PluginAuthPolicy,
+  availability: Schema.optionalKey(
+    Schema.Literals(["DISABLED_BY_ADMIN", "AVAILABLE"]).annotate({
+      description: "Availability state for installing and using the plugin.",
+      default: "AVAILABLE",
+    }),
+  ),
+  enabled: Schema.Boolean,
+  id: Schema.String,
+  installPolicy: V2PluginReadResponse__PluginInstallPolicy,
+  installed: Schema.Boolean,
+  interface: Schema.optionalKey(Schema.Union([V2PluginReadResponse__PluginInterface, Schema.Null])),
+  keywords: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+  name: Schema.String,
+  shareContext: Schema.optionalKey(
+    Schema.Union([V2PluginReadResponse__PluginShareContext, Schema.Null]).annotate({
+      description: "Remote sharing context associated with this plugin when available.",
+    }),
+  ),
+  source: V2PluginReadResponse__PluginSource,
+});
+
+export type V2PluginShareListResponse__PluginSummary = {
+  readonly authPolicy: V2PluginShareListResponse__PluginAuthPolicy;
+  readonly availability?: "DISABLED_BY_ADMIN" | "AVAILABLE";
+  readonly enabled: boolean;
+  readonly id: string;
+  readonly installPolicy: V2PluginShareListResponse__PluginInstallPolicy;
+  readonly installed: boolean;
+  readonly interface?: V2PluginShareListResponse__PluginInterface | null;
+  readonly keywords?: ReadonlyArray<string>;
+  readonly name: string;
+  readonly shareContext?: V2PluginShareListResponse__PluginShareContext | null;
+  readonly source: V2PluginShareListResponse__PluginSource;
+};
+export const V2PluginShareListResponse__PluginSummary = Schema.Struct({
+  authPolicy: V2PluginShareListResponse__PluginAuthPolicy,
+  availability: Schema.optionalKey(
+    Schema.Literals(["DISABLED_BY_ADMIN", "AVAILABLE"]).annotate({
+      description: "Availability state for installing and using the plugin.",
+      default: "AVAILABLE",
+    }),
+  ),
+  enabled: Schema.Boolean,
+  id: Schema.String,
+  installPolicy: V2PluginShareListResponse__PluginInstallPolicy,
+  installed: Schema.Boolean,
+  interface: Schema.optionalKey(
+    Schema.Union([V2PluginShareListResponse__PluginInterface, Schema.Null]),
+  ),
+  keywords: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+  name: Schema.String,
+  shareContext: Schema.optionalKey(
+    Schema.Union([V2PluginShareListResponse__PluginShareContext, Schema.Null]).annotate({
+      description: "Remote sharing context associated with this plugin when available.",
+    }),
+  ),
+  source: V2PluginShareListResponse__PluginSource,
+});
+
+export type V2RawResponseItemCompletedNotification__ResponseItem =
+  | {
+      readonly content: ReadonlyArray<V2RawResponseItemCompletedNotification__ContentItem>;
+      readonly id?: string | null;
+      readonly phase?: V2RawResponseItemCompletedNotification__MessagePhase | null;
+      readonly role: string;
+      readonly type: "message";
+    }
+  | {
+      readonly content?: ReadonlyArray<V2RawResponseItemCompletedNotification__ReasoningItemContent> | null;
+      readonly encrypted_content?: string | null;
+      readonly summary: ReadonlyArray<V2RawResponseItemCompletedNotification__ReasoningItemReasoningSummary>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly action: V2RawResponseItemCompletedNotification__LocalShellAction;
+      readonly call_id?: string | null;
+      readonly id?: string | null;
+      readonly status: V2RawResponseItemCompletedNotification__LocalShellStatus;
+      readonly type: "local_shell_call";
+    }
+  | {
+      readonly arguments: string;
+      readonly call_id: string;
+      readonly id?: string | null;
+      readonly name: string;
+      readonly namespace?: string | null;
+      readonly type: "function_call";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly call_id?: string | null;
+      readonly execution: string;
+      readonly id?: string | null;
+      readonly status?: string | null;
+      readonly type: "tool_search_call";
+    }
+  | {
+      readonly call_id: string;
+      readonly output: V2RawResponseItemCompletedNotification__FunctionCallOutputBody;
+      readonly type: "function_call_output";
+    }
+  | {
+      readonly call_id: string;
+      readonly id?: string | null;
+      readonly input: string;
+      readonly name: string;
+      readonly status?: string | null;
+      readonly type: "custom_tool_call";
+    }
+  | {
+      readonly call_id: string;
+      readonly name?: string | null;
+      readonly output: V2RawResponseItemCompletedNotification__FunctionCallOutputBody;
+      readonly type: "custom_tool_call_output";
+    }
+  | {
+      readonly call_id?: string | null;
+      readonly execution: string;
+      readonly status: string;
+      readonly tools: ReadonlyArray<unknown>;
+      readonly type: "tool_search_output";
+    }
+  | {
+      readonly action?: V2RawResponseItemCompletedNotification__ResponsesApiWebSearchAction | null;
+      readonly id?: string | null;
+      readonly status?: string | null;
+      readonly type: "web_search_call";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revised_prompt?: string | null;
+      readonly status: string;
+      readonly type: "image_generation_call";
+    }
+  | { readonly encrypted_content: string; readonly type: "compaction" }
+  | { readonly encrypted_content?: string | null; readonly type: "context_compaction" }
+  | { readonly type: "other" };
+export const V2RawResponseItemCompletedNotification__ResponseItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2RawResponseItemCompletedNotification__ContentItem),
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      phase: Schema.optionalKey(
+        Schema.Union([V2RawResponseItemCompletedNotification__MessagePhase, Schema.Null]),
+      ),
+      role: Schema.String,
+      type: Schema.Literal("message").annotate({ title: "MessageResponseItemType" }),
+    }).annotate({ title: "MessageResponseItem" }),
+    Schema.Struct({
+      content: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2RawResponseItemCompletedNotification__ReasoningItemContent),
+          Schema.Null,
+        ]),
+      ),
+      encrypted_content: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      summary: Schema.Array(V2RawResponseItemCompletedNotification__ReasoningItemReasoningSummary),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningResponseItemType" }),
+    }).annotate({ title: "ReasoningResponseItem" }),
+    Schema.Struct({
+      action: V2RawResponseItemCompletedNotification__LocalShellAction,
+      call_id: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Set when using the Responses API." }),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Legacy id field retained for compatibility with older payloads.",
+            writeOnly: true,
+          }),
+          Schema.Null,
+        ]),
+      ),
+      status: V2RawResponseItemCompletedNotification__LocalShellStatus,
+      type: Schema.Literal("local_shell_call").annotate({
+        title: "LocalShellCallResponseItemType",
+      }),
+    }).annotate({ title: "LocalShellCallResponseItem" }),
+    Schema.Struct({
+      arguments: Schema.String,
+      call_id: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      name: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("function_call").annotate({ title: "FunctionCallResponseItemType" }),
+    }).annotate({ title: "FunctionCallResponseItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      call_id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      execution: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("tool_search_call").annotate({
+        title: "ToolSearchCallResponseItemType",
+      }),
+    }).annotate({ title: "ToolSearchCallResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      output: V2RawResponseItemCompletedNotification__FunctionCallOutputBody,
+      type: Schema.Literal("function_call_output").annotate({
+        title: "FunctionCallOutputResponseItemType",
+      }),
+    }).annotate({ title: "FunctionCallOutputResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      input: Schema.String,
+      name: Schema.String,
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("custom_tool_call").annotate({
+        title: "CustomToolCallResponseItemType",
+      }),
+    }).annotate({ title: "CustomToolCallResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      name: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      output: V2RawResponseItemCompletedNotification__FunctionCallOutputBody,
+      type: Schema.Literal("custom_tool_call_output").annotate({
+        title: "CustomToolCallOutputResponseItemType",
+      }),
+    }).annotate({ title: "CustomToolCallOutputResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      execution: Schema.String,
+      status: Schema.String,
+      tools: Schema.Array(Schema.Unknown),
+      type: Schema.Literal("tool_search_output").annotate({
+        title: "ToolSearchOutputResponseItemType",
+      }),
+    }).annotate({ title: "ToolSearchOutputResponseItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([
+          V2RawResponseItemCompletedNotification__ResponsesApiWebSearchAction,
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("web_search_call").annotate({ title: "WebSearchCallResponseItemType" }),
+    }).annotate({ title: "WebSearchCallResponseItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revised_prompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: Schema.String,
+      type: Schema.Literal("image_generation_call").annotate({
+        title: "ImageGenerationCallResponseItemType",
+      }),
+    }).annotate({ title: "ImageGenerationCallResponseItem" }),
+    Schema.Struct({
+      encrypted_content: Schema.String,
+      type: Schema.Literal("compaction").annotate({ title: "CompactionResponseItemType" }),
+    }).annotate({ title: "CompactionResponseItem" }),
+    Schema.Struct({
+      encrypted_content: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("context_compaction").annotate({
+        title: "ContextCompactionResponseItemType",
+      }),
+    }).annotate({ title: "ContextCompactionResponseItem" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherResponseItemType" }),
+    }).annotate({ title: "OtherResponseItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ReviewStartResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ReviewStartResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ReviewStartResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ReviewStartResponse__TurnStatus;
+};
+export const V2ReviewStartResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ReviewStartResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ReviewStartResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ReviewStartResponse__TurnStatus,
+});
+
+export type V2SkillsListResponse__SkillsListEntry = {
+  readonly cwd: string;
+  readonly errors: ReadonlyArray<V2SkillsListResponse__SkillErrorInfo>;
+  readonly skills: ReadonlyArray<V2SkillsListResponse__SkillMetadata>;
+};
+export const V2SkillsListResponse__SkillsListEntry = Schema.Struct({
+  cwd: Schema.String,
+  errors: Schema.Array(V2SkillsListResponse__SkillErrorInfo),
+  skills: Schema.Array(V2SkillsListResponse__SkillMetadata),
+});
+
+export type V2ThreadForkResponse__PermissionProfileFileSystemPermissions =
+  | {
+      readonly entries: ReadonlyArray<V2ThreadForkResponse__FileSystemSandboxEntry>;
+      readonly globScanMaxDepth?: number | null;
+      readonly type: "restricted";
+    }
+  | { readonly type: "unrestricted" };
+export const V2ThreadForkResponse__PermissionProfileFileSystemPermissions = Schema.Union(
+  [
+    Schema.Struct({
+      entries: Schema.Array(V2ThreadForkResponse__FileSystemSandboxEntry),
+      globScanMaxDepth: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(1)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("restricted").annotate({
+        title: "RestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "RestrictedPermissionProfileFileSystemPermissions" }),
+    Schema.Struct({
+      type: Schema.Literal("unrestricted").annotate({
+        title: "UnrestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "UnrestrictedPermissionProfileFileSystemPermissions" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadForkResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadForkResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadForkResponse__TurnStatus;
+};
+export const V2ThreadForkResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadForkResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadForkResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadForkResponse__TurnStatus,
+});
+
+export type V2ThreadListResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadListResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadListResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadListResponse__TurnStatus;
+};
+export const V2ThreadListResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadListResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadListResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadListResponse__TurnStatus,
+});
+
+export type V2ThreadMetadataUpdateResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadMetadataUpdateResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadMetadataUpdateResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadMetadataUpdateResponse__TurnStatus;
+};
+export const V2ThreadMetadataUpdateResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadMetadataUpdateResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadMetadataUpdateResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadMetadataUpdateResponse__TurnStatus,
+});
+
+export type V2ThreadReadResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadReadResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadReadResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadReadResponse__TurnStatus;
+};
+export const V2ThreadReadResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadReadResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadReadResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadReadResponse__TurnStatus,
+});
+
+export type V2ThreadResumeResponse__PermissionProfileFileSystemPermissions =
+  | {
+      readonly entries: ReadonlyArray<V2ThreadResumeResponse__FileSystemSandboxEntry>;
+      readonly globScanMaxDepth?: number | null;
+      readonly type: "restricted";
+    }
+  | { readonly type: "unrestricted" };
+export const V2ThreadResumeResponse__PermissionProfileFileSystemPermissions = Schema.Union(
+  [
+    Schema.Struct({
+      entries: Schema.Array(V2ThreadResumeResponse__FileSystemSandboxEntry),
+      globScanMaxDepth: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(1)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("restricted").annotate({
+        title: "RestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "RestrictedPermissionProfileFileSystemPermissions" }),
+    Schema.Struct({
+      type: Schema.Literal("unrestricted").annotate({
+        title: "UnrestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "UnrestrictedPermissionProfileFileSystemPermissions" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadResumeResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadResumeResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadResumeResponse__TurnStatus;
+};
+export const V2ThreadResumeResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadResumeResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadResumeResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadResumeResponse__TurnStatus,
+});
+
+export type V2ThreadRollbackResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadRollbackResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadRollbackResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadRollbackResponse__TurnStatus;
+};
+export const V2ThreadRollbackResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadRollbackResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadRollbackResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadRollbackResponse__TurnStatus,
+});
+
+export type V2ThreadStartedNotification__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadStartedNotification__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadStartedNotification__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadStartedNotification__TurnStatus;
+};
+export const V2ThreadStartedNotification__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadStartedNotification__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadStartedNotification__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadStartedNotification__TurnStatus,
+});
+
+export type V2ThreadStartResponse__PermissionProfileFileSystemPermissions =
+  | {
+      readonly entries: ReadonlyArray<V2ThreadStartResponse__FileSystemSandboxEntry>;
+      readonly globScanMaxDepth?: number | null;
+      readonly type: "restricted";
+    }
+  | { readonly type: "unrestricted" };
+export const V2ThreadStartResponse__PermissionProfileFileSystemPermissions = Schema.Union(
+  [
+    Schema.Struct({
+      entries: Schema.Array(V2ThreadStartResponse__FileSystemSandboxEntry),
+      globScanMaxDepth: Schema.optionalKey(
+        Schema.Union([
+          Schema.Number.annotate({ format: "uint" })
+            .check(Schema.isInt())
+            .check(Schema.isGreaterThanOrEqualTo(1)),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("restricted").annotate({
+        title: "RestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "RestrictedPermissionProfileFileSystemPermissions" }),
+    Schema.Struct({
+      type: Schema.Literal("unrestricted").annotate({
+        title: "UnrestrictedPermissionProfileFileSystemPermissionsType",
+      }),
+    }).annotate({ title: "UnrestrictedPermissionProfileFileSystemPermissions" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadStartResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadStartResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadStartResponse__TurnStatus;
+};
+export const V2ThreadStartResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadStartResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadStartResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadStartResponse__TurnStatus,
+});
+
+export type V2ThreadUnarchiveResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2ThreadUnarchiveResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2ThreadUnarchiveResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2ThreadUnarchiveResponse__TurnStatus;
+};
+export const V2ThreadUnarchiveResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2ThreadUnarchiveResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2ThreadUnarchiveResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2ThreadUnarchiveResponse__TurnStatus,
+});
+
+export type V2TurnCompletedNotification__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2TurnCompletedNotification__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2TurnCompletedNotification__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2TurnCompletedNotification__TurnStatus;
+};
+export const V2TurnCompletedNotification__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2TurnCompletedNotification__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2TurnCompletedNotification__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2TurnCompletedNotification__TurnStatus,
+});
+
+export type V2TurnStartedNotification__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2TurnStartedNotification__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2TurnStartedNotification__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2TurnStartedNotification__TurnStatus;
+};
+export const V2TurnStartedNotification__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2TurnStartedNotification__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2TurnStartedNotification__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2TurnStartedNotification__TurnStatus,
+});
+
+export type V2TurnStartResponse__Turn = {
+  readonly completedAt?: number | null;
+  readonly durationMs?: number | null;
+  readonly error?: V2TurnStartResponse__TurnError | null;
+  readonly id: string;
+  readonly items: ReadonlyArray<V2TurnStartResponse__ThreadItem>;
+  readonly itemsView?: "notLoaded" | "summary" | "full";
+  readonly startedAt?: number | null;
+  readonly status: V2TurnStartResponse__TurnStatus;
+};
+export const V2TurnStartResponse__Turn = Schema.Struct({
+  completedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn completed.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  durationMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Duration between turn start and completion in milliseconds, if known.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  error: Schema.optionalKey(
+    Schema.Union([V2TurnStartResponse__TurnError, Schema.Null]).annotate({
+      description: "Only populated when the Turn's status is failed.",
+    }),
+  ),
+  id: Schema.String,
+  items: Schema.Array(V2TurnStartResponse__ThreadItem).annotate({
+    description: "Thread items currently included in this turn payload.",
+  }),
+  itemsView: Schema.optionalKey(
+    Schema.Literals(["notLoaded", "summary", "full"]).annotate({
+      description: "Describes how much of `items` has been loaded for this turn.",
+      default: "full",
+    }),
+  ),
+  startedAt: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Unix timestamp (in seconds) when the turn started.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  status: V2TurnStartResponse__TurnStatus,
+});
+
+export type McpServerElicitationRequestParams__McpElicitationEnumSchema =
+  | McpServerElicitationRequestParams__McpElicitationSingleSelectEnumSchema
+  | McpServerElicitationRequestParams__McpElicitationMultiSelectEnumSchema
+  | McpServerElicitationRequestParams__McpElicitationLegacyTitledEnumSchema;
+export const McpServerElicitationRequestParams__McpElicitationEnumSchema = Schema.Union([
+  McpServerElicitationRequestParams__McpElicitationSingleSelectEnumSchema,
+  McpServerElicitationRequestParams__McpElicitationMultiSelectEnumSchema,
+  McpServerElicitationRequestParams__McpElicitationLegacyTitledEnumSchema,
+]);
+
+export type PermissionsRequestApprovalParams__RequestPermissionProfile = {
+  readonly fileSystem?: PermissionsRequestApprovalParams__AdditionalFileSystemPermissions | null;
+  readonly network?: PermissionsRequestApprovalParams__AdditionalNetworkPermissions | null;
+};
+export const PermissionsRequestApprovalParams__RequestPermissionProfile = Schema.Struct({
+  fileSystem: Schema.optionalKey(
+    Schema.Union([PermissionsRequestApprovalParams__AdditionalFileSystemPermissions, Schema.Null]),
+  ),
+  network: Schema.optionalKey(
+    Schema.Union([PermissionsRequestApprovalParams__AdditionalNetworkPermissions, Schema.Null]),
+  ),
+});
+
+export type PermissionsRequestApprovalResponse__GrantedPermissionProfile = {
+  readonly fileSystem?: PermissionsRequestApprovalResponse__AdditionalFileSystemPermissions | null;
+  readonly network?: PermissionsRequestApprovalResponse__AdditionalNetworkPermissions | null;
+};
+export const PermissionsRequestApprovalResponse__GrantedPermissionProfile = Schema.Struct({
+  fileSystem: Schema.optionalKey(
+    Schema.Union([
+      PermissionsRequestApprovalResponse__AdditionalFileSystemPermissions,
+      Schema.Null,
+    ]),
+  ),
+  network: Schema.optionalKey(
+    Schema.Union([PermissionsRequestApprovalResponse__AdditionalNetworkPermissions, Schema.Null]),
+  ),
+});
+
+export type ServerNotification__RequestPermissionProfile = {
+  readonly fileSystem?: ServerNotification__AdditionalFileSystemPermissions | null;
+  readonly network?: ServerNotification__AdditionalNetworkPermissions | null;
+};
+export const ServerNotification__RequestPermissionProfile = Schema.Struct({
+  fileSystem: Schema.optionalKey(
+    Schema.Union([ServerNotification__AdditionalFileSystemPermissions, Schema.Null]),
+  ),
+  network: Schema.optionalKey(
+    Schema.Union([ServerNotification__AdditionalNetworkPermissions, Schema.Null]),
+  ),
+});
+
+export type ServerNotification__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: ServerNotification__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: ServerNotification__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<ServerNotification__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: ServerNotification__ThreadSource | null;
+  readonly turns: ReadonlyArray<ServerNotification__Turn>;
+  readonly updatedAt: number;
+};
+export const ServerNotification__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([ServerNotification__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: ServerNotification__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(ServerNotification__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([ServerNotification__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(ServerNotification__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type ServerNotification__TurnCompletedNotification = {
+  readonly threadId: string;
+  readonly turn: ServerNotification__Turn;
+};
+export const ServerNotification__TurnCompletedNotification = Schema.Struct({
+  threadId: Schema.String,
+  turn: ServerNotification__Turn,
+});
+
+export type ServerNotification__TurnStartedNotification = {
+  readonly threadId: string;
+  readonly turn: ServerNotification__Turn;
+};
+export const ServerNotification__TurnStartedNotification = Schema.Struct({
+  threadId: Schema.String,
+  turn: ServerNotification__Turn,
+});
+
+export type ServerRequest__RequestPermissionProfile = {
+  readonly fileSystem?: ServerRequest__AdditionalFileSystemPermissions | null;
+  readonly network?: ServerRequest__AdditionalNetworkPermissions | null;
+};
+export const ServerRequest__RequestPermissionProfile = Schema.Struct({
+  fileSystem: Schema.optionalKey(
+    Schema.Union([ServerRequest__AdditionalFileSystemPermissions, Schema.Null]),
+  ),
+  network: Schema.optionalKey(
+    Schema.Union([ServerRequest__AdditionalNetworkPermissions, Schema.Null]),
+  ),
+});
+
+export type ServerRequest__McpElicitationEnumSchema =
+  | ServerRequest__McpElicitationSingleSelectEnumSchema
+  | ServerRequest__McpElicitationMultiSelectEnumSchema
+  | ServerRequest__McpElicitationLegacyTitledEnumSchema;
+export const ServerRequest__McpElicitationEnumSchema = Schema.Union([
+  ServerRequest__McpElicitationSingleSelectEnumSchema,
+  ServerRequest__McpElicitationMultiSelectEnumSchema,
+  ServerRequest__McpElicitationLegacyTitledEnumSchema,
+]);
+
+export type V2ConfigReadResponse__Config = {
+  readonly analytics?: V2ConfigReadResponse__AnalyticsConfig | null;
+  readonly approval_policy?: V2ConfigReadResponse__AskForApproval | null;
+  readonly approvals_reviewer?: V2ConfigReadResponse__ApprovalsReviewer | null;
+  readonly compact_prompt?: string | null;
+  readonly developer_instructions?: string | null;
+  readonly forced_chatgpt_workspace_id?: string | null;
+  readonly forced_login_method?: V2ConfigReadResponse__ForcedLoginMethod | null;
+  readonly instructions?: string | null;
+  readonly model?: string | null;
+  readonly model_auto_compact_token_limit?: number | null;
+  readonly model_context_window?: number | null;
+  readonly model_provider?: string | null;
+  readonly model_reasoning_effort?: V2ConfigReadResponse__ReasoningEffort | null;
+  readonly model_reasoning_summary?: V2ConfigReadResponse__ReasoningSummary | null;
+  readonly model_verbosity?: V2ConfigReadResponse__Verbosity | null;
+  readonly profile?: string | null;
+  readonly profiles?: { readonly [x: string]: V2ConfigReadResponse__ProfileV2 };
+  readonly review_model?: string | null;
+  readonly sandbox_mode?: V2ConfigReadResponse__SandboxMode | null;
+  readonly sandbox_workspace_write?: V2ConfigReadResponse__SandboxWorkspaceWrite | null;
+  readonly service_tier?: string | null;
+  readonly tools?: V2ConfigReadResponse__ToolsV2 | null;
+  readonly web_search?: V2ConfigReadResponse__WebSearchMode | null;
+  readonly [x: string]: unknown;
+};
+export const V2ConfigReadResponse__Config = Schema.StructWithRest(
+  Schema.Struct({
+    analytics: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__AnalyticsConfig, Schema.Null]),
+    ),
+    approval_policy: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__AskForApproval, Schema.Null]),
+    ),
+    approvals_reviewer: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__ApprovalsReviewer, Schema.Null]).annotate({
+        description:
+          "[UNSTABLE] Optional default for where approval requests are routed for review.",
+      }),
+    ),
+    compact_prompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    developer_instructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    forced_chatgpt_workspace_id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    forced_login_method: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__ForcedLoginMethod, Schema.Null]),
+    ),
+    instructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    model: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    model_auto_compact_token_limit: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+        Schema.Null,
+      ]),
+    ),
+    model_context_window: Schema.optionalKey(
+      Schema.Union([
+        Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+        Schema.Null,
+      ]),
+    ),
+    model_provider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    model_reasoning_effort: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__ReasoningEffort, Schema.Null]),
+    ),
+    model_reasoning_summary: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__ReasoningSummary, Schema.Null]),
+    ),
+    model_verbosity: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__Verbosity, Schema.Null]),
+    ),
+    profile: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    profiles: Schema.optionalKey(
+      Schema.Record(Schema.String, V2ConfigReadResponse__ProfileV2).annotate({ default: {} }),
+    ),
+    review_model: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    sandbox_mode: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__SandboxMode, Schema.Null]),
+    ),
+    sandbox_workspace_write: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__SandboxWorkspaceWrite, Schema.Null]),
+    ),
+    service_tier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    tools: Schema.optionalKey(Schema.Union([V2ConfigReadResponse__ToolsV2, Schema.Null])),
+    web_search: Schema.optionalKey(
+      Schema.Union([V2ConfigReadResponse__WebSearchMode, Schema.Null]),
+    ),
+  }),
+  [Schema.Record(Schema.String, Schema.Unknown)],
+);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__RequestPermissionProfile = {
+  readonly fileSystem?: V2ItemGuardianApprovalReviewCompletedNotification__AdditionalFileSystemPermissions | null;
+  readonly network?: V2ItemGuardianApprovalReviewCompletedNotification__AdditionalNetworkPermissions | null;
+};
+export const V2ItemGuardianApprovalReviewCompletedNotification__RequestPermissionProfile =
+  Schema.Struct({
+    fileSystem: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewCompletedNotification__AdditionalFileSystemPermissions,
+        Schema.Null,
+      ]),
+    ),
+    network: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewCompletedNotification__AdditionalNetworkPermissions,
+        Schema.Null,
+      ]),
+    ),
+  });
+
+export type V2ItemGuardianApprovalReviewStartedNotification__RequestPermissionProfile = {
+  readonly fileSystem?: V2ItemGuardianApprovalReviewStartedNotification__AdditionalFileSystemPermissions | null;
+  readonly network?: V2ItemGuardianApprovalReviewStartedNotification__AdditionalNetworkPermissions | null;
+};
+export const V2ItemGuardianApprovalReviewStartedNotification__RequestPermissionProfile =
+  Schema.Struct({
+    fileSystem: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewStartedNotification__AdditionalFileSystemPermissions,
+        Schema.Null,
+      ]),
+    ),
+    network: Schema.optionalKey(
+      Schema.Union([
+        V2ItemGuardianApprovalReviewStartedNotification__AdditionalNetworkPermissions,
+        Schema.Null,
+      ]),
+    ),
+  });
+
+export type V2PluginListResponse__PluginMarketplaceEntry = {
+  readonly interface?: V2PluginListResponse__MarketplaceInterface | null;
+  readonly name: string;
+  readonly path?: V2PluginListResponse__AbsolutePathBuf | null;
+  readonly plugins: ReadonlyArray<V2PluginListResponse__PluginSummary>;
+};
+export const V2PluginListResponse__PluginMarketplaceEntry = Schema.Struct({
+  interface: Schema.optionalKey(
+    Schema.Union([V2PluginListResponse__MarketplaceInterface, Schema.Null]),
+  ),
+  name: Schema.String,
+  path: Schema.optionalKey(
+    Schema.Union([V2PluginListResponse__AbsolutePathBuf, Schema.Null]).annotate({
+      description:
+        "Local marketplace file path when the marketplace is backed by a local file. Remote-only catalog marketplaces do not have a local path.",
+    }),
+  ),
+  plugins: Schema.Array(V2PluginListResponse__PluginSummary),
+});
+
+export type V2PluginReadResponse__PluginDetail = {
+  readonly apps: ReadonlyArray<V2PluginReadResponse__AppSummary>;
+  readonly description?: string | null;
+  readonly hooks: ReadonlyArray<V2PluginReadResponse__PluginHookSummary>;
+  readonly marketplaceName: string;
+  readonly marketplacePath?: V2PluginReadResponse__AbsolutePathBuf | null;
+  readonly mcpServers: ReadonlyArray<string>;
+  readonly skills: ReadonlyArray<V2PluginReadResponse__SkillSummary>;
+  readonly summary: V2PluginReadResponse__PluginSummary;
+};
+export const V2PluginReadResponse__PluginDetail = Schema.Struct({
+  apps: Schema.Array(V2PluginReadResponse__AppSummary),
+  description: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  hooks: Schema.Array(V2PluginReadResponse__PluginHookSummary),
+  marketplaceName: Schema.String,
+  marketplacePath: Schema.optionalKey(
+    Schema.Union([V2PluginReadResponse__AbsolutePathBuf, Schema.Null]),
+  ),
+  mcpServers: Schema.Array(Schema.String),
+  skills: Schema.Array(V2PluginReadResponse__SkillSummary),
+  summary: V2PluginReadResponse__PluginSummary,
+});
+
+export type V2PluginShareListResponse__PluginShareListItem = {
+  readonly localPluginPath?: V2PluginShareListResponse__AbsolutePathBuf | null;
+  readonly plugin: V2PluginShareListResponse__PluginSummary;
+  readonly shareUrl: string;
+};
+export const V2PluginShareListResponse__PluginShareListItem = Schema.Struct({
+  localPluginPath: Schema.optionalKey(
+    Schema.Union([V2PluginShareListResponse__AbsolutePathBuf, Schema.Null]),
+  ),
+  plugin: V2PluginShareListResponse__PluginSummary,
+  shareUrl: Schema.String,
+});
+
+export type V2ThreadForkResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadForkResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadForkResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadForkResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadForkResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadForkResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadForkResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadForkResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadForkResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadForkResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadForkResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadForkResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadListResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadListResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadListResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadListResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadListResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadListResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadListResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadListResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadListResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadListResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadListResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadListResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadMetadataUpdateResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadMetadataUpdateResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadMetadataUpdateResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadMetadataUpdateResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadMetadataUpdateResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadMetadataUpdateResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadMetadataUpdateResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadMetadataUpdateResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadMetadataUpdateResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadMetadataUpdateResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadMetadataUpdateResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadMetadataUpdateResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadReadResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadReadResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadReadResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadReadResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadReadResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadReadResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadReadResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadReadResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadReadResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadReadResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadReadResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadReadResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadResumeResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadResumeResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadResumeResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadResumeResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadResumeResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadResumeResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadResumeResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadResumeResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadResumeResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadResumeResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadResumeResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadResumeResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadStartedNotification__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadStartedNotification__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadStartedNotification__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadStartedNotification__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadStartedNotification__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadStartedNotification__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadStartedNotification__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadStartedNotification__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadStartedNotification__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadStartedNotification__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadStartedNotification__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadStartedNotification__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadStartResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadStartResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadStartResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadStartResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadStartResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadStartResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadStartResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadStartResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadStartResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadStartResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadStartResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadStartResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadUnarchiveResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadUnarchiveResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadUnarchiveResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadUnarchiveResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadUnarchiveResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadUnarchiveResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadUnarchiveResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadUnarchiveResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadUnarchiveResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadUnarchiveResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadUnarchiveResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadUnarchiveResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type McpServerElicitationRequestParams__McpElicitationPrimitiveSchema =
+  | McpServerElicitationRequestParams__McpElicitationEnumSchema
+  | McpServerElicitationRequestParams__McpElicitationStringSchema
+  | McpServerElicitationRequestParams__McpElicitationNumberSchema
+  | McpServerElicitationRequestParams__McpElicitationBooleanSchema;
+export const McpServerElicitationRequestParams__McpElicitationPrimitiveSchema = Schema.Union([
+  McpServerElicitationRequestParams__McpElicitationEnumSchema,
+  McpServerElicitationRequestParams__McpElicitationStringSchema,
+  McpServerElicitationRequestParams__McpElicitationNumberSchema,
+  McpServerElicitationRequestParams__McpElicitationBooleanSchema,
+]);
+
+export type ServerNotification__GuardianApprovalReviewAction =
+  | {
+      readonly command: string;
+      readonly cwd: ServerNotification__AbsolutePathBuf;
+      readonly source: ServerNotification__GuardianCommandSource;
+      readonly type: "command";
+    }
+  | {
+      readonly argv: ReadonlyArray<string>;
+      readonly cwd: ServerNotification__AbsolutePathBuf;
+      readonly program: string;
+      readonly source: ServerNotification__GuardianCommandSource;
+      readonly type: "execve";
+    }
+  | {
+      readonly cwd: ServerNotification__AbsolutePathBuf;
+      readonly files: ReadonlyArray<ServerNotification__AbsolutePathBuf>;
+      readonly type: "applyPatch";
+    }
+  | {
+      readonly host: string;
+      readonly port: number;
+      readonly protocol: ServerNotification__NetworkApprovalProtocol;
+      readonly target: string;
+      readonly type: "networkAccess";
+    }
+  | {
+      readonly connectorId?: string | null;
+      readonly connectorName?: string | null;
+      readonly server: string;
+      readonly toolName: string;
+      readonly toolTitle?: string | null;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly permissions: ServerNotification__RequestPermissionProfile;
+      readonly reason?: string | null;
+      readonly type: "requestPermissions";
+    };
+export const ServerNotification__GuardianApprovalReviewAction = Schema.Union(
+  [
+    Schema.Struct({
+      command: Schema.String,
+      cwd: ServerNotification__AbsolutePathBuf,
+      source: ServerNotification__GuardianCommandSource,
+      type: Schema.Literal("command").annotate({
+        title: "CommandGuardianApprovalReviewActionType",
+      }),
+    }).annotate({ title: "CommandGuardianApprovalReviewAction" }),
+    Schema.Struct({
+      argv: Schema.Array(Schema.String),
+      cwd: ServerNotification__AbsolutePathBuf,
+      program: Schema.String,
+      source: ServerNotification__GuardianCommandSource,
+      type: Schema.Literal("execve").annotate({ title: "ExecveGuardianApprovalReviewActionType" }),
+    }).annotate({ title: "ExecveGuardianApprovalReviewAction" }),
+    Schema.Struct({
+      cwd: ServerNotification__AbsolutePathBuf,
+      files: Schema.Array(ServerNotification__AbsolutePathBuf),
+      type: Schema.Literal("applyPatch").annotate({
+        title: "ApplyPatchGuardianApprovalReviewActionType",
+      }),
+    }).annotate({ title: "ApplyPatchGuardianApprovalReviewAction" }),
+    Schema.Struct({
+      host: Schema.String,
+      port: Schema.Number.annotate({ format: "uint16" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      protocol: ServerNotification__NetworkApprovalProtocol,
+      target: Schema.String,
+      type: Schema.Literal("networkAccess").annotate({
+        title: "NetworkAccessGuardianApprovalReviewActionType",
+      }),
+    }).annotate({ title: "NetworkAccessGuardianApprovalReviewAction" }),
+    Schema.Struct({
+      connectorId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      connectorName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      server: Schema.String,
+      toolName: Schema.String,
+      toolTitle: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("mcpToolCall").annotate({
+        title: "McpToolCallGuardianApprovalReviewActionType",
+      }),
+    }).annotate({ title: "McpToolCallGuardianApprovalReviewAction" }),
+    Schema.Struct({
+      permissions: ServerNotification__RequestPermissionProfile,
+      reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("requestPermissions").annotate({
+        title: "RequestPermissionsGuardianApprovalReviewActionType",
+      }),
+    }).annotate({ title: "RequestPermissionsGuardianApprovalReviewAction" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__ThreadStartedNotification = {
+  readonly thread: ServerNotification__Thread;
+};
+export const ServerNotification__ThreadStartedNotification = Schema.Struct({
+  thread: ServerNotification__Thread,
+});
+
+export type ServerRequest__PermissionsRequestApprovalParams = {
+  readonly cwd: ServerRequest__AbsolutePathBuf;
+  readonly itemId: string;
+  readonly permissions: ServerRequest__RequestPermissionProfile;
+  readonly reason?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerRequest__PermissionsRequestApprovalParams = Schema.Struct({
+  cwd: ServerRequest__AbsolutePathBuf,
+  itemId: Schema.String,
+  permissions: ServerRequest__RequestPermissionProfile,
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  turnId: Schema.String,
+});
+
+export type ServerRequest__McpElicitationPrimitiveSchema =
+  | ServerRequest__McpElicitationEnumSchema
+  | ServerRequest__McpElicitationStringSchema
+  | ServerRequest__McpElicitationNumberSchema
+  | ServerRequest__McpElicitationBooleanSchema;
+export const ServerRequest__McpElicitationPrimitiveSchema = Schema.Union([
+  ServerRequest__McpElicitationEnumSchema,
+  ServerRequest__McpElicitationStringSchema,
+  ServerRequest__McpElicitationNumberSchema,
+  ServerRequest__McpElicitationBooleanSchema,
+]);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewAction =
+  | {
+      readonly command: string;
+      readonly cwd: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf;
+      readonly source: V2ItemGuardianApprovalReviewCompletedNotification__GuardianCommandSource;
+      readonly type: "command";
+    }
+  | {
+      readonly argv: ReadonlyArray<string>;
+      readonly cwd: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf;
+      readonly program: string;
+      readonly source: V2ItemGuardianApprovalReviewCompletedNotification__GuardianCommandSource;
+      readonly type: "execve";
+    }
+  | {
+      readonly cwd: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf;
+      readonly files: ReadonlyArray<V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf>;
+      readonly type: "applyPatch";
+    }
+  | {
+      readonly host: string;
+      readonly port: number;
+      readonly protocol: V2ItemGuardianApprovalReviewCompletedNotification__NetworkApprovalProtocol;
+      readonly target: string;
+      readonly type: "networkAccess";
+    }
+  | {
+      readonly connectorId?: string | null;
+      readonly connectorName?: string | null;
+      readonly server: string;
+      readonly toolName: string;
+      readonly toolTitle?: string | null;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly permissions: V2ItemGuardianApprovalReviewCompletedNotification__RequestPermissionProfile;
+      readonly reason?: string | null;
+      readonly type: "requestPermissions";
+    };
+export const V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewAction =
+  Schema.Union(
+    [
+      Schema.Struct({
+        command: Schema.String,
+        cwd: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf,
+        source: V2ItemGuardianApprovalReviewCompletedNotification__GuardianCommandSource,
+        type: Schema.Literal("command").annotate({
+          title: "CommandGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "CommandGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        argv: Schema.Array(Schema.String),
+        cwd: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf,
+        program: Schema.String,
+        source: V2ItemGuardianApprovalReviewCompletedNotification__GuardianCommandSource,
+        type: Schema.Literal("execve").annotate({
+          title: "ExecveGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "ExecveGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        cwd: V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf,
+        files: Schema.Array(V2ItemGuardianApprovalReviewCompletedNotification__AbsolutePathBuf),
+        type: Schema.Literal("applyPatch").annotate({
+          title: "ApplyPatchGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "ApplyPatchGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        host: Schema.String,
+        port: Schema.Number.annotate({ format: "uint16" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        protocol: V2ItemGuardianApprovalReviewCompletedNotification__NetworkApprovalProtocol,
+        target: Schema.String,
+        type: Schema.Literal("networkAccess").annotate({
+          title: "NetworkAccessGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "NetworkAccessGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        connectorId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        connectorName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        server: Schema.String,
+        toolName: Schema.String,
+        toolTitle: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        type: Schema.Literal("mcpToolCall").annotate({
+          title: "McpToolCallGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "McpToolCallGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        permissions: V2ItemGuardianApprovalReviewCompletedNotification__RequestPermissionProfile,
+        reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        type: Schema.Literal("requestPermissions").annotate({
+          title: "RequestPermissionsGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "RequestPermissionsGuardianApprovalReviewAction" }),
+    ],
+    { mode: "oneOf" },
+  );
+
+export type V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewAction =
+  | {
+      readonly command: string;
+      readonly cwd: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf;
+      readonly source: V2ItemGuardianApprovalReviewStartedNotification__GuardianCommandSource;
+      readonly type: "command";
+    }
+  | {
+      readonly argv: ReadonlyArray<string>;
+      readonly cwd: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf;
+      readonly program: string;
+      readonly source: V2ItemGuardianApprovalReviewStartedNotification__GuardianCommandSource;
+      readonly type: "execve";
+    }
+  | {
+      readonly cwd: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf;
+      readonly files: ReadonlyArray<V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf>;
+      readonly type: "applyPatch";
+    }
+  | {
+      readonly host: string;
+      readonly port: number;
+      readonly protocol: V2ItemGuardianApprovalReviewStartedNotification__NetworkApprovalProtocol;
+      readonly target: string;
+      readonly type: "networkAccess";
+    }
+  | {
+      readonly connectorId?: string | null;
+      readonly connectorName?: string | null;
+      readonly server: string;
+      readonly toolName: string;
+      readonly toolTitle?: string | null;
+      readonly type: "mcpToolCall";
+    }
+  | {
+      readonly permissions: V2ItemGuardianApprovalReviewStartedNotification__RequestPermissionProfile;
+      readonly reason?: string | null;
+      readonly type: "requestPermissions";
+    };
+export const V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewAction =
+  Schema.Union(
+    [
+      Schema.Struct({
+        command: Schema.String,
+        cwd: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf,
+        source: V2ItemGuardianApprovalReviewStartedNotification__GuardianCommandSource,
+        type: Schema.Literal("command").annotate({
+          title: "CommandGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "CommandGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        argv: Schema.Array(Schema.String),
+        cwd: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf,
+        program: Schema.String,
+        source: V2ItemGuardianApprovalReviewStartedNotification__GuardianCommandSource,
+        type: Schema.Literal("execve").annotate({
+          title: "ExecveGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "ExecveGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        cwd: V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf,
+        files: Schema.Array(V2ItemGuardianApprovalReviewStartedNotification__AbsolutePathBuf),
+        type: Schema.Literal("applyPatch").annotate({
+          title: "ApplyPatchGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "ApplyPatchGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        host: Schema.String,
+        port: Schema.Number.annotate({ format: "uint16" })
+          .check(Schema.isInt())
+          .check(Schema.isGreaterThanOrEqualTo(0)),
+        protocol: V2ItemGuardianApprovalReviewStartedNotification__NetworkApprovalProtocol,
+        target: Schema.String,
+        type: Schema.Literal("networkAccess").annotate({
+          title: "NetworkAccessGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "NetworkAccessGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        connectorId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        connectorName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        server: Schema.String,
+        toolName: Schema.String,
+        toolTitle: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        type: Schema.Literal("mcpToolCall").annotate({
+          title: "McpToolCallGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "McpToolCallGuardianApprovalReviewAction" }),
+      Schema.Struct({
+        permissions: V2ItemGuardianApprovalReviewStartedNotification__RequestPermissionProfile,
+        reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+        type: Schema.Literal("requestPermissions").annotate({
+          title: "RequestPermissionsGuardianApprovalReviewActionType",
+        }),
+      }).annotate({ title: "RequestPermissionsGuardianApprovalReviewAction" }),
+    ],
+    { mode: "oneOf" },
+  );
+
+export type McpServerElicitationRequestParams__McpElicitationSchema = {
+  readonly $schema?: string | null;
+  readonly properties: {
+    readonly [x: string]: McpServerElicitationRequestParams__McpElicitationPrimitiveSchema;
+  };
+  readonly required?: ReadonlyArray<string> | null;
+  readonly type: McpServerElicitationRequestParams__McpElicitationObjectType;
+};
+export const McpServerElicitationRequestParams__McpElicitationSchema = Schema.Struct({
+  $schema: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  properties: Schema.Record(
+    Schema.String,
+    McpServerElicitationRequestParams__McpElicitationPrimitiveSchema,
+  ),
+  required: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  type: McpServerElicitationRequestParams__McpElicitationObjectType,
+}).annotate({
+  description:
+    "Typed form schema for MCP `elicitation/create` requests.\n\nThis matches the `requestedSchema` shape from the MCP 2025-11-25 `ElicitRequestFormParams` schema.",
+});
+
+export type ServerNotification__ItemGuardianApprovalReviewCompletedNotification = {
+  readonly action: ServerNotification__GuardianApprovalReviewAction;
+  readonly decisionSource: ServerNotification__AutoReviewDecisionSource;
+  readonly review: ServerNotification__GuardianApprovalReview;
+  readonly reviewId: string;
+  readonly targetItemId?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ItemGuardianApprovalReviewCompletedNotification = Schema.Struct({
+  action: ServerNotification__GuardianApprovalReviewAction,
+  decisionSource: ServerNotification__AutoReviewDecisionSource,
+  review: ServerNotification__GuardianApprovalReview,
+  reviewId: Schema.String.annotate({ description: "Stable identifier for this review." }),
+  targetItemId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Identifier for the reviewed item or tool call when one exists.\n\nIn most cases, one review maps to one target item. The exceptions are - execve reviews, where a single command may contain multiple execve calls to review (only possible when using the shell_zsh_fork feature) - network policy reviews, where there is no target item\n\nA network call is triggered by a CommandExecution item, so having a target_item_id set to the CommandExecution item would be misleading because the review is about the network call, not the command execution. Therefore, target_item_id is set to None for network policy reviews.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  description:
+    "[UNSTABLE] Temporary notification payload for approval auto-review. This shape is expected to change soon.",
+});
+
+export type ServerNotification__ItemGuardianApprovalReviewStartedNotification = {
+  readonly action: ServerNotification__GuardianApprovalReviewAction;
+  readonly review: ServerNotification__GuardianApprovalReview;
+  readonly reviewId: string;
+  readonly targetItemId?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ServerNotification__ItemGuardianApprovalReviewStartedNotification = Schema.Struct({
+  action: ServerNotification__GuardianApprovalReviewAction,
+  review: ServerNotification__GuardianApprovalReview,
+  reviewId: Schema.String.annotate({ description: "Stable identifier for this review." }),
+  targetItemId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Identifier for the reviewed item or tool call when one exists.\n\nIn most cases, one review maps to one target item. The exceptions are - execve reviews, where a single command may contain multiple execve calls to review (only possible when using the shell_zsh_fork feature) - network policy reviews, where there is no target item\n\nA network call is triggered by a CommandExecution item, so having a target_item_id set to the CommandExecution item would be misleading because the review is about the network call, not the command execution. Therefore, target_item_id is set to None for network policy reviews.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  description:
+    "[UNSTABLE] Temporary notification payload for approval auto-review. This shape is expected to change soon.",
+});
+
+export type ServerRequest__McpElicitationSchema = {
+  readonly $schema?: string | null;
+  readonly properties: { readonly [x: string]: ServerRequest__McpElicitationPrimitiveSchema };
+  readonly required?: ReadonlyArray<string> | null;
+  readonly type: ServerRequest__McpElicitationObjectType;
+};
+export const ServerRequest__McpElicitationSchema = Schema.Struct({
+  $schema: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  properties: Schema.Record(Schema.String, ServerRequest__McpElicitationPrimitiveSchema),
+  required: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  type: ServerRequest__McpElicitationObjectType,
+}).annotate({
+  description:
+    "Typed form schema for MCP `elicitation/create` requests.\n\nThis matches the `requestedSchema` shape from the MCP 2025-11-25 `ElicitRequestFormParams` schema.",
+});
+
+export type ServerRequest__McpServerElicitationRequestParams =
+  | {
+      readonly _meta?: unknown;
+      readonly message: string;
+      readonly mode: "form";
+      readonly requestedSchema: ServerRequest__McpElicitationSchema;
+      readonly serverName: string;
+      readonly threadId: string;
+      readonly turnId?: string | null;
+    }
+  | {
+      readonly _meta?: unknown;
+      readonly elicitationId: string;
+      readonly message: string;
+      readonly mode: "url";
+      readonly url: string;
+      readonly serverName: string;
+      readonly threadId: string;
+      readonly turnId?: string | null;
+    };
+export const ServerRequest__McpServerElicitationRequestParams = Schema.Union(
+  [
+    Schema.Struct({
+      _meta: Schema.optionalKey(Schema.Unknown),
+      message: Schema.String,
+      mode: Schema.Literal("form"),
+      requestedSchema: ServerRequest__McpElicitationSchema,
+      serverName: Schema.String,
+      threadId: Schema.String,
+      turnId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "Active Codex turn when this elicitation was observed, if app-server could correlate one.\n\nThis is nullable because MCP models elicitation as a standalone server-to-client request identified by the MCP server request id. It may be triggered during a turn, but turn context is app-server correlation rather than part of the protocol identity of the elicitation itself.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }),
+    Schema.Struct({
+      _meta: Schema.optionalKey(Schema.Unknown),
+      elicitationId: Schema.String,
+      message: Schema.String,
+      mode: Schema.Literal("url"),
+      url: Schema.String,
+      serverName: Schema.String,
+      threadId: Schema.String,
+      turnId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "Active Codex turn when this elicitation was observed, if app-server could correlate one.\n\nThis is nullable because MCP models elicitation as a standalone server-to-client request identified by the MCP server request id. It may be triggered during a turn, but turn context is app-server correlation rather than part of the protocol identity of the elicitation itself.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ApplyPatchApprovalParams = {
+  readonly callId: string;
+  readonly conversationId: ApplyPatchApprovalParams__ThreadId;
+  readonly fileChanges: { readonly [x: string]: ApplyPatchApprovalParams__FileChange };
+  readonly grantRoot?: string | null;
+  readonly reason?: string | null;
+};
+export const ApplyPatchApprovalParams = Schema.Struct({
+  callId: Schema.String.annotate({
+    description:
+      "Use to correlate this with [codex_protocol::protocol::PatchApplyBeginEvent] and [codex_protocol::protocol::PatchApplyEndEvent].",
+  }),
+  conversationId: ApplyPatchApprovalParams__ThreadId,
+  fileChanges: Schema.Record(Schema.String, ApplyPatchApprovalParams__FileChange),
+  grantRoot: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reason: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional explanatory reason (e.g. request for extra write access).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ApplyPatchApprovalParams" });
+
+export type ApplyPatchApprovalResponse = {
+  readonly decision: ApplyPatchApprovalResponse__ReviewDecision;
+};
+export const ApplyPatchApprovalResponse = Schema.Struct({
+  decision: ApplyPatchApprovalResponse__ReviewDecision,
+}).annotate({ title: "ApplyPatchApprovalResponse" });
+
+export type ChatgptAuthTokensRefreshParams = {
+  readonly previousAccountId?: string | null;
+  readonly reason: ChatgptAuthTokensRefreshParams__ChatgptAuthTokensRefreshReason;
+};
+export const ChatgptAuthTokensRefreshParams = Schema.Struct({
+  previousAccountId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Workspace/account identifier that Codex was previously using.\n\nClients that manage multiple accounts/workspaces can use this as a hint to refresh the token for the correct workspace.\n\nThis may be `null` when the prior auth state did not include a workspace identifier (`chatgpt_account_id`).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reason: ChatgptAuthTokensRefreshParams__ChatgptAuthTokensRefreshReason,
+}).annotate({ title: "ChatgptAuthTokensRefreshParams" });
+
+export type ChatgptAuthTokensRefreshResponse = {
+  readonly accessToken: string;
+  readonly chatgptAccountId: string;
+  readonly chatgptPlanType?: string | null;
+};
+export const ChatgptAuthTokensRefreshResponse = Schema.Struct({
+  accessToken: Schema.String,
+  chatgptAccountId: Schema.String,
+  chatgptPlanType: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "ChatgptAuthTokensRefreshResponse" });
+
+export type ClientNotification = { readonly method: "initialized" };
+export const ClientNotification = Schema.Union(
+  [
+    Schema.Struct({
+      method: Schema.Literal("initialized").annotate({ title: "InitializedNotificationMethod" }),
+    }).annotate({ title: "InitializedNotification" }),
+  ],
+  { mode: "oneOf" },
+).annotate({ title: "ClientNotification" });
+
+export type ClientRequest =
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "initialize";
+      readonly params: ClientRequest__InitializeParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/start";
+      readonly params: ClientRequest__ThreadStartParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/resume";
+      readonly params: ClientRequest__ThreadResumeParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/fork";
+      readonly params: ClientRequest__ThreadForkParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/archive";
+      readonly params: ClientRequest__ThreadArchiveParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/unsubscribe";
+      readonly params: ClientRequest__ThreadUnsubscribeParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/name/set";
+      readonly params: ClientRequest__ThreadSetNameParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/metadata/update";
+      readonly params: ClientRequest__ThreadMetadataUpdateParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/unarchive";
+      readonly params: ClientRequest__ThreadUnarchiveParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/compact/start";
+      readonly params: ClientRequest__ThreadCompactStartParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/shellCommand";
+      readonly params: ClientRequest__ThreadShellCommandParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/approveGuardianDeniedAction";
+      readonly params: ClientRequest__ThreadApproveGuardianDeniedActionParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/rollback";
+      readonly params: ClientRequest__ThreadRollbackParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/list";
+      readonly params: ClientRequest__ThreadListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/loaded/list";
+      readonly params: ClientRequest__ThreadLoadedListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/read";
+      readonly params: ClientRequest__ThreadReadParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "thread/inject_items";
+      readonly params: ClientRequest__ThreadInjectItemsParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "skills/list";
+      readonly params: ClientRequest__SkillsListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "hooks/list";
+      readonly params: ClientRequest__HooksListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "marketplace/add";
+      readonly params: ClientRequest__MarketplaceAddParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "marketplace/remove";
+      readonly params: ClientRequest__MarketplaceRemoveParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "marketplace/upgrade";
+      readonly params: ClientRequest__MarketplaceUpgradeParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/list";
+      readonly params: ClientRequest__PluginListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/read";
+      readonly params: ClientRequest__PluginReadParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/skill/read";
+      readonly params: ClientRequest__PluginSkillReadParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/share/save";
+      readonly params: ClientRequest__PluginShareSaveParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/share/updateTargets";
+      readonly params: ClientRequest__PluginShareUpdateTargetsParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/share/list";
+      readonly params: ClientRequest__PluginShareListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/share/delete";
+      readonly params: ClientRequest__PluginShareDeleteParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "app/list";
+      readonly params: ClientRequest__AppsListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/readFile";
+      readonly params: ClientRequest__FsReadFileParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/writeFile";
+      readonly params: ClientRequest__FsWriteFileParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/createDirectory";
+      readonly params: ClientRequest__FsCreateDirectoryParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/getMetadata";
+      readonly params: ClientRequest__FsGetMetadataParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/readDirectory";
+      readonly params: ClientRequest__FsReadDirectoryParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/remove";
+      readonly params: ClientRequest__FsRemoveParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/copy";
+      readonly params: ClientRequest__FsCopyParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/watch";
+      readonly params: ClientRequest__FsWatchParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fs/unwatch";
+      readonly params: ClientRequest__FsUnwatchParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "skills/config/write";
+      readonly params: ClientRequest__SkillsConfigWriteParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/install";
+      readonly params: ClientRequest__PluginInstallParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "plugin/uninstall";
+      readonly params: ClientRequest__PluginUninstallParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "turn/start";
+      readonly params: ClientRequest__TurnStartParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "turn/steer";
+      readonly params: ClientRequest__TurnSteerParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "turn/interrupt";
+      readonly params: ClientRequest__TurnInterruptParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "review/start";
+      readonly params: ClientRequest__ReviewStartParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "model/list";
+      readonly params: ClientRequest__ModelListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "modelProvider/capabilities/read";
+      readonly params: ClientRequest__ModelProviderCapabilitiesReadParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "experimentalFeature/list";
+      readonly params: ClientRequest__ExperimentalFeatureListParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "experimentalFeature/enablement/set";
+      readonly params: ClientRequest__ExperimentalFeatureEnablementSetParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "mcpServer/oauth/login";
+      readonly params: ClientRequest__McpServerOauthLoginParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "config/mcpServer/reload";
+      readonly params?: null;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "mcpServerStatus/list";
+      readonly params: ClientRequest__ListMcpServerStatusParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "mcpServer/resource/read";
+      readonly params: ClientRequest__McpResourceReadParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "mcpServer/tool/call";
+      readonly params: ClientRequest__McpServerToolCallParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "windowsSandbox/setupStart";
+      readonly params: ClientRequest__WindowsSandboxSetupStartParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "windowsSandbox/readiness";
+      readonly params?: null;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "account/login/start";
+      readonly params: ClientRequest__LoginAccountParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "account/login/cancel";
+      readonly params: ClientRequest__CancelLoginAccountParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "account/logout";
+      readonly params?: null;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "account/rateLimits/read";
+      readonly params?: null;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "account/sendAddCreditsNudgeEmail";
+      readonly params: ClientRequest__SendAddCreditsNudgeEmailParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "feedback/upload";
+      readonly params: ClientRequest__FeedbackUploadParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "command/exec";
+      readonly params: ClientRequest__CommandExecParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "command/exec/write";
+      readonly params: ClientRequest__CommandExecWriteParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "command/exec/terminate";
+      readonly params: ClientRequest__CommandExecTerminateParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "command/exec/resize";
+      readonly params: ClientRequest__CommandExecResizeParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "config/read";
+      readonly params: ClientRequest__ConfigReadParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "externalAgentConfig/detect";
+      readonly params: ClientRequest__ExternalAgentConfigDetectParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "externalAgentConfig/import";
+      readonly params: ClientRequest__ExternalAgentConfigImportParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "config/value/write";
+      readonly params: ClientRequest__ConfigValueWriteParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "config/batchWrite";
+      readonly params: ClientRequest__ConfigBatchWriteParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "configRequirements/read";
+      readonly params?: null;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "account/read";
+      readonly params: ClientRequest__GetAccountParams;
+    }
+  | {
+      readonly id: ClientRequest__RequestId;
+      readonly method: "fuzzyFileSearch";
+      readonly params: ClientRequest__FuzzyFileSearchParams;
+    };
+export const ClientRequest = Schema.Union(
+  [
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("initialize").annotate({ title: "InitializeRequestMethod" }),
+      params: ClientRequest__InitializeParams,
+    }).annotate({ title: "InitializeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/start").annotate({ title: "Thread/startRequestMethod" }),
+      params: ClientRequest__ThreadStartParams,
+    }).annotate({ title: "Thread/startRequest", description: "NEW APIs" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/resume").annotate({ title: "Thread/resumeRequestMethod" }),
+      params: ClientRequest__ThreadResumeParams,
+    }).annotate({ title: "Thread/resumeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/fork").annotate({ title: "Thread/forkRequestMethod" }),
+      params: ClientRequest__ThreadForkParams,
+    }).annotate({ title: "Thread/forkRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/archive").annotate({ title: "Thread/archiveRequestMethod" }),
+      params: ClientRequest__ThreadArchiveParams,
+    }).annotate({ title: "Thread/archiveRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/unsubscribe").annotate({
+        title: "Thread/unsubscribeRequestMethod",
+      }),
+      params: ClientRequest__ThreadUnsubscribeParams,
+    }).annotate({ title: "Thread/unsubscribeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/name/set").annotate({ title: "Thread/name/setRequestMethod" }),
+      params: ClientRequest__ThreadSetNameParams,
+    }).annotate({ title: "Thread/name/setRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/metadata/update").annotate({
+        title: "Thread/metadata/updateRequestMethod",
+      }),
+      params: ClientRequest__ThreadMetadataUpdateParams,
+    }).annotate({ title: "Thread/metadata/updateRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/unarchive").annotate({
+        title: "Thread/unarchiveRequestMethod",
+      }),
+      params: ClientRequest__ThreadUnarchiveParams,
+    }).annotate({ title: "Thread/unarchiveRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/compact/start").annotate({
+        title: "Thread/compact/startRequestMethod",
+      }),
+      params: ClientRequest__ThreadCompactStartParams,
+    }).annotate({ title: "Thread/compact/startRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/shellCommand").annotate({
+        title: "Thread/shellCommandRequestMethod",
+      }),
+      params: ClientRequest__ThreadShellCommandParams,
+    }).annotate({ title: "Thread/shellCommandRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/approveGuardianDeniedAction").annotate({
+        title: "Thread/approveGuardianDeniedActionRequestMethod",
+      }),
+      params: ClientRequest__ThreadApproveGuardianDeniedActionParams,
+    }).annotate({ title: "Thread/approveGuardianDeniedActionRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/rollback").annotate({ title: "Thread/rollbackRequestMethod" }),
+      params: ClientRequest__ThreadRollbackParams,
+    }).annotate({ title: "Thread/rollbackRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/list").annotate({ title: "Thread/listRequestMethod" }),
+      params: ClientRequest__ThreadListParams,
+    }).annotate({ title: "Thread/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/loaded/list").annotate({
+        title: "Thread/loaded/listRequestMethod",
+      }),
+      params: ClientRequest__ThreadLoadedListParams,
+    }).annotate({ title: "Thread/loaded/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/read").annotate({ title: "Thread/readRequestMethod" }),
+      params: ClientRequest__ThreadReadParams,
+    }).annotate({ title: "Thread/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("thread/inject_items").annotate({
+        title: "Thread/injectItemsRequestMethod",
+      }),
+      params: ClientRequest__ThreadInjectItemsParams,
+    }).annotate({
+      title: "Thread/injectItemsRequest",
+      description:
+        "Append raw Responses API items to the thread history without starting a user turn.",
+    }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("skills/list").annotate({ title: "Skills/listRequestMethod" }),
+      params: ClientRequest__SkillsListParams,
+    }).annotate({ title: "Skills/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("hooks/list").annotate({ title: "Hooks/listRequestMethod" }),
+      params: ClientRequest__HooksListParams,
+    }).annotate({ title: "Hooks/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("marketplace/add").annotate({ title: "Marketplace/addRequestMethod" }),
+      params: ClientRequest__MarketplaceAddParams,
+    }).annotate({ title: "Marketplace/addRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("marketplace/remove").annotate({
+        title: "Marketplace/removeRequestMethod",
+      }),
+      params: ClientRequest__MarketplaceRemoveParams,
+    }).annotate({ title: "Marketplace/removeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("marketplace/upgrade").annotate({
+        title: "Marketplace/upgradeRequestMethod",
+      }),
+      params: ClientRequest__MarketplaceUpgradeParams,
+    }).annotate({ title: "Marketplace/upgradeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/list").annotate({ title: "Plugin/listRequestMethod" }),
+      params: ClientRequest__PluginListParams,
+    }).annotate({ title: "Plugin/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/read").annotate({ title: "Plugin/readRequestMethod" }),
+      params: ClientRequest__PluginReadParams,
+    }).annotate({ title: "Plugin/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/skill/read").annotate({
+        title: "Plugin/skill/readRequestMethod",
+      }),
+      params: ClientRequest__PluginSkillReadParams,
+    }).annotate({ title: "Plugin/skill/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/share/save").annotate({
+        title: "Plugin/share/saveRequestMethod",
+      }),
+      params: ClientRequest__PluginShareSaveParams,
+    }).annotate({ title: "Plugin/share/saveRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/share/updateTargets").annotate({
+        title: "Plugin/share/updateTargetsRequestMethod",
+      }),
+      params: ClientRequest__PluginShareUpdateTargetsParams,
+    }).annotate({ title: "Plugin/share/updateTargetsRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/share/list").annotate({
+        title: "Plugin/share/listRequestMethod",
+      }),
+      params: ClientRequest__PluginShareListParams,
+    }).annotate({ title: "Plugin/share/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/share/delete").annotate({
+        title: "Plugin/share/deleteRequestMethod",
+      }),
+      params: ClientRequest__PluginShareDeleteParams,
+    }).annotate({ title: "Plugin/share/deleteRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("app/list").annotate({ title: "App/listRequestMethod" }),
+      params: ClientRequest__AppsListParams,
+    }).annotate({ title: "App/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/readFile").annotate({ title: "Fs/readFileRequestMethod" }),
+      params: ClientRequest__FsReadFileParams,
+    }).annotate({ title: "Fs/readFileRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/writeFile").annotate({ title: "Fs/writeFileRequestMethod" }),
+      params: ClientRequest__FsWriteFileParams,
+    }).annotate({ title: "Fs/writeFileRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/createDirectory").annotate({
+        title: "Fs/createDirectoryRequestMethod",
+      }),
+      params: ClientRequest__FsCreateDirectoryParams,
+    }).annotate({ title: "Fs/createDirectoryRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/getMetadata").annotate({ title: "Fs/getMetadataRequestMethod" }),
+      params: ClientRequest__FsGetMetadataParams,
+    }).annotate({ title: "Fs/getMetadataRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/readDirectory").annotate({
+        title: "Fs/readDirectoryRequestMethod",
+      }),
+      params: ClientRequest__FsReadDirectoryParams,
+    }).annotate({ title: "Fs/readDirectoryRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/remove").annotate({ title: "Fs/removeRequestMethod" }),
+      params: ClientRequest__FsRemoveParams,
+    }).annotate({ title: "Fs/removeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/copy").annotate({ title: "Fs/copyRequestMethod" }),
+      params: ClientRequest__FsCopyParams,
+    }).annotate({ title: "Fs/copyRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/watch").annotate({ title: "Fs/watchRequestMethod" }),
+      params: ClientRequest__FsWatchParams,
+    }).annotate({ title: "Fs/watchRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fs/unwatch").annotate({ title: "Fs/unwatchRequestMethod" }),
+      params: ClientRequest__FsUnwatchParams,
+    }).annotate({ title: "Fs/unwatchRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("skills/config/write").annotate({
+        title: "Skills/config/writeRequestMethod",
+      }),
+      params: ClientRequest__SkillsConfigWriteParams,
+    }).annotate({ title: "Skills/config/writeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/install").annotate({ title: "Plugin/installRequestMethod" }),
+      params: ClientRequest__PluginInstallParams,
+    }).annotate({ title: "Plugin/installRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("plugin/uninstall").annotate({
+        title: "Plugin/uninstallRequestMethod",
+      }),
+      params: ClientRequest__PluginUninstallParams,
+    }).annotate({ title: "Plugin/uninstallRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("turn/start").annotate({ title: "Turn/startRequestMethod" }),
+      params: ClientRequest__TurnStartParams,
+    }).annotate({ title: "Turn/startRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("turn/steer").annotate({ title: "Turn/steerRequestMethod" }),
+      params: ClientRequest__TurnSteerParams,
+    }).annotate({ title: "Turn/steerRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("turn/interrupt").annotate({ title: "Turn/interruptRequestMethod" }),
+      params: ClientRequest__TurnInterruptParams,
+    }).annotate({ title: "Turn/interruptRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("review/start").annotate({ title: "Review/startRequestMethod" }),
+      params: ClientRequest__ReviewStartParams,
+    }).annotate({ title: "Review/startRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("model/list").annotate({ title: "Model/listRequestMethod" }),
+      params: ClientRequest__ModelListParams,
+    }).annotate({ title: "Model/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("modelProvider/capabilities/read").annotate({
+        title: "ModelProvider/capabilities/readRequestMethod",
+      }),
+      params: ClientRequest__ModelProviderCapabilitiesReadParams,
+    }).annotate({ title: "ModelProvider/capabilities/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("experimentalFeature/list").annotate({
+        title: "ExperimentalFeature/listRequestMethod",
+      }),
+      params: ClientRequest__ExperimentalFeatureListParams,
+    }).annotate({ title: "ExperimentalFeature/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("experimentalFeature/enablement/set").annotate({
+        title: "ExperimentalFeature/enablement/setRequestMethod",
+      }),
+      params: ClientRequest__ExperimentalFeatureEnablementSetParams,
+    }).annotate({ title: "ExperimentalFeature/enablement/setRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("mcpServer/oauth/login").annotate({
+        title: "McpServer/oauth/loginRequestMethod",
+      }),
+      params: ClientRequest__McpServerOauthLoginParams,
+    }).annotate({ title: "McpServer/oauth/loginRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("config/mcpServer/reload").annotate({
+        title: "Config/mcpServer/reloadRequestMethod",
+      }),
+      params: Schema.optionalKey(Schema.Null),
+    }).annotate({ title: "Config/mcpServer/reloadRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("mcpServerStatus/list").annotate({
+        title: "McpServerStatus/listRequestMethod",
+      }),
+      params: ClientRequest__ListMcpServerStatusParams,
+    }).annotate({ title: "McpServerStatus/listRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("mcpServer/resource/read").annotate({
+        title: "McpServer/resource/readRequestMethod",
+      }),
+      params: ClientRequest__McpResourceReadParams,
+    }).annotate({ title: "McpServer/resource/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("mcpServer/tool/call").annotate({
+        title: "McpServer/tool/callRequestMethod",
+      }),
+      params: ClientRequest__McpServerToolCallParams,
+    }).annotate({ title: "McpServer/tool/callRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("windowsSandbox/setupStart").annotate({
+        title: "WindowsSandbox/setupStartRequestMethod",
+      }),
+      params: ClientRequest__WindowsSandboxSetupStartParams,
+    }).annotate({ title: "WindowsSandbox/setupStartRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("windowsSandbox/readiness").annotate({
+        title: "WindowsSandbox/readinessRequestMethod",
+      }),
+      params: Schema.optionalKey(Schema.Null),
+    }).annotate({ title: "WindowsSandbox/readinessRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("account/login/start").annotate({
+        title: "Account/login/startRequestMethod",
+      }),
+      params: ClientRequest__LoginAccountParams,
+    }).annotate({ title: "Account/login/startRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("account/login/cancel").annotate({
+        title: "Account/login/cancelRequestMethod",
+      }),
+      params: ClientRequest__CancelLoginAccountParams,
+    }).annotate({ title: "Account/login/cancelRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("account/logout").annotate({ title: "Account/logoutRequestMethod" }),
+      params: Schema.optionalKey(Schema.Null),
+    }).annotate({ title: "Account/logoutRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("account/rateLimits/read").annotate({
+        title: "Account/rateLimits/readRequestMethod",
+      }),
+      params: Schema.optionalKey(Schema.Null),
+    }).annotate({ title: "Account/rateLimits/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("account/sendAddCreditsNudgeEmail").annotate({
+        title: "Account/sendAddCreditsNudgeEmailRequestMethod",
+      }),
+      params: ClientRequest__SendAddCreditsNudgeEmailParams,
+    }).annotate({ title: "Account/sendAddCreditsNudgeEmailRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("feedback/upload").annotate({ title: "Feedback/uploadRequestMethod" }),
+      params: ClientRequest__FeedbackUploadParams,
+    }).annotate({ title: "Feedback/uploadRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("command/exec").annotate({ title: "Command/execRequestMethod" }),
+      params: ClientRequest__CommandExecParams,
+    }).annotate({
+      title: "Command/execRequest",
+      description: "Execute a standalone command (argv vector) under the server's sandbox.",
+    }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("command/exec/write").annotate({
+        title: "Command/exec/writeRequestMethod",
+      }),
+      params: ClientRequest__CommandExecWriteParams,
+    }).annotate({
+      title: "Command/exec/writeRequest",
+      description: "Write stdin bytes to a running `command/exec` session or close stdin.",
+    }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("command/exec/terminate").annotate({
+        title: "Command/exec/terminateRequestMethod",
+      }),
+      params: ClientRequest__CommandExecTerminateParams,
+    }).annotate({
+      title: "Command/exec/terminateRequest",
+      description: "Terminate a running `command/exec` session by client-supplied `processId`.",
+    }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("command/exec/resize").annotate({
+        title: "Command/exec/resizeRequestMethod",
+      }),
+      params: ClientRequest__CommandExecResizeParams,
+    }).annotate({
+      title: "Command/exec/resizeRequest",
+      description:
+        "Resize a running PTY-backed `command/exec` session by client-supplied `processId`.",
+    }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("config/read").annotate({ title: "Config/readRequestMethod" }),
+      params: ClientRequest__ConfigReadParams,
+    }).annotate({ title: "Config/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("externalAgentConfig/detect").annotate({
+        title: "ExternalAgentConfig/detectRequestMethod",
+      }),
+      params: ClientRequest__ExternalAgentConfigDetectParams,
+    }).annotate({ title: "ExternalAgentConfig/detectRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("externalAgentConfig/import").annotate({
+        title: "ExternalAgentConfig/importRequestMethod",
+      }),
+      params: ClientRequest__ExternalAgentConfigImportParams,
+    }).annotate({ title: "ExternalAgentConfig/importRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("config/value/write").annotate({
+        title: "Config/value/writeRequestMethod",
+      }),
+      params: ClientRequest__ConfigValueWriteParams,
+    }).annotate({ title: "Config/value/writeRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("config/batchWrite").annotate({
+        title: "Config/batchWriteRequestMethod",
+      }),
+      params: ClientRequest__ConfigBatchWriteParams,
+    }).annotate({ title: "Config/batchWriteRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("configRequirements/read").annotate({
+        title: "ConfigRequirements/readRequestMethod",
+      }),
+      params: Schema.optionalKey(Schema.Null),
+    }).annotate({ title: "ConfigRequirements/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("account/read").annotate({ title: "Account/readRequestMethod" }),
+      params: ClientRequest__GetAccountParams,
+    }).annotate({ title: "Account/readRequest" }),
+    Schema.Struct({
+      id: ClientRequest__RequestId,
+      method: Schema.Literal("fuzzyFileSearch").annotate({ title: "FuzzyFileSearchRequestMethod" }),
+      params: ClientRequest__FuzzyFileSearchParams,
+    }).annotate({ title: "FuzzyFileSearchRequest" }),
+  ],
+  { mode: "oneOf" },
+).annotate({ title: "ClientRequest", description: "Request from the client to the server." });
+
+export type ClientRequest__ByteRange = { readonly end: number; readonly start: number };
+export const ClientRequest__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type ClientRequest__CollaborationMode = {
+  readonly mode: ClientRequest__ModeKind;
+  readonly settings: ClientRequest__Settings;
+};
+export const ClientRequest__CollaborationMode = Schema.Struct({
+  mode: ClientRequest__ModeKind,
+  settings: ClientRequest__Settings,
+}).annotate({ description: "Collaboration mode for a Codex session." });
+
+export type ClientRequest__DynamicToolSpec = {
+  readonly deferLoading?: boolean;
+  readonly description: string;
+  readonly inputSchema: unknown;
+  readonly name: string;
+  readonly namespace?: string | null;
+};
+export const ClientRequest__DynamicToolSpec = Schema.Struct({
+  deferLoading: Schema.optionalKey(Schema.Boolean),
+  description: Schema.String,
+  inputSchema: Schema.Unknown,
+  name: Schema.String,
+  namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type ClientRequest__NetworkAccess = "restricted" | "enabled";
+export const ClientRequest__NetworkAccess = Schema.Literals(["restricted", "enabled"]);
+
+export type ClientRequest__PermissionProfile =
+  | {
+      readonly fileSystem: ClientRequest__PermissionProfileFileSystemPermissions;
+      readonly network: ClientRequest__PermissionProfileNetworkPermissions;
+      readonly type: "managed";
+    }
+  | { readonly type: "disabled" }
+  | {
+      readonly network: ClientRequest__PermissionProfileNetworkPermissions;
+      readonly type: "external";
+    };
+export const ClientRequest__PermissionProfile = Schema.Union(
+  [
+    Schema.Struct({
+      fileSystem: ClientRequest__PermissionProfileFileSystemPermissions,
+      network: ClientRequest__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("managed").annotate({ title: "ManagedPermissionProfileType" }),
+    }).annotate({
+      title: "ManagedPermissionProfile",
+      description: "Codex owns sandbox construction for this profile.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("disabled").annotate({ title: "DisabledPermissionProfileType" }),
+    }).annotate({
+      title: "DisabledPermissionProfile",
+      description: "Do not apply an outer sandbox.",
+    }),
+    Schema.Struct({
+      network: ClientRequest__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("external").annotate({ title: "ExternalPermissionProfileType" }),
+    }).annotate({
+      title: "ExternalPermissionProfile",
+      description: "Filesystem isolation is enforced by an external caller.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__PermissionProfileSelectionParams = {
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<ClientRequest__PermissionProfileModificationParams> | null;
+  readonly type: "profile";
+};
+export const ClientRequest__PermissionProfileSelectionParams = Schema.Union(
+  [
+    Schema.Struct({
+      id: Schema.String,
+      modifications: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(ClientRequest__PermissionProfileModificationParams),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("profile").annotate({
+        title: "ProfilePermissionProfileSelectionParamsType",
+      }),
+    }).annotate({
+      title: "ProfilePermissionProfileSelectionParams",
+      description:
+        "Select a named built-in or user-defined profile and optionally apply bounded modifications that Codex knows how to validate.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ProcessTerminalSize = { readonly cols: number; readonly rows: number };
+export const ClientRequest__ProcessTerminalSize = Schema.Struct({
+  cols: Schema.Number.annotate({
+    description: "Terminal width in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  rows: Schema.Number.annotate({
+    description: "Terminal height in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({ description: "PTY size in character cells for `process/spawn` PTY sessions." });
+
+export type ClientRequest__RealtimeOutputModality = "text" | "audio";
+export const ClientRequest__RealtimeOutputModality = Schema.Literals(["text", "audio"]);
+
+export type ClientRequest__RealtimeVoice =
+  | "alloy"
+  | "arbor"
+  | "ash"
+  | "ballad"
+  | "breeze"
+  | "cedar"
+  | "coral"
+  | "cove"
+  | "echo"
+  | "ember"
+  | "juniper"
+  | "maple"
+  | "marin"
+  | "sage"
+  | "shimmer"
+  | "sol"
+  | "spruce"
+  | "vale"
+  | "verse";
+export const ClientRequest__RealtimeVoice = Schema.Literals([
+  "alloy",
+  "arbor",
+  "ash",
+  "ballad",
+  "breeze",
+  "cedar",
+  "coral",
+  "cove",
+  "echo",
+  "ember",
+  "juniper",
+  "maple",
+  "marin",
+  "sage",
+  "shimmer",
+  "sol",
+  "spruce",
+  "vale",
+  "verse",
+]);
+
+export type ClientRequest__ResponseItem =
+  | {
+      readonly content: ReadonlyArray<ClientRequest__ContentItem>;
+      readonly id?: string | null;
+      readonly phase?: ClientRequest__MessagePhase | null;
+      readonly role: string;
+      readonly type: "message";
+    }
+  | {
+      readonly content?: ReadonlyArray<ClientRequest__ReasoningItemContent> | null;
+      readonly encrypted_content?: string | null;
+      readonly summary: ReadonlyArray<ClientRequest__ReasoningItemReasoningSummary>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly action: ClientRequest__LocalShellAction;
+      readonly call_id?: string | null;
+      readonly id?: string | null;
+      readonly status: ClientRequest__LocalShellStatus;
+      readonly type: "local_shell_call";
+    }
+  | {
+      readonly arguments: string;
+      readonly call_id: string;
+      readonly id?: string | null;
+      readonly name: string;
+      readonly namespace?: string | null;
+      readonly type: "function_call";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly call_id?: string | null;
+      readonly execution: string;
+      readonly id?: string | null;
+      readonly status?: string | null;
+      readonly type: "tool_search_call";
+    }
+  | {
+      readonly call_id: string;
+      readonly output: ClientRequest__FunctionCallOutputBody;
+      readonly type: "function_call_output";
+    }
+  | {
+      readonly call_id: string;
+      readonly id?: string | null;
+      readonly input: string;
+      readonly name: string;
+      readonly status?: string | null;
+      readonly type: "custom_tool_call";
+    }
+  | {
+      readonly call_id: string;
+      readonly name?: string | null;
+      readonly output: ClientRequest__FunctionCallOutputBody;
+      readonly type: "custom_tool_call_output";
+    }
+  | {
+      readonly call_id?: string | null;
+      readonly execution: string;
+      readonly status: string;
+      readonly tools: ReadonlyArray<unknown>;
+      readonly type: "tool_search_output";
+    }
+  | {
+      readonly action?: ClientRequest__ResponsesApiWebSearchAction | null;
+      readonly id?: string | null;
+      readonly status?: string | null;
+      readonly type: "web_search_call";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revised_prompt?: string | null;
+      readonly status: string;
+      readonly type: "image_generation_call";
+    }
+  | { readonly encrypted_content: string; readonly type: "compaction" }
+  | { readonly encrypted_content?: string | null; readonly type: "context_compaction" }
+  | { readonly type: "other" };
+export const ClientRequest__ResponseItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(ClientRequest__ContentItem),
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([ClientRequest__MessagePhase, Schema.Null])),
+      role: Schema.String,
+      type: Schema.Literal("message").annotate({ title: "MessageResponseItemType" }),
+    }).annotate({ title: "MessageResponseItem" }),
+    Schema.Struct({
+      content: Schema.optionalKey(
+        Schema.Union([Schema.Array(ClientRequest__ReasoningItemContent), Schema.Null]),
+      ),
+      encrypted_content: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      summary: Schema.Array(ClientRequest__ReasoningItemReasoningSummary),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningResponseItemType" }),
+    }).annotate({ title: "ReasoningResponseItem" }),
+    Schema.Struct({
+      action: ClientRequest__LocalShellAction,
+      call_id: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Set when using the Responses API." }),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Legacy id field retained for compatibility with older payloads.",
+            writeOnly: true,
+          }),
+          Schema.Null,
+        ]),
+      ),
+      status: ClientRequest__LocalShellStatus,
+      type: Schema.Literal("local_shell_call").annotate({
+        title: "LocalShellCallResponseItemType",
+      }),
+    }).annotate({ title: "LocalShellCallResponseItem" }),
+    Schema.Struct({
+      arguments: Schema.String,
+      call_id: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      name: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("function_call").annotate({ title: "FunctionCallResponseItemType" }),
+    }).annotate({ title: "FunctionCallResponseItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      call_id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      execution: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("tool_search_call").annotate({
+        title: "ToolSearchCallResponseItemType",
+      }),
+    }).annotate({ title: "ToolSearchCallResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      output: ClientRequest__FunctionCallOutputBody,
+      type: Schema.Literal("function_call_output").annotate({
+        title: "FunctionCallOutputResponseItemType",
+      }),
+    }).annotate({ title: "FunctionCallOutputResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      input: Schema.String,
+      name: Schema.String,
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("custom_tool_call").annotate({
+        title: "CustomToolCallResponseItemType",
+      }),
+    }).annotate({ title: "CustomToolCallResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      name: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      output: ClientRequest__FunctionCallOutputBody,
+      type: Schema.Literal("custom_tool_call_output").annotate({
+        title: "CustomToolCallOutputResponseItemType",
+      }),
+    }).annotate({ title: "CustomToolCallOutputResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      execution: Schema.String,
+      status: Schema.String,
+      tools: Schema.Array(Schema.Unknown),
+      type: Schema.Literal("tool_search_output").annotate({
+        title: "ToolSearchOutputResponseItemType",
+      }),
+    }).annotate({ title: "ToolSearchOutputResponseItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([ClientRequest__ResponsesApiWebSearchAction, Schema.Null]),
+      ),
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("web_search_call").annotate({ title: "WebSearchCallResponseItemType" }),
+    }).annotate({ title: "WebSearchCallResponseItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revised_prompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: Schema.String,
+      type: Schema.Literal("image_generation_call").annotate({
+        title: "ImageGenerationCallResponseItemType",
+      }),
+    }).annotate({ title: "ImageGenerationCallResponseItem" }),
+    Schema.Struct({
+      encrypted_content: Schema.String,
+      type: Schema.Literal("compaction").annotate({ title: "CompactionResponseItemType" }),
+    }).annotate({ title: "CompactionResponseItem" }),
+    Schema.Struct({
+      encrypted_content: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("context_compaction").annotate({
+        title: "ContextCompactionResponseItemType",
+      }),
+    }).annotate({ title: "ContextCompactionResponseItem" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherResponseItemType" }),
+    }).annotate({ title: "OtherResponseItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ClientRequest__ThreadGoalStatus = "active" | "paused" | "budgetLimited" | "complete";
+export const ClientRequest__ThreadGoalStatus = Schema.Literals([
+  "active",
+  "paused",
+  "budgetLimited",
+  "complete",
+]);
+
+export type ClientRequest__ThreadMemoryMode = "enabled" | "disabled";
+export const ClientRequest__ThreadMemoryMode = Schema.Literals(["enabled", "disabled"]);
+
+export type ClientRequest__ThreadRealtimeAudioChunk = {
+  readonly data: string;
+  readonly itemId?: string | null;
+  readonly numChannels: number;
+  readonly sampleRate: number;
+  readonly samplesPerChannel?: number | null;
+};
+export const ClientRequest__ThreadRealtimeAudioChunk = Schema.Struct({
+  data: Schema.String,
+  itemId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  numChannels: Schema.Number.annotate({ format: "uint16" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  sampleRate: Schema.Number.annotate({ format: "uint32" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  samplesPerChannel: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint32" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ description: "EXPERIMENTAL - thread realtime audio chunk." });
+
+export type ClientRequest__ThreadRealtimeStartTransport =
+  | { readonly type: "websocket" }
+  | { readonly sdp: string; readonly type: "webrtc" };
+export const ClientRequest__ThreadRealtimeStartTransport = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("websocket").annotate({
+        title: "WebsocketThreadRealtimeStartTransportType",
+      }),
+    }).annotate({ title: "WebsocketThreadRealtimeStartTransport" }),
+    Schema.Struct({
+      sdp: Schema.String.annotate({
+        description:
+          "SDP offer generated by a WebRTC RTCPeerConnection after configuring audio and the realtime events data channel.",
+      }),
+      type: Schema.Literal("webrtc").annotate({ title: "WebrtcThreadRealtimeStartTransportType" }),
+    }).annotate({ title: "WebrtcThreadRealtimeStartTransport" }),
+  ],
+  { mode: "oneOf" },
+).annotate({ description: "EXPERIMENTAL - transport used by thread realtime." });
+
+export type ClientRequest__TurnEnvironmentParams = {
+  readonly cwd: ClientRequest__AbsolutePathBuf;
+  readonly environmentId: string;
+};
+export const ClientRequest__TurnEnvironmentParams = Schema.Struct({
+  cwd: ClientRequest__AbsolutePathBuf,
+  environmentId: Schema.String,
+});
+
+export type ClientRequest__TurnItemsView = "notLoaded" | "summary" | "full";
+export const ClientRequest__TurnItemsView = Schema.Literals(["notLoaded", "summary", "full"]);
+
+export type CommandExecutionRequestApprovalParams = {
+  readonly approvalId?: string | null;
+  readonly command?: string | null;
+  readonly commandActions?: ReadonlyArray<CommandExecutionRequestApprovalParams__CommandAction> | null;
+  readonly cwd?: CommandExecutionRequestApprovalParams__AbsolutePathBuf | null;
+  readonly itemId: string;
+  readonly networkApprovalContext?: CommandExecutionRequestApprovalParams__NetworkApprovalContext | null;
+  readonly proposedExecpolicyAmendment?: ReadonlyArray<string> | null;
+  readonly proposedNetworkPolicyAmendments?: ReadonlyArray<CommandExecutionRequestApprovalParams__NetworkPolicyAmendment> | null;
+  readonly reason?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const CommandExecutionRequestApprovalParams = Schema.Struct({
+  approvalId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Unique identifier for this specific approval callback.\n\nFor regular shell/unified_exec approvals, this is null.\n\nFor zsh-exec-bridge subcommand approvals, multiple callbacks can belong to one parent `itemId`, so `approvalId` is a distinct opaque callback id (a UUID) used to disambiguate routing.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  command: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "The command to be executed." }),
+      Schema.Null,
+    ]),
+  ),
+  commandActions: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(CommandExecutionRequestApprovalParams__CommandAction).annotate({
+        description: "Best-effort parsed command actions for friendly display.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.optionalKey(
+    Schema.Union([CommandExecutionRequestApprovalParams__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "The command's working directory.",
+    }),
+  ),
+  itemId: Schema.String,
+  networkApprovalContext: Schema.optionalKey(
+    Schema.Union([
+      CommandExecutionRequestApprovalParams__NetworkApprovalContext,
+      Schema.Null,
+    ]).annotate({ description: "Optional context for a managed-network approval prompt." }),
+  ),
+  proposedExecpolicyAmendment: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Optional proposed execpolicy amendment to allow similar commands without prompting.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  proposedNetworkPolicyAmendments: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(CommandExecutionRequestApprovalParams__NetworkPolicyAmendment).annotate({
+        description:
+          "Optional proposed network policy amendments (allow/deny host) for future requests.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reason: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional explanatory reason (e.g. request for network access).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "CommandExecutionRequestApprovalParams" });
+
+export type CommandExecutionRequestApprovalParams__AdditionalPermissionProfile = {
+  readonly fileSystem?: CommandExecutionRequestApprovalParams__AdditionalFileSystemPermissions | null;
+  readonly network?: CommandExecutionRequestApprovalParams__AdditionalNetworkPermissions | null;
+};
+export const CommandExecutionRequestApprovalParams__AdditionalPermissionProfile = Schema.Struct({
+  fileSystem: Schema.optionalKey(
+    Schema.Union([
+      CommandExecutionRequestApprovalParams__AdditionalFileSystemPermissions,
+      Schema.Null,
+    ]),
+  ),
+  network: Schema.optionalKey(
+    Schema.Union([
+      CommandExecutionRequestApprovalParams__AdditionalNetworkPermissions,
+      Schema.Null,
+    ]).annotate({ description: "Partial overlay used for per-command permission requests." }),
+  ),
+});
+
+export type CommandExecutionRequestApprovalParams__CommandExecutionApprovalDecision =
+  | "accept"
+  | "acceptForSession"
+  | {
+      readonly acceptWithExecpolicyAmendment: {
+        readonly execpolicy_amendment: ReadonlyArray<string>;
+      };
+    }
+  | {
+      readonly applyNetworkPolicyAmendment: {
+        readonly network_policy_amendment: CommandExecutionRequestApprovalParams__NetworkPolicyAmendment;
+      };
+    }
+  | "decline"
+  | "cancel";
+export const CommandExecutionRequestApprovalParams__CommandExecutionApprovalDecision = Schema.Union(
+  [
+    Schema.Literal("accept").annotate({ description: "User approved the command." }),
+    Schema.Literal("acceptForSession").annotate({
+      description:
+        "User approved the command and future prompts in the same session-scoped approval cache should run without prompting.",
+    }),
+    Schema.Struct({
+      acceptWithExecpolicyAmendment: Schema.Struct({
+        execpolicy_amendment: Schema.Array(Schema.String),
+      }),
+    }).annotate({
+      title: "AcceptWithExecpolicyAmendmentCommandExecutionApprovalDecision",
+      description:
+        "User approved the command, and wants to apply the proposed execpolicy amendment so future matching commands can run without prompting.",
+    }),
+    Schema.Struct({
+      applyNetworkPolicyAmendment: Schema.Struct({
+        network_policy_amendment: CommandExecutionRequestApprovalParams__NetworkPolicyAmendment,
+      }),
+    }).annotate({
+      title: "ApplyNetworkPolicyAmendmentCommandExecutionApprovalDecision",
+      description: "User chose a persistent network policy rule (allow/deny) for this host.",
+    }),
+    Schema.Literal("decline").annotate({
+      description: "User denied the command. The agent will continue the turn.",
+    }),
+    Schema.Literal("cancel").annotate({
+      description: "User denied the command. The turn will also be immediately interrupted.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type CommandExecutionRequestApprovalResponse = {
+  readonly decision: CommandExecutionRequestApprovalResponse__CommandExecutionApprovalDecision;
+};
+export const CommandExecutionRequestApprovalResponse = Schema.Struct({
+  decision: CommandExecutionRequestApprovalResponse__CommandExecutionApprovalDecision,
+}).annotate({ title: "CommandExecutionRequestApprovalResponse" });
+
+export type DynamicToolCallParams = {
+  readonly arguments: unknown;
+  readonly callId: string;
+  readonly namespace?: string | null;
+  readonly threadId: string;
+  readonly tool: string;
+  readonly turnId: string;
+};
+export const DynamicToolCallParams = Schema.Struct({
+  arguments: Schema.Unknown,
+  callId: Schema.String,
+  namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  tool: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "DynamicToolCallParams" });
+
+export type DynamicToolCallResponse = {
+  readonly contentItems: ReadonlyArray<DynamicToolCallResponse__DynamicToolCallOutputContentItem>;
+  readonly success: boolean;
+};
+export const DynamicToolCallResponse = Schema.Struct({
+  contentItems: Schema.Array(DynamicToolCallResponse__DynamicToolCallOutputContentItem),
+  success: Schema.Boolean,
+}).annotate({ title: "DynamicToolCallResponse" });
+
+export type ExecCommandApprovalParams = {
+  readonly approvalId?: string | null;
+  readonly callId: string;
+  readonly command: ReadonlyArray<string>;
+  readonly conversationId: ExecCommandApprovalParams__ThreadId;
+  readonly cwd: string;
+  readonly parsedCmd: ReadonlyArray<ExecCommandApprovalParams__ParsedCommand>;
+  readonly reason?: string | null;
+};
+export const ExecCommandApprovalParams = Schema.Struct({
+  approvalId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Identifier for this specific approval callback." }),
+      Schema.Null,
+    ]),
+  ),
+  callId: Schema.String.annotate({
+    description:
+      "Use to correlate this with [codex_protocol::protocol::ExecCommandBeginEvent] and [codex_protocol::protocol::ExecCommandEndEvent].",
+  }),
+  command: Schema.Array(Schema.String),
+  conversationId: ExecCommandApprovalParams__ThreadId,
+  cwd: Schema.String,
+  parsedCmd: Schema.Array(ExecCommandApprovalParams__ParsedCommand),
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "ExecCommandApprovalParams" });
+
+export type ExecCommandApprovalResponse = {
+  readonly decision: ExecCommandApprovalResponse__ReviewDecision;
+};
+export const ExecCommandApprovalResponse = Schema.Struct({
+  decision: ExecCommandApprovalResponse__ReviewDecision,
+}).annotate({ title: "ExecCommandApprovalResponse" });
+
+export type FileChangeRequestApprovalParams = {
+  readonly grantRoot?: string | null;
+  readonly itemId: string;
+  readonly reason?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const FileChangeRequestApprovalParams = Schema.Struct({
+  grantRoot: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "[UNSTABLE] When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  itemId: Schema.String,
+  reason: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional explanatory reason (e.g. request for extra write access).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "FileChangeRequestApprovalParams" });
+
+export type FileChangeRequestApprovalResponse = {
+  readonly decision: FileChangeRequestApprovalResponse__FileChangeApprovalDecision;
+};
+export const FileChangeRequestApprovalResponse = Schema.Struct({
+  decision: FileChangeRequestApprovalResponse__FileChangeApprovalDecision,
+}).annotate({ title: "FileChangeRequestApprovalResponse" });
+
+export type FuzzyFileSearchParams = {
+  readonly cancellationToken?: string | null;
+  readonly query: string;
+  readonly roots: ReadonlyArray<string>;
+};
+export const FuzzyFileSearchParams = Schema.Struct({
+  cancellationToken: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  query: Schema.String,
+  roots: Schema.Array(Schema.String),
+}).annotate({ title: "FuzzyFileSearchParams" });
+
+export type FuzzyFileSearchResponse = {
+  readonly files: ReadonlyArray<FuzzyFileSearchResponse__FuzzyFileSearchResult>;
+};
+export const FuzzyFileSearchResponse = Schema.Struct({
+  files: Schema.Array(FuzzyFileSearchResponse__FuzzyFileSearchResult),
+}).annotate({ title: "FuzzyFileSearchResponse" });
+
+export type FuzzyFileSearchSessionCompletedNotification = { readonly sessionId: string };
+export const FuzzyFileSearchSessionCompletedNotification = Schema.Struct({
+  sessionId: Schema.String,
+}).annotate({ title: "FuzzyFileSearchSessionCompletedNotification" });
+
+export type FuzzyFileSearchSessionUpdatedNotification = {
+  readonly files: ReadonlyArray<FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchResult>;
+  readonly query: string;
+  readonly sessionId: string;
+};
+export const FuzzyFileSearchSessionUpdatedNotification = Schema.Struct({
+  files: Schema.Array(FuzzyFileSearchSessionUpdatedNotification__FuzzyFileSearchResult),
+  query: Schema.String,
+  sessionId: Schema.String,
+}).annotate({ title: "FuzzyFileSearchSessionUpdatedNotification" });
+
+export type GetAuthStatusParams = {
+  readonly includeToken?: boolean | null;
+  readonly refreshToken?: boolean | null;
+};
+export const GetAuthStatusParams = Schema.Struct({
+  includeToken: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  refreshToken: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+}).annotate({ title: "GetAuthStatusParams" });
+
+export type GetAuthStatusResponse = {
+  readonly authMethod: unknown | null;
+  readonly authToken: string | null;
+  readonly requiresOpenaiAuth: boolean | null;
+};
+export const GetAuthStatusResponse = Schema.Struct({
+  authMethod: Schema.Union([Schema.Unknown, Schema.Null]),
+  authToken: Schema.Union([Schema.String, Schema.Null]),
+  requiresOpenaiAuth: Schema.Union([Schema.Boolean, Schema.Null]),
+}).annotate({ title: "GetAuthStatusResponse" });
+
+export type GetConversationSummaryParams =
+  | { readonly rolloutPath: string }
+  | { readonly conversationId: string };
+export const GetConversationSummaryParams = Schema.Union(
+  [Schema.Struct({ rolloutPath: Schema.String }), Schema.Struct({ conversationId: Schema.String })],
+  { mode: "oneOf" },
+).annotate({ title: "GetConversationSummaryParams" });
+
+export type GetConversationSummaryResponse = { readonly summary: unknown };
+export const GetConversationSummaryResponse = Schema.Struct({ summary: Schema.Unknown }).annotate({
+  title: "GetConversationSummaryResponse",
+});
+
+export type GitDiffToRemoteParams = { readonly cwd: string };
+export const GitDiffToRemoteParams = Schema.Struct({ cwd: Schema.String }).annotate({
+  title: "GitDiffToRemoteParams",
+});
+
+export type GitDiffToRemoteResponse = { readonly sha: string; readonly diff: string };
+export const GitDiffToRemoteResponse = Schema.Struct({
+  sha: Schema.String,
+  diff: Schema.String,
+}).annotate({ title: "GitDiffToRemoteResponse" });
+
+export type JSONRPCError = {
+  readonly error: JSONRPCError__JSONRPCErrorError;
+  readonly id: JSONRPCError__RequestId;
+};
+export const JSONRPCError = Schema.Struct({
+  error: JSONRPCError__JSONRPCErrorError,
+  id: JSONRPCError__RequestId,
+}).annotate({
+  title: "JSONRPCError",
+  description: "A response to a request that indicates an error occurred.",
+});
+
+export type JSONRPCErrorError = {
+  readonly code: number;
+  readonly data?: unknown;
+  readonly message: string;
+};
+export const JSONRPCErrorError = Schema.Struct({
+  code: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  data: Schema.optionalKey(Schema.Unknown),
+  message: Schema.String,
+}).annotate({ title: "JSONRPCErrorError" });
+
+export type JSONRPCMessage =
+  | JSONRPCMessage__JSONRPCRequest
+  | JSONRPCMessage__JSONRPCNotification
+  | JSONRPCMessage__JSONRPCResponse
+  | JSONRPCMessage__JSONRPCError;
+export const JSONRPCMessage = Schema.Union([
+  JSONRPCMessage__JSONRPCRequest,
+  JSONRPCMessage__JSONRPCNotification,
+  JSONRPCMessage__JSONRPCResponse,
+  JSONRPCMessage__JSONRPCError,
+]).annotate({
+  title: "JSONRPCMessage",
+  description:
+    "Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent.",
+});
+
+export type JSONRPCNotification = { readonly method: string; readonly params?: unknown };
+export const JSONRPCNotification = Schema.Struct({
+  method: Schema.String,
+  params: Schema.optionalKey(Schema.Unknown),
+}).annotate({
+  title: "JSONRPCNotification",
+  description: "A notification which does not expect a response.",
+});
+
+export type JSONRPCRequest = {
+  readonly id: JSONRPCRequest__RequestId;
+  readonly method: string;
+  readonly params?: unknown;
+  readonly trace?: JSONRPCRequest__W3cTraceContext | null;
+};
+export const JSONRPCRequest = Schema.Struct({
+  id: JSONRPCRequest__RequestId,
+  method: Schema.String,
+  params: Schema.optionalKey(Schema.Unknown),
+  trace: Schema.optionalKey(
+    Schema.Union([JSONRPCRequest__W3cTraceContext, Schema.Null]).annotate({
+      description: "Optional W3C Trace Context for distributed tracing.",
+    }),
+  ),
+}).annotate({ title: "JSONRPCRequest", description: "A request that expects a response." });
+
+export type JSONRPCResponse = { readonly id: JSONRPCResponse__RequestId; readonly result: unknown };
+export const JSONRPCResponse = Schema.Struct({
+  id: JSONRPCResponse__RequestId,
+  result: Schema.Unknown,
+}).annotate({
+  title: "JSONRPCResponse",
+  description: "A successful (non-error) response to a request.",
+});
+
+export type McpServerElicitationRequestParams =
+  | {
+      readonly _meta?: unknown;
+      readonly message: string;
+      readonly mode: "form";
+      readonly requestedSchema: McpServerElicitationRequestParams__McpElicitationSchema;
+      readonly serverName: string;
+      readonly threadId: string;
+      readonly turnId?: string | null;
+    }
+  | {
+      readonly _meta?: unknown;
+      readonly elicitationId: string;
+      readonly message: string;
+      readonly mode: "url";
+      readonly url: string;
+      readonly serverName: string;
+      readonly threadId: string;
+      readonly turnId?: string | null;
+    };
+export const McpServerElicitationRequestParams = Schema.Union(
+  [
+    Schema.Struct({
+      _meta: Schema.optionalKey(Schema.Unknown),
+      message: Schema.String,
+      mode: Schema.Literal("form"),
+      requestedSchema: McpServerElicitationRequestParams__McpElicitationSchema,
+      serverName: Schema.String,
+      threadId: Schema.String,
+      turnId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "Active Codex turn when this elicitation was observed, if app-server could correlate one.\n\nThis is nullable because MCP models elicitation as a standalone server-to-client request identified by the MCP server request id. It may be triggered during a turn, but turn context is app-server correlation rather than part of the protocol identity of the elicitation itself.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({ title: "McpServerElicitationRequestParams" }),
+    Schema.Struct({
+      _meta: Schema.optionalKey(Schema.Unknown),
+      elicitationId: Schema.String,
+      message: Schema.String,
+      mode: Schema.Literal("url"),
+      url: Schema.String,
+      serverName: Schema.String,
+      threadId: Schema.String,
+      turnId: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "Active Codex turn when this elicitation was observed, if app-server could correlate one.\n\nThis is nullable because MCP models elicitation as a standalone server-to-client request identified by the MCP server request id. It may be triggered during a turn, but turn context is app-server correlation rather than part of the protocol identity of the elicitation itself.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+    }).annotate({ title: "McpServerElicitationRequestParams" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type McpServerElicitationRequestResponse = {
+  readonly _meta?: unknown;
+  readonly action: McpServerElicitationRequestResponse__McpServerElicitationAction;
+  readonly content?: unknown;
+};
+export const McpServerElicitationRequestResponse = Schema.Struct({
+  _meta: Schema.optionalKey(
+    Schema.Unknown.annotate({
+      description: "Optional client metadata for form-mode action handling.",
+    }),
+  ),
+  action: McpServerElicitationRequestResponse__McpServerElicitationAction,
+  content: Schema.optionalKey(
+    Schema.Unknown.annotate({
+      description:
+        "Structured user input for accepted elicitations, mirroring RMCP `CreateElicitationResult`.\n\nThis is nullable because decline/cancel responses have no content.",
+    }),
+  ),
+}).annotate({ title: "McpServerElicitationRequestResponse" });
+
+export type PermissionsRequestApprovalParams = {
+  readonly cwd: PermissionsRequestApprovalParams__AbsolutePathBuf;
+  readonly itemId: string;
+  readonly permissions: PermissionsRequestApprovalParams__RequestPermissionProfile;
+  readonly reason?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const PermissionsRequestApprovalParams = Schema.Struct({
+  cwd: PermissionsRequestApprovalParams__AbsolutePathBuf,
+  itemId: Schema.String,
+  permissions: PermissionsRequestApprovalParams__RequestPermissionProfile,
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "PermissionsRequestApprovalParams" });
+
+export type PermissionsRequestApprovalResponse = {
+  readonly permissions: PermissionsRequestApprovalResponse__GrantedPermissionProfile;
+  readonly scope?: "turn" | "session";
+  readonly strictAutoReview?: boolean | null;
+};
+export const PermissionsRequestApprovalResponse = Schema.Struct({
+  permissions: PermissionsRequestApprovalResponse__GrantedPermissionProfile,
+  scope: Schema.optionalKey(Schema.Literals(["turn", "session"]).annotate({ default: "turn" })),
+  strictAutoReview: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description:
+          "Review every subsequent command in this turn before normal sandboxed execution.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "PermissionsRequestApprovalResponse" });
+
+export type PermissionsRequestApprovalResponse__PermissionGrantScope = "turn" | "session";
+export const PermissionsRequestApprovalResponse__PermissionGrantScope = Schema.Literals([
+  "turn",
+  "session",
+]);
+
+export type RequestId = string | number;
+export const RequestId = Schema.Union([
+  Schema.String,
+  Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+]).annotate({ title: "RequestId" });
+
+export type ServerNotification =
+  | { readonly method: "error"; readonly params: ServerNotification__ErrorNotification }
+  | {
+      readonly method: "thread/started";
+      readonly params: ServerNotification__ThreadStartedNotification;
+    }
+  | {
+      readonly method: "thread/status/changed";
+      readonly params: ServerNotification__ThreadStatusChangedNotification;
+    }
+  | {
+      readonly method: "thread/archived";
+      readonly params: ServerNotification__ThreadArchivedNotification;
+    }
+  | {
+      readonly method: "thread/unarchived";
+      readonly params: ServerNotification__ThreadUnarchivedNotification;
+    }
+  | {
+      readonly method: "thread/closed";
+      readonly params: ServerNotification__ThreadClosedNotification;
+    }
+  | {
+      readonly method: "skills/changed";
+      readonly params: ServerNotification__SkillsChangedNotification;
+    }
+  | {
+      readonly method: "thread/name/updated";
+      readonly params: ServerNotification__ThreadNameUpdatedNotification;
+    }
+  | {
+      readonly method: "thread/goal/updated";
+      readonly params: ServerNotification__ThreadGoalUpdatedNotification;
+    }
+  | {
+      readonly method: "thread/goal/cleared";
+      readonly params: ServerNotification__ThreadGoalClearedNotification;
+    }
+  | {
+      readonly method: "thread/tokenUsage/updated";
+      readonly params: ServerNotification__ThreadTokenUsageUpdatedNotification;
+    }
+  | {
+      readonly method: "turn/started";
+      readonly params: ServerNotification__TurnStartedNotification;
+    }
+  | {
+      readonly method: "hook/started";
+      readonly params: ServerNotification__HookStartedNotification;
+    }
+  | {
+      readonly method: "turn/completed";
+      readonly params: ServerNotification__TurnCompletedNotification;
+    }
+  | {
+      readonly method: "hook/completed";
+      readonly params: ServerNotification__HookCompletedNotification;
+    }
+  | {
+      readonly method: "turn/diff/updated";
+      readonly params: ServerNotification__TurnDiffUpdatedNotification;
+    }
+  | {
+      readonly method: "turn/plan/updated";
+      readonly params: ServerNotification__TurnPlanUpdatedNotification;
+    }
+  | {
+      readonly method: "item/started";
+      readonly params: ServerNotification__ItemStartedNotification;
+    }
+  | {
+      readonly method: "item/autoApprovalReview/started";
+      readonly params: ServerNotification__ItemGuardianApprovalReviewStartedNotification;
+    }
+  | {
+      readonly method: "item/autoApprovalReview/completed";
+      readonly params: ServerNotification__ItemGuardianApprovalReviewCompletedNotification;
+    }
+  | {
+      readonly method: "item/completed";
+      readonly params: ServerNotification__ItemCompletedNotification;
+    }
+  | {
+      readonly method: "item/agentMessage/delta";
+      readonly params: ServerNotification__AgentMessageDeltaNotification;
+    }
+  | {
+      readonly method: "item/plan/delta";
+      readonly params: ServerNotification__PlanDeltaNotification;
+    }
+  | {
+      readonly method: "command/exec/outputDelta";
+      readonly params: ServerNotification__CommandExecOutputDeltaNotification;
+    }
+  | {
+      readonly method: "process/outputDelta";
+      readonly params: ServerNotification__ProcessOutputDeltaNotification;
+    }
+  | {
+      readonly method: "process/exited";
+      readonly params: ServerNotification__ProcessExitedNotification;
+    }
+  | {
+      readonly method: "item/commandExecution/outputDelta";
+      readonly params: ServerNotification__CommandExecutionOutputDeltaNotification;
+    }
+  | {
+      readonly method: "item/commandExecution/terminalInteraction";
+      readonly params: ServerNotification__TerminalInteractionNotification;
+    }
+  | {
+      readonly method: "item/fileChange/outputDelta";
+      readonly params: ServerNotification__FileChangeOutputDeltaNotification;
+    }
+  | {
+      readonly method: "item/fileChange/patchUpdated";
+      readonly params: ServerNotification__FileChangePatchUpdatedNotification;
+    }
+  | {
+      readonly method: "serverRequest/resolved";
+      readonly params: ServerNotification__ServerRequestResolvedNotification;
+    }
+  | {
+      readonly method: "item/mcpToolCall/progress";
+      readonly params: ServerNotification__McpToolCallProgressNotification;
+    }
+  | {
+      readonly method: "mcpServer/oauthLogin/completed";
+      readonly params: ServerNotification__McpServerOauthLoginCompletedNotification;
+    }
+  | {
+      readonly method: "mcpServer/startupStatus/updated";
+      readonly params: ServerNotification__McpServerStatusUpdatedNotification;
+    }
+  | {
+      readonly method: "account/updated";
+      readonly params: ServerNotification__AccountUpdatedNotification;
+    }
+  | {
+      readonly method: "account/rateLimits/updated";
+      readonly params: ServerNotification__AccountRateLimitsUpdatedNotification;
+    }
+  | {
+      readonly method: "app/list/updated";
+      readonly params: ServerNotification__AppListUpdatedNotification;
+    }
+  | {
+      readonly method: "remoteControl/status/changed";
+      readonly params: ServerNotification__RemoteControlStatusChangedNotification;
+    }
+  | {
+      readonly method: "externalAgentConfig/import/completed";
+      readonly params: ServerNotification__ExternalAgentConfigImportCompletedNotification;
+    }
+  | { readonly method: "fs/changed"; readonly params: ServerNotification__FsChangedNotification }
+  | {
+      readonly method: "item/reasoning/summaryTextDelta";
+      readonly params: ServerNotification__ReasoningSummaryTextDeltaNotification;
+    }
+  | {
+      readonly method: "item/reasoning/summaryPartAdded";
+      readonly params: ServerNotification__ReasoningSummaryPartAddedNotification;
+    }
+  | {
+      readonly method: "item/reasoning/textDelta";
+      readonly params: ServerNotification__ReasoningTextDeltaNotification;
+    }
+  | {
+      readonly method: "thread/compacted";
+      readonly params: ServerNotification__ContextCompactedNotification;
+    }
+  | {
+      readonly method: "model/rerouted";
+      readonly params: ServerNotification__ModelReroutedNotification;
+    }
+  | {
+      readonly method: "model/verification";
+      readonly params: ServerNotification__ModelVerificationNotification;
+    }
+  | { readonly method: "warning"; readonly params: ServerNotification__WarningNotification }
+  | {
+      readonly method: "guardianWarning";
+      readonly params: ServerNotification__GuardianWarningNotification;
+    }
+  | {
+      readonly method: "deprecationNotice";
+      readonly params: ServerNotification__DeprecationNoticeNotification;
+    }
+  | {
+      readonly method: "configWarning";
+      readonly params: ServerNotification__ConfigWarningNotification;
+    }
+  | {
+      readonly method: "fuzzyFileSearch/sessionUpdated";
+      readonly params: ServerNotification__FuzzyFileSearchSessionUpdatedNotification;
+    }
+  | {
+      readonly method: "fuzzyFileSearch/sessionCompleted";
+      readonly params: ServerNotification__FuzzyFileSearchSessionCompletedNotification;
+    }
+  | {
+      readonly method: "thread/realtime/started";
+      readonly params: ServerNotification__ThreadRealtimeStartedNotification;
+    }
+  | {
+      readonly method: "thread/realtime/itemAdded";
+      readonly params: ServerNotification__ThreadRealtimeItemAddedNotification;
+    }
+  | {
+      readonly method: "thread/realtime/transcript/delta";
+      readonly params: ServerNotification__ThreadRealtimeTranscriptDeltaNotification;
+    }
+  | {
+      readonly method: "thread/realtime/transcript/done";
+      readonly params: ServerNotification__ThreadRealtimeTranscriptDoneNotification;
+    }
+  | {
+      readonly method: "thread/realtime/outputAudio/delta";
+      readonly params: ServerNotification__ThreadRealtimeOutputAudioDeltaNotification;
+    }
+  | {
+      readonly method: "thread/realtime/sdp";
+      readonly params: ServerNotification__ThreadRealtimeSdpNotification;
+    }
+  | {
+      readonly method: "thread/realtime/error";
+      readonly params: ServerNotification__ThreadRealtimeErrorNotification;
+    }
+  | {
+      readonly method: "thread/realtime/closed";
+      readonly params: ServerNotification__ThreadRealtimeClosedNotification;
+    }
+  | {
+      readonly method: "windows/worldWritableWarning";
+      readonly params: ServerNotification__WindowsWorldWritableWarningNotification;
+    }
+  | {
+      readonly method: "windowsSandbox/setupCompleted";
+      readonly params: ServerNotification__WindowsSandboxSetupCompletedNotification;
+    }
+  | {
+      readonly method: "account/login/completed";
+      readonly params: ServerNotification__AccountLoginCompletedNotification;
+    };
+export const ServerNotification = Schema.Union(
+  [
+    Schema.Struct({
+      method: Schema.Literal("error").annotate({ title: "ErrorNotificationMethod" }),
+      params: ServerNotification__ErrorNotification,
+    }).annotate({ title: "ErrorNotification", description: "NEW NOTIFICATIONS" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/started").annotate({
+        title: "Thread/startedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadStartedNotification,
+    }).annotate({ title: "Thread/startedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/status/changed").annotate({
+        title: "Thread/status/changedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadStatusChangedNotification,
+    }).annotate({ title: "Thread/status/changedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/archived").annotate({
+        title: "Thread/archivedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadArchivedNotification,
+    }).annotate({ title: "Thread/archivedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/unarchived").annotate({
+        title: "Thread/unarchivedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadUnarchivedNotification,
+    }).annotate({ title: "Thread/unarchivedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/closed").annotate({
+        title: "Thread/closedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadClosedNotification,
+    }).annotate({ title: "Thread/closedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("skills/changed").annotate({
+        title: "Skills/changedNotificationMethod",
+      }),
+      params: ServerNotification__SkillsChangedNotification,
+    }).annotate({ title: "Skills/changedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/name/updated").annotate({
+        title: "Thread/name/updatedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadNameUpdatedNotification,
+    }).annotate({ title: "Thread/name/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/goal/updated").annotate({
+        title: "Thread/goal/updatedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadGoalUpdatedNotification,
+    }).annotate({ title: "Thread/goal/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/goal/cleared").annotate({
+        title: "Thread/goal/clearedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadGoalClearedNotification,
+    }).annotate({ title: "Thread/goal/clearedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/tokenUsage/updated").annotate({
+        title: "Thread/tokenUsage/updatedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadTokenUsageUpdatedNotification,
+    }).annotate({ title: "Thread/tokenUsage/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("turn/started").annotate({ title: "Turn/startedNotificationMethod" }),
+      params: ServerNotification__TurnStartedNotification,
+    }).annotate({ title: "Turn/startedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("hook/started").annotate({ title: "Hook/startedNotificationMethod" }),
+      params: ServerNotification__HookStartedNotification,
+    }).annotate({ title: "Hook/startedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("turn/completed").annotate({
+        title: "Turn/completedNotificationMethod",
+      }),
+      params: ServerNotification__TurnCompletedNotification,
+    }).annotate({ title: "Turn/completedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("hook/completed").annotate({
+        title: "Hook/completedNotificationMethod",
+      }),
+      params: ServerNotification__HookCompletedNotification,
+    }).annotate({ title: "Hook/completedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("turn/diff/updated").annotate({
+        title: "Turn/diff/updatedNotificationMethod",
+      }),
+      params: ServerNotification__TurnDiffUpdatedNotification,
+    }).annotate({ title: "Turn/diff/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("turn/plan/updated").annotate({
+        title: "Turn/plan/updatedNotificationMethod",
+      }),
+      params: ServerNotification__TurnPlanUpdatedNotification,
+    }).annotate({ title: "Turn/plan/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/started").annotate({ title: "Item/startedNotificationMethod" }),
+      params: ServerNotification__ItemStartedNotification,
+    }).annotate({ title: "Item/startedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/autoApprovalReview/started").annotate({
+        title: "Item/autoApprovalReview/startedNotificationMethod",
+      }),
+      params: ServerNotification__ItemGuardianApprovalReviewStartedNotification,
+    }).annotate({ title: "Item/autoApprovalReview/startedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/autoApprovalReview/completed").annotate({
+        title: "Item/autoApprovalReview/completedNotificationMethod",
+      }),
+      params: ServerNotification__ItemGuardianApprovalReviewCompletedNotification,
+    }).annotate({ title: "Item/autoApprovalReview/completedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/completed").annotate({
+        title: "Item/completedNotificationMethod",
+      }),
+      params: ServerNotification__ItemCompletedNotification,
+    }).annotate({ title: "Item/completedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/agentMessage/delta").annotate({
+        title: "Item/agentMessage/deltaNotificationMethod",
+      }),
+      params: ServerNotification__AgentMessageDeltaNotification,
+    }).annotate({ title: "Item/agentMessage/deltaNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/plan/delta").annotate({
+        title: "Item/plan/deltaNotificationMethod",
+      }),
+      params: ServerNotification__PlanDeltaNotification,
+    }).annotate({
+      title: "Item/plan/deltaNotification",
+      description: "EXPERIMENTAL - proposed plan streaming deltas for plan items.",
+    }),
+    Schema.Struct({
+      method: Schema.Literal("command/exec/outputDelta").annotate({
+        title: "Command/exec/outputDeltaNotificationMethod",
+      }),
+      params: ServerNotification__CommandExecOutputDeltaNotification,
+    }).annotate({
+      title: "Command/exec/outputDeltaNotification",
+      description:
+        "Stream base64-encoded stdout/stderr chunks for a running `command/exec` session.",
+    }),
+    Schema.Struct({
+      method: Schema.Literal("process/outputDelta").annotate({
+        title: "Process/outputDeltaNotificationMethod",
+      }),
+      params: ServerNotification__ProcessOutputDeltaNotification,
+    }).annotate({
+      title: "Process/outputDeltaNotification",
+      description:
+        "Stream base64-encoded stdout/stderr chunks for a running `process/spawn` session.",
+    }),
+    Schema.Struct({
+      method: Schema.Literal("process/exited").annotate({
+        title: "Process/exitedNotificationMethod",
+      }),
+      params: ServerNotification__ProcessExitedNotification,
+    }).annotate({
+      title: "Process/exitedNotification",
+      description: "Final exit notification for a `process/spawn` session.",
+    }),
+    Schema.Struct({
+      method: Schema.Literal("item/commandExecution/outputDelta").annotate({
+        title: "Item/commandExecution/outputDeltaNotificationMethod",
+      }),
+      params: ServerNotification__CommandExecutionOutputDeltaNotification,
+    }).annotate({ title: "Item/commandExecution/outputDeltaNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/commandExecution/terminalInteraction").annotate({
+        title: "Item/commandExecution/terminalInteractionNotificationMethod",
+      }),
+      params: ServerNotification__TerminalInteractionNotification,
+    }).annotate({ title: "Item/commandExecution/terminalInteractionNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/fileChange/outputDelta").annotate({
+        title: "Item/fileChange/outputDeltaNotificationMethod",
+      }),
+      params: ServerNotification__FileChangeOutputDeltaNotification,
+    }).annotate({
+      title: "Item/fileChange/outputDeltaNotification",
+      description: "Deprecated legacy apply_patch output stream notification.",
+    }),
+    Schema.Struct({
+      method: Schema.Literal("item/fileChange/patchUpdated").annotate({
+        title: "Item/fileChange/patchUpdatedNotificationMethod",
+      }),
+      params: ServerNotification__FileChangePatchUpdatedNotification,
+    }).annotate({ title: "Item/fileChange/patchUpdatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("serverRequest/resolved").annotate({
+        title: "ServerRequest/resolvedNotificationMethod",
+      }),
+      params: ServerNotification__ServerRequestResolvedNotification,
+    }).annotate({ title: "ServerRequest/resolvedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/mcpToolCall/progress").annotate({
+        title: "Item/mcpToolCall/progressNotificationMethod",
+      }),
+      params: ServerNotification__McpToolCallProgressNotification,
+    }).annotate({ title: "Item/mcpToolCall/progressNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("mcpServer/oauthLogin/completed").annotate({
+        title: "McpServer/oauthLogin/completedNotificationMethod",
+      }),
+      params: ServerNotification__McpServerOauthLoginCompletedNotification,
+    }).annotate({ title: "McpServer/oauthLogin/completedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("mcpServer/startupStatus/updated").annotate({
+        title: "McpServer/startupStatus/updatedNotificationMethod",
+      }),
+      params: ServerNotification__McpServerStatusUpdatedNotification,
+    }).annotate({ title: "McpServer/startupStatus/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("account/updated").annotate({
+        title: "Account/updatedNotificationMethod",
+      }),
+      params: ServerNotification__AccountUpdatedNotification,
+    }).annotate({ title: "Account/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("account/rateLimits/updated").annotate({
+        title: "Account/rateLimits/updatedNotificationMethod",
+      }),
+      params: ServerNotification__AccountRateLimitsUpdatedNotification,
+    }).annotate({ title: "Account/rateLimits/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("app/list/updated").annotate({
+        title: "App/list/updatedNotificationMethod",
+      }),
+      params: ServerNotification__AppListUpdatedNotification,
+    }).annotate({ title: "App/list/updatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("remoteControl/status/changed").annotate({
+        title: "RemoteControl/status/changedNotificationMethod",
+      }),
+      params: ServerNotification__RemoteControlStatusChangedNotification,
+    }).annotate({ title: "RemoteControl/status/changedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("externalAgentConfig/import/completed").annotate({
+        title: "ExternalAgentConfig/import/completedNotificationMethod",
+      }),
+      params: ServerNotification__ExternalAgentConfigImportCompletedNotification,
+    }).annotate({ title: "ExternalAgentConfig/import/completedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("fs/changed").annotate({ title: "Fs/changedNotificationMethod" }),
+      params: ServerNotification__FsChangedNotification,
+    }).annotate({ title: "Fs/changedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/reasoning/summaryTextDelta").annotate({
+        title: "Item/reasoning/summaryTextDeltaNotificationMethod",
+      }),
+      params: ServerNotification__ReasoningSummaryTextDeltaNotification,
+    }).annotate({ title: "Item/reasoning/summaryTextDeltaNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/reasoning/summaryPartAdded").annotate({
+        title: "Item/reasoning/summaryPartAddedNotificationMethod",
+      }),
+      params: ServerNotification__ReasoningSummaryPartAddedNotification,
+    }).annotate({ title: "Item/reasoning/summaryPartAddedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("item/reasoning/textDelta").annotate({
+        title: "Item/reasoning/textDeltaNotificationMethod",
+      }),
+      params: ServerNotification__ReasoningTextDeltaNotification,
+    }).annotate({ title: "Item/reasoning/textDeltaNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/compacted").annotate({
+        title: "Thread/compactedNotificationMethod",
+      }),
+      params: ServerNotification__ContextCompactedNotification,
+    }).annotate({
+      title: "Thread/compactedNotification",
+      description: "Deprecated: Use `ContextCompaction` item type instead.",
+    }),
+    Schema.Struct({
+      method: Schema.Literal("model/rerouted").annotate({
+        title: "Model/reroutedNotificationMethod",
+      }),
+      params: ServerNotification__ModelReroutedNotification,
+    }).annotate({ title: "Model/reroutedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("model/verification").annotate({
+        title: "Model/verificationNotificationMethod",
+      }),
+      params: ServerNotification__ModelVerificationNotification,
+    }).annotate({ title: "Model/verificationNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("warning").annotate({ title: "WarningNotificationMethod" }),
+      params: ServerNotification__WarningNotification,
+    }).annotate({ title: "WarningNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("guardianWarning").annotate({
+        title: "GuardianWarningNotificationMethod",
+      }),
+      params: ServerNotification__GuardianWarningNotification,
+    }).annotate({ title: "GuardianWarningNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("deprecationNotice").annotate({
+        title: "DeprecationNoticeNotificationMethod",
+      }),
+      params: ServerNotification__DeprecationNoticeNotification,
+    }).annotate({ title: "DeprecationNoticeNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("configWarning").annotate({
+        title: "ConfigWarningNotificationMethod",
+      }),
+      params: ServerNotification__ConfigWarningNotification,
+    }).annotate({ title: "ConfigWarningNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("fuzzyFileSearch/sessionUpdated").annotate({
+        title: "FuzzyFileSearch/sessionUpdatedNotificationMethod",
+      }),
+      params: ServerNotification__FuzzyFileSearchSessionUpdatedNotification,
+    }).annotate({ title: "FuzzyFileSearch/sessionUpdatedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("fuzzyFileSearch/sessionCompleted").annotate({
+        title: "FuzzyFileSearch/sessionCompletedNotificationMethod",
+      }),
+      params: ServerNotification__FuzzyFileSearchSessionCompletedNotification,
+    }).annotate({ title: "FuzzyFileSearch/sessionCompletedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/started").annotate({
+        title: "Thread/realtime/startedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeStartedNotification,
+    }).annotate({ title: "Thread/realtime/startedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/itemAdded").annotate({
+        title: "Thread/realtime/itemAddedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeItemAddedNotification,
+    }).annotate({ title: "Thread/realtime/itemAddedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/transcript/delta").annotate({
+        title: "Thread/realtime/transcript/deltaNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeTranscriptDeltaNotification,
+    }).annotate({ title: "Thread/realtime/transcript/deltaNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/transcript/done").annotate({
+        title: "Thread/realtime/transcript/doneNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeTranscriptDoneNotification,
+    }).annotate({ title: "Thread/realtime/transcript/doneNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/outputAudio/delta").annotate({
+        title: "Thread/realtime/outputAudio/deltaNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeOutputAudioDeltaNotification,
+    }).annotate({ title: "Thread/realtime/outputAudio/deltaNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/sdp").annotate({
+        title: "Thread/realtime/sdpNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeSdpNotification,
+    }).annotate({ title: "Thread/realtime/sdpNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/error").annotate({
+        title: "Thread/realtime/errorNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeErrorNotification,
+    }).annotate({ title: "Thread/realtime/errorNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("thread/realtime/closed").annotate({
+        title: "Thread/realtime/closedNotificationMethod",
+      }),
+      params: ServerNotification__ThreadRealtimeClosedNotification,
+    }).annotate({ title: "Thread/realtime/closedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("windows/worldWritableWarning").annotate({
+        title: "Windows/worldWritableWarningNotificationMethod",
+      }),
+      params: ServerNotification__WindowsWorldWritableWarningNotification,
+    }).annotate({
+      title: "Windows/worldWritableWarningNotification",
+      description:
+        "Notifies the user of world-writable directories on Windows, which cannot be protected by the sandbox.",
+    }),
+    Schema.Struct({
+      method: Schema.Literal("windowsSandbox/setupCompleted").annotate({
+        title: "WindowsSandbox/setupCompletedNotificationMethod",
+      }),
+      params: ServerNotification__WindowsSandboxSetupCompletedNotification,
+    }).annotate({ title: "WindowsSandbox/setupCompletedNotification" }),
+    Schema.Struct({
+      method: Schema.Literal("account/login/completed").annotate({
+        title: "Account/login/completedNotificationMethod",
+      }),
+      params: ServerNotification__AccountLoginCompletedNotification,
+    }).annotate({ title: "Account/login/completedNotification" }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  title: "ServerNotification",
+  description: "Notification sent from the server to the client.",
+});
+
+export type ServerNotification__ByteRange = { readonly end: number; readonly start: number };
+export const ServerNotification__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type ServerNotification__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const ServerNotification__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type ServerNotification__CollabAgentToolCallStatus = "inProgress" | "completed" | "failed";
+export const ServerNotification__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type ServerNotification__CommandExecOutputStream = "stdout" | "stderr";
+export const ServerNotification__CommandExecOutputStream = Schema.Literals([
+  "stdout",
+  "stderr",
+]).annotate({ description: "Stream label for `command/exec/outputDelta` notifications." });
+
+export type ServerNotification__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const ServerNotification__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type ServerNotification__HookSource =
+  | "system"
+  | "user"
+  | "project"
+  | "mdm"
+  | "sessionFlags"
+  | "plugin"
+  | "cloudRequirements"
+  | "legacyManagedConfigFile"
+  | "legacyManagedConfigMdm"
+  | "unknown";
+export const ServerNotification__HookSource = Schema.Literals([
+  "system",
+  "user",
+  "project",
+  "mdm",
+  "sessionFlags",
+  "plugin",
+  "cloudRequirements",
+  "legacyManagedConfigFile",
+  "legacyManagedConfigMdm",
+  "unknown",
+]);
+
+export type ServerNotification__ProcessOutputStream = "stdout" | "stderr";
+export const ServerNotification__ProcessOutputStream = Schema.Literals([
+  "stdout",
+  "stderr",
+]).annotate({ description: "Stream label for `process/outputDelta` notifications." });
+
+export type ServerNotification__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: ServerNotification__SubAgentSource };
+export const ServerNotification__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: ServerNotification__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ServerNotification__TurnItemsView = "notLoaded" | "summary" | "full";
+export const ServerNotification__TurnItemsView = Schema.Literals(["notLoaded", "summary", "full"]);
+
+export type ServerRequest =
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "item/commandExecution/requestApproval";
+      readonly params: ServerRequest__CommandExecutionRequestApprovalParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "item/fileChange/requestApproval";
+      readonly params: ServerRequest__FileChangeRequestApprovalParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "item/tool/requestUserInput";
+      readonly params: ServerRequest__ToolRequestUserInputParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "mcpServer/elicitation/request";
+      readonly params: ServerRequest__McpServerElicitationRequestParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "item/permissions/requestApproval";
+      readonly params: ServerRequest__PermissionsRequestApprovalParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "item/tool/call";
+      readonly params: ServerRequest__DynamicToolCallParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "account/chatgptAuthTokens/refresh";
+      readonly params: ServerRequest__ChatgptAuthTokensRefreshParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "applyPatchApproval";
+      readonly params: ServerRequest__ApplyPatchApprovalParams;
+    }
+  | {
+      readonly id: ServerRequest__RequestId;
+      readonly method: "execCommandApproval";
+      readonly params: ServerRequest__ExecCommandApprovalParams;
+    };
+export const ServerRequest = Schema.Union(
+  [
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("item/commandExecution/requestApproval").annotate({
+        title: "Item/commandExecution/requestApprovalRequestMethod",
+      }),
+      params: ServerRequest__CommandExecutionRequestApprovalParams,
+    }).annotate({
+      title: "Item/commandExecution/requestApprovalRequest",
+      description:
+        "NEW APIs Sent when approval is requested for a specific command execution. This request is used for Turns started via turn/start.",
+    }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("item/fileChange/requestApproval").annotate({
+        title: "Item/fileChange/requestApprovalRequestMethod",
+      }),
+      params: ServerRequest__FileChangeRequestApprovalParams,
+    }).annotate({
+      title: "Item/fileChange/requestApprovalRequest",
+      description:
+        "Sent when approval is requested for a specific file change. This request is used for Turns started via turn/start.",
+    }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("item/tool/requestUserInput").annotate({
+        title: "Item/tool/requestUserInputRequestMethod",
+      }),
+      params: ServerRequest__ToolRequestUserInputParams,
+    }).annotate({
+      title: "Item/tool/requestUserInputRequest",
+      description: "EXPERIMENTAL - Request input from the user for a tool call.",
+    }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("mcpServer/elicitation/request").annotate({
+        title: "McpServer/elicitation/requestRequestMethod",
+      }),
+      params: ServerRequest__McpServerElicitationRequestParams,
+    }).annotate({
+      title: "McpServer/elicitation/requestRequest",
+      description: "Request input for an MCP server elicitation.",
+    }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("item/permissions/requestApproval").annotate({
+        title: "Item/permissions/requestApprovalRequestMethod",
+      }),
+      params: ServerRequest__PermissionsRequestApprovalParams,
+    }).annotate({
+      title: "Item/permissions/requestApprovalRequest",
+      description: "Request approval for additional permissions from the user.",
+    }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("item/tool/call").annotate({ title: "Item/tool/callRequestMethod" }),
+      params: ServerRequest__DynamicToolCallParams,
+    }).annotate({
+      title: "Item/tool/callRequest",
+      description: "Execute a dynamic tool call on the client.",
+    }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("account/chatgptAuthTokens/refresh").annotate({
+        title: "Account/chatgptAuthTokens/refreshRequestMethod",
+      }),
+      params: ServerRequest__ChatgptAuthTokensRefreshParams,
+    }).annotate({ title: "Account/chatgptAuthTokens/refreshRequest" }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("applyPatchApproval").annotate({
+        title: "ApplyPatchApprovalRequestMethod",
+      }),
+      params: ServerRequest__ApplyPatchApprovalParams,
+    }).annotate({
+      title: "ApplyPatchApprovalRequest",
+      description:
+        "DEPRECATED APIs below Request to approve a patch. This request is used for Turns started via the legacy APIs (i.e. SendUserTurn, SendUserMessage).",
+    }),
+    Schema.Struct({
+      id: ServerRequest__RequestId,
+      method: Schema.Literal("execCommandApproval").annotate({
+        title: "ExecCommandApprovalRequestMethod",
+      }),
+      params: ServerRequest__ExecCommandApprovalParams,
+    }).annotate({
+      title: "ExecCommandApprovalRequest",
+      description:
+        "Request to exec a command. This request is used for Turns started via the legacy APIs (i.e. SendUserTurn, SendUserMessage).",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({
+  title: "ServerRequest",
+  description: "Request initiated from the server and sent to the client.",
+});
+
+export type ServerRequest__AdditionalPermissionProfile = {
+  readonly fileSystem?: ServerRequest__AdditionalFileSystemPermissions | null;
+  readonly network?: ServerRequest__AdditionalNetworkPermissions | null;
+};
+export const ServerRequest__AdditionalPermissionProfile = Schema.Struct({
+  fileSystem: Schema.optionalKey(
+    Schema.Union([ServerRequest__AdditionalFileSystemPermissions, Schema.Null]),
+  ),
+  network: Schema.optionalKey(
+    Schema.Union([ServerRequest__AdditionalNetworkPermissions, Schema.Null]).annotate({
+      description: "Partial overlay used for per-command permission requests.",
+    }),
+  ),
+});
+
+export type ServerRequest__CommandExecutionApprovalDecision =
+  | "accept"
+  | "acceptForSession"
+  | {
+      readonly acceptWithExecpolicyAmendment: {
+        readonly execpolicy_amendment: ReadonlyArray<string>;
+      };
+    }
+  | {
+      readonly applyNetworkPolicyAmendment: {
+        readonly network_policy_amendment: ServerRequest__NetworkPolicyAmendment;
+      };
+    }
+  | "decline"
+  | "cancel";
+export const ServerRequest__CommandExecutionApprovalDecision = Schema.Union(
+  [
+    Schema.Literal("accept").annotate({ description: "User approved the command." }),
+    Schema.Literal("acceptForSession").annotate({
+      description:
+        "User approved the command and future prompts in the same session-scoped approval cache should run without prompting.",
+    }),
+    Schema.Struct({
+      acceptWithExecpolicyAmendment: Schema.Struct({
+        execpolicy_amendment: Schema.Array(Schema.String),
+      }),
+    }).annotate({
+      title: "AcceptWithExecpolicyAmendmentCommandExecutionApprovalDecision",
+      description:
+        "User approved the command, and wants to apply the proposed execpolicy amendment so future matching commands can run without prompting.",
+    }),
+    Schema.Struct({
+      applyNetworkPolicyAmendment: Schema.Struct({
+        network_policy_amendment: ServerRequest__NetworkPolicyAmendment,
+      }),
+    }).annotate({
+      title: "ApplyNetworkPolicyAmendmentCommandExecutionApprovalDecision",
+      description: "User chose a persistent network policy rule (allow/deny) for this host.",
+    }),
+    Schema.Literal("decline").annotate({
+      description: "User denied the command. The agent will continue the turn.",
+    }),
+    Schema.Literal("cancel").annotate({
+      description: "User denied the command. The turn will also be immediately interrupted.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type ToolRequestUserInputParams = {
+  readonly itemId: string;
+  readonly questions: ReadonlyArray<ToolRequestUserInputParams__ToolRequestUserInputQuestion>;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const ToolRequestUserInputParams = Schema.Struct({
+  itemId: Schema.String,
+  questions: Schema.Array(ToolRequestUserInputParams__ToolRequestUserInputQuestion),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  title: "ToolRequestUserInputParams",
+  description: "EXPERIMENTAL. Params sent with a request_user_input event.",
+});
+
+export type ToolRequestUserInputResponse = {
+  readonly answers: {
+    readonly [x: string]: ToolRequestUserInputResponse__ToolRequestUserInputAnswer;
+  };
+};
+export const ToolRequestUserInputResponse = Schema.Struct({
+  answers: Schema.Record(Schema.String, ToolRequestUserInputResponse__ToolRequestUserInputAnswer),
+}).annotate({
+  title: "ToolRequestUserInputResponse",
+  description: "EXPERIMENTAL. Response payload mapping question ids to answers.",
+});
+
+export type V1InitializeParams = {
+  readonly capabilities?: V1InitializeParams__InitializeCapabilities | null;
+  readonly clientInfo: V1InitializeParams__ClientInfo;
+};
+export const V1InitializeParams = Schema.Struct({
+  capabilities: Schema.optionalKey(
+    Schema.Union([V1InitializeParams__InitializeCapabilities, Schema.Null]),
+  ),
+  clientInfo: V1InitializeParams__ClientInfo,
+}).annotate({ title: "InitializeParams" });
+
+export type V1InitializeResponse = {
+  readonly codexHome: string;
+  readonly platformFamily: string;
+  readonly platformOs: string;
+  readonly userAgent: string;
+};
+export const V1InitializeResponse = Schema.Struct({
+  codexHome: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  platformFamily: Schema.String.annotate({
+    description:
+      'Platform family for the running app-server target, for example `"unix"` or `"windows"`.',
+  }),
+  platformOs: Schema.String.annotate({
+    description:
+      'Operating system for the running app-server target, for example `"macos"`, `"linux"`, or `"windows"`.',
+  }),
+  userAgent: Schema.String,
+}).annotate({ title: "InitializeResponse" });
+
+export type V1InitializeResponse__AbsolutePathBuf = string;
+export const V1InitializeResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2AccountLoginCompletedNotification = {
+  readonly error?: string | null;
+  readonly loginId?: string | null;
+  readonly success: boolean;
+};
+export const V2AccountLoginCompletedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  loginId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  success: Schema.Boolean,
+}).annotate({ title: "AccountLoginCompletedNotification" });
+
+export type V2AccountRateLimitsUpdatedNotification = {
+  readonly rateLimits: V2AccountRateLimitsUpdatedNotification__RateLimitSnapshot;
+};
+export const V2AccountRateLimitsUpdatedNotification = Schema.Struct({
+  rateLimits: V2AccountRateLimitsUpdatedNotification__RateLimitSnapshot,
+}).annotate({ title: "AccountRateLimitsUpdatedNotification" });
+
+export type V2AccountUpdatedNotification = {
+  readonly authMode?: V2AccountUpdatedNotification__AuthMode | null;
+  readonly planType?: V2AccountUpdatedNotification__PlanType | null;
+};
+export const V2AccountUpdatedNotification = Schema.Struct({
+  authMode: Schema.optionalKey(Schema.Union([V2AccountUpdatedNotification__AuthMode, Schema.Null])),
+  planType: Schema.optionalKey(Schema.Union([V2AccountUpdatedNotification__PlanType, Schema.Null])),
+}).annotate({ title: "AccountUpdatedNotification" });
+
+export type V2AgentMessageDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2AgentMessageDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "AgentMessageDeltaNotification" });
+
+export type V2AppListUpdatedNotification = {
+  readonly data: ReadonlyArray<V2AppListUpdatedNotification__AppInfo>;
+};
+export const V2AppListUpdatedNotification = Schema.Struct({
+  data: Schema.Array(V2AppListUpdatedNotification__AppInfo),
+}).annotate({
+  title: "AppListUpdatedNotification",
+  description: "EXPERIMENTAL - notification emitted when the app list changes.",
+});
+
+export type V2AppsListParams = {
+  readonly cursor?: string | null;
+  readonly forceRefetch?: boolean;
+  readonly limit?: number | null;
+  readonly threadId?: string | null;
+};
+export const V2AppsListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  forceRefetch: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "When true, bypass app caches and fetch the latest data from sources.",
+    }),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional thread id used to evaluate app feature gating from that thread's config.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  title: "AppsListParams",
+  description: "EXPERIMENTAL - list available apps/connectors.",
+});
+
+export type V2AppsListResponse = {
+  readonly data: ReadonlyArray<V2AppsListResponse__AppInfo>;
+  readonly nextCursor?: string | null;
+};
+export const V2AppsListResponse = Schema.Struct({
+  data: Schema.Array(V2AppsListResponse__AppInfo),
+  nextCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor to pass to the next call to continue after the last item. If None, there are no more items to return.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "AppsListResponse", description: "EXPERIMENTAL - app list response." });
+
+export type V2CancelLoginAccountParams = { readonly loginId: string };
+export const V2CancelLoginAccountParams = Schema.Struct({ loginId: Schema.String }).annotate({
+  title: "CancelLoginAccountParams",
+});
+
+export type V2CancelLoginAccountResponse = {
+  readonly status: V2CancelLoginAccountResponse__CancelLoginAccountStatus;
+};
+export const V2CancelLoginAccountResponse = Schema.Struct({
+  status: V2CancelLoginAccountResponse__CancelLoginAccountStatus,
+}).annotate({ title: "CancelLoginAccountResponse" });
+
+export type V2CommandExecOutputDeltaNotification = {
+  readonly capReached: boolean;
+  readonly deltaBase64: string;
+  readonly processId: string;
+  readonly stream: "stdout" | "stderr";
+};
+export const V2CommandExecOutputDeltaNotification = Schema.Struct({
+  capReached: Schema.Boolean.annotate({
+    description:
+      "`true` on the final streamed chunk for a stream when `outputBytesCap` truncated later output on that stream.",
+  }),
+  deltaBase64: Schema.String.annotate({ description: "Base64-encoded output bytes." }),
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+  stream: Schema.Literals(["stdout", "stderr"]).annotate({
+    description: "Stream label for `command/exec/outputDelta` notifications.",
+  }),
+}).annotate({
+  title: "CommandExecOutputDeltaNotification",
+  description:
+    "Base64-encoded output chunk emitted for a streaming `command/exec` request.\n\nThese notifications are connection-scoped. If the originating connection closes, the server terminates the process.",
+});
+
+export type V2CommandExecOutputDeltaNotification__CommandExecOutputStream = "stdout" | "stderr";
+export const V2CommandExecOutputDeltaNotification__CommandExecOutputStream = Schema.Literals([
+  "stdout",
+  "stderr",
+]).annotate({ description: "Stream label for `command/exec/outputDelta` notifications." });
+
+export type V2CommandExecParams = {
+  readonly command: ReadonlyArray<string>;
+  readonly cwd?: string | null;
+  readonly disableOutputCap?: boolean;
+  readonly disableTimeout?: boolean;
+  readonly env?: { readonly [x: string]: string | null } | null;
+  readonly outputBytesCap?: number | null;
+  readonly processId?: string | null;
+  readonly sandboxPolicy?: V2CommandExecParams__SandboxPolicy | null;
+  readonly size?: V2CommandExecParams__CommandExecTerminalSize | null;
+  readonly streamStdin?: boolean;
+  readonly streamStdoutStderr?: boolean;
+  readonly timeoutMs?: number | null;
+  readonly tty?: boolean;
+};
+export const V2CommandExecParams = Schema.Struct({
+  command: Schema.Array(Schema.String).annotate({
+    description: "Command argv vector. Empty arrays are rejected.",
+  }),
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional working directory. Defaults to the server cwd.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  disableOutputCap: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Disable stdout/stderr capture truncation for this request.\n\nCannot be combined with `outputBytesCap`.",
+    }),
+  ),
+  disableTimeout: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Disable the timeout entirely for this request.\n\nCannot be combined with `timeoutMs`.",
+    }),
+  ),
+  env: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Null])).annotate({
+        description:
+          "Optional environment overrides merged into the server-computed environment.\n\nMatching names override inherited values. Set a key to `null` to unset an inherited variable.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  outputBytesCap: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description:
+          "Optional per-stream stdout/stderr capture cap in bytes.\n\nWhen omitted, the server default applies. Cannot be combined with `disableOutputCap`.",
+        format: "uint",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  processId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional client-supplied, connection-scoped process id.\n\nRequired for `tty`, `streamStdin`, `streamStdoutStderr`, and follow-up `command/exec/write`, `command/exec/resize`, and `command/exec/terminate` calls. When omitted, buffered execution gets an internal id that is not exposed to the client.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sandboxPolicy: Schema.optionalKey(
+    Schema.Union([V2CommandExecParams__SandboxPolicy, Schema.Null]).annotate({
+      description:
+        "Optional sandbox policy for this command.\n\nUses the same shape as thread/turn execution sandbox configuration and defaults to the user's configured policy when omitted. Cannot be combined with `permissionProfile`.",
+    }),
+  ),
+  size: Schema.optionalKey(
+    Schema.Union([V2CommandExecParams__CommandExecTerminalSize, Schema.Null]).annotate({
+      description: "Optional initial PTY size in character cells. Only valid when `tty` is true.",
+    }),
+  ),
+  streamStdin: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Allow follow-up `command/exec/write` requests to write stdin bytes.\n\nRequires a client-supplied `processId`.",
+    }),
+  ),
+  streamStdoutStderr: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Stream stdout/stderr via `command/exec/outputDelta` notifications.\n\nStreamed bytes are not duplicated into the final response and require a client-supplied `processId`.",
+    }),
+  ),
+  timeoutMs: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description:
+          "Optional timeout in milliseconds.\n\nWhen omitted, the server default applies. Cannot be combined with `disableTimeout`.",
+        format: "int64",
+      }).check(Schema.isInt()),
+      Schema.Null,
+    ]),
+  ),
+  tty: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Enable PTY mode.\n\nThis implies `streamStdin` and `streamStdoutStderr`.",
+    }),
+  ),
+}).annotate({
+  title: "CommandExecParams",
+  description:
+    "Run a standalone command (argv vector) in the server sandbox without creating a thread or turn.\n\nThe final `command/exec` response is deferred until the process exits and is sent only after all `command/exec/outputDelta` notifications for that connection have been emitted.",
+});
+
+export type V2CommandExecParams__NetworkAccess = "restricted" | "enabled";
+export const V2CommandExecParams__NetworkAccess = Schema.Literals(["restricted", "enabled"]);
+
+export type V2CommandExecParams__PermissionProfile =
+  | {
+      readonly fileSystem: V2CommandExecParams__PermissionProfileFileSystemPermissions;
+      readonly network: V2CommandExecParams__PermissionProfileNetworkPermissions;
+      readonly type: "managed";
+    }
+  | { readonly type: "disabled" }
+  | {
+      readonly network: V2CommandExecParams__PermissionProfileNetworkPermissions;
+      readonly type: "external";
+    };
+export const V2CommandExecParams__PermissionProfile = Schema.Union(
+  [
+    Schema.Struct({
+      fileSystem: V2CommandExecParams__PermissionProfileFileSystemPermissions,
+      network: V2CommandExecParams__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("managed").annotate({ title: "ManagedPermissionProfileType" }),
+    }).annotate({
+      title: "ManagedPermissionProfile",
+      description: "Codex owns sandbox construction for this profile.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("disabled").annotate({ title: "DisabledPermissionProfileType" }),
+    }).annotate({
+      title: "DisabledPermissionProfile",
+      description: "Do not apply an outer sandbox.",
+    }),
+    Schema.Struct({
+      network: V2CommandExecParams__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("external").annotate({ title: "ExternalPermissionProfileType" }),
+    }).annotate({
+      title: "ExternalPermissionProfile",
+      description: "Filesystem isolation is enforced by an external caller.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2CommandExecResizeParams = {
+  readonly processId: string;
+  readonly size: { readonly cols: number; readonly rows: number };
+};
+export const V2CommandExecResizeParams = Schema.Struct({
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+  size: Schema.Struct({
+    cols: Schema.Number.annotate({
+      description: "Terminal width in character cells.",
+      format: "uint16",
+    })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+    rows: Schema.Number.annotate({
+      description: "Terminal height in character cells.",
+      format: "uint16",
+    })
+      .check(Schema.isInt())
+      .check(Schema.isGreaterThanOrEqualTo(0)),
+  }).annotate({ description: "PTY size in character cells for `command/exec` PTY sessions." }),
+}).annotate({
+  title: "CommandExecResizeParams",
+  description: "Resize a running PTY-backed `command/exec` session.",
+});
+
+export type V2CommandExecResizeParams__CommandExecTerminalSize = {
+  readonly cols: number;
+  readonly rows: number;
+};
+export const V2CommandExecResizeParams__CommandExecTerminalSize = Schema.Struct({
+  cols: Schema.Number.annotate({
+    description: "Terminal width in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  rows: Schema.Number.annotate({
+    description: "Terminal height in character cells.",
+    format: "uint16",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+}).annotate({ description: "PTY size in character cells for `command/exec` PTY sessions." });
+
+export type V2CommandExecResizeResponse = {};
+export const V2CommandExecResizeResponse = Schema.Struct({}).annotate({
+  title: "CommandExecResizeResponse",
+  description: "Empty success response for `command/exec/resize`.",
+});
+
+export type V2CommandExecResponse = {
+  readonly exitCode: number;
+  readonly stderr: string;
+  readonly stdout: string;
+};
+export const V2CommandExecResponse = Schema.Struct({
+  exitCode: Schema.Number.annotate({ description: "Process exit code.", format: "int32" }).check(
+    Schema.isInt(),
+  ),
+  stderr: Schema.String.annotate({
+    description:
+      "Buffered stderr capture.\n\nEmpty when stderr was streamed via `command/exec/outputDelta`.",
+  }),
+  stdout: Schema.String.annotate({
+    description:
+      "Buffered stdout capture.\n\nEmpty when stdout was streamed via `command/exec/outputDelta`.",
+  }),
+}).annotate({
+  title: "CommandExecResponse",
+  description: "Final buffered result for `command/exec`.",
+});
+
+export type V2CommandExecTerminateParams = { readonly processId: string };
+export const V2CommandExecTerminateParams = Schema.Struct({
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+}).annotate({
+  title: "CommandExecTerminateParams",
+  description: "Terminate a running `command/exec` session.",
+});
+
+export type V2CommandExecTerminateResponse = {};
+export const V2CommandExecTerminateResponse = Schema.Struct({}).annotate({
+  title: "CommandExecTerminateResponse",
+  description: "Empty success response for `command/exec/terminate`.",
+});
+
+export type V2CommandExecutionOutputDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2CommandExecutionOutputDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "CommandExecutionOutputDeltaNotification" });
+
+export type V2CommandExecWriteParams = {
+  readonly closeStdin?: boolean;
+  readonly deltaBase64?: string | null;
+  readonly processId: string;
+};
+export const V2CommandExecWriteParams = Schema.Struct({
+  closeStdin: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Close stdin after writing `deltaBase64`, if present.",
+    }),
+  ),
+  deltaBase64: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional base64-encoded stdin bytes to write." }),
+      Schema.Null,
+    ]),
+  ),
+  processId: Schema.String.annotate({
+    description:
+      "Client-supplied, connection-scoped `processId` from the original `command/exec` request.",
+  }),
+}).annotate({
+  title: "CommandExecWriteParams",
+  description: "Write stdin bytes to a running `command/exec` session, close stdin, or both.",
+});
+
+export type V2CommandExecWriteResponse = {};
+export const V2CommandExecWriteResponse = Schema.Struct({}).annotate({
+  title: "CommandExecWriteResponse",
+  description: "Empty success response for `command/exec/write`.",
+});
+
+export type V2ConfigBatchWriteParams = {
+  readonly edits: ReadonlyArray<V2ConfigBatchWriteParams__ConfigEdit>;
+  readonly expectedVersion?: string | null;
+  readonly filePath?: string | null;
+  readonly reloadUserConfig?: boolean;
+};
+export const V2ConfigBatchWriteParams = Schema.Struct({
+  edits: Schema.Array(V2ConfigBatchWriteParams__ConfigEdit),
+  expectedVersion: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  filePath: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Path to the config file to write; defaults to the user's `config.toml` when omitted.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  reloadUserConfig: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "When true, hot-reload the updated user config into all loaded threads after writing.",
+    }),
+  ),
+}).annotate({ title: "ConfigBatchWriteParams" });
+
+export type V2ConfigReadParams = { readonly cwd?: string | null; readonly includeLayers?: boolean };
+export const V2ConfigReadParams = Schema.Struct({
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional working directory to resolve project config layers. If specified, return the effective config as seen from that directory (i.e., including any project layers between `cwd` and the project/repo root).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  includeLayers: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+}).annotate({ title: "ConfigReadParams" });
+
+export type V2ConfigReadResponse = {
+  readonly config: V2ConfigReadResponse__Config;
+  readonly layers?: ReadonlyArray<V2ConfigReadResponse__ConfigLayer> | null;
+  readonly origins: { readonly [x: string]: V2ConfigReadResponse__ConfigLayerMetadata };
+};
+export const V2ConfigReadResponse = Schema.Struct({
+  config: V2ConfigReadResponse__Config,
+  layers: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2ConfigReadResponse__ConfigLayer), Schema.Null]),
+  ),
+  origins: Schema.Record(Schema.String, V2ConfigReadResponse__ConfigLayerMetadata),
+}).annotate({ title: "ConfigReadResponse" });
+
+export type V2ConfigReadResponse__AppConfig = {
+  readonly default_tools_approval_mode?: V2ConfigReadResponse__AppToolApproval | null;
+  readonly default_tools_enabled?: boolean | null;
+  readonly destructive_enabled?: boolean | null;
+  readonly enabled?: boolean;
+  readonly open_world_enabled?: boolean | null;
+  readonly tools?: V2ConfigReadResponse__AppToolsConfig | null;
+};
+export const V2ConfigReadResponse__AppConfig = Schema.Struct({
+  default_tools_approval_mode: Schema.optionalKey(
+    Schema.Union([V2ConfigReadResponse__AppToolApproval, Schema.Null]),
+  ),
+  default_tools_enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  destructive_enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  enabled: Schema.optionalKey(Schema.Boolean.annotate({ default: true })),
+  open_world_enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  tools: Schema.optionalKey(Schema.Union([V2ConfigReadResponse__AppToolsConfig, Schema.Null])),
+});
+
+export type V2ConfigReadResponse__AppsConfig = {
+  readonly _default?: V2ConfigReadResponse__AppsDefaultConfig | null;
+};
+export const V2ConfigReadResponse__AppsConfig = Schema.Struct({
+  _default: Schema.optionalKey(
+    Schema.Union([V2ConfigReadResponse__AppsDefaultConfig, Schema.Null]),
+  ),
+});
+
+export type V2ConfigReadResponse__AppToolConfig = {
+  readonly approval_mode?: V2ConfigReadResponse__AppToolApproval | null;
+  readonly enabled?: boolean | null;
+};
+export const V2ConfigReadResponse__AppToolConfig = Schema.Struct({
+  approval_mode: Schema.optionalKey(
+    Schema.Union([V2ConfigReadResponse__AppToolApproval, Schema.Null]),
+  ),
+  enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+});
+
+export type V2ConfigRequirementsReadResponse = {
+  readonly requirements?: V2ConfigRequirementsReadResponse__ConfigRequirements | null;
+};
+export const V2ConfigRequirementsReadResponse = Schema.Struct({
+  requirements: Schema.optionalKey(
+    Schema.Union([V2ConfigRequirementsReadResponse__ConfigRequirements, Schema.Null]).annotate({
+      description:
+        "Null if no requirements are configured (e.g. no requirements.toml/MDM entries).",
+    }),
+  ),
+}).annotate({ title: "ConfigRequirementsReadResponse" });
+
+export type V2ConfigRequirementsReadResponse__ApprovalsReviewer =
+  | "user"
+  | "auto_review"
+  | "guardian_subagent";
+export const V2ConfigRequirementsReadResponse__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ConfigRequirementsReadResponse__ManagedHooksRequirements = {
+  readonly PermissionRequest: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly PostCompact: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly PostToolUse: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly PreCompact: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly PreToolUse: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly SessionStart: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly Stop: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly UserPromptSubmit: ReadonlyArray<V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup>;
+  readonly managedDir?: string | null;
+  readonly windowsManagedDir?: string | null;
+};
+export const V2ConfigRequirementsReadResponse__ManagedHooksRequirements = Schema.Struct({
+  PermissionRequest: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  PostCompact: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  PostToolUse: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  PreCompact: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  PreToolUse: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  SessionStart: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  Stop: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  UserPromptSubmit: Schema.Array(V2ConfigRequirementsReadResponse__ConfiguredHookMatcherGroup),
+  managedDir: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  windowsManagedDir: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ConfigRequirementsReadResponse__NetworkRequirements = {
+  readonly allowLocalBinding?: boolean | null;
+  readonly allowUnixSockets?: ReadonlyArray<string> | null;
+  readonly allowUpstreamProxy?: boolean | null;
+  readonly allowedDomains?: ReadonlyArray<string> | null;
+  readonly dangerouslyAllowAllUnixSockets?: boolean | null;
+  readonly dangerouslyAllowNonLoopbackProxy?: boolean | null;
+  readonly deniedDomains?: ReadonlyArray<string> | null;
+  readonly domains?: {
+    readonly [x: string]: V2ConfigRequirementsReadResponse__NetworkDomainPermission;
+  } | null;
+  readonly enabled?: boolean | null;
+  readonly httpPort?: number | null;
+  readonly managedAllowedDomainsOnly?: boolean | null;
+  readonly socksPort?: number | null;
+  readonly unixSockets?: {
+    readonly [x: string]: V2ConfigRequirementsReadResponse__NetworkUnixSocketPermission;
+  } | null;
+};
+export const V2ConfigRequirementsReadResponse__NetworkRequirements = Schema.Struct({
+  allowLocalBinding: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  allowUnixSockets: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description: "Legacy compatibility view derived from `unix_sockets`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  allowUpstreamProxy: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  allowedDomains: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description: "Legacy compatibility view derived from `domains`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  dangerouslyAllowAllUnixSockets: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  dangerouslyAllowNonLoopbackProxy: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  deniedDomains: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description: "Legacy compatibility view derived from `domains`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  domains: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(
+        Schema.String,
+        V2ConfigRequirementsReadResponse__NetworkDomainPermission,
+      ).annotate({ description: "Canonical network permission map for `experimental_network`." }),
+      Schema.Null,
+    ]),
+  ),
+  enabled: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  httpPort: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint16" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  managedAllowedDomainsOnly: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description:
+          "When true, only managed allowlist entries are respected while managed network enforcement is active.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  socksPort: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({ format: "uint16" })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  unixSockets: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(
+        Schema.String,
+        V2ConfigRequirementsReadResponse__NetworkUnixSocketPermission,
+      ).annotate({
+        description: "Canonical unix socket permission map for `experimental_network`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+});
+
+export type V2ConfigValueWriteParams = {
+  readonly expectedVersion?: string | null;
+  readonly filePath?: string | null;
+  readonly keyPath: string;
+  readonly mergeStrategy: V2ConfigValueWriteParams__MergeStrategy;
+  readonly value: unknown;
+};
+export const V2ConfigValueWriteParams = Schema.Struct({
+  expectedVersion: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  filePath: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Path to the config file to write; defaults to the user's `config.toml` when omitted.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  keyPath: Schema.String,
+  mergeStrategy: V2ConfigValueWriteParams__MergeStrategy,
+  value: Schema.Unknown,
+}).annotate({ title: "ConfigValueWriteParams" });
+
+export type V2ConfigWarningNotification = {
+  readonly details?: string | null;
+  readonly path?: string | null;
+  readonly range?: V2ConfigWarningNotification__TextRange | null;
+  readonly summary: string;
+};
+export const V2ConfigWarningNotification = Schema.Struct({
+  details: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional extra guidance or error details." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional path to the config file that triggered the warning.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  range: Schema.optionalKey(
+    Schema.Union([V2ConfigWarningNotification__TextRange, Schema.Null]).annotate({
+      description: "Optional range for the error location inside the config file.",
+    }),
+  ),
+  summary: Schema.String.annotate({ description: "Concise summary of the warning." }),
+}).annotate({ title: "ConfigWarningNotification" });
+
+export type V2ConfigWriteResponse = {
+  readonly filePath: string;
+  readonly overriddenMetadata?: V2ConfigWriteResponse__OverriddenMetadata | null;
+  readonly status: V2ConfigWriteResponse__WriteStatus;
+  readonly version: string;
+};
+export const V2ConfigWriteResponse = Schema.Struct({
+  filePath: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  overriddenMetadata: Schema.optionalKey(
+    Schema.Union([V2ConfigWriteResponse__OverriddenMetadata, Schema.Null]),
+  ),
+  status: V2ConfigWriteResponse__WriteStatus,
+  version: Schema.String,
+}).annotate({ title: "ConfigWriteResponse" });
+
+export type V2ContextCompactedNotification = { readonly threadId: string; readonly turnId: string };
+export const V2ContextCompactedNotification = Schema.Struct({
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  title: "ContextCompactedNotification",
+  description: "Deprecated: Use `ContextCompaction` item type instead.",
+});
+
+export type V2DeprecationNoticeNotification = {
+  readonly details?: string | null;
+  readonly summary: string;
+};
+export const V2DeprecationNoticeNotification = Schema.Struct({
+  details: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional extra guidance, such as migration steps or rationale.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  summary: Schema.String.annotate({ description: "Concise summary of what is deprecated." }),
+}).annotate({ title: "DeprecationNoticeNotification" });
+
+export type V2ErrorNotification = {
+  readonly error: V2ErrorNotification__TurnError;
+  readonly threadId: string;
+  readonly turnId: string;
+  readonly willRetry: boolean;
+};
+export const V2ErrorNotification = Schema.Struct({
+  error: V2ErrorNotification__TurnError,
+  threadId: Schema.String,
+  turnId: Schema.String,
+  willRetry: Schema.Boolean,
+}).annotate({ title: "ErrorNotification" });
+
+export type V2ExperimentalFeatureEnablementSetParams = {
+  readonly enablement: { readonly [x: string]: boolean };
+};
+export const V2ExperimentalFeatureEnablementSetParams = Schema.Struct({
+  enablement: Schema.Record(Schema.String, Schema.Boolean).annotate({
+    description:
+      "Process-wide runtime feature enablement keyed by canonical feature name.\n\nOnly named features are updated. Omitted features are left unchanged. Send an empty map for a no-op.",
+  }),
+}).annotate({ title: "ExperimentalFeatureEnablementSetParams" });
+
+export type V2ExperimentalFeatureEnablementSetResponse = {
+  readonly enablement: { readonly [x: string]: boolean };
+};
+export const V2ExperimentalFeatureEnablementSetResponse = Schema.Struct({
+  enablement: Schema.Record(Schema.String, Schema.Boolean).annotate({
+    description: "Feature enablement entries updated by this request.",
+  }),
+}).annotate({ title: "ExperimentalFeatureEnablementSetResponse" });
+
+export type V2ExperimentalFeatureListParams = {
+  readonly cursor?: string | null;
+  readonly limit?: number | null;
+};
+export const V2ExperimentalFeatureListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ExperimentalFeatureListParams" });
+
+export type V2ExperimentalFeatureListResponse = {
+  readonly data: ReadonlyArray<V2ExperimentalFeatureListResponse__ExperimentalFeature>;
+  readonly nextCursor?: string | null;
+};
+export const V2ExperimentalFeatureListResponse = Schema.Struct({
+  data: Schema.Array(V2ExperimentalFeatureListResponse__ExperimentalFeature),
+  nextCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor to pass to the next call to continue after the last item. If None, there are no more items to return.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ExperimentalFeatureListResponse" });
+
+export type V2ExperimentalFeatureListResponse__ExperimentalFeatureStage =
+  | "beta"
+  | "underDevelopment"
+  | "stable"
+  | "deprecated"
+  | "removed";
+export const V2ExperimentalFeatureListResponse__ExperimentalFeatureStage = Schema.Literals([
+  "beta",
+  "underDevelopment",
+  "stable",
+  "deprecated",
+  "removed",
+]);
+
+export type V2ExternalAgentConfigDetectParams = {
+  readonly cwds?: ReadonlyArray<string> | null;
+  readonly includeHome?: boolean;
+};
+export const V2ExternalAgentConfigDetectParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description: "Zero or more working directories to include for repo-scoped detection.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  includeHome: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "If true, include detection under the user's home (~/.claude, ~/.codex, etc.).",
+    }),
+  ),
+}).annotate({ title: "ExternalAgentConfigDetectParams" });
+
+export type V2ExternalAgentConfigDetectResponse = {
+  readonly items: ReadonlyArray<V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItem>;
+};
+export const V2ExternalAgentConfigDetectResponse = Schema.Struct({
+  items: Schema.Array(V2ExternalAgentConfigDetectResponse__ExternalAgentConfigMigrationItem),
+}).annotate({ title: "ExternalAgentConfigDetectResponse" });
+
+export type V2ExternalAgentConfigImportCompletedNotification = {};
+export const V2ExternalAgentConfigImportCompletedNotification = Schema.Struct({}).annotate({
+  title: "ExternalAgentConfigImportCompletedNotification",
+});
+
+export type V2ExternalAgentConfigImportParams = {
+  readonly migrationItems: ReadonlyArray<V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItem>;
+};
+export const V2ExternalAgentConfigImportParams = Schema.Struct({
+  migrationItems: Schema.Array(V2ExternalAgentConfigImportParams__ExternalAgentConfigMigrationItem),
+}).annotate({ title: "ExternalAgentConfigImportParams" });
+
+export type V2ExternalAgentConfigImportResponse = {};
+export const V2ExternalAgentConfigImportResponse = Schema.Struct({}).annotate({
+  title: "ExternalAgentConfigImportResponse",
+});
+
+export type V2FeedbackUploadParams = {
+  readonly classification: string;
+  readonly extraLogFiles?: ReadonlyArray<string> | null;
+  readonly includeLogs: boolean;
+  readonly reason?: string | null;
+  readonly tags?: { readonly [x: string]: string } | null;
+  readonly threadId?: string | null;
+};
+export const V2FeedbackUploadParams = Schema.Struct({
+  classification: Schema.String,
+  extraLogFiles: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  includeLogs: Schema.Boolean,
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  tags: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.String), Schema.Null]),
+  ),
+  threadId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "FeedbackUploadParams" });
+
+export type V2FeedbackUploadResponse = { readonly threadId: string };
+export const V2FeedbackUploadResponse = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "FeedbackUploadResponse",
+});
+
+export type V2FileChangeOutputDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2FileChangeOutputDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  title: "FileChangeOutputDeltaNotification",
+  description:
+    "Deprecated legacy notification for `apply_patch` textual output.\n\nThe server no longer emits this notification.",
+});
+
+export type V2FileChangePatchUpdatedNotification = {
+  readonly changes: ReadonlyArray<V2FileChangePatchUpdatedNotification__FileUpdateChange>;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2FileChangePatchUpdatedNotification = Schema.Struct({
+  changes: Schema.Array(V2FileChangePatchUpdatedNotification__FileUpdateChange),
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "FileChangePatchUpdatedNotification" });
+
+export type V2FsChangedNotification = {
+  readonly changedPaths: ReadonlyArray<V2FsChangedNotification__AbsolutePathBuf>;
+  readonly watchId: string;
+};
+export const V2FsChangedNotification = Schema.Struct({
+  changedPaths: Schema.Array(V2FsChangedNotification__AbsolutePathBuf).annotate({
+    description: "File or directory paths associated with this event.",
+  }),
+  watchId: Schema.String.annotate({
+    description: "Watch identifier previously provided to `fs/watch`.",
+  }),
+}).annotate({
+  title: "FsChangedNotification",
+  description: "Filesystem watch notification emitted for `fs/watch` subscribers.",
+});
+
+export type V2FsCopyParams = {
+  readonly destinationPath: string;
+  readonly recursive?: boolean;
+  readonly sourcePath: string;
+};
+export const V2FsCopyParams = Schema.Struct({
+  destinationPath: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  recursive: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "Required for directory copies; ignored for file copies.",
+    }),
+  ),
+  sourcePath: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({
+  title: "FsCopyParams",
+  description: "Copy a file or directory tree on the host filesystem.",
+});
+
+export type V2FsCopyParams__AbsolutePathBuf = string;
+export const V2FsCopyParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsCopyResponse = {};
+export const V2FsCopyResponse = Schema.Struct({}).annotate({
+  title: "FsCopyResponse",
+  description: "Successful response for `fs/copy`.",
+});
+
+export type V2FsCreateDirectoryParams = {
+  readonly path: string;
+  readonly recursive?: boolean | null;
+};
+export const V2FsCreateDirectoryParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  recursive: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "Whether parent directories should also be created. Defaults to `true`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  title: "FsCreateDirectoryParams",
+  description: "Create a directory on the host filesystem.",
+});
+
+export type V2FsCreateDirectoryParams__AbsolutePathBuf = string;
+export const V2FsCreateDirectoryParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsCreateDirectoryResponse = {};
+export const V2FsCreateDirectoryResponse = Schema.Struct({}).annotate({
+  title: "FsCreateDirectoryResponse",
+  description: "Successful response for `fs/createDirectory`.",
+});
+
+export type V2FsGetMetadataParams = { readonly path: string };
+export const V2FsGetMetadataParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({
+  title: "FsGetMetadataParams",
+  description: "Request metadata for an absolute path.",
+});
+
+export type V2FsGetMetadataParams__AbsolutePathBuf = string;
+export const V2FsGetMetadataParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsGetMetadataResponse = {
+  readonly createdAtMs: number;
+  readonly isDirectory: boolean;
+  readonly isFile: boolean;
+  readonly isSymlink: boolean;
+  readonly modifiedAtMs: number;
+};
+export const V2FsGetMetadataResponse = Schema.Struct({
+  createdAtMs: Schema.Number.annotate({
+    description: "File creation time in Unix milliseconds when available, otherwise `0`.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  isDirectory: Schema.Boolean.annotate({
+    description: "Whether the path resolves to a directory.",
+  }),
+  isFile: Schema.Boolean.annotate({ description: "Whether the path resolves to a regular file." }),
+  isSymlink: Schema.Boolean.annotate({
+    description: "Whether the path itself is a symbolic link.",
+  }),
+  modifiedAtMs: Schema.Number.annotate({
+    description: "File modification time in Unix milliseconds when available, otherwise `0`.",
+    format: "int64",
+  }).check(Schema.isInt()),
+}).annotate({
+  title: "FsGetMetadataResponse",
+  description: "Metadata returned by `fs/getMetadata`.",
+});
+
+export type V2FsReadDirectoryParams = { readonly path: string };
+export const V2FsReadDirectoryParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({
+  title: "FsReadDirectoryParams",
+  description: "List direct child names for a directory.",
+});
+
+export type V2FsReadDirectoryParams__AbsolutePathBuf = string;
+export const V2FsReadDirectoryParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsReadDirectoryResponse = {
+  readonly entries: ReadonlyArray<V2FsReadDirectoryResponse__FsReadDirectoryEntry>;
+};
+export const V2FsReadDirectoryResponse = Schema.Struct({
+  entries: Schema.Array(V2FsReadDirectoryResponse__FsReadDirectoryEntry).annotate({
+    description: "Direct child entries in the requested directory.",
+  }),
+}).annotate({
+  title: "FsReadDirectoryResponse",
+  description: "Directory entries returned by `fs/readDirectory`.",
+});
+
+export type V2FsReadFileParams = { readonly path: string };
+export const V2FsReadFileParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ title: "FsReadFileParams", description: "Read a file from the host filesystem." });
+
+export type V2FsReadFileParams__AbsolutePathBuf = string;
+export const V2FsReadFileParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsReadFileResponse = { readonly dataBase64: string };
+export const V2FsReadFileResponse = Schema.Struct({
+  dataBase64: Schema.String.annotate({ description: "File contents encoded as base64." }),
+}).annotate({
+  title: "FsReadFileResponse",
+  description: "Base64-encoded file contents returned by `fs/readFile`.",
+});
+
+export type V2FsRemoveParams = {
+  readonly force?: boolean | null;
+  readonly path: string;
+  readonly recursive?: boolean | null;
+};
+export const V2FsRemoveParams = Schema.Struct({
+  force: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "Whether missing paths should be ignored. Defaults to `true`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  recursive: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "Whether directory removal should recurse. Defaults to `true`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({
+  title: "FsRemoveParams",
+  description: "Remove a file or directory tree from the host filesystem.",
+});
+
+export type V2FsRemoveParams__AbsolutePathBuf = string;
+export const V2FsRemoveParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsRemoveResponse = {};
+export const V2FsRemoveResponse = Schema.Struct({}).annotate({
+  title: "FsRemoveResponse",
+  description: "Successful response for `fs/remove`.",
+});
+
+export type V2FsUnwatchParams = { readonly watchId: string };
+export const V2FsUnwatchParams = Schema.Struct({
+  watchId: Schema.String.annotate({
+    description: "Watch identifier previously provided to `fs/watch`.",
+  }),
+}).annotate({
+  title: "FsUnwatchParams",
+  description: "Stop filesystem watch notifications for a prior `fs/watch`.",
+});
+
+export type V2FsUnwatchResponse = {};
+export const V2FsUnwatchResponse = Schema.Struct({}).annotate({
+  title: "FsUnwatchResponse",
+  description: "Successful response for `fs/unwatch`.",
+});
+
+export type V2FsWatchParams = { readonly path: string; readonly watchId: string };
+export const V2FsWatchParams = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  watchId: Schema.String.annotate({
+    description: "Connection-scoped watch identifier used for `fs/unwatch` and `fs/changed`.",
+  }),
+}).annotate({
+  title: "FsWatchParams",
+  description: "Start filesystem watch notifications for an absolute path.",
+});
+
+export type V2FsWatchParams__AbsolutePathBuf = string;
+export const V2FsWatchParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsWatchResponse = { readonly path: string };
+export const V2FsWatchResponse = Schema.Struct({
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ title: "FsWatchResponse", description: "Successful response for `fs/watch`." });
+
+export type V2FsWatchResponse__AbsolutePathBuf = string;
+export const V2FsWatchResponse__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsWriteFileParams = { readonly dataBase64: string; readonly path: string };
+export const V2FsWriteFileParams = Schema.Struct({
+  dataBase64: Schema.String.annotate({ description: "File contents encoded as base64." }),
+  path: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+}).annotate({ title: "FsWriteFileParams", description: "Write a file on the host filesystem." });
+
+export type V2FsWriteFileParams__AbsolutePathBuf = string;
+export const V2FsWriteFileParams__AbsolutePathBuf = Schema.String.annotate({
+  description:
+    "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+});
+
+export type V2FsWriteFileResponse = {};
+export const V2FsWriteFileResponse = Schema.Struct({}).annotate({
+  title: "FsWriteFileResponse",
+  description: "Successful response for `fs/writeFile`.",
+});
+
+export type V2GetAccountParams = { readonly refreshToken?: boolean };
+export const V2GetAccountParams = Schema.Struct({
+  refreshToken: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "When `true`, requests a proactive token refresh before returning.\n\nIn managed auth mode this triggers the normal refresh-token flow. In external auth mode this flag is ignored. Clients should refresh tokens themselves and call `account/login/start` with `chatgptAuthTokens`.",
+      default: false,
+    }),
+  ),
+}).annotate({ title: "GetAccountParams" });
+
+export type V2GetAccountRateLimitsResponse = {
+  readonly rateLimits: {
+    readonly credits?: V2GetAccountRateLimitsResponse__CreditsSnapshot | null;
+    readonly limitId?: string | null;
+    readonly limitName?: string | null;
+    readonly planType?: V2GetAccountRateLimitsResponse__PlanType | null;
+    readonly primary?: V2GetAccountRateLimitsResponse__RateLimitWindow | null;
+    readonly rateLimitReachedType?: V2GetAccountRateLimitsResponse__RateLimitReachedType | null;
+    readonly secondary?: V2GetAccountRateLimitsResponse__RateLimitWindow | null;
+  };
+  readonly rateLimitsByLimitId?: {
+    readonly [x: string]: V2GetAccountRateLimitsResponse__RateLimitSnapshot;
+  } | null;
+};
+export const V2GetAccountRateLimitsResponse = Schema.Struct({
+  rateLimits: Schema.Struct({
+    credits: Schema.optionalKey(
+      Schema.Union([V2GetAccountRateLimitsResponse__CreditsSnapshot, Schema.Null]),
+    ),
+    limitId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    limitName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+    planType: Schema.optionalKey(
+      Schema.Union([V2GetAccountRateLimitsResponse__PlanType, Schema.Null]),
+    ),
+    primary: Schema.optionalKey(
+      Schema.Union([V2GetAccountRateLimitsResponse__RateLimitWindow, Schema.Null]),
+    ),
+    rateLimitReachedType: Schema.optionalKey(
+      Schema.Union([V2GetAccountRateLimitsResponse__RateLimitReachedType, Schema.Null]),
+    ),
+    secondary: Schema.optionalKey(
+      Schema.Union([V2GetAccountRateLimitsResponse__RateLimitWindow, Schema.Null]),
+    ),
+  }).annotate({
+    description: "Backward-compatible single-bucket view; mirrors the historical payload.",
+  }),
+  rateLimitsByLimitId: Schema.optionalKey(
+    Schema.Union([
+      Schema.Record(Schema.String, V2GetAccountRateLimitsResponse__RateLimitSnapshot).annotate({
+        description: "Multi-bucket view keyed by metered `limit_id` (for example, `codex`).",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "GetAccountRateLimitsResponse" });
+
+export type V2GetAccountResponse = {
+  readonly account?: V2GetAccountResponse__Account | null;
+  readonly requiresOpenaiAuth: boolean;
+};
+export const V2GetAccountResponse = Schema.Struct({
+  account: Schema.optionalKey(Schema.Union([V2GetAccountResponse__Account, Schema.Null])),
+  requiresOpenaiAuth: Schema.Boolean,
+}).annotate({ title: "GetAccountResponse" });
+
+export type V2GuardianWarningNotification = { readonly message: string; readonly threadId: string };
+export const V2GuardianWarningNotification = Schema.Struct({
+  message: Schema.String.annotate({
+    description: "Concise guardian warning message for the user.",
+  }),
+  threadId: Schema.String.annotate({ description: "Thread target for the guardian warning." }),
+}).annotate({ title: "GuardianWarningNotification" });
+
+export type V2HookCompletedNotification = {
+  readonly run: V2HookCompletedNotification__HookRunSummary;
+  readonly threadId: string;
+  readonly turnId?: string | null;
+};
+export const V2HookCompletedNotification = Schema.Struct({
+  run: V2HookCompletedNotification__HookRunSummary,
+  threadId: Schema.String,
+  turnId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "HookCompletedNotification" });
+
+export type V2HookCompletedNotification__HookSource =
+  | "system"
+  | "user"
+  | "project"
+  | "mdm"
+  | "sessionFlags"
+  | "plugin"
+  | "cloudRequirements"
+  | "legacyManagedConfigFile"
+  | "legacyManagedConfigMdm"
+  | "unknown";
+export const V2HookCompletedNotification__HookSource = Schema.Literals([
+  "system",
+  "user",
+  "project",
+  "mdm",
+  "sessionFlags",
+  "plugin",
+  "cloudRequirements",
+  "legacyManagedConfigFile",
+  "legacyManagedConfigMdm",
+  "unknown",
+]);
+
+export type V2HooksListParams = { readonly cwds?: ReadonlyArray<string> };
+export const V2HooksListParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      description: "When empty, defaults to the current session working directory.",
+    }),
+  ),
+}).annotate({ title: "HooksListParams" });
+
+export type V2HooksListResponse = {
+  readonly data: ReadonlyArray<V2HooksListResponse__HooksListEntry>;
+};
+export const V2HooksListResponse = Schema.Struct({
+  data: Schema.Array(V2HooksListResponse__HooksListEntry),
+}).annotate({ title: "HooksListResponse" });
+
+export type V2HookStartedNotification = {
+  readonly run: V2HookStartedNotification__HookRunSummary;
+  readonly threadId: string;
+  readonly turnId?: string | null;
+};
+export const V2HookStartedNotification = Schema.Struct({
+  run: V2HookStartedNotification__HookRunSummary,
+  threadId: Schema.String,
+  turnId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "HookStartedNotification" });
+
+export type V2HookStartedNotification__HookSource =
+  | "system"
+  | "user"
+  | "project"
+  | "mdm"
+  | "sessionFlags"
+  | "plugin"
+  | "cloudRequirements"
+  | "legacyManagedConfigFile"
+  | "legacyManagedConfigMdm"
+  | "unknown";
+export const V2HookStartedNotification__HookSource = Schema.Literals([
+  "system",
+  "user",
+  "project",
+  "mdm",
+  "sessionFlags",
+  "plugin",
+  "cloudRequirements",
+  "legacyManagedConfigFile",
+  "legacyManagedConfigMdm",
+  "unknown",
+]);
+
+export type V2ItemCompletedNotification = {
+  readonly completedAtMs: number;
+  readonly item: V2ItemCompletedNotification__ThreadItem;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2ItemCompletedNotification = Schema.Struct({
+  completedAtMs: Schema.Number.annotate({
+    description: "Unix timestamp (in milliseconds) when this item lifecycle completed.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  item: V2ItemCompletedNotification__ThreadItem,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "ItemCompletedNotification" });
+
+export type V2ItemCompletedNotification__ByteRange = {
+  readonly end: number;
+  readonly start: number;
+};
+export const V2ItemCompletedNotification__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ItemCompletedNotification__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ItemCompletedNotification__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ItemCompletedNotification__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ItemCompletedNotification__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ItemCompletedNotification__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ItemCompletedNotification__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ItemGuardianApprovalReviewCompletedNotification = {
+  readonly action: V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewAction;
+  readonly decisionSource: V2ItemGuardianApprovalReviewCompletedNotification__AutoReviewDecisionSource;
+  readonly review: V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReview;
+  readonly reviewId: string;
+  readonly targetItemId?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2ItemGuardianApprovalReviewCompletedNotification = Schema.Struct({
+  action: V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReviewAction,
+  decisionSource: V2ItemGuardianApprovalReviewCompletedNotification__AutoReviewDecisionSource,
+  review: V2ItemGuardianApprovalReviewCompletedNotification__GuardianApprovalReview,
+  reviewId: Schema.String.annotate({ description: "Stable identifier for this review." }),
+  targetItemId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Identifier for the reviewed item or tool call when one exists.\n\nIn most cases, one review maps to one target item. The exceptions are - execve reviews, where a single command may contain multiple execve calls to review (only possible when using the shell_zsh_fork feature) - network policy reviews, where there is no target item\n\nA network call is triggered by a CommandExecution item, so having a target_item_id set to the CommandExecution item would be misleading because the review is about the network call, not the command execution. Therefore, target_item_id is set to None for network policy reviews.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  title: "ItemGuardianApprovalReviewCompletedNotification",
+  description:
+    "[UNSTABLE] Temporary notification payload for approval auto-review. This shape is expected to change soon.",
+});
+
+export type V2ItemGuardianApprovalReviewStartedNotification = {
+  readonly action: V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewAction;
+  readonly review: V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReview;
+  readonly reviewId: string;
+  readonly targetItemId?: string | null;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2ItemGuardianApprovalReviewStartedNotification = Schema.Struct({
+  action: V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReviewAction,
+  review: V2ItemGuardianApprovalReviewStartedNotification__GuardianApprovalReview,
+  reviewId: Schema.String.annotate({ description: "Stable identifier for this review." }),
+  targetItemId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Identifier for the reviewed item or tool call when one exists.\n\nIn most cases, one review maps to one target item. The exceptions are - execve reviews, where a single command may contain multiple execve calls to review (only possible when using the shell_zsh_fork feature) - network policy reviews, where there is no target item\n\nA network call is triggered by a CommandExecution item, so having a target_item_id set to the CommandExecution item would be misleading because the review is about the network call, not the command execution. Therefore, target_item_id is set to None for network policy reviews.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  title: "ItemGuardianApprovalReviewStartedNotification",
+  description:
+    "[UNSTABLE] Temporary notification payload for approval auto-review. This shape is expected to change soon.",
+});
+
+export type V2ItemStartedNotification = {
+  readonly item: V2ItemStartedNotification__ThreadItem;
+  readonly startedAtMs: number;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2ItemStartedNotification = Schema.Struct({
+  item: V2ItemStartedNotification__ThreadItem,
+  startedAtMs: Schema.Number.annotate({
+    description: "Unix timestamp (in milliseconds) when this item lifecycle started.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "ItemStartedNotification" });
+
+export type V2ItemStartedNotification__ByteRange = { readonly end: number; readonly start: number };
+export const V2ItemStartedNotification__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ItemStartedNotification__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ItemStartedNotification__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ItemStartedNotification__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ItemStartedNotification__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ItemStartedNotification__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ItemStartedNotification__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ListMcpServerStatusParams = {
+  readonly cursor?: string | null;
+  readonly detail?: V2ListMcpServerStatusParams__McpServerStatusDetail | null;
+  readonly limit?: number | null;
+};
+export const V2ListMcpServerStatusParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  detail: Schema.optionalKey(
+    Schema.Union([V2ListMcpServerStatusParams__McpServerStatusDetail, Schema.Null]).annotate({
+      description:
+        "Controls how much MCP inventory data to fetch for each server. Defaults to `Full` when omitted.",
+    }),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a server-defined value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ListMcpServerStatusParams" });
+
+export type V2ListMcpServerStatusResponse = {
+  readonly data: ReadonlyArray<V2ListMcpServerStatusResponse__McpServerStatus>;
+  readonly nextCursor?: string | null;
+};
+export const V2ListMcpServerStatusResponse = Schema.Struct({
+  data: Schema.Array(V2ListMcpServerStatusResponse__McpServerStatus),
+  nextCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor to pass to the next call to continue after the last item. If None, there are no more items to return.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ListMcpServerStatusResponse" });
+
+export type V2LoginAccountParams =
+  | { readonly apiKey: string; readonly type: "apiKey" }
+  | { readonly codexStreamlinedLogin?: boolean; readonly type: "chatgpt" }
+  | { readonly type: "chatgptDeviceCode" }
+  | {
+      readonly accessToken: string;
+      readonly chatgptAccountId: string;
+      readonly chatgptPlanType?: string | null;
+      readonly type: "chatgptAuthTokens";
+    };
+export const V2LoginAccountParams = Schema.Union(
+  [
+    Schema.Struct({
+      apiKey: Schema.String,
+      type: Schema.Literal("apiKey").annotate({ title: "ApiKeyv2::LoginAccountParamsType" }),
+    }).annotate({ title: "ApiKeyv2::LoginAccountParams" }),
+    Schema.Struct({
+      codexStreamlinedLogin: Schema.optionalKey(Schema.Boolean),
+      type: Schema.Literal("chatgpt").annotate({ title: "Chatgptv2::LoginAccountParamsType" }),
+    }).annotate({ title: "Chatgptv2::LoginAccountParams" }),
+    Schema.Struct({
+      type: Schema.Literal("chatgptDeviceCode").annotate({
+        title: "ChatgptDeviceCodev2::LoginAccountParamsType",
+      }),
+    }).annotate({ title: "ChatgptDeviceCodev2::LoginAccountParams" }),
+    Schema.Struct({
+      accessToken: Schema.String.annotate({
+        description:
+          "Access token (JWT) supplied by the client. This token is used for backend API requests and email extraction.",
+      }),
+      chatgptAccountId: Schema.String.annotate({
+        description: "Workspace/account identifier supplied by the client.",
+      }),
+      chatgptPlanType: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description:
+              "Optional plan type supplied by the client.\n\nWhen `null`, Codex attempts to derive the plan type from access-token claims. If unavailable, the plan defaults to `unknown`.",
+          }),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("chatgptAuthTokens").annotate({
+        title: "ChatgptAuthTokensv2::LoginAccountParamsType",
+      }),
+    }).annotate({
+      title: "ChatgptAuthTokensv2::LoginAccountParams",
+      description:
+        "[UNSTABLE] FOR OPENAI INTERNAL USE ONLY - DO NOT USE. The access token must contain the same scopes that Codex-managed ChatGPT auth tokens have.",
+    }),
+  ],
+  { mode: "oneOf" },
+).annotate({ title: "LoginAccountParams" });
+
+export type V2LoginAccountResponse =
+  | { readonly type: "apiKey" }
+  | { readonly authUrl: string; readonly loginId: string; readonly type: "chatgpt" }
+  | {
+      readonly loginId: string;
+      readonly type: "chatgptDeviceCode";
+      readonly userCode: string;
+      readonly verificationUrl: string;
+    }
+  | { readonly type: "chatgptAuthTokens" };
+export const V2LoginAccountResponse = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("apiKey").annotate({ title: "ApiKeyv2::LoginAccountResponseType" }),
+    }).annotate({ title: "ApiKeyv2::LoginAccountResponse" }),
+    Schema.Struct({
+      authUrl: Schema.String.annotate({
+        description: "URL the client should open in a browser to initiate the OAuth flow.",
+      }),
+      loginId: Schema.String,
+      type: Schema.Literal("chatgpt").annotate({ title: "Chatgptv2::LoginAccountResponseType" }),
+    }).annotate({ title: "Chatgptv2::LoginAccountResponse" }),
+    Schema.Struct({
+      loginId: Schema.String,
+      type: Schema.Literal("chatgptDeviceCode").annotate({
+        title: "ChatgptDeviceCodev2::LoginAccountResponseType",
+      }),
+      userCode: Schema.String.annotate({
+        description: "One-time code the user must enter after signing in.",
+      }),
+      verificationUrl: Schema.String.annotate({
+        description:
+          "URL the client should open in a browser to complete device code authorization.",
+      }),
+    }).annotate({ title: "ChatgptDeviceCodev2::LoginAccountResponse" }),
+    Schema.Struct({
+      type: Schema.Literal("chatgptAuthTokens").annotate({
+        title: "ChatgptAuthTokensv2::LoginAccountResponseType",
+      }),
+    }).annotate({ title: "ChatgptAuthTokensv2::LoginAccountResponse" }),
+  ],
+  { mode: "oneOf" },
+).annotate({ title: "LoginAccountResponse" });
+
+export type V2LogoutAccountResponse = {};
+export const V2LogoutAccountResponse = Schema.Struct({}).annotate({
+  title: "LogoutAccountResponse",
+});
+
+export type V2MarketplaceAddParams = {
+  readonly refName?: string | null;
+  readonly source: string;
+  readonly sparsePaths?: ReadonlyArray<string> | null;
+};
+export const V2MarketplaceAddParams = Schema.Struct({
+  refName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  source: Schema.String,
+  sparsePaths: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+}).annotate({ title: "MarketplaceAddParams" });
+
+export type V2MarketplaceAddResponse = {
+  readonly alreadyAdded: boolean;
+  readonly installedRoot: V2MarketplaceAddResponse__AbsolutePathBuf;
+  readonly marketplaceName: string;
+};
+export const V2MarketplaceAddResponse = Schema.Struct({
+  alreadyAdded: Schema.Boolean,
+  installedRoot: V2MarketplaceAddResponse__AbsolutePathBuf,
+  marketplaceName: Schema.String,
+}).annotate({ title: "MarketplaceAddResponse" });
+
+export type V2MarketplaceRemoveParams = { readonly marketplaceName: string };
+export const V2MarketplaceRemoveParams = Schema.Struct({ marketplaceName: Schema.String }).annotate(
+  { title: "MarketplaceRemoveParams" },
+);
+
+export type V2MarketplaceRemoveResponse = {
+  readonly installedRoot?: V2MarketplaceRemoveResponse__AbsolutePathBuf | null;
+  readonly marketplaceName: string;
+};
+export const V2MarketplaceRemoveResponse = Schema.Struct({
+  installedRoot: Schema.optionalKey(
+    Schema.Union([V2MarketplaceRemoveResponse__AbsolutePathBuf, Schema.Null]),
+  ),
+  marketplaceName: Schema.String,
+}).annotate({ title: "MarketplaceRemoveResponse" });
+
+export type V2MarketplaceUpgradeParams = { readonly marketplaceName?: string | null };
+export const V2MarketplaceUpgradeParams = Schema.Struct({
+  marketplaceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "MarketplaceUpgradeParams" });
+
+export type V2MarketplaceUpgradeResponse = {
+  readonly errors: ReadonlyArray<V2MarketplaceUpgradeResponse__MarketplaceUpgradeErrorInfo>;
+  readonly selectedMarketplaces: ReadonlyArray<string>;
+  readonly upgradedRoots: ReadonlyArray<V2MarketplaceUpgradeResponse__AbsolutePathBuf>;
+};
+export const V2MarketplaceUpgradeResponse = Schema.Struct({
+  errors: Schema.Array(V2MarketplaceUpgradeResponse__MarketplaceUpgradeErrorInfo),
+  selectedMarketplaces: Schema.Array(Schema.String),
+  upgradedRoots: Schema.Array(V2MarketplaceUpgradeResponse__AbsolutePathBuf),
+}).annotate({ title: "MarketplaceUpgradeResponse" });
+
+export type V2McpResourceReadParams = {
+  readonly server: string;
+  readonly threadId?: string | null;
+  readonly uri: string;
+};
+export const V2McpResourceReadParams = Schema.Struct({
+  server: Schema.String,
+  threadId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  uri: Schema.String,
+}).annotate({ title: "McpResourceReadParams" });
+
+export type V2McpResourceReadResponse = {
+  readonly contents: ReadonlyArray<V2McpResourceReadResponse__ResourceContent>;
+};
+export const V2McpResourceReadResponse = Schema.Struct({
+  contents: Schema.Array(V2McpResourceReadResponse__ResourceContent),
+}).annotate({ title: "McpResourceReadResponse" });
+
+export type V2McpServerOauthLoginCompletedNotification = {
+  readonly error?: string | null;
+  readonly name: string;
+  readonly success: boolean;
+};
+export const V2McpServerOauthLoginCompletedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  success: Schema.Boolean,
+}).annotate({ title: "McpServerOauthLoginCompletedNotification" });
+
+export type V2McpServerOauthLoginParams = {
+  readonly name: string;
+  readonly scopes?: ReadonlyArray<string> | null;
+  readonly timeoutSecs?: number | null;
+};
+export const V2McpServerOauthLoginParams = Schema.Struct({
+  name: Schema.String,
+  scopes: Schema.optionalKey(Schema.Union([Schema.Array(Schema.String), Schema.Null])),
+  timeoutSecs: Schema.optionalKey(
+    Schema.Union([Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()), Schema.Null]),
+  ),
+}).annotate({ title: "McpServerOauthLoginParams" });
+
+export type V2McpServerOauthLoginResponse = { readonly authorizationUrl: string };
+export const V2McpServerOauthLoginResponse = Schema.Struct({
+  authorizationUrl: Schema.String,
+}).annotate({ title: "McpServerOauthLoginResponse" });
+
+export type V2McpServerRefreshResponse = {};
+export const V2McpServerRefreshResponse = Schema.Struct({}).annotate({
+  title: "McpServerRefreshResponse",
+});
+
+export type V2McpServerStatusUpdatedNotification = {
+  readonly error?: string | null;
+  readonly name: string;
+  readonly status: V2McpServerStatusUpdatedNotification__McpServerStartupState;
+};
+export const V2McpServerStatusUpdatedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  name: Schema.String,
+  status: V2McpServerStatusUpdatedNotification__McpServerStartupState,
+}).annotate({ title: "McpServerStatusUpdatedNotification" });
+
+export type V2McpServerToolCallParams = {
+  readonly _meta?: unknown;
+  readonly arguments?: unknown;
+  readonly server: string;
+  readonly threadId: string;
+  readonly tool: string;
+};
+export const V2McpServerToolCallParams = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  arguments: Schema.optionalKey(Schema.Unknown),
+  server: Schema.String,
+  threadId: Schema.String,
+  tool: Schema.String,
+}).annotate({ title: "McpServerToolCallParams" });
+
+export type V2McpServerToolCallResponse = {
+  readonly _meta?: unknown;
+  readonly content: ReadonlyArray<unknown>;
+  readonly isError?: boolean | null;
+  readonly structuredContent?: unknown;
+};
+export const V2McpServerToolCallResponse = Schema.Struct({
+  _meta: Schema.optionalKey(Schema.Unknown),
+  content: Schema.Array(Schema.Unknown),
+  isError: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  structuredContent: Schema.optionalKey(Schema.Unknown),
+}).annotate({ title: "McpServerToolCallResponse" });
+
+export type V2McpToolCallProgressNotification = {
+  readonly itemId: string;
+  readonly message: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2McpToolCallProgressNotification = Schema.Struct({
+  itemId: Schema.String,
+  message: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "McpToolCallProgressNotification" });
+
+export type V2ModelListParams = {
+  readonly cursor?: string | null;
+  readonly includeHidden?: boolean | null;
+  readonly limit?: number | null;
+};
+export const V2ModelListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  includeHidden: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description: "When true, include models that are hidden from the default picker list.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ModelListParams" });
+
+export type V2ModelListResponse = {
+  readonly data: ReadonlyArray<V2ModelListResponse__Model>;
+  readonly nextCursor?: string | null;
+};
+export const V2ModelListResponse = Schema.Struct({
+  data: Schema.Array(V2ModelListResponse__Model),
+  nextCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor to pass to the next call to continue after the last item. If None, there are no more items to return.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ModelListResponse" });
+
+export type V2ModelProviderCapabilitiesReadParams = {};
+export const V2ModelProviderCapabilitiesReadParams = Schema.Struct({}).annotate({
+  title: "ModelProviderCapabilitiesReadParams",
+});
+
+export type V2ModelProviderCapabilitiesReadResponse = {
+  readonly imageGeneration: boolean;
+  readonly namespaceTools: boolean;
+  readonly webSearch: boolean;
+};
+export const V2ModelProviderCapabilitiesReadResponse = Schema.Struct({
+  imageGeneration: Schema.Boolean,
+  namespaceTools: Schema.Boolean,
+  webSearch: Schema.Boolean,
+}).annotate({ title: "ModelProviderCapabilitiesReadResponse" });
+
+export type V2ModelReroutedNotification = {
+  readonly fromModel: string;
+  readonly reason: V2ModelReroutedNotification__ModelRerouteReason;
+  readonly threadId: string;
+  readonly toModel: string;
+  readonly turnId: string;
+};
+export const V2ModelReroutedNotification = Schema.Struct({
+  fromModel: Schema.String,
+  reason: V2ModelReroutedNotification__ModelRerouteReason,
+  threadId: Schema.String,
+  toModel: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "ModelReroutedNotification" });
+
+export type V2ModelVerificationNotification = {
+  readonly threadId: string;
+  readonly turnId: string;
+  readonly verifications: ReadonlyArray<V2ModelVerificationNotification__ModelVerification>;
+};
+export const V2ModelVerificationNotification = Schema.Struct({
+  threadId: Schema.String,
+  turnId: Schema.String,
+  verifications: Schema.Array(V2ModelVerificationNotification__ModelVerification),
+}).annotate({ title: "ModelVerificationNotification" });
+
+export type V2PlanDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2PlanDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  title: "PlanDeltaNotification",
+  description:
+    "EXPERIMENTAL - proposed plan streaming deltas for plan items. Clients should not assume concatenated deltas match the completed plan item content.",
+});
+
+export type V2PluginInstallParams = {
+  readonly marketplacePath?: V2PluginInstallParams__AbsolutePathBuf | null;
+  readonly pluginName: string;
+  readonly remoteMarketplaceName?: string | null;
+};
+export const V2PluginInstallParams = Schema.Struct({
+  marketplacePath: Schema.optionalKey(
+    Schema.Union([V2PluginInstallParams__AbsolutePathBuf, Schema.Null]),
+  ),
+  pluginName: Schema.String,
+  remoteMarketplaceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "PluginInstallParams" });
+
+export type V2PluginInstallResponse = {
+  readonly appsNeedingAuth: ReadonlyArray<V2PluginInstallResponse__AppSummary>;
+  readonly authPolicy: V2PluginInstallResponse__PluginAuthPolicy;
+};
+export const V2PluginInstallResponse = Schema.Struct({
+  appsNeedingAuth: Schema.Array(V2PluginInstallResponse__AppSummary),
+  authPolicy: V2PluginInstallResponse__PluginAuthPolicy,
+}).annotate({ title: "PluginInstallResponse" });
+
+export type V2PluginListParams = {
+  readonly cwds?: ReadonlyArray<V2PluginListParams__AbsolutePathBuf> | null;
+  readonly marketplaceKinds?: ReadonlyArray<V2PluginListParams__PluginListMarketplaceKind> | null;
+};
+export const V2PluginListParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(V2PluginListParams__AbsolutePathBuf).annotate({
+        description:
+          "Optional working directories used to discover repo marketplaces. When omitted, only home-scoped marketplaces and the official curated marketplace are considered.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  marketplaceKinds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(V2PluginListParams__PluginListMarketplaceKind).annotate({
+        description:
+          "Optional marketplace kind filter. When omitted, only local marketplaces are queried, plus the default remote catalog when enabled by feature flag.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "PluginListParams" });
+
+export type V2PluginListResponse = {
+  readonly featuredPluginIds?: ReadonlyArray<string>;
+  readonly marketplaceLoadErrors?: ReadonlyArray<V2PluginListResponse__MarketplaceLoadErrorInfo>;
+  readonly marketplaces: ReadonlyArray<V2PluginListResponse__PluginMarketplaceEntry>;
+};
+export const V2PluginListResponse = Schema.Struct({
+  featuredPluginIds: Schema.optionalKey(Schema.Array(Schema.String).annotate({ default: [] })),
+  marketplaceLoadErrors: Schema.optionalKey(
+    Schema.Array(V2PluginListResponse__MarketplaceLoadErrorInfo).annotate({ default: [] }),
+  ),
+  marketplaces: Schema.Array(V2PluginListResponse__PluginMarketplaceEntry),
+}).annotate({ title: "PluginListResponse" });
+
+export type V2PluginListResponse__PluginAvailability = "DISABLED_BY_ADMIN" | "AVAILABLE";
+export const V2PluginListResponse__PluginAvailability = Schema.Literals([
+  "DISABLED_BY_ADMIN",
+  "AVAILABLE",
+]);
+
+export type V2PluginReadParams = {
+  readonly marketplacePath?: V2PluginReadParams__AbsolutePathBuf | null;
+  readonly pluginName: string;
+  readonly remoteMarketplaceName?: string | null;
+};
+export const V2PluginReadParams = Schema.Struct({
+  marketplacePath: Schema.optionalKey(
+    Schema.Union([V2PluginReadParams__AbsolutePathBuf, Schema.Null]),
+  ),
+  pluginName: Schema.String,
+  remoteMarketplaceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "PluginReadParams" });
+
+export type V2PluginReadResponse = { readonly plugin: V2PluginReadResponse__PluginDetail };
+export const V2PluginReadResponse = Schema.Struct({
+  plugin: V2PluginReadResponse__PluginDetail,
+}).annotate({ title: "PluginReadResponse" });
+
+export type V2PluginReadResponse__PluginAvailability = "DISABLED_BY_ADMIN" | "AVAILABLE";
+export const V2PluginReadResponse__PluginAvailability = Schema.Literals([
+  "DISABLED_BY_ADMIN",
+  "AVAILABLE",
+]);
+
+export type V2PluginShareDeleteParams = { readonly remotePluginId: string };
+export const V2PluginShareDeleteParams = Schema.Struct({ remotePluginId: Schema.String }).annotate({
+  title: "PluginShareDeleteParams",
+});
+
+export type V2PluginShareDeleteResponse = {};
+export const V2PluginShareDeleteResponse = Schema.Struct({}).annotate({
+  title: "PluginShareDeleteResponse",
+});
+
+export type V2PluginShareListParams = {};
+export const V2PluginShareListParams = Schema.Struct({}).annotate({
+  title: "PluginShareListParams",
+});
+
+export type V2PluginShareListResponse = {
+  readonly data: ReadonlyArray<V2PluginShareListResponse__PluginShareListItem>;
+};
+export const V2PluginShareListResponse = Schema.Struct({
+  data: Schema.Array(V2PluginShareListResponse__PluginShareListItem),
+}).annotate({ title: "PluginShareListResponse" });
+
+export type V2PluginShareListResponse__PluginAvailability = "DISABLED_BY_ADMIN" | "AVAILABLE";
+export const V2PluginShareListResponse__PluginAvailability = Schema.Literals([
+  "DISABLED_BY_ADMIN",
+  "AVAILABLE",
+]);
+
+export type V2PluginShareSaveParams = {
+  readonly discoverability?: V2PluginShareSaveParams__PluginShareDiscoverability | null;
+  readonly pluginPath: V2PluginShareSaveParams__AbsolutePathBuf;
+  readonly remotePluginId?: string | null;
+  readonly shareTargets?: ReadonlyArray<V2PluginShareSaveParams__PluginShareTarget> | null;
+};
+export const V2PluginShareSaveParams = Schema.Struct({
+  discoverability: Schema.optionalKey(
+    Schema.Union([V2PluginShareSaveParams__PluginShareDiscoverability, Schema.Null]),
+  ),
+  pluginPath: V2PluginShareSaveParams__AbsolutePathBuf,
+  remotePluginId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  shareTargets: Schema.optionalKey(
+    Schema.Union([Schema.Array(V2PluginShareSaveParams__PluginShareTarget), Schema.Null]),
+  ),
+}).annotate({ title: "PluginShareSaveParams" });
+
+export type V2PluginShareSaveResponse = {
+  readonly remotePluginId: string;
+  readonly shareUrl: string;
+};
+export const V2PluginShareSaveResponse = Schema.Struct({
+  remotePluginId: Schema.String,
+  shareUrl: Schema.String,
+}).annotate({ title: "PluginShareSaveResponse" });
+
+export type V2PluginShareUpdateTargetsParams = {
+  readonly remotePluginId: string;
+  readonly shareTargets: ReadonlyArray<V2PluginShareUpdateTargetsParams__PluginShareTarget>;
+};
+export const V2PluginShareUpdateTargetsParams = Schema.Struct({
+  remotePluginId: Schema.String,
+  shareTargets: Schema.Array(V2PluginShareUpdateTargetsParams__PluginShareTarget),
+}).annotate({ title: "PluginShareUpdateTargetsParams" });
+
+export type V2PluginShareUpdateTargetsResponse = {
+  readonly principals: ReadonlyArray<V2PluginShareUpdateTargetsResponse__PluginSharePrincipal>;
+};
+export const V2PluginShareUpdateTargetsResponse = Schema.Struct({
+  principals: Schema.Array(V2PluginShareUpdateTargetsResponse__PluginSharePrincipal),
+}).annotate({ title: "PluginShareUpdateTargetsResponse" });
+
+export type V2PluginSkillReadParams = {
+  readonly remoteMarketplaceName: string;
+  readonly remotePluginId: string;
+  readonly skillName: string;
+};
+export const V2PluginSkillReadParams = Schema.Struct({
+  remoteMarketplaceName: Schema.String,
+  remotePluginId: Schema.String,
+  skillName: Schema.String,
+}).annotate({ title: "PluginSkillReadParams" });
+
+export type V2PluginSkillReadResponse = { readonly contents?: string | null };
+export const V2PluginSkillReadResponse = Schema.Struct({
+  contents: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "PluginSkillReadResponse" });
+
+export type V2PluginUninstallParams = { readonly pluginId: string };
+export const V2PluginUninstallParams = Schema.Struct({ pluginId: Schema.String }).annotate({
+  title: "PluginUninstallParams",
+});
+
+export type V2PluginUninstallResponse = {};
+export const V2PluginUninstallResponse = Schema.Struct({}).annotate({
+  title: "PluginUninstallResponse",
+});
+
+export type V2ProcessExitedNotification = {
+  readonly exitCode: number;
+  readonly processHandle: string;
+  readonly stderr: string;
+  readonly stderrCapReached: boolean;
+  readonly stdout: string;
+  readonly stdoutCapReached: boolean;
+};
+export const V2ProcessExitedNotification = Schema.Struct({
+  exitCode: Schema.Number.annotate({ description: "Process exit code.", format: "int32" }).check(
+    Schema.isInt(),
+  ),
+  processHandle: Schema.String.annotate({
+    description: "Client-supplied, connection-scoped `processHandle` from `process/spawn`.",
+  }),
+  stderr: Schema.String.annotate({
+    description:
+      "Buffered stderr capture.\n\nEmpty when stderr was streamed via `process/outputDelta`.",
+  }),
+  stderrCapReached: Schema.Boolean.annotate({
+    description:
+      "Whether stderr reached `outputBytesCap`.\n\nIn streaming mode, stderr is empty and cap state is also reported on the final stderr `process/outputDelta` notification.",
+  }),
+  stdout: Schema.String.annotate({
+    description:
+      "Buffered stdout capture.\n\nEmpty when stdout was streamed via `process/outputDelta`.",
+  }),
+  stdoutCapReached: Schema.Boolean.annotate({
+    description:
+      "Whether stdout reached `outputBytesCap`.\n\nIn streaming mode, stdout is empty and cap state is also reported on the final stdout `process/outputDelta` notification.",
+  }),
+}).annotate({
+  title: "ProcessExitedNotification",
+  description: "Final process exit notification for `process/spawn`.",
+});
+
+export type V2ProcessOutputDeltaNotification = {
+  readonly capReached: boolean;
+  readonly deltaBase64: string;
+  readonly processHandle: string;
+  readonly stream: "stdout" | "stderr";
+};
+export const V2ProcessOutputDeltaNotification = Schema.Struct({
+  capReached: Schema.Boolean.annotate({
+    description:
+      "True on the final streamed chunk for this stream when output was truncated by `outputBytesCap`.",
+  }),
+  deltaBase64: Schema.String.annotate({ description: "Base64-encoded output bytes." }),
+  processHandle: Schema.String.annotate({
+    description: "Client-supplied, connection-scoped `processHandle` from `process/spawn`.",
+  }),
+  stream: Schema.Literals(["stdout", "stderr"]).annotate({
+    description: "Stream label for `process/outputDelta` notifications.",
+  }),
+}).annotate({
+  title: "ProcessOutputDeltaNotification",
+  description: "Base64-encoded output chunk emitted for a streaming `process/spawn` request.",
+});
+
+export type V2ProcessOutputDeltaNotification__ProcessOutputStream = "stdout" | "stderr";
+export const V2ProcessOutputDeltaNotification__ProcessOutputStream = Schema.Literals([
+  "stdout",
+  "stderr",
+]).annotate({ description: "Stream label for `process/outputDelta` notifications." });
+
+export type V2RawResponseItemCompletedNotification = {
+  readonly item: V2RawResponseItemCompletedNotification__ResponseItem;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2RawResponseItemCompletedNotification = Schema.Struct({
+  item: V2RawResponseItemCompletedNotification__ResponseItem,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "RawResponseItemCompletedNotification" });
+
+export type V2ReasoningSummaryPartAddedNotification = {
+  readonly itemId: string;
+  readonly summaryIndex: number;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2ReasoningSummaryPartAddedNotification = Schema.Struct({
+  itemId: Schema.String,
+  summaryIndex: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "ReasoningSummaryPartAddedNotification" });
+
+export type V2ReasoningSummaryTextDeltaNotification = {
+  readonly delta: string;
+  readonly itemId: string;
+  readonly summaryIndex: number;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2ReasoningSummaryTextDeltaNotification = Schema.Struct({
+  delta: Schema.String,
+  itemId: Schema.String,
+  summaryIndex: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "ReasoningSummaryTextDeltaNotification" });
+
+export type V2ReasoningTextDeltaNotification = {
+  readonly contentIndex: number;
+  readonly delta: string;
+  readonly itemId: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2ReasoningTextDeltaNotification = Schema.Struct({
+  contentIndex: Schema.Number.annotate({ format: "int64" }).check(Schema.isInt()),
+  delta: Schema.String,
+  itemId: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "ReasoningTextDeltaNotification" });
+
+export type V2RemoteControlStatusChangedNotification = {
+  readonly environmentId?: string | null;
+  readonly status: V2RemoteControlStatusChangedNotification__RemoteControlConnectionStatus;
+};
+export const V2RemoteControlStatusChangedNotification = Schema.Struct({
+  environmentId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  status: V2RemoteControlStatusChangedNotification__RemoteControlConnectionStatus,
+}).annotate({
+  title: "RemoteControlStatusChangedNotification",
+  description: "Current remote-control connection status and environment id exposed to clients.",
+});
+
+export type V2ReviewStartParams = {
+  readonly delivery?: V2ReviewStartParams__ReviewDelivery | null;
+  readonly target: V2ReviewStartParams__ReviewTarget;
+  readonly threadId: string;
+};
+export const V2ReviewStartParams = Schema.Struct({
+  delivery: Schema.optionalKey(
+    Schema.Union([V2ReviewStartParams__ReviewDelivery, Schema.Null]).annotate({
+      description:
+        "Where to run the review: inline (default) on the current thread or detached on a new thread (returned in `reviewThreadId`).",
+    }),
+  ),
+  target: V2ReviewStartParams__ReviewTarget,
+  threadId: Schema.String,
+}).annotate({ title: "ReviewStartParams" });
+
+export type V2ReviewStartResponse = {
+  readonly reviewThreadId: string;
+  readonly turn: V2ReviewStartResponse__Turn;
+};
+export const V2ReviewStartResponse = Schema.Struct({
+  reviewThreadId: Schema.String.annotate({
+    description:
+      "Identifies the thread where the review runs.\n\nFor inline reviews, this is the original thread id. For detached reviews, this is the id of the new review thread.",
+  }),
+  turn: V2ReviewStartResponse__Turn,
+}).annotate({ title: "ReviewStartResponse" });
+
+export type V2ReviewStartResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ReviewStartResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ReviewStartResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ReviewStartResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ReviewStartResponse__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ReviewStartResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ReviewStartResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ReviewStartResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ReviewStartResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ReviewStartResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2SendAddCreditsNudgeEmailParams = {
+  readonly creditType: V2SendAddCreditsNudgeEmailParams__AddCreditsNudgeCreditType;
+};
+export const V2SendAddCreditsNudgeEmailParams = Schema.Struct({
+  creditType: V2SendAddCreditsNudgeEmailParams__AddCreditsNudgeCreditType,
+}).annotate({ title: "SendAddCreditsNudgeEmailParams" });
+
+export type V2SendAddCreditsNudgeEmailResponse = {
+  readonly status: V2SendAddCreditsNudgeEmailResponse__AddCreditsNudgeEmailStatus;
+};
+export const V2SendAddCreditsNudgeEmailResponse = Schema.Struct({
+  status: V2SendAddCreditsNudgeEmailResponse__AddCreditsNudgeEmailStatus,
+}).annotate({ title: "SendAddCreditsNudgeEmailResponse" });
+
+export type V2ServerRequestResolvedNotification = {
+  readonly requestId: V2ServerRequestResolvedNotification__RequestId;
+  readonly threadId: string;
+};
+export const V2ServerRequestResolvedNotification = Schema.Struct({
+  requestId: V2ServerRequestResolvedNotification__RequestId,
+  threadId: Schema.String,
+}).annotate({ title: "ServerRequestResolvedNotification" });
+
+export type V2SkillsChangedNotification = {};
+export const V2SkillsChangedNotification = Schema.Struct({}).annotate({
+  title: "SkillsChangedNotification",
+  description:
+    "Notification emitted when watched local skill files change.\n\nTreat this as an invalidation signal and re-run `skills/list` with the client's current parameters when refreshed skill metadata is needed.",
+});
+
+export type V2SkillsConfigWriteParams = {
+  readonly enabled: boolean;
+  readonly name?: string | null;
+  readonly path?: V2SkillsConfigWriteParams__AbsolutePathBuf | null;
+};
+export const V2SkillsConfigWriteParams = Schema.Struct({
+  enabled: Schema.Boolean,
+  name: Schema.optionalKey(
+    Schema.Union([Schema.String.annotate({ description: "Name-based selector." }), Schema.Null]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([V2SkillsConfigWriteParams__AbsolutePathBuf, Schema.Null]).annotate({
+      description: "Path-based selector.",
+    }),
+  ),
+}).annotate({ title: "SkillsConfigWriteParams" });
+
+export type V2SkillsConfigWriteResponse = { readonly effectiveEnabled: boolean };
+export const V2SkillsConfigWriteResponse = Schema.Struct({
+  effectiveEnabled: Schema.Boolean,
+}).annotate({ title: "SkillsConfigWriteResponse" });
+
+export type V2SkillsListParams = {
+  readonly cwds?: ReadonlyArray<string>;
+  readonly forceReload?: boolean;
+  readonly perCwdExtraUserRoots?: ReadonlyArray<V2SkillsListParams__SkillsListExtraRootsForCwd> | null;
+};
+export const V2SkillsListParams = Schema.Struct({
+  cwds: Schema.optionalKey(
+    Schema.Array(Schema.String).annotate({
+      description: "When empty, defaults to the current session working directory.",
+    }),
+  ),
+  forceReload: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "When true, bypass the skills cache and re-scan skills from disk.",
+    }),
+  ),
+  perCwdExtraUserRoots: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(V2SkillsListParams__SkillsListExtraRootsForCwd).annotate({
+        description: "Optional per-cwd extra roots to scan as user-scoped skills.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "SkillsListParams" });
+
+export type V2SkillsListResponse = {
+  readonly data: ReadonlyArray<V2SkillsListResponse__SkillsListEntry>;
+};
+export const V2SkillsListResponse = Schema.Struct({
+  data: Schema.Array(V2SkillsListResponse__SkillsListEntry),
+}).annotate({ title: "SkillsListResponse" });
+
+export type V2TerminalInteractionNotification = {
+  readonly itemId: string;
+  readonly processId: string;
+  readonly stdin: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2TerminalInteractionNotification = Schema.Struct({
+  itemId: Schema.String,
+  processId: Schema.String,
+  stdin: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "TerminalInteractionNotification" });
+
+export type V2ThreadApproveGuardianDeniedActionParams = {
+  readonly event: unknown;
+  readonly threadId: string;
+};
+export const V2ThreadApproveGuardianDeniedActionParams = Schema.Struct({
+  event: Schema.Unknown.annotate({
+    description: "Serialized `codex_protocol::protocol::GuardianAssessmentEvent`.",
+  }),
+  threadId: Schema.String,
+}).annotate({ title: "ThreadApproveGuardianDeniedActionParams" });
+
+export type V2ThreadApproveGuardianDeniedActionResponse = {};
+export const V2ThreadApproveGuardianDeniedActionResponse = Schema.Struct({}).annotate({
+  title: "ThreadApproveGuardianDeniedActionResponse",
+});
+
+export type V2ThreadArchivedNotification = { readonly threadId: string };
+export const V2ThreadArchivedNotification = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadArchivedNotification",
+});
+
+export type V2ThreadArchiveParams = { readonly threadId: string };
+export const V2ThreadArchiveParams = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadArchiveParams",
+});
+
+export type V2ThreadArchiveResponse = {};
+export const V2ThreadArchiveResponse = Schema.Struct({}).annotate({
+  title: "ThreadArchiveResponse",
+});
+
+export type V2ThreadClosedNotification = { readonly threadId: string };
+export const V2ThreadClosedNotification = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadClosedNotification",
+});
+
+export type V2ThreadCompactStartParams = { readonly threadId: string };
+export const V2ThreadCompactStartParams = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadCompactStartParams",
+});
+
+export type V2ThreadCompactStartResponse = {};
+export const V2ThreadCompactStartResponse = Schema.Struct({}).annotate({
+  title: "ThreadCompactStartResponse",
+});
+
+export type V2ThreadForkParams = {
+  readonly approvalPolicy?: V2ThreadForkParams__AskForApproval | null;
+  readonly approvalsReviewer?: V2ThreadForkParams__ApprovalsReviewer | null;
+  readonly baseInstructions?: string | null;
+  readonly config?: { readonly [x: string]: unknown } | null;
+  readonly cwd?: string | null;
+  readonly developerInstructions?: string | null;
+  readonly ephemeral?: boolean;
+  readonly model?: string | null;
+  readonly modelProvider?: string | null;
+  readonly sandbox?: V2ThreadForkParams__SandboxMode | null;
+  readonly serviceTier?: string | null;
+  readonly threadId: string;
+  readonly threadSource?: V2ThreadForkParams__ThreadSource | null;
+};
+export const V2ThreadForkParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(
+    Schema.Union([V2ThreadForkParams__AskForApproval, Schema.Null]),
+  ),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([V2ThreadForkParams__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this thread and subsequent turns.",
+    }),
+  ),
+  baseInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  config: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.Unknown), Schema.Null]),
+  ),
+  cwd: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developerInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  ephemeral: Schema.optionalKey(Schema.Boolean),
+  model: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Configuration overrides for the forked thread, if any.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  modelProvider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sandbox: Schema.optionalKey(Schema.Union([V2ThreadForkParams__SandboxMode, Schema.Null])),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadForkParams__ThreadSource, Schema.Null]).annotate({
+      description:
+        "Optional client-supplied analytics source classification for this forked thread.",
+    }),
+  ),
+}).annotate({
+  title: "ThreadForkParams",
+  description:
+    "There are two ways to fork a thread: 1. By thread_id: load the thread from disk by thread_id and fork it into a new thread. 2. By path: load the thread from disk by path and fork it into a new thread.\n\nIf using path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+});
+
+export type V2ThreadForkParams__PermissionProfileSelectionParams = {
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<V2ThreadForkParams__PermissionProfileModificationParams> | null;
+  readonly type: "profile";
+};
+export const V2ThreadForkParams__PermissionProfileSelectionParams = Schema.Union(
+  [
+    Schema.Struct({
+      id: Schema.String,
+      modifications: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadForkParams__PermissionProfileModificationParams),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("profile").annotate({
+        title: "ProfilePermissionProfileSelectionParamsType",
+      }),
+    }).annotate({
+      title: "ProfilePermissionProfileSelectionParams",
+      description:
+        "Select a named built-in or user-defined profile and optionally apply bounded modifications that Codex knows how to validate.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse = {
+  readonly approvalPolicy: V2ThreadForkResponse__AskForApproval;
+  readonly approvalsReviewer: "user" | "auto_review" | "guardian_subagent";
+  readonly cwd: V2ThreadForkResponse__AbsolutePathBuf;
+  readonly instructionSources?: ReadonlyArray<V2ThreadForkResponse__AbsolutePathBuf>;
+  readonly model: string;
+  readonly modelProvider: string;
+  readonly reasoningEffort?: V2ThreadForkResponse__ReasoningEffort | null;
+  readonly sandbox:
+    | { readonly type: "dangerFullAccess" }
+    | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+    | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+    | {
+        readonly excludeSlashTmp?: boolean;
+        readonly excludeTmpdirEnvVar?: boolean;
+        readonly networkAccess?: boolean;
+        readonly type: "workspaceWrite";
+        readonly writableRoots?: ReadonlyArray<V2ThreadForkResponse__AbsolutePathBuf>;
+      };
+  readonly serviceTier?: string | null;
+  readonly thread: V2ThreadForkResponse__Thread;
+};
+export const V2ThreadForkResponse = Schema.Struct({
+  approvalPolicy: V2ThreadForkResponse__AskForApproval,
+  approvalsReviewer: Schema.Literals(["user", "auto_review", "guardian_subagent"]).annotate({
+    description:
+      "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+  }),
+  cwd: V2ThreadForkResponse__AbsolutePathBuf,
+  instructionSources: Schema.optionalKey(
+    Schema.Array(V2ThreadForkResponse__AbsolutePathBuf).annotate({
+      description: "Instruction source files currently loaded for this thread.",
+      default: [],
+    }),
+  ),
+  model: Schema.String,
+  modelProvider: Schema.String,
+  reasoningEffort: Schema.optionalKey(
+    Schema.Union([V2ThreadForkResponse__ReasoningEffort, Schema.Null]),
+  ),
+  sandbox: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("dangerFullAccess").annotate({
+          title: "DangerFullAccessSandboxPolicyType",
+        }),
+      }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+      Schema.Struct({
+        networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+      }).annotate({ title: "ReadOnlySandboxPolicy" }),
+      Schema.Struct({
+        networkAccess: Schema.optionalKey(
+          Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+        ),
+        type: Schema.Literal("externalSandbox").annotate({
+          title: "ExternalSandboxSandboxPolicyType",
+        }),
+      }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+      Schema.Struct({
+        excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        type: Schema.Literal("workspaceWrite").annotate({
+          title: "WorkspaceWriteSandboxPolicyType",
+        }),
+        writableRoots: Schema.optionalKey(
+          Schema.Array(V2ThreadForkResponse__AbsolutePathBuf).annotate({ default: [] }),
+        ),
+      }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description:
+      "Legacy sandbox policy retained for compatibility. Experimental clients should prefer `permissionProfile` when they need exact runtime permissions.",
+  }),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  thread: V2ThreadForkResponse__Thread,
+}).annotate({ title: "ThreadForkResponse" });
+
+export type V2ThreadForkResponse__ActivePermissionProfile = {
+  readonly extends?: string | null;
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<V2ThreadForkResponse__ActivePermissionProfileModification>;
+};
+export const V2ThreadForkResponse__ActivePermissionProfile = Schema.Struct({
+  extends: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Parent profile identifier once permissions profiles support inheritance. This is currently always `null`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  id: Schema.String.annotate({
+    description:
+      "Identifier from `default_permissions` or the implicit built-in default, such as `:workspace` or a user-defined `[permissions.<id>]` profile.",
+  }),
+  modifications: Schema.optionalKey(
+    Schema.Array(V2ThreadForkResponse__ActivePermissionProfileModification).annotate({
+      description:
+        "Bounded user-requested modifications applied on top of the named profile, if any.",
+      default: [],
+    }),
+  ),
+});
+
+export type V2ThreadForkResponse__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const V2ThreadForkResponse__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ThreadForkResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ThreadForkResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadForkResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadForkResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadForkResponse__CollabAgentToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadForkResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadForkResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadForkResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadForkResponse__NetworkAccess = "restricted" | "enabled";
+export const V2ThreadForkResponse__NetworkAccess = Schema.Literals(["restricted", "enabled"]);
+
+export type V2ThreadForkResponse__PermissionProfile =
+  | {
+      readonly fileSystem: V2ThreadForkResponse__PermissionProfileFileSystemPermissions;
+      readonly network: V2ThreadForkResponse__PermissionProfileNetworkPermissions;
+      readonly type: "managed";
+    }
+  | { readonly type: "disabled" }
+  | {
+      readonly network: V2ThreadForkResponse__PermissionProfileNetworkPermissions;
+      readonly type: "external";
+    };
+export const V2ThreadForkResponse__PermissionProfile = Schema.Union(
+  [
+    Schema.Struct({
+      fileSystem: V2ThreadForkResponse__PermissionProfileFileSystemPermissions,
+      network: V2ThreadForkResponse__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("managed").annotate({ title: "ManagedPermissionProfileType" }),
+    }).annotate({
+      title: "ManagedPermissionProfile",
+      description: "Codex owns sandbox construction for this profile.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("disabled").annotate({ title: "DisabledPermissionProfileType" }),
+    }).annotate({
+      title: "DisabledPermissionProfile",
+      description: "Do not apply an outer sandbox.",
+    }),
+    Schema.Struct({
+      network: V2ThreadForkResponse__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("external").annotate({ title: "ExternalPermissionProfileType" }),
+    }).annotate({
+      title: "ExternalPermissionProfile",
+      description: "Filesystem isolation is enforced by an external caller.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__SandboxPolicy =
+  | { readonly type: "dangerFullAccess" }
+  | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+  | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+  | {
+      readonly excludeSlashTmp?: boolean;
+      readonly excludeTmpdirEnvVar?: boolean;
+      readonly networkAccess?: boolean;
+      readonly type: "workspaceWrite";
+      readonly writableRoots?: ReadonlyArray<V2ThreadForkResponse__AbsolutePathBuf>;
+    };
+export const V2ThreadForkResponse__SandboxPolicy = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("dangerFullAccess").annotate({
+        title: "DangerFullAccessSandboxPolicyType",
+      }),
+    }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+    }).annotate({ title: "ReadOnlySandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(
+        Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+      ),
+      type: Schema.Literal("externalSandbox").annotate({
+        title: "ExternalSandboxSandboxPolicyType",
+      }),
+    }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+    Schema.Struct({
+      excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("workspaceWrite").annotate({ title: "WorkspaceWriteSandboxPolicyType" }),
+      writableRoots: Schema.optionalKey(
+        Schema.Array(V2ThreadForkResponse__AbsolutePathBuf).annotate({ default: [] }),
+      ),
+    }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadForkResponse__SubAgentSource };
+export const V2ThreadForkResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadForkResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadForkResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadForkResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadForkResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadForkResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadForkResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadGoalClearedNotification = { readonly threadId: string };
+export const V2ThreadGoalClearedNotification = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadGoalClearedNotification",
+});
+
+export type V2ThreadGoalUpdatedNotification = {
+  readonly goal: V2ThreadGoalUpdatedNotification__ThreadGoal;
+  readonly threadId: string;
+  readonly turnId?: string | null;
+};
+export const V2ThreadGoalUpdatedNotification = Schema.Struct({
+  goal: V2ThreadGoalUpdatedNotification__ThreadGoal,
+  threadId: Schema.String,
+  turnId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "ThreadGoalUpdatedNotification" });
+
+export type V2ThreadInjectItemsParams = {
+  readonly items: ReadonlyArray<unknown>;
+  readonly threadId: string;
+};
+export const V2ThreadInjectItemsParams = Schema.Struct({
+  items: Schema.Array(Schema.Unknown).annotate({
+    description: "Raw Responses API items to append to the thread's model-visible history.",
+  }),
+  threadId: Schema.String,
+}).annotate({ title: "ThreadInjectItemsParams" });
+
+export type V2ThreadInjectItemsResponse = {};
+export const V2ThreadInjectItemsResponse = Schema.Struct({}).annotate({
+  title: "ThreadInjectItemsResponse",
+});
+
+export type V2ThreadListParams = {
+  readonly archived?: boolean | null;
+  readonly cursor?: string | null;
+  readonly cwd?: V2ThreadListParams__ThreadListCwdFilter | null;
+  readonly limit?: number | null;
+  readonly modelProviders?: ReadonlyArray<string> | null;
+  readonly searchTerm?: string | null;
+  readonly sortDirection?: V2ThreadListParams__SortDirection | null;
+  readonly sortKey?: V2ThreadListParams__ThreadSortKey | null;
+  readonly sourceKinds?: ReadonlyArray<V2ThreadListParams__ThreadSourceKind> | null;
+  readonly useStateDbOnly?: boolean;
+};
+export const V2ThreadListParams = Schema.Struct({
+  archived: Schema.optionalKey(
+    Schema.Union([
+      Schema.Boolean.annotate({
+        description:
+          "Optional archived filter; when set to true, only archived threads are returned. If false or null, only non-archived threads are returned.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cwd: Schema.optionalKey(
+    Schema.Union([V2ThreadListParams__ThreadListCwdFilter, Schema.Null]).annotate({
+      description:
+        "Optional cwd filter or filters; when set, only threads whose session cwd exactly matches one of these paths are returned.",
+    }),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to a reasonable server-side value.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+  modelProviders: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(Schema.String).annotate({
+        description:
+          "Optional provider filter; when set, only sessions recorded under these providers are returned. When present but empty, includes all providers.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  searchTerm: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional substring filter for the extracted thread title.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  sortDirection: Schema.optionalKey(
+    Schema.Union([V2ThreadListParams__SortDirection, Schema.Null]).annotate({
+      description: "Optional sort direction; defaults to descending (newest first).",
+    }),
+  ),
+  sortKey: Schema.optionalKey(
+    Schema.Union([V2ThreadListParams__ThreadSortKey, Schema.Null]).annotate({
+      description: "Optional sort key; defaults to created_at.",
+    }),
+  ),
+  sourceKinds: Schema.optionalKey(
+    Schema.Union([
+      Schema.Array(V2ThreadListParams__ThreadSourceKind).annotate({
+        description:
+          "Optional source filter; when set, only sessions from these source kinds are returned. When omitted or empty, defaults to interactive sources.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  useStateDbOnly: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "If true, return from the state DB without scanning JSONL rollouts to repair thread metadata. Omitted or false preserves scan-and-repair behavior.",
+    }),
+  ),
+}).annotate({ title: "ThreadListParams" });
+
+export type V2ThreadListResponse = {
+  readonly backwardsCursor?: string | null;
+  readonly data: ReadonlyArray<V2ThreadListResponse__Thread>;
+  readonly nextCursor?: string | null;
+};
+export const V2ThreadListResponse = Schema.Struct({
+  backwardsCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor to pass as `cursor` when reversing `sortDirection`. This is only populated when the page contains at least one thread. Use it with the opposite `sortDirection`; for timestamp sorts it anchors at the start of the page timestamp so same-second updates are not skipped.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  data: Schema.Array(V2ThreadListResponse__Thread),
+  nextCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor to pass to the next call to continue after the last item. if None, there are no more items to return.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ThreadListResponse" });
+
+export type V2ThreadListResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ThreadListResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadListResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadListResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadListResponse__CollabAgentToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadListResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadListResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadListResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadListResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadListResponse__SubAgentSource };
+export const V2ThreadListResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadListResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadListResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadListResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadListResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadListResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadListResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadListResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadLoadedListParams = {
+  readonly cursor?: string | null;
+  readonly limit?: number | null;
+};
+export const V2ThreadLoadedListParams = Schema.Struct({
+  cursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Opaque pagination cursor returned by a previous call.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  limit: Schema.optionalKey(
+    Schema.Union([
+      Schema.Number.annotate({
+        description: "Optional page size; defaults to no limit.",
+        format: "uint32",
+      })
+        .check(Schema.isInt())
+        .check(Schema.isGreaterThanOrEqualTo(0)),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ThreadLoadedListParams" });
+
+export type V2ThreadLoadedListResponse = {
+  readonly data: ReadonlyArray<string>;
+  readonly nextCursor?: string | null;
+};
+export const V2ThreadLoadedListResponse = Schema.Struct({
+  data: Schema.Array(Schema.String).annotate({
+    description: "Thread ids for sessions currently loaded in memory.",
+  }),
+  nextCursor: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Opaque cursor to pass to the next call to continue after the last item. if None, there are no more items to return.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "ThreadLoadedListResponse" });
+
+export type V2ThreadMetadataUpdateParams = {
+  readonly gitInfo?: V2ThreadMetadataUpdateParams__ThreadMetadataGitInfoUpdateParams | null;
+  readonly threadId: string;
+};
+export const V2ThreadMetadataUpdateParams = Schema.Struct({
+  gitInfo: Schema.optionalKey(
+    Schema.Union([
+      V2ThreadMetadataUpdateParams__ThreadMetadataGitInfoUpdateParams,
+      Schema.Null,
+    ]).annotate({
+      description:
+        "Patch the stored Git metadata for this thread. Omit a field to leave it unchanged, set it to `null` to clear it, or provide a string to replace the stored value.",
+    }),
+  ),
+  threadId: Schema.String,
+}).annotate({ title: "ThreadMetadataUpdateParams" });
+
+export type V2ThreadMetadataUpdateResponse = {
+  readonly thread: V2ThreadMetadataUpdateResponse__Thread;
+};
+export const V2ThreadMetadataUpdateResponse = Schema.Struct({
+  thread: V2ThreadMetadataUpdateResponse__Thread,
+}).annotate({ title: "ThreadMetadataUpdateResponse" });
+
+export type V2ThreadMetadataUpdateResponse__ByteRange = {
+  readonly end: number;
+  readonly start: number;
+};
+export const V2ThreadMetadataUpdateResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadMetadataUpdateResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadMetadataUpdateResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadMetadataUpdateResponse__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadMetadataUpdateResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadMetadataUpdateResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadMetadataUpdateResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadMetadataUpdateResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadMetadataUpdateResponse__SubAgentSource };
+export const V2ThreadMetadataUpdateResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadMetadataUpdateResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadMetadataUpdateResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadMetadataUpdateResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadMetadataUpdateResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadMetadataUpdateResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadMetadataUpdateResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadNameUpdatedNotification = {
+  readonly threadId: string;
+  readonly threadName?: string | null;
+};
+export const V2ThreadNameUpdatedNotification = Schema.Struct({
+  threadId: Schema.String,
+  threadName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+}).annotate({ title: "ThreadNameUpdatedNotification" });
+
+export type V2ThreadReadParams = { readonly includeTurns?: boolean; readonly threadId: string };
+export const V2ThreadReadParams = Schema.Struct({
+  includeTurns: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description: "When true, include turns and their items from rollout history.",
+      default: false,
+    }),
+  ),
+  threadId: Schema.String,
+}).annotate({ title: "ThreadReadParams" });
+
+export type V2ThreadReadResponse = { readonly thread: V2ThreadReadResponse__Thread };
+export const V2ThreadReadResponse = Schema.Struct({
+  thread: V2ThreadReadResponse__Thread,
+}).annotate({ title: "ThreadReadResponse" });
+
+export type V2ThreadReadResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ThreadReadResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadReadResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadReadResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadReadResponse__CollabAgentToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2ThreadReadResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadReadResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadReadResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadReadResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadReadResponse__SubAgentSource };
+export const V2ThreadReadResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadReadResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadReadResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadReadResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadReadResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadReadResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadReadResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadRealtimeClosedNotification = {
+  readonly reason?: string | null;
+  readonly threadId: string;
+};
+export const V2ThreadRealtimeClosedNotification = Schema.Struct({
+  reason: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadRealtimeClosedNotification",
+  description: "EXPERIMENTAL - emitted when thread realtime transport closes.",
+});
+
+export type V2ThreadRealtimeErrorNotification = {
+  readonly message: string;
+  readonly threadId: string;
+};
+export const V2ThreadRealtimeErrorNotification = Schema.Struct({
+  message: Schema.String,
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadRealtimeErrorNotification",
+  description: "EXPERIMENTAL - emitted when thread realtime encounters an error.",
+});
+
+export type V2ThreadRealtimeItemAddedNotification = {
+  readonly item: unknown;
+  readonly threadId: string;
+};
+export const V2ThreadRealtimeItemAddedNotification = Schema.Struct({
+  item: Schema.Unknown,
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadRealtimeItemAddedNotification",
+  description: "EXPERIMENTAL - raw non-audio thread realtime item emitted by the backend.",
+});
+
+export type V2ThreadRealtimeOutputAudioDeltaNotification = {
+  readonly audio: V2ThreadRealtimeOutputAudioDeltaNotification__ThreadRealtimeAudioChunk;
+  readonly threadId: string;
+};
+export const V2ThreadRealtimeOutputAudioDeltaNotification = Schema.Struct({
+  audio: V2ThreadRealtimeOutputAudioDeltaNotification__ThreadRealtimeAudioChunk,
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadRealtimeOutputAudioDeltaNotification",
+  description: "EXPERIMENTAL - streamed output audio emitted by thread realtime.",
+});
+
+export type V2ThreadRealtimeSdpNotification = { readonly sdp: string; readonly threadId: string };
+export const V2ThreadRealtimeSdpNotification = Schema.Struct({
+  sdp: Schema.String,
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadRealtimeSdpNotification",
+  description: "EXPERIMENTAL - emitted with the remote SDP for a WebRTC realtime session.",
+});
+
+export type V2ThreadRealtimeStartedNotification = {
+  readonly realtimeSessionId?: string | null;
+  readonly threadId: string;
+  readonly version: V2ThreadRealtimeStartedNotification__RealtimeConversationVersion;
+};
+export const V2ThreadRealtimeStartedNotification = Schema.Struct({
+  realtimeSessionId: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+  version: V2ThreadRealtimeStartedNotification__RealtimeConversationVersion,
+}).annotate({
+  title: "ThreadRealtimeStartedNotification",
+  description: "EXPERIMENTAL - emitted when thread realtime startup is accepted.",
+});
+
+export type V2ThreadRealtimeTranscriptDeltaNotification = {
+  readonly delta: string;
+  readonly role: string;
+  readonly threadId: string;
+};
+export const V2ThreadRealtimeTranscriptDeltaNotification = Schema.Struct({
+  delta: Schema.String.annotate({ description: "Live transcript delta from the realtime event." }),
+  role: Schema.String,
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadRealtimeTranscriptDeltaNotification",
+  description:
+    "EXPERIMENTAL - flat transcript delta emitted whenever realtime transcript text changes.",
+});
+
+export type V2ThreadRealtimeTranscriptDoneNotification = {
+  readonly role: string;
+  readonly text: string;
+  readonly threadId: string;
+};
+export const V2ThreadRealtimeTranscriptDoneNotification = Schema.Struct({
+  role: Schema.String,
+  text: Schema.String.annotate({ description: "Final complete text for the transcript part." }),
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadRealtimeTranscriptDoneNotification",
+  description:
+    "EXPERIMENTAL - final transcript text emitted when realtime completes a transcript part.",
+});
+
+export type V2ThreadResumeParams = {
+  readonly approvalPolicy?: V2ThreadResumeParams__AskForApproval | null;
+  readonly approvalsReviewer?: V2ThreadResumeParams__ApprovalsReviewer | null;
+  readonly baseInstructions?: string | null;
+  readonly config?: { readonly [x: string]: unknown } | null;
+  readonly cwd?: string | null;
+  readonly developerInstructions?: string | null;
+  readonly model?: string | null;
+  readonly modelProvider?: string | null;
+  readonly personality?: V2ThreadResumeParams__Personality | null;
+  readonly sandbox?: V2ThreadResumeParams__SandboxMode | null;
+  readonly serviceTier?: string | null;
+  readonly threadId: string;
+};
+export const V2ThreadResumeParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(
+    Schema.Union([V2ThreadResumeParams__AskForApproval, Schema.Null]),
+  ),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([V2ThreadResumeParams__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this thread and subsequent turns.",
+    }),
+  ),
+  baseInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  config: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.Unknown), Schema.Null]),
+  ),
+  cwd: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developerInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  model: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Configuration overrides for the resumed thread, if any.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  modelProvider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  personality: Schema.optionalKey(Schema.Union([V2ThreadResumeParams__Personality, Schema.Null])),
+  sandbox: Schema.optionalKey(Schema.Union([V2ThreadResumeParams__SandboxMode, Schema.Null])),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  threadId: Schema.String,
+}).annotate({
+  title: "ThreadResumeParams",
+  description:
+    "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+});
+
+export type V2ThreadResumeParams__PermissionProfileSelectionParams = {
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<V2ThreadResumeParams__PermissionProfileModificationParams> | null;
+  readonly type: "profile";
+};
+export const V2ThreadResumeParams__PermissionProfileSelectionParams = Schema.Union(
+  [
+    Schema.Struct({
+      id: Schema.String,
+      modifications: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadResumeParams__PermissionProfileModificationParams),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("profile").annotate({
+        title: "ProfilePermissionProfileSelectionParamsType",
+      }),
+    }).annotate({
+      title: "ProfilePermissionProfileSelectionParams",
+      description:
+        "Select a named built-in or user-defined profile and optionally apply bounded modifications that Codex knows how to validate.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeParams__ResponseItem =
+  | {
+      readonly content: ReadonlyArray<V2ThreadResumeParams__ContentItem>;
+      readonly id?: string | null;
+      readonly phase?: V2ThreadResumeParams__MessagePhase | null;
+      readonly role: string;
+      readonly type: "message";
+    }
+  | {
+      readonly content?: ReadonlyArray<V2ThreadResumeParams__ReasoningItemContent> | null;
+      readonly encrypted_content?: string | null;
+      readonly summary: ReadonlyArray<V2ThreadResumeParams__ReasoningItemReasoningSummary>;
+      readonly type: "reasoning";
+    }
+  | {
+      readonly action: V2ThreadResumeParams__LocalShellAction;
+      readonly call_id?: string | null;
+      readonly id?: string | null;
+      readonly status: V2ThreadResumeParams__LocalShellStatus;
+      readonly type: "local_shell_call";
+    }
+  | {
+      readonly arguments: string;
+      readonly call_id: string;
+      readonly id?: string | null;
+      readonly name: string;
+      readonly namespace?: string | null;
+      readonly type: "function_call";
+    }
+  | {
+      readonly arguments: unknown;
+      readonly call_id?: string | null;
+      readonly execution: string;
+      readonly id?: string | null;
+      readonly status?: string | null;
+      readonly type: "tool_search_call";
+    }
+  | {
+      readonly call_id: string;
+      readonly output: V2ThreadResumeParams__FunctionCallOutputBody;
+      readonly type: "function_call_output";
+    }
+  | {
+      readonly call_id: string;
+      readonly id?: string | null;
+      readonly input: string;
+      readonly name: string;
+      readonly status?: string | null;
+      readonly type: "custom_tool_call";
+    }
+  | {
+      readonly call_id: string;
+      readonly name?: string | null;
+      readonly output: V2ThreadResumeParams__FunctionCallOutputBody;
+      readonly type: "custom_tool_call_output";
+    }
+  | {
+      readonly call_id?: string | null;
+      readonly execution: string;
+      readonly status: string;
+      readonly tools: ReadonlyArray<unknown>;
+      readonly type: "tool_search_output";
+    }
+  | {
+      readonly action?: V2ThreadResumeParams__ResponsesApiWebSearchAction | null;
+      readonly id?: string | null;
+      readonly status?: string | null;
+      readonly type: "web_search_call";
+    }
+  | {
+      readonly id: string;
+      readonly result: string;
+      readonly revised_prompt?: string | null;
+      readonly status: string;
+      readonly type: "image_generation_call";
+    }
+  | { readonly encrypted_content: string; readonly type: "compaction" }
+  | { readonly encrypted_content?: string | null; readonly type: "context_compaction" }
+  | { readonly type: "other" };
+export const V2ThreadResumeParams__ResponseItem = Schema.Union(
+  [
+    Schema.Struct({
+      content: Schema.Array(V2ThreadResumeParams__ContentItem),
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      phase: Schema.optionalKey(Schema.Union([V2ThreadResumeParams__MessagePhase, Schema.Null])),
+      role: Schema.String,
+      type: Schema.Literal("message").annotate({ title: "MessageResponseItemType" }),
+    }).annotate({ title: "MessageResponseItem" }),
+    Schema.Struct({
+      content: Schema.optionalKey(
+        Schema.Union([Schema.Array(V2ThreadResumeParams__ReasoningItemContent), Schema.Null]),
+      ),
+      encrypted_content: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      summary: Schema.Array(V2ThreadResumeParams__ReasoningItemReasoningSummary),
+      type: Schema.Literal("reasoning").annotate({ title: "ReasoningResponseItemType" }),
+    }).annotate({ title: "ReasoningResponseItem" }),
+    Schema.Struct({
+      action: V2ThreadResumeParams__LocalShellAction,
+      call_id: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({ description: "Set when using the Responses API." }),
+          Schema.Null,
+        ]),
+      ),
+      id: Schema.optionalKey(
+        Schema.Union([
+          Schema.String.annotate({
+            description: "Legacy id field retained for compatibility with older payloads.",
+            writeOnly: true,
+          }),
+          Schema.Null,
+        ]),
+      ),
+      status: V2ThreadResumeParams__LocalShellStatus,
+      type: Schema.Literal("local_shell_call").annotate({
+        title: "LocalShellCallResponseItemType",
+      }),
+    }).annotate({ title: "LocalShellCallResponseItem" }),
+    Schema.Struct({
+      arguments: Schema.String,
+      call_id: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      name: Schema.String,
+      namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("function_call").annotate({ title: "FunctionCallResponseItemType" }),
+    }).annotate({ title: "FunctionCallResponseItem" }),
+    Schema.Struct({
+      arguments: Schema.Unknown,
+      call_id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      execution: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("tool_search_call").annotate({
+        title: "ToolSearchCallResponseItemType",
+      }),
+    }).annotate({ title: "ToolSearchCallResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      output: V2ThreadResumeParams__FunctionCallOutputBody,
+      type: Schema.Literal("function_call_output").annotate({
+        title: "FunctionCallOutputResponseItemType",
+      }),
+    }).annotate({ title: "FunctionCallOutputResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      input: Schema.String,
+      name: Schema.String,
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("custom_tool_call").annotate({
+        title: "CustomToolCallResponseItemType",
+      }),
+    }).annotate({ title: "CustomToolCallResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.String,
+      name: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      output: V2ThreadResumeParams__FunctionCallOutputBody,
+      type: Schema.Literal("custom_tool_call_output").annotate({
+        title: "CustomToolCallOutputResponseItemType",
+      }),
+    }).annotate({ title: "CustomToolCallOutputResponseItem" }),
+    Schema.Struct({
+      call_id: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      execution: Schema.String,
+      status: Schema.String,
+      tools: Schema.Array(Schema.Unknown),
+      type: Schema.Literal("tool_search_output").annotate({
+        title: "ToolSearchOutputResponseItemType",
+      }),
+    }).annotate({ title: "ToolSearchOutputResponseItem" }),
+    Schema.Struct({
+      action: Schema.optionalKey(
+        Schema.Union([V2ThreadResumeParams__ResponsesApiWebSearchAction, Schema.Null]),
+      ),
+      id: Schema.optionalKey(
+        Schema.Union([Schema.String.annotate({ writeOnly: true }), Schema.Null]),
+      ),
+      status: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("web_search_call").annotate({ title: "WebSearchCallResponseItemType" }),
+    }).annotate({ title: "WebSearchCallResponseItem" }),
+    Schema.Struct({
+      id: Schema.String,
+      result: Schema.String,
+      revised_prompt: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      status: Schema.String,
+      type: Schema.Literal("image_generation_call").annotate({
+        title: "ImageGenerationCallResponseItemType",
+      }),
+    }).annotate({ title: "ImageGenerationCallResponseItem" }),
+    Schema.Struct({
+      encrypted_content: Schema.String,
+      type: Schema.Literal("compaction").annotate({ title: "CompactionResponseItemType" }),
+    }).annotate({ title: "CompactionResponseItem" }),
+    Schema.Struct({
+      encrypted_content: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+      type: Schema.Literal("context_compaction").annotate({
+        title: "ContextCompactionResponseItemType",
+      }),
+    }).annotate({ title: "ContextCompactionResponseItem" }),
+    Schema.Struct({
+      type: Schema.Literal("other").annotate({ title: "OtherResponseItemType" }),
+    }).annotate({ title: "OtherResponseItem" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse = {
+  readonly approvalPolicy: V2ThreadResumeResponse__AskForApproval;
+  readonly approvalsReviewer: "user" | "auto_review" | "guardian_subagent";
+  readonly cwd: V2ThreadResumeResponse__AbsolutePathBuf;
+  readonly instructionSources?: ReadonlyArray<V2ThreadResumeResponse__AbsolutePathBuf>;
+  readonly model: string;
+  readonly modelProvider: string;
+  readonly reasoningEffort?: V2ThreadResumeResponse__ReasoningEffort | null;
+  readonly sandbox:
+    | { readonly type: "dangerFullAccess" }
+    | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+    | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+    | {
+        readonly excludeSlashTmp?: boolean;
+        readonly excludeTmpdirEnvVar?: boolean;
+        readonly networkAccess?: boolean;
+        readonly type: "workspaceWrite";
+        readonly writableRoots?: ReadonlyArray<V2ThreadResumeResponse__AbsolutePathBuf>;
+      };
+  readonly serviceTier?: string | null;
+  readonly thread: V2ThreadResumeResponse__Thread;
+};
+export const V2ThreadResumeResponse = Schema.Struct({
+  approvalPolicy: V2ThreadResumeResponse__AskForApproval,
+  approvalsReviewer: Schema.Literals(["user", "auto_review", "guardian_subagent"]).annotate({
+    description:
+      "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+  }),
+  cwd: V2ThreadResumeResponse__AbsolutePathBuf,
+  instructionSources: Schema.optionalKey(
+    Schema.Array(V2ThreadResumeResponse__AbsolutePathBuf).annotate({
+      description: "Instruction source files currently loaded for this thread.",
+      default: [],
+    }),
+  ),
+  model: Schema.String,
+  modelProvider: Schema.String,
+  reasoningEffort: Schema.optionalKey(
+    Schema.Union([V2ThreadResumeResponse__ReasoningEffort, Schema.Null]),
+  ),
+  sandbox: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("dangerFullAccess").annotate({
+          title: "DangerFullAccessSandboxPolicyType",
+        }),
+      }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+      Schema.Struct({
+        networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+      }).annotate({ title: "ReadOnlySandboxPolicy" }),
+      Schema.Struct({
+        networkAccess: Schema.optionalKey(
+          Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+        ),
+        type: Schema.Literal("externalSandbox").annotate({
+          title: "ExternalSandboxSandboxPolicyType",
+        }),
+      }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+      Schema.Struct({
+        excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        type: Schema.Literal("workspaceWrite").annotate({
+          title: "WorkspaceWriteSandboxPolicyType",
+        }),
+        writableRoots: Schema.optionalKey(
+          Schema.Array(V2ThreadResumeResponse__AbsolutePathBuf).annotate({ default: [] }),
+        ),
+      }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description:
+      "Legacy sandbox policy retained for compatibility. Experimental clients should prefer `permissionProfile` when they need exact runtime permissions.",
+  }),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  thread: V2ThreadResumeResponse__Thread,
+}).annotate({ title: "ThreadResumeResponse" });
+
+export type V2ThreadResumeResponse__ActivePermissionProfile = {
+  readonly extends?: string | null;
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<V2ThreadResumeResponse__ActivePermissionProfileModification>;
+};
+export const V2ThreadResumeResponse__ActivePermissionProfile = Schema.Struct({
+  extends: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Parent profile identifier once permissions profiles support inheritance. This is currently always `null`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  id: Schema.String.annotate({
+    description:
+      "Identifier from `default_permissions` or the implicit built-in default, such as `:workspace` or a user-defined `[permissions.<id>]` profile.",
+  }),
+  modifications: Schema.optionalKey(
+    Schema.Array(V2ThreadResumeResponse__ActivePermissionProfileModification).annotate({
+      description:
+        "Bounded user-requested modifications applied on top of the named profile, if any.",
+      default: [],
+    }),
+  ),
+});
+
+export type V2ThreadResumeResponse__ApprovalsReviewer =
+  | "user"
+  | "auto_review"
+  | "guardian_subagent";
+export const V2ThreadResumeResponse__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ThreadResumeResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ThreadResumeResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadResumeResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadResumeResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadResumeResponse__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadResumeResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadResumeResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadResumeResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadResumeResponse__NetworkAccess = "restricted" | "enabled";
+export const V2ThreadResumeResponse__NetworkAccess = Schema.Literals(["restricted", "enabled"]);
+
+export type V2ThreadResumeResponse__PermissionProfile =
+  | {
+      readonly fileSystem: V2ThreadResumeResponse__PermissionProfileFileSystemPermissions;
+      readonly network: V2ThreadResumeResponse__PermissionProfileNetworkPermissions;
+      readonly type: "managed";
+    }
+  | { readonly type: "disabled" }
+  | {
+      readonly network: V2ThreadResumeResponse__PermissionProfileNetworkPermissions;
+      readonly type: "external";
+    };
+export const V2ThreadResumeResponse__PermissionProfile = Schema.Union(
+  [
+    Schema.Struct({
+      fileSystem: V2ThreadResumeResponse__PermissionProfileFileSystemPermissions,
+      network: V2ThreadResumeResponse__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("managed").annotate({ title: "ManagedPermissionProfileType" }),
+    }).annotate({
+      title: "ManagedPermissionProfile",
+      description: "Codex owns sandbox construction for this profile.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("disabled").annotate({ title: "DisabledPermissionProfileType" }),
+    }).annotate({
+      title: "DisabledPermissionProfile",
+      description: "Do not apply an outer sandbox.",
+    }),
+    Schema.Struct({
+      network: V2ThreadResumeResponse__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("external").annotate({ title: "ExternalPermissionProfileType" }),
+    }).annotate({
+      title: "ExternalPermissionProfile",
+      description: "Filesystem isolation is enforced by an external caller.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__SandboxPolicy =
+  | { readonly type: "dangerFullAccess" }
+  | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+  | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+  | {
+      readonly excludeSlashTmp?: boolean;
+      readonly excludeTmpdirEnvVar?: boolean;
+      readonly networkAccess?: boolean;
+      readonly type: "workspaceWrite";
+      readonly writableRoots?: ReadonlyArray<V2ThreadResumeResponse__AbsolutePathBuf>;
+    };
+export const V2ThreadResumeResponse__SandboxPolicy = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("dangerFullAccess").annotate({
+        title: "DangerFullAccessSandboxPolicyType",
+      }),
+    }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+    }).annotate({ title: "ReadOnlySandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(
+        Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+      ),
+      type: Schema.Literal("externalSandbox").annotate({
+        title: "ExternalSandboxSandboxPolicyType",
+      }),
+    }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+    Schema.Struct({
+      excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("workspaceWrite").annotate({ title: "WorkspaceWriteSandboxPolicyType" }),
+      writableRoots: Schema.optionalKey(
+        Schema.Array(V2ThreadResumeResponse__AbsolutePathBuf).annotate({ default: [] }),
+      ),
+    }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadResumeResponse__SubAgentSource };
+export const V2ThreadResumeResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadResumeResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadResumeResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadResumeResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadResumeResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadResumeResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadResumeResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadRollbackParams = { readonly numTurns: number; readonly threadId: string };
+export const V2ThreadRollbackParams = Schema.Struct({
+  numTurns: Schema.Number.annotate({
+    description:
+      "The number of turns to drop from the end of the thread. Must be >= 1.\n\nThis only modifies the thread's history and does not revert local file changes that have been made by the agent. Clients are responsible for reverting these changes.",
+    format: "uint32",
+  })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  threadId: Schema.String,
+}).annotate({ title: "ThreadRollbackParams" });
+
+export type V2ThreadRollbackResponse = {
+  readonly thread: {
+    readonly agentNickname?: string | null;
+    readonly agentRole?: string | null;
+    readonly cliVersion: string;
+    readonly createdAt: number;
+    readonly cwd: string;
+    readonly ephemeral: boolean;
+    readonly forkedFromId?: string | null;
+    readonly gitInfo?: V2ThreadRollbackResponse__GitInfo | null;
+    readonly id: string;
+    readonly modelProvider: string;
+    readonly name?: string | null;
+    readonly path?: string | null;
+    readonly preview: string;
+    readonly sessionId: string;
+    readonly source:
+      | "cli"
+      | "vscode"
+      | "exec"
+      | "appServer"
+      | "unknown"
+      | { readonly custom: string }
+      | { readonly subAgent: V2ThreadRollbackResponse__SubAgentSource };
+    readonly status:
+      | { readonly type: "notLoaded" }
+      | { readonly type: "idle" }
+      | { readonly type: "systemError" }
+      | {
+          readonly activeFlags: ReadonlyArray<V2ThreadRollbackResponse__ThreadActiveFlag>;
+          readonly type: "active";
+        };
+    readonly threadSource?: V2ThreadRollbackResponse__ThreadSource | null;
+    readonly turns: ReadonlyArray<V2ThreadRollbackResponse__Turn>;
+    readonly updatedAt: number;
+  };
+};
+export const V2ThreadRollbackResponse = Schema.Struct({
+  thread: Schema.Struct({
+    agentNickname: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description:
+            "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    agentRole: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    cliVersion: Schema.String.annotate({
+      description: "Version of the CLI that created the thread.",
+    }),
+    createdAt: Schema.Number.annotate({
+      description: "Unix timestamp (in seconds) when the thread was created.",
+      format: "int64",
+    }).check(Schema.isInt()),
+    cwd: Schema.String.annotate({
+      description:
+        "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+    }),
+    ephemeral: Schema.Boolean.annotate({
+      description: "Whether the thread is ephemeral and should not be materialized on disk.",
+    }),
+    forkedFromId: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({
+          description: "Source thread id when this thread was created by forking another thread.",
+        }),
+        Schema.Null,
+      ]),
+    ),
+    gitInfo: Schema.optionalKey(
+      Schema.Union([V2ThreadRollbackResponse__GitInfo, Schema.Null]).annotate({
+        description: "Optional Git metadata captured when the thread was created.",
+      }),
+    ),
+    id: Schema.String,
+    modelProvider: Schema.String.annotate({
+      description: "Model provider used for this thread (for example, 'openai').",
+    }),
+    name: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({ description: "Optional user-facing thread title." }),
+        Schema.Null,
+      ]),
+    ),
+    path: Schema.optionalKey(
+      Schema.Union([
+        Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+        Schema.Null,
+      ]),
+    ),
+    preview: Schema.String.annotate({
+      description: "Usually the first user message in the thread, if available.",
+    }),
+    sessionId: Schema.String.annotate({
+      description: "Session id shared by threads that belong to the same session tree.",
+    }),
+    source: Schema.Union(
+      [
+        Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+        Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+        Schema.Struct({ subAgent: V2ThreadRollbackResponse__SubAgentSource }).annotate({
+          title: "SubAgentSessionSource",
+        }),
+      ],
+      { mode: "oneOf" },
+    ).annotate({
+      description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+    }),
+    status: Schema.Union(
+      [
+        Schema.Struct({
+          type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+        }).annotate({ title: "NotLoadedThreadStatus" }),
+        Schema.Struct({
+          type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+        }).annotate({ title: "IdleThreadStatus" }),
+        Schema.Struct({
+          type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+        }).annotate({ title: "SystemErrorThreadStatus" }),
+        Schema.Struct({
+          activeFlags: Schema.Array(V2ThreadRollbackResponse__ThreadActiveFlag),
+          type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+        }).annotate({ title: "ActiveThreadStatus" }),
+      ],
+      { mode: "oneOf" },
+    ).annotate({ description: "Current runtime status for the thread." }),
+    threadSource: Schema.optionalKey(
+      Schema.Union([V2ThreadRollbackResponse__ThreadSource, Schema.Null]).annotate({
+        description: "Optional analytics source classification for this thread.",
+      }),
+    ),
+    turns: Schema.Array(V2ThreadRollbackResponse__Turn).annotate({
+      description:
+        "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+    }),
+    updatedAt: Schema.Number.annotate({
+      description: "Unix timestamp (in seconds) when the thread was last updated.",
+      format: "int64",
+    }).check(Schema.isInt()),
+  }).annotate({
+    description:
+      "The updated thread after applying the rollback, with `turns` populated.\n\nThe ThreadItems stored in each Turn are lossy since we explicitly do not persist all agent interactions, such as command executions. This is the same behavior as `thread/resume`.",
+  }),
+}).annotate({ title: "ThreadRollbackResponse" });
+
+export type V2ThreadRollbackResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ThreadRollbackResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadRollbackResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadRollbackResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadRollbackResponse__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadRollbackResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadRollbackResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadRollbackResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadRollbackResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadRollbackResponse__SubAgentSource };
+export const V2ThreadRollbackResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadRollbackResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__Thread = {
+  readonly agentNickname?: string | null;
+  readonly agentRole?: string | null;
+  readonly cliVersion: string;
+  readonly createdAt: number;
+  readonly cwd: string;
+  readonly ephemeral: boolean;
+  readonly forkedFromId?: string | null;
+  readonly gitInfo?: V2ThreadRollbackResponse__GitInfo | null;
+  readonly id: string;
+  readonly modelProvider: string;
+  readonly name?: string | null;
+  readonly path?: string | null;
+  readonly preview: string;
+  readonly sessionId: string;
+  readonly source:
+    | "cli"
+    | "vscode"
+    | "exec"
+    | "appServer"
+    | "unknown"
+    | { readonly custom: string }
+    | { readonly subAgent: V2ThreadRollbackResponse__SubAgentSource };
+  readonly status:
+    | { readonly type: "notLoaded" }
+    | { readonly type: "idle" }
+    | { readonly type: "systemError" }
+    | {
+        readonly activeFlags: ReadonlyArray<V2ThreadRollbackResponse__ThreadActiveFlag>;
+        readonly type: "active";
+      };
+  readonly threadSource?: V2ThreadRollbackResponse__ThreadSource | null;
+  readonly turns: ReadonlyArray<V2ThreadRollbackResponse__Turn>;
+  readonly updatedAt: number;
+};
+export const V2ThreadRollbackResponse__Thread = Schema.Struct({
+  agentNickname: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  agentRole: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  cliVersion: Schema.String.annotate({
+    description: "Version of the CLI that created the thread.",
+  }),
+  createdAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was created.",
+    format: "int64",
+  }).check(Schema.isInt()),
+  cwd: Schema.String.annotate({
+    description:
+      "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+  }),
+  ephemeral: Schema.Boolean.annotate({
+    description: "Whether the thread is ephemeral and should not be materialized on disk.",
+  }),
+  forkedFromId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Source thread id when this thread was created by forking another thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  gitInfo: Schema.optionalKey(
+    Schema.Union([V2ThreadRollbackResponse__GitInfo, Schema.Null]).annotate({
+      description: "Optional Git metadata captured when the thread was created.",
+    }),
+  ),
+  id: Schema.String,
+  modelProvider: Schema.String.annotate({
+    description: "Model provider used for this thread (for example, 'openai').",
+  }),
+  name: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "Optional user-facing thread title." }),
+      Schema.Null,
+    ]),
+  ),
+  path: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({ description: "[UNSTABLE] Path to the thread on disk." }),
+      Schema.Null,
+    ]),
+  ),
+  preview: Schema.String.annotate({
+    description: "Usually the first user message in the thread, if available.",
+  }),
+  sessionId: Schema.String.annotate({
+    description: "Session id shared by threads that belong to the same session tree.",
+  }),
+  source: Schema.Union(
+    [
+      Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+      Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+      Schema.Struct({ subAgent: V2ThreadRollbackResponse__SubAgentSource }).annotate({
+        title: "SubAgentSessionSource",
+      }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description: "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.).",
+  }),
+  status: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+      }).annotate({ title: "NotLoadedThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+      }).annotate({ title: "IdleThreadStatus" }),
+      Schema.Struct({
+        type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+      }).annotate({ title: "SystemErrorThreadStatus" }),
+      Schema.Struct({
+        activeFlags: Schema.Array(V2ThreadRollbackResponse__ThreadActiveFlag),
+        type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+      }).annotate({ title: "ActiveThreadStatus" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({ description: "Current runtime status for the thread." }),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadRollbackResponse__ThreadSource, Schema.Null]).annotate({
+      description: "Optional analytics source classification for this thread.",
+    }),
+  ),
+  turns: Schema.Array(V2ThreadRollbackResponse__Turn).annotate({
+    description:
+      "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
+  }),
+  updatedAt: Schema.Number.annotate({
+    description: "Unix timestamp (in seconds) when the thread was last updated.",
+    format: "int64",
+  }).check(Schema.isInt()),
+});
+
+export type V2ThreadRollbackResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadRollbackResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadRollbackResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadRollbackResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadRollbackResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadRollbackResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadSetNameParams = { readonly name: string; readonly threadId: string };
+export const V2ThreadSetNameParams = Schema.Struct({
+  name: Schema.String,
+  threadId: Schema.String,
+}).annotate({ title: "ThreadSetNameParams" });
+
+export type V2ThreadSetNameResponse = {};
+export const V2ThreadSetNameResponse = Schema.Struct({}).annotate({
+  title: "ThreadSetNameResponse",
+});
+
+export type V2ThreadShellCommandParams = { readonly command: string; readonly threadId: string };
+export const V2ThreadShellCommandParams = Schema.Struct({
+  command: Schema.String.annotate({
+    description:
+      "Shell command string evaluated by the thread's configured shell. Unlike `command/exec`, this intentionally preserves shell syntax such as pipes, redirects, and quoting. This runs unsandboxed with full access rather than inheriting the thread sandbox policy.",
+  }),
+  threadId: Schema.String,
+}).annotate({ title: "ThreadShellCommandParams" });
+
+export type V2ThreadShellCommandResponse = {};
+export const V2ThreadShellCommandResponse = Schema.Struct({}).annotate({
+  title: "ThreadShellCommandResponse",
+});
+
+export type V2ThreadStartedNotification = { readonly thread: V2ThreadStartedNotification__Thread };
+export const V2ThreadStartedNotification = Schema.Struct({
+  thread: V2ThreadStartedNotification__Thread,
+}).annotate({ title: "ThreadStartedNotification" });
+
+export type V2ThreadStartedNotification__ByteRange = {
+  readonly end: number;
+  readonly start: number;
+};
+export const V2ThreadStartedNotification__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadStartedNotification__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadStartedNotification__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadStartedNotification__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadStartedNotification__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadStartedNotification__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadStartedNotification__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadStartedNotification__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadStartedNotification__SubAgentSource };
+export const V2ThreadStartedNotification__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadStartedNotification__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadStartedNotification__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadStartedNotification__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadStartedNotification__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartedNotification__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadStartedNotification__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadStartParams = {
+  readonly approvalPolicy?: V2ThreadStartParams__AskForApproval | null;
+  readonly approvalsReviewer?: V2ThreadStartParams__ApprovalsReviewer | null;
+  readonly baseInstructions?: string | null;
+  readonly config?: { readonly [x: string]: unknown } | null;
+  readonly cwd?: string | null;
+  readonly developerInstructions?: string | null;
+  readonly ephemeral?: boolean | null;
+  readonly model?: string | null;
+  readonly modelProvider?: string | null;
+  readonly personality?: V2ThreadStartParams__Personality | null;
+  readonly sandbox?: V2ThreadStartParams__SandboxMode | null;
+  readonly serviceName?: string | null;
+  readonly serviceTier?: string | null;
+  readonly sessionStartSource?: V2ThreadStartParams__ThreadStartSource | null;
+  readonly threadSource?: V2ThreadStartParams__ThreadSource | null;
+};
+export const V2ThreadStartParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(
+    Schema.Union([V2ThreadStartParams__AskForApproval, Schema.Null]),
+  ),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([V2ThreadStartParams__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this thread and subsequent turns.",
+    }),
+  ),
+  baseInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  config: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Schema.Unknown), Schema.Null]),
+  ),
+  cwd: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  developerInstructions: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  ephemeral: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Null])),
+  model: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  modelProvider: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  personality: Schema.optionalKey(Schema.Union([V2ThreadStartParams__Personality, Schema.Null])),
+  sandbox: Schema.optionalKey(Schema.Union([V2ThreadStartParams__SandboxMode, Schema.Null])),
+  serviceName: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  sessionStartSource: Schema.optionalKey(
+    Schema.Union([V2ThreadStartParams__ThreadStartSource, Schema.Null]),
+  ),
+  threadSource: Schema.optionalKey(
+    Schema.Union([V2ThreadStartParams__ThreadSource, Schema.Null]).annotate({
+      description: "Optional client-supplied analytics source classification for this thread.",
+    }),
+  ),
+}).annotate({ title: "ThreadStartParams" });
+
+export type V2ThreadStartParams__DynamicToolSpec = {
+  readonly deferLoading?: boolean;
+  readonly description: string;
+  readonly inputSchema: unknown;
+  readonly name: string;
+  readonly namespace?: string | null;
+};
+export const V2ThreadStartParams__DynamicToolSpec = Schema.Struct({
+  deferLoading: Schema.optionalKey(Schema.Boolean),
+  description: Schema.String,
+  inputSchema: Schema.Unknown,
+  name: Schema.String,
+  namespace: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+});
+
+export type V2ThreadStartParams__PermissionProfileSelectionParams = {
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<V2ThreadStartParams__PermissionProfileModificationParams> | null;
+  readonly type: "profile";
+};
+export const V2ThreadStartParams__PermissionProfileSelectionParams = Schema.Union(
+  [
+    Schema.Struct({
+      id: Schema.String,
+      modifications: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2ThreadStartParams__PermissionProfileModificationParams),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("profile").annotate({
+        title: "ProfilePermissionProfileSelectionParamsType",
+      }),
+    }).annotate({
+      title: "ProfilePermissionProfileSelectionParams",
+      description:
+        "Select a named built-in or user-defined profile and optionally apply bounded modifications that Codex knows how to validate.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartParams__TurnEnvironmentParams = {
+  readonly cwd: V2ThreadStartParams__AbsolutePathBuf;
+  readonly environmentId: string;
+};
+export const V2ThreadStartParams__TurnEnvironmentParams = Schema.Struct({
+  cwd: V2ThreadStartParams__AbsolutePathBuf,
+  environmentId: Schema.String,
+});
+
+export type V2ThreadStartResponse = {
+  readonly approvalPolicy: V2ThreadStartResponse__AskForApproval;
+  readonly approvalsReviewer: "user" | "auto_review" | "guardian_subagent";
+  readonly cwd: V2ThreadStartResponse__AbsolutePathBuf;
+  readonly instructionSources?: ReadonlyArray<V2ThreadStartResponse__AbsolutePathBuf>;
+  readonly model: string;
+  readonly modelProvider: string;
+  readonly reasoningEffort?: V2ThreadStartResponse__ReasoningEffort | null;
+  readonly sandbox:
+    | { readonly type: "dangerFullAccess" }
+    | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+    | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+    | {
+        readonly excludeSlashTmp?: boolean;
+        readonly excludeTmpdirEnvVar?: boolean;
+        readonly networkAccess?: boolean;
+        readonly type: "workspaceWrite";
+        readonly writableRoots?: ReadonlyArray<V2ThreadStartResponse__AbsolutePathBuf>;
+      };
+  readonly serviceTier?: string | null;
+  readonly thread: V2ThreadStartResponse__Thread;
+};
+export const V2ThreadStartResponse = Schema.Struct({
+  approvalPolicy: V2ThreadStartResponse__AskForApproval,
+  approvalsReviewer: Schema.Literals(["user", "auto_review", "guardian_subagent"]).annotate({
+    description:
+      "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+  }),
+  cwd: V2ThreadStartResponse__AbsolutePathBuf,
+  instructionSources: Schema.optionalKey(
+    Schema.Array(V2ThreadStartResponse__AbsolutePathBuf).annotate({
+      description: "Instruction source files currently loaded for this thread.",
+      default: [],
+    }),
+  ),
+  model: Schema.String,
+  modelProvider: Schema.String,
+  reasoningEffort: Schema.optionalKey(
+    Schema.Union([V2ThreadStartResponse__ReasoningEffort, Schema.Null]),
+  ),
+  sandbox: Schema.Union(
+    [
+      Schema.Struct({
+        type: Schema.Literal("dangerFullAccess").annotate({
+          title: "DangerFullAccessSandboxPolicyType",
+        }),
+      }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+      Schema.Struct({
+        networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+      }).annotate({ title: "ReadOnlySandboxPolicy" }),
+      Schema.Struct({
+        networkAccess: Schema.optionalKey(
+          Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+        ),
+        type: Schema.Literal("externalSandbox").annotate({
+          title: "ExternalSandboxSandboxPolicyType",
+        }),
+      }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+      Schema.Struct({
+        excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+        type: Schema.Literal("workspaceWrite").annotate({
+          title: "WorkspaceWriteSandboxPolicyType",
+        }),
+        writableRoots: Schema.optionalKey(
+          Schema.Array(V2ThreadStartResponse__AbsolutePathBuf).annotate({ default: [] }),
+        ),
+      }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+    ],
+    { mode: "oneOf" },
+  ).annotate({
+    description:
+      "Legacy sandbox policy retained for compatibility. Experimental clients should prefer `permissionProfile` when they need exact runtime permissions.",
+  }),
+  serviceTier: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  thread: V2ThreadStartResponse__Thread,
+}).annotate({ title: "ThreadStartResponse" });
+
+export type V2ThreadStartResponse__ActivePermissionProfile = {
+  readonly extends?: string | null;
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<V2ThreadStartResponse__ActivePermissionProfileModification>;
+};
+export const V2ThreadStartResponse__ActivePermissionProfile = Schema.Struct({
+  extends: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description:
+          "Parent profile identifier once permissions profiles support inheritance. This is currently always `null`.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  id: Schema.String.annotate({
+    description:
+      "Identifier from `default_permissions` or the implicit built-in default, such as `:workspace` or a user-defined `[permissions.<id>]` profile.",
+  }),
+  modifications: Schema.optionalKey(
+    Schema.Array(V2ThreadStartResponse__ActivePermissionProfileModification).annotate({
+      description:
+        "Bounded user-requested modifications applied on top of the named profile, if any.",
+      default: [],
+    }),
+  ),
+});
+
+export type V2ThreadStartResponse__ApprovalsReviewer = "user" | "auto_review" | "guardian_subagent";
+export const V2ThreadStartResponse__ApprovalsReviewer = Schema.Literals([
+  "user",
+  "auto_review",
+  "guardian_subagent",
+]).annotate({
+  description:
+    "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
+});
+
+export type V2ThreadStartResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ThreadStartResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadStartResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadStartResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadStartResponse__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadStartResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadStartResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadStartResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadStartResponse__NetworkAccess = "restricted" | "enabled";
+export const V2ThreadStartResponse__NetworkAccess = Schema.Literals(["restricted", "enabled"]);
+
+export type V2ThreadStartResponse__PermissionProfile =
+  | {
+      readonly fileSystem: V2ThreadStartResponse__PermissionProfileFileSystemPermissions;
+      readonly network: V2ThreadStartResponse__PermissionProfileNetworkPermissions;
+      readonly type: "managed";
+    }
+  | { readonly type: "disabled" }
+  | {
+      readonly network: V2ThreadStartResponse__PermissionProfileNetworkPermissions;
+      readonly type: "external";
+    };
+export const V2ThreadStartResponse__PermissionProfile = Schema.Union(
+  [
+    Schema.Struct({
+      fileSystem: V2ThreadStartResponse__PermissionProfileFileSystemPermissions,
+      network: V2ThreadStartResponse__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("managed").annotate({ title: "ManagedPermissionProfileType" }),
+    }).annotate({
+      title: "ManagedPermissionProfile",
+      description: "Codex owns sandbox construction for this profile.",
+    }),
+    Schema.Struct({
+      type: Schema.Literal("disabled").annotate({ title: "DisabledPermissionProfileType" }),
+    }).annotate({
+      title: "DisabledPermissionProfile",
+      description: "Do not apply an outer sandbox.",
+    }),
+    Schema.Struct({
+      network: V2ThreadStartResponse__PermissionProfileNetworkPermissions,
+      type: Schema.Literal("external").annotate({ title: "ExternalPermissionProfileType" }),
+    }).annotate({
+      title: "ExternalPermissionProfile",
+      description: "Filesystem isolation is enforced by an external caller.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__SandboxPolicy =
+  | { readonly type: "dangerFullAccess" }
+  | { readonly networkAccess?: boolean; readonly type: "readOnly" }
+  | { readonly networkAccess?: "restricted" | "enabled"; readonly type: "externalSandbox" }
+  | {
+      readonly excludeSlashTmp?: boolean;
+      readonly excludeTmpdirEnvVar?: boolean;
+      readonly networkAccess?: boolean;
+      readonly type: "workspaceWrite";
+      readonly writableRoots?: ReadonlyArray<V2ThreadStartResponse__AbsolutePathBuf>;
+    };
+export const V2ThreadStartResponse__SandboxPolicy = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("dangerFullAccess").annotate({
+        title: "DangerFullAccessSandboxPolicyType",
+      }),
+    }).annotate({ title: "DangerFullAccessSandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("readOnly").annotate({ title: "ReadOnlySandboxPolicyType" }),
+    }).annotate({ title: "ReadOnlySandboxPolicy" }),
+    Schema.Struct({
+      networkAccess: Schema.optionalKey(
+        Schema.Literals(["restricted", "enabled"]).annotate({ default: "restricted" }),
+      ),
+      type: Schema.Literal("externalSandbox").annotate({
+        title: "ExternalSandboxSandboxPolicyType",
+      }),
+    }).annotate({ title: "ExternalSandboxSandboxPolicy" }),
+    Schema.Struct({
+      excludeSlashTmp: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      excludeTmpdirEnvVar: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      networkAccess: Schema.optionalKey(Schema.Boolean.annotate({ default: false })),
+      type: Schema.Literal("workspaceWrite").annotate({ title: "WorkspaceWriteSandboxPolicyType" }),
+      writableRoots: Schema.optionalKey(
+        Schema.Array(V2ThreadStartResponse__AbsolutePathBuf).annotate({ default: [] }),
+      ),
+    }).annotate({ title: "WorkspaceWriteSandboxPolicy" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadStartResponse__SubAgentSource };
+export const V2ThreadStartResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadStartResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadStartResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadStartResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadStartResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadStartResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadStartResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadStatusChangedNotification = {
+  readonly status: V2ThreadStatusChangedNotification__ThreadStatus;
+  readonly threadId: string;
+};
+export const V2ThreadStatusChangedNotification = Schema.Struct({
+  status: V2ThreadStatusChangedNotification__ThreadStatus,
+  threadId: Schema.String,
+}).annotate({ title: "ThreadStatusChangedNotification" });
+
+export type V2ThreadTokenUsageUpdatedNotification = {
+  readonly threadId: string;
+  readonly tokenUsage: V2ThreadTokenUsageUpdatedNotification__ThreadTokenUsage;
+  readonly turnId: string;
+};
+export const V2ThreadTokenUsageUpdatedNotification = Schema.Struct({
+  threadId: Schema.String,
+  tokenUsage: V2ThreadTokenUsageUpdatedNotification__ThreadTokenUsage,
+  turnId: Schema.String,
+}).annotate({ title: "ThreadTokenUsageUpdatedNotification" });
+
+export type V2ThreadUnarchivedNotification = { readonly threadId: string };
+export const V2ThreadUnarchivedNotification = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadUnarchivedNotification",
+});
+
+export type V2ThreadUnarchiveParams = { readonly threadId: string };
+export const V2ThreadUnarchiveParams = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadUnarchiveParams",
+});
+
+export type V2ThreadUnarchiveResponse = { readonly thread: V2ThreadUnarchiveResponse__Thread };
+export const V2ThreadUnarchiveResponse = Schema.Struct({
+  thread: V2ThreadUnarchiveResponse__Thread,
+}).annotate({ title: "ThreadUnarchiveResponse" });
+
+export type V2ThreadUnarchiveResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2ThreadUnarchiveResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2ThreadUnarchiveResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2ThreadUnarchiveResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2ThreadUnarchiveResponse__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2ThreadUnarchiveResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2ThreadUnarchiveResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2ThreadUnarchiveResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2ThreadUnarchiveResponse__SessionSource =
+  | "cli"
+  | "vscode"
+  | "exec"
+  | "appServer"
+  | "unknown"
+  | { readonly custom: string }
+  | { readonly subAgent: V2ThreadUnarchiveResponse__SubAgentSource };
+export const V2ThreadUnarchiveResponse__SessionSource = Schema.Union(
+  [
+    Schema.Literals(["cli", "vscode", "exec", "appServer", "unknown"]),
+    Schema.Struct({ custom: Schema.String }).annotate({ title: "CustomSessionSource" }),
+    Schema.Struct({ subAgent: V2ThreadUnarchiveResponse__SubAgentSource }).annotate({
+      title: "SubAgentSessionSource",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnarchiveResponse__ThreadStatus =
+  | { readonly type: "notLoaded" }
+  | { readonly type: "idle" }
+  | { readonly type: "systemError" }
+  | {
+      readonly activeFlags: ReadonlyArray<V2ThreadUnarchiveResponse__ThreadActiveFlag>;
+      readonly type: "active";
+    };
+export const V2ThreadUnarchiveResponse__ThreadStatus = Schema.Union(
+  [
+    Schema.Struct({
+      type: Schema.Literal("notLoaded").annotate({ title: "NotLoadedThreadStatusType" }),
+    }).annotate({ title: "NotLoadedThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("idle").annotate({ title: "IdleThreadStatusType" }),
+    }).annotate({ title: "IdleThreadStatus" }),
+    Schema.Struct({
+      type: Schema.Literal("systemError").annotate({ title: "SystemErrorThreadStatusType" }),
+    }).annotate({ title: "SystemErrorThreadStatus" }),
+    Schema.Struct({
+      activeFlags: Schema.Array(V2ThreadUnarchiveResponse__ThreadActiveFlag),
+      type: Schema.Literal("active").annotate({ title: "ActiveThreadStatusType" }),
+    }).annotate({ title: "ActiveThreadStatus" }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2ThreadUnarchiveResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2ThreadUnarchiveResponse__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2ThreadUnsubscribeParams = { readonly threadId: string };
+export const V2ThreadUnsubscribeParams = Schema.Struct({ threadId: Schema.String }).annotate({
+  title: "ThreadUnsubscribeParams",
+});
+
+export type V2ThreadUnsubscribeResponse = {
+  readonly status: V2ThreadUnsubscribeResponse__ThreadUnsubscribeStatus;
+};
+export const V2ThreadUnsubscribeResponse = Schema.Struct({
+  status: V2ThreadUnsubscribeResponse__ThreadUnsubscribeStatus,
+}).annotate({ title: "ThreadUnsubscribeResponse" });
+
+export type V2TurnCompletedNotification = {
+  readonly threadId: string;
+  readonly turn: V2TurnCompletedNotification__Turn;
+};
+export const V2TurnCompletedNotification = Schema.Struct({
+  threadId: Schema.String,
+  turn: V2TurnCompletedNotification__Turn,
+}).annotate({ title: "TurnCompletedNotification" });
+
+export type V2TurnCompletedNotification__ByteRange = {
+  readonly end: number;
+  readonly start: number;
+};
+export const V2TurnCompletedNotification__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2TurnCompletedNotification__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2TurnCompletedNotification__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2TurnCompletedNotification__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2TurnCompletedNotification__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnCompletedNotification__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2TurnCompletedNotification__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2TurnCompletedNotification__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2TurnCompletedNotification__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2TurnDiffUpdatedNotification = {
+  readonly diff: string;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2TurnDiffUpdatedNotification = Schema.Struct({
+  diff: Schema.String,
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({
+  title: "TurnDiffUpdatedNotification",
+  description:
+    "Notification that the turn-level unified diff has changed. Contains the latest aggregated diff across all file changes in the turn.",
+});
+
+export type V2TurnInterruptParams = { readonly threadId: string; readonly turnId: string };
+export const V2TurnInterruptParams = Schema.Struct({
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "TurnInterruptParams" });
+
+export type V2TurnInterruptResponse = {};
+export const V2TurnInterruptResponse = Schema.Struct({}).annotate({
+  title: "TurnInterruptResponse",
+});
+
+export type V2TurnPlanUpdatedNotification = {
+  readonly explanation?: string | null;
+  readonly plan: ReadonlyArray<V2TurnPlanUpdatedNotification__TurnPlanStep>;
+  readonly threadId: string;
+  readonly turnId: string;
+};
+export const V2TurnPlanUpdatedNotification = Schema.Struct({
+  explanation: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  plan: Schema.Array(V2TurnPlanUpdatedNotification__TurnPlanStep),
+  threadId: Schema.String,
+  turnId: Schema.String,
+}).annotate({ title: "TurnPlanUpdatedNotification" });
+
+export type V2TurnStartedNotification = {
+  readonly threadId: string;
+  readonly turn: V2TurnStartedNotification__Turn;
+};
+export const V2TurnStartedNotification = Schema.Struct({
+  threadId: Schema.String,
+  turn: V2TurnStartedNotification__Turn,
+}).annotate({ title: "TurnStartedNotification" });
+
+export type V2TurnStartedNotification__ByteRange = { readonly end: number; readonly start: number };
+export const V2TurnStartedNotification__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2TurnStartedNotification__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2TurnStartedNotification__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2TurnStartedNotification__CollabAgentToolCallStatus =
+  | "inProgress"
+  | "completed"
+  | "failed";
+export const V2TurnStartedNotification__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnStartedNotification__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2TurnStartedNotification__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2TurnStartedNotification__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2TurnStartedNotification__TurnItemsView = Schema.Literals([
+  "notLoaded",
+  "summary",
+  "full",
+]);
+
+export type V2TurnStartParams = {
+  readonly approvalPolicy?: V2TurnStartParams__AskForApproval | null;
+  readonly approvalsReviewer?: V2TurnStartParams__ApprovalsReviewer | null;
+  readonly cwd?: string | null;
+  readonly effort?: V2TurnStartParams__ReasoningEffort | null;
+  readonly input: ReadonlyArray<V2TurnStartParams__UserInput>;
+  readonly model?: string | null;
+  readonly outputSchema?: unknown;
+  readonly personality?: V2TurnStartParams__Personality | null;
+  readonly sandboxPolicy?: V2TurnStartParams__SandboxPolicy | null;
+  readonly serviceTier?: string | null;
+  readonly summary?: V2TurnStartParams__ReasoningSummary | null;
+  readonly threadId: string;
+};
+export const V2TurnStartParams = Schema.Struct({
+  approvalPolicy: Schema.optionalKey(
+    Schema.Union([V2TurnStartParams__AskForApproval, Schema.Null]).annotate({
+      description: "Override the approval policy for this turn and subsequent turns.",
+    }),
+  ),
+  approvalsReviewer: Schema.optionalKey(
+    Schema.Union([V2TurnStartParams__ApprovalsReviewer, Schema.Null]).annotate({
+      description:
+        "Override where approval requests are routed for review on this turn and subsequent turns.",
+    }),
+  ),
+  cwd: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Override the working directory for this turn and subsequent turns.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  effort: Schema.optionalKey(
+    Schema.Union([V2TurnStartParams__ReasoningEffort, Schema.Null]).annotate({
+      description: "Override the reasoning effort for this turn and subsequent turns.",
+    }),
+  ),
+  input: Schema.Array(V2TurnStartParams__UserInput),
+  model: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Override the model for this turn and subsequent turns.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  outputSchema: Schema.optionalKey(
+    Schema.Unknown.annotate({
+      description:
+        "Optional JSON Schema used to constrain the final assistant message for this turn.",
+    }),
+  ),
+  personality: Schema.optionalKey(
+    Schema.Union([V2TurnStartParams__Personality, Schema.Null]).annotate({
+      description: "Override the personality for this turn and subsequent turns.",
+    }),
+  ),
+  sandboxPolicy: Schema.optionalKey(
+    Schema.Union([V2TurnStartParams__SandboxPolicy, Schema.Null]).annotate({
+      description: "Override the sandbox policy for this turn and subsequent turns.",
+    }),
+  ),
+  serviceTier: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Override the service tier for this turn and subsequent turns.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+  summary: Schema.optionalKey(
+    Schema.Union([V2TurnStartParams__ReasoningSummary, Schema.Null]).annotate({
+      description: "Override the reasoning summary for this turn and subsequent turns.",
+    }),
+  ),
+  threadId: Schema.String,
+}).annotate({ title: "TurnStartParams" });
+
+export type V2TurnStartParams__ByteRange = { readonly end: number; readonly start: number };
+export const V2TurnStartParams__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2TurnStartParams__CollaborationMode = {
+  readonly mode: V2TurnStartParams__ModeKind;
+  readonly settings: V2TurnStartParams__Settings;
+};
+export const V2TurnStartParams__CollaborationMode = Schema.Struct({
+  mode: V2TurnStartParams__ModeKind,
+  settings: V2TurnStartParams__Settings,
+}).annotate({ description: "Collaboration mode for a Codex session." });
+
+export type V2TurnStartParams__NetworkAccess = "restricted" | "enabled";
+export const V2TurnStartParams__NetworkAccess = Schema.Literals(["restricted", "enabled"]);
+
+export type V2TurnStartParams__PermissionProfileSelectionParams = {
+  readonly id: string;
+  readonly modifications?: ReadonlyArray<V2TurnStartParams__PermissionProfileModificationParams> | null;
+  readonly type: "profile";
+};
+export const V2TurnStartParams__PermissionProfileSelectionParams = Schema.Union(
+  [
+    Schema.Struct({
+      id: Schema.String,
+      modifications: Schema.optionalKey(
+        Schema.Union([
+          Schema.Array(V2TurnStartParams__PermissionProfileModificationParams),
+          Schema.Null,
+        ]),
+      ),
+      type: Schema.Literal("profile").annotate({
+        title: "ProfilePermissionProfileSelectionParamsType",
+      }),
+    }).annotate({
+      title: "ProfilePermissionProfileSelectionParams",
+      description:
+        "Select a named built-in or user-defined profile and optionally apply bounded modifications that Codex knows how to validate.",
+    }),
+  ],
+  { mode: "oneOf" },
+);
+
+export type V2TurnStartParams__TurnEnvironmentParams = {
+  readonly cwd: V2TurnStartParams__AbsolutePathBuf;
+  readonly environmentId: string;
+};
+export const V2TurnStartParams__TurnEnvironmentParams = Schema.Struct({
+  cwd: V2TurnStartParams__AbsolutePathBuf,
+  environmentId: Schema.String,
+});
+
+export type V2TurnStartResponse = { readonly turn: V2TurnStartResponse__Turn };
+export const V2TurnStartResponse = Schema.Struct({ turn: V2TurnStartResponse__Turn }).annotate({
+  title: "TurnStartResponse",
+});
+
+export type V2TurnStartResponse__ByteRange = { readonly end: number; readonly start: number };
+export const V2TurnStartResponse__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2TurnStartResponse__CollabAgentTool =
+  | "spawnAgent"
+  | "sendInput"
+  | "resumeAgent"
+  | "wait"
+  | "closeAgent";
+export const V2TurnStartResponse__CollabAgentTool = Schema.Literals([
+  "spawnAgent",
+  "sendInput",
+  "resumeAgent",
+  "wait",
+  "closeAgent",
+]);
+
+export type V2TurnStartResponse__CollabAgentToolCallStatus = "inProgress" | "completed" | "failed";
+export const V2TurnStartResponse__CollabAgentToolCallStatus = Schema.Literals([
+  "inProgress",
+  "completed",
+  "failed",
+]);
+
+export type V2TurnStartResponse__CommandExecutionSource =
+  | "agent"
+  | "userShell"
+  | "unifiedExecStartup"
+  | "unifiedExecInteraction";
+export const V2TurnStartResponse__CommandExecutionSource = Schema.Literals([
+  "agent",
+  "userShell",
+  "unifiedExecStartup",
+  "unifiedExecInteraction",
+]);
+
+export type V2TurnStartResponse__TurnItemsView = "notLoaded" | "summary" | "full";
+export const V2TurnStartResponse__TurnItemsView = Schema.Literals(["notLoaded", "summary", "full"]);
+
+export type V2TurnSteerParams = {
+  readonly expectedTurnId: string;
+  readonly input: ReadonlyArray<V2TurnSteerParams__UserInput>;
+  readonly threadId: string;
+};
+export const V2TurnSteerParams = Schema.Struct({
+  expectedTurnId: Schema.String.annotate({
+    description:
+      "Required active turn id precondition. The request fails when it does not match the currently active turn.",
+  }),
+  input: Schema.Array(V2TurnSteerParams__UserInput),
+  threadId: Schema.String,
+}).annotate({ title: "TurnSteerParams" });
+
+export type V2TurnSteerParams__ByteRange = { readonly end: number; readonly start: number };
+export const V2TurnSteerParams__ByteRange = Schema.Struct({
+  end: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  start: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+});
+
+export type V2TurnSteerResponse = { readonly turnId: string };
+export const V2TurnSteerResponse = Schema.Struct({ turnId: Schema.String }).annotate({
+  title: "TurnSteerResponse",
+});
+
+export type V2WarningNotification = { readonly message: string; readonly threadId?: string | null };
+export const V2WarningNotification = Schema.Struct({
+  message: Schema.String.annotate({ description: "Concise warning message for the user." }),
+  threadId: Schema.optionalKey(
+    Schema.Union([
+      Schema.String.annotate({
+        description: "Optional thread target when the warning applies to a specific thread.",
+      }),
+      Schema.Null,
+    ]),
+  ),
+}).annotate({ title: "WarningNotification" });
+
+export type V2WindowsSandboxReadinessResponse = {
+  readonly status: V2WindowsSandboxReadinessResponse__WindowsSandboxReadiness;
+};
+export const V2WindowsSandboxReadinessResponse = Schema.Struct({
+  status: V2WindowsSandboxReadinessResponse__WindowsSandboxReadiness,
+}).annotate({ title: "WindowsSandboxReadinessResponse" });
+
+export type V2WindowsSandboxSetupCompletedNotification = {
+  readonly error?: string | null;
+  readonly mode: V2WindowsSandboxSetupCompletedNotification__WindowsSandboxSetupMode;
+  readonly success: boolean;
+};
+export const V2WindowsSandboxSetupCompletedNotification = Schema.Struct({
+  error: Schema.optionalKey(Schema.Union([Schema.String, Schema.Null])),
+  mode: V2WindowsSandboxSetupCompletedNotification__WindowsSandboxSetupMode,
+  success: Schema.Boolean,
+}).annotate({ title: "WindowsSandboxSetupCompletedNotification" });
+
+export type V2WindowsSandboxSetupStartParams = {
+  readonly cwd?: V2WindowsSandboxSetupStartParams__AbsolutePathBuf | null;
+  readonly mode: V2WindowsSandboxSetupStartParams__WindowsSandboxSetupMode;
+};
+export const V2WindowsSandboxSetupStartParams = Schema.Struct({
+  cwd: Schema.optionalKey(
+    Schema.Union([V2WindowsSandboxSetupStartParams__AbsolutePathBuf, Schema.Null]),
+  ),
+  mode: V2WindowsSandboxSetupStartParams__WindowsSandboxSetupMode,
+}).annotate({ title: "WindowsSandboxSetupStartParams" });
+
+export type V2WindowsSandboxSetupStartResponse = { readonly started: boolean };
+export const V2WindowsSandboxSetupStartResponse = Schema.Struct({
+  started: Schema.Boolean,
+}).annotate({ title: "WindowsSandboxSetupStartResponse" });
+
+export type V2WindowsWorldWritableWarningNotification = {
+  readonly extraCount: number;
+  readonly failedScan: boolean;
+  readonly samplePaths: ReadonlyArray<string>;
+};
+export const V2WindowsWorldWritableWarningNotification = Schema.Struct({
+  extraCount: Schema.Number.annotate({ format: "uint" })
+    .check(Schema.isInt())
+    .check(Schema.isGreaterThanOrEqualTo(0)),
+  failedScan: Schema.Boolean,
+  samplePaths: Schema.Array(Schema.String),
+}).annotate({ title: "WindowsWorldWritableWarningNotification" });
diff --git a/packages/effect-codex-app-server/src/_internal/shared.ts b/packages/effect-codex-app-server/src/_internal/shared.ts
new file mode 100644
index 00000000000..99fe8e5360b
--- /dev/null
+++ b/packages/effect-codex-app-server/src/_internal/shared.ts
@@ -0,0 +1,101 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+
+import * as CodexError from "../errors.ts";
+
+const formatSchemaIssue = SchemaIssue.makeFormatterDefault();
+
+export const JsonRpcId = Schema.Union([Schema.Number, Schema.String]);
+
+export const JsonRpcError = Schema.Struct({
+  code: Schema.Number,
+  message: Schema.String,
+  data: Schema.optional(Schema.Unknown),
+});
+
+export const JsonRpcResponseEnvelope = Schema.Struct({
+  id: JsonRpcId,
+  result: Schema.optional(Schema.Unknown),
+  error: Schema.optional(JsonRpcError),
+});
+
+export const decodeOptionalPayload = <A, I>(
+  method: string,
+  schema: Schema.Codec<A, I> | undefined,
+  raw: unknown,
+): Effect.Effect<A, CodexError.CodexAppServerRequestError> => {
+  if (!schema) {
+    if (raw === undefined) {
+      return Effect.sync(() => undefined as A);
+    }
+    return Effect.fail(
+      CodexError.CodexAppServerRequestError.invalidParams(`${method} does not accept params`, raw),
+    );
+  }
+
+  return Schema.decodeUnknownEffect(schema)(raw).pipe(
+    Effect.mapError((error) =>
+      CodexError.CodexAppServerRequestError.invalidParams(
+        `Invalid ${method} payload: ${formatSchemaIssue(error.issue)}`,
+        { issue: error.issue },
+      ),
+    ),
+  );
+};
+
+export const encodeOptionalPayload = <A, I>(
+  method: string,
+  schema: Schema.Codec<A, I> | undefined,
+  payload: A,
+): Effect.Effect<I | undefined, CodexError.CodexAppServerRequestError> => {
+  if (!schema) {
+    if (payload === undefined) {
+      return Effect.sync(() => undefined);
+    }
+    return Effect.fail(
+      CodexError.CodexAppServerRequestError.invalidParams(
+        `${method} does not accept params`,
+        payload,
+      ),
+    );
+  }
+
+  return Schema.encodeEffect(schema)(payload).pipe(
+    Effect.mapError((error) =>
+      CodexError.CodexAppServerRequestError.invalidParams(
+        `Invalid ${method} payload: ${formatSchemaIssue(error.issue)}`,
+        { issue: error.issue },
+      ),
+    ),
+  );
+};
+
+export const decodeNotificationPayload = <A, I>(
+  method: string,
+  schema: Schema.Codec<A, I> | undefined,
+  raw: unknown,
+): Effect.Effect<A, CodexError.CodexAppServerProtocolParseError> =>
+  decodeOptionalPayload(method, schema, raw).pipe(
+    Effect.mapError(
+      (error) =>
+        new CodexError.CodexAppServerProtocolParseError({
+          detail: error.message,
+          cause: error,
+        }),
+    ),
+  );
+
+export const runHandler = Effect.fnUntraced(function* <A, B>(
+  handler: ((payload: A) => Effect.Effect<B, CodexError.CodexAppServerError>) | undefined,
+  payload: A,
+  method: string,
+) {
+  if (!handler) {
+    return yield* CodexError.CodexAppServerRequestError.methodNotFound(method);
+  }
+
+  return yield* handler(payload).pipe(
+    Effect.mapError((error) => CodexError.normalizeToRequestError(error)),
+  );
+});
diff --git a/packages/effect-codex-app-server/src/_internal/stdio.ts b/packages/effect-codex-app-server/src/_internal/stdio.ts
new file mode 100644
index 00000000000..ced07fb53e2
--- /dev/null
+++ b/packages/effect-codex-app-server/src/_internal/stdio.ts
@@ -0,0 +1,57 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+import * as Sink from "effect/Sink";
+import * as Stdio from "effect/Stdio";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import * as CodexError from "../errors.ts";
+
+const encoder = new TextEncoder();
+
+export const makeChildStdio = (handle: ChildProcessSpawner.ChildProcessHandle) =>
+  Stdio.make({
+    args: Effect.succeed([]),
+    stdin: handle.stdout,
+    stdout: () =>
+      Sink.mapInput(handle.stdin, (chunk: string | Uint8Array) =>
+        typeof chunk === "string" ? encoder.encode(chunk) : chunk,
+      ),
+    stderr: () => Sink.drain,
+  });
+
+export const makeInMemoryStdio = Effect.fn("makeInMemoryStdio")(function* () {
+  const input = yield* Queue.unbounded<Uint8Array, Cause.Done<void>>();
+  const output = yield* Queue.unbounded<string>();
+  const decoder = new TextDecoder();
+
+  return {
+    stdio: Stdio.make({
+      args: Effect.succeed([]),
+      stdin: Stream.fromQueue(input),
+      stdout: () =>
+        Sink.forEach((chunk: string | Uint8Array) =>
+          Queue.offer(
+            output,
+            typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }),
+          ),
+        ),
+      stderr: () => Sink.drain,
+    }),
+    input,
+    output,
+  };
+});
+
+export const makeTerminationError = (
+  handle: ChildProcessSpawner.ChildProcessHandle,
+): Effect.Effect<CodexError.CodexAppServerError> =>
+  Effect.match(handle.exitCode, {
+    onFailure: (cause) =>
+      new CodexError.CodexAppServerTransportError({
+        detail: "Failed to determine Codex App Server process exit status",
+        cause,
+      }),
+    onSuccess: (code) => new CodexError.CodexAppServerProcessExitedError({ code }),
+  });
diff --git a/packages/effect-codex-app-server/src/client.test.ts b/packages/effect-codex-app-server/src/client.test.ts
new file mode 100644
index 00000000000..0e0127b1a94
--- /dev/null
+++ b/packages/effect-codex-app-server/src/client.test.ts
@@ -0,0 +1,154 @@
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+
+import * as CodexClient from "./client.ts";
+
+const mockPeerPath = Effect.map(Effect.service(Path.Path), (path) =>
+  path.join(import.meta.dirname, "../test/fixtures/codex-app-server-mock-peer.ts"),
+);
+
+it.layer(NodeServices.layer)("effect-codex-app-server client", (it) => {
+  const makeHandle = () =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const path = yield* Path.Path;
+      const command = ChildProcess.make("bun", ["run", yield* mockPeerPath], {
+        cwd: path.join(import.meta.dirname, ".."),
+        shell: process.platform === "win32",
+      });
+      return yield* spawner.spawn(command);
+    });
+
+  it.effect("initializes, handles typed server requests, and reads account and skills data", () =>
+    Effect.gen(function* () {
+      const userInputRequests = yield* Ref.make<Array<unknown>>([]);
+      const messageDeltas = yield* Ref.make<Array<unknown>>([]);
+      const handle = yield* makeHandle();
+      const scope = yield* Scope.make();
+      const clientLayer = CodexClient.layerChildProcess(handle);
+      const context = yield* Layer.buildWithScope(clientLayer, scope);
+
+      const result = yield* Effect.gen(function* () {
+        const client = yield* CodexClient.CodexAppServerClient;
+
+        yield* client.handleServerRequest("item/tool/requestUserInput", (payload) =>
+          Ref.update(userInputRequests, (current) => [...current, payload]).pipe(
+            Effect.as({
+              answers: {
+                approved: {
+                  answers: ["yes"],
+                },
+              },
+            }),
+          ),
+        );
+
+        yield* client.handleServerNotification("item/agentMessage/delta", (payload) =>
+          Ref.update(messageDeltas, (current) => [...current, payload]),
+        );
+
+        const initialized = yield* client.request("initialize", {
+          clientInfo: {
+            name: "effect-codex-app-server-test",
+            title: "Effect Codex App Server Test",
+            version: "0.0.0",
+          },
+          capabilities: {
+            experimentalApi: true,
+            optOutNotificationMethods: null,
+          },
+        });
+        assert.equal(initialized.userAgent, "mock-codex-app-server");
+
+        yield* client.notify("initialized", undefined);
+
+        const account = yield* client.request("account/read", {});
+        assert.equal(account.requiresOpenaiAuth, false);
+        assert.deepEqual(account.account, {
+          type: "chatgpt",
+          email: "mock@example.com",
+          planType: "plus",
+        });
+
+        const skills = yield* client.request("skills/list", {
+          cwds: [process.cwd()],
+        });
+        assert.equal(skills.data.length, 1);
+        assert.equal(skills.data[0]?.cwd, process.cwd());
+
+        return {
+          account,
+          skills,
+        };
+      }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+
+      assert.equal(result.skills.data[0]?.skills.length, 0);
+      assert.deepEqual(yield* Ref.get(userInputRequests), [
+        {
+          itemId: "item-approval-1",
+          threadId: "thread-1",
+          turnId: "turn-1",
+          questions: [
+            {
+              id: "approved",
+              header: "Approve",
+              question: "Continue with the mock skills request?",
+              options: [
+                {
+                  label: "yes",
+                  description: "Approve the request",
+                },
+              ],
+            },
+          ],
+        },
+      ]);
+      assert.deepEqual(yield* Ref.get(messageDeltas), [
+        {
+          delta: "Mock server is ready.",
+          itemId: "item-1",
+          threadId: "thread-1",
+          turnId: "turn-1",
+        },
+      ]);
+    }),
+  );
+
+  it.effect("initializes a command-backed app-server client", () =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const scope = yield* Scope.make();
+      const clientLayer = CodexClient.layerCommand({
+        command: "bun",
+        args: ["run", yield* mockPeerPath],
+        cwd: path.join(import.meta.dirname, ".."),
+      });
+      const context = yield* Layer.buildWithScope(clientLayer, scope);
+
+      const initialized = yield* Effect.gen(function* () {
+        const client = yield* CodexClient.CodexAppServerClient;
+        return yield* client.request("initialize", {
+          clientInfo: {
+            name: "effect-codex-app-server-test",
+            title: "Effect Codex App Server Test",
+            version: "0.0.0",
+          },
+          capabilities: {
+            experimentalApi: true,
+            optOutNotificationMethods: null,
+          },
+        });
+      }).pipe(Effect.provide(context), Effect.ensuring(Scope.close(scope, Exit.void)));
+
+      assert.equal(initialized.userAgent, "mock-codex-app-server");
+    }),
+  );
+});
diff --git a/packages/effect-codex-app-server/src/client.ts b/packages/effect-codex-app-server/src/client.ts
new file mode 100644
index 00000000000..18a9ed9316c
--- /dev/null
+++ b/packages/effect-codex-app-server/src/client.ts
@@ -0,0 +1,300 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stdio from "effect/Stdio";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import * as CodexRpc from "./_generated/meta.gen.ts";
+import * as CodexError from "./errors.ts";
+import * as CodexProtocol from "./protocol.ts";
+import {
+  decodeNotificationPayload,
+  decodeOptionalPayload,
+  encodeOptionalPayload,
+  runHandler,
+} from "./_internal/shared.ts";
+import { makeChildStdio, makeTerminationError } from "./_internal/stdio.ts";
+
+const DEFAULT_APP_SERVER_FORCE_KILL_AFTER = "2 seconds" as const;
+
+export interface CodexAppServerClientOptions {
+  readonly logIncoming?: boolean;
+  readonly logOutgoing?: boolean;
+  readonly logger?: (
+    event: CodexProtocol.CodexAppServerProtocolLogEvent,
+  ) => Effect.Effect<void, never>;
+}
+
+interface CodexAppServerClientRaw {
+  readonly notifications: CodexProtocol.CodexAppServerPatchedProtocol["incomingNotifications"];
+  readonly requests: CodexProtocol.CodexAppServerPatchedProtocol["incomingRequests"];
+  readonly request: CodexProtocol.CodexAppServerPatchedProtocol["request"];
+  readonly notify: CodexProtocol.CodexAppServerPatchedProtocol["notify"];
+  readonly respond: CodexProtocol.CodexAppServerPatchedProtocol["respond"];
+  readonly respondError: CodexProtocol.CodexAppServerPatchedProtocol["respondError"];
+}
+
+export interface CodexAppServerClientShape {
+  readonly raw: CodexAppServerClientRaw;
+  readonly request: <M extends CodexRpc.ClientRequestMethod>(
+    method: M,
+    payload: CodexRpc.ClientRequestParamsByMethod[M],
+  ) => Effect.Effect<CodexRpc.ClientRequestResponsesByMethod[M], CodexError.CodexAppServerError>;
+  readonly notify: <M extends CodexRpc.ClientNotificationMethod>(
+    method: M,
+    payload: CodexRpc.ClientNotificationParamsByMethod[M],
+  ) => Effect.Effect<void, CodexError.CodexAppServerError>;
+  readonly handleServerRequest: <M extends CodexRpc.ServerRequestMethod>(
+    method: M,
+    handler: (
+      payload: CodexRpc.ServerRequestParamsByMethod[M],
+    ) => Effect.Effect<CodexRpc.ServerRequestResponsesByMethod[M], CodexError.CodexAppServerError>,
+  ) => Effect.Effect<void>;
+  readonly handleServerNotification: <M extends CodexRpc.ServerNotificationMethod>(
+    method: M,
+    handler: (
+      payload: CodexRpc.ServerNotificationParamsByMethod[M],
+    ) => Effect.Effect<void, CodexError.CodexAppServerError>,
+  ) => Effect.Effect<void>;
+  readonly handleUnknownServerRequest: (
+    handler: (
+      method: string,
+      params: unknown,
+    ) => Effect.Effect<unknown, CodexError.CodexAppServerError>,
+  ) => Effect.Effect<void>;
+  readonly handleUnknownServerNotification: (
+    handler: (
+      method: string,
+      params: unknown,
+    ) => Effect.Effect<void, CodexError.CodexAppServerError>,
+  ) => Effect.Effect<void>;
+}
+
+export class CodexAppServerClient extends Context.Service<
+  CodexAppServerClient,
+  CodexAppServerClientShape
+>()("effect-codex-app-server/CodexAppServerClient") {}
+
+type ServerRequestHandler = (
+  payload: unknown,
+) => Effect.Effect<unknown, CodexError.CodexAppServerError>;
+type ServerNotificationHandler = (
+  payload: unknown,
+) => Effect.Effect<void, CodexError.CodexAppServerError>;
+
+export const make = Effect.fn("effect-codex-app-server/CodexAppServerClient.make")(function* (
+  stdio: Stdio.Stdio,
+  options: CodexAppServerClientOptions = {},
+  terminationError?: Effect.Effect<CodexError.CodexAppServerError>,
+): Effect.fn.Return<CodexAppServerClientShape, never, Scope.Scope> {
+  const requestHandlers = new Map<string, ServerRequestHandler>();
+  const notificationHandlers = new Map<string, Array<ServerNotificationHandler>>();
+  let unknownRequestHandler:
+    | ((method: string, params: unknown) => Effect.Effect<unknown, CodexError.CodexAppServerError>)
+    | undefined;
+  let unknownNotificationHandler:
+    | ((method: string, params: unknown) => Effect.Effect<void, CodexError.CodexAppServerError>)
+    | undefined;
+
+  const getServerRequestParamSchema = <M extends CodexRpc.ServerRequestMethod>(
+    method: M,
+  ):
+    | Schema.Codec<CodexRpc.ServerRequestParamsByMethod[M], CodexRpc.ServerRequestParamsByMethod[M]>
+    | undefined => CodexRpc.SERVER_REQUEST_PARAMS[method] as never;
+
+  const getServerRequestResponseSchema = <M extends CodexRpc.ServerRequestMethod>(
+    method: M,
+  ):
+    | Schema.Codec<
+        CodexRpc.ServerRequestResponsesByMethod[M],
+        CodexRpc.ServerRequestResponsesByMethod[M]
+      >
+    | undefined => CodexRpc.SERVER_REQUEST_RESPONSES[method] as never;
+
+  const getClientRequestParamSchema = <M extends CodexRpc.ClientRequestMethod>(
+    method: M,
+  ):
+    | Schema.Codec<CodexRpc.ClientRequestParamsByMethod[M], CodexRpc.ClientRequestParamsByMethod[M]>
+    | undefined => CodexRpc.CLIENT_REQUEST_PARAMS[method] as never;
+
+  const getClientRequestResponseSchema = <M extends CodexRpc.ClientRequestMethod>(
+    method: M,
+  ):
+    | Schema.Codec<
+        CodexRpc.ClientRequestResponsesByMethod[M],
+        CodexRpc.ClientRequestResponsesByMethod[M]
+      >
+    | undefined => CodexRpc.CLIENT_REQUEST_RESPONSES[method] as never;
+
+  const getClientNotificationParamSchema = <M extends CodexRpc.ClientNotificationMethod>(
+    method: M,
+  ):
+    | Schema.Codec<
+        CodexRpc.ClientNotificationParamsByMethod[M],
+        CodexRpc.ClientNotificationParamsByMethod[M]
+      >
+    | undefined => CodexRpc.CLIENT_NOTIFICATION_PARAMS[method] as never;
+
+  const dispatchNotification = (
+    notification: CodexProtocol.CodexAppServerIncomingNotification,
+  ): Effect.Effect<void, never> => {
+    const schema =
+      notification.method in CodexRpc.SERVER_NOTIFICATION_PARAMS
+        ? CodexRpc.SERVER_NOTIFICATION_PARAMS[
+            notification.method as CodexRpc.ServerNotificationMethod
+          ]
+        : undefined;
+    const handlers = notificationHandlers.get(notification.method) ?? [];
+
+    if (schema) {
+      return decodeNotificationPayload(notification.method, schema, notification.params).pipe(
+        Effect.flatMap((decoded) =>
+          Effect.forEach(handlers, (handler) => handler(decoded), { discard: true }),
+        ),
+        Effect.catch(() => Effect.void),
+      );
+    }
+
+    return unknownNotificationHandler
+      ? unknownNotificationHandler(notification.method, notification.params).pipe(
+          Effect.catch(() => Effect.void),
+        )
+      : Effect.void;
+  };
+
+  const dispatchRequest = (
+    request: CodexProtocol.CodexAppServerIncomingRequest,
+  ): Effect.Effect<unknown, CodexError.CodexAppServerError> => {
+    if (request.method in CodexRpc.SERVER_REQUEST_PARAMS) {
+      const method = request.method as CodexRpc.ServerRequestMethod;
+      const payloadSchema = getServerRequestParamSchema(method);
+      const responseSchema = getServerRequestResponseSchema(method);
+      const handler = requestHandlers.get(method);
+
+      return decodeOptionalPayload(method, payloadSchema, request.params).pipe(
+        Effect.flatMap((decoded) => runHandler(handler, decoded, method)),
+        Effect.flatMap((result) => encodeOptionalPayload(method, responseSchema, result)),
+      );
+    }
+
+    return unknownRequestHandler
+      ? unknownRequestHandler(request.method, request.params)
+      : Effect.fail(CodexError.CodexAppServerRequestError.methodNotFound(request.method));
+  };
+
+  const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({
+    stdio,
+    ...(terminationError ? { terminationError } : {}),
+    ...(options.logIncoming !== undefined ? { logIncoming: options.logIncoming } : {}),
+    ...(options.logOutgoing !== undefined ? { logOutgoing: options.logOutgoing } : {}),
+    ...(options.logger ? { logger: options.logger } : {}),
+    onNotification: dispatchNotification,
+    onRequest: dispatchRequest,
+  });
+
+  const request = <M extends CodexRpc.ClientRequestMethod>(
+    method: M,
+    payload: CodexRpc.ClientRequestParamsByMethod[M],
+  ): Effect.Effect<CodexRpc.ClientRequestResponsesByMethod[M], CodexError.CodexAppServerError> =>
+    encodeOptionalPayload(method, getClientRequestParamSchema(method), payload).pipe(
+      Effect.flatMap((encoded) => transport.request(method, encoded)),
+      Effect.flatMap(
+        (
+          raw,
+        ): Effect.Effect<
+          CodexRpc.ClientRequestResponsesByMethod[M],
+          CodexError.CodexAppServerError
+        > => decodeOptionalPayload(method, getClientRequestResponseSchema(method), raw),
+      ),
+    );
+
+  const notify = <M extends CodexRpc.ClientNotificationMethod>(
+    method: M,
+    payload: CodexRpc.ClientNotificationParamsByMethod[M],
+  ) =>
+    encodeOptionalPayload(method, getClientNotificationParamSchema(method), payload).pipe(
+      Effect.flatMap((encoded) => transport.notify(method, encoded)),
+    );
+
+  return CodexAppServerClient.of({
+    raw: {
+      notifications: transport.incomingNotifications,
+      requests: transport.incomingRequests,
+      request: transport.request,
+      notify: transport.notify,
+      respond: transport.respond,
+      respondError: transport.respondError,
+    },
+    request,
+    notify,
+    handleServerRequest: (method, handler) =>
+      Effect.sync(() => {
+        requestHandlers.set(method, handler as ServerRequestHandler);
+      }),
+    handleServerNotification: (method, handler) =>
+      Effect.sync(() => {
+        const current = notificationHandlers.get(method) ?? [];
+        current.push(handler as ServerNotificationHandler);
+        notificationHandlers.set(method, current);
+      }),
+    handleUnknownServerRequest: (handler) =>
+      Effect.sync(() => {
+        unknownRequestHandler = handler;
+      }),
+    handleUnknownServerNotification: (handler) =>
+      Effect.sync(() => {
+        unknownNotificationHandler = handler;
+      }),
+  });
+});
+
+export const layerChildProcess = (
+  handle: ChildProcessSpawner.ChildProcessHandle,
+  options: CodexAppServerClientOptions = {},
+): Layer.Layer<CodexAppServerClient> => {
+  const stdio = makeChildStdio(handle);
+  const terminationError = makeTerminationError(handle);
+  return Layer.effect(CodexAppServerClient, make(stdio, options, terminationError));
+};
+
+export interface CodexAppServerCommandLayerOptions extends CodexAppServerClientOptions {
+  readonly command: string;
+  readonly args?: ReadonlyArray<string>;
+  readonly cwd?: string;
+  readonly env?: Record<string, string>;
+}
+
+export const layerCommand = (
+  options: CodexAppServerCommandLayerOptions,
+): Layer.Layer<
+  CodexAppServerClient,
+  CodexError.CodexAppServerSpawnError,
+  ChildProcessSpawner.ChildProcessSpawner
+> =>
+  Layer.effect(
+    CodexAppServerClient,
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const command = ChildProcess.make(options.command, [...(options.args ?? [])], {
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
+        forceKillAfter: DEFAULT_APP_SERVER_FORCE_KILL_AFTER,
+        shell: process.platform === "win32",
+      });
+      return yield* spawner.spawn(command).pipe(
+        Effect.mapError(
+          (cause) =>
+            new CodexError.CodexAppServerSpawnError({
+              command: [options.command, ...(options.args ?? [])].join(" "),
+              cause,
+            }),
+        ),
+      );
+    }).pipe(
+      Effect.flatMap((handle) =>
+        make(makeChildStdio(handle), options, makeTerminationError(handle)),
+      ),
+    ),
+  );
diff --git a/packages/effect-codex-app-server/src/errors.ts b/packages/effect-codex-app-server/src/errors.ts
new file mode 100644
index 00000000000..930dd68c3ed
--- /dev/null
+++ b/packages/effect-codex-app-server/src/errors.ts
@@ -0,0 +1,152 @@
+import * as Schema from "effect/Schema";
+
+export interface CodexAppServerProtocolErrorShape {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: unknown;
+}
+
+export class CodexAppServerSpawnError extends Schema.TaggedErrorClass<CodexAppServerSpawnError>()(
+  "CodexAppServerSpawnError",
+  {
+    command: Schema.optional(Schema.String),
+    cause: Schema.Defect,
+  },
+) {
+  override get message() {
+    return this.command
+      ? `Failed to spawn Codex App Server process for command: ${this.command}`
+      : "Failed to spawn Codex App Server process";
+  }
+}
+
+export class CodexAppServerProcessExitedError extends Schema.TaggedErrorClass<CodexAppServerProcessExitedError>()(
+  "CodexAppServerProcessExitedError",
+  {
+    code: Schema.optional(Schema.Number),
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message() {
+    return this.code === undefined
+      ? "Codex App Server process exited"
+      : `Codex App Server process exited with code ${this.code}`;
+  }
+}
+
+export class CodexAppServerProtocolParseError extends Schema.TaggedErrorClass<CodexAppServerProtocolParseError>()(
+  "CodexAppServerProtocolParseError",
+  {
+    detail: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {
+  override get message() {
+    return `Failed to parse Codex App Server protocol message: ${this.detail}`;
+  }
+}
+
+export class CodexAppServerTransportError extends Schema.TaggedErrorClass<CodexAppServerTransportError>()(
+  "CodexAppServerTransportError",
+  {
+    detail: Schema.String,
+    cause: Schema.Defect,
+  },
+) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+export class CodexAppServerRequestError extends Schema.TaggedErrorClass<CodexAppServerRequestError>()(
+  "CodexAppServerRequestError",
+  {
+    code: Schema.Number,
+    errorMessage: Schema.String,
+    data: Schema.optional(Schema.Unknown),
+  },
+) {
+  override get message() {
+    return this.errorMessage;
+  }
+
+  static fromProtocolError(error: CodexAppServerProtocolErrorShape) {
+    return new CodexAppServerRequestError({
+      code: error.code,
+      errorMessage: error.message,
+      ...(error.data !== undefined ? { data: error.data } : {}),
+    });
+  }
+
+  static parseError(message = "Parse error", data?: unknown) {
+    return new CodexAppServerRequestError({
+      code: -32700,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static invalidRequest(message = "Invalid request", data?: unknown) {
+    return new CodexAppServerRequestError({
+      code: -32600,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static methodNotFound(method: string) {
+    return new CodexAppServerRequestError({
+      code: -32601,
+      errorMessage: `Method not found: ${method}`,
+    });
+  }
+
+  static invalidParams(message = "Invalid params", data?: unknown) {
+    return new CodexAppServerRequestError({
+      code: -32602,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static internalError(message = "Internal error", data?: unknown) {
+    return new CodexAppServerRequestError({
+      code: -32603,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  static overloaded(message = "Server overloaded; retry later.", data?: unknown) {
+    return new CodexAppServerRequestError({
+      code: -32001,
+      errorMessage: message,
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  toProtocolError(): CodexAppServerProtocolErrorShape {
+    return {
+      code: this.code,
+      message: this.errorMessage,
+      ...(this.data !== undefined ? { data: this.data } : {}),
+    };
+  }
+}
+
+export const CodexAppServerError = Schema.Union([
+  CodexAppServerRequestError,
+  CodexAppServerSpawnError,
+  CodexAppServerProcessExitedError,
+  CodexAppServerProtocolParseError,
+  CodexAppServerTransportError,
+]);
+
+export type CodexAppServerError = typeof CodexAppServerError.Type;
+const isCodexAppServerRequestError = Schema.is(CodexAppServerRequestError);
+
+export function normalizeToRequestError(error: CodexAppServerError): CodexAppServerRequestError {
+  return isCodexAppServerRequestError(error)
+    ? error
+    : CodexAppServerRequestError.internalError(error.message);
+}
diff --git a/packages/effect-codex-app-server/src/protocol.test.ts b/packages/effect-codex-app-server/src/protocol.test.ts
new file mode 100644
index 00000000000..2a1d964a9e6
--- /dev/null
+++ b/packages/effect-codex-app-server/src/protocol.test.ts
@@ -0,0 +1,201 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Queue from "effect/Queue";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+
+import * as CodexError from "./errors.ts";
+import * as CodexProtocol from "./protocol.ts";
+import { makeInMemoryStdio } from "./_internal/stdio.ts";
+const encodeUnknownJsonString = Schema.encodeUnknownSync(Schema.UnknownFromJsonString);
+
+const encoder = new TextEncoder();
+
+const encodeJsonl = (value: unknown) => encoder.encode(`${encodeUnknownJsonString(value)}\n`);
+
+const decodeJson = Schema.decodeEffect(Schema.UnknownFromJsonString);
+
+it.layer(NodeServices.layer)("effect-codex-app-server protocol", (it) => {
+  it.effect(
+    "encodes requests without a jsonrpc field and routes inbound requests and notifications",
+    () =>
+      Effect.gen(function* () {
+        const { stdio, input, output } = yield* makeInMemoryStdio();
+        const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({ stdio });
+
+        const notificationDeferred =
+          yield* Deferred.make<ReadonlyArray<CodexProtocol.CodexAppServerIncomingNotification>>();
+        const requestDeferred =
+          yield* Deferred.make<ReadonlyArray<CodexProtocol.CodexAppServerIncomingRequest>>();
+
+        yield* transport.incomingNotifications.pipe(
+          Stream.take(1),
+          Stream.runCollect,
+          Effect.flatMap((notifications) => Deferred.succeed(notificationDeferred, notifications)),
+          Effect.forkScoped,
+        );
+
+        yield* transport.incomingRequests.pipe(
+          Stream.take(1),
+          Stream.runCollect,
+          Effect.flatMap((requests) => Deferred.succeed(requestDeferred, requests)),
+          Effect.forkScoped,
+        );
+
+        yield* transport.notify("initialized");
+        assert.equal(yield* Queue.take(output), '{"method":"initialized"}\n');
+
+        const initializeParams = {
+          clientInfo: {
+            name: "effect-codex-app-server-test",
+            title: "Effect Codex App Server Test",
+            version: "0.0.0",
+          },
+          capabilities: {
+            experimentalApi: true,
+            optOutNotificationMethods: null,
+          },
+        };
+
+        const pendingInitialize = yield* transport
+          .request("initialize", initializeParams)
+          .pipe(Effect.forkScoped);
+        assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
+          id: 1,
+          method: "initialize",
+          params: initializeParams,
+        });
+
+        yield* Queue.offer(
+          input,
+          encodeJsonl({
+            method: "item/agentMessage/delta",
+            params: {
+              delta: "Hello from the mock peer.",
+              itemId: "item-1",
+              threadId: "thread-1",
+              turnId: "turn-1",
+            },
+          }),
+        );
+        yield* Queue.offer(
+          input,
+          encodeJsonl({
+            id: 77,
+            method: "item/tool/requestUserInput",
+            params: {
+              itemId: "item-approval-1",
+              threadId: "thread-1",
+              turnId: "turn-1",
+              questions: [
+                {
+                  id: "approved",
+                  header: "Approve",
+                  question: "Continue?",
+                },
+              ],
+            },
+          }),
+        );
+        yield* Queue.offer(
+          input,
+          encodeJsonl({
+            id: 1,
+            result: {
+              userAgent: "mock-codex-app-server",
+              codexHome: "/tmp/codex-home",
+              platformFamily: "unix",
+              platformOs: "macos",
+            },
+          }),
+        );
+
+        assert.deepEqual(yield* Fiber.join(pendingInitialize), {
+          userAgent: "mock-codex-app-server",
+          codexHome: "/tmp/codex-home",
+          platformFamily: "unix",
+          platformOs: "macos",
+        });
+        assert.deepEqual(yield* Deferred.await(notificationDeferred), [
+          {
+            method: "item/agentMessage/delta",
+            params: {
+              delta: "Hello from the mock peer.",
+              itemId: "item-1",
+              threadId: "thread-1",
+              turnId: "turn-1",
+            },
+          },
+        ]);
+        assert.deepEqual(yield* Deferred.await(requestDeferred), [
+          {
+            id: 77,
+            method: "item/tool/requestUserInput",
+            params: {
+              itemId: "item-approval-1",
+              threadId: "thread-1",
+              turnId: "turn-1",
+              questions: [
+                {
+                  id: "approved",
+                  header: "Approve",
+                  question: "Continue?",
+                },
+              ],
+            },
+          },
+        ]);
+
+        yield* transport.respond(77, {
+          answers: {
+            approved: {
+              answers: ["yes"],
+            },
+          },
+        });
+        assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
+          id: 77,
+          result: {
+            answers: {
+              approved: {
+                answers: ["yes"],
+              },
+            },
+          },
+        });
+
+        yield* transport.respondError(
+          78,
+          CodexError.CodexAppServerRequestError.methodNotFound("x/test"),
+        );
+        assert.deepEqual(yield* decodeJson(yield* Queue.take(output)), {
+          id: 78,
+          error: {
+            code: -32601,
+            message: "Method not found: x/test",
+          },
+        });
+      }),
+  );
+
+  it.effect("surfaces JSON encoding failures as protocol parse errors", () =>
+    Effect.gen(function* () {
+      const { stdio } = yield* makeInMemoryStdio();
+      const transport = yield* CodexProtocol.makeCodexAppServerPatchedProtocol({ stdio });
+
+      const bigintError = yield* transport.notify("x/test", 1n).pipe(Effect.flip);
+      assert.instanceOf(bigintError, CodexError.CodexAppServerProtocolParseError);
+      assert.equal(bigintError.detail, "Failed to encode Codex App Server message");
+
+      const circular: Record<string, unknown> = {};
+      circular.self = circular;
+      const circularError = yield* transport.notify("x/test", circular).pipe(Effect.flip);
+      assert.instanceOf(circularError, CodexError.CodexAppServerProtocolParseError);
+      assert.equal(circularError.detail, "Failed to encode Codex App Server message");
+    }),
+  );
+});
diff --git a/packages/effect-codex-app-server/src/protocol.ts b/packages/effect-codex-app-server/src/protocol.ts
new file mode 100644
index 00000000000..0fc2ce73c5c
--- /dev/null
+++ b/packages/effect-codex-app-server/src/protocol.ts
@@ -0,0 +1,406 @@
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import * as Schema from "effect/Schema";
+import * as Stdio from "effect/Stdio";
+import * as Stream from "effect/Stream";
+
+import * as CodexError from "./errors.ts";
+import { JsonRpcId, JsonRpcResponseEnvelope } from "./_internal/shared.ts";
+const isJsonRpcId = Schema.is(JsonRpcId);
+const isJsonRpcResponseEnvelope = Schema.is(JsonRpcResponseEnvelope);
+const isCodexAppServerError = Schema.is(CodexError.CodexAppServerError);
+
+export interface CodexAppServerProtocolLogEvent {
+  readonly direction: "incoming" | "outgoing";
+  readonly stage: "raw" | "decoded" | "decode_failed";
+  readonly payload: unknown;
+}
+
+export interface CodexAppServerIncomingNotification {
+  readonly method: string;
+  readonly params?: unknown;
+}
+
+export interface CodexAppServerIncomingRequest {
+  readonly id: string | number;
+  readonly method: string;
+  readonly params?: unknown;
+}
+
+export interface CodexAppServerPatchedProtocolOptions {
+  readonly stdio: Stdio.Stdio;
+  readonly terminationError?: Effect.Effect<CodexError.CodexAppServerError>;
+  readonly logIncoming?: boolean;
+  readonly logOutgoing?: boolean;
+  readonly logger?: (event: CodexAppServerProtocolLogEvent) => Effect.Effect<void, never>;
+  readonly onNotification?: (
+    notification: CodexAppServerIncomingNotification,
+  ) => Effect.Effect<void, never>;
+  readonly onRequest?: (
+    request: CodexAppServerIncomingRequest,
+  ) => Effect.Effect<unknown, CodexError.CodexAppServerError>;
+  readonly onTermination?: (error: CodexError.CodexAppServerError) => Effect.Effect<void, never>;
+}
+
+export interface CodexAppServerPatchedProtocol {
+  readonly incomingNotifications: Stream.Stream<CodexAppServerIncomingNotification>;
+  readonly incomingRequests: Stream.Stream<CodexAppServerIncomingRequest>;
+  readonly request: (
+    method: string,
+    payload?: unknown,
+  ) => Effect.Effect<unknown, CodexError.CodexAppServerError>;
+  readonly notify: (
+    method: string,
+    payload?: unknown,
+  ) => Effect.Effect<void, CodexError.CodexAppServerError>;
+  readonly respond: (
+    requestId: string | number,
+    result: unknown,
+  ) => Effect.Effect<void, CodexError.CodexAppServerError>;
+  readonly respondError: (
+    requestId: string | number,
+    error: CodexError.CodexAppServerRequestError,
+  ) => Effect.Effect<void, CodexError.CodexAppServerError>;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isIncomingRequest(value: unknown): value is CodexAppServerIncomingRequest {
+  if (!isObject(value) || typeof value.method !== "string") {
+    return false;
+  }
+  return isJsonRpcId(value.id);
+}
+
+function isIncomingNotification(value: unknown): value is CodexAppServerIncomingNotification {
+  return isObject(value) && typeof value.method === "string" && !("id" in value);
+}
+
+function isIncomingResponse(value: unknown): value is typeof JsonRpcResponseEnvelope.Type {
+  return isJsonRpcResponseEnvelope(value);
+}
+
+const encodeJsonString = Schema.encodeUnknownEffect(Schema.UnknownFromJsonString);
+const decodeJsonString = Schema.decodeUnknownEffect(Schema.UnknownFromJsonString);
+
+const encodeWireMessage = (
+  message: Record<string, unknown>,
+): Effect.Effect<string, CodexError.CodexAppServerProtocolParseError> =>
+  encodeJsonString(message).pipe(
+    Effect.map((encoded) => `${encoded}\n`),
+    Effect.mapError(
+      (cause) =>
+        new CodexError.CodexAppServerProtocolParseError({
+          detail: "Failed to encode Codex App Server message",
+          cause,
+        }),
+    ),
+  );
+
+const decodeWireMessage = (
+  line: string,
+): Effect.Effect<unknown, CodexError.CodexAppServerProtocolParseError> =>
+  decodeJsonString(line).pipe(
+    Effect.mapError(
+      (cause) =>
+        new CodexError.CodexAppServerProtocolParseError({
+          detail: "Failed to decode Codex App Server wire message",
+          cause,
+        }),
+    ),
+  );
+
+const normalizeIncomingError = (error: unknown, detail: string): CodexError.CodexAppServerError =>
+  isCodexAppServerError(error)
+    ? error
+    : new CodexError.CodexAppServerTransportError({
+        detail,
+        cause: error,
+      });
+
+const toProtocolMessage = (
+  requestId: string | number,
+  fields: {
+    readonly result?: unknown;
+    readonly error?: CodexError.CodexAppServerProtocolErrorShape;
+  },
+): { readonly [key: string]: unknown } => ({
+  id: requestId,
+  ...(fields.result !== undefined ? { result: fields.result } : {}),
+  ...(fields.error !== undefined ? { error: fields.error } : {}),
+});
+
+export const makeCodexAppServerPatchedProtocol = Effect.fn("makeCodexAppServerPatchedProtocol")(
+  function* (
+    options: CodexAppServerPatchedProtocolOptions,
+  ): Effect.fn.Return<CodexAppServerPatchedProtocol, never, Scope.Scope> {
+    const outgoing = yield* Queue.unbounded<string, Cause.Done<void>>();
+    const incomingNotifications = yield* Queue.unbounded<CodexAppServerIncomingNotification>();
+    const incomingRequests = yield* Queue.unbounded<CodexAppServerIncomingRequest>();
+    const pending = yield* Ref.make(
+      new Map<string, Deferred.Deferred<unknown, CodexError.CodexAppServerError>>(),
+    );
+    const nextRequestId = yield* Ref.make(1);
+    const remainder = yield* Ref.make("");
+    const terminationHandled = yield* Ref.make(false);
+
+    const logProtocol = (event: CodexAppServerProtocolLogEvent) => {
+      if (event.direction === "incoming" && !options.logIncoming) {
+        return Effect.void;
+      }
+      if (event.direction === "outgoing" && !options.logOutgoing) {
+        return Effect.void;
+      }
+      return (
+        options.logger?.(event) ??
+        Effect.logDebug("Codex App Server protocol event").pipe(Effect.annotateLogs({ event }))
+      );
+    };
+
+    const failAllPending = (error: CodexError.CodexAppServerError) =>
+      Ref.get(pending).pipe(
+        Effect.flatMap((current) =>
+          Effect.forEach([...current.values()], (deferred) => Deferred.fail(deferred, error), {
+            discard: true,
+          }),
+        ),
+        Effect.andThen(Ref.set(pending, new Map())),
+      );
+
+    const handleTermination = (classify: () => Effect.Effect<CodexError.CodexAppServerError>) =>
+      Ref.modify(terminationHandled, (handled) => {
+        if (handled) {
+          return [Effect.void, true] as const;
+        }
+        return [
+          Effect.gen(function* () {
+            const error = yield* classify();
+            yield* failAllPending(error);
+            yield* Queue.end(outgoing);
+            if (options.onTermination) {
+              yield* options.onTermination(error);
+            }
+          }),
+          true,
+        ] as const;
+      }).pipe(Effect.flatten);
+
+    const offerOutgoing = (message: Record<string, unknown>) =>
+      Effect.gen(function* () {
+        yield* logProtocol({
+          direction: "outgoing",
+          stage: "decoded",
+          payload: message,
+        });
+        const encoded = yield* encodeWireMessage(message);
+        yield* logProtocol({
+          direction: "outgoing",
+          stage: "raw",
+          payload: encoded,
+        });
+        yield* Queue.offer(outgoing, encoded).pipe(Effect.asVoid);
+      });
+
+    const removePending = (requestId: string) =>
+      Ref.update(pending, (current) => {
+        if (!current.has(requestId)) {
+          return current;
+        }
+        const next = new Map(current);
+        next.delete(requestId);
+        return next;
+      });
+
+    const resolvePending = (
+      requestId: string,
+      handler: (
+        deferred: Deferred.Deferred<unknown, CodexError.CodexAppServerError>,
+      ) => Effect.Effect<void>,
+    ) =>
+      Ref.modify(pending, (current) => {
+        const deferred = current.get(requestId);
+        if (!deferred) {
+          return [Effect.void, current] as const;
+        }
+        const next = new Map(current);
+        next.delete(requestId);
+        return [handler(deferred), next] as const;
+      }).pipe(Effect.flatten);
+
+    const respond = (requestId: string | number, result: unknown) =>
+      offerOutgoing(toProtocolMessage(requestId, { result }));
+
+    const respondError = (
+      requestId: string | number,
+      error: CodexError.CodexAppServerRequestError,
+    ) => offerOutgoing(toProtocolMessage(requestId, { error: error.toProtocolError() }));
+
+    const handleResponse = (response: typeof JsonRpcResponseEnvelope.Type) => {
+      const requestId = String(response.id);
+      const protocolError = response.error;
+      if (protocolError !== undefined) {
+        return resolvePending(requestId, (deferred) =>
+          Deferred.fail(
+            deferred,
+            CodexError.CodexAppServerRequestError.fromProtocolError(protocolError),
+          ),
+        );
+      }
+      return resolvePending(requestId, (deferred) => Deferred.succeed(deferred, response.result));
+    };
+
+    const handleRequest = (request: CodexAppServerIncomingRequest) =>
+      Queue.offer(incomingRequests, request).pipe(
+        Effect.andThen(
+          options.onRequest
+            ? options.onRequest(request).pipe(
+                Effect.matchEffect({
+                  onFailure: (error) =>
+                    respondError(request.id, CodexError.normalizeToRequestError(error)),
+                  onSuccess: (result) => respond(request.id, result),
+                }),
+              )
+            : Effect.void,
+        ),
+        Effect.asVoid,
+      );
+
+    const handleNotification = (notification: CodexAppServerIncomingNotification) =>
+      Queue.offer(incomingNotifications, notification).pipe(
+        Effect.andThen(options.onNotification ? options.onNotification(notification) : Effect.void),
+        Effect.asVoid,
+      );
+
+    const routeMessage = (
+      message: unknown,
+    ): Effect.Effect<void, CodexError.CodexAppServerError> => {
+      if (isIncomingRequest(message)) {
+        return handleRequest(message);
+      }
+      if (isIncomingNotification(message)) {
+        return handleNotification(message);
+      }
+      if (isIncomingResponse(message)) {
+        return handleResponse(message);
+      }
+      return Effect.fail(
+        new CodexError.CodexAppServerProtocolParseError({
+          detail: "Received protocol message in an unknown shape",
+        }),
+      );
+    };
+
+    const handleLine = (line: string): Effect.Effect<void, CodexError.CodexAppServerError> => {
+      if (line.trim().length === 0) {
+        return Effect.void;
+      }
+      return logProtocol({
+        direction: "incoming",
+        stage: "raw",
+        payload: line,
+      }).pipe(
+        Effect.flatMap(() => decodeWireMessage(line)),
+        Effect.tap((decoded) =>
+          logProtocol({
+            direction: "incoming",
+            stage: "decoded",
+            payload: decoded,
+          }),
+        ),
+        Effect.tapErrorTag("CodexAppServerProtocolParseError", (error) =>
+          logProtocol({
+            direction: "incoming",
+            stage: "decode_failed",
+            payload: {
+              detail: error.detail,
+              cause: error.cause,
+            },
+          }),
+        ),
+        Effect.flatMap(routeMessage),
+      );
+    };
+
+    yield* options.stdio.stdin.pipe(
+      Stream.decodeText(),
+      Stream.runForEach((chunk) =>
+        Ref.modify(remainder, (current) => {
+          const combined = current + chunk;
+          const lines = combined.split("\n");
+          const nextRemainder = lines.pop() ?? "";
+          return [lines.map((line) => line.replace(/\r$/, "")), nextRemainder] as const;
+        }).pipe(Effect.flatMap((lines) => Effect.forEach(lines, handleLine, { discard: true }))),
+      ),
+      Effect.matchEffect({
+        onFailure: (error) =>
+          handleTermination(() =>
+            Effect.succeed(normalizeIncomingError(error, "Codex App Server input stream failed")),
+          ),
+        onSuccess: () =>
+          Ref.get(remainder).pipe(
+            Effect.flatMap((line) => (line.trim().length === 0 ? Effect.void : handleLine(line))),
+            Effect.matchEffect({
+              onFailure: (error) => handleTermination(() => Effect.succeed(error)),
+              onSuccess: () =>
+                handleTermination(
+                  () =>
+                    options.terminationError ??
+                    Effect.succeed(
+                      new CodexError.CodexAppServerTransportError({
+                        detail: "Codex App Server input stream ended",
+                        cause: new Error("Codex App Server input stream ended"),
+                      }),
+                    ),
+                ),
+            }),
+          ),
+      }),
+      Effect.forkScoped,
+    );
+
+    yield* Stream.fromQueue(outgoing).pipe(Stream.run(options.stdio.stdout()), Effect.forkScoped);
+
+    const request = (method: string, payload?: unknown) =>
+      Effect.gen(function* () {
+        const requestId = yield* Ref.modify(
+          nextRequestId,
+          (current) => [current, current + 1] as const,
+        );
+        const deferred = yield* Deferred.make<unknown, CodexError.CodexAppServerError>();
+        yield* Ref.update(pending, (current) => new Map(current).set(String(requestId), deferred));
+        yield* offerOutgoing({
+          id: requestId,
+          method,
+          ...(payload !== undefined ? { params: payload } : {}),
+        }).pipe(
+          Effect.catch((error) =>
+            removePending(String(requestId)).pipe(Effect.andThen(Effect.fail(error))),
+          ),
+        );
+        return yield* Deferred.await(deferred).pipe(
+          Effect.onInterrupt(() => removePending(String(requestId))),
+        );
+      });
+
+    const notify = (method: string, payload?: unknown) =>
+      offerOutgoing({
+        method,
+        ...(payload !== undefined ? { params: payload } : {}),
+      });
+
+    return {
+      incomingNotifications: Stream.fromQueue(incomingNotifications),
+      incomingRequests: Stream.fromQueue(incomingRequests),
+      request,
+      notify,
+      respond,
+      respondError,
+    } satisfies CodexAppServerPatchedProtocol;
+  },
+);
diff --git a/packages/effect-codex-app-server/src/rpc.ts b/packages/effect-codex-app-server/src/rpc.ts
new file mode 100644
index 00000000000..21dca8a7ead
--- /dev/null
+++ b/packages/effect-codex-app-server/src/rpc.ts
@@ -0,0 +1 @@
+export * from "./_generated/meta.gen.ts";
diff --git a/packages/effect-codex-app-server/src/schema.ts b/packages/effect-codex-app-server/src/schema.ts
new file mode 100644
index 00000000000..2d5349752a0
--- /dev/null
+++ b/packages/effect-codex-app-server/src/schema.ts
@@ -0,0 +1,3 @@
+export * from "./_generated/schema.gen.ts";
+export * from "./_generated/meta.gen.ts";
+export * from "./_generated/namespaces.gen.ts";
diff --git a/packages/effect-codex-app-server/test/examples/codex-app-server-probe.ts b/packages/effect-codex-app-server/test/examples/codex-app-server-probe.ts
new file mode 100644
index 00000000000..b6383c0ab7d
--- /dev/null
+++ b/packages/effect-codex-app-server/test/examples/codex-app-server-probe.ts
@@ -0,0 +1,62 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+
+import * as CodexClient from "../../src/client.ts";
+
+const program = Effect.gen(function* () {
+  const codexLayer = CodexClient.layerCommand({
+    command: process.env.CODEX_BIN ?? "codex",
+    args: ["app-server"],
+    cwd: process.cwd(),
+    logIncoming: true,
+    logOutgoing: true,
+  });
+
+  yield* Effect.gen(function* () {
+    const client = yield* CodexClient.CodexAppServerClient;
+
+    yield* client.handleServerRequest("item/tool/requestUserInput", (payload) =>
+      Effect.succeed({
+        answers: Object.fromEntries(
+          payload.questions.map((question) => [
+            question.id,
+            {
+              answers:
+                question.options && question.options.length > 0
+                  ? [question.options[0]!.label]
+                  : ["ok"],
+            },
+          ]),
+        ),
+      }),
+    );
+
+    const initialized = yield* client.request("initialize", {
+      clientInfo: {
+        name: "effect-codex-app-server-probe",
+        title: "Effect Codex App Server Probe",
+        version: "0.0.0",
+      },
+      capabilities: {
+        experimentalApi: true,
+        optOutNotificationMethods: null,
+      },
+    });
+    yield* Console.log("initialize", initialized);
+
+    yield* client.notify("initialized", undefined);
+
+    const account = yield* client.request("account/read", {});
+    yield* Console.log("account/read", account);
+
+    const skills = yield* client.request("skills/list", {
+      cwds: [process.cwd()],
+    });
+    yield* Console.log("skills/list", skills);
+  }).pipe(Effect.provide(codexLayer));
+});
+
+program.pipe(Effect.scoped, Effect.provide(NodeServices.layer), NodeRuntime.runMain);
diff --git a/packages/effect-codex-app-server/test/fixtures/codex-app-server-mock-peer.ts b/packages/effect-codex-app-server/test/fixtures/codex-app-server-mock-peer.ts
new file mode 100644
index 00000000000..51668b5e248
--- /dev/null
+++ b/packages/effect-codex-app-server/test/fixtures/codex-app-server-mock-peer.ts
@@ -0,0 +1,144 @@
+let nextServerRequestId = 10_000;
+let pendingSkillsListRequestId: number | string | null = null;
+let pendingUserInputRequestId: number | null = null;
+
+const writeMessage = (message: unknown) => {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+};
+
+const respond = (id: number | string, result: unknown) => {
+  writeMessage({ id, result });
+};
+
+const respondError = (id: number | string, code: number, message: string) => {
+  writeMessage({
+    id,
+    error: {
+      code,
+      message,
+    },
+  });
+};
+
+const sendRequest = (method: string, params: unknown) => {
+  const id = nextServerRequestId++;
+  writeMessage({ id, method, params });
+  return id;
+};
+
+const handleMethod = (message: Record<string, unknown>) => {
+  const method = message.method;
+  if (typeof method !== "string") {
+    return;
+  }
+
+  switch (method) {
+    case "initialize": {
+      respond(message.id as number | string, {
+        userAgent: "mock-codex-app-server",
+        codexHome: process.cwd(),
+        platformFamily: process.platform === "win32" ? "windows" : "unix",
+        platformOs: process.platform === "darwin" ? "macos" : process.platform,
+      });
+      return;
+    }
+    case "initialized": {
+      writeMessage({
+        method: "item/agentMessage/delta",
+        params: {
+          delta: "Mock server is ready.",
+          itemId: "item-1",
+          threadId: "thread-1",
+          turnId: "turn-1",
+        },
+      });
+      return;
+    }
+    case "account/read": {
+      respond(message.id as number | string, {
+        account: {
+          type: "chatgpt",
+          email: "mock@example.com",
+          planType: "plus",
+        },
+        requiresOpenaiAuth: false,
+      });
+      return;
+    }
+    case "skills/list": {
+      pendingSkillsListRequestId = message.id as number | string;
+      pendingUserInputRequestId = sendRequest("item/tool/requestUserInput", {
+        itemId: "item-approval-1",
+        threadId: "thread-1",
+        turnId: "turn-1",
+        questions: [
+          {
+            id: "approved",
+            header: "Approve",
+            question: "Continue with the mock skills request?",
+            options: [
+              {
+                label: "yes",
+                description: "Approve the request",
+              },
+            ],
+          },
+        ],
+      });
+      return;
+    }
+    default: {
+      if (message.id !== undefined) {
+        respondError(message.id as number | string, -32601, `Unhandled request: ${method}`);
+      }
+    }
+  }
+};
+
+const handleResponse = (message: Record<string, unknown>) => {
+  if (message.id !== pendingUserInputRequestId) {
+    return;
+  }
+
+  pendingUserInputRequestId = null;
+
+  respond(pendingSkillsListRequestId!, {
+    data: [
+      {
+        cwd: process.cwd(),
+        errors: [],
+        skills: [],
+      },
+    ],
+  });
+  pendingSkillsListRequestId = null;
+};
+
+let remainder = "";
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  remainder += chunk;
+  const lines = remainder.split("\n");
+  remainder = lines.pop() ?? "";
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+
+    const message = JSON.parse(trimmed) as Record<string, unknown>;
+    if ("method" in message) {
+      handleMethod(message);
+      continue;
+    }
+    if ("id" in message) {
+      handleResponse(message);
+    }
+  }
+});
+
+process.stdin.on("end", () => {
+  process.exit(0);
+});
diff --git a/packages/effect-codex-app-server/tsconfig.json b/packages/effect-codex-app-server/tsconfig.json
new file mode 100644
index 00000000000..04f1d37800f
--- /dev/null
+++ b/packages/effect-codex-app-server/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": ["src", "scripts", "test"]
+}
diff --git a/packages/shared/package.json b/packages/shared/package.json
index ed65cbeaf3c..c27a95ea904 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -1,6 +1,5 @@
 {
   "name": "@t3tools/shared",
-  "version": "0.0.0-alpha.1",
   "private": true,
   "type": "module",
   "exports": {
@@ -8,18 +7,34 @@
       "types": "./src/model.ts",
       "import": "./src/model.ts"
     },
+    "./advertisedEndpoint": {
+      "types": "./src/advertisedEndpoint.ts",
+      "import": "./src/advertisedEndpoint.ts"
+    },
     "./git": {
       "types": "./src/git.ts",
       "import": "./src/git.ts"
     },
+    "./sourceControl": {
+      "types": "./src/sourceControl.ts",
+      "import": "./src/sourceControl.ts"
+    },
     "./logging": {
       "types": "./src/logging.ts",
       "import": "./src/logging.ts"
     },
+    "./observability": {
+      "types": "./src/observability.ts",
+      "import": "./src/observability.ts"
+    },
     "./shell": {
       "types": "./src/shell.ts",
       "import": "./src/shell.ts"
     },
+    "./semver": {
+      "types": "./src/semver.ts",
+      "import": "./src/semver.ts"
+    },
     "./Net": {
       "types": "./src/Net.ts",
       "import": "./src/Net.ts"
@@ -36,6 +51,10 @@
       "types": "./src/schemaJson.ts",
       "import": "./src/schemaJson.ts"
     },
+    "./toolActivity": {
+      "types": "./src/toolActivity.ts",
+      "import": "./src/toolActivity.ts"
+    },
     "./Struct": {
       "types": "./src/Struct.ts",
       "import": "./src/Struct.ts"
@@ -59,10 +78,21 @@
     "./qrCode": {
       "types": "./src/qrCode.ts",
       "import": "./src/qrCode.ts"
+    },
+    "./cliArgs": {
+      "types": "./src/cliArgs.ts",
+      "import": "./src/cliArgs.ts"
+    },
+    "./path": {
+      "types": "./src/path.ts",
+      "import": "./src/path.ts"
+    },
+    "./keybindings": {
+      "types": "./src/keybindings.ts",
+      "import": "./src/keybindings.ts"
     }
   },
   "scripts": {
-    "prepare": "effect-language-service patch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
@@ -72,6 +102,7 @@
   },
   "devDependencies": {
     "@effect/language-service": "catalog:",
+    "@effect/platform-node": "catalog:",
     "@effect/vitest": "catalog:",
     "@types/node": "catalog:",
     "typescript": "catalog:",
diff --git a/packages/shared/src/DrainableWorker.test.ts b/packages/shared/src/DrainableWorker.test.ts
index 1d7a3a83c78..7fc1a5fc23d 100644
--- a/packages/shared/src/DrainableWorker.test.ts
+++ b/packages/shared/src/DrainableWorker.test.ts
@@ -1,8 +1,9 @@
 import { it } from "@effect/vitest";
 import { describe, expect } from "vitest";
-import { Deferred, Effect } from "effect";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
 
-import { makeDrainableWorker } from "./DrainableWorker";
+import { makeDrainableWorker } from "./DrainableWorker.ts";
 
 describe("makeDrainableWorker", () => {
   it.live("waits for work enqueued during active processing before draining", () =>
diff --git a/packages/shared/src/DrainableWorker.ts b/packages/shared/src/DrainableWorker.ts
index 55483f33e8c..de40ec5e36b 100644
--- a/packages/shared/src/DrainableWorker.ts
+++ b/packages/shared/src/DrainableWorker.ts
@@ -8,8 +8,10 @@
  *
  * @module DrainableWorker
  */
-import type { Scope } from "effect";
-import { Effect, TxQueue, TxRef } from "effect";
+import * as Scope from "effect/Scope";
+import * as Effect from "effect/Effect";
+import * as TxQueue from "effect/TxQueue";
+import * as TxRef from "effect/TxRef";
 
 export interface DrainableWorker<A> {
   /**
diff --git a/packages/shared/src/KeyedCoalescingWorker.test.ts b/packages/shared/src/KeyedCoalescingWorker.test.ts
index 2226bbd003e..a010d732310 100644
--- a/packages/shared/src/KeyedCoalescingWorker.test.ts
+++ b/packages/shared/src/KeyedCoalescingWorker.test.ts
@@ -1,8 +1,9 @@
 import { it } from "@effect/vitest";
 import { describe, expect } from "vitest";
-import { Deferred, Effect } from "effect";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
 
-import { makeKeyedCoalescingWorker } from "./KeyedCoalescingWorker";
+import { makeKeyedCoalescingWorker } from "./KeyedCoalescingWorker.ts";
 
 describe("makeKeyedCoalescingWorker", () => {
   it.live("waits for latest work enqueued during active processing before draining the key", () =>
@@ -73,7 +74,7 @@ describe("makeKeyedCoalescingWorker", () => {
               if (value === "first") {
                 yield* Deferred.succeed(firstStarted, undefined).pipe(Effect.orDie);
                 yield* Deferred.await(releaseFailure);
-                yield* Effect.fail("boom");
+                return yield* Effect.fail("boom");
               }
 
               if (value === "second") {
diff --git a/packages/shared/src/KeyedCoalescingWorker.ts b/packages/shared/src/KeyedCoalescingWorker.ts
index 567c1dac173..f4edebfafb3 100644
--- a/packages/shared/src/KeyedCoalescingWorker.ts
+++ b/packages/shared/src/KeyedCoalescingWorker.ts
@@ -7,8 +7,10 @@
  *
  * @module KeyedCoalescingWorker
  */
-import type { Scope } from "effect";
-import { Effect, TxQueue, TxRef } from "effect";
+import * as Scope from "effect/Scope";
+import * as Effect from "effect/Effect";
+import * as TxQueue from "effect/TxQueue";
+import * as TxRef from "effect/TxRef";
 
 export interface KeyedCoalescingWorker<K, V> {
   readonly enqueue: (key: K, value: V) => Effect.Effect<void>;
diff --git a/packages/shared/src/Net.test.ts b/packages/shared/src/Net.test.ts
index 137a9416fd1..e165d944b56 100644
--- a/packages/shared/src/Net.test.ts
+++ b/packages/shared/src/Net.test.ts
@@ -1,11 +1,11 @@
-import * as Net from "node:net";
+import * as NodeNet from "node:net";
 
 import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
 
-import { NetError, NetService } from "./Net";
+import * as NetService from "./Net.ts";
 
-const closeServer = (server: Net.Server) =>
+const closeServer = (server: NodeNet.Server) =>
   Effect.sync(() => {
     try {
       server.close();
@@ -14,24 +14,26 @@ const closeServer = (server: Net.Server) =>
     }
   });
 
-const getPort = (server: Net.Server): number => {
+const getPort = (server: NodeNet.Server): number => {
   const address = server.address();
   return typeof address === "object" && address !== null ? address.port : 0;
 };
 
-const openServer = (host?: string): Effect.Effect<Net.Server, NetError> =>
-  Effect.callback<Net.Server, NetError>((resume) => {
-    const server = Net.createServer();
+const openServer = (host?: string): Effect.Effect<NodeNet.Server, NetService.NetError> =>
+  Effect.callback<NodeNet.Server, NetService.NetError>((resume) => {
+    const server = NodeNet.createServer();
     let settled = false;
 
-    const settle = (effect: Effect.Effect<Net.Server, NetError>) => {
+    const settle = (effect: Effect.Effect<NodeNet.Server, NetService.NetError>) => {
       if (settled) return;
       settled = true;
       resume(effect);
     };
 
     server.once("error", (cause) => {
-      settle(Effect.fail(new NetError({ message: "Failed to open test server", cause })));
+      settle(
+        Effect.fail(new NetService.NetError({ message: "Failed to open test server", cause })),
+      );
     });
 
     if (host) {
@@ -47,7 +49,7 @@ it.layer(NetService.layer)("NetService", (it) => {
   describe("Net helpers", () => {
     it.effect("reserveLoopbackPort returns a positive loopback port", () =>
       Effect.gen(function* () {
-        const net = yield* NetService;
+        const net = yield* NetService.NetService;
         const port = yield* net.reserveLoopbackPort();
 
         assert.ok(port > 0);
@@ -59,7 +61,7 @@ it.layer(NetService.layer)("NetService", (it) => {
         openServer("127.0.0.1"),
         (server) =>
           Effect.gen(function* () {
-            const net = yield* NetService;
+            const net = yield* NetService.NetService;
             const port = getPort(server);
 
             const available = yield* net.isPortAvailableOnLoopback(port);
@@ -71,7 +73,7 @@ it.layer(NetService.layer)("NetService", (it) => {
 
     it.effect("findAvailablePort returns preferred when it is free", () =>
       Effect.gen(function* () {
-        const net = yield* NetService;
+        const net = yield* NetService.NetService;
         const preferred = yield* net.reserveLoopbackPort();
 
         const resolved = yield* net.findAvailablePort(preferred);
@@ -84,7 +86,7 @@ it.layer(NetService.layer)("NetService", (it) => {
         openServer(),
         (server) =>
           Effect.gen(function* () {
-            const net = yield* NetService;
+            const net = yield* NetService.NetService;
             const preferred = getPort(server);
 
             const resolved = yield* net.findAvailablePort(preferred);
diff --git a/packages/shared/src/Net.ts b/packages/shared/src/Net.ts
index d0a44cc5724..0a3c6283756 100644
--- a/packages/shared/src/Net.ts
+++ b/packages/shared/src/Net.ts
@@ -1,24 +1,26 @@
-import * as Net from "node:net";
+import * as NodeNet from "node:net";
 
-import { Data, Effect, Layer, Context } from "effect";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Context from "effect/Context";
+import * as Predicate from "effect/Predicate";
 
 export class NetError extends Data.TaggedError("NetError")<{
   readonly message: string;
   readonly cause?: unknown;
 }> {}
 
-function isErrnoExceptionWithCode(cause: unknown): cause is {
+const isErrnoExceptionWithCode = (
+  cause: unknown,
+): cause is {
   readonly code: string;
-} {
-  return (
-    typeof cause === "object" &&
-    cause !== null &&
-    "code" in cause &&
-    typeof (cause as { readonly code: unknown }).code === "string"
-  );
-}
+} =>
+  Predicate.isObject(cause) &&
+  Predicate.hasProperty(cause, "code") &&
+  Predicate.isString(cause.code);
 
-const closeServer = (server: Net.Server) => {
+const closeServer = (server: NodeNet.Server) => {
   try {
     server.close();
   } catch {
@@ -28,7 +30,7 @@ const closeServer = (server: Net.Server) => {
 
 const tryReservePort = (port: number): Effect.Effect<number, NetError> =>
   Effect.callback<number, NetError>((resume) => {
-    const server = Net.createServer();
+    const server = NodeNet.createServer();
     let settled = false;
 
     const settle = (effect: Effect.Effect<number, NetError>) => {
@@ -87,94 +89,96 @@ export interface NetServiceShape {
  */
 export class NetService extends Context.Service<NetService, NetServiceShape>()(
   "@t3tools/shared/Net/NetService",
-) {
-  static readonly layer = Layer.sync(NetService, () => {
-    /**
-     * Returns true when a TCP server can bind to {host, port}.
-     * `EADDRNOTAVAIL` is treated as available so IPv6-absent hosts don't fail
-     * loopback availability checks.
-     */
-    const canListenOnHost = (port: number, host: string): Effect.Effect<boolean> =>
-      Effect.callback<boolean>((resume) => {
-        const server = Net.createServer();
-        let settled = false;
-
-        const settle = (value: boolean) => {
-          if (settled) return;
-          settled = true;
-          resume(Effect.succeed(value));
-        };
-
-        server.unref();
-
-        server.once("error", (cause) => {
-          if (isErrnoExceptionWithCode(cause) && cause.code === "EADDRNOTAVAIL") {
-            settle(true);
-            return;
-          }
-          settle(false);
-        });
+) {}
+
+export const make = () => {
+  /**
+   * Returns true when a TCP server can bind to {host, port}.
+   * `EADDRNOTAVAIL` is treated as available so IPv6-absent hosts don't fail
+   * loopback availability checks.
+   */
+  const canListenOnHost = (port: number, host: string): Effect.Effect<boolean> =>
+    Effect.callback<boolean>((resume) => {
+      const server = NodeNet.createServer();
+      let settled = false;
+
+      const settle = (value: boolean) => {
+        if (settled) return;
+        settled = true;
+        resume(Effect.succeed(value));
+      };
+
+      server.unref();
+
+      server.once("error", (cause) => {
+        if (isErrnoExceptionWithCode(cause) && cause.code === "EADDRNOTAVAIL") {
+          settle(true);
+          return;
+        }
+        settle(false);
+      });
 
-        server.once("listening", () => {
-          server.close(() => {
-            settle(true);
-          });
+      server.once("listening", () => {
+        server.close(() => {
+          settle(true);
         });
+      });
 
-        server.listen({ host, port });
+      server.listen({ host, port });
 
-        return Effect.sync(() => {
-          closeServer(server);
-        });
+      return Effect.sync(() => {
+        closeServer(server);
       });
+    });
 
-    /**
-     * Reserve an ephemeral loopback port and release it immediately.
-     * Returns the reserved port number.
-     */
-    const reserveLoopbackPort = (host = "127.0.0.1"): Effect.Effect<number, NetError> =>
-      Effect.callback<number, NetError>((resume) => {
-        const probe = Net.createServer();
-        let settled = false;
-
-        const settle = (effect: Effect.Effect<number, NetError>) => {
-          if (settled) return;
-          settled = true;
-          resume(effect);
-        };
-
-        probe.once("error", (cause) => {
-          settle(Effect.fail(new NetError({ message: "Failed to reserve loopback port", cause })));
-        });
+  /**
+   * Reserve an ephemeral loopback port and release it immediately.
+   * Returns the reserved port number.
+   */
+  const reserveLoopbackPort = (host = "127.0.0.1"): Effect.Effect<number, NetError> =>
+    Effect.callback<number, NetError>((resume) => {
+      const probe = NodeNet.createServer();
+      let settled = false;
+
+      const settle = (effect: Effect.Effect<number, NetError>) => {
+        if (settled) return;
+        settled = true;
+        resume(effect);
+      };
+
+      probe.once("error", (cause) => {
+        settle(Effect.fail(new NetError({ message: "Failed to reserve loopback port", cause })));
+      });
 
-        probe.listen(0, host, () => {
-          const address = probe.address();
-          const port = typeof address === "object" && address !== null ? address.port : 0;
-          probe.close(() => {
-            if (port > 0) {
-              settle(Effect.succeed(port));
-              return;
-            }
-            settle(Effect.fail(new NetError({ message: "Failed to reserve loopback port" })));
-          });
+      probe.listen(0, host, () => {
+        const address = probe.address();
+        const port = typeof address === "object" && address !== null ? address.port : 0;
+        probe.close(() => {
+          if (port > 0) {
+            settle(Effect.succeed(port));
+            return;
+          }
+          settle(Effect.fail(new NetError({ message: "Failed to reserve loopback port" })));
         });
+      });
 
-        return Effect.sync(() => {
-          closeServer(probe);
-        });
+      return Effect.sync(() => {
+        closeServer(probe);
       });
+    });
 
-    return {
-      canListenOnHost,
-      isPortAvailableOnLoopback: (port) =>
-        Effect.zipWith(
-          canListenOnHost(port, "127.0.0.1"),
-          canListenOnHost(port, "::1"),
-          (ipv4, ipv6) => ipv4 && ipv6,
-        ),
-      reserveLoopbackPort,
-      findAvailablePort: (preferred) =>
-        Effect.catch(tryReservePort(preferred), () => tryReservePort(0)),
-    } satisfies NetServiceShape;
-  });
-}
+  return {
+    canListenOnHost,
+    isPortAvailableOnLoopback: (port) =>
+      Effect.zipWith(
+        canListenOnHost(port, "127.0.0.1"),
+        canListenOnHost(port, "::1"),
+        (ipv4, ipv6) => ipv4 && ipv6,
+      ),
+    reserveLoopbackPort,
+    findAvailablePort: (preferred) =>
+      Effect.catch(tryReservePort(preferred), () => tryReservePort(0)),
+  } satisfies NetServiceShape;
+};
+
+export const layer = Layer.sync(NetService, make);
diff --git a/packages/shared/src/String.test.ts b/packages/shared/src/String.test.ts
index d70bfe840f2..92730cd596e 100644
--- a/packages/shared/src/String.test.ts
+++ b/packages/shared/src/String.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { truncate } from "./String";
+import { truncate } from "./String.ts";
 
 describe("truncate", () => {
   it("trims surrounding whitespace", () => {
diff --git a/packages/shared/src/advertisedEndpoint.ts b/packages/shared/src/advertisedEndpoint.ts
new file mode 100644
index 00000000000..314d8272c81
--- /dev/null
+++ b/packages/shared/src/advertisedEndpoint.ts
@@ -0,0 +1,78 @@
+import type {
+  AdvertisedEndpoint,
+  AdvertisedEndpointHostedHttpsCompatibility,
+  AdvertisedEndpointProvider,
+  AdvertisedEndpointReachability,
+  AdvertisedEndpointSource,
+  AdvertisedEndpointStatus,
+} from "@t3tools/contracts";
+
+export interface CreateAdvertisedEndpointInput {
+  readonly id: string;
+  readonly label: string;
+  readonly provider: AdvertisedEndpointProvider;
+  readonly httpBaseUrl: string;
+  readonly reachability: AdvertisedEndpointReachability;
+  readonly hostedHttpsCompatibility?: AdvertisedEndpointHostedHttpsCompatibility;
+  readonly desktopCompatibility?: "compatible" | "unknown";
+  readonly source: AdvertisedEndpointSource;
+  readonly status?: AdvertisedEndpointStatus;
+  readonly isDefault?: boolean;
+  readonly description?: string;
+}
+
+export function normalizeHttpBaseUrl(rawValue: string): string {
+  const url = new URL(rawValue);
+  if (url.protocol === "ws:") {
+    url.protocol = "http:";
+  } else if (url.protocol === "wss:") {
+    url.protocol = "https:";
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Endpoint must use HTTP or HTTPS. Received ${url.protocol}`);
+  }
+
+  url.pathname = "/";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+export function deriveWsBaseUrl(httpBaseUrl: string): string {
+  const url = new URL(normalizeHttpBaseUrl(httpBaseUrl));
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString();
+}
+
+export function classifyHostedHttpsCompatibility(
+  httpBaseUrl: string,
+  fallback: AdvertisedEndpointHostedHttpsCompatibility = "unknown",
+): AdvertisedEndpointHostedHttpsCompatibility {
+  const url = new URL(normalizeHttpBaseUrl(httpBaseUrl));
+  if (url.protocol === "http:") {
+    return "mixed-content-blocked";
+  }
+  return fallback === "mixed-content-blocked" ? "unknown" : fallback;
+}
+
+export function createAdvertisedEndpoint(input: CreateAdvertisedEndpointInput): AdvertisedEndpoint {
+  const httpBaseUrl = normalizeHttpBaseUrl(input.httpBaseUrl);
+  return {
+    id: input.id,
+    label: input.label,
+    provider: input.provider,
+    httpBaseUrl,
+    wsBaseUrl: deriveWsBaseUrl(httpBaseUrl),
+    reachability: input.reachability,
+    compatibility: {
+      hostedHttpsApp:
+        input.hostedHttpsCompatibility ?? classifyHostedHttpsCompatibility(httpBaseUrl),
+      desktopApp: input.desktopCompatibility ?? "compatible",
+    },
+    source: input.source,
+    status: input.status ?? "available",
+    ...(input.isDefault === undefined ? {} : { isDefault: input.isDefault }),
+    ...(input.description === undefined ? {} : { description: input.description }),
+  };
+}
diff --git a/packages/shared/src/cliArgs.test.ts b/packages/shared/src/cliArgs.test.ts
new file mode 100644
index 00000000000..62544c682c0
--- /dev/null
+++ b/packages/shared/src/cliArgs.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+
+import { parseCliArgs } from "./cliArgs.ts";
+
+describe("parseCliArgs", () => {
+  it("returns empty result for empty string", () => {
+    expect(parseCliArgs("")).toEqual({ flags: {}, positionals: [] });
+  });
+
+  it("returns empty result for whitespace-only string", () => {
+    expect(parseCliArgs("   ")).toEqual({ flags: {}, positionals: [] });
+  });
+
+  it("returns empty result for empty array", () => {
+    expect(parseCliArgs([])).toEqual({ flags: {}, positionals: [] });
+  });
+
+  it("parses --chrome boolean flag", () => {
+    expect(parseCliArgs("--chrome")).toEqual({
+      flags: { chrome: null },
+      positionals: [],
+    });
+  });
+
+  it("parses --chrome with --verbose", () => {
+    expect(parseCliArgs("--chrome --verbose")).toEqual({
+      flags: { chrome: null, verbose: null },
+      positionals: [],
+    });
+  });
+
+  it("parses --effort with a value", () => {
+    expect(parseCliArgs("--effort high")).toEqual({
+      flags: { effort: "high" },
+      positionals: [],
+    });
+  });
+
+  it("parses --chrome --effort high --debug", () => {
+    expect(parseCliArgs("--chrome --effort high --debug")).toEqual({
+      flags: { chrome: null, effort: "high", debug: null },
+      positionals: [],
+    });
+  });
+
+  it("parses --model with full model name", () => {
+    expect(parseCliArgs("--model claude-sonnet-4-6")).toEqual({
+      flags: { model: "claude-sonnet-4-6" },
+      positionals: [],
+    });
+  });
+
+  it("parses --append-system-prompt with value and --chrome", () => {
+    expect(parseCliArgs("--append-system-prompt always-think-step-by-step --chrome")).toEqual({
+      flags: { "append-system-prompt": "always-think-step-by-step", chrome: null },
+      positionals: [],
+    });
+  });
+
+  it("parses --max-budget-usd with numeric value", () => {
+    expect(parseCliArgs("--chrome --max-budget-usd 5.00")).toEqual({
+      flags: { chrome: null, "max-budget-usd": "5.00" },
+      positionals: [],
+    });
+  });
+
+  it("parses --effort=high syntax", () => {
+    expect(parseCliArgs("--effort=high")).toEqual({
+      flags: { effort: "high" },
+      positionals: [],
+    });
+  });
+
+  it("parses --key=value mixed with boolean flags", () => {
+    expect(parseCliArgs("--chrome --model=claude-sonnet-4-6 --debug")).toEqual({
+      flags: { chrome: null, model: "claude-sonnet-4-6", debug: null },
+      positionals: [],
+    });
+  });
+
+  it("collects positional arguments", () => {
+    expect(parseCliArgs("1.2.3")).toEqual({
+      flags: {},
+      positionals: ["1.2.3"],
+    });
+  });
+
+  it("collects positionals mixed with flags (argv array)", () => {
+    expect(parseCliArgs(["1.2.3", "--root", "/path", "--github-output"])).toEqual({
+      flags: { root: "/path", "github-output": null },
+      positionals: ["1.2.3"],
+    });
+  });
+
+  it("handles extra whitespace between tokens", () => {
+    expect(parseCliArgs("  --chrome   --verbose  ")).toEqual({
+      flags: { chrome: null, verbose: null },
+      positionals: [],
+    });
+  });
+
+  it("ignores bare -- with no flag name", () => {
+    expect(parseCliArgs("--")).toEqual({ flags: {}, positionals: [] });
+  });
+
+  it("boolean flag does not consume next token as value", () => {
+    expect(parseCliArgs(["--github-output", "1.2.3"], { booleanFlags: ["github-output"] })).toEqual(
+      {
+        flags: { "github-output": null },
+        positionals: ["1.2.3"],
+      },
+    );
+  });
+
+  it("non-boolean flag still consumes next token", () => {
+    expect(parseCliArgs(["--root", "/path", "1.2.3"], { booleanFlags: ["github-output"] })).toEqual(
+      {
+        flags: { root: "/path" },
+        positionals: ["1.2.3"],
+      },
+    );
+  });
+
+  it("mixes boolean and value flags with positionals", () => {
+    expect(
+      parseCliArgs(["--github-output", "--root", "/path", "1.2.3"], {
+        booleanFlags: ["github-output"],
+      }),
+    ).toEqual({
+      flags: { "github-output": null, root: "/path" },
+      positionals: ["1.2.3"],
+    });
+  });
+});
diff --git a/packages/shared/src/cliArgs.ts b/packages/shared/src/cliArgs.ts
new file mode 100644
index 00000000000..20920093302
--- /dev/null
+++ b/packages/shared/src/cliArgs.ts
@@ -0,0 +1,76 @@
+export interface ParsedCliArgs {
+  readonly flags: Record<string, string | null>;
+  readonly positionals: string[];
+}
+
+export interface ParseCliArgsOptions {
+  readonly booleanFlags?: readonly string[];
+}
+
+/**
+ * Parse CLI-style arguments into flags and positionals.
+ *
+ * Accepts a string (split by whitespace) or a pre-split argv array.
+ * Supports `--key value`, `--key=value`, and `--flag` (boolean) syntax.
+ *
+ *   parseCliArgs("")
+ *     → { flags: {}, positionals: [] }
+ *
+ *   parseCliArgs("--chrome")
+ *     → { flags: { chrome: null }, positionals: [] }
+ *
+ *   parseCliArgs("--chrome --effort high")
+ *     → { flags: { chrome: null, effort: "high" }, positionals: [] }
+ *
+ *   parseCliArgs("--effort=high")
+ *     → { flags: { effort: "high" }, positionals: [] }
+ *
+ *   parseCliArgs(["1.2.3", "--root", "/path", "--github-output"], { booleanFlags: ["github-output"] })
+ *     → { flags: { root: "/path", "github-output": null }, positionals: ["1.2.3"] }
+ */
+export function parseCliArgs(
+  args: string | readonly string[],
+  options?: ParseCliArgsOptions,
+): ParsedCliArgs {
+  const tokens =
+    typeof args === "string" ? args.trim().split(/\s+/).filter(Boolean) : Array.from(args);
+  const booleanSet = options?.booleanFlags ? new Set(options.booleanFlags) : undefined;
+
+  const flags: Record<string, string | null> = {};
+  const positionals: string[] = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+
+    if (token.startsWith("--")) {
+      const rest = token.slice(2);
+      if (!rest) continue;
+
+      // Handle --key=value syntax
+      const eqIndex = rest.indexOf("=");
+      if (eqIndex !== -1) {
+        flags[rest.slice(0, eqIndex)] = rest.slice(eqIndex + 1);
+        continue;
+      }
+
+      // Known boolean flag — never consumes next token
+      if (booleanSet?.has(rest)) {
+        flags[rest] = null;
+        continue;
+      }
+
+      // Handle --key value or --flag (boolean)
+      const next = tokens[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags[rest] = next;
+        i++;
+      } else {
+        flags[rest] = null;
+      }
+    } else {
+      positionals.push(token);
+    }
+  }
+
+  return { flags, positionals };
+}
diff --git a/packages/shared/src/git.test.ts b/packages/shared/src/git.test.ts
index dac644e83bb..5eb9fd51244 100644
--- a/packages/shared/src/git.test.ts
+++ b/packages/shared/src/git.test.ts
@@ -1,11 +1,14 @@
-import type { GitStatusRemoteResult, GitStatusResult } from "@t3tools/contracts";
+import type { VcsStatusRemoteResult, VcsStatusResult } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 
 import {
   applyGitStatusStreamEvent,
+  buildTemporaryWorktreeBranchName,
+  isTemporaryWorktreeBranch,
   normalizeGitRemoteUrl,
   parseGitHubRepositoryNameWithOwnerFromRemoteUrl,
-} from "./git";
+  WORKTREE_BRANCH_PREFIX,
+} from "./git.ts";
 
 describe("normalizeGitRemoteUrl", () => {
   it("canonicalizes equivalent GitHub remotes across protocol variants", () => {
@@ -50,9 +53,27 @@ describe("parseGitHubRepositoryNameWithOwnerFromRemoteUrl", () => {
   });
 });
 
+describe("isTemporaryWorktreeBranch", () => {
+  it("matches the generated temporary worktree refName format", () => {
+    expect(isTemporaryWorktreeBranch(buildTemporaryWorktreeBranchName())).toBe(true);
+  });
+
+  it("matches generated temporary worktree refs", () => {
+    expect(isTemporaryWorktreeBranch(`${WORKTREE_BRANCH_PREFIX}/deadbeef`)).toBe(true);
+    expect(isTemporaryWorktreeBranch(` ${WORKTREE_BRANCH_PREFIX}/deadbeef `)).toBe(true);
+    expect(isTemporaryWorktreeBranch(`${WORKTREE_BRANCH_PREFIX}/DEADBEEF`)).toBe(true);
+  });
+
+  it("rejects non-temporary refName names", () => {
+    expect(isTemporaryWorktreeBranch(`${WORKTREE_BRANCH_PREFIX}/feature/demo`)).toBe(false);
+    expect(isTemporaryWorktreeBranch("main")).toBe(false);
+    expect(isTemporaryWorktreeBranch(`${WORKTREE_BRANCH_PREFIX}/deadbeef-extra`)).toBe(false);
+  });
+});
+
 describe("applyGitStatusStreamEvent", () => {
   it("treats a remote-only update as a repository when local state is missing", () => {
-    const remote: GitStatusRemoteResult = {
+    const remote: VcsStatusRemoteResult = {
       hasUpstream: true,
       aheadCount: 2,
       behindCount: 1,
@@ -61,9 +82,9 @@ describe("applyGitStatusStreamEvent", () => {
 
     expect(applyGitStatusStreamEvent(null, { _tag: "remoteUpdated", remote })).toEqual({
       isRepo: true,
-      hasOriginRemote: false,
-      isDefaultBranch: false,
-      branch: null,
+      hasPrimaryRemote: false,
+      isDefaultRef: false,
+      refName: null,
       hasWorkingTreeChanges: false,
       workingTree: { files: [], insertions: 0, deletions: 0 },
       hasUpstream: true,
@@ -74,16 +95,16 @@ describe("applyGitStatusStreamEvent", () => {
   });
 
   it("preserves local-only fields when applying a remote update", () => {
-    const current: GitStatusResult = {
+    const current: VcsStatusResult = {
       isRepo: true,
-      hostingProvider: {
+      sourceControlProvider: {
         kind: "github",
         name: "GitHub",
         baseUrl: "https://github.com",
       },
-      hasOriginRemote: true,
-      isDefaultBranch: false,
-      branch: "feature/demo",
+      hasPrimaryRemote: true,
+      isDefaultRef: false,
+      refName: "feature/demo",
       hasWorkingTreeChanges: true,
       workingTree: {
         files: [{ path: "src/demo.ts", insertions: 1, deletions: 0 }],
@@ -96,7 +117,7 @@ describe("applyGitStatusStreamEvent", () => {
       pr: null,
     };
 
-    const remote: GitStatusRemoteResult = {
+    const remote: VcsStatusRemoteResult = {
       hasUpstream: true,
       aheadCount: 2,
       behindCount: 1,
diff --git a/packages/shared/src/git.ts b/packages/shared/src/git.ts
index a39c9244477..1ad17f52bd4 100644
--- a/packages/shared/src/git.ts
+++ b/packages/shared/src/git.ts
@@ -1,14 +1,20 @@
 import type {
-  GitBranch,
-  GitHostingProvider,
-  GitStatusLocalResult,
-  GitStatusRemoteResult,
-  GitStatusResult,
-  GitStatusStreamEvent,
+  VcsRef,
+  SourceControlProviderInfo,
+  VcsStatusLocalResult,
+  VcsStatusRemoteResult,
+  VcsStatusResult,
+  VcsStatusStreamEvent,
 } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Random from "effect/Random";
+import { detectSourceControlProviderFromRemoteUrl } from "./sourceControl.ts";
+
+export const WORKTREE_BRANCH_PREFIX = "t3code";
+const TEMP_WORKTREE_BRANCH_PATTERN = new RegExp(`^${WORKTREE_BRANCH_PREFIX}\\/[0-9a-f]{8}$`);
 
 /**
- * Sanitize an arbitrary string into a valid, lowercase git branch fragment.
+ * Sanitize an arbitrary string into a valid, lowercase git refName fragment.
  * Strips quotes, collapses separators, limits to 64 chars.
  */
 export function sanitizeBranchFragment(raw: string): string {
@@ -30,7 +36,7 @@ export function sanitizeBranchFragment(raw: string): string {
 }
 
 /**
- * Sanitize a string into a `feature/…` branch name.
+ * Sanitize a string into a `feature/…` refName name.
  * Preserves an existing `feature/` prefix or slash-separated namespace.
  */
 export function sanitizeFeatureBranchName(raw: string): string {
@@ -44,8 +50,8 @@ export function sanitizeFeatureBranchName(raw: string): string {
 const AUTO_FEATURE_BRANCH_FALLBACK = "feature/update";
 
 /**
- * Resolve a unique `feature/…` branch name that doesn't collide with
- * any existing branch. Appends a numeric suffix when needed.
+ * Resolve a unique `feature/…` refName name that doesn't collide with
+ * any existing refName. Appends a numeric suffix when needed.
  */
 export function resolveAutoFeatureBranchName(
   existingBranchNames: readonly string[],
@@ -55,7 +61,7 @@ export function resolveAutoFeatureBranchName(
   const resolvedBase = sanitizeFeatureBranchName(
     preferred && preferred.length > 0 ? preferred : AUTO_FEATURE_BRANCH_FALLBACK,
   );
-  const existingNames = new Set(existingBranchNames.map((branch) => branch.toLowerCase()));
+  const existingNames = new Set(existingBranchNames.map((refName) => refName.toLowerCase()));
 
   if (!existingNames.has(resolvedBase)) {
     return resolvedBase;
@@ -80,6 +86,15 @@ export function deriveLocalBranchNameFromRemoteRef(branchName: string): string {
   return branchName.slice(firstSeparatorIndex + 1);
 }
 
+export function buildTemporaryWorktreeBranchName(): string {
+  const token = Effect.runSync(Random.nextUUIDv4).replace(/-/g, "").slice(0, 8).toLowerCase();
+  return `${WORKTREE_BRANCH_PREFIX}/${token}`;
+}
+
+export function isTemporaryWorktreeBranch(refName: string): boolean {
+  return TEMP_WORKTREE_BRANCH_PATTERN.test(refName.trim().toLowerCase());
+}
+
 /**
  * Normalize a git remote URL into a stable comparison key.
  */
@@ -151,139 +166,86 @@ function deriveLocalBranchNameCandidatesFromRemoteRef(
 }
 
 /**
- * Hide `origin/*` remote refs when a matching local branch already exists.
+ * Hide `origin/*` remote refs when a matching local refName already exists.
  */
 export function dedupeRemoteBranchesWithLocalMatches(
-  branches: ReadonlyArray<GitBranch>,
-): ReadonlyArray<GitBranch> {
+  refs: ReadonlyArray<VcsRef>,
+): ReadonlyArray<VcsRef> {
   const localBranchNames = new Set(
-    branches.filter((branch) => !branch.isRemote).map((branch) => branch.name),
+    refs.filter((refName) => !refName.isRemote).map((refName) => refName.name),
   );
 
-  return branches.filter((branch) => {
-    if (!branch.isRemote) {
+  return refs.filter((refName) => {
+    if (!refName.isRemote) {
       return true;
     }
 
-    if (branch.remoteName !== "origin") {
+    if (refName.remoteName !== "origin") {
       return true;
     }
 
     const localBranchCandidates = deriveLocalBranchNameCandidatesFromRemoteRef(
-      branch.name,
-      branch.remoteName,
+      refName.name,
+      refName.remoteName,
     );
     return !localBranchCandidates.some((candidate) => localBranchNames.has(candidate));
   });
 }
 
-function parseGitRemoteHost(remoteUrl: string): string | null {
-  const trimmed = remoteUrl.trim();
-  if (trimmed.length === 0) {
-    return null;
-  }
-
-  if (trimmed.startsWith("git@")) {
-    const hostWithPath = trimmed.slice("git@".length);
-    const separatorIndex = hostWithPath.search(/[:/]/);
-    if (separatorIndex <= 0) {
-      return null;
-    }
-    return hostWithPath.slice(0, separatorIndex).toLowerCase();
-  }
-
-  try {
-    return new URL(trimmed).hostname.toLowerCase();
-  } catch {
-    return null;
-  }
-}
-
-function toBaseUrl(host: string): string {
-  return `https://${host}`;
-}
-
-function isGitHubHost(host: string): boolean {
-  return host === "github.com" || host.includes("github");
-}
-
-function isGitLabHost(host: string): boolean {
-  return host === "gitlab.com" || host.includes("gitlab");
-}
-
-export function detectGitHostingProviderFromRemoteUrl(
+export function detectSourceControlProviderFromGitRemoteUrl(
   remoteUrl: string,
-): GitHostingProvider | null {
-  const host = parseGitRemoteHost(remoteUrl);
-  if (!host) {
-    return null;
-  }
-
-  if (isGitHubHost(host)) {
-    return {
-      kind: "github",
-      name: host === "github.com" ? "GitHub" : "GitHub Self-Hosted",
-      baseUrl: toBaseUrl(host),
-    };
-  }
-
-  if (isGitLabHost(host)) {
-    return {
-      kind: "gitlab",
-      name: host === "gitlab.com" ? "GitLab" : "GitLab Self-Hosted",
-      baseUrl: toBaseUrl(host),
-    };
-  }
-
-  return {
-    kind: "unknown",
-    name: host,
-    baseUrl: toBaseUrl(host),
-  };
+): SourceControlProviderInfo | null {
+  return detectSourceControlProviderFromRemoteUrl(remoteUrl);
 }
 
-const EMPTY_GIT_STATUS_REMOTE: GitStatusRemoteResult = {
+const EMPTY_GIT_STATUS_REMOTE: VcsStatusRemoteResult = {
   hasUpstream: false,
   aheadCount: 0,
   behindCount: 0,
+  aheadOfDefaultCount: 0,
   pr: null,
 };
 
 export function mergeGitStatusParts(
-  local: GitStatusLocalResult,
-  remote: GitStatusRemoteResult | null,
-): GitStatusResult {
+  local: VcsStatusLocalResult,
+  remote: VcsStatusRemoteResult | null,
+): VcsStatusResult {
   return {
     ...local,
     ...(remote ?? EMPTY_GIT_STATUS_REMOTE),
   };
 }
 
-function toRemoteStatusPart(status: GitStatusResult): GitStatusRemoteResult {
+function toRemoteStatusPart(status: VcsStatusResult): VcsStatusRemoteResult {
   return {
     hasUpstream: status.hasUpstream,
     aheadCount: status.aheadCount,
     behindCount: status.behindCount,
+    ...(status.aheadOfDefaultCount === undefined
+      ? {}
+      : { aheadOfDefaultCount: status.aheadOfDefaultCount }),
     pr: status.pr,
   };
 }
 
-function toLocalStatusPart(status: GitStatusResult): GitStatusLocalResult {
+function toLocalStatusPart(status: VcsStatusResult): VcsStatusLocalResult {
   return {
     isRepo: status.isRepo,
-    ...(status.hostingProvider ? { hostingProvider: status.hostingProvider } : {}),
-    hasOriginRemote: status.hasOriginRemote,
-    isDefaultBranch: status.isDefaultBranch,
-    branch: status.branch,
+    ...(status.sourceControlProvider
+      ? { sourceControlProvider: status.sourceControlProvider }
+      : {}),
+    hasPrimaryRemote: status.hasPrimaryRemote,
+    isDefaultRef: status.isDefaultRef,
+    refName: status.refName,
     hasWorkingTreeChanges: status.hasWorkingTreeChanges,
     workingTree: status.workingTree,
   };
 }
 
 export function applyGitStatusStreamEvent(
-  current: GitStatusResult | null,
-  event: GitStatusStreamEvent,
-): GitStatusResult {
+  current: VcsStatusResult | null,
+  event: VcsStatusStreamEvent,
+): VcsStatusResult {
   switch (event._tag) {
     case "snapshot":
       return mergeGitStatusParts(event.local, event.remote);
@@ -294,9 +256,9 @@ export function applyGitStatusStreamEvent(
         return mergeGitStatusParts(
           {
             isRepo: true,
-            hasOriginRemote: false,
-            isDefaultBranch: false,
-            branch: null,
+            hasPrimaryRemote: false,
+            isDefaultRef: false,
+            refName: null,
             hasWorkingTreeChanges: false,
             workingTree: { files: [], insertions: 0, deletions: 0 },
           },
diff --git a/packages/shared/src/keybindings.ts b/packages/shared/src/keybindings.ts
new file mode 100644
index 00000000000..3cc2e913621
--- /dev/null
+++ b/packages/shared/src/keybindings.ts
@@ -0,0 +1,283 @@
+import {
+  type KeybindingRule,
+  type KeybindingShortcut,
+  type KeybindingWhenNode,
+  MAX_KEYBINDINGS_COUNT,
+  MAX_WHEN_EXPRESSION_DEPTH,
+  MODEL_PICKER_JUMP_KEYBINDING_COMMANDS,
+  type ResolvedKeybindingRule,
+  type ResolvedKeybindingsConfig,
+  THREAD_JUMP_KEYBINDING_COMMANDS,
+} from "@t3tools/contracts";
+
+type WhenToken =
+  | { type: "identifier"; value: string }
+  | { type: "not" }
+  | { type: "and" }
+  | { type: "or" }
+  | { type: "lparen" }
+  | { type: "rparen" };
+
+export const DEFAULT_KEYBINDINGS: ReadonlyArray<KeybindingRule> = [
+  { key: "mod+j", command: "terminal.toggle" },
+  { key: "mod+d", command: "terminal.split", when: "terminalFocus" },
+  { key: "mod+n", command: "terminal.new", when: "terminalFocus" },
+  { key: "mod+w", command: "terminal.close", when: "terminalFocus" },
+  { key: "mod+d", command: "diff.toggle", when: "!terminalFocus" },
+  { key: "mod+k", command: "commandPalette.toggle", when: "!terminalFocus" },
+  { key: "mod+n", command: "chat.new", when: "!terminalFocus" },
+  { key: "mod+shift+o", command: "chat.new", when: "!terminalFocus" },
+  { key: "mod+shift+n", command: "chat.newLocal", when: "!terminalFocus" },
+  { key: "mod+shift+m", command: "modelPicker.toggle", when: "!terminalFocus" },
+  { key: "mod+o", command: "editor.openFavorite" },
+  { key: "mod+shift+[", command: "thread.previous" },
+  { key: "mod+shift+]", command: "thread.next" },
+  ...THREAD_JUMP_KEYBINDING_COMMANDS.map((command, index) => ({
+    key: `mod+${index + 1}`,
+    command,
+  })),
+  ...MODEL_PICKER_JUMP_KEYBINDING_COMMANDS.map((command, index) => ({
+    key: `mod+${index + 1}`,
+    command,
+    when: "modelPickerOpen",
+  })),
+];
+
+function normalizeKeyToken(token: string): string {
+  if (token === "space") return " ";
+  if (token === "esc") return "escape";
+  return token;
+}
+
+export function parseKeybindingShortcut(value: string): KeybindingShortcut | null {
+  const rawTokens = value
+    .toLowerCase()
+    .split("+")
+    .map((token) => token.trim());
+  const tokens = [...rawTokens];
+  let trailingEmptyCount = 0;
+  while (tokens[tokens.length - 1] === "") {
+    trailingEmptyCount += 1;
+    tokens.pop();
+  }
+  if (trailingEmptyCount > 0) {
+    tokens.push("+");
+  }
+  if (tokens.some((token) => token.length === 0)) {
+    return null;
+  }
+  if (tokens.length === 0) return null;
+
+  let key: string | null = null;
+  let metaKey = false;
+  let ctrlKey = false;
+  let shiftKey = false;
+  let altKey = false;
+  let modKey = false;
+
+  for (const token of tokens) {
+    switch (token) {
+      case "cmd":
+      case "meta":
+        metaKey = true;
+        break;
+      case "ctrl":
+      case "control":
+        ctrlKey = true;
+        break;
+      case "shift":
+        shiftKey = true;
+        break;
+      case "alt":
+      case "option":
+        altKey = true;
+        break;
+      case "mod":
+        modKey = true;
+        break;
+      default: {
+        if (key !== null) return null;
+        key = normalizeKeyToken(token);
+      }
+    }
+  }
+
+  if (key === null) return null;
+  return {
+    key,
+    metaKey,
+    ctrlKey,
+    shiftKey,
+    altKey,
+    modKey,
+  };
+}
+
+function tokenizeWhenExpression(expression: string): WhenToken[] | null {
+  const tokens: WhenToken[] = [];
+  let index = 0;
+
+  while (index < expression.length) {
+    const current = expression[index];
+    if (!current) break;
+
+    if (/\s/.test(current)) {
+      index += 1;
+      continue;
+    }
+    if (expression.startsWith("&&", index)) {
+      tokens.push({ type: "and" });
+      index += 2;
+      continue;
+    }
+    if (expression.startsWith("||", index)) {
+      tokens.push({ type: "or" });
+      index += 2;
+      continue;
+    }
+    if (current === "!") {
+      tokens.push({ type: "not" });
+      index += 1;
+      continue;
+    }
+    if (current === "(") {
+      tokens.push({ type: "lparen" });
+      index += 1;
+      continue;
+    }
+    if (current === ")") {
+      tokens.push({ type: "rparen" });
+      index += 1;
+      continue;
+    }
+
+    const identifier = /^[A-Za-z_][A-Za-z0-9_.-]*/.exec(expression.slice(index));
+    if (!identifier) {
+      return null;
+    }
+    tokens.push({ type: "identifier", value: identifier[0] });
+    index += identifier[0].length;
+  }
+
+  return tokens;
+}
+
+export function parseKeybindingWhenExpression(expression: string): KeybindingWhenNode | null {
+  const tokens = tokenizeWhenExpression(expression);
+  if (!tokens || tokens.length === 0) return null;
+  let index = 0;
+
+  const parsePrimary = (depth: number): KeybindingWhenNode | null => {
+    if (depth > MAX_WHEN_EXPRESSION_DEPTH) {
+      return null;
+    }
+    const token = tokens[index];
+    if (!token) return null;
+
+    if (token.type === "identifier") {
+      index += 1;
+      return { type: "identifier", name: token.value };
+    }
+
+    if (token.type === "lparen") {
+      index += 1;
+      const expressionNode = parseOr(depth + 1);
+      const closeToken = tokens[index];
+      if (!expressionNode || !closeToken || closeToken.type !== "rparen") {
+        return null;
+      }
+      index += 1;
+      return expressionNode;
+    }
+
+    return null;
+  };
+
+  const parseUnary = (depth: number): KeybindingWhenNode | null => {
+    let notCount = 0;
+    while (tokens[index]?.type === "not") {
+      index += 1;
+      notCount += 1;
+      if (notCount > MAX_WHEN_EXPRESSION_DEPTH) {
+        return null;
+      }
+    }
+
+    let node = parsePrimary(depth);
+    if (!node) return null;
+
+    while (notCount > 0) {
+      node = { type: "not", node };
+      notCount -= 1;
+    }
+
+    return node;
+  };
+
+  const parseAnd = (depth: number): KeybindingWhenNode | null => {
+    let left = parseUnary(depth);
+    if (!left) return null;
+
+    while (tokens[index]?.type === "and") {
+      index += 1;
+      const right = parseUnary(depth);
+      if (!right) return null;
+      left = { type: "and", left, right };
+    }
+
+    return left;
+  };
+
+  const parseOr = (depth: number): KeybindingWhenNode | null => {
+    let left = parseAnd(depth);
+    if (!left) return null;
+
+    while (tokens[index]?.type === "or") {
+      index += 1;
+      const right = parseAnd(depth);
+      if (!right) return null;
+      left = { type: "or", left, right };
+    }
+
+    return left;
+  };
+
+  const ast = parseOr(0);
+  if (!ast || index !== tokens.length) return null;
+  return ast;
+}
+
+export function compileResolvedKeybindingRule(rule: KeybindingRule): ResolvedKeybindingRule | null {
+  const shortcut = parseKeybindingShortcut(rule.key);
+  if (!shortcut) return null;
+
+  if (rule.when !== undefined) {
+    const whenAst = parseKeybindingWhenExpression(rule.when);
+    if (!whenAst) return null;
+    return {
+      command: rule.command,
+      shortcut,
+      whenAst,
+    };
+  }
+
+  return {
+    command: rule.command,
+    shortcut,
+  };
+}
+
+export function compileResolvedKeybindingsConfig(
+  config: ReadonlyArray<KeybindingRule>,
+): ResolvedKeybindingsConfig {
+  const compiled: ResolvedKeybindingRule[] = [];
+  for (const rule of config) {
+    const result = compileResolvedKeybindingRule(rule);
+    if (result) {
+      compiled.push(result);
+    }
+  }
+  return compiled.slice(-MAX_KEYBINDINGS_COUNT);
+}
+
+export const DEFAULT_RESOLVED_KEYBINDINGS = compileResolvedKeybindingsConfig(DEFAULT_KEYBINDINGS);
diff --git a/packages/shared/src/logging.ts b/packages/shared/src/logging.ts
index 98fee9464c7..8e1d1019e1d 100644
--- a/packages/shared/src/logging.ts
+++ b/packages/shared/src/logging.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import fs from "node:fs";
 import path from "node:path";
 
diff --git a/packages/shared/src/model.test.ts b/packages/shared/src/model.test.ts
index 62313f360b7..61cc8d181f4 100644
--- a/packages/shared/src/model.test.ts
+++ b/packages/shared/src/model.test.ts
@@ -1,56 +1,81 @@
 import { describe, expect, it } from "vitest";
-import { DEFAULT_MODEL_BY_PROVIDER, type ModelCapabilities } from "@t3tools/contracts";
+import {
+  DEFAULT_MODEL,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ModelCapabilities,
+} from "@t3tools/contracts";
 
 import {
   applyClaudePromptEffortPrefix,
-  getDefaultContextWindow,
-  getDefaultEffort,
-  hasContextWindowOption,
-  hasEffortLevel,
+  buildProviderOptionSelectionsFromDescriptors,
+  createModelCapabilities,
+  createModelSelection,
+  getModelSelectionBooleanOptionValue,
+  getModelSelectionStringOptionValue,
+  getProviderOptionDescriptors,
+  getProviderOptionBooleanSelectionValue,
+  getProviderOptionStringSelectionValue,
   isClaudeUltrathinkPrompt,
-  normalizeClaudeModelOptionsWithCapabilities,
-  normalizeCodexModelOptionsWithCapabilities,
   normalizeModelSlug,
-  resolveApiModelId,
-  resolveContextWindow,
-  resolveEffort,
-  resolveModelSlug,
   resolveModelSlugForProvider,
   resolveSelectableModel,
   trimOrNull,
-} from "./model";
-
-const codexCaps: ModelCapabilities = {
-  reasoningEffortLevels: [
-    { value: "xhigh", label: "Extra High" },
-    { value: "high", label: "High", isDefault: true },
+} from "./model.ts";
+
+const codexCaps: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [
+    {
+      id: "reasoningEffort",
+      label: "Reasoning",
+      type: "select",
+      options: [
+        { id: "xhigh", label: "Extra High" },
+        { id: "high", label: "High", isDefault: true },
+      ],
+      currentValue: "high",
+    },
+    {
+      id: "fastMode",
+      label: "Fast Mode",
+      type: "boolean",
+    },
   ],
-  supportsFastMode: true,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-};
+});
 
-const claudeCaps: ModelCapabilities = {
-  reasoningEffortLevels: [
-    { value: "medium", label: "Medium" },
-    { value: "high", label: "High", isDefault: true },
-    { value: "ultrathink", label: "Ultrathink" },
-  ],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [
-    { value: "200k", label: "200k" },
-    { value: "1m", label: "1M", isDefault: true },
+const claudeCaps: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [
+    {
+      id: "effort",
+      label: "Reasoning",
+      type: "select",
+      options: [
+        { id: "medium", label: "Medium" },
+        { id: "high", label: "High", isDefault: true },
+        { id: "ultrathink", label: "Ultrathink" },
+      ],
+      currentValue: "high",
+      promptInjectedValues: ["ultrathink"],
+    },
+    {
+      id: "contextWindow",
+      label: "Context Window",
+      type: "select",
+      options: [
+        { id: "200k", label: "200k" },
+        { id: "1m", label: "1M", isDefault: true },
+      ],
+      currentValue: "1m",
+    },
   ],
-  promptInjectedEffortLevels: ["ultrathink"],
-};
+});
 
 describe("normalizeModelSlug", () => {
   it("maps known aliases to canonical slugs", () => {
+    const claude = ProviderDriverKind.make("claudeAgent");
     expect(normalizeModelSlug("gpt-5-codex")).toBe("gpt-5.4");
     expect(normalizeModelSlug("5.3")).toBe("gpt-5.3-codex");
-    expect(normalizeModelSlug("sonnet", "claudeAgent")).toBe("claude-sonnet-4-6");
+    expect(normalizeModelSlug("sonnet", claude)).toBe("claude-sonnet-4-6");
   });
 
   it("returns null for empty or missing values", () => {
@@ -61,17 +86,20 @@ describe("normalizeModelSlug", () => {
   });
 });
 
-describe("resolveModelSlug", () => {
+describe("resolveModelSlugForProvider", () => {
   it("returns defaults when the model is missing", () => {
-    expect(resolveModelSlug(undefined, "codex")).toBe(DEFAULT_MODEL_BY_PROVIDER.codex);
-
-    expect(resolveModelSlugForProvider("claudeAgent", undefined)).toBe(
-      DEFAULT_MODEL_BY_PROVIDER.claudeAgent,
+    expect(resolveModelSlugForProvider(ProviderDriverKind.make("codex"), undefined)).toBe(
+      DEFAULT_MODEL,
+    );
+    expect(resolveModelSlugForProvider(ProviderDriverKind.make("ollama"), undefined)).toBe(
+      DEFAULT_MODEL,
     );
   });
 
   it("preserves normalized unknown models", () => {
-    expect(resolveModelSlug("custom/internal-model", "codex")).toBe("custom/internal-model");
+    expect(
+      resolveModelSlugForProvider(ProviderDriverKind.make("codex"), "custom/internal-model"),
+    ).toBe("custom/internal-model");
   });
 });
 
@@ -81,62 +109,21 @@ describe("resolveSelectableModel", () => {
       { slug: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
       { slug: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
     ];
-    expect(resolveSelectableModel("codex", "gpt-5.3-codex", options)).toBe("gpt-5.3-codex");
-    expect(resolveSelectableModel("codex", "gpt-5.3 codex", options)).toBe("gpt-5.3-codex");
-    expect(resolveSelectableModel("claudeAgent", "sonnet", options)).toBe("claude-sonnet-4-6");
-  });
-});
-
-describe("capability helpers", () => {
-  it("reads default efforts", () => {
-    expect(getDefaultEffort(codexCaps)).toBe("high");
-    expect(getDefaultEffort(claudeCaps)).toBe("high");
-  });
-
-  it("checks effort support", () => {
-    expect(hasEffortLevel(codexCaps, "xhigh")).toBe(true);
-    expect(hasEffortLevel(codexCaps, "max")).toBe(false);
-  });
-});
-
-describe("resolveEffort", () => {
-  it("returns the explicit value when supported and not prompt-injected", () => {
-    expect(resolveEffort(codexCaps, "xhigh")).toBe("xhigh");
-    expect(resolveEffort(codexCaps, "high")).toBe("high");
-    expect(resolveEffort(claudeCaps, "medium")).toBe("medium");
-  });
-
-  it("falls back to default when value is unsupported", () => {
-    expect(resolveEffort(codexCaps, "bogus")).toBe("high");
-    expect(resolveEffort(claudeCaps, "bogus")).toBe("high");
-  });
-
-  it("returns the default when no value is provided", () => {
-    expect(resolveEffort(codexCaps, undefined)).toBe("high");
-    expect(resolveEffort(codexCaps, null)).toBe("high");
-    expect(resolveEffort(codexCaps, "")).toBe("high");
-    expect(resolveEffort(codexCaps, "  ")).toBe("high");
-  });
-
-  it("excludes prompt-injected efforts and falls back to default", () => {
-    expect(resolveEffort(claudeCaps, "ultrathink")).toBe("high");
-  });
-
-  it("returns undefined for models with no effort levels", () => {
-    const noCaps: ModelCapabilities = {
-      reasoningEffortLevels: [],
-      supportsFastMode: false,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    };
-    expect(resolveEffort(noCaps, undefined)).toBeUndefined();
-    expect(resolveEffort(noCaps, "high")).toBeUndefined();
+    expect(resolveSelectableModel(ProviderDriverKind.make("codex"), "gpt-5.3-codex", options)).toBe(
+      "gpt-5.3-codex",
+    );
+    expect(resolveSelectableModel(ProviderDriverKind.make("codex"), "gpt-5.3 codex", options)).toBe(
+      "gpt-5.3-codex",
+    );
+    expect(resolveSelectableModel(ProviderDriverKind.make("claudeAgent"), "sonnet", options)).toBe(
+      "claude-sonnet-4-6",
+    );
   });
 });
 
 describe("misc helpers", () => {
   it("detects ultrathink prompts", () => {
+    expect(isClaudeUltrathinkPrompt("Please ultrathink about this")).toBe(true);
     expect(isClaudeUltrathinkPrompt("Ultrathink:\nInvestigate")).toBe(true);
     expect(isClaudeUltrathinkPrompt("Investigate")).toBe(false);
   });
@@ -156,130 +143,88 @@ describe("misc helpers", () => {
   });
 });
 
-describe("context window helpers", () => {
-  it("reads default context window", () => {
-    expect(getDefaultContextWindow(claudeCaps)).toBe("1m");
-  });
-
-  it("returns null for models without context window options", () => {
-    expect(getDefaultContextWindow(codexCaps)).toBeNull();
-  });
-
-  it("checks context window support", () => {
-    expect(hasContextWindowOption(claudeCaps, "1m")).toBe(true);
-    expect(hasContextWindowOption(claudeCaps, "200k")).toBe(true);
-    expect(hasContextWindowOption(claudeCaps, "bogus")).toBe(false);
-    expect(hasContextWindowOption(codexCaps, "1m")).toBe(false);
-  });
-});
-
-describe("resolveContextWindow", () => {
-  it("returns the explicit value when supported", () => {
-    expect(resolveContextWindow(claudeCaps, "200k")).toBe("200k");
-    expect(resolveContextWindow(claudeCaps, "1m")).toBe("1m");
-  });
-
-  it("falls back to default when value is unsupported", () => {
-    expect(resolveContextWindow(claudeCaps, "bogus")).toBe("1m");
-  });
-
-  it("returns the default when no value is provided", () => {
-    expect(resolveContextWindow(claudeCaps, undefined)).toBe("1m");
-    expect(resolveContextWindow(claudeCaps, null)).toBe("1m");
-    expect(resolveContextWindow(claudeCaps, "")).toBe("1m");
-  });
-
-  it("returns undefined for models with no context window options", () => {
-    expect(resolveContextWindow(codexCaps, undefined)).toBeUndefined();
-    expect(resolveContextWindow(codexCaps, "1m")).toBeUndefined();
-  });
-});
-
-describe("resolveApiModelId", () => {
-  it("appends [1m] suffix for 1m context window", () => {
-    expect(
-      resolveApiModelId({
-        provider: "claudeAgent",
-        model: "claude-opus-4-6",
-        options: { contextWindow: "1m" },
-      }),
-    ).toBe("claude-opus-4-6[1m]");
-  });
-
-  it("returns the model as-is for 200k context window", () => {
+describe("descriptor helpers", () => {
+  it("applies selection values to capability descriptors", () => {
     expect(
-      resolveApiModelId({
-        provider: "claudeAgent",
-        model: "claude-opus-4-6",
-        options: { contextWindow: "200k" },
+      getProviderOptionDescriptors({
+        caps: claudeCaps,
+        selections: [
+          { id: "effort", value: "medium" },
+          { id: "contextWindow", value: "200k" },
+        ],
       }),
-    ).toBe("claude-opus-4-6");
-  });
-
-  it("returns the model as-is when no context window is set", () => {
-    expect(resolveApiModelId({ provider: "claudeAgent", model: "claude-opus-4-6" })).toBe(
-      "claude-opus-4-6",
-    );
-    expect(
-      resolveApiModelId({ provider: "claudeAgent", model: "claude-opus-4-6", options: {} }),
-    ).toBe("claude-opus-4-6");
-  });
+    ).toEqual([
+      {
+        id: "effort",
+        label: "Reasoning",
+        type: "select",
+        options: [
+          { id: "medium", label: "Medium" },
+          { id: "high", label: "High", isDefault: true },
+          { id: "ultrathink", label: "Ultrathink" },
+        ],
+        currentValue: "medium",
+        promptInjectedValues: ["ultrathink"],
+      },
+      {
+        id: "contextWindow",
+        label: "Context Window",
+        type: "select",
+        options: [
+          { id: "200k", label: "200k" },
+          { id: "1m", label: "1M", isDefault: true },
+        ],
+        currentValue: "200k",
+      },
+    ]);
+  });
+
+  it("builds wire-format option selections from descriptors", () => {
+    const descriptors = getProviderOptionDescriptors({
+      caps: codexCaps,
+      selections: [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ],
+    });
 
-  it("returns the model as-is for Codex selections", () => {
-    expect(resolveApiModelId({ provider: "codex", model: "gpt-5.4" })).toBe("gpt-5.4");
+    expect(buildProviderOptionSelectionsFromDescriptors(descriptors)).toEqual([
+      { id: "reasoningEffort", value: "high" },
+      { id: "fastMode", value: true },
+    ]);
   });
-});
 
-describe("normalize*ModelOptionsWithCapabilities", () => {
-  it("preserves explicit false codex fast mode", () => {
+  it("stores option selection arrays in model selections", () => {
     expect(
-      normalizeCodexModelOptionsWithCapabilities(codexCaps, {
-        reasoningEffort: "high",
-        fastMode: false,
-      }),
+      createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ]),
     ).toEqual({
-      reasoningEffort: "high",
-      fastMode: false,
+      instanceId: "codex",
+      model: "gpt-5.4",
+      options: [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ],
     });
   });
 
-  it("preserves the default Claude context window explicitly", () => {
-    expect(
-      normalizeClaudeModelOptionsWithCapabilities(
-        {
-          ...claudeCaps,
-          contextWindowOptions: [
-            { value: "200k", label: "200k", isDefault: true },
-            { value: "1m", label: "1M" },
-          ],
-        },
-        {
-          effort: "high",
-          contextWindow: "200k",
-        },
-      ),
-    ).toEqual({
-      effort: "high",
-      contextWindow: "200k",
-    });
-  });
+  it("reads typed option selection values", () => {
+    const selection = createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+      { id: "reasoningEffort", value: "high" },
+      { id: "fastMode", value: true },
+    ]);
 
-  it("omits unsupported Claude context window options", () => {
+    expect(getProviderOptionStringSelectionValue(selection.options, "reasoningEffort")).toBe(
+      "high",
+    );
+    expect(getProviderOptionStringSelectionValue(selection.options, "fastMode")).toBeUndefined();
+    expect(getProviderOptionBooleanSelectionValue(selection.options, "fastMode")).toBe(true);
     expect(
-      normalizeClaudeModelOptionsWithCapabilities(
-        {
-          ...claudeCaps,
-          reasoningEffortLevels: [],
-          supportsThinkingToggle: true,
-          contextWindowOptions: [],
-        },
-        {
-          thinking: true,
-          contextWindow: "1m",
-        },
-      ),
-    ).toEqual({
-      thinking: true,
-    });
+      getProviderOptionBooleanSelectionValue(selection.options, "reasoningEffort"),
+    ).toBeUndefined();
+    expect(getModelSelectionStringOptionValue(selection, "reasoningEffort")).toBe("high");
+    expect(getModelSelectionBooleanOptionValue(selection, "fastMode")).toBe(true);
   });
 });
diff --git a/packages/shared/src/model.ts b/packages/shared/src/model.ts
index 2aa378cf63d..9fdbd6c0447 100644
--- a/packages/shared/src/model.ts
+++ b/packages/shared/src/model.ts
@@ -1,120 +1,231 @@
 import {
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
   MODEL_SLUG_ALIASES_BY_PROVIDER,
-  type ClaudeCodeEffort,
-  type ClaudeModelOptions,
-  type CodexModelOptions,
   type ModelCapabilities,
   type ModelSelection,
-  type ProviderKind,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ProviderOptionDescriptor,
+  type ProviderOptionSelection,
 } from "@t3tools/contracts";
 
+const DEFAULT_PROVIDER_DRIVER_KIND = ProviderDriverKind.make("codex");
+
 export interface SelectableModelOption {
   slug: string;
   name: string;
 }
 
-// ── Effort helpers ────────────────────────────────────────────────────
+export function createModelCapabilities(input: {
+  optionDescriptors: ReadonlyArray<ProviderOptionDescriptor>;
+}): ModelCapabilities {
+  return {
+    optionDescriptors: input.optionDescriptors.map(cloneDescriptor),
+  };
+}
 
-/** Check whether a capabilities object includes a given effort value. */
-export function hasEffortLevel(caps: ModelCapabilities, value: string): boolean {
-  return caps.reasoningEffortLevels.some((l) => l.value === value);
+function getRawSelectionValueById(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): string | boolean | undefined {
+  const selection = selections?.find((candidate) => candidate.id === id);
+  return selection?.value;
 }
 
-/** Return the default effort value for a capabilities object, or null if none. */
-export function getDefaultEffort(caps: ModelCapabilities): string | null {
-  return caps.reasoningEffortLevels.find((l) => l.isDefault)?.value ?? null;
+export function getProviderOptionSelectionValue(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): string | boolean | undefined {
+  return getRawSelectionValueById(selections, id);
 }
 
-/**
- * Resolve a raw effort option against capabilities.
- *
- * Returns the effective effort value — the explicit value if supported and not
- * prompt-injected, otherwise the model's default. Returns `undefined` only
- * when the model has no effort levels at all.
- *
- * Prompt-injected efforts (e.g. "ultrathink") are excluded because they are
- * applied via prompt text, not the effort API parameter.
- */
-export function resolveEffort(
-  caps: ModelCapabilities,
+export function getProviderOptionStringSelectionValue(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): string | undefined {
+  const value = getProviderOptionSelectionValue(selections, id);
+  return typeof value === "string" ? value : undefined;
+}
+
+export function getProviderOptionBooleanSelectionValue(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): boolean | undefined {
+  const value = getProviderOptionSelectionValue(selections, id);
+  return typeof value === "boolean" ? value : undefined;
+}
+
+export function getModelSelectionOptionValue(
+  modelSelection: ModelSelection | null | undefined,
+  id: string,
+): string | boolean | undefined {
+  return getProviderOptionSelectionValue(modelSelection?.options, id);
+}
+
+export function getModelSelectionStringOptionValue(
+  modelSelection: ModelSelection | null | undefined,
+  id: string,
+): string | undefined {
+  return getProviderOptionStringSelectionValue(modelSelection?.options, id);
+}
+
+export function getModelSelectionBooleanOptionValue(
+  modelSelection: ModelSelection | null | undefined,
+  id: string,
+): boolean | undefined {
+  return getProviderOptionBooleanSelectionValue(modelSelection?.options, id);
+}
+
+function resolveDescriptorChoiceValue(
+  descriptor: Extract<ProviderOptionDescriptor, { type: "select" }>,
   raw: string | null | undefined,
 ): string | undefined {
-  const defaultValue = getDefaultEffort(caps);
-  const trimmed = typeof raw === "string" ? raw.trim() : null;
+  const trimmed = trimOrNull(raw);
+  if (!trimmed) {
+    return descriptor.currentValue ?? descriptor.options.find((option) => option.isDefault)?.id;
+  }
+  if (descriptor.options.length === 0) {
+    return trimmed;
+  }
   if (
-    trimmed &&
-    !caps.promptInjectedEffortLevels.includes(trimmed) &&
-    hasEffortLevel(caps, trimmed)
+    descriptor.promptInjectedValues?.includes(trimmed) &&
+    descriptor.options.some((option) => option.id === trimmed)
   ) {
+    return descriptor.options.find((option) => option.isDefault)?.id;
+  }
+  if (descriptor.options.some((option) => option.id === trimmed)) {
     return trimmed;
   }
-  return defaultValue ?? undefined;
+  return descriptor.currentValue ?? descriptor.options.find((option) => option.isDefault)?.id;
 }
 
-// ── Context window helpers ───────────────────────────────────────────
+function cloneDescriptor(descriptor: ProviderOptionDescriptor): ProviderOptionDescriptor {
+  return descriptor.type === "select"
+    ? {
+        ...descriptor,
+        options: [...descriptor.options],
+        ...(descriptor.promptInjectedValues
+          ? { promptInjectedValues: [...descriptor.promptInjectedValues] }
+          : {}),
+      }
+    : { ...descriptor };
+}
 
-/** Check whether a capabilities object includes a given context window value. */
-export function hasContextWindowOption(caps: ModelCapabilities, value: string): boolean {
-  return caps.contextWindowOptions.some((o) => o.value === value);
+function cloneSelection(selection: ProviderOptionSelection): ProviderOptionSelection {
+  return { ...selection };
 }
 
-/** Return the default context window value, or `null` if none is defined. */
-export function getDefaultContextWindow(caps: ModelCapabilities): string | null {
-  return caps.contextWindowOptions.find((o) => o.isDefault)?.value ?? null;
+function withDescriptorCurrentValue(
+  descriptor: ProviderOptionDescriptor,
+  rawCurrentValue: string | boolean | undefined,
+): ProviderOptionDescriptor {
+  if (descriptor.type === "boolean") {
+    if (typeof rawCurrentValue === "boolean") {
+      return {
+        ...descriptor,
+        currentValue: rawCurrentValue,
+      };
+    }
+    return descriptor;
+  }
+  const currentValue =
+    typeof rawCurrentValue === "string"
+      ? resolveDescriptorChoiceValue(descriptor, rawCurrentValue)
+      : resolveDescriptorChoiceValue(descriptor, descriptor.currentValue);
+  if (!currentValue) {
+    const { currentValue: _unusedCurrentValue, ...rest } = descriptor;
+    return rest;
+  }
+  return {
+    ...descriptor,
+    currentValue,
+  };
 }
 
-/**
- * Resolve a raw `contextWindow` option against capabilities.
- *
- * Returns the effective context window value — the explicit value if supported,
- * otherwise the model's default. Returns `undefined` only when the model has
- * no context window options at all.
- *
- * Unlike effort levels (where the API has matching defaults), the context
- * window requires an explicit API suffix (e.g. `[1m]`), so we always preserve
- * the resolved value to avoid ambiguity between "user chose the default" and
- * "not specified".
- */
-export function resolveContextWindow(
-  caps: ModelCapabilities,
-  raw: string | null | undefined,
+export function getProviderOptionDescriptors(input: {
+  caps: ModelCapabilities;
+  selections?: ReadonlyArray<ProviderOptionSelection> | null | undefined;
+}): ReadonlyArray<ProviderOptionDescriptor> {
+  const { caps, selections } = input;
+  const baseDescriptors = (caps.optionDescriptors ?? []).map(cloneDescriptor);
+
+  return baseDescriptors.map((descriptor) =>
+    withDescriptorCurrentValue(
+      descriptor,
+      getRawSelectionValueById(selections, descriptor.id) ?? descriptor.currentValue,
+    ),
+  );
+}
+
+export function getProviderOptionCurrentValue(
+  descriptor: ProviderOptionDescriptor | null | undefined,
+): string | boolean | undefined {
+  if (!descriptor) {
+    return undefined;
+  }
+  if (descriptor.type === "boolean") {
+    return descriptor.currentValue;
+  }
+  if (descriptor.currentValue) {
+    return descriptor.currentValue;
+  }
+  return descriptor.options.find((option) => option.isDefault)?.id;
+}
+
+export function getProviderOptionCurrentLabel(
+  descriptor: ProviderOptionDescriptor | null | undefined,
 ): string | undefined {
-  const defaultValue = getDefaultContextWindow(caps);
-  if (!raw) return defaultValue ?? undefined;
-  return hasContextWindowOption(caps, raw) ? raw : (defaultValue ?? undefined);
+  if (!descriptor) {
+    return undefined;
+  }
+  if (descriptor.type === "boolean") {
+    return typeof descriptor.currentValue === "boolean"
+      ? descriptor.currentValue
+        ? "On"
+        : "Off"
+      : undefined;
+  }
+  const currentValue = getProviderOptionCurrentValue(descriptor);
+  if (typeof currentValue !== "string") {
+    return undefined;
+  }
+  return descriptor.options.find((option) => option.id === currentValue)?.label;
 }
 
-export function normalizeCodexModelOptionsWithCapabilities(
-  caps: ModelCapabilities,
-  modelOptions: CodexModelOptions | null | undefined,
-): CodexModelOptions | undefined {
-  const reasoningEffort = resolveEffort(caps, modelOptions?.reasoningEffort);
-  const fastMode = caps.supportsFastMode ? modelOptions?.fastMode : undefined;
-  const nextOptions: CodexModelOptions = {
-    ...(reasoningEffort
-      ? { reasoningEffort: reasoningEffort as CodexModelOptions["reasoningEffort"] }
-      : {}),
-    ...(fastMode !== undefined ? { fastMode } : {}),
-  };
-  return Object.keys(nextOptions).length > 0 ? nextOptions : undefined;
+export function buildProviderOptionSelectionsFromDescriptors(
+  descriptors: ReadonlyArray<ProviderOptionDescriptor> | null | undefined,
+): Array<ProviderOptionSelection> | undefined {
+  if (!descriptors || descriptors.length === 0) {
+    return undefined;
+  }
+
+  const nextSelections: Array<ProviderOptionSelection> = [];
+
+  for (const descriptor of descriptors) {
+    const value = getProviderOptionCurrentValue(descriptor);
+    if (typeof value === "string" || typeof value === "boolean") {
+      nextSelections.push({ id: descriptor.id, value });
+    }
+  }
+
+  return nextSelections.length > 0 ? nextSelections : undefined;
 }
 
-export function normalizeClaudeModelOptionsWithCapabilities(
-  caps: ModelCapabilities,
-  modelOptions: ClaudeModelOptions | null | undefined,
-): ClaudeModelOptions | undefined {
-  const effort = resolveEffort(caps, modelOptions?.effort);
-  const thinking = caps.supportsThinkingToggle ? modelOptions?.thinking : undefined;
-  const fastMode = caps.supportsFastMode ? modelOptions?.fastMode : undefined;
-  const contextWindow = resolveContextWindow(caps, modelOptions?.contextWindow);
-  const nextOptions: ClaudeModelOptions = {
-    ...(thinking !== undefined ? { thinking } : {}),
-    ...(effort ? { effort: effort as ClaudeModelOptions["effort"] } : {}),
-    ...(fastMode !== undefined ? { fastMode } : {}),
-    ...(contextWindow !== undefined ? { contextWindow } : {}),
-  };
-  return Object.keys(nextOptions).length > 0 ? nextOptions : undefined;
+export function getModelSelectionOptionDescriptors(
+  modelSelection: ModelSelection | null | undefined,
+  caps?: ModelCapabilities | null | undefined,
+): ReadonlyArray<ProviderOptionDescriptor> {
+  if (!modelSelection) {
+    return [];
+  }
+  if (!caps) {
+    return [];
+  }
+  return getProviderOptionDescriptors({
+    caps,
+    selections: modelSelection.options,
+  });
 }
 
 export function isClaudeUltrathinkPrompt(text: string | null | undefined): boolean {
@@ -123,7 +234,7 @@ export function isClaudeUltrathinkPrompt(text: string | null | undefined): boole
 
 export function normalizeModelSlug(
   model: string | null | undefined,
-  provider: ProviderKind = "codex",
+  provider: ProviderDriverKind = DEFAULT_PROVIDER_DRIVER_KIND,
 ): string | null {
   if (typeof model !== "string") {
     return null;
@@ -134,7 +245,7 @@ export function normalizeModelSlug(
     return null;
   }
 
-  const aliases = MODEL_SLUG_ALIASES_BY_PROVIDER[provider] as Record<string, string>;
+  const aliases = MODEL_SLUG_ALIASES_BY_PROVIDER[provider] ?? {};
   const aliased = Object.prototype.hasOwnProperty.call(aliases, trimmed)
     ? aliases[trimmed]
     : undefined;
@@ -142,7 +253,7 @@ export function normalizeModelSlug(
 }
 
 export function resolveSelectableModel(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   value: string | null | undefined,
   options: ReadonlyArray<SelectableModelOption>,
 ): string | null {
@@ -174,16 +285,16 @@ export function resolveSelectableModel(
   return resolved ? resolved.slug : null;
 }
 
-export function resolveModelSlug(model: string | null | undefined, provider: ProviderKind): string {
+function resolveModelSlug(model: string | null | undefined, provider: ProviderDriverKind): string {
   const normalized = normalizeModelSlug(model, provider);
   if (!normalized) {
-    return DEFAULT_MODEL_BY_PROVIDER[provider];
+    return DEFAULT_MODEL_BY_PROVIDER[provider] ?? DEFAULT_MODEL;
   }
   return normalized;
 }
 
 export function resolveModelSlugForProvider(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   model: string | null | undefined,
 ): string {
   return resolveModelSlug(model, provider);
@@ -196,36 +307,51 @@ export function trimOrNull<T extends string>(value: T | null | undefined): T | n
   return trimmed || null;
 }
 
+function cloneSelections(
+  selections: ReadonlyArray<ProviderOptionSelection>,
+): Array<ProviderOptionSelection> {
+  return selections.map(cloneSelection);
+}
+
+export function createModelSelection(
+  instanceId: ProviderInstanceId,
+  model: string,
+  options?: ReadonlyArray<ProviderOptionSelection> | null,
+): ModelSelection {
+  const selections = options ? cloneSelections(options) : [];
+  const base: ModelSelection = {
+    instanceId,
+    model,
+  };
+  return selections.length > 0 ? { ...base, options: selections } : base;
+}
+
 /**
- * Resolve the actual API model identifier from a model selection.
- *
- * Provider-aware: each provider can map `contextWindow` (or other options)
- * to whatever the API requires — a model-id suffix, a separate parameter, etc.
- * The canonical slug stored in the selection stays unchanged so the
- * capabilities system keeps working.
+ * Returns the effort value if it is a prompt-injected value according to
+ * any select descriptor in the given capabilities, or null otherwise.
  *
- * Expects `contextWindow` to already be resolved (via `resolveContextWindow`)
- * to the effective value, not stripped to `undefined` for defaults.
+ * Unlike a single `find`, this checks every descriptor so that the
+ * correct descriptor's `promptInjectedValues` list is consulted even when
+ * multiple select descriptors exist.
  */
-export function resolveApiModelId(modelSelection: ModelSelection): string {
-  switch (modelSelection.provider) {
-    case "claudeAgent": {
-      switch (modelSelection.options?.contextWindow) {
-        case "1m":
-          return `${modelSelection.model}[1m]`;
-        default:
-          return modelSelection.model;
-      }
-    }
-    default: {
-      return modelSelection.model;
+export function resolvePromptInjectedEffort(
+  caps: ModelCapabilities,
+  rawEffort: string | null | undefined,
+): string | null {
+  const trimmed = trimOrNull(rawEffort);
+  if (!trimmed) return null;
+  const descriptors = getProviderOptionDescriptors({ caps });
+  for (const descriptor of descriptors) {
+    if (descriptor.type === "select" && descriptor.promptInjectedValues?.includes(trimmed)) {
+      return trimmed;
     }
   }
+  return null;
 }
 
 export function applyClaudePromptEffortPrefix(
   text: string,
-  effort: ClaudeCodeEffort | null | undefined,
+  effort: string | null | undefined,
 ): string {
   const trimmed = text.trim();
   if (!trimmed) {
diff --git a/packages/shared/src/observability.test.ts b/packages/shared/src/observability.test.ts
new file mode 100644
index 00000000000..5e9894550a5
--- /dev/null
+++ b/packages/shared/src/observability.test.ts
@@ -0,0 +1,313 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Path from "effect/Path";
+import * as References from "effect/References";
+import * as Schema from "effect/Schema";
+import * as Tracer from "effect/Tracer";
+
+import {
+  compactTraceAttributes,
+  makeLocalFileTracer,
+  makeTraceSink,
+  type TraceRecord,
+} from "./observability.ts";
+
+const TraceRecordLine = Schema.Struct({
+  name: Schema.String,
+  spanId: Schema.String,
+  parentSpanId: Schema.optional(Schema.String),
+  attributes: Schema.Record(Schema.String, Schema.Unknown),
+  events: Schema.Array(
+    Schema.Struct({
+      name: Schema.String,
+      attributes: Schema.Record(Schema.String, Schema.Unknown),
+    }),
+  ),
+  exit: Schema.optional(
+    Schema.Struct({
+      _tag: Schema.String,
+    }),
+  ),
+});
+
+const decodeTraceRecordLine = Schema.decodeUnknownSync(Schema.fromJsonString(TraceRecordLine));
+
+const makeRecord = (name: string, suffix = ""): TraceRecord => ({
+  type: "effect-span",
+  name,
+  traceId: `trace-${name}-${suffix}`,
+  spanId: `span-${name}-${suffix}`,
+  sampled: true,
+  kind: "internal",
+  startTimeUnixNano: "1",
+  endTimeUnixNano: "2",
+  durationMs: 1,
+  attributes: {
+    payload: suffix,
+  },
+  events: [],
+  links: [],
+  exit: {
+    _tag: "Success",
+  },
+});
+
+const readTraceRecords = Effect.fn("readTraceRecords")(function* (tracePath: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  return (yield* fileSystem.readFileString(tracePath))
+    .trim()
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => decodeTraceRecordLine(line));
+});
+
+const makeTestLayer = (tracePath: string) =>
+  Layer.mergeAll(
+    Layer.effect(
+      Tracer.Tracer,
+      makeLocalFileTracer({
+        filePath: tracePath,
+        maxBytes: 1024 * 1024,
+        maxFiles: 2,
+        batchWindowMs: 10_000,
+      }),
+    ),
+    Logger.layer([Logger.tracerLogger], { mergeWithExisting: false }),
+    Layer.succeed(References.MinimumLogLevel, "Info"),
+  );
+
+const nodeServicesIt = it.layer(NodeServices.layer);
+
+describe("observability", () => {
+  it("normalizes circular arrays, maps, and sets without recursing forever", () => {
+    const array: Array<unknown> = ["alpha"];
+    array.push(array);
+
+    const map = new Map<string, unknown>();
+    map.set("self", map);
+
+    const set = new Set<unknown>();
+    set.add(set);
+
+    assert.deepStrictEqual(
+      compactTraceAttributes({
+        array,
+        map,
+        set,
+      }),
+      {
+        array: ["alpha", "[Circular]"],
+        map: { self: "[Circular]" },
+        set: ["[Circular]"],
+      },
+    );
+  });
+
+  it("normalizes invalid dates without throwing", () => {
+    // @effect-diagnostics-next-line globalDate:off
+    const invalidDate = new Date("not-a-real-date");
+    assert.deepStrictEqual(
+      compactTraceAttributes({
+        invalidDate,
+      }),
+      {
+        invalidDate: "Invalid Date",
+      },
+    );
+  });
+
+  nodeServicesIt("node services", (it) => {
+    it.effect("flushes buffered trace records on close", () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-trace-sink-" });
+          const tracePath = path.join(tempDir, "shared.trace.ndjson");
+
+          const sink = yield* makeTraceSink({
+            filePath: tracePath,
+            maxBytes: 1024,
+            maxFiles: 2,
+            batchWindowMs: 10_000,
+          });
+
+          sink.push(makeRecord("alpha"));
+          sink.push(makeRecord("beta"));
+          yield* sink.close();
+
+          const lines = yield* readTraceRecords(tracePath);
+
+          assert.equal(lines.length, 2);
+          assert.equal(lines[0]?.name, "alpha");
+          assert.equal(lines[1]?.name, "beta");
+        }),
+      ),
+    );
+
+    it.effect("rotates the trace file when the configured max size is exceeded", () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-trace-sink-" });
+          const tracePath = path.join(tempDir, "shared.trace.ndjson");
+
+          const sink = yield* makeTraceSink({
+            filePath: tracePath,
+            maxBytes: 180,
+            maxFiles: 2,
+            batchWindowMs: 10_000,
+          });
+
+          for (let index = 0; index < 8; index += 1) {
+            sink.push(makeRecord("rotate", `${index}-${"x".repeat(48)}`));
+            yield* sink.flush;
+          }
+          yield* sink.close();
+
+          const matchingFiles = (yield* fileSystem.readDirectory(tempDir))
+            .filter(
+              (entry) =>
+                entry === "shared.trace.ndjson" || entry.startsWith("shared.trace.ndjson."),
+            )
+            .toSorted();
+
+          assert.equal(
+            matchingFiles.some((entry) => entry === "shared.trace.ndjson.1"),
+            true,
+          );
+          assert.equal(
+            matchingFiles.some((entry) => entry === "shared.trace.ndjson.3"),
+            false,
+          );
+        }),
+      ),
+    );
+
+    it.effect("drops only the invalid trace record when serialization fails", () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-trace-sink-" });
+          const tracePath = path.join(tempDir, "shared.trace.ndjson");
+
+          const sink = yield* makeTraceSink({
+            filePath: tracePath,
+            maxBytes: 1024,
+            maxFiles: 2,
+            batchWindowMs: 10_000,
+          });
+
+          const circular: Array<unknown> = [];
+          circular.push(circular);
+
+          sink.push(makeRecord("alpha"));
+          sink.push({
+            ...makeRecord("invalid"),
+            attributes: {
+              circular,
+            },
+          } as TraceRecord);
+          sink.push(makeRecord("beta"));
+          yield* sink.close();
+
+          const lines = yield* readTraceRecords(tracePath);
+
+          assert.deepStrictEqual(
+            lines.map((line) => line.name),
+            ["alpha", "beta"],
+          );
+        }),
+      ),
+    );
+
+    it.effect("writes nested spans to disk and captures log messages as span events", () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-local-tracer-" });
+          const tracePath = path.join(tempDir, "shared.trace.ndjson");
+
+          yield* Effect.scoped(
+            Effect.gen(function* () {
+              const program = Effect.gen(function* () {
+                yield* Effect.annotateCurrentSpan({
+                  "demo.parent": true,
+                });
+                yield* Effect.logInfo("parent event");
+                yield* Effect.gen(function* () {
+                  yield* Effect.annotateCurrentSpan({
+                    "demo.child": true,
+                  });
+                  yield* Effect.logInfo("child event");
+                }).pipe(Effect.withSpan("child-span"));
+              }).pipe(Effect.withSpan("parent-span"));
+
+              yield* program.pipe(Effect.provide(makeTestLayer(tracePath)));
+            }),
+          );
+
+          const records = yield* readTraceRecords(tracePath);
+          assert.equal(records.length, 2);
+
+          const parent = records.find((record) => record.name === "parent-span");
+          const child = records.find((record) => record.name === "child-span");
+
+          assert.notEqual(parent, undefined);
+          assert.notEqual(child, undefined);
+          if (!parent || !child) {
+            return;
+          }
+
+          assert.equal(child.parentSpanId, parent.spanId);
+          assert.equal(parent.attributes["demo.parent"], true);
+          assert.equal(child.attributes["demo.child"], true);
+          assert.equal(
+            parent.events.some((event) => event.name === "parent event"),
+            true,
+          );
+          assert.equal(
+            child.events.some((event) => event.name === "child event"),
+            true,
+          );
+          assert.equal(
+            child.events.some((event) => event.attributes["effect.logLevel"] === "INFO"),
+            true,
+          );
+        }),
+      ),
+    );
+
+    it.effect("serializes interrupted spans with an interrupted exit status", () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const tempDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-local-tracer-" });
+          const tracePath = path.join(tempDir, "shared.trace.ndjson");
+
+          yield* Effect.scoped(
+            Effect.exit(
+              Effect.interrupt.pipe(
+                Effect.withSpan("interrupt-span"),
+                Effect.provide(makeTestLayer(tracePath)),
+              ),
+            ),
+          );
+
+          const records = yield* readTraceRecords(tracePath);
+          assert.equal(records.length, 1);
+          assert.equal(records[0]?.name, "interrupt-span");
+          assert.equal(records[0]?.exit?._tag, "Interrupted");
+        }),
+      ),
+    );
+  });
+});
diff --git a/apps/server/src/observability/TraceRecord.ts b/packages/shared/src/observability.ts
similarity index 53%
rename from apps/server/src/observability/TraceRecord.ts
rename to packages/shared/src/observability.ts
index a9a598288b1..4a49545e393 100644
--- a/apps/server/src/observability/TraceRecord.ts
+++ b/packages/shared/src/observability.ts
@@ -1,15 +1,24 @@
-import { Cause, Exit, Option, Tracer } from "effect";
-
-import { compactTraceAttributes } from "./Attributes.ts";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import type * as Exit from "effect/Exit";
+import * as ExitRuntime from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Tracer from "effect/Tracer";
 import { OtlpResource, OtlpTracer } from "effect/unstable/observability";
 
-interface TraceRecordEvent {
+import { RotatingFileSink } from "./logging.ts";
+
+const FLUSH_BUFFER_THRESHOLD = 32;
+
+export type TraceAttributes = Readonly<Record<string, unknown>>;
+
+export interface TraceRecordEvent {
   readonly name: string;
   readonly timeUnixNano: string;
   readonly attributes: Readonly<Record<string, unknown>>;
 }
 
-interface TraceRecordLink {
+export interface TraceRecordLink {
   readonly traceId: string;
   readonly spanId: string;
   readonly attributes: Readonly<Record<string, unknown>>;
@@ -46,7 +55,7 @@ export interface EffectTraceRecord extends BaseTraceRecord {
       };
 }
 
-interface OtlpTraceRecord extends BaseTraceRecord {
+export interface OtlpTraceRecord extends BaseTraceRecord {
   readonly type: "otlp-span";
   readonly resourceAttributes: Readonly<Record<string, unknown>>;
   readonly scope: Readonly<{
@@ -64,6 +73,25 @@ interface OtlpTraceRecord extends BaseTraceRecord {
 
 export type TraceRecord = EffectTraceRecord | OtlpTraceRecord;
 
+export interface TraceSinkOptions {
+  readonly filePath: string;
+  readonly maxBytes: number;
+  readonly maxFiles: number;
+  readonly batchWindowMs: number;
+}
+
+export interface TraceSink {
+  readonly filePath: string;
+  push: (record: TraceRecord) => void;
+  flush: Effect.Effect<void>;
+  close: () => Effect.Effect<void>;
+}
+
+export interface LocalFileTracerOptions extends TraceSinkOptions {
+  readonly delegate?: Tracer.Tracer;
+  readonly sink?: TraceSink;
+}
+
 type OtlpSpan = OtlpTracer.ScopeSpan["spans"][number];
 type OtlpSpanEvent = OtlpSpan["events"][number];
 type OtlpSpanLink = OtlpSpan["links"][number];
@@ -84,8 +112,87 @@ interface SerializableSpan {
   >;
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function markSeen(value: object, seen: WeakSet<object>): boolean {
+  if (seen.has(value)) {
+    return true;
+  }
+  seen.add(value);
+  return false;
+}
+
+function normalizeJsonValue(value: unknown, seen: WeakSet<object> = new WeakSet()): unknown {
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value ?? null;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+  }
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      ...(value.stack ? { stack: value.stack } : {}),
+    };
+  }
+  if (Array.isArray(value)) {
+    if (markSeen(value, seen)) {
+      return "[Circular]";
+    }
+    return value.map((entry) => normalizeJsonValue(entry, seen));
+  }
+  if (value instanceof Map) {
+    if (markSeen(value, seen)) {
+      return "[Circular]";
+    }
+    return Object.fromEntries(
+      Array.from(value.entries(), ([key, entryValue]) => [
+        String(key),
+        normalizeJsonValue(entryValue, seen),
+      ]),
+    );
+  }
+  if (value instanceof Set) {
+    if (markSeen(value, seen)) {
+      return "[Circular]";
+    }
+    return Array.from(value.values(), (entry) => normalizeJsonValue(entry, seen));
+  }
+  if (!isPlainObject(value)) {
+    return String(value);
+  }
+  if (markSeen(value, seen)) {
+    return "[Circular]";
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entryValue]) => [key, normalizeJsonValue(entryValue, seen)]),
+  );
+}
+
+export function compactTraceAttributes(
+  attributes: Readonly<Record<string, unknown>>,
+): TraceAttributes {
+  return Object.fromEntries(
+    Object.entries(attributes)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => [key, normalizeJsonValue(value)]),
+  );
+}
+
 function formatTraceExit(exit: Exit.Exit<unknown, unknown>): EffectTraceRecord["exit"] {
-  if (Exit.isSuccess(exit)) {
+  if (ExitRuntime.isSuccess(exit)) {
     return { _tag: "Success" };
   }
   if (Cause.hasInterruptsOnly(exit.cause)) {
@@ -130,6 +237,151 @@ export function spanToTraceRecord(span: SerializableSpan): EffectTraceRecord {
   };
 }
 
+export const makeTraceSink = Effect.fn("makeTraceSink")(function* (options: TraceSinkOptions) {
+  const sink = new RotatingFileSink({
+    filePath: options.filePath,
+    maxBytes: options.maxBytes,
+    maxFiles: options.maxFiles,
+  });
+
+  let buffer: Array<string> = [];
+
+  const flushUnsafe = () => {
+    if (buffer.length === 0) {
+      return;
+    }
+
+    const chunk = buffer.join("");
+    buffer = [];
+
+    try {
+      sink.write(chunk);
+    } catch {
+      buffer.unshift(chunk);
+    }
+  };
+
+  const flush = Effect.sync(flushUnsafe).pipe(Effect.withTracerEnabled(false));
+
+  yield* Effect.addFinalizer(() => flush.pipe(Effect.ignore));
+  yield* Effect.forkScoped(
+    Effect.sleep(`${options.batchWindowMs} millis`).pipe(Effect.andThen(flush), Effect.forever),
+  );
+
+  return {
+    filePath: options.filePath,
+    push(record) {
+      try {
+        buffer.push(`${JSON.stringify(record)}\n`);
+        if (buffer.length >= FLUSH_BUFFER_THRESHOLD) {
+          flushUnsafe();
+        }
+      } catch {
+        return;
+      }
+    },
+    flush,
+    close: () => flush,
+  } satisfies TraceSink;
+});
+
+class LocalFileSpan implements Tracer.Span {
+  readonly _tag = "Span";
+  readonly name: string;
+  readonly spanId: string;
+  readonly traceId: string;
+  readonly parent: Option.Option<Tracer.AnySpan>;
+  readonly annotations: Tracer.Span["annotations"];
+  readonly links: Array<Tracer.SpanLink>;
+  readonly sampled: boolean;
+  readonly kind: Tracer.SpanKind;
+
+  status: Tracer.SpanStatus;
+  attributes: Map<string, unknown>;
+  events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]>;
+  private readonly delegate: Tracer.Span;
+  private readonly push: (record: EffectTraceRecord) => void;
+
+  constructor(
+    options: Parameters<Tracer.Tracer["span"]>[0],
+    delegate: Tracer.Span,
+    push: (record: EffectTraceRecord) => void,
+  ) {
+    this.delegate = delegate;
+    this.push = push;
+    this.name = delegate.name;
+    this.spanId = delegate.spanId;
+    this.traceId = delegate.traceId;
+    this.parent = options.parent;
+    this.annotations = options.annotations;
+    this.links = [...options.links];
+    this.sampled = delegate.sampled;
+    this.kind = delegate.kind;
+    this.status = {
+      _tag: "Started",
+      startTime: options.startTime,
+    };
+    this.attributes = new Map();
+    this.events = [];
+  }
+
+  end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
+    this.status = {
+      _tag: "Ended",
+      startTime: this.status.startTime,
+      endTime,
+      exit,
+    };
+    this.delegate.end(endTime, exit);
+
+    if (this.sampled) {
+      this.push(spanToTraceRecord(this));
+    }
+  }
+
+  attribute(key: string, value: unknown): void {
+    this.attributes.set(key, value);
+    this.delegate.attribute(key, value);
+  }
+
+  event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void {
+    const nextAttributes = attributes ?? {};
+    this.events.push([name, startTime, nextAttributes]);
+    this.delegate.event(name, startTime, nextAttributes);
+  }
+
+  addLinks(links: ReadonlyArray<Tracer.SpanLink>): void {
+    this.links.push(...links);
+    this.delegate.addLinks(links);
+  }
+}
+
+export const makeLocalFileTracer = Effect.fn("makeLocalFileTracer")(function* (
+  options: LocalFileTracerOptions,
+) {
+  const sink =
+    options.sink ??
+    (yield* makeTraceSink({
+      filePath: options.filePath,
+      maxBytes: options.maxBytes,
+      maxFiles: options.maxFiles,
+      batchWindowMs: options.batchWindowMs,
+    }));
+
+  const delegate =
+    options.delegate ??
+    Tracer.make({
+      span: (spanOptions) => new Tracer.NativeSpan(spanOptions),
+    });
+
+  return Tracer.make({
+    span(spanOptions) {
+      return new LocalFileSpan(spanOptions, delegate.span(spanOptions), sink.push);
+    },
+    ...(delegate.context ? { context: delegate.context } : {}),
+  });
+});
+
 const SPAN_KIND_MAP: Record<number, OtlpTraceRecord["kind"]> = {
   1: "internal",
   2: "server",
diff --git a/packages/shared/src/path.test.ts b/packages/shared/src/path.test.ts
new file mode 100644
index 00000000000..1c74c59a36f
--- /dev/null
+++ b/packages/shared/src/path.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import {
+  isExplicitRelativePath,
+  isUncPath,
+  isWindowsAbsolutePath,
+  isWindowsDrivePath,
+} from "./path.ts";
+
+describe("path helpers", () => {
+  it("detects windows drive paths", () => {
+    expect(isWindowsDrivePath("C:\\repo")).toBe(true);
+    expect(isWindowsDrivePath("D:/repo")).toBe(true);
+    expect(isWindowsDrivePath("/repo")).toBe(false);
+  });
+
+  it("detects UNC paths", () => {
+    expect(isUncPath("\\\\server\\share\\repo")).toBe(true);
+    expect(isUncPath("C:\\repo")).toBe(false);
+  });
+
+  it("detects windows absolute paths", () => {
+    expect(isWindowsAbsolutePath("C:\\repo")).toBe(true);
+    expect(isWindowsAbsolutePath("\\\\server\\share\\repo")).toBe(true);
+    expect(isWindowsAbsolutePath("./repo")).toBe(false);
+  });
+
+  it("detects explicit relative paths", () => {
+    expect(isExplicitRelativePath(".")).toBe(true);
+    expect(isExplicitRelativePath("..")).toBe(true);
+    expect(isExplicitRelativePath("./repo")).toBe(true);
+    expect(isExplicitRelativePath("..\\repo")).toBe(true);
+    expect(isExplicitRelativePath("~/repo")).toBe(false);
+  });
+});
diff --git a/packages/shared/src/path.ts b/packages/shared/src/path.ts
new file mode 100644
index 00000000000..2bb2ca0238d
--- /dev/null
+++ b/packages/shared/src/path.ts
@@ -0,0 +1,22 @@
+export function isWindowsDrivePath(value: string): boolean {
+  return /^[a-zA-Z]:([/\\]|$)/.test(value);
+}
+
+export function isUncPath(value: string): boolean {
+  return value.startsWith("\\\\");
+}
+
+export function isWindowsAbsolutePath(value: string): boolean {
+  return isUncPath(value) || isWindowsDrivePath(value);
+}
+
+export function isExplicitRelativePath(value: string): boolean {
+  return (
+    value === "." ||
+    value === ".." ||
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    value.startsWith(".\\") ||
+    value.startsWith("..\\")
+  );
+}
diff --git a/packages/shared/src/qrCode.ts b/packages/shared/src/qrCode.ts
index 678d38c1114..490e11fa04f 100644
--- a/packages/shared/src/qrCode.ts
+++ b/packages/shared/src/qrCode.ts
@@ -1,4 +1,3 @@
-// @ts-nocheck
 /* oxlint-disable eslint/no-useless-escape */
 /*
  * QR Code generator library (TypeScript)
@@ -25,960 +24,962 @@
 
 "use strict";
 
-namespace qrcodegen {
-  type bit = number;
-  type byte = number;
-  type int = number;
-
-  /*---- QR Code symbol class ----*/
-
-  /*
-   * A QR Code symbol, which is a type of two-dimension barcode.
-   * Invented by Denso Wave and described in the ISO/IEC 18004 standard.
-   * Instances of this class represent an immutable square grid of dark and light cells.
-   * The class provides static factory functions to create a QR Code from text or binary data.
-   * The class covers the QR Code Model 2 specification, supporting all versions (sizes)
-   * from 1 to 40, all 4 error correction levels, and 4 character encoding modes.
-   *
-   * Ways to create a QR Code object:
-   * - High level: Take the payload data and call QrCode.encodeText() or QrCode.encodeBinary().
-   * - Mid level: Custom-make the list of segments and call QrCode.encodeSegments().
-   * - Low level: Custom-make the array of data codeword bytes (including
-   *   segment headers and final padding, excluding error correction codewords),
-   *   supply the appropriate version number, and call the QrCode() constructor.
-   * (Note that all ways require supplying the desired error correction level.)
-   */
-  export class QrCode {
-    /*-- Static factory functions (high level) --*/
-
-    // Returns a QR Code representing the given Unicode text string at the given error correction level.
-    // As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer
-    // Unicode code points (not UTF-16 code units) if the low error correction level is used. The smallest possible
-    // QR Code version is automatically chosen for the output. The ECC level of the result may be higher than the
-    // ecl argument if it can be done without increasing the version.
-    public static encodeText(text: string, ecl: QrCode.Ecc): QrCode {
-      const segs: Array<QrSegment> = qrcodegen.QrSegment.makeSegments(text);
-      return QrCode.encodeSegments(segs, ecl);
-    }
+type bit = number;
+type byte = number;
+type int = number;
 
-    // Returns a QR Code representing the given binary data at the given error correction level.
-    // This function always encodes using the binary segment mode, not any text mode. The maximum number of
-    // bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
-    // The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
-    public static encodeBinary(data: Readonly<Array<byte>>, ecl: QrCode.Ecc): QrCode {
-      const seg: QrSegment = qrcodegen.QrSegment.makeBytes(data);
-      return QrCode.encodeSegments([seg], ecl);
-    }
+/*---- QR Code symbol class ----*/
 
-    /*-- Static factory functions (mid level) --*/
-
-    // Returns a QR Code representing the given segments with the given encoding parameters.
-    // The smallest possible QR Code version within the given range is automatically
-    // chosen for the output. Iff boostEcl is true, then the ECC level of the result
-    // may be higher than the ecl argument if it can be done without increasing the
-    // version. The mask number is either between 0 to 7 (inclusive) to force that
-    // mask, or -1 to automatically choose an appropriate mask (which may be slow).
-    // This function allows the user to create a custom sequence of segments that switches
-    // between modes (such as alphanumeric and byte) to encode text in less space.
-    // This is a mid-level API; the high-level API is encodeText() and encodeBinary().
-    public static encodeSegments(
-      segs: Readonly<Array<QrSegment>>,
-      ecl: QrCode.Ecc,
-      minVersion: int = 1,
-      maxVersion: int = 40,
-      mask: int = -1,
-      boostEcl: boolean = true,
-    ): QrCode {
-      if (
-        !(
-          QrCode.MIN_VERSION <= minVersion &&
-          minVersion <= maxVersion &&
-          maxVersion <= QrCode.MAX_VERSION
-        ) ||
-        mask < -1 ||
-        mask > 7
-      )
-        throw new RangeError("Invalid value");
-
-      // Find the minimal version number to use
-      let version: int;
-      let dataUsedBits: int;
-      for (version = minVersion; ; version++) {
-        const dataCapacityBits: int = QrCode.getNumDataCodewords(version, ecl) * 8; // Number of data bits available
-        const usedBits: number = QrSegment.getTotalBits(segs, version);
-        if (usedBits <= dataCapacityBits) {
-          dataUsedBits = usedBits;
-          break; // This version number is found to be suitable
-        }
-        if (version >= maxVersion)
-          // All versions in the range could not fit the given data
-          throw new RangeError("Data too long");
-      }
+/*
+ * A QR Code symbol, which is a type of two-dimension barcode.
+ * Invented by Denso Wave and described in the ISO/IEC 18004 standard.
+ * Instances of this class represent an immutable square grid of dark and light cells.
+ * The class provides static factory functions to create a QR Code from text or binary data.
+ * The class covers the QR Code Model 2 specification, supporting all versions (sizes)
+ * from 1 to 40, all 4 error correction levels, and 4 character encoding modes.
+ *
+ * Ways to create a QR Code object:
+ * - High level: Take the payload data and call QrCode.encodeText() or QrCode.encodeBinary().
+ * - Mid level: Custom-make the list of segments and call QrCode.encodeSegments().
+ * - Low level: Custom-make the array of data codeword bytes (including
+ *   segment headers and final padding, excluding error correction codewords),
+ *   supply the appropriate version number, and call the QrCode() constructor.
+ * (Note that all ways require supplying the desired error correction level.)
+ */
+export class QrCode {
+  public static Ecc: typeof QrCodeEcc;
+
+  /*-- Static factory functions (high level) --*/
+
+  // Returns a QR Code representing the given Unicode text string at the given error correction level.
+  // As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer
+  // Unicode code points (not UTF-16 code units) if the low error correction level is used. The smallest possible
+  // QR Code version is automatically chosen for the output. The ECC level of the result may be higher than the
+  // ecl argument if it can be done without increasing the version.
+  public static encodeText(text: string, ecl: QrCodeEcc): QrCode {
+    const segs: Array<QrSegment> = QrSegment.makeSegments(text);
+    return QrCode.encodeSegments(segs, ecl);
+  }
 
-      // Increase the error correction level while the data still fits in the current version number
-      for (const newEcl of [QrCode.Ecc.MEDIUM, QrCode.Ecc.QUARTILE, QrCode.Ecc.HIGH]) {
-        // From low to high
-        if (boostEcl && dataUsedBits <= QrCode.getNumDataCodewords(version, newEcl) * 8)
-          ecl = newEcl;
-      }
+  // Returns a QR Code representing the given binary data at the given error correction level.
+  // This function always encodes using the binary segment mode, not any text mode. The maximum number of
+  // bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output.
+  // The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.
+  public static encodeBinary(data: Readonly<Array<byte>>, ecl: QrCodeEcc): QrCode {
+    const seg: QrSegment = QrSegment.makeBytes(data);
+    return QrCode.encodeSegments([seg], ecl);
+  }
 
-      // Concatenate all segments to create the data bit string
-      let bb: Array<bit> = [];
-      for (const seg of segs) {
-        appendBits(seg.mode.modeBits, 4, bb);
-        appendBits(seg.numChars, seg.mode.numCharCountBits(version), bb);
-        for (const b of seg.getData()) bb.push(b);
+  /*-- Static factory functions (mid level) --*/
+
+  // Returns a QR Code representing the given segments with the given encoding parameters.
+  // The smallest possible QR Code version within the given range is automatically
+  // chosen for the output. Iff boostEcl is true, then the ECC level of the result
+  // may be higher than the ecl argument if it can be done without increasing the
+  // version. The mask number is either between 0 to 7 (inclusive) to force that
+  // mask, or -1 to automatically choose an appropriate mask (which may be slow).
+  // This function allows the user to create a custom sequence of segments that switches
+  // between modes (such as alphanumeric and byte) to encode text in less space.
+  // This is a mid-level API; the high-level API is encodeText() and encodeBinary().
+  public static encodeSegments(
+    segs: Readonly<Array<QrSegment>>,
+    ecl: QrCodeEcc,
+    minVersion: int = 1,
+    maxVersion: int = 40,
+    mask: int = -1,
+    boostEcl: boolean = true,
+  ): QrCode {
+    if (
+      !(
+        QrCode.MIN_VERSION <= minVersion &&
+        minVersion <= maxVersion &&
+        maxVersion <= QrCode.MAX_VERSION
+      ) ||
+      mask < -1 ||
+      mask > 7
+    )
+      throw new RangeError("Invalid value");
+
+    // Find the minimal version number to use
+    let version: int;
+    let dataUsedBits: int;
+    for (version = minVersion; ; version++) {
+      const dataCapacityBits: int = QrCode.getNumDataCodewords(version, ecl) * 8; // Number of data bits available
+      const usedBits: number = QrSegment.getTotalBits(segs, version);
+      if (usedBits <= dataCapacityBits) {
+        dataUsedBits = usedBits;
+        break; // This version number is found to be suitable
       }
-      assert(bb.length == dataUsedBits);
-
-      // Add terminator and pad up to a byte if applicable
-      const dataCapacityBits: int = QrCode.getNumDataCodewords(version, ecl) * 8;
-      assert(bb.length <= dataCapacityBits);
-      appendBits(0, Math.min(4, dataCapacityBits - bb.length), bb);
-      appendBits(0, (8 - (bb.length % 8)) % 8, bb);
-      assert(bb.length % 8 == 0);
-
-      // Pad with alternating bytes until data capacity is reached
-      for (let padByte = 0xec; bb.length < dataCapacityBits; padByte ^= 0xec ^ 0x11)
-        appendBits(padByte, 8, bb);
-
-      // Pack bits into bytes in big endian
-      let dataCodewords: Array<byte> = [];
-      while (dataCodewords.length * 8 < bb.length) dataCodewords.push(0);
-      bb.forEach((b: bit, i: int) => (dataCodewords[i >>> 3] |= b << (7 - (i & 7))));
-
-      // Create the QR Code object
-      return new QrCode(version, ecl, dataCodewords, mask);
+      if (version >= maxVersion)
+        // All versions in the range could not fit the given data
+        throw new RangeError("Data too long");
     }
 
-    /*-- Fields --*/
-
-    // The width and height of this QR Code, measured in modules, between
-    // 21 and 177 (inclusive). This is equal to version * 4 + 17.
-    public readonly size: int;
-
-    // The index of the mask pattern used in this QR Code, which is between 0 and 7 (inclusive).
-    // Even if a QR Code is created with automatic masking requested (mask = -1),
-    // the resulting object still has a mask value between 0 and 7.
-    public readonly mask: int;
-
-    // The modules of this QR Code (false = light, true = dark).
-    // Immutable after constructor finishes. Accessed through getModule().
-    private readonly modules: Array<Array<boolean>> = [];
-
-    // Indicates function modules that are not subjected to masking. Discarded when constructor finishes.
-    private readonly isFunction: Array<Array<boolean>> = [];
-
-    /*-- Constructor (low level) and fields --*/
-
-    // Creates a new QR Code with the given version number,
-    // error correction level, data codeword bytes, and mask number.
-    // This is a low-level API that most users should not use directly.
-    // A mid-level API is the encodeSegments() function.
-    public constructor(
-      // The version number of this QR Code, which is between 1 and 40 (inclusive).
-      // This determines the size of this barcode.
-      public readonly version: int,
-
-      // The error correction level used in this QR Code.
-      public readonly errorCorrectionLevel: QrCode.Ecc,
-
-      dataCodewords: Readonly<Array<byte>>,
-
-      msk: int,
-    ) {
-      // Check scalar arguments
-      if (version < QrCode.MIN_VERSION || version > QrCode.MAX_VERSION)
-        throw new RangeError("Version value out of range");
-      if (msk < -1 || msk > 7) throw new RangeError("Mask value out of range");
-      this.size = version * 4 + 17;
-
-      // Initialize both grids to be size*size arrays of Boolean false
-      let row: Array<boolean> = [];
-      for (let i = 0; i < this.size; i++) row.push(false);
-      for (let i = 0; i < this.size; i++) {
-        this.modules.push(row.slice()); // Initially all light
-        this.isFunction.push(row.slice());
-      }
-
-      // Compute ECC, draw modules
-      this.drawFunctionPatterns();
-      const allCodewords: Array<byte> = this.addEccAndInterleave(dataCodewords);
-      this.drawCodewords(allCodewords);
-
-      // Do masking
-      if (msk == -1) {
-        // Automatically choose best mask
-        let minPenalty: int = 1000000000;
-        for (let i = 0; i < 8; i++) {
-          this.applyMask(i);
-          this.drawFormatBits(i);
-          const penalty: int = this.getPenaltyScore();
-          if (penalty < minPenalty) {
-            msk = i;
-            minPenalty = penalty;
-          }
-          this.applyMask(i); // Undoes the mask due to XOR
-        }
-      }
-      assert(0 <= msk && msk <= 7);
-      this.mask = msk;
-      this.applyMask(msk); // Apply the final choice of mask
-      this.drawFormatBits(msk); // Overwrite old format bits
+    // Increase the error correction level while the data still fits in the current version number
+    for (const newEcl of [QrCode.Ecc.MEDIUM, QrCode.Ecc.QUARTILE, QrCode.Ecc.HIGH]) {
+      // From low to high
+      if (boostEcl && dataUsedBits <= QrCode.getNumDataCodewords(version, newEcl) * 8) ecl = newEcl;
+    }
 
-      this.isFunction = [];
+    // Concatenate all segments to create the data bit string
+    let bb: Array<bit> = [];
+    for (const seg of segs) {
+      appendBits(seg.mode.modeBits, 4, bb);
+      appendBits(seg.numChars, seg.mode.numCharCountBits(version), bb);
+      for (const b of seg.getData()) bb.push(b);
     }
+    assert(bb.length == dataUsedBits);
 
-    /*-- Accessor methods --*/
+    // Add terminator and pad up to a byte if applicable
+    const dataCapacityBits: int = QrCode.getNumDataCodewords(version, ecl) * 8;
+    assert(bb.length <= dataCapacityBits);
+    appendBits(0, Math.min(4, dataCapacityBits - bb.length), bb);
+    appendBits(0, (8 - (bb.length % 8)) % 8, bb);
+    assert(bb.length % 8 == 0);
 
-    // Returns the color of the module (pixel) at the given coordinates, which is false
-    // for light or true for dark. The top left corner has the coordinates (x=0, y=0).
-    // If the given coordinates are out of bounds, then false (light) is returned.
-    public getModule(x: int, y: int): boolean {
-      return 0 <= x && x < this.size && 0 <= y && y < this.size && this.modules[y][x];
-    }
+    // Pad with alternating bytes until data capacity is reached
+    for (let padByte = 0xec; bb.length < dataCapacityBits; padByte ^= 0xec ^ 0x11)
+      appendBits(padByte, 8, bb);
 
-    /*-- Private helper methods for constructor: Drawing function modules --*/
+    // Pack bits into bytes in big endian
+    let dataCodewords: Array<byte> = [];
+    while (dataCodewords.length * 8 < bb.length) dataCodewords.push(0);
+    bb.forEach((b: bit, i: int) => (dataCodewords[i >>> 3]! |= b << (7 - (i & 7))));
 
-    // Reads this object's version field, and draws and marks all function modules.
-    private drawFunctionPatterns(): void {
-      // Draw horizontal and vertical timing patterns
-      for (let i = 0; i < this.size; i++) {
-        this.setFunctionModule(6, i, i % 2 == 0);
-        this.setFunctionModule(i, 6, i % 2 == 0);
-      }
+    // Create the QR Code object
+    return new QrCode(version, ecl, dataCodewords, mask);
+  }
 
-      // Draw 3 finder patterns (all corners except bottom right; overwrites some timing modules)
-      this.drawFinderPattern(3, 3);
-      this.drawFinderPattern(this.size - 4, 3);
-      this.drawFinderPattern(3, this.size - 4);
-
-      // Draw numerous alignment patterns
-      const alignPatPos: Array<int> = this.getAlignmentPatternPositions();
-      const numAlign: int = alignPatPos.length;
-      for (let i = 0; i < numAlign; i++) {
-        for (let j = 0; j < numAlign; j++) {
-          // Don't draw on the three finder corners
-          if (
-            !((i == 0 && j == 0) || (i == 0 && j == numAlign - 1) || (i == numAlign - 1 && j == 0))
-          )
-            this.drawAlignmentPattern(alignPatPos[i], alignPatPos[j]);
+  /*-- Fields --*/
+
+  // The width and height of this QR Code, measured in modules, between
+  // 21 and 177 (inclusive). This is equal to version * 4 + 17.
+  public readonly version: int;
+  public readonly errorCorrectionLevel: QrCodeEcc;
+  public readonly size: int;
+
+  // The index of the mask pattern used in this QR Code, which is between 0 and 7 (inclusive).
+  // Even if a QR Code is created with automatic masking requested (mask = -1),
+  // the resulting object still has a mask value between 0 and 7.
+  public readonly mask: int;
+
+  // The modules of this QR Code (false = light, true = dark).
+  // Immutable after constructor finishes. Accessed through getModule().
+  private readonly modules: Array<Array<boolean>> = [];
+
+  // Indicates function modules that are not subjected to masking. Discarded when constructor finishes.
+  private readonly isFunction: Array<Array<boolean>> = [];
+
+  /*-- Constructor (low level) and fields --*/
+
+  // Creates a new QR Code with the given version number,
+  // error correction level, data codeword bytes, and mask number.
+  // This is a low-level API that most users should not use directly.
+  // A mid-level API is the encodeSegments() function.
+  public constructor(
+    // The version number of this QR Code, which is between 1 and 40 (inclusive).
+    // This determines the size of this barcode.
+    version: int,
+
+    // The error correction level used in this QR Code.
+    errorCorrectionLevel: QrCodeEcc,
+
+    dataCodewords: Readonly<Array<byte>>,
+
+    msk: int,
+  ) {
+    this.version = version;
+    this.errorCorrectionLevel = errorCorrectionLevel;
+
+    // Check scalar arguments
+    if (version < QrCode.MIN_VERSION || version > QrCode.MAX_VERSION)
+      throw new RangeError("Version value out of range");
+    if (msk < -1 || msk > 7) throw new RangeError("Mask value out of range");
+    this.size = version * 4 + 17;
+
+    // Initialize both grids to be size*size arrays of Boolean false
+    let row: Array<boolean> = [];
+    for (let i = 0; i < this.size; i++) row.push(false);
+    for (let i = 0; i < this.size; i++) {
+      this.modules.push(row.slice()); // Initially all light
+      this.isFunction.push(row.slice());
+    }
+
+    // Compute ECC, draw modules
+    this.drawFunctionPatterns();
+    const allCodewords: Array<byte> = this.addEccAndInterleave(dataCodewords);
+    this.drawCodewords(allCodewords);
+
+    // Do masking
+    if (msk == -1) {
+      // Automatically choose best mask
+      let minPenalty: int = 1000000000;
+      for (let i = 0; i < 8; i++) {
+        this.applyMask(i);
+        this.drawFormatBits(i);
+        const penalty: int = this.getPenaltyScore();
+        if (penalty < minPenalty) {
+          msk = i;
+          minPenalty = penalty;
         }
+        this.applyMask(i); // Undoes the mask due to XOR
       }
-
-      // Draw configuration data
-      this.drawFormatBits(0); // Dummy mask value; overwritten later in the constructor
-      this.drawVersion();
     }
+    assert(0 <= msk && msk <= 7);
+    this.mask = msk;
+    this.applyMask(msk); // Apply the final choice of mask
+    this.drawFormatBits(msk); // Overwrite old format bits
 
-    // Draws two copies of the format bits (with its own error correction code)
-    // based on the given mask and this object's error correction level field.
-    private drawFormatBits(mask: int): void {
-      // Calculate error correction code and pack bits
-      const data: int = (this.errorCorrectionLevel.formatBits << 3) | mask; // errCorrLvl is uint2, mask is uint3
-      let rem: int = data;
-      for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
-      const bits = ((data << 10) | rem) ^ 0x5412; // uint15
-      assert(bits >>> 15 == 0);
-
-      // Draw first copy
-      for (let i = 0; i <= 5; i++) this.setFunctionModule(8, i, getBit(bits, i));
-      this.setFunctionModule(8, 7, getBit(bits, 6));
-      this.setFunctionModule(8, 8, getBit(bits, 7));
-      this.setFunctionModule(7, 8, getBit(bits, 8));
-      for (let i = 9; i < 15; i++) this.setFunctionModule(14 - i, 8, getBit(bits, i));
-
-      // Draw second copy
-      for (let i = 0; i < 8; i++) this.setFunctionModule(this.size - 1 - i, 8, getBit(bits, i));
-      for (let i = 8; i < 15; i++) this.setFunctionModule(8, this.size - 15 + i, getBit(bits, i));
-      this.setFunctionModule(8, this.size - 8, true); // Always dark
-    }
+    this.isFunction = [];
+  }
+
+  /*-- Accessor methods --*/
+
+  // Returns the color of the module (pixel) at the given coordinates, which is false
+  // for light or true for dark. The top left corner has the coordinates (x=0, y=0).
+  // If the given coordinates are out of bounds, then false (light) is returned.
+  public getModule(x: int, y: int): boolean {
+    return 0 <= x && x < this.size && 0 <= y && y < this.size && this.modules[y]![x]!;
+  }
 
-    // Draws two copies of the version bits (with its own error correction code),
-    // based on this object's version field, iff 7 <= version <= 40.
-    private drawVersion(): void {
-      if (this.version < 7) return;
-
-      // Calculate error correction code and pack bits
-      let rem: int = this.version; // version is uint6, in the range [7, 40]
-      for (let i = 0; i < 12; i++) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25);
-      const bits: int = (this.version << 12) | rem; // uint18
-      assert(bits >>> 18 == 0);
-
-      // Draw two copies
-      for (let i = 0; i < 18; i++) {
-        const color: boolean = getBit(bits, i);
-        const a: int = this.size - 11 + (i % 3);
-        const b: int = Math.floor(i / 3);
-        this.setFunctionModule(a, b, color);
-        this.setFunctionModule(b, a, color);
+  /*-- Private helper methods for constructor: Drawing function modules --*/
+
+  // Reads this object's version field, and draws and marks all function modules.
+  private drawFunctionPatterns(): void {
+    // Draw horizontal and vertical timing patterns
+    for (let i = 0; i < this.size; i++) {
+      this.setFunctionModule(6, i, i % 2 == 0);
+      this.setFunctionModule(i, 6, i % 2 == 0);
+    }
+
+    // Draw 3 finder patterns (all corners except bottom right; overwrites some timing modules)
+    this.drawFinderPattern(3, 3);
+    this.drawFinderPattern(this.size - 4, 3);
+    this.drawFinderPattern(3, this.size - 4);
+
+    // Draw numerous alignment patterns
+    const alignPatPos: Array<int> = this.getAlignmentPatternPositions();
+    const numAlign: int = alignPatPos.length;
+    for (let i = 0; i < numAlign; i++) {
+      for (let j = 0; j < numAlign; j++) {
+        // Don't draw on the three finder corners
+        if (!((i == 0 && j == 0) || (i == 0 && j == numAlign - 1) || (i == numAlign - 1 && j == 0)))
+          this.drawAlignmentPattern(alignPatPos[i]!, alignPatPos[j]!);
       }
     }
 
-    // Draws a 9*9 finder pattern including the border separator,
-    // with the center module at (x, y). Modules can be out of bounds.
-    private drawFinderPattern(x: int, y: int): void {
-      for (let dy = -4; dy <= 4; dy++) {
-        for (let dx = -4; dx <= 4; dx++) {
-          const dist: int = Math.max(Math.abs(dx), Math.abs(dy)); // Chebyshev/infinity norm
-          const xx: int = x + dx;
-          const yy: int = y + dy;
-          if (0 <= xx && xx < this.size && 0 <= yy && yy < this.size)
-            this.setFunctionModule(xx, yy, dist != 2 && dist != 4);
-        }
-      }
+    // Draw configuration data
+    this.drawFormatBits(0); // Dummy mask value; overwritten later in the constructor
+    this.drawVersion();
+  }
+
+  // Draws two copies of the format bits (with its own error correction code)
+  // based on the given mask and this object's error correction level field.
+  private drawFormatBits(mask: int): void {
+    // Calculate error correction code and pack bits
+    const data: int = (this.errorCorrectionLevel.formatBits << 3) | mask; // errCorrLvl is uint2, mask is uint3
+    let rem: int = data;
+    for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
+    const bits = ((data << 10) | rem) ^ 0x5412; // uint15
+    assert(bits >>> 15 == 0);
+
+    // Draw first copy
+    for (let i = 0; i <= 5; i++) this.setFunctionModule(8, i, getBit(bits, i));
+    this.setFunctionModule(8, 7, getBit(bits, 6));
+    this.setFunctionModule(8, 8, getBit(bits, 7));
+    this.setFunctionModule(7, 8, getBit(bits, 8));
+    for (let i = 9; i < 15; i++) this.setFunctionModule(14 - i, 8, getBit(bits, i));
+
+    // Draw second copy
+    for (let i = 0; i < 8; i++) this.setFunctionModule(this.size - 1 - i, 8, getBit(bits, i));
+    for (let i = 8; i < 15; i++) this.setFunctionModule(8, this.size - 15 + i, getBit(bits, i));
+    this.setFunctionModule(8, this.size - 8, true); // Always dark
+  }
+
+  // Draws two copies of the version bits (with its own error correction code),
+  // based on this object's version field, iff 7 <= version <= 40.
+  private drawVersion(): void {
+    if (this.version < 7) return;
+
+    // Calculate error correction code and pack bits
+    let rem: int = this.version; // version is uint6, in the range [7, 40]
+    for (let i = 0; i < 12; i++) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25);
+    const bits: int = (this.version << 12) | rem; // uint18
+    assert(bits >>> 18 == 0);
+
+    // Draw two copies
+    for (let i = 0; i < 18; i++) {
+      const color: boolean = getBit(bits, i);
+      const a: int = this.size - 11 + (i % 3);
+      const b: int = Math.floor(i / 3);
+      this.setFunctionModule(a, b, color);
+      this.setFunctionModule(b, a, color);
     }
+  }
 
-    // Draws a 5*5 alignment pattern, with the center module
-    // at (x, y). All modules must be in bounds.
-    private drawAlignmentPattern(x: int, y: int): void {
-      for (let dy = -2; dy <= 2; dy++) {
-        for (let dx = -2; dx <= 2; dx++)
-          this.setFunctionModule(x + dx, y + dy, Math.max(Math.abs(dx), Math.abs(dy)) != 1);
+  // Draws a 9*9 finder pattern including the border separator,
+  // with the center module at (x, y). Modules can be out of bounds.
+  private drawFinderPattern(x: int, y: int): void {
+    for (let dy = -4; dy <= 4; dy++) {
+      for (let dx = -4; dx <= 4; dx++) {
+        const dist: int = Math.max(Math.abs(dx), Math.abs(dy)); // Chebyshev/infinity norm
+        const xx: int = x + dx;
+        const yy: int = y + dy;
+        if (0 <= xx && xx < this.size && 0 <= yy && yy < this.size)
+          this.setFunctionModule(xx, yy, dist != 2 && dist != 4);
       }
     }
+  }
 
-    // Sets the color of a module and marks it as a function module.
-    // Only used by the constructor. Coordinates must be in bounds.
-    private setFunctionModule(x: int, y: int, isDark: boolean): void {
-      this.modules[y][x] = isDark;
-      this.isFunction[y][x] = true;
+  // Draws a 5*5 alignment pattern, with the center module
+  // at (x, y). All modules must be in bounds.
+  private drawAlignmentPattern(x: int, y: int): void {
+    for (let dy = -2; dy <= 2; dy++) {
+      for (let dx = -2; dx <= 2; dx++)
+        this.setFunctionModule(x + dx, y + dy, Math.max(Math.abs(dx), Math.abs(dy)) != 1);
     }
+  }
 
-    /*-- Private helper methods for constructor: Codewords and masking --*/
-
-    // Returns a new byte string representing the given data with the appropriate error correction
-    // codewords appended to it, based on this object's version and error correction level.
-    private addEccAndInterleave(data: Readonly<Array<byte>>): Array<byte> {
-      const ver: int = this.version;
-      const ecl: QrCode.Ecc = this.errorCorrectionLevel;
-      if (data.length != QrCode.getNumDataCodewords(ver, ecl))
-        throw new RangeError("Invalid argument");
-
-      // Calculate parameter numbers
-      const numBlocks: int = QrCode.NUM_ERROR_CORRECTION_BLOCKS[ecl.ordinal][ver];
-      const blockEccLen: int = QrCode.ECC_CODEWORDS_PER_BLOCK[ecl.ordinal][ver];
-      const rawCodewords: int = Math.floor(QrCode.getNumRawDataModules(ver) / 8);
-      const numShortBlocks: int = numBlocks - (rawCodewords % numBlocks);
-      const shortBlockLen: int = Math.floor(rawCodewords / numBlocks);
-
-      // Split data into blocks and append ECC to each block
-      let blocks: Array<Array<byte>> = [];
-      const rsDiv: Array<byte> = QrCode.reedSolomonComputeDivisor(blockEccLen);
-      for (let i = 0, k = 0; i < numBlocks; i++) {
-        let dat: Array<byte> = data.slice(
-          k,
-          k + shortBlockLen - blockEccLen + (i < numShortBlocks ? 0 : 1),
-        );
-        k += dat.length;
-        const ecc: Array<byte> = QrCode.reedSolomonComputeRemainder(dat, rsDiv);
-        if (i < numShortBlocks) dat.push(0);
-        blocks.push(dat.concat(ecc));
-      }
+  // Sets the color of a module and marks it as a function module.
+  // Only used by the constructor. Coordinates must be in bounds.
+  private setFunctionModule(x: int, y: int, isDark: boolean): void {
+    this.modules[y]![x] = isDark;
+    this.isFunction[y]![x] = true;
+  }
 
-      // Interleave (not concatenate) the bytes from every block into a single sequence
-      let result: Array<byte> = [];
-      for (let i = 0; i < blocks[0].length; i++) {
-        blocks.forEach((block, j) => {
-          // Skip the padding byte in short blocks
-          if (i != shortBlockLen - blockEccLen || j >= numShortBlocks) result.push(block[i]);
-        });
-      }
-      assert(result.length == rawCodewords);
-      return result;
-    }
+  /*-- Private helper methods for constructor: Codewords and masking --*/
+
+  // Returns a new byte string representing the given data with the appropriate error correction
+  // codewords appended to it, based on this object's version and error correction level.
+  private addEccAndInterleave(data: Readonly<Array<byte>>): Array<byte> {
+    const ver: int = this.version;
+    const ecl: QrCodeEcc = this.errorCorrectionLevel;
+    if (data.length != QrCode.getNumDataCodewords(ver, ecl))
+      throw new RangeError("Invalid argument");
+
+    // Calculate parameter numbers
+    const numBlocks: int = QrCode.NUM_ERROR_CORRECTION_BLOCKS[ecl.ordinal]![ver]!;
+    const blockEccLen: int = QrCode.ECC_CODEWORDS_PER_BLOCK[ecl.ordinal]![ver]!;
+    const rawCodewords: int = Math.floor(QrCode.getNumRawDataModules(ver) / 8);
+    const numShortBlocks: int = numBlocks - (rawCodewords % numBlocks);
+    const shortBlockLen: int = Math.floor(rawCodewords / numBlocks);
+
+    // Split data into blocks and append ECC to each block
+    let blocks: Array<Array<byte>> = [];
+    const rsDiv: Array<byte> = QrCode.reedSolomonComputeDivisor(blockEccLen);
+    for (let i = 0, k = 0; i < numBlocks; i++) {
+      let dat: Array<byte> = data.slice(
+        k,
+        k + shortBlockLen - blockEccLen + (i < numShortBlocks ? 0 : 1),
+      );
+      k += dat.length;
+      const ecc: Array<byte> = QrCode.reedSolomonComputeRemainder(dat, rsDiv);
+      if (i < numShortBlocks) dat.push(0);
+      blocks.push(dat.concat(ecc));
+    }
+
+    // Interleave (not concatenate) the bytes from every block into a single sequence
+    let result: Array<byte> = [];
+    for (let i = 0; i < blocks[0]!.length; i++) {
+      blocks.forEach((block, j) => {
+        // Skip the padding byte in short blocks
+        if (i != shortBlockLen - blockEccLen || j >= numShortBlocks) result.push(block[i]!);
+      });
+    }
+    assert(result.length == rawCodewords);
+    return result;
+  }
 
-    // Draws the given sequence of 8-bit codewords (data and error correction) onto the entire
-    // data area of this QR Code. Function modules need to be marked off before this is called.
-    private drawCodewords(data: Readonly<Array<byte>>): void {
-      if (data.length != Math.floor(QrCode.getNumRawDataModules(this.version) / 8))
-        throw new RangeError("Invalid argument");
-      let i: int = 0; // Bit index into the data
-      // Do the funny zigzag scan
-      for (let right = this.size - 1; right >= 1; right -= 2) {
-        // Index of right column in each column pair
-        if (right == 6) right = 5;
-        for (let vert = 0; vert < this.size; vert++) {
-          // Vertical counter
-          for (let j = 0; j < 2; j++) {
-            const x: int = right - j; // Actual x coordinate
-            const upward: boolean = ((right + 1) & 2) == 0;
-            const y: int = upward ? this.size - 1 - vert : vert; // Actual y coordinate
-            if (!this.isFunction[y][x] && i < data.length * 8) {
-              this.modules[y][x] = getBit(data[i >>> 3], 7 - (i & 7));
-              i++;
-            }
-            // If this QR Code has any remainder bits (0 to 7), they were assigned as
-            // 0/false/light by the constructor and are left unchanged by this method
+  // Draws the given sequence of 8-bit codewords (data and error correction) onto the entire
+  // data area of this QR Code. Function modules need to be marked off before this is called.
+  private drawCodewords(data: Readonly<Array<byte>>): void {
+    if (data.length != Math.floor(QrCode.getNumRawDataModules(this.version) / 8))
+      throw new RangeError("Invalid argument");
+    let i: int = 0; // Bit index into the data
+    // Do the funny zigzag scan
+    for (let right = this.size - 1; right >= 1; right -= 2) {
+      // Index of right column in each column pair
+      if (right == 6) right = 5;
+      for (let vert = 0; vert < this.size; vert++) {
+        // Vertical counter
+        for (let j = 0; j < 2; j++) {
+          const x: int = right - j; // Actual x coordinate
+          const upward: boolean = ((right + 1) & 2) == 0;
+          const y: int = upward ? this.size - 1 - vert : vert; // Actual y coordinate
+          if (!this.isFunction[y]![x]! && i < data.length * 8) {
+            this.modules[y]![x] = getBit(data[i >>> 3]!, 7 - (i & 7));
+            i++;
           }
+          // If this QR Code has any remainder bits (0 to 7), they were assigned as
+          // 0/false/light by the constructor and are left unchanged by this method
         }
       }
-      assert(i == data.length * 8);
     }
+    assert(i == data.length * 8);
+  }
 
-    // XORs the codeword modules in this QR Code with the given mask pattern.
-    // The function modules must be marked and the codeword bits must be drawn
-    // before masking. Due to the arithmetic of XOR, calling applyMask() with
-    // the same mask value a second time will undo the mask. A final well-formed
-    // QR Code needs exactly one (not zero, two, etc.) mask applied.
-    private applyMask(mask: int): void {
-      if (mask < 0 || mask > 7) throw new RangeError("Mask value out of range");
-      for (let y = 0; y < this.size; y++) {
-        for (let x = 0; x < this.size; x++) {
-          let invert: boolean;
-          switch (mask) {
-            case 0:
-              invert = (x + y) % 2 == 0;
-              break;
-            case 1:
-              invert = y % 2 == 0;
-              break;
-            case 2:
-              invert = x % 3 == 0;
-              break;
-            case 3:
-              invert = (x + y) % 3 == 0;
-              break;
-            case 4:
-              invert = (Math.floor(x / 3) + Math.floor(y / 2)) % 2 == 0;
-              break;
-            case 5:
-              invert = ((x * y) % 2) + ((x * y) % 3) == 0;
-              break;
-            case 6:
-              invert = (((x * y) % 2) + ((x * y) % 3)) % 2 == 0;
-              break;
-            case 7:
-              invert = (((x + y) % 2) + ((x * y) % 3)) % 2 == 0;
-              break;
-            default:
-              throw new Error("Unreachable");
-          }
-          if (!this.isFunction[y][x] && invert) this.modules[y][x] = !this.modules[y][x];
+  // XORs the codeword modules in this QR Code with the given mask pattern.
+  // The function modules must be marked and the codeword bits must be drawn
+  // before masking. Due to the arithmetic of XOR, calling applyMask() with
+  // the same mask value a second time will undo the mask. A final well-formed
+  // QR Code needs exactly one (not zero, two, etc.) mask applied.
+  private applyMask(mask: int): void {
+    if (mask < 0 || mask > 7) throw new RangeError("Mask value out of range");
+    for (let y = 0; y < this.size; y++) {
+      for (let x = 0; x < this.size; x++) {
+        let invert: boolean;
+        switch (mask) {
+          case 0:
+            invert = (x + y) % 2 == 0;
+            break;
+          case 1:
+            invert = y % 2 == 0;
+            break;
+          case 2:
+            invert = x % 3 == 0;
+            break;
+          case 3:
+            invert = (x + y) % 3 == 0;
+            break;
+          case 4:
+            invert = (Math.floor(x / 3) + Math.floor(y / 2)) % 2 == 0;
+            break;
+          case 5:
+            invert = ((x * y) % 2) + ((x * y) % 3) == 0;
+            break;
+          case 6:
+            invert = (((x * y) % 2) + ((x * y) % 3)) % 2 == 0;
+            break;
+          case 7:
+            invert = (((x + y) % 2) + ((x * y) % 3)) % 2 == 0;
+            break;
+          default:
+            throw new Error("Unreachable");
         }
+        if (!this.isFunction[y]![x]! && invert) this.modules[y]![x] = !this.modules[y]![x]!;
       }
     }
+  }
 
-    // Calculates and returns the penalty score based on state of this QR Code's current modules.
-    // This is used by the automatic mask choice algorithm to find the mask pattern that yields the lowest score.
-    private getPenaltyScore(): int {
-      let result: int = 0;
+  // Calculates and returns the penalty score based on state of this QR Code's current modules.
+  // This is used by the automatic mask choice algorithm to find the mask pattern that yields the lowest score.
+  private getPenaltyScore(): int {
+    let result: int = 0;
 
-      // Adjacent modules in row having same color, and finder-like patterns
-      for (let y = 0; y < this.size; y++) {
-        let runColor = false;
-        let runX = 0;
-        let runHistory = [0, 0, 0, 0, 0, 0, 0];
-        for (let x = 0; x < this.size; x++) {
-          if (this.modules[y][x] == runColor) {
-            runX++;
-            if (runX == 5) result += QrCode.PENALTY_N1;
-            else if (runX > 5) result++;
-          } else {
-            this.finderPenaltyAddHistory(runX, runHistory);
-            if (!runColor)
-              result += this.finderPenaltyCountPatterns(runHistory) * QrCode.PENALTY_N3;
-            runColor = this.modules[y][x];
-            runX = 1;
-          }
-        }
-        result +=
-          this.finderPenaltyTerminateAndCount(runColor, runX, runHistory) * QrCode.PENALTY_N3;
-      }
-      // Adjacent modules in column having same color, and finder-like patterns
+    // Adjacent modules in row having same color, and finder-like patterns
+    for (let y = 0; y < this.size; y++) {
+      let runColor = false;
+      let runX = 0;
+      let runHistory = [0, 0, 0, 0, 0, 0, 0];
       for (let x = 0; x < this.size; x++) {
-        let runColor = false;
-        let runY = 0;
-        let runHistory = [0, 0, 0, 0, 0, 0, 0];
-        for (let y = 0; y < this.size; y++) {
-          if (this.modules[y][x] == runColor) {
-            runY++;
-            if (runY == 5) result += QrCode.PENALTY_N1;
-            else if (runY > 5) result++;
-          } else {
-            this.finderPenaltyAddHistory(runY, runHistory);
-            if (!runColor)
-              result += this.finderPenaltyCountPatterns(runHistory) * QrCode.PENALTY_N3;
-            runColor = this.modules[y][x];
-            runY = 1;
-          }
+        if (this.modules[y]![x] === runColor) {
+          runX++;
+          if (runX == 5) result += QrCode.PENALTY_N1;
+          else if (runX > 5) result++;
+        } else {
+          this.finderPenaltyAddHistory(runX, runHistory);
+          if (!runColor) result += this.finderPenaltyCountPatterns(runHistory) * QrCode.PENALTY_N3;
+          runColor = this.modules[y]![x]!;
+          runX = 1;
         }
-        result +=
-          this.finderPenaltyTerminateAndCount(runColor, runY, runHistory) * QrCode.PENALTY_N3;
       }
-
-      // 2*2 blocks of modules having same color
-      for (let y = 0; y < this.size - 1; y++) {
-        for (let x = 0; x < this.size - 1; x++) {
-          const color: boolean = this.modules[y][x];
-          if (
-            color == this.modules[y][x + 1] &&
-            color == this.modules[y + 1][x] &&
-            color == this.modules[y + 1][x + 1]
-          )
-            result += QrCode.PENALTY_N2;
+      result += this.finderPenaltyTerminateAndCount(runColor, runX, runHistory) * QrCode.PENALTY_N3;
+    }
+    // Adjacent modules in column having same color, and finder-like patterns
+    for (let x = 0; x < this.size; x++) {
+      let runColor = false;
+      let runY = 0;
+      let runHistory = [0, 0, 0, 0, 0, 0, 0];
+      for (let y = 0; y < this.size; y++) {
+        if (this.modules[y]![x] === runColor) {
+          runY++;
+          if (runY == 5) result += QrCode.PENALTY_N1;
+          else if (runY > 5) result++;
+        } else {
+          this.finderPenaltyAddHistory(runY, runHistory);
+          if (!runColor) result += this.finderPenaltyCountPatterns(runHistory) * QrCode.PENALTY_N3;
+          runColor = this.modules[y]![x]!;
+          runY = 1;
         }
       }
-
-      // Balance of dark and light modules
-      let dark: int = 0;
-      for (const row of this.modules)
-        dark = row.reduce((sum, color) => sum + (color ? 1 : 0), dark);
-      const total: int = this.size * this.size; // Note that size is odd, so dark/total != 1/2
-      // Compute the smallest integer k >= 0 such that (45-5k)% <= dark/total <= (55+5k)%
-      const k: int = Math.ceil(Math.abs(dark * 20 - total * 10) / total) - 1;
-      assert(0 <= k && k <= 9);
-      result += k * QrCode.PENALTY_N4;
-      assert(0 <= result && result <= 2568888); // Non-tight upper bound based on default values of PENALTY_N1, ..., N4
-      return result;
-    }
-
-    /*-- Private helper functions --*/
-
-    // Returns an ascending list of positions of alignment patterns for this version number.
-    // Each position is in the range [0,177), and are used on both the x and y axes.
-    // This could be implemented as lookup table of 40 variable-length lists of integers.
-    private getAlignmentPatternPositions(): Array<int> {
-      if (this.version == 1) return [];
-      else {
-        const numAlign: int = Math.floor(this.version / 7) + 2;
-        const step: int =
-          this.version == 32 ? 26 : Math.ceil((this.version * 4 + 4) / (numAlign * 2 - 2)) * 2;
-        let result: Array<int> = [6];
-        for (let pos = this.size - 7; result.length < numAlign; pos -= step)
-          result.splice(1, 0, pos);
-        return result;
+      result += this.finderPenaltyTerminateAndCount(runColor, runY, runHistory) * QrCode.PENALTY_N3;
+    }
+
+    // 2*2 blocks of modules having same color
+    for (let y = 0; y < this.size - 1; y++) {
+      for (let x = 0; x < this.size - 1; x++) {
+        const color: boolean = this.modules[y]![x]!;
+        if (
+          color == this.modules[y]![x + 1]! &&
+          color == this.modules[y + 1]![x]! &&
+          color == this.modules[y + 1]![x + 1]!
+        )
+          result += QrCode.PENALTY_N2;
       }
     }
 
-    // Returns the number of data bits that can be stored in a QR Code of the given version number, after
-    // all function modules are excluded. This includes remainder bits, so it might not be a multiple of 8.
-    // The result is in the range [208, 29648]. This could be implemented as a 40-entry lookup table.
-    private static getNumRawDataModules(ver: int): int {
-      if (ver < QrCode.MIN_VERSION || ver > QrCode.MAX_VERSION)
-        throw new RangeError("Version number out of range");
-      let result: int = (16 * ver + 128) * ver + 64;
-      if (ver >= 2) {
-        const numAlign: int = Math.floor(ver / 7) + 2;
-        result -= (25 * numAlign - 10) * numAlign - 55;
-        if (ver >= 7) result -= 36;
-      }
-      assert(208 <= result && result <= 29648);
+    // Balance of dark and light modules
+    let dark: int = 0;
+    for (const row of this.modules) dark = row.reduce((sum, color) => sum + (color ? 1 : 0), dark);
+    const total: int = this.size * this.size; // Note that size is odd, so dark/total != 1/2
+    // Compute the smallest integer k >= 0 such that (45-5k)% <= dark/total <= (55+5k)%
+    const k: int = Math.ceil(Math.abs(dark * 20 - total * 10) / total) - 1;
+    assert(0 <= k && k <= 9);
+    result += k * QrCode.PENALTY_N4;
+    assert(0 <= result && result <= 2568888); // Non-tight upper bound based on default values of PENALTY_N1, ..., N4
+    return result;
+  }
+
+  /*-- Private helper functions --*/
+
+  // Returns an ascending list of positions of alignment patterns for this version number.
+  // Each position is in the range [0,177), and are used on both the x and y axes.
+  // This could be implemented as lookup table of 40 variable-length lists of integers.
+  private getAlignmentPatternPositions(): Array<int> {
+    if (this.version == 1) return [];
+    else {
+      const numAlign: int = Math.floor(this.version / 7) + 2;
+      const step: int =
+        this.version == 32 ? 26 : Math.ceil((this.version * 4 + 4) / (numAlign * 2 - 2)) * 2;
+      let result: Array<int> = [6];
+      for (let pos = this.size - 7; result.length < numAlign; pos -= step) result.splice(1, 0, pos);
       return result;
     }
+  }
 
-    // Returns the number of 8-bit data (i.e. not error correction) codewords contained in any
-    // QR Code of the given version number and error correction level, with remainder bits discarded.
-    // This stateless pure function could be implemented as a (40*4)-cell lookup table.
-    private static getNumDataCodewords(ver: int, ecl: QrCode.Ecc): int {
-      return (
-        Math.floor(QrCode.getNumRawDataModules(ver) / 8) -
-        QrCode.ECC_CODEWORDS_PER_BLOCK[ecl.ordinal][ver] *
-          QrCode.NUM_ERROR_CORRECTION_BLOCKS[ecl.ordinal][ver]
-      );
-    }
+  // Returns the number of data bits that can be stored in a QR Code of the given version number, after
+  // all function modules are excluded. This includes remainder bits, so it might not be a multiple of 8.
+  // The result is in the range [208, 29648]. This could be implemented as a 40-entry lookup table.
+  private static getNumRawDataModules(ver: int): int {
+    if (ver < QrCode.MIN_VERSION || ver > QrCode.MAX_VERSION)
+      throw new RangeError("Version number out of range");
+    let result: int = (16 * ver + 128) * ver + 64;
+    if (ver >= 2) {
+      const numAlign: int = Math.floor(ver / 7) + 2;
+      result -= (25 * numAlign - 10) * numAlign - 55;
+      if (ver >= 7) result -= 36;
+    }
+    assert(208 <= result && result <= 29648);
+    return result;
+  }
 
-    // Returns a Reed-Solomon ECC generator polynomial for the given degree. This could be
-    // implemented as a lookup table over all possible parameter values, instead of as an algorithm.
-    private static reedSolomonComputeDivisor(degree: int): Array<byte> {
-      if (degree < 1 || degree > 255) throw new RangeError("Degree out of range");
-      // Polynomial coefficients are stored from highest to lowest power, excluding the leading term which is always 1.
-      // For example the polynomial x^3 + 255x^2 + 8x + 93 is stored as the uint8 array [255, 8, 93].
-      let result: Array<byte> = [];
-      for (let i = 0; i < degree - 1; i++) result.push(0);
-      result.push(1); // Start off with the monomial x^0
-
-      // Compute the product polynomial (x - r^0) * (x - r^1) * (x - r^2) * ... * (x - r^{degree-1}),
-      // and drop the highest monomial term which is always 1x^degree.
-      // Note that r = 0x02, which is a generator element of this field GF(2^8/0x11D).
-      let root = 1;
-      for (let i = 0; i < degree; i++) {
-        // Multiply the current product by (x - r^i)
-        for (let j = 0; j < result.length; j++) {
-          result[j] = QrCode.reedSolomonMultiply(result[j], root);
-          if (j + 1 < result.length) result[j] ^= result[j + 1];
-        }
-        root = QrCode.reedSolomonMultiply(root, 0x02);
-      }
-      return result;
-    }
+  // Returns the number of 8-bit data (i.e. not error correction) codewords contained in any
+  // QR Code of the given version number and error correction level, with remainder bits discarded.
+  // This stateless pure function could be implemented as a (40*4)-cell lookup table.
+  private static getNumDataCodewords(ver: int, ecl: QrCodeEcc): int {
+    return (
+      Math.floor(QrCode.getNumRawDataModules(ver) / 8) -
+      QrCode.ECC_CODEWORDS_PER_BLOCK[ecl.ordinal]![ver]! *
+        QrCode.NUM_ERROR_CORRECTION_BLOCKS[ecl.ordinal]![ver]!
+    );
+  }
 
-    // Returns the Reed-Solomon error correction codeword for the given data and divisor polynomials.
-    private static reedSolomonComputeRemainder(
-      data: Readonly<Array<byte>>,
-      divisor: Readonly<Array<byte>>,
-    ): Array<byte> {
-      let result: Array<byte> = divisor.map((_) => 0);
-      for (const b of data) {
-        // Polynomial division
-        const factor: byte = b ^ (result.shift() as byte);
-        result.push(0);
-        divisor.forEach((coef, i) => (result[i] ^= QrCode.reedSolomonMultiply(coef, factor)));
+  // Returns a Reed-Solomon ECC generator polynomial for the given degree. This could be
+  // implemented as a lookup table over all possible parameter values, instead of as an algorithm.
+  private static reedSolomonComputeDivisor(degree: int): Array<byte> {
+    if (degree < 1 || degree > 255) throw new RangeError("Degree out of range");
+    // Polynomial coefficients are stored from highest to lowest power, excluding the leading term which is always 1.
+    // For example the polynomial x^3 + 255x^2 + 8x + 93 is stored as the uint8 array [255, 8, 93].
+    let result: Array<byte> = [];
+    for (let i = 0; i < degree - 1; i++) result.push(0);
+    result.push(1); // Start off with the monomial x^0
+
+    // Compute the product polynomial (x - r^0) * (x - r^1) * (x - r^2) * ... * (x - r^{degree-1}),
+    // and drop the highest monomial term which is always 1x^degree.
+    // Note that r = 0x02, which is a generator element of this field GF(2^8/0x11D).
+    let root = 1;
+    for (let i = 0; i < degree; i++) {
+      // Multiply the current product by (x - r^i)
+      for (let j = 0; j < result.length; j++) {
+        result[j] = QrCode.reedSolomonMultiply(result[j]!, root);
+        if (j + 1 < result.length) result[j]! ^= result[j + 1]!;
       }
-      return result;
+      root = QrCode.reedSolomonMultiply(root, 0x02);
     }
+    return result;
+  }
 
-    // Returns the product of the two given field elements modulo GF(2^8/0x11D). The arguments and result
-    // are unsigned 8-bit integers. This could be implemented as a lookup table of 256*256 entries of uint8.
-    private static reedSolomonMultiply(x: byte, y: byte): byte {
-      if (x >>> 8 != 0 || y >>> 8 != 0) throw new RangeError("Byte out of range");
-      // Russian peasant multiplication
-      let z: int = 0;
-      for (let i = 7; i >= 0; i--) {
-        z = (z << 1) ^ ((z >>> 7) * 0x11d);
-        z ^= ((y >>> i) & 1) * x;
-      }
-      assert(z >>> 8 == 0);
-      return z as byte;
-    }
+  // Returns the Reed-Solomon error correction codeword for the given data and divisor polynomials.
+  private static reedSolomonComputeRemainder(
+    data: Readonly<Array<byte>>,
+    divisor: Readonly<Array<byte>>,
+  ): Array<byte> {
+    let result: Array<byte> = divisor.map((_) => 0);
+    for (const b of data) {
+      // Polynomial division
+      const factor: byte = b ^ (result.shift() as byte);
+      result.push(0);
+      divisor.forEach((coef, i) => (result[i]! ^= QrCode.reedSolomonMultiply(coef, factor)));
+    }
+    return result;
+  }
 
-    // Can only be called immediately after a light run is added, and
-    // returns either 0, 1, or 2. A helper function for getPenaltyScore().
-    private finderPenaltyCountPatterns(runHistory: Readonly<Array<int>>): int {
-      const n: int = runHistory[1];
-      assert(n <= this.size * 3);
-      const core: boolean =
-        n > 0 &&
-        runHistory[2] == n &&
-        runHistory[3] == n * 3 &&
-        runHistory[4] == n &&
-        runHistory[5] == n;
-      return (
-        (core && runHistory[0] >= n * 4 && runHistory[6] >= n ? 1 : 0) +
-        (core && runHistory[6] >= n * 4 && runHistory[0] >= n ? 1 : 0)
-      );
-    }
+  // Returns the product of the two given field elements modulo GF(2^8/0x11D). The arguments and result
+  // are unsigned 8-bit integers. This could be implemented as a lookup table of 256*256 entries of uint8.
+  private static reedSolomonMultiply(x: byte, y: byte): byte {
+    if (x >>> 8 != 0 || y >>> 8 != 0) throw new RangeError("Byte out of range");
+    // Russian peasant multiplication
+    let z: int = 0;
+    for (let i = 7; i >= 0; i--) {
+      z = (z << 1) ^ ((z >>> 7) * 0x11d);
+      z ^= ((y >>> i) & 1) * x;
+    }
+    assert(z >>> 8 == 0);
+    return z as byte;
+  }
 
-    // Must be called at the end of a line (row or column) of modules. A helper function for getPenaltyScore().
-    private finderPenaltyTerminateAndCount(
-      currentRunColor: boolean,
-      currentRunLength: int,
-      runHistory: Array<int>,
-    ): int {
-      if (currentRunColor) {
-        // Terminate dark run
-        this.finderPenaltyAddHistory(currentRunLength, runHistory);
-        currentRunLength = 0;
-      }
-      currentRunLength += this.size; // Add light border to final run
+  // Can only be called immediately after a light run is added, and
+  // returns either 0, 1, or 2. A helper function for getPenaltyScore().
+  private finderPenaltyCountPatterns(runHistory: Readonly<Array<int>>): int {
+    const n: int = runHistory[1]!;
+    assert(n <= this.size * 3);
+    const core: boolean =
+      n > 0 &&
+      runHistory[2] === n &&
+      runHistory[3] === n * 3 &&
+      runHistory[4] === n &&
+      runHistory[5] === n;
+    return (
+      (core && runHistory[0]! >= n * 4 && runHistory[6]! >= n ? 1 : 0) +
+      (core && runHistory[6]! >= n * 4 && runHistory[0]! >= n ? 1 : 0)
+    );
+  }
+
+  // Must be called at the end of a line (row or column) of modules. A helper function for getPenaltyScore().
+  private finderPenaltyTerminateAndCount(
+    currentRunColor: boolean,
+    currentRunLength: int,
+    runHistory: Array<int>,
+  ): int {
+    if (currentRunColor) {
+      // Terminate dark run
       this.finderPenaltyAddHistory(currentRunLength, runHistory);
-      return this.finderPenaltyCountPatterns(runHistory);
+      currentRunLength = 0;
     }
+    currentRunLength += this.size; // Add light border to final run
+    this.finderPenaltyAddHistory(currentRunLength, runHistory);
+    return this.finderPenaltyCountPatterns(runHistory);
+  }
 
-    // Pushes the given value to the front and drops the last value. A helper function for getPenaltyScore().
-    private finderPenaltyAddHistory(currentRunLength: int, runHistory: Array<int>): void {
-      if (runHistory[0] == 0) currentRunLength += this.size; // Add light border to initial run
-      runHistory.pop();
-      runHistory.unshift(currentRunLength);
-    }
+  // Pushes the given value to the front and drops the last value. A helper function for getPenaltyScore().
+  private finderPenaltyAddHistory(currentRunLength: int, runHistory: Array<int>): void {
+    if (runHistory[0] === 0) currentRunLength += this.size; // Add light border to initial run
+    runHistory.pop();
+    runHistory.unshift(currentRunLength);
+  }
 
-    /*-- Constants and tables --*/
-
-    // The minimum version number supported in the QR Code Model 2 standard.
-    public static readonly MIN_VERSION: int = 1;
-    // The maximum version number supported in the QR Code Model 2 standard.
-    public static readonly MAX_VERSION: int = 40;
-
-    // For use in getPenaltyScore(), when evaluating which mask is best.
-    private static readonly PENALTY_N1: int = 3;
-    private static readonly PENALTY_N2: int = 3;
-    private static readonly PENALTY_N3: int = 40;
-    private static readonly PENALTY_N4: int = 10;
-
-    private static readonly ECC_CODEWORDS_PER_BLOCK: Array<Array<int>> = [
-      // Version: (note that index 0 is for padding, and is set to an illegal value)
-      //0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40    Error correction level
-      [
-        -1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28,
-        30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
-      ], // Low
-      [
-        -1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28,
-        28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28,
-      ], // Medium
-      [
-        -1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30,
-        30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
-      ], // Quartile
-      [
-        -1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24,
-        30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
-      ], // High
-    ];
-
-    private static readonly NUM_ERROR_CORRECTION_BLOCKS: Array<Array<int>> = [
-      // Version: (note that index 0 is for padding, and is set to an illegal value)
-      //0, 1, 2, 3, 4, 5, 6, 7, 8, 9,10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40    Error correction level
-      [
-        -1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13,
-        14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25,
-      ], // Low
-      [
-        -1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21,
-        23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49,
-      ], // Medium
-      [
-        -1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29,
-        34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68,
-      ], // Quartile
-      [
-        -1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32,
-        35, 37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81,
-      ], // High
-    ];
-  }
-
-  // Appends the given number of low-order bits of the given value
-  // to the given buffer. Requires 0 <= len <= 31 and 0 <= val < 2^len.
-  function appendBits(val: int, len: int, bb: Array<bit>): void {
-    if (len < 0 || len > 31 || val >>> len != 0) throw new RangeError("Value out of range");
-    for (
-      let i = len - 1;
-      i >= 0;
-      i-- // Append bit by bit
-    )
-      bb.push((val >>> i) & 1);
-  }
-
-  // Returns true iff the i'th bit of x is set to 1.
-  function getBit(x: int, i: int): boolean {
-    return ((x >>> i) & 1) != 0;
-  }
-
-  // Throws an exception if the given condition is false.
-  function assert(cond: boolean): void {
-    if (!cond) throw new Error("Assertion error");
-  }
-
-  /*---- Data segment class ----*/
-
-  /*
-   * A segment of character/binary/control data in a QR Code symbol.
-   * Instances of this class are immutable.
-   * The mid-level way to create a segment is to take the payload data
-   * and call a static factory function such as QrSegment.makeNumeric().
-   * The low-level way to create a segment is to custom-make the bit buffer
-   * and call the QrSegment() constructor with appropriate values.
-   * This segment class imposes no length restrictions, but QR Codes have restrictions.
-   * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data.
-   * Any segment longer than this is meaningless for the purpose of generating QR Codes.
-   */
-  export class QrSegment {
-    /*-- Static factory functions (mid level) --*/
-
-    // Returns a segment representing the given binary data encoded in
-    // byte mode. All input byte arrays are acceptable. Any text string
-    // can be converted to UTF-8 bytes and encoded as a byte mode segment.
-    public static makeBytes(data: Readonly<Array<byte>>): QrSegment {
-      let bb: Array<bit> = [];
-      for (const b of data) appendBits(b, 8, bb);
-      return new QrSegment(QrSegment.Mode.BYTE, data.length, bb);
-    }
+  /*-- Constants and tables --*/
+
+  // The minimum version number supported in the QR Code Model 2 standard.
+  public static readonly MIN_VERSION: int = 1;
+  // The maximum version number supported in the QR Code Model 2 standard.
+  public static readonly MAX_VERSION: int = 40;
+
+  // For use in getPenaltyScore(), when evaluating which mask is best.
+  private static readonly PENALTY_N1: int = 3;
+  private static readonly PENALTY_N2: int = 3;
+  private static readonly PENALTY_N3: int = 40;
+  private static readonly PENALTY_N4: int = 10;
+
+  private static readonly ECC_CODEWORDS_PER_BLOCK: Array<Array<int>> = [
+    // Version: (note that index 0 is for padding, and is set to an illegal value)
+    //0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40    Error correction level
+    [
+      -1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30,
+      30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
+    ], // Low
+    [
+      -1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28,
+      28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28,
+    ], // Medium
+    [
+      -1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30,
+      30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
+    ], // Quartile
+    [
+      -1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24,
+      30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30,
+    ], // High
+  ];
+
+  private static readonly NUM_ERROR_CORRECTION_BLOCKS: Array<Array<int>> = [
+    // Version: (note that index 0 is for padding, and is set to an illegal value)
+    //0, 1, 2, 3, 4, 5, 6, 7, 8, 9,10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40    Error correction level
+    [
+      -1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13,
+      14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25,
+    ], // Low
+    [
+      -1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23,
+      25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49,
+    ], // Medium
+    [
+      -1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29,
+      34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68,
+    ], // Quartile
+    [
+      -1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35,
+      37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81,
+    ], // High
+  ];
+}
 
-    // Returns a segment representing the given string of decimal digits encoded in numeric mode.
-    public static makeNumeric(digits: string): QrSegment {
-      if (!QrSegment.isNumeric(digits))
-        throw new RangeError("String contains non-numeric characters");
-      let bb: Array<bit> = [];
-      for (let i = 0; i < digits.length; ) {
-        // Consume up to 3 digits per iteration
-        const n: int = Math.min(digits.length - i, 3);
-        appendBits(parseInt(digits.substring(i, i + n), 10), n * 3 + 1, bb);
-        i += n;
-      }
-      return new QrSegment(QrSegment.Mode.NUMERIC, digits.length, bb);
-    }
+// Appends the given number of low-order bits of the given value
+// to the given buffer. Requires 0 <= len <= 31 and 0 <= val < 2^len.
+function appendBits(val: int, len: int, bb: Array<bit>): void {
+  if (len < 0 || len > 31 || val >>> len != 0) throw new RangeError("Value out of range");
+  for (
+    let i = len - 1;
+    i >= 0;
+    i-- // Append bit by bit
+  )
+    bb.push((val >>> i) & 1);
+}
 
-    // Returns a segment representing the given text string encoded in alphanumeric mode.
-    // The characters allowed are: 0 to 9, A to Z (uppercase only), space,
-    // dollar, percent, asterisk, plus, hyphen, period, slash, colon.
-    public static makeAlphanumeric(text: string): QrSegment {
-      if (!QrSegment.isAlphanumeric(text))
-        throw new RangeError("String contains unencodable characters in alphanumeric mode");
-      let bb: Array<bit> = [];
-      let i: int;
-      for (i = 0; i + 2 <= text.length; i += 2) {
-        // Process groups of 2
-        let temp: int = QrSegment.ALPHANUMERIC_CHARSET.indexOf(text.charAt(i)) * 45;
-        temp += QrSegment.ALPHANUMERIC_CHARSET.indexOf(text.charAt(i + 1));
-        appendBits(temp, 11, bb);
-      }
-      if (i < text.length)
-        // 1 character remaining
-        appendBits(QrSegment.ALPHANUMERIC_CHARSET.indexOf(text.charAt(i)), 6, bb);
-      return new QrSegment(QrSegment.Mode.ALPHANUMERIC, text.length, bb);
-    }
+// Returns true iff the i'th bit of x is set to 1.
+function getBit(x: int, i: int): boolean {
+  return ((x >>> i) & 1) != 0;
+}
 
-    // Returns a new mutable list of zero or more segments to represent the given Unicode text string.
-    // The result may use various segment modes and switch modes to optimize the length of the bit stream.
-    public static makeSegments(text: string): Array<QrSegment> {
-      // Select the most efficient segment encoding automatically
-      if (text == "") return [];
-      else if (QrSegment.isNumeric(text)) return [QrSegment.makeNumeric(text)];
-      else if (QrSegment.isAlphanumeric(text)) return [QrSegment.makeAlphanumeric(text)];
-      else return [QrSegment.makeBytes(QrSegment.toUtf8ByteArray(text))];
-    }
+// Throws an exception if the given condition is false.
+function assert(cond: boolean): void {
+  if (!cond) throw new Error("Assertion error");
+}
 
-    // Returns a segment representing an Extended Channel Interpretation
-    // (ECI) designator with the given assignment value.
-    public static makeEci(assignVal: int): QrSegment {
-      let bb: Array<bit> = [];
-      if (assignVal < 0) throw new RangeError("ECI assignment value out of range");
-      else if (assignVal < 1 << 7) appendBits(assignVal, 8, bb);
-      else if (assignVal < 1 << 14) {
-        appendBits(0b10, 2, bb);
-        appendBits(assignVal, 14, bb);
-      } else if (assignVal < 1000000) {
-        appendBits(0b110, 3, bb);
-        appendBits(assignVal, 21, bb);
-      } else throw new RangeError("ECI assignment value out of range");
-      return new QrSegment(QrSegment.Mode.ECI, 0, bb);
-    }
+/*---- Data segment class ----*/
 
-    // Tests whether the given string can be encoded as a segment in numeric mode.
-    // A string is encodable iff each character is in the range 0 to 9.
-    public static isNumeric(text: string): boolean {
-      return QrSegment.NUMERIC_REGEX.test(text);
-    }
+/*
+ * A segment of character/binary/control data in a QR Code symbol.
+ * Instances of this class are immutable.
+ * The mid-level way to create a segment is to take the payload data
+ * and call a static factory function such as QrSegment.makeNumeric().
+ * The low-level way to create a segment is to custom-make the bit buffer
+ * and call the QrSegment() constructor with appropriate values.
+ * This segment class imposes no length restrictions, but QR Codes have restrictions.
+ * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data.
+ * Any segment longer than this is meaningless for the purpose of generating QR Codes.
+ */
+export class QrSegment {
+  public static Mode: typeof QrSegmentMode;
+
+  /*-- Static factory functions (mid level) --*/
+
+  // Returns a segment representing the given binary data encoded in
+  // byte mode. All input byte arrays are acceptable. Any text string
+  // can be converted to UTF-8 bytes and encoded as a byte mode segment.
+  public static makeBytes(data: Readonly<Array<byte>>): QrSegment {
+    let bb: Array<bit> = [];
+    for (const b of data) appendBits(b, 8, bb);
+    return new QrSegment(QrSegment.Mode.BYTE, data.length, bb);
+  }
 
-    // Tests whether the given string can be encoded as a segment in alphanumeric mode.
-    // A string is encodable iff each character is in the following set: 0 to 9, A to Z
-    // (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon.
-    public static isAlphanumeric(text: string): boolean {
-      return QrSegment.ALPHANUMERIC_REGEX.test(text);
-    }
+  // Returns a segment representing the given string of decimal digits encoded in numeric mode.
+  public static makeNumeric(digits: string): QrSegment {
+    if (!QrSegment.isNumeric(digits))
+      throw new RangeError("String contains non-numeric characters");
+    let bb: Array<bit> = [];
+    for (let i = 0; i < digits.length; ) {
+      // Consume up to 3 digits per iteration
+      const n: int = Math.min(digits.length - i, 3);
+      appendBits(parseInt(digits.substring(i, i + n), 10), n * 3 + 1, bb);
+      i += n;
+    }
+    return new QrSegment(QrSegment.Mode.NUMERIC, digits.length, bb);
+  }
 
-    /*-- Constructor (low level) and fields --*/
-
-    // Creates a new QR Code segment with the given attributes and data.
-    // The character count (numChars) must agree with the mode and the bit buffer length,
-    // but the constraint isn't checked. The given bit buffer is cloned and stored.
-    public constructor(
-      // The mode indicator of this segment.
-      public readonly mode: QrSegment.Mode,
-
-      // The length of this segment's unencoded data. Measured in characters for
-      // numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
-      // Always zero or positive. Not the same as the data's bit length.
-      public readonly numChars: int,
-
-      // The data bits of this segment. Accessed through getData().
-      private readonly bitData: Array<bit>,
-    ) {
-      if (numChars < 0) throw new RangeError("Invalid argument");
-      this.bitData = bitData.slice(); // Make defensive copy
-    }
+  // Returns a segment representing the given text string encoded in alphanumeric mode.
+  // The characters allowed are: 0 to 9, A to Z (uppercase only), space,
+  // dollar, percent, asterisk, plus, hyphen, period, slash, colon.
+  public static makeAlphanumeric(text: string): QrSegment {
+    if (!QrSegment.isAlphanumeric(text))
+      throw new RangeError("String contains unencodable characters in alphanumeric mode");
+    let bb: Array<bit> = [];
+    let i: int;
+    for (i = 0; i + 2 <= text.length; i += 2) {
+      // Process groups of 2
+      let temp: int = QrSegment.ALPHANUMERIC_CHARSET.indexOf(text.charAt(i)) * 45;
+      temp += QrSegment.ALPHANUMERIC_CHARSET.indexOf(text.charAt(i + 1));
+      appendBits(temp, 11, bb);
+    }
+    if (i < text.length)
+      // 1 character remaining
+      appendBits(QrSegment.ALPHANUMERIC_CHARSET.indexOf(text.charAt(i)), 6, bb);
+    return new QrSegment(QrSegment.Mode.ALPHANUMERIC, text.length, bb);
+  }
 
-    /*-- Methods --*/
+  // Returns a new mutable list of zero or more segments to represent the given Unicode text string.
+  // The result may use various segment modes and switch modes to optimize the length of the bit stream.
+  public static makeSegments(text: string): Array<QrSegment> {
+    // Select the most efficient segment encoding automatically
+    if (text == "") return [];
+    else if (QrSegment.isNumeric(text)) return [QrSegment.makeNumeric(text)];
+    else if (QrSegment.isAlphanumeric(text)) return [QrSegment.makeAlphanumeric(text)];
+    else return [QrSegment.makeBytes(QrSegment.toUtf8ByteArray(text))];
+  }
 
-    // Returns a new copy of the data bits of this segment.
-    public getData(): Array<bit> {
-      return this.bitData.slice(); // Make defensive copy
-    }
+  // Returns a segment representing an Extended Channel Interpretation
+  // (ECI) designator with the given assignment value.
+  public static makeEci(assignVal: int): QrSegment {
+    let bb: Array<bit> = [];
+    if (assignVal < 0) throw new RangeError("ECI assignment value out of range");
+    else if (assignVal < 1 << 7) appendBits(assignVal, 8, bb);
+    else if (assignVal < 1 << 14) {
+      appendBits(0b10, 2, bb);
+      appendBits(assignVal, 14, bb);
+    } else if (assignVal < 1000000) {
+      appendBits(0b110, 3, bb);
+      appendBits(assignVal, 21, bb);
+    } else throw new RangeError("ECI assignment value out of range");
+    return new QrSegment(QrSegment.Mode.ECI, 0, bb);
+  }
 
-    // (Package-private) Calculates and returns the number of bits needed to encode the given segments at
-    // the given version. The result is infinity if a segment has too many characters to fit its length field.
-    public static getTotalBits(segs: Readonly<Array<QrSegment>>, version: int): number {
-      let result: number = 0;
-      for (const seg of segs) {
-        const ccbits: int = seg.mode.numCharCountBits(version);
-        if (seg.numChars >= 1 << ccbits) return Infinity; // The segment's length doesn't fit the field's bit width
-        result += 4 + ccbits + seg.bitData.length;
-      }
-      return result;
+  // Tests whether the given string can be encoded as a segment in numeric mode.
+  // A string is encodable iff each character is in the range 0 to 9.
+  public static isNumeric(text: string): boolean {
+    return QrSegment.NUMERIC_REGEX.test(text);
+  }
+
+  // Tests whether the given string can be encoded as a segment in alphanumeric mode.
+  // A string is encodable iff each character is in the following set: 0 to 9, A to Z
+  // (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon.
+  public static isAlphanumeric(text: string): boolean {
+    return QrSegment.ALPHANUMERIC_REGEX.test(text);
+  }
+
+  /*-- Constructor (low level) and fields --*/
+
+  public readonly mode: QrSegmentMode;
+  public readonly numChars: int;
+  private readonly bitData: Array<bit>;
+
+  // Creates a new QR Code segment with the given attributes and data.
+  // The character count (numChars) must agree with the mode and the bit buffer length,
+  // but the constraint isn't checked. The given bit buffer is cloned and stored.
+  public constructor(
+    // The mode indicator of this segment.
+    mode: QrSegmentMode,
+
+    // The length of this segment's unencoded data. Measured in characters for
+    // numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
+    // Always zero or positive. Not the same as the data's bit length.
+    numChars: int,
+
+    // The data bits of this segment. Accessed through getData().
+    bitData: Array<bit>,
+  ) {
+    this.mode = mode;
+    this.numChars = numChars;
+    if (numChars < 0) throw new RangeError("Invalid argument");
+    this.bitData = bitData.slice(); // Make defensive copy
+  }
+
+  /*-- Methods --*/
+
+  // Returns a new copy of the data bits of this segment.
+  public getData(): Array<bit> {
+    return this.bitData.slice(); // Make defensive copy
+  }
+
+  // (Package-private) Calculates and returns the number of bits needed to encode the given segments at
+  // the given version. The result is infinity if a segment has too many characters to fit its length field.
+  public static getTotalBits(segs: Readonly<Array<QrSegment>>, version: int): number {
+    let result: number = 0;
+    for (const seg of segs) {
+      const ccbits: int = seg.mode.numCharCountBits(version);
+      if (seg.numChars >= 1 << ccbits) return Infinity; // The segment's length doesn't fit the field's bit width
+      result += 4 + ccbits + seg.bitData.length;
     }
+    return result;
+  }
 
-    // Returns a new array of bytes representing the given string encoded in UTF-8.
-    private static toUtf8ByteArray(str: string): Array<byte> {
-      str = encodeURI(str);
-      let result: Array<byte> = [];
-      for (let i = 0; i < str.length; i++) {
-        if (str.charAt(i) != "%") result.push(str.charCodeAt(i));
-        else {
-          result.push(parseInt(str.substring(i + 1, i + 3), 16));
-          i += 2;
-        }
+  // Returns a new array of bytes representing the given string encoded in UTF-8.
+  private static toUtf8ByteArray(str: string): Array<byte> {
+    str = encodeURI(str);
+    let result: Array<byte> = [];
+    for (let i = 0; i < str.length; i++) {
+      if (str.charAt(i) != "%") result.push(str.charCodeAt(i));
+      else {
+        result.push(parseInt(str.substring(i + 1, i + 3), 16));
+        i += 2;
       }
-      return result;
     }
+    return result;
+  }
 
-    /*-- Constants --*/
+  /*-- Constants --*/
 
-    // Describes precisely all strings that are encodable in numeric mode.
-    private static readonly NUMERIC_REGEX: RegExp = /^[0-9]*$/;
+  // Describes precisely all strings that are encodable in numeric mode.
+  private static readonly NUMERIC_REGEX: RegExp = /^[0-9]*$/;
 
-    // Describes precisely all strings that are encodable in alphanumeric mode.
-    private static readonly ALPHANUMERIC_REGEX: RegExp = /^[A-Z0-9 $%*+.\/:-]*$/;
+  // Describes precisely all strings that are encodable in alphanumeric mode.
+  private static readonly ALPHANUMERIC_REGEX: RegExp = /^[A-Z0-9 $%*+.\/:-]*$/;
 
-    // The set of all legal characters in alphanumeric mode,
-    // where each character value maps to the index in the string.
-    private static readonly ALPHANUMERIC_CHARSET: string =
-      "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:";
-  }
+  // The set of all legal characters in alphanumeric mode,
+  // where each character value maps to the index in the string.
+  private static readonly ALPHANUMERIC_CHARSET: string =
+    "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:";
 }
 
 /*---- Public helper enumeration ----*/
 
-namespace qrcodegen.QrCode {
-  type int = number;
+class QrCodeEcc {
+  /*-- Constants --*/
 
-  /*
-   * The error correction level in a QR Code symbol. Immutable.
-   */
-  export class Ecc {
-    /*-- Constants --*/
+  public static readonly LOW = new QrCodeEcc(0, 1); // The QR Code can tolerate about  7% erroneous codewords
+  public static readonly MEDIUM = new QrCodeEcc(1, 0); // The QR Code can tolerate about 15% erroneous codewords
+  public static readonly QUARTILE = new QrCodeEcc(2, 3); // The QR Code can tolerate about 25% erroneous codewords
+  public static readonly HIGH = new QrCodeEcc(3, 2); // The QR Code can tolerate about 30% erroneous codewords
 
-    public static readonly LOW = new Ecc(0, 1); // The QR Code can tolerate about  7% erroneous codewords
-    public static readonly MEDIUM = new Ecc(1, 0); // The QR Code can tolerate about 15% erroneous codewords
-    public static readonly QUARTILE = new Ecc(2, 3); // The QR Code can tolerate about 25% erroneous codewords
-    public static readonly HIGH = new Ecc(3, 2); // The QR Code can tolerate about 30% erroneous codewords
+  public readonly ordinal: int;
+  public readonly formatBits: int;
 
-    /*-- Constructor and fields --*/
+  /*-- Constructor and fields --*/
 
-    private constructor(
-      // In the range 0 to 3 (unsigned 2-bit integer).
-      public readonly ordinal: int,
-      // (Package-private) In the range 0 to 3 (unsigned 2-bit integer).
-      public readonly formatBits: int,
-    ) {}
+  private constructor(
+    // In the range 0 to 3 (unsigned 2-bit integer).
+    ordinal: int,
+    // (Package-private) In the range 0 to 3 (unsigned 2-bit integer).
+    formatBits: int,
+  ) {
+    this.ordinal = ordinal;
+    this.formatBits = formatBits;
   }
 }
 
 /*---- Public helper enumeration ----*/
 
-namespace qrcodegen.QrSegment {
-  type int = number;
+class QrSegmentMode {
+  /*-- Constants --*/
 
-  /*
-   * Describes how a segment's data bits are interpreted. Immutable.
-   */
-  export class Mode {
-    /*-- Constants --*/
+  public static readonly NUMERIC = new QrSegmentMode(0x1, [10, 12, 14]);
+  public static readonly ALPHANUMERIC = new QrSegmentMode(0x2, [9, 11, 13]);
+  public static readonly BYTE = new QrSegmentMode(0x4, [8, 16, 16]);
+  public static readonly KANJI = new QrSegmentMode(0x8, [8, 10, 12]);
+  public static readonly ECI = new QrSegmentMode(0x7, [0, 0, 0]);
 
-    public static readonly NUMERIC = new Mode(0x1, [10, 12, 14]);
-    public static readonly ALPHANUMERIC = new Mode(0x2, [9, 11, 13]);
-    public static readonly BYTE = new Mode(0x4, [8, 16, 16]);
-    public static readonly KANJI = new Mode(0x8, [8, 10, 12]);
-    public static readonly ECI = new Mode(0x7, [0, 0, 0]);
+  public readonly modeBits: int;
+  private readonly numBitsCharCount: [int, int, int];
 
-    /*-- Constructor and fields --*/
+  /*-- Constructor and fields --*/
 
-    private constructor(
-      // The mode indicator bits, which is a uint4 value (range 0 to 15).
-      public readonly modeBits: int,
-      // Number of character count bits for three different version ranges.
-      private readonly numBitsCharCount: [int, int, int],
-    ) {}
+  private constructor(
+    // The mode indicator bits, which is a uint4 value (range 0 to 15).
+    modeBits: int,
+    // Number of character count bits for three different version ranges.
+    numBitsCharCount: [int, int, int],
+  ) {
+    this.modeBits = modeBits;
+    this.numBitsCharCount = numBitsCharCount;
+  }
 
-    /*-- Method --*/
+  /*-- Method --*/
 
-    // (Package-private) Returns the bit width of the character count field for a segment in
-    // this mode in a QR Code at the given version number. The result is in the range [0, 16].
-    public numCharCountBits(ver: int): int {
-      return this.numBitsCharCount[Math.floor((ver + 7) / 17)];
-    }
+  // (Package-private) Returns the bit width of the character count field for a segment in
+  // this mode in a QR Code at the given version number. The result is in the range [0, 16].
+  public numCharCountBits(ver: int): int {
+    return this.numBitsCharCount[Math.floor((ver + 7) / 17)]!;
   }
 }
 
-export const QrCode = qrcodegen.QrCode;
-export const QrSegment = qrcodegen.QrSegment;
+QrCode.Ecc = QrCodeEcc;
+QrSegment.Mode = QrSegmentMode;
diff --git a/packages/shared/src/schemaJson.test.ts b/packages/shared/src/schemaJson.test.ts
new file mode 100644
index 00000000000..7f3db7034b5
--- /dev/null
+++ b/packages/shared/src/schemaJson.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+
+import { extractJsonObject } from "./schemaJson.ts";
+
+describe("schemaJson helpers", () => {
+  it("extracts a balanced JSON object from surrounding text", () => {
+    expect(
+      extractJsonObject(`Sure, here is the JSON:
+\`\`\`json
+{
+  "subject": "Update README",
+  "body": ""
+}
+\`\`\`
+Done.`),
+    ).toBe(`{
+  "subject": "Update README",
+  "body": ""
+}`);
+  });
+
+  it("ignores braces inside strings while finding the object boundary", () => {
+    expect(
+      extractJsonObject('prefix {"message":"literal } brace","nested":{"ok":true}} suffix'),
+    ).toBe('{"message":"literal } brace","nested":{"ok":true}}');
+  });
+
+  it("returns trimmed input when no JSON object starts", () => {
+    expect(extractJsonObject("  no structured output  ")).toBe("no structured output");
+  });
+});
diff --git a/packages/shared/src/schemaJson.ts b/packages/shared/src/schemaJson.ts
index 9e38b1f8b85..0d879913ebf 100644
--- a/packages/shared/src/schemaJson.ts
+++ b/packages/shared/src/schemaJson.ts
@@ -1,14 +1,12 @@
-import {
-  Cause,
-  Effect,
-  Exit,
-  Option,
-  Result,
-  Schema,
-  SchemaGetter,
-  SchemaIssue,
-  SchemaTransformation,
-} from "effect";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaGetter from "effect/SchemaGetter";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
 
 export const decodeJsonResult = <S extends Schema.Codec<unknown, unknown, never, never>>(
   schema: S,
@@ -86,6 +84,10 @@ export const fromLenientJsonString = new SchemaTransformation.Transformation(
   SchemaGetter.stringifyJson(),
 );
 
+export const prettyJsonString = SchemaGetter.parseJson<string>().compose(
+  SchemaGetter.stringifyJson({ space: 2 }),
+);
+
 /**
  * Build a schema that decodes a lenient JSON string into `A`.
  *
@@ -94,3 +96,65 @@ export const fromLenientJsonString = new SchemaTransformation.Transformation(
  */
 export const fromLenientJson = <S extends Schema.Top>(schema: S) =>
   Schema.String.pipe(Schema.decodeTo(schema, fromLenientJsonString));
+
+export function extractJsonObject(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return trimmed;
+  }
+
+  const start = trimmed.indexOf("{");
+  if (start < 0) {
+    return trimmed;
+  }
+
+  let depth = 0;
+  let inString = false;
+  let escaping = false;
+  for (let index = start; index < trimmed.length; index += 1) {
+    const char = trimmed[index];
+    if (inString) {
+      if (escaping) {
+        escaping = false;
+      } else if (char === "\\") {
+        escaping = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return trimmed.slice(start, index + 1);
+      }
+    }
+  }
+
+  return trimmed.slice(start);
+}
+
+/**
+ * Build a JSON string schema that encodes with stable 2-space formatting.
+ *
+ * Decode behavior matches `Schema.fromJsonString(schema)`. Encode behavior
+ * keeps the transformation schema-based while preserving human-readable JSON.
+ */
+export const fromJsonStringPretty = <S extends Schema.Top>(schema: S) =>
+  Schema.fromJsonString(schema).pipe(
+    Schema.encode({
+      decode: prettyJsonString,
+      encode: prettyJsonString,
+    }),
+  );
diff --git a/packages/shared/src/searchRanking.test.ts b/packages/shared/src/searchRanking.test.ts
index d8c4b3d6ca4..dc43770bddd 100644
--- a/packages/shared/src/searchRanking.test.ts
+++ b/packages/shared/src/searchRanking.test.ts
@@ -6,7 +6,7 @@ import {
   normalizeSearchQuery,
   scoreQueryMatch,
   scoreSubsequenceMatch,
-} from "./searchRanking";
+} from "./searchRanking.ts";
 
 describe("normalizeSearchQuery", () => {
   it("trims and lowercases queries", () => {
diff --git a/packages/shared/src/semver.test.ts b/packages/shared/src/semver.test.ts
new file mode 100644
index 00000000000..b3c629740a7
--- /dev/null
+++ b/packages/shared/src/semver.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { compareSemverVersions, normalizeSemverVersion, satisfiesSemverRange } from "./semver.ts";
+
+describe("semver helpers", () => {
+  it("matches supported range groups", () => {
+    const range = "^22.16 || ^23.11 || >=24.10";
+
+    expect(satisfiesSemverRange("22.16.0", range)).toBe(true);
+    expect(satisfiesSemverRange("23.11.1", range)).toBe(true);
+    expect(satisfiesSemverRange("24.10.0", range)).toBe(true);
+    expect(satisfiesSemverRange("22.15.9", range)).toBe(false);
+    expect(satisfiesSemverRange("23.10.9", range)).toBe(false);
+    expect(satisfiesSemverRange("24.9.9", range)).toBe(false);
+  });
+
+  it("normalizes versions with a missing patch segment", () => {
+    expect(normalizeSemverVersion("2.1")).toBe("2.1.0");
+  });
+
+  it("compares prerelease versions before stable versions", () => {
+    expect(compareSemverVersions("2.1.111-beta.1", "2.1.111")).toBeLessThan(0);
+  });
+
+  it("falls back to lexical comparison for malformed numeric segments", () => {
+    expect(compareSemverVersions("1.2.3abc", "1.2.10")).toBeGreaterThan(0);
+  });
+
+  it("supports comparison comparators", () => {
+    expect(satisfiesSemverRange("24.9.0", ">=24.0 <24.10")).toBe(true);
+    expect(satisfiesSemverRange("24.10.0", ">=24.0 <24.10")).toBe(false);
+  });
+
+  it("honors caret range upper bounds for zero-major versions", () => {
+    expect(satisfiesSemverRange("0.2.3", "^0.2.3")).toBe(true);
+    expect(satisfiesSemverRange("0.2.9", "^0.2.3")).toBe(true);
+    expect(satisfiesSemverRange("0.3.0", "^0.2.3")).toBe(false);
+    expect(satisfiesSemverRange("0.5.0", "^0.2.3")).toBe(false);
+    expect(satisfiesSemverRange("0.0.3", "^0.0.3")).toBe(true);
+    expect(satisfiesSemverRange("0.0.4", "^0.0.3")).toBe(false);
+  });
+
+  it("rejects invalid versions and unsupported range syntax", () => {
+    expect(satisfiesSemverRange("not-a-version", ">=24.0")).toBe(false);
+    expect(satisfiesSemverRange("24.10.0", "~24.10")).toBe(false);
+  });
+
+  it("keeps the range checker stringifiable and executable as plain JavaScript", () => {
+    const source = satisfiesSemverRange.toString();
+    const recreated = Function(`return (${source});`)() as typeof satisfiesSemverRange;
+
+    expect(source).toContain("function satisfiesSemverRange");
+    expect(source).not.toContain(": string");
+    expect(source).not.toContain(": boolean");
+    expect(recreated("24.10.0", ">=24.10")).toBe(true);
+    expect(recreated("24.9.9", ">=24.10")).toBe(false);
+  });
+});
diff --git a/packages/shared/src/semver.ts b/packages/shared/src/semver.ts
new file mode 100644
index 00000000000..de213764504
--- /dev/null
+++ b/packages/shared/src/semver.ts
@@ -0,0 +1,216 @@
+interface ParsedSemver {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly prerelease: ReadonlyArray<string>;
+}
+
+const SEMVER_NUMBER_SEGMENT = /^\d+$/;
+
+export function normalizeSemverVersion(version: string): string {
+  const [main, prerelease] = version.trim().split("-", 2);
+  const segments = (main ?? "")
+    .split(".")
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+
+  if (segments.length === 2) {
+    segments.push("0");
+  }
+
+  return prerelease ? `${segments.join(".")}-${prerelease}` : segments.join(".");
+}
+
+export function parseSemver(value: string): ParsedSemver | null {
+  const normalized = normalizeSemverVersion(value).replace(/^v/, "");
+  const [main = "", prerelease] = normalized.split("-", 2);
+  const segments = main.split(".");
+  if (segments.length !== 3) {
+    return null;
+  }
+
+  const [majorSegment, minorSegment, patchSegment] = segments;
+  if (majorSegment === undefined || minorSegment === undefined || patchSegment === undefined) {
+    return null;
+  }
+  if (
+    !SEMVER_NUMBER_SEGMENT.test(majorSegment) ||
+    !SEMVER_NUMBER_SEGMENT.test(minorSegment) ||
+    !SEMVER_NUMBER_SEGMENT.test(patchSegment)
+  ) {
+    return null;
+  }
+
+  const major = Number.parseInt(majorSegment, 10);
+  const minor = Number.parseInt(minorSegment, 10);
+  const patch = Number.parseInt(patchSegment, 10);
+  if (![major, minor, patch].every(Number.isInteger)) {
+    return null;
+  }
+
+  return {
+    major,
+    minor,
+    patch,
+    prerelease:
+      prerelease
+        ?.split(".")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0) ?? [],
+  };
+}
+
+function comparePrereleaseIdentifier(left: string, right: string): number {
+  const leftNumeric = SEMVER_NUMBER_SEGMENT.test(left);
+  const rightNumeric = SEMVER_NUMBER_SEGMENT.test(right);
+
+  if (leftNumeric && rightNumeric) {
+    return Number.parseInt(left, 10) - Number.parseInt(right, 10);
+  }
+  if (leftNumeric) {
+    return -1;
+  }
+  if (rightNumeric) {
+    return 1;
+  }
+  return left.localeCompare(right);
+}
+
+export function compareSemverVersions(left: string, right: string): number {
+  const parsedLeft = parseSemver(left);
+  const parsedRight = parseSemver(right);
+  if (!parsedLeft || !parsedRight) {
+    return left.localeCompare(right);
+  }
+
+  if (parsedLeft.major !== parsedRight.major) {
+    return parsedLeft.major - parsedRight.major;
+  }
+  if (parsedLeft.minor !== parsedRight.minor) {
+    return parsedLeft.minor - parsedRight.minor;
+  }
+  if (parsedLeft.patch !== parsedRight.patch) {
+    return parsedLeft.patch - parsedRight.patch;
+  }
+
+  if (parsedLeft.prerelease.length === 0 && parsedRight.prerelease.length === 0) {
+    return 0;
+  }
+  if (parsedLeft.prerelease.length === 0) {
+    return 1;
+  }
+  if (parsedRight.prerelease.length === 0) {
+    return -1;
+  }
+
+  const length = Math.max(parsedLeft.prerelease.length, parsedRight.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftIdentifier = parsedLeft.prerelease[index];
+    const rightIdentifier = parsedRight.prerelease[index];
+    if (leftIdentifier === undefined) {
+      return -1;
+    }
+    if (rightIdentifier === undefined) {
+      return 1;
+    }
+    const comparison = comparePrereleaseIdentifier(leftIdentifier, rightIdentifier);
+    if (comparison !== 0) {
+      return comparison;
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * Small semver range checker for CLI/runtime gates.
+ *
+ * Keep the function body valid plain JavaScript: SSH startup stringifies this
+ * function and runs it on remote Node versions before TypeScript support is known.
+ *
+ * @param rawVersion Version string, with or without a leading `v`.
+ * @param range Space-separated comparators, with `||` range groups.
+ * @returns Whether `rawVersion` satisfies the supported range syntax.
+ */
+export const satisfiesSemverRange: (rawVersion: string, range: string) => boolean =
+  function satisfiesSemverRange(rawVersion, range) {
+    const normalizedVersion = String(rawVersion).trim().replace(/^v/, "");
+    const versionMatch = normalizedVersion.match(
+      /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-[0-9A-Za-z.-]+)?$/,
+    );
+    if (!versionMatch) {
+      return false;
+    }
+
+    const version = {
+      major: Number(versionMatch[1]),
+      minor: Number(versionMatch[2] || 0),
+      patch: Number(versionMatch[3] || 0),
+    };
+
+    return range.split("||").some((group) => {
+      const comparators = group.trim().split(/\s+/).filter(Boolean);
+      if (comparators.length === 0) {
+        return false;
+      }
+      return comparators.every((comparator) => {
+        const match = comparator.trim().match(/^(\^|>=|>|<=|<|=)?\s*v?(\d+(?:\.\d+){0,2})$/);
+        if (!match) {
+          return false;
+        }
+        const targetVersion = match[2];
+        if (targetVersion === undefined) {
+          return false;
+        }
+        const targetMatch = targetVersion.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+        if (!targetMatch) {
+          return false;
+        }
+        const target = {
+          major: Number(targetMatch[1]),
+          minor: Number(targetMatch[2] || 0),
+          patch: Number(targetMatch[3] || 0),
+        };
+        const compared =
+          version.major !== target.major
+            ? version.major > target.major
+              ? 1
+              : -1
+            : version.minor !== target.minor
+              ? version.minor > target.minor
+                ? 1
+                : -1
+              : version.patch !== target.patch
+                ? version.patch > target.patch
+                  ? 1
+                  : -1
+                : 0;
+        const operator = match[1] || "=";
+        switch (operator) {
+          case "^":
+            if (compared < 0) {
+              return false;
+            }
+            if (target.major > 0) {
+              return version.major === target.major;
+            }
+            if (target.minor > 0) {
+              return version.major === 0 && version.minor === target.minor;
+            }
+            return version.major === 0 && version.minor === 0 && version.patch === target.patch;
+          case ">=":
+            return compared >= 0;
+          case ">":
+            return compared > 0;
+          case "<=":
+            return compared <= 0;
+          case "<":
+            return compared < 0;
+          case "=":
+            return compared === 0;
+          default:
+            return false;
+        }
+      });
+    });
+  };
diff --git a/packages/shared/src/serverSettings.test.ts b/packages/shared/src/serverSettings.test.ts
index 0ac5e415dff..3e8114f0dc2 100644
--- a/packages/shared/src/serverSettings.test.ts
+++ b/packages/shared/src/serverSettings.test.ts
@@ -1,9 +1,16 @@
+import {
+  DEFAULT_SERVER_SETTINGS,
+  ProviderDriverKind,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
+import { createModelSelection } from "./model.ts";
 import {
+  applyServerSettingsPatch,
   extractPersistedServerObservabilitySettings,
   normalizePersistedServerSettingString,
   parsePersistedServerObservabilitySettings,
-} from "./serverSettings";
+} from "./serverSettings.ts";
 
 describe("serverSettings helpers", () => {
   it("normalizes optional persisted strings", () => {
@@ -50,4 +57,141 @@ describe("serverSettings helpers", () => {
       otlpMetricsUrl: undefined,
     });
   });
+
+  it("replaces text generation selection when provider/model are provided", () => {
+    const current = {
+      ...DEFAULT_SERVER_SETTINGS,
+      textGenerationModelSelection: createModelSelection(
+        ProviderInstanceId.make("codex"),
+        "gpt-5.4-mini",
+        [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
+      ),
+    };
+
+    expect(
+      applyServerSettingsPatch(current, {
+        textGenerationModelSelection: {
+          instanceId: ProviderInstanceId.make("codex"),
+          model: "gpt-5.4-mini",
+        },
+      }).textGenerationModelSelection,
+    ).toEqual({
+      instanceId: "codex",
+      model: "gpt-5.4-mini",
+    });
+  });
+
+  it("still deep merges text generation selection when only options are provided", () => {
+    const current = {
+      ...DEFAULT_SERVER_SETTINGS,
+      textGenerationModelSelection: createModelSelection(
+        ProviderInstanceId.make("codex"),
+        "gpt-5.4-mini",
+        [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
+      ),
+    };
+
+    expect(
+      applyServerSettingsPatch(current, {
+        textGenerationModelSelection: {
+          options: [{ id: "fastMode", value: false }],
+        },
+      }).textGenerationModelSelection,
+    ).toEqual({
+      instanceId: "codex",
+      model: "gpt-5.4-mini",
+      options: [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: false },
+      ],
+    });
+  });
+
+  it("replaces text generation selection across providers without leaking stale options", () => {
+    const current = {
+      ...DEFAULT_SERVER_SETTINGS,
+      textGenerationModelSelection: createModelSelection(
+        ProviderInstanceId.make("codex"),
+        "gpt-5.4-mini",
+        [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
+      ),
+    };
+
+    expect(
+      applyServerSettingsPatch(current, {
+        textGenerationModelSelection: {
+          instanceId: ProviderInstanceId.make("opencode"),
+          model: "openai/gpt-5",
+        },
+      }).textGenerationModelSelection,
+    ).toEqual({
+      instanceId: "opencode",
+      model: "openai/gpt-5",
+    });
+  });
+
+  it("accepts array-based text generation selection patches", () => {
+    expect(
+      applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+        textGenerationModelSelection: {
+          instanceId: ProviderInstanceId.make("opencode"),
+          model: "openai/gpt-5",
+          options: [
+            { id: "variant", value: "prod" },
+            { id: "agent", value: "build" },
+          ],
+        },
+      }).textGenerationModelSelection,
+    ).toEqual({
+      instanceId: "opencode",
+      model: "openai/gpt-5",
+      options: [
+        { id: "variant", value: "prod" },
+        { id: "agent", value: "build" },
+      ],
+    });
+  });
+
+  it("replaces providerInstances maps so omitted instance fields are cleared", () => {
+    const codexId = ProviderInstanceId.make("codex");
+    const current = {
+      ...DEFAULT_SERVER_SETTINGS,
+      providerInstances: {
+        [codexId]: {
+          driver: ProviderDriverKind.make("codex"),
+          displayName: "Codex Work",
+          accentColor: "#7c3aed",
+          enabled: true,
+          config: { homePath: "~/.codex" },
+        },
+      },
+    };
+
+    expect(
+      applyServerSettingsPatch(current, {
+        providerInstances: {
+          [codexId]: {
+            driver: ProviderDriverKind.make("codex"),
+            displayName: "Codex Work",
+            enabled: true,
+            config: { homePath: "~/.codex" },
+          },
+        },
+      }).providerInstances[codexId],
+    ).toEqual({
+      driver: ProviderDriverKind.make("codex"),
+      displayName: "Codex Work",
+      enabled: true,
+      config: { homePath: "~/.codex" },
+    });
+  });
 });
diff --git a/packages/shared/src/serverSettings.ts b/packages/shared/src/serverSettings.ts
index e7b25606dc1..1bbf466f60b 100644
--- a/packages/shared/src/serverSettings.ts
+++ b/packages/shared/src/serverSettings.ts
@@ -1,8 +1,12 @@
-import { ServerSettings } from "@t3tools/contracts";
-import { Schema } from "effect";
-import { fromLenientJson } from "./schemaJson";
+import { ServerSettings, type ServerSettingsPatch } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { deepMerge } from "./Struct.ts";
+import { fromLenientJson } from "./schemaJson.ts";
+import { createModelSelection } from "./model.ts";
 
 const ServerSettingsJson = fromLenientJson(ServerSettings);
+const decodeServerSettingsJson = Schema.decodeUnknownOption(ServerSettingsJson);
 
 export interface PersistedServerObservabilitySettings {
   readonly otlpTracesUrl: string | undefined;
@@ -31,10 +35,71 @@ export function extractPersistedServerObservabilitySettings(input: {
 export function parsePersistedServerObservabilitySettings(
   raw: string,
 ): PersistedServerObservabilitySettings {
-  try {
-    const decoded = Schema.decodeUnknownSync(ServerSettingsJson)(raw);
-    return extractPersistedServerObservabilitySettings(decoded);
-  } catch {
-    return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
+  const decoded = decodeServerSettingsJson(raw);
+  if (Option.isSome(decoded)) {
+    return extractPersistedServerObservabilitySettings(decoded.value);
   }
+  return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
+}
+
+function shouldReplaceTextGenerationModelSelection(
+  patch: ServerSettingsPatch["textGenerationModelSelection"] | undefined,
+): boolean {
+  return Boolean(patch && (patch.instanceId !== undefined || patch.model !== undefined));
+}
+
+function mergeModelSelectionOptionsById(input: {
+  current: ReadonlyArray<{ readonly id: string; readonly value: string | boolean }> | undefined;
+  patch: ReadonlyArray<{ readonly id: string; readonly value: string | boolean }> | undefined;
+}): Array<{ id: string; value: string | boolean }> | undefined {
+  if (input.patch === undefined) {
+    return input.current ? [...input.current] : undefined;
+  }
+  if (input.patch.length === 0) {
+    return undefined;
+  }
+
+  const merged = new Map((input.current ?? []).map((selection) => [selection.id, selection.value]));
+  for (const selection of input.patch) {
+    merged.set(selection.id, selection.value);
+  }
+  return [...merged.entries()].map(([id, value]) => ({ id, value }));
+}
+
+/**
+ * Applies a server settings patch while treating textGenerationModelSelection as
+ * replace-on-provider/model updates. This prevents stale nested options from
+ * surviving a reset patch that intentionally omits options.
+ */
+export function applyServerSettingsPatch(
+  current: ServerSettings,
+  patch: ServerSettingsPatch,
+): ServerSettings {
+  const selectionPatch = patch.textGenerationModelSelection;
+  const { automaticGitFetchInterval, ...patchForMerge } = patch;
+  const next = deepMerge(current, patchForMerge);
+  const nextWithReplacements = {
+    ...next,
+    ...(patch.providerInstances !== undefined
+      ? { providerInstances: patch.providerInstances }
+      : {}),
+    ...(automaticGitFetchInterval !== undefined ? { automaticGitFetchInterval } : {}),
+  };
+  if (!selectionPatch) {
+    return nextWithReplacements;
+  }
+
+  const instanceId = selectionPatch.instanceId ?? current.textGenerationModelSelection.instanceId;
+  const model = selectionPatch.model ?? current.textGenerationModelSelection.model;
+  const options = shouldReplaceTextGenerationModelSelection(selectionPatch)
+    ? selectionPatch.options
+    : mergeModelSelectionOptionsById({
+        current: current.textGenerationModelSelection.options,
+        patch: selectionPatch.options,
+      });
+
+  return {
+    ...nextWithReplacements,
+    textGenerationModelSelection: createModelSelection(instanceId, model, options),
+  };
 }
diff --git a/packages/shared/src/shell.test.ts b/packages/shared/src/shell.test.ts
index e2393eefff6..214c03a7e53 100644
--- a/packages/shared/src/shell.test.ts
+++ b/packages/shared/src/shell.test.ts
@@ -2,9 +2,18 @@ import { describe, expect, it, vi } from "vitest";
 
 import {
   extractPathFromShellOutput,
+  isCommandAvailable,
+  listLoginShellCandidates,
+  mergePathEntries,
+  mergePathValues,
   readEnvironmentFromLoginShell,
+  readEnvironmentFromWindowsShell,
+  readPathFromLaunchctl,
   readPathFromLoginShell,
-} from "./shell";
+  resolveCommandPath,
+  resolveKnownWindowsCliDirs,
+  resolveWindowsEnvironment,
+} from "./shell.ts";
 
 describe("extractPathFromShellOutput", () => {
   it("extracts the path between capture markers", () => {
@@ -60,6 +69,38 @@ describe("readPathFromLoginShell", () => {
   });
 });
 
+describe("readPathFromLaunchctl", () => {
+  it("returns a trimmed PATH value from launchctl", () => {
+    const execFile = vi.fn<
+      (
+        file: string,
+        args: ReadonlyArray<string>,
+        options: { encoding: "utf8"; timeout: number },
+      ) => string
+    >(() => "  /opt/homebrew/bin:/usr/bin  \n");
+
+    expect(readPathFromLaunchctl(execFile)).toBe("/opt/homebrew/bin:/usr/bin");
+    expect(execFile).toHaveBeenCalledWith("/bin/launchctl", ["getenv", "PATH"], {
+      encoding: "utf8",
+      timeout: 2000,
+    });
+  });
+
+  it("returns undefined when launchctl is unavailable", () => {
+    const execFile = vi.fn<
+      (
+        file: string,
+        args: ReadonlyArray<string>,
+        options: { encoding: "utf8"; timeout: number },
+      ) => string
+    >(() => {
+      throw new Error("spawn /bin/launchctl ENOENT");
+    });
+
+    expect(readPathFromLaunchctl(execFile)).toBeUndefined();
+  });
+});
+
 describe("readEnvironmentFromLoginShell", () => {
   it("extracts multiple environment variables from a login shell command", () => {
     const execFile = vi.fn<
@@ -126,3 +167,304 @@ describe("readEnvironmentFromLoginShell", () => {
     });
   });
 });
+
+describe("listLoginShellCandidates", () => {
+  it("returns env shell, user shell, then the platform fallback without duplicates", () => {
+    expect(listLoginShellCandidates("darwin", " /opt/homebrew/bin/nu ", "/bin/zsh")).toEqual([
+      "/opt/homebrew/bin/nu",
+      "/bin/zsh",
+    ]);
+  });
+
+  it("falls back to the platform default when no shells are available", () => {
+    expect(listLoginShellCandidates("linux", undefined, "")).toEqual(["/bin/bash"]);
+  });
+});
+
+describe("mergePathEntries", () => {
+  it("prefers login-shell PATH entries and keeps inherited extras", () => {
+    expect(
+      mergePathEntries("/opt/homebrew/bin:/usr/bin", "/Users/test/.local/bin:/usr/bin", "darwin"),
+    ).toBe("/opt/homebrew/bin:/usr/bin:/Users/test/.local/bin");
+  });
+
+  it("uses the platform-specific delimiter", () => {
+    expect(mergePathEntries("C:\\Tools;C:\\Windows", "C:\\Windows;C:\\Git", "win32")).toBe(
+      "C:\\Tools;C:\\Windows;C:\\Git",
+    );
+  });
+});
+
+describe("readEnvironmentFromWindowsShell", () => {
+  it("extracts environment variables from a PowerShell command", () => {
+    const execFile = vi.fn<
+      (
+        file: string,
+        args: ReadonlyArray<string>,
+        options: { encoding: "utf8"; timeout: number },
+      ) => string
+    >(
+      () =>
+        "__T3CODE_ENV_PATH_START__\nC:\\Users\\testuser\\AppData\\Roaming\\npm\n__T3CODE_ENV_PATH_END__\n",
+    );
+
+    expect(readEnvironmentFromWindowsShell(["PATH"], execFile)).toEqual({
+      PATH: "C:\\Users\\testuser\\AppData\\Roaming\\npm",
+    });
+    expect(execFile).toHaveBeenCalledWith(
+      "pwsh.exe",
+      expect.arrayContaining(["-NoLogo", "-NoProfile", "-NonInteractive", "-Command"]),
+      { encoding: "utf8", timeout: 5000 },
+    );
+  });
+
+  it("strips CRLF delimiters from captured PowerShell values", () => {
+    const execFile = vi.fn<
+      (
+        file: string,
+        args: ReadonlyArray<string>,
+        options: { encoding: "utf8"; timeout: number },
+      ) => string
+    >(
+      () =>
+        "__T3CODE_ENV_FNM_DIR_START__\r\nC:\\Users\\testuser\\AppData\\Roaming\\fnm\r\n__T3CODE_ENV_FNM_DIR_END__\r\n",
+    );
+
+    expect(readEnvironmentFromWindowsShell(["FNM_DIR"], execFile)).toEqual({
+      FNM_DIR: "C:\\Users\\testuser\\AppData\\Roaming\\fnm",
+    });
+  });
+
+  it("omits -NoProfile when loadProfile is enabled", () => {
+    const execFile = vi.fn<
+      (
+        file: string,
+        args: ReadonlyArray<string>,
+        options: { encoding: "utf8"; timeout: number },
+      ) => string
+    >(() => "__T3CODE_ENV_PATH_START__\nC:\\Tools\n__T3CODE_ENV_PATH_END__\n");
+
+    expect(readEnvironmentFromWindowsShell(["PATH"], { loadProfile: true }, execFile)).toEqual({
+      PATH: "C:\\Tools",
+    });
+    expect(execFile).toHaveBeenCalledWith(
+      "pwsh.exe",
+      expect.arrayContaining(["-NoLogo", "-NonInteractive", "-Command"]),
+      { encoding: "utf8", timeout: 5000 },
+    );
+    expect(execFile.mock.calls[0]?.[1]).not.toContain("-NoProfile");
+  });
+
+  it("falls back to Windows PowerShell when pwsh.exe is unavailable", () => {
+    const execFile = vi.fn<
+      (
+        file: string,
+        args: ReadonlyArray<string>,
+        options: { encoding: "utf8"; timeout: number },
+      ) => string
+    >((file) => {
+      if (file === "pwsh.exe") {
+        throw new Error("spawn pwsh.exe ENOENT");
+      }
+      return "__T3CODE_ENV_PATH_START__\nC:\\Tools\n__T3CODE_ENV_PATH_END__\n";
+    });
+
+    expect(readEnvironmentFromWindowsShell(["PATH"], execFile)).toEqual({
+      PATH: "C:\\Tools",
+    });
+    expect(execFile).toHaveBeenNthCalledWith(1, "pwsh.exe", expect.any(Array), {
+      encoding: "utf8",
+      timeout: 5000,
+    });
+    expect(execFile).toHaveBeenNthCalledWith(2, "powershell.exe", expect.any(Array), {
+      encoding: "utf8",
+      timeout: 5000,
+    });
+  });
+});
+
+describe("mergePathValues", () => {
+  it("dedupes case-insensitively on Windows while preserving preferred order", () => {
+    expect(
+      mergePathValues(
+        'C:\\Users\\testuser\\AppData\\Roaming\\npm;"C:\\Program Files\\nodejs"',
+        "c:\\users\\testuser\\appdata\\roaming\\npm;C:\\Windows\\System32",
+        "win32",
+      ),
+    ).toBe(
+      'C:\\Users\\testuser\\AppData\\Roaming\\npm;"C:\\Program Files\\nodejs";C:\\Windows\\System32',
+    );
+  });
+
+  it("dedupes case-sensitively on POSIX", () => {
+    expect(mergePathValues("/usr/local/bin:/usr/bin", "/usr/bin:/USR/BIN", "linux")).toBe(
+      "/usr/local/bin:/usr/bin:/USR/BIN",
+    );
+  });
+});
+
+describe("resolveKnownWindowsCliDirs", () => {
+  it("returns known Windows CLI install directories in priority order", () => {
+    expect(
+      resolveKnownWindowsCliDirs({
+        APPDATA: "C:\\Users\\testuser\\AppData\\Roaming",
+        LOCALAPPDATA: "C:\\Users\\testuser\\AppData\\Local",
+        USERPROFILE: "C:\\Users\\testuser",
+      }),
+    ).toEqual([
+      "C:\\Users\\testuser\\AppData\\Roaming\\npm",
+      "C:\\Users\\testuser\\AppData\\Local\\Programs\\nodejs",
+      "C:\\Users\\testuser\\AppData\\Local\\Volta\\bin",
+      "C:\\Users\\testuser\\AppData\\Local\\pnpm",
+      "C:\\Users\\testuser\\.bun\\bin",
+      "C:\\Users\\testuser\\scoop\\shims",
+    ]);
+  });
+});
+
+describe("isCommandAvailable", () => {
+  it("returns false when PATH is empty", () => {
+    expect(
+      isCommandAvailable("definitely-not-installed", {
+        platform: "win32",
+        env: { PATH: "", PATHEXT: ".COM;.EXE;.BAT;.CMD" },
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("resolveCommandPath", () => {
+  it("returns the first executable resolved from PATH", () => {
+    expect(
+      resolveCommandPath("definitely-not-installed", {
+        platform: "win32",
+        env: { PATH: "", PATHEXT: ".COM;.EXE;.BAT;.CMD" },
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("resolveWindowsEnvironment", () => {
+  it("returns the baseline no-profile PATH patch when node is already available", () => {
+    const readEnvironment = vi.fn(
+      (_names: ReadonlyArray<string>, options?: { loadProfile?: boolean }) =>
+        options?.loadProfile
+          ? { PATH: "C:\\Profile\\Bin" }
+          : { PATH: "C:\\Shell\\Bin;C:\\Windows\\System32" },
+    );
+    const commandAvailable = vi.fn(() => true);
+
+    expect(
+      resolveWindowsEnvironment(
+        {
+          PATH: "C:\\Windows\\System32",
+          APPDATA: "C:\\Users\\testuser\\AppData\\Roaming",
+          LOCALAPPDATA: "C:\\Users\\testuser\\AppData\\Local",
+          USERPROFILE: "C:\\Users\\testuser",
+        },
+        {
+          readEnvironment,
+          commandAvailable,
+        },
+      ),
+    ).toEqual({
+      PATH: [
+        "C:\\Users\\testuser\\AppData\\Roaming\\npm",
+        "C:\\Users\\testuser\\AppData\\Local\\Programs\\nodejs",
+        "C:\\Users\\testuser\\AppData\\Local\\Volta\\bin",
+        "C:\\Users\\testuser\\AppData\\Local\\pnpm",
+        "C:\\Users\\testuser\\.bun\\bin",
+        "C:\\Users\\testuser\\scoop\\shims",
+        "C:\\Shell\\Bin",
+        "C:\\Windows\\System32",
+      ].join(";"),
+    });
+    expect(readEnvironment).toHaveBeenCalledTimes(1);
+    expect(readEnvironment).toHaveBeenCalledWith(["PATH"], { loadProfile: false });
+    expect(commandAvailable).toHaveBeenCalledWith(
+      "node",
+      expect.objectContaining({
+        platform: "win32",
+      }),
+    );
+  });
+
+  it("loads the PowerShell profile when baseline env cannot resolve node", () => {
+    const readEnvironment = vi.fn(
+      (_names: ReadonlyArray<string>, options?: { loadProfile?: boolean }) =>
+        options?.loadProfile
+          ? {
+              PATH: "C:\\Profile\\Node;C:\\Windows\\System32",
+              FNM_DIR: "C:\\Users\\testuser\\AppData\\Roaming\\fnm",
+              FNM_MULTISHELL_PATH: "C:\\Users\\testuser\\AppData\\Local\\fnm_multishells\\123",
+            }
+          : { PATH: "C:\\Shell\\Bin;C:\\Windows\\System32" },
+    );
+    const commandAvailable = vi.fn(() => false);
+
+    expect(
+      resolveWindowsEnvironment(
+        {
+          PATH: "C:\\Windows\\System32",
+          APPDATA: "C:\\Users\\testuser\\AppData\\Roaming",
+          LOCALAPPDATA: "C:\\Users\\testuser\\AppData\\Local",
+          USERPROFILE: "C:\\Users\\testuser",
+        },
+        {
+          readEnvironment,
+          commandAvailable,
+        },
+      ),
+    ).toEqual({
+      PATH: [
+        "C:\\Profile\\Node",
+        "C:\\Windows\\System32",
+        "C:\\Users\\testuser\\AppData\\Roaming\\npm",
+        "C:\\Users\\testuser\\AppData\\Local\\Programs\\nodejs",
+        "C:\\Users\\testuser\\AppData\\Local\\Volta\\bin",
+        "C:\\Users\\testuser\\AppData\\Local\\pnpm",
+        "C:\\Users\\testuser\\.bun\\bin",
+        "C:\\Users\\testuser\\scoop\\shims",
+        "C:\\Shell\\Bin",
+      ].join(";"),
+      FNM_DIR: "C:\\Users\\testuser\\AppData\\Roaming\\fnm",
+      FNM_MULTISHELL_PATH: "C:\\Users\\testuser\\AppData\\Local\\fnm_multishells\\123",
+    });
+    expect(readEnvironment).toHaveBeenNthCalledWith(1, ["PATH"], { loadProfile: false });
+    expect(readEnvironment).toHaveBeenNthCalledWith(2, ["PATH", "FNM_DIR", "FNM_MULTISHELL_PATH"], {
+      loadProfile: true,
+    });
+    expect(commandAvailable).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the baseline env when profiled probe still does not resolve node", () => {
+    const readEnvironment = vi.fn(
+      (_names: ReadonlyArray<string>, options?: { loadProfile?: boolean }) =>
+        options?.loadProfile ? { FNM_DIR: "C:\\Users\\testuser\\AppData\\Roaming\\fnm" } : {},
+    );
+    const commandAvailable = vi.fn(() => false);
+
+    expect(
+      resolveWindowsEnvironment(
+        {
+          PATH: "C:\\Windows\\System32",
+          APPDATA: "C:\\Users\\testuser\\AppData\\Roaming",
+          USERPROFILE: "C:\\Users\\testuser",
+        },
+        {
+          readEnvironment,
+          commandAvailable,
+        },
+      ),
+    ).toEqual({
+      PATH: [
+        "C:\\Users\\testuser\\AppData\\Roaming\\npm",
+        "C:\\Users\\testuser\\.bun\\bin",
+        "C:\\Users\\testuser\\scoop\\shims",
+        "C:\\Windows\\System32",
+      ].join(";"),
+      FNM_DIR: "C:\\Users\\testuser\\AppData\\Roaming\\fnm",
+    });
+    expect(commandAvailable).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/shared/src/shell.ts b/packages/shared/src/shell.ts
index d9e8a7881b1..0572aaf989a 100644
--- a/packages/shared/src/shell.ts
+++ b/packages/shared/src/shell.ts
@@ -1,8 +1,15 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeOS from "node:os";
 import { execFileSync } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { extname, join } from "node:path";
 
 const PATH_CAPTURE_START = "__T3CODE_PATH_START__";
 const PATH_CAPTURE_END = "__T3CODE_PATH_END__";
 const SHELL_ENV_NAME_PATTERN = /^[A-Z0-9_]+$/;
+const WINDOWS_PATH_DELIMITER = ";";
+const POSIX_PATH_DELIMITER = ":";
+const WINDOWS_SHELL_CANDIDATES = ["pwsh.exe", "powershell.exe"] as const;
 
 type ExecFileSyncLike = (
   file: string,
@@ -10,24 +17,47 @@ type ExecFileSyncLike = (
   options: { encoding: "utf8"; timeout: number },
 ) => string;
 
-export function resolveLoginShell(
-  platform: NodeJS.Platform,
-  shell: string | undefined,
-): string | undefined {
-  const trimmedShell = shell?.trim();
-  if (trimmedShell) {
-    return trimmedShell;
-  }
+export interface CommandAvailabilityOptions {
+  readonly platform?: NodeJS.Platform;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface WindowsEnvironmentProbeOptions {
+  readonly loadProfile?: boolean;
+}
+
+function trimNonEmpty(value: string | null | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
 
-  if (platform === "darwin") {
-    return "/bin/zsh";
+function readUserLoginShell(): string | undefined {
+  try {
+    return trimNonEmpty(NodeOS.userInfo().shell);
+  } catch {
+    return undefined;
   }
+}
+
+export function listLoginShellCandidates(
+  platform: NodeJS.Platform,
+  shell: string | undefined,
+  userShell = readUserLoginShell(),
+): ReadonlyArray<string> {
+  const fallbackShell =
+    platform === "darwin" ? "/bin/zsh" : platform === "linux" ? "/bin/bash" : undefined;
+  const seen = new Set<string>();
+  const candidates: string[] = [];
 
-  if (platform === "linux") {
-    return "/bin/bash";
+  for (const candidate of [trimNonEmpty(shell), trimNonEmpty(userShell), fallbackShell]) {
+    if (!candidate || seen.has(candidate)) {
+      continue;
+    }
+    seen.add(candidate);
+    candidates.push(candidate);
   }
 
-  return undefined;
+  return candidates;
 }
 
 export function extractPathFromShellOutput(output: string): string | null {
@@ -49,6 +79,45 @@ export function readPathFromLoginShell(
   return readEnvironmentFromLoginShell(shell, ["PATH"], execFile).PATH;
 }
 
+export function readPathFromLaunchctl(
+  execFile: ExecFileSyncLike = execFileSync,
+): string | undefined {
+  try {
+    return trimNonEmpty(
+      execFile("/bin/launchctl", ["getenv", "PATH"], {
+        encoding: "utf8",
+        timeout: 2000,
+      }),
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+export function mergePathEntries(
+  preferredPath: string | undefined,
+  inheritedPath: string | undefined,
+  platform: NodeJS.Platform,
+): string | undefined {
+  const delimiter = platform === "win32" ? ";" : ":";
+  const merged: string[] = [];
+  const seen = new Set<string>();
+
+  for (const pathValue of [preferredPath, inheritedPath]) {
+    if (!pathValue) continue;
+    for (const entry of pathValue.split(delimiter)) {
+      const trimmedEntry = entry.trim();
+      if (!trimmedEntry || seen.has(trimmedEntry)) {
+        continue;
+      }
+      seen.add(trimmedEntry);
+      merged.push(trimmedEntry);
+    }
+  }
+
+  return merged.length > 0 ? merged.join(delimiter) : undefined;
+}
+
 function envCaptureStart(name: string): string {
   return `__T3CODE_ENV_${name}_START__`;
 }
@@ -73,6 +142,24 @@ function buildEnvironmentCaptureCommand(names: ReadonlyArray<string>): string {
     .join("; ");
 }
 
+function buildWindowsEnvironmentCaptureCommand(names: ReadonlyArray<string>): string {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    ...names.flatMap((name) => {
+      if (!SHELL_ENV_NAME_PATTERN.test(name)) {
+        throw new Error(`Unsupported environment variable name: ${name}`);
+      }
+
+      return [
+        `Write-Output '${envCaptureStart(name)}'`,
+        `$value = [Environment]::GetEnvironmentVariable('${name}')`,
+        "if ($null -ne $value -and $value.Length -gt 0) { Write-Output $value }",
+        `Write-Output '${envCaptureEnd(name)}'`,
+      ];
+    }),
+  ].join("; ");
+}
+
 function extractEnvironmentValue(output: string, name: string): string | undefined {
   const startMarker = envCaptureStart(name);
   const endMarker = envCaptureEnd(name);
@@ -83,13 +170,10 @@ function extractEnvironmentValue(output: string, name: string): string | undefin
   const endIndex = output.indexOf(endMarker, valueStartIndex);
   if (endIndex === -1) return undefined;
 
-  let value = output.slice(valueStartIndex, endIndex);
-  if (value.startsWith("\n")) {
-    value = value.slice(1);
-  }
-  if (value.endsWith("\n")) {
-    value = value.slice(0, -1);
-  }
+  const value = output
+    .slice(valueStartIndex, endIndex)
+    .replace(/^\r?\n/, "")
+    .replace(/\r?\n$/, "");
 
   return value.length > 0 ? value : undefined;
 }
@@ -124,3 +208,295 @@ export const readEnvironmentFromLoginShell: ShellEnvironmentReader = (
 
   return environment;
 };
+
+export type WindowsShellEnvironmentReader = (
+  names: ReadonlyArray<string>,
+  options?: WindowsEnvironmentProbeOptions,
+) => Partial<Record<string, string>>;
+
+export function readEnvironmentFromWindowsShell(
+  names: ReadonlyArray<string>,
+  execFile?: ExecFileSyncLike,
+): Partial<Record<string, string>>;
+export function readEnvironmentFromWindowsShell(
+  names: ReadonlyArray<string>,
+  options?: WindowsEnvironmentProbeOptions,
+  execFile?: ExecFileSyncLike,
+): Partial<Record<string, string>>;
+export function readEnvironmentFromWindowsShell(
+  names: ReadonlyArray<string>,
+  optionsOrExecFile?: WindowsEnvironmentProbeOptions | ExecFileSyncLike,
+  maybeExecFile?: ExecFileSyncLike,
+): Partial<Record<string, string>> {
+  if (names.length === 0) {
+    return {};
+  }
+
+  const options =
+    typeof optionsOrExecFile === "function"
+      ? ({} satisfies WindowsEnvironmentProbeOptions)
+      : (optionsOrExecFile ?? {});
+  const execFile: ExecFileSyncLike =
+    typeof optionsOrExecFile === "function"
+      ? optionsOrExecFile
+      : (maybeExecFile ?? (execFileSync as ExecFileSyncLike));
+  const command = buildWindowsEnvironmentCaptureCommand(names);
+  const args = [
+    "-NoLogo",
+    ...(options.loadProfile ? ([] as const) : (["-NoProfile"] as const)),
+    "-NonInteractive",
+    "-Command",
+    command,
+  ];
+  for (const shell of WINDOWS_SHELL_CANDIDATES) {
+    try {
+      const output = execFile(shell, args, { encoding: "utf8", timeout: 5000 });
+
+      const environment: Partial<Record<string, string>> = {};
+      for (const name of names) {
+        const value = extractEnvironmentValue(output, name);
+        if (value !== undefined) {
+          environment[name] = value;
+        }
+      }
+      return environment;
+    } catch {
+      continue;
+    }
+  }
+
+  return {};
+}
+
+function stripWrappingQuotes(value: string): string {
+  return value.replace(/^"+|"+$/g, "");
+}
+
+function pathDelimiterForPlatform(platform: NodeJS.Platform): string {
+  return platform === "win32" ? WINDOWS_PATH_DELIMITER : POSIX_PATH_DELIMITER;
+}
+
+function normalizePathEntryForComparison(entry: string, platform: NodeJS.Platform): string {
+  const normalized = stripWrappingQuotes(entry.trim());
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+export function mergePathValues(
+  preferredPath: string | undefined,
+  inheritedPath: string | undefined,
+  platform: NodeJS.Platform,
+): string | undefined {
+  const delimiter = pathDelimiterForPlatform(platform);
+  const merged: string[] = [];
+  const seen = new Set<string>();
+
+  for (const rawValue of [preferredPath, inheritedPath]) {
+    if (!rawValue) continue;
+
+    for (const entry of rawValue.split(delimiter)) {
+      const trimmed = entry.trim();
+      if (trimmed.length === 0) continue;
+
+      const normalized = normalizePathEntryForComparison(trimmed, platform);
+      if (normalized.length === 0 || seen.has(normalized)) continue;
+
+      seen.add(normalized);
+      merged.push(trimmed);
+    }
+  }
+
+  return merged.length > 0 ? merged.join(delimiter) : undefined;
+}
+
+function readEnvPath(env: NodeJS.ProcessEnv): string | undefined {
+  return env.PATH ?? env.Path ?? env.path;
+}
+
+function resolvePathEnvironmentVariable(env: NodeJS.ProcessEnv): string {
+  return readEnvPath(env) ?? "";
+}
+
+function resolveWindowsPathExtensions(env: NodeJS.ProcessEnv): ReadonlyArray<string> {
+  const rawValue = env.PATHEXT;
+  const fallback = [".COM", ".EXE", ".BAT", ".CMD"];
+  if (!rawValue) return fallback;
+
+  const parsed = rawValue
+    .split(";")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .map((entry) => (entry.startsWith(".") ? entry.toUpperCase() : `.${entry.toUpperCase()}`));
+  return parsed.length > 0 ? Array.from(new Set(parsed)) : fallback;
+}
+
+function resolveCommandCandidates(
+  command: string,
+  platform: NodeJS.Platform,
+  windowsPathExtensions: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+  if (platform !== "win32") return [command];
+  const extension = extname(command);
+  const normalizedExtension = extension.toUpperCase();
+
+  if (extension.length > 0 && windowsPathExtensions.includes(normalizedExtension)) {
+    const commandWithoutExtension = command.slice(0, -extension.length);
+    return Array.from(
+      new Set([
+        command,
+        `${commandWithoutExtension}${normalizedExtension}`,
+        `${commandWithoutExtension}${normalizedExtension.toLowerCase()}`,
+      ]),
+    );
+  }
+
+  const candidates: string[] = [];
+  for (const candidateExtension of windowsPathExtensions) {
+    candidates.push(`${command}${candidateExtension}`);
+    candidates.push(`${command}${candidateExtension.toLowerCase()}`);
+  }
+  return Array.from(new Set(candidates));
+}
+
+function isExecutableFile(
+  filePath: string,
+  platform: NodeJS.Platform,
+  windowsPathExtensions: ReadonlyArray<string>,
+): boolean {
+  try {
+    const stat = statSync(filePath);
+    if (!stat.isFile()) return false;
+    if (platform === "win32") {
+      const extension = extname(filePath);
+      if (extension.length === 0) return false;
+      return windowsPathExtensions.includes(extension.toUpperCase());
+    }
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveCommandPath(
+  command: string,
+  options: CommandAvailabilityOptions = {},
+): string | null {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const windowsPathExtensions = platform === "win32" ? resolveWindowsPathExtensions(env) : [];
+  const commandCandidates = resolveCommandCandidates(command, platform, windowsPathExtensions);
+
+  if (command.includes("/") || command.includes("\\")) {
+    for (const candidate of commandCandidates) {
+      if (isExecutableFile(candidate, platform, windowsPathExtensions)) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+
+  const pathValue = resolvePathEnvironmentVariable(env);
+  if (pathValue.length === 0) return null;
+  const pathEntries = pathValue
+    .split(pathDelimiterForPlatform(platform))
+    .map((entry) => stripWrappingQuotes(entry.trim()))
+    .filter((entry) => entry.length > 0);
+
+  for (const pathEntry of pathEntries) {
+    for (const candidate of commandCandidates) {
+      const candidatePath = join(pathEntry, candidate);
+      if (isExecutableFile(candidatePath, platform, windowsPathExtensions)) {
+        return candidatePath;
+      }
+    }
+  }
+  return null;
+}
+
+export function isCommandAvailable(
+  command: string,
+  options: CommandAvailabilityOptions = {},
+): boolean {
+  return resolveCommandPath(command, options) !== null;
+}
+
+export function resolveKnownWindowsCliDirs(env: NodeJS.ProcessEnv): ReadonlyArray<string> {
+  const appData = env.APPDATA?.trim();
+  const localAppData = env.LOCALAPPDATA?.trim();
+  const userProfile = env.USERPROFILE?.trim();
+
+  return [
+    ...(appData ? [`${appData}\\npm`] : []),
+    ...(localAppData ? [`${localAppData}\\Programs\\nodejs`, `${localAppData}\\Volta\\bin`] : []),
+    ...(localAppData ? [`${localAppData}\\pnpm`] : []),
+    ...(userProfile ? [`${userProfile}\\.bun\\bin`, `${userProfile}\\scoop\\shims`] : []),
+  ];
+}
+
+export interface WindowsEnvironmentResolverOptions {
+  readonly readEnvironment?: WindowsShellEnvironmentReader;
+  readonly commandAvailable?: typeof isCommandAvailable;
+}
+
+function readWindowsEnvironmentSafely(
+  readEnvironment: WindowsShellEnvironmentReader,
+  names: ReadonlyArray<string>,
+  options?: WindowsEnvironmentProbeOptions,
+): Partial<Record<string, string>> {
+  try {
+    return readEnvironment(names, options);
+  } catch {
+    return {};
+  }
+}
+
+function mergeWindowsEnv(
+  currentEnv: NodeJS.ProcessEnv,
+  patch: Partial<Record<string, string>>,
+): NodeJS.ProcessEnv {
+  const nextEnv: NodeJS.ProcessEnv = { ...currentEnv };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== undefined) {
+      nextEnv[key] = value;
+    }
+  }
+  return nextEnv;
+}
+
+export function resolveWindowsEnvironment(
+  env: NodeJS.ProcessEnv,
+  options: WindowsEnvironmentResolverOptions = {},
+): Partial<NodeJS.ProcessEnv> {
+  const readEnvironment = options.readEnvironment ?? readEnvironmentFromWindowsShell;
+  const commandAvailable = options.commandAvailable ?? isCommandAvailable;
+  const inheritedPath = readEnvPath(env);
+  const shellPath = readWindowsEnvironmentSafely(readEnvironment, ["PATH"], {
+    loadProfile: false,
+  }).PATH;
+  const mergedPath = mergePathValues(shellPath, inheritedPath, "win32");
+  const knownCliPath = resolveKnownWindowsCliDirs(env).join(WINDOWS_PATH_DELIMITER);
+  const baselinePath = mergePathValues(knownCliPath, mergedPath, "win32");
+  const baselinePatch: Partial<NodeJS.ProcessEnv> = baselinePath ? { PATH: baselinePath } : {};
+  const baselineEnv = mergeWindowsEnv(env, baselinePatch);
+
+  if (commandAvailable("node", { platform: "win32", env: baselineEnv })) {
+    return baselinePatch;
+  }
+
+  const profiledEnvironment = readWindowsEnvironmentSafely(
+    readEnvironment,
+    ["PATH", "FNM_DIR", "FNM_MULTISHELL_PATH"],
+    { loadProfile: true },
+  );
+  const profiledPath = mergePathValues(profiledEnvironment.PATH, baselinePath, "win32");
+  const profiledPatch: Partial<NodeJS.ProcessEnv> = {
+    ...(profiledPath ? { PATH: profiledPath } : {}),
+    ...(profiledEnvironment.FNM_DIR ? { FNM_DIR: profiledEnvironment.FNM_DIR } : {}),
+    ...(profiledEnvironment.FNM_MULTISHELL_PATH
+      ? { FNM_MULTISHELL_PATH: profiledEnvironment.FNM_MULTISHELL_PATH }
+      : {}),
+  };
+  return Object.keys(profiledPatch).length > 0
+    ? { ...baselinePatch, ...profiledPatch }
+    : baselinePatch;
+}
diff --git a/packages/shared/src/sourceControl.test.ts b/packages/shared/src/sourceControl.test.ts
new file mode 100644
index 00000000000..697e65f0914
--- /dev/null
+++ b/packages/shared/src/sourceControl.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  detectSourceControlProviderFromRemoteUrl,
+  getChangeRequestTerminologyForKind,
+  resolveChangeRequestPresentation,
+} from "./sourceControl.ts";
+
+describe("source control presentation", () => {
+  it("uses merge request terminology for GitLab", () => {
+    expect(getChangeRequestTerminologyForKind("gitlab")).toEqual({
+      shortLabel: "MR",
+      singular: "merge request",
+    });
+  });
+
+  it("uses pull request terminology for GitHub-compatible providers", () => {
+    expect(getChangeRequestTerminologyForKind("github")).toEqual({
+      shortLabel: "PR",
+      singular: "pull request",
+    });
+    expect(getChangeRequestTerminologyForKind("azure-devops")).toEqual({
+      shortLabel: "PR",
+      singular: "pull request",
+    });
+    expect(getChangeRequestTerminologyForKind("bitbucket")).toEqual({
+      shortLabel: "PR",
+      singular: "pull request",
+    });
+  });
+
+  it("falls back to generic change request copy for unknown providers", () => {
+    expect(
+      resolveChangeRequestPresentation({ kind: "unknown", name: "forge", baseUrl: "" }),
+    ).toEqual(
+      expect.objectContaining({
+        shortName: "change request",
+        longName: "change request",
+      }),
+    );
+  });
+});
+
+describe("detectSourceControlProviderFromRemoteUrl", () => {
+  it("detects common source control hosts", () => {
+    expect(detectSourceControlProviderFromRemoteUrl("git@github.com:owner/repo.git")?.kind).toBe(
+      "github",
+    );
+    expect(
+      detectSourceControlProviderFromRemoteUrl("https://gitlab.com/group/repo.git")?.kind,
+    ).toBe("gitlab");
+    expect(
+      detectSourceControlProviderFromRemoteUrl("https://dev.azure.com/org/project/_git/repo")?.kind,
+    ).toBe("azure-devops");
+    expect(
+      detectSourceControlProviderFromRemoteUrl("git@bitbucket.org:workspace/repo.git")?.kind,
+    ).toBe("bitbucket");
+  });
+});
diff --git a/packages/shared/src/sourceControl.ts b/packages/shared/src/sourceControl.ts
new file mode 100644
index 00000000000..24ff3a0da83
--- /dev/null
+++ b/packages/shared/src/sourceControl.ts
@@ -0,0 +1,223 @@
+import type { SourceControlProviderInfo, SourceControlProviderKind } from "@t3tools/contracts";
+
+export interface ChangeRequestPresentation {
+  readonly icon: "github" | "gitlab" | "azure-devops" | "bitbucket" | "change-request";
+  readonly providerName: string;
+  readonly shortName: string;
+  readonly longName: string;
+  readonly pluralLongName: string;
+  readonly providerLongName: string;
+  readonly checkoutCommandExample?: string;
+  readonly urlExample: string;
+}
+
+export interface ChangeRequestTerminology {
+  readonly shortLabel: string;
+  readonly singular: string;
+}
+
+export const DEFAULT_CHANGE_REQUEST_TERMINOLOGY: ChangeRequestTerminology = {
+  shortLabel: "PR",
+  singular: "pull request",
+};
+
+const GITHUB_CHANGE_REQUEST_PRESENTATION: ChangeRequestPresentation = {
+  icon: "github",
+  providerName: "GitHub",
+  shortName: "PR",
+  longName: "pull request",
+  pluralLongName: "pull requests",
+  providerLongName: "GitHub pull request",
+  checkoutCommandExample: "gh pr checkout 123",
+  urlExample: "https://github.com/owner/repo/pull/42",
+};
+
+const GITLAB_CHANGE_REQUEST_PRESENTATION: ChangeRequestPresentation = {
+  icon: "gitlab",
+  providerName: "GitLab",
+  shortName: "MR",
+  longName: "merge request",
+  pluralLongName: "merge requests",
+  providerLongName: "GitLab merge request",
+  checkoutCommandExample: "glab mr checkout 123",
+  urlExample: "https://gitlab.com/group/project/-/merge_requests/42",
+};
+
+const AZURE_DEVOPS_CHANGE_REQUEST_PRESENTATION: ChangeRequestPresentation = {
+  icon: "azure-devops",
+  providerName: "Azure DevOps",
+  shortName: "PR",
+  longName: "pull request",
+  pluralLongName: "pull requests",
+  providerLongName: "Azure DevOps pull request",
+  checkoutCommandExample: "az repos pr checkout --id 123",
+  urlExample: "https://dev.azure.com/org/project/_git/repo/pullrequest/42",
+};
+
+const BITBUCKET_CHANGE_REQUEST_PRESENTATION: ChangeRequestPresentation = {
+  icon: "bitbucket",
+  providerName: "Bitbucket",
+  shortName: "PR",
+  longName: "pull request",
+  pluralLongName: "pull requests",
+  providerLongName: "Bitbucket pull request",
+  urlExample: "https://bitbucket.org/workspace/repo/pull-requests/42",
+};
+
+const GENERIC_CHANGE_REQUEST_PRESENTATION: ChangeRequestPresentation = {
+  icon: "change-request",
+  providerName: "source control",
+  shortName: "change request",
+  longName: "change request",
+  pluralLongName: "change requests",
+  providerLongName: "change request",
+  urlExample: "#42",
+};
+
+export function resolveChangeRequestPresentation(
+  provider: SourceControlProviderInfo | null | undefined,
+): ChangeRequestPresentation {
+  switch (provider?.kind) {
+    case "github":
+    case undefined:
+      return GITHUB_CHANGE_REQUEST_PRESENTATION;
+    case "gitlab":
+      return GITLAB_CHANGE_REQUEST_PRESENTATION;
+    case "azure-devops":
+      return AZURE_DEVOPS_CHANGE_REQUEST_PRESENTATION;
+    case "bitbucket":
+      return BITBUCKET_CHANGE_REQUEST_PRESENTATION;
+    case "unknown":
+      return GENERIC_CHANGE_REQUEST_PRESENTATION;
+  }
+}
+
+export function resolveChangeRequestPresentationForKind(
+  kind: SourceControlProviderKind,
+): ChangeRequestPresentation {
+  return resolveChangeRequestPresentation({ kind, name: "", baseUrl: "" });
+}
+
+export function formatChangeRequestAction(
+  verb: "View" | "Create",
+  presentation: ChangeRequestPresentation,
+): string {
+  return `${verb} ${presentation.shortName}`;
+}
+
+export function formatCreateChangeRequestPhrase(presentation: ChangeRequestPresentation): string {
+  return `create ${presentation.shortName}`;
+}
+
+export function getChangeRequestTerminology(
+  provider: SourceControlProviderInfo | null | undefined,
+): ChangeRequestTerminology {
+  if (!provider) {
+    return DEFAULT_CHANGE_REQUEST_TERMINOLOGY;
+  }
+
+  const presentation = resolveChangeRequestPresentation(provider);
+  return {
+    shortLabel: presentation.shortName,
+    singular: presentation.longName,
+  };
+}
+
+export function getChangeRequestTerminologyForKind(
+  kind: SourceControlProviderKind,
+): ChangeRequestTerminology {
+  const presentation = resolveChangeRequestPresentationForKind(kind);
+  return {
+    shortLabel: presentation.shortName,
+    singular: presentation.longName,
+  };
+}
+
+function parseRemoteHost(remoteUrl: string): string | null {
+  const trimmed = remoteUrl.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+
+  if (trimmed.startsWith("git@")) {
+    const hostWithPath = trimmed.slice("git@".length);
+    const separatorIndex = hostWithPath.search(/[:/]/);
+    if (separatorIndex <= 0) {
+      return null;
+    }
+    return hostWithPath.slice(0, separatorIndex).toLowerCase();
+  }
+
+  try {
+    return new URL(trimmed).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function toBaseUrl(host: string): string {
+  return `https://${host}`;
+}
+
+function isGitHubHost(host: string): boolean {
+  return host === "github.com" || host.includes("github");
+}
+
+function isGitLabHost(host: string): boolean {
+  return host === "gitlab.com" || host.includes("gitlab");
+}
+
+function isAzureDevOpsHost(host: string): boolean {
+  return host === "dev.azure.com" || host.endsWith(".visualstudio.com");
+}
+
+function isBitbucketHost(host: string): boolean {
+  return host === "bitbucket.org" || host.includes("bitbucket");
+}
+
+export function detectSourceControlProviderFromRemoteUrl(
+  remoteUrl: string,
+): SourceControlProviderInfo | null {
+  const host = parseRemoteHost(remoteUrl);
+  if (!host) {
+    return null;
+  }
+
+  if (isGitHubHost(host)) {
+    return {
+      kind: "github",
+      name: host === "github.com" ? "GitHub" : "GitHub Self-Hosted",
+      baseUrl: toBaseUrl(host),
+    };
+  }
+
+  if (isGitLabHost(host)) {
+    return {
+      kind: "gitlab",
+      name: host === "gitlab.com" ? "GitLab" : "GitLab Self-Hosted",
+      baseUrl: toBaseUrl(host),
+    };
+  }
+
+  if (isAzureDevOpsHost(host)) {
+    return {
+      kind: "azure-devops",
+      name: "Azure DevOps",
+      baseUrl: toBaseUrl(host),
+    };
+  }
+
+  if (isBitbucketHost(host)) {
+    return {
+      kind: "bitbucket",
+      name: host === "bitbucket.org" ? "Bitbucket" : "Bitbucket Self-Hosted",
+      baseUrl: toBaseUrl(host),
+    };
+  }
+
+  return {
+    kind: "unknown",
+    name: host,
+    baseUrl: toBaseUrl(host),
+  };
+}
diff --git a/packages/shared/src/toolActivity.test.ts b/packages/shared/src/toolActivity.test.ts
new file mode 100644
index 00000000000..e31ea4e342c
--- /dev/null
+++ b/packages/shared/src/toolActivity.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+
+import { deriveToolActivityPresentation } from "./toolActivity.ts";
+
+describe("toolActivity", () => {
+  it("normalizes command tools to a stable ran-command label", () => {
+    expect(
+      deriveToolActivityPresentation({
+        itemType: "command_execution",
+        title: "Terminal",
+        detail: "Terminal",
+        data: {
+          command: "bun run lint",
+        },
+        fallbackSummary: "Terminal",
+      }),
+    ).toEqual({
+      summary: "Ran command",
+      detail: "bun run lint",
+    });
+  });
+
+  it("uses structured file paths for read-file tools when available", () => {
+    expect(
+      deriveToolActivityPresentation({
+        itemType: "dynamic_tool_call",
+        title: "Read File",
+        detail: "Read File",
+        data: {
+          kind: "read",
+          locations: [{ path: "/tmp/app.ts" }],
+        },
+        fallbackSummary: "Read File",
+      }),
+    ).toEqual({
+      summary: "Read file",
+      detail: "/tmp/app.ts",
+    });
+  });
+
+  it("drops duplicated generic read-file detail when no path is available", () => {
+    expect(
+      deriveToolActivityPresentation({
+        itemType: "dynamic_tool_call",
+        title: "Read File",
+        detail: "Read File",
+        data: {
+          kind: "read",
+          rawInput: {},
+        },
+        fallbackSummary: "Read File",
+      }),
+    ).toEqual({
+      summary: "Read file",
+    });
+  });
+});
diff --git a/packages/shared/src/toolActivity.ts b/packages/shared/src/toolActivity.ts
new file mode 100644
index 00000000000..5e2f18044f5
--- /dev/null
+++ b/packages/shared/src/toolActivity.ts
@@ -0,0 +1,257 @@
+import type { ToolLifecycleItemType } from "@t3tools/contracts";
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function asTrimmedString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeCommandValue(value: unknown): string | undefined {
+  const direct = asTrimmedString(value);
+  if (direct) {
+    return direct;
+  }
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const parts = value
+    .map((entry) => asTrimmedString(entry))
+    .filter((entry): entry is string => entry !== undefined);
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
+function stripTrailingExitCode(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const match = /^(?<output>[\s\S]*?)(?:\s*<exited with exit code \d+>)\s*$/iu.exec(trimmed);
+  const output = match?.groups?.output?.trim() ?? trimmed;
+  return output.length > 0 ? output : undefined;
+}
+
+function extractCommandFromTitle(title: string | undefined): string | undefined {
+  if (!title) {
+    return undefined;
+  }
+  const backtickMatch = /`([^`]+)`/u.exec(title);
+  return backtickMatch?.[1]?.trim() || undefined;
+}
+
+function extractToolCommand(data: Record<string, unknown> | undefined, title: string | undefined) {
+  const item = asRecord(data?.item);
+  const itemInput = asRecord(item?.input);
+  const itemResult = asRecord(item?.result);
+  const rawInput = asRecord(data?.rawInput);
+  const candidates = [
+    normalizeCommandValue(item?.command),
+    normalizeCommandValue(itemInput?.command),
+    normalizeCommandValue(itemResult?.command),
+    normalizeCommandValue(data?.command),
+    normalizeCommandValue(rawInput?.command),
+  ];
+  const direct = candidates.find((candidate) => candidate !== undefined);
+  if (direct) {
+    return direct;
+  }
+  const executable = asTrimmedString(rawInput?.executable);
+  const args = normalizeCommandValue(rawInput?.args);
+  if (executable && args) {
+    return `${executable} ${args}`;
+  }
+  if (executable) {
+    return executable;
+  }
+  return extractCommandFromTitle(title);
+}
+
+function maybePathLike(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (
+    value.includes("/") ||
+    value.includes("\\") ||
+    value.startsWith(".") ||
+    /\.(?:[a-z0-9]{1,12})$/iu.test(value)
+  ) {
+    return value;
+  }
+  return undefined;
+}
+
+function collectPaths(value: unknown, paths: string[], seen: Set<string>, depth: number): void {
+  if (depth > 4 || paths.length >= 8) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectPaths(entry, paths, seen, depth + 1);
+      if (paths.length >= 8) {
+        return;
+      }
+    }
+    return;
+  }
+  const record = asRecord(value);
+  if (!record) {
+    return;
+  }
+  for (const key of ["path", "filePath", "relativePath", "filename", "newPath", "oldPath"]) {
+    const candidate = maybePathLike(asTrimmedString(record[key]));
+    if (!candidate || seen.has(candidate)) {
+      continue;
+    }
+    seen.add(candidate);
+    paths.push(candidate);
+    if (paths.length >= 8) {
+      return;
+    }
+  }
+  for (const nestedKey of ["locations", "item", "input", "result", "rawInput", "data", "changes"]) {
+    if (!(nestedKey in record)) {
+      continue;
+    }
+    collectPaths(record[nestedKey], paths, seen, depth + 1);
+    if (paths.length >= 8) {
+      return;
+    }
+  }
+}
+
+function extractPrimaryPath(data: Record<string, unknown> | undefined): string | undefined {
+  const paths: string[] = [];
+  collectPaths(data, paths, new Set<string>(), 0);
+  return paths[0];
+}
+
+function normalizeEquivalentValue(value: string | undefined): string | undefined {
+  const trimmed = asTrimmedString(value);
+  if (!trimmed) {
+    return undefined;
+  }
+  return trimmed
+    .replace(/\s+/gu, " ")
+    .replace(/\s+(?:complete|completed|started)\s*$/iu, "")
+    .trim();
+}
+
+function isEquivalent(left: string | undefined, right: string | undefined): boolean {
+  const normalizedLeft = normalizeEquivalentValue(left)?.toLowerCase();
+  const normalizedRight = normalizeEquivalentValue(right)?.toLowerCase();
+  return normalizedLeft !== undefined && normalizedLeft === normalizedRight;
+}
+
+function classifyToolAction(input: {
+  readonly itemType?: ToolLifecycleItemType | null | undefined;
+  readonly title?: string | undefined;
+  readonly data?: Record<string, unknown> | undefined;
+}): "command" | "read" | "file_change" | "search" | "other" {
+  const itemType = input.itemType ?? undefined;
+  const kind = asTrimmedString(input.data?.kind)?.toLowerCase();
+  const title = asTrimmedString(input.title)?.toLowerCase();
+  if (itemType === "command_execution" || kind === "execute" || title === "terminal") {
+    return "command";
+  }
+  if (kind === "read" || title === "read file") {
+    return "read";
+  }
+  if (
+    itemType === "file_change" ||
+    kind === "edit" ||
+    kind === "move" ||
+    kind === "delete" ||
+    kind === "write"
+  ) {
+    return "file_change";
+  }
+  if (itemType === "web_search" || kind === "search" || title === "find" || title === "grep") {
+    return "search";
+  }
+  return "other";
+}
+
+export interface ToolActivityPresentationInput {
+  readonly itemType?: ToolLifecycleItemType | null | undefined;
+  readonly title?: string | null | undefined;
+  readonly detail?: string | null | undefined;
+  readonly data?: unknown;
+  readonly fallbackSummary?: string | null | undefined;
+}
+
+export interface ToolActivityPresentation {
+  readonly summary: string;
+  readonly detail?: string | undefined;
+}
+
+export function deriveToolActivityPresentation(
+  input: ToolActivityPresentationInput,
+): ToolActivityPresentation {
+  const title = asTrimmedString(input.title);
+  const detail = stripTrailingExitCode(asTrimmedString(input.detail));
+  const fallbackSummary = asTrimmedString(input.fallbackSummary) ?? "Tool";
+  const data = asRecord(input.data);
+  const command = extractToolCommand(data, title);
+  const primaryPath = extractPrimaryPath(data);
+  const action = classifyToolAction({
+    itemType: input.itemType,
+    title,
+    data,
+  });
+
+  if (action === "command") {
+    return {
+      summary: "Ran command",
+      ...(command ? { detail: command } : {}),
+    };
+  }
+
+  if (action === "read") {
+    if (primaryPath) {
+      return {
+        summary: "Read file",
+        detail: primaryPath,
+      };
+    }
+    return {
+      summary: "Read file",
+    };
+  }
+
+  if (action === "file_change") {
+    return {
+      summary: "Changed files",
+      ...(primaryPath ? { detail: primaryPath } : {}),
+    };
+  }
+
+  if (action === "search") {
+    const query =
+      asTrimmedString(asRecord(data?.rawInput)?.query) ??
+      asTrimmedString(asRecord(data?.rawInput)?.pattern) ??
+      asTrimmedString(asRecord(data?.rawInput)?.searchTerm);
+    return {
+      summary: "Searched files",
+      ...(query ? { detail: query } : {}),
+    };
+  }
+
+  if (detail && !isEquivalent(detail, title) && !isEquivalent(detail, fallbackSummary)) {
+    return {
+      summary: title ?? fallbackSummary,
+      detail,
+    };
+  }
+
+  return {
+    summary: title ?? fallbackSummary,
+  };
+}
diff --git a/packages/shared/tsconfig.json b/packages/shared/tsconfig.json
index 564a5990051..73a306f847a 100644
--- a/packages/shared/tsconfig.json
+++ b/packages/shared/tsconfig.json
@@ -1,4 +1,5 @@
 {
   "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
   "include": ["src"]
 }
diff --git a/packages/ssh/package.json b/packages/ssh/package.json
new file mode 100644
index 00000000000..a3df6fea2b4
--- /dev/null
+++ b/packages/ssh/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@t3tools/ssh",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./auth": {
+      "types": "./src/auth.ts",
+      "import": "./src/auth.ts"
+    },
+    "./command": {
+      "types": "./src/command.ts",
+      "import": "./src/command.ts"
+    },
+    "./config": {
+      "types": "./src/config.ts",
+      "import": "./src/config.ts"
+    },
+    "./errors": {
+      "types": "./src/errors.ts",
+      "import": "./src/errors.ts"
+    },
+    "./tunnel": {
+      "types": "./src/tunnel.ts",
+      "import": "./src/tunnel.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@t3tools/contracts": "workspace:*",
+    "@t3tools/shared": "workspace:*",
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@effect/platform-node": "catalog:",
+    "@effect/vitest": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/packages/ssh/src/auth.test.ts b/packages/ssh/src/auth.test.ts
new file mode 100644
index 00000000000..e59707207a2
--- /dev/null
+++ b/packages/ssh/src/auth.test.ts
@@ -0,0 +1,68 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+
+import {
+  buildSshAskpassHelperDescriptor,
+  buildSshChildEnvironment,
+  isSshAuthFailure,
+} from "./auth.ts";
+
+describe("ssh auth", () => {
+  it.effect("detects ssh auth failures from common permission denied messages", () =>
+    Effect.sync(() => {
+      assert.equal(
+        isSshAuthFailure(
+          new Error(
+            "julius@100.65.180.100: Permission denied (publickey,password,keyboard-interactive).",
+          ),
+        ),
+        true,
+      );
+      assert.equal(isSshAuthFailure(new Error("Permission denied (publickey).")), true);
+      assert.equal(isSshAuthFailure(new Error("Connection timed out")), false);
+      assert.equal(isSshAuthFailure(new Error("mkdir: Permission denied")), false);
+    }),
+  );
+
+  it.effect("creates askpass env for cached password prompts", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-ssh-askpass-test-" });
+      const env = yield* buildSshChildEnvironment({
+        authSecret: "super-secret",
+        interactiveAuth: true,
+        askpassDirectory: directory,
+        platform: "linux",
+        baseEnv: {},
+      });
+
+      const askpassPath = path.join(directory, "ssh-askpass.sh");
+      assert.equal(env.SSH_ASKPASS, askpassPath);
+      assert.equal(env.SSH_ASKPASS_REQUIRE, "force");
+      assert.equal(env.T3_SSH_AUTH_SECRET, "super-secret");
+      assert.equal(env.DISPLAY, "t3code");
+      assert.equal(yield* fs.exists(askpassPath), true);
+      assert.include(yield* fs.readFileString(askpassPath), 'printf "%s\\n" "$T3_SSH_AUTH_SECRET"');
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+
+  it.effect("builds a windows askpass launcher pair", () =>
+    Effect.gen(function* () {
+      const descriptor = yield* buildSshAskpassHelperDescriptor({
+        directory: "C:\\temp\\t3code-ssh-askpass",
+        platform: "win32",
+      }).pipe(Effect.provide(NodeServices.layer));
+
+      assert.equal(descriptor.launcherPath, "C:\\temp\\t3code-ssh-askpass\\ssh-askpass.cmd");
+      assert.deepEqual(
+        descriptor.files.map((file) => file.path.split("\\").at(-1)),
+        ["ssh-askpass.cmd", "ssh-askpass.ps1"],
+      );
+    }),
+  );
+});
diff --git a/packages/ssh/src/auth.ts b/packages/ssh/src/auth.ts
new file mode 100644
index 00000000000..13ddee9ca2d
--- /dev/null
+++ b/packages/ssh/src/auth.ts
@@ -0,0 +1,210 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+
+import { SshPasswordPromptError } from "./errors.ts";
+
+export interface SshPasswordRequest {
+  readonly destination: string;
+  readonly username: string | null;
+  readonly prompt: string;
+  readonly attempt: number;
+}
+
+export interface SshAskpassFile {
+  readonly path: string;
+  readonly contents: string;
+  readonly mode?: number;
+}
+
+export interface SshAskpassHelperDescriptor {
+  readonly launcherPath: string;
+  readonly files: ReadonlyArray<SshAskpassFile>;
+}
+
+export interface SshAuthOptions {
+  readonly authSecret?: string | null;
+  readonly batchMode?: "yes" | "no";
+  readonly interactiveAuth?: boolean;
+}
+
+export interface SshPasswordPromptShape {
+  readonly isAvailable: boolean;
+  readonly request: (
+    request: SshPasswordRequest,
+  ) => Effect.Effect<string | null, SshPasswordPromptError>;
+}
+
+export class SshPasswordPrompt extends Context.Service<SshPasswordPrompt, SshPasswordPromptShape>()(
+  "@t3tools/ssh/SshPasswordPrompt",
+) {
+  static readonly disabledLayer = Layer.succeed(
+    SshPasswordPrompt,
+    SshPasswordPrompt.of({
+      isAvailable: false,
+      request: () => Effect.succeed(null),
+    }),
+  );
+}
+
+export interface SshChildEnvironmentOptions {
+  readonly interactiveAuth?: boolean;
+  readonly baseEnv?: NodeJS.ProcessEnv;
+  readonly askpassDirectory?: string;
+  readonly authSecret?: string | null;
+  readonly platform?: NodeJS.Platform;
+}
+
+const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
+
+function joinSshAskpassPath(
+  directory: string,
+  fileName: string,
+  platform: NodeJS.Platform,
+): string {
+  const trimmed = directory.replace(/[\\/]+$/u, "");
+  return platform === "win32" ? `${trimmed}\\${fileName}` : `${trimmed}/${fileName}`;
+}
+
+export const ASKPASS_POSIX_SCRIPT = `#!/bin/sh
+# Invoked by ssh via SSH_ASKPASS when T3 Code re-runs ssh with a cached password
+# from the renderer's in-app prompt. We never expose a native dialog here - if
+# T3_SSH_AUTH_SECRET is missing, that's a caller bug and we fail loudly.
+if [ "\${T3_SSH_AUTH_SECRET+x}" = "x" ]; then
+  printf "%s\\n" "$T3_SSH_AUTH_SECRET"
+  exit 0
+fi
+printf 'T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.\\n' >&2
+exit 1
+`;
+
+export const ASKPASS_WINDOWS_LAUNCHER_SCRIPT = `@echo off\r
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0ssh-askpass.ps1" %*\r
+`;
+
+export const ASKPASS_WINDOWS_SCRIPT = `# Invoked by ssh via SSH_ASKPASS (through ssh-askpass.cmd) when T3 Code re-runs\r
+# ssh with a cached password from the renderer's in-app prompt. We never expose\r
+# a native dialog here - if T3_SSH_AUTH_SECRET is missing, that's a caller bug\r
+# and we fail loudly.\r
+if ($null -ne $env:T3_SSH_AUTH_SECRET) {\r
+  [Console]::Out.WriteLine($env:T3_SSH_AUTH_SECRET)\r
+  exit 0\r
+}\r
+[Console]::Error.WriteLine("T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.")\r
+exit 1\r
+`;
+
+export const getDefaultSshAskpassDirectory = Effect.fn("ssh/auth.getDefaultSshAskpassDirectory")(
+  function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const parentDirectory = yield* fs.makeTempDirectory({ prefix: "t3code-ssh-runtime-" });
+    return path.join(parentDirectory, SSH_ASKPASS_DIR_NAME);
+  },
+);
+
+export const buildSshAskpassHelperDescriptor = Effect.fn(
+  "ssh/auth.buildSshAskpassHelperDescriptor",
+)(function* (input: {
+  readonly directory: string;
+  readonly platform?: NodeJS.Platform;
+}): Effect.fn.Return<SshAskpassHelperDescriptor, never, Path.Path> {
+  const platform = input.platform ?? process.platform;
+  const path = yield* Path.Path;
+  const directory = input.directory;
+
+  if (platform === "win32") {
+    const powershellPath = joinSshAskpassPath(directory, "ssh-askpass.ps1", platform);
+    return {
+      launcherPath: joinSshAskpassPath(directory, "ssh-askpass.cmd", platform),
+      files: [
+        {
+          path: joinSshAskpassPath(directory, "ssh-askpass.cmd", platform),
+          contents: ASKPASS_WINDOWS_LAUNCHER_SCRIPT,
+        },
+        {
+          path: powershellPath,
+          contents: ASKPASS_WINDOWS_SCRIPT,
+        },
+      ],
+    };
+  }
+
+  return {
+    launcherPath: path.join(directory, "ssh-askpass.sh"),
+    files: [
+      {
+        path: path.join(directory, "ssh-askpass.sh"),
+        contents: ASKPASS_POSIX_SCRIPT,
+        mode: 0o700,
+      },
+    ],
+  };
+});
+
+export const ensureSshAskpassHelpers = Effect.fn("ssh/auth.ensureSshAskpassHelpers")(
+  function* (input: {
+    readonly directory: string;
+    readonly platform?: NodeJS.Platform;
+  }): Effect.fn.Return<string, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path> {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const descriptor = yield* buildSshAskpassHelperDescriptor(input);
+    const platform = input.platform ?? process.platform;
+
+    yield* fs.makeDirectory(path.dirname(descriptor.launcherPath), { recursive: true });
+
+    for (const file of descriptor.files) {
+      const existing = yield* fs.exists(file.path);
+      const current = existing ? yield* fs.readFileString(file.path) : null;
+      if (current !== file.contents) {
+        yield* fs.writeFileString(file.path, file.contents);
+      }
+      if (file.mode !== undefined && platform !== "win32") {
+        yield* fs.chmod(file.path, file.mode);
+      }
+    }
+
+    return descriptor.launcherPath;
+  },
+);
+
+export const buildSshChildEnvironment = Effect.fn("ssh/auth.buildSshChildEnvironment")(function* (
+  input: SshChildEnvironmentOptions = {},
+): Effect.fn.Return<
+  NodeJS.ProcessEnv,
+  PlatformError.PlatformError,
+  FileSystem.FileSystem | Path.Path
+> {
+  const baseEnv = { ...(input.baseEnv ?? process.env) };
+  if (!input.interactiveAuth) {
+    return baseEnv;
+  }
+
+  const platform = input.platform ?? process.platform;
+  const directory = input.askpassDirectory ?? (yield* getDefaultSshAskpassDirectory());
+  const sshAskpass = yield* ensureSshAskpassHelpers({ directory, platform });
+
+  return {
+    ...baseEnv,
+    SSH_ASKPASS: sshAskpass,
+    SSH_ASKPASS_REQUIRE: "force",
+    ...(input.authSecret === undefined ? {} : { T3_SSH_AUTH_SECRET: input.authSecret ?? "" }),
+    ...(platform === "win32" || baseEnv.DISPLAY ? {} : { DISPLAY: "t3code" }),
+  };
+});
+
+export function isSshAuthFailure(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  return (
+    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]*\)/u.test(
+      normalized,
+    ) ||
+    /authentication failed/u.test(normalized) ||
+    /too many authentication failures/u.test(normalized)
+  );
+}
diff --git a/packages/ssh/src/command.test.ts b/packages/ssh/src/command.test.ts
new file mode 100644
index 00000000000..d95ffed49dc
--- /dev/null
+++ b/packages/ssh/src/command.test.ts
@@ -0,0 +1,157 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Result from "effect/Result";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  baseSshArgs,
+  getLastNonEmptyOutputLine,
+  parseSshResolveOutput,
+  resolveRemoteT3CliPackageSpec,
+  runSshCommand,
+} from "./command.ts";
+
+const makeNeverFinishingProcess = () => {
+  let finish: ((exitCode: ChildProcessSpawner.ExitCode) => void) | null = null;
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout: Stream.empty,
+    stderr: Stream.empty,
+    all: Stream.empty,
+    exitCode: Effect.callback<ChildProcessSpawner.ExitCode>((resume) => {
+      finish = (exitCode) => resume(Effect.succeed(exitCode));
+      return Effect.sync(() => {
+        finish = null;
+      });
+    }),
+    isRunning: Effect.succeed(true),
+    kill: () =>
+      Effect.sync(() => {
+        finish?.(ChildProcessSpawner.ExitCode(143));
+      }),
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+};
+
+describe("ssh command", () => {
+  it.effect("parses resolved ssh config output into a target", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        parseSshResolveOutput(
+          "devbox",
+          ["hostname devbox.example.com", "user julius", "port 2222", ""].join("\n"),
+        ),
+        {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 2222,
+        },
+      );
+    }),
+  );
+
+  it.effect("builds interactive ssh args without forcing batch mode", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        baseSshArgs(
+          {
+            alias: "devbox",
+            hostname: "devbox.example.com",
+            username: "julius",
+            port: 2222,
+          },
+          { batchMode: "no" },
+        ),
+        ["-o", "BatchMode=no", "-o", "ConnectTimeout=10", "-p", "2222"],
+      );
+    }),
+  );
+
+  it.effect("resolves the remote t3 package spec from the desktop release channel", () =>
+    Effect.sync(() => {
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.17",
+          updateChannel: "latest",
+        }),
+        "t3@0.0.17",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.17-nightly.20260415.44",
+          updateChannel: "nightly",
+        }),
+        "t3@0.0.17-nightly.20260415.44",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.0-dev",
+          updateChannel: "nightly",
+          isDevelopment: true,
+        }),
+        "t3@nightly",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.0-dev",
+          updateChannel: "latest",
+          isDevelopment: true,
+        }),
+        "t3@nightly",
+      );
+    }),
+  );
+
+  it.effect("reads the last non-empty ssh output line", () =>
+    Effect.sync(() => {
+      assert.equal(
+        getLastNonEmptyOutputLine(
+          ["Welcome to the host", "", '{"credential":"pairing-token"}', ""].join("\n"),
+        ),
+        '{"credential":"pairing-token"}',
+      );
+    }),
+  );
+
+  it.effect("fails commands that never finish", () => {
+    const spawner = ChildProcessSpawner.make(() => Effect.succeed(makeNeverFinishingProcess()));
+    const spawnerLayer = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner);
+    const processLayer = Layer.mergeAll(NodeServices.layer, spawnerLayer, TestClock.layer());
+
+    return Effect.gen(function* () {
+      const fiber = yield* Effect.forkChild(
+        Effect.result(
+          runSshCommand(
+            {
+              alias: "devbox",
+              hostname: "devbox.example.com",
+              username: "julius",
+              port: 2222,
+            },
+            { timeoutMs: 1 },
+          ),
+        ),
+      );
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(1));
+
+      const result = yield* Fiber.join(fiber);
+
+      assert.isTrue(Result.isFailure(result));
+      if (Result.isFailure(result)) {
+        assert.include(result.failure.message, "SSH command timed out after 1ms.");
+      }
+    }).pipe(Effect.provide(processLayer));
+  });
+});
diff --git a/packages/ssh/src/command.ts b/packages/ssh/src/command.ts
new file mode 100644
index 00000000000..dc8839378cd
--- /dev/null
+++ b/packages/ssh/src/command.ts
@@ -0,0 +1,343 @@
+import * as Crypto from "node:crypto";
+
+import type { DesktopSshEnvironmentTarget, DesktopUpdateChannel } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { buildSshChildEnvironment, type SshAuthOptions } from "./auth.ts";
+import { SshCommandError, SshInvalidTargetError } from "./errors.ts";
+
+const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+const DEFAULT_SSH_COMMAND_TIMEOUT_MS = 60_000;
+
+const encoder = new TextEncoder();
+
+export interface SshCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface RunSshCommandOptions extends SshAuthOptions {
+  readonly preHostArgs?: ReadonlyArray<string>;
+  readonly remoteCommandArgs?: ReadonlyArray<string>;
+  readonly stdin?: string;
+  readonly timeoutMs?: number;
+}
+
+export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
+  const values = new Map<string, string>();
+  for (const line of stdout.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const [key, ...rest] = trimmed.split(/\s+/u);
+    if (!key || rest.length === 0 || values.has(key)) {
+      continue;
+    }
+    values.set(key, rest.join(" ").trim());
+  }
+
+  const hostname = values.get("hostname")?.trim() || alias;
+  const username = values.get("user")?.trim() || null;
+  const rawPort = values.get("port")?.trim() ?? "";
+  const parsedPort = Number.parseInt(rawPort, 10);
+
+  return {
+    alias,
+    hostname,
+    username,
+    port: Number.isInteger(parsedPort) ? parsedPort : null,
+  };
+}
+
+export function targetConnectionKey(target: DesktopSshEnvironmentTarget): string {
+  return `${target.alias}\u0000${target.hostname}\u0000${target.username ?? ""}\u0000${target.port ?? ""}`;
+}
+
+export function remoteStateKey(target: DesktopSshEnvironmentTarget): string {
+  return Crypto.createHash("sha256").update(targetConnectionKey(target)).digest("hex").slice(0, 16);
+}
+
+export function buildSshHostSpec(target: DesktopSshEnvironmentTarget): string {
+  const destination = target.alias.trim() || target.hostname.trim();
+  if (destination.length === 0) {
+    throw new Error("SSH target is missing its alias/hostname.");
+  }
+  return target.username ? `${target.username}@${destination}` : destination;
+}
+
+export const buildSshHostSpecEffect = (
+  target: DesktopSshEnvironmentTarget,
+): Effect.Effect<string, SshInvalidTargetError> =>
+  Effect.try({
+    try: () => buildSshHostSpec(target),
+    catch: (cause) =>
+      new SshInvalidTargetError({
+        message: cause instanceof Error ? cause.message : "SSH target is invalid.",
+      }),
+  });
+
+export function baseSshArgs(
+  target: DesktopSshEnvironmentTarget,
+  input?: { readonly batchMode?: "yes" | "no" },
+): string[] {
+  return [
+    "-o",
+    `BatchMode=${input?.batchMode ?? "no"}`,
+    "-o",
+    "ConnectTimeout=10",
+    ...(target.port !== null ? ["-p", String(target.port)] : []),
+  ];
+}
+
+export function getLastNonEmptyOutputLine(stdout: string): string | null {
+  return (
+    stdout
+      .trim()
+      .split(/\r?\n/u)
+      .map((entry) => entry.trim())
+      .findLast((entry) => entry.length > 0) ?? null
+  );
+}
+
+export const collectProcessOutput = <E>(
+  stream: Stream.Stream<Uint8Array, E>,
+): Effect.Effect<string, E> =>
+  stream.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => "",
+      (acc, chunk) => acc + chunk,
+    ),
+  );
+
+function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
+  const cleaned = stderr.trim();
+  return cleaned.length > 0 ? cleaned : fallbackMessage;
+}
+
+function sshTargetLogFields(target: DesktopSshEnvironmentTarget) {
+  return {
+    alias: target.alias,
+    hostname: target.hostname,
+    username: target.username,
+    port: target.port,
+  };
+}
+
+function stdinStream(input: string | undefined) {
+  return input === undefined ? Stream.empty : Stream.make(encoder.encode(input));
+}
+
+const runSshCommandInScope = Effect.fn("ssh/command.runSshCommand.inScope")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input: RunSshCommandOptions,
+  commandScope: Scope.Scope,
+): Effect.fn.Return<
+  SshCommandResult,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const hostSpec = yield* buildSshHostSpecEffect(target);
+  const environment = yield* buildSshChildEnvironment({
+    ...(input.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+    ...(input.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+  }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: ["ssh"],
+          exitCode: null,
+          stderr: "",
+          message: "Failed to prepare SSH authentication helpers.",
+          cause,
+        }),
+    ),
+  );
+  const args = [
+    ...baseSshArgs(target, {
+      batchMode: input.batchMode ?? (input.interactiveAuth ? "no" : "yes"),
+    }),
+    ...(input.preHostArgs ?? []),
+    hostSpec,
+    ...(input.remoteCommandArgs ?? []),
+  ];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  yield* Effect.logDebug("ssh.command.start", {
+    ...sshTargetLogFields(target),
+    command: ["ssh", ...args],
+    hasStdin: input.stdin !== undefined,
+    timeoutMs: input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS,
+  });
+  const child = yield* spawner
+    .spawn(
+      ChildProcess.make("ssh", args, {
+        env: environment,
+        shell: process.platform === "win32",
+        stdin: {
+          stream: stdinStream(input.stdin),
+          endOnDone: true,
+        },
+      }),
+    )
+    .pipe(
+      Effect.provideService(Scope.Scope, commandScope),
+      Effect.mapError(
+        (cause) =>
+          new SshCommandError({
+            command: ["ssh", ...args],
+            exitCode: null,
+            stderr: "",
+            message:
+              cause instanceof Error
+                ? cause.message
+                : `Failed to spawn SSH command for ${hostSpec}.`,
+            cause,
+          }),
+      ),
+    );
+
+  const [stdout, stderr, exitCode] = yield* Effect.all(
+    [
+      collectProcessOutput(child.stdout),
+      collectProcessOutput(child.stderr),
+      child.exitCode.pipe(Effect.map(Number)),
+    ],
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: ["ssh", ...args],
+          exitCode: null,
+          stderr: "",
+          message:
+            cause instanceof Error ? cause.message : `Failed to run SSH command for ${hostSpec}.`,
+          cause,
+        }),
+    ),
+  );
+
+  if (exitCode !== 0) {
+    yield* Effect.logWarning("ssh.command.failed", {
+      ...sshTargetLogFields(target),
+      command: ["ssh", ...args],
+      exitCode,
+      stderr,
+    });
+    return yield* new SshCommandError({
+      command: ["ssh", ...args],
+      exitCode,
+      stderr,
+      message: normalizeSshErrorMessage(
+        stderr,
+        `SSH command failed for ${hostSpec} (exit ${exitCode}).`,
+      ),
+    });
+  }
+
+  yield* Effect.logDebug("ssh.command.succeeded", {
+    ...sshTargetLogFields(target),
+    command: ["ssh", ...args],
+  });
+  return { stdout, stderr };
+});
+
+export const runSshCommand = Effect.fn("ssh/command.runSshCommand")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input: RunSshCommandOptions = {},
+): Effect.fn.Return<
+  SshCommandResult,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  return yield* Effect.scopedWith((commandScope) =>
+    runSshCommandInScope(target, input, commandScope),
+  ).pipe(
+    Effect.timeoutOption(Duration.millis(input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS)),
+    Effect.flatMap((result) =>
+      Option.match(result, {
+        onSome: Effect.succeed,
+        onNone: () =>
+          Effect.gen(function* () {
+            yield* Effect.logWarning("ssh.command.timedOut", {
+              ...sshTargetLogFields(target),
+              timeoutMs: input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS,
+              remoteCommandArgs: input.remoteCommandArgs ?? [],
+              preHostArgs: input.preHostArgs ?? [],
+              hasStdin: input.stdin !== undefined,
+            });
+            return yield* new SshCommandError({
+              command: ["ssh"],
+              exitCode: null,
+              stderr: "",
+              message: `SSH command timed out after ${input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS}ms.`,
+            });
+          }),
+      }),
+    ),
+  );
+});
+
+export const resolveSshTarget = Effect.fn("ssh/command.resolveSshTarget")(function* (
+  alias: string,
+): Effect.fn.Return<
+  DesktopSshEnvironmentTarget,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const trimmedAlias = alias.trim();
+  if (trimmedAlias.length === 0) {
+    return yield* new SshInvalidTargetError({ message: "SSH host alias is required." });
+  }
+
+  yield* Effect.logDebug("ssh.target.resolve.start", { alias: trimmedAlias });
+  return yield* runSshCommand(
+    {
+      alias: trimmedAlias,
+      hostname: trimmedAlias,
+      username: null,
+      port: null,
+    },
+    { preHostArgs: ["-G"] },
+  ).pipe(
+    Effect.map((result) => parseSshResolveOutput(trimmedAlias, result.stdout)),
+    Effect.tap((target) =>
+      Effect.logDebug("ssh.target.resolve.succeeded", sshTargetLogFields(target)),
+    ),
+    Effect.catch((cause) =>
+      Effect.logDebug("ssh.target.resolve.fallback", { alias: trimmedAlias, cause }).pipe(
+        Effect.as({
+          alias: trimmedAlias,
+          hostname: trimmedAlias,
+          username: null,
+          port: null,
+        }),
+      ),
+    ),
+  );
+});
+
+export function resolveRemoteT3CliPackageSpec(input: {
+  readonly appVersion: string;
+  readonly updateChannel: DesktopUpdateChannel;
+  readonly isDevelopment?: boolean;
+}): string {
+  const appVersion = input.appVersion.trim();
+  if (!input.isDevelopment && PUBLISHABLE_T3_VERSION_PATTERN.test(appVersion)) {
+    return `t3@${appVersion}`;
+  }
+
+  if (input.isDevelopment) {
+    return "t3@nightly";
+  }
+
+  return input.updateChannel === "nightly" ? "t3@nightly" : "t3@latest";
+}
diff --git a/packages/ssh/src/config.test.ts b/packages/ssh/src/config.test.ts
new file mode 100644
index 00000000000..0446370337a
--- /dev/null
+++ b/packages/ssh/src/config.test.ts
@@ -0,0 +1,138 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+
+import {
+  discoverSshHosts,
+  parseKnownHostsHostnames,
+  resolveSshConfigIncludePattern,
+} from "./config.ts";
+
+function makeTempHomeDir() {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    return yield* fs.makeTempDirectoryScoped({ prefix: "t3-ssh-test-" });
+  });
+}
+
+describe("ssh config", () => {
+  it.effect("discovers ssh config hosts across included files", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const homeDir = yield* makeTempHomeDir();
+      const sshDir = path.join(homeDir, ".ssh");
+      yield* fs.makeDirectory(path.join(sshDir, "config.d"), { recursive: true });
+      yield* fs.writeFileString(
+        path.join(sshDir, "config"),
+        [
+          "Host devbox",
+          "  HostName devbox.example.com",
+          "Host=equalsbox",
+          "Include=config.d/*.conf",
+          "",
+        ].join("\n"),
+      );
+      yield* fs.writeFileString(
+        path.join(sshDir, "config.d", "team.conf"),
+        [
+          "Host staging",
+          "  HostName staging.example.com",
+          "Host *",
+          "  ServerAliveInterval 30",
+          "",
+        ].join("\n"),
+      );
+      yield* fs.writeFileString(
+        path.join(sshDir, "known_hosts"),
+        [
+          "known.example.com ssh-ed25519 AAAA",
+          "|1|hashed|entry ssh-ed25519 AAAA",
+          "[bastion.example.com]:2222 ssh-ed25519 AAAA",
+          "",
+        ].join("\n"),
+      );
+
+      const hosts = yield* discoverSshHosts({ homeDir });
+      assert.deepEqual(hosts, [
+        {
+          alias: "bastion.example.com",
+          hostname: "bastion.example.com",
+          username: null,
+          port: null,
+          source: "known-hosts",
+        },
+        {
+          alias: "devbox",
+          hostname: "devbox",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
+        {
+          alias: "equalsbox",
+          hostname: "equalsbox",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
+        {
+          alias: "known.example.com",
+          hostname: "known.example.com",
+          username: null,
+          port: null,
+          source: "known-hosts",
+        },
+        {
+          alias: "staging",
+          hostname: "staging",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
+      ]);
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+
+  it.effect("parses known_hosts entries without returning hashed hosts", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        parseKnownHostsHostnames(
+          [
+            "github.com ssh-ed25519 AAAA",
+            "gitlab.com,gitlab-alias ssh-ed25519 BBBB",
+            "|1|hashed|entry ssh-ed25519 CCCC",
+            "@cert-authority *.example.com ssh-ed25519 DDDD",
+            "[ssh.example.com]:2200 ssh-ed25519 EEEE",
+            "port.example.com:22 ssh-ed25519 HHHH",
+            "::1 ssh-ed25519 FFFF",
+            "2001:db8::1 ssh-ed25519 GGGG",
+            "",
+          ].join("\n"),
+        ),
+        [
+          "::1",
+          "2001:db8::1",
+          "github.com",
+          "gitlab-alias",
+          "gitlab.com",
+          "port.example.com",
+          "ssh.example.com",
+        ],
+      );
+    }),
+  );
+
+  it.effect("expands tilde-prefixed ssh config include patterns", () =>
+    Effect.gen(function* () {
+      const pattern = yield* resolveSshConfigIncludePattern(
+        "~/.ssh/config.d/*.conf",
+        "/tmp/project",
+        "/tmp/home",
+      );
+      assert.equal(pattern, "/tmp/home/.ssh/config.d/*.conf");
+    }).pipe(Effect.provide(NodeServices.layer)),
+  );
+});
diff --git a/packages/ssh/src/config.ts b/packages/ssh/src/config.ts
new file mode 100644
index 00000000000..a8d17946129
--- /dev/null
+++ b/packages/ssh/src/config.ts
@@ -0,0 +1,254 @@
+import type { DesktopDiscoveredSshHost } from "@t3tools/contracts";
+
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as PlatformError from "effect/PlatformError";
+
+import { SshHostDiscoveryError } from "./errors.ts";
+
+const NO_HOSTS: ReadonlyArray<string> = [] as const;
+
+function stripInlineComment(line: string): string {
+  const hashIndex = line.indexOf("#");
+  return (hashIndex >= 0 ? line.slice(0, hashIndex) : line).trim();
+}
+
+function splitDirectiveArgs(value: string): ReadonlyArray<string> {
+  return value
+    .replace(/=(?!=)/gu, " ")
+    .trim()
+    .split(/\s+/u)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function expandHomePath(input: string, homeDir: string): string {
+  return input.replace(/^~(?=$|\/|\\)/u, homeDir);
+}
+
+export const resolveSshConfigIncludePattern = Effect.fnUntraced(function* (
+  includePattern: string,
+  _directory: string,
+  homeDir: string,
+) {
+  const path = yield* Path.Path;
+  const expandedPattern = expandHomePath(includePattern, homeDir);
+  return path.isAbsolute(expandedPattern)
+    ? expandedPattern
+    : path.resolve(path.join(homeDir, ".ssh"), expandedPattern);
+});
+
+function hasSshPattern(value: string): boolean {
+  return value.includes("*") || value.includes("?") || value.startsWith("!");
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function globToRegExp(pattern: string): RegExp {
+  return new RegExp(
+    `^${escapeRegex(pattern).replace(/\\\*/gu, ".*").replace(/\\\?/gu, ".")}$`,
+    "u",
+  );
+}
+
+const expandGlob = Effect.fnUntraced(function* (pattern: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return (yield* fs.exists(pattern)) ? [pattern] : NO_HOSTS;
+  }
+
+  const directory = path.dirname(pattern);
+  const basePattern = path.basename(pattern);
+  if (!(yield* fs.exists(directory))) {
+    return NO_HOSTS;
+  }
+
+  const matcher = globToRegExp(basePattern);
+  const entries = yield* fs.readDirectory(directory);
+  const matchedPaths: string[] = [];
+  for (const entry of entries) {
+    if (!matcher.test(entry)) {
+      continue;
+    }
+    const entryPath = path.join(directory, entry);
+    if (yield* fs.exists(entryPath)) {
+      matchedPaths.push(entryPath);
+    }
+  }
+  return matchedPaths.toSorted((left, right) => left.localeCompare(right));
+});
+
+export const collectSshConfigAliasesFromFile = Effect.fnUntraced(function* (
+  filePath: string,
+  visited = new Set<string>(),
+  homeDir: string,
+): Effect.fn.Return<
+  ReadonlyArray<string>,
+  PlatformError.PlatformError,
+  FileSystem.FileSystem | Path.Path
+> {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const resolvedPath = path.resolve(filePath);
+  if (visited.has(resolvedPath) || !(yield* fs.exists(resolvedPath))) {
+    return NO_HOSTS;
+  }
+  visited.add(resolvedPath);
+
+  const aliases = new Set<string>();
+  const directory = path.dirname(resolvedPath);
+  const raw = yield* fs.readFileString(resolvedPath);
+
+  for (const line of raw.split(/\r?\n/u)) {
+    const stripped = stripInlineComment(line);
+    if (stripped.length === 0) {
+      continue;
+    }
+
+    const [directive = "", ...rawArgs] = splitDirectiveArgs(stripped);
+    const normalizedDirective = directive.toLowerCase();
+    if (normalizedDirective === "include") {
+      for (const includePattern of rawArgs) {
+        const resolvedPattern = yield* resolveSshConfigIncludePattern(
+          includePattern,
+          directory,
+          homeDir,
+        );
+        const includedPaths = yield* expandGlob(resolvedPattern);
+        for (const includedPath of includedPaths) {
+          const includedAliases = yield* collectSshConfigAliasesFromFile(
+            includedPath,
+            visited,
+            homeDir,
+          );
+          for (const alias of includedAliases) {
+            aliases.add(alias);
+          }
+        }
+      }
+      continue;
+    }
+
+    if (normalizedDirective !== "host") {
+      continue;
+    }
+
+    for (const alias of rawArgs) {
+      if (alias.length === 0 || hasSshPattern(alias)) {
+        continue;
+      }
+      aliases.add(alias);
+    }
+  }
+
+  return [...aliases].toSorted((left, right) => left.localeCompare(right));
+});
+
+function normalizeKnownHostsHostname(rawHost: string): string {
+  const bracketMatch = /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost);
+  if (bracketMatch?.[1]) {
+    return bracketMatch[1];
+  }
+
+  if (!rawHost.includes(":")) {
+    return rawHost;
+  }
+
+  const firstColonIndex = rawHost.indexOf(":");
+  const lastColonIndex = rawHost.lastIndexOf(":");
+  return firstColonIndex === lastColonIndex ? rawHost.slice(0, lastColonIndex) : rawHost;
+}
+
+export function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
+  const hostnames = new Set<string>();
+
+  for (const line of raw.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const withoutMarker = trimmed.startsWith("@")
+      ? trimmed.split(/\s+/u).slice(1).join(" ")
+      : trimmed;
+    const [hostField = ""] = withoutMarker.split(/\s+/u);
+    if (hostField.length === 0 || hostField.startsWith("|")) {
+      continue;
+    }
+
+    for (const rawHost of hostField.split(",")) {
+      const host = normalizeKnownHostsHostname(rawHost).trim();
+      if (host.length === 0 || hasSshPattern(host)) {
+        continue;
+      }
+      hostnames.add(host);
+    }
+  }
+
+  return [...hostnames].toSorted((left, right) => left.localeCompare(right));
+}
+
+const readKnownHostsHostnames = Effect.fnUntraced(function* (filePath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(filePath))) {
+    return NO_HOSTS;
+  }
+  return parseKnownHostsHostnames(yield* fs.readFileString(filePath));
+});
+
+export const discoverSshHosts = Effect.fnUntraced(
+  function* (input: { readonly homeDir?: string }) {
+    const path = yield* Path.Path;
+    const homeDir = input?.homeDir ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (homeDir.trim().length === 0) {
+      return [];
+    }
+
+    const sshDirectory = path.join(homeDir, ".ssh");
+    const configAliases = yield* collectSshConfigAliasesFromFile(
+      path.join(sshDirectory, "config"),
+      new Set<string>(),
+      homeDir,
+    );
+    const knownHosts = yield* readKnownHostsHostnames(path.join(sshDirectory, "known_hosts"));
+    const discovered = new Map<string, DesktopDiscoveredSshHost>();
+
+    for (const alias of configAliases) {
+      discovered.set(alias, {
+        alias,
+        hostname: alias,
+        username: null,
+        port: null,
+        source: "ssh-config",
+      });
+    }
+
+    for (const hostname of knownHosts) {
+      if (discovered.has(hostname)) {
+        continue;
+      }
+      discovered.set(hostname, {
+        alias: hostname,
+        hostname,
+        username: null,
+        port: null,
+        source: "known-hosts",
+      });
+    }
+
+    return [...discovered.values()].toSorted((left, right) =>
+      left.alias.localeCompare(right.alias),
+    );
+  },
+  Effect.mapError(
+    (cause) =>
+      new SshHostDiscoveryError({
+        message: "Failed to discover SSH hosts.",
+        cause,
+      }),
+  ),
+);
diff --git a/packages/ssh/src/errors.ts b/packages/ssh/src/errors.ts
new file mode 100644
index 00000000000..357aaef091d
--- /dev/null
+++ b/packages/ssh/src/errors.ts
@@ -0,0 +1,46 @@
+import * as Data from "effect/Data";
+
+export class SshHostDiscoveryError extends Data.TaggedError("SshHostDiscoveryError")<{
+  readonly message: string;
+  readonly cause: unknown;
+}> {}
+
+export class SshInvalidTargetError extends Data.TaggedError("SshInvalidTargetError")<{
+  readonly message: string;
+}> {}
+
+export class SshCommandError extends Data.TaggedError("SshCommandError")<{
+  readonly message: string;
+  readonly command: readonly string[];
+  readonly exitCode: number | null;
+  readonly stderr: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshLaunchError extends Data.TaggedError("SshLaunchError")<{
+  readonly message: string;
+  readonly stdout: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshPairingError extends Data.TaggedError("SshPairingError")<{
+  readonly message: string;
+  readonly stdout: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshHttpBridgeError extends Data.TaggedError("SshHttpBridgeError")<{
+  readonly message: string;
+  readonly status?: number;
+  readonly cause?: unknown;
+}> {}
+
+export class SshReadinessError extends Data.TaggedError("SshReadinessError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshPasswordPromptError extends Data.TaggedError("SshPasswordPromptError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
new file mode 100644
index 00000000000..80e684d8611
--- /dev/null
+++ b/packages/ssh/src/tunnel.test.ts
@@ -0,0 +1,393 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NetService from "@t3tools/shared/Net";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Result from "effect/Result";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { SshPasswordPrompt } from "./auth.ts";
+import {
+  buildRemoteLaunchScript,
+  buildRemotePairingScript,
+  buildRemoteStopScript,
+  buildRemoteT3RunnerScript,
+  describeReadinessCause,
+  issueRemotePairingToken,
+  launchOrReuseRemoteServer,
+  REMOTE_PICK_PORT_SCRIPT,
+  SshEnvironmentManager,
+  waitForHttpReady,
+} from "./tunnel.ts";
+
+const TEST_NODE_ENGINE_RANGE = "^22.16 || ^23.11 || >=24.10";
+
+const makeSuccessfulProcess = (stdout: string) => {
+  const stdoutStream = Stream.make(new TextEncoder().encode(stdout));
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout: stdoutStream,
+    stderr: Stream.empty,
+    all: stdoutStream,
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+};
+
+const makeRunningProcess = (onKill: () => void) => {
+  let finish: ((exitCode: ChildProcessSpawner.ExitCode) => void) | null = null;
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout: Stream.empty,
+    stderr: Stream.empty,
+    all: Stream.empty,
+    exitCode: Effect.callback<ChildProcessSpawner.ExitCode>((resume) => {
+      finish = (exitCode) => resume(Effect.succeed(exitCode));
+      return Effect.sync(() => {
+        finish = null;
+      });
+    }),
+    isRunning: Effect.succeed(true),
+    kill: () =>
+      Effect.sync(() => {
+        onKill();
+        finish?.(ChildProcessSpawner.ExitCode(143));
+      }),
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+};
+
+const testHttpClient = HttpClient.make((request) =>
+  Effect.succeed(HttpClientResponse.fromWeb(request, new Response("", { status: 200 }))),
+);
+
+const hangingHttpClient = HttpClient.make(() => Effect.never);
+
+const testNetService = NetService.NetService.of({
+  canListenOnHost: () => Effect.succeed(true),
+  isPortAvailableOnLoopback: () => Effect.succeed(true),
+  reserveLoopbackPort: () => Effect.succeed(41_773),
+  findAvailablePort: (preferred) => Effect.succeed(preferred),
+});
+
+function commandArgs(command: ChildProcess.Command): ReadonlyArray<string> {
+  return command._tag === "StandardCommand" ? command.args : [];
+}
+
+describe("ssh tunnel scripts", () => {
+  it("builds the remote t3 runner with npx and npm fallbacks", () => {
+    const script = buildRemoteT3RunnerScript({ nodeEngineRange: TEST_NODE_ENGINE_RANGE });
+
+    assert.include(script, "T3_NODE_SCRIPT_PATH=''");
+    assert.include(script, 'exec t3 "$@"');
+    assert.include(script, "exec npx --yes 't3@latest' \"$@\"");
+    assert.include(script, "exec npm exec --yes 't3@latest' -- \"$@\"");
+    assert.include(script, "could not install 't3@latest'");
+    assert.include(script, 'prepend_path_if_dir "$HOME/.local/bin"');
+    assert.include(script, `T3_NODE_ENGINE_RANGE='${TEST_NODE_ENGINE_RANGE}'`);
+    assert.include(script, "remote_node_satisfies_engine()");
+    assert.include(script, "function satisfiesSemverRange");
+    assert.include(script, "satisfiesSemverRange(rawVersion, range)");
+    assert.include(script, 'prepend_path_if_dir "$VOLTA_HOME/bin"');
+    assert.include(script, 'prepend_path_if_dir "$HOME/.asdf/shims"');
+    assert.include(script, 'prepend_path_if_dir "$HOME/.local/share/mise/shims"');
+    assert.include(script, 'eval "$(fnm env --use-on-cd --shell sh)"');
+    assert.include(script, 'prepend_path_if_dir "$HOME/.nodenv/shims"');
+    assert.include(script, 'NVM_DIR="$HOME/.nvm"');
+    assert.include(script, "nvm use --silent default");
+    assert.include(script, 'for T3_NODE_BIN in "$NVM_DIR"/versions/node/*/bin');
+    assert.notInclude(script, "ensure $NVM_DIR/nvm.sh is available");
+  });
+
+  it("does not hard-code a remote node engine range", () => {
+    const script = buildRemoteT3RunnerScript();
+
+    assert.include(script, "T3_NODE_ENGINE_RANGE=''");
+    assert.notInclude(script, TEST_NODE_ENGINE_RANGE);
+  });
+
+  it("shell-quotes package specs in the remote t3 runner", () => {
+    const script = buildRemoteT3RunnerScript({
+      packageSpec: "t3@nightly; touch /tmp/t3-owned",
+    });
+
+    assert.include(script, "exec npx --yes 't3@nightly; touch /tmp/t3-owned' \"$@\"");
+    assert.include(script, "exec npm exec --yes 't3@nightly; touch /tmp/t3-owned' -- \"$@\"");
+    assert.notInclude(script, "exec npx --yes t3@nightly; touch /tmp/t3-owned");
+  });
+
+  it("builds the remote t3 runner with a node script override", () => {
+    const script = buildRemoteT3RunnerScript({
+      nodeScriptPath: "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs",
+    });
+
+    assert.include(
+      script,
+      "T3_NODE_SCRIPT_PATH='/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs'",
+    );
+    assert.include(script, 'exec node "$T3_NODE_SCRIPT_PATH" "$@"');
+  });
+
+  it("uses the remote t3 runner for launch and pairing scripts", () => {
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+
+    assert.include(
+      buildRemoteLaunchScript({ nodeEngineRange: TEST_NODE_ENGINE_RANGE }),
+      '[ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null',
+    );
+    assert.include(buildRemoteLaunchScript(), "RUNNER_CHANGED=1");
+    assert.include(buildRemoteLaunchScript(), "ensure_remote_node_path()");
+    assert.include(buildRemoteLaunchScript(), "if ! ensure_remote_node_path; then");
+    assert.include(
+      buildRemoteLaunchScript({ nodeEngineRange: TEST_NODE_ENGINE_RANGE }),
+      `T3_NODE_ENGINE_RANGE='${TEST_NODE_ENGINE_RANGE}'`,
+    );
+    assert.include(
+      buildRemoteLaunchScript({ nodeEngineRange: TEST_NODE_ENGINE_RANGE }),
+      "does not satisfy required range ",
+    );
+    assert.include(buildRemoteLaunchScript(), 'kill "$REMOTE_PID" 2>/dev/null || true');
+    assert.include(buildRemoteLaunchScript(), "wait_ready");
+    assert.include(buildRemoteLaunchScript(), '"$RUNNER_FILE" serve --host 127.0.0.1');
+    assert.include(buildRemoteLaunchScript(), '--base-dir "$DEFAULT_SERVER_HOME"');
+    assert.notInclude(buildRemoteLaunchScript(), "server-home");
+    assert.include(buildRemoteLaunchScript(), "Remote T3 server did not become ready");
+    assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
+    assert.include(
+      buildRemotePairingScript(target),
+      '"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json',
+    );
+    assert.include(buildRemotePairingScript(target), 'PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"');
+    assert.notInclude(buildRemotePairingScript(target), "server-home");
+    assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
+    assert.include(
+      buildRemoteStopScript(target),
+      'if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ]',
+    );
+    assert.include(buildRemoteStopScript(target), 'kill "$REMOTE_PID" 2>/dev/null || true');
+    assert.include(buildRemoteStopScript(target), 'rm -f "$PID_FILE" "$PORT_FILE" "$MANAGED_FILE"');
+    assert.include(
+      buildRemoteLaunchScript(),
+      'DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"',
+    );
+    assert.include(buildRemoteLaunchScript(), "resolve_default_runtime_port()");
+    assert.include(
+      buildRemoteLaunchScript(),
+      'DEFAULT_RUNTIME_INFO="$(resolve_default_runtime_port',
+    );
+    assert.include(
+      buildRemoteLaunchScript(),
+      "if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(port))",
+    );
+    assert.include(buildRemoteLaunchScript(), 'PID_TO_STOP="${REMOTE_PID:-$DEFAULT_RUNTIME_PID}"');
+    assert.include(buildRemoteLaunchScript(), 'REMOTE_PORT="$DEFAULT_REMOTE_PORT"');
+    assert.include(buildRemoteLaunchScript(), 'rm -f "$PID_FILE"');
+    assert.include(buildRemoteLaunchScript(), "printf 'external\\n' >\"$MANAGED_FILE\"");
+    assert.include(buildRemoteLaunchScript(), 'if [ -z "$REMOTE_PORT" ]; then');
+    assert.isBelow(
+      buildRemoteLaunchScript().indexOf('if [ "$REMOTE_MANAGED" = "managed" ]'),
+      buildRemoteLaunchScript().indexOf("printf 'external\\n' >\"$MANAGED_FILE\""),
+    );
+    assert.isBelow(
+      buildRemoteLaunchScript().indexOf('DEFAULT_RUNTIME_INFO="$(resolve_default_runtime_port'),
+      buildRemoteLaunchScript().indexOf('elif [ -n "$REMOTE_PID" ]'),
+    );
+  });
+
+  it.effect("accepts launch JSON after remote shell startup noise", () => {
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+    const spawner = ChildProcessSpawner.make(() =>
+      Effect.succeed(makeSuccessfulProcess('loaded nvm default\n{"remotePort":3774}\n')),
+    );
+    const spawnerLayer = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner);
+    const processLayer = Layer.merge(NodeServices.layer, spawnerLayer);
+
+    return Effect.gen(function* () {
+      const result = yield* launchOrReuseRemoteServer(target);
+      assert.equal(result.remotePort, 3774);
+    }).pipe(Effect.provide(processLayer));
+  });
+
+  it("allows the remote port picker to run without a state file path", () => {
+    assert.include(REMOTE_PICK_PORT_SCRIPT, 'const filePath = process.argv[2] ?? "";');
+  });
+
+  it.effect("bounds each HTTP readiness probe so retries cannot hang on one request", () =>
+    Effect.gen(function* () {
+      const fiber = yield* Effect.forkChild(
+        Effect.result(
+          waitForHttpReady({
+            baseUrl: "http://127.0.0.1:41773/",
+            timeoutMs: 1_000,
+            intervalMs: 100,
+            probeTimeoutMs: 250,
+          }),
+        ),
+      );
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(1_000));
+
+      const result = yield* Fiber.join(fiber);
+
+      assert.isTrue(Result.isFailure(result));
+      if (Result.isFailure(result)) {
+        assert.include(result.failure.message, "Timed out waiting 1000ms");
+      }
+    }).pipe(
+      Effect.provide(
+        Layer.merge(TestClock.layer(), Layer.succeed(HttpClient.HttpClient, hangingHttpClient)),
+      ),
+    ),
+  );
+
+  it("preserves primitive readiness reason values in diagnostic output", () => {
+    assert.deepEqual(
+      describeReadinessCause({
+        _tag: "HttpClientError",
+        message: "Backend readiness probe failed.",
+        reason: "authentication failed",
+        cause: "upstream closed",
+      }),
+      {
+        _tag: "HttpClientError",
+        message: "Backend readiness probe failed.",
+        reason: "authentication failed",
+        cause: "upstream closed",
+      },
+    );
+  });
+
+  it.effect("accepts pretty-printed pairing JSON from the remote CLI", () => {
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+    const spawner = ChildProcessSpawner.make(() =>
+      Effect.succeed(
+        makeSuccessfulProcess(`{
+  "id": "88941235-6ed5-4184-a2ff-5339e2075958",
+  "credential": "LCL4R2TPHDKQ",
+  "role": "client",
+  "expiresAt": "2026-04-29T01:01:20.994Z"
+}
+
+`),
+      ),
+    );
+    const spawnerLayer = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner);
+    const processLayer = Layer.merge(NodeServices.layer, spawnerLayer);
+    return Effect.gen(function* () {
+      const result = yield* issueRemotePairingToken(target);
+      assert.equal(result.credential, "LCL4R2TPHDKQ");
+    }).pipe(Effect.provide(processLayer));
+  });
+
+  it.effect("accepts pretty-printed pairing JSON after remote shell startup noise", () => {
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+    const spawner = ChildProcessSpawner.make(() =>
+      Effect.succeed(
+        makeSuccessfulProcess(`loaded nvm default
+{
+  "id": "88941235-6ed5-4184-a2ff-5339e2075958",
+  "credential": "LCL4R2TPHDKQ",
+  "role": "client",
+  "expiresAt": "2026-04-29T01:01:20.994Z"
+}
+
+`),
+      ),
+    );
+    const spawnerLayer = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner);
+    const processLayer = Layer.merge(NodeServices.layer, spawnerLayer);
+    return Effect.gen(function* () {
+      const result = yield* issueRemotePairingToken(target);
+      assert.equal(result.credential, "LCL4R2TPHDKQ");
+    }).pipe(Effect.provide(processLayer));
+  });
+
+  it.effect("closes the tunnel scope and starts fresh after disconnect", () => {
+    const spawnedCommands: Array<ReadonlyArray<string>> = [];
+    let tunnelKillCount = 0;
+    let stopCommandCount = 0;
+    const spawner = ChildProcessSpawner.make((command) =>
+      Effect.sync(() => {
+        const args = commandArgs(command);
+        spawnedCommands.push(args);
+        if (args.includes("-N")) {
+          return makeRunningProcess(() => {
+            tunnelKillCount += 1;
+          });
+        }
+        if (args.includes("sh") && args.includes("--")) {
+          return makeSuccessfulProcess('{"remotePort":3773}\n');
+        }
+        if (args.includes("sh")) {
+          stopCommandCount += 1;
+          return makeSuccessfulProcess('{"stopped":true}\n');
+        }
+        return makeSuccessfulProcess("\n");
+      }),
+    );
+    const layer = Layer.mergeAll(
+      NodeServices.layer,
+      Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner),
+      Layer.succeed(HttpClient.HttpClient, testHttpClient),
+      Layer.succeed(NetService.NetService, testNetService),
+      SshPasswordPrompt.disabledLayer,
+      SshEnvironmentManager.layer(),
+    );
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+
+    return Effect.gen(function* () {
+      const manager = yield* SshEnvironmentManager;
+
+      const first = yield* manager.ensureEnvironment(target);
+      assert.equal(first.httpBaseUrl, "http://127.0.0.1:41773/");
+
+      yield* manager.disconnectEnvironment(target);
+      assert.equal(tunnelKillCount, 1);
+      assert.equal(stopCommandCount, 1);
+
+      yield* manager.ensureEnvironment(target);
+
+      assert.equal(spawnedCommands.filter((args) => args.includes("-N")).length, 2);
+      assert.equal(tunnelKillCount, 1);
+    }).pipe(Effect.provide(layer), Effect.scoped);
+  });
+});
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
new file mode 100644
index 00000000000..5ee5c684779
--- /dev/null
+++ b/packages/ssh/src/tunnel.ts
@@ -0,0 +1,1762 @@
+import type {
+  DesktopSshEnvironmentBootstrap,
+  DesktopSshEnvironmentTarget,
+} from "@t3tools/contracts";
+import * as NetService from "@t3tools/shared/Net";
+import { extractJsonObject, fromLenientJson } from "@t3tools/shared/schemaJson";
+import { satisfiesSemverRange } from "@t3tools/shared/semver";
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Ref from "effect/Ref";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  buildSshChildEnvironment,
+  type SshAuthOptions,
+  SshPasswordPrompt,
+  isSshAuthFailure,
+} from "./auth.ts";
+import {
+  baseSshArgs,
+  buildSshHostSpecEffect,
+  collectProcessOutput,
+  getLastNonEmptyOutputLine,
+  remoteStateKey,
+  resolveSshTarget,
+  runSshCommand,
+  targetConnectionKey,
+} from "./command.ts";
+import {
+  SshCommandError,
+  SshHttpBridgeError,
+  SshInvalidTargetError,
+  SshLaunchError,
+  SshPairingError,
+  SshPasswordPromptError,
+  SshReadinessError,
+} from "./errors.ts";
+
+export const DEFAULT_REMOTE_PORT = 3773;
+const REMOTE_PORT_SCAN_WINDOW = 200;
+const SSH_READY_TIMEOUT_MS = 20_000;
+const SSH_READY_PROBE_TIMEOUT_MS = 1_000;
+const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
+const REMOTE_READY_TIMEOUT_MS = 15_000;
+const REMOTE_REUSE_READY_TIMEOUT_MS = 2_000;
+
+export interface RemoteT3RunnerOptions {
+  readonly packageSpec?: string;
+  readonly nodeScriptPath?: string | null;
+  readonly nodeEngineRange?: string | null;
+}
+
+export interface SshEnvironmentManagerOptions {
+  readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: Effect.Effect<RemoteT3RunnerOptions>;
+}
+
+interface SshTunnelEntry {
+  readonly key: string;
+  readonly target: DesktopSshEnvironmentTarget;
+  readonly remotePort: number;
+  readonly remoteServerKind: "external" | "managed" | null;
+  readonly localPort: number;
+  readonly httpBaseUrl: string;
+  readonly wsBaseUrl: string;
+  readonly process: ChildProcessSpawner.ChildProcessHandle;
+  readonly scope: Scope.Scope;
+}
+
+type SshEnvironmentEffectContext =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | HttpClient.HttpClient
+  | NetService.NetService
+  | SshPasswordPrompt;
+
+type SshEnvironmentEffectError =
+  | SshCommandError
+  | SshInvalidTargetError
+  | SshLaunchError
+  | SshPairingError
+  | SshReadinessError
+  | SshPasswordPromptError
+  | NetService.NetError;
+
+function makeSshTunnelCancelledError(target: DesktopSshEnvironmentTarget): SshCommandError {
+  return new SshCommandError({
+    command: ["ssh"],
+    exitCode: null,
+    stderr: "",
+    message: `SSH environment connection was cancelled for ${target.alias || target.hostname}.`,
+  });
+}
+
+function sshTargetLogFields(target: DesktopSshEnvironmentTarget) {
+  return {
+    alias: target.alias,
+    hostname: target.hostname,
+    username: target.username,
+    port: target.port,
+  };
+}
+
+function sshRunnerLogFields(runner: RemoteT3RunnerOptions | undefined) {
+  if (runner?.nodeScriptPath?.trim()) {
+    return { runner: "node-script", nodeScriptPath: runner.nodeScriptPath.trim() };
+  }
+  if (runner?.packageSpec?.trim()) {
+    return { runner: "package", packageSpec: runner.packageSpec.trim() };
+  }
+  return { runner: "default" };
+}
+
+interface SshAuthOperationInput<T> {
+  readonly key: string;
+  readonly target: DesktopSshEnvironmentTarget;
+  readonly operation: (
+    authOptions: SshAuthOptions,
+  ) => Effect.Effect<T, SshEnvironmentEffectError, SshEnvironmentEffectContext>;
+}
+
+interface SshAuthAttemptInput<T> extends SshAuthOperationInput<T> {
+  readonly promptCount: number;
+  readonly authSecret: string | null;
+}
+
+export interface SshEnvironmentManagerShape {
+  readonly ensureEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+    options?: { readonly issuePairingToken?: boolean },
+  ) => Effect.Effect<
+    DesktopSshEnvironmentBootstrap,
+    SshEnvironmentEffectError,
+    SshEnvironmentEffectContext
+  >;
+  readonly disconnectEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+  ) => Effect.Effect<void, SshEnvironmentEffectError, SshEnvironmentEffectContext>;
+}
+
+const RemoteLaunchResult = Schema.Struct({
+  remotePort: Schema.Number,
+  serverKind: Schema.optional(Schema.Literals(["external", "managed"])),
+});
+
+const RemotePairingResult = Schema.Struct({
+  credential: Schema.String,
+});
+
+const RemoteHttpError = Schema.Struct({
+  error: Schema.optional(Schema.String),
+});
+
+const decodeRemoteLaunchResult = Schema.decodeEffect(fromLenientJson(RemoteLaunchResult));
+const decodeRemotePairingResult = Schema.decodeEffect(fromLenientJson(RemotePairingResult));
+const decodeRemoteHttpError = Schema.decodeEffect(Schema.fromJsonString(RemoteHttpError));
+
+const decodeRemoteJsonOutput = <A, E>(
+  stdout: string,
+  decode: (input: string) => Effect.Effect<A, E>,
+): Effect.Effect<A, E> =>
+  decode(stdout).pipe(
+    Effect.catch((error) =>
+      Effect.gen(function* () {
+        const jsonObject = extractJsonObject(stdout);
+        if (jsonObject === stdout.trim()) {
+          return yield* Effect.fail(error);
+        }
+        const exit = yield* Effect.exit(decode(jsonObject));
+        if (Exit.isSuccess(exit)) {
+          return exit.value;
+        }
+        return yield* Effect.fail(error);
+      }),
+    ),
+  );
+
+const decodeRemoteLaunchOutput = (stdout: string) =>
+  decodeRemoteJsonOutput(stdout, decodeRemoteLaunchResult);
+
+const decodeRemotePairingOutput = (stdout: string) =>
+  decodeRemoteJsonOutput(stdout, decodeRemotePairingResult);
+
+const remoteNodeEngineCheckMain = function remoteNodeEngineCheckMain() {
+  const range = process.argv[2] || "";
+  const rawVersion =
+    process.versions && process.versions.node ? process.versions.node : process.version;
+
+  if (!satisfiesSemverRange(rawVersion, range)) {
+    process.stderr.write(
+      "Remote node " + rawVersion + " does not satisfy required range " + range + ".\n",
+    );
+    process.exit(1);
+  }
+};
+
+function buildRemoteNodeEngineCheckScript(): string {
+  return `${satisfiesSemverRange.toString()}
+(${remoteNodeEngineCheckMain.toString()})();`;
+}
+
+export function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
+  const cleaned = stderr.trim();
+  return cleaned.length > 0 ? cleaned : fallbackMessage;
+}
+
+function stripTrailingNewlines(value: string): string {
+  return value.replace(/\n+$/u, "");
+}
+
+function shellSingleQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function applyScriptPlaceholders(
+  template: string,
+  replacements: Readonly<Record<string, string>>,
+): string {
+  let result = template;
+  for (const [token, value] of Object.entries(replacements)) {
+    result = result.replaceAll(`@@${token}@@`, value);
+  }
+  return result;
+}
+
+export function describeReadinessCause(cause: unknown): unknown {
+  if (cause instanceof SshReadinessError) {
+    return {
+      _tag: cause._tag,
+      message: cause.message,
+      ...(cause.cause === undefined ? {} : { cause: describeReadinessCause(cause.cause) }),
+    };
+  }
+  if (cause instanceof Error) {
+    return {
+      name: cause.name,
+      message: cause.message,
+      ...(cause.cause === undefined ? {} : { cause: describeReadinessCause(cause.cause) }),
+    };
+  }
+  if (typeof cause !== "object" || cause === null) {
+    return cause;
+  }
+
+  const record = cause as Readonly<Record<string, unknown>>;
+  return {
+    ...(typeof record._tag === "string" ? { _tag: record._tag } : {}),
+    ...(typeof record.message === "string" ? { message: record.message } : {}),
+    ...(record.reason === undefined ? {} : { reason: describeReadinessCause(record.reason) }),
+    ...(record.cause === undefined ? {} : { cause: describeReadinessCause(record.cause) }),
+  };
+}
+
+export const REMOTE_PICK_PORT_SCRIPT = `const fs = require("node:fs");
+const net = require("node:net");
+const filePath = process.argv[2] ?? "";
+const defaultPort = Number.parseInt(process.argv[3] ?? "", 10);
+const scanWindow = Number.parseInt(process.argv[4] ?? "", 10);
+const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8").trim() : "";
+const preferred = Number.parseInt(raw, 10);
+const start = Number.isInteger(preferred) ? preferred : defaultPort;
+const end = start + scanWindow;
+
+function tryPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => {
+      server.close((error) => resolve(error ? false : port));
+    });
+  });
+}
+
+(async () => {
+  for (let port = start; port < end; port += 1) {
+    const available = await tryPort(port);
+    if (available) {
+      process.stdout.write(String(port));
+      return;
+    }
+  }
+  process.exit(1);
+})().catch(() => process.exit(1));
+`;
+
+export const REMOTE_WAIT_READY_SCRIPT = `const http = require("node:http");
+const port = Number.parseInt(process.argv[2] ?? "", 10);
+const timeoutMs = Number.parseInt(process.argv[3] ?? "", 10);
+const probeTimeoutMs = Number.parseInt(process.argv[4] ?? "", 10);
+if (!Number.isInteger(port) || !Number.isInteger(timeoutMs) || !Number.isInteger(probeTimeoutMs)) {
+  process.exit(1);
+}
+const deadline = Date.now() + timeoutMs;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function probe() {
+  return new Promise((resolve) => {
+    const request = http.get(
+      {
+        hostname: "127.0.0.1",
+        port,
+        path: "/",
+        timeout: probeTimeoutMs,
+      },
+      (response) => {
+        response.resume();
+        response.once("end", () => {
+          resolve(response.statusCode >= 200 && response.statusCode < 300);
+        });
+      },
+    );
+    request.once("timeout", () => {
+      request.destroy();
+      resolve(false);
+    });
+    request.once("error", () => resolve(false));
+  });
+}
+
+(async () => {
+  while (Date.now() < deadline) {
+    if (await probe()) {
+      process.exit(0);
+    }
+    await sleep(100);
+  }
+  process.exit(1);
+})().catch(() => process.exit(1));
+`;
+
+export const REMOTE_NODE_ENV_SCRIPT = `prepend_path_if_dir() {
+  if [ -d "$1" ]; then
+    case ":$PATH:" in
+      *":$1:"*) ;;
+      *) PATH="$1:$PATH" ;;
+    esac
+  fi
+}
+
+remote_node_satisfies_engine() {
+  T3_NODE_ENGINE_RANGE=@@T3_NODE_ENGINE_RANGE@@
+  if [ -z "$T3_NODE_ENGINE_RANGE" ]; then
+    return 0
+  fi
+  node - "$T3_NODE_ENGINE_RANGE" <<'NODE'
+@@T3_NODE_ENGINE_CHECK_SCRIPT@@
+NODE
+}
+
+ensure_remote_node_path() {
+  if command -v node >/dev/null 2>&1 && remote_node_satisfies_engine >/dev/null 2>&1; then
+    return 0
+  fi
+
+  prepend_path_if_dir "$HOME/.local/bin"
+  prepend_path_if_dir "$HOME/bin"
+  prepend_path_if_dir "/opt/homebrew/bin"
+  prepend_path_if_dir "/usr/local/bin"
+  prepend_path_if_dir "/usr/bin"
+  prepend_path_if_dir "/bin"
+
+  if [ -z "\${VOLTA_HOME:-}" ]; then
+    VOLTA_HOME="$HOME/.volta"
+  fi
+  export VOLTA_HOME
+  prepend_path_if_dir "$VOLTA_HOME/bin"
+
+  prepend_path_if_dir "$HOME/.asdf/shims"
+  prepend_path_if_dir "$HOME/.asdf/bin"
+  if [ ! -x "$HOME/.asdf/shims/node" ] && [ -s "$HOME/.asdf/asdf.sh" ]; then
+    # shellcheck disable=SC1090
+    . "$HOME/.asdf/asdf.sh"
+  fi
+
+  prepend_path_if_dir "$HOME/.local/share/mise/shims"
+  prepend_path_if_dir "$HOME/.mise/shims"
+  if ! command -v node >/dev/null 2>&1 && command -v mise >/dev/null 2>&1; then
+    eval "$(mise activate sh)" >/dev/null 2>&1 || true
+  fi
+
+  if [ -z "\${FNM_DIR:-}" ]; then
+    FNM_DIR="$HOME/.local/share/fnm"
+  fi
+  export FNM_DIR
+  prepend_path_if_dir "$FNM_DIR"
+  prepend_path_if_dir "$HOME/.fnm"
+  if ! command -v node >/dev/null 2>&1 && command -v fnm >/dev/null 2>&1; then
+    eval "$(fnm env --use-on-cd --shell sh)" >/dev/null 2>&1 || eval "$(fnm env --shell sh)" >/dev/null 2>&1 || true
+  fi
+
+  prepend_path_if_dir "$HOME/.nodenv/bin"
+  prepend_path_if_dir "$HOME/.nodenv/shims"
+  if ! command -v node >/dev/null 2>&1 && command -v nodenv >/dev/null 2>&1; then
+    eval "$(nodenv init -)" >/dev/null 2>&1 || true
+  fi
+
+  if [ -z "\${NVM_DIR:-}" ]; then
+    NVM_DIR="$HOME/.nvm"
+  fi
+  export NVM_DIR
+
+  if [ -s "$NVM_DIR/nvm.sh" ]; then
+    # shellcheck disable=SC1090
+    . "$NVM_DIR/nvm.sh"
+    if ! command -v node >/dev/null 2>&1 && command -v nvm >/dev/null 2>&1; then
+      nvm use --silent default >/dev/null 2>&1 || nvm use --silent node >/dev/null 2>&1 || nvm use --silent --lts >/dev/null 2>&1 || true
+    fi
+  fi
+
+  if ! command -v node >/dev/null 2>&1 && [ -d "$NVM_DIR/versions/node" ]; then
+    for T3_NODE_BIN in "$NVM_DIR"/versions/node/*/bin; do
+      if [ -x "$T3_NODE_BIN/node" ]; then
+        PATH="$T3_NODE_BIN:$PATH"
+        export PATH
+      fi
+    done
+  fi
+
+  command -v node >/dev/null 2>&1 && remote_node_satisfies_engine
+}
+`;
+
+export const REMOTE_RUNNER_SCRIPT = `#!/bin/sh
+set -eu
+@@T3_NODE_ENV_SCRIPT@@
+ensure_remote_node_path || true
+T3_NODE_SCRIPT_PATH=@@T3_NODE_SCRIPT_PATH@@
+if [ -n "$T3_NODE_SCRIPT_PATH" ]; then
+  if ! command -v node >/dev/null 2>&1; then
+    printf 'Remote host is missing node on PATH. Install Node or configure a supported version manager for non-interactive shells.\\n' >&2
+    exit 1
+  fi
+  exec node "$T3_NODE_SCRIPT_PATH" "$@"
+fi
+if command -v t3 >/dev/null 2>&1; then
+  exec t3 "$@"
+fi
+if command -v npx >/dev/null 2>&1; then
+  exec npx --yes @@T3_PACKAGE_SPEC@@ "$@"
+fi
+if command -v npm >/dev/null 2>&1; then
+  exec npm exec --yes @@T3_PACKAGE_SPEC@@ -- "$@"
+fi
+printf 'Remote host is missing the t3 CLI and could not install @@T3_PACKAGE_SPEC@@ because node/npm/npx are unavailable on PATH. Install Node or configure a supported version manager for non-interactive shells.\\n' >&2
+exit 1
+`;
+
+export const REMOTE_LAUNCH_SCRIPT = `set -eu
+@@T3_NODE_ENV_SCRIPT@@
+STATE_KEY="$1"
+STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
+DEFAULT_SERVER_HOME="$HOME/.t3"
+DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"
+PORT_FILE="$STATE_DIR/port"
+PID_FILE="$STATE_DIR/pid"
+MANAGED_FILE="$STATE_DIR/managed"
+LOG_FILE="$STATE_DIR/server.log"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+RUNNER_NEXT="$STATE_DIR/run-t3.next.$$"
+mkdir -p "$STATE_DIR"
+cleanup_runner_next() {
+  rm -f "$RUNNER_NEXT"
+}
+trap cleanup_runner_next EXIT
+cat >"$RUNNER_NEXT" <<'SH'
+@@T3_RUNNER_SCRIPT@@
+SH
+RUNNER_CHANGED=0
+if [ ! -f "$RUNNER_FILE" ] || ! cmp -s "$RUNNER_NEXT" "$RUNNER_FILE"; then
+  RUNNER_CHANGED=1
+fi
+mv "$RUNNER_NEXT" "$RUNNER_FILE"
+chmod 700 "$RUNNER_FILE"
+if ! ensure_remote_node_path; then
+  printf 'Remote host is missing node on PATH. Install Node or configure a supported version manager for non-interactive shells.\\n' >&2
+  exit 1
+fi
+pick_port() {
+  node - "$PORT_FILE" "@@T3_DEFAULT_REMOTE_PORT@@" "@@T3_REMOTE_PORT_SCAN_WINDOW@@" <<'NODE'
+@@T3_PICK_PORT_SCRIPT@@
+NODE
+}
+wait_ready() {
+  node - "$REMOTE_PORT" "$1" "@@T3_READY_PROBE_TIMEOUT_MS@@" <<'NODE'
+@@T3_WAIT_READY_SCRIPT@@
+NODE
+}
+wait_for_pid_exit() {
+  PID_TO_WAIT="$1"
+  WAIT_COUNT=0
+  while kill -0 "$PID_TO_WAIT" 2>/dev/null && [ "$WAIT_COUNT" -lt 20 ]; do
+    WAIT_COUNT=$((WAIT_COUNT + 1))
+    sleep 0.1
+  done
+}
+resolve_default_runtime_port() {
+  node - "$DEFAULT_RUNTIME_FILE" <<'NODE'
+const fs = require("node:fs");
+const runtimePath = process.argv[2] ?? "";
+try {
+	  const runtime = JSON.parse(fs.readFileSync(runtimePath, "utf8"));
+	  const pid = Number(runtime.pid);
+	  const port = Number(runtime.port);
+	  if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(port)) {
+	    process.exit(1);
+	  }
+  const origin = new URL(String(runtime.origin ?? ""));
+  if (origin.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(origin.hostname)) {
+    process.exit(1);
+  }
+  process.kill(pid, 0);
+  process.stdout.write(\`\${pid} \${port}\`);
+} catch {
+  process.exit(1);
+}
+NODE
+}
+REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
+REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
+DEFAULT_RUNTIME_INFO="$(resolve_default_runtime_port 2>/dev/null || true)"
+DEFAULT_RUNTIME_PID=""
+DEFAULT_REMOTE_PORT=""
+if [ -n "$DEFAULT_RUNTIME_INFO" ]; then
+  DEFAULT_RUNTIME_PID="\${DEFAULT_RUNTIME_INFO%% *}"
+  DEFAULT_REMOTE_PORT="\${DEFAULT_RUNTIME_INFO#* }"
+fi
+if [ -n "$DEFAULT_REMOTE_PORT" ]; then
+  REMOTE_PORT="$DEFAULT_REMOTE_PORT"
+  if wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    if [ "$REMOTE_MANAGED" = "managed" ]; then
+      PID_TO_STOP="\${REMOTE_PID:-$DEFAULT_RUNTIME_PID}"
+      if [ -n "$PID_TO_STOP" ] && kill -0 "$PID_TO_STOP" 2>/dev/null; then
+        kill "$PID_TO_STOP" 2>/dev/null || true
+        wait_for_pid_exit "$PID_TO_STOP"
+      fi
+      REMOTE_PID=""
+      REMOTE_PORT="$DEFAULT_REMOTE_PORT"
+      REMOTE_MANAGED="external"
+      rm -f "$PID_FILE"
+      printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+      printf 'external\\n' >"$MANAGED_FILE"
+    else
+      printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+      printf 'external\\n' >"$MANAGED_FILE"
+      REMOTE_PID=""
+      REMOTE_MANAGED="external"
+    fi
+  else
+    REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+    REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
+    REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
+  fi
+fi
+if [ "$REMOTE_MANAGED" = "external" ]; then
+  if [ -z "$REMOTE_PORT" ] || ! wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    REMOTE_PID=""
+    REMOTE_PORT=""
+    REMOTE_MANAGED=""
+  fi
+elif [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+  if [ "$RUNNER_CHANGED" -eq 1 ]; then
+    kill "$REMOTE_PID" 2>/dev/null || true
+    wait_for_pid_exit "$REMOTE_PID"
+    REMOTE_PID=""
+    REMOTE_PORT=""
+    REMOTE_MANAGED=""
+  elif ! wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    kill "$REMOTE_PID" 2>/dev/null || true
+    wait_for_pid_exit "$REMOTE_PID"
+    REMOTE_PID=""
+    REMOTE_PORT=""
+    REMOTE_MANAGED=""
+  fi
+else
+  REMOTE_PID=""
+  REMOTE_PORT=""
+  REMOTE_MANAGED=""
+fi
+if [ -z "$REMOTE_PORT" ]; then
+  REMOTE_PORT="$(pick_port)" || true
+  if [ -z "$REMOTE_PORT" ]; then
+    printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\\n' >&2
+    exit 1
+  fi
+  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$DEFAULT_SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
+  REMOTE_PID="$!"
+  printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
+  printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+  printf 'managed\\n' >"$MANAGED_FILE"
+  if ! wait_ready "@@T3_READY_TIMEOUT_MS@@"; then
+    printf 'Remote T3 server did not become ready on 127.0.0.1:%s.\\n' "$REMOTE_PORT" >&2
+    tail -n 80 "$LOG_FILE" >&2 2>/dev/null || true
+    kill "$REMOTE_PID" 2>/dev/null || true
+    wait_for_pid_exit "$REMOTE_PID"
+    rm -f "$PID_FILE" "$PORT_FILE" "$MANAGED_FILE"
+    exit 1
+  fi
+fi
+printf '{"remotePort":%s,"serverKind":"%s"}\\n' "$REMOTE_PORT" "\${REMOTE_MANAGED:-managed}"
+`;
+
+export const REMOTE_PAIRING_SCRIPT = `set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+DEFAULT_SERVER_HOME="$HOME/.t3"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR"
+cat >"$RUNNER_FILE" <<'SH'
+@@T3_RUNNER_SCRIPT@@
+SH
+chmod 700 "$RUNNER_FILE"
+PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"
+"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json
+`;
+
+export const REMOTE_STOP_SCRIPT = `set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+PID_FILE="$STATE_DIR/pid"
+PORT_FILE="$STATE_DIR/port"
+MANAGED_FILE="$STATE_DIR/managed"
+REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
+REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+  kill "$REMOTE_PID" 2>/dev/null || true
+  WAIT_COUNT=0
+  while kill -0 "$REMOTE_PID" 2>/dev/null && [ "$WAIT_COUNT" -lt 20 ]; do
+    WAIT_COUNT=$((WAIT_COUNT + 1))
+    sleep 0.1
+  done
+fi
+rm -f "$PID_FILE" "$PORT_FILE" "$MANAGED_FILE"
+printf '{"stopped":true}\\n'
+`;
+
+const REMOTE_LOG_TAIL_SCRIPT = `set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+LOG_FILE="$STATE_DIR/server.log"
+if [ -f "$LOG_FILE" ]; then
+  tail -n 80 "$LOG_FILE" 2>/dev/null || true
+fi
+`;
+
+export function buildRemoteT3RunnerScript(input?: RemoteT3RunnerOptions): string {
+  const packageSpec = shellSingleQuote(input?.packageSpec?.trim() || "t3@latest");
+  const nodeScriptPath = input?.nodeScriptPath?.trim() || "";
+  return stripTrailingNewlines(
+    applyScriptPlaceholders(REMOTE_RUNNER_SCRIPT, {
+      T3_PACKAGE_SPEC: packageSpec,
+      T3_NODE_SCRIPT_PATH: shellSingleQuote(nodeScriptPath),
+      T3_NODE_ENV_SCRIPT: buildRemoteNodeEnvScript(input),
+    }),
+  );
+}
+
+function buildRemoteNodeEnvScript(input?: RemoteT3RunnerOptions): string {
+  return stripTrailingNewlines(
+    applyScriptPlaceholders(REMOTE_NODE_ENV_SCRIPT, {
+      T3_NODE_ENGINE_RANGE: shellSingleQuote(input?.nodeEngineRange?.trim() || ""),
+      T3_NODE_ENGINE_CHECK_SCRIPT: stripTrailingNewlines(buildRemoteNodeEngineCheckScript()),
+    }),
+  );
+}
+
+export function buildRemoteLaunchScript(input?: RemoteT3RunnerOptions): string {
+  return applyScriptPlaceholders(REMOTE_LAUNCH_SCRIPT, {
+    T3_NODE_ENV_SCRIPT: buildRemoteNodeEnvScript(input),
+    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
+    T3_PICK_PORT_SCRIPT: stripTrailingNewlines(REMOTE_PICK_PORT_SCRIPT),
+    T3_WAIT_READY_SCRIPT: stripTrailingNewlines(REMOTE_WAIT_READY_SCRIPT),
+    T3_DEFAULT_REMOTE_PORT: String(DEFAULT_REMOTE_PORT),
+    T3_REMOTE_PORT_SCAN_WINDOW: String(REMOTE_PORT_SCAN_WINDOW),
+    T3_READY_TIMEOUT_MS: String(REMOTE_READY_TIMEOUT_MS),
+    T3_REUSE_READY_TIMEOUT_MS: String(REMOTE_REUSE_READY_TIMEOUT_MS),
+    T3_READY_PROBE_TIMEOUT_MS: String(SSH_READY_PROBE_TIMEOUT_MS),
+  });
+}
+
+export function buildRemotePairingScript(
+  target: DesktopSshEnvironmentTarget,
+  input?: RemoteT3RunnerOptions,
+): string {
+  return applyScriptPlaceholders(REMOTE_PAIRING_SCRIPT, {
+    T3_STATE_KEY: remoteStateKey(target),
+    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
+  });
+}
+
+export function buildRemoteStopScript(target: DesktopSshEnvironmentTarget): string {
+  return applyScriptPlaceholders(REMOTE_STOP_SCRIPT, {
+    T3_STATE_KEY: remoteStateKey(target),
+  });
+}
+
+function buildRemoteLogTailScript(target: DesktopSshEnvironmentTarget): string {
+  return applyScriptPlaceholders(REMOTE_LOG_TAIL_SCRIPT, {
+    T3_STATE_KEY: remoteStateKey(target),
+  });
+}
+
+export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemoteServer")(
+  function* (
+    target: DesktopSshEnvironmentTarget,
+    input?: SshAuthOptions,
+    runner?: RemoteT3RunnerOptions,
+  ): Effect.fn.Return<
+    { readonly remotePort: number; readonly remoteServerKind: "external" | "managed" | null },
+    SshCommandError | SshInvalidTargetError | SshLaunchError,
+    ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+  > {
+    yield* Effect.logInfo("ssh.remoteServer.launch.start", {
+      ...sshTargetLogFields(target),
+      ...sshRunnerLogFields(runner),
+      stateKey: remoteStateKey(target),
+    });
+    const result = yield* runSshCommand(target, {
+      remoteCommandArgs: ["sh", "-s", "--", remoteStateKey(target)],
+      stdin: buildRemoteLaunchScript(runner),
+      ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+      ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+      ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+    });
+    if (!getLastNonEmptyOutputLine(result.stdout)) {
+      return yield* new SshLaunchError({
+        message: "SSH launch did not return a remote port.",
+        stdout: result.stdout,
+      });
+    }
+    const parsed = yield* decodeRemoteLaunchOutput(result.stdout).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SshLaunchError({
+            message: "SSH launch returned unparseable output.",
+            stdout: result.stdout,
+            cause,
+          }),
+      ),
+    );
+    if (!Number.isInteger(parsed.remotePort)) {
+      return yield* new SshLaunchError({
+        message: `SSH launch returned an invalid remote port: ${String(parsed.remotePort)}.`,
+        stdout: result.stdout,
+      });
+    }
+    yield* Effect.logInfo("ssh.remoteServer.launch.ready", {
+      ...sshTargetLogFields(target),
+      remotePort: parsed.remotePort,
+      remoteServerKind: parsed.serverKind ?? null,
+      stateKey: remoteStateKey(target),
+    });
+    return {
+      remotePort: parsed.remotePort,
+      remoteServerKind: parsed.serverKind ?? null,
+    };
+  },
+);
+
+export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingToken")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+  runner?: RemoteT3RunnerOptions,
+): Effect.fn.Return<
+  {
+    readonly credential: string;
+  },
+  SshCommandError | SshInvalidTargetError | SshPairingError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  yield* Effect.logDebug("ssh.remoteServer.pairingToken.start", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
+  const result = yield* runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s"],
+    stdin: buildRemotePairingScript(target, runner),
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+  if (!getLastNonEmptyOutputLine(result.stdout)) {
+    return yield* new SshPairingError({
+      message: "SSH pairing did not return a credential.",
+      stdout: result.stdout,
+    });
+  }
+  const parsed = yield* decodeRemotePairingOutput(result.stdout).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshPairingError({
+          message: "SSH pairing returned unparseable output.",
+          stdout: result.stdout,
+          cause,
+        }),
+    ),
+  );
+  if (parsed.credential.trim().length === 0) {
+    return yield* new SshPairingError({
+      message: "SSH pairing command returned an invalid credential.",
+      stdout: result.stdout,
+    });
+  }
+  yield* Effect.logDebug("ssh.remoteServer.pairingToken.created", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
+  return {
+    credential: parsed.credential,
+  };
+});
+
+export const stopRemoteServer = Effect.fn("ssh/tunnel.stopRemoteServer")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+): Effect.fn.Return<
+  void,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  yield* Effect.logInfo("ssh.remoteServer.stop.start", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
+  yield* runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s"],
+    stdin: buildRemoteStopScript(target),
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+  yield* Effect.logInfo("ssh.remoteServer.stop.succeeded", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
+});
+
+const readRemoteServerLogTail = Effect.fn("ssh/tunnel.readRemoteServerLogTail")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+): Effect.fn.Return<
+  string,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const result = yield* runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s"],
+    stdin: buildRemoteLogTailScript(target),
+    timeoutMs: 10_000,
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+  return result.stdout.trim();
+});
+
+export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(function* (input: {
+  readonly baseUrl: string;
+  readonly timeoutMs?: number;
+  readonly intervalMs?: number;
+  readonly probeTimeoutMs?: number;
+  readonly path?: string;
+}): Effect.fn.Return<void, SshReadinessError, HttpClient.HttpClient> {
+  const timeoutMs = input.timeoutMs ?? 30_000;
+  const intervalMs = input.intervalMs ?? 100;
+  const probeTimeoutMs = input.probeTimeoutMs ?? SSH_READY_PROBE_TIMEOUT_MS;
+  const retryPolicy = Schedule.spaced(Duration.millis(intervalMs)).pipe(
+    Schedule.take(Math.max(0, Math.ceil(timeoutMs / intervalMs))),
+  );
+  const requestUrl = new URL(input.path ?? "/", input.baseUrl).toString();
+  const client = yield* HttpClient.HttpClient;
+  const lastProbeFailure = yield* Ref.make<unknown>(null);
+  let attempt = 0;
+
+  yield* Effect.logDebug("ssh.tunnel.httpReady.start", {
+    baseUrl: input.baseUrl,
+    requestUrl,
+    timeoutMs,
+    intervalMs,
+    probeTimeoutMs,
+  });
+
+  const readinessClient = client.pipe(
+    HttpClient.filterStatusOk,
+    HttpClient.transform((effect) =>
+      Effect.gen(function* () {
+        attempt += 1;
+        const responseOption = yield* effect.pipe(
+          Effect.timeoutOption(Duration.millis(probeTimeoutMs)),
+          Effect.mapError(
+            (cause) =>
+              new SshReadinessError({
+                message: `Backend readiness probe failed at ${requestUrl}.`,
+                cause,
+              }),
+          ),
+        );
+        return yield* Option.match(responseOption, {
+          onSome: Effect.succeed,
+          onNone: () =>
+            Effect.fail(
+              new SshReadinessError({
+                message: `Backend readiness probe exceeded ${probeTimeoutMs}ms at ${requestUrl}.`,
+                cause: {
+                  kind: "probe-timeout",
+                  attempt,
+                  probeTimeoutMs,
+                },
+              }),
+            ),
+        });
+      }).pipe(
+        Effect.mapError((cause) =>
+          cause instanceof SshReadinessError
+            ? cause
+            : new SshReadinessError({
+                message: `Backend readiness probe failed at ${requestUrl}.`,
+                cause,
+              }),
+        ),
+        Effect.tapError((cause) =>
+          Ref.set(lastProbeFailure, {
+            attempt,
+            cause: describeReadinessCause(cause),
+          }),
+        ),
+      ),
+    ),
+    HttpClient.tap((response) => response.text.pipe(Effect.ignore)),
+    HttpClient.retry(retryPolicy),
+  );
+
+  const result = yield* readinessClient.execute(HttpClientRequest.get(requestUrl)).pipe(
+    Effect.mapError((cause) =>
+      cause instanceof SshReadinessError
+        ? cause
+        : new SshReadinessError({
+            message: `Backend readiness probe failed at ${requestUrl}.`,
+            cause,
+          }),
+    ),
+    Effect.timeoutOption(Duration.millis(timeoutMs)),
+  );
+
+  return yield* Option.match(result, {
+    onSome: () =>
+      Effect.logDebug("ssh.tunnel.httpReady.succeeded", {
+        baseUrl: input.baseUrl,
+        requestUrl,
+        attempts: attempt,
+      }),
+    onNone: () =>
+      Effect.gen(function* () {
+        const lastFailure = yield* Ref.get(lastProbeFailure);
+        yield* Effect.logWarning("ssh.tunnel.httpReady.timedOut", {
+          baseUrl: input.baseUrl,
+          requestUrl,
+          timeoutMs,
+          intervalMs,
+          probeTimeoutMs,
+          attempts: attempt,
+          lastFailure,
+        });
+        return yield* new SshReadinessError({
+          message: `Timed out waiting ${timeoutMs}ms for backend readiness at ${input.baseUrl}.`,
+          cause: lastFailure,
+        });
+      }),
+  });
+});
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname
+    .trim()
+    .toLowerCase()
+    .replace(/^\[(.*)\]$/, "$1");
+  return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
+}
+
+function resolveLoopbackSshHttpUrl(
+  rawHttpBaseUrl: unknown,
+  pathname: string,
+): Effect.Effect<URL, SshHttpBridgeError> {
+  return Effect.try({
+    try: () => {
+      if (typeof rawHttpBaseUrl !== "string" || rawHttpBaseUrl.trim().length === 0) {
+        throw new Error("Invalid SSH forwarded http base URL.");
+      }
+      const baseUrl = new URL(rawHttpBaseUrl);
+      if (!isLoopbackHostname(baseUrl.hostname)) {
+        throw new Error("SSH desktop bridge only supports loopback forwarded URLs.");
+      }
+      const url = new URL(baseUrl.toString());
+      url.pathname = pathname;
+      url.search = "";
+      url.hash = "";
+      return url;
+    },
+    catch: (cause) =>
+      new SshHttpBridgeError({
+        message: cause instanceof Error ? cause.message : "Invalid SSH forwarded http base URL.",
+        cause,
+      }),
+  });
+}
+
+export const fetchLoopbackSshJson = Effect.fn("ssh/tunnel.fetchLoopbackSshJson")(function* <
+  T,
+>(input: {
+  readonly httpBaseUrl: unknown;
+  readonly pathname: string;
+  readonly method?: "GET" | "POST";
+  readonly bearerToken?: unknown;
+  readonly body?: unknown;
+}): Effect.fn.Return<T, SshHttpBridgeError, HttpClient.HttpClient> {
+  const requestUrl = yield* resolveLoopbackSshHttpUrl(input.httpBaseUrl, input.pathname);
+  const bearerToken =
+    typeof input.bearerToken === "string" && input.bearerToken.trim().length > 0
+      ? input.bearerToken
+      : null;
+
+  const request = (
+    input.method === "POST"
+      ? HttpClientRequest.post(requestUrl.toString())
+      : HttpClientRequest.get(requestUrl.toString())
+  ).pipe(
+    input.body === undefined ? (req) => req : HttpClientRequest.bodyJsonUnsafe(input.body),
+    bearerToken
+      ? HttpClientRequest.setHeader("authorization", `Bearer ${bearerToken}`)
+      : (req) => req,
+  );
+  const client = yield* HttpClient.HttpClient;
+  const response = yield* client.execute(request).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshHttpBridgeError({
+          message: `Failed to reach SSH forwarded endpoint ${requestUrl.toString()}.`,
+          cause,
+        }),
+    ),
+  );
+  if (response.status < 200 || response.status >= 300) {
+    const text = yield* response.text.pipe(Effect.catch(() => Effect.succeed("")));
+    const parsedError = yield* decodeRemoteHttpError(text).pipe(
+      Effect.catch(() => Effect.succeed(null)),
+    );
+    const message =
+      parsedError?.error && parsedError.error.trim().length > 0
+        ? parsedError.error
+        : text || `SSH forwarded request failed (${response.status}).`;
+    return yield* new SshHttpBridgeError({
+      status: response.status,
+      message: `[ssh_http:${response.status}] ${message} (${input.method ?? "GET"} ${requestUrl.toString()})`,
+    });
+  }
+  return (yield* response.json.pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshHttpBridgeError({
+          message: `SSH forwarded endpoint ${requestUrl.toString()} returned invalid JSON.`,
+          cause,
+        }),
+    ),
+  )) as T;
+});
+
+const reserveLocalTunnelPort = Effect.fn("ssh/tunnel.reserveLocalTunnelPort")(function* () {
+  const net = yield* NetService.NetService;
+  return yield* net.reserveLoopbackPort();
+});
+
+const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input: {
+  readonly key: string;
+  readonly resolvedTarget: DesktopSshEnvironmentTarget;
+  readonly remotePort: number;
+  readonly localPort: number;
+  readonly httpBaseUrl: string;
+  readonly wsBaseUrl: string;
+  readonly authOptions: SshAuthOptions;
+  readonly remoteServerKind: "external" | "managed" | null;
+}): Effect.fn.Return<
+  SshTunnelEntry,
+  SshCommandError | SshInvalidTargetError | SshReadinessError,
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | HttpClient.HttpClient
+  | NetService.NetService
+  | Scope.Scope
+> {
+  const hostSpec = yield* buildSshHostSpecEffect(input.resolvedTarget);
+  const childEnvironment = yield* buildSshChildEnvironment({
+    ...(input.authOptions.authSecret === undefined
+      ? {}
+      : { authSecret: input.authOptions.authSecret }),
+    ...(input.authOptions.interactiveAuth === undefined
+      ? {}
+      : { interactiveAuth: input.authOptions.interactiveAuth }),
+  }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: ["ssh"],
+          exitCode: null,
+          stderr: "",
+          message: "Failed to prepare SSH authentication helpers.",
+          cause,
+        }),
+    ),
+  );
+  const args = [
+    ...baseSshArgs(input.resolvedTarget, {
+      batchMode: input.authOptions.batchMode ?? "no",
+    }),
+    "-o",
+    "ExitOnForwardFailure=yes",
+    "-o",
+    "ServerAliveInterval=15",
+    "-o",
+    "ServerAliveCountMax=3",
+    "-n",
+    "-N",
+    "-L",
+    `${input.localPort}:127.0.0.1:${input.remotePort}`,
+    hostSpec,
+  ];
+  const tunnelCommand = ["ssh", ...args];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const scope = yield* Scope.Scope;
+  yield* Effect.logDebug("ssh.tunnel.spawn.start", {
+    ...sshTargetLogFields(input.resolvedTarget),
+    command: tunnelCommand,
+    localPort: input.localPort,
+    remotePort: input.remotePort,
+    remoteServerKind: input.remoteServerKind,
+    httpBaseUrl: input.httpBaseUrl,
+  });
+  const child = yield* spawner
+    .spawn(
+      ChildProcess.make("ssh", args, {
+        env: childEnvironment,
+        shell: process.platform === "win32",
+        stdin: {
+          stream: Stream.empty,
+          endOnDone: true,
+        },
+      }),
+    )
+    .pipe(
+      Effect.mapError(
+        (cause) =>
+          new SshCommandError({
+            command: tunnelCommand,
+            exitCode: null,
+            stderr: "",
+            message:
+              cause instanceof Error
+                ? cause.message
+                : `Failed to spawn SSH tunnel for ${input.resolvedTarget.alias}.`,
+            cause,
+          }),
+      ),
+    );
+  yield* Effect.logDebug("ssh.tunnel.spawn.succeeded", {
+    ...sshTargetLogFields(input.resolvedTarget),
+    command: tunnelCommand,
+    pid: child.pid,
+    localPort: input.localPort,
+    remotePort: input.remotePort,
+    httpBaseUrl: input.httpBaseUrl,
+  });
+  const tunnelEntry: SshTunnelEntry = {
+    key: input.key,
+    target: input.resolvedTarget,
+    remotePort: input.remotePort,
+    remoteServerKind: input.remoteServerKind,
+    localPort: input.localPort,
+    httpBaseUrl: input.httpBaseUrl,
+    wsBaseUrl: input.wsBaseUrl,
+    process: child,
+    scope,
+  };
+  const exitFailure = Effect.all(
+    [collectProcessOutput(child.stderr), child.exitCode.pipe(Effect.map(Number))],
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: tunnelCommand,
+          exitCode: null,
+          stderr: "",
+          message:
+            cause instanceof Error
+              ? cause.message
+              : `Failed to monitor SSH tunnel for ${input.resolvedTarget.alias}.`,
+          cause,
+        }),
+    ),
+    Effect.flatMap(([stderr, exitCode]) => {
+      const error = new SshCommandError({
+        command: tunnelCommand,
+        exitCode,
+        stderr,
+        message: normalizeSshErrorMessage(
+          stderr,
+          `SSH tunnel exited unexpectedly for ${input.resolvedTarget.alias} (exit ${exitCode}).`,
+        ),
+      });
+      return Effect.logWarning("ssh.tunnel.process.exited", {
+        ...sshTargetLogFields(input.resolvedTarget),
+        command: tunnelCommand,
+        pid: child.pid,
+        localPort: input.localPort,
+        remotePort: input.remotePort,
+        httpBaseUrl: input.httpBaseUrl,
+        exitCode,
+        stderr,
+      }).pipe(Effect.andThen(Effect.fail(error)));
+    }),
+  );
+  yield* Effect.raceFirst(
+    waitForHttpReady({
+      baseUrl: input.httpBaseUrl,
+      timeoutMs: SSH_READY_TIMEOUT_MS,
+    }),
+    exitFailure,
+  ).pipe(
+    Effect.tap(() =>
+      Effect.logInfo("ssh.tunnel.ready", {
+        ...sshTargetLogFields(input.resolvedTarget),
+        command: tunnelCommand,
+        pid: child.pid,
+        localPort: input.localPort,
+        remotePort: input.remotePort,
+        httpBaseUrl: input.httpBaseUrl,
+      }),
+    ),
+    Effect.tapError((cause) =>
+      Effect.gen(function* () {
+        const net = yield* NetService.NetService;
+        const processRunningExit = yield* Effect.exit(child.isRunning);
+        const localPortAvailableExit = yield* Effect.exit(
+          net.canListenOnHost(input.localPort, "127.0.0.1"),
+        );
+        const remoteLogTailExit = yield* Effect.exit(
+          readRemoteServerLogTail(input.resolvedTarget, input.authOptions),
+        );
+        const processRunning = Exit.isSuccess(processRunningExit) ? processRunningExit.value : null;
+        const localPortAvailable = Exit.isSuccess(localPortAvailableExit)
+          ? localPortAvailableExit.value
+          : null;
+        const remoteLogTail = Exit.isSuccess(remoteLogTailExit)
+          ? remoteLogTailExit.value || null
+          : null;
+        yield* Effect.logWarning("ssh.tunnel.ready.failed", {
+          ...sshTargetLogFields(input.resolvedTarget),
+          command: tunnelCommand,
+          pid: child.pid,
+          processRunning,
+          ...(Exit.isSuccess(processRunningExit)
+            ? {}
+            : { processRunningError: processRunningExit.cause }),
+          localPort: input.localPort,
+          localPortListening: localPortAvailable === null ? null : !localPortAvailable,
+          remotePort: input.remotePort,
+          httpBaseUrl: input.httpBaseUrl,
+          ...(Exit.isSuccess(localPortAvailableExit)
+            ? {}
+            : { localPortProbeError: localPortAvailableExit.cause }),
+          ...(remoteLogTail === null ? {} : { remoteLogTail }),
+          ...(Exit.isSuccess(remoteLogTailExit)
+            ? {}
+            : { remoteLogTailError: remoteLogTailExit.cause }),
+          cause,
+        });
+      }),
+    ),
+    Effect.onExit((exit) =>
+      Exit.isSuccess(exit)
+        ? Effect.void
+        : child
+            .kill({
+              killSignal: "SIGTERM",
+              forceKillAfter: TUNNEL_SHUTDOWN_TIMEOUT_MS,
+            })
+            .pipe(Effect.ignore),
+    ),
+  );
+  return tunnelEntry;
+});
+
+const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.make")(function* (
+  options: SshEnvironmentManagerOptions = {},
+): Effect.fn.Return<SshEnvironmentManagerShape, never, Scope.Scope> {
+  const managerScope = yield* Scope.Scope;
+  const tunnels = new Map<string, SshTunnelEntry>();
+  const pendingTunnelEntries = new Map<
+    string,
+    Deferred.Deferred<SshTunnelEntry, SshEnvironmentEffectError>
+  >();
+  const authSecrets = new Map<string, string>();
+
+  const closeTunnelEntry = Effect.fn("ssh/tunnel.closeTunnelEntry")(function* (
+    entry: SshTunnelEntry,
+  ) {
+    yield* Effect.logDebug("ssh.tunnel.close.start", {
+      ...sshTargetLogFields(entry.target),
+      key: entry.key,
+      localPort: entry.localPort,
+      remotePort: entry.remotePort,
+    });
+    yield* Scope.close(entry.scope, Exit.void).pipe(Effect.ignore);
+    yield* Effect.logInfo("ssh.tunnel.close.succeeded", {
+      ...sshTargetLogFields(entry.target),
+      key: entry.key,
+      localPort: entry.localPort,
+      remotePort: entry.remotePort,
+    });
+  });
+
+  const cancelPendingTunnelEntry = Effect.fn("ssh/tunnel.cancelPendingTunnelEntry")(function* (
+    key: string,
+    target: DesktopSshEnvironmentTarget,
+  ) {
+    const pending = pendingTunnelEntries.get(key);
+    if (!pending) {
+      return;
+    }
+    pendingTunnelEntries.delete(key);
+    yield* Deferred.fail(pending, makeSshTunnelCancelledError(target)).pipe(Effect.ignore);
+  });
+
+  yield* Scope.addFinalizer(
+    managerScope,
+    Effect.sync(() => [...tunnels.values()]).pipe(
+      Effect.flatMap((entries) =>
+        Effect.forEach(entries, closeTunnelEntry, { concurrency: "unbounded" }),
+      ),
+      Effect.ignore,
+    ),
+  );
+
+  const promptForPassword = Effect.fn("ssh/tunnel.promptForPassword")(function* (
+    target: DesktopSshEnvironmentTarget,
+    attempt: number,
+  ): Effect.fn.Return<string, SshInvalidTargetError | SshPasswordPromptError, SshPasswordPrompt> {
+    const promptService = yield* SshPasswordPrompt;
+    const hostSpec = yield* buildSshHostSpecEffect(target);
+    if (!promptService.isAvailable) {
+      yield* Effect.logWarning("ssh.auth.passwordPrompt.unavailable", {
+        ...sshTargetLogFields(target),
+        attempt,
+      });
+      return yield* new SshPasswordPromptError({
+        message: `SSH authentication failed for ${hostSpec}.`,
+      });
+    }
+
+    yield* Effect.logInfo("ssh.auth.passwordPrompt.request", {
+      ...sshTargetLogFields(target),
+      attempt,
+    });
+    const password = yield* promptService.request({
+      attempt,
+      destination: target.alias.trim() || target.hostname.trim(),
+      username: target.username,
+      prompt: `Enter the SSH password for ${hostSpec}.`,
+    });
+    if (password === null) {
+      yield* Effect.logWarning("ssh.auth.passwordPrompt.cancelled", {
+        ...sshTargetLogFields(target),
+        attempt,
+      });
+      return yield* new SshPasswordPromptError({
+        message: `SSH authentication cancelled for ${hostSpec}.`,
+      });
+    }
+    yield* Effect.logInfo("ssh.auth.passwordPrompt.received", {
+      ...sshTargetLogFields(target),
+      attempt,
+    });
+    return password;
+  });
+
+  const handleSshAuthFailure = Effect.fn("ssh/tunnel.runWithSshAuthAttempt.handleFailure")(
+    function* <T>(
+      input: SshAuthAttemptInput<T> & {
+        readonly error: SshEnvironmentEffectError;
+      },
+    ): Effect.fn.Return<T, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+      if (!isSshAuthFailure(input.error)) {
+        return yield* input.error;
+      }
+
+      yield* Effect.logWarning("ssh.auth.failed", {
+        ...sshTargetLogFields(input.target),
+        key: input.key,
+        promptCount: input.promptCount,
+        cause: input.error,
+      });
+      const promptService = yield* SshPasswordPrompt;
+      if (!promptService.isAvailable) {
+        return yield* input.error;
+      }
+      if (input.authSecret !== null) {
+        authSecrets.delete(input.key);
+      }
+      if (input.promptCount >= 2) {
+        return yield* input.error;
+      }
+
+      const nextPromptCount = input.promptCount + 1;
+      const nextAuthSecret = yield* promptForPassword(input.target, nextPromptCount);
+      authSecrets.set(input.key, nextAuthSecret);
+      return yield* runWithSshAuthAttempt({
+        ...input,
+        promptCount: nextPromptCount,
+        authSecret: nextAuthSecret,
+      });
+    },
+  );
+
+  const runWithSshAuthAttempt = Effect.fn("ssh/tunnel.runWithSshAuthAttempt")(function* <T>(
+    input: SshAuthAttemptInput<T>,
+  ): Effect.fn.Return<T, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    const promptService = yield* SshPasswordPrompt;
+    const authOptions =
+      input.authSecret === null
+        ? {
+            batchMode: promptService.isAvailable ? ("yes" as const) : ("no" as const),
+            interactiveAuth: !promptService.isAvailable,
+          }
+        : {
+            authSecret: input.authSecret,
+            batchMode: "no" as const,
+            interactiveAuth: true,
+          };
+
+    return yield* input
+      .operation(authOptions)
+      .pipe(Effect.catch((error) => handleSshAuthFailure({ ...input, error })));
+  });
+
+  const runWithSshAuth = Effect.fn("ssh/tunnel.runWithSshAuth")(function* <T>(
+    input: SshAuthOperationInput<T>,
+  ): Effect.fn.Return<T, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    return yield* runWithSshAuthAttempt({
+      ...input,
+      promptCount: 0,
+      authSecret: authSecrets.get(input.key) ?? null,
+    });
+  });
+
+  const createTunnelEntry = Effect.fn("ssh/tunnel.ensureTunnelEntry.create")(function* (input: {
+    readonly key: string;
+    readonly resolvedTarget: DesktopSshEnvironmentTarget;
+    readonly runner?: RemoteT3RunnerOptions;
+  }): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    yield* Effect.logDebug("ssh.environment.tunnel.create.start", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      ...sshRunnerLogFields(input.runner),
+      key: input.key,
+    });
+    const remoteLaunch = yield* runWithSshAuth({
+      key: input.key,
+      target: input.resolvedTarget,
+      operation: (authOptions) =>
+        launchOrReuseRemoteServer(input.resolvedTarget, authOptions, input.runner),
+    });
+    const remotePort = remoteLaunch.remotePort;
+    yield* Effect.logDebug("ssh.environment.remotePort.ready", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      key: input.key,
+      remotePort,
+      remoteServerKind: remoteLaunch.remoteServerKind,
+    });
+    const localPort = yield* reserveLocalTunnelPort();
+    const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
+    const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
+    yield* Effect.logDebug("ssh.environment.localPort.reserved", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      key: input.key,
+      localPort,
+      remotePort,
+    });
+    const entryScope = yield* Scope.make("sequential");
+    const tunnelEntry = yield* runWithSshAuth({
+      key: input.key,
+      target: input.resolvedTarget,
+      operation: (authOptions) =>
+        startSshTunnel({
+          key: input.key,
+          resolvedTarget: input.resolvedTarget,
+          remotePort,
+          localPort,
+          httpBaseUrl,
+          wsBaseUrl,
+          authOptions,
+          remoteServerKind: remoteLaunch.remoteServerKind,
+        }).pipe(Effect.provideService(Scope.Scope, entryScope)),
+    }).pipe(
+      Effect.onExit((exit) =>
+        Exit.isSuccess(exit) ? Effect.void : Scope.close(entryScope, Exit.void).pipe(Effect.ignore),
+      ),
+    );
+    tunnels.set(input.key, tunnelEntry);
+    const spawnerService = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const fileSystemService = yield* FileSystem.FileSystem;
+    const pathService = yield* Path.Path;
+    yield* Scope.addFinalizer(
+      entryScope,
+      Effect.gen(function* () {
+        if (tunnels.get(tunnelEntry.key) !== tunnelEntry) {
+          return;
+        }
+        yield* Effect.logDebug("ssh.environment.tunnel.finalizer.start", {
+          ...sshTargetLogFields(tunnelEntry.target),
+          key: tunnelEntry.key,
+          localPort: tunnelEntry.localPort,
+          remotePort: tunnelEntry.remotePort,
+        });
+        tunnels.delete(tunnelEntry.key);
+        const authSecret = authSecrets.get(tunnelEntry.key) ?? null;
+        yield* Effect.all(
+          [
+            tunnelEntry.process.kill({
+              killSignal: "SIGTERM",
+              forceKillAfter: TUNNEL_SHUTDOWN_TIMEOUT_MS,
+            }),
+            stopRemoteServer(
+              tunnelEntry.target,
+              authSecret === null
+                ? {
+                    batchMode: "yes",
+                    interactiveAuth: false,
+                  }
+                : {
+                    authSecret,
+                    batchMode: "no",
+                    interactiveAuth: true,
+                  },
+            ).pipe(
+              Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawnerService),
+              Effect.provideService(FileSystem.FileSystem, fileSystemService),
+              Effect.provideService(Path.Path, pathService),
+            ),
+          ],
+          { concurrency: "unbounded" },
+        ).pipe(Effect.ignore);
+        yield* Effect.logDebug("ssh.environment.tunnel.finalizer.succeeded", {
+          ...sshTargetLogFields(tunnelEntry.target),
+          key: tunnelEntry.key,
+          localPort: tunnelEntry.localPort,
+          remotePort: tunnelEntry.remotePort,
+        });
+      }).pipe(Effect.ignore),
+    );
+    yield* Effect.logDebug("ssh.environment.tunnel.create.succeeded", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      key: input.key,
+      localPort,
+      remotePort,
+    });
+    return tunnelEntry;
+  });
+
+  const ensureTunnelEntry = Effect.fn("ssh/tunnel.ensureTunnelEntry")(function* (
+    key: string,
+    resolvedTarget: DesktopSshEnvironmentTarget,
+    runner?: RemoteT3RunnerOptions,
+  ): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    let entry = tunnels.get(key) ?? null;
+
+    if (entry !== null) {
+      yield* Effect.logDebug("ssh.environment.tunnel.existing.check", {
+        ...sshTargetLogFields(resolvedTarget),
+        key,
+        localPort: entry.localPort,
+        remotePort: entry.remotePort,
+      });
+      const readinessExit = yield* Effect.exit(
+        waitForHttpReady({ baseUrl: entry.httpBaseUrl, timeoutMs: 2_000 }),
+      );
+      if (Exit.isSuccess(readinessExit)) {
+        yield* Effect.logDebug("ssh.environment.tunnel.reused", {
+          ...sshTargetLogFields(resolvedTarget),
+          key,
+          localPort: entry.localPort,
+          remotePort: entry.remotePort,
+        });
+        return entry;
+      }
+      yield* Effect.logWarning("ssh.environment.tunnel.existing.stale", {
+        ...sshTargetLogFields(resolvedTarget),
+        key,
+        localPort: entry.localPort,
+        remotePort: entry.remotePort,
+        cause: readinessExit.cause,
+      });
+      yield* closeTunnelEntry(entry);
+      yield* cancelPendingTunnelEntry(key, resolvedTarget);
+      entry = null;
+    }
+
+    const pending = pendingTunnelEntries.get(key);
+    if (pending) {
+      yield* Effect.logDebug("ssh.environment.tunnel.pending.await", {
+        ...sshTargetLogFields(resolvedTarget),
+        key,
+      });
+      return yield* Deferred.await(pending);
+    }
+
+    const deferred = yield* Deferred.make<SshTunnelEntry, SshEnvironmentEffectError>();
+    pendingTunnelEntries.set(key, deferred);
+
+    return yield* createTunnelEntry({
+      key,
+      resolvedTarget,
+      ...(runner === undefined ? {} : { runner }),
+    }).pipe(
+      Effect.tapError((cause) =>
+        Effect.logWarning("ssh.environment.tunnel.create.failed", {
+          ...sshTargetLogFields(resolvedTarget),
+          key,
+          cause,
+        }),
+      ),
+      Effect.onExit((exit) =>
+        Effect.sync(() => {
+          if (pendingTunnelEntries.get(key) === deferred) {
+            pendingTunnelEntries.delete(key);
+          }
+        }).pipe(Effect.andThen(Deferred.done(deferred, exit))),
+      ),
+    );
+  });
+
+  const ensureEnvironment = Effect.fn("ssh/tunnel.ensureEnvironment")(function* (
+    target: DesktopSshEnvironmentTarget,
+    requestOptions?: { readonly issuePairingToken?: boolean },
+  ): Effect.fn.Return<
+    DesktopSshEnvironmentBootstrap,
+    SshEnvironmentEffectError,
+    SshEnvironmentEffectContext
+  > {
+    yield* Effect.logInfo("ssh.environment.ensure.start", {
+      ...sshTargetLogFields(target),
+      issuePairingToken: requestOptions?.issuePairingToken === true,
+    });
+    const baseResolved = yield* resolveSshTarget(target.alias || target.hostname);
+    const resolvedTarget: DesktopSshEnvironmentTarget = {
+      ...baseResolved,
+      ...(target.username !== null ? { username: target.username } : {}),
+      ...(target.port !== null ? { port: target.port } : {}),
+    };
+    const key = targetConnectionKey(resolvedTarget);
+    yield* Effect.logDebug("ssh.environment.target.resolved", {
+      ...sshTargetLogFields(resolvedTarget),
+      key,
+    });
+    const packageSpec = options.resolveCliPackageSpec?.();
+    const runner =
+      options.resolveCliRunner === undefined
+        ? packageSpec === undefined
+          ? undefined
+          : { packageSpec }
+        : yield* options.resolveCliRunner;
+    yield* Effect.logDebug("ssh.environment.runner.resolved", {
+      ...sshTargetLogFields(resolvedTarget),
+      ...sshRunnerLogFields(runner),
+      key,
+    });
+    const entry = yield* ensureTunnelEntry(key, resolvedTarget, runner);
+
+    const pairingResult = requestOptions?.issuePairingToken
+      ? yield* runWithSshAuth({
+          key,
+          target: entry.target,
+          operation: (authOptions) => issueRemotePairingToken(entry.target, authOptions, runner),
+        })
+      : null;
+    const pairingToken = pairingResult?.credential ?? null;
+
+    yield* Effect.logInfo("ssh.environment.ensure.succeeded", {
+      ...sshTargetLogFields(entry.target),
+      key,
+      localPort: entry.localPort,
+      remotePort: entry.remotePort,
+      remoteServerKind: entry.remoteServerKind,
+      issuedPairingToken: pairingToken !== null,
+    });
+    return {
+      target: entry.target,
+      httpBaseUrl: entry.httpBaseUrl,
+      wsBaseUrl: entry.wsBaseUrl,
+      pairingToken,
+      remotePort: entry.remotePort,
+      ...(entry.remoteServerKind ? { remoteServerKind: entry.remoteServerKind } : {}),
+    };
+  });
+
+  const disconnectEnvironment = Effect.fn("ssh/tunnel.disconnectEnvironment")(function* (
+    target: DesktopSshEnvironmentTarget,
+  ): Effect.fn.Return<void, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    yield* Effect.logInfo("ssh.environment.disconnect.start", sshTargetLogFields(target));
+    const baseResolved = yield* resolveSshTarget(target.alias || target.hostname);
+    const resolvedTarget: DesktopSshEnvironmentTarget = {
+      ...baseResolved,
+      ...(target.username !== null ? { username: target.username } : {}),
+      ...(target.port !== null ? { port: target.port } : {}),
+    };
+    const key = targetConnectionKey(resolvedTarget);
+    const entry = tunnels.get(key) ?? null;
+    yield* Effect.logDebug("ssh.environment.disconnect.targetResolved", {
+      ...sshTargetLogFields(resolvedTarget),
+      key,
+      hasTunnel: entry !== null,
+      hasPendingTunnel: pendingTunnelEntries.has(key),
+    });
+    if (entry !== null) {
+      yield* closeTunnelEntry(entry);
+    }
+    yield* cancelPendingTunnelEntry(key, resolvedTarget);
+    if (entry === null) {
+      yield* runWithSshAuth({
+        key,
+        target: resolvedTarget,
+        operation: (authOptions) => stopRemoteServer(resolvedTarget, authOptions),
+      });
+    }
+    yield* Effect.logInfo("ssh.environment.disconnect.succeeded", {
+      ...sshTargetLogFields(resolvedTarget),
+      key,
+    });
+  });
+
+  return SshEnvironmentManager.of({ ensureEnvironment, disconnectEnvironment });
+});
+
+export class SshEnvironmentManager extends Context.Service<
+  SshEnvironmentManager,
+  SshEnvironmentManagerShape
+>()("@t3tools/ssh/SshEnvironmentManager") {
+  static readonly layer = (options: SshEnvironmentManagerOptions = {}) =>
+    Layer.effect(SshEnvironmentManager, makeSshEnvironmentManager(options));
+}
diff --git a/packages/ssh/tsconfig.json b/packages/ssh/tsconfig.json
new file mode 100644
index 00000000000..73a306f847a
--- /dev/null
+++ b/packages/ssh/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": ["src"]
+}
diff --git a/packages/tailscale/package.json b/packages/tailscale/package.json
new file mode 100644
index 00000000000..85fdde36e79
--- /dev/null
+++ b/packages/tailscale/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@t3tools/tailscale",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@effect/platform-node": "catalog:",
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@effect/vitest": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/packages/tailscale/src/index.ts b/packages/tailscale/src/index.ts
new file mode 100644
index 00000000000..b6cba8d7b43
--- /dev/null
+++ b/packages/tailscale/src/index.ts
@@ -0,0 +1 @@
+export * from "./tailscale.ts";
diff --git a/packages/tailscale/src/tailscale.test.ts b/packages/tailscale/src/tailscale.test.ts
new file mode 100644
index 00000000000..dd2b1772fd6
--- /dev/null
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -0,0 +1,144 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  buildTailscaleHttpsBaseUrl,
+  disableTailscaleServe,
+  ensureTailscaleServe,
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  parseTailscaleStatus,
+  readTailscaleStatus,
+} from "./tailscale.ts";
+
+const encoder = new TextEncoder();
+const tailscaleStatusJson = `{"Self":{"DNSName":"desktop.tail.ts.net.","TailscaleIPs":["100.100.100.100","fd7a:115c:a1e0::1","192.168.1.20"]}}`;
+const tailscaleStatusWithSingleIpJson = `{"Self":{"DNSName":"desktop.tail.ts.net.","TailscaleIPs":["100.90.1.2"]}}`;
+
+function mockHandle(result: { stdout?: string; stderr?: string; code?: number }) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(result.code ?? 0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: Sink.drain,
+    stdout: Stream.make(encoder.encode(result.stdout ?? "")),
+    stderr: Stream.make(encoder.encode(result.stderr ?? "")),
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+function mockSpawnerLayer(
+  handler: (
+    command: string,
+    args: ReadonlyArray<string>,
+  ) => { stdout?: string; stderr?: string; code?: number },
+) {
+  return Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make((command) => {
+      const childProcess = command as unknown as {
+        readonly command: string;
+        readonly args: ReadonlyArray<string>;
+      };
+      return Effect.succeed(mockHandle(handler(childProcess.command, childProcess.args)));
+    }),
+  );
+}
+
+describe("tailscale", () => {
+  it.effect("detects Tailnet IPv4 addresses", () =>
+    Effect.sync(() => {
+      assert.equal(isTailscaleIpv4Address("100.64.0.1"), true);
+      assert.equal(isTailscaleIpv4Address("100.127.255.254"), true);
+      assert.equal(isTailscaleIpv4Address("100.128.0.1"), false);
+      assert.equal(isTailscaleIpv4Address("192.168.1.44"), false);
+    }),
+  );
+
+  it.effect("parses MagicDNS names from tailscale status", () =>
+    Effect.gen(function* () {
+      const dnsName = yield* parseTailscaleMagicDnsName(tailscaleStatusJson);
+      assert.equal(dnsName, "desktop.tail.ts.net");
+      assert.equal(yield* parseTailscaleMagicDnsName("{}"), null);
+    }),
+  );
+
+  it.effect("parses status facts", () =>
+    Effect.gen(function* () {
+      const status = yield* parseTailscaleStatus(tailscaleStatusJson);
+      assert.deepEqual(status, {
+        magicDnsName: "desktop.tail.ts.net",
+        tailnetIpv4Addresses: ["100.100.100.100"],
+      });
+    }),
+  );
+
+  it.effect("builds clean HTTPS base URLs", () =>
+    Effect.sync(() => {
+      assert.equal(
+        buildTailscaleHttpsBaseUrl({ magicDnsName: "desktop.tail.ts.net" }),
+        "https://desktop.tail.ts.net/",
+      );
+      assert.equal(
+        buildTailscaleHttpsBaseUrl({ magicDnsName: "desktop.tail.ts.net", servePort: 8443 }),
+        "https://desktop.tail.ts.net:8443/",
+      );
+    }),
+  );
+
+  it.effect("reads tailscale status through the process spawner service", () => {
+    const layer = mockSpawnerLayer((command, args) => {
+      assert.equal(command, "tailscale");
+      assert.deepEqual(args, ["status", "--json"]);
+      return {
+        stdout: tailscaleStatusWithSingleIpJson,
+      };
+    });
+
+    return Effect.gen(function* () {
+      const status = yield* readTailscaleStatus.pipe(Effect.provide(layer));
+      assert.deepEqual(status, {
+        magicDnsName: "desktop.tail.ts.net",
+        tailnetIpv4Addresses: ["100.90.1.2"],
+      });
+    });
+  });
+
+  it.effect("configures tailscale serve through the process spawner service", () => {
+    const layer = mockSpawnerLayer((command, args) => {
+      assert.equal(command, "tailscale");
+      assert.deepEqual(args, ["serve", "--bg", "--https=8443", "http://127.0.0.1:13773"]);
+      return {};
+    });
+
+    return ensureTailscaleServe({ localPort: 13773, servePort: 8443 }).pipe(Effect.provide(layer));
+  });
+
+  it.effect("disables tailscale serve through the process spawner service", () => {
+    const commands: {
+      readonly command: string;
+      readonly args: ReadonlyArray<string>;
+    }[] = [];
+    const layer = mockSpawnerLayer((command, args) => {
+      commands.push({ command, args });
+      assert.equal(command, "tailscale");
+      assert.deepEqual(args, ["serve", "--https=8443", "off"]);
+      return {};
+    });
+
+    return Effect.gen(function* () {
+      yield* disableTailscaleServe({ servePort: 8443 }).pipe(Effect.provide(layer));
+      assert.deepEqual(commands, [
+        { command: "tailscale", args: ["serve", "--https=8443", "off"] },
+      ]);
+    });
+  });
+});
diff --git a/packages/tailscale/src/tailscale.ts b/packages/tailscale/src/tailscale.ts
new file mode 100644
index 00000000000..c40cd54fc44
--- /dev/null
+++ b/packages/tailscale/src/tailscale.ts
@@ -0,0 +1,324 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+export const DEFAULT_TAILSCALE_SERVE_PORT = 443;
+export const TAILSCALE_STATUS_TIMEOUT_MS = 1_500;
+export const TAILSCALE_SERVE_TIMEOUT_MS = 10_000;
+export const TAILSCALE_PROBE_TIMEOUT_MS = 2_500;
+
+export class TailscaleCommandError extends Data.TaggedError("TailscaleCommandError")<{
+  readonly command: readonly string[];
+  readonly message: string;
+  readonly exitCode: number | null;
+  readonly stderr: string;
+}> {}
+
+export class TailscaleStatusParseError extends Data.TaggedError("TailscaleStatusParseError")<{
+  readonly cause: unknown;
+}> {}
+
+export class TailscaleUnavailableError extends Data.TaggedError("TailscaleUnavailableError")<{
+  readonly reason: string;
+}> {}
+
+const TailscaleStatusSelf = Schema.Struct({
+  DNSName: Schema.optional(Schema.Unknown),
+  TailscaleIPs: Schema.optional(Schema.Unknown),
+});
+
+const TailscaleStatusJson = Schema.Struct({
+  Self: Schema.optional(TailscaleStatusSelf),
+});
+
+export type TailscaleStatusSelf = typeof TailscaleStatusSelf.Type;
+export type TailscaleStatusJson = typeof TailscaleStatusJson.Type;
+
+export interface TailscaleStatus {
+  readonly magicDnsName: string | null;
+  readonly tailnetIpv4Addresses: readonly string[];
+}
+
+const collectStdout = <E>(stream: Stream.Stream<Uint8Array, E>): Effect.Effect<string, E> =>
+  stream.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => "",
+      (acc, chunk) => acc + chunk,
+    ),
+  );
+
+const collectStderr = collectStdout;
+
+const tailscaleCommandError = (
+  args: readonly string[],
+  message: string,
+  exitCode: number | null,
+  stderr = "",
+): TailscaleCommandError =>
+  new TailscaleCommandError({
+    command: ["tailscale", ...args],
+    message,
+    exitCode,
+    stderr,
+  });
+
+const decodeTailscaleStatusJson = Schema.decodeEffect(Schema.fromJsonString(TailscaleStatusJson));
+
+function normalizeMagicDnsName(status: TailscaleStatusJson): string | null {
+  const dnsName = status.Self?.DNSName;
+  if (typeof dnsName !== "string") {
+    return null;
+  }
+
+  const normalized = dnsName.trim().replace(/\.$/u, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+export const parseTailscaleMagicDnsName = (
+  rawStatusJson: string,
+): Effect.Effect<string | null, TailscaleStatusParseError> =>
+  decodeTailscaleStatusJson(rawStatusJson).pipe(
+    Effect.mapError((cause) => new TailscaleStatusParseError({ cause })),
+    Effect.map(normalizeMagicDnsName),
+  );
+
+export function isTailscaleIpv4Address(address: string): boolean {
+  const parts = address.split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  const [first, second, third, fourth] = parts.map((part) => Number.parseInt(part, 10));
+  if (
+    first === undefined ||
+    second === undefined ||
+    third === undefined ||
+    fourth === undefined ||
+    [first, second, third, fourth].some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return false;
+  }
+  return first === 100 && second >= 64 && second <= 127;
+}
+
+export const parseTailscaleStatus = (
+  rawStatusJson: string,
+): Effect.Effect<TailscaleStatus, TailscaleStatusParseError> =>
+  decodeTailscaleStatusJson(rawStatusJson).pipe(
+    Effect.mapError((cause) => new TailscaleStatusParseError({ cause })),
+    Effect.map((parsed) => {
+      const rawIps = parsed.Self?.TailscaleIPs;
+      const tailnetIpv4Addresses = Array.isArray(rawIps)
+        ? rawIps
+            .filter((address): address is string => typeof address === "string")
+            .filter(isTailscaleIpv4Address)
+        : [];
+
+      return {
+        magicDnsName: normalizeMagicDnsName(parsed),
+        tailnetIpv4Addresses,
+      };
+    }),
+  );
+
+export const readTailscaleStatus: Effect.Effect<
+  TailscaleStatus,
+  TailscaleCommandError | TailscaleStatusParseError,
+  ChildProcessSpawner.ChildProcessSpawner
+> = Effect.gen(function* () {
+  const args = ["status", "--json"];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner
+    .spawn(
+      ChildProcess.make("tailscale", args, {
+        shell: process.platform === "win32",
+      }),
+    )
+    .pipe(
+      Effect.mapError((cause) =>
+        tailscaleCommandError(
+          args,
+          cause instanceof Error ? cause.message : "Failed to spawn tailscale status.",
+          null,
+        ),
+      ),
+    );
+  const [stdout, stderr, exitCode] = yield* Effect.all(
+    [
+      collectStdout(child.stdout),
+      collectStderr(child.stderr),
+      child.exitCode.pipe(Effect.map(Number)),
+    ],
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.mapError((cause) =>
+      tailscaleCommandError(
+        args,
+        cause instanceof Error ? cause.message : "Failed to run tailscale status.",
+        null,
+      ),
+    ),
+  );
+  if (exitCode !== 0) {
+    return yield* tailscaleCommandError(
+      args,
+      `Tailscale status exited with code ${exitCode}.`,
+      exitCode,
+      stderr,
+    );
+  }
+  return yield* parseTailscaleStatus(stdout);
+}).pipe(
+  Effect.scoped,
+  Effect.timeoutOption(TAILSCALE_STATUS_TIMEOUT_MS),
+  Effect.flatMap((result) =>
+    Option.match(result, {
+      onNone: () =>
+        Effect.fail(
+          tailscaleCommandError(["status", "--json"], "Tailscale status timed out.", null),
+        ),
+      onSome: Effect.succeed,
+    }),
+  ),
+);
+
+export function buildTailscaleHttpsBaseUrl(input: {
+  readonly magicDnsName: string;
+  readonly servePort?: number;
+}): string {
+  const url = new URL(`https://${input.magicDnsName}`);
+  const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
+  if (servePort !== DEFAULT_TAILSCALE_SERVE_PORT) {
+    url.port = String(servePort);
+  }
+  url.pathname = "/";
+  return url.toString();
+}
+
+const runTailscaleCommand = (
+  args: readonly string[],
+  input: {
+    readonly spawnMessage: string;
+    readonly runMessage: string;
+    readonly exitMessage: (exitCode: number) => string;
+    readonly timeoutMessage: string;
+    readonly timeoutMs: number;
+  },
+): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const child = yield* spawner
+      .spawn(
+        ChildProcess.make("tailscale", args, {
+          shell: process.platform === "win32",
+        }),
+      )
+      .pipe(
+        Effect.mapError((cause) =>
+          tailscaleCommandError(
+            args,
+            cause instanceof Error ? cause.message : input.spawnMessage,
+            null,
+          ),
+        ),
+      );
+    const [stderr, exitCode] = yield* Effect.all(
+      [collectStderr(child.stderr), child.exitCode.pipe(Effect.map(Number))],
+      { concurrency: "unbounded" },
+    ).pipe(
+      Effect.mapError((cause) =>
+        tailscaleCommandError(
+          args,
+          cause instanceof Error ? cause.message : input.runMessage,
+          null,
+        ),
+      ),
+    );
+    if (exitCode !== 0) {
+      return yield* tailscaleCommandError(args, input.exitMessage(exitCode), exitCode, stderr);
+    }
+  }).pipe(
+    Effect.scoped,
+    Effect.timeoutOption(input.timeoutMs),
+    Effect.flatMap((result) =>
+      Option.match(result, {
+        onNone: () => Effect.fail(tailscaleCommandError(args, input.timeoutMessage, null)),
+        onSome: Effect.succeed,
+      }),
+    ),
+  );
+
+export const ensureTailscaleServe = (input: {
+  readonly localPort: number;
+  readonly servePort?: number;
+  readonly localHost?: string;
+}): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> => {
+  const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
+  const localHost = input.localHost ?? "127.0.0.1";
+  const args = ["serve", "--bg", `--https=${servePort}`, `http://${localHost}:${input.localPort}`];
+  return runTailscaleCommand(args, {
+    spawnMessage: "Failed to spawn tailscale serve.",
+    runMessage: "Failed to run tailscale serve.",
+    exitMessage: (exitCode) => `Tailscale serve exited with code ${exitCode}.`,
+    timeoutMessage: "Tailscale serve timed out.",
+    timeoutMs: TAILSCALE_SERVE_TIMEOUT_MS,
+  });
+};
+
+export const disableTailscaleServe = (
+  input: {
+    readonly servePort?: number;
+  } = {},
+): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function* () {
+    const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
+    return yield* runTailscaleCommand(["serve", `--https=${servePort}`, "off"], {
+      spawnMessage: "Failed to spawn tailscale serve off.",
+      runMessage: "Failed to run tailscale serve off.",
+      exitMessage: (exitCode) => `Tailscale serve off exited with code ${exitCode}.`,
+      timeoutMessage: "Tailscale serve off timed out.",
+      timeoutMs: TAILSCALE_SERVE_TIMEOUT_MS,
+    });
+  });
+
+export const probeTailscaleHttpsEndpoint = (input: {
+  readonly baseUrl: string;
+  readonly timeoutMs?: number;
+}): Effect.Effect<boolean, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* Effect.gen(function* () {
+      const url = new URL("/.well-known/t3/environment", input.baseUrl);
+      const request = HttpClientRequest.get(url.toString());
+      return yield* client.execute(request);
+    }).pipe(Effect.timeoutOption(input.timeoutMs ?? TAILSCALE_PROBE_TIMEOUT_MS));
+
+    return Option.match(response, {
+      onNone: () => false,
+      onSome: (httpResponse) => httpResponse.status >= 200 && httpResponse.status < 300,
+    });
+  }).pipe(Effect.catch(() => Effect.succeed(false)));
+
+export const resolveTailscaleHttpsBaseUrl = (
+  input: {
+    readonly servePort?: number;
+  } = {},
+): Effect.Effect<
+  string | null,
+  TailscaleCommandError | TailscaleStatusParseError,
+  ChildProcessSpawner.ChildProcessSpawner
+> =>
+  readTailscaleStatus.pipe(
+    Effect.map((status) =>
+      status.magicDnsName
+        ? buildTailscaleHttpsBaseUrl({
+            magicDnsName: status.magicDnsName,
+            ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+          })
+        : null,
+    ),
+  );
diff --git a/packages/tailscale/tsconfig.json b/packages/tailscale/tsconfig.json
new file mode 100644
index 00000000000..73a306f847a
--- /dev/null
+++ b/packages/tailscale/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": ["src"]
+}
diff --git a/patches/effect@4.0.0-beta.59.patch b/patches/effect@4.0.0-beta.59.patch
new file mode 100644
index 00000000000..479004acf33
--- /dev/null
+++ b/patches/effect@4.0.0-beta.59.patch
@@ -0,0 +1,277 @@
+diff --git a/dist/unstable/rpc/RpcClient.d.ts b/dist/unstable/rpc/RpcClient.d.ts
+index 7c5970042df67a25b4145df017960b3e6febed9c..7af3374632d53ad59f24e80835aa6741853b1f2b 100644
+--- a/dist/unstable/rpc/RpcClient.d.ts
++++ b/dist/unstable/rpc/RpcClient.d.ts
+@@ -2,6 +2,7 @@ import * as Cause from "../../Cause.ts";
+ import * as Context from "../../Context.ts";
+ import type * as Duration from "../../Duration.ts";
+ import * as Effect from "../../Effect.ts";
++import * as Exit from "../../Exit.ts";
+ import * as Layer from "../../Layer.ts";
+ import * as Queue from "../../Queue.ts";
+ import * as Schedule from "../../Schedule.ts";
+@@ -192,9 +193,40 @@ export declare const layerProtocolWorker: (options: {
+     readonly targetUtilization?: number | undefined;
+     readonly timeToLive: Duration.Input;
+ }) => Layer.Layer<Protocol, WorkerError, Worker.WorkerPlatform | Worker.Spawner>;
++declare const RequestHooks_base: Context.ServiceClass<RequestHooks, "effect/rpc/RpcClient/RequestHooks", {
++    readonly onRequestStart?: ((info: {
++        readonly id: RequestId;
++        readonly tag: string;
++        readonly stream: boolean;
++    }) => Effect.Effect<void>) | undefined;
++    readonly onRequestChunk?: ((info: {
++        readonly id: RequestId;
++        readonly tag: string;
++        readonly chunkCount: number;
++    }) => Effect.Effect<void>) | undefined;
++    readonly onRequestExit?: ((info: {
++        readonly id: RequestId;
++        readonly tag: string;
++        readonly stream: boolean;
++        readonly exit: Exit.Exit<unknown, unknown>;
++    }) => Effect.Effect<void>) | undefined;
++    readonly onRequestInterrupt?: ((info: {
++        readonly id: RequestId;
++        readonly tag?: string | undefined;
++    }) => Effect.Effect<void>) | undefined;
++}>;
++/**
++ * @since 4.0.0
++ * @category RequestHooks
++ */
++export declare class RequestHooks extends RequestHooks_base {
++}
+ declare const ConnectionHooks_base: Context.ServiceClass<ConnectionHooks, "effect/rpc/RpcClient/ConnectionHooks", {
+     readonly onConnect: Effect.Effect<void>;
+     readonly onDisconnect: Effect.Effect<void>;
++    readonly onPing?: Effect.Effect<void> | undefined;
++    readonly onPong?: Effect.Effect<void> | undefined;
++    readonly onPingTimeout?: Effect.Effect<void> | undefined;
+ }>;
+ /**
+  * @since 4.0.0
+diff --git a/dist/unstable/rpc/RpcClient.js b/dist/unstable/rpc/RpcClient.js
+index 951dfc2d667a9136cfa714dcd3195e6575917fde..599c0345873bedd72bc93afe80eab0c676319421 100644
+--- a/dist/unstable/rpc/RpcClient.js
++++ b/dist/unstable/rpc/RpcClient.js
+@@ -42,6 +42,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+   const services = yield* Effect.context();
+   const scope = Context.get(services, Scope.Scope);
+   const entries = new Map();
++  const hooks = yield* Effect.serviceOption(RequestHooks);
+   let isShutdown = false;
+   yield* Scope.addFinalizer(scope, Effect.withFiber(parent => {
+     isShutdown = true;
+@@ -79,6 +80,11 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       return Effect.interrupt;
+     }
+     const id = generateRequestId();
++    const onStart = Option.isSome(hooks) && hooks.value.onRequestStart ? hooks.value.onRequestStart({
++      id,
++      tag: rpc._tag,
++      stream: false
++    }) : Effect.void;
+     const send = middleware(message => options.onFromClient({
+       message,
+       context,
+@@ -96,7 +102,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       headers: Headers.merge(parentFiber.getRef(CurrentHeaders), headers)
+     });
+     if (discard) {
+-      return send;
++      return onStart.pipe(Effect.andThen(send));
+     }
+     let fiber;
+     return Effect.onInterrupt(Effect.callback(resume => {
+@@ -114,7 +120,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+         }
+       };
+       entries.set(id, entry);
+-      fiber = send.pipe(span ? Effect.withParentSpan(span, {
++      fiber = onStart.pipe(Effect.andThen(send), span ? Effect.withParentSpan(span, {
+         captureStackTrace: false
+       }) : identity, Effect.runForkWith(parentFiber.context));
+       fiber.addObserver(exit => {
+@@ -123,8 +129,9 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+         }
+       });
+     }), interruptors => {
++      const entry = entries.get(id);
+       entries.delete(id);
+-      return Effect.andThen(Fiber.interrupt(fiber), sendInterrupt(id, Array.from(interruptors), context));
++      return Effect.andThen(Fiber.interrupt(fiber), sendInterrupt(id, Array.from(interruptors), context, entry?.rpc._tag));
+     });
+   });
+   const onStreamRequest = Effect.fnUntraced(function* (rpc, middleware, payload, headers, streamBufferSize, context) {
+@@ -136,11 +143,17 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+     });
+     const fiber = Fiber.getCurrent();
+     const id = generateRequestId();
++    const onStart = Option.isSome(hooks) && hooks.value.onRequestStart ? hooks.value.onRequestStart({
++      id,
++      tag: rpc._tag,
++      stream: true
++    }) : Effect.void;
+     const scope = Context.getUnsafe(fiber.context, Scope.Scope);
+     yield* Scope.addFinalizerExit(scope, exit => {
+-      if (!entries.has(id)) return Effect.void;
++      const entry = entries.get(id);
++      if (!entry) return Effect.void;
+       entries.delete(id);
+-      return sendInterrupt(id, Exit.isFailure(exit) ? Array.from(Cause.interruptors(exit.cause)) : [], context);
++      return sendInterrupt(id, Exit.isFailure(exit) ? Array.from(Cause.interruptors(exit.cause)) : [], context, entry.rpc._tag);
+     });
+     const queue = yield* Queue.bounded(streamBufferSize);
+     entries.set(id, {
+@@ -148,9 +161,10 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       rpc,
+       queue,
+       scope,
+-      context
++      context,
++      chunkCount: 0
+     });
+-    yield* middleware(message => options.onFromClient({
++    yield* onStart.pipe(Effect.andThen(middleware(message => options.onFromClient({
+       message,
+       context,
+       discard: false
+@@ -165,7 +179,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+         sampled: span.sampled
+       } : {}),
+       headers: Headers.merge(fiber.getRef(CurrentHeaders), headers)
+-    }).pipe(span ? Effect.withParentSpan(span, {
++    }))).pipe(span ? Effect.withParentSpan(span, {
+       captureStackTrace: false
+     }) : identity, Effect.catchCause(error => Queue.failCause(queue, error)), Effect.interruptible, Effect.forkIn(scope, {
+       startImmediately: true
+@@ -195,7 +209,10 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       });
+     };
+   };
+-  const sendInterrupt = (requestId, interruptors, context) => Effect.callback(resume => {
++  const sendInterrupt = (requestId, interruptors, context, tag) => (Option.isSome(hooks) && hooks.value.onRequestInterrupt ? hooks.value.onRequestInterrupt({
++    id: requestId,
++    tag
++  }) : Effect.void).pipe(Effect.andThen(Effect.callback(resume => {
+     const parentFiber = Fiber.getCurrent();
+     const fiber = options.onFromClient({
+       message: {
+@@ -209,7 +226,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+     fiber.addObserver(() => {
+       resume(Effect.void);
+     });
+-  });
++  })));
+   const write = message => {
+     switch (message._tag) {
+       case "Chunk":
+@@ -217,7 +234,13 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+           const requestId = message.requestId;
+           const entry = entries.get(requestId);
+           if (!entry || entry._tag !== "Queue") return Effect.void;
+-          return Queue.offerAll(entry.queue, message.values).pipe(supportsAck ? Effect.flatMap(() => options.onFromClient({
++          const chunkCount = entry.chunkCount += message.values.length;
++          const onChunk = Option.isSome(hooks) && hooks.value.onRequestChunk ? hooks.value.onRequestChunk({
++            id: requestId,
++            tag: entry.rpc._tag,
++            chunkCount
++          }) : Effect.void;
++          return Queue.offerAll(entry.queue, message.values).pipe(Effect.andThen(onChunk), supportsAck ? Effect.flatMap(() => options.onFromClient({
+             message: {
+               _tag: "Ack",
+               requestId: message.requestId
+@@ -232,11 +255,18 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+           const entry = entries.get(requestId);
+           if (!entry) return Effect.void;
+           entries.delete(requestId);
++          const onExit = Option.isSome(hooks) && hooks.value.onRequestExit ? hooks.value.onRequestExit({
++            id: requestId,
++            tag: entry.rpc._tag,
++            stream: entry._tag === "Queue",
++            exit: message.exit
++          }) : Effect.void;
+           if (entry._tag === "Effect") {
+-            entry.resume(message.exit);
+-            return Effect.void;
++            return onExit.pipe(Effect.andThen(Effect.sync(() => {
++              entry.resume(message.exit);
++            })));
+           }
+-          return message.exit._tag === "Success" ? Queue.end(entry.queue) : Queue.failCause(entry.queue, message.exit.cause);
++          return onExit.pipe(Effect.andThen(message.exit._tag === "Success" ? Queue.end(entry.queue) : Queue.failCause(entry.queue, message.exit.cause)));
+         }
+       case "Defect":
+         {
+@@ -530,7 +560,7 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+   const requestClientMap = new Map();
+   const write = yield* socket.writer;
+   let parser = serialization.makeUnsafe();
+-  const pinger = yield* makePinger(write(parser.encode(constPing)));
++  const pinger = yield* makePinger(write(parser.encode(constPing)), Option.isSome(hooks) ? hooks.value : undefined);
+   let currentError;
+   const onOpen = Effect.suspend(() => {
+     currentError = undefined;
+@@ -550,8 +580,7 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+           body: () => {
+             const response = responses[i++];
+             if (response._tag === "Pong") {
+-              pinger.onPong();
+-              return Effect.void;
++              return pinger.onPong;
+             }
+             if ("requestId" in response) {
+               const clientId = requestClientMap.get(response.requestId);
+@@ -579,12 +608,12 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+       }
+     }, {
+       onOpen
+-    }).pipe(Effect.raceFirst(Effect.flatMap(pinger.timeout, () => Effect.fail(new Socket.SocketError({
++    }).pipe(Effect.raceFirst(Effect.flatMap(pinger.timeout, () => (Option.isSome(hooks) && hooks.value.onPingTimeout ? hooks.value.onPingTimeout : Effect.void).pipe(Effect.andThen(Effect.fail(new Socket.SocketError({
+       reason: new Socket.SocketOpenError({
+         kind: "Timeout",
+         cause: new Error("ping timeout")
+       })
+-    })))));
++    })))))));
+   }).pipe(Effect.flatMap(() => Effect.fail(new Socket.SocketError({
+     reason: new Socket.SocketCloseError({
+       code: 1000
+@@ -626,20 +655,20 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+   };
+ }));
+ const defaultRetryPolicy = /*#__PURE__*/Schedule.exponential(500, 1.5).pipe(/*#__PURE__*/Schedule.either(/*#__PURE__*/Schedule.spaced(5000)));
+-const makePinger = /*#__PURE__*/Effect.fnUntraced(function* (writePing) {
++const makePinger = /*#__PURE__*/Effect.fnUntraced(function* (writePing, hooks) {
+   let recievedPong = true;
+   const latch = Latch.makeUnsafe();
+   const reset = () => {
+     recievedPong = true;
+     latch.closeUnsafe();
+   };
+-  const onPong = () => {
++  const onPong = Effect.sync(() => {
+     recievedPong = true;
+-  };
++  }).pipe(Effect.andThen(hooks?.onPong ?? Effect.void));
+   yield* Effect.suspend(() => {
+     if (!recievedPong) return latch.open;
+     recievedPong = false;
+-    return writePing;
++    return (hooks?.onPing ?? Effect.void).pipe(Effect.andThen(writePing));
+   }).pipe(Effect.delay("5 seconds"), Effect.ignore, Effect.forever, Effect.interruptible, Effect.forkScoped);
+   return {
+     timeout: latch.await,
+@@ -773,6 +802,11 @@ export const makeProtocolWorker = options => Protocol.make(Effect.fnUntraced(fun
+  * @category protocol
+  */
+ export const layerProtocolWorker = /*#__PURE__*/flow(makeProtocolWorker, /*#__PURE__*/Layer.effect(Protocol));
++/**
++ * @since 4.0.0
++ * @category RequestHooks
++ */
++export class RequestHooks extends /*#__PURE__*/Context.Service()("effect/rpc/RpcClient/RequestHooks") {}
+ /**
+  * @since 4.0.0
+  * @category ConnectionHooks
diff --git a/scripts/apply-web-brand-assets.ts b/scripts/apply-web-brand-assets.ts
new file mode 100644
index 00000000000..30e6bc325b6
--- /dev/null
+++ b/scripts/apply-web-brand-assets.ts
@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import {
+  resolveWebAssetBrandForChannel,
+  resolveWebIconOverrides,
+  WEB_ASSET_CHANNELS,
+  type WebAssetBrand,
+} from "./lib/brand-assets.ts";
+
+const WEB_ASSET_BRANDS = [
+  "development",
+  "nightly",
+  "production",
+] as const satisfies ReadonlyArray<WebAssetBrand>;
+
+export const applyWebBrandAssets = Effect.fn("applyWebBrandAssets")(function* (
+  brand: WebAssetBrand,
+  targetDirectory: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const repoRoot = yield* path.fromFileUrl(new URL("..", import.meta.url));
+
+  yield* Effect.forEach(
+    resolveWebIconOverrides(brand, targetDirectory),
+    (override) =>
+      fs.copyFile(
+        path.join(repoRoot, override.sourceRelativePath),
+        path.join(repoRoot, override.targetRelativePath),
+      ),
+    { concurrency: "unbounded" },
+  );
+});
+
+export const applyWebBrandAssetsCommand = Command.make(
+  "apply-web-brand-assets",
+  {
+    brand: Argument.choice("brand", WEB_ASSET_BRANDS).pipe(
+      Argument.withDescription("Asset brand to copy into the hosted web output directory."),
+      Argument.optional,
+    ),
+    channel: Flag.choice("channel", WEB_ASSET_CHANNELS).pipe(
+      Flag.withDescription("Hosted release channel to map to a web asset brand."),
+      Flag.optional,
+    ),
+    targetDirectory: Argument.string("target-directory").pipe(
+      Argument.withDescription("Output directory that contains the hosted web build assets."),
+      Argument.optional,
+    ),
+  },
+  ({ brand, channel, targetDirectory }) =>
+    applyWebBrandAssets(
+      Option.getOrElse(brand, () =>
+        Option.match(channel, {
+          onNone: () => "production" as const,
+          onSome: resolveWebAssetBrandForChannel,
+        }),
+      ),
+      Option.getOrElse(targetDirectory, () => "apps/web/dist"),
+    ),
+).pipe(Command.withDescription("Copy web brand assets into a built hosted web app."));
+
+if (import.meta.main) {
+  Command.run(applyWebBrandAssetsCommand, { version: "0.0.0" }).pipe(
+    Effect.provide(NodeServices.layer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index f86beb6ff40..743263d43b3 100644
--- a/scripts/build-desktop-artifact.test.ts
+++ b/scripts/build-desktop-artifact.test.ts
@@ -1,10 +1,93 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
-import { ConfigProvider, Effect, Option } from "effect";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 
-import { resolveBuildOptions } from "./build-desktop-artifact.ts";
+import {
+  resolveDesktopRuntimeDependencies,
+  resolveBuildOptions,
+  resolveDesktopBuildIconAssets,
+  resolveDesktopProductName,
+  resolveDesktopUpdateChannel,
+  resolveMockUpdateServerPort,
+  resolveMockUpdateServerUrl,
+} from "./build-desktop-artifact.ts";
+import { BRAND_ASSET_PATHS } from "./lib/brand-assets.ts";
 
 it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
+  it("resolves the dedicated nightly updater channel from nightly versions", () => {
+    assert.equal(resolveDesktopUpdateChannel("0.0.17-nightly.20260413.42"), "nightly");
+    assert.equal(resolveDesktopUpdateChannel("0.0.17"), "latest");
+  });
+
+  it("switches desktop packaging product names to nightly for nightly builds", () => {
+    assert.equal(resolveDesktopProductName("0.0.17"), "T3 Code (Alpha)");
+    assert.equal(resolveDesktopProductName("0.0.17-nightly.20260413.42"), "T3 Code (Nightly)");
+  });
+
+  it("switches desktop packaging icons to the nightly artwork for nightly versions", () => {
+    assert.deepStrictEqual(resolveDesktopBuildIconAssets("0.0.17"), {
+      macIconPng: BRAND_ASSET_PATHS.productionMacIconPng,
+      linuxIconPng: BRAND_ASSET_PATHS.productionLinuxIconPng,
+      windowsIconIco: BRAND_ASSET_PATHS.productionWindowsIconIco,
+    });
+
+    assert.deepStrictEqual(resolveDesktopBuildIconAssets("0.0.17-nightly.20260413.42"), {
+      macIconPng: BRAND_ASSET_PATHS.nightlyMacIconPng,
+      linuxIconPng: BRAND_ASSET_PATHS.nightlyLinuxIconPng,
+      windowsIconIco: BRAND_ASSET_PATHS.nightlyWindowsIconIco,
+    });
+  });
+
+  it("omits bundled workspace packages from staged desktop dependencies", () => {
+    assert.deepStrictEqual(
+      resolveDesktopRuntimeDependencies(
+        {
+          "@effect/platform-node": "catalog:",
+          "@t3tools/contracts": "workspace:*",
+          "@t3tools/shared": "workspace:*",
+          "@t3tools/ssh": "workspace:*",
+          "@t3tools/tailscale": "workspace:*",
+          effect: "catalog:",
+          electron: "41.5.0",
+        },
+        {
+          "@effect/platform-node": "4.0.0-beta.59",
+          effect: "4.0.0-beta.59",
+        },
+      ),
+      {
+        "@effect/platform-node": "4.0.0-beta.59",
+        effect: "4.0.0-beta.59",
+      },
+    );
+  });
+
+  it("falls back to the default mock update port when the configured port is blank", () => {
+    assert.equal(resolveMockUpdateServerUrl(undefined), "http://localhost:3000");
+    assert.equal(resolveMockUpdateServerUrl(4123), "http://localhost:4123");
+  });
+
+  it.effect("normalizes mock update server ports from env-style strings", () =>
+    Effect.gen(function* () {
+      assert.equal(yield* resolveMockUpdateServerPort(undefined), undefined);
+      assert.equal(yield* resolveMockUpdateServerPort(""), undefined);
+      assert.equal(yield* resolveMockUpdateServerPort("   "), undefined);
+      assert.equal(yield* resolveMockUpdateServerPort("4123"), 4123);
+    }),
+  );
+
+  it.effect("rejects non-numeric or out-of-range mock update ports", () =>
+    Effect.gen(function* () {
+      const invalidPorts = ["abc", "12.5", "0", "65536"];
+      for (const port of invalidPorts) {
+        const exit = yield* Effect.exit(resolveMockUpdateServerPort(port));
+        assert.equal(exit._tag, "Failure");
+      }
+    }),
+  );
+
   it.effect("preserves explicit false boolean flags over true env defaults", () =>
     Effect.gen(function* () {
       const resolved = yield* resolveBuildOptions({
diff --git a/scripts/build-desktop-artifact.ts b/scripts/build-desktop-artifact.ts
index 97d46451aef..104cbef20c1 100644
--- a/scripts/build-desktop-artifact.ts
+++ b/scripts/build-desktop-artifact.ts
@@ -1,19 +1,25 @@
 #!/usr/bin/env node
 
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-
 import rootPackageJson from "../package.json" with { type: "json" };
 import desktopPackageJson from "../apps/desktop/package.json" with { type: "json" };
 import serverPackageJson from "../apps/server/package.json" with { type: "json" };
 
 import { BRAND_ASSET_PATHS } from "./lib/brand-assets.ts";
+import { getDefaultBuildArch } from "./lib/build-target-arch.ts";
 import { resolveCatalogDependencies } from "./lib/resolve-catalog.ts";
 
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { Config, Data, Effect, FileSystem, Layer, Logger, Option, Path, Schema } from "effect";
+import * as Config from "effect/Config";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import { Command, Flag } from "effect/unstable/cli";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
@@ -23,23 +29,14 @@ const BuildArch = Schema.Literals(["arm64", "x64", "universal"]);
 const RepoRoot = Effect.service(Path.Path).pipe(
   Effect.flatMap((path) => path.fromFileUrl(new URL("..", import.meta.url))),
 );
-const ProductionMacIconSource = Effect.zipWith(
-  RepoRoot,
-  Effect.service(Path.Path),
-  (repoRoot, path) => path.join(repoRoot, BRAND_ASSET_PATHS.productionMacIconPng),
-);
-const ProductionLinuxIconSource = Effect.zipWith(
-  RepoRoot,
-  Effect.service(Path.Path),
-  (repoRoot, path) => path.join(repoRoot, BRAND_ASSET_PATHS.productionLinuxIconPng),
-);
-const ProductionWindowsIconSource = Effect.zipWith(
-  RepoRoot,
-  Effect.service(Path.Path),
-  (repoRoot, path) => path.join(repoRoot, BRAND_ASSET_PATHS.productionWindowsIconIco),
-);
 const encodeJsonString = Schema.encodeEffect(Schema.UnknownFromJsonString);
 
+interface DesktopBuildIconAssets {
+  readonly macIconPng: string;
+  readonly linuxIconPng: string;
+  readonly windowsIconIco: string;
+}
+
 interface PlatformConfig {
   readonly cliFlag: "--mac" | "--linux" | "--win";
   readonly defaultTarget: string;
@@ -75,7 +72,7 @@ interface BuildCliInput {
   readonly signed: Option.Option<boolean>;
   readonly verbose: Option.Option<boolean>;
   readonly mockUpdates: Option.Option<boolean>;
-  readonly mockUpdateServerPort: Option.Option<string>;
+  readonly mockUpdateServerPort: Option.Option<number>;
 }
 
 function detectHostBuildPlatform(hostPlatform: string): typeof BuildPlatform.Type | undefined {
@@ -91,14 +88,7 @@ function getDefaultArch(platform: typeof BuildPlatform.Type): typeof BuildArch.T
     return "x64";
   }
 
-  if (process.arch === "arm64" && config.archChoices.includes("arm64")) {
-    return "arm64";
-  }
-  if (process.arch === "x64" && config.archChoices.includes("x64")) {
-    return "x64";
-  }
-
-  return config.archChoices[0] ?? "x64";
+  return getDefaultBuildArch(platform, process.arch, process.env, config);
 }
 
 class BuildScriptError extends Data.TaggedError("BuildScriptError")<{
@@ -106,12 +96,49 @@ class BuildScriptError extends Data.TaggedError("BuildScriptError")<{
   readonly cause?: unknown;
 }> {}
 
-function resolveGitCommitHash(repoRoot: string): string {
-  const result = spawnSync("git", ["rev-parse", "--short=12", "HEAD"], {
-    cwd: repoRoot,
-    encoding: "utf8",
-  });
-  if (result.status !== 0) {
+const collectStreamAsString = <E>(stream: Stream.Stream<Uint8Array, E>): Effect.Effect<string, E> =>
+  stream.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => "",
+      (acc, chunk) => acc + chunk,
+    ),
+  );
+
+const spawnAndCollectOutput = Effect.fn("spawnAndCollectOutput")(function* (
+  command: ChildProcess.Command,
+) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner.spawn(command);
+
+  const [stdout, stderr, exitCode] = yield* Effect.all(
+    [
+      collectStreamAsString(child.stdout),
+      collectStreamAsString(child.stderr),
+      child.exitCode.pipe(Effect.map(Number)),
+    ],
+    { concurrency: "unbounded" },
+  );
+
+  return { stdout, stderr, exitCode } as const;
+});
+
+const resolveGitCommitHash = Effect.fn("resolveGitCommitHash")(function* (repoRoot: string) {
+  const result = yield* spawnAndCollectOutput(
+    ChildProcess.make("git", ["rev-parse", "--short=12", "HEAD"], {
+      cwd: repoRoot,
+    }),
+  ).pipe(
+    Effect.catch(() =>
+      Effect.succeed({
+        stdout: "",
+        stderr: "",
+        exitCode: 1,
+      }),
+    ),
+  );
+
+  if (result.exitCode !== 0) {
     return "unknown";
   }
   const hash = result.stdout.trim();
@@ -119,11 +146,13 @@ function resolveGitCommitHash(repoRoot: string): string {
     return "unknown";
   }
   return hash.toLowerCase();
-}
+});
 
-function resolvePythonForNodeGyp(): string | undefined {
+const resolvePythonForNodeGyp = Effect.fn("resolvePythonForNodeGyp")(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
   const configured = process.env.npm_config_python ?? process.env.PYTHON;
-  if (configured && existsSync(configured)) {
+  if (configured && (yield* fs.exists(configured))) {
     return configured;
   }
 
@@ -131,28 +160,37 @@ function resolvePythonForNodeGyp(): string | undefined {
     const localAppData = process.env.LOCALAPPDATA;
     if (localAppData) {
       for (const version of ["Python313", "Python312", "Python311", "Python310"]) {
-        const candidate = join(localAppData, "Programs", "Python", version, "python.exe");
-        if (existsSync(candidate)) {
+        const candidate = path.join(localAppData, "Programs", "Python", version, "python.exe");
+        if (yield* fs.exists(candidate)) {
           return candidate;
         }
       }
     }
   }
 
-  const probe = spawnSync("python", ["-c", "import sys;print(sys.executable)"], {
-    encoding: "utf8",
-  });
-  if (probe.status !== 0) {
+  const probe = yield* spawnAndCollectOutput(
+    ChildProcess.make("python", ["-c", "import sys;print(sys.executable)"]),
+  ).pipe(
+    Effect.catch(() =>
+      Effect.succeed({
+        stdout: "",
+        stderr: "",
+        exitCode: 1,
+      }),
+    ),
+  );
+
+  if (probe.exitCode !== 0) {
     return undefined;
   }
 
   const executable = probe.stdout.trim();
-  if (!executable || !existsSync(executable)) {
+  if (!executable || !(yield* fs.exists(executable))) {
     return undefined;
   }
 
   return executable;
-}
+});
 
 interface ResolvedBuildOptions {
   readonly platform: typeof BuildPlatform.Type;
@@ -165,7 +203,7 @@ interface ResolvedBuildOptions {
   readonly signed: boolean;
   readonly verbose: boolean;
   readonly mockUpdates: boolean;
-  readonly mockUpdateServerPort: string | undefined;
+  readonly mockUpdateServerPort: number | undefined;
 }
 
 interface StagePackageJson {
@@ -213,11 +251,28 @@ const BuildEnvConfig = Config.all({
   mockUpdateServerPort: Config.string("T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT").pipe(Config.option),
 });
 
+const MockUpdateServerPortSchema = Schema.NumberFromString.check(
+  Schema.isInt(),
+  Schema.isBetween({ minimum: 1, maximum: 65535 }),
+);
+const decodeMockUpdateServerPort = Schema.decodeUnknownEffect(MockUpdateServerPortSchema);
+
 const resolveBooleanFlag = (flag: Option.Option<boolean>, envValue: boolean) =>
   Option.getOrElse(flag, () => envValue);
 const mergeOptions = <A>(a: Option.Option<A>, b: Option.Option<A>, defaultValue: A) =>
   Option.getOrElse(a, () => Option.getOrElse(b, () => defaultValue));
 
+export const resolveMockUpdateServerPort = Effect.fn("resolveMockUpdateServerPort")(function* (
+  mockUpdateServerPort: string | undefined,
+) {
+  const port = mockUpdateServerPort?.trim();
+  if (!port) {
+    return undefined;
+  }
+
+  return yield* decodeMockUpdateServerPort(port);
+});
+
 export const resolveBuildOptions = Effect.fn("resolveBuildOptions")(function* (
   input: BuildCliInput,
 ) {
@@ -254,11 +309,17 @@ export const resolveBuildOptions = Effect.fn("resolveBuildOptions")(function* (
   const verbose = resolveBooleanFlag(input.verbose, env.verbose);
 
   const mockUpdates = resolveBooleanFlag(input.mockUpdates, env.mockUpdates);
-  const mockUpdateServerPort = mergeOptions(
-    input.mockUpdateServerPort,
-    env.mockUpdateServerPort,
-    undefined,
-  );
+  const mockUpdateServerPort =
+    Option.getOrUndefined(input.mockUpdateServerPort) ??
+    (yield* resolveMockUpdateServerPort(Option.getOrUndefined(env.mockUpdateServerPort)).pipe(
+      Effect.mapError(
+        (cause) =>
+          new BuildScriptError({
+            message: "Invalid mock update server port.",
+            cause,
+          }),
+      ),
+    ));
 
   return {
     platform,
@@ -329,14 +390,13 @@ function generateMacIconSet(
   });
 }
 
-function stageMacIcons(stageResourcesDir: string, verbose: boolean) {
+function stageMacIcons(stageResourcesDir: string, sourcePng: string, verbose: boolean) {
   return Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const iconSource = yield* ProductionMacIconSource;
-    if (!(yield* fs.exists(iconSource))) {
+    if (!(yield* fs.exists(sourcePng))) {
       return yield* new BuildScriptError({
-        message: `Production icon source is missing at ${iconSource}`,
+        message: `Desktop macOS icon source is missing at ${sourcePng}`,
       });
     }
 
@@ -350,42 +410,40 @@ function stageMacIcons(stageResourcesDir: string, verbose: boolean) {
     yield* runCommand(
       ChildProcess.make({
         ...commandOutputOptions(verbose),
-      })`sips -z 512 512 ${iconSource} --out ${iconPngPath}`,
+      })`sips -z 512 512 ${sourcePng} --out ${iconPngPath}`,
     );
 
-    yield* generateMacIconSet(iconSource, iconIcnsPath, tmpRoot, path, verbose);
+    yield* generateMacIconSet(sourcePng, iconIcnsPath, tmpRoot, path, verbose);
   });
 }
 
-function stageLinuxIcons(stageResourcesDir: string) {
+function stageLinuxIcons(stageResourcesDir: string, sourcePng: string) {
   return Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const iconSource = yield* ProductionLinuxIconSource;
-    if (!(yield* fs.exists(iconSource))) {
+    if (!(yield* fs.exists(sourcePng))) {
       return yield* new BuildScriptError({
-        message: `Production icon source is missing at ${iconSource}`,
+        message: `Desktop Linux icon source is missing at ${sourcePng}`,
       });
     }
 
     const iconPath = path.join(stageResourcesDir, "icon.png");
-    yield* fs.copyFile(iconSource, iconPath);
+    yield* fs.copyFile(sourcePng, iconPath);
   });
 }
 
-function stageWindowsIcons(stageResourcesDir: string) {
+function stageWindowsIcons(stageResourcesDir: string, sourceIco: string) {
   return Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const iconSource = yield* ProductionWindowsIconSource;
-    if (!(yield* fs.exists(iconSource))) {
+    if (!(yield* fs.exists(sourceIco))) {
       return yield* new BuildScriptError({
-        message: `Production Windows icon source is missing at ${iconSource}`,
+        message: `Desktop Windows icon source is missing at ${sourceIco}`,
       });
     }
 
     const iconPath = path.join(stageResourcesDir, "icon.ico");
-    yield* fs.copyFile(iconSource, iconPath);
+    yield* fs.copyFile(sourceIco, iconPath);
   });
 }
 
@@ -426,7 +484,7 @@ function validateBundledClientAssets(clientDir: string) {
   });
 }
 
-function resolveDesktopRuntimeDependencies(
+export function resolveDesktopRuntimeDependencies(
   dependencies: Record<string, string> | undefined,
   catalog: Record<string, string>,
 ): Record<string, string> {
@@ -435,18 +493,22 @@ function resolveDesktopRuntimeDependencies(
   }
 
   const runtimeDependencies = Object.fromEntries(
-    Object.entries(dependencies).filter(([dependencyName]) => dependencyName !== "electron"),
+    Object.entries(dependencies).filter(
+      ([dependencyName, dependencySpec]) =>
+        dependencyName !== "electron" && !dependencySpec.startsWith("workspace:"),
+    ),
   );
 
   return resolveCatalogDependencies(runtimeDependencies, catalog, "apps/desktop");
 }
 
-function resolveGitHubPublishConfig():
+function resolveGitHubPublishConfig(updateChannel: "latest" | "nightly"):
   | {
       readonly provider: "github";
       readonly owner: string;
       readonly repo: string;
-      readonly releaseType: "release";
+      readonly releaseType: "release" | "prerelease";
+      readonly channel?: "nightly";
     }
   | undefined {
   const rawRepo =
@@ -462,34 +524,66 @@ function resolveGitHubPublishConfig():
     provider: "github",
     owner,
     repo,
-    releaseType: "release",
+    releaseType: updateChannel === "nightly" ? "prerelease" : "release",
+    ...(updateChannel === "nightly" ? { channel: "nightly" as const } : {}),
   };
 }
 
+export function resolveDesktopUpdateChannel(version: string): "latest" | "nightly" {
+  return /-nightly\.\d{8}\.\d+$/.test(version) ? "nightly" : "latest";
+}
+
+export function resolveDesktopBuildIconAssets(version: string): DesktopBuildIconAssets {
+  if (resolveDesktopUpdateChannel(version) === "nightly") {
+    return {
+      macIconPng: BRAND_ASSET_PATHS.nightlyMacIconPng,
+      linuxIconPng: BRAND_ASSET_PATHS.nightlyLinuxIconPng,
+      windowsIconIco: BRAND_ASSET_PATHS.nightlyWindowsIconIco,
+    };
+  }
+
+  return {
+    macIconPng: BRAND_ASSET_PATHS.productionMacIconPng,
+    linuxIconPng: BRAND_ASSET_PATHS.productionLinuxIconPng,
+    windowsIconIco: BRAND_ASSET_PATHS.productionWindowsIconIco,
+  };
+}
+
+export function resolveMockUpdateServerUrl(mockUpdateServerPort: number | undefined): string {
+  return `http://localhost:${mockUpdateServerPort ?? 3000}`;
+}
+
+export function resolveDesktopProductName(version: string): string {
+  return resolveDesktopUpdateChannel(version) === "nightly"
+    ? "T3 Code (Nightly)"
+    : (desktopPackageJson.productName ?? "T3 Code");
+}
+
 const createBuildConfig = Effect.fn("createBuildConfig")(function* (
   platform: typeof BuildPlatform.Type,
   target: string,
-  productName: string,
+  version: string,
   signed: boolean,
   mockUpdates: boolean,
-  mockUpdateServerPort: string | undefined,
+  mockUpdateServerPort: number | undefined,
 ) {
   const buildConfig: Record<string, unknown> = {
     appId: "com.t3tools.t3code",
-    productName,
+    productName: resolveDesktopProductName(version),
     artifactName: "T3-Code-${version}-${arch}.${ext}",
     directories: {
       buildResources: "apps/desktop/resources",
     },
   };
-  const publishConfig = resolveGitHubPublishConfig();
+  const updateChannel = resolveDesktopUpdateChannel(version);
+  const publishConfig = resolveGitHubPublishConfig(updateChannel);
   if (publishConfig) {
     buildConfig.publish = [publishConfig];
   } else if (mockUpdates) {
     buildConfig.publish = [
       {
         provider: "generic",
-        url: `http://localhost:${mockUpdateServerPort ?? 3000}`,
+        url: resolveMockUpdateServerUrl(mockUpdateServerPort),
       },
     ];
   }
@@ -517,12 +611,15 @@ const createBuildConfig = Effect.fn("createBuildConfig")(function* (
   }
 
   if (platform === "win") {
+    buildConfig.npmRebuild = false;
     const winConfig: Record<string, unknown> = {
       target: [target],
       icon: "icon.ico",
     };
     if (signed) {
       winConfig.azureSignOptions = yield* AzureTrustedSigningOptionsConfig;
+    } else {
+      winConfig.signAndEditExecutable = false;
     }
     buildConfig.win = winConfig;
   }
@@ -533,20 +630,21 @@ const createBuildConfig = Effect.fn("createBuildConfig")(function* (
 const assertPlatformBuildResources = Effect.fn("assertPlatformBuildResources")(function* (
   platform: typeof BuildPlatform.Type,
   stageResourcesDir: string,
+  iconAssets: DesktopBuildIconAssets,
   verbose: boolean,
 ) {
   if (platform === "mac") {
-    yield* stageMacIcons(stageResourcesDir, verbose);
+    yield* stageMacIcons(stageResourcesDir, iconAssets.macIconPng, verbose);
     return;
   }
 
   if (platform === "linux") {
-    yield* stageLinuxIcons(stageResourcesDir);
+    yield* stageLinuxIcons(stageResourcesDir, iconAssets.linuxIconPng);
     return;
   }
 
   if (platform === "win") {
-    yield* stageWindowsIcons(stageResourcesDir);
+    yield* stageWindowsIcons(stageResourcesDir, iconAssets.windowsIconIco);
   }
 });
 
@@ -614,7 +712,8 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
   });
 
   const appVersion = options.version ?? serverPackageJson.version;
-  const commitHash = resolveGitCommitHash(repoRoot);
+  const iconAssets = resolveDesktopBuildIconAssets(appVersion);
+  const commitHash = yield* resolveGitCommitHash(repoRoot);
   const mkdir = options.keepStage ? fs.makeTempDirectory : fs.makeTempDirectoryScoped;
   const stageRoot = yield* mkdir({
     prefix: `t3code-desktop-${options.platform}-stage-`,
@@ -665,7 +764,16 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
   yield* fs.copy(distDirs.desktopResources, stageResourcesDir);
   yield* fs.copy(distDirs.serverDist, path.join(stageAppDir, "apps/server/dist"));
 
-  yield* assertPlatformBuildResources(options.platform, stageResourcesDir, options.verbose);
+  yield* assertPlatformBuildResources(
+    options.platform,
+    stageResourcesDir,
+    {
+      macIconPng: path.join(repoRoot, iconAssets.macIconPng),
+      linuxIconPng: path.join(repoRoot, iconAssets.linuxIconPng),
+      windowsIconIco: path.join(repoRoot, iconAssets.windowsIconIco),
+    },
+    options.verbose,
+  );
 
   // electron-builder is filtering out stageResourcesDir directory in the AppImage for production
   yield* fs.copy(stageResourcesDir, path.join(stageAppDir, "apps/desktop/prod-resources"));
@@ -678,11 +786,11 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
     private: true,
     description: "T3 Code desktop build",
     author: "T3 Tools",
-    main: "apps/desktop/dist-electron/main.js",
+    main: "apps/desktop/dist-electron/main.cjs",
     build: yield* createBuildConfig(
       options.platform,
       options.target,
-      desktopPackageJson.productName ?? "T3 Code",
+      appVersion,
       options.signed,
       options.mockUpdates,
       options.mockUpdateServerPort,
@@ -707,7 +815,7 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
       ...commandOutputOptions(options.verbose),
       // Windows needs shell mode to resolve .cmd shims (e.g. bun.cmd).
       shell: process.platform === "win32",
-    })`bun install --production`,
+    })`bun install --production --omit optional`,
   );
 
   const buildEnv: NodeJS.ProcessEnv = {
@@ -728,7 +836,7 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
   }
 
   if (process.platform === "win32") {
-    const python = resolvePythonForNodeGyp();
+    const python = yield* resolvePythonForNodeGyp();
     if (python) {
       buildEnv.PYTHON = python;
       buildEnv.npm_config_python = python;
@@ -747,7 +855,7 @@ const buildDesktopArtifact = Effect.fn("buildDesktopArtifact")(function* (
       ...commandOutputOptions(options.verbose),
       // Windows needs shell mode to resolve .cmd shims.
       shell: process.platform === "win32",
-    })`bunx electron-builder ${platformConfig.cliFlag} --${options.arch} --publish never`,
+    })`bun x --install=fallback electron-builder ${platformConfig.cliFlag} --${options.arch} --publish never`,
   );
 
   const stageDistDir = path.join(stageAppDir, "dist");
@@ -829,7 +937,8 @@ const buildDesktopArtifactCli = Command.make("build-desktop-artifact", {
     Flag.withDescription("Enable mock updates (env: T3CODE_DESKTOP_MOCK_UPDATES)."),
     Flag.optional,
   ),
-  mockUpdateServerPort: Flag.string("mock-update-server-port").pipe(
+  mockUpdateServerPort: Flag.integer("mock-update-server-port").pipe(
+    Flag.withSchema(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }))),
     Flag.withDescription("Mock update server port (env: T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT)."),
     Flag.optional,
   ),
diff --git a/scripts/dev-runner.test.ts b/scripts/dev-runner.test.ts
index b880f1bca45..724b328c4c6 100644
--- a/scripts/dev-runner.test.ts
+++ b/scripts/dev-runner.test.ts
@@ -1,8 +1,8 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { homedir } from "node:os";
-import { resolve } from "node:path";
+import * as NodeOS from "node:os";
 import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
 
 import {
   checkPortAvailabilityOnHosts,
@@ -49,6 +49,7 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
   describe("createDevRunnerEnv", () => {
     it.effect("defaults T3CODE_HOME to ~/.t3 when not provided", () =>
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const env = yield* createDevRunnerEnv({
           mode: "dev",
           baseEnv: {},
@@ -63,12 +64,13 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
           devUrl: undefined,
         });
 
-        assert.equal(env.T3CODE_HOME, resolve(homedir(), ".t3"));
+        assert.equal(env.T3CODE_HOME, path.resolve(NodeOS.homedir(), ".t3"));
       }),
     );
 
     it.effect("supports explicit typed overrides", () =>
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const env = yield* createDevRunnerEnv({
           mode: "dev:server",
           baseEnv: {},
@@ -83,7 +85,7 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
           devUrl: new URL("http://localhost:7331"),
         });
 
-        assert.equal(env.T3CODE_HOME, resolve("/tmp/custom-t3"));
+        assert.equal(env.T3CODE_HOME, path.resolve("/tmp/custom-t3"));
         assert.equal(env.T3CODE_PORT, "4222");
         assert.equal(env.VITE_HTTP_URL, "http://localhost:4222");
         assert.equal(env.VITE_WS_URL, "ws://localhost:4222");
@@ -142,6 +144,7 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
 
     it.effect("uses custom t3Home when provided", () =>
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const env = yield* createDevRunnerEnv({
           mode: "dev",
           baseEnv: {},
@@ -156,12 +159,13 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
           devUrl: undefined,
         });
 
-        assert.equal(env.T3CODE_HOME, resolve("/tmp/my-t3"));
+        assert.equal(env.T3CODE_HOME, path.resolve("/tmp/my-t3"));
       }),
     );
 
     it.effect("pins desktop dev to a stable backend port and websocket url", () =>
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const env = yield* createDevRunnerEnv({
           mode: "dev:desktop",
           baseEnv: {
@@ -182,7 +186,7 @@ it.layer(NodeServices.layer)("dev-runner", (it) => {
           devUrl: undefined,
         });
 
-        assert.equal(env.T3CODE_HOME, resolve("/tmp/my-t3"));
+        assert.equal(env.T3CODE_HOME, path.resolve("/tmp/my-t3"));
         assert.equal(env.PORT, "5733");
         assert.equal(env.VITE_DEV_SERVER_URL, "http://127.0.0.1:5733");
         assert.equal(env.HOST, "127.0.0.1");
diff --git a/scripts/dev-runner.ts b/scripts/dev-runner.ts
index 4d34fe389e9..58bbb1ac35e 100644
--- a/scripts/dev-runner.ts
+++ b/scripts/dev-runner.ts
@@ -1,11 +1,19 @@
 #!/usr/bin/env node
 
-import { homedir } from "node:os";
+import * as NodeOS from "node:os";
 
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { NetService } from "@t3tools/shared/Net";
-import { Config, Data, Effect, Hash, Layer, Logger, Option, Path, Schema } from "effect";
+import * as NetService from "@t3tools/shared/Net";
+import * as Config from "effect/Config";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Hash from "effect/Hash";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { ChildProcess } from "effect/unstable/process";
 
@@ -17,7 +25,7 @@ const DESKTOP_DEV_LOOPBACK_HOST = "127.0.0.1";
 const DEV_PORT_PROBE_HOSTS = ["127.0.0.1", "0.0.0.0", "::1", "::"] as const;
 
 export const DEFAULT_T3_HOME = Effect.map(Effect.service(Path.Path), (path) =>
-  path.join(homedir(), ".t3"),
+  path.join(NodeOS.homedir(), ".t3"),
 );
 
 const MODE_ARGS = {
@@ -238,22 +246,22 @@ export function checkPortAvailabilityOnHosts<R>(
   });
 }
 
-const defaultCheckPortAvailability: PortAvailabilityCheck<NetService> = (port) =>
+const defaultCheckPortAvailability: PortAvailabilityCheck<NetService.NetService> = (port) =>
   Effect.gen(function* () {
-    const net = yield* NetService;
+    const net = yield* NetService.NetService;
     return yield* checkPortAvailabilityOnHosts(port, DEV_PORT_PROBE_HOSTS, (candidatePort, host) =>
       net.canListenOnHost(candidatePort, host),
     );
   });
 
-interface FindFirstAvailableOffsetInput<R = NetService> {
+interface FindFirstAvailableOffsetInput<R = NetService.NetService> {
   readonly startOffset: number;
   readonly requireServerPort: boolean;
   readonly requireWebPort: boolean;
   readonly checkPortAvailability?: PortAvailabilityCheck<R>;
 }
 
-export function findFirstAvailableOffset<R = NetService>({
+export function findFirstAvailableOffset<R = NetService.NetService>({
   startOffset,
   requireServerPort,
   requireWebPort,
@@ -300,7 +308,7 @@ export function findFirstAvailableOffset<R = NetService>({
   });
 }
 
-interface ResolveModePortOffsetsInput<R = NetService> {
+interface ResolveModePortOffsetsInput<R = NetService.NetService> {
   readonly mode: DevMode;
   readonly startOffset: number;
   readonly hasExplicitServerPort: boolean;
@@ -308,7 +316,7 @@ interface ResolveModePortOffsetsInput<R = NetService> {
   readonly checkPortAvailability?: PortAvailabilityCheck<R>;
 }
 
-export function resolveModePortOffsets<R = NetService>({
+export function resolveModePortOffsets<R = NetService.NetService>({
   mode,
   startOffset,
   hasExplicitServerPort,
@@ -523,11 +531,10 @@ const cliRuntimeLayer = Layer.mergeAll(
   NetService.layer,
 );
 
-const runtimeProgram = Command.run(devRunnerCli, { version: "0.0.0" }).pipe(
-  Effect.scoped,
-  Effect.provide(cliRuntimeLayer),
-);
-
 if (import.meta.main) {
-  NodeRuntime.runMain(runtimeProgram);
+  Command.run(devRunnerCli, { version: "0.0.0" }).pipe(
+    Effect.scoped,
+    Effect.provide(cliRuntimeLayer),
+    NodeRuntime.runMain,
+  );
 }
diff --git a/scripts/lib/brand-assets.test.ts b/scripts/lib/brand-assets.test.ts
new file mode 100644
index 00000000000..0f463b3f024
--- /dev/null
+++ b/scripts/lib/brand-assets.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BRAND_ASSET_PATHS,
+  DEVELOPMENT_ICON_OVERRIDES,
+  PUBLISH_ICON_OVERRIDES,
+  resolveWebAssetBrandForChannel,
+  resolveWebIconOverrides,
+} from "./brand-assets.ts";
+
+describe("brand-assets", () => {
+  it("maps server publish web assets to production icons", () => {
+    expect(PUBLISH_ICON_OVERRIDES).toEqual([
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebFaviconIco,
+        targetRelativePath: "dist/client/favicon.ico",
+      },
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon16Png,
+        targetRelativePath: "dist/client/favicon-16x16.png",
+      },
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon32Png,
+        targetRelativePath: "dist/client/favicon-32x32.png",
+      },
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
+        targetRelativePath: "dist/client/apple-touch-icon.png",
+      },
+    ]);
+  });
+
+  it("maps server build web assets to development icons", () => {
+    expect(DEVELOPMENT_ICON_OVERRIDES[0]).toEqual({
+      sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFaviconIco,
+      targetRelativePath: "dist/client/favicon.ico",
+    });
+  });
+
+  it("can target hosted web dist directly", () => {
+    expect(resolveWebIconOverrides("production", "apps/web/dist")).toContainEqual({
+      sourceRelativePath: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
+      targetRelativePath: "apps/web/dist/apple-touch-icon.png",
+    });
+  });
+
+  it("maps hosted nightly web assets to nightly icons", () => {
+    expect(resolveWebIconOverrides("nightly", "apps/web/dist")).toContainEqual({
+      sourceRelativePath: BRAND_ASSET_PATHS.nightlyWebFaviconIco,
+      targetRelativePath: "apps/web/dist/favicon.ico",
+    });
+  });
+
+  it("maps hosted release channels to web asset brands", () => {
+    expect(resolveWebAssetBrandForChannel("latest")).toBe("production");
+    expect(resolveWebAssetBrandForChannel("nightly")).toBe("nightly");
+  });
+});
diff --git a/scripts/lib/brand-assets.ts b/scripts/lib/brand-assets.ts
index 990d05c321f..87b0cab219e 100644
--- a/scripts/lib/brand-assets.ts
+++ b/scripts/lib/brand-assets.ts
@@ -6,6 +6,16 @@ export const BRAND_ASSET_PATHS = {
   productionWebFavicon16Png: "assets/prod/t3-black-web-favicon-16x16.png",
   productionWebFavicon32Png: "assets/prod/t3-black-web-favicon-32x32.png",
   productionWebAppleTouchIconPng: "assets/prod/t3-black-web-apple-touch-180.png",
+
+  nightlyMacIconPng: "assets/nightly/blueprint-macos-1024.png",
+  nightlyLinuxIconPng: "assets/nightly/blueprint-universal-1024.png",
+  nightlyWindowsIconIco: "assets/nightly/blueprint-windows.ico",
+  nightlyWebFaviconIco: "assets/nightly/blueprint-web-favicon.ico",
+  nightlyWebFavicon16Png: "assets/nightly/blueprint-web-favicon-16x16.png",
+  nightlyWebFavicon32Png: "assets/nightly/blueprint-web-favicon-32x32.png",
+  nightlyWebAppleTouchIconPng: "assets/nightly/blueprint-web-apple-touch-180.png",
+
+  developmentDesktopIconPng: "assets/dev/blueprint-macos-1024.png",
   developmentWindowsIconIco: "assets/dev/blueprint-windows.ico",
   developmentWebFaviconIco: "assets/dev/blueprint-web-favicon.ico",
   developmentWebFavicon16Png: "assets/dev/blueprint-web-favicon-16x16.png",
@@ -13,45 +23,74 @@ export const BRAND_ASSET_PATHS = {
   developmentWebAppleTouchIconPng: "assets/dev/blueprint-web-apple-touch-180.png",
 } as const;
 
+export type WebAssetBrand = "development" | "nightly" | "production";
+
+export const WEB_ASSET_CHANNELS = ["latest", "nightly"] as const;
+
+export type WebAssetChannel = (typeof WEB_ASSET_CHANNELS)[number];
+
+export function resolveWebAssetBrandForChannel(channel: WebAssetChannel): WebAssetBrand {
+  return channel === "nightly" ? "nightly" : "production";
+}
+
 export interface IconOverride {
   readonly sourceRelativePath: string;
   readonly targetRelativePath: string;
 }
 
-export const DEVELOPMENT_ICON_OVERRIDES: ReadonlyArray<IconOverride> = [
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFaviconIco,
-    targetRelativePath: "dist/client/favicon.ico",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFavicon16Png,
-    targetRelativePath: "dist/client/favicon-16x16.png",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFavicon32Png,
-    targetRelativePath: "dist/client/favicon-32x32.png",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebAppleTouchIconPng,
-    targetRelativePath: "dist/client/apple-touch-icon.png",
-  },
-];
+const WEB_ICON_TARGET_FILENAMES = {
+  faviconIco: "favicon.ico",
+  favicon16Png: "favicon-16x16.png",
+  favicon32Png: "favicon-32x32.png",
+  appleTouchIconPng: "apple-touch-icon.png",
+} as const;
 
-export const PUBLISH_ICON_OVERRIDES: ReadonlyArray<IconOverride> = [
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebFaviconIco,
-    targetRelativePath: "dist/client/favicon.ico",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon16Png,
-    targetRelativePath: "dist/client/favicon-16x16.png",
+const WEB_ICON_SOURCE_PATHS_BY_BRAND = {
+  development: {
+    faviconIco: BRAND_ASSET_PATHS.developmentWebFaviconIco,
+    favicon16Png: BRAND_ASSET_PATHS.developmentWebFavicon16Png,
+    favicon32Png: BRAND_ASSET_PATHS.developmentWebFavicon32Png,
+    appleTouchIconPng: BRAND_ASSET_PATHS.developmentWebAppleTouchIconPng,
   },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon32Png,
-    targetRelativePath: "dist/client/favicon-32x32.png",
+  nightly: {
+    faviconIco: BRAND_ASSET_PATHS.nightlyWebFaviconIco,
+    favicon16Png: BRAND_ASSET_PATHS.nightlyWebFavicon16Png,
+    favicon32Png: BRAND_ASSET_PATHS.nightlyWebFavicon32Png,
+    appleTouchIconPng: BRAND_ASSET_PATHS.nightlyWebAppleTouchIconPng,
   },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
-    targetRelativePath: "dist/client/apple-touch-icon.png",
+  production: {
+    faviconIco: BRAND_ASSET_PATHS.productionWebFaviconIco,
+    favicon16Png: BRAND_ASSET_PATHS.productionWebFavicon16Png,
+    favicon32Png: BRAND_ASSET_PATHS.productionWebFavicon32Png,
+    appleTouchIconPng: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
   },
-];
+} as const satisfies Record<WebAssetBrand, Record<keyof typeof WEB_ICON_TARGET_FILENAMES, string>>;
+
+export function resolveWebIconOverrides(
+  brand: WebAssetBrand,
+  targetDirectory: string,
+): ReadonlyArray<IconOverride> {
+  const sourcePaths = WEB_ICON_SOURCE_PATHS_BY_BRAND[brand];
+  return [
+    {
+      sourceRelativePath: sourcePaths.faviconIco,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.faviconIco}`,
+    },
+    {
+      sourceRelativePath: sourcePaths.favicon16Png,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.favicon16Png}`,
+    },
+    {
+      sourceRelativePath: sourcePaths.favicon32Png,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.favicon32Png}`,
+    },
+    {
+      sourceRelativePath: sourcePaths.appleTouchIconPng,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.appleTouchIconPng}`,
+    },
+  ];
+}
+
+export const DEVELOPMENT_ICON_OVERRIDES = resolveWebIconOverrides("development", "dist/client");
+
+export const PUBLISH_ICON_OVERRIDES = resolveWebIconOverrides("production", "dist/client");
diff --git a/scripts/lib/build-target-arch.test.ts b/scripts/lib/build-target-arch.test.ts
new file mode 100644
index 00000000000..56251d3ffd1
--- /dev/null
+++ b/scripts/lib/build-target-arch.test.ts
@@ -0,0 +1,61 @@
+import { assert, describe, it } from "@effect/vitest";
+
+import { getDefaultBuildArch, resolveHostProcessArch } from "./build-target-arch.ts";
+
+describe("build-target-arch", () => {
+  it("prefers arm64 for Windows-on-Arm hosts running x64 emulation", () => {
+    // Windows-on-Arm can run an x64 Node process under emulation while still
+    // exposing the real host CPU via PROCESSOR_ARCHITEW6432.
+    const hostArch = resolveHostProcessArch("win32", "x64", {
+      PROCESSOR_ARCHITECTURE: "AMD64", // The currently running Node process is x64.
+      PROCESSOR_ARCHITEW6432: "ARM64", // Windows exposes the real host CPU here when x64 runs under ARM emulation.
+    });
+
+    assert.equal(hostArch, "arm64");
+  });
+
+  it("falls back to x64 for native x64 Windows hosts", () => {
+    const hostArch = resolveHostProcessArch("win32", "x64", {
+      PROCESSOR_ARCHITECTURE: "AMD64", // Both the process and the Windows host are native x64.
+    });
+
+    assert.equal(hostArch, "x64");
+  });
+
+  it("keeps arm64 when the current process is already native arm64", () => {
+    const hostArch = resolveHostProcessArch("win32", "arm64", {});
+
+    assert.equal(hostArch, "arm64");
+  });
+
+  it("uses the resolved host arch when selecting the default Windows build arch", () => {
+    // This mirrors the packaging script's default-path behavior: the current
+    // process is x64, but the machine itself is ARM64, so the default build
+    // target should be win-arm64 rather than win-x64.
+    const arch = getDefaultBuildArch(
+      "win",
+      "x64",
+      {
+        PROCESSOR_ARCHITECTURE: "AMD64", // The currently running Node process is x64.
+        PROCESSOR_ARCHITEW6432: "ARM64", // The process is x64, but the actual Windows host is ARM64.
+      },
+      { archChoices: ["x64", "arm64"] },
+    );
+
+    assert.equal(arch, "arm64");
+  });
+
+  it("does not apply Windows host env heuristics for non-Windows targets", () => {
+    const arch = getDefaultBuildArch(
+      "linux",
+      "x64",
+      {
+        PROCESSOR_ARCHITECTURE: "AMD64",
+        PROCESSOR_ARCHITEW6432: "ARM64",
+      },
+      { archChoices: ["x64", "arm64"] },
+    );
+
+    assert.equal(arch, "x64");
+  });
+});
diff --git a/scripts/lib/build-target-arch.ts b/scripts/lib/build-target-arch.ts
new file mode 100644
index 00000000000..8c39648414a
--- /dev/null
+++ b/scripts/lib/build-target-arch.ts
@@ -0,0 +1,50 @@
+export type BuildArch = "arm64" | "x64" | "universal";
+export type BuildPlatform = "mac" | "linux" | "win";
+
+interface PlatformConfig {
+  readonly archChoices: ReadonlyArray<BuildArch>;
+}
+
+function normalizeWindowsArch(value: string | undefined): BuildArch | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) return undefined;
+  if (normalized.includes("arm64") || normalized === "aarch64") return "arm64";
+  if (normalized.includes("amd64") || normalized.includes("x64")) return "x64";
+  return undefined;
+}
+
+export function resolveHostProcessArch(
+  platform: NodeJS.Platform,
+  processArch: NodeJS.Architecture,
+  env: NodeJS.ProcessEnv,
+): BuildArch | undefined {
+  if (processArch === "arm64") return "arm64";
+  if (processArch === "x64") {
+    if (platform !== "win32") return "x64";
+
+    // On Windows-on-Arm, x64 Node/Bun can run under emulation while the host
+    // still reports ARM64 via the processor environment variables.
+    return (
+      normalizeWindowsArch(env.PROCESSOR_ARCHITEW6432) ??
+      normalizeWindowsArch(env.PROCESSOR_ARCHITECTURE) ??
+      "x64"
+    );
+  }
+  return undefined;
+}
+
+export function getDefaultBuildArch(
+  platform: BuildPlatform,
+  processArch: NodeJS.Architecture,
+  env: NodeJS.ProcessEnv,
+  platformConfig: PlatformConfig,
+): BuildArch {
+  const hostPlatform: NodeJS.Platform =
+    platform === "win" ? "win32" : platform === "mac" ? "darwin" : "linux";
+  const hostArch = resolveHostProcessArch(hostPlatform, processArch, env);
+  if (hostArch && platformConfig.archChoices.includes(hostArch)) {
+    return hostArch;
+  }
+
+  return platformConfig.archChoices[0] ?? "x64";
+}
diff --git a/scripts/merge-mac-update-manifests.ts b/scripts/lib/update-manifest.ts
similarity index 58%
rename from scripts/merge-mac-update-manifests.ts
rename to scripts/lib/update-manifest.ts
index c59bc76b9b0..191a3c0e535 100644
--- a/scripts/merge-mac-update-manifests.ts
+++ b/scripts/lib/update-manifest.ts
@@ -1,23 +1,19 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-interface MacUpdateFile {
+export interface UpdateManifestFile {
   readonly url: string;
   readonly sha512: string;
   readonly size: number;
 }
 
-type MacUpdateScalar = string | number | boolean;
+export type UpdateManifestScalar = string | number | boolean;
 
-interface MacUpdateManifest {
+export interface UpdateManifest {
   readonly version: string;
   readonly releaseDate: string;
-  readonly files: ReadonlyArray<MacUpdateFile>;
-  readonly extras: Readonly<Record<string, MacUpdateScalar>>;
+  readonly files: ReadonlyArray<UpdateManifestFile>;
+  readonly extras: Readonly<Record<string, UpdateManifestScalar>>;
 }
 
-interface MutableMacUpdateFile {
+interface MutableUpdateManifestFile {
   url?: string;
   sha512?: string;
   size?: number;
@@ -31,10 +27,11 @@ function stripSingleQuotes(value: string): string {
 }
 
 function parseFileRecord(
-  currentFile: MutableMacUpdateFile | null,
+  currentFile: MutableUpdateManifestFile | null,
   sourcePath: string,
   lineNumber: number,
-): MacUpdateFile | null {
+  platformLabel: string,
+): UpdateManifestFile | null {
   if (currentFile === null) {
     return null;
   }
@@ -44,7 +41,7 @@ function parseFileRecord(
     typeof currentFile.size !== "number"
   ) {
     throw new Error(
-      `Invalid macOS update manifest at ${sourcePath}:${lineNumber}: incomplete file entry.`,
+      `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: incomplete file entry.`,
     );
   }
   return {
@@ -54,7 +51,7 @@ function parseFileRecord(
   };
 }
 
-function parseScalarValue(rawValue: string): MacUpdateScalar {
+function parseScalarValue(rawValue: string): UpdateManifestScalar {
   const trimmed = rawValue.trim();
   const isQuoted = trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2;
   const value = isQuoted ? trimmed.slice(1, -1).replace(/''/g, "'") : trimmed;
@@ -67,14 +64,18 @@ function parseScalarValue(rawValue: string): MacUpdateScalar {
   return value;
 }
 
-export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpdateManifest {
+export function parseUpdateManifest(
+  raw: string,
+  sourcePath: string,
+  platformLabel: string,
+): UpdateManifest {
   const lines = raw.split(/\r?\n/);
-  const files: MacUpdateFile[] = [];
-  const extras: Record<string, MacUpdateScalar> = {};
+  const files: UpdateManifestFile[] = [];
+  const extras: Record<string, UpdateManifestScalar> = {};
   let version: string | null = null;
   let releaseDate: string | null = null;
   let inFiles = false;
-  let currentFile: MutableMacUpdateFile | null = null;
+  let currentFile: MutableUpdateManifestFile | null = null;
 
   for (const [index, rawLine] of lines.entries()) {
     const lineNumber = index + 1;
@@ -83,7 +84,7 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
 
     const fileUrlMatch = line.match(/^  - url:\s*(.+)$/);
     if (fileUrlMatch?.[1]) {
-      const finalized = parseFileRecord(currentFile, sourcePath, lineNumber);
+      const finalized = parseFileRecord(currentFile, sourcePath, lineNumber, platformLabel);
       if (finalized) files.push(finalized);
       currentFile = { url: stripSingleQuotes(fileUrlMatch[1].trim()) };
       inFiles = true;
@@ -94,7 +95,7 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
     if (fileShaMatch?.[1]) {
       if (currentFile === null) {
         throw new Error(
-          `Invalid macOS update manifest at ${sourcePath}:${lineNumber}: sha512 without a file entry.`,
+          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: sha512 without a file entry.`,
         );
       }
       currentFile.sha512 = stripSingleQuotes(fileShaMatch[1].trim());
@@ -105,7 +106,7 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
     if (fileSizeMatch?.[1]) {
       if (currentFile === null) {
         throw new Error(
-          `Invalid macOS update manifest at ${sourcePath}:${lineNumber}: size without a file entry.`,
+          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: size without a file entry.`,
         );
       }
       currentFile.size = Number(fileSizeMatch[1]);
@@ -118,7 +119,7 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
     }
 
     if (inFiles && currentFile !== null) {
-      const finalized = parseFileRecord(currentFile, sourcePath, lineNumber);
+      const finalized = parseFileRecord(currentFile, sourcePath, lineNumber, platformLabel);
       if (finalized) files.push(finalized);
       currentFile = null;
     }
@@ -127,7 +128,7 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
     const topLevelMatch = line.match(/^([A-Za-z][A-Za-z0-9]*):\s*(.+)$/);
     if (!topLevelMatch?.[1] || topLevelMatch[2] === undefined) {
       throw new Error(
-        `Invalid macOS update manifest at ${sourcePath}:${lineNumber}: unsupported line '${line}'.`,
+        `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: unsupported line '${line}'.`,
       );
     }
 
@@ -137,7 +138,7 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
     if (key === "version") {
       if (typeof value !== "string") {
         throw new Error(
-          `Invalid macOS update manifest at ${sourcePath}:${lineNumber}: version must be a string.`,
+          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: version must be a string.`,
         );
       }
       version = value;
@@ -147,7 +148,7 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
     if (key === "releaseDate") {
       if (typeof value !== "string") {
         throw new Error(
-          `Invalid macOS update manifest at ${sourcePath}:${lineNumber}: releaseDate must be a string.`,
+          `Invalid ${platformLabel} update manifest at ${sourcePath}:${lineNumber}: releaseDate must be a string.`,
         );
       }
       releaseDate = value;
@@ -161,17 +162,19 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
     extras[key] = value;
   }
 
-  const finalized = parseFileRecord(currentFile, sourcePath, lines.length);
+  const finalized = parseFileRecord(currentFile, sourcePath, lines.length, platformLabel);
   if (finalized) files.push(finalized);
 
   if (!version) {
-    throw new Error(`Invalid macOS update manifest at ${sourcePath}: missing version.`);
+    throw new Error(`Invalid ${platformLabel} update manifest at ${sourcePath}: missing version.`);
   }
   if (!releaseDate) {
-    throw new Error(`Invalid macOS update manifest at ${sourcePath}: missing releaseDate.`);
+    throw new Error(
+      `Invalid ${platformLabel} update manifest at ${sourcePath}: missing releaseDate.`,
+    );
   }
   if (files.length === 0) {
-    throw new Error(`Invalid macOS update manifest at ${sourcePath}: missing files.`);
+    throw new Error(`Invalid ${platformLabel} update manifest at ${sourcePath}: missing files.`);
   }
 
   return {
@@ -183,16 +186,17 @@ export function parseMacUpdateManifest(raw: string, sourcePath: string): MacUpda
 }
 
 function mergeExtras(
-  primary: Readonly<Record<string, MacUpdateScalar>>,
-  secondary: Readonly<Record<string, MacUpdateScalar>>,
-): Record<string, MacUpdateScalar> {
-  const merged: Record<string, MacUpdateScalar> = { ...primary };
+  primary: Readonly<Record<string, UpdateManifestScalar>>,
+  secondary: Readonly<Record<string, UpdateManifestScalar>>,
+  platformLabel: string,
+): Record<string, UpdateManifestScalar> {
+  const merged: Record<string, UpdateManifestScalar> = { ...primary };
 
   for (const [key, value] of Object.entries(secondary)) {
     const existing = merged[key];
     if (existing !== undefined && existing !== value) {
       throw new Error(
-        `Cannot merge macOS update manifests: conflicting '${key}' values ('${existing}' vs '${value}').`,
+        `Cannot merge ${platformLabel} update manifests: conflicting '${key}' values ('${existing}' vs '${value}').`,
       );
     }
     merged[key] = value;
@@ -201,22 +205,23 @@ function mergeExtras(
   return merged;
 }
 
-export function mergeMacUpdateManifests(
-  primary: MacUpdateManifest,
-  secondary: MacUpdateManifest,
-): MacUpdateManifest {
+export function mergeUpdateManifests(
+  primary: UpdateManifest,
+  secondary: UpdateManifest,
+  platformLabel: string,
+): UpdateManifest {
   if (primary.version !== secondary.version) {
     throw new Error(
-      `Cannot merge macOS update manifests with different versions (${primary.version} vs ${secondary.version}).`,
+      `Cannot merge ${platformLabel} update manifests with different versions (${primary.version} vs ${secondary.version}).`,
     );
   }
 
-  const filesByUrl = new Map<string, MacUpdateFile>();
+  const filesByUrl = new Map<string, UpdateManifestFile>();
   for (const file of [...primary.files, ...secondary.files]) {
     const existing = filesByUrl.get(file.url);
     if (existing && (existing.sha512 !== file.sha512 || existing.size !== file.size)) {
       throw new Error(
-        `Cannot merge macOS update manifests: conflicting file entry for ${file.url}.`,
+        `Cannot merge ${platformLabel} update manifests: conflicting file entry for ${file.url}.`,
       );
     }
     filesByUrl.set(file.url, file);
@@ -227,7 +232,7 @@ export function mergeMacUpdateManifests(
     releaseDate:
       primary.releaseDate >= secondary.releaseDate ? primary.releaseDate : secondary.releaseDate,
     files: [...filesByUrl.values()],
-    extras: mergeExtras(primary.extras, secondary.extras),
+    extras: mergeExtras(primary.extras, secondary.extras, platformLabel),
   };
 }
 
@@ -235,15 +240,20 @@ function quoteYamlString(value: string): string {
   return `'${value.replace(/'/g, "''")}'`;
 }
 
-function serializeScalarValue(value: MacUpdateScalar): string {
+function serializeScalarValue(value: UpdateManifestScalar): string {
   if (typeof value === "string") {
     return quoteYamlString(value);
   }
   return String(value);
 }
 
-export function serializeMacUpdateManifest(manifest: MacUpdateManifest): string {
-  const lines = [`version: ${manifest.version}`, "files:"];
+export function serializeUpdateManifest(
+  manifest: UpdateManifest,
+  options: {
+    readonly platformLabel: string;
+  },
+): string {
+  const lines = [`version: ${quoteYamlString(manifest.version)}`, "files:"];
 
   for (const file of manifest.files) {
     lines.push(`  - url: ${file.url}`);
@@ -254,7 +264,9 @@ export function serializeMacUpdateManifest(manifest: MacUpdateManifest): string
   for (const key of Object.keys(manifest.extras).toSorted()) {
     const value = manifest.extras[key];
     if (value === undefined) {
-      throw new Error(`Cannot serialize macOS update manifest: missing value for '${key}'.`);
+      throw new Error(
+        `Cannot serialize ${options.platformLabel} update manifest: missing value for '${key}'.`,
+      );
     }
     lines.push(`${key}: ${serializeScalarValue(value)}`);
   }
@@ -263,25 +275,3 @@ export function serializeMacUpdateManifest(manifest: MacUpdateManifest): string
   lines.push("");
   return lines.join("\n");
 }
-
-function main(args: ReadonlyArray<string>): void {
-  const [arm64PathArg, x64PathArg, outputPathArg] = args;
-  if (!arm64PathArg || !x64PathArg) {
-    throw new Error(
-      "Usage: node scripts/merge-mac-update-manifests.ts <latest-mac.yml> <latest-mac-x64.yml> [output-path]",
-    );
-  }
-
-  const arm64Path = resolve(arm64PathArg);
-  const x64Path = resolve(x64PathArg);
-  const outputPath = resolve(outputPathArg ?? arm64PathArg);
-
-  const arm64Manifest = parseMacUpdateManifest(readFileSync(arm64Path, "utf8"), arm64Path);
-  const x64Manifest = parseMacUpdateManifest(readFileSync(x64Path, "utf8"), x64Path);
-  const merged = mergeMacUpdateManifests(arm64Manifest, x64Manifest);
-  writeFileSync(outputPath, serializeMacUpdateManifest(merged));
-}
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  main(process.argv.slice(2));
-}
diff --git a/scripts/merge-mac-update-manifests.test.ts b/scripts/merge-mac-update-manifests.test.ts
deleted file mode 100644
index 22d2e7627e9..00000000000
--- a/scripts/merge-mac-update-manifests.test.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-import { assert, describe, it } from "@effect/vitest";
-
-import {
-  mergeMacUpdateManifests,
-  parseMacUpdateManifest,
-  serializeMacUpdateManifest,
-} from "./merge-mac-update-manifests.ts";
-
-describe("merge-mac-update-manifests", () => {
-  it("merges arm64 and x64 macOS update manifests into one multi-arch manifest", () => {
-    const arm64 = parseMacUpdateManifest(
-      `version: 0.0.4
-files:
-  - url: T3-Code-0.0.4-arm64.zip
-    sha512: arm64zip
-    size: 125621344
-  - url: T3-Code-0.0.4-arm64.dmg
-    sha512: arm64dmg
-    size: 131754935
-path: T3-Code-0.0.4-arm64.zip
-sha512: arm64zip
-releaseDate: '2026-03-07T10:32:14.587Z'
-`,
-      "latest-mac.yml",
-    );
-
-    const x64 = parseMacUpdateManifest(
-      `version: 0.0.4
-files:
-  - url: T3-Code-0.0.4-x64.zip
-    sha512: x64zip
-    size: 132000112
-  - url: T3-Code-0.0.4-x64.dmg
-    sha512: x64dmg
-    size: 138148807
-path: T3-Code-0.0.4-x64.zip
-sha512: x64zip
-releaseDate: '2026-03-07T10:36:07.540Z'
-`,
-      "latest-mac-x64.yml",
-    );
-
-    const merged = mergeMacUpdateManifests(arm64, x64);
-
-    assert.equal(merged.version, "0.0.4");
-    assert.equal(merged.releaseDate, "2026-03-07T10:36:07.540Z");
-    assert.deepStrictEqual(
-      merged.files.map((file) => file.url),
-      [
-        "T3-Code-0.0.4-arm64.zip",
-        "T3-Code-0.0.4-arm64.dmg",
-        "T3-Code-0.0.4-x64.zip",
-        "T3-Code-0.0.4-x64.dmg",
-      ],
-    );
-
-    const serialized = serializeMacUpdateManifest(merged);
-    assert.ok(!serialized.includes("path:"));
-    assert.equal((serialized.match(/- url:/g) ?? []).length, 4);
-  });
-
-  it("rejects mismatched manifest versions", () => {
-    const arm64 = parseMacUpdateManifest(
-      `version: 0.0.4
-files:
-  - url: T3-Code-0.0.4-arm64.zip
-    sha512: arm64zip
-    size: 1
-releaseDate: '2026-03-07T10:32:14.587Z'
-`,
-      "latest-mac.yml",
-    );
-
-    const x64 = parseMacUpdateManifest(
-      `version: 0.0.5
-files:
-  - url: T3-Code-0.0.5-x64.zip
-    sha512: x64zip
-    size: 1
-releaseDate: '2026-03-07T10:36:07.540Z'
-`,
-      "latest-mac-x64.yml",
-    );
-
-    assert.throws(() => mergeMacUpdateManifests(arm64, x64), /different versions/);
-  });
-
-  it("preserves quoted scalars as strings", () => {
-    const manifest = parseMacUpdateManifest(
-      `version: '1.0'
-files:
-  - url: T3-Code-1.0-x64.zip
-    sha512: zipsha
-    size: 1
-releaseName: 'true'
-minimumSystemVersion: '13.0'
-stagingPercentage: 50
-releaseDate: '2026-03-07T10:36:07.540Z'
-`,
-      "latest-mac.yml",
-    );
-
-    assert.equal(manifest.version, "1.0");
-    assert.equal(manifest.extras.releaseName, "true");
-    assert.equal(manifest.extras.minimumSystemVersion, "13.0");
-    assert.equal(manifest.extras.stagingPercentage, 50);
-  });
-});
diff --git a/scripts/merge-update-manifests.test.ts b/scripts/merge-update-manifests.test.ts
new file mode 100644
index 00000000000..32431b81d33
--- /dev/null
+++ b/scripts/merge-update-manifests.test.ts
@@ -0,0 +1,308 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { Command, CliError } from "effect/unstable/cli";
+
+import {
+  mergePlatformUpdateManifests,
+  mergeUpdateManifestsCommand,
+  parsePlatformUpdateManifest,
+  serializePlatformUpdateManifest,
+} from "./merge-update-manifests.ts";
+
+const runCli = Command.runWith(mergeUpdateManifestsCommand, { version: "0.0.0" });
+
+describe("merge-update-manifests", () => {
+  it("merges arm64 and x64 macOS update manifests into one multi-arch manifest", () => {
+    const arm64 = parsePlatformUpdateManifest(
+      "mac",
+      `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-arm64.zip
+    sha512: arm64zip
+    size: 125621344
+  - url: T3-Code-0.0.4-arm64.dmg
+    sha512: arm64dmg
+    size: 131754935
+path: T3-Code-0.0.4-arm64.zip
+sha512: arm64zip
+releaseDate: '2026-03-07T10:32:14.587Z'
+`,
+      "latest-mac.yml",
+    );
+
+    const x64 = parsePlatformUpdateManifest(
+      "mac",
+      `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-x64.zip
+    sha512: x64zip
+    size: 132000112
+  - url: T3-Code-0.0.4-x64.dmg
+    sha512: x64dmg
+    size: 138148807
+path: T3-Code-0.0.4-x64.zip
+sha512: x64zip
+releaseDate: '2026-03-07T10:36:07.540Z'
+`,
+      "latest-mac-x64.yml",
+    );
+
+    const merged = mergePlatformUpdateManifests("mac", arm64, x64);
+
+    assert.equal(merged.version, "0.0.4");
+    assert.equal(merged.releaseDate, "2026-03-07T10:36:07.540Z");
+    assert.deepStrictEqual(
+      merged.files.map((file) => file.url),
+      [
+        "T3-Code-0.0.4-arm64.zip",
+        "T3-Code-0.0.4-arm64.dmg",
+        "T3-Code-0.0.4-x64.zip",
+        "T3-Code-0.0.4-x64.dmg",
+      ],
+    );
+
+    const serialized = serializePlatformUpdateManifest("mac", merged);
+    assert.ok(!serialized.includes("path:"));
+    assert.equal((serialized.match(/- url:/g) ?? []).length, 4);
+  });
+
+  it("merges arm64 and x64 Windows update manifests into one multi-arch manifest", () => {
+    const arm64 = parsePlatformUpdateManifest(
+      "win",
+      `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-arm64.exe
+    sha512: arm64exe
+    size: 125621344
+  - url: T3-Code-0.0.4-arm64.exe.blockmap
+    sha512: arm64blockmap
+    size: 131754
+path: T3-Code-0.0.4-arm64.exe
+sha512: arm64exe
+releaseDate: '2026-03-07T10:32:14.587Z'
+`,
+      "latest-win-arm64.yml",
+    );
+
+    const x64 = parsePlatformUpdateManifest(
+      "win",
+      `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-x64.exe
+    sha512: x64exe
+    size: 132000112
+  - url: T3-Code-0.0.4-x64.exe.blockmap
+    sha512: x64blockmap
+    size: 138148
+path: T3-Code-0.0.4-x64.exe
+sha512: x64exe
+releaseDate: '2026-03-07T10:36:07.540Z'
+`,
+      "latest-win-x64.yml",
+    );
+
+    const merged = mergePlatformUpdateManifests("win", arm64, x64);
+
+    assert.equal(merged.version, "0.0.4");
+    assert.equal(merged.releaseDate, "2026-03-07T10:36:07.540Z");
+    assert.deepStrictEqual(
+      merged.files.map((file) => file.url),
+      [
+        "T3-Code-0.0.4-arm64.exe",
+        "T3-Code-0.0.4-arm64.exe.blockmap",
+        "T3-Code-0.0.4-x64.exe",
+        "T3-Code-0.0.4-x64.exe.blockmap",
+      ],
+    );
+
+    const serialized = serializePlatformUpdateManifest("win", merged);
+    assert.ok(!serialized.includes("path:"));
+    assert.equal((serialized.match(/- url:/g) ?? []).length, 4);
+  });
+
+  it("rejects mismatched manifest versions", () => {
+    const primary = parsePlatformUpdateManifest(
+      "win",
+      `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-arm64.exe
+    sha512: arm64exe
+    size: 1
+releaseDate: '2026-03-07T10:32:14.587Z'
+`,
+      "latest-win-arm64.yml",
+    );
+
+    const secondary = parsePlatformUpdateManifest(
+      "win",
+      `version: 0.0.5
+files:
+  - url: T3-Code-0.0.5-x64.exe
+    sha512: x64exe
+    size: 1
+releaseDate: '2026-03-07T10:36:07.540Z'
+`,
+      "latest-win-x64.yml",
+    );
+
+    assert.throws(
+      () => mergePlatformUpdateManifests("win", primary, secondary),
+      /different versions/,
+    );
+  });
+
+  it("preserves quoted scalars as strings", () => {
+    const manifest = parsePlatformUpdateManifest(
+      "mac",
+      `version: '1.0'
+files:
+  - url: T3-Code-1.0-x64.zip
+    sha512: zipsha
+    size: 1
+releaseName: 'true'
+minimumSystemVersion: '13.0'
+stagingPercentage: 50
+releaseDate: '2026-03-07T10:36:07.540Z'
+`,
+      "latest-mac.yml",
+    );
+
+    assert.equal(manifest.version, "1.0");
+    assert.equal(manifest.extras.releaseName, "true");
+    assert.equal(manifest.extras.minimumSystemVersion, "13.0");
+    assert.equal(manifest.extras.stagingPercentage, 50);
+  });
+
+  it("round-trips numeric-looking versions as strings", () => {
+    const original = parsePlatformUpdateManifest(
+      "win",
+      `version: '1.0'
+files:
+  - url: T3-Code-1.0-x64.exe
+    sha512: exesha
+    size: 1
+releaseDate: '2026-03-07T10:36:07.540Z'
+`,
+      "latest-win-x64.yml",
+    );
+
+    const serialized = serializePlatformUpdateManifest("win", original);
+    assert.ok(serialized.includes("version: '1.0'"));
+
+    const reparsed = parsePlatformUpdateManifest("win", serialized, "latest-win-x64.yml");
+    assert.equal(reparsed.version, "1.0");
+  });
+});
+
+it.layer(NodeServices.layer)("merge-update-manifests cli", (it) => {
+  const arm64MacManifest = `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-arm64.zip
+    sha512: arm64zip
+    size: 125621344
+  - url: T3-Code-0.0.4-arm64.dmg
+    sha512: arm64dmg
+    size: 131754935
+path: T3-Code-0.0.4-arm64.zip
+sha512: arm64zip
+releaseDate: '2026-03-07T10:32:14.587Z'
+`;
+
+  const x64MacManifest = `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-x64.zip
+    sha512: x64zip
+    size: 132000112
+  - url: T3-Code-0.0.4-x64.dmg
+    sha512: x64dmg
+    size: 138148807
+path: T3-Code-0.0.4-x64.zip
+sha512: x64zip
+releaseDate: '2026-03-07T10:36:07.540Z'
+`;
+
+  it.effect("writes the merged manifest back to the primary path by default", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "merge-update-manifests-cli-",
+      });
+      const primaryPath = path.join(baseDir, "latest-mac.yml");
+      const secondaryPath = path.join(baseDir, "latest-mac-x64.yml");
+
+      yield* fs.writeFileString(primaryPath, arm64MacManifest);
+      yield* fs.writeFileString(secondaryPath, x64MacManifest);
+
+      yield* runCli(["--platform", "mac", primaryPath, secondaryPath]);
+
+      const merged = yield* fs.readFileString(primaryPath);
+      assert.ok(merged.includes("T3-Code-0.0.4-arm64.zip"));
+      assert.ok(merged.includes("T3-Code-0.0.4-x64.zip"));
+      assert.ok(!merged.includes("path:"));
+    }),
+  );
+
+  it.effect("writes the merged manifest to an explicit output path", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "merge-update-manifests-cli-output-",
+      });
+      const primaryPath = path.join(baseDir, "latest-win-arm64.yml");
+      const secondaryPath = path.join(baseDir, "latest-win-x64.yml");
+      const outputPath = path.join(baseDir, "latest-win.yml");
+
+      yield* fs.writeFileString(
+        primaryPath,
+        `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-arm64.exe
+    sha512: arm64exe
+    size: 125621344
+releaseDate: '2026-03-07T10:32:14.587Z'
+`,
+      );
+      yield* fs.writeFileString(
+        secondaryPath,
+        `version: 0.0.4
+files:
+  - url: T3-Code-0.0.4-x64.exe
+    sha512: x64exe
+    size: 132000112
+releaseDate: '2026-03-07T10:36:07.540Z'
+`,
+      );
+
+      yield* runCli(["--platform", "win", primaryPath, secondaryPath, outputPath]);
+
+      const merged = yield* fs.readFileString(outputPath);
+      assert.ok(merged.includes("T3-Code-0.0.4-arm64.exe"));
+      assert.ok(merged.includes("T3-Code-0.0.4-x64.exe"));
+    }),
+  );
+
+  it.effect("rejects invalid platform values during cli parsing", () =>
+    Effect.gen(function* () {
+      const error = yield* runCli(["--platform", "linux", "a.yml", "b.yml"]).pipe(Effect.flip);
+
+      if (!CliError.isCliError(error)) {
+        assert.fail(`Expected CliError, got ${String(error)}`);
+      }
+
+      const platformError =
+        error._tag === "ShowHelp" ? (error.errors[0] as CliError.CliError | undefined) : error;
+
+      if (!platformError || platformError._tag !== "InvalidValue") {
+        assert.fail(`Expected InvalidValue, got ${String(platformError?._tag)}`);
+      }
+
+      assert.equal(platformError.option, "platform");
+      assert.equal(platformError.value, "linux");
+    }),
+  );
+});
diff --git a/scripts/merge-update-manifests.ts b/scripts/merge-update-manifests.ts
new file mode 100644
index 00000000000..f7ba30f8a30
--- /dev/null
+++ b/scripts/merge-update-manifests.ts
@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import {
+  mergeUpdateManifests,
+  parseUpdateManifest,
+  serializeUpdateManifest,
+  type UpdateManifest,
+} from "./lib/update-manifest.ts";
+
+const UpdateManifestPlatform = Schema.Literals(["mac", "win"]);
+export type UpdateManifestPlatform = typeof UpdateManifestPlatform.Type;
+
+function getPlatformLabel(platform: UpdateManifestPlatform): string {
+  return platform === "mac" ? "macOS" : "Windows";
+}
+
+export function parsePlatformUpdateManifest(
+  platform: UpdateManifestPlatform,
+  raw: string,
+  sourcePath: string,
+): UpdateManifest {
+  return parseUpdateManifest(raw, sourcePath, getPlatformLabel(platform));
+}
+
+export function mergePlatformUpdateManifests(
+  platform: UpdateManifestPlatform,
+  primary: UpdateManifest,
+  secondary: UpdateManifest,
+): UpdateManifest {
+  return mergeUpdateManifests(primary, secondary, getPlatformLabel(platform));
+}
+
+export function serializePlatformUpdateManifest(
+  platform: UpdateManifestPlatform,
+  manifest: UpdateManifest,
+): string {
+  return serializeUpdateManifest(manifest, {
+    platformLabel: getPlatformLabel(platform),
+  });
+}
+
+export const mergeUpdateManifestFiles = Effect.fn("mergeUpdateManifestFiles")(function* (
+  platform: UpdateManifestPlatform,
+  primaryPathArg: string,
+  secondaryPathArg: string,
+  outputPathArg: string | undefined,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  const primaryPath = path.resolve(primaryPathArg);
+  const secondaryPath = path.resolve(secondaryPathArg);
+  const outputPath = path.resolve(outputPathArg ?? primaryPathArg);
+
+  const primaryManifest = parsePlatformUpdateManifest(
+    platform,
+    yield* fs.readFileString(primaryPath),
+    primaryPath,
+  );
+  const secondaryManifest = parsePlatformUpdateManifest(
+    platform,
+    yield* fs.readFileString(secondaryPath),
+    secondaryPath,
+  );
+  const merged = mergePlatformUpdateManifests(platform, primaryManifest, secondaryManifest);
+
+  yield* fs.writeFileString(outputPath, serializePlatformUpdateManifest(platform, merged));
+});
+
+export const mergeUpdateManifestsCommand = Command.make(
+  "merge-update-manifests",
+  {
+    platform: Flag.choice("platform", UpdateManifestPlatform.literals).pipe(
+      Flag.withDescription("Update manifest platform."),
+    ),
+    primaryPath: Argument.string("primary-path").pipe(
+      Argument.withDescription("Primary update manifest path. Defaults to the output path."),
+    ),
+    secondaryPath: Argument.string("secondary-path").pipe(
+      Argument.withDescription(
+        "Secondary update manifest path to merge into the primary manifest.",
+      ),
+    ),
+    outputPath: Argument.string("output-path").pipe(
+      Argument.withDescription("Optional output path for the merged manifest."),
+      Argument.optional,
+    ),
+  },
+  ({ platform, primaryPath, secondaryPath, outputPath }) =>
+    mergeUpdateManifestFiles(
+      platform,
+      primaryPath,
+      secondaryPath,
+      Option.getOrUndefined(outputPath),
+    ),
+).pipe(Command.withDescription("Merge two Electron updater manifests into a multi-arch manifest."));
+
+if (import.meta.main) {
+  Command.run(mergeUpdateManifestsCommand, { version: "0.0.0" }).pipe(
+    Effect.provide(NodeServices.layer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/scripts/mock-update-server.test.ts b/scripts/mock-update-server.test.ts
new file mode 100644
index 00000000000..747a21c68b4
--- /dev/null
+++ b/scripts/mock-update-server.test.ts
@@ -0,0 +1,107 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { HttpClient, HttpRouter } from "effect/unstable/http";
+
+import { makeMockUpdateRouteLayer } from "./mock-update-server.ts";
+
+const withMockUpdateServer = <A, E, R>(rootRealPath: string, effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(
+    Effect.provide(
+      HttpRouter.serve(makeMockUpdateRouteLayer(rootRealPath), {
+        disableListenLog: true,
+        disableLogger: true,
+      }).pipe(Layer.provideMerge(NodeHttpServer.layerTest)),
+    ),
+  );
+
+it.layer(NodeServices.layer)("mock-update-server", (it) => {
+  it.effect("serves files from the configured root", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "mock-update-server-root-",
+      });
+      const rootRealPath = yield* fileSystem.realPath(root);
+      const filePath = path.join(root, "latest.yml");
+
+      yield* fileSystem.writeFileString(filePath, "version: 0.0.1\n");
+
+      yield* withMockUpdateServer(
+        rootRealPath,
+        Effect.gen(function* () {
+          const client = yield* HttpClient.HttpClient;
+          const response = yield* client.get("/latest.yml");
+
+          assert.equal(response.status, 200);
+          assert.equal(response.headers["content-type"], "text/yaml");
+          assert.equal(yield* response.text, "version: 0.0.1\n");
+        }),
+      );
+    }),
+  );
+
+  it.effect("rejects encoded path traversal outside the configured root", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "mock-update-server-root-",
+      });
+      const outside = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "mock-update-server-outside-",
+      });
+      const rootRealPath = yield* fileSystem.realPath(root);
+
+      yield* fileSystem.writeFileString(path.join(outside, "secret.txt"), "nope\n");
+
+      yield* withMockUpdateServer(
+        rootRealPath,
+        Effect.gen(function* () {
+          const client = yield* HttpClient.HttpClient;
+          const response = yield* client.get("/%2e%2e/secret.txt");
+
+          assert.equal(response.status, 404);
+          assert.equal(yield* response.text, "Not Found");
+        }),
+      );
+    }),
+  );
+
+  it.effect("rejects symlinked files that escape the configured root", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "mock-update-server-root-",
+      });
+      const outside = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "mock-update-server-outside-",
+      });
+      const rootRealPath = yield* fileSystem.realPath(root);
+      const outsideFile = path.join(outside, "outside.yml");
+      const linksDir = path.join(root, "links");
+      const symlinkPath = path.join(linksDir, "outside.yml");
+
+      yield* fileSystem.writeFileString(outsideFile, "version: outside\n");
+      yield* fileSystem.makeDirectory(linksDir, { recursive: true });
+      yield* fileSystem.symlink(outsideFile, symlinkPath);
+
+      yield* withMockUpdateServer(
+        rootRealPath,
+        Effect.gen(function* () {
+          const client = yield* HttpClient.HttpClient;
+          const response = yield* client.get("/links/outside.yml");
+
+          assert.equal(response.status, 404);
+          assert.equal(yield* response.text, "Not Found");
+        }),
+      );
+    }),
+  );
+});
diff --git a/scripts/mock-update-server.ts b/scripts/mock-update-server.ts
index 57dab49ffa3..27715b5c5ad 100644
--- a/scripts/mock-update-server.ts
+++ b/scripts/mock-update-server.ts
@@ -1,44 +1,160 @@
-import { resolve, relative } from "node:path";
-import { realpathSync } from "node:fs";
+// @effect-diagnostics-next-line nodeBuiltinImport:off - NodeHttpServer.layer takes `NodeHttp.createServer` as arg
+import * as NodeHttp from "node:http";
 
-const port = Number(process.env.T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT ?? 3000);
-const root =
-  process.env.T3CODE_DESKTOP_MOCK_UPDATE_SERVER_ROOT ??
-  resolve(import.meta.dirname, "..", "release-mock");
+import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
-const mockServerLog = (level: "info" | "warn" | "error" = "info", message: string) => {
-  console[level](`[mock-update-server] ${message}`);
-};
-
-function isWithinRoot(filePath: string): boolean {
-  try {
-    return !relative(realpathSync(root), realpathSync(filePath)).startsWith(".");
-  } catch (error) {
-    mockServerLog("error", `Error checking if file is within root: ${error}`);
-    return false;
-  }
+interface MockUpdateServerConfig {
+  readonly port: number;
+  readonly rootRealPath: string;
 }
 
-Bun.serve({
-  port,
-  hostname: "localhost",
-  fetch: async (request) => {
-    const url = new URL(request.url);
-    const path = url.pathname;
-    mockServerLog("info", `Request received for path: ${path}`);
-    const filePath = resolve(root, `.${path}`);
-    if (!isWithinRoot(filePath)) {
-      mockServerLog("warn", `Attempted to access file outside of root: ${filePath}`);
-      return new Response("Not Found", { status: 404 });
+const resolveMockUpdateServerConfig = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const config = yield* Config.all({
+    port: Config.port("T3CODE_DESKTOP_MOCK_UPDATE_SERVER_PORT").pipe(Config.withDefault(3000)),
+    root: Config.string("T3CODE_DESKTOP_MOCK_UPDATE_SERVER_ROOT").pipe(
+      Config.withDefault("../release-mock"),
+    ),
+  }).asEffect();
+
+  const resolvedRoot = path.resolve(import.meta.dirname, config.root);
+
+  return {
+    port: config.port,
+    rootRealPath: yield* fileSystem.realPath(resolvedRoot),
+  } satisfies MockUpdateServerConfig;
+});
+
+const isOutsideRoot = (rootRealPath: string, filePath: string) =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const relativePath = path.relative(rootRealPath, filePath);
+    return (
+      relativePath === ".." || relativePath.startsWith("../") || relativePath.startsWith("..\\")
+    );
+  });
+
+const isWithinRoot = (rootRealPath: string, filePath: string) =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const resolvedFilePath = yield* fileSystem.realPath(filePath).pipe(
+      Effect.match({
+        onFailure: () => undefined,
+        onSuccess: (resolvedPath) => resolvedPath,
+      }),
+    );
+
+    return (
+      resolvedFilePath !== undefined && !(yield* isOutsideRoot(rootRealPath, resolvedFilePath))
+    );
+  });
+
+const resolveRequestedFilePath = (rootRealPath: string, requestUrl: string | undefined) =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const rawPath = (requestUrl ?? "/").split("?", 1)[0] ?? "/";
+    const decodedPath = yield* Effect.try({
+      try: () => decodeURIComponent(rawPath),
+      catch: () => null,
+    }).pipe(
+      Effect.match({
+        onFailure: () => undefined,
+        onSuccess: (value) => value,
+      }),
+    );
+
+    if (!decodedPath) {
+      return undefined;
     }
-    const file = Bun.file(filePath);
-    if (!(await file.exists())) {
-      mockServerLog("warn", `Attempted to access non-existent file: ${filePath}`);
-      return new Response("Not Found", { status: 404 });
+
+    if (decodedPath.includes("\0")) {
+      return undefined;
     }
-    mockServerLog("info", `Serving file: ${filePath}`);
-    return new Response(file.stream());
-  },
-});
 
-mockServerLog("info", `running on http://localhost:${port}`);
+    const filePath = path.resolve(
+      rootRealPath,
+      `.${decodedPath.startsWith("/") ? decodedPath : `/${decodedPath}`}`,
+    );
+
+    return (yield* isOutsideRoot(rootRealPath, filePath)) ? undefined : filePath;
+  });
+
+const isServableFile = (rootRealPath: string, filePath: string) =>
+  Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const stat = yield* fileSystem.stat(filePath).pipe(
+      Effect.match({
+        onFailure: () => undefined,
+        onSuccess: (info) => info,
+      }),
+    );
+
+    if (stat?.type !== "File") {
+      return false;
+    }
+
+    return yield* isWithinRoot(rootRealPath, filePath);
+  });
+
+export const makeMockUpdateRouteLayer = (rootRealPath: string) => {
+  return HttpRouter.add(
+    "*",
+    "*",
+    Effect.gen(function* () {
+      const request = yield* HttpServerRequest.HttpServerRequest;
+      const requestPath = (request.url ?? "/").split("?", 1)[0] ?? "/";
+      yield* Effect.logInfo(`Request received for path: ${requestPath}`);
+
+      const filePath = yield* resolveRequestedFilePath(rootRealPath, request.url);
+      if (!filePath) {
+        yield* Effect.logWarning(`Attempted to access file outside of root: ${request.url ?? "/"}`);
+        return HttpServerResponse.text("Not Found", { status: 404 });
+      }
+
+      if (!(yield* isServableFile(rootRealPath, filePath))) {
+        yield* Effect.logWarning(`Attempted to access invalid file: ${filePath}`);
+        return HttpServerResponse.text("Not Found", { status: 404 });
+      }
+
+      yield* Effect.logInfo(`Serving file: ${filePath}`);
+      return yield* HttpServerResponse.file(filePath, { status: 200 });
+    }).pipe(
+      Effect.catchCause((cause) =>
+        Effect.gen(function* () {
+          yield* Effect.logError(`Unhandled mock update request failure: ${cause}`);
+          return HttpServerResponse.text("Internal Server Error", { status: 500 });
+        }),
+      ),
+    ),
+  );
+};
+
+const makeMockUpdateServerLayer = (config: MockUpdateServerConfig) =>
+  HttpRouter.serve(makeMockUpdateRouteLayer(config.rootRealPath)).pipe(
+    Layer.provideMerge(
+      NodeHttpServer.layer(NodeHttp.createServer, {
+        host: "localhost",
+        port: config.port,
+      }),
+    ),
+    Layer.provideMerge(NodeServices.layer),
+  );
+
+if (import.meta.main) {
+  resolveMockUpdateServerConfig.pipe(
+    Effect.map(makeMockUpdateServerLayer),
+    Layer.unwrap,
+    Layer.launch,
+    Effect.provide(NodeServices.layer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/scripts/notify-discord-release.test.ts b/scripts/notify-discord-release.test.ts
new file mode 100644
index 00000000000..23f73fa0d76
--- /dev/null
+++ b/scripts/notify-discord-release.test.ts
@@ -0,0 +1,88 @@
+import { assert, it } from "@effect/vitest";
+
+import { buildDiscordReleaseAnnouncement } from "./notify-discord-release.ts";
+
+it("builds a prerelease Discord announcement for nightly subscribers", () => {
+  assert.deepStrictEqual(
+    buildDiscordReleaseAnnouncement({
+      target: "prerelease",
+      roleId: "111111111111111111",
+      releaseName: "T3 Code Nightly 1.2.4-nightly.20260501.17 (abcdef123456)",
+      version: "1.2.4-nightly.20260501.17",
+      tag: "v1.2.4-nightly.20260501.17",
+      releaseUrl: new URL(
+        "https://github.com/t3dotgg/t3-code/releases/tag/v1.2.4-nightly.20260501.17",
+      ),
+      timestamp: "2026-05-01T01:41:00.000Z",
+    }),
+    {
+      content:
+        "<@&111111111111111111> Prerelease published: T3 Code Nightly 1.2.4-nightly.20260501.17 (abcdef123456)",
+      allowed_mentions: {
+        roles: ["111111111111111111"],
+      },
+      embeds: [
+        {
+          title: "T3 Code Nightly 1.2.4-nightly.20260501.17 (abcdef123456)",
+          url: "https://github.com/t3dotgg/t3-code/releases/tag/v1.2.4-nightly.20260501.17",
+          description: "A new T3 Code prerelease is available for nightly testers.",
+          color: 0x5865f2,
+          fields: [
+            {
+              name: "Version",
+              value: "1.2.4-nightly.20260501.17",
+              inline: true,
+            },
+            {
+              name: "Tag",
+              value: "v1.2.4-nightly.20260501.17",
+              inline: true,
+            },
+          ],
+          timestamp: "2026-05-01T01:41:00.000Z",
+        },
+      ],
+    },
+  );
+});
+
+it("builds a latest Discord announcement for stable subscribers", () => {
+  assert.deepStrictEqual(
+    buildDiscordReleaseAnnouncement({
+      target: "latest",
+      roleId: "222222222222222222",
+      releaseName: "T3 Code v1.2.3",
+      version: "1.2.3",
+      tag: "v1.2.3",
+      releaseUrl: new URL("https://github.com/t3dotgg/t3-code/releases/tag/v1.2.3"),
+      timestamp: "2026-05-01T01:41:00.000Z",
+    }),
+    {
+      content: "<@&222222222222222222> Latest published: T3 Code v1.2.3",
+      allowed_mentions: {
+        roles: ["222222222222222222"],
+      },
+      embeds: [
+        {
+          title: "T3 Code v1.2.3",
+          url: "https://github.com/t3dotgg/t3-code/releases/tag/v1.2.3",
+          description: "A new T3 Code latest release is available.",
+          color: 0x2ecc71,
+          fields: [
+            {
+              name: "Version",
+              value: "1.2.3",
+              inline: true,
+            },
+            {
+              name: "Tag",
+              value: "v1.2.3",
+              inline: true,
+            },
+          ],
+          timestamp: "2026-05-01T01:41:00.000Z",
+        },
+      ],
+    },
+  );
+});
diff --git a/scripts/notify-discord-release.ts b/scripts/notify-discord-release.ts
new file mode 100644
index 00000000000..1e3106b05ed
--- /dev/null
+++ b/scripts/notify-discord-release.ts
@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Config from "effect/Config";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Schema from "effect/Schema";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/unstable/http";
+
+export type DiscordReleaseTarget = "prerelease" | "latest";
+
+interface DiscordReleaseAnnouncementOptions {
+  readonly target: DiscordReleaseTarget;
+  readonly roleId: string;
+  readonly releaseName: string;
+  readonly version: string;
+  readonly tag: string;
+  readonly releaseUrl: URL;
+  readonly timestamp: string;
+}
+
+interface DiscordWebhookPayload {
+  readonly content: string;
+  readonly allowed_mentions: {
+    readonly roles: ReadonlyArray<string>;
+  };
+  readonly embeds: ReadonlyArray<{
+    readonly title: string;
+    readonly url: string;
+    readonly description: string;
+    readonly color: number;
+    readonly fields: ReadonlyArray<{
+      readonly name: string;
+      readonly value: string;
+      readonly inline: boolean;
+    }>;
+    readonly timestamp: string;
+  }>;
+}
+
+const DISCORD_RELEASE_TARGETS = ["prerelease", "latest"] as const;
+const DiscordRoleIdSchema = Schema.String.check(Schema.isPattern(/^\d+$/));
+const DiscordWebhookUrl = Config.url("DISCORD_WEBHOOK_URL");
+
+class DiscordReleaseAnnouncementError extends Data.TaggedError("DiscordReleaseAnnouncementError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+const targetLabels = {
+  prerelease: "Prerelease",
+  latest: "Latest",
+} as const satisfies Record<DiscordReleaseTarget, string>;
+
+const targetColors = {
+  prerelease: 0x5865f2,
+  latest: 0x2ecc71,
+} as const satisfies Record<DiscordReleaseTarget, number>;
+
+function describeWebhookUrl(webhookUrl: URL) {
+  return {
+    configured: true,
+    origin: webhookUrl.origin,
+    pathnameSegmentCount: webhookUrl.pathname.split("/").filter(Boolean).length,
+  } as const;
+}
+
+function summarizePayload(payload: DiscordWebhookPayload) {
+  return {
+    contentLength: payload.content.length,
+    embedCount: payload.embeds.length,
+    allowedRoleMentionCount: payload.allowed_mentions.roles.length,
+    hasRoleMentionSyntax: payload.content.includes("<@&"),
+  } as const;
+}
+
+export const buildDiscordReleaseAnnouncement = (
+  options: DiscordReleaseAnnouncementOptions,
+): DiscordWebhookPayload => ({
+  content: `<@&${options.roleId}> ${targetLabels[options.target]} published: ${options.releaseName}`,
+  allowed_mentions: {
+    roles: [options.roleId],
+  },
+  embeds: [
+    {
+      title: options.releaseName,
+      url: options.releaseUrl.href,
+      description:
+        options.target === "prerelease"
+          ? "A new T3 Code prerelease is available for nightly testers."
+          : "A new T3 Code latest release is available.",
+      color: targetColors[options.target],
+      fields: [
+        {
+          name: "Version",
+          value: options.version,
+          inline: true,
+        },
+        {
+          name: "Tag",
+          value: options.tag,
+          inline: true,
+        },
+      ],
+      timestamp: options.timestamp,
+    },
+  ],
+});
+
+const postDiscordWebhook = Effect.fn("postDiscordWebhook")(function* (
+  webhookUrl: URL,
+  payload: DiscordWebhookPayload,
+) {
+  const httpClient = (yield* HttpClient.HttpClient).pipe(
+    HttpClient.retryTransient({
+      retryOn: "errors-and-responses",
+      times: 3,
+    }),
+  );
+
+  yield* Effect.logInfo("discord webhook request dispatching").pipe(
+    Effect.annotateLogs({
+      ...describeWebhookUrl(webhookUrl),
+      ...summarizePayload(payload),
+    }),
+  );
+
+  const response = yield* HttpClientRequest.post(webhookUrl).pipe(
+    HttpClientRequest.bodyJson(payload),
+    Effect.flatMap(httpClient.execute),
+    Effect.mapError(
+      (cause) =>
+        new DiscordReleaseAnnouncementError({
+          message: "Failed to post Discord release announcement.",
+          cause,
+        }),
+    ),
+  );
+
+  yield* Effect.logInfo("discord webhook response received").pipe(
+    Effect.annotateLogs({
+      status: response.status,
+      ok: response.status >= 200 && response.status < 300,
+    }),
+  );
+
+  yield* HttpClientResponse.filterStatusOk(response).pipe(
+    Effect.mapError(
+      (cause) =>
+        new DiscordReleaseAnnouncementError({
+          message: `Discord webhook returned status ${response.status}.`,
+          cause,
+        }),
+    ),
+  );
+});
+
+export const notifyDiscordReleaseCommand = Command.make(
+  "notify-discord-release",
+  {
+    target: Argument.choice("target", DISCORD_RELEASE_TARGETS).pipe(
+      Argument.withDescription("Discord announcement target: prerelease or latest."),
+    ),
+    roleId: Flag.string("role-id").pipe(
+      Flag.withSchema(DiscordRoleIdSchema),
+      Flag.withDescription("Discord role ID to mention in the release announcement."),
+    ),
+    releaseName: Flag.string("release-name").pipe(
+      Flag.withSchema(Schema.NonEmptyString),
+      Flag.withDescription("Human-readable release name."),
+    ),
+    releaseVersion: Flag.string("release-version").pipe(
+      Flag.withSchema(Schema.NonEmptyString),
+      Flag.withDescription("Release version."),
+    ),
+    tag: Flag.string("tag").pipe(
+      Flag.withSchema(Schema.NonEmptyString),
+      Flag.withDescription("Git tag for the release."),
+    ),
+    releaseUrl: Flag.string("release-url").pipe(
+      Flag.withSchema(Schema.URLFromString),
+      Flag.withDescription("Public GitHub release URL."),
+    ),
+  },
+  ({ target, roleId, releaseName, releaseVersion, tag, releaseUrl }) =>
+    Effect.gen(function* () {
+      yield* Effect.logInfo("discord release announcement starting").pipe(
+        Effect.annotateLogs({
+          target,
+          roleIdProvided: roleId.length > 0,
+          roleIdLength: roleId.length,
+          releaseName,
+          version: releaseVersion,
+          tag,
+          releaseUrl,
+        }),
+      );
+
+      const webhookUrl = yield* DiscordWebhookUrl;
+      const timestamp = DateTime.formatIso(yield* DateTime.now);
+      const payload = buildDiscordReleaseAnnouncement({
+        target,
+        roleId,
+        releaseName,
+        version: releaseVersion,
+        tag,
+        releaseUrl,
+        timestamp,
+      });
+
+      yield* Effect.logInfo("discord release announcement payload built").pipe(
+        Effect.annotateLogs(summarizePayload(payload)),
+      );
+      yield* postDiscordWebhook(webhookUrl, payload);
+      yield* Effect.logInfo("discord release announcement completed");
+    }),
+).pipe(Command.withDescription("Post a T3 Code release announcement to Discord."));
+
+if (import.meta.main) {
+  Command.run(notifyDiscordReleaseCommand, { version: "0.0.0" }).pipe(
+    Effect.provide(
+      Layer.mergeAll(
+        Logger.layer([Logger.consolePretty()]),
+        NodeServices.layer,
+        FetchHttpClient.layer,
+      ),
+    ),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/scripts/package.json b/scripts/package.json
index 157763b3986..dd801521387 100644
--- a/scripts/package.json
+++ b/scripts/package.json
@@ -3,7 +3,6 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "prepare": "effect-language-service patch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
diff --git a/scripts/release-smoke.ts b/scripts/release-smoke.ts
index 98f7da57891..5f8f737fd53 100644
--- a/scripts/release-smoke.ts
+++ b/scripts/release-smoke.ts
@@ -1,8 +1,19 @@
+// @effect-diagnostics nodeBuiltinImport:off
 import { execFileSync } from "node:child_process";
-import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
 
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -13,9 +24,14 @@ const workspaceFiles = [
   "apps/desktop/package.json",
   "apps/web/package.json",
   "apps/marketing/package.json",
+  "oxlint-plugin-t3code/package.json",
   "packages/client-runtime/package.json",
   "packages/contracts/package.json",
   "packages/shared/package.json",
+  "packages/ssh/package.json",
+  "packages/tailscale/package.json",
+  "packages/effect-acp/package.json",
+  "packages/effect-codex-app-server/package.json",
   "scripts/package.json",
 ] as const;
 
@@ -26,6 +42,17 @@ function copyWorkspaceManifestFixture(targetRoot: string): void {
     mkdirSync(dirname(destinationPath), { recursive: true });
     cpSync(sourcePath, destinationPath);
   }
+
+  const packageJson = JSON.parse(readFileSync(resolve(repoRoot, "package.json"), "utf8")) as {
+    readonly patchedDependencies?: Record<string, string>;
+  };
+
+  for (const relativePath of Object.values(packageJson.patchedDependencies ?? {})) {
+    const sourcePath = resolve(repoRoot, relativePath);
+    const destinationPath = resolve(targetRoot, relativePath);
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    cpSync(sourcePath, destinationPath);
+  }
 }
 
 function writeMacManifestFixtures(targetRoot: string): { arm64Path: string; x64Path: string } {
@@ -70,12 +97,91 @@ releaseDate: '2026-03-08T10:36:07.540Z'
   return { arm64Path, x64Path };
 }
 
+function writeWindowsManifestFixtures(
+  targetRoot: string,
+  channel: string,
+): { arm64Path: string; x64Path: string } {
+  const assetDirectory = resolve(targetRoot, "release-assets");
+  mkdirSync(assetDirectory, { recursive: true });
+
+  const arm64Path = resolve(assetDirectory, `${channel}-win-arm64.yml`);
+  const x64Path = resolve(assetDirectory, `${channel}-win-x64.yml`);
+
+  writeFileSync(
+    arm64Path,
+    `version: 9.9.9-smoke.0
+files:
+  - url: T3-Code-9.9.9-smoke.0-arm64.exe
+    sha512: arm64exe
+    size: 126621344
+  - url: T3-Code-9.9.9-smoke.0-arm64.exe.blockmap
+    sha512: arm64blockmap
+    size: 152344
+path: T3-Code-9.9.9-smoke.0-arm64.exe
+sha512: arm64exe
+releaseDate: '2026-03-08T10:32:14.587Z'
+`,
+  );
+
+  writeFileSync(
+    x64Path,
+    `version: 9.9.9-smoke.0
+files:
+  - url: T3-Code-9.9.9-smoke.0-x64.exe
+    sha512: x64exe
+    size: 132000112
+  - url: T3-Code-9.9.9-smoke.0-x64.exe.blockmap
+    sha512: x64blockmap
+    size: 160112
+path: T3-Code-9.9.9-smoke.0-x64.exe
+sha512: x64exe
+releaseDate: '2026-03-08T10:36:07.540Z'
+`,
+  );
+
+  return { arm64Path, x64Path };
+}
+
+function writeWindowsBuilderDebugFixtures(targetRoot: string): {
+  arm64Path: string;
+  x64Path: string;
+} {
+  const assetDirectory = resolve(targetRoot, "release-assets");
+  mkdirSync(assetDirectory, { recursive: true });
+
+  const arm64Path = resolve(assetDirectory, "builder-debug-win-arm64.yml");
+  const x64Path = resolve(assetDirectory, "builder-debug-win-x64.yml");
+  const debugFixture = `arm64:
+  firstOrDefaultFilePatterns:
+    - '**/*'
+nsis:
+  script: |-
+    !include "example.nsh"
+`;
+
+  writeFileSync(arm64Path, debugFixture);
+  writeFileSync(x64Path, debugFixture);
+
+  return { arm64Path, x64Path };
+}
 function assertContains(haystack: string, needle: string, message: string): void {
   if (!haystack.includes(needle)) {
     throw new Error(message);
   }
 }
 
+function assertExists(path: string, message: string): void {
+  if (!existsSync(path)) {
+    throw new Error(message);
+  }
+}
+
+function assertMissing(path: string, message: string): void {
+  if (existsSync(path)) {
+    throw new Error(message);
+  }
+}
+
 const tempRoot = mkdtempSync(join(tmpdir(), "t3-release-smoke-"));
 
 try {
@@ -95,7 +201,9 @@ try {
     },
   );
 
-  execFileSync("bun", ["install", "--lockfile-only", "--ignore-scripts"], {
+  rmSync(resolve(tempRoot, "bun.lock"), { force: true });
+
+  execFileSync("bun", ["install", "--ignore-scripts"], {
     cwd: tempRoot,
     stdio: "inherit",
   });
@@ -107,10 +215,50 @@ try {
     "Expected bun.lock to contain the smoke version.",
   );
 
+  const nightlyReleaseMetadata = execFileSync(
+    process.execPath,
+    [
+      resolve(repoRoot, "scripts/resolve-nightly-release.ts"),
+      "--date",
+      "20260413",
+      "--run-number",
+      "321",
+      "--sha",
+      "abcdef1234567890",
+      "--root",
+      tempRoot,
+    ],
+    {
+      cwd: repoRoot,
+      encoding: "utf8",
+    },
+  );
+  assertContains(
+    nightlyReleaseMetadata,
+    "version=9.9.10-nightly.20260413.321",
+    "Expected nightly metadata to contain the derived nightly version.",
+  );
+  assertContains(
+    nightlyReleaseMetadata,
+    "tag=v9.9.10-nightly.20260413.321",
+    "Expected nightly metadata to contain the derived nightly tag.",
+  );
+  assertContains(
+    nightlyReleaseMetadata,
+    "name=T3 Code Nightly 9.9.10-nightly.20260413.321 (abcdef123456)",
+    "Expected nightly metadata to include the short commit SHA in the release name.",
+  );
+
   const { arm64Path, x64Path } = writeMacManifestFixtures(tempRoot);
   execFileSync(
     process.execPath,
-    [resolve(repoRoot, "scripts/merge-mac-update-manifests.ts"), arm64Path, x64Path],
+    [
+      resolve(repoRoot, "scripts/merge-update-manifests.ts"),
+      "--platform",
+      "mac",
+      arm64Path,
+      x64Path,
+    ],
     {
       cwd: repoRoot,
       stdio: "inherit",
@@ -129,7 +277,123 @@ try {
     "Merged manifest is missing the x64 asset.",
   );
 
-  console.log("Release smoke checks passed.");
+  const { arm64Path: winArm64Path, x64Path: winX64Path } = writeWindowsManifestFixtures(
+    tempRoot,
+    "latest",
+  );
+  const mergedWindowsManifestPath = resolve(tempRoot, "release-assets/latest.yml");
+  const { arm64Path: nightlyWinArm64Path, x64Path: nightlyWinX64Path } =
+    writeWindowsManifestFixtures(tempRoot, "nightly");
+  const mergedNightlyWindowsManifestPath = resolve(tempRoot, "release-assets/nightly.yml");
+  const { arm64Path: previewWinArm64Path, x64Path: previewWinX64Path } =
+    writeWindowsManifestFixtures(tempRoot, "preview");
+  const mergedPreviewWindowsManifestPath = resolve(tempRoot, "release-assets/preview.yml");
+  const { arm64Path: winDebugArm64Path, x64Path: winDebugX64Path } =
+    writeWindowsBuilderDebugFixtures(tempRoot);
+  execFileSync(
+    "bash",
+    [
+      "-lc",
+      `
+        release_assets_dir=${JSON.stringify(resolve(tempRoot, "release-assets"))}
+        shopt -s nullglob
+        found_windows_manifest=false
+        for x64_manifest in "$release_assets_dir"/*-win-x64.yml; do
+          if [[ "$(basename "$x64_manifest")" == builder-debug-* ]]; then
+            continue
+          fi
+
+          arm64_manifest="\${x64_manifest/-x64.yml/-arm64.yml}"
+          output_manifest="\${x64_manifest/-win-x64.yml/.yml}"
+          if [[ ! -f "$arm64_manifest" ]]; then
+            echo "Missing matching arm64 Windows manifest for $x64_manifest" >&2
+            exit 1
+          fi
+
+          found_windows_manifest=true
+          ${JSON.stringify(process.execPath)} ${JSON.stringify(resolve(repoRoot, "scripts/merge-update-manifests.ts"))} --platform win \
+            "$arm64_manifest" \
+            "$x64_manifest" \
+            "$output_manifest"
+          rm -f "$arm64_manifest" "$x64_manifest"
+        done
+
+        if [[ "$found_windows_manifest" != true ]]; then
+          echo "No Windows updater manifests found to merge." >&2
+          exit 1
+        fi
+      `,
+    ],
+    {
+      cwd: repoRoot,
+      stdio: "inherit",
+    },
+  );
+
+  const mergedWindowsManifest = readFileSync(mergedWindowsManifestPath, "utf8");
+  assertContains(
+    mergedWindowsManifest,
+    "T3-Code-9.9.9-smoke.0-arm64.exe",
+    "Merged Windows manifest is missing the arm64 asset.",
+  );
+  assertContains(
+    mergedWindowsManifest,
+    "T3-Code-9.9.9-smoke.0-x64.exe",
+    "Merged Windows manifest is missing the x64 asset.",
+  );
+  const mergedNightlyWindowsManifest = readFileSync(mergedNightlyWindowsManifestPath, "utf8");
+  assertContains(
+    mergedNightlyWindowsManifest,
+    "T3-Code-9.9.9-smoke.0-arm64.exe",
+    "Merged nightly Windows manifest is missing the arm64 asset.",
+  );
+  assertContains(
+    mergedNightlyWindowsManifest,
+    "T3-Code-9.9.9-smoke.0-x64.exe",
+    "Merged nightly Windows manifest is missing the x64 asset.",
+  );
+  const mergedPreviewWindowsManifest = readFileSync(mergedPreviewWindowsManifestPath, "utf8");
+  assertContains(
+    mergedPreviewWindowsManifest,
+    "T3-Code-9.9.9-smoke.0-arm64.exe",
+    "Merged preview Windows manifest is missing the arm64 asset.",
+  );
+  assertContains(
+    mergedPreviewWindowsManifest,
+    "T3-Code-9.9.9-smoke.0-x64.exe",
+    "Merged preview Windows manifest is missing the x64 asset.",
+  );
+  assertMissing(
+    winArm64Path,
+    "Windows release smoke unexpectedly kept the arm64 updater manifest.",
+  );
+  assertMissing(winX64Path, "Windows release smoke unexpectedly kept the x64 updater manifest.");
+  assertMissing(
+    nightlyWinArm64Path,
+    "Windows release smoke unexpectedly kept the nightly arm64 updater manifest.",
+  );
+  assertMissing(
+    nightlyWinX64Path,
+    "Windows release smoke unexpectedly kept the nightly x64 updater manifest.",
+  );
+  assertMissing(
+    previewWinArm64Path,
+    "Windows release smoke unexpectedly kept the preview arm64 updater manifest.",
+  );
+  assertMissing(
+    previewWinX64Path,
+    "Windows release smoke unexpectedly kept the preview x64 updater manifest.",
+  );
+  assertExists(
+    winDebugArm64Path,
+    "Windows release smoke unexpectedly removed the arm64 builder debug fixture.",
+  );
+  assertExists(
+    winDebugX64Path,
+    "Windows release smoke unexpectedly removed the x64 builder debug fixture.",
+  );
+
+  Effect.runSync(Console.log("Release smoke checks passed."));
 } finally {
   rmSync(tempRoot, { recursive: true, force: true });
 }
diff --git a/scripts/resolve-nightly-release.test.ts b/scripts/resolve-nightly-release.test.ts
new file mode 100644
index 00000000000..82b25737a58
--- /dev/null
+++ b/scripts/resolve-nightly-release.test.ts
@@ -0,0 +1,32 @@
+import { assert, it } from "@effect/vitest";
+
+import {
+  resolveNightlyBaseVersion,
+  resolveNightlyReleaseMetadata,
+  resolveNightlyTargetVersion,
+} from "./resolve-nightly-release.ts";
+
+it("strips prerelease and build metadata when deriving the nightly base version", () => {
+  assert.equal(resolveNightlyBaseVersion("0.0.17"), "0.0.17");
+  assert.equal(resolveNightlyBaseVersion("9.9.9-smoke.0"), "9.9.9");
+  assert.equal(resolveNightlyBaseVersion("1.2.3-beta.4+build.9"), "1.2.3");
+});
+
+it("bumps the patch version before deriving nightly prerelease versions", () => {
+  assert.equal(resolveNightlyTargetVersion("0.0.17"), "0.0.18");
+  assert.equal(resolveNightlyTargetVersion("9.9.9-smoke.0"), "9.9.10");
+  assert.equal(resolveNightlyTargetVersion("1.2.3-beta.4+build.9"), "1.2.4");
+});
+
+it("derives nightly metadata including the short commit sha in the release name", () => {
+  assert.deepStrictEqual(
+    resolveNightlyReleaseMetadata("9.9.10", "20260413", 321, "abcdef1234567890"),
+    {
+      baseVersion: "9.9.10",
+      version: "9.9.10-nightly.20260413.321",
+      tag: "v9.9.10-nightly.20260413.321",
+      name: "T3 Code Nightly 9.9.10-nightly.20260413.321 (abcdef123456)",
+      shortSha: "abcdef123456",
+    },
+  );
+});
diff --git a/scripts/resolve-nightly-release.ts b/scripts/resolve-nightly-release.ts
new file mode 100644
index 00000000000..e3f064305bf
--- /dev/null
+++ b/scripts/resolve-nightly-release.ts
@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Console from "effect/Console";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { Command, Flag } from "effect/unstable/cli";
+
+interface NightlyReleaseMetadata {
+  readonly baseVersion: string;
+  readonly version: string;
+  readonly tag: string;
+  readonly name: string;
+  readonly shortSha: string;
+}
+
+const DateSchema = Schema.String.check(Schema.isPattern(/^\d{8}$/));
+const RunNumberSchema = Schema.FiniteFromString.check(
+  Schema.isInt(),
+  Schema.isGreaterThanOrEqualTo(1),
+);
+const ShaSchema = Schema.String.check(Schema.isPattern(/^[0-9a-f]{7,40}$/i));
+const DesktopPackageJsonSchema = Schema.Struct({
+  version: Schema.NonEmptyString,
+});
+
+const RepoRoot = Effect.service(Path.Path).pipe(
+  Effect.flatMap((path) => path.fromFileUrl(new URL("..", import.meta.url))),
+);
+const decodeDesktopPackageJson = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(DesktopPackageJsonSchema),
+);
+
+export const resolveNightlyBaseVersion = (version: string) => version.replace(/[-+].*$/, "");
+
+export const resolveNightlyTargetVersion = (version: string) => {
+  const stableCore = resolveNightlyBaseVersion(version);
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(stableCore);
+  if (!match) {
+    throw new Error(`Invalid desktop package version '${version}'.`);
+  }
+
+  const [, major, minor, patch] = match;
+  return `${major}.${minor}.${Number(patch) + 1}`;
+};
+
+export const resolveNightlyReleaseMetadata = (
+  baseVersion: string,
+  date: string,
+  runNumber: number,
+  sha: string,
+) => {
+  const shortSha = sha.slice(0, 12);
+  const version = `${baseVersion}-nightly.${date}.${runNumber}`;
+  return {
+    baseVersion,
+    version,
+    tag: `v${version}`,
+    name: `T3 Code Nightly ${version} (${shortSha})`,
+    shortSha,
+  };
+};
+
+const readDesktopBaseVersion = Effect.fn("readDesktopBaseVersion")(function* (
+  rootDir: string | undefined,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const workspaceRoot = rootDir ? path.resolve(rootDir) : yield* RepoRoot;
+  const packageJsonPath = path.join(workspaceRoot, "apps/desktop/package.json");
+  const packageJson = yield* fs
+    .readFileString(packageJsonPath)
+    .pipe(Effect.flatMap(decodeDesktopPackageJson));
+  return resolveNightlyTargetVersion(packageJson.version);
+});
+
+const writeOutput = Effect.fn("writeOutput")(function* (
+  metadata: NightlyReleaseMetadata,
+  writeGithubOutput: boolean,
+) {
+  const fs = yield* FileSystem.FileSystem;
+
+  const entries = [
+    ["base_version", metadata.baseVersion],
+    ["version", metadata.version],
+    ["tag", metadata.tag],
+    ["name", metadata.name],
+    ["short_sha", metadata.shortSha],
+  ] as const;
+
+  if (writeGithubOutput) {
+    const githubOutputPath = yield* Config.nonEmptyString("GITHUB_OUTPUT");
+    const serialized = entries.map(([key, value]) => `${key}=${value}\n`).join("");
+    yield* fs.writeFileString(githubOutputPath, serialized, { flag: "a" });
+  } else {
+    for (const [key, value] of entries) {
+      yield* Console.log(`${key}=${value}`);
+    }
+  }
+});
+
+const command = Command.make(
+  "resolve-nightly-release",
+  {
+    date: Flag.string("date").pipe(
+      Flag.withSchema(DateSchema),
+      Flag.withDescription("Nightly build date in YYYYMMDD."),
+    ),
+    runNumber: Flag.string("run-number").pipe(
+      Flag.withSchema(RunNumberSchema),
+      Flag.withDescription("GitHub Actions run number."),
+    ),
+    sha: Flag.string("sha").pipe(
+      Flag.withSchema(ShaSchema),
+      Flag.withDescription("Commit sha for the nightly build."),
+    ),
+    githubOutput: Flag.boolean("github-output").pipe(
+      Flag.withDescription("Write values to GITHUB_OUTPUT instead of stdout."),
+      Flag.withDefault(false),
+    ),
+    root: Flag.string("root").pipe(
+      Flag.withDescription("Workspace root used to resolve apps/desktop/package.json."),
+      Flag.optional,
+    ),
+  },
+  ({ date, runNumber, sha, githubOutput, root }) =>
+    readDesktopBaseVersion(Option.getOrUndefined(root)).pipe(
+      Effect.map((baseVersion) => resolveNightlyReleaseMetadata(baseVersion, date, runNumber, sha)),
+      Effect.flatMap((metadata) => writeOutput(metadata, githubOutput)),
+    ),
+).pipe(Command.withDescription("Resolve nightly release version metadata."));
+
+if (import.meta.main) {
+  Command.run(command, { version: "0.0.0" }).pipe(
+    Effect.provide(NodeServices.layer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/scripts/resolve-previous-release-tag.ts b/scripts/resolve-previous-release-tag.ts
new file mode 100644
index 00000000000..f75c3a4f8a4
--- /dev/null
+++ b/scripts/resolve-previous-release-tag.ts
@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Array from "effect/Array";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as String from "effect/String";
+import { Command, Flag } from "effect/unstable/cli";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+const ReleaseChannel = Schema.Literals(["stable", "nightly"]);
+type ReleaseChannel = typeof ReleaseChannel.Type;
+
+interface StableVersion {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly prerelease: ReadonlyArray<string>;
+}
+
+interface NightlyVersion {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly date: number;
+  readonly runNumber: number;
+}
+
+const parseNumericIdentifier = (identifier: string): number | undefined =>
+  /^\d+$/.test(identifier) ? Number(identifier) : undefined;
+
+const comparePrereleaseIdentifiers = (left: string, right: string): number => {
+  const leftNumeric = parseNumericIdentifier(left);
+  const rightNumeric = parseNumericIdentifier(right);
+
+  if (leftNumeric !== undefined && rightNumeric !== undefined) {
+    return leftNumeric - rightNumeric;
+  }
+  if (leftNumeric !== undefined) {
+    return -1;
+  }
+  if (rightNumeric !== undefined) {
+    return 1;
+  }
+  return left.localeCompare(right);
+};
+
+const compareStableVersions = (left: StableVersion, right: StableVersion): number => {
+  if (left.major !== right.major) return left.major - right.major;
+  if (left.minor !== right.minor) return left.minor - right.minor;
+  if (left.patch !== right.patch) return left.patch - right.patch;
+
+  const leftHasPrerelease = left.prerelease.length > 0;
+  const rightHasPrerelease = right.prerelease.length > 0;
+  if (!leftHasPrerelease && !rightHasPrerelease) return 0;
+  if (!leftHasPrerelease) return 1;
+  if (!rightHasPrerelease) return -1;
+
+  const maxLength = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < maxLength; index += 1) {
+    const leftIdentifier = left.prerelease[index];
+    const rightIdentifier = right.prerelease[index];
+    if (leftIdentifier === undefined) return -1;
+    if (rightIdentifier === undefined) return 1;
+
+    const comparison = comparePrereleaseIdentifiers(leftIdentifier, rightIdentifier);
+    if (comparison !== 0) return comparison;
+  }
+
+  return 0;
+};
+
+const parseStableTag = (tag: string): StableVersion | undefined => {
+  const match = /^v(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(tag);
+  if (!match) return undefined;
+
+  const [, major, minor, patch, prerelease] = match;
+  if (!major || !minor || !patch) return undefined;
+
+  const prereleaseIdentifiers = prerelease ? prerelease.split(".") : [];
+  // Nightly tags also start with `v` and carry a `nightly.*` prerelease
+  // identifier. They must not be considered stable candidates when resolving
+  // the previous stable tag.
+  if (prereleaseIdentifiers[0] === "nightly") return undefined;
+
+  return {
+    major: Number(major),
+    minor: Number(minor),
+    patch: Number(patch),
+    prerelease: prereleaseIdentifiers,
+  };
+};
+
+const compareNightlyVersions = (left: NightlyVersion, right: NightlyVersion): number => {
+  if (left.major !== right.major) return left.major - right.major;
+  if (left.minor !== right.minor) return left.minor - right.minor;
+  if (left.patch !== right.patch) return left.patch - right.patch;
+  if (left.date !== right.date) return left.date - right.date;
+  return left.runNumber - right.runNumber;
+};
+
+const parseNightlyTag = (tag: string): NightlyVersion | undefined => {
+  // Accept both the current `v<semver>` format and the legacy `nightly-v<semver>`
+  // format so release note diffs keep working across the tag-format transition.
+  const match = /^(?:nightly-)?v(\d+)\.(\d+)\.(\d+)-nightly\.(\d{8})\.(\d+)$/.exec(tag);
+  if (!match) return undefined;
+
+  const [, major, minor, patch, date, runNumber] = match;
+  if (!major || !minor || !patch || !date || !runNumber) return undefined;
+
+  return {
+    major: Number(major),
+    minor: Number(minor),
+    patch: Number(patch),
+    date: Number(date),
+    runNumber: Number(runNumber),
+  };
+};
+
+const resolvePreviousReleaseTag = (
+  channel: ReleaseChannel,
+  currentTag: string,
+  tags: ReadonlyArray<string>,
+): string | undefined => {
+  if (channel === "stable") {
+    const current = parseStableTag(currentTag);
+    if (!current) {
+      throw new Error(`Invalid stable release tag '${currentTag}'.`);
+    }
+
+    const candidates = tags
+      .map((tag) => ({ tag, parsed: parseStableTag(tag) }))
+      .filter(
+        (entry): entry is { tag: string; parsed: StableVersion } => entry.parsed !== undefined,
+      )
+      .filter((entry) => compareStableVersions(entry.parsed, current) < 0)
+      .toSorted((left, right) => compareStableVersions(right.parsed, left.parsed));
+
+    return candidates[0]?.tag;
+  }
+
+  const current = parseNightlyTag(currentTag);
+  if (!current) {
+    throw new Error(`Invalid nightly release tag '${currentTag}'.`);
+  }
+
+  const candidates = tags
+    .map((tag) => ({ tag, parsed: parseNightlyTag(tag) }))
+    .filter((entry): entry is { tag: string; parsed: NightlyVersion } => entry.parsed !== undefined)
+    .filter((entry) => compareNightlyVersions(entry.parsed, current) < 0)
+    .toSorted((left, right) => compareNightlyVersions(right.parsed, left.parsed));
+
+  return candidates[0]?.tag;
+};
+
+const listGitTags = Effect.fn("listGitTags")(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner.spawn(ChildProcess.make("git", ["tag", "--list"]));
+  const tags = yield* child.stdout.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => "",
+      (acc, chunk) => acc + chunk,
+    ),
+    Effect.map(String.split(/\r?\n/)),
+    Effect.map(Array.map(String.trim)),
+    Effect.map(Array.filter(String.isNonEmpty)),
+  );
+  return tags;
+});
+
+const writeOutput = Effect.fn("writeOutput")(function* (
+  previousTag: string | undefined,
+  writeGithubOutput: boolean,
+) {
+  const entry = `previous_tag=${previousTag ?? ""}\n`;
+
+  if (writeGithubOutput) {
+    const fs = yield* FileSystem.FileSystem;
+    const githubOutputPath = yield* Config.nonEmptyString("GITHUB_OUTPUT");
+    yield* fs.writeFileString(githubOutputPath, entry, { flag: "a" });
+    return;
+  }
+
+  process.stdout.write(entry);
+});
+
+const command = Command.make(
+  "resolve-previous-release-tag",
+  {
+    channel: Flag.choice("channel", ReleaseChannel.literals).pipe(
+      Flag.withDescription("Release channel whose previous tag should be resolved."),
+    ),
+    currentTag: Flag.string("current-tag").pipe(
+      Flag.withDescription("Current release tag to compare against."),
+    ),
+    githubOutput: Flag.boolean("github-output").pipe(
+      Flag.withDescription("Write values to GITHUB_OUTPUT instead of stdout."),
+      Flag.withDefault(false),
+    ),
+  },
+  ({ channel, currentTag, githubOutput }) =>
+    listGitTags().pipe(
+      Effect.map((tags) => resolvePreviousReleaseTag(channel, currentTag, tags)),
+      Effect.flatMap((previousTag) => writeOutput(previousTag, githubOutput)),
+    ),
+).pipe(Command.withDescription("Resolve the previous release tag for a stable or nightly series."));
+
+if (import.meta.main) {
+  Command.run(command, { version: "0.0.0" }).pipe(
+    Effect.scoped,
+    Effect.provide(NodeServices.layer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/scripts/tsconfig.json b/scripts/tsconfig.json
index e9ed7c8ae53..61307d2992e 100644
--- a/scripts/tsconfig.json
+++ b/scripts/tsconfig.json
@@ -2,15 +2,8 @@
   "extends": "../tsconfig.base.json",
   "compilerOptions": {
     "composite": true,
-    "types": ["node", "bun"],
-    "lib": ["ES2023", "esnext.disposable"],
-    "noEmit": true,
-    "allowImportingTsExtensions": true,
-    "plugins": [
-      {
-        "name": "@effect/language-service"
-      }
-    ]
+    "types": ["node"],
+    "lib": ["ESNext", "esnext.disposable"]
   },
   "include": ["**/*.ts"]
 }
diff --git a/scripts/update-release-package-versions.test.ts b/scripts/update-release-package-versions.test.ts
new file mode 100644
index 00000000000..802e13f35d9
--- /dev/null
+++ b/scripts/update-release-package-versions.test.ts
@@ -0,0 +1,211 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { Command, CliError } from "effect/unstable/cli";
+import * as TestConsole from "effect/testing/TestConsole";
+import { fromJsonStringPretty } from "@t3tools/shared/schemaJson";
+
+import {
+  releasePackageFiles,
+  updateReleasePackageVersions,
+  updateReleasePackageVersionsCommand,
+} from "./update-release-package-versions.ts";
+
+const ScriptTestLayer = Layer.mergeAll(NodeServices.layer, TestConsole.layer);
+const runCli = Command.runWith(updateReleasePackageVersionsCommand, { version: "0.0.0" });
+const PackageJsonSchema = Schema.Record(Schema.String, Schema.Unknown);
+const PackageJsonPrettyJson = fromJsonStringPretty(PackageJsonSchema);
+const decodePackageJson = Schema.decodeEffect(PackageJsonPrettyJson);
+const encodePackageJson = Schema.encodeEffect(PackageJsonPrettyJson);
+
+const writePackageJsonFixtures = Effect.fn("writePackageJsonFixtures")(function* (
+  rootDir: string,
+  version: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  for (const relativePath of releasePackageFiles) {
+    const filePath = path.join(rootDir, relativePath);
+    yield* fs.makeDirectory(path.dirname(filePath), { recursive: true });
+    yield* fs.writeFileString(
+      filePath,
+      `${yield* encodePackageJson({
+        name: relativePath,
+        version,
+        private: true,
+      })}\n`,
+    );
+  }
+});
+
+const readReleaseVersions = Effect.fn("readReleaseVersions")(function* (rootDir: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const versions = new Map<string, string>();
+
+  for (const relativePath of releasePackageFiles) {
+    const filePath = path.join(rootDir, relativePath);
+    const packageJson = yield* fs.readFileString(filePath).pipe(Effect.flatMap(decodePackageJson));
+    versions.set(relativePath, String(packageJson.version));
+  }
+
+  return versions;
+});
+
+const captureLogs = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  Effect.gen(function* () {
+    const result = yield* effect;
+    const logs = (yield* TestConsole.logLines).filter(
+      (line): line is string => typeof line === "string",
+    );
+    return { result, logs };
+  });
+
+it.layer(ScriptTestLayer)("update-release-package-versions", (it) => {
+  it.effect("updates all release package versions under the provided root", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const baseDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "update-release-package-versions-",
+      });
+
+      yield* writePackageJsonFixtures(baseDir, "0.0.1");
+
+      const result = yield* updateReleasePackageVersions("1.2.3", { rootDir: baseDir });
+      const versions = yield* readReleaseVersions(baseDir);
+
+      assert.deepStrictEqual(result, { changed: true });
+      assert.deepStrictEqual(
+        Array.from(versions.entries()),
+        releasePackageFiles.map((relativePath) => [relativePath, "1.2.3"]),
+      );
+    }),
+  );
+
+  it.effect("returns changed=false when all versions already match", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const baseDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "update-release-package-versions-unchanged-",
+      });
+
+      yield* writePackageJsonFixtures(baseDir, "1.2.3");
+
+      const result = yield* updateReleasePackageVersions("1.2.3", { rootDir: baseDir });
+
+      assert.deepStrictEqual(result, { changed: false });
+    }),
+  );
+
+  it.effect("accepts flags before the version positional and appends changed output", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "update-release-package-versions-cli-",
+      });
+      const githubOutputPath = path.join(baseDir, "github-output.txt");
+
+      yield* writePackageJsonFixtures(baseDir, "0.0.1");
+
+      yield* runCli(["--github-output", "--root", baseDir, "2.0.0"]).pipe(
+        Effect.provide(
+          ConfigProvider.layer(
+            ConfigProvider.fromEnv({
+              env: {
+                GITHUB_OUTPUT: githubOutputPath,
+              },
+            }),
+          ),
+        ),
+      );
+
+      const githubOutput = yield* fs.readFileString(githubOutputPath);
+      assert.equal(githubOutput, "changed=true\n");
+    }),
+  );
+
+  it.effect("logs when nothing changed", () =>
+    captureLogs(
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const baseDir = yield* fs.makeTempDirectoryScoped({
+          prefix: "update-release-package-versions-cli-log-",
+        });
+
+        yield* writePackageJsonFixtures(baseDir, "3.0.0");
+        yield* runCli(["3.0.0", "--root", baseDir]);
+      }),
+    ).pipe(
+      Effect.tap(({ logs }) => {
+        assert.deepStrictEqual(logs, ["All package.json versions already match release version."]);
+        return Effect.void;
+      }),
+    ),
+  );
+
+  it.effect("requires GITHUB_OUTPUT when --github-output is set", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const baseDir = yield* fs.makeTempDirectoryScoped({
+        prefix: "update-release-package-versions-cli-missing-output-",
+      });
+
+      yield* writePackageJsonFixtures(baseDir, "0.0.1");
+
+      const error = yield* runCli(["4.0.0", "--root", baseDir, "--github-output"]).pipe(
+        Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} }))),
+        Effect.flip,
+      );
+
+      assert.equal(
+        error.message,
+        'SchemaError(Expected string, got undefined\n  at ["GITHUB_OUTPUT"])',
+      );
+    }),
+  );
+
+  it.effect("rejects unknown flags during cli parsing", () =>
+    Effect.gen(function* () {
+      const error = yield* runCli(["1.2.3", "--unknown"]).pipe(Effect.flip);
+
+      if (!CliError.isCliError(error)) {
+        assert.fail(`Expected CliError, got ${String(error)}`);
+      }
+
+      const optionError =
+        error._tag === "ShowHelp" ? (error.errors[0] as CliError.CliError | undefined) : error;
+
+      if (!optionError || optionError._tag !== "UnrecognizedOption") {
+        assert.fail(`Expected UnrecognizedOption, got ${String(optionError?._tag)}`);
+      }
+
+      assert.equal(optionError.option, "--unknown");
+    }),
+  );
+
+  it.effect("rejects a missing version positional during cli parsing", () =>
+    Effect.gen(function* () {
+      const error = yield* runCli(["--github-output"]).pipe(Effect.flip);
+
+      if (!CliError.isCliError(error)) {
+        assert.fail(`Expected CliError, got ${String(error)}`);
+      }
+
+      const versionError =
+        error._tag === "ShowHelp" ? (error.errors[0] as CliError.CliError | undefined) : error;
+
+      if (!versionError || versionError._tag !== "MissingArgument") {
+        assert.fail(`Expected MissingArgument, got ${String(versionError?._tag)}`);
+      }
+
+      assert.equal(versionError.argument, "version");
+    }),
+  );
+});
diff --git a/scripts/update-release-package-versions.ts b/scripts/update-release-package-versions.ts
index b860b85e8e8..cebf434d0ae 100644
--- a/scripts/update-release-package-versions.ts
+++ b/scripts/update-release-package-versions.ts
@@ -1,6 +1,16 @@
-import { appendFileSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Config from "effect/Config";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { fromJsonStringPretty } from "@t3tools/shared/schemaJson";
 
 export const releasePackageFiles = [
   "apps/server/package.json",
@@ -10,103 +20,75 @@ export const releasePackageFiles = [
 ] as const;
 
 interface UpdateReleasePackageVersionsOptions {
-  readonly rootDir?: string;
+  readonly rootDir?: string | undefined;
 }
 
-interface MutablePackageJson {
-  version?: string;
-  [key: string]: unknown;
-}
+const PackageJsonSchema = Schema.Record(Schema.String, Schema.Unknown);
+const PackageJsonPrettyJson = fromJsonStringPretty(PackageJsonSchema);
+const decodePackageJson = Schema.decodeUnknownEffect(PackageJsonPrettyJson);
+const encodePackageJson = Schema.encodeEffect(PackageJsonPrettyJson);
 
-export function updateReleasePackageVersions(
+export const updateReleasePackageVersions = Effect.fn("updateReleasePackageVersions")(function* (
   version: string,
   options: UpdateReleasePackageVersionsOptions = {},
-): { changed: boolean } {
-  const rootDir = resolve(options.rootDir ?? process.cwd());
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
   let changed = false;
 
   for (const relativePath of releasePackageFiles) {
-    const filePath = resolve(rootDir, relativePath);
-    const packageJson = JSON.parse(readFileSync(filePath, "utf8")) as MutablePackageJson;
+    const filePath = path.join(rootDir, relativePath);
+    const packageJson = yield* fs.readFileString(filePath).pipe(Effect.flatMap(decodePackageJson));
     if (packageJson.version === version) {
       continue;
     }
 
-    packageJson.version = version;
-    writeFileSync(filePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+    const packageJsonString = yield* encodePackageJson({ ...packageJson, version });
+    yield* fs.writeFileString(filePath, `${packageJsonString}\n`);
     changed = true;
   }
 
   return { changed };
-}
-
-function parseArgs(argv: ReadonlyArray<string>): {
-  version: string;
-  rootDir: string | undefined;
-  writeGithubOutput: boolean;
-} {
-  let version: string | undefined;
-  let rootDir: string | undefined;
-  let writeGithubOutput = false;
-
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index];
-    if (argument === undefined) {
-      continue;
-    }
-
-    if (argument === "--github-output") {
-      writeGithubOutput = true;
-      continue;
-    }
-
-    if (argument === "--root") {
-      rootDir = argv[index + 1];
-      if (!rootDir) {
-        throw new Error("Missing value for --root.");
-      }
-      index += 1;
-      continue;
-    }
-
-    if (argument.startsWith("--")) {
-      throw new Error(`Unknown argument: ${argument}`);
-    }
-
-    if (version !== undefined) {
-      throw new Error("Only one release version can be provided.");
-    }
-    version = argument;
-  }
-
-  if (!version) {
-    throw new Error(
-      "Usage: node scripts/update-release-package-versions.ts <version> [--root <path>] [--github-output]",
-    );
-  }
-
-  return { version, rootDir, writeGithubOutput };
-}
-
-const isMain =
-  process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
-
-if (isMain) {
-  const { version, rootDir, writeGithubOutput } = parseArgs(process.argv.slice(2));
-  const { changed } = updateReleasePackageVersions(
-    version,
-    rootDir === undefined ? {} : { rootDir },
+});
+
+const writeGithubOutput = Effect.fn("writeGithubOutput")(function* (changed: boolean) {
+  const fs = yield* FileSystem.FileSystem;
+  const githubOutputPath = yield* Config.nonEmptyString("GITHUB_OUTPUT");
+  yield* fs.writeFileString(githubOutputPath, `changed=${changed}\n`, { flag: "a" });
+});
+
+export const updateReleasePackageVersionsCommand = Command.make(
+  "update-release-package-versions",
+  {
+    version: Argument.string("version").pipe(
+      Argument.withDescription("Release version to write into each releasable package.json."),
+    ),
+    root: Flag.string("root").pipe(
+      Flag.withDescription("Workspace root used to resolve the release package manifests."),
+      Flag.optional,
+    ),
+    githubOutput: Flag.boolean("github-output").pipe(
+      Flag.withDescription("Append changed=<boolean> to GITHUB_OUTPUT."),
+      Flag.withDefault(false),
+    ),
+  },
+  ({ version, root, githubOutput }) =>
+    updateReleasePackageVersions(version, {
+      rootDir: Option.getOrUndefined(root),
+    }).pipe(
+      Effect.tap(({ changed }) =>
+        changed
+          ? Effect.void
+          : Console.log("All package.json versions already match release version."),
+      ),
+      Effect.tap(({ changed }) => (githubOutput ? writeGithubOutput(changed) : Effect.void)),
+    ),
+).pipe(Command.withDescription("Update release package versions across the workspace."));
+
+if (import.meta.main) {
+  Command.run(updateReleasePackageVersionsCommand, { version: "0.0.0" }).pipe(
+    Effect.provide(NodeServices.layer),
+    NodeRuntime.runMain,
   );
-
-  if (!changed) {
-    console.log("All package.json versions already match release version.");
-  }
-
-  if (writeGithubOutput) {
-    const githubOutputPath = process.env.GITHUB_OUTPUT;
-    if (!githubOutputPath) {
-      throw new Error("GITHUB_OUTPUT is required when --github-output is set.");
-    }
-    appendFileSync(githubOutputPath, `changed=${changed}\n`);
-  }
 }
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 538fa0f0eb3..4f7edbaf759 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -1,8 +1,13 @@
 {
   "compilerOptions": {
-    "target": "ES2023",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
     "strict": true,
     "noUncheckedIndexedAccess": true,
     "exactOptionalPropertyTypes": true,
@@ -12,6 +17,39 @@
     "skipLibCheck": true,
     "allowSyntheticDefaultImports": true,
     "esModuleInterop": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "namespaceImportPackages": ["@effect/platform-node", "effect"],
+        "diagnosticSeverity": {
+          "importFromBarrel": "error",
+          "anyUnknownInErrorContext": "error",
+          "unsafeEffectTypeAssertion": "error",
+          "instanceOfSchema": "error",
+          "deterministicKeys": "error",
+          "strictEffectProvide": "off",
+          "missingEffectServiceDependency": "error",
+          "leakingRequirements": "error",
+          "globalErrorInEffectCatch": "error",
+          "globalErrorInEffectFailure": "error",
+          "unknownInEffectCatch": "error",
+          "strictBooleanExpressions": "off",
+          "preferSchemaOverJson": "error",
+          "schemaSyncInEffect": "error",
+          "cryptoRandomUUID": "error",
+          "cryptoRandomUUIDInEffect": "error",
+          "nodeBuiltinImport": "error",
+          "globalDate": "error",
+          "globalDateInEffect": "error",
+          "globalConsole": "error",
+          "globalConsoleInEffect": "error",
+          "globalRandom": "error",
+          "globalRandomInEffect": "error",
+          "globalTimers": "error",
+          "globalTimersInEffect": "error"
+        }
+      }
+    ]
   }
 }
diff --git a/turbo.json b/turbo.json
index d4d58c15e6d..9a726d92e1a 100644
--- a/turbo.json
+++ b/turbo.json
@@ -11,6 +11,8 @@
     "T3CODE_NO_BROWSER",
     "T3CODE_HOME",
     "T3CODE_AUTH_TOKEN",
+    "T3CODE_TAILSCALE_SERVE",
+    "T3CODE_TAILSCALE_SERVE_PORT",
     "T3CODE_DESKTOP_WS_URL",
     "T3CODE_TRACE_MIN_LEVEL",
     "T3CODE_TRACE_TIMING_ENABLED",
@@ -21,8 +23,12 @@
     "T3CODE_OTLP_TRACES_URL",
     "T3CODE_OTLP_METRICS_URL",
     "T3CODE_OTLP_EXPORT_INTERVAL_MS",
-    "T3CODE_OTLP_SERVICE_NAME"
+    "T3CODE_OTLP_SERVICE_NAME",
+    "APP_VERSION",
+    "VITE_HOSTED_APP_URL",
+    "VITE_HOSTED_APP_CHANNEL"
   ],
+  "globalPassThroughEnv": ["PATHEXT"],
   "tasks": {
     "build": {
       "dependsOn": ["^build"],